diff --git a/.gitignore b/.gitignore index 07fc814..d3aacd0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ # Removing docs build docs/build/ +*.bak # Removing pycache __pycache__ @@ -9,3 +10,6 @@ docs/source/module_index.rst # removing swap files *.swp + +# the ERSEM setups repo should be cloned each time +docs/source/ersem-setups diff --git a/docs/images/GPP.gif b/docs/images/GPP.gif new file mode 100644 index 0000000..37655b9 Binary files /dev/null and b/docs/images/GPP.gif differ diff --git a/docs/images/N1_p.gif b/docs/images/N1_p.gif new file mode 100644 index 0000000..3cf63f9 Binary files /dev/null and b/docs/images/N1_p.gif differ diff --git a/docs/images/N3_n.gif b/docs/images/N3_n.gif new file mode 100644 index 0000000..f535710 Binary files /dev/null and b/docs/images/N3_n.gif differ diff --git a/docs/images/O3_c.gif b/docs/images/O3_c.gif new file mode 100644 index 0000000..69ac5b8 Binary files /dev/null and b/docs/images/O3_c.gif differ diff --git a/docs/images/P1_Chl.gif b/docs/images/P1_Chl.gif new file mode 100644 index 0000000..3ed6c67 Binary files /dev/null and b/docs/images/P1_Chl.gif differ diff --git a/docs/images/R6_c.gif b/docs/images/R6_c.gif new file mode 100644 index 0000000..ad3cc3a Binary files /dev/null and b/docs/images/R6_c.gif differ diff --git a/docs/images/bathymetry.png b/docs/images/bathymetry.png new file mode 100644 index 0000000..55f5661 Binary files /dev/null and b/docs/images/bathymetry.png differ diff --git a/docs/images/out.gif b/docs/images/out.gif new file mode 100644 index 0000000..60567e3 Binary files /dev/null and b/docs/images/out.gif differ diff --git a/docs/images/salinity.gif b/docs/images/salinity.gif new file mode 100644 index 0000000..9371235 Binary files /dev/null and b/docs/images/salinity.gif differ diff --git a/docs/images/temp.gif b/docs/images/temp.gif new file mode 100644 index 0000000..0e77946 Binary files /dev/null and b/docs/images/temp.gif differ diff --git a/docs/images/total_chl.gif b/docs/images/total_chl.gif new file mode 100644 index 0000000..e831b4b Binary files /dev/null and b/docs/images/total_chl.gif differ diff --git a/docs/images/total_food.gif b/docs/images/total_food.gif new file mode 100644 index 0000000..163c83e Binary files /dev/null and b/docs/images/total_food.gif differ diff --git a/docs/images/tracer1_c.gif b/docs/images/tracer1_c.gif new file mode 100644 index 0000000..272c874 Binary files /dev/null and b/docs/images/tracer1_c.gif differ diff --git a/docs/requirements.txt b/docs/requirements.txt index 50cfb5d..76d16b5 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -4,3 +4,4 @@ m2r2 numpy sphinxcontrib-bibtex beautifulsoup4 +sphinx-panels diff --git a/docs/source/_scripts/ersem_webpage.py b/docs/source/_scripts/ersem_webpage.py index 0fd876f..695bc52 100644 --- a/docs/source/_scripts/ersem_webpage.py +++ b/docs/source/_scripts/ersem_webpage.py @@ -1,6 +1,7 @@ from bs4 import BeautifulSoup from urllib import request - +import ssl +ssl._create_default_https_context = ssl._create_unverified_context def generator_web_doc(file_name): url = "https://www.pml.ac.uk/Modelling_at_PML/Models/ERSEM" diff --git a/docs/source/conf.py b/docs/source/conf.py index 16b0bc8..9c91a57 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,6 +15,7 @@ sys.path.insert(0, os.path.abspath('_scripts')) import module_index_generator import ersem_webpage +import subprocess sys.path.insert(0, os.path.abspath('../../')) @@ -27,7 +28,12 @@ # The full version, including alpha/beta/rc tags release = '2021' - +if os.path.isdir("ersem-setups"): + os.chdir("ersem-setups") + subprocess.run(['git', 'pull']) + os.chdir("..") +else: + subprocess.run(['git', 'clone', 'git@github.com:pmlmodelling/ersem-setups.git']) # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be @@ -36,7 +42,8 @@ extensions = ['m2r2', 'sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex', - 'sphinx.ext.imgmath'] + 'sphinx.ext.imgmath', + 'sphinx_panels'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/source/index.rst b/docs/source/index.rst index d08ccf6..a13598b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -28,3 +28,4 @@ Welcome to ERSEM's documentation! acknowledgements support references + diff --git a/docs/source/tutorials/fvcom.rst b/docs/source/tutorials/fvcom.rst index 2bce02a..0aaa6ed 100644 --- a/docs/source/tutorials/fvcom.rst +++ b/docs/source/tutorials/fvcom.rst @@ -1,8 +1,138 @@ .. _fvcom: +########################## +FVCOM: ideal estuary model +########################## -FVCOM + FABM + ERSEM -~~~~~~~~~~~~~~~~~~~~ +This tutorial gives an end to end example how to install and then use +FVCOM-ERSEM with an ideal estuary model on a high performance computing +(HPC) machine. We have used PML's in house machine, +`CETO `_. +Unlike the other tutorials in this section we go through setting up +FVCOM-ERSEM on the HPC machine and then running and plotting the results. + +This tutorial is based on the scripts found in the +`ERSEM's setups repository `_. +The individual scripts can be found in the `ideal_estuary` folder. + +.. note:: + You will need to get access to the + `UK-FVCOM GitLab repo `_. + +Building and running FVCOM-ERSEM +################################ + +The three key packages required to run this tutorial are: + +* `FVCOM `__ (UK version -- see note) +* `FABM `__ +* `ERSEM `__ + +Both ERSEM and FABM are freely available on GitHub, however, for UK-FVCOM +you will have to register for the code -- see note above. + +An example build script is as follows: + +.. literalinclude:: ../ersem-setups/ideal_estuary/build.sh + :language: bash + :linenos: + +Here you will have to adapt the script to ensure you are using the right +HPC modules and the corresponding compilers. The important compiler is the +fortran one which is set with the variable `FC`. + +Another key file to change is the ``make.inc`` file, here again you will +need to change the compilers to reflect the modules you are using on the +HPC machine. For example, on lines 74 and 75 ``IOLIBS`` and ``IOINCS`` are +set, these would need to be change to reflect the modules on the HPC machine +you are using. + +.. dropdown:: ``make.inc`` file + + .. literalinclude:: ../ersem-setups/ideal_estuary/make_ideal_estuary.inc + :language: bash + :linenos: + +The key lines to change are: + +* 74--75 +* 174 +* 458--465 + +After building FVCOM-ERSEM, we suggest you use a HPC scheduler, for example, +`SLURM `_ to run example. An +example of the SLURM script used here is given below: + +.. literalinclude:: ../ersem-setups/ideal_estuary/model/estuary/launch_estuary.slurm + :language: bash + :linenos: + +Example output from FVCOM-ERSEM +############################### + +We provide two ``python`` scripts to demonstrate how to visualise both the +input files and the output files. The plotting uses ``PyFVCOM``, we suggest +you ask for access `here `_, +however, a version of the code is available on +`GitHub `_ as well as it being +`pip installable `__. + +.. dropdown:: ``python`` input plot script + + .. literalinclude:: ../ersem-setups/ideal_estuary/plot_input.py + :language: python + :linenos: + +Using the input ``python`` plot script, we generate the domain as follows: + +.. image:: ../../images/bathymetry.png + +.. dropdown:: ``python`` output plot script + + .. literalinclude:: ../ersem-setups/ideal_estuary/plot_output.py + :language: python + :linenos: + +The following plots videos are produced from the plots produced by the +``python`` output plot script. + +.. dropdown:: Gros primary production + + .. image:: ../../images/GPP.gif + +.. dropdown:: Phosphate phosphorus + + .. image:: ../../images/N1_p.gif + +.. dropdown:: Nitrate nitrogen + + .. image:: ../../images/N3_n.gif + +.. dropdown:: Carbonate total dissolved inorganic carbon + + .. image:: ../../images/O3_c.gif + +.. dropdown:: Diatoms chlorophyll + + .. image:: ../../images/P1_Chl.gif + +.. dropdown:: Medium-sized POM carbon + + .. image:: ../../images/R6_c.gif + +.. dropdown:: Salinity + + .. image:: ../../images/salinity.gif + +.. dropdown:: Temperature + + .. image:: ../../images/temp.gif + +.. dropdown:: Total chorophyll + + .. image:: ../../images/total_chl.gif + +.. dropdown:: Tracer1 concentration + + .. image:: ../../images/tracer1_c.gif -.. warning:: - Tutorial under construction diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst index 947bc1a..273d81e 100644 --- a/docs/source/tutorials/index.rst +++ b/docs/source/tutorials/index.rst @@ -20,8 +20,8 @@ Here we describe several tutorials for the common use cases for ERSEM. pyfabm fabm0d gotm - nemo fvcom + nemo .. _conda-install: