update README and demo.py on sample code

- renanme external_node_id to node_id in class Node;
- renanme external_from_node to from_node_id and external_to_node
  to to_node_id in class Link;
- renanme internal_node_seq_no_dict to node_id_to_no_dict and
  external_node_id_dict to node_no_to_id_dict in class Network;
- all their instances are updated as well.

Author: jdlph

README.md

@@ -279,7 +279,7 @@ network = pg.read_network(load_demand=False)
 print('\nstart accessibility evaluation\n')
 st = time()
 
-pg.evaluate_accessiblity(network, multimodal=False)
+pg.evaluate_accessibility(network, multimodal=False)
 # the default is under mode auto (i.e., p)
 # if you would like to evaluate accessibility under a target mode, say walk, then
 # pg.evaluate_accessibility(network, multimodal=False, mode='w')
@@ -312,9 +312,9 @@ network.get_accessible_links(1, 15, 'w')
 ```
 
 ### When Time-Dependent Link Travel Time Matters
-Link travel time is crucial in calculating accessibility. In the classic accessibility analysis, evalutaion networks are usually considered to be static in terms of link travel time, which is determined by link length and link free-flow speed under a specific mode. The free-flow speed comes from either link.csv or settings.yml (both are denoted as 'free_speed'). When they are different, the minimum of these two will be adopted. The cases demonstrated above are all falling within this category.
+Link travel time is crucial in calculating accessibility. In the classic accessibility analysis, evalutaion networks are usually considered to be static in terms of link travel time, which is determined by link length and link free-flow speed under a specific mode. The free-flow speed comes from either link.csv or settings.yml (both are denoted as "free_speed"). When they are different, the minimum of these two will be adopted. The cases demonstrated above are all falling within this category.
 
-Link travel time varies over time so does accessibility. When the time-dependent accessibility is of interested, time-dependent link travel time (i.e., VDF_fftt from a given demand period in link.csv) will come into play by overwriting the static link free-flow speed above. This new feature is now part of v0.7.3 and is illustrated as below.
+Link travel time varies over time so does accessibility. When the time-dependent accessibility is of interested, time-dependent link travel time (i.e., VDF_fftt from a given demand period in link.csv) will come into play by overwriting the (static) link free-flow speed. This new feature is now part of v0.7.3 and is illustrated as below.
 
 ```python
 import path4gmns as pg
@@ -327,25 +327,22 @@ st = time()
 
 # time-dependent accessibility under the default mode auto (i.e., p)
 # for demand period 0 (i.e., VDF_fftt1 in link.csv will be used in the evaluation)
-pg.evaluate_accessiblity(network, multimodal=False, time_dependent=True)
+pg.evaluate_accessibility(network, multimodal=False, time_dependent=True)
 
 # if you would like to evaluate accessibility under a different demand period
 # (say 1, which must be defined in settings.yml along with VDF_fftt2 in link.csv), then
-# pg.evaluate_accessiblity(network, multimodal=False, time_dependent=True, demand_period_id=1)
+pg.evaluate_accessibility(network, multimodal=False, time_dependent=True, demand_period_id=1)
 
 # if you would like to evaluate accessibility under a target mode, say walk, then
-# pg.evaluate_accessibility(network, multimodal=False, mode='w', time_dependent=True)
-# or equivalently pg.evaluate_accessibility(network, multimodal=False, mode='walk', time_dependent=True)
-
-print('complete accessibility evaluation.\n')
-print(f'processing time of accessibility evaluation: {time()-st:.2f} s')
+pg.evaluate_accessibility(network, multimodal=False, mode='w', time_dependent=True)
 ```
 
-While VDF_fftt begins with 1 (i.e., VDF_fftt1), the argument demand_period_id, corresponding to the sequence number of demand period appeared in demand_periods in settings.yml, starts from 0. So 'demand_period_id=1' indicates that 'VDF_fftt2' will be used.
+While VDF_fftt begins with 1 (i.e., VDF_fftt1), the argument demand_period_id, corresponding to the sequence number of demand period appeared in demand_periods in settings.yml, starts from 0. So "demand_period_id=0" indicates that VDF_fftt1 will be used (and so on and so forth).
 
-**As VDF_fftt in link.csv can only accommodate one mode, time-dependent accessibility evaluation will require the user to prepare mode-specific link.csv with dedicated VDF_fftt and allowed_uses**. That's the reason that multimodal=False is always enforced in these examples.
+**As VDF_fftt in link.csv can only accommodate one mode, time-dependent accessibility evaluation will require the user to prepare a mode-specific link.csv with dedicated VDF_fftt and allowed_uses**. That's the reason that "multimodal=False" is always enforced in these examples.
+
+Retrieve the time-dependent accessible nodes and links is similar to evaluate time-dependent accessibility by simply passing time_dependent and demand_period_id to get_accessible_nodes() and get_accessible_links().
 
-Retrieve the time-dependent accessible nodes and links is similar to evaluate time-dependent accessibility by simply passing time_dependent and demand_period_id to get_accessible_nodes() and get_accessible_links()
 ```python
 import path4gmns as pg
 
@@ -355,6 +352,7 @@ network = pg.read_network(load_demand=False)
 # get accessible nodes and links starting from node 1 with a 5-minitue
 # time window for the default mode auto (i.e., 'p') for demand period 0
 network.get_accessible_nodes(1, 5, time_dependent=True)
+
 # get accessible nodes and links starting from node 1 with a 5-minitue
 # time window for the default mode auto (i.e., 'p') for demand period 1 if it is defined
 network.get_accessible_links(1, 5, time_dependent=True, demand_period_id=1)

path4gmns/classes.py

@@ -12,12 +12,12 @@
 
 class Node:
 
-    def __init__(self, node_seq_no, external_node_id, zone_id, x='', y=''):
+    def __init__(self, node_seq_no, node_id, zone_id, x='', y=''):
         """ the attributes of node  """
-        # external_node_id: user defined node id from input
-        self.node_seq_no = node_seq_no
         # node_seq_no: internal node index used for calculation
-        self.external_node_id = external_node_id
+        self.node_seq_no = node_seq_no
+        # node_id: user defined node id from input
+        self.node_id = node_id
         self.outgoing_link_list = []
         self.incoming_link_list = []
         self.zone_id = zone_id
@@ -34,7 +34,7 @@ def get_zone_id(self):
         return self.zone_id
 
     def get_node_id(self):
-        return self.external_node_id
+        return self.node_id
 
     def get_node_no(self):
         return self.node_seq_no
@@ -76,8 +76,8 @@ def __init__(self,
         self.link_seq_no = link_seq_no
         self.from_node_seq_no = from_node_no
         self.to_node_seq_no = to_node_no
-        self.external_from_node = from_node_id
-        self.external_to_node = to_node_id
+        self.from_node_id = from_node_id
+        self.to_node_id = to_node_id
         # length is mile or km
         self.length = length
         self.lanes = lanes
@@ -117,10 +117,10 @@ def get_seq_no(self):
         return self.link_seq_no
 
     def get_from_node_id(self):
-        return self.external_from_node
+        return self.from_node_id
 
     def get_to_node_id(self):
-        return self.external_to_node
+        return self.to_node_id
 
     def get_length(self):
         return self.length
@@ -257,9 +257,9 @@ def __init__(self):
         self.link_size = 0
         self.agent_size = 0
         # key: node id, value: node seq no
-        self.internal_node_seq_no_dict = {}
+        self.node_id_to_no_dict = {}
         # key: node seq no, value: node id
-        self.external_node_id_dict = {}
+        self.node_no_to_id_dict = {}
         # map link id to link seq no
         self.link_id_dict = {}
         # td:time-dependent, key:simulation time interval,
@@ -464,7 +464,7 @@ def get_agent_node_path(self, agent_id, path_only):
         path = ''
         if agent.node_path:
             path = ';'.join(
-                str(self.external_node_id_dict[x]) for x in reversed(agent.node_path)
+                str(self.node_no_to_id_dict[x]) for x in reversed(agent.node_path)
             )
 
         if path_only:
@@ -517,7 +517,7 @@ def get_nodes_from_zone(self, zone_id):
         return self.zone_to_nodes_dict[zone_id]
 
     def get_node_no(self, node_id):
-        return self.internal_node_seq_no_dict[node_id]
+        return self.node_id_to_no_dict[node_id]
 
     def get_node_size(self):
         return self.node_size
@@ -953,8 +953,8 @@ def __init__(self, base, add_cc=True):
         self.base = base
         self.node_list = self.base.get_nodes()
         self.link_list = self.base.get_links()
-        self.map_id_to_no = self.base.internal_node_seq_no_dict
-        self.map_no_to_id = self.base.external_node_id_dict
+        self.map_id_to_no = self.base.node_id_to_no_dict
+        self.map_no_to_id = self.base.node_no_to_id_dict
         self.node_size = base.get_node_size()
         self.link_size = base.get_link_size()
         self.centroids = []
@@ -1402,7 +1402,7 @@ def get_node_label_cost(self, node_no):
 
     def get_accessible_nodes(self, source_node_id, time_budget,
                              mode, time_dependent, tau):
-        if source_node_id not in self.network.internal_node_seq_no_dict.keys():
+        if source_node_id not in self.network.node_id_to_no_dict.keys():
             raise Exception(f"Node ID: {source_node_id} not in the network")
 
         assert(time_budget>=0)

path4gmns/path.py

@@ -248,7 +248,7 @@ def output_path_sequence(G, to_node_id, type='node'):
     Note that this function returns GENERATOR rather than list.
     """
     path = []
-    current_node_seq_no = G.internal_node_seq_no_dict[to_node_id]
+    current_node_seq_no = G.node_id_to_no_dict[to_node_id]
 
     if type.startswith('node'):
         # retrieve the sequence backwards
@@ -257,7 +257,7 @@ def output_path_sequence(G, to_node_id, type='node'):
             current_node_seq_no = G.node_predecessor[current_node_seq_no]
         # reverse the sequence
         for node_seq_no in reversed(path):
-            yield G.external_node_id_dict[node_seq_no]
+            yield G.node_no_to_id_dict[node_seq_no]
     else:
         # retrieve the sequence backwards
         current_link_seq_no = G.link_predecessor[current_node_seq_no]
@@ -271,15 +271,15 @@ def output_path_sequence(G, to_node_id, type='node'):
 
 
 def _get_path_cost(G, to_node_id):
-    to_node_no = G.internal_node_seq_no_dict[to_node_id]
+    to_node_no = G.node_id_to_no_dict[to_node_id]
 
     return G.node_label_cost[to_node_no]
 
 
 def find_shortest_path(G, from_node_id, to_node_id, seq_type='node'):
-    if from_node_id not in G.internal_node_seq_no_dict.keys():
+    if from_node_id not in G.node_id_to_no_dict.keys():
         raise Exception(f"Node ID: {from_node_id} not in the network")
-    if to_node_id not in G.internal_node_seq_no_dict.keys():
+    if to_node_id not in G.node_id_to_no_dict.keys():
         raise Exception(f"Node ID: {to_node_id} not in the network")
 
     single_source_shortest_path(G, from_node_id, engine_type='c')
@@ -319,9 +319,9 @@ def find_path_for_agents(G, column_pool, engine_type='c'):
         if from_node_id == to_node_id:
             continue
 
-        if from_node_id not in G.internal_node_seq_no_dict.keys():
+        if from_node_id not in G.node_id_to_no_dict.keys():
             raise Exception(f"Node ID: {from_node_id} not in the network")
-        if to_node_id not in G.internal_node_seq_no_dict.keys():
+        if to_node_id not in G.node_id_to_no_dict.keys():
             raise Exception(f"Node ID: {to_node_id} not in the network")
 
         # simple caching strategy
@@ -334,7 +334,7 @@ def find_path_for_agents(G, column_pool, engine_type='c'):
         node_path = []
         link_path = []
 
-        current_node_seq_no = G.internal_node_seq_no_dict[to_node_id]
+        current_node_seq_no = G.node_id_to_no_dict[to_node_id]
         # set up the cost
         agent.path_cost = G.node_label_cost[current_node_seq_no]
 

path4gmns/utils.py

@@ -555,14 +555,14 @@ def read_network(load_demand='true', input_dir='.'):
 
     read_nodes(input_dir,
                network.node_list,
-               network.internal_node_seq_no_dict,
-               network.external_node_id_dict,
+               network.node_id_to_no_dict,
+               network.node_no_to_id_dict,
                network.zone_to_nodes_dict)
 
     read_links(input_dir,
                network.link_list,
                network.node_list,
-               network.internal_node_seq_no_dict,
+               network.node_id_to_no_dict,
                network.link_id_dict,
                assignm.get_agent_type_count(),
                assignm.get_demand_period_count(),

tests/demo.py

@@ -154,10 +154,14 @@ def test_accessibility():
     # time-dependent accessibility under the default mode auto (i.e., p)
     # for demand period 0 (i.e., VDF_fftt1 in link.csv will be used in the
     # evaluation)
-    # pg.evaluate_accessiblity(network, multimodal=False, time_dependent=True)
+    # pg.evaluate_accessibility(network, multimodal=False, time_dependent=True)
+
+    # it is equivalent to
+    # pg.evaluate_accessibility(network, multimodal=False,
+    #                           time_dependent=True, demand_period_id=0)
 
     # get accessible nodes and links starting from node 1 with a 5-minitue
-    # time window for the default mode auto (i.e., 'p') for demand period 0 
+    # time window for the default mode auto (i.e., 'p') for demand period 0
     # network.get_accessible_nodes(1, 5, time_dependent=True)
 
     # get accessible nodes and links starting from node 1 with a 15-minitue
@@ -195,4 +199,4 @@ def demo_mode(mode):
 
 if __name__=="__main__":
 
-    demo_mode(3)
+    demo_mode(6)