csnlp.wrappers.Mpc#

class csnlp.wrappers.Mpc(nlp, prediction_horizon, control_horizon=None, input_spacing=1, shooting='multi')[source]#

Bases: NonRetroactiveWrapper[SymType]

A wrapper to easily turn an NLP scheme into an MPC controller. Most of the theory for MPC is taken from [6].

Parameters:

nlpNlp: NLP scheme to be wrapped
prediction_horizonint: A positive integer for the prediction horizon of the MPC controller.
control_horizonint, optional: A positive integer for the control horizon of the MPC controller. If not given, it is set equal to the control horizon.
input_spacingint, optional: Spacing between independent input actions. This argument allows to reduce the number of free actions along the control horizon by allowing only the first action every n to be free, and the following n-1 to be fixed equal to that action (where n is given by input_spacing). By default, no spacing is allowed, i.e., 1.
shooting‘single’ or ‘multi’, optional: Type of approach in the direct shooting for parametrizing the control trajectory. See Section 8.5 in [6]. By default, direct shooting is used.

Raises:

ValueError: Raises if the shooting method is invalid; or if any of the horizons are invalid.

Methods

`action`(name[, size, discrete, lb, ub])	Adds a control action variable to the MPC controller along the whole control horizon.
`constraint`(name, lhs, op, rhs[, soft, simplify])	See `csnlp.Nlp.constraint`.
`disturbance`(name[, size])	Adds a disturbance parameter to the MPC controller along the whole prediction horizon.
`is_wrapped`(wrapper_type)	Gets whether the NLP instance is wrapped or not by the given wrapper type.
`set_affine_dynamics`(A, B[, D, c, ...])	Sets affine dynamics as the controller's prediction model and creates the corresponding dynamics constraints.
`set_nonlinear_dynamics`(F[, parallelization, ...])	Sets the nonlinear dynamics of the controller's prediction model and creates the corresponding dynamics constraints.
`state`(name[, size, discrete, lb, ub, ...])	Adds a state variable to the MPC controller along the whole prediction horizon.

Attributes

`actions`	Gets the control actions of the MPC controller.
`actions_expanded`	Gets the expanded control actions of the MPC controller.
`control_horizon`	Gets the control horizon of the MPC controller.
`disturbances`	Gets the disturbance parameters of the MPC controller.
`first_actions`	Gets the first (along the prediction horizon) actions of the controller.
`first_states`	Gets the first (along the prediction horizon) states of the controller.
`initial_states`	Gets the initial states (parameters) of the MPC controller.
`na`	Gets the number of actions of the MPC controller.
`nd`	Gets the number of disturbances in the MPC controller.
`ns`	Gets the number of states of the MPC controller.
`nslacks`	Gets the number of slacks of the MPC controller.
`prediction_horizon`	Gets the prediction horizon of the MPC controller.
`slacks`	Gets the slack variables of the MPC controller.
`states`	Gets the states of the MPC controller.
`unwrapped`	'Returns the original NLP of the wrapper.

action(name, size=1, discrete=False, lb=-inf, ub=inf)[source]#

Adds a control action variable to the MPC controller along the whole control horizon. Automatically expands this action to be of the same length of the prediction horizon by padding with the final action.

Parameters:

namestr: Name of the control action.
sizeint, optional: Size of the control action (assumed to be a vector). Defaults to 1.
discretebool, optional: Flag indicating if the action is discrete. Defaults to False.
lbarray_like, casadi.DM, optional: Hard lower bound of the control action, by default -np.inf.
ubarray_like, casadi.DM, optional: Hard upper bound of the control action, by default +np.inf.

Returns:

actioncasadi.SX or MX: The control action symbolic variable.
action_expandedcasadi.SX or MX: The same control action variable, but expanded to the same length of the prediction horizon.

Return type:

tuple[TypeVar(SymType, SX, MX), TypeVar(SymType, SX, MX)]

property actions: dict[str, SymType]#: Gets the control actions of the MPC controller.

property actions_expanded: dict[str, SymType]#: Gets the expanded control actions of the MPC controller.

constraint(name, lhs, op, rhs, soft=False, simplify=True)[source]#

See csnlp.Nlp.constraint.

Return type:: tuple[TypeVar(SymType, SX, MX), ...]

property control_horizon: int#: Gets the control horizon of the MPC controller.

disturbance(name, size=1)[source]#

Adds a disturbance parameter to the MPC controller along the whole prediction horizon.

Parameters:

namestr: Name of the disturbance.
sizeint, optional: Size of the disturbance (assumed to be a vector). Defaults to 1.

Returns:

casadi.SX or MX: The symbol for the new disturbance in the MPC controller.

Return type:

TypeVar(SymType, SX, MX)

property disturbances: dict[str, SymType]#: Gets the disturbance parameters of the MPC controller.

property first_actions: dict[str, SymType]#: Gets the first (along the prediction horizon) actions of the controller.

property first_states: dict[str, SymType]#: Gets the first (along the prediction horizon) states of the controller.

property initial_states: dict[str, SymType]#: Gets the initial states (parameters) of the MPC controller.

is_wrapped(wrapper_type)#

Gets whether the NLP instance is wrapped or not by the given wrapper type.

Parameters:

wrapper_typetype of Wrapper: Type of wrapper to check if the NLP is wrapped with.

Returns:

bool: True if wrapped by an instance of wrapper_type; False, otherwise.

Return type:

bool

property na: int#: Gets the number of actions of the MPC controller.

property nd: int#: Gets the number of disturbances in the MPC controller.

property ns: int#: Gets the number of states of the MPC controller.

property nslacks: int#: Gets the number of slacks of the MPC controller.

property prediction_horizon: int#: Gets the prediction horizon of the MPC controller.

set_affine_dynamics(A, B, D=None, c=None, parallelization='thread', max_num_threads=None)[source]#

Sets affine dynamics as the controller’s prediction model and creates the corresponding dynamics constraints. The dynamics are in the affine form

\[x_+ = A x + B u + D w + c,\]

where \(x_+\) is the next state, \(x\) is the current state, \(u\) is the control action, \(w\) is the disturbance, and \(c\) is a constant term.

Parameters:

Asymbolic or numerical array: The state matrix \(A\) in the dynamics equation. Can also be sparse.
Bsymbolic or numerical array: The action matrix \(B\) in the dynamics equation. Can also be sparse.
Dsymbolic or numerical array, optional: The disturbance matrix \(D\) in the dynamics equation. Must be None if no disturbances were provided via the disturbance method. Can also be sparse.
csymbolic or numerical array, optional: The constant term \(c\) in the dynamics equation. By default, None. If not provided, the dynamics become linear instead of affine.
parallelization“serial”, “unroll”, “inline”, “thread”, “openmp”: The type of parallelization to use (see casadi.Function.map) when applying the dynamics along the horizon in multiple shooting. By default, "thread" is selected.
max_num_threadsint, optional: Maximum number of threads to use in parallelization (if in multiple shooting). See casadi.Function.map for more information. By default, set equal to the prediction horizon.

Returns:

Optional 4-tuple of symbolic or numerical arrays: In multiple shooting, returns a tuple of None. In single shooting, returns the matrices \(F, G, H, L\) that parametrize the dynamics. See, e.g., [5].

Raises:

RuntimeError: Raises if the dynamics were already set.
ValueError: Raises if any of the matrices have the wrong shape; or if D was not provided but disturbances were set; or if D was provided but there are no disturbances set.

Return type:: tuple[Optional[TypeVar(MatType, TypeVar(SymType, SX, MX), DM, ndarray)], Optional[TypeVar(MatType, TypeVar(SymType, SX, MX), DM, ndarray)], Optional[TypeVar(MatType, TypeVar(SymType, SX, MX), DM, ndarray)], Optional[TypeVar(MatType, TypeVar(SymType, SX, MX), DM, ndarray)]]

set_nonlinear_dynamics(F, parallelization='thread', max_num_threads_or_unrolling_base=None)[source]#

Sets the nonlinear dynamics of the controller’s prediction model and creates the corresponding dynamics constraints.

Parameters:

Fcasadi.Function or callable: A CasADi function of the form \(x_+ = F(x,u)\) or \(x+ = F(x,u,d)\), where \(x,u,d\) are the state, action, and disturbance respectively, \(F\) is a generic nonlinear function and \(x_+\) is the next state.
parallelization“serial”, “unroll”, “inline”, “thread”, “openmp”: The type of parallelization to use (see casadi.Function.map) when applying the dynamics along the horizon in multiple shooting. By default, "thread" is selected.
max_num_threads_or_unrolling_baseint, optional: Maximum number of threads to use in parallelization (if in multiple shooting), or the base for unrolling (if in single shooting). See casadi.Function.map and casadi.Function.mapaccum for more information, respectively. By default, set equal to the prediction horizon.

Raises:

ValueError: Raises if the dynamics do not accept 2 or 3 input arguments.
RuntimeError: Raises if the dynamics have been already set; or if the function F does not accept the expected input sizes.

Return type:

None

property slacks: dict[str, SymType]#: Gets the slack variables of the MPC controller.

state(name, size=1, discrete=False, lb=-inf, ub=inf, bound_initial=True, bound_terminal=True)[source]#

Adds a state variable to the MPC controller along the whole prediction horizon. Automatically creates the constraint on the initial conditions for this state.

Parameters:

namestr: Name of the state.
sizeint: Size of the state (assumed to be a vector).
discretebool, optional: Flag indicating if the state is discrete. Defaults to False.
lbarray_like, casadi.DM, optional: Hard lower bound of the state, by default -np.inf.
ubarray_like, casadi.DM, optional: Hard upper bound of the state, by default +np.inf.
bound_initialbool, optional: If False, then the upper and lower bounds on the initial state are not imposed, i.e., set to +/- np.inf (since the initial state is constrained to be equal to the current state of the system, it is sometimes advantageous to remove its bounds). By default True.
bound_terminalbool, optional: Same as above, but for the terminal state. By default True.

Returns:

statecasadi.SX or MX or None: The state symbolic variable. If shooting=single, then None is returned since the state will only be available once the dynamics are set.
initial statecasadi.SX or MX: The initial state symbolic parameter.

Raises:

ValueError: Raises if there exists already a state with the same name.
RuntimeError: Raises in single shooting if lower or upper bounds have been specified, since these can only be set after the dynamics have been set via the constraint method.

Return type: