PlasmaMLPALLAS
Loading...
Searching...
No Matches
PlasmaMLPALLAS

PALLAS Simulation – Plasma Beam Generation with Geant4 & ML Integration

Project Authors: Arnaud HUBER & Alexei SYTOV
Date: 2024–2025
Collaboration: GEANT4, PALLAS Project

Table of Contents

  • Introduction
  • Features
  • Dependencies
  • Installation
  • Building the Simulation
  • Running the Simulation
  • PlasmaMLPALLAS Macro Configuration
  • Primary Generator
  • ONNX Model Inference for Plasma Beam Generation
  • Geometry Utilities
  • PALLAS Geometry Construction
  • PALLAS MagneticField
  • Physics List
  • Quadrupole Utilities
  • Step-Level Tracking and Data Extraction
  • ROOT Output
  • Architecture Diagram
  • Documentation
  • License

Introduction

The PALLAS simulation framework is a Geant4-based toolkit for modeling plasma-accelerated particle beams. It integrates traditional Monte Carlo methods with machine learning-based ONNX beam generation, allowing flexible, high-fidelity simulations of beam transport through dipole and quadrupole fields.

🎯 Audience: Physicists, accelerator scientists, ML/physics integration developers.

🧩 Applications: Plasma accelerators, beamline design, detector response studies.

⚡ Strength: Combines ML inference + Geant4 physics + ROOT data analysis in a single workflow.

Features

  • Primary particle generation via:
    • ONNX ML model
    • Geant4 General Particle Source (GPS)
  • Custom physics list optimized for plasma and nuclear physics:
    • High-precision hadronic and electromagnetic physics
    • Ion interactions and stopping physics
    • Decay and radioactive decay
  • Magnetic field simulation:
    • Dipole and quadrupole contributions
    • Fitted field maps (error function + Gaussian)
  • Quadrupole tracking utilities
  • User interface commands for interactive parameter adjustment
  • Multithreaded event generation with progress display
  • Doxygen-documented codebase

Dependencies

  • Geant4 >= 11.1 with GDML option ACTIVATED [Compilation OK on version 11.3.2]
    cmake -DGEANT4_USE_GDML=ON
  • CLHEP (units & constants)
  • ONNX Runtime
  • C++17 or later
  • Standard libraries: <atomic>, <chrono>, <vector>, <string>, <cmath>, <memory>

Installation

git clone https://github.com/ahuber33/PlasmaMLPALLAS

Building the Simulation

mkdir build && cd build
cmake -DGeant4_DIR=$G4COMP ../ -DOnnxRuntime_LIBRARY=../onnxruntime-linux-x64-1.17.1/lib/libonnxruntime.so.1.17.1
make -j$(nproc)

The executable PlasmaMLPALLAS will be added to your bin folder.

Running the Simulation

  • With visualization:
./PlasmaMLPALLAS [name_of_ROOT_file]

It will generate particles according to the macro (e.g., vis.mac) and produce a ROOT file in the Resultats folder.

  • Without visualization (statistics only):
./PlasmaMLPALLAS [name_of_ROOT_file] [number_of_events] [macro_file] [MT ON/OFF] [number_of_threads]

Notes:

  • If MT is ON, temporary ROOT files for each thread are merged at the end.
  • If MT is OFF, no need to specify the number of threads.
  • You can use any macro file (e.g., vrml.mac).

PlasmaMLPALLAS Macro Configuration

This macro configures geometry, magnetic fields, tracking, and particle sources for PALLAS PlasmaMLP simulations. It allows full customization of quadrupole setup, dipole fields, and particle generation methods.

Geometry Configuration:

  • Quadrupole lengths: Q1-Q4 individually configurable.
  • Distances: between source, quadrupoles and collimators.
  • Display options: toggle full geometry, quadrupoles and collimators for visualization.
  • Changes are applied with /run/reinitializeGeometry.

Magnetic Fields Configuration:

  • Quadrupole gradients: individually set for Q1-Q4.
  • B-field map mode: can be enabled/disabled for dipole spectrometer
  • Dipole field: constant value if B-field map mode is disabled.

Tracking options Configuration:

  • Particle tracking can be enabled/disabled globally or for collimators interaction.
  • Verbosity controls for both tracking and run output.

Particle Sources Configuration:

  • ONNX-based Particle Gun:
    • Particle type, laser focus, normalized vector potential, dopant fraction and chamber pressure configurable.
  • GEANT4 GPS (General Particle Source):
    • Number, type, position, direction and energy of particles.

This macro provides a ready-to-use setup for simulations with either the particle gun or GPS, including full control over magnetic fields and geometry.

User Interface Commands:

  • /PlasmaMLPALLAS/geometry/... – Geometry configuration
  • /PlasmaMLPALLAS/display/... – Geometry visualization options
  • /PlasmaMLPALLAS/field/... – Magnetic field configuraiton
  • /PlasmaMLPALLAS/step/... – Particle tracking settings
  • /PlasmaMLPALLAS/gun/... – Particle generation
  • /PlasmaMLPALLAS/laser/... – ML laser parameters

Controls:

  • ONNX particle gun: enable/disable (/gun/setStatusONNX)
  • Particle type: set particle name (/gun/setParticleName)
  • Laser parameters:
    • focus offset: /laser/setOffsetLaserFocus
    • normalized vector potential: /laser/setNormVecPotential
    • dopant fraction: /laser/setFracDopTargetChamber
    • chamber pressure: /laser/setPressure
  • Quadrupoles:
    • lengths: /geometry/setQnLength
    • positions and distances between quadrupoles or source: /geometry/setSourceQ1Distance, /geometry/setQnQn+1Distance
  • Magnetic fields:
    • quadrupole gradients: /field/setQnGradient
    • dipole field value: /field/setConstantDipoleBField
    • mapped-field mode on/off: /field/setStatusMapBField
  • Tracking:
    • enable/disable globally: /step/SetTrackingStatus
    • enable/disable for collimators: /step/SetTrackingStatusCollimators
  • Display:
    • enable/disable geometry: /display/setStatusDisplayGeometry
    • enable/disable quadrupoles: /display/setStatusDisplayQuadrupoles
    • enable/disable collimators: /display/setStatusDisplayCollimators
  • GPS (alternative to particle gun):
    • particle number: /gps/number
    • particle type: /gps/particle
    • particle position: /gps/pos
    • particle direction: /gps/direction
    • particle energy: /gps/energy

Primary Generator

Class: PlasmaMLPALLASPrimaryGeneratorAction

The PlasmaMLPALLASPrimaryGeneratorAction class handles the generation of primary particles for the PALLAS simulation. It supports two generation modes:

Modes:

  • ONNX ML-based beam generation:
    • Uses a neural network to predict beam parameters (energy, charge, emittance, transverse positions and momenta).
    • Configures the particle gun based on the predicted parameters.
    • Energy smearing with Gaussian fluctuations is applied.
  • GPS particle source:
    • Standard particle generation using the Geant4 GPS

Features:

  • Thread-safe generation using atomic counters.
  • Per-thread UI handling; thread 0 displays a progress bar with estimated remaining time.
  • Automatic particle definition lookup in the Geant4 particle table.
  • Supports multithreading and safe progress display.

Usage:

  • Instantiate the class and assign it to Geant4 run manager using SetUserAction
  • Configure ONNX or GPS parameters via the messenger before starting the run.

ONNX Model Inference for Plasma Beam Generation

Class: PlasmaMLPALLASOnnxInference

The PlasmaMLPALLASOnnxInference class provides a mechanism to generate physically realistic beam parameters using a pre-trained ONNX neural network model. It is used to configure the primary particle gun in the PALLAS simulation.

Functionality:

  • Initializes the ONNX runtime environnment and loads the specific model.
  • Prepares input tensors from simulation parameters:
    • Laser focal offset fXof
    • Laser normalized amplitude fA0
    • Fraction Dopant in Chamber fCN2
    • Gas pressure in Chamber fPressure
  • Runs inference and converts model outputs to physical units.
  • Samples transverse beam coordinates (x, z) and angles (xp, zp) using Gaussian/Twiss-based distributions
  • Produces a BeamParameters structure containing:
    • Kinetic energy Ekin and energy spread dEkin
    • Beam charge Q
    • Normalized emittance epsb
    • Transverse positions (x, z) and angles (xp, zp)

Purpose:

  • To generate ONNX-predicted particle beams with realistic physical characteristics for use in Geant4 simulations.
  • Integrates seamlessly with the primary generator action (PlasmaMLPALLASPrimaryGeneratorAction) for ONNX-based particle generation.

Units:

  • All physical quantities are expressed using CLHEP units.

Geometry Utilities

File: Geometry.cc

The Geometry class provides tools to define and load geometrical volumes for the PALLAS simulation. It centralizes the construction of detector and beamline components, either from GDML descriptions or via simplified Geant4 primitives.

Features:

  • GDML Import: Load volumes from GDML files and assign materials dynamically.
  • Quadrupole Construction: Generate simplified quadrupole magnets as vacuum-filled box volumes.
  • Diagnostics Chambers: Create cylindrical chambers by subtracting tubular volumes, useful for fast detector prototyping.

Example:

// Load a GDML-defined volume
auto* vol = geometry.GetGDMLVolume("beamline.gdml", "Target", material);
// Create a simple quadrupole
auto* quad = geometry.GetQuadrupoleVolume("Q1", 50, 50, 200);
// Build a diagnostic chamber
auto* chamber = geometry.GetFakeDiagsChamber();

This utility simplifies beamline setup and makes it easier to switch between realistic GDML-based geometries and fast approximations for testing.

PALLAS Geometry Construction

File:: PlasmaMLPALLASGeometryConstruction.cc

This module handles the full PALLAS experimental geometry in Geant4, including CAD/GDML model imports, definition of logical and physical volumes, and magnetic field configuration for simulations.

Overall Structure:

  • World and Hodler: global empty volume serving as the main container for all components. Holder is here to count and stop particles which are going to the World volume.
  • Plasma Cells: assembly of two connected plasma cells
  • LIF (Laser-Induced Fluorescence): optical components (windows, crosses, breadbords, ...).
  • Quadrupoles:
    • Simplified: parametrized volumes for production runs.
    • Full: GDML imported from CAD models for detailed visualization.
  • Experimental Sections:
    • Section 1: ISO chamber, base and plasma cell supports.
    • Section 2: Removal chambers and ISO tubes.
    • Section 3: ASM and YAG station.
    • Section 4: Dipole chamber, dipole magnet and associated diagnostics.
    • Section 4 Dump: shielding, chassis and protection components.
  • Collimators: horizontal and vertical collimators from GDML files, manually aligned with the beam axis.

Magnetic Fields:

  • Complete magnetic field configuration:
    • Constant dipole field.
    • Quadrupole gradients (Q1-Q4).
    • Drift distances and quadrupole lengths.
  • Uses G4FieldManagerand G4ChordFinder with a classical RK4 stepper for accurate particle tracking.

Construction Modes:

  • Full Geometry: all sections and GDML volumes for complete visualization.
  • Simplified Geometry: only Section 4, avoiding potential stuck tracks from complex GDML during production simulations.

Visualization:

-Logical volumes are color-coded for easier inspection:

  • Red: quadrupoles and ISO chambers.
  • Cyan: Sections 2 and 4.
  • Orange: Section 3.
  • Green: LIF components.
  • Yellow: collimators and some diagnostics chambers

Notes:

  • Some GDML files (e.g. ISO chamber) may require adjustements for stable operation.
  • Manual offsets are applied to quadrupoles and collimators to align components precisely with the beam.

PALLAS MagneticField

File:: PlasmaMLPALLASMagneticField.cc

This class provides the magnetic field configuration for the PALLAS PlasmaMLP simulation in Geant4, combining dipole and quadrupole contributions with optional mapped-field profiles. It includes both field computation and parameter management.

Features:

  • Dipole Field:
    • Constant or mapped-field mode.
    • Can be enabled/disabled at runtime
  • Quadrupoles Fields:
    • Configurable gradients, lengths and drift distances.
    • Contributions automatically applied in the relevant spatial regions.
  • Fit Functions:

Magnetic Field Computation:

  • GetFieldValue(point, bField): computes the total magnetic field at any point in space.
  • Quadrupole contributions are added only if the particle is within their defined range.
  • Mapped-field mode uses parametrized fits along Y and S axes; otherwise, a constant dipole field is aplied.

Configuration Methods:

  • SetDipoleField(value): set constant dipole field in Tesla.
  • SetMapBFieldStatus(status): toggle mapped-field mode.
  • SetGradient(index, value), SetQLength(index, value), SetQDrift(index, value): configure quadrupoles individually.
  • Corresponding getters are provided for all quadrupole parameters.

Units:

  • Compatible with GEANT4 and CLHEP units for length, field and gradient.

Physics List

Class: PlasmaMLPALLASPhysics
Derived from G4VModularPhysicsList

Includes:

  • High-precision hadronic and elastic models
  • Electromagnetic physics (G4EmStandardPhysics_option3)
  • Stopping physics
  • Decay and radioactive decay

Quadrupole Utilities

File: PlasmaMLPALLASQuadrupoleUtils.cc

Update individual vector components of quadrupoles (position or momentum, start or end).

Example:

SetQuadrupoleValue(stats, QuadID::Q1, PositionType::Begin, VectorType::Position, Axis::X, 0.1f);
SetQuadrupoleValue
void SetQuadrupoleValue(RunTallyQuadrupoles &stats, QuadID qid, PositionType posType, VectorType vecType, Axis axis, float value)
Sets a specific component of a quadrupole vector.
Definition PlasmaMLPALLASQuadrupoleUtils.cc:54

Step-Level Tracking and Data Extraction

File: PlasmaMLPALLASSteppingAction.cc

The PlasmaMLPALLASSteppingAction class handles fine-grained particle tracking at each simulation step in the PALLAS project. It collects particle data, manages quadrupole interactions, collimator events, and YAG screen statistics.

Functionality:

  • Extracts positions, momentum directions, kinetic energy and deposited energy at each Geant4 step.
  • Stores initial beam parameters for primary particles at the first step.
  • Tracks particle crossings through quadrupoles and records entry/exit statistics.
  • Updates collimator interactions: records positions and energies, optionally terminates tracks if collimator tracking is disabled.
  • Updates YAG screen statistics: exit positions, deposited energy, particle IDs and total deposited energy.
  • Automatically kills particles leaving the world volume.

Purpose:

  • Provides detailed per-step data collection for beamline analysis.
  • Enables statistics for quadrupoles, collimators and diagnostics screens.
  • Integrates with PlasmaMLPALLASEventAction for storing and tallying simulation results.

ROOT Output

  • BeginOfRunAction creates six trees:
    • Tree_GlobalInput – Simulation and ML parameters
    • Tree_Input – Particle initial positions, momenta, offsets
    • Tree_HorizontalColl – Energy deposited in horizontal collimator
    • Tree_VerticalColl – Energy deposited in vertical collimator
    • Tree_BSYAG – Particles interacting with YAG, magnet OFF
    • Tree_BSPECYAG – Particles interacting with YAG, magnet ON
  • Variables are initialized in BeginOfEventAction and filled in EndOfEventAction.
  • Particle propagation and interaction info is collected in PlasmaMLPALLASSteppingAction.cc.

Architecture Diagram

+------------------------------+
| PALLAS Simulation |
+------------------------------+
|
v
+------------------------------+
| PrimaryGeneratorAction |
| - GPS / ONNX ML Beam |
+------------------------------+
|
v
+------------------------------+
| ONNXInference |
| - GenerateBeam(params) |
+------------------------------+
|
v
+------------------------------+ +-------------------------+
| MagneticField (Dipole + |<---->| Quadrupole Utilities |
| Quadrupoles / Fitted Maps) | | - Set/Update Vectors |
+------------------------------+ +-------------------------+
|
v
+------------------------------+
| Physics List (EM + Had) |
| - G4EmStandardPhysics_option3|
| - G4HadronPhysicsQGSP_BIC_HP|
| - Ion, Stopping, Decay |
+------------------------------+
|
v
+------------------------------+
| Event Generation & Output |
+------------------------------+

Documentation

La documentation du projet est disponible ici :
📖 Documentation Doxygen

Generate with:

doxygen Doxyfile

Access via: docs/html/index.html

License

PALLAS Project – GEANT4 Collaboration

See the LICENSE file for details.

Generated by doxygen 1.9.8