BeamOnTarget

A high-performance Python application for simulating the interaction of particle beams with complex 3D geometries. It calculates the power deposited on the surfaces of mesh objects (from .stl files) and is optimised for parallel processing, memory efficiency, and batch-run capabilities.

The primary workflow involves defining geometry and particle sources, running the simulation, and analysing the detailed, ParaView-compatible output files — all from a graphical interface or the command line.

---

Key Features

• Graphical User Interface — Tkinter-based GUI (beamontarget.gui.sim_gui) for managing configurations, launching simulations, viewing results in an embedded 3D viewer (Open3D), and comparing CSV summaries with interactive bar-charts.
• Built-in 3D Viewer — GPU-accelerated Open3D renderer embedded inside the GUI with mouse-drag rotation, scroll-wheel zoom, right-click pan, orientation axis overlay, and jet colour-map with colour bar.
• High-Performance Engine — Uses trimesh with the pyembree ray-tracing backend for extremely fast intersection calculations.
• Parallel Processing — Leverages joblib to distribute work across multiple CPU cores.
• Memory-Safe Design — Handles billions of particles without storing them all in memory simultaneously.
• Folder-Centric Geometry — Organise .stl files into folders; apply scaling and mesh refinement to entire groups.
• Geometry Caching — Saves processed (refined) meshes to a cache, speeding up subsequent runs.
• Batch Simulation — Automatically finds and runs a simulation for every .bl file in the source directory.
• Advanced Particle Sources — Multiple beam models including GaussianTwissBeam.
• Professional Output — Saves results as ParaView-compatible .vtp files with cell data (Deposited Power, Power Density).
• Automated Post-Processing — Optional smoothing algorithm for clearer heat maps.
• VTP Data Extraction — Extract cell data from .vtp files to CSV directly from the GUI.
• CSV Result Comparison — Side-by-side bar-charts of peak power density and deposited power across multiple simulation runs, with per-component labels, multipliers, and log-scale toggles.
• Cross-Platform — Runs on Linux and Windows (Python ≥ 3.10).

---

File Structure

File	Description
src/beamontarget/gui/sim_gui.py	Tkinter GUI — the main graphical entry point (beamontarget command).
src/beamontarget/visualization/viewer.py	Built-in 3D viewer (Open3D off-screen rendering in Tk canvas).
src/beamontarget/workflows/run_simulation.py	CLI entry point — handles arguments and orchestrates simulation runs.
src/beamontarget/config.py	Central configuration module; reads/writes config.json.
config.json	Default configuration — the simple cube-and-sphere example.
config_beamline_example.json	Second configuration — the neutral beam injector example.
src/beamontarget/engine/engine.py	Core computational engine — power deposition calculation.
src/beamontarget/geometry/geometry.py	Loading, processing, caching, and grouping of .stl meshes.
src/beamontarget/particles/particles.py	Particle source classes and .bl file loading.
src/beamontarget/io/output.py	File output — .vtp saving and summary .csv reports.
src/beamontarget/io/smooth_results.py	Core smoothing logic (library).
src/beamontarget/io/batch_smoother.py	Applies smoothing to result .vtp files in a directory.
src/beamontarget/workflows/post_smooth.py	Additional post-processing / smoothing utilities.
src/beamontarget/io/generate_report.py	Automated report generation from results.
src/beamontarget/io/extract_mesh_data.py	CLI tool for extracting mesh cell data from .vtp to CSV.
pyproject.toml	Modern Python packaging metadata (PEP 621).
requirements.txt	Pinned dependency list (legacy, kept for reference).
install.sh	One-step installer for Linux.
install.bat	One-step installer for Windows.

---

Installation

Prerequisites

Requirement	Notes
Python ≥ 3.10	Any CPython 3.10–3.12 build.
Tkinter	Usually bundled with Python. On Debian/Ubuntu: apt install python3-tk.
C compiler (Linux only)	Required to build pyembree / embreex from source.

Running on an HPC cluster with environment modules? BeamOnTarget makes no assumption about your site. If your cluster uses Lmod or Environment Modules, load a suitable Python and Tk before installing, e.g. module load Python/3.11.5-GCCcore-13.2.0 Tkinter/3.11.5-GCCcore-13.2.0 — substitute the module names your site actually provides. Likewise, PARAVIEW_PATH in config.json defaults to paraview (resolved on PATH); set it to an absolute path, or set PARAVIEW_MODULE to the module the GUI should load, if that is how ParaView is provided at your site.

Option A — Quick Install (recommended)

Linux / macOS:

git clone https://github.com/iterorganization/BeamOnTarget.git
cd BeamOnTarget
chmod +x install.sh
./install.sh            # creates ./venv and installs everything
source venv/bin/activate
beamontarget            # launch the GUI

Windows:

git clone https://github.com/iterorganization/BeamOnTarget.git
cd BeamOnTarget
install.bat             &:: creates .\venv and installs everything
venv\Scripts\activate
beamontarget            &:: launch the GUI

Both scripts accept an optional argument to specify a custom venv path:

./install.sh /opt/beamontarget/env    # Linux
install.bat  C:\bot\env               :: Windows

Option B — Manual Install

python3 -m venv venv
source venv/bin/activate              # Windows: venv\Scripts\activate
pip install --upgrade pip setuptools wheel
pip install -e .                      # editable install from pyproject.toml

Option C — pip install from requirements.txt (legacy)

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Note on Windows: pyembree and embreex may fail to compile. If so, install them via conda instead:

conda install -c conda-forge pyembree embreex

All other dependencies (Open3D, pyvista, matplotlib, …) have pre-built wheels for Windows.

---

Quick Start

1. Launch the GUI

beamontarget              # if installed via pip install -e .
# or
python -m beamontarget.gui.sim_gui

The GUI has five tabs:

Tab	Purpose
General	ParaView path, number of CPU cores, particles per beamlet, energy.
Geometry	Add / edit / remove geometry folders and their STL files.
Particles	Select particle source directory and .bl files.
Output	Output directory, save options, CSV result comparison charts, VTP data extraction.
Run	Save configuration, launch simulation, view live log output.

2. The two shipped examples

The repository ships two complete examples, so a fresh checkout runs without any input of your own.

Config	Geometry	Beam	Runtime
config.json (default)	GEOMETRY_EXAMPLE/ — a cube and a sphere	BEAM_CONFIG_EXAMPLE/example_simple.bl — 50 random beamlets, 50 kW	seconds
config_beamline_example.json	NEU/, RID/, CAL/ — neutral beam injector components	BEAM_CONFIG_BEAMLINE/example_bl_config.bl — 1280 beamlets at 870 keV	minutes

beamontarget-run                                      # the simple example
beamontarget-run -i config_beamline_example.json      # the beamline example

Run both from the repository root. Relative paths in a config are resolved against the project folder, so launching from elsewhere will not find the geometry.

The simple example

GEOMETRY_EXAMPLE/ holds a 1 m cube and a sphere of radius 0.75 m, side by side in y with a gap between them. 50 beamlets are scattered at random across a source plane upstream and travel along +x, so roughly a third strike the cube, a third the sphere, and a third pass between. The beam carries exactly 1 kW per beamlet, 50 kW in total, of which about 37 kW lands on the two bodies.

It finishes in a few seconds and is the fastest way to confirm your installation works. See GEOMETRY_EXAMPLE/README.md and BEAM_CONFIG_EXAMPLE/README.md.

The beamline example

Folder	Contents	Description
NEU/	NEU1.stl - NEU5.stl	Five rectangular slabs forming a channel, x = 1.900-4.900 m
RID/	RID1.stl - RID5.stl	Five rectangular slabs, x = 5.400-7.200 m
CAL/	BENCHMARK.stl	A single flat plane at x = 7.750 m, 0.800 x 1.700 m

These are generic blocks and planes, not a model of any particular machine. The beam is a nominal unsteered configuration of 1280 parallel beamlets on a 20 x 64 grid at 870 keV, 3 mrad core divergence, inclined 49.22 mrad downward. Each folder has a README.md with dimensions and tessellation; note in particular that the deflecting field region in config_beamline_example.json is aligned to the RID panel extent.

3. Using your own geometry and beam

• Create folders (e.g. MY_GEOMETRY/, TARGETS/) and place .stl files inside. In the Geometry tab, add each folder and configure its scale and mesh refinement settings.

• Create a directory with one or more .bl files — space-separated text with columns:

  # CenterX CenterY CenterZ DirX DirY DirZ Mass_kg Charge_e CurrentDensity_A_m2 SigmaY_m DeltaY_rad SigmaZ_m DeltaZ_rad HaloFraction DeltaHY_rad DeltaHZ_rad
  0 0 0 1 0 0 1.67e-27 1 1.0 0.005 0.005 0.005 0.005 0.1 0.01 0.01
  

  Select it in the Particles tab, or set PARTICLE_SOURCE_DIR. Every .bl file in that directory becomes a separate simulation run.

  BEAM_CONFIG_BEAMLINE/README.md documents every column.

4. Run the Simulation

Click ▶ Run in the Run tab, or from the command line:

python -m beamontarget.workflows.run_simulation

Results are saved as .vtp files in the output directory (default OUTPUT/), organised by .bl filename.

5. View Results

• Built-in viewer: Use the 3D viewer buttons in the GUI (Geometry / Results / All / Sources). The viewer supports rotation (left-drag), zoom (scroll), and pan (right-drag).
• ParaView: Open the .vtp files directly in ParaView, or use the GUI's ParaView integration buttons.
• CSV comparison: In the Output tab, load summary CSV files and compare peak power density / deposited power across runs with interactive bar charts.
• Data extraction: Use the Extract results data button to export VTP cell data (coordinates, area, power, power load) to CSV.

---

Command-Line Usage

# Run the default config.json (the simple cube-and-sphere example)
beamontarget-run

# Run a different configuration
beamontarget-run -i config_beamline_example.json

# Preview geometry and source positions (needs a display)
beamontarget-run --view-setup

# Preview geometry only
beamontarget-run --view-setup geo

beamontarget-run is equivalent to python -m beamontarget.workflows.run_simulation. The only options are -i/--input-config and --view-setup.

Run from the repository root: relative paths in a config are resolved against the project folder, not the current directory.

Results are written to <DETAILED_OUTPUT_DIR>/<beam file name>/, so the two shipped examples land in OUTPUT/example_simple/ and OUTPUT/example_bl_config/ respectively.

Running without geometry

Geometry is optional. If no .stl files are found, the run continues with an empty scene and particles are tracked through free space -- nothing is struck, so no power is deposited.

This is most useful with "TRACKING_MODE": "em_track_then_bvh", where the electromagnetic integration and the pre-run analysis (Larmor radius, reaction evolution) are the point and targets are irrelevant. To study how a beam drifts and disperses in a field before adding any hardware, point GEOMETRY_FOLDERS at an empty folder and configure EXTERNAL_FIELD as usual.

Manual Smoothing

python -m beamontarget.io.batch_smoother -i OUTPUT/my_beam_run

VTP Data Extraction (CLI)

python -m beamontarget.io.extract_mesh_data input.vtp -o output.csv

---

Dependencies

All dependencies are declared in pyproject.toml and installed automatically. Key packages:

Package	Purpose
numpy	Numerical arrays
trimesh + pyembree / embreex	Mesh loading and ray tracing
pyvista	VTP file I/O
open3d ≥ 0.17	GPU-accelerated 3D rendering (off-screen)
matplotlib	Bar-chart plotting in GUI
Pillow	Image processing for viewer overlay
pandas	CSV / DataFrame handling
scipy	Smoothing algorithms
joblib	Parallel processing
tqdm	Progress bars

---

Authors and attribution

Copyright © 2025-2026 ITER Organization, Route de Vinon-sur-Verdon, CS 90 046, 13067 St Paul Lez Durance Cedex, France.

BeamOnTarget was developed at the ITER Organization by Carlo Poggi, with contributions from David Atteln (HTWK Leipzig). See AUTHORS for the full list and a breakdown of contributions.

The views and opinions expressed herein do not necessarily reflect those of the ITER Organization.

---

Citing BeamOnTarget

If you use BeamOnTarget in published work, please cite it using the metadata in CITATION.cff. GitHub renders this as a "Cite this repository" button in the sidebar.

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening an issue or a pull request.

---

License

BeamOnTarget is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License, version 3 (LGPL-3.0-only) as published by the Free Software Foundation.

BeamOnTarget is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

• LICENSE — the full text of the GNU LGPL v3.
• GPLv3.txt — the full text of the GNU GPL v3, whose terms the LGPL v3 incorporates by reference.

The LGPL was chosen, rather than the GPL, so that BeamOnTarget can be used as a component of larger integrated modelling frameworks released under other licences.