class

`SushiDSP::dk::DkCircuit`

template <std::size_t S, std::size_t N, std::size_t I, std::size_t O>

Solves one discretised nonlinear circuit block by damped Newton per sample, on the nodal DK method with the trapezoidal rule (include/SushiDSP/README.md).

Declared in: include/SushiDSP/math/dk/DkCircuit.hpp

The caller's NonlinearSystem exposes void currents_and_jacobian(const std::array<double, N>& v, std::array<double, N>& i, std::array<std::array<double, N>, N>& j) const; the Jacobian buffer arrives zeroed. No output is ever non-finite.

Template parameters

N: Nonlinear branch count; may be zero, in which case no solver runs.

Static public attributes

static constexpr std::size_t kMaximumSystemOrder = kMaximumNodes + I + kMaximumNullors

Dimension of the augmented nodal system at the maximum supported node count.

One row and one column per node, per input source and per nullor. At the worst shape that is 16 + 2 + 4 = 22, so the system and its inverse are under 8 KB together.

Public member functions

bool prepare(const DkNetlist< S, N, I, O > &netlist, double sample_rate)

Validates a netlist, discretises it at the run rate and derives the matrices.

The run rate is the oversampled rate the block will actually be stepped at, not the host rate. All potentiometers start at position 0.5. Also clears state and statistics.

Parameters

netlist: The circuit description; copied, so the builder may go out of scope.
sample_rate: Run rate in hertz, strictly positive.

Returns

False when the netlist is malformed or the nodal system is singular; the object is then not usable.

template <typename NonlinearSystem>
void process_sample(NonlinearSystem &nonlinear, const std::array< double, I > &inputs, std::array< double, O > &outputs)

Advances the circuit by one sample, warm-starting Newton from the previous sample's port voltages.

Allocation-free, lock-free, syscall-free and throw-free, provided the supplied models are.

Parameters

nonlinear: The model glue instance; referenced, never stored.
inputs: Source voltages u[n], in the order the sources were added.
outputs: Probe voltages y[n], overwritten; always finite.

void set_potentiometer(std::size_t index, double position)

Sets a potentiometer's wiper position.

Cheap and idempotent: an unchanged position marks nothing dirty, which is what makes calling this from a SmoothedParameter every block free while the knob is still. Cadence contract: the owning node calls update_matrices_if_dirty() once per block, after its smoothers advance and before the sample loop; never from inside the loop.

Parameters

index: The index returned by DkNetlist::potentiometer; out-of-range is ignored.
position: Wiper position, clamped to [0, 1].

bool update_matrices_if_dirty()

Re-derives the DK matrices when a potentiometer has moved since the last call.

RT-safe. Cadence contract: call once per block, after the smoothers advance and before the sample loop; never from inside the sample loop.

Returns

True when the matrices were re-derived; false when nothing was dirty, or when the new nodal system was singular and the previous matrices were kept.

void reset()

Clears state, port voltages, port currents and the statistics counters.

Does not re-derive: a reset is a state clear, not a topology change.

const std::array< double, N > & nonlinear_currents() const

The nonlinear branch currents from the most recent sample.

D6d reads this to feed a power-supply-sag block one sample late (D6b plan, ruling 7).

Returns

i[n], in the order the nonlinear branches were added.

const std::array< double, N > & nonlinear_voltages() const

The nonlinear branch voltages from the most recent sample.

Returns

v[n], in the order the nonlinear branches were added.

const std::array< double, S > & states() const

The reactive element states after the most recent sample.

Returns

x[n], in the order the reactive elements were added.

std::uint64_t non_converged_samples() const

Samples whose Newton iteration did not converge since the last reset.

Returns

The non-convergence count.

std::uint64_t nan_fallback_samples() const

Samples that produced a non-finite value and fell back to the previous state.

Returns

The fallback count.

std::uint64_t total_samples() const

Samples processed since the last reset.

Returns

The sample count.

std::uint32_t maximum_iterations_seen() const

Worst-case Newton iteration count over any single sample since the last reset.

Returns

The worst-case iteration count.

void reset_statistics()

Clears the convergence, fallback and sample counters.

void set_state_limit(double limit)

Sets the magnitude each state is clamped to every sample.

The clamp is what stops a transient from reaching the range where a device model's exponential overflows; the default of 1e4 is far outside any physical rail.

Parameters

limit: Clamp magnitude; non-positive values are ignored.