Density of States (DOS)
***********************

   DOS
      CalcDOS Yes/No
      CalcPDOS Yes/No
      CalcPopulationAnalysis Yes/No
      CompensateDeltaE Yes/No
      DeltaE float
      Energies integer
      File string
      IntegrateDeltaE Yes/No
      Max float
      Min float
      StoreCoopPerBasPair Yes/No
   End

"DOS"
   Type:
      Block

   Description:
      Density-Of-States (DOS) options

   "CalcDOS"
      Type:
         Bool

      Default value:
         Yes

      GUI name:
         Calculate DOS

      Description:
         Whether or not to calculate the density of states.

   "CalcPDOS"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Calculate PDOS

      Description:
         Whether or not to calculate the partial DOS (projections on
         basis functions). This can be significantly more expensive
         than calculating the total DOS

   "CalcPopulationAnalysis"
      Type:
         Bool

      Default value:
         Yes

      GUI name:
         Calculate Mulliken charges

      Description:
         Whether or not to calculate the population analysis.
         Population analysis can become very expensive when there are
         many symmetry operators, such as in a super cell.

   "CompensateDeltaE"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Only relevant when IntegrateDeltaE=yes. If set to true then
         after integrating each interval over DeltaE the result is
         divided by DeltaE, so that the unit is DOS.

   "DeltaE"
      Type:
         Float

      Default value:
         0.005

      Unit:
         Hartree

      GUI name:
         Delta E

      Description:
         Energy step for the DOS grid. Using a smaller value (e.g.
         half the default value) will result in a finer sampling of
         the DOS.

   "Energies"
      Type:
         Integer

      Description:
         Number of equidistant energy-values for the DOS grid. This
         keyword is superseded by the 'DeltaE' keyword.

   "File"
      Type:
         String

      Description:
         Write the DOS (plain text format) to the specified file
         instead of writing it to the standard output.

   "IntegrateDeltaE"
      Type:
         Bool

      Default value:
         Yes

      Description:
         This subkey handles which algorithm is used to calculate the
         data-points in the plotted DOS. If true, the data-points
         represent an integral over the states in an energy interval.
         Here, the energy interval depends on the number of Energies
         and the user-defined upper and lower energy for the
         calculation of the DOS. The result has as unit [number of
         states / (energy interval * unit cell)]. If false, the data-
         points do represent the number of states for a specific
         energy and the resulting plot is equal to the DOS per unit
         cell (unit: [1/energy]). Since the resulting plot can be a
         wild function and one might miss features of the DOS due to
         the step length between the energies, the default is set to
         the integration algorithm.

   "Max"
      Type:
         Float

      Unit:
         Hartree

      Description:
         User defined upper bound energy (with respect to the Fermi
         energy)

   "Min"
      Type:
         Float

      Unit:
         Hartree

      Description:
         User defined lower bound energy (with respect to the Fermi
         energy)

   "StoreCoopPerBasPair"
      Type:
         Bool

      Default value:
         No

      GUI name:
         Calculate COOP

      Description:
         Calculate the COOP (crystal orbital overlap population).

An example input:

   DOS
      Enabled     True
      Energies    500
      Min        -0.35
      Max         1.05
      File        plotfile
   End

According to this example, DOS values will be generated in an
equidistant mesh of 500 energy values, ranging from 0.35 a.u. below
the Fermi level to 1.05 a.u. above it. All information will be written
to a file plotfile. The information on the plot file is a long list of
pairs of values (energy and DOS), with some informative text-headers
and general information. DOS values are generated for the total DOS
and optionally also for some partial DOS (see the keys
GrossPopulations and OverlapPopulations).

A common problem is that of missing DOS: an energy interval with bands
but no DOS. This is caused by an insufficient k-space sampling. Try to
Restart the DOS with a better k-grid.

In the **DOS** and **Band Structure** **GUI modules**, it is possible
to visualize partial density of states (**p-DOS**). The partial
contributions are obtained from the total DOS by following the
**Mulliken population analysis** partitioning prescription (see
wikipedia).

Tip:

  The tutorial Calculation of Band Structure and COOP of CsPbBr3 with
  BAND contains some advanced usage of the **DOS** and **BAND
  Structure** **GUI modules**.


Gross populations
=================

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

"GrossPopulations"
   Type:
      Non-standard block

   Description:
      Partial DOS (pDOS) are generated for the gross populations
      listed under this key. See example.

Syntax:

   GrossPopulations
      {iat lq}
      {FragFun jat ifun}
      {Frag kat}
      {Sum
       ...
       EndSum}
   End

"iat"
   pDOS is generated for atom *lq*.

"FragFun"
   pDOS is generated for atom *jat* with all real spherical harmonics
   belonging to l-value *ifun*.

"Frag"
   pDOS of the functions belonging to atom *kat* will be calculated.

"Sum"
   sum all pDOS, specified in this block.

Example:

   GrossPopulations
      FragFun 1 2:: Second function of first atom
      Frag 2 :: Sum of all functions from second atom
      SUM:: sum following PDOSes
         Frag 1::Atom nr.1
         FragFun 2 1::First function of second atom
         5 1:: All pfunctions of fifth atom
      EndSum
   End


Overlap populations
===================

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

"OverlapPopulations"
   Type:
      Non-standard block

   Description:
      Overlap population weighted DOS (OPWDOS), also known as the
      crystal orbital overlap population (COOP).

*Overlap population weighted* DOS are generated for the overlap
populations listed:

   OVERLAPPOPULATIONS
      Left
         { iat lq }
         { FragFun jat ifun }
         { Frag kat }
      Right
         ...
   End

You can use this to get the OPWDOS of two functions, or, if you like,
one bunch of functions with another bunch of functions. The key-block
should consist of left-right pairs. After a line with left you enter
lines that specify one or more functions (according to
GrossPopulations), followed by a similar structure beginning with
right, which will produce the OPWDOS of the left functions with the
right functions.

Example:

   OVERLAPPOPULATIONS
      LEFT::First OPWDOS
         Frag 1
      RIGHT
         Frag 2
      LEFT:: Next OPWDOS
         FragFun 1 1
      RIGHT
         2 1
         FragFun 3 5
   End
