GAUDI User Guide

Chapter 8
Detector Description

8.1  Overview

In this chapter we describe how we make available to the physics application developed using the framework the information related to the detector that resides in the detector description database (DDDB). The DDDB is the persistent storage for all the versions of the detector data needed to describe and qualify the detecting apparatus in order to interpret the event data.

The final clients of the detector description are the algorithms that need this information in order to perform their job (reconstruction, simulation, etc.). To provide this information, there needs to be a sub-detector specific part that understands the sub-detector in question and uses a set of common services. The detector description we are providing in GAUDI is nothing else than a framework for developers to provide the specific detector information to algorithms by using as much as possible common or generic services.

8.2  Detector Description Database

The detector description database (DDDB), see Figure 8 , includes a physical and a logical description of the detector. The physical description covers dimensions, shape and material of the different types of elements from which the detector is constructed. There is also information which corresponds to each element which is actually manufactured and assembled into a detector, for example the positioning of each element. Both active and passive elements should be included. The description of active elements should allow for the specification of deficiencies (dead channels), alignment corrections, etc. and also detector response characteristics, e.g. energy normalization in calorimeters, drift velocity in gas chambers.

Figure 8 Overview of the Detector Description model.

 

The logical description provides two main functions. The first is a simplified access to particular parts of a physical detector description. This could be a hierarchical description where the a given detector setup is composed of various sub-detectors, each of which is made up of a number stations, modules or layers, etc. and there would be a simple way for a client to use this description to navigate to the information of interest. The second function of the logical description is to provide a means of detector element identification. This allows for different sets of information which are correlated to specific detector elements to be correctly associated with each other

In a detector description, the definition of the detector elements and the data associated to their physical description may vary over time, for instance due to real or hypothetical changes to the detector. Each such change should be recorded as a different version of the detector element. Additionally, it should be possible to capture for an entire description a version of each of the elements and associate a name to that set. This is similar to the way CVS allows one to tag a set of files so that one does not need to know the independent version numbers for each file in the set.

8.3  Using the Detector Data transient store

8.3.1  Structure of the transient store

The transient representation of the detector description is implemented as a standard GAUDI data store. Refer to Chapter 6 for general information on how to access data in stores. The structure of the detector transient store is represented in Figure 9 . There are various branches in the hierarchical tree structure and probably there will be more of them defined in the future.

At the present there are three top level catalogs in the transient store.The main catalog, called "Structure" contains the logical structure of the detector identified by the "setup name" i.e. "LHCb" containing the description of the detector and this catalog is used for identification and navigation purposes. Other catalogs are the palette of logical volumes and solids, called "Geometry", used for the geometry description and the palette of materials, called "Materials", used to describe the material properties of the solids needed for the detector simulation, etc.

Figure 9 The structure of part of the LHCb detector data transient store.

 

8.3.2  Accessing detector data in the transient store

An algorithm that needs to access a given detector part uses the detector data service to locate the relevant DetectorElement . This operation of locating the required detector description object can be generally done during the initialization phase of the algorithm. Contrary to the Event Data, the Detector Data store is not cleared for each event and the references to detector elements remains valid and are updated automatically during the execution of the program. Locating the relevant detector element is done using the standard IDataProviderSvc interface as is shown in the next code fragment.

The user uses the accessor detectorDataService() to obtain a reference to the detector data service and passes it to smart data pointer. Use of smart pointers is the preferred way for retrieving detector data objects from persistent storage. This method is much safer than using the retrieveObject() method of the service, since all casting is already done, so the user can work with the retrieved objects immediately.

Listing 12 Retrieving a detector element by using smart pointers

 
 
SmartDataPtr<DetectorElement> vertex( detectorDataService(), 
                                        "/dd/Structure/Vertex/VStation01"); 
if( !vertex ) { 
  // Error, detector element has not been retrieved 
}

Similarly the user can retrieve an array of such references. The following code fragment can be used to prepare an array with pointers to all of the Muon stations. Here we use an STL vector of pointers to DeMuonStation objects to store the retrieved Muon stations.

Listing 13 Retrieving a vector of detector elements using smart references

 
 
std::vector<DeMuonStation*> d_stations; 
 
SmartDataPtr<DetectorElement> stations(detDataService(), 
                                     "/dd/Structure/LHCb/Muon/Stations" ); 
if( !stations ) { 
  return StatusCode::FAILURE; 
} 
   
/// Loop over all the muon stations found in the detector model 
for ( DataObject::DirIterator d =  stations->dirBegin(); 
                              d != stations->dirEnd(); 
                                d++ )                                       
{ 
  SmartDataPtr<DeMuonStation> s( detDataService(),(*d)->fullpath() ); 
  if( !s ) { 
    return sc; 
  } 
  d_stations.push_back( s ); 
}

8.3.3  Using the DetectorElement class

Since the implementation in Gaudi release 2, the functionality of the DetectorElement has gone through many improvements. The interface IDetectorElement has been developed for the DetectorElement class. This interface has activated only the already known geometry() accessor method. The rest of the interface will be implemented in the next releases of the detector description package. In addition, a new IValidity interface has been defined. This interface is used to check if the detector element is synchronized with the current event. If the detector element contains information no longer valid at the time the current event was generated, its content must be updated from the persistent storage. In the current implementation it is not foreseen for end users to use this interface directly, so only the geometry part is described in this section.

The accessor method geometry() gives access to geometry information offered by the interface of type IGeometryInfo . This interface allows the retrieval of a reference to a logical volume associated with the given detector element, its material property, the position in the geometrical hierarchy. In addition to that you can ask it questions like:

  1. Transformation matrix from the Global to the Local Reference system
  2. Transformation matrix from the Local to the Global Reference system
  3. Perform transformation of point from the Global to Local Reference system
  4. Perform transformation of point from the Local to Global Reference system
  5. Name of daughter volume (of current volume) which contains given (global) point
  6. Get a pointer to daughter volume which contains given (global) point
  7. Name of daughter volume (at deeper hierarchical level) which contains given point
  8. Get a pointer to daughter volume (on deeper level) to which contains given point
  9. Get the exact full geometry location 1
  10. Whether the given point is inside the associated logical volume or not
  11. A pointer to the associated logical volume

For example:

Listing 14 Getting pointer to a logical volume and retrieving its material property

 
 
SmartDataPtr<DetectorElement> vs(detDataService(), 
                                    "/dd/Structure/LHCb/Vertex/VStation01"); 
if( !vs ) { 
  return StatusCode::FAILURE; 
} 
/// Report the material and its radiation length 
ILVolume* stvol = vs->geometry()->lvolume(); 
log << MSG::INFO << vs->fullpath() << " is made of " << stvol->materialName() 
    << " with radiation length " << stvol->material()->radiationLength() 
    << endreq;

8.4  Persistent representation

In the current release of the framework we offer a temporary solution for describing and storing the detector description (logical description and geometry). We expect in future releases to upgrade this to use a proper object persistency based on an object oriented database, for example ObjectivityDB.

The current implementation is based on text files whose structure is described by XML (eXtendible Markup Language), a standard language which allows the definition of custom tags, unlike the fixed set of tags of HTML used for WWW. XML files are understandable by humans as well as computers. Data in XML are self-descriptive so that by looking at the XML data one can easily guess what the data mean. Unlike the HTML tags, tags in XML do not define how to render or visualize the data. This is left to an application which understands the data and can visualize them if wanted. An advantage of XML is that there exists plenty of software which can be used for parsing and analysing, as it is an industry standard.

8.4.1  Brief introduction to XML

8.4.1.1  XML Basics

XML is extendible, meaning that a user can define his own markup language with his own tags. The tags define what the data they represent or contain mean. They act as data describers. For example, Listing 15 : shows the XML file which describes an e-mail.

Listing 15 Simple XML file describing an e-mail

 
 
<?xml version=`1.0' encoding=`UTF-8'?> 
<!-- This is an example of XML --> 
<Email> 
  <TimeStamp time="11:38:43" date="22/11/1999" /> 
  <Sender>sender@cern.ch</Sender> 
  <Recipient>recipient@cern.ch</Recipient> 
  <Subject>Lunch...</Subject> 
  <Body> Could we meet at 14:00? 
    <Signature>Sender's signature</Signature> 
  </Body> 
</Email>

At the first look this markup language looks like screwed up HTML. This is because both HTML and XML have their roots in SGML, but they are used for different purposes. From the example above it's not clear how to present the data described there nor how to visualize them. What is clear however is the meaning of the data items encoded in XML. Thus one can easily recognize the data items and guess what they mean. On the other hand it is relatively easy to instruct a computer program what to do with the given data item according to the XML markup elements it is encapsulated in. Let us analyse the example shown above.

8.4.1.2  XML components

XML declaration

must be at the beginning of each XML document. It is the first line in the example. It says that this file is an XML file conforming to the XML standard version 1.0 and is encoded in UTF-8 encoding. The encoding is very important because XML has been designed to describe data using the Unicode standard for text encoding. This means that all XML documents are treated as 16 bit Unicode characters instead of usual ASCII. So, even if you write your XML files using 7 or 8 bit ASCII, all the XML applications will work with it as with 16 bit Unicode XML data. The encoding information is important, for example when an XML document is transferred over the Internet to some other country where a different encoding is used. If the receiving application can guess the XML encoding from the received file, it can apply transcoding methods to convert the file into proper local encoding, thus preserving readability of the data.

XML comments

look like comments in SGML or HTML. They start with <!-- and end with -->. Comments in XML cannot be nested.

XML elements

are the markup components describing data in XML. In the example we had the following XML elements: Email, TimeStamp, Sender, Recipient, Subject, Body, Signature. The very basic and mandatory rule of XML is that all XML element tags must nest properly and there must be only one root XML element at the top level of each XML document, which contains all the others. Proper nesting means that each XML element has its opening and closing tag and the closing tag must appear before the parent element's closing tag, as shown in Listing 16 . Following these rules one can always produce well-formed XML documents.

Listing 16 XML elements syntax and proper vs. invalid nesting

 
 
<?xml version='1.0' encoding='UTF-8' standalone='yes'?> 
<!-- Root tag is top level root element of XML file --> 
<Root> 
  <!-- Elements which are empty --> 
  <EmptyElement /> 
  <EmptyWithAttributes attr1="first" attr2='second' /> 
  <!-- Elements having content model --> 
  <ProperNesting> <Something>In</Something> </ProperNesting> 
  <WRONGNESTING> <BADTHING>huhu </WRONGNESTING> </BADTHING> 
</Root>

XML elements can have attributes and a content. Attributes usually describe the properties of the given element. The value of the attribute follows the assignment operator and is enclosed inside double or single quotes.In the content can appear text data or other properly nested elements. The text data and nested elements can be mixed inside the content.

8.4.1.3  Well formed versus Valid XML documents

A well formed XML document is any XML document which follows the rules described in the previous section. However this is not sufficient in some cases. Inside an XML document you can have any XML tag you can imagine. This is not harmful to XML itself but makes it impossible to process such a document with a computer program and makes it very hard to maintain the program to keep it synchronised with all the new tags users invent. For a well formed XML document is not possible to check or validate that the document contains only the tags which make sense or have valid content. For that purpose there exists a notation called Document Type Definition (DTD) which comes from SGML world. This notation permits the definition of a grammar (a valid set of tags, their contents and attributes) which allows then to perform the validation of XML documents, i.e. whether the document contains the XML tags which belong to the set of tags defined by its associated DTD. In addition, the validating application can check whether the tags contain only allowed tags or text data, and whether the tags use only attributes defined for them by the DTD. The validation process can can also perform normalization of attributes, i.e. assign default values to attributes that the user has omitted because they are described as optional or with a fixed value in the DTD.

Important note: the default behaviour of the validating application, recommended by the XML standard, is to stop parsing of an XML document in case of an error. This is because the XML files describe data and an error in XML means corrupted data.

8.4.2  Working with the persistent detector description in XML

In this section we describe how to create or update the XML data files used by the detector description database. We will go through all available XML elements defined for the detector description, explain their XML syntax and show how to use them. For convenience we have included pseudo UML diagrams showing content model definitions of the XML tags. This approach has been chosen because it is easier to understand the graphical input than raw DTD definitions. Here follows a brief explanation how to read these pseudo UML diagrams:

8.4.2.1  Defining the top level structure

To fulfil the XML basic rule that each XML document must have only the one root XML element we have defined the element DDDB, see Figure 10 .

Figure 10 Content model definition of the root element for detector description

 

This element must be present in each of the XML files created for the detector description. This element is so defined that it can contain all the important elements needed for detector description and thus the database can be spread over multiple XML files. The DDDB element can contain one or more of the following elements: catalog, catalogref, detelem, logvol, material. Each of these elements will be described in detail later

The detector description in XML requires a bootstrap file which contains a definition of the database root and a definition of the top level catalogs mentioned above. This done in a flexible way to make it possible to have multiple bootstrap files. This can be done in the job options by setting the application manager properties DetDbLocation and DetDbRootName. They allow to switch from one bootstrap file to another and to switch between root nodes. The bootstrap file must have defined the root node catalog as the only child of the DDDB element. Inside the root node catalog the top level catalogs can be defined according to the required content. See the Listing 17 for an example.

Listing 17 Example of a boostrap file for the detector description

 
 
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE DDDB SYSTEM "xmldb.dtd"> 
<DDDB> 
  <catalog classID="3" name="dd"> 
    <catalogref href="catalogs.xml#Structure" /> 
    <catalogref classID="3" href="catalogs.xml#Materials" /> 
    <catalog name="Geometry"> 
      <logvolref href="geometry.xml#lvLHCb" /> 
      <logvolref href="geometry.xml#lvVertex" /> 
      <logvolref href="geometry.xml#lvVStation" /> 
    </catalog> 
  </catalog> 
</DDDB>

In the example, the root nodes catalog /dd and its three top level catalogs for logical detector description, geometry and materials are defined. Note that some of the catalog and catalogref tags have not specified the classID attribute. This shows how the validation can reduce the amount of the text in XML because these values are automatically included after the document has been validated against the DTD file xmldb.dtd specified in the DOCTYPE section.

The catalog and catalogrefs are used as bookshelves or references to bookshelves respectively to achieve a possibility to split the XML database into logical partitions. The catalogref element acts as forward reference saying where to find the given catalog definition. This tag is one of the XML references defined for the detector description. All of them have almost the same usage and syntax. The common things they have are attributes for class ID and hyperlink reference. The difference is the value of the class ID of the objects they point to, also some of them may contain other elements. The hyperlink is in general specified using the format:

protocol 2 ://hostname/path/to/the/file.xml#ObjectID

where protocol and hostname parts can be omitted if the file resides on the local host. If the file.xml is omitted as well this means that the referred object is located in the same file. For content model definitions of the catalog and catalogref elements see Figure 11 .

Figure 11 Content model definition of the catalog and catalogref elements

 

8.4.2.2  Defining detector elements

Figure 12 shows the content model definition of the detelem element and its child elements.

Figure 12 Content model definition of the detelem element

 

The detelem element has a sequence of tags which must appear in the same order shown on the diagram (author, version, geometryinfo, detelemref, specific). The child elements author, detelemref and specific are optional so if they are not present the content is still valid. The #PCDATA stands for "parsed character data" which is text 3 .

Listing 18 shows the XML definition of the LHCb detector containing the author of this definition, the version, geometry information about the associated logical volume and two sub detectors of the LHCb detector.

Listing 18 Example of a detector element definition in XML

 
 
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE DDDB SYSTEM "xmldb.dtd"> 
<DDDB> 
  <detelem classID="2" name="LHCb" type="passive"> 
    <author>Author Name</author> 
    <version>0.1</version> 
    <geometryinfo logvol="/dd/Geometry/lvLHCb"/> 
    <detelemref classID="9999" href="vertex.xml#Vertex"/> 
    <detelemref classID="2"    href="muon.xml#Muon"/> 
  </detelem> 
</DDDB>

The example shows that the definition of the sub detectors can be found in vertex.xml or muon.xml respectively. The standard class ID for detector element is 2, but in the example the class ID of the Vertex sub-detector is set to 9999 which means that this sub-detector is customized by the user and contains specific information. How to customize detector elements will be described in section 8.4.3.2 .

The geometryinfo element definition says that the LHCb detector has an associated logical volume with the given name on the transient store. The logical volume should be defined somewhere else in the XML and is retrieved automatically when the user asks for it via the IGeometryInterface returned by the geometry() accessor method. There two more attributes missing in the geometryinfo definition. They are supporting detector element and replica path. The supporting detector element is one of the parent detector elements sitting on the same branch in the logical detector description hierarchy. It can be a direct parent or a detector element 3 levels up. Its role is to help in finding of physical volume location in the geometry hierarchy for the detector element which is referring to it. The replica path is a sequence of numbers which is used by the algorithm looking for the physical volume location in the geometry hierarchy. This sequence is composed of the number of daughter volume IDs which must be followed from a logical volume of supporting detector elements down through the hierarchy. Its usage is shown in Listing 22 .

Finally, the specific child element can have anything inside its content and is provided to allow customizing of the detector elements. Users can define their own XML tags which describe very specific features or characteristics of the detector. The customisation of detector elements is described in section 8.4.3.2 .

8.4.2.3  Defining logical volumes

To define a logical volume in XML the logvol element is used, see Figure 13 .

Figure 13 Content model definition of logvol element

 

The complete logical volume definition includes the name of the logical volume, its material, class ID can be omitted (because the DTD defines its fixed value), its solid (shape) and list of daughter volumes represented here as physical volumes. The diagram shows all attributes for solids but in this context, when the definition of logical volume is made, the attributes for position and rotation of the solids can be left out. They are used for construction of boolean solids described later in this section. Listing 19 shows an example of a logical volume in XML.

The example shows two logical volumes lvLHCb and lvVertex. The former volume has he material Vacuum and a solid defined as a box with dimensions 5000 x 5000 x 6000. Then it has ascribed one daughter volume lvVertex positioned inside the lvLHCb volume without rotation and translated along the z-axis by 200. The latter volume is actually the definition of the daughter volume which is made of material Silicon and solid tube (cylinder) and has one daughter volume lvVStation

.

Listing 19 Example of a logical volume definition in XML

 
 
<?xml version="1.0" encoding="UTF-8" standalone="no"?> 
<!DOCTYPE DDDB SYSTEM "xmldb.dtd"> 
<DDDB> 
  <logvol name="lvLHCb" material="Vacuum"> 
    <box name="caveBox" sizeX="5000" sizeY="5000" sizeZ="6000"/> 
    <physvol name="VertexSubsystem" x="0" y="0" z="200" logvol="lvVertex"/> 
  </logvol> 
  <logvol name="lvVertex" material="Silicon"> 
    <tubs name="vertexTubs" sizeZ="600" outerRadius="20" innerRadius="0" 
                           startPhiAngle="0" deltaPhiAngle="360"/> 
    <physvol name="vStation01" x="0" y="0" z="-200" logvol="lvVStation" /> 
  </logvol> 
</DDDB>
Boolean solids

The current implementation allows to create boolean solids as a union, intersection or subtraction of several simple solids. The user has to start with the so called main solid and all the other solids participating in the boolean solid are positioned relative to the main solid. In this context the position and rotation attributes of solids are applied together with their dimensions attributes. Listing 20 show how to create a simple union of solids.

Listing 20 Example of boolean solid in XML

 
 
<?xml version="1.0" encoding="UTF-8" standalone="no"?> 
<!DOCTYPE DDDB SYSTEM "xmldb.dtd"> 
<DDDB> 
  <logvol name="lvSampleBoolean" material="Vacuum"> 
    <union name="BoxUnion"> 
      <box name="MainBox" sizeX="10" sizeY="10" sizeZ="10"/> 
      <box name="Box2" sizeX="10" sizeY="10" sizeZ="10" 
                       x="0" y="0" z="10" /> 
    </union> 
    <physvol name="SampleChild" x="0" y="0" z="200" logvol="lvChild"/> 
  </logvol> 
</DDDB>

The example shows the union of two boxes where the first one is the main solid and the second one is positioned just next to the main solid along the z-axis.

8.4.2.4  Defining materials

Figure 14 Content model definition of material element

 

Materials are needed by logical volumes. Materials can be defined as isotopes, elements or mixtures. Elements can be optionally composed of isotopes. Mixtures can be composed of elements or of other mixtures. Composition of elements is done always by specifying the fraction of the mass for each of the isotopes of the element. For a mixture the user can specify either composition by number of atoms of by fraction of the mass for each of the elements or mixtures. The listing shows how to define a material in XML.

Listing 21 Example of a material in XML

 
 
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE DDDB SYSTEM "xmldb.dtd"> 
<DDDB> 
  <material name="Argon_CF_4_CO_2" classID="&mixture;"> 
    <density>2.14160E-3</density> 
    <materialref classID="&element;" href="#Argon"> 
      <fraction> <mass n="0.3"/> </fraction> 
    </materialref> 
    <materialref classID="&mixture;" href="#CF_4"> 
      <fraction> <mass n="0.2"/> </fraction> 
    </materialref> 
    <materialref classID="&mixture;" href="#CO_2"> 
      <fraction> <mass n="0.5"/> </fraction> 
    </materialref> 
  </material> 
</DDDB>

8.4.3  Customizing a detector element

The specific detector description can be made available to algorithms by customizing the generic detector element. Customizing is done by inheriting the specific detector class from the generic DetectorElement. The sub-detector specialist can provide specific answers to algorithms based on a combination of common parameters (general geometry, material etc.) and some specific parameters. For example, an algorithm may want to know what are the coordinates in the local system of reference of a given cell or wire number. The specialist can "code" the answer by using a minimal number of parameters specific to the detector structure.

Step 1: Define your specific part in XML

Listing 22 has at the begins with a new section. This section is called "local DTD". It can be used in cases where the common DTD is not enough and a new set of tags has to be defined. We have reserved a place holder for such new tags, the already mentioned element called specific. This element can contain any XML tag and thus we can extend easily the common set of tags by user defined ones placed inside the specific element in the detector element definition in XML. What is done in the local DTD section is the definition of two new elements called Al_plate_thickness and pad_dimensions. We used an ELEMENT keyword of the DTD notation to do that. A keyword ATTLIST is used to define attributes for the new elements. We have defined the required attribute value for the Al_plate_thickness element and required attributes padX and padY attributes for the pad_dimensions element. All the attributes are defined of type CDATA which means text string. All of the attributes are required.

Listing 22 Defining the user tags which can be used inside the specific element

 
 
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE DDDB SYSTEM "xmldb.dtd" [ 
  <!--The folowing elements can be placed inside specific element--> 
  <!-- Aluminium plate thickness --> 
  <!ELEMENT Al_plate_thickness EMPTY> 
  <!ATTLIST Al_plate_thickness value CDATA #REQUIRED> 
  <!-- Dimensions of pads --> 
  <!ELEMENT pad_dimensions EMPTY> 
  <!ATTLIST pad_dimensions padX CDATA #REQUIRED> 
  <!ATTLIST pad_dimensions padY CDATA #REQUIRED> 
]> 
<DDDB> 
  <detelem classID="2" name="Muon"> 
    <author>Radovan Chytracek</author> 
    <version>0.1</version> 
    <geometryinfo logvol="/dd/Geometry/lvMuon" 
                  support="/dd/Structure/LHCb" 
                  rpath="1" /> 
    <detelemref classID="2" href="#Stations"/> 
  </detelem> 
  <detelem classID="2" name="Stations"> 
    <author>Radovan Chytracek</author> 
    <version>0.1</version> 
<!-- No geometry information is specified since it is just ghost --> 
    <geometryinfo /> 
    <detelemref classID="9990" href="#MStation01"/> 
  </detelem> 
  <detelem classID="9990" name="MStation01"> 
    <author>Radovan Chytracek</author> 
    <version>0.1</version> 
    <geometryinfo logvol="/dd/Geometry/lvMStation01" 
                  support="/dd/Structure/LHCb/Muon" 
                  rpath="0" /> 
    <specific> 
      <Al_plate_thickness value="1.1111" /> 
      <pad_dimensions padX="2" padY="4" /> 
    </specific> 
  </detelem> 
</DDDB>

Later in the example these new elements are placed inside the specific element as the custom data defined by the user.

8.4.3.1  Step 2: Define your own detector element

Listing 23 shows the C++ definition of a user defined detector element which makes use of the new elements inside the specific element in XML.

Listing 23 User defined detector element

 
 
#ifndef DDEXAMPLE_DEMUONSTATION_H 
#define DDEXAMPLE_DEMUONSTATION_H 1 
// Include files 
#include "Gaudi/DetectorDataSvc/DetectorElement.h" 
 
// External declarations 
extern const CLID& CLID_DEMuonStation; 
 
class DeMuonStation: public DetectorElement 
{ 
public: 
  // Constructors 
  DeMuonStation(); 
  DeMuonStation( double t, double x, double y ); 
 
  // Destructor 
  ~DeMuonStation(); 
 
  // Retrieve refrence to class identifier 
  virtual const CLID& clID() const; 
 
  // Get/Set thickness 
  double thickness(); 
  void   setThickness( double t ); 
 
  // Get/Set pad dimensions 
  double padx(); 
  double pady(); 
  void   setPadx( double x ); 
  void   setPady( double y ); 
 
private: 
 
  double    m_thickness; // Aluminium plate thickness 
  double    m_padx;      // Pad X dimension 
  double    m_pady;      // Pad Y dimension 
}; 
 
#endif    // DDEXAMPLE_DEMUONSTATION_H

The user inherits from DetectorElement class and adds new data members according to the new set of user defined XML elements.

8.4.3.2   Step 3: Write your user defined XML converter

To be able to retrieve the data inside specific element, a user defined converter is required which knows what to do with the elements there. To write such a converter the user has to inherit and implement a set of callbacks of the IUserSax8BitDocHandler interface provided for this purpose. A very important method to be implemented is the createObj() method from the Converter base class. This is shown in the DDexample source files in the standard set of Gaudi examples.

Listing 24 shows the interface to be implemented.

Listing 24 Example of the user defined XML converter

 
 
class XmlMuonStationCnv : public Converter, 
                          virtual public IUserSax8BitDocHandler 
{ 
// ----------------------------------------------------------------------- 
/// Implementations of the Converter interface 
// ----------------------------------------------------------------------- 
... removed stuff ... 
// ----------------------------------------------------------------------- 
/// Implementation of the User SAX DocumentHandler interface 
// ----------------------------------------------------------------------- 
/// Start of the XML document callback 
  virtual void uStartDocument() { } 
/// End of the XML document callback 
  virtual void uEndDocument() { } 
/// Parsed character data callback 
virtual void uCharacters(const char* const chars,const unsigned int length); 
/// White space characters callback 
virtual void uIgnorableWhitespace(const char* const chars, 
                                  const unsigned int length ); 
/// Start of the XML element callback 
virtual void uStartElement(const char* const name, 
                           XmlCnvAttributeList& attributes); 
/// End of the XML element callback 
virtual void uEndElement( const char* const name ); 
 
private: 
/// Our "quazi base class" generic detector element converter 
IConverter*       m_deCnv; 
/// We have to keep the DataObject pointer to be visible inside callbacks 
DeMuonStation*    m_dataObj; 
};

Listing 25 shows the example of the uStartElement() callback implementation. For more details please see the DDexample source files in the standard set of Gaudi examples

Listing 25 Example of the callback implementation to handle XML parser events and retrieve data from new defined XML elements in specific section

 
 
/// Start of the XML element callback 
void XmlMuonStationCnv::uStartElement( const char* const name, 
                                     XmlCnvAttributeList& attributes) 
{ 
  MsgStream log( messageService(), "XmlMuonStationCnv" ); 
  std::string tagName( name ); 
  if( tagName == "Al_plate_thickness" ) { 
    // get a value of the 'value' attribute 
    std::string value = attributes.getValue( "value" ); 
    if( !value.empty() ) { 
      atof(value.c_str()) << endreq; 
      m_dataObj->setThickness( atof(value.c_str()) ); 
    } 
  } 
  else if( tagName == "pad_dimensions" ) { 
    // get a values of the 'padX' and 'padY' attributes 
    std::string padX = attributes.getValue( "padX" ); 
    std::string padY = attributes.getValue( "padY" ); 
    if( !padX.empty() && !padY.empty() ) { 
      m_dataObj->setPadx( atof(padX.c_str()) ); 
      m_dataObj->setPady( atof(padY.c_str()) ); 
    } 
  } 
  else { 
    // Unknown tag, a warning message can be issued here 
    ; 
  } 
}
  1. 1. This operation can be time consuming!

2. The current implementation supports only file:// protocol, this is due to limited support in the XML4C library from IBM

3. Text format of #PCDATA content in XML is verbatim so all white space characters are preserved