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 
44 
47 
50 
52  double progressStep;
53 
55  RunOptions(void) :
56  subValueCount(1),
57  subValueId(0),
58  useSparse(false),
59  nullValue(FLT_MIN),
60  isDbMicrodata(false),
61  isCsvMicrodata(false),
62  isTraceMicrodata(false),
63  progressPercent(0),
64  progressStep(0.0)
65  { }
66  ~RunOptions(void) noexcept { }
67 
69  bool isMicrodata(void) const { return isDbMicrodata || isCsvMicrodata || isTraceMicrodata; }
70 
72  bool isTextMicrodata(void) const { return isCsvMicrodata || isTraceMicrodata; }
73  };
74 
76  struct IRunOptions
77  {
78  virtual ~IRunOptions(void) noexcept = 0;
79 
81  virtual bool isOptionExist(const char * i_key) const noexcept = 0;
82 
84  virtual std::string strOption(const char * i_key, const std::string & i_default = "") const noexcept = 0;
85 
87  virtual bool boolOption(const char * i_key) const noexcept = 0;
88 
95  virtual int boolOptionToInt(const char * i_key) const noexcept = 0;
96 
98  virtual int intOption(const char * i_key, int i_default) const noexcept = 0;
99 
101  virtual long long longOption(const char * i_key, long long i_default) const noexcept = 0;
102 
104  virtual double doubleOption(const char * i_key, double i_default) const noexcept = 0;
105 
107  virtual std::vector<std::pair<std::string, std::string>> allOptions(void) const noexcept = 0;
108  };
109 
111  struct IRunBase : public IRunOptions
112  {
113  virtual ~IRunBase(void) noexcept = 0;
114 
116  virtual int parameterIdByName(const char * i_name) const = 0;
117 
119  virtual int parameterSubCount(int i_paramId) const = 0;
120 
122  virtual int parameterSelfSubCount(int i_paramId) const = 0;
123 
125  virtual int parameterSubValueIndex(int i_paramId, int i_subId) const = 0;
126 
128  virtual bool isUseSubValue(int i_subId) const = 0;
129 
131  virtual void readParameter(const char * i_name, int i_subId, const std::type_info & i_type, size_t i_size, void * io_valueArr) = 0;
132  };
133 
135  struct IModel
136  {
137  virtual ~IModel(void) noexcept = 0;
138 
140  virtual int subValueCount(void) const noexcept = 0;
141 
143  virtual int subValueId(void) const noexcept = 0;
144 
146  virtual int tableIdByName(const char * i_name) const = 0;
147 
149  virtual bool isSuppressed(const char * i_name) const = 0;
150 
152  virtual const RunOptions * runOptions(void) const = 0;
153 
155  virtual int parameterSubValueIndex(const char * i_name) const = 0;
156 
158  virtual void writeOutputTable(const char * i_name, size_t i_size, std::forward_list<std::unique_ptr<double[]> > & io_accValues) = 0;
159 
161  virtual void updateProgress(int i_count, double i_value = 0.0) = 0;
162 
169  virtual void writeDbMicrodata(int i_entityKind, uint64_t i_microdataKey, const void * i_entityThis) = 0;
170 
179  virtual void writeCsvMicrodata(int i_entityKind, uint64_t i_microdataKey, int i_eventId, bool i_isSameEntity, const void * i_entityThis) = 0;
180  };
181 
184  {
186  const char * name;
187 
189  const std::type_info & typeOf;
190 
192  const size_t size;
193  };
194 
196  extern const size_t PARAMETER_NAME_ARR_LEN;
197 
200 
203  {
205  int entityId;
206 
208  const char * entity;
209 
212 
214  const char * attribute;
215 
217  const std::type_info & typeOf;
218 
220  const size_t size;
221 
223  const ptrdiff_t offset;
224 
226  static int byName(const char * i_entityName, const char * i_attrName);
227  };
228 
230  extern const size_t ENTITY_NAME_SIZE_ARR_LEN;
231 
233  extern const EntityNameSizeItem EntityNameSizeArr[];
234 
235  struct EventIdNameItem; // model events id, name
236 
238  extern const EventIdNameItem EventIdNameArr[];
239 
241  extern const size_t EVENT_ID_NAME_ARR_LEN;
242 
245  {
247  int eventId;
248 
250  const char * eventName;
251 
253  static const char * byId(int i_eventId);
254 
256  static bool checkId(int i_eventId)
257  {
258  return EVENT_ID_NAME_ARR_LEN > 0 &&
259  (i_eventId == EventIdNameArr[0].eventId ||
260  (0 < i_eventId + 1 && i_eventId + 1 < (int)EVENT_ID_NAME_ARR_LEN));
261  }
262  };
263 
265  #define OM_USE_MICRODATA_EVENTS (EVENT_ID_NAME_ARR_LEN > 1)
266 
268  extern const char modelUnknownErrorMessage[];
269 
272 
274  extern const char simulationUnknownErrorMessage[];
275 
278 
280  template<typename TVal> std::vector<TVal> read_om_parameter(IRunBase * const i_runBase, const char * i_name)
281  {
282  int paramId = i_runBase->parameterIdByName(i_name);
283  int allCount = i_runBase->parameterSubCount(paramId); // number of parameter sub-values
284  int selfCount = i_runBase->parameterSelfSubCount(paramId); // number of sub-values for current process
285 
286  // storage array: parameter values for current process
287  // extra parameter value for exchange between root and child process
288  std::vector<TVal> valueVec(selfCount);
289  TVal extraVal;
290  bool isStr = typeid(TVal) == typeid(std::string); // no default null values for string parameters
291 
292  // read sub-values and place into storage array or send to child process
293  for (int nSub = 0; nSub < allCount; nSub++) {
294 
295  void * pData = &extraVal;
296  if (!isStr) {
297  extraVal = std::numeric_limits<TVal>::quiet_NaN(); // set default null value
298  }
299  i_runBase->readParameter(i_name, nSub, typeid(TVal), 1, pData);
300 
301  if (allCount <= 1) {
302  valueVec[0] = extraVal;
303  }
304  else {
305  if (i_runBase->isUseSubValue(nSub)) valueVec[i_runBase->parameterSubValueIndex(paramId, nSub)] = extraVal;
306  }
307  }
308  return valueVec;
309  }
310 
312  template<typename TVal> std::vector<std::unique_ptr<TVal[]>> read_om_parameter(IRunBase * const i_runBase, const char * i_name, size_t i_size)
313  {
314  int paramId = i_runBase->parameterIdByName(i_name);
315  int allCount = i_runBase->parameterSubCount(paramId); // number of parameter sub-values
316  int selfCount = i_runBase->parameterSelfSubCount(paramId); // number of sub-values for current process
317 
318  if (i_size <= 0) throw ModelException("invalid size: %zd of parameter %s", i_size, i_name);
319 
320  // storage array: parameter values for current process
321  std::vector<std::unique_ptr<TVal[]>> valueVec(selfCount);
322  for (auto & p : valueVec) {
323  p.reset(new TVal[i_size]);
324  }
325 
326  std::unique_ptr<TVal> extraVal; // extra parameter value for exchange between root and child process
327  if (allCount > 1) {
328  extraVal.reset(new TVal[i_size]);
329  }
330  bool isStr = typeid(TVal) == typeid(std::string); // no default null values for string parameters
331 
332  // read sub-values and place into storage array or send to child process
333  for (int nSub = 0; nSub < allCount; nSub++) {
334 
335  void * pData = valueVec[0].get();
336  if (allCount > 1) {
337  pData =
338  i_runBase->isUseSubValue(nSub) ?
339  valueVec[i_runBase->parameterSubValueIndex(paramId, nSub)].get() :
340  extraVal.get();
341  }
342  // set default null values and read parameter
343  if (!isStr) {
344  std::fill(static_cast<TVal *>(pData), &(static_cast<TVal *>(pData))[i_size], std::numeric_limits<TVal>::quiet_NaN());
345  }
346  i_runBase->readParameter(i_name, nSub, typeid(TVal), i_size, pData);
347  }
348  return valueVec;
349  }
350 }
351 
352 //
353 // modeling library import and export
354 //
355 #ifdef __cplusplus
356  extern "C" {
357 #endif
358 
360 extern const char * OM_MODEL_NAME;
361 
363 extern const char * OM_MODEL_DIGEST;
364 
366 int main(int argc, char ** argv);
367 
369 typedef void(*OM_RUN_ONCE_HANDLER)(openm::IRunBase * const i_runBase);
371 
373 typedef void(*OM_RUN_INIT_HANDLER)(openm::IRunBase * const i_runBase);
375 
377 typedef void(*OM_STARTUP_HANDLER)(openm::IModel * const i_model);
379 
381 typedef void (*OM_EVENT_LOOP_HANDLER)(openm::IModel * const i_model);
383 
385 typedef void (*OM_SHUTDOWN_HANDLER)(openm::IModel * const i_model);
387 
390 
391 #ifdef __cplusplus
392  }
393 #endif
394 
395 #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:271
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:280
const ParameterNameSizeItem parameterNameSizeArr[]
model input parameters name, type and size
const EventIdNameItem EventIdNameArr[]
list of events id, name
const char modelUnknownErrorMessage[]
default error message: "unknown model error"
Definition: modelBase.cpp:14
const size_t EVENT_ID_NAME_ARR_LEN
size of event list: all events in all entities
const size_t PARAMETER_NAME_ARR_LEN
size of parameters list: number of model input parameters
const size_t ENTITY_NAME_SIZE_ARR_LEN
size of entity attributes list: all attributes of all entities
const char simulationUnknownErrorMessage[]
simulation exception default error message: "unknown error in simulation"
Definition: modelBase.cpp:17
OpenmException< 4000, simulationUnknownErrorMessage > SimulationException
simulation exception
Definition: omModel.h:277
const EntityNameSizeItem EntityNameSizeArr[]
list of entity attributes name, type, size and member offset
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:377
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:381
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:369
void(* OM_SHUTDOWN_HANDLER)(openm::IModel *const i_model)
model shutdown method: save output results
Definition: omModel.h:385
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:373
OpenM++ modeling library: model run state public interface.
model entity attributes name, type, size and member offset
Definition: omModel.h:203
const ptrdiff_t offset
attribute value offset in entity this
Definition: omModel.h:223
const char * attribute
attribute name
Definition: omModel.h:214
int entityId
entity metadata id in database
Definition: omModel.h:205
int attributeId
attribute metadata id in database
Definition: omModel.h:211
const char * entity
entity name
Definition: omModel.h:208
const std::type_info & typeOf
attribute value type
Definition: omModel.h:217
const size_t size
attribute value bytes size
Definition: omModel.h:220
model events id, name
Definition: omModel.h:245
int eventId
event id
Definition: omModel.h:247
const char * eventName
event name
Definition: omModel.h:250
static bool checkId(int i_eventId)
return true if event id valid
Definition: omModel.h:256
model sub-value run public interface
Definition: omModel.h:136
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 void writeCsvMicrodata(int i_entityKind, uint64_t i_microdataKey, int i_eventId, bool i_isSameEntity, const void *i_entityThis)=0
write microdata into CSV file or into trace.
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.
virtual void writeDbMicrodata(int i_entityKind, uint64_t i_microdataKey, const void *i_entityThis)=0
write microdata into the database.
model run state public interface: thread safe
Definition: omModelRunState.h:139
public interface to initialize model run and input parameters
Definition: omModel.h:112
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:77
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:184
const size_t size
parameter size (number of parameter values)
Definition: omModel.h:192
const std::type_info & typeOf
value type
Definition: omModel.h:189
const char * name
input parameter name
Definition: omModel.h:186
basic model run options
Definition: omModel.h:26
bool isMicrodata(void) const
retrun true if any microdata output enabled
Definition: omModel.h:69
bool isTraceMicrodata
if true then model run is writing microdata into trace output
Definition: omModel.h:46
double progressStep
if positive then used for simulation progress reporting, ex: every 1000 cases or every 0....
Definition: omModel.h:52
bool isTextMicrodata(void) const
retrun true if microdata output to text enabled: output to CSV or to trace
Definition: omModel.h:72
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:49
bool isCsvMicrodata
if true then model run is writing microdata into CSV
Definition: omModel.h:43
int subValueId
sub-value index for current modeling thread
Definition: omModel.h:31
bool isDbMicrodata
if true then model run is storing microdata in database
Definition: omModel.h:40
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:55