mathspec 0.1.0__py3-none-any.whl

mathspec/_yaml.py

@@ -0,0 +1,141 @@
+# SPDX-FileCopyrightText: mathspec Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""How this project reads a YAML file.
+
+`yaml.safe_load` implements YAML 1.1, and two of its rules are wrong for a
+language whose scalars are user data; both are fixed here:
+
+- **1.2 booleans.** ``on``/``off``/``yes``/``no``/``y``/``n`` are ordinary
+  names in this language — a country code as a dimension, a mode as a relation.
+  YAML 1.1 resolves them to ``True``/``False``; only ``true``/``false`` are
+  booleans here, which is the YAML 1.2 core schema.
+- **Duplicate keys.** 1.1 lets the last one win silently, discarding a
+  declaration the file plainly contains.
+
+The output is plain ``dict``/``str``: no loader wrapper reaches the schema
+or the AST.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml
+
+from mathspec.errors import SchemaError
+
+#: The YAML 1.2 core-schema boolean set — nothing else resolves to a bool.
+_BOOL_1_2 = re.compile(r'^(?:true|True|TRUE|false|False|FALSE)$')
+
+
+if TYPE_CHECKING:
+    # Typed as SafeLoader: typeshed declares CSafeLoader unconditionally, and a PyYAML without libyaml lacks it.
+    _BaseLoader = yaml.SafeLoader
+else:
+    # Same document either way: both drive the Python Resolver and SafeConstructor.
+    _BaseLoader = getattr(yaml, 'CSafeLoader', yaml.SafeLoader)
+
+
+class _StrictLoader(_BaseLoader):
+    """SafeLoader with 1.2 booleans. Duplicate keys are checked on the nodes."""
+
+
+# Rebuilt rather than edited: the table is inherited, and mutating it reconfigures PyYAML process-wide.
+_StrictLoader.yaml_implicit_resolvers = {
+    ch: [(tag, rx) for tag, rx in pairs if tag != 'tag:yaml.org,2002:bool']
+    for ch, pairs in _BaseLoader.yaml_implicit_resolvers.items()
+}
+_StrictLoader.add_implicit_resolver('tag:yaml.org,2002:bool', _BOOL_1_2, list('tTfF'))
+
+
+#: PyYAML's tag for ``<<:``, the one key a mapping may carry more than once.
+_MERGE = 'tag:yaml.org,2002:merge'
+
+
+def _check_duplicate_keys(node: yaml.Node, origin: str) -> None:
+    """Reject a mapping that declares the same key twice, or a key that is not a scalar.
+
+    Checked on the node tree before construction, so a ``<<:`` merge key that
+    a mapping overrides is not a duplicate — the override is the point — and
+    two merge keys are two merges, which PyYAML accumulates.
+    """
+    if isinstance(node, yaml.MappingNode):
+        seen: dict[str, int] = {}
+        pairs: list[tuple[yaml.Node, yaml.Node]] = node.value
+        for key_node, value_node in pairs:
+            line = key_node.start_mark.line + 1
+            if not isinstance(key_node, yaml.ScalarNode):
+                msg = f'{origin}:{line}: a key must be a scalar — a name, not a list or a mapping.'
+                raise SchemaError(msg)
+            key = key_node.value
+            if key_node.tag == _MERGE:
+                _check_duplicate_keys(value_node, origin)
+                continue
+            if key in seen:
+                msg = (
+                    f'{origin}:{line}: duplicate key {key!r} — first declared on '
+                    f'line {seen[key]}. YAML would silently keep the last one, '
+                    f'discarding a declaration the file contains.'
+                )
+                raise SchemaError(msg)
+            seen[key] = line
+            _check_duplicate_keys(value_node, origin)
+    elif isinstance(node, yaml.SequenceNode):
+        for item in node.value:
+            _check_duplicate_keys(item, origin)
+
+
+def read_yaml(path: Path | str) -> dict[str, object]:
+    """Read *path* off disk and parse it, in YAML 1.2's reading of scalars."""
+    return parse_yaml(Path(path).read_text(encoding='utf-8'), str(path))
+
+
+def read_model(model: str | Path) -> dict[str, object]:
+    """A model from a file or from its text — a newline decides which a ``str`` is.
+
+    A :class:`~pathlib.Path` names a file, and so does a ``str`` with no
+    newline in it, since no path holds one; a ``str`` with a newline is the
+    YAML itself, which every file and every ``to_yaml()`` ends with. Nothing
+    else is read off the content and nothing is read off the disk to decide.
+
+    Raises:
+        FileNotFoundError: A ``str`` with no newline that names no file — a
+            one-line text is told to end with one.
+    """
+    if isinstance(model, str) and '\n' not in model and not Path(model).is_file():
+        msg = (
+            f'no file named {model!r}. A str with no newline in it is read as a path, and YAML text '
+            f'is told apart by one — end the text with a newline, or pass a Path.'
+        )
+        raise FileNotFoundError(msg)
+    if isinstance(model, Path) or '\n' not in model:
+        return read_yaml(Path(model))
+    return parse_yaml(model, 'YAML text')
+
+
+def parse_yaml(text: str, origin: str = '<string>') -> dict[str, object]:
+    """Parse YAML *text* as a mapping of sections.
+
+    Args:
+        text: The YAML source.
+        origin: What a load error calls this source — a file's path, or the default for text that never was one.
+    """
+    loader = _StrictLoader(text)
+    try:
+        node = loader.get_single_node()
+        if node is None:
+            return {}
+        _check_duplicate_keys(node, origin)
+        data = loader.construct_document(node)
+    finally:
+        loader.dispose()
+    if not data:
+        return {}
+    if not isinstance(data, dict):
+        msg = f'{origin}: a model file must be a mapping of sections (dimensions:, variables:, …), got {type(data).__name__}.'
+        raise SchemaError(msg)
+    return data

mathspec/advice.py

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: mathspec Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Advice — what is decidable without data and is a note rather than a refusal.
+
+One door, :func:`advice`, over every pass of that kind.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mathspec.boundedness import unbounded_notes
+from mathspec.errors import Advice
+from mathspec.program import GroupSum, Program, Pullback, walk
+from mathspec.validation import to_spec
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+    from mathspec.model import Spec
+
+
+def advice(model: str | Path | Mapping[str, object] | Spec | Program) -> tuple[Advice, ...]:
+    """Everything the language advises about *model* — never an error, decidable without data.
+
+    Args:
+        model: A YAML path, a mapping, a loaded :class:`Spec`, or a
+            :class:`Program`, read as it arrived. A ``piecewise:`` or ``sos:``
+            block is read as the rows it states, so the answer is the one its
+            expansion gets, with nothing expanded.
+
+    Returns:
+        The never-an-axis advice in declaration order, then the unboundedness
+        advice; ``str()`` of each is its sentence.
+    """
+    program = model if isinstance(model, Program) else to_spec(model).program
+    return tuple(_never_an_axis(program) + unbounded_notes(program))
+
+
+def _never_an_axis(program: Program) -> list[Advice]:
+    """One piece of advice per dimension nothing reaches.
+
+    A dimension a relation has a column over is reached: its members are the
+    labels that column is checked against, and a ``where`` selects on them,
+    so it is in use even where nothing is indexed by it.
+    """
+    reached: set[str] = set()
+    for declaration in (*program.parameters.values(), *program.variables.values(), *program.constraints.values()):
+        reached.update(declaration.dims)
+    reached |= _produced_axes(program)
+    reached |= {dim for lk in program.relations.values() for dim in lk.dims}
+
+    return [
+        Advice(
+            'never-an-axis',
+            name,
+            f"dimension '{name}' is never used: nothing is indexed by it, nothing "
+            f'aggregates into it, and no relation has a column over it. Remove it — or keep it '
+            f'knowingly, if the declarations that use it are still to be written.',
+        )
+        for name in program.dimensions
+        if name not in reached
+    ]
+
+
+def _produced_axes(program: Program) -> set[str]:
+    """The axes the expressions create beyond what any declaration indexes.
+
+    ``sum(by=)`` lands on its target and ``at()`` spreads onto its fine
+    dimension: either way, the dims the direction produces.
+    """
+    axes: set[str] = set()
+    for node in walk(*program.roots):
+        if isinstance(node, GroupSum | Pullback):
+            axes.update(node.direction.produced_dims)
+    return axes

mathspec/boundedness.py

@@ -0,0 +1,168 @@
+# SPDX-FileCopyrightText: mathspec Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Provably unbounded models, named before a solver says a bare ``unbounded``.
+
+A variable unbounded on the side its objective term improves toward, and named
+by no constraint, runs to infinity for any data. Which side is read off the
+sign the variable enters the objective with: under ``minimize`` a ``+v`` term
+runs down toward ``lower``. Where that sign is not decidable without data — a
+parameter coefficient, or occurrences of both signs — nothing is claimed.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal, assert_never
+
+from mathspec.errors import Advice
+from mathspec.program import (
+    Add,
+    Cases,
+    Constant,
+    Divide,
+    Dual,
+    Expression,
+    GroupSum,
+    Multiply,
+    Named,
+    Negate,
+    Parameter,
+    Power,
+    Pullback,
+    Sum,
+    Translate,
+    Variable,
+    WindowSum,
+    children,
+    variables_of,
+)
+
+if TYPE_CHECKING:
+    from mathspec.program import Program, VariableDeclaration
+
+#: The sign a term carries into the objective, or ``None`` where the file does
+#: not decide it: a parameter coefficient (which may be zero), a variable
+#: appearing with both signs (which may cancel), a divisor carrying one.
+Sign = Literal['+', '-'] | None
+
+#: Which of a variable's two bounds a term drives it toward.
+BoundSide = Literal['lower', 'upper']
+
+
+def unbounded_notes(program: Program) -> list[Advice]:
+    """Name every variable the objective can drive to infinity unopposed.
+
+    Args:
+        program: The program as it is. A curve's links and a set's variable
+            count as named by a row, as the rows they expand into would be.
+
+    Returns:
+        One note per variable that is unbounded on the side its objective term
+        improves toward and named by no constraint.
+    """
+    if program.objective is None:
+        return []
+
+    constrained = {block.variable for block in program.sos.values()}
+    for curve in program.piecewise.values():
+        constrained |= variables_of(*(link.expression for link in curve.links))
+    for constraint in program.constraints.values():
+        constrained |= variables_of(constraint.lhs, constraint.rhs)
+
+    signs: dict[str, Sign] = {}
+    _record_signs(program.objective.expression, '+', signs)
+
+    minimize = program.objective.sense == 'minimize'
+    notes: list[Advice] = []
+    for vname, sign in signs.items():
+        if sign is None or vname in constrained:
+            continue
+        side: BoundSide = 'lower' if minimize == (sign == '+') else 'upper'
+        if _is_open(program.variables[vname], side):
+            notes.append(
+                Advice(
+                    'unbounded',
+                    vname,
+                    f"Variable '{vname}' makes this model unbounded: no constraint names it, and "
+                    f'bounds.{side} is open, which is the direction a {sign}{vname} term '
+                    f'improves a {program.objective.sense} objective in. No data can change that, so '
+                    f'the solve would answer `unbounded` and name nothing.\n'
+                    f'Give it a finite bounds.{side}, or the constraint that was meant to define it.',
+                )
+            )
+    return notes
+
+
+def _is_open(vdef: VariableDeclaration, side: BoundSide) -> bool:
+    """Whether *vdef* states no bound on *side*.
+
+    A bound naming a parameter is finite or not by data, so it does not count.
+    """
+    return (vdef.lower if side == 'lower' else vdef.upper) is None
+
+
+def _flip(sign: Sign) -> Sign:
+    return None if sign is None else ('-' if sign == '+' else '+')
+
+
+def _times(sign: Sign, other: Sign) -> Sign:
+    return None if sign is None or other is None else ('+' if sign == other else '-')
+
+
+def _coefficient_sign(node: Expression) -> Sign:
+    """The sign *node* scales a term by, or ``None`` unless it is a signed constant.
+
+    ``-2`` lowers to a negation over a constant, so the sign of a literal
+    coefficient is not always on the node itself, and a named one is its
+    body's. Zero is ``None`` on purpose: a term multiplied away is not in the
+    objective, so the variable it names is driven nowhere.
+    """
+    if isinstance(node, Negate):
+        return _flip(_coefficient_sign(node.operand))
+    if isinstance(node, Named):
+        return _coefficient_sign(node.body)
+    if isinstance(node, Constant) and node.value != 0:
+        return '+' if node.value > 0 else '-'
+    return None
+
+
+def _record_signs(node: Expression, sign: Sign, signs: dict[str, Sign]) -> None:
+    """Record the sign each variable under *node* carries into the objective.
+
+    A variable reached twice with different signs, or once with an undecidable
+    one, lands on ``None``, which claims nothing. A reduction, a re-index, a
+    window and a cases selection pass *sign* to their children unchanged; a
+    power carries no sign in either half. A Constant, Parameter or Dual is a
+    variable-free leaf and contributes nothing — the Dual arm only keeps the
+    walk exhaustive, since the loader refuses one in any objective.
+    """
+    if isinstance(node, Variable):
+        signs[node.name] = sign if signs.setdefault(node.name, sign) == sign else None
+        return
+    if isinstance(node, Constant | Parameter | Dual):
+        return
+    if isinstance(node, Negate):
+        _record_signs(node.operand, _flip(sign), signs)
+        return
+    if isinstance(node, Add):
+        _record_signs(node.left, sign, signs)
+        _record_signs(node.right, sign, signs)
+        return
+    if isinstance(node, Multiply):
+        _record_signs(node.left, _times(sign, _coefficient_sign(node.right)), signs)
+        _record_signs(node.right, _times(sign, _coefficient_sign(node.left)), signs)
+        return
+    if isinstance(node, Divide):
+        _record_signs(node.numerator, _times(sign, _coefficient_sign(node.divisor)), signs)
+        _record_signs(node.divisor, None, signs)
+        return
+    if isinstance(node, Power):
+        _record_signs(node.base, None, signs)
+        _record_signs(node.exponent, None, signs)
+        return
+    if isinstance(node, Sum | GroupSum | Pullback | Translate | WindowSum | Cases | Named):
+        for child in children(node):
+            _record_signs(child, sign, signs)
+        return
+    assert_never(node)

mathspec/degree.py

@@ -0,0 +1,209 @@
+# SPDX-FileCopyrightText: mathspec Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Degree — the one admissibility rule that is a scope choice (docs/about/limits.md).
+
+**Degree 2 in the math, degree 1 in what stands beside it.** An objective and a
+constraint both take ``variable * variable``; a *bound* and a ``piecewise:``
+link do not — each of those is read affinely. An ``expressions:`` entry is not
+degree-checked at declaration at all: the math reading it is checked where it
+reads, at that position's own ceiling, and an entry the math never reads
+(``ExpressionDeclaration.in_math``) is held to no degree.
+
+A degree-2 product has a second rule: **at most one factor may be a sum of
+terms**. ``sum(x, over=i) * sum(y, over=j)`` is a cross join whose size the
+file states nowhere. Factors carrying *different dims* are not that: ``x[i] *
+y[j]`` broadcasts.
+
+A divisor's **shape** is decided here too: a quotient is multiplication by one
+reciprocal factor, so a divisor that adds is refused at load, where the message
+can name the rewrite.
+"""
+
+from __future__ import annotations
+
+from mathspec.errors import LanguageError
+from mathspec.program import (
+    Add,
+    Divide,
+    Dual,
+    Expression,
+    GroupSum,
+    Multiply,
+    Power,
+    Sum,
+    Variable,
+    WindowSum,
+    carries_variable,
+    children,
+    walk,
+)
+
+
+def _adds(node: Expression) -> bool:
+    """Whether *node* adds anywhere inside it.
+
+    Anywhere, not only at its head: every operator over a variable-free
+    expression maps over its parts rather than folding them, so an addition
+    under a ``sum`` or a product reaches the quotient as two factors just as
+    one at the top does.
+    """
+    return any(isinstance(found, Add) for found in walk(node))
+
+
+def check_binary(node: Multiply | Divide | Power, context: str, *, ceiling: int) -> None:
+    """Check that *node* stays inside the degree its position allows.
+
+    Args:
+        node: The product, quotient or power to judge.
+        context: What to name in the message — the declaration being read.
+        ceiling: The highest degree this position can honour — 2 in an
+            objective or a constraint, 1 everywhere else.
+
+    Raises:
+        LanguageError: A product of two variable-carrying factors where the
+            position allows only degree 1 or where both factors are sums of
+            terms, a power over anything carrying a variable, a divisor carrying
+            a variable or adding.
+    """
+    where = f'{context}: ' if context else ''
+    if isinstance(node, Power):
+        if carries_variable(node):
+            raise LanguageError(_a_variable_under_a_power_message(where))
+        if _adds(node.base) or _adds(node.exponent):
+            raise LanguageError(
+                f'{where}a base and an exponent must each be a single Constant/Parameter factor, '
+                f'not a sum — addition does not distribute over `**`, so `(1 + rate) ** period` is '
+                f'refused where `growth ** period` is not. Declare the factor itself as a parameter.'
+            )
+        return
+    if isinstance(node, Divide):
+        if carries_variable(node.divisor):
+            raise LanguageError(
+                f'{where}the divisor contains variables, which is not affine. '
+                f'Divide by a parameter, or precompute the reciprocal as one.'
+            )
+        if _adds(node.divisor):
+            raise LanguageError(
+                f'{where}a divisor must be a single Constant/Parameter factor, '
+                f'not a sum — rewrite as multiplication by a precomputed parameter'
+            )
+        return
+    if not (carries_variable(node.left) and carries_variable(node.right)):
+        return
+    if ceiling < 2:
+        raise LanguageError(_degree_two_here_message(where))
+    if (degree := _degree(node)) > ceiling:
+        raise LanguageError(_above_the_ceiling_message(where, degree))
+    _check_single_term_factor(node, where)
+
+
+def _degree(node: Expression) -> int:
+    """The polynomial degree *node* stands for, counted structurally.
+
+    A product adds its factors' degrees and a division keeps the dividend's
+    (:func:`check_binary` has already refused a divisor carrying a variable);
+    everything else — a sum, a reduction, a shape operator — is the highest
+    degree beneath it. No data, so this answers at ``check`` time, which is
+    what stops a cubic from reaching a consumer to be refused by whichever one
+    happens to notice.
+    """
+    if isinstance(node, Variable):
+        return 1
+    if isinstance(node, Multiply):
+        return _degree(node.left) + _degree(node.right)
+    if isinstance(node, Divide):
+        return _degree(node.numerator)
+    return max((_degree(child) for child in children(node)), default=0)
+
+
+def _above_the_ceiling_message(where: str, degree: int) -> str:
+    """About the product's own degree, since ``p * p * p`` is two admissible products nested."""
+    return (
+        f'{where}this product is degree {degree}. The language takes degree 2 and nothing above it.\n'
+        f'Multiply by a parameter instead, or give the inner product a name — a variable '
+        f'constrained to equal it is degree 1 wherever it is used.'
+    )
+
+
+def _a_variable_under_a_power_message(where: str) -> str:
+    return (
+        f'{where}`**` is not in the language over variables: it takes a base and an exponent that '
+        f'carry none.\n'
+        f'Write the product out — `x * x` for a square — or precompute the factor as a parameter. '
+        f'A variable base above degree 2 has no rewrite at all, and one whose exponent is data has '
+        f'no degree until the data arrives — see docs/about/limits.md.'
+    )
+
+
+def _degree_two_here_message(where: str) -> str:
+    return (
+        f'{where}both factors of a product contain variables, which is degree 2. '
+        f'The **objective and constraints** take that; a bound and a piecewise: '
+        f'link do not — each of those is read affinely by something '
+        f'downstream.\n'
+        f'Multiply the variable by a parameter instead, or state the product where '
+        f'it can stand: as a constraint of its own, with a variable holding the '
+        f'result.'
+    )
+
+
+def _check_single_term_factor(node: Multiply, where: str) -> None:
+    """Refuse a degree-2 product of two multi-term factors."""
+    if not (_multi_term(node.left) and _multi_term(node.right)):
+        return
+    raise LanguageError(
+        f'{where}both factors of this product are sums of more than one term, so it is an outer '
+        f'product — every term of one against every term of the other, and nothing in the file '
+        f'says how many that is.\n'
+        f'Multiply *before* reducing (``sum(x * y, over=d)`` rather than '
+        f'``sum(x, over=d) * sum(y, over=d)``).'
+    )
+
+
+def _multi_term(node: Expression) -> bool:
+    """Whether *node* stands for more than one variable term at a coordinate.
+
+    A reduction does, and so does an addition of two variable-carrying
+    operands; a product is multi-term exactly when one of its factors is, a
+    coefficient not multiplying the count. Structural, so it needs no data.
+    """
+    return any(_joins_terms(found) for found in walk(node))
+
+
+def _joins_terms(node: Expression) -> bool:
+    """Whether *node* itself makes several terms of one: a reduction over a variable, or a sum of two variable-carrying sides.
+
+    A pullback and a translation re-index and are not reductions: they move a
+    term, leaving one term where there was one.
+    """
+    if isinstance(node, Sum | GroupSum | WindowSum):
+        return carries_variable(node.operand)
+    return isinstance(node, Add) and carries_variable(node.left) and carries_variable(node.right)
+
+
+def check_expression(node: Expression, context: str, *, ceiling: int = 1) -> None:
+    """What the math admits at one position: no dual anywhere under *node*, then :func:`check_binary` everywhere in it.
+
+    Asked of the resolved tree, so a dual or a product reached through a
+    macro or a named expression is caught alongside one written in place.
+    What a plan node can represent is the consumer's question, not this one's.
+
+    Raises:
+        LanguageError: A dual, which exists only after a solve; or what
+            :func:`check_binary` refuses.
+    """
+    for found in walk(node):
+        if isinstance(found, Dual):
+            raise LanguageError(
+                f'{context}: a dual exists only after a solve; the math cannot read one — '
+                f'keep the entry that carries it out of constraints, the objective, bounds and where.'
+            )
+        if isinstance(found, Multiply | Divide | Power):
+            check_binary(found, context, ceiling=ceiling)
+
+
+def calls_dual(node: Expression) -> bool:
+    """Whether a :class:`~mathspec.program.Dual` stands anywhere under *node*."""
+    return any(isinstance(found, Dual) for found in walk(node))