math_spec.resolution

Name resolution — the pass that reads the syntax tree into the program vocabulary.

The grammars emit bare names and calls; this module builds the :mod:math_spec.program node each stands for, so every pass after — the dim rules, the degree rules, the typesetter, lowering — reads one vocabulary. The rules live in the language reference.

DeclarationKind = Literal['variable', 'parameter', 'dimension', 'relation'] module-attribute

Namespace(schema)

The declared names of one schema, by kind — the whole of what a file may name, read once.

A name has one kind: model.py refuses one declared under two sections.

Source code in src/math_spec/resolution.py

def __init__(self, schema: Spec) -> None:
    #: The schema the names come from — what an expression is expanded and
    #: dim-checked against, since macros, named expressions and the dim
    #: rules read declarations the flat listing below does not carry.
    self.schema = schema
    self.variables = frozenset(schema.variables)
    self.parameters = frozenset(schema.parameters)
    self.dimensions = frozenset(schema.dimensions)
    #: The declared constraint names, off the flat namespace: a bare name
    #: never reaches them, so a model may name a constraint after a variable.
    #: Consulted only in ``dual()``'s argument position.
    self.constraints = frozenset(schema.constraints)
    #: name -> declared dtype, for dimensions, parameters and relations alike;
    #: what a where comparison checks its literal against.
    self.dtypes: dict[str, DeclaredDtype] = {
        **{p: pd.dtype for p, pd in schema.parameters.items()},
        **{d: dd.dtype for d, dd in schema.dimensions.items()},
    }
    #: relation name -> its columns and key, as declared.
    self.relations: dict[str, RelationDeclaration] = {
        n: RelationDeclaration(lk.pairs, lk.key_roles) for n, lk in schema.relations.items()
    }
    #: parameter or variable name -> the dims it is read through —
    #: parameters by their ``dims``, variables by their frame. Stamped onto
    #: each leaf a where names, the way a relation leaf carries ``over``.
    self.leaf_dims: dict[str, tuple[str, ...]] = {
        **{p: tuple(pd.dims) for p, pd in schema.parameters.items()},
        **{v: tuple(vd.dims) for v, vd in schema.variables.items()},
    }
    #: named expression -> its resolved node, or ``None``, and its refusals;
    #: filled the first time anything reads the name.
    self._named: dict[str, tuple[Named | None, tuple[str, ...]]] = {}
    #: The named expressions being resolved, outermost first — a cycle's chain.
    self._loading: list[str] = []

constraints = frozenset(schema.constraints) instance-attribute

dimensions = frozenset(schema.dimensions) instance-attribute

dtypes = {**{p: pd.dtype for p, pd in schema.parameters.items()}, **{d: dd.dtype for d, dd in schema.dimensions.items()}} instance-attribute

leaf_dims = {**{p: tuple(pd.dims) for p, pd in schema.parameters.items()}, **{v: tuple(vd.dims) for v, vd in schema.variables.items()}} instance-attribute

parameters = frozenset(schema.parameters) instance-attribute

relations = {n: RelationDeclaration(lk.pairs, lk.key_roles) for n, lk in schema.relations.items()} instance-attribute

schema = schema instance-attribute

variables = frozenset(schema.variables) instance-attribute

kind(name)

What name was declared as, or None where the file declares it nowhere.

Source code in src/math_spec/resolution.py

def kind(self, name: str) -> DeclarationKind | None:
    """What *name* was declared as, or ``None`` where the file declares it nowhere."""
    if name in self.variables:
        return 'variable'
    if name in self.parameters:
        return 'parameter'
    if name in self.dimensions:
        return 'dimension'
    if name in self.relations:
        return 'relation'
    return None

named(name, context)

The expressions: entry name as the node that stands where its name is written.

Resolved under the entry's own context the first time it is asked for, and read from then on, so a fault in it is reported once.

RAISES	DESCRIPTION
SchemaError	The entry reads itself, or does not load.

Source code in src/math_spec/resolution.py

def named(self, name: str, context: str) -> Named:
    """The ``expressions:`` entry *name* as the node that stands where its name is written.

    Resolved under the entry's own context the first time it is asked
    for, and read from then on, so a fault in it is reported once.

    Raises:
        SchemaError: The entry reads itself, or does not load.
    """
    if name in self._loading:
        chain = ' -> '.join([*self._loading[self._loading.index(name) :], name])
        msg = f'{context}: circular expression reference: {chain}'
        raise SchemaError(msg)
    node, _ = self.named_entry(name)
    if node is None:
        msg = f"{context}: named expression '{name}' does not load. Its refusal is listed with it."
        raise SchemaError(msg)
    return node

named_entry(name)

The expressions: entry name resolved, or None, with every refusal it earned.

Source code in src/math_spec/resolution.py

def named_entry(self, name: str) -> tuple[Named | None, tuple[str, ...]]:
    """The ``expressions:`` entry *name* resolved, or ``None``, with every refusal it earned."""
    if name not in self._named:
        errors: list[str] = []
        self._loading.append(name)
        try:
            node = _named(name, self.schema.expressions[name], self, errors)
        finally:
            self._loading.pop()
        self._named[name] = (node, tuple(errors))
    return self._named[name]

unknown(name, context, *, allow_dims, formals=())

The refusal for a name declared nowhere, listing what it could have been.

PARAMETER	DESCRIPTION
name	The name the file wrote. TYPE: str
context	The declaration it was found in. TYPE: str
allow_dims	Whether a dimension would have been accepted there. It marks a where string, which reads a relation as readily as a parameter, so the listing carries the relations too; an expression, where a relation is not a value, lists the variables instead. TYPE: bool
formals	A macro's formals, listed first when there are any. TYPE: Iterable[str] DEFAULT: ()

Source code in src/math_spec/resolution.py

def unknown(self, name: str, context: str, *, allow_dims: bool, formals: Iterable[str] = ()) -> str:
    """The refusal for a *name* declared nowhere, listing what it could have been.

    Args:
        name: The name the file wrote.
        context: The declaration it was found in.
        allow_dims: Whether a dimension would have been accepted there. It marks a
            where string, which reads a relation as readily as a parameter, so the
            listing carries the relations too; an expression, where a relation is not a
            value, lists the variables instead.
        formals: A macro's formals, listed first when there are any.
    """
    shown: list[tuple[str, Iterable[str]]] = [('Formals', formals)] if formals else []
    shown += (
        [('Parameters', self.parameters), ('Dimensions', self.dimensions), ('Relations', self.relations)]
        if allow_dims
        else [('Variables', self.variables), ('Parameters', self.parameters)]
    )
    listing = '\n'.join(f'  {kind}: {sorted(names)}' for kind, names in shown)
    return f"{context}: '{name}' not found.\n{listing}\nCheck for typos, or ensure '{name}' is declared."

unknown_constraint(name, context, *, formals=())

The refusal for a dual(name) naming no constraint — nor, inside a template, a formal.

Source code in src/math_spec/resolution.py

def unknown_constraint(self, name: str, context: str, *, formals: Iterable[str] = ()) -> str:
    """The refusal for a ``dual(name)`` naming no constraint — nor, inside a template, a formal."""
    also = ' or a formal of this macro' if formals else ''
    return (
        f"{context}: dual({name}): '{name}' is not a declared constraint{also}.\n"
        f'  Constraints: {sorted(self.constraints)}\n'
        f"Check for typos, or declare '{name}' under 'constraints:'."
    )

Resolved(expressions, variables, constraints, objective, relations, assumptions, piecewise) dataclass

Every expression and where string of one schema, typed once at load, in the program's own vocabulary.

:func:~math_spec.validation.validate_expressions builds it, and every reader after — the dim rules, lowering, the typesetter — walks these trees rather than parsing, expanding and resolving the text again. Each mapping is keyed as the schema's own section is. A where the file did not write, or one every row passes, is None. What a program does not carry is here alone: every use of an expressions: entry stands as the :class:~math_spec.program.Named node resolution built for it, which lowering inlines.

ATTRIBUTE	DESCRIPTION
expressions	Each expressions: entry as the node every use of it holds — a plain entry's body, or a cased one's :class:~math_spec.program.Cases with every region's mask typed and the otherwise carrying the negation of the rest. TYPE: dict[str, Named]
variables	Each variable's where. TYPE: dict[str, Mask | None]
constraints	Each constraint, as a program declares it. TYPE: dict[str, ConstraintDeclaration]
objective	The objective, None where the file declares none. TYPE: ObjectiveDeclaration | None
relations	Each relation's columns and key, as declared — the one copy, which every :class:~math_spec.program.Direction and :class:~math_spec.program.Partition in the trees holds. TYPE: dict[str, RelationDeclaration]
assumptions	Each assumptions: entry's predicate and the mask it is checked under. TYPE: dict[str, Assumption]
piecewise	Each piecewise: block's link expressions, in link order. TYPE: dict[str, tuple[Expression, ...]]

assumptions instance-attribute

constraints instance-attribute

expressions instance-attribute

objective instance-attribute

piecewise instance-attribute

read_by_the_math cached property

The named expressions the math reads: every entry the objective, a constraint or a curve reaches, transitively.

Read off those three positions alone: a bound and a where name no entry. The rest of the expressions: section is read back after a solve and never fed to one (:attr:~math_spec.program.ExpressionDeclaration.in_math). A curve counts because it states rows, so the answer does not move when the curve is written out (:meth:~math_spec.model.Spec.expand).

relations instance-attribute

variables instance-attribute

mask_of(node)

The mask a declaration carries for a resolved where: None where there is none, or where every row passes.

Source code in src/math_spec/resolution.py

def mask_of(node: Predicate | None) -> Mask | None:
    """The mask a declaration carries for a resolved where: ``None`` where there is none, or where every row passes."""
    if node is None or (isinstance(node, BooleanLiteral) and node.value):
        return None
    return Mask(node)

names_in(value)

The names a relation kwarg carries: one bare, several bracketed, none otherwise.

Source code in src/math_spec/resolution.py

def names_in(value: ArithmeticNode) -> tuple[str, ...]:
    """The names a relation kwarg carries: one bare, several bracketed, none otherwise."""
    if isinstance(value, NameNode):
        return (value.name,)
    return value.names if isinstance(value, NameListNode) else ()

remainder(masks)

The region left over: where not one of masks holds.

The otherwise arm's own mask, built rather than written. cases: carries at least one case, so there is no vacuous truth to spell.

Source code in src/math_spec/resolution.py

def remainder(masks: Iterable[Mask]) -> Mask:
    """The region left over: where not one of *masks* holds.

    The ``otherwise`` arm's own mask, built rather than written. ``cases:``
    carries at least one case, so there is no vacuous truth to spell.
    """
    first, *rest = masks
    left = ~first
    for mask in rest:
        left = left & ~mask
    return left

resolve_constraint_text(text, ns, context, errors)

Parse, expand, resolve and degree-check one constraint string: exactly one comparison, a variable on a side (#1171).

RETURNS	DESCRIPTION
tuple[Expression, ComparisonOperator, Expression] | None	The two sides and the sense between them, or None once anything
tuple[Expression, ComparisonOperator, Expression] | None	failed, the problem appended to errors.

Source code in src/math_spec/resolution.py

def resolve_constraint_text(
    text: str, ns: Namespace, context: str, errors: list[str]
) -> tuple[Expression, ComparisonOperator, Expression] | None:
    """Parse, expand, resolve and degree-check one constraint string: exactly one comparison, a variable on a side (#1171).

    Returns:
        The two sides and the sense between them, or ``None`` once anything
        failed, the problem appended to *errors*.
    """
    ast = _parsed(text, ns, context, errors)
    if ast is None:
        return None
    if not isinstance(ast, ComparisonNode):
        errors.append(
            f'{context}: expression must contain exactly one comparison operator (<=, >=, ==).\nGot: {text!r}'
        )
        return None
    found = len(errors)
    resolver = _Resolver(ns, context, errors)
    left, right = resolver.arith(ast.left), resolver.arith(ast.right)
    if len(errors) > found or left is None or right is None:
        return None
    if any(_over_the_ceiling(side, context, errors, ceiling=2) for side in (left, right)):
        return None
    if not (carries_variable(left) or carries_variable(right)):
        errors.append(
            f'{context}: neither side of the comparison carries a variable, so the row decides nothing.\n'
            f'Got: {text!r}\n'
            f'A constraint is a claim about a decision, and a comparison of numbers and parameters '
            f'is settled before the solve — no consumer builds a row for it. Name the variable it should '
            f'bound, or state the fact under `assumptions:`, where the consumer binding the data checks it.'
        )
        return None
    return left, ast.op, right

resolve_expression(node, ns, context, errors, *, formals=frozenset())

Build the program tree node stands for, checking every name and operator call shape on the way.

RETURNS	DESCRIPTION
Expression | None	The tree, or None once anything failed — appending to errors
Expression | None	rather than raising, so a caller collecting problems across a whole
Expression | None	schema reports them together. Also None, with nothing appended,
Expression | None	where a name in formals stands under node: a macro template is
Expression | None	checked by the rules a call site is before anything calls it, and
Expression | None	only the call site that binds its formals has a tree to build.

Source code in src/math_spec/resolution.py

def resolve_expression(
    node: ArithmeticNode,
    ns: Namespace,
    context: str,
    errors: list[str],
    *,
    formals: frozenset[str] = frozenset(),
) -> Expression | None:
    """Build the program tree *node* stands for, checking every name and operator call shape on the way.

    Returns:
        The tree, or ``None`` once anything failed — appending to *errors*
        rather than raising, so a caller collecting problems across a whole
        schema reports them together. Also ``None``, with nothing appended,
        where a name in *formals* stands under *node*: a macro template is
        checked by the rules a call site is before anything calls it, and
        only the call site that binds its formals has a tree to build.
    """
    before = len(errors)
    resolved = _Resolver(ns, context, errors, formals=formals).arith(node)
    return None if len(errors) > before else resolved

resolve_expression_text(text, ns, context, errors, *, ceiling)

Parse, expand, resolve and degree-check one expression string that stands for a value.

ceiling is the degree the position honours, and None for an expressions: entry's body: what the math admits (:func:~math_spec.degree.check_expression) is a rule about the position that reads it, so it fires on the expanded tree of every objective and piecewise link, and not where an entry is declared. A constraint is :func:resolve_constraint_text's.

RETURNS	DESCRIPTION
Expression | None	The typed tree, or None once anything failed, the problem appended
Expression | None	to errors.

Source code in src/math_spec/resolution.py

def resolve_expression_text(
    text: str, ns: Namespace, context: str, errors: list[str], *, ceiling: int | None
) -> Expression | None:
    """Parse, expand, resolve and degree-check one expression string that stands for a value.

    *ceiling* is the degree the position honours, and ``None`` for an
    ``expressions:`` entry's body: what the math admits
    (:func:`~math_spec.degree.check_expression`) is a rule about the position
    that *reads* it, so it fires on the expanded tree of every objective and
    piecewise link, and not where an entry is declared. A constraint is
    :func:`resolve_constraint_text`'s.

    Returns:
        The typed tree, or ``None`` once anything failed, the problem appended
        to *errors*.
    """
    ast = _parsed(text, ns, context, errors)
    if ast is None:
        return None
    if isinstance(ast, ComparisonNode):
        errors.append(f'{context}: expression must not contain a comparison operator.\nGot: {text!r}')
        return None
    resolved = resolve_expression(ast, ns, context, errors)
    if resolved is None or ceiling is None:
        return resolved
    return None if _over_the_ceiling(resolved, context, errors, ceiling=ceiling) else resolved

resolve_where(node, ns, context, errors, self_variable=None)

Rewrite a parsed where AST into typed predicates, folded as :class:~math_spec.program.Mask folds.

RETURNS	DESCRIPTION
Predicate | None	The typed tree — a mask admitting every row or none comes back as the
Predicate | None	one BooleanLiteral — or None once anything failed, with the
Predicate | None	problems appended to errors.

Source code in src/math_spec/resolution.py

def resolve_where(
    node: Predicate | UnresolvedWhereNode,
    ns: Namespace,
    context: str,
    errors: list[str],
    self_variable: str | None = None,
) -> Predicate | None:
    """Rewrite a parsed where AST into typed predicates, folded as :class:`~math_spec.program.Mask` folds.

    Returns:
        The typed tree — a mask admitting every row or none comes back as the
        one ``BooleanLiteral`` — or ``None`` once anything failed, with the
        problems appended to *errors*.
    """
    before = len(errors)
    resolved = _Resolver(ns, context, errors, self_variable).where(node)
    return None if len(errors) > before else Mask(cast('Predicate', resolved)).root

resolve_where_text(text, ns, context, errors, self_variable=None)

Parse and resolve one where string as :func:resolve_where does, a parse failure appended to errors.

RETURNS	DESCRIPTION
Predicate | None	None where there is no mask to read, and where reading it failed.

Source code in src/math_spec/resolution.py

def resolve_where_text(
    text: str | None,
    ns: Namespace,
    context: str,
    errors: list[str],
    self_variable: str | None = None,
) -> Predicate | None:
    """Parse and resolve one where string as :func:`resolve_where` does, a parse failure appended to *errors*.

    Returns:
        ``None`` where there is no mask to read, and where reading it failed.
    """
    if text is None:
        return None
    try:
        node = parse_where(text)
    except ValueError as e:
        errors.append(f'{context}: {e}')
        return None
    return resolve_where(node, ns, context, errors, self_variable)