Tutorial:DetDesc/XML Files

From Daya Bay

Jump to: navigation, search

Detector Description XML Files.

The XML Schema

A "schema" is simply a formal statement as how some kind of information is organized. In the case of XML it says what elements or entities (ie, XML tags) can exist, what others they can contain and what attributes an element can have. The schema is represented in XML which is itself in a special schema called Document Type Definition (DTD).

For DetDesc files there are several such schemas, each in their own .dtd file. You can learn to read and understand them directly or you can refer to the LHCb Detector Description DTD manual. Some of the basics are reproduced below.

Basics of the Schema

There are three main schema to be concerned of:

structure.dtd 
defines the XML format for the information that organizes the Transient Detector Store (TDS).
materials.dtd 
defines the XML format for the information that defines all materials used in the detectors.
geometry.dtd 
defines the XML format for the information that describes the geometry containment hierarchy.


materials.dtd

This schema states how information about materials is formated. An example is:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE materials SYSTEM "../DTD/materials.dtd">
<materials>
  <catalog name="Materials">
    <element density="0.14300e-02*g/cm3" name="Oxygen" symbol="O">
      <atom A="15.999*g/mole" Zeff="8.0000" />
    </element>
    <element density="0.70800E-01*g/cm3" name="Hydrogen" symbol="H">
      <atom A="1.00794*g/mole" Zeff="1.0"/>
    </element>
    <material density="1.0000*g/cm3" name="Water">
      <component name="Hydrogen" natoms="2"/>
      <component name="Oxygen" natoms="1"/>
    </material>
  </catalog>
</materials>

This is now broken down:

Boilerplate telling what XML version and encoding is used.:

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

Define the DTD so parsers can validate. Path is relative to current file location:

<!DOCTYPE materials SYSTEM "../DTD/materials.dtd">

Start materials section and place it in a container in the TDS at /dd/Materials where /dd is defined by the catalog that contains this one.

<materials>
  <catalog name="Materials">

Define two elements

    <element density="0.14300e-02*g/cm3" name="Oxygen" symbol="O">
      <atom A="15.999*g/mole" Zeff="8.0000" />
    </element>
    <element density="0.70800E-01*g/cm3" name="Hydrogen" symbol="H">
      <atom A="1.00794*g/mole" Zeff="1.0"/>
    </element>

Combine them into a material

    <material density="1.0000*g/cm3" name="Water">
      <component name="Hydrogen" natoms="2"/>
      <component name="Oxygen" natoms="1"/>
    </material>
  </catalog>
</materials>

geometry.dtd

This schema defines how information about the geometry is formatted. An example is:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE DDDB SYSTEM "../DTD/geometry.dtd"
  [<!ENTITY SiteParameters SYSTEM "parameters.xml">]>
<catalog name="Geometry">
  <logvol name="lvSimpleBox" material="Water">
    <box name="simple_box" sizeX="10*m" sizeY="10*m" sizeZ="10*m"/>
    <physvol name="Chamber1" logvol="/dd/Geometry/Chambers/lvChamber">
      <posXYZ x="0*m" y="0*m" z="ChamberOffset"/>
      <rotXYZ rotX="0*deg" rotY="0*deg" rotZ="ChamberRotation"/>
    </physvol>
    <physvol name="Chamber2" logvol="/dd/Geometry/Chambers/lvChamber">
      <posXYZ x="0*m" y="0*m" z="-ChamberOffset"/>
      <rotXYZ rotX="0*deg" rotY="0*deg" rotZ="-ChamberRotation"/>
    </physvol>
  </logvol>
</catalog>

This brings in several new features. The first is the ability to include other XML files. First the file is declared as an "external entity":

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE DDDB SYSTEM "../DTD/geometry.dtd"
  [<!ENTITY SiteParameters SYSTEM "parameters.xml">]>

and then included:

&SiteParameters;

Stare a /dd/Geometry catalog

<catalog name="Geometry">

Define a top level logical volume which will be accessible in the TDS at /dd/Geometry/lvSimpleBox and made from a box of water:

  <logvol name="lvSimpleBox" material="Water">
    <box name="simple_box" sizeX="10*m" sizeY="10*m" sizeZ="10*m"/>

It contains two physical volumes, each consisting of the same logical volume lvChamber (defined elsewhere), which are placed based on parameters defined in the parameters.xml file:

    <physvol name="Chamber1" logvol="/dd/Geometry/Chambers/lvChamber">
      <posXYZ x="0*m" y="0*m" z="ChamberOffset"/>
      <rotXYZ rotX="0*deg" rotY="0*deg" rotZ="ChamberRotation"/>
    </physvol>
    <physvol name="Chamber2" logvol="/dd/Geometry/Chambers/lvChamber">
      <posXYZ x="0*m" y="0*m" z="-ChamberOffset"/>
      <rotXYZ rotX="0*deg" rotY="0*deg" rotZ="-ChamberRotation"/>
    </physvol>
  </logvol>
</catalog>

The parameters.xml is simple:

<?xml version="1.0" encoding="UTF-8"?>
<parameter name="ChamberOffset" value="1*m"/>
<parameter name="ChamberRotation" value="15*deg"/>

structure.dtd

This schema is for describing what important, physical volumes exist. It also defines the top level "/dd" catalog.

  <catalog name="Structure">
    <detelem name="World" type="passive">
      <geometryinfo lvname="/dd/Geometry/lvSimpleBox"/>
      <detelem name="

File Organization

File locations

The files are organized in a directory hierarchy that mirrors the /dd/Geometry TDS hierarchy. Namely, all files defining volumes under

/dd/Geometry/Pool

will reside in

XmlDetDesc/DDDB/Pool/

The directories enumerate the major sections of the geometry:

DayaBay/ 
world volume and positions of sites and reactors
Sites/ 
halls and rock neighborhood
Pool/ 
inner/outer water shield
AD/ 
anti-neutrino detector
RPC/ 
RPC planes.

File types

Each directory will have the files:

geometry.xml 
main entry point for populating this subdirectory of /dd/Geometry
structure.xml 
main entry point for populating this subdirectory of /dd/Structure
parameters.xml 
(optional) any parameters used in the above files
ELEMENT.xml 
(optional) break out any large (many XML tags) parts into their own files
Personal tools