Quartz 5

base_guidance

Properties2
tagsguidance
aliasesBaseGuidance

3 min read

base_guidance — BaseGuidance

Purpose

Adds the desired base attitude along the orbit to the CoM reference: a roll-continuous frame
sequence is built once offline, SLERPed at runtime, and blended toward inward-pointing
near a singularity. The middle layer of the deep guidance chain.

Role in the system

  • extends com_guidance (COMGuidance, the CoM-reference root) — inherits build_com_desired_for_step, smooth_desired_com_reference, orbit + progress tracking.
  • Extended by ee_guidance (EEGuidance layers EE pose selection, the POSE path, and GuidanceMode on top).
  • build_base_desired_for_step is called by breve_controller’s _build_base_desired_for_step once per control step; the returned Desired carries R_b/z_b/omega_b that the base attitude PD law (x_b_tilde, compute_tau_b_oplus) regulates.
  • The same s_min_G conditioning ramp drives both the speed derate here and the EE derate_twist_by_gamma in ee_guidance / analytic_feedforward (Option A — one ramp for all).

Inputs / Outputs

  • In: current CoM p_c, joint state (q, v), time t, the previous desired (des_prev); a robot handle (for dyn.s_min_G and the SVD ramp robot.sampling.scale_by_svd); config (guidance.base.window_size, guidance.base.omega_body_frame, controller.base.conditioning).
  • Out: a Desired with base attitude R_b (inward z_b, roll-continuous x-hint) and desired omega_b, derate-scaled CoM (v_c, a_c, omega_b), plus a guidance Package(s_min_G, z_bd).

Key methods

  • build_base_desired_for_step — per-step base+CoM desired: derate → smooth → sample attitude → conditioning blend — GNC/base_guidance.py:114
  • build_base_frame_references — offline roll-continuous frame field (inward z, parallel-transported x) — :176
  • interpolate_base_frame — runtime SLERP of the frame field at fractional progress — :191
  • sample_base_goal_on_interval — write R_b/z_b/omega_b onto the CoM desired — :219
  • base_frame_angular_velocity — desired omega_b from a central finite difference of the frame field — :244
  • derate_desired_by_gamma — speed-derate: v_c·γ, a_c·γ², omega_b·γ — :141
  • blend_base_goal_by_conditioning — blend the desired attitude toward inward as γ shrinks — :151
  • build_orbit_windows / window_bounds — partition the orbit into [i0, i1) windows and resolve bounds — :38 / :88

Footguns

omega_body_frame — BODY vs SPATIAL finite-difference increment

omega_bd is consumed in the body frame (differenced against Pinocchio’s LOCAL omega_b), so the
correct FD increment is log(R₋ᵀ R₊) (body). frame_ang_vel returns the spatial increment
log(R₊ R₋ᵀ), which is ≈90° misdirected — the B0 bug caused ≈90° heading error. The correct
branch is flag-gated: set guidance.base.omega_body_frame = True. (GNC/INSIGHTS.md [footgun][frame])

Speed-derate gates on the single Option-A conditioning flag

Mechanism B (speed-derate) now gates on controller.base.conditioning.enable (TASK_2/TASK_4),
matching every other conditioning path. The old controller.com.speed_derating.enable gate is now
inert config (both were true). (GNC/INSIGHTS.md [derate])

Conditioning collapsed onto s_min_G — not a separate s_min_J

blend_base_goal_by_conditioning once drove off a separate s_min_J / J⁺ path; it now reads the
same s_min_G ramp (per F4: Γ is singular iff J_ν_e is). Don’t reintroduce a second axis.
(GNC/INSIGHTS.md [guidance])

Pseudocode (one base-guidance step)

des_com = build_com_desired_for_step(t, p_c)         # inherited from COMGuidance (smooth=False)
if conditioning.enable:                              # Option-A γ ramp
    γ = scale_by_svd(dyn.s_min_G, base.conditioning.sigma)
    des_com = derate_desired_by_gamma(des_com, s_min_G)   # v_c·γ, a_c·γ², omega_b·γ
des_com = smooth_desired_com_reference(des_com, des_prev)
prog    = clip(current_progress, window.i0, window.i1)
R_hint  = interpolate_base_frame(frame_refs, prog)   # SLERP the offline frame field
des.R_b = frame_from_z_axis(-p̂_c, x_hint=R_hint[:,0])  # z strictly inward; borrow x for roll continuity
des.omega_b = base_frame_angular_velocity(...)       # central FD; body vs spatial per omega_body_frame
if conditioning.enable:
    des = blend_base_goal_by_conditioning(des, s_min_G)  # near-singular → blend attitude toward inward

Equations & references

Key equations mirrored from current_sota — the math source of truth; see there for derivations.

Runtime base-attitude SLERP — §5.3, eq (5.6):

Impedance-derate ramp — §6.3, eq (6.4):

References:

  • Base attitude reference (offline frame build + runtime SLERP, eq for R_bd(s) and α_bd): current_sota > 5 §5.3.
  • Singularity handling / conditioning ramp γ(s_min_G) (the derate stack): current_sota > 6 · eq↔code in generated_reports/GNC/cross_check.md.

com_guidance · ee_guidance · breve_controller · analytic_feedforward · base_controller · terminology · com_vs_base · speed_gain_derate

Graph View

Backlinks