Struct LinearModel 

pub struct LinearModel {
    pub weights: AlignedVec<f32>,
    pub bias: f32,
    pub history: MirroredBuffer<f32>,
    pub write_pos: usize,
    pub receptive_field: usize,
    pub prewarm_on_reset: bool,
    pub implementation: LinearImplementation,
    pub mode: LinearMode,
    /* private fields */
}

Linear Model — lightweight FIR-based neural model.

This is the simplest NAM architecture: a single linear layer (dot product) applied over the recent sample history with an optional scalar bias.

RT-Safety

• Zero allocation on the hot-path (process).
• Uses MirroredBuffer for branch-free ring buffer access.
• No locks, no unwrap(), no I/O.

Fields

weights: AlignedVec<f32>

FIR filter weights stored in reversed order (matching C++ internal layout). JSON weights are reversed on construction, so that dot(weights, oldest_to_newest_window) produces the FIR convolution. 64-byte aligned for AVX2/AVX-512 SIMD loads.

bias: f32

Scalar bias added after the dot product.

history: MirroredBuffer<f32>

Circular buffer of past input samples, backed by mirrored memory mapping for branch-free contiguous access across the wrap boundary.

write_pos: usize

Current write position in the history ring buffer (0..receptive_field-1).

receptive_field: usize

Number of input samples in the receptive field (= weights.len()).

prewarm_on_reset: bool

Whether to execute prewarm during reset(). Default: true.

implementation: LinearImplementation

Convolution implementation mode as configured in the JSON.

mode: LinearMode

Runtime convolution mode — Direct or Fft with partitioned FFT state.

Implementations

impl LinearModel

pub unsafe fn process(&mut self, input: &[f32], output: &mut [f32])

Processes a block of audio samples.

Safety

self.weights must be 64-byte aligned.

pub fn prewarm(&mut self, _num_samples: usize)

Fills the history buffer with zeros, resets the write pointer, and reinitializes the FFT state (if active).

pub fn reset(&mut self, _sample_rate: u32, _max_buffer_size: usize)

Resets internal state: zeroes the history buffer, write pointer, and FFT state (if active).

impl LinearModel

pub fn new( weights: Vec<f32>, bias: f32, implementation: LinearImplementation, ) -> Result<Self>

Creates a new LinearModel with the given weights, bias, and implementation.

Weights are expected in forward-time order as stored in the .nam JSON (w[0] is the response at the current sample). They are reversed internally to match the C++ nam::Linear layout.

implementation controls the convolution strategy (Auto, Direct, Fft) as configured in the model’s JSON:

• Direct: always uses time-domain dot product.
• Auto: uses FFT when receptive_field >= 256, otherwise Direct.
• Fft: uses FFT partitioned convolution; falls back to Direct with a warning if the receptive field is too small (< 256).

Allocates the MirroredBuffer for the input history. The buffer is initialized to zero (silence) by the operating system via mmap.

Errors

Returns std::io::Error if the MirroredBuffer allocation fails (e.g., out of memory or virtual address space).

Trait Implementations

impl NamModel for LinearModel

fn process(&mut self, input: &[f32], output: &mut [f32])

Invoked by the DSP RT-Thread to process acoustic sample blocks (Float32).

fn prewarm(&mut self, num_samples: usize)

“Heats up” the virtual tubes of the neural engine (prewarm).

fn reset(&mut self, sample_rate: u32, max_buffer_size: usize) -> Result<()>

Resets the model’s internal state with a new sample rate and max buffer size.

fn prewarm_samples(&self) -> usize

Returns the number of samples needed to fully stabilize the model’s internal state (receptive field / recurrent memory depth).

fn prewarm_on_reset(&self) -> bool

Returns whether prewarm should be executed on reset().

fn set_prewarm_on_reset(&mut self, val: bool)

Sets whether prewarm should be executed on reset().

fn set_max_buffer_size(&mut self, _max_buf: usize) -> Result<()>

Reallocates internal buffers to support the given maximum block size.

fn slimmable_breakpoints(&self) -> Vec<f64>

Returns the breakpoints at which slimmable quality transitions occur.