math_spec.piecewise

Expand piecewise: blocks into plain variables and constraints.

A block becomes ordinary affine declarations before anything reads the model, under names prefixed with the block's own; what each method emits is tabled in docs/reference/language/piecewise.md. Everything the language decides about a block against its model is decided once, in :func:check, and the emitters write rows from the facts it settled. A refusal names the link or key the file wrote rather than an emitted declaration.

ASSUMED = ('complete', 'increasing', 'curvature', 'breakpoints', 'contiguous') module-attribute

GateRow = tuple[str, str | None, str] module-attribute

Curve(name, block, frame, rows, mask, gates, names) dataclass

One piecewise: block held to its model: every fact the rows it writes read.

:func:check is the only thing that builds one, so holding one is the proof that the block is inside the language, and nothing after it decides anything.

ATTRIBUTE	DESCRIPTION
name	The block's key. TYPE: str
block	The block as written. TYPE: PiecewiseBlock
frame	The dims the block builds one curve per coordinate of. TYPE: tuple[str, ...]
rows	Each link's row frame — the frame, or its refinement through the link's relation. TYPE: tuple[tuple[str, ...], ...]
mask	The block's where:, as each shape of row reads it. TYPE: CurveMask
gates	The rows the weights sum under, one or two. TYPE: tuple[GateRow, ...]
names	Every name the expansion writes. TYPE: Names

block instance-attribute

frame instance-attribute

gates instance-attribute

mask instance-attribute

name instance-attribute

names instance-attribute

rows instance-attribute

CurveMask(block, resolved)

A block's where:, as each shape of row the expansion writes reads it.

Built from the block and its resolved mask, to answer the one question the expansion asks of it: whether it reads the breakpoint dim. Such a where is ragged — it says how far each curve runs, not only which curves exist — so a row over the frame and the breakpoint dim takes it as written, the rows on a curve's edges shift it, and a row over the frame alone, which cannot read that dim, takes the count of breakpoints it admits. A where over the frame alone reaches every row as written.

Source code in src/math_spec/piecewise.py

def __init__(self, block: PiecewiseBlock, resolved: Mask | None) -> None:
    self.text = block.where
    self.along = block.along
    self.dims: frozenset[str] = resolved.dims if resolved is not None else frozenset()

along = block.along instance-attribute

dims = resolved.dims if resolved is not None else frozenset() instance-attribute

exists property

What a row over the frame alone takes: the where, or the count of breakpoints a ragged one admits.

frame property

The where as a row over the frame and the breakpoint dim conjoins it onto a position test — none where ragged.

ragged property

Whether the where reads the breakpoint dim, and so says how far each curve runs.

text = block.where instance-attribute

edge(end)

The first or last breakpoint of each curve: where the mask holds and does not one step outward.

The vacated edge of a shift in a where is false, which is what makes the head and the tail of the axis their own edge.

Source code in src/math_spec/piecewise.py

def edge(self, end: Literal['first', 'last']) -> str:
    """The first or last breakpoint of each curve: where the mask holds and does not one step outward.

    The vacated edge of a ``shift`` in a ``where`` is false, which is what
    makes the head and the tail of the axis their own edge.
    """
    if not self.ragged:
        return f'position({self.along}) == {0 if end == "first" else -1}'
    return f'{self._atom} AND NOT {self._shifted(1 if end == "first" else -1)}'

interior()

Where a breakpoint has one on either side: the rows a claim about a bend is true of.

Source code in src/math_spec/piecewise.py

def interior(self) -> str:
    """Where a breakpoint has one on either side: the rows a claim about a bend is true of."""
    if not self.ragged:
        return f'position({self.along}) > 0 AND position({self.along}) != -1'
    return f'{self._atom} AND {self._shifted(1)} AND {self._shifted(-1)}'

neighbours()

Where a breakpoint and the one before it are both there: the rows a claim about a segment is true of.

Source code in src/math_spec/piecewise.py

def neighbours(self) -> str:
    """Where a breakpoint and the one before it are both there: the rows a claim about a segment is true of."""
    if not self.ragged:
        return f'position({self.along}) > 0'
    return f'{self._atom} AND {self._shifted(1)}'

Names(name, weights, convexity, chord, domain_lo, domain_hi, links, sos) dataclass

Every name one block's expansion writes, spelled once for the emitters and the collision check.

Every name is reserved whichever method the block declares: which method writes which is the method's business, and a collision is the file's either way. sos holds the names a method that states a set writes through :func:math_spec.sos.emit.

by_kind property

Each name by the kind of declaration it would collide with.

chord instance-attribute

convexity instance-attribute

domain_hi instance-attribute

domain_lo instance-attribute

links instance-attribute

name instance-attribute

sos instance-attribute

ungated property

The second gate row, where the gate variable does not exist.

weights instance-attribute

of(name, links) classmethod

The names block name with links links writes.

Source code in src/math_spec/piecewise.py

@classmethod
def of(cls, name: str, links: int) -> Names:
    """The names block *name* with *links* links writes."""
    return cls(
        name=name,
        weights=f'{name}_lam',
        convexity=f'{name}_convexity',
        chord=f'{name}_chord',
        domain_lo=f'{name}_domain_lo',
        domain_hi=f'{name}_domain_hi',
        links=tuple(f'{name}_link{i}' for i in range(links)),
        sos=Emitted.of(name, 2),
    )

assumptions_of(name, block, where)

What block assumes of its numbers, by the name the document prints and a refusal quotes.

Every curve assumes its breakpoints are there: a missing parameter row is not absence, it is a zero, so an undeclared breakpoint sits the curve on the origin rather than shortening it. A curve has an x-axis only where two links tie it, so the increasing condition — and the shape it is checked with — exist only there; lp alone needs a segment to state a line for; a ragged where: must mark one run.

Read off the block rather than off an expansion, so a model states what it assumes whether or not its curves have been written out. Each condition is a where string over the parameters the file declared: the expansion writes them into assumptions:, and a model that still declares the block derives the same text at load. A where: over the frame alone is not written into them: a program carries it on the declaration, and asks each condition only where it holds.

Source code in src/math_spec/piecewise.py

def assumptions_of(name: str, block: PiecewiseBlock, where: CurveMask) -> dict[str, AssumptionBlock]:
    """What *block* assumes of its numbers, by the name the document prints and a refusal quotes.

    Every curve assumes its breakpoints are there: a missing parameter row is
    not absence, it is a zero, so an undeclared breakpoint sits the curve on
    the origin rather than shortening it. A curve has an x-axis only where two
    links tie it, so the increasing condition — and the shape it is checked
    with — exist only there; ``lp`` alone needs a segment to state a line for;
    a ragged ``where:`` must mark one run.

    Read off the block rather than off an expansion, so a model states what it
    assumes whether or not its curves have been written out. Each condition is
    a where string over the parameters the file declared: the expansion writes
    them into ``assumptions:``, and a model that still declares the block
    derives the same text at load. A ``where:`` over the frame alone is not
    written into them: a program carries it on the declaration, and asks each
    condition only where it holds.
    """
    d = block.along
    mask = where.text if where.ragged else None
    values = [link.values for link in block.links]
    assumed = {
        f'{name}_complete': AssumptionBlock(
            holds=' AND '.join(dict.fromkeys(values)),
            where=mask,
            description=f"piecewise '{name}': every breakpoint the curve runs through needs a row in "
            f'{_quoted(values)} — a missing row is read as a zero rather than as a shorter curve, so it sits '
            f'the curve on the origin. '
            + (
                f'Bind the rows, or narrow where: {mask!r} to where the curve runs.'
                if mask is not None
                else 'Bind the rows, or declare where: to say how far the curve runs.'
            ),
        )
    }
    curvature = _curvature_required(block)
    if curvature is not None:
        x, y = (link.values for link in block.curve)
        assumed[f'{name}_increasing'] = AssumptionBlock(
            holds=f'{_neighbour(x, d, 1)} < {x}',
            where=where.neighbours(),
            description=f"piecewise '{name}': method: {block.method} requires strictly increasing breakpoints "
            f"in '{x}' along '{d}'",
        )
        assumed[f'{name}_curvature'] = _bends(name, block, where, x, y, curvature)
    if block.method == 'lp':
        assumed[f'{name}_breakpoints'] = AssumptionBlock(
            holds=f'count({mask or block.curve[0].values}, over={d}) >= 2',
            description=f"piecewise '{name}': method: lp needs at least two breakpoints per curve — the method "
            f'*is* its segment lines, so a curve with no segment states nothing and leaves the bounded link on '
            f'its own bound. Use method: adjacency, sos2 or convex, which pin it to the points it does have.',
        )
    if mask is not None:
        assumed[f'{name}_contiguous'] = AssumptionBlock(
            holds=f'count({where.edge("first")}, over={d}) == 1',
            description=f"piecewise '{name}': where: {mask!r} must mark a consecutive run of at least one "
            f'breakpoint per curve — {_GAP[block.method]}.',
        )
    return assumed

check(schema, name, block)

block held to everything the language decides about it against its model, as the facts its rows read.

What the block names by key — dimensions, parameters, relations, the gate — and the names it writes are checked as the file loads, with every other cross-declaration rule (:class:~math_spec.model.Spec); the link expressions and the where are typed with the rest of the model (:attr:~math_spec.model.Spec.resolved), so a fault in one is named against the link there. What is left is what needs those typed forms: the frame, declared by dims: or read off the links; each link's row; that each link's expression and values fit its row; and that the where: fits the frame.

RAISES	DESCRIPTION
PiecewiseExpansionError	A link that does not fit its row, a frame that reaches the breakpoint dim, or a where outside the frame.

Source code in src/math_spec/piecewise.py

def check(schema: Spec, name: str, block: PiecewiseBlock) -> Curve:
    """*block* held to everything the language decides about it against its model, as the facts its rows read.

    What the block names by key — dimensions, parameters, relations, the gate
    — and the names it writes are checked as the file loads, with every other
    cross-declaration rule (:class:`~math_spec.model.Spec`); the link
    expressions and the where are typed with the rest of the model
    (:attr:`~math_spec.model.Spec.resolved`), so a fault in one is named
    against the link there. What is left is what needs those typed forms: the
    frame, declared by ``dims:`` or read off the links; each link's row; that
    each link's expression and values fit its row; and that the ``where:``
    fits the frame.

    Raises:
        PiecewiseExpansionError: A link that does not fit its row, a frame
            that reaches the breakpoint dim, or a where outside the frame.
    """
    ctx = f"piecewise '{name}'"
    links, where = schema.resolved.piecewise[name]
    expressions = tuple(dims_of(node, schema, f'{ctx} link {i}') for i, node in enumerate(links))
    frame = _frame(schema, block, expressions, ctx)
    rows = tuple(_row(schema, block, i, link, frame, ctx) for i, link in enumerate(block.links))
    _links_fit(block, expressions, rows, ctx)
    _values_fit(schema, block, rows, ctx)
    mask = CurveMask(block, where)
    _where_fits(block, mask, frame, ctx)
    return Curve(name, block, frame, rows, mask, _gate_rows(schema, block), Names.of(name, len(block.links)))

declaration_of(block, where=None)

The curve of one expanded block, as a program carries it.

PARAMETER	DESCRIPTION
block	The block as written. TYPE: PiecewiseBlock
where	Which coordinates of the frame have a curve, lowered — and so which ones what the block assumes is asked at. TYPE: Mask | None DEFAULT: None

Source code in src/math_spec/piecewise.py

def declaration_of(block: PiecewiseBlock, where: Mask | None = None) -> PiecewiseDeclaration:
    """The curve of one expanded block, as a program carries it.

    Args:
        block: The block as written.
        where: Which coordinates of the frame have a curve, lowered — and so
            which ones what the block assumes is asked at.
    """
    return PiecewiseDeclaration(
        along=block.along,
        method=block.method,
        breakpoints=tuple(link.values for link in block.links),
        where=where,
    )

expand_piecewise(schema)

schema with every piecewise: block written out — schema itself where it declares none.

A method: adjacency block states its restriction as the set method: sos2 states, and then that set is written out here too: the binaries are what the method is, so the model that comes back carries no set of its own (:func:math_spec.sos.emit is where they are spelled).

RAISES	DESCRIPTION
PiecewiseExpansionError	A block :func:check refuses.

Source code in src/math_spec/piecewise.py

def expand_piecewise(schema: Spec) -> Spec:
    """*schema* with every ``piecewise:`` block written out — *schema* itself where it declares none.

    A ``method: adjacency`` block states its restriction as the set
    ``method: sos2`` states, and then that set is written out here too: the
    binaries are what the method *is*, so the model that comes back carries no
    set of its own (:func:`math_spec.sos.emit` is where they are spelled).

    Raises:
        PiecewiseExpansionError: A block :func:`check` refuses.
    """
    if not schema.piecewise:
        return schema

    raw = schema.model_dump()
    raw.setdefault('variables', {})
    raw.setdefault('constraints', {})
    for name, block in schema.piecewise.items():
        _write(raw, check(schema, name, block))
    raw['piecewise'].clear()
    for name, block in schema.piecewise.items():
        if block.method == 'adjacency':
            emit(raw, name)
    expanded = Spec.model_validate(raw)
    expanded._expanded_piecewise = dict(schema.piecewise)
    del expanded.resolved  # validation typed the rows before the records were here, and a block's own where is on one
    return expanded