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.105.2.1 $
41 //
42 // Revision Date : $Date: 2015/04/02 18:20:18 $
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 <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, const TIAParams &tia_params, double suggestedMaxTimeStep=0.0);
130 
132  Parallel::Machine comm,
133  const TimeIntInfo & tiInfo,
134  bool breakpoints_enabled,
135  double initial_time,
136  bool min_time_steps_breakpoint_given,
137  double min_time_steps_breakpoint);
138 
139  // Print out the time-step information.
140  void outputTimeInfo(std::ostream &os);
141 
142  int getNumberOfSteps() const {
143  return numberOfSteps_;
144  }
145 
146  // Requests dynamic breakpoint information from the loader. Adds, subtracts
147  // from the breakpoints array.
148  bool updateBreakPoints(double initial_time);
149 
150  // add individual breakpoints
151  void setBreakPoint(const Util::BreakPoint &breakpoint, double initial_time);
152  void setBreakPoint(double bp);
153 
154  // signal that pause breakpoint has been reached
155  void simulationPaused(double initial_time);
156 
157  // is the current time a pause time?
158  bool isPauseTime();
159 
160  // Sets the minimum time step based on machine precision.
161  bool updateMinTimeStep();
162 
163  bool isFinished();
164 
165  void evaluateStepError(const TIAParams &tia_params);
166 
167  // Gets the size of the restart data.
168  int getRestartDataSize( bool pack );
169 
170  // Output restart data.
171  bool dumpRestartData(char * buf, int bsize, int & pos, N_PDS_Comm * comm, bool pack );
172 
173  // Load restart data.
174  bool restoreRestartData(char * buf, int bsize, int & pos, N_PDS_Comm * comm, bool pack, double &initial_time);
175 
176  // called if you want to start the time integration over from scratch.
177  bool resetAll(const TIAParams &tia_params);
178 
179  // Method which sets the TIA parameters object pointer.
180  bool setFromTIAParams(const TIAParams &tia_params);
181 
182  void printBreakPoints (std::ostream & os) const;
183 
184  double getEstOverTol() const;
185 
186  void setTimeStep(double newTimeStep);
187 
188 private:
189  bool initializeBreakPoints(double start_time, double initial_time, double final_time);
190 
191  void updatePauseTime(Util::BreakPoint breakpoint, double initial_time);
192 
193  void integrationStepReport(std::ostream &os, bool step_attempt_status, bool sAStatus, bool testedError, const TIAParams &tia_params);
194 
195  void terseIntegrationStepReport(std::ostream &os, bool step_attempt_status, bool sAStatus, bool testedError, const TIAParams &tia_params);
196 
197 
198  // member data:
199 private:
201  WorkingIntegrationMethod & wimPtr_; /// Working integration method.
202  const std::string netlistFilename_;
203 
204 public:
205  // StepSize Variables
209  double lastTimeStep;
210  double minTimeStep;
211  double maxTimeStep;
214 
216 
217  double lastTime;
218  double currentTime;
219  double nextTime;
220  double stopTime;
221  double initialTime;
222  double finalTime;
223 
226 
229 
231 
232  int nIterations; ///< Number of newton iterations
233 
236 
237  // Needed for 2-level:
239  double estOverTol_;
241 
242  double pauseTime; ///< Time step value at which to "pause" the simulation.
243  bool pauseSetAtZero; ///< Flag used to indicate that a pause was specifically set at time zero and thus should not be ignored.
244 
245 private:
249  double tolAimFac_;
250 
251  Util::BreakPointLess breakPointLess_;
252 
253  BreakPointSet breakPoints_;
254  BreakPointSet::iterator currentPauseBP;
255 
256 private :
257  // 03/08/04 tscoffe: Local data for BDF 1-5 method
258  int currentOrder_; // Current order of integration
259  int oldOrder_; // previous order of integration
260  int minOrder_; // minimum order = max(1,user option minord)
261  int maxOrder_; // maximum order = min(5,user option maxord)
262  int usedOrder_; // order used in current step (used after currentOrder is updated)
263  double alphas_; // $\alpha_s$ fixed-leading coefficient of this BDF method
264  std::vector<double> alpha_; // $\alpha_j(n)=h_n/\psi_j(n)$ coefficient used in local error test
265  // note: $h_n$ = current step size, n = current time step
266  double alpha0_; // $-\sum_{j=1}^k \alpha_j(n)$ coefficient used in local error test
267  double cj_; // $-\alpha_s/h_n$ coefficient used in local error test
268  double ck_; // local error coefficient
269  std::vector<double> sigma_; // $\sigma_j(n) = \frac{h_n^j(j-1)!}{\psi_1(n)*\cdots *\psi_j(n)}$
270  std::vector<double> gamma_; // $\gamma_j(n)=\sum_{l=1}^{j-1}1/\psi_l(n)$ coefficient used to
271  // calculate time derivative of history array for predictor
272  std::vector<double> beta_; // coefficients used to evaluate predictor from history array
273  std::vector<double> psi_; // $\psi_j(n) = t_n-t_{n-j}$ intermediary variable used to
274  // compute $\beta_j(n)$
275  int numberOfSteps_; // number of total time integration steps taken
276  int nef_; // number of successive error failures (yes I know this is duplicated above)
277  double usedStep_; // step-size used in current step
278  int nscsco_; // Number of Steps taken with Constant Step-size and Constant Order
279  double Ek_,Ekm1_,Ekm2_,Ekp1_; // Estimated LTE at currentOrder, currentOrder-1, and currentOrder-2
280  double Est_; // Represents which of Ek,Ekm1,Ekm2 will be used for step-size selection
281  double Tk_,Tkm1_,Tkm2_,Tkp1_; // Estimated $\|h_n^{k+1} y_n^{(k+1)}\|$, basically, order * E
282  int newOrder_; // order of next step
283  bool initialPhase_; // determines if we're in the initial phase of integration where we
284  // double the step-size & increase the order.
285  double h0_safety_; // safety factor in picking initial step-size
286  double h0_max_factor_; // h0 <= h0_max_factor * length of integration time
287  double h_phase0_incr_; // amount to increase step-sizes during initial phase
288  double h_max_inv_; // inverse of maximum step size
289  double Tkm1_Tk_safety_; // magic number for determining order reduction
290  double Tkp1_Tk_safety_; // magic number for determining order reduction
291  double r_factor_; // basic reduction factor for rr
292  double r_safety_; // safety factor in computing rr
293  double r_fudge_; // fudge factor in computing rr
294  double r_min_; // minimum reduction factor
295  double r_max_; // maximum reduction factor
296  double r_hincr_test_; // threshold for increasing the step-size
297  double r_hincr_; // factor used for increasing the step-size
298  int max_LET_fail_; // max number of error test failures before quitting.
299 };
300 
301 //-----------------------------------------------------------------------------
302 // Function : StepErrorControl::finished
303 // Purpose : This function is called by the time integraion algorithm
304 // class to determine if the main time integration while
305 // loop should end.
306 // Special Notes :
307 // Scope : public
308 // Creator : Eric Keiter, SNL, Parallel ComputationalSciences.
309 // Creation Date : 10/11/00
310 //-----------------------------------------------------------------------------
312 {
313  double delta = currentTime - finalTime;
314 
315  delta = std::fabs(delta);
316  return (delta < 1.0e-10 * (finalTime - initialTime));
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)
Pure virtual class to augment a linear system.
int nIterations
Number of newton iterations.
void updateTwoLevelTimeInfo(Parallel::Machine comm, const TimeIntInfo &tiInfo, bool breakpoints_enabled, double initial_time, bool min_time_steps_breakpoint_given, double min_time_steps_breakpoint)
bool updateMaxTimeStep(Parallel::Machine comm, const TIAParams &tia_params, double suggestedMaxTimeStep=0.0)
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)
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)
bool updateBreakPoints(double initial_time)
void evaluateStepError(const TIAParams &tia_params)
const std::string netlistFilename_
Working integration method.
void terseIntegrationStepReport(std::ostream &os, bool step_attempt_status, bool sAStatus, bool testedError, const TIAParams &tia_params)