
********************************************************************************

                 Domain-decomposed deflation preconditioner

********************************************************************************


Files
-----

dfl_geometry.c      Geometry of the DFL_BLOCKS block grid.

dfl_modes.c         Computation of the global modes used to construct
                    the deflation subspace.

dfl_sap_gcr.c       SAP+GCR solver for the Wilson-Dirac equation with
                    local deflation.

dfl_subspace.c      Basic utility programs related to the deflation
                    subspace.

ltl_gcr.c           GCR solver for the little Dirac equation Aw*psi=eta.


Include file
------------

The file dfl.h defines the prototypes for all externally accessible
functions that are defined in the *.c files listed above.


List of functions
-----------------

dfl_grid_t dfl_geometry(void)
  Returns a structure containing the index arrays that describe the
  geometry of the DFL_BLOCKS block grid (see the notes).

void dfl_modes(int *status)
  Computes the basis vectors of the deflation subspace by applying a
  smoothing procedure to a set of random fields. The subspace is then
  initialized by calling the program dfl_subspace().

void dfl_update(int nsm,int *status)
  Updates the deflation subspace by applying nsm deflated smoothing
  steps to the global fields from which the current subspace was built.

void dfl_modes2(int *status)
  Calls the program dfl_modes() and, if status[0]=-3 is returned,
  call dfl_modes() a second time. The array status must have at least
  two elements that report the status values returned in the two calls.
  Normally dfl_modes() is called only once in which case status[1]=0.

void dfl_update2(int nsm,int *status)
  Calls the program dfl_update() and, if status[0]=-3 is returned,
  call dfl_modes(). The array status must have at least two elements
  that report the status values returned in the two calls. Normally
  dfl_modes is not called in which case status[1]=0.

double dfl_sap_gcr(int nkv,int nmx,double res,double mu,
                   spinor_dble *eta,spinor_dble *psi,int *status)
  Obtains an approximate solution psi of the Wilson-Dirac equation for
  given source eta using the deflated SAP-preconditioned GCR algorithm.
  See the notes for the explanation of the parameters of the program.

double dfl_sap_gcr2(int nkv,int nmx,double res,double mu,
                    spinor_dble *eta,spinor_dble *psi,int *status)
  This program calls dfl_sap_gcr() with the parameters nkv,..,status.
  If the solver fails and status[0]=-3 or status[0]>=0, the deflation
  subspace is regenerated by calling dfl_modes(). The solver program
  dfl_sap_gcr() is then called again and the results are passed to
  the calling program.

void dfl_sd2vd(spinor_dble *sd,complex_dble *vd)
  Assigns the components of the global double-precision spinor field
  sd along the deflation subspace to the double-precision vector
  field vd.

void dfl_vd2sd(complex_dble *vd,spinor_dble *sd)
  Assigns the element of the deflation subspace corresponding to the
  double-precision vector field vd to the global double-precision spinor
  field sd.

void dfl_sub_vd2sd(complex_dble *vd,spinor_dble *sd)
  Subtracts the element of the deflation subspace corresponding to the
  double-precision vector field vd from the global double-precision
  spinor field sd.

void dfl_s2v(spinor *s,complex *v)
  Assigns the components of the global single-precision spinor field
  s along the deflation subspace to the single-precision vector
  field v.

void dfl_v2s(complex *v,spinor *s)
  Assigns the element of the deflation subspace corresponding to the
  single-precision vector field v to the global single-precision spinor
  field s.

void dfl_sub_v2s(complex *v,spinor *s)
  Subtracts the element of the deflation subspace corresponding to the
  double-precision vector field v from the global single-precision spinor
  field s.

void dfl_subspace(spinor **mds)
  Copies the global single-precision spinor fields mds[0],..,mds[Ns-1]
  to the fields b.sd[1],..,b.sd[Ns] on the blocks b of the DFL_BLOCKS
  grid. The block fields are then orthonormalized and are assigned to
  the single-precision block fields b.s[1],..,b.s[Ns].
   In this basis of fields, the modes mds[0],..,mds[Ns-1] are given by
  fields vmds[0],..,vmds[Ns-1] of Ns*nb complex numbers, where nb is
  the number of blocks in the block grid. These fields are assigned to
  the last Ns single-precision vector fields of the array returned by
  vflds() [vflds/vflds.c].

double ltl_gcr(int nkv,int nmx,double res,double mu,
               complex_dble *eta,complex_dble *psi,int *status)
  Obtains an approximate solution psi of the little Dirac equation for
  given source eta using the even-odd preconditioned GCR algorithm. See
  the notes for the explanation of the parameters of the program.
