Class for solving scalar Poisson's equation on SAMR grid, wrapping up lower-level components (FAC cycling, Poisson equation operations and boundary conditions) in a single high-level interface. More...

#include <CellPoissonFACSolver.h>

Public Member Functions
	CellPoissonFACSolver (const std::string &object_name, tbox::Pointer< tbox::Database > database=tbox::Pointer< tbox::Database >())
	Construct a solver. More...

	~CellPoissonFACSolver ()
	Destructor. More...

void	enableLogging (bool logging)
	Enable logging. More...

bool	solveSystem (const int solution, const int rhs, tbox::Pointer< hier::PatchHierarchy< DIM > > hierarchy, int coarse_ln=-1, int fine_ln=-1)
	Solve Poisson's equation, assuming an uninitialized solver state. More...

bool	solveSystem (const int solution, const int rhs)
	Solve Poisson's equation using the current solver state set by initializeSolverState(). More...

void	setBoundaries (const std::string &boundary_type, const int fluxes=-1, const int flags=-1, int *bdry_types=NULL)
	Specify the boundary conditions that are to be used at the physical domain boundary. More...

void	setBcObject (const RobinBcCoefStrategy< DIM > *bc_object)
	Override internal implementation to set boundary condition coefficients with user-provided implementation. More...

Specifying PDE parameters
void	setDPatchDataId (int id)
	Set the patch data index for variable D. More...

void	setDConstant (double scalar)
	Set the scalar value variable D. More...

void	setCPatchDataId (int id)
	Set the scalar value variable C. More...

void	setCConstant (double scalar)
	Set the patch data index for variable C. More...

void	setCoarsestLevelSolverChoice (const std::string &choice)
	Set coarse level solver. More...

void	setCoarsestLevelSolverTolerance (double tol)
	Set tolerance for coarse level solve. More...

void	setCoarsestLevelSolverMaxIterations (int max_iterations)
	Set max iterations for coarse level solve. More...

void	setCoarseFineDiscretization (const std::string &coarsefine_method)
	Set the coarse-fine boundary discretization method. More...

void	setProlongationMethod (const std::string &prolongation_method)
	Set the name of the prolongation method. More...

void	setPresmoothingSweeps (int num_pre_sweeps)
	Set the number of pre-smoothing sweeps during FAC iteration process. More...

void	setPostsmoothingSweeps (int num_post_sweeps)
	Set the number of post-smoothing sweeps during FAC iteration process. More...

void	setMaxCycles (int max_cycles)
	Set the max number of iterations (cycles) to use per solve. More...

void	setResidualTolerance (double residual_tol)
	Set the residual tolerance for stopping. More...

void	initializeSolverState (const int solution, const int rhs, tbox::Pointer< hier::PatchHierarchy< DIM > > hierarchy, const int coarse_level=-1, const int fine_level=-1)
	Prepare the solver's internal state for solving. More...

void	deallocateSolverState ()
	Remove the solver's internal state data. More...

Functions to get data on last solve.
std::string	d_object_name
	Object name. More...

PoissonSpecifications	d_poisson_spec
	Object holding the specifications of the Poisson equation. More...

CellPoissonFACOps< DIM >	d_fac_ops
	FAC operator implementation corresponding to cell-centered Poisson discretization. More...

FACPreconditioner< DIM >	d_fac_precond
	FAC preconditioner algorithm. More...

const RobinBcCoefStrategy< DIM > *	d_bc_object
	Robin bc object in use. More...

SimpleCellRobinBcCoefs< DIM >	d_simple_bc

tbox::Pointer< hier::PatchHierarchy< DIM > >	d_hierarchy

int	d_ln_min

int	d_ln_max

tbox::Pointer< hier::VariableContext >	d_context
	Context for all internally maintained data. More...

tbox::Pointer< SAMRAIVectorReal< DIM, double > >	d_uv

tbox::Pointer< SAMRAIVectorReal< DIM, double > >	d_fv

bool	d_solver_is_initialized

bool	d_enable_logging

static int	s_weight_id

static int	s_instance_counter

int	getNumberOfIterations () const
	Return FAC iteration count from last (or current if there is one) FAC iteration process. More...

void	getConvergenceFactors (double &avg_factor, double &final_factor) const
	Get average convergance rate and convergence rate of the last (or current if there is one) FAC solve. More...

double	getResidualNorm () const
	Return residual norm from the just-completed FAC iteration. More...

void	getFromInput (tbox::Pointer< tbox::Database > database)
	Set state using database. More...

void	createVectorWrappers (int u, int f)

void	destroyVectorWrappers ()

Detailed Description

template<int DIM>
class SAMRAI::solv::CellPoissonFACSolver< DIM >

Note: this class provides a backward-compatible interface to the soon-to-be obsolete PoissonHierarchySolver<DIM> class. Although this class hides the lower-level components (FAC cycling, Poisson equation operations and boundary conditions), it is perfectly acceptable to use those lower-level components directly.

We solve the equation div(D grad(u)) + Cu = f where D is a side-centered array and C is a cell-centered array. u and f are also cell-centered. Boundary conditions supported are Dirichlet, Neumann and mixed (Dirichlet on some faces and Neumann on others).

This class is a wrapper, providing a single class that coordinates three major components: the FAC solver, the cell-centered Poisson FAC operator and a default Robin bc coefficient implelemtation. It is perfectly acceptable to use those classes outside of this class.

The underlying solver is an FAC solver using cell-centered discretization. The difference scheme is second-order central-difference. On coarse-fine boundaries within the solution levels, the composite grid operator uses, by default, the discretization method of Ewing, Lazarov and Vassilevski ("Local Refinement Techniques for Elliptic Problems on Cell-Centered Grids, I. Error Analysis", Mathematics of Computation, Vol. 56, No. 194, April 1991, pp. 437-461).

Typical use of this class is:

Construct a CellPoissonFACSolver<DIM> object, providing it the hierarchy and range of levels participating in the solve.
Set the parameters C and D using the functions named setC... and setD... By default, D=1 and C=0 everywhere.
Call setBoundaries() to state the types boundary conditions, along with supplemental data for setting those boundary conditions.
Call initializeSolverState() to set up information internal to the solver. This is step is not required but will save setup costs if you are making multiple solves. This commits the object to the current hierarchy state and the specific types of boundary conditions you selected, It does NOT commit to the specific values of the boundary condition. A hierarchy change (through adaption or other means) invalidates the state, thus you must reinitialize or deallocateSolverState() the state before another solve.
Solve the equation with solveSystem(). You provide the patch data indices for the solution u and the right hand side f. u must have at least one ghost cell and where a Dirichlet boundary condition applies, those cells must be set to the value on the boundary. If only Neumann boundary conditions are used, the ghost cell values do not matter.
Call deallocateSolverState() to free up internal resources, if initializeSolverState() was called before the solve.

After the solve, information on the solve can be obtained by calling one of these functions:

getNumberOfIterations() gives the number of FAC cycles used.
getConvergenceFactors() gives the average and final convergence factors for the solve.
getResidualNorm() gives the final residual

Finer solver controls can be set using the functions in this class.

Object of this class can be set using input databases. The following parameters can be set. Each is shown with its default value in the case where hypre is used.

* enable_logging = TRUE // Bool flag to switch logging on/off
* max_cycles = 10       // Integer number of max FAC cycles to use
* residual_tol = 1.e-6  // Residual tolerance to solve for
* num_pre_sweeps = 1    // Number of presmoothing sweeps to use
* num_post_sweeps = 1   // Number of postsmoothing sweeps to use
* coarse_fine_discretization = "Ewing" // Name of coarse-fine discretization
* prolongation_method = "CONSTANT_REFINE" // Name of prolongation method
* coarse_solver_choice = "hypre"  // Name of coarse level solver
* coarse_solver_tolerance = 1e-10 // Coarse level tolerance
* coarse_solver_max_iterations = 20 // Coarse level max iterations
* use_smg = "FALSE"     // Whether to use hypre's smg solver
*                       // (alternative is the pfmg solver)
*

Constructor & Destructor Documentation

◆ CellPoissonFACSolver()

template<int DIM>

SAMRAI::solv::CellPoissonFACSolver< DIM >::CellPoissonFACSolver	(	const std::string &	object_name,
		tbox::Pointer< tbox::Database >	database = `tbox::Pointer< tbox::Database >()`
	)

If the database is not NULL, initial settings will be set using the database. The solver is uninitialized until initializeSolverState() is called.

Parameters

object_name	Name of object used in outputs
database	tbox::Database for initialization (may be NULL)

◆ ~CellPoissonFACSolver()

template<int DIM>

SAMRAI::solv::CellPoissonFACSolver< DIM >::~CellPoissonFACSolver ( )

Member Function Documentation

◆ enableLogging()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::enableLogging ( bool logging )

To disable, pass in false.

◆ solveSystem() [1/2]

template<int DIM>

bool SAMRAI::solv::CellPoissonFACSolver< DIM >::solveSystem	(	const int	solution,
		const int	rhs,
		tbox::Pointer< hier::PatchHierarchy< DIM > >	hierarchy,
		int	coarse_ln = `-1`,
		int	fine_ln = `-1`
	)

Here, u is the "solution" patch data index and f is the right hand side patch data index. The return value is true if the solver converged and false otherwise.

This function is a wrapper. It simply initializes the solver state, call the solveSystem(const int,const int) for the initialized solver then deallocates the solver state.

Upon return from this function, solution will contain the result of the solve.

See initializeSolverState() for opportunities to save overhead when using multiple consecutive solves.

See also: solveSystem(const int,const int)

Parameters

solution	hier::Patch data index for solution u
rhs	hier::Patch data index for right hand side f
hierarchy	The patch hierarchy to solve on
coarse_ln	The coarsest level in the solve.
fine_ln	The finest level in the solve.

Returns: whether solver converged to specified level

See also: initializeSolverState

◆ solveSystem() [2/2]

template<int DIM>

bool SAMRAI::solv::CellPoissonFACSolver< DIM >::solveSystem	(	const int	solution,
		const int	rhs
	)

When the solver state has been initialized, this function may be called repeadedly with different values on the rhs. There is some cost savings for multiple solves when this is done.

Before calling this function, the solution and right-hand-side quantities should be set properly by the user on all patch interiors on the range of levels covered by the FAC iteration. All data for these patch data index should be allocated. Thus, the user is responsible for managing the storage for the solution and right-hand-side.

Returns: whether solver converged to specified level

See also: solveSystem( const int, const int, tbox::Pointer< hier::PatchHierarchy<DIM> >, int, int);

◆ setBoundaries()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::setBoundaries	(	const std::string &	boundary_type,
		const int	fluxes = `-1`,
		const int	flags = `-1`,
		int *	bdry_types = `NULL`
	)

This method is used to set up the default SimpleCellRobinBcCoefs<DIM> object for specifying boundary conditions. Note that you may alternatively provide your own implementation of the Robin boundary condition coefficients using the setBcObject() method.

The boundary conditions specified as the string argument "boundary_type." The boundary type argument can be "Dirichlet", "Neumann", or "Mixed".

If using Dirichlet boundary conditions, then before the solver is called, the storage for the unknown u must have a layer of ghost cells at least one cell wide that includes the Dirichlet boundary values.

If using Neumann boundary conditions, then before the solver is called, the outerface boundary flux data must be set for the Neumann conditions. The fluxes argument gives the patch data index of this flux data.

The mixed boundary type is for a mixture of Dirichlet and Neumann boundary conditions are used at the physical domain boundary. The fluxes argument gives the patch data index of the outerface data that specifies the flux data for the Neumann conditions. The flags array is an outerface data array of integer flags that specifies whether Dirichlet (flag == zero) or Neumann (flag == one) conditions are to be used at a particular cell boundary face. Note that the flag data must be set before the matrix entries can be computed and the flux data must be set before the solver is called. The bdry_types argument can be used if the boundary conditions are mixed but one or more of the faces of the physical boundary are entirely either Dirichlet or Neumann boundaries. The bdry_types argument should be an array of 2*DIM integers, specifying the boundary conditions on each side of the physical domain. It should be ordered {x_lo, x_hi, y_lo, y_hi, z_lo, z_hi}, with the values for each face being 0 for Dirichlet conditions, 1 for Neumann conditions, and 2 for mixed boundary conditions. The bdry_type argument is never required, but if used it can sometimes make the PoissonHYPRESolver class more efficient.

◆ setBcObject()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::setBcObject ( const RobinBcCoefStrategy< DIM > * bc_object )

◆ setCoarsestLevelSolverTolerance()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::setCoarsestLevelSolverTolerance ( double tol )

If the coarse level solver requires a tolerance (currently, they all do), the specified value is used.

◆ setCoarsestLevelSolverMaxIterations()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::setCoarsestLevelSolverMaxIterations ( int max_iterations )

If the coarse level solver requires a max iteration limit (currently, they all do), the specified value is used.

◆ setCoarseFineDiscretization()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::setCoarseFineDiscretization ( const std::string & coarsefine_method )

Specify the op_name string which will be passed to xfer::Geometry<DIM>::lookupRefineOperator() to get the operator for setting fine grid ghost cells from the coarse grid. Note that chosing this operator implicitly choses the discretization method at the coarse-fine boundary.

There is one important instance where this string is not passed to xfer::Geometry<DIM>::lookupRefineOperator(). If this variable is set to "Ewing", a constant refinement method is used along with Ewing's correction. For a reference to the correction method, see "Local Refinement Techniques for Elliptic Problems on Cell-Centered Grids, I. Error Analysis", Mathematics of Computation, Vol. 56, No. 194, April 1991, pp. 437-461.

Parameters

coarsefine_method String selecting the coarse-fine discretization method.

◆ setProlongationMethod()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::setProlongationMethod ( const std::string & prolongation_method )

Specify the op_name string which will be passed to xfer::Geometry<DIM>::lookupRefineOperator() to get the operator for prolonging the coarse-grid correction.

By default, "CONSTANT_REFINE" is used. "LINEAR_REFINE" seems to to lead to faster convergence, but it does NOT satisfy the Galerkin condition.

Prolonging using linear refinement requires a Robin bc coefficient implementation that is capable of delivering coefficients for non-hierarchy data, because linear refinement requires boundary conditions to be set on temporary levels.

Parameters

prolongation_method String selecting the coarse-fine discretization method.

◆ setPresmoothingSweeps()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::setPresmoothingSweeps ( int num_pre_sweeps )

Presmoothing is applied during the fine-to-coarse phase of the iteration. The default is to use one sweep.

Parameters

num_pre_sweeps Number of presmoothing sweeps

◆ setPostsmoothingSweeps()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::setPostsmoothingSweeps ( int num_post_sweeps )

Postsmoothing is applied during the coarse-to-fine phase of the iteration. The default is to use one sweep.

Parameters

num_post_sweeps Number of postsmoothing sweeps

◆ setMaxCycles()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::setMaxCycles ( int max_cycles )

◆ setResidualTolerance()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::setResidualTolerance ( double residual_tol )

If you want the prescribed maximum number of cycles to always be taken, set the residual tolerance to a negative number.

◆ initializeSolverState()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::initializeSolverState	(	const int	solution,
		const int	rhs,
		tbox::Pointer< hier::PatchHierarchy< DIM > >	hierarchy,
		const int	coarse_level = `-1`,
		const int	fine_level = `-1`
	)

In the interest of efficiency, this class may prepare and cache some hierarchy-dependent objects. Though it is not required, initializing the solver state makes for greater efficiency when you are doing multiple solves on the same system of equation. If you do not initialize the state, it is initialized and deallocated each time you call solveSystem(const int, const int). The state must be reinitialized if the hierarchy or a boundary condition type changes.

To unset the data set in this function, see deallocateSolverState().

The solution and rhs patch data indices in the argument list are used to determine the form of the data you plan to use in the solve. They need not be the same data you solve on, but they should be similar. Both must represent cell-centered double data. The solution must have at least one ghost cell width, though this is not checked in the initialize phase, because data is not required yet.

Parameters

solution	solution patch data index for u
rhs	right hand side patch data index for f
hierarchy	The patch hierarchy to solve on
coarse_level	The coarsest level in the solve
fine_level	The finest level in the solve

◆ deallocateSolverState()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::deallocateSolverState ( )

Remove all hierarchy-dependent data set by initializeSolverState. It is safe to call deallocateSolverState() even state is already deallocated, but nothing is done in that case.

See also: initializeSolverState()

◆ getNumberOfIterations()

template<int DIM>

int SAMRAI::solv::CellPoissonFACSolver< DIM >::getNumberOfIterations ( ) const

◆ getConvergenceFactors()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::getConvergenceFactors	(	double &	avg_factor,
		double &	final_factor
	)		const

Parameters

avg_factor	average convergence factor over current FAC cycles
final_factor	convergence factor of the last FAC cycle

◆ getResidualNorm()

template<int DIM>

double SAMRAI::solv::CellPoissonFACSolver< DIM >::getResidualNorm ( ) const

The norm return value is computed as the maximum norm over all patch levels involved in the solve. The value corresponds to the norm applied in the user-defined residual computation.

The latest computed norm is the one returned.

◆ getFromInput()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::getFromInput ( tbox::Pointer< tbox::Database > database )

private

See the class description for the parameters that can be set from a database.

Parameters

database Input database. If a NULL pointer is given, nothing is done.

◆ createVectorWrappers()

template<int DIM>

void SAMRAI::solv::CellPoissonFACSolver< DIM >::createVectorWrappers	(	int	u,
		int	f
	)

private

◆ destroyVectorWrappers()

template<int DIM>

template<int DIM>

int SAMRAI::solv::CellPoissonFACSolver< DIM >::s_instance_counter

staticprivate

The documentation for this class was generated from the following file:

/samrai/include/CellPoissonFACSolver.h

Public Member Functions

Functions to get data on last solve.

Detailed Description

template<int DIM> class SAMRAI::solv::CellPoissonFACSolver< DIM >

Constructor & Destructor Documentation

◆ CellPoissonFACSolver()

◆ ~CellPoissonFACSolver()

Member Function Documentation

◆ enableLogging()

◆ solveSystem() [1/2]

◆ solveSystem() [2/2]

◆ setBoundaries()

◆ setBcObject()

◆ setDPatchDataId()

◆ setDConstant()

◆ setCPatchDataId()

◆ setCConstant()

◆ setCoarsestLevelSolverChoice()

◆ setCoarsestLevelSolverTolerance()

◆ setCoarsestLevelSolverMaxIterations()

◆ setCoarseFineDiscretization()

◆ setProlongationMethod()

◆ setPresmoothingSweeps()

◆ setPostsmoothingSweeps()

◆ setMaxCycles()

◆ setResidualTolerance()

◆ initializeSolverState()

◆ deallocateSolverState()

◆ getNumberOfIterations()

◆ getConvergenceFactors()

◆ getResidualNorm()

◆ getFromInput()

◆ createVectorWrappers()

◆ destroyVectorWrappers()

Member Data Documentation

◆ d_object_name

◆ d_poisson_spec

◆ d_fac_ops

◆ d_fac_precond

◆ d_bc_object

◆ d_simple_bc

◆ d_hierarchy

◆ d_ln_min

◆ d_ln_max

◆ d_context

◆ d_uv

◆ d_fv

◆ d_solver_is_initialized

◆ d_enable_logging

◆ s_weight_id

◆ s_instance_counter

template<int DIM>
class SAMRAI::solv::CellPoissonFACSolver< DIM >