Creating and setting alignment objects

Alignment objects are created by means of their constructors which need to be given the identifiers for the volume (a symbolic volume name - "symname" - and a unique global index, index ) and the parameters specifying the transformation. Examples of creation of alignment objects are the macros MakeDETZeroMisAlignment.C MakeDETResMisAlignment.C and MakeDETFullMisAlignment.C , all in the $ALICE_ROOT/macros , where DET is to be replaced by the detector abbraviation. While the choice of creating an instance of either AliAlignObjParams of AliAlignObjMatrix class relates to what the object stores, in both cases the user can choose to pass the delta-transformation either by means of a TGeoMatrix delta or by means of six doubles (three shifts - x,y,z - plus three Euler angles - , see here for explanations). The user can also decide to either refer to the transformation to be applied in the global RS or to refer to the transformation to be applied in the local reference frame of the ideal position of the volume (see here for explanations on the use of the global and local delta-transformation in alignment objects). Combining the two possibilities for the two choices, the user can pass to the alignment object constructor one among the following four set of variables:

• the matrix of the global delta-transformation - Delta:
  
  AliAlignObjParams* alobj = new AliAlignObjParams("symname",index,Delta,kTRUE)
• the matrix of the local delta-transformation - delta :
  
  AliAlignObjParams* alobj = new AliAlignObjParams("symname",index,delta,kFALSE)
• the parameters of the global delta-transformation - Dx,Dy,Dz,Dpsi,Dtheta,Dphi :
  
  AliAlignObjParams* alobj = new AliAlignObjParams("symname",index,X,Y,Z,Psi,Theta,Phi,kTRUE)
• the parameters of the local delta-transformation - dx,dy,dz,dpsi,dtheta,dphi :
  
  AliAlignObjParams* alobj = new AliAlignObjParams("symname",index,x,y,z,psi,theta,phi,kFALSE)

Similar functionality is provided for setting the alignment object, choosing again between the global or local delta-transformation and between a matrix or six parameters for representing it; the analoguous cases for setting an object AliAlignObjParams alobj are then:

• alobj.SetPars(Dx,Dy,Dz,Dpsi,Dtheta,Dphi);
• alobj.SetMatrix(Delta);
• alobj.SetLocalPars(dx,dy,dz,dpsi,dtheta,dphi);
• alobj.SetLocalMatrix(delta);

The same flexibility is allowed for setting only the translation or the rotation part of the global delta-transformation by means of the SetRotation and SetTranslation (or SetLocalRotation and SetLocalTranslation ) methods; again the corresponding setters in the local RS are available, that is the user can set the translation or rotation part only of the local delta transformation. All these methods can take either 3 doubles or a matrix:

or:

From the conventions used it follows that rot (or psi, theta, phi ) and transl (or x,y,z ) have to be the rotation and the translation which one has to apply to a vector in to get it in , (e.g. x,y,z are the coordinates of origin as seen by

Storing, uploading and checking alignment objects

Once created, alignment objects can be stored in any ROOT collector; anyway, to take full advantage of the framework, they have to be stored in TClonesArray ; the following is an example of creating and storing alignment objects:

In the following two examples we upload the array of alignment objects from a file where it has been saved either directly (case 1.) or as an AliCDBEntry , that is as an entry for the Offline Conditions Data Base (case 2.):

1. TClonesArray of alignment objects stored in a file:
   
   TFile* file = TFile::Open(...);
   TClonesArray* array = f->Get("AlignObjArray")

   If you don't know the name of the array to be passed to the TFile::Get method, just do f->ls() to find it out.

2. File containing a TClonesArray of alignment objects stored as AliCDBEntry:
   
   TFile* file = ...;
   AliCDBEntry* entry = file->Get("AliCDBEntry");
   TClonesArray* array = (TClonesArray*) entry->GetObject()

The user can check at this point the alignment object by means of the AliAlignObj::Print() method, which will print the alignment constants contained in the object itself. The same method can be called for all the objects in the array simply by:

All the alignment constants can be obtained individually by the corresponding getters. The user can retrieve the transformation matrix or the transformation parameters expressing either the global or the local delta transformation. The getters involving the construction of the three angles from the rotation matrix coefficients return a boolean, which is false in case the calculation of the angle would involve a division by a null matrix element. Two examples follow (the reader can easily extend them for getting the other alignment constants owned by the object):

The AliGeomManager provides a practical means to query the geometry for all alignable volumes, on a sub-detector basis. Thanks to the two static look-up tables maneged by this singleton, the user can get information about alignable volumes in a fast and coherent way. The two look-up tables are initialized at the first instance of the AliGeomManager class or at the first query. The map of alignable entries is reinitialized in case a different geometry has been loaded. A simple example follows, in which the user is interested in getting the global transformation matrix for all alignable volumes of the first TPC layer, that is the TPC inner readout chambers: TGeoHMatrix m;

Default uploading during simulation and reconstruction runs

An important task of the ALICE alignment framework is to set default behaviours for loading alignment objects residing on the Offline Conditions Data Base (OCDB) during simulation and reconstruction jobs; at the same time the framework has to present a simple interface for managing specific use cases (activation/deactivation of specific CDB storages done detector by detector, use of alignment objects in memory ...). The OCDB is filled with conditions (calibration and alignment) objects; the alignment objects in the OCDB are presently created by macros to reproduce two possible misalignment scenarios:

• the initial misalignment - expected deviations from the ideal geometry just after the sub-detectors are installed;
• the residual misalignment - deviations which can not be resolved by the alignment procedures.

These alignment objects on the OCDB will be updated respectively by:

• survey procedures (as soon as survey data are available to the offline)
• alignment procedures (as soon as reconstruction will start from real data)

before being used by the reconstruction of the real data in its different passes.

The OCDB stores the conditions making use of the database capabilities of a file system's three-level directory structure; the run and the version are stored in the file name. If not otherwise specified, the OCDB returns the latest version of the required object. When an object is uploaded it is automatically saved with increased version number (for a complete description of the OCDB functionality see the OCDB page).

The ALICE alignment framework sets a default behaviour for simulation and reconstruction runs: alignment objects are loaded from a default conditions data base storage for all the sub-detectors. The user can modify this behaviour in several ways: (s)he can set a different storage, either residing locally or on the grid. As an example, being sim the active instance of AliSimulation , the user can set:

or

The user can also run the simulation or the reconstruction with a geometry modified by an array of alignment objects available in memory by means of the SetAlignObjArray(array) method of AliSimulation or AliReconstruction , which also deactivates the loading of alignment objects from any OCDB storage.

The definition of a non-default storage for the OCDB, as well as its activation, can also be given for specific sub-detectors only, by adding as an argument of the SetSpecificStorage call the string indicating the concerned part of the OCDB:

The following line preceding the launching of a simulation run:

would instead tell the simulation to load alignment objects for the specified detector only (HMPID in this case).

The user can also just switch off the loading of any alignment object with a call like:

The same is possible in reconstruction too, using the anlogous method of AliReconstruction :

During a normal simulation run (sim.Run()) the ideal geometry is saved in the file "geometry.root".

Application of alignment objects to the geometry

The method for applying an alignment object to the geometry in memory, thus displacing the volume to which the alignment object refers, is: AliAlignObj::ApplyToGeometry() . To apply a single object:
((AliAlignObj*)ar->UncheckedAt(i))->ApplyToGeometry();
To apply all the objects belonging to the given array you would do:

But there can be no guarantee that the objects will be applied correctly at the level of the alignment object, because there are two checks to be done which concern the whole set of objects one applies to the geometry:

1. in case of alignment objects referring to physical volumes on the same branch, they have to be applied from the uppermost to the lowermost volume in the physical tree (that is starting from the outermost container volume down to the innermost contained volume);
2. alignment objects should never be applied more then once to the same physical volume

The reason for the first limitation is in short the fact that the position of the contained volume depends on the position of the container volume and not vice versa. The reason for the second limitation is that the delta-transformation is expressed w.r.t. the ideal global position of the given volume, while the separate application of two or more alignment objects to it would imply that all of them but the first would refer to a geometry which has already been displaced by applying previous objects(an error is returned if trying to align a physical volume already aligned, but this safety fails if you reopen the geometry).

The tools used by the framework for checking that the two previous conditions are fulfilled are respectively:

1. compare the positions of the physical volumes on the same branch by means of the method Compare or by directly using GetLevel() which returns the depth of the physical volume to which the given alignment object refers.
2. Combine more objects referring to the same volume by means of the operator *= s:
   
   AliAlignObjMatrix alobj1;
   AliAlignObjMatrix alobj2;
   alobj1 *= alobj2;
   before applying them to the geometry.

These checks are performed by the AliGeomManager::ApplyAlignObjsToGeom method, which is used by AliSimulation and AliReconstruction to apply a set of alignment objects to the geometry; therefore the user can consistently apply the objects to the geometry, having the two checks above transparently performed, if it does it by modifying the default behaviour of AliSimulation and AliReconstruction.
An additional check performed in AliGeomManager::ApplyAlignObjsToGeom is that the application of the alignment objects does not introduce overlaps or extrusions exceeding a fixed threshold. This check is done via a call to gGeoManager->GetTopNode()->CheckOverlaps(); (see TGeo manual for further TGeo functionality). Overlaps and extrusions can invalidate the geometry (hiding some sensitive parts or significantly changing the material budget during tracking). A simple example follows in which AliSimulation functionality is used to apply the alignment objects to the ideal geometry in case the array of alignment objects is saved directly into a file and the checks are transparently performed:

An analoguous example holds for AliReconstruction.

Sometimes the user already has a geometry in memory, either because he has produced it ( gAlice->Init() ) or because he has uploaded it ( TGeoManager::Import("geometry.root") ); then he wants to apply some alignment objects to it indipendently of any simulation or reconstruction job. In this case the user can make direct use of the AliGeomManager::ApplyAlignObjsToGeom method, which allows to pass either the array of alignment objects directly or a list of detectors for which to upload the alignment objects from the active CDB storage or, finally, the identifiers for the entry in the storage itself.

Additional functionality

• Extract alignment constants from the current geometry
• Correcting positions using aligned geometry
• Getting information for alignable volumes

Extract alignment constants from the current geometry

The method AliAlignObj::GetFromGeometry(symname, &alobj) allows to set the alignment object from the position of the physical volume identified by symname with respect to the ideal position for that volume.

This method is intended to be used occasionally (e.g. not in loops) because the search for the physical volume in the geometry tree is a search by string and it is then quite expensive in terms of time!

Correcting positions using aligned geometry

Probably the main advantage of saving the global delta-transformation (w.r.t. the local one) is that it can directly be used for transforming positions in the ideal geometry into positions in the aligned geometry in the global RS; in alignment procedures this is the most useful case, since the parameters of the track are expressed in the global reference system. The method AliAlignObj::Transform allows to directly use the alignment object to update the ideal global positions of a space point or of an array of them.

Getting information for alignable volumes

The steering class AliGeomManager provides the getters for the geometrical information for alignable volumes given one volume identifier: either its global index, or the pair layer index + index inside layer or the symbolic volume name. The geometry information is retrieved in the most efficient way thanks to the flow volume identifier -> TGeoPNEntry -> TGeoPhysicalNode, which is transparent to the user and made possible by the two look-up tables held by the AliGeomManager class. Since this class optimizes access of geometry information for alignable volumes, AliRoot code in general is expected not to query directly TGeo but by means of the AliGeomManager static methods.

We list here some possible examples; they only require an active geometry (non NULL gGeoManager ). The most common and general use is to retrieve the global matrix of an alignable volume or its rotational or translational part:

• Get actual global matrix for volume identified by index(1), by layerId + id inside layer (2) or by symname(3):
  1. TGeoHMatrix hm = *AliGeomManager::GetMatrix(index);
  2. TGeoHMatrix hm = *AliGeomManager::GetMatrix(ELayerID layerId, Int_t modId);
  3. TGeoHMatrix hm = *AliGeomManager::GetMatrix(symname);

  This methods access the node by means of GetMatrix(TGeoPNEntry* pne), which in turn retrieve the alignable entry using one of the GetPNEntry methods; if the physical volume is not yet a physical node, then the query is done in the alternative, slower way of cding to the physical volume and querying the current matrix.
  Note: the expected use of these methods is, as in the examples, to make a copy of the returned pointer, since the method, based on TGeoPhysicalNode::GetMatrix() returns a pointer to a region of memory whose content would change after changing the current status of gGeoManager (aftergGeoManager->cd(secondvolpath)).

• Get translational or rotational part of the original global matrix for volume identified by index or symname:
  
  Double_t tr[3], rot[9];
  Int_t index = AliGeomManager::LayerToVolUID(AliGeomManager::kTPC1,1)
  1. AliGeomManager::GetTranslation(index, tr);
  2. AliGeomManager::GetRotation(index, rot);
• In an analogous way it's possible to query the geometry for the original global matrix for a given volume identified by index(1) or by symbolic name, or just the translation/rotational part of it:
  TGeoHMatrix gm;
  1. AliGeomManager::GetOrigGlobalMatrix(index, gm);
  2. AliGeomManager::GetOrigGlobalMatrix(symname, gm);
  3. AliGeomManager::GetOrigTranslation(index, tr);
  4. AliGeomManager::GetOrigRotation(symname, rot);
• We can ask for the local or global tracking matrix for a given alignable volume, provided the corresponding data member in TGeoPNEntry has been set with TGeoPNEntry::SetMatrix for that volume.
  1. TGeoHMatrix* t2l = AliGeomManager::GetTracking2LocalMatrix(Int_t index);
  2. TGeoHMatrix t2g;
     AliGeomManager::GetTrackingMatrix(index, t2g);
• Finally the AliGeomManager singleton allows to set from the current geometry the alignment object for a given alignable volume:
  1. AliAlignObjParams* alobj = AliGeomManager::GetAlignObj(index);
  2. AliAlignObj* alobj = AliGeomManager::GetAlignObj(AliGeomManager::kTPC1, 1);
  3. const char* symname = AliGeomManager::SymName(AliGeomManager::kTPC1, 1);
     AliAlignObjParams alobj;
     GetFromGeometry(symname, AliAlignObj &alobj);

  The method InitAlignObjFromGeometry() initialises the alignment objects for all indexed alignable volumes from the current geometry.

Summary

The ALICE alignment framework, based on the ROOT geometry package, aims at allowing a consistent and flexible management of the alignment information, while leaving the related complexity as much as possible hidden to the user. The framework allows to:

• save, retrieve and check the alignment constants relative to a specific alignable volume or to all alignable volumes of a given sub-detector (automatic retrieval from a Conditions Data Base is handled).
• apply the alignment objects to the current (ideal) geometry
• get from the current geometry the alignment object for a specified volume path
• transform positions in the ideal global RS into positions in the aligned global RS

These functionalities are built around the AliAlignObj base class and its two derived classes, AliAlignObjParams and AliAlignObjMatrix , which store the delta-transformation either by means of the transformation matrix or by means of the six transformation parameters respectively, while the user interface is the same in both cases.

The framework sets the internal representation of the delta-transformation by fixing the following conventions:

• the transformations are interpreted according to the local-to-global convention;
• the delta-transformation stored is the global delta-transformation;
• the three parameters to specify the rotation are the roll-pitch-yaw Euler angles, with the "active-transformations" convention.

The framework fixes also the following default behaviours in simulation and reconstruction runs:

• objects are loaded from a default Conditions Data Base storage, on a sub-detector basis;
• the set of loaded objects is sorted for assuring the consistency of its application to the geometry;
• the ideal and aligned geometries are saved.

A good deal of flexibility is left to the user w.r.t. how to set the alignment objects and the delta-transformation in particular; the user can:

• choose to set the alignment object either by passing a TGeoMatrix or by giving the six parameters which uniquely identify the global delta-transformation;
• choose if he wants the object to store either the TGeoMatrix , using an AliAlignObjMatrix or the six parameters, using an AliAlignObjParams ;
• choose if the transformation he is passing is the global delta-transformation or the local delta-transformation; in this latter case the framework converts it to the global one to set the internal data members.