Overview

The LW Integrator is a covariant electromagnetic particle tracking code tuned for accelerator physics studies. The validated implementation still lives in the legacy/ tree, but the modern core/ package mirrors the same physics with clearer structure, type hints, and unit-tested helper utilities. This page summarises the pieces you will encounter when navigating the repository.

High-level anatomy

core/: The maintained implementation of the retarded Liénard–Wiechert solver. trajectory_integrator.py retains the original algorithm but exposes it through typed helper functions (image charge generators, retarded-distance utilities, and the IntegratorConfig data class). performance.py bundles optional Numba kernels that accelerate large runs without changing the underlying physics. self_consistency.py holds the fixed-point iteration used for radiation-reaction corrections.
legacy/: Archived notebooks and scripts from the original codebase. They are kept for regression comparisons and historical reference. Production workflows should use core/ unless you are debugging a discrepancy.
examples/: Ready-to-run validation material. The validation/ folder contains both Python scripts and Jupyter notebooks that reproduce the legacy vs. core comparisons. The comparison/ folder houses CLI benchmarks that report metrics (maximum Δγ, Δz, etc.) across seeded simulation suites.
tests/: Automated regression coverage. tests/integration/test_core_integrators.py verifies equivalence between the core solver, its self-consistent variant, and the legacy implementation. tests/unit hosts deterministic unit tests for helper functions such as generate_conducting_image.
input_output/: Utilities for constructing particle bunch dictionaries in the format the integrator expects. bunch_initialization.py is the main entry point and is documented in the API section below.
docs/: The refreshed documentation that you are currently reading. Sphinx builds use the configuration in docs/source/conf.py and the helper script docs/build_docs.sh.

Key ideas to keep in mind

Physics parity matters. The core code is intentionally a transcription of the legacy solver. Any behavioural change should come with matching updates to the validation scripts and the integration tests.
Particle states are dictionaries of NumPy arrays. Whenever you initialize particles manually, fill every expected key (x, Pz, gamma, q, char_time …) or use input_output.create_bunch_from_energy to obtain a correctly shaped state.
Simulation modes are enumerated. SimulationType enumerates the three supported wall configurations. The solver mirrors the legacy integer flags so comparison runs remain straightforward.
Notebook tooling is first-class. The validation notebooks are kept in sync with the scripts and expose colourblind-friendly plots, high-DPI export, and configuration widgets. Use them to explore scenarios before committing to scripted sweeps.
Need the math? See Theory primer for the derivation of the covariant equations of motion implemented in core/trajectory_integrator.py and the approximations used in the benchmark studies.

With the map in hand, continue to Quick start to set up a development environment or jump to Validation and regression for the comparison workflows.