Xyce  6.1
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-2015 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.109 $
41 //
42 // Revision Date : $Date: 2015/04/17 20:32:13 $
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 #include <N_UTL_Math.h>
55 
56 #include <N_ANP_fwd.h>
57 #include <N_IO_fwd.h>
58 #include <N_LOA_fwd.h>
59 #include <N_PDS_fwd.h>
60 #include <N_TIA_fwd.h>
61 
62 #include <N_UTL_BreakPoint.h>
63 
64 namespace Xyce {
65 namespace TimeIntg {
66 
67 //-----------------------------------------------------------------------------
68 // Class : StepErrorControl
69 // Purpose : This is the time integration step & error control class.
70 //
71 // Special Notes : ERK. 6/19/2010 This class was originally designed to
72 // handle much of the time step selection logic. This
73 // design intent was associated with the original
74 // "old-DAE(ODE)" version of the integrator, which
75 // is no longer in the code. However numerous artifacts
76 // of this design are still here. For example, the step size
77 // variables (such as currentTimeStep, currentTime)
78 // are still here. So at this point, this is mostly a data
79 // storage class for step variables that have a global
80 // scope.
81 //
82 // The implementation of the "new-DAE" form
83 // moved away from this design idea, and placed most of the
84 // step-size selection directly inside of specific algorithms.
85 // So, BDF15 handles stepsize selection specific to it in the
86 // BDF15 class, and the same goes for OneStep.
87 //
88 // Creator : Buddy Watts, SNL
89 // Creation Date : 6/01/00
90 //-----------------------------------------------------------------------------
92 {
94  friend class Gear12;
95  friend class OneStep;
96 
97 public:
98  typedef std::set<Util::BreakPoint, Util::BreakPointLess> BreakPointSet;
99 
101  const std::string & netlist_filename,
102  Analysis::AnalysisManager & analysis_manager,
103  WorkingIntegrationMethod & working_integration_method,
104  const TIAParams & tia_params);
105 
106  virtual ~StepErrorControl();
107 
108 private:
111 
112 public:
113  const Util::BreakPointLess &getBreakPointLess() const {
114  return breakPointLess_;
115  }
116 
117  // The "stop time" is either the next discontinuity point, or the final time,
118  // whichever comes first.
119  void updateStopTime(
120  Parallel::Machine comm,
121  bool breakpoints_enabled,
122  double initial_time,
123  bool min_time_steps_breakpoint_given,
124  double min_time_steps_breakpoint);
125 
126  double findNextStopTimeDeprecated(Parallel::Machine comm, bool breakpoints_enabled);
127 
128  // Requests dynamic time step information from the loader.
129  bool updateMaxTimeStep(Parallel::Machine comm, Loader::Loader &loader, const TIAParams &tia_params, double suggestedMaxTimeStep=0.0);
130 
132  Parallel::Machine comm,
133  double nextTimeStep,
134  double nextTime,
135  int currentOrder,
136  bool breakpoints_enabled,
137  double initial_time,
138  bool min_time_steps_breakpoint_given,
139  double min_time_steps_breakpoint);
140 
141  // Print out the time-step information.
142  void outputTimeInfo(std::ostream &os);
143 
144  int getNumberOfSteps() const {
145  return numberOfSteps_;
146  }
147 
148  // Requests dynamic breakpoint information from the loader. Adds, subtracts
149  // from the breakpoints array.
150  bool updateBreakPoints(const Loader::Loader &loader, double initial_time);
151 
152  // add individual breakpoints
153  void setBreakPoint(const Util::BreakPoint &breakpoint, double initial_time);
154  void setBreakPoint(double bp);
155 
156  // signal that pause breakpoint has been reached
157  void simulationPaused(double initial_time);
158 
159  // is the current time a pause time?
160  bool isPauseTime();
161 
162  // Sets the minimum time step based on machine precision.
163  bool updateMinTimeStep();
164 
165  //-----------------------------------------------------------------------------
166  // Function : StepErrorControl::finished
167  // Purpose : This function is called by the time integraion algorithm
168  // class to determine if the main time integration while
169  // loop should end.
170  // Special Notes :
171  // Scope : public
172  // Creator : Eric Keiter, SNL, Parallel ComputationalSciences.
173  // Creation Date : 10/11/00
174  //-----------------------------------------------------------------------------
175  bool isFinished()
176  {
177  double delta = currentTime - finalTime;
178 
179  delta = std::fabs(delta);
180  return (delta < 1.0e-10 * (finalTime - initialTime));
181  }
182 
183  void evaluateStepError(const Loader::Loader &loader, const TIAParams &tia_params);
184 
185  // Gets the size of the restart data.
186  int getRestartDataSize( bool pack );
187 
188  // Output restart data.
189  bool dumpRestartData(char * buf, int bsize, int & pos, N_PDS_Comm * comm, bool pack );
190 
191  // Load restart data.
192  bool restoreRestartData(char * buf, int bsize, int & pos, N_PDS_Comm * comm, bool pack, double &initial_time);
193 
194  // called if you want to start the time integration over from scratch.
195  bool resetAll(const TIAParams &tia_params);
196 
197  // Method which sets the TIA parameters object pointer.
198  bool setFromTIAParams(const TIAParams &tia_params);
199 
200  void printBreakPoints (std::ostream & os) const;
201 
202  double getEstOverTol() const;
203 
204  void setTimeStep(double newTimeStep);
205 
206 private:
207  bool initializeBreakPoints(double start_time, double initial_time, double final_time);
208 
209  void updatePauseTime(Util::BreakPoint breakpoint, double initial_time);
210 
211  void integrationStepReport(std::ostream &os, bool step_attempt_status, bool sAStatus, bool testedError, const TIAParams &tia_params);
212 
213  void terseIntegrationStepReport(std::ostream &os, bool step_attempt_status, bool sAStatus, bool testedError, const TIAParams &tia_params);
214 
215 
216  // member data:
217 private:
219  WorkingIntegrationMethod & wimPtr_; /// Working integration method.
220  const std::string netlistFilename_;
221 
222 public:
223  // StepSize Variables
227  double lastTimeStep;
228  double minTimeStep;
229  double maxTimeStep;
232 
234 
235  double lastTime;
236  double currentTime;
237  double nextTime;
238  double stopTime;
239  double initialTime;
240  double finalTime;
241 
244 
247 
249 
250  int nIterations; ///< Number of newton iterations
251 
254 
255  // Needed for 2-level:
257  double estOverTol_;
259 
260  double pauseTime; ///< Time step value at which to "pause" the simulation.
261  bool pauseSetAtZero; ///< Flag used to indicate that a pause was specifically set at time zero and thus should not be ignored.
262 
263 private:
267  double tolAimFac_;
268 
269  Util::BreakPointLess breakPointLess_;
270 
271  BreakPointSet breakPoints_;
272  BreakPointSet::iterator currentPauseBP;
273 
274 private :
275  // 03/08/04 tscoffe: Local data for BDF 1-5 method
276  int currentOrder_; // Current order of integration
277  int oldOrder_; // previous order of integration
278  int minOrder_; // minimum order = max(1,user option minord)
279  int maxOrder_; // maximum order = min(5,user option maxord)
280  int usedOrder_; // order used in current step (used after currentOrder is updated)
281  double alphas_; // $\alpha_s$ fixed-leading coefficient of this BDF method
282  std::vector<double> alpha_; // $\alpha_j(n)=h_n/\psi_j(n)$ coefficient used in local error test
283  // note: $h_n$ = current step size, n = current time step
284  double alpha0_; // $-\sum_{j=1}^k \alpha_j(n)$ coefficient used in local error test
285  double cj_; // $-\alpha_s/h_n$ coefficient used in local error test
286  double ck_; // local error coefficient
287  std::vector<double> sigma_; // $\sigma_j(n) = \frac{h_n^j(j-1)!}{\psi_1(n)*\cdots *\psi_j(n)}$
288  std::vector<double> gamma_; // $\gamma_j(n)=\sum_{l=1}^{j-1}1/\psi_l(n)$ coefficient used to
289  // calculate time derivative of history array for predictor
290  std::vector<double> beta_; // coefficients used to evaluate predictor from history array
291  std::vector<double> psi_; // $\psi_j(n) = t_n-t_{n-j}$ intermediary variable used to
292  // compute $\beta_j(n)$
293  int numberOfSteps_; // number of total time integration steps taken
294  int nef_; // number of successive error failures (yes I know this is duplicated above)
295  double usedStep_; // step-size used in current step
296  int nscsco_; // Number of Steps taken with Constant Step-size and Constant Order
297  double Ek_,Ekm1_,Ekm2_,Ekp1_; // Estimated LTE at currentOrder, currentOrder-1, and currentOrder-2
298  double Est_; // Represents which of Ek,Ekm1,Ekm2 will be used for step-size selection
299  double Tk_,Tkm1_,Tkm2_,Tkp1_; // Estimated $\|h_n^{k+1} y_n^{(k+1)}\|$, basically, order * E
300  int newOrder_; // order of next step
301  bool initialPhase_; // determines if we're in the initial phase of integration where we
302  // double the step-size & increase the order.
303  double h0_safety_; // safety factor in picking initial step-size
304  double h0_max_factor_; // h0 <= h0_max_factor * length of integration time
305  double h_phase0_incr_; // amount to increase step-sizes during initial phase
306  double h_max_inv_; // inverse of maximum step size
307  double Tkm1_Tk_safety_; // magic number for determining order reduction
308  double Tkp1_Tk_safety_; // magic number for determining order reduction
309  double r_factor_; // basic reduction factor for rr
310  double r_safety_; // safety factor in computing rr
311  double r_fudge_; // fudge factor in computing rr
312  double r_min_; // minimum reduction factor
313  double r_max_; // maximum reduction factor
314  double r_hincr_test_; // threshold for increasing the step-size
315  double r_hincr_; // factor used for increasing the step-size
316  int max_LET_fail_; // max number of error test failures before quitting.
317 };
318 
319 //-----------------------------------------------------------------------------
320 // Function : operator<<
321 // Purpose : "<<" operator for step error control class.
322 // Special Notes :
323 // Scope : public
324 // Creator : Eric R. Keiter, SNL, Parallel Computational Sciences
325 // Creation Date : 10/17/05
326 //-----------------------------------------------------------------------------
327 std::ostream & operator<<(std::ostream & os, const StepErrorControl & sec);
328 
329 } // namespace TimeIntg
330 } // namespace Xyce
331 
332 #endif // Xyce_N_TIA_STEP_ERROR_CONTROL_H
bool initializeBreakPoints(double start_time, double initial_time, double final_time)
bool dumpRestartData(char *buf, int bsize, int &pos, N_PDS_Comm *comm, bool pack)
void evaluateStepError(const Loader::Loader &loader, const TIAParams &tia_params)
Pure virtual class to augment a linear system.
int nIterations
Number of newton iterations.
void updatePauseTime(Util::BreakPoint breakpoint, double initial_time)
StepErrorControl & operator=(const StepErrorControl &)
bool resetAll(const TIAParams &tia_params)
const Util::BreakPointLess & getBreakPointLess() const
bool setFromTIAParams(const TIAParams &tia_params)
WorkingIntegrationMethod & wimPtr_
Analysis manager.
std::set< Util::BreakPoint, Util::BreakPointLess > BreakPointSet
void updateStopTime(Parallel::Machine comm, bool breakpoints_enabled, double initial_time, bool min_time_steps_breakpoint_given, double min_time_steps_breakpoint)
double findNextStopTimeDeprecated(Parallel::Machine comm, bool breakpoints_enabled)
bool restoreRestartData(char *buf, int bsize, int &pos, N_PDS_Comm *comm, bool pack, double &initial_time)
StepErrorControl(const std::string &netlist_filename, Analysis::AnalysisManager &analysis_manager, WorkingIntegrationMethod &working_integration_method, const TIAParams &tia_params)
void updateTwoLevelTimeInfo(Parallel::Machine comm, double nextTimeStep, double nextTime, int currentOrder, bool breakpoints_enabled, double initial_time, bool min_time_steps_breakpoint_given, double min_time_steps_breakpoint)
std::ostream & operator<<(std::ostream &os, const StepErrorControl &sec)
void setBreakPoint(const Util::BreakPoint &breakpoint, double initial_time)
void simulationPaused(double initial_time)
Analysis::AnalysisManager & analysisManager_
double pauseTime
Time step value at which to "pause" the simulation.
bool pauseSetAtZero
Flag used to indicate that a pause was specifically set at time zero and thus should not be ignored...
void printBreakPoints(std::ostream &os) const
void integrationStepReport(std::ostream &os, bool step_attempt_status, bool sAStatus, bool testedError, const TIAParams &tia_params)
const std::string netlistFilename_
Working integration method.
bool updateMaxTimeStep(Parallel::Machine comm, Loader::Loader &loader, const TIAParams &tia_params, double suggestedMaxTimeStep=0.0)
void terseIntegrationStepReport(std::ostream &os, bool step_attempt_status, bool sAStatus, bool testedError, const TIAParams &tia_params)
bool updateBreakPoints(const Loader::Loader &loader, double initial_time)