Skip to content

ucon.maps

Composable conversion morphisms. All unit conversions in ucon are expressed as Map instances.

ucon.maps

Implements the Map class hierarchy — the composable substrate for all unit conversion morphisms in ucon.

Classes

  • :class:Map — Abstract base for conversion morphisms.
  • :class:LinearMap — y = a * x
  • :class:AffineMap — y = a * x + b
  • :class:LogMap — y = scale * log_base(x) + offset
  • :class:ExpMap — y = base^(scale * x + offset)
  • :class:ReciprocalMap — y = a / x (inversely proportional)
  • :class:ComposedMap — Generic composition fallback: g(f(x))

All maps support both scalar and numpy array inputs. NumPy is optional; scalar operations use the standard library math module.

Map

Bases: ABC

Abstract base for all conversion morphisms.

Subclasses must implement __call__, inverse, __pow__, and derivative. Composition via @ defaults to :class:ComposedMap; subclasses may override for closed composition within their own type.

All concrete maps carry a rel_uncertainty property (default 0.0) representing the relative standard uncertainty of the conversion factor. This is nonzero for edges derived from measured physical constants (e.g., Hartree energy, Planck mass). Uncertainty composes through @ via quadrature and is preserved through inverse().

rel_uncertainty property

Relative uncertainty of the conversion factor. Default: 0 (exact).

__call__(x) abstractmethod

Apply the map to a numeric value.

inverse() abstractmethod

Return the inverse map.

__matmul__(other) abstractmethod

Compose: (f @ g)(x) == f(g(x)).

__pow__(exp) abstractmethod

Raise map to a power (for exponent handling in factorwise conversion).

derivative(x) abstractmethod

Return the derivative of the map at point x.

Used for uncertainty propagation: δy = |f'(x)| * δx

is_identity(tol=1e-09)

Check if this map is approximately the identity.

to_dict()

Serialize this map to a TOML-friendly dict.

Map-valued fields are recursively serialized via their own to_dict(). Lists are handled element-wise.

LinearMap dataclass

Bases: Map

A linear conversion: y = a * x.

Parameters

a : float Scale factor. rel_uncertainty : float Relative standard uncertainty of a. Default 0.0 (exact). Nonzero for factors derived from measured constants (e.g., CODATA).

derivative(x)

Derivative of y = a*x is a (constant).

AffineMap dataclass

Bases: Map

An affine conversion: y = a * x + b.

Parameters

a : float Slope (scale factor). b : float Offset. rel_uncertainty : float Relative standard uncertainty of the slope a. Default 0.0 (exact). The offset b is always treated as exact.

derivative(x)

Derivative of y = a*x + b is a (constant).

LogMap dataclass

Bases: Map

Logarithmic map: y = scale * log_base(x / reference) + offset

Parameters

scale : float Multiplier for logarithm (10 for dB power, 20 for dB amplitude) base : float Logarithm base (10 for dB, e for neper) reference : float Reference value; x/reference is the argument to log. Default 1.0 means pure ratio (no reference level). offset : float Added after logarithm (rarely used)

Examples::

LogMap()                           # log₁₀(x) — pure ratio
LogMap(scale=10)                   # 10·log₁₀(x) — bel×10 (dB power)
LogMap(scale=10, reference=0.001)  # 10·log₁₀(x/1mW) — dBm
LogMap(scale=-1)                   # -log₁₀(x) — pH-style
LogMap(base=math.e)                # ln(x) — neper

For transforms like nines (-log₁₀(1-x)), compose with AffineMap::

LogMap(scale=-1) @ AffineMap(a=-1, b=1)

__call__(x)

Apply the logarithmic map. Works with scalars and numpy arrays.

inverse()

Return the inverse exponential map.

derivative(x)

Derivative: d/dx[scale * log_base(x/ref)] = scale / (x * ln(base))

Works with both scalars and numpy arrays.

ExpMap dataclass

Bases: Map

Exponential map: y = reference * base^(scale * x + offset)

This is the inverse of :class:LogMap. Typically obtained via LogMap.inverse() rather than constructed directly.

Parameters

scale : float Multiplier for the exponent. base : float Base of the exponential (10 for dB, e for neper). reference : float Multiplier for the result. Default 1.0 for pure ratio. offset : float Added to exponent before evaluation.

__call__(x)

Apply the exponential map. Works with scalars and numpy arrays.

inverse()

Return the inverse logarithmic map.

derivative(x)

Derivative: d/dx[ref * base^(scalex + offset)] = ln(base) * scale * ref * base^(scalex + offset)

Works with both scalars and numpy arrays.

ReciprocalMap dataclass

Bases: Map

Inversely proportional map: y = a / x.

Used for cross-dimensional conversions where quantities are inversely related through a physical constant (e.g., wavelength and frequency via c = λν).

Parameters

a : float The constant of proportionality. rel_uncertainty : float Relative uncertainty of the constant a. Default: 0.0 (exact).

__call__(x)

Apply the inverse map. Works with scalars and numpy arrays.

inverse()

ReciprocalMap is self-inverse: if y = a/x, then x = a/y.

derivative(x)

Derivative: d/dx[a/x] = -a/x². Works with scalars and numpy arrays.

ComposedMap dataclass

Bases: Map

Generic composition fallback: (outer ∘ inner)(x) = outer(inner(x)).

rel_uncertainty is computed as a property: sqrt(outer.rel_uncertainty**2 + inner.rel_uncertainty**2).

derivative(x)

Chain rule: d/dx [outer(inner(x))] = outer'(inner(x)) * inner'(x).