Geant4 GDML HOWTO

Introduction

GDML 1.0 is the markup language to allow definition of geometry data in XML format. The structure of GDML is defined by its corresponding GDML Schema. Having the schema allows the both the developers and users to learn what is available and at the same time what is forbidden in the GDML data files. For users it means at first security, as XML parser can immediately warn about all deviations from the prescribed GDML "syntax".
On the other hand developers can make use of the knowledge gathered from schema for translation into programming language abstractions describing concepts in the schema.

The domain of GDML is targeting the geometry description of HEP detectors. This does not prevents its possible applications to other fields where such a language is needed. It complements the very often used way of data input in form of a source code. What users gain is the reduced time when writing their geometry description as no need for re-compilation and re-linking of their applications is required even for one number change. The other advantage is that it allows them easy exchange of geometry data without a need to reveal their source code and makes life easier for developers as well because they can use the GDML data for tracing bugs and problems in geometry processing code.

This document provides a brief introduction to what GDML 1.0 offers and provides an introduction to its use described by annotated example.

Features

The features in the GDML 1.0 cover the set of basic elements needed to describe geometry. This set of features is not the final one and some extensions are already planned, see later in section Future.

GDML Feature Matrix

Structure

Hierarchical geometry structure elements

volume
assembly
child placement (single)
setup

Solids

CSG¹ solids:

box
tube
cone
sphere
parallelepiped
trapezoid
general trapezoid

Boolean solids:

union
subtraction
intersection

Materials

Materials definitions

isotopes
elements
- elements built from isotopes
complex materials
- molecules built from elements by atoms
- mixtures built from elements and/or other complex materials by fractional mass

Numerical
expressions

Actual definitions of numerical elements:

constant
quantity
expression
Cartesian position and rotation

Core

Base types for constants, expressions, quantities, vectors and (local) references

Annotated
Example

XML Declaration

<?xml version="1.0" encoding="UTF-8"?>

GDML Namespace
XML Schema Instance Namespace
GDML Schema location

<gdml xmlns:gdml="http://cern.ch/2001/Schemas/GDML"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="gdml_1.0.xsd">

Numerical definitions:

constant PI
NOTE: require the CLHEP built-in pi!
position center( 0.0, 0.0, 0.0 )
rotation identity equals to
identity.rotateX( 0.0 )
identity.rotateY( 0.0 )
identity.rotateZ( 0.0 )

NOTE: GDML rotation is axial rotation

<define>
 <constant name="HALFPI" value="pi/2."/>
 <constant name="PI" value="1.*pi"/>
 <constant name="TWOPI" value="2.*pi"/>
 <position name="center"/>
 <rotation name="identity"/>
 <position name="shiftbyx" x="20.0"/>
 <position name="px10" x="10.0"/>
 <position name="px250" x="250.0"/>
 <position name="px200" x="200.0"/>
 <rotation name="rotatebyx" x="HALFPI/2."/>
 <rotation name="rotatebyall" x="HALFPI" y="PI" z="TWOPI"/>
</define>

Density quantity definition

Isotopes
and
their use to create an element

Simple elements type definitions
NOTE: elements can't be associated with a volume, only materials can!

Simple material a la element way

Simple material created from two elements by number of atoms

Material mixture created by fractional mass

 <materials>
  <define>
   <quantity type="density" name="ro" unit="g/cm3" value="1234.00"/>
  </define>
  <isotope name="U235" Z="92"   N="235"> <atom type="A" value="235.01"/>
  </isotope>
  <isotope name="U238" Z="92.0" N="238"> <atom type="A" value="238.03"/>
  </isotope>
  <element name="enriched_Uranium">
   <fraction ref="U235" n="0.9"/> <fraction ref="U238" n="0.1"/>
  </element>
  <element name="Hydrogen" formula="H" Z="1."> <atom value="1.01"/>
  </element>
  <element name="Oxygen" formula="O" Z="8."> <atom value="16.0"/>
  </element>
  <element name="Nitrogen" formula="N" Z="7."> <atom value="14.01"/>
  </element>
  <element name="Lead" formula="Pb" Z="82."> <atom value="207.20"/>
  </element>
  <material name="Al" Z="13.0">
   <D value="2.70"/> <atom value="26.98"/>
  </material>
  <material name="Water" formula="H20">
   <D value="1.0"/>
   <composite n="2" ref="Hydrogen"/>
   <composite n="1" ref="Oxygen"/>
  </material>
  <material name="Air">
   <D value="1.290" unit="mg/cm3"/>
   <fraction n="0.7" ref="Nitrogen"/>
   <fraction n="0.3" ref="Oxygen"/>
  </material>
 </materials>

Examples of all available CSG solids
One can place numeric definitions here as well as into materials and structure section.
NOTE: All numeric definitions are global!

Boxes

Cone
Parallelepiped

Sphere
General trapezoid

Trapezoid
Tubes

 <solids>
  <define>
   <quantity type="length" name="sizeoft500" unit="mm" value="500.0"/>
   <position name="shiftbysizeoft500" x="500.0"/>
  </define>
  <box name="WorldBox" x="10000.0" y="10000.0" z="10000.0"/>
  <box name="b100" x="100.0" y="100.0" z="100.0"/>
  <box name="b500" x="500.0" y="500.0" z="500.0"/>
  <cone name="c1" z="111.0" rmax1="22.0" rmax2="33.0" deltaphi="TWOPI"/>
  <para name="p1" x="10.0"     y="10.0"     z="10.0"
                  alpha="30.0" theta="30.0" phi="30.0"/>
  <sphere name="s1" rmax="200.0" deltaphi="TWOPI" deltatheta="PI"/>
  <trap name="trap1" z="100.0"     theta="60.0"  phi="60.0"
                     y1="10.0"     x1="10.0"     x2="10.0"
                     alpha1="30.0" y2="10.0"     x3="10.0"
                     x4="10.0"     alpha2="30.0"/>
  <trd name="trd1" x1="10.0" x2="10.0" y1="10.0" y2="20.0" z="30.0"/>
  <tube name="t1000" z="1000.0" rmax="100.0" deltaphi="TWOPI"/>
  <tube name="t900" z="900.0" rmax="100.0" deltaphi="TWOPI"/>
  <tube name="t100" z="102.0" rmax="30.0" deltaphi="TWOPI"/>

Make a union where tube "t100" is moved 250.0 mm along x-axis from center of the box "b500"

Subtract the non-rotated tube "t100" from the center of box "b100"

Intersection of box "b100" and tube "t100" where tube is moved by 10.0mm in x and rotated by 45 degrees around x-axis

  <union name="u2">
   <first ref="b500"/> <second ref="t100"/>
   <positionref ref="px450"/>
  </union>
  <subtraction name="sub2">
   <first ref="b100"/> <second ref="t100"/>
   <positionref ref="center"/> <rotationref ref="identity"/>
  </subtraction>
  <intersection name="intersec1">
   <first ref="b100"/> <second ref="b100"/>
   <positionref ref="px10"/> <rotationref ref="rotatebyx"/>
  </intersection>
 </solids>

Simple geometry setup
Volume definitions²

World volume definition

Place child volume "v2" at the center

Place the child volume "v1" moved by 200.0 mm along x-axis from the center

 <structure>
  <volume name="v1">
   <materialref ref="Lead"/> <solidref ref="t1000"/>
  </volume>
  <volume name="v2">
   <materialref ref="Lead"/> <solidref ref="sub2"/>
  </volume>
  <volume name="World">
   <materialref ref="Air"/> <solidref ref="WorldBox"/>
   <child>
    <volumeref ref="v2"/> <positionref ref="center"/>
                          <rotationref ref="identity"/>
   </child>
   <child>
    <volumeref ref="v1"/> <positionref ref="px200"/>
                          <rotationref ref="identity"/>
   </child>
  </volume>
 </structure>

Only one setup is defined here, however it is possible define multiple geometry setups choosing different volumes as world volumes from all the already defined volumes

 <setup name="Test1" version="1.0">
  <world ref="World"/>
 </setup>

</gdml>

Geant4/GDML
Binding

Having some GDML data is fine. Now it is needed to marry the Geant4 and GDML processing engine to let them together build the wanted geometry marked-up in XML. The idea is simple. There is G4VUserDetectorConstruction abstract class expected by Geant4 run-time which one has to inherit from and implement its Construct() method which is responsible for actual geometry construction and returns the pointer to a world volume. In standard Geant4 application its implementation contains direct calls to Geant4 materials and geometry APIs and few others. In case of GDML this task is simplified in sense it gets rid of materials & geometry APIs. The following code listing demonstrates GDML way of implementing user detector construction:

#include "G4String.hh"
#include "G4VUserDetectorConstruction.hh"
#include "G4VPhysicalVolume.hh"

#include "SAXProcessor.hh"
#include "ProcessingConfigurator.hh"

class ExN03CalorimeterSD;
class ExN03DetectorMessenger;

class ExN03DetectorConstruction : public G4VUserDetectorConstruction
{
public:
  ExN03DetectorConstruction();
  ~ExN03DetectorConstruction();

public:
  G4VPhysicalVolume* Construct();     //The queen of methods one has to implement
  
... removed some stuff for brevity   

private:
  SAXProcessor sxp;                   //XML engine
  ProcessingConfigurator config;      //XML engine configuration
  G4VPhysicalVolume* fWorld;          //World volume
  ExN03CalorimeterSD* calorimeterSD;  //pointer to the sensitive detector
  ExN03DetectorMessenger* detectorMessenger;
};

#include "ExN03DetectorConstruction.hh"
#include "ExN03DetectorMessenger.hh"
#include "ExN03CalorimeterSD.hh"

#include "G4SDManager.hh"
#include "G4VisAttributes.hh"
#include "G4Colour.hh"

#include "GDMLProcessor.hh"
#include "GDMLExpressionEvaluator.hh"

ExN03DetectorConstruction::ExN03DetectorConstruction() : calorimeterSD( 0 ) {
  // create commands for interactive definition of the calorimeter
  detectorMessenger = new ExN03DetectorMessenger(this);
  sxp.Initialize();                // Initialize XML engine
  config.SetURI( "NO3.gdml" );     // Set the GDML data location
  config.SetSetupName( "N03" );    // Set the wanted setup name
  sxp.Configure( &config );        // Apply the configuration settings to XML engine
}

ExN03DetectorConstruction::~ExN03DetectorConstruction() {
  sxp.Finalize();                  // Shut-down XML engine properly
}

G4VPhysicalVolume* ExN03DetectorConstruction::Construct() {
  // Launch XML engine to process GDML data
  sxp.Run();

  // Retrieve the world volume from GDML processor
  fWorld = (G4VPhysicalVolume *)GDMLProcessor::GetInstance()->GetWorldVolume();

  // Check if the world volume seems to be fine
  if( fWorld == 0 ) {
    G4Exception(
       "Invalid world volume, check your setup selection criteria or GDML input!"
               );
  }

  /// THIS CODE IS ALMOST THE SAME AS BEFORE TO SETUP THINGS NOT DEFINED IN GDML ///
  //
  // Sensitive Detectors: Absorber and Gap
  //
  G4SDManager* SDman = G4SDManager::GetSDMpointer();
  if(!calorimeterSD) {
    calorimeterSD = new ExN03CalorimeterSD("CalorSD",this);
    SDman->AddNewDetector( calorimeterSD );
  }
  G4LogicalVolume* lv = 0;
  lv = FindLogicalVolume( "Absorber" );        // FindLogicalVolume makes use of
  if ( lv )                                    // GDMLProcessor which keeps track
    lv->SetSensitiveDetector(calorimeterSD);   // of all Geant4 objects it has created
  lv = FindLogicalVolume( "Gap" );             // during the GDML data processing
  if ( lv )                                    // In the same way one can retrieve
    lv->SetSensitiveDetector(calorimeterSD);   // materials or rotations, etc.

  //
  // Visualization attributes
  //
  lv = FindLogicalVolume( "World" );
  lv->SetVisAttributes (G4VisAttributes::Invisible);
  lv = FindLogicalVolume( "Calorimeter" );
  lv->SetVisAttributes (G4VisAttributes::Invisible);

  G4VisAttributes* simpleBoxVisAtt= new G4VisAttributes(G4Colour(1.0,1.0,1.0));
  simpleBoxVisAtt->SetVisibility(true);
  lv = FindLogicalVolume( "Layer" );
  lv->SetVisAttributes(simpleBoxVisAtt);

  return fWorld;
}

GDML version of user detector construction in Geant4 (taken from Geant4 extended GDML example)

Practical
advices

Basic rule in GDML is "define before use", as it is common practice in many programming languages. This makes GDML processing easier, especially the evaluation of numeric elements, for example constants and expressions
Only materials defined with <material> tag can be assigned to volumes. Define elements with <element> tag when you need them later to create more complex materials
Assembly volumes can contain only volumes. If assembly were allowed to adopt other assembly volumes it might become very ambiguous configuration
When there is a need to repeat a complex configuration in space one can save some effort by using assembly volume
Be careful! Do not abuse assembly volumes! Making a lot of children of assembly type in the same mother volume can generate many many child volumes, which in some applications can affect performance!

Future

Current set of GDML features is already rich and usable for practical applications. Of course is far from being exhaustive or complete. The following list of features is planned to be implemented in the near future:

Replicated children, one <child> tag creates N copies
Spherical and cylindrical transformations
Placement policies, in other words placing algorithms parameterized from GDML
- Basic idea here is to define a set of algorithms which place children inside a mother volume with well defined behavior and user only supplies a set of parameters defining the placement
- For example: "Place N children of volume "Vxyz" around circle with radius R and center at position (x, y, z)

Well, I am sure the list can be extended. Any suggestions are welcome and can be submitted either to my e-mail bellow or to mailing list shown on the GDML main web page.

1. Constructive Solid Geometry

2. Assembly volumes are not shown, they will be described in GDML Specification and User's Guide

Author: Radovan Chytracek

IT/ADC CERN

Last update: January 31, 2005 14:54

<-- Back to the GDML web page