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