solitonlab

A fast, correct engine for nonlinear field theory with guaranteed topological bookkeeping.

solitonlab simulates relativistic scalar field models (sine-Gordon, φ⁴, Klein-Gordon) and tracks their topological invariants — 1D winding numbers and 2D vortex charges — as integer quantities conserved to machine precision. It gets right the parts that ad-hoc simulation code usually gets wrong:

• Winding-aware differential operators. A phase field on a ring is periodic only modulo 2π. The naïve periodic Laplacian produces a spurious spike at the seam; winding_laplacian_1d handles it exactly, so a kink can wrap the ring and stay a soliton.
• Topological charge conserved to ~1e-16. Winding/vortex charges are computed as wrapped lattice sums that are exact for smooth fields and robust to noise.
• Symplectic time stepping with a CFL guard. Leapfrog integration keeps energy bounded over long runs (no artificial dispersion), and a supplied dt above the stability limit raises rather than silently blowing up.
• Relativistic soliton diagnostics. Charge-weighted kink tracking, width/dispersion measurement, and a constant-proper-acceleration (Rindler) invariant for driven kinks.

Use cases

What it's good for today

• Teaching topological defects. Show students a kink wrap a ring, a winding number stay pinned to an integer, or a vortex/antivortex pair annihilate — with numerics that actually conserve the charge instead of drifting.
• Research prototyping. Explore sine-Gordon, φ⁴, and Klein-Gordon dynamics with the bookkeeping already correct, so you can focus on the physics rather than debugging your Laplacian at the periodic seam.
• A trusted reference/baseline. Validate your own PDE solver against a library whose charge conservation and energy behaviour are pinned by tests, to catch seam bugs and numerical dispersion in your code.
• Relativistic soliton kinematics. Drive a kink with a bias field and measure its Rindler (constant-proper-acceleration) motion and Lorentz contraction directly.
• 2D vortex counting. Detect and sign topological defects in any phase / order-parameter field with vortex_charge_2d and find_vortices_2d.

Where it can go (natural extensions, not yet built in)

• Josephson junctions & fluxon dynamics — the long junction is driven sine-Gordon.
• Superfluid / superconductor vortices — 2D order-parameter defect tracking.
• Kibble–Zurek quench studies — defect formation rates under a controlled ramp.
• Domain walls in magnetism / ferroelectrics — φ⁴ kink dynamics under forcing.
• Labeled ML datasets — generate fields with known topological charge for training and benchmarking defect-detection models.

If you build one of these on top of solitonlab, a PR adding it as an example is very welcome.

Install

pip install -e .            # from source
pip install -e ".[dev]"     # with pytest + matplotlib

Quick start

import numpy as np
from solitonlab import Lattice1D, SineGordon, Simulator, winding_number_1d

lat = Lattice1D(n=1024, length=2*np.pi*8, bc="winding")   # a ring
model = SineGordon(lat, m=1.0)

phi0 = model.kink(center=lat.length/2, velocity=0.6)       # a moving winding kink
phit0 = model.kink_velocity_field(phi0, 0.6)

res = Simulator(model, phi0, phit0).run(steps=6000, record_every=60)

print(winding_number_1d(phi0), "->", winding_number_1d(res.field))   # 1 -> 1 (protected)

Command line

solitonlab kink --velocity 0.6 --steps 4000     # soliton on a ring; reports invariants
solitonlab vortices                             # detect a +1/-1 vortex pair in 2D

What's inside

Tests

pytest

The suite verifies the properties that make the library trustworthy: charge conservation, non-dispersing solitons, bounded energy, correct seam handling, and relativistic kink motion.

Contributing

Contributions are welcome. Every change ships with a test that pins the invariant it preserves — see CONTRIBUTING.md. By participating you agree to the Code of Conduct.

Roadmap

Planned directions for future releases (feedback and PRs welcome):

• Spectral (FFT-based) operators as a high-accuracy alternative to finite differences.
• A GinzburgLandau / complex-field model for superfluid- and superconductor-style vortices.
• 2D vortex dynamics (motion, pair annihilation) and a worked example.
• Time-dependent forcing and Kibble–Zurek quench helpers.
• Optional numba/vectorised fast paths for large lattices.

Citing

If solitonlab is useful in your work, please cite it — see CITATION.cff or use "Cite this repository" on GitHub.

License

MIT © Koby Fowler — see LICENSE.