data_class_helpers

data_class_helpers — dataclass field factories + log serialisation

Purpose

Two tiny, stateless utilities for the sim records: field default factories (default_flat_zero,
default_z, default_eye) that give each dataclass instance its own fresh numpy default, and the
internal log-serialisation walk (_as_log_dict → _field_names → _log_value) behind Package.log().

Role in the system

• Consumed by data_classes: every numpy field on State/Desired/Package is declared with one of
  the default_* factories so two instances never share a mutable default array.
• The _as_log_dict walk is the serialiser invoked by Package.log() (utils/infra.py:265) and by the
  per-record log() methods (e.g. data_classes.py:128), turning a dataclass into a flat, log-safe dict
  for the run → log pipeline that the orchestrator / data_analyzer read back.

Inputs / Outputs

• In: default_* take a size (or nothing) and return a dataclasses.field(default_factory=…); the
  log walk takes any dataclass instance plus arbitrary nested values.
• Out: field descriptors for class bodies; a {field_name: log_safe_value} dict where enums become
  .value, numpy scalars become Python scalars, arrays are copied, and dict/list/tuple recurse.

Key functions

• default_flat_zero — field defaulting to a fresh flat zero vector of length size — utils/data_class_helpers.py:7
• default_z — field defaulting to a fresh unit +z axis [0,0,1] — utils/data_class_helpers.py:12
• default_eye — field defaulting to a fresh size×size identity — utils/data_class_helpers.py:17
• _log_value — coerce one value to a log-safe form (enum/np-scalar/array-copy + container recursion) — utils/data_class_helpers.py:34

Related

data_classes · infra · orchestrator · terminology