bulksimulation.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_BULKSIMULATION_H
#define VOTCA_XTP_BULKSIMULATION_H
 
// Standard includes
#include <cstdint>
#include <memory>
#include <string>
#include <vector>
 
// Local VOTCA includes
#include "eigen.h"
#include "kmcengine.h"
#include "kmcrates.h"
#include "kmcwaitingtime.h"
#include "tofgraph.h"
 
namespace votca {
namespace xtp {

class BulkSimulation {
 public:
  struct Settings {
    std::uint64_t seed = 1;
    Index runs = 1;
    Index carriers = 1;
    KMCEngine::Limits limits;
    double equilibration = 0.0;  // s
    Index blocks = 50;
    double sample_interval = 0.0;
    Index sample_hops = 0;
  };

  struct Sample {
    double time = 0.0;
    Index hops = 0;
    std::vector<Eigen::Vector3d> positions;
    double energy = 0.0;
  };
 
  struct RunData {
    KMCEngine::RunStatus status;
    double start = 0.0;
    double end = 0.0;
    Eigen::Vector3d velocity = Eigen::Vector3d::Zero();
    Eigen::Matrix3d diffusion = Eigen::Matrix3d::Zero();
    Eigen::Matrix3d velocity_covariance = Eigen::Matrix3d::Zero();
    Index blocks = 0;
    double block_length = 0.0;
    std::vector<Eigen::Vector3d> displacement;
  };
 
  struct Result {
    std::vector<RunData> runs;
    Eigen::Vector3d velocity = Eigen::Vector3d::Zero();
    Eigen::Vector3d velocity_error = Eigen::Vector3d::Zero();
    Eigen::Matrix3d diffusion = Eigen::Matrix3d::Zero();
    Eigen::Matrix3d diffusion_error = Eigen::Matrix3d::Zero();
    Eigen::VectorXd occupation;
    std::vector<Sample> trajectory;
    Index hops = 0;
    Index null_events = 0;
    Index wall_time_stops = 0;
  };

  struct ExactResult {
    bool available = false;
    std::string message;
    Index sites = 0;  // in the closed class
    Eigen::Vector3d velocity = Eigen::Vector3d::Zero();
    Eigen::Matrix3d diffusion = Eigen::Matrix3d::Zero();
    Eigen::VectorXd occupation;  // pi, zero outside the closed class
    std::string solver;
    double backward_error = 0.0;
    bool converged = false;
  };

  static ExactResult Exact(const ToFGraph& graph, Index direct_limit = 20000,
                           double tolerance = 1e-12);

  BulkSimulation(const ToFGraph& graph, const Settings& settings);
  BulkSimulation(const ToFGraph& graph, const Settings& settings,
                 const TimeDependentRates& rates,
                 WaitingTimeStrategy& strategy);
 
  Result Simulate() const;
 
 private:
  const ToFGraph& graph_;
  Settings settings_;
  std::unique_ptr<TimeDependentRates> own_rates_;
  std::unique_ptr<WaitingTimeStrategy> own_strategy_;
  std::unique_ptr<KMCEngine> engine_;
 
  void Check() const;
  RunData SingleRun(Index run, Eigen::VectorXd& occupation,
                    std::vector<Sample>* trajectory) const;
};
 
}  // namespace xtp
}  // namespace votca
 
#endif  // VOTCA_XTP_BULKSIMULATION_H