How to implement a pixel custom geometry in GeoModel

FastGeoModel is a package that allows to build the ITK pixel layouts geometries independently from the usual geometry tag system. The layout geometry is described in two steps :

  1. the tracking geometry (FATRAS) : sensors  detector ( InnerDectector/InDetDetDescr/InDetTrackingGeometryXML package )
  2. the detector geometry (GeoModel) : geometric envelopes, staves, services passive detector ( InnerDectector/InDetDetDescr/PixelLayouts/... packages)

The first step consists therefore in using the FATRAS XML interface to build the sensitive detector : follow the instructions on CustomGeometryImplementationGuide to build and validate your tracking geometry.

Once the tracking geometry is ready and validated, one can implement the GeoModel (i.e fullsim geometry) by refining the detector description and by defining the services.

FastGeoModel layout : XML-based implementation

FastGeoModel code bundle - available currently as as a tarball - ATHENA

Copy the following file to your working directory : ~selles/public/PixelGeometry_SimuDigi20.tar.gz This package is tested and validated with ATHENA

Untar the files, proceed to the setup of ATHENA and compile the complete set of packages :

The default ATHENA release is 19.2.4, but can be changed to any simu/digi/reco release (not mig5 or 10.7.x compliant, maybe we can use 20.20.X-VAL now)


The FastGeoModel bundle is organized as a set of tools one can combine to create a pixel geometry on the fly :

  • the PixelLayouts repository contains a package per type of layout (LoI, ECring, InclBrl, ExtBrl...). Each group is responsible for its package.
  • the module geometry and readout geometries are defined and managed by AthTools defined in PixelLayouts/PixelModule
  • the pixel services are defined and managed by the AthAlgTool defined in PixelLayouts/PixelServiceTool
The FastGeoModel geometry is entirely put together through the jobOption files, in which one selects the tools used to build each section of the pixel detector as well as the XML files to be read.

FastGeoModel jobOption files

In the current SLHC/ITk code, one has to include the following file InDetSLHC_Example/ (as preinclude or postinclude) in all the ATHENA commands to specifically ask the ITk code to be used.

In FastGeoModel, this file simply needs to be replaced by the one corresponding to the layout one would like to build. For example: InDetSLHC_Example/

Several files are available in the directory InnerDetector/InDetExample/InDetSLHC_Example/python : file Layout/geometry geometry db tag Pixel identifier file Comment ITk LoI geometry ATLAS-P2-ITK-01-00-00 LoI geometry build with FastGeoModel ITk LoI-VF geometry ATLAS-P2-ITK-02-01-00 LoI-VF geometry build with FastGeoModel ITk LoI-ECRing 3-5-8 geometry ATLAS-P2-ITK-03-01-00 LoI-ECring 3-5-8 geometry build with FastGeoModel Extended barrel - eta<3.2 ATLAS-P2-ITK-05-00-00 IdDictInnerDetector_SLHC_ExtBrl_32.xml Extended barrel - eta<4 ATLAS-P2-ITK-06-00-00 IdDictInnerDetector_SLHC_ExtBrl_4.xml Inclined Extended barrel - layers 0&1 ATLAS-P2-ITK-07-00-00 IdDictInnerDetector_SLHC_IExttBrl_4.xml Full Inclined Extended barrel ATLAS-P2-ITK-08-00-00 IdDictInnerDetector_SLHC_InclBrl_4.xml  
Each file contains the 2 sections that describe the tracking geometry (link to the FATRAS - XML files) and the fullsim geometry (links to the FASTGEOMODEL - XML description files).

FATRAS - XML description files

###### Setup ITk XML reader ######
from InDetTrackingGeometryXML.InDetTrackingGeometryXMLConf import InDet__XMLReaderSvc
xmlReader = InDet__XMLReaderSvc(name='InDetXMLReaderSvc')
PixelLayout = "ExtBrl4Ref"
PixelEndcapLayout = "ECRingRef"
SCTLayout    = "LoI"
dictionaryFileName = "InDetIdDictFiles/IdDictInnerDetector_SLHC_ExtBrl_4.xml"
createXML = False
doPix = True
doSCT = False

The PixelLayout and PixelEndcapLayout variables specify the names of the XML files that define the detector tracking geometry. Those files are located in the package InnerDetector/InDetDetDescr/InDetTrackingGeometryXML/share/

Important note: only the PixelLayouts are configurable through XML files. The SCT geometry is built from the usual geometry tag system. Volunteers are welcome to adapt the FastGeoModel code to the SCT detector.

FASTGEOMODEL - XML description files

     "PIXELROUTINGSERVICE":"BrlExt4_PixelRoutingService", }

These parameters define the names of the FastGeoModel XML files used to configure :

  • PIXELGENERAL : the pixel, barrel and endcaps general envelopes
  • PIXELSIMPLESERVICE : the simple services shapes (IST, PST, ...)
  • STAVESUPPORT : the stave support geometry
  • MATERIAL : additional materials
  • PIXELDYNAMICSERVICE : old GeoModel compilant scaling/routing of the services (LoI & ECRing 3-5-8 geometries only)
  • PIXELROUTINGSERVICE : automated sclaing and routing of the services throug the ID

The XML files are stored by default in InnerDetector/InDetDetDescr/PixelLayouts/your_layout/data
There files defined for the LoI(VF) and LoI-ECRing(3-5-8) can be found in the directory InnerDetector/InDetDetDescr/PixelLayouts/PixelLayoutUtilsdata/

Caution : the XML files shared with FATRAS ( active detector and modules) are stored in [InnerDetector/InDetDetDescr/InDetTrackingGeometryXML/share

The names of the xml files are displayed in the ATHENA log files : athena your_jobOption | grep ENV

FASTGEOMODEL - geometry tool builder selection (barrel, endcap, services, ...)

from PixelModuleTool.PixelModuleToolConf import PixelModuleBuilder
from PixelModuleTool.PixelModuleToolConf import PixelDesignBuilder
from PixelServicesTool.PixelServicesToolConf import PixelServicesTool
from BarrelExtendedRef.BarrelExtendedRefConf import GeoPixelBarrelExtRefTool
from EndcapRingRef.EndcapRingRefConf import GeoPixelEndcapECRingRefTool

The PixelModuleBuilder, PixelDesignBuilder and PixelServicesTool should not be modified unless one would like to develop its own tools. However, it is up to each user to configure the Barrel and endcap tools to create its own pixel geometry. These tools are defined in the PixelLayouts packages.

FastGeoModel layout

ID identifier dictionary & geometry tags

A geometry tag is assigned to each layout in order to define properly the name of the corresponding ID identifier dictionnary (see the table above), and to avoid issues with the cal and muon sub-detectors while overriding manually the dictionary.

The geometry tag in itself does not contain the description of the GeoModel geometry and should not be used directly without the FastGeoModel interface.

how to create the ID identifier

Edit the SLHC_Setup file corresponding to your layout ( directory InnerDetector/InDetExample/InDetSLHC_Example/python ) and set the createXML and doSCT parameters to true ( setting doSCT to true does not imply that the SCT geomodel is build based on XML files)

###### Setup ITk XML reader ######
from InDetTrackingGeometryXML.InDetTrackingGeometryXMLConf import InDet__XMLReaderSvc
xmlReader = InDet__XMLReaderSvc(name='InDetXMLReaderSvc')
PixelLayout = "ExtBrl4Ref"
PixelEndcapLayout = "ECRingRef"
SCTLayout    = "LoI"
dictionaryFileName = "InDetIdDictFiles/IdDictInnerDetector_SLHC_ExtBrl_4.xml"
createXML = <b>True</b>
doPix = True
doSCT = <b>True</b>

the updated dictionary is going to be created automatically by launching any command that implies the geometry to be built (for example athena

Remark :

  • the dictionaries are stored in your working directory in the InDetIdDictFiles subdirectory.
  • it is possible to leave the createXML and doSCT set to True
Hash id and/or identifier error

In case a hash id error or identifier error occurs while using ATHENA, remove the identifier file if it exists and proceed as described above to recreate the identifier file

module geometry and readout geometry

The modules are currently defined in InnerDetector/InDetDetDescr/InDetTrackingGeometryXML/share/ITK-modules.xml

the pixel volume, barrel and endcap envelopes

The envelopes volumes for pixel, barrel and endcap volumes are defined in the PIXELGENERAL file (see

If the envelopes are defined as cylinders, one has to define the zMin,zMax (or half length) and rMin,rMax values following this pattern :

  <PixelBarrelEnvelope> ...
     <RadiusMin> 34.1 </RadiusMin>
     <RadiusMax> 259 </RadiusMax>
     <HalfLength> 810 </HalfLength>

In case a more complex envelope shapes have to be defined (extended barrel geometry for example), a specific pattern has to be used :

 <PixelBarrelEnvelope> ...  
     <RadiusList> 34.1  149.9 340.99</RadiusList>      the barrel is made of two cylinders :  34.1<R<149.4 & halfLength=1278  and 149.9<R<340.99  & halflength=745.1
     <HalfLengthList> 1278 745.1 </HalfLengthList>

A XML description of a standard pixel / barrel/endcap envelope can be found LoI_PixelGeneral.xml
A second example - extended barrel geometry- is available BrlExt4_PixelGeneral.xml

envelope and barrel geometries

The pixel barrel tool package should at least contain the following Athena algtools that are going to ba called to build the pixel envelope and the pixel barrel : GeoPixelEnvelopeTool & GeoPixelbarrelTool.
The functions used to build the layer, ladders and staves can be defined as Athena alg tools or simple builder depending on what king of geometry is build : identical layers vs mix of several types of layers, tool copy/pastes or shared with another type of layout,.etc...

For example, two layer athena alg tools are defined in PixelLayout/BarrelInclinedLayout, to build respectively planar and inclined layers. It is not mandatory to define all the builders as athena alg tools.

endcap geometry

The Pixel endcap tool package should at leat contain the GeoPixelEndcap Athena algtool. It is once aiaing up to the developper to decide wether or not it is necessary to define the dics/rings or layers/rings structures as algTool or simple builder.
Endcap ring geometry The endcap ring geometry should be defined as layers of rings, instead of a set of discs/rings. The tracking geometry is automatically build with rings grouped as layers, several rings can therefore be placed at the same Z position. (see the PixelLayout/EndcapRinfRef package. ) The LoI+ECring 5-8-12 layout is also built as a set of ring layers.

the pixel service tool

The pixel service tool is used to build and place different types of services :

>> the static services :

these services are defined by simple shapes (disks, cylinders, ...) and used mailnly for IST & PST

>> the dynamic services :

>>>> old GeoModel compilant scaling/routing of the services developed for the LoI & ECRing 3-5-8 geometries only

PIXELDYNAMICSERVIold GeoModel compilant scaling/routing of the services (LoI & ECRing 3-5-8 geometries only)

>>>> automated scaling and routing of the services throug the ID

PIXELROUTINGSERVICE : automated sclaing and routing of the services throug the ID

>>>> remarks

It is recommanded to comment out the PIXELDYNAMICSERVICE or PIXELROUTINGSERVICE while building the barrel/endcap geometry until the pixel subdetector is properly built.

>> Configuration of the automated scaling and routing service tool:

>> Service routing XML files jobs

The commented example is the IExtBrl layout. The PixelRouting XML file is the following : InnerDetector/InDetDetDescr/PixelLayouts/BarrelInclinedRef/data/IExtBrl4_PixelRoutingService.xml

>>> Services for layer 0 modules

Layer 0 is an inclined layer :

<!-- defines the different type of services (barrel + endcap modules) for each leayer -->
  <service>BarrelLayer_0 BarrelLayer_1</service>

the barrel module services are described in <ServiceSet> with name= BarrelLayer_0
the endcap module services are described in <ServiceSet> with name= BarrelLayer_1

>>> Definition of a barrel service route :

  <layer>0 1 </layer>     < --- layer 0 and 1 are grouped
  <thickness> .5 </thickness> 
  <r> r_Layer r_Layer inner_IST inner_IST</r>                 <-- radius of layer // radius of layer     // inner IST radius    // inner IST radius
  <z> zMax_Layer zMax_AllLayer zMax_AllLayer zMax_IST</z>     <-- zMax of laer    // zMax of both layers // zMax of both layers // zMax of IST

>>> Definition of an endcap service route :

  <layer>14 17 22 25 29 32 35 39 41 44 48 50 54 57 59 62 64</layer>    <--- list of the ring numbers routed together
  <thickness> .5 </thickness> 
  <r> rMax_Disc_14+.02 rMax_Disc_14+.02</r>
  <z> z_Disc zMax_PST</z>

The set of (r,z) points defined in the XML file define the segments along which the services are going to be routed One can define as many points as needed

How to find the ring numbers corresponding to a layer ?
Run the VP1 display script (see below) that correspond to your layout ( script) and capture the log file of the job.

athena  | tee  output.log
cat output.log | grep "Disc trk"

>>> Services route definition - keywords

A set of '''keywords''' can be used in order to avoid having to use hardcoded values :

r_layer    : radius of the selected barrel layer
r_layer_i  : radius of the barrel layer No i
zMax_layer : zMax position of the selected layer
zMax_AllLayer : zMax for all the layers selected in the PixelServiceRoute object

rMin_Disc / rMax_Disc : min/max radius of a disc
rMin_Disc_i / rMax_Disc_i : min/max radius of disc no i
z_Disc     : z position of the selected disc
z_Disc_i   : z position of disc no i

Any floating value can also be used to define a point
Layer and disc keywords can be suffixed with a + or - value : for example z_Disc+10.

inner_IST / outer_IST / zMax_IST : inner/outer radius of IST, z max position of IST 
inner_PST / outer_PST / zMax_PST : inner/outer radius of PST, z max position of PST

To identify of rings are named and grouped to build the layers : athena | grep "Disc trk layer indices"

>>> Service material description (ServiceSet)

Example 1 : cables and cooling

  <Service>  HV   /4_module  lin std::Copper  0.08  pix::Polyimide  0.119   Cu  </Service>
  <Service>  data   /2_module  lin std::Copper  0.241  pix::Polyimide  6.479   Cu  </Service>
  <Service>  DCS1   /4_module  lin std::Copper  0.123  std::Aluminium  0.697   pix::Polyimide  2.731   Cu-clad_Al  </Service>
  <Service>  DCS2   /4_module  lin std::Copper  0.051  pix::Polyimide  0.076   Cu  </Service>
  <Service>  DCS3   /4_module  lin std::Copper  0.41  pix::Polyimide  2.937   Cu-clad_Al  </Service>
  <Cooling>  TiCO2 *2_stave   lin 2. 2.275 pix::CoolingFluid std::Titanium</Cooling>

The different tags are : * : cable defined by its components (name + weight in g) for a 1 mm length section * : colling line defined by the inner/outer diamters and the cooling fluid / cooling pipe materials

Parameters :

*HV, data, DCS1, DCS2 and DCS3 are the different type of cables : this identifier must be unique in a service set *multiplicity :
/4_module : one cable serves 4 modules, *3_module : 3 cables are added per module
/2_chip : one cable serves 2 chips, *2_stave : 2 cables are added per stave
and so on
*Keyword "lin" : this keywords is used to define a linear weighted material (material defined per 1mm length section)

Example 2 : cables, cooling and EOS card (only for endcap rings)

  <Service>  LV_quad   /10_module  lin std::Copper  0.00175616  029988   pix::Polyimide  0.0040334   Cu-clad_Al  </Service>
  <Service>  HV   /10_module  lin std::Copper  0.000361386666667     pix::Polyimide  8.30666666667e-05   Cu  </Service>
  <Service>  data   /5_module  lin std::Copper  0.000540586666667     pix::Polyimide  0.00226776666667   Cu  </Service>
  <Service>  DCS1   /4_module  lin std::Copper  0.000552533333333  009414   pix::Polyimide  0.00191193333333   Cu-clad_Al  </Service>
  <Service>  DCS2   /1_stave  lin std::Copper  0.00022848     pix::Polyimide  5.32e-05   Cu  </Service>
  <Service>  DCS3   /4_module  lin std::Copper  0.0018368     pix::Polyimide  0.00205566666667   Cu-clad_Al  </Service>
  <Cooling>  TiCO2 *2_stave   lin 2. 2.275 pix::CoolingFluid std::Titanium</Cooling>
  <Object>  EOScard  /4_module wgt std::Copper .12 std::Lead .001  std::Bakelite 3.4 EOS_card</Object>

The new tag is used to define an object by its real weight, i.e. the material is not defined as a linear weighted material and is not scaled vs the lenght of the route. This tag cannot be used to define a barrel layer service set.

>>> Services - geometric shapes / density / X0 and compoenents

Run the VP1 display script (see below) that correspond to your layout ( script) and capture the log file of the job.

athena  | tee  output.log
The list of the services created by PixelserviceTool can be displayed with the following command :

cat output.log | grep svcMat

SvcEc50_RadL_L35_Sec0 2219 2219.5 274.77 315.47 188.515 1.66787 Copper 0.0643363  Carbon 0.238603  Hydrogen 0.0691333  Oxygen 0.571051  Nitrogen 0.00281539  Titanium 0.0538227  Lead 0.000238335  
SvcEc50_RadL_L37_Sec0 2357 2357.5 274.77 315.47 188.515 1.66787 Copper 0.0643363  Carbon 0.238603  Hydrogen 0.0691333  Oxygen 0.571051  Nitrogen 0.00281539  Titanium 0.0538227  Lead 0.000238335  
SvcEc50_RadL_L39_Sec0 2504 2504.5 274.77 315.47 188.515 1.66787 Copper 0.0643363  Carbon 0.238603  Hydrogen 0.0691333  Oxygen 0.571051  Nitrogen 0.00281539  Titanium 0.0538227  Lead 0.000238335 

the parameter displayed for each service are : zMin, zMax, rMin, rMax, density (g/cm3), X0 (cm), material description (components + % in weight)

CAUTION : the material is scaled following the volume of the geometric shape, so the density varies according to this volume. A same material can therefore be shown with different densities

Material definition

An initial material list is read and initialized staring from the geometry tag assigned to the pixel layout. The materials defined in pixel/SCT and standard tables are available to build GeoModel.

To browse a geometry tag : geometry DB
* select a geometry tag in the left window to display the corresponding node and table hierarchy
* open the InnerDetector node :
- pixel materials : see the PixMaterials table in the Pixel node
- sct materials : see the SCTMaterials table in the SCT_SLHC node
- std materials : see the StdMaterials table in the Materials node

>>> Layout specific material definition (XML file)

Additional materials can de defined through the XML file spcified in the file (see the FASTGEOMODEL- XML description file section) The name of the file is defined by the MATERIAL environment parameter defined in the python file.

Basic material A material is defined by its density (g/cm3) and its components list (name+% in weight)

    <name> L2_FlexMat0 </name>
    <density> 1.97 </density>
    <component> <name> std::Copper </name> <weight> .36 </weight> </component>
    <component> <name> pix::Polyimide </name> <weight> .63 </weight> </component>

The pix/sct/std prefixes indicates wether the material is taken from the pixel/sct or standard tables.
A material component can be an other material.

Weighted material Weighted materials are usually used to define the sensor/chip/hybrid and services material. One has to define a base material (density set to 1.) and the weighted material build based on it : the density is computed automatically based on the geometric shape volume the material is assigned to and the weight of the material.

    <name> ChipBase  </name>
    <density> 1. </density>
    <component> <name> std::Silicon </name> <weight> .9971 </weight> </component>
    <component> <name> Tin </name> <weight> .0015 </weight> </component>
    <component> <name> std::Lead </name> <weight> .0014 </weight> </component>

    <name> Chip_FourChip  </name>
    <base> ChipBase  </base>
    <weight> 1.2 </weight> 

>>> Sensor/chip/hybrid material

They are defined in the MATERIAL file (see first bullet)

>>> Stave support material

They are defined in the MATERIAL file (see first bullet)

FastGeoModel geometry validation

VP1 display

One can visualize the geometries defined in the table given above by launching the corresponding defined in the InnerDetector/InDetExample/InDetSLHC_Example/run/ directory.

You can add a line at the end of the jobOption to use the configuration file provided in attachment.

from VP1Algs.VP1AlgsConf import VP1Alg
VP1Alg.InitiallyLoadedVP1Files = [ "BasicVisualisationGeoModel.vp1" ]
job += VP1Alg()


  • The ITk geometries LoI, LoI-VF and LoI-ECRing are exact copies of the geometries build by the standard GeoModel code.
  • The ExtBrl and InclBrl files are only templates, they need to be updated by the corresponding layout responsible.

check geometry overlaps

A script to check the geometry overlaps is also available in the run directory : Configure its content to test your layout (geometry tag and SLHC_Setup file) and launch the script in order for Geant4 to check if there are overlaps in the geometry you want to build.

FastGeoModel : full simulation samples production

For the latest recipe in release 20.20, see

Beam pipe geometry

The package used to develop and test the current SLHC beam pipe geometry is AtlasGeometryCommon/BeamPipeGeoModel. This package has been modify to read the bema pipe geometry from the txt file used to overwrite the pixel/SCT geometry.

To develop the new ITk beam pipe geometry :

  • compile AtlasGeometryCommon/BeamPipeGeoModel/
  • fill in the following text file : InnerDetector/InDetExample/InDetSLHC_Example/data/slhcsct_local_database_SLHC-BeamPipe.txt
  • and use InnerDetector/InDetExample/InDetSLHC_Example/run/ to visualize and test the new beam pipe geometry
The slhcsct_local_database_SLHC-BeamPipe.txt contains 2 sections :
  • the BPipeEnvelope section describes the beam pipe envelope following a (Z,R) description (this section has to end with the point (0 -1) )
  • the BPipeSections section describes the different layers of material used to build the bema pipe (this section has to end with a line where SECNUM is set to -1)

The current SLHC beam pipe description is available as txt file in InnerDetector/InDetExample/InDetSLHC_Example/data/slhcsct_local_database_SLHC-Current-BeamPipe.txt

-- Main.SabineElles - 2015-10-12

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatvp1 BasicVisualisationGeoModel.vp1 r1 manage 1.5 K 2015-10-14 - 14:10 JessicaLeveque VP1 configuration file to vizualize the Inner Detector GeoModel (modules + services)
Edit | Attach | Watch | Print version | History: r17 < r16 < r15 < r14 < r13 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r17 - 2016-02-11 - SabineElles
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    Sandbox All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback