Glossary

# Glossary: Key Terms in Compitum's Bounded Optimization

**Quick-Scan Infobox**

| Aspect | Details |

|--------|---------|

| **Target User** | Educators, developers, and newcomers decoding certs/traces; no prior RL/geometry req'd. |

| **Core Goal** | Demystify jargon—from metrics to signals—for confident routing and extension. |

| **Time to Lookup** | <2 mins: Search term, scan def + analogy. |

| **Key Analogy** | Like a class vocab list: Each term a building block—stack 'em to construct quadratic insights. |

| **Scope** | Covers v1.0 core; evolves with Roadmap (e.g., Thompson priors incoming). |

## Core Principles Layer (Technical Backbone)

Compitum's lexicon roots in constrained optimization and Riemannian geometry: Terms describe the machinery of bounded observers querying quadratic spaces, yielding auditable certificates. Definitions are precise, with math ties for rigor—e.g., free energy as the variational bound \( E \approx -\log Z \), minimized over feasible sets.

- **SPD Metric**: Symmetric Positive Definite matrix \( M \succ 0 \), inducing Mahalanobis distances \( d(x,y) = \sqrt{(x-y)^T M (x-y)} \) on embeddings. Low-rank approx (rank \( r \ll D \)) via eigendecomp \( M = U \Lambda U^T \); learned in metric.py for manifold-aware routing.

- **Trust Region**: Bounded ball \( \|\Delta \theta\| \leq r_t \) around current params \( \theta_t \), enforced by SRMF controller to guarantee descent: \( E(\theta_{t+1}) \leq E(\theta_t) + g^T \Delta \theta + \frac{1}{2} \Delta \theta^T H \Delta \theta \). Radius adapts via EMA of Cauchy steps.

- **Coherence (KDE)**: Kernel Density Estimate log-evidence \( \log p(\mathbf{x} | \hat{p}) = \sum \log \hat{p}(x_i) \), where \( \hat{p} \) is KDE on trace neighborhoods—measures local consistency (high if traces cluster). Threshold > -2 flags "coherent paths."

- **Shadow Price**: Dual variable \( \lambda_i = \frac{\partial U^*}{\partial b_i} \) in LP/QP optima, quantifying utility gain from relaxing constraint i by 1 unit (e.g., cost cap). Computed via finite diffs or KKT conditions in constraints.py.

- **Boundary**: Region where top utilities satisfy \( |U_1 - U_2| < \delta \) (gap) or softmax entropy \( H > \log 2 \) (uncertainty)—triggers diagnostics like Thompson exploration. Flags ambiguity in selection.

- **Free Energy**: Surrogate objective \( E = \alpha q - \beta_t l - \beta_c c - \beta_d d - \beta_s (-\log p) \), variational upper bound on negative log-evidence; minimized for routing (low E = good). Weights from Configuration.

- **Process Reward**: Intrinsic, step-wise signal (e.g., \( r_t = -\Delta E_t - \sum \max(0, -s_i) \))—mechanistic proxy for policy gradients, auditable without judges. Guides local updates via \( \theta \leftarrow \theta + \eta r_t \nabla \log \pi \).

*Why this vocab?* Anchors the quadratic loop: Metrics define space, regions bound motion, signals query progress—emergent from constraints.

Math Dive: Free Energy Decomposition (Collapsible for Tinkerers)

\[

E(\mathbf{x}) = \underbrace{\alpha \cdot q(\mathbf{x})}_{\text{quality}} - \underbrace{\beta_t \cdot l(\mathbf{x})}_{\text{latency}} - \underbrace{\beta_c \cdot c(\mathbf{x})}_{\text{cost}} - \underbrace{\beta_d \cdot d(\mathbf{x}, \mu)}_{\text{distance to prior}} - \underbrace{\beta_s \cdot (-\log p(\mathbf{x} | \text{KDE}))}_{\text{coherence evidence}}

\]

Subject to \( A \mathbf{x} \leq \mathbf{b} \); shadows \( \lambda \) emerge at optima.

Open on GitHub | Open in nbviewer | Launch in Binder

Snippet from Glossary.md

# Snippet: Compute Sample Free Energy
# U = alpha*quality - beta_t*latency - beta_c*(cost+model.cost) - beta_d*distance + beta_s*evidence
# (see docs/Certificate-Schema.md for the certificate's utility_components field)

components = {"quality": 0.8, "latency": 0.2, "cost": 0.1, "distance": 0.15, "evidence": -0.05}
weights = {"alpha": 0.4, "beta_t": 0.2, "beta_c": 0.15, "beta_d": 0.15, "beta_s": 0.1}

E = (
    weights["alpha"] * components["quality"]
    - weights["beta_t"] * components["latency"]
    - weights["beta_c"] * components["cost"]
    - weights["beta_d"] * components["distance"]
    + weights["beta_s"] * components["evidence"]
)

print(f"E: {E:.3f}")  # Negative ideal; ties to shadow sensitivity.

*Pro Tip:* High \( \beta_s E_s \) in traces? Boost KDE bandwidth for looser neighborhoods.

## Approachable Layer (Relatable Hooks for Educators)

These terms are your "shortcut keys" for Compitum convos: SPD metric? That's the "custom ruler" measuring idea closeness, not Euclidean straight-lines. For teachers, they're metaphors made math—shadow prices as "what if we bend the rules?" in a debate, free energy the "total vibe score" balancing depth vs. drag.

- **Classroom Tie-In**: Teach boundaries via group votes: Small gaps/high entropy? Reroute to subgroups—turns vocab into a facilitation tool.

- **Analogy Echo**: Process rewards as mid-lesson check-ins: Quick thumbs-up (low drift) keeps momentum, no waiting for the bell.

- **Common Hurdle**: Terms blur? Pair with cert JSON—e.g., spot "shadow_prices: [0.3]" as a nudge to tweak configs.

## Quick-Reference Toolkit (Term Breakdown)

| Term | TL;DR | Math Tie | Classroom Use | See Also |

|------|--------|----------|---------------|----------|

| **SPD Metric** | Curved ruler for embeddings. | \( d = \sqrt{(x-y)^T M (x-y)} \), \( M \succ 0 \). | Measure "idea distance" in student mindmaps. | Configuration metric.D. |

| **Trust Region** | Safety bubble for updates. | \( \|\Delta\| \leq r_t \); SRMF adapt. | Limit group drift in collabs—stay on-topic. | Design-Notes stability. |

| **Coherence (KDE)** | Neighborhood consistency score. | \( \log p(\mathbf{x} | \hat{p}_{\text{KDE}}) \). | Check if class themes align—spot outliers. | Output-Format evidence. |

| **Shadow Price** | Gain from rule tweaks. | \( \lambda_i = \partial U^* / \partial b_i \). | "What if longer recess?"—budget impacts. | Constraints examples. |

| **Boundary** | Tie/ambiguity zone. | Gap < δ or H > log(2). | Debate deadlocks—probe for clarity. | Boundary diagnostics. |

| **Free Energy** | Overall goodness scalar. | \( E = \alpha q - \sum \beta c \). | Lesson balance: Fun vs. time/effort. | Energy components. |

| **Process Reward** | Step-by-step nudge. | \( r_t = -\Delta E - \sum \max(0, -s) \). | Instant feedback loops—no end-game waits. | FAQ instantaneous. |

Gotchas Table (Collapsible: Term Mix-Ups)

| Term | Common Confusion | Clarify | Analogy |

|------|------------------|---------|---------|

| **SPD vs. Euclidean** | Thinks flat distances. | SPD warps for task fit. | City grid vs. bird's-eye—routes differ. |

| **Shadow vs. Slack** | Utility vs. feasibility. | Shadow: Why loosen? Slack: How much room? | Cost of overtime vs. hours left. |

| **Boundary vs. Constraint** | Ambiguity vs. hard stop. | Boundary: Fuzzy edge; constraint: Wall. | Gray area vs. off-limits zone. |

| **Free Energy vs. Utility** | Total vs. raw quality. | E penalizes costs; U just upsides. | Net profit vs. sales—deduct overhead. |

## Next Steps: Your Loop

- **Term Hunt**: Route a prompt, grep cert for "shadow"—decode its price?

- **Quiz It**: Flashcard these in Cookbook scripts; test recall on signals.

- **Expand**: Spot a gap? PR to this MD with your def + analogy.

See also: Philosophy for conceptual weaves; API-Reference for term'd functions; Verification for signal thresholds.