Field Registry¶

Field metadata registry mapping canonical field names to quantity types, SI unit labels, human-readable names, and LaTeX symbols. Single source of truth for field display metadata.

`fields` ¶

Field metadata registry: names, units, and display labels.

Maps every canonical field name to its physical quantity type, SI unit label, human-readable long name, and LaTeX symbol. The literal lives in pypic._field_table; this module resolves lookups through the alias and species-pattern fallbacks, and owns register_field. compute.field_si_factor reads the table directly at lookup time.

`FieldInfo` `dataclass` ¶

Metadata for a single field or derived quantity.

Parameters:

Name	Type	Description	Default
`quantity_type`	`str`	Physical quantity type matching `Normalization.si_factor()` (e.g. `"b_field"`, `"pressure"`, `"dimensionless"`).	required
`long_name`	`str`	Human-readable name (e.g. `"Magnetic field component 1"`).	required
`si_unit`	`str`	SI unit label (e.g. `"T"`, `"Pa"`, `""` for dimensionless).	required
`latex`	`str`	LaTeX symbol for plot labels (e.g. `r"$B_1$"`).	`''`
`unit_dimension`	`tuple[int, ...] \| None`	openPMD-style 7-tuple of integer SI base-unit powers (length, mass, time, current, temperature, amount, luminosity). `None` (the default) defers to `quantity_dimension(quantity_type)` at attrs-population time; a non-`None` value overrides the canonical lookup for custom-registered fields.	`None`

Source code in src/pypic/_field_table.py

@dataclass(frozen=True, slots=True)
class FieldInfo:
    r"""Metadata for a single field or derived quantity.

    Parameters
    ----------
    quantity_type : str
        Physical quantity type matching ``Normalization.si_factor()``
        (e.g. ``"b_field"``, ``"pressure"``, ``"dimensionless"``).
    long_name : str
        Human-readable name (e.g. ``"Magnetic field component 1"``).
    si_unit : str
        SI unit label (e.g. ``"T"``, ``"Pa"``, ``""`` for dimensionless).
    latex : str
        LaTeX symbol for plot labels (e.g. ``r"$B_1$"``).
    unit_dimension : tuple[int, ...] | None
        openPMD-style 7-tuple of integer SI base-unit powers
        (length, mass, time, current, temperature, amount, luminosity).
        ``None`` (the default) defers to ``quantity_dimension(quantity_type)``
        at attrs-population time; a non-``None`` value overrides the
        canonical lookup for custom-registered fields.
    """

    quantity_type: str
    long_name: str
    si_unit: str
    latex: str = ""
    unit_dimension: tuple[int, int, int, int, int, int, int] | None = None

`QuantityType` ¶

Bases: StrEnum

Physical quantity types for field metadata and SI conversion.

Each member corresponds to a key in Normalization.si_factor() and maps to a default SI unit label. Since QuantityType is a StrEnum, members compare equal to plain strings: QuantityType.B_FIELD == "b_field" is True.

Examples:

>>> QuantityType.B_FIELD
<QuantityType.B_FIELD: 'b_field'>
>>> QuantityType.B_FIELD == "b_field"
True

Source code in src/pypic/fields.py

class QuantityType(StrEnum):
    """Physical quantity types for field metadata and SI conversion.

    Each member corresponds to a key in ``Normalization.si_factor()``
    and maps to a default SI unit label.  Since ``QuantityType`` is a
    ``StrEnum``, members compare equal to plain strings:
    ``QuantityType.B_FIELD == "b_field"`` is ``True``.

    Examples
    --------
    >>> QuantityType.B_FIELD
    <QuantityType.B_FIELD: 'b_field'>
    >>> QuantityType.B_FIELD == "b_field"
    True
    """

    B_FIELD = "b_field"
    E_FIELD = "e_field"
    VELOCITY = "velocity"
    FOUR_VELOCITY = "four_velocity"
    LENGTH = "length"
    TIME = "time"
    DENSITY = "density"
    MASS_DENSITY = "mass_density"
    CHARGE_DENSITY = "charge_density"
    CURRENT_DENSITY = "current_density"
    PRESSURE = "pressure"
    TEMPERATURE = "temperature"
    ENERGY_DENSITY = "energy_density"
    FREQUENCY = "frequency"
    POYNTING_FLUX = "poynting_flux"
    ENERGY_FLUX = "energy_flux"
    B_FIELD_PER_LENGTH = "b_field_per_length"
    E_FIELD_PER_LENGTH = "e_field_per_length"
    VELOCITY_PER_LENGTH = "velocity_per_length"
    SPECIFIC_ENERGY = "specific_energy"
    POWER_DENSITY = "power_density"
    DIMENSIONLESS = "dimensionless"

`quantity_dimension(quantity)` ¶

Return the openPMD unitDimension 7-tuple for a quantity type.

The tuple gives integer powers of the SI base units in the order (length, mass, time, current, temperature, amount, luminosity).

Parameters:

Name	Type	Description	Default
`quantity`	`str or QuantityType`	Physical quantity type — one of the keys in `_QUANTITY_UNITS`.	required

Returns:

Type	Description
`tuple[int, ...]`	Seven-element tuple of integer dimensional powers.

Raises:

Type	Description
`KeyError`	If quantity is not a recognized quantity type.

Examples:

>>> quantity_dimension("b_field")
(0, 1, -2, -1, 0, 0, 0)
>>> quantity_dimension(QuantityType.VELOCITY)
(1, 0, -1, 0, 0, 0, 0)
>>> quantity_dimension("dimensionless")
(0, 0, 0, 0, 0, 0, 0)

Source code in src/pypic/fields.py

def quantity_dimension(
    quantity: str | QuantityType,
) -> tuple[int, int, int, int, int, int, int]:
    r"""Return the openPMD ``unitDimension`` 7-tuple for a quantity type.

    The tuple gives integer powers of the SI base units in the order
    *(length, mass, time, current, temperature, amount, luminosity)*.

    Parameters
    ----------
    quantity : str or QuantityType
        Physical quantity type — one of the keys in ``_QUANTITY_UNITS``.

    Returns
    -------
    tuple[int, ...]
        Seven-element tuple of integer dimensional powers.

    Raises
    ------
    KeyError
        If *quantity* is not a recognized quantity type.

    Examples
    --------
    >>> quantity_dimension("b_field")
    (0, 1, -2, -1, 0, 0, 0)
    >>> quantity_dimension(QuantityType.VELOCITY)
    (1, 0, -1, 0, 0, 0, 0)
    >>> quantity_dimension("dimensionless")
    (0, 0, 0, 0, 0, 0, 0)
    """
    key = quantity.value if isinstance(quantity, QuantityType) else quantity
    return _QUANTITY_DIMENSIONS[key]

`register_field(name, quantity_type, *, long_name='', si_unit=None, latex='', unit_dimension=None)` ¶

Register metadata for a custom field.

Enables field_info(), field_si_factor(), in_si(), in_units(), and unit_label() for user-defined fields.

Parameters:

Name	Type	Description	Default
`name`	`str`	Field name (e.g. `"my_diagnostic"`).	required
`quantity_type`	`QuantityType \| str`	Physical quantity type — must be a key in `_QUANTITY_UNITS` (e.g. `QuantityType.VELOCITY`, `"pressure"`).	required
`long_name`	`str`	Human-readable label for plot titles.	`''`
`si_unit`	`str \| None`	SI unit label. If `None`, inferred from quantity_type.	`None`
`latex`	`str`	LaTeX symbol for plot labels.	`''`
`unit_dimension`	`tuple[int, ...] \| None`	openPMD `unitDimension` 7-tuple (powers of length, mass, time, current, temperature, amount, luminosity). `None` (the default) uses `quantity_dimension(quantity_type)`. Provide an explicit tuple only for non-canonical fields whose dimension differs from the standard lookup.	`None`

Raises:

Type	Description
`ValueError`	If quantity_type is not recognized, unit_dimension is not a length-7 sequence of ints, or name is already registered.

Source code in src/pypic/fields.py

def register_field(
    name: str,
    quantity_type: QuantityType | str,
    *,
    long_name: str = "",
    si_unit: str | None = None,
    latex: str = "",
    unit_dimension: tuple[int, int, int, int, int, int, int] | None = None,
) -> None:
    """Register metadata for a custom field.

    Enables ``field_info()``, ``field_si_factor()``, ``in_si()``,
    ``in_units()``, and ``unit_label()`` for user-defined fields.

    Parameters
    ----------
    name : str
        Field name (e.g. ``"my_diagnostic"``).
    quantity_type : QuantityType | str
        Physical quantity type — must be a key in ``_QUANTITY_UNITS``
        (e.g. ``QuantityType.VELOCITY``, ``"pressure"``).
    long_name : str
        Human-readable label for plot titles.
    si_unit : str | None
        SI unit label.  If ``None``, inferred from *quantity_type*.
    latex : str
        LaTeX symbol for plot labels.
    unit_dimension : tuple[int, ...] | None
        openPMD ``unitDimension`` 7-tuple (powers of length, mass,
        time, current, temperature, amount, luminosity).  ``None``
        (the default) uses ``quantity_dimension(quantity_type)``.
        Provide an explicit tuple only for non-canonical fields whose
        dimension differs from the standard lookup.

    Raises
    ------
    ValueError
        If *quantity_type* is not recognized, *unit_dimension* is not a
        length-7 sequence of ints, or *name* is already registered.
    """
    if quantity_type not in _QUANTITY_UNITS:
        valid = sorted(_QUANTITY_UNITS)
        msg = f"Unknown quantity_type {quantity_type!r}. Valid: {valid}"
        raise ValueError(msg)

    if si_unit is None:
        si_unit = _QUANTITY_UNITS[quantity_type]

    if unit_dimension is not None:
        if len(unit_dimension) != 7 or not all(
            isinstance(p, int) for p in unit_dimension
        ):
            msg = f"unit_dimension must be a 7-tuple of ints, got {unit_dimension!r}"
            raise ValueError(msg)
        unit_dimension = tuple(unit_dimension)  # type: ignore[assignment]

    info = FieldInfo(quantity_type, long_name, si_unit, latex, unit_dimension)

    with _lock:
        if name in _FIELD_INFO:
            msg = f"Field metadata for {name!r} is already registered"
            raise ValueError(msg)
        _FIELD_INFO[name] = info

`unregister_field(name)` ¶

Remove custom field metadata.

Raises:

Type	Description
`KeyError`	If name is not registered.

Source code in src/pypic/fields.py

def unregister_field(name: str) -> None:
    """Remove custom field metadata.

    Raises
    ------
    KeyError
        If *name* is not registered.
    """
    with _lock:
        try:
            del _FIELD_INFO[name]
        except KeyError:
            msg = f"No field metadata registered for {name!r}"
            raise KeyError(msg) from None

`field_info(name, *, axis_names=None)` ¶

Look up metadata for a field or derived quantity.

Resolution order:

Direct lookup in the registry
Compute alias resolution ("B_mag" -> "|B|")
Field alias fallback ("Bx" -> "B_1")
Per-species regex patterns ("n_s5", "omega_p_s3")

Parameters:

Name	Type	Description	Default
`name`	`str`	Field or derived quantity name.	required
`axis_names`	`tuple[str, str, str] \| None`	Coordinate axis labels. When provided, component labels are localized (e.g. "component 1" -> "x-component" for Cartesian).	`None`

Returns:

Type	Description
`FieldInfo`

Raises:

Type	Description
`KeyError`	If name cannot be resolved.

Examples:

>>> field_info("|B|").si_unit
'T'
>>> field_info("beta").latex
'$\\beta$'
>>> field_info("B_1", axis_names=("x", "y", "z")).long_name
'Magnetic field x-component'

Source code in src/pypic/fields.py

def field_info(
    name: str, *, axis_names: tuple[str, str, str] | None = None
) -> FieldInfo:
    r"""Look up metadata for a field or derived quantity.

    Resolution order:

    1. Direct lookup in the registry
    2. Compute alias resolution (``"B_mag"`` -> ``"|B|"``)
    3. Field alias fallback (``"Bx"`` -> ``"B_1"``)
    4. Per-species regex patterns (``"n_s5"``, ``"omega_p_s3"``)

    Parameters
    ----------
    name : str
        Field or derived quantity name.
    axis_names : tuple[str, str, str] | None
        Coordinate axis labels.  When provided, component labels are
        localized (e.g. "component 1" -> "x-component" for Cartesian).

    Returns
    -------
    FieldInfo

    Raises
    ------
    KeyError
        If *name* cannot be resolved.

    Examples
    --------
    >>> field_info("|B|").si_unit
    'T'
    >>> field_info("beta").latex
    '$\\beta$'
    >>> field_info("B_1", axis_names=("x", "y", "z")).long_name
    'Magnetic field x-component'
    """

    def _maybe_localize(info: FieldInfo) -> FieldInfo:
        if axis_names is not None:
            return _localize_field_info(info, axis_names)
        return info

    # 1. Direct lookup
    info = _FIELD_INFO.get(name)
    if info is not None:
        return _maybe_localize(info)

    # 2. Compute alias resolution (B_mag -> |B|, etc.)
    canonical = COMPUTE_ALIASES.get(name)
    if canonical is not None:
        info = _FIELD_INFO.get(canonical)
        if info is not None:
            return _maybe_localize(info)

    # 3. Field alias fallback (Bx -> B_1, P_e -> Pe, etc.)
    fallback = _get_field_alias_fallback()
    target = canonical if canonical is not None else name
    resolved = fallback.get(target, name)
    info = _FIELD_INFO.get(resolved)
    if info is not None:
        return _maybe_localize(info)

    # 4. Per-species regex patterns
    species_info = _try_species_info(target)
    if species_info is not None:
        return _maybe_localize(species_info)
    if resolved != target:
        species_info = _try_species_info(resolved)
        if species_info is not None:
            return _maybe_localize(species_info)

    msg = f"No metadata for field {name!r}"
    raise UnknownFieldError(msg)

`vector_component(name)` ¶

Split a registered vector component name into (base, component).

The Tier-3 form <base>_<component> with a registered metadata entry marks a vector component: B_1, KEF_s0_2, E_prime_3. Scalars, tensor components (P_s0_11) and unregistered names return None.

Parameters:

Name	Type	Description	Default
`name`	`str`	Field or derived quantity name.	required

Returns:

Type	Description
`tuple[str, int] \| None`	Vector base name and 1-based component, or `None`.

Examples:

>>> vector_component("B_1")
('B', 1)
>>> vector_component("KEF_s0_2")
('KEF_s0', 2)
>>> vector_component("P_s0_11") is None
True
>>> vector_component("rho_c") is None
True

Source code in src/pypic/fields.py

def vector_component(name: str) -> tuple[str, int] | None:
    """Split a registered vector component name into ``(base, component)``.

    The Tier-3 form ``<base>_<component>`` with a registered metadata
    entry marks a vector component: ``B_1``, ``KEF_s0_2``, ``E_prime_3``.
    Scalars, tensor components (``P_s0_11``) and unregistered names
    return ``None``.

    Parameters
    ----------
    name : str
        Field or derived quantity name.

    Returns
    -------
    tuple[str, int] | None
        Vector base name and 1-based component, or ``None``.

    Examples
    --------
    >>> vector_component("B_1")
    ('B', 1)
    >>> vector_component("KEF_s0_2")
    ('KEF_s0', 2)
    >>> vector_component("P_s0_11") is None
    True
    >>> vector_component("rho_c") is None
    True
    """
    m = _COMPONENT_SUFFIX_RE.match(name)
    if m is None:
        return None
    try:
        field_info(name)
    except UnknownFieldError:
        return None
    return m.group("base"), int(m.group("component"))

`unit_label(name, *, to_si=False)` ¶

Return a unit label string for a field, suitable for plot axes.

Parameters:

Name	Type	Description	Default
`name`	`str`	Field or derived quantity name.	required
`to_si`	`bool`	If `True`, return the SI unit label (e.g. `"T"`). If `False`, return `"normalized"` or `""` for dimensionless.	`False`

Returns:

Type	Description
`str`

Examples:

>>> unit_label("B_1", to_si=True)
'T'
>>> unit_label("B_1")
'normalized'
>>> unit_label("beta", to_si=True)
''
>>> unit_label("beta")
''

Source code in src/pypic/fields.py

def unit_label(name: str, *, to_si: bool = False) -> str:
    r"""Return a unit label string for a field, suitable for plot axes.

    Parameters
    ----------
    name : str
        Field or derived quantity name.
    to_si : bool
        If ``True``, return the SI unit label (e.g. ``"T"``).
        If ``False``, return ``"normalized"`` or ``""`` for dimensionless.

    Returns
    -------
    str

    Examples
    --------
    >>> unit_label("B_1", to_si=True)
    'T'
    >>> unit_label("B_1")
    'normalized'
    >>> unit_label("beta", to_si=True)
    ''
    >>> unit_label("beta")
    ''
    """
    info = field_info(name)
    if to_si:
        return info.si_unit
    return "" if info.quantity_type == "dimensionless" else "normalized"

`quantity_units(quantity_type)` ¶

Return the SI unit label for a physical quantity type.

Parameters:

Name	Type	Description	Default
`quantity_type`	`str`	Quantity type string (e.g. `"b_field"`, `"pressure"`).	required

Returns:

Type	Description
`str`	SI unit label.

Raises:

Type	Description
`KeyError`	If quantity_type is unknown.

Examples:

>>> quantity_units("b_field")
'T'
>>> quantity_units("dimensionless")
''

Source code in src/pypic/fields.py

def quantity_units(quantity_type: str) -> str:
    r"""Return the SI unit label for a physical quantity type.

    Parameters
    ----------
    quantity_type : str
        Quantity type string (e.g. ``"b_field"``, ``"pressure"``).

    Returns
    -------
    str
        SI unit label.

    Raises
    ------
    KeyError
        If *quantity_type* is unknown.

    Examples
    --------
    >>> quantity_units("b_field")
    'T'
    >>> quantity_units("dimensionless")
    ''
    """
    try:
        return _QUANTITY_UNITS[quantity_type]
    except KeyError:
        valid = sorted(_QUANTITY_UNITS)
        msg = f"Unknown quantity type {quantity_type!r}. Valid: {valid}"
        raise KeyError(msg) from None

Field Registry¶

fields ¶

FieldInfo dataclass ¶

QuantityType ¶

quantity_dimension(quantity) ¶

register_field(name, quantity_type, *, long_name='', si_unit=None, latex='', unit_dimension=None) ¶

unregister_field(name) ¶

field_info(name, *, axis_names=None) ¶

vector_component(name) ¶

unit_label(name, *, to_si=False) ¶

quantity_units(quantity_type) ¶

`fields` ¶

`FieldInfo` `dataclass` ¶

`QuantityType` ¶

`quantity_dimension(quantity)` ¶

`register_field(name, quantity_type, *, long_name='', si_unit=None, latex='', unit_dimension=None)` ¶

`unregister_field(name)` ¶

`field_info(name, *, axis_names=None)` ¶

`vector_component(name)` ¶

`unit_label(name, *, to_si=False)` ¶

`quantity_units(quantity_type)` ¶