Livt packages

Livt.Math

Version 1.7.2

Reusable integer and fixed-point arithmetic, complex numbers, trigonometry, and statistics for FPGA applications written in Livt.

docs/usage.md

Usage Examples

Livt.Math exposes fixed-size arithmetic components. These examples show the basic call order and boundary behavior expected by the package.

Bounded Stream Statistics

Use StreamingMomentsInt16 when a finite block needs integer mean, population variance, and standard deviation without retaining its samples. Finalize after the block has been added, and check its Boolean result before reading the finalized fields.

namespace Example

using Livt.Math.Statistics

component BlockStatisticsExample
{
    statistics: StreamingMomentsInt16<256>

    new()
    {
        statistics = new StreamingMomentsInt16<256>()
    }

    public fn Summarize()
    {
        statistics.Reset()
        statistics.Add(-12)
        statistics.Add(4)
        statistics.Add(20)

        if (statistics.Finalize()) {
            var mean: int = statistics.GetMean()
            var variance: uint = statistics.GetVariance()
            var deviation: uint = statistics.GetStdDev()
        }
    }
}

Integer Helpers

Use the context-free integer helpers for reusable combinational selection, magnitude, and saturating arithmetic. Magnitude returns uint so the magnitude of signed int minimum remains representable. AbsSaturating returns int and saturates that one value to signed maximum.

namespace Example

using Livt.Math.Arithmetic

component IntegerMathExample
{
	public fn Run()
	{
		var bounded: int = IntegerMath.Clamp(120, -100, 100)
		var magnitude: uint = IntegerMath.Magnitude(-2147483647 - 1)
		var signedSum: int = IntegerMath.AddSaturating(2147483647, 1)
		var unsignedDifference: uint = UnsignedMath.SubSaturating(3, 7)
	}
}

Integer Square Root

Use SqrtLUT for 8-bit inputs when a small table is a better fit than an iterative divider. Inputs outside [0, 255] are clamped.

namespace Example

using Livt.Math.Sqrt

component SqrtLutExample
{
    sqrt: SqrtLUT

    new()
    {
        sqrt = new SqrtLUT()
    }

    public fn Run()
    {
        var root144: int = sqrt.Compute(144)
        var rootLarge: int = sqrt.Compute(300)
    }
}

Use SqrtNewtonRaphson for larger integer inputs. Inputs outside [0, 32767] are clamped.

namespace Example

using Livt.Math.Sqrt

component SqrtNewtonExample
{
    sqrt: SqrtNewtonRaphson

    new()
    {
        sqrt = new SqrtNewtonRaphson()
    }

    public fn Run()
    {
        var root32766: int = sqrt.Compute(32766)
        var rootClamped: int = sqrt.Compute(40000)
    }
}

Saturating Multiply-Accumulate

MacUnit stores a signed 16-bit accumulator. Each Accumulate(a, b) call adds a * b and clamps the stored result to [-32768, 32767].

namespace Example

using Livt.Math.Arithmetic

component MacExample
{
    mac: MacUnit

    new()
    {
        mac = new MacUnit()
    }

    public fn Run()
    {
        mac.Reset()
        mac.Accumulate(1, 4)
        mac.Accumulate(2, 5)
        mac.Accumulate(3, 6)
        var dot: int = mac.GetResult()
    }
}

Fixed-Point Formats

Use named fixed-point helpers when values have a clear scale. Q15 is the default choice for normalized signed DSP coefficients, while Q7 is compact and UQ8 is useful for unsigned normalized values such as duty cycles.

For reusable combinational arithmetic, call the static context-free helpers directly. They return values and do not require a component instance.

namespace Example

using Livt.Math.FixedPoint

component FixedPointExample
{
    public fn Run()
    {
        var half: int = 16384
        var quarter: int = Q15.MulValue(half, half)
        var saturated: int = Q15.AddSaturatingValue(32767, 10)
        var brightness: int = UQ8.MulValue(128, 128)
    }
}

Stateful calls remain available when a component should store the latest result.

namespace Example

using Livt.Math.FixedPoint

component StatefulFixedPointExample
{
    q15: Q15

    new()
    {
        q15 = new Q15()
    }

    public fn Run()
    {
        q15.Mul(16384, 16384)
        var quarter: int = q15.GetResult()
    }
}

Q15 Complex Arithmetic

ComplexQ15 stores a complex value in Q15 format and exposes the latest result through explicit read methods. Static helpers are available for direct complex composition when an algorithm wants real and imaginary parts as values.

namespace Example

using Livt.Math.Complex
using Livt.Math.FixedPoint

component ComplexExample
{
    value: ComplexQ15

    new()
    {
        value = new ComplexQ15()
    }

    public fn Run()
    {
        value.Set(16384, 0)
        value.MulByTwiddle(0, 32767)
        var real: int = value.GetResultReal()
        var imag: int = value.GetResultImag()

        var directReal: int = ComplexQ15.MulReal(16384, 0, 0, 32767)
        var directImag: int = ComplexQ15.MulImag(16384, 0, 0, 32767)
    }
}

Q15 Lookup Constants

Use TrigQ15 for small deterministic sine/cosine values. It is intentionally a lookup helper, not a full transform implementation. FFT orchestration belongs in a DSP/signal-processing package that depends on these primitives.

namespace Example

using Livt.Math.Lookup

component LookupExample
{
    trig: TrigQ15

    new()
    {
        trig = new TrigQ15()
    }

    public fn Run()
    {
        var cos45: int = trig.Cos(1, 8)
        var sin90: int = trig.Sin(1, 4)
    }
}

Arbitrary Q15 Sine and Cosine

Use the scheduled CORDIC worker when the phase is not one of the common values provided by TrigQ15. Phase units map 32768 to π radians, so 8192 represents π/4. A successful call retains both Q1.15 results.

namespace Example

using Livt.Math.Trigonometry

component CordicExample
{
    cordic: CordicSinCosQ15

    new()
    {
        cordic = new CordicSinCosQ15()
    }

    public fn Run() bool
    {
        if (!cordic.Compute(CordicSinCosQ15.QUARTER_PI)) {
            return false
        }

        var sine: int = cordic.GetSin()
        var cosine: int = cordic.GetCos()
        return true
    }
}

See CordicSinCosQ15.md for the numeric error and lifecycle contract.

Q15 Vector Phase and Magnitude

Use the vectoring CORDIC worker to convert a nonzero Cartesian Q1.15 vector into canonical phase and unsigned magnitude. Magnitude keeps 15 fractional bits and can represent the complete diagonal range.

namespace Example

using Livt.Math.Trigonometry

component VectoringExample
{
    cordic: CordicAtan2MagnitudeQ15

    new()
    {
        cordic = new CordicAtan2MagnitudeQ15()
    }

    public fn Run() bool
    {
        if (!cordic.Compute(23170, 23170)) {
            return false
        }

        var phase: int = cordic.GetPhase()
        var magnitude: uint = cordic.GetMagnitude()
        return true
    }
}

See CordicAtan2MagnitudeQ15.md for the numeric and lifecycle contracts.

Fixed-Point Logarithm, Exponential, and Reciprocal

The special-function components use paired, bounded formats suitable for FPGA gain and compression paths.

namespace Example

using Livt.Math.Approximation
using Livt.Math.FixedPoint

component SpecialFunctionExample
{
    logarithm: Log2UQ15
    exponential: Exp2Q11
    reciprocal: ReciprocalUQ15

    new()
    {
        logarithm = new Log2UQ15()
        exponential = new Exp2Q11()
        reciprocal = new ReciprocalUQ15()
    }

    public fn Run() bool
    {
        if (!logarithm.Compute(46341 as uint)) {
            return false
        }

        var logValue: int = logarithm.GetResult()
        if (!exponential.Compute(logValue)) {
            return false
        }

        var restored: uint = exponential.GetResult()
        var inverse: uint = reciprocal.Compute(24576 as uint)
        return restored > (0 as uint) && inverse > (0 as uint)
    }
}

See SpecialFunctions.md for the numeric and lifecycle contracts.