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.

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 Sectors. 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() 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(*args, **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.

Allocation of the auxillary arrays is handled internally by:

get_tmp_arrays_like(**kwargs)

Allocates required temporary arrays matching those passed via keyword.

Returns:

A dict of named arrays, suitable for passing via dictionary expansion.

New in version 2020.2.

get_tmp_arrays_like() is called the first time __call__() is called, with the result stored in the attribute tmp_arrays. These arrays must not be modified between substages of a single timestep, but may be safely modified in between timesteps.

Changed in version 2020.2: Auxillary arrays handled internally by get_tmp_arrays_like(). Previously, manual allocation (and passing) of a single temporary array k_tmp was required.

class pystella.LowStorageRK54(*args, **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(*args, **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(*args, **kwargs)

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

class pystella.LowStorageRK3SSP(*args, **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 Fields (or pymbolic.primitives.Subscripts 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.