Description

pyoomph is a object-oriented multi-physics finite element framework. It is mainly a custom high level python frontend for the main functionalities (but by far not all) of the powerful C++ library oomph-lib.

For performance reasons, pyoomph uses GiNaC and CLN to automatically generate C code for the equations you have entered in python. It automatically generates C code for symbolically derived Jacobian matrices, parameter derivatives and Hessians. These even include the complicated derivatives with respect to the moving mesh coordinates on a symbolical level. The generated code is compiled and linked back to the running python script, either with the TinyC compiler (invoked by tccbox) or, when installed, with a more performant alternative like gcc, LLVM/clang or MSBuild.

If you want to use the full flexibility of oomph-lib, you are probably better suited using oomph-lib directly. If your want to use python to solve equations on a single static mesh, you might want to check out FEniCS instead. Also, have a look at NGSolve or nutils which have similar and complementary features. If you are looking for a python framework for multi-physics problems formulated on (potentially multiple) moving meshes, including the possibility of (azimuthal) bifurcation tracking, pyoomph might be the right choice for you.

pyoomph is still in an early stage of development: While most features work nicely, it is neither feature-complete, nor free of bugs.

Installation

Please consult the file INSTALL.md in the git repository for installation instructions. Alternatively, follow the instructions in our tutorial.

Documentation and Examples

Documentation of the API and tons of examples can be found at pyoomph.readthedocs.io. A PDF version of the tutorial is also available.

Some more examples can be found in our repository pyoomph_examples.

License

pyoomph itself is distributed as combined work under the GPL v3 license. However, mind the third-party licences stated below, in particular when distributing derived work or redistributing pyoomph. The full license file can be found in COPYING.

Third-Party-Licenses

The distribution of pyoomph contains code taken from other authors/projects:

• In src/thirdparty/oomph-lib/include, you find the necessary main files of oomph-lib, (LGPL v2.1 or later license). Minor modifications, as mentioned in src/thirdparty/INFO_oomph-lib, had to be made. Furthermore, code parts of these oomph-lib files had been copied to corresponding derived classes of pyoomph.
• A copy of the header-only library nanoflann is located in src/thirdparty/nanoflann.hpp, (BSD license).
• A copy of the header-only library delaunator-cpp is located in src/thirdparty/delaunator.hpp, (MIT license).
• The file src/pyginacstruct.hpp is strongly based on the file structure.h of GiNaC (GPL v2 or later license).
• A copy of the library Project Nayuki/smallest enslosing circle (LGPL v3 license or later) is added (after adding type specifications) to pyoomph/utils/smallest_circle.py.
• When using materials or the thermodynamic activity models AIOMFAC, original UNIFAC or modified UNIFAC (Dortmund), please see below.

The third-party licenses/acknowledgement files can be found in src/thirdparty. In the provided python wheels, these requirements are statically included.

During compilation, pyoomph includes/links against or makes use of the following libraries:

• GiNaC (GPL v2 or later license), GiNaC is statically included in the distribution as wheels.
• CLN (GPL v2 or later license), CLN is statically included in the distribution as wheels.
• MPI, depending on the system e.g. OpenMPI (3-clause BSD license), MPICH (MPICH license), Microsoft MPI (MIT license), the wheels distributions are compiled without MPI support.
• python3.8 or higher, (PSF license).
• pybind11, (BSD-style license).
• pybind11-stubgen, (BSD-style license).
• pip, (MIT license).

Beyond that, pyoomph makes use of the following libraries at runtime. During installation with pip, many (but not all) of these libraries are automatically fetched as requirements.

• python core libraries, (PSF license).
• numpy, (BSD license).
• pygmsh, (GPL v3 license).
• gmsh, (GPL v2 or later license).
• meshio, (MIT license).
• mpi4py, (BSD 2-Clause "Simplified" license).
• scipy, (BSD-3-Clause license).
• matplotlib, (PSF-based license).
• mkl, (Intel Simplified Software license).
• petsc and petsc4py, (BSD 2-Clause license).
• slepc and slepc4py, (BSD 2-Clause license).
• vtk, (BSD 3-clause license).
• paraview, (BSD 3-clause license). Only used for the included Paraview filter for visualizing azimuthal perturbations.
• setuptools (MIT license) is used for installation, wheel generation and to invoke the system's C compiler
• cibuildwheel, (BSD 2-Clause license) is used to compile the provided wheels
• pybind11-stubgen, (BSD 3-Clause license) is used to generate python stubs from the C++ core
• tccbox used as wrapper for the TinyC compiler, (LPGL 2 or later license)

Be aware that some of these libraries can have further dependencies.

Authors and acknowledgements

pyoomph was founded in 2021 by Christian Diddens. Later, Duarte Rocha joined the team.

The authors gratefully acknowledge financial support by the Industrial Partnership Programme Fundamental Fluid Dynamics Challenges in Inkjet Printing of the Netherlands Organisation for Scientific Research (NWO) & High Tech Systems and Materials (HTSM), co-financed by Canon Production Printing Netherlands B.V., IamFluidics B.V., TNO Holst Centre, University of Twente, Eindhoven University of Technology and Utrecht University.

Contributing

If you want to contribute by e.g. adding new equations, meshes, problems, materials or additional features, get in contact with us or send us a pull request. If you encounter a bug, please also let us know at [email protected] or [email protected].

How to cite

At the moment, just cite the following paper for pyoomph:

Christian Diddens and Duarte Rocha, Bifurcation tracking on moving meshes and with consideration of azimuthal symmetry breaking instabilities, J. Comput. Phys. 518, 113306, (2024), doi:10.1016/j.jcp.2024.113306.

Please mention that pyoomph is based on oomph-lib and GiNaC, i.e. also cite at least:

oomph-lib: M. Heil, A. L. Hazel, oomph-lib - An Object-oriented multi-physics finite-element library, Lect. Notes Comput. Sci. Eng. 53, 19-49, (2006), doi:10.1007/3-540-34596-5_2.

GiNaC: C. Bauer, A. Frink, R. Kreckel, Introduction to the GiNaC framework for symbolic computation within the C++ programming language, J. Symb. Comput. 33(1), 1-12, (2002), doi:10.1006/jsco.2001.0494.

Citing of material properties and activity models

• pyoomph includes some parameters of the AIOMFAC activity model in pyoomph/materials/UNIFAC/aiomfac.py. These are based on the source code of AIOMFAC (GPL v3 license). Cite the relevant scientific publications when publishing results based on the AIOMFAC activity model.
• Alternatively, you can choose the original UNIFAC model or the modified UNIFAC model (Dortmund). In that case, cite the publications listed under these links if you use these models.
• For more accurate results, it is advised to obtain the updated parameters for the UNIFAC Consortium. Such updated parameter sets can be implemented by hand following the templates for the free parameters in pyoomph/materials/UNIFAC/. The usage of such updated parameters of the UNIFAC Consortium are restricted to the terms of use of the UNIFAC Consortium.
• When using the material properties from pyoomph/materials/default_materials.py, please have a look at the comments in this file to cite the correct papers.