hmf.core.units

The units boundary of the v4 core.

hmf.core follows one units policy (“option B” of issue #389):

  • Quantities at every public boundary. Stage fields, public model and stage methods, and all their outputs carry astropy.units.Quantity.

  • Unit-free kernels inside. The numerics in hmf.core._kernels work on plain arrays in the canonical units of CANONICAL_UNITS.

  • h-units are explicit, through littleh (astropy.cosmology.units.littleh). Outputs are in h-units. Inputs may be in h-units or in physical units; physical units are converted with the H0 of the object whose method is called.

The unit_boundary() decorator is the bridge between the two. It strips the units off dimensional arguments, converting them to the canonical unit first if needed, and puts the canonical unit on the outputs. Its fixed cost is budgeted at 2 µs per call (benchmarks/test_core_units.py measures it), so it uses Quantity views and per-instance cached conversion factors, not astropy.units.quantity_input().

Rules

  • Use the constants in this module (Msun_h, Mpc_h, …) whenever you attach a unit. A freshly built u.Msun / cu.littleh equals Msun_h, but it is a different object, so it misses the boundary’s identity fast path.

  • A bare float or ndarray for a dimensional argument is an error (UnitBoundaryError). hmf never guesses units.

  • Dimensionless arguments (z, sigma, peak height, delta_c, Omega, …) are plain floats or arrays, and pass through the boundary unchanged.

  • Never enable with_H0() globally (with astropy.units.set_enabled_equivalencies()): inside it, h-scaled and physical values convert into each other silently. hmf only ever passes it explicitly, for one conversion at a time.

  • Take logarithms of values in an explicit unit: np.log10(m / Msun_h), never np.log10(m.value) (whose unit is whatever the caller used).

Classes

HasUnitContext(*args, **kwargs)

An object whose unit_boundary() methods can convert physical units.

UnitContext([H0])

Per-instance unit-conversion state: the H0, and cached conversion factors.

Functions

littleh_power(unit)

Return the power of littleh in unit (0 if it has none).

littleh_units_enabled()

Enable parsing of unit strings that contain littleh.

parse_unit(text)

Parse a unit string that may contain littleh, e.g. from a config file.

unit_boundary(*[, returns])

Make a method a units boundary: Quantities outside, plain arrays inside.

Exceptions

UnitBoundaryError

A dimensional argument was given without units (a bare float or array).