*** FILE AUTOMATICALLY CREATED: DO NOT EDIT, CHANGES WILL BE LOST *** ------------------------------------------------------------------------ INPUT FILE DESCRIPTION Program: pw.x with OS-CDFT / PWscf / Quantum ESPRESSO (version: 7.5) ------------------------------------------------------------------------ :::: 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 ""://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 ... 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 -oscdft ... 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 +-------------------------------------------------------------------- Variable: oscdft_type Type: INTEGER Default: 1 Description: 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). +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: n_oscdft Type: INTEGER Status: REQUIRED Description: Number of entries of the "TARGET_OCCUPATION_NUMBERS" card. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: get_ground_state_first Type: LOGICAL Default: .FALSE. Description: If .TRUE., perform an scf calculation to convergence before applying constraint. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: warm_up_niter Type: INTEGER Default: 0 Description: 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. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: convergence_type Type: CHARACTER Default: 'gradient' Description: 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). +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: iteration_type Type: INTEGER Status: REQUIRED Description: 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. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: optimization_method Type: CHARACTER Default: 'gradient descent' Description: 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) +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: array_convergence_func Type: CHARACTER Default: 'maxval' Description: 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. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: max_conv_thr Type: DOUBLE Default: 1.D-1 Description: 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. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: min_conv_thr Type: DOUBLE Default: 1.D-3 Description: 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. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: final_conv_thr Type: DOUBLE Default: -1.D0 Description: 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. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: conv_thr_multiplier Type: DOUBLE Default: 0.5D0 Description: If "iteration_type" is 0, see "iteration_type" for explanations. Otherwise, this is ignored. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: print_occupation_matrix Type: LOGICAL Default: .FALSE. Description: If .TRUE., prints the occupation matrices. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: print_occupation_eigenvectors Type: LOGICAL Default: .FALSE. Description: If .TRUE., prints the occupation eigenvectors. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: min_gamma_n Type: DOUBLE Default: 1.D0 Description: Learning rate of optimizations. See "optimization_method". +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: has_min_multiplier Type: LOGICAL Default: .FALSE. Description: If .TRUE., sets the minimum value of the OS-CDFT multipliers to "min_multiplier". +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: min_multiplier Type: DOUBLE Status: REQUIRED if "has_min_multiplier" is .TRUE. Description: Minimum value of the OS-CDFT multipliers. Enabled using "has_min_multiplier" +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: has_max_multiplier Type: LOGICAL Default: .FALSE. Description: If .TRUE., sets the maximum value of the OS-CDFT multipliers to "max_multiplier". +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: max_multiplier Type: DOUBLE Status: REQUIRED if "has_max_multiplier" is .TRUE. Description: Maximum value of the OS-CDFT multipliers. Enabled using "has_max_multiplier" +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: miniter Type: INTEGER Default: 0 Description: Minimum OS-CDFT iterations. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: maxiter Type: INTEGER Default: 0 Description: Maximum OS-CDFT iterations. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: swapping_technique Type: CHARACTER Default: 'none' Description: See ""://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) +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: debug_print Type: LOGICAL Default: .FALSE. Description: If .TRUE., prints additional debug informations. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: orthogonalize_swfc Type: LOGICAL Default: .FALSE. Description: If .TRUE., uses Lowdin orthogonalized atomic orbitals. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: normalize_swfc Type: LOGICAL Default: .FALSE. Description: If .TRUE., uses Lowdin normalized atomic orbitals. Atomic orbitals are not orthogonalized in this case. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: constraint_strength Type: DOUBLE Default: 1.0D0 Description: Multiplicative factor in front of the constraint term in the potential (and energy). +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: constraint_conv_thr Type: DOUBLE Default: 5.0D-3 Description: 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. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: constraint_maxstep Type: INTEGER Default: 200 Description: When the number of SCF iterations is larger than this number, the constraint is not updated. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: constraint_mixing_beta Type: DOUBLE Default: 4.0D-1 Description: The multiplicative factor in front of the constraint term. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: constraint_diag Type: LOGICAL Default: .FALSE. Description: 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). +-------------------------------------------------------------------- ===END OF NAMELIST====================================================== ======================================================================== 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: +-------------------------------------------------------------------- Variable: applied Type: CHARACTER Status: REQUIRED Description: 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. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: spin Type: CHARACTER Status: REQUIRED Description: 1, UP : Spin up channel 2, DOWN : Spin down channel +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: orbital_desc Type: CHARACTER Status: REQUIRED Description: 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. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: constr_idx Type: VARIOUS Status: REQUIRED if "applied"(I) == T Description: 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 +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: target Type: DOUBLE Status: REQUIRED if "applied"(I) == T Description: The target occupation number for the constraint. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: start_mul Type: DOUBLE Status: REQUIRED if "applied"(I) == T Description: Starting value of the multiplier. For normal operations, set this to 0.D0. +-------------------------------------------------------------------- +-------------------------------------------------------------------- Variable: start_index Type: INTEGER Default: 1 Description: 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. +-------------------------------------------------------------------- ===END OF CARD========================================================== ======================================================================== 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: +-------------------------------------------------------------------- Variable: gamma_val Type: DOUBLE Status: REQUIRED if "optimization_method" == 'gradient descent2' Description: This sets the learning rate for each multipliers, allowing different learning rate for each multipliers. See "optimization_method" for more details. +-------------------------------------------------------------------- ===END OF CARD========================================================== :::: 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