New import convention for TopoNetX

README.md

@@ -85,64 +85,53 @@ pre-commit install
 ## Example 1: creating a simplicial complex
 
 ```python
-from toponetx.classes import SimplicialComplex
+import toponetx as tnx
 
 # Instantiate a SimplicialComplex object with a few simplices
-
-sc = SimplicialComplex([[1, 2, 3], [2, 3, 4], [0, 1]])
+sc = tnx.SimplicialComplex([[1, 2, 3], [2, 3, 4], [0, 1]])
 
 # Compute the incidence matrix between 1-skeleton and 0-skeleton
-
 B1 = sc.incidence_matrix(1)
 
 # Compute the incidence matrix between 2-skeleton and 1-skeleton
-
 B2 = sc.incidence_matrix(2)
 ```
 
 ## Example 2: creating a cell complex
 
 ```python
-from toponetx.classes import CellComplex
+import toponetx as tnx
 
 # Instantiate a CellComplex object with a few cells
-
-cx = CellComplex([[1, 2, 3, 4], [3, 4, 5, 6, 7, 8]], ranks=2)
+cx = tnx.CellComplex([[1, 2, 3, 4], [3, 4, 5, 6, 7, 8]], ranks=2)
 
 # Add an edge (cell of rank 1) after initialization
-
 cx.add_edge(0, 1)
 
 # Compute the Hodge Laplacian matrix of dimension 1
-
 L1 = cx.hodge_laplacian_matrix(1)
 
 # Compute the Hodge Laplacian matrix of dimension 2
-
 L2 = cx.hodge_laplacian_matrix(2)
 ```
 
 ## Example 3: creating a combinatorial complex
 
 ```python
-from toponetx.classes import CombinatorialComplex
+import toponetx as tnx
 
 # Instantiate a combinatorial complex object with a few cells
-
-cc = CombinatorialComplex()
+cc = tnx.CombinatorialComplex()
 
 # Add some cells of different ranks after initialization
-
 cc.add_cell([1, 2, 3], rank=2)
 cc.add_cell([3, 4, 5], rank=2)
 cc.add_cells_from([[2, 3, 4, 5], [3, 4, 5, 6, 7]], ranks=3)
 
 # Compute the incidence matrix between cells of rank 0 and 2
-
 B02 = cc.incidence_matrix(0, 2)
 
 # Compute the incidence matrix between cells of rank 0 and 3
-
 B03 = cc.incidence_matrix(0, 3)
 ```
 

conftest.py

@@ -0,0 +1,31 @@
+"""Configure our testing suite."""
+
+import networkx
+import numpy
+import pytest
+
+import toponetx
+
+
+@pytest.fixture(autouse=True)
+def doctest_default_imports(doctest_namespace):
+    """Add default imports to the doctest namespace.
+
+    This fixture adds the following default imports to every doctest, so that their use
+    is consistent across all doctests without boilerplate imports polluting the
+    doctests themselves:
+
+    .. code-block:: python
+
+        import numpy as np
+        import networkx as nx
+        import toponetx as tnx
+
+    Parameters
+    ----------
+    doctest_namespace : dict
+        The namespace of the doctest.
+    """
+    doctest_namespace["np"] = numpy
+    doctest_namespace["nx"] = networkx
+    doctest_namespace["tnx"] = toponetx

toponetx/__init__.py

@@ -1,4 +1,14 @@
 """Initialize the library with modules and other content."""
+
 __version__ = "0.0.2"
 
-__all__ = ["algorithms", "classes", "datasets", "generators", "transform", "utils"]
+from toponetx.algorithms import *
+from toponetx.classes import *
+from toponetx.exception import *
+from toponetx.generators import *
+from toponetx.readwrite import *
+from toponetx.transform import *
+from toponetx.utils import *
+
+# Do not import the contents of the following modules into the global namespace:
+# from toponetx.datasets import *

toponetx/algorithms/components.py

@@ -1,4 +1,5 @@
 """Module to compute connected components on topological domains."""
+
 from collections.abc import Generator, Hashable
 from typing import Literal, TypeVar, overload
 
@@ -87,20 +88,20 @@ def s_connected_components(
 
     Examples
     --------
-    >>> CC = CellComplex()
+    >>> CC = tnx.CellComplex()
     >>> CC.add_cell([2, 3, 4], rank=2)
     >>> CC.add_cell([5, 6, 7], rank=2)
-    >>> list(s_connected_components(CC, s=1, cells=False))
+    >>> list(tnx.s_connected_components(CC, s=1, cells=False))
     [{2, 3, 4}, {5, 6, 7}]
-    >>> list(s_connected_components(CC, s=1, cells=True))
+    >>> list(tnx.s_connected_components(CC, s=1, cells=True))
     [{(2, 3), (2, 3, 4), (2, 4), (3, 4)}, {(5, 6), (5, 6, 7), (5, 7), (6, 7)}]
     >>> CHG = CC.to_colored_hypergraph()
-    >>> list(s_connected_components(CHG, s=1, cells=False))
+    >>> list(tnx.s_connected_components(CHG, s=1, cells=False))
     >>> CC.add_cell([4, 5], rank=1)
-    >>> list(s_connected_components(CC, s=1, cells=False))
+    >>> list(tnx.s_connected_components(CC, s=1, cells=False))
     [{2, 3, 4, 5, 6, 7}]
     >>> CCC = CC.to_combinatorial_complex()
-    >>> list(s_connected_components(CCC, s=1, cells=False))
+    >>> list(tnx.s_connected_components(CCC, s=1, cells=False))
     """
     if cells:
         cell_dict, A = domain.all_cell_to_node_coadjacency_matrix(s=s, index=True)
@@ -160,16 +161,16 @@ def s_component_subcomplexes(
 
     Examples
     --------
-    >>> CC = CellComplex()
+    >>> CC = tnx.CellComplex()
     >>> CC.add_cell([2, 3, 4], rank=2)
     >>> CC.add_cell([5, 6, 7], rank=2)
-    >>> list(s_component_subcomplexes(CC, 1, cells=False))
+    >>> list(tnx.s_component_subcomplexes(CC, 1, cells=False))
     >>> CCC = CC.to_combinatorial_complex()
-    >>> list(s_component_subcomplexes(CCC, s=1, cells=False))
+    >>> list(tnx.s_component_subcomplexes(CCC, s=1, cells=False))
     >>> CHG = CC.to_colored_hypergraph()
-    >>> list(s_component_subcomplexes(CHG, s=1, cells=False))
+    >>> list(tnx.s_component_subcomplexes(CHG, s=1, cells=False))
     >>> CC.add_cell([4, 5], rank=1)
-    >>> list(s_component_subcomplexes(CC, s=1, cells=False))
+    >>> list(tnx.s_component_subcomplexes(CC, s=1, cells=False))
     """
     for c in s_connected_components(
         domain, s=s, cells=cells, return_singletons=return_singletons
@@ -232,12 +233,12 @@ def connected_components(
 
     Examples
     --------
-    >>> CC = CellComplex()
+    >>> CC = tnx.CellComplex()
     >>> CC.add_cell([2, 3, 4], rank=2)
     >>> CC.add_cell([5, 6, 7], rank=2)
-    >>> list(connected_components(CC, cells=False))
+    >>> list(tnx.connected_components(CC, cells=False))
     >>> CC.add_cell([4, 5], rank=1)
-    >>> list(CC.connected_components(CC, cells=False))
+    >>> list(tnx.CC.connected_components(CC, cells=False))
     """
     yield from s_connected_components(
         domain, s=1, cells=cells, return_singletons=return_singletons
@@ -270,11 +271,11 @@ def connected_component_subcomplexes(
 
     Examples
     --------
-    >>> CC = CellComplex()
+    >>> CC = tnx.CellComplex()
     >>> CC.add_cell([2, 3, 4], rank=2)
     >>> CC.add_cell([5, 6, 7], rank=2)
-    >>> list(connected_component_subcomplexes(CC))
+    >>> list(tnx.connected_component_subcomplexes(CC))
     >>> CC.add_cell([4, 5], rank=1)
-    >>> list(connected_component_subcomplexes(CC))
+    >>> list(tnx.connected_component_subcomplexes(CC))
     """
     yield from s_component_subcomplexes(domain, return_singletons=return_singletons)

toponetx/algorithms/distance.py

@@ -1,4 +1,5 @@
 """Module to compute distance between nodes or cells on topological domains."""
+
 from collections.abc import Hashable, Iterable
 
 import networkx as nx
@@ -61,14 +62,14 @@ def distance(
 
     Examples
     --------
-    >>> CC = CellComplex()
+    >>> CC = tnx.CellComplex()
     >>> CC.add_cell([2, 3, 4], rank=2)
     >>> CC.add_cell([5, 6, 7], rank=2)
-    >>> list(node_diameters(CC))
+    >>> list(tnx.node_diameters(CC))
     >>> CCC = CC.to_combinatorial_complex()
-    >>> list(node_diameters(CCC))
+    >>> list(tnx.node_diameters(CCC))
     >>> CHG = CC.to_colored_hypergraph()
-    >>> list(node_diameters(CHG))
+    >>> list(tnx.node_diameters(CHG))
     """
     if not isinstance(domain, CellComplex | CombinatorialComplex | ColoredHyperGraph):
         raise TypeError(f"Input complex {domain} is not supported.")
@@ -137,15 +138,15 @@ def cell_distance(
 
     Examples
     --------
-    >>> CC = CellComplex()
+    >>> CC = tnx.CellComplex()
     >>> CC.add_cell([2, 3, 4], rank=2)
     >>> CC.add_cell([5, 6, 7], rank=2)
     >>> CC.add_cell([5, 2], rank=1)
-    >>> cell_distance(CC, [2, 3], [6, 7])
+    >>> tnx.cell_distance(CC, [2, 3], [6, 7])
     >>> CHG = CC.to_colored_hypergraph()
-    >>> cell_distance(CHG, (frozenset({2, 3}), 0), (frozenset({6, 7}), 0))
+    >>> tnx.cell_distance(CHG, (frozenset({2, 3}), 0), (frozenset({6, 7}), 0))
     >>> CCC = CC.to_combinatorial_complex()
-    >>> cell_distance(CCC, frozenset({2, 3}), frozenset({6, 7}))
+    >>> tnx.cell_distance(CCC, frozenset({2, 3}), frozenset({6, 7}))
     """
     if not isinstance(domain, CellComplex | CombinatorialComplex | ColoredHyperGraph):
         raise TypeError(f"Input complex {domain} is not supported.")

toponetx/algorithms/distance_measures.py

@@ -1,4 +1,5 @@
 """Module to distance measures on topological domains."""
+
 from collections.abc import Hashable
 
 import networkx as nx
@@ -31,14 +32,14 @@ def node_diameters(domain: ComplexType) -> tuple[list[int], list[set[Hashable]]]
 
     Examples
     --------
-    >>> CC = CellComplex()
+    >>> CC = tnx.CellComplex()
     >>> CC.add_cell([2, 3, 4], rank=2)
     >>> CC.add_cell([5, 6, 7], rank=2)
-    >>> list(node_diameters(CC))
+    >>> tnx.node_diameters(CC)
     >>> CCC = CC.to_combinatorial_complex()
-    >>> list(node_diameters(CCC))
+    >>> tnx.node_diameters(CCC)
     >>> CHG = CC.to_colored_hypergraph()
-    >>> list(node_diameters(CHG))
+    >>> tnx.node_diameters(CHG)
     """
     node_dict, A = domain.node_to_all_cell_adjacnecy_matrix(index=True)
     node_dict = {v: k for k, v in node_dict.items()}
@@ -79,11 +80,11 @@ def cell_diameters(domain: ComplexType, s: int = 1) -> tuple[list[int], list[set
     >>> CC = CellComplex()
     >>> CC.add_cell([2, 3, 4], rank=2)
     >>> CC.add_cell([5, 6, 7], rank=2)
-    >>> list(cell_diameters(CC))
+    >>> tnx.cell_diameters(CC)
     >>> CCC = CC.to_combinatorial_complex()
-    >>> list(cell_diameters(CCC))
+    >>> tnx.cell_diameters(CCC)
     >>> CHG = CC.to_colored_hypergraph()
-    >>> list(cell_diameters(CHG))
+    >>> tnx.cell_diameters(CHG)
     """
     if not isinstance(domain, CellComplex | CombinatorialComplex | ColoredHyperGraph):
         raise TypeError(f"Input complex {domain} is not supported.")
@@ -130,15 +131,15 @@ def diameter(domain: ComplexType) -> int:
 
     Examples
     --------
-    >>> CC = CellComplex()
+    >>> CC = tnx.CellComplex()
     >>> CC.add_cell([2, 3, 4], rank=2)
     >>> CC.add_cell([5, 6, 7], rank=2)
     >>> CC.add_cell([2, 5], rank=2)
-    >>> diameter(CC)
+    >>> tnx.diameter(CC)
     >>> CCC = CC.to_combinatorial_complex()
-    >>> diameter(CCC)
+    >>> tnx.diameter(CCC)
     >>> CHG = CC.to_colored_hypergraph()
-    >>> diameter(CHG)
+    >>> tnx.diameter(CHG)
     """
     if not isinstance(domain, CellComplex | CombinatorialComplex | ColoredHyperGraph):
         raise TypeError(f"Input complex {domain} is not supported.")
@@ -178,15 +179,15 @@ def cell_diameter(domain: ComplexType, s: int | None = None) -> int:
 
     Examples
     --------
-    >>> CC = CellComplex()
+    >>> CC = tnx.CellComplex()
     >>> CC.add_cell([2, 3, 4], rank=2)
     >>> CC.add_cell([5, 6, 7], rank=2)
     >>> CC.add_cell([2, 5], rank=1)
-    >>> cell_diameter(CC)
+    >>> tnx.cell_diameter(CC)
     >>> CCC = CC.to_combinatorial_complex()
-    >>> cell_diameter(CCC)
+    >>> tnx.cell_diameter(CCC)
     >>> CHG = CC.to_colored_hypergraph()
-    >>> cell_diameter(CHG)
+    >>> tnx.cell_diameter(CHG)
     """
     if not isinstance(domain, CellComplex | CombinatorialComplex | ColoredHyperGraph):
         raise TypeError(f"Input complex {domain} is not supported.")