control.optimal.OptimalControlProblem

class control.optimal.OptimalControlProblem(sys, timepts, integral_cost, trajectory_constraints=[], terminal_cost=None, terminal_constraints=[], initial_guess=None, trajectory_method=None, basis=None, log=False, **kwargs)[source]

Bases: object

Description of a finite horizon, optimal control problem.

The OptimalControlProblem class holds all of the information required to specify an optimal control problem: the system dynamics, cost function, and constraints. As much as possible, the information used to specify an optimal control problem matches the notation and terminology of the SciPy optimize.minimize module, with the hope that this makes it easier to remember how to describe a problem.

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

  • timepts (1D array_like) – List of times at which the optimal input should be computed.

  • integral_cost (callable) – Function that returns the integral cost given the current state and input. Called as integral_cost(x, u).

  • 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 current state and input. Called as terminal_cost(x, u).

  • trajectory_method (string, optional) – Method to use for carrying out the optimization. Currently supported methods are ‘shooting’ and ‘collocation’ (continuous time only). The default value is ‘shooting’ for discrete time systems and ‘collocation’ for continuous time systems

  • initial_guess ((tuple of) 1D or 2D array_like) – Initial states and/or inputs to use as a guess for the optimal trajectory. For shooting methods, an array of inputs for each time point should be specified. For collocation methods, the initial guess is either the input vector or a tuple consisting guesses for the state and the input. Guess should either be a 2D vector of shape (ninputs, ntimepts) or a 1D input of shape (ninputs,) that will be broadcast by extension of the time axis.

  • log (bool, optional) – If True, turn on logging messages (using Python logging module). Use logging.basicConfig() to enable logging output (e.g., to a file).

  • basis (BasisFamily, optional) – Use the given set of basis functions for the inputs instead of setting the value of the input at each point in the timepts vector.

  • 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

ocp – Optimal control problem object, to be used in computing optimal controllers.

Return type

OptimalControlProblem

Notes

To describe an optimal control problem we need an input/output system, a time horizon, a cost function, and (optionally) a set of constraints on the state and/or input, either along the trajectory and at the terminal time. This class sets up an optimization over the inputs at each point in time, using the integral and terminal costs as well as the trajectory and terminal constraints. The compute_trajectory method sets up an optimization problem that can be solved using scipy.optimize.minimize().

The _cost_function method takes the information computes the cost of the trajectory generated by the proposed input. It does this by calling a user-defined function for the integral_cost given the current states and inputs at each point along the trajectory and then adding the value of a user-defined terminal cost at the final point in the trajectory.

The _constraint_function method evaluates the constraint functions along the trajectory generated by the proposed input. As in the case of the cost function, the constraints are evaluated at the state and input 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.

If basis is specified, then the optimization is done over coefficients of the basis elements. Otherwise, the optimization is performed over the values of the input at the specified times (using linear interpolation for continuous systems).

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_mpc

Compute the optimal input at state x

compute_trajectory

Compute the optimal input at state x

create_mpc_iosystem

Create an I/O system implementing an MPC controller

compute_mpc(x, squeeze=None)[source]

Compute the optimal input at state x

This function calls the compute_trajectory() method and returns the input at the first time point.

Parameters
  • x (array-like or number, optional) – Initial state for the system.

  • squeeze (bool, optional) – If True and if the system has a single output, return the system 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’].

Returns

input – Optimal input for the system at the current time. If the system is SISO and squeeze is not True, the array is 1D (indexed by time). If the system is not SISO or squeeze is False, the array is 2D (indexed by the output number and time). Set to None if the optimization failed.

Return type

array

compute_trajectory(x, squeeze=None, transpose=None, return_states=True, initial_guess=None, print_summary=True, **kwargs)[source]

Compute the optimal input at state x

Parameters
  • x (array-like or number, optional) – Initial state for the system.

  • return_states (bool, optional) – If True (default), return the values of the state at each time.

  • squeeze (bool, optional) – If True and if the system has a single output, return the system 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’].

  • transpose (bool, optional) – If True, assume that 2D input arrays are transposed from the standard format. Used to convert MATLAB-style inputs to our format.

Returns

  • res (OptimalControlResult) – Bundle object with the results of the optimal control problem.

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

  • res.time (array) – Time values of the input.

  • res.inputs (array) – Optimal inputs for the system. If the system is SISO and squeeze is not True, the array is 1D (indexed by time). If the system is not SISO or squeeze is False, the array is 2D (indexed by the output number and time).

  • res.states (array) – Time evolution of the state vector (if return_states=True).

create_mpc_iosystem()[source]

Create an I/O system implementing an MPC controller