Input File Description

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

TABLE OF CONTENTS

ABOUT

COMPILATION

USAGE

INTRODUCTION

&OSCDFT

oscdft_type | 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 | debug_print | orthogonalize_swfc | normalize_swfc | constraint_strength | constraint_conv_thr | constraint_maxstep | constraint_mixing_beta | constraint_diag

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

oscdft_type INTEGER
Default: 1 
1 : C. Ku, P. H. L. Sit, J. Chem. Theory Comput. 15, 4781 (2019).
2 : L. Ponet, E. Di Lucente, N. Marzari, npj Comput. Mater. 10, 151 (2024).

Note: For oscdft_type=2, only the keyword "occupation" and the keywords
      constraint_* can be used (see below).
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)
debug_print 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.
constraint_strength DOUBLE
Default: 1.0D0 
Multiplicative factor in front of the constraint term in
the potential (and energy).
constraint_conv_thr DOUBLE
Default: 5.0D-3 
Convergence threshold for the mean absolute error (MAE) computed
by averaging the absolute difference between the current and
target occupation matrices. When this threshold is reached,
the constarined is released.
constraint_maxstep INTEGER
Default: 200 
When the number of SCF iterations is larger than this number,
the constraint is not updated.
constraint_mixing_beta DOUBLE
Default: 4.0D-1 
The multiplicative factor in front of the constraint term.
constraint_diag LOGICAL
Default: .FALSE. 
If .TRUE., TARGET_OCCUPATION_NUMBERS must contain the
eigenvalues of the occupation matrix instead of the full
(generally) nondiagonal target occupation matrix.
The code will read these eigenvalues and reconstruct the
nondiagonal target occupation matrix that will be used
for constrained calculations. This should behave similarly
to the starting_ns_eigenvalue keyword, but better since the
constraint is applied until the constraint_conv_thr is
reached (contrary to a simple reinitialization of starting
occupations that is done using starting_ns_eigenvalue).

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 ! This card can be used only with oscdft_type = 1.

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.)

5. To use oscdft_type = 2, see the last two examples below as well as
   PW/examples/example15.

ADDITIONAL EXAMPLES FOR TARGET_OCCUPATION_NUMBERS 

Input File:
&OSCDFT
  oscdft_type=1,
  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
  oscdft_type=1,
  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
  oscdft_type=1,
  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
  oscdft_type=1,
  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
  oscdft_type=1,
  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

Input File:
&OSCDFT
  oscdft_type=2,
  n_oscdft=20,
  constraint_diag = .true.
  ...
/
TARGET_OCCUPATION_NUMBERS
  1 1 1 0.990
  1 1 2 0.990
  1 1 3 0.995
  1 1 4 0.997
  1 1 5 0.997
  1 2 1 0.055
  1 2 2 0.055
  1 2 3 0.171
  1 2 4 0.171
  1 2 5 0.975
  ...
Explanations:
  Column 1: the atomic index (according to ATOMIC_POSITIONS)
  Column 2: the spin index (1 for up, and 2 for down)
  Column 3: the index of the eigenvalue
            (e.g. from 1 to 5 for d electrons)
  Column 4: the target eignvalue of the occupation matrix
  For more details, see PW/examples/example15/run1 and README.

Input File:
&OSCDFT
  oscdft_type=2,
  n_oscdft=100,
  constraint_diag = .false.
  ...
/
TARGET_OCCUPATION_NUMBERS
  1 1 1 1  1.000
  1 1 1 2  0.000
  1 1 1 3  0.000
  1 1 1 4  0.000
  1 1 1 5  0.000
  1 1 2 1  0.000
  1 1 2 2  1.000
  1 1 2 3  0.000
  1 1 2 4  0.000
  1 1 2 5  0.000
  ...
Explanations:
  Column 1: the atomic index (according to ATOMIC_POSITIONS)
  Column 2: the spin index (1 for up, and 2 for down)
  Columns 3 and 4: the indices of the magnetic quantum numbers
                   (e.g. from 1 to 5 for d electrons)
  Column 5: the target occupation value
  For more details, see PW/examples/example15/run2 and README.
This file has been created by helpdoc utility on Wed Sep 03 14:22:45 CEST 2025.