Bug fix for initial status and initial setting used by the WNTRSimulator (#506)

* added _user_status to initial_status setter

* added test and documented status variables in comments

* Added _setting to initial setting and added a test

* documentation update

Author: kaklise

wntr/network/base.py

@@ -355,22 +355,26 @@ def __init__(self, wn, link_name, start_node_name, end_node_name):
         # Set and register the ending node
         self._end_node = self._node_reg[end_node_name]
         self._node_reg.add_usage(end_node_name, (link_name, self.link_type))
-        # Set up other metadata fields
-        self._initial_status = LinkStatus.Opened
-        self._initial_setting = None
-        self._vertices = []
-        self._tag = None
-        # Model state variables
-        self._user_status = LinkStatus.Opened
-        self._internal_status = LinkStatus.Active
+        # Set status variables
+        self._user_status = LinkStatus.Opened # Control status, can be changed by the user
+        self._initial_status = LinkStatus.Opened # Model initial status, can be changed by the user
+        self._internal_status = LinkStatus.Active # Intermediate simulation status, read only
+        self._status= None # Current simulation status, read only
+        # Set setting variables
+        self._initial_setting = None # Model initial setting, can be changed by the user
+        self._prev_setting = None # Previous simulation setting, read only
+        self._setting = None # Current simulation setting, read only
+        # Other model state variables
         self._initial_quality = None
-        self._prev_setting = None
-        self._setting = None
         self._flow = None
         self._velocity = None
         self._is_isolated = False
         self._quality = None
         self._headloss = None
+        # Other
+        self._vertices = []
+        self._tag = None
+        
 
     def _compare(self, other):
         """
@@ -423,6 +427,7 @@ def initial_status(self, status):
             elif isinstance(status, str): status = LinkStatus[status]
             else: status = LinkStatus(int(status))
         self._initial_status = status
+        self._user_status = status
 
     @property
     def initial_setting(self):
@@ -432,6 +437,7 @@ def initial_setting(self):
     def initial_setting(self, setting):
         # TODO: typechecking
         self._initial_setting = setting
+        self._setting =  setting
 
     @property
     def start_node(self):

wntr/tests/test_network_controls.py

@@ -2,6 +2,7 @@
 import unittest
 import warnings
 from os.path import abspath, dirname, join
+import copy
 
 import wntr
 
@@ -11,15 +12,24 @@
 
 
 class TestValveSettingControls(unittest.TestCase):
-    def test_status_open_when_setting_changes(self):
+    @classmethod
+    def setUpClass(self):
         wn = wntr.network.WaterNetworkModel()
         wn.add_reservoir("r1", base_head=10)
         wn.add_junction("j1", base_demand=0)
         wn.add_junction("j2", base_demand=0.05)
         wn.add_pipe("p1", "r1", "j1")
-        wn.add_valve("v1", "j1", "j2", valve_type="PRV", initial_setting=2)
+        wn.add_valve("v1", "j1", "j2", valve_type="PRV", 
+                     initial_setting=2, initial_status='Active')
         wn.options.time.duration = 3600 * 5
-
+        self.wn = wn
+    
+    @classmethod
+    def tearDownClass(self):
+        pass
+    
+    def test_status_open_when_setting_changes(self):
+        wn = copy.deepcopy(self.wn)
         action = wntr.network.ControlAction(
             wn.get_link("v1"), "status", wntr.network.LinkStatus.Closed
         )
@@ -37,8 +47,64 @@ def test_status_open_when_setting_changes(self):
         self.assertEqual(
             results.link["status"].at[7200, "v1"], wntr.network.LinkStatus.Active
         )
-
-
+    
+    def test_initial_status(self):
+        # Run simulations with open valve
+        wn = copy.deepcopy(self.wn)
+        valve_name = 'v1'
+        valve = wn.get_link(valve_name)
+        valve.initial_status = 'Open'
+        
+        sim = wntr.sim.EpanetSimulator(wn)
+        results_epanet_open = sim.run_sim()
+        
+        sim = wntr.sim.WNTRSimulator(wn)
+        results_wntr_open = sim.run_sim()
+        
+        # Check that valve is open (1) and flow is not 0
+        assert (results_epanet_open.link['status'].loc[:,'v1'] == 1).all()
+        assert (results_wntr_open.link['status'].loc[:,'v1'] == 1).all()
+        assert (results_epanet_open.link['flowrate'].loc[:,'v1'].abs() > 0).all()
+        assert (results_wntr_open.link['flowrate'].loc[:,'v1'].abs() > 0).all()
+        
+        # Run simulations with closed valve
+        wn = copy.deepcopy(self.wn)
+        valve_name = 'v1'
+        valve = wn.get_link(valve_name)
+        valve.initial_status = 'Closed'
+        
+        sim = wntr.sim.EpanetSimulator(wn)
+        results_epanet_closed = sim.run_sim()
+        
+        sim = wntr.sim.WNTRSimulator(wn)
+        results_wntr_closed = sim.run_sim()
+        
+        # Check that valve is closed (0) and flow is 0
+        assert (results_epanet_closed.link['status'].loc[:,'v1'] == 0).all()
+        assert (results_wntr_closed.link['status'].loc[:,'v1'] == 0).all()
+        assert (results_epanet_closed.link['flowrate'].loc[:,'v1'] == 0).all()
+        assert (results_wntr_closed.link['flowrate'].loc[:,'v1'] == 0).all()
+
+    def test_initial_setting(self):
+        # Run simulations with valve setting of 4
+        wn = copy.deepcopy(self.wn)
+        valve_name = 'v1'
+        valve = wn.get_link(valve_name)
+        # pressure setting on its downstream side when the upstream pressure is above the setting
+        valve.initial_setting = 4
+        
+        sim = wntr.sim.EpanetSimulator(wn)
+        results_epanet_open = sim.run_sim()
+        
+        sim = wntr.sim.WNTRSimulator(wn)
+        results_wntr_open = sim.run_sim()
+        
+        # Check that valve is active (2) and the downstream pressure is 4
+        assert (results_epanet_open.link['status'].loc[:,'v1'] == 2).all()
+        assert (results_wntr_open.link['status'].loc[:,'v1'] == 2).all()
+        assert (results_epanet_open.node['pressure'].loc[:,'j2'] == 4).all()
+        assert (results_wntr_open.node['pressure'].loc[:,'j2'] == 4).all()
+        
 class TestPumpSettingControls(unittest.TestCase):
     def test_status_open_when_setting_changes(self):
         wn = wntr.network.WaterNetworkModel()