lp2graph 0.3.0__py3-none-any.whl

lp2graph/core/model.py

@@ -0,0 +1,437 @@
+"""Canonical pydantic models for LP/MIP/MILP formulations.
+
+Mirrors ``schema/canonical.schema.json`` one-to-one. Every public class
+here corresponds to a ``$defs`` entry in the schema; field names are
+identical. The canonical model is the *single source of truth* — every
+view, metric, render, and export consumes a ``Formulation`` instance.
+
+The model is deliberately conservative about what it stores: only what
+cannot be derived. Anything that is a function of the canonical fields
+(grounding, metrics, renders) is computed on demand.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+# ---------------------------------------------------------------------------
+# Primitives
+# ---------------------------------------------------------------------------
+
+Identifier = Annotated[str, Field(pattern=r"^[A-Za-z_][A-Za-z0-9_]*$")]
+"""A Python-like identifier. Used for index, parameter, variable, and
+constraint names."""
+
+
+class _Frozen(BaseModel):
+    """Base model — strict, frozen, forbid-extra. Determinism by default."""
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        populate_by_name=True,
+        validate_assignment=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Index families and parameters
+# ---------------------------------------------------------------------------
+
+
+class Index(_Frozen):
+    """An index family (set) over which templates may range.
+
+    Examples: ``I`` (trains), ``T`` (time slots). An *ordered* index has
+    a natural sequence so that offsets like ``t-1`` are meaningful. A
+    *cyclic* index wraps modulo cardinality (PESP-style).
+    """
+
+    name: Identifier
+    description: str = ""
+    ordered: bool = False
+    cyclic: bool = False
+
+
+# Domain facet (additive): semantic class of a parameter, independent of 'kind'.
+ParameterDomainClass = Literal[
+    "cost_weight",
+    "time_duration",
+    "capacity",
+    "demand",
+    "network_structure",
+    "penalty_bigM",
+    "count_limit",
+    "unclassified",
+]
+
+
+class Parameter(_Frozen):
+    """A constant input to the formulation.
+
+    Parameters carry a *shape* — the index families they are indexed by —
+    and a *kind* tag that classifies them (e.g. ``big_m`` for tightening
+    constants, ``tolerance`` for slacks). Concrete numeric values are
+    *not* stored; they are supplied at grounding time when needed.
+    """
+
+    name: Identifier
+    description: str = ""
+    shape: tuple[Identifier, ...] = ()
+    kind: Literal["scalar", "vector", "matrix", "big_m", "tolerance"] = "scalar"
+    domain_class: ParameterDomainClass | None = None
+
+
+# ---------------------------------------------------------------------------
+# Variable templates
+# ---------------------------------------------------------------------------
+
+
+VariableDomain = Literal["continuous", "non_negative", "integer", "binary"]
+VariableRole = Literal["primary", "auxiliary", "slack", "indicator"]
+# Domain facet (additive): semantic role, independent of the structural 'role'.
+VariableDomainRole = Literal[
+    "selection_assignment",
+    "ordering_precedence",
+    "routing_path_column",
+    "timing",
+    "flow_quantity",
+    "auxiliary_linearization",
+    "unclassified",
+]
+
+
+class VariableTemplate(_Frozen):
+    """A template for a family of decision variables.
+
+    A template ``x[I, T]`` with ``domain="binary"`` represents the
+    ``|I| * |T|`` binary variables ``x_{i,t}`` that appear in the
+    grounded model. The schema view exposes the template; the ground
+    view exposes the instances.
+    """
+
+    name: Identifier
+    description: str = ""
+    shape: tuple[Identifier, ...] = ()
+    domain: VariableDomain
+    lower: float | None = None
+    upper: float | None = None
+    role: VariableRole = "primary"
+    domain_role: VariableDomainRole | None = None
+
+
+# ---------------------------------------------------------------------------
+# Quantifiers, bindings, terms
+# ---------------------------------------------------------------------------
+
+
+QuantifierRestriction = Literal[
+    "none", "ne_other", "lt_other", "le_other", "gt_other", "ge_other", "ordered_pair"
+]
+
+
+class QuantifierWhere(_Frozen):
+    """Attribute-based selection predicate on a quantifier.
+
+    Restricts the tuples admitted by the quantifier to those for which a
+    parameter (shaped over the quantifier's ``over`` index family)
+    equals a given value. For example, with a binary parameter
+    ``is_local`` of shape ``[T]``, ``QuantifierWhere(parameter="is_local",
+    equals=True)`` keeps only the values of the index where
+    ``is_local`` is true. Schema and hybrid views surface this as a
+    label on the quantifier; the ground view applies it as a filter at
+    materialization time.
+    """
+
+    parameter: Identifier
+    equals: bool | int | float | str
+
+
+class Quantifier(_Frozen):
+    """A constraint-template quantifier: ``index ∈ over``.
+
+    Optional ``restriction`` references another quantifier (via
+    ``restriction_other``). For example, ``j ∈ I, j != i`` is encoded as
+    ``Quantifier(index="j", over="I", restriction="ne_other",
+    restriction_other="i")``.
+
+    Optional ``where`` adds an attribute-based selection predicate
+    (e.g. ``is_local[t] == True``).
+    """
+
+    index: Identifier
+    over: Identifier
+    restriction: QuantifierRestriction = "none"
+    restriction_other: Identifier | None = None
+    where: QuantifierWhere | None = None
+
+    @model_validator(mode="after")
+    def _check_restriction_pair(self) -> Quantifier:
+        if self.restriction != "none" and self.restriction_other is None:
+            raise ValueError(
+                f"quantifier {self.index!r} has restriction {self.restriction!r} "
+                "but no restriction_other"
+            )
+        if self.restriction == "none" and self.restriction_other is not None:
+            raise ValueError(
+                f"quantifier {self.index!r} sets restriction_other={self.restriction_other!r} "
+                "but restriction is 'none'"
+            )
+        return self
+
+
+class Binding(_Frozen):
+    """The binding of one index slot of a referenced template.
+
+    For a template ``x[I, T]`` referenced inside a constraint quantified
+    over ``i ∈ I, t ∈ T``, the binding ``index="T", expr="t-1",
+    offset=-1`` resolves to ``x_{i, t-1}``. The ``modulo`` field, when
+    set to an index name, indicates that the offset should wrap modulo
+    that index's cardinality (PESP).
+    """
+
+    index: Identifier
+    expr: str
+    offset: int = 0
+    modulo: Identifier | None = None
+
+
+TermRefKind = Literal["variable", "parameter", "literal"]
+TermRole = Literal["lhs", "rhs", "objective", "slack", "aux"]
+TermOperator = Literal["none", "sum", "max", "min", "abs", "indicator", "modulo"]
+
+
+class Term(_Frozen):
+    """A single term in a constraint LHS, constraint RHS, or objective.
+
+    The four-tuple ``(ref, bindings, role, sign)`` is what makes the
+    schema/hybrid/ground views derivable from a single source of truth.
+
+    - ``ref`` names the referenced entity (variable, parameter, or
+      literal).
+    - ``bindings`` resolves each index slot of the referenced template
+      to an expression in the enclosing quantifier scope.
+    - ``coefficient`` is a parameter name or a numeric literal.
+    - ``sign`` is multiplied with the coefficient at evaluation time but
+      kept separate so renderers can show it explicitly.
+    - ``role`` drives edge coloring in rendered graphs.
+    - ``operator`` and ``operator_over`` capture aggregations like
+      ``sum_{t in T}`` so they are visible in the schema view.
+
+    For constant terms, prefer the ``constant`` shorthand
+    (``{"constant": 3599, "role": "rhs"}``); it is normalized at parse
+    time to a literal term whose ``coefficient`` carries the value.
+    """
+
+    ref: Identifier = "_const"
+    ref_kind: TermRefKind = "variable"
+    bindings: tuple[Binding, ...] = ()
+    coefficient: float | str | None = 1
+    sign: Literal[1, -1] = 1
+    role: TermRole
+    operator: TermOperator = "none"
+    operator_over: tuple[Identifier, ...] = ()
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_constant(cls, data: object) -> object:
+        if not isinstance(data, dict):
+            return data
+        if "constant" not in data:
+            return data
+        if data.get("ref") is not None or data.get("ref_kind") not in (None, "literal"):
+            raise ValueError(
+                "term: 'constant' is mutually exclusive with 'ref'/'ref_kind' "
+                "(other than ref_kind='literal')"
+            )
+        if "coefficient" in data and data["coefficient"] not in (None, 1):
+            raise ValueError(
+                "term: 'constant' is mutually exclusive with 'coefficient'; "
+                "the constant's value is its own coefficient"
+            )
+        if data.get("bindings"):
+            raise ValueError("term: constant term must not carry bindings")
+        out = {k: v for k, v in data.items() if k != "constant"}
+        out["ref"] = "_const"
+        out["ref_kind"] = "literal"
+        out["coefficient"] = data["constant"]
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Constraint and objective
+# ---------------------------------------------------------------------------
+
+
+Comparator = Literal["le", "ge", "eq"]
+ConstraintKind = Literal[
+    "linear",
+    "big_m",
+    "indicator",
+    "ordering",
+    "headway",
+    "capacity",
+    "flow_balance",
+    "modulo",
+    "soft",
+    "robust",
+    "set_packing",
+    "block_occupation",
+    "moving_block",
+    "dwell",
+]
+# Domain facet (additive): semantic function, independent of structural 'kind'.
+ConstraintDomainClass = Literal[
+    "assignment_covering",
+    "flow_conservation",
+    "capacity_resource",
+    "precedence_ordering",
+    "headway_separation",
+    "timing_window",
+    "coupling_linking_definition",
+    "periodic_modulo_pesp",
+    "subtour_connectivity",
+    "variable_bound_fix",
+    "objective_defining",
+    "unclassified",
+]
+
+
+class IndicatorTrigger(_Frozen):
+    """Logical gate for an indicator constraint: the body is enforced only
+    when ``binary`` equals ``active_value``. A back-end deterministically
+    emits either a native indicator constraint or a tightened big-M
+    linearization (see :mod:`lp2graph.transform.bigm`)."""
+
+    binary: Identifier
+    active_value: Literal[0, 1] = 1
+
+
+class ConstraintTemplate(_Frozen):
+    """A quantified constraint template.
+
+    The template's body is a comparison ``Σ lhs ⋄ Σ rhs`` where ``⋄`` is
+    one of ``≤``, ``≥``, ``=``. Each side is a list of :class:`Term`
+    instances; the side they appear in determines their default role,
+    but a term may carry its own role override (e.g. a slack term
+    appearing in the LHS of a soft constraint).
+    """
+
+    name: Identifier
+    description: str = ""
+    quantifiers: tuple[Quantifier, ...] = ()
+    comparator: Comparator
+    lhs: tuple[Term, ...]
+    rhs: tuple[Term, ...]
+    kind: ConstraintKind = "linear"
+    domain_class: ConstraintDomainClass | None = None
+    indicator: IndicatorTrigger | None = None
+
+
+ObjectiveSense = Literal["min", "max"]
+ObjectiveCombination = Literal["sum", "lexicographic", "weighted_sum"]
+
+
+class Objective(_Frozen):
+    """The objective function as a first-class section.
+
+    Mirrors the structure of constraints but without quantifiers (the
+    objective itself is scalar; its terms may carry ``sum`` operators
+    over index families to express ``min Σ_i c_i x_i``).
+    """
+
+    sense: ObjectiveSense
+    name: str = "objective"
+    description: str = ""
+    terms: tuple[Term, ...]
+    combination: ObjectiveCombination = "sum"
+
+
+# ---------------------------------------------------------------------------
+# Provenance
+# ---------------------------------------------------------------------------
+
+
+class Provenance(_Frozen):
+    """Optional metadata about where the formulation came from."""
+
+    source: str = ""
+    reference: str = ""
+    author: str = ""
+    date: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Formulation
+# ---------------------------------------------------------------------------
+
+
+Family = Literal["lp", "mip", "milp"]
+
+
+class Formulation(_Frozen):
+    """The canonical container.
+
+    A ``Formulation`` is the input to every view, metric, render, and
+    export in the library.
+    """
+
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: Annotated[str, Field(pattern=r"^[a-z0-9][a-z0-9_.-]*$")]
+    name: str
+    family: Family
+    description: str = ""
+    tags: tuple[str, ...] = ()
+    provenance: Provenance | None = None
+    indices: tuple[Index, ...] = ()
+    parameters: tuple[Parameter, ...] = ()
+    variables: tuple[VariableTemplate, ...]
+    constraints: tuple[ConstraintTemplate, ...] = ()
+    objective: Objective | None = None
+
+    # Convenience indexes for fast lookups -------------------------------
+
+    def index_map(self) -> dict[str, Index]:
+        return {i.name: i for i in self.indices}
+
+    def parameter_map(self) -> dict[str, Parameter]:
+        return {p.name: p for p in self.parameters}
+
+    def variable_map(self) -> dict[str, VariableTemplate]:
+        return {v.name: v for v in self.variables}
+
+    def constraint_map(self) -> dict[str, ConstraintTemplate]:
+        return {c.name: c for c in self.constraints}
+
+
+__all__ = [
+    "Binding",
+    "Comparator",
+    "ConstraintKind",
+    "ConstraintTemplate",
+    "Family",
+    "Formulation",
+    "Identifier",
+    "Index",
+    "Objective",
+    "ObjectiveCombination",
+    "ObjectiveSense",
+    "Parameter",
+    "Provenance",
+    "Quantifier",
+    "QuantifierRestriction",
+    "QuantifierWhere",
+    "Term",
+    "TermOperator",
+    "TermRefKind",
+    "TermRole",
+    "VariableDomain",
+    "VariableRole",
+    "VariableTemplate",
+]
+
+
+# Union type for term references (variable templates or parameters).
+TermReferent = VariableTemplate | Parameter

lp2graph/core/validate.py

@@ -0,0 +1,237 @@
+"""Cross-cutting invariants beyond what pydantic and JSON Schema enforce.
+
+Validation runs in two phases:
+
+1. **Schema validation** (handled by :mod:`lp2graph.core.loader` via
+   pydantic). Catches malformed JSON, wrong types, missing fields,
+   invalid enum values.
+2. **Semantic validation** (this module). Catches references to
+   undefined entities, bindings that do not match a referenced
+   template's shape, quantifiers that reference an unknown index, etc.
+
+Semantic errors are aggregated and raised as a single
+:class:`ValidationError` carrying a list of human-readable messages.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from lp2graph.core.model import (
+        ConstraintTemplate,
+        Formulation,
+        Objective,
+        Term,
+    )
+
+
+class ValidationError(Exception):
+    """Aggregated semantic validation error.
+
+    The ``errors`` attribute lists every issue found in a single pass,
+    so callers see all problems instead of fixing them one at a time.
+    """
+
+    def __init__(self, message: str, errors: list[str] | None = None) -> None:
+        super().__init__(message)
+        self.errors: list[str] = errors or []
+
+
+def validate(f: Formulation) -> None:
+    """Validate cross-cutting invariants of a formulation.
+
+    Raises :class:`ValidationError` if any invariant is violated.
+    """
+    errors: list[str] = []
+
+    index_names = {i.name for i in f.indices}
+    parameter_names = {p.name for p in f.parameters}
+    variable_names = {v.name for v in f.variables}
+
+    # 1. Variable shapes reference declared indices.
+    for v in f.variables:
+        for s in v.shape:
+            if s not in index_names:
+                errors.append(f"variable {v.name!r}: shape index {s!r} is not declared")
+
+    # 2. Parameter shapes reference declared indices.
+    for p in f.parameters:
+        for s in p.shape:
+            if s not in index_names:
+                errors.append(f"parameter {p.name!r}: shape index {s!r} is not declared")
+
+    # 3. Constraints: quantifiers, references, bindings.
+    for c in f.constraints:
+        _validate_constraint(
+            c,
+            index_names=index_names,
+            parameter_names=parameter_names,
+            variable_names=variable_names,
+            variable_shapes={v.name: v.shape for v in f.variables},
+            parameter_shapes={p.name: p.shape for p in f.parameters},
+            errors=errors,
+        )
+
+    # 4. Objective.
+    if f.objective is not None:
+        _validate_objective(
+            f.objective,
+            index_names=index_names,
+            parameter_names=parameter_names,
+            variable_names=variable_names,
+            variable_shapes={v.name: v.shape for v in f.variables},
+            parameter_shapes={p.name: p.shape for p in f.parameters},
+            errors=errors,
+        )
+
+    # 5. Family consistency: lp must not have integer/binary variables.
+    if f.family == "lp":
+        for v in f.variables:
+            if v.domain in ("integer", "binary"):
+                errors.append(f"family is 'lp' but variable {v.name!r} has domain {v.domain!r}")
+    if f.family == "mip":
+        # mip permits both integer and continuous; nothing to enforce.
+        pass
+    if f.family == "milp" and not any(v.domain in ("integer", "binary") for v in f.variables):
+        errors.append("family is 'milp' but no variable has integer or binary domain")
+
+    if errors:
+        raise ValidationError(
+            f"{len(errors)} validation error(s) in formulation {f.id!r}",
+            errors=errors,
+        )
+
+
+def _validate_constraint(
+    c: ConstraintTemplate,
+    *,
+    index_names: set[str],
+    parameter_names: set[str],
+    variable_names: set[str],
+    variable_shapes: dict[str, tuple[str, ...]],
+    parameter_shapes: dict[str, tuple[str, ...]],
+    errors: list[str],
+) -> None:
+    quantifier_indices = {q.index for q in c.quantifiers}
+
+    # Quantifier 'over' is a declared index family.
+    for q in c.quantifiers:
+        if q.over not in index_names:
+            errors.append(
+                f"constraint {c.name!r}: quantifier {q.index!r} ranges over "
+                f"undeclared index {q.over!r}"
+            )
+        if q.restriction != "none":
+            assert q.restriction_other is not None  # checked by pydantic
+            if q.restriction_other not in quantifier_indices:
+                errors.append(
+                    f"constraint {c.name!r}: quantifier {q.index!r} restriction "
+                    f"references unknown quantifier {q.restriction_other!r}"
+                )
+        if q.where is not None:
+            if q.where.parameter not in parameter_names:
+                errors.append(
+                    f"constraint {c.name!r}: quantifier {q.index!r} where-clause "
+                    f"references undeclared parameter {q.where.parameter!r}"
+                )
+            else:
+                p_shape = parameter_shapes[q.where.parameter]
+                if p_shape != (q.over,):
+                    errors.append(
+                        f"constraint {c.name!r}: quantifier {q.index!r} where-clause "
+                        f"parameter {q.where.parameter!r} has shape {list(p_shape)} "
+                        f"but must be shaped [{q.over!r}]"
+                    )
+
+    # Each side's terms validate against the available scope.
+    scope = quantifier_indices | index_names  # bindings may use any of these
+    for term in c.lhs:
+        _validate_term(
+            term,
+            where=f"constraint {c.name!r} lhs",
+            parameter_names=parameter_names,
+            variable_names=variable_names,
+            variable_shapes=variable_shapes,
+            parameter_shapes=parameter_shapes,
+            quantifier_scope=scope,
+            errors=errors,
+        )
+    for term in c.rhs:
+        _validate_term(
+            term,
+            where=f"constraint {c.name!r} rhs",
+            parameter_names=parameter_names,
+            variable_names=variable_names,
+            variable_shapes=variable_shapes,
+            parameter_shapes=parameter_shapes,
+            quantifier_scope=scope,
+            errors=errors,
+        )
+
+
+def _validate_objective(
+    o: Objective,
+    *,
+    index_names: set[str],
+    parameter_names: set[str],
+    variable_names: set[str],
+    variable_shapes: dict[str, tuple[str, ...]],
+    parameter_shapes: dict[str, tuple[str, ...]],
+    errors: list[str],
+) -> None:
+    # Objective has no quantifiers; aggregations live in operator_over.
+    for term in o.terms:
+        scope = set(term.operator_over) | index_names
+        _validate_term(
+            term,
+            where=f"objective {o.name!r}",
+            parameter_names=parameter_names,
+            variable_names=variable_names,
+            variable_shapes=variable_shapes,
+            parameter_shapes=parameter_shapes,
+            quantifier_scope=scope,
+            errors=errors,
+        )
+
+
+def _validate_term(
+    term: Term,
+    *,
+    where: str,
+    parameter_names: set[str],
+    variable_names: set[str],
+    variable_shapes: dict[str, tuple[str, ...]],
+    parameter_shapes: dict[str, tuple[str, ...]],
+    quantifier_scope: set[str],
+    errors: list[str],
+) -> None:
+    if term.ref_kind == "variable":
+        if term.ref not in variable_names:
+            errors.append(f"{where}: term references unknown variable {term.ref!r}")
+            return
+        shape = variable_shapes[term.ref]
+    elif term.ref_kind == "parameter":
+        if term.ref not in parameter_names:
+            errors.append(f"{where}: term references unknown parameter {term.ref!r}")
+            return
+        shape = parameter_shapes[term.ref]
+    else:  # literal
+        if term.bindings:
+            errors.append(f"{where}: literal term must not carry bindings")
+        return
+
+    # Bindings must cover exactly the referenced template's shape.
+    binding_indices = [b.index for b in term.bindings]
+    if set(binding_indices) != set(shape):
+        errors.append(
+            f"{where}: term ref {term.ref!r} has shape {shape!r} but bindings "
+            f"cover {sorted(binding_indices)!r}"
+        )
+
+    # Coefficient: if string, must be a parameter name.
+    if isinstance(term.coefficient, str) and term.coefficient not in parameter_names:
+        errors.append(f"{where}: term coefficient {term.coefficient!r} is not a declared parameter")
+
+
+__all__ = ["ValidationError", "validate"]

lp2graph/export/__init__.py

@@ -0,0 +1,13 @@
+"""Export adapters: NetworkX, PyG, DGL, LaTeX, Pyomo stubs.
+
+Heavy framework imports happen lazily inside each adapter to keep
+``lp2graph`` importable without optional dependencies.
+"""
+
+from lp2graph.export.dgl import to_dgl
+from lp2graph.export.latex import to_latex
+from lp2graph.export.networkx_adapter import to_networkx
+from lp2graph.export.pyg import to_pyg
+from lp2graph.export.pyomo_stub import to_pyomo_stub
+
+__all__ = ["to_dgl", "to_latex", "to_networkx", "to_pyg", "to_pyomo_stub"]