MPCData#

class MPCData(model)[source]#

Bases: Data

do-mpc data container for the do_mpc.controller.MPC instance. This method inherits from Data and extends it to query the MPC predictions.

Warning

For robust multi-stage MPC, the MPCData class stores by default only the nominal values of the uncertain parameters.

Parameters:

model (Union[Model, LinearModel]) – model from do_mpc.model

__getitem__(ind)#

Query data fields. This method can be used to obtain the stored results in the Data instance.

The full list of available fields can be inspected with:

print(data.data_fields)

The dict also denotes the dimension of each field.

The method allows for power indexing the results for the fields _x, _u, _z, _tvp, _p, _aux, _y where further indices refer to the configured variables in the do_mpc.model.Model and do_mpc.model.LinearModel instance.

Example:

# Assume the following model was used (excerpt):
model = do_mpc.model.Model('continuous')

model.set_variable('_x', 'Temperature', shape=(5,1)) # Vector
model.set_variable('_p', 'disturbance', shape=(3,3)) # Matrix
model.set_variable('_u', 'heating')                  # scalar

...

# the model was used (among others) for the MPC controller
mpc = do_mpc.controller.MPC(model)

...

# Query the mpc.data instance:
mpc.data['_x']                      # Return all states
mpc.data['_x', 'Temperature']       # Return the 5 temp states
mpc.data['_x', 'Temperature', :2]   # Return the first 2 temp. states
mpc.data['_p', 'disturbance', 0, 2] # Matrix allows for further indices

# Other fields can also be queried, e.g.:
mpc.data['_time']                   # current time
mpc.data['t_wall_total']            # optimizer runtime
# These do not allow further indices.
Parameters:

ind (Tuple) – Power index to query the prediction of a specific variable.

Returns:

ndarray – Returns the queried data field (for all time instances)

Methods#

export#

export(self)#

The export method returns a dictionary of the stored data.

Returns:

dict – Dictionary of the currently stored data.

init_storage#

init_storage(self)#

Create new (empty) arrays for all variables. The variables of interest are listed in the data_fields dictionary, with their respective dimension. This dictionary may be updated. The do_mpc.controller.MPC class adds for example optimizer information.

Return type:

None

prediction#

prediction(self, ind, t_ind=-1)#

Query the MPC trajectories. Use this method to obtain specific MPC trajectories from the data object.

Warning

This method requires that the optimal solution is stored in the do_mpc.data.MPCData instance. Storing the optimal solution must be activated with do_mpc.controller.MPC.set_param().

Querying predicted trajectories requires the use of power indices, which is passed as tuple e.g.:

data.prediction((var_type, var_name, i), t_ind)

where

  • var_type refers to _x, _u, _z, _tvp, _p, _aux

  • var_name refers to the user-defined names in the do_mpc.model.Model

  • Use i to index vector valued variables.

The method returns a multidimensional numpy.ndarray. The dimensions refer to:

arr = data.prediction(('_x', 'x_1'))
arr.shape
>> (n_size, n_horizon, n_scenario)

with:

  • n_size denoting the number of elements in x_1, where n_size = 1 is a scalar variable.

  • n_horizon is the MPC horizon defined with do_mpc.controller.MPC.set_param()

  • n_scenario refers to the number of uncertain scenarios (for robust MPC).

Additional to the power index tuple, a time index (t_ind) can be passed to access the prediction for a certain time.

Parameters:
  • ind (tuple) – Power index to query the prediction of a specific variable.

  • t_ind (float) – Time index

Returns:

ndarray – Predicted trajectories for the queries variable.

set_meta#

set_meta(self, **kwargs)#

Set meta data for the current instance of the data object.

Return type:

None

update#

update(self, **kwargs)#

Update value(s) of the data structure with key word arguments. These key word arguments must exist in the data fields of the data objective. See self.data_fields for a complete list of data fields.

Example:

_x = np.ones((1, 3))
_u = np.ones((1, 2))
data.update('_x': _x, '_u': _u)

or:
data.update('_x': _x)
data.update('_u': _u)

Alternatively:
data_dict = {
    '_x':np.ones((1, 3)),
    '_u':np.ones((1, 2))
}

data.update(**data_dict)
Parameters:

kwargs (Dict[ndarray, DM]) – Arbitrary number of key word arguments for data fields that should be updated.

Raises:

assertion – Keyword must be in existing data_fields.

Return type:

None