Merge pull request #161 from snek5000/doc

Doc improvements

CHANGELOG.md

@@ -78,14 +78,13 @@ Security in case of vulnerabilities.
 - {meth}`snek5000.output.base.Output.get_configfile` (use a string `"config_simul.yml"`
   instead in user Snakefile).
 - The `warnings` parameter in
-  {meth}`snek5000.output.base.Output.update_snakemake_config` is deprecated!
-  Use `verbosity=0` (now default) to disable warnings.
+  {meth}`snek5000.output.base.Output.update_snakemake_config` is deprecated! Use
+  `verbosity=0` (now default) to disable warnings.
 
 ### Removed
 
-- Parameter `warnings` in {func}`snek5000.util.smake.append_debug_flags` is
-  replaced by a separate function
-  {func}`snek5000.util.smake.set_compiler_verbosity`.
+- Parameter `warnings` in {func}`snek5000.util.smake.append_debug_flags` is replaced by
+  a separate function {func}`snek5000.util.smake.set_compiler_verbosity`.
 
 ### Fixed
 

docs/configuring.rst

@@ -19,17 +19,18 @@ You are expected to keep one configuration file for per machine / cluster where
 ``snek5000`` is executed. When a file is not found during runtime it issues a
 warning similar to::
 
-   WARNING  Missing a configuration file describing compilers and flags. Create one at either of the following paths to avoid future warnings:
-            /home/avmo/.config/snek5000/<hostname>.yml
-            /home/avmo/.config/snek5000.yml
-            /home/avmo/src/snek5000/snek5000-canonical/src/snek5000_canonical/etc/<hostname>.yml
+   WARNING: Missing a configuration file describing compilers and flags. Create one at either of the following paths to avoid future warnings:
+      /home/docs/.config/snek5000/<hostname>.yml
+      /home/docs/.config/snek5000.yml
+      /home/docs/src/snek5000/snek5000-canonical/src/snek5000_canonical/etc/<hostname>.yml
    INFO     Using default configuration for now:
-            /home/avmo/src/snek5000/snek5000/src/snek5000/assets/default_configfile.yml
+      /home/docs/src/snek5000/snek5000/src/snek5000/assets/default_configfile.yml
 
-As the warnings suggest, there are two possible paths where you can save your configuration:
+As the warnings suggest, there are three possible paths where you can save your configuration:
 
 1. ``~/.config/snek5000/<hostname>.yml``
-2. ``<path to package root>/etc/<hostname>.yml``
+2. ``~/.config/snek5000.yml``
+3. ``<path to package root>/etc/<hostname>.yml``
 
 .. note::
 

docs/tuto_cbox.md

@@ -106,19 +106,18 @@ from snek5000 import load
 sim = load(sim.path_run)
 ```
 
-then we are able to  plot all the history points for one variable like $u_x$,
+then we are able to plot all the history points for one variable like $u_x$,
 
 ```{code-cell}
 sim.output.history_points.plot(key='ux')
-
 ```
 
 or just one history point:
 
 ```{code-cell}
-
-sim.output.history_points.plot_1point(index_point=0, key='temperature', tmin=600, tmax=800)
-
+sim.output.history_points.plot_1point(
+  index_point=0, key='temperature', tmin=600, tmax=800
+)
 ```
 
 Also we can load the history points data to compute growth rate:

docs/tuto_phill.md

@@ -10,14 +10,15 @@ execution:
 ---
 
 <!-- #region tags=[] -->
+
 # Demo periodic hill (snek5000-phill)
 
 <!-- #endregion -->
 
 ## Initialize and setup up simulation parameters (recap)
 
-
-In the previous tutorial we saw how to install the packages and setup a simulation run. Let us do it here in one step.
+In the previous tutorial we saw how to install the packages and setup a simulation run.
+Let us do it here in one step.
 
 ```{code-cell}
 from phill.solver import Simul
@@ -46,45 +47,48 @@ sim = Simul(params)
 
 ## Execute the simulation
 
-To run the simulation we need to execute certain commands. These are described
-using [snakemake](https://snakemake.rtfd.io) in the Snakefile. Let's look at
-the rules defined in the Snakefile (which are nearly generic for any Nek5000
-case).
+To run the simulation we need to execute certain commands. These are described using
+[snakemake](https://snakemake.rtfd.io) in the Snakefile. Let's look at the rules defined
+in the Snakefile (which are nearly generic for any Nek5000 case).
 
 ```{code-cell}
 sim.make.list()
 ```
 
-The rules in the Snakefile are either shell commands or Python code which
-handle different parts of the build step, such as building a mesh (rule
-`mesh`), compiling (rule `compile`) and running the simulation (rule `run` or
-`run_fg`). The rules can be executed on by one by passing them as strings to
-the [exec](snek5000.make.Make.exec) method of the `sim.make` object. The
-default parameter is to do everything to run a simulation.
+The rules in the Snakefile are either shell commands or Python code which handle
+different parts of the build step, such as building a mesh (rule `mesh`), compiling
+(rule `compile`) and running the simulation (rule `run` or `run_fg`). The rules can be
+executed on by one by passing them as strings to the [exec](snek5000.make.Make.exec)
+method of the `sim.make` object. The default parameter is to do everything to run a
+simulation.
 
 From a user's perspective the following rules are essential:
+
 - `compile`: Only compile the executable
 - `run`: Run the simulation in the background (non-blocking)
-- `run_fg`: Run the simulation in the foreground (blocking, till the simulation is over / terminated)
+- `run_fg`: Run the simulation in the foreground (blocking, till the simulation is over
+  / terminated)
 
 <!-- #region tags=[] -->
+
 ### Debug mode
 
 During development, it is useful to turn on the debug environment variable.
+
 <!-- #endregion -->
 
 ```{code-cell}
 import os
 os.environ["SNEK_DEBUG"] = "1"
 ```
 
-The equivalent of this in the shell command line would be ``export
-SNEK_DEBUG=1``. By doing so, snek5000 would:
-
-- perform stricter compile time checks. See {func}`snek5000.util.smake.append_debug_flags`
-- activate the code blocks under the preprocessing flag in Fortran sources `#ifdef DEBUG`
-
+The equivalent of this in the shell command line would be `export SNEK_DEBUG=1`. By
+doing so, snek5000 would:
 
+- perform stricter compile time checks. See
+  {func}`snek5000.util.smake.append_debug_flags`
+- activate the code blocks under the preprocessing flag in Fortran sources
+  `#ifdef DEBUG`
 
 Now let's execute the simulation
 
@@ -113,6 +117,7 @@ snakemake.__version__
 import snek5000
 snek5000.__version__
 ```
+
 ```{code-cell}
 import phill
 phill.__version__

docs/tuto_phill_setup.md

@@ -10,21 +10,26 @@ execution:
 ---
 
 <!-- #region tags=[] -->
-# First step with snek5000-phill: setting up the simulation
 
-The [phill example](https://github.com/KTH-Nek5000/KTH_Examples/tree/master/phill_STAT) has been adapted for a workflow using snek5000 and pymech. Here we will show how a workflow looks like. To get started, we install everything we need:
+# First steps with snek5000-phill: setting up the simulation
+
+The
+[Nek5000 phill example](https://github.com/KTH-Nek5000/KTH_Examples/tree/master/phill_STAT)
+has been adapted for a workflow using snek5000. Here we will show how this workflow
+looks like. To get started, we install everything we need:
 
 ```sh
 python -m venv venv
 source venv/bin/activate
-pip install snek5000 pymech -e "git+https://github.com/snek5000/snek5000-phill#egg=phill"
+pip install -e "snek5000-phill @ git+https://github.com/snek5000/snek5000-phill.git"
 ```
 
 ```{note}
 The repository `snek5000-phill` provides a Python package `phill` - the same
 name as the `usr` files. More on packaging Nek5000 files can be found in the
 {ref}`packaging tutorial <packaging>`.
 ```
+
 <!-- #endregion -->
 
 ## Initialize and setup up simulation parameters
@@ -35,29 +40,46 @@ from phill.solver import Simul
 params = Simul.create_default_params()
 ```
 
-The `params` object gives you a consolidated view of the parameters which are spread out in a typical Nek5000 case into `.par`, `.box` and `SIZE` file.  Already we seen that the parameters are more verbose, easier to understand. As a bonus, some parameters which depend on others are automatically set. For example, see {py:mod}`snek5000.operators`.
+The `params` object gives you a consolidated view of the parameters which are spread out
+in a typical Nek5000 case into `.par`, `.box` and `SIZE` file. Already we seen that the
+parameters are more verbose, easier to understand. As a bonus, some parameters which
+depend on others are automatically set. For example, see {py:mod}`snek5000.operators`.
+
+Now let us take a look at all the compilation parameters that we can modify. In a
+console the params would also output as follows:
+
+```{code-cell}
+params
+```
 
-Now let us take a look at all the compilation parameters that we can modify. In a console the params would also output as follows:
+One can also print only one section:
 
 ```{code-cell}
-print(params)
+params.nek.general
 ```
 
-One can print some help about some parameters. For example, for `params.oper`:
+and print some help about some parameters:
 
 ```{code-cell}
 params.oper._print_docs()
 ```
 
-The parameters can be modified. For instance, let us tweak the number of elements, time-stepping and I/O parameters
+```{warning}
+The same object `params` can also be obtained from a simulation object (with
+`sim.params`), but the help on the parameters can only be printed from `params`
+objects obtained from `Simul.create_default_params()`.
+```
+
+The parameters can be modified. For instance, let us tweak the number of elements,
+time-stepping and I/O parameters
 
 ```python
-# This affects both the box and SIZE files
+# This affects both the .box and SIZE files
 params.oper.nx = 12
 params.oper.ny = 10
 params.oper.nz = 8
 
-# This affects the par file
+# This affects the .par file
 params.nek.velocity.residual_tol = 1e-8
 params.nek.pressure.residual_tol = 1e-6
 params.nek.general.num_steps = 10
@@ -68,19 +90,30 @@ params.nek.stat.av_step = 3
 params.nek.stat.io_step = 10
 ```
 
-Now initialize the simulation. This would copy the files based on the templates we have specified.
+Now let's initialize the simulation. This is going to create the files based on the
+templates we have specified.
 
 ```{code-cell}
 sim = Simul(params)
+```
+
+A directory has been created with all the files necessary to compile and run the
+simulation:
+
+```{code-cell}
 sim.path_run
 ```
 
+Let's check that the .par, .box and SIZE file are present:
+
 ```{code-cell}
 !ls {sim.path_run}
 ```
 
 <!-- #region tags=[] -->
+
 ## Versions used in this tutorial
+
 <!-- #endregion -->
 
 ```{code-cell}
@@ -92,6 +125,7 @@ snakemake.__version__
 import snek5000
 snek5000.__version__
 ```
+
 ```{code-cell}
 import phill
 phill.__version__

docs/tuto_tgv.md

@@ -15,7 +15,9 @@ execution:
 
 ## Run the simulation
 
-See [`snek5000-tgv`](https://github.com/snek5000/snek5000/tree/main/docs/examples/snek5000-tgv) for the implementation. The simulation was executed as follows:
+See
+[`snek5000-tgv`](https://github.com/snek5000/snek5000/tree/main/docs/examples/snek5000-tgv)
+for the implementation. The simulation was executed as follows:
 
 ```{code-cell}
 from snek5000_tgv.solver import Simul
@@ -42,6 +44,7 @@ sim.make.exec("run_fg", resources={"nproc": 2})
 ## Load the simulation
 
 Here we load and process the output.
+
 <!-- #endregion -->
 
 ```{code-cell}
@@ -50,9 +53,12 @@ from snek5000 import load
 sim = load(sim.path_run)
 ```
 
-## Visualize raw data via ``sim.output.print_stdout``
+## Visualize raw data via `sim.output.print_stdout`
 
-In subroutine `userchk` of `tgv.usr.f`, the time stamp, kinetic energy and enstrophy are output into standard output, with a keyword `monitor` at the end of the line. We can use regular expressions to extract these lines. If you are new to regular expressions, this website can help you <https://regex101.com/>.
+In subroutine `userchk` of `tgv.usr.f`, the time stamp, kinetic energy and enstrophy are
+output into standard output, with a keyword `monitor` at the end of the line. We can use
+regular expressions to extract these lines. If you are new to regular expressions, this
+website can help you <https://regex101.com/>.
 
 ```{code-cell}
 import re
@@ -61,7 +67,8 @@ monitor = re.findall('(.*)monitor$', sim.output.print_stdout.text, re.MULTILINE)
 monitor
 ```
 
-It is also possible to achieve the same using Python's string manipulation and list comprehension:
+It is also possible to achieve the same using Python's string manipulation and list
+comprehension:
 
 ```{code-cell}
 monitor = [
@@ -105,7 +112,7 @@ ref.plot(
     logy=True,
     colormap="Accent"
 )
-_ = ax.set(
+ax.set(
     title=f"Taylor-Green vortex: evolution of K.E. and enstrophy. Re={-sim.params.nek.velocity.viscosity}"
-)
+);
 ```

requirements/docs.txt

@@ -241,6 +241,7 @@ numpy==1.23.4
     #   h5py
     #   matplotlib
     #   pandas
+    #   scipy
     #   xarray
 packaging==21.3
     # via
@@ -344,6 +345,8 @@ requests==2.28.1
     #   sphinx
 reretry==0.11.1
     # via snakemake
+scipy==1.9.3
+    # via snek5000 (setup.cfg)
 send2trash==1.8.0
     # via jupyter-server
 setuptools-scm==7.0.5