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 typeestimationpy.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 ofestimationpy.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 ofestimationpy.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
- dataList (List(InOutVar)) – a list that contains object of type
-
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, otherwiseNone
.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 parametert
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 flagmeasured = 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
andfinal_time
, otherwise one can specify the parametertime
and the input matrixinput
. 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.
- If
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