Glossary
Quick reference for domain-specific terms that appear across the codebase and documentation.
Architecture Terms
Section titled “Architecture Terms”Project JSON : The canonical data format exchanged between the frontend editor and the backend/converter. Contains all simulation parameters: beam, geometry, materials, detectors, scoring, and physics settings.
Parser
: A converter class that translates project JSON into a specific simulator’s input format. Each engine has its own parser (e.g., ShieldhitParser, FlukaParser).
Direct Execution : Running simulations on the backend server itself, using Celery workers. Faster for small jobs.
Batch Execution : Submitting simulations to an HPC cluster (e.g., PLGrid/Prometheus) via SSH and Slurm. For large-scale computations.
Celery Worker : A background process that executes simulation tasks. YAPTIDE uses two types: simulation workers (run the simulator binary) and helper workers (poll batch job status).
Frontend Terms
Section titled “Frontend Terms”YaptideEditor
: The central TypeScript class that manages the 3D scene, all object managers, and the serialization state. Extends Three.js EventDispatcher.
Signal : A Three.js event used for communication between editor components. Similar to an event emitter pattern.
Command : An undoable action in the editor (add object, change property, etc.). All mutations go through the command system to support undo/redo.
ServiceTree : The top-level React component tree that provides all context providers (auth, simulation, backend connection) to the application.
Pyodide : A Python runtime compiled to WebAssembly. Used to run the YAPTIDE converter directly in the browser without a backend.
Simulation Engines
Section titled “Simulation Engines”SHIELD-HIT12A : A Monte Carlo particle transport code specializing in ion beam therapy. The most complete engine in YAPTIDE.
FLUKA : A general-purpose Monte Carlo code for particle transport developed at CERN. Uses a card-based input format.
Geant4 : A toolkit for simulating particle passage through matter, developed at CERN. Uses GDML for geometry and macro files for configuration.
TOPAS : A Monte Carlo tool built on Geant4, focused on proton therapy. Experimental support in YAPTIDE.
Infrastructure Terms
Section titled “Infrastructure Terms”Poetry
: Python dependency manager used by the backend and converter. Replaces pip + requirements.txt with pyproject.toml + poetry.lock.
Keycloak : An open-source identity provider. YAPTIDE uses it for SSO authentication, especially for PLGrid HPC access.
PLGrid : Polish national computing infrastructure. YAPTIDE can submit batch simulations to PLGrid clusters via Slurm.
Slurm : A workload manager for HPC clusters. YAPTIDE generates Slurm job scripts for batch execution.
GDML : Geometry Description Markup Language — an XML schema used by Geant4 for geometry definitions.
Simulation Concepts
Section titled “Simulation Concepts”CSG (Constructive Solid Geometry) : A modeling technique that builds complex shapes by combining simple primitives (boxes, cylinders, spheres) using boolean operations — union, subtraction, and intersection.
Zone : A region of space defined by CSG operations on figures. Each zone is assigned a material. In FLUKA, zones are called “regions.”
Figure : A geometric primitive (box, cylinder, sphere) with position and rotation. Figures are the building blocks of zones.
Black-Hole Boundary : A surrounding zone filled with “black hole” material that absorbs all particles exiting the simulation geometry. Auto-generated by the converter.
Primary / Primaries : The initial particles in a simulation (e.g. protons, carbon ions). The number of primaries determines statistical accuracy.
Estimator / Detector : A scoring mesh that tallies physical quantities (dose, fluence, LET) in a defined region of space. Types include mesh (Cartesian grid), cylindrical, and zone-based.
Scoring : The process of recording (tallying) physical quantities during particle transport. A scoring definition ties a quantity to a detector.
Page / Output : A single scored quantity on a single detector. One simulation can produce multiple pages of results.
LET (Linear Energy Transfer) : Energy deposited by a charged particle per unit path length. Typically measured in keV/µm.
Fluence : Number of particles passing through a unit area. Measured in particles/cm².
Dose : Energy deposited per unit mass. Measured in Gray (Gy).