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

[Back to Top]

get_ground_state_first | LOGICAL
Default: | .FALSE.

>     If .TRUE., perform an scf calculation to convergence before applying constraint.

[Back to Top]

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.

[Back to Top]

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

[Back to Top]

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.

[Back to Top]

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)

[Back to Top]

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.

[Back to Top]

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.

[Back to Top]

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.

[Back to Top]

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.

[Back to Top]

conv_thr_multiplier | DOUBLE
Default: | 0.5D0

>     If iteration_type is 0, see iteration_type for explanations.
>     Otherwise, this is ignored.

[Back to Top]

print_occupation_matrix | LOGICAL
Default: | .FALSE.

>     If .TRUE., prints the occupation matrices.

[Back to Top]

print_occupation_eigenvectors | LOGICAL
Default: | .FALSE.

>     If .TRUE., prints the occupation eigenvectors.

[Back to Top]

min_gamma_n | DOUBLE
Default: | 1.D0

>     Learning rate of optimizations. See optimization_method.

[Back to Top]

has_min_multiplier | LOGICAL
Default: | .FALSE.

>     If .TRUE., sets the minimum value of the OS-CDFT multipliers
>     to min_multiplier.

[Back to Top]

min_multiplier | DOUBLE
Status: | REQUIRED if has_min_multiplier is .TRUE.

>     Minimum value of the OS-CDFT multipliers.
>     Enabled using has_min_multiplier

[Back to Top]

has_max_multiplier | LOGICAL
Default: | .FALSE.

>     If .TRUE., sets the maximum value of the OS-CDFT multipliers
>     to max_multiplier.

[Back to Top]

max_multiplier | DOUBLE
Status: | REQUIRED if has_max_multiplier is .TRUE.

>     Maximum value of the OS-CDFT multipliers.
>     Enabled using has_max_multiplier

[Back to Top]

miniter | INTEGER
Default: | 0

>     Minimum OS-CDFT iterations.

[Back to Top]

maxiter | INTEGER
Default: | 0

>     Maximum OS-CDFT iterations.

[Back to Top]

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)

[Back to Top]

print_debug | LOGICAL
Default: | .FALSE.

>     If .TRUE., prints additional debug informations.

[Back to Top]

orthogonalize_swfc | LOGICAL
Default: | .FALSE.

>     If .TRUE., uses Lowdin orthogonalized atomic orbitals.

[Back to Top]

normalize_swfc | LOGICAL
Default: | .FALSE.

>     If .TRUE., uses Lowdin normalized atomic orbitals.
>     Atomic orbitals are not orthogonalized in this case.

[Back to Top]

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

> [Back to Top]

> spin | CHARACTER
> Status: | REQUIRED

> > `1, UP :`

> >       Spin up channel

> > `2, DOWN :`

> >       Spin down channel

> [Back to Top]

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

> [Back to Top]

> 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

> [Back to Top]

> target | DOUBLE
> Status: | REQUIRED if applied(I) == T

> >     The target occupation number for the constraint.

> [Back to Top]

> start_mul | DOUBLE
> Status: | REQUIRED if applied(I) == T

> >     Starting value of the multiplier.
> >     For normal operations, set this to 0.D0.

> [Back to Top]

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

> [Back to Top]

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

> [Back to Top]

> ### 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 Sat Mar 18 16:00:16 CET 2023.