Skip to content

Add central-force potential family with conservation certificates - #3

Open
xJoepec wants to merge 1 commit into
NanarchTech:mainfrom
xJoepec:feat/central-force-potentials
Open

Add central-force potential family with conservation certificates#3
xJoepec wants to merge 1 commit into
NanarchTech:mainfrom
xJoepec:feat/central-force-potentials

Conversation

@xJoepec

@xJoepec xJoepec commented Aug 22, 2026

Copy link
Copy Markdown
Contributor

Summary

Generalizes the potential layer from the two hardcoded binding laws
(Harmonic, Coulomb) into an extensible central-force family, without
touching 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)

  • CentralPotential base: a subclass supplies only three radial functions
    U(s), U'(s), U''(s) of the softened radius s = √(r² + softening²); the
    base derives the Cartesian force and an analytic force_jacobian via
    F = g(s) x, g = −U'/s, J = g I + (g'/s) x xᵀ.
  • PowerLaw, Yukawa, Morse, AnharmonicOscillator (isotropic Duffing),
    LennardJones. PowerLaw reduces exactly to Harmonic (p=2) and
    Coulomb (p=−1) — used as reduction oracles in the tests.

Declarative ops (src/blueberry_circus/program.py)

  • Matching Operations for each law (bc.PowerLaw, bc.Yukawa, bc.Morse,
    bc.Anharmonic, bc.LennardJones).
  • Program.compile() now collects potentials by a _PotentialOp marker instead
    of a hardcoded (Harmonic, Coulomb) tuple, so future potentials are picked up
    automatically (the exhaustiveness pass keys on the same marker).

Conservation certificates (src/blueberry_circus/conservation.py)

  • energy_conservation_certificate and
    angular_momentum_conservation_certificate encode the fractional peak-to-peak
    drift of the invariant against the canonical residual_le_tol rule. An
    under-resolved integration or a tampered trajectory re-derives FAIL. For a
    central force, |L| conservation is the signature of centrality, and energy
    conservation cross-checks that a new potential's analytic force is consistent
    with its potential energy — 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 independent
ways:

  1. Finite differences — analytic force == −∇U and force_jacobian == dforce/dx;
    Jacobian symmetry (curl-free).
  2. Reduction oraclesPowerLaw reproduces Harmonic and Coulomb to
    floating-point closeness.
  3. Conservation — closed orbits pass the energy and |L| certificates (all
    six families to ≲10⁻¹¹ at dt = 5·10⁻³), and a real drift FAILs an
    impossibly tight tolerance.

Plus radiation-reaction stability for the new families and declarative-program
integration through the Engine.

$ pytest -q
167 passed, 2 xfailed

No changes to existing behavior: Harmonic/Coulomb and all prior certified
results are untouched (the PowerLaw reduction tests prove the generalization is
consistent 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/LJ
wells) plus certified invariants give clean, re-checkable ground truth for
inverse-dynamics and law-inference tasks.

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
xJoepec force-pushed the feat/central-force-potentials branch from 657066b to 384b593 Compare August 22, 2026 20:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant