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!

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:

Or check out an IMEX-type method for the monodomain equations:

Advanced demos

There’s also an example solving a Sobolev-type equation

Finally, if you feel you must bypass the TimeStepper abstraction, we have some examples how to interact with Irksome at a slightly lower level:

API documentation

There is also an alphabetical index, and a search engine.