libRoadRunner C++ API  1.3
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Pages
Integrator.h
Go to the documentation of this file.
1 // == PREAMBLE ================================================
2 
3 // * Licensed under the Apache License, Version 2.0; see README
4 
5 // == FILEDOC =================================================
6 
7 /** @file Integrator.h
8 * @author ETS, WBC, JKM
9 * @date Sep 7, 2013
10 * @copyright Apache License, Version 2.0
11 * @brief Contains the base class for RoadRunner integrators
12 **/
13 
14 # ifndef RR_INTEGRATOR_H_
15 # define RR_INTEGRATOR_H_
16 
17 // == INCLUDES ================================================
18 
19 # include "rrLogger.h"
20 # include "rrOSSpecifics.h"
21 # include "Dictionary.h"
22 # include "rrException.h"
23 # include "Solver.h"
24 
25 # include "tr1proxy/rr_memory.h"
26 # include "tr1proxy/rr_unordered_map.h"
27 # include <stdexcept>
28 
29 // == CODE ====================================================
30 
31 namespace rr
32 {
33 
34  class Integrator;
35  class ExecutableModel;
36 
37  /*-------------------------------------------------------------------------------------------
38  IntegratorListener listens for integrator events.
39  ---------------------------------------------------------------------------------------------*/
40  class IntegratorListener
41  {
42  public:
43 
44  /**
45  * is called after the internal integrator completes each internal time step.
46  */
47  virtual uint onTimeStep(Integrator* integrator, ExecutableModel* model, double time) = 0;
48 
49  /**
50  * whenever model event occurs and after it is procesed.
51  */
52  virtual uint onEvent(Integrator* integrator, ExecutableModel* model, double time) = 0;
53 
54  virtual ~IntegratorListener() {};
55  };
56 
57  typedef cxx11_ns::shared_ptr<IntegratorListener> IntegratorListenerPtr;
58 
59  /*-------------------------------------------------------------------------------------------
60  Integrator is an abstract base class that provides an interface to specific integrator
61  class implementations.
62  ---------------------------------------------------------------------------------------------*/
63  class RR_DECLSPEC Integrator : public Solver
64  {
65  public:
66  enum IntegrationMethod
67  {
68  Deterministic,
69  Stochastic,
70  Hybrid,
71  Other
72  };
73 
74  virtual ~Integrator() {};
75 
76  virtual IntegrationMethod getIntegrationMethod() const = 0;
77 
78  /**
79  * @author JKM
80  * @brief Called whenever a new model is loaded to allow integrator
81  * to reset internal state
82  */
83  virtual void syncWithModel(ExecutableModel* m);
84 
85  virtual void loadConfigSettings();
86  virtual void loadSBMLSettings(const std::string& filename);
87 
88  virtual double integrate(double t0, double hstep) = 0;
89  virtual void restart(double t0) = 0;
90 
91  /**
92  * @author JKM, WBC, ETS, MTK
93  * @brief Fix tolerances for SBML tests
94  * @details In order to ensure that the results of the SBML test suite
95  * remain valid, this method enforces a lower bound on tolerance values.
96  * Sets minimum absolute and relative tolerances to
97  * Config::CVODE_MIN_ABSOLUTE and Config::CVODE_MIN_RELATIVE resp.
98  */
99  virtual void tweakTolerances();
100 
101  /* CARRYOVER METHODS */
102  virtual void setListener(IntegratorListenerPtr) = 0;
103  virtual IntegratorListenerPtr getListener() = 0;
104  std::string toString() const;
105 
106  /**
107  * @author JKM
108  * @brief Return string representation a la Python __repr__ method
109  */
110  virtual std::string toRepr() const;
111  /* !-- END OF CARRYOVER METHODS */
112  };
113 
114 
115  class IntegratorException : public std::runtime_error
116  {
117  public:
118  explicit IntegratorException(const std::string& what) :
119  std::runtime_error(what)
120  {
121  Log(rr::Logger::LOG_ERROR) << __FUNC__ << "what: " << what;
122  }
123 
124  explicit IntegratorException(const std::string& what, const std::string &where) :
125  std::runtime_error(what + "; In " + where)
126  {
127  Log(rr::Logger::LOG_ERROR) << __FUNC__ << "what: " << what << ", where: " << where;
128  }
129  };
130 
131  /**
132  * @author JKM, WBC
133  * @brief Handles constructing an integrator and contains meta
134  * information about it
135  */
136  class RR_DECLSPEC IntegratorRegistrar
137  {
138  protected:
139  typedef Integrator* (*IntegratorCtor)(ExecutableModel *model);
140  public:
141  virtual ~IntegratorRegistrar();
142 
143  /**
144  * @author JKM, WBC
145  * @brief Gets the name associated with this integrator type
146  */
147  virtual std::string getName() const = 0;
148 
149  /**
150  * @author JKM, WBC
151  * @brief Gets the description associated with this integrator type
152  */
153  virtual std::string getDescription() const = 0;
154 
155  /**
156  * @author JKM, WBC
157  * @brief Gets the hint associated with this integrator type
158  */
159  virtual std::string getHint() const = 0;
160 
161  /**
162  * @author JKM, WBC
163  * @brief Constructs a new integrator of a given type
164  */
165  virtual Integrator* construct(ExecutableModel *model) const = 0;
166  };
167 
168  /**
169  * @author JKM, WBC
170  * @brief Constructs new integrators
171  * @details Implements the factory and singleton patterns.
172  * Constructs a new integrator given the name (e.g. cvode, gillespie)
173  * and returns a base pointer to @ref rr::Integrator.
174  */
175  class RR_DECLSPEC IntegratorFactory
176  {
177  public:
178  virtual ~IntegratorFactory();
179 
180  /**
181  * @author JKM, WBC
182  * @brief Constructs a new integrator given the name
183  * (e.g. cvode, gillespie)
184  */
185  Integrator* New(std::string name, ExecutableModel *m) const;
186 
187  /**
188  * @author JKM, WBC
189  * @brief Registers a new integrator with the factory
190  * so that it can be constructed
191  * @details Should be called at startup for new integrators.
192  */
193  void registerIntegrator(IntegratorRegistrar* i);
194 
195  /**
196  * @author JKM, WBC
197  * @brief Returns the singleton instance of the integrator factory
198  */
199  static IntegratorFactory& getInstance();
200 
201  // ** Indexing *********************************************************
202 
203  std::size_t getNumIntegrators() const;
204 
205  std::string getIntegratorName(std::size_t n) const;
206 
207  std::string getIntegratorHint(std::size_t n) const;
208 
209  std::string getIntegratorDescription(std::size_t n) const;
210 
211  private:
212  /**
213  * @author JKM, WBC
214  * @brief Prevents external instantiation
215  */
216  IntegratorFactory() {}
217  typedef std::vector<IntegratorRegistrar*> IntegratorRegistrars;
218  IntegratorRegistrars mRegisteredIntegrators;
219  };
220 
221 }
222 
223 # endif /* RR_INTEGRATOR_H_ */
Constructs new integrators.
Definition: Integrator.h:175
Definition: CVODEIntegrator.cpp:26
Contains the base class for RoadRunner solvers.
Base class for all code generation systems; allows compiling and evaluating the model.
Definition: rrExecutableModel.h:127
Handles constructing an integrator and contains meta information about it.
Definition: Integrator.h:136