diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000000000000000000000000000000000000..1319cc1d1da8b9570d0e494be4b2fb5499b6fd9b
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,159 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml drafthtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " drafthtml to make an autoupdate HTML export while editing (todo list included)"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+drafthtml:
+ sphinx-autobuild -b html -t draft $(ALLSPHINXOPTS) $(BUILDDIR)/drafthtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/drafthtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/NEMO.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/NEMO.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/NEMO"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/NEMO"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e6a213f8728571f4fb31f0dbf4ca3285f455fbdd
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,56 @@
+**********************
+NEMO Quick Start Guide
+**********************
+
+| The NEMO guide is made up of several files written in
+ `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ (`.rst` extension),
+ a WYSIWYG markup language used in the Python community, and scattered all over the NEMO sources.
+| You can view them one by one in plain text from `./source` folder, or export all to a user-friendly guide under `./build` (only HTML format at the moment, PDF expected later).
+
+Build and export the guide in HTML
+==================================
+
+1. Install Sphinx documentation generator, its BibTeX extension and "Read The Docs" theme thanks to `pip` packages tool
+
+ .. code-block:: console
+
+ $ pip install sphinx sphinxcontrib.bibtex sphinx_rtd_theme
+
+2. Build the HTML export with `make` in `./build/html`
+
+ .. code-block:: console
+
+ $ make html
+
+3. Finally browse the guide by opening `./build/html/NEMO_guide.html`
+
+
+Edit the sources and check the output in real time
+==================================================
+
+| To facilitate the update of the guide, editors can install a useful package that will automatically trigger a new build and the reload of the HTML page for every recorded change in the sources.
+| So the reviewer saves time by controlling on-line their modifications almost as it types and also by avoiding repeated interactive rebuilds.
+
+Install `sphinx-autobuild` package
+
+.. code-block:: console
+
+ $ pip install sphinx-autobuild
+
+Launch a local web server hosting a draft export of the guide (build this time in `./build/livehtml`)
+
+.. code-block:: console
+
+ $ make livehtml
+
+| Open in the same time the 2 formats of the content to review: the source file and the web page by browsing from the new guide hosted by your local server on `<http://127.0.0.1:8000/NEMO_guide.html>`_.
+| Start the update, save your changes and verify instantly the HTML export in your browser.
+
+.. warning::
+
+ | Your modifications are not taken into account?
+ | For symlink file, you will have to close it to update the HTML export. Otherwise look at the log of the Sphinx build, you probably made a typo!
+
+.. hint::
+
+ Are there broken links? Fix "Page not found" errors by running `make linkcheck`
diff --git a/source/_static/AGRIF_DEMO.jpg b/source/_static/AGRIF_DEMO.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..09d53e0f5af4db01a6b09caab26ba46c5dc8201a
Binary files /dev/null and b/source/_static/AGRIF_DEMO.jpg differ
diff --git a/source/_static/AGRIF_DEMO_no_cap.jpg b/source/_static/AGRIF_DEMO_no_cap.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..1950511d3881f964bf1b3a48c521fa60b160df1d
Binary files /dev/null and b/source/_static/AGRIF_DEMO_no_cap.jpg differ
diff --git a/source/_static/AMM_domain.png b/source/_static/AMM_domain.png
new file mode 100644
index 0000000000000000000000000000000000000000..d33400f62d3e0ec105f4e7b972bf06e494c32f3c
Binary files /dev/null and b/source/_static/AMM_domain.png differ
diff --git a/source/_static/ICE_AGRIF_UDIAG_43days_UM5.gif b/source/_static/ICE_AGRIF_UDIAG_43days_UM5.gif
new file mode 100644
index 0000000000000000000000000000000000000000..12e54644ec95e26fe94b148468b9f02066c1c608
Binary files /dev/null and b/source/_static/ICE_AGRIF_UDIAG_43days_UM5.gif differ
diff --git a/source/_static/ISOMIP_moc.png b/source/_static/ISOMIP_moc.png
new file mode 100644
index 0000000000000000000000000000000000000000..48282ae34893d4e305166dedfb5dfc61e7597140
Binary files /dev/null and b/source/_static/ISOMIP_moc.png differ
diff --git a/source/_static/LOCK-FCT4_flux_ubs.gif b/source/_static/LOCK-FCT4_flux_ubs.gif
new file mode 100644
index 0000000000000000000000000000000000000000..b6475b8465354a803dc2009c84a80320409dca76
Binary files /dev/null and b/source/_static/LOCK-FCT4_flux_ubs.gif differ
diff --git a/source/_static/NEMO_grey.png b/source/_static/NEMO_grey.png
new file mode 100644
index 0000000000000000000000000000000000000000..80256ab145a2563163240fcccf599c7e1f2f1e54
Binary files /dev/null and b/source/_static/NEMO_grey.png differ
diff --git a/source/_static/ORCA.ico b/source/_static/ORCA.ico
new file mode 100644
index 0000000000000000000000000000000000000000..e7049e4b2b7a1c85295e88000dcb4df0acbb796d
Binary files /dev/null and b/source/_static/ORCA.ico differ
diff --git a/source/_static/OVF-sco_FCT4_flux_cen-ahm1000.gif b/source/_static/OVF-sco_FCT4_flux_cen-ahm1000.gif
new file mode 100644
index 0000000000000000000000000000000000000000..929066c5addc2535f52fdf5984fde0f6094cea39
Binary files /dev/null and b/source/_static/OVF-sco_FCT4_flux_cen-ahm1000.gif differ
diff --git a/source/_static/Papa2015.jpg b/source/_static/Papa2015.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..2e6035c207a38f8f4ba9f46b56ea625220b151e0
Binary files /dev/null and b/source/_static/Papa2015.jpg differ
diff --git a/source/_static/VORTEX_anim.gif b/source/_static/VORTEX_anim.gif
new file mode 100644
index 0000000000000000000000000000000000000000..2133742947bb00cf69042f86dd3491df6229951c
Binary files /dev/null and b/source/_static/VORTEX_anim.gif differ
diff --git a/source/_static/agrif_grid_position.jpg b/source/_static/agrif_grid_position.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..5faf00ef43980ef1f9898c376e87630757a38142
Binary files /dev/null and b/source/_static/agrif_grid_position.jpg differ
diff --git a/source/_static/crs_wiki_1.1.pdf b/source/_static/crs_wiki_1.1.pdf
new file mode 100644
index 0000000000000000000000000000000000000000..fea68a43d4ba709bd059991eb4b5e282961a4e1f
Binary files /dev/null and b/source/_static/crs_wiki_1.1.pdf differ
diff --git a/source/_static/file_crs_def.xml b/source/_static/file_crs_def.xml
new file mode 100644
index 0000000000000000000000000000000000000000..d1b164c12ed55195916bc8ed6459ba53131b67c3
--- /dev/null
+++ b/source/_static/file_crs_def.xml
@@ -0,0 +1,80 @@
+ <!--
+============================================================================================================
+= output files definition =
+= Define your own files =
+= put the variables you want... =
+============================================================================================================
+ -->
+ <file_definition type="multiple_file" name="PATH_OUT/@expname@_@freq@" sync_freq="1d" min_digits="4">
+
+ <file_group id="1d" output_freq="1d" split_freq="1d" output_level="10" enabled=".TRUE."> <!-- 1d files -->
+
+ <file id="file1" name_suffix="_gcrsT" description="ocean T grid variables" >
+ <field field_ref="e3t" name="e3t" />
+ <field field_ref="toce" name="votemper" operation="instant" freq_op="1d" > @toce_e3t / @e3t </field>
+ <field field_ref="soce" name="vosaline" operation="instant" freq_op="1d" > @soce_e3t / @e3t </field>
+ <field field_ref="mldkz5" name="somixhgt" />
+ </file>
+
+ <file id="file2" name_suffix="_gcrsU" description="ocean T grid variables" >
+ <field field_ref="e3u" name="e3u" />
+ <field field_ref="uoce" name="uo" operation="instant" freq_op="1d" > @uoce_e3u / @e3u </field>
+ </file>
+
+ <file id="file3" name_suffix="_gcrsV" description="ocean T grid variables" >
+ <field field_ref="e3v" name="e3v" />
+ <field field_ref="voce" name="vo" operation="instant" freq_op="1d" > @voce_e3v / @e3v </field>
+ </file>
+
+ <file id="file4" name_suffix="_gcrsW" description="ocean T grid variables" >
+ <field field_ref="woce" name="woce" />
+ <field field_ref="avt" name="difvho" />
+ </file>
+
+ <file id="file5" name_suffix="_gcrsC" description="ocean T grid variables" >
+ <field field_ref="Alkalini" operation="instant" freq_op="1d" > @Alkalini_E3T / @e3t </field>
+ <field field_ref="O2" operation="instant" freq_op="1d" > @O2_E3T / @e3t </field>
+ <field field_ref="Si" operation="instant" freq_op="1d" > @Si_E3T / @e3t </field>
+ <field field_ref="PHY" operation="instant" freq_op="1d" > @PHY_E3T / @e3t </field>
+ <field field_ref="ZOO" operation="instant" freq_op="1d" > @ZOO_E3T / @e3t </field>
+ <field field_ref="DOC" operation="instant" freq_op="1d" > @DOC_E3T / @e3t </field>
+ <field field_ref="NCHL" operation="instant" freq_op="1d" > @NCHL_E3T / @e3t </field>
+ <field field_ref="DCHL" operation="instant" freq_op="1d" > @DCHL_E3T / @e3t </field>
+ <field field_ref="NO3" operation="instant" freq_op="1d" > @NO3_E3T / @e3t </field>
+ </file>
+
+ </file_group>
+
+ <file_group id="1mo" output_freq="1mo" split_freq="1mo" output_level="10" enabled=".TRUE."> <!-- 1d files -->
+
+ <file id="file6" name_suffix="_gcrsC" description="ocean T grid variables" >
+ <field field_ref="DIC" operation="instant" freq_op="1mo" > @DIC_E3T / @e3t </field>
+ <field field_ref="Alkalini" operation="instant" freq_op="1mo" > @Alkalini_E3T / @e3t </field>
+ <field field_ref="O2" operation="instant" freq_op="1mo" > @O2_E3T / @e3t </field>
+ <field field_ref="CaCO3" operation="instant" freq_op="1mo" > @CaCO3_E3T / @e3t </field>
+ <field field_ref="PO4" operation="instant" freq_op="1mo" > @PO4_E3T / @e3t </field>
+ <field field_ref="POC" operation="instant" freq_op="1mo" > @POC_E3T / @e3t </field>
+ <field field_ref="Si" operation="instant" freq_op="1mo" > @Si_E3T / @e3t </field>
+ <field field_ref="PHY" operation="instant" freq_op="1mo" > @PHY_E3T / @e3t </field>
+ <field field_ref="ZOO" operation="instant" freq_op="1mo" > @ZOO_E3T / @e3t </field>
+ <field field_ref="DOC" operation="instant" freq_op="1mo" > @DOC_E3T / @e3t </field>
+ <field field_ref="PHY2" operation="instant" freq_op="1mo" > @PHY2_E3T / @e3t </field>
+ <field field_ref="ZOO2" operation="instant" freq_op="1mo" > @ZOO2_E3T / @e3t </field>
+ <field field_ref="DSi" operation="instant" freq_op="1mo" > @DSi_E3T / @e3t </field>
+ <field field_ref="Fer" operation="instant" freq_op="1mo" > @Fer_E3T / @e3t </field>
+ <field field_ref="BFe" operation="instant" freq_op="1mo" > @BFe_E3T / @e3t </field>
+ <field field_ref="GOC" operation="instant" freq_op="1mo" > @GOC_E3T / @e3t </field>
+ <field field_ref="SFe" operation="instant" freq_op="1mo" > @SFe_E3T / @e3t </field>
+ <field field_ref="DFe" operation="instant" freq_op="1mo" > @DFe_E3T / @e3t </field>
+ <field field_ref="GSi" operation="instant" freq_op="1mo" > @GSi_E3T / @e3t </field>
+ <field field_ref="NFe" operation="instant" freq_op="1mo" > @NFe_E3T / @e3t </field>
+ <field field_ref="NCHL" operation="instant" freq_op="1mo" > @NCHL_E3T / @e3t </field>
+ <field field_ref="DCHL" operation="instant" freq_op="1mo" > @DCHL_E3T / @e3t </field>
+ <field field_ref="NO3" operation="instant" freq_op="1mo" > @NO3_E3T / @e3t </field>
+ <field field_ref="NH4" operation="instant" freq_op="1mo" > @NH4_E3T / @e3t </field>
+ </file>
+
+ </file_group>
+
+
+ </file_definition>
diff --git a/source/_static/file_def.xml b/source/_static/file_def.xml
new file mode 100644
index 0000000000000000000000000000000000000000..79853c7d5322175d81d33f102e09de806cd85a02
--- /dev/null
+++ b/source/_static/file_def.xml
@@ -0,0 +1,111 @@
+ <!--
+============================================================================================================
+= output files definition =
+= Define your own files default value="9.96921e+36" =
+= put the variables you want... =
+============================================================================================================
+ -->
+
+ <file_definition type="multiple_file" name="PATH_OUT/@expname@_@freq@" sync_freq="1d" min_digits="4" >
+
+
+ <file_group id="1d" output_freq="1d" split_freq="1d" output_level="10" enabled=".TRUE." > <!-- 5d files -->
+
+ <file id="file1" name_suffix="_gridT" description="ocean T grid variables" >
+ <field field_ref="e3t" name="e3t" />
+ <field field_ref="toce" name="votemper" operation="instant" freq_op="1d" > @toce_e3t / @e3t </field>
+ </file>
+
+ <file id="file2" name_suffix="_gridS" description="ocean T grid variables" >
+ <field field_ref="soce" name="vosaline" operation="instant" freq_op="1d" > @soce_e3t / @e3t </field>
+ </file>
+
+ <file id="file3" name_suffix="_grid2D" description="ocean T grid variables" >
+ <field field_ref="mldkz5" name="somixhgt" />
+ <field field_ref="empmr" name="sowaflup" />
+ <field field_ref="empbmr" name="sowaflupb" />
+ <field field_ref="fmmflx" name="iowaflup" />
+ <field field_ref="ice_cover" name="soicecov" />
+ <field field_ref="qsr" name="soceshwf" />
+ <field field_ref="taum" name="sowindsp" />
+ <field field_ref="runoffs" name="runoffs" />
+ </file>
+
+ <file id="file4" name_suffix="_gridU" description="ocean U grid variables" >
+ <field field_ref="e3u" name="e3u" />
+ <field field_ref="uocetr_eff" name="uocetr_eff" />
+ <field field_ref="utau" name="tauuo" />
+ </file>
+
+ <file id="file5" name_suffix="_gridV" description="ocean V grid variables" >
+ <field field_ref="e3v" name="e3v" />
+ <field field_ref="vocetr_eff" name="vocetr_eff" />
+ <field field_ref="vtau" name="tauvo" />
+ </file>
+
+ <file id="file6" name_suffix="_gridW" description="ocean W grid variables" >
+ <field field_ref="e3w" name="e3w" />
+ <field field_ref="wocetr_eff" name="wocetr_eff" />
+ </file>
+
+ <file id="file7" name_suffix="_gridKZ" description="ocean W grid variables" >
+ <field field_ref="avt" name="voddmavs" />
+ </file>
+
+ <file id="file8" name_suffix="_gridH" description="ocean W grid variables" >
+ <field field_ref="hdiv" name="hdivtr" long_name="horizontal divergence transport" operation="average" freq_op="1d" > @hdiv * @e3t </field>
+ </file>
+
+ </file_group>
+
+ <file_group id="1mo" output_freq="1mo" split_freq="1mo" output_level="10" enabled=".TRUE." > <!-- 5d files -->
+
+ <file id="file10" name_suffix="_gridT" description="ocean T grid variables" >
+ <field field_ref="e3t" name="e3t" />
+ <field field_ref="toce" name="votemper" operation="instant" freq_op="1d" > @toce_e3t / @e3t </field>
+ </file>
+
+ <file id="file11" name_suffix="_gridS" description="ocean T grid variables" >
+ <field field_ref="soce" name="vosaline" operation="instant" freq_op="1d" > @soce_e3t / @e3t </field>
+ </file>
+
+ <file id="file12" name_suffix="_grid2D" description="ocean T grid variables" >
+ <field field_ref="mldkz5" name="somixhgt" />
+ <field field_ref="empmr" name="sowaflup" />
+ <field field_ref="empbmr" name="sowaflupb" />
+ <field field_ref="fmmflx" name="iowaflup" />
+ <field field_ref="ice_cover" name="soicecov" />
+ <field field_ref="qsr" name="soceshwf" />
+ <field field_ref="taum" name="sowindsp" />
+ <field field_ref="runoffs" name="runoffs" />
+ </file>
+
+ <file id="file13" name_suffix="_gridU" description="ocean U grid variables" >
+ <field field_ref="e3u" name="e3u" />
+ <field field_ref="uocetr_eff" name="uocetr_eff" />
+ <field field_ref="utau" name="tauuo" />
+ </file>
+
+ <file id="file14" name_suffix="_gridV" description="ocean V grid variables" >
+ <field field_ref="e3v" name="e3v" />
+ <field field_ref="vocetr_eff" name="vocetr_eff" />
+ <field field_ref="vtau" name="tauvo" />
+ </file>
+
+ <file id="file15" name_suffix="_gridW" description="ocean W grid variables" >
+ <field field_ref="e3w" name="e3w" />
+ <field field_ref="wocetr_eff" name="wocetr_eff" />
+ </file>
+
+ <file id="file16" name_suffix="_gridKZ" description="ocean W grid variables" >
+ <field field_ref="avt" name="voddmavs" />
+ </file>
+
+ <file id="file17" name_suffix="_gridH" description="ocean W grid variables" >
+ <field field_ref="hdiv" name="hdivtr" long_name="horizontal divergence transport" operation="average" freq_op="1d" > @hdiv * @e3t </field>
+ </file>
+
+
+ </file_group>
+
+ </file_definition>
diff --git a/source/_static/frames/VORTEX_anim-00.png b/source/_static/frames/VORTEX_anim-00.png
new file mode 100644
index 0000000000000000000000000000000000000000..2364fcdac113e9fc7f9393d1ac987efdf630ba21
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-00.png differ
diff --git a/source/_static/frames/VORTEX_anim-01.png b/source/_static/frames/VORTEX_anim-01.png
new file mode 100644
index 0000000000000000000000000000000000000000..e0504e713da0f900fbaf5b2091b64cdbcb780311
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-01.png differ
diff --git a/source/_static/frames/VORTEX_anim-02.png b/source/_static/frames/VORTEX_anim-02.png
new file mode 100644
index 0000000000000000000000000000000000000000..ee7ae393716cb85b14ee9a4aa38a2067363e250d
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-02.png differ
diff --git a/source/_static/frames/VORTEX_anim-03.png b/source/_static/frames/VORTEX_anim-03.png
new file mode 100644
index 0000000000000000000000000000000000000000..93b175ecc6d29f1594492411a2c5953df49b327d
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-03.png differ
diff --git a/source/_static/frames/VORTEX_anim-04.png b/source/_static/frames/VORTEX_anim-04.png
new file mode 100644
index 0000000000000000000000000000000000000000..1d1e5a5200f1fb5b0a668d99313df77b46423168
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-04.png differ
diff --git a/source/_static/frames/VORTEX_anim-05.png b/source/_static/frames/VORTEX_anim-05.png
new file mode 100644
index 0000000000000000000000000000000000000000..a8a15fde99816a68fd8c98c15b49e36bb1ff4cfa
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-05.png differ
diff --git a/source/_static/frames/VORTEX_anim-06.png b/source/_static/frames/VORTEX_anim-06.png
new file mode 100644
index 0000000000000000000000000000000000000000..06367425ee55adee6fb8b1b40beea4804c777bd1
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-06.png differ
diff --git a/source/_static/frames/VORTEX_anim-07.png b/source/_static/frames/VORTEX_anim-07.png
new file mode 100644
index 0000000000000000000000000000000000000000..870186e70af46163e4be3fe6b31ca00a30244a88
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-07.png differ
diff --git a/source/_static/frames/VORTEX_anim-08.png b/source/_static/frames/VORTEX_anim-08.png
new file mode 100644
index 0000000000000000000000000000000000000000..20d0feb684e01bfc59097ad036b7be8b59c208e8
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-08.png differ
diff --git a/source/_static/frames/VORTEX_anim-09.png b/source/_static/frames/VORTEX_anim-09.png
new file mode 100644
index 0000000000000000000000000000000000000000..0e1792eeb62dfedd80b4f5f6c192d82fa3e27ddb
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-09.png differ
diff --git a/source/_static/frames/VORTEX_anim-10.png b/source/_static/frames/VORTEX_anim-10.png
new file mode 100644
index 0000000000000000000000000000000000000000..cedf9c21ec0a73cc00d02fac5ffbdb39e2a5769e
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-10.png differ
diff --git a/source/_static/frames/VORTEX_anim-11.png b/source/_static/frames/VORTEX_anim-11.png
new file mode 100644
index 0000000000000000000000000000000000000000..2ca801d2eddf9b8096adc406095fce7bc4660112
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-11.png differ
diff --git a/source/_static/frames/VORTEX_anim-12.png b/source/_static/frames/VORTEX_anim-12.png
new file mode 100644
index 0000000000000000000000000000000000000000..9fa29ca51353af7bab8fba203fde90841f18cf02
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-12.png differ
diff --git a/source/_static/frames/VORTEX_anim-13.png b/source/_static/frames/VORTEX_anim-13.png
new file mode 100644
index 0000000000000000000000000000000000000000..1bde81e9352df94b1c5983a353e0a85692802591
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-13.png differ
diff --git a/source/_static/frames/VORTEX_anim-14.png b/source/_static/frames/VORTEX_anim-14.png
new file mode 100644
index 0000000000000000000000000000000000000000..c655808e3d6dc0674481e29f2a8b7c46f38086a7
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-14.png differ
diff --git a/source/_static/frames/VORTEX_anim-15.png b/source/_static/frames/VORTEX_anim-15.png
new file mode 100644
index 0000000000000000000000000000000000000000..e8dc7d0310e39b2ea18fa06558c5d6c440e01b2e
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-15.png differ
diff --git a/source/_static/frames/VORTEX_anim-16.png b/source/_static/frames/VORTEX_anim-16.png
new file mode 100644
index 0000000000000000000000000000000000000000..a4e8af317d79c3200a36199f976e259e67959487
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-16.png differ
diff --git a/source/_static/frames/VORTEX_anim-17.png b/source/_static/frames/VORTEX_anim-17.png
new file mode 100644
index 0000000000000000000000000000000000000000..7f64667d7f21cb2e15d7e68d66baee64cda01121
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-17.png differ
diff --git a/source/_static/frames/VORTEX_anim-18.png b/source/_static/frames/VORTEX_anim-18.png
new file mode 100644
index 0000000000000000000000000000000000000000..154d64e0faec6a535e4bac1958d9c8aef8eb476e
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-18.png differ
diff --git a/source/_static/frames/VORTEX_anim-19.png b/source/_static/frames/VORTEX_anim-19.png
new file mode 100644
index 0000000000000000000000000000000000000000..725a4dac3c0df9b5066f61f773ecfee5bd22c794
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-19.png differ
diff --git a/source/_static/frames/VORTEX_anim-20.png b/source/_static/frames/VORTEX_anim-20.png
new file mode 100644
index 0000000000000000000000000000000000000000..5722dc20fcdd28b62c9d1284d3e9855dc3a79c04
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-20.png differ
diff --git a/source/_static/frames/VORTEX_anim-21.png b/source/_static/frames/VORTEX_anim-21.png
new file mode 100644
index 0000000000000000000000000000000000000000..fb1f3e9bc2eb7a13842f721fc1855b094f276599
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-21.png differ
diff --git a/source/_static/frames/VORTEX_anim-22.png b/source/_static/frames/VORTEX_anim-22.png
new file mode 100644
index 0000000000000000000000000000000000000000..3cad65b4153b53c730dd833cbdb9d48f04a72c95
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-22.png differ
diff --git a/source/_static/frames/VORTEX_anim-23.png b/source/_static/frames/VORTEX_anim-23.png
new file mode 100644
index 0000000000000000000000000000000000000000..937707e2bc40baed2a3f8749a93f3aaeeb3becc7
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-23.png differ
diff --git a/source/_static/frames/VORTEX_anim-24.png b/source/_static/frames/VORTEX_anim-24.png
new file mode 100644
index 0000000000000000000000000000000000000000..d9e4495304a43d0ba7cb47a08903e615e1452daa
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-24.png differ
diff --git a/source/_static/frames/VORTEX_anim-25.png b/source/_static/frames/VORTEX_anim-25.png
new file mode 100644
index 0000000000000000000000000000000000000000..61ac5733c4cd369129b513e52db41350aba113b6
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-25.png differ
diff --git a/source/_static/frames/VORTEX_anim-26.png b/source/_static/frames/VORTEX_anim-26.png
new file mode 100644
index 0000000000000000000000000000000000000000..0cdaf5ab704a450c1bd2c5c535b73c2f6021d25a
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-26.png differ
diff --git a/source/_static/frames/VORTEX_anim-27.png b/source/_static/frames/VORTEX_anim-27.png
new file mode 100644
index 0000000000000000000000000000000000000000..3dbf082e11b2a17474569ae4110a103bed77a8b4
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-27.png differ
diff --git a/source/_static/frames/VORTEX_anim-28.png b/source/_static/frames/VORTEX_anim-28.png
new file mode 100644
index 0000000000000000000000000000000000000000..54aeaf48ecd0bf231ab5d05f6b231e8d8173b3bf
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-28.png differ
diff --git a/source/_static/frames/VORTEX_anim-29.png b/source/_static/frames/VORTEX_anim-29.png
new file mode 100644
index 0000000000000000000000000000000000000000..55d699594129abed16ce11b7868a856e7d79ab23
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-29.png differ
diff --git a/source/_static/frames/VORTEX_anim-30.png b/source/_static/frames/VORTEX_anim-30.png
new file mode 100644
index 0000000000000000000000000000000000000000..0dbff6b64697c35837a2f0b328056307c6e3d083
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-30.png differ
diff --git a/source/_static/frames/VORTEX_anim-31.png b/source/_static/frames/VORTEX_anim-31.png
new file mode 100644
index 0000000000000000000000000000000000000000..607990df40189c7e6a3e15c9a0315404f3721b6e
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-31.png differ
diff --git a/source/_static/frames/VORTEX_anim-32.png b/source/_static/frames/VORTEX_anim-32.png
new file mode 100644
index 0000000000000000000000000000000000000000..3d5d7dfe8f1cf04fec4ad3e393457a3f31b5a024
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-32.png differ
diff --git a/source/_static/frames/VORTEX_anim-33.png b/source/_static/frames/VORTEX_anim-33.png
new file mode 100644
index 0000000000000000000000000000000000000000..ef2f4646f0c5ed5391bc06c4f06864fa67654641
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-33.png differ
diff --git a/source/_static/frames/VORTEX_anim-34.png b/source/_static/frames/VORTEX_anim-34.png
new file mode 100644
index 0000000000000000000000000000000000000000..0b4dfb8ac5c590e402e762ac15d3c084ff359465
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-34.png differ
diff --git a/source/_static/frames/VORTEX_anim-35.png b/source/_static/frames/VORTEX_anim-35.png
new file mode 100644
index 0000000000000000000000000000000000000000..1c79402cb1dbe9ebf7c8b03e825d5c5a400424b7
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-35.png differ
diff --git a/source/_static/frames/VORTEX_anim-36.png b/source/_static/frames/VORTEX_anim-36.png
new file mode 100644
index 0000000000000000000000000000000000000000..7721743e64e86b72285063dd69e652d0421ac8c3
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-36.png differ
diff --git a/source/_static/frames/VORTEX_anim-37.png b/source/_static/frames/VORTEX_anim-37.png
new file mode 100644
index 0000000000000000000000000000000000000000..557afc1ceacc2b6e4cb50880ab54c5bb14b2bdc7
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-37.png differ
diff --git a/source/_static/frames/VORTEX_anim-38.png b/source/_static/frames/VORTEX_anim-38.png
new file mode 100644
index 0000000000000000000000000000000000000000..0fa4287dc9c2e7c4b3c6abcf8ac146e1f8d61a6e
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-38.png differ
diff --git a/source/_static/frames/VORTEX_anim-39.png b/source/_static/frames/VORTEX_anim-39.png
new file mode 100644
index 0000000000000000000000000000000000000000..fe1d65da4482f5cb3dbb5380d2431eec42e1fe16
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-39.png differ
diff --git a/source/_static/frames/VORTEX_anim-40.png b/source/_static/frames/VORTEX_anim-40.png
new file mode 100644
index 0000000000000000000000000000000000000000..0eefb3d285ba6d0c25f5090fc92799a7ecc9ab8a
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-40.png differ
diff --git a/source/_static/frames/VORTEX_anim-41.png b/source/_static/frames/VORTEX_anim-41.png
new file mode 100644
index 0000000000000000000000000000000000000000..dee0d07b83514b3510da2d13e0af42b8541f47c6
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-41.png differ
diff --git a/source/_static/frames/VORTEX_anim-42.png b/source/_static/frames/VORTEX_anim-42.png
new file mode 100644
index 0000000000000000000000000000000000000000..c0e1d7d62ff8361f5458d12086112c41ad532dfc
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-42.png differ
diff --git a/source/_static/frames/VORTEX_anim-43.png b/source/_static/frames/VORTEX_anim-43.png
new file mode 100644
index 0000000000000000000000000000000000000000..e12688da8ce0b0bae958e13398f8d1c470cc3f3a
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-43.png differ
diff --git a/source/_static/frames/VORTEX_anim-44.png b/source/_static/frames/VORTEX_anim-44.png
new file mode 100644
index 0000000000000000000000000000000000000000..4efdebfc5a28fea1fb1f26a83e66c2889e23ca7c
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-44.png differ
diff --git a/source/_static/frames/VORTEX_anim-45.png b/source/_static/frames/VORTEX_anim-45.png
new file mode 100644
index 0000000000000000000000000000000000000000..203a27363d25e42b5d81613dd801b0fd1d738b14
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-45.png differ
diff --git a/source/_static/frames/VORTEX_anim-46.png b/source/_static/frames/VORTEX_anim-46.png
new file mode 100644
index 0000000000000000000000000000000000000000..c6d17faa6e5f708c6c21f0a26ed02c26603d32e9
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-46.png differ
diff --git a/source/_static/frames/VORTEX_anim-47.png b/source/_static/frames/VORTEX_anim-47.png
new file mode 100644
index 0000000000000000000000000000000000000000..6c35db795dfb90d163ede4fd8a8a0023699d4895
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-47.png differ
diff --git a/source/_static/frames/VORTEX_anim-48.png b/source/_static/frames/VORTEX_anim-48.png
new file mode 100644
index 0000000000000000000000000000000000000000..a0734873a0cd27d1688bde2e724dc94f440f326a
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-48.png differ
diff --git a/source/_static/frames/VORTEX_anim-49.png b/source/_static/frames/VORTEX_anim-49.png
new file mode 100644
index 0000000000000000000000000000000000000000..9d34bd763f160f35d48f1867139027d72d66271d
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-49.png differ
diff --git a/source/_static/frames/VORTEX_anim-50.png b/source/_static/frames/VORTEX_anim-50.png
new file mode 100644
index 0000000000000000000000000000000000000000..d7a446a072771584375b397d13fb6c1dc7f41173
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-50.png differ
diff --git a/source/_static/frames/VORTEX_anim-51.png b/source/_static/frames/VORTEX_anim-51.png
new file mode 100644
index 0000000000000000000000000000000000000000..b9b2314744d74a3c975b2d185055868249b36787
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-51.png differ
diff --git a/source/_static/frames/VORTEX_anim-52.png b/source/_static/frames/VORTEX_anim-52.png
new file mode 100644
index 0000000000000000000000000000000000000000..39be2c9d408a465d3f6a9180f8e9215e61541cf3
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-52.png differ
diff --git a/source/_static/frames/VORTEX_anim-53.png b/source/_static/frames/VORTEX_anim-53.png
new file mode 100644
index 0000000000000000000000000000000000000000..74713c20292e0a7d43300ac2e0e947e11384d51f
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-53.png differ
diff --git a/source/_static/frames/VORTEX_anim-54.png b/source/_static/frames/VORTEX_anim-54.png
new file mode 100644
index 0000000000000000000000000000000000000000..5e94ac7a5913aee8f9dac8f433e349ebe8bf1a10
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-54.png differ
diff --git a/source/_static/frames/VORTEX_anim-55.png b/source/_static/frames/VORTEX_anim-55.png
new file mode 100644
index 0000000000000000000000000000000000000000..c86cc86303a303e33c8275dfd5e2dd3dcc3a863e
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-55.png differ
diff --git a/source/_static/frames/VORTEX_anim-56.png b/source/_static/frames/VORTEX_anim-56.png
new file mode 100644
index 0000000000000000000000000000000000000000..abee6b30d44d45e99d1e301edec037d2f10a900e
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-56.png differ
diff --git a/source/_static/frames/VORTEX_anim-57.png b/source/_static/frames/VORTEX_anim-57.png
new file mode 100644
index 0000000000000000000000000000000000000000..f3be90fa652b672b236bd31e896e6c479b040c18
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-57.png differ
diff --git a/source/_static/frames/VORTEX_anim-58.png b/source/_static/frames/VORTEX_anim-58.png
new file mode 100644
index 0000000000000000000000000000000000000000..44e517e8cfd307901ea91826e1216e8ba21e67f6
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-58.png differ
diff --git a/source/_static/frames/VORTEX_anim-59.png b/source/_static/frames/VORTEX_anim-59.png
new file mode 100644
index 0000000000000000000000000000000000000000..f19510a8b50c4d9e8b027130d446d7c6dc871c17
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-59.png differ
diff --git a/source/_static/frames/VORTEX_anim-60.png b/source/_static/frames/VORTEX_anim-60.png
new file mode 100644
index 0000000000000000000000000000000000000000..0aa06561d502843d71cbbab91560bffa6ec072d3
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-60.png differ
diff --git a/source/_static/frames/VORTEX_anim-61.png b/source/_static/frames/VORTEX_anim-61.png
new file mode 100644
index 0000000000000000000000000000000000000000..de9c4a8187a944caa6d6a97a015ea56378029e0b
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-61.png differ
diff --git a/source/_static/frames/VORTEX_anim-62.png b/source/_static/frames/VORTEX_anim-62.png
new file mode 100644
index 0000000000000000000000000000000000000000..424527b16f3108a295a179b4bbfe3c935e0cc31b
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-62.png differ
diff --git a/source/_static/frames/VORTEX_anim-63.png b/source/_static/frames/VORTEX_anim-63.png
new file mode 100644
index 0000000000000000000000000000000000000000..d44917ba243dc41b05def369db60169e87157ca9
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-63.png differ
diff --git a/source/_static/frames/VORTEX_anim-64.png b/source/_static/frames/VORTEX_anim-64.png
new file mode 100644
index 0000000000000000000000000000000000000000..e2075bae3498af5fce98fc95bf745c74d4186063
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-64.png differ
diff --git a/source/_static/frames/VORTEX_anim-65.png b/source/_static/frames/VORTEX_anim-65.png
new file mode 100644
index 0000000000000000000000000000000000000000..00a2765b30d5ea5355e5a0b6b284465a2d662511
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-65.png differ
diff --git a/source/_static/frames/VORTEX_anim-66.png b/source/_static/frames/VORTEX_anim-66.png
new file mode 100644
index 0000000000000000000000000000000000000000..c9047e2545a62d0c296522250e7b3f7d9a6e8f23
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-66.png differ
diff --git a/source/_static/frames/VORTEX_anim-67.png b/source/_static/frames/VORTEX_anim-67.png
new file mode 100644
index 0000000000000000000000000000000000000000..4c8562c26741daeb2d9bf2ebf691ea1b6d224c0e
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-67.png differ
diff --git a/source/_static/frames/VORTEX_anim-68.png b/source/_static/frames/VORTEX_anim-68.png
new file mode 100644
index 0000000000000000000000000000000000000000..61c08c10d9e7ea3d150c36491486793b113b0492
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-68.png differ
diff --git a/source/_static/frames/VORTEX_anim-69.png b/source/_static/frames/VORTEX_anim-69.png
new file mode 100644
index 0000000000000000000000000000000000000000..19cf33fd7988dae00cf5eb936d21a51b4141ed53
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-69.png differ
diff --git a/source/_static/frames/VORTEX_anim-70.png b/source/_static/frames/VORTEX_anim-70.png
new file mode 100644
index 0000000000000000000000000000000000000000..2968282e46dd64068da49b99f59734e752969d80
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-70.png differ
diff --git a/source/_static/frames/VORTEX_anim-71.png b/source/_static/frames/VORTEX_anim-71.png
new file mode 100644
index 0000000000000000000000000000000000000000..0c88d5676853ee57b869450d1a4c69f7477776f3
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-71.png differ
diff --git a/source/_static/frames/VORTEX_anim-72.png b/source/_static/frames/VORTEX_anim-72.png
new file mode 100644
index 0000000000000000000000000000000000000000..d5c41d540f6f3affbb9cb47da9120b515cf929a3
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-72.png differ
diff --git a/source/_static/frames/VORTEX_anim-73.png b/source/_static/frames/VORTEX_anim-73.png
new file mode 100644
index 0000000000000000000000000000000000000000..0cd58a877e34ff353e5f93e685b2edc27188ebb7
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-73.png differ
diff --git a/source/_static/frames/VORTEX_anim-74.png b/source/_static/frames/VORTEX_anim-74.png
new file mode 100644
index 0000000000000000000000000000000000000000..3c25510bdc8b90e20aa55b266536ce7e89ab71c7
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-74.png differ
diff --git a/source/_static/frames/VORTEX_anim-75.png b/source/_static/frames/VORTEX_anim-75.png
new file mode 100644
index 0000000000000000000000000000000000000000..251acf46e8e0b15ffa8bc442691f786e6c36342c
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-75.png differ
diff --git a/source/_static/frames/VORTEX_anim-76.png b/source/_static/frames/VORTEX_anim-76.png
new file mode 100644
index 0000000000000000000000000000000000000000..37fa77f1850ca3fd87a33900ec7ff034f36a792a
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-76.png differ
diff --git a/source/_static/frames/VORTEX_anim-77.png b/source/_static/frames/VORTEX_anim-77.png
new file mode 100644
index 0000000000000000000000000000000000000000..5d854b8561b042f55a655e9099d25ddffe7db7c9
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-77.png differ
diff --git a/source/_static/frames/VORTEX_anim-78.png b/source/_static/frames/VORTEX_anim-78.png
new file mode 100644
index 0000000000000000000000000000000000000000..45ad9081723f73e893f4ddba60820cfce20f0dc2
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-78.png differ
diff --git a/source/_static/frames/VORTEX_anim-79.png b/source/_static/frames/VORTEX_anim-79.png
new file mode 100644
index 0000000000000000000000000000000000000000..cb11a7d283071e634fc8759e8e84cf88145fa344
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-79.png differ
diff --git a/source/_static/frames/VORTEX_anim-80.png b/source/_static/frames/VORTEX_anim-80.png
new file mode 100644
index 0000000000000000000000000000000000000000..68d2f8998b4ca8b2f42fcb6e5271a038a51e6b71
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-80.png differ
diff --git a/source/_static/frames/VORTEX_anim-81.png b/source/_static/frames/VORTEX_anim-81.png
new file mode 100644
index 0000000000000000000000000000000000000000..e096e75aeaf5af6e5f0257cd5a59885c12ef776e
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-81.png differ
diff --git a/source/_static/frames/VORTEX_anim-82.png b/source/_static/frames/VORTEX_anim-82.png
new file mode 100644
index 0000000000000000000000000000000000000000..971aab0639d6b46cad9d28e7f81d6c2eee3e841d
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-82.png differ
diff --git a/source/_static/frames/VORTEX_anim-83.png b/source/_static/frames/VORTEX_anim-83.png
new file mode 100644
index 0000000000000000000000000000000000000000..d5864ce5a9219d35c7e26058abddbf8a23895f52
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-83.png differ
diff --git a/source/_static/frames/VORTEX_anim-84.png b/source/_static/frames/VORTEX_anim-84.png
new file mode 100644
index 0000000000000000000000000000000000000000..07592219385e29609768841451d76db479ed6382
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-84.png differ
diff --git a/source/_static/frames/VORTEX_anim-85.png b/source/_static/frames/VORTEX_anim-85.png
new file mode 100644
index 0000000000000000000000000000000000000000..05b0cd231ea7514e9b3e8740b48ca96adbba7ef3
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-85.png differ
diff --git a/source/_static/frames/VORTEX_anim-86.png b/source/_static/frames/VORTEX_anim-86.png
new file mode 100644
index 0000000000000000000000000000000000000000..5903109a3715a14120d909d2714963bb20297c6c
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-86.png differ
diff --git a/source/_static/frames/VORTEX_anim-87.png b/source/_static/frames/VORTEX_anim-87.png
new file mode 100644
index 0000000000000000000000000000000000000000..73b73fa6b7ce5cd33c644d2ae013ef56e42ad11a
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-87.png differ
diff --git a/source/_static/frames/VORTEX_anim-88.png b/source/_static/frames/VORTEX_anim-88.png
new file mode 100644
index 0000000000000000000000000000000000000000..d6a5269b6806ea875228b507d959d6c98011e8a4
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-88.png differ
diff --git a/source/_static/frames/VORTEX_anim-89.png b/source/_static/frames/VORTEX_anim-89.png
new file mode 100644
index 0000000000000000000000000000000000000000..1749c91b81970f98621e1b7f0cf9e6372b94d1ba
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-89.png differ
diff --git a/source/_static/frames/VORTEX_anim-90.png b/source/_static/frames/VORTEX_anim-90.png
new file mode 100644
index 0000000000000000000000000000000000000000..6796dcf1f75a0a5958bd45b9284fc91e45ff265d
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-90.png differ
diff --git a/source/_static/frames/VORTEX_anim-91.png b/source/_static/frames/VORTEX_anim-91.png
new file mode 100644
index 0000000000000000000000000000000000000000..c48c47b56c28a6948cb8990aecff25fcf1b6998d
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-91.png differ
diff --git a/source/_static/frames/VORTEX_anim-92.png b/source/_static/frames/VORTEX_anim-92.png
new file mode 100644
index 0000000000000000000000000000000000000000..2cd5f6efa2d6073fe69c201366cbbde98ce3bc26
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-92.png differ
diff --git a/source/_static/frames/VORTEX_anim-93.png b/source/_static/frames/VORTEX_anim-93.png
new file mode 100644
index 0000000000000000000000000000000000000000..11c91654893e6b066a2c7f46b7f201eed21cf9f5
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-93.png differ
diff --git a/source/_static/frames/VORTEX_anim-94.png b/source/_static/frames/VORTEX_anim-94.png
new file mode 100644
index 0000000000000000000000000000000000000000..cb6c4365882939559decb4866a70ff7e2af91e2f
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-94.png differ
diff --git a/source/_static/frames/VORTEX_anim-95.png b/source/_static/frames/VORTEX_anim-95.png
new file mode 100644
index 0000000000000000000000000000000000000000..a28d1703c1024e3a3bddb2f2a994808e2303cbac
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-95.png differ
diff --git a/source/_static/frames/VORTEX_anim-96.png b/source/_static/frames/VORTEX_anim-96.png
new file mode 100644
index 0000000000000000000000000000000000000000..9d10e8962aeb13d378ea58183088398f0ad43d53
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-96.png differ
diff --git a/source/_static/frames/VORTEX_anim-97.png b/source/_static/frames/VORTEX_anim-97.png
new file mode 100644
index 0000000000000000000000000000000000000000..f05ffa6f8430665106d56959e0e79a0b38b98ec9
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-97.png differ
diff --git a/source/_static/frames/VORTEX_anim-98.png b/source/_static/frames/VORTEX_anim-98.png
new file mode 100644
index 0000000000000000000000000000000000000000..9588c5161878a56400d5251277916d4be6702e1e
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-98.png differ
diff --git a/source/_static/frames/VORTEX_anim-99.png b/source/_static/frames/VORTEX_anim-99.png
new file mode 100644
index 0000000000000000000000000000000000000000..a3b00e7d551e84fb335a996085ca21fc82a8e56f
Binary files /dev/null and b/source/_static/frames/VORTEX_anim-99.png differ
diff --git a/source/_static/iodef.xml b/source/_static/iodef.xml
new file mode 100644
index 0000000000000000000000000000000000000000..911b117d343d81bbdfba04a08930e6fc1825e213
--- /dev/null
+++ b/source/_static/iodef.xml
@@ -0,0 +1,194 @@
+<?xml version="1.0"?>
+<simulation>
+
+ <context id="nemo" >
+
+ <!-- $id$ -->
+
+ <!--
+============================================================================================================
+= definition of all existing variables =
+= DO NOT CHANGE =
+============================================================================================================
+ -->
+ <field_definition src="./field_def.xml"/>
+ <!--
+============================================================================================================
+= output files definition =
+= Define your own files =
+= put the variables you want... =
+============================================================================================================
+ -->
+
+ <file_definition src="./file_def.xml"/>
+
+ <!--
+
+============================================================================================================
+= grid definition = = DO NOT CHANGE =
+============================================================================================================
+ -->
+
+ <axis_definition>
+ <axis id="deptht" long_name="Vertical T levels" unit="m" positive="down" />
+ <axis id="depthu" long_name="Vertical U levels" unit="m" positive="down" />
+ <axis id="depthv" long_name="Vertical V levels" unit="m" positive="down" />
+ <axis id="depthw" long_name="Vertical W levels" unit="m" positive="down" />
+ <axis id="nfloat" long_name="Float number" unit="1" />
+ <axis id="icbcla" long_name="Iceberg class" unit="1" />
+ <axis id="ncatice" long_name="Ice category" unit="1" />
+ <axis id="iax_20C" long_name="20 degC isotherm" unit="degC" />
+ <axis id="iax_28C" long_name="28 degC isotherm" unit="degC" />
+ </axis_definition>
+
+ <domain_definition src="./domain_def.xml"/>
+
+ <grid_definition>
+ <grid id="grid_T_2D" >
+ <domain id="grid_T" />
+ </grid>
+ <grid id="grid_T_3D" >
+ <domain id="grid_T" />
+ <axis id="deptht" />
+ </grid>
+ <grid id="grid_U_2D" >
+ <domain id="grid_U" />
+ </grid>
+ <grid id="grid_U_3D" >
+ <domain id="grid_U" />
+ <axis id="depthu" />
+ </grid>
+ <grid id="grid_V_2D" >
+ <domain id="grid_V" />
+ </grid>
+ <grid id="grid_V_3D" >
+ <domain id="grid_V" />
+ <axis id="depthv" />
+ </grid>
+ <grid id="grid_W_2D" >
+ <domain id="grid_W" />
+ </grid>
+ <grid id="grid_W_3D" >
+ <domain id="grid_W" />
+ <axis id="depthw" />
+ </grid>
+ <grid id="scalarpoint" />
+
+ </grid_definition>
+
+ </context>
+
+ <!--
+============================================================================================================
+============================================================================================================
+============================================================================================================
+= CRS context
+============================================================================================================
+============================================================================================================
+============================================================================================================
+ -->
+
+ <context id="nemo_crs" >
+
+ <!-- $id$ -->
+
+ <!--
+============================================================================================================
+= definition of all existing variables =
+= DO NOT CHANGE =
+============================================================================================================
+ -->
+ <field_definition src="./field_def.xml"/>
+ <!--
+============================================================================================================
+= output files definition =
+= Define your own files =
+= put the variables you want... =
+============================================================================================================
+ -->
+
+ <file_definition src="./file_crs_def.xml"/>
+
+ <!--
+
+============================================================================================================
+= grid definition = = DO NOT CHANGE =
+============================================================================================================
+ -->
+
+ <axis_definition>
+ <axis id="deptht" long_name="Vertical T levels" unit="m" positive="down" />
+ <axis id="depthu" long_name="Vertical U levels" unit="m" positive="down" />
+ <axis id="depthv" long_name="Vertical V levels" unit="m" positive="down" />
+ <axis id="depthw" long_name="Vertical W levels" unit="m" positive="down" />
+ <axis id="nfloat" long_name="Float number" unit="1" />
+ <axis id="icbcla" long_name="Iceberg class" unit="1" />
+ <axis id="ncatice" long_name="Ice category" unit="1" />
+ <axis id="iax_20C" long_name="20 degC isotherm" unit="degC" />
+ <axis id="iax_28C" long_name="28 degC isotherm" unit="degC" />
+ </axis_definition>
+
+ <domain_definition src="./domain_def.xml"/>
+
+ <grid_definition>
+ <grid id="grid_T_2D" >
+ <domain id="grid_T" />
+ </grid>
+ <grid id="grid_T_3D" >
+ <domain id="grid_T" />
+ <axis id="deptht" />
+ </grid>
+ <grid id="grid_U_2D" >
+ <domain id="grid_U" />
+ </grid>
+ <grid id="grid_U_3D" >
+ <domain id="grid_U" />
+ <axis id="depthu" />
+ </grid>
+ <grid id="grid_V_2D" >
+ <domain id="grid_V" />
+ </grid>
+ <grid id="grid_V_3D" >
+ <domain id="grid_V" />
+ <axis id="depthv" />
+ </grid>
+ <grid id="grid_W_2D" >
+ <domain id="grid_W" />
+ </grid>
+ <grid id="grid_W_3D" >
+ <domain id="grid_W" />
+ <axis id="depthw" />
+ </grid>
+ <grid id="scalarpoint" />
+
+ </grid_definition>
+
+ </context>
+
+ <!--
+============================================================================================================
+============================================================================================================
+============================================================================================================
+= XIOS context
+============================================================================================================
+============================================================================================================
+============================================================================================================
+ -->
+
+ <context id="xios">
+
+ <variable_definition>
+
+ <!--
+ We must have buffer_size > jpi*jpj*jpk*8 (with jpi and jpj the subdomain size)
+-->
+ <variable id="info_level" type="int">0</variable>
+ <variable id="using_server" type="bool">true</variable>
+ <variable id="using_oasis" type="bool">false</variable>
+ <variable id="oasis_codes_id" type="string" >oceanx</variable>
+
+ </variable_definition>
+
+ </context>
+
+</simulation>
diff --git a/source/_static/style.css b/source/_static/style.css
new file mode 100644
index 0000000000000000000000000000000000000000..bc8c6e7962e7b0806e06823de67434c55ff467ea
--- /dev/null
+++ b/source/_static/style.css
@@ -0,0 +1,5 @@
+.blue { color: blue ; }
+.grey , .greysup { color: grey ; }
+.green { color: seagreen; }
+
+.logo { filter: invert(1) !important; }
diff --git a/source/_static/wad_testcase_7.gif b/source/_static/wad_testcase_7.gif
new file mode 100644
index 0000000000000000000000000000000000000000..e06f6b6c52e4e0410f5a1438610dbfa33eb9e243
Binary files /dev/null and b/source/_static/wad_testcase_7.gif differ
diff --git a/source/_templates/layout.html b/source/_templates/layout.html
new file mode 100644
index 0000000000000000000000000000000000000000..85d9b30ceeca5d71a200dc041d6761d1c8e298ac
--- /dev/null
+++ b/source/_templates/layout.html
@@ -0,0 +1,18 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+ <link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}
+
+{% block sidebartitle %}
+
+ <a href="{{ pathto(master_doc) }}">
+ <img src="{{ pathto('_static/NEMO_grey.png', 1) }}" class="logo" alt="Logo"/>
+ </a>
+
+ <p>Community ocean model for multifarious space and time scales</p>
+
+ <div class="version">{{ version }}</div>
+
+ {% include "searchbox.html" %}
+
+{% endblock %}
diff --git a/source/acro.rst b/source/acro.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e39a4bc9dd6a104f3423b71e743d191a2fd98083
--- /dev/null
+++ b/source/acro.rst
@@ -0,0 +1,39 @@
+********
+Acronyms
+********
+
+.. todo::
+
+
+
+.. glossary::
+
+ `AGRIF`_
+ *Adaptive Grid Refinement In Fortran*,
+ package for the integration of full adaptive mesh refinement features within
+ an existing multidimensional finite difference model
+
+ SI\ :sup:`3`\
+ *Sea Ice Integrated Initiative*,
+ unified sea ice model merging functionalities from CICE, GELATO and LIM into the NEMO framework
+
+ `OASIS`_
+ *Ocean Atmosphere Sea Ice Soil*,
+ coupling software to synchronise numerical codes representing different components of the climate system
+
+ PISCES
+ *Pelagic Interactions Scheme for Carbon and Ecosystem Studies*,
+ biogeochemical model simulating marine ecosystems, cycles of carbon and the main nutrients
+
+ TAM
+ *Tangent linear and Adjoint Model*,
+ tools to analyse and control the NEMO dynamical core for a wide range of applications such as
+ sensitivity analysis, parameter estimation, vectors computation or data assimilation.
+
+ TOP
+ *Tracers in Ocean Paradigm*,
+ on/off-line oceanic tracers transport and biogeochemistry models
+
+ `XIOS`_
+ *XML Input Output Server*,
+ library dedicated to input/output management of climate code
diff --git a/source/cfgs.bib b/source/cfgs.bib
new file mode 100644
index 0000000000000000000000000000000000000000..550d2da48893171cd3f7d5a71c3aed2ea9cdc52f
--- /dev/null
+++ b/source/cfgs.bib
@@ -0,0 +1,34 @@
+
+@article{ aumont.ethé.ea_GMD15,
+ title = "PISCES-v2: an ocean biogeochemical model for carbon and
+ ecosystem studies",
+ pages = "2465--2513",
+ journal = "Geoscientific Model Development",
+ volume = "8",
+ number = "8",
+ author = "Aumont, O. and Ethé, C. and Tagliabue, A. and Bopp, L.
+ and Gehlen, M.",
+ year = "2015",
+ month = "Aug",
+ publisher = "Copernicus GmbH",
+ issn = "1991-9603",
+ doi = "10.5194/gmd-8-2465-2015"
+}
+
+@article{ o’dea.arnold.ea_JOO12,
+ title = "An operational ocean forecast system incorporating NEMO
+ and SST data assimilation for the tidally driven European
+ North-West shelf",
+ pages = "3--17",
+ journal = "Journal of Operational Oceanography",
+ volume = "5",
+ number = "1",
+ author = "O’Dea, E J and Arnold, A K and Edwards, K P and Furner,
+ R and Hyder, P and Martin, M J and Siddorn, J R and
+ Storkey, D and While, J and Holt, J T and et al.",
+ year = "2012",
+ month = "Feb",
+ publisher = "Informa UK Limited",
+ issn = "1755-8778",
+ doi = "10.1080/1755876x.2012.11020128"
+}
diff --git a/source/cfgs.rst b/source/cfgs.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9d76be7256a65fb3bba3f364f805853be0e8ff2c
--- /dev/null
+++ b/source/cfgs.rst
@@ -0,0 +1,331 @@
+********************************
+Run the Reference configurations
+********************************
+
+.. todo::
+
+ Lack of illustrations for ref. cfgs, and more generally in the guide.
+
+NEMO is distributed with a set of reference configurations allowing both
+the user to set up his own first applications and
+the developer to test/validate his NEMO developments (using SETTE package).
+
+.. contents::
+ :local:
+ :depth: 1
+
+.. attention::
+
+ Concerning the configurations,
+ the NEMO System Team is only in charge of the so-called reference configurations described below.
+
+.. hint::
+
+ Configurations developed by external research projects or initiatives that
+ make use of NEMO are welcome to be publicized through the website by
+ filling up the form :website:`to add an associated project<projects/add>`.
+
+How to compile an experiment from a reference configuration
+===========================================================
+
+To compile the ORCA2_ICE_PISCES_ reference configuration using :file:`makenemo`,
+one should use the following, by selecting among available architecture file or
+providing a user defined one:
+
+.. code-block:: console
+
+ $ ./makenemo -r 'ORCA2_ICE_PISCES' -m 'my_arch' -j '4'
+
+A new ``EXP00`` folder will be created within the selected reference configurations,
+namely ``./cfgs/ORCA2_ICE_PISCES/EXP00``.
+It will be necessary to uncompress the archives listed in the above table for
+the given reference configuration that includes input & forcing files.
+
+Then it will be possible to launch the execution of the model through a runscript
+(opportunely adapted to the user system).
+
+List of Configurations
+======================
+
+All forcing files listed below in the table are available from |DOI data|_
+
+=================== === === === === === ==================================
+ Configuration Component(s) Archives (input & forcing files)
+------------------- ------------------- ----------------------------------
+ Name O S T P A
+=================== === === === === === ==================================
+ AGRIF_DEMO_ X X X AGRIF_DEMO_v4.0.tar,
+ ORCA2_ICE_v4.0.tar
+ AMM12_ X AMM12_v4.0.tar
+ C1D_PAPA_ X INPUTS_C1D_PAPA_v4.0.tar
+ GYRE_BFM_ X X *none*
+ GYRE_PISCES_ X X X *none*
+ ORCA2_ICE_PISCES_ X X X X ORCA2_ICE_v4.0.tar,
+ INPUTS_PISCES_v4.0.tar
+ ORCA2_OFF_PISCES_ X X ORCA2_OFF_v4.0.tar,
+ INPUTS_PISCES_v4.0.tar
+ ORCA2_OFF_TRC_ X ORCA2_OFF_v4.0.tar
+ ORCA2_SAS_ICE_ X ORCA2_ICE_v4.0.tar,
+ INPUTS_SAS_v4.0.tar
+ SPITZ12_ X X SPITZ12_v4.0.tar
+=================== === === === === === ==================================
+
+.. admonition:: Legend for component combination
+
+ O for OCE, S for SI\ :sup:`3`, T for TOP, P for PISCES and A for AGRIF
+
+AGRIF_DEMO
+----------
+
+``AGRIF_DEMO`` is based on the ``ORCA2_ICE_PISCES`` global configuration at 2° of resolution with
+the inclusion of 3 online nested grids to demonstrate the overall capabilities of AGRIF in
+a realistic context (including the nesting of sea ice models).
+
+The configuration includes a 1:1 grid in the Pacific and two successively nested grids with
+odd and even refinement ratios over the Arctic ocean,
+with the finest grid spanning the whole Svalbard archipelago that is of
+particular interest to test sea ice coupling.
+
+.. image:: _static/AGRIF_DEMO_no_cap.jpg
+ :scale: 66%
+ :align: center
+
+The 1:1 grid can be used alone as a benchmark to check that
+the model solution is not corrupted by grid exchanges.
+Note that since grids interact only at the baroclinic time level,
+numerically exact results can not be achieved in the 1:1 case.
+Perfect reproducibility is obtained only by switching to a fully explicit setup instead of
+a split explicit free surface scheme.
+
+AMM12
+-----
+
+``AMM12`` stands for *Atlantic Margin Model at 12 km* that is
+a regional configuration covering the Northwest European Shelf domain on
+a regular horizontal grid of ~12 km of resolution (see :cite:`ODEA2012`).
+
+.. image:: _static/AMM_domain.png
+ :align: center
+
+This configuration allows to tests several features of NEMO specifically addressed to the shelf seas.
+In particular, ``AMM12`` accounts for vertical s-coordinates system, GLS turbulence scheme,
+tidal lateral boundary conditions using a flather scheme (see more in ``BDY``).
+Boundaries may be completely omitted by setting ``ln_bdy = .false.`` in ``nambdy``.
+
+Sample surface fluxes, river forcing and an initial restart file are included to test a realistic model run
+(``AMM12_v4.0.tar``).
+
+Note that, the Baltic boundary is included within the river input file and is specified as a river source,
+but unlike ordinary river points the Baltic inputs also include salinity and temperature data.
+
+C1D_PAPA
+--------
+
+.. figure:: _static/Papa2015.jpg
+ :height: 225px
+ :align: left
+
+``C1D_PAPA`` is a 1D configuration for the `PAPA station`_ located in
+the northern-eastern Pacific Ocean at 50.1°N, 144.9°W.
+See :gmd:`Reffray et al. (2015) <8/69/2015>` for the description of
+its physical and numerical turbulent-mixing behaviour.
+
+| The water column setup, called NEMO1D, is activated by
+ setting ``ln_c1d = .true.`` in ``namdom`` and
+ has a horizontal domain of 1x1 grid point.
+| This reference configuration uses 75 vertical levels grid (1m at the surface),
+ GLS turbulence scheme with K-epsilon closure and the NCAR bulk formulae.
+
+Data provided with ``INPUTS_C1D_PAPA_v4.2.tar`` file account for:
+
+- :file:`forcing_PAPASTATION_1h_y201[0-1].nc`:
+ ECMWF operational analysis atmospheric forcing rescaled to 1h
+ (with long and short waves flux correction) for years 2010 and 2011
+- :file:`init_PAPASTATION_m06d15.nc`: Initial Conditions from
+ observed data and Levitus 2009 climatology
+- :file:`chlorophyll_PAPASTATION.nc`: surface chlorophyll file from Seawifs data
+
+GYRE_BFM
+--------
+
+``GYRE_BFM`` shares the same physical setup of GYRE_PISCES_,
+but NEMO is coupled with the `BFM`_ biogeochemical model as described in ``./cfgs/GYRE_BFM/README``.
+
+GYRE_PISCES
+-----------
+
+``GYRE_PISCES`` is an idealized configuration representing a Northern hemisphere double gyres system,
+in the Beta-plane approximation with a regular 1° horizontal resolution and 31 vertical levels,
+with PISCES BGC model :cite:`gmd-8-2465-2015`.
+Analytical forcing for heat, freshwater and wind-stress fields are applied.
+
+This configuration acts also as demonstrator of the **user defined setup**
+(``ln_read_cfg = .false.``) and grid setting are handled through
+the ``&namusr_def`` controls in :file:`namelist_cfg`:
+
+.. literalinclude:: ../../../cfgs/GYRE_PISCES/EXPREF/namelist_cfg
+ :language: fortran
+ :lines: 35-41
+
+Note that, the default grid size is 30x20 grid points (with ``nn_GYRE = 1``) and
+vertical levels are set by ``jpkglo``.
+The specific code changes can be inspected in :file:`./src/OCE/USR`.
+
+.. rubric:: Running GYRE as a benchmark
+
+| This simple configuration can be used as a benchmark since it is easy to increase resolution,
+ with the drawback of getting results that have a very limited physical meaning.
+| GYRE grid resolution can be increased at runtime by setting a different value of ``nn_GYRE``
+ (integer multiplier scaling factor), as described in the following table:
+
+=========== ============ ============ ============ ===============
+``nn_GYRE`` ``jpiglo`` ``jpjglo`` ``jpkglo`` Equivalent to
+=========== ============ ============ ============ ===============
+ 1 30 20 31 GYRE 1°
+ 25 750 500 101 ORCA 1/2°
+ 50 1500 1000 101 ORCA 1/4°
+ 150 4500 3000 101 ORCA 1/12°
+ 200 6000 4000 101 ORCA 1/16°
+=========== ============ ============ ============ ===============
+
+| Note that, it is necessary to set ``ln_bench = .true.`` in ``&namusr_def`` to
+ avoid problems in the physics computation and that
+ the model timestep should be adequately rescaled.
+| For example if ``nn_GYRE = 150``, equivalent to an ORCA 1/12° grid,
+ the timestep ``rn_rdt`` should be set to 1200 seconds
+ Differently from previous versions of NEMO, the code uses by default the time-splitting scheme and
+ internally computes the number of sub-steps.
+
+ORCA2_ICE_PISCES
+----------------
+
+``ORCA2_ICE_PISCES`` is a reference configuration for the global ocean with
+a 2°x2° curvilinear horizontal mesh and 31 vertical levels,
+distributed using z-coordinate system and with 10 levels in the top 100m.
+ORCA is the generic name given to global ocean Mercator mesh,
+(i.e. variation of meridian scale factor as cosinus of the latitude),
+with two poles in the northern hemisphere so that
+the ratio of anisotropy is nearly one everywhere
+
+This configuration uses the three components
+
+- |OCE|, the ocean dynamical core
+- |ICE|, the thermodynamic-dynamic sea ice model.
+- |MBG|, passive tracer transport module and PISCES BGC model :cite:`gmd-8-2465-2015`
+
+All components share the same grid.
+The model is forced with CORE-II normal year atmospheric forcing and
+it uses the NCAR bulk formulae.
+
+.. rubric:: Ocean Physics
+
+:horizontal diffusion on momentum:
+ the eddy viscosity coefficient depends on the geographical position.
+ It is taken as 40000 m\ :sup:`2`/s, reduced in the equator regions (2000 m\ :sup:`2`/s)
+ excepted near the western boundaries.
+:isopycnal diffusion on tracers:
+ the diffusion acts along the isopycnal surfaces (neutral surface) with
+ an eddy diffusivity coefficient of 2000 m\ :sup:`2`/s.
+:Eddy induced velocity parametrization:
+ With a coefficient that depends on the growth rate of baroclinic instabilities
+ (it usually varies from 15 m\ :sup:`2`/s to 3000 m\ :sup:`2`/s).
+:lateral boundary conditions:
+ Zero fluxes of heat and salt and no-slip conditions are applied through lateral solid boundaries.
+:bottom boundary condition:
+ Zero fluxes of heat and salt are applied through the ocean bottom.
+ The Beckmann [19XX] simple bottom boundary layer parameterization is applied along
+ continental slopes.
+ A linear friction is applied on momentum.
+:convection:
+ The vertical eddy viscosity and diffusivity coefficients are increased to 1 m\ :sup:`2`/s in
+ case of static instability.
+:time step: is 5400sec (1h30') so that there is 16 time steps in one day.
+
+ORCA2_OFF_PISCES
+----------------
+
+``ORCA2_OFF_PISCES`` shares the same general offline configuration of ``ORCA2_ICE_TRC``,
+but only PISCES model is an active component of TOP.
+
+ORCA2_OFF_TRC
+-------------
+
+| ``ORCA2_OFF_TRC`` is based on the ORCA2 global ocean configuration
+ (see ORCA2_ICE_PISCES_ for general description) along with
+ the tracer passive transport module (TOP),
+ but dynamical fields are pre-calculated and read with specific time frequency.
+| This enables for an offline coupling of TOP components,
+ here specifically inorganic carbon compounds (CFC11, CFC12, SF6, C14) and water age module (age).
+ See :file:`namelist_top_cfg` to inspect the selection of
+ each component with the dedicated logical keys.
+
+Pre-calculated dynamical fields are provided to NEMO using
+the namelist ``&namdta_dyn`` in :file:`namelist_cfg`,
+in this case with a 5 days frequency (120 hours):
+
+.. literalinclude:: ../../namelists/namdta_dyn
+ :language: fortran
+
+Input dynamical fields for this configuration (:file:`ORCA2_OFF_v4.0.tar`) comes from
+a 2000 years long climatological simulation of ORCA2_ICE using ERA40 atmospheric forcing.
+
+| Note that,
+ this configuration default uses linear free surface (``ln_linssh = .true.``) assuming that
+ model mesh is not varying in time and
+ it includes the bottom boundary layer parameterization (``ln_trabbl = .true.``) that
+ requires the provision of BBL coefficients through ``sn_ubl`` and ``sn_vbl`` fields.
+| It is also possible to activate PISCES model (see ``ORCA2_OFF_PISCES``) or
+ a user defined set of tracers and source-sink terms with ``ln_my_trc = .true.``
+ (and adaptation of ``./src/TOP/MY_TRC`` routines).
+
+In addition, the offline module (OFF) allows for the provision of further fields:
+
+1. **River runoff** can be provided to TOP components by setting ``ln_dynrnf = .true.`` and
+ by including an input datastream similarly to the following:
+
+ .. code-block:: fortran
+
+ sn_rnf = 'dyna_grid_T', 120, 'sorunoff' , .true., .true., 'yearly', '', '', ''
+
+2. **VVL dynamical fields**, in the case input data were produced by a dyamical core using
+ variable volume (``ln_linssh = .false.``)
+ it is necessary to provide also diverce and E-P at before timestep by
+ including input datastreams similarly to the following
+
+ .. code-block:: fortran
+
+ sn_div = 'dyna_grid_T', 120, 'e3t' , .true., .true., 'yearly', '', '', ''
+ sn_empb = 'dyna_grid_T', 120, 'sowaflupb', .true., .true., 'yearly', '', '', ''
+
+More details can be found by inspecting the offline data manager in
+the routine :file:`./src/OFF/dtadyn.F90`.
+
+ORCA2_SAS_ICE
+-------------
+
+| ORCA2_SAS_ICE is a demonstrator of the Stand-Alone Surface (SAS) module and
+ it relies on ORCA2 global ocean configuration (see ORCA2_ICE_PISCES_ for general description).
+| The standalone surface module allows surface elements such as sea-ice, iceberg drift, and
+ surface fluxes to be run using prescribed model state fields.
+ It can profitably be used to compare different bulk formulae or
+ adjust the parameters of a given bulk formula.
+
+More informations about SAS can be found in :doc:`NEMO manual <cite>`.
+
+SPITZ12
+-------
+
+``SPITZ12`` is a regional configuration around the Svalbard archipelago
+at 1/12° of horizontal resolution and 75 vertical levels.
+See :gmd:`Rousset et al. (2015) <8/2991/2015>` for more details.
+
+This configuration references to year 2002,
+with atmospheric forcing provided every 2 hours using NCAR bulk formulae,
+while lateral boundary conditions for dynamical fields have 3 days time frequency.
+
+.. rubric:: References
+
+.. bibliography:: cfgs.bib
+ :all:
+ :style: unsrt
+ :labelprefix: C
diff --git a/source/cite.rst b/source/cite.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7e42f825e24f18d4e620b0e3a2a94182b3fb0742
--- /dev/null
+++ b/source/cite.rst
@@ -0,0 +1,47 @@
+***********
+How to cite
+***********
+
+.. todo::
+
+
+
+|NEMO-OCE|
+ :title:`NEMO ocean engine`,
+ NEMO System Team,
+ Scientific Notes of Climate Modelling Center, 27,
+ ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+ :doi:`10.5281/zenodo.1464816`
+
+.. literalinclude:: ref.bib
+ :language: bibtex
+ :lines: 1-9
+ :caption: BibTeX source for NEMO manual
+
+|NEMO-ICE|
+ :title:`Sea Ice modelling Integrated Initiative (SI`\ :sup:`3`\ :title:`) --
+ The NEMO sea ice engine`,
+ NEMO Sea Ice Working Group,
+ Scientific Notes of Climate Modelling Center, 31,
+ ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+ :doi:`10.5281/zenodo.1464816`
+
+
+.. literalinclude:: ref.bib
+ :language: bibtex
+ :lines: 13-21
+ :caption: BibTeX source for SI\ :sup:`3` manual
+
+|NEMO-TOP|
+ :title:`Tracer in Ocean Paradigm (TOP) -- The NEMO passive tracer engine`,
+ NEMO TOP Working Group,
+ Scientific Notes of Climate Modelling Center, 28,
+ ISSN 1288-1619 Institut Pierre-Simon Laplace (IPSL),
+ :doi:`10.5281/zenodo.1464816`
+
+
+
+.. literalinclude:: ref.bib
+ :language: bibtex
+ :lines: 25-33
+ :caption: BibTeX source for TOP manual
diff --git a/source/conf.py b/source/conf.py
new file mode 100644
index 0000000000000000000000000000000000000000..e05efa51f89d76a1e90fec40a77d6052dda5d520
--- /dev/null
+++ b/source/conf.py
@@ -0,0 +1,283 @@
+# -*- coding: utf-8 -*-
+#
+# NEMO documentation build configuration file, created by
+# sphinx-quickstart on Tue Oct 15 20:13:55 2019.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.extlinks', 'sphinxcontrib.bibtex',
+ 'sphinx.ext.todo' , 'sphinx.ext.autosectionlabel']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'guide'
+
+# General information about the project.
+project = u'NEMO'
+copyright = u'2020, NEMO Consortium'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'trunk'
+# The full version, including alpha/beta/rc tags.
+release = 'trunk'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['global.rst', 'readme.rst']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'emacs'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = '_static/ORCA.ico'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'NEMOdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('guide', 'guide.tex', u'NEMO Quick Start Guide',
+ u'NEMO Consortium', 'howto'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('guide', 'nemo', u'NEMO Documentation',
+ [u'NEMO System Team'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('guide', 'NEMO', u'NEMO Documentation',
+ u'NEMO System Team', 'NEMO', 'Community Ocean Model',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# -- Customisation -------------------------------------------------------------
+
+# Timestamping
+import datetime
+year = datetime.date.today().year
+copyright = '2008-' + str( year ) + ', NEMO Consortium'
+
+# Link aliases
+extlinks = {
+ 'doi' : ('https://doi.org/%s' , 'doi:'),
+ 'manhtml': ('https://forge.ipsl.jussieu.fr/nemo/chrome/site/doc/NEMO/manual/html/%s', None ),
+ 'forge' : ('https://forge.ipsl.jussieu.fr/nemo/%s' , None ),
+ 'gmd' : ('https://www.geosci-model-dev.net/%s' , None ),
+ 'github' : ('https://github.com/NEMO-ocean/%s' , None ),
+ 'xios' : ('https://forge.ipsl.jussieu.fr/ioserver/%s' , None ),
+ 'website': ('https://www.nemo-ocean.eu/%s' , None ),
+ 'zenodo' : ('https://zenodo.org/publication/%s' , None )
+}
+
+# Include common directives for every rst file
+rst_epilog = open('global.rst', 'r').read()
+
+# SVN revision
+import subprocess
+rev = subprocess.check_output("svnversion").decode("utf-8")
+rst_prolog = '.. |revision| replace:: %s' % rev
+
+# 'draft' build tag: DRAFT watermark and TODO list
+if tags.has('draft'):
+ todo_include_todos = True
+ todo_emit_warnings = True
+else:
+ exclude_patterns = ['global.rst', 'readme.rst', 'todos.rst', 'unpub*']
+
+# Default language to highlight set to fortran
+highlight_language = 'fortran'
+
+# Extra setting for sphinxcontrib.bibtex upgrade to 2.X.X branche
+bibtex_bibfiles = ['cfgs.bib', 'ref.bib', 'tests.bib', 'zooms.bib']
diff --git a/source/cplg.rst b/source/cplg.rst
new file mode 100644
index 0000000000000000000000000000000000000000..51108819c6529cd77d2f859c37c9ced6b5cd2db7
--- /dev/null
+++ b/source/cplg.rst
@@ -0,0 +1,21 @@
+********
+Coupling
+********
+
+.. todo::
+
+ The ‘Coupling’ chapter needs to be enriched
+
+NEMO currently exploits OASIS-3-MCT (versions 1 to 4) to implement a generalised coupled interface
+(:manhtml:`Coupled Formulation <node50.html>`).
+It can be used to interface with most of the European atmospheric GCM
+(ARPEGE, ECHAM, ECMWF, Ha- dAM, HadGAM, LMDz), as well as to regional atmospheric models
+(WRF, COSMO, Meso-NH, AROME).
+To implement the coupling of two independent NEMO components,
+ocean on one hand and sea-ice plus other surface processes on the other hand
+(:manhtml:`Standalone Surface Module - SAS <node46.html>`).
+
+To enable the OASIS interface the required compilation key is ``key_oasis3``.
+You must also add ``key_oasis3_v1v2`` if you use OASIS-3-MCT version 1 and 2.
+The parameters to set are in sections ``&namsbc_cpl`` and
+in case of using of SAS also in section ``&namsbc_sas``.
diff --git a/source/da.rst b/source/da.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8a6cad6d8139beaf08c17564e3a6fec5de6bfef9
--- /dev/null
+++ b/source/da.rst
@@ -0,0 +1,68 @@
+*****************
+Data assimilation
+*****************
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+The assimilation interface to NEMO is split into three modules.
+
+- ``OBS`` for the observation operator
+- ``ASM`` for the application of increments and model bias correction
+ (based on the assimilation increments).
+- ``TAM`` the tangent linear and adjoint model.
+
+Please see :doc:`NEMO manual <cite>` for more details including
+information about the input file formats and the namelist settings.
+
+Observation and model comparison (``OBS``)
+==========================================
+
+The observation and model comparison code (OBS) reads in observation files
+(profile temperature and salinity, sea surface temperature, sea level anomaly, sea ice concentration,
+and velocity) and calculates an interpolated model equivalent value at
+the observation location and nearest model timestep.
+The resulting data are saved in a feedback file (or files).
+The code was originally developed for use with the NEMOVAR data assimilation code, but
+can be used for validation or verification of model or any other data assimilation system.
+This is all controlled by the namelist.
+To build with the OBS code active ``key_diaobs`` must be set.
+
+More details in :manhtml:`"Observation and Model Comparison (OBS)" chapter <node83.html>`.
+
+Standalone observation operator (``SAO``)
+-----------------------------------------
+
+The OBS code can also be run after a model run using saved NEMO model data.
+This is accomplished using the standalone observation operator (SAO)
+(previously known the offline observation operator).
+
+To build the SAO use :file:`makenemo`.
+This means compiling NEMO once (in the normal way) for the chosen configuration.
+Then include ``SAO`` at the end of the relevant line in :file:`cfg.txt` file.
+Then recompile with the replacement main program in :file:`./src/SAO`.
+This is a special version of :file:`nemogcm.F90` (which doesn't run the model,
+but reads in the model fields, and observations and runs the OBS code.
+See :manhtml:`"Standalone observation operator (SAO)" section <node88.html>`.
+
+Apply assimilation increments (``ASM``)
+=======================================
+
+The ASM code adds the functionality to apply increments to the model variables:
+temperature, salinity, sea surface height, velocity and sea ice concentration.
+These are read into the model from a NetCDF file which
+may be produced by separate data assimilation code.
+The code can also output model background fields which are used as an input to data assimilation code.
+This is all controlled by the namelist ``&nam_asminc``.
+To build the ASM code ``key asminc`` must be set.
+
+More details in :manhtml:`"Apply Assimilation Increments (ASM)" chapter <node89.html>`.
+
+Tangent linear and adjoint (``TAM``)
+====================================
+
+This is the tangent linear and adjoint code of NEMO which is useful to 4D VAR assimilation.
diff --git a/source/diags.rst b/source/diags.rst
new file mode 100644
index 0000000000000000000000000000000000000000..d940197c6db5ddf130b0913aa2137f939308b56b
--- /dev/null
+++ b/source/diags.rst
@@ -0,0 +1,119 @@
+***********
+Diagnostics
+***********
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+Output of diagnostics in NEMO is usually done using XIOS.
+This is an efficient way of writing diagnostics because
+the time averaging, file writing and even some simple arithmetic or regridding is carried out in
+parallel to the NEMO model run.
+This page gives a basic introduction to using XIOS with NEMO.
+Much more information is available from the :xios:`XIOS homepage<>` above and from the NEMO manual.
+
+Use of XIOS for diagnostics is activated using the pre-compiler key ``key_xios``.
+
+Extracting and installing XIOS
+==============================
+
+1. Install the NetCDF4 library.
+ If you want to use single file output you will need to compile the HDF & NetCDF libraries to
+ allow parallel IO.
+2. Download the version of XIOS that you wish to use.
+ The recommended version is now XIOS 2.5:
+
+ .. code-block:: console
+
+ $ svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
+
+and follow the instructions in :xios:`XIOS documentation <wiki/documentation>` to compile it.
+If you find problems at this stage, support can be found by subscribing to
+the :xios:`XIOS mailing list <../mailman/listinfo.cgi/xios-users>` and sending a mail message to it.
+
+XIOS Configuration files
+------------------------
+
+XIOS is controlled using XML input files that should be copied to
+your model run directory before running the model.
+Examples of these files can be found in the reference configurations (:file:`./cfgs`).
+The XIOS executable expects to find a file called :file:`iodef.xml` in the model run directory.
+In NEMO we have made the decision to use include statements in the :file:`iodef.xml` file to include:
+
+- :file:`field_def_nemo-oce.xml` (for physics),
+- :file:`field_def_nemo-ice.xml` (for ice),
+- :file:`field_def_nemo-pisces.xml` (for biogeochemistry) and
+- :file:`domain_def.xml` from the :file:`./cfgs/SHARED` directory.
+
+Most users will not need to modify :file:`domain_def.xml` or :file:`field_def_nemo-???.xml` unless
+they want to add new diagnostics to the NEMO code.
+The definition of the output files is organized into separate :file:`file_definition.xml` files which
+are included in the :file:`iodef.xml` file.
+
+Modes
+=====
+
+Detached Mode
+-------------
+
+In detached mode the XIOS executable is executed on separate cores from the NEMO model.
+This is the recommended method for using XIOS for realistic model runs.
+To use this mode set ``using_server`` to ``true`` at the bottom of the :file:`iodef.xml` file:
+
+.. code-block:: xml
+
+ <variable id="using_server" type="boolean">true</variable>
+
+Make sure there is a copy (or link to) your XIOS executable in the working directory and
+in your job submission script allocate processors to XIOS.
+
+Attached Mode
+-------------
+
+In attached mode XIOS runs on each of the cores used by NEMO.
+This method is less efficient than the detached mode but can be more convenient for testing or
+with small configurations.
+To activate this mode simply set ``using_server`` to false in the :file:`iodef.xml` file
+
+.. code-block:: xml
+
+ <variable id="using_server" type="boolean">false</variable>
+
+and don't allocate any cores to XIOS.
+
+.. note::
+
+ Due to the different domain decompositions between XIOS and NEMO,
+ if the total number of cores is larger than the number of grid points in the ``j`` direction then
+ the model run will fail.
+
+Adding new diagnostics
+======================
+
+If you want to add a NEMO diagnostic to the NEMO code you will need to do the following:
+
+1. Add any necessary code to calculate you new diagnostic in NEMO
+2. Send the field to XIOS using ``CALL iom_put( 'field_id', variable )`` where
+ ``field_id`` is a unique id for your new diagnostics and
+ variable is the fortran variable containing the data.
+ This should be called at every model timestep regardless of how often you want to output the field.
+ No time averaging should be done in the model code.
+3. If it is computationally expensive to calculate your new diagnostic
+ you should also use "iom_use" to determine if it is requested in the current model run.
+ For example,
+
+ .. code-block:: fortran
+
+ IF iom_use('field_id') THEN
+ !Some expensive computation
+ !...
+ !...
+ iom_put('field_id', variable)
+ ENDIF
+
+4. Add a variable definition to the :file:`field_def_nemo-???.xml` file.
+5. Add the variable to the :file:`iodef.xml` or :file:`file_definition.xml` file.
diff --git a/source/docutils.conf b/source/docutils.conf
new file mode 100644
index 0000000000000000000000000000000000000000..1bf4d8323e24191a19a7023fb96275331fe93197
--- /dev/null
+++ b/source/docutils.conf
@@ -0,0 +1,2 @@
+[restructuredtext parser]
+syntax_highlight = short
diff --git a/source/global.rst b/source/global.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9aa69404714702f176b6209f3941c0f74c8cc0d3
--- /dev/null
+++ b/source/global.rst
@@ -0,0 +1,79 @@
+.. Roles
+
+.. custom styles related to CSS classes in './_static/style.css'
+
+.. role:: blue
+.. role:: green
+.. role:: grey
+.. role:: greysup(sup)
+
+.. inline code snippets
+
+.. role:: python(code)
+ :language: python
+ :class: highlight
+
+.. role:: fortran(code)
+ :language: fortran
+ :class: highlight
+
+.. role:: console(code)
+ :language: console
+ :class: highlight
+
+.. Substitutions
+
+.. |NEMO-OCE| replace:: :blue:`NEMO-OCE (Ocean dynamics)`
+.. |OCE| replace:: :blue:`NEMO-OCE`
+.. |NEMO-ICE| replace:: :grey:`NEMO-SI`\ :greysup:`3` :grey:`(Sea Ice)`
+.. |ICE| replace:: :grey:`NEMO-SI`\ :greysup:`3`
+.. |NEMO-MBG| replace:: :green:`NEMO-TOP/PISCES (Tracers)`
+.. |MBG| replace:: :green:`NEMO-TOP/PISCES`
+
+.. External links
+
+ .. Consortium institutes
+
+.. _CMCC: https://www.cmcc.it
+.. _CNRS: https://www.cnrs.fr
+.. _Met Office: https://www.metoffice.gov.uk
+.. _MOI: https://www.mercator-ocean.fr
+.. _NERC: https://nerc.ukri.org
+
+ .. Models / Libraries / Dependencies
+
+.. _AGRIF: http://agrif.imag.fr
+.. _BFM: http://www.bfm-community.eu
+.. _FCM: https://metomi.github.io/fcm
+.. _IOIPSL: https://forge.ipsl.jussieu.fr/igcmg/browser/IOIPSL
+.. _NEMO: https://www.nemo-ocean.eu
+.. _OASIS: https://portal.enes.org/oasis
+.. _XIOS: https://forge.ipsl.jussieu.fr/ioserver
+
+ .. Misc.
+
+.. _EGU: http://www.egu.eu
+.. _Special Issue: https://www.geosci-model-dev.net/special_issue40.html
+.. _BFM man: https://cmcc-foundation.github.io/www.bfm-community.eu/files/bfm-nemo-manual_r1.0_201508.pdf
+.. _RST man: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+.. _PAPA station: http://www.pmel.noaa.gov/OCS/Papa/index-Papa.shtml
+.. _ISOMIP: http://staff.acecrc.org.au/~bkgalton/ISOMIP/test_cavities.pdf
+
+.. DOI
+
+ .. Publications (`:samp:` to deactivate link for unpublished documents)
+
+.. _DOI man OCE: https://doi.org/10.5281/zenodo.1464816
+.. _DOI man ICE: :samp: https://doi.org/10.5281/zenodo.1471689
+.. _DOI man MBG: :samp: https://doi.org/10.5281/zenodo.1471700
+.. _DOI qsg: :samp: https://doi.org/10.5281/zenodo.1475325
+.. _DOI dev stgy: https://doi.org/10.5281/zenodo.1471663
+.. _DOI data: https://doi.org/10.5281/zenodo.1472245
+
+ .. Badges (same labels as previously, substitution to link images)
+
+.. |DOI man OCE| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1464816.svg
+.. |DOI man ICE| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471689.svg
+.. |DOI man MBG| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+.. |DOI qsg| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1475325.svg
+.. |DOI data| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1472245.svg
diff --git a/source/guide.rst b/source/guide.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2f17b3e1207e5334e525f42aeebb81148100e228
--- /dev/null
+++ b/source/guide.rst
@@ -0,0 +1,76 @@
+#################
+Quick Start Guide
+#################
+
+.. For headings markup, this convention is recommended from Python’s Style Guide
+ # with overline, for parts
+ * with overline, for chapters
+ =, for sections
+ -, for subsections
+ ^, for subsubsections
+ ", for paragraphs
+
+ 'global.rst' contains a list of roles, substitutions and URL links for the guide.
+ It is loaded for each file with the 'rst_epilog' setting in 'conf.py'
+
+.. toctree::
+ :hidden:
+
+ todos
+
+.. Only displayed with 'make drafthtml'
+
+.. toctree::
+ :hidden:
+ :caption: Unpublished READMEs
+ :glob:
+ :titlesonly:
+
+ unpub/*
+
+.. Only displayed with 'make drafthtml'
+
+.. toctree::
+ :hidden:
+ :caption: Getting started
+
+ install
+ cfgs
+ tests
+
+.. toctree::
+ :hidden:
+ :caption: Setup your configuration
+
+ setup
+ diags
+ tools
+
+.. toctree::
+ :hidden:
+ :caption: Advanced use
+
+ zooms
+ cplg
+ da
+ tracers
+
+.. toctree::
+ :hidden:
+ :caption: Miscellaneous
+
+ cite
+ contrib
+ changes
+ acro
+
+:Release: |release|
+
+.. only:: draft
+
+ .. Only on draft
+
+ :*Date*: |today|
+ :*SVN rev*: |revision|
+
+.. include:: readme.rst
diff --git a/source/readme.rst b/source/readme.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7e722505b3d2842f5aab0cfa07acb6acb37d042f
--- /dev/null
+++ b/source/readme.rst
@@ -0,0 +1,130 @@
+**Contents**
+
+.. contents::
+ :local:
+
+
+
+
+.. _`Former web platform forge`: https://forge.ipsl.jussieu.fr/nemo
+.. _`NEMO users' guide`: https://sites.nemo-ocean.io/user-guide
+.. _`Migration Guide`: https://sites.nemo-ocean.io/user-guide/migration.html
+.. _`Change list`: https://sites.nemo-ocean.io/user-guide/changes.html
+.. _`Test case repository`: https://github.com/NEMO-ocean/NEMO-examples
+.. _`How to cite`: https://www.nemo-ocean.eu/bibliography/how-to-cite/
+.. _`NEMO forums`: https://nemo-ocean.discourse.group
+.. _`NEMO newsletter`: https://listes.ipsl.fr/sympa/subscribe/nemo-newsletter
+.. _`NEMO publications`: https://www.nemo-ocean.eu/bibliography/publications/add
+.. _`NEMO projects`: https://www.nemo-ocean.eu/projects/add
+.. _`Special Issue`: https://gmd.copernicus.org/articles/special_issue40.html
+.. _`NEMO System Team wiki`: https://forge.nemo-ocean.eu/developers/home/-/wikis/Home
+.. _`NEMO ocean engine`: https://zenodo.org/record/1464816
+.. _`NEMO Tracers engine` : https://zenodo.org/record/1471700
+.. _`NEMO Sea Ice engine`: https://zenodo.org/record/1471689
+
+
+**Welcome to NEMO home page!**
+
+NEMO (*Nucleus for European Modelling of the Ocean*) is a state-of-the-art modelling
+framework for research activities and forecasting services in ocean and climate sciences,
+developed in a sustainable way by the NEMO European consortium since 2008.
+
+This page intends to help you to get started using the NEMO platform and to introduce you
+to the different levels of information available. It starts here with NEMO release 4.2.0.
+
+Reminder: Our `Former web platform forge`_ (SVN+Trac) contains the previous documentation
+and releases made available from the beginning of the project up to of NEMO 4.0.
+
+Getting started
+===============
+
+Getting your hands on NEMO: the first steps are described in detail in the
+`NEMO users' guide`_ . This explains how to download the code, build the environment,
+create the executable, and perform a first integration.
+
+If you are already using a previous release of NEMO, please refer to the
+`Migration Guide`_ which aims to help you to make the move to 4.2.0.
+
+The above users guides cover in detail what is available from gitlab and supported by NEMO
+System Team. Aside from this web platform, a set of test cases is also available from the
+`Test case repository`_ . These test cases can be useful for students, outreach, and
+exploring specific aspects of NEMO with light configurations. The web page also allows you
+to submit test cases you have developed and want to share with the community. Feel free to
+contribute!
+
+
+Project documentation
+=====================
+
+Reference manuals fully describing NEMO for the three main component
+
+* |OCE| models the ocean {thermo}dynamics and solves the primitive equations (`./src/OCE <./src/OCE>`_)
+
+* |ICE| simulates sea-ice {thermo}dynamics, brine inclusions and subgrid-scale thickness
+ variations (`./src/ICE <./src/ICE>`_)
+
+* |MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes
+ (`./src/TOP <./src/TOP>`_)
+are available from Zenodo:
+
+============ ======================== =====
+ Component Reference Manual DOI
+============ ======================== =====
+ |NEMO-OCE| `NEMO ocean engine`_ .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.6334656.svg
+ :target: https://doi.org/10.5281/zenodo.6334656
+ |NEMO-ICE| `NEMO Sea Ice engine`_ *not yet available*
+ |NEMO-MBG| `NEMO Tracers engine`_ .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+ :target: https://doi.org/10.5281/zenodo.1471700
+============ ======================== =====
+
+These reference manuals are the publications that should be cited in your own
+publications. Please visit `How to cite`_? for details.
+
+New features of 4.2.0 release are described in the `Change list`_ section of the `NEMO users' guide`_
+
+
+Asking questions, and exchanging information
+============================================
+- Register once for all and use the `NEMO forums`_ on discourse to share and discuss with the NEMO community.
+
+- Register once for all and receive by mail the `NEMO newsletter`_ : recommended for all
+ users to receive the major announcements from the project (new releases, open meetings and
+ main informations). Low traffic: about ten messages a year.
+
+
+Contributing to NEMO visibility: projects and publications
+==========================================================
+Please help us justifying the NEMO development efforts by
+
+- Adding your publications using NEMO and its outputs to the `NEMO publications`_ page
+
+- Describing your project using NEMO on the `NEMO projects`_ page
+
+NEMO also has a `Special Issue`_ in the open-access journal
+Geoscientific Model Development (GMD) from the European Geosciences Union
+The main scope is to collect relevant manuscripts covering various topics and
+to provide a single portal to assess the model potential and evolution.
+
+
+
+Contributing to NEMO development
+================================
+
+NEMO strives to be written in a way which allows the easy incorporation of developments.
+You are welcome to contribute to the development of the NEMO Shared reference. NEMO
+development is driven by NEMO Consortium planning and producing NEMO's sustainable
+development in order to keep a reliable evolving framework. Development is organised and
+scheduled through a five years development strategy, Working groups and the activities of
+the development team (named NEMO System Team) in a yearly workplan. More information is
+available on the `NEMO System Team wiki`_
+
+
+Disclaimer
+==========
+
+The NEMO source code is freely available and distributed under
+`CeCILL v2.0 license <./LICENSE>`_ (GNU GPL compatible).
+
+You can use, modify and/or redistribute the software under its terms,
+but users are provided only with a limited warranty and the software's authors and
+the successive licensor's have only limited liability.
diff --git a/source/setup.rst b/source/setup.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1560de3b9d847adf78543a3d7423defc426f81f4
--- /dev/null
+++ b/source/setup.rst
@@ -0,0 +1,283 @@
+******************************
+Setting up a new configuration
+******************************
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+Starting from an existing configuration
+=======================================
+
+There are three options to build a new configuration from an existing one.
+
+Option 1: Duplicate an existing configuration
+---------------------------------------------
+
+The NEMO so-called Reference Configurations cover a number of major features for NEMO setup
+(global, regional, 1D, using embedded zoom with AGRIF...)
+
+One can create a new configuration by duplicating one of the reference configurations
+(``ORCA2_ICE_PISCES`` in the following example)
+
+.. code-block:: console
+
+ $ ./makenemo –n 'ORCA2_ICE_PISCES_MINE' -r 'ORCA2_ICE_PISCES' -m 'my_arch'
+
+Option 2: Duplicate with differences
+------------------------------------
+
+Create and compile a new configuration based on a reference configuration
+(``ORCA2_ICE_PISCES`` in the following example) but with different pre-processor options.
+For this either add ``add_key`` or ``del_key`` keys as required; e.g.
+
+.. code-block:: console
+
+ $ ./makenemo –n 'ORCA2_ICE_PISCES_MINE' -r 'ORCA2_ICE_PISCES' -m 'my_arch' del_key 'key_xios' add_key 'key_diahth'
+
+Option 3: Use the SIREN tools to subset an existing model
+---------------------------------------------------------
+
+Define a regional configuration which is a {sub,super}-set of an existing configuration.
+
+This last option employs the SIREN software tools that are included in the standard distribution.
+The software is written in Fortran 95 and available in the :file:`./tools/SIREN` directory.
+SIREN allows you to create your own regional configuration embedded in a wider one.
+
+SIREN is a set of programs to create all the input files you need to
+run a NEMO regional configuration.
+
+:Demo: Set of GLORYS files (GLObal ReanalYSis on the ORCA025 grid),
+ as well as examples of namelists are available `here`_.
+:Doc: :forge:`chrome/site/doc/SIREN/html/index.html`
+:Support: Any questions or comments regarding the use of SIREN should be posted in
+ :forge:`the corresponding forum <discussion/forum/2>`.
+
+.. _here: https://prodn.idris.fr/thredds/catalog/ipsl_public/rron463/catalog.html
+
+Option 4: Use the nesting tools to create embedded zooms or regional configurations from an existing grid
+---------------------------------------------------------------------------------------------------------
+(see :download:`NESTING README <../../../tools/NESTING/README>`).
+
+
+Creating a completely new configuration
+=======================================
+
+From NEMO version 4.0 there are two ways to build configurations from scratch.
+The appropriate method to use depends largely on the target configuration.
+Method 1 is for more complex/realistic global or regional configurations and
+method 2 is intended for simpler, idealised configurations whose
+domains and characteristics can be described in simple geometries and formulae.
+
+Option 1: Create and use a domain configuration file
+----------------------------------------------------
+
+This method is used by each of the reference configurations,
+so that downloading their input files linked to their description can help.
+Although starting from scratch,
+it is advisable to create the directory structure to house your new configuration by
+duplicating the closest reference configuration to your target application.
+For example, if your application requires both ocean ice and passive tracers,
+then use the ``ORCA2_ICE_PISCES`` as template,
+and execute following command to build your ``MY_NEW_CONFIG`` configuration:
+
+.. code-block:: sh
+
+ $ ./makenemo –n 'MY_NEW_CONFIG' -r 'ORCA2_ICE_PISCES' -m 'my_arch'
+
+where ``MY_NEW_CONFIG`` can be substituted with
+a suitably descriptive name for your new configuration.
+
+The purpose of this step is simply to create and populate the appropriate :file:`WORK`,
+:file:`MY_SRC` and :file:`EXP00` subdirectories for your new configuration.
+Other choices for the base reference configuration might be
+
+:GYRE: If your target application is ocean-only
+:AMM12: If your target application is regional with open boundaries
+
+All the domain information for your new configuration will be contained within
+a netcdf file called :file:`domain_cfg.nc` which you will need to create and
+place in the :file:`./cfgs/MY_NEW_CONFIG/EXP00` sub-directory.
+Firstly though, ensure that your configuration is set to use such a file by checking that
+
+.. code-block:: fortran
+
+ ln_read_cfg = .true.
+
+in :file:`./cfgs/MY_NEW_CONFIG/EXP00/namelist_cfg`
+
+Create the :file:`domain_cfg.nc` file which must contain the following fields
+
+.. code-block:: c
+
+ /* configuration name, configuration resolution */
+ int ORCA, ORCA_index
+ /* lateral global domain b.c. */
+ int Iperio, Jperio, NFoldT, NFoldF
+ /* flags for z-coord, z-coord with partial steps and s-coord */
+ int ln_zco, ln_zps, ln_sco
+ /* flag for ice shelf cavities */
+ int ln_isfcav
+ /* geographic position */
+ double glamt, glamu, glamv, glamf
+ /* geographic position */
+ double gphit, gphiu, gphiv, gphif
+ /* Coriolis parameter (if not on the sphere) */
+ double iff, ff_f, ff_t
+ /* horizontal scale factors */
+ double e1t, e1u, e1v, e1f
+ /* horizontal scale factors */
+ double e2t, e2u, e2v, e2f
+ /* U and V surfaces (if grid size reduction in some straits) */
+ double ie1e2u_v, e1e2u, e1e2v
+ /* reference vertical scale factors at T and W points */
+ double e3t_1d, e3w_1d
+ /* vertical scale factors 3D coordinate at T,U,V,F and W points */
+ double e3t_0, e3u_0, e3v_0, e3f_0, e3w_0
+ /* vertical scale factors 3D coordinate at UW and VW points */
+ double e3uw_0, e3vw_0
+ /* last wet T-points, 1st wet T-points (for ice shelf cavities) */
+ int bottom_level, top_level
+
+There are two options for creating a :file:`domain_cfg.nc` file:
+
+- Users can use tools of their own choice to build a :file:`domain_cfg.nc` with all mandatory fields.
+- Users can adapt and apply the supplied tool available in :file:`./tools/DOMAINcfg`.
+ This tool is based on code extracted from NEMO version 3.6 and will allow similar choices for
+ the horizontal and vertical grids that were available internally to that version.
+ See :ref:`tools <DOMAINcfg>` for details.
+
+Option 2: Adapt the usr_def configuration module of NEMO for you own purposes
+-----------------------------------------------------------------------------
+
+This method is intended for configuring easily simple/idealised configurations which
+are often used as demonstrators or for process evaluation and comparison.
+This method can be used whenever the domain geometry has a simple mathematical description and
+the ocean initial state and boundary forcing is described analytically.
+As a start, consider the case of starting a completely new ocean-only test case based on
+the ``LOCK_EXCHANGE`` example.
+
+.. note::
+
+ We probably need an even more basic example than this with only one namelist and
+ minimal changes to the usrdef modules
+
+Firstly, construct the directory structure, starting in the :file:`cfgs` directory:
+
+.. code-block:: console
+
+ $ ./makenemo -n 'MY_NEW_TEST' -t 'LOCK_EXCHANGE' -m 'my_arch'
+
+where the ``-t`` option has been used to locate the new configuration in
+the :file:`tests` subdirectory
+(it is recommended practice to keep full configurations and idealised cases clearly distinguishable).
+This command will create (amongst others) the following files and directories::
+
+ ./tests/MY_NEW_TEST:
+ BLD EXP00 MY_SRC WORK cpp_MY_NEW_TEST.fcm
+
+ ./tests/MY_NEW_TEST/EXP00:
+ context_nemo.xml domain_def_nemo.xml field_def_nemo-oce.xml file_def_nemo-oce.xml iodef.xml
+ namelist_cfg namelist_ref
+
+ ./tests/MY_NEW_TEST/MY_SRC:
+ usrdef_hgr.F90 usrdef_nam.F90 usrdef_zgr.F90 usrdef_istate.F90 usrdef_sbc.F90 zdfini.F90
+
+The key to setting up an idealised configuration lies in
+adapting a small set of short Fortran 90 modules which
+should be dropped into the :file:`MY_SRC` directory.
+Here the ``LOCK_EXCHANGE`` example is using 5 such routines but the full set that is available in
+the :file:`src/OCE/USR` directory is::
+
+ ./src/OCE/USR:
+ usrdef_closea.F90 usrdef_fmask.F90 usrdef_hgr.F90 usrdef_istate.F90
+ usrdef_nam.F90 usrdef_sbc.F90 usrdef_zgr.F90
+
+Before discussing these in more detail it is worth noting the various namelist controls that
+engage the different user-defined aspects.
+These controls are set using two new logical switches or are implied by the settings of existing ones.
+For example, the mandatory requirement for an idealised configuration is to provide routines which
+define the horizontal and vertical domains.
+Templates for these are provided in the :file:`usrdef_hgr.F90` and :file:`usrdef_zgr.F90` modules.
+The application of these modules is activated whenever:
+
+.. code-block:: fortran
+
+ ln_read_cfg = .false.
+
+in any configuration's :file:`namelist_cfg` file.
+This setting also activates the reading of an optional ``&nam_usrdef`` namelist which can be used to
+supply configuration specific settings.
+These need to be declared and read in the :file:`usrdef_nam.F90` module.
+
+Another explicit control is available in the ``&namsbc`` namelist which
+activates the use of analytical forcing.
+With
+
+.. code-block:: fortran
+
+ ln_usr = .true.
+
+Other usrdef modules are activated by less explicit means.
+For example, code in :file:`usrdef_istate.F90` is used to
+define initial temperature and salinity fields if
+
+.. code-block:: fortran
+
+ ln_tsd_init = .false.
+
+in the ``&namtsd`` namelist.
+The remaining modules, namely :file:`usrdef_closea.F90` :file:`usrdef_fmask.F90` are specific to
+ORCA configurations and set local variations of some specific fields for
+the various resolutions of the global models.
+They do not need to be considered here in the context of idealised cases but
+it is worth noting that all configuration specific code has now been isolated in the usrdef modules.
+In the case of these last two modules, they are activated only if an ORCA configuration is detected.
+Currently,
+this requires a specific integer variable named ``ORCA`` to be set in a :file:`domain_cfg.nc` file.
+
+.. note::
+
+ This would be less confusing if the ``cn_cfg`` string is read directly as
+ a character attribue from the :file:`domain_cfg.nc`.
+
+So, in most cases, the set up of idealised model configurations can be completed by
+copying the template routines from :file:`./src/OCE/USR` into
+your new :file:`./cfgs/MY_NEW_TEST/MY_SRC` directory and
+editing the appropriate modules as needed.
+The default set are those used for the GYRE reference configuration.
+The contents of :file:`MY_SRC` directories from other idealised configurations may provide
+more convenient templates if they share common characteristics with your target application.
+
+Whatever the starting point,
+it should not require too many changes or additional lines of code to produce routines in
+:file:`./src/OCE/USR` that define analytically the domain,
+the initial state and the surface boundary conditions for your new configuration.
+
+To summarize, the base set of modules is:
+
+:usrdef_hgr.F90: Define horizontal grid
+:usrdef_zgr.F90: Define vertical grid
+:usrdef_sbc.F90: Provides at each time-step the surface boundary condition,
+ i.e. the momentum, heat and freshwater fluxes
+:usrdef_istate.F90: Defines initialization of the dynamics and tracers
+:usrdef_nam.F90: Configuration-specific namelist processing to
+ set any associated run-time parameters
+
+with two specialised ORCA modules
+(not related to idealised configurations but used to isolate configuration specific code that
+is used in ORCA2 reference configurations and established global configurations using
+the ORCA tripolar grid):
+
+:usrdef_fmask.F90: only used in ORCA configurations for
+ alteration of f-point land/ocean mask in some straits
+:usrdef_closea.F90: only used in ORCA configurations for
+ specific treatments associated with closed seas
+
+From version 4.0, the NEMO release includes a :file:`tests` subdirectory containing available and
+up to date :doc:`test cases <tests>` build by the community.
+These will not be fully supported as are NEMO reference configurations,
+but should provide a source of raw material.
diff --git a/source/tests.bib b/source/tests.bib
new file mode 100644
index 0000000000000000000000000000000000000000..7b9856e8bf762dc9f27d41ab9846de1a70c6db00
--- /dev/null
+++ b/source/tests.bib
@@ -0,0 +1,115 @@
+
+@article{ brodeau.barnier.ea_JPO16,
+ title = "Climatologically Significant Effects of Some
+ Approximations in the Bulk Parameterizations of Turbulent
+ Air–Sea Fluxes",
+ pages = "5--28",
+ journal = "Journal of Physical Oceanography",
+ volume = "47",
+ number = "1",
+ author = "Brodeau, Laurent and Barnier, Bernard and Gulev, Sergey K.
+ and Woods, Cian",
+ year = "2016",
+ month = "Dec",
+ publisher = "American Meteorological Society",
+ issn = "1520-0485",
+ doi = "10.1175/jpo-d-16-0169.1"
+}
+
+@techreport{ burchard.bolding_trpt02,
+ title = "GETM, A General Estuarine Transport Model: Scientific
+ Documentation",
+ pages = "",
+ series = "Tech. Rep. EUR 20253 EN",
+ author = "Burchard, Hans and Bolding, Karsten",
+ institution = "European Commission",
+ year = "2002",
+ month = "01"
+}
+
+@article{ haidvogel.beckmann_SESM99,
+ title = "Numerical Ocean Circulation Modeling",
+ journal = "Series on Environmental Science and Management",
+ author = "Haidvogel, Dale B and Beckmann, Aike",
+ year = "1999",
+ month = "Apr",
+ publisher = "IMPERIAL COLLEGE PRESS",
+ issn = "0219-9793",
+ isbn = "9781860943935",
+ doi = "10.1142/p097"
+}
+
+@article{ ilıcak.adcroft.ea_OM12,
+ title = "Spurious dianeutral mixing and the role of momentum
+ closure",
+ pages = "37--58",
+ journal = "Ocean Modelling",
+ volume = "45-46",
+ author = "Ilıcak, Mehmet and Adcroft, Alistair J. and Griffies,
+ Stephen M. and Hallberg, Robert W.",
+ year = "2012",
+ month = "Jan",
+ publisher = "Elsevier BV",
+ issn = "1463-5003",
+ doi = "10.1016/j.ocemod.2011.10.003"
+}
+
+@article{ lipscomb.hunke_MWR04,
+ title = "Modeling Sea Ice Transport Using Incremental Remapping",
+ pages = "1341--1354",
+ journal = "Monthly Weather Review",
+ volume = "132",
+ number = "6",
+ author = "Lipscomb, William H. and Hunke, Elizabeth C.",
+ year = "2004",
+ month = "Jun",
+ publisher = "American Meteorological Society",
+ issn = "1520-0493",
+ doi = "10.1175/1520-0493(2004)132<1341:msitui>2.0.co;2"
+}
+
+@article{ losch_JGR08,
+ title = "Modeling ice shelf cavities in a z coordinate ocean
+ general circulation model",
+ journal = "Journal of Geophysical Research",
+ volume = "113",
+ number = "C8",
+ author = "Losch, M.",
+ year = "2008",
+ month = "Aug",
+ publisher = "American Geophysical Union (AGU)",
+ issn = "0148-0227",
+ doi = "10.1029/2007jc004368"
+}
+
+@article{ mathiot.jenkins.ea_GMD17,
+ title = "Explicit representation and parametrised impacts of under
+ ice shelf seas in the ${z}^{\ast}$ coordinate ocean model
+ NEMO 3.6",
+ pages = "2849--2874",
+ journal = "Geoscientific Model Development",
+ volume = "10",
+ number = "7",
+ author = "Mathiot, Pierre and Jenkins, Adrian and Harris,
+ Christopher and Madec, Gurvan",
+ year = "2017",
+ month = "Jul",
+ publisher = "Copernicus GmbH",
+ issn = "1991-9603",
+ doi = "10.5194/gmd-10-2849-2017"
+}
+
+@article{ schär.smolarkiewicz_JCP96,
+ title = "A Synchronous and Iterative Flux-Correction Formalism for
+ Coupled Transport Equations",
+ pages = "101--120",
+ journal = "Journal of Computational Physics",
+ volume = "128",
+ number = "1",
+ author = "Schär, Christoph and Smolarkiewicz, Piotr K.",
+ year = "1996",
+ month = "Oct",
+ publisher = "Elsevier BV",
+ issn = "0021-9991",
+ doi = "10.1006/jcph.1996.0198"
+}
diff --git a/source/tests.rst b/source/tests.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2b946dc1d58d65778830b7f30d5faa7b610d6120
--- /dev/null
+++ b/source/tests.rst
@@ -0,0 +1,272 @@
+**********************
+Explore the test cases
+**********************
+
+.. todo::
+
+ CANAL animated gif is missing
+
+.. contents::
+ :local:
+ :depth: 1
+
+Installation
+============
+
+Download
+--------
+
+| The complete and up-to-date set of test cases is available on
+ :github:`NEMO test cases repository <NEMO-examples>`.
+| Download it directly into the :file:`./tests` root directory with
+
+.. code-block:: console
+
+ $ git clone http://github.com/NEMO-ocean/NEMO-examples
+
+Compilation
+-----------
+
+The compilation of the test cases is very similar to
+the manner the reference configurations are compiled.
+If you are not familiar on how to compile NEMO,
+it is first recomended to read :doc:`the instructions <install>`.
+
+| As the reference configurations are compiled with ``-r`` option,
+ test cases can be compiled by the use of :file:`makenemo` with ``-a`` option.
+| Here an example to compile a copy named WAD2 of the wetting and drying test case (WAD):
+
+.. code-block:: console
+
+ $ ./makenemo -n 'WAD2' -a 'WAD' -m 'my_arch' -j '4'
+
+Run and analysis
+----------------
+
+There no requirement of specific input file for the test_cases presented here.
+The XIOS xml input files and namelist are already setup correctly.
+For detailed description and Jupyter notebook, the reader is directed on
+the :github:`NEMO test cases repository <NEMO-examples>`
+
+The description below is a brief advertisement of some test cases.
+
+List of test cases
+==================
+
+ICE_AGRIF
+---------
+
+.. figure:: _static/ICE_AGRIF_UDIAG_43days_UM5.gif
+ :width: 200px
+ :align: left
+
+ ..
+
+| This test case illustrates the advection of an ice patch across
+ an East/West and North/South periodic channel over a slab ocean (i.e. one ocean layer),
+ and with an AGRIF zoom (1:3) in the center.
+| The purpose of this configuration is to
+ test the advection of the ice patch in and across the AGRIF boundary.
+ One can either impose ice velocities or ice-atm.
+ Stresses and let rheology define velocities (see :file:`README` for details)
+
+VORTEX
+------
+
+.. figure:: _static/VORTEX_anim.gif
+ :width: 200px
+ :align: right
+
+ ..
+
+This test case illustrates the propagation of an anticyclonic eddy over a Beta plan and a flat bottom.
+It is implemented here with an online refined subdomain (1:3) out of which the vortex propagates.
+It serves as a benchmark for quantitative estimates of nesting errors as in :cite:`DEBREU2012`,
+:cite:`PENVEN2006` or :cite:`SPALL1991`.
+
+The animation (sea level anomaly in meters) illustrates with
+two 1:2 successively nested grids how the vortex smoothly propagates out of the refined grids.
+
+ISOMIP
+------
+
+.. figure:: _static/ISOMIP_moc.png
+ :width: 200px
+ :align: left
+
+ ..
+
+| The purpose of this test case is to evaluate the impact of various schemes and new development with
+ the iceshelf cavities circulation and melt.
+ This configuration served as initial assesment of the ice shelf module in :cite:`LOSCH2008` and
+ :cite:`MATHIOT2017`.
+ The default setup is the one described |ISOMIP|_.
+| The figure (meridional overturning circulation) illustrates
+ the circulation generated after 10000 days by the ice shelf melting (ice pump).
+
+.. |ISOMIP| replace:: here
+
+LOCK_EXCHANGE
+-------------
+
+.. figure:: _static/LOCK-FCT4_flux_ubs.gif
+ :width: 200px
+ :align: right
+
+ ..
+
+| The LOCK EXCHANGE experiment is a classical fluid dynamics experiment that has been adapted
+ by :cite:`HAIDVOGEL1999` for testing advection schemes in ocean circulation models.
+ It has been used by several authors including :cite:`BURCHARD2002` and :cite:`ILICAK2012`.
+ The LOCK EXCHANGE experiment can in particular illustrate
+ the impact of different choices of numerical schemes and/or subgrid closures on
+ spurious interior mixing.
+| Here the animation of the LOCK_EXCHANGE test case using
+ the advection scheme FCT4 (forth order) for tracer and ubs for dynamics.
+
+OVERFLOW
+--------
+
+.. figure:: _static/OVF-sco_FCT4_flux_cen-ahm1000.gif
+ :width: 200px
+ :align: left
+
+ ..
+
+| The OVERFLOW experiment illustrates the impact of different choices of numerical schemes and/or
+ subgrid closures on spurious interior mixing close to bottom topography.
+ The OVERFLOW experiment is adapted from the non-rotating overflow configuration described in
+ :cite:`HAIDVOGEL1999` and further used by :cite:`ILICAK2012`.
+ Here we can assess the behaviour of the second-order tracer advection scheme FCT2 and
+ forth-order FCT4, z-coordinate and sigma coordinate (...).
+| Here the animation of the OVERFLOW test case in sigma coordinate with
+ the forth-order advection scheme FCT4.
+
+WAD
+---
+
+.. figure:: _static/wad_testcase_7.gif
+ :width: 200px
+ :align: right
+
+ ..
+
+| 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.
+| Here the animation of the test case 7.
+ This test case is a simple linear slope with a mid-depth shelf with
+ an open boundary forced with a sinusoidally varying ssh.
+ This test case has been introduced to emulate a typical coastal application with
+ a tidally forced open boundary with an adverse SSH gradient that,
+ when released, creates a surge up the slope.
+ The parameters are chosen such that
+ the surge rises above sea-level before falling back and oscillating towards an equilibrium position.
+
+CANAL
+-----
+
+.. figure:: _static/CANAL_image.gif
+ :width: 200px
+ :align: left
+
+ ..
+
+East-west periodic canal of variable size with several initial states and
+associated geostrophic currents (zonal jets or vortex).
+
+ICE_ADV2D
+---------
+
+| This test case illustrates the advection of an ice patch across
+ an East/West and North/South periodic channel over a slab ocean (i.e. one ocean layer).
+ The configuration is similar to ICE_AGRIF, except for the AGRIF zoom.
+| The purpose of this configuration is to test the advection schemes available in the sea-ice code
+ (for now, Prather and Ultimate-Macho from 1st to 5th order),
+ especially the occurence of overshoots in ice thickness
+
+ICE_ADV1D
+---------
+
+| This experiment is the classical :cite:`SCHAR1996` test case ,
+ which has been used in :cite:`LIPSCOMB2004`, and in which very specific shapes of ice concentration,
+ thickness and volume converge toward the center of a basin.
+ Convergence is unidirectional (in x) while fields are homogeneous in y.
+| The purpose of this configuration is to
+ test the caracteristics of advection schemes available in the sea-ice code
+ (for now, Prather and Ultimate-Macho from 1st to 5th order),
+ especially the constitency between concentration, thickness and volume,
+ and the preservation of initial shapes.
+
+.. rubric:: References
+
+.. bibliography:: tests.bib
+ :all:
+ :style: unsrt
+ :labelprefix: T
+
+ICE_RHEO
+--------
+|
+
+BENCH
+-----
+| Benchmark configuration. Allow to run any configuration (including ORCA type or BDY) with idealized grid
+ and initial state so it does not need any input file other than the namelists.
+ As usual, all configuration changes can be done through the namelist.
+ We provide 3 example of namelist_cfg to mimic ORCA1, OR025 or ORCA12 configurations.
+ By default do not produce any output file. An extensive description of BENCH will be abailable in
+ Irrmann et al. 2021.
+
+CPL_OASIS
+---------
+| This test case checks the OASIS interface in OCE/SBC, allowing to set up
+ a coupled configuration through OASIS. See CPL_OASIS/README.md for more information.
+
+DIA_GPU
+---------
+| This is a demonstrator of diagnostic DIAHSB ported to GPU using CUDA Fortran.
+ Memory communications between host and device are asynchronous given the device has that capability.
+ This experiment is target for ORCA2_ICE_PISCES
+
+TSUNAMI
+---------
+| just use dynspg_ts to simulate the propagation of an ssh anomaly (cosinus) in a box configuration
+ with flat bottom and jpk=2.
+
+DONUT
+-----
+| Donut shaped configuration to test MPI decomposition with bdy.
+
+C1D_ASICS
+---------
+|
+
+DOME
+----
+|
+
+ICB
+----
+| ICB is a very idealized configuration used to test and debug the icb module.
+ The configuration is box with a shallow shelf (40m) on the east and west part of the domain
+ with a deep central trough (> 100m).
+ ICB are generating using the test capability of the icb model along a E-W line (this can easily be tuned).
+
+STATION_ASF
+-----------
+| this demonstration test case can be used to perform a sanity test of the SBCBLK interface of
+ NEMO. It will test all the bulk-parameterization algorithms using an idealized
+ forcing that includes a wide range of *SSX / surface atmospheric state*
+ conditions to detect potential error / inconsistencies. Both a short report and
+ boolean output: *passed* or *failed* is provided as an output.
+
+SWG
+---
+| Square bassin blown with an analytical wind. Vertical structure allows only one mode
+ associated with reduced gravity to develop. This configuration is based on Adcroft & Marshall 1998.
+ Also run with RK3 time stepping.
+
+ADIAB_WAVE
+----------
+| The purpose of this test case is to validate the implementation of the Generalized Lagrangian Mean equations for the coupling of NEMO with waves. This test case was first proposed by Ardhuin et al. (2008) and was successively detailed by Bennis et al (2011).
diff --git a/source/todos.rst b/source/todos.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1ac494828ae0d431fbabb103b4e805ad3689d22d
--- /dev/null
+++ b/source/todos.rst
@@ -0,0 +1,5 @@
+*********************
+List of editing tasks
+*********************
+
+.. todolist::
diff --git a/source/tools.rst b/source/tools.rst
new file mode 100644
index 0000000000000000000000000000000000000000..703a0d688306381c8ee22287f4f2e705924589a2
--- /dev/null
+++ b/source/tools.rst
@@ -0,0 +1,141 @@
+*****
+Tools
+*****
+
+.. todo::
+
+ The 'Tools' chapter needs to be enriched
+
+.. contents::
+ :local:
+ :depth: 1
+
+A set of tools is provided with NEMO to setup user own configuration and (pre|post)process data.
+
+How to compile a tool
+=====================
+
+The tool can be compiled using the maketools script in the tools directory as follows:
+
+.. code-block:: console
+
+ $ ./maketools -m 'my_arch' -n '<TOOL_NAME>'
+
+where ``my_arch`` can be selected among available architecture files or providing a user defined one.
+
+List of tools
+=============
+
+BDY_TOOLS
+---------
+
+It contains the utility *bdy_reorder* used to reorder old BDY data files used with
+previous versions of the model (before 3.4) to make them compatible with NEMO 3.4.
+
+DMP_TOOLS
+---------
+
+Used to create a netcdf file called :file:`resto.nc` containing
+restoration coefficients for use with the :file:`tra_dmp` module in NEMO
+(see :download:`DMP_TOOLS README <../../../tools/DMP_TOOLS/README>`).
+
+DOMAINcfg
+---------
+A toolbox allowing the creation of regional configurations from curvilinear grid
+(see :download:`DOMAINcfg README <../../../tools/DOMAINcfg/README.rst>`).
+
+GRIDGEN
+-------
+This tool allows the creation of a domain configuration file (``domain_cfg.nc``) containing
+the ocean domain information required to define an ocean configuration from scratch.
+(see :download:`GRIDGEN documentation <../../../tools/GRIDGEN/doc_cfg_tools.pdf>`).
+
+MISCELLANEOUS
+-------------
+
+The tool allows to create alternative configurations to the community without
+having to rely on system team sponsorship and support.
+
+MPP_PREP
+--------
+
+This tool provides the user with information to choose the best domain decomposition.
+The tool computes the number of water processors for all possible decompositions,
+up to a maximum number of processors
+(see :download:`MPP_PREP documentation <../../../tools/MPP_PREP/mpp_nc.pdf>` and
+:download:`MPP_PREP archive <../../../tools/MPP_PREP/mpp_prep-1.0.tar.gz>`).
+
+NESTING
+-------
+
+AGRIF nesting tool allows for the seamless two-way coupling of nested sub-models within
+the NEMO framework as long as these are defined on subsets of the original root grid.
+It allows to create the grid coordinates, the surface forcing and the initial conditions required by
+each sub-model when running a NEMO/AGRIF embedded mode
+(see :download:`NESTING README <../../../tools/NESTING/README>`).
+
+OBSTOOLS
+--------
+
+A series of Fortran utilities which are helpful in handling observation files and
+the feedback file output from the NEMO observation operator.
+Further info are available in the :doc:`Nemo manual <cite>`.
+
+REBUILD_NEMO
+------------
+
+REBUILD_NEMO is a tool to rebuild NEMO output files from multiple processors
+(mesh_mask, restart or XIOS output files) into one file
+(see :download:`REBUILD_NEMO README <../../../tools/REBUILD_NEMO/README.rst>`).
+
+REBUILD
+-------
+
+It contains the old version of REBUILD_NEMO tool based on the IOIPSL code.
+
+SCOORD_GEN
+----------
+
+Offline tool to generate a vertical coordinates input file for use with S coordinates.
+This has been carried out by copying the model code to an offline tool and then
+modifying it to suppress the use of 3D arrays (to reduce memory usage).
+The tool has been created in preparation for the removal of the vertical grid definition from
+the code.
+The output file should contain all variables that are necessary to restart the model.
+
+SECTIONS_DIADCT
+---------------
+
+When the Transport across sections diagnostic is activated (``key_diadct``),
+this tool is used to build the binary file containing the pathways between
+the extremities of each section.
+Further info are available in the :doc:`Nemo manual <cite>`.
+
+SIREN
+-----
+
+SIREN is a configuration management tool to set up regional configurations with NEMO
+(see :download:`SIREN README <../../../tools/SIREN/README>`).
+
+WEIGHTS
+-------
+
+This directory contains software for generating and manipulating interpolation weights for use with
+the Interpolation On the Fly (IOF) option in NEMO v3 onwards
+(see :download:`WEIGHTS README <../../../tools/WEIGHTS/README>`).
+
+TOYATM
+------
+
+This directory contains a simplified model that send/receive atmospheric fields to/from NEMO, for use in the CPL_OASIS sed to test case of the NEMO-OASIS coupling interface.
+This toy requires OASIS3-MCT to be installed and properly defined in the arch file.
+(see :download:`CPL_OASIS README <../../../tests/CPL_OASIS/README.md>`).
+
+ABL_TOOLS
+---------
+
+3 steps to generate atmospheric forcings from ECMWF products for ABL1d model with NEMO:
+- main_uvg_hpg (optional): geostrophic wind or horizontal pressure gradient computation on ECMWF eta-levels (to force ABL dynamics)
+- main_vinterp: vertical interpolation from ECWMF vertical eta-levels to ABL Z-levels
+- main_hdrown: 3D-fields horizontal drowning (extrapolation over land totally inspired from SOSIE by L. Brodeau)
+(more details available in Lemarie et al. 2020 GMD)
diff --git a/source/tracers.rst b/source/tracers.rst
new file mode 100644
index 0000000000000000000000000000000000000000..65b1ac39dcb338fcb7e90b90dbbd9774ca838da6
--- /dev/null
+++ b/source/tracers.rst
@@ -0,0 +1,392 @@
+***************
+Oceanic tracers
+***************
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+TOP (Tracers in the Ocean Paradigm) is the NEMO hardwired interface toward
+biogeochemical models and provide the physical constraints/boundaries for oceanic tracers.
+It consists of a modular framework to handle multiple ocean tracers,
+including also a variety of built-in modules.
+
+This component of the NEMO framework allows one to exploit available modules (see below) and
+further develop a range of applications, spanning from the implementation of a dye passive tracer to
+evaluate dispersion processes (by means of MY_TRC), track water masses age (AGE module),
+assess the ocean interior penetration of persistent chemical compounds
+(e.g., gases like CFC or even PCBs), up to the full set of equations involving
+marine biogeochemical cycles.
+
+Structure
+=========
+
+TOP interface has the following location in the source code :file:`./src/TOP` and
+the following modules are available:
+
+:file:`TRP`
+ Interface to NEMO physical core for computing tracers transport
+
+:file:`CFC`
+ Inert carbon tracers (CFC11,CFC12,SF6)
+
+:file:`C14`
+ Radiocarbon passive tracer
+
+:file:`AGE`
+ Water age tracking
+
+:file:`MY_TRC`
+ Template for creation of new modules and external BGC models coupling
+
+:file:`PISCES`
+ Built in BGC model. See :cite:`gmd-8-2465-2015` for a throughout description.
+
+The usage of TOP is activated
+*i)* by including in the configuration definition the component ``TOP`` and
+*ii)* by adding the macro ``key_top`` in the configuration CPP file
+(see for more details :forge:`"Learn more about the model" <wiki/Users>`).
+
+As an example, the user can refer to already available configurations in the code,
+``GYRE_PISCES`` being the NEMO biogeochemical demonstrator and
+``GYRE_BFM`` to see the required configuration elements to couple with an external biogeochemical model
+(see also Section 4) .
+
+Note that, since version 4.0,
+TOP interface core functionalities are activated by means of logical keys and
+all submodules preprocessing macros from previous versions were removed.
+
+Here below the list of preprocessing keys that applies to the TOP interface (beside ``key_top``):
+
+``key_xios``
+ use XIOS I/O
+
+``key_agrif``
+ enable AGRIF coupling
+
+``key_trdtrc`` & ``key_trdmxl_trc``
+ trend computation for tracers
+
+Synthetic Workflow
+==================
+
+A synthetic description of the TOP interface workflow is given below to
+summarize the steps involved in the computation of biogeochemical and physical trends and
+their time integration and outputs,
+by reporting also the principal Fortran subroutine herein involved.
+
+Model initialization (:file:`./src/OCE/nemogcm.F90`)
+----------------------------------------------------
+
+Call to ``trc_init`` subroutine (:file:`./src/TOP/trcini.F90`) to initialize TOP.
+
+.. literalinclude:: ../../../src/TOP/trcini.F90
+ :language: fortran
+ :lines: 41-86
+ :emphasize-lines: 21,30-32,38-40
+ :caption: ``trc_init`` subroutine
+
+Time marching procedure (:file:`./src/OCE/step.F90`)
+----------------------------------------------------
+
+Call to ``trc_stp`` subroutine (:file:`./src/TOP/trcstp.F90`) to compute/update passive tracers.
+
+.. literalinclude:: ../../../src/TOP/trcstp.F90
+ :language: fortran
+ :lines: 46-125
+ :emphasize-lines: 42,55-57
+ :caption: ``trc_stp`` subroutine
+
+BGC trends computation for each submodule (:file:`./src/TOP/trcsms.F90`)
+------------------------------------------------------------------------
+
+.. literalinclude:: ../../../src/TOP/trcsms.F90
+ :language: fortran
+ :lines: 21
+ :caption: :file:`trcsms` snippet
+
+Physical trends computation (:file:`./src/TOP/TRP/trctrp.F90`)
+--------------------------------------------------------------
+
+.. literalinclude:: ../../../src/TOP/TRP/trctrp.F90
+ :language: fortran
+ :lines: 46-95
+ :emphasize-lines: 17,21,29,33-35
+ :caption: ``trc_trp`` subroutine
+
+Namelists walkthrough
+=====================
+
+:file:`namelist_top`
+--------------------
+
+Here below are listed the features/options of the TOP interface accessible through
+the :file:`namelist_top_ref` and modifiable by means of :file:`namelist_top_cfg`
+(as for NEMO physical ones).
+
+Note that ``##`` is used to refer to a number in an array field.
+
+.. literalinclude:: ../../namelists/namtrc_run
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_dta
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_adv
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_ldf
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_rad
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_snk
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_dmp
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_ice
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_trd
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_bc
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namtrc_bdy
+ :language: fortran
+
+.. literalinclude:: ../../namelists/namage
+ :language: fortran
+
+Two main types of data structure are used within TOP interface
+to initialize tracer properties (1) and
+to provide related initial and boundary conditions (2).
+
+1. TOP tracers initialization: ``sn_tracer`` (``&namtrc``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Beside providing name and metadata for tracers,
+here are also defined the use of initial (``sn_tracer%llinit``) and
+boundary (``sn_tracer%llsbc, sn_tracer%llcbc, sn_tracer%llobc``) conditions.
+
+In the following, an example of the full structure definition is given for
+two idealized tracers both with initial conditions given,
+while the first has only surface boundary forcing and
+the second both surface and coastal forcings:
+
+.. code-block:: fortran
+
+ ! ! name ! title of the field ! units ! initial data ! sbc ! cbc ! obc !
+ sn_tracer(1) = 'TRC1' , 'Tracer 1 Concentration ', ' - ' , .true. , .true., .false., .true.
+ sn_tracer(2) = 'TRC2 ' , 'Tracer 2 Concentration ', ' - ' , .true. , .true., .true. , .false.
+
+As tracers in BGC models are increasingly growing,
+the same structure can be written also in a more compact and readable way:
+
+.. code-block:: fortran
+
+ ! ! name ! title of the field ! units ! initial data !
+ sn_tracer(1) = 'TRC1' , 'Tracer 1 Concentration ', ' - ' , .true.
+ sn_tracer(2) = 'TRC2 ' , 'Tracer 2 Concentration ', ' - ' , .true.
+ ! sbc
+ sn_tracer(1)%llsbc = .true.
+ sn_tracer(2)%llsbc = .true.
+ ! cbc
+ sn_tracer(2)%llcbc = .true.
+
+The data structure is internally initialized by code with dummy names and
+all initialization/forcing logical fields set to ``.false.`` .
+
+2. Structures to read input initial and boundary conditions: ``&namtrc_dta`` (``sn_trcdta``), ``&namtrc_bc`` (``sn_trcsbc`` / ``sn_trccbc`` / ``sn_trcobc``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The overall data structure (Fortran type) is based on the general one defined for NEMO core in the SBC component
+(see details in ``SBC`` Chapter of :doc:`Reference Manual <cite>` on Input Data specification).
+
+Input fields are prescribed within ``&namtrc_dta`` (with ``sn_trcdta`` structure),
+while Boundary Conditions are applied to the model by means of ``&namtrc_bc``,
+with dedicated structure fields for surface (``sn_trcsbc``), riverine (``sn_trccbc``), and
+lateral open (``sn_trcobc``) boundaries.
+
+The following example illustrates the data structure in the case of initial condition for
+a single tracer contained in the file named :file:`tracer_1_data.nc`
+(``.nc`` is implicitly assumed in namelist filename),
+with a doubled initial value, and located in the :file:`usr/work/model/inputdata` folder:
+
+.. code-block:: fortran
+
+ ! ! file name ! frequency (hours) ! variable ! time interp. ! clim ! 'yearly'/ ! weights ! rotation ! land/sea mask !
+ ! ! ! (if <0 months) ! name ! (logical) ! (T/F) ! 'monthly' ! filename ! pairing ! filename !
+ sn_trcdta(1) = 'tracer_1_data' , -12 , 'TRC1' , .false. , .true. , 'yearly' , '' , '' , ''
+ rf_trfac(1) = 2.0
+ cn_dir = 'usr/work/model/inputdata/'
+
+Note that, the Lateral Open Boundaries conditions are applied on
+the segments defined for the physical core of NEMO
+(see ``BDY`` description in the :doc:`Reference Manual <cite>`).
+
+:file:`namelist_trc`
+--------------------
+
+Here below the description of :file:`namelist_trc_ref` used to handle Carbon tracers modules,
+namely CFC and C14.
+
+.. literalinclude:: ../../../cfgs/SHARED/namelist_trc_ref
+ :language: fortran
+ :lines: 7,17,26,34
+ :caption: :file:`namelist_trc_ref` snippet
+
+``MY_TRC`` interface for coupling external BGC models
+=====================================================
+
+The generalized interface is pivoted on MY_TRC module that contains template files to
+build the coupling between
+NEMO and any external BGC model.
+
+The call to MY_TRC is activated by setting ``ln_my_trc = .true.`` (in ``&namtrc``)
+
+The following 6 fortran files are available in MY_TRC with the specific purposes here described.
+
+:file:`par_my_trc.F90`
+ This module allows to define additional arrays and public variables to
+ be used within the MY_TRC interface
+
+:file:`trcini_my_trc.F90`
+ Here are initialized user defined namelists and
+ the call to the external BGC model initialization procedures to populate general tracer array
+ (``trn`` and ``trb``).
+ Here are also likely to be defined support arrays related to system metrics that
+ could be needed by the BGC model.
+
+:file:`trcnam_my_trc.F90`
+ This routine is called at the beginning of ``trcini_my_trc`` and
+ should contain the initialization of additional namelists for the BGC model or user-defined code.
+
+:file:`trcsms_my_trc.F90`
+ The routine performs the call to Boundary Conditions and its main purpose is to
+ contain the Source-Minus-Sinks terms due to the biogeochemical processes of the external model.
+ Be aware that lateral boundary conditions are applied in trcnxt routine.
+
+ .. warning::
+ The routines to compute the light penetration along the water column and
+ the tracer vertical sinking should be defined/called in here,
+ as generalized modules are still missing in the code.
+
+:file:`trcice_my_trc.F90`
+ Here it is possible to prescribe the tracers concentrations in the sea-ice that
+ will be used as boundary conditions when ice melting occurs (``nn_ice_tr = 1`` in ``&namtrc_ice``).
+ See e.g. the correspondent PISCES subroutine.
+
+:file:`trcwri_my_trc.F90`
+ This routine performs the output of the model tracers (only those defined in ``&namtrc``) using
+ IOM module (see chapter “Output and Diagnostics†in the :doc:`Reference Manual <cite>`).
+ It is possible to place here the output of additional variables produced by the model,
+ if not done elsewhere in the code, using the call to ``iom_put``.
+
+Coupling an external BGC model using NEMO framework
+===================================================
+
+The coupling with an external BGC model through the NEMO compilation framework can be achieved in
+different ways according to the degree of coding complexity of the Biogeochemical model, like e.g.,
+the whole code is made only by one file or
+it has multiple modules and interfaces spread across several subfolders.
+
+Beside the 6 core files of MY_TRC module, let’s assume an external BGC model named *MYBGC* and
+constituted by a rather essential coding structure, likely few Fortran files.
+The new coupled configuration name is *NEMO_MYBGC*.
+
+The best solution is to have all files (the modified ``MY_TRC`` routines and the BGC model ones)
+placed in a unique folder with root ``MYBGCPATH`` and
+to use the makenemo external readdressing of ``MY_SRC`` folder.
+
+The coupled configuration listed in :file:`work_cfgs.txt` will look like
+
+::
+
+ NEMO_MYBGC OCE TOP
+
+and the related ``cpp_MYBGC.fcm`` content will be
+
+.. code-block:: perl
+
+ bld::tool::fppkeys key_xios key_top
+
+the compilation with :file:`makenemo` will be executed through the following syntax
+
+.. code-block:: console
+
+ $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>'
+
+The makenemo feature ``-e`` was introduced to
+readdress at compilation time the standard MY_SRC folder (usually found in NEMO configurations) with
+a user defined external one.
+
+The compilation of more articulated BGC model code & infrastructure,
+like in the case of BFM (|BFM man|_), requires some additional features.
+
+As before, let’s assume a coupled configuration name *NEMO_MYBGC*,
+but in this case MYBGC model root becomes :file:`MYBGC` path that
+contains 4 different subfolders for biogeochemistry,
+named :file:`initialization`, :file:`pelagic`, and :file:`benthic`,
+and a separate one named :file:`nemo_coupling` including the modified `MY_SRC` routines.
+The latter folder containing the modified NEMO coupling interface will be still linked using
+the makenemo ``-e`` option.
+
+In order to include the BGC model subfolders in the compilation of NEMO code,
+it 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
+
+.. code-block:: perl
+
+ bld::tool::fppkeys key_xios key_top
+
+ src::MYBGC::initialization <MYBGCPATH>/initialization
+ src::MYBGC::pelagic <MYBGCPATH>/pelagic
+ src::MYBGC::benthic <MYBGCPATH>/benthic
+
+ bld::pp::MYBGC 1
+ bld::tool::fppflags::MYBGC %FPPFLAGS
+ bld::tool::fppkeys %bld::tool::fppkeys MYBGC_MACROS
+
+where *MYBGC_MACROS* is the space delimited list of macros used in *MYBGC* model for
+selecting/excluding specific parts of the code.
+The BGC model code will be preprocessed in the configuration :file:`BLD` folder as for NEMO,
+but with an independent path, like :file:`NEMO_MYBGC/BLD/MYBGC/<subforlders>`.
+
+The compilation will be performed similarly to in the previous case with the following
+
+.. code-block:: console
+
+ $ makenemo -n 'NEMO_MYBGC' -m '<arch_my_machine>' -j 8 -e '<MYBGCPATH>/nemo_coupling'
+
+.. note::
+ The additional lines specific for the BGC model source and build paths can be written into
+ a separate file, e.g. named :file:`MYBGC.fcm`,
+ and then simply included in the :file:`cpp_NEMO_MYBGC.fcm` as follow
+
+ .. code-block:: perl
+
+ bld::tool::fppkeys key_xios key_top
+ inc <MYBGCPATH>/MYBGC.fcm
+
+ This will enable a more portable compilation structure for all MYBGC related configurations.
+
+.. warning::
+ The coupling interface contained in :file:`nemo_coupling` cannot be added using the FCM syntax,
+ as the same files already exists in NEMO and they are overridden only with
+ the readdressing of MY_SRC contents to avoid compilation conflicts due to duplicate routines.
+
+All modifications illustrated above, can be easily implemented using shell or python scripting
+to edit the NEMO configuration :file:`CPP.fcm` file and
+to create the BGC model specific FCM compilation file with code paths.
+
+.. |BFM man| replace:: BFM-NEMO coupling manual
diff --git a/source/unpub/crs.rst b/source/unpub/crs.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8633dbeb339fd6d61d4f191a6d453c7936d430f8
--- /dev/null
+++ b/source/unpub/crs.rst
@@ -0,0 +1,153 @@
+**********************************
+On line biogeochemistry coarsening
+**********************************
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+Presentation
+============
+
+A capacity of coarsening physics to force a BGC model coupled to NEMO has been developed.
+This capacity allow to run 'online' a BGC model coupled to OCE-SI3 with a lower resolution,
+to reduce the CPU cost of the BGC model, while preserving the effective resolution of the dynamics.
+
+A presentation is available [attachment:crs_wiki_1.1.pdf​ here], where the methodology is presented.
+
+What is available and working for now in this version
+=====================================================
+
+[To be completed]
+
+Description of the successful validation tests
+==============================================
+
+[To be completed]
+
+What is not working yet with on line coarsening of biogeochemistry
+==================================================================
+
+[To be completed]
+
+''should include precise explanation on MPI decomposition problems too''
+
+How to set up and use on line biogeochemistry
+=============================================
+
+Extract the on line biogeochemistry branch
+------------------------------------------
+
+To get the appropriate source code with the on line coarsening of biogeochemistry feature:
+
+.. code-block:: console
+
+ $ svn co https://forge.ipsl.jussieu.fr/nemo/browser/NEMO/branches/2018/dev_r5003_MERCATOR6_CRS
+
+
+How to activate coarsening?
+---------------------------
+
+To activate the coarsening, ``key_crs`` should be added to list of CPP keys.
+This key will only activate the coarsening of dynamics.
+
+Some parameters are available in the namelist_cfg:
+
+.. code-block:: fortran
+
+ ! passive tracer coarsened online simulations
+ !-----------------------------------------------------------------------
+ nn_factx = 3 ! Reduction factor of x-direction
+ nn_facty = 3 ! Reduction factor of y-direction
+ nn_msh_crs = 0 ! create (=1) a mesh file or not (=0)
+ nn_crs_kz = 3 ! 0, volume-weighted MEAN of KZ
+ ! 1, MAX of KZ
+ ! 2, MIN of KZ
+ ! 3, 10^(MEAN(LOG(KZ))
+ ! 4, MEDIANE of KZ
+ ln_crs_wn = .false. ! wn coarsened (T) or computed using horizontal divergence ( F )
+ ! !
+ ln_crs_top = .true. !coarsening online for the bio
+ /
+
+- Only ``nn_factx = 3`` is available and the coarsening only works for grids with a T-pivot point for
+ the north-fold lateral boundary condition (ORCA025, ORCA12, ORCA36, ...).
+- ``nn_msh_crs = 1`` will activate the generation of the coarsened grid meshmask.
+- ``nn_crs_kz`` is the operator to coarsen the vertical mixing coefficient.
+- ``ln_crs_wn``
+
+ - when ``key_vvl`` is activated, this logical has no effect;
+ the coarsened vertical velocities are computed using horizontal divergence.
+ - when ``key_vvl`` is not activated,
+
+ - coarsened vertical velocities are computed using horizontal divergence (``ln_crs_wn = .false.``)
+ - or coarsened vertical velocities are computed with an average operator (``ln_crs_wn = .true.``)
+- ``ln_crs_top = .true.``: should be activated to run BCG model in coarsened space;
+ so only works when ``key_top`` is in the cpp list and eventually ``key_pisces`` or ``key_my_trc``.
+
+Choice of operator to coarsene KZ
+---------------------------------
+
+A sensiblity test has been done with an Age tracer to compare the different operators.
+The 3 and 4 options seems to provide the best results.
+
+Some results can be found [xxx here]
+
+Example of xml files to output coarsened variables with XIOS
+------------------------------------------------------------
+
+In the [attachment:iodef.xml iodef.xml] file, a "nemo" context is defined and
+some variable defined in [attachment:file_def.xml file_def.xml] are writted on the ocean-dynamic grid.
+To write variables on the coarsened grid, and in particular the passive tracers,
+a "nemo_crs" context should be defined in [attachment:iodef.xml iodef.xml] and
+the associated variable are listed in [attachment:file_crs_def.xml file_crs_def.xml ].
+
+Passive tracers tracers initial conditions
+------------------------------------------
+
+When initial conditions are provided in NetCDF files, the field might be:
+
+- on the coarsened grid
+- or they can be on another grid and
+ interpolated `on-the-fly <http://forge.ipsl.jussieu.fr/nemo/wiki/Users/SetupNewConfiguration/Weight-creator>`_.
+ Example of namelist for PISCES :
+
+ .. code-block:: fortran
+
+ !-----------------------------------------------------------------------
+ &namtrc_dta ! Initialisation from data input file
+ !-----------------------------------------------------------------------
+ !
+ sn_trcdta(1) = 'DIC_REG1' , -12 , 'DIC' , .false. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(2) = 'ALK_REG1' , -12 , 'ALK' , .false. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(3) = 'O2_REG1' , -1 , 'O2' , .true. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(5) = 'PO4_REG1' , -1 , 'PO4' , .true. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(7) = 'Si_REG1' , -1 , 'Si' , .true. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(10) = 'DOC_REG1' , -12 , 'DOC' , .false. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(14) = 'Fe_REG1' , -12 , 'Fe' , .false. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ sn_trcdta(23) = 'NO3_REG1' , -1 , 'NO3' , .true. , .true. , 'yearly' , 'reshape_REG1toeORCA075_bilin.nc' , '' , ''
+ rn_trfac(1) = 1.0e-06 ! multiplicative factor
+ rn_trfac(2) = 1.0e-06 ! - - - -
+ rn_trfac(3) = 44.6e-06 ! - - - -
+ rn_trfac(5) = 122.0e-06 ! - - - -
+ rn_trfac(7) = 1.0e-06 ! - - - -
+ rn_trfac(10) = 1.0e-06 ! - - - -
+ rn_trfac(14) = 1.0e-06 ! - - - -
+ rn_trfac(23) = 7.6e-06 ! - - - -
+
+ cn_dir = './' ! root directory for the location of the data files
+
+PISCES forcing files
+--------------------
+
+They might be on the coarsened grid.
+
+Perspectives
+============
+
+For the future, a few options are on the table to implement coarsening for biogeochemistry in 4.0 and
+future releases.
+Those will be discussed in Autumn 2018
diff --git a/source/unpub/doc.rst b/source/unpub/doc.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7e722505b3d2842f5aab0cfa07acb6acb37d042f
--- /dev/null
+++ b/source/unpub/doc.rst
@@ -0,0 +1,130 @@
+**Contents**
+
+.. contents::
+ :local:
+
+
+
+
+.. _`Former web platform forge`: https://forge.ipsl.jussieu.fr/nemo
+.. _`NEMO users' guide`: https://sites.nemo-ocean.io/user-guide
+.. _`Migration Guide`: https://sites.nemo-ocean.io/user-guide/migration.html
+.. _`Change list`: https://sites.nemo-ocean.io/user-guide/changes.html
+.. _`Test case repository`: https://github.com/NEMO-ocean/NEMO-examples
+.. _`How to cite`: https://www.nemo-ocean.eu/bibliography/how-to-cite/
+.. _`NEMO forums`: https://nemo-ocean.discourse.group
+.. _`NEMO newsletter`: https://listes.ipsl.fr/sympa/subscribe/nemo-newsletter
+.. _`NEMO publications`: https://www.nemo-ocean.eu/bibliography/publications/add
+.. _`NEMO projects`: https://www.nemo-ocean.eu/projects/add
+.. _`Special Issue`: https://gmd.copernicus.org/articles/special_issue40.html
+.. _`NEMO System Team wiki`: https://forge.nemo-ocean.eu/developers/home/-/wikis/Home
+.. _`NEMO ocean engine`: https://zenodo.org/record/1464816
+.. _`NEMO Tracers engine` : https://zenodo.org/record/1471700
+.. _`NEMO Sea Ice engine`: https://zenodo.org/record/1471689
+
+
+**Welcome to NEMO home page!**
+
+NEMO (*Nucleus for European Modelling of the Ocean*) is a state-of-the-art modelling
+framework for research activities and forecasting services in ocean and climate sciences,
+developed in a sustainable way by the NEMO European consortium since 2008.
+
+This page intends to help you to get started using the NEMO platform and to introduce you
+to the different levels of information available. It starts here with NEMO release 4.2.0.
+
+Reminder: Our `Former web platform forge`_ (SVN+Trac) contains the previous documentation
+and releases made available from the beginning of the project up to of NEMO 4.0.
+
+Getting started
+===============
+
+Getting your hands on NEMO: the first steps are described in detail in the
+`NEMO users' guide`_ . This explains how to download the code, build the environment,
+create the executable, and perform a first integration.
+
+If you are already using a previous release of NEMO, please refer to the
+`Migration Guide`_ which aims to help you to make the move to 4.2.0.
+
+The above users guides cover in detail what is available from gitlab and supported by NEMO
+System Team. Aside from this web platform, a set of test cases is also available from the
+`Test case repository`_ . These test cases can be useful for students, outreach, and
+exploring specific aspects of NEMO with light configurations. The web page also allows you
+to submit test cases you have developed and want to share with the community. Feel free to
+contribute!
+
+
+Project documentation
+=====================
+
+Reference manuals fully describing NEMO for the three main component
+
+* |OCE| models the ocean {thermo}dynamics and solves the primitive equations (`./src/OCE <./src/OCE>`_)
+
+* |ICE| simulates sea-ice {thermo}dynamics, brine inclusions and subgrid-scale thickness
+ variations (`./src/ICE <./src/ICE>`_)
+
+* |MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes
+ (`./src/TOP <./src/TOP>`_)
+are available from Zenodo:
+
+============ ======================== =====
+ Component Reference Manual DOI
+============ ======================== =====
+ |NEMO-OCE| `NEMO ocean engine`_ .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.6334656.svg
+ :target: https://doi.org/10.5281/zenodo.6334656
+ |NEMO-ICE| `NEMO Sea Ice engine`_ *not yet available*
+ |NEMO-MBG| `NEMO Tracers engine`_ .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471700.svg
+ :target: https://doi.org/10.5281/zenodo.1471700
+============ ======================== =====
+
+These reference manuals are the publications that should be cited in your own
+publications. Please visit `How to cite`_? for details.
+
+New features of 4.2.0 release are described in the `Change list`_ section of the `NEMO users' guide`_
+
+
+Asking questions, and exchanging information
+============================================
+- Register once for all and use the `NEMO forums`_ on discourse to share and discuss with the NEMO community.
+
+- Register once for all and receive by mail the `NEMO newsletter`_ : recommended for all
+ users to receive the major announcements from the project (new releases, open meetings and
+ main informations). Low traffic: about ten messages a year.
+
+
+Contributing to NEMO visibility: projects and publications
+==========================================================
+Please help us justifying the NEMO development efforts by
+
+- Adding your publications using NEMO and its outputs to the `NEMO publications`_ page
+
+- Describing your project using NEMO on the `NEMO projects`_ page
+
+NEMO also has a `Special Issue`_ in the open-access journal
+Geoscientific Model Development (GMD) from the European Geosciences Union
+The main scope is to collect relevant manuscripts covering various topics and
+to provide a single portal to assess the model potential and evolution.
+
+
+
+Contributing to NEMO development
+================================
+
+NEMO strives to be written in a way which allows the easy incorporation of developments.
+You are welcome to contribute to the development of the NEMO Shared reference. NEMO
+development is driven by NEMO Consortium planning and producing NEMO's sustainable
+development in order to keep a reliable evolving framework. Development is organised and
+scheduled through a five years development strategy, Working groups and the activities of
+the development team (named NEMO System Team) in a yearly workplan. More information is
+available on the `NEMO System Team wiki`_
+
+
+Disclaimer
+==========
+
+The NEMO source code is freely available and distributed under
+`CeCILL v2.0 license <./LICENSE>`_ (GNU GPL compatible).
+
+You can use, modify and/or redistribute the software under its terms,
+but users are provided only with a limited warranty and the software's authors and
+the successive licensor's have only limited liability.
diff --git a/source/unpub/src.rst b/source/unpub/src.rst
new file mode 100644
index 0000000000000000000000000000000000000000..4ea8114d03b3688ffee7fdda1f82a76942756356
--- /dev/null
+++ b/source/unpub/src.rst
@@ -0,0 +1,15 @@
+*******
+Sources
+*******
+
+.. todo::
+
+
+
+:file:`ICE`: |NEMO-ICE|
+
+:file:`NST`: AGRIF for embedded zooms
+
+:file:`OCE`: |NEMO-OCE|
+
+:file:`TOP`: |NEMO-MBG|
diff --git a/source/zooms.bib b/source/zooms.bib
new file mode 100644
index 0000000000000000000000000000000000000000..2071f4e1fe7ee1dab155c5d98d5fca7f0a5503d9
--- /dev/null
+++ b/source/zooms.bib
@@ -0,0 +1,46 @@
+
+@article{ debreu.marchesiello.ea_OM12,
+ title = "Two-way nesting in split-explicit ocean models:
+ Algorithms, implementation and validation",
+ pages = "1--21",
+ journal = "Ocean Modelling",
+ volume = "49-50",
+ author = "Debreu, Laurent and Marchesiello, Patrick and Penven,
+ Pierrick and Cambon, Gildas",
+ year = "2012",
+ month = "Jun",
+ publisher = "Elsevier BV",
+ issn = "1463-5003",
+ doi = "10.1016/j.ocemod.2012.03.003"
+}
+
+@article{ penven.debreu.ea_OM06,
+ title = "Evaluation and application of the ROMS 1-way embedding
+ procedure to the central california upwelling system",
+ pages = "157--187",
+ journal = "Ocean Modelling",
+ volume = "12",
+ number = "1-2",
+ author = "Penven, Pierrick and Debreu, Laurent and Marchesiello,
+ Patrick and McWilliams, James C.",
+ year = "2006",
+ month = "Jan",
+ publisher = "Elsevier BV",
+ issn = "1463-5003",
+ doi = "10.1016/j.ocemod.2005.05.002"
+}
+
+@article{ spall.holland_JPO91,
+ title = "A Nested Primitive Equation Model for Oceanic
+ Applications",
+ pages = "205--220",
+ journal = "Journal of Physical Oceanography",
+ volume = "21",
+ number = "2",
+ author = "Spall, Michael A. and Holland, William R.",
+ year = "1991",
+ month = "Feb",
+ publisher = "American Meteorological Society",
+ issn = "1520-0485",
+ doi = "10.1175/1520-0485(1991)021<0205:anpemf>2.0.co;2"
+}
diff --git a/source/zooms.rst b/source/zooms.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2d5469dfb2c7c738ca4d2d23453525e8dfb493bd
--- /dev/null
+++ b/source/zooms.rst
@@ -0,0 +1,106 @@
+**************
+Embedded zooms
+**************
+
+.. todo::
+
+
+
+.. contents::
+ :local:
+
+Overview
+========
+
+AGRIF (Adaptive Grid Refinement In Fortran) is a library that
+allows the seamless space and time refinement over rectangular regions in NEMO.
+Refinement factors can be odd or even (usually lower than 5 to maintain stability).
+Interaction between grid is "two-ways" in the sense that
+the parent grid feeds the child grid open boundaries and
+the child grid provides volume averages of prognostic variables once
+a given number of time step is completed.
+These pages provide guidelines how to use AGRIF in NEMO.
+For a more technical description of the library itself, please refer to AGRIF_.
+
+Compilation
+===========
+
+Activating AGRIF requires to append the cpp key ``key_agrif`` at compilation time:
+
+.. code-block:: sh
+
+ ./makenemo [...] add_key 'key_agrif'
+
+Although this is transparent to users,
+the way the code is processed during compilation is different from the standard case:
+a preprocessing stage (the so called ``conv`` program) translates the actual code so that
+saved arrays may be switched in memory space from one domain to an other.
+
+Definition of the grid hierarchy
+================================
+
+An additional text file :file:`AGRIF_FixedGrids.in` is required at run time.
+This is where the grid hierarchy is defined.
+An example of such a file, here taken from the ``ICEDYN`` test case, is given below
+
+.. literalinclude:: ../../../tests/ICE_AGRIF/EXPREF/AGRIF_FixedGrids.in
+
+The first line indicates the number of zooms (1).
+The second line contains the starting and ending indices in both directions on the root grid
+(``imin=34 imax=63 jmin=34 jmax=63``) followed by the space and time refinement factors (3 3 3).
+The last line is the number of child grid nested in the refined region (0).
+A more complex example with telescoping grids can be found below and
+in the :file:`AGRIF_DEMO` reference configuration directory.
+
+.. todo::
+
+ Add some plots here with grid staggering and positioning?
+
+When creating the nested domain, one must keep in mind that
+the child domain is shifted toward north-east and
+depends on the number of ghost cells as illustrated by
+the *attempted* drawing below for ``nbghostcells=1`` and ``nbghostcells=3``.
+The grid refinement is 3 and ``nxfin`` is the number of child grid points in i-direction.
+
+.. image:: _static/agrif_grid_position.jpg
+
+Note that rectangular regions must be defined so that they are connected to a single parent grid.
+Hence, defining overlapping grids with the same refinement ratio will not work properly,
+boundary data exchange and update being only performed between root and child grids.
+Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either.
+Defining for instance a circumpolar zoom in a global model is therefore not possible.
+
+Preprocessing
+=============
+
+Knowing the refinement factors and area,
+a ``NESTING`` pre-processing tool may help to create needed input files
+(mesh file, restart, climatological and forcing files).
+The key is to ensure volume matching near the child grid interface,
+a step done by invoking the :file:`Agrif_create_bathy.exe` program.
+You may use the namelists provided in the :file:`NESTING` directory as a guide.
+These correspond to the namelists used to create ``AGRIF_DEMO`` inputs.
+
+Namelist options
+================
+
+Each child grid expects to read its own namelist so that different numerical choices can be made
+(these should be stored in the form :file:`1_namelist_cfg`, :file:`2_namelist_cfg`, etc...
+according to their rank in the grid hierarchy).
+Consistent time steps and number of steps with the chosen time refinement have to be provided.
+Specific to AGRIF is the following block:
+
+.. literalinclude:: ../../namelists/namagrif
+ :language: fortran
+
+where sponge layer coefficients have to be chosen according to the child grid mesh size.
+The sponge area is hard coded in NEMO and applies on the following grid points:
+2 x refinement factor (from ``i=1+nbghostcells+1`` to ``i=1+nbghostcells+sponge_area``)
+
+.. rubric:: References
+
+.. bibliography:: zooms.bib
+ :all:
+ :style: unsrt
+ :labelprefix: A
+ :keyprefix: a-