g4new

Easiest way to get a fully working Geant4 project ready to run.

Quick Start

pip install g4new
g4new init myproject

Requirements

g4new init checks these are installed before generating a project (unless skipped):

• CMake >= 3.16.0
• Geant4 >= 10.7.0

g4new init options

g4new init PROJECT_NAME [OPTIONS]

Option	Default	Description
--particle TEXT	e-	Primary particle fired by the generated gun
--energy TEXT	6 MeV	Primary energy, e.g. 6 MeV, 1.5 GeV (value + a Geant4 unit: eV/keV/MeV/GeV/TeV)
--physics TEXT	FTFP_BERT	Geant4 reference physics list
--skip-cmake		Skip the CMake dependency check
--skip-geant4		Skip the Geant4 dependency check
--override		Overwrite the project directory if it already exists

Generated project

g4new init myproject produces a complete, buildable application:

myproject/
  CMakeLists.txt
  macros/
    vis.mac
    run.mac
  include/
    geometry/DetectorConstruction.h
    physics/PhysicsList.h
    action/PrimaryGeneratorAction.h
    action/ActionInitialization.h
    action/RunAction.h
    action/EventAction.h
    action/SteppingAction.h
    cli/RunConfig.h
    messenger/AppMessenger.h
  src/
    main.cpp
    geometry/DetectorConstruction.cpp
    physics/PhysicsList.cpp
    action/PrimaryGeneratorAction.cpp
    action/ActionInitialization.cpp
    action/RunAction.cpp
    action/EventAction.cpp
    action/SteppingAction.cpp
    cli/RunConfig.cpp
    messenger/AppMessenger.cpp
  README.md
  .gitignore

The scaffold is a working example that scores energy deposited in a central water Target volume — extend the geometry, physics, and scoring from there. The modernized CMakeLists.txt links Geant4's imported targets with the ui_all vis_all components, builds against C++17, and copies macros/ next to the executable.

Category	Class	Role
geometry	DetectorConstruction	Builds a world containing a central water Target volume
physics	PhysicsList	Thin subclass of the selected reference physics list (FTFP_BERT by default, set via --physics)
action	PrimaryGeneratorAction	Fires the chosen primary particle (--particle, default e-) along +z at the chosen energy (--energy, default 6 MeV) via G4ParticleGun
action	ActionInitialization	Registers PrimaryGeneratorAction, RunAction, EventAction, and SteppingAction
action	RunAction	Opens the G4AnalysisManager output at BeginOfRunAction and writes it at EndOfRunAction
action	EventAction	Accumulates the per-event energy deposited in the Target and fills the analysis output
action	SteppingAction	Adds each step's energy deposit inside the Target to the current event
cli	RunConfig	Hand-rolled command-line parser for the generated executable
messenger	AppMessenger	Hierarchical Geant4 UI command tree (/app/...), extend it with your own commands

main.cpp wires all of these together: it parses the command line via RunConfig, constructs an AppMessenger, creates a G4RunManager (G4RunManagerType::Default, so it runs multithreaded whenever the Geant4 build supports it), registers DetectorConstruction/PhysicsList/ActionInitialization, then either runs the given macro in batch mode or opens the interactive OpenGL viewer.

Running the generated executable

Run with no arguments to open an interactive OpenGL viewer, which executes macros/vis.mac:

./build/myproject

Run headless/batch by passing a macro:

./build/myproject --mac macros/run.mac

Option	Description
--mac <file>	Run the given macro in batch mode instead of opening the interactive viewer
--verbose	Parsed and stored, no behavior wired up yet — read it once you add your own logging
--out <file>	Parsed and stored, no behavior wired up yet — read it once you add your own output
--help, -h	Show usage

The generated project also exposes a /app/setVerbose Geant4 UI command (via AppMessenger) that you can call from a macro or interactive session — add your own commands under /app/ following the same pattern.