Xyce  6.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
N_NLS_NOX_StagnationTest.h
Go to the documentation of this file.
1 //-------------------------------------------------------------------------
2 // Copyright Notice
3 //
4 // Copyright 2002 Sandia Corporation. Under the terms
5 // of Contract DE-AC04-94AL85000 with Sandia Corporation, the U.S.
6 // Government retains certain rights in this software.
7 //
8 // Xyce(TM) Parallel Electrical Simulator
9 // Copyright (C) 2002-2014 Sandia Corporation
10 //
11 // This program is free software: you can redistribute it and/or modify
12 // it under the terms of the GNU General Public License as published by
13 // the Free Software Foundation, either version 3 of the License, or
14 // (at your option) any later version.
15 //
16 // This program is distributed in the hope that it will be useful,
17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 // GNU General Public License for more details.
20 //
21 // You should have received a copy of the GNU General Public License
22 // along with this program. If not, see <http://www.gnu.org/licenses/>.
23 //-------------------------------------------------------------------------
24 
25 //-------------------------------------------------------------------------
26 // Filename : $RCSfile: N_NLS_NOX_StagnationTest.h,v $
27 //
28 // Purpose :
29 //
30 // Special Notes :
31 //
32 // Creator :
33 //
34 // Creation Date :
35 //
36 // Revision Information:
37 // ---------------------
38 //
39 // Revision Number: $Revision: 1.7 $
40 //
41 // Revision Date : $Date: 2014/02/24 23:49:24 $
42 //
43 // Current Owner : $Author: tvrusso $
44 //-------------------------------------------------------------------------
45 
46 #ifndef N_NLS_NOX_STAGNATIONTEST_H
47 #define N_NLS_NOX_STAGNATIONTEST_H
48 
49 #include "NOX_StatusTest_Generic.H" // base class
50 
51 namespace N_NLS_NOX {
52 
53 //! Failure test based on the convergence rate between nonlinear iterations.
54 /*!
55  This status test returns a Failed status if the convergence rate is worse
56  than a specified tolerance for \f$ n \f$ consecutive iterations.
57 
58  In many codes if the Jacobian is not accurate, the solver can stagnate.
59  In this case, further nonlinear iterations make negligible progress in
60  reducing the norm of F. To prevent unnecessary churning, this status test
61  will identify when a code stagnates and ends the solve.
62 
63  This status test returns a Failed status if \f$ n \f$ nonlinear steps
64  have consecutively failed the following test:
65 
66  At nonlinear iteration \f$ k \f$, the convergence rate, \f$ \eta \f$ is
67  computed by:
68 
69  \f[ \eta = \frac{\| F_k \|}{\| F_{k-1} \|} \f]
70 
71  If \f$ \eta \f$ is greater than or equal to the specified tolerance, then
72  a counter is incremented. If the counter hits the user specified number of
73  iterations, the status test returns a Failed status. NOTE: For the counter
74  to increment, the steps have to fail CONSECUTIVELY. The counter is reset
75  every time a convergence rate passes the requested tolerance.
76 
77  Based on experience the following values are recomended:
78 
79  <ul>
80  <li> For Newton solves: n = 50, tolerance = 1.0<br>
81  <li> For Newton solves with a line search: n = 15, tolerance = 0.99
82  <\ul>
83 */
84 class Stagnation : public NOX::StatusTest::Generic {
85 
86 public:
87 
88  //! Constructor.
89  /*! n is the number of consecutive nonlinear iterations with a
90  convergence rate failure for this test to return a Failed status.
91  */
92  Stagnation(int n = 5, double tolerance = 1.0e-3);
93 
94  //! Destructor.
95  virtual ~Stagnation();
96 
97  virtual NOX::StatusTest::StatusType checkStatus(const NOX::Solver::Generic&
98  problem);
99 
100  virtual NOX::StatusTest::StatusType getStatus() const;
101 
102  virtual std::ostream& print(std::ostream& stream, int indent = 0) const;
103 
104  //! Returns the used specified number of steps that can consecutively fail the tolerance test before the test returns a failed status.
105  virtual int getMaxNumSteps() const;
106 
107  //! Returns the current number of steps that have consecutively failed the tolerance test.
108  virtual int getCurrentNumSteps() const;
109 
110  //! Returns the user specified tolerance.
111  virtual double getTolerance() const;
112 
113  //! Returns the current convergence rate.
114  virtual double getConvRate() const;
115 
116 private:
117 
118  //! User supplied value of n.
119  int maxSteps;
120 
121  //! Current number of consecutive nonlinear iterations that have failed the specified tolerance.
122  int numSteps;
123 
124  //! The last nonlinear iteration index.
125  /*! This is used to prevent counting a step multiple times if by chance
126  the status test is called multiple times between iterations.
127  */
129 
130  //! User specified tolerance.
131  double tolerance;
132 
133  //! Currently computed convergence rate.
134  double convRate;
135 
136  double minConvRate;
137 
138  double normFInit;
139 
140  //! %Status
141  NOX::StatusTest::StatusType status;
142 
143 };
144 
145 } // namespace N_NLS_NOX
146 
147 #endif // N_NLS_NOX_STAGNATIONTEST_H
148