Skip to content
Snippets Groups Projects
Commit 13658b48 authored by Andrew Coward's avatar Andrew Coward
Browse files

Tidy up top-level rst/md files which are now resident in the user-guide

parent 3def55a6
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
CHANGES.md deleted 100644 → 0
+ 0
− 71
View file @ 3def55a6
# List of the main additions of the new 4.2 release - February 2022
This section provides you an overview of the major NEMO upgrades as included in the new 4.2 release.
It includes instructions on how to move to new version and a list of the novelties of changed NEMO modules.
If you are willing to port an existing configuration in order to start using this new release, it is sugggested to also look at the 4.2 [Migration Guide](https://sites.nemo-ocean.io/user-guide/migration.html).
## KERNEL
- Quasi Eulerian Coordinates
- New HPG schemes (improvements and new option)
- Preparatory stages for new RK3 time stepping scheme (includes time-pointer changes, DO LOOP macros, changes in main arrays dimensions)
- Full Shallow Water setup
- New vertical scale factors management in time reducing meùory footprint : added key qco (Quasi Eulerian Coordinates), key linssh, see Migration Guide
## AIR SEA INTERACTIONS
- Currents feedbacks
- Mass-flux convection scheme (still not compatible with TOP & PISCES)
- Bulk improvements
- Atmospheric Boundary layer model (1D vertical as for now) & tools improvements
- Wave forcing improvements
## AGRIF zooms
- Improvement of Agrif for global configurations (periodic, north fold zoom, HPC),
- Allow AGRIF for multiple vertical grids
- Updated Nesting Tools to set up the AGRIF zooms
## Sea-ice SI3
- EAP & VP rheology (V&V to complete)
- Melt ponds (preliminary implementation)
- (Updated Reference Manual will be made available to users by March 2022)
## ENHANCEMENTS
- Ocean column properties in NEMO-ICB
- OSMOSIS
- Update internal tidal mixing
## Tracers and biogeochemistry TOP
- Ice sheet iron sources
- Scheme for vertical penetration of visible light
- (Updated Reference Manual will be made available to users by March 2022)
## DATA interface
- OBS modifications
## Input Output Manager
- Use XIOS to read & write restart file (allowing to produce a unique restart file while using domain decomposition)
## High Performance Computing HPC
- MPI Communication cleanup & improvements using MPI3
- Reduce memory footprint
- Improved computational performance of solar penetration scheme
So as some new features implemented, and now needing further work to produce actual performance improvements:
- Extra Halo extension
- Mixed precision preparatory phase
- Loop fusion
- Tiling
## VERIFICATION & VALIDATION
- Tests cases now available with most new developments
- SETTE validation script improvements
- OASIS test case for ocean atmosphere coupled interface
CONTRIBUTING.rst deleted 100644 → 0
+ 0
− 73
View file @ 3def55a6
************
Contributing
************
.. todo::
.. contents::
:local:
Sending feedbacks
=================
| Sending feedbacks is a useful way to contribute to NEMO efficency and reliability. Before doing so,
please check here :forge:`search <search on the developement platform>` in wiki, tickets, forum and online
documentation if the subject has already been discussed. You can either contribute to an existing
discussion, or
| Create an entry for the discussion online, according to your needs
- You have a question: create a topic in the appropriate :forge:`discussion <forum>`
- You would like to raise and issue: open a new ticket of the right type depending of its severity
- "Unavoidable" :forge:`newticket?type=Bug <bug>`
- "Workable" :forge:`newticket?type=Defect <defect>`
Please follow the guidelines and try to be as specific as possible in the ticket description.
New development
===============
You have build a development relevant for NEMO shared reference: an addition of the source code,
a full fork of the reference, ...
You may want to share it with the community (see Hack below) or to propose it for implementation in the future
NEMO release (see Proposal / Task below).
The proposals for developments to be included in the shared NEMO reference are first examined by NEMO Developers
Committee / Scientific Advisory Board.
The implementation of a new development requires some additionnal work from the intial developer.
These tasks will need to be scheduled with NEMO System Team.
Hack
----
You only would like to inform NEMO community about your developments.
You can promote your work on NEMO forum gathering the contributions fromof the community by creating
a specific topic here :forge:`discussion/forum/5 <dedicated forum>`
Proposal / Task
---------------
| Your development is quite small, and you would only like to offer it as a possible enhancement. Please suggest it
as an enhancement here :forge:`newticket?type=Enhancement <enhancement>` . It will be taken in account, if
feasible, by NEMO System Team. To ease the process, it is suggested, rather than attaching the modified
routines to the ticket, to highlight the proposed changes by adding to the ticket the output of ``svn diff``
or ``svn patch`` from your working copy.
| Your development seems relevant for addition into the future release of NEMO shared reference.
Implementing it into NEMO shared reference following the usual quality control will require some additionnal work
from you and also from the NEMO System Team in charge of NEMO development. In order to evaluate the work,
your suggestion should be send as a proposed enhancement here :forge:`newticket?type=Enhancement <enhancement>`
including description of the development, its implementation, and the existing validations.
The proposed enhancement will be examined by NEMO Developers Committee / Scientific Advisory Board.
Once approved by the Committee, the assicated development task can be scheduled in NEMO development work plan,
and tasks distributed between you as initial developer and PI of this development action, and the NEMO System Team.
Once sucessful (meeting the usual quality control steps) this action will allow the merge of these developments with
other developments of the year, building the future NEMO.
INSTALL.rst deleted 100644 → 0
+ 0
− 270
View file @ 3def55a6
*******************
Build the framework
*******************
.. todo::
TBD
.. contents::
:local:
Prerequisites
=============
| The NEMO source code is written in *Fortran 95* and
some of its prerequisite tools and libraries are already included in the download.
| It contains the AGRIF_ preprocessing program ``conv``; the FCM_ build system and
the IOIPSL_ library for parts of the output.
System dependencies
-------------------
In the first place the other requirements should be provided natively by your system or
can be installed from the official repositories of your Unix-like distribution:
- *Perl* interpreter
- *Fortran* compiler (``ifort``, ``gfortran``, ``pgfortran``, ...),
- *Message Passing Interface (MPI)* implementation (e.g. |OpenMPI|_ or |MPICH|_).
- |NetCDF|_ library with its underlying |HDF|_
**NEMO, by default, takes advantage of some MPI features introduced into the MPI-3 standard.**
.. hint::
The MPI implementation is not strictly essential
since it is possible to compile and run NEMO on a single processor.
However most realistic configurations will require the parallel capabilities of NEMO and
these use the MPI standard.
.. note::
On older systems, that do not support MPI-3 features,
the ``key_mpi2`` preprocessor key should be used at compile time.
This will limit MPI features to those defined within the MPI-2 standard
(but will lose some performance benefits).
.. |OpenMPI| replace:: *OpenMPI*
.. _OpenMPI: https://www.open-mpi.org
.. |MPICH| replace:: *MPICH*
.. _MPICH: https://www.mpich.org
.. |NetCDF| replace:: *Network Common Data Form (NetCDF)*
.. _NetCDF: https://www.unidata.ucar.edu
.. |HDF| replace:: *Hierarchical Data Form (HDF)*
.. _HDF: https://www.hdfgroup.org
Specifics for NetCDF and HDF
----------------------------
NetCDF and HDF versions from official repositories may have not been compiled with MPI support.
However access to all the options available with the XIOS IO-server will require
the parallelism of these libraries.
| **To satisfy these requirements, it is common to have to compile from source
in this order HDF (C library) then NetCDF (C and Fortran libraries)**
| It is also necessary to compile these libraries with the same version of the MPI implementation that
both NEMO and XIOS (see below) have been compiled and linked with.
.. hint::
| It is difficult to define the options for the compilation as
they differ from one architecture to another according to
the hardware used and the software installed.
| The following is provided without any warranty
.. code-block:: console
$ ./configure [--{enable-fortran,disable-shared,enable-parallel}] ...
It is recommended to build the tests ``--enable-parallel-tests`` and run them with ``make check``
Particular versions of these libraries may have their own restrictions.
State the following requirements for netCDF-4 support:
.. caution::
| When building NetCDF-C library versions older than 4.4.1, use only HDF5 1.8.x versions.
| Combining older NetCDF-C versions with newer HDF5 1.10 versions will create superblock 3 files
that are not readable by lots of older software.
Extract and install XIOS
========================
With the sole exception of running NEMO in mono-processor mode
(in which case output options are limited to those supported by the ``IOIPSL`` library),
diagnostic outputs from NEMO are handled by the third party ``XIOS`` library.
It can be used in two different modes:
:*attached*: Every NEMO process also acts as a XIOS server
:*detached*: Every NEMO process runs as a XIOS client.
Output is collected and collated by external, stand-alone XIOS server processors.
Instructions on how to install XIOS can be found on its :xios:`wiki<>`.
.. hint::
It is recommended to use XIOS 2.5 release.
This version should be more stable (in terms of future code changes) than the XIOS trunk.
It is also the one used by the NEMO system team when testing all developments and new releases.
This particular version has its own branch and can be checked out with:
.. code:: console
$ svn co https://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/branchs/xios-2.5
Download and install the NEMO code
==================================
Checkout the NEMO sources
-------------------------
.. code:: console
$ svn co https://forge.ipsl.jussieu.fr/nemo/svn/NEMO/trunk
Description of 1\ :sup:`st` level tree structure
------------------------------------------------
+---------------+----------------------------------------+
| :file:`arch` | Compilation settings |
+---------------+----------------------------------------+
| :file:`cfgs` | :doc:`Reference configurations <cfgs>` |
+---------------+----------------------------------------+
| :file:`doc` | :doc:`Documentation <doc>` |
+---------------+----------------------------------------+
| :file:`ext` | Dependencies included |
| | (``AGRIF``, ``FCM`` & ``IOIPSL``) |
+---------------+----------------------------------------+
| :file:`mk` | Compilation scripts |
+---------------+----------------------------------------+
| :file:`src` | :doc:`Modelling routines <src>` |
+---------------+----------------------------------------+
| :file:`tests` | :doc:`Test cases <tests>` |
| | (unsupported) |
+---------------+----------------------------------------+
| :file:`tools` | :doc:`Utilities <tools>` |
| | to {pre,post}process data |
+---------------+----------------------------------------+
Setup your architecture configuration file
------------------------------------------
All compiler options in NEMO are controlled using files in :file:`./arch/arch-'my_arch'.fcm` where
``my_arch`` is the name of the computing architecture
(generally following the pattern ``HPCC-compiler`` or ``OS-compiler``).
It is recommended to copy and rename an configuration file from an architecture similar to your owns.
You will need to set appropriate values for all of the variables in the file.
In particular the FCM variables:
``%NCDF_HOME``; ``%HDF5_HOME`` and ``%XIOS_HOME`` should be set to
the installation directories used for XIOS installation
.. code-block:: sh
%NCDF_HOME /usr/local/path/to/netcdf
%HDF5_HOME /usr/local/path/to/hdf5
%XIOS_HOME /home/$( whoami )/path/to/xios-2.5
%OASIS_HOME /home/$( whoami )/path/to/oasis
Create and compile a new configuration
======================================
The main script to {re}compile and create executable is called :file:`makenemo` located at
the root of the working copy.
It is used to identify the routines you need from the source code, to build the makefile and run it.
As an example, compile a :file:`MY_GYRE` configuration from GYRE with 'my_arch':
.. code-block:: sh
./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE'
Then at the end of the configuration compilation,
:file:`MY_GYRE` directory will have the following structure.
+------------+----------------------------------------------------------------------------+
| Directory | Purpose |
+============+============================================================================+
| ``BLD`` | BuiLD folder: target executable, headers, libs, preprocessed routines, ... |
+------------+----------------------------------------------------------------------------+
| ``EXP00`` | Run folder: link to executable, namelists, ``*.xml`` and IOs |
+------------+----------------------------------------------------------------------------+
| ``EXPREF`` | Files under version control only for :doc:`official configurations <cfgs>` |
+------------+----------------------------------------------------------------------------+
| ``MY_SRC`` | New routines or modified copies of NEMO sources |
+------------+----------------------------------------------------------------------------+
| ``WORK`` | Links to all raw routines from :file:`./src` considered |
+------------+----------------------------------------------------------------------------+
After successful execution of :file:`makenemo` command,
the executable called `nemo` is available in the :file:`EXP00` directory
More :file:`makenemo` options
-----------------------------
``makenemo`` has several other options that can control which source files are selected and
the operation of the build process itself.
.. literalinclude:: ../../../makenemo
:language: text
:lines: 119-143
:caption: Output of ``makenemo -h``
These options can be useful for maintaining several code versions with only minor differences but
they should be used sparingly.
Note however the ``-j`` option which should be used more routinely to speed up the build process.
For example:
.. code-block:: sh
./makenemo –m 'my_arch' –r GYRE -n 'MY_GYRE' -j 8
will compile up to 8 processes simultaneously.
Default behaviour
-----------------
At the first use,
you need the ``-m`` option to specify the architecture configuration file
(compiler and its options, routines and libraries to include),
then for next compilation, it is assumed you will be using the same compiler.
If the ``-n`` option is not specified the last compiled configuration will be used.
Tools used during the process
-----------------------------
* :file:`functions.sh`: bash functions used by ``makenemo``, for instance to create the WORK directory
* :file:`cfg.txt` : text list of configurations and source directories
* :file:`bld.cfg` : FCM rules for compilation
Examples
--------
.. literalinclude:: ../../../makenemo
:language: text
:lines: 146-153
Running the model
=================
Once :file:`makenemo` has run successfully,
the ``nemo`` executable is available in :file:`./cfgs/MY_CONFIG/EXP00`.
For the reference configurations, the :file:`EXP00` folder also contains the initial input files
(namelists, ``*.xml`` files for the IOs, ...).
If the configuration needs other input files, they have to be placed here.
.. code-block:: sh
cd 'MY_CONFIG'/EXP00
mpirun -n $NPROCS ./nemo # $NPROCS is the number of processes
# mpirun is your MPI wrapper
Viewing and changing list of active CPP keys
============================================
For a given configuration (here called ``MY_CONFIG``),
the list of active CPP keys can be found in :file:`./cfgs/'MYCONFIG'/cpp_MY_CONFIG.fcm`
This text file can be edited by hand or with :file:`makenemo` to change the list of active CPP keys.
Once changed, one needs to recompile ``nemo`` in order for this change to be taken in account.
Note that most NEMO configurations will need to specify the following CPP keys:
``key_xios`` for IOs. MPI parallelism is activated by default. Use ``key_mpi_off`` to compile without MPI.
README.rst
+ 12
− 7
View file @ 13658b48
......@@ -5,6 +5,11 @@
.. _`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
.. _`Test case repository`: https://github.com/NEMO-ocean/NEMO-examples
Welcome to NEMO home page!
==========================
......@@ -13,15 +18,15 @@ NEMO (*Nucleus for European Modelling of the Ocean*) is a state-of-the-art model
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: [Former web platform forge](https://forge.ipsl.jussieu.fr/nemo) (SVN+Trac) contains the previous documentation and releases made available from the beginning of the project up to of NEMO 4.0.
Reminder: `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: https://sites.nemo-ocean.io/user-guide/. This explains how to download the code, build the environment, create the executable, and perform a first integration.
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] (https://sites.nemo-ocean.io/user-guide/migration.html) which aims to help you to make the move to 4.2.0.
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 https://github.com/NEMO-ocean/NEMO-examples. 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!
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
......@@ -29,11 +34,11 @@ Project documentation
Reference manuals fully describing NEMO for the three main component
* |OCE| models the ocean {thermo}dynamics and solves the primitive equations (:file:`./src/OCE`)
* |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 (:file:`./src/ICE`)
* |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 (:file:`./src/TOP`)
* |MBG| models the {on,off}line oceanic tracers transport and biogeochemical processes (`./src/TOP <./src/TOP>`_)
are available from zenodo
============ ============================================== ===============================================
......
REFERENCES.bib deleted 100644 → 0
+ 0
− 53
View file @ 3def55a6
@manual{ NEMO_man,
title = "NEMO ocean engine",
series = "Scientific Notes of Climate Modelling Center",
number = "27",
author = "Gurvan Madec and NEMO System Team",
institution = "Institut Pierre-Simon Laplace (IPSL)",
publisher = "Zenodo",
issn = "1288-1619",
doi = "10.5281/zenodo.1464816"
}
% edition="",
% year=""
@manual{ SI3_man,
title = "Sea Ice modelling Integrated Initiative (SI$^3$) -- The
NEMO sea ice engine",
series = "Scientific Notes of Climate Modelling Center",
number = "31",
author = "NEMO Sea Ice Working Group",
institution = "Institut Pierre-Simon Laplace (IPSL)",
publisher = "Zenodo",
issn = "1288-1619",
doi = "10.5281/zenodo.1471689"
}
% edition="",
% year=""
@manual{ TOP_man,
title = "Tracers in Ocean Paradigm (TOP) -- The NEMO passive
tracers engine",
series = "Scientific Notes of Climate Modelling Center",
number = "28",
author = "NEMO TOP Working Group",
institution = "Institut Pierre-Simon Laplace (IPSL)",
publisher = "Zenodo",
issn = "1288-1619",
doi = "10.5281/zenodo.1471700"
}
% edition="",
% year=""
@article{ TAM_pub,
title = "NEMOTAM: Tangent and Adjoint Models for the ocean
modelling platform NEMO",
pages = "1245--1257",
journal = "Geoscientific Model Development",
volume = "8",
number = "4",
author = "Vidard, A. and Bouttier, P.-A. and Vigilant, F.",
year = "2015",
doi = "10.5194/gmd-8-1245-2015"
}
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment