SAMRAI::solv::FACPreconditioner< DIM > Class Template Reference

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 <source/solvers/FAC/FACPreconditioner.h>

List of all members.

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.
void	initializeSolverState (const SAMRAIVectorReal< DIM, double > &solution, const SAMRAIVectorReal< DIM, double > &rhs)
	Compute hierarchy-dependent data required for solving.
void	deallocateSolverState ()
	Remove all hierarchy-dependent data computed by initializeSolverState().
bool	checkVectorStateCompatibility (const SAMRAIVectorReal< DIM, double > &solution, const SAMRAIVectorReal< DIM, double > &rhs) const
	Check compatibility of vectors with existing solver state.
virtual void	printClassData (std::ostream &os) const
	Print data members for debugging.
Functions to set solving parameters.
void	setPresmoothingSweeps (int num_pre_sweeps)
	Set the number of pre-smoothing sweeps during FAC iteration process.
void	setPostsmoothingSweeps (int num_post_sweeps)
	Set the number of post-smoothing sweeps during FAC iteration process.
void	setMaxCycles (int max_cycles)
	Set the max number of iterations (cycles) to use per solve.
void	setResidualTolerance (double residual_tol, double relative_residual_tol=-1.0)
	Set the residual tolerance for stopping.
void	setAlgorithmChoice (const std::string &choice)
	Set the choice of FAC cycling algorithm to use.
void	enableLogging (bool enabled=true)
	Enable or disable logging.
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.
void	getConvergenceFactors (double &avg_factor, double &final_factor) const
	Get convergance rates of the last (or current if there is one) FAC solve.
double	getNetConvergenceFactor () const
	Get the net convergance rate of the last (or current if there is one) FAC solve.
double	getAvgConvergenceFactor () const
	Get the average convergance rates of the last (or current if there is one) FAC solve.
double	getFinalConvergenceFactor () const
	Get the final convergance rate of the last (or current if there is one) FAC solve.
double	getResidualNorm () const
	Return residual norm from the just-completed FAC iteration.

---

Detailed Description

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

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.

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:

1. Create a FACPreconditioner<DIM>, providing a valid concrete FACOperatorStrategy<DIM> object.
2. Set the stopping criteria using the setStoppingParameters() function.
3. Set the number of smooting sweeps using the setSmoothingSweeps() function. This is optional; if not used, the default is one sweep in each case.
4. 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).
5. 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.
6. After solving, get solver statistics by viewing the log information and calling getNumberOfIterations(), getResidualNorm() functions if desired.

---

Constructor & Destructor Documentation

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

template<int DIM>

SAMRAI::solv::FACPreconditioner< DIM >::~FACPreconditioner

(

)

[virtual]

Virtual destructor.

---

Member Function Documentation

template<int DIM>

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

Solve linear system Au=f using the FAC algorithm.

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

template<int DIM>

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

Compute hierarchy-dependent data required for solving.

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

template<int DIM>

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

(

)

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

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

template<int DIM>

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

Check compatibility of vectors with existing solver state.

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

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::setPresmoothingSweeps

(

int

num_pre_sweeps

)

[inline]

Set the number of pre-smoothing sweeps during FAC iteration process.

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

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::setPostsmoothingSweeps

(

int

num_post_sweeps

)

[inline]

Set the number of post-smoothing sweeps during FAC iteration process.

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

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::setMaxCycles

(

int

max_cycles

)

[inline]

Set the max number of iterations (cycles) to use per solve.

template<int DIM>

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

Set the residual tolerance for stopping.

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.

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::setAlgorithmChoice

(

const std::string &

choice

)

[inline]

Set the choice of FAC cycling algorithm to use.

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

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::enableLogging

(

bool

enabled = true

)

[inline]

Enable or disable logging.

Set streams to NULL to turn off output.

Parameters:

enabled

Logging state. true=on, false=off.

template<int DIM>

int SAMRAI::solv::FACPreconditioner< DIM >::getNumberOfIterations

(

)

const [inline]

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

template<int DIM>

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

Get convergance rates of the last (or current if there is one) FAC solve.

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

template<int DIM>

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

(

)

const [inline]

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

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.

template<int DIM>

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

(

)

const [inline]

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

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.

template<int DIM>

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

(

)

const [inline]

Get the final convergance rate of the last (or current if there is one) FAC solve.

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

template<int DIM>

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

(

)

const [inline]

Return residual norm from the just-completed FAC iteration.

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.

template<int DIM>

void SAMRAI::solv::FACPreconditioner< DIM >::printClassData

(

std::ostream &

os

)

const [virtual]

Print data members for debugging.

---

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

• source/solvers/FAC/FACPreconditioner.h
• source/solvers/FAC/FACPreconditioner.C
• source/solvers/FAC/FACPreconditioner.I

---