Merge pull request #233 from snek5000/doc/final-touches

Final touches to docs and release
snek5000 · Dec 6, 2022 · cb62400 · cb62400
2 parents 1b60f36 + 597760a
commit cb62400
Show file tree

Hide file tree

Showing 20 changed files with 240 additions and 16 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -30,7 +30,7 @@ Security in case of vulnerabilities.
 
 <!-- ## [Unreleased] -->
 
-## [0.8.0] - 2022-12-05
+## [0.8.0] - 2022-12-06
 
 This is the first stable version and is the result of a huge work (more than 550 commits
 and [60 closed issues](https://github.com/snek5000/snek5000/milestone/1)). To summarize,

diff --git a/CITATION.cff b/CITATION.cff
@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it as below."
 title: "Snek5000: Computational Fluid Dynamics with Python and Nek5000"
-version: 0.8.0rc1
+version: 0.8.0
 abstract: |
   Snek5000 is a Python package which allows one to write Fluidsim solvers based
   for the simulations on the Fortran CFD code Nek5000. With a Snek5000-Fluidsim
@@ -21,7 +21,7 @@ authors:
     given-names: Pierre
     orcid: https://orcid.org/0000-0001-9481-4459
 
-doi: 10.5281/zenodo.7399622
-date-released: 2022-12-05
+doi: 10.5281/zenodo.7399621
+date-released: 2022-12-06
 license: BSD-3-Clause
 repository-code: "https://github.com/snek5000/snek5000"
diff --git a/README.md b/README.md
@@ -3,12 +3,12 @@
 # Snek5000
 
 [![PyPI](https://img.shields.io/pypi/v/snek5000)](https://pypi.org/project/snek5000/)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7399622.svg)](https://doi.org/10.5281/zenodo.7399622)
 [![Build Status](https://img.shields.io/github/workflow/status/snek5000/snek5000/build)](https://github.com/snek5000/snek5000/actions)
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/snek5000/snek5000/main.svg)](https://results.pre-commit.ci/latest/github/snek5000/snek5000/main)
 [![Documentation Status](https://readthedocs.org/projects/snek5000/badge/?version=latest)](https://snek5000.readthedocs.io/en/latest/?badge=latest)
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=snek5000_snek5000&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=snek5000_snek5000)
 [![Code coverage](https://codecov.io/gh/snek5000/snek5000/branch/main/graph/badge.svg?token=WzGnN0dfbw)](https://codecov.io/gh/snek5000/snek5000)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7399621.svg)](https://doi.org/10.5281/zenodo.7399621)
 
 <!-- badges -->
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -88,8 +88,8 @@ def root(module):
     "sphinx.ext.viewcode",
     "sphinx_inline_tabs",
     "IPython.sphinxext.ipython_console_highlighting",
-    #  "recommonmark",
-    #  "myst_parser",
+    # "recommonmark",
+    # "myst_parser",
     "myst_nb",
     "sphinx_copybutton",
 ]
@@ -115,8 +115,7 @@ def root(module):
 source_suffix = {
     ".rst": "restructuredtext",
     ".ipynb": "myst-nb",
-    ".myst": "myst-nb",
-    ".md": "myst-nb",
+    ".myst.md": "myst-nb",
 }
 
 # Execute Doxygen

diff --git a/docs/dev/edit_tutorials.md b/docs/dev/edit_tutorials.md
@@ -1,6 +1,6 @@
 # How to work on tutorials
 
-The tutorials are saved and version controlled as .md files (md:myst format) in the
+The tutorials are saved and version controlled as `.myst.md` files (md:myst format) in the
 `docs` directory. They can be opened as standard text file with your favorite text
 editor. Moreover, these files can be opened as notebooks in Jupyter Lab. One needs to
 start Jupyter Lab from the `docs` directory. When [Jupytext] is installed, you should be

diff --git a/docs/how-to/archive-simulation-data.md b/docs/how-to/archive-simulation-data.md
@@ -0,0 +1,26 @@
+# How to make a compressed archive of simulation data
+
+Nek5000 simulations can generate a lot of data files. To reduce the strain in your HPC facility, it is often recommended:
+
+1. To limit the **number of files**
+1. Reduce the **disk usage**
+
+We can achieve both without erasing any data by using Snek5000 and efficient
+compression tools namely [`zstandard`](https://en.wikipedia.org/wiki/Zstd) and
+preferably
+[`bsdtar`](https://www.freebsd.org/cgi/man.cgi?query=bsdtar&sektion=1&format=html)
+(usually faster) if not [GNU `tar`](https://www.gnu.org/software/tar/). If
+unavailable some of these can be installed using conda / mamba:
+
+```bash
+conda install -c conda-forge zstandard tar
+```
+
+Once a simulation is done, you can create the archive using
+
+```bash
+cd path/to/sim
+snek-make archive
+```
+
+The module which does the archiving is described [here](snek5000.util.archive).
diff --git a/docs/how-to/control-fortran-warnings.md b/docs/how-to/control-fortran-warnings.md
@@ -0,0 +1,21 @@
+# How to control Fortran warnings during compilation
+
+By default Snek5000 suppresses the compilation warnings. This is because
+Nek5000 uses a lot of *legacy tricks* to achieve high performance which
+triggers warnings in modern C and Fortran compilers.
+
+To display the warnings one should adjust the `verbosity` keyword argument for
+[`Output.update_snakemake_config`](snek5000.output.base.Output.update_snakemake_config). For example
+in your solver's Snakemake file
+
+```{code-block} python
+---
+emphasize-lines: 6
+---
+from snek5000 import ensure_env, get_snek_resource
+from snek5000_canonical import short_name, Output
+
+configfile: "config_simul.yml"
+
+Output.update_snakemake_config(config, short_name, verbosity=1)
+```
diff --git a/docs/how-to/export-sans-snek5000.myst.md b/docs/how-to/export-sans-snek5000.myst.md
@@ -0,0 +1,84 @@
+---
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.14.1
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+# How to export a standalone source code archive which excludes Snek5000
+
+Add the following Snakemake rule to your solver's Snakefile (for example see
+[snek5000-phill]):
+
+```python
+from phill import short_name, Output
+
+# generate compile.sh
+# ===================
+rule generate_compile_sh:
+    output:
+        "compile.sh",
+    run:
+        from phill.templates import env
+
+        template = env.get_template("compile.sh.j2")
+        Output.write_compile_sh(template, config, path=output)
+
+
+# create a archive with source files
+# ==================================
+rule source_archive:
+    input:
+        f"{short_name}.box",
+        f"{short_name}.par",
+        f"{short_name}.usr",
+        "SIZE",
+        "compile.sh",
+        "makefile_usr.inc",
+        *list(Output().makefile_usr_sources),
+    output:
+        f"{short_name}-source_archive.tar.gz",
+    shell:
+        """
+        tar cvf {output} {input}
+        """
+```
+
+Now execute in an IPython console to generate source code from your templates
+and prescribed parameters.
+
+```{code-cell} python
+---
+tags: [hide-output]
+---
+from phill.solver import Simul
+
+params = Simul.create_default_params()
+# modify params if necessary
+sim = Simul(params)
+```
+
+Finally make the source code archive:
+
+```{code-cell} python
+---
+tags: [hide-output]
+---
+sim.make.exec('source_archive')
+```
+
+```{code-cell} python
+%mv {sim.path_run}/phill_source-archive.tar.gz .
+```
+
+This archive may now be shared to your colleagues or kept as a standalone
+archive which only depends on Nek5000 for compilation.
+
+[snek5000-phill]: https://github.com/snek5000/snek5000-phill/blob/main/src/phill/Snakefile
diff --git a/docs/how-to/history_points.md b/docs/how-to/history_points.md
@@ -10,7 +10,7 @@ params.output.history_points.coords: list[tuple[float, float, float] | tuple[flo
 ```
 
 For example, see the
-[parameters used in the tutorial for snek5000-cbox](../tuto_cbox.md#initialize-and-setup-simulation-parameters).
+[parameters used in the tutorial for snek5000-cbox](../tuto_cbox.myst.md#initialize-and-setup-simulation-parameters).
 
 This should be coupled along with a `hpts()` call in `userchk()` subroutine in the
 Nek5000 user file. For more information, see *documentation for
@@ -21,4 +21,4 @@ Nek5000 user file. For more information, see *documentation for
 Use `load*` and `plot*` methods in class
 {class}`snek5000.output.history_points.HistoryPoints`. A working example of this can be
 found in
-[a tutorial where we process results from a snek5000-cbox simulation](../tuto_cbox.md#postprocessing).
+[a tutorial where we process results from a snek5000-cbox simulation](../tuto_cbox.myst.md#postprocessing).
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -6,9 +6,13 @@
 ---
 maxdepth: 1
 ---
-restart.md
+run-background-foreground.md
+restart.myst.md
 history_points.md
 snek-make.md
+rebuild-nek.md
+export-sans-snek5000.myst.md
+archive-simulation-data.md
 ```
 
 ## For developer of Snek5000 solvers
@@ -17,4 +21,6 @@ snek-make.md
 ---
 maxdepth: 1
 ---
+control-fortran-warnings.md
+read-write-par-files.md
 ```
diff --git a/docs/how-to/read-write-par-files.md b/docs/how-to/read-write-par-files.md
@@ -0,0 +1,36 @@
+# How to read / write default parameter values from a `*.par` file
+
+Snek5000 is capable of parsing existing `*.par` files. This is shown in the [`snek5000-tgv` example](../examples/snek5000-tgv/src/snek5000_tgv/solver.py),
+
+```{code-block} python
+---
+emphasize-lines: 15-17
+---
+from snek5000.solvers.base import SimulNek
+from snek5000.params import complete_params_from_par_file
+
+
+class SimulTGV(SimulNek):
+    ...
+    @classmethod
+    def create_default_params(cls):
+        ...
+
+        # Read defaults for `params.nek` from `tgv.par.cfg` (original code)
+        info_solver = cls.info_solver  # cls.InfoSolver()
+        output_cls = info_solver.import_classes()["Output"]
+        root = output_cls.get_root()
+        complete_params_from_par_file(
+            params, root / f"{info_solver.short_name}.par.cfg"
+        )
+```
+
+This is useful while porting an existing Nek5000 code as a Snek5000 solver.
+[See the function's
+documentation](snek5000.params.complete_params_from_par_file) for more details.
+
+```{note}
+In Snek5000 we follow a convention of renaming the `*.par` file as `*.par.cfg`
+in the common source code file to distinguish from the generated `*.par` file
+for a specific simulation.
+```
diff --git a/docs/how-to/rebuild-nek.md b/docs/how-to/rebuild-nek.md
@@ -0,0 +1,13 @@
+# How to rebuild Nek5000 libraries and tools
+
+For a fresh git clone of Nek5000 sources, Snek5000 takes care of the build
+automatically. However if your C and Fortran compiler with its related
+toolchain gets an update, or if you change it intentionally you may need to
+recompile Nek5000 libraries again. To do so:
+
+```sh
+cd $NEK_SOURCE_ROOT
+git clean -xdf
+```
+
+Next time you execute a Snek5000 solver, the libraries would be rebuild.
diff --git a/docs/how-to/restart.md → docs/how-to/restart.myst.md b/docs/how-to/restart.md → docs/how-to/restart.myst.md
@@ -12,7 +12,7 @@ kernelspec:
   name: python3
 ---
 
-# Restart simulations
+# How to restart simulations
 
 Restarting simulations with Nek5000 can be tricky. For example, it is easy to erase some
 results from the initial simulation! To fix this issue Snek5000 uses the notion of
@@ -47,7 +47,7 @@ Let's give few examples. We start from a simulation using the `snek5000-phill` s
    ```
 
    ```{note}
-   This method is used in [the tutorial using our snek5000-tgv solver](../tuto_tgv.md#restart-to-run-further).
+   This method is used in [the tutorial using our snek5000-tgv solver](../tuto_tgv.myst.md#restart-to-run-further).
    ```
 
 1. To restart the simulation in a new session (no compilation needed) from the

diff --git a/docs/how-to/run-background-foreground.md b/docs/how-to/run-background-foreground.md
@@ -0,0 +1,36 @@
+# How to run a simulation in the foreground / background
+
+By default, executing a simulation as
+
+```{code-block} python
+---
+emphasize-lines: 5
+---
+from snek5000_canonical.solver import Simul
+
+params = Simul.create_default_params()
+sim = Simul(params)
+sim.make.exec('run')
+```
+
+would launch the Snakemake rule `run` (default, if not specified) which
+launches a simulation in the **background** and returns control to the user.
+This is useful in monitoring the simulation. For example see the [tutorial for
+snek5000-cbox](../tuto_cbox).
+
+However in HPC clusters you should launch your simulations in the
+**foreground**, thus preventing the job from exiting while the simulation is
+going on. You can also specify number of MPI processes using the `nproc` keyword argument. For example:
+
+```{code-block} python
+---
+emphasize-lines: 5
+---
+nb_nodes = 2
+nb_procs_per_node = 32
+
+sim.make.exec(
+    'run_fg',
+    nproc=nb_nodes * nb_procs_per_node
+)
+```
diff --git a/docs/how-to/snek-make.md → docs/how-to/snek-make.myst.md b/docs/how-to/snek-make.md → docs/how-to/snek-make.myst.md
diff --git a/docs/tuto_cbox.md → docs/tuto_cbox.myst.md b/docs/tuto_cbox.md → docs/tuto_cbox.myst.md
diff --git a/docs/tuto_phill.md → docs/tuto_phill.myst.md b/docs/tuto_phill.md → docs/tuto_phill.myst.md
diff --git a/docs/tuto_phill_setup.md → docs/tuto_phill_setup.myst.md b/docs/tuto_phill_setup.md → docs/tuto_phill_setup.myst.md
diff --git a/docs/tuto_tgv.md → docs/tuto_tgv.myst.md b/docs/tuto_tgv.md → docs/tuto_tgv.myst.md
diff --git a/noxfile.py b/noxfile.py
@@ -36,7 +36,10 @@
 try:
     NEK_SOURCE_ROOT = os.environ["NEK_SOURCE_ROOT"]
 except KeyError:
-    raise RuntimeError("NEK_SOURCE_ROOT has point to Nek5000 top level directory.")
+    raise RuntimeError(
+        "Environment variable NEK_SOURCE_ROOT should be set "
+        "pointing to Nek5000 top level directory."
+    )
 
 TEST_ENV_VARS = {
     "NEK_SOURCE_ROOT": NEK_SOURCE_ROOT,