Merge pull request #102 from dlcole3/dc/add_query_info_to_docs

Added details to docs for accessing variables on nodes and subgraphs

docs/src/tutorials/gas_pipeline.md

@@ -374,3 +374,8 @@ depicts the optimization problem partitioned into 13 distinct partitions.
 
 
 ![partition](../assets/13_pipeline_space_time_partition.svg)
+
+## Querying Solutions
+The modular construction of an OptiGraph often results in variables with the same names being stored on different subgraphs or nodes, and accessing variables in OptiGraphs with multiple nodes or subgraphs is not always as simple as calling the symbol for the variable. Variable references for variables in a graph can be thought of as being "nested" on nodes that are "nested" on subgraphs. The "owning" subgraph can be accessed by calling `getsubgraphs(::OptiGraph)`. In addition, in the above code, each pipeline, junction, and compressor subgraph was saved on the OptiGraph `gas_network` using the symbols `:pipeline`, `:junction`, and `:compressor`, respectively. Thus, the subgraphs for each of these objects can be called by using these symbols, such as using `gas_network[:pipeline]` to get the vector of all pipeline subgraphs. *Importantly, the vectors of subgraphs are not in the order they appear in the network because they were formed by iterating through entries to dictionaries, which are order-free*. In other words, the pipelines are not in order from 1 - 13. To identify the order the pipelines, junctions, and compressors appear in their respective vectors, the user will have to track the order to which these are added in the for loop.
+
+As an example of the "nested" nature of the variables, we can consider the problem above. There is a set of nodes called `grid` (that contain `nt` $\times$ `nx` nodes) for each `pipeline` OptiGraph, and each of these nodes contain a variable called `px` and `fx`. To access the `px` variable at $t = 1$ and $x = 2$ on the first pipeline subgraph of the vector, we can call `gas_network[:pipelines][1][:grid][1, 2][:px]`. Here, `[:pipelines]` acesses the vector of pipelines, `[1]` accesses the first subgraph of that vector, `[:grid]` accesses the set of nodes called "grid", `[1, 2]` accesses the node at time $t = 1$ and $x = 2$, and `[:px]` accesses the variable called `px`. Alternatively, instead of calling `gas_network[:pipelines][1]`, the same pipeline subgraph could be accessed by calling `getsubgraphs(gas_network)[26]`. Subgraphs appear in `getsubgraphs(::OptiGraph)` in the order they were added to the OptiGraph; as the junctions are added to `gas_network` first, followed by pipelines and then compressors in the above code, the first 25 entries of `getsubgraphs(gas_network)` will correspond to junctions and entries 26 - 38 will contain the pipelines. With the variable references, a user can query solutions to these variables after calling `optimize!(gas_network)` by using `JuMP.value`, such as calling `value(gas_network[:pipelines][1][:grid][1, 2][:px])`.