From 733cafa06d35128cbfd7dbe799e4cfc4712ecec6 Mon Sep 17 00:00:00 2001
From: Markus Frank <Markus.Frank@cern.ch>
Date: Thu, 30 Mar 2023 16:22:04 +0200
Subject: [PATCH] Improve inline documentation at least for a few plugins
---
DDCore/src/plugins/DetElementVolumeIDs.cpp | 90 +++---
DDCore/src/plugins/ShapePlugins.cpp | 313 ++++++++++++++++++++-
DDCore/src/plugins/StandardPlugins.cpp | 133 ++++++---
3 files changed, 441 insertions(+), 95 deletions(-)
diff --git a/DDCore/src/plugins/DetElementVolumeIDs.cpp b/DDCore/src/plugins/DetElementVolumeIDs.cpp
index 665ae903e..644c2e5c9 100644
--- a/DDCore/src/plugins/DetElementVolumeIDs.cpp
+++ b/DDCore/src/plugins/DetElementVolumeIDs.cpp
@@ -14,7 +14,7 @@
#define DD4HEP_DETELEMENTVOLUMEIDS_H
// Framework include files
-#include <DD4hep/Detector.h>
+#include <DD4hep/DetElement.h>
#include <DD4hep/Volumes.h>
// C/C++ includes
@@ -22,21 +22,25 @@
/// Namespace for the AIDA detector description toolkit
namespace dd4hep {
- /// Helper class to assign volume identifiers to DetElements in a subdetector tree
+ /// Forward declarations
+ class Detector;
+
+ /// Actor class to assign volume identifiers to DetElements in a subdetector tree
/**
+ * During the tree traversal the encoding information is also accumulated
+ * in a map indexed by the DetElement.
+ *
* \author M.Frank
* \version 1.0
*/
class DetElementVolumeIDs {
private:
- using Chain = std::vector<PlacedVolume>;
-
/// Reference to the Detector instance
const Detector& m_detDesc;
- /// Node counter
- std::size_t m_numNodes = 0;
public:
+ /// Node counter
+ std::size_t numberOfNodes { 0 };
/// Encoding/mask for sensitive volumes
struct Encoding {
VolumeID identifier;
@@ -46,22 +50,22 @@ namespace dd4hep {
std::map<DetElement, std::vector<Encoding> > entries;
private:
+ using PlacementPath = std::vector<PlacedVolume>;
+
/// Scan a single physical volume and look for sensitive elements below
std::size_t scanPhysicalVolume(DetElement& parent,
DetElement e,
PlacedVolume pv,
Encoding parent_encoding,
SensitiveDetector& sd,
- Chain& chain);
+ PlacementPath& chain);
public:
/// Default constructor
DetElementVolumeIDs(const Detector& description);
- /// Access node count
- std::size_t numNodes() const { return m_numNodes; }
/// Populate the Volume manager
std::size_t populate(DetElement e);
};
-} /* End namespace dd4hep */
+} /* End namespace dd4hep */
#endif // DD4HEP_DETELEMENTVOLUMEIDS_H
//==========================================================================
// AIDA Detector description implementation
@@ -79,33 +83,15 @@ namespace dd4hep {
// Framework include files
#include <DD4hep/Printout.h>
#include <DD4hep/Factories.h>
+#include <DD4hep/Detector.h>
#include <DD4hep/DetectorTools.h>
#include <DD4hep/detail/DetectorInterna.h>
/// Namespace for the AIDA detector description toolkit
using namespace dd4hep;
-using Encoding = DetElementVolumeIDs::Encoding;
-using Chain = std::vector<PlacedVolume>;
-using VolIDs = PlacedVolume::VolIDs;
-
namespace {
- /// Compute the encoding for a set of VolIDs within a readout descriptor
- Encoding update_encoding(const IDDescriptor iddesc, const VolIDs& ids, const Encoding& initial) {
- VolumeID volume_id = initial.identifier, mask = initial.mask;
- for (VolIDs::const_iterator i = ids.begin(); i != ids.end(); ++i) {
- const auto& id = (*i);
- const BitFieldElement* f = iddesc.field(id.first);
- VolumeID msk = f->mask();
- int off = f->offset();
- VolumeID val = id.second; // Necessary to extend volume IDs > 32 bit
- volume_id |= ((f->value(val << off) << off)&msk);
- mask |= msk;
- }
- return { volume_id, mask };
- }
-
/// Basic entry point to assign volume identifiers to detector elements
/**
* Factory: DD4hep_DetElementVolumeIDs
@@ -147,6 +133,27 @@ namespace {
}
DECLARE_APPLY(DD4hep_DetElementVolumeIDs,assign_de_volumeIDs)
+using Encoding = DetElementVolumeIDs::Encoding;
+using VolIDs = PlacedVolume::VolIDs;
+
+namespace {
+
+ /// Compute the encoding for a set of VolIDs within a readout descriptor
+ Encoding update_encoding(const IDDescriptor iddesc, const VolIDs& ids, const Encoding& initial) {
+ VolumeID volume_id = initial.identifier, mask = initial.mask;
+ for (VolIDs::const_iterator i = ids.begin(); i != ids.end(); ++i) {
+ const auto& id = (*i);
+ const BitFieldElement* f = iddesc.field(id.first);
+ VolumeID msk = f->mask();
+ int off = f->offset();
+ VolumeID val = id.second; // Necessary to extend volume IDs > 32 bit
+ volume_id |= ((f->value(val << off) << off)&msk);
+ mask |= msk;
+ }
+ return { volume_id, mask };
+ }
+}
+
/// Default constructor
DetElementVolumeIDs::DetElementVolumeIDs(const Detector& description)
: m_detDesc(description)
@@ -170,9 +177,9 @@ std::size_t DetElementVolumeIDs::populate(DetElement det) {
DetElement de = i.second;
pv = de.placement();
if (pv.isValid()) {
- Chain chain;
- Encoding coding {0, 0};
- SensitiveDetector sd(0);
+ PlacementPath chain;
+ Encoding coding { 0, 0 };
+ SensitiveDetector sd (0);
count += scanPhysicalVolume(de, de, pv, coding, sd, chain);
continue;
}
@@ -188,19 +195,20 @@ std::size_t DetElementVolumeIDs::populate(DetElement det) {
"+++ No sensitive detector available for top level DetElement %s.",
det.path().c_str());
}
- Chain chain;
+ PlacementPath chain;
count += scanPhysicalVolume(det, det, pv, encoding, sd, chain);
printout(INFO, "DetElementVolumeIDs", "++ Assigned %ld volume identifiers to DetElements.", count);
return count;
}
/// Scan a single physical volume and look for sensitive elements below
-std::size_t DetElementVolumeIDs::scanPhysicalVolume(DetElement& parent,
- DetElement e,
- PlacedVolume pv,
- Encoding parent_encoding,
- SensitiveDetector& sd,
- Chain& chain)
+std::size_t
+DetElementVolumeIDs::scanPhysicalVolume(DetElement& parent,
+ DetElement e,
+ PlacedVolume pv,
+ Encoding parent_encoding,
+ SensitiveDetector& sd,
+ PlacementPath& chain)
{
TGeoNode* node = pv.ptr();
std::size_t count = 0;
@@ -252,7 +260,7 @@ std::size_t DetElementVolumeIDs::scanPhysicalVolume(DetElement& parent,
}
}
if ( de_dau.isValid() ) {
- Chain dau_chain;
+ PlacementPath dau_chain;
count += scanPhysicalVolume(parent, de_dau, place_dau, vol_encoding, sd, dau_chain);
}
else { // there may be several layers of volumes between mother-child of DE
@@ -290,7 +298,7 @@ std::size_t DetElementVolumeIDs::scanPhysicalVolume(DetElement& parent,
// Collect all sensitive volumes, which belong to the next DetElement
if ( entries.find(e) == entries.end()) {
entries[e].emplace_back(vol_encoding);
- ++m_numNodes;
+ ++numberOfNodes;
}
++count;
}
diff --git a/DDCore/src/plugins/ShapePlugins.cpp b/DDCore/src/plugins/ShapePlugins.cpp
index e2444890a..2a2a276eb 100644
--- a/DDCore/src/plugins/ShapePlugins.cpp
+++ b/DDCore/src/plugins/ShapePlugins.cpp
@@ -29,6 +29,20 @@ using namespace std;
using namespace dd4hep;
using namespace dd4hep::detail;
+/// Plugin to create a scaled shape
+/**
+ * The xml entity 'e' must look like the following:
+ * - name is optional, x,y,z is the scale.
+ * - <shape>: some shape understood by a DD4hep factory.
+ *
+ * <some-tag name="my-solid" x="1.0" y="2.0" z="3.0" ... stuff not looked at .... >
+ * <shape> ...... </shape>
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Scaled(Detector&, xml_h e) {
xml_dim_t scale(e);
Solid shape(xml_comp_t(scale.child(_U(shape))).createShape());
@@ -38,6 +52,18 @@ static Handle<TObject> create_Scaled(Detector&, xml_h e) {
}
DECLARE_XML_SHAPE(Scale__shape_constructor,create_Scaled)
+/// Plugin to create an assembly shape
+/**
+ * The xml entity 'e' must look like the following:
+ * - name is optional
+ *
+ * <some-tag name="my-assembly" ......stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Assembly(Detector&, xml_h e) {
xml_dim_t dim(e);
Solid solid = Handle<TNamed>(new TGeoShapeAssembly());
@@ -46,6 +72,18 @@ static Handle<TObject> create_Assembly(Detector&, xml_h e) {
}
DECLARE_XML_SHAPE(Assembly__shape_constructor,create_Assembly)
+/// Plugin to create a 3D box
+/**
+ * The xml entity 'e' must look like the following:
+ * - name is optional, x,y,z are the dimensions
+ *
+ * <some-tag name="my-box" x="1.0*cm" y="2.0*cm" z="3.0*cm" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Box(Detector&, xml_h e) {
xml_dim_t dim(e);
Solid solid = Box(dim.dx(),dim.dy(),dim.dz());
@@ -54,6 +92,20 @@ static Handle<TObject> create_Box(Detector&, xml_h e) {
}
DECLARE_XML_SHAPE(Box__shape_constructor,create_Box)
+/// Plugin to create a half-space
+/**
+ * The xml entity 'e' must look like the following:
+ * - name is optional
+ *
+ * <some-tag name="my-box" ... stuff not looked at .... >
+ * <point x="1.0*cm" y="2.0*cm" z="3.0*cm"/>
+ * <normal x="1.0" y="0.0" z="0.0"/>
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_HalfSpace(Detector&, xml_h e) {
xml_dim_t dim(e);
xml_dim_t point = e.child(_U(point));
@@ -66,6 +118,23 @@ static Handle<TObject> create_HalfSpace(Detector&, xml_h e) {
}
DECLARE_XML_SHAPE(HalfSpace__shape_constructor,create_HalfSpace)
+/// Plugin to create a poly-cone
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional, startphi, deltaphi are optional
+ *
+ * <some-tag name="my-polycone" startphi="0*rad" deltaphi="pi" ... stuff not looked at .... >
+ * <zplane rmin="1.0*cm" rmax="2.0*cm"/>
+ * <zplane rmin="2.0*cm" rmax="4.0*cm"/>
+ * <zplane rmin="3.0*cm" rmax="6.0*cm"/>
+ * <zplane rmin="4.0*cm" rmax="8.0*cm"/>
+ * <zplane rmin="5.0*cm" rmax="10.0*cm"/>
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Polycone(Detector&, xml_h element) {
xml_dim_t e(element);
int num = 0;
@@ -86,6 +155,24 @@ static Handle<TObject> create_Polycone(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(Polycone__shape_constructor,create_Polycone)
+/// Plugin to create a cone-segment
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional, rmin1, rmin2, startphi, deltaphi are optional
+ * <some-tag name="my-polycone" rmin1="1*cm" rmax1="2.cm" rmin1="2*cm" rmax1="3.cm"
+ * startphi="0*rad" deltaphi="pi" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ * OR (deprecated):
+ * - name is optional, rmin1, rmin2, (phi1 or phi2) are optional
+ * <some-tag name="my-polycone" rmin1="1*cm" rmax1="2.cm" rmin1="2*cm" rmax1="3.cm"
+ * phi1="0*rad" phi2="pi" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_ConeSegment(Detector&, xml_h element) {
Solid solid;
xml_dim_t e(element);
@@ -109,6 +196,24 @@ static Handle<TObject> create_ConeSegment(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(ConeSegment__shape_constructor,create_ConeSegment)
+/// Plugin to create a tube
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional, rmin, startphi, deltaphi are optional
+ * <some-tag name="my-tube" rmin="1*cm" rmax="2.cm"
+ startphi="0*rad" deltaphi="pi" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ * OR (deprecated):
+ * - name is optional, rmin, (phi1 or phi2) are optional
+ * <some-tag name="my-tube" rmin="1*cm" rmax="2.cm"
+ * phi1="0*rad" phi2="pi" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Tube(Detector&, xml_h element) {
Solid solid;
xml_dim_t e(element);
@@ -129,6 +234,12 @@ static Handle<TObject> create_Tube(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(Tube__shape_constructor,create_Tube)
+/// Plugin to create a twisted tube
+/**
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_TwistedTube(Detector&, xml_h element) {
xml_dim_t e(element);
Solid solid;
@@ -151,6 +262,12 @@ static Handle<TObject> create_TwistedTube(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(TwistedTube__shape_constructor,create_TwistedTube)
+/// Plugin to create a cut tube
+/**
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_CutTube(Detector&, xml_h element) {
xml_dim_t e(element);
Solid solid = CutTube(e.rmin(0.0),e.rmax(),e.dz(),
@@ -167,6 +284,12 @@ static Handle<TObject> create_CutTube(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(CutTube__shape_constructor,create_CutTube)
+/// Plugin to create an elliptical tube
+/**
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_EllipticalTube(Detector&, xml_h element) {
xml_dim_t e(element);
Solid solid = EllipticalTube(e.a(),e.b(),e.dz());
@@ -175,6 +298,12 @@ static Handle<TObject> create_EllipticalTube(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(EllipticalTube__shape_constructor,create_EllipticalTube)
+/// Plugin to create an ttruncated tube
+/**
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_TruncatedTube(Detector&, xml_h element) {
xml_dim_t e(element);
double sp = e.startphi(0.0), dp = e.deltaphi(2*M_PI);
@@ -187,6 +316,17 @@ static Handle<TObject> create_TruncatedTube(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(TruncatedTube__shape_constructor,create_TruncatedTube)
+/// Plugin to create a cone
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional, rmin is optional
+ * <some-tag name="my-tube" rmin="1*cm" rmax="2.cm" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Cone(Detector&, xml_h element) {
xml_dim_t e(element);
double rmi1 = e.rmin1(0.0), rma1 = e.rmax1();
@@ -196,6 +336,24 @@ static Handle<TObject> create_Cone(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(Cone__shape_constructor,create_Cone)
+/// Plugin to create a trap
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional, rmin is optional
+ * <some-tag name="my-tube" dx="1*cm" dy="2.cm" dz="2*cm" pLTX="..." ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ * OR:
+ * name is optional, z, theta, phi, alpha1, alpha2, x3, x4, y1, y2 is optional
+ * <some-tag name="my-tube" z="2*cm" theta="0" phi="0"
+ * y1="1*cm" x1="1*cm" x2="2.cm" alpha1="0"
+ * y2="2.cm" x3="2*cm" x4="2*cm" alpha2="pi"
+ * ... stuff not looked at .... >
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Trap(Detector&, xml_h element) {
xml_dim_t e(element);
Solid solid;
@@ -217,6 +375,12 @@ static Handle<TObject> create_Trap(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(Trap__shape_constructor,create_Trap)
+/// Plugin to create a pseudo trap
+/**
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_PseudoTrap(Detector&, xml_h element) {
xml_dim_t e(element);
Solid solid = PseudoTrap(e.x1(),e.x2(),e.y1(),e.y2(),e.z(),e.radius(),e.attr<bool>(xml_tag_t("minusZ")));
@@ -225,6 +389,17 @@ static Handle<TObject> create_PseudoTrap(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(PseudoTrap__shape_constructor,create_PseudoTrap)
+/// Plugin to create a trd1
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional, z is optional
+ * <some-tag name="my-trd1" x1="1*cm" x2="2*cm" y="1*cm" z="2*cm" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Trd1(Detector&, xml_h element) {
xml_dim_t e(element);
Solid solid = Trd1(e.x1(),e.x2(),e.y(),e.z(0.0));
@@ -233,6 +408,17 @@ static Handle<TObject> create_Trd1(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(Trd1__shape_constructor,create_Trd1)
+/// Plugin to create a trd2
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional, z is optional
+ * <some-tag name="my-trd2" x1="1*cm" x2="2*cm" y1="1*cm" y2="2*cm" z="2*cm" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Trd2(Detector&, xml_h element) {
xml_dim_t e(element);
Solid solid = Trd2(e.x1(),e.x2(),e.y1(),e.y2(),e.z(0.0));
@@ -242,6 +428,24 @@ static Handle<TObject> create_Trd2(Detector&, xml_h element) {
DECLARE_XML_SHAPE(Trapezoid__shape_constructor,create_Trd2)
DECLARE_XML_SHAPE(Trd2__shape_constructor,create_Trd2)
+/// Plugin to create a torus
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional, rmin, startphi, deltaphi are optional
+ * <some-tag name="my-torus" r="10*cm" rmin="1*cm" rmax="2.cm"
+ startphi="0*rad" deltaphi="pi" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ * OR (deprecated):
+ * - name is optional, rmin, (phi1 or phi2) are optional
+ * <some-tag name="my-tube" r="10*cm" rmin="1*cm" rmax="2.cm"
+ * phi1="0*rad" phi2="pi" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Torus(Detector&, xml_h element) {
Solid solid;
xml_dim_t e(element);
@@ -311,6 +515,17 @@ static Handle<TObject> create_Sphere(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(Sphere__shape_constructor,create_Sphere)
+/// Plugin to create a paraboloid
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional, rmin is optional
+ * <some-tag name="my-paraboloid" rmin="1*cm" rmax="2*cm" dz="1*cm" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Paraboloid(Detector&, xml_h element) {
xml_dim_t e(element);
Solid solid = Paraboloid(e.rmin(0.0),e.rmax(),e.dz());
@@ -319,6 +534,19 @@ static Handle<TObject> create_Paraboloid(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(Paraboloid__shape_constructor,create_Paraboloid)
+/// Plugin to create a hyperboloid
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional, rmin is optional
+ * <some-tag name="my-hyperboloid" rmin="1*cm" inner_stereo="pi/2"
+ * rmax="2*cm" outer_stereo="pi/2"
+ * dz="5*cm" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Hyperboloid(Detector&, xml_h element) {
xml_dim_t e(element);
Solid solid = Hyperboloid(e.rmin(), e.inner_stereo(), e.rmax(), e.outer_stereo(), e.dz());
@@ -327,6 +555,18 @@ static Handle<TObject> create_Hyperboloid(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(Hyperboloid__shape_constructor,create_Hyperboloid)
+/// Plugin to create a regular polyhedron
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional
+ * <some-tag name="my-polyhedron" numsides="5" rmin="1*cm" rmax="2*cm" dz="5*cm"
+ * dz="5*cm" ... stuff not looked at .... >
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_PolyhedraRegular(Detector&, xml_h element) {
xml_dim_t e(element);
Solid solid = PolyhedraRegular(e.numsides(),e.rmin(),e.rmax(),e.dz());
@@ -335,7 +575,20 @@ static Handle<TObject> create_PolyhedraRegular(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(PolyhedraRegular__shape_constructor,create_PolyhedraRegular)
-/// Plugin factory to created polyhedra shapes
+/// Plugin to create a irregular polyhedron
+/**
+ * The xml entity 'element' must look like the following:
+ * - name is optional
+ * <some-tag name="my-polyhedron" numsides="5" startphi="0" deltaphi="2*pi" ... stuff not looked at .... >
+ * <plane rmin="1*cm" rmax="2*cm" z="1*cm"/>
+ * <plane rmin="2*cm" rmax="3*cm" z="2*cm"/>
+ * <plane rmin="2*cm" rmax="4*cm" z="4*cm"/>
+ * ... stuff not looked at ....
+ * </some-tag>
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_Polyhedra(Detector&, xml_h element) {
xml_dim_t e(element);
std::vector<double> z, rmin, rmax;
@@ -351,7 +604,12 @@ static Handle<TObject> create_Polyhedra(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(Polyhedra__shape_constructor,create_Polyhedra)
-/// Plugin factory to created extruded polygons
+/// Plugin factory to create extruded polygons
+/**
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_ExtrudedPolygon(Detector&, xml_h element) {
xml_dim_t e(element);
std::vector<double> pt_x, pt_y, sec_z, sec_x, sec_y, sec_scale;
@@ -373,7 +631,12 @@ static Handle<TObject> create_ExtrudedPolygon(Detector&, xml_h element) {
}
DECLARE_XML_SHAPE(ExtrudedPolygon__shape_constructor,create_ExtrudedPolygon)
-/// Plugin factory to created arbitrary 8-point solids
+/// Plugin factory to create arbitrary 8-point solids
+/**
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_EightPointSolid(Detector&, xml_h element) {
xml_dim_t e(element);
double v[8][2];
@@ -391,7 +654,12 @@ static Handle<TObject> create_EightPointSolid(Detector&, xml_h element) {
DECLARE_XML_SHAPE(EightPointSolid__shape_constructor,create_EightPointSolid)
#if ROOT_VERSION_CODE > ROOT_VERSION(6,21,0)
-/// Plugin factory to created tessellated shapes
+/// Plugin factory to create tessellated shapes
+/**
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Handle<TObject> create_TessellatedSolid(Detector&, xml_h element) {
xml_dim_t e(element);
std::vector<TessellatedSolid::Vertex> vertices;
@@ -623,15 +891,29 @@ static Handle<TObject> create_BooleanMulti(Detector& description, xml_h element)
}
DECLARE_XML_SHAPE(BooleanShape__shape_constructor,create_BooleanMulti)
-static Handle<TObject> create_std_volume(Detector& description, xml_h e) {
- return xml::createStdVolume(description, e);
+/// Plugin factory to create arbitrary volumes using the xml::createStdVolume utility
+/**
+ * For details see the implementation in DDCore/src/XML/Utilities.cpp
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
+static Handle<TObject> create_std_volume(Detector& description, xml_h element) {
+ return xml::createStdVolume(description, element);
}
DECLARE_XML_VOLUME(DD4hep_StdVolume,create_std_volume)
-static Handle<TObject> create_gen_volume(Detector& description, xml_h e) {
- xml_dim_t elt = e;
+/// Plugin factory to create arbitrary volumes using the xml::createVolume utility
+/**
+ * For details see the implementation in DDCore/src/XML/Utilities.cpp
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
+static Handle<TObject> create_gen_volume(Detector& description, xml_h element) {
+ xml_dim_t elt = element;
string typ = elt.attr<string>(_U(type));
- return xml::createVolume(description, typ, e);
+ return xml::createVolume(description, typ, element);
}
DECLARE_XML_VOLUME(DD4hep_GenericVolume,create_gen_volume)
@@ -644,6 +926,12 @@ TGeoCombiTrans* createPlacement(const Rotation3D& iRot, const Position& iTrans)
return new TGeoCombiTrans(t, r);
}
+/// Plugin factory to create shapes for shape check tests
+/**
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
static Ref_t create_shape(Detector& description, xml_h e, SensitiveDetector sens) {
xml_det_t x_det = e;
string name = x_det.nameStr();
@@ -899,6 +1187,12 @@ static Ref_t create_shape(Detector& description, xml_h e, SensitiveDetector sens
// first argument is the type from the xml file
DECLARE_DETELEMENT(DD4hep_TestShape_Creator,create_shape)
+/// Plugin factory to check shape meshes against a reference file
+/**
+ *
+ * \author M.Frank
+ * \version 1.0
+ */
void* shape_mesh_verifier(Detector& description, int argc, char** argv) {
if ( argc != 2 ) { }
xml_det_t x_det = *(xml_h*)argv[0];
@@ -986,5 +1280,4 @@ void* shape_mesh_verifier(Detector& description, int argc, char** argv) {
}
return Constant("SUCCESS",os.str().c_str()).ptr();
}
-
DECLARE_DD4HEP_CONSTRUCTOR(DD4hep_Mesh_Verifier,shape_mesh_verifier)
diff --git a/DDCore/src/plugins/StandardPlugins.cpp b/DDCore/src/plugins/StandardPlugins.cpp
index 4f2c86b40..953247a20 100644
--- a/DDCore/src/plugins/StandardPlugins.cpp
+++ b/DDCore/src/plugins/StandardPlugins.cpp
@@ -97,7 +97,7 @@ static long dummy_plugin(Detector& , int, char**) {
}
DECLARE_APPLY(DD4hep_DummyPlugin,dummy_plugin)
-/// Basic entry point to create a Detector instance
+/// Basic entry point to create/access the Detector instance
/**
* Factory: Detector_constructor
*
@@ -187,9 +187,10 @@ static long run_function(Detector&, int argc, char** argv) {
}
if ( lib.empty() || func.empty() ) {
std::cout <<
- "Usage: -plugin <name> -arg [-arg] \n"
- " -library <string> Library to be loaded \n"
- " -function <string> name of the entry point to be executed. \n"
+ "Usage: -plugin <name> -arg [-arg] \n\n"
+ " Execute a function without arguments inside a library. \n\n"
+ " -library <string> Library to be loaded \n"
+ " -function <string> name of the entry point to be executed. \n"
"\tArguments given: " << arguments(argc,argv) << std::endl << std::flush;
::exit(EINVAL);
}
@@ -252,9 +253,7 @@ DECLARE_APPLY(DD4hep_Rint,run_interpreter)
*/
static long root_ui(Detector& description, int /* argc */, char** /* argv */) {
char cmd[256];
- //DD4hepUI* ui = new DD4hepUI(description);
- //::snprintf(cmd,sizeof(cmd),"dd4hep::detail::DD4hepUI* gDD4hepUI = (dd4hep::detail::DD4hepUI*)%p;",(void*)ui);
- std::snprintf(cmd,sizeof(cmd),
+ std::snprintf(cmd, sizeof(cmd),
"dd4hep::detail::DD4hepUI* gDD4hepUI = new "
"dd4hep::detail::DD4hepUI(*(dd4hep::Detector*)%p);",
(void*)&description);
@@ -391,17 +390,39 @@ DECLARE_APPLY(DD4hep_Dump_BorderSurfaces,root_dump_border_surfaces)
* \date 01/04/2014
*/
static long root_elements(Detector& description, int argc, char** argv) {
+ using elt_h = xml::Element;
+
+ /// Generic printer object. Calls the print method of TObject
+ /**
+ * \author M.Frank
+ * \version 1.0
+ * \date 01/04/2014
+ */
struct ElementPrint {
+ /// Default constructor
ElementPrint() = default;
+ /// Default destructor
virtual ~ElementPrint() = default;
- virtual void operator()(TGeoElement* elt) { elt->Print(); }
- virtual void operator()(TGeoIsotope* iso) { iso->Print(); }
+ /// Element writer
+ virtual void operator()(TGeoElement* elt) { elt->Print(); }
+ /// Isotope writer
+ virtual void operator()(TGeoIsotope* iso) { iso->Print(); }
};
+
+ /// XML printer to produce XML output
+ /**
+ * \author M.Frank
+ * \version 1.0
+ * \date 01/04/2014
+ */
struct ElementPrintXML : public ElementPrint {
- typedef xml::Element elt_h;
+ /// Root XML element
elt_h root;
+ /// Initializing constructor
ElementPrintXML(elt_h r) : root(r) {}
+ /// Default destructor
virtual ~ElementPrintXML() {}
+ /// Element writer
virtual void operator()(TGeoElement* element) {
elt_h elt = root.addChild(_U(element));
elt.setAttr(_U(Z),element->Z());
@@ -413,6 +434,7 @@ static long root_elements(Detector& description, int argc, char** argv) {
atom.setAttr(_U(unit),"g/mole");
atom.setAttr(_U(value),element->A());
}
+ /// Isotope writer
virtual void operator()(TGeoIsotope* isotope) {
elt_h iso = root.addChild(_U(isotope));
iso.setAttr(_U(Z),isotope->GetZ());
@@ -442,9 +464,9 @@ static long root_elements(Detector& description, int argc, char** argv) {
}
}
- xml::Document doc(0);
+ xml::Document doc(0);
xml::DocumentHandler docH;
- xml::Element element(0);
+ xml::Element element(0);
if ( type == "xml" ) {
const char comment[] = "\n"
" +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n"
@@ -496,19 +518,34 @@ DECLARE_APPLY(DD4hep_ElementTable,root_elements)
* \date 01/04/2014
*/
static long root_materials(Detector& description, int argc, char** argv) {
+
+ using elt_h = xml::Element;
+
+ /// Material printer object
+ /**
+ * \author M.Frank
+ * \version 1.0
+ * \date 01/04/2014
+ */
struct MaterialPrint {
- typedef xml::Element elt_h;
+ public:
+ /// Reference to the detector description
Detector& description;
+
+ public:
+ /// Initializing constructor
MaterialPrint(Detector& desc) : description(desc) {}
+ /// Default destructor
virtual ~MaterialPrint() = default;
+ /// Print single material
virtual elt_h print(TGeoMaterial* mat) {
const char* st = "Undefined";
- switch(mat->GetState()) {
- case TGeoMaterial::kMatStateSolid: st = "solid"; break;
- case TGeoMaterial::kMatStateLiquid: st = "liquid"; break;
- case TGeoMaterial::kMatStateGas: st = "gas"; break;
- case TGeoMaterial::kMatStateUndefined:
- default: st = "Undefined"; break;
+ switch( mat->GetState() ) {
+ case TGeoMaterial::kMatStateSolid: st = "solid"; break;
+ case TGeoMaterial::kMatStateLiquid: st = "liquid"; break;
+ case TGeoMaterial::kMatStateGas: st = "gas"; break;
+ case TGeoMaterial::kMatStateUndefined:
+ default: st = "Undefined"; break;
}
::printf("%-32s %-8s\n", mat->GetName(), mat->IsMixture() ? "Mixture" : "Material");
::printf(" Aeff=%7.3f Zeff=%7.4f rho=%8.3f [g/mole] radlen=%8.3g [cm] intlen=%8.3g [cm] index=%3d\n",
@@ -518,11 +555,13 @@ static long root_materials(Detector& description, int argc, char** argv) {
mat->GetTemperature(), mat->GetPressure()/dd4hep::pascal/100.0, st);
return elt_h(0);
}
+ /// Print element entry
virtual void print(elt_h, TGeoElement* elt, double frac) {
::printf(" %-6s Fraction: %7.3f Z=%3d A=%6.2f N=%3d Neff=%6.2f\n",
elt->GetName(), frac, elt->Z(), elt->A(), elt->N(), elt->Neff());
}
#if ROOT_VERSION_CODE >= ROOT_VERSION(6,17,0)
+ /// Print material property
virtual void printProperty(elt_h, TNamed* prop, TGDMLMatrix* matrix) {
if ( matrix )
::printf(" Property: %-20s [%ld x %ld] --> %s\n",
@@ -534,19 +573,25 @@ static long root_materials(Detector& description, int argc, char** argv) {
#endif
virtual void operator()(TGeoMaterial* mat) {
Double_t* mix = mat->IsMixture() ? ((TGeoMixture*)mat)->GetWmixt() : 0;
- elt_h mh = print(mat);
- for(int n=mat->GetNelements(), i=0; i<n; ++i) {
+ elt_h mh = print(mat);
+ for( int n=mat->GetNelements(), i=0; i<n; ++i ) {
TGeoElement* elt = mat->GetElement(i);
print(mh, elt, mix ? mix[i] : 1);
}
#if ROOT_VERSION_CODE >= ROOT_VERSION(6,17,0)
TListIter mat_iter(&mat->GetProperties());
- for(TObject* i = mat_iter.Next(); i; i=mat_iter.Next()) {
+ for( TObject* i = mat_iter.Next(); i; i=mat_iter.Next() ) {
printProperty(mh, (TNamed*)i, description.manager().GetGDMLMatrix(i->GetTitle()));
}
#endif
}
};
+ /// XML printer to produce XML output
+ /**
+ * \author M.Frank
+ * \version 1.0
+ * \date 01/04/2014
+ */
struct MaterialPrintXML : public MaterialPrint {
elt_h root;
MaterialPrintXML(elt_h elt, Detector& desc) : MaterialPrint(desc), root(elt) {}
@@ -620,31 +665,31 @@ static long root_materials(Detector& description, int argc, char** argv) {
}
}
- xml::Document doc(0);
+ xml::Document doc(0);
xml::DocumentHandler docH;
- xml::Element element(0);
+ xml::Element element(0);
if ( type == "xml" ) {
- const char comment[] = "\n"
- " +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n"
- " ++++ Generic detector description in C++ ++++\n"
- " ++++ dd4hep Detector description generator. ++++\n"
- " ++++ ++++\n"
- " ++++ Parser:"
- XML_IMPLEMENTATION_TYPE
- " ++++\n"
- " ++++ ++++\n"
- " ++++ Table of elements as defined in ROOT: " ROOT_RELEASE " ++++\n"
- " ++++ ++++\n"
- " ++++ M.Frank CERN/LHCb ++++\n"
- " +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n ";
- doc = docH.create("materials", comment);
- element = doc.root();
+ const char comment[] = "\n"
+ " +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n"
+ " ++++ Generic detector description in C++ ++++\n"
+ " ++++ dd4hep Detector description generator. ++++\n"
+ " ++++ ++++\n"
+ " ++++ Parser:"
+ XML_IMPLEMENTATION_TYPE
+ " ++++\n"
+ " ++++ ++++\n"
+ " ++++ Table of elements as defined in ROOT: " ROOT_RELEASE " ++++\n"
+ " ++++ ++++\n"
+ " ++++ M.Frank CERN/LHCb ++++\n"
+ " +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n ";
+ doc = docH.create("materials", comment);
+ element = doc.root();
}
dd4hep_ptr<MaterialPrint> printer(element
? new MaterialPrintXML(element, description)
- : new MaterialPrint(description));
+ : new MaterialPrint(description));
TObject* obj = 0;
- TList* mats = description.manager().GetListOfMaterials();
+ TList* mats = description.manager().GetListOfMaterials();
dd4hep_ptr<TIterator> iter(mats->MakeIterator());
while( (obj=iter->Next()) != 0 ) {
TGeoMaterial* mat = (TGeoMaterial*)obj;
@@ -746,7 +791,7 @@ static long process_xml_doc(Detector& description, int argc, char** argv) {
DetectorImp* imp = dynamic_cast<DetectorImp*>(&description);
if ( imp ) {
xml::XmlElement* h = (xml::XmlElement*)argv[0];
- xml::Handle_t input(h);
+ xml::Handle_t input(h);
if ( input.ptr() ) {
if ( argc > 1 ) {
type = buildType(argv[1]);
@@ -1287,9 +1332,9 @@ DECLARE_APPLY(DD4hep_VolumeDump,dump_volume_tree)
* \date 18/11/2016
*/
static int detelement_processor(Detector& description, int argc, char** argv) {
- bool recursive = true;
+ bool recursive = true;
ProcessorArgs args(argc, argv);
- DetElement det = description.world();
+ DetElement det = description.world();
std::unique_ptr<DetectorProcessor>
proc(dd4hep::createProcessor<DetectorProcessor>(description, args.argc, &args.argv[0]));
--
GitLab