Project source organization

The following guidelines describes how project files are organized.

The usage of each sub-directory is listed below:

Name | Description |
---|---|

`doc` | Doxygen generated documentation |

`logo` | The Notus logo |

`src` | Fortran source files |

`std` | Standard database |

`test_cases` | Test case description files |

`tools` | Useful development and validation scripts |

The sources of Notus are devided into 4 parts:

- The Notus library sources that are compiled first to create its library
`libnotus.a`

. Corresponding files are in`src/lib`

. - The user interface, the main program and some specific routines associated to some test cases are compiled on a second step and linked with
`libnotus.a`

. They can be found in`src/notus`

. - The doc sources in
`src/doc`

. - Some unit testing in
`src/unit_testing`

directory.

The library architecture is based on 8 different modules that the developer will find in the corresponding source directories. The following section describes each module as well as its interaction with others.

The **User** module is the place where the *advanced user* can develop its own code when the *NTS* files aren't sufficient for his/her needs.

The **Core** module furnishes the base code on which is built the library. It contains the following sub-modules:

*system*: the Notus dynamic execution procedures (memory allocation, performance monitors, etc.)*data_structures*: the*face_field*(for face-based vector fields), the*boundary_conditions*related structures and the*containers*(linked lists, maps, etc.) derivable types*parallelism*: parallel threads construction and data exchange procedures between processors*misc*: various useful functions, notably mathematical functions (constants, algebra, polynomial roots, etc.)

The **Modeling** module is the place where the equations of the physical models (see Brief description of models and equations) are solved. To do so, it uses principally the **Discretization** and the **Linear System Solver** modules. This is where the *model developer* will integrate his own code. We use *high-level numerical methods* term for this module.

The following sub-modules are furnished in the library and can serve as examples:

*navier*: the incompressible Navier-Stokes equations*energy*: the energy (temperature) equation*species_transport*: the transport of one or multiple species by the flow*turbulence*: the turbulence models*phase_advection*: the advection of immiscible phases*compute_physical_fields*: is used for*density*and*viscosity*computation*generic_transport_equation*: is used by both the*energy*and the*species_transport*equations, as they share similarities in their solving

The **Discretization** module furnishes all the computation procedures and functions that are (mainly) used by the **Modeling** module to effectively solve the equations. For example, the developer will find there all the differential cell or face operator implicit discretization routines, the explicit differential operators (gradient, divergence, etc.) and finite difference schemes. We use the *low-level numerical methods* term for this module. The *model developer* will use this part of the library, whereas the *numerical developer* will develop his own methods inside it.

It is divided in sub-modules:

*implicit_discretization*: the main implicit discretization methods for face or cell based terms*explicit_discretization*: the explicit discretization methods for face or cell based terms*differential_operators*: operators (gradient, divergence, laplacian, etc.) defined on cells and faces*node_level_schemes*: finite difference schemes, interpolation and extrapolation methods (for example, used by the above sub-modules)*time*: procedures for time related discretization questions*immersed_boundary*: particular discretization operations for the immersed boundaries*multiphase*: multiphase methods (VOF, MOF, level set)

The **Post process** module furnishes all the tools that are used and can be used to extract numerical and physical diagnostics from the computed data. For example, one can use this module to compute the \(L_2\) norm of the error to a reference solution, or the strain rate based on the velocity field.

It is divided in sub-modules:

*error_computation*: error computation on nodes and different norms ( \(L_2\), \(L_1\), \(L_\infty\))*integration*: integration useful functions (eg. compute the integral of a cell field)*physical_diagnostic*: a collection of physical based diagnostic quantities (vorticity, Nusselt number, etc.) that can be computed from the various fields*validation*: a place used to process validation related data (eg. particular output for grid convergence)

The **Geometry** module contains procedures related to the discrete and physical geometry of the problem. It is separated in two distinct sub-modules:

*grid*: this is where the discrete grid is defined and constructed from the input physical boundaries. The developer will find there the important data structures (coordinates, spatial steps, etc.) and useful associated functions (eg. get the \((x,y,z)\) coordinates of a cell's center)*computational_geometry*: this module proposed a set of geometrical shape definition (eg. circle, square, etc.) that are used at initialization and useful functions to manipulated 3D meshes (with triangles, polygons, tetrahedrons)

The **Linear system solver** module handles the different solvers encapsulated into Notus and the external solver interfaces. It furnishes the procedure to use the three following solvers:

*hypre_interface*: the HYPRE library Notus interface*mumps_interface*: the MUMPS library Notus interface*notus_solver*: the Notus internal solver

The **Input/Output** module proposed the various procedures to read the input data and write output information and results. It contains also the `log`

and `debug`

procedures to display/save various information during the calculus.

It is divided in sub-modules:

*log*: mainly the useful`notus_log`

function for printing specific output during the calculations*debug*: functions to write debug output*adios_interface*: the interface between Notus data fields and Adios data procedures*lexer_parser*: procedures for the reading and parsing of the input file*checkpoint_restart*: procedures to export data (checkpoint) that can be used to start again a computation in case of a computer crash (restart)

For a complete view of this directory at a lower level, see Modules and topics on left menu. It contains numerical method and source descriptions.

The main program `notus.f90`

is found in `src/notus`

directory. It is described next section (Code overview).

Routine `finalize_initialization.f90`

finalizes the initialization process of a simulation. It is called just before the time loop.

Fortran programs relative to some test cases that cannot be completely described by the User Interface are present in the `test_cases`

subdirectory. For instance, it may be some time dependant velocity field, spatial dependant boundary conditions, etc. There is one subdirectory associated to the each test case that need such routines. In this case, a keyword is present in the corresponding *NTS* file. For instance:

test_case tc_vof_sheared;

These routines may be called to initialize, prepare next time loop iteration, or for post-processing purposes.

The user interface is in the `ui`

sub-directory.

It contains routines that read Notus command line.

This directory contains doc sources (Markdown .md files) which are not directly linked to a source file but describe some basic concepts of the code (build, source organization, description of the domain, etc.).

This directory contains the Unit Testing ('UT') subdirectories that are aimed to test and validate each individual element/part of the code, separately.

This directory contains the test cases *NTS* files that are used to verify and validate Notus. Verification analyzes the solution of the code when an exact solution of the problem exists (or is eventually manufactured). It is essentially a mathematical process. Validation checks the capacity of the code to represent a physical problem (flow, heat transfer, etc.) that do not have an exact solution.

Thus, the Notus test cases are divided into 2 groups, verification and validation test cases. Each test case is described by an *NTS* file that is read by the parser of Notus. It follows a specific succession of information (grammar) about the domain and the mesh, the modeling and the numerical methods, and finally about post-processing.

The description of each test case and their expected results can be found in these two pages verification and validation.

Enventually, some specific routines associated to initialization, time dependant source terms or boundary conditions, etc., are defined in `src/notus/test_cases directory`, that follows the same tree then then the `test_cases`

directory.

This directory contains the standard Notus database that is reduced at present time to the fluid physical properties database `physical_properties.nts`

.