Defines a Strategy pattern interface to problem-specific operations needed to implement the FAC preconditioner algorithm. More...

#include <FACOperatorStrategy.h>

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

[legend]

Public Member Functions
	FACOperatorStrategy ()
	Empty constructor. More...

virtual	~FACOperatorStrategy ()
	Virtual destructor. More...

Operator-dependent virtual methods
virtual void	restrictSolution (const SAMRAIVectorReal< DIM, double > &source, SAMRAIVectorReal< DIM, double > &dest, int dest_ln)=0
	Restrict the solution quantity to the specified level from the next finer level. More...

virtual void	restrictResidual (const SAMRAIVectorReal< DIM, double > &source, SAMRAIVectorReal< DIM, double > &dest, int dest_ln)=0
	Restrict the residual quantity to the specified level from the next finer level. More...

virtual void	prolongErrorAndCorrect (const SAMRAIVectorReal< DIM, double > &source, SAMRAIVectorReal< DIM, double > &dest, int dest_ln)=0
	Prolong the error quantity to the specified level from the next coarser level and apply the correction to the fine-level error. More...

virtual void	smoothError (SAMRAIVectorReal< DIM, double > &error, const SAMRAIVectorReal< DIM, double > &residual, int ln, int num_sweeps)=0
	Perform a given number of relaxations on the error. More...

virtual int	solveCoarsestLevel (SAMRAIVectorReal< DIM, double > &error, const SAMRAIVectorReal< DIM, double > &residual, int coarsest_ln)=0
	Solve the residual equation Ae=r on the coarsest level in the FAC iteration. More...

virtual void	computeCompositeResidualOnLevel (SAMRAIVectorReal< DIM, double > &residual, const SAMRAIVectorReal< DIM, double > &solution, const SAMRAIVectorReal< DIM, double > &rhs, int ln, bool error_equation_indicator)=0
	Compute composite grid residual on a single level. More...

virtual double	computeResidualNorm (const SAMRAIVectorReal< DIM, double > &residual, int fine_ln, int coarse_ln)=0
	Compute the norm of the residual quantity. More...

virtual void	postprocessOneCycle (int fac_cycle_num, const SAMRAIVectorReal< DIM, double > &current_soln, const SAMRAIVectorReal< DIM, double > &residual)
	Regular call back routine to be called after each FAC cycle. More...

virtual void	initializeOperatorState (const SAMRAIVectorReal< DIM, double > &solution, const SAMRAIVectorReal< DIM, double > &rhs)
	Compute hierarchy-dependent data if any is required. More...

virtual void	deallocateOperatorState ()
	Remove all hierarchy-dependent data. More...

Detailed Description

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

The FACPreconditioner<DIM> constructor accepts a concrete implementation of this interface and calls the concrete implementations of the virtual functions declared herein during the solution process.

All vector arguments in these interfaces are guaranteed to be either the vectors given to in FACPreconditioner<DIM>::solveSystem() or FACPreconditioner<DIM>::initializeSolverState() or vectors cloned from them.

See also: solv::FACPreconditioner

Constructor & Destructor Documentation

◆ FACOperatorStrategy()

template<int DIM>

SAMRAI::solv::FACOperatorStrategy< DIM >::FACOperatorStrategy ( )

◆ ~FACOperatorStrategy()

template<int DIM>

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

virtual

Member Function Documentation

◆ restrictSolution()

template<int DIM>

virtual void SAMRAI::solv::FACOperatorStrategy< DIM >::restrictSolution	(	const SAMRAIVectorReal< DIM, double > &	source,
		SAMRAIVectorReal< DIM, double > &	dest,
		int	dest_ln
	)

pure virtual

Restrict the residual data to level dest_ln in the destination vector d, from level dest_ln+1 in the source vector s.

Can assume:

dest_ln is not the finest level in the range being solved.
corresponding solution has been computed on level dest_ln+1.
the source and destination residual vectors (s and d) may or may not be the same. (This function must work in either case.)

Upon return from this function, the solution on the refined region of the coarse level will represent the coarsened version of the fine solution in a manner that is consistent with the linear system approximation on the composite grid. This function must not change the solution values anywhere except on level dest_ln of the destination vector.

The source and destination vectors may be the same.

Parameters

source	source solution
dest	destination solution
dest_ln	destination level number

Implemented in SAMRAI::solv::CellPoissonFACOps< DIM >.

◆ restrictResidual()

template<int DIM>

virtual void SAMRAI::solv::FACOperatorStrategy< DIM >::restrictResidual	(	const SAMRAIVectorReal< DIM, double > &	source,
		SAMRAIVectorReal< DIM, double > &	dest,
		int	dest_ln
	)

pure virtual

Restrict the residual data to level dest_ln in the destination vector d, from level dest_ln+1 in the source vector s.

Can assume:

dest_ln is not the finest level in the range being solved.
correspnding residual has been computed on level dest_ln+1.
the source and destination residual vectors (s and d) may or may not be the same. (This function must work in either case.)

Upon return from this function, the residual on the refined region of the coarse level will represent the coarsened version of the fine residual in a manner that is consistent with the linear system approximation on the composite grid. This function must not change the residual values anywhere except on level dest_ln of the destination vector.

The source and destination vectors may be the same.

Parameters

source	source residual
dest	destination residual
dest_ln	destination level number

Implemented in SAMRAI::solv::CellPoissonFACOps< DIM >.

◆ prolongErrorAndCorrect()

template<int DIM>

virtual void SAMRAI::solv::FACOperatorStrategy< DIM >::prolongErrorAndCorrect	(	const SAMRAIVectorReal< DIM, double > &	source,
		SAMRAIVectorReal< DIM, double > &	dest,
		int	dest_ln
	)

pure virtual

On the part of the coarse level that does not overlap the fine level, the error is the corection to Au=f.

On the part of the coarse level that does overlap the fine level, the error is the corection to Ae=r of the fine level.

This function should apply the coarse-level correction to the fine level, that is

\[ e^{fine} \leftarrow e^{fine} + I^{fine}_{coarse} e^{coarse} \]

Note: You probably have to store the refined error in a temporary location before adding it to the current error.

The array of boundary information contains a description of the coarse-fine level boundary for each patch on the level; the boundary information for patch N is obtained as the N-th element in the array, coarse_fine_boundary[N].

Upon return from this function, the error on the fine level must represent the correction to the solution on that level. Also, this function must not change the error values on the coarse level.

The source and destination vectors may be the same.

Parameters

source	source error vector
dest	destination error vector
dest_ln	destination level number of data transfer

Implemented in SAMRAI::solv::CellPoissonFACOps< DIM >.

◆ smoothError()

template<int DIM>

virtual void SAMRAI::solv::FACOperatorStrategy< DIM >::smoothError	(	SAMRAIVectorReal< DIM, double > &	error,
		const SAMRAIVectorReal< DIM, double > &	residual,
		int	ln,
		int	num_sweeps
	)

pure virtual

Relax the residual equation Ae=r by applying the given number of smoothing sweeps on the specified level. The relaxation may ignore the possible existence of finer levels on a given level.

The array of boundary information contains a description of the coarse-fine level boundary for each patch on the level; the boundary information for patch N is obtained as the N-th element in the array, coarse_fine_boundary[N].

May assume:

If intermediate data from level l+1 is needed (for example, to match flux at coarse-fine boundaries), that data is already computed and stored on level l+1.
The error in the next finer level has been computed and stored there.

Steps for each iteration.

Fill ghost boundaries
Compute intermediate data (if needed) and coarsen intermediate data stored in level l+1 (if needed).
Perform relaxation step (update e toward a better approximation).

Final step before leaving function.

If needed, compute and store intermediate data for next coarser level l-1.

Parameters

error	error vector
residual	residual vector
ln	level number
num_sweeps	number of sweeps

Implemented in SAMRAI::solv::CellPoissonFACOps< DIM >.

◆ solveCoarsestLevel()

template<int DIM>

virtual int SAMRAI::solv::FACOperatorStrategy< DIM >::solveCoarsestLevel	(	SAMRAIVectorReal< DIM, double > &	error,
		const SAMRAIVectorReal< DIM, double > &	residual,
		int	coarsest_ln
	)

pure virtual

Here e is the given error quantity and r is the given residual quantity. The array of boundary information contains a description of the coarse-fine level boundary for each patch on the level; the boundary information for patch N is obtained as the N-th element in the array, coarse_fine_boundary[N].

This routine must fill boundary values for given solution quantity on all patches on the specified level before the solve is performed.

Parameters

error	error vector
residual	residual vector
coarsest_ln	coarsest level number

Returns: 0 if solver converged to specified level, nonzero otherwise.

Implemented in SAMRAI::solv::CellPoissonFACOps< DIM >.

◆ computeCompositeResidualOnLevel()

template<int DIM>

virtual void SAMRAI::solv::FACOperatorStrategy< DIM >::computeCompositeResidualOnLevel	(	SAMRAIVectorReal< DIM, double > &	residual,
		const SAMRAIVectorReal< DIM, double > &	solution,
		const SAMRAIVectorReal< DIM, double > &	rhs,
		int	ln,
		bool	error_equation_indicator
	)

pure virtual

For the specified level number ln, compute the composite residual r=f-Au, where f is the right hand side and u is the solution. Note that the composite residual is not a one-level residual. It must take into account the composite grid stencil around the coarse-fine grid interface.

May assume:

Composite residual on next finer level l+1, has been computed already.
If any intermediately computed data is needed from level l+1, it has been done and stored on that level.
Residual computations for the original equation and the error equations will not be intermingled within one FAC cycle.

Steps:

Fill boundary ghosts.
If needed, coarsen intermediate data from level l+1.
Compute residual \( r^l \leftarrow f - A u^l \).

Final step before leaving function:

If any intermediately computed data is needed in at level l-1, it must be computed and stored before leaving this function.

Important: Do not restrict residual from finer levels. (However, you must write the function restrictResidual() to do this.)

Important: This function must also work when the right-hand-side and the residual are identical. In that case, it should effectively do \( r \leftarrow r - A u \).

Parameters

residual	residual vector
solution	solution vector
rhs	source (right hand side) vector
ln	level number
error_equation_indicator	flag stating whether u is an error vector or a solution vector

Implemented in SAMRAI::solv::CellPoissonFACOps< DIM >.

◆ computeResidualNorm()

template<int DIM>

virtual double SAMRAI::solv::FACOperatorStrategy< DIM >::computeResidualNorm	(	const SAMRAIVectorReal< DIM, double > &	residual,
		int	fine_ln,
		int	coarse_ln
	)

pure virtual

Compute norm of the given residual on the given range of hierarchy levels. The residual vector is computed already and you should not change it. The only purpose of this function to allow you to choose how to define the norm.

The norm value is used during the FAC iteration to determine convergence of the composite grid linear system.

Residual values that lie under a finer level should not be counted.

Parameters

residual	residual vector
fine_ln	finest level number
coarse_ln	coarsest level number

Returns: norm value of residual vector, which should be non-negative

Implemented in SAMRAI::solv::CellPoissonFACOps< DIM >.

◆ postprocessOneCycle()

template<int DIM>

virtual void SAMRAI::solv::FACOperatorStrategy< DIM >::postprocessOneCycle	(	int	fac_cycle_num,
		const SAMRAIVectorReal< DIM, double > &	current_soln,
		const SAMRAIVectorReal< DIM, double > &	residual
	)

virtual

This function is called after each FAC cycle. It allows you to monitor the progress and do other things. You should not modify the solution vector in the argument.

The default implementation does nothing.

Parameters

fac_cycle_num	FAC cycle number completed
current_soln	current solution
residual	residual based on the current solution

Reimplemented in SAMRAI::solv::CellPoissonFACOps< DIM >.

◆ initializeOperatorState()

template<int DIM>

virtual void SAMRAI::solv::FACOperatorStrategy< DIM >::initializeOperatorState	(	const SAMRAIVectorReal< DIM, double > &	solution,
		const SAMRAIVectorReal< DIM, double > &	rhs
	)

virtual

This function is called when the hierarchy configuration changes. If you maintain any hierarchy-dependent data in your implementation (for example, caching communication schedules or computing coarse-fine boundaries), use this function to update that data.

If you do not maintain such data, this function may be empty.

Note that although the vector arguments given to other methods in this class may not necessarily be the same as those given to this method, there will be similarities, including: