parameter_loader

parameter_loader — config loading + derived-quantity baking

Purpose

Load parameters.yaml (+ robot/target asset YAMLs) into one RecursiveNamespace, bake every
derived quantity at load time, and expose the rederive_* escapes from the resulting snapshot trap.

Role in the system

• The single entry to config: load_parameters() is what runner, validation/run_mission.py, and
  every controller construction call to get a finalized cfg.
• Resolves assets via assets.yaml → robot block consumed by robot (GiordanoRobot), target block
  feeds the mesh path used by mesh / target_finder.
• Builds the controller gain matrices (Gains → make_namespace) that
  breve_controller / com_controller read as cfg.controller.gains.*.
• Derives the dt-dependent guidance smoothing and camera-aim bounds consumed by the ee_guidance /
  com_guidance tower.
• Namespaces, path constants (YAML_DICT, PROJECT_ROOT) and apply_overrides’ nesting test come from
  utils/infra.py.

Inputs / Outputs

• In: parameters.yaml + assets.yaml (via YAML_DICT); an optional nested overrides namespace.
• Out: a fully-derived config RecursiveNamespace — raw YAML leaves plus every baked quantity
  (orbit radius, gain matrices, accel limits, smoothing alphas, camera FOV/reach geometry, startup steps).

Key methods / functions

• load_parameters(overrides) — public entry: load + override + finalize — utils/parameter_loader.py:15
• ParameterLoader.load — load parameters domain, apply overrides, finalize — :87
• finalize_parameters — attach robot/target assets, then bake derived params + flags — :121
• add_derived_parameters — the derivation hub (orbit, gains, guidance, camera) — :144
• apply_flags — resolve boolean/startup flags (effective controller startup steps) — :129
• apply_overrides — recursive in-place override; raises on missing / shape-mismatched paths — :227
• build_controller_gains(ctrl) — raw gain leaves → diag-matrix namespace — :40
• rederive_dt_dependent(params) — re-bake dt-derived params after a post-load dt override — :56
• rederive_camera_radius(params) — re-bake camera targeting after a radius_scale/reach.* override — :66

Footguns

The snapshot trap: derived quantities are baked once, BEFORE any post-load override

finalize_parameters() bakes all derived quantities at load, before any pre_run_loader override
runs. A post-load raw-input override (dt, radius_scale, gain scalar) leaves its derived
quantities silently stale — the sim runs with the old baked value and no error fires.
(utils/INSIGHTS.md → parameter_loader [footgun])

Gain matrices are snapshotted — override the BUILT matrix, not the scalar

Gains are baked into controller.gains at load; a post-load raw gain override is inert. Either
override the built matrix cfg.controller.gains.base.K directly, or call build_controller_gains()
to rebuild. (utils/INSIGHTS.md; memory controller-gains-built-matrix-path)

camera_radius = radius_scale · r_reach is baked — a sweep on radius_scale was inert

A post-load radius_scale sweep silently did nothing (Jun 19) until rederive_camera_radius(params)
was called after the override. The three rederive_* helpers are the only escape from the trap:
each re-runs the owning derivation method (no formula duplication) and is idempotent at unchanged inputs.
(utils/INSIGHTS.md)

Convention: load + derive only; flags in apply_flags; preserve YAML order

Keep this file simple — complex logic belongs in active control/guidance code. Prefer explicit enable
gates over implicit arithmetic like alpha = dt / max(t_s, dt); all boolean/startup flags go in
apply_flags(). Don’t re-group parameters relative to YAML order — re-group in the YAML if needed.
(utils/INSIGHTS.md)

Pseudocode (load path)

load(overrides):
    params = parse parameters.yaml          # raw leaves only
    apply_overrides(params, overrides)      # nested in-place; raises on bad path
    finalize_parameters():
        attach robot + target asset blocks
        add_derived_parameters()            # orbit radius, gains, accel limits,
                                            #   guidance smoothing, camera FOV/reach  <-- BAKED HERE
        apply_flags()                       # effective startup steps, enable gates
    return params

# post-load raw override?  the bake is already done -> stale.
rederive_dt_dependent(params) / rederive_camera_radius(params)   # re-run the owning derivation

Related

robot · data_classes · breve_controller · com_guidance · ee_guidance · mesh · runner · terminology