Package              : Rich/RichMirrAlign
Package Coordinators : Paras Naik, Anatoly Solomin
Purpose              : RICH mirror alignment program
2019-08-30 - Paras Naik
- RICH-53 was supposed to recreate the same behavior as before RICH-53
  when stopDecisionMode == 1, however this was not the case if
  regularizationMode == 0. The code for those conditions was iterating
  even when an iteration was unnecessary, so PN has temporarily fixed
  this until Anatoly has the opportunity to address it further.

2018-07-03 - Anatoly Solomin
- Incremented version to v20r2.

- In line with RICH-53 JIRA task: "Upgrade iteration stopping decision
  at RichMirrAlign to be consistent with the latest regularization"
  Introduced new parameter stopDecisionMode 0/1.
  In case ==0 (default):
  if sqrt(regularizationTerm)/(priMirrTotNum + secMirrTotNum) >
  stopToleranceTotal (which is just ==
  nominalResolutionSigma * stopSigmaFraction),
  then the decision is to go for a next iteration.
  This case makes sence only when regularizationMode ==0,
  and therefore program throws
  if stopDecisionMode==0  &&  !(regularizationMode==0).
  In case ==1: calculations are done in compliance with the chosen
  regularizationMode, and each solution component (particular
  correction of the previous compensation) is tested individually,
  as before.

- Just for consistency, the code for the regularization term now
  "optically" more closely follows recent "compact" version of the maths
  in the alignment note for run 2.

- Fixed a typo in RichMirrAlignFcn.cpp, which did not influence solution
  with any significance, only in third digit after decimal point, i.e.
  only about few 0.001 mrad.

- Further "elevenized" the code, i.e. more use of C++11.

2017-12-07 - Anatoly Solomin
- Incremented version to v20r1.

- Updated the "regularizationMode" option's description.

- Improved the detailed printout of the MFs analysis and calculation.

2017-11-21 - Anatoly Solomin
- Incremented version to v20r0.

- In accordance with RICH-35 JIRA task, a new approach to the
  regularization is implemented, and it became the default mode, i.e.
  0. Previous version of the refined regularization term calculation
  became 10. If regularizationMode = 0 (default), the regularizing sum
  consists of the squares of the "magnified" solution vector
  components. Each component of the solution vector is multiplied by
  the respective individual magnification factors, MFs, both by
  "major" MF and also by respective "minor" (AKA "Y-Z cross-talk") MF,
  averaged for each primary/secondary mirror over its
  secondary/primary partners in the mirror combinations it
  participates and of course, over the respective calibrational, +/-,
  tilts.

- A thorough analysis of the MFs at each iteration is implemented, and
  detailed printout is supplied. It proves that the new approach is
  justified.

2017-10-27 - Anatoly Solomin
- Incremented version to v19r4.

- In accordance with RICH-35 JIRA task, the refined regularization
  term calculation becomes the default mode, i.e. 0/1.

2017-10-27 - Anatoly Solomin
- Incremented version to v19r3.

- In accordance with RICH-35 JIRA task, refined the regularization
  term calculation. The old algorithm remains in place with the
  same regularizationMode=0/1. While the refined analogous modes
  are 10/11 (magnified/non-magnified).
  After through tests we will place new calculation algorithm
  as the default mode, i.e. 0/1.

2017-10-19 - Paras Naik
- "Tagged" as v19r2p0 (internally, since only Panoptes gets a tag now).

- Removed the case insensitivity when parsing the mirror
  combination subsets file. The primary mirrors are now
  read in until the word 'Secondary', with that capitalization,
  is seen; then the secondary mirrors are read in.

- Confirmed that Mirror Combination Subsets are the same in
  Rich/RichMirrAlign as in Rich/RichMirrCombinFit
  and Rich/RichMirrorAlignmentOnline

2017-06-09 Rich/RichMirrAlign v19r2

This version was already in PANOPTES v7r3 but never tagged. Fixed key typo where SecZ was accidentally SecY. Fortunately, this had virtually no impact on our results since the quad tolerances were first implemented. Note that after moving from Subversion to git, versions of packages are no longer officially tagged; only projects are tagged now, but we keep an internal record of package versions anyway.

2017-06-09 - Paras Naik
- "Tagged" as v19r2 (internally, since only Panoptes gets a tag now).

- Added trailing slash to workDir in files/*.conf since this is now,
  always provided by RichMirrorAlignmentOnline and thus expected.

- Fixed typos, including key typo where SecZ was accidentally SecY.
  Fortunately, this had virtually no impact on our results since
  the quad tolerances were first implemented.

2016-05-22 Rich/RichMirrAlign v19r1

This version is in master of PANOPTES v6r0. The regularization in LS method is accounted for the magnifications (can be switched off). Added the ability to use four separate stop tolerances for primary and secondary mirrors and Y, Z, calculated from nominal sigma, its tolerance fraction and magnifications, or set by hand. Improved printouts. Eliminated default values for RICH-dependent options.

2016-05-22 - Anatoly Solomin
- Incremented version to v19r1.

- As Paras suggested, the "magnification" in the regularization
  term can now be switched off. Introduced regularizationMode
  option: 0(def)->use "magnified" with average magn factors
  regularization terms; !=0-> all "magnifications" = 1.
2016-04-25 - Anatoly Solomin
- Incremented version to v19r0.

- In LS method the regularizing sum is now squares of "magnified"
  solution. Each component of the solution vector is multiplied by
  the respective magnification factor, averaged over all mirror
  combinations and calibrational tilts.

- Introduced option nominalResolutionSigma: RICH-dependent nominal
  Cherenkov angle distribution sigma; no default here.

- Introduced option stopSigmaFraction (default 0.5): tolerance
  for total tilt of mirror pair in terms of fraction of the
  nominal sigma.

- Introduced option printMode: results print style mode
  0 - Paras one-glance style
  1 - Anatoly detailed style
  2 - both: first Anatoly, then Paras
  -2.17 will be printed as: 1-> -2.1, 0-> -2, while
  -0.97 will be printed as: 1->  -.9, 0->  0

- Introduced four (instead of two) RICH-dependent stop tolerances:
  stopTolerancePriY
  stopTolerancePriZ
  stopToleranceSecY
  stopToleranceSecZ

- Introduced option stopToleranceMode: 0(default)->calculate them
  from nominal sigma, average magn factors and stopSigmaFraction, e.g.
  stopTolerancePriY = 0.5*nominalResolutionSigma*stopSigmaFraction/
  (averaged magnification factor priY_Y)
  1->use those set up by hand in the conf file.

- Respective changes in the conf files. Examples in <...>/files.

- Eliminated default values for RICH-dependent options.

- Fixed and improved the printouts.

- Fixed previous entries of these release notes. This text is "pre",
  and therefore it should be decently formatted by hand in the
  editor: Ctrl+j. Otherwise it looks ugly in the browser.
  Also convention is to summarize only per Panoptes release, not per
  version increment of a package.

2016-04-09 - Paras Naik
- Added the ability to use separate stopTolerances for primary
  and secondary mirrors, If stopToleranceSec = 0, then all
  mirrors use stopTolerance to determine the threshold for
  alignment in this case, the printouts show the updated
  compensations in mrad, as used to be the case Otherwise the
  threshold for primary mirrors is stopTolerance and the
  threshold for secondary mirrors is stopToleranceSec in this new
  case, the printouts now show the updated compensations divided
  by the tolerance.

2016-03-29 - Paras Naik
- Incremented version to v18r5

- Remove thisVariant+"_" from the name of the predefined
  magnification factors text files if the string "online" is a
  substring of thisVariant

2016-03-21 - Paras Naik
- Incremented version to v18r4p0.

- Updated CMakeLists.txt

2016-03-09 - Anatoly Solomin
- Incremented version to v18r4.

- More simple way of reading the list of combinations from
  m_combAndMirrSubsetsFile.

- In parameter names in config file replaced subsets file name with
  combAndMirrSubsets

- combAndMirrSubsets file got new, more convenient format. Pattern
  is in Panoptes_XXXXX/Rich/RichMirrCombinFit/files

- Added "files" folder with *.conf files and
  RichMirrAlignREADME.txt with example how to run (cmt fashion).
  Updated cmt/requirements accordingly.

- Code style now complies to CERN's rules: indentations, TypeA* typea;
  ++i in loops, etc. Please, please, do not use your personal code
  styles: this is core LHCb software, not our private at all.

- Test folder removed for now: needs updating.

- HPD part still needs to be investigated.

2015-06-14 Rich/RichMirrAlign v18r3

This version released in PANOPTES v5r6. Added a new setting 'stopTolerance' that can be provided by conf file. If the updated compensations to mirror tilts are all less than stopTolerance, then the alignment will stop successfully.

2015-06-14 - Paras Naik
- Added a new setting 'stopTolerance' that can be provided by conf
  file. If the updated compensations to mirror tilts are all less
  than stopTolerance, then the alignment will stop successfully.

2015-03-30 Rich/RichMirrAlign v18r1

This version released in PANOPTES v5r4. Massive rewrite. Each RICH is aligned as a whole, not side-by-side. Least squares solution again became the main. New regularization minimizes perturbation caused by misalignment compensation. Algebraic method became rudimentary. More comprehensible summary tables print numbers truncated, not rounded.

2015-03-30 - Anatoly Solomin
- Changed back printout to provide one digit after the decimal
  point; Paras agreed. The numbers in the summary tables are
  now printed truncated, not rounded: -.095... is ".0" now. RICH
  number is printed with every mirror type title.

2015-03-28 - Paras Naik
- Changed printout to provide two digits after the decimal point.

2015-03-05 - Anatoly Solomin
- Added missing files with magnification factors to
  the Test directory.

2015-03-03 - Anatoly Solomin
- Incremented version to v18r1.
- Entire mirror system of a RICH is now aligned as a whole in
  one go, not side-by-side anymore.
- The algebraic method with fixed mirrors can still be chosen,
  although also in the "overall" mode.
- Files, necessary for testing in stand-alone mode are
  added in the Test directory. A small README instruction
  of how to build and then run the test is also included.
- Made consistent naming of the files used by the
  RichHPDAlign.cpp as well as some internal calls there.

2015-03-03 - Anatoly Solomin
- Incremented version to v17r1.
- The program is massively rewritten.
- Least-squares solution of the under-determined system of
  equations for rotational misalignments of the mirrors is now
  regularized by adding squared norm of the solution to the sum
  of squared residuals.
- The algebraic method can still be chosen.
- The printouts are principally more informative and graspable,
  while their code is way shorter and easier to understand.
- The code now is based on minimal number of maps, not vectors,
  it is shorter, more readable.
- More explanations added.
- The printout became a separate function.
- File-naming conventions are more consistent.
- The "Coombs" method of pre-averaging corrections for RICH1
  primary mirrors at the zeroth iteration is excluded.

2014-10-20 - Anatoly Solomin
- Fixed the program for RICH2 algebraic method.
- Added many comments.
- Changed and improved readability, consistency of some identifiers.
- Fixed and improved printouts.
- Added rich1PriMirrInitMethod program_option parameter to switch
  from standard to Matt Coombes method of RICH1 primary mirror
  initialization.

2014-03-10 - Anatoly Solomin
- Fixed map side0-side1 mirror numbers of RICH1. Eliminated its
  duplication.
- Fixed RICH1 equation-order string for the first iteration.

2014-03-09 - Anatoly Solomin
- Incremented version to v16r2
- Restored previous coding conventions.
- Improved readability.
- Fixed string defining the equation solving order. Only
  one primary 12 mirror has fixed correction instead of
  the pri 12 and sec 09 pair.
- Corrected RICH1 "most-populated" secondary mirror numbers.
- Added comments in the "algebraic" part of RICH2.
- For consistency, renamed RichAlignFcn to RichMirrAlignFcn.

2013-11-14 Rich/RichMirrAlign v16r1

This version released in PANOPTES v5r1. Added HPD alignment.

2012-12-20 - Matthew Coombes
- Removed more warnings

2012-12-10 - Matthew Coombes
- Removed some compile time warnings

2012-07-26 - Matthew Coombes
- Added HPD alignment to RichMirrAlign Package.

2011-06-09 Rich/RichMirrAlign v15r1

This version released in PANOPTES v3r4. Totally different wrappers. Usability improvements. New naming conventions.

2011-06-30 - Matthew Coombes
- Changed Rich1Fixed mirrors from sec 06 to pri 01
  to help with faster convergence.

2011-06-09 - Matthew Coombes
- Introduce algebraic solution method for RICH1

2011-06-08 - Anatoly Solomin
- Incremented version to v15r1.
- Streamlined job, file, etc. naming conventions for better
  usability. Modified programmatic name formation accordingly
- Improved code readability.
- Because the numerical part of the
  Rich/RichMirrorAlignmentGanga migrated from Job
  application GaudiPython to Executable (thus re-enabling
  the framework to run with the checked out local versions
  of the numeric packages RichMirrCombinFit and
  RichMirrAlign), the wrappers:
  Rich1MirrAlignWrapper.py and
  Rich2MirrAlignWrapper.py
  are totally rewritten.

2011-05-20 - Anatoly Solomin
- Incremented version to v14r5.
- Corrected these release notes: fixed the header of the
  previous release, to address the fact that in PANOPTES
  v3r0, v3r1 and v3r2 these packages were temporarily
  excluded, because xqilla was not yet available in the
  officially released LHCb environment.
- Erased from the code all previously commented out remnants
  of XercesC 2.8 and hence all non-XQilla code.
- Some formatting trims.

2011-03-30 Rich/RichMirrAlign v14r4

This version released in PANOPTES v3r3. Completely new approach: the system of equations is not over-determined any more; it is solved algebraically, not by minimization of RMS.

2011-03-30 - Matthew Coombes
- Incremented version to v14r4.
- Fixed bug to work with RICH1.
- Found bug that prevented alignment moving to it1 in solution
  method 0. Temp fix.

2010-11-09 - Anatoly Solomin
- Incremented version to v14r3. From now on, based only on
  Xerces-C++ 3.1 and XQilla.
- Completely new approach: the system of equations is not
  over-determined any more. An optimized subset of mirror
  pairs selected for that.
- The system is being solved by a combination of substitution
  method (pair-by-pair level) and Cramer's rule (Y/Z level).
- Method of solving the system using Minuit is retained as
  an alternative option.
- Fixed mirrors are denoted in the steering list by
  brackets and handled properly automatically.
- Further cosmetic improvements of printout.

2010-08-30 - Anatoly Solomin
- Incremented version to v12r0.
- Implemented fixation of pair of primary and secondary
  segments on each side of RICH2 p12s09 and p43s30.

2010-08-07 Rich/RichMirrAlign v11r0

This version released in PANOPTES v2r13. Universalized for both RICH detectors; implemented for both Xerces-C++ 2.8/3.1; migrated to XQilla (in case 3.1).

2010-08-07 - Anatoly Solomin
- Incremented version to v11r0.
- Migrated to XQilla.

2010-07-06 - Anatoly Solomin
- Incremented version to v10r0.
- Implemented fork (using #ifdef XERCESC_GE_31) for using both
  Xerces-C++ 2.8/3.1 in lhcb-prerelease/lhcb-gaudi-head
  nightlies respectively.
- For Xerces-C++ 3.1 implemented usage of XPath.

2010-07-01 - Anatoly Solomin, Matt Coombes
- Incremented version to v9r0.
- Started universalization for both RICHes.
- Started rewriting the Xerces part to meet new options in 3.1.
- Forked code so that it compiles against both 2.8 and 3.1 by
  using #ifdef XERCESC_GE_31.

2010-06-03 - Anatoly Solomin
- Incremented version to v8r2.
- Solved problem of back-reproducing the predefined tilts in MC
  for testing purposes.

2010-06-02 - Anatoly Solomin
- Made uniform format for tilts in xml.

2010-05-26 Rich/Rich2MirrAlign v8r1

This version released in PANOPTES v2r12. New, 2D approach; arbitrary mirror subsets; new parameter control; various fixes; improved general convergence; magnification coefficients variably calibrated.

2010-05-26 - Anatoly Solomin
- Incremented version to v8r1.
- Made magnification coefficients calibration tilts
  variate-able instead of being always 1 mrad.

2010-05-20 - Anatoly Solomin
- Added parameter for control of pre-misaligned case.
- Adapted for pre-misaligned case.
- Improved printout.
- More improved convergence of fit for each iteration.
- More improved convergence of the alignment in terms of the
  re-reconstruction iterations.

2010-05-14 - Anatoly Solomin
- Incremented version to v7r7.
- Improved printout.
- New (ASCII-graphical) way to choose subsets of mirror
  segments to be non-fixed, with variated alignment
  corrections.
- Improved convergence of fit for each iteration.
- Improved convergence of the alignment in terms of the
  re-reconstruction iterations.

2010-05-04 - Anatoly Solomin
- Incremented version to v7r6.
- Added printing of the cumulative corrections after each
  iteration.

2010-04-26 - Anatoly Solomin
- Incremented version to v7r5.
- Fixed stop-to-iterate criterion.
- Improved printing of the resultant corrections of each
  iteration.

2010-04-15 - Anatoly Solomin
- Incremented version to v7r4.
- Improved naming convention. Following respective
  modifications in the Rich2MirrCombinFit.
- Better passing variant name via program options.

2010-03-28 - Anatoly Solomin
- Incremented version to v7r2. Accumulates massive modifications.
- Fit both dimensions, i.e. Y and Z jointly. As a consequence,
  number of equations doubled.
- Subset of mirrors defined by an "ASCII-pictorial" list of
  chosen mirror combinations.
- Control parameters are now keyed, and typed as a key=value
  column in Rich2MirrAlign.conf. Modified the
  Rich2MirrAlignWrapper.py Use boost::program_options library.
- Separate lists of mirror combinations for each side.
- Eight families of conversion coefficients: primary/secondary
  times Y/Z times +/-. Each mirror segment tilt around one
  axis results in final tilts around both axes: major around
  the corresponding, minor around the alternative one.

2009-10-23 Rich/Rich2MirrAlign v5r6

This version released in PANOPTES v2r7. Minor cleanup.

2009-07-21 - Anatoly Solomin
- Incremented version to v5r6.
- Minor cleanup.

2009-07-21 Rich/Rich2MirrAlign v5r4

This version released in PANOPTES v2r5. Resolved degeneracy, degraded precision in favor of stability and reduced hardcodedness.

2009-07-21 - Anatoly Solomin
- Incremented version to v5r4.
- Reduced hardcodedness.

2009-07-16 - Anatoly Solomin
- Incremented version to v5r3.
- Fit one dimension at a time, i.e. Y and Z separately.
- System of equations degeneracy resolved by always fixing
  one of the sought tilts equal to 0.0.
- Add fit of the "right-hand" side.

2009-04-20 - Anatoly Solomin
- Update file names for using 2008 geometry.

2009-03-04 - Anatoly Solomin
- Increment version: v4r1.

2009-02-27 Rich/Rich2MirrAlign v4r0

Major revamp for DDDB 2008 using XercesC 2.8. This version released in PANOPTES v2r2.

2009-02-11 - Anatoly Solomin
- Massive rewrite of main.cpp using XercesC 2.8 to work with
  DDDB 2008.
- Add use XercesC to requirements file.
- Add several helper classes.

2009-02-06 - Ulrich Kerzel
- add Gaudi Policy to requirements file,
- add apply_pattern to requirements file
- change <.h> to ".h"

2008-11-01 Rich/Rich2MirrAlign v3r1

This version is the first official release.

2008-11-14 - Anatoly Solomin
- Wrap Rich2MirrAlign.exe executable into the
  python/Rich2MirrAlignWrapper.py. This enables Ganga to run
  it within a Ganga script the following way:
  app = GaudiPython( project ='Panoptes', ...)
  j = Job( application = app )
  j.application.script = expandvars('.../Rich2MirrAlignWrapper.py')
  j.inputsandbox += [expandvars('.../Rich2MirrAlign.exe')]

2008-11-01 - Anatoly Solomin
- Parameter definitions for Minuit are now map-directed.