# computationalradiationphysics/picongpu architecture

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

- Interactive diagram: https://gitdiagram.com/computationalradiationphysics/picongpu
- Repository: https://github.com/computationalradiationphysics/picongpu

## Overview

PIConGPU is a relativistic particle-in-cell plasma simulator. Users provide configuration and run a simulation: the executable parses arguments, then hands control to the simulation lifecycle; initialization configures fields and particle species, and the PIC cycle advances particles and electromagnetic fields. The README also documents coupled atomic physics, radiation diagnostics, openPMD output/restarts, live diagnostics, and extensible plugins. Several implementation paths are represented by their existing enclosing directories because their specific files were not sampled; those connections are documented or marked unverified accordingly.

Main entry points: [`include/picongpu/particles/MoveParticle.hpp`](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/particles/MoveParticle.hpp) (Particle motion), [`include/picongpu/initialization/InitialiserController.hpp`](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/initialization/InitialiserController.hpp) (Simulation initialization), [`include/picongpu/main.x.cpp`](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/main.x.cpp) (Executable entry), [`include/picongpu/fields/EMFieldBase.hpp`](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/fields/EMFieldBase.hpp) (Electromagnetic fields)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Run and setup"]
  node_entry["Executable entry<br/>[main.x.cpp]"]
  node_arguments["Argument parser<br/>[ArgsParser.cpp]"]
  node_initialization["Simulation initialization"]
  node_profiles["Particle profiles"]
  node_python["PICMI interface<br/>[simulation.py]"]
end

subgraph group_pic["PIC physics"]
  node_fields["Electromagnetic fields<br/>[EMFieldBase.hpp]"]
  node_maxwell["Maxwell solvers<br/>[Solvers.hpp]"]
  node_incident["Incident fields<br/>[profiles.hpp]"]
  node_pusher["Particle motion<br/>[MoveParticle.hpp]"]
  node_deposition["Current deposition<br/>[Deposit.hpp]"]
  node_boundaries["Particle boundaries<br/>[Apply.hpp]"]
end

subgraph group_extensions["Physics extensions"]
  node_atomic["Atomic physics"]
  node_collisions["Particle collisions"]
  node_radiation["Radiation reaction"]
end

subgraph group_runtime["Runtime and diagnostics"]
  node_plugins["Plugin controller"]
  node_diagnostics["Online diagnostics"]
  node_openpmd["openPMD I/O"]
  node_pmacc["PMacc runtime<br/>[Manager.hpp]"]
end

node_user(("Simulation user"))
node_openpmd_service[("openPMD services")]

node_user -->|"runs"| node_entry
node_entry -->|"parses arguments"| node_arguments
node_entry -.->|"starts simulation"| node_initialization
node_initialization -->|"configures"| node_fields
node_initialization -->|"checks solver"| node_maxwell
node_initialization -->|"configures profiles"| node_incident
node_initialization -.->|"initializes species"| node_profiles
node_pusher -.->|"interpolates fields"| node_fields
node_pusher -.->|"deposits current"| node_deposition
node_maxwell -.->|"updates fields"| node_fields
node_incident -.->|"adds incident fields"| node_fields
node_boundaries -.->|"affects particle motion"| node_pusher
node_atomic -.->|"couples field ionization"| node_fields
node_collisions -.->|"alters particle motion"| node_pusher
node_radiation -.->|"couples radiation reaction"| node_pusher
node_plugins -->|"hosts plugins"| node_diagnostics
node_plugins -.->|"hosts plugins"| node_openpmd
node_diagnostics -.->|"observes particles"| node_pusher
node_openpmd -->|"writes and restarts"| node_openpmd_service
node_entry -->|"finalizes runtime"| node_pmacc
node_python -.->|"configures runs"| node_entry

click node_entry "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/main.x.cpp"
click node_arguments "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/ArgsParser.cpp"
click node_initialization "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/initialization/InitialiserController.hpp"
click node_profiles "https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/particles/densityProfiles"
click node_fields "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/fields/EMFieldBase.hpp"
click node_maxwell "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/fields/MaxwellSolver/Solvers.hpp"
click node_incident "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/fields/incidentField/profiles/profiles.hpp"
click node_pusher "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/particles/MoveParticle.hpp"
click node_deposition "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/fields/currentDeposition/Deposit.hpp"
click node_boundaries "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/particles/boundary/Apply.hpp"
click node_atomic "https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/particles/atomicPhysics"
click node_collisions "https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/particles/collision"
click node_radiation "https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/particles"
click node_plugins "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/plugins/PluginController.hpp"
click node_diagnostics "https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/plugins"
click node_openpmd "https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/plugins"
click node_pmacc "https://github.com/computationalradiationphysics/picongpu/blob/dev/include/pmacc/eventSystem/Manager.hpp"
click node_python "https://github.com/computationalradiationphysics/picongpu/blob/dev/lib/python/picongpu/picmi/simulation.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_arguments,node_initialization,node_profiles,node_python,node_user toneBlue
class node_fields,node_maxwell,node_incident,node_pusher,node_deposition,node_boundaries,node_openpmd_service toneAmber
class node_atomic,node_collisions,node_radiation toneMint
class node_plugins,node_diagnostics,node_openpmd,node_pmacc toneRose
```

## Components

### Run and setup

- [Executable entry](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/main.x.cpp): `include/picongpu/main.x.cpp`
- [Argument parser](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/ArgsParser.cpp): `include/picongpu/ArgsParser.cpp`
- [Simulation initialization](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/initialization/InitialiserController.hpp): `include/picongpu/initialization/InitialiserController.hpp`
- [Particle profiles](https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/particles/densityProfiles): `include/picongpu/particles/densityProfiles`
- [PICMI interface](https://github.com/computationalradiationphysics/picongpu/blob/dev/lib/python/picongpu/picmi/simulation.py): `lib/python/picongpu/picmi/simulation.py`

### PIC physics

- [Electromagnetic fields](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/fields/EMFieldBase.hpp): `include/picongpu/fields/EMFieldBase.hpp`
- [Maxwell solvers](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/fields/MaxwellSolver/Solvers.hpp): `include/picongpu/fields/MaxwellSolver/Solvers.hpp`
- [Incident fields](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/fields/incidentField/profiles/profiles.hpp): `include/picongpu/fields/incidentField/profiles/profiles.hpp`
- [Particle motion](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/particles/MoveParticle.hpp): `include/picongpu/particles/MoveParticle.hpp`
- [Current deposition](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/fields/currentDeposition/Deposit.hpp): `include/picongpu/fields/currentDeposition/Deposit.hpp`
- [Particle boundaries](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/particles/boundary/Apply.hpp): `include/picongpu/particles/boundary/Apply.hpp`

### Physics extensions

- [Atomic physics](https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/particles/atomicPhysics): `include/picongpu/particles/atomicPhysics`
- [Particle collisions](https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/particles/collision): `include/picongpu/particles/collision`
- [Radiation reaction](https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/particles): `include/picongpu/particles`

### Runtime and diagnostics

- [Plugin controller](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/picongpu/plugins/PluginController.hpp): `include/picongpu/plugins/PluginController.hpp`
- [Online diagnostics](https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/plugins): `include/picongpu/plugins`
- [openPMD I/O](https://github.com/computationalradiationphysics/picongpu/tree/dev/include/picongpu/plugins): `include/picongpu/plugins`
- [PMacc runtime](https://github.com/computationalradiationphysics/picongpu/blob/dev/include/pmacc/eventSystem/Manager.hpp): `include/pmacc/eventSystem/Manager.hpp`

### Other components

- **Simulation user**
- **openPMD services**

## Connections

- Simulation user → Executable entry: runs
- Executable entry → Argument parser: parses arguments (evidence: `include/picongpu/main.x.cpp`)
- Executable entry → Simulation initialization: starts simulation
- Simulation initialization → Electromagnetic fields: configures (evidence: `include/picongpu/initialization/InitialiserController.hpp`)
- Simulation initialization → Maxwell solvers: checks solver (evidence: `include/picongpu/initialization/InitialiserController.hpp`)
- Simulation initialization → Incident fields: configures profiles (evidence: `include/picongpu/initialization/InitialiserController.hpp`)
- Simulation initialization → Particle profiles: initializes species
- Particle motion → Electromagnetic fields: interpolates fields
- Particle motion → Current deposition: deposits current
- Maxwell solvers → Electromagnetic fields: updates fields
- Incident fields → Electromagnetic fields: adds incident fields
- Particle boundaries → Particle motion: affects particle motion
- Atomic physics → Electromagnetic fields: couples field ionization
- Particle collisions → Particle motion: alters particle motion
- Radiation reaction → Particle motion: couples radiation reaction
- Plugin controller → Online diagnostics: hosts plugins (evidence: `include/picongpu/plugins/PluginController.hpp`)
- Plugin controller → openPMD I/O: hosts plugins (evidence: `include/picongpu/plugins/PluginController.hpp`)
- Online diagnostics → Particle motion: observes particles
- openPMD I/O → openPMD services: writes and restarts
- Executable entry → PMacc runtime: finalizes runtime (evidence: `include/picongpu/main.x.cpp`)
- PICMI interface → Executable entry: configures runs
