Schema Validation

The Pydantic v2 models that define the simulation.toml v1.0 contract, and validate_simulation_toml(), the entry point that returns a strictly typed SimulationSchema.

This subpackage is authoritative: readers.config.load_config() is a thin translator that delegates all shape validation here and then maps the result onto the internal SimulationConfig / GridInfo / Normalization / SpeciesInfo. It deliberately has no pypic-internal imports — only stdlib and pydantic — so it can be lifted into a standalone distribution.

The prose specification is Schema; the annotated reference template is pypic.simulation.toml at the repository root. A generated JSON Schema ships in the wheel for consumers that are not running Python:

uv run pypic schema export -o simulation.schema.v2.0.json
uv run pypic schema validate path/to/simulation.toml
uv run pypic schema diff path/to/proposed.json

schema

Pydantic v2 validator for the pypic simulation.toml v2.0 schema.

Designed to be decoupled from pypic itself — the only imports are stdlib and pydantic, so this subpackage can be lifted into a standalone distribution without modification.

Entry point: validate_simulation_toml, which accepts a path, a TOML text blob, or a pre-parsed dict and returns a fully typed SimulationSchema root model.

Examples:

>>> from pypic.schema import validate_simulation_toml
>>> doc = '''
... [schema]
... version = "2.0"
... [model]
... name = "demo"
... type = "PIC"
... [run]
... name = "r0"
... [time]
... scheme = "fixed"
... dt = 0.1
... t_start = 0.0
... t_end = 1.0
... n_steps = 10
... [grid]
... dimensions = [4, 4, 4]
... spacing = [1.0, 1.0, 1.0]
... lower = [0.0, 0.0, 0.0]
... upper = [4.0, 4.0, 4.0]
... [units]
... anchor = "si"
... [coordinates]
... geometry = "cartesian"
... frame = "sim"
... [[species]]
... name = "electrons"
... charge = -1.0
... mass = 1.0
... '''
>>> s = validate_simulation_toml(doc)
>>> s.model.type
'PIC'

Allocation

Bases: _StrictBase

One entry in [[run.resources.allocations]] (heterogeneous HW).

Source code in src/pypic/schema/_models.py

class Allocation(_StrictBase):
    """One entry in ``[[run.resources.allocations]]`` (heterogeneous HW)."""

    type: Literal["cpu", "gpu", "tpu", "accelerator"]
    hardware: str
    count: PositiveInt
    hours: NonNegativeFloat

Author

Bases: _StrictBase

Person entry in [model].authors or [run].authors.

Source code in src/pypic/schema/_models.py

class Author(_StrictBase):
    """Person entry in ``[model].authors`` or ``[run].authors``."""

    name: str
    orcid: str | None = None
    affiliation: str | None = None
    role: str | None = None

Body

Bases: _StrictBase

One entry in [[bodies]] — registry of physical objects.

Source code in src/pypic/schema/_models.py

class Body(_StrictBase):
    """One entry in ``[[bodies]]`` — registry of physical objects."""

    name: str
    center: AxisFloat
    radius: PositiveFloat | None = None
    shape: ShapeLiteral = "sphere"
    intrinsic_dipole: Vec3Float | None = None
    dipole_center_offset: Vec3Float | None = None
    rotation_axis: Vec3Float | None = None
    rotation_period: NonNegativeFloat | None = None
    mass: PositiveFloat | None = None
    surface_absorbs_ions: bool | None = None
    has_atmosphere: bool | None = None
    has_intrinsic_field: bool | None = None

BoundaryConditions

Bases: BoundaryConditionsBase

[boundary_conditions] — per-face tag arrays.

The default form: one tag per face per axis applied uniformly to every field. field_overrides lets PIC PML simulations and solar-wind-driven runs declare different BCs for E (PML), B (PML), and particles (reflecting / absorbing / thermal-bath) at the same face. Each entry is a BoundaryConditionsBase matching the same axis count as the default.

Source code in src/pypic/schema/_models.py

class BoundaryConditions(BoundaryConditionsBase):
    """``[boundary_conditions]`` — per-face tag arrays.

    The default form: one tag per face per axis applied uniformly to
    every field. ``field_overrides`` lets PIC PML simulations and
    solar-wind-driven runs declare *different* BCs for E (PML), B (PML),
    and particles (reflecting / absorbing / thermal-bath) at the same
    face. Each entry is a `BoundaryConditionsBase` matching the
    same axis count as the default.
    """

    field_overrides: dict[BCFieldGroup, BoundaryConditionsBase] | None = None

    @model_validator(mode="after")
    def _check_overrides_axis_count(self) -> BoundaryConditions:
        if self.field_overrides is None:
            return self
        n = len(self.lower)
        for field_group, override in self.field_overrides.items():
            if len(override.lower) != n:
                raise ValueError(
                    f"boundary_conditions.field_overrides[{field_group!r}] "
                    f"has {len(override.lower)} axes but the default has {n}"
                )
        return self

BoundaryConditionsBase

Bases: _StrictBase

Reusable per-face BC vector + optional driver foreign keys.

lower / upper carry one tag per axis ("periodic", "reflecting", "open", "driven", ...). The vocabulary is free-form: validators don't constrain the strings, so different code families coexist without an upstream enum cut.

drivers_lower / drivers_upper link individual faces to a declared [[drivers]].name entry. Each is sparse: a dict keyed by axis index as a string ("0", "1", "2"), valued with the driver name. Faces without a driver simply don't appear. The root validator enforces foreign-key resolution against [[drivers]] and the axis-index range against grid.dimensions.

Source code in src/pypic/schema/_models.py

class BoundaryConditionsBase(_StrictBase):
    """Reusable per-face BC vector + optional driver foreign keys.

    ``lower`` / ``upper`` carry one tag per axis (``"periodic"``,
    ``"reflecting"``, ``"open"``, ``"driven"``, ...). The vocabulary is
    free-form: validators don't constrain the strings, so different code
    families coexist without an upstream enum cut.

    ``drivers_lower`` / ``drivers_upper`` link individual faces to a
    declared ``[[drivers]].name`` entry. Each is sparse: a dict keyed by
    axis index as a string (``"0"``, ``"1"``, ``"2"``), valued with the
    driver name. Faces without a driver simply don't appear. The root
    validator enforces foreign-key resolution against ``[[drivers]]``
    and the axis-index range against ``grid.dimensions``.
    """

    lower: list[str] = Field(..., min_length=1, max_length=3)
    upper: list[str] = Field(..., min_length=1, max_length=3)
    drivers_lower: dict[str, str] | None = None
    drivers_upper: dict[str, str] | None = None

    @model_validator(mode="after")
    def _check_face_alignment(self) -> BoundaryConditionsBase:
        if len(self.lower) != len(self.upper):
            raise ValueError(
                f"boundary_conditions.lower ({len(self.lower)}) and .upper "
                f"({len(self.upper)}) must have equal length"
            )
        for face_name in ("drivers_lower", "drivers_upper"):
            drivers = getattr(self, face_name)
            if drivers is None:
                continue
            for raw_key in drivers:
                try:
                    idx = int(raw_key)
                except ValueError as exc:
                    raise ValueError(
                        f"boundary_conditions.{face_name} key {raw_key!r} "
                        f"is not a non-negative integer"
                    ) from exc
                if idx < 0 or idx >= len(self.lower):
                    raise ValueError(
                        f"boundary_conditions.{face_name} key {raw_key!r} "
                        f"out of range for {len(self.lower)} axes"
                    )
        return self

BoxRegion

Bases: _StrictBase

[output.streams.<n>.region] — axis-aligned box selection.

Coordinates in code units (matches [grid].lower / [grid].upper convention). upper must be strictly greater than lower per axis; the per-axis count must align with [grid].dimensions — enforced at the root level.

Source code in src/pypic/schema/_models.py

class BoxRegion(_StrictBase):
    """``[output.streams.<n>.region]`` — axis-aligned box selection.

    Coordinates in code units (matches ``[grid].lower`` / ``[grid].upper``
    convention). ``upper`` must be strictly greater than ``lower`` per
    axis; the per-axis count must align with ``[grid].dimensions`` —
    enforced at the root level.
    """

    kind: Literal["box"] = "box"
    lower: AxisFloat
    upper: AxisFloat

    @model_validator(mode="after")
    def _check_box(self) -> BoxRegion:
        if len(self.lower) != len(self.upper):
            raise ValueError(
                f"output stream box region: lower ({len(self.lower)}) and "
                f"upper ({len(self.upper)}) must align"
            )
        for i, (lo, up) in enumerate(zip(self.lower, self.upper, strict=True)):
            if up <= lo:
                raise ValueError(
                    f"output stream box region: upper[{i}] ({up}) must be > "
                    f"lower[{i}] ({lo})"
                )
        return self

Collision

Bases: _ExtensibleBase

One entry in [[collisions]] — inter-species collision model.

Collisional PIC codes (Smilei, EPOCH, OSIRIS-collisional, PIConGPU) declare per-pair Coulomb collisions, BGK relaxation, or Monte-Carlo scattering. The schema captures the declaration of each pair; numerical parameters live on the entry.

species_pair lists the two species names participating; the root validator enforces that both names exist in [[species]]. Self-collisions (same species twice) are permitted.

Extra keys are accepted (_ExtensibleBase) so code-specific knobs — cross-section table paths, BGK relaxation-rate models, Monte-Carlo scattering-table identifiers — can land here without forcing every collisional reader through the top-level x- namespace. Portable additions (when a vocabulary stabilises across codes) become typed fields in a future version.

Source code in src/pypic/schema/_models.py

class Collision(_ExtensibleBase):
    r"""One entry in ``[[collisions]]`` — inter-species collision model.

    Collisional PIC codes (Smilei, EPOCH, OSIRIS-collisional, PIConGPU)
    declare per-pair Coulomb collisions, BGK relaxation, or
    Monte-Carlo scattering. The schema captures the *declaration* of
    each pair; numerical parameters live on the entry.

    ``species_pair`` lists the two species names participating; the
    root validator enforces that both names exist in ``[[species]]``.
    Self-collisions (same species twice) are permitted.

    Extra keys are accepted (``_ExtensibleBase``) so code-specific
    knobs — cross-section table paths, BGK relaxation-rate models,
    Monte-Carlo scattering-table identifiers — can land here without
    forcing every collisional reader through the top-level ``x-``
    namespace. Portable additions (when a vocabulary stabilises across
    codes) become typed fields in a future version.
    """

    species_pair: list[str] = Field(..., min_length=2, max_length=2)
    model: CollisionModel
    coulomb_log: PositiveFloat | None = None
    temperature_ref: PositiveFloat | None = None
    description: str | None = None

Coordinates

Bases: _StrictBase

[coordinates] — geometry + reference frame.

physical_extent is metadata at the schema level: the validator only checks shape and positivity. Post-translation, the reader-side helper pypic.readers.config.apply_physical_extent consumes it to auto-compute transform scale factors and a shrink-factor diagnostic (see docs/schema.md § Coordinates).

modes is required when geometry = "thetaMode" (FBPIC azimuthal- mode decomposition over an (r, z) grid) and forbidden otherwise.

Source code in src/pypic/schema/_models.py

class Coordinates(_StrictBase):
    """``[coordinates]`` — geometry + reference frame.

    ``physical_extent`` is metadata at the schema level: the validator
    only checks shape and positivity. Post-translation, the reader-side
    helper ``pypic.readers.config.apply_physical_extent`` consumes it to
    auto-compute transform scale factors and a shrink-factor diagnostic
    (see ``docs/schema.md`` § Coordinates).

    ``modes`` is required when ``geometry = "thetaMode"`` (FBPIC azimuthal-
    mode decomposition over an (r, z) grid) and forbidden otherwise.
    """

    geometry: Geometry
    frame: str
    axis_labels: Vec3Str | None = None
    physical_extent: AxisPosFloat | None = None
    physical_extent_unit: PhysicalExtentUnit | None = None
    transforms: dict[str, CoordinateTransform] = Field(default_factory=dict)
    modes: CoordinatesModes | None = None

    @model_validator(mode="after")
    def _check_modes_geometry(self) -> Coordinates:
        if self.geometry == "thetaMode" and self.modes is None:
            raise ValueError(
                "coordinates.geometry = 'thetaMode' requires "
                "[coordinates.modes] (n_modes at minimum)"
            )
        if self.geometry != "thetaMode" and self.modes is not None:
            raise ValueError(
                f"coordinates.modes is only valid for geometry = 'thetaMode' "
                f"(got '{self.geometry}')"
            )
        return self

CoordinatesModes

Bases: _StrictBase

[coordinates.modes] — azimuthal-mode decomposition for FBPIC RZ.

Required when geometry = "thetaMode". n_modes counts the azimuthal modes stored on disk (typically 1–3, with mode 0 cylindrically symmetric). mode_indices is an optional explicit list of mode numbers — when omitted, modes are assumed to run 0, 1, ..., n_modes-1.

Source code in src/pypic/schema/_models.py

class CoordinatesModes(_StrictBase):
    """``[coordinates.modes]`` — azimuthal-mode decomposition for FBPIC RZ.

    Required when ``geometry = "thetaMode"``. ``n_modes`` counts the
    azimuthal modes stored on disk (typically 1–3, with mode 0 cylindrically
    symmetric). ``mode_indices`` is an optional explicit list of mode
    numbers — when omitted, modes are assumed to run ``0, 1, ..., n_modes-1``.
    """

    n_modes: PositiveInt
    mode_indices: list[NonNegativeInt] | None = None

    @model_validator(mode="after")
    def _check_indices_match_count(self) -> CoordinatesModes:
        if self.mode_indices is not None and len(self.mode_indices) != self.n_modes:
            raise ValueError(
                f"coordinates.modes.mode_indices has "
                f"{len(self.mode_indices)} entries but n_modes = {self.n_modes}"
            )
        return self

CoordinateTransform

Bases: _StrictBase

One entry under [coordinates.transforms.<frame>].

rotation, when present, must be a 3×3 signed permutation matrix: exactly one ±1 per row and per column with every other entry zero. That covers all axis-relabeling / handedness flips pypic's frame transforms support today (GSE↔GSM-style rotations with continuous angles are time-dependent and route through parameter instead — see coordinates.transforms). Catching a malformed matrix here is cheaper than letting it slip into pypic.coordinates._frames and surface as a runtime error at apply time.

Source code in src/pypic/schema/_models.py

class CoordinateTransform(_StrictBase):
    """One entry under ``[coordinates.transforms.<frame>]``.

    ``rotation``, when present, must be a 3×3 *signed permutation*
    matrix: exactly one ±1 per row and per column with every other
    entry zero. That covers all axis-relabeling / handedness flips
    pypic's frame transforms support today (GSE↔GSM-style rotations
    with continuous angles are time-dependent and route through
    ``parameter`` instead — see ``coordinates.transforms``). Catching
    a malformed matrix here is cheaper than letting it slip into
    ``pypic.coordinates._frames`` and surface as a runtime error at
    apply time.
    """

    origin: AxisFloat | None = None
    rotation: list[Vec3Float] | None = None
    scale: float | None = None
    from_frame: str | None = None
    parameter: str | None = None
    axis_labels: Vec3Str | None = None

    @model_validator(mode="after")
    def _check_rotation_signed_permutation(self) -> CoordinateTransform:
        if self.rotation is None:
            return self
        rows = self.rotation
        if len(rows) != 3:
            raise ValueError(
                f"coordinates.transforms.rotation must be a 3x3 matrix; "
                f"got {len(rows)} rows"
            )
        # Signed permutation: each row and each column has exactly one
        # entry equal to +/-1, all others zero. Equivalent statement —
        # R R^T == I with entries drawn from {-1, 0, +1}.
        col_used = [False, False, False]
        for i, row in enumerate(rows):
            nonzero = [(j, v) for j, v in enumerate(row) if v != 0.0]
            if len(nonzero) != 1 or nonzero[0][1] not in (1.0, -1.0):
                raise ValueError(
                    f"coordinates.transforms.rotation row {i} = {row} is "
                    f"not a signed unit vector (need exactly one +/-1 entry, "
                    f"all others 0)"
                )
            j = nonzero[0][0]
            if col_used[j]:
                raise ValueError(
                    f"coordinates.transforms.rotation column {j} is used "
                    f"twice; matrix is not a permutation"
                )
            col_used[j] = True
        return self

Driver

Bases: _ExtensibleBase

One entry in [[drivers]].

Drivers have a core set of v2.0 fields plus driver-type-specific keys — extra keys allowed so individual driver types (magnetogram, solar_wind_timeseries, pickup_ion_source, ...) don't need a model per type in v2.0.

An entry describes the external input from this run's perspective. For two-way coupling (direction = "two_way"), the asymmetry is in information flow, not in physics: the peer run, if pypic-aware, owns its own simulation.toml with its own [[drivers]] entry pointing back. [drivers.model] is where the peer's identity (name, type, url, description) lives; pure data drivers (CSV, HDF5 timeseries) can omit the sub-table and use source alone.

Source code in src/pypic/schema/_models.py

class Driver(_ExtensibleBase):
    """One entry in ``[[drivers]]``.

    Drivers have a core set of v2.0 fields plus driver-type-specific
    keys — extra keys allowed so individual driver types (magnetogram,
    solar_wind_timeseries, pickup_ion_source, ...) don't need a model
    per type in v2.0.

    An entry describes the *external input from this run's
    perspective*. For two-way coupling (``direction = "two_way"``),
    the asymmetry is in information flow, not in physics: the peer
    run, if pypic-aware, owns its own ``simulation.toml`` with its
    own ``[[drivers]]`` entry pointing back. ``[drivers.model]`` is
    where the peer's identity (name, type, url, description) lives;
    pure data drivers (CSV, HDF5 timeseries) can omit the sub-table
    and use ``source`` alone.
    """

    name: str
    type: str
    coupling: DriverCoupling
    direction: DriverDirection = "one_way"
    description: str | None = None
    source: str | None = None
    columns: list[str] | None = None
    cadence: NonNegativeFloat | None = None
    interpolation: str | None = None
    target_lower: AxisFloat | None = None
    target_upper: AxisFloat | None = None
    body: str | None = None
    model: DriverModel | None = None

    @model_validator(mode="after")
    def _check_target_box(self) -> Driver:
        lo, up = self.target_lower, self.target_upper
        if lo is None and up is None:
            return self
        if lo is None or up is None:
            raise ValueError(
                f"driver '{self.name}': target_lower and target_upper must "
                f"both be present or both absent"
            )
        if len(lo) != len(up):
            raise ValueError(
                f"driver '{self.name}': target_lower has {len(lo)} entries "
                f"but target_upper has {len(up)}"
            )
        # Allow per-axis equality (thin sheet / line / surface drivers like
        # photospheric magnetograms); reject only an axis where upper < lower.
        for i, (lov, upv) in enumerate(zip(lo, up, strict=True)):
            if upv < lov:
                raise ValueError(
                    f"driver '{self.name}': target_upper[{i}] ({upv}) must be "
                    f">= target_lower[{i}] ({lov})"
                )
        return self

DriverModel

Bases: _ExtensibleBase

[drivers.model] — identity of a coupled external system.

Used when a driver entry refers to a named model rather than (or in addition to) a flat data file. The type vocabulary is open: "MHD" and "PIC" cover pypic-aware peers, but "ionosphere_potential_solver" (RIM, Weimer), "magnetic_field_ extrapolation" (PFSS, NLFFF), "fluid_atmosphere" (GITM, TIE- GCM), "fusion_transport" (ASTRA, JETTO), and any other category are equally valid.

url is a single opaque pointer. It may be the peer's simulation.toml cross-link (when pypic-aware), a homepage URL, a DOI, or any other machine- or human-readable metadata reference. The schema does not resolve or sniff the format — that is a consumer concern, in the same spirit as restart.from and the top-level [model].url. A non-standard metadata file is better than no link at all.

_ExtensibleBase lets coupling-specific keys (version, doi, git_sha, model-specific knobs) ride along without bloating the typed surface.

Source code in src/pypic/schema/_models.py

class DriverModel(_ExtensibleBase):
    """``[drivers.model]`` — identity of a coupled external system.

    Used when a driver entry refers to a *named model* rather than (or
    in addition to) a flat data file. The type vocabulary is open:
    ``"MHD"`` and ``"PIC"`` cover pypic-aware peers, but
    ``"ionosphere_potential_solver"`` (RIM, Weimer), ``"magnetic_field_
    extrapolation"`` (PFSS, NLFFF), ``"fluid_atmosphere"`` (GITM, TIE-
    GCM), ``"fusion_transport"`` (ASTRA, JETTO), and any other category
    are equally valid.

    ``url`` is a single opaque pointer. It may be the peer's
    ``simulation.toml`` cross-link (when pypic-aware), a homepage URL,
    a DOI, or any other machine- or human-readable metadata reference.
    The schema does not resolve or sniff the format — that is a consumer
    concern, in the same spirit as ``restart.from`` and the top-level
    ``[model].url``. A non-standard metadata file is better than no
    link at all.

    ``_ExtensibleBase`` lets coupling-specific keys (``version``,
    ``doi``, ``git_sha``, model-specific knobs) ride along without
    bloating the typed surface.
    """

    name: str
    type: str
    url: str | None = None
    description: str | None = None

Ensemble

Bases: _StrictBase

[run.ensemble] — ensemble-member identity for stochastic runs.

Required for cosmological PIC, turbulence realizations, and any other setup where multiple runs share initial conditions modulo a random seed. member_id is 1-indexed and bounded by total; the validator enforces 1 <= member_id <= total.

Source code in src/pypic/schema/_models.py

class Ensemble(_StrictBase):
    """``[run.ensemble]`` — ensemble-member identity for stochastic runs.

    Required for cosmological PIC, turbulence realizations, and any other
    setup where multiple runs share initial conditions modulo a random
    seed. ``member_id`` is 1-indexed and bounded by ``total``; the
    validator enforces ``1 <= member_id <= total``.
    """

    member_id: PositiveInt
    total: PositiveInt

    @model_validator(mode="after")
    def _check_member_id_in_range(self) -> Ensemble:
        if self.member_id > self.total:
            raise ValueError(
                f"ensemble.member_id ({self.member_id}) must be "
                f"<= ensemble.total ({self.total})"
            )
        return self

Grid

Bases: _StrictBase

[grid] — computational grid in code units.

ghost_cells records the number of ghost cells per axis used by the code's halo exchange. Optional metadata for downstream edge-derivative analysis; readers strip ghosts before populating FieldDataset.

stretched describes per-axis non-uniform cell widths. Sparse — only axes with non-uniform spacing appear in [grid.stretched.axis_widths]; the remaining axes inherit spacing. The validator enforces that any listed axis widths sum to upper[i] - lower[i] and that the list length equals dimensions[i].

stagger consolidates the three field-placement-inside-cell tiers (convention, fields, position) under a single sub-table — see GridStagger.

Source code in src/pypic/schema/_models.py

class Grid(_StrictBase):
    """``[grid]`` — computational grid in code units.

    ``ghost_cells`` records the number of ghost cells per axis used by the
    code's halo exchange. Optional metadata for downstream edge-derivative
    analysis; readers strip ghosts before populating ``FieldDataset``.

    ``stretched`` describes per-axis non-uniform cell widths. Sparse —
    only axes with non-uniform spacing appear in
    ``[grid.stretched.axis_widths]``; the remaining axes inherit
    ``spacing``. The validator enforces that any listed axis widths sum
    to ``upper[i] - lower[i]`` and that the list length equals
    ``dimensions[i]``.

    ``stagger`` consolidates the three field-placement-inside-cell
    tiers (``convention``, ``fields``, ``position``) under a single
    sub-table — see `GridStagger`.
    """

    dimensions: AxisInt
    spacing: AxisPosFloat
    lower: AxisFloat
    upper: AxisFloat
    stagger: GridStagger = Field(default_factory=GridStagger)
    ghost_cells: (
        Annotated[list[NonNegativeInt], Field(min_length=1, max_length=3)] | None
    ) = None
    source: str | None = None
    source_format: str | None = None
    amr: GridAMR | None = None
    refinement: list[GridRefinementBox] = Field(default_factory=list)
    stretched: GridStretched | None = None

    @model_validator(mode="after")
    def _check_axis_consistency(self) -> Grid:
        n = len(self.dimensions)
        for field_name in ("spacing", "lower", "upper"):
            arr = getattr(self, field_name)
            if len(arr) != n:
                raise ValueError(
                    f"{field_name} has {len(arr)} entries but dimensions has {n}"
                )
        for i, (lo, up) in enumerate(zip(self.lower, self.upper, strict=True)):
            if up <= lo:
                raise ValueError(f"upper[{i}] ({up}) must be > lower[{i}] ({lo})")
        if self.ghost_cells is not None and len(self.ghost_cells) != n:
            raise ValueError(
                f"ghost_cells has {len(self.ghost_cells)} entries but "
                f"dimensions has {n}"
            )
        if self.stretched is not None:
            for raw_key, widths in self.stretched.axis_widths.items():
                idx = int(raw_key)
                if idx >= n:
                    raise ValueError(
                        f"grid.stretched.axis_widths['{raw_key}'] references "
                        f"axis {idx}, but grid.dimensions has {n} axes"
                    )
                if len(widths) != self.dimensions[idx]:
                    raise ValueError(
                        f"grid.stretched.axis_widths['{raw_key}'] has "
                        f"{len(widths)} entries, expected dimensions[{idx}]"
                        f" = {self.dimensions[idx]}"
                    )
                expected_extent = self.upper[idx] - self.lower[idx]
                actual_extent = float(sum(widths))
                tol = self.stretched.sum_rtol * max(abs(expected_extent), 1.0)
                if abs(actual_extent - expected_extent) > tol:
                    raise ValueError(
                        f"grid.stretched.axis_widths['{raw_key}'] sums to "
                        f"{actual_extent}, expected upper - lower = "
                        f"{expected_extent} (within rtol "
                        f"{self.stretched.sum_rtol})"
                    )
        if self.stagger.position is not None:
            for name, offsets in self.stagger.position.items():
                if len(offsets) != n:
                    raise ValueError(
                        f"grid.stagger.position['{name}'] has {len(offsets)} "
                        f"entries, expected dimensions has {n}"
                    )
                for offset in offsets:
                    if not 0.0 <= offset < 1.0:
                        raise ValueError(
                            f"grid.stagger.position['{name}'] = {offsets} — "
                            f"each offset must be in [0.0, 1.0)"
                        )
        return self

GridAMR

Bases: _StrictBase

[grid.amr] — dynamic adaptive refinement parameters.

amr_kind discriminates block/patch (BoxLib / AMReX / Chombo / FLASH) from octree codes (RAMSES, MPI-AMRVAC); octree leaves are single cells so block_size does not apply. level_subcycling records whether different AMR levels advance at different effective timesteps (Athena++ and AMReX-based codes); a per-level dt_factor array would be a future v2.1 add if needed.

Source code in src/pypic/schema/_models.py

class GridAMR(_StrictBase):
    """``[grid.amr]`` — dynamic adaptive refinement parameters.

    ``amr_kind`` discriminates block/patch (BoxLib / AMReX / Chombo / FLASH)
    from octree codes (RAMSES, MPI-AMRVAC); octree leaves are single cells
    so ``block_size`` does not apply. ``level_subcycling`` records whether
    different AMR levels advance at different effective timesteps (Athena++
    and AMReX-based codes); a per-level ``dt_factor`` array would be a
    future v2.1 add if needed.
    """

    max_level: NonNegativeInt
    refinement_ratio: PositiveInt = 2
    block_size: list[PositiveInt] | None = None
    refinement_criteria: list[str] = Field(default_factory=list)
    refinement_threshold: NonNegativeFloat | None = None
    amr_kind: AMRKind = "block"
    level_subcycling: bool = False

GridRefinementBox

Bases: _StrictBase

One entry in [[grid.refinement]] (static nested refinement box).

Source code in src/pypic/schema/_models.py

class GridRefinementBox(_StrictBase):
    """One entry in ``[[grid.refinement]]`` (static nested refinement box)."""

    level: NonNegativeInt
    box: list[list[float]] = Field(..., min_length=2, max_length=2)

GridStretched

Bases: _StrictBase

[grid.stretched] — non-uniform per-axis cell widths.

Sparse, keyed by axis index as a string ("0" / "1" / "2"). Only stretched axes appear; uniform axes inherit Grid.spacing. Per-axis cell widths must sum to upper[i] - lower[i] and the list length must equal dimensions[i]; both invariants are enforced by Grid._check_axis_consistency.

Adopted to describe ARMS spherical-r stretches, PLUTO log-radial grids, Athena++ stretched grids, and FLASH per-block-non-uniform layouts losslessly. Kept additive so uniform documents validate unchanged. Metric-aware operators are out of scope for v2.0.x — consumers that need them should guard explicitly.

Source code in src/pypic/schema/_models.py

class GridStretched(_StrictBase):
    """``[grid.stretched]`` — non-uniform per-axis cell widths.

    Sparse, keyed by axis index as a string (``"0"`` / ``"1"`` / ``"2"``).
    Only stretched axes appear; uniform axes inherit ``Grid.spacing``.
    Per-axis cell widths must sum to ``upper[i] - lower[i]`` and the
    list length must equal ``dimensions[i]``; both invariants are
    enforced by ``Grid._check_axis_consistency``.

    Adopted to describe ARMS spherical-r stretches, PLUTO log-radial
    grids, Athena++ stretched grids, and FLASH per-block-non-uniform
    layouts losslessly. Kept additive so uniform documents validate
    unchanged. Metric-aware operators are out of scope for v2.0.x —
    consumers that need them should guard explicitly.
    """

    # Required; the section is meaningful only when at least one axis is
    # declared stretched. The validator additionally enforces non-empty
    # so an explicit ``axis_widths = {}`` is rejected with a clear message.
    axis_widths: dict[str, list[PositiveFloat]]
    # Relative-tolerance for the cell-width sum vs (upper - lower) check.
    # Defaults are intentionally loose to accommodate float drift in
    # hand-written TOML; tighten via this knob when authoring tests.
    sum_rtol: NonNegativeFloat = 1.0e-9

    @model_validator(mode="after")
    def _check_axis_keys(self) -> GridStretched:
        # Keys must be parseable as small non-negative integers in
        # [0, 2]. The full axis-count cross-check (against
        # ``Grid.dimensions``) lives on ``Grid``.
        if not self.axis_widths:
            raise ValueError(
                "grid.stretched.axis_widths must contain at least one axis"
            )
        for raw_key in self.axis_widths:
            try:
                idx = int(raw_key)
            except ValueError as exc:
                raise ValueError(
                    f"grid.stretched.axis_widths key {raw_key!r} is not a "
                    f"non-negative integer"
                ) from exc
            if idx < 0 or idx > 2:
                raise ValueError(
                    f"grid.stretched.axis_widths key {raw_key!r} is out of range [0, 2]"
                )
        return self

HybridSolver

Bases: _ExtensibleBase

[physics.hybrid.solver]. Extra keys accepted.

Source code in src/pypic/schema/_models.py

class HybridSolver(_ExtensibleBase):
    """``[physics.hybrid.solver]``. Extra keys accepted."""

    scheme: HybridSolverScheme
    field_pusher: HybridFieldPusher | None = None
    resistivity: NonNegativeFloat | None = None
    hyper_resistivity: NonNegativeFloat | None = None
    current_smoothing: NonNegativeInt | None = None
    preconditioner: Preconditioner | None = None

InitialConditions

Bases: _ExtensibleBase

[initial_conditions] — flat table, setup-specific keys vary.

Source code in src/pypic/schema/_models.py

class InitialConditions(_ExtensibleBase):
    """``[initial_conditions]`` — flat table, setup-specific keys vary."""

    type: str

MHDSolver

Bases: _ExtensibleBase

[physics.mhd.solver]. Extra keys accepted.

Source code in src/pypic/schema/_models.py

class MHDSolver(_ExtensibleBase):
    """``[physics.mhd.solver]``. Extra keys accepted."""

    scheme: MHDSolverScheme
    reconstruction: MHDReconstruction | None = None
    limiter: MHDLimiter | None = None
    divergence_cleaning: DivergenceCleaning | None = None
    riemann: MHDRiemann | None = None
    preconditioner: Preconditioner | None = None

Model

Bases: _StrictBase

[model] — identity of the code that produced the data.

Source code in src/pypic/schema/_models.py

class Model(_StrictBase):
    """``[model]`` — identity of the code that produced the data."""

    name: str
    type: ModelType
    version: str | None = None
    description: str | None = None
    url: str | None = None
    doi: str | None = None
    license: str | None = None
    authors: list[Author] = Field(default_factory=list)

Output

Bases: _StrictBase

[output] — umbrella for all write-side configuration.

Source code in src/pypic/schema/_models.py

class Output(_StrictBase):
    """``[output]`` — umbrella for all write-side configuration."""

    checkpoints: OutputCheckpoints | None = None
    fields: OutputFields | None = None
    particles: OutputParticles | None = None
    probes: OutputProbes | None = None
    diagnostics: OutputDiagnostics | None = None
    streams: list[OutputStream] = Field(default_factory=list)

    @model_validator(mode="after")
    def _check_stream_names_unique(self) -> Output:
        names = [s.name for s in self.streams]
        if len(set(names)) != len(names):
            duplicates = sorted({n for n in names if names.count(n) > 1})
            raise ValueError(
                f"output.streams entries must have distinct names; "
                f"duplicates: {duplicates}"
            )
        return self

OutputCheckpoints

Bases: _OutputBase

[output.checkpoints] — lossless full-state dumps.

Source code in src/pypic/schema/_models.py

class OutputCheckpoints(_OutputBase):
    """``[output.checkpoints]`` — lossless full-state dumps."""

    precision: Precision = "f64"
    keep_last: PositiveInt | None = None

OutputDiagnostics

Bases: _OutputBase

[output.diagnostics] — on-the-fly derived quantities.

Source code in src/pypic/schema/_models.py

class OutputDiagnostics(_OutputBase):
    """``[output.diagnostics]`` — on-the-fly derived quantities."""

    quantities: list[str]

OutputFields

Bases: _OutputBase

[output.fields] — field output cadence + quantities.

Source code in src/pypic/schema/_models.py

class OutputFields(_OutputBase):
    """``[output.fields]`` — field output cadence + quantities."""

    quantities: list[str]
    precision_overrides: dict[str, Precision] = Field(default_factory=dict)

    @model_validator(mode="after")
    def _check_overrides_subset(self) -> OutputFields:
        _validate_precision_overrides(
            self.precision_overrides, self.quantities, where="output.fields"
        )
        return self

OutputParticles

Bases: _OutputBase

[output.particles] — particle output cadence + selection.

Source code in src/pypic/schema/_models.py

class OutputParticles(_OutputBase):
    """``[output.particles]`` — particle output cadence + selection."""

    species: list[str]
    include_ids: bool = False
    include_energy: bool = False
    sample: float | int | None = None

OutputProbes

Bases: _OutputBase

[output.probes] — probe time-series cadence.

Source code in src/pypic/schema/_models.py

class OutputProbes(_OutputBase):
    """``[output.probes]`` — probe time-series cadence."""

    precision: Precision = "f64"

OutputStream

Bases: _OutputBase

One entry in [[output.streams]] — multi-cadence / ROI output.

The repeatable form alongside the existing singleton [output.fields]. Use this for runs that write moments at 10x the cadence of full distributions, or ROI slabs at 10x the cadence of the global volume, or that simply need named output groups for downstream pipelines.

name is required and must be unique across streams. region optionally restricts the write to a sub-volume or plane; precision_overrides re-uses the [output.fields] semantics (per-field-name dtype overrides; names must appear in quantities).

Source code in src/pypic/schema/_models.py

class OutputStream(_OutputBase):
    """One entry in ``[[output.streams]]`` — multi-cadence / ROI output.

    The repeatable form alongside the existing singleton ``[output.fields]``.
    Use this for runs that write moments at 10x the cadence of full
    distributions, or ROI slabs at 10x the cadence of the global volume,
    or that simply need named output groups for downstream pipelines.

    ``name`` is required and must be unique across streams. ``region``
    optionally restricts the write to a sub-volume or plane;
    ``precision_overrides`` re-uses the ``[output.fields]`` semantics
    (per-field-name dtype overrides; names must appear in ``quantities``).
    """

    name: str
    quantities: list[str]
    region: Region | None = None
    precision_overrides: dict[str, Precision] = Field(default_factory=dict)

    @model_validator(mode="after")
    def _check_overrides_subset(self) -> OutputStream:
        _validate_precision_overrides(
            self.precision_overrides,
            self.quantities,
            where=f"output.streams[{self.name!r}]",
        )
        return self

PhaseSpace

Bases: _StrictBase

[phase_space] — kinetic phase-space dimensions for >3D codes.

Gyrokinetic codes (GENE, GS2, GX, Gkeyll-GK) run on 5-D grids (3 spatial + 2 velocity); continuum-Vlasov codes use 6-D phase space (3 spatial + 3 velocity). This block describes the augmented phase-space dimensionality without lifting the Grid.dimensions cap on the spatial side.

Required when the simulation operates on a phase-space grid larger than [grid].dimensions. Optional otherwise. The root validator enforces consistency: [phase_space].dimensions[:n_spatial] must match [grid].dimensions when both are present.

storage is the sparse-block sub-table for continuum-Vlasov codes. Gyrokinetic runs omit it.

Source code in src/pypic/schema/_models.py

class PhaseSpace(_StrictBase):
    r"""``[phase_space]`` — kinetic phase-space dimensions for >3D codes.

    Gyrokinetic codes (GENE, GS2, GX, Gkeyll-GK) run on 5-D grids
    (3 spatial + 2 velocity); continuum-Vlasov codes use 6-D phase
    space (3 spatial + 3 velocity). This block describes the
    *augmented* phase-space dimensionality without lifting the
    ``Grid.dimensions`` cap on the spatial side.

    Required when the simulation operates on a phase-space grid larger
    than ``[grid].dimensions``. Optional otherwise. The root validator
    enforces consistency: ``[phase_space].dimensions[:n_spatial]``
    must match ``[grid].dimensions`` when both are present.

    ``storage`` is the sparse-block sub-table for continuum-Vlasov
    codes.  Gyrokinetic runs omit it.
    """

    dimensions: list[PositiveInt] = Field(..., min_length=2, max_length=6)
    axis_labels: list[str] | None = None
    extents: list[list[float]] | None = None
    coordinate_system: PhaseSpaceCoordSystem = "cartesian"
    storage: PhaseSpaceStorage | None = None

    @model_validator(mode="after")
    def _check_axis_labels_and_extents(self) -> PhaseSpace:
        n = len(self.dimensions)
        if self.axis_labels is not None and len(self.axis_labels) != n:
            raise ValueError(
                f"phase_space.axis_labels has {len(self.axis_labels)} "
                f"entries but dimensions has {n}"
            )
        if self.extents is not None:
            if len(self.extents) != n:
                raise ValueError(
                    f"phase_space.extents has {len(self.extents)} axes but "
                    f"dimensions has {n}"
                )
            for i, axis_extent in enumerate(self.extents):
                if len(axis_extent) != 2:
                    raise ValueError(
                        f"phase_space.extents[{i}] must have 2 entries "
                        f"[lower, upper], got {len(axis_extent)}"
                    )
                lo, up = axis_extent
                if up <= lo:
                    raise ValueError(
                        f"phase_space.extents[{i}]: upper ({up}) must be > lower ({lo})"
                    )
        return self

PhaseSpaceStorage

Bases: _StrictBase

[phase_space.storage] — sparse-block velocity-grid storage.

Continuum-Vlasov codes (Vlasiator, Gkeyll-Vlasov-Maxwell) subdivide the velocity sub-grid into blocks for adaptive memory use, dropping blocks whose distribution-function density falls below a threshold. block_size records the per-velocity-axis block factor; sparsity_threshold records the density floor.

Optional sub-table on PhaseSpace. Gyrokinetic codes (GENE, GS2, GX, Gkeyll-GK) emit dense 5-D grids and omit this block entirely. The validator checks that block_size length matches the velocity sub-axes of the parent dimensions — enforced on the parent PhaseSpace once the spatial dimension count is known at the root level.

Source code in src/pypic/schema/_models.py

class PhaseSpaceStorage(_StrictBase):
    r"""``[phase_space.storage]`` — sparse-block velocity-grid storage.

    Continuum-Vlasov codes (Vlasiator, Gkeyll-Vlasov-Maxwell) subdivide
    the velocity sub-grid into blocks for adaptive memory use, dropping
    blocks whose distribution-function density falls below a threshold.
    ``block_size`` records the per-velocity-axis block factor;
    ``sparsity_threshold`` records the density floor.

    Optional sub-table on `PhaseSpace`. Gyrokinetic codes
    (GENE, GS2, GX, Gkeyll-GK) emit dense 5-D grids and omit this
    block entirely. The validator checks that ``block_size`` length
    matches the velocity sub-axes of the parent ``dimensions`` —
    enforced on the parent `PhaseSpace` once the spatial
    dimension count is known at the root level.
    """

    block_size: list[PositiveInt] | None = None
    sparsity_threshold: NonNegativeFloat | None = None

Physics

Bases: _ExtensibleBase

[physics] — flags whose semantics are identical across models.

Extra top-level keys under [physics] are accepted to leave room for v2.1+ additions ([physics.vlasov] in particular).

Source code in src/pypic/schema/_models.py

class Physics(_ExtensibleBase):
    """``[physics]`` — flags whose semantics are identical across models.

    Extra top-level keys under ``[physics]`` are accepted to leave room
    for v2.1+ additions (``[physics.vlasov]`` in particular).
    """

    relativistic: bool = False
    pic: PhysicsPIC | None = None
    mhd: PhysicsMHD | None = None
    hybrid: PhysicsHybrid | None = None

PhysicsHybrid

Bases: _ExtensibleBase

[physics.hybrid] — hybrid physics-model knobs. Extra keys accepted.

Source code in src/pypic/schema/_models.py

class PhysicsHybrid(_ExtensibleBase):
    """``[physics.hybrid]`` — hybrid physics-model knobs. Extra keys accepted."""

    solver: HybridSolver | None = None

PhysicsMHD

Bases: _ExtensibleBase

[physics.mhd] — MHD physics-model knobs. Extra keys accepted.

Source code in src/pypic/schema/_models.py

class PhysicsMHD(_ExtensibleBase):
    """``[physics.mhd]`` — MHD physics-model knobs. Extra keys accepted."""

    gamma_eos: PositiveFloat | None = None
    resistivity: NonNegativeFloat | None = None
    hall_term: bool | None = None
    solver: MHDSolver | None = None

PhysicsPIC

Bases: _ExtensibleBase

[physics.pic] — PIC physics-model knobs. Extra keys accepted.

Source code in src/pypic/schema/_models.py

class PhysicsPIC(_ExtensibleBase):
    """``[physics.pic]`` — PIC physics-model knobs. Extra keys accepted."""

    omega_p_over_omega_c: PositiveFloat | None = None
    solver: PICSolver | None = None

PICSolver

Bases: _ExtensibleBase

[physics.pic.solver]. Extra keys accepted — vocabulary evolves.

current_smoothing / charge_smoothing count the binomial / compensator filter passes per step (standard in WarpX, Smilei, PIConGPU, OSIRIS — already exposed on HybridSolver). charge_correction, current_deposition adopt the openPMD ED-PIC vocabulary; see ChargeCorrection, CurrentDeposition.

Source code in src/pypic/schema/_models.py

class PICSolver(_ExtensibleBase):
    """``[physics.pic.solver]``. Extra keys accepted — vocabulary evolves.

    ``current_smoothing`` / ``charge_smoothing`` count the binomial /
    compensator filter passes per step (standard in WarpX, Smilei,
    PIConGPU, OSIRIS — already exposed on ``HybridSolver``).
    ``charge_correction``, ``current_deposition`` adopt the openPMD
    ED-PIC vocabulary; see `ChargeCorrection`,
    `CurrentDeposition`.
    """

    scheme: PICSolverScheme
    implicitness: float | None = None
    pusher: PICPusher | None = None
    field_solver: PICFieldSolver | None = None
    preconditioner: Preconditioner | None = None
    current_smoothing: NonNegativeInt | None = None
    charge_smoothing: NonNegativeInt | None = None
    charge_correction: ChargeCorrection | None = None
    current_deposition: CurrentDeposition | None = None

PlaneRegion

Bases: _StrictBase

[output.streams.<n>.region] — single-axis plane slice.

axis selects a coordinate axis (0/1/2). value is the plane position in code units; the reader is responsible for resolving it to the nearest grid index.

Source code in src/pypic/schema/_models.py

class PlaneRegion(_StrictBase):
    """``[output.streams.<n>.region]`` — single-axis plane slice.

    ``axis`` selects a coordinate axis (``0``/``1``/``2``).
    ``value`` is the plane position in code units; the reader is
    responsible for resolving it to the nearest grid index.
    """

    kind: Literal["plane"] = "plane"
    axis: NonNegativeInt = Field(..., le=2)
    value: float

Probe

Bases: _StrictBase

One entry in [[probes]] — fixed or trajectory sampler.

fields controls which dataset fields the probe samples. Two modes:

• fields = None (omitted) — sample every storage-primitive field present in the dataset at probe time. Storage primitives are what readers expose via available_fields() — moments and EM fields actually on disk, never derived quantities like |B| or beta. Users who want derived quantities listed must request them explicitly. The narrow default keeps probe time-series cheap on big runs.
• fields = [...] — sample exactly this list. Names that don't resolve at sample time should fail loudly rather than be silently dropped; resolution against available_fields() happens in the probe sampler, not here.

Source code in src/pypic/schema/_models.py

class Probe(_StrictBase):
    """One entry in ``[[probes]]`` — fixed or trajectory sampler.

    ``fields`` controls which dataset fields the probe samples. Two modes:

    - ``fields = None`` (omitted) — sample every **storage-primitive**
      field present in the dataset at probe time. Storage primitives are
      what readers expose via ``available_fields()`` — moments and EM
      fields actually on disk, never derived quantities like ``|B|`` or
      ``beta``. Users who want derived quantities listed must request
      them explicitly. The narrow default keeps probe time-series cheap
      on big runs.
    - ``fields = [...]`` — sample exactly this list. Names that don't
      resolve at sample time should fail loudly rather than be
      silently dropped; resolution against ``available_fields()``
      happens in the probe sampler, not here.
    """

    name: str
    position: Vec3Float | None = None
    trajectory: str | None = None
    fields: list[str] | None = None
    frame: str | None = None

    @model_validator(mode="after")
    def _check_position_xor_trajectory(self) -> Probe:
        has_pos = self.position is not None
        has_traj = self.trajectory is not None
        if has_pos == has_traj:
            raise ValueError(
                f"probe '{self.name}' must have exactly one of "
                f"`position` or `trajectory`"
            )
        # `frame` is only meaningful for trajectory probes (it names the
        # frame the trajectory file is expressed in). A fixed probe sits
        # in `[coordinates].frame` by definition; carrying a `frame=` on
        # it is silently ambiguous, so we reject it.
        if has_pos and self.frame is not None:
            raise ValueError(
                f"probe '{self.name}': `frame` is only valid with "
                f"`trajectory` (fixed probes inherit [coordinates].frame)"
            )
        return self

    def resolve_fields(self, available: Iterable[str]) -> list[str]:
        """Return the concrete field list this probe samples.

        Parameters
        ----------
        available
            Storage-primitive field names present in the dataset, as
            returned by ``reader.available_fields()``.

        Returns
        -------
        list[str]
            ``list(available)`` when ``fields is None``; otherwise
            ``self.fields`` after validating that every name resolves —
            either as a storage primitive in ``available`` or as a
            derived quantity (any name not in ``available`` is left for
            the sampler to dispatch through ``compute()`` and is *not*
            rejected here, since the schema layer has no compute
            registry).
        """
        available_list = list(available)
        if self.fields is None:
            return available_list
        # Explicit list passes through verbatim; the sampler is
        # responsible for raising KeyError on names that resolve neither
        # as primitives nor as derived quantities.
        return list(self.fields)

resolve_fields(available)

Return the concrete field list this probe samples.

Parameters:

Name	Type	Description	Default
available	Iterable[str]	Storage-primitive field names present in the dataset, as returned by reader.available_fields().	required

Returns:

Type	Description
list[str]	list(available) when fields is None; otherwise self.fields after validating that every name resolves — either as a storage primitive in available or as a derived quantity (any name not in available is left for the sampler to dispatch through compute() and is not rejected here, since the schema layer has no compute registry).

Source code in src/pypic/schema/_models.py

def resolve_fields(self, available: Iterable[str]) -> list[str]:
    """Return the concrete field list this probe samples.

    Parameters
    ----------
    available
        Storage-primitive field names present in the dataset, as
        returned by ``reader.available_fields()``.

    Returns
    -------
    list[str]
        ``list(available)`` when ``fields is None``; otherwise
        ``self.fields`` after validating that every name resolves —
        either as a storage primitive in ``available`` or as a
        derived quantity (any name not in ``available`` is left for
        the sampler to dispatch through ``compute()`` and is *not*
        rejected here, since the schema layer has no compute
        registry).
    """
    available_list = list(available)
    if self.fields is None:
        return available_list
    # Explicit list passes through verbatim; the sampler is
    # responsible for raising KeyError on names that resolve neither
    # as primitives nor as derived quantities.
    return list(self.fields)

Restart

Bases: _StrictBase

[restart] — continuation pointer from a prior run.

from is the path (or paths) to the restart artifact:

• a single file (./chk_000030.h5),
• a directory of per-rank checkpoints (./restart_30000/),
• a glob pattern, or
• an explicit list of per-rank files for runs whose names don't follow the source code's convention (relocated reruns, mixed naming schemes).

Whether the path resolves to one file or many is determined at read time by the filesystem and the code, not by the schema.

restore enables partial restart — restarting only the listed state categories rather than all of them (e.g., fields-only continuation that re-initializes particles from a fresh distribution). mode distinguishes a full state reload ("hot") from a setup-restart that re-applies initial conditions on top of the saved geometry ("cold"). Both optional; a missing restore means the full state is restored.

Source code in src/pypic/schema/_models.py

class Restart(_StrictBase):
    """``[restart]`` — continuation pointer from a prior run.

    ``from`` is the path (or paths) to the restart artifact:

    * a single file (``./chk_000030.h5``),
    * a directory of per-rank checkpoints (``./restart_30000/``),
    * a glob pattern, or
    * an explicit list of per-rank files for runs whose names don't
      follow the source code's convention (relocated reruns, mixed
      naming schemes).

    Whether the path resolves to one file or many is determined at
    read time by the filesystem and the code, not by the schema.

    ``restore`` enables partial restart — restarting only the listed
    state categories rather than all of them (e.g., fields-only
    continuation that re-initializes particles from a fresh
    distribution). ``mode`` distinguishes a full state reload
    (``"hot"``) from a setup-restart that re-applies initial
    conditions on top of the saved geometry (``"cold"``). Both
    optional; a missing ``restore`` means the full state is restored.
    """

    from_: str | list[str] = Field(..., alias="from")
    step: NonNegativeInt | None = None
    time: NonNegativeFloat | None = None
    restore: list[RestoreKind] | None = None
    mode: RestartMode | None = None

    @model_validator(mode="after")
    def _check_restart(self) -> Restart:
        if self.restore is not None and len(set(self.restore)) != len(self.restore):
            raise ValueError(
                f"restart.restore entries must be distinct, got {self.restore}"
            )
        if self.restore is not None and not self.restore:
            raise ValueError("restart.restore must be non-empty when present")
        if isinstance(self.from_, list):
            if not self.from_:
                raise ValueError("restart.from must be non-empty when given as a list")
            if len(set(self.from_)) != len(self.from_):
                raise ValueError(
                    f"restart.from entries must be distinct, got {self.from_}"
                )
        return self

Run

Bases: _StrictBase

[run] — identity + provenance of THIS run.

id is the stable, globally unique identifier for the run, and is the key every derived product carries back to its source. name is a human label and carries no uniqueness contract; doi is scarce by design, since archives do not mint one per run. No format is enforced — CCMC run IDs, ULIDs and per-lab conventions all differ, and the schema's job here is to record an identifier, not to police its shape.

references is results metadata: what was published from this run. Distinct from doi (this run's data) and [model].doi (the code).

idealized is deliberately tri-state. True means the run does not correspond to a real time period — artificial drivers, artificial internal settings, or a 2D reduction of a 3D system — so harvesting real-event characteristics from it would produce wrong metadata. False asserts the conditions are real. None (the default) means unstated, which is what every deck written before this key existed actually means; a plain bool default would make all of them silently claim to be real events.

epoch anchors code time t = 0 to a UTC instant, so a run of a real event can say which event. It lives here rather than on [time] because [time] does not survive to the typed in-memory config — only dt reaches a FieldDataset — whereas [run] round-trips end to end. It is also identity: "which real period is this" is a search-and-discovery question, not an integrator setting.

Source code in src/pypic/schema/_models.py

class Run(_StrictBase):
    """``[run]`` — identity + provenance of THIS run.

    ``id`` is the stable, globally unique identifier for the run, and is
    the key every derived product carries back to its source. ``name``
    is a human label and carries no uniqueness contract; ``doi`` is
    scarce by design, since archives do not mint one per run. No format
    is enforced — CCMC run IDs, ULIDs and per-lab conventions all differ,
    and the schema's job here is to record an identifier, not to police
    its shape.

    ``references`` is *results* metadata: what was published from this
    run. Distinct from ``doi`` (this run's data) and ``[model].doi``
    (the code).

    ``idealized`` is deliberately tri-state. ``True`` means the run does
    not correspond to a real time period — artificial drivers, artificial
    internal settings, or a 2D reduction of a 3D system — so harvesting
    real-event characteristics from it would produce wrong metadata.
    ``False`` asserts the conditions are real. ``None`` (the default)
    means unstated, which is what every deck written before this key
    existed actually means; a plain ``bool`` default would make all of
    them silently claim to be real events.

    ``epoch`` anchors code time ``t = 0`` to a UTC instant, so a run of a
    real event can say which event. It lives here rather than on
    ``[time]`` because ``[time]`` does not survive to the typed
    in-memory config — only ``dt`` reaches a `FieldDataset` — whereas
    ``[run]`` round-trips end to end. It is also identity: "which real
    period is this" is a search-and-discovery question, not an
    integrator setting.
    """

    name: str
    id: str | None = None
    description: str | None = None
    idealized: bool | None = None
    authors: list[Author] = Field(default_factory=list)
    date: _date | None = None
    epoch: AwareDatetime | None = None
    git_sha: str | None = None
    host: str | None = None
    license: str | None = None
    doi: str | None = None
    references: list[RunReference] = Field(default_factory=list)
    funding: list[str] = Field(default_factory=list)
    embargo: _date | None = None
    resources: RunResources | None = None
    # Stochasticity / ensemble metadata. Optional — readers fall back to
    # the `x-` extension namespace for codes that don't expose either.
    random_seed: int | None = None
    ensemble: Ensemble | None = None

RunReference

Bases: _StrictBase

[[run.references]] — one result published from this run.

Results metadata is what makes an archived run findable by the science it produced rather than only by its settings. Each entry needs at least one of doi / url / citation — an entry naming only a kind identifies nothing.

Source code in src/pypic/schema/_models.py

class RunReference(_StrictBase):
    """``[[run.references]]`` — one result published from this run.

    Results metadata is what makes an archived run findable by the
    science it produced rather than only by its settings. Each entry
    needs at least one of ``doi`` / ``url`` / ``citation`` — an entry
    naming only a ``kind`` identifies nothing.
    """

    doi: str | None = None
    url: str | None = None
    citation: str | None = None
    # Open string. Canonical: "publication" | "preprint" | "presentation"
    # | "poster" | "dataset" | "thesis" | "report".
    kind: str | None = None

    @model_validator(mode="after")
    def _check_identifiable(self) -> RunReference:
        if self.doi is None and self.url is None and self.citation is None:
            raise ValueError(
                "run.references entry needs at least one of 'doi', 'url' or 'citation'"
            )
        return self

RunResources

Bases: _StrictBase

[run.resources] — runtime accounting (all keys optional).

Source code in src/pypic/schema/_models.py

class RunResources(_StrictBase):
    """``[run.resources]`` — runtime accounting (all keys optional)."""

    mpi_ranks: PositiveInt | None = None
    mpi_topology: list[PositiveInt] | None = None
    nodes: PositiveInt | None = None
    wall_clock_hours: NonNegativeFloat | None = None
    cpu_core_hours: NonNegativeFloat | None = None
    node_hours: NonNegativeFloat | None = None
    peak_memory_gb: NonNegativeFloat | None = None
    cpu_type: str | None = None
    gpu_hours: NonNegativeFloat | None = None
    energy_kwh: NonNegativeFloat | None = None
    carbon_kg_co2eq: NonNegativeFloat | None = None
    allocations: list[Allocation] = Field(default_factory=list)

SchemaMeta

Bases: _StrictBase

[schema] — schema version + creation date.

Source code in src/pypic/schema/_models.py

class SchemaMeta(_StrictBase):
    """``[schema]`` — schema version + creation date."""

    version: str
    created: _date | None = None

SimulationSchema

Bases: _ExtensibleBase

Root model for a pypic simulation.toml v2.0 document.

Required top-level sections per v2.0: [schema], [model], [run], [time], [grid], [units], [coordinates], and at least one [[species]] entry.

Optional sections may be omitted entirely.

Extension policy at root: unknown keys must start with x- or x_. Known optional sections that are present are strictly validated.

[schema].version is the single discriminator for both the TOML config and the on-disk vocabulary it describes; v2.x is additive-only per schema.md §1 Versioning.

Source code in src/pypic/schema/_models.py

class SimulationSchema(_ExtensibleBase):
    """Root model for a pypic simulation.toml v2.0 document.

    Required top-level sections per v2.0:
        [schema], [model], [run], [time], [grid], [units],
        [coordinates], and at least one [[species]] entry.

    Optional sections may be omitted entirely.

    Extension policy at root: unknown keys must start with ``x-`` or
    ``x_``. Known optional sections that are present are strictly
    validated.

    ``[schema].version`` is the single discriminator for both the
    TOML config and the on-disk vocabulary it describes; v2.x is
    additive-only per ``schema.md`` §1 *Versioning*.
    """

    schema_: SchemaMeta = Field(..., alias="schema")
    model: Model
    run: Run
    time: Time
    grid: Grid
    units: Units
    coordinates: Coordinates
    species: list[Species] = Field(..., min_length=1)

    boundary_conditions: BoundaryConditions | None = None
    physics: Physics | None = None
    bodies: list[Body] = Field(default_factory=list)
    initial_conditions: InitialConditions | None = None
    drivers: list[Driver] = Field(default_factory=list)
    restart: Restart | None = None
    output: Output | None = None
    probes: list[Probe] = Field(default_factory=list)
    phase_space: PhaseSpace | None = None
    collisions: list[Collision] = Field(default_factory=list)

    @model_validator(mode="after")
    def _check_root_invariants(self) -> SimulationSchema:
        if not self.schema_.version.startswith("2."):
            raise ValueError(
                f"this validator implements schema v2.x; got "
                f"'{self.schema_.version}'. v2.0 renamed [units].system to "
                f"[units].anchor and replaced the PIC/MHD/SI/custom vocabulary "
                f"with from_species/explicit/si — see docs/schema.md section 1."
            )
        n = len(self.grid.dimensions)
        if (
            self.boundary_conditions is not None
            and len(self.boundary_conditions.lower) != n
        ):
            raise ValueError(
                f"boundary_conditions has "
                f"{len(self.boundary_conditions.lower)} axes but "
                f"grid.dimensions has {n}"
            )
        if (
            self.coordinates.physical_extent is not None
            and len(self.coordinates.physical_extent) != n
        ):
            raise ValueError(
                f"coordinates.physical_extent has "
                f"{len(self.coordinates.physical_extent)} entries but "
                f"grid.dimensions has {n}"
            )
        for body in self.bodies:
            if len(body.center) != n:
                raise ValueError(
                    f"body '{body.name}': center has {len(body.center)} "
                    f"entries but grid.dimensions has {n}"
                )
        if self.physics is not None:
            self._check_physics_matches_model_type()
        self._check_reference_species_exists()
        self._check_body_names_unique()
        self._check_driver_body_references()
        self._check_collision_species_references()
        self._check_bc_driver_references()
        self._check_output_particles_species_references()
        self._check_output_stream_axis_count(n)
        self._check_phase_space_consistency(n)
        self._check_extras_are_extensions()
        return self

    def _check_physics_matches_model_type(self) -> None:
        assert self.physics is not None
        # Only PIC/MHD/hybrid have a typed sub-table at v2.0; the new
        # vlasov/gyrokinetic model types route through the [physics]
        # extras namespace until typed sub-tables land in v2.1+. For
        # those, no typed-branch cross-check is possible (or needed).
        typed_branch = {"PIC": "pic", "MHD": "mhd", "hybrid": "hybrid"}.get(
            self.model.type
        )
        if typed_branch is None:
            return
        other_branches = {"pic", "mhd", "hybrid"} - {typed_branch}
        for branch in other_branches:
            if getattr(self.physics, branch) is not None:
                raise ValueError(
                    f"model.type = '{self.model.type}' but "
                    f"[physics.{branch}] is set; only "
                    f"[physics.{typed_branch}] is permitted for this model"
                )

    def _check_reference_species_exists(self) -> None:
        """Ensure ``[units].reference_species`` resolves.

        Either matches a declared ``[[species]].name`` entry, or names one
        of the always-valid PIC builtins ``{electrons, ions, protons}``.
        The builtin fallback covers legacy iPIC3D-style configs where the
        normalization references a canonical species the run hasn't
        explicitly declared in ``[[species]]``.
        """
        ref = getattr(self.units, "reference_species", None)
        if ref is None:
            return
        names = {s.name for s in self.species}
        builtins = {"electrons", "ions", "protons"}
        if ref not in names and ref not in builtins:
            raise ValueError(
                f"units.reference_species = '{ref}' does not match any "
                f"[[species]].name entry: {sorted(names)}"
            )

    def _check_body_names_unique(self) -> None:
        """Ensure ``[[bodies]].name`` entries are distinct.

        Drivers and initial-condition entries reference bodies by name
        (``[[drivers]].body``, ``[initial_conditions].dipole_bodies``).
        Duplicate names would silently route the foreign key to whichever
        entry the reader happens to encounter first. Catching it at
        validation time keeps body-name reference resolution unambiguous.
        """
        names = [b.name for b in self.bodies]
        if len(set(names)) != len(names):
            duplicates = sorted({n for n in names if names.count(n) > 1})
            raise ValueError(
                f"bodies entries must have distinct names; duplicates: {duplicates}"
            )

    def _check_driver_body_references(self) -> None:
        """Ensure every ``[[drivers]].body`` references a declared body.

        Drivers that delegate their target box to a body (``body = "..."``)
        can only resolve if that body exists in ``[[bodies]]``. Same
        string-as-foreign-key discipline as ``reference_species``.
        """
        body_names = {b.name for b in self.bodies}
        for driver in self.drivers:
            if driver.body is not None and driver.body not in body_names:
                raise ValueError(
                    f"driver '{driver.name}': body = '{driver.body}' does "
                    f"not match any [[bodies]].name entry: "
                    f"{sorted(body_names) or '(none declared)'}"
                )

    def _check_collision_species_references(self) -> None:
        """Ensure every ``[[collisions]].species_pair`` resolves.

        Both species names in each pair must match a declared
        ``[[species]].name`` entry. Self-collisions (same species twice)
        are permitted — codes that need them include them as
        ``species_pair = ["e", "e"]``.
        """
        if not self.collisions:
            return
        names = {s.name for s in self.species}
        for collision in self.collisions:
            for species_name in collision.species_pair:
                if species_name not in names:
                    raise ValueError(
                        f"collisions.species_pair references unknown species "
                        f"'{species_name}'; declared species: {sorted(names)}"
                    )

    def _check_output_particles_species_references(self) -> None:
        """Ensure every ``[output.particles].species`` resolves.

        Each name in the ``[output.particles].species`` list must match a
        declared ``[[species]].name`` entry. Without this check, a typo
        (``species = ["electron"]``) is silently accepted by the schema
        layer and only surfaces as an empty-write or KeyError at output
        time. Mirrors the foreign-key discipline used by
        ``[[collisions]].species_pair`` and ``[[drivers]].body``.
        """
        if self.output is None or self.output.particles is None:
            return
        requested = self.output.particles.species
        if not requested:
            return
        names = {s.name for s in self.species}
        for species_name in requested:
            if species_name not in names:
                raise ValueError(
                    f"output.particles.species references unknown species "
                    f"'{species_name}'; declared species: {sorted(names)}"
                )

    def _check_bc_driver_references(self) -> None:
        """Ensure every ``boundary_conditions.drivers_*`` resolves.

        Per-face driver names (in the default ``BoundaryConditions`` and
        in any ``field_overrides`` entry) must match a declared
        ``[[drivers]].name`` entry. ``None`` slots are allowed and mean
        "no driver supplies this face."
        """
        if self.boundary_conditions is None:
            return
        driver_names = {d.name for d in self.drivers}

        def _check_block(block: BoundaryConditionsBase, scope: str) -> None:
            for face_name in ("drivers_lower", "drivers_upper"):
                drivers = getattr(block, face_name)
                if drivers is None:
                    continue
                for axis_key, name in drivers.items():
                    if name not in driver_names:
                        raise ValueError(
                            f"{scope}.{face_name}['{axis_key}'] = '{name}' "
                            f"does not match any [[drivers]].name entry: "
                            f"{sorted(driver_names) or '(none declared)'}"
                        )

        _check_block(self.boundary_conditions, "boundary_conditions")
        if self.boundary_conditions.field_overrides is not None:
            for group, override in self.boundary_conditions.field_overrides.items():
                _check_block(
                    override, f"boundary_conditions.field_overrides[{group!r}]"
                )

    def _check_output_stream_axis_count(self, n: int) -> None:
        """Ensure each ``[[output.streams]].region`` aligns with the grid."""
        if self.output is None or not self.output.streams:
            return
        for stream in self.output.streams:
            region = stream.region
            if region is None:
                continue
            if isinstance(region, BoxRegion):
                if len(region.lower) != n:
                    raise ValueError(
                        f"output.streams[{stream.name!r}].region (box) has "
                        f"{len(region.lower)} axes but grid.dimensions has {n}"
                    )
            elif isinstance(region, PlaneRegion) and region.axis >= n:
                raise ValueError(
                    f"output.streams[{stream.name!r}].region (plane) "
                    f"axis {region.axis} out of range for grid.dimensions"
                    f" ({n} axes)"
                )

    def _check_phase_space_consistency(self, n: int) -> None:
        """Ensure ``[phase_space]`` agrees with ``[grid]`` on the spatial part.

        When ``[phase_space]`` is present, its first ``n`` dimensions must
        match ``[grid].dimensions`` exactly — the spatial sub-grid is
        owned by ``[grid]``; the velocity / extra-D extension lives in
        ``[phase_space]``. The remaining ``len(phase_space.dimensions) - n``
        entries describe the kinetic side (e.g. 2 velocity dims for
        gyrokinetic, 3 for full Vlasov phase space).
        """
        if self.phase_space is None:
            return
        ps_dims = self.phase_space.dimensions
        if len(ps_dims) <= n:
            raise ValueError(
                f"phase_space.dimensions has {len(ps_dims)} axes but "
                f"grid.dimensions has {n} (phase space must strictly "
                f"extend the spatial grid; declare velocity / extra-D "
                f"dimensions beyond the {n} spatial ones)"
            )
        for i in range(n):
            if ps_dims[i] != self.grid.dimensions[i]:
                raise ValueError(
                    f"phase_space.dimensions[{i}] ({ps_dims[i]}) must match "
                    f"grid.dimensions[{i}] ({self.grid.dimensions[i]})"
                )
        # ``phase_space.storage.block_size`` describes sparse-block storage
        # of the velocity sub-grid. Its length must equal the number of
        # velocity axes (``len(ps_dims) - n``), and each block must evenly
        # divide the corresponding velocity dimension.
        if self.phase_space.storage is None:
            return
        block_size = self.phase_space.storage.block_size
        if block_size is None:
            return
        n_velocity = len(ps_dims) - n
        if len(block_size) != n_velocity:
            raise ValueError(
                f"phase_space.storage.block_size has {len(block_size)} axes "
                f"but phase_space has {n_velocity} velocity dimensions "
                f"(phase_space.dimensions[{n}:])"
            )
        for i, (block, dim) in enumerate(zip(block_size, ps_dims[n:], strict=True)):
            if dim % block != 0:
                raise ValueError(
                    f"phase_space.storage.block_size[{i}] ({block}) must "
                    f"divide phase_space.dimensions[{n + i}] ({dim}) evenly"
                )

    def _check_extras_are_extensions(self) -> None:
        extra: dict[str, Any] = self.__pydantic_extra__ or {}
        non_ext = [k for k in extra if not _is_extension_key(k)]
        if non_ext:
            raise ValueError(
                f"unknown top-level keys (extensions must be prefixed 'x-' "
                f"or 'x_'): {sorted(non_ext)}"
            )

Species

Bases: _StrictBase

One entry in [[species]].

Provide either (charge, mass) OR charge_to_mass, not both. Validated after the fact.

Species are indexed in declaration order — _s0 binds to the first [[species]] entry, _s1 to the second, etc. Reordering entries is a breaking change to any downstream field-name reference that uses the _sN suffix.

Source code in src/pypic/schema/_models.py

class Species(_StrictBase):
    """One entry in ``[[species]]``.

    Provide either ``(charge, mass)`` OR ``charge_to_mass``, not both.
    Validated after the fact.

    Species are indexed in declaration order — ``_s0`` binds to the
    first ``[[species]]`` entry, ``_s1`` to the second, etc. Reordering
    entries is a breaking change to any downstream field-name reference
    that uses the ``_sN`` suffix.
    """

    name: str
    charge: float | None = None
    # Zero is legal for a fluid species only — massless electrons are the
    # standard hybrid closure, and `inertia` (me/mi, 0 = massless) has
    # always accepted it. `_check_mass_charge` enforces the restriction.
    mass: NonNegativeFloat | None = None
    charge_to_mass: float | None = None
    # 0 (or absent) marks a fluid species — see [[species]] in schema.md.
    particles_per_cell: (
        NonNegativeInt
        | Annotated[list[NonNegativeInt], Field(min_length=3, max_length=3)]
        | None
    ) = None
    temperature: NonNegativeFloat | None = None
    thermal_velocity: Vec3Float | None = None
    drift_velocity: Vec3Float | None = None
    density: NonNegativeFloat | None = None
    closure: Closure | None = None
    gamma_eos: PositiveFloat | None = None
    # Anisotropic adiabatic indices for two-fluid + 10-moment hybrids
    # (Gkeyll, Hakim) where the species pressure splits into parallel
    # and perpendicular channels. Both must be set together; cannot
    # combine with the scalar ``gamma_eos``. Validators below enforce
    # the (par AND perp) XOR (gamma_eos) discipline.
    gamma_eos_par: PositiveFloat | None = None
    gamma_eos_perp: PositiveFloat | None = None
    inertia: NonNegativeFloat | None = None
    # Particle shape factor (NGP / CIC / TSC / PQS) per ED-PIC. Optional —
    # codes that pin a global default leave this unset; codes that vary the
    # shape per species (WarpX, Smilei) populate it explicitly.
    shape: ParticleShape | None = None
    # Tracer flag. PIC codes routinely write a tagged subset for trajectory
    # tracking; the reader is responsible for propagating this hint to
    # downstream particle-trajectory analysis. Test-particle vs tagged-tracer
    # semantics may need a follow-up `tracer_kind` field; the boolean is the
    # additive starting point.
    tracer: bool = False

    def _is_kinetic(self) -> bool:
        """Whether the deck asks for macroparticles rather than a fluid."""
        ppc = self.particles_per_cell
        if ppc is None:
            return False
        return any(ppc) if isinstance(ppc, list) else ppc > 0

    @model_validator(mode="after")
    def _check_mass_charge(self) -> Species:
        has_qm = self.charge is not None and self.mass is not None
        has_qom = self.charge_to_mass is not None
        if not (has_qm or has_qom):
            raise ValueError(
                f"species '{self.name}' must specify either "
                f"(charge + mass) or charge_to_mass"
            )
        if has_qm and has_qom:
            raise ValueError(
                f"species '{self.name}' has both (charge + mass) and "
                f"charge_to_mass — choose one"
            )
        if self.mass == 0.0 and self._is_kinetic():
            raise ValueError(
                f"species '{self.name}' carries particles_per_cell, so it is "
                f"kinetic and needs mass > 0; mass = 0 describes a massless "
                f"fluid species"
            )
        has_par = self.gamma_eos_par is not None
        has_perp = self.gamma_eos_perp is not None
        if has_par != has_perp:
            raise ValueError(
                f"species '{self.name}': gamma_eos_par and gamma_eos_perp "
                f"must both be present or both absent"
            )
        if has_par and self.gamma_eos is not None:
            raise ValueError(
                f"species '{self.name}': cannot set scalar gamma_eos and "
                f"anisotropic (gamma_eos_par, gamma_eos_perp) simultaneously"
            )
        return self

Time

Bases: _StrictBase

[time] — temporal integration controls.

Scheme-specific keys are deliberately not modelled as a discriminated union — the vocabulary is still settling and the cost of a wrong shape here is low. v2.0 enforces only the cross-field invariants that are unambiguous:

• fixed/subcycled require dt > 0 (the integration step);
• subcycled requires field_substeps (dt_field is recommended but advisory, not enforced);
• adaptive omits dt (or accepts any non-negative value as a hint); the runtime derives the first step from cfl / dt_min / dt_max and owns CFL bookkeeping thereafter.

A future v2.1 may formalise these as a discriminated union once codes converge on a common spelling.

Source code in src/pypic/schema/_models.py

class Time(_StrictBase):
    """``[time]`` — temporal integration controls.

    Scheme-specific keys are deliberately *not* modelled as a discriminated
    union — the vocabulary is still settling and the cost of a wrong shape
    here is low. v2.0 enforces only the cross-field invariants that are
    unambiguous:

    - fixed/subcycled require ``dt > 0`` (the integration step);
    - subcycled requires ``field_substeps`` (``dt_field`` is recommended
      but advisory, not enforced);
    - adaptive omits ``dt`` (or accepts any non-negative value as a hint);
      the runtime derives the first step from ``cfl`` / ``dt_min`` /
      ``dt_max`` and owns CFL bookkeeping thereafter.

    A future v2.1 may formalise these as a discriminated union once codes
    converge on a common spelling.
    """

    scheme: TimeScheme = "fixed"
    dt: NonNegativeFloat | None = None
    t_start: float
    t_end: float
    n_steps: PositiveInt
    cfl: float | None = None
    dt_min: float | None = None
    dt_max: float | None = None
    dt_field: float | None = None
    field_substeps: PositiveInt | None = None
    splitting: TimeSplitting | None = None

    @model_validator(mode="after")
    def _check_time_range(self) -> Time:
        if self.t_end < self.t_start:
            raise ValueError(f"t_end ({self.t_end}) < t_start ({self.t_start})")
        if self.scheme == "subcycled" and self.field_substeps is None:
            raise ValueError(
                "scheme='subcycled' requires field_substeps (and usually dt_field)"
            )
        # Adaptive runs derive the first step from CFL bookkeeping and may
        # omit ``dt`` entirely. Every other scheme — fixed, subcycled, and
        # the RK / SSP-RK / IMEX-RK variants — uses ``dt`` as the integration
        # step (or the base step that CFL may further bound from above).
        if self.scheme != "adaptive" and (self.dt is None or self.dt == 0.0):
            raise ValueError(f"scheme={self.scheme!r} requires dt > 0")
        return self

UnitsExplicit

Bases: _UnitsBase

[units] with anchor = "explicit" — the length unit is given.

Covers MHD, PLUTO/Athena++-class codes, gyrokinetics, and any hand-built reference set. Three relations close the eight primitives:

\[v = l/t, \qquad E = vB, \qquad B = v\sqrt{\mu_0 n m}\]

The third ties the field, velocity and density scales together, so a deck supplies reference_length plus any two of:

• a velocity — reference_velocity or reference_time
• a density — reference_number_density or reference_mass_density
• a field — reference_b_field or reference_e_field

and the third follows. Supplying all three is legal: the relations then describe rather than derive, which is what gyrokinetic decks need, where \(v \neq l/t\) by \(\rho_*\) and \(B^2 \neq \mu_0 n m v^2\) by \(2/\beta\) on purpose. Normalization.rationalization_ratio reports the result.

Duplicate spellings of one primitive are rejected; redundant distinct primitives are accepted. Both density keys together is an error, because which unit a number carries would be ambiguous. reference_b_field with reference_velocity is fine — those are two different quantities, and a tolerance gate could not tell a deliberate \(2/\beta\) from a typo anyway.

reference_mass defaults to the proton mass whichever density spelling is used. Keying the default off the spelling would make two decks describing one plasma disagree by \(m_p/m_e\) in silence, which is the trap this form exists to remove.

Source code in src/pypic/schema/_models.py

class UnitsExplicit(_UnitsBase):
    r"""``[units]`` with ``anchor = "explicit"`` — the length unit is given.

    Covers MHD, PLUTO/Athena++-class codes, gyrokinetics, and any
    hand-built reference set.  Three relations close the eight
    primitives:

    $$v = l/t, \qquad E = vB, \qquad B = v\sqrt{\mu_0 n m}$$

    The third ties the field, velocity and density scales together, so
    a deck supplies `reference_length` plus **any two** of:

    - a velocity — `reference_velocity` or `reference_time`
    - a density — `reference_number_density` or `reference_mass_density`
    - a field — `reference_b_field` or `reference_e_field`

    and the third follows.  Supplying all three is legal: the relations
    then describe rather than derive, which is what gyrokinetic decks
    need, where $v \neq l/t$ by $\rho_*$ and $B^2 \neq \mu_0 n m v^2$ by
    $2/\beta$ on purpose.  `Normalization.rationalization_ratio` reports
    the result.

    **Duplicate spellings of one primitive are rejected; redundant
    distinct primitives are accepted.**  Both density keys together is
    an error, because which unit a number carries would be ambiguous.
    `reference_b_field` with `reference_velocity` is fine — those are
    two different quantities, and a tolerance gate could not tell a
    deliberate $2/\beta$ from a typo anyway.

    `reference_mass` defaults to the proton mass whichever density
    spelling is used.  Keying the default off the spelling would make
    two decks describing one plasma disagree by $m_p/m_e$ in silence,
    which is the trap this form exists to remove.
    """

    anchor: Literal["explicit"]
    reference_length: PositiveFloat
    reference_time: PositiveFloat | None = None
    reference_velocity: PositiveFloat | None = None
    reference_b_field: PositiveFloat | None = None
    reference_e_field: PositiveFloat | None = None
    reference_number_density: PositiveFloat | None = None
    reference_mass_density: PositiveFloat | None = None
    reference_mass: PositiveFloat | None = None
    reference_charge: PositiveFloat | None = None

    @model_validator(mode="after")
    def _check_determined(self) -> UnitsExplicit:
        if (
            self.reference_number_density is not None
            and self.reference_mass_density is not None
        ):
            raise ValueError(
                "[units] names the density twice: 'reference_number_density' "
                "(m^-3) and 'reference_mass_density' (kg/m^3). Give exactly "
                "one — which unit the number carries is otherwise ambiguous."
            )
        scales = {
            "a velocity ('reference_velocity' or 'reference_time')": (
                self.reference_velocity is not None or self.reference_time is not None
            ),
            ("a density ('reference_number_density' or 'reference_mass_density')"): (
                self.reference_number_density is not None
                or self.reference_mass_density is not None
            ),
            "a field ('reference_b_field' or 'reference_e_field')": (
                self.reference_b_field is not None or self.reference_e_field is not None
            ),
        }
        missing = [name for name, given in scales.items() if not given]
        if len(missing) > 1:
            raise ValueError(
                "[units] anchor = 'explicit' is underdetermined. With "
                "'reference_length' given, supply any two of the three "
                "scales; B = v*sqrt(mu_0*n*m) closes the third. Missing: "
                + "; ".join(missing)
            )
        return self

UnitsFromSpecies

Bases: _UnitsBase

[units] with anchor = "from_species" — length from microphysics.

The form for codes that resolve a kinetic scale: PIC, hybrid, and anything else whose grid is measured in skin depths. The length unit is derived, \(l_{ref} = c/\omega_{ref}\), from the reference species' plasma frequency — which is what distinguishes this form from UnitsExplicit, where length is given.

The velocity unit defaults to c, the PIC convention. Hybrid codes normalize to the Alfvén speed instead and set reference_velocity to it, which makes \(B_{ref}\) the field at which \(v_A\) equals that speed and lands the time unit on the inverse ion cyclotron frequency, via \(d_i \Omega_{ci} = v_A\).

Source code in src/pypic/schema/_models.py

class UnitsFromSpecies(_UnitsBase):
    r"""``[units]`` with ``anchor = "from_species"`` — length from microphysics.

    The form for codes that resolve a kinetic scale: PIC, hybrid, and
    anything else whose grid is measured in skin depths.  The length
    unit is *derived*, $l_{ref} = c/\omega_{ref}$, from the reference
    species' plasma frequency — which is what distinguishes this form
    from `UnitsExplicit`, where length is given.

    The velocity unit defaults to *c*, the PIC convention.  Hybrid codes
    normalize to the Alfvén speed instead and set `reference_velocity`
    to it, which makes $B_{ref}$ the field at which $v_A$ equals that
    speed and lands the time unit on the inverse ion cyclotron
    frequency, via $d_i \Omega_{ci} = v_A$.
    """

    anchor: Literal["from_species"]
    reference_species: str = "electrons"
    reference_number_density: PositiveFloat
    reference_mass: PositiveFloat | None = None
    # A magnitude, matching the builtin defaults (electrons carry +e).
    # Signed input used to survive here and die downstream complaining
    # about b_field_ref, a key the deck never mentioned.
    reference_charge: PositiveFloat | None = None
    reference_velocity: PositiveFloat | None = None

UnitsSI

Bases: _UnitsBase

[units] with anchor = "si" — SI data with no code-unit anchor.

All eight references are 1.0, so conversion is a no-op. That makes electromagnetic quantities unsafe: pypic.derived computes in SI-rationalized units where \(\mu_0 = 1\), and SI data has \(\mu_0 = 1.2566\times10^{-6}\), so anything carrying a vacuum constant is wrong by a power of it.

A deck that wants its SI arrays computed on correctly declares a real anchor and sets data_in_si instead.

Source code in src/pypic/schema/_models.py

class UnitsSI(_UnitsBase):
    r"""``[units]`` with ``anchor = "si"`` — SI data with no code-unit anchor.

    All eight references are 1.0, so conversion is a no-op.  That makes
    electromagnetic quantities unsafe: `pypic.derived` computes in
    SI-rationalized units where $\mu_0 = 1$, and SI data has
    $\mu_0 = 1.2566\times10^{-6}$, so anything carrying a vacuum
    constant is wrong by a power of it.

    A deck that wants its SI arrays computed on correctly declares a
    real anchor and sets ``data_in_si`` instead.
    """

    anchor: Literal["si"]

    @model_validator(mode="after")
    def _check_no_rescale(self) -> UnitsSI:
        if self.data_in_si:
            raise ValueError(
                "[units] anchor = 'si' with data_in_si = true would "
                "normalize SI arrays against identity references, which is a "
                "no-op. Declare the anchor to rescale against — "
                "anchor = 'explicit' with reference_length, a density and a "
                "field or velocity."
            )
        return self

schema_structured_diff(a, b)

Return a structured {added, removed, changed} diff.

Semantics

• added: sorted list of paths present in b but not a.
• removed: sorted list of paths present in a but not b.
• changed: dict mapping path → {"before": ..., "after": ...} for leaf-value mismatches or list-length differences. Lists of equal length recurse element-wise (each index gets its own path); lists of differing lengths record the entire lists at the parent path without per-element add/remove decomposition.

Paths use RFC 6901 JSON Pointer syntax (/$defs/Run, /properties/time/properties/dt) with ~ → ~0 and / → ~1 escapes for object keys.

Examples:

>>> schema_structured_diff({"a": 1}, {"a": 1})
{'added': [], 'removed': [], 'changed': {}}
>>> schema_structured_diff({"a": 1, "b": 2}, {"a": 1, "c": 3})
{'added': ['/c'], 'removed': ['/b'], 'changed': {}}

Source code in src/pypic/schema/_diff.py

def schema_structured_diff(
    a: Mapping[str, Any],
    b: Mapping[str, Any],
) -> dict[str, Any]:
    r"""Return a structured ``{added, removed, changed}`` diff.

    Semantics
    ---------
    - ``added``: sorted list of paths present in *b* but not *a*.
    - ``removed``: sorted list of paths present in *a* but not *b*.
    - ``changed``: dict mapping path → ``{"before": ..., "after": ...}``
      for leaf-value mismatches or list-length differences. Lists of
      equal length recurse element-wise (each index gets its own path);
      lists of differing lengths record the entire lists at the parent
      path without per-element add/remove decomposition.

    Paths use RFC 6901 JSON Pointer syntax (``/$defs/Run``,
    ``/properties/time/properties/dt``) with ``~`` → ``~0`` and
    ``/`` → ``~1`` escapes for object keys.

    Examples
    --------
    >>> schema_structured_diff({"a": 1}, {"a": 1})
    {'added': [], 'removed': [], 'changed': {}}
    >>> schema_structured_diff({"a": 1, "b": 2}, {"a": 1, "c": 3})
    {'added': ['/c'], 'removed': ['/b'], 'changed': {}}
    """
    added: list[str] = []
    removed: list[str] = []
    changed: dict[str, dict[str, Any]] = {}
    _walk_diff(a, b, "", added, removed, changed)
    added.sort()
    removed.sort()
    return {
        "added": added,
        "removed": removed,
        "changed": dict(sorted(changed.items())),
    }

schema_text_diff(a, b, *, fromfile='a', tofile='b', n_context=3)

Return a unified text diff of two JSON Schema documents.

Returns the empty string when the documents are byte-equivalent after pretty-printing with sorted keys.

Parameters:

Name	Type	Description	Default
a	Mapping[str, Any]	JSON Schema documents (or any JSON-serializable mappings) to compare. Order is significant: lines prefixed - are in a, lines prefixed + are in b.	required
b	Mapping[str, Any]	JSON Schema documents (or any JSON-serializable mappings) to compare. Order is significant: lines prefixed - are in a, lines prefixed + are in b.	required
fromfile	str	Labels for the unified-diff header lines.	'a'
tofile	str	Labels for the unified-diff header lines.	'a'
n_context	int	Number of context lines around each hunk (difflib default 3).	3

Source code in src/pypic/schema/_diff.py

def schema_text_diff(
    a: Mapping[str, Any],
    b: Mapping[str, Any],
    *,
    fromfile: str = "a",
    tofile: str = "b",
    n_context: int = 3,
) -> str:
    """Return a unified text diff of two JSON Schema documents.

    Returns the empty string when the documents are byte-equivalent
    after pretty-printing with sorted keys.

    Parameters
    ----------
    a, b
        JSON Schema documents (or any JSON-serializable mappings) to
        compare. Order is significant: lines prefixed ``-`` are in *a*,
        lines prefixed ``+`` are in *b*.
    fromfile, tofile
        Labels for the unified-diff header lines.
    n_context
        Number of context lines around each hunk (``difflib`` default 3).
    """
    a_lines = dump_schema(a, pretty=True).splitlines(keepends=True)
    b_lines = dump_schema(b, pretty=True).splitlines(keepends=True)
    return "".join(
        difflib.unified_diff(
            a_lines,
            b_lines,
            fromfile=fromfile,
            tofile=tofile,
            n=n_context,
        )
    )

build_schema(*, include_x_extensions=False, inline_single_use_defs=False, schema_version=SCHEMA_VERSION)

Return the post-processed JSON Schema 2020-12 document.

Parameters:

Name	Type	Description	Default
include_x_extensions	bool	When True, annotate non-strict object schemas with patternProperties: {"^x[-_]": {}} to document the v2.0 x-<code> extension namespace. Off by default for a leaner document; the namespace is described in the top-level $comment regardless.	False
inline_single_use_defs	bool	When True, $defs entries referenced exactly once are inlined at the reference site and removed from $defs. Helps json-schema-to-zod produce flatter Zod, at the cost of a larger root schema. Off by default.	False
schema_version	str	Override the version stamped in $id and title. Does not affect which models are exported.	SCHEMA_VERSION

Source code in src/pypic/schema/_export.py

def build_schema(
    *,
    include_x_extensions: bool = False,
    inline_single_use_defs: bool = False,
    schema_version: str = SCHEMA_VERSION,
) -> dict[str, Any]:
    """Return the post-processed JSON Schema 2020-12 document.

    Parameters
    ----------
    include_x_extensions
        When True, annotate non-strict object schemas with
        ``patternProperties: {"^x[-_]": {}}`` to document the v2.0
        ``x-<code>`` extension namespace. Off by default for a leaner
        document; the namespace is described in the top-level
        ``$comment`` regardless.
    inline_single_use_defs
        When True, ``$defs`` entries referenced exactly once are inlined
        at the reference site and removed from ``$defs``. Helps
        ``json-schema-to-zod`` produce flatter Zod, at the cost of a
        larger root schema. Off by default.
    schema_version
        Override the version stamped in ``$id`` and ``title``. Does not
        affect which models are exported.
    """
    schema = SimulationSchema.model_json_schema(
        mode="validation",
        ref_template="#/$defs/{model}",
        by_alias=True,
    )
    _drop_pydantic_noise(schema)
    if inline_single_use_defs:
        _inline_single_use_defs(schema)
    if include_x_extensions:
        _annotate_x_extensions(schema)
    _stamp_metadata(schema, schema_version=schema_version)
    return cast("dict[str, Any]", _sort_keys(schema))

dump_schema(schema, *, pretty=True)

Serialize schema as JSON with stable key ordering.

Both pretty and compact output end with a trailing newline so the file plays nicely with POSIX text-file conventions and git diff, and so callers don't have to special-case the sink.

Source code in src/pypic/schema/_export.py

def dump_schema(schema: Mapping[str, Any], *, pretty: bool = True) -> str:
    """Serialize ``schema`` as JSON with stable key ordering.

    Both ``pretty`` and ``compact`` output end with a trailing newline
    so the file plays nicely with POSIX text-file conventions and
    ``git diff``, and so callers don't have to special-case the sink.
    """
    if pretty:
        return json.dumps(schema, indent=2, sort_keys=True) + "\n"
    return json.dumps(schema, separators=(",", ":"), sort_keys=True) + "\n"

get_schema_path(version=SCHEMA_VERSION)

Locate the bundled JSON Schema file inside the installed package.

Returns the path to simulation.schema.v{version}.json shipped in the pypic wheel. Works for normal pip install; zipped installs would require importlib.resources.as_file — pypic isn't packaged that way in practice (requires-python >=3.13 wheels).

Source code in src/pypic/schema/_export.py

def get_schema_path(version: str = SCHEMA_VERSION) -> Path:
    """Locate the bundled JSON Schema file inside the installed package.

    Returns the path to ``simulation.schema.v{version}.json`` shipped in
    the pypic wheel. Works for normal ``pip install``; zipped installs
    would require ``importlib.resources.as_file`` — pypic isn't packaged
    that way in practice (requires-python >=3.13 wheels).
    """
    ref = importlib.resources.files("pypic.schema").joinpath(
        f"simulation.schema.v{version}.json"
    )
    return Path(str(ref))

validate_simulation_toml(source)

Validate a pypic v2.0 simulation.toml document.

Parameters:

Name	Type	Description	Default
source	str | bytes | PathLike[str] | dict[str, Any]	Either a filesystem path to a .toml file, a str/bytes blob of TOML text, or a pre-parsed dict (the output of tomllib.loads).	required

Returns:

Type	Description
SimulationSchema	The validated, fully-typed root model. All cross-section invariants have already been checked.

Raises:

Type	Description
ValidationError	When any field fails validation. The error object carries precise dotted paths (e.g. grid.spacing.0) for every violation, plus the contextual message from any cross-section validator.
FileNotFoundError	When source is a path that does not exist.
TOMLDecodeError	When source is a path or text that is not valid TOML.

Examples:

>>> doc = '''
... [schema]
... version = "2.0"
... [model]
... name = "demo"
... type = "PIC"
... [run]
... name = "r0"
... [time]
... scheme = "fixed"
... dt = 0.1
... t_start = 0.0
... t_end = 1.0
... n_steps = 10
... [grid]
... dimensions = [4, 4, 4]
... spacing = [1.0, 1.0, 1.0]
... lower = [0.0, 0.0, 0.0]
... upper = [4.0, 4.0, 4.0]
... [units]
... anchor = "si"
... [coordinates]
... geometry = "cartesian"
... frame = "sim"
... [[species]]
... name = "electrons"
... charge = -1.0
... mass = 1.0
... '''
>>> s = validate_simulation_toml(doc)
>>> s.model.name
'demo'

Source code in src/pypic/schema/_loader.py

def validate_simulation_toml(
    source: str | bytes | PathLike[str] | dict[str, Any],
) -> SimulationSchema:
    """Validate a pypic v2.0 simulation.toml document.

    Parameters
    ----------
    source
        Either a filesystem path to a .toml file, a str/bytes blob of
        TOML text, or a pre-parsed dict (the output of ``tomllib.loads``).

    Returns
    -------
    SimulationSchema
        The validated, fully-typed root model. All cross-section
        invariants have already been checked.

    Raises
    ------
    pydantic.ValidationError
        When any field fails validation. The error object carries
        precise dotted paths (e.g. ``grid.spacing.0``) for every
        violation, plus the contextual message from any cross-section
        validator.
    FileNotFoundError
        When ``source`` is a path that does not exist.
    tomllib.TOMLDecodeError
        When ``source`` is a path or text that is not valid TOML.

    Examples
    --------
    >>> doc = '''
    ... [schema]
    ... version = "2.0"
    ... [model]
    ... name = "demo"
    ... type = "PIC"
    ... [run]
    ... name = "r0"
    ... [time]
    ... scheme = "fixed"
    ... dt = 0.1
    ... t_start = 0.0
    ... t_end = 1.0
    ... n_steps = 10
    ... [grid]
    ... dimensions = [4, 4, 4]
    ... spacing = [1.0, 1.0, 1.0]
    ... lower = [0.0, 0.0, 0.0]
    ... upper = [4.0, 4.0, 4.0]
    ... [units]
    ... anchor = "si"
    ... [coordinates]
    ... geometry = "cartesian"
    ... frame = "sim"
    ... [[species]]
    ... name = "electrons"
    ... charge = -1.0
    ... mass = 1.0
    ... '''
    >>> s = validate_simulation_toml(doc)
    >>> s.model.name
    'demo'
    """
    data = _load_toml(source)
    return SimulationSchema.model_validate(data)