Crate qtty_core 

Core type system for strongly typed physical quantities.

qtty-core provides a minimal, zero-cost units model:

• A unit is a zero-sized marker type implementing Unit.
• A value tagged with a unit is a Quantity<U, S>, where S is the scalar type (defaults to f64). Supported scalars include f64, f32, signed integers (i8–i128), and optionally Rational64.
• Conversion is an explicit, type-checked scaling via Quantity::to (for Real scalars) or Quantity::to_lossy (for Exact scalars).
• Derived units like velocity are expressed as Per<N, D> (e.g. Meter/Second).

Most users should depend on qtty (the facade crate) unless they need direct access to these primitives.

What this crate solves

• Compile-time separation of dimensions (length vs time vs angle, …).
• Zero runtime overhead for unit tags (phantom types only).
• Full dimensional arithmetic: m * m → Prod<Meter, Meter>, m / s → Per<Meter, Second>, m / m → Quantity<Unitless>. Named derived units (e.g. SquareMeter) are obtained via .to().
• Automatic compile-time verification that multiplied/divided quantities produce the correct dimension.

What this crate does not try to solve

• General-purpose symbolic simplification of arbitrary unit expressions. Products and quotients are structural (Prod<A, B>, Per<A, B>); use .to() to convert to named units.

Quick start

Convert between predefined units:

use qtty_core::length::{Kilometers, Meter};

let km = Kilometers::new(1.25);
let m = km.to::<Meter>();
assert!((m.value() - 1250.0).abs() < 1e-12);

Compose derived units using /:

use qtty_core::length::{Meter, Meters};
use qtty_core::time::{Second, Seconds};
use qtty_core::velocity::Velocity;

let d = Meters::new(100.0);
let t = Seconds::new(20.0);
let v: Velocity<Meter, Second> = d / t;
assert!((v.value() - 5.0).abs() < 1e-12);

no_std

Disable default features to build qtty-core without std:

[dependencies]
qtty-core = { version = "0.7.0", default-features = false }

When std is disabled, floating-point math that isn’t available in core is provided via libm.

Feature flags

• std (default): enables std support.
• cross-unit-ops (default): enables direct cross-unit comparison operators (==, <, etc.) for built-in unit catalogs.
• serde: enables serde support for Quantity<U, S>; serialization is the raw scalar value.
• pyo3: enables PyO3 bindings for Python interop via #[pyclass] and #[pymethods].

Panics and errors

This crate does not define an error type and does not return Result from its core operations. For floating-point scalars (f64, f32), arithmetic follows IEEE-754 behavior (NaN and infinities propagate). For integer scalars, abs() uses saturating semantics at the minimum value (e.g. i32::MIN.abs() returns i32::MAX instead of panicking). Standard integer overflow rules still apply to addition, subtraction, and multiplication.

SemVer and stability

This crate is currently 0.x. Expect breaking changes between minor versions until 1.0.

Re-exports

pub use scalar::Exact;

pub use scalar::IntegerScalar;

pub use scalar::Real;

pub use scalar::Scalar;

pub use scalar::Transcendental;

pub use unit_arithmetic::QuantityDivOutput;

pub use unit_arithmetic::SameDivOutput;

pub use unit_arithmetic::UnitDiv;

pub use unit_arithmetic::UnitMul;

pub use unit_arithmetic::UnitSqrt;

pub use units::acceleration;

pub use units::angular;

pub use units::angular_rate;

pub use units::area;

pub use units::dimensionless;

pub use units::energy;

pub use units::force;

pub use units::length;

pub use units::mass;

pub use units::power;

pub use units::pressure;

pub use units::solid_angle;

pub use units::temperature;

pub use units::time;

pub use units::velocity;

pub use units::volume;

Modules

scalar

Scalar traits for quantity values.

unit_arithmetic

Stable unit arithmetic layer: UnitDiv and UnitMul traits. Stable, macro-generated unit arithmetic layer.

units

Predefined unit modules (grouped by dimension).

Macros

impl_unit_arithmetic_pairs

Convenience macro that generates both division and multiplication pair tables for a set of units.

impl_unit_arithmetic_pairs_between

Convenience macro that generates both division and multiplication impls between an existing base group and a new extra group.

impl_unit_conversions

Generates all pairwise conversions and cross-unit comparisons.

impl_unit_cross_unit_ops

Generates cross-unit PartialEq and PartialOrd implementations for all pairs of units.

impl_unit_cross_unit_ops_between

Generates cross-unit PartialEq and PartialOrd implementations between every unit in the extra group and every unit in the base group, plus all intra-extra pairs.

impl_unit_division_pairs

Generates UnitDiv impls for all ordered pairs of distinct units.

impl_unit_division_pairs_between

Generates UnitDiv impls between every unit in the extra group and every unit in the base group, plus all intra-extra pairs.

impl_unit_from_conversions

Generates bidirectional From trait implementations for all pairs of units within a dimension.

impl_unit_from_conversions_between

Generates From implementations between every unit in the extra group and every unit in the base group, plus all intra-extra pairs.

impl_unit_multiplication_pairs

Generates UnitMul impls for all ordered pairs of units, including self-pairs (A * A).

impl_unit_multiplication_pairs_between

Generates UnitMul impls between every unit in the extra group and every unit in the base group, plus all intra-extra pairs.

Structs

Per

Unit representing the division of two other units.

Prod

Unit representing the product of two other units.

Quantity

A quantity with a specific unit and scalar type.

Traits

Dimension

Marker trait for dimensions.

Unit

Trait implemented by every unit type.

Type Aliases

Acceleration

Acceleration (L¹ · T⁻²).

AmountOfSubstance

Amount of substance (N¹).

Angular

Plane angle (A¹) — treated as an independent dimension for type safety.

AngularRate

Angular rate (A¹ · T⁻¹) — angular displacement per unit time.

Area

Area (L²).

Capacitance

Electrical capacitance (M⁻¹ · L⁻² · T⁴ · I²) — SI unit: farad (F).

Charge

Electric charge (I¹ · T¹) — SI unit: coulomb (C = A·s).

Current

Electric current (I¹).

Density

Mass density (M¹ · L⁻³) — SI unit: kg·m⁻³.

Dimensionless

Dimensionless (all exponents zero).

Energy

Energy (M¹ · L² · T⁻²).

Force

Force (M¹ · L¹ · T⁻²).

Frequency

Frequency (T⁻¹) — reciprocal time, SI unit: hertz (Hz = s⁻¹).

Illuminance

Illuminance (J¹ · A² · L⁻²) — luminous flux per unit area; SI unit: lux (lx = lm·m⁻²).

Inductance

Electrical inductance (M¹ · L² · T⁻² · I⁻²) — SI unit: henry (H).

InverseSolidAngle

Inverse solid angle (A⁻²) — used by photometric brightness scales such as the S10 “10th-magnitude stars per square degree” unit.

Length

Length (L¹).

LuminousFlux

Luminous flux (J¹ · A²) — radiant power weighted by the luminosity function; SI unit: lumen (lm = cd·sr).

LuminousIntensity

Luminous intensity (J¹).

MagneticFlux

Magnetic flux (M¹ · L² · T⁻² · I⁻¹) — SI unit: weber (Wb).

MagneticFluxDensity

Magnetic flux density / magnetic field (M¹ · T⁻² · I⁻¹) — SI unit: tesla (T).

Mass

Mass (M¹).

PhotonRadiance

Photon radiance (L⁻² · T⁻¹ · A⁻²) — photon count per area per time per solid angle (e.g. ph·cm⁻²·s⁻¹·sr⁻¹). Photons are treated as dimensionless counts.

Power

Power (M¹ · L² · T⁻³).

Pressure

Pressure (M¹ · L⁻¹ · T⁻²) — equivalently, force per unit area (N/m²).

Quantity32

A quantity backed by f32.

Quantity64

A quantity backed by f64 (the default).

QuantityI8

A quantity backed by i8.

QuantityI16

A quantity backed by i16.

QuantityI32

A quantity backed by i32.

QuantityI64

A quantity backed by i64.

QuantityI128

A quantity backed by i128.

Radiance

Radiance (M¹ · T⁻³ · A⁻²) — radiant power per unit area per unit solid angle (e.g. W·m⁻²·sr⁻¹).

Resistance

Electrical resistance (M¹ · L² · T⁻³ · I⁻²) — SI unit: ohm (Ω).

SolidAngle

Solid angle (A²) — plane angle squared (e.g. steradian, square degree).

SpectralPhotonRadiance

Spectral photon radiance per unit wavelength (L⁻³ · T⁻¹ · A⁻²) — photon radiance per unit wavelength (e.g. ph·cm⁻²·s⁻¹·sr⁻¹·Å⁻¹).

SpectralRadiance

Spectral radiance per unit wavelength (L⁻¹ · M¹ · T⁻³ · A⁻²) — radiance per unit wavelength (e.g. W·m⁻²·sr⁻¹·nm⁻¹).

Temperature

Thermodynamic temperature (Θ¹).

Time

Time (T¹).

Velocity

Velocity (L¹ · T⁻¹).

Voltage

Voltage / electromotive force (M¹ · L² · T⁻³ · I⁻¹) — SI unit: volt (V).

Volume

Volume (L³).