org.simantics.fmil.core/native/FMILibrary/src/Import/include/FMI2/fmi2_import.h

   1 /*\r
   2     Copyright (C) 2012 Modelon AB\r
   3 \r
   4     This program is free software: you can redistribute it and/or modify\r
   5     it under the terms of the BSD style license.\r
   6 \r
   7     This program is distributed in the hope that it will be useful,\r
   8     but WITHOUT ANY WARRANTY; without even the implied warranty of\r
   9     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  10     FMILIB_License.txt file for more details.\r
  11 \r
  12     You should have received a copy of the FMILIB_License.txt file\r
  13     along with this program. If not, contact Modelon AB <http://www.modelon.com>.\r
  14 */\r
  15 \r
  16 /** \file fmi2_import.h\r
  17 *  \brief Public interface to the FMI import C-library.\r
  18 */\r
  19 \r
  20 #ifndef FMI2_IMPORT_H_\r
  21 #define FMI2_IMPORT_H_\r
  22 \r
  23 #include <stddef.h>\r
  24 #include <fmilib_config.h>\r
  25 #include <JM/jm_callbacks.h>\r
  26 #include <FMI/fmi_import_util.h>\r
  27 #include <FMI/fmi_import_context.h>\r
  28 /* #include <FMI2/fmi2_xml_model_description.h> */\r
  29 \r
  30 #include <FMI2/fmi2_types.h>\r
  31 #include <FMI2/fmi2_functions.h>\r
  32 #include <FMI2/fmi2_enums.h>\r
  33 \r
  34 #include "fmi2_import_type.h"\r
  35 #include "fmi2_import_unit.h"\r
  36 #include "fmi2_import_variable.h"\r
  37 #include "fmi2_import_variable_list.h"\r
  38 \r
  39 #include "fmi2_import_capi.h"\r
  40 #include "fmi2_import_convenience.h"\r
  41 \r
  42 #ifdef __cplusplus\r
  43 extern "C" {\r
  44 #endif\r
  45 \r
  46 /**\r
  47  * \addtogroup  fmi2_import FMI 2.0 import interface\r
  48  *  All the structures used in the interfaces are intended to\r
  49  *  be treated as opaque objects by the client code.\r
  50  @{ \r
  51  */\r
  52 \r
  53 /**     \addtogroup fmi2_import_init Constuction, destruction and error handling\r
  54  *      \addtogroup fmi2_import_gen General information retrieval\r
  55  *      \addtogroup fmi2_import_capi Interface to the standard FMI 2.0 "C" API\r
  56  *  \brief Convenient functions for calling the FMI functions. This interface wrappes the "C" API. \r
  57  */\r
  58  /** @} */\r
  59  /** @} */\r
  60 \r
  61 /** \addtogroup fmi2_import_init Constuction, destruction and error handling\r
  62 @{\r
  63 */\r
  64 \r
  65 /**\r
  66 * \brief Retrieve the last error message.\r
  67 *\r
  68 * Error handling:\r
  69 *\r
  70 *  Many functions in the library return pointers to struct. An error is indicated by returning NULL/0-pointer.\r
  71 *  If error is returned than fmi2_import_get_last_error() functions can be used to retrieve the error message.\r
  72 *  If logging callbacks were specified then the same information is reported via logger.\r
  73 *  Memory for the error string is allocated and deallocated in the module.\r
  74 *  Client code should not store the pointer to the string since it can become invalid.\r
  75 *    @param fmu An FMU object as returned by fmi2_import_parse_xml().\r
  76 *    @return NULL-terminated string with an error message.\r
  77 */\r
  78 FMILIB_EXPORT const char* fmi2_import_get_last_error(fmi2_import_t* fmu);\r
  79 \r
  80 /**\r
  81 \brief Clear the error message.\r
  82 * @param fmu An FMU object as returned by fmi2_import_parse_xml().\r
  83 * @return 0 if further processing is possible. If it returns 1 then the \r
  84 *       error was not recoverable. The \p fmu object should then be freed and recreated.\r
  85 */\r
  86 FMILIB_EXPORT int fmi2_import_clear_last_error(fmi2_import_t* fmu);\r
  87 \r
  88 /**\r
  89 \brief Release the memory allocated\r
  90 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
  91 */\r
  92 FMILIB_EXPORT void fmi2_import_free(fmi2_import_t* fmu);\r
  93 /** @}\r
  94 \addtogroup fmi2_import_gen\r
  95  * \brief Functions for retrieving general model information. Memory for the strings is allocated and deallocated in the module.\r
  96  *   All the functions take an FMU object as returned by fmi2_import_parse_xml() as a parameter. \r
  97  *   The information is retrieved from the XML file.\r
  98  * @{\r
  99 */\r
 100 /** \r
 101 \brief Get model name. \r
 102 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 103 */\r
 104 FMILIB_EXPORT const char* fmi2_import_get_model_name(fmi2_import_t* fmu);\r
 105 \r
 106 /** \brief Retrieve capability flags by ID. */\r
 107 FMILIB_EXPORT unsigned int fmi2_import_get_capability(fmi2_import_t* , fmi2_capabilities_enu_t id);\r
 108 \r
 109 /** \r
 110 \brief Get model identifier for ModelExchange. \r
 111 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 112 */\r
 113 FMILIB_EXPORT const char* fmi2_import_get_model_identifier_ME(fmi2_import_t* fmu);\r
 114 \r
 115 /** \r
 116 \brief Get model identifier for CoSimulation. \r
 117 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 118 */\r
 119 FMILIB_EXPORT const char* fmi2_import_get_model_identifier_CS(fmi2_import_t* fmu);\r
 120 \r
 121 /** \r
 122 \brief Get FMU GUID. \r
 123 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 124 */\r
 125 FMILIB_EXPORT const char* fmi2_import_get_GUID(fmi2_import_t* fmu);\r
 126 \r
 127 /** \r
 128 \brief Get FMU description.\r
 129 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 130 */\r
 131 FMILIB_EXPORT const char* fmi2_import_get_description(fmi2_import_t* fmu);\r
 132 \r
 133 /** \r
 134 \brief Get FMU author. \r
 135 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 136 */\r
 137 FMILIB_EXPORT const char* fmi2_import_get_author(fmi2_import_t* fmu);\r
 138 \r
 139 /** \r
 140 \brief Get FMU copyright information. \r
 141 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 142 */\r
 143 FMILIB_EXPORT const char* fmi2_import_get_copyright(fmi2_import_t* fmu);\r
 144 \r
 145 /** \r
 146 \brief Get FMU license information. \r
 147 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 148 */\r
 149 FMILIB_EXPORT const char* fmi2_import_get_license(fmi2_import_t* fmu);\r
 150 \r
 151 /** \brief Get FMU version.\r
 152 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 153 */\r
 154 FMILIB_EXPORT const char* fmi2_import_get_model_version(fmi2_import_t* fmu);\r
 155 \r
 156 /** \brief Get FMI standard version (always 2.0). \r
 157 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 158 */\r
 159 FMILIB_EXPORT const char* fmi2_import_get_model_standard_version(fmi2_import_t* fmu);\r
 160 \r
 161 /** \brief Get FMU generation tool. \r
 162 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 163 */\r
 164 FMILIB_EXPORT const char* fmi2_import_get_generation_tool(fmi2_import_t* fmu);\r
 165 \r
 166 /** \brief Get FMU generation date and time. \r
 167 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 168 */\r
 169 FMILIB_EXPORT const char* fmi2_import_get_generation_date_and_time(fmi2_import_t* fmu);\r
 170 \r
 171 /** \brief Get variable naming convention used. \r
 172 @param fmu An fmu object as returned by fmi2_import_parse_xml().\r
 173 */\r
 174 FMILIB_EXPORT fmi2_variable_naming_convension_enu_t fmi2_import_get_naming_convention(fmi2_import_t* fmu);\r
 175 \r
 176 /** \brief Get the number of continuous states. \r
 177 */\r
 178 FMILIB_EXPORT size_t fmi2_import_get_number_of_continuous_states(fmi2_import_t* fmu);\r
 179 \r
 180 /** \brief Get the number of event indicators. */\r
 181 FMILIB_EXPORT size_t fmi2_import_get_number_of_event_indicators(fmi2_import_t* fmu);\r
 182 \r
 183 /** \brief Get the start time for default experiment as specified in the XML file. */\r
 184 FMILIB_EXPORT double fmi2_import_get_default_experiment_start(fmi2_import_t* fmu);\r
 185 \r
 186 /** \brief Get the stop time for default experiment as specified in the XML file. */\r
 187 FMILIB_EXPORT double fmi2_import_get_default_experiment_stop(fmi2_import_t* fmu);\r
 188 \r
 189 /** \brief Get the tolerance for default experiment as specified in the XML file. */\r
 190 FMILIB_EXPORT double fmi2_import_get_default_experiment_tolerance(fmi2_import_t* fmu);\r
 191 \r
 192 /** \brief Get the step size for default experiment as specified in the XML file. */\r
 193 FMILIB_EXPORT double fmi2_import_get_default_experiment_step(fmi2_import_t* fmu);\r
 194 \r
 195 /** \brief Get the type of the FMU (model exchange or co-simulation) */\r
 196 FMILIB_EXPORT fmi2_fmu_kind_enu_t fmi2_import_get_fmu_kind(fmi2_import_t* fmu);\r
 197 \r
 198 /** \brief Get the list of all the type definitions in the model*/\r
 199 FMILIB_EXPORT fmi2_import_type_definitions_t* fmi2_import_get_type_definitions(fmi2_import_t* );\r
 200 \r
 201 /** \brief Get a list of all the unit definitions in the model. */\r
 202 FMILIB_EXPORT fmi2_import_unit_definitions_t* fmi2_import_get_unit_definitions(fmi2_import_t* fmu);\r
 203 \r
 204 /** \brief Get the variable with the same value reference that is not an alias*/\r
 205 FMILIB_EXPORT fmi2_import_variable_t* fmi2_import_get_variable_alias_base(fmi2_import_t* fmu,fmi2_import_variable_t*);\r
 206 \r
 207 /**\r
 208     Get the list of all the variables aliased to the given one (including the base one).\r
 209 \r
 210     Note that the list is ordered: base variable, aliases, negated aliases.\r
 211 */\r
 212 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_variable_aliases(fmi2_import_t* fmu,fmi2_import_variable_t*);\r
 213 \r
 214 /** \brief Get the list of all the variables in the model.\r
 215 * @param fmu An FMU object as returned by fmi2_import_parse_xml().\r
 216 * @param sortOrder Specifies the order of the variables in the list: \r
 217                 0 - original order as found in the XML file; 1 - sorted alfabetically by variable name; 2 sorted by types/value references.\r
 218 * @return a variable list with all the variables in the model.\r
 219 *\r
 220 * Note that variable lists are allocated dynamically and must be freed when not needed any longer.\r
 221 */\r
 222 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_variable_list(fmi2_import_t* fmu, int sortOrder);\r
 223 \r
 224 /** \brief Create a variable list with a single variable.\r
 225   \r
 226 \param fmu An FMU object that this variable list will reference.\r
 227 \param v A variable.\r
 228 */\r
 229 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_create_var_list(fmi2_import_t* fmu,fmi2_import_variable_t* v);\r
 230 \r
 231 /** \brief Get the number of vendors that had annotations in the XML*/\r
 232 FMILIB_EXPORT size_t fmi2_import_get_vendors_num(fmi2_import_t* fmu);\r
 233 \r
 234 /** \brief Get the name of the vendor with that had annotations in the XML by index */\r
 235 FMILIB_EXPORT const char* fmi2_import_get_vendor_name(fmi2_import_t* fmu, size_t index);\r
 236 \r
 237 /** \brief Get the number of log categories defined in the XML */\r
 238 FMILIB_EXPORT size_t fmi2_import_get_log_categories_num(fmi2_import_t* fmu);\r
 239 \r
 240 /** \brief Get the log category by index */\r
 241 FMILIB_EXPORT const char* fmi2_import_get_log_category(fmi2_import_t* fmu, size_t index);\r
 242 \r
 243 /** \brief Get the log category description by index */\r
 244 FMILIB_EXPORT const char* fmi2_import_get_log_category_description(fmi2_import_t* fmu, size_t index);\r
 245 \r
 246 /** \brief Get the number of source files for ME defined in the XML */\r
 247 FMILIB_EXPORT size_t fmi2_import_get_source_files_me_num(fmi2_import_t* fmu);\r
 248 \r
 249 /** \brief Get the ME source file by index */\r
 250 FMILIB_EXPORT const char* fmi2_import_get_source_file_me(fmi2_import_t* fmu, size_t index);\r
 251 \r
 252 /** \brief Get the number of source files for CS defined in the XML */\r
 253 FMILIB_EXPORT size_t fmi2_import_get_source_files_cs_num(fmi2_import_t* fmu);\r
 254 \r
 255 /** \brief Get the CS source file by index */\r
 256 FMILIB_EXPORT const char* fmi2_import_get_source_file_cs(fmi2_import_t* fmu, size_t index);\r
 257 \r
 258 /**\r
 259         \brief Get variable by variable name.\r
 260         \param fmu - An fmu object as returned by fmi2_import_parse_xml().\r
 261         \param name - variable name\r
 262         \return variable pointer.\r
 263 */\r
 264 FMILIB_EXPORT fmi2_import_variable_t* fmi2_import_get_variable_by_name(fmi2_import_t* fmu, const char* name);\r
 265 \r
 266 /**\r
 267         \brief Get variable by value reference.\r
 268         \param fmu - An fmu object as returned by fmi2_import_parse_xml().\r
 269         \param baseType - basic data type\r
 270         \param vr - value reference\r
 271         \return variable pointer.\r
 272 */\r
 273 FMILIB_EXPORT fmi2_import_variable_t* fmi2_import_get_variable_by_vr(fmi2_import_t* fmu, fmi2_base_type_enu_t baseType, fmi2_value_reference_t vr);\r
 274 \r
 275 /** \brief Get the list of all the output variables in the model.\r
 276 * @param fmu An FMU object as returned by fmi2_import_parse_xml().\r
 277 * @return a variable list with all the output variables in the model.\r
 278 *\r
 279 * Note that variable lists are allocated dynamically and must be freed when not needed any longer.\r
 280 */\r
 281 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_outputs_list(fmi2_import_t* fmu);\r
 282 \r
 283 /** \brief Get the list of all the derivative variables in the model.\r
 284 * @param fmu An FMU object as returned by fmi2_import_parse_xml().\r
 285 * @return a variable list with all the continuous state derivatives in the model.\r
 286 *\r
 287 * Note that variable lists are allocated dynamically and must be freed when not needed any longer.\r
 288 */\r
 289 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_derivatives_list(fmi2_import_t* fmu);\r
 290 \r
 291 /** \brief Get the list of all the discrete state variables in the model.\r
 292 * @param fmu An FMU object as returned by fmi2_import_parse_xml().\r
 293 * @return a variable list with all the discrete state variables in the model.\r
 294 *\r
 295 * Note that variable lists are allocated dynamically and must be freed when not needed any longer.\r
 296 */\r
 297 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_discrete_states_list(fmi2_import_t* fmu);\r
 298 \r
 299 /** \brief Get the list of all the initial unknown variables in the model.\r
 300 * @param fmu An FMU object as returned by fmi2_import_parse_xml().\r
 301 * @return a variable list with all the initial unknowns in the model.\r
 302 *\r
 303 * Note that variable lists are allocated dynamically and must be freed when not needed any longer.\r
 304 */\r
 305 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_initial_unknowns_list(fmi2_import_t* fmu);\r
 306 \r
 307 /** \brief Get dependency information in row-compressed format. \r
 308  * @param fmu An FMU object as returned by fmi2_import_parse_xml(). \r
 309  * @param startIndex - outputs a pointer to an array of start indices (size of array is number of outputs + 1).\r
 310  *                     First element is zero, last is equal to the number of elements in the dependency and factor arrays. \r
 311  *                     NULL pointer is returned if no dependency information was provided in the XML. \r
 312  * @param dependency - outputs a pointer to the dependency index data. Indices are 1-based. Index equals to zero  \r
 313  *                     means "depends on all" (no information in the XML). \r
 314  * @param factorKind - outputs a pointer to the factor kind data. The values can be converted to ::fmi2_dependency_factor_kind_enu_t \r
 315  */ \r
 316 FMILIB_EXPORT void fmi2_import_get_outputs_dependencies(fmi2_import_t* fmu, size_t** startIndex, size_t** dependency, char** factorKind);\r
 317  \r
 318 /** \brief Get dependency information in row-compressed format. \r
 319  * @param fmu An FMU object as returned by fmi2_import_parse_xml(). \r
 320  * @param startIndex - outputs a pointer to an array of start indices (size of array is number of derivatives + 1).\r
 321  *                     First element is zero, last is equal to the number of elements in the dependency and factor arrays. \r
 322  *                     NULL pointer is returned if no dependency information was provided in the XML. \r
 323  * @param dependency - outputs a pointer to the dependency index data. Indices are 1-based. Index equals to zero  \r
 324  *                     means "depends on all" (no information in the XML). \r
 325  * @param factorKind - outputs a pointer to the factor kind data. The values can be converted to ::fmi2_dependency_factor_kind_enu_t \r
 326  */ \r
 327 FMILIB_EXPORT void fmi2_import_get_derivatives_dependencies(fmi2_import_t* fmu, size_t** startIndex, size_t** dependency, char** factorKind);\r
 328 \r
 329 /** \brief Get dependency information in row-compressed format. \r
 330  * @param fmu An FMU object as returned by fmi2_import_parse_xml(). \r
 331  * @param startIndex - outputs a pointer to an array of start indices (size of array is number of discrete states + 1).\r
 332  *                     First element is zero, last is equal to the number of elements in the dependency and factor arrays. \r
 333  *                     NULL pointer is returned if no dependency information was provided in the XML. \r
 334  * @param dependency - outputs a pointer to the dependency index data. Indices are 1-based. Index equals to zero  \r
 335  *                     means "depends on all" (no information in the XML). \r
 336  * @param factorKind - outputs a pointer to the factor kind data. The values can be converted to ::fmi2_dependency_factor_kind_enu_t \r
 337  */ \r
 338 FMILIB_EXPORT void fmi2_import_get_discrete_states_dependencies(fmi2_import_t* fmu, size_t** startIndex, size_t** dependency, char** factorKind);\r
 339  \r
 340 /** \brief Get dependency information in row-compressed format. \r
 341  * @param fmu An FMU object as returned by fmi2_import_parse_xml(). \r
 342  * @param startIndex - outputs a pointer to an array of start indices (size of array is number of initial unknowns + 1).\r
 343  *                     First element is zero, last is equal to the number of elements in the dependency and factor arrays. \r
 344  *                     NULL pointer is returned if no dependency information was provided in the XML. \r
 345  * @param dependency - outputs a pointer to the dependency index data. Indices are 1-based. Index equals to zero  \r
 346  *                     means "depends on all" (no information in the XML). \r
 347  * @param factorKind - outputs a pointer to the factor kind data. The values can be converted to ::fmi2_dependency_factor_kind_enu_t \r
 348  */ \r
 349 FMILIB_EXPORT void fmi2_import_get_initial_unknowns_dependencies(fmi2_import_t* fmu, size_t** startIndex, size_t** dependency, char** factorKind);\r
 350  \r
 351 /**@} */\r
 352 \r
 353 #ifdef __cplusplus\r
 354 }\r
 355 #endif\r
 356 \r
 357 #endif\r