Skip to main content

BlockKind

Enum BlockKind 

Source
pub enum BlockKind {
Show 36 variants Const(ConstValue), Time, Pwc { points: Vec<(f64, f64)>, repeat: bool, }, Pwl { points: Vec<(f64, f64)>, repeat: bool, }, Waveform(TransientFunction), Sum(Vec<f64>), Gain(GainValue), Pid { pid: Pid, clamp: PidClamp, }, StateSpace(StateSpace), TransferFunction(TransferFunction), DiscreteStateSpace { ss: StateSpace, sample_time: SampleTimeSpec, }, DiscreteTransferFunction { tf: TransferFunction, sample_time: SampleTimeSpec, }, DiscretePid { pid: DiscretePid, clamp: PidClamp, sample_time: SampleTimeSpec, }, Vco(Vco), Pwm { freq_hz: f64, red: f64, fed: f64, output_names: Vec<String>, }, PhaseShiftPwm { osc: Vco, red: f64, fed: f64, output_names: Vec<String>, }, Product, Saturation(f64), Table(Vec<(f64, f64)>), MathFn1(MathFn1), MathFn2(MathFn2), MathFn3(MathFn3), Hysteresis(Hysteresis), LogicGate(LogicOp), SrLatch { priority: LatchPriority, }, FlipFlop { kind: FlipFlopKind, reset: bool, }, Counter { up_down: bool, modulus: Option<u32>, reset: bool, }, CScript { lib: PathBuf, output_names: Vec<String>, sample_time: Option<SampleTimeSpec>, xc_count: usize, }, PyBlock { path: PathBuf, output_names: Vec<String>, sample_time: Option<SampleTimeSpec>, xc_count: usize, }, PyFunction { path: PathBuf, function: String, output_names: Vec<String>, sample_time: Option<SampleTimeSpec>, }, OctFunc { path: PathBuf, function: String, output_names: Vec<String>, sample_time: Option<SampleTimeSpec>, }, OctBlock { path: PathBuf, function: String, output_names: Vec<String>, sample_time: Option<SampleTimeSpec>, xc_count: usize, }, CoordinateTransform { kind: CoordinateTransform, output_names: Vec<String>, }, Pmsm { pmsm: Pmsm, output_names: Vec<String>, }, Phys2Sig(Phys2SigTarget), Sig2Phys { domain: PhysicalDomain, },
}
Expand description

One block’s behavior. Const/Pwc/Pwl/Sin/Pulse/Exp/Sffm are sources (zero inputs); Sum/Gain are stateless (recomputed fresh from their inputs every step); Pid/StateSpace/TransferFunction/Vco carry their own state forward across steps.

Variants§

§

Const(ConstValue)

§Constant

Purpose: a fixed reference value — a setpoint, bias, or offset that doesn’t vary with time. Library: Sources

§Description

A fixed value, independent of time: a scalar (value=5) or a fixed vector (value=[1,2,3], a Python-list literal). No inputs, no state, nothing to evaluate per step. The vector form exists specifically to feed the vector-aware math blocks — a per-element offset into a vector Sum, or a matrix Gain’s input.

§Parameters
  • value=<f64> — a plain number (the scalar form).
  • value=[x1,x2,...] — a Python-style list literal (the vector form). Entries must be finite: nan/inf are rejected at parse time, since a NaN would otherwise silently propagate into downstream sorts/comparisons and panic the process.
§Errors
  • value=abc (scalar not a number) — rejected at parse time: field 'value' is not a number.
  • value=[1,x,3] (vector entry not a number) — rejected at parse time: field 'value' entry 'x' is not a number.
  • value=[1,nan,3] (non-finite vector entry) — rejected at parse time: field 'value' entry 'nan' must be a finite number (got NaN).
  • A missing value= is the generic missing field 'value' error every kind= block shares — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=const value=<f64> | value=[x1,x2,...]
§Example

A scalar setpoint and a constant vector offset, unchanged at every step:

SETPOINT kind=const value=5
OFFSETS kind=const value=[1,2,3]
§

Time

§Time

Purpose: the current simulated time as a signal — the block-diagram “clock” source. Library: Sources

§Description

Outputs the current step’s own simulated time in seconds. Takes no fields and no inputs. Its job is building genuine time-varying signals out of the stateless math blocks: there is otherwise no way for a block to see t directly (pwc/pwl/waveform’s own use of time is internal to those blocks alone). The standard sin(2*pi*f*t) recipe is time -> gain(k=2*pi*f) -> sin — see the Example.

§Parameters

None — kind=time takes no fields at all.

§Errors

None — there is nothing component-specific to get wrong beyond the generic unknown device kind error for a misspelled kind.

§Netlist form
NAME kind=time
§Example

A 1 kHz sine wave built entirely from ordinary blocks (6283.185307179586 is 2*pi*1000):

T kind=time
G kind=gain in=T k=6283.185307179586
S kind=sin in=G
§

Pwc

§Piecewise-Constant Source (pwc)

Purpose: a time schedule that holds a constant value between its breakpoints — reference schedules and step tests. Library: Sources

§Description

A piecewise-constant function of time: the value is the last breakpoint’s value at or before t (the first point’s value before it, the last point’s value forever after). Two points make a step test; more points make an arbitrary staircase schedule. With repeat=true, t wraps into [points[0].0, points[last].0) (period = last time − first time) once past the last point, making a periodic square/staircase waveform — a repeating list needs a final point back at the value the cycle starts from, since the wrapped t lands in [first, last) and never reaches the last point’s own value.

Not the same interpolation as BlockKind::Pwl (real SPICE piecewise-linear semantics): this block is named pwc at the CLI level specifically to avoid the ambiguity a shared pwl name would create — pwc holds between breakpoints, pwl interpolates.

§Parameters
  • points=[[t1,v1],[t2,v2],...] — (time, value) breakpoints as a Python list of 2-element lists. Sorted ascending by t at parse time, so declaration order doesn’t matter.
  • repeat=true — optional (default: hold flat past the last point); wraps t into the breakpoint span as above. Matched exactly: any other spelling (including True) means no repeat.
§Errors
  • A points= entry that is not a 2-element [x,y] list — rejected at parse time: field 'points': each entry must be a 2-element '[x,y]' list (got '[1.0]').
  • points=abc (not a Python list at all) — rejected at parse time: field 'points' must be a Python-style list, e.g. '[1,2,3]' or '[[1,2],[3,4]]' (got 'abc').
  • A missing points= is the generic missing field 'points' error — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=pwc points=[[t1,v1],[t2,v2],...] [repeat=true]
§Example

A step test at t = 0.001, and a periodic square wave (period 0.001):

STEP kind=pwc points=[[0,0],[0.001,1]]
SQUARE kind=pwc points=[[0,0],[0.0005,1],[0.001,0]] repeat=true

Fields

§points: Vec<(f64, f64)>

(time, value) breakpoints, in order.

§repeat: bool

If true, wraps t into the breakpoint range instead of holding flat past the last point.

§

Pwl

§Piecewise-Linear Source (pwl)

Purpose: a time waveform linearly interpolated between breakpoints — real SPICE PWL semantics in the signal domain. Library: Sources

§Description

A piecewise-linear function of time: linear interpolation between breakpoints, held at the first/last point’s value before/after the breakpoint range — exactly TransientFunction::Pwl’s own electrical-domain behavior, so the same breakpoint list means the same waveform whether it drives a V/I source directly or a signal-domain reference through this block. With repeat=true, t wraps into [points[0].0, points[last].0) (period = last time − first time) once past the last point — the electrical-domain PWL source has no such option, so a genuinely periodic piecewise-linear waveform (a triangle/sawtooth reference, a repeating ramp) is only available here in the signal domain. Not the same interpolation as BlockKind::Pwc (piecewise-constant): pwl interpolates, pwc holds.

§Parameters
  • points=[[t1,v1],[t2,v2],...] — (time, value) breakpoints as a Python list of 2-element lists. Sorted ascending by t at parse time, so declaration order doesn’t matter.
  • repeat=true — optional (default: hold flat past the last point); wraps t into the breakpoint span as above. Matched exactly: any other spelling (including True) means no repeat.
§Errors
  • A points= entry that is not a 2-element [x,y] list — rejected at parse time: field 'points': each entry must be a 2-element '[x,y]' list (got '[1.0]').
  • points= not a Python list at all — rejected at parse time with the same field 'points' must be a Python-style list, ... error as pwc (shared parser — see the pwc entry).
  • A missing points= is the generic missing field 'points' error — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=pwl points=[[t1,v1],[t2,v2],...] [repeat=true]
§Example

A ramp to 1, and a periodic triangle (period 0.001):

RAMP kind=pwl points=[[0,0],[0.001,1]]
TRI kind=pwl points=[[0,0],[0.0005,1],[0.001,0]] repeat=true

Fields

§points: Vec<(f64, f64)>

(time, value) breakpoints, in order.

§repeat: bool

If true, wraps t into the breakpoint range instead of holding flat past the last point.

§

Waveform(TransientFunction)

§Waveform Sources (sinwave / pulsewave / expwave / sffmwave)

Purpose: the electrical domain’s four non-PWL time-varying source forms, reusable as zero-input signal references. Library: Sources

§Description

One of TransientFunction’s four non-Pwl variants, reused directly rather than reimplemented: kind=sinwave/pulsewave/expwave/sffmwave take the same field names, order and defaults as SPICE’s SIN()/PULSE()/EXP()/SFFM() sources, so a V/I source and a signal-domain reference built from the same parameters produce bit-for-bit the same waveform (evaluated via TransientFunction::value_at at the current step’s own t). See TransientFunction’s own doc comment for the exact formula each form implements (offset + damped sinusoid, periodic trapezoid, two-stage exponential, single-frequency FM). The fifth form, PWL, is its own block kind here (BlockKind::Pwl) — the only member of the family with the repeat option TransientFunction doesn’t have.

§Parameters
  • sinwave: va=<f64> freq=<f64> required (amplitude; frequency in Hz). Optional: v0=<f64> (0), td=<f64> (0), theta=<f64> (0, exponential damping), phase=<f64> (0, degrees).
  • pulsewave: v1=<f64> v2=<f64> required (low/high levels). Optional: td (0), tr (0), tf (0), pw (default: effectively forever), per (effectively forever). tr/tf of exactly 0 are instantaneous edges.
  • expwave: v1=<f64> v2=<f64> required. Optional: td1 (0), tau1 (1), td2 (effectively never — not td1), tau2 (1).
  • sffmwave: va=<f64> fc=<f64> fs=<f64> required (carrier amplitude, carrier frequency, signal frequency, all Hz/amplitude as in SPICE). Optional: v0 (0), mdi (0, modulation index).
  • An optional field that is present but doesn’t parse as a number silently falls back to its default — td=abc behaves exactly like an omitted td, with no error.
§Errors
  • A required field missing (sinwave without va) — the generic missing field 'va' error (see BlockInstance’s own doc comment).
  • A required field not a number (va=abc) — rejected at parse time: field 'va' is not a number.
§Netlist form
NAME kind=sinwave    va=<f64> freq=<f64> [v0=<f64>] [td=<f64>] [theta=<f64>] [phase=<f64>]
NAME kind=pulsewave  v1=<f64> v2=<f64> [td=<f64>] [tr=<f64>] [tf=<f64>] [pw=<f64>] [per=<f64>]
NAME kind=expwave    v1=<f64> v2=<f64> [td1=<f64>] [tau1=<f64>] [td2=<f64>] [tau2=<f64>]
NAME kind=sffmwave   va=<f64> fc=<f64> fs=<f64> [v0=<f64>] [mdi=<f64>]
§Example

A 1 kHz sinusoid, a delayed 1 kHz square wave, an exponential rise/fall, and an unmodulated FM carrier, all as signal-domain references:

SINREF kind=sinwave va=10 freq=1000
PULSEREF kind=pulsewave v1=0 v2=10 td=0.001 tr=0.0001 tf=0.0001 pw=0.0002 per=0.001
EXPREF kind=expwave v1=0 v2=1 td1=0 tau1=0.0001 td2=0.001 tau2=0.0001
FMREF kind=sffmwave v0=0 va=1 fc=1000 mdi=0 fs=100
§

Sum(Vec<f64>)

§Sum

Purpose: weighted sum of its inputs, one sign per input — e.g. an error junction. Library: Sources / Math operations

§Description

Computes $s_1 x_1 + s_2 x_2 + \dots$ with one sign per input (+1.0/-1.0 for an error junction; any number is allowed, so a weighted average is the same block with fractional signs). Input-shape rule (shared with Product): all-Scalar inputs give a Scalar; otherwise every input must be a Vector of one common length N, reduced elementwise to a Vector(N) — a mix of Scalar and Vector inputs is rejected rather than guessed at (an N-input reduction has no unambiguous placement for a lone scalar once more than one vector is already present).

§Parameters
  • inputs=<sig1,sig2,...> — comma-separated input signals, one per term.
  • signs=<s1,s2,...> — one sign (any number) per input, comma-separated, exactly as many entries as inputs has.
§Errors
  • inputs and signs counts differ — rejected at parse time: 'inputs' has 2 entries but 'signs' has 1 (need one sign per input).
  • A signs entry that is not a number — rejected at parse time: field 'signs' entry 'x' is not a number.
  • Mixed Scalar/Vector inputs — rejected at evaluation time: VectorSignalNotSupported { block: "<name>" }.
  • Vector inputs of differing lengths — rejected at evaluation time: VectorSignalSizeMismatch { block: "<name>", expected: N, got: M }.
  • A missing inputs=/signs= is the generic missing field '<key>' error — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=sum inputs=<sig1,sig2,...> signs=<s1,s2,...>
§Example

An error junction (A - B) and an elementwise vector sum:

A kind=const value=3
B kind=const value=1
ERR kind=sum inputs=A,B signs=1,-1
OA kind=const value=[1,2]
OB kind=const value=[10,20]
VSUM kind=sum inputs=OA,OB signs=1,1
§

Gain(GainValue)

§Gain

Purpose: scales its single input — a plain factor, or a full matrix-vector product. Library: Sources / Math operations

§Description

k as a plain number (Scalar): Scalar -> Scalar (k*x), or Vector(N) -> Vector(N) (every element scaled by k, broadcast). k as a matrix ([[...],[...]], an M x N matrix, row-major matrix[row][col]): requires a Vector input of length exactly N, and outputs Vector(M), the matrix-vector product $K,x$ — the one math block that changes a signal’s length. A flat list (k=[1,2,3]) is not a valid Gain shape at all (unlike Const, Gain’s own value is never itself a vector) and is rejected at parse time.

§Parameters
  • in=<signal> — the single input.
  • k=<f64> — a plain scale factor.
  • k=[[r1...],[r2...],...] — an M x N matrix (Python-style nested list, row-major); the input must be a Vector of length N, the output is Vector(M).
§Errors
  • k=[1,2,3] (flat list) — rejected at parse time: field 'k' must be a scalar (e.g. '2.0') or a matrix (e.g. '[[1,0],[0,1]]') -- got a flat list '[1,2,3]', which is not a valid Gain shape.
  • k=abc — rejected at parse time: field 'k' is not a number.
  • A matrix k with a Scalar input — rejected at evaluation time: VectorSignalNotSupported { block: "<name>" }.
  • A matrix k with a Vector input whose length isn’t N — rejected at evaluation time: VectorSignalSizeMismatch { block: "<name>", expected: N, got: M }.
  • A missing in=/k= is the generic missing field '<key>' error — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=gain in=<signal> k=<f64> | k=[[r1...],[r2...],...]
§Example

A scalar gain and a 2x3 matrix gain fed by a length-3 vector:

IN kind=const value=2
G kind=gain in=IN k=3
V kind=const value=[1,2,3]
M kind=gain in=V k=[[1,0,0],[0,1,0]]
§

Pid

§PID Controller

Purpose: closed-loop error compensation with a filtered derivative and anti-windup. Library: Control / Continuous

§Description

A parallel PID ($C(s) = K_p + \dfrac{K_i}{s} + \dfrac{K_d N s}{s + N}$, filtered-derivative form — see continuous_blocks::Pid’s own doc comment for the transfer-function derivation) with two-sided conditional-integration anti-windup against clamp: while the compensator’s raw (unclamped) output would exceed clamp’s bound, the integral term stops accumulating in the direction that would make the saturation worse, but keeps integrating normally in the direction that would relieve it — so the controller recovers immediately once the error’s sign allows it to, instead of first having to “unwind” a runaway integral term. clamp is this PID’s own notion of “my output is saturated,” independent of whatever downstream Gain/Vco block does to the value afterward — the same role a real PID block’s own configured output limits play.

See PidClamp for the fixed-vs-dynamic choice, which also changes this block’s own input count (one, just the error signal, for Fixed; three — error, clamp_lo, clamp_hi — for Dynamic). Reach for Dynamic specifically when the achievable output range is itself state-dependent (e.g. a current-loop PID commanding a pole voltage that can’t physically exceed roughly half a DC bus voltage that is itself still rising during a soft-start ramp) — a Fixed bound sized for the final steady-state range is badly oversized early on, so anti-windup never engages even though the real plant is already saturated far below that fixed bound, producing sustained, hard-to-diagnose windup-driven oscillation.

§Parameters
  • in=<signal> — the error signal (one input).
  • kp=<f64>, ki=<f64>, kd=<f64> — proportional/integral/derivative gains. No sign or magnitude restriction (a negative gain is a legitimate, if unusual, choice depending on the plant’s own sign convention).
  • n=<f64> — the derivative filter coefficient (the filter pole sits at -n); must be > 0. A larger n tracks the ideal (unrealizable) pure derivative more closely, at the cost of stiffening the resulting ODE.
  • Anti-windup bound, exactly one of:
    • clamp_lo=<f64> clamp_hi=<f64> — fixed bound (PidClamp::Fixed).
    • clamp_lo_in=<signal> clamp_hi_in=<signal> — read fresh from the graph every step (PidClamp::Dynamic), added as two extra inputs after the error signal, in that order.
  • ic=<f64> — optional (default: start from rest); pre-loads the integrator so the controller output starts at this value with zero error — a bumpless start at a known operating point. Resolved through continuous_blocks::TransferFunction::settled_state on this PID’s own transfer function.
§Errors
  • n <= 0.0 — rejected at parse time (invalid PID (NonPositiveFilterCoefficient)): a non-positive filter coefficient puts the derivative filter’s pole at the origin or in the right half-plane, a non-causal or outright unstable filter.
  • Giving only one of clamp_lo_in/clamp_hi_in (not both, and not neither) — rejected at parse time: 'clamp_lo_in'/'clamp_hi_in' must both be given together (dynamic clamp) or both omitted (fixed clamp= clamp_lo/clamp_hi).
  • A missing or non-numeric field (kp/ki/kd/n/clamp_lo/clamp_hi) is the same generic missing field '<key>'/field '<key>' is not a number error every kind= block produces — see BlockInstance’s own doc comment.
  • ic= with ki=0 — rejected at parse time: field 'ic' pre-loads the integrator, but this PID has ki=0 -- there is no integrator to hold it.
§Netlist form
NAME kind=pid in=<signal> kp=<f64> ki=<f64> kd=<f64> n=<f64> \
     (clamp_lo=<f64> clamp_hi=<f64> | clamp_lo_in=<signal> clamp_hi_in=<signal>) [ic=<f64>]
§Example

A fixed-clamp PI (no derivative action) regulating an error signal ERR to [-1, 1]:

PID1 kind=pid in=ERR kp=1 ki=0 kd=0 n=1 clamp_lo=-1 clamp_hi=1

Fields

§pid: Pid

The compiled PID gains/state.

§clamp: PidClamp

The fixed-vs-dynamic anti-windup bound.

§

StateSpace(StateSpace)

§State-Space

Purpose: an arbitrary continuous-time linear block given directly as (A, B, C, D) matrices. Library: Control / Continuous

§Description

A compensator/filter that doesn’t already have a named convenience constructor, e.g. a low-pass filter placed ahead of a Pid to damp a resonant plant: $\dot{x} = Ax + Bu, \quad y = Cx + Du$. Genuinely MIMO: B’s own column count (StateSpace::inputs()) and C‘s own row count (StateSpace::outputs()) are not constrained to 1 — a single-input single-output declaration is simply the 1x1 case. outputs() == 1 produces a SignalValue::Scalar; outputs() > 1 produces a SignalValue::Vector of that length. Inputs are the flattened concatenation of this block’s own declared Signals (scalar or vector, in order) — see evaluate_blocks’/ dae-runtime’s own input-flattening convention, shared with CoordinateTransform/Pmsm/CScript. No anti-windup (that’s specifically a Pid output’s own concern, not every dynamic block’s); stepped forward unconditionally every timestep via StateSpace::rk4_step (RK4, not backward Euler — this block’s own state is never part of the circuit’s own descriptor-DAE solve).

§Parameters
  • a=<matrix> — the n x n dynamics matrix, e.g. a=[[0,1],[-1,-1]].
  • b=<matrix|vector> — n x p (p inputs); a flat vector (b=[1,0]) is SISO shorthand for p=1, matching the pre-vector-signals convention unchanged.
  • c=<matrix|vector> — q x n (q outputs); same flat-vector SISO shorthand for q=1.
  • d=<matrix|scalar> — optional, defaults to an all-zero q x n matrix; a bare scalar is only accepted when q=1 and p=1 (SISO) — a MIMO system must give the full matrix, since a lone scalar has no unambiguous placement in a larger D.
  • in=<signal> (SISO, p must be 1) or inputs=<sig1,...> (exactly p entries, each independently scalar or vector; the flattened total length must equal p, checked at evaluation time, not parse time, since a vector signal’s own arity isn’t knowable from netlist text alone).
  • ic=[x1,...,xn] — optional (default: every state zero); the initial state vector $x(0)$, one entry per state. A bare number (ic=2) is accepted for a one-state system.
§Errors
  • q != 1 || p != 1 with a bare scalar d= — rejected at parse time: field 'd' is a bare scalar, but this system has <q> output(s) and <p> input(s) -- declare 'd=[[...],...]' (<q>x<p>) for a MIMO system, a bare scalar is only valid for a 1x1 (SISO) one.
  • There is no e= (descriptor-matrix) field exposed at the netlist level yet, so StateSpaceError::NonInvertibleDescriptorMatrix (a singular descriptor matrix) is currently unreachable through this parser — e is always None (ordinary, non-descriptor state-space) for every netlist-declared instance.
  • ic= with a number of entries other than the block’s own state count — rejected at parse time: field 'ic' has <m> value(s), but this block has <n> state(s).
§Netlist form
NAME kind=statespace a=<matrix> b=<matrix|vector> c=<matrix|vector> [d=<matrix|scalar>] \
     (in=<signal> | inputs=<sig1,sig2,...>) [ic=<vector>]
§Example

A first-order low-pass ($\dot{x} = -x + u$, $y = x$, pole at $s=-1$) — verified end to end, SRC=1 settling toward SS1=1:

SRC kind=const value=1
SS1 kind=statespace a=[[-1]] b=[1] c=[1] in=SRC
§

TransferFunction(TransferFunction)

§Transfer Function

Purpose: a single-input single-output block given as a rational $N(s)/D(s)$. Library: Control / Continuous

§Description

Numerator/denominator coefficients, highest-degree first, rather than a Pid’s Kp/Ki/Kd convenience parameterization — e.g. a hand-derived PID-with-filtered- derivative compensator ($C(s) = K_p + K_i/s + K_d N s/(s+N)$, put over one denominator first: a pure derivative term alone is non-causal/unrealizable, so every real PID, textbook or otherwise, filters it — see continuous_blocks::Pid::to_transfer_function’s own doc comment for the derivation). Compiled once via TransferFunction::to_state_space (controllable canonical form); no anti-windup, for the same reason BlockKind::StateSpace above has none.

§Parameters
  • num=<vector> — numerator coefficients, highest-degree first, e.g. num=[1,2] for $s + 2$.
  • den=<vector> — denominator coefficients, highest-degree first, e.g. den=[1,3,2] for $s^2 + 3s + 2$. Must be non-empty and nonzero-leading; deg(num) <= deg(den) (a proper transfer function — every realizable continuous-time physical system is).
  • in=<signal> — the single input (one input, always — this block is SISO by definition).
  • ic=[x1,...,xn] — optional (default: every state zero); the initial state of the controllable canonical realization (see continuous_blocks::TransferFunction::to_state_space), $n = \deg(\text{den})$ entries. With the denominator made monic, $x_1$ is the state whose $k$-th derivative is $x_{k+1}$, and the output is $y = \sum_i b_i x_{i+1} + d,u$.
  • y0=<f64> — optional, mutually exclusive with ic=; starts the filter already settled at output $y_0$: $x = (y_0 / N(0), 0, \dots, 0)$ with $N(0)$ the normalized numerator’s constant term (see continuous_blocks::TransferFunction::settled_state). Fed the matching constant input $u = y_0 / G(0)$ the output stays at $y_0$ exactly; a pole at the origin is fine (the matching input is then $0$).
§Errors
  • den=[] (empty) — rejected at parse time: invalid transfer function (EmptyDenominator).
  • den’s first (highest-degree) coefficient is 0.0 — rejected: invalid transfer function (ZeroLeadingDenominatorCoefficient) (a zero leading coefficient means the stated degree is a lie — the true denominator degree is lower).
  • deg(num) > deg(den) (more numerator coefficients than denominator ones) — rejected: invalid transfer function (ImproperTransferFunction) — an improper transfer function has no causal realization.
  • ic= with a number of entries other than the block’s own state count — rejected at parse time: field 'ic' has <m> value(s), but this block has <n> state(s).
  • ic= and y0= both given — rejected at parse time: 'ic' (the state vector) and 'y0' (the settled output) both set an initial condition -- give one or the other.
  • y0= on a transfer function whose numerator is zero at DC — rejected at parse time: field 'y0': this transfer function's numerator is zero at DC, so its settled output is always 0 and no state holds the requested one.
§Netlist form
NAME kind=tf num=<vector> den=<vector> in=<signal> [ic=<vector> | y0=<f64>]
§Example

The same first-order low-pass as StateSpace’s own example ($1/(s+1)$), verified to settle toward the same steady-state value:

SRC kind=const value=1
TF1 kind=tf num=[1] den=[1,1] in=SRC
§

DiscreteStateSpace

§Discrete State-Space

Purpose: the discrete-domain counterpart to StateSpace — a plain linear recursion. Library: Control / Discrete

§Description

$x_{i+1} = Ax_i + Bu_i$, $y_i = Cx_i + Du_i$ — no RK4, no dt at all: A/B/C/D are already discrete-domain matrices, given directly by the netlist author, not derived from continuous ones. sample_time is required here (unlike cscript’s own optional field) and must be periodic — a discrete system’s own dynamics are its sample period, there is no “continuous” fallback the way omitting it means for cscript, and a solver-chosen variable schedule doesn’t compose with a fixed-period recursion at all. See general-simulator’s own book/dev-guide/src/discrete-time-blocks.md.

§Parameters
  • a=/b=/c=/d=/in=/inputs= — identical shape and MIMO rules to BlockKind::StateSpace’s own Parameters (see there); the only difference is these matrices are already discrete-domain.
  • ts=<f64> / freq=<f64> (with optional to=<f64> offset) — required; unlike cscript, ts=variable is not accepted here (see Errors).
  • ic=[x1,...,xn] — optional (default: every state zero); the initial state vector $x_0$, one entry per state (a bare number for a one-state system). With a nonzero sample offset, the output held before the first sample hit is $C,x_0$.
§Errors
  • Same MIMO scalar-d rejection as StateSpace (see there).
  • ts=/freq= missing entirely — rejected at parse time: missing 'ts=' or 'freq=' -- a discrete-time block's own sample period is not optional (its dynamics *are* that period), unlike the optional 'ts='/'freq=' on kind=cscript/pyblock/pyfunc.
  • ts=variable — rejected at parse time: ts=variable is not available here -- a discrete block's own recursion has its coefficients baked in at one fixed sample period, which 'the block decides its own next execution time' doesn't compose with.
  • ic= with a number of entries other than the block’s own state count — rejected at parse time: field 'ic' has <m> value(s), but this block has <n> state(s).
§Netlist form
NAME kind=discretestatespace a=<matrix> b=<matrix|vector> c=<matrix|vector> \
     [d=<matrix|scalar>] (ts=<f64> | freq=<f64> [to=<f64>]) \
     (in=<signal> | inputs=<sig1,sig2,...>) [ic=<vector>]
§Example

A discrete integrator ($x_{i+1} = x_i + 0.1 \cdot u_i$, $y=x$, ts=0.1) fed a constant 1 — verified end to end, DS1 reaching 0.5 after 5 sample hits ($5 \times 0.1$):

SRC kind=const value=1
DS1 kind=discretestatespace a=[[1]] b=[0.1] c=[1] ts=0.1 in=SRC

Fields

§ss: StateSpace

The discrete-domain A/B/C/D matrices.

§sample_time: SampleTimeSpec

Must be SampleTimeSpec::Periodic — a discrete system’s dynamics are its sample period.

§

DiscreteTransferFunction

§Discrete Transfer Function

Purpose: the discrete-domain counterpart to Transfer Function — $Y(z)/U(z) = N(z)/D(z)$. Library: Control / Discrete

§Description

Coefficients already in the $z$-domain. Realized via the exact same TransferFunction::to_state_space the continuous version uses (coefficient-to- companion-form conversion is domain-agnostic algebra — it doesn’t know or care whether the variable is called $s$ or $z$), evaluated via StateSpace::discrete_step instead of rk4_step. Same mandatory-periodic-sample_time rule as BlockKind::DiscreteStateSpace.

§Parameters
  • num=/den=/in= — identical shape and validity rules to BlockKind::TransferFunction’s own Parameters (see there); coefficients are already in the $z$-domain rather than $s$.
  • ts=<f64> / freq=<f64> (with optional to=<f64>) — required, same rule as DiscreteStateSpace.
  • ic=[x1,...,xn] — optional (default: every state zero); the initial state of the same controllable canonical realization as BlockKind::TransferFunction’s own ic=, stepped as a difference equation.
  • y0=<f64> — optional, mutually exclusive with ic=; starts the filter already settled at output $y_0$ — every canonical state equal to $y_0 / N(1)$, with $N(1)$ the normalized numerator evaluated at $z = 1$ (see continuous_blocks::TransferFunction::settled_state_discrete). Fed the matching constant input $u = y_0 / H(1)$ the output stays at $y_0$ exactly.
§Errors

Identical to BlockKind::TransferFunction’s own (EmptyDenominator, ZeroLeadingDenominatorCoefficient, ImproperTransferFunction), plus the same missing-ts=/ts=variable-rejected errors as DiscreteStateSpace.

  • ic= and y0= both given — rejected at parse time: 'ic' (the state vector) and 'y0' (the settled output) both set an initial condition -- give one or the other.
  • y0= on a transfer function whose numerator is zero at DC — rejected at parse time: field 'y0': this transfer function's numerator is zero at DC, so its settled output is always 0 and no state holds the requested one.
§Netlist form
NAME kind=discretetf num=<vector> den=<vector> (ts=<f64> | freq=<f64> [to=<f64>]) in=<signal> \
     [ic=<vector> | y0=<f64>]
§Example

The exact $z$-domain realization of DiscreteStateSpace’s own example above ($Y(z)/U(z) = 0.1/(z-1)$, a discrete integrator) — verified to reach the same DTF1=0.5 after 5 sample hits:

SRC kind=const value=1
DTF1 kind=discretetf num=[0.1] den=[1,-1] ts=0.1 in=SRC

Fields

§tf: TransferFunction

The z-domain numerator/denominator coefficients.

§

DiscretePid

§Discrete PID Controller

Purpose: the discrete-domain counterpart to PID Controller. Library: Control / Discrete

§Description

Reuses the exact same PidClamp anti-windup mechanism as BlockKind::Pid, but the integral/derivative actions advance once per declared sample period via continuous_blocks::DiscretePid::step instead of RK4-integrating continuously. Not built by converting to one combined $z$-domain transfer function and back — realized directly from the block’s own diagram (three parallel branches, summed). Same mandatory-periodic-sample_time rule as DiscreteStateSpace/DiscreteTransferFunction above — this block’s own integration period is set from sample_time, not a separately-entered value.

§Parameters
  • in=<signal>, kp=/ki=/kd=/n=, and the fixed-vs-dynamic clamp fields (clamp_lo=/clamp_hi= or clamp_lo_in=/clamp_hi_in=) — identical meaning to BlockKind::Pid’s own Parameters (see there).
  • ts=<f64> / freq=<f64> (with optional to=<f64>) — required.
  • integration_method=<forward|backward|trapezoidal> — optional, defaults to forward (forward Euler); selects the discrete integration rule the integral term uses each sample period.
  • ic=<f64> — optional (default: start from rest); pre-loads the integrator so the controller output starts at this value with zero error (the integrator’s accumulated value is set to $\text{ic}/k_i$).
§Errors
  • Same n <= 0.0 and clamp-pairing errors as BlockKind::Pid (see there).
  • Same missing-ts=/ts=variable-rejected errors as DiscreteStateSpace.
  • integration_method present but not one of the three known names — rejected at parse time: unknown integration_method '<value>' (expected 'forward', 'backward', or 'trapezoidal').
  • ic= with ki=0 — rejected at parse time: field 'ic' pre-loads the integrator, but this PID has ki=0 -- there is no integrator to hold it.
§Netlist form
NAME kind=discretepid in=<signal> kp=<f64> ki=<f64> kd=<f64> n=<f64> \
     (ts=<f64> | freq=<f64> [to=<f64>]) \
     (clamp_lo=<f64> clamp_hi=<f64> | clamp_lo_in=<signal> clamp_hi_in=<signal>) \
     [integration_method=<forward|backward|trapezoidal>] [ic=<f64>]
§Example

A discrete PI (no derivative action) sampled every 0.1 s, integrating a fixed error signal once per sample hit — verified end to end, DPID1 stepping 0.5 -> 0.525 -> 0.55 -> 0.575 -> 0.6 at each ts=0.1 boundary (unchanged between hits, matching the discrete-recursion contract exactly):

ERR kind=const value=0.5
DPID1 kind=discretepid in=ERR kp=1 ki=0.5 kd=0 n=1 ts=0.1 clamp_lo=-1 clamp_hi=1

Fields

§pid: DiscretePid

The compiled discrete PID gains/state.

§clamp: PidClamp

The fixed-vs-dynamic anti-windup bound.

§sample_time: SampleTimeSpec

Must be SampleTimeSpec::Periodic; also sets pid’s own period.

§

Vco(Vco)

§VCO (Voltage-Controlled Oscillator)

Purpose: a bare, standalone oscillator producing a [0, 1) ramp from a frequency input. Library: Control / Continuous

§Description

A raw frequency-to-ramp conversion, still useful on its own outside gate-driving PWM — e.g. feeding a MathFn1::Sin/Gain chain to build a variable-frequency sinusoidal reference. Not how a gate-driving PWM modulator gets its own switching frequency, though — see BlockKind::Pwm/BlockKind::PhaseShiftPwm below, neither of which reads this block at all (each owns its own internal oscillator).

§Parameters
  • f_min=<f64>, f_max=<f64> — the frequency clamp range, Hz; the one input (in=) is internally clamped to [f_min, f_max] before integration.
  • in=<signal> — the frequency command, Hz (one input).
  • ic=<f64> — optional (default 0); the initial phase, in cycles, $0 \le \text{ic} < 1$.
§Errors
  • f_min > f_max — rejected at parse time: invalid vco (FMinExceedsFMax).
  • ic= outside $0 \le \text{ic} < 1$ — rejected at parse time: field 'ic' is the initial phase in cycles and must satisfy 0 <= ic < 1 (got <value>).
§Netlist form
NAME kind=vco f_min=<f64> f_max=<f64> in=<signal> [ic=<f64>]
§Example

A fixed 10 Hz oscillator, verified to produce a [0,1) ramp (not stuck at a constant):

FREQ kind=const value=10
VCO1 kind=vco f_min=1 f_max=1000 in=FREQ
§

Pwm

§PWM Modulator 1

Purpose: fixed-frequency, duty-driven, active-high complementary PWM. Library: Power Electronics

§Description

One input, duty ([0,1], clamped, read fresh every step from anywhere in the graph — a Pid, a filtered TransferFunction, a plain Const…), fixed carrier frequency freq_hz. Two outputs, following the BlockKind::CScript output_names convention: output_names[0] (aliasing this block’s own .name) is the main signal, output_names[1] its active-high complement. red/fed (seconds) are independent per-edge dead-time delays — see math_ops::complementary_pwm_with_deadtime (in dae-runtime) for the exact rising-edge-only-delay semantics and why red=fed=0.0 recovers the ideal, gap-free, overlap-free pair exactly. Stateless: a pure function of (t, duty) every step, no internal oscillator.

§Parameters
  • freq=<f64> — fixed carrier frequency, Hz.
  • in=<signal> — the duty command, [0,1] (clamped internally; no error for a value outside that range).
  • red=<f64>, fed=<f64> — optional, default 0.0; rising/falling-edge dead time, seconds.
  • outputs=<main,complement> — optional; defaults to <name>,<name>_comp. Exactly 2 entries if given.
§Errors
  • outputs= with a count other than 2 — rejected at parse time: 'outputs' needs exactly 2 entries (main, complement; got <n>).
  • red=/fed= present but not a number — the generic field '<key>' is not a number error.
§Netlist form
NAME kind=pwm freq=<f64> in=<signal> [red=<f64>] [fed=<f64>] [outputs=<main,complement>]
§Example

A 10 kHz, 30% duty modulator with no dead time — verified end to end: PWM1 high (>= 0.99) for the first ~30% of each 100 µs period and its complement exactly inverted, PWM1 + PWM1_comp == 1 at every sampled instant:

DUTY kind=const value=0.3
PWM1 kind=pwm freq=10000 in=DUTY

Fields

§freq_hz: f64

Fixed carrier frequency, Hz.

§red: f64

Rising-edge dead time, seconds.

§fed: f64

Falling-edge dead time, seconds.

§output_names: Vec<String>

[main, complement] output names.

§

PhaseShiftPwm

§PWM Modulator 2 (Phase-Shift PWM)

Purpose: frequency+phase+duty-driven, active-high complementary PWM with its own internal oscillator. Library: Power Electronics

§Description

This is not a variant of BlockKind::Vco — it owns its own frequency-integration state directly (osc reuses Vco’s own clamp-and-integrate math purely as an implementation detail, the same formula, not a shared block reference), so two instances fed the same freq input stay bit-for-bit phase-synchronized (deterministic integration, same dt, same starting phase 0.0), the way e.g. a dual-active-bridge’s two legs need to be, without a separately-declared shared oscillator block in between. red/fed are in seconds, exactly like BlockKind::Pwm’s own, but converted to a phase fraction using this step’s own resolved frequency (not a fixed constant) — this matters for a variable-frequency converter, since the same absolute dead time eats a larger fraction of the period at higher switching frequency, a real effect on e.g. a resonant converter’s own ZVS margin, not just bookkeeping.

§Parameters
  • f_min=<f64>, f_max=<f64> — the internal oscillator’s frequency clamp range, Hz.
  • inputs=<freq,phase,duty> — exactly 3, in this order: freq (Hz, clamped internally to [f_min, f_max]), phase ([0,1), a phase-shift command as a fraction of one carrier period — not this block’s own internal integration state, a different thing; applied as a lead: conduction begins at $(1 - \text{phase})$ of the carrier period, so 0.25 starts the pulse three quarters of the way through the period, not one quarter — see the user guide’s gate-bindings chapter for the run that shows it), duty ([0,1], clamped).
  • red=<f64>, fed=<f64> — optional, default 0.0; seconds, converted internally to a phase fraction using the current resolved frequency.
  • outputs=<main,complement> — optional; defaults to <name>,<name>_comp.
  • ic=<f64> — optional (default 0); the carrier’s own initial phase, in cycles, $0 \le \text{ic} < 1$ — applied before, and independent of, the phase input’s own offset.
§Errors
  • inputs= with a count other than 3 — rejected at parse time: kind='pspwm' needs 3 inputs (freq,phase,duty; got <n>).
  • f_min > f_max — rejected at parse time: invalid pspwm oscillator (FMinExceedsFMax).
  • outputs= with a count other than 2 — same error as BlockKind::Pwm’s own.
  • ic= outside $0 \le \text{ic} < 1$ — rejected at parse time: field 'ic' is the initial phase in cycles and must satisfy 0 <= ic < 1 (got <value>).
§Netlist form
NAME kind=pspwm f_min=<f64> f_max=<f64> inputs=<freq_signal,phase_signal,duty_signal> \
     [red=<f64>] [fed=<f64>] [outputs=<main,complement>] [ic=<f64>]
§Example

A 10 kHz, zero-phase-shift, 40% duty modulator — verified end to end: both outputs [0,1]-valued, PSPWM1 + PSPWM1_comp == 1 at every sampled instant:

FREQ kind=const value=10000
PHASE kind=const value=0
DUTY kind=const value=0.4
PSPWM1 kind=pspwm f_min=1000 f_max=50000 inputs=FREQ,PHASE,DUTY

Fields

§osc: Vco

The internal frequency-integrating oscillator.

§red: f64

Rising-edge dead time, seconds.

§fed: f64

Falling-edge dead time, seconds.

§output_names: Vec<String>

[main, complement] output names.

§

Product

§Product

Purpose: multiplies all its inputs together. Library: Sources / Math operations

§Description

The product $x_1 \cdot x_2 \cdot \dots$ of its inputs. Input-shape rule shared with Sum: all-Scalar inputs give a Scalar; otherwise every input must be a Vector of one common length N, multiplied elementwise to a Vector(N) — a mix of Scalar and Vector inputs is rejected rather than guessed at (see the Sum entry).

§Parameters
  • inputs=<sig1,sig2,...> — comma-separated input signals, one per factor.
§Errors
  • Mixed Scalar/Vector inputs — rejected at evaluation time: VectorSignalNotSupported { block: "<name>" }.
  • Vector inputs of differing lengths — rejected at evaluation time: VectorSignalSizeMismatch { block: "<name>", expected: N, got: M }.
  • A missing inputs= is the generic missing field 'inputs' error — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=product inputs=<sig1,sig2,...>
§Example
A kind=const value=2
B kind=const value=3
C kind=const value=4
P kind=product inputs=A,B,C
§

Saturation(f64)

§Saturation

Purpose: clamps its single input to a symmetric ±limit. Library: Sources / Math operations

§Description

Clamps its input to [-limit, limit] (elementwise for a Vector input) — the block-diagram saturation/limiter. See continuous_blocks::math_ops::saturation’s own doc comment for why this is a plain direct evaluation rather than a PWL device: the active segment depends only on this block’s own input, so there is no simultaneous-resolution problem the way there is for a diode’s terminal voltage.

§Parameters
  • in=<signal> — the single input.
  • limit=<f64> — the symmetric bound. Must be non-negative — but this is not checked at parse time; a negative limit panics the process at the first evaluation (see Errors).
§Errors
  • limit=-1 — not a clean error: parse time never validates limit, so the evaluation code’s own assert fires and the whole process panics with limit must be nonnegative. Keep limit >= 0.
  • A missing in=/limit= or a non-numeric limit= is the generic missing field '<key>'/field '<key>' is not a number error — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=saturation in=<signal> limit=<f64>
§Example

The time ramp (0..2 s) clamped to ±1 — passes through while |x| <= 1, holds 1 beyond:

X kind=time
LIM kind=saturation in=X limit=1
§

Table(Vec<(f64, f64)>)

§Table Lookup

Purpose: linear interpolation through a fixed (x, y) table. Library: Sources / Math operations

§Description

A table(x, a, b, c, d, ...)-style lookup: linear interpolation through the fixed (x, y) breakpoints (elementwise for a Vector input), clamped — not extrapolated — outside the range, holding the nearest endpoint’s y. Implemented by continuous_blocks::waveform_arithmetic::table.

§Parameters
  • in=<signal> — the single input (x).
  • points=[[x1,y1],[x2,y2],...] — the lookup table as a Python list of 2-element lists. Sorted ascending by x at parse time, so declaration order doesn’t matter. Must have at least one point — but that is not checked at parse time; an empty list panics the process at the first evaluation (see Errors).
§Errors
  • A points= entry that is not a 2-element [x,y] list — rejected at parse time: field 'points': each entry must be a 2-element '[x,y]' list (got '[1.0]').
  • points=[] — not a clean error: parse time never rejects an empty list, so the evaluation code’s own assert fires and the whole process panics with table needs at least one point.
  • A missing in=/points= is the generic missing field '<key>' error — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=table in=<signal> points=[[x1,y1],[x2,y2],...]
§Example

A trapezoid profile (ramp up, flat, ramp down, held at 0) driven by the time ramp:

X kind=time
T kind=table in=X points=[[0,0],[1,10],[2,10],[3,0]]
§

MathFn1(MathFn1)

§Waveform Arithmetic Functions (unary)

Purpose: one of the 26 single-argument real functions — trig, exponential/log, rounding, sign, step — as a stateless block. Library: Sources / Math operations

§Description

One entry for the whole unary family: every member is a pure Scalar -> Scalar function (elementwise Vector -> Vector for a Vector input), selected by its own kind= name, so they all share one input/error contract. Each name maps onto the same-named f64 method where one exists (continuous_blocks::waveform_arithmetic::MathFn1::call), with the same domain/range behavior — trig in radians, sqrt/ln NaN for negative arguments, and so on. What the library as a whole deliberately leaves out (a finite-difference derivative, noise/random generators, complex-data functions, boolean comparison operators) is argued in continuous_blocks::waveform_arithmetic’s own module doc comment.

nameformulanotes
abs$x
acos$\arccos x$
acosh$\operatorname{arcosh} x$
asin$\arcsin x$
asinh$\operatorname{arsinh} x$
atan$\arctan x$
atanh$\operatorname{artanh} x$
buf$1$ if $x > 0.5$ else $0$threshold/buffer, companion to inv
ceil$\lceil x \rceil$
cos$\cos x$radians
cosh$\cosh x$
exp$e^x$
floor$\lfloor x \rfloor$
inttruncation toward zero
inv$0$ if $x > 0.5$ else $1$complement of buf
ln$\ln x$natural log
log10$\log_{10} x$
roundround half away from zero
sgn$-1$/$0$/$1$sign; 0 at the origin (unlike f64::signum, which returns 1 there)
sin$\sin x$radians
sinh$\sinh x$
sqrt$\sqrt{x}$
tan$\tan x$radians
tanh$\tanh x$
u$1$ if $x > 0$ else $0$unit step
uramp$x$ if $x > 0$ else $0$ramp that starts at the origin (Relu)
§Parameters
  • in=<signal> — the single argument.
§Errors
  • A misspelled/unknown name (kind=cosx) — rejected at parse time: unknown device kind 'cosx'.
  • A missing in= is the generic missing field 'in' error — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=<fn> in=<signal>
§Example

sin(2*pi*1000*t) built from ordinary blocks, plus cos/exp and the elementwise vector form:

T kind=time
G kind=gain in=T k=6283.185307179586
S kind=sin in=G
C kind=cos in=G
E kind=exp in=T
SV kind=const value=[1,4,9]
SQ kind=sqrt in=SV
§

MathFn2(MathFn2)

§Waveform Arithmetic Functions (binary)

Purpose: one of the eight two-argument real functions — atan2/hypot/pow family, min/max, anglewrap — as a stateless block. Library: Sources / Math operations

§Description

One entry for the whole binary family: every member is a pure two-argument function selected by its own kind= name, taking in1=/in2= in that order. Input-shape rule: two Scalars give a Scalar; otherwise every Vector operand must share one length N (elementwise application, with a lone Scalar operand broadcast against it).

nameformulanotes
atan2$\operatorname{atan2}(x, y)$Rust’s x.atan2(y): the four-quadrant angle whose tangent is x/y
anglewrap$\operatorname{atan2}(\beta, \alpha)$ wrapped to $[0, 2\pi)$takes (alpha, beta); the angle-tracking half of a synchronous-reference-frame PLL — see below
hypot$\sqrt{x^2 + y^2}$
max$\max(x, y)$
min$\min(x, y)$
pow$x^y$plain f64::powf (negative base with non-integer exponent is NaN)
pwr$x
pwrs$\operatorname{sgn}(x),x

anglewrap is the special member: (alpha, beta) -> theta — the atan2(beta, alpha) angle shifted by a full turn when negative, so theta stays in [0, 2*pi) and is a monotonically-sensible input to park/clarke_park across a full revolution — the angle-tracking half of a synchronous-reference-frame PLL (see continuous_blocks::coordinate_transforms::anglewrap, whose output feeds park/ clarke_park). It lives here rather than with the Clarke/Park transforms because it is single-output: an ordinary two-argument function like every other member.

§Parameters
  • in1=<signal> in2=<signal> — the two arguments, in formula order above.
§Errors
  • A misspelled/unknown name — the same unknown device kind '<name>' error as the unary entry.
  • Vector operands of differing lengths — rejected at evaluation time: VectorSignalSizeMismatch { block: "<name>", expected: N, got: M }.
  • A missing in1=/in2= is the generic missing field '<key>' error — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=<fn> in1=<signal> in2=<signal>
§Example

The textbook 3-4-5 triangle, and the same pair’s anglewrap result (atan2(4,3) ~ 0.9273 rad):

X kind=const value=3
Y kind=const value=4
H kind=hypot in1=X in2=Y
AW kind=anglewrap in1=X in2=Y
§

MathFn3(MathFn3)

§Waveform Arithmetic Functions (ternary: if, limit)

Purpose: a threshold select (if) and a clamp (limit) — the two three-argument functions. Library: Sources / Math operations

§Description

One entry for the two three-argument functions — genuinely different semantics, but one shared input/error contract (documented at the type’s own granularity). Both take in1=/in2=/in3= in the order below, and both use the binary entry’s Scalar/ Vector rule unchanged.

nameformulanotes
if$y$ if $x > 0.5$ else $z$select/comparator: in2 while in1 > 0.5, else in3
limitclamp $x$ to $[\min(y, z), \max(y, z)]$the “intermediate value” of x, y, z — the bounds may be given in either order

limit’s bounds are not fixed at ±limit the way kind=saturation’s are — they are two ordinary inputs, so they can themselves come from elsewhere in the graph.

§Parameters
  • in1=<signal> in2=<signal> in3=<signal> — the three arguments, in formula order above.
§Errors
  • A misspelled/unknown name — the same unknown device kind '<name>' error as the unary entry.
  • A missing in1=/in2=/in3= is the generic missing field '<key>' error — see BlockInstance’s own doc comment.
§Netlist form
NAME kind=if     in1=<signal> in2=<signal> in3=<signal>
NAME kind=limit  in1=<signal> in2=<signal> in3=<signal>
§Example

A select picking between two references, and a clamp of 5 to the span [0, 2]:

CND kind=const value=1
THEN kind=const value=10
ELSE kind=const value=20
SEL kind=if in1=CND in2=THEN in3=ELSE
V kind=const value=5
LO kind=const value=0
HI kind=const value=2
L kind=limit in1=V in2=LO in3=HI
§

Hysteresis(Hysteresis)

§Hysteresis (Schmitt Trigger)

Purpose: a bang-bang/hysteresis-band comparator. Library: Logic

§Description

Stays HIGH until the input drops below low, stays LOW until the input rises above high (see continuous_blocks::Hysteresis) — used for current-mode control when there’s no fixed switching frequency to modulate a duty command onto (unlike Pid feeding a BlockKind::Pwm). Its output is 1.0/0.0, read directly by a GateBinding::Block rather than compared against a carrier. Deliberately not a StateSpace: the on/off memory is a genuine discrete latch, not a linear dynamic.

§Parameters
  • high=<f64>, low=<f64> — the two switching thresholds; must satisfy low <= high.
  • in=<signal> — the input signal (one input).
  • ic=0|1 — optional (default 0); the output the block starts the run holding, until its own inputs first change it.
§Errors
  • low > high — rejected at parse time: invalid hysteresis (LowExceedsHigh).
  • ic= that is neither 0 nor 1 — rejected at parse time: field 'ic' is the initial logic output and must be 0 or 1 (got '<value>').
§Netlist form
NAME kind=hysteresis high=<f64> low=<f64> in=<signal> [ic=0|1]
§Example

A [-1, 1] band, verified end to end: a rising Time-driven ramp is LOW until crossing 1, then HIGH:

T kind=time
RAMP kind=gain k=1 in=T
HYST1 kind=hysteresis high=1 low=-1 in=RAMP
§

LogicGate(LogicOp)

§Logic Gate

Purpose: a combinational digital logic gate. Library: Logic

§Description

and/or/xor/nand/nor/xnor (N-input, N >= 2) or not (exactly 1 input) — see continuous_blocks::LogicOp::call for the exact reduction rule (Xor/Xnor use the standard N-input generalization: true iff an odd/even number of inputs are true, not “exactly one”). Every input/output is an ordinary f64 signal, thresholded at >= 0.5 — the same convention GateBinding/BlockKind::Hysteresis already use; there is no dedicated boolean SignalValue variant anywhere in this crate. Purely combinational — no persistent state, recomputed fresh every step, the same as BlockKind::Sum/BlockKind::Gain already are.

§Parameters
  • kind=<and|or|xor|nand|nor|xnor|not> — which gate.
  • inputs=<sig1,sig2,...> — for every kind except not; at least 2 entries.
  • in=<signal> — for kind=not only; exactly 1 input.
§Errors
  • and/or/xor/nand/nor/xnor with fewer than 2 inputs= entries — rejected at parse time: kind=<name> needs at least 2 comma-separated inputs= entries (got <n>).
§Netlist form
NAME kind=<and|or|xor|nand|nor|xnor> inputs=<sig1,sig2,...>
NAME kind=not in=<signal>
§Example

A 2-input and, verified end to end (1 and 0 = 0, 1 and 1 = 1):

A kind=const value=1
B kind=const value=0
G1 kind=and inputs=A,B
§

SrLatch

§SR Latch

Purpose: a level-triggered set/reset latch. Library: Logic

§Description

No clock — set/reset act every step, immediately. The one genuinely new state shape in this family (a single persisted bool, updated every step from whichever of set/reset is currently asserted — see continuous_blocks::srlatch_next): set,reset -> q_next: false,false holds; true,false sets true; false,true sets false; true,true (both at once) resolves per priority. Set (the default) is the right default for this block’s own motivating use case, a sticky fault latch — a fault occurring in the same step a reset is asserted should still latch, not silently clear.

§Parameters
  • set=<signal>, reset=<signal> — both required.
  • priority=<set|reset> — optional, defaults to set; which input wins when both are asserted simultaneously.
  • ic=0|1 — optional (default 0); the output the block starts the run holding, until its own inputs first change it.
§Errors
  • priority= present but not set/reset — rejected at parse time: field 'priority' must be 'set' or 'reset' (got '<value>').
  • ic= that is neither 0 nor 1 — rejected at parse time: field 'ic' is the initial logic output and must be 0 or 1 (got '<value>').
§Netlist form
NAME kind=srlatch set=<signal> reset=<signal> [priority=<set|reset>] [ic=0|1]
§Example

A fault latch, verified end to end: FAULT pulses to 1 briefly then returns to 0 at t=0.1, but LATCH1 stays 1 afterward (no separate reset asserted):

FAULT kind=pwc points=[[0,1],[0.1,0]]
CLEAR kind=const value=0
LATCH1 kind=srlatch set=FAULT reset=CLEAR

Fields

§priority: LatchPriority

Which input wins when set and reset are asserted simultaneously.

§

FlipFlop

§Flip-Flop

Purpose: an edge-triggered D/JK/T flip-flop. Library: Logic

§Description

Unlike BlockKind::SrLatch above, the next-state rule only fires at a detected rising clk edge (continuous_blocks::rising_edge); the previous clk sample is held alongside the output q between edges, the bookkeeping a level-triggered latch doesn’t need at all.

§Parameters
  • kind=<dff|jkff|tff> — which flip-flop.
  • clk=<signal> — the clock input, required for every kind.
  • d=<signal> — for kind=dff only: the data input.
  • t=<signal> — for kind=tff only: the toggle-enable input.
  • j=<signal>, k=<signal> — for kind=jkff only: both required.
  • reset=<signal> — optional; if given, declares a synchronous reset input.
  • ic=0|1 — optional (default 0); the output the block starts the run holding, until its own inputs first change it.
§Errors
  • The kind-specific data input (d=/t=/j=+k=) missing for its own kind — the generic missing field '<key>' error.
  • ic= that is neither 0 nor 1 — rejected at parse time: field 'ic' is the initial logic output and must be 0 or 1 (got '<value>').
§Netlist form
NAME kind=dff clk=<signal> d=<signal> [reset=<signal>] [ic=0|1]
NAME kind=tff clk=<signal> t=<signal> [reset=<signal>] [ic=0|1]
NAME kind=jkff clk=<signal> j=<signal> k=<signal> [reset=<signal>] [ic=0|1]
§Example

A D flip-flop, verified end to end: Q1 only updates to D’s current value at a clock rising edge, not continuously:

CLK kind=pwc points=[[0,0],[5e-3,1]]
D kind=const value=1
Q1 kind=dff clk=CLK d=D

Fields

§kind: FlipFlopKind

dff/jkff/tff.

§reset: bool

Whether this instance declares a synchronous reset input.

§

Counter

§Counter

Purpose: a clocked up/down counter. Library: Logic

§Description

Shares the same rising-edge-detection skeleton BlockKind::FlipFlop uses, generalized from a single bit to an integer count. up_down/modulus/reset are all optional: omitting up_down always increments; omitting modulus gives a free-running signed i64 that wraps only at i64’s own bounds; omitting reset means no synchronous reset input at all.

§Parameters
  • clk=<signal> — the clock input, required.
  • up_down=<signal> — optional; if given, declares a direction input (counts down when its value thresholds true, up otherwise).
  • modulus=<u32> — optional; wraps the count into [0, modulus) if given.
  • reset=<signal> — optional; if given, declares a synchronous reset input.
  • ic=<integer> — optional (default 0); the initial count. With modulus=, must satisfy $0 \le \text{ic} < \text{modulus}$.
§Errors
  • modulus= present but not a non-negative integer — rejected at parse time: field 'modulus' is not a non-negative integer.
  • up_down=/reset= declared (field present) but the signal itself malformed — the generic missing field '<key>'/parse-signal errors.
  • ic= not an integer — rejected at parse time: field 'ic' is not an integer.
  • ic= outside the modulus — rejected at parse time: field 'ic' must satisfy 0 <= ic < modulus (<m>) (got <value>).
§Netlist form
NAME kind=counter clk=<signal> [up_down=<signal>] [modulus=<u32>] [reset=<signal>] \
     [ic=<integer>]
§Example

A free-running up counter clocked by a repeating pulse train — verified end to end, CNT1 increasing by exactly 1 at each detected clock rising edge:

CLK kind=pwc points=[[0,0],[1e-3,1],[2e-3,0]] repeat=true
CNT1 kind=counter clk=CLK

Fields

§up_down: bool

Whether this instance declares an up/down direction input (unset: always increments).

§modulus: Option<u32>

Wraps at this value if set; free-running i64 otherwise.

§reset: bool

Whether this instance declares a synchronous reset input.

§

CScript

§CScript

Purpose: call into a user-supplied, precompiled native shared library once per (block-local) step — an escape hatch for stateful behavior no existing block covers. Library: Extensibility

§Description

A dynamically-loaded, user-supplied block: lib is a precompiled shared library (.so/.dylib/.dll) exporting cscript_start/cscript_output/(optionally) cscript_free/cscript_clone, filling output_names.len() outputs. Unlike every other BlockKind, this one can carry state no Rust type here knows anything about — see cscript_ffi’s own module doc comment (in the sibling cscript-ffi crate) for the full C-side contract. This is the one place in the workspace where arbitrary native code loads into the process — calling into it is unsafe by construction (in-process, full host privileges, can corrupt memory or crash the process); this is an accepted, bounded risk of an explicitly opt-in feature (the user names their own .so in their own netlist), not something sandboxed away.

sample_time, if given, makes this block run on its own schedule, independent of the circuit’s own resolved step size — either a fixed period (optionally phase-offset), or a schedule the block computes for itself every time it runs. None (the default) calls cscript_output every resolved circuit step instead, passing that step’s own dt — the right choice for a block meant to behave continuously. See SampleTimeSpec’s own doc comment for the two Some(..) cases.

xc_count, if nonzero, declares this block as owning that many continuous states the solver itself numerically integrates (one independent RK4 per block, the same convention every other dynamic BlockKind here uses), as opposed to a block hand- integrating its own state inside cscript_output (still the right choice for a fixed- rate discrete recursion, e.g. a bilinear-transform-derived filter — see cscript_ffi’s own module doc comment, “The optional continuous-state (xc) contract,” for exactly which case this is for). 0 (the default) is the plain, single-function contract unchanged from before this field existed: lib must export cscript_start/ cscript_output/(optionally) cscript_free/cscript_clone. Nonzero requires lib to export cscript_start/cscript_derivative/cscript_output_xc/(optionally) cscript_free/cscript_clone instead of cscript_output.

§Parameters
  • lib=<path> — the precompiled shared library. Like every field, this is whitespace- tokenized; a path containing whitespace must be "double-quoted" (lib="my libs/gain.so") — verified directly against a real space-containing directory. An unquoted path with no whitespace needs no quotes, unchanged.
  • outputs=<name1,name2,...> — this block’s own output names; defaults to a single output aliasing the block’s own .name if omitted.
  • in=<signal> or inputs=<sig1,sig2,...> — exactly one of these; inputs= for more than one input, in the order cscript_output’s own in/in_len receives them.
  • ts=<f64> / freq=<f64> / to=<f64> / ts=variable — optional; see SampleTimeSpec. Omit entirely to run every resolved circuit step.
  • xc_count=<usize> — optional, default 0; number of solver-integrated continuous states (switches the required C export set — see Description above).
§Errors
  • lib/in missing, or both in and inputs given, or neither — the generic missing field '<key>' error (see BlockInstance’s own doc comment); there is no inputs-vs-in mutual-exclusion check specifically, inputs= simply takes priority when both are present.
  • xc_count present but not a non-negative integer — field 'xc_count' is not a non-negative integer.
  • ts=variable combined with freq=/to= — rejected at parse time: ts=variable is exclusive with 'freq'/'to' (the block computes its own schedule; there's no fixed period/offset to combine it with).
  • Adaptive step-size control requires cscript_clone to be exported — the solver retries a rejected trial step from an independent copy of every block’s state. Running a CScript block with no cscript_clone export under adaptive stepping (i.e. no --dt given to the CLI) fails at the first step with CScriptRequiresCloneForAdaptiveStep { block_name: "<name>" } (verified directly: this is the CLI’s raw {e:?} Debug formatting of dae_runtime’s own error type, not a hand-written message). Use a fixed --dt instead if the library doesn’t export it.
  • A .so missing a required export, or a signature mismatch, surfaces as a load-time or call-time failure from cscript_ffi itself — see that crate’s own error type.
§Netlist form
NAME kind=cscript lib=<path> (in=<signal> | inputs=<sig1,sig2,...>) \
     [outputs=<name1,name2,...>] [ts=<f64>|freq=<f64> [to=<f64>] | ts=variable] \
     [xc_count=<usize>]
§Example

A fixed-gain block computed in C (out = 2 * in), run every circuit step — lib names a shared library compiled from a two-function .c file exporting exactly cscript_start/cscript_output. Verified end to end (compiled, run through the real CLI, G1’s output confirmed to track 2 * SRC every step, e.g. SRC=3 produces G1=6):

SRC kind=const value=3
G1 kind=cscript lib=gain.so in=SRC

Fields

§lib: PathBuf

The precompiled shared library exporting the cscript_* C ABI.

§output_names: Vec<String>

This block’s own output names, in order.

§sample_time: Option<SampleTimeSpec>

None runs every resolved circuit step; Some runs on its own schedule.

§xc_count: usize

Number of solver-integrated continuous states this block owns; 0 for the plain contract.

§

PyBlock

§PyBlock

Purpose: call into a user-supplied, stateful Python function once per step — the Python-hosted counterpart to BlockKind::CScript. Library: Extensibility

§Description

A dynamically-loaded, user-supplied Python block (see pyblock_ffi): an escape hatch to a full scripting language (including numpy/scipy) when the existing block library doesn’t cover something. path is a .py file exporting start/output (or, if xc_count > 0, start/derivative/output_xc instead of output — the same continuous-state split CScript’s own xc_count has, for the same reason). output_names/sample_time/xc_count all have exactly the same meaning as CScript’s own fields — deliberately scalar-only outputs, the same zero-order-hold sample_time convention, the same solver-integrated-vs-hand-managed state split. See general-simulator’s own book/dev-guide/src/python-blocks.md for the full design and the measurements behind it.

§Parameters
  • path=<path> — the .py file exporting start/output (or the xc contract). Same whitespace-tokenization rule as CScript’s lib= — "double-quote" a path containing whitespace.
  • outputs=<name1,name2,...> — output names; defaults to a single output aliasing the block’s own .name.
  • in=<signal> or inputs=<sig1,sig2,...> — exactly one of these.
  • ts=<f64> / freq=<f64> / to=<f64> / ts=variable — optional; see SampleTimeSpec. ts=variable here requires the .py file to also export next_sample_hit (unlike BlockKind::PyFunction, where ts=variable is rejected outright).
  • xc_count=<usize> — optional, default 0.
§Errors
  • This block requires the CLI/library built with the python Cargo feature enabled (cargo build --features python) — it is not on by default, since it needs a discoverable Python/libpython at build/link time and kind=cscript already covers the same “dynamically-loaded custom block” need without that dependency. Without it, any kind=pyblock/kind=pyfunc netlist fails at the first step with PythonSupportNotCompiledIn { block_name: "<name>" } (verified directly — the CLI’s raw {e:?} formatting of dae_runtime’s own error, not a hand-written message).
  • path/in missing, or malformed outputs=/xc_count= — same generic/xc_count errors as BlockKind::CScript.
  • A .py file missing a required function, raising an exception, or returning the wrong arity surfaces as a Python-traceback-bearing failure from pyblock_ffi itself at call time, not at parse time.
§Netlist form
NAME kind=pyblock path=<path> (in=<signal> | inputs=<sig1,sig2,...>) \
     [outputs=<name1,name2,...>] [ts=<f64>|freq=<f64> [to=<f64>] | ts=variable] \
     [xc_count=<usize>]
§Example

A fixed-gain block computed in Python (out = 2 * in) — verified end to end against a --features python build of the CLI, SRC=3 producing G1=6:

SRC kind=const value=3
G1 kind=pyblock path=gain.py in=SRC

where gain.py is:

def start():
    return None

def output(state, t, dt, inputs):
    return inputs[0] * 2.0

The xc_count>0 contract (derivative/output_xc) is verified separately end to end against its own analytic solution ($\dot{x}_c = 1 - x_c$, starting at rest, so $x_c(t) = 1 - e^{-t}$) — see doc-verify/pyblock/xc_example.cir.

Fields

§path: PathBuf

The .py file exporting start/output (or start/derivative/output_xc).

§output_names: Vec<String>

This block’s own output names, in order.

§sample_time: Option<SampleTimeSpec>

None runs every resolved circuit step; Some runs on its own schedule.

§xc_count: usize

Number of solver-integrated continuous states this block owns; 0 for the plain contract.

§

PyFunction

§PyFunction

Purpose: call a plain, stateless, named Python function once per step. Library: Extensibility

§Description

A genuinely separate contract from BlockKind::PyBlock above (not a mode of it): no start, no persistent state, no t/dt boilerplate, just function (a name inside path’s own .py file) called with each declared inputs= entry as its own positional argument (f(*inputs), never bundled into one list), returning a single value or a tuple/list matching output_names. The closest equivalent to a plain named-input/named-output function block in other block-diagram tools. output_names/ sample_time mean the same as PyBlock’s own (still scalar-only outputs, still the same zero-order-hold convention) — there is no xc_count here at all, since a purely stateless function has nothing for a continuous state to mean. See pyblock_ffi::PyFunctionInstance’s own module doc comment for the full contract.

§Parameters
  • path=<path> — the .py file containing function. "double-quote" a path containing whitespace, same as CScript’s lib=.
  • function=<name> — required, no default; the function called as f(*inputs).
  • outputs=<name1,name2,...> — output names; defaults to a single output aliasing the block’s own .name.
  • in=<signal> or inputs=<sig1,sig2,...> — exactly one of these.
  • ts=<f64> / freq=<f64> / to=<f64> — optional, SampleTimeSpec::Periodic only; ts=variable is rejected (see Errors).
§Errors
  • Requires a --features python build — see BlockKind::PyBlock’s own Errors section; identical PythonSupportNotCompiledIn failure.
  • ts=variable — rejected at parse time, verified directly: ts=variable is not available for kind=pyfunc (a stateless function call has no instance to remember a requested next-hit time against) -- use kind=pyblock instead. A stateless function call has no instance to remember “when am I next due” against.
  • function missing — the generic missing field 'function' error.
  • A .py file missing function, raising an exception, or returning the wrong arity surfaces as a Python-traceback-bearing failure from pyblock_ffi at call time.
§Netlist form
NAME kind=pyfunc path=<path> function=<name> (in=<signal> | inputs=<sig1,sig2,...>) \
     [outputs=<name1,name2,...>] [ts=<f64> | freq=<f64> [to=<f64>]]
§Example

Verified end to end against a --features python build, SRC=3 producing G1=4:

SRC kind=const value=3
G1 kind=pyfunc path=add.py function=add_one in=SRC

where add.py is:

def add_one(x):
    return x + 1.0

inputs=A,B calling f(A, B) as two genuinely distinct positional arguments (never bundled into one list) is verified separately — see doc-verify/pyfunc/example_two_inputs.cir.

Fields

§path: PathBuf

The .py file containing function.

§function: String

The function name called with each declared input as a positional argument.

§output_names: Vec<String>

This block’s own output names, in order.

§sample_time: Option<SampleTimeSpec>

None runs every resolved circuit step; Some must be SampleTimeSpec::Periodic.

§

OctFunc

§OctFunc

Purpose: call a plain, stateless, named Octave-compatible function once per step. Library: Extensibility

§Description

The .m-file counterpart to BlockKind::PyFunction above – same genuinely separate, stateless contract (no start, no persistent state, no t/dt boilerplate), for people with legacy Octave-compatible .m scripts instead of Python. function (a name inside path’s own .m file, which must itself be named <function>.m – Octave’s own requirement that a function’s file name match its function name) is called with each declared inputs= entry as its own positional argument (f(arg0, arg1, ...), never bundled into one array), returning a single value or as many comma-separated return values as output_names declares ([y1, y2] = f(...)). output_names/sample_time mean the same as PyFunction’s own – still scalar-only outputs, still the same zero-order-hold convention – and there is no xc_count here either, for the same reason PyFunction has none: a purely stateless function has nothing for a continuous state to mean.

Unlike PyFunction, this block never embeds an interpreter in-process: it calls into a separately installed octave-cli binary as a subprocess (one shared, persistent process for the whole simulation run, spawned lazily on first use), specifically so this permissively-licensed project never links against GPLv3-licensed Octave code – see octave_ffi’s own module doc comment and general-simulator’s own book/dev-guide/src/octave-blocks.md for the full licensing rationale and the measured costs behind this design.

§Parameters
  • path=<path> — the .m file containing function; its own file name (minus .m) must equal function. "double-quote" a path containing whitespace, same as CScript’s lib=.
  • function=<name> — required, no default; the function called as f(arg0, arg1, ...), and the required base name of path’s own file.
  • outputs=<name1,name2,...> — output names; defaults to a single output aliasing the block’s own .name.
  • in=<signal> or inputs=<sig1,sig2,...> — exactly one of these.
  • ts=<f64> / freq=<f64> / to=<f64> — optional, SampleTimeSpec::Periodic only; ts=variable is rejected (see Errors), for exactly the reason PyFunction’s own is.
§Errors
  • ts=variable — rejected at parse time, the same wording PyFunction uses (a stateless function call has no instance to remember a requested next-hit time against): ts=variable is not available for kind=octfunc (a stateless function call has no instance to remember a requested next-hit time against).
  • function missing — the generic missing field 'function' error.
  • octave-cli not found on PATH when this block is first evaluated, an Octave-side exception raised by the called function, or a malformed/desynchronized reply from the shared session — surfaces as a call-time failure from octave_ffi itself (see octave_ffi::OctaveError’s own three cases: not-found, process-exited, and Octave-side runtime error), not at parse time.
§Netlist form
NAME kind=octfunc path=<file.m> function=<name> (in=<signal> | inputs=<sig1,sig2,...>) \
     [outputs=<name1,name2,...>] [ts=<f64> | freq=<f64> [to=<f64>]]
§Example

Verified end to end against the real CLI (no special feature flag needed – unlike kind=pyblock/kind=pyfunc, this block builds and runs unconditionally), SRC=3 producing G1=4:

SRC kind=const value=3
G1 kind=octfunc path=add_one.m function=add_one in=SRC

where add_one.m is:

function y = add_one(x)
  y = x + 1;
end

inputs=A,B calling f(A, B) as two genuinely distinct positional arguments is verified separately – see doc-verify/octfunc/example_two_inputs.cir.

Fields

§path: PathBuf

The .m file containing function – its own base file name must equal function.

§function: String

The function name called with each declared input as a positional argument.

§output_names: Vec<String>

This block’s own output names, in order.

§sample_time: Option<SampleTimeSpec>

None runs every resolved circuit step; Some must be SampleTimeSpec::Periodic.

§

OctBlock

§OctBlock

Purpose: call into a user-supplied, stateful Octave-compatible function once per step – the Octave-hosted counterpart to BlockKind::PyBlock, and the stateful sibling of BlockKind::OctFunc (not a mode of it – see that variant’s own doc comment for the stateless contract this one deliberately does not share). Library: Extensibility

§Description

An escape hatch to Octave-compatible .m-file functions with real persistent state across steps – for people with legacy Octave-compatible .m scripts who need pyblock’s own start/output/update/xc_count contract, not octfunc’s stateless one. output_names/sample_time/xc_count all mean exactly what BlockKind::PyBlock’s own do (scalar-only outputs, the same zero-order-hold sample_time convention, the same solver-integrated-vs-hand-managed xc split).

path= names a directory, not a single file – the one place this contract cannot simply reuse OctFunc’s own single-.m-file convention: Octave only auto-loads the first function ... end block in a .m file by filename, so a second function in the same file is an invisible private subfunction (confirmed empirically against real octave-cli). Every contract function therefore needs its own file, named <function>_<role>.m, all living together in path’s own directory:

FileRequiredSignature
<function>_start.malwaysstate = <function>_start()
<function>.munless xc_count>0[new_state, y1, y2, ...] = <function>(state, t, dt, u1, u2, ...)
<function>_derivative.monly if xc_count>0xc_dot = <function>_derivative(state, u1, ..., xc) – pure, must not mutate state; called up to 4x/step (RK4 stages), including from discarded trial steps under adaptive stepping
<function>_output_xc.monly if xc_count>0[new_state, y1, ...] = <function>_output_xc(state, t, dt, u1, ..., xc) – xc here is this step’s own already-integrated continuous state
<function>_update.moptionalnew_state = <function>_update(state, t, dt, u1, ...) – called once per resolved step, after output; if absent, output/output_xc’s own returned new_state is the only state advance
<function>_next_sample_hit.monly if ts=variableseconds = <function>_next_sample_hit(state, t, dt, u1, ...)

A user coming from Octave/legacy-language habits of “one script, many local functions” hits this immediately – this is not a buried caveat, it is the load-bearing difference from every other block kind’s own path=.

Each instance’s own opaque state (whatever <function>_start returns) lives entirely inside the shared Octave session itself, in one global struct keyed by this block’s own instance name (global __gs_state; __gs_state.('<name>') = ...) – it is never serialized back into Rust at all, unlike PyBlock’s own state (an opaque Python object pyblock_ffi holds a handle to) or CScript’s (an opaque void*). Two instances of the same Octave function never contaminate each other’s state – validated directly against real octave-cli (interleaved calls, zero cross-contamination; see octave_ffi::OctaveSession’s own tests/stateful_session.rs). The one piece of state that does cross the pipe as explicit numeric data (the same %.17g-per-line protocol octfunc already uses, extended to a literal Octave vector) is the solver-owned xc continuous-state vector for the xc_count > 0 case – that’s the solver’s state, not the block’s own opaque one, so it has to be explicit, exactly mirroring cscript’s/ pyblock’s own xc vs. opaque-state split. See general-simulator’s own book/dev-guide/src/octave-blocks.md for the full protocol, licensing rationale, and measured costs.

Like OctFunc, this block shares one persistent octave-cli subprocess with every other Octave-hosted block kind in the same run (spawned lazily, on first use) – never a second process.

§Parameters
  • path=<dir> — the directory containing <function>_*.m (see the file table above). "double-quote" a path containing whitespace, same as CScript’s lib=.
  • function=<name> — required, no default; the base name every <function>_<role>.m file shares.
  • outputs=<name1,name2,...> — output names; defaults to a single output aliasing the block’s own .name.
  • in=<signal> or inputs=<sig1,sig2,...> — exactly one of these.
  • ts=<f64> / freq=<f64> / to=<f64> / ts=variable — optional; see SampleTimeSpec. ts=variable here requires <function>_next_sample_hit.m to also exist in path’s own directory.
  • xc_count=<usize> — optional, default 0.
§Errors
  • path/function/in missing, or malformed outputs=/xc_count= — same generic/ xc_count errors as BlockKind::CScript.
  • A required <function>_*.m file missing from path’s own directory (per the file table above, given this block’s own xc_count/ts=) — checked once, up front, at construction time, before octave-cli is ever asked about it: dae_runtime::DaeError ::OctBlockMissingRequiredFile { block_name, expected_path }.
  • ts=variable without <function>_next_sample_hit.m present — checked the same way: dae_runtime::DaeError::OctBlockRequiresNextSampleHitForVariableSampleTime.
  • octave-cli not found on PATH, an Octave-side exception raised by a called function, or a malformed/desynchronized reply — surfaces as a call-time failure from octave_ffi itself (dae_runtime::DaeError::Octave), not at parse time.
  • kind=octblock does not support TimeStep::Adaptive — this instance’s own opaque state lives inside the one shared octave-cli session, which is never cloned, so a rejected adaptive trial step’s own state-mutating calls could not be rolled back; a netlist using kind=octblock under an adaptive run fails at construction with dae_runtime::DaeError::OctBlockDoesNotSupportAdaptiveStep { block_name }. Use a fixed --dt.
§Netlist form
NAME kind=octblock path=<dir> function=<name> (in=<signal> | inputs=<sig1,sig2,...>) \
     [outputs=<name1,name2,...>] [ts=<f64>|freq=<f64> [to=<f64>] | ts=variable] \
     [xc_count=<usize>]
§Example

A stateful accumulator (out = state + in, state advances by in every step) verified end to end against the real CLI, SRC=3 producing G1=3,6,9,... across successive steps:

SRC kind=const value=3
G1 kind=octblock path=accum function=accumulate in=SRC

where accum/accumulate_start.m is:

function state = accumulate_start()
  state = 0;
end

and accum/accumulate.m is:

function [new_state, y] = accumulate(state, t, dt, u)
  new_state = state + u;
  y = new_state;
end

The xc_count>0 contract (_derivative/_output_xc) is verified separately end to end against its own analytic solution ($\dot{x}_c = 1 - x_c$, starting at rest, so $x_c(t) = 1 - e^{-t}$) — see doc-verify/octblock/xc_example.cir, mirroring doc-verify/pyblock/xc_example.cir’s own precedent.

Fields

§path: PathBuf

The directory containing <function>_start.m, <function>.m (or <function>_derivative.m/<function>_output_xc.m), and optionally <function>_update.m/<function>_next_sample_hit.m.

§function: String

The shared base name every <function>_<role>.m file in path uses.

§output_names: Vec<String>

This block’s own output names, in order.

§sample_time: Option<SampleTimeSpec>

None runs every resolved circuit step; Some runs on its own schedule.

§xc_count: usize

Number of solver-integrated continuous states this block owns; 0 for the plain contract.

§

CoordinateTransform

§Coordinate Transform (Clarke/Park)

Purpose: one of the six Clarke/Park three-phase coordinate transforms. Library: Coordinate Transforms

§Description

The standard abc/alpha-beta-0/d-q-0 change of basis (see continuous_blocks::CoordinateTransform) used to regulate a three-phase quantity (grid-tied PFC, motor drive) with a Pid on a DC-like d/q value instead of chasing a sine wave directly. Stateless and multi-output, following exactly the same output_names convention BlockKind::CScript established: inputs supplies kind.input_count() values in the order CoordinateTransform::call expects, output_names.len() must equal 3 (this family’s output count — the conventional per-transform names, e.g. ["alpha", "beta", "zero"] for Clarke), the block’s own .name binds to the first (primary) output, and the remaining two are inserted under their own output_names entries so a downstream block can reference them directly via Signal::Block(name).

§Parameters
  • kind=<clarke|clarkeinv|park|parkinv|clarkepark|clarkeparkinv> — which transform.
  • inputs=<sig1,...> — 3 entries for clarke/clarkeinv, 4 for the other four (park/parkinv/clarkepark/clarkeparkinv also take an angle input).
  • outputs=<name1,name2,name3> — optional; defaults to <name>,<name>_<suffix2>, <name>_<suffix3> using this transform’s own conventional output names.
§Errors
  • Wrong inputs= count for this transform — rejected at parse time: kind='<kind>' needs <n> inputs (got <m>).
  • outputs= with a count other than 3 — rejected at parse time: 'outputs' needs exactly 3 entries (got <n>).
§Netlist form
NAME kind=clarke inputs=<a,b,c> [outputs=<name1,name2,name3>]
NAME kind=park inputs=<a,b,c,theta> [outputs=<name1,name2,name3>]
§Example

A balanced three-phase set through clarke — verified end to end: for $a=1,b=-0.5,c=-0.5$ (a peak on phase A), $\alpha = 1$, $\beta = 0$ exactly:

A kind=const value=1
B kind=const value=-0.5
C kind=const value=-0.5
CT1 kind=clarke inputs=A,B,C

Fields

§kind: CoordinateTransform

Which of the six Clarke/Park transforms this is.

§output_names: Vec<String>

Output names; length must equal 3 for this family.

§

Pmsm

§PMSM (Permanent-Magnet Synchronous Motor)

Purpose: a nonlinear permanent-magnet synchronous motor model. Library: Machines

§Description

Genuinely nonlinear (bilinear speed/current coupling — see continuous_blocks::Pmsm), so like BlockKind::Vco it carries its own state and is integrated via its own step() (RK4) rather than compiled to a StateSpace. Three inputs, in order: vd, vq (rotor-frame stator voltage commands, V — typically a ClarkeParkInv’s output, or a CoordinateTransform intermediate wired through a Pid), and t_load (N·m, the mechanical load torque). Four outputs, same output_names convention as BlockKind::CoordinateTransform/BlockKind::CScript: id, iq (A), omega_m (mechanical speed, rad/s), and theta_e (electrical angle, already wrapped to $[0, 2\pi)$ via Pmsm::theta_e_wrapped — ready to feed a Park/ClarkePark block directly). Starts at rest (id = iq = omega_m = theta_e = 0) — no initial-condition override, matching every other dynamic block in this graph. Surface-mount motors have l_d == l_q (no reluctance torque term); interior-PM motors have l_d != l_q.

§Parameters
  • r_s=<f64> — stator resistance, Ω; must be >= 0.
  • l_d=<f64>, l_q=<f64> — d/q-axis inductance, H; both must be > 0.
  • lambda_pm=<f64> — permanent-magnet flux linkage, Wb.
  • pole_pairs=<f64> — must be > 0.
  • inertia=<f64> — rotor inertia, kg·m²; must be > 0.
  • friction=<f64> — viscous friction coefficient; must be >= 0.
  • inputs=<vd,vq,t_load> — exactly 3, in this order.
  • outputs=<id,iq,omega_m,theta_e> — optional; defaults to <name>,<name>_iq, <name>_omega_m,<name>_theta_e.
  • ic=[id,iq,omega_m,theta_e] — optional (default: all zero); the four machine states at $t = 0$: $d$/$q$ currents (A), mechanical speed (rad/s), electrical angle (rad).
§Errors
  • r_s < 0 — invalid pmsm (NegativeResistance).
  • l_d <= 0 or l_q <= 0 — invalid pmsm (NonPositiveInductance).
  • pole_pairs <= 0 — invalid pmsm (NonPositivePolePairs).
  • inertia <= 0 — invalid pmsm (NonPositiveInertia).
  • friction < 0 — invalid pmsm (NegativeFriction).
  • ic= with other than four entries — rejected at parse time: field 'ic' has <m> value(s), but this block has 4 state(s).
§Netlist form
NAME kind=pmsm r_s=<f64> l_d=<f64> l_q=<f64> lambda_pm=<f64> pole_pairs=<f64> \
     inertia=<f64> friction=<f64> inputs=<vd,vq,t_load> [outputs=<id,iq,omega_m,theta_e>] \
     [ic=<vector>]
§Example

A small surface-mount motor at rest with zero applied voltage/load — verified to run without error and stay at rest (id = iq = omega_m = 0, no torque applied):

VD kind=const value=0
VQ kind=const value=0
TLOAD kind=const value=0
M1 kind=pmsm r_s=0.5 l_d=1e-3 l_q=1e-3 lambda_pm=0.05 pole_pairs=4 inertia=1e-5 \
     friction=1e-6 inputs=VD,VQ,TLOAD

Fields

§pmsm: Pmsm

The motor’s own parameters/state.

§output_names: Vec<String>

Output names; length must equal 4 (id, iq, omega_m, theta_e).

§

Phys2Sig(Phys2SigTarget)

§Phys2Sig (Physical-to-Signal Converter)

Purpose: the only way a circuit quantity enters the signal domain. Library: Electrical Interface

§Description

Zero block-graph inputs (it reads the circuit’s own previous-step operating point directly). Its value is then an ordinary block output, read by any downstream block via Signal::Block(this_block's_name) exactly like any other source block (Const/Pwl/Time). Modeled directly on the physical/signal converter block a real block-diagram simulation tool requires: a physical port and a signal port are type-distinct there and cannot be wired together without one of these in between — the same rule, enforced the same way, at the netlist level instead of a GUI’s wiring canvas. Named symmetrically with BlockKind::Sig2Phys (its write-direction counterpart): phys2sig reads a circuit quantity into the signal domain, sig2phys drives a signal-domain value onto a circuit quantity.

§Parameters
  • node=<name> — reads V(node). Mutually exclusive with branch=.
  • branch=<name> — reads I(branch). Mutually exclusive with node=.
§Errors
  • Both node= and branch= given — rejected at parse time: 'node' and 'branch' are mutually exclusive (a phys2sig reads either a node voltage or a branch current, never both).
  • Neither given — rejected at parse time: kind='phys2sig' needs 'node=<name>' (reads V(node)) or 'branch=<name>' (reads I(branch)).
  • branch=<name> naming an element that has no MNA branch-current unknown at all — rejected at build time (once the full circuit is known), not silently read back as 0.0: only V/L/E (VCVS)/H (CCVS) elements carry a branch-current unknown (see MnaBuilder::is_branch_device); naming anything else (a resistor, a capacitor, a diode, an ideal switch, …) is line N: device '<name>' kind='phys2sig' branch='<branch>' has no current unknown available (only V/L/E/H sources carry a branch-current unknown) -- insert a 0V voltage source in series in the branch you want to measure and probe its current instead — the standard SPICE “ammeter” idiom: a 0V source in series perturbs nothing electrically, but (being a V element) gets its own branch-current unknown for free, which branch= can then read.
  • branch=<name> naming an element that doesn’t exist anywhere in the netlist at all (not just the wrong type) — a distinct build-time error: line N: device '<name>' kind='phys2sig' branch='<branch>' names no such element.
§Netlist form
NAME kind=phys2sig node=<node_name>
NAME kind=phys2sig branch=<branch_name>
§Example

Reading a resistor-divider node’s own voltage — verified end to end, PROBE1 tracking V(out) exactly:

V1 in 0 5
R1 in out 1k
R2 out 0 1k
PROBE1 kind=phys2sig node=out

The ammeter idiom — measuring the current through R1 (which has no branch-current unknown of its own) by inserting a 0V source VAMM in series and reading that instead; verified end to end, IMEAS tracking 5 / (1000 + 1000) = 0.0025 A exactly (the 0V source doesn’t perturb the divider at all):

V1 in 0 5
VAMM in mid 0
R1 mid out 1000
R2 out 0 1000
IMEAS kind=phys2sig branch=VAMM
§

Sig2Phys

§Sig2Phys (Signal-to-Physical Converter)

Purpose: the only legal way a signal-domain block’s output drives a V/I source’s magnitude or an ideal switch’s gate. Library: Electrical Interface

§Description

Closes the write-direction gap BlockKind::Phys2Sig doesn’t (a phys2sig only ever reads). A V/I element’s own literal value field in the netlist names this block directly (e.g. V1 a 0 VDRV, where VDRV is a declared domain=voltage block) — general-mna’s own Expression::parse_scalar already accepts a bare symbol there with no change needed on that side; dae-runtime requires, at validation time, that any such symbol naming a declared block resolve to exactly this kind with the matching domain for the device letter driving it (V requires domain=voltage, I requires domain=current) — DaeError::SourceNotSig2PhysicalConverter otherwise — and every step, substitutes this block’s own just-computed output value into the circuit solve in that symbol’s place.

Also the only legal target for a GateBinding::Block’s own named block, and there only the domain=voltage form — dae-runtime rejects a GateBinding naming anything else, including a domain=current Sig2Phys, with DaeError::GateTargetNotSig2Voltage. An ideal switch’s gate is itself a voltage (V_GS against the gate’s own v_gs_th), not a distinct discrete-actuation signal domain, so there is no separate gate-only converter — one type, Sig2Phys, parameterized by PhysicalDomain, is the whole Signal-to-PS boundary for “a signal-domain block’s output drives a physical voltage or current,” whether that voltage happens to source a node, gate a switch, or drive a current source. Purely an identity pass-through numerically (value = input) in every role; the domain field is what the enforcement keys on. One input.

§Parameters
  • domain=<voltage|current> — which physical quantity this converter drives. Required.
  • in=<signal> — the value to drive onto the physical side (one input).
§Errors
  • domain= missing entirely — rejected at parse time: line N: device '<name>' missing field 'domain'.
  • domain= present but not voltage/current — rejected at parse time: line N: device '<name>' field 'domain' must be 'voltage' or 'current' (got '<value>').
  • Beyond that, none specific to this kind= — every real enforcement (a V/I/gate target actually naming a Sig2Phys of the right domain) happens at dae-runtime’s validation stage, not netlist parse time. general-mna itself only ever sees the device-source half of a document (with --devices <file>, it doesn’t see the netlist at all), so it cannot detect a converter’s name reused as an ordinary circuit node — that mistake produces no parse error here. dae-runtime rejects it as DaeError::Sig2PhysUsedAsCircuitNode: this block has no terminals and stamps nothing into the MNA system, so a net sharing its name is merely undriven, and KCL solves it to a silently wrong 0 rather than failing — a converter must always be referenced by name (a source’s value field, or a switch’s gate=/ctrl=), never wired.
§Netlist form
NAME kind=sig2phys domain=voltage in=<signal>
NAME kind=sig2phys domain=current in=<signal>
§Example

A block-driven voltage source — verified end to end, V1’s magnitude tracking a Const through the converter exactly:

CMD kind=const value=5
VDRV kind=sig2phys domain=voltage in=CMD
V1 a 0 VDRV
R1 a 0 1k

A block-driven current source — verified end to end, I1’s magnitude tracking a Const through the converter exactly:

CMD kind=const value=0.1
IDRV kind=sig2phys domain=current in=CMD
I1 a 0 IDRV
R1 a 0 1k

Fields

§domain: PhysicalDomain

Which physical quantity this converter drives — V-source targets and GateBinding::Block targets require Voltage; I-source targets require Current.

Trait Implementations§

Source§

impl Clone for BlockKind

Source§

fn clone(&self) -> BlockKind

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for BlockKind

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
Source§

impl PartialEq for BlockKind

Source§

fn eq(&self, other: &BlockKind) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for BlockKind

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.