version 0.5.0
How 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.

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]


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.

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:

   case(kw_tc_your_test_case)
test_case = test_case_your_test_case


Now, compile again the code !