OpenM++ runtime library (libopenm)
omModel.h
Go to the documentation of this file.
1 
5 // Copyright (c) 2013-2015 OpenM++
6 // This code is licensed under the MIT license (see LICENSE.txt for details)
7 
8 #ifndef OM_H_MODEL_H
9 #define OM_H_MODEL_H
10 
11 #include <memory>
12 #include <cfloat>
13 #include <forward_list>
14 #include <type_traits>
15 #include <typeinfo>
16 #include <vector>
17 
18 #include "omModelRunState.h"
19 #include "omLog.h"
20 #include "omError.h"
21 
22 namespace openm
23 {
25  struct RunOptions
26  {
29 
32 
34  bool useSparse;
35 
37  double nullValue;
38 
41 
43  double progressStep;
44 
46  RunOptions(void) :
47  subValueCount(1),
48  subValueId(0),
49  useSparse(false),
50  nullValue(FLT_MIN),
51  progressPercent(0),
52  progressStep(0.0)
53  { }
54  ~RunOptions(void) noexcept { }
55  };
56 
58  struct IRunOptions
59  {
60  virtual ~IRunOptions(void) noexcept = 0;
61 
63  virtual bool isOptionExist(const char * i_key) const noexcept = 0;
64 
66  virtual std::string strOption(const char * i_key, const std::string & i_default = "") const noexcept = 0;
67 
69  virtual bool boolOption(const char * i_key) const noexcept = 0;
70 
77  virtual int boolOptionToInt(const char * i_key) const noexcept = 0;
78 
80  virtual int intOption(const char * i_key, int i_default) const noexcept = 0;
81 
83  virtual long long longOption(const char * i_key, long long i_default) const noexcept = 0;
84 
86  virtual double doubleOption(const char * i_key, double i_default) const noexcept = 0;
87 
89  virtual std::vector<std::pair<std::string, std::string>> allOptions(void) const noexcept = 0;
90  };
91 
93  struct IRunBase : public IRunOptions
94  {
95  virtual ~IRunBase(void) noexcept = 0;
96 
98  virtual int parameterIdByName(const char * i_name) const = 0;
99 
101  virtual int parameterSubCount(int i_paramId) const = 0;
102 
104  virtual int parameterSelfSubCount(int i_paramId) const = 0;
105 
107  virtual int parameterSubValueIndex(int i_paramId, int i_subId) const = 0;
108 
110  virtual bool isUseSubValue(int i_subId) const = 0;
111 
113  virtual void readParameter(const char * i_name, int i_subId, const std::type_info & i_type, size_t i_size, void * io_valueArr) = 0;
114  };
115 
117  struct IModel
118  {
119  virtual ~IModel(void) noexcept = 0;
120 
122  virtual int subValueCount(void) const noexcept = 0;
123 
125  virtual int subValueId(void) const noexcept = 0;
126 
128  virtual int tableIdByName(const char * i_name) const = 0;
129 
131  virtual bool isSuppressed(const char * i_name) const = 0;
132 
134  virtual const RunOptions * runOptions(void) const = 0;
135 
137  virtual int parameterSubValueIndex(const char * i_name) const = 0;
138 
140  virtual void writeOutputTable(const char * i_name, size_t i_size, std::forward_list<std::unique_ptr<double[]> > & io_accValues) = 0;
141 
143  virtual void updateProgress(int i_count, double i_value = 0.0) = 0;
144  };
145 
148  {
150  const char * name;
151 
153  const std::type_info & typeOf;
154 
156  const size_t size;
157  };
158 
160  extern const size_t PARAMETER_NAME_ARR_LEN;
161 
164 
166  extern const char modelUnknownErrorMessage[];
167 
170 
172  extern const char simulationUnknownErrorMessage[];
173 
176 
178  template<typename TVal> std::vector<TVal> read_om_parameter(IRunBase * const i_runBase, const char * i_name)
179  {
180  int paramId = i_runBase->parameterIdByName(i_name);
181  int allCount = i_runBase->parameterSubCount(paramId); // number of parameter sub-values
182  int selfCount = i_runBase->parameterSelfSubCount(paramId); // number of sub-values for current process
183 
184  // storage array: parameter values for current process
185  // extra parameter value for exchange between root and child process
186  std::vector<TVal> valueVec(selfCount);
187  TVal extraVal;
188  bool isStr = typeid(TVal) == typeid(std::string); // no default null values for string parameters
189 
190  // read sub-values and place into storage array or send to child process
191  for (int nSub = 0; nSub < allCount; nSub++) {
192 
193  void * pData = &extraVal;
194  if (!isStr) {
195  extraVal = std::numeric_limits<TVal>::quiet_NaN(); // set default null value
196  }
197  i_runBase->readParameter(i_name, nSub, typeid(TVal), 1, pData);
198 
199  if (allCount <= 1) {
200  valueVec[0] = extraVal;
201  }
202  else {
203  if (i_runBase->isUseSubValue(nSub)) valueVec[i_runBase->parameterSubValueIndex(paramId, nSub)] = extraVal;
204  }
205  }
206  return valueVec;
207  }
208 
210  template<typename TVal> std::vector<std::unique_ptr<TVal[]>> read_om_parameter(IRunBase * const i_runBase, const char * i_name, size_t i_size)
211  {
212  int paramId = i_runBase->parameterIdByName(i_name);
213  int allCount = i_runBase->parameterSubCount(paramId); // number of parameter sub-values
214  int selfCount = i_runBase->parameterSelfSubCount(paramId); // number of sub-values for current process
215 
216  if (i_size <= 0) throw ModelException("invalid size: %zd of parameter %s", i_size, i_name);
217 
218  // storage array: parameter values for current process
219  std::vector<std::unique_ptr<TVal[]>> valueVec(selfCount);
220  for (auto & p : valueVec) {
221  p.reset(new TVal[i_size]);
222  }
223 
224  std::unique_ptr<TVal> extraVal; // extra parameter value for exchange between root and child process
225  if (allCount > 1) {
226  extraVal.reset(new TVal[i_size]);
227  }
228  bool isStr = typeid(TVal) == typeid(std::string); // no default null values for string parameters
229 
230  // read sub-values and place into storage array or send to child process
231  for (int nSub = 0; nSub < allCount; nSub++) {
232 
233  void * pData = valueVec[0].get();
234  if (allCount > 1) {
235  pData =
236  i_runBase->isUseSubValue(nSub) ?
237  valueVec[i_runBase->parameterSubValueIndex(paramId, nSub)].get() :
238  extraVal.get();
239  }
240  // set default null values and read parameter
241  if (!isStr) {
242  std::fill(static_cast<TVal *>(pData), &(static_cast<TVal *>(pData))[i_size], std::numeric_limits<TVal>::quiet_NaN());
243  }
244  i_runBase->readParameter(i_name, nSub, typeid(TVal), i_size, pData);
245  }
246  return valueVec;
247  }
248 }
249 
250 //
251 // modeling library import and export
252 //
253 #ifdef __cplusplus
254  extern "C" {
255 #endif
256 
258 extern const char * OM_MODEL_NAME;
259 
261 extern const char * OM_MODEL_DIGEST;
262 
264 int main(int argc, char ** argv);
265 
267 typedef void(*OM_RUN_ONCE_HANDLER)(openm::IRunBase * const i_runBase);
269 
271 typedef void(*OM_RUN_INIT_HANDLER)(openm::IRunBase * const i_runBase);
273 
275 typedef void(*OM_STARTUP_HANDLER)(openm::IModel * const i_model);
277 
279 typedef void (*OM_EVENT_LOOP_HANDLER)(openm::IModel * const i_model);
281 
283 typedef void (*OM_SHUTDOWN_HANDLER)(openm::IModel * const i_model);
285 
288 
289 #ifdef __cplusplus
290  }
291 #endif
292 
293 #endif // OM_H_MODEL_H
openM++ exceptions
Definition: omError.h:19
openM++ namespace
Definition: log.h:32
OpenmException< 4000, modelUnknownErrorMessage > ModelException
modeling library exception
Definition: omModel.h:169
std::vector< TVal > read_om_parameter(IRunBase *const i_runBase, const char *i_name)
read scalar parameter value or all sub-values for the current process
Definition: omModel.h:178
const ParameterNameSizeItem parameterNameSizeArr[]
model input parameters name, type and size
const char modelUnknownErrorMessage[]
default error message: "unknown model error"
Definition: modelBase.cpp:12
const size_t PARAMETER_NAME_ARR_LEN
size of parameters list: number of model input parameters
const char simulationUnknownErrorMessage[]
simulation exception default error message: "unknown error in simulation"
Definition: modelBase.cpp:15
OpenmException< 4000, simulationUnknownErrorMessage > SimulationException
simulation exception
Definition: omModel.h:175
OpenM++: public interface for errors and exceptions.
OpenM++: public interface for log and trace support.
const char * OM_MODEL_NAME
model name
openm::IModelRunState * theModelRunState
public interface of process-wide model run state: status, progress, update times
Definition: modelRunState.cpp:33
void(* OM_STARTUP_HANDLER)(openm::IModel *const i_model)
model startup method: initialize sub-value
Definition: omModel.h:275
OM_SHUTDOWN_HANDLER ModelShutdownHandler
model shutdown method: save output results
Definition: main.cpp:64
int main(int argc, char **argv)
main entry point
Definition: main.cpp:79
OM_STARTUP_HANDLER ModelStartupHandler
model startup method: initialize sub-value
Definition: main.cpp:58
OM_RUN_ONCE_HANDLER RunOnceHandler
model one-time initialization
Definition: main.cpp:52
void(* OM_EVENT_LOOP_HANDLER)(openm::IModel *const i_model)
model event loop: user code entry point
Definition: omModel.h:279
OM_RUN_INIT_HANDLER RunInitHandler
model run initialization: read input parameters
Definition: main.cpp:55
void(* OM_RUN_ONCE_HANDLER)(openm::IRunBase *const i_runBase)
model one-time initialization
Definition: omModel.h:267
void(* OM_SHUTDOWN_HANDLER)(openm::IModel *const i_model)
model shutdown method: save output results
Definition: omModel.h:283
OM_EVENT_LOOP_HANDLER RunModelHandler
model event loop: user code entry point
Definition: main.cpp:61
const char * OM_MODEL_DIGEST
model metadata digest: unique model key
void(* OM_RUN_INIT_HANDLER)(openm::IRunBase *const i_runBase)
model run initialization: read input parameters
Definition: omModel.h:271
OpenM++ modeling library: model run state public interface.
model sub-value run public interface
Definition: omModel.h:118
virtual void updateProgress(int i_count, double i_value=0.0)=0
set modeling progress count and value
virtual const RunOptions * runOptions(void) const =0
return basic model run options
virtual int subValueCount(void) const noexcept=0
number of sub-values
virtual int tableIdByName(const char *i_name) const =0
return id of output table by name
virtual int parameterSubValueIndex(const char *i_name) const =0
return index of parameter sub-value in the storage array for current modeling thread
virtual int subValueId(void) const noexcept=0
sub-value index of current modeling thread
virtual void writeOutputTable(const char *i_name, size_t i_size, std::forward_list< std::unique_ptr< double[]> > &io_accValues)=0
write output result table: sub values
virtual bool isSuppressed(const char *i_name) const =0
check by name if output table suppressed.
model run state public interface: thread safe
Definition: omModelRunState.h:139
public interface to initialize model run and input parameters
Definition: omModel.h:94
virtual int parameterSubValueIndex(int i_paramId, int i_subId) const =0
return index of parameter sub-value in the storage array of sub-values
virtual void readParameter(const char *i_name, int i_subId, const std::type_info &i_type, size_t i_size, void *io_valueArr)=0
read model parameter
virtual int parameterSelfSubCount(int i_paramId) const =0
number of parameter sub-values for current process
virtual int parameterSubCount(int i_paramId) const =0
number of parameter sub-values
virtual bool isUseSubValue(int i_subId) const =0
return true if sub-value used by current process
virtual int parameterIdByName(const char *i_name) const =0
return id of parameter by name
public interface to get model run options
Definition: omModel.h:59
virtual bool isOptionExist(const char *i_key) const noexcept=0
return true if run option found by i_key in run_option table for the current run id.
virtual int boolOptionToInt(const char *i_key) const noexcept=0
search for boolean value of run option by i_key and return one of: return 1 if key found and value i...
virtual double doubleOption(const char *i_key, double i_default) const noexcept=0
return double value of run option by i_key or default if not found or can not be converted to double.
virtual long long longOption(const char *i_key, long long i_default) const noexcept=0
return long value of run option by i_key or default if not found or can not be converted to long.
virtual std::vector< std::pair< std::string, std::string > > allOptions(void) const noexcept=0
return a copy of all run options as [key, value] pairs, ordered by key.
virtual std::string strOption(const char *i_key, const std::string &i_default="") const noexcept=0
return string value of run option by i_key or default value if not found.
virtual int intOption(const char *i_key, int i_default) const noexcept=0
return int value of run option by i_key or default if not found or can not be converted to int.
virtual bool boolOption(const char *i_key) const noexcept=0
return boolean value of run option by i_key or false if not found or value is not "yes",...
model input parameter name, type and size
Definition: omModel.h:148
const size_t size
parameter size (number of parameter values)
Definition: omModel.h:156
const std::type_info & typeOf
value type
Definition: omModel.h:153
const char * name
input parameter name
Definition: omModel.h:150
basic model run options
Definition: omModel.h:26
double progressStep
if positive then used for simulation progress reporting, ex: every 1000 cases or every 0....
Definition: omModel.h:43
bool useSparse
if true then use sparse output to database
Definition: omModel.h:34
int progressPercent
if positive then used for simulation progress reporting, ex: every 10%
Definition: omModel.h:40
int subValueId
sub-value index for current modeling thread
Definition: omModel.h:31
int subValueCount
number of sub-values
Definition: omModel.h:28
double nullValue
if use sparse and abs(value) <= nullValue then value not stored
Definition: omModel.h:37
RunOptions(void)
init run options with default values
Definition: omModel.h:46