# Input variables

## Input parameters for linear-scaling BigDFT

Linear-scaling BigDFT now only accepts the `yaml` input file format. We therefore require two input files: the usual XYZ coordinates file `posinp.xyz`, and an `input.yaml` file containing all the calculation parameters. The `yaml` input file contains blocks of parameters, some of which are general to cubic-scaling calculations and others which are specific to linear-scaling BigDFT.

For users who are new to the linear scaling code, it is recommended to use profiles, for example via `import linear_moderate`, as demonstrated in the following tutorials. However, for more advanced users in the following we give an overview of some of the input parameters, including recommended values for a typical O(N) calculation.
For a complete list, see the file `BIGDFT_ROOT/bigdft/src/input_variables_definition.yaml`.

** dft **:

This block contains the standard DFT input variables. The linear version is also activated here by specifying:

inputpsiid: linear

For post-processing/restart calculations we can also write the support functions to disk by setting:

output_wf: 1

** perf **:

This block contains some performance and other general variables. The following are recommended for standard O(N) calculations, but can be modified once you are familiar with the code:

store_index: No check_matrix_compression: No experimental_mode: Yes calculate_KS_residue: No hamapp_radius_incr: 6 FOE_restart: 1 foe_gap: True

** lin_general **:

This block contains the general parameters for the linear scaling version, and will therefore have similar values whether you're using FOE or direct minimization. For all variables, where two values are given this refers to 'low accuracy' iterations (with confining potential) and 'high accuracy' iterations (without confining potential), when only one value is given and the hybrid mode is not activated, the same value is used for both. Some of the important values include `nit`, the number of outer loop iterations, `rpnrm_cv`, the outer loop convergence threshold and `taylor_older` which specifies the approach used to calculate the inverse overlap matrix and related quantities. Some sensible default values are:

hybrid: Yes nit: 50 rpnrm_cv: 1.0e-12 taylor_order: 1020 max_inversion_error: 5.0e-8 output_mat: 1 output_coeff: 1

** lin_basis **:

This block contains parameters relating to the generation of support functions. These include the number of basis iterations `nit`, the DIIS history length `idsx`. Some sensible default values are:

nit: 8 idsx: 8 alpha_diis: 0.5 alpha_sd: 0.5 fix_basis: 1.0e-12 correction_orthoconstraint: 0 gnrm_ig: 1.e-1

The following parameters indicate the convergence threshold for the support functions. For medium accuracy:

gnrm_cv: 2.0e-3 min_gnrm_for_dynamic: 4.0e-3

For high accuracy:

gnrm_cv: 1.0e-3 min_gnrm_for_dynamic: 2.0e-3

** lin_kernel **:

This block contains parameters for the density kernel optimization. The values will depend on the choice of FOE or direct minimization. Important parameters include the choice of approach `linear_method`, the number of basis iterations `nit`, the DIIS history length `idsx` and the density mixing parameter `alphamix`. In general, the FOE approach is recommended as the default, however when direct access to the KS coefficients is required (e.g. transfer integrals, optimizing LUMO etc.) or for charged systems in cases where charge sloshing occurs with FOE, direct minimization should be used.

Some sensible default values for FOE are:

linear_method: FOE idsx: 6 fscale_foe: 5.0E-002

The suggested values of `nit` and `alphamix` depend on the size of the HOMO-LUMO gap. For a system with a small gap:

nit: 6 alphamix: 0.1

For a system with a large gap:

nit: 4 alphamix: 0.2

For direct minimization, we also need to define the number of steps to optimize the coefficients for each update of the kernel and density `nstep` and the corresponding DIIS history length `idsx_coeff`. If `nstep` is set to a very high number this becomes equivalent to the diagonalization approach, whereas for few steps this is similar to mixing the density. For some systems this can become unstable, particularly in charged calculations (where diagonalization and density mixing is also unstable), so use caution when increasing this parameter. In cases where instabilities occur, it is also recommended to revert to steepest descents.
Some sensible default values for direct minimization are:

linear_method: DIRMIN nit: 6 alphamix: 1.0 idsx: 6

** lin_basis_params **:

This block contains the information specifying the support functions for each atom type. These include the variables for the confining potential `ao_confinement` and `confinement` which the code can also calculate automatically. Other variables require some additional explanation:

`nbasis`: Number of support functions per atom type: usually 4 is sufficient. Exceptions include: H 1, Si 9, Pb 5.

`rloc`: Localization radius for the support functions (in bohr). Values for medium accuracy: H 5.0; B,C,N,O: 5.5, Si: 6.5, I: 8.0; Pb: 7.5. For high accuracy add about 1.0 bohr. For the best precision, performance convergence tests for each system.

`rloc_kernel`: Density kernel cutoff in atomic units. This value depends on the HOMO-LUMO gap. Large gaps: 8.0; small gaps: 9.0; even smaller gaps: 10.0. The value must be at least `rloc`+`hamapp_radius_incr`*`hgrid`. The code will adjust it automatically if this condition is not fulfilled.

`rloc_kernel_foe`: Cutoff for the columns during the matrix vector multiplications, in atomic units. The value must be at least `rloc`+`hamapp_radius_incr`*`hgrid`, otherwise the code will stop (maybe it will adjust it automatically in the future).

Example values for Carbon:

C: nbasis: 4 ao_confinement: -1.0 confinement: -1.0 rloc: 5.5 rloc kernel: 9.0 rloc kernel foe: 10.0

** ig_occupation **:

This block specifies the electronic configuration used to initialize the support functions and also the occupation numbers for the input guess inthe cubic version. It is necessary if the number of support functions is different from the electronic configuration specified by the pseudopotential. Example for Silicon:

Si: 3s: 2.0 3p: [5/3, 5/3, 5/3] 5d: [0.0, 0.0, 0.0, 0.0, 0.0]

If you want to specify only empty_shells, you can use the syntax as for H-Rydberg test:

ig_occupation: H: {empty_shells: [p, s]}