Presentation

Tolosa (TOols Library for unstructured Ocean models and Surge Applications) is a free and open source computational software framework whose main purpose is to simulate some models for ocean and river dynamics, on unstructured meshes, within a CPU MPI parallel environment and with original numerical schemes.

All source files are written in Fortran 2008 following a KISS (Keep It Stupid and Simple) principle with some Object-oriented features.

The development has been designed in such a way that the code is as simple and light as possible using object-oriented programming (possible in Fortran since the 95 standard and greatly improved since then with the 2003, 2008 and 2018 standards), while maintaining the highest level of performance, within the limits of our capacities. This means that it is necessary to find the right balance between oriented object sophistication and computing speed. The typical example being the manipulation of AoS (Arrays of Structures) and SoA (Structures of Arrays). Good performance is also achieved taking care to the data locality in memory cache when performing loops on cells, edges and nodes with corresponding inter connectivities.

Tolosa encapsulates several models for ocean and river dynamics. Each numerically resolved model and associated numerical scheme revolve around the Tolosa library Tolosa-lib. This library is a set of structures and tools to help each model's implementation along.

This website is divided in three tabs and focuses on the presentation of :

• the library Tolosa-lib and its features.
• the Shallow-Water model implemented in Tolosa-sw.
• the Shallow-Water post-treatment tool PyTolosa.

License

The Tolosa software is distributed under the CeCILL 2.1 license compatible with the GNU GPL license.

List of the external libraries that are eventually used by the Tolosa software:

• Scotch: a software package for graph and mesh/hypergraph partitioning, graph clustering, and sparse matrix ordering available as free software under the CeCILL-C license.

System requirements

The Tolosa software needs to be compiled if you want to use it. There are two reasons:

• The compilation uses some compilation flags that aim is to optimize the execution computation speed according to the characteristics of the machine.

• Some inputs are defined by some user-functions which are part of the Fortran code, so we need to recompile the code every time we change one of them (these user-functions are not always needed).

In this document, we will assume that you have a Linux operating system even if compilation remains possible on Windows and MacOS operating systems.

Compilation

One of these two compilers must be installed,

• the GNU Fortran compiler (free software under the GPL free license).

• the INTEL Fortran compiler (commercial software under a proprietary license).

Generated result files

Result output files can be written in the following formats,

• text format (.txt extension) or csv format (.csv extension): a basic format file that can generally be plotted with your favorite graphical XY-plot software.

• VTK format (.vtk extension): the Kitware free format file that can be read by visualization free softwares like Paraview or Visit.

• Tecplot format (.plt extension): a proprietary format file used by the visualization commercial software Tecplot.

• Binary format (.binextension): in-house binary format that can be post-processed with PyTolosa.

and gives the choice of the visualization software(s) to be used.

Directories organization

At the root of the Tolosa reperitories, one can find:

• a Makefile in order to compile the software, clean some generated files and eventually directly control the execution.

• the /src directory, containing all source files with:

  • at the root some Fortran modules and eventually a main program (which can be placed in another location using certain features of the Makefile).

  • the /src/includerepertory containing source files included in Fortran modules at the root (in order to separate and cut the source code length).

  • the /src/submodulerepertory containing submodule source files attached to Fortran modules at the root.

• the /bin directory: the main directory to use the Tolosa software after compilation. First, the simulation control files have to be put in,

  • the input.txt file (must be provided) which allows the user to define all variables defining the targeted simulation: the mesh, the numerical and physical parameters, the input/output options, etc ...

  • the m_user_data.f90 file (must be provided) which contains user-subroutines which can be used to define initial conditions, boundary conditions, etc ...

  After calling the Makefile, the linked executable exe is put in this same directory, as all simulation result files after execution in the /bin/res directory.

• the /tests directory and its subdirectories containing the input.txt and m_user_data.f90 files, and eventually others, to perform some prepared simulations, generally test cases.

• after compilation, the /build directory: a working directory generated by the Makefile containing all files generated to compile, including the eventual libraries.

• eventually, the /Tolosa-lib repertory in order to use it to derive the numerical implementation of some models, therefore outside the library itself in separate repertories.