control.optimal.OptimalEstimationProblem

class control.optimal.OptimalEstimationProblem(sys, timepts, integral_cost, terminal_cost=None, trajectory_constraints=None, control_indices=None, disturbance_indices=None, **kwargs)

Bases: object

Description of a finite horizon, optimal estimation problem.

The OptimalEstimationProblem class holds all of the information required to specify an optimal estimation problem: the system dynamics, cost function (negative of the log likelihood), and constraints.

Parameters

• sys (InputOutputSystem) – I/O system for which the optimal input will be computed.

• timepts (1D array) – Set up time points at which the inputs and outputs are given.

• integral_cost (callable) – Function that returns the integral cost given the estimated state, system inputs, and output error. Called as integral_cost(xhat, u, v, w) where xhat is the estimated state, u is the appplied input to the system, v is the estimated disturbance input, and w is the difference between the measured and the estimated output.

• trajectory_constraints (list of constraints, optional) – List of constraints that should hold at each point in the time vector. Each element of the list should be an object of type LinearConstraint with arguments (A, lb, ub) or NonlinearConstraint with arguments (fun, lb, ub). The constraints will be applied at each time point along the trajectory.

• terminal_cost (callable, optional) – Function that returns the terminal cost given the initial estimated state and expected value. Called as terminal_cost(xhat, x0).

• control_indices (int, slice, or list of int or string, optional) – Specify the indices in the system input vector that correspond to the control inputs. These inputs will be used as known control inputs for the estimator. If value is an integer m, the first m system inputs are used. Otherwise, the value should be a slice or a list of indices. The list of indices can be specified as either integer offsets or as system input signal names. If not specified, defaults to the complement of the disturbance indices (see also notes below).

• disturbance_indices (int, list of int, or slice, optional) – Specify the indices in the system input vector that correspond to the process disturbances. If value is an integer m, the last m system inputs are used. Otherwise, the value should be a slice or a list of indices, as describedf for control_indices. If not specified, defaults to the complement of the control indicies (see also notes below).

• terminal_constraints (list of constraints, optional) – List of constraints that should hold at the terminal point in time, in the same form as trajectory_constraints.

• solve_ivp_method (str, optional) – Set the method used by scipy.integrate.solve_ivp().

• solve_ivp_kwargs (str, optional) – Pass additional keywords to scipy.integrate.solve_ivp().

• minimize_method (str, optional) – Set the method used by scipy.optimize.minimize().

• minimize_options (str, optional) – Set the options keyword used by scipy.optimize.minimize().

• minimize_kwargs (str, optional) – Pass additional keywords to scipy.optimize.minimize().

Returns

oep – Optimal estimation problem object, to be used in computing optimal estimates.

Return type

OptimalEstimationProblem

Notes

To describe an optimal estimation problem we need an input/output system, a set of time points, applied inputs and measured outputs, a cost function, and (optionally) a set of constraints on the state and/or inputs along the trajectory (and at the terminal time). This class sets up an optimization over the state and disturbances at each point in time, using the integral and terminal costs as well as the trajectory constraints. The compute_estimate() method solves the underling optimization problem using scipy.optimize.minimize().

The control input and disturbance indices can be specified using the control_indices and disturbance_indices keywords. If only one is given, the other is assumed to be the remaining indices in the system input. If neither is given, the disturbance inputs are assumed to be the same as the control inputs.

The “cost” (e.g. negative of the log likelihood) of the estimated trajectory is computed using the estimated state, the disturbances and noise, and the measured output. This is done by calling a user-defined function for the integral_cost along the trajectory and then adding the value of a user-defined terminal cost at the initial point in the trajectory.

The constraint functions are evaluated at each point on the trajectory generated by the proposed estimate and disturbances. As in the case of the cost function, the constraints are evaluated at the estimated state, inputs, and measured outputs along each point on the trajectory. This information is compared against the constraint upper and lower bounds. The constraint function is processed in the class initializer, so that it only needs to be computed once.

The default values for minimize_method, minimize_options, minimize_kwargs, solve_ivp_method, and solve_ivp_options can be set using config.defaults[‘optimal.<keyword>’].

Methods

compute_estimate	Compute the optimal input at state x
create_mhe_iosystem	Create an I/O system implementing an MPC controller

compute_estimate(Y, U, X0=None, initial_guess=None, squeeze=None, print_summary=True)

Compute the optimal input at state x

Parameters

• Y (2D array) – Measured outputs at each time point.

• U (2D array) – Applied inputs at each time point.

• X0 (1D array) – Expected initial value of the state.

• initial_guess (2-tuple of 2D arrays) – A 2-tuple consisting of the estimated states and disturbance values to use as a guess for the optimal estimated trajectory.

• squeeze (bool, optional) – If True and if the system has a single disturbance input and single measured output, return the system input and output as a 1D array rather than a 2D array. If False, return the system output as a 2D array even if the system is SISO. Default value set by config.defaults[‘control.squeeze_time_response’].

• print_summary (bool, optional) – If True (default), print a short summary of the computation.

Returns

• res (OptimalEstimationResult) – Bundle object with the results of the optimal estimation problem.

• res.success (bool) – Boolean flag indicating whether the optimization was successful.

• res.time (array) – Time values of the input (same as self.timepts).

• res.inputs (array) – Estimated disturbance inputs for the system trajectory.

• res.states (array) – Time evolution of the estimated state vector.

• res.outputs (array) – Estimated measurement noise for the system trajectory.

create_mhe_iosystem(estimate_labels=None, measurement_labels=None, control_labels=None, inputs=None, outputs=None, **kwargs)

Create an I/O system implementing an MPC controller

This function creates an input/output system that implements a moving horizon estimator for a an optimal estimation problem. The I/O system takes the system measurements and applied inputs as as inputs and outputs the estimated state.

Parameters

• estimate_labels (str or list of str, optional) – Set the name of the signals to use for the estimated state (estimator outputs). If a single string is specified, it should be a format string using the variable i as an index. Otherwise, a list of strings matching the size of the estimated state should be used. Default is “xhat[{i}]”. These settings can also be overriden using the outputs keyword.

• measurement_labels (str or list of str, optional) – Set the name of the measurement and control signal names (estimator inputs). If a single string is specified, it should be a format string using the variable i as an index. Otherwise, a list of strings matching the size of the system inputs and outputs should be used. Default is the signal names for the system outputs and control inputs. These settings can also be overriden using the inputs keyword.

• control_labels (str or list of str, optional) – Set the name of the measurement and control signal names (estimator inputs). If a single string is specified, it should be a format string using the variable i as an index. Otherwise, a list of strings matching the size of the system inputs and outputs should be used. Default is the signal names for the system outputs and control inputs. These settings can also be overriden using the inputs keyword.

• **kwargs – Additional keyword arguments to set system, input, and output signal names; see InputOutputSystem().

• optional – Additional keyword arguments to set system, input, and output signal names; see InputOutputSystem().

Returns

estim – An I/O system taking the measured output and applied input for the model system and returning the estimated state of the system, as determined by solving the optimal estimation problem.

Return type

InputOutputSystem

Notes

The labels for the input signals for the system are determined based on the signal names for the system model used in the optimal estimation problem. The system name and signal names can be overridden using the name, input, and output keywords, as described in InputOutputSystem().