graphrandomwalk.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_GRAPHRANDOMWALK_H
#define VOTCA_XTP_GRAPHRANDOMWALK_H
 
// Standard includes
#include <array>
#include <stdexcept>
#include <string>
#include <vector>
 
// Third party includes
#include <Eigen/SparseCore>
 
// Local VOTCA includes
#include "eigen.h"
#include "tofgraph.h"
 
namespace votca {
namespace xtp {

class GraphRandomWalk {
 public:
  enum class Solver { Auto, Cholesky, LU, CG, BiCGSTAB };
  enum class Observable { First, Transit };
 
  struct Settings {
    Index direct_limit = 5000;
    double tolerance = 1e-14;
    Index max_iterations = 100000;
    Index max_states = 50000000;
  };
 
  struct Result {
    std::string solver;
    Index carriers = 1;
    Observable observable = Observable::First;
    Index unknowns = 0;
    double backward_error = 0.0;
    Index refinement_steps = 0;
    Index iterations = 0;
    bool converged = true;

    std::vector<std::vector<Index>> sources;
    Eigen::VectorXd tau;
    Eigen::VectorXd tau_std;

    double tau_mean = 0.0;
    double tau_std_injection = 0.0;
    double tau_harmonic = 0.0;

    Eigen::VectorXd occupation_time;
  };
 
  explicit GraphRandomWalk(const ToFGraph& graph) : graph_(graph) {
    if (graph_.isBulk()) {
      throw std::runtime_error(
          "GraphRandomWalk: hitting times need a ToF graph with sinks, not a "
          "bulk graph without sinks");
    }
  }
 
  void setSettings(const Settings& settings) { settings_ = settings; }
 
  Result SingleCarrier(Solver solver = Solver::Auto) const;
 
  Result TwoCarriers(Observable observable, Solver solver = Solver::Auto) const;
 
  static Solver SolverFromString(const std::string& name);
  static Observable ObservableFromString(const std::string& name);
 
 private:
  struct Transient {
    std::vector<Index> index_of;      // graph site -> transient index or -1
    std::vector<Index> site_of;       // transient index -> graph site
    Eigen::VectorXd half_log_weight;  // -(U - Uref)/2kT
  };
  Transient FindTransient() const;
 
  const ToFGraph& graph_;
  Settings settings_;
};
 
}  // namespace xtp
}  // namespace votca
 
#endif  // VOTCA_XTP_GRAPHRANDOMWALK_H