Detector Description
Offline Documentation: [Offline Category] [FAQ] [Howto] [Reference] [Manual] |
Offline Documentation |
This article is part of the Offline Documentation |
Other pages... |
Offline Category |
See also... |
This topic describes the Daya Bay detector description (geometry) packages, data files and organizational conventions.
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 hierarchystructure.xml
the main entry to the structure hierarchymaterials/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
andstructure.xml
file describing just this element - Zero or more parameters files
- one or more files describing the sub-elements
- A
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 anENTITY
.
${DD_AD_???_TOP}
- added to
DDDB/AD/???.xml
above the definition forlv???
logical volume and can be used to either place anENTITY
.
${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] |