csnlp.wrappers.MultiScenarioMpc

class csnlp.wrappers.MultiScenarioMpc(nlp, n_scenarios, prediction_horizon, control_horizon=None, input_spacing=1, input_sharing=1, shooting='multi')

Bases: ScenarioBasedMpc[SymType]

Multi-scenario model predictive control (MSMPC) wrapper for a csnlp.Nlp scheme. It generlizes csnlp.wrappers.ScenarioBasedMpc to allow for multiple scenarios, each with its own state trajectory, action sequence (a number of these actions can be shared across all scenarios; see input_sharing), and parameters.

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.

input_sharingint, optional

Number of actions that are shared across all scenarios. If 0, each scenario has its own action trajectory; if n, all scenarios share the same first n actions. Must not be larger than the number of free actions in the control horizon. By default, 1, so only the first action is shared across the scenarios.

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; or if input_sharing is not a valid integer (nonnegative and not larger than the number of free actions in the control horizon).

Methods

action(name[, size, discrete, lb, ub])	Adds one control action variable per scenario to the MSMPC controller.
actions_expanded_i(i)	Gets the symbolic expanded actions belonging to the i-th scenario.
actions_i(i)	Gets the symbolic actions belonging to the i-th scenario.
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.
parameter(name[, shape])	Adds one parameter per scenario to the MSMPC controller.
parameters_i(i)	Gets the symbolic parameters belonging to 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	Number of actions in a single scenario in the NLP scheme.
na_all	Gets the number of actions of the MSMPC controller considering all scenarios.
nd	Gets the number of disturbances in the MPC controller.
nd_all	Gets the number of disturbances of the SCMPC controller considering all scenarios.
np	Number of parameters in a single scenario in the NLP scheme.
np_all	Gets the number of parameters of the MSMPC 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 one control action variable per scenario to the MSMPC controller. Automatically handles sharing of actions across scenarios, generating less free actions if some of these are to be shared across scenarios.

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:

single actioncasadi.SX or MX

Symbol corresponding to the action of a single scenario. This is useful for automatically defining, e.g., the objective and constraints over the various scenarios of the MSMPC controller, but it is not used in the actual NLP solver.

single action expandedcasadi.SX or MX

Same as above, but the action is expanded to the same length of the prediction horizon.

actionslist of casadi.SX or MX

The list of the action symbolic variable.

actions expandedlist of casadi.SX or MX

The list of the same action symbolic variable, but expanded to the same length of the prediction horizon.

Return type:

tuple[TypeVar(SymType, SX, MX), TypeVar(SymType, SX, MX), list[TypeVar(SymType, SX, MX)], list[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.

actions_expanded_i(i)

Gets the symbolic expanded actions belonging to the i-th scenario.

Return type:

dict[str, TypeVar(SymType, SX, MX)]

actions_i(i)

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

Return type:

dict[str, TypeVar(SymType, SX, MX)]

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)

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)

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)

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)

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

Number of actions in a single scenario in the NLP scheme.

property na_all: int

Gets the number of actions of the MSMPC controller considering all scenarios.

name_i(base_name, i)

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 np: int

Number of parameters in a single scenario in the NLP scheme.

property np_all: int

Gets the number of parameters of the MSMPC 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.

parameter(name, shape=(1, 1))

Adds one parameter per scenario to the MSMPC controller.

Parameters:

namestr

Name of the new parameter. Must not be already in use.

shapetuple of 2 ints, optional

Shape of the new parameter. By default a scalar, i.e., (1, 1).

Returns:

single_parametercasadi.SX or MX

Symbol corresponding to the parameter of a single scenario. See the note for :meth:state

parameterslist of casadi.SX or MX

The symbols for the new parameters of each scenario in the MSMPC controller.

Raises:

ValueError

Raises if there is already another parameter with the same name name.

Return type:

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

parameters_i(i)

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

Return type:

dict[str, TypeVar(SymType, SX, MX)]

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)

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)

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)

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)

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:

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

property states: dict[str, SymType]

Gets the states of the MPC controller.

states_i(i)

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

Return type:

dict[str, TypeVar(SymType, SX, MX)]

property unwrapped: Nlp[SymType]

‘Returns the original NLP of the wrapper.

Examples using csnlp.wrappers.MultiScenarioMpc

Multiple Scenario MPC

Multiple Scenario MPC