Welcome to pySDC!¶
The pySDC
project is a Python implementation of the
spectral deferred correction (SDC) approach and its flavors, esp. the
multilevel extension MLSDC and PFASST. It is intended for rapid
prototyping and educational purposes. New ideas like e.g. sweepers or
predictors can be tested and first toy problems can be easily
implemented.
Features¶
Variants of SDC: explicit, implicit, IMEX, multi-implicit, Verlet, multi-level, diagonal, multi-step
Variants of PFASST: virtual parallel or MPI-based parallel, classical of multigrid perspective
8 tutorials: from setting up a first collocation problem to SDC, PFASST and advanced topics
Projects: many documented projects with defined and tested outcomes
Many different examples, collocation types, data types already implemented
Works with FEniCS, mpi4py-fft and PETSc (through petsc4py)
Continuous integration via GitHub Actions and Gitlab CI (through the GitHub2Gitlab Action)
Fully compatible with Python 3.9 - 3.12, runs at least on Ubuntu
Getting started¶
The code is hosted on GitHub, see
https://github.com/Parallel-in-Time/pySDC, and PyPI, see
https://pypi.python.org/pypi/pySDC. While using pip install pySDC
will give you a core version of pySDC
to work with,
working with the developer version is most often the better choice. We
thus recommend to checkout the code from GitHub and install the
dependencies e.g. by using a conda
environment. For this, pySDC
ships with environment files
which can be found in the folder etc/
. Use these as e.g.
conda env create -f etc/environment-base.yml
If you want to install the developer version using pip
directly from the GitHub repository, use this:
# optionally use venv
python3 -m venv name_of_pySDC_env
. ./name_of_pySDC_env/bin/activate
# drop @5.5.0 if you want to install the develop version
pip install git+https://github.com/Parallel-in-Time/pySDC@5.5.0
To check your installation, run
pytest pySDC/tests -m NAME
where NAME
corresponds to the environment you chose (base
in the
example above). You may need to update your PYTHONPATH
by running
export PYTHONPATH=$PYTHONPATH:/path/to/pySDC/root/folder
in particular if you want to run any of the playgrounds, projects or
tutorials. All import
statements there assume that the
pySDC
's base directory is part of PYTHONPATH
.
For many examples, LaTeX
is used for the plots, i.e. a
decent installation of this is needed in order to run those examples.
When using fenics
or petsc4py
, a C++
compiler is required (although installation may go through at first).
For more details on pySDC
, check out http://www.parallel-in-time.org/pySDC.
How to cite¶
If you use pySDC or parts of it for your work, great! Let us know if we can help you with this. Also, we would greatly appreciate a citation of this paper:
Robert Speck, Algorithm 997: pySDC - Prototyping Spectral Deferred Corrections, ACM Transactions on Mathematical Software (TOMS), Volume 45 Issue 3, August 2019, https://doi.org/10.1145/3310410
The current software release can be cited using Zenodo:
Contributing¶
pySDC
code was originally developed by Robert Speck (@pancetta),
and is now maintained and developed by a small community of scientists interested in SDC methods.
Checkout the Changelog to see pySDC’s evolution since 2016. It has a
software management plan (SWP), too, see here.
Any contribution is dearly welcome! If you want to contribute, please take the time to read our Contribution Guidelines (and don’t forget to take a peek at our nice Code of Conduct 😉).
Acknowledgements¶
This project has received funding from the European High-Performance Computing Joint Undertaking (JU) under grant agreement No 955701 (TIME-X) and grant agreement No 101118139. The JU receives support from the European Union’s Horizon 2020 research and innovation programme and Belgium, France, Germany, and Switzerland. This project also received funding from the German Federal Ministry of Education and Research (BMBF) grants 16HPC047 and 16ME0679K. Supported by the European Union - NextGenerationEU. The project also received help from the Helmholtz Platform for Research Software Engineering - Preparatory Study (HiRSE_PS).
Tests¶
Most of the code is supported by tests, mainly realized by using the tutorial as the test routines with clearly defined results. Also, projects are accompanied by tests.
User Guide¶
Tutorial¶
To flatten the steep learning curve of SDC and the likes, this tutorial contains eight steps to introduce, demonstrate and briefly discuss the main features of pySDC. We start with a simple problem setup, add the collocation problem, solve this via SDC, MLSDC and finally PFASST and discuss further extensions. Along the way we highlight special features of pySDC and explain how different features or implementations can be used (or disabled).
All tutorials are supported by tests and are run automatically after pushing to master. The results are shown within the description and can be found here (yes, yes, Jupyter notebooks would be awesome, just need to find someone to do it):
Playgrounds¶
This folder gathers various small to medium experiments done with pySDC. They are for example grouped by application (e.g. Boris
) or by problem type (e.g. ODEs
).
Also, the deprecated
folder lists a few old applications which have not been ported to the current version of pySDC.
Experiments which become more complex or which eventually evolve into a publication of any form should go to the projects
folder and should receive proper documentation and description.
The playground codes are supposed to be cleaned up, but there is no detailed documentation available.
Projects¶
In the projects
folder we gather focussed experiments with pySDC which go beyond simple toy problems or feature tests.
In particular, projects are structured and documented codes which form the basis for publications or presentations.
All projects are expected to contain a README file describing the intention and content of the work.
Parts of the Python scripts are supported by tests and checked for PEP8 conformity.
- Attempts to parallelize SDC
- Fast-Wave-Slow-Wave SDC
- RDC: Rational Deferred Corrections
- Asymptotic convergence of PFASST
- Matrix-based versions of PFASST
- Second-order Problems
- What is the fastest SDC variant?
- Allen-Cahn problems from Bayreuth
- Performance analysis of pySDC
- Parallel-in-time simulation for multi-modal energy systems
- Resilience in SDC
- Solving differential algebraic equations with SDC
- Compression in pySDC
- Spectral Deferred Correction Methods for Second-Order Problems
- Exponential SDC for the Monodomain Equation in Cardiac Electrophysiology
API documentation¶
The Python files contained in core
, implementations
and helpers
are fully documented and their API is generated automatically with sphinx-apidoc after each update:
Indices and tables :