Merge pull request #129 from JuliaOpt/dev-nightly

Dev nightly

Author: leclere

doc/conf.py

@@ -31,7 +31,7 @@
 # ones.
 extensions = [
     'sphinx.ext.coverage',
-    'sphinx.ext.mathjax', 
+    'sphinx.ext.mathjax',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -56,9 +56,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = '0.2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/index.rst

@@ -7,13 +7,18 @@
 StochDynamicProgramming
 =======================
 
-This package implements the Stochastic Dual Dynamic Programming (SDDP) algorithm with Julia. It relies upon MathProgBase_ and JuMP_.
+This package implements the Stochastic Dual Dynamic Programming (SDDP)
+algorithm with Julia. It relies upon MathProgBase_ and JuMP_, and is compatible
+with both Julia v0.4 and v0.5.
 
 A complete overview of this algorithm could be found here_.
 
-At the moment the plan is to create a type such that :
+Description of SDDP
+^^^^^^^^^^^^^^^^^^^
 
-- you can fix linear time :math:`t` cost function (then convex piecewise linear)
+At the moment:
+
+- you can fix linear or quadratic time :math:`t` cost function (then convex piecewise linear)
 - you can fix linear dynamic (with a physical state :math:`x` and a control :math:`u`)
 - the scenarios are created by assuming that the noise :math:`\xi_t` is independent in time, each given by a table (value, probability)
 
@@ -27,19 +32,34 @@ Then it is standard SDDP :
 
 Once solved the SDDP model should be able to :
 
-- give the lower bound on the cost
+- give the lower bound on the cost and its evolution along iterations
 - simulate trajectories to evaluate expected cost
 - give the optimal control given current time state and noise
 
 
+Supported features
+^^^^^^^^^^^^^^^^^^
+
+.. .. table:
+.. ======  =========== ===============
+.. Solver  Is working? Quadratic costs
+.. ======  =========== ===============
+.. Linear Cost     Yes         No
+.. Quadratic Cost   Yes         Yes
+.. Integer controls
+.. Quadratic regularization
+.. Cuts pruning
+
+
+Ongoing developments
+^^^^^^^^^^^^^^^^^^^^
+
 We have a lot of ideas to implement further :
 
 - spatial construction (i.e : defining stock one by one and then their interactions)
 - noise as AR (eventually with fitting on historic datas)
 - convex solvers
 - refined stopping rules
-- cut pruning
-- paralellization
 
 
 
@@ -49,7 +69,9 @@ Contents:
 .. toctree::
    install
    quickstart
+   sddp_api
    tutorial
+   quickstart_sdp
    install_windows
 
 .. _MathProgBase: http://mathprogbasejl.readthedocs.org/en/latest/

doc/install.rst

@@ -32,18 +32,18 @@ Refer to the documentation of JuMP_ to get another solver and interface it with
 The following solvers have been tested:
 
 .. table:
-======  ===========
-Solver  Is working?
-======  ===========
-Clp     Yes
-CPLEX   Yes
-Gurobi  Yes
-GLPK    **No**
-======  ===========
+======  =========== ===============
+Solver  Is working? Quadratic costs
+======  =========== ===============
+Clp     Yes         No
+CPLEX   Yes         Yes
+Gurobi  Yes         Yes
+GLPK    **No**      **No**
+======  =========== ===============
 
 Run Unit-Tests
 --------------
-To run unit-tests::
+To run unit-tests (depend upon `FactCheck.jl`)::
 
    $ julia test/runtests.jl
 

doc/quickstart.rst

@@ -4,29 +4,33 @@
 SDDP: Step-by-step example
 ====================
 
-This page gives a short introduction to the interface of this package. It explains the resolution with SDDP of a classical example: the management of a dam over one year with random inflow.
+This page gives a short introduction to the interface of this package. It
+explains the resolution with SDDP of a classical example: the management of a
+dam over one year with random inflow.
 
 Use case
 ========
-In the following, :math:`x_t` will denote the state and :math:`u_t` the control at time :math:`t`.
-We will consider a dam, whose dynamic is:
+In the following, :math:`x_t` denotes the state and :math:`u_t` the control at time :math:`t`.
+We consider a dam, whose dynamic is:
 
 .. math::
    x_{t+1} = x_t - u_t + w_t
 
-At time :math:`t`, we have a random inflow :math:`w_t` and we choose to turbine a quantity :math:`u_t` of water.
+At time :math:`t`, we have a random inflow :math:`w_t` and we choose to turbine
+a quantity :math:`u_t` of water.
 
-The turbined water is used to produce electricity, which is being sold at a price :math:`c_t`. At time :math:`t` we gain:
+The turbined water is used to produce electricity, which is being sold at a
+price :math:`c_t`. At time :math:`t` we gain:
 
 .. math::
     C(x_t, u_t, w_t) = c_t \times u_t
 
 We want to minimize the following criterion:
 
 .. math::
-    J = \underset{x, u}{\min} \sum_{t=0}^{T-1} C(x_t, u_t, w_t)
+    J = \underset{x, u}{\min} \mathbb{E} \;\left[ \sum_{t=0}^{T-1} C(x_t, u_t, w_t) \right]
 
-We will assume that both states and controls are bounded:
+We assume that both states and controls are bounded:
 
 .. math::
     x_t \in [0, 100], \qquad u_t \in [0, 7]
@@ -35,7 +39,8 @@ We will assume that both states and controls are bounded:
 Problem definition in Julia
 ===========================
 
-We will consider 52 time steps as we want to find optimal value functions for one year::
+We consider 52 time steps as we want to find optimal value functions every week
+during one year::
 
     N_STAGES = 52
 
@@ -44,7 +49,7 @@ and we consider the following initial position::
 
     X0 = [50]
 
-Note that X0 is a vector.
+Note that `X0` is a vector.
 
 Dynamic
 ^^^^^^^
@@ -59,7 +64,8 @@ We write the dynamic (which return a vector)::
 Cost
 ^^^^
 
-we store evolution of costs :math:`c_t` in an array `COSTS`, and we define the cost function (which return a float)::
+We store evolution of costs :math:`c_t` in an array `COSTS`, and we define
+the cost function (which return a float)::
 
     function cost_t(t, x, u, w)
         return COSTS[t] * u[1]
@@ -68,7 +74,7 @@ we store evolution of costs :math:`c_t` in an array `COSTS`, and we define the c
 Noises
 ^^^^^^
 
-Noises are defined in an array of Noiselaw. This type defines a discrete probability.
+Noises are defined in an array of `Noiselaw`. This type defines a discrete probability.
 
 
 For instance, if we want to define a uniform probability with size :math:`N= 10`, such that:
@@ -80,7 +86,7 @@ we write::
 
     N = 10
     proba = 1/N*ones(N) # uniform probabilities
-    xi_support = collect(linspace(1,N,N))
+    xi_support = collect(linspace(1, N, N))
     xi_law = NoiseLaw(xi_support, proba)
 
 
@@ -92,7 +98,7 @@ Thus, we could define a different probability laws for each time :math:`t`. Here
 Bounds
 ^^^^^^
 
-We add bounds over the state and the control::
+Both state and control are bounded:
 
     s_bounds = [(0, 100)]
     u_bounds = [(0, 7)]
@@ -103,7 +109,7 @@ Problem definition
 
 As our problem is purely linear, we instantiate::
 
-    spmodel = LinearDynamicLinearCostSPmodel(N_STAGES,u_bounds,X0,cost_t,dynamic,xi_laws)
+    spmodel = LinearSPModel(N_STAGES, u_bounds, X0, cost_t, dynamic, xi_laws)
 
 We add the state bounds to the model afterward::
 
@@ -119,42 +125,52 @@ First, we need to use a LP solver::
     using Clp
     SOLVER = ClpSolver()
 
-Clp is automatically installed during package installation. To install different solvers on your machine, refer to the JuMP_ documentation.
+Clp is automatically installed during packages' installation. To install
+different solvers on your machine, refer to the JuMP_ documentation.
 
-Once the solver installed, we define SDDP algorithm parameters::
+Once the solver is installed, we define SDDP parameters::
 
     forwardpassnumber = 2 # number of forward pass
-    sensibility = 0. # admissible gap between upper and lower bound
+    gap = 0. # admissible gap between upper and lower bound
     max_iter = 20  # maximum number of iterations
 
-    paramSDDP = SDDPparameters(SOLVER, forwardpassnumber, sensibility, max_iter)
+    paramSDDP = SDDPparameters(SOLVER,
+                               passnumber=forwardpassnumber,
+                               gap=gap,
+                               max_iterations=max_iter)
 
 
 Now, we solve the problem by computing Bellman values::
 
-    V, pbs = solve_SDDP(spmodel, paramSDDP, 10) # display information every 10 iterations
+    V, pbs, stats = solve_SDDP(spmodel, paramSDDP, 10) # display information every 10 iterations
 
-:code:`V` is an array storing the value functions, and :code:`pbs` a vector of JuMP.Model storing each value functions as a linear problem.
+:code:`V` is an array storing the value functions, and :code:`pbs` a vector of
+JuMP.Model storing each value functions as a linear problem.
+:code:`stats` is an object which stores a few informations about the convergence
+of SDDP (execution time, evolution of upper and lower bounds, number of calls to
+solver, etc.).
 
-We have an exact lower bound given by :code:`V` with the function::
+The exact lower bound is given by the function::
 
     lb_sddp = StochDynamicProgramming.get_lower_bound(spmodel, paramSDDP, V)
 
 
 Find optimal controls
 =====================
 
-Once Bellman functions are computed, we can control our system over assessments scenarios, without assuming knowledge of the future.
+Once Bellman functions are computed, we can control our system over
+assessments scenarios, without assuming knowledge of the future.
 
 We build 1000 scenarios according to the laws stored in :code:`xi_laws`::
 
-    scenarios = StochDynamicProgramming.simulate_scenarios(xi_laws,1000)
+    scenarios = StochDynamicProgramming.simulate_scenarios(xi_laws, 1000)
 
 We compute 1000 simulations of the system over these scenarios::
 
-    costsddp, stocks = forward_simulations(spmodel, paramSDDP, V, pbs, scenarios)
+    costsddp, stocks = forward_simulations(spmodel, paramSDDP, pbs, scenarios)
 
-:code:`costsddp` returns the costs for each scenario, and :code:`stocks` the evolution of each stock along time, for each scenario.
+:code:`costsddp` returns the costs for each scenario, and :code:`stocks`
+the evolution of stocks along time, for each scenario.
 
 .. _JuMP: http://jump.readthedocs.io/en/latest/installation.html#coin-or-clp-and-cbc