Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 81 additions & 0 deletions docs/advanced/scf/construct_H.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,3 +80,84 @@ Conventional functionals, e.g., L(S)DA and GGAs, encounter failures in strongly
Now the DFT+*U* method is accessible in ABACUS. The details of the DFT+*U* method could be found in this [paper](https://doi.org/10.1063/5.0090122). It should be noted that the DFT+*U* works only within the NAO scheme, which means that the value of the keyword `basis_type` must be lcao when DFT+*U* is called. To turn on DFT+*U*, users need to set the value of the `dft_plus_u` keyword in the `INPUT` file to be 1. All relevant parmeters used in DFT+*U* calculations are listed in the [DFT+*U* correction](../input_files/input-main.md#dftu-correction) part of the [list of keywords](../input_files/input-main.md).

Examples of DFT+*U* calculations are provided in this [directory](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/19_dftu).

### Full-projector double counting

Here **Full** names the existing radius-adjustable localized projection
(`dft_plus_u=1`, controlled by `onsite_radius`) implemented by `DFTU_onsite`.
It does **not** mean a full anisotropic $U/J$ interaction. The input
`hubbard_u` is the simplified $U_{\rm eff}=U-J$; no separate Hund's $J$ or
Slater-integral tensor is introduced. Retaining `DFTU_onsite` is not the
addition of a new On-site/projector-3 method.

For this projector, `dftu_dc` selects `fll` (default),
`amf`, or `mixed`. Omitting the new parameters or explicitly selecting `fll`
keeps the existing FLL potential and energy path. This extension does not
change Dual (`dft_plus_u=2`) or add another projector.

For fixed-weight interpolation, specify both parameters:

```text
dftu_dc mixed
dftu_alpha 0.5
```

`dftu_alpha` must be explicitly supplied, finite and in [0,1] for `mixed`;
it is rejected for other modes. Zero gives AMF and one gives FLL. The mixing
is applied to the local interaction energy and its potential, not to two
separate SCF results. This is a fixed input weight, not a self-consistently
determined interpolation parameter.

For each atom and spin channel $\sigma$, let $n^\sigma$ be the existing
projected Hermitian occupation matrix of dimension $M=2l+1$ and
$N_\sigma=\mathrm{Tr}(n^\sigma)$. AMF subtracts the orbital average
$\bar n_\sigma=N_\sigma/M$ **within each spin channel**, not the common
spin average $(N_\uparrow+N_\downarrow)/(2M)$. No additional trace
normalization or rescaling of the existing projected occupation is applied.
Suppressing the atom/spin labels, the isotropic effective-$U$ convention is

$$
E_\alpha=\frac{U_{\rm eff}}{2}
\left[\alpha N+(1-\alpha)\frac{N^2}{M}-\mathrm{Tr}(n^2)\right],
\qquad
V_\alpha=U_{\rm eff}\left[
\left(\frac{\alpha}{2}+(1-\alpha)\frac{N}{M}\right)I-n\right].
$$

In particular, $E_{\rm AMF}=-U_{\rm eff}\mathrm{Tr}[(n-\bar n I)^2]/2$.
Thus a uniform shell in either spin channel has zero AMF correction, even
when the two spin channels have different occupations. Both the functional
and its derivative are interpolated at the **same** occupation and a fixed
input $\alpha$, not at occupations from separate converged calculations.

Here $\delta E=\mathrm{Re}\,\mathrm{Tr}(V\delta n)$. Energies are summed over
atoms and spin channels. For `nspin=1`, the existing Full occupation builder
halves the spin-summed density; the resulting shell energy is doubled, but
the potential is not. The Full operator's band-energy correction is
$E_\alpha-\mathrm{Re}\,\mathrm{Tr}(V_\alpha n)$, evaluated with the **same**
occupation as the potential. This extension retains that existing update
timing; it does not implement a different post-diagonalization energy ledger.
Equivalently, for a spin-summed matrix $D$ in `nspin=1`,
$E_{\rm total}(D)=2E_\alpha(D/2)$ and
$\delta E_{\rm total}=\mathrm{Re}\,\mathrm{Tr}[V_\alpha(D/2)\delta D]$.
The factor two in the energy cancels the one-half from differentiating the
occupation, so doubling the potential would be incorrect. With `nspin=2`,
the two shell energies and band corrections are accumulated once each.

AMF and mixed requests, including both endpoints, currently require explicit
PBE, double-precision CPU LCAO, fixed-structure KS SCF, collinear `nspin=1/2`,
`symmetry=0` or `-1`, one k pool and atomic cold start. The supported solver
choices are `genelpa`, `elpa`, `lapack` and `scalapack_gvx`. Gamma and multi-k
representations use the same local-shell formulas. SOC/spin constraints,
force/stress requests even during fixed-structure SCF, restart/occupation
files, U ramping, Yukawa U, occupation/DMR
mixing, EXX and matrix/Wannier/QO exports are rejected. These new restrictions
do **not** apply to legacy FLL requests. Charge and Mulliken output remain
available.

For context on FLL, AMF and interpolation, see
[Dudarev et al., Phys. Rev. B 57, 1505 (1998)](https://doi.org/10.1103/PhysRevB.57.1505),
[Czyzyk and Sawatzky, Phys. Rev. B 49, 14211 (1994)](https://doi.org/10.1103/PhysRevB.49.14211), and
[Petukhov et al., Phys. Rev. B 67, 153106 (2003)](https://doi.org/10.1103/PhysRevB.67.153106).
The equations above specify the convention implemented here; this is not a
general Slater-integral or self-consistent-alpha implementation.
2 changes: 2 additions & 0 deletions source/Makefile.Objects
Original file line number Diff line number Diff line change
Expand Up @@ -829,6 +829,7 @@ OBJS_IO=module_parameter/input_conv.o\
module_parameter/sccs_inp_check.o\
module_parameter/read_inp_postproc.o\
module_parameter/read_inp_exx_dftu.o\
dftu_dc_check.o\
module_parameter/read_inp_dfpt.o\
module_parameter/read_inp_other.o\
module_parameter/read_inp_out.o\
Expand Down Expand Up @@ -1125,6 +1126,7 @@ OBJS_DFTU=dftu_nao_fs_k.o\
dftu_nao_str_r.o\
dftu_nao_folding.o\
dftu_nao_pots.o\
dftu_full_dc.o\
dftu_nao_energy.o\
dftu_nao_op_legacy.o\
dftu_nao_adj.o\
Expand Down
2 changes: 2 additions & 0 deletions source/source_io/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,8 @@ add_library(
module_parameter/sccs_inp_check.cpp
module_parameter/read_inp_postproc.cpp
module_parameter/read_inp_exx_dftu.cpp
# DFT+U owns these checks; INPUT and documentation need them even without LCAO.
../source_lcao/module_dftu/dftu_dc_check.cpp
module_parameter/read_inp_other.cpp
module_parameter/read_inp_out.cpp
module_parameter/availability.cpp
Expand Down
2 changes: 2 additions & 0 deletions source/source_io/module_parameter/input_parameter.h
Original file line number Diff line number Diff line change
Expand Up @@ -714,6 +714,8 @@ struct Input_para
// DFT+U Xin Qu added on 2020-10-29
int dft_plus_u = 0; ///< 0: standard DFT calculation (default)
bool dft_plus_dmft = false; ///< true:DFT+DMFT; false: standard DFT calcullation(default)
std::string dftu_dc = "fll"; ///< Full DC: fll, amf or fixed-alpha mixed
double dftu_alpha = 1.0; ///< used only by mixed; explicit INPUT required
bool yukawa_potential = false; ///< default: false
double yukawa_lambda = -1.0; ///< default: -1.0, which means we calculate lambda
double uramping_eV = -1.0; ///< U-Ramping method (eV)
Expand Down
52 changes: 52 additions & 0 deletions source/source_io/module_parameter/read_inp_exx_dftu.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
#include "source_base/tool_quit.h"
#include "read_input.h"
#include "read_input_tool.h"
#include "source_lcao/module_dftu/dftu_dc_check.h"
#include <iomanip>
#include <limits>
namespace ModuleIO
{
void ReadInput::item_exx()
Expand Down Expand Up @@ -720,6 +723,55 @@ void ReadInput::item_dftu()
};
this->add_item(item);
}
{
Input_Item item("dftu_dc");
item.domain.set_choices({"fll", "amf", "mixed"});
item.annotation = "double counting for radius-adjustable Full Ueff DFT+U";
item.category = "DFT+U correction";
item.type = "String";
item.default_value = "fll";
item.unit = "";
item.description = R"(Double counting: `fll` preserves the legacy path; `amf` and `mixed` opt into a Full-only extension (`dft_plus_u=1`).
Full denotes the existing radius-adjustable localized projection implemented by DFTU_onsite, not an anisotropic U/J functional. hubbard_u is Ueff=U-J.
AMF subtracts Tr(n_sigma)/(2l+1) separately in each spin channel, using the existing projected occupation without additional normalization.
`mixed` uses fixed dftu_alpha: 0 is AMF, 1 is FLL. Both local interaction energy and potential are mixed, not two SCF results.
For nspin=1 the spin-summed occupation is halved and the shell energy doubled, but the potential is not doubled. The band correction is E_corr-ReTr(V*n).
New modes require explicit PBE, CPU double-precision LCAO KS SCF, nspin=1/2, symmetry=0/-1, a single k pool and atomic cold start. Supported solvers are genelpa, elpa, lapack and scalapack_gvx.
SOC, spin constraints, force/stress, restart, EXX, U ramping, Yukawa U, occupation/DMR mixing and matrix/Wannier/QO exports are not supported. These restrictions also apply to mixed endpoints, but not to fll.)";
read_sync_string(input.dftu_dc);
this->add_item(item);
}
{
Input_Item item("dftu_alpha");
item.set_availability("dftu_dc==mixed");
item.annotation = "fixed FLL weight for mixed Full DFT+U";
item.category = "DFT+U correction";
item.type = "Real";
item.default_value = "explicitly required for mixed; otherwise unused";
item.unit = "";
item.description = "Explicit finite weight in [0,1] for dftu_dc=mixed. Zero gives AMF and one gives FLL. Not accepted for other DC modes. This weight is fixed, not determined self-consistently.";
item.domain.scalar();
item.domain.set_rule("value>=0 and value<=1");
item.read_value = [](const Input_Item& item, Parameter& para) {
const std::string& token = item.str_values.at(0);
para.input.dftu_alpha = DFTU_LCAO::parse_dftu_alpha(token);
};
sync_double(input.dftu_alpha);
item.get_final_value = [](Input_Item& item, const Parameter& para) {
// Preserve near-endpoint weights when the emitted INPUT is read again.
item.final_value << std::setprecision(std::numeric_limits<double>::max_digits10)
<< para.inp.dftu_alpha;
};
item.check_value = [](const Input_Item& item, const Parameter& para) {
const bool was_read = item.is_read();
const std::string error = DFTU_LCAO::dftu_dc_error(para.inp, was_read, para.sys.kpar_lcao);
if (!error.empty())
{
ModuleBase::WARNING_QUIT("ReadInput", error);
}
};
this->add_item(item);
}
{
Input_Item item("dft_plus_dmft");
item.annotation = "true:DFT+DMFT; false: standard DFT calcullation(default)";
Expand Down
5 changes: 5 additions & 0 deletions source/source_io/module_parameter/read_input.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -738,6 +738,11 @@ void ReadInput::write_txt_input(const Parameter& param, const std::string& filen
for (auto& item: this->input_lists)
{
Input_Item* p_item = &(item.second);
// An inactive mixed-only weight must not become explicit INPUT on reread.
if (p_item->label == "dftu_alpha" && param.inp.dftu_dc != "mixed")
{
continue;
}
// Do not serialize an inactive internal marker as a public INPUT value.
if (!p_item->domain.can_write(param)) { continue; }
if (p_item->get_final_value == nullptr) {
Expand Down
6 changes: 6 additions & 0 deletions source/source_io/test_serial/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ add_library(
../module_parameter/sccs_inp_check.cpp
../module_parameter/read_inp_postproc.cpp
../module_parameter/read_inp_exx_dftu.cpp
../../source_lcao/module_dftu/dftu_dc_check.cpp
../module_parameter/read_inp_other.cpp
../module_parameter/read_inp_out.cpp
../module_parameter/read_input.cpp
Expand Down Expand Up @@ -55,6 +56,11 @@ addtest(

addtest(TARGET MODULE_IO_read_input_tool SOURCES read_input_tool_test.cpp)

addtest(
TARGET MODULE_IO_read_inp_exx_dftu
LIBS parameter base device io_input_serial
SOURCES ../unittests/test_read_inp_exx_dftu.cpp)

addtest(
TARGET MODULE_IO_rho_io
LIBS parameter base device cell_info
Expand Down
14 changes: 14 additions & 0 deletions source/source_io/unittests/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ addTest(

addtest(TARGET MODULE_IO_spin_tag SOURCES test_spin_tag.cpp)

addtest(
TARGET MODULE_IO_dftu_dc_check
SOURCES test_dftu_dc_check.cpp ../../source_lcao/module_dftu/dftu_dc_check.cpp)

addtest(
TARGET MODULE_IO_libxc_r_suffix
SOURCES test_libxc_r_suffix.cpp
Expand Down Expand Up @@ -52,6 +56,16 @@ foreach(
duplicate_string_eof
invalid_value
invalid_dependency
dftu_default
dftu_fll
dftu_amf
dftu_mixed0
dftu_mixed05
dftu_mixed1
dftu_alpha_below_zero
dftu_alpha_above_one
dftu_alpha_nonfinite
dftu_alpha_trailing
out_dmk_zero_precision
out_hsk_zero_precision
out_mat_tk_zero_precision
Expand Down
Loading
Loading