archgraph-layout 1.0.0__py3-none-any.whl

archgraph/model.py

@@ -0,0 +1,394 @@
+"""Core data model: graph, subsystems, nodes, ports, edges, buses and hints."""
+from __future__ import annotations
+
+import itertools
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+
+from .geometry import Point, Rect
+
+
+class ArchGraphError(Exception):
+    """Raised for invalid input; carries all messages collected while parsing."""
+
+    def __init__(self, messages):
+        if isinstance(messages, str):
+            messages = [messages]
+        self.messages = list(messages)
+        super().__init__("\n".join(self.messages))
+
+
+# --------------------------------------------------------------------------------------
+# Settings
+# --------------------------------------------------------------------------------------
+
+@dataclass
+class Settings:
+    title: str = ""
+    subtitle: str = ""
+    direction: str = "LR"              # default flow direction: LR, RL, TB, BT
+    aspect: Optional[float] = 1.6      # target width/height of the whole drawing (None = free)
+    theme: str = "light"
+    seed: int = 7
+    quality: str = "normal"            # draft | normal | high | max
+    node_spacing: float = 34.0         # minimum gap between sibling blocks
+    subsystem_padding: float = 16.0    # inner padding of subsystem boxes
+    edge_spacing: float = 7.0          # pitch between parallel wires after nudging
+    port_spacing: float = 14.0         # minimum pitch between ports on a side
+    node_margin: float = 10.0          # wire clearance around nodes
+    font_family: str = "Helvetica, Arial, sans-serif"
+    font_size: float = 12.0
+    routing: str = "orthogonal"        # orthogonal | straight
+    corner_radius: float = 3.0         # rounded wire corners (0 = sharp)
+    crossings: str = "hop"             # hop | gap | none
+    legend: str = "auto"               # auto | none | always
+    merge_nets: bool = True            # edges leaving the same port route as one net (tree)
+    auto_group: str = "auto"           # auto | visible | off  -- automatic clustering of huge levels
+    max_level_items: int = 30          # auto-cluster threshold per subsystem level
+    passes: int = 0                    # 0 = by quality
+    flow: str = "normal"               # strong | normal | weak | none
+    align_edges: bool = True
+    show_ports: bool = True
+    port_labels: bool = True
+    junction_dots: bool = True
+    shadows: bool = True
+    background_grid: bool = False
+    edge_labels: bool = True
+    default_shape: str = "box"
+    bundle_parallel: bool = False      # merge parallel edges between the same endpoints
+    margin: float = 24.0               # outer margin of the drawing
+    weights: Dict[str, float] = field(default_factory=dict)  # floorplanner cost weight overrides
+    time_budget: float = 0.0           # optional soft limit in seconds for annealing (0 = none)
+    spacing_passes: int = -1           # routing-aware spacing iterations (-1 = by quality)
+    float_ports: bool = True           # let a routing pass choose the side of automatic ports
+    uniform_instances: bool = True     # instances of the same template share one internal layout
+
+    def quality_factor(self) -> float:
+        return {"draft": 0.25, "fast": 0.25, "normal": 1.0, "high": 2.5, "max": 6.0}.get(self.quality, 1.0)
+
+    def num_spacing_passes(self) -> int:
+        if self.spacing_passes >= 0:
+            return self.spacing_passes
+        return {"draft": 0, "fast": 0, "normal": 2, "high": 3, "max": 4}.get(self.quality, 2)
+
+    def num_passes(self) -> int:
+        if self.passes > 0:
+            return self.passes
+        return {"draft": 1, "fast": 1, "normal": 2, "high": 3, "max": 3}.get(self.quality, 2)
+
+
+# --------------------------------------------------------------------------------------
+# Graph elements
+# --------------------------------------------------------------------------------------
+
+_counter = itertools.count()
+
+
+@dataclass(eq=False, repr=False)
+class Port:
+    id: str
+    owner: "Element"
+    side: Optional[str] = None         # requested side (None = automatic)
+    label: str = ""
+    order: Optional[float] = None
+    direction: Optional[str] = None    # in | out | inout
+    style: Dict[str, Any] = field(default_factory=dict)
+    fixed: bool = False                # do not slide along the side
+    anonymous: bool = False            # generated for an edge that named no port
+    line: Optional[int] = None
+    # layout results
+    assigned_side: Optional[str] = None
+    route_side: Optional[str] = None   # side chosen by the floating-port routing pass
+    x: float = 0.0
+    y: float = 0.0
+    edges: List["Edge"] = field(default_factory=list)
+
+    @property
+    def full_id(self) -> str:
+        return f"{self.owner.id}:{self.id}"
+
+    @property
+    def point(self) -> Point:
+        return (self.x, self.y)
+
+    def __repr__(self):
+        return f"Port({self.full_id})"
+
+
+@dataclass(eq=False, repr=False)
+class Element:
+    id: str
+    label: str = ""
+    parent: Optional["Subsystem"] = None
+    classes: List[str] = field(default_factory=list)
+    attrs: Dict[str, str] = field(default_factory=dict)
+    style: Dict[str, Any] = field(default_factory=dict)
+    props: List[Tuple[str, str]] = field(default_factory=list)
+    ports: Dict[str, Port] = field(default_factory=dict)
+    tooltip: str = ""
+    url: str = ""
+    line: Optional[int] = None
+    # geometry (centre + size)
+    x: float = 0.0
+    y: float = 0.0
+    w: float = 0.0
+    h: float = 0.0
+    uid: int = field(default_factory=lambda: next(_counter))
+
+    kind = "element"
+
+    @property
+    def rect(self) -> Rect:
+        return Rect.from_center(self.x, self.y, self.w, self.h)
+
+    def set_rect(self, r: Rect):
+        self.x, self.y, self.w, self.h = r.cx, r.cy, r.w, r.h
+
+    def ancestors(self) -> List["Subsystem"]:
+        out = []
+        p = self.parent
+        while p is not None:
+            out.append(p)
+            p = p.parent
+        return out
+
+    @property
+    def depth(self) -> int:
+        return len(self.ancestors())
+
+    def is_descendant_of(self, sub: "Subsystem") -> bool:
+        p = self.parent
+        while p is not None:
+            if p is sub:
+                return True
+            p = p.parent
+        return False
+
+    def display_label(self) -> str:
+        return self.label if self.label is not None else self.id
+
+    def __hash__(self):
+        return self.uid
+
+    def __repr__(self):
+        return f"{type(self).__name__}({self.id})"
+
+
+@dataclass(eq=False, repr=False)
+class Node(Element):
+    shape: str = "box"
+    sublabel: str = ""
+    icon: str = ""
+    multiplicity: int = 1
+    min_w: Optional[float] = None
+    min_h: Optional[float] = None
+    virtual: bool = False              # internal helper node (not drawn)
+    is_note: bool = False
+
+    kind = "node"
+
+
+@dataclass(eq=False, repr=False)
+class Subsystem(Element):
+    children: List[Element] = field(default_factory=list)
+    direction: Optional[str] = None
+    algorithm: str = "auto"            # auto | floorplan | layered | grid | row | column
+    aspect: Optional[float] = None
+    padding: Optional[float] = None
+    spacing: Optional[float] = None
+    collapsed: bool = False
+    visible: bool = True
+    auto: bool = False                 # created by auto-clustering
+    columns: Optional[int] = None      # for grid algorithm
+    header_h: float = 0.0              # computed height reserved for the title
+
+    kind = "subsystem"
+
+    def iter_descendants(self) -> Iterator[Element]:
+        for c in self.children:
+            yield c
+            if isinstance(c, Subsystem):
+                yield from c.iter_descendants()
+
+    def leaves(self) -> List[Node]:
+        return [e for e in self.iter_descendants() if isinstance(e, Node)]
+
+    def subsystems(self) -> List["Subsystem"]:
+        return [e for e in self.iter_descendants() if isinstance(e, Subsystem)]
+
+    def contains(self, el: Element) -> bool:
+        return el.is_descendant_of(self)
+
+    def child_containing(self, el: Element) -> Optional[Element]:
+        """Direct child of this subsystem that is or contains ``el``."""
+        cur = el
+        while cur is not None and cur.parent is not self:
+            cur = cur.parent
+        return cur
+
+
+@dataclass(eq=False, repr=False)
+class Endpoint:
+    element: Element
+    port: Optional[Port] = None
+    ref: str = ""
+
+    @property
+    def node(self) -> Element:
+        return self.element
+
+    def __repr__(self):
+        return f"Endpoint({self.port.full_id if self.port else self.element.id})"
+
+
+@dataclass(eq=False, repr=False)
+class Edge:
+    id: str
+    src: Endpoint
+    dst: Endpoint
+    label: str = ""
+    src_label: str = ""
+    dst_label: str = ""
+    classes: List[str] = field(default_factory=list)
+    attrs: Dict[str, str] = field(default_factory=dict)
+    style: Dict[str, Any] = field(default_factory=dict)
+    directed: bool = True
+    arrowhead: Optional[str] = None
+    arrowtail: Optional[str] = None
+    weight: float = 1.0
+    minlen: int = 1
+    constraint: bool = True            # participates in flow direction
+    layout: bool = True                # participates in placement at all
+    straight: bool = False             # high priority for straight routing
+    bits: str = ""                     # bus width annotation (e.g. 64 -> slash marker)
+    net: Optional[str] = None
+    tooltip: str = ""
+    multiplicity: int = 1
+    line: Optional[int] = None
+    # results
+    points: List[Point] = field(default_factory=list)
+    label_pos: Optional[Tuple[float, float, float, float]] = None   # x, y, w, h (centre)
+    src_label_pos: Optional[Tuple[float, float]] = None
+    dst_label_pos: Optional[Tuple[float, float]] = None
+    routed: bool = False
+    uid: int = field(default_factory=lambda: next(_counter))
+
+    def __hash__(self):
+        return self.uid
+
+    def __repr__(self):
+        return f"Edge({self.id}: {self.src} -> {self.dst})"
+
+    def endpoints(self) -> Tuple[Endpoint, Endpoint]:
+        return self.src, self.dst
+
+
+@dataclass(eq=False, repr=False)
+class BusTap:
+    endpoint: Endpoint
+    label: str = ""
+    direction: Optional[str] = None
+
+
+@dataclass(eq=False, repr=False)
+class Bus:
+    id: str
+    label: str = ""
+    taps: List[BusTap] = field(default_factory=list)
+    classes: List[str] = field(default_factory=list)
+    attrs: Dict[str, str] = field(default_factory=dict)
+    style: Dict[str, Any] = field(default_factory=dict)
+    bits: str = ""
+    orientation: str = "auto"
+    tooltip: str = ""
+    line: Optional[int] = None
+    # results
+    segments: List[Tuple[Point, Point]] = field(default_factory=list)
+    junctions: List[Point] = field(default_factory=list)
+    label_pos: Optional[Tuple[float, float, float, float]] = None
+    routed: bool = False
+    uid: int = field(default_factory=lambda: next(_counter))
+
+    def __hash__(self):
+        return self.uid
+
+
+@dataclass
+class Hint:
+    kind: str
+    refs: List[str] = field(default_factory=list)
+    params: Dict[str, Any] = field(default_factory=dict)
+    line: Optional[int] = None
+    elements: List[Element] = field(default_factory=list)   # resolved refs
+
+    def __repr__(self):
+        return f"Hint({self.kind} {' '.join(self.refs)} {self.params})"
+
+
+@dataclass
+class LegendEntry:
+    label: str
+    kind: str = "node"       # node | edge | subsystem | bus
+    classes: List[str] = field(default_factory=list)
+    style: Dict[str, Any] = field(default_factory=dict)
+    shape: Optional[str] = None
+
+
+@dataclass
+class Graph:
+    root: Subsystem
+    settings: Settings = field(default_factory=Settings)
+    elements: Dict[str, Element] = field(default_factory=dict)
+    edges: List[Edge] = field(default_factory=list)
+    buses: List[Bus] = field(default_factory=list)
+    hints: List[Hint] = field(default_factory=list)
+    classes: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    legend: List[LegendEntry] = field(default_factory=list)
+    legend_title: str = "Legend"
+    titleblock: Dict[str, str] = field(default_factory=dict)
+    warnings: List[str] = field(default_factory=list)
+    source: str = ""
+    # results
+    bbox: Optional[Rect] = None
+    layout_stats: Dict[str, Any] = field(default_factory=dict)
+    extras: Dict[str, Any] = field(default_factory=dict)
+
+    # -- queries -----------------------------------------------------------------------
+    def nodes(self, include_virtual: bool = False) -> List[Node]:
+        return [e for e in self.root.iter_descendants()
+                if isinstance(e, Node) and (include_virtual or not e.virtual)]
+
+    def subsystems(self) -> List[Subsystem]:
+        return [e for e in self.root.iter_descendants() if isinstance(e, Subsystem)]
+
+    def get(self, ident: str) -> Optional[Element]:
+        return self.elements.get(ident)
+
+    def lca(self, a: Element, b: Element) -> Subsystem:
+        """Deepest subsystem strictly containing both elements."""
+        anc_b = set(b.ancestors())
+        for s in a.ancestors():
+            if s in anc_b:
+                return s
+        return self.root
+
+    def edge_scope(self, a: Element, b: Element) -> Subsystem:
+        """Subsystem in which a connection between ``a`` and ``b`` lives.
+
+        A connection from a block to a port of one of its own ancestors lives inside
+        that ancestor; otherwise it lives in the strict lowest common ancestor."""
+        if isinstance(b, Subsystem) and a.is_descendant_of(b):
+            return b
+        if isinstance(a, Subsystem) and b.is_descendant_of(a):
+            return a
+        return self.lca(a, b)
+
+    def all_ports(self) -> List[Port]:
+        out = []
+        for e in self.root.iter_descendants():
+            out.extend(e.ports.values())
+        out.extend(self.root.ports.values())
+        return out
+
+    def warn(self, msg: str):
+        self.warnings.append(msg)