Input File Description

Program: pw.x with OS-CDFT / PWscf / Quantum ESPRESSO (version: 7.2)

TABLE OF CONTENTS

ABOUT

COMPILATION

USAGE

INTRODUCTION

&OSCDFT

n_oscdft | get_ground_state_first | warm_up_niter | convergence_type | iteration_type | optimization_method | array_convergence_func | max_conv_thr | min_conv_thr | final_conv_thr | conv_thr_multiplier | print_occupation_matrix | print_occupation_eigenvectors | min_gamma_n | has_min_multiplier | min_multiplier | has_max_multiplier | max_multiplier | miniter | maxiter | swapping_technique | print_debug | orthogonalize_swfc | normalize_swfc

TARGET_OCCUPATION_NUMBERS

applied | spin | orbital_desc | constr_idx | target | start_mul | start_index

GAMMA_VAL

gamma_val

ADDITIONAL NOTES

ADDITIONAL EXAMPLES FOR TARGET_OCCUPATION_NUMBERS

ABOUT 

OS-CDFT allows control of the oxidation state of a transition metal element by
constraining the occupation numbers.
For information on the method, see http://doi.org/10.1021/acs.jctc.9b00281
C. Ku, P. H. L. Sit, J. Chem. Theory Comput. 2019, 15, 9, 4781-4789

COMPILATION 

Using autoconf:
    ./configure ...
    nano make.inc # append -D__OSCDFT into DFLAGS = ... (or MANUAL_DFLAGS = ...)
    make pw pp ...

Using cmake:
    cmake -DQE_ENABLE_OSCDFT=ON ... <path-to-qe-source>
    make pw pp ...

USAGE 

Requires oscdft.in file, described below, in the same directory as where the pw.x command is ran. 
    pw.x -inp <input-file> -oscdft ...

INTRODUCTION

Input data format: { } = optional, [ ] = it depends, | = or

Structure of the oscdft.in file:
===============================================================================

    &OSCDFT
      ...
    /

    TARGET_OCCUPATION_NUMBERS
      see TARGET_OCCUPATION_NUMBERS

    [ GAMMA_VAL
      gamma_val(1)
      ...
      gamma_val(n_oscdft) ]

Namelist: &OSCDFT

n_oscdft INTEGER
Status: REQUIRED 
Number of entries of the TARGET_OCCUPATION_NUMBERS card.
get_ground_state_first LOGICAL
Default: .FALSE. 
If .TRUE., perform an scf calculation to convergence before applying constraint.
warm_up_niter INTEGER
Default: 0 
Runs warm_up_niter scf iterations first before applying constraint.
If get_ground_state_first is .TRUE. then scf convergence is achieved first
before running warm_up_niter scf iterations without applying the constraints.
convergence_type CHARACTER
Default: 'gradient' 
The variable that is checked for convergence with the convergence threshold.
'multipliers' :
Converges when the change in multipliers between iterations
is less than the threshold.
'gradient' :
Converges when (occupation number - target occupation number)
is less than the threshold.
'energy' :
Converges when the change in total energy between iterations
is less than the threshold.
'always_false' :
Never converges (for debugging).
'always_true' :
Always converges (for debugging).
iteration_type INTEGER
Status: REQUIRED 
Order of charge density and OS-CDFT multipliers optimizations.
0 :
OS-CDFT multipliers optimization is a micro-iteration inside
the charge density iteration. The convergence threshold of the
OS-CDFT multipliers iterations can be set to start loose at
max_conv_thr and gradually tighten to a minimum of min_conv_thr
by multiplying the threshold with conv_thr_multiplier after
every successful OS-CDFT multipliers iteration. A final
convergence threshold of final_conv_thr can also be set
to prevent the charge density iteration from converging when
the OS-CDFT convergence test is larger than final_conv_thr.
1 :
Charge density optimization is a micro-iteration inside the
OS-CDFT multiplier optimization. The convergence threshold of
the OS-CDFT multipliers is set by max_conv_thr.
min_conv_thr, conv_thr_multiplier, and final_conv_thr are
ignored.
optimization_method CHARACTER
Default: 'gradient descent' 
Method to update the OS-CDFT multipliers.
'gradient descent' :
multipliers -= min_gamma_n
               * (occupation number - target occupation number)
'gradient descent2' :
multipliers -= gamma_val * min_gamma_n
               * (occupation number - target occupation number)
array_convergence_func CHARACTER
Default: 'maxval' 
Specify the method of multiple values to scalar for convergence test
when convergence_type is either 'gradient' or 'multipliers'.
'maxval' :
Takes the maximum of the convergence_type before comparing with
threshold.
'norm' :
Takes the root sum squared of the convergence_type before
comparing with threshold.
'rms' :
Takes the root mean squared of the convergence_type before
comparing with threshold.
max_conv_thr DOUBLE
Default: 1.D-1 
If iteration_type is 0, this is the starting convergence threshold.
If iteration_type is 1, this is the convergence threshold.
See iteration_type for more explanations.
min_conv_thr DOUBLE
Default: 1.D-3 
If iteration_type is 0, this is the minimum convergence threshold.
If iteration_type is 1, this is ignored.
See iteration_type for more explanations.
final_conv_thr DOUBLE
Default: -1.D0 
If iteration_type is 0 and final_conv_thr > 0.D0, the charge density
convergence is prevented when the OS-CDFT convergence test is
larger than final_conv_thr. Otherwise, this is ignored.
conv_thr_multiplier DOUBLE
Default: 0.5D0 
If iteration_type is 0, see iteration_type for explanations.
Otherwise, this is ignored.
print_occupation_matrix LOGICAL
Default: .FALSE. 
If .TRUE., prints the occupation matrices.
print_occupation_eigenvectors LOGICAL
Default: .FALSE. 
If .TRUE., prints the occupation eigenvectors.
min_gamma_n DOUBLE
Default: 1.D0 
Learning rate of optimizations. See optimization_method.
has_min_multiplier LOGICAL
Default: .FALSE. 
If .TRUE., sets the minimum value of the OS-CDFT multipliers
to min_multiplier.
min_multiplier DOUBLE
Status: REQUIRED if has_min_multiplier is .TRUE. 
Minimum value of the OS-CDFT multipliers.
Enabled using has_min_multiplier
has_max_multiplier LOGICAL
Default: .FALSE. 
If .TRUE., sets the maximum value of the OS-CDFT multipliers
to max_multiplier.
max_multiplier DOUBLE
Status: REQUIRED if has_max_multiplier is .TRUE. 
Maximum value of the OS-CDFT multipliers.
Enabled using has_max_multiplier
miniter INTEGER
Default: 0 
Minimum OS-CDFT iterations.
maxiter INTEGER
Default: 0 
Maximum OS-CDFT iterations.
swapping_technique CHARACTER
Default: 'none' 
See https://doi.org/10.1021/acs.jctc.9b00281
'none' :
No swapping technique.
Always chooses the occupation number in ascending order.
'permute' :
Chooses the occupation number associated with the
occupation eigenvector that is most similar compared
to previous iteration (using dot product)
print_debug LOGICAL
Default: .FALSE. 
If .TRUE., prints additional debug informations.
orthogonalize_swfc LOGICAL
Default: .FALSE. 
If .TRUE., uses Lowdin orthogonalized atomic orbitals.
normalize_swfc LOGICAL
Default: .FALSE. 
If .TRUE., uses Lowdin normalized atomic orbitals.
Atomic orbitals are not orthogonalized in this case.

Card: TARGET_OCCUPATION_NUMBERS

Specifies the OS-CDFT constraint to apply. Also allows printing of occupation matrix without applying OS-CDFT constraints.

Syntax:

TARGET_OCCUPATION_NUMBERS
 applied(1)   spin(1)   orbital_desc(1)  [  constr_idx(1)   target(1)   start_mul(1)  {  start_index(1)  } ]
 applied(2)   spin(2)   orbital_desc(2)  [  constr_idx(2)   target(2)   start_mul(2)  {  start_index(2)  } ]
 . . .
 applied(n_oscdft)   spin(n_oscdft)   orbital_desc(n_oscdft)  [  constr_idx(n_oscdft)   target(n_oscdft)   start_mul(n_oscdft)  {  start_index(n_oscdft)  } ]

Description of items:

applied CHARACTER
Status: REQUIRED
T :
Applies a constraint.

spin, orbital_desc, constr_idx, target,
and start_mul are requried.
spin is optional.
F :
Just prints the occupation number.

Only spin and orbital_desc are requried.
Others are ignored.
spin CHARACTER
Status: REQUIRED
1, UP :
Spin up channel
2, DOWN :
Spin down channel
orbital_desc CHARACTER
Status: REQUIRED 
Orbitals included in the occupation number

Syntax of the orbital descriptor:
     atom_index(manifold...)... 

Where:
atom_index = atom index in the order of ATOMIC_POSITIONS
manifold   = principal and azimuthal quantum numbers
                (can specify more than one manifolds)
                (eg. 3d, 2s2p)

Examples:
5(3d)   describes a 5x5 occupation matrix which includes:
- 3d orbital of atom 5.

3(2s2p) describes a 4x4 occupation matrix which includes:
- 2s orbital of atom 3.
- 2p orbital of atom 3.

Additional notes: See ADDITIONAL NOTES below.
constr_idx VARIOUS
Status: REQUIRED if applied(I) == T 
Specifies how the constraint is applied:

To apply a constraint on an occupation number:
  Write the index of the occupation numbers, sorted in ascending order,
  where the OS-CDFT constraint is applied.
  See swapping_technique.

  Example:
  Apply a constraint to the 5th spin-up occupation number of
  the 3d orbital of atom 2 to a target of 0.9
  &OSCDFT
    n_oscdft=1
    ...
  /
  TARGET_OCCUPATION_NUMBERS
    T UP 2(3d) 5 0.9 0.0

To apply a constraint on the trace of the occupation matrix:
  Write trace for this variable.
  swapping_technique is ignored when this is used.

  Example:
  Apply a constraint to the trace of the spin-up occupation number of
  the 3d orbital of atom 2 to a target of 3.2
  &OSCDFT
    n_oscdft=1
    ...
  /
  TARGET_OCCUPATION_NUMBERS
    T UP 2(3d) trace 3.2 0.0

To apply a cosntraint on the sum of occupation numbers:
  sum number orbital_index row_index(1) ... row_index(number-1)
  Applies constraint on orbital_index-th occupation number
  of the occupation matrix.
  However, the occupation number inputted to the optimization subroutines
  is the sum of this orbital index along with the occupation number of
  row_index(1) ... row_index(number-1)
  swapping_technique is ignored when this is used.

  Example:
  Apply a constraint to the sum of the 3rd, 4th, and 5th
  occupation numbers of the 3d orbital of atom 2 to a target of 2.8
  &OSCDFT
    n_oscdft=3
    ...
  /
  TARGET_OCCUPATION_NUMBERS
    T UP 2(3d) sum 3 3 2 3 2.8 0.0
    T UP 2(3d) sum 3 4 1 3 2.8 0.0
    T UP 2(3d) sum 3 5 1 2 2.8 0.0

  Explanation:
  Row 1: Applies constraint to 3rd occupation number. However, the multiplier is
         optimized until the sum of the 3rd occupation number, along with the
         occupation numbers of row 2 and row 3 of the TARGET_OCCUPATION_NUMBERS
         card equals 2.8
  Row 2: Applies constraint to 4th occupation number. However, the multiplier is
         optimized until the sum of the 4th occupation number, along with the
         occupation numbers of row 1 and row 3 of the TARGET_OCCUPATION_NUMBERS
         card equals 2.8
  Row 3: Applies constraint to 5th occupation number. However, the multiplier is
         optimized until the sum of the 5th occupation number, along with the
         occupation numbers of row 1 and row 2 of the TARGET_OCCUPATION_NUMBERS
         card equals 2.8
target DOUBLE
Status: REQUIRED if applied(I) == T 
The target occupation number for the constraint.
start_mul DOUBLE
Status: REQUIRED if applied(I) == T 
Starting value of the multiplier.
For normal operations, set this to 0.D0.
start_index INTEGER
Default: 1 
If iteration_type is 0, delays the application of this
row of OS-CDFT constraint until the rest of the constraint is
converged. Otherwise, this is ignored.

Example (n_oscdft = 4):
TARGET_OCCUPATION_NUMBERS
  T UP 3(3d) 5 0.9 0.0 1
  T UP 4(3d) 5 0.9 0.0 1
  T UP 5(3d) 5 0.9 0.0 2
  T UP 6(3d) 5 0.9 0.0 3
The constraints on atom 3 and 4 are applied first until convergence.
Then, the constraints on atom 3, 4, and 5 are applied until convergence.
Finally, the constraints on atom 3, 4, 5, and 6 are applied until convergence.

Card: GAMMA_VAL

Conditional card, used only if optimization_method == 'gradient descent2', ignored otherwise !

Syntax:

GAMMA_VAL
 gamma_val(1) 
 gamma_val(2) 
 . . .
 gamma_val(n_oscdft) 

Description of items:

gamma_val DOUBLE
Status: REQUIRED if optimization_method == 'gradient descent2' 
This sets the learning rate for each multipliers,
allowing different learning rate for each multipliers.
See optimization_method for more details.

ADDITIONAL NOTES 

1. The default values are the recommeded options for convergence_type
   and array_convergence_func

2. When using diagonalization='davidson', OS-CDFT may fail with
   'S matrix not positive definite' as an error. When that occurs,
   use diagonalization='cg'.

3. Use iteration_type=0 for most cases. iteration_type=0 is faster,
   due to the ability to gradually tighten the convergence threshold.
   However, iteration_type=1 is more robust.

4. orbital_desc in the TARGET_OCCUPATION_NUMBERS card:
   While one orbital_desc can be composed of multiple atoms,
   the occupation number may not be accurate.
   For example, 5(3d)6(2s2p) will be accepted, however the
   atomic wavefunction of atom 5 and atom 6 may not be orthogonal.
   (unless orthogonalize_swfc is .true.)

ADDITIONAL EXAMPLES FOR TARGET_OCCUPATION_NUMBERS 

Input File:
&OSCDFT
  n_oscdft=2
  ...
/
TARGET_OCCUPATION_NUMBERS
  T UP   5(3d) 5 0.9075202 0.0
  F DOWN 5(3d)
Explanations:
Row 1: Apply a constraint on the 5th spin-up occupation number of the
       3d orbital of atom 5 to a target of 0.9075202
Row 2: Print the occupation numbers of the spin-down occupation numbers
       of the 3d orbital of atom 5


Input File:
&OSCDFT
  n_oscdft=2
  ...
/
TARGET_OCCUPATION_NUMBERS
  F UP   1(3d)
  T DOWN 1(3d) 5 0.9369434 0.0
  F UP   2(3d)
  T DOWN 2(3d) 5 0.261727 0.0
Explanations:
Row 1: Print the occupation numbers of the spin-up occupation numbers of the
       3d orbital of atom 1
Row 2: Apply a constraint on the 5th spin-down occupation number of the
       3d orbital of atom 1 to a target of 0.9369434
Row 3: Print the occupation numbers of the spin-up occupation numbers of the
       3d orbital of atom 2
Row 4: Apply a constraint on the 5th spin-down occupation number of the
       3d orbital of atom 2 to a target of 0.261727


Input File:
&OSCDFT
  n_oscdft=7
  ...
/
TARGET_OCCUPATION_NUMBERS
  T UP    9(3d) sum 4 2 2 3 4 4.0135939 0.0
  T UP    9(3d) sum 4 3 1 3 4 4.0135939 0.0
  T UP    9(3d) sum 4 4 1 2 4 4.0135939 0.0
  T UP    9(3d) sum 4 5 1 2 3 4.0135939 0.0
  F DOWN  9(3d)
  F UP   16(3d)
  F DOWN 16(3d)
Explanations:
Row 1-4: Apply a constraint on the sum of the 2nd, 3rd, 4th, and 5th spin-up
         occupation number of the 3d orbital of atom 9 to a target of 4.0135939
Row 5  : Print the occupation numbers of the spin-down occupation numbers of the
         3d orbital of atom 9
Row 6  : Print the occupation numbers of the spin-up occupation numbers of the
         3d orbital of atom 16
Row 7  : Print the occupation numbers of the spin-down occupation numbers of the
         3d orbital of atom 16


Input File:
&OSCDFT
  n_oscdft=7
  ...
/
TARGET_OCCUPATION_NUMBERS
  F UP    9(3d)
  F DOWN  9(3d)
  T UP   16(3d) sum 4 2 4 5 6 4.0135939 0.0
  T UP   16(3d) sum 4 3 3 5 6 4.0135939 0.0
  T UP   16(3d) sum 4 4 3 4 6 4.0135939 0.0
  T UP   16(3d) sum 4 5 3 4 5 4.0135939 0.0
  F DOWN 16(3d)
Explanations:
Row 1  : Print the occupation numbers of the spin-up occupation numbers of the
         3d orbital of atom 9
Row 2  : Print the occupation numbers of the spin-down occupation numbers of the
         3d orbital of atom 9
Row 3-6: Apply a constraint on the sum of the 2nd, 3rd, 4th, and 5th spin-up
         occupation number of the 3d orbital of atom 16 to a target of 4.0135939
Row 7  : Print the occupation numbers of the spin-down occupation numbers of the
         3d orbital of atom 16


Input File:
&OSCDFT
  n_oscdft=7
  ...
/
TARGET_OCCUPATION_NUMBERS
  T UP   39(3d) sum 4 2 2 3 4 4.0135939 0.0
  T UP   39(3d) sum 4 3 1 3 4 4.0135939 0.0
  T UP   39(3d) sum 4 4 1 2 4 4.0135939 0.0
  T UP   39(3d) sum 4 5 1 2 3 4.0135939 0.0
  T DOWN 39(3d) sum 3 3 6 7   3.0020503 0.0
  T DOWN 39(3d) sum 3 4 5 7   3.0020503 0.0
  T DOWN 39(3d) sum 3 5 5 6   3.0020503 0.0
Explanations:
Row 1-4: Apply a constraint on the sum of the 2nd, 3rd, 4th, and 5th spin-up
         occupation number of the 3d orbital of atom 39 to a target of 4.0135939
Row 5-7: Apply a constraint on the sum of the 3rd, 4th, and 5th spin-down
         occupation number of the 3d orbital of atom 39 to a target of 3.0020503
This file has been created by helpdoc utility on Thu Mar 30 12:14:09 CEST 2023.