Gear

pathsim.solvers.gear.compute_bdf_coefficients(order, timesteps)

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)

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

classmethod cast(other, parent, **solver_kwargs)

cast to this solver needs special handling of startup method

Parameters:

• other (Solver) – solver instance to cast new instance of this class from

• parent (None | Solver) – solver instance to use as parent

• solver_kwargs (dict) – other args for the solver

Returns:

engine – instance of GEAR solver with params and state from other

Return type:

GEAR

classmethod create(initial_value, parent=None, from_engine=None, **solver_kwargs)

Create a new GEAR solver, properly initializing the startup solver.

Parameters:

• initial_value (float, array) – initial condition / integration constant

• parent (None | Solver) – parent solver instance for stage synchronization

• from_engine (None | Solver) – existing solver to inherit state and settings from

• solver_kwargs (dict) – additional args for the solver

Returns:

engine – new GEAR solver instance

Return type:

GEAR

to_checkpoint(prefix)

Serialize GEAR solver state including startup solver and timestep history.

load_checkpoint(json_data, npz, prefix)

Restore GEAR solver state including startup solver and timestep history.

stages(t, dt)

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

Parameters:

• t (float) – evaluation time

• dt (float) – integration timestep

reset(initial_value=None)

“Resets integration engine to initial value, optionally provides new initial value

Parameters:

initial_value (None | float | np.ndarray) – new initial value of the engine, optional

buffer(dt)

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()

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)

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)

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)

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)

Bases: GEAR

Variable-step 2nd order BDF with 1st order error estimate. A-stable.

BDF coefficients are recomputed each step to account for variable timesteps. Uses ESDIRK32 as startup solver.

Characteristics

• Order: 2 (stepping) / 1 (error estimate)

• Implicit variable-step multistep

• Adaptive timestep

• A-stable

Note

The simplest adaptive multistep stiff solver. A-stability makes it safe for any stiff block diagram. The multistep approach reuses past solution values, so per-step cost is lower than single-step implicit methods (ESDIRK), but a startup phase is needed to fill the history buffer. For higher accuracy, use GEAR32 or ESDIRK43.

References

[1]

Gear, C. W. (1971). “Numerical Initial Value Problems in Ordinary Differential Equations”. Prentice-Hall.

[2]

Hairer, E., & Wanner, G. (1996). “Solving Ordinary Differential Equations II: Stiff and Differential-Algebraic Problems”. Springer Series in Computational Mathematics, Vol. 14. :doi:`10.1007/978-3-642-05221-7`

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

Bases: GEAR

Variable-step 3rd order BDF with 2nd order error estimate. \(A(\alpha)\)-stable.

Uses ESDIRK32 as startup solver.

Characteristics

• Order: 3 (stepping) / 2 (error estimate)

• Implicit variable-step multistep

• Adaptive timestep

• \(A(\alpha)\)-stable (BDF3 stability wedge)

Note

Good balance of accuracy and stability for stiff block diagrams. The stability wedge is nearly as wide as GEAR21 (\(\approx 86°\)) while providing an extra order of accuracy. For most stiff systems this is a practical default when a multistep solver is preferred over ESDIRK.

References

[1]

Gear, C. W. (1971). “Numerical Initial Value Problems in Ordinary Differential Equations”. Prentice-Hall.

[2]

Hairer, E., & Wanner, G. (1996). “Solving Ordinary Differential Equations II: Stiff and Differential-Algebraic Problems”. Springer Series in Computational Mathematics, Vol. 14. :doi:`10.1007/978-3-642-05221-7`

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

Bases: GEAR

Variable-step 4th order BDF with 3rd order error estimate. \(A(\alpha)\)-stable.

Uses ESDIRK32 as startup solver.

Characteristics

• Order: 4 (stepping) / 3 (error estimate)

• Implicit variable-step multistep

• Adaptive timestep

• \(A(\alpha)\)-stable (BDF4 stability wedge, \(\approx 73°\))

Note

Narrower stability wedge than GEAR32. Eigenvalues near the imaginary axis may be poorly damped. Use only when the stiff modes are strongly dissipative and 4th order accuracy is needed. Otherwise, GEAR32 or ESDIRK43 are safer choices.

References

[1]

Gear, C. W. (1971). “Numerical Initial Value Problems in Ordinary Differential Equations”. Prentice-Hall.

[2]

Hairer, E., & Wanner, G. (1996). “Solving Ordinary Differential Equations II: Stiff and Differential-Algebraic Problems”. Springer Series in Computational Mathematics, Vol. 14. :doi:`10.1007/978-3-642-05221-7`

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

Bases: GEAR

Variable-step 5th order BDF with 4th order error estimate. \(A(\alpha)\)-stable.

Uses ESDIRK32 as startup solver.

Characteristics

• Order: 5 (stepping) / 4 (error estimate)

• Implicit variable-step multistep

• Adaptive timestep

• \(A(\alpha)\)-stable (BDF5 stability wedge, \(\approx 51°\))

Note

The stability wedge is significantly narrower than lower-order GEAR variants. Only justified for mildly stiff problems where 5th order accuracy yields a clear efficiency gain. For strongly stiff systems, GEAR21/GEAR32 or ESDIRK54 are more robust.

References

[1]

Gear, C. W. (1971). “Numerical Initial Value Problems in Ordinary Differential Equations”. Prentice-Hall.

[2]

Hairer, E., & Wanner, G. (1996). “Solving Ordinary Differential Equations II: Stiff and Differential-Algebraic Problems”. Springer Series in Computational Mathematics, Vol. 14. :doi:`10.1007/978-3-642-05221-7`

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

Bases: GEAR

Variable-step, variable-order BDF (orders 2–5). Adapts both timestep and order automatically.

At each step the error controller compares estimates from orders \(n-1\) and \(n+1\) and selects the order that minimises the normalised error, allowing larger steps. Analogous to MATLAB’s ode15s. Uses ESDIRK32 as startup solver.

Characteristics

• Order: variable, 2–5

• Implicit variable-step, variable-order multistep

• Adaptive timestep and order

• Stability: A-stable at order 2, \(A(\alpha)\)-stable at orders 3–5

Note

The most autonomous stiff solver in this library. Automatically selects higher orders in smooth regions for larger steps and drops to low order in stiff or transient regions for stability. A good default when the character of the block diagram is unknown or changes during the simulation (e.g. switching events, varying loads).

References

[1]

Gear, C. W. (1971). “Numerical Initial Value Problems in Ordinary Differential Equations”. Prentice-Hall.

[2]

Shampine, L. F., & Reichelt, M. W. (1997). “The MATLAB ODE Suite”. SIAM Journal on Scientific Computing, 18(1), 1-22. :doi:`10.1137/S1064827594276424`

[3]

Hairer, E., & Wanner, G. (1996). “Solving Ordinary Differential Equations II: Stiff and Differential-Algebraic Problems”. Springer Series in Computational Mathematics, Vol. 14. :doi:`10.1007/978-3-642-05221-7`

buffer(dt)

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)

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)

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)

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