topologicpy 0.8.55__py3-none-any.whl → 0.8.57__py3-none-any.whl

topologicpy/Graph.py

@@ -448,6 +448,67 @@ class Graph:
         new_graph = Graph.ByVerticesEdges(graph_vertices, graph_edges)
         return new_graph
     
+    @staticmethod
+    def AddEdgeByIndex(graph, index: list = None, dictionary = None, silent: bool = False):
+        """
+        Creates an edge in the input Graph by connecting the two vertices specified by their indices (e.g., [5, 6] connects the 4th and 6th vertices).
+
+        Parameters
+        ----------
+        graph : topologic_core.Graph
+            The input graph.
+        index : list or tuple
+            The input list of vertex indices (e.g. [4, 6]).
+        dictionary : topologic_core.Dictionary , optional
+            The input edge dictionary.
+        silent : bool , optional
+            If set to True, error and warning messages are suppressed. Default is False.
+
+        Returns
+        -------
+        topologic_core.Graph
+            The input graph with the input edge added to it.
+
+        """
+        from topologicpy.Edge import Edge
+        from topologicpy.Topology import Topology
+
+        if not Topology.IsInstance(graph, "Graph"):
+            if not silent:
+                print("Graph.AddEdgeIndex - Error: The input graph parameter is not a valid graph. Returning None.")
+            return None
+        if dictionary:
+            if not Topology.IsInstance(dictionary, "Dictionary"):
+                if not silent:
+                    print("Graph.AddEdgeIndex - Error: The input dictionary parameter is not a valid dictionary. Returning None.")
+                return None
+        if not isinstance(index, list):
+            if not silent:
+                print("Graph.AddEdgeIndex - Error: The input index parameter is not a valid list. Returning None.")
+            return None
+        index = [x for x in index if isinstance(x, int)]
+        if not len(index) == 2:
+            if not silent:
+                print("Graph.AddEdgeIndex - Error: The input index parameter should only contain two integer numbers. Returning None.")
+            return None
+        vertices = Graph.Vertices(graph)
+        n = len(vertices)
+        if index[0] < 0 or index[0] > n-1:
+            if not silent:
+                print("Graph.AddEdgeIndex - Error: The first integer in the input index parameter does not exist in the input graph. Returning None.")
+            return None
+        if index[1] < 0 or index[1] > n-1:
+            if not silent:
+                print("Graph.AddEdgeIndex - Error: The second integer in the input index parameter does not exist in the input graph. Returning None.")
+            return None
+        sv = vertices[index[0]]
+        ev = vertices[index[1]]
+        edge = Edge.ByVertices(sv, ev)
+        if dictionary:
+            edge = Topology.SetDictionary(edge, dictionary)
+        graph = Graph.AddEdge(graph,edge)
+        return graph
+
     @staticmethod
     def AddVertex(graph, vertex, tolerance: float = 0.0001, silent: bool = False):
         """
@@ -2835,6 +2896,158 @@ class Graph:
             graphs.append(Graph.ByVerticesEdges(vertices, edges))
         return {'graphs':graphs, 'labels':labels}
 
+    @staticmethod
+    def ByDictionaries(graphDictionary, vertexDictionaries, edgeDictionaries, vertexKey: str = None, edgeKey: str = None, silent: bool = False, tolerance: float = 0.0001):
+        """
+        Creates a graph from input python dictionaries.
+
+        Rules:
+        All vertex dictionaries must contain at least the vertexKey.
+        All edge dictionaries must contain at least the edgeKey.
+        The edgeKey must be a tuple or list of two str values.
+        x,y,z coordinates are optional. However, if a vertex dictionary contains x,y,z coordinates then all vertex dictionaries must contain x,y,z coordinates.
+        If vertex dictionaries contain x,y,z coordinates they must not overlap and be separated by a distance greater than tolerance.
+        Keys and values are case sensitive.
+        x,y,z keys, if present  must be lowercase.
+
+        Example:
+        graphDictionary = {"name": "Small Apartment", "location": "123 Main Street"}
+        vertexDictionaries = [
+            {"name":"Entry", "type":"Circulation", "x":1, "y":4, "z":0, "area":5},
+            {"name":"Living Room", "type":"Living Room", "x":3,  "y":4 , "z":0, "area":24},
+            {"name":"Dining Room", "type":"Dining Room", "x":5,  "y":2, "z":0,  "area":18},
+            {"name":"Kitchen", "type":"Kitchen", "x":1, "y":2, "z":0,  "area":15},
+            {"name":"Bathroom", "type":"Bathroom", "x":3, "y":6, "z":0, "area":9},
+            {"name":"Bedroom", "type":"Bedroom", "x":5, "y":4, "z":0, "area":16}
+        ]
+        edgeDictionaries = [
+            {"connects": ("Entry","Living Room"), "relationship": "adjacent_to"},
+            {"connects": ("Living Room","Kitchen"), "relationship": "adjacent_to"},
+            {"connects": ("Dining Room","Kitchen"), "relationship": "adjacent_to"},
+            {"connects": ("Living Room","Dining Room"), "relationship": "adjacent_to"},
+            {"connects": ("Living Room","Bedroom"), "relationship": "adjacent_to"},
+            {"connects": ("Living Room","Bathroom"), "relationship": "adjacent_to"}
+        ]
+        vertexKey = "name"
+        edgeKey = "connects"
+
+        Parameters
+        ----------
+        graphDictionary : dict
+            The python dictionary to associate with the resulting graph
+        vertexDictionaries : list
+            The input list of vertex dictionaries. These must contain the vertexKey. X,Y,Z coordinates are optional.
+        edgeDictionaries : list
+            The input list of edge dictionaries. These must have the edgeKey to specify the two vertices they connect (by using the vertexKey)
+        vertexKey: str
+            The vertex key used to identify which vertices and edge connects.
+        edgeKey: str
+            The edge key under which the pair of vertex keys are listed as a tuple or list.
+        tolerance: float , optional
+            The desired tolerance. The default is 0.0001
+        silent : bool , optional
+            If set to True, error and warning messages are suppressed. Default is False.
+
+        Returns
+        -------
+        topologic_core.Graph
+            The resulting graph
+
+        """
+        from topologicpy.Vertex import Vertex
+        from topologicpy.Edge import Edge
+        from topologicpy.Cluster import Cluster
+        from topologicpy.Topology import Topology
+        from topologicpy.Dictionary import Dictionary
+
+        def _set_dict(obj, kv: dict):
+            keys = list(kv.keys())
+            vals = list(kv.values())
+            d = Dictionary.ByKeysValues(keys, vals)
+            Topology.SetDictionary(obj, d)
+            return obj
+
+        def _vertex(vertexDictionary, vertices, vertexKey, tolerance=0.0001, silent=False):
+            x = vertexDictionary.get("x", 0)
+            y = vertexDictionary.get("y", 0)
+            z = vertexDictionary.get("z", 0)
+            v = Vertex.ByCoordinates(x, y, z)
+            v = _set_dict(v, vertexDictionary)
+            if "x" in vertexDictionary.keys(): # Check for overlap only if coords are given.
+                if len(vertices) > 0:
+                    nv = Vertex.NearestVertex(v, Cluster.ByTopologies(vertices))
+                    d = Topology.Dictionary(nv)
+                    nv_name = Dictionary.ValueAtKey(d, vertexKey, "Unknown")
+                    if Vertex.Distance(v, nv) < tolerance:
+                        if not silent:
+                            v_name = vertexDictionary[vertexKey]
+                            print(f"Graph.ByDictionaries - Warning: Vertices {v_name} and {nv_name} overlap.")
+            return v
+
+
+        if graphDictionary:
+            if not isinstance(graphDictionary, dict):
+                if not silent:
+                    print("Graph.ByDictionaries - Error: The input graphDictionary parameter is not a valid python dictionary. Returning None.")
+                return None
+        
+        if not isinstance(vertexDictionaries, list):
+            if not silent:    
+                print("Graph.ByDictionaries - Error: The input vertexDictionaries parameter is not a valid list. Returning None.")
+            return None
+        
+        if not isinstance(edgeDictionaries, list):
+            if not silent:    
+                print("Graph.ByDictionaries - Error: The input edgeDictionaries parameter is not a valid list. Returning None.")
+            return None
+        
+        name_to_vertex = {}
+        vertices = []
+        for vd in vertexDictionaries:
+            v = _vertex(vd, vertices, vertexKey=vertexKey, tolerance=tolerance, silent=silent)
+            if v:
+                vertices.append(v)
+
+        # If coordinates are not present, make sure you separate the vertices to allow edges to be created.
+        if "x" not in vertexDictionaries[0].keys():
+            vertices = Vertex.Separate(vertices, minDistance=max(1, tolerance))
+
+        for i, v in enumerate(vertices):
+            vd = vertexDictionaries[i]
+            name_to_vertex[vd[vertexKey]] = v
+
+        # Create adjacency edges (undirected: one edge per pair)
+        edges = []
+        for d in edgeDictionaries:
+            a, b = d[edgeKey]
+            va = name_to_vertex.get(a, None)
+            vb = name_to_vertex.get(b, None)
+            if not va and not vb:
+                if not silent:
+                    print(f"Graph.ByDictionaries - Warning: vertices '{a}' and '{b}' are missing. Could not create an edge between them.")
+                continue
+            if not va:
+                if not silent:
+                    print(f"Graph.ByDictionaries - Warning: vertex '{a}' is missing. Could not create an edge between '{a}' and '{b}'.")
+                continue
+            if not vb:
+                if not silent:
+                    print(f"Graph.ByDictionaries - Warning: vertex '{b}' is missing. Could not create an edge between '{a}' and '{b}'.")
+                continue
+            e = Edge.ByStartVertexEndVertex(va, vb, silent=True)
+            if not e:
+                if not silent:
+                    print(f"Graph.ByDictionaries - Warning: Could not create an edge between '{a}' and '{b}'. Check if the distance betwen '{a}' and '{b}' is kess than the input tolerance.")
+                continue
+            edges.append(e)
+        # Build graph
+        g = Graph.ByVerticesEdges(vertices, edges)
+
+        # Attach graph-level metadata
+        if graphDictionary:
+            _set_dict(g, graphDictionary)
+        return g
+
     @staticmethod
     def ByIFCFile(file,
                   includeTypes: list = [],
@@ -9117,8 +9330,6 @@ class Graph:
 
             return pos
 
-        
-
         def radial_layout_2d(edge_list, root_index=0):
             import numpy as np
             from collections import deque
@@ -9270,9 +9481,15 @@ class Graph:
 
         if not Topology.IsInstance(graph, "Graph"):
             if not silent:
-                print("Graph.Flatten - Error: The input graph is not a valid topologic graph. Returning None.")
+                print("Graph.Reshape - Error: The input graph is not a valid topologic graph. Returning None.")
             return None
         
+        vertices = Graph.Vertices(graph)
+        if len(vertices) < 2:
+            if not silent:
+                print("Graph.Reshape - Warning: The graph has less than two vertices. It cannot be rehsaped. Returning the original input graph.")
+            return graph
+        
         if 'circ' in shape.lower():
             return circle_layout_2d(graph, radius=size/2, sides=sides)
         elif 'lin' in shape.lower():

topologicpy/Kuzu.py

@@ -0,0 +1,589 @@
+from __future__ import annotations
+import threading, contextlib, time, json
+from typing import Dict, Any, List, Optional
+
+
+# Optional TopologicPy imports (make this file safe to import without TopologicPy)
+from topologicpy.Graph import Graph
+from topologicpy.Vertex import Vertex
+from topologicpy.Edge import Edge
+from topologicpy.Dictionary import Dictionary
+from topologicpy.Topology import Topology
+
+import os
+import warnings
+
+try:
+    import kuzu
+except:
+    print("Kuzu - Installing required kuzu library.")
+    try:
+        os.system("pip install kuzu")
+    except:
+        os.system("pip install kuzu --user")
+    try:
+        import kuzu
+    except:
+        warnings.warn("Kuzu - Error: Could not import Kuzu.")
+        kuzu = None
+
+
+class _DBCache:
+    """
+    One kuzu.Database per path. Thread-safe and process-local.
+    """
+    def __init__(self):
+        self._lock = threading.RLock()
+        self._cache: Dict[str, "kuzu.Database"] = {}
+
+    def get(self, path: str) -> "kuzu.Database":
+        if kuzu is None:
+            raise "Kuzu - Error: Kuzu is not available"
+        with self._lock:
+            db = self._cache.get(path)
+            if db is None:
+                db = kuzu.Database(path)
+                self._cache[path] = db
+            return db
+
+class _WriteGate:
+    """
+    Serialize writes to avoid IO lock contention.
+    """
+    def __init__(self):
+        self._lock = threading.RLock()
+
+    @contextlib.contextmanager
+    def hold(self):
+        with self._lock:
+            yield
+
+_db_cache = _DBCache()
+_write_gate = _WriteGate()
+
+class _ConnectionPool:
+    """
+    Per-thread kuzu.Connection pool bound to a Database instance.
+    """
+    def __init__(self, db: "kuzu.Database"):
+        self.db = db
+        self._local = threading.local()
+
+    def _ensure(self) -> "kuzu.Connection":
+        if not hasattr(self._local, "conn"):
+            self._local.conn = kuzu.Connection(self.db)
+        return self._local.conn
+
+    @contextlib.contextmanager
+    def connection(self, write: bool = False, retries: int = 5, backoff: float = 0.15):
+        conn = self._ensure()
+        if not write:
+            yield conn
+            return
+        # Serialize writes and retry transient failures
+        with _write_gate.hold():
+            attempt = 0
+            while True:
+                try:
+                    yield conn
+                    break
+                except Exception as e:
+                    attempt += 1
+                    if attempt > retries:
+                        raise f"Kuzu write failed after {retries} retries: {e}"
+                    time.sleep(backoff * attempt)
+
+class _Mgr:
+    """
+    Lightweight facade (per-db-path) providing read/write execution and schema bootstrap.
+    """
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        self._db = _db_cache.get(db_path)
+        self._pool = _ConnectionPool(self._db)
+
+    @contextlib.contextmanager
+    def read(self):
+        with self._pool.connection(write=False) as c:
+            yield c
+
+    @contextlib.contextmanager
+    def write(self):
+        with self._pool.connection(write=True) as c:
+            yield c
+
+    def exec(self, query: str, params: Optional[dict] = None, write: bool = False):
+        with (self.write() if write else self.read()) as c:
+            with c.execute(query, parameters=params or {}) as res:
+                try:
+                    return res.rows_as_dict().get_all()
+                except Exception:
+                    return None
+
+    def ensure_schema(self):
+        # Node tables
+        self.exec("""
+        CREATE NODE TABLE IF NOT EXISTS GraphCard(
+            id STRING,
+            label STRING,
+            num_nodes INT64,
+            num_edges INT64,
+            props STRING,
+            PRIMARY KEY(id)
+        );
+        """, write=True)
+        self.exec("""
+        CREATE NODE TABLE IF NOT EXISTS Vertex(
+            id STRING,
+            graph_id STRING,
+            label STRING,
+            x DOUBLE,
+            y DOUBLE,
+            z DOUBLE,
+            props STRING,
+            PRIMARY KEY(id)
+        );
+        """, write=True)
+        
+        # Relationship tables
+        self.exec("""
+        CREATE REL TABLE IF NOT EXISTS CONNECT(FROM Vertex TO Vertex, label STRING, props STRING);
+        """, write=True)
+
+        # Figure out later if we need sessions and steps
+        # self.exec("""
+        # CREATE NODE TABLE IF NOT EXISTS Session(
+        #     id STRING,
+        #     title STRING,
+        #     created_at STRING,
+        #     PRIMARY KEY(id)
+        # );
+        # """, write=True)
+        # self.exec("""
+        # CREATE NODE TABLE IF NOT EXISTS Step(
+        #     id STRING,
+        #     session_id STRING,
+        #     idx INT64,
+        #     action STRING,
+        #     ok BOOL,
+        #     message STRING,
+        #     snapshot_before STRING,
+        #     snapshot_after STRING,
+        #     evidence STRING,
+        #     created_at STRING,
+        #     PRIMARY KEY(id)
+        # );
+        # """, write=True)
+        # self.exec("CREATE REL TABLE IF NOT EXISTS SessionHasStep(FROM Session TO Step);", write=True)
+
+
+class Kuzu:
+    """
+    TopologicPy-style class of static methods for Kùzu integration.
+
+    Notes
+    -----
+    - All methods are *static* to match TopologicPy's style.
+    - Graph persistence:
+        * Vertices: stored in `Vertex` with (id, graph_id, label, props JSON)
+        * Edges: stored as `CONNECT` relations a->b with label + props JSON
+        * We assume undirected design intent; only one CONNECT is stored (a->b),
+          but TopologicPy Graph treats edges as undirected by default.
+    """
+
+    # ---------- Core (DB + Connection + Schema) ----------
+    @staticmethod
+    def EnsureSchema(db_path: str, silent: bool = False) -> bool:
+        """
+        Ensures the required Kùzu schema exists in the database at `db_path`.
+
+        Parameters
+        ----------
+        db_path : str
+            Path to the Kùzu database directory. It will be created if it does not exist.
+        silent : bool , optional
+            If True, suppresses error messages. Default is False.
+
+        Returns
+        -------
+        bool
+            True if successful, False otherwise.
+        """
+        try:
+            mgr = _Mgr(db_path)
+            mgr.ensure_schema()
+            return True
+        except Exception as e:
+            if not silent:
+                print(f"Kuzu.EnsureSchema - Error: {e}")
+            return False
+
+    @staticmethod
+    def Database(db_path: str):
+        """
+        Returns the underlying `kuzu.Database` instance for `db_path`.
+        """
+        return _db_cache.get(db_path)
+
+    @staticmethod
+    def Connection(db_path: str):
+        """
+        Returns a `kuzu.Connection` bound to the database at `db_path`.
+        """
+        mgr = _Mgr(db_path)
+        with mgr.read() as c:
+            return c  # Note: returns a live connection (do not use across threads)
+
+    # ---------- Graph <-> DB Conversion ----------
+
+    @staticmethod
+    def UpsertGraph(db_path: str,
+                    graph,
+                    graphIDKey: Optional[str] = None,
+                    vertexIDKey: Optional[str] = None,
+                    vertexLabelKey: Optional[str] = None,
+                    mantissa: int = 6,
+                    silent: bool = False) -> str:
+        """
+        Upserts (deletes prior + inserts new) a TopologicPy graph and its GraphCard.
+
+        Parameters
+        ----------
+        db_path : str
+            Kùzu database path.
+        graph : topologicpy.Graph
+            The input TopologicPy graph.
+        graphIDKey : str , optional
+            The graph dictionary key under which the graph ID is stored. If None, a UUID is generated.
+        title, domain, geo, time_start, time_end, summary : str , optional
+            Optional metadata for GraphCard.
+        silent : bool , optional
+            If True, suppresses error messages. Default is False.
+
+        Returns
+        -------
+        str
+            The graph_id used.
+        """
+        from topologicpy.Topology import Topology
+        from topologicpy.Dictionary import Dictionary
+        d = Topology.Dictionary(graph)
+        if graphIDKey is None:
+            gid =  Topology.UUID(graph)
+        else:
+            gid = Dictionary.ValueAtKey(d, graphIDKey, Topology.UUID(graph))
+        g_props = Dictionary.PythonDictionary(d)
+        mesh_data = Graph.MeshData(graph, mantissa=mantissa)
+        verts = mesh_data['vertices']
+        v_props = mesh_data['vertexDictionaries']
+        edges = mesh_data['edges']
+        e_props = mesh_data['edgeDictionaries']
+        num_nodes = len(verts)
+        num_edges = len(edges)
+        mgr = _Mgr(db_path)
+        try:
+            mgr.ensure_schema()
+            # Upsert GraphCard
+            mgr.exec("MATCH (g:GraphCard) WHERE g.id = $id DELETE g;", {"id": gid}, write=True)
+            mgr.exec("""
+                CREATE (g:GraphCard {id:$id, num_nodes:$num_nodes, num_edges: $num_edges, props:$props});
+            """, {"id": gid, "num_nodes": num_nodes, "num_edges": num_edges, "props": json.dumps(g_props)}, write=True)
+
+            # Remove existing vertices/edges for this graph_id
+            mgr.exec("""
+                MATCH (a:Vertex)-[r:CONNECT]->(b:Vertex)
+                WHERE a.graph_id = $gid AND b.graph_id = $gid
+                DELETE r;
+            """, {"gid": gid}, write=True)
+            mgr.exec("MATCH (v:Vertex) WHERE v.graph_id = $gid DELETE v;", {"gid": gid}, write=True)
+
+            # Insert vertices
+            for i, v in enumerate(verts):
+                x,y,z = v
+                if vertexIDKey is None:
+                    vid = f"{gid}:{i}"
+                else:
+                    vid = v_props[i].get(vertexIDKey, f"{gid}:{i}")
+                if vertexLabelKey is None:
+                    label = str(i)
+                else:
+                    label = v_props[i].get(vertexIDKey, str(i))
+                mgr.exec("""
+                    CREATE (v:Vertex {id:$id, graph_id:$gid, label:$label, props:$props, x:$x, y:$y, z:$z});
+                """, {"id": vid, "gid": gid, "label": label, "x": x, "y": y, "z": z,
+                        "props": json.dumps(v_props[i])}, write=True)
+
+            # Insert edges
+            for i, e in enumerate(edges):
+                a_id = v_props[e[0]].get(vertexIDKey, f"{gid}:{e[0]}")
+                b_id = v_props[e[1]].get(vertexIDKey, f"{gid}:{e[1]}")
+                mgr.exec("""
+                    MATCH (a:Vertex {id:$a}), (b:Vertex {id:$b})
+                    CREATE (a)-[:CONNECT {label:$label, props:$props}]->(b);
+                """, {"a": a_id, "b": b_id,
+                        "label": e_props[i].get("label", str(i)),
+                        "props": json.dumps(e_props[i])}, write=True)
+
+            return gid
+        except Exception as e:
+            if not silent:
+                print(f"Kuzu.UpsertGraph - Error: {e}")
+            raise
+
+    @staticmethod
+    def GraphByID(db_path: str, graphID: str, silent: bool = False):
+        """
+        Reads a graph with id `graph_id` from Kùzu and constructs a TopologicPy graph.
+
+        Returns
+        -------
+        topologicpy.Graph
+            A new TopologicPy Graph, or None on error.
+        """
+        # if TGraph is None:
+        #     raise _KuzuError("TopologicPy is required to use Kuzu.ReadTopologicGraph.")
+        import random
+        mgr = _Mgr(db_path)
+
+        try:
+            mgr.ensure_schema()
+            # Read the GraphCard
+            g = mgr.exec("""
+                    MATCH (g:GraphCard) WHERE g.id = $id
+                    RETURN g.id AS id, g.num_nodes AS num_nodes, g.num_edges AS num_edges, g.props AS props
+                    ;
+                     """, {"id": graphID}, write=False) or None
+            if g is None:
+                return None
+            g = g[0]
+            g_dict = dict(json.loads(g.get("props") or "{}") or {})
+            g_dict = Dictionary.ByPythonDictionary(g_dict)
+            # Read vertices
+            rows_v = mgr.exec("""
+                MATCH (v:Vertex) WHERE v.graph_id = $gid
+                RETURN v.id AS id, v.label AS label, v.x AS x, v.y AS y, v.z AS z, v.props AS props
+                ORDER BY id;
+            """, {"gid": graphID}, write=False) or []
+
+            id_to_vertex = {}
+            vertices = []
+            for row in rows_v:
+                try:
+                    x = row.get("x") or random.uniform(0,1000)
+                    y = row.get("y") or random.uniform(0,1000)
+                    z = row.get("z") or random.uniform(0,1000)
+                except:
+                    x = random.uniform(0,1000)
+                    y = random.uniform(0,1000)
+                    z = random.uniform(0,1000)
+                v = Vertex.ByCoordinates(x,y,z)
+                props = {}
+                try:
+                    props = json.loads(row.get("props") or "{}")
+                except Exception:
+                    props = {}
+                # Ensure 'label' key present
+                props = dict(props or {})
+                if "label" not in props:
+                    props["label"] = row.get("label") or ""
+                d = Dictionary.ByKeysValues(list(props.keys()), list(props.values()))
+                v = Topology.SetDictionary(v, d)
+                id_to_vertex[row["id"]] = v
+                vertices.append(v)
+
+            # Read edges
+            rows_e = mgr.exec("""
+                MATCH (a:Vertex)-[r:CONNECT]->(b:Vertex)
+                WHERE a.graph_id = $gid AND b.graph_id = $gid
+                RETURN a.id AS a_id, b.id AS b_id, r.label AS label, r.props AS props;
+            """, {"gid": graphID}, write=False) or []
+            edges = []
+            for row in rows_e:
+                va = id_to_vertex.get(row["a_id"])
+                vb = id_to_vertex.get(row["b_id"])
+                if not va or not vb:
+                    continue
+                e = Edge.ByStartVertexEndVertex(va, vb)
+                props = {}
+                try:
+                    props = json.loads(row.get("props") or "{}")
+                except Exception:
+                    props = {}
+                props = dict(props or {})
+                if "label" not in props:
+                    props["label"] = row.get("label") or "connect"
+                d = Dictionary.ByKeysValues(list(props.keys()), list(props.values()))
+                e = Topology.SetDictionary(e, d)
+                edges.append(e)
+            if len(vertices) > 0:
+                g = Graph.ByVerticesEdges(vertices, edges)
+                g = Topology.SetDictionary(g, g_dict)
+            else:
+                g = None
+            return g
+        except Exception as e:
+            if not silent:
+                print(f"Kuzu.GraphByID - Error: {e}")
+            return None
+
+    @staticmethod
+    def GraphsByQuery(
+        db_path: str,
+        query: str,
+        params: dict | None = None,
+        graphIDKey: str = "graph_id",
+        silent: bool = False,
+    ):
+        """
+        Executes a Kùzu Cypher query and returns a list of TopologicPy Graphs.
+        The query should return at least one column identifying each graph.
+        By default this column is expected to be named 'graph_id', but you can
+        override that via `graph_id_field`.
+
+        The method will:
+        1) run the query,
+        2) extract distinct graph IDs from the result set (using `graph_id_field`
+            if present; otherwise it attempts to infer IDs from common fields like
+            'a_id', 'b_id', or 'id' that look like '<graph_id>:<vertex_index>'),
+        3) reconstruct each graph via Kuzu.ReadTopologicGraph(...).
+
+        Parameters
+        ----------
+        db_path : str
+            Path to the Kùzu database directory.
+        query : str
+            A valid Kùzu Cypher query.
+        params : dict , optional
+            Parameters to pass with the query.
+        graph_id_field : str , optional
+            The field name in the query result that contains the graph ID(s).
+            Default is "graph_id".
+        silent : bool , optional
+            If True, suppresses errors and returns an empty list on failure.
+
+        Returns
+        -------
+        list[topologicpy.Graph]
+            A list of reconstructed TopologicPy graphs.
+        """
+        # if TGraph is None:
+        #     raise _KuzuError("TopologicPy is required to use Kuzu.GraphsFromQuery.")
+
+        try:
+            mgr = _Mgr(db_path)
+            mgr.ensure_schema()
+            rows = mgr.exec(query, params or {}, write=False) or []
+
+            # Collect distinct graph IDs
+            gids = []
+            for r in rows:
+                gid = r.get(graphIDKey)
+
+                # Fallback: try to infer from common id fields like "<graph_id>:<i>"
+                if gid is None:
+                    for k in ("a_id", "b_id", "id"):
+                        v = r.get(k)
+                        if isinstance(v, str) and ":" in v:
+                            gid = v.split(":", 1)[0]
+                            break
+
+                if gid and gid not in gids:
+                    gids.append(gid)
+
+            # Reconstruct each graph
+            graphs = []
+            for gid in gids:
+                g = Kuzu.GraphByID(db_path, gid, silent=True)
+                if g is not None:
+                    graphs.append(g)
+            return graphs
+
+        except Exception as e:
+            if not silent:
+                print(f"Kuzu.GraphsByQuery - Error: {e}")
+            return []
+
+    @staticmethod
+    def DeleteGraph(db_path: str, graph_id: str, silent: bool = False) -> bool:
+        """
+        Deletes a graph (vertices/edges) and its GraphCard by id.
+        """
+        try:
+            mgr = _Mgr(db_path)
+            mgr.ensure_schema()
+            # Delete edges
+            mgr.exec("""
+                MATCH (a:Vertex)-[r:CONNECT]->(b:Vertex)
+                WHERE a.graph_id = $gid AND b.graph_id = $gid
+                DELETE r;
+            """, {"gid": graph_id}, write=True)
+            # Delete vertices
+            mgr.exec("MATCH (v:Vertex) WHERE v.graph_id = $gid DELETE v;", {"gid": graph_id}, write=True)
+            # Delete card
+            mgr.exec("MATCH (g:GraphCard) WHERE g.id = $gid DELETE g;", {"gid": graph_id}, write=True)
+            return True
+        except Exception as e:
+            if not silent:
+                print(f"Kuzu.DeleteGraph - Error: {e}")
+            return False
+    
+    @staticmethod
+    def EmptyDatabase(db_path: str, drop_schema: bool = False, recreate_schema: bool = True, silent: bool = False) -> bool:
+        """
+        Empties the Kùzu database at `db_path`.
+
+        Two modes:
+        - Soft clear (default): delete ALL relationships, then ALL nodes across all tables.
+        - Hard reset (drop_schema=True): drop known node/rel tables, optionally recreate schema.
+
+        Parameters
+        ----------
+        db_path : str
+            Path to the Kùzu database directory.
+        drop_schema : bool , optional
+            If True, DROP the known tables instead of deleting rows. Default False.
+        recreate_schema : bool , optional
+            If True and drop_schema=True, re-create the minimal schema after dropping. Default True.
+        silent : bool , optional
+            Suppress errors if True. Default False.
+
+        Returns
+        -------
+        bool
+            True on success, False otherwise.
+        """
+        try:
+            mgr = _Mgr(db_path)
+            # Ensure DB exists (does not create tables unless needed)
+            mgr.ensure_schema()
+
+            if drop_schema:
+                # Drop relationship tables FIRST (to release dependencies), then node tables.
+                # IF EXISTS is convenient; if your Kùzu version doesn't support it, remove and ignore exceptions.
+                for stmt in [
+                    "DROP TABLE IF EXISTS CONNECT;",
+                    "DROP TABLE IF EXISTS Vertex;",
+                    "DROP TABLE IF EXISTS GraphCard;",
+                ]:
+                    try:
+                        mgr.exec(stmt, write=True)
+                    except Exception as _e:
+                        if not silent:
+                            print(f"Kuzu.EmptyDatabase - Warning dropping table: {_e}")
+
+                if recreate_schema:
+                    mgr.ensure_schema()
+                return True
+
+            # Soft clear: remove all relationships, then all nodes (covers all labels/tables).
+            # Delete all edges (any direction)
+            mgr.exec("MATCH (a)-[r]->(b) DELETE r;", write=True)
+            # Delete all nodes (from all node tables)
+            mgr.exec("MATCH (n) DELETE n;", write=True)
+            return True
+
+        except Exception as e:
+            if not silent:
+                print(f"Kuzu.EmptyDatabase - Error: {e}")
+            return False
+

topologicpy/Vertex.py

@@ -1818,6 +1818,7 @@ class Vertex():
         pt = project_point_onto_plane(Vertex.Coordinates(vertex), [eq["a"], eq["b"], eq["c"], eq["d"]], direction)
         return Vertex.ByCoordinates(pt[0], pt[1], pt[2])
 
+
     @staticmethod
     def Separate(*vertices, minDistance: float = 0.0001, iterations: int = 100, strength: float = 0.1, tolerance: float = 0.0001, silent: bool = False):
         """
@@ -1846,68 +1847,97 @@ class Vertex():
         """
         from topologicpy.Topology import Topology
         from topologicpy.Helper import Helper
+        from topologicpy.Vertex import Vertex
         import math
+        from collections import defaultdict
 
+        # --- Gather & validate inputs ---
         if len(vertices) == 0:
             if not silent:
                 print("Vertex.Separate - Error: The input vertices parameter is an empty list. Returning None.")
             return None
-        if len(vertices) == 1:
-            vertices = vertices[0]
-            if isinstance(vertices, list):
-                if len(vertices) == 0:
-                    if not silent:
-                        print("Vertex.Separate - Error: The input vertices parameter is an empty list. Returning None.")
-                    return None
-                else:
-                    vertexList = [x for x in vertices if Topology.IsInstance(x, "Vertex")]
-                    if len(vertexList) == 0:
-                        if not silent:
-                            print("Vertex.Separate - Error: The input vertices parameter does not contain any valid vertices. Returning None.")
-                        return None
-            else:
-                if not silent:
-                    print("Vertex.Separate - Warning: The input vertices parameter contains only one vertex. Returning the same vertex.")
-                return vertices
+
+        # Allow either a single list or varargs
+        if len(vertices) == 1 and isinstance(vertices[0], list):
+            raw_list = vertices[0]
         else:
-            vertexList = Helper.Flatten(list(vertices))
-            vertexList = [x for x in vertexList if Topology.IsInstance(x, "Vertex")]
+            raw_list = Helper.Flatten(list(vertices))
+
+        vertexList = [v for v in raw_list if Topology.IsInstance(v, "Vertex")]
         if len(vertexList) == 0:
             if not silent:
                 print("Vertex.Separate - Error: The input parameters do not contain any valid vertices. Returning None.")
             return None
+        if len(vertexList) == 1:
+            if not silent:
+                print("Vertex.Separate - Warning: Only one vertex supplied. Returning it unchanged.")
+            return vertexList
+
+        minDistance = float(minDistance) + float(tolerance)  # safety margin
+        n = len(vertexList)
+
+        # Mutable coordinates
+        coords = [[vertexList[i].X(), vertexList[i].Y(), vertexList[i].Z()] for i in range(n)]
+        dicts  = [Topology.Dictionary(v) for v in vertexList]
+
+        # --- Pre-seed coincident vertices so they can start moving ---
+        # Cluster indices by quantized coordinate to catch exact (or near-exact) duplicates
+        key_scale = max(tolerance, 1e-12)
+        clusters = defaultdict(list)
+        for idx, (x, y, z) in enumerate(coords):
+            key = (round(x / key_scale), round(y / key_scale), round(z / key_scale))
+            clusters[key].append(idx)
+
+        # For any cluster with >1 vertex, spread them on a small circle in XY
+        for idxs in clusters.values():
+            k = len(idxs)
+            if k > 1:
+                r = minDistance * 0.5  # small initial spread; repulsion will take it from here
+                for m, idx in enumerate(idxs):
+                    ang = (2.0 * math.pi * m) / k
+                    coords[idx][0] += r * math.cos(ang)
+                    coords[idx][1] += r * math.sin(ang)
+                    # leave Z unchanged to avoid unintended vertical drift
+
+        # --- Repulsion simulation ---
+        eps = 1e-12
+        for _ in range(int(iterations)):
+            all_ok = True
+            for i in range(n):
+                xi, yi, zi = coords[i]
+                for j in range(i + 1, n):
+                    xj, yj, zj = coords[j]
+                    dx = xj - xi
+                    dy = yj - yi
+                    dz = zj - zi
+                    dist_sq = dx*dx + dy*dy + dz*dz
+                    if dist_sq <= 0.0:
+                        # still coincident: nudge with a tiny deterministic push along x
+                        dx, dy, dz = (eps, 0.0, 0.0)
+                        dist_sq = eps*eps
+                    dist = math.sqrt(dist_sq)
+
+                    if dist < minDistance:
+                        all_ok = False
+                        # Repulsion magnitude; clamp denominator to avoid blow-ups
+                        repel = (minDistance - dist) / max(dist, eps) * float(strength)
+                        # Split the move equally
+                        sx = 0.5 * dx * repel
+                        sy = 0.5 * dy * repel
+                        sz = 0.5 * dz * repel
+                        coords[i][0] -= sx; coords[i][1] -= sy; coords[i][2] -= sz
+                        coords[j][0] += sx; coords[j][1] += sy; coords[j][2] += sz
+            if all_ok:
+                break  # everything already at least minDistance apart
+
+        # --- Rebuild vertices & restore dictionaries ---
+        new_vertices = [Vertex.ByCoordinates(x, y, z) for (x, y, z) in coords]
+        for i in range(n):
+            new_vertices[i] = Topology.SetDictionary(new_vertices[i], dicts[i])
 
-        minDistance = minDistance + tolerance # Add a bit of a safety factor
-
-        # Convert to mutable coordinates
-        coords = [[v.X(), v.Y(), v.Z()] for v in vertices]
-        
-        for _ in range(iterations):
-            for i in range(len(coords)):
-                for j in range(i + 1, len(coords)):
-                    dx = coords[j][0] - coords[i][0]
-                    dy = coords[j][1] - coords[i][1]
-                    dz = coords[j][2] - coords[i][2]
-                    dist = math.sqrt(dx*dx + dy*dy + dz*dz)
-                    
-                    if dist < minDistance and dist > 1e-9:
-                        # Calculate repulsion vector
-                        repel = (minDistance - dist) / dist * strength
-                        shift = [dx * repel * 0.5, dy * repel * 0.5, dz * repel * 0.5]
-                        coords[i][0] -= shift[0]
-                        coords[i][1] -= shift[1]
-                        coords[i][2] -= shift[2]
-                        coords[j][0] += shift[0]
-                        coords[j][1] += shift[1]
-                        coords[j][2] += shift[2]
-        
-        # Reconstruct TopologicPy Vertex objects
-        new_vertices = [Vertex.ByCoordinates(x, y, z) for x, y, z in coords]
-        # Transfer the dictionaries
-        for i, v in enumerate(new_vertices):
-            v = Topology.SetDictionary(v, Topology.Dictionary(vertices[i]))
         return new_vertices
 
+
     @staticmethod
     def Transform(vertex, matrix, mantissa: int = 6, silent: bool = False):
         """

topologicpy/version.py

@@ -1 +1 @@
-__version__ = '0.8.55'
+__version__ = '0.8.57'

{topologicpy-0.8.55.dist-info → topologicpy-0.8.57.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topologicpy
-Version: 0.8.55
+Version: 0.8.57
 Summary: An AI-Powered Spatial Modelling and Analysis Software Library for Architecture, Engineering, and Construction.
 Author-email: Wassim Jabi <wassim.jabi@gmail.com>
 License: AGPL v3 License

{topologicpy-0.8.55.dist-info → topologicpy-0.8.57.dist-info}/RECORD

@@ -12,10 +12,11 @@ topologicpy/Dictionary.py,sha256=Z4YQ88tONWd-0X0dENQ8IZqIOa9mbBqhJkTBsHmft2g,446
 topologicpy/Edge.py,sha256=DifItuyabFDUFC7CVMlt2DeMFMNaGOqCg43iU9CPP0A,74029
 topologicpy/EnergyModel.py,sha256=hB1aiJe45gdDMFm1AhkBr-1djjtXSzn24iRpQMk43-4,57749
 topologicpy/Face.py,sha256=aX9EcR3JGbLITElhd25J0Z8m9U8KkmbYivGg3oZN-Uw,202296
-topologicpy/Graph.py,sha256=Oa0oOrPoOSUGL5fvJYHBH_r6kRZ944wk-P828GyAjk4,705757
+topologicpy/Graph.py,sha256=EdB8N58bm74Uy6Y9xTrNgtewU-wx8Tq7y8EhyZ50wvs,716133
 topologicpy/Grid.py,sha256=3OsBMyHh4w8gpFOTMKHMNTpo62V0CwRNu5cwm87yDUA,18421
 topologicpy/Helper.py,sha256=Nr6pyzl0sZm4Cu11wOqoYKu6yYal5N6A9jErXnaZBJc,31765
 topologicpy/Honeybee.py,sha256=DzaG9wpkJdcDWcjOGXhuN5X0gCqypmZGBa1y5E2MkjU,48964
+topologicpy/Kuzu.py,sha256=4j6yPMOlCtugXKO-nrjjige98MeYOE1PfzKdFEenpjk,20959
 topologicpy/Matrix.py,sha256=bOofT34G3YHu9aMIWx60YHAJga4R0GbDjsZBUD4Hu_k,22706
 topologicpy/Neo4j.py,sha256=J8jU_mr5-mWC0Lg_D2dMjMlx1rY_eh8ks_aubUuTdWw,22319
 topologicpy/Plotly.py,sha256=kF7JwBMWJQAuGezaJYI6Cq7ErNwEtcKzaExOfdGPIMc,123003
@@ -27,12 +28,12 @@ topologicpy/Speckle.py,sha256=-eiTqJugd7pHiHpD3pDUcDO6CGhVyPV14HFRzaqEoaw,18187
 topologicpy/Sun.py,sha256=8S6dhCKfOhUGVny-jEk87Q08anLYMB1JEBKRGCklvbQ,36670
 topologicpy/Topology.py,sha256=R5Ac3V_ADDRDZjhpcNvhM3AvDOLU6ORvB3yILyEkxnI,472559
 topologicpy/Vector.py,sha256=pEC8YY3TeHGfGdeNgvdHjgMDwxGabp5aWjwYC1HSvMk,42236
-topologicpy/Vertex.py,sha256=0f6HouARKaCuxhdxsUEYi8T9giJycnWhQ8Cn70YILBA,84885
+topologicpy/Vertex.py,sha256=r_3cicgpino96ymm1ANptfOuqE59b99YWwksxyPOYK4,85914
 topologicpy/Wire.py,sha256=gjgQUGHdBdXUIijgZc_VIW0E39w-smaVhhdl0jF63fQ,230466
 topologicpy/__init__.py,sha256=RMftibjgAnHB1vdL-muo71RwMS4972JCxHuRHOlU428,928
-topologicpy/version.py,sha256=EKCMooHLmkTpTBR1XTlkHxj-YkXZosf7ysuCeCcjiR8,23
-topologicpy-0.8.55.dist-info/licenses/LICENSE,sha256=FK0vJ73LuE8PYJAn7LutsReWR47-Ooovw2dnRe5yV6Q,681
-topologicpy-0.8.55.dist-info/METADATA,sha256=BIWmEWd275UZuMnl423fCxI3Bv6-vZpot8niPNApQAE,10535
-topologicpy-0.8.55.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-topologicpy-0.8.55.dist-info/top_level.txt,sha256=J30bDzW92Ob7hw3zA8V34Jlp-vvsfIkGzkr8sqvb4Uw,12
-topologicpy-0.8.55.dist-info/RECORD,,
+topologicpy/version.py,sha256=9nWlfIrJh0NFxdTerGFsViWVZBvjxJ997KXXkuz9AiM,23
+topologicpy-0.8.57.dist-info/licenses/LICENSE,sha256=FK0vJ73LuE8PYJAn7LutsReWR47-Ooovw2dnRe5yV6Q,681
+topologicpy-0.8.57.dist-info/METADATA,sha256=fHGtx2lc9MaC1L2EVY49mFCTJBz9V6zKGFpX08QyrZQ,10535
+topologicpy-0.8.57.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+topologicpy-0.8.57.dist-info/top_level.txt,sha256=J30bDzW92Ob7hw3zA8V34Jlp-vvsfIkGzkr8sqvb4Uw,12
+topologicpy-0.8.57.dist-info/RECORD,,