mathspec 0.1.0__py3-none-any.whl

mathspec/sos.py

@@ -0,0 +1,159 @@
+# SPDX-FileCopyrightText: mathspec Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Expand ``sos:`` blocks into the binaries and rows that state the same restriction.
+
+A set becomes ordinary declarations under names prefixed with the block's own,
+the way a ``piecewise:`` block becomes weights and rows; what it emits is
+tabled in ``docs/reference/language/piecewise.md``. An unpicked member is held
+at zero from both sides, so the rewrite states the same feasible set whatever
+sign the member takes — what it needs is a coefficient on each side, which a
+model declaring a set without is refused at load for
+(:meth:`mathspec.model.Spec` validates it) rather than here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from mathspec.model import Spec
+
+if TYPE_CHECKING:
+    from mathspec.program import SosType
+
+#: One member's two linking coefficients, below and above. ``None`` on a side is
+#: a side the model leaves open, where no rewrite can hold the member at zero.
+Coefficients = tuple[float | str | None, float | str | None]
+
+
+def coefficients(domain: str, lower: float | str | None, upper: float | str | None) -> Coefficients:
+    """What a member's two linking rows multiply its binary by, ``None`` on a side the model leaves open.
+
+    The 0 and 1 a binary's domain fixes, which no bounds block carries;
+    otherwise the member's own declared bounds, each a number or the name of a
+    parameter. A parameter is a coefficient like any other: it is what the row
+    multiplies by, and no rewrite needs to know its value. Nothing else is a
+    coefficient: a number below the bound would cap a picked member the set
+    does not cap, and one above it is a looser row than the bound already
+    states.
+    """
+    if domain == 'binary':
+        return 0.0, 1.0
+    return lower, upper
+
+
+@dataclass(frozen=True)
+class Emitted:
+    """Every name one set's expansion writes, spelled once for the emitter and the collision check.
+
+    The linking row is named after what it says, which the two orders do not
+    share: order 2 admits a member in either half of one segment, and order 1
+    admits it alone. ``below`` is the same row from underneath, written only
+    where the member may be nonzero below zero.
+    """
+
+    seg: str
+    pick: str
+    link: str
+
+    @classmethod
+    def of(cls, name: str, order: SosType) -> Emitted:
+        """The names set *name* of *order* writes."""
+        admits = 'adjacency' if order == 2 else 'nonzero'
+        return cls(f'{name}_seg', f'{name}_pick', f'{name}_{admits}')
+
+    @property
+    def below(self) -> str:
+        """The linking row from underneath."""
+        return f'{self.link}_below'
+
+    @property
+    def by_kind(self) -> tuple[tuple[str, tuple[str, ...]], ...]:
+        """Each name by the kind of declaration it would collide with."""
+        return (('variable', (self.seg,)), ('constraint', (self.pick, self.link, self.below)))
+
+
+#: What the binary says, per order — the description its legend entry carries.
+_SEGMENTS = {
+    1: 'a binary per member, 1 where that member may be nonzero',
+    2: 'a binary per segment, 1 where the two members it spans may be nonzero',
+}
+
+
+def expand_sets(schema: Spec) -> Spec:
+    """*schema* with every ``sos:`` block written out as binaries and the rows that link them.
+
+    The curves an expansion wrote out ride along, because a model whose
+    curves are already written out is the one this is usually asked of.
+    """
+    raw = schema.model_dump()
+    for name in list(schema.sos):
+        emit(raw, name)
+    return Spec.model_validate(raw)
+
+
+def emit(raw: dict[str, object], name: str) -> None:
+    """Write what the set *name* states as declarations of *raw*, and drop the block.
+
+    Args:
+        raw: A model as data, mid-expansion, declaring the set and the variable
+            it runs over.
+        name: Which set to lower.
+    """
+    sets = section(raw, 'sos')
+    block = sets.pop(name)
+    assert isinstance(block, dict), 'a validated model carries each set as a mapping'
+    variable, over, order = block['variable'], block['along'], block['type']
+    member = section(raw, 'variables')[variable]
+    assert isinstance(member, dict), 'a validated model carries each variable as a mapping'
+    dims = list(member['dims'])
+    emitted = Emitted.of(name, order)
+
+    section(raw, 'variables')[emitted.seg] = {
+        'dims': dims,
+        **({'where': member['where']} if member.get('where') else {}),
+        'domain': 'binary',
+        'description': _SEGMENTS[order],
+    }
+    picked = emitted.seg if order == 1 else f'{emitted.seg} + shift({emitted.seg}, along={over}, offset=1, edge=0)'
+    constraints = section(raw, 'constraints')
+    constraints[emitted.pick] = {
+        'dims': [d for d in dims if d != over],
+        'expression': f'sum({emitted.seg}, over={over}) <= 1',
+    }
+    below, above = _coefficients(member)
+    constraints[emitted.link] = {'dims': dims, 'expression': f'{variable} <= {_scaled(above, picked)}'}
+    if below != 0.0:
+        constraints[emitted.below] = {'dims': dims, 'expression': f'{variable} >= {_scaled(below, picked)}'}
+
+
+def _scaled(factor: float | str, picked: str) -> str:
+    """The binaries a member is admitted by, times *factor*.
+
+    A coefficient of 1 is left out. It is the common one — a weight and a binary
+    are both bounded by 1 — and ``x <= 1 * (seg)`` is a factor every reader of
+    the row has to work out means nothing.
+    """
+    return f'({picked})' if factor == 1.0 else f'{factor} * ({picked})'
+
+
+def _coefficients(member: dict[str, object]) -> tuple[float | str, float | str]:
+    """The two coefficients as an expression writes them, read off the member."""
+    declared = member.get('bounds')
+    assert declared is None or isinstance(declared, dict), 'a validated model carries a bounds block as a mapping'
+    lower, upper = (declared.get('lower'), declared.get('upper')) if declared else (None, None)
+    assert isinstance(lower, float | str | None) and isinstance(upper, float | str | None), (
+        'a bound is a number, the name of a parameter, or open'
+    )
+    below, above = coefficients(str(member.get('domain', 'continuous')), lower, upper)
+    assert below is not None and above is not None, 'a set with a side left open is refused at load'
+    return below, above
+
+
+def section(raw: dict[str, object], name: str) -> dict[str, object]:
+    """The *name* section of the raw model, created empty where the file declares none."""
+    section = raw.setdefault(name, {})
+    assert isinstance(section, dict), f'{name}: is a mapping in a validated model'
+    return section

mathspec/typesetting/README.md

@@ -0,0 +1,110 @@
+<!--
+SPDX-FileCopyrightText: mathspec Contributors
+SPDX-License-Identifier: MIT
+-->
+
+# `typesetting/` — the model, printed
+
+This package is a consumer of the program. It builds no model and attaches no
+data. It walks a program, the one a loaded `Spec` holds or one handed to it,
+and prints it.
+
+| Module        | Role                                                                                                   |
+| ------------- | ------------------------------------------------------------------------------------------------------ |
+| `__init__.py` | `typeset` / `to_latex` / `to_markdown` / `to_typst`, `typeset_declaration`, and the `FORMATS` registry |
+| `walk.py`     | the program's trees to `Line`s. Every decision about the **math**, written once                        |
+| `legend.py`   | the notes under the equations, read off what the program uses                                          |
+| `format.py`   | the boundary: what a format must spell, and the operator vocabulary                                    |
+| `symbols.py`  | which symbol a name gets, and the `SymbolTable` sidecar that overrides it                              |
+| `latex.py`    | amsmath, the format that lands in a journal                                                            |
+| `typst.py`    | Typst, the format that compiles without a toolchain                                                    |
+| `markdown.py` | GitHub-flavoured Markdown: LaTeX math, with a Markdown document layer                                  |
+
+## Why the walk and the formats are separate files
+
+`walk.py` makes the decisions about the math. It decides where a bracket changes
+the reading, which dimension a reduction binds, that a mask belongs on the ∀
+rather than in the equation, and that a translation shows at the leaf it
+re-indexes.
+
+A `Format` makes a much smaller decision: that a sum is written `\sum_{…}` or
+`sum_(…)`.
+
+Those are different questions, and they live in different files. With one
+module, the second format becomes a _copy of the walk_. Two copies of a walk are
+two walks that can disagree about what the model says. That matters more here
+than it looks, because a typeset model is what a reader checks the math against.
+
+Two rules keep the split honest:
+
+- **A walk emits bare math.** No `$`, and no environment. The format wraps the
+  math with `math()` when it embeds it in prose, so the walk never knows which
+  mode it is in.
+- **A format spells; it never decides.** No method in `format.py` takes a
+  syntax-tree node or a schema. If a format had to look at the model to answer a
+  question, that question belongs in the walk.
+
+## Notation
+
+Symbols are derived by default, so a model prints with no setup at all.
+
+A `SymbolTable` overrides the derived symbols. `symbols=` takes the table in
+whichever form the caller already has. The `--symbols` flag on the command line
+is the path case:
+
+```python
+mathspec.to_latex('dispatch.yaml', symbols='dispatch.symbols.yaml')  # a path
+mathspec.to_latex('dispatch.yaml', symbols={'notation': 'latex', 'names': {'load': r'\ell'}})  # a dict
+mathspec.to_latex('dispatch.yaml', symbols=mathspec.SymbolTable.load(table))  # the object
+```
+
+The dict has the same sections as the file, which are `notation`, `dimensions`
+and `names`. It is what the YAML parses to, and not a flat `{name: symbol}` map.
+
+Whichever form you use, the table is checked against the model. A key that names
+nothing is an error, and the message gives the near miss. Without that check, a
+silent typo would be a symbol that never applies, and a reader who never finds
+out.
+
+Every value is a spelling, and it is printed exactly as written. Nothing parses
+or translates it. `notation` says which language the table is written in, and a
+format that reads the other language refuses the table. Everything past that
+comparison is the caller's business.
+
+The table carries **notation only**. What a declaration _is_, which is the prose
+in the right-hand column of the legend, comes from the model's own
+`description:`, read straight off the block. That is the model talking about
+itself, rather than a reader choosing symbols.
+
+A description travels with the file, survives a rename, and needs no sidecar.
+The price is that it has to be plain prose, because every format sets the same
+words.
+
+## Adding a format
+
+1. Add a module here with a class that satisfies `Format`. That means atoms,
+   structure, document, and a spelling for every name in `OPERATOR_NAMES`.
+2. Add a row to `FORMATS` in `__init__.py`. The command-line verb comes from the
+   key.
+3. Change nothing in `walk.py`. If you find that you need to, then either the
+   walk is making a syntax decision that it should not make, or `format.py` is
+   missing a method. Fix that, rather than adding a special case.
+
+`markdown.py` is the cheap case. Markdown has no math of its own, so it
+subclasses `LatexFormat` and overrides only the document layer.
+
+`tests/typesetting/test_typeset.py` runs the shared expectations against
+**every** entry in `FORMATS`, so a new format inherits the whole suite. Two of
+those expectations are the point: every operator name is spelled, and no format
+leaks another format's syntax.
+
+## What CI checks, and what it cannot
+
+LaTeX and Typst are **compiled** in CI, not just matched as strings. LaTeX needs
+a two-package apt install. Typst is a pip wheel, so the suite compiles it
+in-process.
+
+The structural checks run as well. Those check brace balance, environment
+nesting, and `\left` and `\right` pairing, which are the things a _generator_
+gets wrong. But a structural check is not a compile. A malformed `\mathcal`
+passes every one of them.

mathspec/typesetting/__init__.py

@@ -0,0 +1,223 @@
+# SPDX-FileCopyrightText: mathspec Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Typeset a validated model — a *reading* of the math.
+
+Symbols are **derived** by default, aiming at unambiguous rather than
+beautiful, so it prints with no setup; a
+:class:`~mathspec.typesetting.symbols.SymbolTable` (``--symbols``) makes it
+conventional. It does not line-break: a wide equation runs off the page.
+
+Usage::
+
+    import mathspec
+
+    print(mathspec.to_latex('model.yaml'))
+    print(mathspec.to_typst('model.yaml', standalone=True))
+    print(mathspec.to_markdown('model.yaml'))  # renders as-is on GitHub
+    print(mathspec.to_latex('model.yaml', symbols='model.symbols.yaml'))
+
+or from a shell::
+
+    python -m mathspec latex model.yaml --symbols model.symbols.yaml --standalone -o model.tex
+    python -m mathspec typst model.yaml --standalone -o model.typ
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal, TypedDict, Unpack
+
+from mathspec.program import Program
+from mathspec.typesetting.latex import LatexFormat
+from mathspec.typesetting.legend import Legend, notice
+from mathspec.typesetting.markdown import MarkdownFormat
+from mathspec.typesetting.symbols import SymbolTable, symbols_for
+from mathspec.typesetting.typst import TypstFormat
+from mathspec.typesetting.walk import Walk
+from mathspec.validation import to_spec
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+    from mathspec.model import Spec
+    from mathspec.typesetting.format import Format
+
+__all__ = [
+    'FORMATS',
+    'FormatName',
+    'SymbolTable',
+    'to_latex',
+    'to_markdown',
+    'to_typst',
+    'typeset',
+    'typeset_declaration',
+]
+
+#: A format by the name the CLI takes — what every renderer here is asked for.
+FormatName = Literal['latex', 'markdown', 'typst']
+
+#: Every format, by name. Adding one is a module plus a row.
+FORMATS: dict[FormatName, Format] = {
+    'latex': LatexFormat(),
+    'markdown': MarkdownFormat(),
+    'typst': TypstFormat(),
+}
+
+
+class _Options(TypedDict, total=False):
+    """The keyword arguments :func:`typeset` takes, which the three per-format doors forward whole."""
+
+    symbols: str | Path | Mapping[str, object] | SymbolTable | None
+    standalone: bool
+    legend: bool
+    numbered: bool
+    inline_expressions: bool
+
+
+def _walk(
+    model: str | Path | Mapping[str, object] | Spec | Program,
+    fmt: FormatName,
+    symbols: str | Path | Mapping[str, object] | SymbolTable | None,
+    *,
+    inline_expressions: bool,
+) -> Walk:
+    """The loaded, symbol-resolved walk every renderer builds from model, format and table."""
+    if fmt not in FORMATS:
+        msg = f"'{fmt}' is not a format this package prints. Formats: {', '.join(FORMATS)}."
+        raise ValueError(msg)
+    program = model if isinstance(model, Program) else to_spec(model).program
+    format_ = FORMATS[fmt]
+    if symbols is None:
+        symbols = SymbolTable(format_.notation)
+    table = symbols if isinstance(symbols, SymbolTable) else SymbolTable.load(symbols)
+    return Walk(
+        program,
+        symbols_for(program, format_, table.checked_against(program)),
+        format_,
+        inline_expressions=inline_expressions,
+    )
+
+
+def typeset(
+    model: str | Path | Mapping[str, object] | Spec | Program,
+    fmt: FormatName,
+    *,
+    symbols: str | Path | Mapping[str, object] | SymbolTable | None = None,
+    standalone: bool = False,
+    legend: bool = True,
+    numbered: bool = True,
+    inline_expressions: bool = False,
+) -> str:
+    """Render *model*'s math in *fmt*.
+
+    Args:
+        model: Anything :func:`mathspec.to_spec` accepts, or a
+            :class:`~mathspec.program.Program`. A ``Spec`` or a ``Program``
+            is rendered as it stands, so printing one model in several formats
+            reads and checks the file once rather than once per format, and a
+            curve prints as the curve it states. Pass ``spec.expand()`` for the rows a solver holds
+            instead.
+        fmt: What spells the math — a key of :data:`FORMATS`.
+        symbols: How names print, as a :class:`SymbolTable`, a path or a
+            mapping. Names it does not carry are derived, and it must be
+            written in *fmt*'s notation.
+        standalone: Emit a compilable document rather than a fragment.
+        legend: Prepend the sets/parameters/variables table. The model's own
+            ``description:`` opens the document either way — it is what the
+            file says it is, not a symbol table.
+        numbered: Number the equations.
+        inline_expressions: Substitute each plain named expression into the equations that
+            use it, rather than printing its symbol there and its definition
+            once. A cased expression is a definition either way: its block is
+            taller than the line it would sit in.
+
+    Returns:
+        The rendered text.
+
+    Raises:
+        ValueError: *fmt* names no format.
+        LanguageError: A model that does not compile; it does not print.
+        SchemaError: A symbol table entry naming nothing in the model, or a
+            table written in a notation *fmt* does not read.
+    """
+    walk = _walk(model, fmt, symbols, inline_expressions=inline_expressions)
+    program, format_ = walk.program, walk.format
+
+    rendered = [
+        format_.section(title, format_.equations(lines, numbered=numbered))
+        for title, lines in walk.equations()
+        if lines
+    ]
+
+    blocks = [format_.note(format_.escape(program.description))] if program.description else []
+    if legend:
+        explained, noticed = Legend(program, walk.symbols, format_), notice(program)
+        blocks += [
+            format_.section(title, format_.glossary(entries))
+            for title, entries in explained.glossaries(noticed, walk.defined())
+        ]
+        blocks += [format_.note(text) for text in explained.convention_notes()]
+        blocks += [format_.note(text) for text in explained.translation_notes(noticed)]
+        blocks += [format_.note(text) for text in explained.position_notes(noticed)]
+    return format_.document([*blocks, *rendered], standalone=standalone)
+
+
+def typeset_declaration(
+    model: str | Path | Mapping[str, object] | Spec | Program,
+    name: str,
+    fmt: FormatName,
+    *,
+    symbols: str | Path | Mapping[str, object] | SymbolTable | None = None,
+    inline_expressions: bool = True,
+) -> str:
+    """Render one declaration as the bare line the document prints for it.
+
+    The line the whole-model render prints for it — a named expression's
+    definition, a constraint, an assumption, a ``piecewise:`` curve, or a
+    variable's domain, quantifier included —
+    with no document, label, equation number or math delimiters around it, for
+    a math context the caller lays out: a docstring, a table cell. A line on
+    its own has no Definitions section beside it, so the plain named
+    expressions it uses are substituted unless *inline_expressions* says otherwise; a cased
+    one prints by symbol, and a second call with its name prints its block.
+
+    Args:
+        model: Anything :func:`mathspec.to_spec` accepts, or a :class:`~mathspec.program.Program`.
+        name: A named expression, constraint, assumption, ``piecewise:``
+            block or variable the model declares.
+        fmt: What spells the math — a key of :data:`FORMATS`.
+        symbols: How names print; see :func:`typeset`.
+        inline_expressions: Substitute the plain named expressions the line uses, so it
+            stands on its own; ``False`` prints their symbols, as the document
+            does. A plain expression asked for by name prints its definition
+            either way.
+
+    Returns:
+        The line, math only.
+
+    Raises:
+        ValueError: *fmt* names no format.
+        LanguageError: A model that does not compile; it does not print.
+        SchemaError: *name* is declared as none of the five, or as two — a
+            constraint may share a variable's name; or a symbol table entry
+            names nothing in the model.
+    """
+    walk = _walk(model, fmt, symbols, inline_expressions=inline_expressions)
+    return walk.format.equation(walk.line(name))
+
+
+def to_latex(model: str | Path | Mapping[str, object] | Spec | Program, **options: Unpack[_Options]) -> str:
+    """Render *model* as LaTeX (amsmath ``align``). See :func:`typeset`."""
+    return typeset(model, 'latex', **options)
+
+
+def to_typst(model: str | Path | Mapping[str, object] | Spec | Program, **options: Unpack[_Options]) -> str:
+    """Render *model* as Typst. See :func:`typeset`."""
+    return typeset(model, 'typst', **options)
+
+
+def to_markdown(model: str | Path | Mapping[str, object] | Spec | Program, **options: Unpack[_Options]) -> str:
+    """Render *model* as GitHub-flavoured Markdown. See :func:`typeset`."""
+    return typeset(model, 'markdown', **options)