diff --git a/Makefile b/Makefile index 069a450..39f6344 100644 --- a/Makefile +++ b/Makefile @@ -50,6 +50,9 @@ OUTPUTDIR=$(CURDIR)/build/html CONFFILE=$(CURDIR)/scripts/pelican/pelicanconf.py PORT ?= 8000 +CONTENT_FILES := $(shell find $(INPUTDIR) -type f) +PELICAN_CONFIG_FILES := $(shell find $(CURDIR)/scripts/pelican -type f) + PELICANOPTS= GENERATEDOXYOPTS= SETUPOPTS= @@ -75,7 +78,7 @@ html: build/html/index.html @echo "[atlas-docs] Generated html at $(CURDIR)/build/html" @echo "[atlas-docs] To visualise, execute \"make serve\" and open browser at \"http://localhost:8000\"" -build/html/index.html: content/generated/atlas_release_version.rst build/html/$(DOXYGEN_API)/index.html +build/html/index.html: content/generated/atlas_release_version.rst build/html/$(DOXYGEN_API)/index.html $(CONTENT_FILES) $(PELICAN_CONFIG_FILES) @echo "[atlas-docs] Building Pelican documentation" @$(PELICAN) $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS) @@ -95,7 +98,7 @@ else @touch build/doxygen/atlas.tag endif -build/doxygen/Doxyfile: venv/bin/activate +build/doxygen/Doxyfile: venv/bin/activate scripts/generate_doxyfile.py scripts/doxygen/Doxyfile-default scripts/doxygen/Doxyfile-custom scripts/doxygen/Doxyfile-mcss @echo "[atlas-docs] Generating Doxyfile \"build/doxygen/Doxyfile\"" @$(GENERATE_DOXYFILE) $(GENERATEDOXYOPTS) diff --git a/content/design.rst b/content/design.rst index 1980958..0792e30 100644 --- a/content/design.rst +++ b/content/design.rst @@ -18,6 +18,9 @@ are aided by diagrams formulated in the `Unified Modelling Language (UML) `_ ======================================================== +`Output and visualisation » <{filename}/design/output_and_visualisation.rst>`_ +=============================================================================== + `Parallelisation » <{filename}/design/parallelisation.rst>`_ ============================================================ diff --git a/content/design/grid.rst b/content/design/grid.rst index c40ce77..36c296b 100644 --- a/content/design/grid.rst +++ b/content/design/grid.rst @@ -6,8 +6,6 @@ Grid .. role:: cpp(code) :language: cpp -.. note-danger:: Under construction!!! - .. contents:: :class: m-block m-default @@ -169,7 +167,18 @@ Following code snippets shows how to construct any grid from either a configurat .. block-warning:: Example on construction of grids - C++ example: + .. raw:: html + +
+ + + +
+ + + +
+
.. code:: cpp @@ -177,12 +186,15 @@ Following code snippets shows how to construct any grid from either a configurat Config F16_config; F16_config.set( "type", "regular_gaussian" ); F16_config.set( "N", 16 ); - + Grid F16( F16_config ); // regular Gaussian grid (F16) Grid N16( "N16" ); // classic reduced Gaussian (N16) - Fortran example: - + .. raw:: html + +
+
+ .. code:: fortran type(atlas_Grid) :: F16, N16 @@ -195,6 +207,27 @@ Following code snippets shows how to construct any grid from either a configurat F16 = atlas_Grid( F16_config ) ! regular Gaussian grid (F16) N16 = atlas_Grid( "N16" ) ! classic reduced Gaussian grid (N16) + .. raw:: html + +
+
+ + .. code:: python + + import atlas + + f16_config = atlas.Config() + f16_config.set("type", "regular_gaussian") + f16_config.set("N", 16) + + F16 = atlas.Grid(f16_config) # regular Gaussian grid (F16) + N16 = atlas.Grid("N16") # classic reduced Gaussian grid (N16) + + .. raw:: html + +
+
+ .. note-success:: Even though the configuration object (``F16_config``) is here constructed programatically, diff --git a/content/design/output_and_visualisation.rst b/content/design/output_and_visualisation.rst new file mode 100644 index 0000000..2ddb5d7 --- /dev/null +++ b/content/design/output_and_visualisation.rst @@ -0,0 +1,50 @@ +Output and visualisation +######################## + +:breadcrumb: {filename}/design.rst Design + +.. role:: cpp(code) + :language: cpp + +.. role:: verbatim(code) + :language: verbatim + +.. contents:: + :class: m-block m-default + +Atlas provides a way to visualise parallel meshes and fields from its output. The Atlas output is supported in ``Gmsh`` and ``SCRIP/netcdf`` format. + +Gmsh visualisation +================== + +Installing Gmsh +--------------- + +Please `download and install the 4.6 version of Gmsh `_ to visualize Atlas output. + +.. note-warning:: + + Atlas is tested with Gmsh **4.6**. Please make sure to install this version of Gmsh to visualize Atlas output. + + +Example of visualising meshes and fields with Gmsh +-------------------------------------------------- + +Atlas can output meshes and fields in the `Gmsh `_ `format `_. +This is a great format to visualise low resolution meshes and fields with the interactive Gmsh viewer. +However, it becomes sluggish to unresponsive for high resolution meshes and fields. + +Using ``atlas-meshgen`` and ``atlas-interpolation`` tools, one can generate meshes and variable field values in Gmsh format, and visualise them with the interactive Gmsh viewer. +Here is an example of visualising a mesh with the Gmsh viewer: + +.. code-block:: bash + + ./bin/atlas-meshgen --3d --include-pole O4 + gmsh mesh.msh + +It is also possible to visualise fields with the Gmsh viewer. Here is an example of outputting and visualising an interpolated field with the Gmsh viewer: + +.. code-block:: bash + + ./bin/atlas-interpolation --s.grid O4 --t.grid O4 --interpolation nearest --output-gmsh + gmsh tgt_mesh.msh tgt_field.msh diff --git a/content/getting_started/linking.rst b/content/getting_started/linking.rst index a28432b..9754814 100644 --- a/content/getting_started/linking.rst +++ b/content/getting_started/linking.rst @@ -165,16 +165,44 @@ a ``BUNDLE`` option to toggle the behaviour of either bundling the dependencies To enable the bundling, the argument ``-DBUNDLE=ON`` needs to be passed on the cmake configuration command line. -- The content of ``hello_atlas.cc`` is: +.. raw:: html + +
+ + + +
+ + + +
+
.. include:: project_bundle_atlas/src/hello-atlas.cc :code: c++ -- The content of ``hello_atlas_f.cc`` is: +.. raw:: html + +
+
.. include:: project_bundle_atlas/src/hello-atlas_f.F90 :code: fortran - + +.. raw:: html + +
+
+ +.. include:: project_bundle_atlas/src/hello-atlas.py + :code: python + +.. raw:: html + +
+
+ + Creating a new project with ecbuild ----------------------------------- diff --git a/content/getting_started/project_bundle_atlas/src/hello-atlas.py b/content/getting_started/project_bundle_atlas/src/hello-atlas.py new file mode 100644 index 0000000..4d794f0 --- /dev/null +++ b/content/getting_started/project_bundle_atlas/src/hello-atlas.py @@ -0,0 +1,9 @@ +#!/usr/bin/env python3 +import atlas + +def main() -> None: + _ = atlas + print("Hello from atlas") + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/content/index.rst b/content/index.rst index 693e730..d1ef50a 100644 --- a/content/index.rst +++ b/content/index.rst @@ -7,9 +7,6 @@ Atlas :description: Data structure library for NWP and Climate Modelling :summary: Data structure library for NWP and Climate Modelling :hide_navbar_brand: True - -.. include:: generated/atlas_release_version.rst - :landing: .. container:: m-row @@ -43,3 +40,50 @@ Atlas | Version |atlas-release-version| released +Overview +======== + +Atlas is an ECMWF library for parallel data structures supporting unstructured +grids and function spaces, with the aim to investigate alternative, more scalable +dynamical core options for Earth system models, and to support modern interpolation +and product generation software. + +Atlas is predominantly C++ code, with main features available to Fortran codes +through a F2003 interface. It requires some flavour of Unix (such as Linux). +It is known to run on a number of systems, some of which are directly supported +by ECMWF. + +What's New? +=========== + +Curious about what was added or improved recently? +Check out the `Changelog `_. + +Contributing +============ + +Contributions to Atlas are welcome. Open an issue to discuss a feature request +or bug, then submit a pull request against the ``develop`` branch. + +Citing Atlas +============ + +If Atlas was useful in your research, please cite: + +.. code-block:: bibtex + + @article{DECONINCK2017188, + title = "Atlas : A library for numerical weather prediction and climate modelling", + journal = "Computer Physics Communications", + volume = "220", + pages = "188 - 204", + year = "2017", + issn = "0010-4655", + doi = "https://doi.org/10.1016/j.cpc.2017.07.006", + url = "http://www.sciencedirect.com/science/article/pii/S0010465517302138", + author = "Willem Deconinck and Peter Bauer and Michail Diamantakis and Mats Hamrud and Christian Kuhnlein and Pedro Maciel and Gianmarco Mengaldo and Tiago Quintino and Baudouin Raoult and Piotr K. Smolarkiewicz and Nils P. Wedi", + keywords = "Numerical weather prediction, Climate, Earth system, High performance computing, Meteorology, Flexible mesh data structure" + } + +.. include:: generated/atlas_release_version.rst + diff --git a/content/tools.rst b/content/tools.rst index 0139d25..81fb643 100644 --- a/content/tools.rst +++ b/content/tools.rst @@ -9,3 +9,8 @@ This page discusses some of the tools thar are provided by the atlas installatio `atlas-meshgen » <{filename}/tools/atlas-meshgen.rst>`_ ======================================================= +`atlas-interpolation » <{filename}/tools/atlas-interpolation.rst>`_ +=================================================================== + +`atlas-gaussian-latitudes » <{filename}/tools/atlas-gaussian-latitudes.rst>`_ +============================================================================= \ No newline at end of file diff --git a/content/tools/atlas-grids.rst b/content/tools/atlas-grids.rst index 7759725..32b89e9 100644 --- a/content/tools/atlas-grids.rst +++ b/content/tools/atlas-grids.rst @@ -11,13 +11,36 @@ The command-line tool ``atlas-grids`` provides information on grids supported by Usage ----- -.. code :: shell +.. code-block:: shell $ atlas-grids [OPTION]... [--help] For a list of supported grids, use -.. code :: shell +.. code-block:: shell $ atlas-grids --list +Special grids FESOM and ORCA +============================ + +Different FESOM and ORCA meshes are available as Atlas plugins after adding them in ``atlas-bundle/bundle.yml``: + +.. code-block:: yaml + + - atlas-orca : + git : ${GITHUB}/ecmwf/atlas-orca + version : develop + require : atlas + + - atlas-fesom : + git : ${GITHUB}/ecmwf/atlas-fesom + version : develop + require : atlas + +Before using FESOM and ORCA grids, we need to set environment variables: + +.. code-block:: bash + + export ATLAS_ORCA_CACHING=1 + export ATLAS_FESOM_CACHING=1 \ No newline at end of file diff --git a/content/tools/atlas-interpolation.rst b/content/tools/atlas-interpolation.rst new file mode 100644 index 0000000..04f0fb7 --- /dev/null +++ b/content/tools/atlas-interpolation.rst @@ -0,0 +1,132 @@ +atlas-interpolation +################### + +:breadcrumb: {filename}/tools.rst Tools + +The command-line tool ``atlas-interpolation`` provides information on interpolations supported by Atlas. + +.. contents:: + :class: m-block m-default + +Specific usage +================== + +List all available interpolations + +.. code :: bash + + $ atlas-interpolation --list + +Generate interpolation weights for a pair of source and target meshes: + +.. code :: bash + + $ atlas-interpolation --s.grid --t.grid --interpolation \ + [--output-matrix|--read-matrix|--test-matrix] [--format scrip|eckit] [--output-gmsh] + +and optionally, apply the interpolation to a test field on the source mesh and write the interpolated field on the target mesh. +For larger meshes, the interpolation weights can be written-out to a file and read-in later to save time when the same interpolation is applied repeatedly. +Both writting-out and reading-in can be done in parallel by pre-appending e.g. ``OMP_NUM_THREADS=1 mpirun -np 4`` to the command above. + +If ``--output-matrix`` (or ``--read-matrix``) is given, the interpolation weights get written-out (or read-in) to/from the file +``` +remap___.nc +``` +in the SCRIP format (only if ``--format scrip`` is given) or +``` +remap___.eckit +``` +in the eckit-binary format. + +If ``--output-gmsh`` is given, a test source field gets remapped and written-out to the file ``tgt_field.msh`` in the Gmsh format, +and the target mesh gets written-out to the file ``tgt_mesh.msh`` in the Gmsh format along with the source mesh in the file ``src_mesh.msh`` in the Gmsh format. + +A few other useful options are available. Please use the help message to learn about them: + +.. code :: bash + + $ atlas-interpolation --help + + +Comparison of interpolation methods available on arbitrary meshes +================================================================= + +Most useful interpolation methods are available on every kind of mesh. Atlas has a few of these methods readily available. +Whilst the conservative remapping method still require that mesh cells form a convex polygon, this is a minimal requirement met for almost every imaginable mesh these days. + +Experimental order of converge of interpolation methods +------------------------------------------------------- + +The figures below show the convergence of interpolation errors for different interpolation methods available in Atlas. Apart from the ``grid-box-average`` method, +which requires a semi-structured grid of Atlas type ``StructuredGrid``, the other methods are available on any kind of unstructured grids. + +The figures below show the experimental order of convergence of different interpolators. The Atlas implementations confirms the formal order of convergence +from these interpolation methods. + +.. container:: m-row + + .. container:: m-col-l-6 + + .. figure:: {static}/tools/img/atlas_interpolators_convergence.png + :target: {static}/tools/img/atlas_interpolators_convergence.png + :height: 400 px + + .. container:: m-col-l-6 + + .. figure:: {static}/tools/img/atlas_interpolators_eoc.png + :target: {static}/tools/img/atlas_interpolators_eoc.png + :height: 400 px + + + +Timings of interpolation methods with and without caching +--------------------------------------------------------- + +The following table summarises the timing of different interpolation methods when the caching is used versus the recomputing of the interpolation weights. + +.. figure:: {static}/tools/img/atlas_interpolators_timing.png + :target: {static}/tools/img/atlas_interpolators_timing.png + :height: 400 px + +Diffusion of interpolators in a model coupler +--------------------------------------------- + +In a consequtive remapping (normally seen in model coupler) different interpolators can be used to retain extrema of fields. +In one such scenario, we remap consequtively from a source grid (here, O16) to a target grid (here, O32) and back, then repeated 200 times. +Ideally, a given initial data on the source grid would remain identical after 200 interpolations to the target grid +and finally back onto the source. + +The initial data is "the sinusoid" from Valcke et al (2022), modified to show only the one positive sinusoid as seen here for the initial data on O16. +For visualisation ease only, we scaled the hill height by 100x. + +The top left is the initial data on the source grid. All other show the remapped field after 200 back-and-forth remappings. +The top right shows the result for ``grid-box-method`` which is the only non-parallel interpolator here. + +The nearest neighbour and the conservative second order spherical polygon interpolators are the least diffusive methods. +The other methods, in particular, the more accurate, finite-elements and bilinear interpolators are noticeably more diffusive. +In the F16↔H32 grid setup, the 4-nearest-neighbour was much less diffusive than depicted here for the O16↔O32 setup, however, +the 4-nearest-neighbour was again more diffusive than the nearest-neighbour. + +.. container:: m-row + + .. container:: m-col-l-6 + + .. figure:: {static}/tools/img/diffusion_init.png + :target: {static}/tools/img/diffusion_init.png + :height: 150 px + + .. figure:: {static}/tools/img/diffusion_1of3.png + :target: {static}/tools/img/diffusion_1of3.png + :height: 450 px + + .. container:: m-col-l-6 + + .. figure:: {static}/tools/img/diffusion_3of3.png + :target: {static}/tools/img/diffusion_3of3.png + :height: 150 px + + + + .. figure:: {static}/tools/img/diffusion_2of3.png + :target: {static}/tools/img/diffusion_2of3.png + :height: 450 px \ No newline at end of file diff --git a/content/tools/atlas-meshgen.rst b/content/tools/atlas-meshgen.rst index a5235a8..e190344 100644 --- a/content/tools/atlas-meshgen.rst +++ b/content/tools/atlas-meshgen.rst @@ -6,10 +6,6 @@ atlas-meshgen The command-line tool ``atlas-meshgen`` generates a mesh in the `Gmsh `_ `format `_ given a grid and options. -.. note-warning:: - - Gmsh is great to visualize low resolution meshes but becomes sluggish to unresponsive for high resolution meshes. - This tool is however invaluable for development and for understanding of how low resolution grids and meshes are constructed. .. contents:: :class: m-block m-default @@ -81,4 +77,4 @@ The ``--include-pole`` option will make the mesh generator add one extra point a .. figure:: {static}/tools/img/mesh3d_point.png :target: {static}/tools/img/mesh3d_point.png - :width: 500 px + :width: 500 px \ No newline at end of file diff --git a/content/tools/img/atlas_interpolators_convergence.png b/content/tools/img/atlas_interpolators_convergence.png new file mode 100644 index 0000000..b799abc Binary files /dev/null and b/content/tools/img/atlas_interpolators_convergence.png differ diff --git a/content/tools/img/atlas_interpolators_eoc.png b/content/tools/img/atlas_interpolators_eoc.png new file mode 100644 index 0000000..10cbeee Binary files /dev/null and b/content/tools/img/atlas_interpolators_eoc.png differ diff --git a/content/tools/img/atlas_interpolators_timing.png b/content/tools/img/atlas_interpolators_timing.png new file mode 100644 index 0000000..d176a3f Binary files /dev/null and b/content/tools/img/atlas_interpolators_timing.png differ diff --git a/content/tools/img/diffusion_1of3.png b/content/tools/img/diffusion_1of3.png new file mode 100644 index 0000000..39c1ac2 Binary files /dev/null and b/content/tools/img/diffusion_1of3.png differ diff --git a/content/tools/img/diffusion_2of3.png b/content/tools/img/diffusion_2of3.png new file mode 100644 index 0000000..c6f948a Binary files /dev/null and b/content/tools/img/diffusion_2of3.png differ diff --git a/content/tools/img/diffusion_3of3.png b/content/tools/img/diffusion_3of3.png new file mode 100644 index 0000000..59bfbf3 Binary files /dev/null and b/content/tools/img/diffusion_3of3.png differ diff --git a/content/tools/img/diffusion_init.png b/content/tools/img/diffusion_init.png new file mode 100644 index 0000000..d4f1c45 Binary files /dev/null and b/content/tools/img/diffusion_init.png differ diff --git a/scripts/generate_doxyfile.py b/scripts/generate_doxyfile.py index c9aa431..05cfb3f 100755 --- a/scripts/generate_doxyfile.py +++ b/scripts/generate_doxyfile.py @@ -44,7 +44,8 @@ doxygen = """ -INPUT = {atlas}/doc/pages +INPUT = {atlas}/doc/pages/atlas_environment_variables.md +INPUT += {atlas}/doc/pages/developer_information.md INPUT += {atlas}/src/atlas INPUT += {atlas_aliases}/src/atlas diff --git a/scripts/pelican/pelicanconf.py b/scripts/pelican/pelicanconf.py index 1be9be4..2c6be38 100644 --- a/scripts/pelican/pelicanconf.py +++ b/scripts/pelican/pelicanconf.py @@ -71,22 +71,24 @@ latest_atlas_docs = "c++" enable_blog = False -M_LINKS_NAVBAR1 = [('Tools', 'tools/', 'tools', [ - ('atlas-grids','tools/atlas-grids',''), - ('atlas-meshgen','tools/atlas-meshgen',''), - ('atlas-gaussian-latitudes','tools/atlas-gaussian-latitudes','')]), - ('Design', 'design/', 'design', [ +M_LINKS_NAVBAR1 = [ ('Getting Started', 'getting_started/', 'getting_started', [ + ('Downloading and building', 'getting_started/installation',''), + ('Linking Atlas into your project', 'getting_started/linking','')]), + ('Design', 'design/', 'design', [ ('Object oriented design','design/object_oriented',''), ('Grid','design/grid',''), ('Mesh','design/mesh',''), ('Interpolation','design/interpolation',''), + ('Output and visualisation','design/output_and_visualisation',''), ('Plugin architecture','design/plugin_architecture','')]), - ('Getting Started', 'getting_started/', 'getting_started', [ - ('Downloading and building', 'getting_started/installation',''), - ('Linking Atlas into your project', 'getting_started/linking','')]), - ('Docs', latest_atlas_docs+'/', '', [ + ('Tools', 'tools/', 'tools', [ + ('atlas-grids','tools/atlas-grids',''), + ('atlas-meshgen','tools/atlas-meshgen',''), + ('atlas-interpolation','tools/atlas-interpolation',''), + ('atlas-gaussian-latitudes','tools/atlas-gaussian-latitudes','')]), + ('Docs', latest_atlas_docs+'/', '', [ ('C++ API', latest_atlas_docs+'/', ''), - ('Fortran API [TODO]', '', '')])] + ('Fortran API [TODO]', '', '')]) ] M_LINKS_NAVBAR2 = [] if enable_blog: @@ -112,7 +114,8 @@ M_LINKS_FOOTER4 = []#('Ha', 'contact/')] M_CSS_FILES = ['https://fonts.googleapis.com/css?family=Source+Code+Pro:400,400i,600%7CSource+Sans+Pro:400,400i,600,600i&subset=latin-ext', - 'static/m-dark.css'] + 'static/m-dark.css', + 'static/atlas-tabs.css'] M_FINE_PRINT = """ | Atlas. Copyright © `ECMWF `_. Site powered by `Pelican `_