Struct CompileOptions 

pub struct CompileOptions {
    pub oversampling: OversamplingFactor,
    pub tolerance: ToleranceEngine,
    pub thermal: bool,
    pub collapse_nl: bool,
    pub skip_k_tables: bool,
    pub skip_blockwise: bool,
    pub force_serial_blockwise: bool,
    pub force_serial_blockwise_feedback_gain: f64,
    pub disable_iir: bool,
    pub coupled_blockwise_newton: bool,
}

Fields

oversampling: OversamplingFactor

tolerance: ToleranceEngine

thermal: bool

collapse_nl: bool

When true, collapse ALL nonlinear elements into a single MultiNlStage instead of planning them as individual stages. Used for sidechain sub-circuits where the entire NL network should be solved as one multi-junction system (shared MNA + scattering matrix).

skip_k_tables: bool

When true, skip K-method lookup table generation. NL roots fall back to Newton-Raphson iteration at runtime. Use for fast debug builds — K-table generation is the main compile-time bottleneck (65536-entry 2D sweeps per NL root).

skip_blockwise: bool

When true, skip blockwise decomposition of multi-NL groups. Falls back to monolithic R-type adaptor. Use when blockwise produces incorrect pot bindings or signal routing.

force_serial_blockwise: bool

Diagnostic mode: build blockwise-decomposed nonlinear ladders as serial WDF/K-method rung stages instead of packaging them into one delay-free Blockwise coupling stage. This intentionally breaks delay-free feedback, so it is only useful for isolating rung behavior.

force_serial_blockwise_feedback_gain: f64

Diagnostic mode: when force_serial_blockwise is enabled, wrap the serial rung stages in a one-sample output feedback loop with this gain. 0.0 preserves the plain forced-serial behavior.

disable_iir: bool

Diagnostic mode: do not synthesize IIR stages from rigid subgraphs. Rigid passive networks fall through to StateSpace where possible, and active feedback networks fall through to the existing WDF adaptors.

coupled_blockwise_newton: bool

Solve coupled blockwise K-method stages with the full delay-free Newton/Jacobian iteration. This is useful for compiler validation and offline reference renders, but too expensive for some realtime targets. When false, coupled blockwise stages use table-driven fixed-point iteration without building/solving the full Jacobian.

Implementations

impl CompileOptions

pub fn force_monolithic(self) -> Self

Return a copy of these options with blockwise decomposition disabled, forcing all nonlinear groups through the monolithic/rigid MNA path.

Use this for differential testing: compile the same circuit twice (default() and force_monolithic()) and compare outputs sample-wise. Any deviation indicates that blockwise is behaving as a dialect change rather than a pure optimization — which is a bug.

Follows the same opt-in pattern as CompileOptions::thermal: default false (blockwise enabled), set true to override.

pub fn release() -> Self

Default options for release builds: full optimization including K-tables.

pub fn debug() -> Self

Fast options for debug builds: skip K-table generation. NL elements use Newton-Raphson iteration instead (correct but slower at runtime).

pub fn from_cargo_profile() -> Self

Auto-detect from the PROFILE env var set by Cargo during build.rs. Returns release() for “release” profile, debug() for everything else.

Use in build.rs:

let options = pedalkernel::compiler::CompileOptions::from_cargo_profile();

Trait Implementations

impl Clone for CompileOptions

fn clone(&self) -> CompileOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for CompileOptions

fn default() -> Self

Returns the “default value” for a type.