version 0.5.0
How to run Notus

The following guidelines describes the different ways to run Notus.

Basic way to run Notus

Notus runs only through mpirun command, at least on 1 processor. The description of physical case to simulate is present in an _.nts_ file of one of the test_cases subdirectory that must given on the command-line. For instance, to run Notus on 8 processors and solve the Poiseuille flow, the command is:

mpirun -np 8 notus test_cases/verification/navier/poiseuille.nts

Notus full help:

usage: notus [OPTIONS] [--] CASE_FILE

CASE_FILE               Notus case file (*.nts)

OPTIONS

-D TYPE:IDENT=VALUE     Define an identifier outside the Notus case file
                        TYPE: integer|double|boolean|string
                        IDENT: identifier name
                        VALUE: identifier value corresponding to the type

-h, --help              Display help and exit

-t NUM, --thread NUM    Use NUM OpenMP threads. Has no effect if Notus is compiled without OpenMP.

--no-banner             Do not display Notus banner

--no-color              Disable the use of ANSI color codes

--cpu-time-file FILE    File where the CPU time is output

--validation-file FILE  File where the validation is output

Advanced ways to run Notus with the script notus.py

The script notus.py enables one to run Notus in two different modes : Non-regression and Run

Here is Notus help, which presents only the different modes available:

usage: notus.py [-h] {non-regression, run} ...

positionnal arguments:
    {non-regression, run}  Sub-command help
    non-regression         Run Notus non-regression tests
    run                    Execute Notus

optional arguments:
    -h, --help         Show this help message and exit

Information about the options of these modes can be found in the following subparagraphs.

Non-regression mode

It is possible to run all or a part of the non regression tests, composed with verification and validation test cases (Verification and Validation) as well as various tests, thanks to the notus.py script. It is useful to check Notus portal on a new computer or to validate new developments.

Notus full help in Non-regression mode:

Usage: notus.py non-regression [-h] [-r REGEXP] [-s] [-f] [-m MPI_COMMAND]
                               [-o OUTPUT] [-b {black,white}] [-P PBS] [-S SLURM]
                               [--no-color] [-v]

Optional arguments:

    -h, --help                                    show this help message and exit
    -r REGEXP, --regexp REGEXP                    filter test cases using a regular expression
    -s, --sequential                              enable sequential non-regression tests
    -f, --full                                    enable full non-regression tests
    -m MPI_COMMAND, --mpi-command MPI_COMMAND     MPI command (default: mpirun)
    -o OUTPUT, --output OUTPUT                    output directory of log files
    -b {black,white}, --background {black,white}  colors for display are chosen according to the color of the background (default: black)
    -P PBS, --PBS PBS                             launch non-regression using a batch system (PBS)
    -S SLURM, --SLURM SLURM                       launch non-regression using a batch system (SLURM)
    --no-color                                    Disable the use of ANSI color codes
    -v, --verbose                                 Diplay output

Since the script detects automatically the test cases to use, if you want to test only some of them, you will have to use the -r argument to filter those cases.

The full non-regression is possible thanks to the syntax introduced in every NTS file that makes it possible to run the same test case several times (to rotate the direction of flow for instance). For further information about this, see Add a test case to Notus test case bank

The SLURM template is yet to be written, which means that the non-regression using SLURM batch system is not available for now.

Results can be compared to some obtained on different hardware and software architecture present in the test_cases/results directory.

Run mode

It is the mode to use if you want to execute Notus.

Here is Notus full help for this mode:

usage: notus.py run [-h] [-n PROCS_NUMBER] [-f] [-m MPI_COMMAND] [-o OUTPUT]
                    [-b {black,white}] [-P PBS] [-S SLURM] [--no-color] [-v]
                    NTS_FILES [NTS_FILES ...]

positional arguments:
    NTS_FILES                                     Notus input files (.nts)

optional arguments:
    -h, --help                                    Show this help message and exit
    -n PROCS_NUMBER, --procs-number PROCS_NUMBER  Number of processors used tu run Notus
    -f, --full                                    Enable full validation
    -m MPI_COMMAND, --mpi-command MPI_COMMAND     MPI command (default: mpirun)
    -o OUTPUT, --output OUTPUT                    Output directory of log files
    -b {black,white}, --background {black,white}  Colors for display are chosen according to the color of the background (default: black)
    -P PBS, --PBS PBS                             Launch validation using a batch system (PBS)
    -S SLURM, --SLURM SLURM                       Launch validation using a batch system (SLURM)
    --no-color                                    Disable the use of ANSI color codes
    -v, --verbose                                 Diplay output

The only new argument here compared to the Non-regression mode is the number of processors that the user wants to use for the execution of Notus.

Run a mesh convergence study

When developing numerical methods, it is important to check its spatial convergence order. To do this, if an exact solution of the problem exists, the dependency of the solution error as a function of the mesh refinement can be studied. Typically, if one refines the mesh by a factor 2 in each direction, if the numerical method is at 2nd order, the error should decreased by a factor 4.

The script notus_grid_convergence is helpful for such kind of study. It runs several times the code, changing the mesh size each time, and computes automatically the convergence order.

First, a _.grid_convergence.json_ file that contains the different mesh sizes have to be created in the directory that contains the _.nts_ file. The fisrt part of the file name must be the same than the one of the _.nts_ file. Below an example of a _.grid_convergence.json_ file:

[
    {"number_of_cells": [ 16, 16]},
    {"number_of_cells": [ 32, 32]},
    {"number_of_cells": [ 64, 64]},
    {"number_of_cells": [128,128]},
    {"number_of_cells": [256,256]},
    {"number_of_cells": [512,512]}
]

Eventually, time step can also be given in the _.grid_convergence.json_ file:

[
    {"number_of_cells": [  40,  16], "time_step": 0.3656250},
    {"number_of_cells": [  80,  32], "time_step": 0.2728125},
    {"number_of_cells": [ 160,  64], "time_step": 0.17578125},
    {"number_of_cells": [ 320, 128], "time_step": 0.13359375}
]

Then, the _.nts_ file have to be modified. For instance, in its post_processing block, in order to compute the error on the temperature and to enable the grid convergece study, one have to add the following lines:

compute_error temperature;
enable_grid_convergence true;
grid_convergence_file "raw_grid_convergence";
grid_convergence_quantities error_temperature;

Then, the script can be executed:

./notus_grid_convergence -np 8 test_cases/verification/laplacian/ibm/dirichlet.nts

At the end of the execution, in the output directory relative to the _.nts_ file, the raw_grid_convergence file contains the convergence study results:

    Conv? Temperature Linf error        Temperature L1 error          Temperature L2 error
16  N/A   +3.89838295157308e-03    +nan +7.00347336404399e-03    +nan +4.50838553065628e-03    +nan
32  N/A   +9.70249207645768e-04  +2.006 +2.07071610951175e-03  +1.758 +1.29125807033986e-03  +1.804 
64  N/A   +2.50782543541384e-04  +1.952 +4.60099280625383e-04  +2.170 +2.92047547289175e-04  +2.145 
128 N/A   +6.30554131784145e-05  +1.992 +1.21145071157781e-04  +1.925 +7.63404019645710e-05  +1.936 
256 N/A   +1.64327856615465e-05  +1.940 +2.99795764731030e-05  +2.015 +1.89298091593766e-05  +2.012 

Below a complete usage description of the script:

usage: notus_grid_convergence [-h] [-C] [-w] [--ignore-timestep]
                              [-np PROC_NUMBER] [-d] [--doxygen]
                              name

Perform the spatial convergence test of a given Notus test case. It uses the
test case input file <name>.nts and the description of the convergence test
<name>.grid_convergence.json.

positional arguments:
  name                  <case-path-name>[ .nts | .grid_convergence.json ].

optional arguments:
  -h, --help            show this help message and exit
  -C, --check-input-files
                        print generated NTS files, instead of running
                        convergence
  -w, --write-fields    leaves notus write fields
  --ignore-timestep     do not consider time_step instructions. Currently has
                        no effect.
  -np PROC_NUMBER, --proc-number PROC_NUMBER
                        set the number of processor to use instead of the
                        default.
  -d, --dplace          using dplace to submit jobs.
  --doxygen             format output into Doxygen format

Use pydoc notus_grid_convergence for detailed information.