00001 ///////////////////////////////////////////////////////////////////////////////////////// 00002 /// \file ctrls.h 00003 /// \brief Header file for the definition of the SPARK::TRuntimeControls class 00004 /// 00005 /// The SPARK::TRuntimeControls class is a wrapper class around all run-time control data 00006 /// needed to run a %SPARK problem. It also provides access and predicate methods for each 00007 /// runtime control. 00008 /// 00009 ///////////////////////////////////////////////////////////////////////////////////////// 00010 /// \attention 00011 /// PORTIONS COPYRIGHT (C) 2003 AYRES SOWELL ASSOCIATES, INC. \n 00012 /// PORTIONS COPYRIGHT (C) 2003 THE REGENTS OF THE UNIVERSITY OF CALIFORNIA . 00013 /// PENDING APPROVAL BY THE US DEPARTMENT OF ENERGY. ALL RIGHTS RESERVED. 00014 /// 00015 ///////////////////////////////////////////////////////////////////////////////////////// 00016 /// \author Dimitri Curtil (LBNL/SRG) 00017 /// \date January 15, 2003 00018 ///////////////////////////////////////////////////////////////////////////////////////// 00019 00020 00021 // Gets rid of warning messages about dll-interface for private data member 00022 // Message shows typically with std classes, e.g., std::string 00023 #pragma warning(disable:4251) 00024 00025 00026 #if !defined(__CTRLS_H__) 00027 #define __CTRLS_H__ 00028 00029 #include <ctime> 00030 #include <cstdlib> 00031 #include <cmath> 00032 #include <iosfwd> 00033 #include <vector> 00034 #include <string> 00035 00036 #include "exceptions.h" // for SPARK::XInitialization, SPARK::XIO 00037 #include "compat.h" // for CLASS_DECLSPEC 00038 00039 00040 ///////////////////////////////////////////////////////////////////////////////////////// 00041 /// \namespace SPARK::DefaultRuntimeControls 00042 /// \brief Default controls are defined in this namespace. The default controls are used 00043 /// if no entry is found in the *.run file for the control in question. 00044 ///////////////////////////////////////////////////////////////////////////////////////// 00045 namespace SPARK { namespace DefaultRuntimeControls { 00046 00047 const double InitialTime = 0.0; ///< Default initial time 00048 const double FinalTime = 0.0; ///< Default final time 00049 00050 const double InitialTimeStep = 1.0; ///< Default initial time step value 00051 const double MinTimeStep = 1.0e-6; ///< Default min time step value [feature added in %SPARK 2.0] 00052 const double MaxTimeStep = 1.0e+6; ///< Default max time step value [feature added in %SPARK 2.0] 00053 00054 const double ReportCycle = InitialTimeStep; ///< Default report cycle is equal to initial time step 00055 const double FirstReport = InitialTime; ///< Default first report is at inital time 00056 00057 const unsigned VariableTimeStep = 0; ///< Constant time step mode by default [feature added in %SPARK 2.0] 00058 const unsigned ConsistentInitialCalculation = 1; ///< Consistent initalization calculation is required by default [feature added in %SPARK 2.0] 00059 const unsigned DiagnosticLevel = 0; ///< Silent diagnostic mode by default 00060 00061 // Default max number of successively rejected steps allowed before aborting simulation 00062 // with TProblem::SimulatorState_FAILED_STEP. 00063 const unsigned MaxRejectedStepCount = 20; 00064 00065 }; }; // namespace SPARK::DefaultRuntimeControls 00066 ///////////////////////////////////////////////////////////////////////////////////////// 00067 00068 00069 00070 ///////////////////////////////////////////////////////////////////////////////////////// 00071 namespace SPARK { 00072 00073 ///////////////////////////////////////////////////////////////////////////////////// 00074 // Forward declaration 00075 ///////////////////////////////////////////////////////////////////////////////////// 00076 class TPrefList; 00077 00078 00079 ///////////////////////////////////////////////////////////////////////////////////// 00080 /// \class TRuntimeControls 00081 /// \brief Wrapper class for all the runtime control information required to initialize a 00082 /// TProblem object in order to make a simulation run. 00083 class CLASS_DECLSPEC TRuntimeControls 00084 { 00085 public: 00086 ///////////////////////////////////////////////////////////////////////////////// 00087 // Type definition 00088 ///////////////////////////////////////////////////////////////////////////////// 00089 00090 /// Type used to describe the list of input files specified in the *.run file with the key \c InputFiles 00091 typedef std::vector<std::string> TInputFiles; 00092 00093 00094 ///////////////////////////////////////////////////////////////////////////////// 00095 /// \name Structors 00096 //@{ 00097 /// Loads default controls 00098 TRuntimeControls(const char* name); 00099 /// \brief Loads controls from file "runFileName" 00100 /// 00101 /// \exception SPARK::XInitialization Thrown if the runtime controls could not be validated. 00102 TRuntimeControls(const char* name, const char* runFileName) SPARK_THROWING( (SPARK::XInitialization) ); 00103 /// Trivial destructor 00104 ~TRuntimeControls() SPARK_NOT_THROWING; 00105 //@} 00106 ///////////////////////////////////////////////////////////////////////////////// 00107 00108 00109 ///////////////////////////////////////////////////////////////////////////////// 00110 /// \name Access methods 00111 //@{ 00112 /// Returns name of runtime controls as <code>const char*</code> 00113 const char* GetName() const { return Name.c_str(); } 00114 /// Returns name of the *.run file as <code>const char*</code> 00115 const char* GetRunFileName() const { return RunFileName.c_str(); } 00116 00117 /// \brief Returns the name of the initial snapshot file as <code>const char*</code> 00118 /// \note By default, no initial snapshot file will be generated. 00119 const char* GetInitialSnapshotFileName() const { return InitialSnapshotFileName.c_str(); } 00120 /// Sets the name of the initial snapshot file to <code>str</code> 00121 void SetInitialSnapshotFileName(const char* str) { InitialSnapshotFileName = str; } 00122 00123 /// \brief Returns the name of the final snapshot file as <code>const char*</code> 00124 /// \note By default, no final snapshot file will be generated. 00125 const char* GetFinalSnapshotFileName() const { return FinalSnapshotFileName.c_str(); } 00126 /// Sets the name of the final snapshot file to <code>str</code> 00127 void SetFinalSnapshotFileName(const char* str) { FinalSnapshotFileName = str; } 00128 00129 /// Returns a reference to the TInputFiles object that contains the list of the input files specified in the *.run file 00130 TInputFiles& GetInputFiles() { return InputFiles; } 00131 /// Returns a const reference to the TInputFiles object that contains the list of the input files specified in the *.run file 00132 const TInputFiles& GetInputFiles() const { return InputFiles; } 00133 00134 /// Returns the name of the output file as <code>const char*</code> where the variables tagged with the \c REPORT keyword are reported 00135 const char* GetOutputFileName() const { return OutFileName.c_str(); } 00136 /// Sets the name of the output file to <code>filename</code> where the variables tagged with the \c REPORT keyword will be reported 00137 void SetOutputFileName(const char* filename) { OutFileName = filename; } 00138 00139 /// \brief Returns the string describing the initial wall clock as <code>const char*</code> 00140 /// 00141 /// The format of the initial wall clock string follows: "mm/dd/yyyy hh:mm:ss" 00142 /// 00143 /// \note The initial wall clock string is parsed by the URL engine and is used for 00144 /// synchronization with various weather files. 00145 const char* GetInitialWallClock() const { return InitialWallClock.c_str(); } 00146 /// Sets the string describing the initial wall clock to <code>str</code> 00147 void SetInitialWallClock(const char* str) { InitialWallClock = str; } 00148 00149 /// \brief Returns the string describing the time unit used in the physical model as <code>const char*</code> 00150 /// 00151 /// \li The time unit is used by the URL engine to initialize the weather file readers with the 00152 /// proper time unit used in the simulation model. 00153 /// 00154 /// \li Also, this time unit will be used to override the unit strings in the global time and global time step 00155 /// variables in the physical model for consistency reasons. 00156 /// 00157 /// \note It should be a unit string reecognized by the URL engine. 00158 const char* GetTimeUnit() const { return TimeUnit.c_str(); } 00159 /// Sets the string describing the time unit used in the physical model to <code>str</code> 00160 void SetTimeUnit(const char* str) { TimeUnit = str; } 00161 00162 /// Returns the number of successive past values that the problem simulator keeps track of as \c unsigned 00163 unsigned GetNumPastValues() const { return NumPastValues; } 00164 /// Sets the number of successive past values that the problem simulator keeps track of to \c numPastValues 00165 void SetNumPastValues(unsigned numPastValues) { NumPastValues = numPastValues; } 00166 00167 /// \brief Returns the diagnostic level as \c unsigned 00168 /// 00169 /// The possible values for the diagnostic level are defined in TProblem::DiagnosticTypes 00170 /// 00171 /// \note The value 0 indicates that no diagnostic will be generated at runtime. 00172 unsigned GetDiagnosticLevel() const { return DiagnosticLevel; } 00173 /// Sets the diagnostic level to \c level 00174 void SetDiagnosticLevel(unsigned level) { DiagnosticLevel = level; } 00175 00176 /// Returns the initial time value as \c double 00177 double GetInitialTime() const { return InitialTime; } 00178 /// Sets the initial time value to \c initialTime 00179 void SetInitialTime(double initialTime) { InitialTime = initialTime; } 00180 00181 /// Returns the final time value as \c double 00182 double GetFinalTime() const { return FinalTime; } 00183 /// Sets the final time value to \c finalTime 00184 void SetFinalTime(double finalTime) { FinalTime = finalTime; } 00185 /// \brief Sets the final time value to infinity. 00186 /// 00187 /// The problem simulator will not stopped unless a stop request, abort request or a 00188 /// set stop time request is posted. 00189 /// This is equivalent to specifying <CODE>FinalTime( * ())</CODE> in the *.run file. 00190 void SetInfiniteFinalTime(); 00191 00192 /// \brief Returns the value of the intial time step as \c double 00193 /// 00194 /// \note If the value is zero, then the clock will not be advanced and only one step 00195 /// will be calculated. 00196 double GetInitialTimeStep() const { return InitialTimeStep; } 00197 /// Sets the value of the initial time step to \c initialTimeStep 00198 void SetInitialTimeStep(double initialTimeStep) { InitialTimeStep = initialTimeStep; } 00199 00200 /// Returns the value for the minimum time step allowed as \c double 00201 double GetMinTimeStep() const { return MinTimeStep; } 00202 /// Sets the value for the minimum time step allowed to \c minTimeStep 00203 void SetMinTimeStep(double minTimeStep) { MinTimeStep = minTimeStep; } 00204 00205 /// Returns the value for the maximum time step allowed as \c double 00206 double GetMaxTimeStep() const { return MaxTimeStep; } 00207 /// Sets the value for the maximum time step allowed to \c maxTimeStep 00208 void SetMaxTimeStep(double maxTimeStep) { MaxTimeStep = maxTimeStep; } 00209 00210 /// Returns the time for the first report to be generated as \c double 00211 double GetFirstReport() const { return FirstReport; } 00212 /// Sets the time of the first report to \c firstReport 00213 void SetFirstReport(double firstReport) { FirstReport = firstReport; } 00214 00215 /// \brief Returns the time step used to generate the reports as \c double 00216 /// 00217 /// This report time step is independent from the simulation time step. 00218 /// However, if the simulation supports variable time stepping, then 00219 /// the simultation time step will be adapted to synchronize with the 00220 /// \c i desired reporting times \f$t_{report}[i]\f$: 00221 /// \f$t_{report}[i] = FirstReport + i * ReportCycle\f$ 00222 /// 00223 /// \note If \f$ReportCycle==0\f$, then reports are generate at each 00224 /// simulation step. 00225 double GetReportCycle() const { return ReportCycle; } 00226 /// Sets the time step used to generate the reports to \c reportCycle 00227 void SetReportCycle(double reportCycle) { ReportCycle = reportCycle; } 00228 00229 /// \brief Returns the flag that controls whether variable time stepping operation is on or off as \c unsigned 00230 /// 00231 /// \li If <code>VariableTimeStep==0</code> then the time step remains constant during the 00232 /// course of the simulation. 00233 /// \li If <code>VariableTimeStep==1</code> then the time step is adapted to satisfy the meeting 00234 /// points and the time step requests during the course of the simulation. 00235 unsigned GetVariableTimeStep() const { return VariableTimeStep; } 00236 /// Sets the flag taht controls whether variable time stepping operation is on or off to \c flag 00237 void SetVariableTimeStep(unsigned flag) { VariableTimeStep = flag; } 00238 00239 /// \brief Returns the flag that controls whether or not to perform an initial consistent 00240 /// calculation for the first step of the simulation as \c unsigned 00241 /// 00242 /// \li If <code>ConsistentInitialCalculation == 0</code> then no initial calculation is performed. 00243 /// \li If <code>ConsistentInitialCalculation == 1</code> then an initial calculation is performed 00244 /// in order to ensure a consistent of initial values. 00245 /// 00246 /// The initial consistent calculation consists in computing a static step to solve for the 00247 /// time-derivatives, the dynamic variables being set to their user-specified initial values. 00248 /// 00249 /// \note It is highly recommended to perform an initial consistent calculation for dynamic 00250 /// problems to make sure that the integrator classes do rely on a consistent set of 00251 /// initial conditions. 00252 /// Otherwise, it is likely that the initial error will accumulate and is likely to 00253 /// produce an inaccurate dynamic solution. 00254 unsigned GetConsistentInitialCalculation() const { return ConsistentInitialCalculation; } 00255 /// Sets the flag that controls whether or not to perform an initial consistent 00256 /// calculation for the first step of the simulation to \c flag 00257 void SetConsistentInitialCalculation(unsigned flag) { ConsistentInitialCalculation = flag; } 00258 //@} 00259 ///////////////////////////////////////////////////////////////////////////////// 00260 00261 ///////////////////////////////////////////////////////////////////////////////// 00262 // Not yet documented. Do not use! 00263 ///////////////////////////////////////////////////////////////////////////////// 00264 unsigned GetNumInnerValues() const { return NumInnerValues; } 00265 void SetNumInnerValues(unsigned numInnerValues) { NumInnerValues = numInnerValues; } 00266 00267 unsigned long GetMaxRejectedStepCount() const { return MaxRejectedStepCount; } 00268 void SetMaxRejectedStepCount(unsigned long count) { MaxRejectedStepCount = count; } 00269 00270 00271 ///////////////////////////////////////////////////////////////////////////////// 00272 /// \name I/O Operations 00273 //@{ 00274 /// Writes the runtime controls to \c os 00275 void Write(std::ostream& os, const std::string& before) const; 00276 //@} 00277 ///////////////////////////////////////////////////////////////////////////////// 00278 00279 00280 ///////////////////////////////////////////////////////////////////////////////// 00281 /// \name Misc operation 00282 //@{ 00283 /// \brief Checks specified controls and returns the number of invalid controls 00284 /// 00285 /// \note This method is called in TRuntimeControls(const char* runFileName). 00286 /// If using the default constructor TRuntimeControls(), then you should call this 00287 /// method explicitly to make sure that the controls are valid. 00288 unsigned ValidateControls(std::ostream& os) const; 00289 /// \brief Resets all controls to the default values. 00290 /// 00291 /// See namespace SPARK::DefaultRuntimeControls for the list of the default controls. 00292 void Reset(); 00293 //@} 00294 ///////////////////////////////////////////////////////////////////////////////// 00295 00296 00297 private: 00298 ///////////////////////////////////////////////////////////////////////////////// 00299 /// \name Operations 00300 //@{ 00301 /// Sets the name of the *.run file with the runtime controls expressed in the preference format. 00302 /// 00303 /// \exception SPARK::XInitialization Thrown if file name is invalid. 00304 void SetRunFileName(const char* name) SPARK_THROWING( (SPARK::XInitialization) ); 00305 00306 /// Loads all runtime controls from the file named runFileName. 00307 /// 00308 /// \exception SPARK::XIO Thrown if file could not be opened. 00309 void LoadFromFile(const char* runFileName) SPARK_THROWING( (SPARK::XIO) ); 00310 void LoadFromPreferences(SPARK::TPrefList* prefList); 00311 void LoadFromSTDIN(); 00312 void LoadInputFiles(SPARK::TPrefList* prefList); ///> populates TRuntimeControls::InputFileNames 00313 //@} 00314 ///////////////////////////////////////////////////////////////////////////////// 00315 00316 00317 ///////////////////////////////////////////////////////////////////////////////// 00318 /// \name Predicate methods 00319 //@{ 00320 bool AreUrlDefaultSettings() const; 00321 //@} 00322 ///////////////////////////////////////////////////////////////////////////////// 00323 00324 00325 private: 00326 ///////////////////////////////////////////////////////////////////////////////// 00327 // Data 00328 std::string Name; ///< Controls name 00329 std::string RunFileName; ///< "*.run" file name 00330 std::string OutFileName; ///< "*.out" file name 00331 std::string FinalSnapshotFileName; ///< snapshot file name with last computed values 00332 std::string InitialSnapshotFileName;///< snapshot file name with initial values 00333 TInputFiles InputFiles; ///< collection of "*.inp" file names specified under key "InputFiles" 00334 00335 std::string TimeUnit; ///< used by URL engine 00336 std::string InitialWallClock; ///< used by URL engine 00337 00338 double InitialTime; ///< Initial time of the simulation 00339 double FinalTime; ///< Final time of the simulation 00340 00341 unsigned VariableTimeStep; ///< If set to 1, then simulator is in variable time step mode. Otherwise in constant time step mode. 00342 00343 unsigned ConsistentInitialCalculation; ///< If set to 1, then a static step forces a consistent initial calculation 00344 unsigned long MaxRejectedStepCount; ///< Max number of steps that can be rejected successively before aborting 00345 00346 double InitialTimeStep; ///< Initial time step. Also value of the constant time step if VariableTimeStep==0 00347 double MinTimeStep; ///< Minimum time step allowed 00348 double MaxTimeStep; ///< Maximum time step allowed 00349 00350 double ReportCycle; ///< Reporting cycle. If set to 0.0, then all steps are reported 00351 double FirstReport; ///< Indicates when to start reporting 00352 unsigned DiagnosticLevel; ///< Used to write diagnostic to the output stream over the course of the simulation. See enum TProblem::TDiagnosticLevel 00353 00354 unsigned NumPastValues; ///< Number of past values that are being kept track of 00355 unsigned NumInnerValues; ///< Number of inner values that are being kept track of 00356 00357 // Declared as mutable variables because of the update at runtime scheme that 00358 // updates the next variables at every step, therefore breakng the constness assumption 00359 // for the methods used by the TProblem object 00360 mutable time_t LastTimeModified; 00361 00362 /// \deprecated Decommissioned following code as of SPARK 2 00363 /// unsigned UpdatePrfFileAtRunTime; 00364 /// bool UpdateComponentPreferencesAtRunTime() const; 00365 }; 00366 ///////////////////////////////////////////////////////////////////////////////////// 00367 00368 00369 }; // namespace SPARK 00370 ///////////////////////////////////////////////////////////////////////////////////////// 00371 00372 00373 #endif // __CTRLS_H__ 00374 00375