DynaProg

Solve multi-stage deterministic decision problems

Syntax

prob = DynaProg(StateGrid, StateInitial, StateFinal, ControlGrid, NStages, SysName)

prob = DynaProg(StateGrid, StateInitial, [], ControlGrid, NStages, SysName)

prob = DynaProg(StateGrid, StateInitial, StateFinal, ControlGrid, NStages, ExtSysName, IntSysName)

prob = DynaProg(__, Name, Value)

prob = run(prob)

plot(prob)

Description

prob = DynaProg(StateGrid, StateInitial, StateFinal, ControlGrid, NStages, SysName) creates the basic problem structure prob.

prob = DynaProg(StateGrid, StateInitial, [], ControlGrid, NStages, SysName) creates the basic problem structure prob, with no contraints on the final state.

prob = DynaProg(StateGrid, StateInitial, StateFinal, ControlGrid, NStages, ExtSysName, IntSysName) creates the basic problem structure prob, using the configuration matrices approach.

prob = DynaProg(__, Name, Value) specifies additional properties and information with parameter/value pairs.

prob = run(prob) runs the optimization algorithm on an existing problem structure and stores the results in the problem structure prob.

plot(prob) visualizes results of an existing problem structure containing optimization results.

Input Arguments

StateGrid

StateGrid is a cell array of numeric vectors, where each vector defines the discretized grid for a state variable.

StateInitial

StateInitial is a cell array of scalar values, where each value defines the initial value for a state variable.

StateFinal

StateFinal is a cell array of two-element vectors, where each vector defines lower and upper constraints for the final value for each state variable. Each vector must contain the lower and upper bound, in this order.

ControlGrid

ControlGrid is a cell array of numeric vectors, where each vector defines the discretized grid for a control variable.

NStages

NStages is the number of stages of the optimization problem.

SysName

SysName is a function handle to the model function. The model function must return the updated state value and the stage cost as a function of the current state value and the control variables. Additionally, it can accept an exogenous input and it can return unfeasibilities.The structure of the model function must be:

[x_next, stageCost, unfeas] = SysName(x, u, w);

where:

x is a cell array, where each cell contains the value for a state variable.
u is a cell array, where each cell contains the value for a control variable.
w (optional) is a cell array, where each cell contains the value for an exogenous input variable. If not needed, replace with a tilde (~) in the function signature. See also Set up a basic problem.
x_next is a cell array, where each cell contains the value for the updated state variable.
stageCost is a numeric variable, containing the stage cost.
unfeas is either an empty array a boolean variable, set to true for unfeasible (not allowed) combinations of state variables, control variables and exogenous inputs. If not needed, return an empty array ([]) in its place.

ExtSysName

ExtSysName is a function handle to the external model function. The external model function must return the intermediate variables as a function of the control variables. Additionally, it can accept exogenous inputs and it can return unfeasibilities. The structure of the external model function must be:

[m, unfeas] = ExtSysName(u, w);

where:

u is a cell array, where each cell contains the value for a control variable.

w (optional) is a cell array, where each cell contains the value for an exogenous input variable.

m is a cell array, where each cell contains the value for an intermediate variable.

unfeas (optional) is a boolean variable, set to true for unfeasible (not allowed) combinations of state variables, control variables and exogenous inputs.

IntSysName

IntSysName is a function handle to the internal model function. The internal model function must return the updated state value and the stage cost as a function of the current state value, the control variables and the intermediate variables. Additionally, it can accept an exogenous input and it can return unfeasibilities (both are optional).

The structure of the model function must be:

[x_next, stageCost, unfeas] = IntSysName(x, u, m, w);

where:

x is a cell array, where each cell contains the value for a state variable.
u is a cell array, where each cell contains the value for a control variable.
m is a cell array, where each cell contains the value for an intermediate variable.
w (optional) is a cell array, where each cell contains the value for an exogenous input variable.
x_next is a cell array, where each cell contains the value for the updated state variable.
stageCost is a numeric variable, containing the stage cost.
unfeas (optional) is a boolean variable, set to true for unfeasible (not allowed) combinations of state variables, control variables and exogenous inputs.

Name-Value Pair Arguments

Optional arguments. Specify each argument with a pair of arguments Name, Value. Name is one of the argument names specified below and it must be written inside quotes. Value is the value you want to specify for that setting. You can specify any number of name-value pair arguments, in any order.

'UseLevelSet'

Enable Level-Set DP. Defaults to false if unspecified.

'ExogenousInput'

Specify exogenous inputs required for your model in a cell array of numeric vectors. Each vector must have the same length as the number of stages of the optimization problem.

'SafeMode'

Enable Safe Mode (see the documentation).

'StoreControlMap'

Store the optimal control variables as a function of state for each stage. This cv map is returned in prob.ControlMap as a

- by -

cell array,

being the number of control variables. Each cell is a $N_{SV_1} x N_{SV_2} x ... x N_{SV__{NS}}$ array which contain the optimal value for the correspondant control variable and stage as a function of the state variables.

'StoreValueFunction'

Store the value function. If true, running the problem also stores the value function for each stage in a cell array VF.

'StateName'

Specify state variables names in a string array.

'ControlName'

Specify state variables names in a string array.

'CostName'

Specify the cumulative cost name as a string.

'Time'

Specify time instead of stages. This property is only used in the plots produced with the plot method. It does not affect the optimization.

'TerminalCost'

Specify a terminal cost

as a function handle. This property defaults to a null cost. See Specify a terminal cost and this example for more usage information or the terminal cost section in the theory guide for more information.

'VFPenalty'

Specify how final state values outside of the final state constraints bounds should be penalized.

Set to 'rift' to penalize state values outside of the bounds specified as StateFinal penalize with a cost equal to infinity.
Set to 'linear' to penalize them with a cost term proportional to the distance from the bounds.
Set to 'none' to disable any penalization. This may be useful if you want to only use your own terminal cost specified with the TerminalCost property.

This property defaults to 'linear' if 'UseLevelSet' is set to true and it is set to 'rift' otherwise.

Read the terminal cost section in the theory guide for more information.

'VFPenFactors'

Specify the proportionality factors for the linear terminal cost. This property is only used if VFPenalty is set to 'linear'. Specify as a numeric array with one factor for each state variable. Read the terminal cost section in the theory guide for more information.

'myInf'

Specify penalty term for the terminal cost when VFPenalty is set to 'rift'. This term is used to penalize deviations of the terminal state when it is outside of the terminal state bounds. This term should be larger than your expected total cost by at least one or two orders of magnitude. However, it may cause numerical issues if you set it too large.

'EnforceStateGrid'

Set a constraint on the state variables so that they do not exceed the state grids. This constraint is needed if your system allows to strongly exceed the state bounduaries over a single stage (simulation step). Defaults to true if unspecified.

'Display'

Adjust the level of display in the command window. Defaults to 'detailed' if unspecified.

Set to 'off' to display no output.
Set to 'warn' to displays only warnings and hide the progress bar.
Set to 'detailed' to display both warnings and the progress bar.

Output Arguments

prob

Problem structure, containing all the information required to set up and run the optimization. After run is used on a problem structure to run the optmization algorithm, it also contains the optimization results. Most importantly:

prob.StateProfile is a cell array, with one cell for each state variable. Each cell contains a vector with the values for that state variable at each stage.
prob.ControlProfile is a cell array, with one cell for each control variable. Each cell contains a vector with the values for that control variable at each stage.
prob.CostProfile is a vector containing the stageCost at each stage (not including the terminal state cost).
prob.AddOutputsProfile is a cell array, with one cell for each additional output. Each cell contains a vector with the values for that additional output at each stage.
prob.totalCost is the total evaluated cost. If the optimization failed, prob.totalCost is set to inf.

Contact: federico.miretti@polito.it