States

Name DegeneracyThreshold
Section States
Type float
Default 1e-5

States with energy $E_i$ and $E_j$ will be considered degenerate if $ \left| E_i - E_j \right| < $DegeneracyThreshold.

Name ExcessCharge
Section States
Type float
Default 0.0

The net charge of the system. A negative value means that we are adding electrons, while a positive value means we are taking electrons from the system.

Name ExtraStates
Section States
Type integer
Default 0

The number of states is in principle calculated considering the minimum numbers of states necessary to hold the electrons present in the system. The number of electrons is in turn calculated considering the nature of the species supplied in the Species block, and the value of the ExcessCharge variable. However, one may command Octopus to use more states, which is necessary if one wants to use fractional occupational numbers, either fixed from the beginning through the Occupations block or by prescribing an electronic temperature with Smearing, or in order to calculate excited states (including with CalculationMode = unocc).

Name ExtraStatesInPercent
Section States
Type float
Default 0

This variable allows to set the number of extra/empty states as percentage of the used occupied states. For example, a value 35 for ExtraStatesInPercent would amount to ceiling(35/100 * nstates) extra states, where nstates denotes the amount of occupied states Octopus is using for the system at hand.

Name ExtraStatesToConverge
Section States
Type integer
Default 0

Only for unocc calculations. Specifies the number of extra states that will be considered for reaching the convergence. Together with ExtraStates, one can have some more states which will not be considered for the convergence criteria, thus making the convergence of the unocc calculation faster. By default, all extra states need to be converged.

Name InitialSpins
Section States
Type block

The spin character of the initial random guesses for the spinors can be fixed by making use of this block. Note that this will not "fix" the the spins during the calculation (this cannot be done in spinors mode, in being able to change the spins is why the spinors mode exists in the first place).

This block is meaningless and ignored if the run is not in spinors mode (SpinComponents = spinors).

The structure of the block is very simple: each column contains the desired $\left< S_x \right>, \left< S_y \right>, \left< S_z \right> $ for each spinor. If the calculation is for a periodic system and there is more than one k-point, the spins of all the k-points are the same.

For example, if we have two spinors, and we want one in the $S_x$ "down" state, and another one in the $S_x$ "up" state:

%InitialSpins
    0.5 | 0.0 | 0.0
   -0.5 | 0.0 | 0.0
%

WARNING: if the calculation is for a system described by pseudopotentials (as opposed to user-defined potentials or model systems), this option is meaningless since the random spinors are overwritten by the atomic orbitals.

This constraint must be fulfilled:
$ \left< S_x \right>^2 + \left< S_y \right>^2 + \left< S_z \right>^2 = \frac{1}{4} $

Name Occupations
Section States
Type block

The occupation numbers of the orbitals can be fixed through the use of this variable. For example:

%Occupations
  2 | 2 | 2 | 2 | 2
%

would fix the occupations of the five states to 2. There can be at most as many columns as states in the calculation. If there are fewer columns than states, then the code will assume that the user is indicating the occupations of the uppermost states where all lower states have full occupation (i.e. 2 for spin-unpolarized calculations, 1 otherwise) and all higher states have zero occupation. The first column will be taken to refer to the lowest state such that the occupations would be consistent with the correct total charge. For example, if there are 8 electrons and 10 states (from ExtraStates = 6), then an abbreviated specification

%Occupations
  1 | 0 | 1
%

would be equivalent to a full specification

%Occupations
  2 | 2 | 2 | 1 | 0 | 1 | 0 | 0 | 0 | 0
%

This is an example of use for constrained density-functional theory, crudely emulating a HOMO->LUMO+1 optical excitation. The number of rows should be equal to the number of k-points times the number of spins. For example, for a finite system with SpinComponents == spin_polarized, this block should contain two lines, one for each spin channel. All rows must have the same number of columns.

The Occupations block is useful for the ground state of highly symmetric small systems (like an open-shell atom), to fix the occupation numbers of degenerate states in order to help octopus to converge. This is to be used in conjuction with ExtraStates. For example, to calculate the carbon atom, one would do:

ExtraStates = 2
%Occupations
  2 | 2/3 | 2/3 | 2/3
%

If you want the calculation to be spin-polarized (which makes more sense), you could do:

ExtraStates = 2
%Occupations
   2/3 | 2/3 | 2/3
   0 | 0 | 0
%

Note that in this case the first state is absent, the code will calculate four states (two because there are four electrons, plus two because ExtraStates = 2), and since it finds only three columns, it will occupy the first state with one electron for each of the spin options.

If the sum of occupations is not equal to the total charge set by ExcessCharge, an error message is printed. If FromScratch = no and RestartFixedOccupations = yes, this block will be ignored.

Name OnlyUserDefinedInitialStates
Section States
Type logical
Default no

If true, then only user-defined states from the block UserDefinedStates will be used as initial states for a time-propagation. No attempt is made to load ground-state orbitals from a previous ground-state run.

Name PhotoDopingBand
Section States
Type integer
Default 1

This variable specifies where the minium (starting) conduction band index for the photodoping electrons.

Name PhotoDopingNumElectrons
Section States
Type float
Default 0

This variable allows to set the number of valence electrons taken out to put into the conduction bands. The method follows Marini and Calandra, PRB 104, 144103 (2021).

Name PhotoDopingSmearing
Section States
Type float
Default 0.1 eV

If Occupations is not set, PhotoDopingSmearing is the smearing width used in the SmearingFunction to distribute the electrons in conduction bands among the existing states.

Name RestartFixedOccupations
Section States
Type logical
Default yes

Setting this variable will make the restart proceed as if the occupations from the previous calculation had been set via the Occupations block, i.e. fixed. Otherwise, occupations will be determined by smearing.

Name RestartReorderOccs
Section States
Type logical
Default no

Consider doing a ground-state calculation, and then restarting with new occupations set with the Occupations block, in an attempt to populate the orbitals of the original calculation. However, the eigenvalues may reorder as the density changes, in which case the occupations will now be referring to different orbitals. Setting this variable to yes will try to solve this issue when the restart data is being read, by reordering the occupations according to the order of the expectation values of the restart wavefunctions.

Name Smearing
Section States
Type float
Default 0.1 eV

If Occupations is not set, Smearing is the smearing width used in the SmearingFunction to distribute the electrons among the existing states.

Name SmearingFunction
Section States
Type integer
Default semiconducting

This is the function used to smear the electronic occupations. It is ignored if the Occupations block is set.

Options:

• semiconducting:
  Semiconducting occupations, i.e. the lowest lying states are occupied until no more electrons are left.
  
• fermi_dirac:
  Simple Fermi-Dirac distribution. In this case, Smearing has the meaning of an electronic temperature. DN Mermin, Phys. Rev. 137, A1441 (1965).
  
• cold_smearing:
  N Marzari, D Vanderbilt, A De Vita, and MC Payne, Phys. Rev. Lett. 82, 3296 (1999).
  
• methfessel_paxton:
  M Methfessel and AT Paxton, Phys. Rev. B 40, 3616 (1989). In this case, the variable SmearingMPOrder sets the order of the smearing. Occupations may be negative.
  
• spline_smearing:
  Nearly identical to Gaussian smearing. JM Holender, MJ Gillan, MC Payne, and AD Simpson, Phys. Rev. B 52, 967 (1995).
  

Name SmearingMPOrder
Section States
Type integer
Default 1

Sets the order of the Methfessel-Paxton smearing function.

Name SpinComponents
Section States
Type integer
Default unpolarized

The calculations may be done in three different ways: spin-restricted (TD)DFT (i.e., doubly occupied "closed shells"), spin-unrestricted or "spin-polarized" (TD)DFT (i.e. we have two electronic systems, one with spin up and one with spin down), or making use of two-component spinors.

Options:

• unpolarized:
  Spin-restricted calculations.
  
• polarized:
  
• spin_polarized:
  (Synonym polarized.) Spin-unrestricted, also known as spin-DFT, SDFT. This mode will double the number of wavefunctions necessary for a spin-unpolarized calculation.
  
• non_collinear:
  
• spinors:
  (Synonym: non_collinear.) The spin-orbitals are two-component spinors. This effectively allows the spin-density to be oriented non-collinearly: i.e. the magnetization vector is allowed to take different directions at different points. This vector is always in 3D regardless of Dimensions.
  

Name StatesRandomization
Section States
Type integer
Default par_independent

The randomization of states can be done in two ways: i) a parallelisation independent way (default), where the random states are identical, irrespectively of the number of tasks and ii) a parallelisation dependent way, which can prevent linear dependency to occur for large systems.

Options:

• par_independent:
  Parallelisation-independent randomization of states.
  
• par_dependent:
  The randomization depends on the number of taks used in the calculation.
  

Name SymmetrizeDensity
Section States
Type logical
Default no

When enabled the density is symmetrized. Currently, this can only be done for periodic systems. (Experimental.)

Name TotalStates
Section States
Type integer
Default 0

This variable sets the total number of states that Octopus will use. This is normally not necessary since by default Octopus sets the number of states to the minimum necessary to hold the electrons present in the system. (This default behavior is obtained by setting TotalStates to 0).

If you want to add some unoccupied states, probably it is more convenient to use the variable ExtraStates.

Name TransformStates
Section States
Type block
Default no

Before starting the td calculation, the initial states (that are read from the restart/gs directory, which should have been generated in a previous ground-state calculation) can be "transformed" among themselves. The block TransformStates gives the transformation matrix to be used. The number of rows and columns of the matrix should equal the number of the states present in the time-dependent calculation (the independent spin and k-point subspaces are all transformed equally); the number of columns should be equal to the number of states present in the restart/gs directory. This number may be different: for example, one could have run previously in unocc mode in order to obtain unoccupied Kohn-Sham states, and therefore restart/gs will contain more states. These states can be used in the transformation.

Note that the code will not check the orthonormality of the new states!

Each line provides the coefficients of the new states, in terms of the old ones. The coefficients are complex, but the imaginary part will be ignored for real wavefunctions. Note: This variable cannot be used when parallel in states.

Name UserDefinedStates
Section States
Type block

Instead of using the ground state as initial state for time-propagations it might be interesting in some cases to specify alternate states. Like with user-defined potentials, this block allows you to specify formulas for the orbitals at t=0.

Example:

%UserDefinedStates
   1 | 1 | 1 | formula | "exp(-r^2)exp(-i0.2*x)" | normalize_yes
%

The first column specifies the component of the spinor, the second column the number of the state and the third contains k-point and spin quantum numbers. Column four indicates that column five should be interpreted as a formula for the corresponding orbital.

Alternatively, if column four states file the state will be read from the file given in column five.

%UserDefinedStates
   1 | 1 | 1 | file | "/path/to/file" | normalize_no
%

Octopus reads first the ground-state orbitals from the restart/gs directory. Only the states that are specified in the above block will be overwritten with the given analytic expression for the orbital.

The sixth (optional) column indicates whether Octopus should renormalize the orbital. The default (no sixth column given) is to renormalize.

Options:

• file:
  Read initial orbital from file. Accepted file formats, detected by extension: obf, ncdf and csv (real only).
  
• formula:
  Calculate initial orbital by given analytic expression.
  
• normalize_yes:
  Normalize orbitals (default).
  
• normalize_no:
  Do not normalize orbitals.