Merge pull request #43 from lanl-ansi/im-updates

Updates for GasModels v0.7

.travis.yml

@@ -4,15 +4,15 @@ os:
   - osx
 julia:
   - 1.0
-  - 1.4
+  - 1.5
   - nightly
 codecov: true
 jobs:
   allow_failures:
     - julia: nightly
   include:
     - stage: "Documentation"
-      julia: 1.4
+      julia: 1.5
       os: linux
       script:
         - julia --project=docs/ -e 'using Pkg; Pkg.instantiate(); Pkg.develop(PackageSpec(path=pwd()))'

README.md

@@ -1,56 +1,94 @@
 # GasPowerModels.jl 
-
-Dev:
 [![Build Status](https://travis-ci.org/lanl-ansi/GasPowerModels.jl.svg?branch=master)](https://travis-ci.org/lanl-ansi/GasPowerModels.jl)
 [![codecov](https://codecov.io/gh/lanl-ansi/GasPowerModels.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/lanl-ansi/GasPowerModels.jl)
-[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://lanl-ansi.github.io/GasPowerModels.jl/latest)
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://lanl-ansi.github.io/GasPowerModels.jl/stable)
+[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://lanl-ansi.github.io/GasPowerModels.jl/dev)
 
-GasPowerModels.jl is a Julia/JuMP package for Simultaneous Steady-State Natural Gas and Electric Power Network Optimization.
-It is designed to enable computational evaluation of emerging Gas-Grid network formulations and algorithms in a common platform.
-The code is engineered to decouple problem specifications (e.g. Flow, Expansion planning, ...) from the gas and power network formulations (e.g. MINLP, MISOCP, ...) defined in PowerModels.jl and GasModels.jl
-This enables the definition of a wide variety of formulations and their comparison on common problem specifications.
+GasPowerModels.jl is a Julia/JuMP package for the joint optimization of steady state natural gas and power transmission networks.
+It provides utilities for modeling problems that combine elements of natural gas and electric power systems.
+It is designed to enable the computational evaluation of historical and emerging gas-power network optimization formulations and algorithms using a common platform.
+The code is engineered to decouple problem specifications (e.g., gas-power flow, network expansion planning) from network formulations (e.g., mixed-integer linear, mixed-integer nonlinear).
+This decoupling enables the definition of a variety of optimization formulations and their comparison on common problem specifications.
 
 **Core Problem Specifications**
-* Flow (f)
-* Expansion Planning (ne)
+* Gas-Power Flow (`gpf`)
+* Optimal Power Flow (`opf`)
+* Network Expansion Planning (`ne`)
+* Optimal Power Flow with Network Expansion Planning (`opf_ne`)
 
 **Core Network Formulations**
-* MINLP 
-* MISOCP
+* Mixed-integer nonconvex nonlinear program (`MINLP`)
+* Mixed-integer second-order cone program (`MISOCP`)
 
-## Installation
+## Documentation
+The package [documentation](https://lanl-ansi.github.io/GasPowerModels.jl/stable/) includes a [quick start guide](https://lanl-ansi.github.io/GasPowerModels.jl/stable/quickguide).
 
-GasPowerModels.jl should be installed using the command
+## Installation
+The latest stable release of GasPowerModels can be installed using the Julia package manager with
+```julia
+] add GasPowerModels
+```
 
-`add GasPowerModels`
+For the current development version, install the package using
+```julia
+] add GasPowerModels#master
+```
 
-At least one solver is required for running GasPowerModels.  Commercial or psuedo-commerical solvers seem to handle these problems much better than some of the open source alternatives.  Gurobi and Cplex perform well on the MISOCP model, and SCIP handles the MINLP model reasonably well.
+Finally, test that the package works as expected by executing
+```julia
+] test GasPowerModels
+```
 
-## Basic Usage
+## Usage at a Glance
+At least one optimization solver is required to run GasPowerModels.
+The solver selected typically depends on the type of problem formulation being employed.
+As an example, the mixed-integer nonlinear programming solver [Juniper](https://github.com/lanl-ansi/Juniper.jl) can be used for testing any of the problem formulations considered in this package.
+Juniper itself depends on the installation of a nonlinear programming solver (e.g., [Ipopt](https://github.com/jump-dev/Ipopt.jl)) and a mixed-integer linear programming solver (e.g., [CBC](https://github.com/jump-dev/Cbc.jl)).
+Installation of the JuMP interfaces to Juniper, Ipopt, and Cbc can be performed via the Julia package manager, i.e.,
 
-Once GasPowerModels is installed, a solver is installed, and a network data file  has been acquired, a Gas-Grid Flow can be executed with,
+```julia
+] add JuMP Juniper Ipopt Cbc
 ```
+
+After installation of the required solvers, an example gas-power flow feasibility problem (whose file inputs can be found in the `examples` directory within the [GasPowerModels repository](https://github.com/lanl-ansi/GasPowerModels.jl)) can be solved via
+```julia
+using JuMP, Juniper, Ipopt, Cbc
 using GasPowerModels
-using <solver_package>
 
-run_gpf("power.m", "gas.m", <>PowerModel, <>GasModel, <>Solver())
-```
+# Set up the optimization solvers.
+ipopt = JuMP.optimizer_with_attributes(Ipopt.Optimizer, "print_level"=>0, "sb"=>"yes")
+cbc = JuMP.optimizer_with_attributes(Cbc.Optimizer, "logLevel"=>0)
+juniper = JuMP.optimizer_with_attributes(Juniper.Optimizer, "nl_solver"=>ipopt, "mip_solver"=>cbc)
 
-Similarly, an expansion solver can be executed with,
-```
-run_ne("power.m", "gas.m", <>PowerModel, <>GasModel, <>Solver())
-```
+# Specify paths to the gas and power network files.
+g_file = "examples/data/matgas/belgian.m" # Gas network.
+p_file = "examples/data/matpower/case14.m" # Power network.
 
-where <>GasModel is the implementation of the mathematical program of the Gas equations you plan to use (i.e. MINLPGasModel) and <>Solver is the JuMP solver you want to use to solve the optimization problem (i.e. IpoptSolver).
+# Specify the gas and power formulation types separately.
+g_type, p_type = MISOCPGasModel, SOCWRPowerModel
 
+# Solve the gas-power flow feasibility problem.
+result = run_gpf(g_file, p_file, g_type, p_type, juniper;
+    gm_solution_processors=[GasPowerModels._GM.sol_psqr_to_p!],
+    pm_solution_processors=[GasPowerModels._PM.sol_data_model!])
+```
 
-## Acknowledgments
+After solving the problem, results can then be analyzed, e.g.,
+```julia
+# The termination status of the optimization solver.
+result["termination_status"]
 
-The primary developers are Russell Bent and Kaarthik Sundar. Significant contributions on the technical model were made by Conrado Borraz-Sanchez, Pascal van Hentenryck, and Seth Blumsack.
+# Generator 1's real power generation.
+result["solution"]["gen"]["1"]["pg"]
 
-Special thanks to Miles Lubin and Carleton Coffrin for their assistance in integrating with Julia/JuMP and PowerModels.jl.
+# Junction 1's pressure.
+result["solution"]["junction"]["1"]["p"]
+```
 
+## Acknowledgments
+The primary developers are Russell Bent and Kaarthik Sundar.
+Significant contributions on the technical model were made by Conrado Borraz-Sanchez, Pascal van Hentenryck, and Seth Blumsack.
+Special thanks to Miles Lubin and Carleton Coffrin for their assistance in integrating with Julia/JuMP and PowerModels.jl.
 
 ## License
-
 This code is provided under a BSD license as part of the Multi-Infrastructure Control and Optimization Toolkit (MICOT) project, LA-CC-13-108.

docs/README.md

@@ -1,21 +1,21 @@
 # Building the Documentation for GasPowerModels.jl
 
 ## Installation
-We rely on [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). To install it, run the following command in a julia session:
-
+We rely on [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl).
+To install it, run the following command in a Julia session:
 ```julia
 Pkg.add("Documenter")
 ```
 
 ## Building the Docs
-To preview the html output of the documents, run the following command:
-
+To preview the HTML output of the documents, run the following command:
 ```julia
 julia --color=yes make.jl
 ```
 
 You can then view the documents in `build/index.html`.
 
-**Warning**: Do not `git commit` the contents of build (or any other content generated by Documenter) to your repository's master branch. This helps to avoid including unnecessary changes for anyone reviewing commits that happen to include documentation changes.
+**Warning**: Do not `git commit` the contents of build (or any other content generated by Documenter) to your repository's master branch.
+This helps to avoid including unnecessary changes for anyone reviewing commits that happen to include documentation changes.
 
-For further details, please read the [documentation for Documenter.jl](https://juliadocs.github.io/Documenter.jl/stable/).
+For further details, please read the [documentation for Documenter.jl](https://juliadocs.github.io/Documenter.jl/stable/).

docs/src/constraints.md

@@ -1,5 +1,4 @@
 # Constraints
-
 ```@autodocs
 Modules = [GasPowerModels]
 Pages   = ["core/constraint_template.jl"]

docs/src/developer.md

@@ -1,3 +1 @@
 # Developer Documentation
-
-Nothing yet.

docs/src/formulations.md

@@ -1,4 +1,2 @@
 # Network Formulations
-
-The network formulations for coupled gas grid modeling directly use the formulations defined in GasModels.jl and PowerModels.jl
-
+The network formulations for joint gas-power modeling use the formulations defined in GasModels.jl and PowerModels.jl.

docs/src/index.md

@@ -5,33 +5,70 @@ CurrentModule = GasPowerModels
 ```
 
 ## Overview
-
-GasPowerModels.jl is a Julia/JuMP package for Steady-State Gas Network Optimization. It provides utilities for modeling problems that combine elements of natural gas and electric power systems. It is designed to enable computational evaluation of emerging gas and power network formulations and algorithms in a common platform.
-
-The code is engineered to decouple [Problem Specifications](@ref) (e.g. Flow, Expansion Planning, ...) from [Network Formulations](@ref) (e.g. MINLP, MISOC-relaxation, ...). This enables the definition of a wide variety of coupled network formulations and their comparison on common problem specifications.
+GasPowerModels.jl is a Julia/JuMP package for the joint optimization of steady state natural gas and power transmission networks.
+It provides utilities for modeling problems that combine elements of natural gas and electric power systems.
+It is designed to enable the computational evaluation of historical and emerging gas-power network optimization formulations and algorithms using a common platform.
+The code is engineered to decouple [Problem Specifications](@ref) (e.g., gas-power flow, network expansion planning) from [Network Formulations](@ref) (e.g., mixed-integer linear, mixed-integer nonlinear).
+This decoupling enables the definition of a variety of optimization formulations and their comparison on common problem specifications.
 
 ## Installation
-
-The latest stable release of GasPowerModels will be installed using the Julia package manager with
-
+The latest stable release of GasPowerModels can be installed using the Julia package manager with
 ```julia
-Pkg.add("GasPowerModels")
+] add GasPowerModels
 ```
 
-For the current development version, "checkout" this package with
+For the current development version, install the package using
+```julia
+] add GasPowerModels#master
+```
 
+Finally, test that the package works as expected by executing
 ```julia
-Pkg.checkout("GasPowerModels")
+] test GasPowerModels
 ```
 
-At least one solver is required for running GasModels.  The open-source solver Pavito is recommended and can be used to solve a wide variety of the problems and network formulations provided in GasModels.  The Pavito solver can be installed via the package manager with
+## Usage at a Glance
+At least one optimization solver is required to run GasPowerModels.
+The solver selected typically depends on the type of problem formulation being employed.
+As an example, the mixed-integer nonlinear programming solver [Juniper](https://github.com/lanl-ansi/Juniper.jl) can be used for testing any of the problem formulations considered in this package.
+Juniper itself depends on the installation of a nonlinear programming solver (e.g., [Ipopt](https://github.com/jump-dev/Ipopt.jl)) and a mixed-integer linear programming solver (e.g., [CBC](https://github.com/jump-dev/Cbc.jl)).
+Installation of the JuMP interfaces to Juniper, Ipopt, and Cbc can be performed via the Julia package manager, i.e.,
 
 ```julia
-Pkg.add("Pavito")
+] add JuMP Juniper Ipopt Cbc
 ```
 
-Test that the package works by running
+After installation of the required solvers, an example gas-power flow feasibility problem (whose file inputs can be found in the `examples` directory within the [GasPowerModels repository](https://github.com/lanl-ansi/GasPowerModels.jl)) can be solved via
+```julia
+using JuMP, Juniper, Ipopt, Cbc
+using GasPowerModels
+
+# Set up the optimization solvers.
+ipopt = JuMP.optimizer_with_attributes(Ipopt.Optimizer, "print_level"=>0, "sb"=>"yes")
+cbc = JuMP.optimizer_with_attributes(Cbc.Optimizer, "logLevel"=>0)
+juniper = JuMP.optimizer_with_attributes(Juniper.Optimizer, "nl_solver"=>ipopt, "mip_solver"=>cbc)
+
+# Specify paths to the gas and power network files.
+g_file = "examples/data/matgas/belgian.m" # Gas network.
+p_file = "examples/data/matpower/case14.m" # Power network.
 
+# Specify the gas and power formulation types separately.
+g_type, p_type = MISOCPGasModel, SOCWRPowerModel
+
+# Solve the gas-power flow feasibility problem.
+result = run_gpf(g_file, p_file, g_type, p_type, juniper;
+    gm_solution_processors=[GasPowerModels._GM.sol_psqr_to_p!],
+    pm_solution_processors=[GasPowerModels._PM.sol_data_model!])
+```
+
+After solving the problem, results can then be analyzed, e.g.,
 ```julia
-Pkg.test("GasPowerModels")
+# The termination status of the optimization solver.
+result["termination_status"]
+
+# Generator 1's real power generation.
+result["solution"]["gen"]["1"]["pg"]
+
+# Junction 1's pressure.
+result["solution"]["junction"]["1"]["p"]
 ```

docs/src/math-model.md

@@ -1,15 +1,14 @@
 # The GasPowerModels Mathematical Model
-
-As GasPowerModels implements a variety of coupled gas grid network optimization problems, the implementation is the best reference for precise mathematical formulations.  This section provides a mathematical specification for a prototypical coupled gas grid Flow problem, to provide an overview of the typical mathematical models in GasPowerModels.
-
+As GasPowerModels implements a variety of coupled gas grid network optimization problems, the implementation is the best reference for precise mathematical formulations.
+This section provides a mathematical specification for a prototypical coupled gas grid flow problem to provide an overview of the typical mathematical models in GasPowerModels.
 
 ## Coupled Gas Electric Power Flow
-
-GasPowerModels implements a steady-state model of gas flow and power flow based on the implementations of gas flows in GasModels.jl and power flows in PowerModels.jl.  The key coupling constraint between
-power and gas systems is through generators that consume gas to produce power.  This is expressed in terms of a heat rate curve, i.e.
-
+GasPowerModels implements a steady-state model of gas flow and power flow based on the implementations of gas flows in GasModels.jl and power flows in PowerModels.jl.
+The key coupling constraint between power and gas systems is through generators that consume gas to produce power.
+This is expressed in terms of a heat rate curve, i.e.
 ```math
 f = e * \rho (h_2 * pg^2 + h_1 * pg + h_0)
 ```
-where $h$ is a quadratic function used to convert MW ($pg$) into Joules consumed per second. This is then converted to mass flow, $f$, (kg/s) of gas consumed to produce this energy. Here, $e$ is an energy factor (m^3/s) and $\rho$ is standard density (kg/m^3).
-
+where $h$ is a quadratic function used to convert MW ($pg$) into Joules consumed per second.
+This is then converted to mass flow, $f$, (kg/s) of gas consumed to produce this energy.
+Here, $e$ is an energy factor (m^3/s) and $\rho$ is standard density (kg/m^3).

docs/src/model.md

@@ -1,4 +1,2 @@
 # Gas Grid Model
-
 A gas grid model is defined in terms of a GasModel and a PowerModel.
-