How angelfp/wake-t works
Project Type and Purpose
• Wake-T is a Python-based simulation library for plasma wakefield accelerators (“Wakefield particle Tracker”).
• Not a client/server or microservice app, but a computational library with a clear modular structure: beamline elements, field solvers, particle pushers, tracking orchestration, diagnostics, and utilities.
File Structure
• Top-level package: wake_t/ contains all core code.
• beamline_elements/ – definitions of components in a beamline (drift, quadrupole, plasma stages, lenses, etc.)
• fields/ – abstractions & implementations of wakefields (analytical, numerical, RZ solver, gather/interpolation)
• particles/ – particle‐bunch representation, deposition/gather, and pushers (Boris, RK4, transfer matrices)
• physics_models/ – reduced plasma wake models (blowout regimes, CSR, envelope solvers)
• tracking/ – the Tracker orchestrator runs the simulation sequence, stepping through the beamline
• diagnostics/ – collects and processes data (bunch analyses, OpenPMD output)
• utilities/ – helpers for bunch generation, saving, numba optimizations, etc.
• Supporting items:
• examples/ and tutorials/ – usage scripts illustrating typical workflows
• tests/ – unit and regression tests validating each module
• docs/ – Sphinx docs and API references
Key Insights from README
• The simulation pipeline: user defines a beamline (combination of plasma stages, magnets, drifts) → Tracker runs through each element → at each step, fields are computed from reduced models (via physics_models + fields) → particles are advanced via pushers → diagnostics record results.
• Emphasis on speed: uses Runge‐Kutta solvers and transfer matrices instead of full PIC.
Main Components & Interactions
1) User Interface / Entry Point
– Python scripts/notebooks that import wake_t and define beamline + simulation parameters
2) Simulation Controller (tracking/Tracker)
3) Beamline Elements
– Each element has its own class (drift, quadrupole, plasma stage, etc.)
4) Field Computation Subsystem
– physics_models + fields modules collaborate to compute wakefields
5) Particle Pusher Subsystem
– Boris pusher, RK4, transfer matrices (in particles/push/)
6) Data Domain Objects
– Particle bunch (particles/particle_bunch.py), Field grids, diagnostics buffers
7) Diagnostics & Outputs
– Analysis and file writing (OpenPMD, custom plots)
8) Utilities
– Bunch generation, I/O, helper routines
• User script → initializes Simulation Controller + beamline definition
• Controller → iterates through Beamline Elements → at each:
• calls Field Computation Subsystem → returns field values
• passes fields + bunch to Particle Pusher → updates bunch
• invokes Diagnostics to record state
• Final bunch & diagnostics → returned to user / saved to disk via Utilities
c. Architectural Patterns & Principles:
• Modular separation: distinct packages for physics, fields, particles, tracking, diagnostics
• Pipeline pattern: sequential processing of beamline elements
• Strategy pattern: interchangeable pusher algorithms and field‐model implementations
• Data-driven design: core objects (bunch, fields) passed through modules
d. Key Technologies / Libraries
– Python 3, NumPy, Numba (optional), OpenPMD for I/O
– Sphinx for docs, pytest for tests
4) From that container, bifurcate two calls:
– one to “Particle Pusher” (group containing Boris, RK4, TransferMatrix).
8) Extension points: “Swap field model here”, “Select pusher strategy here.”