Implements the FAC iterative solution procedure for a linear system of equations, Au=f, defined on some subset of levels in an AMR patch hierarchy. More...

#include <ibtk/FACPreconditioner.h>

Inheritance diagram for SAMRAI::solv::FACPreconditioner< DIM >:

[legend]

Public Member Functions
	FACPreconditioner (const std::string &name, FACOperatorStrategy< DIM > &user_ops, tbox::Pointer< tbox::Database > database=NULL)

virtual	~FACPreconditioner ()

bool	solveSystem (SAMRAIVectorReal< DIM, double > &solution, SAMRAIVectorReal< DIM, double > &rhs)
	Solve linear system Au=f using the FAC algorithm. More...

void	initializeSolverState (const SAMRAIVectorReal< DIM, double > &solution, const SAMRAIVectorReal< DIM, double > &rhs)
	Compute hierarchy-dependent data required for solving. More...

void	deallocateSolverState ()
	Remove all hierarchy-dependent data computed by initializeSolverState() More...

bool	checkVectorStateCompatibility (const SAMRAIVectorReal< DIM, double > &solution, const SAMRAIVectorReal< DIM, double > &rhs) const
	Check compatibility of vectors with existing solver state. More...

Functions to set solving parameters.
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, double relative_residual_tol=-1.0)
	Set the residual tolerance for stopping. More...

void	setAlgorithmChoice (const std::string &choice)
	Set the choice of FAC cycling algorithm to use. More...

void	enableLogging (bool enabled=true)
	Enable or disable logging. More...

Functions to get data on last solve.
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 convergance rates of the last (or current if there is one) FAC solve. More...

double	getNetConvergenceFactor () const
	Get the net convergance rate of the last (or current if there is one) FAC solve. More...

double	getAvgConvergenceFactor () const
	Get the average convergance rates of the last (or current if there is one) FAC solve. More...

double	getFinalConvergenceFactor () const
	Get the final convergance 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...

virtual void	printClassData (std::ostream &os) const
	Print data members for debugging. More...

Private Attributes
Solution vector-dependent data.
These variables are set by initializeSolverState and deallocateSolverState and used only during the solve process.
tbox::Pointer< hier::PatchHierarchy< DIM > >	d_patch_hierarchy

int	d_coarsest_ln

int	d_finest_ln

tbox::Pointer< SAMRAIVectorReal< DIM, double > >	d_residual_vector
	Clone of solution vector to store residual. More...

tbox::Pointer< SAMRAIVectorReal< DIM, double > >	d_tmp_residual
	Clone of solution vector to store temporary residual. More...

tbox::Pointer< SAMRAIVectorReal< DIM, double > >	d_error_vector
	Error vector. More...

tbox::Pointer< SAMRAIVectorReal< DIM, double > >	d_tmp_error
	Error vector for homogeneous boundary condition problem.. More...

Parameters for FAC iteration.
int	d_max_iterations

double	d_residual_tolerance

double	d_relative_residual_tolerance

int	d_presmoothing_sweeps

int	d_postsmoothing_sweeps

std::string	d_algorithm_choice

Status quantitities for FAC iteration.
int	d_number_iterations

double	d_residual_norm

double	d_rhs_norm
	Norm of RHS, for computing relative residual. More...

tbox::Array< double >	d_convergence_factor
	Convergence factor stack. More...

double	d_avg_convergence_factor

double	d_net_convergence_factor

bool	d_do_log
	Flag stating whether to log. More...

tbox::Array< tbox::Pointer< math::HierarchyDataOpsReal< DIM, double > > >	d_controlled_level_ops
	Objects facilitating operations over a specific range of levels. More...

tbox::Pointer< tbox::Timer >	t_solve_system

Functions not implemented:
std::string	d_object_name
	Name of this FAC solver object. More...

FACOperatorStrategy< DIM > &	d_fac_operator
	Object providing problem-specific routines. More...

	FACPreconditioner (const FACPreconditioner< DIM > &)

void	operator= (const FACPreconditioner< DIM > &)

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

double	computeFullCompositeResidual (SAMRAIVectorReal< DIM, double > &residual, SAMRAIVectorReal< DIM, double > &solution, SAMRAIVectorReal< DIM, double > &rhs)
	Compute composite residual on all levels and returns residual norm. More...

void	facCycle_Recursive (SAMRAIVectorReal< DIM, double > &error, SAMRAIVectorReal< DIM, double > &residual, SAMRAIVectorReal< DIM, double > &solution, int lmax, int lmin, int ln)
	Perform recursive FAC cycle iteration. More...

void	facCycle_McCormick (SAMRAIVectorReal< DIM, double > &error, SAMRAIVectorReal< DIM, double > &residual, SAMRAIVectorReal< DIM, double > &solution, int lmax, int lmin, int ln)
	Perform recursive FAC cycle iteration from McCormick. More...

void	facCycle (SAMRAIVectorReal< DIM, double > &error, SAMRAIVectorReal< DIM, double > &residual, SAMRAIVectorReal< DIM, double > &solution, int lmax, int lmin)
	Perform FAC cycle iteration. More...

Detailed Description

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

The solution is found by applying an FAC algorithm to the composite grid represented in the hierarchy. After each FAC cycle the norm of the residual will be computed over all levels involved. The FAC iteration will stop when either the maximum number of iterations is reached, or the residual norm on all levels is below the given tolerance.

The user must perform the following steps to use the FAC solver:

Create a FACPreconditioner<DIM>, providing a valid concrete FACOperatorStrategy<DIM> object.
Set the stopping criteria using the setStoppingParameters() function.
Set the number of smooting sweeps using the setSmoothingSweeps() function. This is optional; if not used, the default is one sweep in each case.
Enable logging to record the FAC residual norms during the FAC itertion using the setFACLogFlag() function. This is optional; the default is to turn logging off. When loggin is turned on, the default mode is to send this information to the application log file (i.e., plog).
Invoke the FAC iteration process by calling solveSystem(), providing the vectors u and f, defined on a patch hierarchy containing the desired range of levels.
After solving, get solver statistics by viewing the log information and calling getNumberOfIterations(), getResidualNorm() functions if desired.

Constructor & Destructor Documentation

◆ FACPreconditioner() [1/2]

template<int DIM>

SAMRAI::solv::FACPreconditioner< DIM >::FACPreconditioner	(	const std::string &	name,
		FACOperatorStrategy< DIM > &	user_ops,
		tbox::Pointer< tbox::Database >	database = `NULL`
	)

Constructor.

Parameters

name	Object name
user_ops	Reference to user-specified FAC operator
database	Input database with initialization parameters

◆ ~FACPreconditioner()

template<int DIM>

virtual SAMRAI::solv::FACPreconditioner< DIM >::~FACPreconditioner ( )

virtual

Virtual destructor.

◆ FACPreconditioner() [2/2]

template<int DIM>

SAMRAI::solv::FACPreconditioner< DIM >::FACPreconditioner ( const FACPreconditioner< DIM > & )

private

Member Function Documentation

◆ solveSystem()

template<int DIM>

bool SAMRAI::solv::FACPreconditioner< DIM >::solveSystem	(	SAMRAIVectorReal< DIM, double > &	solution,
		SAMRAIVectorReal< DIM, double > &	rhs
	)

The return value is true if the solver converged and false otherwise. The problem-specific portions of the FAC procedure, including the definitions of A are provided by the FACOperatorStrategy<DIM> object passed to the constructor. More information about the iteration can be found by calling the functions getNumberOfIterations() and getResidualNorm() and by looking at the log information.

Before calling this function, the form of 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 in these vectors (that will be used by the FACOperatorStrategy implementation) should be allocated. Thus, the user is responsible for managing the storage for the solution and right-hand-side.

Conditions on arguments:

vectors solution and rhs must have same hierarchy
vectors solution and rhs must have same variables (except that solution can–and should–have enough ghost cells for computation).

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

Parameters

solution	solution vector u
rhs	right hand side vector f

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

Returns: whether solver converged to specified level

See also: initializeSolverState

◆ initializeSolverState()

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::initializeSolverState	(	const SAMRAIVectorReal< DIM, double > &	solution,
		const SAMRAIVectorReal< DIM, double > &	rhs
	)

By default, the solveSystem() method computes some required hierarchy-dependent data before solving and removes that data after the solve. For multiple solves using the same hierarchy configuration, it is more efficient to manually compute, using initializeSolverState(), and remove, using deallocateSolverState(), the hierarchy-dependent data so that it is not done inside solveSystem(). If solveSystem() detects that the solver state is already initialized, it will NOT change the state.

The vector arguments for solveSystem() need not match those for initializeSolverState(). However, there must be a certain degree of similarity, including

hierarchy configuration (hierarchy pointer and level range)
number, type and alignment of vector component data
ghost cell width of data in the solution vector

When assertion checking is enabled, limited checking is done by solveSystem() to help ensure that of the vectors passed to solveSystem() is compatible with the existing state.

It is important to remember to reinitialize the solver state when your hierarchy configuration changes.

It is safe to initializeSolverState() when the state is already initialized (the state is deallocated and reinitialized).

Conditions on arguments:

solution and rhs must have same hierarchy
solution and rhs must have same structure, depth, etc. (except that u can–and should–have enough ghost cells for computation).
coarsest_ln through finest_ln must exist in u.

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

After setting data for the current object, this function calls the operator's corresponding function, FACOperatorStrategy<DIM>::initializeOperatorState() so that the operator object can take steps to remain in sync.

Parameters

solution	solution vector u
rhs	right hand side vector f

◆ deallocateSolverState()

template<int DIM>

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

Remove all hierarchy-dependent data set by initializeSolverState(). It is safe to call deallocateSolverState() even state is already deallocated.

After deallocating data for the current object, this function calls the operator's corresponding function, FACOperatorStrategy<DIM>::deallocateOperatorState() so that the operator object can take steps to remain in sync.

See also: initializeSolverState

◆ checkVectorStateCompatibility()

template<int DIM>

bool SAMRAI::solv::FACPreconditioner< DIM >::checkVectorStateCompatibility	(	const SAMRAIVectorReal< DIM, double > &	solution,
		const SAMRAIVectorReal< DIM, double > &	rhs
	)		const

Check whether the solution and residual vectors given are compatible with the existing solver state (solver state must be initialized). Compatibility means that the vectors are sufficiently similar with the vectors with which the state are initialized. Compatibility implies that the vectors may be used in solveSystem().

The checking is not perfect! Due to the possibility of user-defined patch data, data-dependent checks cannot be performed. It is possible that a false compatibility is returned.

Returns: true if vectors are compatible with existing state

◆ setPresmoothingSweeps()

template<int DIM>

void SAMRAI::solv::FACPreconditioner< 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::FACPreconditioner< 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::FACPreconditioner< DIM >::setMaxCycles ( int max_cycles )

◆ setResidualTolerance()

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::setResidualTolerance	(	double	residual_tol,
		double	relative_residual_tol = `-1.0`
	)

The solution is considered converged if ||b-Ax|| <= residual_tol or ||b-Ax|| <= relative_residual_tol*||b||.

If you want the prescribed maximum number of cycles to always be taken, set both residual tolerances to negative numbers.

◆ setAlgorithmChoice()

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::setAlgorithmChoice ( const std::string & choice )

For developer experimentation use only. All others should use the default choice.

◆ enableLogging()

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::enableLogging ( bool enabled = true )

Set streams to NULL to turn off output.

Parameters

enabled Logging state. true=on, false=off.

◆ getNumberOfIterations()

template<int DIM>

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

◆ getConvergenceFactors()

template<int DIM>

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

The convergence factor is the factor to which the residual has been reduced. The final factor is that from the last FAC cycle.

Parameters

avg_factor	average convergence factor over FAC cycles from last solve.
final_factor	convergence factor of the last FAC cycle

◆ getNetConvergenceFactor()

template<int DIM>

double SAMRAI::solv::FACPreconditioner< DIM >::getNetConvergenceFactor ( ) const

The net factor is the factor to which the residual has been reduced by the FAC cycles. It is (current residual)/( initial residual + epsilon), so it may not be accurate if the initial residual is very small.

◆ getAvgConvergenceFactor()

template<int DIM>

double SAMRAI::solv::FACPreconditioner< DIM >::getAvgConvergenceFactor ( ) const

The average factor is the net factor to the power of 1/(number of FAC cycles). It may not be accurate if the initial residual is very small.

◆ getFinalConvergenceFactor()

template<int DIM>

double SAMRAI::solv::FACPreconditioner< DIM >::getFinalConvergenceFactor ( ) const

The final factor is the factor to which the residual has been reduced by the last FAC cycle.

◆ getResidualNorm()

template<int DIM>

double SAMRAI::solv::FACPreconditioner< 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.

◆ printClassData()

template<int DIM>

virtual void SAMRAI::solv::FACPreconditioner< DIM >::printClassData ( std::ostream & os ) const

virtual

◆ operator=()

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::operator= ( const FACPreconditioner< DIM > & )

private

◆ getFromInput()

template<int DIM>

void SAMRAI::solv::FACPreconditioner< 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.

◆ computeFullCompositeResidual()

template<int DIM>

double SAMRAI::solv::FACPreconditioner< DIM >::computeFullCompositeResidual	(	SAMRAIVectorReal< DIM, double > &	residual,
		SAMRAIVectorReal< DIM, double > &	solution,
		SAMRAIVectorReal< DIM, double > &	rhs
	)

private

Uses the FACOperatorStrategy<DIM>::computeResidualOnLevel() function provided by the operator object to compute per level residual. Perform coarsen residual operation to get fine-grid approximation of residual on to coarse grid.

The residual is r=f-Au.

Parameters

residual	residual vector r
solution	solution vector u
rhs	right hand side vector f

◆ facCycle_Recursive()

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::facCycle_Recursive	(	SAMRAIVectorReal< DIM, double > &	error,
		SAMRAIVectorReal< DIM, double > &	residual,
		SAMRAIVectorReal< DIM, double > &	solution,
		int	lmax,
		int	lmin,
		int	ln
	)

private

Do one FAC iteration of Ae=r system. The FAC algorithm modifies Ae=r on coarser levels so that each coarser level solves for the change in error of the next finer level, as is expected in the FAC algorithm.

The level number range lmax to lmin must exist in the vectors e and r.

Assumes:

The error vector is preset to 0 on levels lmin to ln.

Parameters

error	error vector e
residual	residual vector r
solution	solution vector u
lmax	finest level number
lmin	coarsest level number
ln	current level number

◆ facCycle_McCormick()

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::facCycle_McCormick	(	SAMRAIVectorReal< DIM, double > &	error,
		SAMRAIVectorReal< DIM, double > &	residual,
		SAMRAIVectorReal< DIM, double > &	solution,
		int	lmax,
		int	lmin,
		int	ln
	)

private

Do one FAC iteration of Ae=r system. The FAC algorithm modifies Ae=r on coarser levels so that each coarser level solves for the change in error of the next finer level, as is expected in the FAC algorithm.

The level number range lmax to lmin must exist in the vectors e and r.

Assumes:

The error vector is preset to 0 on levels lmin to ln.

Parameters

error	error vector e
residual	residual vector r
solution	solution vector u
lmax	finest level number
lmin	coarsest level number
ln	current level number

◆ facCycle()

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::facCycle	(	SAMRAIVectorReal< DIM, double > &	error,
		SAMRAIVectorReal< DIM, double > &	residual,
		SAMRAIVectorReal< DIM, double > &	solution,
		int	lmax,
		int	lmin
	)

private

Do one FAC iteration of Ae=r system. The FAC algorithm modifies Ae=r on coarser levels so that each coarser level solves for the change in error of the next finer level, as is expected in the FAC algorithm.

The level number range lmax to lmin must exist in the vectors e and r.

Assumes:

The error vector is preset to 0.

Member Data Documentation

◆ d_object_name

template<int DIM>

std::string SAMRAI::solv::FACPreconditioner< DIM >::d_object_name

private

◆ d_fac_operator

◆ d_avg_convergence_factor

template<int DIM>

double SAMRAI::solv::FACPreconditioner< DIM >::d_avg_convergence_factor

private

The average convergence factor computed from the current values in d_convergence_factor.

◆ d_net_convergence_factor

template<int DIM>

double SAMRAI::solv::FACPreconditioner< DIM >::d_net_convergence_factor

private

The net convergence factor computed from the current values in d_convergence_factor.

◆ d_do_log

template<int DIM>

bool SAMRAI::solv::FACPreconditioner< DIM >::d_do_log

private

◆ d_controlled_level_ops

template<int DIM>

tbox::Array< tbox::Pointer< math::HierarchyDataOpsReal<DIM,double> > > SAMRAI::solv::FACPreconditioner< DIM >::d_controlled_level_ops

private

◆ t_solve_system

template<int DIM>

tbox::Pointer<tbox::Timer> SAMRAI::solv::FACPreconditioner< DIM >::t_solve_system

private

Timers for performance measurement.

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

ibtk/include/ibtk/FACPreconditioner.h

Public Member Functions

Private Attributes

Functions not implemented:

Detailed Description

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

Constructor & Destructor Documentation

◆ FACPreconditioner() [1/2]

◆ ~FACPreconditioner()

◆ FACPreconditioner() [2/2]

Member Function Documentation

◆ solveSystem()

◆ initializeSolverState()

◆ deallocateSolverState()

◆ checkVectorStateCompatibility()

◆ setPresmoothingSweeps()

◆ setPostsmoothingSweeps()

◆ setMaxCycles()

◆ setResidualTolerance()

◆ setAlgorithmChoice()

◆ enableLogging()

◆ getNumberOfIterations()

◆ getConvergenceFactors()

◆ getNetConvergenceFactor()

◆ getAvgConvergenceFactor()

◆ getFinalConvergenceFactor()

◆ getResidualNorm()

◆ printClassData()

◆ operator=()

◆ getFromInput()

◆ computeFullCompositeResidual()

◆ facCycle_Recursive()

◆ facCycle_McCormick()

◆ facCycle()

Member Data Documentation

◆ d_object_name

◆ d_fac_operator

◆ d_patch_hierarchy

◆ d_coarsest_ln

◆ d_finest_ln

◆ d_residual_vector

◆ d_tmp_residual

◆ d_error_vector

◆ d_tmp_error

◆ d_max_iterations

◆ d_residual_tolerance

◆ d_relative_residual_tolerance

◆ d_presmoothing_sweeps

◆ d_postsmoothing_sweeps

◆ d_algorithm_choice

◆ d_number_iterations

◆ d_residual_norm

◆ d_rhs_norm

◆ d_convergence_factor

◆ d_avg_convergence_factor

◆ d_net_convergence_factor

◆ d_do_log

◆ d_controlled_level_ops

◆ t_solve_system

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