Architecture
============

This page summarizes how PyPIC3D is organized and how data flows through a run.

Execution Flow
--------------

1. ``PyPIC3D.__main__.main`` parses ``--config`` and enables JAX settings.
2. ``initialization.initialize_simulation`` builds defaults, loads TOML,
   computes derived world parameters, builds grids, initializes particles and
   fields, and selects loop functions.
3. ``run_PyPIC3D`` executes the timestep loop, writes diagnostics/outputs, and
   dumps run metadata.

Core Module Map
---------------

- ``PyPIC3D/__main__.py``: CLI and top-level run loop.
- ``PyPIC3D/initialization.py``: parameter defaults, config merge, world/grid
  setup, and mode selection.
- ``PyPIC3D/evolve.py``: JIT-compiled per-step loops.
- ``PyPIC3D/particle.py``: particle species model, initialization loaders,
  particle boundary handling.
- ``PyPIC3D/J.py``: current deposition kernels.
- ``PyPIC3D/rho.py``: charge deposition.
- ``PyPIC3D/solvers/``: field update operators and electrostatic Poisson
  helpers.
- ``PyPIC3D/diagnostics/``: phase-space plots, VTK output, openPMD output.
- ``PyPIC3D/utils.py``: config handling, filters, energy calculations,
  serialization helpers.

State Model
-----------

Main runtime objects:

- ``particles``: list of particle species objects.
- ``fields``:

  - electrodynamic/electrostatic: ``(E, B, J, rho, phi)``
  - vector potential path: ``(E, B, J, rho, phi, A2, A1, A0)``

- ``world``: spatial/temporal metadata, grid spacing, grid arrays, encoded field
  boundary conditions.
- ``constants``: physical constants and filter coefficients.

Data and Output Flow
--------------------

- Diagnostics and metadata are written under ``<output_dir>/data``.
- Text outputs include energy and momentum traces.
- Optional outputs include VTK files and openPMD files.
- ``output.toml`` captures simulation stats, resolved runtime parameters,
  particle summaries, and package versions.