2 Copyright (C) 2012 Modelon AB
\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
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
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
16 /** \file fmi2_import.h
\r
17 * \brief Public interface to the FMI import C-library.
\r
20 #ifndef FMI2_IMPORT_H_
\r
21 #define FMI2_IMPORT_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
30 #include <FMI2/fmi2_types.h>
\r
31 #include <FMI2/fmi2_functions.h>
\r
32 #include <FMI2/fmi2_enums.h>
\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
39 #include "fmi2_import_capi.h"
\r
40 #include "fmi2_import_convenience.h"
\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
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
61 /** \addtogroup fmi2_import_init Constuction, destruction and error handling
\r
66 * \brief Retrieve the last error message.
\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
78 FMILIB_EXPORT const char* fmi2_import_get_last_error(fmi2_import_t* fmu);
\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
86 FMILIB_EXPORT int fmi2_import_clear_last_error(fmi2_import_t* fmu);
\r
89 \brief Release the memory allocated
\r
90 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
92 FMILIB_EXPORT void fmi2_import_free(fmi2_import_t* fmu);
\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
101 \brief Get model name.
\r
102 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
104 FMILIB_EXPORT const char* fmi2_import_get_model_name(fmi2_import_t* fmu);
\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
110 \brief Get model identifier for ModelExchange.
\r
111 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
113 FMILIB_EXPORT const char* fmi2_import_get_model_identifier_ME(fmi2_import_t* fmu);
\r
116 \brief Get model identifier for CoSimulation.
\r
117 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
119 FMILIB_EXPORT const char* fmi2_import_get_model_identifier_CS(fmi2_import_t* fmu);
\r
122 \brief Get FMU GUID.
\r
123 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
125 FMILIB_EXPORT const char* fmi2_import_get_GUID(fmi2_import_t* fmu);
\r
128 \brief Get FMU description.
\r
129 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
131 FMILIB_EXPORT const char* fmi2_import_get_description(fmi2_import_t* fmu);
\r
134 \brief Get FMU author.
\r
135 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
137 FMILIB_EXPORT const char* fmi2_import_get_author(fmi2_import_t* fmu);
\r
140 \brief Get FMU copyright information.
\r
141 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
143 FMILIB_EXPORT const char* fmi2_import_get_copyright(fmi2_import_t* fmu);
\r
146 \brief Get FMU license information.
\r
147 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
149 FMILIB_EXPORT const char* fmi2_import_get_license(fmi2_import_t* fmu);
\r
151 /** \brief Get FMU version.
\r
152 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
154 FMILIB_EXPORT const char* fmi2_import_get_model_version(fmi2_import_t* fmu);
\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
159 FMILIB_EXPORT const char* fmi2_import_get_model_standard_version(fmi2_import_t* fmu);
\r
161 /** \brief Get FMU generation tool.
\r
162 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
164 FMILIB_EXPORT const char* fmi2_import_get_generation_tool(fmi2_import_t* fmu);
\r
166 /** \brief Get FMU generation date and time.
\r
167 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
169 FMILIB_EXPORT const char* fmi2_import_get_generation_date_and_time(fmi2_import_t* fmu);
\r
171 /** \brief Get variable naming convention used.
\r
172 @param fmu An fmu object as returned by fmi2_import_parse_xml().
\r
174 FMILIB_EXPORT fmi2_variable_naming_convension_enu_t fmi2_import_get_naming_convention(fmi2_import_t* fmu);
\r
176 /** \brief Get the number of continuous states.
\r
178 FMILIB_EXPORT size_t fmi2_import_get_number_of_continuous_states(fmi2_import_t* fmu);
\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
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
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
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
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
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
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
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
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
208 Get the list of all the variables aliased to the given one (including the base one).
\r
210 Note that the list is ordered: base variable, aliases, negated aliases.
\r
212 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_variable_aliases(fmi2_import_t* fmu,fmi2_import_variable_t*);
\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
220 * Note that variable lists are allocated dynamically and must be freed when not needed any longer.
\r
222 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_variable_list(fmi2_import_t* fmu, int sortOrder);
\r
224 /** \brief Create a variable list with a single variable.
\r
226 \param fmu An FMU object that this variable list will reference.
\r
227 \param v A variable.
\r
229 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_create_var_list(fmi2_import_t* fmu,fmi2_import_variable_t* v);
\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
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
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
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
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
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
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
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
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
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
264 FMILIB_EXPORT fmi2_import_variable_t* fmi2_import_get_variable_by_name(fmi2_import_t* fmu, const char* name);
\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
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
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
279 * Note that variable lists are allocated dynamically and must be freed when not needed any longer.
\r
281 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_outputs_list(fmi2_import_t* fmu);
\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
287 * Note that variable lists are allocated dynamically and must be freed when not needed any longer.
\r
289 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_derivatives_list(fmi2_import_t* fmu);
\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
295 * Note that variable lists are allocated dynamically and must be freed when not needed any longer.
\r
297 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_discrete_states_list(fmi2_import_t* fmu);
\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
303 * Note that variable lists are allocated dynamically and must be freed when not needed any longer.
\r
305 FMILIB_EXPORT fmi2_import_variable_list_t* fmi2_import_get_initial_unknowns_list(fmi2_import_t* fmu);
\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
316 FMILIB_EXPORT void fmi2_import_get_outputs_dependencies(fmi2_import_t* fmu, size_t** startIndex, size_t** dependency, char** factorKind);
\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
327 FMILIB_EXPORT void fmi2_import_get_derivatives_dependencies(fmi2_import_t* fmu, size_t** startIndex, size_t** dependency, char** factorKind);
\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
338 FMILIB_EXPORT void fmi2_import_get_discrete_states_dependencies(fmi2_import_t* fmu, size_t** startIndex, size_t** dependency, char** factorKind);
\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
349 FMILIB_EXPORT void fmi2_import_get_initial_unknowns_dependencies(fmi2_import_t* fmu, size_t** startIndex, size_t** dependency, char** factorKind);
\r