Offline Documentation: [Offline Category] [FAQ] [Howto] [Reference] [Manual]

Offline Documentation

This article is part
of the Offline Documentation

Other pages...

Offline Category
FAQ
How Tos
Reference
Manual
Getting Started
Software Installation

Overview

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

dybgaudi/Detector/XmlDetDesc

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

lhcb/Det/DetDesc

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

/dd

Daya Bay Basics

Ignoring many details, the Daya Bay Experiment consists of:

Reactors: 3 (Daya Bay, Ling Ao 1, Ling Ao 2) each with 2 cores

Site: 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

Pool: 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.

AD: 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.

RPC

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:

materials: defines the elements, isotopes and materials and their optical properties that make up the detectors and the reactors.
geometry: 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.
structure: 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:

[PREFIX]<MAJOR ELEMENT><SUB ELEMENT><SUB SUB ELEMENT><...>

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

Examples:

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

Surfaces

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.

Hierarchies

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.

Conventions

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:

/dd/Materials/: 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.

/dd/Geometry/: 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.

/dd/Structure/: 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

nuwa.py -V

XML Files

Parameterization

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

Location

The XML files are located in

dybgaudi/Detector/XmlDetDesc/DDDB/

At top level exist:

dayabay.xml: 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:

/dd/Structure/daya-bay/far-rock/far-ows/far-curtain/far-iws

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:

/dd/Structure/daya-bay/far-rock/far-ade1/far-ad1-tank/far-ad1-oil

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".../>
    </catalog>
  </catalog>
</catalog>

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

/dd/DayaBay/Sites/lvNearSite

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

DayaBay/Site/parameters.xml

The sites are placed in

DayaBay/geometry.xml

with XML looking like:

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

<DDDB>

  &SiteParameters;

  <catalog name="DayaBay">
    <logvol name="lvDayaBay" material="Vacuum">
      <box name="world" sizeX="2400*m" sizeY="2400*m" sizeZ="500*m"/>
      
      <physvol name="DBNearSite"
              logvol="/dd/Geometry/Sites/lvNearSite">
        <posXYZ 
           x="DBNearSiteX-MidSiteX"
           y="DBNearSiteY-MidSiteY"
           z="DBNearSiteZ-MidSiteZ"/>
        <rotXYZ
           rotX="DBNearSiteRotX"
           rotY="DBNearSiteRotY"
           rotZ="DBNearSiteRotZ"/>
      </physvol>
      ...

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:

${NAME}

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:

${DD_GEOMETRY_EXTRA}: added to DDDB/geometry.xml inside the /dd/Geometry catalog with which you can define a <catalogref>

${DD_STRUCTURE_EXTRA}: added to DDDB/structure.xml inside the /dd/Structure catalog with which you can define <catalogref>

${DD_AD_???_EE}: added to DDDB/AD/???.xml and inside the <!DOCTYPE> in order to define an ENTITY.

${DD_AD_???_TOP}: added to DDDB/AD/???.xml above the definition for lv??? logical volume and can be used to either place an ENTITY.

${DD_AD_???_PV}: 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.

Caveats

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]

Detector Description

From Daya Bay

Contents