Advanced Occupation Options
***************************

By default the levels are occupied according to the aufbau principle.
In some cases it is possible to create holes below the Fermi level or
uneven occupation for alpha and beta electrons with the "Occupations"
(\Gamma-only) and alternatively the "EnforcedSpinPolarization" (for an
arbitrary number of k-points) key.

   Occupations # Non-standard block. See details.
      ...
   End

"Occupations"
   Type:
      Non-standard block

   Description:
      Allows one to input specific occupations numbers. Applies only
      for calculations that use only one k-point (i.e. pseudo-molecule
      calculations). See example.

Example:

   OCCUPATIONS
      1 occupations_alpha {// occupations_beta}
   End

* "occupations_beta" and the separating double slash (//) must not be
  used in a spin-restricted calculation.

* "occupations_alpha/beta" is a sequence of values assigned to the
  states ('bands') in energy ordering.

   ElectronHole
      BandIndex integer
      SpinIndex integer
   End

"ElectronHole"
   Type:
      Block

   Description:
      Allows one to specify an occupied band which shall be
      depopulated, where the electrons are then moved to the Fermi
      level. For a spin-restricted calculation 2 electrons are shifted
      and for a spin-unrestricted calculation only one electron is
      shifted.

   "BandIndex"
      Type:
         Integer

      Description:
         Which occupied band shall be depopulated.

   "SpinIndex"
      Type:
         Integer

      Description:
         Defines the spin of the shifted electron (1 or 2).

See the example Si_ElectronHole

Finally, also the "Convergence%StartWithMaxSpin" influences
(indirectly) the final state. Running for instance the H2 molecule
with a PBE functional preserves the triplet state through the SCF (not
being the ground state).
