-
Notifications
You must be signed in to change notification settings - Fork 60
Explanation of the folder structure of Lethe
The folder structure of Lethe is relatively complex. Once you have cloned and compiled Lethe, it is normal that you might be confused as to the meaning of the various folder in the cloned directory (which we will refer to as the lethe folder) or in the build folder. This section of the wiki aims at demystifying these elements.
The Lethe folder is the folder which has been cloned from github. At the top of the source folder, the following structure is present:
/applications/applications_tests/contrib/includes/logo/prototypes/sources/tests
In what follows, we explain the content of each folder and the logic behind this complex structure. We explain the folder not in alphabetical order but in a more "logical" order...
Lethe is designed to contain a number of solvers for single or multiphysics problems. These various solvers take the form of multiple executables which are named applications. They are stored in the /applications folder.
Each application is housed in its own separate folder. For example, the folder /applications/gls_navier_stokes_2d contains the source which instantiates the 2D version of the GLS Navier-Stokes solver, whereas the /applications/gls_navier_stokes_3d folder stores the source which instantiates the 3D version of the GLS Navier-Stokes solver.
In Lethe, solvers are minimal applications with only a main file. They contain little source code (generally < 100 lines). Their only goal is to instantiate the solver classes with the appropriate dimension of the problem. Since all of Lethe solvers are templated for the dimension of the problem (int dim), the same source code is re-used in both 2D and 3D. Applications are made to be comprehensive. They are fully controlled from text files (.prm and eventually .json).
The /applications_tests folder contains the functional tests for the applications. These tests are grouped in folders that correspond to the name of the application. For example, the folder /applications_tests/gls_navier_stokes_2d folder contains multiple tests for the GLS Navier-Stokes 2D solver. Each test is two or more files and is identified with a single prefix. It must necessarily contain a ".prm" file, which is the parameter file that is used to launch the test. It must also contain a ".output" file, which is the expected output of the solver. Additional file may be present if the test it to be ran with multiple processors combination or if the test requires a mesh file.
For example, the cylinder_gls test is made of three files: cylinder_gls.output, which is the expected output, cylinder_gls.prm, which is the parameter file used to control the simulation (with the appropriate boundary conditions, etc.) and the cylinder_structured.msh file which is a GMSH mesh that is required for the simulation to run.
You may notice that some outputs are preceded by a mpirun=2 prefix. For example, the mms-2d_gls.mpirun=2.output file. This additional prefix indicates that the test will be run with two processors. If this prefix is not present, the test will always be run with a single processor. To ensure enhanced compatibility with the CI, tests should not use over 3 processors.
The include folder houses the prototypes for all the functions and the classes within Lethe whereas the source folder houses the source code. All the files within the include folder are .h files whereas all files within the source folder are .cc, as per the deal.II standards.
It can readily be noticed that the include and source folder are subdivided into additional sub-directories. At the time of this writing the sub-directories are :
coresolvers
The content of Lethe is subdivided into modules that are generally independent of one another. This encapsulates furthermore the content of the software. The core module contains the core functionality of Lethe, whereas the solvers module contains the applications that are related to the finite element solution of multiphysics problem. The dependency between the module can only be uni-directional. For example, the solvers module requires the core module, but the core module could not require the solvers module.
The /tests folder houses the unit tests for all of the modules of Lethe. The unit tests are different from the application's tests. Their scope is only to verify that a single class or functions behave in the expected manner. They are used to test individual components of the Lethe and not complete applications. Hence, these tests are grouped by modules.
The /prototypes folder houses temporary applications in Lethe. These applications are prototypes that are very close to the steps of deal.II. They are used to tests novel development before they are fully integrated within Lethe. The prototypes are not expected to be stable.
The prototypes folder contains a template folder which contains a virgin prototype. Each prototype should be implemented within their own folder. When implementing a new prototype, the following should be done:
- Copy the template folder to a new folder within the prototypes folder that bears the name of what you want to develop
- Within the new folder, modify the CMakeLists.txt file to ensure that the name of the application has the name you want it to have. This is achieved my modifying the SET(TARGET "protype_template") line to SET(TARGET "my_project_name")
- Modify the name of the .cc files so that it corresponds to the name of your prototype. All .cc and .h files will be detected automatically by the CMakeLists.txt GLOB instructions
- Add the new folder to the list of prototypes to be taken into account by modifying the prototypes/CMakeLists.txt and adding a ADD_SUBDIRECTORY(my_prototype)
The /contrib folder houses various scripts that help for the maintenance of Lethe. It notably contains the contrib/utilities/indent-all script which can be used to automatically indent the entire Lethe source code to ensure that it adheres to the clang-format rules contained in the `/contrib folder
The /logo folder is the simplest one, it houses the logo of Lethe in various formats :)!