Repository navigation
Mathematics
Quick Scan
For: Educators incorporating math into curriculum, engineers understanding implementation, researchers verifying claims
Time to first insight: 5 minutes (pick any topic, read intuition section)
Prerequisites: Comfort with algebra; calculus helpful but not required
What you'll learn: How Compitum's mathematical components work and why they matter
Compitum makes routing decisions using techniques from Riemannian geometry, convex optimization, and control theory. This might sound intimidating. It's not.
Each mathematical component solves a specific, practical problem:
- SPD metrics: Measure distance in a way that respects semantic structure
- Constraints: Enforce non-negotiable boundaries (privacy, regional restrictions)
- Lyapunov stability: Prevent the system from oscillating or diverging during learning
- Shadow prices: Quantify the value of relaxing each constraint
- Coherence (KDE): Build confidence from past successful decisions
- Trust regions: Bound update sizes to prevent instability
- Calibration: Ensure uncertainty estimates are reliable
- Boundary detection: Identify ambiguous decisions where multiple models are viable
This hub page organizes these topics. Each links to a dedicated page with:
- Intuition (plain language, analogies, why it matters)
- Formal sketch (key equations, no full derivations)
- Compitum implementation (where to find it in code)
- Common pitfalls (what goes wrong and how to fix it)
- Further reading (canonical references)
The components form a decision pipeline:
graph TD
A[Query Embedding] --> B[SPD Metric]
B --> C[Distance to Models]
C --> D[Predict Quality/Latency/Cost]
D --> E[Compute Free Energy]
E --> F[Check Constraints]
F --> G[Select Feasible Model]
G --> H[Boundary Analysis]
H --> I{Update Metric?}
I -->|Yes| J[Trust Region Check]
J --> K[Lyapunov Controller]
K --> B
I -->|No| L[Emit Certificate]
style B fill:#e3f2fd
style F fill:#fce4ec
style H fill:#fff3e0
style K fill:#e8f5e9
Figure 1: Decision pipeline. Queries flow through metric computation, constraint checking, and optional learning updates governed by stability guarantees.
The key insight: These aren't independent techniques stacked together. They're mutually reinforcing:
- The SPD metric defines distances, which feed the trust region controller
- Constraints filter viable models before free energy optimization
- Coherence (past success patterns) adjusts utility, influencing boundary detection
- Lyapunov stability bounds metric updates, preventing divergence
This design mirrors how teachers structure learning environments: define the space (metric), set boundaries (constraints), ensure safe exploration (trust regions), build on past success (coherence).
Topics: SPD Metrics, Constraints and Shadow Prices
What you learn: How Compitum represents query similarity and enforces boundaries.
Why start here: You can't understand routing decisions without understanding the geometry they operate in and the rules they must follow.
Key pages:
Practical outcome: You'll understand why two queries might be "close" even when their text differs, and why certain models are immediately ruled out.
Topics: Lyapunov Stability, Trust Regions
What you learn: How Compitum updates its understanding without oscillating or diverging.
Why second: Once you know the space and rules, you need to understand how the system safely adapts over time.
Key pages:
Practical outcome: You'll understand why metric updates are bounded and what the "drift status" in certificates means.
Topics: Kernel Density Estimation, Calibration, Boundary Detection, EMA Control
What you learn: How Compitum builds confidence, quantifies uncertainty, and detects ambiguous cases.
Why last: These components refine the core decision-making established in Stages 1 and 2.
Key pages:
- Math-Kernel-Density-and-Coherence
- Math-Uncertainty-and-Calibration
- Math-Boundary-Gap-and-Entropy
- Math-EMA-and-Integral-Control
Practical outcome: You'll understand how the system knows when it's confident versus uncertain, and how it learns from patterns of success.
| Topic | Core Question | Code Location | Typical Pitfall |
|---|---|---|---|
| SPD Metrics | How do we measure semantic distance? | metric.py |
Choosing rank too high in high dimensions |
| Constraints | What's non-negotiable? | constraints.py |
Assuming shadow prices work with non-convex constraints |
| Lyapunov Stability | How do we prevent divergence? | control.py |
Mistaking transient oscillation for instability |
| Shadow Prices | What's the cost of each constraint? | constraints.py |
Interpreting shadows when multiple constraints bind |
| Coherence (KDE) | Have we succeeded here before? | coherence.py |
Bandwidth too narrow (overfitting) or too wide (oversmoothing) |
| Trust Regions | How big a step is safe? | control.py |
Radius too tight (slow learning) or too loose (instability) |
| Calibration | Are our uncertainties reliable? | predictors.py |
Calibrating once then forgetting distribution shift |
| Boundary Detection | Is this decision ambiguous? | boundary.py |
Temperature scaling that artificially sharpens entropy |
| EMA Control | How do we smooth noisy signals? | control.py |
Integral windup from persistent bias |
Each mathematical concept has pedagogical parallels you already use:
SPD Metrics → Concept mapping where connections matter more than raw features
Constraints → Non-negotiable classroom rules that enable freedom within structure
Lyapunov Stability → Ensuring group discussions converge rather than spiral
Shadow Prices → Understanding the cost of relaxing a rule ("what if we extended the deadline?")
Coherence → Building on past successful lesson structures
Trust Regions → Not changing too much at once when iterating curriculum
Calibration → Being honest about what we know vs. what we're guessing
Boundary Detection → Recognizing when students are genuinely confused vs. making careless errors
For concrete teaching activities using these concepts, see Educators#Classroom Applications.
Where to start: Clone the repo, run python examples/synth_bench.py to see SPD metrics in action on synthetic clusters.
Key files:
-
src/compitum/metric.py- Riemannian distance computation and online learning -
src/compitum/constraints.py- Feasibility checking and shadow price approximation -
src/compitum/control.py- Lyapunov-based trust region controller -
src/compitum/coherence.py- Kernel density estimation for evidence -
src/compitum/boundary.py- Gap and entropy-based ambiguity detection -
src/compitum/predictors.py- Calibrated uncertainty quantification
Testing: Each component has unit tests. Run pytest tests/test_metric.py to verify SPD properties.
Ablations: Use CLI flags --no-metric-update and --no-controller to disable components and measure their contribution.
For step-by-step setup, see Getting Started.
Compitum builds on established theory:
Riemannian optimization: Absil et al. (2008), Optimization Algorithms on Matrix Manifolds
Convex constraints: Boyd & Vandenberghe (2004), Convex Optimization
Lyapunov stability: Khalil (2002), Nonlinear Systems
Shadow prices: Rockafellar (1970), Convex Analysis
Kernel methods: Scott (2015), Multivariate Density Estimation
Trust regions: Nocedal & Wright (2006), Numerical Optimization
Calibration: Gneiting & Raftery (2007), "Strictly Proper Scoring Rules"
Our contribution is not inventing these techniques but integrating them into a coherent system with closed-loop learning guarantees.
Key theoretical results:
- Metric updates decrease a Lyapunov function (proven convergence under bounded observer assumptions)
- Trust region controller prevents unbounded drift (proof sketch in control.py docstrings)
- Constraint solver finds optimal feasible model or reports infeasibility with violation details
For full proofs and ablation studies, see our technical reports in docs/theory/.
Q: Do I need to understand all the math to use Compitum?
A: No. The system works out of the box. This section exists for those who want to understand why it works or need to debug unusual behavior.
Q: Which topic should I read first?
A: Start with Math-SPD-Metrics-and-Riemannian-Geometry. Everything else builds on understanding that distance isn't Euclidean.
Q: Can I skip the formal sections?
A: Yes. Read intuition and Compitum implementation. Return to formal sections only when you need deeper understanding.
Q: Why no full derivations?
A: This is a practitioner's reference, not a textbook. We cite canonical sources for complete treatments. Our focus is showing how theory connects to implementation.
Q: What if I find an error?
A: Open an issue on GitHub. Mathematical rigor requires community scrutiny.
Not a tutorial: We don't teach Riemannian geometry from scratch. We explain how Compitum uses it.
Not a textbook: We don't prove every theorem. We cite proofs and sketch key results.
Not implementation documentation: For API details, see API Reference. This section explains mathematical design choices.
Not optional reading for contributors: If you're modifying core algorithms, you need to understand the mathematical guarantees you might be breaking.
If you're new: Start with Math-SPD-Metrics-and-Riemannian-Geometry, then work through Stage 1.
If you're debugging: Check the pitfall column in the reference table, then read the relevant topic page.
If you're researching: Read all topic pages in sequence, then dive into docs/theory/ for proofs.
If you're teaching: See Educators#Control of Error in Practice for connections between these mathematical concepts and pedagogical principles.
- Educators - How mathematical concepts map to teaching practice
- Getting Started - Set up Compitum and run examples
- Examples - Working code demonstrating each component
- Philosophy - Why we chose these mathematical tools
- Glossary - Quick definitions of technical terms
- API Reference - Function signatures and parameters
We use standard notation where possible:
- Vectors: lowercase bold (x, y)
- Matrices: uppercase bold (M, A)
- Scalars: lowercase italic (α, β)
- Sets: uppercase script (𝒳, 𝒴)
When notation conflicts with code (e.g., beta_d in code vs. βd in math), we note it explicitly.
Code comments include equation references when implementing formulas, making it easy to trace between math and implementation.
This section formalizes what educators already know works. The mathematics proves it. The code implements it. The certificates demonstrate it.