Merge pull request #104 from lanl-ansi/documentation

DOC: Update quick start documentation to be accurate. FIX: Explicitly separate design pipes from non-design pipes.

Author: tasseff

LICENSE.md

@@ -1,19 +1,19 @@
-Copyright (c) 2016, Triad National Security, LLC.
-
-All rights reserved.
-
-This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. The U.S. Government has rights to use, reproduce, and distribute this software. NEITHER THE GOVERNMENT NOR TRIAD NATIONAL SECURITY, LLC MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY FOR THE USE OF THIS SOFTWARE. If software is modified to produce derivative works, such modified software should be clearly marked, so as not to confuse it with the version available from LANL.
-
-All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.
-
-Additionally, redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-3. Neither the name of Triad National Security, LLC, Los Alamos National Laboratory, LANL, the U.S. Government, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
- 
-THIS SOFTWARE IS PROVIDED BY TRIAD NATIONAL SECURITY, LLC AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TRIAD NATIONAL SECURITY, LLC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- 
-LICENSEE AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE U.S. GOVERNMENT AND THE UNITED STATES GOVERNMENT'S CONTRACTORS AND SUBCONTRACTORS, AND SHALL INDEMNIFY AND HOLD HARMLESS THE U.S. GOVERNMENT AND THE UNITED STATES GOVERNMENT'S CONTRACTORS AND SUBCONTRACTORS FOR ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES, OR LOSSES THAT MAY ARISE FROM RECIPIENT'S USE OF THE NUFLOOD SOFTWARE OR PROVIDED DOCUMENTATION, INCLUDING ANY LIABILITIES OR DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, THE USE THEREOF.
+Copyright (c) 2016, Triad National Security, LLC.
+
+All rights reserved.
+
+This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. The U.S. Government has rights to use, reproduce, and distribute this software. NEITHER THE GOVERNMENT NOR TRIAD NATIONAL SECURITY, LLC MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY FOR THE USE OF THIS SOFTWARE. If software is modified to produce derivative works, such modified software should be clearly marked, so as not to confuse it with the version available from LANL.
+
+All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.
+
+Additionally, redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of Triad National Security, LLC, Los Alamos National Laboratory, LANL, the U.S. Government, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+ 
+THIS SOFTWARE IS PROVIDED BY TRIAD NATIONAL SECURITY, LLC AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TRIAD NATIONAL SECURITY, LLC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ 
+LICENSEE AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE U.S. GOVERNMENT AND THE UNITED STATES GOVERNMENT'S CONTRACTORS AND SUBCONTRACTORS, AND SHALL INDEMNIFY AND HOLD HARMLESS THE U.S. GOVERNMENT AND THE UNITED STATES GOVERNMENT'S CONTRACTORS AND SUBCONTRACTORS FOR ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES, OR LOSSES THAT MAY ARISE FROM RECIPIENT'S USE OF THE WATERMODELS SOFTWARE OR PROVIDED DOCUMENTATION, INCLUDING ANY LIABILITIES OR DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, THE USE THEREOF.

README.md

@@ -9,9 +9,9 @@ The code is engineered to decouple problem specifications (e.g., network design,
 This decoupling enables the definition of a wide variety of optimization formulations and their comparison on common problem specifications.
 
 **Core Problem Specifications**
-* Water Flow (wf) - obtain feasible flows for a fixed network
-* Optimal Water Flow (owf) - minimize the cost required for network operation
-* Network Design (des) - minimize the cost of network design
+* Water Flow (`wf` and `mn_wf`) - obtain feasible flows for a network
+* Optimal Water Flow (`owf` and `mn_owf`) - minimize the cost of network operation
+* Network Design (`des`) - minimize the cost of network design
 
 **Core Network Formulations**
 * NLP - nonconvex nonlinear program
@@ -20,7 +20,8 @@ This decoupling enables the definition of a wide variety of optimization formula
 * MILP-R - relaxation-based mixed-integer linear program
 
 ## Documentation
-The package [documentation](https://lanl-ansi.github.io/WaterModels.jl/latest/) includes a [quick start guide](https://lanl-ansi.github.io/WaterModels.jl/latest/quickguide).
+The package [documentation](https://lanl-ansi.github.io/WaterModels.jl/latest) includes a [quick start guide](https://lanl-ansi.github.io/WaterModels.jl/latest/quickguide).
+Be advised that aside from the quick start guide, documentation is under development and may currently be inaccurate.
 
 ## Development
 Community-driven development and enhancement of WaterModels is welcomed and encouraged.
@@ -38,6 +39,7 @@ The primary developer is [Byron Tasseff](https://github.com/tasseff) with suppor
 - [Russell Bent](https://github.com/rb004f), Los Alamos National Laboratory
 - [Carleton Coffrin](https://github.com/ccoffrin), Los Alamos National Laboratory
 - Donatella Pasqualini, Los Alamos National Laboratory
+- [Jonathan Stickel](https://github.com/jjstickel), National Renewable Energy Laboratory
 
 ## License
 This code is provided under a [modified BSD license](https://github.com/lanl-ansi/WaterModels.jl/blob/master/LICENSE.md) as part of the Multi-Infrastructure Control and Optimization Toolkit (MICOT), LA-CC-13-108.

docs/make.jl

@@ -2,9 +2,9 @@ using Documenter, WaterModels
 
 makedocs(
     modules = [WaterModels],
-    format = Documenter.HTML(analytics="UA-367975-10", mathengine=Documenter.MathJax()),
+    format = Documenter.HTML(analytics="UA-367975-10", mathengine=Documenter.MathJax(), prettyurls=false),
     sitename = "WaterModels",
-    authors = "Byron Tasseff, Russell Bent, Carleton Coffrin, Donatella Pasqualini, Clayton Barrows, Sai Krishna Kanth Hari, and contributors.",
+    authors = "Byron Tasseff and contributors",
     pages = [
         "Home" => "index.md",
         "Manual" => [
@@ -26,7 +26,7 @@ makedocs(
             "File I/O" => "parser.md"
         ],
         "Developer" => "developer.md",
-        "Experiment Results" => "experiment-results.md"
+        "Benchmarks" => "benchmarks.md"
     ]
 )
 

docs/src/benchmarks.md

@@ -0,0 +1 @@
+# WaterModels Benchmarks

docs/src/experiment-results.md

@@ -5,10 +5,10 @@ CurrentModule = WaterModels
 ```
 
 ## Overview
-WaterModels.jl is a Julia/JuMP package for steady state water network optimization.
-It is designed to enable computational evaluation of historical and emerging water network formulations and algorithms using a common platform.
-The code is engineered to decouple [Problem Specifications](@ref) (e.g., water flow, optimal water flow, network design) from [Network Formulations](@ref) (e.g., mixed-integer linear, mixed-integer nonlinear).
-This decoupling enables the definition of a wide variety of water network optimization formulations and their comparison on common problem specifications.
+WaterModels.jl is a Julia/JuMP package for steady state potable water distribution network optimization.
+It is designed to enable the computational evaluation of historical and emerging water network optimization formulations and algorithms using a common platform.
+The code is specifically engineered to decouple [Problem Specifications](@ref) (e.g., water flow, optimal water flow, network design) from [Network Formulations](@ref) (e.g., mixed-integer linear, mixed-integer nonlinear).
+This decoupling enables the definition of a wide variety of water network optimization formulations and their comparison across several common problem specifications.
 
 ## Installation
 The latest stable release of WaterModels can be installed using the Julia package manager with
@@ -21,26 +21,40 @@ For the current development version, install the package using
 ] add WaterModels#master
 ```
 
-Test that the package works by executing
+Finally, test that the package works as expected by executing
 ```julia
 ] test WaterModels
 ```
 
 ## Usage at a Glance
 At least one optimization solver is required to run WaterModels.
 The solver selected typically depends on the type of problem formulation being employed.
-As an example, to solve a mixed-integer linear programming (MILP) formulation of the water flow feasibility problem, the open-source mixed-integer programming solver [CBC](https://github.com/coin-or/Cbc) can be used.
+As an example, to solve a mixed-integer linear programming (MILP) formulation of the feasible water flow (`wf`) problem, the open-source mixed-integer programming solver [CBC](https://github.com/coin-or/Cbc) can be used.
 Installation of the JuMP interface to CBC can be performed via the Julia package manager, i.e.,
 
 ```julia
 ] add Cbc
 ```
 
-Then, as one example, an approximation of water flow physics for the well-known [shamir network](https://github.com/lanl-ansi/WaterModels.jl/blob/master/test/data/epanet/shamir.inp), using ten breakpoints to model each potential (or head) loss curve, can be obtained by executing
+Then, as one example, a piecewise-linear approximation of the physics for the well-known [Shamir (two-loop) network](https://github.com/lanl-ansi/WaterModels.jl/blob/master/examples/data/epanet/shamir.inp), using ten breakpoints to model each pipe's Hazen-Williams head loss curve, can be solved to feasibility using
 
 ```julia
-using Cbc
-using WaterModels
-ext = Dict(:pipe_breakpoints=>10)
-result = run_wf("shamir.inp", MILPWaterModel, Cbc.Optimizer, ext=ext)
+using WaterModels, Cbc
+ext = Dict(:pipe_breakpoints=>10) # Defines additional parameters used in model construction.
+result = run_wf("examples/data/epanet/shamir.inp", MILPWaterModel, Cbc.Optimizer; ext=ext)
+```
+
+After solving the problem, its results can then be analyzed, e.g.,
+```julia
+# The termination status of the optimization solver.
+result["termination_status"]
+
+# The flow along pipe 4, in cubic meters per second.
+result["solution"]["pipe"]["4"]["q"]
+
+# The total hydraulic head at junction (node) 2, in meters.
+result["solution"]["node"]["2"]["h"]
+
+# The pressure head at junction (node) 2, in meters.
+result["solution"]["node"]["2"]["p"]
 ```