pathsim.solvers.gear module

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

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

“Resets integration engine to initial state.

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

Adaptive-step GEAR integrator using 2nd order BDF with variable timesteps.

Uses 2nd order BDF for timestepping and 1st order BDF (Backward Euler) for truncation error estimation. Dynamically computes BDF coefficients for variable timesteps. Excellent for moderately stiff problems where adaptive timestepping is beneficial. Uses ESDIRK32 for startup.

Characteristics

• Stepping Order: 2 (max)

• Error Estimation Order: 1

• Implicit Variable-Step Multistep

• Adaptive timestep

• A-stable (based on BDF2)

When to Use

• Stiff problems with adaptive stepping: Classic adaptive stiff solver

• Variable dynamics: When solution changes character over time

• Efficient stiff integration: Good balance of stability and accuracy

• Long-time simulations: Stable for extended integrations

Note

Good choice as a default adaptive stiff solver. For higher accuracy, use GEAR32 or ESDIRK43. For fixed timestep, use BDF2.

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.

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

Bases: GEAR

Adaptive-step GEAR integrator using 3rd order BDF with variable timesteps.

Uses 3rd order BDF for timestepping and 2nd order BDF for truncation error estimation. Dynamically computes BDF coefficients for variable timesteps. Suitable for stiff problems requiring higher accuracy than GEAR21. Uses ESDIRK32 for startup.

Characteristics

• Stepping Order: 3 (max)

• Error Estimation Order: 2

• Implicit Variable-Step Multistep

• Adaptive timestep

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

When to Use

• Higher accuracy stiff problems: 3rd order with adaptive stepping

• Good stability/accuracy balance: Better accuracy with excellent stability

• Chemical reactions: Common in kinetics problems

• Engineering simulations: Widely used in practice

Note

Slightly less stable than GEAR21, but more accurate. For very high accuracy, use GEAR43 or ESDIRK54.

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.

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

Bases: GEAR

Adaptive-step GEAR integrator using 4th order BDF with variable timesteps.

Uses 4th order BDF for timestepping and 3rd order BDF for truncation error estimation. Dynamically computes BDF coefficients for variable timesteps. Suitable for stiff problems requiring good accuracy. Uses ESDIRK32 for startup.

Characteristics

• Stepping Order: 4 (max)

• Error Estimation Order: 3

• Implicit Variable-Step Multistep

• Adaptive timestep

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

When to Use

• High-accuracy stiff problems: 4th order with adaptive stepping

• Demanding applications: When higher accuracy is needed

• Smooth stiff dynamics: Problems with smooth solutions

• Scientific computing: Common in research applications

Note

Smaller stability angle than GEAR32. For very stiff problems, GEAR21 or GEAR32 may be more robust. For very high accuracy, use GEAR54 or ESDIRK54.

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.

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

Bases: GEAR

Adaptive-step GEAR integrator using 5th order BDF with variable timesteps.

Uses 5th order BDF for timestepping and 4th order BDF for truncation error estimation. Dynamically computes BDF coefficients for variable timesteps. Suitable for stiff problems requiring high accuracy, but stability region is smaller than lower-order GEAR methods. Uses ESDIRK32 for startup.

Characteristics

• Stepping Order: 5 (max)

• Error Estimation Order: 4

• Implicit Variable-Step Multistep

• Adaptive timestep

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

When to Use

• Very high accuracy on mildly stiff problems: 5th order when stability angle sufficient

• Smooth stiff problems: Problems without extreme stiffness

• High-precision requirements: Better accuracy than GEAR43

• Research applications: Specialized high-accuracy needs

Warns:

• Reduced stability compared to lower-order GEAR methods. For very stiff problems,

• use GEAR21 or GEAR32. Consider ESDIRK54 as an alternative high-accuracy stiff solver.

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.

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

Bases: GEAR

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

This method dynamically adjusts both timestep and BDF order (between 2 and 5) based on error estimates from lower and higher order predictors. Optimizes step size by using higher orders for smooth regions and lower, more stable orders for stiff or rapidly changing regions. Dynamically computes BDF coefficients for variable timesteps and orders. Uses ESDIRK32 for startup.

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

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)

When to Use

• Problems with varying character: Automatically adapts to changing dynamics

• Black-box applications: Minimal tuning required

• Efficiency priority: Optimizes order for efficiency

• General-purpose adaptive stiff solver: Robust default choice

Note

Recommended for problems where the optimal order is unknown. This is similar to MATLAB’s ode15s. Can be more efficient than fixed-order methods for problems with varying smoothness.

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.

[3]

Hairer, E., & Wanner, G. (1996). “Solving Ordinary Differential Equations II: Stiff and Differential-Algebraic Problems”. Springer Series in Computational Mathematics, Vol. 14.

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