# Constrained Density Functional Theory (cDFT)

- Author:
Gilberto Teobaldi, University of Liverpool (g.teobaldi@liv.ac.uk)

- Date:
November 2013

## cDFT input check-list

This is a short check-list meant to help the setting up of a constrained-DFT (cDFT) simulation. ONETEP implements some rather extensive check of the input (as specified in .dat file). In spite of this, users may be still capable of creating erroneous inputs which I could not think of. If you experience disaster (commutators larger than 1.E-3, NWGFs- and cDFT-optimisation stuck at the same value of the gradient for many iterations, or NaN (Not A Number) and ‘***’ outputs from ONETEP), please do get in touch.

### Can I start by running a cDFT geometry-optimisation and/or Molecular Dynamics straightaway?

Currently, this is **not** possible. ONETEP will not allow you to run a
geometry-optimisation/molecular dynamics simulation unless a .cdft file
(containing the cDFT-potentials, Uq/s) is present. This is meant to
force you to first make sure that your cDFT-settings let you obtain a
good convergence in a single-point calculation for the system and
constrained solution you are interested in.

### What projectors am I telling ONETEP to use?

Is cdft_read_projector=F (this is the default) and cdft_multi_proj=F (this is the default) in your input?

If so, you will be using as cDFT-projectors the orbitals, of angular
momentum *L-projectors*, of a hydrogenic atom of atomic number
*Z-projector*, provided *Z-projector* is positive in the %block
constrained_dft (Z>0). Conversely, if you have entered a negative
*Z-projector* value in the %block constrained_dft (Z<0), you will be
using the numerical orbital (of angular momentum *L-projectors*) for the
given cDFT-atom as cDFT-projectors.

Is cdft_multi_proj=T (this is NOT the default) in your input?

If so, you will be using as cDFT-projectors the numerical orbitals, obtained from the pseudo-atom solver. You will be using as many cDFT-projectors as NGWFs for the given cDFT-site. Thus, to know the number and angular momentum of your cDFT-projectors, you need to refer to the specific settings of the cDFT-site in the %block species_atom_set and the relevant output in the standard .out file.

Is cdft_read_projector=T in your input?

If so, you will use the projectors stored in the .tightbox_hub_projs
file (or experience a crash if this file is not present). Mind that the
file will contain different classes of projectors (hydrogenic orbitals,
numerical orbitals, self-consistent projectors) depending on the
settings you used for the cDFT-run which generated the
.tightbox_hub_projs file. This means that, unless one wants to
experience a crash, the projectors in the .tightbox_hub_projs file
should have been generated with the same entries for *Z-projector* *and
L-projector* in %block constrained_dft **OR** cdft_multi_proj and
%block species_atom_set as in the current calculation.

### Is this the first single-point cDFT submission or do I want to restart a single-point calculation?

For submission from scratch the user can chose between starting the
cDFT-run from previously obtained DFT-NGWFs and Density Kernel (DKN), by
setting (read_denskern=T and read_tightbox_ngwfs=T), **or not**
(read_denskern=F and read_tightbox_ngwfs=F).

**To restart a cDFT**-single point run (from the latest Uq/s-potentials)
or to run cDFT-geometry optimisations/Molecular Dynamics it is necessary
to activate cdft_continuation=T. **Mind** that if, instead of
hydrogenic or numerical orbitals as cDFT-projectors (see above) one
wants to use/keep using pre-optimised projectors (stored in
.tightbox_hub_projs file) it is necessary to activate also
cdft_read_projector=T in a restart.

### Are the columns of the %block constrained_dft requesting the right targets for the given cDFT-flavour?

**MIND** that, as explained in the description of the keywords,
different columns of the %block constrained_dft are used depending on
the selected cDFT-modes (cdft_atom_charge, cdft_atom_spin,
cdft_group_charge/spin_acceptor/donor,
cdft_group_charge/spin_diff). Are you requesting the right targets in
terms of atomic-population, group-populations, atomic magnetic-moments
and group magnetic-moments?

Mind also that the cdft_group_charge/spin_acceptor/donor, cdft_group_charge/spin_diff cDFT-modes require that targeted population, magnetic-moment and differences are entered explicitly with the corresponding _TARGET keyword. If you have forgotten entering the relevant _TARGET keyword in your input, the simulation will stop and ONETEP will tell you about it.

### Have I set CDFT_GROUP_CHARGE_UP/DOWN_ONLY=T?

Remember that, for CDFT_GROUP_CHARGE_UP/DOWN_ONLY=T, only the
corresponding spin-channel will be constrained in
cdft_group_charge_acceptor/donor and cdft_group_charge_diff runs.
Accordingly, you should target populations for one-spin channel only
(**not** for the UP+DOWN channels).

### Is the sign of U_{q/s} correct for the group_charge/spin_acceptor/donor/diff run?

Remember that atoms in acceptor- and donor-group are identified by mean
of the sign of the Uq/s in the %block constrained_dft. Thus,
**acceptor-group atoms** need to be assigned negative (e-attractive)
U_{q/s} (**U:sub:`q/s`<0**), whereas **donor-group atoms**
need to be assigned positive (e-repulsive) U_{q/s}
(**U:sub:`q/s`>0**).

### Are my constraints compatible with the spin (=N_{UP}-N_{DOWN}) keyword in the input (.dat) file?

Remember that ONETEP optimises the Density Kernel keeping the number of
UP (N_{UP}) and DOWN (N_{DOWN}) electrons fixed. As a result,
the net magnetization of the system (N_{UP}-N_{DOWN}) is also
fixed. Have you introduced any incongruence between the spin=0,1,2,etc
keyword and the cDFT-ones in your input? If your targeted cDFT-solution
results in a high-value (i.e. > 0 \(\mu\)_{B}) magnetization of the
**total** system, the spin keyword should reflect it.

### What values of min/maxit_lnv, maxit_ngwf_cg and maxit_cdft_u_cg should I use?

Based on the tests run so far, and considering that the cDFT-potentials (Uq/s) are iteratively optimised at each (1:sup:st) step of the NGWFs-optimisation line-search, the following choices seem to be reasonable:

```
maxit_palser_mano : -1
kerfix : 2
maxit_pen : 0
minit_lnv : 5
maxit_lnv : 10
maxit_ngwf_cg : 60
lnv_check_trial_steps : T
lnv_threshold_orig : 1.0e-10
maxit_cdft_u_cg : 5
```

Increasing maxit_cdft_u_cg above 5 is hardly going to accelerate the convergence of the cDFT-run (the NGWFs will change at the following step of NGWFs-optimisation), decreasing minit_lnv below 5 might be risky.

### To what value should I initialise the cDFT-potentials (Uq/s)?

In the current implementation, unless cdft_guru=T, in which case the Uq/s entered in the %block constrained_dft will be used, the absolute value of the Uq/s cDFT-potentials are internally initialised to 1 eV (their original sign is, of course, maintained). For spin-excitation |Us|=1eV may be too large, and initialising the |Us| with 0.1-0.3 eV may accelerate convergence (this has been tested only on triplet excitations in benzene dimers).

### What is the difference between a cdft_atom_charge run and a cdft_group_charge_acceptor/donor one with one-atom group?

Whereas the cdft_atom_charge=T mode allows independent (i.e.
potentially different) constraining potentials to be applied to the UP
and DOWN spin-channels, for **one-atom**
cdft_group_charge_acceptor/donor=T the same Uq will be applied to
both the UP and DOWN spin-channel. Activation of
cdft_group_charge_up/down_only=T in cdft_group_acceptor/donor
modes allows to optimise Uq for only a spin-channel, leaving the other
spin-channel unconstrained.

### Have I chosen a meaningful cdft_cg_max for the cDFT-mode I wish to use?

For cDFT-runs with only one cDFT-group in the system
(cdft_group_charge/spin_acceptor/donor modes) and
group_charge/spin_diff runs, **only one** cDFT-potential (Uq/s) will
be optimised in the cDFT-loop. Accordingly, for these cases it is
recommended to perform the cDFT-optimisation via a steepest descendent
algorithm (cdft_cg_max=1).

### How do I obtain the population of the cDFT-sites for a standard DFT-run?

Performing a single-point (task=singlepoint) fixed-Uq/s (maxit_cdft_u_cg=0) cDFT-run using very small (e.g. 1.E-60) Uq/s-potentials in the %block constrained_dft and setting output_detail=VERBOSE will result in the cDFT-population of all the cDFT-sites being printed in the standard output (.out) file. To obtain atom-specific (instead of atomic_species-specific) information on the population of the cDFT-sites, it is necessary to set CDFT_PRINT_ALL_OCC=T.

**Mind.** The population of a given cDFT-site depends critically on the
projector used. Make sure you decide your cDFT-targets from the
DFT-populations obtained with the same set of projectors!

### How do I optimise self-consistently the projectors for a given geometry?

In analogy with DFT+U simulations, self-consistent optimisation of the cDFT-projectors (for a fixed geometry) is activated by setting task=HUBBARDSCF in the .dat file. It is recommended to start the task=HUBBARDSCF run from pre-optimised PAO-cDFT projectors (Z<0 in %block constrained_dft), cDFT-potentials (Uq/s), NGWFs and DKN. This is accomplished, regardless of the keywords specific to the chosen cDFT-flavour, by making sure the input file (.dat) contains:

```
task : HUBBARDSCF
hubbard_max_iter : 40 # perform 40 Hubbard-SCF iterations
read_denskern : T
read_tightbox_ngwfs : T
cdft_read_projectors : T
cdft_continuation : T
```

The percentage of the latest-optimised cDFT-NGWFs to be used as new cDFT-projectors is controlled by the hubbard_proj_mixing keyword [0 < |hubbard_proj_mixing| < 1], with hubbard_proj_mixing=1 meaning that the latest optimised-NGWFs are used entirely as new cDFT-projectors.

**Mind.** Provided cdft_read_projector=T, the cDFT-projectors in the
.tightbox_hub_projs file are used (entirely) as new projector during
the 1^{st} HUBBARDSCF iteration.

### Is self-consistent optimisation of the cDFT-projectors at the DFT-geometry a good idea?

From the tests so far, this is **not a good idea**. For tightly
constrained systems (for instance an hypothetical
N^{(+)}=N^{(-)} excitation) a cDFT task=HUBBARDSCF run at
the DFT-optimised geometry may result in very slow convergence. The
recommended procedure is to **first** optimise the cDFT-geometry using
numerical orbitals (PAO) as projectors (Z-projector <0 in %block
constrained_dft) and **then** optimise the cDFT-projectors at the
PAO-cDFT optimised geometry.

## cDFT Keywords

### Intermediate Keywords

**CDFT_ATOM_CHARGE**

Syntax: CDFT_ATOM_CHARGE [Logical]

Description: Activate atom charge-constrained-DFT mode. This mode is incompatible with any other cDFT-mode.

Default: False

Example: CDFT_ATOM_CHARGE T

**CDFT_ATOM_SPIN**

Syntax: CDFT_ATOM_SPIN [Logical]

Description: Activate atom magnetic-moment-constrained-DFT mode. This mode is incompatible with any other cDFT-mode.

Default: False

Example: CDFT_ATOM_SPIN T

**CDFT_CG_MAX**

Syntax: CDFT_CG_MAX [Real]

Description: Specifies the maximum number of constraining potential (Uq/s) conjugate gradient iterations between resets.

Default: Number of independent Uq/s for cdft_guru=F

Example: CDFT_CG_MAX 1 #Perform steepest descents optimisation

**CDFT_CG_MAX_STEP**

Syntax: CDFT_CG_MAX_STEP [Real]

Description: Maximum length of trial step for the constraining potential (Uq/s) optimisation line search.

Default: 50.0

Example: CDFT_CG_MAX_STEP 10.0

**CDFT_CG_THRESHOLD**

Syntax: CDFT_CG_THRESHOLD [Real]

Description: Specifies the convergence threshold for the RMS gradient of the constraining potentials (Uq/s).

Default: 1.0E-3

Example: CDFT_CG_THRESHOLD 0.01

**CDFT_CG_TYPE**

Syntax: CDFT_CG_TYPE [Text]

Description: Specifies the variant of the conjugate gradients algorithm used for the optimization of the constraining potentials (Uq/s), currently either NGWF_FLETCHER for Fletcher-Reeves or NGWF_POLAK for Polak-Ribiere.

Default: NGWF_FLETCHER

Example: CDFT_CG_TYPE NGWF_POLAK

**CDFT_CHARGE_ACCEPTOR_TARGET**

Syntax: CDFT_CHARGE_ACCEPTOR_TARGET [Real]

Description: Targeted acceptor-group electron population for acceptor-group charge-constrained-DFT mode [CDFT_GROUP_CHARGE_ACCEPTOR=T].

Default: 0.

Example: CDFT_CHARGE_ACCEPTOR_TARGET 17 #Constrain Nup+Ndown=17 e in subspace

**CDFT_CHARGE_DONOR_TARGET**

Syntax: CDFT_CHARGE_DONOR_TARGET [Real]

Description: Targeted donor-group electron population for donor-group charge-constrained-DFT mode [CDFT_GROUP_CHARGE_DONOR=T].

Default: 0.

Example: CDFT_CHARGE_DONOR_TARGET 17 #Constrain Nup+Ndown=17 e in subspace

**CDFT_CONTINUATION**

Syntax: CDFT_CONTINUATION [Logical]

Description: Continue a constraining potential (Uq/s) optimisation from a previous run using the .cdft file with the latest cDFT-potentials. CDFT_CONTINUATION=T allows also to perform single-point cDFT runs (MAXIT_CDFT_U_CG=0) reading atom-specific constraining potentials from .cdft file (instead of species-specific ones from the CONSTRAINED_DFT block). For cdft_continuation=T, the constraining potentials (Uq/s) are read from the .cdft file no matter the setting of cdft_guru.

Default: False

Example: CDFT_CONTINUATION T

**CDFT_GROUP_CHARGE_ACCEPTOR**

Syntax: CDFT_GROUP_CHARGE_ACCEPTOR [Logical]

Description: Activate acceptor-group charge-constrained-DFT mode. This mode is compatible with CDFT_GROUP_CHARGE_DONOR and CDFT_GROUP_SPIN_ACCEPTOR/DONOR cDFT-modes, and incompatible with CDFT_ATOM_CHARGE/SPIN and CDFT_GROUP_CHARGE/SPIN_DIFF cDFT modes.

Default: False

Example: CDFT_GROUP_CHARGE_ACCEPTOR T

**CDFT_GROUP_CHARGE_DIFF**

Syntax: CDFT_GROUP_CHARGE_DIFF [Logical]

Description: Activate group charge-difference constrained-DFT mode. This mode is compatible with CDFT_GROUP_SPIN_DIFF cDFT mode only. Thus, it is incompatible with any other CDFT_ATOM_CHARGE/SPIN and CDFT_GROUP_CHARGE/SPIN_ACCEPTOR/DONOR cDFT modes.

Default: False

Example: CDFT_GROUP_CHARGE_DIFF T

**CDFT_GROUP_CHARGE_DIFF_TARGET**

Syntax: CDFT_CHARGE_DIFF_TARGET [Real]

Description: Targeted electron population difference between acceptor and donor group for -group charge-difference constrained-DFT mode [CDFT_GROUP_CHARGE_DIFF=T].

Default: 0.

Example: CDFT_CHARGE_ACCEPTOR_TARGET 2

#Constrain [Nup+Ndown]_ACC - [Nup+Ndown]_DON to 2 e.

**CDFT_GROUP_CHARGE_DONOR**

Syntax: CDFT_GROUP_CHARGE_DONOR [Logical]

Description: Activate donor-group charge-constrained-DFT mode. This mode is compatible with CDFT_GROUP_CHARGE_ACCEPTOR and CDFT_GROUP_SPIN_ACCEPTOR/DONOR cDFT-modes, and incompatible with CDFT_ATOM_CHARGE/SPIN and CDFT_GROUP_CHARGE/SPIN_DIFF cDFT modes.

Default: False

Example: CDFT_GROUP_CHARGE_DONOR T

**CDFT_GROUP_CHARGE_DOWN_ONLY**

Syntax: CDFT_GROUP_CHARGE_DOWN_ONLY [Logical]

Description: Constrain only SPIN-DOWN channel in CDFT_GROUP_CHARGE_ACCEPTOR, CDFT_GROUP_CHARGE_DONOR and CDFT_GROUP_CHARGE_DIFF modes. To avoid disaster, make sure the specified CDFT_CHARGE_ACCEPTOR/DONOR_TARGET or CDFT_CHARGE_DIFF_TARGET keywords are consistent with the fact only one spin channel is being constrained. This functionality is NOT compatible with CDFT_GROUP_CHARGE_UP_ONLY, CDFT_ATOM_CHARGE/SPIN, and CDFT_GROUP_SPIN_ACCEPTOR/DONOR and CDFT_GROUP_SPIN_DIFF cDFT modes.

Default: False

Example: CDFT_GROUP_CHARGE_DOWN_ONLY T

**CDFT_GROUP_CHARGE_UP_ONLY**

Syntax: CDFT_GROUP_CHARGE_UP_ONLY [Logical]

Description: Constrain only SPIN-UP channel in CDFT_GROUP_CHARGE_ACCEPTOR, CDFT_GROUP_CHARGE_DONOR and CDFT_GROUP_CHARGE_DIFF modes. To avoid disaster, make sure the specified CDFT_CHARGE_ACCEPTOR/DONOR_TARGET or CDFT_CHARGE_DIFF_TARGET keywords are consistent with the fact only one spin channel is being constrained. This functionality is NOT compatible with CDFT_GROUP_CHARGE_DOWN_ONLY, CDFT_ATOM_CHARGE/SPIN, and CDFT_GROUP_SPIN_ACCEPTOR/DONOR and CDFT_GROUP_SPIN_DIFF cDFT modes.

Default: False

Example: CDFT_GROUP_CHARGE_UP_ONLY T

**CDFT_GROUP_SPIN_ACCEPTOR**Syntax: CDFT_GROUP_SPIN_ACCEPTOR
[Logical]

Description: Activate acceptor-group magnetic-moment constrained-DFT mode. This mode is compatible with CDFT_GROUP_SPIN_DONOR and CDFT_GROUP_CHARGE_ACCEPTOR/DONOR cDFT-modes, and incompatible with CDFT_ATOM_CHARGE/SPIN and CDFT_GROUP_CHARGE/SPIN_DIFF cDFT modes.

Default: False

Example: CDFT_GROUP_SPIN_ACCEPTOR T

**CDFT_GROUP_SPIN_DIFF**

Syntax: CDFT_GROUP_SPIN_DIFF [Logical]

Description: Activate group magnetic-moment-difference constrained-DFT mode. This mode is compatible with CDFT_GROUP_CHARGE_DIFF cDFT mode only. Thus, it is incompatible with any other CDFT_ATOM_CHARGE/SPIN and CDFT_GROUP_CHARGE/SPIN_ACCEPTOR/DONOR cDFT modes.

Default: False

Example: CDFT_GROUP_CHARGE_DIFF T

**CDFT_GROUP_SPIN_DIFF_TARGET**

Syntax: CDFT_SPIN_DIFF_TARGET [Real]

Description: Targeted magnetic-moment difference between acceptor and donor group for group magnetic-moment-difference constrained-DFT mode [CDFT_GROUP_SPIN_DIFF=T].

Default: 0.

Example: CDFT_CHARGE_ACCEPTOR_TARGET 2

#Constrain [Nup-Ndown]_ACC - [Nup-Ndown]_DON to 2 e.

**CDFT_GROUP_SPIN_DONOR**

Syntax: CDFT_GROUP_SPIN_DONOR [Logical]

Description: Activate donor-group magnetic-moment constrained-DFT mode. This mode is compatible with CDFT_GROUP_SPIN_ACCEPTOR and CDFT_GROUP_CHARGE_ACCEPTOR/DONOR cDFT-modes, and incompatible with CDFT_ATOM_CHARGE/SPIN and CDFT_GROUP_CHARGE/SPIN_DIFF cDFT modes.

Default: False

Example: CDFT_GROUP_SPIN_DONOR T

**CDFT_GURU**

Syntax: CDFT_GURU [Logical]

Description: Tell ONETEP you are a cDFT-expert and prevent it from initialising the active |Uq/s| to failsafe value of 1 eV overwriting the values entered in the %block constrained_dft (Uq/s).

Default: False

Example: CDFT_GURU T

**CDFT_HUBBARD**

Syntax: CDFT_HUBBARD [Logical]

Description: Activate the constrained-DFT+U functionality. It requires specifications of a positive value for the Hubbard correction (Uh) in the CONSTRAINED_DFT Block.

Default: False

Example: CDFT_HUBBARD T

**CDFT_MAX_GRAD**

Syntax: CDFT_MAX_GRAD [Real]

Description: Specifies the convergence threshold for the maximum value of the constraining-potential (Uq/s) gradient at any cDFT-site

Default: 1.0E-3

Example: CDFT_MAX_GRAD 0.01

**CDFT_MULTI_PROJ**

Syntax: CDFT_MULTI_PROJ [Logical]

Description: Activate the “as many cDFT-projectors as NGWFs” cDFT-mode. In this mode, the number of cDFT-projectors for a given cDFT-atom equals the number of NWGFs for that atom as specified in the %block species. Both the cDFT-projectors and the NGWFs are localised within spheres of the same radius. When activated, this mode overwrites the L-projectors and Z-projectors settings in %block constrained_dft, and the cDFT-projectors are built according to the settings in %block species_atomic_set for that atom=cDFT-site.

Default: False

Example: CDFT_MULTI_PROJ T

**CDFT_PRINT_ALL_OCC**

Syntax: CDFT_PRINT_ALL_OCC [Logical]

Description: Print detailed information of occupancies for al the cDFT-sites, for OUTPUT_DETAIL = VERBOSE.

Default: False

Example: CDFT_PRINT_ALL_OCC T

**CDFT_READ_PROJ**

Syntax: CDFT_READ_PROJ [Logical]

Description: Read cDFT-projectors from .tightbox_hub_proj file. Activation of this keyword overwrites any Z-projector setting in %block constrained_dft. It also makes not necessary to set hubbard_proj_mixing<0 to have task=HUBBARDSCF runs with projectors read in from file.

Default: False

Example: CDFT_READ_PROJ T

**CDFT_SPIN_ACCEPTOR_TARGET**

Syntax: CDFT_SPIN_ACCEPTOR_TARGET [Real]

Description: Targeted group magnetic-moment for acceptor-group magnetic-moment constrained-DFT mode [CDFT_GROUP_SPIN_ACCEPTOR=T].

Default: 0.

Example: CDFT_SPIN_ACCEPTOR_TARGET -2 #Constrain Nup-Ndown=-2 in subspace

**CDFT_SPIN_DONOR_TARGET**

Syntax: CDFT_SPIN_DONOR_TARGET [Real]

Description: Targeted group magnetic-moment for donor-group magnetic-moment constrained-DFT mode [CDFT_GROUP_SPIN_DONOR=T].

Default: 0.

Example: CDFT_SPIN_DONOR_TARGET -2 #Constrain Nup-Ndown=-2 in subspace

**CDFT_TRIAL_LENGTH**

Syntax: CDFT_TRIAl_LENGTH [Real]

Description: Specifies initial trial length for first step of constraining-potential (Uq/s) conjugate gradients optimisation.

Default: 0.1

Example: CDFT_TRIAL_LENGTH 1.0

**CI_CDFT**

Syntax: CI_CDFT [Logical]

Description: Perform a Configuration Interaction calculation based on constrained-DFT configurations.

Default: False

Example: CI_CDFT T

**CI_CDFT_NUM_CONF**

Syntax: CDFT_MAX_GRAD [Integer]

Description: Specifies the number of constrained-DFT configuration available for a CI_CDFT=T simulation

Default: 0

Example: CI_CDFT_NUM_CONF 4

**CONSTRAINED_DFT**

Syntax: CONSTRAINED_DFT [Block]

Syntax: %BLOCK CONSTRAINED_DFT

S1 L1 Z1 Uh1 Uq1(UP) Uq1(DOWN) Us1 N1(UP) N1(DOWN) [N1(UP)-N1(DOWN)] S2 L2 Z2 Uh2 Uq2(UP) Uq2(DOWN) Us2 N2(UP) N2(DOWN) [N2(UP)-N2(DOWN)] … . .

… . .

SM LM ZM UhM UqM(UP) UqM(DOWN) UsM NM(UP) NM(DOWN) [NM(UP)-NM(DOWN)]

%ENDBLOCK CONSTRAINED_DFT

Description: Manages constrained-DFT simulations. Provided cdft_multi_proj=F, for species S and subspace of angular momentum channel L (with principal quantum number n=L+1) we apply charge spin-specific [Uq(UP), Uq(DOWN)] or magnetic-moment-specific (Us) constraining potentials (eV). For cdft_atom_charge=T, N(UP) and N(DOWN) indicate the targeted e-population for spin-channel UP and DOWN, respectively. For cdft_atom_spin=T, [N1(UP)-N1(DOWN)] indicates the targeted e-population difference (i.e. local magnetic moment). Uh indicates the optional Hubbard parameter (U, eV) to be applied for cdft_hubbard=T. An effective nuclear charge Z defines the hydrogenic orbitals spanning the subspace unless a negative value is given, e.g., Z=-10, in which case the NGWFs initial guess orbitals (numerical atomic orbitals) are used. Depending on the activated cDFT-mode, different columns of the block are used. These are:

S, L, Z, (Uh), Uq(UP), Uq(DOWN), N(UP), N(DOWN) for cdft_atom_charge=T

S, L, Z, (Uh), Us, [N(UP)-N(DOWN)] for cdft_atom_spin=T

S, L, Z, (Uh), Uq(UP), Uq(DOWN) for cdft_group_charge_acceptor=T, cdft_group_charge_donor=T, or cdft_group_charge_diff=T. In this case, Uq(UP) must be equal to Uq(DOWN). Acceptor and donor atoms are differentiated by mean of negative [Uq(UP/DOWN)<0] and positive [Uq(UP/DOWN)>0] constraining-potentials, respectively. Setting Uq=0 in the %block constrained_dft will result in the given cDFT-atom being excluded from the list of the atoms in a given cdft_group_charge_donor/acceptor/diff group.

S, L, Z, (Uh), and Us for cdft_group_spin_acceptor=T, cdft_group_spin_donor=T, or cdft_group_spin_diff=T. In this case, Acceptor and donor atoms are differentiated by mean of negative (Us<0) and positive (Us>0) constraining-potentials, respectively. Setting Us=0 in the %block constrained_dft will result in the given cDFT-atom being excluded from the list of the atoms in a given cdft_group_spin_donor/acceptor/diff group.

cdft_group_spin_acceptor=T, cdft_group_spin_donor=T, cdft_group_charge_acceptor=T and cdft_group_charge_donor=T are all compatible one with another. Charge- and magnetic-moment acceptor- and donor-groups may or may not be the same group. Thus, besides simultaneously constraining the charge and magnetic-moment on a given group, it is also possible (by setting the appropriate sign of Uq and Us in the %block constrained_dft) to create, within the same input and system, a charge_acceptor group-A, a charge_donor group-B, a spin_acceptor group-C and a spin_donor group-C. Similar considerations apply also for simultaneous activation of group_charge_diff and group_spin_diff cDFT-modes. In sum,

Activation of cdft_group_charge_up(down)_only=T for cdft_group_charge_acceptor/donor or cdft_group_charge_diff modes leads to optimisation of the Uq potentials only for the selected spin-channel i.e. Uq(UP) only for cdft_group_charge_up_only=T, and Uq(DOWN) only for cdft_group_charge_down_only=T, leaving the other spin channel unconstrained.

For cdft_multi_proj=T the L-projector and Z-projector columns in the %block constrained_dft are read but NOT used. The cDFT-projectors are set on the basis of the %block species_atomic_set and taken as the NGWFs initial guess (numerical atomic orbital). This leads to as many cDFT-projectors as NGWFs for the cDFT-atom being used. In the current implementation, the same Uq/s is applied to all the projectors of a given cDFT-atom regardless of their principal quantum number and angular momentum.

For all the cDFT-modes, unless maxit_cdft_u_cg=0, and depending of the specific cDFT-mode, the constraining potentials (Uq,Us) will be automatically optimised. Note that, unless cdft_guru=T, the constraining potentials (Uq/s) will be initialised to 1 eV. Thus, to perform fixed-Uq/s cDFT-runs or to initialise Uq/s with values different from 1 eV (useful for low-energy spin-excitation), it is necessary to set cdft_guru=T.

The CONSTRAINED_DFT Block is incompatible with the HUBBARD Block. To perform a constrained-DFT+U simulation with Hubbard (Uh) correction applied to the subspace in addition to the constraining potentials (Uq/s) it is necessary to set cdft_hubbard=T. For cdft_hubbard=F (which is the default), the Hubbard correction will NOT be applied to the subspace.

Example: %BLOCK CONSTRAINED_DFT

# L Z Uh Uq(UP) Uq(DOWN) Us N(UP) N1(DOWN) [N1(UP)-N1(DOWN)]

N1 1 -5. 0.0 11.0 11.0 0.0 2.3 1.3 0.

N2 1 -5. 0.0 -26.0 -26.0 0.0 2.7 2.7 0.

%ENDBLOCK CONSTRAINED_DFT

**MAXIT_CDFT_U_CG**

Syntax: MAXIT_CDFT_U_CG [Integer]

Description: Specifies the maximum number of iterations for the constraining potentials (Uq/s) conjugate gradients optimisation.

Default: 60

Example: MAXIT_CDFT_U_CG 5

**HUBBARD_TENSOR_CORR**

Syntax: HUBBARD_TENSOR_CORR [Integer]

Description:

1: Correct tensorially for the slight nonorthogonality between DFT+U or constrained DFT (cDFT) projectors of numerical pseudoatomic orbital form, individually on each atom, which arise due to finite psinc sampling. See details see Phys. Rev. B 83, 245124 (2011).

2: Use the full simulation-cell overlap matrix of the initial numerical pseudoatomic orbitals (whether or not they are selected as projectors) to form the nonorthogonality correction, in the vein of Mulliken analysis. Experimental, non-Hermitian at present, and not recommended.

3: Do not correct for the slight nonorthogonality between DFT+U or constrained DFT (cDFT) projectors on a given atom. This is standard in many codes, and currently necessary to choose when using USP/PAW.

4: This is a reasonable, but not necessary choice, when using cDFT with constraints based on atom group populations. The non-negligible nonorthogonality between projectors on different atoms in the group is accounted for tensorially. This also activates multi-site Pulay force terms in constrained DFT (cDFT) that account for varying inter-atom nonorthogonality. For details see Phys. Rev. B 97, 205120 (2018).

5: This is also an arguably reasonable, but not necessary choice, when using cDFT with constraints based on, e.g. the difference of atom or atom group populations, that is source-drain cDFT. The non-negligible nonorthogonality between projectors on different atoms in a group is accounted for tensorially, and also the possible nonorthogonality between the source and drain atoms or atom-groups. For an application see Phys. Rev. B 93, 165102 (2016). This also activates (in principle) multi-site Pulay force terms in constrained DFT (cDFT) that account for varying inter-subspace nonorthogonality. This also activates multi-site Pulay force terms in constrained DFT (cDFT) that account for varying inter-atom nonorthogonality. This also activates multi-site Pulay force terms in constrained DFT (cDFT) that account for varying inter-atom nonorthogonality. For details see Phys. Rev. B 97, 205120 (2018).

The HUBBARD_TENSOR_CORR functionality is not activated in the rare case that analytical hydrogenic projectors are instead of the default numerical pseudoatomic ones.

Default: 1

Example: HUBBARD_TENSOR_CORR 4