control.optimal.OptimalControlProblem

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

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 scipy.optimize module, with the hope that this makes it easier to remember how to describe a problem.

Parameters

sysInputOutputSystem

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

timepts1D array_like

List of times at which the optimal input should be computed.

integral_costcallable

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

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

trajectory_methodstring, 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.

logbool, optional

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

Other Parameters

basisBasisFamily, 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_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 control problem we need an input/output system, a set of time points over a a fixed 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 time 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>'].

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_mpc	Compute the optimal input at state x.
compute_trajectory	Compute the optimal trajectory starting at state x.
create_mpc_iosystem	Create an I/O system implementing an MPC controller.

compute_mpc(x, squeeze=None)

Compute the optimal input at state x.

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

Parameters

xarray_like or number, optional

Initial state for the system.

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

inputarray

Optimal input for the system at the current time, as a 1D array (even in the SISO case). Set to None if the optimization failed.

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

Compute the optimal trajectory starting at state x.

Parameters

xarray_like or number, optional

Initial state for the system.

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.

return_statesbool, optional

If True (default), return the values of the state at each time.

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

transposebool, optional

If True, assume that 2D input arrays are transposed from the standard format. Used to convert MATLAB-style inputs to our format.

print_summarybool, optional

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

Returns

resOptimalControlResult

Bundle object with the results of the optimal control problem.

res.successbool

Boolean flag indicating whether the optimization was successful.

res.timearray

Time values of the input.

res.inputsarray

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

Time evolution of the state vector.

create_mpc_iosystem(**kwargs)

Create an I/O system implementing an MPC controller.

For a discrete-time system, creates an input/output system taking the current state x and returning the control u to apply at the current time step.

Parameters

namestr, optional

Name for the system controller. Defaults to a generic system name of the form ‘sys[i]’.

inputslist of str, optional

Labels for the controller inputs. Defaults to the system state labels.

outputslist of str, optional

Labels for the controller outputs. Defaults to the system input labels.

stateslist of str, optional

Labels for the internal controller states, which consist either of the input values over the horizon of the controller or the coefficients of the basis functions. Defaults to strings of the form ‘x[i]’.

Returns

NonlinearIOSystem

Notes

Only works for discrete-time systems.