Input File Description

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

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:

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:

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 Tue Mar 19 09:22:36 CET 2024.