breve_core_controller

breve_core_controller — BreveCoreController (shared base-attitude/breve methods)

Purpose

The shared intermediate controller base that holds the methods base_controller and
breve_controller used to carry as byte-identical copies. The EE/arm leaves these methods call
are overridden per-subclass (Template Method), so one shared template yields both the base-only
diagnostic path and the full coordinated path. Extracted 2026-06-22 from a clone-detector finding,
proven byte-identical (all 5 baselines max_abs_diff = 0.000e+00).

Role in the system

• extends com_controller (CC_Controller, the per-step control loop + Γᵀ force map).
• Parent of base_controller (BaseController, base-only diagnostic) and breve_controller
  (BreveController, the live workhorse) — the chain is now CC_Controller → BreveCoreController → {Base, Breve}.
• Not selected by controller.name and never instantiated alone — it has no __init__; both subclasses’
  constructors set self.g, self.traj, dynamics, etc. before any shared method runs.
• Dynamics (Γ, M̆, C̆, s_min_G) come from utils/robot.py as self.dyn.*.

Inputs / Outputs

• In: State (q, v, dynamics cache), base Desired (CoM + base attitude), config gains, s_min_G.
• Out: base reduced torque τ_b⊕, the stacked task error/Jacobian (x̃, J_x), and the reduced
  step-integration derivatives (omega_b_dot, nu_e_oplus_dot). The EE/arm specifics are delegated to the
  subclass leaves (zero in base_controller, full in breve_controller).

Key methods

• compute_tau_b_oplus — base attitude PD torque, derate-scaled + saturated — GNC/breve_core_controller.py:84
• all_control_terms — chains super()’s CoM terms + the breve step-integration derivatives — :97
• _apply_step_state_update — integrate (omega_b, nu_e_oplus) one step with saturation (chains super()) — :108
• conditioning_scale — the single γ ramp on s_min_G (Option A) — :80
• x_b_tilde / J_xb / x_b_tilde_dot — base attitude error, its Jacobian, its rate — :51 / :62 / :57
• x_tilde / J_x — stacked [base; EE] task error & 9×9 Jacobian (call the per-subclass x_e_rhs / J_xe leaves) — :68 / :72
• v_breve_damping_error — stacked [omega_b_err; nu_e_err] (calls the per-subclass damping leaves) — :76
• build_desired_for_step / _build_base_desired_for_step — base reference builder (the base path; breve_controller overrides build_desired_for_step to add the EE goal) — :43 / :38
• _loop_sync_uses_update_views — returns False (vs CC_Controller’s True) for both subclasses — :34

Footguns

Editing here changes BOTH controllers — verify against all 5 baselines

Every method here is shared by base_controller and breve_controller. The 13 methods were moved
verbatim; validate_base_baseline.py + the four validate_ee_* reproduce at max_abs_diff = 0.000e+00
(checked, not re-pinned — per GNC hard rules). Any logic change is a behaviour change to the whole
control chain. (generated_reports/GNC/controller_twin_extraction.md)

The EE/arm leaves are deliberately NOT defined here (Template Method)

x_e_rhs, J_xe, omega_b_damping_error, nu_e_damping_error, arm_breve_gains, rhs_feedforward,
v_breve_dot, RHS34b, calc_posture, reconstruct_generalized_velocity are the forks — each
subclass supplies its own (zeroed in Base, full in Breve). The shared methods call them via self.*, so a
shared method’s behaviour IS the subclass’s. Do not add a default leaf here without checking both paths.

Never instantiated alone — no __init__

BreveCoreController relies on the subclass __init__ having set self.g (gains), self.traj
(guidance), and the dynamics cache. Constructing it directly would AttributeError the moment
compute_tau_b_oplus reads self.g.base.K.

_loop_sync_uses_update_views = False is effectively inert in the loop

Both subclasses override CC_Controller’s True to False, but _sync_loop_state ignores the flag in
the loop (it always refreshes dynamics + breve views). Kept here to preserve intent, not for a live effect.

Pseudocode (the shared template, one base-path step)

build_desired_for_step(t) → _build_base_desired_for_step(t)   # base ref; Breve overrides to add the EE goal
τ_b⊕  = compute_tau_b_oplus(des)              # attitude PD, γ-scaled, saturated
x̃     = x_tilde(des) = [x_b_tilde ; x_e_rhs]  # x_e_rhs LEAF → 0 (Base) / full EE (Breve)
J_x   = block9(J_xb, J_xe)                     # J_xe   LEAF → 0 (Base) / full   (Breve)
all_control_terms: super().CoM terms ; v̆_dot = v_breve_dot(st, des)   # v_breve_dot LEAF (per-subclass)
                   step.omega_b_dot, step.nu_e_oplus_dot ← saturate(v̆_dot)
_apply_step_state_update: super() ; integrate (omega_b, nu_e_oplus) with saturation

Equations & references

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

Compact base+EE control law (the shared all_control_terms form) — §4.2, eq (4.7):

$$\left[\begin{array}{c}{\mathbf{\tau }}_b^{\oplus }\\ {\mathbf{w}}_e^{\oplus }\end{array}\right]=-{\mathbf{J}}_{\tilde{x}}^T\breve{\mathbf{K}}\tilde{\mathbf{x}}-\breve{\mathbf{D}}\breve{\mathbf{v}},\breve{\mathbf{K}}=\mathrm{blkdiag}({\mathbf{K}}_b,{\mathbf{K}}_e),\breve{\mathbf{D}}=\mathrm{blkdiag}({\mathbf{D}}_b,{\mathbf{D}}_e)$$

Impedance-derate ramp $\gamma ({\sigma }_G)$ (conditioning_scale) — §6.3, eq (6.4):

$$\gamma ({\sigma }_G)=\{\begin{array}{ll}{\sigma }_{\mathrm{crit},1}& {\sigma }_G\le {\sigma }_{\mathrm{crit},2},\\ 1& {\sigma }_G\ge {\sigma }_{\mathrm{crit},1},\\ {\sigma }_{\mathrm{crit},1}+(1-{\sigma }_{\mathrm{crit},1})\frac{{\sigma }_G-{\sigma }_{\mathrm{crit},2}}{{\sigma }_{\mathrm{crit},1}-{\sigma }_{\mathrm{crit},2}}& \text{otherwise.}\end{array}$$

References:

• Coordinated control + working eq (§4.4–4.12): current_sota > 4.
• Singularity / derate stack (§6): current_sota > 6 · eq↔code in generated_reports/GNC/cross_check.md.
• Extraction rationale + byte-identity proof: generated_reports/GNC/controller_twin_extraction.md.

Related

com_controller · base_controller · breve_controller · terminology · current_sota · circumcentroidal_control · speed_gain_derate