UgliGeometry

Last significant change: 2004/03/11

NB: This chapter is appropriate for users of MINOS software dated prior to 2006/09/19, or for those using MINOS software more recent than that but who have configured the default behavior off in favor of restoring the geometry build used previous to this date. The last release prior to this date was R1.24.0. For R1.24.1 or later, the information in this chapter has been superceded by that in the next chapter entitled Geometry.

Introduction

The UgliGeometry package provides services for managing the physical placement of detector elements in 3-space.

Creating a geometry

The user does not work directly with a UgliGeometry object, but instead works through a UgliGeomHandle. These UgliGeomHandles are lightweight proxy objects that do little work of any substance. During the creation of a UgliGeomHandle a loan pool of real UgliGeometry objects searched for an appropriate object; if no match exists one will be created. The UgliGeomHandle then forwards member function calls to the correct UgliGeometry. This allows the UgliGeomHandle to share the larger underlying collection of information and it lowers the overhead of the creation and deletion of UgliGeomHandles.

This approach also allows the UgliGeomHandles to be created on the stack and thus avoids a common source of memory leaks. The lookup procedure is so fast that users should not be concerned with (or even attempt) to retain a handle, but rather should construct one from a VldContext whenever one is needed.

#include "UgliGeometry/UgliGeomHandle.h"

  // retrieve a copy of the VldContext object identifying 
  // the configuration of the current record
  VldContext vldc = [..]

  // create a UgliGeomxHandle (on the stack)
  UgliGeomHandle ugh(vldc)

  [....]
  // work with UgliGeomHandle and it gets automagically destroyed
  // when the code block ends, but the next invocation is
  // likely to acquire the same underlying UgliGeometry without
  // significant overhead.

Configuring how geometries are constructed

The behaviour of the ugli package can be modified by manipulating the configuration of the UgliLoanPool. To change a parameter from within C++ code one writes code like:

   // UgliLoanPool is a CfgConfigurable 
   UgliLoanPool* ulpool  = UgliLoanPool::Instance();
   ulpool->Set("...");
   ulpool->Set("...");
   ulpool->Update();

On startup the interface checks the environmental variable ENV_UGLI which can contain a semi-colon separated list of configuration requests, e.g.:

   setenv ENV_UGLI "MaxUnref=2; AlwaysUseDbi=0"

One can also show the current status of the UgliLoanPool using:

   UgliLoanPool::Instance()->Print();

which gives something like:

   "UgliLoanPool Configuration", 13 entries. keys unlocked, values unlocked
       AlgorithmicCalDet = 0
       AlgorithmicFar = 0
       AlgorithmicNear = 0
       AlwaysUseDbi = 1
       Cache = ''
       CacheWrite = 1
       CutAppliesToMC = 0
       CutAppliesToVetoShield = 0
       CutMsgLevel = 'Synopsis'
       CutOnPlnInstallCalDet = 0
       CutOnPlnInstallFar = 1
       CutOnPlnInstallNear = 0
       MaxUnref = 1
    --- Frozen UgliLoanPool ---
     UgliGeometry has 1 references
       |CalDet|Data|
            2001-07-24 00:00:04.000000000Z
            2001-08-13 00:00:04.000000000Z
            from source: DBI, From Database
       fRootGeom "Frozen|CalDet|Data|2001-07-24 00:00:04"
    --- Modifiable UgliLoanPool ---
    --- End of UgliLoanPool ---

Managing shared geometries

As described in Section 6.2 the user normally interfaces with the package via the class UgliGeomHandle. This allows the ugli package to maintain a pool of UgliGeometry objects to which handles can easily be attached as needed. Users might need to trade off memory requirements of holding multiple geometries vs. the time requirement of repeatedly building one for the pool. Users can configure the number of unreferenced geometries that are retained by the pool for shared use via the MaxUnref config value.

Caching a copy of the loan pool

During development when prototyping code in a rapid cycle the overhead of reconstructing a geometry every time the job is run can be an annoyance. Some time can be save, of order $\sim40$s of $\sim70$s, by writing out the geometry as a root file and reading it back rather than pulling the data from the database and building it from scratch. This approach can also be dangerous in that it bypasses the database and thus heavy reliance on it can lead to the use of outdated constants. It also has no protection against multiple jobs trying to read and write the file simultaneously.

Nevertheless, it is sometime useful. This behavour can be enabled by setting the Cache config variable to the name of the root file to use. One then runs the job once to build the necessary geometry from the database and the job will write the file upon teardown of the UgliLoanPool at job end. Subsequent jobs will then read the cached file and can avoid the re-writing overhead by setting the CacheWrite config value to zero.

UgliGeomHandle

UgliPlaneHandle

UgliStripHandle

Building, changing and sharing a modified geometry

Normally one builds a geometry that is frozen, i.e. unmutable, and exactly reflects the constants stored in the database. Sometimes it is useful to adjust various parameters, for instance in attempting to do alignment. The UgliLoanPool in fact manages two distinct pools of geometries. The normal UgliGeomHandle constructor actually has a second argument beyond the VldContext. The second argument specifies from which pool to draw.

    UgliGeomHandle cold_geom(vldc,Ugli::kFrozen);
    UgliGeomHandle playdough_geom(vldc,Ugli::kModifiable);
    
    UgliGeomHandle oneofthetwo_geom(vldc);

The cold_geom and playdough_geom are distinct geometries. The third geometry, since it has a compatible VldContext, is guarenteed to be one of the two previously created. But exactly which depends on the state of the DefaultModifyMode. This allows one to set the default so that an code written using the single argument for the constructor can be toggled:

    Ugli::SetDefaultModifyMode(Ugli::kModifiable);
    // run a job path to do some tracking/fitting 
    // it will run using the modified geometry
    // even if it wasn't explicitly written to do so.
    [...]
    // run a chi2 check against the modified geometry
    [...]
    Ugli::SetDefaultModifyMode(Ugli::kFrozen);
    // run a chi2 check against the frozen (Database) geometry
    [...]

Example code demonstrating some of the adjustment capabilities is show below:

 
    UgliStripHandle    ush  = playdough_geom.GetStripHandle(stripid);
    UgliScintPlnHandle usph = ush.GetScintPlnHandle();
    UgliScintMdlHandle usmh = ush.GetScintMdlHandle();
 
    // shift,rotate the strip relative to the module by
    // some delta from current position
    // L=longitudinal position, T=transverse position
    //ush.ShiftLTPosRelMdlBy(0*Munits::cm,1.0*Munits::cm);
    //ush.RotateRelMdlBy(2.0*Munits::mrad);
 
    // shift,rotate module relative to scint plane by absolute amounts
    usmh.SetLTPosRelPln(1.5*Munits::cm,200.0*Munits::cm);
    usmh.SetZRotRelPlnRad(2.0*Munits::mrad);

    // see Ugli*Handle for more details about available methods
    // currently UgliSteelPlnHandle's can not be adjusted.