Unit-aware measured values and standard uncertainty propagation for MoonBit.

moonbit

uncertainty

measurement

metrology

units

science

moon add FrozenLemonTee/LunarUncertainty@0.1.1

Download zip

Author

FrozenLemonTee

Version

0.1.1

License

Apache-2.0

Repository

github.com/FrozenLemonTee/LunarUncertainty

Last updated

last month

Downloads

Dependencies

FrozenLemonTee/LunarUnits0.1.7

README

#LunarUncertainty

LunarUncertainty is a small MoonBit library for measured values with units and standard uncertainty propagation. It builds on LunarUnits, so measured values keep the same dimension checks, unit conversions, composite units and formatters as ordinary Quantity values.

The first release focuses on the common engineering model:

x = nominal ± standard_uncertainty

MeasuredQuantity assumes independent variables and uses first-order uncertainty propagation for addition, subtraction, multiplication, division and integer powers.

#Features

MeasuredQuantity: one nominal value, one non-negative standard uncertainty and one shared LunarUnits unit.
Construction from two LunarUnits Quantity values, with compatible uncertainty units normalized into the nominal unit.
Unit conversion for both nominal value and uncertainty.
Addition/subtraction with root-sum-square absolute uncertainty propagation.
Multiplication/division/powers with relative uncertainty propagation.
Structured errors for negative uncertainty and zero nominal values in relative propagation paths.
Simple formatting with LunarUnits FormatStyle support.

#Installation

moon add FrozenLemonTee/LunarUncertainty

Then import the measurement package and the LunarUnits packages you need:

import {
  "FrozenLemonTee/LunarUncertainty/measure",
  "FrozenLemonTee/LunarUnits/quantities/qelectromagnetism",
  "FrozenLemonTee/LunarUnits/quantities/qgeometry",
  "FrozenLemonTee/LunarUnits/quantities/qmass",
  "FrozenLemonTee/LunarUnits/quantities/qsi",
  "FrozenLemonTee/LunarUnits/units/mass",
  "FrozenLemonTee/LunarUnits/units/mechanics",
}

#Quick Start

let distance = @measure.MeasuredQuantity::new(
  @qgeometry.meters(10.0),
  @qgeometry.meters(0.2),
)
let time = @measure.MeasuredQuantity::new(
  @qsi.seconds(2.0),
  @qsi.seconds(0.1),
)

let speed = distance.div(time)
let text = @measure.format_measured_quantity(speed)
// "5 ± 0.26925824035672524 m/s"

A compatible uncertainty unit is converted automatically:

let length = @measure.MeasuredQuantity::new(
  @qgeometry.meters(10.0),
  @qgeometry.centimeters(20.0),
)
// Stored as 10.0 ± 0.2 m.

Dimension errors still come from LunarUnits, so 10 m ± 1 s is rejected with the same dimension mismatch information users get from Quantity.

#Relative Uncertainty

When an instrument reports a relative standard uncertainty, construct the measured quantity directly from that ratio:

let length = @measure.MeasuredQuantity::from_relative(
  @qgeometry.meters(10.0),
  0.02,
)
// Stored as 10.0 ± 0.2 m.

The checked_from_relative variant returns None when the relative uncertainty is negative.

#More Examples

Density keeps the mass and volume units attached:

let mass = @measure.MeasuredQuantity::new(
  @qmass.kilograms(12.0),
  @qmass.kilograms(0.1),
)
let volume = @measure.MeasuredQuantity::new(
  @qgeometry.liters(3.0),
  @qgeometry.liters(0.05),
)
let density = mass.div(volume)
let density_si = density.to(@mass.kilogram_per_cubic_meter)
// density_si.value() == 4000.0

Electrical power composes voltage and current into watts:

let voltage = @measure.MeasuredQuantity::new(
  @qelectromagnetism.volts(12.0),
  @qelectromagnetism.volts(0.1),
)
let current = @measure.MeasuredQuantity::new(
  @qsi.amperes(2.0),
  @qsi.amperes(0.02),
)
let power = voltage.mul(current)
// power.unit().is_compatible(@mechanics.watt)

#Error Model

NegativeUncertainty: raised when an absolute or relative standard uncertainty is negative.
ZeroNominalForRelativeUncertainty: raised by multiplication, division and non-zero powers when relative uncertainty propagation needs a zero nominal value.
LunarUnits DimensionMismatch: raised by construction, conversion, addition and subtraction when units are not dimensionally compatible.

Most recoverable paths also have checked_* variants. For example, checked_mul, checked_div, checked_pow and checked_relative_uncertainty return None for zero-nominal relative propagation cases.

#Statistical Boundary

This library models symmetric standard uncertainty only. It does not implement asymmetric intervals, correlations, covariance matrices, probability distributions, Monte Carlo propagation, confidence intervals or automatic significant-figure rounding. Applications can layer those policies on top when they need them.

#Development

Run the full test suite:

moon test

Update generated interfaces and formatting before review:

moon info
moon fmt

Site source Report issue Packages Build queue Skills Statistics