mathspec 0.2.0__tar.gz → 0.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mathspec
-Version: 0.2.0
+Version: 0.2.1
 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
@@ -49,15 +49,6 @@ 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:engines] -->
-
-mathspec builds nothing and solves nothing itself.
-[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.
-
-<!--- --8<-- [end:engines] -->
-
 <!--- --8<-- [start:benefits] -->
 
 - **Check specs in CI, with no data.** A wrong name or
@@ -208,6 +199,35 @@ A [symbol table](https://mathspec.readthedocs.io/en/latest/reference/typeset/#sy
 conventional spelling, as in the folded block.
 [Print a spec as math](https://mathspec.readthedocs.io/en/latest/howto/print/) does the same from a shell.
 
+## Engines and other tools
+
+<!--- --8<-- [start:engines] -->
+
+mathspec builds nothing and solves nothing itself.
+[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
+read the same spec through the
+[Program API](https://mathspec.readthedocs.io/en/latest/reference/program/).
+The solid boxes are mathspec; the dashed boxes are outside it.
+
+```mermaid
+flowchart LR
+    accTitle: What mathspec does, and what other tools do with a spec
+    accDescr: A YAML file loads into a Spec and the Program it lowers to. mathspec checks the spec and prints it as math, with no data. Outside mathspec, drawn dashed, an engine such as specsolve or linopy reads the same spec, takes your data and returns your answers, and any other tool, such as a renderer or an analyser, reads the same spec through the Program API.
+    Y(["your spec<br/>one YAML file"]) --> SPEC["<b>Spec</b> and the <b>Program</b> it lowers to<br/><i>checked before any data exists</i>"]
+    SPEC --> CHECK["<b>check it</b><br/>python -m mathspec check"]
+    SPEC --> SHOW["<b>print it as math</b><br/>LaTeX · Typst · Markdown"]
+    SPEC -.-> OTHER["<b>your own tool</b><br/>a renderer · an analyser · …<br/>reads the Program API"]
+    SPEC -.-> ENGINE["<b>an engine</b><br/>specsolve · linopy<br/>builds and solves the model"]
+    DATA[("your data")] -.-> ENGINE
+    ENGINE -.-> ANS(["your answers"])
+    classDef outside stroke-dasharray:5 4
+    class ENGINE,DATA,ANS,OTHER outside
+```
+
+<!--- --8<-- [end:engines] -->
+
 ## Documentation
 
 The documentation is at <https://mathspec.readthedocs.io>.

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

@@ -24,15 +24,6 @@ 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:engines] -->
-
-mathspec builds nothing and solves nothing itself.
-[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.
-
-<!--- --8<-- [end:engines] -->
-
 <!--- --8<-- [start:benefits] -->
 
 - **Check specs in CI, with no data.** A wrong name or
@@ -183,6 +174,35 @@ A [symbol table](https://mathspec.readthedocs.io/en/latest/reference/typeset/#sy
 conventional spelling, as in the folded block.
 [Print a spec as math](https://mathspec.readthedocs.io/en/latest/howto/print/) does the same from a shell.
 
+## Engines and other tools
+
+<!--- --8<-- [start:engines] -->
+
+mathspec builds nothing and solves nothing itself.
+[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
+read the same spec through the
+[Program API](https://mathspec.readthedocs.io/en/latest/reference/program/).
+The solid boxes are mathspec; the dashed boxes are outside it.
+
+```mermaid
+flowchart LR
+    accTitle: What mathspec does, and what other tools do with a spec
+    accDescr: A YAML file loads into a Spec and the Program it lowers to. mathspec checks the spec and prints it as math, with no data. Outside mathspec, drawn dashed, an engine such as specsolve or linopy reads the same spec, takes your data and returns your answers, and any other tool, such as a renderer or an analyser, reads the same spec through the Program API.
+    Y(["your spec<br/>one YAML file"]) --> SPEC["<b>Spec</b> and the <b>Program</b> it lowers to<br/><i>checked before any data exists</i>"]
+    SPEC --> CHECK["<b>check it</b><br/>python -m mathspec check"]
+    SPEC --> SHOW["<b>print it as math</b><br/>LaTeX · Typst · Markdown"]
+    SPEC -.-> OTHER["<b>your own tool</b><br/>a renderer · an analyser · …<br/>reads the Program API"]
+    SPEC -.-> ENGINE["<b>an engine</b><br/>specsolve · linopy<br/>builds and solves the model"]
+    DATA[("your data")] -.-> ENGINE
+    ENGINE -.-> ANS(["your answers"])
+    classDef outside stroke-dasharray:5 4
+    class ENGINE,DATA,ANS,OTHER outside
+```
+
+<!--- --8<-- [end:engines] -->
+
 ## Documentation
 
 The documentation is at <https://mathspec.readthedocs.io>.

{mathspec-0.2.0 → mathspec-0.2.1}/pyproject.toml

@@ -211,12 +211,13 @@ extend-exclude = ["CHANGELOG.md"]
 [tool.typos.default.extend-words]
 # Each of these is deliberate, and none is reachable by fixing a spelling.
 #
-# `wher` and `generatr` are misspellings *on purpose*: they are the input to the
-# did-you-mean suggester, so correcting them deletes the case. `missable` is the
+# `wher`, `generatr` and `balnce` are misspellings *on purpose*: they are the
+# input to the did-you-mean suggester, so correcting them deletes the case. `missable` is the
 # word the sentence wants — a coordinate that can go missing — and is not
 # "miscible". `unparseable` is the accepted variant and is the name of a test.
 wher = "wher"
 generatr = "generatr"
+balnce = "balnce"
 missable = "missable"
 unparseable = "unparseable"
 # `fom` is PyPSA's `fom_cost` — fixed operation and maintenance — quoted by name

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

@@ -13,6 +13,7 @@ program instead.
 
 from mathspec import program
 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
@@ -40,6 +41,8 @@ __all__ = [
     'SymbolTable',
     'advice',
     'did_you_mean',
+    'merge',
+    'override',
     'program',
     'to_latex',
     'to_markdown',

{mathspec-0.2.0 → mathspec-0.2.1}/src/mathspec/__main__.py

@@ -4,9 +4,11 @@
 
 """``python -m mathspec <verb> spec.yaml`` — the shell front.
 
-``check`` loads the file and prints the language's advice; one further verb
-per typeset format, read off [`mathspec.typesetting.FORMATS`][]. Every verb
-reads the file as written, and nothing here writes a formulation out unasked.
+``check`` loads the file and prints the language's advice; ``canonical``
+writes the spec in the form two files that state the same spec share, or with
+``--check`` asks whether the file is already in that form; one further verb per
+typeset format, read off [`mathspec.typesetting.FORMATS`][]. Every verb reads
+the file as written, and nothing here writes a formulation out unasked.
 The typeset verbs take ``--expand``, because a shell cannot compose
 [`expand`][mathspec.spec.Spec.expand] the way a caller does and the rows are a
 different document; ``check`` has no such flag, because advice reads a block
@@ -33,6 +35,13 @@ def parser() -> argparse.ArgumentParser:
     check = verbs.add_parser('check', help='load a spec, and print what the language advises')
     check.add_argument('spec', help='path to a mathspec YAML file')
 
+    canonical = verbs.add_parser('canonical', help='write a spec in the form two files that state it share')
+    canonical.add_argument('spec', help='path to a mathspec YAML file')
+    target = canonical.add_mutually_exclusive_group()
+    target.add_argument('-o', '--out', help='write here instead of stdout')
+    target.add_argument('--write', action='store_true', help='rewrite the file in the form, dropping its comments')
+    target.add_argument('--check', action='store_true', help='exit 1 if the file is not in the form, writing nothing')
+
     for name in FORMATS:
         verb = verbs.add_parser(name, help=f'render a spec as {name}')
         verb.add_argument('spec', help='path to a mathspec YAML file')
@@ -52,10 +61,26 @@ def parser() -> argparse.ArgumentParser:
     return front
 
 
+def _checked(path: str, text: str) -> int:
+    """Exit status 0 if the file at *path* already holds *text*, the form, and 1 with the rewrite on stderr if not.
+
+    A CI job runs this, so it compares bytes and writes nothing: the job fails,
+    and the author runs the rewrite the message names.
+    """
+    if Path(path).read_text(encoding='utf-8') == text:
+        return 0
+    sys.stderr.write(
+        f'{path} is not in the canonical form. Run `python -m mathspec canonical --write {path}` to rewrite it.\n'
+    )
+    return 1
+
+
 def main(argv: list[str] | None = None) -> int:
     """Run one verb; a refused file is its message on stderr and exit status 1.
 
-    Advice is not a refusal: ``check`` prints it and exits 0.
+    Advice is not a refusal: ``check`` prints it and exits 0. A file that
+    ``canonical --check`` finds out of the form exits 1, with the rewrite on
+    stderr.
     """
     args = parser().parse_args(argv)
     if args.verb == 'check':
@@ -66,16 +91,28 @@ def main(argv: list[str] | None = None) -> int:
             return 1
         sys.stdout.write(''.join(f'{note}\n' for note in notes))
         return 0
-    spec = to_spec(args.spec).expand() if args.expand else args.spec
-    text = typeset(
-        spec,
-        args.verb,
-        symbols=args.symbols,
-        standalone=args.standalone,
-        legend=not args.no_legend,
-        numbered=not args.no_numbers,
-        inline_expressions=args.inline_expressions,
-    )
+    if args.verb == 'canonical':
+        try:
+            text = to_spec(args.spec).to_yaml(canonical=True)
+        except MathSpecError as e:
+            sys.stderr.write(f'{e}\n')
+            return 1
+        if args.check:
+            return _checked(args.spec, text)
+        if args.write:
+            Path(args.spec).write_text(text, encoding='utf-8')
+            return 0
+    else:
+        spec = to_spec(args.spec).expand() if args.expand else args.spec
+        text = typeset(
+            spec,
+            args.verb,
+            symbols=args.symbols,
+            standalone=args.standalone,
+            legend=not args.no_legend,
+            numbered=not args.no_numbers,
+            inline_expressions=args.inline_expressions,
+        )
     if args.out:
         Path(args.out).write_text(text, encoding='utf-8')
     else:

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

@@ -220,6 +220,13 @@ def with_children(node: ArithmeticNode, recurse: Callable[[ArithmeticNode], Arit
 # ---------------------------------------------------------------------------
 
 
+#: A bracketed list of names as a kwarg value, in an expression and in a where
+#: string alike.
+NAME_LIST = (pp.Suppress('[') + pp.DelimitedList(pp.Regex(NAME)) + pp.Suppress(']')).set_parse_action(
+    lambda t: NameListNode(tuple(str(x) for x in t))
+)
+
+
 def _build_grammar() -> tuple[pp.ParserElement, pp.ParserElement]:
     """The arithmetic grammar, and the expression grammar that puts one comparison over it.
 
@@ -235,10 +242,7 @@ 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])))
-    name_list = (pp.Suppress('[') + pp.DelimitedList(name) + pp.Suppress(']')).set_parse_action(
-        lambda t: NameListNode(tuple(str(x) for x in t))
-    )
-    kwarg = (name + pp.Suppress('=') + (quoted | name_list | arith)).set_parse_action(lambda t: (t[0], t[1]))
+    kwarg = (name + pp.Suppress('=') + (quoted | 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)

{mathspec-0.2.0 → mathspec-0.2.1}/src/mathspec/_expression_resolver.py

@@ -182,7 +182,7 @@ class ExpressionResolver:
         """
         if node.name in self.formals:
             return None
-        if node.name in self.ns.schema.expressions:
+        if node.name in self.ns.bodies:
             try:
                 return cast('Expression', self.ns.named(node.name, self.context))
             except SchemaError as e:
@@ -243,7 +243,7 @@ class ExpressionResolver:
                 f'{self.context}: {node.name}({", ".join(f"{k}=" for k in roles)}) names a column of a relation, '
                 f'and no by= names the relation. Write {builtin.usage}'
             )
-        dims: dict[str, str | None] = {}
+        dims: dict[str, tuple[str, ...] | None] = {}
         amounts: dict[str, int | str | None] = {}
         edge: _Edge | None = None
         for key, value in node.kwargs.items():
@@ -251,14 +251,15 @@ class ExpressionResolver:
                 case 'edge':
                     edge = self._edge(value, node.name)
                 case 'dimension':
-                    dims[key] = self._dim_ref(value, node.name, key)
+                    dims[key] = self._dim_refs(value, node.name, key, several=key in builtin.dimension_or_role_kwargs)
                 case 'value':
                     amounts[key] = self._amount(value, node.name, key)
                 case 'relation' | 'role' | None:
                     pass
         read = None
         if 'by' in node.kwargs and builtin.kind_of('by') == 'relation':
-            read = self.relation_ref(node.kwargs['by'], node.name, 'by', roles, dims.get('along'))
+            along = dims.get('along')
+            read = self.relation_ref(node.kwargs['by'], node.name, 'by', roles, along[0] if along else None)
         unread = (
             shape_error is not None
             or unrelated
@@ -277,7 +278,7 @@ class ExpressionResolver:
         self,
         operator: str,
         operand: Expression,
-        dims: Mapping[str, str | None],
+        dims: Mapping[str, tuple[str, ...] | None],
         amounts: Mapping[str, int | str | None],
         edge: _Edge | None,
         read: Direction | Partition | None,
@@ -288,14 +289,15 @@ class ExpressionResolver:
                 assert isinstance(read, Direction), 'a sum reads its relation in a direction'
                 return GroupSum(operand, read)
             if (over := dims.get('over')) is not None:
-                return Sum(operand, (over,))
+                return Sum(operand, over)
             return self._bare_sum(operand)
         if operator == 'at':
             assert isinstance(read, Direction), 'at reads its relation in a direction'
             return Pullback(operand, read)
         assert read is None or isinstance(read, Partition), 'a translation reads its relation as a partition'
-        along = dims['along']
-        assert along is not None
+        named = dims['along']
+        assert named is not None, 'a translation names the dimension it steps along'
+        (along,) = named
         wrap, fill = edge if edge is not None else (False, None)
         if operator == 'shift':
             offset = amounts['offset']
@@ -421,6 +423,20 @@ class ExpressionResolver:
             return None
         return False, literal.value
 
+    def _dim_refs(self, value: ArithmeticNode, operator: str, key: str, *, several: bool) -> tuple[str, ...] | None:
+        """An operator kwarg whose *value* names declared dimensions: one, or a list where *several* are allowed."""
+        if not (several and isinstance(value, NameListNode)):
+            found = self._dim_ref(value, operator, key)
+            return None if found is None else (found,)
+        if repeated := sorted({name for name in value.names if value.names.count(name) > 1}):
+            self.errors.append(
+                f'{self.context}: {operator}({key}={value}) names {", ".join(map(repr, repeated))} twice. '
+                f'Name each dimension once.'
+            )
+            return None
+        found = [self._dim_ref(NameNode(name), operator, key) for name in value.names]
+        return None if None in found else tuple(cast('list[str]', found))
+
     def _dim_ref(self, value: ArithmeticNode, operator: str, key: str) -> str | None:
         """An operator kwarg whose *value* must name a declared dimension."""
         if self._formal(value):

{mathspec-0.2.0 → mathspec-0.2.1}/src/mathspec/_where_parser.py

@@ -23,6 +23,7 @@ import pyparsing as pp
 from mathspec._expression_parser import (
     ARITHMETIC,
     NAME,
+    NAME_LIST,
     ArithmeticNode,
     KeywordNode,
     NameNode,
@@ -154,7 +155,7 @@ def _build_where_grammar() -> pp.ParserElement:
     )
     comparator = pp.one_of(list(get_args(PredicateOperator)))
 
-    kwarg = (name + pp.Suppress('=') + (quoted | ARITHMETIC)).set_parse_action(lambda t: (t[0], t[1]))
+    kwarg = (name + pp.Suppress('=') + (quoted | NAME_LIST | ARITHMETIC)).set_parse_action(lambda t: (t[0], t[1]))
 
     def _call(head: pp.ParserElement) -> pp.ParserElement:
         """``<head>(<predicate>[, <kwarg>…])`` — the one shape whose operand is a predicate.

{mathspec-0.2.0 → mathspec-0.2.1}/src/mathspec/_where_resolver.py

@@ -72,6 +72,7 @@ from mathspec.program import (
     TypedPredicate,
     VariableDefined,
     carries_variable,
+    variables_of,
     walk,
 )
 
@@ -81,6 +82,14 @@ if TYPE_CHECKING:
     from mathspec.program import DeclaredDtype
     from mathspec.resolution import Namespace
 
+#: Why a mask may not read a given expression. The namespace files a given
+#: expression with the variables, since it is read as a column, so the refusal
+#: names it apart.
+GIVEN_IN_A_MASK = (
+    'A given expression may hold a variable, and a where mask is built before variables exist — it may test '
+    'parameters and dimension coordinates only.'
+)
+
 
 @dataclass(frozen=True)
 class WhereResolver:
@@ -323,9 +332,9 @@ class WhereResolver:
             value = literal.value
         else:
             value = _side_name(right)
-            if value is not None and (value in ns.schema.expressions or ns.kind(value) == 'parameter'):
+            if value is not None and (value in ns.bodies or ns.kind(value) == 'parameter'):
                 return None
-        if name is None or value is None or name in ns.schema.expressions:
+        if name is None or value is None or name in ns.bodies:
             return None
         return _Plain(name, node.op, value, quoted)
 
@@ -361,7 +370,12 @@ class WhereResolver:
         assert len(sides) == 2, 'a side of a where builds or refuses, since a where holds no formal'
         dims: set[str] = set()
         for side in sides:
-            if carries_variable(side):
+            if given := sorted(variables_of(side) & set(ns.schema.given.expressions)):
+                self.errors.append(
+                    f'{context}: a where compares expressions, and one side reads the given expression '
+                    f'{given[0]!r}. {GIVEN_IN_A_MASK}'
+                )
+            elif carries_variable(side):
                 self.errors.append(
                     f'{context}: a where compares expressions, and one side names a variable. A where mask '
                     f'is built before variables exist — it may test parameters and dimension coordinates only.'
@@ -453,7 +467,8 @@ class WhereResolver:
                         return node
                     dims = tuple(ns.relations[left_name].dim(k) for k in ns.relations[left_name].key)
                     return RelationPairComparison(left_name, left, right_name, right, plain.op, dims)
-                self.errors.append(_declared_rhs_error(context, plain, value, rhs_kind))
+                given = right_name in ns.schema.given.expressions
+                self.errors.append(_declared_rhs_error(context, plain, value, rhs_kind, given=given))
                 return node
 
         kind = ns.kind(left_name)
@@ -491,6 +506,8 @@ class WhereResolver:
                 assert column is not None
                 shape = ns.relations[left_name]
                 return RelationComparison(left_name, column, plain.op, value, tuple(shape.dim(k) for k in shape.key))
+            case 'variable' if left_name in ns.schema.given.expressions:
+                self.errors.append(f"{context}: where references the given expression '{left_name}'. {GIVEN_IN_A_MASK}")
             case 'variable':
                 self.errors.append(
                     f"{context}: where references variable '{left_name}'. A where "
@@ -693,9 +710,14 @@ def _not_arithmetic(context: str, side: ColumnNode | KeywordNode) -> str:
     )
 
 
-def _declared_rhs_error(context: str, node: _Plain, value: str, kind: str) -> str:
-    """Why the right-hand side of a where-comparison may not name a variable, a relation or a dimension."""
+def _declared_rhs_error(context: str, node: _Plain, value: str, kind: str, *, given: bool = False) -> str:
+    """Why the right-hand side of a where-comparison may not name a variable, a relation or a dimension.
+
+    A given expression is filed with the variables, and *given* says the name is one.
+    """
     comparison = f"'{node.name} {node.op} {value}'"
+    if given:
+        return f'{context}: {comparison} compares against the given expression {value!r}. {GIVEN_IN_A_MASK}'
     if kind == 'variable':
         return (
             f'{context}: {comparison} compares against variable {value!r}. '

{mathspec-0.2.0 → mathspec-0.2.1}/src/mathspec/advising.py

@@ -35,15 +35,57 @@ def advice(spec: str | Path | Mapping[str, object] | Spec | Program) -> tuple[Ad
             nothing expanded.
 
     Returns:
-        The never-an-axis advice in declaration order, then the unboundedness
-        advice; ``str()`` of each is its sentence.
+        The never-an-axis advice in declaration order, then one note per
+        declaration the program reads and does not build, then the
+        unboundedness advice; ``str()`` of each is its sentence.
 
     Raises:
         LanguageError: *spec* does not load; [`to_spec`][] says why.
         FileNotFoundError: A ``str`` with no newline that names no file.
     """
     program = spec if isinstance(spec, Program) else to_spec(spec).program
-    return tuple(_never_an_axis(program) + unbounded_notes(program))
+    return tuple(_never_an_axis(program) + _given(program) + unbounded_notes(program))
+
+
+def _given(program: Program) -> list[Advice]:
+    """One note per declaration the program reads and does not build.
+
+    A note rather than a refusal: the file is a spec somebody meant, and only
+    the consumer can tell whether the model it is layered onto provides the
+    name. An expression this file adds a term to is completed by `merge`
+    rather than by a host, so its note says that instead.
+    """
+    given = program.given
+    written = {entry.adds_to for entry in program.expressions.values()}
+    return [
+        *(Advice('given', name, _given_note('parameter', name)) for name in given.parameters),
+        *(Advice('given', name, _given_note('variable', name)) for name in given.variables),
+        *(
+            Advice(
+                'given',
+                name,
+                _term_note(name) if name in written else _given_note('expression', name),
+            )
+            for name in given.expressions
+        ),
+        *(Advice('given', name, _given_note('row family', name)) for name in given.constraints),
+    ]
+
+
+def _given_note(kind: str, name: str) -> str:
+    return (
+        f"{kind} '{name}' is read here and declared elsewhere: the model this one is layered onto "
+        f'provides it. A consumer checks that it does, on the same frame, and refuses the program where '
+        f'it does not. A fragment is composed instead: merge() folds this declaration into the one a '
+        f'sibling introduces{", or writes it from the terms siblings add" if kind == "expression" else ""}.'
+    )
+
+
+def _term_note(name: str) -> str:
+    return (
+        f"expression '{name}' is read here, and this file adds a term to it: merge() sums the term with what "
+        f'the other files write under the name. Until then, the program reads it and does not build it.'
+    )
 
 
 def _never_an_axis(program: Program) -> list[Advice]:
@@ -51,10 +93,20 @@ def _never_an_axis(program: Program) -> list[Advice]:
 
     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.
+    so it is in use even where nothing is indexed by it. A dimension only a
+    given declaration indexes is reached too: the column exists, in another
+    file.
     """
     reached: set[str] = set()
-    for declaration in (*program.parameters.values(), *program.variables.values(), *program.constraints.values()):
+    for declaration in (
+        *program.parameters.values(),
+        *program.variables.values(),
+        *program.constraints.values(),
+        *program.given.parameters.values(),
+        *program.given.variables.values(),
+        *program.given.expressions.values(),
+        *program.given.constraints.values(),
+    ):
         reached.update(declaration.dims)
     reached |= _produced_axes(program)
     reached |= {dim for lk in program.relations.values() for dim in lk.dims}

{mathspec-0.2.0 → mathspec-0.2.1}/src/mathspec/boundedness.py

@@ -59,7 +59,9 @@ def unbounded_notes(program: Program) -> list[Advice]:
 
     Returns:
         One note per variable that is unbounded on the side its objective term
-        improves toward and named by no constraint.
+        improves toward and named by no constraint. A given column, which the
+        program reads and does not declare, has its bounds where it is built,
+        so it gets none.
     """
     if program.objective is None:
         return []
@@ -76,7 +78,7 @@ def unbounded_notes(program: Program) -> list[Advice]:
     minimize = program.objective.sense == 'minimize'
     notes: list[Advice] = []
     for vname, sign in signs.items():
-        if sign is None or vname in constrained:
+        if sign is None or vname in constrained or vname not in program.variables:
             continue
         side: BoundSide = 'lower' if minimize == (sign == '+') else 'upper'
         if _is_open(program.variables[vname], side):