pathsim.blocks._block module

class pathsim.blocks._block.Block

Bases: Serializable

Base ‘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.

Notes

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:

dict{int: float}

outputs

output value register of block

Type:

dict{int: float}

engine

numerical integrator instance

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

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.

get_events()

Return internal events of the block, for discrete time blocks such as triggers / comparators, clocks, etc.

Returns:

events – internal events of the block

Return type:

list[Event]

set_solver(Solver, **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 it does not require an integration engine, this method just passes.

Parameters:

• Solver (Solver) – numerical integrator

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

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.

Parameters:

t (float) – evaluation time for sampling

set(port, value)

Set the value of an input port of the block.

Parameters:

• port (int) – input port number

• value (int, float, complex) – value to set at input register port

get(port)

Get the value of an output port of the block.

Uses the ‘get’ method of ‘outputs’ dict with default value ‘0.0’.

Parameters:

port (int) – output port number

Returns:

value – value of the output register port

Return type:

int, float, complex

update(t)

The ‘update’ method is called iteratively for all blocks BEFORE the timestep to resolve algebraic loops (fixed-point iteraion).

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.

It computes and returns the relative difference between the new output and the previous output (before the step) to track convergence of the fixed-point iteration.

Parameters:

t (float) – evaluation time

Returns:

error – relative error to previous iteration for convergence control

Return type:

float

solve(t, dt)

The ‘solve’ method performes 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 performes 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) – timestep rescale from adaptive integrators