Density Fitting
***************

The Coulomb potential in Band is computed using a method called
density fitting. The density fitting scheme in BAND is called **Zlm
Fit**, and it is described in reference [1]. The ZlmFit is also used
to compute (when needed) the gradient and hessian of the electron
density.


Zlm Fit
=======

The idea behind Zlm Fit can be summarized as follows: the total
electron density is split into localized atomic densities (in a
similar way as the volume is partitioned in the Becke grid). These
atomic densities are then approximated by a combination of radial
spline functions and real spherical harmonics (Zlm), for which the
Coulomb potential can be easily computed.

   ZlmFit
      Quality [Auto | Basic | Normal | Good | VeryGood | Excellent]
      QualityPerRegion
         Quality [Basic | Normal | Good | VeryGood | Excellent]
         Region string
      End
   End

"ZlmFit"
   Type:
      Block

   Description:
      Options for the density fitting scheme 'ZlmFit'.

   "Quality"
      Type:
         Multiple Choice

      Default value:
         Auto

      Options:
         [Auto, Basic, Normal, Good, VeryGood, Excellent]

      GUI name:
         Spline Zlm fit

      Description:
         Quality of the density-fitting approximation. For a
         description of the various qualities and the associated
         numerical accuracy see reference. If 'Auto', the quality
         defined in the 'NumericalQuality' will be used.

   "QualityPerRegion"
      Type:
         Block

      Recurring:
         True

      Description:
         Sets the ZlmFit quality for all atoms in a region. If
         specified, this overwrites the globally set quality.

      "Quality"
         Type:
            Multiple Choice

         Options:
            [Basic, Normal, Good, VeryGood, Excellent]

         Description:
            The region's quality of the ZlmFit.

      "Region"
         Type:
            String

         Description:
            The identifier of the region for which to set the quality.

Example: Multiresolution illustrates how to use the "QualityPerRegion"
option.


Expert options
--------------

   ZlmFit
      LMargin integer
      AllowBoost Yes/No
      DensityThreshold float
      PartitionFunThreshold float
      FGaussianW float
      FGridSpacing float
      FKSpaceCutOff float
      FirstTopoCell integer
      LastTopoCell integer
      OrderTopoTrick integer
      NumStarsPartitionFun integer
   End

"ZlmFit"
   Type:
      Block

   Description:
      Options for the density fitting scheme 'ZlmFit'.

   "LMargin"
      Type:
         Integer

      Description:
         User-defined l-margin, i.e., l_max for fitting is max(lMargin
         + l_max_basis_function, 2*l_max_basis_function). Depends on
         Quality and normally is 4

   "AllowBoost"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Allow automatic atom-dependent tuning of maximum l of
         spherical harmonics expansion. Whether or not this boost is
         needed for a given atom is based on an heuristic estimate of
         how complex the density around that atom is.

   "DensityThreshold"
      Type:
         Float

      Description:
         Threshold below which the electron density is considered to
         be negligible. Depends on Quality and is normally 1.0e-7

   "PartitionFunThreshold"
      Type:
         Float

      Default value:
         0.0

      Description:
         Threshold for the partition functions: if an integration
         point has a partition function weight smaller than this
         threshold, it will be discarded.

   "FGaussianW"
      Type:
         Float

      Default value:
         1.0

      Description:
         Only for 3D periodic systems. Width of the Gaussian functions
         replacing the S and P Zlms for Fourier transform.

   "FGridSpacing"
      Type:
         Float

      Description:
         Only for 3D periodic systems. Spacing for the Fourier grid.
         By default, this depends on the quality.

   "FKSpaceCutOff"
      Type:
         Float

      Description:
         Only for 3D periodic systems. Cut-off of the grid in k-space
         for the Fourier transform.

   "FirstTopoCell"
      Type:
         Integer

      Default value:
         5

      Description:
         First cell for the topological extrapolation of the long
         range part of the Coulomb Potential.

   "LastTopoCell"
      Type:
         Integer

      Default value:
         10

      Description:
         Last cell for the topological extrapolation of the long range
         part of the Coulomb Potential.

   "OrderTopoTrick"
      Type:
         Integer

      Default value:
         3

      Description:
         Order of the topological extrapolation of the long range part
         of the Coulomb Potential.

   "NumStarsPartitionFun"
      Type:
         Integer

      Default value:
         5

      Description:
         Number of cell stars to consider when computing the partition
         function.


STO Fit (Deprecated)
====================

In previous version of BAND (pre2014) this was the default option,
which is now replaced by Zlm Fit. It is still used in the context of
"NMR" and "OldResponse" calculations.

[1] M. Franchini, P.H.T. Philipsen, E. van Lenthe, L. Visscher,
    *Accurate Coulomb Potentials for Periodic and Molecular Systems
    through Density Fitting*,  Journal of Chemical Theory and
    Computation 10, 1994 (2014).
