Skip to content

Commit

Permalink
Adding nemo1d tutorial (#82)
Browse files Browse the repository at this point in the history
* Create nemo1d

initialise 1D NEMO-FABM-ERSEM tutorial

* Update nemo1d

* Rename nemo1d to nemo1d.rst

* Update nemo1d.rst

* Update nemo1d.rst

* added link to C1D_PAPA inputs

* added compilation instructions

* added further instructions

* corrected steps numbering

* Update nemo1d.rst

* specify input file name

* python plotting example

* python code and text updates

* Add C1D example plot via upload

* Update nemo1d.rst

* Update nemo1d.rst

* Update index.rst

* Update docs/source/tutorials/nemo1d.rst

Co-authored-by: Michael Wathen <[email protected]>

* Update docs/source/tutorials/nemo1d.rst

Co-authored-by: Michael Wathen <[email protected]>

* Update nemo1d.rst

* Update docs/source/tutorials/nemo1d.rst

Co-authored-by: Michael Wathen <[email protected]>

* Swap make command order

* Do not load mpi module as it is a 1D case

* refer to cfgs dir for NEMO configuration

* Update docs/source/tutorials/nemo1d.rst

Co-authored-by: Michael Wathen <[email protected]>

* link to fabm.yaml in C1D ERSEM configuration

Co-authored-by: Michael Wathen <[email protected]>
Co-authored-by: Michael Wathen <[email protected]>
  • Loading branch information
3 people authored Oct 20, 2022
1 parent 363499c commit a3f27e2
Show file tree
Hide file tree
Showing 3 changed files with 122 additions and 0 deletions.
Binary file added docs/images/C1D_PAPA_ERSEM_plots.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/source/tutorials/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ Here we describe several tutorials for the common use cases for ERSEM.
gotm
fvcom
nemo
nemo1d

.. _conda-install:

Expand Down
121 changes: 121 additions & 0 deletions docs/source/tutorials/nemo1d.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@

.. _nemo:

#############################
NEMO-ERSEM in a water column
#############################

This tutorial demonstrates how to configure and run NEMO 1D (water-column) reference configuration C1D_PAPA with ERSEM biogeochemistry. This example is a demonstration of the concept, as it combines hydrodynamics of ocean station `PAPA <https://www.pmel.noaa.gov/ocs/Papa>`_ in the North Pacific Ocean with biogeochemistry of `L4 station <https://www.westernchannelobservatory.org.uk/>`_ in the Western English Channel. Users are encouraged to modify this example to fit their own purposes.

We recommend to read the brief description of the NEMO `C1D_PAPA configuration <https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/cfgs.html#c1d-papa>`__ before continuing with this tutorial.

Step 1: Obtaining the code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The input data contained in ``INPUTS_C1D_PAPA_v4.0.tar`` file must be obtained from `NEMO Reference configurations inputs <https://zenodo.org/record/1472245#.Yt6_QIzMKEI>`__ repository on Zenodo and unpacked into the working directory.

NEMO4 code base with FABM support can be obtained in the corresponding `repository <https://github.com/pmlmodelling/NEMO4.0-FABM>`__. The next step is to download `FABM <https://github.com/fabm-model/fabm>`__ and `ERSEM <https://github.com/pmlmodelling/ersem>`__. Finally, I/O server `XIOS-2.5 <https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/guide/html/install.html#extract-and-install-xios>`__ must be downloaded and `installed <https://forge.ipsl.jussieu.fr/ioserver/>`__. The compiled `xios_server.exe` executable should be copied into the working directory.


Step 2: Compiling the code
~~~~~~~~~~~~~~~~~~~~~~~~~~~

First, FABM must be compiled with ERSEM support, specifying nemo as a physical host model. The following commands can be run in a command line or wrapped into an executable file for easy recompilation at any future point:

.. code-block:: bash
old=$(pwd) #remember current (working) directory
mkdir -p ~/build/nemo-fabm-ersem # create directory for the build
cd ~/build/nemo-fabm-ersem # go to the build directory
cmake <FABM_DIR> -DFABM_HOST=nemo -DFABM_ERSEM_BASE=<ERSEM_DIR> -DCMAKE_INSTALL_PREFIX=~/local/fabm/nemo-fabm-ersem
#replace <FABM_DIR> and <ERSEM_DIR> with the corresponding directories the FABM and ERSEM code bases were downloaded to.
make -j4
make install
cd $old # return to the working directory
Thereafter, it is time to compile the NEMO executable. Users may refer to the `C1D_PAPA_FABM_ERSEM` configuration provided with the NEMO4.0-FABM in *cfgs* directory. The critical point is to specify all the necessary compilation keys in ``cpp_X.fcm`` file, i.e. key_c1d for compilation in 1D, and key_fabm for FABM support:

.. code-block:: bash
bld::tool::fppkeys key_c1d key_mpp_mpi key_iomput key_nosignedzero key_top key_fabm
Next, compile the model by executing the following lines:

.. code-block:: bash
#!/bin/bash
NEMO_BUILD_DIR=$<NEMO_DIR>
RUN_DIR=$<RUN_DIR>
export XIOS_HOME=$<XIOS_DIR>
export FABM_HOME=$HOME/local/fabm/nemo-fabm-ersem
# replace <NEMO_DIR> and <XIOS_DIR> with the path to the corresponding code bases and <RUNDIR> with the working directory. FABM_HOME in this example corresponds to the directory where FABM-ERSEM was installed.
ARCH=GCC_PMPC # specify build architecture
cd $NEMO_BUILD_DIR
./makenemo -m $ARCH -r C1D_PAPA_FABM_ERSEM -n C1D_PAPA_FABM_ERSEM_BLD_SCRATCH | tee compile.log
mv $NEMO_BUILD_DIR/cfgs/C1D_PAPA_FABM_ERSEM_BLD_SCRATCH/BLD/bin/nemo.exe $RUN_DIR/
echo "Done."
The script above will compile the model and move the nemo executable into the working directory.

Note that the architecture file might require some editing depending on the machine the model is compiled and run on. This will include compiler version, compiler flags and links to netCDF libraries. Here, we are pointing our compilation to arch-GCC_PMPC.fcm file (available within NEMO4.0-FABM repository) to compile on a typical PML workstation running Fedora Linux distribution and using a GNU Fortran compiler.

Step 3: Getting ready to run the model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Within the working directory, create a link to the desired model configuration file. For this tutorial, we will link fabm.yaml provided with the cfgs/C1D_PAPA_FABM_ERSEM configuration:

.. code-block:: bash
ln -sf <NEMO_DIR>/cgfs/C1D_PAPA_FABM_ERSEM/fabm.yaml.ersem_c1d fabm.yaml
# replace <NEMO_DIR> with the directory containing the ERSEM code.
ERSEM requires some external inputs, which must be provided. The following lines have been appended to the fabm.yaml file we are using (for simplicity we are using constant parameter values here). Depending on the configuration, the list of required external inputs will vary.

.. code-block:: bash
pco2a:
model: horizontal_constant
parameters:
value: 400.
standard_name: mole_fraction_of_carbon_dioxide_in_air
ADY_0:
model: horizontal_constant
parameters:
value: 1.0e-10
standard_name: gelbstoff_absorption_satellite
Create links to, or copy namelist files from NEMO cfgs/C1D_PAPA_FABM_ERSEM folder into the working directory. Repeat the same procedure for *.xml files. file_def_nemo.xml defines which outputs will be saved, and at what frequency. For the purpose of this example, we will save a range of daily averaged pelagic and benthic state and diagnostic variables. This file can be used as a template to specify the desired range of model outputs.
Step 4: Running the model and visualising the outputs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The model is deployed by running the executable file in the working directory:

.. code-block:: bash
./nemo.exe
As a result, several output files will be generated according to specifications in file_def_nemo.xml file. Additionally, NEMO will generate restart files. The outputs can be visualised using netCDF viewer (e.g. `ncview <http://meteora.ucsd.edu/~pierce/ncview_home_page.html>`_ or `PyNcView <https://github.com/BoldingBruggeman/pyncview>`_), or in Python using `xarray <https://docs.xarray.dev/en/stable/#>`_:

.. code-block:: python
import xarray as xr # import xarray
import matplotlib.pyplot as plt # import matplotlib
dat = xr.open_dataset('C1D_PAPA_1d_20100615_20110614_ptrc_T.nc') # open dataset with ERSEM variables
fig,axes=plt.subplots(nrows=2,figsize=(8,6)) # create figure with 2 subplots
dat.N3_n[:,0:35,1,1].plot(x='time_counter',yincrease=False,ax=axes[0]) # plot Hovmöller diagram for nitrate
dat.O2_o[:,0:35,1,1].plot(x='time_counter',yincrease=False,ax=axes[1]) # plot Hovmöller diagram for oxygen
axes[0].set_title('Modelled nitrate at PAPA') # add title
axes[1].set_title('Modelled dissolved oxygen at PAPA') # add another title
fig.tight_layout() # make it look nice
In the example above we plot the variables over the entire modelled period, but only in the upper 35 vertical layers (from surface down to ~300 m depth). We also have to specify spatial dimensions of the output, as 1D configuration in NEMO actually has horizontal resolution of 3x3 grid points.

The resulting figure should look like this:

.. image:: ../../images/C1D_PAPA_ERSEM_plots.png
:alt: Example C1D_PAPA_FABM_ERSEM output
:width: 100.0%

0 comments on commit a3f27e2

Please sign in to comment.