Quartz 5

sampling

Properties2
tagsutils
aliasesSampling

3 min read

sampling — joint-config sampler + the single γ derate ramp

Purpose

Two jobs in one small class: (1) a startup joint-config sampler that ranks random arm
configurations by Jacobian conditioning (σ_min), and (2) scale_by_svd — the single piecewise-linear
γ ramp that maps σ_min → [floor, 1] and that every derate mechanism in the controller consumes.

Role in the system

  • Owned by robot (GiordanoRobot.__init__ builds self.sampling = Sampling(cfg), utils/robot.py:44).
    Everything reaches it as self.robot.sampling.*.
  • Conditioning readout (per step): sigma_min_and_cond is called from robot on both the damped
    J⊕ and Γ to log s_min_J/κ_J and s_min_G/κ_G (utils/robot.py:283,295).
  • The γ ramp: scale_by_svd(s_min_G, …) is the one ramp behind every derate. The controllers wrap it
    as conditioning_scale (breve_controller :309, base_controller :122) and base_guidance
    calls it directly (:144,154). See current_sota > 6 §6.3.
  • Startup q-init: best_sample feeds the random-search initial configuration in robot (:414),
    a fallback to the analytic _deterministic_q_init.

Inputs / Outputs

  • In: the full config (config_sampling block: seed, default.{step_size,num}, the low/high/floor
    ramp knobs), a nominal q_bar, and a scoring func (a Jacobian-producing closure).
  • Out: ranked sample dicts (sample, q_joint, q_full, sigma_min); (σ_min, κ) scalars; and the
    scalar derate γ ∈ [floor, 1].

Key functions & methods

  • sigma_min — smallest singular value of A, or None if non-finite — module-level utils/sampling.py:10
  • sigma_min_and_cond — (σ_min, κ=σ_max/σ_min) from one SVD pass — module-level utils/sampling.py:16

    Both promoted out of Sampling to module level 2026-06-22 (pure SVD utilities, no class state); robot.py
    calls the functions directly. All 5 baselines max_abs_diff = 0.000e+00. (logs/logs_Jun22_26/CLAIMS.md C8)

  • generate_samples — uniform random arm configs within ±step_size of q_bar — utils/sampling.py:41
  • sorted_samples / best_sample — score by σ_min(func(q)), sort ascending / take the top — utils/sampling.py:56,71
  • scale_by_svd — the single piecewise-linear γ derate ramp — utils/sampling.py:75

Footguns

config_sampling, not conditioning — a deliberate rename

The sampler’s config block was renamed from top-level conditioning because it name-collided with
controller.base.conditioning, the runtime derating block. They are different things. (utils/INSIGHTS.md [history])

Use the one-pass conditioning call when you need κ

sigma_min_and_cond returns both σ_min and κ from a single SVD; call it instead of sigma_min when the
condition number is also wanted, to avoid a redundant decomposition. (utils/INSIGHTS.md [footgun])

Pseudocode (the γ ramp)

scale_by_svd(σ, opts):           # opts = {low, high, floor}
    if σ <= low:  return floor   # near-singular → softest (emergent slowdown)
    if σ >= high: return 1.0     # well-conditioned → full authority
    return floor + (1 - floor) * (σ - low) / (high - low)   # linear blend

Equations & references

  • Impedance / derate stack (§6.3, the emergent-slowdown ramp): current_sota > 6. The γ value drives
    K/D and base-wrench scaling in the controller; eq↔code in generated_reports/GNC/cross_check.md.

robot · breve_controller · base_controller · base_guidance · terminology

Graph View

Backlinks