PSYDAC is a Python 3 library for isogeometric analysis. It is an academic, open-source project created by numerical mathematicians at the Max Planck Institute for Plasma Physics (NMPP division, FEM group).

PSYDAC can solve general systems of partial differential equations in weak form, which users define using the domain-specific language provided by SymPDE. It supports finite element exterior calculus (FEEC) with tensor-product spline spaces and handles multi-patch geometries in various ways.

PSYDAC automatically generates Python code for the assembly of user-defined functionals and linear and bilinear forms from the weak formulation of the problem. This Python code is then accelerated to C/Fortran speed using Pyccel. The library also enables large parallel computations on distributed-memory supercomputers using MPI and OpenMP.

Note

The name PSYDAC stands for "Python Spline librarY for Differential equations with Automatic Code generation". It is pronounced like the famous Pokémon character, from which the developers draw inspiration for its psychic powers.

Citing

If PSYDAC has been significant in your research, and you would like to acknowledge the project in your academic publication, we would ask that you cite the following paper:

Güçlü, Y., S. Hadjout, and A. Ratnani. “PSYDAC: A High-Performance IGA Library in Python.” In 8th European Congress on Computational Methods in Applied Sciences and Engineering. CIMNE, 2022. https://doi.org/10.23967/eccomas.2022.227.

The associated BibTeX file can be found here.

Installation

PSYDAC requires a certain number of components to be installed on the machine:

• Fortran and C compilers with OpenMP support
• OpenMP library
• BLAS and LAPACK libraries
• MPI library
• HDF5 library with MPI support

The installation instructions depend on the operating system and on the packaging manager used. It is particularly important to determine the HDF5 root folder, as this will be needed to install the h5py package in parallel mode. Detailed instructions can be found in the documentation.

Once those components are installed, we recommend using venv to set up a fresh Python virtual environment at a location <ENV-PATH>:

python3 -m venv <ENV-PATH>
source <ENV-PATH>/bin/activate

PSYDAC and its Python dependencies can now be installed in the virtual environment using pip, the Python package manager:

export CC="mpicc"
export HDF5_MPI="ON"
export HDF5_DIR=<HDF5-PATH>

pip install --upgrade pip
pip install h5py --no-cache-dir --no-binary h5py
pip install "psydac[test]"

Here <HDF5-PATH> is the path to the HDF5 root folder, such that <HDF5-PATH>/lib/ contains the HDF5 dynamic libraries with MPI support.

The last command above installs the latest version of PSYDAC found on PyPI, the Python Package Index, together with some optional packages needed for running the unit tests. A developer wanting to modify the source code should skip that command, and instead clone the PSYDAC repository to perform an editable install:

git clone --recurse-submodules https://github.com/pyccel/psydac.git
cd psydac

pip install meson-python "pyccel>=2.1.0"
pip install --no-build-isolation --editable ".[test]"

Again, for more details we refer to our documentation.

Tip

PSYDAC provides the functionality to convert its MPI-parallel matrices and vectors to their PETSc equivalent, and back. This gives the user access to a wide variety of linear solvers and other algorithms. Instructions for installing PETSc and petsc4py can be found in our documentation.

Running Tests

We strongly advice users and developers to run the test suite of PSYDAC to verify the correct installation on their machine (possibly a supercomputer). All unit tests are based on pytest and are installed together with the library. For convenience, PSYDAC provides the psydac test command as shown below.

In order to run all serial and parallel tests which do not use PETSc, just type:

psydac test
psydac test --mpi

If PETSc and petsc4py were installed, additional serial and parallel tests can be run:

psydac test --petsc
psydac test --petsc --mpi

Speeding up PSYDAC's core

Many of PSYDAC's low-level Python functions can be translated to a compiled language using the Pyccel transpiler. Currently, all of those functions are collected in modules which follow the name pattern [module]_kernels.py.

For both classical and editable installations, all kernel files are translated to Fortran without user intervention. If the user adds or edits a kernel file within an editable install, they should use the command psydac compile in order to be able to see the changes at runtime. This command applies Pyccel to all the kernel files in the source directory. The default language is Fortran, and C is also available.

• Only in development mode:

  psydac compile [--language {fortran, c}]

Examples and Tutorials

Our documentation provides Jupyter notebooks that present many aspects of this library. Additional tutorials on isogeometric analysis, with many example notebooks where various PDEs are solved with PSYDAC, is under construction in the IGA-Python repository. Some other examples can be found here.

Library Documentation

• Output formats
• Mesh generation
• Modules

Contributing

There are several ways to contribute to this project!

If you find a problem, please check if this is already discussed in one of our issues and feel free to add your opinion; if not, please create a new issue. If you want to fix an issue, improve our notebooks, or add a new example, please fork our Git repository, make and commit your changes, and create a pull request (PRs). All PRs are reviewed by the project maintainers. During the PR review, GitHub workflows are triggered on various platforms.

We keep an up-to-date list of maintainers and contributors in our AUTHORS file. Thank you!