### Install OpenMP on macOS

Source: https://path4gmns.readthedocs.io/en/latest/usecases.html

Installs the OpenMP library on macOS using Homebrew, which is required for DTALite's parallel computing features.

```bash
$ brew install libomp

```

--------------------------------

### Install libomp on macOS

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Installs the libomp library using Homebrew, which is required for DTALite's parallel computing feature on macOS.

```bash
$ brew install libomp
```

--------------------------------

### Get Accessible Nodes and Links within Time Budget

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Retrieves accessible nodes and links from a starting node within a specified time budget for a given mode. The mode must be defined in settings.yml.

```python
import path4gmns as pg

network = pg.read_network()

# get accessible nodes and links starting from node 1 with a 5-minute
# time window for the default mode auto (i.e., 'a')
network.get_accessible_nodes(1, 5)
network.get_accessible_links(1, 5)

# get accessible nodes and links starting from node 1 with a 15-minute
# time window for mode walk (i.e., 'w')
network.get_accessible_nodes(1, 15, 'w')
network.get_accessible_links(1, 15, 'w')
# the following two work equivalently as their counterparts above
# network.get_accessible_nodes(1, 15, 'walk')
# network.get_accessible_links(1, 15, 'walk')
```

--------------------------------

### Get Links

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns a list of all links in the network.

```python
return self.links
```

--------------------------------

### Get From Node Number Array

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the array containing the starting node numbers for all links.

```python
return self.from_node_no_array
```

--------------------------------

### Get Allowed Uses

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the list of allowed uses or types for agents.

```python
return self.allowed_uses
```

--------------------------------

### Get Agents

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns a list of all agent objects.

```python
return self.agents
```

--------------------------------

### Setup Shortest Path Network

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Sets up the shortest path network, optionally filtering by demand directives. Initializes SPNetwork objects for relevant agent types and demand periods.

```python
def setup_spnetwork(self, demand_directive=False):
        if self.has_created_spnet:
            return

        self.network.add_centroids_connectors()

        spvec = {}
        partial_keys = {}
        if demand_directive:
            partial_keys = {k[:3]: None for k in self.column_pool}

        # z is zone id
        for z in self.get_zones():
            if not z or not self._has_outgoing_links(z):
                continue

            for d in self.demands:
                at = self.get_agent_type(d.get_agent_type_str())
                dp = self.get_demand_period(d.get_period())
                pk = (at.get_id(), dp.get_id(), z)

                if demand_directive and pk not in partial_keys:
                    continue

                k = pk[:2]
                if k not in spvec:
                    sp = SPNetwork(self.network, at, dp)
                    spvec[k] = sp
                    sp.orig_zones.append(z)
                    self.spnetworks.append(sp)
                else:
                    sp = spvec[k]
                    sp.orig_zones.append(z)

        self.has_created_spnet = True
```

--------------------------------

### Get Nodes

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns a list of all nodes in the network.

```python
return self.nodes
```

--------------------------------

### Get Sorted Zone Keys

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns a sorted list of zone keys. Sorting is required for the setup_spnetwork() function.

```python
# sorting is needed for setup_spnetwork()
return sorted(self.zones.keys())
```

--------------------------------

### Get First Links Array

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns an array mapping each node to its first outgoing link.

```python
return self.first_link_from
```

--------------------------------

### Load Existing UE Results for ODME

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Loads network data and prepares for ODME by first loading existing UE results. This snippet is a starting point for subsequent ODME operations.

```python
import path4gmns as pg

network = pg.read_network()
```

--------------------------------

### Error Handling for Settings File

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/io.html

Handles ImportError if pyyaml is not installed and FileNotFoundError if settings.yml is missing. In both cases, it issues a warning and calls _auto_setup.

```python
    except ImportError:
        # just in case user does not have pyyaml installed
        warnings.warn(
            'Please install pyyaml next time!\n'
            'Engine will set up one demand period and one agent type using '
            'default values for you, which might NOT reflect your case!'
        )
        _auto_setup(assignment)
    except FileNotFoundError:
        # just in case user does not provide settings.yml
        warnings.warn(
            'Please provide settings.yml next time!\n'
            'Engine will set up one demand period and one agent type using '
            'default values for you, which might NOT reflect your case!'
        )
        _auto_setup(assignment)
    except Exception as e:
        raise e
```

--------------------------------

### Get Shortest Path Tree by Distance (Link Sequence)

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Retrieves the shortest path tree from a source node to all other nodes, with costs measured by distance and paths represented as link sequences. Requires network data to be loaded.

```python
# get shortest path tree (in link sequences) from node 1
# cost is measured by distance (in miles)
sp_tree_link = network.get_shortest_path_tree(1, seq_type='link', cost_type='distance')
# retrieve the shortest path from the source node (i.e., node 1) to node 2
print(f'shortest path (link id) from node 1 to node 2: {sp_tree_link[2]}')
# retrieve the shortest path from the source node (i.e., node 1) to node 3
print(f'shortest path (link id) from node 1 to node 3: {sp_tree_link[3]}')
```

--------------------------------

### Get Shortest Path Tree

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Generates the shortest path tree from a specified source node. Allows customization of mode, sequence type (node/link), and cost type (time/distance).

```python
def get_shortest_path_tree(self, from_node_id,
                               mode='all',
                               seq_type='node',
                               cost_type='time'):
        """ return the shorest path tree from the source node (from_node_id)

        Parameters
        ----------
        from_node_id
            the source (root) node id

        mode
            the target transportation mode which is defined in settings.yml. It
            can be either agent type or its name. For example, 'w' and 'walk'
            are equivalent inputs.

            The default is 'all', which means that links are open to all modes.

        seq_type
            'node' or 'link'. You will get the shortest path in sequence of
            either node IDs or link IDs. The default is 'node'.

        cost_type
            'time' or 'distance'. find the shortest path according travel time
            or travel distance.

        Returns
        -------
        dictionary
            shortest paths from the source node to any other nodes (the
            source node itself is excluded).

            key is to_node_id and value is the corresponding shortest path
            information including path cost and path details (as a tuple).

            path cost and path details are in line with the specified
            cost_type and seq_type.
        """

        return self._base_assignment.get_shortest_path_tree(
            from_node_id, mode, seq_type, cost_type
        )
```

--------------------------------

### Get Shortest Path Tree by Distance

Source: https://path4gmns.readthedocs.io/en/latest/usecases.html

Calculates the shortest path tree from a source node using distance as the cost. Supports both node and link sequence outputs.

```python
import path4gmns as pg

network = pg.read_network()

# get shortest path tree (in node sequences) from node 1
# cost is measured by distance (in miles)
sp_tree_node = network.get_shortest_path_tree(1, cost_type='distance')
# retrieve the shortest path from the source node (i.e., node 1) to node 2
print(f'shortest path (node id) from node 1 to node 2: {sp_tree_node[2]}')
# retrieve the shortest path from the source node (i.e., node 1) to node 3
print(f'shortest path (node id) from node 1 to node 3: {sp_tree_node[3]}')

# get shortest path tree (in link sequences) from node 1
# cost is measured by distance (in miles)
sp_tree_link = network.get_shortest_path_tree(1, seq_type='link', cost_type='distance')
# retrieve the shortest path from the source node (i.e., node 1) to node 2
print(f'shortest path (link id) from node 1 to node 2: {sp_tree_link[2]}')
# retrieve the shortest path from the source node (i.e., node 1) to node 3
print(f'shortest path (link id) from node 1 to node 3: {sp_tree_link[3]}')
```

--------------------------------

### setup_spnetwork

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Sets up the shortest path network, optionally with demand directives.

```APIDOC
## setup_spnetwork

### Description
Initializes and configures the shortest path network. This method should be called before performing shortest path calculations.

### Parameters
- **demand_directive** (boolean): If true, sets up the network considering demand directives. Defaults to false.
```

--------------------------------

### Setup Agents

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Sets up agents based on OD volume data. It iterates through column pool entries, creates Agent objects, and assigns random origin and destination nodes within their respective zones. The number of agents created is printed upon completion.

```python
def setup_agents(self, column_pool):
        agent_id = 1
        agent_no = 0

        for k, cv in column_pool.items():
            if cv.get_od_volume() <= 0:
                continue

            # k= (at, dp, orig, dest)
            at = k[0]
            dp = k[1]
            oz = k[2]
            dz = k[3]

            vol = int(cv.get_od_volume()+1)
            for _ in range(vol):
                # construct agent using valid record
                agent = Agent(agent_id,
                              agent_no,
                              at,
                              dp,
                              oz,
                              dz)

                # step 1 generate o_node_id and d_node_id randomly
                # according to o_zone_id and d_zone_id
                agent.o_node_id = choice(
                    self.zones[oz].get_nodes()
                )
                agent.d_node_id = choice(
                    self.zones[dz].get_nodes()
                )

                # step 2 update agent_id and agent_no
                agent_id += 1
                agent_no += 1

                self.agents.append(agent)

        print(f'the number of agents is {len(self.agents)}')
```

--------------------------------

### path4gmns.utils.download_sample_setting_file

Source: https://path4gmns.readthedocs.io/en/latest/api.html

Downloads the sample settings.yml file from the Github repository. This file can be used as a template for configuring Path4GMNS.

```APIDOC
## path4gmns.utils.download_sample_setting_file

### Description
Downloads the sample settings.yml from the Github repo.

### Returns
None
```

--------------------------------

### Get Agent Path and Cost

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Retrieves the path and its associated cost for a given agent. Returns infinity if the path cost exceeds a maximum threshold. Formats the output string based on the cost type.

```python
agent = self._get_agent(agent_no)

path_cost = agent.get_path_cost()
if path_cost >= MAX_LABEL_COST:
    return f'path {cost_type}: infinity | path: '

path = ''
if agent.node_path:
    path = ';'.join(
        self.map_no_to_id[x] for x in reversed(agent.node_path)
    )

if path_only:
    return path
else:
    unit = 'minutes'
    if cost_type.startswith('dis'):
        unit = self.get_length_unit() + 's'

    return f'path {cost_type}: {path_cost:.4f} {unit} | node path: {path}'
```

--------------------------------

### Initialize Simulation

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Initializes the simulation by creating agents based on loading profiles and setting up network parameters. Supports 'constant', 'random', and 'uniform' loading profiles.

```python
def initialize_simulation(self, loading_profile):
 profiles = ['constant', 'random', 'uniform']
 if loading_profile not in profiles:
 Warning.warn(
 f'{loading_profile} is not supported!'
 ' constant loading profile will be adopted.'
 )

 agent_id = 1
 links = self.get_links()
 column_pool = self.get_column_pool()

 for k, cv in column_pool.items():
 if cv.get_od_volume() <= 0:
 continue

 # k= (at, dp, orig, dest)
 at = k[0]
 dp = k[1]
 oz = k[2]
 dz = k[3]

 for col in cv.get_columns():
 if col.nodes is None:
 continue

 # link volume is already set up in UE
 vol = ceil(col.get_volume())
 for j in range(vol):
 agent = Agent(agent_id, agent_id - 1, at, dp, oz, dz)

 n = col.get_link_num()
 agent.curr_link_pos = n - 1
 agent.link_arr_interval = [-1] * n
 agent.link_dep_interval = [-1] * n

 # constant departure time by default
 t = self.simu_st
 if loading_profile.startswith('uniform'):
 t += int(j / col.get_volume() * self.simu_dur)
 elif loading_profile.startswith('random'):
 t += randint(0, self.simu_dur - 1)

 # simulation interval
 i = self.cast_minute_to_interval(t - self.simu_st)
 agent.link_arr_interval[-1] = i
 agent.dep_time = t

 # set up node path and link path
 agent.link_path = [x for x in col.links]
 agent.node_path = [x for x in col.nodes]
 agent.path_cost = col.get_distance()
 if i not in self.network.td_agents:
 self.network.td_agents[i] = []
 self.network.td_agents[i].append(agent.get_seq_no())
 self.network.agents.append(agent)

 agent_id += 1

 # replicate _update_link_travel_time_and_cost()
 for link in links:
 if link.length == 0:
 continue

 # link_capacity is for one hour, i.e., 3600 s
 cap = ceil(link.link_capacity / SECONDS_IN_HOUR * self.simu_rez)
 n1 = self.get_total_simu_intervals()
 n2 = self.get_simu_duration()

 link.outflow_cap = [cap] * n1
 link.cum_arr = [0] * n1
 link.cum_dep = [0] * n1
 # waiting time in terms of simulation interval
 link.waiting_time = [0] * n2
```

--------------------------------

### Calculate Shortest Path Distance

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Computes the shortest path distance from a starting point to a given node number. It iteratively sums link lengths by traversing predecessor links until the start is reached or no predecessor exists.

```python
def get_sp_distance(self, node_no):
    """ get the shortest path distance """
    if self.link_preds[node_no] == -1:
        return MAX_LABEL_COST

    dist = 0
    while node_no >= 0:
        link_no = self.link_preds[node_no]
        if link_no >= 0:
            dist += self.get_link(link_no).get_length()

        node_no = self.node_preds[node_no]

    return dist
```

--------------------------------

### Auto-Setup Demand Period and Agent Type

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/io.html

Automatically sets up a default demand period and agent type for the assignment. This is useful for initial configuration.

```python
def _auto_setup(assignment):
    """ automatically set up one demand period and one agent type

    The two objects will be set up using the default constructors using the
    default values. See class DemandPeriod and class AgentType for details
    """
    at = AgentType()
    dp = DemandPeriod()
    d = Demand()

    assignment.update_agent_types(at)
    assignment.update_demand_periods(dp)
    assignment.update_demands(d)
```

--------------------------------

### Synthesize Zones and OD Demand

Source: https://path4gmns.readthedocs.io/en/latest/usecases.html

Demonstrates how to explicitly synthesize zones and OD demand when zone information is not provided. This involves allocating total demand proportionally to synthesized zones based on their activity nodes.

```python
import path4gmns as pg

network = pg.read_network()

print('\nstart zone synthesis')
st = time()

```

--------------------------------

### get_shortest_path_tree

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Retrieves the shortest path tree starting from a given node.

```APIDOC
## get_shortest_path_tree

### Description
Retrieves the shortest path tree originating from a specified node.

### Parameters
- **from_node_id** (string): The ID of the starting node.
- **mode**: The mode of transportation.
- **seq_type**: The type of sequence.
- **cost_type**: The type of cost to consider.
```

--------------------------------

### Get Zone Size

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the total number of zones in the network.

```python
return len(self.zone_)
```

--------------------------------

### Agent Class Initialization and Getters

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Initializes an Agent object with its ID, type, origin-destination information, and path details. Provides getter methods for various agent attributes.

```python
    def __init__(self, agent_id, agent_no, agent_type_id,
                 demand_period_id, o_zone_id, d_zone_id):
        """ the attribute of agent """
        self.id = agent_id
        self.seq_no = agent_no
        # vehicle
        self.at_id = agent_type_id
        self.dp_id = demand_period_id
        self.o_zone_id = o_zone_id
        self.d_zone_id = d_zone_id
        self.o_node_id = 0
        self.d_node_id = 0
        self.node_path = None
        self.link_path = None
        # Passenger Car Equivalent (PCE) of the agent
        self.PCE_factor = 1
        self.path_cost = 0
        # for simulation
        self.dep_time = 0
        # corresponding to each link along the link path
        self.link_dep_interval = None
        self.link_arr_interval = None
        self.curr_link_pos = 0

    def get_orig_node_id(self):
        return self.o_node_id

    def get_dest_node_id(self):
        return self.d_node_id

    def get_seq_no(self):
        return self.seq_no

    def get_id(self):
        return self.id

    def get_orig_zone_id(self):
        return self.o_zone_id

    def get_dest_zone_id(self):
        return self.d_zone_id

    def get_path_cost(self):
        return self.path_cost

    def get_node_path(self):
        return self.node_path

    def get_at_id(self):
        return self.at_id

    def get_dp_id(self):
        return self.dp_id

    def get_od(self):
        return self.o_zone_id, self.d_zone_id
```

--------------------------------

### Path-Based UE Assignment from Loaded Columns

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Continues a path-based User Equilibrium assignment by loading existing columns (paths) from files. Set column generation to 0 to skip this stage. Requires network data to be loaded.

```python
import path4gmns as pg

# no need to load demand file as we will infer the demand from columns
network = pg.read_network()
# you can specify the input directory
# e.g., pg.load_columns(network, 'data/Chicago_Sketch')
pg.load_columns(network)

# we recommend NOT doing assignment again after loading columns
column_gen_num = 0
column_upd_num = 20

pg.find_ue(network, column_gen_num, column_upd_num)

pg.output_columns(network)
pg.output_link_performance(network)
```

--------------------------------

### Get Link Size

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the total number of links in the network.

```python
return len(self.links)
```

--------------------------------

### Get Node Size

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the total number of nodes in the network.

```python
return len(self.nodes)
```

--------------------------------

### Zone Class Initialization

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Initializes a Zone object with its ID, bin index, and attributes related to production, centroid, boundaries, and coordinates. Includes fields for ODME calculations.

```python
    def __init__(self, zone_id, bin_index=0):
        self.no = -1
        self.id = str(zone_id)
        self.bin_id = bin_index
        self.production = 0
        self.centroid = None
        self.boundaries = []
        self.coord_x = 91
        self.coord_y = 181
        self.nodes = []
        self.activity_nodes = []
        # for ODME
        self.prod_obs = 0
        self.attr_obs = 0
        self.attr_est = 0
        self.prod_est = 0
        self.prod_est_dev = 0
        self.attr_est_dev = 0
        self.is_prod_obs_upper_bounded = False
        self.is_attr_obs_upper_bounded = False
```

--------------------------------

### Get Time-Dependent Agents

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Retrieves time-dependent agents associated with a given index `i`.

```python
return self.td_agents[i]
```

--------------------------------

### Time Conversion Methods

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Provides methods for converting between simulation intervals and minutes, both as integers and floating-point numbers. These are essential for time-based calculations within the simulation.

```python
def cast_interval_to_minute(self, i):
 return floor(i * self.simu_rez / SECONDS_IN_MINUTE)
```

```python
def cast_interval_to_minute_float(self, i):
 return i * self.simu_rez / SECONDS_IN_MINUTE
```

```python
def cast_minute_to_interval(self, m):
 return floor(m * SECONDS_IN_MINUTE / self.simu_rez)
```

--------------------------------

### Link-Based UE with Default Settings

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Performs a link-based UE assignment using the Frank-Wolfe algorithm with default parameters for maximum iterations and relative gap tolerance.

```python
import path4gmns as pg

network = pg.read_network()
pg.read_demand(network)

pg.find_ue_fw(network)
pg.output_link_performance(network)

# NOTE that pg.output_columns(network) is NOT available under the link-based UE!
```

--------------------------------

### Get Link Costs Array

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the array containing costs for all links.

```python
return self.link_cost_array
```

--------------------------------

### Find Path for Agents

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Finds and sets up the shortest path for each agent in the network. Resets agent type string or mode according to user input.

```python
def find_path_for_agents(self, mode, cost_type):
        """ find and set up shortest path for each agent """
        # reset agent type str or mode according to user's input
        at_name, _ = self._convert_mode(mode)
        self.network.set_agent_type_name(at_name)

        find_path_for_agents(self.network, self.column_pool, cost_type)
```

--------------------------------

### Get Link Predecessors

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns a data structure representing the predecessors for each link.

```python
return self.link_preds
```

--------------------------------

### Get Node Predecessors

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns a data structure representing the predecessors for each node.

```python
return self.node_preds
```

--------------------------------

### Assignment Class Initialization

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Initializes the Assignment class, setting up empty lists for agent types, demand periods, and demands. It also initializes a dictionary for column pooling and placeholders for network and shortest path network instances.

```python
class Assignment:

    def __init__(self):
        self.agent_types = []
        self.demand_periods = []
        self.demands = []
        # 4-d array
        # the insertion order is conserved starting from Python 3.6
        self.column_pool = {}
        # base physical network
        self.network = None
        # SPNetwork instance for computing shortest paths only
        self.spnet = None
        self.spnetworks = []
        self.accessnetwork = None
```

--------------------------------

### Get Nodes from Zone

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Retrieves all nodes associated with a specific zone ID.

```python
return self.zones[zone_id].get_nodes()
```

--------------------------------

### Find Path for Agents (Deprecated)

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Deprecated method to find and set up shortest paths for agents. It sets the agent cost type and calls the base assignment's pathfinding method.

```python
def find_path_for_agents(self, mode='all', cost_type='time'):
        """ DEPRECATED

        find and set up shortest path for each agent

        Parameters
        ----------
        mode
            the target transportation mode which is defined in settings.yml. It
            can be either agent type or its name. For example, 'w' and 'walk'
            are equivalent inputs.

            The default is 'all', which means that links are open to all modes.

        cost_type
            'time' or 'distance'. find the shortest path according travel time
            or travel distance.

        Returns
        -------
        None
        """
        self._agent_cost_type = cost_type
        return self._base_assignment.find_path_for_agents(mode, cost_type)
```

--------------------------------

### Get Agent Count

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the total number of agents managed by the network.

```python
return len(self.agents)
```

--------------------------------

### Get Centroids from Zones

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Yields the centroid of each zone, skipping zones with empty keys.

```python
for k, v in self.zones.items():
    if not k:
        continue

    yield v.get_centroid()
```

--------------------------------

### Get Last Through Node

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the node number of the last potential centroid in the network.

```python
return self.last_thru_node
```

--------------------------------

### Get Shortest Path Tree by Mode and Time (Node Sequence)

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Calculates the shortest path tree from a source node considering a specific travel mode and cost measured by time. Paths are returned as node sequences. Requires network and settings.yml to be configured.

```python
import path4gmns as pg

network = pg.read_network()

# get shortest path tree (in node sequences) from node 1 under mode 'w'
# cost is measured by time (in minutes)
sp_tree_node = network.get_shortest_path_tree(1, mode='w')
# retrieve the shortest path from the source node (i.e., node 1) to node 2
print(f'shortest path (node id) from node 1 to node 2: {sp_tree_node[2]}')
# retrieve the shortest path from the source node (i.e., node 1) to node 3
print(f'shortest path (node id) from node 1 to node 3: {sp_tree_node[3]}')
```

--------------------------------

### Get Queue Next

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the data structure representing the next elements in a queue.

```python
return self.queue_next
```

--------------------------------

### Get Shortest Path Tree by Mode and Distance (Link Sequence)

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Calculates the shortest path tree from a source node considering a specific travel mode and cost measured by distance. Paths are returned as link sequences. Requires network and settings.yml to be configured.

```python
# get shortest path tree (in link sequences) from node 1 under mode 'w'
# cost is measured by distance
sp_tree_link = network.get_shortest_path_tree(1, mode='w', seq_type='link', cost_type='distance')
# retrieve the shortest path from the source node (i.e., node 1) to node 2
print(f'shortest path (link id) from node 1 to node 2: {sp_tree_link[2]}')
# retrieve the shortest path from the source node (i.e., node 1) to node 3
print(f'shortest path (link id) from node 1 to node 3: {sp_tree_link[3]}')
```

--------------------------------

### Get Node Label Costs

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the array containing label costs for all nodes.

```python
return self.node_label_cost
```

--------------------------------

### DTALite Classic for Path-Based UE

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Executes a path-based UE assignment using DTALiteClassic with specified column generation and update numbers. Network and demand loading are handled internally by DTALite.

```python
import path4gmns as pg

# no need to call read_network() like the python module
# as network and demand loading will be handled within DTALite

# path-based UE
mode = 1
column_gen_num = 20
column_upd_num = 20

pg.DTALiteClassic(mode, column_gen_num, column_upd_num)

# no need to call output_columns() and output_link_performance()
# since outputs will be processed within DTalite

print('\npath finding results can be found in route_assignment.csv')
```

--------------------------------

### Get Agent Link Path

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the sequence of link IDs representing the path of an agent.

```python
def get_agent_link_path(self, agent_id):
        """ return the sequence of link IDs along the agent path """
        return self._base_assignment.get_agent_link_path(agent_id, self._agent_cost_type)
```

--------------------------------

### Initialize Link Costs

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Initializes link costs based on the specified cost type ('time' or 'length'). This method prepares the link cost array for use in calculations.

```python
def init_link_costs(self, cost_type='time'):
        if cost_type == 'time':
            link_costs = [link.fftt for link in self.links]
        else:
            link_costs = [link.length for link in self.links]

        double_arr_link = ctypes.c_double * self.get_link_size()
        self.link_cost_array = double_arr_link(*link_costs)
```

--------------------------------

### Get Node Label Cost

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Retrieves the cost associated with a node label from the access network.

```python
def get_node_label_cost(self, node_no):
        return self.accessnetwork.get_node_label_cost(node_no)
```

--------------------------------

### Get Node Number by ID

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Retrieves the node sequence number using its integer ID.

```python
def get_node_no(self, id):
        """ id is integer """
        return self.network.get_node_no(id)
```

--------------------------------

### Agent Class Path and Time Update Methods

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Manages agent's movement along a path by updating link departure and arrival intervals, current link position, and retrieving time-related information.

```python
    def update_dep_interval(self, intvl):
        self.link_dep_interval[self.curr_link_pos] = (
            self.link_arr_interval[self.curr_link_pos] + intvl
        )

    def get_curr_dep_interval(self):
        return self.link_dep_interval[self.curr_link_pos]

    def reached_last_link(self):
        return self.curr_link_pos == 0

    def get_next_link_no(self):
        pos = self.curr_link_pos - 1
        return self.link_path[pos]

    def set_dep_interval(self, i):
        self.link_dep_interval[self.curr_link_pos] = i

    def set_arr_interval(self, i, increment=0):
        self.link_arr_interval[self.curr_link_pos-increment] = i

    def get_arr_interval(self):
        return self.link_arr_interval[self.curr_link_pos]

    def increment_link_pos(self):
        if self.curr_link_pos > 0:
            self.curr_link_pos -= 1

    def get_dep_time(self):
        return self.dep_time

    def get_origin_dep_interval(self):
        return self.link_arr_interval[-1]
```

--------------------------------

### Retrieve Shortest Path Tree (Link Sequences)

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Generates the shortest path tree from a source node, returning paths as link sequences. Allows retrieval of the shortest path to any other node.

```python
import path4gmns as pg

network = pg.read_network()

# get shortest path tree (in link sequences) from node 1
# cost is measured by time (in minutes)
sp_tree_link = network.get_shortest_path_tree(1, seq_type='link')
# retrieve the shortest path from the source node (i.e., node 1) to node 2
print(f'shortest path (link id) from node 1 to node 2: {sp_tree_link[2]}')
```

--------------------------------

### Get Link Number by ID

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Retrieves the link sequence number using its string ID.

```python
def get_link_no(self, id):
        """ id is string """
        return self.network.get_link_no(id)
```

--------------------------------

### Get Length Unit

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the unit of length used in the network (e.g., 'meters', 'kilometers').

```python
return self.len_unit
```

--------------------------------

### Get Link Number from ID

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Converts a link ID to its corresponding internal sequence number.

```python
return self.link_ids[id]
```

--------------------------------

### Dynamic Traffic Simulation with Pre-loaded UE Results

Source: https://path4gmns.readthedocs.io/en/latest/usecases.html

Conduct dynamic traffic simulation by loading existing User Equilibrium (UE) results from a file, bypassing the UE calculation step. This is useful if you have route_assignment.csv from a previous run or DTALite.

```python
import path4gmns as pg

# no need to load demand file as we will infer the demand from columns
network = pg.read_network()

# load existing UE result
pg.load_columns(network)

# DTA
pg.perform_simple_simulation(network)
print('complete dynamic simulation.\n')

print('writing agent trajectories')
pg.output_agent_trajectory(network)

```

--------------------------------

### Get Link by Sequence Number

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Retrieves a specific link object using its sequence number.

```python
return self.links[seq_no]
```

--------------------------------

### DemandPeriod Class Initialization and Time Parsing

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Defines a demand period with an ID, period name, and time range. It includes logic to parse the time period string into start and end times in minutes, with backward compatibility for different delimiters.

```python
    def __init__(self, id=0, period='AM', time_period='0700-0800'):
        self.id = id
        self.period = period
        self.time_period = time_period
        self.special_event = None
        self._setup_time()

    def _parse_time_period(self, delim='-'):
        s1, s2 = self.time_period.split(delim)
        t1 = datetime.strptime(s1, '%H%M')
        t2 = datetime.strptime(s2, '%H%M')
        if t2 <= t1:
            raise ValueError('ending time <= starting time')

        st_ = t1.hour * 60 + t1.minute
        et_ = t2.hour * 60 + t2.minute

        return st_, et_

    def _setup_time(self):
        try:
            st_, et_ = self._parse_time_period()
        except ValueError:
            # backward compatibility for versions <= v0.9.3
            st_, et_ = self._parse_time_period('_')
        except Exception as e:
            raise e

        self.st = st_
        self.et = et_

    def get_id(self):
        return self.id

    def get_period(self):

```

--------------------------------

### Get Last Links Array

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns an array mapping each node to its last outgoing link.

```python
return self.last_link_from
```

--------------------------------

### Retrieve Shortest Path Tree (Node Sequences)

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Generates the shortest path tree from a source node, returning paths as node sequences. Allows retrieval of the shortest path to any other node.

```python
import path4gmns as pg

network = pg.read_network()

# get shortest path tree (in node sequences) from node 1
# cost is measured by time (in minutes)
sp_tree_node = network.get_shortest_path_tree(1)
# retrieve the shortest path from the source node (i.e., node 1) to node 2
print(f'shortest path (node id) from node 1 to node 2: {sp_tree_node[2]}')
```

```python
import path4gmns as pg

network = pg.read_network()

# get shortest path tree (in node sequences) from node 1
# cost is measured by time (in minutes)
sp_tree_node = network.get_shortest_path_tree(1)
# retrieve the shortest path from the source node (i.e., node 1) to node 3
print(f'shortest path (node id) from node 1 to node 3: {sp_tree_node[3]}')
```

--------------------------------

### Get Accessible Nodes

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Calculates and returns nodes accessible from a source node within a given time budget. Includes caching for shortest path calculations and updates link costs based on agent type and time dependency.

```python
def get_accessible_nodes(self, source_node_id, time_budget,
                             mode, time_dependent, tau):
        source_node_id = str(source_node_id)
        if source_node_id not in self.network.map_id_to_no:
            raise Exception(f'Node ID: {source_node_id} not in the network')

        if time_budget <= 0:
            return []

        if not self.accessnetwork:
            self.accessnetwork = AccessNetwork(self.network, False)

        # simple caching to avoid duplicate shortest path calculation
        run_sp = False
        if self.accessnetwork.pre_source_node_id != source_node_id:
            self.accessnetwork.set_source_node_id(source_node_id)
            run_sp = True

        at_name, at_str = self._convert_mode(mode)
        if self.accessnetwork.agent_type_name != at_name:
            self.accessnetwork.set_target_mode(at_name)
            at = self.get_agent_type(at_str)
            self.accessnetwork.update_generalized_link_cost(at,
                                                            time_dependent,
                                                            tau)
            run_sp = True

        if run_sp:
            single_source_shortest_path(self.accessnetwork, source_node_id)

        # if max min travel time is less than or equal to time_budget,
        # output the entire node set directly without the following check?
        nodes = []
        for node in self.accessnetwork.get_nodes():
            # do not include the source node itself
```

--------------------------------

### Get To Node Number Array

Source: https://path4gmns.readthedocs.io/en/latest/_modules/path4gmns/classes.html

Returns the array containing the ending node numbers for all links.

```python
return self.to_node_no_array
```

--------------------------------

### Perform Accessibility Evaluation (Default Mode)

Source: https://path4gmns.readthedocs.io/en/latest/_sources/usecases.md.txt

Initiates accessibility evaluation for the network. By default, it evaluates for the 'auto' mode. Demand files are not required for this evaluation.

```python
import path4gmns as pg
from time import time

network = pg.read_network()

print('\nstart accessibility evaluation\n')
st = time()
# no need to load demand file for accessibility evaluation
pg.evaluate_accessibility(network)

print('complete accessibility evaluation.\n')
print(f'processing time of accessibility evaluation: {time()-st:.2f} s')
```

--------------------------------

### ODME with Existing UE Results

Source: https://path4gmns.readthedocs.io/en/latest/usecases.html

Loads existing UE results and then performs ODME to calibrate them using traffic count observations. This is useful when UE has already been computed.

```python
import path4gmns as pg

network = pg.read_network()
# load existing UE result
pg.load_columns(network)

# ODME
odme_upd_num = 20
pg.read_measurements(network)
pg.conduct_odme(network, odme_upd_num)

# output column information to route_assignment.csv
pg.output_columns(network)

```