4.1. SW2D developer manual

Author

Inria LEMON

4.1.1. Development procedure

4.1.1.1. SW2D project structure

app

This folder contains source code that calls libraries (see /src).

build

folder generated automatically.

  • bin contains the executable files

  • lib contains the libraries (Core, Transport, Visualization). The symbolic link does not contain the version number, but the file properties do. The purpose is that the correct library version be referenced automatically as the SW2D version changes.

cmake

The files with a .in suffix are used to generate other makefiles. FindSphinx.cmake is here because Sphinx is not yet included in CMake.

doxygen

folder for generating the doxygen documentation, see [subsec:DocDoxygen]

mr_tests

merge request folder for version systematic testing, see [sec:Merge-request-tests]

pkg

stands for “packaging”. Subfolders of notice:

  • env provides the Conda development environment

  • recipes provides the environment for Conda packages building (e.g. in view of release distribution. Does not contain e.g. swCoreTests, that is a development tool)

utils

contains various python utility scripts

  • compare_fortran_cpp

  • matlab

  • ptyhon

src

contains source code used to build libraries (called by the code in /app)

4.1.1.2. The main steps of the development process

  • Developing

  • Documenting your code - see also [sec:Documentation]

  • Running unit tests

    • Linux/MacOS: go to build, type make test

    • Windows: under Git bash, go to build, type cmake --build . --target RUN_TESTS

    • All systems: go to build/bin/Debug [Release] and type swCoreTests[.exe]

  • Running mr_tests

    • Linux/MacOS: go to build, type make mr_tests

    • Window : go to build, type cmmake -- build . -- target mr_tests

    • All systems (in a Conda prompt for Windows): go to mr_tests and type python run_mr_tests_standalone.py

4.1.1.3. Coding standards

To be completed.

4.1.1.4. Building the documentation[sec:Documentation]

4.1.1.4.1. Doxygen[subsec:DocDoxygen]

4.1.1.4.1.1. Generating the Doxygen documentation
  1. To build the offline doxygen documentation, doxygen should be installed first (available on : http://www.doxygen.nl/download.html).

  2. In the sw2D/doxygen folder, place the doxyfile text file (available from @todo : put the link).

  3. @todo : Installation of dot if necessary

  4. Run the Doxygen documentation generation using the command (in a prompt [Git bash under WIndows])

    doxygen doxyfile
    

    . The documentation can also be generated using a GUI.

  5. The documentation is generated within the sw2D/doxygen/dox_html folder in a html format. The main html file is sw2d/doxygen/dox_html/index.html.

4.1.1.4.1.2. Documenting the code

To be recognized as Doxygen commands, the commands have to be written bewteen tags:

::

/** {DOXYGEN COMMAND} **

Example :

/** @file swMesh.h **/
4.1.1.4.1.2.1. Fields to be filled in all files (.h and .cpp)

Compulsory fields to be filled in .h files

@brief

short description of the function

@return

give the return of a function

@param

indicate the various in/out parameters

Optional fields

@author

@bug

identify the origin of a bug. Try to explain how the bug appears (specify the test case and the operating system).

@date

@file

@todo

point of attention for the next sprint

@why

identify questions to be asked to the SED about the implementation or algorithmic choices

The fields @bug, @todo and @why are listed in specific pages.

4.1.1.4.2. Using GIT

4.1.1.5. Unit tests (swCoreTest)

4.1.1.5.1. How to run them

  • Linux/MacOS : make test

  • Windows:

    • in the Git Bash : ctest

    • in the MiniConda prompt :

4.1.1.5.2. How to develop them

4.1.1.6. Merge request tests (mr_tests)[sec:Merge-request-tests]

4.1.1.6.1. Purpose

The mr_tests folder is part of the SW2D repository. It contains the complete setup for a series of tests that should be passed by the code upon completion of a branch. The branch cannot be validated and merged until all the tests are passed successfully.

4.1.1.6.1.1. Necessary conditions for merge request validation:
  • anyone who has been assigned a merge request should check that the code passes these tests successfully,

  • anyone developing a new test case must supply the complete elements that allow tests case reproduction and result assessment, namely:

    • a minimal documentation of the test case (see Sections 3 and 4),

    • the complete set of input files that allow the test case to be run (mesh, boundary codes, .geo file, boundary condition time series, input file for sw2dSolver, etc.

    • the reference results in a form that is easily readable and usable by a plotting program, a script, etc.

    • one or several scripts allowing for the comparison of code output with the reference results (e.g. a gnuplot script).

4.1.1.6.2. How to run them - Systematic testing script

  • Linux/MacOS : make mr_test

  • Windows:

    • in the Git Bash : ctest

    • in the MiniConda prompt :

In the sw2d/mr_tests folder, one can find a script named run_mr_tests-OS where OS stands for linux, macos or windows. This script is made to enter every subfolder of the current one (see below) and run the simulation. The subfolder graph_scripts will contain outputs obtained after some gnuplot extraction of the produced data. These results will have to be compared with the reference (expected) results.
When running, the script provides the list of subfolders to be considered (one run for each subfolder), then runs the simulation and finally displays the results
In the future it would be nice to include the tests in a makefile (allowing also to clean the outputs). For example ’make mr_tests’ or ’make mr_tests_clean’…

4.1.1.6.3. MR_Test folders

The mr_tests folder is located under the root of the branch. It contains several folders (one for each test case) and the general script that launches the systematic test procedure.

4.1.1.6.3.1. Folder naming
4.1.1.6.3.1.1. Typesetting.

Folder names contain only lowercase characters. When made of several words, those are separated by a single underscore character.

4.1.1.6.3.1.2. Name structure.

The test case folder name follows the structure ${Model}_${Problem type}_${Problem name}

  • ${Model}: an easily understandable shorthand for the target process of the test case. Examples:

    • dip for the Dual Integral Porosity model,

    • ddp for the Depth-Dependent Porosity model,

    • prec or precip for precipitation models,

    • inf or infiltr for infiltration model testing,

    • bio for biological processes.

  • ${Problem type}: the type of the mathematical problem involved. Examples:

    • bvp for Boundary Value Problems,

    • ivp for Initial Value Problems,

    • stdy for steady state test cases.

  • ${Problem name}: a shorthand for the specific test case. Examples:

    • dambreak_poros for a dambreak test case involving the porosity model,

    • dambreak_swes for a dambreak test case involving the classical shallow water equations,

    • prescribed_h for a problem with a prescribed water depth as a boundary condition,

    • static for testing the preservation of static solutions.

4.1.1.6.3.2. Folder structure

Subfolder

Contains

doc

The complete set of files needed to generate the full documentation for the test case:

  • .tex as a main document + the output generated from it (.pdf format)

  • .png (preferred format) files for included graphics, compilable under LaTeX

The .tex file is used as a subfile by the main file of the developer documentation.

graph_scripts

The script(s) for gnuplot or other standard plotting packages. They use the reference solution and the solution provided by the code (in the output folder)

input

All the files necessary to test case generation:

  • mesh file (.2dm or other format),

  • boundary code file (.bc or other format) for .geo generation,

  • .geo file,

  • boundary time series file (.lim file)

  • hydrodynamic configuration file for sw2dSolver

  • additional time series files or maps (precipation time series, roughness coefficient maps, biology, etc.)

reference

The reference (analytical or numerical) solution in a form that is easily readable (ASCII) and usable by standard plotting software for visual comparison purposes.

The standard variables in the output files are the water depth, the free surface elevation, the bottom level, and the two components of the unit discharge.

For tests related to biological processes, other variables can be used, such as temperature, concentrations, etc.

4.1.1.6.4. Test case documentation

The .tex document must include a number of compulsory items, in the following format:

Level

Title

Content

section

Test case name

the same as the folder name

subsection

General information

overall description of the test case

paragraph*

Objectives

describe briefly what is the purpose of the test?

paragraph*

IC and BC

a description of the initial and boundary conditions, either in natural language or using formulae.

subsection

Expected results

Description of the results, in one or several of the following forms:

  • qualitative description (“the water should remain at rest”)

  • analytical solution if available

  • under which conditions should the difference between the reference solution and the code solution be deemed acceptable? visual comparison using the plotting scripts? error norm calculation? any other criteria?


Other items may be included if deemed appropriate.

4.1.1.7. Make commands

Several make commands can be used from the build repository:

  • <make> compiles the code

  • runs the unitary tests

  • <make mr_tests> runs the merge request tests in the <mr_tests> repository

  • <make clean_tests> removes all dummy files from <mr_tests> repository

4.1.2. Source structure

The present chapter gives an overview of the source code folder structure. The purpose is to help the reader find more easily the source files to be modified when new developments/debugging are needed.

4.1.2.1. Folder structure

Overall structure of the ``app`` and ``src`` folders

Overall structure of the app and src folders

The src/swCore folder contains most of the classes used by the numerical solver swSolver:

Overall structure of the ``swCore`` folder

Overall structure of the swCore folder

Closing up into src/swCore/Hydro :

Overall structure of the ``Hydro`` folder

Overall structure of the Hydro folder

4.1.2.2. File naming

File names have the following structure : sw${Type} plus optional extensions: ${B}, ${C}, etc.
where Type can be:
  • Model if this is a model (understood as a set of governing equations solved using a specific numerical technique). Files with this type are found in /src/swCore/Model and in the various subfolders of /src/swCore/Hydro and /src/swCoreTransportReaction. sw${Type}${B}${C}${D} with the following structure:

    • ${B} : the part of the governing equation

      • B = "Hyp" for the hyperbolic part of the governing equations. The corresponding file name is swModelHyp${C}${D}.

        • ${C}: the hyperbolic model

          • Dip for the Dual Integral Porosity (DIP) model

          • Ddp for the Depth Dependent Porosity (DIP) model

        • ${D}: the solution technique

          • Godunov for the Godunov scheme

          • Muscl for the MUSCL scheme

      • B = "SourceTerm" for the source term part of the governing equations. The corresponding file name is swModelSourceTerm.

  • 2DM if this is related to the SMS 2dm files. File names have to following structure: sw${Type}${B} where B is Converter or Importer

  • Core

  • Field to manage the fields of variable in the mesh

  • Mesh to manage the mesh and the geometrical properties

  • Param to store the parameters common to all models

  • Pipeline to execute the computation

  • ReaderPFG:what is it?

  • Serafin if this is related to the Telemac serafin files

  • SettingsPFG:should disappear

  • SourcePFG:should disappear

  • TimeLoopPFG:should disappear

  • TimeSeriesPFG:what is it?

  • WriterPFG:what is it?

  • ZonePFG:what is it?

4.1.3. Dictionary of useful classes and variables

The purpose of the present chapter is to help the reader find the most useful/frequently used classes and variables in the implementation/development of numerical solution methods.

4.1.3.1. Class naming.

The class names are mirrored by those of the source files, see Section 2.2.

PFG:regarder si Doxygen peut aider. Deux solutions envisageables: (i) utiliser un système d’index, (ii) créer un @tag dans les fonctions pour les lister dans un tableau (style @todo)

  • Regarder comment intégrer les fichiers du type /src/add_new_model.dox dans un item du Doxygen, au même titre que par exemple “Questions to SED”

  • Mais dans ce cas il faut absolument pouvoir avoir un moteur de recherche performant dans le Doxygen

incomplete table

Class

Folder

Contains

swMesh

swParam

the .h of the corresponding class in the .cpp that uses these variables

Name

type

class

Meaning

m_mesh:m ath:->getNbCells()

size_t

swMesh

Number of cells in the mesh

m_mesh

\(->\)getNbBc()

size_t

swMesh

Number of boundary condition types

m_mesh:m ath:->getNbNodes()

size_t

swMesh

Number of nodes in the mesh

4.1.4. Implementing a new hyperbolic model

4.1.4.1. [sec:swModelHypDipGodunov]Guided tour: example of swModelHypDipGodunov

The Godunov solution of the DIP model (class swModelHypDipGodunov) is taken as an example. For the principles of class naming, see Subsection 4.2.

4.1.4.1.1. inheritance

swModelHypDipGodunov solves the governing equations of the Dual Integral Porosity (DIP) model using the Godunov technique. Consequently it must inherit from the methods and attributes of the swModelHypDip class, and it incorporates a number of additional methods that are specific to the Godunov solution techniques, and that will not be used by other techniques (such as MUSCL, or Discontinuous Galerkin, etc.). Hence the following include instructions in swModelHypDipGodunov.h:

#include <swCore/Hydro/Hyperbolic/swModelHypDip.h>

class SWCORE_EXPORT swModelHypDipGodunov : public swModelHypDip

The swModelHypDip class is a particular case of a hyperbolic model, thus it inherits from swModelHyp. Note that swModelHyp.h is found in the upper level folder /src/swcore/Model/.

4.1.4.1.2. Inherited functions

The functions (methods) declared as virtual in swModelHyp can be used from the children classes (swModelHypDip and swModelHypDipGodunov).

virtual double compute(double dt) = 0;
virtual void init(swMesh *mesh) = 0;
virtual double timeStep(void) = 0;
virtual void writeLog(void) = 0;

The symbol = 0 imposes that the each function as to be implemented in the cpp of the children classes. The functions init, timeStep and writeLog are implemented in swModelHypDip

void init(swMesh *mesh) override;
double timeStep(void) final;
void writeLog(void) final;

final indicates that timeStep and writeLog cannot be implemented in the classes inheriting of swModelHypDip and final indicates that init replace the implementation made in the upper class (swModelHyp). One can notice that the function compute is implemented in swModelHypDipGodunov and not in swModelHypDip.

4.1.4.1.3. class specific functions

Functions specific to DIP model and Godunov scheme are also implemented:

  • In swModelHypDip:

    • swModelHypDip::lambdaPlus

    • swModelHypDip::lambdaMinus

    • swModelHypDip::specificForce

  • In swModelHypDipGodunov:

    • swModelHypDipGodunov::computeFlux uses swModelHypDip::specificForce and the Godunov characterization of the Riemann problem.

4.1.4.1.4. initialization

The initialization of the swModelHypDipGodunov class is handled by the void swModelHypDipGodunov::init(swMesh *mesh) function. Due to inheritance, the function overrides the init function of the parent class (void swModelHypDip::init(swMesh *mesh)). To avoid any code duplication, the function swModelHypDipGodunov::init calls the function of its direct class (swModelHypDip::init) that calls also (swModelHyp::init). Thus:

  • swModelHyp::init read the initial conditions (setInitCond();), the boundary conditions (initBoundaryConditions();) and the Boussinesq distribution (setBoussinesq();)

  • swModelHypDip::init read the distribution of the parameters corresponding to a DIP model (\(\phi_{\Omega}\), \(\phi_{\Gamma}\) and the momentum dissipation coefficients \(\mu\)).

  • swModelHypDipGodunov::init compute, in the Godunov way, the coefficients to update the hydrodynamic variables

4.1.4.1.5. json parameter file

A swModelHypDipGodunov.json file is associated to the swModelHypDipGodunov class. This file contains the parameter values that are not used by another parent or other non-child class.

4.1.4.1.6. call to the swModelHypDipGodunov class in the workflow

The workflow is managed by the swPipeline::execute() function. The classes of the model (hyperbolic, source terms, …) are used in the function swPipeline::execute() and the following instructions in this function should not be modified:

  • d->model_hyp = swModelHyp::create(d->param); create a swModelHyp object (it is recalled that all classes inheriting from swModelHyp are of type swModelHyp). The swModelHyp::create() function aims to select a hyperbolic model depending upon the user-defined hyperbolic model parameter (model_hyperb) and the numerical scheme parameter (num_schem).

  • d->model_hyp->init(d->m_mesh); initializes the hyperbolic model (read the initial conditions, the parameters distribution, …). The init function that is used depends upon the type of hyperbolic model created (swModelHypDip, swModelHypDipGodunov, …).

  • d->model_hyp->writeLog(); writes log prior to the time loop

  • double dt_compute = d->setTimeStep(); is a function that computes the maximal allowed timestep (using swModelHyp::timeStep() function)

  • d->dt = d->model_hyp->compute(dt_compute); uses the swModelHyp::compute() function to update the hydrodynamic variables. The way the variables are updated depends upon the type of hyperbolic model created (swModelHypDip, swModelHypDipGodunov, …).

4.1.4.2. General rules

  • Hyperbolic models are implemented in swCore/Hydro/Hyperbolic, see Chapter 2 for an overview.

  • Class creation / prototyping :

    • use inheritance as much as possible. Thus define methods on the highest possible level and reuse them in lower level classes. The purpose is to avoid source code duplication as much as possible. For instance, swModelHypDipGodunov and swModelHypDipMuscl share the methods for variables initialization, balance, Riemann solver and time step, but they use different formulae for the left and right states of the Riemann problem. Consequently, it is advised to define init, balance, hllc and timeStep in swModelHypDip and the specific implementations of Riemann problem left/right states in swModelHypDipGodunov and swModelHypDipMuscl.

    • best practice#1: force method coding using the virtual [...] = 0 instruction in the .h files. Example: virtual void balance(void) = 0; The functions may be implemented in the class under consideration or any parent class.

    • best practice#2: the final instruction prevents a method from being modified in inheriting classes.

    • best practice#3: the override instruction replaces a previously defined method with the one in the .h under consideration.

  • In the initialization of each class, check the bounds of the parameters / fields that are specific to the model. Example #1: check that the porosity is between 0 and 1. Example#2: check that the Strickler coefficient is positive.

4.1.4.3. Create the class

  1. Create new files: FILE.cpp and FILE.h in swCore/Hydro/Hyperbolic.

  2. In the header file (FILE.h),

    1. create inheriting relation (directly or indirectly, depending on its level) from swModelHyp. The class from which the model inherits is mentioned in the .h. Example : class SWCORE\_EXPORT swModelHypDipGodunov : public swModelHypDip, the class swModelHypDipGodunov inherits from swModelHypDip that inherits from swModelHyp.

    2. create the functions declared as virtual in the upper classes. Each function have to return the same type of variable and to use the same arguments. When relevant, it is advised to use the final keyword to prevent implementation in inheriting classes.

    3. add compulsory local functions:

      • the class constuctor and destructor

      • void importParameters(dtkCoreParameters): this function aims to translate the default parameters (stored in a dtkCoreParameters variable and read from a json file) into the class attributes. This function have to be public.

      • dtkCoreParameters exportParameters(void): this function aims to translate the class attributes to a dtkCoreParameters variable to update the GUI. This function have to be public.

    4. If the class need a particular initialization (not handle by any of the parent classes), implement the void FILE::init(swMesh *mesh) function.

  3. create FILE.json in swCore/Hydro/Hyperbolic and add it to the list in the following file: /src/swCore/swCore.qrc. This file is used to declare the class parameters as dtkParameter (i.e. a default value, a type and a range - or a list - of admissible values). This particular type is necessary to implement user-controls in the GUI. This file have to be created even if empty.

  4. In the source file (FILE.cpp),

    1. implement the class constructor:

      //-- set the default parameters
      QString filename = ":Common/swParam.json"; // specify the json file path relatively to the swCore folder. Do not forget the ':'
      
      //---- read from default parameters from json
      dtkCoreParameters m_default_parameters;
      m_default_parameters = dtk::core::readParameters(filename);
      //==== read from default parameters from json
      
      //---- assign parameter to swParam attributes
      importParameters(m_default_parameters);
      //==== assign parameter to swParam attributes
      //== read the default parameters in json
      
    2. implement importParameters(dtkCoreParameters) to convert a set of parameters contained in a dtkCoreParameters into the class attributes. Example:

      void swModelHypDip::importParameters(dtkCoreParameters parameters)
      {
          num_schem = dtk::d_inliststring(parameters["num_scheme"]->variant()).value();
          solv = dtk::d_inliststring(parameters["solv"]->variant()).value();
      }
      
    3. implement dtkCoreParameters exportParameters(void) to convert the class attributes into a set of parameters contained in a dtkCoreParameters. Example:

      dtkCoreParameters swModelHypDip::exportParameters(void)
      {
          //--
          dtkCoreParameters export_parameters_for_GUI;
          export_parameters_for_GUI["scheme"] = new dtk::d_string(num_schem);
          export_parameters_for_GUI["solv"] = new dtk::d_string(solv) ;
          //==
          return export_parameters_for_GUI;
      }
      
    4. If necessary, implement the void FILE::init(swMesh *mesh) function. To avoid any code duplication, this function have to call the init function of the parent class (see the example in section [sec:swModelHypDipGodunov]).

  5. In swModelHyp.cpp: adapt the contents ofswModelHyp *swModelHyp::create(const QString& hyp, const QString& num_schem) (see algorithm [alg:swModelHyp::create]) to allow this function to select the new model depending on the user-defined variables: (model_hyperb) and (num_schem).

    else if (hyp.compare("dip") == 0)
    {
        if (num_schem.compare("godunov") == 0)
        {
            return new swModelHypDipGodunov();
        }
        else if (num_schem.compare("muscl") == 0)
        {
            dtkFatal() << Q_FUNC_INFO << __LINE__ << "not implemented";
            return nullptr; // avoid compilation warning
        }
        else
        {
            dtkError() << "'num_schem' parameter value not recognized" << num_schem;
            dtkFatal() << Q_FUNC_INFO << __LINE__;
            return nullptr; // avoid compilation warning
        }
    }
    

4.1.5. The following items are in the old doc

4.1.5.1. Physical models[sec:Physical-models]

4.1.5.1.1. 2D Shallow water equations with porosity

4.1.5.1.2. Wind

4.1.5.1.3. Building exchange

4.1.5.2. Explicit Finite volume scheme[sec:Explicit-Finite-volume]

In this section, the numerical scheme used to solve XXXX is presented.

4.1.5.2.1. Finite volume scheme discretisation

4.1.5.2.2. Internal Riemann fluxes computation

4.1.5.2.2.1. [subsec:HLLC-Riemann-solver]HLLC Riemann solver
4.1.5.2.2.2. [subsec:PorAS-Riemann-solver]PorAS Riemann solver

4.1.5.2.3. Boundary conditions

Several types of boundary conditions are implemented in :

f

for free outlet

c

for prescribed Froude number

h

for prescirbed water depth

z

for prescribed free surface elevation

q

for prescribed unit-discharge

4.1.5.2.3.1. Prescribed unit discharge \(q\)

4.1.5.2.4. Timestep determination

4.1.5.2.5. Source term discretizations

4.1.5.3. Adding a new model[sec:Adding-a-new]

4.1.5.3.1. Example # 1: implementing a new hyperbolic model - Single Porosity (SP)

The SP model is taken as an example. The steps are listed hereafter.

model.

Source

method

Status

Task

swCor e/CMakeLists.txt

List new .h and .cpp where the methods are prototyped and implemented

swParam.cpp

setModelHyperb

Done

Include new model in the list

getInputPorosity SpCellFileName() (also in .h)

Done

Define a method that gets the name of the inoput file containing the porosity for the cells. The pre-defined name is “SP_cell_ porosity_map.txt - mention it in the .h file

s wParam::path(swP aram::SpPhiCell)

Include this method in the .h and .cpp

swModelHypSp.cpp and .h

sw ModelHypSp(void)

Done

Constructor

 sw ModelHypSp(void)

Done

Destructor

::create()

Done

Create the model

:: importParameters

Done

:: exportParameters

Done

init

Done

Initialize friction map

timeStep()

Done

Time step calculation

::check Parameters(void)

Done

Check parameter range

::compute

Done

Calculation of source term influence

swMod elHypSpGodunov.h and .cpp

Header

Done

Include the right classes and .h files

Implementation

Done

swMesh

SetCellsField

Done

include the porosity parameters in fields list - here phiw is reused

swModelHyp.cpp

::create

Done

Add “sp” to the list of allowed models

top of cpp

Done

Add swMod elHypSpGodunov.h to the Include list in header

swMod elHypSpGodunov.h and .cpp

Done

Must be created, use e.g. swMo delHypDipGodunov as a template

s wModelSourceTerm

::create

Done

Implement a call to the source term model creation method. Example: “return new sw ModelSourceFrict ionChezySwes();”

top of .cpp

Done

include the .h of all source term models for the SWES model

s wModelSourceFric tion${model}Swes (.h and .cpp), with ${model} = Chezy, Manning, Strickler

All methods

Duplicate the .h and .cpp of e.g. swModelHypDip and make appropriate changes

s wModelHypSp.json

Done

Must be created, use e.g; sw ModelHypDip.json as a template

Done

num_scheme and solvn must be filled in to include the allowed options

swParam.json

Done

Add to the list of possible models

src/s wCore/swCore.qrc

Done

Add the name of the .json file of the new model if needed+

4.1.5.3.2. Example # 2: implementing a new hyperbolic model - Shallow Water Equations (SWEs)

The steps are listed hereafter.

Equations (SWEs) model.

Source

method

Status

Task

swCor e/CMakeLists.txt

Done

List new .h and .cpp where the methods are prototyped and implemented

Co mmon/swParam.cpp

setModelHyperb

Done

Include new model in the list

ge tInputPorositySw esCellFileName() (also in .h)

Pointless (no porosity)

getLogSwesP hiCellFileName()

Poitless (no porosity)

sw ModelHypSwes.cpp and .h

swMo delHypSwes(void)

Done

Constructor

 swMo delHypSwes(void)

Done

Destructor

::create()

Done

Create the model

:: importParameters

Done

:: exportParameters

Done

init

Done

deactivate Boussinesq and porosity map initialization because these fields are not needed

timeStep()

Done

Time step calculation

::check Parameters(void)

DOne

Check parameter range

::compute

Done

Calculation of source term influence

swModel HypSwesGodunov.h and .cpp

Header

Done

Include the right classes and .h files

Implementation

Done

Common / swMesh

SetCellsField

Done

include the porosity parameters in fields list - here phiw is reused - Not applicable

Model / swModelHyp.cpp

top of cpp

Done

Add swModel HypSwesGodunov.h to the Include list in header

::create

Done

Add “sp” to the list of allowed models

s wModelSourceTerm

::create

Done

Implement a call to the source term model creation method. Example: “return new sw ModelSourceFrict ionChezySwes();”

top of .cpp

Done

include the .h of all source term models for the SWES model

s wModelSourceFric tion${model}Swes (.h and .cpp), with ${model} = Chezy, Manning, Strickler

All methods

Duplicate the .h and .cpp of e.g. swModelHypDip and make appropriate changes

swM odelHypSwes.json

Done

Must be created, use e.g; s wModelHypSp.json as a template

Done

num_scheme and solvn must be filled in to include the allowed options

Common / swParam.json

Done

Add to the list of possible models

src/swCore / swCore.qrc

Done

Add the name of the .json file of the new model if needed

mr_tests

Create one or several mr_tests for the developments

4.1.5.4. Implementing a new computational method

4.1.5.4.1. Example #1 : the MUSCL - EVR method for the shallow water equations

4.1.5.4.1.1. What is needed
  1. Read the table of neighbouring cells of a given cells in .geo - Specific method defined in swParam to extract the cell_to_neigh table.

  2. Implement methods (get them from the Fortran code) to:

    1. set up the weighting coefficients for calculation of the slope of a variable within a cell (InitMUSCL.for)

    2. apply the interpolation to compute the slope at a given time step (MUSCLRec.for)

    3. infer the left and right states of the Equivalent Riemann Problem (ERP.for)

    The first two are model-independent. But the computation of the L and R states of the ERP is model-dependent because it uses the eigenvectors, and those are model-dependent.

Useful Fortran routines: uploaded to the current Overleaf project - to be deleted after completion.

Caption

Source

Method(s)

Status

Comment

Model / swModelHyp.cpp and .h

::intM usclCoefficients

At initialization step : compute the MUSCL weighting coefficients

Use the weighting coefficients to reconstruct the \(x-\) and \(y-\) slope of a given variable

swParam (.h & .cpp)

setNumScheme

Method setting the numerical scheme (“godunov” or “muscl_evr”)