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.

__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.

LinearMap dataclass

Bases: Map

A linear conversion: y = a * x.

derivative(x)

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

AffineMap dataclass

Bases: Map

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

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.

__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)).

derivative(x)

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