#LunarUnits

#Features

• Quantity — a numeric value paired with a unit.
• Seven base dimensions and a minimal normalized symbolic algebra behind them.
• SI base units and a growing set of common units grouped by domain (time, geometry, mass, mechanics, fluid, thermal, electromagnetism, angle, solid_angle, information, currency, count).
• Addition, subtraction, multiplication, division and integer powers, with units composed automatically.
• Same-dimension conversion, and runtime rejection of dimensionally invalid operations.
• checked_* APIs for non-raising addition, subtraction and conversion paths.
• Formatters for units and quantities in ASCII (m/s^2), SI/Unicode (m/s²) and LaTeX (\mathrm{m}/\mathrm{s}^{2}) notations.
• Immutable symbol catalogs (notation/catalog) with prebuilt per-domain catalogs (notation/preset) for resolving and extending unit symbols.
• A string parser (notation/parser) for unit and quantity expressions (m/s^2, 9.8 m/s^2), with classified, non-panicking errors.
• Affine scales (affine/) for absolute points such as temperature (°C, °F, K, °R), distinguishing an absolute point from an interval by type.
• Logarithmic scales (logarithmic/) for levels (dBm, dBW, dBV) and gains (dB, Np), with power vs root-power kept distinct.
• Convenience quantity constructors for built-in unit domains.
• Extension dimensions and common physical constants.
• Every public API ships with a runnable documentation example.

#Installation

moon add FrozenLemonTee/LunarUnits

import {
  "FrozenLemonTee/LunarUnits/core/quantity",
  "FrozenLemonTee/LunarUnits/units/si",
  "FrozenLemonTee/LunarUnits/notation/preset",
  "FrozenLemonTee/LunarUnits/notation/parser",
  "FrozenLemonTee/LunarUnits/quantities/qgeometry",
}

#Quick start

fn main {
  // Build quantities with convenience constructors or directly from a unit.
  let distance = @qgeometry.meters(100.0)
  let time = @quantity.Quantity::new(10.0, @si.second)

  // Arithmetic composes units automatically.
  let speed = distance / time
  println(@quantity.format_quantity(speed))

  // The checked API is convenient in `main`: invalid conversions return None.
  let in_meters = @qgeometry
    .kilometers(2.0)
    .checked_to(@si.meter)
    .unwrap()
  println(@quantity.format_quantity(in_meters))

  // Parse a complete quantity without introducing an unhandled error effect.
  let catalog = @preset.all()
  let gravity = @parser
    .parse_quantity_opt(catalog, "9.8 m/s^2")
    .unwrap()
  println(@quantity.format_quantity(gravity))

  // Dimensionally invalid addition is rejected without terminating the program.
  println(distance.checked_add(time) is None)
}

10 m/s
2000 m
9.8 m/s^2
true

#Design

1. core/algebra — a minimal normalized symbolic algebra. Because units and dimensions only ever multiply, divide and take integer powers, the algebra is a free abelian group over symbols: every expression normalizes to a unique monomial (a coefficient times a product of symbol^exponent terms). This makes comparison, simplification and canonical ordering automatic.
2. core/dimension — the seven SI base dimensions (length, mass, time, electric current, temperature, amount of substance, luminous intensity) expressed as monomials. Two dimensions are equal exactly when their exponent vectors match, which is the basis of dimensional checking.
3. core/unit — Un, a unit symbol monomial paired with a dimension. The coefficient carries the scale relative to the coherent SI unit, so composite units (e.g. m/s) and conversions fall out of the algebra automatically.
4. core/quantity — Quantity, a value plus a unit. Addition/subtraction and conversion are dimensionally checked; multiplication and division compose units. Dimension, Un, and Quantity support * and / as shorthand for total algebraic composition; integer powers remain explicit via .pow(n).

#Package layout

core/
  algebra      normalized symbolic algebra (Expr, Monomial)
  dimension    physical dimensions (Dimension)
  unit         unit definitions and conversion (Un)
  quantity     values with units (Quantity, DimensionMismatch)
dimensions/
  angle_dimension        extension dimension for plane angle
  solid_angle_dimension  extension dimension for solid angle
  information_dimension  extension dimension for information
  currency_dimension     extension dimension for money
  count_dimension        extension dimension for discrete counts
units/
  si           SI base units
  time         minute, hour, day, milli/micro/nanosecond (fixed-length durations)
  angle        radian, degree, turn, arcminute, arcsecond, cycle, hertz
  solid_angle  steradian, square degree, spat
  geometry     length, area, volume
  mass         mass, density
  mechanics    force, pressure, velocity, energy, power
  fluid        dynamic/kinematic viscosity, permeability
  thermal      heat transfer coefficient, conductivity, specific heat, heat
  electromagnetism  charge, voltage, resistance, capacitance, inductance, flux
  information  bit, byte and common decimal/binary byte units
  currency     dollar, cent, k$, M$ (same-currency only)
  count        each, dozen, gross
quantities/
  qtime        time-duration constructors (minutes, hours, days, ...)
  qangle       plane angle constructors, plus cycle and hertz (frequency)
  qsolidangle  solid angle quantity constructors
  qsi          SI base quantity constructors
  qgeometry    geometry quantity constructors
  qmass        mass and density quantity constructors
  qmechanics   mechanics quantity constructors
  qfluid       fluid quantity constructors
  qthermal     thermal quantity constructors
  qelectromagnetism  electrical and magnetic quantity constructors
  qinformation information quantity constructors
  qcurrency    currency quantity constructors
  qcount       discrete-count quantity constructors
constants/
  physics      common physical constants as quantities
notation/
  catalog      immutable symbol -> unit lookup table (Catalog)
  preset       prebuilt catalogs, one per unit package, plus all()
  parser       parse unit/quantity strings (parse_unit, parse_quantity)
affine/        affine scales (AffineUn, Point) with temperature units
logarithmic/   logarithmic scales (Level, Gain) with decibel/neper units
examples/      runnable, self-checking examples
docs/          design and roadmap notes

Linear units/thermal keeps only the kelvin and its linear derivatives. Affine temperature points (°C, °F, °R) live in the separate affine/ package, and logarithmic levels/gains in logarithmic/, so Un/Quantity stay purely multiplicative.

#Development

• Tests live next to the package they validate (_test.mbt for black-box, _wbtest.mbt for white-box). Public APIs also carry runnable doc examples.
• Run moon test to build and verify everything (including doc examples).
• Run moon info && moon fmt before reviewing diffs.

#License