Quartz 5

infra

Properties2
tagsutils
aliasesPackage, RecursiveNamespace, SuperPackage

2 min read

infra — project namespaces, paths & NPZ I/O

Purpose

The bottom layer of the support library: flexible attribute namespaces (Package /
RecursiveNamespace / SuperPackage), the canonical path constants (PROJECT_ROOT, YAML_DICT,
today’s LOGS_DIR), and the lean save/load helpers for NPZ + summary dicts. Almost everything
imports from here.

Role in the system

  • Namespaces. Package is the project’s mutable record type — imported by breve_controller,
    com_controller, guidance_classes, analysis/runner.py and analysis/logger.py. Package.pack(...)
    is the sanctioned “pack these locals” idiom (.claude/rules/PYTHON.md).
  • Config namespaces. RecursiveNamespace.from_mapping turns parsed YAML into dotted-access config;
    parameter_loader builds parameters.yaml and the asset YAMLs on top of it.
  • Paths. PROJECT_ROOT / MODELS_DIR / YAML_DICT / dated LOGS_DIR are the single source of
    filesystem truth consumed across utils/, analysis/ and validation/.
  • NPZ I/O. save_npz / load_npz / last_npz are the lean numbered-file store used by ad-hoc
    studies; the run pipeline’s structured logs go through analysis/logger.py, not here.
  • Pretty-printing: infra re-exports printing’s formatted_dict (from utils.printing import formatted_dict) — the inline copy + _format_* family was removed 2026-06-22, so printing is now
    the single source (Package.__repr__ / SuperPackage route through it).

Inputs / Outputs

  • In: YAML paths, summary dicts, keyword arrays, file stems + an optional cfg/model_key.
  • Out: RecursiveNamespace/Package config objects, numbered .npz/.txt paths under LOGS_DIR,
    and aligned text snapshots.

Key functions / classes

  • Package — mutable attribute namespace with deep copy, recursive merge/update_from, dict log — utils/infra.py:262
  • RecursiveNamespace.from_mapping — nested-dict → dotted-access config namespace — utils/infra.py:393
  • SuperPackage — Package that auto-converts nested mappings on construction — utils/infra.py:430
  • load_spec — YAML file (optionally merged onto a base dict) → RecursiveNamespace — utils/infra.py:17
  • save_npz / load_npz / last_npz — numbered <stem>_<model_key>_N.npz save/load/latest — utils/infra.py:185 / :202 / :169
  • next_filename / find_last_idx — next free / last-used numeric suffix in a folder — utils/infra.py:78 / :98
  • formatted_dict — aligned, precision-controlled pretty-print of nested dicts/arrays — imported from printing (not defined here since 2026-06-22)
  • PROJECT_ROOT, YAML_DICT, LOGS_DIR — repo root, domain-YAML map, today’s dated log dir — utils/infra.py:11 / :14 / :47

Pseudocode (numbered-file store)

save_npz(stem, **arrays)        # stem += "_<model_key>"; fname = next_filename(stem, folder)
                                # np.savez(fname, **arrays)  ->  <stem>_N.npz under LOGS_DIR/npz
load_npz(stem, query=[...])     # fname = last_npz(stem)     # highest N matching <stem>_*.npz
                                # unwrap object arrays; return the queried entries

parameter_loader · printing · data_classes · data_class_helpers · breve_controller · terminology

Graph View

Backlinks