Visualization of network. (#336)

* surrogate training notebook * apply black * updating example * updating tutorial * Run black * adding dataset * applying black * fixing black error * applying black * adding primitive results * applying black adding header * removing commented code * adding position to the nodes * adding pos to the nodes * applying black * adding save figure feature * applying black * adding test * Update pareto/examples/desalination_jupyter_notebooks/desalination_surrogate_training.ipynb * Run black * Increase timeout for utilities tests * Increase timeout for strategic toy case study test * Increase test coverage * Tweak formatting of graphs * Implement show results feature * adding .rst file * adding image with correct extension * updating index.rst * updating index * Edit documentation * Trigger build * Fix indentation * More documentation edits --------- Co-authored-by: JavalVyas2000 <[email protected]> Co-authored-by: Travis Arnold <[email protected]> Co-authored-by: Travis Arnold <[email protected]>
project-pareto · Sep 2, 2024 · c4c82fc · c4c82fc
1 parent 2585277
commit c4c82fc
Show file tree

Hide file tree

Showing 8 changed files with 405 additions and 2 deletions.
diff --git a/docs/utilities/index.rst b/docs/utilities/index.rst
@@ -12,4 +12,5 @@ PARETO project provides a set of user-friendly utility methods to display and an
     Get_Data
     Results
     Earthquake_Distance
+    visualize
 
diff --git a/docs/utilities/network.png b/docs/utilities/network.png
diff --git a/docs/utilities/network_circular.png b/docs/utilities/network_circular.png
diff --git a/docs/utilities/visualize.rst b/docs/utilities/visualize.rst
@@ -0,0 +1,50 @@
+Visualization Feature
+======================
+
+This feature utilizes the `networkx` library to create a graphical visualization of the network model. The method extracts nodes and edges from the model to generate a visual representation, allowing for an intuitive understanding of the network's structure.
+
+Usage Instructions
+------------------
+
+To use this feature, first build the model and then call the visualization method as shown below::
+
+    plot_network(model)
+
+You can customize the visualization by adjusting the argument values as needed. For example, to display both piping and trucking arcs, you can use::
+
+    plot_network(model, show_piping=True, show_trucking=True)
+
+A complete list of the optional keyword arguments for `plot_network()` follows:
+
+- ``show_piping``: (``bool``, default = ``True``)
+    Determines whether to display available pipeline arcs within the network.
+
+- ``show_trucking``: (``bool``, default = ``False``)
+    Determines whether to display available trucking arcs within the network.
+
+- ``show_results``: (``bool``, default = ``False``)
+    If ``True``, the network visualization will highlight the pipelines which are suggested to be built or expanded. The model needs to be in a solved state for this option to have an effect.
+
+- ``save_fig``: (``str``, default = ``None``)
+    Specifies the file name for saving the visualization. No figure is saved if a file name is not provided.
+
+- ``show_fig``: (``bool``, default = ``True``)
+    If ``True``, the network visualization will be displayed directly after creation.
+
+- ``pos``: (``dict``, optional)
+    A dictionary to define the relative positions of the nodes in the format ``{Node: (x, y)}``. For example: ``{R01: (10,10)}``. If this dictionary is not provided, the network elements are displayed in a circular layout.
+
+Examples
+--------
+
+The following figures show the network visualization produced for the strategic toy case study, showing both piping and trucking arcs, first with the default circular layout, and second in a layout with custom positioning:
+
+.. figure:: network_circular.png
+    :width: 800
+    :align: center
+    :alt: Network visualization in a circular layout
+
+.. figure:: network.png
+    :width: 800
+    :align: center
+    :alt: Network visualization with specified positions
diff --git a/pareto/strategic_water_management/run_strategic_model.py b/pareto/strategic_water_management/run_strategic_model.py
@@ -32,6 +32,7 @@
     is_feasible,
     nostdout,
 )
+from pareto.utilities.visualize import plot_network
 from importlib import resources
 
 
@@ -115,3 +116,43 @@
     output_units=OutputUnits.user_units,
     fname="strategic_optimization_results.xlsx",
 )
+
+# Positions for the toy case study
+pos = {
+    "PP01": (20, 20),
+    "PP02": (45, 20),
+    "PP03": (50, 50),
+    "PP04": (80, 40),
+    "CP01": (65, 20),
+    "F01": (75, 15),
+    "F02": (75, 25),
+    "K01": (30, 10),
+    "K02": (40, 50),
+    "S02": (60, 50),
+    "S03": (10, 44),
+    "S04": (10, 36),
+    "R01": (20, 40),
+    "R02": (70, 50),
+    "O01": (1, 55),
+    "O02": (1, 40),
+    "O03": (1, 25),
+    "N01": (30, 20),
+    "N02": (30, 30),
+    "N03": (30, 40),
+    "N04": (40, 40),
+    "N05": (45, 30),
+    "N06": (50, 40),
+    "N07": (60, 40),
+    "N08": (60, 30),
+    "N09": (70, 40),
+}
+
+# Network visualization feature
+plot_network(
+    strategic_model,
+    show_piping=True,
+    show_trucking=True,
+    show_results=False,
+    save_fig="network.png",
+    pos=pos,
+)
diff --git a/pareto/tests/test_strategic_model.py b/pareto/tests/test_strategic_model.py
@@ -1081,7 +1081,7 @@ def test_run_toy_strategic_model(build_toy_strategic_model):
         "deactivate_slacks": True,
         "scale_model": False,
         "scaling_factor": 1000,
-        "running_time": 60 * 5,
+        "running_time": 600,
         "gap": 0,
     }
 

diff --git a/pareto/tests/test_utilities.py b/pareto/tests/test_utilities.py
@@ -44,6 +44,8 @@
     MissingDataError,
     DataInfeasibilityError,
 )
+from pareto.utilities.visualize import plot_network
+from contextlib import nullcontext as does_not_raise
 
 
 ############################
@@ -77,7 +79,7 @@ def fetch_strategic_model(config_dict):
         "deactivate_slacks": True,
         "scale_model": False,
         "scaling_factor": 1000,
-        "running_time": 300,
+        "running_time": 600,
         "gap": 0,
     }
 
@@ -458,3 +460,69 @@ def test_infeasibility_check():
             "An infeasibility in the input data has been detected. The following time periods have higher demand than volume of produced water and externally sourced water available: T01 (70000 koil_bbls demand vs 756 koil_bbls available water)"
             == str(error_record.value)
         )
+
+
+def test_plot_network():
+    with resources.path(
+        "pareto.case_studies",
+        "strategic_toy_case_study.xlsx",
+    ) as fpath:
+        # When set_list and parameter_list are not specified to get_data(), all tabs with valid PARETO input names are read
+        [df_sets, df_parameters] = get_data(fpath, model_type="strategic")
+    strategic_model = create_model(
+        df_sets,
+        df_parameters,
+        default={
+            "objective": Objectives.cost,
+            "pipeline_cost": PipelineCost.distance_based,
+            "pipeline_capacity": PipelineCapacity.input,
+            "hydraulics": Hydraulics.false,
+            "node_capacity": True,
+            "water_quality": WaterQuality.false,
+            "removal_efficiency_method": RemovalEfficiencyMethod.concentration_based,
+            "infrastructure_timing": InfrastructureTiming.true,
+        },
+    )
+
+    # Positions for the toy case study
+    pos = {
+        "PP01": (20, 20),
+        "PP02": (45, 20),
+        "PP03": (50, 50),
+        "PP04": (80, 40),
+        "CP01": (65, 20),
+        "F01": (75, 15),
+        "F02": (75, 25),
+        "K01": (30, 10),
+        "K02": (40, 50),
+        "S02": (60, 50),
+        "S03": (10, 44),
+        "S04": (10, 36),
+        "R01": (20, 40),
+        "R02": (70, 50),
+        "O01": (1, 55),
+        "O02": (1, 40),
+        "O03": (1, 25),
+        "N01": (30, 20),
+        "N02": (30, 30),
+        "N03": (30, 40),
+        "N04": (40, 40),
+        "N05": (45, 30),
+        "N06": (50, 40),
+        "N07": (60, 40),
+        "N08": (60, 30),
+        "N09": (70, 40),
+    }
+
+    # Run the plot_network function with several different sets of input arguments
+    try:
+        plot_network(strategic_model, pos=pos)
+        plot_network(strategic_model, show_piping=True, show_trucking=True)
+        plot_network(
+            strategic_model,
+            show_results=True,
+            save_fig="test_network.png",
+            show_fig=True,
+        )
+    except Exception as e:
+        pytest.fail(f"Plot network feature fails with the following exception {e}")