# angelfp/wake-t architecture

> Architecture diagram of the GitHub repository angelfp/wake-t, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/angelfp/wake-t
- Repository: https://github.com/angelfp/wake-t

## Overview

##### 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.”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface / Entry Point
    subgraph "User Interface / Entry Point"
        direction TB
        Ex1["track_plasma_fluid.py"] 
        Ex2["track_plasma_qs2d.py"] 
        Ex3["00_basic_tutorial.py"] 
        Ex4["01_single_plasma_simulation.py"] 
        Ex5["02_plasma_beamline_simulation.py"] 
    end
    Ex1 --> Tracker
    Ex2 --> Tracker
    Ex3 --> Tracker
    Ex4 --> Tracker
    Ex5 --> Tracker

    %% Simulation Controller
    Tracker["Simulation Controller (Tracker)"]:::control

    %% Beamline Elements
    Tracker --> BeamlineElements
    subgraph "Beamline Elements"
        direction TB
        BeamlineElements["Beamline Elements"]:::subsys
    end

    %% Field Computation Subsystem
    BeamlineElements --> FieldComp
    subgraph "Field Computation Subsystem"
        direction TB
        Fields["fields"]:::physics
        PhysModels["physics_models"]:::physics
    end
    FieldComp["Field Computation"]:::physics
    Fields --> FieldComp
    PhysModels --> FieldComp

    %% Particle Pusher Subsystem
    BeamlineElements --> PusherSub
    subgraph "Particle Pusher Subsystem"
        direction TB
        Boris["Boris Pusher"]:::physics
        RK4["Runge-Kutta 4"]:::physics
        TM["Transfer Matrix"]:::physics
    end
    PusherSub["Particle Pusher"]:::physics
    Boris --> PusherSub
    RK4 --> PusherSub
    TM --> PusherSub

    %% Central Data Object
    FieldComp --> ParticleBunch
    PusherSub --> ParticleBunch
    ParticleBunch[(Particle Bunch)]:::data

    %% Diagnostics & Output
    ParticleBunch --> Diagnostics
    subgraph "Diagnostics & Output"
        direction TB
        Diagnostics["Diagnostics & Output"]:::io
    end
    Diagnostics --> Tracker

    %% Final Results
    Tracker --> Results
    Results[(Results / File Storage)]:::io

    %% Click Events
    click Ex1 "https://github.com/angelfp/wake-t/blob/dev/examples/track_plasma_fluid.py"
    click Ex2 "https://github.com/angelfp/wake-t/blob/dev/examples/track_plasma_qs2d.py"
    click Ex3 "https://github.com/angelfp/wake-t/blob/dev/tutorials/00_basic_tutorial.py"
    click Ex4 "https://github.com/angelfp/wake-t/blob/dev/tutorials/01_single_plasma_simulation.py"
    click Ex5 "https://github.com/angelfp/wake-t/blob/dev/tutorials/02_plasma_beamline_simulation.py"
    click Tracker "https://github.com/angelfp/wake-t/blob/dev/wake_t/tracking/tracker.py"
    click BeamlineElements "https://github.com/angelfp/wake-t/tree/dev/wake_t/beamline_elements/"
    click Fields "https://github.com/angelfp/wake-t/tree/dev/wake_t/fields/"
    click PhysModels "https://github.com/angelfp/wake-t/tree/dev/wake_t/physics_models/"
    click Boris "https://github.com/angelfp/wake-t/blob/dev/wake_t/particles/push/boris_pusher.py"
    click RK4 "https://github.com/angelfp/wake-t/blob/dev/wake_t/particles/push/runge_kutta_4.py"
    click TM "https://github.com/angelfp/wake-t/blob/dev/wake_t/particles/push/transfer_matrix.py"
    click ParticleBunch "https://github.com/angelfp/wake-t/blob/dev/wake_t/particles/particle_bunch.py"
    click Diagnostics "https://github.com/angelfp/wake-t/tree/dev/wake_t/diagnostics/"
    click Results "https://github.com/angelfp/wake-t/tree/dev/wake_t/utilities/"

    %% Styles
    classDef control fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef physics fill:#d4edda,stroke:#333,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef io fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef subsys fill:#f8f9fa,stroke:#333,stroke-width:1px
```
