gsXBraid< T > Class Template Reference

Detailed Description

template<typename T>
class gismo::gsXBraid< T >

Class defining the XBraid wrapper.

The gsXBraid class wraps the BraidApp class provided by the XBraid project and adds a set of commodity functions.

In order to implement an XBraid application the user has to implement a derived class

template<typename T>
class gsXBraid_app : public gsXBraid<T>
{ ... };

and implement the following application-specific functions:

braid_Int Access(...)
braid_Int BufPack(...)
braid_Int BufSize(...)
braid_Int BufUnpack(...)
braid_Int Clone(...)
braid_Int Free(...)
braid_Int Init(...)
braid_Int Residual(...)
braid_Int SpatialNorm(...)
braid_Int Step(...)

which are declared as (pure) virtual functions in BraidApp.

The generic implementation of the gsXBraid class leaves all of these methods unimplemented. We also provide specializations for gsXBraid<gsMatrix<T>> and gsXBraid<gsVector<T>> which assume that the data type for storing the solution (passed as braid_Vector) is of type gsMatrix<T> and gsVector<T>, respectively.

Inheritance diagram for gsXBraid< T >:

Public Member Functions
virtual braid_Int	Free (braid_Vector)
	Frees the given vector (dummy method)
void	GetMyID (braid_Int *myid_ptr)
	Gets the MPI process ID.
void	GetNLevels (braid_Int *nlevels_ptr)
	Gets the total number of levels (XBraid style)
void	GetNumIter (braid_Int *niter_ptr)
	Gets the number of iterations (XBraid style)
void	GetRNorms (braid_Int *nrequest_ptr, braid_Real *rnorms)
	Gets the residual norm (XBraid style)
	gsXBraid (const gsMpiComm &comm, const braid_Real tstart, const braid_Real tstop, braid_Int ntime)
	Constructor.
braid_Int	id ()
	Returns the MPI process ID.
braid_Int	iterations ()
	Returns the number of iterations.
braid_Int	levels ()
	Returns the total number of levels.
braid_Real	norm (braid_Int nrequest)
	Returns the residual norm.
virtual braid_Int	Residual (braid_Vector, braid_Vector, BraidStepStatus &)
	Computes the residual (dummy method)
void	SetAbsTol (braid_Real tol)
	Sets absolute stopping tolerance.
void	SetAccessLevel (braid_Int access_level)
void	SetCFactor (braid_Int level, braid_Int cfactor)
	Sets the coarsening factor cfactor on grid level (default is 2)
void	SetCFactor (braid_Int cfactor)
	Sets the coarsening factor cfactor on all grid levels.
void	SetCRelaxWt (braid_Int level, braid_Real Cwt)
	Sets the C-relaxation weight.
void	SetDefaultPrintFile ()
	Sets the default print file.
void	SetFileIOLevel (braid_Int io_level)
	Sets the file input/output level.
void	SetFMG ()
	Sets FMG (F-cycle)
void	SetFullRNormRes (braid_PtFcnResidual residual)
	Sets callback function for residual numer calculation.
void	SetIncrMaxLevels ()
	Increases the max number of multigrid levels after performing a refinement.
void	SetMaxIter (braid_Int max_iter)
	Sets max number of multigrid iterations.
void	SetMaxLevels (braid_Int max_levels)
	Sets the maximum number of multigrid levels.
void	SetMaxRefinements (braid_Int max_refinements)
	Sets the max number of time grid refinement levels allowed.
void	SetMinCoarse (braid_Int min_coarse)
void	SetNFMG (braid_Int k)
	Sets the number of initial F-cycles to do before switching to V-cycles.
void	SetNFMGVcyc (braid_Int nfmg_Vcyc)
	Sets the number of V-cycles to do at each FMG level (default is 1)
void	SetNRelax (braid_Int level, braid_Int nrelax)
void	SetNRelax (braid_Int nrelax)
void	SetPeriodic (braid_Int periodic)
	Sets periodic time grid (default is 0)
void	SetPrintFile (const char *printfile_name)
	Sets the output file for runtime print message.
void	SetPrintLevel (braid_Int print_level)
void	SetRefine (braid_Int refine)
	Turns time refinement on (refine = 1) or off (refine = 0).
void	SetRelTol (braid_Real tol)
	Sets relative stopping tolerance.
void	SetResidual ()
	Sets user-defined residual routine.
void	SetRichardsonEstimation (braid_Int est_error, braid_Int richardson, braid_Int local_order)
void	SetSeqSoln (braid_Int use_seq_soln)
void	SetSkip (braid_Int skip)
	Sets whether to skip all work on the first down cycle (skip = 1). On by default.
void	SetSpatialCoarsenAndRefine ()
	Sets user-defined coarsening and refinement routine.
void	SetStorage (braid_Int storage)
void	SetSync ()
	Sets user-defined sync routine.
void	SetTemporalNorm (braid_Int tnorm)
	Sets the temporal norm: 1-norm (1), 2-norm (2:default), inf-norm (3)
void	SetTimeGrid (braid_PtFcnTimeGrid tgrid)
	Sets callback function for time grid.
void	SetTPointsCutoff (braid_Int tpoints_cutoff)
	Sets the time cutoff.
void	solve ()
	Runs the parallel-in-time multigrid solver.
virtual	~gsXBraid ()
	Destructor.

Protected Attributes
BraidCore	core
	Braid Core object.

Member Function Documentation

void SetAccessLevel ( braid_Int  access_level )

inline

Sets the acces level for gsXBraid. This controls how often the user's access routine is called.

• Level 0: Never call the user's access routine
• Level 1: Only call the user's access routine after gsXBraid is finished (default)
• Level 2: Call the user's access routine every iteration and on every level. This is during _braid_FRestrict, during the down-cycle part of a gsXBraid iteration.

void SetMinCoarse ( braid_Int  min_coarse )

inline

Sets the minimum allowed coarse grid size. gsXBraid stops coarsening whenever creating the next coarser grid will result in a grid smaller than min_coarse. The maximum possible coarse grid size will be min_coarse*coarsening_factor.

void SetNRelax ( braid_Int  level, braid_Int  nrelax  )

inline

Sets the number of relaxation sweeps nrelax on grid level. Level 0 is the finest grid. One sweep is a CF relaxation sweep.

void SetNRelax ( braid_Int  nrelax )

inline

Sets the number of relaxation sweeps nrelax on all grid levels. One sweep is a CF relaxation sweep.

void SetPrintLevel ( braid_Int  print_level )

inline

Sets the print level for runtime print message.

• Level 0: no output
• Level 1: print runtime information like the residual history
• Level 2: level 1 output, plus post-Braid run statistics (default)
• Level 3: level 2 output, plus debug level output.

void SetRichardsonEstimation ( braid_Int  est_error, braid_Int  richardson, braid_Int  local_order  )

inline

Turns on built-in Richardson-based error estimation and/or extrapolation with gsXBraid. When enabled, the Richardson extrapolation (RE) option (richardson == 1) is used to improve the accuracy of the solution at the C-points on the finest level. When the built-in error estimate option is turned on (est_error == 1), RE is used to estimate the local truncation error at each point. These estimates can be accessed through StepStatus and AccessStatus functions. The last parameter is local_order, which represents the LOCAL order of the* time integration scheme. e.g. local_order = 2 for Backward Euler. Also, the Richardson error estimate is only available after roughly 1 Braid iteration. The estimate is given a dummy value of -1.0, until an actual estimate is available. Thus after an adaptive refinement, and a new hierarchy is formed, another iteration must pass before the error estimates are available again.

void SetSeqSoln ( braid_Int  use_seq_soln )

inline

Sets the initial guess to gsXBraid as the sequential time stepping solution.

• 0: The user's Init() function initializes the state vector (default)
• 1: Sequential time stepping, with the user's initial condition from Init(t=0) initializes the state vector

void SetStorage ( braid_Int  storage )

inline

Sets the storage properties of the code. -1 : Default, store only C-points 0 : Full storage of C- and F-Points on all levels x > 0 : Full storage on all levels >= x