lp2graph 0.3.0__py3-none-any.whl

lp2graph/codec/normalize.py

@@ -0,0 +1,82 @@
+"""Canonical normal form for round-trip comparison.
+
+The LaTeX codec preserves the mathematical model exactly but normalizes a
+small set of *incidental* fields that have no algebraic surface form and
+no effect on grounding/solving:
+
+- A literal term's ``ref`` name (e.g. ``"one"``, ``"_const"``) is folded
+  to ``"_const"`` — only its numeric ``coefficient`` matters.
+- A binding's ``offset`` is recomputed from its own ``expr`` so a stored
+  offset that disagrees with the expression text is corrected.
+- ``coefficient`` ``None`` is folded to ``1`` (the schema default).
+- A negative numeric ``coefficient`` is folded into ``sign`` (the LaTeX
+  surface carries the sign explicitly, the coefficient magnitude bare).
+- A term's ``role`` is folded to the default for the side it sits on
+  (``lhs``/``rhs``/``objective``). ``role`` only drives edge coloring in
+  rendered graphs; it has no algebraic surface form and no effect on
+  grounding or solving.
+
+Two formulations that share a canonical normal form are
+solve-equivalent and structurally identical up to these labels.
+"""
+
+from __future__ import annotations
+
+import re
+
+from lp2graph.core.model import Binding, Formulation, Term
+
+_OFFSET_RE = re.compile(r"[+-]\s*\d+\s*$")
+
+
+def _norm_offset_from_expr(expr: str) -> int:
+    m = _OFFSET_RE.search(expr.replace(" ", ""))
+    if not m:
+        return 0
+    return int(m.group(0).replace(" ", ""))
+
+
+def _norm_binding(b: Binding) -> Binding:
+    return b.model_copy(update={"offset": _norm_offset_from_expr(b.expr)})
+
+
+_SIDE_DEFAULT = {"lhs": "lhs", "rhs": "rhs"}
+
+
+def _norm_term(t: Term, side: str) -> Term:
+    update: dict[str, object] = {
+        "bindings": tuple(_norm_binding(b) for b in t.bindings),
+        "role": _SIDE_DEFAULT.get(side, side),
+    }
+    coef = 1 if t.coefficient is None else t.coefficient
+    sign = t.sign
+    if isinstance(coef, (int, float)) and not isinstance(coef, bool) and coef < 0:
+        coef = -coef
+        sign = -sign
+    update["coefficient"] = coef
+    update["sign"] = sign
+    if t.ref_kind == "literal":
+        update["ref"] = "_const"
+    return t.model_copy(update=update)
+
+
+def canonical_normal_form(f: Formulation) -> Formulation:
+    """Return ``f`` with incidental labels normalized (see module docstring)."""
+    constraints = tuple(
+        c.model_copy(
+            update={
+                "lhs": tuple(_norm_term(t, "lhs") for t in c.lhs),
+                "rhs": tuple(_norm_term(t, "rhs") for t in c.rhs),
+            }
+        )
+        for c in f.constraints
+    )
+    objective = None
+    if f.objective is not None:
+        objective = f.objective.model_copy(
+            update={"terms": tuple(_norm_term(t, "objective") for t in f.objective.terms)}
+        )
+    return f.model_copy(update={"constraints": constraints, "objective": objective})
+
+
+__all__ = ["canonical_normal_form"]

lp2graph/core/__init__.py

@@ -0,0 +1,35 @@
+"""Core canonical model, loader, validator, and internal graph type."""
+
+from lp2graph.core.graph import Edge, Graph, Node
+from lp2graph.core.loader import load, loads
+from lp2graph.core.model import (
+    Binding,
+    ConstraintTemplate,
+    Formulation,
+    Index,
+    Objective,
+    Parameter,
+    Quantifier,
+    Term,
+    VariableTemplate,
+)
+from lp2graph.core.validate import ValidationError, validate
+
+__all__ = [
+    "Binding",
+    "ConstraintTemplate",
+    "Edge",
+    "Formulation",
+    "Graph",
+    "Index",
+    "Node",
+    "Objective",
+    "Parameter",
+    "Quantifier",
+    "Term",
+    "ValidationError",
+    "VariableTemplate",
+    "load",
+    "loads",
+    "validate",
+]

lp2graph/core/graph.py

@@ -0,0 +1,183 @@
+"""Internal typed graph used by view derivations, metrics, render, and export.  # noqa: E501
+
+This is *not* a NetworkX, PyG, or DGL graph. It is a small, library-agnostic
+representation that downstream consumers translate into their own format.
+
+A :class:`Graph` is a directed multigraph with typed nodes and typed edges.
+Nodes carry a ``cls`` (class), ``subtype``, ``shape`` (the index families
+they range over, in the schema view), and a free-form ``data`` dict for
+view-specific metadata. Edges carry a ``type``, ``role``, optional
+``label``, and ``data``.
+
+Determinism: node and edge insertion order is preserved. Equality compares
+nodes and edges as ordered sequences. This guarantees identical render and
+export output across runs given identical inputs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+NodeClass = Literal[
+    "variable",
+    "constraint",
+    "objective",
+    "index",
+    "parameter",
+    "operator",
+    "instance_variable",
+    "instance_constraint",
+]
+"""High-level node category. Drives palette selection in the renderer."""
+
+
+EdgeType = Literal[
+    "var_in_constraint",
+    "var_in_objective",
+    "uses_index",
+    "uses_parameter",
+    "operator_input",
+    "operator_output",
+    "instance_of",
+    "ground_var_in_constraint",
+]
+"""Edge category. Drives stroke/style in the renderer."""
+
+
+@dataclass(frozen=True, slots=True)
+class Node:
+    """A node in the typed graph.
+
+    ``id`` must be unique within the graph. Inserting a node with a
+    duplicate id raises :class:`ValueError`. ``cls`` selects the visual
+    class; ``subtype`` is a free string used by renderers (e.g.
+    ``"binary"`` for a binary variable).
+    """
+
+    id: str
+    cls: NodeClass
+    subtype: str = ""
+    label: str = ""
+    shape: tuple[str, ...] = ()
+    data: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class Edge:
+    """A directed edge in the typed graph."""
+
+    src: str
+    dst: str
+    type: EdgeType
+    role: str = ""
+    label: str = ""
+    data: Mapping[str, Any] = field(default_factory=dict)
+
+
+class Graph:
+    """A directed multigraph with insertion-order determinism.
+
+    Not thread-safe. Designed for single-pass construction inside a view
+    derivation, then read-only consumption by metrics, renderers, and
+    exporters.
+    """
+
+    __slots__ = ("_edges", "_nodes", "_view")
+
+    def __init__(self, view: str = "") -> None:
+        self._nodes: dict[str, Node] = {}
+        self._edges: list[Edge] = []
+        self._view = view
+
+    # -- accessors --------------------------------------------------------
+
+    @property
+    def view(self) -> str:
+        """The view this graph was derived from (``"schema"``, etc.)."""
+        return self._view
+
+    @property
+    def nodes(self) -> tuple[Node, ...]:
+        return tuple(self._nodes.values())
+
+    @property
+    def edges(self) -> tuple[Edge, ...]:
+        return tuple(self._edges)
+
+    def node(self, node_id: str) -> Node:
+        return self._nodes[node_id]
+
+    def has_node(self, node_id: str) -> bool:
+        return node_id in self._nodes
+
+    def __len__(self) -> int:
+        return len(self._nodes)
+
+    # -- mutation ---------------------------------------------------------
+
+    def add_node(
+        self,
+        node_id: str,
+        cls: NodeClass,
+        *,
+        subtype: str = "",
+        label: str = "",
+        shape: Iterable[str] = (),
+        data: Mapping[str, Any] | None = None,
+    ) -> Node:
+        if node_id in self._nodes:
+            raise ValueError(f"duplicate node id: {node_id!r}")
+        node = Node(
+            id=node_id,
+            cls=cls,
+            subtype=subtype,
+            label=label or node_id,
+            shape=tuple(shape),
+            data=dict(data or {}),
+        )
+        self._nodes[node_id] = node
+        return node
+
+    def add_edge(
+        self,
+        src: str,
+        dst: str,
+        type: EdgeType,
+        *,
+        role: str = "",
+        label: str = "",
+        data: Mapping[str, Any] | None = None,
+    ) -> Edge:
+        if src not in self._nodes:
+            raise KeyError(f"unknown source node: {src!r}")
+        if dst not in self._nodes:
+            raise KeyError(f"unknown destination node: {dst!r}")
+        edge = Edge(
+            src=src,
+            dst=dst,
+            type=type,
+            role=role,
+            label=label,
+            data=dict(data or {}),
+        )
+        self._edges.append(edge)
+        return edge
+
+    # -- introspection ----------------------------------------------------
+
+    def nodes_by_class(self, cls: NodeClass) -> tuple[Node, ...]:
+        return tuple(n for n in self._nodes.values() if n.cls == cls)
+
+    def edges_by_type(self, type: EdgeType) -> tuple[Edge, ...]:
+        return tuple(e for e in self._edges if e.type == type)
+
+    def out_edges(self, node_id: str) -> tuple[Edge, ...]:
+        return tuple(e for e in self._edges if e.src == node_id)
+
+    def in_edges(self, node_id: str) -> tuple[Edge, ...]:
+        return tuple(e for e in self._edges if e.dst == node_id)
+
+
+__all__ = ["Edge", "EdgeType", "Graph", "Node", "NodeClass"]

lp2graph/core/loader.py

@@ -0,0 +1,63 @@
+"""Load and parse formulation files.
+
+The loader is intentionally thin: it reads JSON, validates against the
+canonical pydantic model, and returns a :class:`~lp2graph.core.model.Formulation`.
+Schema validation against the JSON Schema runs first to give clear,
+spec-grounded error messages; pydantic then enforces the typed model.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from lp2graph.core.model import Formulation
+from lp2graph.core.validate import validate as _validate
+
+
+def load(path: str | Path) -> Formulation:
+    """Load a formulation from a JSON file path.
+
+    Args:
+        path: Filesystem path to a JSON file conforming to
+            ``schema/canonical.schema.json``.
+
+    Returns:
+        A validated :class:`Formulation`.
+
+    Raises:
+        ValidationError: if the file does not conform to the canonical
+            schema or violates a model invariant.
+        FileNotFoundError: if ``path`` does not exist.
+    """
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    return loads(text, source=str(p))
+
+
+def loads(text: str, *, source: str = "<string>") -> Formulation:
+    """Parse a formulation from a JSON string.
+
+    Args:
+        text: JSON document text.
+        source: Identifier used in error messages.
+
+    Returns:
+        A validated :class:`Formulation`.
+
+    Raises:
+        ValidationError: if the document does not conform.
+    """
+    try:
+        data: Any = json.loads(text)
+    except json.JSONDecodeError as e:
+        from lp2graph.core.validate import ValidationError
+
+        raise ValidationError(f"{source}: invalid JSON: {e}") from e
+    formulation = Formulation.model_validate(data)
+    _validate(formulation)
+    return formulation
+
+
+__all__ = ["load", "loads"]