Welcome to Irksome¶

Irksome is a Python library that adds a temporal discretization layer on top of finite element discretizations provided by Firedrake. We provide a symbolic representation of time derivatives in UFL, allowing users to write weak forms of semidiscrete PDE. Irksome maps this and a Butcher tableau encoding a Runge-Kutta method into a fully discrete variational problem for the stage values. Irksome then leverages existing advanced solver technology in Firedrake and PETSc to allow for efficient computation of the Runge-Kutta stages. Convenience classes package the underlying lower-level manipulations and present users with a friendly high-level interface time stepping.

So, instead of manually coding UFL for backward Euler for the heat equation:

F = inner((unew - uold) / dt, v) * dx + inner(grad(unew), grad(v)) * dx

and rewriting this if you want a different time-stepping method, Irksome lets you write UFL for a semidiscrete form:

F = inner(Dt(u), v) * dx + inner(grad(u), grad(v)) * dx

and maps this and a Butcher tableau for some Runge-Kutta method to UFL for a fully-discrete method. Hence, switching between RK methods is plug-and-play.

Irksome provides convenience classes to package the transformation of forms and boundary conditions and provide a method to advance by a time step. The underlying variational problem for the (possibly implicit!) Runge-Kutta stages composes fully with advanced Firedrake/PETSc solver technology, so you can use block preconditioners, multigrid with patch smooters, and more – and in parallel, too!

Acknowledgements¶

The Irksome team is deeply grateful to David Ham for setting up our initial documentation and Jack Betteridge for initializing the CI. Ivan Yashchuk set up the GitHub Actions. Lawrence Mitchell provided early assistance on some UFL manipulation and documentation

Getting started¶

Irksome requires Firedrake, if you have an existing Firedrake installation, you can add Irksome to it with firedrake-update --install irksome. If you would like a fresh installation including Irksome, use firedrake-install --install irksome. Alternately you can clone the repository and pip install -e . into the Firedrake virtual environment.

Tutorials¶

After your installation works, please check out our demos.

The best place to start are with some simple heat and wave equations:

Since those demos invariably rely on the non-scalable LU factorization, we have several demos showing how to work with Firedrake solver options to deploy more efficient methods:

We now have support for DIRKs: