convergenceacc.h

Go to the documentation of this file.

/*
 *            Copyright 2009-2020 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_CONVERGENCEACC_H
#define VOTCA_XTP_CONVERGENCEACC_H
 
// VOTCA includes
#include <votca/tools/linalg.h>
 
// Local VOTCA includes
#include "adiis.h"
#include "aomatrix.h"
#include "diis.h"
#include "logger.h"
 
namespace votca {
namespace xtp {

class ConvergenceAcc {
 public:
  enum KSmode { closed, open, fractional, restricted_open };

  struct options {
    KSmode mode = KSmode::closed;
    bool usediis;
    bool noisy = false;
    Index histlength;
    bool maxout;
    double adiis_start;
    double diis_start;
    double levelshift;
    double levelshiftend;
    // Independent from adiis_start deliberately -- see
    // UKSConvergenceAcc::Iterate's own comment on where this is used
    // for the full reasoning: ORCA's own DampErr is kept fully
    // separate from its own DIISStart, and their own guidance for
    // difficult systems is to make DampErr much SMALLER than default
    // (keeping damping active LONGER), independent of when DIIS
    // itself engages. Reusing adiis_start for both purposes could not
    // represent that independently.
    double mixingend;
    Index numberofelectrons;
    double mixingparameter;
    // Ceiling mixingparameter can adaptively ramp up toward as the SCF
    // struggles, rather than staying fixed at mixingparameter (the
    // BASE/starting value) for the whole run -- matches ORCA's own
    // static-damping design directly (confirmed from a real ORCA log's
    // own resolved SCF settings, not the manual's generic defaults):
    // DampFac (the base, 0.7 by default) and DampMax (the ceiling, 0.98
    // by default) are two separate parameters there, not one fixed
    // value. Notably, 0.98 is exactly the value this session's own
    // hand-tuning independently landed on for a difficult water dimer
    // case -- this adaptive design is a more principled way to obtain
    // that same benefit only when actually needed, rather than paying
    // its cost (slower convergence on easy iterations) for an entire
    // run regardless of whether the system is struggling at all.
    double mixingmax;
    double Econverged;
    double error_converged;
    Index number_alpha_electrons = 0;
    Index number_beta_electrons = 0;
    // Maximum iterations for the Davidson eigensolver used by
    // CoupledAugmentedHessianStep's own direct-minimization fallback --
    // NOT CDFT-specific, since that fallback can engage for any
    // sufficiently difficult UKS SCF (see this field's own XML help
    // text, dftpackage.xml, for the real case that motivated exposing
    // this at all: a strong CDFT constraint over a large fragment left
    // the solver still short of its own convergence tolerance at the
    // previous, hardcoded default of 50).
    Index davidson_max_iter = 50;
  };

  struct SpinDensity {
    Eigen::MatrixXd alpha;
    Eigen::MatrixXd beta;

    Eigen::MatrixXd total() const { return alpha + beta; }

    Eigen::MatrixXd spin() const { return alpha - beta; }
  };

  void Configure(const ConvergenceAcc::options& opt) {
    opt_ = opt;
    if (opt_.mode == KSmode::closed) {
      nocclevels_ = opt_.numberofelectrons / 2;
    } else if (opt_.mode == KSmode::open) {
      nocclevels_ = opt_.numberofelectrons;
    } else if (opt_.mode == KSmode::fractional) {
      nocclevels_ = 0;
    } else if (opt_.mode == KSmode::restricted_open) {
      nocclevels_ =
          std::max(opt_.number_alpha_electrons, opt_.number_beta_electrons);
    }
    diis_.setHistLength(opt_.histlength);
  }

  void setLogger(Logger* log) { log_ = log; }

  void PrintConfigOptions() const;

  bool isConverged() const {
    if (totE_.size() < 2) {
      return false;
    } else {
      return std::abs(getDeltaE()) < opt_.Econverged &&
             getDIIsError() < opt_.error_converged;
    }
  }

  double getDeltaE() const {
    if (totE_.size() < 2) {
      return 0;
    } else {
      return totE_.back() - totE_[totE_.size() - 2];
    }
  }

  void setOverlap(AOOverlap& S, double etol);

  double getDIIsError() const { return diiserror_; }

  bool getUseMixing() const { return usedmixing_; }

  Eigen::MatrixXd Iterate(const Eigen::MatrixXd& dmat, Eigen::MatrixXd& H,
                          tools::EigenSystem& MOs, double totE);
  tools::EigenSystem SolveFockmatrix(const Eigen::MatrixXd& H) const;
  void Levelshift(Eigen::MatrixXd& H, const Eigen::MatrixXd& MOs_old) const;

  Eigen::MatrixXd DensityMatrix(const tools::EigenSystem& MOs) const;

  SpinDensity DensityMatrixSpinResolved(const tools::EigenSystem& MOs) const;
 
 private:
  options opt_;

  Eigen::MatrixXd DensityMatrixGroundState(const Eigen::MatrixXd& MOs) const;
  Eigen::MatrixXd DensityMatrixGroundState_unres(
      const Eigen::MatrixXd& MOs) const;
  Eigen::MatrixXd DensityMatrixGroundState_frac(
      const tools::EigenSystem& MOs) const;

  SpinDensity DensityMatrixGroundState_restricted_open(
      const Eigen::MatrixXd& MOs) const;
 
  bool usedmixing_ = true;
  double diiserror_ = std::numeric_limits<double>::max();
  Logger* log_;
  const AOOverlap* S_;
 
  Eigen::MatrixXd Sminusahalf;
  std::vector<Eigen::MatrixXd> mathist_;
  std::vector<Eigen::MatrixXd> dmatHist_;
  std::vector<double> totE_;
 
  Index nocclevels_;
  Index maxerrorindex_ = 0;
  double maxerror_ = 0.0;
  ADIIS adiis_;
  DIIS diis_;
};
 
}  // namespace xtp
}  // namespace votca
 
#endif  // VOTCA_XTP_CONVERGENCEACC_H