NAME
ConvMonitor - base class for convergence monitors
INCLUDE
include "ConvMonitor.h"
SYNTAX
//-----------------------------------------------------------------------------
class ConvMonitor : public virtual HandleId
//-----------------------------------------------------------------------------
{
friend class ConvMonitorList;
protected:
// Communication buffer between solver and external objects
Handle(LinEqCommBlk) communication;
bool monitor; // True => record values for plotting
bool criterion; // True => test for convergence
bool append; // Precedence in evaluation of list (append at end)
bool relopIsAnd; // True if AND is relop for use in combined tests
Norm_type norm_tp;
// test: || curr_vec || <= conv_tolerance * base_value
real conv_tolerance;
real base_value;
real tst_value;
bool user_defined_base; // TRUE if the user is allowed to set
// the base_value directly
bool runtime_plot;
// This flag is set if eigenvalue info in communication should be used
bool use_eig_info;
// This flag is set if tst_value is imported from a scalar in communication.
// In such cases, external_value points to the relevant data item.
bool use_external_value;
real* external_value;
bool curr_is_internal; // True if curr_vec is allocated by monitor
Handle(LinEqVector) curr_vec; // vector to test
int chunk_size;
int hpt;
int hmax;
VecSimple(real) history; // information to be plotted
public:
ConvMonitor (const ConvMonitor_prm& p);
ConvMonitor ();
ConvMonitor (real conv_tolerance, Norm_type norm_tp, int chunk_size);
void redim ();
virtual void getScaling (String& scale) const { scale = ""; }
virtual real getScaling () const { return (1.0); }
virtual ~ConvMonitor ();
virtual void init (Handle(LinEqCommBlk)& communication);
virtual bool ok () const;
virtual bool satisfied ();
void setTolerance (const real user_tol) { conv_tolerance = user_tol; }
real getTolerance () const { return conv_tolerance; }
bool userDefinedBaseValue () { return user_defined_base; }
void setBaseValue (real user_base);
real getBaseValue () { return base_value; }
void activateMonitor (const bool onoff);
void activateCriterion (const bool onoff) { criterion = onoff; }
bool activeMonitor () const { return monitor; }
bool activeCriterion () const { return criterion; }
real getTestValue () const { return tst_value; }
real getMinValue () const;
void getMinValue (real& min_value, int& min_iter) const;
virtual int getWork () const;
virtual real getStorage () const;
virtual void performance (ConvStatistics& convStat);
virtual String description () const;
void plotMonitorData (CurvePlotFile& file, const String& title,
const String& comment, bool logplot = true);
void popUpMonitorData (const String& title, const String& geometry);
virtual void print (Os os) const;
bool operator != (const ConvMonitor& monitor);
bool operator == (const ConvMonitor& monitor);
bool operator < (const ConvMonitor& /*monitor*/) // for List of Monitor
{ return false; /* just a dummy implementation */ }
friend Os& operator << (Os& os, ConvMonitor& monitor);
CLASS_INFO
};
KEYWORDS
iterative methods, stopping criterion, convergence monitor
DESCRIPTION
The base class describes an interface for convergence monitors
based on a single vector, e.g. the residual vector r. The vector
to be monitored may be allocated internally if this entity is not
already allocated by the iterative solver and communicated
through a LinEqCommBlk. If the flag use_eig_info is set, the mon
itor will try to use spectral information from the LinEqCommBlk
to scale the test value, see the member function getScaling. If
the same data block also contains the precomputed l2 norm of the
residual vector used by the monitor, this value may be imported
through external_value. If this information is used, the flag
use_external_value is raised.
Depending on the flags monitor and criterion, the present conver
gence monitor will record the convergence history and/or act as a
stopping criterion. From the viewpoint of the IterativeSolver, a
collection of convegence monitors is administered by a ConvMoni
torList.
CONSTRUCTORS AND INITIALIZATION
Construction by a ConvMonitor_prm object or by supplying a maxi
mum tolerance conv_tolerance and a Norm_type (defaults to l2).
MEMBER FUNCTIONS
init - set up communication link via communication.
ok - check current state.
satisfied - monitor the test value and return true of the condi
tion is met.
userDefinedBaseValue - returns true if the user is allowed to
explicitly set the base value.
activateMonitor - allows the user to switch the recording of con
vergence history on/off depending on the value of the boolean
argument.
activateCriterion - allows the user to switch the convergence
test mode on/off depending on the value of the boolean argument.
activeMonitor - returns the current monitor state (on/off).
activeCriterion - returns the current criterion state (on/off).
setTolerance - allows the user to change the tolerance to be used
for the convergence test.
getTolerance - return the current tolerance value used in the
convergence test.
setBaseValue - assigns the base value given by the argument
user_base, if user-defined values are allowed. If not, a warning
message is given.
getBaseValue - returns the current base value.
getTestValue - return latest test value.
getMinValue - minimum test value that occurred during the itera
tion.
getWork and getStorage - estimate work and storage expenses for
this monitor.
performance - fill out relevant parts of a LinEqStatBlk object
for performance report.
plotMonitorData - make a plot of this monitor's history.
popUpMonitorData - pop up a plot of this monitor's history on the
screen.
EXAMPLES
The following table shows the relation between the stopping cri
teria in NSPCG and the present collection of ConvMonitor deriva
tives. The present codes represent far more alternatives.
NSPCG Class name Residual_type use_eig_info
rel_to_rhs (or x0=0)
=============================================================================
1 CMRelMixResidual PSEUDO_RES true true
2 CMRelResSolution PSEUDO_RES true any
3 CMRelResidual PSEUDO_RES true true
4 CMRelResidual PSEUDO_RES false true
-----------------------------------------------------------------------------
5 CMRelResidual ORIGINAL_RES false true
-----------------------------------------------------------------------------
6 CMRelRefSolution - false any
-----------------------------------------------------------------------------
7 CMRelMixResidual PREC_RES true true
8 CMRelResSolution PREC_RES true any
9 CMRelResidual PREC_RES true true
10 CMRelResidual PREC_RES false true
=============================================================================
SEE ALSO
class IterativeSolver, class ConvMonitorList.
DEVELOPED BY
SINTEF Applied Mathematics, Oslo, Norway, and University of Oslo,
Dept. of Mathematics, Norway
AUTHOR
Are Magnus Bruaset, SINTEF Applied Mathematics.