Metadata-Version: 2.4
Name: solitonlab
Version: 0.1.0
Summary: A fast, correct engine for nonlinear field theory with guaranteed topological bookkeeping (solitons, kinks, vortices).
Project-URL: Homepage, https://github.com/kobyfowler-git/solitonlab
Project-URL: Repository, https://github.com/kobyfowler-git/solitonlab
Project-URL: Issues, https://github.com/kobyfowler-git/solitonlab/issues
Project-URL: Changelog, https://github.com/kobyfowler-git/solitonlab/blob/main/CHANGELOG.md
Author: Koby Fowler
License: MIT
License-File: LICENSE
Keywords: field-theory,kink,nonlinear,pde,simulation,sine-gordon,soliton,topological-defect,vortex,winding-number
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: matplotlib>=3.6; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.6; extra == 'viz'
Description-Content-Type: text/markdown

# solitonlab

[![CI](https://github.com/kobyfowler-git/solitonlab/actions/workflows/ci.yml/badge.svg)](https://github.com/kobyfowler-git/solitonlab/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/solitonlab.svg)](https://pypi.org/project/solitonlab/)
[![Downloads](https://static.pepy.tech/badge/solitonlab)](https://pepy.tech/project/solitonlab)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)

**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

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

## Quick start

```python
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

```bash
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

| Module | Purpose |
| --- | --- |
| `lattice` | `Lattice1D` / `Lattice2D` with explicit boundary conditions |
| `operators` | Laplacians/gradients incl. the winding-aware ring Laplacian |
| `models` | `SineGordon`, `Phi4`, `KleinGordon` (+ exact soliton constructors) |
| `integrators` | `Simulator` — leapfrog with CFL safety and energy tracking |
| `topology` | `winding_number_1d`, `vortex_charge_2d`, `find_vortices_2d` |
| `diagnostics` | `kink_center`, `kink_width`, `proper_acceleration`, `energy` |

## Tests

```bash
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](CONTRIBUTING.md). By participating you agree to the
[Code of Conduct](CODE_OF_CONDUCT.md).

## 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](CITATION.cff)
or use "Cite this repository" on GitHub.

## License

MIT © Koby Fowler — see [LICENSE](LICENSE).
