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
OSCDFT 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, 47814789
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 ... <pathtoqesource>
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 <inputfile> 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

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 OSCDFT multipliers optimizations.
 0 :
OSCDFT multipliers optimization is a microiteration inside
the charge density iteration. The convergence threshold of the
OSCDFT 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 OSCDFT multipliers iteration. A final
convergence threshold of final_conv_thr can also be set
to prevent the charge density iteration from converging when
the OSCDFT convergence test is larger than final_conv_thr.
 1 :
Charge density optimization is a microiteration inside the
OSCDFT multiplier optimization. The convergence threshold of
the OSCDFT 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 OSCDFT 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.

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 OSCDFT convergence test is
larger than final_conv_thr. 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.

has_min_multiplier 
LOGICAL 
Default: 
.FALSE.

If .TRUE., sets the minimum value of the OSCDFT multipliers
to min_multiplier.

has_max_multiplier 
LOGICAL 
Default: 
.FALSE.

If .TRUE., sets the maximum value of the OSCDFT multipliers
to max_multiplier.

miniter 
INTEGER 
Default: 
0

Minimum OSCDFT iterations.

maxiter 
INTEGER 
Default: 
0

Maximum OSCDFT 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 OSCDFT constraint to apply.
Also allows printing of occupation matrix without applying OSCDFT constraints.
Syntax:
TARGET_OCCUPATION_NUMBERS

Description of items:
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 OSCDFT constraint is applied.
See swapping_technique.
Example:
Apply a constraint to the 5th spinup 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 spinup 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(number1)
Applies constraint on orbital_indexth 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(number1)
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 OSCDFT 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

Description of items:


ADDITIONAL NOTES
1. The default values are the recommeded options for convergence_type
and array_convergence_func
2. When using diagonalization='davidson', OSCDFT 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 spinup occupation number of the
3d orbital of atom 5 to a target of 0.9075202
Row 2: Print the occupation numbers of the spindown 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 spinup occupation numbers of the
3d orbital of atom 1
Row 2: Apply a constraint on the 5th spindown occupation number of the
3d orbital of atom 1 to a target of 0.9369434
Row 3: Print the occupation numbers of the spinup occupation numbers of the
3d orbital of atom 2
Row 4: Apply a constraint on the 5th spindown 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 14: Apply a constraint on the sum of the 2nd, 3rd, 4th, and 5th spinup
occupation number of the 3d orbital of atom 9 to a target of 4.0135939
Row 5 : Print the occupation numbers of the spindown occupation numbers of the
3d orbital of atom 9
Row 6 : Print the occupation numbers of the spinup occupation numbers of the
3d orbital of atom 16
Row 7 : Print the occupation numbers of the spindown 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 spinup occupation numbers of the
3d orbital of atom 9
Row 2 : Print the occupation numbers of the spindown occupation numbers of the
3d orbital of atom 9
Row 36: Apply a constraint on the sum of the 2nd, 3rd, 4th, and 5th spinup
occupation number of the 3d orbital of atom 16 to a target of 4.0135939
Row 7 : Print the occupation numbers of the spindown 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 14: Apply a constraint on the sum of the 2nd, 3rd, 4th, and 5th spinup
occupation number of the 3d orbital of atom 39 to a target of 4.0135939
Row 57: Apply a constraint on the sum of the 3rd, 4th, and 5th spindown
occupation number of the 3d orbital of atom 39 to a target of 3.0020503
