Gsim Geometry

The detector geometry used in Gsim is controlled by the GEO tables stored in RATDB. Each piece of the detector is represented by a GEO table that gives the name of the element, the shape, position, material, and color (for visualization purposes). This allows simple changes to the detector configuration to be made without having to edit the RAT source code.

Unlike other RATDB files, geometry files end in .geo rather than .ratdb. Because of this, when RAT starts, no GEO tables are loaded into memory. Instead, the program waits until the /run/initialize command is issued, and then loads the geometry file listed in the DETECTOR.geo_file field. It also optionally loads the geometry file given in the DETECTOR.veto_file field if it exists. Once these files have been loaded into the database, the detector is constructed from all of the GEO tables currently in memory.

Customizing the Geometry in a Macro File

There are several ways to customize the detector geometry:

Change DETECTOR.geo_file

If you want to make drastic changes to the detector, you should start by copying one of the geometry files (like simple.geo) and editing it. Then you can add a command like:

/rat/db/set DETECTOR geo_file "mydetector.geo"

to the top of your macro (before /run/initialize). None of the default geometry will be loaded, just your new file. Note that this file should be placed in the data directory.

Load an additional geometry file

Since geometry files are just RATDB files, you can load additional GEO tables using a command like:

/rat/db/load "calibration_source.geo"

This file can contain either completely new detector pieces, or it can override parts of the default geometry. Make sure you set the validity ranges on the tables to put them in the user plane, otherwise they will be overwritten by the defaults when they are loaded. Any extra GEO tables you create will be built right along with the defaults when /run/initialize is executed.

Alter individual fields

For a very small change, like changing just a few numbers, you can use the commands:

/rat/db/set GEO[av] r_max 2800.0
/rat/db/set GEO[scint] r_max 2700.0

Unfortunately, you cannot change array fields using the set command yet.

GEO Table Fields

GEO tables can contain a wide variety of fields to control the properties of the volume. The common fields shared by all tables:

Field Type Description
index string Name of the volume. To conform with RATDB standards, it should follow identifier conventions (no spaces).
mother string Name of the mother volume. The mother volume should fully contain this volume. The world volume has the mother “”.
enable int (optional) If set to zero, this volume is skipped and not constructed.
type string Shape of this volume, see below for list.
sensitive_detector string (optional) Name of sensitive detector if this volume should register hits. Limited to ‘’/mydet/pmt/inner’’ and ‘’/mydet/veto/genericchamber’‘
Allowed types:
  • box - Rectangular solid
  • tube - Cylindrical solid (or section over limited phi range)
  • ptube - Cylindrical solid with circular perforations along z cut out
  • sphere - Spherical solid (or section over limited theta and phi range)
  • psphere - Spherical solid with circular perforations radially cut out
  • revolve - Solid of revolution defined by (r_max, r_min, z)
  • AV - Generic spherical acrylic vessel
  • tubearray - Array of tubes
  • lgarray - Array of tubes where one end has the PMT face cut out
  • pmtarray - Array of PMTs
  • waterboxarray - Array of standard cubitainer water boxes
  • extpolyarray - Array of extruded polygonal solids
  • bubble - Collection of bubbles

All types except “pmtarray”, “waterboxarray”, and “bubble” have these additional fields:

Field Type Description
material string Material filling this volume. See the MaterialList for details.
color float[3|4] (optional) Color to be used for this element in visualization. Either RGB or RGBA (A=alpha transparancy) components ranging from 0.0 to 1.0.
invisible int If set to 1, mark this volume as invisible during visualization
position float[3] (optional) X, Y, Z (mm) components of the position of the volume center, ‘in coordinate system of the mother volume’. Default position is the center.
rotation float[3] (optional) X, Y, Z axis rotations (deg) of element about its center. Rotations are applied in X, Y, Z order. Default is no rotation.
replicas int (optional) Replicate this volume N times inside the mother (position and rotation are ignored if this is set)
replica_axis string (optional) Axis along which to replicate volume: x, y, z
replica_spacing float (optional) Distance (mm) between replicas

Box Fields:

Field Type Description
size float[3] X, Y, Z half-lengths (mm) of box (perpendicular distance from center to each face)

Tube Fields:

Field Type Description
r_max float Outer radius of tube (mm)
r_min float (optional) Inner radius of tube (mm) Default is 0.0 (solid)
size_z float Half-height of tube (mm)
phi_start float (optional) Angle (deg) where tube segment starts. Default is 0.0
phi_delta float (optional) Angle span (deg) of tube segment. Default is 360.0

Sphere Fields:

Field Type Description
r_max float Outer radius of sphere (mm)
r_min float Inner radius of sphere (mm) Default is 0.0 (solid)
theta_start float (optional) Polar angle (deg) where sphere segment starts. Default is 0.0
theta_delta float (optional) Polar angle span (deg) of sphere segment. Default is 180.0
phi_start float (optional) Azimuthal angle (deg) where sphere segment starts. Default is 0.0
phi_delta float (optional) Azimuthal angle span (deg) of sphere segment. Default is 360.0

PMTArray Fields:

Field Type Description
pmt_model string Serves as the index for PMT, PMTCHARGE, and PMTTRANSIT tables giving the geometry, charge response, and time response models.
pos_table string Specifies the PMTINFO table to use when placing these PMTs (see PMT Simulation)
start_idx int (optional) Index to start building PMTs in the PMTINFO table specified (inclusive, defaults to 0)
end_idx int (optional) Index to stop building PMTs in the PMTINFO table specified (inclusive, defaults to length-1)
orientation string Method of determining PMT direction. “point” will aim all PMTs at a point in space. “manual” requires that the position table also contain dir_x, dir_y, and dir_z fields which define the direction vector for each PMT.
orient_point float[3] (optional) Point (mm) in mother volume to aim all PMTs toward.
rescale_radius float (optional) Assumes all PMTs are spherically arranged around the center of the mother volume and rescales their positions to a particular radius. By default, no rescaling is done.

Creating a parameterized geometry

Using a DetectorFactory one can build a DB defined geometry on the fly (less useful), or modify a normal DB defined geometry template (more useful) before the geometry itself is built. Using only .geo files there is no nice way to have a property of a geometry component defined as a formula (a function of other geometry parameters), and no nice way to algorithmically define components of a scalable geometry, e.g. PMT positions for various photocathode coverage fractions.

The DetectorFactory to use is specified by name in the DETECTOR table under the field detector_factory and supersedes the geo_file field if used. If no DetectorFactory is specified, the geo_file specified is loaded as described above. A DetectorFactory should define tables in the DB in the same way a .geo file would and make use of GeoFactory components.

/rat/db/set DETECTOR experiment "Watchman"
/rat/db/set DETECTOR geo_file "Watchman/Watchman.geo"


/rat/db/set DETECTOR experiment "Watchman"
/rat/db/set DETECTOR detector_factory "Watchman"

Example usage would be to load a normal (statically defined) .geo file into the DB and modify it as necessary for the dynamic functionality. See the WatchmanDetectorFactor for example use.