Detector Description

From Daya Bay
Jump to navigation Jump to search
Offline Documentation: [Offline Category] [FAQ] [Howto] [Reference] [Manual]

Offline Documentation
This article is part
of the Offline Documentation
Other pages...

Offline Category
How Tos
Getting Started
Software Installation

See also...

General Help on this Wiki

This topic describes the Daya Bay detector description (geometry) packages, data files and organizational conventions.


The detector description (geometry) is defined in a set of XML files in the DDDB subdirectory of the package:


This information is parsed into C++ objects from the package:


These objects are available to Gaudi based code in the Transient Detector Store (TDS) via the root directory:


Daya Bay Basics

Ignoring many details, the Daya Bay Experiment consists of:

3 (Daya Bay, Ling Ao 1, Ling Ao 2) each with 2 cores
4 detector sites: two near (Daya Bay, Ling Ao) and one far plus potentially one mid.
  • A site is a large cube of rock that has been properly rotated and provides the local site coordinate system.
  • Each site of two main volumes, the Top and Bottom hall.
  • Top hall is a box of air and holds RPCs
  • Bottom hall is a box of rock (embedded in the site rock) and holds water pool and ADs
octagonal water pool fits exactly inside the Bottom Hall and from outside to in, consists of:
  • Tyvek Liner
  • Outer Water Shield (OWS)
  • Tyvek Curtain
  • Inner Water Shield (IWS) pool.
2 or 4 antineutrino detectors. From outside to in:
  • AD Envelope (ADE) a water cylinder
  • Tank cover
  • Steel tank
  • PMTs
  • Oil
  • Acrylic vessel
  • Liquid scintilator layer
  • Acrylic vessel
  • Gd doped LS.

DetDesc Basics

LHCb's DetDesc provides multiple, partially redundant hierarchies of information about the detector (and reactor) in memory (in the TDS).

There are three main parts to DetDesc information:

defines the elements, isotopes and materials and their optical properties that make up the detectors and the reactors.
describes the volumes, along with their solid shape, relative positioning, materials and sensitivity and any surface properties, making up the detectors and reactors. The geometry, like that of Geant4, consists of logical volumes containing other placed (or physical) logical volumes. Logical volumes only know of their children.
points out (logical) volumes of significant importance in the geometry.

Detector Description Organization

Volume Names

  • Logical volumes have a "lv" prefix.
  • Physical volumes have a "pv" prefix.
  • Detector Elements are lower case and use "-" to separate terms
  • The name is a made from a list of descriptions from general to specific. The most generic being the major element that the volume is part of.

So, in general:


With PREFIX = "lv" for logical volumes or "pv" for physical volumes (none for Detector Elements).


Pmt + Hemi(sphere) + Cathode. This is the logical volume for the photocathode of the hemispherical model of the PMT.
Far Pool + IWS. This is the physical volume for the inner water shield (IWS) of the far pool
far + ows. This is the detector element for the Far outer water shield (OWS).


There are three kinds of optical surfaces that can be defined

  • Perfectly smooth boundaries between two volumes with materials that have index of refraction defined
  • Non smooth, single sided (G4LogicalSkinSurface)
  • Non smooth, double sided (G4LogicalBorderSurface)

For a Geant4 based description of surfaces see this presentation (PDF)

For a DetDesc based description see the documents linked in the DetDesc section of Gaudi Learning Resources. In particular the DTD and "Optical Surfaces" document.


There are three types of hierarchy used to organize this information.

TDS Paths Locate TDS Objects

DetDesc objects in the TDS are referenced using a path, analogous to referencing a file in a Unix filesystem.

Filesystem Paths Locate XML Files

XML can reference XML in other files (in general, URLs).

Geometry Containment Locates Volumes

The parent-daughter volume relationship is another hierarchy accessed through the logical and physical volume objects.

Important Structure

The "structure" hierarchy enumerates important physical volumes using the DetectorElement objects.


The TDS and filesystem hierarchies are completely arbitrary and exist only to make it easier for users to interact with the data. In order to keep these views of the information organized several conventions must be followed with writing new or modifying existing description.

TDS Paths

There are three top level subdirectories:

Holds catalogs of defined materials and properties. Materials themselves are all in this directory. Properties are held in a subdirectory named after the material. For example /dd/Materials/WaterMaterials/ holds absorption and index of refraction property information.
Holds catalogs of volumes (specifically, logical ones). Each major part of the experiment should be in its own subdirectory and should not store volumes that are placed in any contained sub-part (they should be stored in the sub-parts own subdirectory). For example, the hemispherical PMT model's logical volume is at /dd/Geometry/PMT/lvPmtHemi. Any surface properties should be kept in a subdirectory. For example /dd/Geometry/PMT/PmtSurfaceProperties hods the PMT-Water surface definition.
Holds a hierarchy mimicking the containment structure of all important volumes. For example, the far OWS is located by /dd/Structure/daya-bay/far-rock/far-ows.

Note: actual paths may differ since these examples were written. You can explore available paths with -V

XML Files


Never use raw numbers except when defining a parameter. Parameters should be put in a special parameters.xml file that others can include.


The XML files are located in


At top level exist:

This is the main entry into the XML. It basically just includes:
  • geometry.xml the main entry to the geometry hierarchy
  • structure.xml the main entry to the structure hierarchy
  • materials/materials.xml the main entry to the materials
main element subdirectories
XML describing each main element is in its own subdirectory. These mirror the subdirectories in /dd/Geometry and contain:
    • A geometry.xml and structure.xml file describing just this element
    • Zero or more parameters files
    • one or more files describing the sub-elements

Structure: The Important Parts

The structure hierarchy lists the important sub-parts. You can think of it as a sub hierarchy of the full geometry that "bookmarks" important physical volumes but ignores volumes that:

  • Are not important for reconstruction (every nut and bolt)
  • Do not have to be given alignment offsets in the simulation

As said above this enumerates physical volumes. By convention use dash-separated lower case labels. For example, to locate an far IWS, one would have:


You must fully enumerate the hierarchy to the extent that one cares about applying alignment offsets. For example, if you do not care about alignments between water pool and AD Envelopes you can locate the ADs like:


Geometry: The Real Parts

Building the TDS Hierarchy

The full geometry description is organized in way that somewhat mirrors the structure. However, instead of focusing on important physical volumes, the layout is based on important logical volumes. References to volumes are through TDS paths with the top level being /dd/Geometry. The paths are constructed through catalog and, optionally, catalogref XML tags. For example:

<catalog name="dd">
  <catalog name="DayaBay">
    <catalog name="Sites">
       <logvol name="lvNearSite".../>

Any logical volume defined inside these nested catalogs will show up as:


and will be used when defining both Daya Bay and Ling Ao near sites (assuming they are truly identical, up to alignment offsets)).

Each element in the TDS path should be mirrored with a filesystem subdirectory holding a geometry.xml file.

Separation of Geometry Structure and Values

The geometry should be parametrized wherever possible. These parameters should be put in an parameters.xml file which is placed in the subdirectory holding the geometry to which they parametrize. For example, the exact locations of detector sites goes in


The sites are placed in


with XML looking like:

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



  <catalog name="DayaBay">
    <logvol name="lvDayaBay" material="Vacuum">
      <box name="world" sizeX="2400*m" sizeY="2400*m" sizeZ="500*m"/>
      <physvol name="DBNearSite"

Environment Variable Extension

Daya Bay's version of DetDesc extends LHCb's to allow environment variables to be used in the XML text. They must be written using the syntax:


Environment Variables for Inserting AD Geometry

In writing the Daya Bay description some special environment variables are added to allow for inserting additional geometry into an AD. Initially they were added to support the MCS geometry but may be used for other purposes. They are:

added to DDDB/geometry.xml inside the /dd/Geometry catalog with which you can define a <catalogref>
added to DDDB/structure.xml inside the /dd/Structure catalog with which you can define <catalogref>
added to DDDB/AD/???.xml and inside the <!DOCTYPE> in order to define an ENTITY.
added to DDDB/AD/???.xml above the definition for lv??? logical volume and can be used to either place an ENTITY.
added to DDDB/AD/???.xml and allows for injecting XML into the logical volume context (ie, to define a physical volume).

Here, ??? matches any of the three letter acronyms of the AD onion: ADE, SST, OIL, OAV, LSA, IAV or GDS.


  • This trick of using environment variables will not work from XML files that are resolved via the external ENTITY mechanism. (The Xerces XML parser fails to pass this syntax).
Offline Software Documentation: [Offline Categories] [FAQ] [Offline Manual Category]