parameters

parameters — master run-spec config

Purpose

Single-file run specification for the nominal GRO inspection mission: simulation timing,
constraints, controller gains, the derate/conditioning stack, guidance, camera targeting, and
the uncertainty risk master switch. Every adopted knob from CHAIN_3 through CHAIN_13 lives here.
The why for each line (adoption/rejection verdicts, byte-identity contracts) is in
YAMLs_by_domain/INSIGHTS.md; this file stays terse (a key keeps only its unit/label).

Conventions (file-wide)

• MKS units; angles in degrees. Keys use enable (not enabled) and suffix _max (not max_).
• Reserved Greek names — do not reuse as generic config: tau = control input, delta = consecutive
  time-series change, alpha = interpolation factor, omega = angular velocity. (INSIGHTS.md [convention])

Structure (top-level blocks)

• simulation — duration/dt, EPS, target (GRO), robot (UR3 | UR3_7, named in assets.yaml).
• constraints — CoM / base / arm caps (theoretical, not hardware) + arm joint_limits.enforce.
• controller — com / base / arm sub-loops: gains, integral, startup, derate, conditioning, FF.
• config_sampling — the startup q0 sampler (deterministic seed OR random search); NOT the runtime derate.
• guidance — CoM orbit + tracking gains; base attitude (omega_body_frame).
• camera_guidance — targeting (reach, reselect, camera FOV/depth, scoring weights) + trajectory (orbit-synced path).
• uncertainty — risk-phase master switch + three noise channels (all 0.0 by default).

Key knobs/sections

key path	what it controls	default/example	note
simulation.time.duration	mission length (s)	1100	CHAIN_5: GRO orbit completes ~1064.5 s
simulation.robot	robot block in assets.yaml	UR3	UR3_7 = 7-DOF S-R-S variant
constraints.arm.joint_limits.enforce	clip arm joints to engineered envelope each step	true	CHAIN_5; breaks elbow singularity lock-in. pan exempt (winding)
controller.base.gains.K / .D	base attitude stiffness/damping (SHARED base+EE breve)	2.0 / 2.0	built into a matrix at load (see Footguns)
controller.base.conditioning.enable	the live singularity-derate gate	true	drives the single γ ramp (base_guidance.py)
controller.base.conditioning.sigma	γ ramp {low,high,floor} on s_min_G	0.005 / 0.025 / 0.25	re-fit to this robot’s distribution (median ~0.032)
controller.base.derate.gain	scale base K/D by γ in RHS34b	false	OFF = BYTE-IDENTICAL (only arm block γ-scaled)
controller.base.coupling_full_damping	Lever G: un-derated damping in CoM-coupling FF	false	false = BYTE-IDENTICAL
controller.arm.gains	EE position/orientation K/D/I	pos K [2,2,4], ori K 1.0	built matrix at load
controller.arm.integral.enable	EE pose-error integral	false	confirmed OFF: can’t null a velocity lag
controller.arm.desired_twist.enable / .v_max	EE velocity feedforward (ESSENTIAL) + cap	true / 0.9	OFF = +287% p_e; cap bites at speed 0.90
controller.arm.desired_twist.velocity_ff	L1: -C(v-v_des) exact zero-lag equilibrium	false	inert on real mission (CHAIN_13); BYTE-IDENTICAL
controller.arm.desired_twist.analytic_ff	closed-form vs FD desired twist (its_tex §3.4)	false	OFF = BYTE-IDENTICAL; real win w/ bounded tradeoff
controller.arm.derate.gain / .speed	γ scales arm K/D (gain) vs EE twist nu_e (speed)	true / false	endorsed = gain; speed collapses cruise-lag floor
controller.arm.null_space.enable / .freeze_floor	7-DOF v_n=0 fiber + kernel freeze	false / 0.025	no-op for 6-DOF; floor mirrors scoreboard 0.025
controller.arm.q0_eps	deterministic plant q0 perturbation [rad]	0.0	0.0 = BYTE-IDENTICAL; chaos-vs-ill-conditioning probe
config_sampling.deterministic.enable / .target_sigma	RNG-free off-neutral q0 seed	true / 0.05	ADOPTED Jun18; `sigma_min ≈ 0.107·
guidance.com.tracking.desired_speed	orbit traversal speed (m/s)	0.90	TASK_6 knee; ~2.6× faster than 0.35
guidance.base.omega_body_frame	desired ω in body frame log(R⁻ᵀR⁺)	true	B3 fix ADOPTED Jun19; z_b RMS −92%
camera_guidance.targeting.startup.time	INITIAL-aim window (s)	90.0	TASK_10: 15 s regressed coverage to 0.78
camera_guidance.targeting.scoring.mode	exponential = prod(score_k**w_k)	exponential	TASK_7; weights now live exponents
camera_guidance.targeting.scoring.sampling.radius_scale	standoff = rs · r_reach	0.40	CHAIN_13 re-pin (p_e_p99 optimum); rs 0.30 noise-fragile
camera_guidance.trajectory.orbit_path.mode	pose (path drives camera) vs anchor	pose	CHAIN_12 retired the reactive flow
camera_guidance.trajectory.orbit_path.progress_sync	aim clock from ACHIEVED orbit progress	true	CHAIN_3 pivot that unlocked coverage
uncertainty.enable	risk-phase master switch	false	false = strict BYTE-IDENTICAL (no RNG, no new keys)

For the exhaustive leaf list, read YAMLs_by_domain/parameters.yaml itself; the rationale per key is in YAMLs_by_domain/INSIGHTS.md.

Who reads it

• parameter_loader — loads into a RecursiveNamespace, derives all computed quantities at load
  (finalize_parameters, build_controller_gains, camera_radius), exposes the rederive_* escapes.
• pre_run_loader — merges with default_run_specs.yaml, applies ordered config overrides, and
  re-derives via the three snapshot-trap guards (gain / dt / camera prefixes). Resolves the
  metric_catalog and scoreboard specs from the sibling metrics.yaml / scoreboard.yaml.
• sampling / robot — consume config_sampling (startup q0 seed, damped-inverse floors).
• breve_controller / base_guidance — consume the controller/derate blocks at runtime.
• uncertainty_model — gated by uncertainty.enable; injects the three noise channels.
• logger / data_analyzer — config scalars are NOT logged; derived quantities are rebuilt
  from cfg at analysis time, so the run-spec YAML is the durable record of a run’s knobs.

Footguns

The snapshot trap — derived quantities bake at LOAD, before any override

parameter_loader.finalize_parameters() bakes all derived quantities at load time, BEFORE any
pre_run_loader override runs. A post-load raw-input override leaves derived quantities SILENTLY STALE:

• Gains are snapshotted into controller.gains (matrix form); a post-load controller.base.gains.K = x
  is inert against the stale controller.gains.base.K matrix — call build_controller_gains().
• dt (simulation.time.dt) feeds EE-goal alphas / startup steps / CoM blend — a dt/2 sweep steers by
  default-dt references without rederive_dt_dependent(cfg) (a convergence-test confound).
• camera_radius = radius_scale · r_reach — an rs sweep ran silently at the default 0.40 instead of
  0.35 before the guard; call rederive_camera_radius(cfg). (utils/INSIGHTS.md [footgun]; analysis/INSIGHTS.md snapshot-trap)

Two blocks named "conditioning" — disjoint consumers

config_sampling is the startup q0 sampler (robot.sampling / robot.damped_inverse); it was renamed
FROM a top-level conditioning block because it name-collided with the runtime derate block
controller.base.conditioning (editing one silently moved the other). The latter is the live derate gate.
(YAMLs_by_domain/USER_README.md; utils/INSIGHTS.md [history])

Legacy/dormant flags that look live but are inert

controller.com.speed_derating.enable is INERT — the live derate gate is controller.base.conditioning.enable.
camera_guidance.trajectory.goal.quintic (G1 v3 shelved; quintic_pose.py purged 2026-06-25) and
...orbit_path.detours (CHAIN_3 CANCELLED; detour_planner.py purged 2026-06-25) are dormant remnants —
the YAML flags now have no backing code at all. aim_floor_rate /
aim_lead_max are falsified-but-retained levers. (YAMLs_by_domain/INSIGHTS.md [history])

Metrics vs scoreboard live next door, with a shared floor

The catalog (metrics.yaml, what is measured) and the judgment layer (scoreboard.yaml, how it is judged)
are SEPARATE concerns parsed by separate loaders. The 0.025 floor appears in three places —
controller.arm.null_space.freeze_floor, the scoreboard s_min_J threshold, and the derate_fraction
metric — and must be kept in sync when the controller floor is tuned. (analysis/INSIGHTS.md [config])

BYTE-IDENTICAL contracts you must preserve

Several flags are pinned OFF as strict no-ops (uncertainty.enable, *.derate.gain, coupling_full_damping,
q0_eps=0.0, velocity_ff, analytic_ff, detours.enable). Flipping any of these re-pins the five baselines

• gold standard; uncertainty.enable=false in particular guarantees no RNG construction-order effects.
  anchor_length = 0.50058 has unknown provenance — treat as a legacy constant until re-derived.

Related

parameter_loader · pre_run_loader · metric_catalog · sampling · robot ·
breve_controller · base_guidance · uncertainty_model · logger · data_analyzer · terminology