math_spec.typesetting.symbols

Which symbol each declared name prints as, and the sidecar that overrides it.

This module decides which symbol a name gets; a :class:~math_spec.typesetting.format.Format decides how it is written.

SymbolTable(notation, indices=dict(), sets=dict(), names=dict()) dataclass

How a reader wants the model to print — notation only, kept out of the model.

Every entry is a spelling, printed verbatim. notation: says which language they are written in, and a render in the other one refuses::

notation: latex
dimensions:
  snapshot: {index: t, set: "\\mathcal{T}"}
  plant:    {index: n}
names:
  marginal_cost: "c^{\\mathrm{marg}}"

An entry naming nothing in the model is an error naming the near miss.

ATTRIBUTE	DESCRIPTION
notation	The language the entries are written in; :meth:load lower-cases it. TYPE: Notation

indices = field(default_factory=dict) class-attribute instance-attribute

names = field(default_factory=dict) class-attribute instance-attribute

notation instance-attribute

sets = field(default_factory=dict) class-attribute instance-attribute

checked_against(schema)

Reject entries naming nothing in schema, with the near miss.

Source code in src/math_spec/typesetting/symbols.py

def checked_against(self, schema: _ExpandedSpec) -> SymbolTable:
    """Reject entries naming nothing in *schema*, with the near miss."""
    dims = set(schema.dimensions)
    everything = (
        dims
        | set(schema.parameters)
        | set(schema.variables)
        | set(printed_expressions(schema))
        | set(reported_expressions(schema))
        | set(schema.constraints)
    )
    errors = [
        *(_unknown_entry(d, 'dimensions', dims) for d in {*self.indices, *self.sets} - dims),
        *(_unknown_entry(n, 'names', everything - dims) for n in set(self.names) - everything),
    ]
    if errors:
        raise SchemaError('\n'.join(sorted(errors)))
    return self

load(source) classmethod

A table from a YAML path or the mapping it parses to.

RAISES	DESCRIPTION
SchemaError	An unknown section, a malformed dimension, or a notation: that is missing or not latex/typst.

Source code in src/math_spec/typesetting/symbols.py

@classmethod
def load(cls, source: str | Path | Mapping[str, Any]) -> SymbolTable:
    """A table from a YAML path or the mapping it parses to.

    Raises:
        SchemaError: An unknown section, a malformed dimension, or a
            ``notation:`` that is missing or not ``latex``/``typst``.
    """
    raw = dict(source) if isinstance(source, Mapping) else read_yaml(Path(source))
    unknown = set(raw) - {'notation', 'dimensions', 'names'}
    if unknown:
        msg = f'symbol table: unknown section(s) {sorted(unknown)}. Valid sections: notation, dimensions, names.'
        raise SchemaError(msg)
    if 'notation' not in raw:
        msg = "symbol table: 'notation:' is required — latex or typst, the language the entries are written in."
        raise SchemaError(msg)
    notation = str(raw['notation']).lower()
    if notation not in NOTATIONS:
        msg = f'symbol table: unknown notation {raw["notation"]!r}. Valid notations: latex, typst.'
        raise SchemaError(msg)

    indices: dict[str, str] = {}
    sets: dict[str, str] = {}
    for dim, spec in (raw.get('dimensions') or {}).items():
        if not isinstance(spec, Mapping):
            msg = f"symbol table: dimension '{dim}' must be a mapping like {{index: t, set: '\\\\mathcal{{T}}'}}"
            raise SchemaError(msg)
        extra = set(spec) - {'index', 'set'}
        if extra:
            msg = f"symbol table: dimension '{dim}' has unknown key(s) {sorted(extra)}. Valid keys: index, set."
            raise SchemaError(msg)
        if 'index' in spec:
            indices[dim] = str(spec['index'])
        if 'set' in spec:
            sets[dim] = str(spec['set'])

    return cls(
        notation=cast('Notation', notation),
        indices=indices,
        sets=sets,
        names={k: str(v) for k, v in (raw.get('names') or {}).items()},
    )

Symbols(schema, namespace, fmt, table)

How every declared name prints: overrides first, derivation for the rest.

Name symbols settle before dimension indices, so an index is kept off a single letter a variable owns — a dimension plant beside a variable p would otherwise render p_{t,p}. A parameter is upright, so \mathrm{p} beside an index p is not a collision.

RAISES	DESCRIPTION
SchemaError	If table is written in a notation fmt does not read.

Source code in src/math_spec/typesetting/symbols.py

def __init__(self, schema: _ExpandedSpec, namespace: Namespace, fmt: Format, table: SymbolTable) -> None:
    if table.notation != fmt.notation:
        msg = (
            f'symbol table: written in {table.notation}, but this is a {fmt.notation} render '
            f'and nothing translates between notations — write a {fmt.notation} table.'
        )
        raise SchemaError(msg)
    printed = printed_expressions(schema)
    reported = reported_expressions(schema)
    chosen = frozenset(schema.variables) | chosen_expressions(schema, namespace) | frozenset(reported)
    names = (*schema.parameters, *schema.variables, *printed, *reported)
    declared = frozenset(names)

    #: Names the table spelled; the convention note quotes only derived symbols.
    self.overridden = frozenset(table.names) & declared
    self.name: dict[str, str] = {
        name: table.names[name]
        if name in table.names
        else _derive_name_symbol(name, declared, fmt, given=name not in chosen)
        for name in names
    }
    spoken_for = {s for s in self.name.values() if len(s) == 1}

    #: Each constraint's symbol, the subscript ``dual(c)`` prints λ against.
    #: Off the flat namespace, like the constraints themselves — a model may
    #: name a constraint after a variable, so this is its own map rather than
    #: an entry in :attr:`name`. Given structure, so upright unless a table
    #: overrides it.
    self.constraint: dict[str, str] = {
        name: table.names[name] if name in table.names else _derive_name_symbol(name, declared, fmt, given=True)
        for name in schema.constraints
    }

    self.index: dict[str, str] = {}
    self.set: dict[str, str] = {}
    taken_index, taken_set = set(spoken_for), set()
    for dim in schema.dimensions:
        overridden = dim in table.indices
        letter = table.indices[dim] if overridden else _first_free(_index_candidates(dim), taken_index)
        taken_index.add(letter)
        self.index[dim] = letter if len(letter) <= 1 or overridden else fmt.upright(letter)
        upper = _first_free(_set_candidates(dim, letter), taken_set)
        taken_set.add(upper)
        self.set[dim] = table.sets[dim] if dim in table.sets else fmt.script(upper)

constraint = {name: table.names[name] if name in table.names else _derive_name_symbol(name, declared, fmt, given=True) for name in schema.constraints} instance-attribute

index = {} instance-attribute

name = {name: table.names[name] if name in table.names else _derive_name_symbol(name, declared, fmt, given=name not in chosen) for name in names} instance-attribute

overridden = frozenset(table.names) & declared instance-attribute

set = {} instance-attribute

chosen_expressions(schema, namespace)

The cased expressions the solver decides, rather than is handed.

A when does not move one: a variable there asks whether the variable exists, which the model settles when it is built. Only a value reaching a variable does — through a second cased expression's arms too, since :func:~math_spec.resolution.expression_of expands those where the name stood.

Source code in src/math_spec/typesetting/symbols.py

def chosen_expressions(schema: _ExpandedSpec, namespace: Namespace) -> frozenset[str]:
    """The cased expressions the solver decides, rather than is handed.

    A ``when`` does not move one: a variable there asks whether the variable
    *exists*, which the model settles when it is built. Only a value reaching a
    variable does — through a second cased expression's arms too, since
    :func:`~math_spec.resolution.expression_of` expands those where the name stood.
    """
    return frozenset(
        name
        for name in printed_expressions(schema)
        if any(
            degree.carries_variable(expression_of(text, schema, namespace, f"expression '{name}', {where}"))
            for text, where in _values_of(schema.expressions[name])
        )
    )

printed_expressions(schema)

The named expressions that print under their own name, in declaration order.

A named expression is substituted where it is used, so it normally prints nothing a symbol could stand for. A cased one is the exception: it prints as a definition of its own, which the equations using it name. The order is the file's, because the definitions print in it.

Source code in src/math_spec/typesetting/symbols.py

def printed_expressions(schema: _ExpandedSpec) -> tuple[str, ...]:
    """The named expressions that print under their own name, in declaration order.

    A named expression is substituted where it is used, so it normally prints
    nothing a symbol could stand for. A **cased** one is the exception: it
    prints as a definition of its own, which the equations using it name. The
    order is the file's, because the definitions print in it.
    """
    return tuple(name for name, block in schema.expressions.items() if block.cases)

reported_expressions(schema)

The entries the math never reads, in declaration order — the Reported quantities section's rows.

Decided by :func:math_spec.expansion.read_by_the_math, the same answer the program carries, so the page and a consumer cannot disagree about which entries the objective and constraints inline. A cased entry is not here whether or not the math reads it: it prints as the definition block :func:printed_expressions already places.

Source code in src/math_spec/typesetting/symbols.py

def reported_expressions(schema: _ExpandedSpec) -> tuple[str, ...]:
    """The entries the math never reads, in declaration order — the Reported quantities section's rows.

    Decided by :func:`math_spec.expansion.read_by_the_math`, the same answer
    the program carries, so the page and a consumer cannot disagree about which
    entries the objective and constraints inline. A cased entry is not here
    whether or not the math reads it: it prints as the definition block
    :func:`printed_expressions` already places.
    """
    in_math = read_by_the_math(schema)
    return tuple(name for name, block in schema.expressions.items() if not block.cases and name not in in_math)