version 0.5.0
How to add a test case to Notus test case bank

The following guidelines will help you to add a test case to Notus test case bank.

Test case type

A Notus test case is based on a NTS file and, eventually, some Fortran routines that compute initialization, boundary conditions, post-processing, etc. that cannot be done within the NTS file. Solution of a test case is also checked automatically at each release of the code by running the validation script. Finally, documentation should be written.

The next sections helps to realize these points.

Add an <em>NTS</em> file to the adequate directory

Test case are separated into verification and validation test cases:

  • The verification topic provides a set of test cases that aim to verify the base numerical methods. Precise convergence is verified, symmetry is tested. It is mainly a mathematical and computer work.
  • The validation topic provides a set of test cases that aim to validate the usability of the code on typical, advanced and well documented physical cases taken from the literature. They can be used to compare results obtained with other CFD codes.

So, you have to put your NTS file in test_cases/verification or test_cases.validation directory.

Within each directory, you will find subdirectories where you can copy your file (or create a new category if necessary). For instance:

$ ls verification/
cell_advection_schemes  laplacian  linear_system_test  navier  phase_advection  species_transport  surface_tension
$ ls validation/
free_convection  laminar_flows  mixed_convection  multiphase  thermosolutal  turbulent_flow

We will name your_test_case_category this directory.

For more clarity, make sure that your NTS file has the suffix *_2D* or *_3D* before the NTS extension.

Associated documentation

The test case should be validated precisely against exact solution, numerical solution or experimental data. Once this work is done, the associated documentation that presents the test case and the obtained solutions are written in a doc.f90 file. This file is put in src/notus/test_cases/your_test_case_category/your_test_case_directory, where your_test_case_directory matches the NTS file without the extension.

Check the solution automatically

For each equation solved, a reference solution can be obtained during the validation process of the test case (the mean velocity magnitude, the mean temperature, the mean species concentration, and/or the mean volume). These reference values, as well as a tolerance value, are entered in the NTS file in the post_processing block:

post_processing {
        validation {
        tolerance 1.d-13;
        reference_mean_temperature 2.999999999997118E+02;
        reference_mean_velocity_magnitude 3.7921755054867766E-03;
        reference_mean_volume_fraction 3.7921755054867766E-03;
        reference_mean_concentration 3.7921755054867766E-03;

After its creation, a new test case is nowhere to be listed. Indeed, the script will determine by itself the test cases required for the execution of the process chosen by the user (Validation or Run). At each new execution of the code, the solution is checked against the referenced one, and the test case is validated if the error is below the tolerance value.

Execute a set of parameters

Sometimes, you may want to execute more than a specific case determined by a specific set of parameters. Indeed, you may have to deal with variables that can take several values. All of these cases can be executed during the same process if variables are defined with the following syntax, where values_list can be any list generator of Python:

# @PARAMETER variable_type variable_name values_list

You can even filter the values taken by the variable:

# @PARAMETER integer variable [n for n in range(10) if n%2 == 0]

This syntax will return a list of integers between 0 and 9 where all odd numbers have been removed.

Notus will create as many jobs as there are possible combinations of the values taken by the variables. For instance:

# @PARAMETER integer dimension [1,2]
# @PARAMETER string advection_scheme ['upwind_o1','weno5']

Notus will treat all the following cases: dimension = 1 and advection_scheme = 'upwind_o1', dimension = 1 and advection_scheme = 'weno5', dimension = 2 and advection_scheme = 'upwind_o1' and dimension = 2 and advection_scheme = 'weno5'.

If you want to use several solvers, values_list needs to be replaced since the list of all the solvers available will be automatically determined by the script.

# @PARAMETER string solver_name @SOLVER

Of course, the code can still be executed with the parameters defined at the beginning of the NTS file. The argument - f must be used in the command line to execute all cases. For further information, see run notus guide.

Number of MPI processors required

The number of MPI processors in Validation Mode is determined at the beginning of every NTS, regardless of the dimension of the case. The syntax is similar to the one used to define parameters :

# @MPI_PROCS integer

where integer is the number of MPI processors required.

Add Fortan routines

If the test case needs special Fortran routines, the execution mode switches from the default mode (that passes through user routines) to the test_case mode that passes through specific routines associated to the test case that is run. This is done thanks a special keyword that is added to the NTS file.

Add a special keyword to the ui

First, add your test case in the Notus test case enumeration that needs specific Fortran routines, in the src/notus/test_cases/enum.f90 file:

 enumerator :: test_case_your_test_case_name

In the User Interface part of the code, src/notus/ui/keywords.f90 file, add an enumerator beginning with kw_tc_:

 ! Test case keywords
 enumerator :: kw_tc_your_test_case_name

Then, in the same file, in subroutine ui_keyword_list_initialize, add the keyword into the keyword list:

ui_keywords(kw_tc_your_test_case_name                        )%name = "tc_your_test_case_name"

Then, in src/notus/ui/tree/system/block_reader.f90 file, in the select case(tok_test_casekeyword_id) section, add your test case:

      test_case = test_case_your_test_case

Now, compile again the code !

Add the Fortran files

Specific routines must be separated into several ones which names are:

  • prepation.f90: for special initialization, boundary condition, etc.
  • new_iteration.f90: called in the time loop before the resolution of the equation (for time dependent boundary conditions, source terms, etc.)
  • reference_solution.f90: to compute the reference solution
  • post_process.f90: for specific post-processing

These routine are put in the src/notus/test_cases/your_test_case_category/your_test_case_directory directory.

The switch during the execution from a set of routines associated to one test case to another is done in the src/notus/test_cases directory in which you have to modify compute_reference_solution.f90, tc_prepare_next_iteration.f90, tc_post_process.f90 and tc_prepare.f90 routines.

Now, compile again the code, and your test case should be added !