Geometry Configuration

The detector geometry is configured through JSON files, making it easy to modify without recompiling the code. JSON files can be created and edited with the companion Geant4 Geometry Editor.

Supported Volume Types

The geometry parser supports the following solid types:

• Primitive shapes — box, cylinder, sphere, ellipsoid, torus, trapezoid, polycone

• Assemblies — groups of volumes placed together via G4AssemblyVolume / MakeImprint, with support for multiple placements and nested hierarchies

• Boolean solids — union, subtraction, and intersection of primitive shapes via G4UnionSolid / G4SubtractionSolid; components are listed in a components array with a boolean_operation field per component

Configuration Files

A single JSON file contains everything needed for a simulation:

1. world — the top-level world volume (always a box)

2. volumes — all daughter volumes, assemblies, and boolean solids

3. materials — material definitions (NIST, element-based, or compounds)

JSON Format

The geometry configuration uses a hierarchical JSON format with placements arrays to support multiple placements of the same volume definition:

{
    "world": {
        "name": "World",
        "type": "box",
        "material": "G4_AIR",
        "dimensions": { "x": 2000, "y": 2000, "z": 2000 },
        "placements": [
            { "x": 0, "y": 0, "z": 0, "rotation": { "x": 0, "y": 0, "z": 0 } }
        ]
    },
    "volumes": [
        {
            "name": "Detector",
            "g4name": "Detector",
            "type": "cylinder",
            "material": "G4_Si",
            "dimensions": { "radius": 50, "height": 100 },
            "placements": [
                {
                    "name": "Detector",
                    "g4name": "Detector",
                    "x": 0, "y": 0, "z": 0,
                    "rotation": { "x": 0, "y": 0, "z": 0 },
                    "parent": "World"
                }
            ],
            "visible": true,
            "hitsCollectionName": "MyHitsCollection"
        }
    ],
    "materials": {
        "G4_AIR": { "type": "nist", "density": 0.00120479, "density_unit": "g/cm3" },
        "G4_Si":  { "type": "nist", "density": 2.33, "density_unit": "g/cm3" }
    }
}

Note

All dimensions are in mm and all angles in radians in the current JSON format produced by the Geometry Editor. The parser also accepts explicit unit fields ("mm", "cm", "m", "deg", "rad").

Boolean Solid Example

A boolean (union) solid with a box and a subtracted cylinder:

{
    "name": "MyUnion",
    "g4name": "MyUnion",
    "type": "union",
    "material": "G4_AIR",
    "placements": [
        { "name": "MyUnion", "g4name": "MyUnion",
          "x": 0, "y": 0, "z": 0,
          "rotation": { "x": 0, "y": 0, "z": 0 },
          "parent": "World" }
    ],
    "components": [
        {
            "name": "BaseBox", "type": "box",
            "dimensions": { "x": 100, "y": 100, "z": 100 },
            "placements": [{ "x": 0, "y": 0, "z": 0, "rotation": { "x": 0, "y": 0, "z": 0 } }],
            "boolean_operation": "union"
        },
        {
            "name": "SubCyl", "type": "cylinder",
            "dimensions": { "radius": 30, "height": 120 },
            "placements": [{ "x": 0, "y": 0, "z": 0, "rotation": { "x": 0, "y": 0, "z": 0 } }],
            "boolean_operation": "subtract"
        }
    ]
}

Units

All dimensions in the geometry configuration can specify units:

• Length units: “mm”, “cm”, “m” (default is “mm” if not specified)

• Angle units: “deg”, “rad” (default is “deg” if not specified)

For shape-specific dimensions (like radius, height), you can specify the unit in two ways:

1. As a property of the vector (for position, size):

   "position": {
       "x": 0.0,
       "y": 0.0,
       "z": 0.0,
       "unit": "cm"
   }
   

2. As a direct property of the volume (for radius, height, etc.):

   "radius": 5.0,
   "height": 10.0,
   "unit": "cm"
   

Rotations

Rotations are specified in the following format:

"rotation": {
    "x": 30.0,
    "y": 0.0,
    "z": 45.0,
    "unit": "deg"
}

Rotations are applied in the Geant4 sequence:

1. First rotation around X axis

2. Then rotation around the new Y axis

3. Finally rotation around the new Z axis

Cylinder Orientation

Cylinders in Geant4 are created with:

• The circular face in the X-Y plane

• The height extending along the Z-axis

This means that rotations will behave as follows:

• X rotation: Tilts the cylinder around the X axis

• Y rotation: Tilts the cylinder around the Y axis

• Z rotation: Rotates the cylinder around its central axis (Z)

For detailed API documentation of the geometry parser, see API Reference.