Merge pull request #17 from lanl-ansi/update-doc

UPD: Update and improve documentation
lanl-ansi · Oct 22, 2022 · 448df71 · 448df71
2 parents 873eec0 + 5d460c2
commit 448df71
Show file tree

Hide file tree

Showing 20 changed files with 463 additions and 21 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@ PowerWaterModels.jl Change Log
 =======================
 
 ### v0.3.0
+- Update documentation.
 - Rename `run_` methods to `_solve` and add deprecation warnings.
 - Updates for InfrastructureModels v0.7.
 - Updates for PowerModelsDistribution v0.14.

diff --git a/docs/make.jl b/docs/make.jl
@@ -10,24 +10,19 @@ makedocs(
         "Manual" => [
             "Getting Started" => "quickguide.md",
             "Network Data Format" => "network-data.md",
-            "Result Data Format" => "result-data.md",
-            "Mathematical Models" => "math-model.md"
+            "Result Data Format" => "result-data.md"
         ],
         "Library" => [
             "Network Formulations" => "formulations.md",
             "Problem Specifications" => "specifications.md",
             "Modeling Components" => [
-                "Power Model" => "power-model.md",
-                "Water Model" => "water-model.md",
                 "Objective" => "objective.md",
-                "Variables" => "variables.md",
                 "Constraints" => "constraints.md"
             ],
-            "Relaxation Schemes" => "relaxations.md",
             "File I/O" => "parser.md"
         ],
         "Developer" => "developer.md",
-        "Benchmarks" => "benchmarks.md"
+        "Examples" => "examples.md"
     ]
 )
 

diff --git a/docs/src/benchmarks.md b/docs/src/benchmarks.md
diff --git a/docs/src/constraints.md b/docs/src/constraints.md
@@ -1,6 +1,10 @@
 # Constraints
-```@meta
-CurrentModule = PowerWaterModels
-```
+We define the following methods to provide a compositional approach toward defining linking constraints used in coupled power-water models.
+Such methods should always be defined over `AbstractPowerWaterModel`.
 
-## Linking Constraints
+```@autodocs
+Modules = [PowerWaterModels]
+Pages   = ["core/constraint.jl"]
+Order   = [:type, :function]
+Private  = true
+```
diff --git a/docs/src/developer.md b/docs/src/developer.md
@@ -1 +1,82 @@
 # Developer Documentation
+
+## Data Processing Functions
+The PowerWaterModels data format allows the user to specify power network data, water network data, and data related to the interdependencies between power and water systems.
+PowerWaterModels relies on the automated data processing routines of [PowerModelsDistribution](https://github.com/lanl-ansi/PowerModelsDistribution.jl) and [WaterModels](https://github.com/lanl-ansi/WaterModels.jl), which include capabilities for status propagation, nondimensionalization, topology correction, etc.
+However, these capabilities are typically used on independent infrastructure data, whereas PowerWaterModels must join these data.
+Thus, in preprocessing routines, it is recommended that capabilities be invoked explictly so that external dependencies are accounted for.
+For example, the core data parsing function `parse_files` performs the following operations:
+```julia
+function parse_files(power_path::String, water_path::String, link_path::String)
+    joint_network_data = parse_link_file(link_path)
+    _IM.update_data!(joint_network_data, parse_power_file(power_path))
+    _IM.update_data!(joint_network_data, parse_water_file(water_path))
+    correct_network_data!(joint_network_data)
+
+    # Store whether or not each network uses per-unit data.
+    p_per_unit = get(joint_network_data["it"][_PMD.pmd_it_name], "per_unit", false)
+    w_per_unit = get(joint_network_data["it"][_WM.wm_it_name], "per_unit", false)
+
+    # Make the power and water data sets multinetwork.
+    joint_network_data_mn = make_multinetwork(joint_network_data)
+
+    # Prepare and correct pump load linking data.
+    assign_pump_loads!(joint_network_data_mn)
+
+    # Modify variable load properties in the power network.
+    _modify_loads!(joint_network_data_mn)
+
+    # Return the network dictionary.
+    return joint_network_data_mn
+end
+```
+
+Here, the `parse_power_file` and `parse_water_file` use custom routines to parse and transform the input data, i.e.,
+```julia
+function parse_power_file(file_path::String)
+    if split(file_path, ".")[end] == "m" # If reading a MATPOWER file.
+        data = _PM.parse_file(file_path)
+        _scale_loads!(data, 1.0 / 3.0)
+        _PMD.make_multiconductor!(data, 3)
+    else
+        data = _PMD.parse_file(file_path)
+    end
+
+    return _IM.ismultiinfrastructure(data) ? data :
+          Dict("multiinfrastructure" => true, "it" => Dict(_PMD.pmd_it_name => data))
+end
+
+
+function parse_water_file(file_path::String; skip_correct::Bool = true)
+    data = _WM.parse_file(file_path; skip_correct = skip_correct)
+    return _IM.ismultiinfrastructure(data) ? data :
+           Dict("multiinfrastructure" => true, "it" => Dict(_WM.wm_it_name => data))
+end
+```
+
+After these routines are called, `correct_network_data!` executes various data and topology correction routines on power, water, and linking data.
+Then, `make_multinetwork` ensures that the temporal dimension of each infrastructure and interdependency subdictionary match.
+Finally, interdependency data are corrected and modified via `assign_pump_loads!` and `_modify_loads!` to ensure linking constraints will be modeled appropriately.
+
+## Compositional Problems
+A best practice is to adopt a compositional approach for building problems in PowerWaterModels, leveraging problem definitions of PowerModelsDistribution and WaterModels.
+This helps lessen the impact of breaking changes across independent infrastructure packages.
+For example, the joint optimal power-water flow problem invokes similar problems of PowerModelsDistribution and WaterModels directly with routines like
+
+```julia
+# Power-only related variables and constraints.
+pmd = _get_powermodel_from_powerwatermodel(pwm)
+_PMD.build_mn_mc_mld_simple(pmd)
+
+# Water-only related variables and constraints.
+wm = _get_watermodel_from_powerwatermodel(pwm)
+_WM.build_mn_owf(wm)
+
+# Power-water linking constraints.
+build_linking(pwm)
+
+# Add the objective that minimizes power generation costs.
+_PMD.objective_mc_min_fuel_cost(pmd)
+```
+
+Compared to the `PowerModelsDistribution` (`_PMD`) and `WaterModels` (`_WM`) routines, the PowerWaterModels routines only specify interdependency constraints.
diff --git a/docs/src/examples.md b/docs/src/examples.md
@@ -0,0 +1,42 @@
+# Examples Documentation
+
+## Optimal Power-Water Flow Example
+
+In the example script located at [`examples/opwf.jl`](https://github.com/lanl-ansi/PowerWaterModels.jl/blob/master/examples/opwf.jl), we demonstrate the utility of PowerWaterModels for exploring the tradeoffs encountered in the coordination of joint power and water distribution system operation.
+Specifically, we draw inspiration from [1], where the joint [Optimal Power-Water Flow (OPWF)](@ref) problem is formalized, which coordinates tanks and pumps in the water network to improve operations in the power network.
+In PowerWaterModels, similar OPWF problems can easily be constructed using a variety of power and water network formulations while forgoing the need to develop specialized algorithms.
+This enables an efficient and systematic analysis of solutions under various modeling assumptions.
+
+Within the script, `LinDist3FlowPowerModel` is based on the power flow approximation of [2], and `PWLRDWaterModel` is a piecewise-linear water flow relaxation similar to the relaxations of [3] and [4]. The example is based on benchmark data described by [1], which couples the IEEE 13-node test feeder of [5] with a synthetic municipal water network developed by [6].
+Notably, the data uses a time series of twelve hours discretized into thirty minute intervals.
+This analysis thus highlights the temporal modeling features of PowerWaterModels.
+
+Joint OPWF problems are naturally geared toward understanding the tradeoffs between power and water network operations.
+These tradeoffs are easily explored via modification of the joint objective function.
+In the example, we test three objectives to explore these tradeoffs.
+The first minimizes operational cost of the single generating unit in the power network while assuming inexpensive midday fuel prices.
+The second does the same while assuming expensive midday fuel prices.
+The final objective minimizes the deviation in active power generation between adjacent time steps, i.e., minimizes fluctuations in the generation profile.
+Each objective has implications for optimal operations of the power network as well as the water network, where pumps are modeled as power loads and water tanks provide indirect energy storage.
+
+The results from executing the example generate a number of plots.
+In one plot, the three distinct price signals are shown.
+These correspond to the various time profiles of generation cost coefficients used in the different analyses.
+The remaining figures indicate how the power generation and water storage vary based on these different objective functions.  
+When generation prices are high, it is less advantageous to operate water pumps, which correspond to drops in power generation and tank volumes during the midday period.
+Otherwise, if generation is inexpensive, it's advantageous to operate water pumps and increase tank volumes during the midday period.
+If the objective is to smooth the generation profile, it can be facilitated through careful use of pumps throughout the day.
+
+## Sources
+
+[1] Zamzam, A. S., Dall’Anese, E., Zhao, C., Taylor, J. A., & Sidiropoulos, N. D. (2018). Optimal water–power flow-problem: Formulation and distributed optimal solution. _IEEE Transactions on Control of Network Systems_, _6_(1), 37-47.
+
+[2] Gan, L., & Low, S. H. (2014, August). Convex relaxations and linear approximation for optimal power flow in multiphase radial networks. In _2014 Power Systems Computation Conference_ (pp. 1-9). IEEE.
+
+[3] Tasseff, B., Bent, R., Coffrin, C., Barrows, C., Sigler, D., Stickel, J., ... & Van Hentenryck, P. (2022). Polyhedral relaxations for optimal pump scheduling of potable water distribution networks. _arXiv preprint arXiv:2208.03551_.
+
+[4] Vieira, B. S., Mayerle, S. F., Campos, L. M., & Coelho, L. C. (2020). Optimizing drinking water distribution system operations. _European Journal of Operational Research_, _280_(3), 1035-1050.
+
+[5] Kersting, W. H. (1991). Radial distribution test feeders. _IEEE Transactions on Power Systems_, _6_(3), 975-985.
+
+[6] Cohen, D., Shamir, U., & Sinai, G. (2000). Optimal operation of multi-quality water supply systems-II: The QH model. _Engineering Optimization+ A35_, _32_(6), 687-719.
diff --git a/docs/src/formulations.md b/docs/src/formulations.md
@@ -1 +1,18 @@
 # Network Formulations
+The network formulations for joint power-water modeling use the formulations defined in [PowerModelsDistribution.jl](https://lanl-ansi.github.io/PowerModelsDistribution.jl/stable/) and [WaterModels.jl](https://lanl-ansi.github.io/WaterModels.jl/stable/).
+
+# PowerWaterModels Types
+```@meta
+CurrentModule = PowerWaterModels
+```
+
+Specification of a `PowerWaterModel` requires the specification of both a `PowerModelsDistribution.AbstractUnbalancedPowerModel` and a `WaterModels.AbstractWaterModel`, respectively.
+For example, to specify a formulation that leverages the `LinDist3FlowPowerModel` and `PWLRDWaterModel` types, the corresponding `PowerWaterModel` type would be
+```julia
+PowerWaterModel{LinDist3FlowPowerModel, PWLRDWaterModel}
+```
+
+PowerWaterModels then utilizes the following (internal) function to construct a `PowerWaterModel` object:
+```@docs
+instantiate_model
+```
diff --git a/docs/src/math-model.md b/docs/src/math-model.md
diff --git a/docs/src/network-data.md b/docs/src/network-data.md
@@ -1 +1,56 @@
 # PowerWaterModels Network Data Format
+
+## The Network Data Dictionary
+Internally, PowerWaterModels uses a dictionary to store network data for both power distribution systems (see [PowerModelsDistribution.jl](https://lanl-ansi.github.io/PowerModelsDistribution.jl/stable/)) and water distribution systems (see [WaterModels.jl](https://lanl-ansi.github.io/WaterModels.jl/stable/)).
+The dictionary uses strings as key values so it can be serialized to JSON for algorithmic data exchange.
+The I/O for PowerWaterModels utilizes the serializations available in [PowerModelsDistribution.jl](https://lanl-ansi.github.io/PowerModelsDistribution.jl/stable/) and [WaterModels.jl](https://lanl-ansi.github.io/WaterModels.jl/stable/) to construct the joint network model.
+All data are assumed to be in per-unit (non-dimensionalized) or SI units.
+Power, water, and interdependency data are each stored in the `data["it"]["pmd"]`, `data["it"]["wm"]`, and `data["it"]["dep"]` subdictionaries of `data`, respectively.
+Descriptions of the first two subdictionaries are presented in the documentation of [PowerModelsDistribution.jl](https://lanl-ansi.github.io/PowerModelsDistribution.jl/stable/) and [WaterModels.jl](https://lanl-ansi.github.io/WaterModels.jl/stable/), respectively.
+
+Beside the standard network data supported by [PowerModelsDistribution.jl](https://lanl-ansi.github.io/PowerModelsDistribution.jl/stable/) and [WaterModels.jl](https://lanl-ansi.github.io/WaterModels.jl/stable/), there are a few extra fields that are required to couple the two systems together.
+These fields are described in the following subsection.
+
+### Interdependency Information
+Note that the current version of PowerWaterModels supports only one type of interdependency, i.e., modeling select pumps in the water distribution network as loads in the power distribution network.
+This is represented by an interdependency type named `"pump_load"`.
+Aside from the interdependency definitions, additional `"source_type"` entries are added to the PowerModelsDistribution (`"pmd"`) and WaterModels (`"wm"`) subdictionaries to assist in ultimately transforming and linking power and water network inputs.
+```json
+{
+    "it": {
+        "dep": {
+            "pump_load": {
+                "1": {
+                    "pump": {
+                        "source_id": <String> # Index in the source water
+                        # network data file of the pump that is being modeled
+                        # in the interdependency.
+                    },
+                    "load": {
+                        "source_id": <String> # Index in the source power
+                        # network data file of the load that is being modeled
+                        # in the interdependency.
+                    },
+                    "status": <Int64> # Indicator (-1, 0, or 1) specifying if
+                    # the status of the interdependency is unknown (-1, i.e.,
+                    # potentially on _or_ off), inactive (0, i.e., off) or 
+                    # active (1, i.e., on).
+                },
+                "2": {
+                    ...
+                },
+                ...
+            }
+        },
+    "pmd": {
+        "source_type": <String> # Type of input file used to describe the power
+        # distribution network model. Can be "opendss" or "matpower".
+        ...
+    },
+    "wm": {
+        "source_type": <String> # Type of input file used to describe the water
+        # distribution network model. Can currently only be set to "epanet".
+        ...
+    }
+}
+```
diff --git a/docs/src/objective.md b/docs/src/objective.md
@@ -1,3 +1,10 @@
 # Objective
-
-## Objective Functions
+The objective used by the [Power-Water Flow (PWF)](@ref) problem specification is a feasibility-only objective.
+The default objective used by the [Optimal Power-Water Flow (OPWF)](@ref) problem specification is [`_PMD.objective_mc_min_fuel_cost(pmd)`](https://lanl-ansi.github.io/PowerModelsDistribution.jl/stable/reference/objectives.html#PowerModelsDistribution.objective_mc_min_fuel_cost-Tuple{AbstractUnbalancedPowerModel}), which is described in the [PowerModelsDistribution documentation](https://lanl-ansi.github.io/PowerModelsDistribution.jl/stable/) and represents a standard fuel cost minimization.
+In addition to these objectives, PowerWaterModels also defines an additional objective, `objective_min_max_generation_fluctuation(pwm)`, defined over `AbstractPowerWaterModel`.
+```@autodocs
+Modules = [PowerWaterModels]
+Pages   = ["core/objective.jl"]
+Order   = [:function]
+Private  = true
+```
diff --git a/docs/src/parser.md b/docs/src/parser.md
@@ -1,8 +1,57 @@
 # File I/O
+Parsing functions in PowerWaterModels use the native parsing features of [PowerModelsDistribution](https://github.com/lanl-ansi/PowerModelsDistribution.jl) and [WaterModels](https://github.com/lanl-ansi/WaterModels.jl) with extra features to parse information used to couple the two infrastructures.
+
 ```@meta
 CurrentModule = PowerWaterModels
 ```
 
+## Coupling Data Format
+The PowerWaterModels parsing implementation relies on data formats that support extensions to accommodate arbitrary extra data fields, such as those required to define couplings between infrastructures.
+Thus, PowerWaterModels largely relies on parsing of [MATPOWER](https://matpower.org/), [OpenDSS](https://www.epri.com/pages/sa/opendss), and [EPANET](https://www.epa.gov/water-research/epanet) input files to populate some data fields.
+In addition, the coupling between loads and pumps is accomplished via a tertiary JSON linking file of the following form (further detailed in [Interdependency Information](@ref)):
+```json
+{
+    "it": {
+        "dep": {
+            "pump_load": {
+                "1": {
+                    "pump": {
+                        "source_id": <String> # Index in the source water
+                        # network data file of the pump that is being modeled
+                        # in the interdependency.
+                    },
+                    "load": {
+                        "source_id": <String> # Index in the source power
+                        # network data file of the load that is being modeled
+                        # in the interdependency.
+                    },
+                    "status": <Int64> # Indicator (-1, 0, or 1) specifying if
+                    # the status of the interdependency is unknown (-1, i.e.,
+                    # potentially on _or_ off), inactive (0, i.e., off) or 
+                    # active (1, i.e., on).
+                },
+                "2": {
+                    ...
+                },
+                ...
+            }
+        },
+    "pmd": {
+        "source_type": <String> # Type of input file used to describe the power
+        # distribution network model. Can be "opendss" or "matpower".
+        ...
+    },
+    "wm": {
+        "source_type": <String> # Type of input file used to describe the water
+        # distribution network model. Can currently only be set to "epanet".
+        ...
+    }
+}
+```
+
+## Parsing Functions
+The following functions can be used for convenient parsing of input files.
+
 ```@docs
 parse_files
 parse_json

diff --git a/docs/src/power-model.md b/docs/src/power-model.md