Merge branch 'develop' of github.com:AequilibraE/aequilibrae into rou…

…te_choice

# Conflicts:
#	setup.py

.github/build_artifacts_qgis.yml

@@ -19,7 +19,7 @@ jobs:
         architecture: ['x64']
         os: [windows-latest, macos-latest]
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set Python environment
       uses: actions/setup-python@v4
       with:

.github/workflows/build_linux.yml

@@ -9,7 +9,7 @@ jobs:
       HAS_SECRETS: ${{ secrets.AWS_SECRET_ACCESS_KEY != '' }}
     continue-on-error: true
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python 3.9
       uses: actions/setup-python@v4
       with:

.github/workflows/build_mac.yml

@@ -16,7 +16,7 @@ jobs:
       matrix:
         python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set Python environment
       uses: actions/setup-python@v4
       with:

.github/workflows/build_windows.yml

@@ -13,7 +13,7 @@ jobs:
         python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
         architecture: ['x64']
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set Python environment
       uses: actions/setup-python@v4
       with:

.github/workflows/debug_tests.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-20.04
     container: python:3.9
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

.github/workflows/documentation.yml

@@ -15,7 +15,7 @@ jobs:
     env:
       HAS_SECRETS: ${{ secrets.AWS_SECRET_ACCESS_KEY != '' }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python 3.9
       uses: actions/setup-python@v4
       with:

.github/workflows/test_linux_with_coverage.yml

@@ -11,7 +11,7 @@ jobs:
       matrix:
         python-version: [3.10]
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
         sudo apt update

.github/workflows/unit_tests.yml

@@ -6,7 +6,7 @@ jobs:
   linting:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set Python environment
         uses: actions/setup-python@v4
         with:
@@ -36,7 +36,7 @@ jobs:
 
       max-parallel: 20
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set Python environment
       uses: actions/setup-python@v4
       with:

aequilibrae/matrix/aequilibrae_matrix.py

@@ -129,7 +129,6 @@ def save(self, names=(), file_name=None) -> None:
         self.computational_view(names)
 
     def __save_as(self, file_name: str, cores: List[str]):
-
         if Path(file_name).suffix.lower() == ".aem":
             mat = AequilibraeMatrix()
             args = {
@@ -250,10 +249,7 @@ def create_empty(
                         if mat_name in object.__dict__:
                             raise ValueError(mat_name + " is a reserved name")
                         if len(mat_name) > CORE_NAME_MAX_LENGTH:
-                            raise ValueError(
-                                "Matrix names need to be be shorter "
-                                "than {}: {}".format(CORE_NAME_MAX_LENGTH, mat_name)
-                            )
+                            raise ValueError(f"Matrix names need to be shorter than {CORE_NAME_MAX_LENGTH}: {mat_name}")
                     else:
                         raise ValueError("Matrix core names need to be strings: " + str(mat_name))
             else:
@@ -608,9 +604,7 @@ def __write__(self):
             np.memmap(self.file_path, dtype="uint8", offset=17, mode="r+", shape=1)[0] = data_size
 
             # matrix name
-            np.memmap(self.file_path, dtype="S" + str(MATRIX_NAME_MAX_LENGTH), offset=18, mode="r+", shape=1)[0] = (
-                self.name
-            )
+            np.memmap(self.file_path, dtype=f"S{MATRIX_NAME_MAX_LENGTH}", offset=18, mode="r+", shape=1)[0] = self.name
 
             # matrix description
             offset = 18 + MATRIX_NAME_MAX_LENGTH
@@ -1133,9 +1127,7 @@ def setName(self, matrix_name: str):
             if len(str(matrix_name)) > MATRIX_NAME_MAX_LENGTH:
                 matrix_name = str(matrix_name)[0:MATRIX_NAME_MAX_LENGTH]
 
-            np.memmap(self.file_path, dtype="S" + str(MATRIX_NAME_MAX_LENGTH), offset=18, mode="r+", shape=1)[0] = (
-                matrix_name
-            )
+            np.memmap(self.file_path, dtype=f"S{MATRIX_NAME_MAX_LENGTH}", offset=18, shape=1)[0] = matrix_name
 
     def setDescription(self, matrix_description: str):
         """

aequilibrae/paths/AoN.pyx

@@ -11,7 +11,6 @@ include 'conical.pyx'
 include 'inrets.pyx'
 include 'parallel_numpy.pyx'
 include 'path_file_saving.pyx'
-include 'graph_building.pyx'
 
 def one_to_all(origin, matrix, graph, result, aux_result, curr_thread):
     # type: (int, AequilibraeMatrix, Graph, AssignmentResults, MultiThreadedAoN, int) -> int

aequilibrae/paths/all_or_nothing.py

@@ -36,8 +36,6 @@ def __init__(self, matrix, graph, results):
         self.graph = graph
         self.results = results
         self.aux_res = MultiThreadedAoN()
-        self.report = []
-        self.cumulative = 0
 
         if results._graph_id != graph._id:
             raise ValueError("Results object not prepared. Use --> results.prepare(graph)")
@@ -55,6 +53,9 @@ def doWork(self):
         self.execute()
 
     def execute(self):
+        self.report = []
+        self.cumulative = 0
+
         if pyqt:
             self.assignment.emit(["zones finalized", 0])
 

aequilibrae/paths/graph.py

@@ -7,14 +7,30 @@
 
 import numpy as np
 import pandas as pd
-from aequilibrae.paths.AoN import build_compressed_graph
+from aequilibrae.paths.graph_building import build_compressed_graph
 
 from aequilibrae.context import get_logger
 
 
 class GraphBase(ABC):  # noqa: B024
     """
-    Graph class
+    Graph class.
+
+    AequilibraE graphs implement two forms of compression.
+        - link contraction, and
+        - dead end removal.
+
+    Link contraction creates a topological equivalent graph by contracting sequences of links between nodes
+    with degrees of two. This compresses long streams of links, such as along highways or curved roads, into single links.
+
+    Dead end removal attempts to remove dead ends and fish spines from the network. It does this based on the observation
+    that in a graph with non-negative weights a dead end will over ever appear in the results of a short(est) path if the
+    origin or destination is present within that dead end.
+
+    Dead end removal is applied before link contraction and does not create a strictly topological equivalent graph,
+    however, all centroids are preserved.
+
+    The compressed graph is used internally.
     """
 
     def __init__(self, logger=None):
@@ -77,6 +93,8 @@ def __init__(self, logger=None):
 
         self.g_link_crosswalk = np.array([])  # 4 a link ID in the BIG graph, a corresponding link in the compressed 1
 
+        self.dead_end_links = np.array([])
+
         # Randomly generate a unique Graph ID randomly
         self._id = uuid.uuid4().hex
 
@@ -170,6 +188,8 @@ def _build_directed_graph(self, network: pd.DataFrame, centroids: np.ndarray):
                 neg_names.append(name + "_ba")
         not_pos = pd.DataFrame(not_pos, copy=True)[neg_names]
         not_pos.columns = names
+
+        # Swap the a and b nodes of these edges. Direction is used for mapping the graph.graph back to the network. It does not indicate the direction of the link.
         not_pos.loc[:, "direction"] = -1
         aux = np.array(not_pos.a_node.values, copy=True)
         not_pos.loc[:, "a_node"] = not_pos.loc[:, "b_node"]