Model¶

@author: marco

class estimationpy.fmu_utils.model.Model(fmu_file=None, result_handler=None, solver=None, atol=1e-06, rtol=0.0001, verbose=None, offset=None)¶

The class Model represents an extension of an FMU model. The FMU model is meant to be used for simulation purposes only. An object of type Model groups multiple information that make it useful for a state or parameter estimation algorithm.

The Model contains a reference to the particular FMU that is being loaded and will be used to perform simulation, but also contains other information such as

the parameters of the models to estimate,
the state variables of the model to estimate,
the inputs and output variables as well the data associated to them.

The parameters and state variables to be stimated will be represented by objects of type estimationpy.fmu_utils.estimation_variable.EstimationVariable, the input and output variables are represented by objects of type estimationpy.fmu_utils.in_out_var.InOutVar.

__init__(fmu_file=None, result_handler=None, solver=None, atol=1e-06, rtol=0.0001, verbose=None, offset=None)¶

Constructor method that initializes an object of type Model that can be used for simulation purposes or within an estimation algorithm.

Parameters:

fmu_file (string) – String representing the path of an FMU model.
result_handler (string) – String that specifies how pyfmi should handle the results of the simulations of the FMU model. See estimationpy.fmu_utils.strings for available options.
solver (string) – String that specifies the solver used by pyfmi to simulate the FMU model. See estimationpy.fmu_utils.strings for available options.
atol (float) – Absolute tolerance used by the solver when simulating the FMU model.
rtol (float) – relative tolerance used by the solver when simulating the FMU model.
verbose (string) – level of verbosity required when log messagess are generated.
offset (datetime.datetime) – a datetime object that is used as offset in the simulations. For example when running an FMU that references a weather data file, one can specify as offset the midnight of the first of January (in ISO format UTC referenced <year>-01-01T00:00+0000) and the command simulate() will use the offset date instead of teh start date to compute the time in seconds.

__set_fmu__(fmu_file, result_handler, solver, atol, rtol, verbose)¶

This method associate an FMU to a model. If the model has already an FMU associated to it the method does not complete the assigment. The method provides a convenient way to set multiple of the details that are needed to run simulation and handle the FMU in the context os estimationpy:

loading the FMU from a file
get the default options for the simulation and modify them if necessary
identify the number os states and their value references
identify properties of the FMU
identify the inputs and outputs of the FMU

See estimationpy.fmu_utils.strings for more information about the options.

Parameters:

fmu_file (string) – path that identifies the FMU to be loaded
result_handler (string) – type of handler for managing the results
solver (string) – name of the solver used for the time integration
atol (float) – absolute tolerance of the solver
rtol (float) – relative tolerance of the solver
verbose (string) – verbosity level used by the ODE solver used by PyFMI

Return type:

None

__set_in_out_var__(variability, causality)¶

This method identifies a subset of the variables that belong to the FMU depending on their charateristics, namely the causality and variability. The variables are identified in the following way

Variable type	causality	variability
input	0	None
output	1	None

Once the variables are identified, they’re added to the list of inputs and outputs of this model.

Parameters:	variability (int) – integer that identifies the variability of a variable in the FMU. causality (int) – integer that identifies the causality of a variable in the FMU.
Return type:	None

__set_inputs__()¶

This function scan the FMU and identifies the input variables of the model. The method uses __set_in_out_var__(). After this method is called, the model will have a list of estimationpy.fmu_utils.in_out_var.InOutVar objects associated to its inputs.

Return type:	None

__set_outputs__()¶

This function scan the FMU and identifies the output variables of the model. The method uses __set_in_out_var__(). After this method is called, the model will have a list of estimationpy.fmu_utils.in_out_var.InOutVar objects associated to its oututs.

Return type:	None

__str__()¶

This method overrides the default __str__ method for this class and creates a string representation for it.

Returns:	string representation of the object that contains the following information FMU file path, name of the FMU, Author of the FMU, Description of the FMU, Type of the FMU, Version of the FMU, GUID of the FMU, Tool used to generate the FMU, Total number of state variables
Return type:	string

add_parameter(obj)¶

This method adds one object to the list of parameters to estimate. This list contains only the parameters that will be modified by further algorithms that make use of objects of type Model.

Parameters:	obj (FmiVariable) – an object representing a variable of the FMU in PyFMI. This object, if not already present, is used to instantiate a new object of type `estimationpy.fmu_utils.estimation_variable.EstimationVariable`.
Returns:	a boolean flag that indicates success. True if added, False if, e.g., the parameter was already present.
Return type:	bool

add_variable(obj)¶

This method adds one object to the list of state variables to estimate. This list contains only the states that will be modified by further algorithms that make use of objects of type Model.

Parameters:	obj (FmiVariable) – an object representing a variable of the FMU in PyFMI. This object, if not already present, is used to instantiate a new object of type `estimationpy.fmu_utils.estimation_variable.EstimationVariable`.
Returns:	a boolean flag that indicates success. True if added, False if, e.g., the variable was already present.
Return type:	bool

check_data_list(dataList, align=True)¶

This method check if all the data series provided by the dataList are ready to be used or not. If not because they are not aligned, this method tries to correct them providing an interpolation.

Parameters:	dataList (List(InOutVar)) – a list that contains object of type `InOutVar`. align (bool) – boolean parameter that specifies whether the method should simply check is the the data is correctly aligned or correct them in case they’re not aligned.
Returns:	a boolean flag that indicates if the data is valid or not.
Return type:	bool

check_input_data(align=True)¶

This method checks if all the data series associated to the inputs variables of this model are ready to be used or not. In case they’re not ready because they are not aligned, this method tries to correct them providing an interpolation.

See check_data_list() for more info.

Parameters:	align (bool) – boolean paramater that indicate whether this method should try to align the input data series in case they aren’t.
Returns:	True if the data is ready, False otherwise.
Return type:	bool

get_constr_obs_states_high()¶

This method returns a numpy.array that contains the upper boundary of the constraints over the observed state variables.

Returns:	An array containing the upper bounds of the constraints for the state variables.
Return type:	numpy.array

get_constr_obs_states_low()¶

This method returns a numpy.array that contains the lower boundary of the constraints over the observed state variables.

Returns:	An array containing the lower bounds of the constraints for the state variables.
Return type:	numpy.array

get_constr_pars_high()¶

This method returns a numpy.array that contains the upper boundary of the constraints over the estimated parameters.

Returns:	An array containing the upper bounds of the constraints for the estimated parameters.
Return type:	numpy.array

get_constr_pars_low()¶

This method returns a numpy.array that contains the lower boundary of the constraints over the estimated parameters.

Returns:	An array containing the lower bounds of the constraints for the estimated parameters.
Return type:	numpy.array

get_cov_matrix_outputs()¶

This method returns a numpy.ndarray representing the covariance matrix of the measured output variables. The matrix is diagonal.

Returns:	A matrix that is the covariance matrix of the measured output variables.
Return type:	numpy.ndarray

get_cov_matrix_parameters()¶

This method returns a numpy.ndarray representing the covariance matrix of the estimated parameters. The matrix is diagonal.

Returns:	A matrix that is the covariance matrix of the estimated parameters.
Return type:	numpy.ndarray

get_cov_matrix_state_pars()¶

This method returns a numpy.ndarray representing the covariance matrix of the estimated state variables and parameters. The matrix is diagonal.

Returns:	A matrix that is the covariance matrix of the state variables and parameters.
Return type:	numpy.ndarray

get_cov_matrix_states()¶

This method returns a numpy.ndarray representing the covariance matrix of the estimated state variables. The matrix is diagonal.

Returns:	A matrix that is the covariance matrix of the state variables.
Return type:	numpy.ndarray

get_fmu()¶

This method return the FMU associated to the model.

Returns:	An object representing the FMU model in PyFMI.
Return type:	pyfmi.FmuModel

get_fmu_file_path()¶

This method returns the file path of the FMU.

Returns:	String representing the path of the FMU file.
Return type:	string

get_fmu_name()¶

This method returns the name of the FMU associated to the model.

Returns:	The name of the FMU from its model description XML file.
Return type:	string

get_input_by_name(name)¶

This method returns the input variable contained in the list of inputs associated to this model that has a name equal to the parameter name.

Parameters:	name (string) – Name of the input variable to find.
Returns:	The input variable associated to the parameter `name` if exists, otherwise `None`.
Return type:	estimationpy.fmu_utils.in_out_var.InOutVar, None

get_input_names()¶

This method returns a list containing the names of the input variables associated to this model.

Returns:	list of input names
Return type:	List(string)

get_inputs()¶

Return the list of input variables associated to the FMU that have been selected. The variables are of type estimationpy.fmu_utils.in_out_var.InOutVar.

Returns:	List of InOutVar objects representing the inputs of the model.
Return type:	List(estimationpy.fmu_utils.in_out_var.InOutVar)

get_measured_data_ouputs(t)¶

The method reads the values of the measured outputs at a given time that is specified by the parameter t. The parameter t is a datetime object that is part of the indexes os the pandas.Series associated to the outputs.

Parameters:	t (datetime.datetime) – time index at which reading the measured output data.
Returns:	an array containing the values of the measured outputs at date and time t.
Return type:	numpy.ndarray

get_measured_output_data_series()¶

This method returns a matrix that contains the data values of the measured outputs of the model. The matrix contains the data in columns. The first column is the time, while the remaining columns are the values of the measured outputs.

Returns:	a matrix containing the measured outputs and the time at which these values are defined.
Return type:	numpy.ndarray

get_measured_outputs_values()¶

This method return a vector that contains the values of the observed state variables of the model. The observed outputs are listed in the object variable self.outputs and are identified by the flag measured = True.

Returns:	A numpy array containing the values of the measured outputs.
Return type:	numpy.array

get_num_inputs()¶

This method returns the total number of input variables of the FMU associated to this model.

Returns:	the number of inputs
Return type:	int

get_num_measured_outputs()¶

This method returns the total number of measured output variables of the FMU associated to this model.

Returns:	the number of measured outputs
Return type:	int

get_num_outputs()¶

This method returns the total number of output variables of the FMU associated to this model.

Returns:	the number of outputs
Return type:	int

get_num_parameters()¶

This method returns the number of parameters of the FMU model that will be estimated or identified.

Returns:	number of parameters to estimate
Return type:	int

get_num_states()¶

This method returns the total number of states variables of the FMU associated to this model.

Returns:	the total number of states
Return type:	int

get_num_variables()¶

This method returns the number of state variables of the FMU model that will be estimated or identified.

Returns:	number of states to estimate
Return type:	int

get_output_by_name(name)¶

This method returns the output variable identified by the parameter name. If there is no variable with the same name, the method returns None.

Returns:	The output variable identified by the parameter `name`
Return type:	estimationpy.fmu_utils.in_out_var.InOutVar, None

get_output_names()¶

This method returns a list of names of the outputs of the model.

Returns:	a list containing the names of the outputs
Return type:	List(String)

get_outputs()¶

Return the list of output variables associated to the FMU.

Returns:	a list of output variables associated to the model.
Return type:	List(estimationpy.fmu_utils.in_out_var.InOutVar)

get_outputs_values()¶

This method return a vector that contains the values of the outputs as read in the FMU associated to this model. The method uses estimationpy.fmu_utils.in_out_var.InOutVar.read_value_in_fmu().

Returns:	an array containing the values of the outputs as read in the FMU model.
Return type:	numpy.ndarray

get_parameter_names()¶

This method returns a list containing the names of the parameters selected in this model that will be estimated.

Returns:	a list containing the names of the selected parameters.
Return type:	List

get_parameter_values()¶

This method return a vector that contains the values of the parametrs as read in the FMU associated to this model. The method uses estimationpy.fmu_utils.estimation_variable.EstimationVariable.read_value_in_fmu().

Returns:	an array containing the values of the parameters selected as read in the FMU model.
Return type:	numpy.ndarray

get_parameters()¶

Return the list of parameters of the model that have been selected. The selection of a parameter happens with the method add_parameter().

Returns:	a list of parameters that are selected
Return type:	List(estimationpy.fmu_utils.estimation_variable.EstimationVariable)

get_parameters_max()¶

This method return an array that contains the maximum values that the estimated parameters can assume.

Returns:	an array with the max values the parameters can assume.
Return type:	numpy.array

get_parameters_min()¶

This method return an array that contains the minimum values that the selected parameters can assume.

Returns:	an array with the min values the parameters can assume.
Return type:	numpy.array

get_properties()¶

This method returns a tuple containing the properties of the FMU associated to this model.

Returns:	A tuple with the following information name of the FMU, author of the FMU, description of the FMU, type of the FMU (e.g., Model Exchange), version of the FMU, GUID of the FMU, tool used to generate it, number of states of the FMU
Return type:	tuple

get_real(var)¶

Get a real variable specified by the PyFmiVariable from the FMU.

Parameters:	var (pyfmiVariable) – FMI variable for which reading the value.
Returns:	the value of the variable
Return type:	float

get_simulation_options()¶

This method returns the simulation options of the simulator.

Returns:	a dictionary that contains the option for the simulator and the solver.
Return type:	dict

get_state()¶

This method returns an array that contains the values of the entire state variables of the model. The methos uses the underlying method _get_continuous_states provided by PyFMI.

Returns:	array containing the state vector
Return type:	numpy.array

get_state_observed_max()¶

This method return an array that contains the maximum values that the observed states can assume.

Returns:	an array with the max values the observed states can assume.
Return type:	numpy.array

get_state_observed_min()¶

This method return an array that contains the minimum values that the observed states can assume.

Returns:	an array with the min values the observed states can assume.
Return type:	numpy.array

get_state_observed_values()¶

This method returns an array that contains the values of the observed state variables of the model. The observed states are listed in self.variables. The order in which they appear is the same they were added using the method :func:add_variable.

Returns:	array containing the observed states in the order they were declared.
Return type:	numpy.array

get_variable_info(variable_info)¶: Given a variable_info object that may be related either to a parameter, a state variable, an input or a output This function returns the values and details associated to it.

get_variable_info_numeric(variable_info)¶

This function takes as parameter variable_info that is an object that can either represent a parameter, a state variable, an input or an output and returns the values and the details associated to it in the FMU.

Parameters: variable_info (estimationpy.fmu_utils.{in_out_var.InOutVar,estimation_variable.EstimationVariable}) – the object for which retrieving the data from the FMU associated to the model.

Returns:

a tuple with the following values

the Type of the variable,
the value of the variable,
the start value of the variable,
the min value of the variable,
the max value of the variable

the tuple contains all None values if there’s no real value to read for the variable.

Return type: tuple

get_variable_names()¶: This method returns a list of names for each state variables observed

get_variable_object(name=None)¶: This method returns a PyFMI variable given its name

get_variables()¶

Return the list of observed state variables of the FMU associated to the model. The selection of an observed state is done by the method add_variable().

Returns:	list of observed states in the same order they were added with the method `add_variable()`.
Return type:	List(estimationpy.fmu_utils.estimation_variable.EstimationVariable)

initialize_simulator(startTime=None)¶

This method performs a simulation of length zero to initialize the model. The initialization is needed only once before running the first simulation. Simulations after the first do not need to execute the initialization again.

By default the simulation is performed at the initial time of the input data series, but the user can specify an other point with the parameter startTime.

Parameters:	startTime (datetime.datetime) – start time and date where the model should be initialized
Returns:	a boolean flag that indicates if the initialization was successful
Return type:	bool

is_parameter_present(obj)¶

This method returns True is the variable specified by the parameter obj is contained in the list of variables of the model (e.g, observed states).

Returns:	flag that indicates if the variable is present in the list of variables.
Return type:	bool

is_variable_present(obj)¶

This method returns True is the variable specified by the parameter obj is contained in the list of variables of the model (e.g, observed states).

Returns:	flag that indicates if the variable is present in the list of variables.
Return type:	bool

load_input(align=True)¶

This method loads all the pandas.Series associated to the inputs. The method returns a boolean variable that indicates if the import was successful.

Returns:	flag that indicates a successful import
Return type:	bool

load_outputs()¶

This method loads all the pandas.Series associated to the outputs. The method returns a boolean variable that indicates if the import was successful.

Returns:	flag that indicates a successful import
Return type:	bool

re_init(fmu_file, result_handler=None, solver=None, atol=1e-06, rtol=0.0001, verbose=None)¶

This function reinitializes the FMU associated to the model and resets the default options for running the simulations.

Parameters:

fmu_file (string) – path that identifies the FMU to be loaded
result_handler (string) – type of handler for managing the results
solver (string) – name of the solver used for the time integration
atol (float) – absolute tolerance of the solver
rtol (float) – relative tolerance of the solver
verbose (string) – verbosity level used by the ODE solver used by PyFMI

Return type:

None

remove_parameter(obj)¶

This method removes one object from the list of parameters. This list contains only the parameters that will be modified during further analysis.

Parameters:	obj (estimationpy.fmu_utils.estimation_variable.EstimationVariable) – The parameter to be removed
Returns:	a boolean that indicates is the operation was successful
Return type:	bool

remove_parameters()¶

This method removes all the objects from the list of parameters.

Return type:	None

remove_variable(obj)¶

This method removes one object from the list of variables. This list contains only the state variables that will be modified during further analysis.

Parameters:	obj (estimationpy.fmu_utils.estimation_variable.EstimationVariable) – The variable to be removed
Returns:	a boolean that indicates is the operation was successful
Return type:	bool

remove_variables()¶: This method removes all the objects from the list of parameters.

set_parameters_selected(p)¶

This method sets the values of the parameters to be estimated that are part of the list self.parameters.

Parameters:	np.array p (list,) – iterable and oredered sequence of parameter values to assign
Returns:	flag that indicates the success of the operation
Return type:	bool

set_real(var, value)¶

This method sets the value of a real variable in the FMU associated to the model.

Parameters:	var (pyfmi.FMIVariable) – FMi variable that is part of the FMU for which the value has to be set value (float) – real value to assign to the variable `var` in the FMU.
Return type:	None

set_result_file(file_name)¶

This method modifies the name of the file that stores the simulation results.

Parameters:	file_name (string) – name of the file that will store the simulation results.
Return type:	None

set_simulation_options(result_handler, solver, atol, rtol, verbose)¶

This method sets the options for the simulator used by PyFMI.

Parameters:

result_handler (string) – result handler that manages the data produced by the FMU. The optiona can be to store data on files, memory, or in a custom way.
solver (string) – dolver used to integrate the ODE represented by the FMU
atol (float) – absolute tolerance of the solver
rtol (float) – relative tolerance of the numerical solver
verbose (string) – string that represents the verbosity level used by the numerical solver

See estimationpy.fmu_utils.strings for more information about the options that are available.

set_state(states_vector)¶

This method sets the value of a real variable in the FMU associated to the model.

Parameters:	states_vector (numpy.array) – a numpy array containing the values for all the state variables of the FMU associated to the model.
Return type:	None

set_state_selected(v)¶

This method sets the values of the states to be estimated that are part of the list self.variables.

Parameters:	np.array s (list,) – iterable and oredered sequence of state values to assign
Returns:	flag that indicates the success of the operation
Return type:	bool

simulate(start_time=None, final_time=None, time=<class 'pandas.tseries.index.DatetimeIndex'> Length: 0, Freq: None, Timezone: None, input=None, complete_res=False)¶

This method simulates the model from the start time to the final time. The simulation is handled by PyFMI and its options can be specified with set_simulation_options(). The method performs the following steps:

Loads all the pandas.Series associated to the inputs variables,
reads all the values associated to the inputs within the period specified by the start and final times,
converts datetime objects into seconds,
creates the input data matrix required by PyFMI,
loads the simulation options,
runs the simulation,
process and aggregates the results

The inputs can be either read from the pandas.Series associated to the InOutVar objects associated to the inputs of the model, or directly specified by the parameter input. In such a case, the input data matrix follows the following structure:

input = [[u1(T0), u2(T0), ...,uM(T0)],
         [u1(T1), u2(T1), ...,uM(T1)],
         ...
         [u1(Tend), u2(Tend), ...,uM(Tend)]]

To summarize one can either implicitly use the data associated to the input variables and thus specify the parameters start_time and final_time, otherwise one can specify the parameter time and the input matrix input. If none of them are specified the method reads the time index associated to the input variables and identifies the longest period over which all input variables are defined.

NOTE Since it may happen that a simulation fails without apparent reasons, it is better to simulate the model again before actual an error. The number of tries is specified by the propertiy self.SIMULATION_TRIES.

Parameters:	start_time (datetime.datetime) – start date and time of the simulation period. final_time (datetime.datetime) – end date and time of the simulation period. time (pandas.DatetimeIndex) – date and time index that can be used in conjunction with the parameter `input`. input (numpy.ndarray) – matrix that contains the inputs for the model stacked in columns. complete_res (bool) – this flag indicates in which format the results should be arranged. If `complete_res == True`, then the method returns all the results as provided by PyFMI. Otherwise it only returns the data that belong to the following categories: state variables, observed state variables, estimated parameters, measured outputs, and outputs.
Returns:	returns a tuple containing as first element the time instants where the solution of the differential equations are computed by the time integrator. The elements of the time vector are datetime objects. The second element is a dictionary containing the results. The number of results available depends depends on the value of the parameter `complete_res`.
Return type:	tuple

toggle_parameter(obj)¶

This method checks if a parameter has been added to the list of parameters to estimate. In case it’s part of the list, the parameter is removed, otherwise it is added.

NOTE This method can be useful when coupled with a GUI.

Return type:	None

toggle_variable(obj)¶

This method checks if a state variable has been added to the list of variable to estimate (i.e., an observed state). In case it’s part of the list, the variable is removed, otherwise it is added.

NOTE This method can be useful when coupled with a GUI.

Return type:	None

unload_fmu()¶

This method unloads the FMU by deallocating the resources associated to it from the memory. This is necessary if an other FMU model needs to be loaded.

Return type:	None