pathsim.simulation
- class pathsim.simulation.Simulation(blocks=None, connections=None, events=None, dt=0.01, dt_min=1e-16, dt_max=None, Solver=<class 'pathsim.solvers.ssprk22.SSPRK22'>, tolerance_fpi=1e-12, iterations_min=1, iterations_max=200, log=True, **solver_args)[source]
Bases:
objectClass that performs transient analysis of the dynamical system, defined by the blocks and connecions. It manages all the blocks and connections and the timestep update.
The global system equation is evaluated by fixed point iteration, so the information from each timestep gets distributed within the entire system and is available for all blocks at all times.
The minimum number of fixed-point iterations ‘iterations_min’ is set to ‘None’ by default and then the length of the longest internal signal path (with passthrough) is used as the estimate for minimum number of iterations needed for the information to reach all instant time blocks in each timestep. Dont change this unless you know that the actual path is shorter or something similar that prohibits instant time information flow.
Convergence check for the fixed-point iteration loop with ‘tolerance_fpi’ is based on max absolute error (max-norm) to previous iteration and should not be touched.
Multiple numerical integrators are implemented in the ‘pathsim.solvers’ module. The default solver is a fixed timestep 2nd order Strong Stability Preserving Runge Kutta (SSPRK22) method which is quite fast and has ok accuracy, especially if you are forced to take small steps to cover the behaviour of forcing functions. Adaptive timestepping and implicit integrators are also available.
Manages an event handling system based on zero crossing detection. Uses ‘Event’ objects to monitor solver states of stateful blocks and applys transformations on the state in case an event is detected.
- Parameters:
connections (list[Connection]) – connections that connect the blocks
events (list[Event]) – list of event trackers (zero crossing detection)
dt (float) – transient simulation timestep in time units
dt_min (float) – lower bound for timestep, default ‘0.0’
dt_max (float) – upper bound for timestep, default ‘None’
Solver (Solver) – solver for numerical integration from pathsim.solvers
tolerance_fpi (float) – absolute tolerance for convergence of fixed-point iterations
iterations_min (int) – minimum number of fixed-point iterations for system function evaluation
iterations_max (int) – maximum allowed number of fixed-point iterations for system function evaluation
log (bool, string) – flag to enable logging (alternatively a path can be specified)
solver_args (dict) – additional parameters for numerical solvers such as abs and rel tolerance
- logger
global simulation logger
- Type:
- save(path='')[source]
Save the dictionary representation of the simulation instance to an external file
- Parameters:
path (str) – filepath to save data to
- classmethod load(path='')[source]
Load and instantiate a Simulation from an external file in json format
- Parameters:
path (str) – filepath to load data from
- Returns:
out – reconstructed object from dict representation
- Return type:
- to_dict(name='Model', description='')[source]
Convert simulation to a complete model representation as a dict with additional metadata.
- classmethod from_dict(data)[source]
Create simulation from model data dict
- Parameters:
data (dict) – model definition in json format
- Returns:
simulation – instance of the Simulation class with mode definition
- Return type:
- add_block(block, recompute_path=True)[source]
Adds a new block to the simulation, initializes its local solver instance and collects internal events of the new block.
This works dynamically for running simulations.
Recomputes the length of the longest internal algebraic signal path if specified in the argument. This is for dynamically adding blocks mid simulation.
- add_connection(connection, recompute_path=True)[source]
Adds a new connection to the simulaiton and checks if the new connection overwrites any existing connections.
This works dynamically for running simulations.
Recomputes the length of the longest internal algebraic signal path if specified in the argument. This is for dynamically adding connections mid simulation.
- Parameters:
connection (Connection) – connection to add to the simulation
recompute_path (bool) – flag for recomputing the algebraic path length
- add_event(event)[source]
Checks and adds a new event to the simulation.
This works dynamically for running simulations.
- Parameters:
event (Event) – event to add to the simulation
- reset()[source]
Reset the blocks to their initial state and the global time of the simulation.
For recording blocks such as ‘Scope’, their recorded data is also reset.
Afterwards the system function os evaluated with ‘_update’ to update the block inputs and outputs.
- steadystate(reset=True)[source]
Find steady state solution (DC operating point) of the system by switching all blocks to steady state solver, solving the fixed point equations, then switching back.
The steady state solver forces all the temporal derivatives, i.e. the right hand side equation (including external inputs) of the engines of dynamic blocks to zero.
- Parameters:
reset (bool) – reset the simulation before solving for steady state
- step_fixed(dt=None)[source]
Advances the simulation by one timestep ‘dt’ for fixed step solvers.
Selects between implicit and explicit solvers. Implicit solvers have an additional loop for solving the implicit update equation in each timestep.
If discrete events are detected, they are resolved immediately within the timestep.
- Parameters:
dt (float) – timestep
- Returns:
success (bool) – indicator if the timestep was successful
max_error (float) – maximum local truncation error from integration
scale (float) – rescale factor for timestep
total_evals (int) – total number of system evaluations
total_solver_its (int) – total number of implicit solver iterations
- step_adaptive(dt=None)[source]
Advances the simulation by one timestep ‘dt’ for adaptive solvers.
Selects between implicit and explicit solvers. Implicit solvers have an additional loop for solving the implicit update equation in each timestep.
If the local truncation error of the solver exceeds the tolerances set in the ‘solver_args’, simulation state is reverted to the state before the ‘step’ method was called.
If the solver is implicit and the solution of the implicit update equation in ‘solve’ doesnt converge, the timestep is also considered unsuccessful. Then it is reverted and the timestep is halfed.
If discrete events are detected, the chronologically first event is handled only. The event location (in time) is approached adaptively by reverting the step and adjusting the stepsize (this is equivalent to the secant method for finding zeros of the event function) until the tolerance of the event is satisfied (close==True).
- Parameters:
dt (float) – timestep
- Returns:
success (bool) – indicator if the timestep was successful
max_error (float) – maximum local truncation error from integration
scale (float) – rescale factor for timestep
total_evals (int) – total number of system evaluations
total_solver_its (int) – total number of implicit solver iterations
- step(dt=None, adaptive=False)[source]
Advances the simulation by one timestep ‘dt’.
Wraps the ‘step_fixed’ and ‘step_adaptive’ methods and selects between them. Can be called from the outside in case the simulation should be advanced one step at a time.
- Parameters:
- Returns:
success (bool) – indicator if the timestep was successful
max_error (float) – maximum local truncation error from integration
scale (float) – rescale factor for timestep
total_evals (int) – total number of system evaluations
total_solver_its (int) – total number of implicit solver iterations
- run(duration=10, reset=True, adaptive=True)[source]
Perform multiple simulation timesteps for a given ‘duration’.
Tracks the total number of block evaluations (proxy for function calls, although larger, since one function call of the system equation consists of many block evaluations) and the total number of solver iterations for implicit solvers.
Additionally the progress of the simulation is tracked by a custom ‘ProgressTracker’ class that is a dynamic generator and interfaces the logging system.