Description

pyoomph is an 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 you 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.
• TQMesh (MIT license), a two-dimensional mesh generator, downloaded at build time and statically included in the distribution as wheels. Optional, see PYOOMPH_HAS_TQMESH and src/thirdparty/INFO_tqmesh.
• Spectra (MPL v2.0 license) and Eigen (MPL v2.0 license), the header-only eigensolver behind the "spectra" eigensolver backend and the linear algebra library it is built on. Both are downloaded at build time and statically included in the distribution as wheels. Optional, see PYOOMPH_HAS_SPECTRA and cmake/ThirdPartySpectra.cmake. Eigen is only primarily MPL2 - a few of its headers carry third-party BSD or LGPL code - so pyoomph compiles it with EIGEN_MPL2_ONLY, which makes including any of those a compile error.
• 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.10 or higher, (PSF license).
• nanobind, (BSD-style license), also used (via its bundled nanobind.stubgen) to generate python stubs from the C++ core.
• 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 3-Clause license).
• more_itertools, (MIT license).
• scipy, (BSD-3-Clause license).
• shapely, (BSD 3-Clause license), only required by pyoomph.meshes.axisymm_topology to plan axisymmetric pinch-off/coalescence. Optional, install with pip install pyoomph[topology].
• 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 to invoke the system's C compiler
• scikit-build-core (Apache 2.0 license) is used for installation and wheel generation
• cibuildwheel, (BSD 2-Clause license) is used to compile the provided wheels
• tccbox used as wrapper for the TinyC compiler, (GPL v2 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 and Maxim de Wildt joined the team. Additional contributors are Vatsal Sanjay and Jnandeep Talukdar. Pyoomph is developed at the Physics of Fluids group of the University of Twente.

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. This work was supported by an Industrial Partnership Programme, High Tech Systems and Materials (HTSM), of the Netherlands Organisation for Scientific Research (NWO); a funding for public-private partnerships (PPS) of the Netherlands Enterprise Agency (RVO) and the Ministry of Economic Affairs (EZ); Canon Production Printing Netherlands B.V.; and the University of Twente.

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 c.diddens@utwente.nl.

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.