csnlp.wrappers.ScenarioBasedMpc#

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

Bases: Mpc[SymType]

Implementation of the Scenario-based Model Predictive Control [7], here referred to as SCMPC, a well-known stochastic MPC formulation.

Parameters:

nlpNlp: NLP scheme to be wrapped
n_scenariosint: Number of scenarios to be considered in the scenario-based MPC formulation. Must be a positive integer.
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; or if the number of scenarios is not a positive integer.

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`.
`constraint_from_single`(name, lhs, op, rhs[, ...])	Similarly to `csnlp.wrappers.Mpc.constraint`, adds a constraint to the MPC scheme.
`disturbance`(name[, size])	Adds one disturbance parameter per scenario to the SCMPC controller along the whole prediction horizon.
`disturbances_i`(i)	Gets the symbolic disturbances belonging to the i-th scenario.
`is_wrapped`(wrapper_type)	Gets whether the NLP instance is wrapped or not by the given wrapper type.
`minimize_from_single`(objective)	Similarly to `csnlp.Nlp.minimize`, adds the objective to be minimized to the NLP scheme.
`name_i`(base_name, i)	Gets the name of the i-th scenario.
`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.
`slacks_i`(i)	Gets the symbolic slack variables belonging to the i-th scenario.
`state`(name[, size, discrete, lb, ub, ...])	Adds one state variable per scenario to the SCMPC controller.
`states_i`(i)	Gets the symbolic states belonging to the i-th scenario.

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.
`n_scenarios`	Gets the number of scenarios.
`na`	Gets the number of actions of the MPC controller.
`nd`	Gets the number of disturbances in the MPC controller.
`nd_all`	Gets the number of disturbances of the SCMPC controller considering all scenarios.
`ns`	Gets the number of states of the MPC controller.
`ns_all`	Gets the number of states of the SCMPC controller considering all scenarios.
`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)#

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)#

See csnlp.Nlp.constraint.

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

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

Similarly to csnlp.wrappers.Mpc.constraint, adds a constraint to the MPC scheme. However, instead of manually creating the constraint for each scenario, this method allows to define only one constraint expression for a single scenario, which is then automatically declined for all scenarios. The symbolical expression must be made up of the single scenario states and disturbances, returned as first output by the methods state and disturbance, respectively. Note that the return types are lists of symbolical variables.

Returns:

exprslist of casadi.SX or MX: The constraint expression in canonical form, i.e., \(g(x,u) = 0\) or \(h(x,u) <= 0\), for each scenario.
lamslist of casadi.SX or MX: The symbol corresponding to the constraint’s multipliers, for each scenario.
single slackcasadi.SX or MX: Symbol corresponding to the slack from a single scenario. This is useful for automatically defining, e.g., the objective over the various scenarios of the SCMPC controller, but it is not used in the actual NLP solver. Only returned if soft=True; otherwise, only a 2-tuple is returned.
slackslist of casadi.SX or MX, optional: Each scenario’s slack variable in case of soft=True; otherwise, only a 2-tuple is returned.

Return type:

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

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

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

Adds one disturbance parameter per scenario to the SCMPC 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:

single disturbancecasadi.SX or MX: Symbol corresponding to the disturbance of a single scenario. See the note for :meth:state.
disturbanceslist of casadi.SX or MX: The symbols for the new disturbances of each scenario in the SCMPC controller.

Return type:

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

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

disturbances_i(i)[source]#

Gets the symbolic disturbances belonging to the i-th scenario.

Return type:: dict[str, TypeVar(SymType, SX, MX)]

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

minimize_from_single(objective)[source]#

Similarly to csnlp.Nlp.minimize, adds the objective to be minimized to the NLP scheme. However, instead of manually creating the objective for each scenario, this method allows to define only one expression for a single scenario, which is then automatically declined and summed for all scenarios. The symbolical expression must be made up of the single scenario states, disturbances, and slacks, returned as first output by the methods state, disturbance, and constraint_from_single, respectively.

Return type:: None

property n_scenarios: int#: Gets the number of scenarios.

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

name_i(base_name, i)[source]#

Gets the name of the i-th scenario.

Return type:: str

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

property nd_all: int#: Gets the number of disturbances of the SCMPC controller considering all scenarios.

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

property ns_all: int#: Gets the number of states of the SCMPC controller considering all scenarios.

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

slacks_i(i)[source]#

Gets the symbolic slack variables belonging to the i-th scenario.

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

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

Adds one state variable per scenario to the SCMPC controller. Automatically creates the (shared) constraint on the initial conditions for these states.

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:

single statecasadi.SX or MX: Symbol corresponding to the state of a single scenario. This is useful for automatically defining, e.g., the objective and constraints over the various scenarios of the SCMPC controller, but it is not used in the actual NLP solver.
stateslist of casadi.SX or MX or None: The list of the state symbolic variable. If shooting=single, then None is returned since the states 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: