Thyra  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Thyra_SolveSupportTypes.hpp
1 // @HEADER
2 // *****************************************************************************
3 // Thyra: Interfaces and Support for Abstract Numerical Algorithms
4 //
5 // Copyright 2004 NTESS and the Thyra contributors.
6 // SPDX-License-Identifier: BSD-3-Clause
7 // *****************************************************************************
8 // @HEADER
9 
10 #ifndef THYRA_SOLVE_SUPPORT_TYPES_HPP
11 #define THYRA_SOLVE_SUPPORT_TYPES_HPP
12 
13 #include "Thyra_OperatorVectorTypes.hpp"
14 #include "Teuchos_ParameterList.hpp"
15 #include "Teuchos_FancyOStream.hpp"
16 #include "Teuchos_Describable.hpp"
17 
18 
19 namespace Thyra {
20 
21 
39 };
40 
41 
46 inline
47 const std::string toString(const ESolveMeasureNormType solveMeasureNormType)
48 {
49  switch(solveMeasureNormType) {
50  case SOLVE_MEASURE_ONE:
51  return "SOLVE_MEASURE_ONE";
53  return "SOLVE_MEASURE_NORM_RESIDUAL";
55  return "SOLVE_MEASURE_NORM_SOLUTION";
57  return "SOLVE_MEASURE_NORM_INIT_RESIDUAL";
59  return "SOLVE_MEASURE_NORM_RHS";
60  default:
62  }
64 }
65 
66 
88  {}
91  :numerator(_numerator),denominator(_denominator)
92  {}
94  void set(ESolveMeasureNormType _numerator, ESolveMeasureNormType _denominator)
95  { numerator = _numerator; denominator = _denominator; }
99  bool useDefault() const
103  ESolveMeasureNormType denominator_in
104  ) const
105  { return ( numerator==numerator_in && denominator==denominator_in ); }
107  bool contains(ESolveMeasureNormType measure) const
108  { return ( numerator==measure || denominator==measure ); }
109 };
110 
111 
116 inline
117 std::ostream& operator<<(std::ostream &out, const SolveMeasureType &solveMeasureType)
118 {
119  out << "("<<toString(solveMeasureType.numerator)
120  << "/"<<toString(solveMeasureType.denominator)<<")";
121  return out;
122 }
123 
124 
128 template<class Scalar>
130 public:
131 
134 
144  reduce( const VectorBase<Scalar> &v ) const
145  {
146 #ifdef THYRA_DEBUG
148  "Error, the vector v="<<v.description()<<" is not compatiable with"
149  " *this="<<this->description()<<"!");
150 #endif
151  return reduceImpl(v);
152  }
153 
157  bool isCompatible( const VectorBase<Scalar> &v ) const
158  { return isCompatibleImpl(v); }
159 
161 
162 protected:
163 
166 
168  virtual typename ScalarTraits<Scalar>::magnitudeType
169  reduceImpl( const VectorBase<Scalar> &v ) const = 0;
170 
172  virtual bool isCompatibleImpl( const VectorBase<Scalar> &v ) const = 0;
173 
175 
176 };
177 
178 
279 template <class Scalar>
284  static ScalarMag unspecifiedTolerance() { return ScalarMag(-1.0); }
306  {}
309  SolveMeasureType solveMeasureType_in,
310  ScalarMag requestedTol_in,
311  const RCP<ParameterList> &extraParameters_in = Teuchos::null,
312  const RCP<ReductionFunctional<Scalar> > &numeratorReductionFunc_in = Teuchos::null,
313  const RCP<ReductionFunctional<Scalar> > &denominatorReductionFunc_in = Teuchos::null
314  )
315  : solveMeasureType(solveMeasureType_in),
316  requestedTol(requestedTol_in),
317  extraParameters(extraParameters_in),
318  numeratorReductionFunc(numeratorReductionFunc_in),
319  denominatorReductionFunc(denominatorReductionFunc_in)
320  {}
321 };
322 
323 
328 template<class Scalar>
329 std::ostream& operator<<(std::ostream &out, const SolveCriteria<Scalar> &solveCriteria)
330 {
331  out << typeName(solveCriteria) << "{";
332  out << "solveMeasureType="<<solveCriteria.solveMeasureType;
333  out << ", requestedTol="<<solveCriteria.requestedTol;
334  if (nonnull(solveCriteria.extraParameters)) {
335  out << ", extraParameters="<<solveCriteria.extraParameters;
336  }
337  if (nonnull(solveCriteria.numeratorReductionFunc)) {
338  out << ", numeratorReductionFunc="<<solveCriteria.numeratorReductionFunc->description();
339  }
340  if (nonnull(solveCriteria.denominatorReductionFunc)) {
341  out << ", denominatorReductionFunc="<<solveCriteria.denominatorReductionFunc->description();
342  }
343  out << "}";
344  return out;
345 }
346 
347 
352 class CatastrophicSolveFailure : public std::runtime_error
353 {public: CatastrophicSolveFailure(const std::string& what_arg) : std::runtime_error(what_arg) {}};
354 
355 
364 };
365 
366 
371 inline
372 const std::string toString(const ESolveStatus solveStatus)
373 {
374  switch(solveStatus) {
375  case SOLVE_STATUS_CONVERGED: return "SOLVE_STATUS_CONVERGED";
376  case SOLVE_STATUS_UNCONVERGED: return "SOLVE_STATUS_UNCONVERGED";
377  case SOLVE_STATUS_UNKNOWN: return "SOLVE_STATUS_UNKNOWN";
378  default: TEUCHOS_TEST_FOR_EXCEPT(true);
379  }
381 }
382 
383 
390 template <class Scalar>
391 struct SolveStatus {
395  static ScalarMag unknownTolerance() { return ScalarMag(-1); }
403  std::string message;
410  {}
413  static std::string achievedTolToString( const ScalarMag &achievedTol )
414  {
415  if(achievedTol==unknownTolerance()) return "unknownTolerance()";
416  std::ostringstream oss; oss << achievedTol; return oss.str();
417  }
418 };
419 
420 
425 template <class Scalar>
426 std::ostream& operator<<( std::ostream& out_arg, const SolveStatus<Scalar> &solveStatus )
427 {
429  out = Teuchos::getFancyOStream(Teuchos::rcp(&out_arg,false));
430  Teuchos::OSTab tab(out);
431  *out
432  << "solveStatus = " << toString(solveStatus.solveStatus) << std::endl
433  << "achievedTol = " << SolveStatus<Scalar>::achievedTolToString(solveStatus.achievedTol) << std::endl;
434  *out << "message:";
435  if (solveStatus.message.length()) {
436  Teuchos::OSTab tab2(out);
437  *out << "\n" << solveStatus.message << "\n";
438  }
439  *out << "extraParameters:";
440  if(solveStatus.extraParameters.get()) {
441  *out << "\n";
442  Teuchos::OSTab tab3(out);
443  solveStatus.extraParameters->print(*out, 10, true);
444  }
445  else {
446  *out << " NONE\n";
447  }
448  return out_arg;
449 }
450 
451 
462 };
463 
464 
472 };
473 
474 
479 template <class Scalar>
481  const Ptr<SolveStatus<Scalar> > &overallSolveStatus
482  )
483 {
484  overallSolveStatus->solveStatus = SOLVE_STATUS_CONVERGED;
485 }
486 
487 
504 template <class Scalar>
506  const SolveCriteria<Scalar>, // ToDo: Never used, need to take this out!
507  const SolveStatus<Scalar> &solveStatus,
508  const Ptr<SolveStatus<Scalar> > &overallSolveStatus
509  )
510 {
511  switch(solveStatus.solveStatus) {
513  {
514  // First, if we see any unconverged solve status, then the entire block is
515  // unconverged!
516  overallSolveStatus->solveStatus = SOLVE_STATUS_UNCONVERGED;
517  overallSolveStatus->message = solveStatus.message;
518  overallSolveStatus->extraParameters = solveStatus.extraParameters;
519  break;
520  }
522  {
523  // Next, if any solve status is unknown, then if the overall solve
524  // status says converged, then we have to mark it as unknown. Note that
525  // unknown could mean that the system is actually converged!
526  switch(overallSolveStatus->solveStatus) {
528  overallSolveStatus->solveStatus = SOLVE_STATUS_UNKNOWN;
529  break;
532  // If we get here then the overall solve status is either unknown
533  // already or says unconverged and this will not change here!
534  overallSolveStatus->message = solveStatus.message;
535  overallSolveStatus->extraParameters = solveStatus.extraParameters;
536  break;
537  default:
538  TEUCHOS_TEST_FOR_EXCEPT(true); // Corrupted enum?
539  }
540  break;
541  }
543  {
544  // If we get here then the overall solve status is either unknown,
545  // unconverged, or converged and this will not change here!
546  if(overallSolveStatus->message == "")
547  overallSolveStatus->message = solveStatus.message;
548  break;
549  }
550  default:
551  TEUCHOS_TEST_FOR_EXCEPT(true); // Corrupted enum?
552  }
553  // Update the achieved tolerence to the maximum returned
554  if( solveStatus.achievedTol > overallSolveStatus->achievedTol ) {
555  overallSolveStatus->achievedTol = solveStatus.achievedTol;
556  }
557  // Set a message if none is set
558  if(overallSolveStatus->message == "")
559  overallSolveStatus->message = solveStatus.message;
560  // Set the extra parameters if none is set
561  if(overallSolveStatus->extraParameters.get()==NULL)
562  overallSolveStatus->extraParameters = solveStatus.extraParameters;
563 }
564 
565 
566 } // namespace Thyra
567 
568 
569 #endif // THYRA_SOLVE_SUPPORT_TYPES_HPP
How the output LOWSB object will be useded for solves in unspecified.
SolveCriteria()
Default construction to use default solve criteria.
Norm of the current solution vector (i.e. ||x||)
ScalarMag requestedTol
The requested solve tolerance (what the client would like to see). Only significant if !this-&gt;solveMe...
virtual ScalarTraits< Scalar >::magnitudeType reduceImpl(const VectorBase< Scalar > &v) const =0
bool useDefault() const
Return if this is a default solve measure (default constructed).
Thrown if vector spaces are incompatible.
bool contains(ESolveMeasureNormType measure) const
The output LOWSB object will only be used for forward solves.
std::string message
A simple one-line message (i.e. no newlines) returned from the solver.
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
The output LOWSB object will used for forward and transpose solves.
The final solution status is unknown but he solve did not totally fail.
bool operator()(ESolveMeasureNormType numerator_in, ESolveMeasureNormType denominator_in) const
Return if (numerator,denominataor) matches this.
void accumulateSolveStatus(const SolveCriteria< Scalar >, const SolveStatus< Scalar > &solveStatus, const Ptr< SolveStatus< Scalar > > &overallSolveStatus)
Accumulate solve status objects for solving a block of RHSs is smaller sub-blocks.
void accumulateSolveStatusInit(const Ptr< SolveStatus< Scalar > > &overallSolveStatus)
Initial overallSolveStatus before calling accumulateSolveStatus().
SolveCriteria(SolveMeasureType solveMeasureType_in, ScalarMag requestedTol_in, const RCP< ParameterList > &extraParameters_in=Teuchos::null, const RCP< ReductionFunctional< Scalar > > &numeratorReductionFunc_in=Teuchos::null, const RCP< ReductionFunctional< Scalar > > &denominatorReductionFunc_in=Teuchos::null)
Construct with a specified solve criteria.
SolveMeasureType(ESolveMeasureNormType _numerator, ESolveMeasureNormType _denominator)
ESolveMeasureNormType numerator
std::ostream & operator<<(std::ostream &out, const SolveMeasureType &solveMeasureType)
Output operator.
ESolveMeasureNormType
Type of solve measure norm.
The output LOWSB object will only be used for transpose solves.
TEUCHOS_DEPRECATED RCP< T > rcp(T *p, Dealloc_T dealloc, bool owns_mem)
ESolveStatus
Solution status.
static ScalarMag unknownTolerance()
virtual std::string description() const
Abstract interface for finite-dimensional dense vectors.
TEUCHOSCORE_LIB_DLL_EXPORT std::string toString(const EVerbosityLevel verbLevel)
Simple struct for the return status from a solve.
ScalarTraits< Scalar >::magnitudeType reduce(const VectorBase< Scalar > &v) const
Compute the reduction over a vector.
Norm of the right-hand side (i.e. ||b||)
ESupportSolveUse
Enum that specifies how a LinearOpWithSolveBase object will be used for solves after it is constructe...
ESolveStatus solveStatus
The return status of the solve.
Teuchos::ScalarTraits< Scalar >::magnitudeType ScalarMag
static ScalarMag unspecifiedTolerance()
void set(ESolveMeasureNormType _numerator, ESolveMeasureNormType _denominator)
No solve measure (i.e. same as 1.0)
bool nonnull(const boost::shared_ptr< T > &p)
ScalarMag achievedTol
The maximum final tolerance actually achieved by the (block) linear solve. A value of unknownToleranc...
static std::string achievedTolToString(const ScalarMag &achievedTol)
Output the achieveTol field.
#define TEUCHOS_UNREACHABLE_RETURN(dummyReturnVal)
RCP< ParameterList > extraParameters
Any extra control parameters (e.g. max iterations).
virtual bool isCompatibleImpl(const VectorBase< Scalar > &v) const =0
bool isCompatible(const VectorBase< Scalar > &v) const
Returns true if v is compatible with *this.
RCP< const ReductionFunctional< Scalar > > numeratorReductionFunc
Reduction function to be used in place of the natural norm of the numerator.
The input preconditioner should just be applied as an operator.
A general reduction functional to be used in specialized solve convergence criteria.
RCP< const ReductionFunctional< Scalar > > denominatorReductionFunc
Reduction function to be used in place of the natural norm of the numerator.
EPreconditionerInputType
Enum defining the status of a preconditioner object.
RCP< ParameterList > extraParameters
Any extra status parameters. Note that the contents of this parameter list is totally undefined...
SolveMeasureType solveMeasureType
The type of solve tolerance requested as given in this-&gt;requestedTol.
The requested solution criteria has likely been achieved.
Exception type thrown on an catastrophic solve failure.
Teuchos::ScalarTraits< Scalar >::magnitudeType ScalarMag
The requested solution criteria has likely not been achieved.
Simple struct that defines the requested solution criteria for a solve.
The input preconditioner should viewed as a matrix to be factored then backsolved as a preconditioner...
ESolveMeasureNormType denominator
#define TEUCHOS_TEST_FOR_EXCEPT(throw_exception_test)
std::string typeName(const T &t)
Norm of the initial residual vector given a non-zero guess (i.e. ||A*xo-b||)
Norm of the current residual vector (i.e. ||A*x-b||)