Struct AffineTransform 

pub struct AffineTransform { /* private fields */ }

Invertible i32 affine map y' = (y * gain + offset) / scale.

Arithmetic uses i64 intermediates and nearest, ties-away-from-zero rounding. Identity (modulo rounding when |scale| ≠ 1) is gain = scale and offset = 0. A negative gain or scale is allowed and flips sense.

This type never reads NVM, wraps a transfer, or writes TransferMetadata. AffineCalibration contains one of these and delegates its gain/offset/scale arithmetic here.

Inverse

unapply solves y = (y' * scale - offset) / gain with the same rounding. Because a zero gain collapses every input onto offset / scale, new rejects gain == 0 rather than deferring the failure to unapply.

Numerical scope

For any i32 y, gain, and offset, the product/sum y * gain + offset always fits in i64; the same holds for y' * scale - offset on the inverse path. Both directions still report AffineOverflow::Overflow when the rounded result does not fit i32.

Both directions round, so unapply(apply(y)) is bounded rather than exact. A transform that compresses the scale cannot restore what the forward quantization discarded. At i32 extremes, inverse rounding of a forward result can land just outside i32, in which case unapply reports overflow.

Implementations

impl AffineTransform

pub const fn new( gain: i32, offset: i32, scale: i32, ) -> Result<Self, AffineTransformError>

Construct an invertible affine transform.

Errors

Returns AffineTransformError::ZeroScale if scale == 0, or AffineTransformError::ZeroGain if gain == 0. A zero gain maps every input onto the single value offset / scale and has no inverse.

Examples found in repository

examples/no_std_generated_fixtures.rs (line 36)

pub fn runtime_api_smoke(code: u16, sample: u32) -> (i32, u16, u32, bool) {
    let transfer = PiecewiseLinearTransfer::new(
        &SMOKE_INPUTS,
        &SMOKE_OUTPUTS,
        MonotonicDirection::Increasing,
    );
    let calibrated = match AffineCalibration::new(transfer, 1_001, 0, 1_000) {
        Ok(value) => value,
        Err(_) => unreachable!(),
    };
    let physical = calibrated.convert(code).unwrap_or_default();
    let inverse = calibrated.invert(physical).unwrap_or_default();

    let affine = match AffineTransform::new(1_001, 0, 1_000) {
        Ok(value) => value,
        Err(_) => unreachable!(),
    };
    let _ = affine
        .apply(physical)
        .and_then(|value| affine.unapply(value));

    let mut average = MovingAverage::<u32, 1>::new();
    let filtered = match average.update(sample) {
        FilterOutput::Ready(value) => value,
        FilterOutput::WarmingUp { .. } => unreachable!(),
    };
    let mut latch = Hysteresis::<u32>::new(100, 200);
    (physical, inverse, filtered, latch.update(filtered))
}

pub const fn gain(&self) -> i32

Return the gain coefficient.

pub const fn offset(&self) -> i32

Return the offset term.

pub const fn scale(&self) -> i32

Return the nonzero scale divisor.

pub fn apply(&self, value: i32) -> Result<i32, AffineOverflow>

Apply y' = (y * gain + offset) / scale.

Rounding is nearest, ties away from zero.

Errors

Returns AffineOverflow::Overflow when the rounded result does not fit in i32.

Examples found in repository

examples/no_std_generated_fixtures.rs (line 41)

pub fn runtime_api_smoke(code: u16, sample: u32) -> (i32, u16, u32, bool) {
    let transfer = PiecewiseLinearTransfer::new(
        &SMOKE_INPUTS,
        &SMOKE_OUTPUTS,
        MonotonicDirection::Increasing,
    );
    let calibrated = match AffineCalibration::new(transfer, 1_001, 0, 1_000) {
        Ok(value) => value,
        Err(_) => unreachable!(),
    };
    let physical = calibrated.convert(code).unwrap_or_default();
    let inverse = calibrated.invert(physical).unwrap_or_default();

    let affine = match AffineTransform::new(1_001, 0, 1_000) {
        Ok(value) => value,
        Err(_) => unreachable!(),
    };
    let _ = affine
        .apply(physical)
        .and_then(|value| affine.unapply(value));

    let mut average = MovingAverage::<u32, 1>::new();
    let filtered = match average.update(sample) {
        FilterOutput::Ready(value) => value,
        FilterOutput::WarmingUp { .. } => unreachable!(),
    };
    let mut latch = Hysteresis::<u32>::new(100, 200);
    (physical, inverse, filtered, latch.update(filtered))
}

pub fn unapply(&self, value: i32) -> Result<i32, AffineOverflow>

Undo y' = (y * gain + offset) / scale, recovering y.

Solves y = (y' * scale - offset) / gain with the same nearest, ties-away rounding. Offset is subtracted in i64 rather than negated as i32, so offset == i32::MIN is representable.

Both directions round, so unapply(apply(y)) is bounded rather than exact: a transform that compresses the scale cannot restore what the forward quantization discarded.

Errors

Returns AffineOverflow::Overflow when the rounded result does not fit in i32.

Examples found in repository

examples/no_std_generated_fixtures.rs (line 42)

pub fn runtime_api_smoke(code: u16, sample: u32) -> (i32, u16, u32, bool) {
    let transfer = PiecewiseLinearTransfer::new(
        &SMOKE_INPUTS,
        &SMOKE_OUTPUTS,
        MonotonicDirection::Increasing,
    );
    let calibrated = match AffineCalibration::new(transfer, 1_001, 0, 1_000) {
        Ok(value) => value,
        Err(_) => unreachable!(),
    };
    let physical = calibrated.convert(code).unwrap_or_default();
    let inverse = calibrated.invert(physical).unwrap_or_default();

    let affine = match AffineTransform::new(1_001, 0, 1_000) {
        Ok(value) => value,
        Err(_) => unreachable!(),
    };
    let _ = affine
        .apply(physical)
        .and_then(|value| affine.unapply(value));

    let mut average = MovingAverage::<u32, 1>::new();
    let filtered = match average.update(sample) {
        FilterOutput::Ready(value) => value,
        FilterOutput::WarmingUp { .. } => unreachable!(),
    };
    let mut latch = Hysteresis::<u32>::new(100, 200);
    (physical, inverse, filtered, latch.update(filtered))
}

Trait Implementations

impl Clone for AffineTransform

fn clone(&self) -> AffineTransform

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for AffineTransform

impl Debug for AffineTransform

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

Formats the value using the given formatter.

impl Eq for AffineTransform

impl PartialEq for AffineTransform

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for AffineTransform