Structural runtime¶

Host-backed execution of checked encoder, decoder, and structural-loss computations.

structural_runtime ¶

Run host-backed structural computations on the reference machine.

StructuralRuntimeProvider `dataclass` ¶

StructuralRuntimeProvider(runtimes: tuple[RuntimeHandler, ...], term_types: frozenset[TypeId], name: str = 'structural')

Bases: RuntimeProvider

PyTorch components and validators for one structural invocation.

PARAMETER	DESCRIPTION
`runtimes`	The host handlers implementing the module's structural computations. TYPE: `tuple[RuntimeHandler, ...]`
`term_types`	Type identities whose host values are structural :class:`Term` instances. TYPE: `frozenset[TypeId]`
`name`	The provider name recorded in execution results and traces. TYPE: `str` DEFAULT: `'structural'`

attach ¶

attach(module: QiecModule, attachments: RuntimeAttachments) -> None

Attach each host computation handler.

PARAMETER	DESCRIPTION
`module`	The checked module, unused because the handlers were selected while constructing this provider. TYPE: `QiecModule`
`attachments`	The invocation's attachment table. TYPE: `RuntimeAttachments`

Source code in src/quivers/qiec/structural_runtime.py

def attach(self, module: QiecModule, attachments: RuntimeAttachments) -> None:
    """Attach each host computation handler.

    Parameters
    ----------
    module
        The checked module, unused because the handlers were selected
        while constructing this provider.
    attachments
        The invocation's attachment table.
    """

    del module
    for runtime in self.runtimes:
        attachments.bind_handler(runtime)

validator_for ¶

validator_for(type_: TypeExpr) -> RuntimeValidator | None

Return the validator for structural terms and torch values.

PARAMETER	DESCRIPTION
`type_`	The closed QIEC type a host argument or result must inhabit. TYPE: `TypeExpr`

RETURNS	DESCRIPTION
`RuntimeValidator \| None`	A predicate for scalar weights, structural terms, tensors, and structural products, or `None` when the provider does not cover `type_`.

Source code in src/quivers/qiec/structural_runtime.py

def validator_for(self, type_: TypeExpr) -> RuntimeValidator | None:
    """Return the validator for structural terms and torch values.

    Parameters
    ----------
    type_
        The closed QIEC type a host argument or result must inhabit.

    Returns
    -------
    RuntimeValidator | None
        A predicate for scalar weights, structural terms, tensors, and
        structural products, or ``None`` when the provider does not cover
        ``type_``.
    """

    if type_ == REAL or type_ == LOG_WEIGHT:
        return lambda value: (
            isinstance(value, int | float)
            and not isinstance(value, bool)
            or isinstance(value, torch.Tensor)
            and value.shape == ()
        )
    if _is_term_type(type_, self.term_types):
        return lambda value: isinstance(value, Term)
    if tensor_shape(type_) is not None:
        return lambda value: _tensor_value(type_, value)
    if isinstance(type_, TypeApplication) and type_.constructor.name.startswith(
        "Product"
    ):
        components = tuple(
            item for item in type_.arguments if isinstance(item, TypeApplication)
        )
        validators = tuple(self.validator_for(item) for item in components)
        if len(validators) != len(type_.arguments) or any(
            validator is None for validator in validators
        ):
            return None

        def product(value: object) -> bool:
            """Check a structural product componentwise.

            Parameters
            ----------
            value
                The host value to validate against the product type.

            Returns
            -------
            bool
                Whether ``value`` is a tuple whose components pass the
                corresponding validators.
            """

            return (
                isinstance(value, tuple)
                and len(value) == len(validators)
                and all(
                    validator is not None and validator(item)
                    for validator, item in zip(validators, value, strict=True)
                )
            )

        return product
    return None

structural_handler_definition ¶

structural_handler_definition(effect: EffectRef, result: TypeExpr, *, instance_name: str, computation_name: str) -> HandlerDef

Build the stable checked handler signature for one neural attachment.

PARAMETER	DESCRIPTION
`effect`	The applied `Compute` interface served by the attachment. TYPE: `EffectRef`
`result`	The closed result type returned by the host component. TYPE: `TypeExpr`
`instance_name`	The source-derived effect-instance name. TYPE: `str`
`computation_name`	The source-derived structural computation name. TYPE: `str`

RETURNS	DESCRIPTION
`HandlerDef`	A stable foreign handler declaration for the component.

Source code in src/quivers/qiec/structural_runtime.py

def structural_handler_definition(
    effect: EffectRef,
    result: TypeExpr,
    *,
    instance_name: str,
    computation_name: str,
) -> HandlerDef:
    """Build the stable checked handler signature for one neural attachment.

    Parameters
    ----------
    effect
        The applied ``Compute`` interface served by the attachment.
    result
        The closed result type returned by the host component.
    instance_name
        The source-derived effect-instance name.
    computation_name
        The source-derived structural computation name.

    Returns
    -------
    HandlerDef
        A stable foreign handler declaration for the component.
    """

    runtime = compute_handler(
        lambda argument, _context: argument,
        effect=effect,
        result_validator=lambda _value: True,
        answer_type=result,
        key=f"structural-{instance_name}-{computation_name}",
    )
    return replace(
        runtime.definition,
        name=f"__structural_{instance_name}_{computation_name}",
    )