Graphics#

class Graphics(data)[source]#

Bases: object

Graphics module to present the results of do-mpc. The module is independent of all other modules and can be used optionally. The module can also be used with pickled result files in post-processing for flexible and custom graphics.

The graphics module is based on Matplotlib and allows for fully customizable, publication ready graphics and animations.

The Graphics module is initialized with an do_mpc.data.Data or do_mpc.data.MPCData module and will showcase this data.

User defined graphics are configured prior to plotting results, e.g.:

mpc = do_mpc.controller.MPC(model)
...

# Initialize graphic:
graphics = do_mpc.graphics.Graphics(mpc.data)

# Create figure with arbitrary Matplotlib method
fig, ax = plt.subplots(5, sharex=True)
# Configure plot (pass the previously obtained ax objects):
graphics.add_line(var_type='_x', var_name='C_a', axis=ax[0])
graphics.add_line(var_type='_x', var_name='C_b', axis=ax[0])
graphics.add_line(var_type='_x', var_name='T_R', axis=ax[1])
graphics.add_line(var_type='_x', var_name='T_K', axis=ax[1])
graphics.add_line(var_type='_aux', var_name='T_dif', axis=ax[2])
graphics.add_line(var_type='_u', var_name='Q_dot', axis=ax[3])
graphics.add_line(var_type='_u', var_name='F', axis=ax[4])
# Optional configuration of the plot(s) with matplotlib:
ax[0].set_ylabel('c [mol/l]')
ax[1].set_ylabel('Temperature [K]')
ax[2].set_ylabel('\Delta T [K]')
ax[3].set_ylabel('Q_heat [kW]')
ax[4].set_ylabel('Flow [l/h]')

fig.align_ylabels()

After initializing the Graphics module, the Graphics.add_line() method is used to define which results are to be plotted on which existing axes object. The method created (empty) line objects for each plotted variable. The graphic is updated with the most recent data with Graphics.plot_results(). Furthermore, the module contains the Graphics.plot_predictions() method which is applicable only for do_mpc.data.MPCData, and can be used to show the predicted trajectories.

Note

A high-level API for obtaining a configured Graphics module is the default_plot() function. Use this function and the obtained Graphics module in the developement process.

Animations can be setup with the follwing loop:

for k in range(50):
    u0 = mpc.make_step(x0)
    y_next = simulator.make_step(u0)
    x0 = estimator.make_step(y_next)

    graphics.plot_results()
    graphics.plot_predictions()
    graphics.reset_axes()
    plt.show()
    plt.pause(0.01)

Parameters:: data (Union[Data, MPCData]) – Data object from the do-mpc modules (simulator, estimator, controller)

Methods#

add_line#

add_line(self, var_type, var_name, axis, **pltkwargs)#

add_line is called during setting up the Graphics class. This is typically the last step of configuring do-mpc. Each call of Graphics.add_line() adds a line to the passed axis according to the variable type (_x, _u, _z, _tvp, _p, _aux) and its name (as defined in the do_mpc.model.Model). Furthermore, all valid matplotlib .plot arguments can be passed as optional keyword arguments, e.g.: linewidth, color, alpha.

Note

Lines can also be configured after adding them with this method. Use the result_lines() and pred_lines() attributes for this purpose.

Parameters:

var_type (str) – Variable type to be plotted. Valid arguments are _x, _u, _z, _tvp, _p, _aux.
var_name (str) – Variable name. Must reference the names defined in the model for the given variable type.
axis (Axes) – Axis object on which to plot the line(s).
pltkwargs – Valid matplotlib pyplot keyword arguments (e.g.: linewidth, color, alpha)

Raises:

assertion – var_type argument must be a string
assertion – var_name argument must be a string
assertion – var_type argument must reference to the valid var_types of do-mpc models.
assertion – axis argument must be matplotlib axes object.

Return type:

None

clear#

clear(self, lines=None)#

Clears all data from lines.

Parameters:: lines (list) –
Return type:: None

plot_predictions#

plot_predictions(self, t_ind=-1)#

Plots the predicted trajectories for the plot configuration. The predicted trajectories are part of the optimal solution at each timestep and are optionally stored in the do_mpc.data.MPCData 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().

The plot_predictions method can only be called with data from the do_mpc.controller.MPC object and raises an error if called with data from other objects. Use the t_ind parameter to plot the prediction for the given time instance. This can be used in post-processing for animations.

Parameters:

t_ind (int) – Plot predictions at this time index.

Raises:

assertion – Can only call plot_predictions with data object from do-mpc optimizer
Exception – Cannot plot predictions if full solution is not stored or supplied when calling the method
assertion – t_ind argument must be a int
assertion – t_ind argument must not exceed the length of the results

Return type:

None

plot_results#

plot_results(self, t_ind=-1)#

Plots the results stored in the data object. Use the t_ind parameter to plot only until the given time index. This can be used in post-processing for animations.

Parameters:

t_ind (int) – Plot results up until this time index.

Raises:

assertion – t_ind argument must be a int
assertion – t_ind argument must not exceed the length of the results

Return type:

None

reset_axes#

reset_axes(self)#

Relimits and scales all axes. This method calls

ax.relim()
ax.autoscale()

on all axes instances in the class.

Return type:: None

reset_prop_cycle#

reset_prop_cycle(self)#

Resets the property cycle for all axes which were passed with Graphics.add_line(). The matplotlib color cycler is restarted.

Return type:: None

Attributes#

pred_lines#

Graphics.pred_lines#

Structure that holds the prediction line objects. Query this structure with power indices. The power indices must have the following order:

pred_lines[var_type, var_name, i, k]

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 (choose 0 for scalars).
Use k to select the k-th scenario (for robust MPC). Note the k=0 is the nominal case.

Note that (e.g.) pred_lines['_x'] will return all lines for all states and pred_lines.full can be used to retrieve all line objects.

This property can be used to query and configure specific lines in the current graphic.

Example:

# Update properties for all lines:
for line_i in graphics.pred_lines.full:
    line_i.set_linewidth(2)
    line_i.set_alpha(0.5)

An extensive list of all line properties can be found here.

Parameters:: powerind (tuple) – Tuple of indices (power indices) to obtain the desired line obects
Returns:: List of line objects.

result_lines#

Graphics.result_lines#

Structure that holds the result line objects. Query this structure with power indices. The power indices must have the following order:

result_lines[var_type, var_name, i]

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
Index i is applicable if the selecte variable is vector valued.

Note that (e.g.) result_lines['_x'] will return all lines for all states and result_lines.full can be used to retrieve all line objects.

This property can be used to query and configure specific lines in the current graphic.

Example:

# Update properties for all lines:
for line_i in graphics.result_lines.full:
    line_i.set_linewidth(2)
    line_i.set_alpha(0.5)

An extensive list of all line properties can be found here.

Parameters:: powerind (tuple) – Tuple of indices (power indices) to obtain the desired line obects
Returns:: List of line objects.

Graphics

Contents

Graphics#

Methods#

add_line#

clear#

plot_predictions#

plot_results#

reset_axes#

reset_prop_cycle#

Attributes#

pred_lines#

result_lines#