|Offline Documentation: [Offline Category] [FAQ] [Howto] [Reference] [Manual]|
|This article is part |
of the Offline Documentation
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
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
- Acrylic vessel
- Liquid scintilator layer
- Acrylic vessel
- Gd doped LS.
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
- 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><...>
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.
The "structure" hierarchy enumerates important physical volumes using
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.
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/PmtSurfacePropertieshods the PMT-Water surface definition.
- Holds a hierarchy mimicking the containment structure of all important volumes. For example, the far OWS is located by
Note: actual paths may differ since these examples were written. You can explore available paths with
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.xmlthe main entry to the geometry hierarchy
structure.xmlthe main entry to the structure hierarchy
materials/materials.xmlthe main entry to the materials
- main element subdirectories
- XML describing each main element is in its own subdirectory. These mirror the subdirectories in
structure.xmlfile 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,
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:
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"]> <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:
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
/dd/Geometrycatalog with which you can define a
- added to
/dd/Structurecatalog with which you can define
- added to
DDDB/AD/???.xmland inside the
<!DOCTYPE>in order to define an
- added to
DDDB/AD/???.xmlabove the definition for
lv???logical volume and can be used to either place an
- added to
DDDB/AD/???.xmland allows for injecting XML into the logical volume context (ie, to define a physical volume).
??? 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
ENTITYmechanism. (The Xerces XML parser fails to pass this syntax).
|Offline Software Documentation: [Offline Categories] [FAQ] [Offline Manual Category]|