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. A link expression is judged before expansion, so a refusal names the link the file wrote rather than an emitted constraint.

assumptions_of(block, expanded)

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

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 mask must be one run.

The space in each name is what keeps these apart from the file's own assumptions: entries in one mapping: a declaration is named as an expression writes it, so no file can write one of these.

Source code in src/math_spec/piecewise.py

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

    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 mask must be one run.

    The space in each name is what keeps these apart from the file's own
    ``assumptions:`` entries in one mapping: a declaration is named as an
    expression writes it, so no file can write one of these.
    """
    pw = expanded.block
    checks: dict[str, Check] = {}
    curvature = _curvature_required(pw)
    if curvature is not None:
        x, y = pw.curve
        checks[f'{block} increasing'] = Increasing(block, pw.method, x.values, pw.over)
        checks[f'{block} curvature'] = Curved(block, pw.method, x.values, y.values, pw.over, curvature)
    if pw.method == 'lp':
        checks[f'{block} breakpoints'] = AtLeastTwo(block, pw.over, expanded.points)
    if expanded.points is not None:
        checks[f'{block} points'] = Contiguous(block, expanded.points, _nominated(pw))
    return checks

declaration_of(expanded)

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

Source code in src/math_spec/piecewise.py

def declaration_of(expanded: ExpandedPiecewise) -> PiecewiseDeclaration:
    """The curve of one expanded block, as a program carries it."""
    pw = expanded.block
    return PiecewiseDeclaration(
        over=pw.over,
        method=pw.method,
        breakpoints=tuple(link.values for link in pw.links),
    )

derivations_of(block, expanded)

How each parameter block's expansion emitted is filled, by name.

Everything emitted hangs off the mask, so a block masking nothing emits nothing for the caller to be told about.

Source code in src/math_spec/piecewise.py

def derivations_of(block: str, expanded: ExpandedPiecewise) -> dict[str, Derivation]:
    """How each parameter *block*'s expansion emitted is filled, by name.

    Everything emitted hangs off the mask, so a block masking nothing emits
    nothing for the caller to be told about.
    """
    if (mask := expanded.points) is None:
        return {}
    derivations: dict[str, Derivation] = {}
    if (values := _nominated(expanded.block)) is not None:
        derivations[mask] = MaskOf(block, values)
    if expanded.starts is not None:
        derivations[expanded.starts] = FirstOf(block, mask)
    if expanded.ends is not None:
        derivations[expanded.ends] = LastOf(block, mask)
    return derivations

expand_piecewise(schema)

Return schema as a :class:_ExpandedSpec — every piecewise: block expanded away.

Memoised on schema.

RAISES	DESCRIPTION
PiecewiseExpansionError	A block naming something that does not exist, or emitting a name the file already declares.

Source code in src/math_spec/piecewise.py

def expand_piecewise(schema: Spec) -> _ExpandedSpec:
    """Return *schema* as a :class:`_ExpandedSpec` — every ``piecewise:`` block expanded away.

    Memoised on *schema*.

    Raises:
        PiecewiseExpansionError: A block naming something that does not exist,
            or emitting a name the file already declares.
    """
    if isinstance(schema, _ExpandedSpec):
        return schema
    if schema._expansion is not None:
        return schema._expansion
    if not schema.piecewise:
        schema._expansion = _ExpandedSpec.model_construct(**dict(schema))
        return schema._expansion

    raw = schema.model_dump()
    raw.setdefault('variables', {})
    raw.setdefault('constraints', {})
    raw['expanded_piecewise'] = {name: _Block(schema, raw, name, pw).expand() for name, pw in schema.piecewise.items()}
    raw['piecewise'].clear()
    expanded = _ExpandedSpec.model_validate(raw)
    schema._expansion = expanded
    return expanded