irksome package

Submodules

irksome.ButcherTableaux module

class irksome.ButcherTableaux.Alexander

Bases: ButcherTableau

Third-order, diagonally implicit, 3-stage, L-stable scheme from Diagonally Implicit Runge-Kutta Methods for Stiff O.D.E.’s, R. Alexander, SINUM 14(6): 1006-1021, 1977.

class irksome.ButcherTableaux.BackwardEuler

Bases: RadauIIA

The rock-solid first-order implicit method.

class irksome.ButcherTableaux.ButcherTableau(A, b, btilde, c, order, embedded_order, gamma0)

Bases: object

Top-level class representing a Butcher tableau encoding

a Runge-Kutta method. It has members

Parameters:

• A – a 2d array containing the Butcher matrix

• b – a 1d array giving weights assigned to each stage when computing the solution at time n+1.

• btilde – If present, a 1d array giving weights for an embedded lower-order method (used in estimating temporal truncation error.)

• c – a 1d array containing weights at which time-dependent terms are evaluated.

• order – the (integer) formal order of accuracy of the method

• embedded_order – If present, the (integer) formal order of accuracy of the embedded method

• gamma0 – If present, the weight on the explicit term in the embedded lower-order method

property is_diagonally_implicit

property is_explicit

property is_fully_implicit

property is_implicit

property is_stiffly_accurate

Determines whether the method is stiffly accurate.

property num_stages

Return the number of stages the method has.

class irksome.ButcherTableaux.CollocationButcherTableau(L, order)

Bases: ButcherTableau

When an RK method is based on collocation with point sets present in FIAT, we have a general formula for producing the Butcher tableau.

Parameters:

• L – a one-dimensional class FIAT.FiniteElement of Lagrange type – the degrees of freedom must all be point evaluation.

• order – the order of the resulting RK method.

class irksome.ButcherTableaux.GaussLegendre(num_stages)

Bases: CollocationButcherTableau

Collocation method based on the Gauss-Legendre points. The order of accuracy is 2 * num_stages. GL methods are A-stable, B-stable, and symplectic.

Parameters:

num_stages – The number of stages (1 or greater)

class irksome.ButcherTableaux.LobattoIIIA(num_stages)

Bases: CollocationButcherTableau

Collocation method based on the Gauss-Lobatto points. The order of accuracy is 2 * num_stages - 2. LobattoIIIA methods are A-stable but not B- or L-stable.

Parameters:

num_stages – The number of stages (2 or greater)

class irksome.ButcherTableaux.LobattoIIIC(num_stages)

Bases: ButcherTableau

Discontinuous collocation method based on the Lobatto points. The order of accuracy is 2 * num_stages - 2. LobattoIIIC methods are A-, L-, algebraically, and B- stable.

Parameters:

num_stages – The number of stages (2 or greater)

class irksome.ButcherTableaux.PareschiRusso(x)

Bases: ButcherTableau

Second order, diagonally implicit, 2-stage. A-stable if x >= 1/4 and L-stable iff x = 1 plus/minus 1/sqrt(2).

class irksome.ButcherTableaux.QinZhang

Bases: PareschiRusso

Symplectic Pareschi-Russo DIRK

class irksome.ButcherTableaux.RadauIIA(num_stages, variant='embed_Radau5')

Bases: CollocationButcherTableau

Collocation method based on the Gauss-Radau points. The order of accuracy is 2 * num_stages - 1. RadauIIA methods are algebraically (hence B-) stable.

Parameters:

• num_stages – The number of stages (2 or greater)

• variant – Indicate whether to use the Radau5 style of embedded scheme (with variant = “embed_Radau5”) or the simple collocation type (with variant = “embed_colloc”)

irksome.ars_dirk_imex_tableaux module

class irksome.ars_dirk_imex_tableaux.ARS_DIRK_IMEX(ns_imp, ns_exp, order)

Bases: DIRK_IMEX

Class to generate IMEX tableaux based on Ascher, Ruuth, and Spiteri (ARS). It has members

Parameters:

• ns_imp – number of implicit stages

• ns_exp – number of explicit stages

• order – the (integer) former order of accuracy of the method

irksome.base_time_stepper module

class irksome.base_time_stepper.BaseTimeStepper(F, t, dt, u0, bcs=None, appctx=None, nullspace=None)

Bases: object

Base class for various time steppers. This is mainly to give code reuse stashing objects that are common to all the time steppers. It’s a developer-level class.

abstractmethod advance()

abstractmethod solver_stats()

class irksome.base_time_stepper.StageCoupledTimeStepper(F, t, dt, u0, num_stages, bcs=None, solver_parameters=None, appctx=None, nullspace=None, transpose_nullspace=None, near_nullspace=None, splitting=None, bc_type=None, butcher_tableau=None, bounds=None, **kwargs)

Bases: BaseTimeStepper

This developer-level class provides common features used by various methods requiring stage-coupled variational problems to compute the stages (e.g. fully implicit RK, Galerkin-in-time)

Parameters:

• F – A ufl.Form instance describing the semi-discrete problem F(t, u; v) == 0, where u is the unknown firedrake.Function and `v is the :class:firedrake.TestFunction`.

• t – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time.

• dt – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time step. The user may adjust this value between time steps.

• u0 – A firedrake.Function containing the current state of the problem to be solved.

• num_stages – The number of stages to solve for. It could be the number of RK stages or relate to the polynomial degree (Galerkin)

• bcs – An iterable of firedrake.DirichletBC or firedrake.EquationBC containing the strongly-enforced boundary conditions. Irksome will manipulate these to obtain boundary conditions for each stage of the RK method. Support for firedrake.EquationBC is limited to the stage derivative formulation with DAE style BCs.

• solver_parameters – An optional dict of solver parameters that will be used in solving the algebraic problem associated with each time step.

• appctx – An optional dict containing application context. This gets included with particular things that Irksome will pass into the nonlinear solver so that, say, user-defined preconditioners have access to it.

• nullspace – A list of tuples of the form (index, VSB) where index is an index into the function space associated with u and VSB is a :class: firedrake.VectorSpaceBasis instance to be passed to a firedrake.MixedVectorSpaceBasis over the larger space associated with the Runge-Kutta method

• splitting – An optional kwarg (not used by all superclasses)

• bc_type – An optional kwarg (not used by all superclasses)

• butcher_tableau – A ButcherTableau instance giving the Runge-Kutta method to be used for time marching.

• bounds – An optional kwarg used in certain bounds-constrained methods.

advance()

Advances the system from time t to time t + dt. Note: overwrites the value u0.

abstractmethod get_form_and_bcs(stages, tableau=None, F=None)

get_stage_bounds(bounds=None)

get_stages()

solver_stats()

irksome.bcs module

irksome.bcs.BCStageData(bc, gcur, u0, stages, i)

class irksome.bcs.BoundsConstrainedDirichletBC(V, g, sub_domain, bounds, solver_parameters=None)

Bases: DirichletBC

A DirichletBC with bounds-constrained data.

property function_arg

The value of this boundary condition.

reconstruct(V=None, g=None, sub_domain=None)

irksome.bcs.EmbeddedBCData(bc, butcher_tableau, t, dt, u0, stages)

irksome.bcs.bc2space(bc, V)

irksome.bcs.extract_bcs(bcs)

Return an iterable of boundary conditions on the residual form

irksome.bcs.get_sub(u, indices)

irksome.bcs.stage2spaces4bc(bc, V, Vbig, i)

used to figure out how to apply Dirichlet BC to each stage

irksome.deriv module

irksome.deriv.Dt(f, order=1)

Short-hand function to produce a TimeDerivative of a given order.

class irksome.deriv.TimeDerivative(f)

Bases: Derivative

UFL node representing a time derivative of some quantity/field. Note: Currently form compilers do not understand how to process these nodes. Instead, Irksome pre-processes forms containing TimeDerivative nodes.

Initalise.

property ufl_free_indices

property ufl_index_dimensions

property ufl_shape

class irksome.deriv.TimeDerivativeRuleDispatcher(t=None, timedep_coeffs=None, **kwargs)

Bases: DAGTraverser

Mapping rules to splat out time derivatives so that replacement should work on more complex problems.

Initialise.

process(o)

process(o: TimeDerivative)

process(o: BaseForm)

process(o: Expr)

Process node by type.

Args:

o: Expr to start DAG traversal from. **kwargs: keyword arguments for the process singledispatchmethod.

Returns:

Processed Expr.

time_derivative(o)

class irksome.deriv.TimeDerivativeRuleset(t=None, timedep_coeffs=None)

Bases: GenericDerivativeRuleset

Apply AD rules to time derivative expressions.

Initialise.

constant(o)

process(o)

process(o: ConstantValue)

process(o: SpatialCoordinate)

process(o: Coefficient)

process(o: TimeDerivative, f)

process(o: Variable, *operands)

process(o: ReferenceValue, *operands)

process(o: ReferenceGrad, *operands)

process(o: Indexed, *operands)

process(o: Grad, *operands)

process(o: Div, *operands)

process(o: Derivative, *operands)

process(o: Curl, *operands)

process(o: Conj, *operands)

Process o.

Args:

o: Expr to be processed.

Returns:

Processed object.

terminal(o)

terminal_modifier(o, *operands)

time_derivative(o, f)

irksome.deriv.apply_time_derivatives(expression, t=None, timedep_coeffs=None)

irksome.deriv.expand_time_derivatives(expression, t=None, timedep_coeffs=None)

irksome.dirk_imex_tableaux module

class irksome.dirk_imex_tableaux.DIRK_IMEX(A: ndarray, b: ndarray, c: ndarray, A_hat: ndarray, b_hat: ndarray, c_hat: ndarray, order: int = None)

Bases: ButcherTableau

Top-level class representing a pair of Butcher tableau encoding an implicit-explicit additive Runge-Kutta method. Since the explicit Butcher matrix is strictly lower triangular, only the lower-left (ns - 1)x(ns - 1) block is given. However, the full b_hat and c_hat are given. It has members

Parameters:

• A – a 2d array containing the implicit Butcher matrix

• b – a 1d array giving weights assigned to each implicit stage when computing the solution at time n+1.

• c – a 1d array containing weights at which time-dependent implicit terms are evaluated.

• A_hat – a 2d array containing the explicit Butcher matrix (lower-left block only)

• b_hat – a 1d array giving weights assigned to each explicit stage when computing the solution at time n+1.

• c_hat – a 1d array containing weights at which time-dependent explicit terms are evaluated.

• order – the (integer) formal order of accuracy of the method

irksome.dirk_stepper module

class irksome.dirk_stepper.DIRKTimeStepper(F, butcher_tableau, t, dt, u0, bcs=None, solver_parameters=None, appctx=None, nullspace=None, transpose_nullspace=None, near_nullspace=None, **kwargs)

Bases: object

Front-end class for advancing a time-dependent PDE via a diagonally-implicit Runge-Kutta method formulated in terms of stage derivatives.

advance()

get_form_and_bcs(stages, tableau=None, F=None)

solver_stats()

update_bc_constants(i, c)

irksome.dirk_stepper.getFormDIRK(F, ks, butch, t, dt, u0, bcs=None)

irksome.discontinuous_galerkin_stepper module

class irksome.discontinuous_galerkin_stepper.DiscontinuousGalerkinTimeStepper(F, order, t, dt, u0, bcs=None, basis_type=None, quadrature=None, **kwargs)

Bases: StageCoupledTimeStepper

Front-end class for advancing a time-dependent PDE via a Discontinuous Galerkin in time method

Parameters:

• F – A ufl.Form instance describing the semi-discrete problem F(t, u; v) == 0, where u is the unknown firedrake.Function and `v is the :class:firedrake.TestFunction`.

• order – an integer indicating the order of the DG space to use (with order == 0 corresponding to DG(0)-in-time)

• t – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time.

• dt – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time step. The user may adjust this value between time steps.

• u0 – A firedrake.Function containing the current state of the problem to be solved.

• bcs – An iterable of firedrake.DirichletBC containing the strongly-enforced boundary conditions. Irksome will manipulate these to obtain boundary conditions for each stage of the method.

• basis_type – A string indicating the finite element family (either ‘Lagrange’ or ‘Bernstein’) or the Lagrange variant for the test/trial spaces. Defaults to equispaced Lagrange elements.

• quadrature – A FIAT.QuadratureRule indicating the quadrature to be used in time, defaulting to GL with order+1 points

• solver_parameters – A dict of solver parameters that will be used in solving the algebraic problem associated with each time step.

• appctx – An optional dict containing application context. This gets included with particular things that Irksome will pass into the nonlinear solver so that, say, user-defined preconditioners have access to it.

• nullspace – A list of tuples of the form (index, VSB) where index is an index into the function space associated with u and VSB is a :class: firedrake.VectorSpaceBasis instance to be passed to a firedrake.MixedVectorSpaceBasis over the larger space associated with the Runge-Kutta method

get_form_and_bcs(stages, basis_type=None, order=None, quadrature=None, F=None)

irksome.discontinuous_galerkin_stepper.getElement(basis_type, order)

irksome.discontinuous_galerkin_stepper.getFormDiscGalerkin(F, L, Q, t, dt, u0, stages, bcs=None)

Given a time-dependent variational form, trial and test spaces, and a quadrature rule, produce UFL for the Discontinuous Galerkin-in-Time method.

Parameters:

• F – UFL form for the semidiscrete ODE/DAE

• L – A FIAT.FiniteElement for the test and trial functions in time

• Q – A FIAT.QuadratureRule for the time integration

• t – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time.

• dt – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time step. The user may adjust this value between time steps.

• u0 – a Function referring to the state of the PDE system at time t

• stages – a Function representing the stages to be solved for.

• bcs – optionally, a DirichletBC object (or iterable thereof) containing (possibly time-dependent) boundary conditions imposed on the system.

• nullspace – A list of tuples of the form (index, VSB) where index is an index into the function space associated with u and VSB is a :class: firedrake.VectorSpaceBasis instance to be passed to a firedrake.MixedVectorSpaceBasis over the larger space associated with the Runge-Kutta method

On output, we return a tuple consisting of four parts:

• Fnew, the Form corresponding to the DG-in-Time discretized problem

• bcnew, a list of firedrake.DirichletBC objects to be posed on the Galerkin-in-time solution,

irksome.explicit_stepper module

class irksome.explicit_stepper.ExplicitTimeStepper(F, butcher_tableau, t, dt, u0, bcs=None, solver_parameters=None, appctx=None)

Bases: DIRKTimeStepper

irksome.galerkin_stepper module

class irksome.galerkin_stepper.GalerkinTimeStepper(F, order, t, dt, u0, bcs=None, basis_type=None, quadrature=None, aux_indices=None, **kwargs)

Bases: StageCoupledTimeStepper

Front-end class for advancing a time-dependent PDE via a Galerkin in time method

Parameters:

• F – A ufl.Form instance describing the semi-discrete problem F(t, u; v) == 0, where u is the unknown firedrake.Function and `v is the :class:firedrake.TestFunction`.

• order – an integer indicating the order of the DG space to use (with order == 1 corresponding to CG(1)-in-time for the trial space)

• t – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time.

• dt – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time step. The user may adjust this value between time steps.

• u0 – A firedrake.Function containing the current state of the problem to be solved.

• bcs – An iterable of firedrake.DirichletBC containing the strongly-enforced boundary conditions. Irksome will manipulate these to obtain boundary conditions for each stage of the method.

• basis_type – A string indicating the finite element family (either ‘Lagrange’ or ‘Bernstein’) or the Lagrange variant for the test/trial spaces. Defaults to equispaced Lagrange elements.

• quadrature – A FIAT.QuadratureRule indicating the quadrature to be used in time, defaulting to GL with order points

• aux_indices – a list of field indices to be discretized in the test space rather than trial space.

• solver_parameters – A dict of solver parameters that will be used in solving the algebraic problem associated with each time step.

• appctx – An optional dict containing application context. This gets included with particular things that Irksome will pass into the nonlinear solver so that, say, user-defined preconditioners have access to it.

• nullspace – A list of tuples of the form (index, VSB) where index is an index into the function space associated with u and VSB is a :class: firedrake.VectorSpaceBasis instance to be passed to a firedrake.MixedVectorSpaceBasis over the larger space associated with the Runge-Kutta method

• aux_indices – a list of field indices to be discretized in the test space rather than trial space.

get_form_and_bcs(stages, basis_type=None, order=None, quadrature=None, aux_indices=None, F=None)

set_initial_guess()

irksome.galerkin_stepper.getElements(basis_type, order)

irksome.galerkin_stepper.getFormGalerkin(F, L_trial, L_test, Qdefault, t, dt, u0, stages, bcs=None, aux_indices=None)

Given a time-dependent variational form, trial and test spaces, and a quadrature rule, produce UFL for the Galerkin-in-Time method.

Parameters:

• F – UFL form for the semidiscrete ODE/DAE

• L_trial – A FIAT.FiniteElement for the trial functions in time

• L_test – A FIAT.FinteElement for the test functions in time

• Qdefault – A FIAT.QuadratureRule for the time integration. This rule will be used for all terms in the semidiscrete variational form that aren’t specifically tagged with another quadrature rule.

• t – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time.

• dt – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time step. The user may adjust this value between time steps.

• u0 – a Function referring to the state of the PDE system at time t

• stages – a Function representing the stages to be solved for.

• bcs – optionally, a DirichletBC object (or iterable thereof) containing (possibly time-dependent) boundary conditions imposed on the system.

• aux_indices – a list of field indices to be discretized in the test space rather than trial space.

On output, we return a tuple consisting of four parts:

• Fnew, the Form corresponding to the Galerkin-in-Time discretized problem

• bcnew, a list of firedrake.DirichletBC objects to be posed on the Galerkin-in-time solution,

irksome.galerkin_stepper.getTermGalerkin(F, L_trial, L_test, Q, t, dt, u0, stages, test, aux_indices)

irksome.imex module

class irksome.imex.DIRKIMEXMethod(F, F_explicit, butcher_tableau, t, dt, u0, bcs=None, solver_parameters=None, mass_parameters=None, appctx=None, nullspace=None)

Bases: object

Front-end class for advancing a time-dependent PDE via a diagonally-implicit Runge-Kutta IMEX method formulated in terms of stage derivatives. This implementation assumes a weak form written as F + F_explicit = 0, where both F and F_explicit are UFL Forms, with terms in F to be handled implicitly and those in F_explicit to be handled explicitly

advance()

solver_stats()

class irksome.imex.RadauIIAIMEXMethod(F, Fexp, butcher_tableau, t, dt, u0, bcs=None, it_solver_parameters=None, prop_solver_parameters=None, splitting=<function AI>, appctx=None, nullspace=None, num_its_initial=0, num_its_per_step=0)

Bases: object

Class for advancing a time-dependent PDE via a polynomial IMEX/RadauIIA method. This requires one to split the PDE into an implicit and explicit part. The class sets up two methods – advance and iterate. The former is used to move the solution forward in time, while the latter is used both to start the method (filling up the initial stage values) and can be used at each time step to increase the accuracy/stability. In the limit as the iterator is applied many times per time step, one expects convergence to the solution that would have been obtained from fully-implicit RadauIIA method.

Parameters:

• F – A ufl.Form instance describing the implicit part of the semi-discrete problem F(t, u; v) == 0, where u is the unknown firedrake.Function and `v is the :class:firedrake.TestFunction`.

• Fexp – A ufl.Form instance describing the part of the PDE that is explicitly split off.

• butcher_tableau – A ButcherTableau instance giving the Runge-Kutta method to be used for time marching. Only RadauIIA is allowed here (but it can be any number of stages).

• t – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time.

• dt – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time step. The user may adjust this value between time steps.

• u0 – A firedrake.Function containing the current state of the problem to be solved.

• bcs – An iterable of firedrake.DirichletBC containing the strongly-enforced boundary conditions. Irksome will manipulate these to obtain boundary conditions for each stage of the RK method.

• it_solver_parameters – A dict of solver parameters that will be used in solving the algebraic problem associated with the iterator.

• prop_solver_parameters – A dict of solver parameters that will be used in solving the algebraic problem associated with the propagator.

• splitting – A callable used to factor the Butcher matrix, currently, only AI is supported.

• appctx – An optional dict containing application context.

• nullspace – An optional null space object.

advance()

get_form_and_bcs(stages, tableau=None, F=None)

iterate()

Called 1 or more times to set up the initial state of the system before time-stepping. Can also be called after each call to advance

propagate()

Moves the solution forward in time, to be followed by 0 or more calls to iterate.

solver_stats()

irksome.imex.getFormExplicit(Fexp, butch, u0, UU, t, dt, splitting=None)

Processes the explicitly split-off part for a RadauIIA-IMEX method. Returns the forms for both the iterator and propagator, which really just differ by which constants are in them.

irksome.imex.getFormsDIRKIMEX(F, Fexp, ks, khats, butch, t, dt, u0, bcs=None)

irksome.imex.riia_explicit_coeffs(k)

Computes the coefficients needed for the explicit part of a RadauIIA-IMEX method.

irksome.labeling module

class irksome.labeling.TimeQuadratureLabel(*args)

Bases: Label

If the constructor gets one argument, it’s an integer for the order of the quadrature rule. If there are two arguments, assume they are the points and weights.

Parameters

label

The name of the label.

value

The value for the label to take. Can be any type (subject to the validator). Defaults to True.

validator

Function to check the validity of any value later passed to the label. Defaults to None.

default_value

label

validator

value

class irksome.labeling.TimeQuadratureRule(x, w)

Bases: object

get_points()

get_weights()

irksome.labeling.split_explicit(F)

irksome.labeling.split_quadrature(F, Qdefault=None)

irksome.manipulation module

Manipulation of expressions containing TimeDerivative terms.

These can be used to do some basic checking of the suitability of a Form for use in Irksome (via check_integrals), and splitting out terms in the Form that contain a time derivative from those that don’t (via extract_terms).

class irksome.manipulation.SplitTimeForm(time: Form, remainder: Form)

Bases: NamedTuple

A container for a form split into time terms and a remainder.

Create new instance of SplitTimeForm(time, remainder)

remainder: Form

Alias for field number 1

time: Form

Alias for field number 0

irksome.manipulation.check_integrals(integrals: List[Integral], expect_time_derivative: bool = True) → List[Integral]

Check a list of integrals for linearity in the time derivative.

Parameters:

• integrals – list of integrals.

• expect_time_derivative – Are we expecting to see a time derivative?

Raises:

ValueError – if we are expecting a time derivative and don’t see one, or time derivatives are applied nonlinearly, to more than one coefficient, or more than first order.

irksome.manipulation.extract_terms(form: Form) → SplitTimeForm

Extract terms from a Form.

This splits a form (a sum of integrals) into those integrals which do contain a TimeDerivative and those that don’t.

Parameters:

form – The form to split.

Returns:

a SplitTimeForm tuple.

Raises:

ValueError – if the form does not apply anything other than first-order time derivatives to a single coefficient.

irksome.nystrom_dirk_stepper module

class irksome.nystrom_dirk_stepper.DIRKNystromTimeStepper(F, tableau, t, dt, u0, ut0, bcs=None, solver_parameters=None, appctx=None, nullspace=None, transpose_nullspace=None, near_nullspace=None, bc_type=None, **kwargs)

Bases: object

Front-end class for advancing a second-order time-dependent PDE via a diagonally-implicit Runge-Kutta-Nystrom method formulated in terms of stage derivatives.

advance()

solver_stats()

update_bc_constants(i, c)

class irksome.nystrom_dirk_stepper.ExplicitNystromTimeStepper(F, tableau, t, dt, u0, ut0, bcs=None, solver_parameters=None, appctx=None, nullspace=None, transpose_nullspace=None, near_nullspace=None, bc_type=None, **kwargs)

Bases: DIRKNystromTimeStepper

Front-end class for advancing a second-order time-dependent PDE via an explicit Runge-Kutta-Nystrom method formulated in terms of stage derivatives.

irksome.nystrom_dirk_stepper.getFormDIRKNystrom(F, ks, tableau, t, dt, u0, ut0, bcs=None, bc_type=None)

irksome.nystrom_stepper module

class irksome.nystrom_stepper.ClassicNystrom4Tableau

Bases: NystromTableau

class irksome.nystrom_stepper.NystromTableau(A, b, c, Abar, bbar, order)

Bases: object

property is_diagonally_implicit

property is_explicit

property is_fully_implicit

property is_implicit

property num_stages

class irksome.nystrom_stepper.StageDerivativeNystromTimeStepper(F, tableau, t, dt, u0, ut0, bcs=None, bc_type='DAE', **kwargs)

Bases: StageCoupledTimeStepper

get_form_and_bcs(stages, tableau=None, F=None)

irksome.nystrom_stepper.butcher_to_nystrom(butch)

irksome.nystrom_stepper.getFormNystrom(F, tableau, t, dt, u0, ut0, stages, bcs=None, bc_type=None)

irksome.pc module

class irksome.pc.ClinesBase

Bases: NystromAuxiliaryOperatorPC

Base class for methods out of Clines/Howle/Long.

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize

• update

• apply

• applyTranspose

class irksome.pc.ClinesLD

Bases: ClinesBase

Implements Clines-type preconditioner using Atilde = LD where A=LDU.

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize

• update

• apply

• applyTranspose

getAtildes(A, Abar)

Derived classes produce a typically structured approximation to A and Abar.

class irksome.pc.IRKAuxiliaryOperatorPC

Bases: AuxiliaryOperatorPC

Base class that inherits from Firedrake’s AuxiliaryOperatorPC class and provides the preconditioning bilinear form associated with an auxiliary Form and/or approximate Butcher matrix (which are provided by subclasses).

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize

• update

• apply

• applyTranspose

form(pc, test, trial)

Implements the interface for AuxiliaryOperatorPC.

getAtilde(A)

Derived classes produce a typically structured approximation to A.

getNewForm(pc, u0, test)

Derived classes can optionally provide an auxiliary Form.

class irksome.pc.NystromAuxiliaryOperatorPC

Bases: AuxiliaryOperatorPC

Base class that inherits from Firedrake’s AuxiliaryOperatorPC class and provides the preconditioning bilinear form associated with an auxiliary Form and/or approximate Nystrom matrices (which are provided by subclasses).

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize

• update

• apply

• applyTranspose

form(pc, test, trial)

Implements the interface for AuxiliaryOperatorPC.

getAtildes(A, Abar)

Derived classes produce a typically structured approximation to A and Abar.

getNewForm(pc, u0, ut0, test)

Derived classes can optionally provide an auxiliary Form.

class irksome.pc.RanaBase

Bases: IRKAuxiliaryOperatorPC

Base class for methods out of Rana, Howle, Long, Meek, & Milestone.

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize

• update

• apply

• applyTranspose

class irksome.pc.RanaDU

Bases: RanaBase

Implements Rana-type preconditioner using Atilde = DU where A=LDU.

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize

• update

• apply

• applyTranspose

getAtilde(A)

Derived classes produce a typically structured approximation to A.

class irksome.pc.RanaLD

Bases: RanaBase

Implements Rana-type preconditioner using Atilde = LD where A=LDU.

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize

• update

• apply

• applyTranspose

getAtilde(A)

Derived classes produce a typically structured approximation to A.

irksome.pc.ldu(A)

irksome.pep_explicit_rk module

class irksome.pep_explicit_rk.PEPRK(ns, order, peporder)

Bases: ButcherTableau

irksome.sspk_tableau module

class irksome.sspk_tableau.SSPButcherTableau(order, ns)

Bases: ButcherTableau

Class used to generate tableau for strong stability preserving (SSP) schemes. It has members

Parameters:

• ns – number of stages

• order – the (integer) formal order of accuracy of the method

class irksome.sspk_tableau.SSPK_DIRK_IMEX(ssp_order, ns_imp, ns_exp, order)

Bases: DIRK_IMEX

Class to generate IMEX tableaux based on Pareschi and Russo. It has members

Parameters:

• ssp_order – order of ssp scheme

• ns_imp – number of implicit stages

• ns_exp – number of explicit stages

• order – the (integer) formal order of accuracy of the method

irksome.stage_derivative module

class irksome.stage_derivative.AdaptiveTimeStepper(F, butcher_tableau, t, dt, u0, bcs=None, appctx=None, solver_parameters=None, bc_type='DAE', splitting=<function AI>, nullspace=None, tol=0.001, dtmin=1e-15, dtmax=1.0, KI=0.06666666666666667, KP=0.13, max_reject=10, onscale_factor=1.2, safety_factor=0.9, gamma0_params=None)

Bases: StageDerivativeTimeStepper

Front-end class for advancing a time-dependent PDE via an adaptive Runge-Kutta method.

Parameters:

• F – A ufl.Form instance describing the semi-discrete problem F(t, u; v) == 0, where u is the unknown firedrake.Function and `v is the :class:firedrake.TestFunction`.

• butcher_tableau – A ButcherTableau instance giving the Runge-Kutta method to be used for time marching.

• t – A firedrake.Constant instance that always contains the time value at the beginning of a time step

• dt – A firedrake.Constant containing the size of the current time step. The user may adjust this value between time steps; however, note that the adaptive time step controls may adjust this before the step is taken.

• u0 – A firedrake.Function containing the current state of the problem to be solved.

• tol – The temporal truncation error tolerance

• dtmin – Minimal acceptable time step. An exception is raised if the step size drops below this threshhold.

• dtmax – Maximal acceptable time step, imposed as a hard cap; this can be adjusted externally once the time-stepper is instantiated, by modifying stepper.dt_max

• KI – Integration gain for step-size controller. Should be less than 1/p, where p is the expected order of the scheme. Larger values lead to faster (attempted) increases in time-step size when steps are accepted. See Gustafsson, Lundh, and Soderlind, BIT 1988.

• KP – Proportional gain for step-size controller. Controls dependence on ratio of (error estimate)/(step size) in determining new time-step size when steps are accepted. See Gustafsson, Lundh, and Soderlind, BIT 1988.

• max_reject – Maximum number of rejected timesteps in a row that does not lead to a failure

• onscale_factor – Allowable tolerance in determining initial timestep to be “on scale”

• safety_factor – Safety factor used when shrinking timestep if a proposed step is rejected

• gamma0_params – Solver parameters for mass matrix solve when using an embedded scheme with explicit first stage

• bcs – An iterable of firedrake.DirichletBC or EquationBC containing the strongly-enforced boundary conditions. Irksome will manipulate these to obtain boundary conditions for each stage of the RK method.

• solver_parameters – A dict of solver parameters that will be used in solving the algebraic problem associated with each time step.

• nullspace – A list of tuples of the form (index, VSB) where index is an index into the function space associated with u and VSB is a :class: firedrake.VectorSpaceBasis instance to be passed to a firedrake.MixedVectorSpaceBasis over the larger space associated with the Runge-Kutta method

advance()

Attempts to advances the system from time t to time t + dt. If the error threshhold is exceeded, will adaptively decrease the time step until the step is accepted. Also predicts new time step once the step is accepted. Note: overwrites the value u0.

class irksome.stage_derivative.StageDerivativeTimeStepper(F, butcher_tableau, t, dt, u0, bcs=None, solver_parameters=None, splitting=<function AI>, appctx=None, bc_type='DAE', **kwargs)

Bases: StageCoupledTimeStepper

Front-end class for advancing a time-dependent PDE via a Runge-Kutta method formulated in terms of stage derivatives.

Parameters:

• F – A ufl.Form instance describing the semi-discrete problem F(t, u; v) == 0, where u is the unknown firedrake.Function and `v is the :class:firedrake.TestFunction`.

• butcher_tableau – A ButcherTableau instance giving the Runge-Kutta method to be used for time marching.

• t – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time.

• dt – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time step. The user may adjust this value between time steps.

• u0 – A firedrake.Function containing the current state of the problem to be solved.

• bcs – An iterable of firedrake.DirichletBC or EquationBC containing the strongly-enforced boundary conditions. Irksome will manipulate these to obtain boundary conditions for each stage of the RK method.

• bc_type – How to manipulate the strongly-enforced boundary conditions to derive the stage boundary conditions. Should be a string, either “DAE”, which implements BCs as constraints in the style of a differential-algebraic equation, or “ODE”, which takes the time derivative of the boundary data and evaluates this for the stage values. Support for firedrake.EquationBC in bcs is limited to DAE style BCs.

• solver_parameters – A dict of solver parameters that will be used in solving the algebraic problem associated with each time step.

• splitting – An callable used to factor the Butcher matrix

• appctx – An optional dict containing application context. This gets included with particular things that Irksome will pass into the nonlinear solver so that, say, user-defined preconditioners have access to it.

• nullspace – A list of tuples of the form (index, VSB) where index is an index into the function space associated with u and VSB is a :class: firedrake.VectorSpaceBasis instance to be passed to a firedrake.MixedVectorSpaceBasis over the larger space associated with the Runge-Kutta method

get_form_and_bcs(stages, tableau=None, F=None)

irksome.stage_derivative.getForm(F, butch, t, dt, u0, stages, bcs=None, bc_type=None, splitting=<function AI>)

Given a time-dependent variational form and a ButcherTableau, produce UFL for the s-stage RK method.

Parameters:

• F – UFL form for the semidiscrete ODE/DAE

• butch – the ButcherTableau for the RK method being used to advance in time.

• t – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time.

• dt – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time step. The user may adjust this value between time steps.

• splitting – a callable that maps the (floating point) Butcher matrix a to a pair of matrices A1, A2 such that butch.A = A1 A2. This is used to vary between the classical RK formulation and Butcher’s reformulation that leads to a denser mass matrix with block-diagonal stiffness. Some choices of function will assume that butch.A is invertible.

• u0 – a Function referring to the state of the PDE system at time t

• stages – a Function representing the stages to be solved for.

• bcs – optionally, a DirichletBC or EquationBC object (or iterable thereof) containing (possibly time-dependent) boundary conditions imposed on the system.

• bc_type – How to manipulate the strongly-enforced boundary conditions to derive the stage boundary conditions. Should be a string, either “DAE”, which implements BCs as constraints in the style of a differential-algebraic equation, or “ODE”, which takes the time derivative of the boundary data and evaluates this for the stage values. Support for firedrake.EquationBC in bcs is limited to DAE style BCs.

On output, we return a tuple consisting of four parts:

• Fnew, the Form

• bcnew, a list of firedrake.DirichletBC or EquationBC objects to be posed on the stages,

irksome.stage_value module

class irksome.stage_value.StageValueTimeStepper(F, butcher_tableau, t, dt, u0, bcs=None, solver_parameters=None, update_solver_parameters=None, splitting=<function AI>, basis_type=None, appctx=None, bounds=None, use_collocation_update=False, **kwargs)

Bases: StageCoupledTimeStepper

get_form_and_bcs(stages, tableau=None, F=None)

get_update_solver(update_solver_parameters)

irksome.stage_value.getFormStage(F, butch, t, dt, u0, stages, bcs=None, splitting=None, vandermonde=None)

Given a time-dependent variational form and a ButcherTableau, produce UFL for the s-stage RK method.

Parameters:

• F – UFL form for the semidiscrete ODE/DAE

• butch – the ButcherTableau for the RK method being used to advance in time.

• t – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time.

• dt – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time step. The user may adjust this value between time steps.

• u0 – a Function referring to the state of the PDE system at time t

• stages – a Function representing the stages to be solved for. It lives in a firedrake.FunctionSpace corresponding to the s-way tensor product of the space on which the semidiscrete form lives.

• splitting – a callable that maps the (floating point) Butcher matrix a to a pair of matrices A1, A2 such that butch.A = A1 A2. This is used to vary between the classical RK formulation and Butcher’s reformulation that leads to a denser mass matrix with block-diagonal stiffness. Only AI and IA are currently supported.

• vandermonde – a numpy array encoding a change of basis to the Lagrange polynomials associated with the collocation nodes from some other (e.g. Bernstein or Chebyshev) basis. This allows us to solve for the coefficients in some basis rather than the values at particular stages, which can be useful for satisfying bounds constraints. If none is provided, we assume it is the identity, working in the Lagrange basis.

• bcs – optionally, a DirichletBC object (or iterable thereof) containing (possibly time-dependent) boundary conditions imposed on the system.

• nullspace – A list of tuples of the form (index, VSB) where index is an index into the function space associated with u and VSB is a :class: firedrake.VectorSpaceBasis instance to be passed to a firedrake.MixedVectorSpaceBasis over the larger space associated with the Runge-Kutta method

On output, we return a tuple consisting of several parts:

• Fnew, the Form

• bcnew, a list of firedrake.DirichletBC objects to be posed on the stages,

irksome.stage_value.to_value(u0, stages, vandermonde)

convert from Bernstein to Lagrange representation

the Bernstein coefficients are [u0; ZZ], and the Lagrange are [u0; UU] since the value at the left-endpoint is unchanged. Since u0 is not part of the unknown vector of stages, we disassemble the Vandermonde matrix (first row is [1, 0, …]).

irksome.stepper module

irksome.stepper.TimeStepper(F, butcher_tableau, t, dt, u0, **kwargs)

Helper function to dispatch between various back-end classes

for doing time stepping. Returns an instance of the appropriate class.

Parameters:

• F – A ufl.Form instance describing the semi-discrete problem F(t, u; v) == 0, where u is the unknown firedrake.Function and `v iss the :class:firedrake.TestFunction`.

• butcher_tableau – A ButcherTableau instance giving the Runge-Kutta method to be used for time marching.

• t – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time.

• dt – a Function on the Real space over the same mesh as u0. This serves as a variable referring to the current time step. The user may adjust this value between time steps.

• u0 – A firedrake.Function containing the current state of the problem to be solved.

• bcs – An iterable of firedrake.DirichletBC or :class: firedrake.EquationBC containing the strongly-enforced boundary conditions. Irksome will manipulate these to obtain boundary conditions for each stage of the RK method.

• nullspace – A list of tuples of the form (index, VSB) where index is an index into the function space associated with u and VSB is a :class: firedrake.VectorSpaceBasis instance to be passed to a firedrake.MixedVectorSpaceBasis over the larger space associated with the Runge-Kutta method

• stage_type – Whether to formulate in terms of a stage derivatives or stage values. Support for firedrake.EquationBC in bcs is limited to the stage derivative formulation.

• splitting – An callable used to factor the Butcher matrix

• bc_type – For stage derivative formulation, how to manipulate the strongly-enforced boundary conditions. Support for firedrake.EquationBC in bcs is limited to DAE style BCs.

• solver_parameters – A dict of solver parameters that will be used in solving the algebraic problem associated with each time step.

• update_solver_parameters – A dict of parameters for inverting the mass matrix at each step (only used if stage_type is “value”)

• adaptive_parameters – A dict of parameters for use with adaptive time stepping (only used if stage_type is “deriv”)

• use_collocation_update – An optional kwarg indicating whether to use the terminal value of the collocation polynomial as the solution update. This is needed to bypass the mass matrix inversion when enforcing bounds constraints with an RK method that is not stiffly accurate. Currently, only constant-in-time boundary conditions are supported.

irksome.stepper.imex_separation(F, Fexp_kwarg, label)

irksome.tools module

irksome.tools.AI(A)

irksome.tools.ConstantOrZero(x, MC=None)

irksome.tools.IA(A)

class irksome.tools.MeshConstant(msh)

Bases: object

Constant(val=0.0)

irksome.tools.dot(A, B)

irksome.tools.flatten_dats(dats)

irksome.tools.getNullspace(V, Vbig, num_stages, nullspace)

Computes the nullspace for a multi-stage method.

Parameters:

• V – The FunctionSpace on which the original time-dependent PDE is posed.

• Vbig – The multi-stage FunctionSpace for the stage problem

• num_stages – The number of stages in the RK method

• nullspace – The nullspace for the original problem.

On output, we produce a MixedVectorSpaceBasis defining the nullspace for the multistage problem.

irksome.tools.get_stage_space(V, num_stages)

irksome.tools.is_ode(f, u)

Given a form defined over a function u, checks if (each bit of) u appears under a time derivative.

irksome.tools.replace(e, mapping)

A wrapper for ufl.replace that allows numpy arrays.

irksome.tools.replace_auxiliary_variables(F, u0, aux_indices)

Discretize the fields corresponding to aux_indices in Dt(V).

irksome.tools.reshape(expr, shape)

irksome.tools.unique_mesh(mesh)

irksome.wso_dirk_tableaux module

class irksome.wso_dirk_tableaux.WSODIRK(ns, order, ws_order)

Bases: ButcherTableau

Module contents