Basic objects and alignment constants The ALICE alignment framework implementation is built on the AliAlignObj base class and its derived classes. An alignment object is an instance of one of those classes and stores the so called alignment constants for a single alignable volume:
- a unique string identifier for the volume: the symbolic name
- a unique numerical identifier for the volume: the unique global index
- a delta-transformation
This is the information to uniquely identify the physical volume (instance of the volume in the geometry tree) and to unambiguously describe the displacement (shift + rotation) to be applied to that volume.
The unique volume identifier is the variable allowing access to a specific physical volume inside the geometry tree. For the ALICE geometry (which is a ROOT geometry) this is the volume path, a string containing the names of all physical volumes in the current branch a la directory tree. For example /A_1/B_i/.../M_j/Vol_k identifies the physical volume "kth copy of the volume Vol " by listing its container volumes; going from right to left in the path corresponds to going from the innermost to the outermost containers and from the lowest to the upper level in the geometry tree, starting from the mother volume M_j of the current volume Vol_k up to the physical top volume A_1 , the root of the geometry tree.
The unique volume identifier stored by the alignment object is not the volume path but a " symbolic volume name", a meaningful string identifying the given physical volume and dynamically associated to the corresponding volume path at the finalisation stage of the geometry and stored as part of it.
The choice of the symbolic volume names is constrained only by the following two rules:
- Each name has to contain a leading sub-string indicating its pertaining sub-detector (/DET/...); in this way the uniqueness of the name inside the sub-detector scope guarantees also its uniqueness in the global scope of the whole geometry.
- Each name has to contain the intermediate alignable levels, separated by a slash (' /'), in case some other physical volume on the same geometry branch is in turn alignable.
There are two advantages of the choice to introduce the symbolic volume names as unique volume identifiers stored in the alignment object instead of the volume path:
- The unique volume identifier has no direct dependency on the geometry; in fact changes in the volume paths reflect in changes in the hash table associating the symbolic names to them, which is built and stored together with the geometry. As a consequence the validity of the alignment objects is not affected by changes in the geometry and hence is in principle unlimited in time.
- The unique volume identifier can be freely chosen, according to the two simple rules mentioned above. This allows to assign meaningful names to the alignable volumes, as opposed to the volume paths which inevitably are long strings of often obscure names.
The symbolic volume names are assigned in each AliDETvX::AddAlignableVolumes by calls like:
A loop on these methods is performed just before the geometry is closed. The hash-table resulting from the loop and storing all "symbolic volume name - volume path" links is stored in the geometry itself.
Among the alignment constants the alignment objects store a numerical index (a short) uniquely identifying the volume to which those constants refer. The 16 available bits of the numerical index are filled by the index of the "layer" or sub-detector to which the volume belongs (5 bits) and by the "local index", i.e. the index of the volume itself inside the sub-detector (the remaining 11 bits). Limiting the range of sub-detectors to 2 5=32 and of alignable volumes inside each sub-detector to 2 11=2048, this fits the cardinality of sub-detectors and sub-detectors'modules in ALICE. Volumes which are allowed to be moved are called alignable; they are declared by creating and associating to them an alignable entry ( TGeoPNEntry ). This is done in the flow of construction of the geometry, by the AliDET::AddAlignableVolumes methods, where AliDET is a generic detector class inheriting from AliModule ). Alignable volumes should be placed in the geometry with some free space around them so that they can move without generating overlaps. It is to be noted that the set of volumes which are associated an index is only a subset of the set of all alignable volumes. The reason for this is that indexed volumes include only sensitive alignable volumes, that is alignable volumes at the lowest level in the geometry tree, i.e. the closest alignable parents of the sensitive volumes or the sensitive volumes themselves in case they are alignable. This implies that they correspond to a real volume that is formed of fixed parts internally but whose position is variable. The user will have no penalty and no gain using the index also for non indexed alignable volumes setting it to zero in the AliAlignObj-ects.
The aim of indexing the alignable volumes is fast iterative access during alignment procedures. By means of the singleton AliGeomManager class, the framework provides two look-up tables to allow for fast retrieval of information from the geometry starting from one of the volume identifiers:
- a look-up table mapping indexes to symbolic volume names;
- a look-up table mapping indexes to alignable entries ( TGeoPNEntry objects) stored in the geometry.
The numerical indices are mapped on a layer basis, where the layer is either a sub-detector or a part of it in case the subdector is built up of several layers in the radial direction. The TGeoPNEntry objects (or alignable entries) are essentially a link between symbolic name and the related volume path, having at the same time direct access to the physical node assigned to that path. This allows the framework, by means of the steering class AliGeomManager , to have direct access to the physical nodes starting from the associated volume identifiers. In addition, alignable entries are also used to hold additional information which is not strictly part of the geometry but that is essentially related to alignable volumes: in fact the framework stores in the alignable entry the local tracking matrix. It is indeed frequent that tracking algorithms make use of a local reference system somehow shifted and/or rotated from the one known by the geometry; the local tracking matrix expresses the transformation from the local tracking reference system to the usual local reference system, the one associated to that volume in the geometry. If we multiply to the right the global matrix for that volume, we get the global tracking matrix for that volume, that is the matrix which transforms point coordinates expressed in the local tracking reference system into point coordinates expressed in the global reference system.
Thanks to the functionality of the TGeoPNEntry class, the AliGeomManager can query TGeo for the position of the given alignable volume according to the sequence:
symbolic volume name (or volume index) ⇒ TGeoPNEntry->GetPhysicalNode() ⇒ TGeoPhysicalNode->GetMatrix()
The fallback solution, in case the volume does not correspond to a physical node already, is to make the given volume path the current physical volume and to ask for the current matrix. This solution is however sensibly slower.
The steering singleton class AliGeomManager holds the two look-up tables; they are built either at the instantiation of the AliGeomManager singleton, or at the first query of the table. In addition to that, the look-up table mapping volume indices to alignable entries is reinitialised in case the active geometry (the TGeoManager instance) has changed.
The framework allows to easily browse the two look-up tables by means of the static methods provided in the steering singleton class AliGeomManager . Some static methods inspect the table itself, to get for example the size and name of a specific layer ( LayerSize , LayerName ), to build the global index given the layer index and the index of the volume inside the layer or to get the layer to which a certain volume belongs, given its global index ( LayerToVolUID and VolUIDToLayer ). The SymName static methods allow to get the symbolic names from the indexes as they are mapped inside the table. Other static methods allow to take advantage of the look-up tables by using the volume identifiers to get from the geometry specific information related to the concerned volume: in particular one can get the ideal global matrix or only the translational or rotational part of it for a given volume identifier either from the current geometry or from the ideal geometry ( GetMatrix and GetOrigMatrix ). The difference between the two geometries can also be used to build on the fly the corresponding alignment object ( GetFromGeometry ). Examples of this are given throughout the related functionality section.
In general simulation and reconstruction do not use the same local RS as the one known by the geometry for the given sensitive volume. Let's call "local tracking RS" the local RS used by simulation and reconstraction code, the RS in which cluster coordinates are expressed; let's denote "TGeo local RS" the local RS of that volume in the geometry, the one deriving from building and positioning that volume inside the geometry.The link between the two RSs was up to now hidden in the code. The TGeoManager::SetAlignableEntry(const char*,const char*) method creates an instance of TGeoPNEntry class, which is also able to store a TGeoHMatrix. This is the place where we have chosen to store the transformation matrix between the tracking local system and the TGeo local system. To save this matrix we use the TGeoPNEntry::SetMatrix(TGeoHMatrix *matrix) method in the same place where we declare that the given volume is alignable, i.e. inside AliDETvX::AddAlignableVolumes (see as an example the implementation in AliITSvPPRasymmFMD::AddAlignableVolumes() ).