Reference: Time stepping

class pystella.step.Stepper(input, MapKernel=<class 'pystella.elementwise.ElementWiseMap'>, **kwargs)

The base class for time steppers, with no implementation of a particular time stepper.

__init__(input, MapKernel=<class 'pystella.elementwise.ElementWiseMap'>, **kwargs)

Parameters

input –

May be one of the following:

• a dict whose values represent the right-hand side of the ODEs to solve, i.e., (key, value) pairs corresponding to \((y, f)\) such that

  \[\frac{\mathrm{d} y}{\mathrm{d} t} = f,\]

  where \(f\) is an arbitrary function of kernel data. Both keys and values must be pymbolic expressions.

• a Sector. In this case, the right-hand side dictionary will be obtained from rhs_dict.

• a list of Sector’s. In this case, the input obtained from each Sector (as described above) will be combined.

The following keyword arguments are recognized:

Parameters

• MapKernel – The kernel class which each substep/stage will be an instance of—i.e., one of ElementWiseMap or its subclasses. Defaults to ElementWiseMap.

• dt – A float fixing the value of the timestep interval. Defaults to None, in which case it is not fixed at kernel creation.

The remaining arguments are passed to MapKernel.__init__() for each substep of the timestepper (i.e., see the documentation of ElementWiseMap).

__call__(stage, queue=None, **kwargs)

Calls substep/stage stage (steps[stage]) of the timestepper, i.e., pystella.ElementWiseMap.__call__() for the kernel for substep/stage stage.

Parameters

stage – The substep/stage of time timestepper to call.

Returns

The pyopencl.Event associated with the kernel invocation.

num_stages

The number of substeps/stages per timestep.

expected_order

The expected convergence order of global error, i.e. \(n\) such that the global error is \(\mathcal{O}(\Delta t^n)\).

num_unknowns

The number of unknown degrees of freedom which are evolved.

Low-storage Runge-Kutta methods

class pystella.step.LowStorageRKStepper(input, MapKernel=<class 'pystella.elementwise.ElementWiseMap'>, **kwargs)

The base implementation of low-storage, explicit Runge-Kutta time steppers, which operate by storing and operating on a single copy of each unknown array, plus an auxillary temporary array.

The substeps are expressed in a standard form, drawing coefficients from a subclass’s provided values of _A, _B, and _C.

__call__(stage, *, k_tmp, queue=None, **kwargs)

Same as Stepper.__call__(), but requires the following arguments:

Parameters

k_tmp – The array used for temporary calculations. Its outer-/left-most axis (i.e., the axis of largest stride) must have length equal to the total number of unknowns, which may be obtained from num_unknowns. Passed by keyword only.

For example:

>>> stepper = LowStorageRK54(rhs_dict)
>>> import pyopencl.array as cla
>>> temp_shape = (stepper.num_unknowns,) + rank_shape
>>> k_tmp = cla.zeros(queue, temp_shape, 'float64')
>>> for stage in range(stepper.num_stages):
...    stepper(stage, queue, k_tmp=k_tmp, ...)

class pystella.LowStorageRK54(input, MapKernel=<class 'pystella.elementwise.ElementWiseMap'>, **kwargs)

A five-stage, fourth-order, low-storage Runge-Kutta method.

See Carpenter, M.H., and Kennedy, C.A., Fourth-order-2N-storage Runge-Kutta schemes, NASA Langley Tech Report TM 109112, 1994

class pystella.LowStorageRK3Williamson(input, MapKernel=<class 'pystella.elementwise.ElementWiseMap'>, **kwargs)

A three-stage, third-order, low-storage Runge-Kutta method.

See Williamson, J. H., Low-storage Runge-Kutta schemes, J. Comput. Phys., 35, 48-56, 1980

class pystella.LowStorageRK3Inhomogeneous(input, MapKernel=<class 'pystella.elementwise.ElementWiseMap'>, **kwargs)

A three-stage, third-order, low-storage Runge-Kutta method.

class pystella.LowStorageRK3SSP(input, MapKernel=<class 'pystella.elementwise.ElementWiseMap'>, **kwargs)

A three-stage, third-order, strong-stability preserving, low-storage Runge-Kutta method.

Classical Runge-Kutta methods

“Classical” Runge-Kutta methods are also implemented, though are not recommended over the low-storage methods above.

class pystella.step.RungeKuttaStepper(input, **kwargs)

The base implementation of classical, explicit Runge-Kutta time steppers, which operate by storing and operating on multiple copies of each unknown array. Subclasses must provide an implementation of step_statements() which returns a key-value pair implementing a specific substep of the particular timestepper.

Warning

To minimize the required storage per unknown (i.e., number of temporaries), the implementation of most subclasses overwrite arrays that are being read as input to compute right-hand sides. This means that any non-local (stencil-type) operations must be precomputed and cached globally (unless otherwise noted).

Raises

ValueError – if the keys of rhs_dict are not Field’s (or pymbolic.primitives.Subscript’s thereof). This is required for make_steps() to be able to prepend unknown arrays’ subscripts with the index corresponding to the temporary storage axis.

class pystella.RungeKutta4(input, **kwargs)

The classical, four-stage, fourth-order Runge-Kutta method. Requires unknown arrays to have temporary storage axes of length three.

class pystella.RungeKutta3SSP(input, **kwargs)

A three-stage, third-order strong-stability preserving Runge-Kutta method. Requires unknown arrays to have temporary storage axes of length two.

class pystella.RungeKutta3Heun(input, **kwargs)

Heun’s three-stage, third-order Runge-Kutta method. Requires unknown arrays to have temporary storage axes of length three.

class pystella.RungeKutta3Nystrom(input, **kwargs)

Nystrom’s three-stage, third-order Runge-Kutta method. Requires unknown arrays to have temporary storage axes of length three.

class pystella.RungeKutta3Ralston(input, **kwargs)

Ralston’s three-stage, third-order Runge-Kutta method. Requires unknown arrays to have temporary storage axes of length three.

class pystella.RungeKutta2Midpoint(input, **kwargs)

The “midpoint” method, a two-stage, second-order Runge-Kutta method. Requires unknown arrays to have temporary storage axes of length two. Note that right-hand side operations can safely involve non-local computations of unknown arrays for this method.

class pystella.RungeKutta2Ralston(input, **kwargs)

Ralstons’s two-stage, second-order Runge-Kutta method. Requires unknown arrays to have temporary storage axes of length two.