Adding basic FVCOM example (#54)

* Adding basic FVCOM example

* Updating docs to include SLURM script

* Adding domain plot to docs

* Updating ignore to remove .bak files

* Updating FVCOM from PR comments

* Fixing typo

.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

docs/requirements.txt

@@ -4,3 +4,4 @@ m2r2
 numpy
 sphinxcontrib-bibtex
 beautifulsoup4
+sphinx-panels

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"

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', '[email protected]: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']

docs/source/index.rst

@@ -28,3 +28,4 @@ Welcome to ERSEM's documentation!
    acknowledgements
    support
    references
+

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 <https://www.pml.ac.uk/Facilities/High_Performance_Computing>`_.
+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 <https://github.com/pmlmodelling/ersem-setups>`_.
+The individual scripts can be found in the `ideal_estuary` folder.
+
+.. note::
+    You will need to get access to the 
+    `UK-FVCOM GitLab repo <https://www.pml.ac.uk/Modelling_at_PML/Access_Code>`_.
+
+Building and running FVCOM-ERSEM
+################################
+
+The three key packages required to run this tutorial are:
+
+* `FVCOM <https://gitlab.ecosystem-modelling.pml.ac.uk/fvcom/uk-fvcom#fabm-ersem>`__ (UK version -- see note)
+* `FABM <https://github.com/fabm-model/fabm>`__
+* `ERSEM <https://github.com/pmlmodelling/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 <https://slurm.schedmd.com/documentation.html>`_ 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 <https://www.pml.ac.uk/Modelling_at_PML/Access_Code>`_,
+however, a version of the code is available on 
+`GitHub <https://github.com/pwcazenave/PyFVCOM>`_ as well as it being 
+`pip installable <https://pypi.org/project/PyFVCOM/>`__.
+
+.. 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

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: