msolveio 0.1.0__py3-none-any.whl

msolveio/__init__.py

@@ -0,0 +1,43 @@
+"""Strict Python I/O for msolve: canonical input, mode-required output.
+
+Groebner-mode (``-g``) only in v0.1. Solver-mode bytes are rejected, not
+interpreted.
+
+msolveio is not a computer algebra system and not a Groebner engine. It writes
+``.ms`` files msolve will parse the way you meant, and reads back only the one
+output language it can identify with certainty.
+"""
+
+from __future__ import annotations
+
+from .emit import emit_system
+from .errors import (
+    MsolveAmbiguous,
+    MsolveDied,
+    MsolveError,
+    MsolveInputError,
+    MsolveOutputError,
+    MsolveTimeout,
+    MsolveVersionUnsupported,
+)
+from .mode import Mode
+from .parse import GroebnerOutput, parse_groebner
+from .run import RunResult, run_groebner
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Mode",
+    "emit_system",
+    "parse_groebner",
+    "run_groebner",
+    "GroebnerOutput",
+    "RunResult",
+    "MsolveError",
+    "MsolveInputError",
+    "MsolveOutputError",
+    "MsolveAmbiguous",
+    "MsolveVersionUnsupported",
+    "MsolveTimeout",
+    "MsolveDied",
+]

msolveio/emit.py

@@ -0,0 +1,373 @@
+"""Canonical emission of msolve ``.ms`` input files.
+
+The msolve 0.10.x parser is permissive in ways that silently change meaning:
+it accepts text it will not evaluate the way a CAS user expects, and it
+truncates oversized coefficients instead of complaining. This module refuses
+anything in that grey zone.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Sequence
+
+from .errors import MsolveInputError
+
+__all__ = ["emit_system", "MAX_TERM_VAR_PRODUCT", "MAX_CHARACTERISTIC"]
+
+#: msolve 0.10.1 indexes the exponent matrix with a 32-bit signed counter.
+#: ``total_terms * nvars`` above this bound segfaults an unpatched build, so we
+#: refuse to write such a file. Exposed as a constant so it can be lowered in
+#: tests without constructing a two-billion-term system.
+MAX_TERM_VAR_PRODUCT = 2**31 - 1
+
+#: msolve's documented prime-field range is ``2 .. 2**31 - 1``.
+MAX_CHARACTERISTIC = 2**31 - 1
+
+#: Coefficient magnitudes are read into signed 64-bit words before reduction.
+_MAX_COEFF_MAGNITUDE = 2**63 - 1
+
+_VARIABLE_RE = re.compile(r"[A-Za-z][A-Za-z0-9]*\Z")
+_TOKEN_RE = re.compile(r"[A-Za-z][A-Za-z0-9]*|[0-9]+|[+\-*/^]|\s+")
+
+_Monomial = tuple[tuple[str, int], ...]
+
+
+def emit_system(
+    polynomials: Sequence[str],
+    *,
+    variables: Sequence[str],
+    characteristic: int = 0,
+) -> str:
+    """Render a polynomial system as msolve input text.
+
+    The result is the three-part msolve file format::
+
+        x,y
+        0
+        x^2+y,
+        x*y-1
+
+    Each polynomial must already be an expanded sum of monomials. Whitespace in
+    the input strings is insignificant and is removed; nothing else about a
+    polynomial is rewritten. Any construct msolve would mis-parse -- parentheses,
+    post-monomial division, unknown identifiers, repeated monomials -- raises
+    :class:`~msolveio.MsolveInputError`.
+
+    :param polynomials: the generators, as expanded monomial sums.
+    :param variables: the variable order, which msolve echoes back in its output.
+    :param characteristic: ``0`` for Q, or a prime in ``2 .. 2**31 - 1``.
+    :raises MsolveInputError: if anything about the system is unsafe to write.
+    """
+    var_tuple = _check_variables(variables)
+    _check_characteristic(characteristic)
+
+    if isinstance(polynomials, str):
+        raise MsolveInputError(
+            "polynomials must be a sequence of strings, not a single string"
+        )
+    polys = list(polynomials)
+    if not polys:
+        raise MsolveInputError("at least one polynomial is required")
+
+    varset = set(var_tuple)
+    rendered: list[str] = []
+    total_terms = 0
+    for index, poly in enumerate(polys):
+        if not isinstance(poly, str):
+            raise MsolveInputError(
+                f"polynomial {index}: expected a string, got {type(poly).__name__}"
+            )
+        text, nterms = _check_polynomial(poly, index, varset, characteristic)
+        rendered.append(text)
+        total_terms += nterms
+
+    # Read the bound through the module global so tests can lower it.
+    bound = MAX_TERM_VAR_PRODUCT
+    product = total_terms * len(var_tuple)
+    if product > bound:
+        raise MsolveInputError(
+            f"system is too large for msolve 0.10.1: total_terms * nvars = "
+            f"{total_terms} * {len(var_tuple)} = {product} exceeds {bound}"
+        )
+
+    header = ",".join(var_tuple)
+    body = ",\n".join(rendered)
+    return f"{header}\n{characteristic}\n{body}\n"
+
+
+def _check_variables(variables: Sequence[str]) -> tuple[str, ...]:
+    if isinstance(variables, str):
+        raise MsolveInputError(
+            "variables must be a sequence of strings, not a single string"
+        )
+    var_tuple = tuple(variables)
+    if not var_tuple:
+        raise MsolveInputError("at least one variable is required")
+
+    seen: set[str] = set()
+    for name in var_tuple:
+        if not isinstance(name, str):
+            raise MsolveInputError(
+                f"variable names must be strings, got {type(name).__name__}"
+            )
+        if not name:
+            raise MsolveInputError("empty variable name")
+        if not _VARIABLE_RE.match(name):
+            raise MsolveInputError(
+                f"invalid variable name {name!r}: names must match "
+                f"[A-Za-z][A-Za-z0-9]* (no underscores, spaces, commas, or operators)"
+            )
+        if name in seen:
+            raise MsolveInputError(f"duplicate variable name {name!r}")
+        seen.add(name)
+    return var_tuple
+
+
+def _check_characteristic(characteristic: int) -> None:
+    if isinstance(characteristic, bool) or not isinstance(characteristic, int):
+        raise MsolveInputError(
+            f"characteristic must be an int, got {type(characteristic).__name__}"
+        )
+    if characteristic == 0:
+        return
+    if characteristic < 0:
+        raise MsolveInputError("characteristic must be 0 or a positive prime")
+    if characteristic == 1:
+        raise MsolveInputError("characteristic 1 is not a field")
+    if characteristic > MAX_CHARACTERISTIC:
+        raise MsolveInputError(
+            f"characteristic {characteristic} is outside msolve's prime-field "
+            f"range 2 .. {MAX_CHARACTERISTIC}"
+        )
+    if not _is_prime(characteristic):
+        raise MsolveInputError(f"characteristic {characteristic} is not prime")
+
+
+def _is_prime(n: int) -> bool:
+    """Deterministic Miller-Rabin. Exact for every n we accept (n < 2**31)."""
+    if n < 2:
+        return False
+    for p in (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37):
+        if n % p == 0:
+            return n == p
+    d = n - 1
+    r = 0
+    while d % 2 == 0:
+        d //= 2
+        r += 1
+    for a in (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37):
+        x = pow(a, d, n)
+        if x == 1 or x == n - 1:
+            continue
+        for _ in range(r - 1):
+            x = x * x % n
+            if x == n - 1:
+                break
+        else:
+            return False
+    return True
+
+
+def _tokenize(poly: str, index: int) -> list[str]:
+    tokens: list[str] = []
+    pos = 0
+    for match in _TOKEN_RE.finditer(poly):
+        if match.start() != pos:
+            bad = poly[pos : match.start()]
+            raise MsolveInputError(_bad_char_message(index, bad))
+        pos = match.end()
+        token = match.group()
+        if not token.isspace():
+            tokens.append(token)
+    if pos != len(poly):
+        raise MsolveInputError(_bad_char_message(index, poly[pos:]))
+    return tokens
+
+
+def _bad_char_message(index: int, bad: str) -> str:
+    char = bad[0]
+    if char in "()":
+        return (
+            f"polynomial {index}: parentheses are not allowed; msolve input must "
+            f"be an expanded sum of monomials"
+        )
+    if char == "_":
+        return (
+            f"polynomial {index}: '_' is not a legal msolve identifier character"
+        )
+    return f"polynomial {index}: unexpected character {char!r}"
+
+
+def _check_polynomial(
+    poly: str,
+    index: int,
+    varset: set[str],
+    characteristic: int,
+) -> tuple[str, int]:
+    """Validate one polynomial. Returns its canonical text and its term count."""
+    tokens = _tokenize(poly, index)
+    if not tokens:
+        raise MsolveInputError(f"polynomial {index}: empty polynomial")
+
+    seen: set[_Monomial] = set()
+    pos = 0
+    ntokens = len(tokens)
+    first = True
+    while pos < ntokens:
+        if tokens[pos] in ("+", "-"):
+            pos += 1
+            if pos >= ntokens:
+                raise MsolveInputError(
+                    f"polynomial {index}: trailing '{tokens[pos - 1]}'"
+                )
+        elif not first:  # unreachable: _parse_term stops only at end or a sign
+            raise MsolveInputError(
+                f"polynomial {index}: expected '+' or '-' before {tokens[pos]!r}"
+            )
+        if tokens[pos] == "*":
+            raise MsolveInputError(
+                f"polynomial {index}: term begins with '*'"
+            )
+        pos, monomial = _parse_term(tokens, pos, index, varset, characteristic)
+        if monomial in seen:
+            raise MsolveInputError(
+                f"polynomial {index}: monomial {_show_monomial(monomial)} appears "
+                f"more than once; msolve's parser is undefined on repeated "
+                f"monomials, so collect terms first"
+            )
+        seen.add(monomial)
+        first = False
+
+    return "".join(tokens), len(seen)
+
+
+def _parse_term(
+    tokens: list[str],
+    pos: int,
+    index: int,
+    varset: set[str],
+    characteristic: int,
+) -> tuple[int, _Monomial]:
+    """Parse one monomial starting at ``pos``. Returns (next position, monomial)."""
+    ntokens = len(tokens)
+    exponents: dict[str, int] = {}
+    factor = 0
+
+    while True:
+        token = tokens[pos]
+        if token.isdigit():
+            if factor != 0:
+                raise MsolveInputError(
+                    f"polynomial {index}: numeric coefficient {token} must come "
+                    f"first in its term"
+                )
+            pos = _parse_coefficient(tokens, pos, index, characteristic)
+        elif token[0].isalpha():
+            if token not in varset:
+                raise MsolveInputError(
+                    f"polynomial {index}: unknown identifier {token!r}; only "
+                    f"declared variables and integer/rational literals are allowed"
+                )
+            pos += 1
+            exponent = 1
+            if pos < ntokens and tokens[pos] == "^":
+                pos += 1
+                if pos >= ntokens or not tokens[pos].isdigit():
+                    raise MsolveInputError(
+                        f"polynomial {index}: exponent of {token!r} must be a "
+                        f"positive integer"
+                    )
+                exponent = int(tokens[pos])
+                if exponent < 1:
+                    raise MsolveInputError(
+                        f"polynomial {index}: exponent of {token!r} must be a "
+                        f"positive integer, got {exponent}"
+                    )
+                pos += 1
+            if token in exponents:
+                raise MsolveInputError(
+                    f"polynomial {index}: variable {token!r} appears twice in one "
+                    f"monomial; write it as a single power instead"
+                )
+            exponents[token] = exponent
+        elif token == "/":
+            raise MsolveInputError(
+                f"polynomial {index}: division is only allowed in a leading "
+                f"rational coefficient such as '1/2*x'"
+            )
+        else:
+            raise MsolveInputError(
+                f"polynomial {index}: unexpected {token!r}"
+            )
+
+        factor += 1
+        if pos >= ntokens or tokens[pos] in ("+", "-"):
+            break
+        if tokens[pos] == "/":
+            raise MsolveInputError(
+                f"polynomial {index}: division is only allowed in a leading "
+                f"rational coefficient such as '1/2*x'"
+            )
+        if tokens[pos] != "*":
+            raise MsolveInputError(
+                f"polynomial {index}: expected '*' between factors, got "
+                f"{tokens[pos]!r}"
+            )
+        pos += 1
+        if pos >= ntokens:
+            raise MsolveInputError(f"polynomial {index}: trailing '*'")
+        if not (tokens[pos].isdigit() or tokens[pos][0].isalpha()):
+            raise MsolveInputError(
+                f"polynomial {index}: expected a factor after '*', got "
+                f"{tokens[pos]!r}"
+            )
+
+    return pos, tuple(sorted(exponents.items()))
+
+
+def _parse_coefficient(
+    tokens: list[str],
+    pos: int,
+    index: int,
+    characteristic: int,
+) -> int:
+    ntokens = len(tokens)
+    numerator = int(tokens[pos])
+    pos += 1
+    parts = [numerator]
+
+    if pos < ntokens and tokens[pos] == "/":
+        if characteristic != 0:
+            raise MsolveInputError(
+                f"polynomial {index}: rational coefficients are not allowed over "
+                f"a prime field; reduce the coefficient modulo {characteristic} first"
+            )
+        pos += 1
+        if pos >= ntokens or not tokens[pos].isdigit():
+            raise MsolveInputError(
+                f"polynomial {index}: expected an integer denominator after '/'"
+            )
+        denominator = int(tokens[pos])
+        if denominator == 0:
+            raise MsolveInputError(f"polynomial {index}: zero denominator")
+        parts.append(denominator)
+        pos += 1
+
+    if characteristic != 0:
+        for value in parts:
+            if value > _MAX_COEFF_MAGNITUDE:
+                raise MsolveInputError(
+                    f"polynomial {index}: coefficient {value} does not fit in a "
+                    f"signed 64-bit word; msolve would truncate it instead of "
+                    f"reducing it modulo {characteristic}"
+                )
+    return pos
+
+
+def _show_monomial(monomial: _Monomial) -> str:
+    if not monomial:
+        return "1"
+    return "*".join(
+        name if exponent == 1 else f"{name}^{exponent}" for name, exponent in monomial
+    )

msolveio/errors.py

@@ -0,0 +1,76 @@
+"""Exception hierarchy for :mod:`msolveio`.
+
+Every failure mode is a distinct type. Nothing here is a warning: msolveio
+refuses ambiguous bytes rather than guessing at their meaning.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "MsolveError",
+    "MsolveInputError",
+    "MsolveOutputError",
+    "MsolveAmbiguous",
+    "MsolveVersionUnsupported",
+    "MsolveTimeout",
+    "MsolveDied",
+]
+
+
+class MsolveError(Exception):
+    """Base class for every error raised by msolveio."""
+
+
+class MsolveInputError(MsolveError):
+    """The caller asked us to emit something msolve would mis-parse.
+
+    Raised by :func:`msolveio.emit_system`. msolveio never rewrites input to
+    make it legal; it reports what is wrong and stops.
+    """
+
+
+class MsolveOutputError(MsolveError):
+    """msolve output was malformed, truncated, or not Groebner-mode output."""
+
+
+class MsolveAmbiguous(MsolveOutputError):
+    """The bytes look like output from a *different* msolve mode.
+
+    Most importantly, solver-mode output such as ``[-1]:`` is a valid-looking
+    list that means "no solutions", not "the Groebner basis is ``[-1]``".
+    Interpreting it as a basis would silently invert the answer, so this is a
+    hard error.
+    """
+
+
+class MsolveVersionUnsupported(MsolveError):
+    """The msolve binary is not a 0.10.x release (and the caller did not opt in)."""
+
+    def __init__(self, message: str, *, version: str | None = None) -> None:
+        super().__init__(message)
+        self.version = version
+
+
+class MsolveTimeout(MsolveError):
+    """msolve exceeded the caller-supplied wall-clock timeout and was killed."""
+
+    def __init__(self, message: str, *, timeout: float) -> None:
+        super().__init__(message)
+        self.timeout = timeout
+
+
+class MsolveDied(MsolveError):
+    """msolve exited nonzero, was killed by a signal, or produced no output."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        returncode: int | None = None,
+        signal: int | None = None,
+        stderr: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.returncode = returncode
+        self.signal = signal
+        self.stderr = stderr

msolveio/mode.py

@@ -0,0 +1,20 @@
+"""Output-language selector.
+
+msolve prints a different language in each mode and does not always make the
+mode obvious from the bytes. Callers name the mode they expect; v0.1 supports
+Groebner mode only. There is deliberately no ``Mode.SOLVER`` member: an enum
+value the library cannot honour would be a promise it does not keep.
+"""
+
+from __future__ import annotations
+
+import enum
+
+__all__ = ["Mode"]
+
+
+class Mode(enum.Enum):
+    """The msolve output language a caller expects."""
+
+    #: Groebner basis output, i.e. msolve invoked with ``-g 1`` or ``-g 2``.
+    GROEBNER = "groebner"

msolveio/parse.py

@@ -0,0 +1,234 @@
+"""Strict parsing of msolve 0.10.x Groebner-mode (``-g 1`` / ``-g 2``) output.
+
+msolve prints different languages in different modes, and they overlap
+syntactically. Solver mode prints ``[-1]:`` to mean "no solutions"; Groebner
+mode prints ``[1]:`` to mean "the unit ideal". Both are bracketed lists, and
+mistaking one for the other inverts the answer. So the ``#`` comment header is
+load-bearing here: it is the only thing that says which language the bytes are
+in, and this module refuses to proceed without it.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import NoReturn
+
+from .errors import MsolveAmbiguous, MsolveOutputError
+from .mode import Mode
+
+__all__ = ["GroebnerOutput", "parse_groebner"]
+
+_GB_HEADER = "#Reduced Groebner basis data"
+_LEADING_HEADER = "#Leading ideal data"
+_SEPARATOR = "#---"
+
+# `[1, <nvars>, -1, []]:` -- solver mode reporting an inconsistent system.
+_SOLVER_EMPTY_RE = re.compile(r"\[\s*1\s*,\s*\d+\s*,\s*-1\s*,\s*\[\s*\]\s*\]\s*:")
+_LENGTH_RE = re.compile(r"(\d+)\s+element")
+
+
+@dataclass(frozen=True)
+class GroebnerOutput:
+    """A parsed msolve Groebner basis.
+
+    :param unit_ideal: ``True`` iff the basis is exactly ``["1"]``, i.e. the
+        ideal is the whole ring and the system has no solutions.
+    :param basis: the basis polynomials as msolve printed them, stripped, with
+        separating commas removed. ``("1",)`` for the unit ideal.
+    :param leading_only: ``True`` iff this was ``-g 1`` output, so the entries
+        are leading monomials rather than full basis elements.
+    :param characteristic: the characteristic msolve printed. Note that msolve
+        0.10.1 labels some unlifted rational bases as characteristic 0 whether
+        or not a lift happened; this field reports what was printed, and nothing
+        more.
+    :param variables: the variable order msolve echoed back.
+    :param monomial_order: the monomial order msolve printed, verbatim.
+    """
+
+    unit_ideal: bool
+    basis: tuple[str, ...]
+    leading_only: bool
+    characteristic: int
+    variables: tuple[str, ...]
+    monomial_order: str
+
+
+def parse_groebner(text: str, *, mode: Mode = Mode.GROEBNER) -> GroebnerOutput:
+    """Parse msolve 0.10.x Groebner-mode output.
+
+    :param text: the contents of msolve's ``-o`` file, or its stdout.
+    :param mode: must be :attr:`Mode.GROEBNER`. Present so callers can state
+        which output language they believe they have; v0.1 parses no other.
+    :raises MsolveAmbiguous: if the bytes look like a different msolve mode.
+    :raises MsolveOutputError: if the bytes are not well-formed Groebner output.
+    """
+    if mode is not Mode.GROEBNER:
+        raise ValueError(f"unsupported mode {mode!r}; v0.1 parses Mode.GROEBNER only")
+    if not isinstance(text, str):
+        raise TypeError(f"expected str, got {type(text).__name__}")
+
+    lines = text.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    start = _first_content_line(lines)
+    if start is None:
+        raise MsolveOutputError("empty msolve output")
+
+    header = lines[start].strip()
+    if header.startswith(_GB_HEADER):
+        leading_only = False
+    elif header.startswith(_LEADING_HEADER):
+        leading_only = True
+    else:
+        _reject_headerless(header)
+
+    fields, body_start = _parse_header_block(lines, start)
+    basis = _parse_basis(lines, body_start)
+
+    characteristic = _require_int(fields, "field characteristic")
+    variables = _require_variables(fields)
+    monomial_order = _require_field(fields, "monomial order")
+    _check_length(fields, basis)
+
+    return GroebnerOutput(
+        unit_ideal=basis == ("1",),
+        basis=basis,
+        leading_only=leading_only,
+        characteristic=characteristic,
+        variables=variables,
+        monomial_order=monomial_order,
+    )
+
+
+def _first_content_line(lines: list[str]) -> int | None:
+    for i, line in enumerate(lines):
+        if line.strip():
+            return i
+    return None
+
+
+def _reject_headerless(header: str) -> NoReturn:
+    """Raise. Ambiguous if the bytes look like solver mode, malformed otherwise."""
+    if (
+        header.startswith("[-1")
+        or header.startswith("[0,")
+        or _SOLVER_EMPTY_RE.match(header)
+    ):
+        raise MsolveAmbiguous(
+            f"refusing to parse solver-mode output as a Groebner basis: "
+            f"{header[:60]!r}. In solver mode '[-1]:' means the system has no "
+            f"solutions; in Groebner mode the unit ideal prints as '[1]:'. "
+            f"Re-run msolve with -g 1 or -g 2."
+        )
+    raise MsolveOutputError(
+        f"missing msolve Groebner header: expected a line starting with "
+        f"{_GB_HEADER!r} or {_LEADING_HEADER!r}, got {header[:60]!r}"
+    )
+
+
+def _parse_header_block(lines: list[str], start: int) -> tuple[dict[str, str], int]:
+    """Parse ``#---`` / fields / ``#---``. Returns the fields and the body index."""
+    pos = start + 1
+    if pos >= len(lines) or lines[pos].strip() != _SEPARATOR:
+        got = lines[pos].strip() if pos < len(lines) else "<end of output>"
+        raise MsolveOutputError(
+            f"malformed msolve header: expected {_SEPARATOR!r} after the header "
+            f"line, got {got[:60]!r}"
+        )
+    pos += 1
+
+    fields: dict[str, str] = {}
+    while pos < len(lines):
+        line = lines[pos].strip()
+        if line == _SEPARATOR:
+            return fields, pos + 1
+        if not line.startswith("#"):
+            raise MsolveOutputError(
+                f"malformed msolve header: expected a '#' field line or "
+                f"{_SEPARATOR!r}, got {line[:60]!r}"
+            )
+        key, sep, value = line[1:].partition(":")
+        if not sep:
+            raise MsolveOutputError(
+                f"malformed msolve header field: {line[:60]!r}"
+            )
+        fields[key.strip().lower()] = value.strip()
+        pos += 1
+
+    raise MsolveOutputError(
+        f"truncated msolve output: header block was never closed with {_SEPARATOR!r}"
+    )
+
+
+def _parse_basis(lines: list[str], body_start: int) -> tuple[str, ...]:
+    body = "\n".join(lines[body_start:]).strip()
+    if not body:
+        raise MsolveOutputError(
+            "truncated msolve output: header present but no basis body"
+        )
+    if not body.startswith("["):
+        raise MsolveOutputError(
+            f"malformed msolve basis: expected '[', got {body[:60]!r}"
+        )
+    if not body.endswith("]:"):
+        if "]:" in body:
+            raise MsolveOutputError(
+                "malformed msolve output: unexpected trailing content after ']:'"
+            )
+        raise MsolveOutputError(
+            "truncated msolve output: basis list is not closed with ']:'"
+        )
+
+    inner = body[1:-2]
+    if not inner.strip():
+        raise MsolveOutputError("malformed msolve basis: empty list")
+
+    entries = []
+    for raw in inner.split(","):
+        entry = raw.strip()
+        if not entry:
+            raise MsolveOutputError(
+                "malformed msolve basis: empty entry (stray comma)"
+            )
+        entries.append(entry)
+    return tuple(entries)
+
+
+def _require_field(fields: dict[str, str], key: str) -> str:
+    if key not in fields:
+        raise MsolveOutputError(f"missing '#{key}' in msolve header")
+    value = fields[key]
+    if not value:
+        raise MsolveOutputError(f"empty '#{key}' in msolve header")
+    return value
+
+
+def _require_int(fields: dict[str, str], key: str) -> int:
+    value = _require_field(fields, key)
+    try:
+        return int(value)
+    except ValueError:
+        raise MsolveOutputError(
+            f"'#{key}' is not an integer: {value[:60]!r}"
+        ) from None
+
+
+def _require_variables(fields: dict[str, str]) -> tuple[str, ...]:
+    value = _require_field(fields, "variable order")
+    variables = tuple(part.strip() for part in value.split(","))
+    if any(not name for name in variables):
+        raise MsolveOutputError(f"malformed '#variable order': {value[:60]!r}")
+    return variables
+
+
+def _check_length(fields: dict[str, str], basis: tuple[str, ...]) -> None:
+    """Cross-check the printed basis length against what we actually read."""
+    value = _require_field(fields, "length of basis")
+    match = _LENGTH_RE.search(value)
+    if match is None:
+        raise MsolveOutputError(f"malformed '#length of basis': {value[:60]!r}")
+    declared = int(match.group(1))
+    if declared != len(basis):
+        raise MsolveOutputError(
+            f"msolve declared {declared} basis element(s) but {len(basis)} were "
+            f"parsed; the output is truncated or corrupt"
+        )

msolveio/run.py

@@ -0,0 +1,236 @@
+"""Subprocess wrapper around the msolve CLI.
+
+Runs msolve with stdin closed, a mandatory timeout, and a version gate, then
+hands the output to :func:`msolveio.parse_groebner`. Nothing here interprets
+msolve's bytes itself.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import shutil
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from .errors import MsolveDied, MsolveTimeout, MsolveVersionUnsupported
+from .mode import Mode
+from .parse import GroebnerOutput, parse_groebner
+
+__all__ = ["RunResult", "run_groebner", "SUPPORTED_VERSION_PREFIX"]
+
+#: The only msolve series v0.1 claims to understand.
+SUPPORTED_VERSION_PREFIX = "0.10."
+
+_VERSION_RE = re.compile(r"\b(\d+\.\d+(?:\.\d+)?)\b")
+_VERSION_PROBE_TIMEOUT = 20.0
+
+
+@dataclass(frozen=True)
+class RunResult:
+    """Everything one msolve invocation produced, plus how it was produced.
+
+    :param output: the parsed Groebner basis.
+    :param argv: the exact command line, with the temp paths msolve saw.
+    :param msolve_version: the version string reported by ``msolve --version``,
+        or ``"unknown"`` when the probe failed under ``allow_unknown_version``.
+    :param wall_seconds: wall-clock time for the solve, excluding the probe.
+    :param returncode: msolve's exit status.
+    :param stderr: msolve's captured stderr.
+    :param input_sha256: SHA-256 of the ``.ms`` bytes written to disk.
+    :param output_sha256: SHA-256 of the output-file bytes read back.
+    """
+
+    output: GroebnerOutput
+    argv: tuple[str, ...]
+    msolve_version: str
+    wall_seconds: float
+    returncode: int
+    stderr: str
+    input_sha256: str
+    output_sha256: str
+
+
+def run_groebner(
+    source: str,
+    *,
+    gb: Literal[1, 2] = 2,
+    timeout: float,
+    threads: int = 1,
+    binary: str | Path | None = None,
+    allow_unknown_version: bool = False,
+    mode: Mode = Mode.GROEBNER,
+) -> RunResult:
+    """Run msolve in Groebner mode on ``source`` and parse the result.
+
+    :param source: msolve input text, normally from :func:`msolveio.emit_system`.
+    :param gb: ``2`` for the reduced Groebner basis, ``1`` for the leading ideal.
+    :param timeout: wall-clock limit in seconds. Required; there is no default,
+        because an unbounded Groebner computation is not a thing to opt into by
+        accident.
+    :param threads: value for msolve's ``-t``.
+    :param binary: path to the msolve executable. Defaults to
+        ``shutil.which("msolve")``.
+    :param allow_unknown_version: run anyway if the binary is not 0.10.x. The
+        parser is written against 0.10.x output and may reject or misread others.
+    :param mode: must be :attr:`Mode.GROEBNER`.
+    :raises MsolveVersionUnsupported: if the version gate fails.
+    :raises MsolveTimeout: if msolve exceeded ``timeout``.
+    :raises MsolveDied: if msolve exited nonzero, took a signal, or wrote nothing.
+    :raises MsolveOutputError: if msolve's output is not well-formed.
+    """
+    if mode is not Mode.GROEBNER:
+        raise ValueError(f"unsupported mode {mode!r}; v0.1 runs Mode.GROEBNER only")
+    if gb not in (1, 2):
+        raise ValueError(f"gb must be 1 or 2, got {gb!r}")
+    if not isinstance(threads, int) or isinstance(threads, bool) or threads < 1:
+        raise ValueError(f"threads must be a positive int, got {threads!r}")
+    if not isinstance(timeout, (int, float)) or isinstance(timeout, bool):
+        raise TypeError(f"timeout must be a number, got {type(timeout).__name__}")
+    if timeout <= 0:
+        raise ValueError(f"timeout must be positive, got {timeout!r}")
+    if not isinstance(source, str):
+        raise TypeError(f"source must be str, got {type(source).__name__}")
+
+    executable = _resolve_binary(binary)
+    version = _check_version(executable, allow_unknown_version)
+
+    payload = source.encode("utf-8")
+    with tempfile.TemporaryDirectory(prefix="msolveio-") as tmp:
+        in_path = Path(tmp) / "system.ms"
+        out_path = Path(tmp) / "basis.out"
+        in_path.write_bytes(payload)
+
+        argv = (
+            executable,
+            "-g",
+            str(gb),
+            "-f",
+            str(in_path),
+            "-o",
+            str(out_path),
+            "-t",
+            str(threads),
+        )
+
+        started = time.monotonic()
+        try:
+            completed = subprocess.run(
+                argv,
+                stdin=subprocess.DEVNULL,
+                capture_output=True,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise MsolveTimeout(
+                f"msolve exceeded the {timeout}s timeout and was killed",
+                timeout=float(timeout),
+            ) from exc
+        except OSError as exc:
+            raise MsolveDied(f"could not execute {executable!r}: {exc}") from exc
+        wall_seconds = time.monotonic() - started
+
+        stderr = completed.stderr.decode("utf-8", errors="replace")
+        _check_exit(completed.returncode, argv, stderr)
+
+        raw = out_path.read_bytes() if out_path.exists() else b""
+        if not raw.strip():
+            # Fall back to stdout: some builds print the basis rather than
+            # writing it when the output file cannot be produced.
+            raw = completed.stdout
+
+    if not raw.strip():
+        raise MsolveDied(
+            "msolve exited 0 but produced no output",
+            returncode=completed.returncode,
+            stderr=stderr,
+        )
+
+    text = raw.decode("utf-8", errors="replace")
+    output = parse_groebner(text, mode=mode)
+
+    return RunResult(
+        output=output,
+        argv=argv,
+        msolve_version=version,
+        wall_seconds=wall_seconds,
+        returncode=completed.returncode,
+        stderr=stderr,
+        input_sha256=hashlib.sha256(payload).hexdigest(),
+        output_sha256=hashlib.sha256(raw).hexdigest(),
+    )
+
+
+def _resolve_binary(binary: str | Path | None) -> str:
+    if binary is None:
+        found = shutil.which("msolve")
+        if found is None:
+            raise MsolveDied(
+                "no msolve binary found on PATH; install msolve 0.10.x or pass "
+                "binary=..."
+            )
+        return found
+    return str(binary)
+
+
+def _check_exit(returncode: int, argv: tuple[str, ...], stderr: str) -> None:
+    if returncode == 0:
+        return
+    if returncode < 0:
+        raise MsolveDied(
+            f"msolve was killed by signal {-returncode}"
+            + (f": {stderr.strip()[:200]}" if stderr.strip() else ""),
+            returncode=returncode,
+            signal=-returncode,
+            stderr=stderr,
+        )
+    raise MsolveDied(
+        f"msolve exited with status {returncode}"
+        + (f": {stderr.strip()[:200]}" if stderr.strip() else ""),
+        returncode=returncode,
+        stderr=stderr,
+    )
+
+
+def _check_version(executable: str, allow_unknown_version: bool) -> str:
+    """Probe ``msolve --version``. Returns the version string it reported."""
+    try:
+        probe = subprocess.run(
+            [executable, "--version"],
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+            timeout=_VERSION_PROBE_TIMEOUT,
+            check=False,
+        )
+        blob = (probe.stdout + b"\n" + probe.stderr).decode("utf-8", errors="replace")
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        if allow_unknown_version:
+            return "unknown"
+        raise MsolveVersionUnsupported(
+            f"could not determine the version of {executable!r}: {exc}. Pass "
+            f"allow_unknown_version=True to run anyway."
+        ) from exc
+
+    match = _VERSION_RE.search(blob)
+    if match is None:
+        if allow_unknown_version:
+            return "unknown"
+        raise MsolveVersionUnsupported(
+            f"{executable!r} did not report a recognizable version. Pass "
+            f"allow_unknown_version=True to run anyway."
+        )
+
+    version = match.group(1)
+    if not version.startswith(SUPPORTED_VERSION_PREFIX) and not allow_unknown_version:
+        raise MsolveVersionUnsupported(
+            f"msolve {version} is not supported; msolveio v0.1 targets "
+            f"{SUPPORTED_VERSION_PREFIX}x output. Pass "
+            f"allow_unknown_version=True to run anyway.",
+            version=version,
+        )
+    return version

msolveio-0.1.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: msolveio
+Version: 0.1.0
+Summary: Strict Python I/O for msolve: canonical input, mode-required output.
+Author: DC Posch
+License: MIT
+Project-URL: Homepage, https://github.com/dcposch/msolveio
+Project-URL: Source, https://github.com/dcposch/msolveio
+Keywords: msolve,groebner,polynomial,computer-algebra
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# msolveio
+
+Strict Python I/O for msolve: canonical input, mode-required output.
+Gröbner-mode (`-g`) only in v0.1. Solver-mode bytes are rejected, not interpreted.
+
+msolveio writes `.ms` files that msolve 0.10.x will parse the way you meant, and reads back
+only the one output language it can identify with certainty. It is not a CAS and not a
+Gröbner engine.
+
+## Install
+
+```
+pip install msolveio
+```
+
+You also need a system `msolve` 0.10.x binary on `PATH` (or pass `binary=`). msolveio has no
+runtime dependencies.
+
+## Usage
+
+```python
+from msolveio import emit_system, parse_groebner, run_groebner, MsolveAmbiguous
+
+source = emit_system(
+    ["x^2+y", "x*y-1"],
+    variables=["x", "y"],
+    characteristic=0,
+)
+
+result = run_groebner(source, gb=2, timeout=60)
+
+print(result.output.unit_ideal)  # False
+print(result.output.basis)       # ('y^2+x', 'x*y-1', 'x^2+y')
+print(result.msolve_version)     # '0.10.1'
+```
+
+`emit_system` raises `MsolveInputError` rather than rewriting input: parentheses,
+post-monomial division (`x/2`), repeated monomials, unknown identifiers, and coefficients
+that would overflow msolve's 64-bit read are all refused. Leading rationals (`1/2*x`) are
+allowed over Q only.
+
+`parse_groebner` requires msolve's `#` comment header. That header is the only thing in the
+bytes that says which mode produced them, so it is load-bearing. Feeding it solver output
+raises `MsolveAmbiguous` instead of returning a basis:
+
+```python
+parse_groebner("[-1]:")  # MsolveAmbiguous
+```
+
+This matters because the two languages invert each other. In solver mode `[-1]:` means *no
+solutions*; in Gröbner mode the unit ideal — the same fact — prints as `[1]:`. A parser that
+guesses gets the answer exactly backwards.
+
+## Not supported in v0.1
+
+- Solver mode, real-root isolation, and `-P` parametrization output — these raise, and are
+  never interpreted as a basis.
+- JSON output, Macaulay2 format, or any other msolve serialization.
+- sympy / flint / numpy interop. Basis elements are returned as strings, exactly as msolve
+  printed them. Nothing is `eval`'d.
+
+## A note on characteristic
+
+msolve 0.10.1 labels some unlifted rational Gröbner bases as characteristic 0 regardless of
+whether a lift to Q actually happened. `GroebnerOutput.characteristic` reports what msolve
+printed and nothing more; msolveio does not pretend to know better.
+
+## License
+
+MIT © 2026 DC Posch — <https://github.com/dcposch/msolveio>

msolveio-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+msolveio/__init__.py,sha256=bWPGDDzlqcYpogO-Y6o6S0yAXBsScnAvwo1ZCWe28Fc,1035
+msolveio/emit.py,sha256=2vf9XgkI9N1LAMMgt0GCVujMV98ozORMf0j5fdtd_Bw,13017
+msolveio/errors.py,sha256=xyuBW2aDzAYrANmnBspaBXypigcxzW01uHVUX7QW_ao,2168
+msolveio/mode.py,sha256=ChPjg-hwvzqHh72HMs_b-QSFZOZBCnLWQbpzjwP3uEU,588
+msolveio/parse.py,sha256=QeqtIGgJW9ZZnyWZ81EuNlt_pjWBMwpcYJP0Yi8uQso,8586
+msolveio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+msolveio/run.py,sha256=oaRSXzAqwd_lZEQOrOoJCfTwf64uKJ6JjZJ6MXEjJUM,8367
+msolveio-0.1.0.dist-info/licenses/LICENSE,sha256=FevCuy6qOnFNl21jI0io0OCoi82mi0dAvboCzFNkPAc,1065
+msolveio-0.1.0.dist-info/METADATA,sha256=ujDv0LIAjhoLD8bPDpx_nsbasm-YEI3QdL9BvD1nrZA,3219
+msolveio-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+msolveio-0.1.0.dist-info/top_level.txt,sha256=WG3OY_xYkzhNScI8nrpvo8HClmaImUgaDpwplsSgMgo,9
+msolveio-0.1.0.dist-info/RECORD,,

msolveio-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

msolveio-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DC Posch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

msolveio-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+msolveio