.. Copyright (c) 1998 Lawrence Livermore National Security, LLC and other
   HYPRE Project Developers. See the top-level COPYRIGHT file for details.

   SPDX-License-Identifier: (Apache-2.0 OR MIT)


FAC
==============================================================================

FAC is a parallel fast adaptive composite grid solver for finite volume,
cell-centred discretizations of smooth diffusion coefficient problems.  To be
precise, it is a FACx algorithm since the patch solves consist of only
relaxation sweeps. For details of the basic overall algorithms, see [McCo1989]_.
Algorithmic particularities include formation of non-Galerkin coarse-grid
operators (i.e., coarse-grid operators underlying refinement patches are
automatically generated) and non-stored linear/constant
interpolation/restriction operators. Implementation particularities include a
processor redistribution of the generated coarse-grid operators so that
intra-level communication between adaptive mesh refinement (AMR) levels during
the solve phase is kept to a minimum. This redistribution is hidden from the
user.

The user input is essentially a linear system describing the *composite*
operator, and the refinement factors between the AMR levels. To form this
composite linear system, the AMR grid is described using semi-structured grid
parts. Each AMR level grid corresponds to a separate part so that this level
grid is simply a collection of boxes, all with the same refinement factor, i.e.,
it is a struct grid. However, several restrictions are imposed on the patch
(box) refinements.  First, a refinement box must cover all underlying coarse
cells- i.e., refinement of a partial coarse cell is not permitted. Also, the
refined/coarse indices must follow a mapping: with :math:`[r_1,r_2,r_3]`
denoting the refinement factor and :math:`[a_1,a_2,a_3] \times [b_1,b_2,b_3]`
denoting the coarse subbox to be refined, the mapping to the refined patch is

.. math::

   [r_1*a_1,r_2*a_2,r_3*a_3] \times [r_1*b_1+ r_1-1, r_2*b_2+ r_2-1,r_3*b_3+ r_3-1].

With the AMR grid constructed under these restrictions, the composite matrix can
be formed. Since the AMR levels correspond to semi-structured grid parts, the
composite matrix is a semi-structured matrix consisting of structured components
within each part, and unstructured components describing the
coarse-to-fine/fine-to-coarse connections. The structured and unstructured
components can be set using stencils and the ``HYPRE_SStructGraphAddEntries``
routine, respectively.  The matrix coefficients can be filled after setting
these non-zero patterns. Between each pair of successive AMR levels, the coarse
matrix underlying the refinement patch must be the identity and the
corresponding rows of the rhs must be zero. These can performed using routines
``HYPRE_SStructFACZeroCFSten`` (to zero off the stencil values reaching from
coarse boxes into refinement boxes), ``HYPRE_SStructFACZeroFCSten`` (to zero off
the stencil values reaching from refinement boxes into coarse boxes),
``HYPRE_SStructFACZeroAMRMatrixData`` (to set the identity at coarse grid points
underlying a refinement patch), and ``HYPRE_SStructFACZeroAMRVectorData`` (to
zero off a vector at coarse grid points underlying a refinement patch).  These
routines can simplify the user's matrix setup. For example, consider two
successive AMR levels with the coarser level consisting of one box and the finer
level consisting of a collection of boxes. Rather than distinguishly setting the
stencil values and the identity in the appropriate locations, the user can set
the stencil values on the whole coarse grid using the
``HYPRE_SStructMatrixSetBoxValues`` routine and then zero off the appropriate
values using the above zeroing routines.

The coarse matrix underlying these patches are algebraically generated by
operator-collapsing the refinement patch operator and the fine-to-coarse
coefficients (this is why stencil values reaching out of a part must be
zeroed). This matrix is re-distributed so that each processor has all of its
coarse-grid operator.

To solve the coarsest AMR level, a PFMG V cycle is used. Note that a minimum of
two AMR levels are needed for this solver.

