Quick start

Follow the steps below to prepare a development environment, run a minimal simulation, and confirm that the regression tooling works on your machine.

1. Clone the repository and create a virtual environment (.venv is assumed throughout the project scripts):

   git clone https://github.com/benfolsom/LW_integrator/
   cd LW_integrator
   python -m venv .venv
   source .venv/bin/activate
   pip install --upgrade pip
   

2. Install the project in editable mode together with the optional extra used by the validation notebooks:

   pip install -e .[dev]
   

   The dev extra mirrors the dependencies used in CI (NumPy, SciPy, Matplotlib, pytest, Sphinx, nbsphinx, etc.).

3. Run the integration test suite to confirm the core and legacy solvers agree on the canonical benchmark:

   pytest tests/integration/test_core_integrators.py -k two_particle
   

   Expect to see both the pure core solver and the self-consistent wrapper match the legacy reference to within floating-point tolerances.

4. Launch the colourblind-friendly benchmark notebook:

   code examples/validation/core_vs_legacy_benchmark.ipynb
   

   From VS Code or Jupyter Lab, execute the cells and experiment with the widgets. The notebook runs the same run_benchmark helper that the CLI uses and can save overlay plots and ΔE scatter figures directly.

5. Generate the HTML documentation locally:

   cd docs
   ./build_docs.sh --clean --type html
   

   Open docs/build/html/index.html in a browser to browse the rendered pages.

Next steps

• Validation and regression details the scripts and notebooks that compare the core and legacy implementations across multiple seeds and integration lengths.

• Working with the notebooks provides guidance on using the interactive assets efficiently (plot styling, DPI control, output directories, etc.).

• Development guide is the entry point for coding conventions, testing expectations, and contribution guidelines.