diff --git a/docs/images/C1D_PAPA_ERSEM_plots.png b/docs/images/C1D_PAPA_ERSEM_plots.png new file mode 100644 index 0000000..9f122ab Binary files /dev/null and b/docs/images/C1D_PAPA_ERSEM_plots.png differ diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst index 273d81e..9c0ef24 100644 --- a/docs/source/tutorials/index.rst +++ b/docs/source/tutorials/index.rst @@ -22,6 +22,7 @@ Here we describe several tutorials for the common use cases for ERSEM. gotm fvcom nemo + nemo1d .. _conda-install: diff --git a/docs/source/tutorials/nemo1d.rst b/docs/source/tutorials/nemo1d.rst new file mode 100644 index 0000000..fe201b6 --- /dev/null +++ b/docs/source/tutorials/nemo1d.rst @@ -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 `_ in the North Pacific Ocean with biogeochemistry of `L4 station `_ 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 `__ 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 `__ repository on Zenodo and unpacked into the working directory. + +NEMO4 code base with FABM support can be obtained in the corresponding `repository `__. The next step is to download `FABM `__ and `ERSEM `__. Finally, I/O server `XIOS-2.5 `__ must be downloaded and `installed `__. 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 -DFABM_HOST=nemo -DFABM_ERSEM_BASE= -DCMAKE_INSTALL_PREFIX=~/local/fabm/nemo-fabm-ersem + #replace and 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=$ + RUN_DIR=$ + export XIOS_HOME=$ + export FABM_HOME=$HOME/local/fabm/nemo-fabm-ersem + # replace and with the path to the corresponding code bases and 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 /cgfs/C1D_PAPA_FABM_ERSEM/fabm.yaml.ersem_c1d fabm.yaml + # replace 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 `_ or `PyNcView `_), or in Python using `xarray `_: + +.. 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%