lp2graph 0.3.0__py3-none-any.whl

lp2graph/__init__.py

@@ -0,0 +1,54 @@
+"""lp2graph — typed-graph representation of LP, MIP, and MILP formulations.
+
+The public API is intentionally small. The canonical entry points are:
+
+    from lp2graph import load, validate
+    from lp2graph import views, metrics, render, export
+
+See ``docs/data-model.md`` for the schema and ``docs/views.md`` for the
+view derivations.
+"""
+
+from __future__ import annotations
+
+from lp2graph.codec import (
+    canonical_normal_form,
+    from_canonical_latex,
+    to_canonical_latex,
+)
+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
+from lp2graph.nl import describe
+
+__all__ = [
+    "Binding",
+    "ConstraintTemplate",
+    "Formulation",
+    "Index",
+    "Objective",
+    "Parameter",
+    "Quantifier",
+    "Term",
+    "ValidationError",
+    "VariableTemplate",
+    "canonical_normal_form",
+    "describe",
+    "from_canonical_latex",
+    "load",
+    "loads",
+    "to_canonical_latex",
+    "validate",
+]
+
+__version__ = "0.3.0"

lp2graph/cli.py

@@ -0,0 +1,238 @@
+"""Command-line entry point: ``lp2graph``.
+
+Subcommands:
+
+- ``lp2graph validate <file>`` — load and validate a formulation file.
+- ``lp2graph view <file> --view {schema,hybrid,ground} [--card I=5 ...]``
+  — derive a view and print a summary.
+- ``lp2graph render <file> --view ... --output graph.svg`` — render to
+  SVG.
+- ``lp2graph metrics <file>`` — compute and print all metrics.
+- ``lp2graph export <file> --format {networkx,pyg,dgl,latex,pyomo}`` —
+  export.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from lp2graph import load
+from lp2graph import validate as _validate
+from lp2graph import views as _views
+from lp2graph.metrics.flags import presence_flags
+from lp2graph.metrics.structural import structural_summary
+from lp2graph.render.svg import render_svg
+
+if TYPE_CHECKING:
+    from lp2graph.core.graph import Graph
+    from lp2graph.core.model import Formulation
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="lp2graph")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_validate = sub.add_parser("validate", help="Validate a formulation file.")
+    p_validate.add_argument("path", type=Path)
+
+    p_view = sub.add_parser("view", help="Derive a view and print a summary.")
+    p_view.add_argument("path", type=Path)
+    p_view.add_argument("--view", choices=("schema", "hybrid", "ground"), default="schema")
+    p_view.add_argument(
+        "--card",
+        action="append",
+        default=[],
+        help="Cardinality, e.g. --card I=5 --card T=8 (only for --view ground).",
+    )
+
+    p_render = sub.add_parser("render", help="Render a view to SVG.")
+    p_render.add_argument("path", type=Path)
+    p_render.add_argument("--view", choices=("schema", "hybrid", "ground"), default="hybrid")
+    p_render.add_argument("--card", action="append", default=[])
+    p_render.add_argument("--output", type=Path, required=True)
+
+    p_metrics = sub.add_parser("metrics", help="Compute all metrics.")
+    p_metrics.add_argument("path", type=Path)
+    p_metrics.add_argument("--view", choices=("schema", "hybrid"), default="schema")
+
+    p_export = sub.add_parser("export", help="Export to a downstream format.")
+    p_export.add_argument("path", type=Path)
+    p_export.add_argument(
+        "--format",
+        choices=("networkx", "pyg", "dgl", "latex", "pyomo"),
+        required=True,
+    )
+    p_export.add_argument("--view", choices=("schema", "hybrid", "ground"), default="hybrid")
+    p_export.add_argument("--card", action="append", default=[])
+    p_export.add_argument("--output", type=Path, default=None)
+
+    p_latex = sub.add_parser(
+        "latex", help="Emit reversible, paper-style canonical LaTeX (graph -> text)."
+    )
+    p_latex.add_argument("path", type=Path)
+    p_latex.add_argument("--output", type=Path, default=None)
+
+    p_parse = sub.add_parser(
+        "parse", help="Parse a canonical-LaTeX document back to JSON (text -> graph)."
+    )
+    p_parse.add_argument("path", type=Path, help="A .tex file produced by `lp2graph latex`.")
+    p_parse.add_argument("--output", type=Path, default=None)
+
+    p_describe = sub.add_parser(
+        "describe",
+        help="Generate a natural-language problem description (graph -> text).",
+    )
+    p_describe.add_argument("path", type=Path)
+    p_describe.add_argument("--instance", type=Path, default=None)
+    p_describe.add_argument("--output", type=Path, default=None)
+
+    p_solve = sub.add_parser("solve", help="Ground with instance data and solve the MILP.")
+    p_solve.add_argument("path", type=Path)
+    p_solve.add_argument("--instance", type=Path, required=True)
+    p_solve.add_argument("--solver", choices=("cbc", "highs", "gurobi"), default="cbc")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "validate":
+        f = load(args.path)
+        _validate(f)
+        print(f"OK: {f.id} ({f.family})")
+        return 0
+
+    if args.cmd == "view":
+        f = load(args.path)
+        g = _derive(f, args.view, args.card)
+        print(json.dumps({"nodes": len(g.nodes), "edges": len(g.edges), "view": g.view}, indent=2))
+        return 0
+
+    if args.cmd == "render":
+        f = load(args.path)
+        g = _derive(f, args.view, args.card)
+        svg = render_svg(g, title=f.name)
+        args.output.write_text(svg, encoding="utf-8")
+        print(f"wrote {args.output}")
+        return 0
+
+    if args.cmd == "metrics":
+        f = load(args.path)
+        g = _derive(f, args.view, [])
+        result: dict[str, object] = {}
+        for name, m in structural_summary(g).items():
+            result[name] = m.value
+        for name, m in presence_flags(f).items():
+            result[name] = m.value
+        print(json.dumps(result, indent=2, default=str))
+        return 0
+
+    if args.cmd == "export":
+        f = load(args.path)
+        if args.format == "latex":
+            from lp2graph.export.latex import to_latex
+
+            out = to_latex(f)
+        elif args.format == "pyomo":
+            from lp2graph.export.pyomo_stub import to_pyomo_stub
+
+            out = to_pyomo_stub(f)
+        else:
+            g = _derive(f, args.view, args.card)
+            if args.format == "networkx":
+                from lp2graph.export.networkx_adapter import to_networkx
+
+                nxg = to_networkx(g)
+                out = f"<NetworkX MultiDiGraph: {len(nxg)} nodes, {nxg.number_of_edges()} edges>"
+            elif args.format == "pyg":
+                from lp2graph.export.pyg import to_pyg
+
+                pyg = to_pyg(g)
+                out = repr(pyg)
+            else:  # dgl
+                from lp2graph.export.dgl import to_dgl
+
+                dglg = to_dgl(g)
+                out = repr(dglg)
+        if args.output:
+            args.output.write_text(out, encoding="utf-8")
+            print(f"wrote {args.output}")
+        else:
+            print(out)
+        return 0
+
+    if args.cmd == "latex":
+        from lp2graph.codec import to_canonical_latex
+
+        out = to_canonical_latex(load(args.path))
+        _emit(out, args.output)
+        return 0
+
+    if args.cmd == "parse":
+        from lp2graph.codec import from_canonical_latex
+
+        text = args.path.read_text(encoding="utf-8")
+        f = from_canonical_latex(text)
+        _emit(f.model_dump_json(indent=2, exclude_defaults=True), args.output)
+        return 0
+
+    if args.cmd == "describe":
+        from lp2graph.nl import describe
+
+        inst = None
+        if args.instance is not None:
+            from lp2graph.solve import Instance
+
+            inst = Instance.load(args.instance)
+        out = describe(load(args.path), inst)
+        _emit(out, args.output)
+        return 0
+
+    if args.cmd == "solve":
+        import pulp
+
+        from lp2graph.solve import Instance, solve
+
+        solver = {
+            "cbc": lambda: pulp.PULP_CBC_CMD(msg=0, threads=1),
+            "highs": lambda: pulp.HiGHS(msg=False),
+            "gurobi": lambda: pulp.GUROBI(msg=0),
+        }[args.solver]()
+        res = solve(load(args.path), Instance.load(args.instance), solver=solver)
+        print(
+            json.dumps(
+                {
+                    "status": res.status,
+                    "objective": res.objective,
+                    "n_vars": res.n_vars,
+                    "n_constraints": res.n_constraints,
+                    "solver": res.solver,
+                },
+                indent=2,
+            )
+        )
+        return 0
+
+    return 0
+
+
+def _emit(text: str, output: Path | None) -> None:
+    if output is not None:
+        output.write_text(text, encoding="utf-8")
+        print(f"wrote {output}")
+    else:
+        print(text)
+
+
+def _derive(f: Formulation, view: str, card_args: list[str]) -> Graph:
+    if view == "schema":
+        return _views.schema(f)
+    if view == "hybrid":
+        return _views.hybrid(f)
+    cards = {k: int(v) for arg in card_args for k, v in [arg.split("=", 1)]}
+    return _views.ground(f, cards)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lp2graph/codec/__init__.py

@@ -0,0 +1,41 @@
+"""Deterministic, reversible LaTeX <-> canonical-model codec.
+
+This subpackage adds a *bidirectional, deterministic* text interface on
+top of the canonical model:
+
+- :func:`to_canonical_latex` renders a :class:`~lp2graph.core.model.Formulation`
+  as a paper-style LaTeX document (``\\mathcal`` index sets, ``\\sum``,
+  ``\\forall`` quantifiers, big-M, ...). The algebra is genuine LaTeX an
+  author could paste into a paper; a compact ``%@`` annotation header
+  carries the non-algebraic metadata (kinds, roles, descriptions, ...).
+
+- :func:`from_canonical_latex` parses that document back into a
+  ``Formulation``. The parse is *deterministic*: same text in, same model
+  out, no model/LLM in the loop.
+
+The two functions are inverses up to a documented normalization
+(:func:`lp2graph.codec.normalize.canonical_normal_form`). The strongest
+guarantee the codec offers — and the one the tests assert — is text-level
+idempotence::
+
+    to_canonical_latex(from_canonical_latex(to_canonical_latex(f))) == to_canonical_latex(f)
+
+i.e. the LaTeX serialization is a fixed point. The *solvable* content
+(sets, parameters, variables, constraints, objective) round-trips
+exactly; only incidental labels (a literal term's ``ref`` name, a
+redundant ``offset`` field that disagrees with its own ``expr``) are
+normalized.
+
+See :mod:`lp2graph.codec.latex` for the grammar.
+"""
+
+from __future__ import annotations
+
+from lp2graph.codec.latex import from_canonical_latex, to_canonical_latex
+from lp2graph.codec.normalize import canonical_normal_form
+
+__all__ = [
+    "canonical_normal_form",
+    "from_canonical_latex",
+    "to_canonical_latex",
+]