Merge pull request #28 from gamma-opt/interface-update

Interface update

Author: solliolli

CONTRIBUTING.md

@@ -0,0 +1,16 @@
+## Contribution guidelines
+
+First of all, thank you for your interest in this project! Most of us working on this are researchers, not software engineers, so we expect there to be room for improvement in this package. If you find something that is unclear or doesn't work or should be done more efficiently etc., please let us know, but remember to be respectful.
+
+If you are new to Julia package development, we strongly recommend reading the rather well-written guide in [the JuMP documentation](https://jump.dev/JuMP.jl/dev/developers/contributing/#Contribute-code-to-JuMP).
+
+How to proceed when you have:
+- A question about how something works
+  - Ask a question on our [discussion forum](https://github.com/gamma-opt/DecisionProgramming.jl/discussions)
+  - If the reason for your confusion was that something was not properly explained in the documentation, create an issue and/or a pull request.
+- A bug report 🐛
+  - Create an issue with a minimal working example that shows how you encountered the bug.
+  - If you know how to fix the bug, you can create a pull request as well, otherwise we'll see your issue and start working on fixing whatever you found.
+- An improvement suggestion
+  - It might be a good idea to first discuss your idea with us, you can start by posting on the [discussion forum](https://github.com/gamma-opt/DecisionProgramming.jl/discussions).
+  - Create an issue and start working on a pull request.

README.md

@@ -14,30 +14,36 @@ We can create an influence diagram as follows:
 
 ```julia
 using DecisionProgramming
-S = States([2, 2, 2, 2])
-C = [ChanceNode(2, [1]), ChanceNode(3, [1])]
-D = [DecisionNode(1, Node[]), DecisionNode(4, [2, 3])]
-V = [ValueNode(5, [4])]
-X = [Probabilities(2, [0.4 0.6; 0.6 0.4]), Probabilities(3, [0.7 0.3; 0.3 0.7])]
-Y = [Consequences(5, [1.5, 1.7])]
-validate_influence_diagram(S, C, D, V)
-sort!.((C, D, V, X, Y), by = x -> x.j)
-P = DefaultPathProbability(C, X)
-U = DefaultPathUtility(V, Y)
+
+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:
 
 ```julia
 using JuMP
 model = Model()
-z = DecisionVariables(model, S, D)
-x_s = PathCompatibilityVariables(model, z, S, P)
-EV = expected_value(model, x_s, U, P)
+z = DecisionVariables(model, diagram)
+x_s = PathCompatibilityVariables(model, diagram, z)
+EV = expected_value(model, diagram, x_s)
 @objective(model, Max, EV)
 ```
 
-Finally, we can optimize the model using MILP solver.
+We can optimize the model using MILP solver.
 
 ```julia
 using Gurobi

docs/make.jl

@@ -33,5 +33,6 @@ makedocs(
 # See "Hosting Documentation" and deploydocs() in the Documenter manual
 # for more information.
 deploydocs(
-    repo = "github.com/gamma-opt/DecisionProgramming.jl.git"
+    repo = "github.com/gamma-opt/DecisionProgramming.jl.git",
+    push_preview = true
 )

docs/src/api.md

@@ -5,21 +5,22 @@
 ### Nodes
 ```@docs
 Node
+Name
+AbstractNode
 ChanceNode
 DecisionNode
 ValueNode
 State
 States
-States(::Vector{Tuple{State, Vector{Node}}})
-validate_influence_diagram
 ```
 
 ### Paths
 ```@docs
 Path
-paths(::AbstractVector{State})
-paths(::AbstractVector{State}, ::Dict{Node, State})
 ForbiddenPath
+FixedPath
+paths(::AbstractVector{State})
+paths(::AbstractVector{State}, ::FixedPath)
 ```
 
 ### Probabilities
@@ -33,9 +34,10 @@ AbstractPathProbability
 DefaultPathProbability
 ```
 
-### Consequences
+### Utilities
 ```@docs
-Consequences
+Utility
+Utilities
 ```
 
 ### Path Utility
@@ -44,6 +46,20 @@ AbstractPathUtility
 DefaultPathUtility
 ```
 
+### InfluenceDiagram
+```@docs
+InfluenceDiagram
+generate_arcs!
+generate_diagram!
+add_node!
+ProbabilityMatrix
+add_probabilities!
+UtilityMatrix
+add_utilities!
+index_of
+num_states
+```
+
 ### Decision Strategy
 ```@docs
 LocalDecisionStrategy
@@ -56,15 +72,13 @@ DecisionStrategy
 ```@docs
 DecisionVariables
 PathCompatibilityVariables
-lazy_probability_cut(::Model, ::PathCompatibilityVariables, ::AbstractPathProbability)
+lazy_probability_cut
 ```
 
 ### Objective Functions
 ```@docs
-PositivePathUtility
-NegativePathUtility
-expected_value(::Model, ::PathCompatibilityVariables, ::AbstractPathUtility, ::AbstractPathProbability; ::Float64)
-conditional_value_at_risk(::Model, ::PathCompatibilityVariables{N}, ::AbstractPathUtility, ::AbstractPathProbability, ::Float64; ::Float64) where N
+expected_value(::Model, ::InfluenceDiagram, ::PathCompatibilityVariables; ::Float64)
+conditional_value_at_risk(::Model, ::InfluenceDiagram, ::PathCompatibilityVariables{N}, ::Float64; ::Float64) where N
 ```
 
 ### Decision Strategy from Variables
@@ -76,13 +90,14 @@ DecisionStrategy(::DecisionVariables)
 ## `analysis.jl`
 ```@docs
 CompatiblePaths
+CompatiblePaths(::InfluenceDiagram, ::DecisionStrategy, ::FixedPath)
 UtilityDistribution
-UtilityDistribution(::States, ::AbstractPathProbability, ::AbstractPathUtility, ::DecisionStrategy)
+UtilityDistribution(::InfluenceDiagram, ::DecisionStrategy)
 StateProbabilities
-StateProbabilities(::States, ::AbstractPathProbability, ::DecisionStrategy)
-StateProbabilities(::States, ::AbstractPathProbability, ::DecisionStrategy, ::Node, ::State, ::StateProbabilities)
-value_at_risk(::Vector{Float64}, ::Vector{Float64}, ::Float64)
-conditional_value_at_risk(::Vector{Float64}, ::Vector{Float64}, ::Float64)
+StateProbabilities(::InfluenceDiagram, ::DecisionStrategy)
+StateProbabilities(::InfluenceDiagram, ::DecisionStrategy, ::Name, ::Name, ::StateProbabilities)
+value_at_risk(::UtilityDistribution, ::Float64)
+conditional_value_at_risk(::UtilityDistribution, ::Float64)
 ```
 
 ## `printing.jl`
@@ -96,9 +111,10 @@ print_risk_measures
 
 ## `random.jl`
 ```@docs
-random_diagram(::AbstractRNG, ::Int, ::Int, ::Int, ::Int, ::Int)
-States(::AbstractRNG, ::Vector{State}, ::Int)
-Probabilities(::AbstractRNG, ::ChanceNode, ::States; ::Int)
-Consequences(::AbstractRNG, ::ValueNode, ::States; ::Float64, ::Float64)
-LocalDecisionStrategy(::AbstractRNG, ::DecisionNode, ::States)
+random_diagram!
+random_probabilities!
+random_utilities!
+LocalDecisionStrategy(::AbstractRNG, ::InfluenceDiagram, ::Node)
+DecisionProgramming.information_set(::AbstractRNG, ::Node, ::Int64)
+DecisionProgramming.information_set(::AbstractRNG, ::Vector{Node}, ::Int64)
 ```

docs/src/decision-programming/analyzing-decision-strategies.md

@@ -1,6 +1,6 @@
 # [Analyzing Decision Strategies](@id analyzing-decision-strategies)
 ## Introduction
-This section focuses on how we can analyze fixed decision strategies $Z$ on an influence diagram $G$, such as ones resulting from the optimization. We can rule out all incompatible and inactive paths from the analysis because they do not influence the outcomes of the strategy. This means that we only consider paths $𝐬$ that are compatible and active $𝐬 \in 𝐒(X) \cap 𝐒(Z)$.
+This section focuses on how we can analyze fixed decision strategies $Z$ on an influence diagram $G$, such as ones obtained by solving the Decision Programming model described in [the previous section](@ref decision-model). We can rule out all incompatible and inactive paths from the analysis because they do not influence the outcomes of the strategy. This means that we only consider paths $𝐬$ that are compatible and active $𝐬 \in 𝐒(X) \cap 𝐒(Z)$.
 
 
 ## Generating Compatible Paths
@@ -20,7 +20,7 @@ The probability mass function of the **utility distribution** associates each un
 
 $$ℙ(X=u)=∑_{𝐬∈𝐒(Z)∣\mathcal{U}(𝐬)=u} p(𝐬),\quad ∀u∈\mathcal{U}^∗.$$
 
-From the utility distribution, we can calculate the cumulative distribution, statistics, and risk measures. The relevant statistics are expected value, standard deviation, skewness and kurtosis. Risk measures focus on the conditional value-at-risk (CVaR), also known as, expected shortfall.
+From the utility distribution, we can calculate the cumulative distribution, statistics, and risk measures. The relevant statistics are expected value, standard deviation, skewness and kurtosis. Risk measures focus on the conditional value-at-risk (CVaR), also known as expected shortfall.
 
 
 ## Measuring Risk
@@ -56,7 +56,7 @@ The above figure demonstrates these values on a discrete probability distributio
 
 
 ## State Probabilities
-We denote **paths with fixed states** where $ϵ$ denotes an empty state using a recursive definition.
+We use a recursive definition where $ϵ$ denotes an empty state to denote **paths with fixed states**.
 
 $$\begin{aligned}
 𝐒_{ϵ} &= 𝐒(Z) \\

docs/src/decision-programming/computational-complexity.md

@@ -32,15 +32,15 @@ $$0 ≤ ∑_{i∈D}|𝐒_{I(i)∪\{i\}}| ≤ |D| \left(\max_{i∈C∪D} |S_j|\ri
 
 In the worst case, $m=n$, a decision node is influenced by every other chance and decision node. However, in most practical cases, we have $m < n,$ where decision nodes are influenced only by a limited number of other chance and decision nodes, making models easier to solve.
 
-## Numerical challenges 
+## Numerical challenges
 
-As has become evident above, in Decision Programming the size of the [Decision Model](@ref decision-model) may become large if the influence diagram has a large number of nodes or nodes with a large number of states. In practice, this results in having a large number of path compatibility and decision variables. This may results in numerical challenges.
+As has become evident above, in Decision Programming the size of the [Decision Model](@ref decision-model) may become large if the influence diagram has a large number of nodes or nodes with a large number of states. In practice, this results in having a large number of path compatibility and decision variables. This may result in numerical challenges.
 
 ### Probability Scaling Factor
-In an influence diagram a large number of nodes or some nodes having a large set of states, causes the path probabilities $p(𝐬)$ to become increasingly small. This may cause numerical issues with the solver or inable it from finding a solution. This issue is showcased in the [CHD preventative care example](../examples/CHD_preventative_care.md).
+If an influence diagram has a large number of nodes or some nodes have a large set of states, the path probabilities $p(𝐬)$ become increasingly small. This may cause numerical issues with the solver, even prevent it from finding a solution. This issue is showcased in the [CHD preventative care example](../examples/CHD_preventative_care.md).
 
-The issue may be helped by multiplying the path probabilities with a scaling factor $\gamma > 0$ in the objective function.
+The issue may be helped by multiplying the path probabilities with a scaling factor $\gamma > 0$. For example, the objective function becomes
 
-$$\operatorname{E}(Z) = ∑_{𝐬∈𝐒} x(𝐬) \ p(𝐬) \ \gamma \ \mathcal{U}(𝐬)$$
+$$\operatorname{E}(Z) = ∑_{𝐬∈𝐒} x(𝐬) \ p(𝐬) \ \gamma \ \mathcal{U}(𝐬).$$
 
-The conditional value-at-risk function can also be scaled so that it is compatible with an expected value objective function that has been scaled.
+The path probabilities should also be scaled in other objective functions or constraints, including the conditional value-at-risk function and the probability cut constraint $∑_{𝐬∈𝐒}x(𝐬) p(𝐬) = 1$.