Improve tutorials

docs/examples/scripts/tuto_phill.py

@@ -1,5 +1,3 @@
-# import os
-
 from phill.solver import Simul
 
 params = Simul.create_default_params()
@@ -20,6 +18,4 @@
 
 sim = Simul(params)
 
-# os.environ["SNEK_DEBUG"] = "1"
-
 sim.make.exec("run_fg", nproc=2)

docs/tuto_phill_make.myst.md

@@ -0,0 +1,123 @@
+---
+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
+---
+
+<!-- #region tags=[] -->
+
+# Second step with `snek5000-phill`: Snakemake rules
+
+<!-- #endregion -->
+
+## Initialization of the simulation (recap)
+
+In the previous tutorial [](../tuto_phill_setup.md), we saw how to setup a simulation
+run. Let us do it here in one step.
+
+```{code-cell} ipython3
+from phill.solver import Simul
+
+params = Simul.create_default_params()
+params.output.sub_directory = "examples_snek/tuto"
+params.oper.nx = 6
+params.oper.ny = 5
+params.oper.nz = 4
+params.oper.elem.order = params.oper.elem.order_out = 10
+
+params.oper.nproc_min = 2
+
+params.nek.general.num_steps = 10
+params.nek.general.time_stepper = "bdf2"
+params.nek.general.write_interval = 10
+
+params.nek.stat.av_step = 3
+params.nek.stat.io_step = 10
+
+sim = Simul(params)
+```
+
+We recall that this instanciation of the class `Simul` creates the simulation directory
+on the disk with the following files:
+
+```{code-cell} ipython3
+!ls {sim.path_run}
+```
+
+## Execute the simulation with Snakemake rules
+
+### Snakemake rules
+
+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} ipython3
+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.
+
+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)
+
+Hence, the most standard method to launch a simulation with Snek5000 is to call
+
+```python
+sim.make.exec("run_fg", nproc=2)
+```
+
+In the next tutorial [](../tuto_phill_script.md), we will do it from a script and see
+what happens, but we can already guess that all the Snakemake rules necessary for the
+simulation are going to be executed.
+
+```{note}
+
+In real life, simulations are usually submitted with Snek5000 from a script and
+we are going to call Snakemake with the [exec](snek5000.make.Make.exec)
+method.
+
+However, there is also a command `snek-make` that can be run from the
+simulation directory to list and invoke the Snakemake rules. See `snek-make -h`
+and `snek-make -l`.
+
+```
+
+<!-- #region tags=[] -->
+
+### Debug mode
+
+During development, it can be useful to turn on the debug environment variable which can
+be done in Python with:
+
+<!-- #endregion -->
+
+```python
+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`

docs/tuto_phill.myst.md → docs/tuto_phill_script.myst.md

@@ -14,105 +14,11 @@ kernelspec:
 
 <!-- #region tags=[] -->
 
-# Demo periodic hill (snek5000-phill solver)
+# Demo periodic hill (`snek5000-phill` solver): running a simulation from a script
 
 <!-- #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.
-
-```{code-cell} ipython3
-from phill.solver import Simul
-
-params = Simul.create_default_params()
-params.output.sub_directory = "examples_snek/tuto"
-params.oper.nx = 6
-params.oper.ny = 5
-params.oper.nz = 4
-params.oper.elem.order = params.oper.elem.order_out = 10
-
-params.oper.nproc_min = 2
-
-params.nek.general.num_steps = 10
-params.nek.general.time_stepper = "bdf2"
-params.nek.general.write_interval = 10
-
-params.nek.stat.av_step = 3
-params.nek.stat.io_step = 10
-
-sim = Simul(params)
-```
-
-We recall that this instanciation of the class `Simul` creates the simulation directory
-on the disk with the following files:
-
-```{code-cell} ipython3
-!ls {sim.path_run}
-```
-
-## Execute the simulation
-
-### Snakemake rules
-
-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} ipython3
-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.
-
-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)
-
-```{note}
-
-In real life, simulations are usually submitted with Snek5000 from a script and
-we are going to call Snakemake from the Snek5000 Python API with a call similar
-to `sim.make.exec("run_fg", nproc=2)` (as in the following example).
-
-However, there is also a command `snek-make` that can be run from the
-simulation directory to list and invoke the Snakemake rules. See `snek-make -h`
-and `snek-make -l`.
-
-```
-
-<!-- #region tags=[] -->
-
-### Debug mode
-
-During development, it can be useful to turn on the debug environment variable which can
-be done in Python with:
-
-<!-- #endregion -->
-
-```python
-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`
-
-### Execution of the main script
+## Execution of the script
 
 Now let's execute the simulation. We will use the script
 [docs/examples/scripts/tuto_phill.py](https://github.com/snek5000/snek5000/tree/main/docs/examples/scripts/tuto_phill.py),
@@ -123,7 +29,8 @@ which contains:
 ```
 
 In normal life, we would just execute this script with something like
-`python tuto_phill.py`. However, in this notebook, we need a bit more code:
+`python tuto_phill.py`. However, in this notebook, we need a bit more code. This is
+specific to these tutorials so you can just look at the output of this cell.
 
 ```{code-cell} ipython3
 from subprocess import run, PIPE, STDOUT
@@ -230,9 +137,3 @@ hexa_data_stat.elem[0].scal.shape
 ```{code-cell} ipython3
 sim.output.phys_fields.plot_hexa_stat(key="scalar 8", vmin=-0.4, vmax=0.4)
 ```
-
-## Versions used in this tutorial
-
-```{code-cell} ipython3
-!snek-info
-```

docs/tuto_phill_setup.myst.md

@@ -14,17 +14,17 @@ kernelspec:
 
 <!-- #region tags=[] -->
 
-# First steps with `snek5000-phill`: setting up a simulation
+# First step with `snek5000-phill`: setting up a simulation
 
 ## Installation of `snek5000-phill`
 
 The
 [Nek5000 phill example](https://github.com/KTH-Nek5000/KTH_Examples/tree/master/phill_STAT)
 (`phill` means periodic hill) has been adapted for a workflow using Snek5000. We created
 [a small Python project called `snek5000-phill`](https://pypi.org/project/snek5000-phill/)
-using the Snek5000 API to define the `phill` case. In this tutorial and in the tutorial
-[](../tuto_phill.md), we will show how this solver can be used. Let's first recall that
-the installation procedure looks like this:
+using the Snek5000 API to define the `phill` case. In this tutorial and in the tutorials
+[](../tuto_phill_make.md) and [](../tuto_phill_script.md), we will show how this solver
+can be used. Let's first recall that the installation procedure looks like this:
 
 ```sh
 export NEK_SOURCE_ROOT="/path/to/Nek5000"
@@ -100,7 +100,7 @@ params.nek.stat.av_step = 3
 params.nek.stat.io_step = 10
 ```
 
-## Creation of the simulation directory
+## Creation of the simulation object and directory
 
 Now let's create the simulation object (We usually use the name `sim`.):
 
@@ -126,13 +126,3 @@ Let's check that the `.par`, `.box` and `SIZE` files are present:
 ```{code-cell}
 !ls {sim.path_run}
 ```
-
-<!-- #region tags=[] -->
-
-## Versions used in this tutorial
-
-<!-- #endregion -->
-
-```{code-cell}
-!snek-info
-```

docs/tutorials.md

@@ -1,3 +1,17 @@
+---
+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
+---
+
 # Tutorials
 
 ```{admonition} Preliminary: introduction on Nek5000 classical workflow
@@ -15,21 +29,29 @@ manual file manipulations are necessary.
 
 Then, some output files can be analyzed and used to produce figures and movies.
 
-Snek5000 is a unified framework providing a Python API and commands to help us
-for these different steps. These tutorials present how it work in practice.
+Snek5000 is a unified framework providing a Python API and shell commands to
+help us for these different steps. These tutorials present how it works in
+practice.
+
+```
+
+**Versions used in these tutorials:**
 
+```{code-cell} ipython3
+!snek-info
 ```
 
 ```{toctree}
 ---
 maxdepth: 2
 ---
-tuto_phill_setup.md
-configuring
-tuto_phill.md
-tuto_tgv.md
-tuto_cbox.md
-packaging.rst
+tuto_phill_setup.myst.md
+tuto_phill_make.myst.md
+tuto_config.rst
+tuto_phill_script.myst.md
+tuto_tgv.myst.md
+tuto_cbox.myst.md
+tuto_packaging.rst
 ```
 
 The snek5000-cbox repository contains