Unit Management and Conversions

This module provides a centralized system for handling physical units, constants, and conversions within the litebird_sim pipeline. It ensures consistency between thermodynamic temperatures (\(K_{CMB}\)), brightness temperatures (\(K_{RJ}\)), and flux densities.

The module leverages pysm3.units and astropy.units to perform physically accurate conversions including frequency-dependent equivalencies.

Supported Units

The following units are supported via the Units Enum:

class litebird_sim.units.Units(value)

Enum for supported units in litebird_sim.

Inheriting from str allows these members to be passed directly to functions expecting standard unit strings (e.g., ‘uK_CMB’ for PySM or Astropy), while ensuring type safety within the simulation pipeline.

K_CMB = 'K_CMB'

mK_CMB = 'mK_CMB'

uK_CMB = 'uK_CMB'

K_RJ = 'K_RJ'

mK_RJ = 'mK_RJ'

uK_RJ = 'uK_RJ'

MJy_over_sr = 'MJy/sr'

Jy_over_sr = 'Jy/sr'

ADU = 'ADU'

Pure = 'dimensionless'

Utility Functions

The UnitUtils class provides static methods to handle conversion logic and plot labeling.

class litebird_sim.units.UnitUtils

Bases: object

Static utility class to handle physical logic, conversions, and formatting for the Units Enum.

It delegates physical constants and conversion formulas to astropy.units to ensure consistency with the input model generation (PySM 3).

static get_astropy_unit(unit: Units)

Returns the actual astropy.unit object corresponding to the Enum.

This handles the instantiation of the unit object from the string value.

static get_conversion_factor(unit_from: Units, unit_to: Units, freq_ghz: float | None = None) → float

Calculates the multiplicative factor to convert between units using Astropy equivalencies.

Formula: value_out = value_in * factor

Parameters:

• unit_from (Units) – The source unit.

• unit_to (Units) – The destination unit.

• freq_ghz (float, optional) – Frequency in Gigahertz (GHz). Strictly required for conversions involving Flux (MJy/sr) or transformations between CMB and RJ temperatures.

Returns:

The scalar conversion factor.

Return type:

float

Raises:

ValueError – If ADU is involved (requires instrument gain) or if frequency is missing for spectral conversions.

static get_label(unit: Units) → str

Returns the LaTeX string label for the unit (e.g., for plotting).

static is_flux(unit: Units) → bool

Returns True if the unit is flux density or surface brightness.

static is_pysm3_compatible(unit: Units) → bool

Returns True if the unit is pysm3 compatible.

static is_temperature(unit: Units) → bool

Returns True if the unit is a thermodynamic or brightness temperature.

Examples

Converting from \(\mu K_{CMB}\) to \(\mathrm{MJy/sr}\) at 100 GHz:

from litebird_sim.units import Units, UnitUtils

freq = 100.0  # GHz
factor = UnitUtils.get_conversion_factor(Units.uK_CMB, Units.MJy_over_sr, freq_ghz=freq)
print(f"Conversion factor: {factor}")

Getting a LaTeX label for a plot:

label = UnitUtils.get_label(Units.uK_RJ)
# Returns: r"$\mu K_{\mathrm{RJ}}$"