pathsim.solvers._solver module

class pathsim.solvers._solver.Solver(initial_value=0, func=<function Solver.<lambda>>, jac=None, tolerance_lte_abs=1e-08, tolerance_lte_rel=1e-05)

Bases: object

Base skeleton class for solver definition. Defines the basic solver methods and the metadata.

Specific solvers need to implement (some of) the base class methods defined here. This depends on the type of solver (implicit/explicit, multistage, adaptive).

Parameters:

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

• func (callable) – function to integrate with state ‘x’, input ‘u’ and time ‘t’ dependency

• jac (callable, None) – jacobian of ‘func’ with respect to ‘x’, depending on ‘x’, ‘u’ and ‘t’, if ‘None’, no jacobian is used

• tolerance_lte_abs (float) – absolute tolerance for local truncation error (for solvers with error estimate)

• tolerance_lte_rel (float) – relative tolerance for local truncation error (for solvers with error estimate)

x_0

internal ‘working’ initial value

Type:

numeric, array[numeric]

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]

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

get()

Returns current internal state of the solver.

Returns:

x – current internal state of the solver

Return type:

numeric, array[numeric]

set(x)

Sets the internal state of the integration engine.

This method is required for event based simulations, and to handle discontinuities in state variables.

Parameters:

x (numeric, array[numeric]) – new internal state of the solver

reset()

“Resets integration engine to initial value

buffer(dt)

Saves the current state to an internal state buffer which is especially relevant for multistage and implicit solvers.

Multistep solver implement rolling buffers for the states and timesteps.

Resets the stage counter.

Parameters:

dt (float) – integration timestep

classmethod cast(other, **solver_args)

Cast the integration engine to the new type and initialize with previous solver arguments so it can continue from where the ‘old’ solver stopped.

Parameters:

• other (Solver) – solver instance to cast to new solver type

• solver_args (dict) – additional args for the new solver

Returns:

engine – new solver instance

Return type:

Solver

error_controller()

Returns the estimated local truncation error (abs and rel) and scaling factor for the timestep, only relevant for adaptive timestepping methods.

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

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.

step(u, t, dt)

Performs the explicit timestep for (t+dt) based on the state and input at (t).

Returns the local truncation error estimate and the rescale factor for the timestep if the solver is adaptive.

Parameters:

• u (numeric, array[numeric]) – function ‘func’ input value

• t (float) – evaluation time of function ‘func’

• 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

interpolate(r, dt)

Interpolate solution after successful timestep as a ratio in the interval [t, t+dt].

This is especially relevant for Runge-Kutta solvers that have a higher order interpolant. Otherwise this is just linear interpolation using the buffered state.

Parameters:

• r (float) – ration for interpolation within timestep

• dt (float) – integration timestep

Returns:

x – interpolated state

Return type:

numeric, array[numeric]

class pathsim.solvers._solver.ExplicitSolver(*solver_args, **solver_kwargs)

Bases: Solver

Base class for explicit solver definition.

x_0

internal ‘working’ initial value

Type:

numeric, array[numeric]

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]

integrate_singlestep(time=0.0, dt=0.1)

Directly integrate the function ‘func’ for a single timestep ‘dt’ with explicit solvers. This method is primarily intended for testing purposes.

Parameters:

• time_start (float) – starting time for timestep

• dt (float) – integration timestep

Returns:

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

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

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

integrate(time_start=0.0, time_end=1.0, dt=0.1, dt_min=0.0, dt_max=None, adaptive=True)

Directly integrate the function ‘func’ from ‘time_start’ to ‘time_end’ with timestep ‘dt’ for explicit solvers.

This method is primarily intended for testing purposes.

Parameters:

• time_start (float) – starting time for integration

• time_end (float) – end time for integration

• dt (float) – timestep or initial timestep for adaptive solvers

• dt_min (float) – lower bound for timestep, default ‘0.0’

• dt_max (float) – upper bound for timestep, default ‘None’

• adaptive (bool) – use adaptive timestepping if available

Returns:

• outout_times (array[float]) – time points of the solution

• output_states (array[numeric], array[array[numeric]]) – state values at solution time points

class pathsim.solvers._solver.ImplicitSolver(*solver_args, **solver_kwargs)

Bases: Solver

Base class for implicit solver definition.

x_0

internal ‘working’ initial value

Type:

numeric, array[numeric]

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.

buffer(dt)

Saves the current state to an internal state buffer which is especially relevant for multistage and implicit solvers.

Resets the stage counter and the optimizer of implicit methods.

Parameters:

dt (float) – integration timestep

solve(u, t, dt)

Advances the solution of the implicit update equation of the solver with the optimizer of the engine and tracks the evolution of the solution by providing the residual norm of the fixed-point solution.

Parameters:

• u (numeric, array[numeric]) – function ‘func’ input value

• t (float) – evaluation time of function ‘func’

• dt (float) – integration timestep

Returns:

err – residual error of the fixed point update equation

Return type:

float

integrate_singlestep(time=0.0, dt=0.1, tolerance_fpi=1e-12, max_iterations=5000)

Directly integrate the function ‘func’ for a single timestep ‘dt’ with implicit solvers. This method is primarily intended for testing purposes.

Parameters:

• time_start (float) – starting time for timestep

• dt (float) – integration timestep

• tolerance_fpi (float) – convergence criterion for implicit update equation

• max_iterations (int) – maximum numer of iterations for optimizer to solve implicit update equation

Returns:

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

• success_sol (bool) – True if optimizer successfully solved implicit update equation

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

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

integrate(time_start=0.0, time_end=1.0, dt=0.1, dt_min=0.0, dt_max=None, adaptive=True, tolerance_fpi=1e-12, max_iterations=5000)

Directly integrate the function ‘func’ from ‘time_start’ to ‘time_end’ with timestep ‘dt’ for implicit solvers.

This method is primarily intended for testing purposes.

Parameters:

• time_start (float) – starting time for integration

• time_end (float) – end time for integration

• dt (float) – timestep or initial timestep for adaptive solvers

• dt_min (float) – lower bound for timestep, default ‘0.0’

• dt_max (float) – upper bound for timestep, default ‘None’

• adaptive (bool) – use adaptive timestepping if available

• tolerance_fpi (float) – convergence criterion for implicit update equation

• max_iterations (int) – maximum numer of iterations for optimizer to solve implicit update equation

Returns:

• outout_times (array[float]) – time points of the solution

• output_states (array[numeric], array[array[numeric]]) – state values at solution time points