kmcengine.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_KMCENGINE_H
#define VOTCA_XTP_KMCENGINE_H
 
// Standard includes
#include <cmath>
#include <cstdint>
#include <limits>
#include <string>
#include <vector>
 
// Local VOTCA includes
#include "eigen.h"
#include "kmcrandom.h"
#include "kmcwaitingtime.h"
#include "tofgraph.h"
 
namespace votca {
namespace xtp {

class KMCEngine {
 public:
  using Random = KMCRandom;
 
  struct Pulse {
    enum class Shape { Delta, Gaussian, Rectangular };
    double start = 0.0;  // s
    Index carriers = 1;
    Shape shape = Shape::Delta;
    double width = 0.0;  // s: standard deviation (Gaussian) or full width
  };

  static std::vector<double> InjectionTimes(const std::vector<Pulse>& pulses,
                                            Random& random);
  static Pulse::Shape ShapeFromString(const std::string& name);
 
  class Observer {
   public:
    virtual ~Observer() = default;
    virtual void Inject(Index /*carrier*/, Index /*site*/, double /*t*/) {}
    virtual void Hop(Index /*carrier*/, Index /*from*/, Index /*to*/,
                     const Eigen::Vector3d& /*dR*/, double /*t*/) {}
    virtual void Absorb(Index /*carrier*/, Index /*site*/, double /*t*/) {}
    virtual void Decay(Index /*carrier*/, Index /*site*/, double /*t*/) {}
  };
 
  struct DecaySettings {
    const std::vector<double>* rates = nullptr;
    bool replace = false;
  };
 
  struct Limits {
    double max_time = std::numeric_limits<double>::infinity();
    Index max_events = std::numeric_limits<Index>::max();
    double max_wall_time = std::numeric_limits<double>::infinity();
    Index max_decays = std::numeric_limits<Index>::max();
  };
 
  struct RunStatus {
    double end_time = 0.0;
    Index hops = 0;
    Index null_events = 0;
    Index injected = 0;
    Index absorbed = 0;
    Index decayed = 0;
    Index blocked_injections = 0;
    bool censored = false;
    bool reached_max_time = false;
    bool reached_wall_time = false;
    bool reached_max_decays = false;
    Index events = 0;
  };

  KMCEngine(const ToFGraph& graph, const WaitingTimeStrategy& strategy)
      : graph_(graph), strategy_(strategy) {}

  void setDecay(const DecaySettings& decay);

  RunStatus Run(const std::vector<double>& injection_times, Random& random,
                Observer& observer, const Limits& limits) const;
 
 private:
  const ToFGraph& graph_;
  const WaitingTimeStrategy& strategy_;
  DecaySettings decay_;
};
 
}  // namespace xtp
}  // namespace votca
 
#endif  // VOTCA_XTP_KMCENGINE_H