Changeset 11713


Ignore:
Timestamp:
2019-10-17T17:49:19+02:00 (11 months ago)
Author:
nicolasmartin
Message:

Revamp TOP README and implement a TODO list
Review tracers.rst by adding snippets of source files
Add drafthtml target for Makefile related to draft building tag for sphinx-build to
display todo items at the top of the guide homepage

Misc:

  • Use dedicated :file: role instead of ... for file or directory
  • Update BibTeX entries of NEMO reference publications by using :title: role
  • Dump of RELEASE_NOTES.rst
  • New file todos.rst to list all items declared with todo directive
  • Modify conf.py to add a conditional test for draft tag
Location:
NEMO/trunk
Files:
1 added
11 edited

Legend:

Unmodified
Added
Removed
  • NEMO/trunk/README.rst

    r11708 r11713  
    1 :Release:  |release| 
    2 :Date:     |today| 
    3 :SVN rev.: |revision| 
    4  
    51NEMO_ for *Nucleus for European Modelling of the Ocean* is a state-of-the-art modelling framework for 
    62research activities and forecasting services in ocean and climate sciences, 
     
    1511The NEMO ocean model has 3 major components: 
    1612 
    17 - |NEMO-OCE| models the ocean {thermo}dynamics and solves the primitive equations (``./src/OCE``) 
    18 - |NEMO-ICE| simulates seaice {thermo}dynamics, brine inclusions and 
    19   subgrid-scale thickness variations (``./src/ICE``) 
    20 - |NEMO-MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes 
    21   (``./src/TOP``) 
     13- |OCE| models the ocean {thermo}dynamics and solves the primitive equations 
     14  (:file:`./src/OCE`) 
     15- |ICE| simulates sea-ice {thermo}dynamics, brine inclusions and 
     16  subgrid-scale thickness variations (:file:`./src/ICE`) 
     17- |MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes 
     18  (:file:`./src/TOP`) 
    2219 
    2320These physical core engines are described in 
     
    3936Several :doc:`built-in configurations<configurations>` are provided to 
    4037evaluate the skills and performances of the model which 
    41 can be used as templates for setting up a new configurations (``./cfgs``). 
     38can be used as templates for setting up a new configurations (:file:`./cfgs`). 
    4239 
    4340The user can also checkout available :doc:`idealized test cases<test_cases>` that 
    44 address specific physical processes (``./tests``). 
     41address specific physical processes (:file:`./tests`). 
    4542 
    46 A set of :doc:`utilities <tools>` is also provided to {pre,post}process your data (``./tools``). 
     43A set of :doc:`utilities <tools>` is also provided to {pre,post}process your data (:file:`./tools`). 
    4744 
    4845Project documentation 
     
    5047 
    5148A walkthrough tutorial illustrates how to get code dependencies, compile and execute NEMO 
    52 (``./INSTALL.rst``). 
     49(:file:`./INSTALL.rst`). 
    5350 
    5451Reference manuals and quick start guide can be build from source and 
    55 exported to HTML or PDF formats (``./doc``) or 
     52exported to HTML or PDF formats (:file:`./doc`) or 
    5653downloaded directly from the :forge:`development platform<wiki/Documentations>`. 
    5754 
    58 ============ ================== ==================== 
    59  Component    Reference Manual   Quick start 
    60 ============ ================== ==================== 
     55============ ================== =================== 
     56 Component    Reference Manual   Quick Start Guide 
     57============ ================== =================== 
    6158 |NEMO-OCE|   |DOI man OCE|_     |DOI strt gui| 
    6259 |NEMO-ICE|   |DOI man ICE| 
    6360 |NEMO-MBG|   |DOI man MBG| 
    64 ============ ================== ==================== 
     61============ ================== =================== 
    6562 
    6663Since 2014 the project has a `Special Issue`_ in the open-access journal 
     
    8784 
    8885.. |DOI dev stgy| replace:: multi-year development strategy 
     86 
     87Disclaimer 
     88========== 
     89 
     90The NEMO source code is freely available and distributed under 
     91:download:`CeCILL v2.0 license <../../../LICENSE>` (GNU GPL compatible). 
     92 
     93You can use, modify and/or redistribute the software under its terms, 
     94but users are provided only with a limited warranty and the software's authors and 
     95the successive licensor's have only limited liability. 
  • NEMO/trunk/REFERENCES.bib

    r10627 r11713  
    1 @manual{NEMO_manual, 
    2    title={NEMO ocean engine}, 
    3    author={Madec Gurvan and NEMO System Team}, 
    4    organization={NEMO Consortium}, 
    5    journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)}, 
    6    number={27}, 
    7    publisher={Zenodo}, 
    8    abstract={The ocean engine of NEMO is a primitive equation model adapted to regional and 
    9    global ocean circulation problems. 
    10    It is intended to be a flexible tool for studying the ocean and its interactions with 
    11    the others components of the earth climate system over a wide range of space and time scales.}, 
    12    doi={10.5281/zenodo.1464816}, 
    13    edition={}, 
    14    year={} 
     1@manual{NEMO_man, 
     2   title="NEMO ocean engine", 
     3   author="NEMO System Team", 
     4   series="Scientific Notes of Climate Modelling Center", 
     5   number="27", 
     6   institution="Institut Pierre-Simon Laplace (IPSL)", 
     7   publisher="Zenodo", 
     8   doi="10.5281/zenodo.1464816", 
    159} 
     10%   edition="", 
     11%   year="" 
    1612 
    17 @manual{SI3_manual, 
    18    title={SI³ – Sea Ice modelling Integrated Initiative – The NEMO Sea Ice engine}, 
    19    author={NEMO Sea Ice Working Group}, 
    20    organization={NEMO Consortium}, 
    21    journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)}, 
    22    number={31}, 
    23    publisher={Zenodo}, 
    24    abstract={SI³ (Sea Ice modelling Integrated Initiative) is the sea ice engine of NEMO 
    25    (Nucleus for European Modelling of the Ocean). 
    26    SI³ is based on the Arctic Ice Dynamics Joint EXperiment (AIDJEX) framework, 
    27    combining the ice thickness distribution framework, the conservation of horizontal momentum, 
    28    an elastic-viscous plastic rheology, and energy-conserving halo-thermodynamics. 
    29    SI³ is interfaced with the NEMO ocean engine, and, via the OASIS coupler, with 
    30    several atmospheric general circulation models. 
    31    It also supports two-way grid embedding via the AGRIF software.}, 
    32    doi={10.5281/zenodo.1471689}, 
    33    edition={}, 
    34    year={} 
     13@manual{SI3_man, 
     14   title="Sea Ice modelling Integrated Initiative (SI$^3$) -- The NEMO Sea Ice engine", 
     15   author="NEMO Sea Ice Working Group", 
     16   series="Scientific Notes of Climate Modelling Center", 
     17   number="31", 
     18   institution="Institut Pierre-Simon Laplace (IPSL)", 
     19   publisher="Zenodo", 
     20   doi="10.5281/zenodo.1471689", 
    3521} 
     22%   edition="", 
     23%   year="" 
    3624 
    37 @manual{TOP_manual, 
    38    title={TOP – Tracers in Ocean Paradigm – The NEMO Tracers engine}, 
    39    author={NEMO TOP Working Group}, 
    40    organization={NEMO Consortium}, 
    41    journal={Notes du Pôle de modélisation de l\'Institut Pierre-Simon Laplace (IPSL)}, 
    42    number={28}, 
    43    publisher={Zenodo}, 
    44    abstract={}, 
    45    doi={10.5281/zenodo.1471700}, 
    46    edition={}, 
    47    year={} 
     25@manual{TOP_man, 
     26   title="Tracers in Ocean Paradigm (TOP) -- The NEMO Tracers engine", 
     27   author="NEMO TOP Working Group", 
     28   series="Scientific Notes of Climate Modelling Center", 
     29   number="28", 
     30   institution="Institut Pierre-Simon Laplace (IPSL)", 
     31   publisher="Zenodo", 
     32   doi="10.5281/zenodo.1471700", 
    4833} 
     34%   edition="", 
     35%   year="" 
    4936 
    50 @Article{gmd-8-1245-2015, 
    51    author = {Vidard, A. and Bouttier, P.-A. and Vigilant, F.}, 
    52    title = {{NEMOTAM}: {T}angent and {A}djoint {M}odels for the ocean modelling platform {NEMO}}, 
    53    journal = {Geoscientific Model Development}, 
    54    volume = {8}, 
    55    year = {2015}, 
    56    number = {4}, 
    57    pages = {1245--1257}, 
    58    doi = {10.5194/gmd-8-1245-2015} 
     37@article{TAM_pub, 
     38   author = "Vidard, A. and Bouttier, P.-A. and Vigilant, F.", 
     39   title = "NEMOTAM: Tangent and Adjoint Models for the ocean modelling platform NEMO", 
     40   journal = "Geoscientific Model Development", 
     41   volume = "8", 
     42   year = "2015", 
     43   number = "4", 
     44   pages = "1245--1257", 
     45   doi = "10.5194/gmd-8-1245-2015" 
    5946} 
  • NEMO/trunk/RELEASE_NOTES.rst

    r10600 r11713  
    33************* 
    44 
    5 New sea-ice component SI3 (in place of LIMx) 
    6 ============================================ 
     5.. todo:: 
    76 
    8 - Physics 
    9  
    10   - Lateral melting 
    11   - Melt ponds: constant or :doi:`Holland et al. 2012<10.1175/JCLI-D-11-00078.1>` formulation (and soon topographic melt ponds) 
    12   - Ice-atm. drags from :doi:`Lupkes et al. 2012<10.1029/2012JD017630>` (depending on ice concentration) or :doi:`Lupkes et al. 2015<10.1002/2014JD022418>` (depending on sea ice concentration and atm. stability) 
    13   - Landfast ice (:doi:`Lemieux et al. 2016<10.1002/2016JC012006>`) 
    14  
    15 - Numerics 
    16  
    17   - Advection: Ultimate-Macho scheme 
    18   - Rheology: adaptive EVP (:doi:`Kimmritz et al. 2017<10.1016/j.ocemod.2016.03.004>`) 
    19   - Coupling interface: conductivity as surface forcing instead of heat fluxes (Met Office requirement) 
    20  
    21 - Performance: all thermodynamics in 1D and reduced mpp communications 
    22 - Usability (users & developers friendly) 
    23  
    24   - Comprehensive set of outputs (universal units and understandable names + includes CMIP) 
    25   - New architecture and namelist 
    26   - All processes can be decoupled from each other (switch on/off) 
    27   - Ice categories bounds can be defined by the user or set automatically 
    28   - For open boundaries, the number of ice categories from the forcing model can be different from the number of categories in the regional simulation 
    29   - Fully compatible with AGRIF_ 
    30   - Revised documentation  
    31  
    32 AGRIF for embedded zooms 
    33 ======================== 
    34  
    35 - Now compatible with new sea ice component 
    36 - Now compatible with z* coordinate 
    37 - Extended ghost cells area to properly handle scheme with spatial order >2 
    38 - Added vertical refinement (beta) 
    39 - Nesting tools for setup now up to date and working  
    40  
    41 Enhancements 
    42 ============ 
    43  
    44 - Fix for tracer conservation with split explicit free surface 
    45 - Bulk formulae : move to aerobulk package (:doi:`Brodeau et al. 2016<10.1175/JPO-D-16-0169.1>`), i.e. NCAR, COARE and ECMWF bulk (remove Clio and MFS bulk) 
    46 - Wetting and drying 
    47 - Added tidal self attraction and loading either read from a file or from usual "scalar" approximation 
    48 - Add a 4th order centered (CEN) and Flux Corrected Transport (FCT) tracer advection 
    49   (using a 4th compact in the vertical) 
    50 - iso-neutral mixing (iso and triad operators): 
    51   add the Method of Stabilizing Correction (MSC) (more accurate calculation) + add a bilaplacian case 
    52 - Lateral physics (``LDF``): scale aware setting of eddy viscosity and diffusivity 
    53 - Vorticity: 2 new energy conserving scheme: ENT with Coriolis defined at T-point (better for Flux form) and EET a variant of EEN where e3t is used instead of e3f (solved the issue with e3f specification but is not enstrophy conserving)  
    54  
    55 Test Cases 
    56 ========== 
    57  
    58 The first test cases available for now are: 
    59  
    60 - ``CANAL``: east-west periodic canal of variable size with several initial states and associated geostrophic currents (zonal jets or vortex) 
    61 - ``ICE_AGRIF``: east-west + north-south periodic channel. The common configuration includes an AGRIF zoom (1:3) in the middle of the basin to test how an ice patch is advected through it but one can also test the advection schemes (Prather and Ultimate-Macho) by removing the ``key_agrif`` in the cpp keys 
    62 - ``ISOMIP``: simple box configuration with an ice shelf with simple geometry on top. The purpose of this test case is to evaluate the impact of various schemes and new development with iceshelf cavities. The exact original setup is described ​here 
    63 - ``LOCK-EXCHANGE``: classical fluid dynamics experiment that has been adapted by Haidvogel and Beckmann (1999) for testing advection schemes in ocean circulation models. It has been used by several authors including Burchard and Bolding (2002) and :doi:`Ilıcak et al. (2012)<10.1016/j.ocemod.2011.10.003>`. The ``LOCK EXCHANGE`` experiment can in particular illustrate the impact of different choices of numerical schemes and/or subgrid closures on spurious interior mixing 
    64 - ``OVERFLOW``: illustrates the impact of different choices of numerical schemes and/or subgrid closures on spurious interior mixing close to bottom topography. It is adapted from the non-rotating overflow configuration described in Haidvogel and Beckmann (1999) and further used by :doi:`Ilıcak et al. (2012)<10.1016/j.ocemod.2011.10.003>` 
    65 - ``VORTEX``: illustrates the propagation of an anticyclonic eddy over a Beta plan and flat bottom. It is implemented here with an online refined subdomain (thanks to ``AGRIF`` library) out of which the vortex propagates. It serves as a benchmark to diagnose nesting errors as in :doi:`Debreu et al. (2012)<10.1016/j.ocemod.2012.03.003>`, :doi:`Penven et al. (2006)<10.1016/j.ocemod.2005.05.002>` and :doi:`Spall and Holland (1991)<10.1175/1520-0485(1991)021<0205:ANPEMF>2.0.CO;2>` 
    66 - ``WAD``: a set of simple closed basin geometries for testing the wetting and drying capabilities. Examples range from a closed channel with EW linear bottom slope to a parabolic EW channel with a Gaussian ridge 
    67  
    68 New Reference configurations 
    69 ============================ 
    70  
    71 ``AGRIF_DEMO``: 2 interlocked zooms (1:4 & 1:3) in the Nordic Seas + 1 zoom (1:1) at the equator 
    72  
    73 ``SPITZ12``: regional configuration around the Svalbard archipelago  
    74  
    75 Wave coupling 
    76 ============= 
    77  
    78 Coupled interface to external wave model 
    79  
    80 Large scale wave interaction process added in momentum and tracer equations  
    81  
    82 Passive tracer TOP and biogeochemical PISCES components 
    83 ======================================================= 
    84  
    85 - The passive tracers transport component was redesigned toward a modular structure and users can enable each module directly through logical flags in namelist_top (no more fortran macros!) 
    86 - :doc:`TOP on-line user documentation<tracers>` 
    87 - TOP currently accounts for the following 5 modules: ``CFC`` contains inorganic carbon tracers (CFC11/CFC12/SF6), ``MY_TRC`` is a template for new modules (or external couplings), ``AGE`` deals with water age tracking, ``C14`` as a radiocarbon passive tracer, and the companion ecosystem model ``PISCES`` 
    88 - A generalized infrastructure was developed to handle the prescription of either surface, coastal, or open boundaries conditions for each passive tracer 
    89 - A new configuration, named ``ORCA2_OFF_TRC``, was created to provide a benchmark simulation environment to deal with inert carbon tracers dynamics by exploiting the offline coupling with NEMO 
    90 - PISCES model contains new developments and modifications: 
    91  
    92   - Particulate Organic Carbon (POC) component comes with a new liability scheme, while the former Kriest parametrisation was superseded 
    93   - A complex iron chemistry scheme is now available, with an improved description of ligands for the marine iron cycle 
    94   - Carbonate chemistry is based on MOCSY 2.0 routines (see :doi:`10.5194/gmd-8-485-2015 <Orr and Epitalon, 2015>`), by complying also with CMIP6 standards 
    95   - Ecosystem components can be optionally modelled by means of explicit nutrient quotas (PISCES-QUOTA)  
    96  
    97 High Performance Computing (HPC): performances improvements 
    98 =========================================================== 
    99  
    100 - Reduce number of MPI communications 
    101   (suppression of redundant communications, gather multiple communications into one) 
    102 - Use of MPI-3 asynchronous routines for performance (use ``key_mpi2`` if MPI-3 not available) 
    103 - Back to standard dynamical allocation (remove of wrk_alloc/dealloc statements) 
    104 - :xios:`XIOS software<>` for IOs version 2.5 as default, and optionally available for restarts  
    105  
    106 Simplification and robustness 
    107 ============================= 
    108  
    109 - Revised structure of ``namelist_ref`` / ``namelist_cfg`` and default reference values 
    110 - Lateral physics (``LDF``): simplification of user interface and removal of CPP keys 
    111 - Vertical physics (``ZDF``) (modularity, share shear production calculation between TKE and GKS, removal of all ZDF CPP keys, removal of ``avmu`` & ``avmv``, minimization of MPP comm.: ~15 removed) 
    112 - Remove the split-explicit ZDF scheme for both ``TRA`` and ``DYN`` 
    113 - Remove the acceleration of convergence 
    114 - Generalised ``lbc_lnk`` and ``lbc_nfd`` 
    115 - Unify mppini 
    116 - Use non uniform jpi/jpj with dynamic allocation to avoid ghost rows/columns 
    117 - MPI Message passing re coded 
    118 - Configuration interface completely rewritten (``DOM`` module mainly suppressed , and in place: ``domain_cfg.nc`` file, or ``usr_def`` module)  
    119  
    120 Collaborative Development Environment 
    121 ===================================== 
    122  
    123 - Access to information on wiki reorganised through portals for users/developers/System Team and complete refactoring of all pages and their layout 
    124 - Reorganisation of SVN repository to be compliant with usual directory tree and facilitate building of the executable 
    125 - Define and install a separate repository for test cases to all easy contributions from the community 
    126 - :forge:`Forums<discussion>` created 
    127 - :website:`Public web site<>` has been revamped and cleaned using Wordpress 
    128 - New mailing lists have been set up 
    129 - Improvements of reliability through automatic and regular testing of the changes made in repository  
     7   Complete "Release Notes" 
  • NEMO/trunk/doc/rst/Makefile

    r11706 r11713  
    1515I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source 
    1616 
    17 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 
     17.PHONY: help clean html dirhtml drafthtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 
    1818 
    1919help: 
     
    2121   @echo "  html       to make standalone HTML files" 
    2222   @echo "  dirhtml    to make HTML files named index.html in directories" 
     23   @echo "  drafthtml  to make an autoupdate HTML export while editing (todo list included)" 
    2324   @echo "  singlehtml to make a single large HTML file" 
    24    @echo "  livehtml   to make an autoupdate HTML export while editing" 
    2525   @echo "  pickle     to make pickle files" 
    2626   @echo "  json       to make JSON files" 
     
    4444 
    4545html: 
    46    $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 
     46   $(SPHINXBUILD)   -b html          $(ALLSPHINXOPTS) $(BUILDDIR)/html 
    4747   @echo 
    4848   @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 
    4949 
    5050dirhtml: 
    51    $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 
     51   $(SPHINXBUILD)   -b dirhtml      $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 
    5252   @echo 
    5353   @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 
    5454 
     55drafthtml: 
     56   sphinx-autobuild -b html -t draft $(ALLSPHINXOPTS) $(BUILDDIR)/drafthtml 
     57   @echo 
     58   @echo "Build finished. The HTML pages are in $(BUILDDIR)/drafthtml." 
     59 
    5560singlehtml: 
    56    $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 
     61   $(SPHINXBUILD)   -b singlehtml    $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 
    5762   @echo 
    5863   @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 
    5964 
    60 livehtml: 
    61    sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 
    62    @echo 
    63    @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 
    64  
    6565pickle: 
    66    $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 
     66   $(SPHINXBUILD)   -b pickle        $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 
    6767   @echo 
    6868   @echo "Build finished; now you can process the pickle files." 
    6969 
    7070json: 
    71    $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 
     71   $(SPHINXBUILD)   -b json          $(ALLSPHINXOPTS) $(BUILDDIR)/json 
    7272   @echo 
    7373   @echo "Build finished; now you can process the JSON files." 
    7474 
    7575htmlhelp: 
    76    $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 
     76   $(SPHINXBUILD)   -b htmlhelp      $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 
    7777   @echo 
    7878   @echo "Build finished; now you can run HTML Help Workshop with the" \ 
     
    8080 
    8181qthelp: 
    82    $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 
     82   $(SPHINXBUILD)   -b qthelp        $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 
    8383   @echo 
    8484   @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 
     
    8989 
    9090devhelp: 
    91    $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 
     91   $(SPHINXBUILD)   -b devhelp      $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 
    9292   @echo 
    9393   @echo "Build finished." 
     
    9898 
    9999epub: 
    100    $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 
     100   $(SPHINXBUILD)   -b epub          $(ALLSPHINXOPTS) $(BUILDDIR)/epub 
    101101   @echo 
    102102   @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 
    103103 
    104104latex: 
    105    $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 
     105   $(SPHINXBUILD)   -b latex        $(ALLSPHINXOPTS) $(BUILDDIR)/latex 
    106106   @echo 
    107107   @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 
     
    110110 
    111111latexpdf: 
    112    $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 
     112   $(SPHINXBUILD)   -b latex        $(ALLSPHINXOPTS) $(BUILDDIR)/latex 
    113113   @echo "Running LaTeX files through pdflatex..." 
    114114   $(MAKE) -C $(BUILDDIR)/latex all-pdf 
     
    116116 
    117117text: 
    118    $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 
     118   $(SPHINXBUILD)   -b text          $(ALLSPHINXOPTS) $(BUILDDIR)/text 
    119119   @echo 
    120120   @echo "Build finished. The text files are in $(BUILDDIR)/text." 
    121121 
    122122man: 
    123    $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 
     123   $(SPHINXBUILD)   -b man          $(ALLSPHINXOPTS) $(BUILDDIR)/man 
    124124   @echo 
    125125   @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 
    126126 
    127127texinfo: 
    128    $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 
     128   $(SPHINXBUILD)   -b texinfo      $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 
    129129   @echo 
    130130   @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 
     
    133133 
    134134info: 
    135    $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 
     135   $(SPHINXBUILD)   -b texinfo      $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 
    136136   @echo "Running Texinfo files through makeinfo..." 
    137137   make -C $(BUILDDIR)/texinfo info 
     
    139139 
    140140gettext: 
    141    $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 
     141   $(SPHINXBUILD)   -b gettext      $(I18NSPHINXOPTS) $(BUILDDIR)/locale 
    142142   @echo 
    143143   @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 
    144144 
    145145changes: 
    146    $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 
     146   $(SPHINXBUILD)   -b changes      $(ALLSPHINXOPTS) $(BUILDDIR)/changes 
    147147   @echo 
    148148   @echo "The overview file is in $(BUILDDIR)/changes." 
    149149 
    150150linkcheck: 
    151    $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 
     151   $(SPHINXBUILD)   -b linkcheck    $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 
    152152   @echo 
    153153   @echo "Link check complete; look for any errors in the above output " \ 
     
    155155 
    156156doctest: 
    157    $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 
     157   $(SPHINXBUILD)   -b doctest      $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 
    158158   @echo "Testing of doctests in the sources finished, look at the " \ 
    159159         "results in $(BUILDDIR)/doctest/output.txt." 
  • NEMO/trunk/doc/rst/source/NEMO_guide.rst

    r11707 r11713  
    1212   ", for paragraphs 
    1313 
    14    'global.rst' contains a list of common directives (roles, substitutions and URL links) 
    15    It is loaded for each file thanks to 'rst_epilog' setting in 'conf.py' 
     14   'global.rst' contains a list of roles, substitutions and URL links for the guide. 
     15   It is loaded for each file with the 'rst_epilog' setting in 'conf.py' 
    1616 
    1717.. toctree:: 
     
    4949   glossary 
    5050 
     51:Release:  |release| 
     52 
     53.. only:: draft 
     54 
     55   .. include:: todos.rst 
     56 
    5157.. include:: readme.rst 
    52  
    53 .. Next headings markup acording to readme.rst 
    54  
    55 Disclaimer 
    56 ========== 
    57  
    58 The NEMO source code is freely available and distributed under CeCILL license 
    59 (GNU GPL compatible - see ``./LICENSE``). 
    60  
    61 You can use, modify and/or redistribute the software under its terms, 
    62 but users are provided only with a limited warranty and the software's authors and 
    63 the successive licensor's have only limited liability. 
  • NEMO/trunk/doc/rst/source/citations.rst

    r11707 r11713  
    1 **************** 
    2 How to cite NEMO 
    3 **************** 
     1*********** 
     2How to cite 
     3*********** 
    44 
    5  
    6 |NEMO-OCE| :cite:`NEMO_manual` 
    7  
    8    | "**NEMO ocean engine**" 
    9    | Gurvan Madec and NEMO System Team 
    10    | *Scientific Notes of Climate Modelling Center*, **27** 
    11    | ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL) 
    12    | |DOI man OCE|_ 
     5|NEMO-OCE| 
     6   :title:`NEMO ocean engine`, 
     7   NEMO System Team, 
     8   Scientific Notes of Climate Modelling Center, 27, 
     9   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL), 
     10   :doi:`10.5281/zenodo.1464816` 
    1311 
    1412.. literalinclude:: references.bib 
    1513   :language: bibtex 
    16    :lines:    1-15 
     14   :lines:    1-9 
    1715   :caption:  BibTeX source for NEMO manual 
    1816 
    19 |NEMO-ICE| :cite:`SI3_manual` 
    20  
    21    | "**Sea Ice modelling Integrated Initiative (SI** :sup:`3` **) -- The NEMO sea ice engine**" 
    22    | NEMO Sea Ice Working Group 
    23    | *Scientific Notes of Climate Modelling Center*, **31** 
    24    | ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL) 
    25    | |DOI man ICE| 
     17|NEMO-ICE| 
     18   :title:`Sea Ice modelling Integrated Initiative (SI`\ :sup:`3`\ :title:`) -- 
     19   The NEMO sea ice engine`, 
     20   NEMO Sea Ice Working Group, 
     21   Scientific Notes of Climate Modelling Center, 31, 
     22   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL), 
     23   :doi:`10.5281/zenodo.1471689` 
    2624 
    2725.. warning::  No official publication yet 
     
    2927.. literalinclude:: references.bib 
    3028   :language: bibtex 
    31    :lines:    17-33 
     29   :lines:    13-21 
    3230   :caption:  BibTeX source for SI\ :sup:`3` manual 
    3331 
    34 |NEMO-MBG| :cite:`TOP_manual` 
    35  
    36    | "**Tracer in Ocean Paradigm (TOP) -- The NEMO passive tracer engine**" 
    37    | NEMO TOP Working Group 
    38    | *Scientific Notes of Climate Modelling Center*, **28** 
    39    | ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL) 
    40    | |DOI man MBG| 
     32|NEMO-MBG| 
     33   :title:`Tracer in Ocean Paradigm (TOP) -- The NEMO passive tracer engine`, 
     34   NEMO TOP Working Group, 
     35   Scientific Notes of Climate Modelling Center, 28, 
     36   ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL), 
     37   :doi:`10.5281/zenodo.1471700` 
    4138 
    4239.. warning::  No official publication yet 
     
    4441.. literalinclude:: references.bib 
    4542   :language: bibtex 
    46    :lines:    37-49 
     43   :lines:    25-33 
    4744   :caption:  BibTeX source for TOP manual 
    48  
    49 References 
    50 ========== 
    51  
    52 .. bibliography:: references.bib 
    53    :style:       unsrt 
    54    :labelprefix: R 
  • NEMO/trunk/doc/rst/source/conf.py

    r11706 r11713  
    2626# Add any Sphinx extension module names here, as strings. They can be extensions 
    2727# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 
    28 extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex', 'sphinx.ext.todo'] 
     28extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex', 'sphinx.ext.todo', 'sphinxmark'] 
    2929 
    3030# Add any paths that contain templates here, relative to this directory. 
     
    251251# Link aliases 
    252252extlinks = { 
    253    'doi'    : ('https://doi.org/%s'                       , None), 
    254    'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'    , None), 
    255    'github' : ('https://github.com/%s'                    , None), 
    256    'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s', None), 
    257    'website': ('https://www.nemo-ocean.eu/%s'             , None), 
    258    'zenodo' : ('https://zenodo.org/publication/%s'        , None) 
     253   'doi'    : ('https://doi.org/%s'                       , 'doi:'), 
     254   'forge'  : ('https://forge.ipsl.jussieu.fr/nemo/%s'    ,   None), 
     255   'github' : ('https://github.com/%s'                    ,   None), 
     256   'xios'   : ('https://forge.ipsl.jussieu.fr/ioserver/%s',   None), 
     257   'website': ('https://www.nemo-ocean.eu/%s'             ,   None), 
     258   'zenodo' : ('https://zenodo.org/publication/%s'        ,   None) 
    259259} 
    260260 
     
    266266revision = subprocess.check_output("svnversion").decode("utf-8") 
    267267rst_prolog = '.. |revision| replace:: %s' % revision 
     268 
     269# Todo 
     270if tags.has('draft'): 
     271    sphinxmark_enable = True 
     272    todo_include_todos = True 
     273    todo_emit_warnings = True 
  • NEMO/trunk/doc/rst/source/data_assimilation.rst

    r11707 r11713  
    4040To build the SAO use makenemo. 
    4141This means compiling NEMO once (in the normal way) for the chosen configuration. 
    42 Then include ``SAO`` at the end of the relevant line in ``cfg.txt`` file. 
    43 Then recompile with the replacement main program in ``./src/SAO``. 
    44 This is a special version of ``nemogcm.F90`` (which doesn't run the model, 
     42Then include ``SAO`` at the end of the relevant line in :file:`cfg.txt` file. 
     43Then recompile with the replacement main program in :file:`./src/SAO`. 
     44This is a special version of :file:`nemogcm.F90` (which doesn't run the model, 
    4545but reads in the model fields, and observations and runs the OBS code. 
    4646See "Standalone observation operator (``SAO``)" section in |DOI man OCE|_. 
  • NEMO/trunk/doc/rst/source/global.rst

    r11707 r11713  
    55.. role:: grey 
    66.. role:: greysup(sup) 
    7 .. role: underline 
    8 ..   :class: underline 
    97 
    108.. Substitutions 
    119 
    12 .. |NEMO-OCE| replace:: :blue:`NEMO-OCE (Ocean dynamics)` 
    13 .. |NEMO-ICE| replace:: :grey:`NEMO-SI`\ :greysup:`3`\ :grey:`(Sea Ice)` 
    14 .. |NEMO-MBG| replace:: :green:`NEMO-TOP/PISCES (Biogeochemistry)` 
     10.. |NEMO-OCE| replace::  :blue:`NEMO-OCE (Ocean dynamics)` 
     11.. |OCE|      replace::  :blue:`NEMO-OCE` 
     12.. |NEMO-ICE| replace::  :grey:`NEMO-SI`\ :greysup:`3`  :grey:`(Sea Ice)` 
     13.. |ICE|      replace::  :grey:`NEMO-SI`\ :greysup:`3` 
     14.. |NEMO-MBG| replace:: :green:`NEMO-TOP/PISCES (Tracers)` 
     15.. |MBG|      replace:: :green:`NEMO-TOP/PISCES` 
    1516 
    1617.. External links 
     
    3738.. _EGU: http://www.egu.eu 
    3839.. _Special Issue: https://www.geosci-model-dev.net/special_issue40.html 
     40.. _BFM man: https://cmcc-foundation.github.io/www.bfm-community.eu/files/bfm-nemo-manual_r1.0_201508.pdf 
    3941 
    4042.. DOI 
  • NEMO/trunk/doc/rst/source/glossary.rst

    r11707 r11713  
    33******** 
    44 
    5 `AGRIF`_ 
    6    *Adaptive Grid Refinement In Fortran*, 
    7    package for the integration of full adaptive mesh refinement features within 
    8    an existing multidimensional finite difference model 
     5.. glossary:: 
    96 
    10 SI\ :sup:`3`\ 
    11    *Sea Ice Integrated Initiative*, 
    12    unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework 
     7   `AGRIF`_ 
     8      *Adaptive Grid Refinement In Fortran*, 
     9      package for the integration of full adaptive mesh refinement features within 
     10      an existing multidimensional finite difference model 
    1311 
    14 `OASIS`_ 
    15    *Ocean Atmosphere Sea Ice Soil*, 
    16    coupling software to synchronise numerical codes representing different components of the climate system 
     12   SI\ :sup:`3`\ 
     13      *Sea Ice Integrated Initiative*, 
     14      unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework 
    1715 
    18 PISCES 
    19    *Pelagic Interactions Scheme for Carbon and Ecosystem Studies*, 
    20    biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients 
     16   `OASIS`_ 
     17      *Ocean Atmosphere Sea Ice Soil*, 
     18      coupling software to synchronise numerical codes representing different components of the climate system 
    2119 
    22 TAM 
    23    *Tangent linear and Adjoint Model*, 
    24    tools to analyse and control the NEMO dynamical core for a wide range of applications such as 
    25    sensitivity analysis, parameter estimation, vectors computation or data assimilation. 
     20   PISCES 
     21      *Pelagic Interactions Scheme for Carbon and Ecosystem Studies*, 
     22      biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients 
    2623 
    27 TOP 
    28    *Tracers in Ocean Paradigm*, 
    29    on/off-line oceanic tracers transport and biogeochemistry models 
     24   TAM 
     25      *Tangent linear and Adjoint Model*, 
     26      tools to analyse and control the NEMO dynamical core for a wide range of applications such as 
     27      sensitivity analysis, parameter estimation, vectors computation or data assimilation. 
    3028 
    31 `XIOS`_ 
    32    *XML Input Output Server*, 
    33    library dedicated to input/output management of climate code 
     29   TOP 
     30      *Tracers in Ocean Paradigm*, 
     31      on/off-line oceanic tracers transport and biogeochemistry models 
     32 
     33   `XIOS`_ 
     34      *XML Input Output Server*, 
     35      library dedicated to input/output management of climate code 
  • NEMO/trunk/src/TOP/README.rst

    r11708 r11713  
    44 
    55.. contents:: 
    6    :local: 
    7  
    8 TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward biogeochemical models and 
    9 provide the physical constraints/boundaries for oceanic tracers. 
    10 It consists of a modular framework to handle multiple ocean tracers, including also a variety of built-in modules. 
     6   :local: 
     7 
     8TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward 
     9biogeochemical models and provide the physical constraints/boundaries for oceanic tracers. 
     10It consists of a modular framework to handle multiple ocean tracers, 
     11including also a variety of built-in modules. 
    1112 
    1213This component of the NEMO framework allows one to exploit available modules (see below) and 
    1314further develop a range of applications, spanning from the implementation of a dye passive tracer to 
    1415evaluate dispersion processes (by means of MY_TRC), track water masses age (AGE module), 
    15 assess the ocean interior penetration of persistent chemical compounds (e.g., gases like CFC or even PCBs), 
    16 up to the full set of equations involving marine biogeochemical cycles. 
     16assess the ocean interior penetration of persistent chemical compounds 
     17(e.g., gases like CFC or even PCBs), up to the full set of equations involving 
     18marine biogeochemical cycles. 
    1719 
    1820Structure 
    1921========= 
    2022 
    21 TOP interface has the following location in the source code ``./src/MBG/`` and 
     23TOP interface has the following location in the source code :file:`./src/TOP` and 
    2224the following modules are available: 
    2325 
    24 ``TRP`` 
    25    Interface to NEMO physical core for computing tracers transport 
    26  
    27 ``CFC`` 
    28    Inert carbon tracers (CFC11,CFC12,SF6) 
    29  
    30 ``C14`` 
    31    Radiocarbon passive tracer 
    32  
    33 ``AGE`` 
    34    Water age tracking 
    35  
    36 ``MY_TRC`` 
    37    Template for creation of new modules and external BGC models coupling 
    38  
    39 ``PISCES`` 
    40    Built in BGC model. 
    41    See [https://www.geosci-model-dev.net/8/2465/2015/gmd-8-2465-2015-discussion.html Aumont et al. (2015)] for 
    42    a throughout description. | 
    43  
    44 The usage of TOP is activated i) by including in the configuration definition  the component ``MBG`` and 
    45 ii) by adding the macro ``key_top`` in the configuration CPP file 
    46 (see for more details [http://forge.ipsl.jussieu.fr/nemo/wiki/Users "Learn more about the model"]). 
     26:file:`TRP` 
     27   Interface to NEMO physical core for computing tracers transport 
     28 
     29:file:`CFC` 
     30   Inert carbon tracers (CFC11,CFC12,SF6) 
     31 
     32:file:`C14` 
     33   Radiocarbon passive tracer 
     34 
     35:file:`AGE` 
     36   Water age tracking 
     37 
     38:file:`MY_TRC` 
     39   Template for creation of new modules and external BGC models coupling 
     40 
     41:file:`PISCES` 
     42   Built in BGC model. See :cite:`gmd-8-2465-2015` for a throughout description. 
     43 
     44The usage of TOP is activated 
     45*i)* by including in the configuration definition the component ``TOP`` and 
     46*ii)* by adding the macro ``key_top`` in the configuration CPP file 
     47(see for more details :forge:`"Learn more about the model" <wiki/Users>`). 
    4748 
    4849As an example, the user can refer to already available configurations in the code, 
     
    5152(see also Section 4) . 
    5253 
    53 Note that, since version 4.0, TOP interface core functionalities are activated by means of logical keys and 
     54Note that, since version 4.0, 
     55TOP interface core functionalities are activated by means of logical keys and 
    5456all submodules preprocessing macros from previous versions were removed. 
    5557 
     
    5759 
    5860``key_iomput`` 
    59    use XIOS I/O 
     61   use XIOS I/O 
    6062 
    6163``key_agrif`` 
    62    enable AGRIF coupling 
     64   enable AGRIF coupling 
    6365 
    6466``key_trdtrc`` & ``key_trdmxl_trc`` 
    65    trend computation for tracers 
     67   trend computation for tracers 
    6668 
    6769Synthetic Workflow 
    6870================== 
    6971 
    70 A synthetic description of the TOP interface workflow is given below to summarize the steps involved in 
    71 the computation of biogeochemical and physical trends and their time integration and outputs, 
     72A synthetic description of the TOP interface workflow is given below to 
     73summarize the steps involved in the computation of biogeochemical and physical trends and 
     74their time integration and outputs, 
    7275by reporting also the principal Fortran subroutine herein involved. 
    7376 
    74 **Model initialization (OPA_SRC/nemogcm.F90)** 
    75  
    76 call to trc_init (trcini.F90) 
    77  
    78   ↳ call trc_nam (trcnam.F90) to initialize TOP tracers and run setting 
    79  
    80   ↳ call trc_ini_sms, to initialize each submodule 
    81  
    82   ↳ call trc_ini_trp, to initialize transport for tracers 
    83  
    84   ↳ call trc_ice_ini, to initialize tracers in seaice 
    85  
    86   ↳ call trc_ini_state, read passive tracers from a restart or input data 
    87  
    88   ↳ call trc_sub_ini, setup substepping if {{{nn_dttrc /= 1}}} 
    89  
    90 **Time marching procedure (OPA_SRC/stp.F90)** 
    91  
    92 call to trc_stp.F90 (trcstp.F90) 
    93  
    94   ↳ call trc_sub_stp, averaging physical variables for sub-stepping 
    95  
    96   ↳ call trc_wri, call XIOS for output of data 
    97  
    98   ↳ call trc_sms, compute BGC trends for each submodule 
    99  
    100     ↳ call trc_sms_my_trc, includes also surface and coastal BCs trends 
    101  
    102   ↳ call trc_trp (TRP/trctrp.F90), compute physical trends 
    103  
    104     ↳ call trc_sbc, get trend due to surface concentration/dilution 
    105  
    106     ↳ call trc_adv, compute tracers advection 
    107  
    108     ↳ call to trc_ldf, compute tracers lateral diffusion 
    109  
    110     ↳ call to trc_zdf, vertical mixing and after tracer fields 
    111  
    112     ↳ call to trc_nxt, tracer fields at next time step. Lateral Boundary Conditions are solved in here. 
    113  
    114     ↳ call to trc_rad, Correct artificial negative concentrations 
    115  
    116   ↳ call trc_rst_wri, output tracers restart files 
     77Model initialization (:file:`./src/OCE/nemogcm.F90`) 
     78---------------------------------------------------- 
     79 
     80Call to ``trc_init`` subroutine (:file:`./src/TOP/trcini.F90`) to initialize TOP. 
     81 
     82.. literalinclude:: ../../../src/TOP/trcini.F90 
     83   :language:        fortran 
     84   :lines:           41-86 
     85   :emphasize-lines: 21,30-32,38-40 
     86   :caption:         ``trc_init`` subroutine 
     87 
     88Time marching procedure (:file:`./src/OCE/step.F90`) 
     89---------------------------------------------------- 
     90 
     91Call to ``trc_stp`` subroutine (:file:`./src/TOP/trcstp.F90`) to compute/update passive tracers. 
     92 
     93.. literalinclude:: ../../../src/TOP/trcstp.F90 
     94   :language:        fortran 
     95   :lines:           46-125 
     96   :emphasize-lines: 42,55-57 
     97   :caption:         ``trc_stp`` subroutine 
     98 
     99BGC trends computation for each submodule (:file:`./src/TOP/trcsms.F90`) 
     100------------------------------------------------------------------------ 
     101 
     102.. literalinclude:: ../../../src/TOP/trcsms.F90 
     103   :language:        fortran 
     104   :lines:           21 
     105   :caption:         :file:`trcsms` snippet 
     106 
     107Physical trends computation (:file:`./src/TOP/TRP/trctrp.F90`) 
     108-------------------------------------------------------------- 
     109 
     110.. literalinclude:: ../../../src/TOP/TRP/trctrp.F90 
     111   :language:        fortran 
     112   :lines:           46-95 
     113   :emphasize-lines: 17,21,29,33-35 
     114   :caption:         ``trc_trp`` subroutine 
    117115 
    118116Namelists walkthrough 
    119117===================== 
    120118 
    121 namelist_top 
    122 ------------ 
    123  
    124 Here below are listed the features/options of the TOP interface accessible through the namelist_top_ref and 
    125 modifiable by means of namelist_top_cfg (as for NEMO physical ones). 
    126  
    127 Note that ## is used to refer to a number in an array field. 
     119:file:`namelist_top` 
     120-------------------- 
     121 
     122Here below are listed the features/options of the TOP interface accessible through 
     123the :file:`namelist_top_ref` and modifiable by means of :file:`namelist_top_cfg` 
     124(as for NEMO physical ones). 
     125 
     126Note that ``##`` is used to refer to a number in an array field. 
    128127 
    129128.. literalinclude:: ../../namelists/namtrc_run 
     
    166165   :language: fortran 
    167166 
    168 Two main types of data structure are used within TOP interface to initialize tracer properties (1) and 
     167Two main types of data structure are used within TOP interface 
     168to initialize tracer properties (1) and 
    169169to provide related initial and boundary conditions (2). 
    170170 
    171 **1. TOP tracers initialization**: sn_tracer (namtrc) 
     1711. TOP tracers initialization: ``sn_tracer`` (``&namtrc``) 
     172^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
    172173 
    173174Beside providing name and metadata for tracers, 
    174 here are also defined the use of initial ({{{sn_tracer%llinit}}}) and 
    175 boundary ({{{sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc}}}) conditions. 
    176  
    177 In the following, an example of the full structure definition is given for two idealized tracers both with 
    178 initial conditions given, while the first has only surface boundary forcing and 
     175here are also defined the use of initial (``sn_tracer%llinit``) and 
     176boundary (``sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc``) conditions. 
     177 
     178In the following, an example of the full structure definition is given for 
     179two idealized tracers both with initial conditions given, 
     180while the first has only surface boundary forcing and 
    179181the second both surface and coastal forcings: 
    180182 
    181183.. code-block:: fortran 
    182184 
    183    !             !    name   !           title of the field            !   units    ! initial data ! sbc   !   cbc  !   obc  ! 
    184    sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,  .true.      , .true., .false., .true. 
    185    sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,  .true.      , .true., .true. , .false. 
     185   !             !    name   !           title of the field            !   units    ! initial data ! sbc   !   cbc  !   obc  ! 
     186   sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,  .true.      , .true., .false., .true. 
     187   sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,  .true.      , .true., .true. , .false. 
    186188 
    187189As tracers in BGC models are increasingly growing, 
     
    190192.. code-block:: fortran 
    191193 
    192    !             !    name   !           title of the field            !   units    ! initial data ! 
    193    sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,   .true. 
    194    sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,   .true. 
    195    ! sbc 
    196    sn_tracer(1)%llsbc = .true. 
    197    sn_tracer(2)%llsbc = .true. 
    198    ! cbc 
    199    sn_tracer(2)%llcbc = .true. 
     194   !             !    name   !           title of the field            !   units    ! initial data ! 
     195   sn_tracer(1)  = 'TRC1'    , 'Tracer 1 Concentration                ',   ' - '    ,   .true. 
     196   sn_tracer(2)  = 'TRC2 '   , 'Tracer 2 Concentration                ',   ' - '    ,   .true. 
     197   ! sbc 
     198   sn_tracer(1)%llsbc = .true. 
     199   sn_tracer(2)%llsbc = .true. 
     200   ! cbc 
     201   sn_tracer(2)%llcbc = .true. 
    200202 
    201203The data structure is internally initialized by code with dummy names and 
    202 all initialization/forcing logical fields set to .false. . 
    203  
    204 **2. Structures to read input initial and boundary conditions**: namtrc_dta (sn_trcdta), namtrc_bc (sn_trcsbc/sn_trccbc/sn_trcobc) 
     204all initialization/forcing logical fields set to ``.false.`` . 
     205 
     2062. Structures to read input initial and boundary conditions: ``&namtrc_dta`` (``sn_trcdta``), ``&namtrc_bc`` (``sn_trcsbc`` / ``sn_trccbc`` / ``sn_trcobc``) 
     207^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
    205208 
    206209The overall data structure (Fortran type) is based on the general one defined for NEMO core in the SBC component 
    207 (see details in User Manual SBC Chapter on Input Data specification). 
    208  
    209 Input fields are prescribed within namtrc_dta (with sn_trcdta structure), 
    210 while Boundary Conditions are applied to the model by means of namtrc_bc, 
    211 with dedicated structure fields for surface (sn_trcsbc), riverine (sn_trccbc), and 
    212 lateral open (sn_trcobc) boundaries. 
     210(see details in ``SBC`` Chapter of :doc:`Reference Manual <citations>` on Input Data specification). 
     211 
     212Input fields are prescribed within ``&namtrc_dta`` (with ``sn_trcdta`` structure), 
     213while Boundary Conditions are applied to the model by means of ``&namtrc_bc``, 
     214with dedicated structure fields for surface (``sn_trcsbc``), riverine (``sn_trccbc``), and 
     215lateral open (``sn_trcobc``) boundaries. 
    213216 
    214217The following example illustrates the data structure in the case of initial condition for 
    215 a single tracer contained in the file named tracer_1_data.nc (.nc is implicitly assumed in namelist filename), 
    216 with a doubled initial value, and located in the usr/work/model/inputdata/ folder: 
     218a single tracer contained in the file named :file:`tracer_1_data.nc` 
     219(``.nc`` is implicitly assumed in namelist filename), 
     220with a doubled initial value, and located in the :file:`usr/work/model/inputdata` folder: 
    217221 
    218222.. code-block:: fortran 
    219223 
    220    !               !  file name             ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask ! 
    221    !               !                        !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      ! 
    222      sn_trcdta(1)  = 'tracer_1_data'        ,        -12        ,  'TRC1'   ,    .false.   , .true. , 'yearly'  , ''       , ''       , '' 
    223      rf_trfac(1) = 2.0 
    224      cn_dir = “usr/work/model/inputdata/” 
    225  
    226 Note that, the Lateral Open Boundaries conditions are applied on the segments defined for the physical core of NEMO 
    227 (see BDY description in the User Manual). 
    228  
    229 namelist_trc 
    230 ------------ 
    231  
    232 Here below the description of namelist_trc_ref used to handle Carbon tracers modules, namely CFC and C14. 
    233  
    234 |||| &'''namcfc'''     !   CFC || 
    235  
    236 |||| &'''namc14_typ'''     !  C14 - type of C14 tracer, default values of C14/C and pco2 || 
    237  
    238 |||| &'''namc14_sbc'''     !  C14 - surface BC || 
    239  
    240 |||| &'''namc14_fcg'''     !  files & dates || 
     224   !               !  file name             ! frequency (hours) ! variable  ! time interp. !  clim  ! 'yearly'/ ! weights  ! rotation ! land/sea mask ! 
     225   !               !                        !  (if <0  months)  !   name    !   (logical)  !  (T/F) ! 'monthly' ! filename ! pairing  ! filename      ! 
     226     sn_trcdta(1)  = 'tracer_1_data'        ,        -12        ,  'TRC1'   ,    .false.   , .true. , 'yearly'  , ''       , ''       , '' 
     227     rf_trfac(1) = 2.0 
     228     cn_dir = 'usr/work/model/inputdata/' 
     229 
     230Note that, the Lateral Open Boundaries conditions are applied on 
     231the segments defined for the physical core of NEMO 
     232(see ``BDY`` description in the :doc:`Reference Manual <citations>`). 
     233 
     234:file:`namelist_trc` 
     235-------------------- 
     236 
     237Here below the description of :file:`namelist_trc_ref` used to handle Carbon tracers modules, 
     238namely CFC and C14. 
     239 
     240.. literalinclude:: ../../../cfgs/SHARED/namelist_trc_ref 
     241   :language: fortran 
     242   :lines: 7,17,26,34 
     243   :caption: :file:`namelist_trc_ref` snippet 
    241244 
    242245``MY_TRC`` interface for coupling external BGC models 
    243246===================================================== 
    244247 
    245 The generalized interface is pivoted on MY_TRC module that contains template files to build the coupling between 
     248The generalized interface is pivoted on MY_TRC module that contains template files to 
     249build the coupling between 
    246250NEMO and any external BGC model. 
    247251 
    248 The call to MY_TRC is activated by setting ``ln_my_trc = .true.`` (in namtrc) 
     252The call to MY_TRC is activated by setting ``ln_my_trc = .true.`` (in ``&namtrc``) 
    249253 
    250254The following 6 fortran files are available in MY_TRC with the specific purposes here described. 
    251255 
    252 ``par_my_trc.F90`` 
    253    This module allows to define additional arrays and public variables to be used within the MY_TRC interface 
    254  
    255 ``trcini_my_trc.F90`` 
    256    Here are initialized user defined namelists and the call to the external BGC model initialization procedures to 
    257    populate general tracer array (trn and trb). Here are also likely to be defined suport arrays related to 
    258    system metrics that could be needed by the BGC model. 
    259  
    260 ``trcnam_my_trc.F90`` 
    261    This routine is called at the beginning of trcini_my_trc and should contain the initialization of 
    262    additional namelists for the BGC model or user-defined code. 
    263  
    264 ``trcsms_my_trc.F90`` 
    265    The routine performs the call to Boundary Conditions and its main purpose is to 
    266    contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model. 
    267    Be aware that lateral boundary conditions are applied in trcnxt routine. 
    268    IMPORTANT: the routines to compute the light penetration along the water column and 
    269    the tracer vertical sinking should be defined/called in here, as generalized modules are still missing in 
    270    the code. 
    271  
    272 ``trcice_my_trc.F90`` 
    273    Here it is possible to prescribe the tracers concentrations in the seaice that will be used as 
    274    boundary conditions when ice melting occurs (nn_ice_tr =1 in namtrc_ice). 
    275    See e.g. the correspondent PISCES subroutine. 
    276  
    277 ``trcwri_my_trc.F90`` 
    278    This routine performs the output of the model tracers (only those defined in namtrc) using IOM module 
    279    (see Manual Chapter “Output and Diagnostics”). 
    280    It is possible to place here the output of additional variables produced by the model, 
    281    if not done elsewhere in the code, using the call to iom_put. 
     256:file:`par_my_trc.F90` 
     257   This module allows to define additional arrays and public variables to 
     258   be used within the MY_TRC interface 
     259 
     260:file:`trcini_my_trc.F90` 
     261   Here are initialized user defined namelists and 
     262   the call to the external BGC model initialization procedures to populate general tracer array 
     263   (``trn`` and ``trb``). 
     264   Here are also likely to be defined support arrays related to system metrics that 
     265   could be needed by the BGC model. 
     266 
     267:file:`trcnam_my_trc.F90` 
     268   This routine is called at the beginning of ``trcini_my_trc`` and 
     269   should contain the initialization of additional namelists for the BGC model or user-defined code. 
     270 
     271:file:`trcsms_my_trc.F90` 
     272   The routine performs the call to Boundary Conditions and its main purpose is to 
     273   contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model. 
     274   Be aware that lateral boundary conditions are applied in trcnxt routine. 
     275 
     276   .. warning:: 
     277      The routines to compute the light penetration along the water column and 
     278      the tracer vertical sinking should be defined/called in here, 
     279      as generalized modules are still missing in the code. 
     280 
     281:file:`trcice_my_trc.F90` 
     282   Here it is possible to prescribe the tracers concentrations in the sea-ice that 
     283   will be used as boundary conditions when ice melting occurs (``nn_ice_tr = 1`` in ``&namtrc_ice``). 
     284   See e.g. the correspondent PISCES subroutine. 
     285 
     286:file:`trcwri_my_trc.F90` 
     287   This routine performs the output of the model tracers (only those defined in ``&namtrc``) using 
     288   IOM module (see chapter “Output and Diagnostics” in the :doc:`Reference Manual <citations>`). 
     289   It is possible to place here the output of additional variables produced by the model, 
     290   if not done elsewhere in the code, using the call to ``iom_put``. 
    282291 
    283292Coupling an external BGC model using NEMO framework 
     
    286295The coupling with an external BGC model through the NEMO compilation framework can be achieved in 
    287296different ways according to the degree of coding complexity of the Biogeochemical model, like e.g., 
    288 the whole code is made only by one file or it has multiple modules and interfaces spread across several subfolders. 
    289  
    290 Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named *MYBGC* and constituted by 
    291 a rather essential coding structure, likely few Fortran files. 
     297the whole code is made only by one file or 
     298it has multiple modules and interfaces spread across several subfolders. 
     299 
     300Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named *MYBGC* and 
     301constituted by a rather essential coding structure, likely few Fortran files. 
    292302The new coupled configuration name is *NEMO_MYBGC*. 
    293303 
    294 The best solution is to have all files (the modified ``MY_TRC`` routines and the BGC model ones) placed in 
    295 a unique folder with root ``MYBGCPATH`` and to use the makenemo external readdressing of ``MY_SRC`` folder. 
    296  
    297 The coupled configuration listed in ``work_cfgs.txt`` will look like 
     304The best solution is to have all files (the modified ``MY_TRC`` routines and the BGC model ones) 
     305placed in a unique folder with root ``MYBGCPATH`` and 
     306to use the makenemo external readdressing of ``MY_SRC`` folder. 
     307 
     308The coupled configuration listed in :file:`work_cfgs.txt` will look like 
    298309 
    299310:: 
    300311 
    301    NEMO_MYBGC OPA_SRC TOP_SRC 
     312   NEMO_MYBGC OCE TOP 
    302313 
    303314and the related ``cpp_MYBGC.fcm`` content will be 
     
    305316.. code-block:: perl 
    306317 
    307    bld::tool::fppkeys key_iomput key_mpp_mpi key_top 
    308  
    309 the compilation with ``makenemo`` will be executed through the following syntax 
     318   bld::tool::fppkeys key_iomput key_mpp_mpi key_top 
     319 
     320the compilation with :file:`makenemo` will be executed through the following syntax 
    310321 
    311322.. code-block:: console 
    312323 
    313    $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>' 
    314  
    315 The makenemo feature “-e” was introduced to readdress at compilation time the standard MY_SRC folder 
    316 (usually found in NEMO configurations) with a user defined external one. 
    317  
    318 The compilation of more articulated BGC model code & infrastructure, like in the case of BFM 
    319 ([http://www.bfm-community.eu/publications/bfmnemomanual_r1.0_201508.pdf BFM-NEMO coupling manual]), 
    320 requires some additional features. 
     324   $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>' 
     325 
     326The makenemo feature ``-e`` was introduced to 
     327readdress at compilation time the standard MY_SRC folder (usually found in NEMO configurations) with 
     328a user defined external one. 
     329 
     330The compilation of more articulated BGC model code & infrastructure, 
     331like in the case of BFM (|BFM man|_), requires some additional features. 
    321332 
    322333As before, let’s assume a coupled configuration name *NEMO_MYBGC*, 
    323 but in this case MYBGC model root becomes ``<MYBGCPATH>`` that contains 4 different subfolders for 
    324 biogeochemistry, named ``initialization``, ``pelagic``, and ``benthic``, and 
    325 a separate one named ``nemo_coupling`` including the modified ``MY_SRC`` routines. 
     334but in this case MYBGC model root becomes :file:`MYBGC` path that 
     335contains 4 different subfolders for biogeochemistry, 
     336named :file:`initialization`, :file:`pelagic`, and :file:`benthic`, 
     337and a separate one named :file:`nemo_coupling` including the modified `MY_SRC` routines. 
    326338The latter folder containing the modified NEMO coupling interface will be still linked using 
    327 the makenemo “-e” option. 
     339the makenemo ``-e`` option. 
    328340 
    329341In order to include the BGC model subfolders in the compilation of NEMO code, 
    330 it will be necessary to extend the configuration ``cpp_NEMO_MYBGC.fcm`` file to include the specific paths of 
    331 ``MYBGC`` folders, as in the following example 
     342it will be necessary to extend the configuration :file:`cpp_NEMO_MYBGC.fcm` file to include the specific paths of :file:`MYBGC` folders, as in the following example 
    332343 
    333344.. code-block:: perl 
    334345 
    335    bld::tool::fppkeys  key_iomput key_mpp_mpi key_top 
    336  
    337    src::MYBGC::initialization         <MYBGCPATH>/initialization 
    338    src::MYBGC::pelagic                <MYBGCPATH>/pelagic 
    339    src::MYBGC::benthic                <MYBGCPATH>/benthic 
    340  
    341    bld::pp::MYBGC      1 
    342    bld::tool::fppflags::MYBGC   %FPPFLAGS 
    343    bld::tool::fppkeys           %bld::tool::fppkeys MYBGC_MACROS 
     346   bld::tool::fppkeys  key_iomput key_mpp_mpi key_top 
     347 
     348   src::MYBGC::initialization         <MYBGCPATH>/initialization 
     349   src::MYBGC::pelagic                <MYBGCPATH>/pelagic 
     350   src::MYBGC::benthic                <MYBGCPATH>/benthic 
     351 
     352   bld::pp::MYBGC      1 
     353   bld::tool::fppflags::MYBGC   %FPPFLAGS 
     354   bld::tool::fppkeys           %bld::tool::fppkeys MYBGC_MACROS 
    344355 
    345356where *MYBGC_MACROS* is the space delimited list of macros used in *MYBGC* model for 
    346357selecting/excluding specific parts of the code. 
    347 The BGC model code will be preprocessed in the configuration ``BLD`` folder as for NEMO, 
    348 but with an independent path, like ``NEMO_MYBGC/BLD/MYBGC/<subforlders>``. 
     358The BGC model code will be preprocessed in the configuration :file:`BLD` folder as for NEMO, 
     359but with an independent path, like :file:`NEMO_MYBGC/BLD/MYBGC/<subforlders>`. 
    349360 
    350361The compilation will be performed similarly to in the previous case with the following 
     
    352363.. code-block:: console 
    353364 
    354    $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>/nemo_coupling' 
    355  
    356 Note that, the additional lines specific for the BGC model source and build paths can be written into 
    357 a separate file, e.g. named ``MYBGC.fcm``, and then simply included in the ``cpp_NEMO_MYBGC.fcm`` as follow 
    358  
    359 .. code-block:: perl 
    360  
    361    bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top 
    362    inc <MYBGCPATH>/MYBGC.fcm 
    363  
    364 This will enable a more portable compilation structure for all MYBGC related configurations. 
    365  
    366 **Important**: the coupling interface contained in nemo_coupling cannot be added using the FCM syntax, 
    367 as the same files already exists in NEMO and they are overridden only with the readdressing of MY_SRC contents to 
    368 avoid compilation conflicts due to duplicate routines. 
    369  
    370 All modifications illustrated above, can be easily implemented using shell or python scripting to 
    371 edit the NEMO configuration CPP.fcm file and to create the BGC model specific FCM compilation file with code paths. 
     365   $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>/nemo_coupling' 
     366 
     367.. note:: 
     368   The additional lines specific for the BGC model source and build paths can be written into 
     369   a separate file, e.g. named :file:`MYBGC.fcm`, 
     370   and then simply included in the :file:`cpp_NEMO_MYBGC.fcm` as follow 
     371 
     372   .. code-block:: perl 
     373 
     374      bld::tool::fppkeys  key_zdftke key_dynspg_ts key_iomput key_mpp_mpi key_top 
     375      inc <MYBGCPATH>/MYBGC.fcm 
     376 
     377   This will enable a more portable compilation structure for all MYBGC related configurations. 
     378 
     379.. warning:: 
     380   The coupling interface contained in :file:`nemo_coupling` cannot be added using the FCM syntax, 
     381   as the same files already exists in NEMO and they are overridden only with 
     382   the readdressing of MY_SRC contents to avoid compilation conflicts due to duplicate routines. 
     383 
     384All modifications illustrated above, can be easily implemented using shell or python scripting 
     385to edit the NEMO configuration :file:`CPP.fcm` file and 
     386to create the BGC model specific FCM compilation file with code paths. 
     387 
     388.. |BFM man| replace:: BFM-NEMO coupling manual 
Note: See TracChangeset for help on using the changeset viewer.