Merge pull request #58 from gamma-opt/minorfixes

Minor fixes before release

Author: solliolli

README.md

@@ -6,8 +6,8 @@
 ## Description
 `DecisionProgramming.jl` is a [Julia](https://julialang.org/) 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](https://jump.dev/) extension. We have also developed a [Python](https://python.org) interface, which is available [here](https://github.com/gamma-opt/pyDecisionProgramming). 
 
-## Citting
-The Decision Programming 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](https://www.sciencedirect.com/science/article/pii/S0377221721010201/pdf)):
+## Citing
+The Decision Programming framework is described in this publication. If you found the framework useful in your work, we kindly ask you to cite the following publication ([pdf](https://www.sciencedirect.com/science/article/pii/S0377221721010201/pdf)):
 ```
 @article{Salo_et_al-2022,
     title = {Decision programming for mixed-integer multi-stage optimization under uncertainty},
@@ -24,6 +24,23 @@ The Decision Programming framework is decribed in this publication. If you found
 }
 ```
 
+If you use the rooted junction tree models, we kindly ask you to cite the following publication ([pdf](https://www.sciencedirect.com/science/article/pii/S0377221721010201/pdf)):
+```
+@article{Parmentier_et_al-2020,
+    title = {Integer programming on the junction tree polytope for influence diagrams},
+    journal = {INFORMS Journal on Optimization},
+    volume = {2},
+    number = {3},
+    pages = {209--228},
+    year = {2020},
+    issn = {0377-2217},
+    doi = {https://doi.org/10.1287/ijoo.2019.0036},
+    url = {https://pubsonline.informs.org/doi/epdf/10.1287/ijoo.2019.0036},
+    author = {Parmentier, Axel and Cohen, Victor and Lecl{\`e}re, Vincent and Obozinski, Guillaume and Salmon, Joseph},
+    keywords = {Influence diagrams, Partially observed Markov decision processes, probabilistic graphical models, Linear programming}
+}
+```
+
 ## Syntax
 ![](examples/figures/simple-id.svg)
 

docs/src/decision-programming/RJT-model.md

@@ -1,4 +1,4 @@
-# [RJT model](RJT-model.md)
+# [RJT model](@id RJT-model)
 ## Introduction
 Influence diagrams can be represented as directed rooted trees composed of clusters, which can be transformed into gradual rooted junction trees (RJTs) by imposing additional constraints. These can then be used to formulate an optimization model. Solving for optimal decision strategies using these formulations is computationally more efficient than for path based formulations. Using RJT based formulations is thus generally preferable.
 
@@ -101,8 +101,6 @@ Currently, the RJT formulation commands in the package do not support forbidden
 
 [^1]: Herrala, O., Terho, T., Oliveira, F., 2024. Risk-averse decision strategies for influence diagrams using rooted junction trees. Retrieved from [https://arxiv.org/abs/2401.03734]
 
-[^2]: Parmentier, A., Cohen, V., Leclere, V., Obozinski, G., Salmon, J., 2020. `
-Integer programming on the junction tree polytope for influence diagrams. INFORMS Journal on Optimization 2, 209–228.
+[^2]: Parmentier, A., Cohen, V., Leclere, V., Obozinski, G., Salmon, J., 2020. Integer programming on the junction tree polytope for influence diagrams. INFORMS Journal on Optimization 2, 209–228.
 
-[^3]: Koller, D., Friedman, N., 2009. Probabilistic graphical models: principles
-and techniques. MIT press
+[^3]: Koller, D., Friedman, N., 2009. Probabilistic graphical models: principles and techniques. MIT press

docs/src/decision-programming/cvar.md

@@ -72,7 +72,8 @@ $$\operatorname{CVaR}_α(Z)=\frac{1}{α}∑_{𝐬∈𝐒}\bar{ρ}(𝐬) \mathcal
 
 ## RJT model
 
-:warning: **WARNING**: A diagram can have only a single value node, when using RJT-based CVaR. Trying to call the RJT-based CVaR function using a diagram with more than one value node results in an error.
+!!! warning 
+    A diagram can have only a single value node when using RJT-based CVaR. Trying to call the RJT-based CVaR function using a diagram with more than one value node results in an error.
 
 CVaR formulation for the RJT model is close to that of path-based model. We denote the possible utility values with $u ∈ U$ and suppose we can define the probability $p(u)$ of attaining a given utility value. In the presence of a single value node, we define $p(u) = ∑_{s_{C_v}∈ \text{\{} S_{C_v} \vert U(s_{C_v})=u \text{\}} }µ(s_{C_v})$. We can then pose the constraints
 
@@ -98,9 +99,9 @@ $$\bar{ρ}(u),ρ(u)∈[0, 1],\quad ∀u∈U \tag{35}$$
 
 $$η∈\mathbb{R} \tag{36}$$
 
-where where α is the probability level in CVaR_α.
+where $α$ is the probability level in $CVaR_α$.
 
-CVaR_α can be obtained as $1/α ∑_{u∈U} \bar{ρ}(u)u$.
+Finally, $CVaR_α$ can be obtained as $1/α ∑_{u∈U} \bar{ρ}(u)u$.
 
 More details, including explanations of variables and constraints, can be found from Herrala et al. (2024)[^1].
 
@@ -113,4 +114,4 @@ where the parameter $w∈[0, 1]$ expresses the decision maker's **risk tolerance
 
 
 ## References
-[^1]: Herrala, O., Terho, T., Oliveira, F., 2024. Risk-averse decision strategies for influence diagrams using rooted junction trees. Retrieved from [https://arxiv.org/abs/2401.03734]
+[^1]: Herrala, O., Terho, T., Oliveira, F., 2024. Risk-averse decision strategies for influence diagrams using rooted junction trees. Retrieved from [https://arxiv.org/abs/2401.03734]

docs/src/decision-programming/path-based-model.md

@@ -1,4 +1,4 @@
-# [Path-based model](path-based-model.md)
+# [Path-based model](@id path-based-model)
 ## Introduction
 
 This section introduces path variables and how to structure an optimization problem based on them. Generally solution times are slower for path based formulations than for RJT based formulations and thus using [RJT formulations](RJT-model.md) is recommended.
@@ -126,7 +126,7 @@ The **default path utility** is the sum of node utilities $U_j$
 
 $$\mathcal{U}(𝐬) = ∑_{j∈V} U_j(Y_j(𝐬_{I(j)})).$$
 
-The utility function affects the objectives as discussed on the [Decision Model](#Decision Model) page. We can choose the utility function such that the path utility function either returns:
+The utility function affects the objectives as discussed on the [Decision Model](#Decision-Model) page. We can choose the utility function such that the path utility function either returns:
 
 * a numerical value, which leads to a mixed-integer linear programming (MILP) formulation or
 * a linear function with real and integer-valued variables, which leads to a mixed-integer quadratic programming (MIQP) formulation.
@@ -152,7 +152,7 @@ Formally, the path $𝐬$ is **ineffective** if and only if $𝐬_A∈𝐒_A^′
 
 $$𝐒^∗=\{𝐬∈𝐒∣𝐬_{A}∉𝐒_{A}^′\}⊆𝐒.$$
 
-The [Decision Model](#Decision Model) size depends on the number of effective paths, rather than the number of paths or size of the influence diagram directly.
+The [Decision Model](#Decision-Model) size depends on the number of effective paths, rather than the number of paths or size of the influence diagram directly.
 
 In Decision Programming, one can declare certain subpaths to be ineffective using the *fixed path* and *forbidden paths* sets.
 
@@ -196,7 +196,7 @@ If there are no other ineffective subpaths, we have
 
 $$𝐒^∗ = 𝐒(X).$$
 
-Notice that, the number of active paths affects the size of the [Decision Model](#Decision Model) because it depends on the number of effective paths.
+Notice that, the number of active paths affects the size of the [Decision Model](#Decision-Model) because it depends on the number of effective paths.
 
 
 ## Compatible Paths