Detector Description "Database" XML Tutorial

Complete: 5


In this tutorial you will learn what the Detector Description Language (DDL) is and how to use it to create your own detector description. Most of this will be practical and not about the reasoning and theory behind the model of the whole Detector Description Database (DDD) although a little of that will be mentioned.


The DDD is a detector description "database" which uses Extensible Markup Language (XML) sources (DDL) to describe the detector's geometry, materials and other parameters. High Energy Physics has a history of the geometry being provided by different pieces of software. GEANT3 and GEANT4 have been used for simulation and have provided the main source of detector descriptions. As a consequence the DDL used by the DDD is influenced in design by both of these even to the extent that solid names being used correspond to solids in those systems. This may lead to some confusion, so please read the DDL definition and use that as opposed to making assumptions about the solid descriptions.

The XML part of the DDD is used to generate the detector in memory. In other words, from the application point of view there is no need to know the DDL and, as a matter of fact, other means of storage could be used. An API is defined by the DDCore to allow client software (such as simulation, reconstruction and analysis) to access the DDD and reshape the information to match their needs. This includes some filtering and querying to limit what one retrieves to only that which is necessary for the client application.

As mentioned earlier, the DDL is an XML document format which is interpreted by the DDD. Although many of you probably have heard of XML let us cover some basics. "XML makes use of tags (words bracketed by '<' and '>') and attributes (of the form name="value" )... to delimit pieces of data and leaves the interpretation of the data completely to the application that reads it." (XML in 10 Points). The term element is used somewhat interchangeably with tag. In this document the term element is used and in the DDL names that start with a capital letter refer to the XML elements (e.g. LogicalPart) and names that start with lower case letters refer to attributes (e.g. deltaPhi).

XML is sometimes referred to as the next generation of HTML (Hypertext Markup Language). This can be misleading since HTML is designed for consistent display of information in the form of pictures, text, tables and links to other documents, whereas XML is designed for reliable transfer of structured data. One of the requirements, for example, for an XML processor is that it fail when not correct, whereas HTML (web browsers) processors are designed to complete whether or not the syntax is exactly correct.

Thus, the requirements of XML allow it to be validated more readily for structural correctness and to go beyond simple XML validation and specify the way elements and attributes are structured within a file. There is more than one way to do this. The DDD uses an XML Schema to validate the files (DDL documents). This is done either as you work, by a schema aware editor, or after you have created the DDL file, running a validation program to check the XML.

The DDL describes a compact view of the detector description. This is done by following a "One Definition Rule" which says that each unique object should only be defined once. For example, given a part is described with it's shape (solid) and the material that it is composed of then this part definition can be used repeatedly for each "real" part of that type and positioned accordingly.

In general a DDL based detector description is divided up into files that correspond to logical divisions of the detector. Each file contains one or more sections that correspond to the major element types of the DDL which are: solids, constants, materials, rotations, logical parts, positioning instructions (positioned parts), specific parameters (parameters specific to a client software), and constraints (which are not addressed in this tutorial). There are other types of elements, such as rMaterial that are classified as reference types. These elements refer to other elements. And, there are incidental elements that are simply ways to describe detail of types that are more complex, such as the RZPoint used by Polyhedra and PolyconeRZ. One file can reference objects in another file using the file name.

ConstantsSection contains declarations of constants to be used in other elements. These can be used through out a file and thus can be located near where they are used. In the following example, the first constant is defined in pixbar.xml file, while the second refers to a constant defined in cms.xml file.

<ConstantsSection label="pixbar.xml" eval="true">
   <Constant name="zero" value="0.0*fm"/>
   <Constant name="Rin1" value="[cms:TrackBeamR1]"/>

SolidSection contains descriptions of solids. LogicalPartSection contains descriptions of LogicalParts. And so-on. You get the picture.

The Model

In simple terms, the detector is composed of LogicalParts which are positioned using PosParts. A LogicalPart consists of a Solid (Box, Trapezoid or Tubs, etc.) and a Material (ElementaryMaterial or CompositeMaterial). The Materials and Solids are defined outside the LogicalPart and a ReferenceType element is used to refer back to those elements. The ReferenceTypes are rMaterial, rSolid, rRotation, rReflectionRotation and rParent and rChild (which refer to LogicalParts). These can refer to the respective types of elements defined in the same file or another file.

Note: There is also a special LogicalPart in which every other part is positioned which is marked as such in the configuration file using a Root element.

A PosPart refers to two LogicalParts using rParent and rChild elements.

What you end up with is a hierarchy of LogicalParts positioned inside other LogicalParts via PosParts. In this compact description a LogicalPart need only be defined once (i.e. it is a type of part) and yet positioned many places in the detector, sometimes algorithmically. The hierarchy of LogicalParts positioned by PosParts results in a multigraph [Figure 1]. In this example, LP4 (LogicalPart 4) will appear twice in the "real" detector. And LP7 is positioned 3 times within LP4. Each LP7 will have a LP8, LP9 and LP10 and thus those are also multiple parts in the real detector as well.

Figure 1: Relationship of LogicalParts and PosParts

Getting Started

For a concrete example, let us say we have a Main detector. The detector consists of 3 Sections which are positioned inside Main.

Where to start describing a detector? All documents start with the first element with attributes that point to the schema. You will need the latest DDLSchema.xsd.

Let's create our CMSSW developers' area and check out all needed packages:

cmsrel CMSSW_6_2_0_SLHC4
cd CMSSW_6_2_0_SLHC4/src
git cms-merge-topic ianna:xml-tutorial
scram b

Have a look at the example of a new xml description in Geometry/XMLTutorial/data/main.xml. If you are manually editing a file with a plain text editor you start with the following line:

<DDDefinition xmlns="" xmlns:xsi="" 
          xsi:schemaLocation=" ../../../DetectorDescription/Schema/DDLSchema.xsd">

and end with


The xsi:schemaLocation attribute consists of two parts. The first part (before the space) you never change. The second half points to the path on your local machine. This second part refers to the actual location of the schema and can be pointed to a url as well.


Now let us define our first Solids, a cylinder and a box of some dimensions.

<SolidSection label="main.xml">
   <Tubs name="MainCylinder" rMin="0*m" rMax="1*m" dz="2*m" startPhi="0*deg" deltaPhi="360*deg"/>
   <Box name="Box" dx="0.5*m" dy="0.1*m" dz="0.25*m"/>

First note a couple of basic things here. XML does not care about white space. Therefore, if one chooses to use a plain text editor for creating this demo spacing is not an issue. The start of the element, a less than sign (<), the name of the element, the attribute names followed by an equal sign (=) and their values, and the "self sealing" end of element (forward-slash followed by a greater than sign (/>)) or an end of element tag such as the are standard XML syntax. For more on this, check your favorite web sites or check out a XML book.

Logical Parts

Next we define LogicalParts consisting of these solids.

<LogicalPartSection label="main.xml">
     <LogicalPart name="MainCylinder" category="unspecified">
             <rSolid name="MainCylinder"/>
             <rMaterial name="materials:Air"/>
     <LogicalPart name="Box" category="unspecified">
             <rSolid name="Box"/>
             <rMaterial name="materials:Air"/>

The above example demonstrates the first ReferenceType usage. The rMaterial refers to a material defined in another file. In general, the Materials and Rotations can be defined in any file or in many files. In this example, I will refer to an already existing materials.xml and rotations.xml.


The PosPartSection section of XML describes the positions of a LogicalPart relative to another one defining a child−parent relation. Use PosPart if it's a single positioning and a DDAlgorithm if it is an algorithmic positioning. We place a MainCylinder volume once in the cms:CMSE (top mother volume for all CMS sub-detectors). Then a Box is placed in the MainCylinder three times with a global:DDAngular algorithm:

<PosPartSection label="main.xml">
      <PosPart copyNumber="1">
             <rParent name="cms:CMSE"/>
             <rChild name="MainCylinder"/>
             <rRotation name="rotations:000D"/>
      <Algorithm name="global:DDAngular">
              <rParent name="MainCylinder"/>
              <String name="ChildName" value="Box"/>
              <Numeric name="StartCopyNo" value="1"/>
              <Numeric name="IncrCopyNo" value="4"/>
              <Numeric name="N" value="3"/>
              <Numeric name="Radius" value="0.5*m"/>
              <Numeric name="StartAngle" value="0.*m"/>
              <Numeric name="RangeAngle" value="360*deg"/>
              <Vector name="Center" type="numeric" nEntries="3"> 0, 0, 0 </Vector>
              <Vector name="RotateSolid" type="numeric" nEntries="9"> 0.*deg, 0.*deg, 180*deg, 90.*deg, 0.*deg, 90.*deg, 0.*deg, 0.*deg, 45.*deg </Vector>

The rChild LogicalPart is placed inside the rParent LogicalPart (referenced to a LogicalPart in another file, cms.xml) and rotating the object by using a rRotation (reference to a Rotation which is defined in the rotations.xml file).

That's all there is to the basic positioning. Look at all the rParent-rChild relationships in other xml files noting how the detector is constructed.

Validation of XML source files

Now we have something described, if you were not using a schema aware editor, you may have made some errors. A simple way to check this is to use the example programs provided by Xerces (Apache XML Parser) or some other XML software.

In your CMSSW environment you can simply validate the file with the following line:

DOMCount -s -n -v=always main.xml


Now we need to tell cmsRun to pick up our "sub-detector" description. It is done in a configuration file fragment (Geometry/XMLTutorial/python/

import FWCore.ParameterSet.Config as cms

XMLIdealGeometryESSource = cms.ESSource("XMLIdealGeometryESSource",
    geomXMLFiles = cms.vstring('Geometry/CMSCommonData/data/materials.xml',
    rootNodeName = cms.string('cms:OCMS')

This cfi file describes our new geometry. This can be included in a cmsRun job to load the geometry into a process:


What Is Next

We can convert the geometry into Root file format (with Geometry/XMLTutorial/python/

cmsRun Geometry/XMLTutorial/python/

and display with cmsShow:

cmsShow --sim-geom-file ./cmsSimGeom-3.root -c Geometry/XMLTutorial/tutorial.fwc

Figure 2. New geometry displayed.


To see debugging messages, please, check out Fireworks/Geometry package and rebuild it with DEBUG enabled:

cvs co -r V06-13-12 Fireworks/Geometry
cmsRun Geometry/XMLTutorial/python/

-- IannaOsborne - 12-Mar-2012

Topic attachments
I Attachment History Action Size Date Who Comment
PNGpng Screen_shot_2012-03-14_at_3.18.25_PM.png r1 manage 106.6 K 2012-03-14 - 16:14 IannaOsborne  
JPEGjpg graphsmall.jpg r1 manage 9.0 K 2012-03-13 - 11:05 IannaOsborne  
Edit | Attach | Watch | Print version | History: r9 < r8 < r7 < r6 < r5 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r9 - 2018-01-31 - IannaOsborne
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

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