This repository implements a modular simulation and control stack for a magnetically actuated spherical robot moving inside a 1 m cube. The mathematical source of truth is the local proof set in Mathematical-Proof/, with the newest authoritative solution files selected per problem:
- Problem statement:
Mathematical-Proof/magnetic-fields-problem.tex - Problem 1:
Mathematical-Proof/Answer-Keys/problem1_solution.tex - Problem 2:
Mathematical-Proof/Answer-Keys/problem2_solution_revised.tex - Problem 3:
Mathematical-Proof/Answer-Keys/problem3_solution_relocked.tex - Problem 4:
Mathematical-Proof/Answer-Keys/problem4_solution.tex - Problem 5:
Mathematical-Proof/Answer-Keys/problem5_solution_patched.tex
The implementation is organized around the proof-backed phase structure:
Phase 0: local proof-file scan, authority map, and docsPhase 1: RK4 translational dynamics with explicit contact handlingPhase 2: control-affine surrogate magnetic force model and hover feasibilityPhase 3: analytic and finite-difference linearization plus stabilizability checksPhase 4: two-layer regulation controller with allocation and local validationPhase 5: quinticC^2trajectory generation and tracking validationPhase 6: physical dipole-based field model, decay-limit analysis, and Earnshaw-style demosPhase 7: minimal dark-mode PySide6 desktop UI
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtRun the full validation suite:
python3 -m pytestFree-fall and backend sanity:
python scripts/run_hover_demo.py --mode freeStatic hover:
python scripts/run_hover_demo.py --mode hoverPoint-to-point transfer:
python scripts/run_transfer_demo.pyReachable-force and feasibility sampling:
python scripts/run_force_map.pyPhysical-limit demo:
python scripts/run_physical_limit_demo.pyDesktop UI:
python scripts/run_ui.pyThe Setup tab includes a Show 3D view toggle. Enable it to expose a 3D View tab beside the existing 2D projections. The preferred backend is pyqtgraph.opengl via PyOpenGL; if that backend cannot initialize, the UI falls back to a minimal VisPy scene. Controls are left drag to orbit, right drag to pan, and scroll to zoom.