trapfinder.h

Go to the documentation of this file.

/*
 *            Copyright 2009-2026 The VOTCA Development Team
 *                       (http://www.votca.org)
 *
 *      Licensed under the Apache License, Version 2.0 (the "License")
 *
 * You may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *              http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */
 
#pragma once
#ifndef VOTCA_XTP_TRAPFINDER_H
#define VOTCA_XTP_TRAPFINDER_H
 
// Standard includes
#include <vector>
 
// Local VOTCA includes
#include "eigen.h"
#include "tofgraph.h"
 
namespace votca {
namespace xtp {

class TrapFinder {
 public:
  struct Settings {
    double threshold = 0.9;  // the paper's a
    double gap = 10.0;
    double mass = 0.5;
    Index max_size = 20;
    Index modes = 50;        // eigenvalues considered
    Index max_sites = 5000;  // dense eigenvalue problem
  };
 
  struct Trap {
    std::vector<Index> sites;  // graph site indices, deepest first
    double weight = 0.0;       // equilibrium probability
    double relaxation_rate = 0.0;
    double release_rate = 0.0;  // relaxation_rate (1 - weight)
    double capture_rate = 0.0;  // relaxation_rate weight
    double hop_rate = 0.0;
  };
 
  struct Result {
    std::vector<double> eigenvalues;
    double gap = 0.0;                // largest ratio l_{i+1}/l_i
    Index slow_modes = 0;            // i of the largest ratio
    std::vector<Trap> traps;         // empty if gap < Settings::gap
    std::vector<double> occupation;  // stationary distribution per site
  };
 
  static Result Find(const ToFGraph& graph, const Settings& settings);
  static Result Find(const ToFGraph& graph) { return Find(graph, Settings()); }
};
 
}  // namespace xtp
}  // namespace votca
 
#endif  // VOTCA_XTP_TRAPFINDER_H