# DecisionProgramming.jl

## Description

`DecisionProgramming.jl`

is a Julia package for solving multi-stage decision problems under uncertainty, modeled using influence diagrams. Internally, it relies on mathematical optimization. Decision models can be embedded within other optimization models. We designed the package as JuMP extension. We have also developed a Python interface, which is available here.

## Citting

The Decision Prgramming framework is decribed in this publication. If you found the framework useful in your work, we kindly ask you to cite the following publication (pdf):

```
@article{Salo_et_al-2022,
title = {Decision programming for mixed-integer multi-stage optimization under uncertainty},
journal = {European Journal of Operational Research},
volume = {299},
number = {2},
pages = {550-565},
year = {2022},
issn = {0377-2217},
doi = {https://doi.org/10.1016/j.ejor.2021.12.013},
url = {https://www.sciencedirect.com/science/article/pii/S0377221721010201},
author = {Ahti Salo and Juho Andelmin and Fabricio Oliveira},
keywords = {Decision analysis, Influence diagrams, Decision trees, Contingent portfolio programming, Stochastic programming}
}
```

## Syntax

We can create an influence diagram as follows:

using DecisionProgramming
diagram = InfluenceDiagram()
add_node!(diagram, DecisionNode("A", [], ["a", "b"]))
add_node!(diagram, DecisionNode("D", ["B", "C"], ["k", "l"]))
add_node!(diagram, ChanceNode("B", ["A"], ["x", "y"]))
add_node!(diagram, ChanceNode("C", ["A"], ["v", "w"]))
add_node!(diagram, ValueNode("V", ["D"]))
generate_arcs!(diagram)
add_probabilities!(diagram, "B", [0.4 0.6; 0.6 0.4])
add_probabilities!(diagram, "C", [0.7 0.3; 0.3 0.7])
add_utilities!(diagram, "V", [1.5, 1.7])
generate_diagram!(diagram)

Using the influence diagram, we create the decision model as follow:

using JuMP
model = Model()
z = DecisionVariables(model, diagram)
x_s = PathCompatibilityVariables(model, diagram, z)
EV = expected_value(model, diagram, x_s)
@objective(model, Max, EV)

We can optimize the model using MILP solver.

using Gurobi
optimizer = optimizer_with_attributes(
() -> Gurobi.Optimizer(Gurobi.Env()),
"IntFeasTol" => 1e-9,
)
set_optimizer(model, optimizer)
optimize!(model)

Finally, we extract the decision strategy from the decision variables.

Z = DecisionStrategy(z)

See the documentation for more detailed examples.

## Installation

`DecisionProgramming.jl`

is registered. You can add it using the command:

```
pkg> add DecisionProgramming
```

To run examples and develop and solve decision models, you have to install JuMP and a solver capable of solving mixed-integer linear programs (MILP). JuMP documentation contains a list of available solvers.

```
pkg> add JuMP
```

We recommend using the Gurobi solver, which is an efficient commercial solver. Academics use Gurobi for free with an academic license. You also need to install the Julia Gurobi package.

```
pkg> add Gurobi
```

Now you are ready to use decision programming.

## Development

Using the package manager, add `DecisionProgramming.jl`

package for development using the command:

```
pkg> develop DecisionProgramming
```

If you have already cloned `DecisionProgramming`

from GitHub, you can use the command:

```
pkg> develop .
```

Inside `DecisionProgramming`

directory, run tests using the commands:

```
pkg> activate .
(DecisionProgramming) pkg> test
```

You can find more instruction on how to install packages for development at Julia's Pkg documentation.