External Geometry Formats
Currently, three formats are supported by BDSIM. GDML is recommended as this is thoroughly supported by Geant4 and the geometry extent can be automatically determined.
More can be added in collaboration with the BDSIM development team - please see Feature Request.
Warning
The Mokka format is not currently developed or maintained in BDSIM.
Warning
The GGMAD format has been deprecated and removed from BDSIM as of V1.7.0 as it was not maintained and was very hard to maintain as it was old code.
GDML
GDML (Geometry Description Markup Language) is an XML schema for detector description. To use Geant4 and BDSIM needs to be built with GDML usage on (default true). For more information please refer to the GDML website and manual.
This format is widely supported and other geometry software may be able to export geometry in GDML format.
See GDML Preprocessing for a relevant discussion about how BDSIM handles GDML files.
GDML Preparation
A Python package pyg4ometry has been created to aid preparation, visualisation and overlap checking of GDML geometry. Please see Geometry Preparation for more details.
This package is used for many of the examples included with BDSIM and the Python scripts are included with the examples.
GDML Colours
BDSIM can read auxiliary information tags in GDML attached to logical volumes. The following
information is optionally interpreted if available in the <volume>
tag:
<auxiliary auxtype="colour" auxvalue="0.39215686274509803 0.5490196078431373 0.596078431372549 1"/>
The auxvalue
should be a white-space separated list of 4 values from 0 to 1 for
RGBA values.
An example can be found in examples/features/geometry/9_gdml/14_gdml_colours.gmad
.
Note
This is not a Geant4 standard and is custom information the user must supply in their GDML file and therefore it is only convention we agree on for the tag and the contents.
Mokka
Warning
The Mokka format is not currently developed or maintained in BDSIM.
This format is currently in the form of a dumped MySQL database format. Note that throughout any of the Mokka files, a # may be used to represent a commented line. There are three key stages, which are detailed in the following sections, that are required for setting up the Mokka geometry:
Describing the geometry
An object must be described by creating a MySQL file containing commands that would typically be used for uploading/creating a database and a corresponding new table into a MySQL database. BDSIM supports only a few such commands - specifically the CREATE TABLE and INSERT INTO commands. When writing a table to describe a solid, there are some parameters that are common to all solid types (such as NAME and MATERIAL) and some that are more specific (such as those relating to radii for cone objects). A full list of the standard and specific table parameters, as well as some basic examples, are given below with each solid type. All files containing geometry descriptions must have the following database creation commands at the top of the file:
DROP DATABASE IF EXISTS DATABASE_NAME;
CREATE DATABASE DATABASE_NAME;
USE DATABASE_NAME;
A table must be created to allow for the insertion of the geometry descriptions. A table is created using the following MySQL compliant commands:
CREATE TABLE TABLE-NAME_GEOMETRY-TYPE (
TABLE-PARAMETER VARIABLE-TYPE,
TABLE-PARAMETER VARIABLE-TYPE,
TABLE-PARAMETER VARIABLE-TYPE
);
Once a table has been created, values must be entered into it in order to define the solids and position them. The insertion command must appear after the table creation and must be followed by the MySQL compliant table insertion command:
INSERT INTO TABLE-NAME_GEOMETRY-TYPE VALUES(value1, value2, "char-value", ...);
The values must be inserted in the same order, as their corresponding parameter types are described in the table creation. Note that ALL length types must be specified in mm and that ALL angles must be in radians.
An example of two simple boxes with no visual attribute set is shown below. The first box is a simple vacuum cube, whilst the second is an iron box with length x = 10mm, length y = 150mm, length z = 50mm, positioned at x=1m, y=0, z=0.5m and with zero rotation:
CREATE TABLE mytable_BOX (
NAME VARCHAR(32),
MATERIAL VARCHAR(32),
LENGTHX DOUBLE(10,3),
LENGTHY DOUBLE(10,3),
LENGTHZ DOUBLE(10,3),
POSX DOUBLE(10,3),
POSY DOUBLE(10,3),
POSZ DOUBLE(10,3),
ROTPSI DOUBLE(10,3),
ROTTHETA DOUBLE(10,3),
ROTPHI DOUBLE(10,3)
);
INSERT INTO mytable_BOX VALUES("a_box","vacuum", 50.0, 50.0, 50.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
INSERT INTO mytable_BOX VALUES("another_box","iron", 10.0, 150.0, 50.0, 1000.0, 0.0, 500.0, 0.0, 0.0, 0.0);
Further examples of the Mokka geometry implementation can be found in the examples/features/geometry/Mokka/General directory. See the common table parameters and solid type sections below for more information on the table parameters available for use.
Common Table Parameters
The following is a list of table parameters that are common to all solid types, either as an optional or mandatory parameter:
- NAMEVariable type: VARCHAR(32)Optional parameterIf supplied, then the Geant4 LogicalVolume associated with the solid will be labelled with this name. The default is set to be the table’s name plus an automatically assigned volume number.
- MATERIALVariable type: VARCHAR(32)Optional parameterIf supplied, then the volume will be created with this material type - note that the material must be given as a character string inside double quotation marks(“). The default material is set as Vacuum.
- PARENTNAMEVariable type: VARCHAR(32)Optional parameterIf supplied, then the volume will be placed as a daughter volume to the object with ID equal to PARENTNAME. The default parent is set to be the Component Volume. Note that if PARENTID is set to the Component Volume, then POSZ will be defined with respect to the start of the object. Else POSZ will be defined with respect to the centre of the parent object.
- INHERITSTYLEVariable type: VARCHAR(32)Optional parameter to be used with PARENTNAME.If set to “SUBTRACT“ then instead of placing the volume within the parent volume as an inherited object, it will be subtracted from the parent volume in a Boolean solid operation. The default for this value is set to ““ - which sets to the usual mother/daughter volume inheritance.
- ALIGNINVariable type: INTEGER(11)Optional parameterIf set to 1 then the placement of components will be rotated and translated such that the incoming beamline will pass through the z-axis of this object. The default is set to zero.
- ALIGNOUTVariable type: INTEGER(11)Optional parameterIf set to 1 then the placement of the next beamline component will be rotated and translated such that the outgoing beamline will pass through the z-axis of this object. The default is set to zero.
- SETSENSITIVEVariable type: INTEGER(11)Optional parameterIf set to 1 then the object will be set up to register energy depositions made within it and also record the z-position at which this deposition occurs. This information will be saved in the ELoss Histogram if using ROOT output. The default is set to zero.
- MAGTYPEVariable type: VARCHAR(32)Optional parameterIf supplied, then the object will be set up to produce the appropriate magnetic field using the supplied K1 or K2 table parameter values . Three magnet types are available - “QUAD”, “SEXT” and “OCT”. The default is set to no magnet type. Note that if MAGTYPE is set to a value whilst K1/K2/K3 are not set, then no magnetic field will be implemented.
- K1Variable type: DOUBLE(10,3)Optional parameterIf set to a value other than zero, in conjunction with MAGTYPE set to “QUAD”, then a quadrupole field with this K1 value will be set up within the object. Default is set to zero.
- K2Variable type: DOUBLE(10,3)Optional parameterIf set to a value other than zero, in conjunction with MAGTYPE set to “SEXT”, then a sextupole field with this K2 value will be set up within the object. Default is set to zero.
- K3Variable type: DOUBLE(10,3)Optional parameterIf set to a value other than zero, in conjunction with MAGTYPE set to “OCT”, then a sextupole field with this K3 value will be set up within the object. Default is set to zero.
- POSX, POSY, POSZVariable type: DOUBLE(10,3)Required parametersThey form the position in mm used to place the object in the component volume. POSX and POSY are defined with respect to the centre of the component volume and with respect to the component volume’s rotation. POSZ is defined with respect to the start of the component volume. Note that if the object is being placed inside another volume using PARENTNAME then the position will refer to the centre of the parent object.
- ROTPSI, ROTTHETA, ROTPHIVariable type: DOUBLE(10,3)Optional parametersThese are the Euler angles in radians used to rotate the object before it is placed. The default is set to zero for each angle.
- RED, BLUE, GREENVariable type: DOUBLE(10,3)Optional parametersThey are the RGB colour components assigned to the object and should be a value between 0 and 1. The default is set to zero for each colour.
- VISATTVariable type: VARCHAR(32)Optional parameterThis is the visual state setting for the object. Setting this to “W” results in a wireframe display of the object. “S” produces a shaded solid and “I” leaves the object invisible. The default is set to be solid.
- FIELDX, FIELDY, FIELDZVariable type: DOUBLE(10,3)Optional parametersThey can be used to apply a uniform field to any volume, with default units of Tesla. Note that if there is a solenoid field present throughout the entire element, then this uniform field will act in addition to the solenoid field.
‘Box’ Solid Types
Append _BOX to the table name in order to make use of the G4Box solid type. The following table parameters are specific to the box solid:
- LENGTHX, LENGTHY, LENGTHZVariable type: DOUBLE(10,3)Required parametersThere values will be used to specify the box’s dimensions.
’Trapezoid’ Solid Types
Append _TRAP to the table name in order to make use of the G4Trd solid type - which is defined as a trapezoid with the X and Y dimensions varying along z-functions. The following table parameters are specific to the trapezoid solid:
- LENGTHXPLUSVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the x-extent of the box’s dimensions at the surface positioned at +dz.
- LENGTHXPMINUSVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the x-extent of the box’s dimensions at the surface positioned at -dz.
- LENGTHYPLUSVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the y-extent of the box’s dimensions at the surface positioned at +dz.
- LENGTHYPMINUSVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the y-extent of the box’s dimensions at the surface positioned at -dz.
- LENGTHZVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the z-extent of the box’s dimensions.
’Cone’ Solid Types
Append _CONE to the table name in order to make use of the G4Cons solid type. The following table parameters are specific to the cone solid:
- LENGTHVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the z-extent of the cone’s dimensions.
- RINNERSTARTVariable type: DOUBLE(10,3)Optional parameterIf set, this value will be used to specify the inner radius of the start of the cone. The default value is zero.
- RINNERENDVariable type: DOUBLE(10,3)Optional parameterIf set, this value will be used to specify the inner radius of the end of the cone. The default value is zero.
- ROUTERSTARTVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the outer radius of the start of the cone.
- ROUTERENDVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the outer radius of the end of the cone.
- STARTPHIVariable type: DOUBLE(10,3)Optional parameterIf set, this value will be used to specify the starting angle of the cone. The default value is zero.
- DELTAPHIVariable type: DOUBLE(10,3)Optional parameterIf set, this value will be used to specify the delta angle of the cone. The default value is 2*pi.
’Torus’ Solid Types
Append _TORUS to the table name in order to make use of the G4Torus solid type. The following table parameters are specific to the torus solid:
- RINNERVariable type: DOUBLE(10,3)Optional parameterIf set, this value will be used to specify the inner radius of the torus tube. The default value is zero.
- ROUTERVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the outer radius of the torus tube.
- RSWEPTVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the swept radius of the torus. It is defined as being the distance from the centre of the torus ring to the centre of the torus tube. For this reason, this value should not be set to less than ROUTER.
- STARTPHIVariable type: DOUBLE(10,3)Optional parameterIf set, this value will be used to specify the starting angle of the torus. The default value is zero.
- DELTAPHIVariable type: DOUBLE(10,3)Optional parameterIf set, this value will be used to specify the delta swept angle of the torus. The default value is 2*pi.
’Polycone’ Solid Types
Append _POLYCONE to the table name in order to make use of the G4Polycone solid type. The following table parameters are specific to the polycone solid:
- NZPLANESVariable type: INTEGER(11)Required parameterThis value will be used to specify the number of z-planes to be used in the polycone. This value must be set to greater than 1.
- PLANEPOS1, PLANEPOS2, …, PLANEPOSNVariable type: DOUBLE(10,3)Required parametersThese values will be used to specify the z-position of the corresponding z-plane of the polycone. There should be as many PLANEPOS parameters set as the number of z-planes. For example, three z-planes will require that PLANEPOS1, PLANEPOS2, and PLANEPOS3 are all set up.
- RINNER1, RINNER2, …, RINNERNVariable type: DOUBLE(10,3)Required parametersThese values will be used to specify the inner radius of the corresponding z-plane of the polycone. There should be as many RINNER parameters set as the number of z-planes. For example, three z-planes will require that RINNER1, RINNER2, and RINNER3 are all set up.
- ROUTER1, ROUTER2, …, ROUTERNVariable type: DOUBLE(10,3)Required parametersThese values will be used to specify the outer radius of the corresponding z-plane of the polycone. There should be as many ROUTER parameters set as the number of z-planes. For example, 3 z-planes will require that ROUTER1, ROUTER2, and ROUTER3 are all set up.
- STARTPHIVariable type: DOUBLE(10,3)Optional parameterIf set, this value will be used to specify the starting angle of the polycone. The default value is zero.
- DELTAPHIVariable type: DOUBLE(10,3)Optional parameterIf set, this value will be used to specify the delta angle of the polycone. The default value is 2*pi.
’Elliptical Cone’ Solid Types
Append _ELLIPTICALCONE to the table name in order to make use of the G4Ellipticalcone solid type. The following table parameters are specific to the elliptical cone solid:
- XSEMIAXISVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the Semiaxis in X.
- YSEMIAXISVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the Semiaxis in Y.
- LENGTHZVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the height of the elliptical cone.
- ZCUTVariable type: DOUBLE(10,3)Required parameterThis value will be used to specify the upper cut plane level.
Note that the above parameters are used to define an elliptical cone with the following parametric equations (in the usual Geant4 way):
X = XSEMIAXIS * (LENGTHZ - u) / u * Cos(v)
Y = YSEMIAXIS * (LENGTHZ - u) / u * Sin(v)
Z = u
where v is between 0 and 2 \(\pi\) and u between 0 and h, respectively.
Creating a geometry list
A geometry list is a simple file consisting of a list of file names that contain geometry descriptions. This is the file that should be passed to the GMAD file when defining the Mokka element. An example of a geometry list containing ’boxes.sql’ and ’cones.sql’ would be:
# ’#’ symbols can be used for commenting out an entire line
/directory/boxes.sql
/directory/cones.sql
Defining a Mokka element
The Mokka element can be defined by the following command:
collimator : element, geometry=mokka:coll_geomlist.sql