Continuous Integrator

Shippingstateful

integrator_continuous

Continuous state block: integrates dx/dt into state x inside a Simulation compound

Signature

Inputs

derivativeSignal|Scalarrequired— The rate of change dx/dt collected by the solver each minor step.
resetSignal|Scalar— Optional external reset event. Unwired = the integrator never resets.

Outputs

stateSignal|Array— The current continuous state x (the integrated trajectory). Rank-1 Array for a vector state.

Parameters

Key	Type	Default	Notes
`initial_value`	float	0.0	State at t0, x(t0) — a physical quantity (value ± σ, unit). An ARRAY literal (e.g. "[1, 0, -1]") makes this a VECTOR state, integrated element-wise — one integrator for a whole 2D/3D Kepler / N-body / state-space system.
`unit`	unit		Physical unit of the integrated state. Leave BLANK to auto-derive it from the dynamics — the state's unit is derivative_unit × time_unit (∫ velocity m/s over seconds ⇒ position m). Set only to override that.
`initial_value_sigma`	float	0.0	Absolute Gaussian standard uncertainty of the initial condition (0 = exact). When > 0 the solver propagates this ±σ through the dynamics via forward sensitivity, so the trajectory returns with a confidence band.
`reset_factor`	float	0.0	Legacy event reset: when an event wired to `reset` fires, state ← reset_factor × state. Use a NEGATIVE value to reflect — e.g. -0.8 for a bouncing ball with restitution 0.8. Honoured only when Reset Mode is None.
`limit_output`	boolean	false	Clamp the state to [Lower Limit, Upper Limit]. While the state sits at a bound and its derivative would push further out, the derivative is zeroed — so the integral does not wind up past the limit (the classic limited integrator).
`upper_limit`	float	infstate unit	Upper saturation bound for the state. Blank / ∞ ⇒ no upper clamp. Active only when Limit Output is on.
`lower_limit`	float	-infstate unit	Lower saturation bound for the state. Blank / −∞ ⇒ no lower clamp. Active only when Limit Output is on.
`wrap_state`	boolean	false	Keep the state inside [Wrapped Lower, Wrapped Upper) by wrapping it by the span each step — e.g. an angle stays in [−π, π) instead of growing without bound. Use instead of Limit Output, not with it.
`wrap_upper`	float	pi	Upper wrap bound (exclusive). Accepts the symbol `pi` for π. Active only when Wrap State is on.
`wrap_lower`	float	-pi	Lower wrap bound (inclusive). Accepts the symbol `-pi` for −π. Active only when Wrap State is on.
`reset_mode`	enum	none	one of: none, rising, falling, either, level, level_hold
`state_name`	text		Optional name for this state (e.g. 'position') — labels it in traces and exported channels. Blank uses the node's own name.
`abs_tol`	float	auto	Per-state absolute tolerance for the adaptive solver's error control. Blank ⇒ auto (the simulation's global absolute tolerance). Smaller = resolve THIS state more tightly, larger = relax it.

Description

Continuous Integrator is the core state block of Captyse's dynamic-simulation engine. Its output state is the current continuous state $x$ , its input derivative is $\overset{x}{˙} = d x / d t$ , and the initial_value param is $x (t_{0})$ . Inside a compound whose execution_mode = Simulation, the sim engine owns this block: each solver minor-step it seeds the output $= x$ , collects the input $= \overset{x}{˙}$ , and advances $x$ with the chosen solver (Euler … RK4 … adaptive ode45 … BDF).

Wiring the state output back into a formula that computes derivative closes the ODE loop — that feedback cycle is the differential equation. A spring–mass–damper, a pendulum, RC decay, Lorenz, predator–prey, or a full $N$ -body system are all just Integrator(s) plus the algebra of their dynamics.

The initial condition is a full physical quantity: it carries a unit and an optional Gaussian $\sigma$. With $σ > 0$ the solver runs forward sensitivity alongside the state so the trajectory returns with a confidence band. The state's unit is normally auto-derived as $derivative unit \times time unit$ (integrating $m/s$ over seconds yields $m$ ); set unit only to override.

An array literal initial value (e.g. [1, 0, -1]) promotes the block to a vector state integrated element-wise — one node for an entire 2-D/3-D or state-space system, output as a rank-1 Array.

Three bounding behaviors are built in: Limit Output (a true limited integrator that zeroes the pushing derivative at a bound to prevent wind-up), Wrap State (keep an angle in $[- π, π)$ ), and the reset input (edge/level reset to the IC, or the legacy scale-by-Reset-Factor for restitution). Pairing a hit_crossing event into reset gives an exact bouncing ball.

Outside a Simulation compound the block degrades gracefully to a benign leaf source that simply emits $x (t_{0})$ (it cannot integrate without the solver's time loop), so the node renders and runs everywhere.

Mathematics

x (t) = x (t_{0}) + \int_{t_{0}}^{t} \overset{x}{˙} (τ) d τ

unit (x) = unit (\overset{x}{˙}) \times unit (t) (auto-derived when blank)

Limited: while x = x_{m a x} and \overset{x}{˙} > 0, \overset{x}{˙} \leftarrow 0 (anti-windup clamp)

Reset (factor): on event, x \leftarrow k x, k = reset_factor

Examples

Spring–mass–damper (second-order ODE)

Model $m \overset{x}{¨} + c \overset{x}{˙} + k x = 0$ with two integrators. Integrator A holds velocity $v$ (IC $v_{0}$ ), integrator B holds position $x$ (IC $x_{0}$ ). Wire $v$ → B's derivative, and a formula computing $\overset{v}{˙} = - (c v + k x) / m$ → A's derivative. Run the compound in Simulation mode: the state trajectories are the damped oscillation.

Bouncing ball with restitution

One integrator for height $y$ (IC = drop height), one for vertical velocity $v$ with derivative $- g$ . Feed $y$ into a hit_crossing (level $0$ , Falling) and wire its event into the velocity integrator's reset with reset_factor = -0.8. On the adaptive solver the crossing time is localized exactly and $v \leftarrow - 0.8 v$ , so the ball bounces at the floor instead of tunneling through it.

Vector state — planar orbit in one node

Set initial_value to [1, 0, 0, 1] (position $x, y$ and velocity $v_{x}, v_{y}$ ). A single integrator now advances the whole 4-vector element-wise; the formula on its derivative computes the Kepler acceleration. Output is a rank-1 Array of the full state.

Applications

Solving ODEs/state-space dynamics on the canvas: oscillators, RC/RL circuits, thermal decay, chemical kinetics, control-plant simulation.
Multi-body and orbital mechanics via a single vector-state integrator (Kepler, N-body, predator–prey).
Bouncing / impact simulations by pairing hit_crossing events into the reset port with a negative reset factor (restitution).
Bounded-state modeling: limited integrators for actuator saturation / anti-windup, and wrapped states for angles and phase.
Uncertainty-aware simulation: propagating an uncertain initial condition (±σ) through the dynamics to get a trajectory confidence band.

Neat

The type id and port names live in a single sim allow-list (crate::sim::state_block), so the validator and the registration can never drift apart — the node is state-bearing by membership, not by being a special node type.

The limited-integrator anti-windup is exact: at a saturation bound the outward-pushing derivative is zeroed on both the fixed and adaptive solvers, so the integral cannot accumulate past the clamp.

±σ on the initial condition is not a Monte-Carlo add-on — the solver carries forward-sensitivity equations alongside the state, so the returned trajectory band is analytic, not sampled.

The same node body doubles as a benign acyclic leaf source (emits x(t₀)) so a simulation block stays renderable and runnable even outside a Simulation compound.

Known issues

Outside a `execution_mode = Simulation` compound there is no solver time loop, so the node cannot integrate — it only emits the initial value.

The legacy scale-by-Reset-Factor event reset is honoured ONLY when Reset Mode is None; selecting an edge/level Reset Mode ignores reset_factor.

Limit Output and Wrap State are mutually exclusive in practice — enable one, not both.

Per-element σ is scalar-only: a VECTOR (array) state carries no per-component uncertainty band.