DUBeat  1.0.1
High-order discontinuous Galerkin methods and applications to cardiac electrophysiology
DUBeat Documentation

DUBeat is a C++ library that exploits lifex and deal.II to provide discontinuous Galerkin methods on simplices and their applications to cardiac electrophysiology. This work originates from a project for the course of Advanced Programming for Scientific Computing at Politecnico di Milano and it is developed by Federica Botta and Matteo Calafà.

The library provides the following two methods:

  1. DG with nodal Lagrangian basis
  2. DG with orthogonal Dubiner basis.

They both work in either 2 or 3 dimensions depending on the lifex configuration (i.e., specifying lifex::dim).
The Dubiner method can be used with every order while the Lagrangian basis degree can be at most 2 due to the current deal.II restrictions.

Citation

If you use DUBeat for your research, please cite our arXiv preprint:

@misc{botta2024highorder,
title={High-order Discontinuous {Galerkin} Methods for the Monodomain and Bidomain Models},
author={Federica Botta and Matteo Calafà and Pasquale C. Africa and Christian Vergara and Paola F. Antonietti},
year={2024},
eprint={2406.03045},
archivePrefix={arXiv},
primaryClass={math.NA},
url={https://arxiv.org/abs/2406.03045},
}

Dependencies

The library can be used only on a linux machine with CMake ≥ 3.22.1 and GNU bash ≥ 5.1.16.
Then, DUBeat 1.0.1 relies almost exclusively on the lifex 1.5.0 installation and its dependencies. Check its download and install page to verify you satisfy all the requirements and install it.
More precisely, the library has been implemented using the libraries included in the lifex mk module, 2022.0 version. This module can be downloaded from here and we refer again to the lifex download and install page for more information. In particular, DUBeat uses from this package:

In addition to the core libraries, other packages need to be installed for supplementary reasons:

  • Python ≥ 3.9.6 for the creation of convergence plot figures (see generate_convergence_plots.py).
  • Doxygen ≥ 1.9.1 for the generation of the library documentation.
  • Graphviz ≥ 2.43.0 for the automatic creation of figures included in the documentation.
  • Clang-Format ≥ 14.0.0 for the automatic indentation of the library codes
  • gmsh ≥ 4.0.4 for the generation of mesh files.
  • ParaView ≥ 5.9.1 for the analysis and view of numerical solutions.

Download and install

  1. To download the library, move to the directory where you desire to install DUBeat 1.0.1 and use the following bash command.
    git clone git@github.com:teocala/DUBeat.git --branch v1.0.1
    Notice that the previous operation requires the SSH key authentication, see the Github dedicated page for more information.
  2. DUBeat is an only header library, so what you have just downloaded is already the library installation.
  3. Modify the variable LIFEX_PATH in the Makefile.inc file specifying your local lifex directory.

Prepare and run your simulation

In the models folder we have already provided three different models:

  • Poisson's problem.
  • Heat problem.
  • Monodomain problem of cardiac electrophysiology.

In addition, you find an example of main execution script in the build folder.
To run from this template, you have to follow the five next steps:

  1. Choose your model modifying the main_dubiner_dg.cpp script.
  2. Go back to the main directory and run make to compile the script.
  3. Now that the execution file is ready, move to the build folder and type
    ./main_dubiner_dg -g
    to generate the main_dubiner_dg.prm parameter file.
  4. You can now set your parameters in this file without the need to re-compile. In particular, you can specify the mesh refinement that consists in the choice of the mesh file from the meshes folder.
  5. Finally, write
    ./main_dubiner_dg
    to run your simulation.

See your results

Results can be viewed and analysed in two ways:

  • By default, you should see on the screen the numerical errors with the exact solution. In addition, the ComputeErrorsDG class will write the errors on a .data file. Finally, you can use the extra/generate_convergence_plots.py script to create plots of the errors for different mesh refinements starting from a .data file.
  • The code generates two solution files, open solution.xdmf with ParaView to see the contour plots of the numerical and exact solutions.

Documentation, indentation and cleaning

The Make configuration permits to easily perform some operations that are suggested to keep a neat and working environment in DUBeat, especially for users that want to contribute to the library or personalize their problems. The following operations are to be executed on the linux command line from the library main folder:

  • Run
    make doc
    to generate the Doxygen documentation under the documentation folder.
  • Use instead
    make indent
    to automatically indent all the files using our customized Clang-Format setup.
  • To conclude, you can run
    make clean
    to remove the previously generated execution files. In addition, you can write
    make distclean
    to perform a complete cleaning, i.e. removing all generated files such as parameter files, documentation and solution files.

Personalize your problem

It is very simple to add a new model/problem in DUBeat, just follow the next tips!

  • A new model should follow the same structure as the ones in the models folder. This implies that the class should derive from ModelDG if it is a stationary problem, while it should derive from ModelDG_t if it is a time-dependent problem.
  • The only method that must necessarily be implemented is assemble_system that specifies how the linear system of the problem is defined. However, also all the other methods can be overridden based on the problem choices.
  • The addition of a new type of discontinuous Galerkin local matrix needs to be supplemented in the assemble_DG.hpp methods.
  • As for now, simplices meshes can not be built runtime in deal.II. Therefore, some example meshes are provided in the folder meshes and used in the default version. In case you need to use your own .msh files, you need to use the version of the create_mesh method in ModelDG that accepts a user-defined mesh path.
  • If you need to add new scripts or folders, remember to add them to the make and indent configurations.