Xyce  6.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
N_TIA_StepErrorControl.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_TIA_StepErrorControl.h,v $
27 //
28 // Purpose : This file defines the class for the time integration
29 // stepsize control algorithms.
30 //
31 // Special Notes :
32 //
33 // Creator : Buddy Watts
34 //
35 // Creation Date : 6/1/00
36 //
37 // Revision Information:
38 // ---------------------
39 //
40 // Revision Number: $Revision: 1.92 $
41 //
42 // Revision Date : $Date: 2014/08/06 22:26:43 $
43 //
44 // Current Owner : $Author: dgbaur $
45 //-----------------------------------------------------------------------------
46 
47 #ifndef Xyce_N_TIA_STEP_ERROR_CONTROL_H
48 #define Xyce_N_TIA_STEP_ERROR_CONTROL_H
49 
50 // ---------- Standard Declarations ----------
51 #include <iosfwd>
52 #include <set>
53 #include <vector>
54 
55 #include <N_ANP_fwd.h>
56 #include <N_IO_fwd.h>
57 #include <N_LOA_fwd.h>
58 #include <N_PDS_fwd.h>
59 #include <N_TIA_fwd.h>
60 
61 #include <N_UTL_BreakPoint.h>
62 
63 //-----------------------------------------------------------------------------
64 // Class : N_TIA_StepErrorControl
65 // Purpose : This is the time integration step & error control class.
66 //
67 // Special Notes : ERK. 6/19/2010 This class was originally designed to
68 // handle much of the time step selection logic. This
69 // design intent was associated with the original
70 // "old-DAE(ODE)" version of the integrator, which
71 // is no longer in the code. However numerous artifacts
72 // of this design are still here. For example, the step size
73 // variables (such as currentTimeStep, currentTime)
74 // are still here. So at this point, this is mostly a data
75 // storage class for step variables that have a global
76 // scope.
77 //
78 // The implementation of the "new-DAE" form
79 // moved away from this design idea, and placed most of the
80 // step-size selection directly inside of specific algorithms.
81 // So, BDF15 handles stepsize selection specific to it in the
82 // BDF15 class, and the same goes for OneStep.
83 //
84 // Creator : Buddy Watts, SNL
85 // Creation Date : 6/01/00
86 //-----------------------------------------------------------------------------
88 {
89  // member functions:
90  public:
91  // constructor
92  N_TIA_StepErrorControl(N_IO_CmdParse & cp,
93  N_ANP_AnalysisManager & anaManager,
94  N_TIA_TIAParams & tiaP);
95 
96  // Destructor:
97  virtual ~N_TIA_StepErrorControl();
98 
100 
101  // The "stop time" is either the next discontinuity point, or the final time,
102  // whichever comes first.
103  void updateStopTime();
104 
105  double findNextStopTime();
106 
107  virtual void updateTwoLevelTimeInfo (const N_TIA_TimeIntInfo & tiInfo);
108 
109  // Print out the time-step information.
110  virtual void outputTimeInfo(std::ostream &os);
111 
112  bool initializeBreakPoints();
113 
114  int getNumberOfSteps() const {
115  return numberOfSteps_;
116  }
117 
118  // Requests dynamic breakpoint information from the loader. Adds, subtracts
119  // from the breakpoints array.
120  bool updateBreakPoints();
121  // add individual breakpoints
122  void setBreakPoint(const N_UTL_BreakPoint &bp);
123  void setBreakPoint(double bp);
124  // signal that pause breakpoint has been reached
125  void simulationPaused();
126  // is the current time a pause time?
127  bool isPauseTime();
128 
129  // Requests dynamic time step information from the loader.
130  bool updateMaxTimeStep(double suggestedMaxTimeStep=0.0);
131 
132  // Sets the minimum time step based on machine precision.
133  bool updateMinTimeStep();
134 
135  bool isFinished();
136 
137  void evaluateStepError ();
138 
139  void integrationStepReport_(std::ostream &os, bool step_attempt_status, bool sAStatus, bool testedError);
140 
141  void terseIntegrationStepReport_(std::ostream &os, bool step_attempt_status, bool sAStatus, bool testedError);
142 
143  // Gets the size of the restart data.
144  virtual int restartDataSize( bool pack );
145 
146  // Output restart data.
147  virtual bool dumpRestartData(char * buf, int bsize, int & pos, N_PDS_Comm * comm, bool pack );
148 
149  // Load restart data.
150  virtual bool restoreRestartData(char * buf, int bsize, int & pos, N_PDS_Comm * comm, bool pack );
151 
152  // called if you want to start the time integration over from scratch.
153  bool resetAll ();
154 
155  // Method which sets the TIA parameters object pointer.
156  virtual bool setTIAParams();
157 
158  // Method which registers the TIA integration object pointer.
160 
161  void printBreakPoints (std::ostream & os) const;
162 
163  double getEstOverTol() const;
164 
165  void setTimeStep(double newTimeStep);
166 
167  bool getTranOPFlag() const;
168 
169  protected:
170 
171  void updatePauseTime(N_UTL_BreakPoint bp);
172 
173  private :
174  // make default constructor private:
176 
177  // member data:
178  public:
179 
180  // StepSize Variables
184  double lastTimeStep;
185  double minTimeStep;
186  double maxTimeStep;
189 
191 
192  double lastTime;
193  double currentTime;
194  double nextTime;
195  double stopTime;
196  double initialTime;
197  double finalTime;
198 
201 
204 
206  // number of newton iters
208 
211 
212  // Needed for 2-level:
214  double estOverTol_;
215 
216  protected:
217 
218  // This initialization flag is true if tiaParams have been
219  // registered and used. Otherwise false.
221 
223 
225 
227 
228  double tolAimFac_;
229 
230  // Pointer to the TIA parameters object.
232 
233  // Pointer to the TIA control algorithm.
235 
236  // Pointer to the current integration method.
238 
239  std::set< N_UTL_BreakPoint > breakPoints_;
240  std::set< N_UTL_BreakPoint >::iterator currentPauseBP;
241 
242  private :
243  // command line object
244  N_IO_CmdParse & commandLine_;
245 
246  // 03/08/04 tscoffe: Local data for BDF 1-5 method
247  int currentOrder_; // Current order of integration
248  int oldOrder_; // previous order of integration
249  int minOrder_; // minimum order = max(1,user option minord)
250  int maxOrder_; // maximum order = min(5,user option maxord)
251  int usedOrder_; // order used in current step (used after currentOrder is updated)
252  double alphas_; // $\alpha_s$ fixed-leading coefficient of this BDF method
253  std::vector<double> alpha_; // $\alpha_j(n)=h_n/\psi_j(n)$ coefficient used in local error test
254  // note: $h_n$ = current step size, n = current time step
255  double alpha0_; // $-\sum_{j=1}^k \alpha_j(n)$ coefficient used in local error test
256  double cj_; // $-\alpha_s/h_n$ coefficient used in local error test
257  double ck_; // local error coefficient
258  std::vector<double> sigma_; // $\sigma_j(n) = \frac{h_n^j(j-1)!}{\psi_1(n)*\cdots *\psi_j(n)}$
259  std::vector<double> gamma_; // $\gamma_j(n)=\sum_{l=1}^{j-1}1/\psi_l(n)$ coefficient used to
260  // calculate time derivative of history array for predictor
261  std::vector<double> beta_; // coefficients used to evaluate predictor from history array
262  std::vector<double> psi_; // $\psi_j(n) = t_n-t_{n-j}$ intermediary variable used to
263  // compute $\beta_j(n)$
264  int numberOfSteps_; // number of total time integration steps taken
265  int nef_; // number of successive error failures (yes I know this is duplicated above)
266  double usedStep_; // step-size used in current step
267  int nscsco_; // Number of Steps taken with Constant Step-size and Constant Order
268  double Ek_,Ekm1_,Ekm2_,Ekp1_; // Estimated LTE at currentOrder, currentOrder-1, and currentOrder-2
269  double Est_; // Represents which of Ek,Ekm1,Ekm2 will be used for step-size selection
270  double Tk_,Tkm1_,Tkm2_,Tkp1_; // Estimated $\|h_n^{k+1} y_n^{(k+1)}\|$, basically, order * E
271  int newOrder_; // order of next step
272  bool initialPhase_; // determines if we're in the initial phase of integration where we
273  // double the step-size & increase the order.
274  double h0_safety_; // safety factor in picking initial step-size
275  double h0_max_factor_; // h0 <= h0_max_factor * length of integration time
276  double h_phase0_incr_; // amount to increase step-sizes during initial phase
277  double h_max_inv_; // inverse of maximum step size
278  double Tkm1_Tk_safety_; // magic number for determining order reduction
279  double Tkp1_Tk_safety_; // magic number for determining order reduction
280  double r_factor_; // basic reduction factor for rr
281  double r_safety_; // safety factor in computing rr
282  double r_fudge_; // fudge factor in computing rr
283  double r_min_; // minimum reduction factor
284  double r_max_; // maximum reduction factor
285  double r_hincr_test_; // threshold for increasing the step-size
286  double r_hincr_; // factor used for increasing the step-size
287  int max_LET_fail_; // max number of error test failures before quitting.
288 
290  friend class N_TIA_Gear12;
291  friend class N_TIA_OneStep;
292 };
293 
294 //-----------------------------------------------------------------------------
295 // Function : N_TIA_StepErrorControl::finished
296 // Purpose : This function is called by the time integraion algorithm
297 // class to determine if the main time integration while
298 // loop should end.
299 // Special Notes :
300 // Scope : public
301 // Creator : Eric Keiter, SNL, Parallel ComputationalSciences.
302 // Creation Date : 10/11/00
303 //-----------------------------------------------------------------------------
305 {
306  double delta = currentTime - finalTime;
307 
308  delta = fabs(delta);
309  return (delta < 1.0e-10 * (finalTime - initialTime));
310 }
311 
312 //-----------------------------------------------------------------------------
313 // Function : N_TIA_StepErrorControl::registerWIMPtr
314 // Purpose :
315 // Special Notes :
316 // Scope : public
317 // Creator : Eric Keiter, SNL, Parallel ComputationalSciences.
318 // Creation Date : 09/06/01
319 //-----------------------------------------------------------------------------
322 {
323  wimPtr_ = wimPtr;
324  return (wimPtr != NULL);
325 }
326 
327 //-----------------------------------------------------------------------------
328 // Function : operator<<
329 // Purpose : "<<" operator for step error control class.
330 // Special Notes :
331 // Scope : public
332 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
333 // Creation Date : 10/17/05
334 //-----------------------------------------------------------------------------
335 std::ostream & operator<<(std::ostream & os, const N_TIA_StepErrorControl & sec);
336 
337 #endif // Xyce_N_TIA_STEP_ERROR_CONTROL_H
338 
339