Block Base

class pathsim.blocks._block.Block

Bases: object

Base ‘Block’ object that defines the inputs, outputs and the block interface.

Block interconnections are handled 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{align} \dot{x} &= f_\mathrm{dyn}(x, u, t)\\ y &= f_\mathrm{alg}(x, u, t) \end{align}\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.

inputs

input value register of block

Type:

Register

outputs

output value register of block

Type:

Register

state

state of engine exposed as a property, only exists for dynamic blocks

Type:

None | float | np.ndarray

engine

numerical integrator instance, only exists for dynamic blocks

Type:

None | Solver

events

list of internal events, for mixed signal blocks

Type:

list[Event]

_active

flag that sets the block active or inactive

Type:

bool

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

input_port_labels = None

output_port_labels = None

property size

Get size information from block, such as number of internal states, etc.

Returns:

sizes – size of block (default 1) and number of internal states (from internal engine)

Return type:

tuple[int]

property shape

Get the number of input and output ports of the block

Returns:

shape – number of input and output ports

Return type:

tuple[int]

classmethod info()

Get block metadata for introspection and UI integration.

Returns a dictionary containing block type information, port mappings, and parameter definitions. Results are cached per class.

Returns:

info – Block metadata with the following keys: - type : str

Class name of the block

• descriptionstr

  Block docstring

• shapetuple

  Input/output shape (n_inputs, n_outputs)

• sizeint

  State vector size

• in_labelsdict

  Input port name to index mapping

• out_labelsdict

  Output port name to index mapping

• parametersdict

  Parameter names mapped to their default values

Return type:

dict

plot(*args, **kwargs)

Block specific visualization, enables plotting access from the simulation level.

This gets primarily used by the visualization blocks such as the ‘Scope’ and ‘Spectrum’.

Parameters:

• args (tuple) – args for the plot methods

• kwargs (dict) – kwargs for the plot method

on()

Activate the block and all internal events, sets the boolean evaluation flag to ‘True’.

off()

Deactivate the block and all internal events, sets the boolean evaluation flag to ‘False’. Also resets the block.

reset()

Reset the blocks inputs and outputs and also its internal solver, if the block has a solver instance.

linearize(t)

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 linearization.

Parameters:

t (float) – evaluation time

delinearize()

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)

Initialize the numerical integration engine with local truncation error tolerance if required.

If the block already has an integration engine, it is changed. If the block does not have an ‘initial_value’ attribute, this method does nothing (block is not dynamic).

Parameters:

• Solver (Solver) – numerical integrator class

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

• solver_args (dict) – additional args for the solver

revert()

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)

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)

Samples the data of the blocks inputs or internal state when called.

This can record block parameters after a successful timestep such as for the ‘Scope’ and ‘Delay’ blocks but also for sampling from a random distribution in the ‘RNG’ and the noise blocks.

Parameters:

• t (float) – evaluation time for sampling

• dt (float) – integration timestep

read()

Read data from recording blocks.

Note

Not implemented by default, special recording blocks implement this method.

collect()

Yield (category, id, data) tuples for recording blocks to simplify

Deprecated since version 1.0.0: its against pathsims philosophy

global data collection from all recording blocks.

Note

Yields an empty generator by default, needs to be implemented by special recording blocks.

get_all()

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

property state

Expose the state of the internal integration engine / Solver instance as an attribute of Block.

Note

Only applies to blocks that are dynamic.

Returns:

state – returns the current state of the block if the block is dynamic (has an internal Solver instance), otherwise returns None

Return type:

None, float, np.ndarray

update(t)

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)

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.

Parameters:

• t (float) – evaluation time

• dt (float) – integration timestep

Returns:

error – solver residual norm

Return type:

float

step(t, dt)

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.

Parameters:

• t (float) – evaluation time

• dt (float) – integration timestep

Returns:

• success (bool) – step was successful

• error (float) – local truncation error from adaptive integrators

• scale (float | None) – timestep rescale from adaptive integrators, None if no rescale needed