Acts/Utilities/AnnealingUtility.hpp

0001 // This file is part of the ACTS project.
0002 //
0003 // Copyright (C) 2016 CERN for the benefit of the ACTS project
0004 //
0005 // This Source Code Form is subject to the terms of the Mozilla Public
0006 // License, v. 2.0. If a copy of the MPL was not distributed with this
0007 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include "Acts/Definitions/Algebra.hpp"
0012
0013 #include <cmath>
0014 #include <vector>
0015
0016 namespace Acts {
0017 /// @brief Implements a deterministic thermodynamic annealing scheme
0018 /// Ref. (1): CERN-THESIS-2010-027
0019 class AnnealingUtility {
0020  public:
0021   /// @brief The annealing state
0022   /// Resetting the state is done by just creating a new instance
0023   struct State {
0024     /// Index pointing to current temperature value in configuration array
0025     unsigned int currentTemperatureIndex{0};
0026
0027     /// Flag indicating whether equilibrium has been reached in annealing
0028     bool equilibriumReached{false};
0029   };
0030
0031   /// @brief The configuration struct
0032   struct Config {
0033     Config();
0034
0035     /// Constructor with parameters
0036     /// @param cutOff_ Cut-off threshold value
0037     /// @param setOfTemperatures_ Vector of temperature values for annealing
0038     Config(double cutOff_, std::vector<double> setOfTemperatures_)
0039         : cutOff(cutOff_), setOfTemperatures(std::move(setOfTemperatures_)) {}
0040
0041     /// Insensitivity threshold for calculated weight at cutoff
0042     double cutOff{9.};
0043
0044     /// Temperature sequence for annealing process, starts at first value
0045     /// and progresses towards the last value
0046     std::vector<double> setOfTemperatures{64., 16., 4., 2., 1.5, 1.};
0047   };
0048
0049   /// Constructor
0050   /// @param cfg The annealing configuration parameters
0051   explicit AnnealingUtility(const Config& cfg = Config()) : m_cfg(cfg) {
0052     // Set Gaussian cut-off terms for each temperature
0053     for (double temp : cfg.setOfTemperatures) {
0054       m_gaussCutTempVec.push_back(std::exp(-cfg.cutOff / (2. * temp)));
0055     }
0056   }
0057
0058   /// Does the actual annealing step
0059   /// @param state The state object to perform annealing on
0060   void anneal(State& state) const;
0061
0062   /// @brief Weight access
0063   ///
0064   /// @param state The state object
0065   /// @param chi2 Chi^2 for e.g. current track, i.e. compatibility
0066   /// of track to current vertex candidate
0067   /// @param allChi2 Vector of all chi^2 values, i.e. e.g. compatibilities
0068   /// of current track to all vertices it is currently attached to
0069   ///
0070   /// @return Calculated weight according to Eq.(5.46) in Ref.(1)
0071   double getWeight(State& state, double chi2,
0072                    const std::vector<double>& allChi2) const;
0073
0074   /// @brief Weight access
0075   ///
0076   /// @param state The state object
0077   /// @param chi2 Chi^2
0078   ///
0079   /// @return Calculated weight
0080   double getWeight(State& state, double chi2) const;
0081
0082  private:
0083   /// Configuration object
0084   Config m_cfg;
0085
0086   // For each temperature, a Gaussian term with the chi2 cut-off value
0087   // is calculated and stored here
0088   std::vector<double> m_gaussCutTempVec;
0089 };
0090 }  // namespace Acts