Proposal: move all probabilities in edges

README.md

@@ -1,2 +1,2 @@
-# StochasticProgram.jl
+# StochOptInterface.jl
 A generic package to write stochastic programs easily

src/StochasticProgram.jl → src/StochOptInterface.jl

@@ -3,12 +3,12 @@
 # An interface for Stochastic Optimization in Julia
 ################################################################################
 
-module StochasticProgram
+module StochOptInterface
 
 using LightGraphs
 
 
-export AbstractStochasticProgram, stochasticprogram
+export AbstractStochasticProgram, stochasticprogram, AbstractStochasticProgramSolver
 
 
 """
@@ -35,8 +35,10 @@ Write the StochasticProgram `sp` inside `filename`.
 function write end
 
 
-include("graph.jl")
 include("node.jl")
+include("edges.jl")
+include("graph.jl")
+include("valuefunction.jl")
 include("solvers.jl")
 
 end

src/edges.jl

@@ -0,0 +1,59 @@
+# Edges utilities
+# Edge stores
+# - an id corresponding to index in graph
+# - a noise, or a collection of noise (for stagewise noise)
+# - an optimization problem (implemented with JuMP or MOI)
+
+abstract type AbstractEdge end
+
+"""
+    sync!(edge::AbstractEdge)
+
+Synchronize state in `edge` with parent node.
+"""
+function sync! end
+
+
+"""
+    set!(edge::AbstractEdge, x)
+
+Set current state in `edge` problem.
+
+    set!(edge::AbstractEdge, noise)
+
+Set current noise in `edge` problem.
+"""
+function set! end
+
+
+"""
+    rand(edge::AbstractEdge)
+
+Draw a random realization of edge's noise (in the case that `edge` stores a
+collection of noises).
+"""
+function rand end
+
+
+"""
+    build!(edge::AbstractEdge)
+
+Build optimization model in `edge` with model stored in AbstractNode parent.
+"""
+function build! end
+
+
+"""
+    reload!(edge:AbstractEdge)
+
+Reload optimization model in `edge`
+"""
+function reload! end
+
+
+"""
+    size(edges)
+
+Return number of noises in `edges`.
+"""
+function size end

src/graph.jl

@@ -1,4 +1,4 @@
-# Graph utilities
+# Graph and edges utilities
 
 """
     getmaster(sp::AbstractStochasticProgram)
@@ -17,11 +17,11 @@ function probability end
 
 
 """
-    setchildx!(sp::AbstractStochasticProgram, node, child, sol)
+    setchildstate!(sp::AbstractStochasticProgram, node::AbstractNode, child::AbstractNode, sol::AbstractSolution)
 
 Sets the parent solution of `child` as `sol`, the solution obtained at `node`.
 """
-function setchildx! end
+function setchildstate! end
 
 
 """
@@ -30,3 +30,11 @@ function setchildx! end
 Sets the probability to take the edge `edge` in the stochastic problem `sp` to `probability`.
 """
 function setprobability! end
+
+
+"""
+    edges(sp::AbstractStochasticProgram, node::AbstractNode)
+
+Returns iterable of outgoing edges in `node`.
+"""
+function edges end

src/node.jl

@@ -1,13 +1,19 @@
 # Nodes utilities
+# Node stores:
+# - an index in the graph, and a stage
+# - an optimization model (with objective, dynamics and constraints)
+# - a value function
+# - a list of outgoing edges
 
 
 abstract type AbstractNode end
 
 
 """
-    solve!(sp::AbstractStochasticProgram, node)
+    solve!(node::AbstractNode, edge)
 
-Solves the program at node `node` in `sp` and returns the solution.
+Solves the problem starting at `node` and stored inside `edge`, and
+returns a AbstractSolution object.
 """
 function solve! end
 
@@ -37,11 +43,19 @@ function statedim end
 
 
 """
-    set(node::AbstractNode, state::AbstractState)
+    set!(node::AbstractNode, state::AbstractState)
 
-Set state inside `node`.
+Set state inside `node` and update out-going edges.
+
+    set!(node::AbstractNode, vf::AbstractValueFunction)
+
+Set value function inside `node`.
+
+    set!(node::AbstractNode, cut::Cuts)
+
+Add new cuts inside `node` and udpate in-going edges.
 """
-function set end
+function set! end
 
 
 """
@@ -53,9 +67,9 @@ numberofpaths(sp::AbstractStochasticProgram, len) = numberofpaths(sp, getmaster(
 
 
 """
-    sample(node::AbstractNode, npaths)
+    sample(node::AbstractNode, npaths::Int)
 
-Sample `npaths` path starting from `node`.
+Sample `npaths` edges outgoing `node` and return a list.
 """
 function sample end
 

src/solution.jl

@@ -0,0 +1,57 @@
+abstract type AbstractSolution end
+
+"""
+    feasibility_cut(sol::AbstractSolution)
+
+Returns the tuple `(a, α)` representing the feasibility cut ``⟨a, x⟩ ≧ α`` certified by this solution.
+"""
+function feasibility_cut end
+
+"""
+    optimality_cut(sol::AbstractSolution)
+
+Returns the tuple `(a, α)` representing the optimality cut ``⟨a, x⟩ + θ ≧ α`` certified by this solution.
+"""
+function optimality_cut end
+
+"""
+    getstatus(sol::AbstractSolution)
+
+Returns the status of the solution `sol`.
+"""
+function getstatus end
+
+"""
+    getobjectivevalue(sol::AbstractSolution)
+
+Returns the objective value of the solution `sol` *including* the part of the objective depending on `θ`.
+"""
+function getobjectivevalue end
+
+"""
+    getstateobjectivevalue(sol::AbstractSolution)
+
+Returns the objective value of the solution `sol` *excluding* the part of the objective depending on `θ`.
+"""
+function getstateobjectivevalue end
+
+
+"""
+    getstatevalue(sol::AbstractSolution)
+
+Returns the value of the state of solution `sol`.
+"""
+function getstatevalue end
+
+"""
+    getbellmanvalue(sp::AbstractStochasticProgram, node, child, sol::AbstractSolution)
+
+Returns the value of the θ in the solution `sol` of node `node` for its child `child`.
+This assumes that `node` is using `MultiCutGenerator`.
+
+    getbellmanvalue(sp::AbstractStochasticProgram, node, sol::AbstractSolution)
+
+Returns the value of the θ in the solution `sol` of node `node`.
+This assumes that `node` is using `AvgCutGenerator`.
+"""
+function getbellmanvalue end

src/solvers.jl

@@ -1,3 +1,3 @@
 # Solver utilities
 
-abstract type AbstractStochasticProgrammingSolver end
+abstract type AbstractStochasticProgramSolver end

src/valuefunction.jl

@@ -0,0 +1,11 @@
+# Abstraction to define value functions
+
+abstract type AbstractValueFunction end
+
+
+"""
+    getvalue(vf::AbstractValueFunction, x)
+
+Get cost-to-go at point `x`.
+"""
+function getvalue end