pathsim.solvers.gear module

pathsim.solvers.gear.compute_bdf_coefficients(order, timesteps)[source]

Computes the coefficients for backward differentiation formulas for a given order. The timesteps can be specified for variable timestep BDF methods.

For m-th order BDF we have for the n-th timestep:

sum(alpha_i * x_i; i=n-m,…,n) = h_n * f_n(x_n, t_n)

or

x_n = beta * h_n * f_n(x_n, t_n) - sum(alpha_j * x_{n-1-j}; j=0,…,order-1)

Parameters:

  • order (int) – order of the integration scheme

  • timesteps (array[float]) – timestep buffer (h_{n-j}; j=0,…,order-1)

Returns:

  • beta (float) – weight for function

  • alpha (array[float]) – weights for previous solutions

class pathsim.solvers.gear.GEAR(*solver_args, **solver_kwargs)[source]

Bases: ImplicitSolver

Base class for GEAR-type integrators that defines the universal methods.

Numerical integration method based on BDFs (linear multistep methods). Uses n-th order BDF for timestepping and (n-1)-th order BDF coefficients to estimate a lower ordersolutuin for error control.

The adaptive timestep BDF coefficients are dynamically computed at the beginning of each timestep from the buffered previous timsteps.

Notes

Not to be used directly!

x

internal ‘working’ state

Type:

numeric, array[numeric]

n

order of integration scheme

Type:

int

s

number of internal intermediate stages

Type:

int

stage

counter for current intermediate stage

Type:

int

eval_stages

rations for evaluation times of intermediate stages

Type:

list[float]

opt

optimizer instance to solve the implicit update equation

Type:

NewtonAnderson, Anderson, etc.

K

bdf coefficients for the state buffer for each order

Type:

dict[int: list[float]]

F

bdf coefficients for the function ‘func’ for each order

Type:

dict[int: float]

history

internal history of past results

Type:

deque[numeric]

history_dt

internal history of past timesteps

Type:

deque[numeric]

startup

internal solver instance for startup (building history) of multistep methods (using ‘ESDIRK32’ for ‘GEAR’ methods)

Type:

Solver

stages(t, dt)[source]

Generator that yields the intermediate evaluation time during the timestep ‘t + ratio * dt’.

Parameters:

  • t (float) – evaluation time

  • dt (float) – integration timestep

reset()[source]

“Resets integration engine to initial state.

buffer(dt)[source]

Buffer the state and timestep. Dynamically precompute the variable timestep BDF coefficients on the fly for the current timestep.

Parameters:

dt (float) – integration timestep

revert()[source]

Revert integration engine to previous timestep, this is only relevant for adaptive methods where the simulation timestep ‘dt’ is rescaled and the engine step is recomputed with the smaller timestep.

error_controller(tr)[source]

Compute scaling factor for adaptive timestep based on absolute and relative tolerances for local truncation error.

Checks if the error tolerance is achieved and returns a success metric.

Parameters:

tr (array[float]) – truncation error estimate

Returns:

  • success (bool) – True if the timestep was successful

  • error (float) – estimated error of the internal error controller

  • scale (float) – estimated timestep rescale factor for error control

solve(f, J, dt)[source]

Solves the implicit update equation using the optimizer of the engine.

Parameters:

  • f (array_like) – evaluation of function

  • J (array_like) – evaluation of jacobian of function

  • dt (float) – integration timestep

Returns:

err – residual error of the fixed point update equation

Return type:

float

step(f, dt)[source]

Finalizes the timestep by resetting the solver for the implicit update equation and computing the lower order estimate of the solution for error control.

Parameters:

  • f (array_like) – evaluation of function

  • dt (float) – integration timestep

Returns:

  • success (bool) – True if the timestep was successful

  • error (float) – estimated error of the internal error controller

  • scale (float) – estimated timestep rescale factor for error control

class pathsim.solvers.gear.GEAR21(*solver_args, **solver_kwargs)[source]

Bases: GEAR

Adaptive-step GEAR integrator using 2nd order BDF for timestepping and 1st order BDF (Backward Euler) for truncation error estimation.

Suitable for moderately stiff problems where variable timestepping is beneficial.

Characteristics:

  • Stepping Order: 2 (max)

  • Error Estimation Order: 1

  • Implicit Variable-Step Multistep

  • Adaptive timestep

  • A-stable (based on BDF2)

class pathsim.solvers.gear.GEAR32(*solver_args, **solver_kwargs)[source]

Bases: GEAR

Adaptive-step GEAR integrator using 3rd order BDF for timestepping and 2nd order BDF for truncation error estimation.

Suitable for stiff problems requiring higher accuracy than GEAR21.

Characteristics:

  • Stepping Order: 3 (max)

  • Error Estimation Order: 2

  • Implicit Variable-Step Multistep

  • Adaptive timestep

  • A(alpha)-stable (based on BDF3)

class pathsim.solvers.gear.GEAR43(*solver_args, **solver_kwargs)[source]

Bases: GEAR

Adaptive-step GEAR integrator using 4th order BDF for timestepping and 3rd order BDF for truncation error estimation.

Suitable for stiff problems requiring good accuracy.

Characteristics:

  • Stepping Order: 4 (max)

  • Error Estimation Order: 3

  • Implicit Variable-Step Multistep

  • Adaptive timestep

  • A(alpha)-stable (based on BDF4)

class pathsim.solvers.gear.GEAR54(*solver_args, **solver_kwargs)[source]

Bases: GEAR

Adaptive-step GEAR integrator using 5th order BDF for timestepping and 4th order BDF for truncation error estimation.

Suitable for stiff problems requiring high accuracy, but stability region is smaller than lower-order GEAR methods.

Characteristics:

  • Stepping Order: 5 (max)

  • Error Estimation Order: 4

  • Implicit Variable-Step Multistep

  • Adaptive timestep

  • A(alpha)-stable (based on BDF5)

class pathsim.solvers.gear.GEAR52A(*solver_args, **solver_kwargs)[source]

Bases: GEAR

Adaptive-order, adaptive-stepsize GEAR integrator (Variable-Step Variable-Order BDF).

This method dynamically adjusts the BDF order used for timestepping (between 2 and 5) based on error estimates from lower and higher order predictors. It aims to optimize step size by using higher orders for smooth regions and lower, more stable orders for stiff or rapidly changing regions.

Error estimation compares the current order solution with predictions from order n-1 and n+1 formulas.

Characteristics:

  • Stepping Order: Variable (2 to 5)

  • Error Estimation Orders: n-1 and n+1 (relative to current n)

  • Implicit Variable-Step, Variable-Order Multistep

  • Adaptive timestep and order

  • Stability varies with the currently selected order (A-stable or A(alpha)-stable)

buffer(dt)[source]

Buffer the state and timestep. Dynamically precompute the variable timestep BDF coefficients on the fly for the current timestep.

Parameters:

dt (float) – integration timestep

error_controller(tr_m, tr_p)[source]

Compute scaling factor for adaptive timestep based on absolute and relative tolerances of the local truncation error estimate obtained from esimated lower and higher order solution.

Checks if the error tolerance is achieved and returns a success metric.

Adapts the stepping order such that the normalized error is minimized and larger steps can be taken by the integrator.

Parameters:

  • tr_m (array[float]) – lower order truncation error estimate

  • tr_p (array[float]) – higher order truncation error estimate

Returns:

  • success (bool) – True if the timestep was successful

  • error (float) – estimated error of the internal error controller

  • scale (float) – estimated timestep rescale factor for error control

solve(f, J, dt)[source]

Solves the implicit update equation using the optimizer of the engine.

Parameters:

  • f (array_like) – evaluation of function

  • J (array_like) – evaluation of jacobian of function

  • dt (float) – integration timestep

Returns:

err – residual error of the fixed point update equation

Return type:

float

step(f, dt)[source]

Finalizes the timestep by resetting the solver for the implicit update equation and computing the lower and higher order estimate of the solution.

Then calls the error controller.

Parameters:

  • f (array_like) – evaluation of function

  • dt (float) – integration timestep

Returns:

  • success (bool) – True if the timestep was successful

  • error (float) – estimated error of the internal error controller

  • scale (float) – estimated timestep rescale factor for error control