mathspec 0.2.1__tar.gz → 0.3.0__tar.gz

{mathspec-0.2.1 → mathspec-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mathspec
-Version: 0.2.1
+Version: 0.3.0
 Summary: Write the specification (spec) of an optimisation model as a YAML file. Check it and print it as math, with no data and no solver.
 Project-URL: Documentation, https://mathspec.readthedocs.io
 Project-URL: Repository, https://github.com/energy-models/mathspec
@@ -43,11 +43,11 @@ SPDX-License-Identifier: CC-BY-4.0
 **Write the specification (spec) of an optimisation model as a YAML file. Check it and print it
 as math, with no data and no solver.**
 
-A mathspec file states a specification, or spec. A spec declares four things: the axes it runs
-over, such as `snapshot` and `generator`; the data it expects, such as `load`
-and `cost`; the decisions the solver makes, such as `dispatch`; and the rules
-those decisions obey, such as `sum(dispatch, over=generator) == load`. The file
-[below](#example) is a complete spec.
+A spec declares four things: the dimensions it runs over, such as `snapshot`
+and `generator`; the data it expects, such as `load` and `cost`; the decisions
+the solver makes, such as `dispatch`; and the rules those decisions obey, such
+as `sum(dispatch, over=generator) == load`. The file [below](#example) is a
+complete spec.
 
 <!--- --8<-- [start:benefits] -->
 
@@ -114,6 +114,14 @@ Markdown is one of three formats, and GitHub renders it here.
 
 Least-cost dispatch of a generator fleet against an hourly load.
 
+#### Variable domains
+
+**`dispatch`**
+
+```math
+0 \le \mathit{dispatch}_{t,g} \le \mathrm{capacity}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \,:\, \mathrm{capacity}_{g} > 0
+```
+
 #### Objective
 
 ```math
@@ -128,14 +136,6 @@ Least-cost dispatch of a generator fleet against an hourly load.
 \sum_{g \in \mathcal{G}} \mathit{dispatch}_{t,g} = \mathrm{load}_{t} \qquad \forall\, t \in \mathcal{T}
 ```
 
-#### Variable domains
-
-**`dispatch`**
-
-```math
-0 \le \mathit{dispatch}_{t,g} \le \mathrm{capacity}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \,:\, \mathrm{capacity}_{g} > 0
-```
-
 <details>
 <summary>The whole document: a symbol table, and the legend it prints</summary>
 
@@ -162,6 +162,12 @@ Least-cost dispatch of a generator fleet against an hourly load.
 |---|---|
 | $`\mathit{dispatch}`$ | `dispatch` over $`\mathcal{S} \times \mathcal{G}`$ — output of a generator in a snapshot |
 
+#### Variable domains
+
+**`dispatch`**
+
+$`0 \le \mathit{dispatch}_{s,g} \le \bar p_{g} \qquad \forall\, s \in \mathcal{S},\ g \in \mathcal{G} \,:\, \bar p_{g} > 0`$
+
 #### Objective
 
 $`\min \sum_{s \in \mathcal{S},\ g \in \mathcal{G}} \mathit{dispatch}_{s,g} \cdot c_{g}`$
@@ -172,12 +178,6 @@ $`\min \sum_{s \in \mathcal{S},\ g \in \mathcal{G}} \mathit{dispatch}_{s,g} \cdo
 
 $`\sum_{g \in \mathcal{G}} \mathit{dispatch}_{s,g} = \ell_{s} \qquad \forall\, s \in \mathcal{S}`$
 
-#### Variable domains
-
-**`dispatch`**
-
-$`0 \le \mathit{dispatch}_{s,g} \le \bar p_{g} \qquad \forall\, s \in \mathcal{S},\ g \in \mathcal{G} \,:\, \bar p_{g} > 0`$
-
 </details>
 
 <!-- readme-math:end -->
@@ -203,7 +203,7 @@ conventional spelling, as in the folded block.
 
 <!--- --8<-- [start:engines] -->
 
-mathspec builds nothing and solves nothing itself.
+mathspec builds nothing and solves nothing itself. Instead,
 [specsolve](https://github.com/fluxopt/specsolve) and
 [linopy](https://github.com/PyPSA/linopy) build a model from a spec and its
 data, and solve it. Support in both is work in progress. Any other tool can
@@ -240,11 +240,10 @@ See [installation](https://mathspec.readthedocs.io/en/latest/howto/installation/
 ## Prior art
 
 Every file under `src/` was written in [specsolve](https://github.com/fluxopt/specsolve)
-and extracted here. The keys themselves,
-which are YAML math, a block per component, `dims:` and a `where:` string,
-come from [Calliope](https://github.com/calliope-project/calliope).
-[linopy](https://github.com/PyPSA/linopy) supplies the vocabulary that
-`sum(over=)` and the dimension rules are named against.
+and extracted here. The keys come from
+[Calliope](https://github.com/calliope-project/calliope): math in YAML, one
+block per component, `dims:` and a `where:` string. `sum(over=)` and the
+dimension rules take their names from [linopy](https://github.com/PyPSA/linopy).
 
 ## Status
 
@@ -255,9 +254,9 @@ Alpha, pre-1.0.
 **Breaking changes land without a deprecation cycle.** Pin an exact version if
 you depend on this, and read the
 [changelog](https://github.com/energy-models/mathspec/blob/main/CHANGELOG.md)
-before upgrading. Every construct round-trips through the schema, the parsers
-and all three typeset formats, and the LaTeX is compiled. The accepted YAML is
-not yet frozen.
+before upgrading. The test suite passes every construct through the schema,
+the parsers and all three typeset formats, and compiles the LaTeX. The YAML that
+mathspec accepts can still change.
 
 <!--- --8<-- [end:status] -->
 

{mathspec-0.2.1 → mathspec-0.3.0}/README.md

@@ -18,11 +18,11 @@ SPDX-License-Identifier: CC-BY-4.0
 **Write the specification (spec) of an optimisation model as a YAML file. Check it and print it
 as math, with no data and no solver.**
 
-A mathspec file states a specification, or spec. A spec declares four things: the axes it runs
-over, such as `snapshot` and `generator`; the data it expects, such as `load`
-and `cost`; the decisions the solver makes, such as `dispatch`; and the rules
-those decisions obey, such as `sum(dispatch, over=generator) == load`. The file
-[below](#example) is a complete spec.
+A spec declares four things: the dimensions it runs over, such as `snapshot`
+and `generator`; the data it expects, such as `load` and `cost`; the decisions
+the solver makes, such as `dispatch`; and the rules those decisions obey, such
+as `sum(dispatch, over=generator) == load`. The file [below](#example) is a
+complete spec.
 
 <!--- --8<-- [start:benefits] -->
 
@@ -89,6 +89,14 @@ Markdown is one of three formats, and GitHub renders it here.
 
 Least-cost dispatch of a generator fleet against an hourly load.
 
+#### Variable domains
+
+**`dispatch`**
+
+```math
+0 \le \mathit{dispatch}_{t,g} \le \mathrm{capacity}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \,:\, \mathrm{capacity}_{g} > 0
+```
+
 #### Objective
 
 ```math
@@ -103,14 +111,6 @@ Least-cost dispatch of a generator fleet against an hourly load.
 \sum_{g \in \mathcal{G}} \mathit{dispatch}_{t,g} = \mathrm{load}_{t} \qquad \forall\, t \in \mathcal{T}
 ```
 
-#### Variable domains
-
-**`dispatch`**
-
-```math
-0 \le \mathit{dispatch}_{t,g} \le \mathrm{capacity}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \,:\, \mathrm{capacity}_{g} > 0
-```
-
 <details>
 <summary>The whole document: a symbol table, and the legend it prints</summary>
 
@@ -137,6 +137,12 @@ Least-cost dispatch of a generator fleet against an hourly load.
 |---|---|
 | $`\mathit{dispatch}`$ | `dispatch` over $`\mathcal{S} \times \mathcal{G}`$ — output of a generator in a snapshot |
 
+#### Variable domains
+
+**`dispatch`**
+
+$`0 \le \mathit{dispatch}_{s,g} \le \bar p_{g} \qquad \forall\, s \in \mathcal{S},\ g \in \mathcal{G} \,:\, \bar p_{g} > 0`$
+
 #### Objective
 
 $`\min \sum_{s \in \mathcal{S},\ g \in \mathcal{G}} \mathit{dispatch}_{s,g} \cdot c_{g}`$
@@ -147,12 +153,6 @@ $`\min \sum_{s \in \mathcal{S},\ g \in \mathcal{G}} \mathit{dispatch}_{s,g} \cdo
 
 $`\sum_{g \in \mathcal{G}} \mathit{dispatch}_{s,g} = \ell_{s} \qquad \forall\, s \in \mathcal{S}`$
 
-#### Variable domains
-
-**`dispatch`**
-
-$`0 \le \mathit{dispatch}_{s,g} \le \bar p_{g} \qquad \forall\, s \in \mathcal{S},\ g \in \mathcal{G} \,:\, \bar p_{g} > 0`$
-
 </details>
 
 <!-- readme-math:end -->
@@ -178,7 +178,7 @@ conventional spelling, as in the folded block.
 
 <!--- --8<-- [start:engines] -->
 
-mathspec builds nothing and solves nothing itself.
+mathspec builds nothing and solves nothing itself. Instead,
 [specsolve](https://github.com/fluxopt/specsolve) and
 [linopy](https://github.com/PyPSA/linopy) build a model from a spec and its
 data, and solve it. Support in both is work in progress. Any other tool can
@@ -215,11 +215,10 @@ See [installation](https://mathspec.readthedocs.io/en/latest/howto/installation/
 ## Prior art
 
 Every file under `src/` was written in [specsolve](https://github.com/fluxopt/specsolve)
-and extracted here. The keys themselves,
-which are YAML math, a block per component, `dims:` and a `where:` string,
-come from [Calliope](https://github.com/calliope-project/calliope).
-[linopy](https://github.com/PyPSA/linopy) supplies the vocabulary that
-`sum(over=)` and the dimension rules are named against.
+and extracted here. The keys come from
+[Calliope](https://github.com/calliope-project/calliope): math in YAML, one
+block per component, `dims:` and a `where:` string. `sum(over=)` and the
+dimension rules take their names from [linopy](https://github.com/PyPSA/linopy).
 
 ## Status
 
@@ -230,9 +229,9 @@ Alpha, pre-1.0.
 **Breaking changes land without a deprecation cycle.** Pin an exact version if
 you depend on this, and read the
 [changelog](https://github.com/energy-models/mathspec/blob/main/CHANGELOG.md)
-before upgrading. Every construct round-trips through the schema, the parsers
-and all three typeset formats, and the LaTeX is compiled. The accepted YAML is
-not yet frozen.
+before upgrading. The test suite passes every construct through the schema,
+the parsers and all three typeset formats, and compiles the LaTeX. The YAML that
+mathspec accepts can still change.
 
 <!--- --8<-- [end:status] -->
 

{mathspec-0.2.1 → mathspec-0.3.0}/src/mathspec/__init__.py

@@ -4,21 +4,26 @@
 
 """The language: what a YAML file may say, and what it means.
 
-Two public states — a [`Spec`][] is what the file *says*,
-and its [`program`][mathspec.spec.Spec.program] is what it *means* — and
-[`to_spec`][], the one door to both. Everything between them — both grammars
-and the tree they build — is package-private, because a consumer reads a
-program instead.
+The top level is what a consumer calls: [`to_spec`][], the one door to a
+file, and the verbs over what it returns. The rest of the surface is three
+modules, each with one rule:
+
+- [`mathspec.spec`][] is what the file *says*: [`Spec`][mathspec.spec.Spec]
+  and the blocks it holds.
+- [`mathspec.program`][] is what the file *means*: the
+  [`Program`][mathspec.program.Program] a spec lowers to, its nodes, and the
+  [`Advice`][mathspec.program.Advice] the language gives about it.
+- [`mathspec.errors`][] is what a consumer catches.
+
+Everything between them — both grammars and the tree they build — is
+package-private, because a consumer reads a program instead.
 """
 
-from mathspec import program
+from mathspec import errors, program, spec
 from mathspec.advising import advice
 from mathspec.composition import merge, override
-from mathspec.errors import Advice, AdviceKind, DimensionError, LanguageError, MathSpecError, SchemaError, did_you_mean
-from mathspec.operators import BUILTIN_NAMES
-from mathspec.spec import Spec
 from mathspec.typesetting import (
-    FORMATS,
+    FormatName,
     SymbolTable,
     to_latex,
     to_markdown,
@@ -29,21 +34,14 @@ from mathspec.typesetting import (
 from mathspec.validation import to_spec
 
 __all__ = [
-    'BUILTIN_NAMES',
-    'FORMATS',
-    'Advice',
-    'AdviceKind',
-    'DimensionError',
-    'LanguageError',
-    'MathSpecError',
-    'SchemaError',
-    'Spec',
+    'FormatName',
     'SymbolTable',
     'advice',
-    'did_you_mean',
+    'errors',
     'merge',
     'override',
     'program',
+    'spec',
     'to_latex',
     'to_markdown',
     'to_spec',

{mathspec-0.2.1 → mathspec-0.3.0}/src/mathspec/_expression_parser.py

@@ -23,23 +23,23 @@ from mathspec.errors import SchemaError
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator, Mapping
 
-#: The relation a comparison may carry — the three an expression may be
-#: written with, which is what a constraint's sense is read off.
+#: The three comparison operators an expression may use. A constraint reads
+#: its sense from this operator.
 ComparisonOperator = Literal['<=', '>=', '==']
 
 #: The sign a unary operator applies to its operand.
 UnaryOperator = Literal['+', '-']
 
-#: The arithmetic a binary operator may spell. Closed by the grammar, and the
-#: vocabulary a renderer dispatching on [`BinaryOperatorNode.op`][]
-#: switches over — it keeps no list of its own.
+#: The arithmetic a binary operator may spell. The grammar closes the set, and
+#: a renderer that dispatches on [`BinaryOperatorNode.op`][] switches over it
+#: and keeps no list of its own.
 BinaryOperator = Literal['+', '-', '*', '/', '**']
 
 #: What an expression writes to refer to a declaration, and so what a
 #: declaration may be named.
 NAME = r'[a-zA-Z_][a-zA-Z0-9_]*'
 
-#: A float — a fractional part or an exponent. A sign is the unary operator's.
+#: A float has a fractional part or an exponent. The unary operator carries the sign.
 REAL = r'\d+\.\d*([eE][+-]?\d+)?|\d+[eE][+-]?\d+'
 
 # ---------------------------------------------------------------------------
@@ -79,6 +79,22 @@ class NameListNode:
         return shown(self.names)
 
 
+@dataclass(frozen=True)
+class ColumnsNode:
+    """Columns of one relation in a kwarg value — ``sum(x, over=g, by=gen_bus[bus])``.
+
+    The relation is written once and its columns after it, so one call cannot
+    name columns of two tables. Unresolved: which columns the kwarg admits is
+    the operator's business.
+    """
+
+    relation: str
+    columns: tuple[str, ...]
+
+    def __str__(self) -> str:
+        return f'{self.relation}[{", ".join(self.columns)}]'
+
+
 @dataclass(frozen=True)
 class KeywordNode:
     """A quoted closed keyword in a kwarg value — ``shift(..., edge='wrap')``.
@@ -131,10 +147,18 @@ class FunctionCallNode:
         return f'{self.name}({", ".join(passed)})'
 
 
-#: Every arithmetic node the grammar builds. A name, a name list and a quoted
-#: keyword are what resolution reads for their kind; the rest is structure.
+#: Every arithmetic node the grammar builds. A name, a name list, a column
+#: selection and a quoted keyword are what resolution reads for their kind; the
+#: rest is structure.
 ArithmeticNode = (
-    NumberNode | NameNode | NameListNode | KeywordNode | UnaryOperatorNode | BinaryOperatorNode | FunctionCallNode
+    NumberNode
+    | NameNode
+    | NameListNode
+    | ColumnsNode
+    | KeywordNode
+    | UnaryOperatorNode
+    | BinaryOperatorNode
+    | FunctionCallNode
 )
 
 
@@ -200,7 +224,7 @@ def nodes(*roots: ParsedNode) -> Iterator[ParsedNode]:
 
 def with_children(node: ArithmeticNode, recurse: Callable[[ArithmeticNode], ArithmeticNode]) -> ArithmeticNode:
     """*node* rebuilt with *recurse* applied to each of its [`children`][]; a leaf comes back as is."""
-    if isinstance(node, NumberNode | NameNode | NameListNode | KeywordNode):
+    if isinstance(node, NumberNode | NameNode | NameListNode | ColumnsNode | KeywordNode):
         return node
     if isinstance(node, UnaryOperatorNode):
         return UnaryOperatorNode(node.op, recurse(node.operand))
@@ -227,8 +251,8 @@ NAME_LIST = (pp.Suppress('[') + pp.DelimitedList(pp.Regex(NAME)) + pp.Suppress('
 )
 
 
-def _build_grammar() -> tuple[pp.ParserElement, pp.ParserElement]:
-    """The arithmetic grammar, and the expression grammar that puts one comparison over it.
+def _build_grammar() -> tuple[pp.ParserElement, pp.ParserElement, pp.ParserElement]:
+    """The arithmetic grammar, the expression grammar that puts one comparison over it, and a column selection.
 
     ``inf`` is a ``pp.Keyword`` rather than a ``pp.Literal``, which would
     match the prefix of ``inflow``.
@@ -242,7 +266,10 @@ def _build_grammar() -> tuple[pp.ParserElement, pp.ParserElement]:
     name = pp.Regex(NAME)
 
     quoted = (pp.QuotedString("'") | pp.QuotedString('"')).set_parse_action(lambda t: KeywordNode(str(t[0])))
-    kwarg = (name + pp.Suppress('=') + (quoted | NAME_LIST | arith)).set_parse_action(lambda t: (t[0], t[1]))
+    columns = (name + pp.Suppress('[') + pp.DelimitedList(name) + pp.Suppress(']')).set_parse_action(
+        lambda t: ColumnsNode(str(t[0]), tuple(str(x) for x in t[1:]))
+    )
+    kwarg = (name + pp.Suppress('=') + (quoted | columns | NAME_LIST | arith)).set_parse_action(lambda t: (t[0], t[1]))
     pos_arg = arith
     arg_list = pp.Optional(pp.DelimitedList(kwarg | pos_arg))
     func_call = (name + pp.Suppress('(') + arg_list + pp.Suppress(')')).set_parse_action(_make_func_call)
@@ -268,7 +295,7 @@ def _build_grammar() -> tuple[pp.ParserElement, pp.ParserElement]:
     expression = (arith + pp.Optional(comparator + arith)).set_parse_action(
         lambda t: ComparisonNode(t[1], t[0], t[2]) if len(t) == 3 else t[0]
     )
-    return arith, expression
+    return arith, expression, columns
 
 
 def _make_func_call(tokens: pp.ParseResults) -> FunctionCallNode:
@@ -286,7 +313,7 @@ def keywords[V](name: str, pairs: Iterable[tuple[str, V]]) -> dict[str, V]:
     kwargs: dict[str, V] = {}
     for key, value in pairs:
         if key in kwargs:
-            msg = f'{name}({key}=) is given twice. A keyword names one value; drop one of them.'
+            msg = f'{name}({key}=) is given twice. Delete one of them.'
             raise SchemaError(msg)
         kwargs[key] = value
     return kwargs
@@ -308,7 +335,9 @@ def _make_power(tokens: pp.ParseResults) -> ArithmeticNode:
 
 #: The arithmetic half on its own, for the where grammar to put a predicate's
 #: comparator over: one grammar for what a side may say, wherever it stands.
-ARITHMETIC, _GRAMMAR = _build_grammar()
+#: The column selection is shared too, so a kwarg reads one the same way in
+#: both grammars.
+ARITHMETIC, _GRAMMAR, COLUMNS = _build_grammar()
 
 
 #: How deep a tree the language admits. Every pass over an expression recurses,
@@ -363,7 +392,7 @@ def parse_text[T](
         result = grammar.parse_string(text, parse_all=True)
     except pp.ParseException as e:
         hint = rewrite(text, e.loc)
-        msg = f'Failed to parse {what}: {text!r}\n{f"{hint}\n" if hint is not None else ""}{e}'
+        msg = f'Cannot parse the {what} {text!r}.\n{f"{hint}\n" if hint is not None else ""}{e}'
         raise SchemaError(msg) from e
     except RecursionError:
         raise SchemaError(_too_deep(what, text, None, deep_rewrite)) from None
@@ -381,22 +410,13 @@ def _named_rewrite(text: str, loc: int) -> str | None:
     """
     rest = text[loc:].lstrip()
     if rest.startswith(get_args(ComparisonOperator)):
-        return (
-            f"'{rest[:2]}' follows a complete comparison, and an expression carries "
-            f'one comparison, at the top. Split the chain into two constraints.'
-        )
+        return f"'{rest[:2]}' follows a complete comparison. Split the chain into two constraints."
     if rest.startswith('!='):
-        return (
-            "'!=' is not a constraint sense — the senses are <=, >= and ==. "
-            'Holding rows apart is a where matter: write the test in where:, where != is legal.'
-        )
+        return "'!=' is not a constraint sense. Write <=, >= or ==, or move the != test to where:."
     if rest.startswith(('<', '>')):
-        return f"'{rest[0]}' is not a constraint sense — the senses are <=, >= and ==. Write the bound inclusive."
+        return f"'{rest[0]}' is not a constraint sense. Write '{rest[0]}=' instead."
     if rest.startswith('='):
-        return (
-            "'=' on its own is how a kwarg is written inside a call, like sum(x, over=d). "
-            'Equality between two sides is written ==.'
-        )
+        return "A single '=' passes a keyword argument, as in sum(x, over=d). Write == for equality."
     if rest.startswith('^'):
         return "power is written '**', not '^'."
     return None