00001 ///////////////////////////////////////////////////////////////////////////////////////// 00002 /// \file component.h 00003 /// \brief Declaration of the SPARK::TComponent class 00004 /// 00005 ///////////////////////////////////////////////////////////////////////////////////////// 00006 /// 00007 /// \author Dimitri Curtil (LBNL/SRG) 00008 /// \date September 9, 2002 00009 /// 00010 ///////////////////////////////////////////////////////////////////////////////////////// 00011 /// \attention 00012 /// PORTIONS COPYRIGHT (C) 2003 AYRES SOWELL ASSOCIATES, INC. \n 00013 /// PORTIONS COPYRIGHT (C) 2003 THE REGENTS OF THE UNIVERSITY OF CALIFORNIA . 00014 /// PENDING APPROVAL BY THE US DEPARTMENT OF ENERGY. ALL RIGHTS RESERVED. 00015 /// 00016 ///////////////////////////////////////////////////////////////////////////////////////// 00017 00018 00019 // This hides the compilation warnings produced by VC++ when a class/struct does not specify a 00020 // dll-interface for the its data to be used by clients 00021 #pragma warning(disable:4251) 00022 00023 00024 #if !defined(__COMPONENT_H__) 00025 #define __COMPONENT_H__ 00026 00027 #include <iosfwd> 00028 #include <string> 00029 #include <memory> 00030 00031 #include "container.h" 00032 00033 #include "compat.h" 00034 #include "numeric.h" // for SPARK numerical exceptions 00035 #include "variable.h" 00036 00037 00038 00039 ///////////////////////////////////////////////////////////////////////////////////////////// 00040 namespace SPARK { 00041 00042 ///////////////////////////////////////////////////////////////////////////////////////// 00043 // Forward declaration 00044 ///////////////////////////////////////////////////////////////////////////////////////// 00045 class TProblem; 00046 class TTopology; 00047 class TObject; 00048 class TEquationSystem; 00049 class TJacobian; 00050 class TNonLinearSolver; 00051 00052 class TGlobalSettings; 00053 class TComponentSettings; 00054 00055 class TTimer; 00056 class TContext; 00057 00058 class TResidualsTracer; 00059 class TIncrementsTracer; 00060 class TVariablesTracer; 00061 class TJacobianTracer; 00062 class TBacktrackingTracer; 00063 00064 00065 00066 ///////////////////////////////////////////////////////////////////////////////////////// 00067 /// \class TComponent 00068 /// \brief Class that solves the set of DAE equations generated by setupcpp. 00069 /// 00070 /// A problem consists of a series of TComponent objects that are solved in a fixed order, 00071 /// from the first component (with index 0) to the last component. The order in which the 00072 /// components need to be solved reflects the topological dependencies derived by setupcpp. 00073 /// 00074 class CLASS_DECLSPEC TComponent 00075 { 00076 public: 00077 ///////////////////////////////////////////////////////////////////////////////////// 00078 // Type definition 00079 ///////////////////////////////////////////////////////////////////////////////////// 00080 00081 /// Type to indicate whether a component consists of a set of weakly- or strongly-connected equations 00082 enum ComponentTypes { 00083 ComponentType_WEAK = 0, ///< Indicates a weakly-connected component that is solved using forward substitution. 00084 ComponentType_STRONG = 1 ///< Indicates a strongly-connected component that requires iterative solution. 00085 }; 00086 00087 typedef SPARK::view_container< SPARK::TObject* > TObjects; 00088 00089 00090 ///////////////////////////////////////////////////////////////////////////////////// 00091 // Structors 00092 ///////////////////////////////////////////////////////////////////////////////////// 00093 00094 /// Constructor 00095 TComponent( 00096 unsigned handle, 00097 unsigned numNormalUnknowns, SPARK::TUnknown normalUnknowns[], 00098 unsigned numBreakUnknowns, SPARK::TUnknown breakUnknowns[], 00099 unsigned numObjects, SPARK::TObject* objects[] 00100 ) 00101 SPARK_THROWING( (SPARK::XMemory) ) 00102 SPARK_RETHROWING( (SPARK::XAssertion) ); 00103 /// Destructor 00104 ~TComponent() SPARK_NOT_THROWING; 00105 00106 00107 ///////////////////////////////////////////////////////////////////////////////////// 00108 // Main operations invoked from TProblem 00109 ///////////////////////////////////////////////////////////////////////////////////// 00110 00111 void Activate(SPARK::TTopology* topology) SPARK_THROWING( (SPARK::XInitialization) ); 00112 void Reset(); // Called when starting a new simulation to reset solvers 00113 00114 void Initialize(bool showDiagnostic) SPARK_RETHROWING( (SPARK::XAssertion) ); 00115 void Terminate(); 00116 00117 /// \brief Solves the set of differential-algebraic equations 00118 /// 00119 /// \exception SPARK::XNoConvergence Thrown if convergence cannot be obtained. 00120 /// \exception SPARK::XBadNumerics Thrown if bad numerics detected. 00121 void Evaluate(); 00122 00123 void Commit(); 00124 void Rollback(); // Load values at the end of last converged step 00125 00126 void ReportStatistics(std::ostream& os, const std::string& before) const; 00127 00128 00129 ///////////////////////////////////////////////////////////////////////////////////// 00130 // Trace file mechanism 00131 ///////////////////////////////////////////////////////////////////////////////////// 00132 void CreateVariablesTracer(const char* traceFileName) SPARK_RETHROWING( (SPARK::XAssertion) ); 00133 void CreateResidualsTracer(const char* traceFileName) SPARK_RETHROWING( (SPARK::XAssertion) ); 00134 void CreateIncrementsTracer(const char* traceFileName) SPARK_RETHROWING( (SPARK::XAssertion) ); 00135 void CreateJacobianTracer(const char* traceFileName) SPARK_RETHROWING( (SPARK::XAssertion) ); 00136 void CreateBacktrackingTracer(const char* traceFileName) SPARK_RETHROWING( (SPARK::XAssertion) ); 00137 00138 00139 ///////////////////////////////////////////////////////////////////////////////////// 00140 // Settings for component solving method 00141 ///////////////////////////////////////////////////////////////////////////////////// 00142 00143 // Load controls from settings for the solvers 00144 void SetupSolver(const SPARK::TGlobalSettings& globalSettings) 00145 SPARK_THROWING( (SPARK::XInitialization) ) 00146 SPARK_RETHROWING( (SPARK::XAssertion) ); 00147 00148 void SetSettings(const SPARK::TComponentSettings& settings); 00149 SPARK::TComponentSettings& GetSettings(); 00150 const SPARK::TComponentSettings& GetSettings() const; 00151 void WriteSettings(std::ostream& os) const; // Used by tracers in header section 00152 00153 00154 ///////////////////////////////////////////////////////////////////////////////////// 00155 // Access methods 00156 ///////////////////////////////////////////////////////////////////////////////////// 00157 const SPARK::TProblem* GetProblem() const { return Problem; } 00158 SPARK::TProblem* GetProblem() { return Problem; } 00159 00160 SPARK::TEquationSystem* GetEquationSystem() { return EquationSystem.get(); } 00161 const SPARK::TEquationSystem* GetEquationSystem() const { return EquationSystem.get(); } 00162 00163 SPARK::TNonLinearSolver* GetNonLinearSolver() { return NonLinearSolver.get(); } 00164 const SPARK::TNonLinearSolver* GetNonLinearSolver() const { return NonLinearSolver.get(); } 00165 00166 SPARK::TJacobian* GetJacobian() { return Jacobian.get(); } 00167 const SPARK::TJacobian* GetJacobian() const { return Jacobian.get(); } 00168 00169 00170 /// \brief Returns the name of the component as const char* 00171 const char* GetName() const { return Name.c_str(); } 00172 /// \brief Returns the unique handle assigne to this component as an unsigned int 00173 unsigned GetHandle() const { return Handle; } 00174 /// \brief Returns the component type as unsigned (see enum TComponent::TType) 00175 unsigned GetType() const { return Type; } 00176 const SPARK::TContext& GetContext() const { return *Context; } 00177 00178 /// \brief Returns the number of objects comprising this component 00179 unsigned GetNumObjects() const { return Objects.size(); } 00180 /// \brief Returns a pointer to the TObject object evaluated in position i 00181 /// \note The first object evaluated in this component is stored in position 0. 00182 SPARK::TObject* GetObject(unsigned i) { return Objects[i]; } 00183 /// \brief Returns a const pointer to the TObject object evaluated in position i 00184 /// \note The first object evaluated in this component is stored in position 0. 00185 const SPARK::TObject* GetObject(unsigned i) const { return Objects[i]; } 00186 00187 00188 // Forward calls to SPARK::TEquationSystem 00189 double GetCallCount() const; // We return the count as a double to avoid overflow 00190 unsigned GetNumPredictors() const; 00191 unsigned GetNumEvaluators() const; 00192 00193 00194 // Forward calls to TProblem (used by SPARK::TTracer and SPARK::TContext objects) 00195 const TVariable& GetGlobalTime() const; 00196 const TVariable& GetGlobalTimeStep() const; 00197 unsigned GetStepCount() const; 00198 00199 00200 // Statistics 00201 double GetElaspedTime_Tracers() const; 00202 double GetElapsedTime_NonlinearSolver() const ; 00203 double GetElapsedTime_LinearSolver() const ; 00204 00205 00206 ///////////////////////////////////////////////////////////////////////////////////// 00207 // Predicate methods 00208 ///////////////////////////////////////////////////////////////////////////////////// 00209 00210 /// \brief Returns true if this component is a strongly-connected component. 00211 bool IsStronglyConnected() const { return (Type == ComponentType_STRONG); } 00212 00213 00214 ///////////////////////////////////////////////////////////////////////////////////// 00215 // I/O operations 00216 ///////////////////////////////////////////////////////////////////////////////////// 00217 void WriteStamp(std::ostream& os) const; 00218 00219 00220 private: 00221 ///////////////////////////////////////////////////////////////////////////////////// 00222 // Private Methods 00223 ///////////////////////////////////////////////////////////////////////////////////// 00224 TComponent(const TComponent& ); // Copy constructor 00225 TComponent& operator=(const TComponent& ); 00226 00227 void IterativeSolution() SPARK_THROWING( (SPARK::XBadNumerics, SPARK::XBadJacobian, SPARK::XNoConvergence) ); // For strongly-connected components 00228 void ForwardSubstitution() SPARK_THROWING( (SPARK::XBadNumerics) ); // For weakly-connected components 00229 00230 unsigned UpdateSettings(const SPARK::TComponentSettings& settings);// Update some settings at run-time 00231 00232 ///////////////////////////////////////////////////////////////////////////////////// 00233 // Private Data 00234 ///////////////////////////////////////////////////////////////////////////////////// 00235 unsigned Handle; ///< Unique ID for this component, used to build Name 00236 const std::string Name; ///< Name of component (error reporting) 00237 std::auto_ptr<SPARK::TContext> Context; ///< Used to report warning /errors to ostream, to convey calling context 00238 const ComponentTypes Type; ///< Does this component require iterative solution? 00239 00240 const std::auto_ptr<SPARK::TTimer> Timer; ///< To estimate CPU time 00241 SPARK::TProblem* Problem; ///< Pointer to owner problem 00242 TObjects Objects; ///< Container with object pointers 00243 00244 // Settings for solution method (as specified in *.prf file) 00245 std::auto_ptr<SPARK::TComponentSettings> Settings; ///< Pointer to the currently active component settings 00246 00247 // Pimpl design pattern 00248 std::auto_ptr<SPARK::TEquationSystem> EquationSystem; 00249 std::auto_ptr<SPARK::TJacobian> Jacobian; 00250 std::auto_ptr<SPARK::TNonLinearSolver> NonLinearSolver; 00251 00252 // Data required for tracing mechanism 00253 std::auto_ptr<SPARK::TVariablesTracer> VariablesTracer; ///< Traces values of unknowns at each iteration 00254 std::auto_ptr<SPARK::TResidualsTracer> ResidualsTracer; ///< Traces residuals and residual norm at each iteration 00255 std::auto_ptr<SPARK::TIncrementsTracer> IncrementsTracer; ///< Traces increments, increment norm and relaxation coefficient at each iteration 00256 std::auto_ptr<SPARK::TJacobianTracer> JacobianTracer; ///< Traces partial derivatives each time they are calculated 00257 std::auto_ptr<SPARK::TBacktrackingTracer> BacktrackingTracer; ///< Only used in SPARK_DEBUG mode to trace the backtracking process! 00258 00259 }; 00260 ///////////////////////////////////////////////////////////////////////////////////////// 00261 00262 00263 }; // namespace SPARK 00264 ///////////////////////////////////////////////////////////////////////////////////////////// 00265 00266 00267 #endif // __COMPONENT_H__ 00268 00269 00270