# Input.occup

At the beginning of a Self-Consistent Field cycle, when the initial wavefunctions are not available from the memory, BigDFT uses as input wavefunctions a suitable linear combination of Atomic Orbitals (AO).
This linear combination is found by identifying the *norb* lowest-energy eigenstates of the Kohn-Sham (KS) Hamiltonian written in the AO basis.

These AO are important to have a initial electronic density and a corresponding KS Hamiltonian. They are generated by solving the Self-consistent KS equation for the Isolated Atom, within LDA approximation and the PSP parameter which are provided by the used for the full run (even if they are not associated to LDA functional). This equation is solved in a basis of even-tempered Gaussians centered on the atoms. The AO wavefunctions (used to build the Atomic Density for the Atomic KS hamiltonian) are then obtained by suitable occupations of the different eigenvectors written in this basis.

Therefore, BigDFT Input Guess is determined by the choice of the Atomic occupation orbitals. The default values are tabulated in the code and generally correspond to the (pseudo) electron configuration of the isolated atom.

However, for some systems it is suitable to override such default values.
This happens in particular when the environment around a give atom (or a given atomic species) is such to strongly modify the electron configuration at convergence. In this case, with the default atomic occupation the code would have convergence problems, as the input KS Hamiltonian is too far from the converged one. The file *input.occup* provides to the user a facilty to modify such Atomic Input occupation.

## Contents |

## File Format and Syntax

The format of *input.occup* file is **yaml** format. This is given in coherency with the BigDFT logfile. For an overview of **yaml** specifications see this page.
The occupation numbers can be defined for a given atom number according to the order given by the input positions, or alternatively for all the atoms belonging to a given species.

Let us illustrate this format with an example.
Imagine we would like to specify the occupation number for the ` Fe ` atom, with 16 valence electron.
This configuration corresponds to the 3s^{2} 3p^{6} 3d^{6} 4s^{2} configuration. This atomic occupation can be specified in the following way:

Fe: (3s): 2 (3p): 6 3d: 6 4s: 2

where the indentation (rigorously only by spaces and without tabbings according to yaml specification) is specifying the shells which belong to ` Fe ` atom. Alternatively, in the flow mapping yaml style, the same information can be given in a single line:

Fe: { (3s): 2, (3p): 6, 3d: 6, 4s: 2}

In this way, **all** the ` Fe ` atoms in the system will have this input occupation. In case we would like to give this occupation only to one of the atoms of the system (say atom No. 5), in the order given by the atomic positions (considering all the atoms), we can specify that by the ` Atom 5 ` key:

Atom 5: (3s): 2 (3p): 6 3d: 6 4s: 2

this will change the input occupation only of fifth atom of the system.

### Shell names and Semicore Shells

Each of the shell names have obvious meaning, given by the principal and angular quantum number.
It is important to notice that the code **does not need** the principal quantum number of each shell, therefore the information is purely decorative.
A physically meaningless information like for example

Fe: { (1s): 2, (1p): 6, 1d: 6, 2s: 2}

would produce the same results.

An important information is encoded by the parenthesys, which tells to the code that these shells have to be treated as **semicore** shells.
This fact means that the corresponding atomic wavefunctions have to be always considered in the input BigDFT wavefunctions **regardless** of their energy in the input hamiltonian. This might be useful especially when the energy of the atomic semicore states is overestimated by the input system. If this is not needed, the parenthesys can be removed, in the following way:

Fe: 3s: 2 3p: 6 3d: 6 4s: 2

and the atomic shells will be treated on equal footing. Note that the shell identification starts always at the same column (indentation is based on the starting character of the key, not on the semicolon).

### Values of the occupation numbers

Both integers and real occupation numbers can be provided. In other terms, also this format is accepted:

Fe: 3s: 2.0 3p: 6 3d: 6.0 4s: 2

Moreover, floating point number can also be expressed in scientific notation (1.e-10 for example), and also fractions are accepted, like

[...] 3p: 2/3 [...]

However, there is an important limitation: for internal workspace reasons, the number of specified shells *per angular quantum number* cannot exceed three.
For example, if we add an extra 5s shell to the above `Fe` atoms, the following error message is produced:

STOP 'noccmax too little'

which will be make more explicit in future versions of the code. In addition, the total number of shells for a given atom (species) cannot exceed 10.

### Spin-polarized atoms

In the above example there is no information on the spin of the atom, this means that the atom is assumed to be spin-averaged (unpolarized). This degeneracy can be removed by specifying the `up` and `down` keywords to each of the desired shells.
For example it could be interesting to polarize the input atom by following the Hund's rule. We should write then:

Fe: (3s): 2 (3p): 6 3d: up: 5 down: 1 4s: 2

with obvious meaning of the quantities. Also the following syntaxes are equivalent:

Fe: (3s): 2 (3p): 6 3d: { up: 5, down: 1} 4s: 2

or even more compact (but less readable):

Fe: { (3s): 2, (3p): 6, 3d: {up: 5, down: 1}, 4s: 2}

Note that this specification would work even for a spin-averaged DFT run (it will be automatically interpreted like the first case).

### Non Spherical occupations

If the atomic occupations are given as specified above it is assumed that the atoms are spherically symmetric. This means that if the shell is not full each of the orbitals is given the same fraction of electron.
In the above example, each of the electrons of the `down` sector of the `3d` shell will have 1/5 electrons. To break this sphericity at the level of the atomic input guess one can specify the list of all the orbitals occupation in the shells:

Fe:

(3s): 2 (3p): 6 3d: up: 5 down: [1, 0, 0, 0, 0] 4s: 2

where each of the entries of the `down` list is associated to a different `d` orbital. Therefore an occupation like

[...] down: [0, 0, 0, 1, 0] [...]

would not produce in general the same results. Also fractional occupations are possible, like for example:

[...] down: [1/3, 1/3, 1/3, 0, 0] [...]

or also

[...] down: [1/4, 1/4, 1/4, 1/8, 1/8] [...]

The number of entries of the list is of course associated to the size of the subspace. For non-spin polarized orbitals the average number is divided by two. A valid example can be also:

Fe: (3s): 2 (3p): 6 3d: [2,2,1,1,0] 4s: 2

## Caveat and Disclaimer

As it can be understood from the introduction, there is no perfect thumb rule to find the most appropriate Input Guess occupation for each of the atoms of a given system. Ideally, the code should converge to the Ground State regardless of the initial guess. This facility is therefore useful when one has chemical intuition of what might be the reasons for a bad wavefunction convergence.

Note also that this file allows also to define atoms with unphysical polarizations and net charges. **No check** is performed by the code to ensure that the atom has the good charge or that the sum of atomic polarization is in agreement with `mpol` variable.

Therefore, this file is intended for expert users.
For more cross-checks, specify the polarization within the `posinp` file as described in Atomic positions file format page.