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

sysInputOutputSystem

I/O system for which the optimal input will be computed.

timepts1D array

Set up time points at which the inputs and outputs are given.

integral_costcallable

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 applied input to the system, v is the estimated disturbance input, and w is the difference between the measured and the estimated output.

trajectory_constraintslist 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 scipy.optimize.LinearConstraint with arguments (A, lb, ub) or scipy.optimize.NonlinearConstraint with arguments (fun, lb, ub). The constraints will be applied at each time point along the trajectory.

terminal_costcallable, optional

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

control_indicesint, 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_indicesint, 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 described for control_indices. If not specified, defaults to the complement of the control indices (see also notes below).

Other Parameters

terminal_constraintslist of constraints, optional

List of constraints that should hold at the terminal point in time, in the same form as trajectory_constraints.

solve_ivp_methodstr, optional

Set the method used by scipy.integrate.solve_ivp.

solve_ivp_kwargsstr, optional

Pass additional keywords to scipy.integrate.solve_ivp.

minimize_methodstr, optional

Set the method used by scipy.optimize.minimize.

minimize_optionsstr, optional

Set the options keyword used by scipy.optimize.minimize.

minimize_kwargsstr, optional

Pass additional keywords to scipy.optimize.minimize.

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>'].

Attributes

constraint: list of SciPy constraint objects

List of scipy.optimize.LinearConstraint or scipy.optimize.NonlinearConstraint objects.

constraint_lb, constrain_ub, eqconst_valuelist of float

List of constraint bounds.

Methods

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

compute_estimate(outputs=None, inputs=None, initial_state=None, initial_guess=None, squeeze=None, print_summary=True, **kwargs)

Compute the optimal input at state x.

Parameters

outputs (or Y)2D array

Measured outputs at each time point.

inputs (or U)2D array

Applied inputs at each time point.

initial_state (or X0)1D array

Expected initial value of the state.

initial_guess2-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.

squeezebool, 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_summarybool, optional

If True (default), print a short summary of the computation.

Returns

resOptimalEstimationResult

Bundle object with the results of the optimal estimation problem.

res.successbool

Boolean flag indicating whether the optimization was successful.

res.timearray

Time values of the input (same as self.timepts).

res.inputsarray

Estimated disturbance inputs for the system trajectory.

res.statesarray

Time evolution of the estimated state vector.

res.outputsarray

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_labelsstr 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 overridden using the outputs keyword.

measurement_labels, control_labelsstr or list of str, optional

Set the names 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 overridden using the inputs keyword.

**kwargs, optional

Additional keyword arguments to set system, input, and output signal names; see InputOutputSystem.

Returns

estimInputOutputSystem

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.

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.