pathsim.blocks._block module¶
- class pathsim.blocks._block.Block[source]¶
Bases:
SerializableBase ‘Block’ object that defines the inputs, outputs and the connect method.
Block interconnections are handeled via the io interface of the blocks. It is realized by dicts for the ‘inputs’ and for the ‘outputs’, where the key of the dict is the input/output channel and the corresponding value is the input/output value.
The block can spawn discrete events that are handled by the main simulation for triggers, discrete time blocks, etc.
Mathematically the block behavior is defined by two operators in most cases
\[\begin{split}\begin{eqnarray} \dot{x} &= f_\mathrm{dyn}(x, u, t)\\ y &= f_\mathrm{alg}(x, u, t) \end{eqnarray}\end{split}\]they are algebraic operators for the algebraic path of the block and for the dynamic path that feeds into the internal numerical integration engine.
There are special cases where one or both of them are not defined, also for purely algebraic blocks such as multipliers and functions, there exists a simplified operator definition:
\[y = f_\mathrm{alg}(u)\]Note
This block is not intended to be used directly and serves as a base class definition for other blocks to be inherited.
- op_alg¶
internal callable operator for algebraic components of block
- Type:
Operator | DynamicOperator | None
- op_dyn¶
internal callable operator for dynamic (ODE) components of block
- Type:
DynamicOperator | None
- _port_map_in¶
string aliases for input port numbers to be referenced in connections or for internal use
- Type:
dict[str: int]
- _port_map_out¶
string aliases for output port numbers to be referenced in connections or for internal use
- Type:
dict[str: int]
- property size¶
Get size information from block, such as number of internal states, etc.
- property shape¶
Get the number of input and output ports of the block
- plot(*args, **kwargs)[source]¶
Block specific visualization, enables plotting access from the simulation level.
This gets primarily used by the visualization blocks such as the ‘Scope’ and ‘Spectrum’.
- on()[source]¶
Activate the block and all internal events, sets the boolean evaluation flag to ‘True’.
- off()[source]¶
Deactivate the block and all internal events, sets the boolean evaluation flag to ‘False’. Also resets the block.
- reset()[source]¶
Reset the blocks inputs and outputs and also its internal solver, if the block has a solver instance.
- linearize(t)[source]¶
Linearize the algebraic and dynamic components of the block.
This is done by linearizing the internal ‘Operator’ and ‘DynamicOperator’ instances in the current system operating point. The operators create 1st order taylor approximations internally and use them on subsequent calls after linarization.
- Parameters:
t (float) – evaluation time
- delinearize()[source]¶
Revert the linearization of the blocks algebraic and dynamic components.
This is resets the internal ‘Operator’ and ‘DynamicOperator’ instances, deleting the linear surrogate model and using the original function for subsequent calls.
- set_solver(Solver, parent, **solver_args)[source]¶
Initialize the numerical integration engine with local truncation error tolerance if required.
If the block already has an integration engine, it is changed, if it does not require an integration engine, this method just passes.
- revert()[source]¶
Revert the block to the state of the previous timestep, if the block has a solver instance indicated by the ‘has_engine’ flag.
This is required for adaptive solvers to revert the state to the previous timestep.
- buffer(dt)[source]¶
Buffer current internal state of the block and the current timestep if the block has a solver instance (is stateful).
This is required for multistage, multistep and adaptive integrators.
- Parameters:
dt (float) – integration timestep
- sample(t, dt)[source]¶
Samples the data of the blocks inputs or internal state when called.
This can record block parameters after a succesful timestep such as for the ‘Scope’ and ‘Delay’ blocks but also for sampling from a random distribution in the ‘RNG’ and the noise blocks.
- get_all()[source]¶
Retrieves and returns internal states of engine (if available) and the block inputs and outputs as arrays for use outside.
Either for monitoring, postprocessing or event detection. In any case this enables easy access to the current block state.
- Returns:
inputs (array) – block input register
outputs (array) – block output register
states (array) – internal states of the block
- update(t)[source]¶
The ‘update’ method is called iteratively for all blocks to evaluate the algebraic components of the global system ode from the DAG.
It is meant for instant time blocks (blocks that dont have a delay due to the timestep, such as Amplifier, etc.) and updates the ‘outputs’ of the block directly based on the ‘inputs’ and possibly internal states.
Note
The implementation of the ‘update’ method in the base ‘Block’ class is intended as a fallback and is not performance optimized. Special blocks might reimplement this method differently for higher performance, for example SISO or MISO blocks.
- Parameters:
t (float) – evaluation time
- solve(t, dt)[source]¶
The ‘solve’ method performs one iterative solution step that is required to solve the implicit update equation of the solver if an implicit solver (numerical integrator) is used.
It returns the relative difference between the new updated solution and the previous iteration of the solution to track convergence within an outer loop.
This only has to be implemented by blocks that have an internal integration engine with an implicit solver.
- step(t, dt)[source]¶
The ‘step’ method is used in transient simulations and performs an action (numeric integration timestep, recording data, etc.) based on the current inputs and the current internal state.
It performs one timestep for the internal states. For instant time blocks, the ‘step’ method does not has to be implemented specifically.
The method handles timestepping for dynamic blocks with internal states such as ‘Integrator’, ‘StateSpace’, etc.