{ "package": "fastsim", "modules": { "fastsim": { "name": "fastsim", "description": "", "docstring_html": "", "classes": [ { "name": "Connection", "description": "Class to handle input-output relations of blocks by connecting them (directed graph)", "docstring_html": "

Class to handle input-output relations of blocks by connecting them (directed graph)\nand transfering data from the output port of the source block to the input port of\nthe target block.

The default ports for connection are (0) -> (0), since these are the default inputs\nthat are used in the SISO blocks.

Examples

Lets assume we have some generic blocks

\nfrom pathsim.blocks._block import Block\n\nB1 = Block()\nB2 = Block()\nB3 = Block()\n

that we want to connect. We initialize a 'Connection' with the blocks directly\nas the arguments if we want to connect the default ports (0) -> (0)

\nfrom pathsim import Connection\n\nC = Connection(B1, B2)\n

which is a connection from block 'B1' to 'B2'. If we want to explicitly declare\nthe input and output ports we can do that by utilizing the '__getitem__' method\nof the blocks

\nC = Connection(B1[0], B2[0])\n

which is exactly the default port setup. Connecting output port (1) of 'B1' to\nthe default input port (0) of 'B2' do

\nC = Connection(B1[1], B2[0])\n

or just

\nC = Connection(B1[1], B2).\n

The 'Connection' class also supports multiple targets for a single source.\nThis is specified by just adding more blocks with their respective ports into\nthe constructor like this:

\nC = Connection(B1, B2[0], B2[1], B3)\n

The port definitions follow the same structure as for single target connections.

'self'-connections also work without a problem. This is useful for modeling direct\nfeedback of a block to itself.

Port definitions support slicing. This enables direct MIMO connections. For example\nconnecting ports 0, 1, 2 of 'B1' to ports 1, 2, 3 of 'B2' works like this:

\nC = Connection(B1[0:2], B2[1:3])\n

Port definitions also support lists and tuples of 'int'. For example the slice\nabove is identical to this:

\nC = Connection(B1[0, 1], B2[1, 2])\n

Or to be more programmatic about it, like this:

\nprts_1 = [0, 1]\nprts_2 = [1, 2]\n\nC = Connection(B1[prts_1], B2[prts_2])\n

Another way to define the ports is by using strings. Some blocks have internal\naliases for the ports that can be used instead of the integer port indices to\ndefine the connections (or access the port data):

\nC = Connection(B1["out"], B2["in"])\n

Or mixed with integer port indices:

\nC = Connection(B1["out"], B2["in"])\n

Parameters

source : PortReference, Block: source block and optional source output port
targets : tuple[PortReference], tuple[Block]: target blocks and optional target input ports

Attributes

_active : bool: flag to set 'Connection' as active or inactive

\n", "source": null, "bases": [ "fastsim._fastsim.Connection" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "Interface", "description": "Bare-bone block that serves as a data interface for the 'Subsystem' class.", "docstring_html": "

Bare-bone block that serves as a data interface for the 'Subsystem' class.

It works like this:

Internal blocks of the subsystem are connected to the inputs and outputs\nof this Interface block via the internal connections.
It behaves like a normal block (inherits the main 'Block' class methods).
It implements some special methods to get and set the inputs and outputs\nof the blocks, that are used to translate between the internal blocks of the\nsubsystem and the inputs and outputs of the subsystem.
Handles data transfer to and from the internal subsystem blocks\nto and from the inputs and outputs of the subsystem.

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Interface'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" } ], "parameters": [] }, { "name": "Subsystem", "description": "Subsystem class that holds its own blocks and connecions and", "docstring_html": "

Subsystem class that holds its own blocks and connecions and\ncan natively interface with the main simulation loop.

IO interface is realized by a special 'Interface' block, that has extra\nmethods for setting and getting inputs and outputs and serves\nas the interface of the internal blocks to the outside.

The subsystem doesnt use its 'inputs' and 'outputs' dicts directly.\nIt exclusively handles data transfer via the 'Interface' block.

This class can be used just like any other block during the simulation,\nsince it implements the required methods 'update' for the fixed-point\niteration (resolving algebraic loops with instant time blocks),\nthe 'step' method that performs timestepping (especially for dynamic\nblocks with internal states) and the 'solve' method for solving the\nimplicit update equation for implicit solvers.

Example

This is how we can wrap up multiple blocks within a subsystem.\nIn this case vanderpol system built from discrete components\ninstead of using an ODE block (in practice you should use\na monolithic ODE whenever possible due to performance).

\nfrom pathsim import Subsystem, Interface, Connection\nfrom pathsim.blocks import Integrator, Function\n\n#van der Pol parameter\nmu = 1000\n\n#blocks in the subsystem\nIf = Interface() # this is the interface to the outside\nI1 = Integrator(2)\nI2 = Integrator(0)\nFn = Function(lambda x1, x2: mu*(1 - x1**2)*x2 - x1)\n\nsub_blocks = [If, I1, I2, Fn]\n\n#connections in the subsystem\nsub_connections = [\n    Connection(I2, I1, Fn[1], If[1]),\n    Connection(I1, Fn, If),\n    Connection(Fn, I2)\n    ]\n\n#the subsystem acts just like a normal block\nvdp = Subsystem(sub_blocks, sub_connections)\n

Parameters

blocks : list[Block] | None: internal blocks of the subsystem
connections : list[Connection] | None: internal connections of the subsystem

events : list[Event] | None\ntolerance_fpi : float

\nabsolute tolerance for convergence of algebraic loops\ndefault see ´SIM_TOLERANCE_FPI´ in ´_constants.py´

iterations_max : int: maximum allowed number of iterations for algebraic loop\nsolver, default see ´SIM_ITERATIONS_MAX´ in ´_constants.py´

Attributes

interface : Interface: internal interface block for data transfer to the outside
graph : Graph: internal graph representation for fast system funcion\nevluations using DAG with algebraic depths
boosters : None | list[ConnectionBooster]: list of boosters (fixed point accelerators) that wrap\nalgebraic loop closing connections assembled from the\nsystem graph

Transient simulation that accepts fastsim and pathsim blocks alike.

A drop-in replacement for the core Simulation that makes block\nprovenance irrelevant at the call site: every block in blocks is run\nthrough :func:`fastsim.port.port` before reaching the Rust engine. fastsim\nblocks pass through untouched; pathsim blocks are accelerated where possible\nand shimmed otherwise. Each porting decision is logged to the\nfastsim.port logger and surfaced on stdout when log is set, alongside\nthe run log.

All other behaviour, methods and attributes (run, reset,\nsteadystate, add_block, time, blocks, ...) are those of the\ncore simulation engine and are delegated transparently.

Note

fastsim Connection objects only accept fastsim blocks, so a connected\nblock must already be ported by the time the connection is built (the\nport-first convention). Auto-porting therefore covers blocks supplied\nun-ported in blocks; for connected toolbox blocks, port the class first\n(MyBlock = port(MyBlock)).

Example

A pathsim block instance and a fastsim block in the same system:

\nfrom fastsim import Simulation, Connection, port\nfrom fastsim.blocks import Scope\nfrom pathsim.blocks import Integrator      # a pathsim block\n\ninteg = port(Integrator())                 # port-first for wiring\nscope = Scope()\nsim = Simulation(\n    blocks=[integ, scope],\n    connections=[Connection(integ, scope)],\n    )\nsim.run(10)\n

Parameters

blocks : list[Block], optional: Blocks in the system. fastsim and pathsim blocks may be mixed; pathsim\nblocks are ported automatically.
connections : list[Connection], optional: Connections between block ports (built against fastsim / ported blocks).
Solver : Solver, optional: Numerical integrator class (default SSPRK22); forwarded to the core\nengine along with any further keyword arguments (dt, log,\ntolerance_lte_abs, ...).

\n", "source": null, "bases": [], "methods": [ { "name": "to_ir", "description": "Export the assembled model as hierarchical IR.", "docstring_html": "

Export the assembled model as hierarchical IR.

Returns a :class:`fastsim.ir.Module`: a typed, inspectable snapshot of\nthe model where each block is lowered to its scalar op-graph (for code\ngeneration / verification) or recorded as a typed extern call, with\nnested subsystems recursed.

Generate standalone C99 source from the assembled model.

Lowers the model straight to C in-process (no IR JSON round-trip):\nreturns a dict mapping each file name to its C source (model.h +\nmodel.c by default). See :meth:`fastsim.ir.Module.to_c` for the full\noption list (numeric, reductions, structure, layout,\nsolver, api). The code generator is built into\nthe fastsim extension under the codegen feature; if the wheel was\nbuilt without it, to_c raises AttributeError.

\n", "source": null, "signature": "(name = 'model', options = {})", "parameters": [ { "name": "name", "type": null, "default": "'model'", "description": "" }, { "name": "options", "type": null, "default": "{}", "description": "" } ], "returns": null, "method_type": "method" }, { "name": "run_streaming", "description": "Run the simulation as a generator, yielding at a fixed rate.", "docstring_html": "

Run the simulation as a generator, yielding at a fixed rate.

Drop-in for pathsim's run_streaming: a Python generator that\nadvances the engine and yields at a fixed WALL-CLOCK rate (tickrate\nyields per real second). Each yield is the return value of\nfunc_callback (or None), so a caller can extract intermediate\nresults, inject mutations, or stop between ticks. Unlike the core\nengine's blocking run_streaming (which runs to completion and\nreturns all frames at once), this cedes control between chunks, making\nit suitable for live UIs.

Parameters

duration : float: simulation time to advance (in time units)
reset : bool: reset the simulation before running (default False)
adaptive : bool: use adaptive timesteps if the solver is adaptive (default True)
tickrate : float: number of yields per time unit, i.e. duration * tickrate ticks\ntotal (default 10)
func_callback : callable, optional: called with no arguments at each tick; its return value is yielded

Yields

object: func_callback() if callable, else None; a final value is\nalways yielded once the run completes.

\n", "source": null, "signature": "(duration = 10.0, reset = False, adaptive = True, tickrate = 10.0, func_callback = None)", "parameters": [ { "name": "duration", "type": null, "default": "10.0", "description": "simulation time to advance (in time units)" }, { "name": "reset", "type": null, "default": "False", "description": "reset the simulation before running (default False)" }, { "name": "adaptive", "type": null, "default": "True", "description": "use adaptive timesteps if the solver is adaptive (default True)" }, { "name": "tickrate", "type": null, "default": "10.0", "description": "number of yields per time unit, i.e. ``duration * tickrate`` ticks total (default 10)" }, { "name": "func_callback", "type": null, "default": "None", "description": "called with no arguments at each tick; its return value is yielded" } ], "returns": null, "method_type": "method" }, { "name": "add_block", "description": "Add a block, or a list of blocks. Accepts either a single `Block`", "docstring_html": "

Add a block, or a list of blocks. Accepts either a single Block\nor any iterable of Block. If a run() is currently active\n(e.g. called from inside a Schedule.func_act callback), the\noperation is queued onto the simulation's pending-ops queue and\napplied at the next timestep boundary; otherwise it is applied\nsynchronously. The bulk path stays inside Rust — no per-block\nPython⇄Rust boundary crossing.

\n", "source": null, "signature": "(arg)", "parameters": [ { "name": "arg", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "add_connection", "description": "Add a connection, or a list of connections.", "docstring_html": "

Add a connection, or a list of connections.

\n", "source": null, "signature": "(arg)", "parameters": [ { "name": "arg", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "add_event", "description": "Add an event (or list of events) to the simulation.", "docstring_html": "

Add an event (or list of events) to the simulation.

\n", "source": null, "signature": "(event)", "parameters": [ { "name": "event", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "compile", "description": "Statically compile this model into a fused `dX/dt = F(X, t)` tape (see", "docstring_html": "

Statically compile this model into a fused dX/dt = F(X, t) tape (see\ncompile). Discrete and event-driven blocks are supported (memory joins a\nglobal M vector; block-internal zero-cross/schedule/condition events drive\nan event-aware run loop). Raises ValueError with a precise reason if the\nmodel is outside the static subset (opaque/extern block whose math lowers to\na call, algebraic loop, no continuous state, simulation-level events). Sinks\nbecome recorded taps; subsystems are flattened.

The compiled simulation inherits this simulation's solver, adaptive\ntolerances (tolerance_lte_abs/tolerance_lte_rel), timestep dt and\nlogging, so a compiled run integrates the same problem with the same\nmethod by default. Override any of these afterwards via set_solver /\ndt / log on the returned object.

\n", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "delinearize", "description": "Revert a previous linearization, restoring the original nonlinear blocks.", "docstring_html": "

Revert a previous linearization, restoring the original nonlinear blocks.

\n", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "enable_wct_trace", "description": "Enable per-timestep wall-clock recording. Subsequent `run` /", "docstring_html": "

Enable per-timestep wall-clock recording. Subsequent run /\ntimestep calls append elapsed seconds for each step into an\ninternal buffer. Negligible overhead (~30 ns/step) when enabled,\nzero overhead when off.

\n", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "linearize", "description": "Linearize the system about the current operating point (state and inputs), replacing nonlinear blocks with their local linear approximation.", "docstring_html": "

Linearize the system about the current operating point (state and inputs), replacing nonlinear blocks with their local linear approximation.

\n", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "pending_ops", "description": "Return a handle on the simulation's mutation queue. Equivalent", "docstring_html": "

Return a handle on the simulation's mutation queue. Equivalent\nto calling sim.add_block(...) etc. directly from a callback,\nkept for explicit-batching use cases.

\n", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "periodic_steady_state", "description": "Find the periodic steady-state limit cycle of period `period` by", "docstring_html": "

Find the periodic steady-state limit cycle of period period by\nmatrix-free Anderson-accelerated shooting on the period map\ng(x_0) = x(T; x_0).

One outer iteration:

Integrate the system over [0, T] with the inner ODE solver\n(a regular transient run(period, ...)).
Per dynamic block, run one matrix-free Anderson step on\n(x_start, x_end), mutating x_start toward the limit-cycle\nperiod-start state.
Check the max WRMS-scaled residual ‖x(T) − x(0)‖ across all\ndynamic blocks against the simulation's NLS_COEF threshold\n(same convergence semantics as every other implicit-stage /\nsteady-state residual).
If not converged: reset sim.time = 0 and event schedules,\nrepeat from step 1.

After convergence, one final transient run over [0, T] records\nthe converged limit-cycle trajectory in Scope blocks.

Anderson needs only function evaluations (one period integration\nper outer iteration) — no monodromy matrix Φ = ∂x(T)/∂x(0) to\nassemble or factorize. Converges in roughly 5–15 iterations on\nsmooth, mildly-coupled periodic systems. DAE blocks pass through\ntransparently — their engine_postprocess installs the\nappropriate StageBuilder on the PSS-augmented engine, exactly\nas with any other solver factory.

PSS pays off when the natural settling time is long relative to\nthe forcing period (high-Q resonators, weakly-damped loops, large\nLC filters). On strongly-damped systems where a plain transient\nsettles in a handful of periods, sim.run() is faster — the\nshooting iteration carries a fixed overhead (warm-up + final\nsample-run) that only amortizes when many periods would otherwise\nbe needed.

Parameters

period : float: Period length T (in simulation time units). Must be positive.
Solver : type, optional: Inner ODE solver class (e.g. RKDP54, ESDIRK43, GEAR52A).\nDefaults to the simulation's current solver.
tolerance_lte_abs : float, optional: Absolute WRMS weight for both the inner solver's LTE control\nand the outer shooting convergence test. Defaults to the\ncurrent solver's setting.
tolerance_lte_rel : float, optional: Relative WRMS weight, same dual role as above. Defaults to\nthe current solver's setting.
adaptive : bool, optional: Enable adaptive timestepping during the period integration.\nOnly honored when the inner solver is adaptive. Default True.
reset : bool, optional: If True, restore all blocks to their initial_value before\nshooting starts. If False, seed shooting from the current\nsimulation state — useful after a transient warm-up that\nproduces a good initial guess. Default False.

Returns

dict: Aggregate run statistics summed across all shooting iterations\nplus the final sample run: total_steps, successful_steps,\nrejected_steps, total_evals, total_solver_its, runtime_ms.

Notes

State-flipping events (relays, hysteresis, mode-switching) make\nx(T; x_0) non-smooth at the boundaries where the event\nactivation changes, which may stall Anderson convergence. If\nshooting fails to converge within SIM_PSS_ITERATIONS_MAX (50)\niterations, a warning is logged and the best-so-far state is\nretained.

\n", "source": null, "signature": "(period, Solver = None, tolerance_lte_abs = None, tolerance_lte_rel = None, adaptive = True, reset = False)", "parameters": [ { "name": "period", "type": null, "default": null, "description": "Period length `T` (in simulation time units). Must be positive." }, { "name": "Solver", "type": null, "default": "None", "description": "Inner ODE solver class (e.g. `RKDP54`, `ESDIRK43`, `GEAR52A`). Defaults to the simulation's current solver." }, { "name": "tolerance_lte_abs", "type": null, "default": "None", "description": "Absolute WRMS weight for both the inner solver's LTE control and the outer shooting convergence test. Defaults to the current solver's setting." }, { "name": "tolerance_lte_rel", "type": null, "default": "None", "description": "Relative WRMS weight, same dual role as above. Defaults to the current solver's setting." }, { "name": "adaptive", "type": null, "default": "True", "description": "Enable adaptive timestepping during the period integration. Only honored when the inner solver is adaptive. Default `True`." }, { "name": "reset", "type": null, "default": "False", "description": "If `True`, restore all blocks to their `initial_value` before shooting starts. If `False`, seed shooting from the current simulation state — useful after a transient warm-up that produces a good initial guess. Default `False`." } ], "returns": null, "method_type": "method" }, { "name": "plot", "description": "Plot the recorded results from all Scope blocks in the simulation.", "docstring_html": "

Plot the recorded results from all Scope blocks in the simulation.

\n", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "remove_block", "description": "Remove a block (or list of blocks) from the simulation.", "docstring_html": "

Remove a block (or list of blocks) from the simulation.

\n", "source": null, "signature": "(arg)", "parameters": [ { "name": "arg", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "remove_connection", "description": "Remove a connection (or list of connections) from the simulation.", "docstring_html": "

Remove a connection (or list of connections) from the simulation.

\n", "source": null, "signature": "(arg)", "parameters": [ { "name": "arg", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "remove_event", "description": "Remove an event (or list of events) from the simulation.", "docstring_html": "

Remove an event (or list of events) from the simulation.

\n", "source": null, "signature": "(event)", "parameters": [ { "name": "event", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "reset", "description": "Reset all blocks to their initial state and the simulation time to zero (or to ``time`` if given).", "docstring_html": "

Reset all blocks to their initial state and the simulation time to zero (or to time if given).

\n", "source": null, "signature": "(time = None)", "parameters": [ { "name": "time", "type": null, "default": "None", "description": "" } ], "returns": null, "method_type": "method" }, { "name": "run", "description": "Run the simulation for a given duration.", "docstring_html": "

Run the simulation for a given duration.

\n", "source": null, "signature": "(duration = 10.0, reset = False, adaptive = True)", "parameters": [ { "name": "duration", "type": null, "default": "10.0", "description": "" }, { "name": "reset", "type": null, "default": "False", "description": "" }, { "name": "adaptive", "type": null, "default": "True", "description": "" } ], "returns": null, "method_type": "method" }, { "name": "run_begin", "description": "Begin a chunked, cooperative run (for the streaming generator).", "docstring_html": "

Begin a chunked, cooperative run (for the streaming generator).\nDoes the one-time setup (optional reset + initial eval/sample); pair\nwith repeated run_until calls. Unlike run_streaming, this path is\nsim-time driven (no wall-clock), so it is WASM-safe and lets Python\nown the yield/step loop, injecting mutations between chunks.

\n", "source": null, "signature": "(reset = False, duration = 10.0)", "parameters": [ { "name": "reset", "type": null, "default": "False", "description": "" }, { "name": "duration", "type": null, "default": "10.0", "description": "" } ], "returns": null, "method_type": "method" }, { "name": "run_end", "description": "Finalize a chunked streaming run (logs FINISHED/INTERRUPTED). Call once", "docstring_html": "

Finalize a chunked streaming run (logs FINISHED/INTERRUPTED). Call once\nafter the last run_until.

\n", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "run_realtime", "description": "Run synchronized to wall-clock time with optional speed factor.", "docstring_html": "

Run synchronized to wall-clock time with optional speed factor.

\n", "source": null, "signature": "(duration = 10.0, reset = False, adaptive = True, tickrate = 30.0, speed = 1.0, func_callback = None)", "parameters": [ { "name": "duration", "type": null, "default": "10.0", "description": "" }, { "name": "reset", "type": null, "default": "False", "description": "" }, { "name": "adaptive", "type": null, "default": "True", "description": "" }, { "name": "tickrate", "type": null, "default": "30.0", "description": "" }, { "name": "speed", "type": null, "default": "1.0", "description": "" }, { "name": "func_callback", "type": null, "default": "None", "description": "" } ], "returns": null, "method_type": "method" }, { "name": "run_until", "description": "Advance up to `target_time` (a chunk boundary). `end_time` is the true", "docstring_html": "

Advance up to target_time (a chunk boundary). end_time is the true\nrun end (for adaptive overshoot prevention). Returns step counts.

\n", "source": null, "signature": "(target_time, end_time, adaptive = True)", "parameters": [ { "name": "target_time", "type": null, "default": null, "description": "" }, { "name": "end_time", "type": null, "default": null, "description": "" }, { "name": "adaptive", "type": null, "default": "True", "description": "" } ], "returns": null, "method_type": "method" }, { "name": "steadystate", "description": "Find the steady-state (DC operating point) of the system by root-finding on the residual rather than time integration.", "docstring_html": "

Find the steady-state (DC operating point) of the system by root-finding on the residual rather than time integration.

\n", "source": null, "signature": "(reset)", "parameters": [ { "name": "reset", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "stop", "description": "Signal a running simulation to stop cleanly at the next timestep boundary.", "docstring_html": "

Signal a running simulation to stop cleanly at the next timestep boundary.

\n", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "take_wct_trace", "description": "Drain the per-timestep wall-clock buffer and return the recorded", "docstring_html": "

Drain the per-timestep wall-clock buffer and return the recorded\ntimes in seconds. Leaves recording enabled with an empty buffer.\nReturns an empty list if tracing was never enabled.

\n", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "to_fmu", "description": "Export this model as a source FMU (FMI 3.0, Model Exchange) written to", "docstring_html": "

Export this model as a source FMU (FMI 3.0, Model Exchange) written to\npath (conventionally *.fmu).

Builds the IR straight from the live model (the same module_from_sim\npath as compile/to_c), lowers it through the struct-API C backend,\nwraps it in the FMI Model-Exchange C layer, and zips the C sources with a\ngenerated modelDescription.xml. The result is a source FMU: it ships\nthe C plus a buildDescription.xml so an importer compiles it on its own\nplatform.

Phase-1 scope: closed (input-free) continuous models with state and no\nevents. Raises ValueError for a model outside that subset (no\ncontinuous state, events, or an opaque block the backend cannot lower).\nThe optional start_time / stop_time / tolerance / step_size\npopulate <DefaultExperiment>; instantiation_token overrides the\ndefault {fastsim-<id>}.

\n", "source": null, "signature": "(path, name = 'model', start_time = None, stop_time = None, tolerance = None, step_size = None, instantiation_token = None)", "parameters": [ { "name": "path", "type": null, "default": null, "description": "" }, { "name": "name", "type": null, "default": "'model'", "description": "" }, { "name": "start_time", "type": null, "default": "None", "description": "" }, { "name": "stop_time", "type": null, "default": "None", "description": "" }, { "name": "tolerance", "type": null, "default": "None", "description": "" }, { "name": "step_size", "type": null, "default": "None", "description": "" }, { "name": "instantiation_token", "type": null, "default": "None", "description": "" } ], "returns": null, "method_type": "method" }, { "name": "to_ir_json", "description": "Export the assembled model as hierarchical IR (JSON). Each block is", "docstring_html": "

Export the assembled model as hierarchical IR (JSON). Each block is\neither lowered to its op-graph (for codegen / verification) or recorded\nas a typed extern call; nested subsystems recurse. See src/ir.

\n", "source": null, "signature": "(name = 'model')", "parameters": [ { "name": "name", "type": null, "default": "'model'", "description": "" } ], "returns": null, "method_type": "method" } ], "attributes": [], "parameters": [ { "name": "blocks", "type": null, "default": "None", "description": "Blocks in the system. fastsim and pathsim blocks may be mixed; pathsim blocks are ported automatically." }, { "name": "connections", "type": null, "default": "None", "description": "Connections between block ports (built against fastsim / ported blocks)." }, { "name": "events", "type": null, "default": "None", "description": "" }, { "name": "dt", "type": null, "default": "0.01", "description": "" }, { "name": "dt_min", "type": null, "default": "1e-16", "description": "" }, { "name": "dt_max", "type": null, "default": "None", "description": "" }, { "name": "Solver", "type": null, "default": "None", "description": "Numerical integrator class (default ``SSPRK22``); forwarded to the core engine along with any further keyword arguments (``dt``, ``log``, ``tolerance_lte_abs``, ...)." }, { "name": "tolerance_fpi", "type": null, "default": "1e-10", "description": "" }, { "name": "iterations_max", "type": null, "default": "200", "description": "" }, { "name": "log", "type": null, "default": "True", "description": "" }, { "name": "diagnostics", "type": null, "default": "False", "description": "" }, { "name": "solver_kwargs", "type": null, "default": "{}", "description": "" } ] }, { "name": "StopSimulation", "description": "Raised by a block or model to signal that the simulation should stop", "docstring_html": "

Raised by a block or model to signal that the simulation should stop\nimmediately. The run loop catches it and terminates cleanly, as if stop()\nhad been called. Drop-in compatible with pathsim.exceptions.StopSimulation.

\n", "source": null, "bases": [ "fastsim._fastsim.StopSimulation" ], "methods": [], "attributes": [], "parameters": [] } ], "functions": [ { "name": "adapt", "description": "Clone `cls` onto the fastsim engine.", "docstring_html": "

Clone cls onto the fastsim engine.

The clone keeps cls's name, module, qualname, attributes and custom\nmethods; only the pathsim bases in its MRO are substituted for their\nfastsim equivalents from the registry. Subclasses further up the chain are\nadapted recursively, so a hierarchy like\nProcess -> ResidenceTime -> DynamicalSystem is fully rebased.

Methods that carry an implicit __class__ cell (anything using bare\nsuper()) are copied with a fresh cell pointing at the new clone — so\nsuper() keeps finding the right MRO.

This is a clone, not in-place mutation: the original cls is untouched\nand isinstance(obj, cls) on an adapted instance returns False. Use\nthe returned class when constructing blocks for a fastsim Simulation.

Parameters

cls : type: Toolbox block class to adapt.
strict : bool, default True: Raise TypeError if any ancestor in the cloned chain overrides a\nmethod/property of the fastsim base. With strict=False the override\nis kept and a warning is emitted.

Returns

type: New class, rebased on fastsim.

See Also

port : Adapt and accelerate a pathsim block (class or instance),: JIT-tracing its right-hand side into the Rust core where possible.\nPrefer port for plain simulation speed-ups; use adapt when you need\nthe rebased class itself (e.g. to subclass it further or inspect its\nMRO).

Examples

Take a pathsim toolbox block class and run it on the fast Rust engine. The\nadapted class behaves exactly like the original — same constructor, same\nattributes — but its pathsim bases are swapped for their fastsim\nequivalents, so it plugs straight into a fastsim Simulation:

\nfrom fastsim import Simulation, Connection, adapt\nfrom fastsim.blocks import Scope\nfrom chem_toolbox import Reactor          # a pathsim-based block class\n\nFastReactor = adapt(Reactor)              # rebased onto the fastsim engine\nr = FastReactor(rate=2.0, volume=1.5)     # constructed like the original\nsco = Scope()\n\nsim = Simulation(\n    blocks=[r, sco],\n    connections=[Connection(r, sco)],\n)\nsim.run(10.0)\n

The original class is untouched, so both engines can be used side by side:

\nr_slow = Reactor(rate=2.0, volume=1.5)    # still the pathsim block\nisinstance(r, Reactor)                    # False — `adapt` returns a clone\n

A whole inheritance chain is rebased in one call. Given\nProcess -> ResidenceTime -> pathsim.blocks.DynamicalSystem, adapt\nwalks the MRO and substitutes the pathsim base, keeping Process's and\nResidenceTime's own methods intact.

\n", "source": null, "signature": "(cls: type, strict: bool = True, _memo: Optional[dict[type, type]] = None)", "parameters": [ { "name": "cls", "type": "type", "default": null, "description": "Toolbox block class to adapt." }, { "name": "strict", "type": "bool", "default": "True", "description": "Raise ``TypeError`` if any ancestor in the cloned chain overrides a method/property of the fastsim base. With ``strict=False`` the override is kept and a warning is emitted." }, { "name": "_memo", "type": "Optional[dict[type, type]]", "default": "None", "description": "" } ], "returns": "type" }, { "name": "random_uniform", "description": "Stateless uniform draw in ``[0, 1)``, keyed by ``key``.", "docstring_html": "

Stateless uniform draw in [0, 1), keyed by key.

key a JitTracer (inside a trace): records one SSA hash node.
key a Python/NumPy scalar: pure-Python hash (bit-identical to the trace).
key an ndarray: element-wise draws (eager fallback path).

\n", "source": null, "signature": "(key)", "parameters": [ { "name": "key", "type": null, "default": null, "description": "" } ], "returns": null }, { "name": "random_normal", "description": "Stateless standard-normal draw ``N(0, 1)``, keyed by ``key``.", "docstring_html": "

Stateless standard-normal draw N(0, 1), keyed by key.

Box-Muller over two decorrelated uniform draws. Polymorphic like\n:func:`random_uniform`; the traced and eager paths agree bit-for-bit.

\n", "source": null, "signature": "(key)", "parameters": [ { "name": "key", "type": null, "default": null, "description": "" } ], "returns": null } ] }, "fastsim.adapter": { "name": "fastsim.adapter", "description": "", "docstring_html": "", "classes": [], "functions": [ { "name": "adapt", "description": "Clone `cls` onto the fastsim engine.", "docstring_html": "

Clone cls onto the fastsim engine.

Methods that carry an implicit __class__ cell (anything using bare\nsuper()) are copied with a fresh cell pointing at the new clone — so\nsuper() keeps finding the right MRO.

Parameters

cls : type: Toolbox block class to adapt.
strict : bool, default True: Raise TypeError if any ancestor in the cloned chain overrides a\nmethod/property of the fastsim base. With strict=False the override\nis kept and a warning is emitted.

Returns

type: New class, rebased on fastsim.

See Also

port : Adapt and accelerate a pathsim block (class or instance),: JIT-tracing its right-hand side into the Rust core where possible.\nPrefer port for plain simulation speed-ups; use adapt when you need\nthe rebased class itself (e.g. to subclass it further or inspect its\nMRO).

Examples

\nfrom fastsim import Simulation, Connection, adapt\nfrom fastsim.blocks import Scope\nfrom chem_toolbox import Reactor          # a pathsim-based block class\n\nFastReactor = adapt(Reactor)              # rebased onto the fastsim engine\nr = FastReactor(rate=2.0, volume=1.5)     # constructed like the original\nsco = Scope()\n\nsim = Simulation(\n    blocks=[r, sco],\n    connections=[Connection(r, sco)],\n)\nsim.run(10.0)\n

The original class is untouched, so both engines can be used side by side:

\nr_slow = Reactor(rate=2.0, volume=1.5)    # still the pathsim block\nisinstance(r, Reactor)                    # False — `adapt` returns a clone\n

\n", "source": null, "signature": "(cls: type, strict: bool = True, _memo: Optional[dict[type, type]] = None)", "parameters": [ { "name": "cls", "type": "type", "default": null, "description": "Toolbox block class to adapt." }, { "name": "strict", "type": "bool", "default": "True", "description": "Raise ``TypeError`` if any ancestor in the cloned chain overrides a method/property of the fastsim base. With ``strict=False`` the override is kept and a warning is emitted." }, { "name": "_memo", "type": "Optional[dict[type, type]]", "default": "None", "description": "" } ], "returns": "type" } ] }, "fastsim.connection": { "name": "fastsim.connection", "description": "", "docstring_html": "", "classes": [ { "name": "Connection", "description": "Class to handle input-output relations of blocks by connecting them (directed graph)", "docstring_html": "

Class to handle input-output relations of blocks by connecting them (directed graph)\nand transfering data from the output port of the source block to the input port of\nthe target block.

The default ports for connection are (0) -> (0), since these are the default inputs\nthat are used in the SISO blocks.

Examples

Lets assume we have some generic blocks

\nfrom pathsim.blocks._block import Block\n\nB1 = Block()\nB2 = Block()\nB3 = Block()\n

that we want to connect. We initialize a 'Connection' with the blocks directly\nas the arguments if we want to connect the default ports (0) -> (0)

\nfrom pathsim import Connection\n\nC = Connection(B1, B2)\n

which is a connection from block 'B1' to 'B2'. If we want to explicitly declare\nthe input and output ports we can do that by utilizing the '__getitem__' method\nof the blocks

\nC = Connection(B1[0], B2[0])\n

which is exactly the default port setup. Connecting output port (1) of 'B1' to\nthe default input port (0) of 'B2' do

\nC = Connection(B1[1], B2[0])\n

or just

\nC = Connection(B1[1], B2).\n

The 'Connection' class also supports multiple targets for a single source.\nThis is specified by just adding more blocks with their respective ports into\nthe constructor like this:

\nC = Connection(B1, B2[0], B2[1], B3)\n

The port definitions follow the same structure as for single target connections.

'self'-connections also work without a problem. This is useful for modeling direct\nfeedback of a block to itself.

Port definitions support slicing. This enables direct MIMO connections. For example\nconnecting ports 0, 1, 2 of 'B1' to ports 1, 2, 3 of 'B2' works like this:

\nC = Connection(B1[0:2], B2[1:3])\n

Port definitions also support lists and tuples of 'int'. For example the slice\nabove is identical to this:

\nC = Connection(B1[0, 1], B2[1, 2])\n

Or to be more programmatic about it, like this:

\nprts_1 = [0, 1]\nprts_2 = [1, 2]\n\nC = Connection(B1[prts_1], B2[prts_2])\n

\nC = Connection(B1["out"], B2["in"])\n

Or mixed with integer port indices:

\nC = Connection(B1["out"], B2["in"])\n

Parameters

source : PortReference, Block: source block and optional source output port
targets : tuple[PortReference], tuple[Block]: target blocks and optional target input ports

Attributes

_active : bool: flag to set 'Connection' as active or inactive

\n", "source": null, "bases": [ "fastsim._fastsim.Connection" ], "methods": [], "attributes": [], "parameters": [] } ], "functions": [] }, "fastsim.exceptions": { "name": "fastsim.exceptions", "description": "", "docstring_html": "", "classes": [ { "name": "StopSimulation", "description": "Raised by a block or model to signal that the simulation should stop", "docstring_html": "

\n", "source": null, "bases": [ "fastsim._fastsim.StopSimulation" ], "methods": [], "attributes": [], "parameters": [] } ], "functions": [] }, "fastsim.ir": { "name": "fastsim.ir", "description": "", "docstring_html": "", "classes": [ { "name": "Tagged", "description": "A serde-tagged enum value: a ``kind`` plus its payload fields.", "docstring_html": "

A serde-tagged enum value: a kind plus its payload fields.

Unit variants (e.g. Op::Time) carry an empty fields; newtype variants\n(e.g. Op::Const(1.5)) expose the value under fields["value"]; struct\nvariants (e.g. Op::Binary{op,a,b}) expose their named fields directly.

\n", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, v: Any)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "v", "type": "Any", "default": null, "description": "" } ], "returns": "'Tagged'", "method_type": "classmethod" } ], "attributes": [ { "name": "kind", "description": "", "type": "str", "value": null }, { "name": "fields", "description": "", "type": "dict", "value": "field(default_factory=dict)" } ], "parameters": [ { "name": "kind", "type": "str", "default": null, "description": "" }, { "name": "fields", "type": "dict", "default": "dict()", "description": "" } ] }, { "name": "Port", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Port'", "method_type": "classmethod" } ], "attributes": [ { "name": "name", "description": "", "type": "str", "value": null }, { "name": "size", "description": "", "type": "int", "value": "1" } ], "parameters": [ { "name": "name", "type": "str", "default": null, "description": "" }, { "name": "size", "type": "int", "default": "1", "description": "" } ] }, { "name": "Ports", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Ports'", "method_type": "classmethod" } ], "attributes": [ { "name": "inputs", "description": "", "type": "list[Port]", "value": "field(default_factory=list)" }, { "name": "outputs", "description": "", "type": "list[Port]", "value": "field(default_factory=list)" } ], "parameters": [ { "name": "inputs", "type": "list[Port]", "default": "list()", "description": "" }, { "name": "outputs", "type": "list[Port]", "default": "list()", "description": "" } ] }, { "name": "Param", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Param'", "method_type": "classmethod" } ], "attributes": [ { "name": "id", "description": "", "type": "int", "value": null }, { "name": "name", "description": "", "type": "str", "value": null }, { "name": "value", "description": "", "type": "ParamValue", "value": null } ], "parameters": [ { "name": "id", "type": "int", "default": null, "description": "" }, { "name": "name", "type": "str", "default": null, "description": "" }, { "name": "value", "type": "ParamValue", "default": null, "description": "" } ] }, { "name": "StateVar", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'StateVar'", "method_type": "classmethod" } ], "attributes": [ { "name": "id", "description": "", "type": "int", "value": null }, { "name": "name", "description": "", "type": "str", "value": null }, { "name": "init", "description": "", "type": "float", "value": null } ], "parameters": [ { "name": "id", "type": "int", "default": null, "description": "" }, { "name": "name", "type": "str", "default": null, "description": "" }, { "name": "init", "type": "float", "default": null, "description": "" } ] }, { "name": "MemorySlot", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'MemorySlot'", "method_type": "classmethod" } ], "attributes": [ { "name": "id", "description": "", "type": "int", "value": null }, { "name": "name", "description": "", "type": "str", "value": null }, { "name": "size", "description": "", "type": "int", "value": null }, { "name": "init", "description": "", "type": "list[float]", "value": null } ], "parameters": [ { "name": "id", "type": "int", "default": null, "description": "" }, { "name": "name", "type": "str", "default": null, "description": "" }, { "name": "size", "type": "int", "default": null, "description": "" }, { "name": "init", "type": "list[float]", "default": null, "description": "" } ] }, { "name": "Region", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Region'", "method_type": "classmethod" } ], "attributes": [ { "name": "ops", "description": "", "type": "list[Op]", "value": "field(default_factory=list)" }, { "name": "writes", "description": "", "type": "list[Write]", "value": "field(default_factory=list)" }, { "name": "is_empty", "description": "", "type": "bool", "value": null } ], "parameters": [ { "name": "ops", "type": "list[Op]", "default": "list()", "description": "" }, { "name": "writes", "type": "list[Write]", "default": "list()", "description": "" } ] }, { "name": "Regions", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Regions'", "method_type": "classmethod" } ], "attributes": [ { "name": "alg", "description": "", "type": "Region", "value": "field(default_factory=Region)" }, { "name": "dyn", "description": "", "type": "Region", "value": "field(default_factory=Region)" } ], "parameters": [ { "name": "alg", "type": "Region", "default": "Region()", "description": "" }, { "name": "dyn", "type": "Region", "default": "Region()", "description": "" } ] }, { "name": "Event", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Event'", "method_type": "classmethod" } ], "attributes": [ { "name": "id", "description": "", "type": "int", "value": null }, { "name": "kind", "description": "", "type": "EventKind", "value": null }, { "name": "effect", "description": "", "type": "Region", "value": "field(default_factory=Region)" }, { "name": "opaque", "description": "True when the guard/action is host code (RNG, scope recording, callback)", "type": "bool", "value": "False" } ], "parameters": [ { "name": "id", "type": "int", "default": null, "description": "" }, { "name": "kind", "type": "EventKind", "default": null, "description": "" }, { "name": "effect", "type": "Region", "default": "Region()", "description": "" }, { "name": "opaque", "type": "bool", "default": "False", "description": "" } ] }, { "name": "Block", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Block'", "method_type": "classmethod" } ], "attributes": [ { "name": "id", "description": "", "type": "int", "value": null }, { "name": "name", "description": "", "type": "str", "value": null }, { "name": "type_name", "description": "", "type": "str", "value": null }, { "name": "role", "description": "", "type": "str", "value": null }, { "name": "ports", "description": "", "type": "Ports", "value": null }, { "name": "params", "description": "", "type": "list[Param]", "value": "field(default_factory=list)" }, { "name": "state", "description": "", "type": "list[StateVar]", "value": "field(default_factory=list)" }, { "name": "memory", "description": "", "type": "list[MemorySlot]", "value": "field(default_factory=list)" }, { "name": "regions", "description": "", "type": "Regions", "value": "field(default_factory=Regions)" }, { "name": "events", "description": "", "type": "list[Event]", "value": "field(default_factory=list)" }, { "name": "is_extern", "description": "True if the block is represented as an opaque extern call (its alg", "type": "bool", "value": null } ], "parameters": [ { "name": "id", "type": "int", "default": null, "description": "" }, { "name": "name", "type": "str", "default": null, "description": "" }, { "name": "type_name", "type": "str", "default": null, "description": "" }, { "name": "role", "type": "str", "default": null, "description": "" }, { "name": "ports", "type": "Ports", "default": null, "description": "" }, { "name": "params", "type": "list[Param]", "default": "list()", "description": "" }, { "name": "state", "type": "list[StateVar]", "default": "list()", "description": "" }, { "name": "memory", "type": "list[MemorySlot]", "default": "list()", "description": "" }, { "name": "regions", "type": "Regions", "default": "Regions()", "description": "" }, { "name": "events", "type": "list[Event]", "default": "list()", "description": "" } ] }, { "name": "PortRef", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'PortRef'", "method_type": "classmethod" } ], "attributes": [ { "name": "block", "description": "", "type": "int", "value": null }, { "name": "port", "description": "", "type": "int", "value": "0" }, { "name": "elems", "description": "", "type": "Optional[list[int]]", "value": "None" }, { "name": "INTERFACE", "description": "", "type": null, "value": "4294967295" }, { "name": "is_interface", "description": "", "type": "bool", "value": null } ], "parameters": [ { "name": "block", "type": "int", "default": null, "description": "" }, { "name": "port", "type": "int", "default": "0", "description": "" }, { "name": "elems", "type": "Optional[list[int]]", "default": "None", "description": "" } ] }, { "name": "Connection", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Connection'", "method_type": "classmethod" } ], "attributes": [ { "name": "id", "description": "", "type": "int", "value": null }, { "name": "src", "description": "", "type": "PortRef", "value": null }, { "name": "targets", "description": "", "type": "list[PortRef]", "value": null } ], "parameters": [ { "name": "id", "type": "int", "default": null, "description": "" }, { "name": "src", "type": "PortRef", "default": null, "description": "" }, { "name": "targets", "type": "list[PortRef]", "default": null, "description": "" } ] }, { "name": "Interface", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Interface'", "method_type": "classmethod" } ], "attributes": [ { "name": "inputs", "description": "", "type": "list[Port]", "value": "field(default_factory=list)" }, { "name": "outputs", "description": "", "type": "list[Port]", "value": "field(default_factory=list)" } ], "parameters": [ { "name": "inputs", "type": "list[Port]", "default": "list()", "description": "" }, { "name": "outputs", "type": "list[Port]", "default": "list()", "description": "" } ] }, { "name": "DagGroup", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'DagGroup'", "method_type": "classmethod" } ], "attributes": [ { "name": "depth", "description": "", "type": "int", "value": null }, { "name": "blocks", "description": "", "type": "list[int]", "value": null } ], "parameters": [ { "name": "depth", "type": "int", "default": null, "description": "" }, { "name": "blocks", "type": "list[int]", "default": null, "description": "" } ] }, { "name": "Scc", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Scc'", "method_type": "classmethod" } ], "attributes": [ { "name": "blocks", "description": "", "type": "list[int]", "value": null }, { "name": "back_edges", "description": "", "type": "list[int]", "value": null } ], "parameters": [ { "name": "blocks", "type": "list[int]", "default": null, "description": "" }, { "name": "back_edges", "type": "list[int]", "default": null, "description": "" } ] }, { "name": "Schedule", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Schedule'", "method_type": "classmethod" } ], "attributes": [ { "name": "topo", "description": "", "type": "list[int]", "value": "field(default_factory=list)" }, { "name": "groups", "description": "", "type": "list[DagGroup]", "value": "field(default_factory=list)" }, { "name": "sccs", "description": "", "type": "list[Scc]", "value": "field(default_factory=list)" }, { "name": "back_edges", "description": "", "type": "list[int]", "value": "field(default_factory=list)" } ], "parameters": [ { "name": "topo", "type": "list[int]", "default": "list()", "description": "" }, { "name": "groups", "type": "list[DagGroup]", "default": "list()", "description": "" }, { "name": "sccs", "type": "list[Scc]", "default": "list()", "description": "" }, { "name": "back_edges", "type": "list[int]", "default": "list()", "description": "" } ] }, { "name": "Subsystem", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Subsystem'", "method_type": "classmethod" }, { "name": "blocks", "description": "Iterate every leaf :class:`Block` in this scope, recursing into", "docstring_html": "

Iterate every leaf :class:`Block` in this scope, recursing into\nnested subsystems.

\n", "source": null, "signature": "()", "parameters": [], "returns": "Iterator[Block]", "method_type": "method" }, { "name": "subsystems", "description": "", "docstring_html": "", "source": null, "signature": "()", "parameters": [], "returns": "Iterator['Subsystem']", "method_type": "method" } ], "attributes": [ { "name": "id", "description": "", "type": "int", "value": null }, { "name": "name", "description": "", "type": "str", "value": null }, { "name": "interface", "description": "", "type": "Interface", "value": null }, { "name": "children", "description": "", "type": "list[Union[Block, 'Subsystem']]", "value": null }, { "name": "connections", "description": "", "type": "list[Connection]", "value": null }, { "name": "schedule", "description": "", "type": "Schedule", "value": null } ], "parameters": [ { "name": "id", "type": "int", "default": null, "description": "" }, { "name": "name", "type": "str", "default": null, "description": "" }, { "name": "interface", "type": "Interface", "default": null, "description": "" }, { "name": "children", "type": "list[Union[Block, 'Subsystem']]", "default": null, "description": "" }, { "name": "connections", "type": "list[Connection]", "default": null, "description": "" }, { "name": "schedule", "type": "Schedule", "default": null, "description": "" } ] }, { "name": "ExternDecl", "description": "", "docstring_html": "", "source": null, "bases": [], "methods": [ { "name": "parse", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'ExternDecl'", "method_type": "classmethod" } ], "attributes": [ { "name": "id", "description": "", "type": "int", "value": null }, { "name": "name", "description": "", "type": "str", "value": null }, { "name": "arity_in", "description": "", "type": "int", "value": null }, { "name": "arity_out", "description": "", "type": "int", "value": null } ], "parameters": [ { "name": "id", "type": "int", "default": null, "description": "" }, { "name": "name", "type": "str", "default": null, "description": "" }, { "name": "arity_in", "type": "int", "default": null, "description": "" }, { "name": "arity_out", "type": "int", "default": null, "description": "" } ] }, { "name": "Module", "description": "Top-level hierarchical IR of a model.", "docstring_html": "

Top-level hierarchical IR of a model.

\n", "source": null, "bases": [], "methods": [ { "name": "from_dict", "description": "", "docstring_html": "", "source": null, "signature": "(cls, d: dict)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "d", "type": "dict", "default": null, "description": "" } ], "returns": "'Module'", "method_type": "classmethod" }, { "name": "from_json", "description": "", "docstring_html": "", "source": null, "signature": "(cls, s: str)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "s", "type": "str", "default": null, "description": "" } ], "returns": "'Module'", "method_type": "classmethod" }, { "name": "from_json_file", "description": "", "docstring_html": "", "source": null, "signature": "(cls, path: str)", "parameters": [ { "name": "cls", "type": null, "default": null, "description": "" }, { "name": "path", "type": "str", "default": null, "description": "" } ], "returns": "'Module'", "method_type": "classmethod" }, { "name": "to_json", "description": "", "docstring_html": "", "source": null, "signature": "(indent: int = 2)", "parameters": [ { "name": "indent", "type": "int", "default": "2", "description": "" } ], "returns": "str", "method_type": "method" }, { "name": "to_json_file", "description": "", "docstring_html": "", "source": null, "signature": "(path: str, indent: int = 2)", "parameters": [ { "name": "path", "type": "str", "default": null, "description": "" }, { "name": "indent", "type": "int", "default": "2", "description": "" } ], "returns": "None", "method_type": "method" }, { "name": "to_c", "description": "Generate standalone C99 source from this IR.", "docstring_html": "

Generate standalone C99 source from this IR.

Lowers the model's scalar op-graph to C (the same path the verification\nsuite checks against :func:`fastsim.ir.eval`). Returns a dict mapping\neach file name to its source: layout="compact" (the default) gives\nmodel.h + model.c; layout="library" additionally splits out\nsolver.{c,h} (the integrator) and, under the hierarchical structure,\nblocks.{c,h} (the per-block functions). Compile the .c files\ntogether.

The code generator is built into the fastsim extension under the\ncodegen feature; raises :class:`ImportError` if the installed wheel\nwas built without it. (With a live :class:`~fastsim.Simulation`, prefer\nsim.to_c(...), which lowers in-process without this JSON round-trip.)

Parameters

numeric : str: scalar type: "double" (default), "float", "fixed" (reserved)
reductions : str: "unrolled" (default) or "vectorized" (Reduce/Dot as a counted loop)
structure : str: "hierarchical" (default; one function per block) or "flat"\n(one fused dx/dt)
layout : str: "compact" (default; .c + .h) or "library" (multi-file)
solver : str: integrator tableau by name (case-insensitive): "rk4" (default) and\n"euler" are fixed-step; "rkdp54"/"rkck54"/"rkf45"/\n"rkf78"/"rkv65"/"rkbs32"/"rkf21"/"rkdp87" are\nadaptive (embedded-error step control); "ssprk22"/"ssprk33"/\n"ssprk34" are fixed-step. Implicit (DIRK/ESDIRK) not yet emitted.
api : str: "struct" (the only API): a single model_t holding state /\nsignals / parameters / memory, with get_signal / set_signal\naccessors. Reentrant and embeddable (inputs set via set_signal).

Returns

dict[str, str]: file name -> C source

Raises

ValueError: an unknown option value, or malformed IR
RuntimeError: the model uses a construct the backend cannot lower (e.g. an opaque\nextern block, or an unsupported option combination)

\n", "source": null, "signature": "(numeric: str = 'double', reductions: str = 'unrolled', structure: str = 'hierarchical', layout: str = 'compact', solver: str = 'rk4', api: str = 'struct')", "parameters": [ { "name": "numeric", "type": "str", "default": "'double'", "description": "scalar type: ``\"double\"`` (default), ``\"float\"``, ``\"fixed\"`` (reserved)" }, { "name": "reductions", "type": "str", "default": "'unrolled'", "description": "``\"unrolled\"`` (default) or ``\"vectorized\"`` (Reduce/Dot as a counted loop)" }, { "name": "structure", "type": "str", "default": "'hierarchical'", "description": "``\"hierarchical\"`` (default; one function per block) or ``\"flat\"`` (one fused ``dx/dt``)" }, { "name": "layout", "type": "str", "default": "'compact'", "description": "``\"compact\"`` (default; ``.c`` + ``.h``) or ``\"library\"`` (multi-file)" }, { "name": "solver", "type": "str", "default": "'rk4'", "description": "integrator tableau by name (case-insensitive): ``\"rk4\"`` (default) and ``\"euler\"`` are fixed-step; ``\"rkdp54\"``/``\"rkck54\"``/``\"rkf45\"``/ ``\"rkf78\"``/``\"rkv65\"``/``\"rkbs32\"``/``\"rkf21\"``/``\"rkdp87\"`` are adaptive (embedded-error step control); ``\"ssprk22\"``/``\"ssprk33\"``/ ``\"ssprk34\"`` are fixed-step. Implicit (DIRK/ESDIRK) not yet emitted." }, { "name": "api", "type": "str", "default": "'struct'", "description": "``\"struct\"`` (the only API): a single ``model_t`` holding state / signals / parameters / memory, with ``get_signal`` / ``set_signal`` accessors. Reentrant and embeddable (inputs set via ``set_signal``)." } ], "returns": "dict[str, str]", "method_type": "method" }, { "name": "blocks", "description": "Every leaf block in the whole model (recurses subsystems).", "docstring_html": "

Every leaf block in the whole model (recurses subsystems).

\n", "source": null, "signature": "()", "parameters": [], "returns": "Iterator[Block]", "method_type": "method" }, { "name": "find", "description": "", "docstring_html": "", "source": null, "signature": "(type_name: str)", "parameters": [ { "name": "type_name", "type": "str", "default": null, "description": "" } ], "returns": "list[Block]", "method_type": "method" }, { "name": "extern_blocks", "description": "", "docstring_html": "", "source": null, "signature": "()", "parameters": [], "returns": "list[Block]", "method_type": "method" }, { "name": "summary", "description": "", "docstring_html": "", "source": null, "signature": "()", "parameters": [], "returns": "str", "method_type": "method" } ], "attributes": [ { "name": "name", "description": "", "type": "str", "value": null }, { "name": "root", "description": "", "type": "Subsystem", "value": null }, { "name": "ir_version", "description": "", "type": "int", "value": "1" }, { "name": "description", "description": "", "type": "str", "value": "''" }, { "name": "events", "description": "Simulation-level (global) events not attached to any block. Always", "type": "list[Event]", "value": "field(default_factory=list)" }, { "name": "extern_decls", "description": "", "type": "list[ExternDecl]", "value": "field(default_factory=list)" }, { "name": "_raw_json", "description": "", "type": "Optional[str]", "value": "field(default=None, repr=False, compare=False)" } ], "parameters": [ { "name": "name", "type": "str", "default": null, "description": "" }, { "name": "root", "type": "Subsystem", "default": null, "description": "" }, { "name": "ir_version", "type": "int", "default": "1", "description": "" }, { "name": "description", "type": "str", "default": "''", "description": "" }, { "name": "events", "type": "list[Event]", "default": "list()", "description": "" }, { "name": "extern_decls", "type": "list[ExternDecl]", "default": "list()", "description": "" }, { "name": "_raw_json", "type": "Optional[str]", "default": "None", "description": "" } ] } ], "functions": [] }, "fastsim.port": { "name": "fastsim.port", "description": "", "docstring_html": "", "classes": [ { "name": "CaptureShim", "description": "Stand-in for a pathsim ``Solver`` that captures the RHS, never integrates.", "docstring_html": "

Stand-in for a pathsim Solver that captures the RHS, never integrates.

Installed on a wrapped pathsim block as block.engine for Tier-3 ports.\nThe block's own step / solve call engine.step(f, dt) /\nengine.solve(f, J, dt) — we store f so the fastsim wrapper can\nforward it to the real engine. state is written by the wrapper before\neach evaluation so the wrapped block sees the current integrator state.

\n", "source": null, "bases": [], "methods": [ { "name": "get", "description": "", "docstring_html": "", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "set", "description": "", "docstring_html": "", "source": null, "signature": "(x)", "parameters": [ { "name": "x", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "step", "description": "", "docstring_html": "", "source": null, "signature": "(f, dt)", "parameters": [ { "name": "f", "type": null, "default": null, "description": "" }, { "name": "dt", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "solve", "description": "", "docstring_html": "", "source": null, "signature": "(f, J, dt)", "parameters": [ { "name": "f", "type": null, "default": null, "description": "" }, { "name": "J", "type": null, "default": null, "description": "" }, { "name": "dt", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "buffer", "description": "", "docstring_html": "", "source": null, "signature": "(dt)", "parameters": [ { "name": "dt", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "revert", "description": "", "docstring_html": "", "source": null, "signature": "()", "parameters": [], "returns": null, "method_type": "method" }, { "name": "reset", "description": "", "docstring_html": "", "source": null, "signature": "(initial_value = None)", "parameters": [ { "name": "initial_value", "type": null, "default": "None", "description": "" } ], "returns": null, "method_type": "method" } ], "attributes": [ { "name": "_x", "description": "", "type": null, "value": "np.atleast_1d(np.asarray(initial_value, dtype=float)).copy()" }, { "name": "_f", "description": "", "type": null, "value": "None" }, { "name": "state", "description": "", "type": null, "value": null } ], "parameters": [ { "name": "initial_value", "type": null, "default": null, "description": "" } ] } ], "functions": [ { "name": "port", "description": "Port a pathsim block onto the fastsim engine, accelerating where possible.", "docstring_html": "

Port a pathsim block onto the fastsim engine, accelerating where possible.

Accepts a pathsim block class or instance and returns a fastsim-native\nequivalent. The block is accelerated as far as it can be and falls back to a\nfaithful Python shim otherwise. fastsim blocks and classes pass through\nunchanged. Each decision is logged to the fastsim.port logger.

The strategy is chosen automatically:

passthrough -- the input is already a fastsim block (or block class).
accelerate -- the block exposes clean op_dyn / op_alg operators\nand overrides no engine hooks; its right-hand-side callables are extracted\nand JIT-traced into the Rust core, running at full native speed.
shim -- a block with custom step / solve or internal events keeps\nits own methods while fastsim's engine drives the integration through a\ncapture shim; internal events are translated to fastsim events.

Passing a class is the intended path for pathsim toolbox blocks: port the\nclass once, then construct instances and wire them with fastsim\nConnection objects as usual.

Example

Use a pathsim toolbox block class inside a fastsim simulation:

\nfrom fastsim import Simulation, Connection, port\nfrom chem_toolbox import Reactor          # a pathsim block class\n\nReactor = port(Reactor)                   # port once\nr = Reactor(rate=2.0)                     # instances are fastsim blocks\nsim = Simulation(\n    blocks=[r, scope],\n    connections=[Connection(r, scope)],   # wired like any fastsim block\n    )\n

Parameters

obj : type | pathsim.blocks.Block: A pathsim block class or instance, or an already-fastsim block (class).

Returns

type | fastsim.blocks.Block: A fastsim-native block class when obj is a class, otherwise a\nfastsim-native block instance. Build connections against the returned\nobject.

\n", "source": null, "signature": "(obj)", "parameters": [ { "name": "obj", "type": null, "default": null, "description": "A pathsim block class or instance, or an already-fastsim block (class)." } ], "returns": null } ] }, "fastsim.random": { "name": "fastsim.random", "description": "", "docstring_html": "", "classes": [], "functions": [ { "name": "random_uniform", "description": "Stateless uniform draw in ``[0, 1)``, keyed by ``key``.", "docstring_html": "

Stateless uniform draw in [0, 1), keyed by key.

key a JitTracer (inside a trace): records one SSA hash node.
key a Python/NumPy scalar: pure-Python hash (bit-identical to the trace).
key an ndarray: element-wise draws (eager fallback path).

Stateless standard-normal draw N(0, 1), keyed by key.

Box-Muller over two decorrelated uniform draws. Polymorphic like\n:func:`random_uniform`; the traced and eager paths agree bit-for-bit.

\n", "source": null, "signature": "(key)", "parameters": [ { "name": "key", "type": null, "default": null, "description": "" } ], "returns": null } ] }, "fastsim.simulation": { "name": "fastsim.simulation", "description": "", "docstring_html": "", "classes": [ { "name": "Simulation", "description": "Transient simulation that accepts fastsim *and* pathsim blocks alike.", "docstring_html": "

Transient simulation that accepts fastsim and pathsim blocks alike.

All other behaviour, methods and attributes (run, reset,\nsteadystate, add_block, time, blocks, ...) are those of the\ncore simulation engine and are delegated transparently.

Note

Example

A pathsim block instance and a fastsim block in the same system:

\nfrom fastsim import Simulation, Connection, port\nfrom fastsim.blocks import Scope\nfrom pathsim.blocks import Integrator      # a pathsim block\n\ninteg = port(Integrator())                 # port-first for wiring\nscope = Scope()\nsim = Simulation(\n    blocks=[integ, scope],\n    connections=[Connection(integ, scope)],\n    )\nsim.run(10)\n

Parameters

blocks : list[Block], optional: Blocks in the system. fastsim and pathsim blocks may be mixed; pathsim\nblocks are ported automatically.
connections : list[Connection], optional: Connections between block ports (built against fastsim / ported blocks).
Solver : Solver, optional: Numerical integrator class (default SSPRK22); forwarded to the core\nengine along with any further keyword arguments (dt, log,\ntolerance_lte_abs, ...).

\n", "source": null, "bases": [], "methods": [ { "name": "to_ir", "description": "Export the assembled model as hierarchical IR.", "docstring_html": "

Export the assembled model as hierarchical IR.

Generate standalone C99 source from the assembled model.

Run the simulation as a generator, yielding at a fixed rate.

Parameters

duration : float: simulation time to advance (in time units)
reset : bool: reset the simulation before running (default False)
adaptive : bool: use adaptive timesteps if the solver is adaptive (default True)
tickrate : float: number of yields per time unit, i.e. duration * tickrate ticks\ntotal (default 10)
func_callback : callable, optional: called with no arguments at each tick; its return value is yielded

Yields

object: func_callback() if callable, else None; a final value is\nalways yielded once the run completes.

Add a connection, or a list of connections.

\n", "source": null, "signature": "(arg)", "parameters": [ { "name": "arg", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "add_event", "description": "Add an event (or list of events) to the simulation.", "docstring_html": "

Add an event (or list of events) to the simulation.

Revert a previous linearization, restoring the original nonlinear blocks.

Linearize the system about the current operating point (state and inputs), replacing nonlinear blocks with their local linear approximation.

Return a handle on the simulation's mutation queue. Equivalent\nto calling sim.add_block(...) etc. directly from a callback,\nkept for explicit-batching use cases.

Find the periodic steady-state limit cycle of period period by\nmatrix-free Anderson-accelerated shooting on the period map\ng(x_0) = x(T; x_0).

One outer iteration:

Integrate the system over [0, T] with the inner ODE solver\n(a regular transient run(period, ...)).
Per dynamic block, run one matrix-free Anderson step on\n(x_start, x_end), mutating x_start toward the limit-cycle\nperiod-start state.
Check the max WRMS-scaled residual ‖x(T) − x(0)‖ across all\ndynamic blocks against the simulation's NLS_COEF threshold\n(same convergence semantics as every other implicit-stage /\nsteady-state residual).
If not converged: reset sim.time = 0 and event schedules,\nrepeat from step 1.

After convergence, one final transient run over [0, T] records\nthe converged limit-cycle trajectory in Scope blocks.

Parameters

period : float: Period length T (in simulation time units). Must be positive.
Solver : type, optional: Inner ODE solver class (e.g. RKDP54, ESDIRK43, GEAR52A).\nDefaults to the simulation's current solver.
tolerance_lte_abs : float, optional: Absolute WRMS weight for both the inner solver's LTE control\nand the outer shooting convergence test. Defaults to the\ncurrent solver's setting.
tolerance_lte_rel : float, optional: Relative WRMS weight, same dual role as above. Defaults to\nthe current solver's setting.
adaptive : bool, optional: Enable adaptive timestepping during the period integration.\nOnly honored when the inner solver is adaptive. Default True.
reset : bool, optional: If True, restore all blocks to their initial_value before\nshooting starts. If False, seed shooting from the current\nsimulation state — useful after a transient warm-up that\nproduces a good initial guess. Default False.

Returns

dict: Aggregate run statistics summed across all shooting iterations\nplus the final sample run: total_steps, successful_steps,\nrejected_steps, total_evals, total_solver_its, runtime_ms.

Notes

Plot the recorded results from all Scope blocks in the simulation.

Remove a block (or list of blocks) from the simulation.

\n", "source": null, "signature": "(arg)", "parameters": [ { "name": "arg", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "remove_connection", "description": "Remove a connection (or list of connections) from the simulation.", "docstring_html": "

Remove a connection (or list of connections) from the simulation.

\n", "source": null, "signature": "(arg)", "parameters": [ { "name": "arg", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "remove_event", "description": "Remove an event (or list of events) from the simulation.", "docstring_html": "

Remove an event (or list of events) from the simulation.

\n", "source": null, "signature": "(event)", "parameters": [ { "name": "event", "type": null, "default": null, "description": "" } ], "returns": null, "method_type": "method" }, { "name": "reset", "description": "Reset all blocks to their initial state and the simulation time to zero (or to ``time`` if given).", "docstring_html": "

Reset all blocks to their initial state and the simulation time to zero (or to time if given).

Run the simulation for a given duration.

Finalize a chunked streaming run (logs FINISHED/INTERRUPTED). Call once\nafter the last run_until.

Run synchronized to wall-clock time with optional speed factor.

Advance up to target_time (a chunk boundary). end_time is the true\nrun end (for adaptive overshoot prevention). Returns step counts.

Find the steady-state (DC operating point) of the system by root-finding on the residual rather than time integration.

Signal a running simulation to stop cleanly at the next timestep boundary.

Drain the per-timestep wall-clock buffer and return the recorded\ntimes in seconds. Leaves recording enabled with an empty buffer.\nReturns an empty list if tracing was never enabled.

Export this model as a source FMU (FMI 3.0, Model Exchange) written to\npath (conventionally *.fmu).

\n", "source": null, "signature": "(name = 'model')", "parameters": [ { "name": "name", "type": null, "default": "'model'", "description": "" } ], "returns": null, "method_type": "method" } ], "attributes": [], "parameters": [ { "name": "blocks", "type": null, "default": "None", "description": "Blocks in the system. fastsim and pathsim blocks may be mixed; pathsim blocks are ported automatically." }, { "name": "connections", "type": null, "default": "None", "description": "Connections between block ports (built against fastsim / ported blocks)." }, { "name": "events", "type": null, "default": "None", "description": "" }, { "name": "dt", "type": null, "default": "0.01", "description": "" }, { "name": "dt_min", "type": null, "default": "1e-16", "description": "" }, { "name": "dt_max", "type": null, "default": "None", "description": "" }, { "name": "Solver", "type": null, "default": "None", "description": "Numerical integrator class (default ``SSPRK22``); forwarded to the core engine along with any further keyword arguments (``dt``, ``log``, ``tolerance_lte_abs``, ...)." }, { "name": "tolerance_fpi", "type": null, "default": "1e-10", "description": "" }, { "name": "iterations_max", "type": null, "default": "200", "description": "" }, { "name": "log", "type": null, "default": "True", "description": "" }, { "name": "diagnostics", "type": null, "default": "False", "description": "" }, { "name": "solver_kwargs", "type": null, "default": "{}", "description": "" } ] } ], "functions": [] }, "fastsim.subsystem": { "name": "fastsim.subsystem", "description": "", "docstring_html": "", "classes": [ { "name": "Interface", "description": "Bare-bone block that serves as a data interface for the 'Subsystem' class.", "docstring_html": "

Bare-bone block that serves as a data interface for the 'Subsystem' class.

It works like this:

Internal blocks of the subsystem are connected to the inputs and outputs\nof this Interface block via the internal connections.
It behaves like a normal block (inherits the main 'Block' class methods).
It implements some special methods to get and set the inputs and outputs\nof the blocks, that are used to translate between the internal blocks of the\nsubsystem and the inputs and outputs of the subsystem.
Handles data transfer to and from the internal subsystem blocks\nto and from the inputs and outputs of the subsystem.

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Interface'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" } ], "parameters": [] }, { "name": "Subsystem", "description": "Subsystem class that holds its own blocks and connecions and", "docstring_html": "

Subsystem class that holds its own blocks and connecions and\ncan natively interface with the main simulation loop.

IO interface is realized by a special 'Interface' block, that has extra\nmethods for setting and getting inputs and outputs and serves\nas the interface of the internal blocks to the outside.

The subsystem doesnt use its 'inputs' and 'outputs' dicts directly.\nIt exclusively handles data transfer via the 'Interface' block.

Example

\nfrom pathsim import Subsystem, Interface, Connection\nfrom pathsim.blocks import Integrator, Function\n\n#van der Pol parameter\nmu = 1000\n\n#blocks in the subsystem\nIf = Interface() # this is the interface to the outside\nI1 = Integrator(2)\nI2 = Integrator(0)\nFn = Function(lambda x1, x2: mu*(1 - x1**2)*x2 - x1)\n\nsub_blocks = [If, I1, I2, Fn]\n\n#connections in the subsystem\nsub_connections = [\n    Connection(I2, I1, Fn[1], If[1]),\n    Connection(I1, Fn, If),\n    Connection(Fn, I2)\n    ]\n\n#the subsystem acts just like a normal block\nvdp = Subsystem(sub_blocks, sub_connections)\n

Parameters

blocks : list[Block] | None: internal blocks of the subsystem
connections : list[Connection] | None: internal connections of the subsystem

events : list[Event] | None\ntolerance_fpi : float

\nabsolute tolerance for convergence of algebraic loops\ndefault see ´SIM_TOLERANCE_FPI´ in ´_constants.py´

iterations_max : int: maximum allowed number of iterations for algebraic loop\nsolver, default see ´SIM_ITERATIONS_MAX´ in ´_constants.py´

Attributes

interface : Interface: internal interface block for data transfer to the outside
graph : Graph: internal graph representation for fast system funcion\nevluations using DAG with algebraic depths
boosters : None | list[ConnectionBooster]: list of boosters (fixed point accelerators) that wrap\nalgebraic loop closing connections assembled from the\nsystem graph

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Subsystem'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'blocks': None, 'connections': None, 'events': None, 'iterations_max': 200}" } ], "parameters": [ { "name": "blocks", "type": null, "default": "None", "description": "internal blocks of the subsystem" }, { "name": "connections", "type": null, "default": "None", "description": "internal connections of the subsystem" }, { "name": "events", "type": null, "default": "None", "description": "" }, { "name": "iterations_max", "type": null, "default": "200", "description": "maximum allowed number of iterations for algebraic loop solver, default see ´SIM_ITERATIONS_MAX´ in ´_constants.py´" }, { "name": "kwargs", "type": null, "default": "{}", "description": "" } ] } ], "functions": [] }, "fastsim.blocks": { "name": "fastsim.blocks", "description": "", "docstring_html": "", "classes": [ { "name": "Scope", "description": "", "docstring_html": "", "source": null, "bases": [ "fastsim._fastsim.Block" ], "methods": [ { "name": "plot", "description": "Plot recorded data with interactive legend picking.", "docstring_html": "

Plot recorded data with interactive legend picking.

\n", "source": null, "signature": "(args = (), kwargs = {})", "parameters": [ { "name": "args", "type": null, "default": "()", "description": "" }, { "name": "kwargs", "type": null, "default": "{}", "description": "" } ], "returns": null, "method_type": "method" } ], "attributes": [], "parameters": [ { "name": "labels", "type": null, "default": "None", "description": "" }, { "name": "sampling_period", "type": null, "default": "None", "description": "" }, { "name": "t_wait", "type": null, "default": "0.0", "description": "" } ] }, { "name": "Spectrum", "description": "", "docstring_html": "", "source": null, "bases": [ "fastsim._fastsim.Block" ], "methods": [ { "name": "plot", "description": "Plot frequency spectrum with interactive legend picking.", "docstring_html": "

Plot frequency spectrum with interactive legend picking.

\n", "source": null, "signature": "(args = (), kwargs = {})", "parameters": [ { "name": "args", "type": null, "default": "()", "description": "" }, { "name": "kwargs", "type": null, "default": "{}", "description": "" } ], "returns": null, "method_type": "method" } ], "attributes": [], "parameters": [ { "name": "freq", "type": null, "default": "None", "description": "" }, { "name": "t_wait", "type": null, "default": "0.0", "description": "" }, { "name": "alpha", "type": null, "default": "0.0", "description": "" }, { "name": "labels", "type": null, "default": "None", "description": "" } ] }, { "name": "ADC", "description": "Models an ideal Analog-to-Digital Converter (ADC).", "docstring_html": "

Models an ideal Analog-to-Digital Converter (ADC).

This block samples an analog input signal periodically, quantizes it\naccording to the specified number of bits and input span, and outputs\nthe resulting digital code on multiple output ports. The sampling\nis triggered by a scheduled event.

Functionality:

Samples the analog input inputs[0] at intervals of T, starting after delay tau.
Clips the input voltage to the defined span [min_voltage, max_voltage].
Scales the clipped voltage to the range [0, 1].
Quantizes the scaled value to an integer code between 0 and 2^n_bits - 1 using flooring.
Converts the integer code to an n_bits binary representation.
Outputs the binary code on ports 0 (LSB) to n_bits-1 (MSB).

Ideal characteristics:

Instantaneous sampling at scheduled times.
Perfect, noise-free quantization.
No aperture jitter or other dynamic errors.

Parameters

n_bits : int, optional: Number of bits for the digital output code. Default is 4.
span : list[float] or tuple[float], optional: The valid analog input value range [min_voltage, max_voltage].\nInputs outside this range will be clipped. Default is [-1, 1].
T : float, optional: Sampling period (time between samples). Default is 1 time unit.
tau : float, optional: Initial delay before the first sample is taken. Default is 0.

Attributes

events : list[Schedule]: Internal scheduled event responsible for periodic sampling and conversion.

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'ADC'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'n_bits': 4, 'span': None, 'T': 1.0, 'tau': 0.0}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "n_bits", "type": null, "default": "4", "description": "Number of bits for the digital output code. Default is 4." }, { "name": "span", "type": null, "default": "None", "description": "The valid analog input value range [min_voltage, max_voltage]. Inputs outside this range will be clipped. Default is [-1, 1]." }, { "name": "T", "type": null, "default": "1.0", "description": "Sampling period (time between samples). Default is 1 time unit." }, { "name": "tau", "type": null, "default": "0.0", "description": "Initial delay before the first sample is taken. Default is 0." } ] }, { "name": "Abs", "description": "Absolute value operator block.", "docstring_html": "

Absolute value operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\vert| \\vec{u} \\vert|\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Abs'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "Adder", "description": "Summs / adds up all input signals to a single output signal (MISO)", "docstring_html": "

Summs / adds up all input signals to a single output signal (MISO)

This is how it works in the default case

\ny(t) = \\sum_i u_i(t)\n

and like this when additional operations are defined

\ny(t) = \\sum_i \\mathrm{op}_i \\cdot u_i(t)\n

Example

This is the default initialization that just adds up all the inputs:

\nA = Adder()\n

and this is the initialization with specific operations that subtracts\nthe second from first input and neglects all others:

\nA = Adder('+-')\n

Note

This block is purely algebraic and its operation (op_alg) will be called\nmultiple times per timestep, each time when Simulation._update(t) is\ncalled in the global simulation loop.

Parameters

operations : str, optional: optional string of operations to be applied before\nsummation, i.e. '+-' will compute the difference,\n'None' will just perform regular sum

Attributes

_ops : dict: dict that maps string operations to numerical
_ops_array : array_like: operations converted to array
op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Adder'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'operations': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "operations", "type": null, "default": "None", "description": "optional string of operations to be applied before summation, i.e. '+-' will compute the difference, 'None' will just perform regular sum" } ] }, { "name": "Alias", "description": "Signal alias / pass-through block.", "docstring_html": "

Signal alias / pass-through block.

Passes the input directly to the output without modification.\nThis is useful for signal renaming in model composition.

\ny = x\n

This block supports vector inputs.

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Alias'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "AllpassFilter", "description": "Direct implementation of a first order allpass filter, or a cascade", "docstring_html": "

Direct implementation of a first order allpass filter, or a cascade\nof n 1st order allpass filters

\nH(s) = \\frac{s - 2\\pi f_s}{s + 2\\pi f_s}\n

where f_s is the frequency, where the 1st order allpass has a 90 deg phase shift.

Parameters

fs : float: frequency for 90 deg phase shift of 1st order allpass
n : int: number of cascades

Amplifies the input signal by multiplication with a constant gain term.

Like this:

\ny(t) = \\mathrm{gain} \\cdot u(t)\n

Note

This block is purely algebraic and its operation (op_alg) will be called\nmultiple times per timestep, each time when Simulation._update(t) is\ncalled in the global simulation loop.

Example

The block is initialized like this:

\n#amplification by factor 5\nA = Amplifier(gain=5)\n

Parameters

gain : float: amplifier gain

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Amplifier'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'gain': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "gain", "type": null, "default": "...", "description": "amplifier gain" } ] }, { "name": "AntiWindupPID", "description": "Proportional-Integral-Differentiation (PID) controller with anti-windup mechanism (back-calculation).", "docstring_html": "

Proportional-Integral-Differentiation (PID) controller with anti-windup mechanism (back-calculation).

Anti-windup mechanisms are needed when the magnitude of the control signal\nfrom the PID controller is limited by some real world saturation. In these cases,\nthe integrator will continue to accumulate the control error and "wind itself up".\nOnce the setpoint is reached, this can result in significant overshoots. This\nimplementation adds a conditional feedback term to the internal integrator that\n"unwinds" it when the PID output crosses some limits. This is pretty much a\ndeadzone feedback element for the integrator.

Mathematically, this block implements the following set of ODEs

\n\\begin{align}\n\\dot{x}_1 &= f_\\mathrm{max} (u - x_1) \\\\\n\\dot{x}_2 &= u - w\n\\end{align}\n

with the anti-windup feedback (depending on the pid output)

\nw = K_s (y - \\min(\\max(y, y_\\mathrm{min}), y_\\mathrm{max}))\n

and the output itself

\ny = K_p u + K_d f_\\mathrm{max} (u - x_1) + K_i x_2\n

Note

Depending on f_max, the resulting system might become stiff or ill conditioned!\nAs a practical choice set f_max to 3x the highest expected signal frequency.\nSince this block uses an approximation of real differentiation, the approximation will\nnot hold if there are high frequency components present in the signal. For example if\nyou have discontinuities such as steps or square waves.

Example

The block is initialized like this:

\n#cutoff at 1kHz, windup limits at [-5, 5]\npid = AntiWindupPID(Kp=2, Ki=0.5, Kd=0.1, f_max=1e3, limits=[-5, 5])\n

Parameters

Kp : float: proportional controller coefficient
Ki : float: integral controller coefficient
Kd : float: differentiator controller coefficient
f_max : float: highest expected signal frequency
Ks : float: feedback term for back calculation for anti-windup control of integrator
limits : array_like[float]: lower and upper limit for PID output that triggers anti-windup of integrator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'AntiWindupPID'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'Kp': 0.0, 'Ki': 0.0, 'Kd': 0.0, 'f_max': 100.0, 'Ks': 10.0, 'limits': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "Kp", "type": null, "default": "0.0", "description": "proportional controller coefficient" }, { "name": "Ki", "type": null, "default": "0.0", "description": "integral controller coefficient" }, { "name": "Kd", "type": null, "default": "0.0", "description": "differentiator controller coefficient" }, { "name": "f_max", "type": null, "default": "100.0", "description": "highest expected signal frequency" }, { "name": "Ks", "type": null, "default": "10.0", "description": "feedback term for back calculation for anti-windup control of integrator" }, { "name": "limits", "type": null, "default": "...", "description": "lower and upper limit for PID output that triggers anti-windup of integrator" } ] }, { "name": "Atan", "description": "Arctangent operator block.", "docstring_html": "

Arctangent operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\arctan(\\vec{u})\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Atan'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "Atan2", "description": "Two-argument arctangent block.", "docstring_html": "

Two-argument arctangent block.

Computes the four-quadrant arctangent of two inputs:

\ny = \\mathrm{atan2}(a, b)\n

Note

This block takes exactly two inputs (a, b) and produces one output.\nThe first input is the y-coordinate, the second is the x-coordinate,\nmatching the convention of numpy.arctan2(y, x).

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Atan2'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'a': 0, 'b': 1}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'y': 0}" } ], "parameters": [] }, { "name": "Backlash", "description": "Backlash (mechanical play) element.", "docstring_html": "

Backlash (mechanical play) element.

Models the hysteresis-like behavior of mechanical backlash in gears,\ncouplings and other systems with play. The output only tracks the input\nafter the input has moved through the full backlash width.

\n\\dot{x} = f_\\mathrm{max} \\left((u - x) - \\mathrm{clip}(u - x,\\; -w/2,\\; w/2)\\right)\n

where w is the total backlash width. Inside the dead zone |u - x| \\leq w/2\nthe output does not move. Once the input pushes past the edge, the output\ntracks with bandwidth f_max.

Example

The block is initialized like this:

\n#backlash with 0.5 units of total play\nbl = Backlash(width=0.5, f_max=1e3)\n

Parameters

width : float: total backlash width (play)
f_max : float: tracking bandwidth parameter when engaged

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Backlash'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'width': None, 'f_max': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "width", "type": null, "default": "...", "description": "total backlash width (play)" }, { "name": "f_max", "type": null, "default": "...", "description": "tracking bandwidth parameter when engaged" } ] }, { "name": "ButterworthBandpassFilter", "description": "Direct implementation of a bandpass butterworth filter block.", "docstring_html": "

Direct implementation of a bandpass butterworth filter block.

Follows the same structure as the 'StateSpace' block in the\n'pathsim.blocks' module. The numerator and denominator of the\nfilter transfer function are generated and then the transfer\nfunction is realized as a state space model.

Parameters

Fc : list[float]: corner frequencies (left, right) of the filter in [Hz]
n : int: filter order

Direct implementation of a bandstop butterworth filter block.

Parameters

Fc : tuple[float], list[float]: corner frequencies (left, right) of the filter in [Hz]
n : int: filter order

Direct implementation of a high pass butterworth filter block.

Parameters

Fc : float: corner frequency of the filter in [Hz]
n : int: filter order

Direct implementation of a low pass butterworth filter block.

Parameters

Fc : float: corner frequency of the filter in [Hz]
n : int: filter order

Chirp source, sinusoid with frequency ramp up and ramp down, plus phase noise.

This works by using a time dependent triangle wave for the frequency\nand integrating it with a numerical integration engine to get a\ncontinuous phase. This phase is then used to evaluate a sinusoid.

Additionally the chirp source can have white and cumulative phase noise.\nMathematically it looks like this for the contributions to the phase from\nthe triangular wave:

\n\\varphi_t(t) = \\int_0^t \\mathrm{tri}_{f_0, B, T}(\\tau) \\, d\\tau\n

And from the white (w) and cumulative (c) noise:

\n\\varphi_n(t) = \\sigma_w \\, n_w(t) + \\sigma_c \\int_0^t n_c(\\tau) \\, d\\tau\n

The phase contributions are then used to evaluate a sinusoid to get the final chirp signal:

\ny(t) = A \\sin(\\varphi_t(t) + \\varphi_n(t) + \\varphi_0)\n

Parameters

amplitude : float: amplitude of the chirp signal
f0 : float: start frequency of the chirp signal
BW : float: bandwidth of the frequency ramp of the chirp signal
T : float: period of the frequency ramp of the chirp signal
phase : float: phase of sinusoid (initial, radians)
sig_cum : float: weight for cumulative phase noise contribution
sig_white : float: weight for white phase noise contribution
sampling_period : float, None: time between phase noise samples. If None,\nnoise is sampled every timestep (default is 0.1)

Attributes

noise_1 : float: internal noise value for white phase noise
noise_2 : float: internal noise value for cumulative phase noise
events : list[Schedule]: scheduled event for periodic sampling (only if sampling_period is set)

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'ChirpPhaseNoiseSource'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'amplitude': 1.0, 'f0': 1.0, 'BW': 1.0, 'T': 1.0, 'phase': 0.0, 'sig_cum': 0.0, 'sig_white': 0.0, 'sampling_period': 0.1, 'seed': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "amplitude", "type": null, "default": "1.0", "description": "amplitude of the chirp signal" }, { "name": "f0", "type": null, "default": "1.0", "description": "start frequency of the chirp signal" }, { "name": "BW", "type": null, "default": "1.0", "description": "bandwidth of the frequency ramp of the chirp signal" }, { "name": "T", "type": null, "default": "1.0", "description": "period of the frequency ramp of the chirp signal" }, { "name": "phase", "type": null, "default": "0.0", "description": "phase of sinusoid (initial, radians)" }, { "name": "sig_cum", "type": null, "default": "0.0", "description": "weight for cumulative phase noise contribution" }, { "name": "sig_white", "type": null, "default": "0.0", "description": "weight for white phase noise contribution" }, { "name": "sampling_period", "type": null, "default": "0.1", "description": "time between phase noise samples. If None, noise is sampled every timestep (default is 0.1)" }, { "name": "seed", "type": null, "default": "None", "description": "" } ] }, { "name": "ChirpSource", "description": "Alias for ChirpPhaseNoiseSource.", "docstring_html": "

Alias for ChirpPhaseNoiseSource.

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'ChirpSource'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'amplitude': 1.0, 'f0': 1.0, 'BW': 1.0, 'T': 1.0, 'phase': 0.0, 'sig_cum': 0.0, 'sig_white': 0.0, 'sampling_period': 0.1, 'seed': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "amplitude", "type": null, "default": "1.0", "description": "" }, { "name": "f0", "type": null, "default": "1.0", "description": "" }, { "name": "BW", "type": null, "default": "1.0", "description": "" }, { "name": "T", "type": null, "default": "1.0", "description": "" }, { "name": "phase", "type": null, "default": "0.0", "description": "" }, { "name": "sig_cum", "type": null, "default": "0.0", "description": "" }, { "name": "sig_white", "type": null, "default": "0.0", "description": "" }, { "name": "sampling_period", "type": null, "default": "0.1", "description": "" }, { "name": "seed", "type": null, "default": "None", "description": "" } ] }, { "name": "Clip", "description": "Clipping/saturation operator block.", "docstring_html": "

Clipping/saturation operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\text{clip}(\\vec{u}, u_{min}, u_{max})\n

Parameters

min_val : float, array_like: minimum clipping value
max_val : float, array_like: maximum clipping value

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Clip'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'min_val': None, 'max_val': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "min_val", "type": null, "default": "...", "description": "minimum clipping value" }, { "name": "max_val", "type": null, "default": "...", "description": "maximum clipping value" } ] }, { "name": "Clock", "description": "Alias for ClockSource.", "docstring_html": "

Alias for ClockSource.

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Clock'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'T': 1.0, 'tau': 0.0}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "T", "type": null, "default": "1.0", "description": "" }, { "name": "tau", "type": null, "default": "0.0", "description": "" } ] }, { "name": "ClockSource", "description": "Discrete time clock source block.", "docstring_html": "

Discrete time clock source block.

Utilizes scheduled events to periodically set\nthe block output to 0 or 1 at discrete times.

Parameters

T : float: period of the clock
tau : float: clock delay

Attributes

events : list[Schedule]: internal scheduled event list

CoSimulationFMU block

Comparator block that sets output depending on predefined thresholds for the input.

Sets the output to '1' if the input signal crosses a predefined threshold and to '-1'\nif it crosses in the reverse direction.

This is realized by the block spawning a zero-crossing event detector that watches\nthe input of the block and locates the transition up to a tolerance.

The block output is determined by a simple sign check in\nthe 'update' method.

Parameters

threshold : float: threshold value for the comparator
tolerance : float: tolerance for zero crossing detection
span : list[float] or tuple[float], optional: output value range [min, max]

Attributes

events : list[ZeroCrossing]: internal zero crossing event

Produces a constant output signal (SISO).

\ny(t) = const.\n

Parameters

value : float: constant defining block output

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Constant'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'value': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "value", "type": null, "default": "...", "description": "constant defining block output" } ] }, { "name": "Cos", "description": "Cosine operator block.", "docstring_html": "

Cosine operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\cos(\\vec{u})\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Cos'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "Cosh", "description": "Hyperbolic cosine operator block.", "docstring_html": "

Hyperbolic cosine operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\cosh(\\vec{u})\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Cosh'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "Counter", "description": "Counts the number of detected bidirectional threshold crossings.", "docstring_html": "

Counts the number of detected bidirectional threshold crossings.

Uses zero-crossing events for the detection and sets the output\naccordingly.

Parameters

start : int: counter start (initial condition)
threshold : float: threshold for zero crossing

Attributes

E : ZeroCrossing: internal event manager
events : list[ZeroCrossing]: internal zero crossing event

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Counter'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'start': None, 'threshold': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "start", "type": null, "default": "...", "description": "counter start (initial condition)" }, { "name": "threshold", "type": null, "default": "...", "description": "threshold for zero crossing" } ] }, { "name": "CounterDown", "description": "Counts the number of detected unidirectional (hi->lo) threshold crossings.", "docstring_html": "

Counts the number of detected unidirectional (hi->lo) threshold crossings.

Note

This is a modification of 'Counter' which only counts\nunidirectional zero-crossings (high -> low)

Parameters

start : int: counter start (initial condition)
threshold : float: threshold for zero crossing

Attributes

E : ZeroCrossingDown: internal event manager
events : list[ZeroCrossing]: internal zero crossing event

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'CounterDown'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'start': None, 'threshold': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "start", "type": null, "default": "...", "description": "counter start (initial condition)" }, { "name": "threshold", "type": null, "default": "...", "description": "threshold for zero crossing" } ] }, { "name": "CounterUp", "description": "Counts the number of detected unidirectional (lo->hi) threshold crossings.", "docstring_html": "

Counts the number of detected unidirectional (lo->hi) threshold crossings.

Note

This is a modification of 'Counter' which only counts\nunidirectional zero-crossings (low -> high)

Parameters

start : int: counter start (initial condition)
threshold : float: threshold for zero crossing

Attributes

E : ZeroCrossingUp: internal event manager
events : list[ZeroCrossing]: internal zero crossing event

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'CounterUp'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'start': None, 'threshold': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "start", "type": null, "default": "...", "description": "counter start (initial condition)" }, { "name": "threshold", "type": null, "default": "...", "description": "threshold for zero crossing" } ] }, { "name": "DAC", "description": "Models an ideal Digital-to-Analog Converter (DAC).", "docstring_html": "

Models an ideal Digital-to-Analog Converter (DAC).

This block reads a digital input code periodically from its input ports,\nreconstructs the corresponding analog value based on the number of bits\nand output span, and holds the output constant between updates. The update\nis triggered by a scheduled event.

Functionality:

Reads the digital code from input ports 0 (LSB) to n_bits-1 (MSB) at intervals of T, starting after delay tau.
Interprets the inputs as an unsigned binary integer code.
Converts the integer code to a fractional value between 0 and (2^n_bits - 1) / 2^n_bits.
Scales this fractional value to the specified analog output span.
Outputs the resulting analog value on outputs[0].
Holds the output value constant until the next scheduled update.

Ideal characteristics:

Instantaneous update at scheduled times.
Perfect, noise-free reconstruction.
No glitches or settling time.

Parameters

n_bits : int, optional: Number of digital input bits expected. Default is 4.
span : list[float] or tuple[float], optional: The analog output value range [min_voltage, max_voltage] corresponding\nto the digital codes 0 and 2^n_bits - 1, respectively (approximately).\nDefault is [-1, 1].
T : float, optional: Update period (time between output updates). Default is 1 time unit.
tau : float, optional: Initial delay before the first output update. Default is 0.

Attributes

events : list[Schedule]: Internal scheduled event responsible for periodic updates.

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'DAC'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'n_bits': 4, 'span': None, 'T': 1.0, 'tau': 0.0}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "n_bits", "type": null, "default": "4", "description": "Number of digital input bits expected. Default is 4." }, { "name": "span", "type": null, "default": "None", "description": "The analog output value range [min_voltage, max_voltage] corresponding to the digital codes 0 and 2^n_bits - 1, respectively (approximately). Default is [-1, 1]." }, { "name": "T", "type": null, "default": "1.0", "description": "Update period (time between output updates). Default is 1 time unit." }, { "name": "tau", "type": null, "default": "0.0", "description": "Initial delay before the first output update. Default is 0." } ] }, { "name": "Deadband", "description": "Deadband (dead zone) element.", "docstring_html": "

Deadband (dead zone) element.

Outputs zero when the input is within the dead zone, and passes\nthe signal shifted by the zone boundary otherwise:

\ny = \\begin{cases}\n    u - u_\\mathrm{upper} & \\text{if } u > u_\\mathrm{upper} \\\\\n    0 & \\text{if } u_\\mathrm{lower} \\leq u \\leq u_\\mathrm{upper} \\\\\n    u - u_\\mathrm{lower} & \\text{if } u < u_\\mathrm{lower}\n\\end{cases}\n

or equivalently y = u - \\mathrm{clip}(u,\\; u_\\mathrm{lower},\\; u_\\mathrm{upper}).

Example

The block is initialized like this:

\n#symmetric dead zone of width 0.2\ndb = Deadband(lower=-0.1, upper=0.1)\n

Parameters

lower : float: lower bound of the dead zone
upper : float: upper bound of the dead zone

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Deadband'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'lower': None, 'upper': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "lower", "type": null, "default": "...", "description": "lower bound of the dead zone" }, { "name": "upper", "type": null, "default": "...", "description": "upper bound of the dead zone" } ] }, { "name": "Delay", "description": "Delays the input signal by a time constant 'tau' in seconds.", "docstring_html": "

Delays the input signal by a time constant 'tau' in seconds.

Supports two modes of operation:

Continuous mode (default, sampling_period=None):\nUses an adaptive interpolating buffer for continuous-time delay.

\ny(t) =\n\\begin{cases}\nx(t - \\tau) & , t \\geq \\tau \\\\\n0            & , t < \\tau\n\\end{cases}\n

Discrete mode (sampling_period provided):\nUses a ring buffer with scheduled sampling events for N-sample delay,\nwhere N = round(tau / sampling_period).

\ny[k] = x[k - N]\n

Note

In continuous mode, the internal adaptive buffer uses interpolation for\nthe evaluation. This is required to be compatible with variable step solvers.\nIt has a drawback however. The order of the ode solver used will degrade\nwhen this block is used, due to the interpolation.

Note

This block supports vector input, meaning we can have multiple parallel\ndelay paths through this block.

Example

Continuous-time delay:

\n#5 time units delay\nD = Delay(tau=5)\n

Discrete-time N-sample delay (10 samples):

\nD = Delay(tau=0.01, sampling_period=0.001)\n

Parameters

tau : float: delay time constant in seconds
sampling_period : float, None: sampling period for discrete mode, default is continuous mode

Attributes

_buffer : AdaptiveBuffer: internal interpolatable adaptive rolling buffer (continuous mode)
_ring : deque: internal ring buffer for N-sample delay (discrete mode)

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Delay'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'tau': 0.001, 'sampling_period': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "tau", "type": null, "default": "0.001", "description": "delay time constant in seconds" }, { "name": "sampling_period", "type": null, "default": "None", "description": "sampling period for discrete mode, default is continuous mode" } ] }, { "name": "Differentiator", "description": "Differentiates the input signal.", "docstring_html": "

Differentiates the input signal.

Uses a first order transfer function with a pole at the origin which implements\na high pass filter. Supports vector input.

\nH_\\mathrm{diff}(s) = \\frac{s}{1 + s / f_\\mathrm{max}}\n

The approximation holds for signals up to a frequency of approximately f_max.

Note

Depending on f_max, the resulting system might become stiff or ill conditioned!\nAs a practical choice set f_max to 3x the highest expected signal frequency.

Note

Since this is an approximation of real differentiation, the approximation will not hold\nif there are high frequency components present in the signal. For example if you have\ndiscontinuities such as steps or squere waves.

Example

The block is initialized like this:

\n#cutoff at 1kHz\nD = Differentiator(f_max=1e3)\n

Parameters

f_max : float: highest expected signal frequency

Attributes

op_dyn : DynamicOperator: internal dynamic operator for ODE component
op_alg : DynamicOperator: internal algebraic operator

Discrete-time backward-difference derivative.

\ny[k] = \\frac{u[k] - u[k-1]}{T}\n

Note

Supports vector input — each channel is differentiated independently.

Parameters

T : float: sampling period
tau : float: delay before first sample

Attributes

events : list[Schedule]: internal scheduled event for periodic update

Discrete-time integrator (forward Euler).

\ny[k+1] = y[k] + T \\, u[k]\n

The output at sample k is the accumulated sum of past inputs;\nthe current input u[k] only enters the next sample.

Note

Supports vector input — each channel is integrated independently.\nPass an array as initial_value to set per-channel initial values.

Parameters

T : float: sampling period
tau : float: delay before first sample
initial_value : float, array_like: initial integrator output y[0]

Attributes

events : list[Schedule]: internal scheduled event for periodic update

Discrete-time MIMO state space block.

\n\\begin{align}\n    x[k+1] &= \\mathbf{A}\\, x[k] + \\mathbf{B}\\, u[k] \\\\\n    y[k]   &= \\mathbf{C}\\, x[k] + \\mathbf{D}\\, u[k]\n\\end{align}\n

Note

The output port reflects y[k] for the duration of the current\nsample interval (zero-order hold between updates). The direct\nfeedthrough term D u[k] is computed at the sample event, so the\nblock has no algebraic passthrough between updates.

Parameters

A, B, C, D : array_like: discrete state space matrices
T : float: sampling period
tau : float: delay before first sample
initial_value : array_like, None: initial state x[0]

Attributes

events : list[Schedule]: internal scheduled event for periodic update

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'DiscreteStateSpace'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'A': None, 'B': None, 'C': None, 'D': None, 'T': 1.0, 'tau': 0.0, 'initial_value': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "A", "type": null, "default": "None", "description": "" }, { "name": "B", "type": null, "default": "None", "description": "" }, { "name": "C", "type": null, "default": "None", "description": "" }, { "name": "D", "type": null, "default": "None", "description": "discrete state space matrices" }, { "name": "T", "type": null, "default": "1.0", "description": "sampling period" }, { "name": "tau", "type": null, "default": "0.0", "description": "delay before first sample" }, { "name": "initial_value", "type": null, "default": "None", "description": "initial state ``x[0]``" } ] }, { "name": "DiscreteTransferFunction", "description": "Discrete-time SISO transfer function in numerator/denominator form.", "docstring_html": "

Discrete-time SISO transfer function in numerator/denominator form.

\nH(z) = \\frac{b_0 z^M + b_1 z^{M-1} + \\dots + b_M}{a_0 z^N + a_1 z^{N-1} + \\dots + a_N}\n

Realized internally as a DiscreteStateSpace via the controllable\ncanonical form returned by scipy.signal.tf2ss.

Parameters

Num : array_like: numerator polynomial coefficients (highest power of z first)
Den : array_like: denominator polynomial coefficients (highest power of z first)
T : float: sampling period
tau : float: delay before first sample

Multiplies and divides input signals (MISO).

This is the default behavior (multiply all):

\ny(t) = \\prod_i u_i(t)\n

and this is the behavior with an operations string:

\ny(t) = \\frac{\\prod_{i \\in M} u_i(t)}{\\prod_{j \\in D} u_j(t)}\n

where M is the set of inputs with * and D the set with /.

Example

Default initialization multiplies the first input and divides by the second:

\nD = Divider()\n

Multiply the first two inputs and divide by the third:

\nD = Divider('**/')\n

Raise an error instead of producing inf when a denominator input is zero:

\nD = Divider('**/', zero_div='raise')\n

Clamp the denominator to machine epsilon so the output stays finite:

\nD = Divider('**/', zero_div='clamp')\n

Note

This block is purely algebraic and its operation (op_alg) will be called\nmultiple times per timestep, each time when Simulation._update(t) is\ncalled in the global simulation loop.

Parameters

operations : str, optional

String of * and / characters indicating which inputs are\nmultiplied (*) or divided (/). Inputs beyond the length of\nthe string default to *. Defaults to '*/' (divide second\ninput by first).

zero_div : str, optional

Behaviour when a denominator input is zero. One of:

'warn' (default): Propagates inf and emits a RuntimeWarning — numpy's\nstandard behaviour.
'raise': Raises ZeroDivisionError.
'clamp': Clamps the denominator magnitude to machine epsilon\n(numpy.finfo(float).eps), preserving sign, so the output\nstays large-but-finite rather than inf.

Attributes

_ops : dict: Maps operation characters to exponent values (+1 or -1).
_ops_array : numpy.ndarray: Exponents (+1 for *, -1 for /) converted to an array.
op_alg : Operator: Internal algebraic operator.

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Divider'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'operations': '*/', 'zero_div': 'warn'}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "operations", "type": null, "default": "'*/'", "description": "String of ``*`` and ``/`` characters indicating which inputs are multiplied (``*``) or divided (``/``). Inputs beyond the length of the string default to ``*``. Defaults to ``'*/'`` (divide second input by first)." }, { "name": "zero_div", "type": null, "default": "'warn'", "description": "Behaviour when a denominator input is zero. One of:" } ] }, { "name": "DynamicalFunction", "description": "Arbitrary MIMO time and input dependent function block.", "docstring_html": "

Arbitrary MIMO time and input dependent function block.

The function signature needs two arguments f(u, t) where u is\nthe (possibly vectorial) block input and t is a time dependency.

\n\\vec{y} = \\mathrm{func}(\\vec{u}, t)\n

Note

This block does essentially the same as Function but with different\nrequirements for the signature of the function to be wrapped.\nBlock inputs are packed into an array u and this block additionally\naccepts time dependency in the function provided.\nThats where the prefix Dynamical.. comes from.

Example

Lets say we want to implement a super simple model for a voltage controlled\noscillator (VCO), where the block input controls the frequency of a sine wave\nat the output.

\nimport numpy as np\nfrom pathsim.blocks import DynamicalFunction\n\nf_0 = 100\n\ndef f_vco(u, t):\n    return np.sin(2*np.pi*f_0*u*t)\n\nvco = DynamicalFunction(f_vco)\n

Using it as a decorator also works:

\nimport numpy as np\nfrom pathsim.blocks import DynamicalFunction\n\nf_0 = 100\n\n@DynamicalFunction\ndef vco(u, t):\n    return np.sin(2*np.pi*f_0*u*t)\n\n#'vco' is now a PathSim block\n

Parameters

func : callable: function that defines algebraic block IO behaviour with time dependency,\nsignature func(u, t) where u is numpy.ndarray and t is float

Attributes

op_alg : DynamicOperator: internal operator that wraps func

This block implements a nonlinear dynamical system / nonlinear state space model.

Its basically the same as the ODE block with the addition of an output equation\nthat takes the state, input and time as arguments:

\n\\begin{align}\n    \\dot{x}(t) &= \\mathrm{func}_\\mathrm{dyn}(x(t), u(t), t) \\\\\n           y(t) &= \\mathrm{func}_\\mathrm{alg}(x(t), u(t), t)\n\\end{align}\n

Parameters

func_dyn : callable: right hand side function of ode-part of the system
func_alg : callable: output function of the system
initial_value : array[float]: initial state / initial condition
jac_dyn : callable | None: optional jacobian of func_dyn to improve convergence\nfor implicit ode solvers

Attributes

op_dyn : DynamicOperator: internal dynamic operator for func_dyn
op_alg : DynamicOperator: internal dynamic operator for func_alg

\n", "source": null, "bases": [ "fastsim.blocks._shim._JitShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'DynamicalSystem'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'func_dyn': None, 'func_alg': None, 'initial_value': None, 'has_passthrough': False, 'jac_dyn': None}" }, { "name": "_jit_fn", "description": "", "type": null, "value": "staticmethod(_jit_dynamical_system)" }, { "name": "_adapt_func", "description": "", "type": null, "value": "False" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "func_dyn", "type": null, "default": "None", "description": "right hand side function of ode-part of the system" }, { "name": "func_alg", "type": null, "default": "None", "description": "output function of the system" }, { "name": "initial_value", "type": null, "default": "None", "description": "initial state / initial condition" }, { "name": "has_passthrough", "type": null, "default": "False", "description": "" }, { "name": "jac_dyn", "type": null, "default": "None", "description": "optional jacobian of `func_dyn` to improve convergence for implicit ode solvers" } ] }, { "name": "Equal", "description": "Equality comparison block.", "docstring_html": "

Equality comparison block.

Compares two inputs and outputs 1.0 if |a - b| <= tolerance, else 0.0.

\ny =\n\\begin{cases}\n1 & , |a - b| \\leq \\epsilon \\\\\n0 & , |a - b| > \\epsilon\n\\end{cases}\n

Parameters

tolerance : float: comparison tolerance for floating point equality

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Equal'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'tolerance': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'a': 0, 'b': 1}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'y': 0}" } ], "parameters": [ { "name": "tolerance", "type": null, "default": "...", "description": "comparison tolerance for floating point equality" } ] }, { "name": "Exp", "description": "Exponential operator block.", "docstring_html": "

Exponential operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = e^{\\vec{u}}\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Exp'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "FIR", "description": "Discrete-time Finite-Impulse-Response (FIR) filter.", "docstring_html": "

Discrete-time Finite-Impulse-Response (FIR) filter.

Applies an FIR filter to a periodically sampled input signal.

\ny[n] = b_0 x[n] + b_1 x[n-1] + \\dots + b_N x[n-N]\n

where b are the filter coefficients and N is the filter order\n(number of coefficients minus one). The output is held constant\nbetween sample times.

Note

Supports vector input — the same coefficients are applied to each\nchannel in parallel.

Parameters

coeffs : array_like: FIR filter coefficients [b0, b1, ..., bN]
T : float: sampling period
tau : float: delay before first sample

Attributes

events : list[Schedule]: internal scheduled event for periodic filter evaluation

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'FIR'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'coeffs': None, 'T': 1.0, 'tau': 0.0}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "coeffs", "type": null, "default": "...", "description": "FIR filter coefficients ``[b0, b1, ..., bN]``" }, { "name": "T", "type": null, "default": "1.0", "description": "sampling period" }, { "name": "tau", "type": null, "default": "0.0", "description": "delay before first sample" } ] }, { "name": "FirstOrderHold", "description": "First-order hold reconstructor.", "docstring_html": "

First-order hold reconstructor.

Reconstructs a continuous signal from periodic samples using linear\nextrapolation across one sampling interval. Causal (one-sample-lag)\nvariant matching the Simulink First-Order Hold block.

Between two consecutive sample times t_{k-1} and t_k,\nthe output is

\ny(t) = u_{k-1} + \\frac{u_{k-1} - u_{k-2}}{T} (t - t_{k-1})\n

During the very first interval (only one sample captured) the output\nis held at the most recent sample.

Note

Supports vector input — each channel is extrapolated independently.

Parameters

T : float: sampling period
tau : float: delay before first sample

Attributes

events : list[Schedule]: internal scheduled event for periodic sampling

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'FirstOrderHold'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'T': None, 'tau': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "T", "type": null, "default": "...", "description": "sampling period" }, { "name": "tau", "type": null, "default": "...", "description": "delay before first sample" } ] }, { "name": "FullyImplicitDAE", "description": "Fully-implicit DAE block.", "docstring_html": "

Fully-implicit DAE block.

For systems that can't be cast into semi-explicit or mass-matrix form —\nimplicit constitutive relations, mixed differential/algebraic with\nnon-trivial coupling — the residual form

\nF(x, \\dot{x}, u, t) = 0, \\quad y = x\n

is solved directly. Only implicit solvers (ESDIRK/DIRK family) work; the\nblock installs a fully-implicit stage builder into the engine via the\npost-processing hook.

The JIT path traces func and derives both\n\\partial F / \\partial x and \\partial F / \\partial \\dot{x}\nvia auto-differentiation when no analytical Jacobians are supplied.\nIndex-1 systems (singular \\partial F / \\partial \\dot{x}):\nprefer DIRK over ESDIRK for stability.

Parameters

func : callable: residual F(x, xdot, u, t) -> ndarray
initial_value : array_like: consistent x_0. The caller is responsible for choosing it such\nthat there exists an \\dot{x}_0 with\nF(x_0, \\dot{x}_0, u_0, 0) \\approx 0.
jac_x : callable, optional: analytical \\partial F / \\partial x as a flat row-major\nn × n array. Falls back to numerical (central differences) if\nomitted.
jac_xdot : callable, optional: analytical \\partial F / \\partial \\dot{x} as a flat row-major\nn × n array. Falls back to numerical (central differences) if\nomitted.

\n", "source": null, "bases": [ "fastsim.blocks._shim._JitShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'FullyImplicitDAE'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'func': None, 'initial_value': None, 'jac_x': None, 'jac_xdot': None}" }, { "name": "_jit_fn", "description": "", "type": null, "value": "staticmethod(_jit_fully_implicit)" }, { "name": "_adapt_func", "description": "", "type": null, "value": "False" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "func", "type": null, "default": "None", "description": "residual ``F(x, xdot, u, t) -> ndarray``" }, { "name": "initial_value", "type": null, "default": "None", "description": "consistent :math:`x_0`. The caller is responsible for choosing it such that there exists an :math:`\\dot{x}_0` with :math:`F(x_0, \\dot{x}_0, u_0, 0) \\approx 0`." }, { "name": "jac_x", "type": null, "default": "None", "description": "analytical :math:`\\partial F / \\partial x` as a flat row-major ``n × n`` array. Falls back to numerical (central differences) if omitted." }, { "name": "jac_xdot", "type": null, "default": "None", "description": "analytical :math:`\\partial F / \\partial \\dot{x}` as a flat row-major ``n × n`` array. Falls back to numerical (central differences) if omitted." } ] }, { "name": "Function", "description": "Arbitrary MIMO function block, defined by a function or `lambda` expression.", "docstring_html": "

Arbitrary MIMO function block, defined by a function or lambda expression.

The function can have multiple arguments that are then provided\nby the input channels of the function block.

Form multi input, the function has to specify multiple arguments\nand for multi output, the aoutputs have to be provided as a\ntuple or list.

In the context of the global system, this block implements algebraic\ncomponents of the global system ODE/DAE.

\n\\vec{y} = \\mathrm{func}(\\vec{u})\n

Note

This block is purely algebraic and its operation (op_alg) will be called\nmultiple times per timestep, each time when Simulation._update(t) is\ncalled in the global simulation loop.\nTherefore func must be purely algebraic and not introduce states,\ndelay, etc. For interfacing with external stateful APIs, use the\nWrapper block.

Note

If the outputs are provided as a single numpy array, they are\nconsidered a single output. For MIMO, output has to be tuple.

Example

consider the function:

\nfrom pathsim.blocks import Function\n\ndef f(a, b, c):\n    return a**2, a*b, b/c\n\nfn = Function(f)\n

then, when the block is updated, the input channels of the block are\nassigned to the function arguments following this scheme:

\ninputs[0] -> a\ninputs[1] -> b\ninputs[2] -> c\n

and the function outputs are assigned to the\noutput channels of the block in the same way:

\na**2 -> outputs[0]\na*b  -> outputs[1]\nb/c  -> outputs[2]\n

Because the Function block only has a single argument, it can be\nused to decorate a function and make it a PathSim block. This might\nbe handy in some cases to keep definitions concise and localized\nin the code:

\nfrom pathsim.blocks import Function\n\n#does the same as the definition above\n\n@Function\ndef fn(a, b, c):\n    return a**2, a*b, b/c\n\n#'fn' is now a PathSim block\n

Parameters

func : callable: MIMO function that defines algebraic block IO behaviour, signature func(*tuple)

Attributes

op_alg : Operator: internal algebraic operator that wraps func

Source block that generates a gaussian pulse

Parameters

amplitude : float: amplitude of the gaussian pulse
f_max : float: maximum frequency component of the gaussian pulse (steepness)
tau : float: time delay of the gaussian pulse

Greater-than comparison block.

Compares two inputs and outputs 1.0 if a > b, else 0.0.

\ny =\n\\begin{cases}\n1 & , a > b \\\\\n0 & , a \\leq b\n\\end{cases}\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'GreaterThan'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'a': 0, 'b': 1}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'y': 0}" } ], "parameters": [] }, { "name": "Integrator", "description": "Integrates the input signal.", "docstring_html": "

Integrates the input signal.

Uses a numerical integration engine like this:

\ny(t) = \\int_0^t u(\\tau) \\ d \\tau\n

or in differential form like this:

\n\\begin{align}\n    \\dot{x}(t) &= u(t) \\\\\n           y(t) &= x(t)\n\\end{align}\n

The Integrator block is inherently MIMO capable, so u\nand y can be vectors.

Example

This is how to initialize the integrator:

\n#initial value 0.0\ni1 = Integrator()\n\n#initial value 2.5\ni2 = Integrator(2.5)\n

Parameters

initial_value : float, array: initial value of integrator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Integrator'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'initial_value': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "initial_value", "type": null, "default": "None", "description": "initial value of integrator" } ] }, { "name": "LUT1D", "description": "One-dimensional lookup table with linear interpolation functionality.", "docstring_html": "

One-dimensional lookup table with linear interpolation functionality.

This class implements a 1-dimensional lookup table that uses scipy's interp1d [1]\nfor piecewise linear interpolation along a single axis. The interpolation\nprovides linear interpolation between adjacent data points and supports\nextrapolation beyond the input data range using the 'extrapolate' fill mode.

The LUT1D acts as a Function block.

References

\n\n\n\n\n\n

[1]	https://docs.scipy.org/doc/scipy-1.16.1/reference/generated/scipy.interpolate.interp1d.html

Parameters

points : array_like of shape (n,): 1-D array of monotonically increasing data point coordinates where n\nis the number of points. These represent the independent variable values\nat which the dependent values are known.
values : array_like of shape (n,) or (n, m): 1-D or 2-D array of data values at the corresponding points. If 1-D,\nrepresents scalar values at each point. If 2-D with shape (n, m),\neach column represents a different output dimension, allowing the\nlookup table to return m-dimensional vectors.
fill_value : float or str, optional: The value to use for points outside the interpolation range. If "extrapolate",\nthe interpolator will use linear extrapolation. Default is "extrapolate".\nSee https://docs.scipy.org/doc/scipy-1.16.1/reference/generated/scipy.interpolate.interp1d.html for more details

Attributes

points : ndarray: Flattened array of input point coordinates, stored as 1-D array.
values : ndarray: Stored array of output values at each point, preserving original shape.
inter : scipy.interpolate.interp1d: The scipy 1D interpolator object used for linear interpolation with\nextrapolation enabled beyond the data range.

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'LUT1D'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'points': None, 'values': None, 'fill_value': 'extrapolate'}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "points", "type": null, "default": "...", "description": "1-D array of monotonically increasing data point coordinates where n is the number of points. These represent the independent variable values at which the dependent values are known." }, { "name": "values", "type": null, "default": "...", "description": "1-D or 2-D array of data values at the corresponding points. If 1-D, represents scalar values at each point. If 2-D with shape (n, m), each column represents a different output dimension, allowing the lookup table to return m-dimensional vectors." }, { "name": "fill_value", "type": null, "default": "'extrapolate'", "description": "The value to use for points outside the interpolation range. If \"extrapolate\", the interpolator will use linear extrapolation. Default is \"extrapolate\". See https://docs.scipy.org/doc/scipy-1.16.1/reference/generated/scipy.interpolate.interp1d.html for more details" } ] }, { "name": "LeadLag", "description": "Lead-Lag compensator.", "docstring_html": "

Lead-Lag compensator.

The transfer function is defined as

\nH(s) = K \\frac{T_1 s + 1}{T_2 s + 1}\n

where K is the static gain, T1 is the lead time constant\nand T2 is the lag time constant.

T_1 > T_2: lead compensator (phase advance)
T_1 < T_2: lag compensator (phase lag)
T_1 = T_2: pure gain

Example

The block is initialized like this:

\n#lead compensator\nll = LeadLag(K=1.0, T1=0.5, T2=0.1)\n

Parameters

K : float: static gain
T1 : float: lead (numerator) time constant in seconds
T2 : float: lag (denominator) time constant in seconds (must be > 0)

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'LeadLag'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'K': None, 'T1': None, 'T2': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "K", "type": null, "default": "...", "description": "static gain" }, { "name": "T1", "type": null, "default": "...", "description": "lead (numerator) time constant in seconds" }, { "name": "T2", "type": null, "default": "...", "description": "lag (denominator) time constant in seconds (must be > 0)" } ] }, { "name": "LessThan", "description": "Less-than comparison block.", "docstring_html": "

Less-than comparison block.

Compares two inputs and outputs 1.0 if a < b, else 0.0.

\ny =\n\\begin{cases}\n1 & , a < b \\\\\n0 & , a \\geq b\n\\end{cases}\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'LessThan'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'a': 0, 'b': 1}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'y': 0}" } ], "parameters": [] }, { "name": "Log", "description": "Natural logarithm operator block.", "docstring_html": "

Natural logarithm operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\ln(\\vec{u})\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Log'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "Log10", "description": "Base-10 logarithm operator block.", "docstring_html": "

Base-10 logarithm operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\log_{10}(\\vec{u})\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Log10'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "LogicAnd", "description": "Logical AND block.", "docstring_html": "

Logical AND block.

Outputs 1.0 if both inputs are nonzero, else 0.0.

\ny = a \\land b\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'LogicAnd'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'a': 0, 'b': 1}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'y': 0}" } ], "parameters": [] }, { "name": "LogicNot", "description": "Logical NOT block.", "docstring_html": "

Logical NOT block.

Outputs 1.0 if input is zero, else 0.0.

\ny = \\lnot x\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'LogicNot'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "LogicOr", "description": "Logical OR block.", "docstring_html": "

Logical OR block.

Outputs 1.0 if either input is nonzero, else 0.0.

\ny = a \\lor b\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'LogicOr'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'a': 0, 'b': 1}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'y': 0}" } ], "parameters": [] }, { "name": "MassMatrixDAE", "description": "Mass-matrix DAE block.", "docstring_html": "

Mass-matrix DAE block.

Solves an implicit ODE with a (possibly singular) constant mass matrix:

\n\\mathbf{M} \\, \\dot{x} = f(x, u, t), \\quad y = x\n

f has the same signature as in :class:`ODE` — only the way the solver\nintegrates it differs. The mass matrix M is stored on the block and\ninstalled into the solver's stage builder when an implicit solver is\nattached. Explicit solvers see a pure ODE and will silently produce wrong\nresults for singular M — use one of the ESDIRK/DIRK/EUB families for any\nnon-trivial mass.

The JIT path traces func and derives \\partial f / \\partial x\nanalytically via auto-differentiation when no analytical Jacobian is\nsupplied.

Parameters

func : callable: right-hand side f(x, u, t) -> ndarray
mass : Mass: mass matrix descriptor (dense, banded or sparse)
initial_value : array_like: initial state, must have the same length as mass.n
jac : callable, optional: analytical \\partial f / \\partial x as a flat row-major\nn × n array. If omitted, numerical or AD-derived Jacobians are\nused downstream.

\n", "source": null, "bases": [ "fastsim.blocks._shim._JitShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'MassMatrixDAE'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'func': None, 'mass': None, 'initial_value': None, 'jac': None}" }, { "name": "_jit_fn", "description": "", "type": null, "value": "staticmethod(_jit_mass_matrix)" }, { "name": "_adapt_func", "description": "", "type": null, "value": "False" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "func", "type": null, "default": "None", "description": "right-hand side ``f(x, u, t) -> ndarray``" }, { "name": "mass", "type": null, "default": "None", "description": "mass matrix descriptor (dense, banded or sparse)" }, { "name": "initial_value", "type": null, "default": "None", "description": "initial state, must have the same length as ``mass.n``" }, { "name": "jac", "type": null, "default": "None", "description": "analytical :math:`\\partial f / \\partial x` as a flat row-major ``n × n`` array. If omitted, numerical or AD-derived Jacobians are used downstream." } ] }, { "name": "Matrix", "description": "Linear matrix operation (matrix-vector product).", "docstring_html": "

Linear matrix operation (matrix-vector product).

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\mathbf{A} \\vec{u}\n

Parameters

A : np.ndarray: matrix, 2d array with dim=2

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Matrix'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'A': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "A", "type": null, "default": "...", "description": "matrix, 2d array with dim=2" } ] }, { "name": "Mod", "description": "Modulo operator block.", "docstring_html": "

Modulo operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\vec{u} \\bmod m\n

Note

modulo is not differentiable at discontinuities

Parameters

modulus : float: modulus value

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Mod'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'modulus': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "modulus", "type": null, "default": "...", "description": "modulus value" } ] }, { "name": "ModelExchangeFMU", "description": "ModelExchangeFMU block", "docstring_html": "

ModelExchangeFMU block

Multiplies all signals from all input ports (MISO).

\ny(t) = \\prod_i u_i(t)\n

Note

This block is purely algebraic and its operation (op_alg) will be called\nmultiple times per timestep, each time when Simulation._update(t) is\ncalled in the global simulation loop.

Attributes

op_alg : Operator: internal algebraic operator that wraps 'prod'

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Multiplier'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [] }, { "name": "Norm", "description": "Vector norm operator block.", "docstring_html": "

Vector norm operator block.

This block computes the Euclidean norm of the input vector:

\ny = \\|\\vec{u}\\|_2 = \\sqrt{\\sum_i u_i^2}\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Norm'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "ODE", "description": "Ordinary differential equation (ODE) defined by its right hand side function.", "docstring_html": "

Ordinary differential equation (ODE) defined by its right hand side function.

\n\\begin{align}\n    \\dot{x}(t) &= \\mathrm{func}(x(t), u(t), t) \\\\\n           y(t) &= x(t)\n\\end{align}\n

with inhomogenity (input) u and state vector x. The function can be nonlinear\nand the ODE can be of arbitrary order. The block utilizes the integration engine\nto solve the ODE by integrating the func, which is the right hand side function.

Example

For example a linear 1st order ODE:

\node = ODE(lambda x, u, t: -x)\n

Or something more complex like the Van der Pol system, where it makes sense to\nalso specify the jacobian, which improves convergence for implicit solvers but is\nnot needed in most cases:

\nimport numpy as np\n\n#initial condition\nx0 = np.array([2, 0])\n\n#van der Pol parameter\nmu = 1000\n\ndef func(x, u, t):\n    return np.array([x[1], mu*(1 - x[0]**2)*x[1] - x[0]])\n\n#analytical jacobian (optional)\ndef jac(x, u, t):\n    return np.array(\n        [[0                , 1               ],\n         [-mu*2*x[0]*x[1]-1, mu*(1 - x[0]**2)]]\n         )\n\n#finally the block\nvdp = ODE(func, x0, jac)\n

Parameters

func : callable: right hand side function of ODE
initial_value : array[float]: initial state / initial condition
jac : callable, None: jacobian of 'func' or 'None'

Attributes

op_dyn : DynamicOperator: internal dynamic operator for ODE right hand side 'func'

Proportional-Integral-Differentiation (PID) controller.

The transfer function is defined as

\nH(s) = K_p + K_i \\frac{1}{s} + K_d \\frac{s}{1 + s / f_\\mathrm{max}}\n

where the differentiation is approximated by a high pass filter that holds\nfor signals up to a frequency of approximately f_max.

Internally realized as a linear state space model with two states\n(differentiator filter state and integrator state).

Note

Example

The block is initialized like this:

\n#cutoff at 1kHz\npid = PID(Kp=2, Ki=0.5, Kd=0.1, f_max=1e3)\n

Parameters

Kp : float: proportional controller coefficient
Ki : float: integral controller coefficient
Kd : float: differentiator controller coefficient
f_max : float: highest expected signal frequency

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'PID'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'Kp': None, 'Ki': None, 'Kd': None, 'f_max': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "Kp", "type": null, "default": "...", "description": "proportional controller coefficient" }, { "name": "Ki", "type": null, "default": "...", "description": "integral controller coefficient" }, { "name": "Kd", "type": null, "default": "...", "description": "differentiator controller coefficient" }, { "name": "f_max", "type": null, "default": "...", "description": "highest expected signal frequency" } ] }, { "name": "PT1", "description": "First-order lag element (PT1).", "docstring_html": "

First-order lag element (PT1).

The transfer function is defined as

\nH(s) = \\frac{K}{1 + T s}\n

where K is the static gain and T is the time constant.

Example

The block is initialized like this:

\npt1 = PT1(K=2.0, T=0.5)\n

Parameters

K : float: static gain
T : float: time constant in seconds (must be > 0)

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'PT1'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'K': None, 'T': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "K", "type": null, "default": "...", "description": "static gain" }, { "name": "T", "type": null, "default": "...", "description": "time constant in seconds (must be > 0)" } ] }, { "name": "PT2", "description": "Second-order lag element (PT2).", "docstring_html": "

Second-order lag element (PT2).

The transfer function is defined as

\nH(s) = \\frac{K}{1 + 2 d T s + T^2 s^2}\n

where K is the static gain, T is the time constant\n(related to the natural frequency by \\omega_n = 1/T)\nand d is the damping ratio.

The damping ratio d controls the transient behavior:

d < 1: underdamped (oscillatory)
d = 1: critically damped
d > 1: overdamped

Example

The block is initialized like this:

\n#underdamped second-order system\npt2 = PT2(K=1.0, T=0.1, d=0.3)\n

Parameters

K : float: static gain
T : float: time constant in seconds (must be > 0)
d : float: damping ratio (must be >= 0)

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'PT2'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'K': None, 'T': None, 'd': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "K", "type": null, "default": "...", "description": "static gain" }, { "name": "T", "type": null, "default": "...", "description": "time constant in seconds (must be > 0)" }, { "name": "d", "type": null, "default": "...", "description": "damping ratio (must be >= 0)" } ] }, { "name": "PinkNoise", "description": "Pink noise (1/f noise) source using the Voss-McCartney algorithm.", "docstring_html": "

Pink noise (1/f noise) source using the Voss-McCartney algorithm.

Generates noise with power spectral density proportional to 1/f, where\nlower frequencies have more power than higher frequencies.

The algorithm maintains num_octaves independent random values representing\ndifferent frequency bands. At each sample, one octave is updated based on the\nbinary representation of the sample counter, creating the characteristic 1/f\nspectrum through the superposition of different update rates.

Note

If spectral_density is provided, it takes precedence over standard_deviation.\nIf sampling_period is set, noise is sampled at fixed intervals (zero-order hold).

Parameters

standard_deviation : float: approximate output standard deviation (default: 1.0)
spectral_density : float, optional: power spectral density, output scaled as √(S₀/(N·dt))
num_octaves : int: number of frequency bands in algorithm (default: 16)
sampling_period : float, optional: time between samples, if None samples every timestep
seed : int, optional: random seed for reproducibility

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'PinkNoise'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'standard_deviation': 1.0, 'spectral_density': None, 'num_octaves': 16, 'sampling_period': None, 'seed': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "standard_deviation", "type": null, "default": "1.0", "description": "approximate output standard deviation (default: 1.0)" }, { "name": "spectral_density", "type": null, "default": "None", "description": "power spectral density, output scaled as √(S₀/(N·dt))" }, { "name": "num_octaves", "type": null, "default": "16", "description": "number of frequency bands in algorithm (default: 16)" }, { "name": "sampling_period", "type": null, "default": "None", "description": "time between samples, if None samples every timestep" }, { "name": "seed", "type": null, "default": "None", "description": "random seed for reproducibility" } ] }, { "name": "Polynomial", "description": "Polynomial operator block.", "docstring_html": "

Polynomial operator block.

Evaluates a polynomial in the input. The coefficients follow the\nnumpy.polyval convention, with the highest order term first:

\n\\vec{y} = c_0 \\vec{u}^n + c_1 \\vec{u}^{n-1} + \\dots + c_{n-1} \\vec{u} + c_n\n

This block supports vector inputs (the polynomial is evaluated\nelement-wise).

Example

Quadratic y = 2 u^2 + 3 u + 1:

\np = Polynomial(coeffs=[2, 3, 1])\n

Parameters

coeffs : array_like: polynomial coefficients in descending order of power,\nfollowing the numpy.polyval convention

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Polynomial'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'coeffs': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "coeffs", "type": null, "default": "...", "description": "polynomial coefficients in descending order of power, following the ``numpy.polyval`` convention" } ] }, { "name": "Pow", "description": "Raise to power operator block.", "docstring_html": "

Raise to power operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\vec{u}^{p}\n

Parameters

exponent : float, array_like: exponent to raise the input to the power of

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Pow'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'exponent': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "exponent", "type": null, "default": "...", "description": "exponent to raise the input to the power of" } ] }, { "name": "PowProd", "description": "Power-Product operator block.", "docstring_html": "

Power-Product operator block.

This block raises each input to a power and then multiplies all results together:

\ny = \\prod_i u_i^{p_i}\n

Parameters

exponents : float, array_like: exponent(s) to raise the inputs to the power of. If scalar,\napplies same exponent to all inputs.

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'PowProd'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'exponents': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "exponents", "type": null, "default": "...", "description": "exponent(s) to raise the inputs to the power of. If scalar, applies same exponent to all inputs." } ] }, { "name": "Pulse", "description": "Alias for PulseSource.", "docstring_html": "

Alias for PulseSource.

Generates a periodic pulse waveform with defined rise and fall times.

Scheduled events trigger phase changes (low, rising, high, falling),\nand the update method calculates the output value based on the\ncurrent phase, performing linear interpolation during rise and fall.

Parameters

amplitude : float, optional: Peak amplitude of the pulse. Default is 1.0.
T : float, optional: Period of the pulse train. Must be positive. Default is 1.0.
t_rise : float, optional: Duration of the rising edge. Default is 0.0.
t_fall : float, optional: Duration of the falling edge. Default is 0.0.
tau : float, optional: Initial delay before the first pulse cycle begins. Default is 0.0.
duty : float, optional: Duty cycle, ratio of the pulse ON duration (plateau time only)\nto the total period T (must be between 0 and 1). Default is 0.5.\nThe high plateau duration is T * duty.

Attributes

events : list[Schedule]: Internal scheduled events triggering phase transitions.
_phase : str: Current phase of the pulse ('low', 'rising', 'high', 'falling').
_phase_start_time : float: Simulation time when the current phase began.

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'PulseSource'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'amplitude': 1.0, 'T': 1.0, 't_rise': 0.0, 't_fall': 0.0, 'tau': 0.0, 'duty': 0.5}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "amplitude", "type": null, "default": "1.0", "description": "Peak amplitude of the pulse. Default is 1.0." }, { "name": "T", "type": null, "default": "1.0", "description": "Period of the pulse train. Must be positive. Default is 1.0." }, { "name": "t_rise", "type": null, "default": "0.0", "description": "Duration of the rising edge. Default is 0.0." }, { "name": "t_fall", "type": null, "default": "0.0", "description": "Duration of the falling edge. Default is 0.0." }, { "name": "tau", "type": null, "default": "0.0", "description": "Initial delay before the first pulse cycle begins. Default is 0.0." }, { "name": "duty", "type": null, "default": "0.5", "description": "Duty cycle, ratio of the pulse ON duration (plateau time only) to the total period T (must be between 0 and 1). Default is 0.5. The high plateau duration is `T * duty`." } ] }, { "name": "RandomNumberGenerator", "description": "Generates a random output value using `numpy.random.rand`.", "docstring_html": "

Generates a random output value using numpy.random.rand.

If no sampling_period (None) is specified, every simulation timestep gets\na random value. Otherwise an internal Schedule event is used to periodically\nsample a random value and set the output like a zero-order-hold stage.

Parameters

sampling_period : float, None: time between random samples

Attributes

_sample : float: internal random number state in case that\nno sampling_period is provided
Evt : Schedule: internal event that periodically samples a random\nvalue in case sampling_period is provided

Rate limiter block that limits the rate of change of a signal.

Implements a continuous-time rate limiter as a first-order tracking system\nwith clipped rate of change:

\n\\dot{x} = \\mathrm{clip}\\left(f_\\mathrm{max} (u - x),\\; -r,\\; r\\right)\n

where r is the maximum allowed rate and f_max controls the tracking\nbandwidth when the signal is not rate-limited. The output is the state\ny = x.

Note

The parameter f_max should be set high enough that the output tracks\nthe input without lag when the rate is within limits.

Example

The block is initialized like this:

\n#max rate of 10 units/s\nrl = RateLimiter(rate=10.0, f_max=1e3)\n

Parameters

rate : float: maximum rate of change (positive value)
f_max : float: tracking bandwidth parameter

Relay block with hysteresis (Schmitt trigger).

Switches output between two values based on input crossing upper and lower\nthresholds. The hysteresis prevents rapid switching when input is noisy.

When input rises above threshold_up, output switches to value_up.\nWhen input falls below threshold_down, output switches to value_down.

Examples

Basic thermostat that turns heater on below 19°C, off above 21°C:

\nfrom pathsim.blocks import Relay\n\nthermostat = Relay(\n    threshold_up=21.0,\n    threshold_down=19.0,\n    value_up=0.0,\n    value_down=1.0\n    )\n

Parameters

threshold_up : float: threshold for transitioning to upper relay state value_up (default: 1.0)
threshold_down : float: threshold for transitioning to lower relay state value_down (default: 0.0)
value_up : float: value for upper relay state (default: 1.0)
value_down : float: value for lower relay state (default: 0.0)

Attributes

events : list[ZeroCrossingUp, ZeroCrossingDown]: internal zero crossing events for relay state transitions

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Relay'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'threshold_up': None, 'threshold_down': None, 'value_up': None, 'value_down': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{'in': 0}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "threshold_up", "type": null, "default": "...", "description": "threshold for transitioning to upper relay state `value_up` (default: 1.0)" }, { "name": "threshold_down", "type": null, "default": "...", "description": "threshold for transitioning to lower relay state `value_down` (default: 0.0)" }, { "name": "value_up", "type": null, "default": "...", "description": "value for upper relay state (default: 1.0)" }, { "name": "value_down", "type": null, "default": "...", "description": "value for lower relay state (default: 0.0)" } ] }, { "name": "Rescale", "description": "Linear rescaling / mapping block.", "docstring_html": "

Linear rescaling / mapping block.

Maps the input linearly from range [i0, i1] to range [o0, o1].\nOptionally saturates the output to [o0, o1].

\ny = o_0 + \\frac{(x - i_0) \\cdot (o_1 - o_0)}{i_1 - i_0}\n

This block supports vector inputs.

Parameters

i0 : float: input range lower bound
i1 : float: input range upper bound
o0 : float: output range lower bound
o1 : float: output range upper bound
saturate : bool: if True, clamp output to [min(o0,o1), max(o0,o1)]

Attributes

op_alg : Operator: internal algebraic operator

Zero-order hold: samples the input periodically and holds it at the output.

\ny(t) = u(k T + \\tau), \\quad k T + \\tau \\leq t < (k+1) T + \\tau\n

Note

Supports vector input — each channel is sampled independently.

Parameters

T : float: sampling period
tau : float: delay before first sample

Attributes

events : list[Schedule]: internal scheduled event for periodic sampling

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'SampleHold'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'T': None, 'tau': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "T", "type": null, "default": "...", "description": "sampling period" }, { "name": "tau", "type": null, "default": "...", "description": "delay before first sample" } ] }, { "name": "SemiExplicitDAE", "description": "Semi-explicit Index-1 DAE block.", "docstring_html": "

Semi-explicit Index-1 DAE block.

Solves an Index-1 system with split differential and algebraic states

\n\\dot{x} &= f_\\mathrm{dyn}(x, z, u, t) \\\\\n0       &= f_\\mathrm{alg}(x, z, u, t)\n

The algebraic state z is eliminated by an inner Newton on\nf_\\mathrm{alg}(x, z, u, t) = 0 at every RHS evaluation\n(warmstarted from the previous call). The outer solver sees a plain ODE\nin x, so any of the explicit or implicit solvers in fastsim can\nbe attached.

The block output is [x; z] (with z taken from the converged\ninner Newton), so downstream blocks see both differential and algebraic\nstates.

Trade-offs vs formulating the same system as a :class:`MassMatrixDAE`\nwith a block-diagonal singular mass:

explicit solvers (RKDP54, RKF78, RKV65, …) work
smaller Newton problem per stage (size n_z instead of\nn_x + n_z)
inner Newton cost per RHS call (typically 1–3 iterations once\nwarmstarted)
adaptive error control watches only x, not z

Parameters

f_dyn : callable: differential RHS f_dyn(x, z, u, t) -> ndarray of length n_x
f_alg : callable: algebraic constraint f_alg(x, z, u, t) -> ndarray of length n_z
x0 : array_like: initial differential state (length n_x)
z0 : array_like: initial algebraic state (length n_z), used as Newton warmstart
jac_z : callable, optional: analytical \\partial f_\\mathrm{alg} / \\partial z as a flat\nrow-major n_z × n_z array. Falls back to central differences if\nomitted.

\n", "source": null, "bases": [ "fastsim.blocks._shim._JitShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'SemiExplicitDAE'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'f_dyn': None, 'f_alg': None, 'x0': None, 'z0': None, 'jac_z': None}" }, { "name": "_jit_fn", "description": "", "type": null, "value": "staticmethod(_jit_semi_explicit)" }, { "name": "_adapt_func", "description": "", "type": null, "value": "False" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "f_dyn", "type": null, "default": "None", "description": "differential RHS ``f_dyn(x, z, u, t) -> ndarray`` of length ``n_x``" }, { "name": "f_alg", "type": null, "default": "None", "description": "algebraic constraint ``f_alg(x, z, u, t) -> ndarray`` of length ``n_z``" }, { "name": "x0", "type": null, "default": "None", "description": "initial differential state (length ``n_x``)" }, { "name": "z0", "type": null, "default": "None", "description": "initial algebraic state (length ``n_z``), used as Newton warmstart" }, { "name": "jac_z", "type": null, "default": "None", "description": "analytical :math:`\\partial f_\\mathrm{alg} / \\partial z` as a flat row-major ``n_z × n_z`` array. Falls back to central differences if omitted." } ] }, { "name": "Sin", "description": "Sine operator block.", "docstring_html": "

Sine operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\sin(\\vec{u})\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Sin'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "Sinh", "description": "Hyperbolic sine operator block.", "docstring_html": "

Hyperbolic sine operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\sinh(\\vec{u})\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Sinh'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "SinusoidalPhaseNoiseSource", "description": "Sinusoidal source with cumulative and white phase noise.", "docstring_html": "

Sinusoidal source with cumulative and white phase noise.

Generates a sinusoid with additive phase noise from two components:

White phase noise: sampled from a normal distribution at each sample
Cumulative phase noise: integrated random walk process

The output is given by:

\ny(t) = A \\sin\\left(\\omega t + \\varphi_0 + \\sigma_w n_w(t) + \\sigma_c \\int_0^t n_c(\\tau) d\\tau\\right)\n

where A is amplitude, \\omega = 2\\pi f is angular frequency,\n\\varphi_0 is initial phase, \\sigma_w and \\sigma_c are\nthe white and cumulative noise weights, and n_w(t) and n_c(t) are\nindependent standard normal random processes sampled at the specified sampling period.

Parameters

frequency : float: frequency of the sinusoid
amplitude : float: amplitude of the sinusoid
phase : float: initial phase of the sinusoid (radians)
sig_cum : float: weight for cumulative phase noise contribution
sig_white : float: weight for white phase noise contribution
sampling_period : float, None: time between phase noise samples. If None,\nnoise is sampled every timestep (default is 0.1)

Attributes

omega : float: angular frequency of the sinusoid, derived from frequency
noise_1 : float: internal noise value for white phase noise
noise_2 : float: internal noise value for cumulative phase noise
events : list[Schedule]: scheduled event for periodic sampling (only if sampling_period is set)

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'SinusoidalPhaseNoiseSource'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'frequency': 1.0, 'amplitude': 1.0, 'phase': 0.0, 'sig_cum': 0.0, 'sig_white': 0.0, 'sampling_period': 0.1, 'seed': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "{}" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "frequency", "type": null, "default": "1.0", "description": "frequency of the sinusoid" }, { "name": "amplitude", "type": null, "default": "1.0", "description": "amplitude of the sinusoid" }, { "name": "phase", "type": null, "default": "0.0", "description": "initial phase of the sinusoid (radians)" }, { "name": "sig_cum", "type": null, "default": "0.0", "description": "weight for cumulative phase noise contribution" }, { "name": "sig_white", "type": null, "default": "0.0", "description": "weight for white phase noise contribution" }, { "name": "sampling_period", "type": null, "default": "0.1", "description": "time between phase noise samples. If None, noise is sampled every timestep (default is 0.1)" }, { "name": "seed", "type": null, "default": "None", "description": "" } ] }, { "name": "SinusoidalSource", "description": "Source block that generates a sinusoid wave", "docstring_html": "

Source block that generates a sinusoid wave

Parameters

frequency : float: frequency of the sinusoid
amplitude : float: amplitude of the sinusoid
phase : float: phase of the sinusoid

Source that produces an arbitrary time dependent output defined by func (callable).

\ny(t) = \\mathrm{func}(t)\n

Note

This block is purely algebraic and its internal function (func) will\nbe called multiple times per timestep, each time when Simulation._update(t)\nis called in the global simulation loop.

Example

For example a ramp:

\nfrom pathsim.blocks import Source\n\nsrc = Source(lambda t : t)\n

or a simple sinusoid with some frequency:

\nimport numpy as np\nfrom pathsim.blocks import Source\n\n#some parameter\nomega = 100\n\n#the function that gets evaluated\ndef f(t):\n    return np.sin(omega * t)\n\nsrc = Source(f)\n

Because the Source block only has a single argument, it can be\nused to decorate a function and make it a PathSim block. This might\nbe handy in some cases to keep definitions concise and localized\nin the code:

\nimport numpy as np\nfrom pathsim.blocks import Source\n\n#does the same as the definition above\n\n@Source\ndef src(t):\n    omega = 100\n    return np.sin(omega * t)\n\n#'src' is now a PathSim block\n

Parameters

func : callable: function defining time dependent block output

Square root operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\sqrt{|\\vec{u}|}\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Sqrt'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "SquareWaveSource", "description": "Discrete time square wave source.", "docstring_html": "

Discrete time square wave source.

Utilizes scheduled events to periodically set\nthe block output at discrete times.

Parameters

amplitude : float: amplitude of the square wave signal
frequency : float: frequency of the square wave signal
phase : float: phase of the square wave signal

Attributes

events : list[Schedule]: internal scheduled events

Linear time invariant (LTI) multi input multi output (MIMO) state space model.

\n\\begin{align}\n    \\dot{x} &= \\mathbf{A} x + \\mathbf{B} u \\\\\n           y &= \\mathbf{C} x + \\mathbf{D} u\n\\end{align}\n

where A, B, C and D are the state space matrices, x is the state,\nu the input and y the output vector.

Example

A SISO state space block with two internal states can be initialized\nlike this:

\nS = StateSpace(\n    A=-np.eye(2),\n    B=np.ones((2, 1)),\n    C=np.ones((1, 2)),\n    D=1.0\n    )\n

and a MIMO (2 in, 2 out) state space block with three internal states\ncan be initialized like this:

\nS = StateSpace(\n    A=-np.eye(3),\n    B=np.ones((3, 2)),\n    C=np.ones((2, 3)),\n    D=np.ones((2, 2))\n    )\n

Parameters

A, B, C, D : array_like: real valued state space matrices
initial_value : array_like, None: initial state / initial condition

Attributes

op_dyn : DynamicOperator: internal dynamic operator for state equation
op_alg : DynamicOperator: internal algebraic operator for mapping to outputs

Alias for StepSource.

Discrete time unit step (or multi step) source block.

Utilizes a scheduled event to set the block output\nto the specified output levels at the defined event times.

The arguments can be vectorial and in that case, the output is set to the\namplitude that corresponds to the defined delay like a zero-order-hold stage.\nThis functionality enables adding external or time series measurement data\ninto the system.

Examples

This is how to use the source as a unit step source:

\nfrom pathsim.blocks import StepSource\n\n#default, starts at 0, jumps to 1\nstp = StepSource()\n

And this is how to configure it with multiple consecutive steps:

\nfrom pathsim.blocks import StepSource\n\n#starts at 0, jumps to 1 at 1, jumps to -1 at 2 and jumps back to 0 at 3\nstp = StepSource(amplitude=[1, -1, 0], tau=[1, 2, 3])\n

Similarly implementing measured time series data via zoh:

\nimport numpy as np\nfrom pathsim.blocks import StepSource\n\n#some random time series arrays\ntimes, data = np.linspace(0, 100, 1000), np.random.rand(1000)\n\n#pass them to the block\nstp = StepSource(amplitude=data, tau=times)\n

Parameters

amplitude : float | list[float]: amplitude of the step signal, or amplitudes / output\nlevels of the multiple steps
tau : float | list[float]: delay of the step, or delays of the different steps

Attributes

Evt : ScheduleList: internal scheduled event directly accessible
events : list[ScheduleList]: list of interna events

Switch block that selects between its inputs.

Example

The block is initialized like this:

\n#default None -> no passthrough\ns1 = Switch()\n\n#selecting port 2 as passthrough\ns2 = Switch(2)\n\n#change the state of the switch to port 3\ns2.select(3)\n

Sets block output depending on self.switch_state like this:

\nswitch_state == None -> outputs[0] = 0\n\nswitch_state == 0 -> outputs[0] = inputs[0]\n\nswitch_state == 1 -> outputs[0] = inputs[1]\n\nswitch_state == 2 -> outputs[0] = inputs[2]\n\n...\n

Parameters

switch_state : int, None: state of the switch

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Switch'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'switch_state': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "{'out': 0}" } ], "parameters": [ { "name": "switch_state", "type": null, "default": "None", "description": "state of the switch" } ] }, { "name": "Tan", "description": "Tangent operator block.", "docstring_html": "

Tangent operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\tan(\\vec{u})\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Tan'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "Tanh", "description": "Hyperbolic tangent operator block.", "docstring_html": "

Hyperbolic tangent operator block.

This block supports vector inputs. This is the operation it does:

\n\\vec{y} = \\tanh(\\vec{u})\n

Attributes

op_alg : Operator: internal algebraic operator

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'Tanh'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [] }, { "name": "TappedDelay", "description": "Tapped delay line.", "docstring_html": "

Tapped delay line.

Outputs the current and N-1 past samples of the input as parallel\nsignals. The block has N outputs:

\ny_i[k] = u[k - i], \\quad i = 0, 1, \\dots, N-1\n

Parameters

N : int: number of taps (output ports)
T : float: sampling period
tau : float: delay before first sample

Attributes

events : list[Schedule]: internal scheduled event for periodic shift

Alias for TransferFunctionPRC.

This block defines a LTI (SISO) transfer function.

The transfer function is defined in polynomial (numerator-denominator) form

\n\\mathbf{H}(s) = \\frac{b_n + b_{n-1} s + \\dots + b_{0} s^n}{a_m + a_{m-1} s + \\dots + a_{0} s^m}\n

where Num is the list of numerator polynomial coefficients and Den the\nlist of denominator coefficients.

Upon initialization, the state space realization of the transfer function is\ncomputed using scipy.signal.TransferFunction(Num, Den).to_ss().

The resulting state space model of the form

\n\\begin{align}\n    \\dot{x} &= \\mathbf{A} x + \\mathbf{B} u \\\\\n           y &= \\mathbf{C} x + \\mathbf{D} u\n\\end{align}\n

is handled the same as the 'StateSpace' block, where A, B, C and D\nare the state space matrices, x is the internal state, u the input and\ny the output vector.

Parameters

Num : array_like: numerator polynomial coefficients
Den : array_like: denominator polynomial coefficients

This block defines a LTI (MIMO for pole residue) transfer function.

The transfer function is defined in pole-residue-constant (PRC) form

\n\\mathbf{H}(s) = \\mathbf{C} + \\sum_n^N \\frac{\\mathbf{R}_n}{s - p_n}\n

where 'Poles' are the scalar (possibly complex conjugate) poles of the\ntransfer function and 'Residues' are the possibly matrix valued (in MIMO case)\nand complex conjugate residues of the transfer function. 'Const' has same\nshape as 'Residues'.

Upon initialization, the state space realization of the transfer\nfunction is computed using a minimal gilbert realization.

The resulting state space model of the form

\n\\begin{align}\n    \\dot{x} &= \\mathbf{A} x + \\mathbf{B} u \\\\\n           y &= \\mathbf{C} x + \\mathbf{D} u\n\\end{align}\n

is handled the same as the 'StateSpace' block, where A, B, C and D\nare the state space matrices, x is the internal state, u the input and\ny the output vector.

Parameters

Poles : array: transfer function poles
Residues : array: transfer function residues
Const : array, float: constant term of transfer function

This block defines a LTI (SISO) transfer function.

The transfer function is defined in zeros-poles-gain (ZPG) form

\n\\mathbf{H}(s) = k \\frac{(s - z_1)(s - z_2)\\cdots(s - z_m)}{(s - p_1)(s - p_2)\\cdots(s - p_n)}\n

where Zeros are the scalar (possibly complex conjugate) zeros of the\ntransfer function, and Poles are the poles (denominator zeros) of the\ntransfer function. Gain is the scalar factor k.

Upon initialization, the state space realization of the transfer function is\ncomputed using scipy.signal.ZerosPolesGain(Zeros, Poles, Gain).to_ss().

The resulting state space model of the form

\n\\begin{align}\n    \\dot{x} &= \\mathbf{A} x + \\mathbf{B} u \\\\\n           y &= \\mathbf{C} x + \\mathbf{D} u\n\\end{align}\n

is handled the same as the 'StateSpace' block, where A, B, C and D\nare the state space matrices, x is the internal state, u the input and\ny the output vector.

Parameters

Poles : array_like: transfer function poles
Zeros : array_like: transfer function zeros
Gain : float: gain term of transfer function

Source block that generates an analog triangle wave

Parameters

frequency : float: frequency of the triangle wave
amplitude : float: amplitude of the triangle wave
phase : float: phase of the triangle wave

White noise source with Gaussian distribution.

Generates uncorrelated random samples with either constant amplitude\n(standard_deviation mode) or timestep-scaled amplitude for stochastic\nintegration (spectral_density mode).

In spectral density mode, output is scaled as √(S₀/dt) so that integrating\nthe noise yields correct statistical properties (Wiener process).

Note

If spectral_density is provided, it takes precedence over standard_deviation.\nIf sampling_period is set, noise is sampled at fixed intervals (zero-order hold).

Parameters

standard_deviation : float: output standard deviation for constant-amplitude mode (default: 1.0)
spectral_density : float, optional: power spectral density S₀ in [signal²/Hz]
sampling_period : float, optional: time between samples, if None samples every timestep
seed : int, optional: random seed for reproducibility

Wrapper block for discrete implementation and external code integration.

The Wrapper class is designed to call the internal func at fixed intervals\nusing an internal Schedule event. This makes it particularly useful for wrapping\nexternal code or implementing discrete-time systems.

Essentially this block does the same as Function with the difference that its\nnot evaluated continuously but periodically at discrete times.

Example

There are two ways to setup the Wrapper, first and standard way is to define\na function to be wrapped and pass it to the block initializer:

\nfrom pathsim.blocks import Wrapper\n\n#function to be wrapped\ndef func(a, b, c):\n    return a * (b + c)\n\nwrp = Wrapper(func, T=0.1)\n

Another option is to use the dec classmethod, which might be more convenient\nin some situations:

\nfrom pathsim.blocks import Wrapper\n\n@Wrapper.dec(T=0.1)\ndef wrp(a, b, c):\n    return a * (b + c)\n

This way the internal function of the block wrp will be evaluated with a period\nof T=0.1 and its outputs updated accordingly.

Parameters

func : callable: function that defines algebraic block IO behaviour
T : float: sampling period for the wrapped function
tau : float: delay time for the start time of the event

Attributes

Evt : Schedule: internal event. Used for periodic sampling the wrapped method

Zero-order hold: samples the input periodically and holds it at the output.

\ny(t) = u(k T + \\tau), \\quad k T + \\tau \\leq t < (k+1) T + \\tau\n

Note

Supports vector input — each channel is sampled independently.

Parameters

T : float: sampling period
tau : float: delay before first sample

Attributes

events : list[Schedule]: internal scheduled event for periodic sampling

\n", "source": null, "bases": [ "fastsim.blocks._shim._ShimBlock" ], "methods": [], "attributes": [ { "name": "_factory_name", "description": "", "type": null, "value": "'ZeroOrderHold'" }, { "name": "_param_defaults", "description": "", "type": null, "value": "{'T': None, 'tau': None}" }, { "name": "input_port_labels", "description": "", "type": null, "value": "None" }, { "name": "output_port_labels", "description": "", "type": null, "value": "None" } ], "parameters": [ { "name": "T", "type": null, "default": "...", "description": "sampling period" }, { "name": "tau", "type": null, "default": "...", "description": "delay before first sample" } ] } ], "functions": [] }, "fastsim.events": { "name": "fastsim.events", "description": "", "docstring_html": "", "classes": [ { "name": "ZeroCrossing", "description": "Subclass of base 'Event' that triggers if the event function crosses zero.", "docstring_html": "

Subclass of base 'Event' that triggers if the event function crosses zero.\nThis is a bidirectional zero-crossing detector.

Monitors system state by evaluating an event function (func_evt) with scalar output and\ntesting for zero crossings (sign changes).

\nfunc_evt(time) -> event?\n

If an event is detected, some action (func_act) is performed on the system state.

\nfunc_evt(time) == 0 -> event -> func_act(time)\n

Example

Initialize a zero-crossing event handler like this:

\n# define the event function\ndef evt(t):\n    # here we have a zero-crossing at 't==10'\n    return t - 10\n\n# define the action function (callback)\ndef act(t):\n    # do something at event resolution\n    pass\n\n# initialize the event manager\nE = ZeroCrossing(\n    func_evt=evt,  # the event function\n    func_act=act   # the action function\n    )\n

Parameters

func_evt : callable: event function, where zeros are events
func_act : callable: action function for event resolution
tolerance : float: tolerance to check if detection is close to actual event

\n", "source": null, "bases": [ "fastsim._fastsim.ZeroCrossing" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "ZeroCrossingUp", "description": "Modification of standard 'ZeroCrossing' event where events are only triggered", "docstring_html": "

Modification of standard 'ZeroCrossing' event where events are only triggered\nif the event function changes sign from negative to positive (up). Also called\nunidirectional zero-crossing.

\n", "source": null, "bases": [ "fastsim._fastsim.ZeroCrossingUp" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "ZeroCrossingDown", "description": "Modification of standard 'ZeroCrossing' event where events are only triggered", "docstring_html": "

Modification of standard 'ZeroCrossing' event where events are only triggered\nif the event function changes sign from positive to negative (down). Also called\nunidirectional zero-crossing.

\n", "source": null, "bases": [ "fastsim._fastsim.ZeroCrossingDown" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "Schedule", "description": "Subclass of base 'Event' that triggers dependent on the evaluation time.", "docstring_html": "

Subclass of base 'Event' that triggers dependent on the evaluation time.

Monitors time in every timestep and triggers periodically (period). This event\ndoes not have an event function as the event condition only depends on time.

\ntime == next_schedule_time -> event\n

Example

Initialize a scheduled event handler like this:

\n#define the action function (callback)\ndef act(t):\n    #do something at event resolution\n    pass\n\n#initialize the event manager\nE = Schedule(\n    t_start=0,    #starting at t=0\n    t_end=None,   #never ending\n    t_period=3,   #triggering every 3 time units\n    func_act=act  #resulting in a callback\n    )\n

Parameters

t_start : float: starting time for schedule
t_end : float: termination time for schedule
t_period : float: time period of schedule, when events are triggered
func_act : callable: action function for event resolution
tolerance : float: tolerance to check if detection is close to actual event

\n", "source": null, "bases": [ "fastsim._fastsim.Schedule" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "ScheduleList", "description": "Subclass of base 'Schedule' that triggers dependent on the evaluation time.", "docstring_html": "

Subclass of base 'Schedule' that triggers dependent on the evaluation time.

Monitors time in every timestep and triggers at the next event time from the\ntime list. This event does not have an event function as the event condition\nonly depends on time.

\ntime == next_scheduled_time -> event\n

Example

Initialize a scheduled event handler like this:

\n#define the action function (callback)\ndef act(t):\n    #do something at event resolution\n    pass\n\n#initialize the event manager\nE = ScheduleList(\n    times_evt=[1, 5, 12, 300],  #event times where to trigger\n    func_act=act                #resulting in a callback\n    )\n

Parameters

times_evt : list[float]: list of event times in ascending order
func_act : callable: action function for event resolution
tolerance : float: tolerance to check if detection is close to actual event

\n", "source": null, "bases": [ "fastsim._fastsim.ScheduleList" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "Condition", "description": "Subclass of base 'Event' that triggers if the event function evaluates to 'True',", "docstring_html": "

Subclass of base 'Event' that triggers if the event function evaluates to 'True',\ni.e. the condition is satisfied.

Monitors system state by evaluating an event function (func_evt) with boolean output.\nThe event is considered detected when the event function evaluates to 'True' for the\nfirst time. Subsequent evaluations to 'True' are not considered unless the event is reset.

\nfunc_evt(time) -> event?\n

If an event is detected, some action (func_act) is performed on the system state.

\nfunc_evt(time) == True -> event -> func_act(time)\n

Note

Condition event functions evaluate to boolean and are therefore not smooth.\nTherefore uses bisection method for event location instead of secant method.

Example

Initialize a conditional event handler like this:

\n#define the event function\ndef evt(t):\n    return t > 10\n\n#define the action function (callback)\ndef act(t):\n    #do something at event resolution\n    pass\n\n#initialize the event manager\nE = Condition(\n    func_evt=evt,  #the event function\n    func_act=act   #the action function\n    )\n

\n", "source": null, "bases": [ "fastsim._fastsim.Condition" ], "methods": [], "attributes": [], "parameters": [] } ], "functions": [] }, "fastsim.jit": { "name": "fastsim.jit", "description": "", "docstring_html": "", "classes": [], "functions": [ { "name": "jit", "description": "Trace and compile a Python function to optimised Rust IR.", "docstring_html": "

Trace and compile a Python function to optimised Rust IR.

The returned callable evaluates the function in Rust with zero Python\noverhead per call. Tracing is lazy by default (on first call) or\neager if n_x is provided.

Supported operations: arithmetic (incl. // floor-division),\nnp.sin/cos/tan/exp/log/tanh/..., np.dot, np.clip, np.where,\nnp.linalg.norm, np.cross, matrix multiply (@, incl. two traced\noperands like a state-dependent M(x) @ v), np.sum,\nfastsim.random_uniform / random_normal (stateless traceable noise),\nand more. Unsupported patterns fall back to the original Python function.

Parameters

func : callable: Python function with signature f(x) or f(x, t).
n_x : int, optional: Input dimension for eager tracing. If omitted, tracing is\ndeferred to the first call.

\n", "source": null, "signature": "(func, n_x = None)", "parameters": [ { "name": "func", "type": null, "default": null, "description": "Python function with signature ``f(x)`` or ``f(x, t)``." }, { "name": "n_x", "type": null, "default": "None", "description": "Input dimension for eager tracing. If omitted, tracing is deferred to the first call." } ], "returns": null }, { "name": "jacobian", "description": "Compute the Jacobian of a Python function via symbolic AD.", "docstring_html": "

Compute the Jacobian of a Python function via symbolic AD.

The returned callable evaluates the full Jacobian matrix in Rust.\nDifferentiation is performed symbolically on the traced computation\ngraph — no finite differences, no tape replay. The Jacobian graph\nis optimised (constant folding, CSE) before evaluation.

Parameters

func : callable: Python function with signature f(x) or f(x, t).\nMust return a list/array of floats.
n_x : int, optional: Input dimension for eager tracing.

\n", "source": null, "signature": "(func, n_x = None)", "parameters": [ { "name": "func", "type": null, "default": null, "description": "Python function with signature ``f(x)`` or ``f(x, t)``. Must return a list/array of floats." }, { "name": "n_x", "type": null, "default": "None", "description": "Input dimension for eager tracing." } ], "returns": null } ] }, "fastsim.solvers": { "name": "fastsim.solvers", "description": "", "docstring_html": "", "classes": [ { "name": "SSPRK22", "description": "Two-stage, 2nd order Strong Stability Preserving (SSP) Runge-Kutta method.", "docstring_html": "

Two-stage, 2nd order Strong Stability Preserving (SSP) Runge-Kutta method.

Also known as Heun's method. SSP methods preserve monotonicity and total\nvariation diminishing (TVD) properties of the spatial discretisation under\na timestep restriction scaled by the SSP coefficient.

Characteristics

Order: 2
Stages: 2
Explicit, fixed timestep
SSP coefficient \\mathcal{C} = 1

Note

Relevant when a block diagram wraps a method-of-lines discretisation of a\nhyperbolic PDE (e.g. shallow water, compressible Euler) inside an ODE\nblock and the spatial operator is TVD under forward Euler. For typical\nODE-based block diagrams without such structure, RK4 or RKDP54\nare more appropriate choices.

References

\n\n\n\n\n\n

[1]	Shu, C.-W., & Osher, S. (1988). "Efficient implementation of\nessentially non-oscillatory shock-capturing schemes". Journal of\nComputational Physics, 77(2), 439-471.\ndoi:10.1016/0021-9991(88)90177-5

\n\n\n\n\n\n

[2]	Gottlieb, S., Shu, C.-W., & Tadmor, E. (2001). "Strong\nstability-preserving high-order time discretization methods".\nSIAM Review, 43(1), 89-112.\ndoi:10.1137/S003614450036757X

\n", "source": null, "bases": [ "fastsim._fastsim.SSPRK22" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "SSPRK33", "description": "Three-stage, 3rd order optimal SSP Runge-Kutta method.", "docstring_html": "

Three-stage, 3rd order optimal SSP Runge-Kutta method.

The unique optimal three-stage, 3rd order SSP scheme. Commonly paired\nwith WENO and ENO spatial discretisations for hyperbolic conservation\nlaws.

Characteristics

Order: 3
Stages: 3
Explicit, fixed timestep
SSP coefficient \\mathcal{C} = 1

Note

The standard SSP time integrator for method-of-lines PDE discretisations\ninside ODE blocks. If the spatial operator is TVD under forward Euler,\nthis method preserves that property at the same timestep restriction.\nWhen stability is borderline, SSPRK34 allows roughly twice the\ntimestep at the cost of one extra stage.

References

\n\n\n\n\n\n

[1]	Shu, C.-W., & Osher, S. (1988). "Efficient implementation of\nessentially non-oscillatory shock-capturing schemes". Journal of\nComputational Physics, 77(2), 439-471.\ndoi:10.1016/0021-9991(88)90177-5

\n\n\n\n\n\n

[2]	Gottlieb, S., Shu, C.-W., & Tadmor, E. (2001). "Strong\nstability-preserving high-order time discretization methods".\nSIAM Review, 43(1), 89-112.\ndoi:10.1137/S003614450036757X

\n\n\n\n\n\n

[3]	Gottlieb, S., Ketcheson, D. I., & Shu, C.-W. (2011). "Strong\nStability Preserving Runge-Kutta and Multistep Time\nDiscretizations". World Scientific. doi:10.1142/7498

\n", "source": null, "bases": [ "fastsim._fastsim.SSPRK33" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "SSPRK34", "description": "Four-stage, 3rd order SSP Runge-Kutta method with SSP coefficient 2.", "docstring_html": "

Four-stage, 3rd order SSP Runge-Kutta method with SSP coefficient 2.

An extra stage compared to SSPRK33 doubles the allowable SSP timestep\n(\\mathcal{C} = 2), giving a larger effective stability region\nalong the negative real axis.

Characteristics

Order: 3
Stages: 4
Explicit, fixed timestep
SSP coefficient \\mathcal{C} = 2

Note

Preferable over SSPRK33 when a method-of-lines ODE block is close\nto the SSP timestep limit and the cost of one additional stage per step is\nacceptable in exchange for a factor-of-two relaxation in the CFL\nconstraint.

References

\n\n\n\n\n\n

[1]	Spiteri, R. J., & Ruuth, S. J. (2002). "A new class of optimal\nhigh-order strong-stability-preserving time discretization methods".\nSIAM Journal on Numerical Analysis, 40(2), 469-491.\ndoi:10.1137/S0036142901389025

\n\n\n\n\n\n

[2]	Gottlieb, S., Ketcheson, D. I., & Shu, C.-W. (2011). "Strong\nStability Preserving Runge-Kutta and Multistep Time\nDiscretizations". World Scientific. doi:10.1142/7498

\n", "source": null, "bases": [ "fastsim._fastsim.SSPRK34" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "RK4", "description": "Classical four-stage, 4th order explicit Runge-Kutta method.", "docstring_html": "

Classical four-stage, 4th order explicit Runge-Kutta method.

\n\\begin{aligned}\nk_1 &= f(x_n,\\; t_n) \\\\\nk_2 &= f\\!\\left(x_n + \\tfrac{h}{2}\\,k_1,\\; t_n + \\tfrac{h}{2}\\right) \\\\\nk_3 &= f\\!\\left(x_n + \\tfrac{h}{2}\\,k_2,\\; t_n + \\tfrac{h}{2}\\right) \\\\\nk_4 &= f(x_n + h\\,k_3,\\; t_n + h) \\\\\nx_{n+1} &= x_n + \\tfrac{h}{6}(k_1 + 2k_2 + 2k_3 + k_4)\n\\end{aligned}\n

Characteristics

Order: 4
Stages: 4
Explicit, fixed timestep

Note

The standard fixed-step explicit solver. Provides a good cost-to-accuracy\nratio for non-stiff block diagrams where the timestep is known a priori\n(e.g. real-time or hardware-in-the-loop simulation with a fixed clock).\nNot suitable for stiff systems. When accuracy demands vary during a run,\nadaptive methods like RKDP54 are more efficient because they\nconcentrate steps where the dynamics change rapidly.

References

\n\n\n\n\n\n

[1]	Kutta, W. (1901). "Beitrag zur näherungsweisen Integration totaler\nDifferentialgleichungen". Zeitschrift für Mathematik und Physik,\n46, 435-453.

\n\n\n\n\n\n

[2]	Hairer, E., Nørsett, S. P., & Wanner, G. (1993). "Solving Ordinary\nDifferential Equations I: Nonstiff Problems". Springer Series in\nComputational Mathematics, Vol. 8.\ndoi:10.1007/978-3-540-78862-1

\n", "source": null, "bases": [ "fastsim._fastsim.RK4" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "EUF", "description": "Explicit forward Euler method. First-order, single-stage.", "docstring_html": "

Explicit forward Euler method. First-order, single-stage.

\nx_{n+1} = x_n + h \\, f(x_n, t_n)\n

Characteristics

Order: 1
Stages: 1
Explicit, fixed timestep
Not A-stable

Note

The cheapest solver per step but also the least accurate. Its small stability\nregion requires very small timesteps for moderately dynamic block diagrams,\nwhich usually makes higher-order methods more efficient overall. Prefer\nRK4 for fixed-step or RKDP54 for adaptive integration of non-stiff\nsystems. Only practical when computational cost per step must be absolute\nminimum and accuracy is secondary.

References

\n\n\n\n\n\n

[1]	Hairer, E., Nørsett, S. P., & Wanner, G. (1993). "Solving Ordinary\nDifferential Equations I: Nonstiff Problems". Springer Series in\nComputational Mathematics, Vol. 8.\ndoi:10.1007/978-3-540-78862-1

\n\n\n\n\n\n

[2]	Butcher, J. C. (2016). "Numerical Methods for Ordinary Differential\nEquations". John Wiley & Sons, 3rd Edition.\ndoi:10.1002/9781119121534

\n", "source": null, "bases": [ "fastsim._fastsim.EUF" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "EUB", "description": "Implicit backward Euler method. First-order, A-stable and L-stable.", "docstring_html": "

Implicit backward Euler method. First-order, A-stable and L-stable.

\nx_{n+1} = x_n + h \\, f(x_{n+1}, t_{n+1})\n

The implicit equation is solved iteratively by the internal optimizer.

Characteristics

Order: 1
Stages: 1 (implicit)
Fixed timestep
A-stable, L-stable

Note

Maximum stability at the cost of accuracy. L-stability fully damps\nparasitic high-frequency modes, making this a safe fallback for very stiff\nblock diagrams (e.g. high-gain PID loops or fast electrical dynamics coupled\nto slow mechanical plant). Because each step requires solving a nonlinear\nequation, the cost per step is higher than explicit methods. For better\naccuracy on stiff systems, use BDF2 (fixed-step) or ESDIRK43\n(adaptive).

References

\n\n\n\n\n\n

[1]	Curtiss, C. F., & Hirschfelder, J. O. (1952). "Integration of stiff\nequations". Proceedings of the National Academy of Sciences, 38(3),\n235-243. doi:10.1073/pnas.38.3.235

\n\n\n\n\n\n

[2]	Hairer, E., & Wanner, G. (1996). "Solving Ordinary Differential\nEquations II: Stiff and Differential-Algebraic Problems". Springer\nSeries in Computational Mathematics, Vol. 14.\ndoi:10.1007/978-3-642-05221-7

\n", "source": null, "bases": [ "fastsim._fastsim.EUB" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "RKF21", "description": "Three-stage, 2nd order Runge-Kutta-Fehlberg method with embedded 1st order error estimate.", "docstring_html": "

Three-stage, 2nd order Runge-Kutta-Fehlberg method with embedded 1st order error estimate.

Characteristics

Order: 2 (propagating) / 1 (embedded)
Stages: 3
Explicit, adaptive timestep

Note

The cheapest adaptive explicit method available. The low order means the\nerror estimate itself is coarse, so step-size control is less reliable\nthan with higher-order pairs. Useful for rough exploratory runs of a new\nblock diagram or when step size is dominated by discrete events (zero\ncrossings, scheduled triggers) rather than truncation error. For\nproduction simulations, RKBS32 or RKDP54 are almost always\npreferable.

References

\n\n\n\n\n\n

[1]	Fehlberg, E. (1969). "Low-order classical Runge-Kutta formulas\nwith stepsize control and their application to some heat transfer\nproblems". NASA Technical Report TR R-315.

\n\n\n\n\n\n

[2]	Hairer, E., Nørsett, S. P., & Wanner, G. (1993). "Solving\nOrdinary Differential Equations I: Nonstiff Problems". Springer\nSeries in Computational Mathematics, Vol. 8.\ndoi:10.1007/978-3-540-78862-1

\n", "source": null, "bases": [ "fastsim._fastsim.RKF21" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "RKBS32", "description": "Bogacki-Shampine 3(2) pair. Four-stage, 3rd order with FSAL property.", "docstring_html": "

Bogacki-Shampine 3(2) pair. Four-stage, 3rd order with FSAL property.

The underlying method of MATLAB's ode23. The First-Same-As-Last\n(FSAL) property makes the effective cost three stages per accepted step.

Characteristics

Order: 3 (propagating) / 2 (embedded)
Stages: 4 (3 effective with FSAL)
Explicit, adaptive timestep

Note

A good default when moderate accuracy suffices and per-step cost matters\nmore than large step sizes. Fewer stages than 5th order pairs, so faster\nper step but needs more steps for the same global error. In a PathSim\nblock diagram with smooth, non-stiff dynamics and relaxed tolerances this\nis often the most efficient explicit choice. Switch to RKDP54 when\ntighter tolerances are required.

References

\n\n\n\n\n\n

[1]	Bogacki, P., & Shampine, L. F. (1989). "A 3(2) pair of\nRunge-Kutta formulas". Applied Mathematics Letters, 2(4),\n321-325. doi:10.1016/0893-9659(89)90079-7

\n\n\n\n\n\n

[2]	Shampine, L. F., & Reichelt, M. W. (1997). "The MATLAB ODE\nSuite". SIAM Journal on Scientific Computing, 18(1), 1-22.\ndoi:10.1137/S1064827594276424

\n", "source": null, "bases": [ "fastsim._fastsim.RKBS32" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "RKF45", "description": "Runge-Kutta-Fehlberg 4(5) pair. Six stages, 4th order propagation with", "docstring_html": "

Runge-Kutta-Fehlberg 4(5) pair. Six stages, 4th order propagation with\n5th order error estimate.

The historically first widely-used embedded pair for automatic step-size\ncontrol. The 4th order solution is propagated; the difference to the 5th\norder solution provides a local error estimate.

Characteristics

Order: 4 (propagating) / 5 (error estimate)
Stages: 6
Explicit, adaptive timestep

Note

Largely superseded by the Dormand-Prince (RKDP54) and Cash-Karp\n(RKCK54) pairs, which achieve better accuracy per function evaluation\non most problems. Still useful for reproducing legacy results or when\ncomparing against published benchmarks that used RKF45.

References

\n\n\n\n\n\n

[1]	Fehlberg, E. (1969). "Low-order classical Runge-Kutta formulas\nwith stepsize control and their application to some heat transfer\nproblems". NASA Technical Report TR R-315.

\n\n\n\n\n\n

[2]	Fehlberg, E. (1970). "Klassische Runge-Kutta-Formeln vierter und\nniedrigerer Ordnung mit Schrittweiten-Kontrolle und ihre Anwendung\nauf Wärmeleitungsprobleme". Computing, 6(1-2), 61-71.\ndoi:10.1007/BF02241732

\n", "source": null, "bases": [ "fastsim._fastsim.RKF45" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "RKCK54", "description": "Cash-Karp 5(4) pair. Six stages, 5th order with embedded 4th order", "docstring_html": "

Cash-Karp 5(4) pair. Six stages, 5th order with embedded 4th order\nerror estimate.

Designed to improve on the stability properties of the Fehlberg pair\n(RKF45) while keeping the same stage count.

Characteristics

Order: 5 (propagating) / 4 (embedded)
Stages: 6
Explicit, adaptive timestep

Note

Comparable to RKDP54 in cost and accuracy for most non-stiff block\ndiagrams. Can exhibit slightly better stability on problems with\neigenvalues near the imaginary axis. Both pairs are solid 5th order\nchoices; RKDP54 is the more commonly used default.

References

\n\n\n\n\n\n

[1]	Cash, J. R., & Karp, A. H. (1990). "A variable order Runge-Kutta\nmethod for initial value problems with rapidly varying right-hand\nsides". ACM Transactions on Mathematical Software, 16(3), 201-222.\ndoi:10.1145/79505.79507

\n\n\n\n\n\n

[2]	Hairer, E., Nørsett, S. P., & Wanner, G. (1993). "Solving\nOrdinary Differential Equations I: Nonstiff Problems". Springer\nSeries in Computational Mathematics, Vol. 8.\ndoi:10.1007/978-3-540-78862-1

\n", "source": null, "bases": [ "fastsim._fastsim.RKCK54" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "RKDP54", "description": "Dormand-Prince 5(4) pair (DOPRI5). Seven stages, 5th order with", "docstring_html": "

Dormand-Prince 5(4) pair (DOPRI5). Seven stages, 5th order with\nembedded 4th order error estimate.

The industry-standard adaptive explicit solver and the basis of MATLAB's\node45. Has the FSAL property (not exploited in this implementation,\nso all seven stages are evaluated each step).

Characteristics

Order: 5 (propagating) / 4 (embedded)
Stages: 7
Explicit, adaptive timestep

Note

Recommended default for non-stiff block diagrams. Handles smooth\nnonlinear dynamics, coupled oscillators, and signal-processing chains\nefficiently. If the simulation warns about excessive step rejections or\nvery small timesteps, the system is likely stiff and an implicit solver\n(ESDIRK43, GEAR52A) should be used instead. For very tight\ntolerances on smooth problems, RKV65 or RKDP87 can be more\nefficient per unit accuracy.

References

\n\n\n\n\n\n

[1]	Dormand, J. R., & Prince, P. J. (1980). "A family of embedded\nRunge-Kutta formulae". Journal of Computational and Applied\nMathematics, 6(1), 19-26.\ndoi:10.1016/0771-050X(80)90013-3

\n\n\n\n\n\n

[2]	Shampine, L. F., & Reichelt, M. W. (1997). "The MATLAB ODE\nSuite". SIAM Journal on Scientific Computing, 18(1), 1-22.\ndoi:10.1137/S1064827594276424

\n", "source": null, "bases": [ "fastsim._fastsim.RKDP54" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "RKV65", "description": "Verner 6(5) \"most robust\" pair. Nine stages, 6th order with", "docstring_html": "

Verner 6(5) "most robust" pair. Nine stages, 6th order with\nembedded 5th order error estimate.

Characteristics

Order: 6 (propagating) / 5 (embedded)
Stages: 9
Explicit, adaptive timestep

Note

Fills the gap between 5th order pairs (RKDP54) and the expensive 8th\norder RKDP87. The extra stages pay off when the dynamics are smooth\nand tolerances are tight (roughly 10^{-8} or below), because the\nhigher order allows much larger steps. For tolerances in the\n10^{-4}--10^{-6} range, RKDP54 is usually cheaper\noverall due to fewer stages.

References

\n\n\n\n\n\n

[1]	Verner, J. H. (2010). "Numerically optimal Runge-Kutta pairs\nwith interpolants". Numerical Algorithms, 53(2-3), 383-396.\ndoi:10.1007/s11075-009-9290-3

\n\n\n\n\n\n

[2]	Hairer, E., Nørsett, S. P., & Wanner, G. (1993). "Solving\nOrdinary Differential Equations I: Nonstiff Problems". Springer\nSeries in Computational Mathematics, Vol. 8.\ndoi:10.1007/978-3-540-78862-1

\n", "source": null, "bases": [ "fastsim._fastsim.RKV65" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "RKF78", "description": "Runge-Kutta-Fehlberg 7(8) pair. Thirteen stages, 7th order propagation", "docstring_html": "

Runge-Kutta-Fehlberg 7(8) pair. Thirteen stages, 7th order propagation\nwith 8th order error estimate.

Characteristics

Order: 7 (propagating) / 8 (error estimate)
Stages: 13
Explicit, adaptive timestep

Note

One of the earliest very-high-order embedded pairs. At the same stage\ncount, the Dormand-Prince pair (RKDP87) generally provides better\nerror constants. Consider RKDP87 for new work unless Fehlberg-pair\ncompatibility is required.

References

\n\n\n\n\n\n

[1]	Fehlberg, E. (1968). "Classical fifth-, sixth-, seventh-, and\neighth-order Runge-Kutta formulas with stepsize control". NASA\nTechnical Report TR R-287.

\n\n\n\n\n\n

[2]	Hairer, E., Nørsett, S. P., & Wanner, G. (1993). "Solving\nOrdinary Differential Equations I: Nonstiff Problems". Springer\nSeries in Computational Mathematics, Vol. 8.\ndoi:10.1007/978-3-540-78862-1

\n", "source": null, "bases": [ "fastsim._fastsim.RKF78" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "RKDP87", "description": "Dormand-Prince 8(7) pair (DOP853). Thirteen stages, 8th order with", "docstring_html": "

Dormand-Prince 8(7) pair (DOP853). Thirteen stages, 8th order with\nembedded 7th order error estimate.

The highest-order general-purpose explicit pair in this library. Has the\nFSAL property (not exploited in this implementation).

Characteristics

Order: 8 (propagating) / 7 (embedded)
Stages: 13
Explicit, adaptive timestep

Note

Only worthwhile when the dynamics are very smooth and tolerances are\nextremely tight (roughly 10^{-10} or below). The 13 function\nevaluations per step are expensive, but the 8th order convergence means\nthe step size can be much larger than with lower-order methods at the\nsame error. Suitable for generating reference solutions to validate other\nsolvers in a block diagram. For typical engineering tolerances\n(10^{-4}--10^{-8}), RKDP54 or RKV65 are more\nefficient.

References

\n\n\n\n\n\n

[1]	Prince, P. J., & Dormand, J. R. (1981). "High order embedded\nRunge-Kutta formulae". Journal of Computational and Applied\nMathematics, 7(1), 67-75.\ndoi:10.1016/0771-050X(81)90010-3

\n\n\n\n\n\n

[2]	Hairer, E., Nørsett, S. P., & Wanner, G. (1993). "Solving\nOrdinary Differential Equations I: Nonstiff Problems". Springer\nSeries in Computational Mathematics, Vol. 8.\ndoi:10.1007/978-3-540-78862-1

\n", "source": null, "bases": [ "fastsim._fastsim.RKDP87" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "DIRK2", "description": "Two-stage, 2nd order DIRK method. L-stable, SSP-optimal, symplectic.", "docstring_html": "

Two-stage, 2nd order DIRK method. L-stable, SSP-optimal, symplectic.

Characteristics

Order: 2
Stages: 2 (implicit)
Fixed timestep
L-stable, SSP-optimal, symplectic

Note

The simplest multi-stage implicit Runge-Kutta method. L-stability\nfully damps parasitic high-frequency modes, and the symplectic property\npreserves Hamiltonian structure when the dynamics are conservative. Two\nimplicit stages per step is relatively cheap. For higher accuracy on\nstiff systems, use DIRK3 or the adaptive ESDIRK43.

References

\n\n\n\n\n\n

[1]	Ferracina, L., & Spijker, M. N. (2008). "Strong stability of\nsingly-diagonally-implicit Runge-Kutta methods". Applied Numerical\nMathematics, 58(11), 1675-1686.\ndoi:10.1016/j.apnum.2007.10.004

\n\n\n\n\n\n

[2]	Hairer, E., & Wanner, G. (1996). "Solving Ordinary Differential\nEquations II: Stiff and Differential-Algebraic Problems". Springer\nSeries in Computational Mathematics, Vol. 14.\ndoi:10.1007/978-3-642-05221-7

\n", "source": null, "bases": [ "fastsim._fastsim.DIRK2" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "DIRK3", "description": "Four-stage, 3rd order L-stable DIRK method. Stiffly accurate.", "docstring_html": "

Four-stage, 3rd order L-stable DIRK method. Stiffly accurate.

L-stability (|R(\\infty)| = 0) fully damps parasitic\nhigh-frequency modes. The stiffly accurate property ensures the last\nstage equals the step output, which is beneficial for\ndifferential-algebraic systems.

Characteristics

Order: 3
Stages: 4 (implicit)
Fixed timestep
L-stable, stiffly accurate

Note

A robust fixed-step solver for stiff block diagrams. L-stability makes\nit well-suited for systems with widely separated time scales, such as a\nfast electrical subsystem driving a slow thermal or mechanical model.\nAlso used internally as the startup method for BDF solvers. For\nadaptive stepping on stiff problems, prefer ESDIRK43.

References

\n\n\n\n\n\n

[1]	Alexander, R. (1977). "Diagonally implicit Runge-Kutta methods\nfor stiff O.D.E.'s". SIAM Journal on Numerical Analysis, 14(6),\n1006-1021. doi:10.1137/0714068

\n\n\n\n\n\n

[2]	Hairer, E., & Wanner, G. (1996). "Solving Ordinary Differential\nEquations II: Stiff and Differential-Algebraic Problems". Springer\nSeries in Computational Mathematics, Vol. 14.\ndoi:10.1007/978-3-642-05221-7

\n", "source": null, "bases": [ "fastsim._fastsim.DIRK3" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "ESDIRK4", "description": "Six-stage, 4th order ESDIRK method. L-stable and stiffly accurate.", "docstring_html": "

Six-stage, 4th order ESDIRK method. L-stable and stiffly accurate.

No embedded error estimator; fixed timestep only.

Characteristics

Order: 4
Stages: 6 (1 explicit, 5 implicit)
Fixed timestep
L-stable, stiffly accurate
Stage order 2

Note

Provides 4th order accuracy on stiff block diagrams when the timestep is\npredetermined (e.g. real-time or hardware-in-the-loop contexts). The\nexplicit first stage reuses the last function evaluation from the\nprevious step, saving one implicit solve per step compared to a fully\nimplicit DIRK. L-stability and stiff accuracy ensure full damping of\nparasitic high-frequency modes. For adaptive stepping, use ESDIRK43\nwhich adds an embedded error estimator at the same stage count.

References

\n\n\n\n\n\n

[1]	Kennedy, C. A., & Carpenter, M. H. (2016). "Diagonally implicit\nRunge-Kutta methods for ordinary differential equations. A\nreview". NASA/TM-2016-219173.

\n\n\n\n\n\n

[2]	Hairer, E., & Wanner, G. (1996). "Solving Ordinary Differential\nEquations II: Stiff and Differential-Algebraic Problems". Springer\nSeries in Computational Mathematics, Vol. 14.\ndoi:10.1007/978-3-642-05221-7

\n", "source": null, "bases": [ "fastsim._fastsim.ESDIRK4" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "ESDIRK32", "description": "Four-stage, 3rd order ESDIRK method with embedded 2nd order error", "docstring_html": "

Four-stage, 3rd order ESDIRK method with embedded 2nd order error\nestimate. L-stable and stiffly accurate.

Characteristics

Order: 3 (propagating) / 2 (embedded)
Stages: 4 (1 explicit, 3 implicit)
Adaptive timestep
L-stable, stiffly accurate
Stage order 2 (\\gamma = 1/2)

Note

The cheapest adaptive implicit Runge-Kutta solver in this library,\nyet remarkably robust. L-stability and stiff accuracy guarantee that\nhigh-frequency parasitic modes are fully damped regardless of\ntimestep, and the optimal stage order of 2 (from \\gamma = 1/2)\nminimises order reduction on stiff problems. Three implicit stages\nper step keeps the cost well below ESDIRK43 while still providing\nadaptive step-size control. For even lower per-step cost the\nGEAR multistep solvers require only one implicit solve per step.\nAlso used internally as the startup method for GEAR solvers.

References

\n\n\n\n\n\n

[1]	Kennedy, C. A., & Carpenter, M. H. (2019). "Diagonally implicit\nRunge-Kutta methods for stiff ODEs". Applied Numerical\nMathematics, 146, 221-244.\ndoi:10.1016/j.apnum.2019.07.008

\n\n\n\n\n\n

[2]	Hairer, E., & Wanner, G. (1996). "Solving Ordinary Differential\nEquations II: Stiff and Differential-Algebraic Problems". Springer\nSeries in Computational Mathematics, Vol. 14.\ndoi:10.1007/978-3-642-05221-7

\n", "source": null, "bases": [ "fastsim._fastsim.ESDIRK32" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "ESDIRK43", "description": "Six-stage, 4th order ESDIRK method with embedded 3rd order error", "docstring_html": "

Six-stage, 4th order ESDIRK method with embedded 3rd order error\nestimate. L-stable and stiffly accurate.

Characteristics

Order: 4 (propagating) / 3 (embedded)
Stages: 6 (1 explicit, 5 implicit)
Adaptive timestep
L-stable, stiffly accurate
Stage order 2

Note

Recommended default for stiff block diagrams. L-stability damps\nhigh-frequency parasitic modes that arise from stiff subsystems (e.g.\nPID controllers with large derivative gain, fast electrical or chemical\ndynamics). The adaptive step-size control concentrates computational\neffort where the solution changes rapidly. For non-stiff systems,\nRKDP54 avoids the implicit solve cost and is more efficient. For\ntighter tolerances on stiff problems, ESDIRK54 provides 5th order\naccuracy.

References

\n\n\n\n\n\n

[1]	Kennedy, C. A., & Carpenter, M. H. (2019). "Diagonally implicit\nRunge-Kutta methods for stiff ODEs". Applied Numerical\nMathematics, 146, 221-244.\ndoi:10.1016/j.apnum.2019.07.008

\n\n\n\n\n\n

[2]	Hairer, E., & Wanner, G. (1996). "Solving Ordinary Differential\nEquations II: Stiff and Differential-Algebraic Problems". Springer\nSeries in Computational Mathematics, Vol. 14.\ndoi:10.1007/978-3-642-05221-7

\n", "source": null, "bases": [ "fastsim._fastsim.ESDIRK43" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "ESDIRK54", "description": "Seven-stage, 5th order ESDIRK method with embedded 4th order error", "docstring_html": "

Seven-stage, 5th order ESDIRK method with embedded 4th order error\nestimate. L-stable and stiffly accurate (ESDIRK5(4)7L[2]SA2).

Characteristics

Order: 5 (propagating) / 4 (embedded)
Stages: 7 (1 explicit, 6 implicit)
Adaptive timestep
L-stable, stiffly accurate
Stage order 2

Note

The highest-accuracy L-stable single-step solver in this library before\nthe much more expensive ESDIRK85. Use when tight tolerances are\nneeded on a stiff block diagram (e.g. multi-rate systems combining fast\nelectrical and slow thermal dynamics). At moderate tolerances,\nESDIRK43 achieves similar results with fewer implicit solves per\nstep.

References

\n\n\n\n\n\n

[1]	Kennedy, C. A., & Carpenter, M. H. (2019). "Diagonally implicit\nRunge-Kutta methods for stiff ODEs". Applied Numerical\nMathematics, 146, 221-244.\ndoi:10.1016/j.apnum.2019.07.008

\n\n\n\n\n\n

[2]	Hairer, E., & Wanner, G. (1996). "Solving Ordinary Differential\nEquations II: Stiff and Differential-Algebraic Problems". Springer\nSeries in Computational Mathematics, Vol. 14.\ndoi:10.1007/978-3-642-05221-7

\n", "source": null, "bases": [ "fastsim._fastsim.ESDIRK54" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "GEAR52A", "description": "Variable-step, variable-order BDF (orders 2--5). Adapts both timestep", "docstring_html": "

Variable-step, variable-order BDF (orders 2--5). Adapts both timestep\nand order automatically.

At each step the error controller compares estimates from orders\nn-1 and n+1 and selects the order that minimises the\nnormalised error, allowing larger steps. Analogous to MATLAB's\node15s. Uses ESDIRK32 as startup solver.

Characteristics

Order: variable, 2--5
Implicit variable-step, variable-order multistep
Adaptive timestep and order
Stability: A-stable at order 2, A(\\alpha)-stable at orders 3--5

Note

The most autonomous stiff solver in this library. Automatically selects\nhigher orders in smooth regions for larger steps and drops to low order\nin stiff or transient regions for stability. A good default when the\ncharacter of the block diagram is unknown or changes during the\nsimulation (e.g. switching events, varying loads).

References

\n\n\n\n\n\n

[1]	Gear, C. W. (1971). "Numerical Initial Value Problems in Ordinary\nDifferential Equations". Prentice-Hall.

\n\n\n\n\n\n

[2]	Shampine, L. F., & Reichelt, M. W. (1997). "The MATLAB ODE\nSuite". SIAM Journal on Scientific Computing, 18(1), 1-22.\ndoi:10.1137/S1064827594276424

\n\n\n\n\n\n

[3]	Hairer, E., & Wanner, G. (1996). "Solving Ordinary Differential\nEquations II: Stiff and Differential-Algebraic Problems". Springer\nSeries in Computational Mathematics, Vol. 14.\ndoi:10.1007/978-3-642-05221-7

\n", "source": null, "bases": [ "fastsim._fastsim.GEAR52A" ], "methods": [], "attributes": [], "parameters": [] }, { "name": "SteadyState", "description": "Pseudo-solver for computing the DC operating point (steady state).", "docstring_html": "

Pseudo-solver for computing the DC operating point (steady state).

Solves f(x, u, t) = 0 by iterating the fixed-point map\nx \\leftarrow x + f(x, u, t) using the internal optimizer\n(Newton-Anderson). Not a time-stepping method.

Characteristics

Purpose: find \\dot{x} = 0
Implicit (uses optimizer)
No time integration

Note

Used by Simulation.steady_state() to initialise block diagrams at\ntheir equilibrium before a transient run. Particularly useful when\ndynamic blocks (Integrator, ODE, LTI) have non-trivial\nequilibria that depend on the surrounding algebraic network.

\n", "source": null, "bases": [ "fastsim._fastsim.SteadyState" ], "methods": [], "attributes": [], "parameters": [] } ], "functions": [] } } }