Add central-force potential family with conservation certificates - #3
Open
xJoepec wants to merge 1 commit into
Open
Add central-force potential family with conservation certificates#3xJoepec wants to merge 1 commit into
xJoepec wants to merge 1 commit into
Conversation
Generalize the potential layer from the two hardcoded laws (Harmonic, Coulomb) into an extensible central-force family, without touching the integrator, the Landau-Lifshitz reduction, or the certificate discipline. Potentials (src/blueberry_circus/potentials.py): - CentralPotential base derives the Cartesian force and an analytic force_jacobian (needed by the RR term) from three radial functions U, U', U'' of the softened radius s = sqrt(r^2 + softening^2). - PowerLaw, Yukawa, Morse, AnharmonicOscillator (isotropic Duffing), LennardJones. PowerLaw reduces exactly to Harmonic (p=2) and Coulomb (p=-1), which the tests pin as reduction oracles. Declarative ops (src/blueberry_circus/program.py): - Matching Operations for each new law. Potential collection in compile() now keys on a _PotentialOp marker instead of a hardcoded (Harmonic, Coulomb) tuple, so new families are picked up automatically. Conservation certificates (src/blueberry_circus/conservation.py): - energy_conservation_certificate / angular_momentum_conservation_certificate encode fractional invariant drift against the canonical residual_le_tol rule; an under-resolved or tampered trajectory re-derives FAIL. This cross-checks that each new potential's analytic force is consistent with its potential energy, purely from the integrated dynamics. Tests (tests/test_central_potentials.py, 33 cases): finite-difference checks of force = -grad U and of the Jacobian, Jacobian symmetry, PowerLaw->Harmonic/Coulomb reductions, energy + |L| conservation on closed orbits (all families to <~1e-11), a tight-tolerance FAIL guard, RR stability, and declarative-program integration. Full suite: 167 passed, 2 expected xfails, no regressions. Also adds docs/central_forces.md and examples/central_forces.py.
xJoepec
force-pushed
the
feat/central-force-potentials
branch
from
August 22, 2026 20:49
657066b to
384b593
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Generalizes the potential layer from the two hardcoded binding laws
(
Harmonic,Coulomb) into an extensible central-force family, withouttouching the integrator, the Landau–Lifshitz radiation-reaction reduction, or
the certificate discipline. New laws are a few lines each and inherit an exact
analytic force Jacobian.
The design goal was to extend the library in its own idiom: analytic forces
with analytic Jacobians (as the RR term requires), reduction oracles against the
existing trusted code, and re-checkable PASS/FAIL certificates on the physics.
What's added
Potentials (
src/blueberry_circus/potentials.py)CentralPotentialbase: a subclass supplies only three radial functionsU(s),U'(s),U''(s)of the softened radiuss = √(r² + softening²); thebase derives the Cartesian
forceand an analyticforce_jacobianviaF = g(s) x,g = −U'/s,J = g I + (g'/s) x xᵀ.PowerLaw,Yukawa,Morse,AnharmonicOscillator(isotropic Duffing),LennardJones.PowerLawreduces exactly toHarmonic(p=2) andCoulomb(p=−1) — used as reduction oracles in the tests.Declarative ops (
src/blueberry_circus/program.py)Operations for each law (bc.PowerLaw,bc.Yukawa,bc.Morse,bc.Anharmonic,bc.LennardJones).Program.compile()now collects potentials by a_PotentialOpmarker insteadof a hardcoded
(Harmonic, Coulomb)tuple, so future potentials are picked upautomatically (the exhaustiveness pass keys on the same marker).
Conservation certificates (
src/blueberry_circus/conservation.py)energy_conservation_certificateandangular_momentum_conservation_certificateencode the fractional peak-to-peakdrift of the invariant against the canonical
residual_le_tolrule. Anunder-resolved integration or a tampered trajectory re-derives
FAIL. For acentral force,
|L|conservation is the signature of centrality, and energyconservation cross-checks that a new potential's analytic
forceis consistentwith its
potentialenergy — purely from the integrated dynamics.Docs & example:
docs/central_forces.md,examples/central_forces.py.Testing
tests/test_central_potentials.py(33 cases) pins correctness three independentways:
force== −∇U andforce_jacobian== dforce/dx;Jacobian symmetry (curl-free).
PowerLawreproducesHarmonicandCoulombtofloating-point closeness.
|L|certificates (allsix families to ≲10⁻¹¹ at
dt = 5·10⁻³), and a real driftFAILs animpossibly tight tolerance.
Plus radiation-reaction stability for the new families and declarative-program
integration through the
Engine.No changes to existing behavior:
Harmonic/Coulomband all prior certifiedresults are untouched (the
PowerLawreduction tests prove the generalization isconsistent with the trusted core).
Motivation
This is the enabling substrate for a general dynamics corpus in which
BlueberryCircus is the data-generating engine: continuous force-law families
(via
PowerLaw's exponent and the qualitatively distinct Yukawa/Morse/Duffing/LJwells) plus certified invariants give clean, re-checkable ground truth for
inverse-dynamics and law-inference tasks.