Primitives

The closed registry of pure primitives values may apply.

primitives

The closed registry of pure primitives QIEC values may apply.

A primitive is nominal: it has a stable identity derived from its name, a fixed monomorphic signature, and a capability tag a backend either supports or refuses. Overloading is a surface concern: a source + on two integers lowers to add_int and on two reals to add_real, so the kernel never has to choose an implementation by inspecting a runtime value. The reference implementations here are what the evaluator runs; each host runtime carries the same table in its own language.

PRIMITIVES module-attribute

PRIMITIVES: Mapping[str, PrimitiveSignature] = MappingProxyType({signature.name: signature for signature, _ in _ENTRIES})

Every primitive by name.

The mapping is closed: a name absent here is not a primitive, and no backend may resolve one dynamically.

IMPLEMENTATIONS module-attribute

IMPLEMENTATIONS: Mapping[str, Callable[..., object]] = MappingProxyType({signature.name: implementation for signature, implementation in _ENTRIES})

The reference evaluator's implementation of every primitive, by name.

PrimitiveCapability

PrimitiveCapability = Literal['arithmetic', 'comparison', 'boolean', 'string', 'conversion', 'math', 'special', 'activation', 'weight']

The feature a target must support to render a primitive.

PrimitiveSignature dataclass

PrimitiveSignature(name: str, parameters: tuple[TypeExpr, ...], result: TypeExpr, capability: PrimitiveCapability)

One primitive's name, types, and the capability a backend needs for it.

PARAMETER	DESCRIPTION
name	The stable nominal name, such as "add_int". TYPE: str
parameters	The argument types, in order. TYPE: tuple[TypeExpr, ...]
result	The result type. TYPE: TypeExpr
capability	The feature a target must support to render the primitive. TYPE: PrimitiveCapability

id property

id: PrimitiveId

The primitive's stable identity.

RETURNS	DESCRIPTION
PrimitiveId	An identity derived from the builtin namespace and the name, so the same primitive has the same identity in every module.

primitive

primitive(name: str) -> PrimitiveSignature

Look up a primitive by name.

PARAMETER	DESCRIPTION
name	The nominal name. TYPE: str

RETURNS	DESCRIPTION
PrimitiveSignature	The primitive's signature.

RAISES	DESCRIPTION
KeyError	If no primitive has the name. Callers turn this into a source-located diagnostic; the registry itself has no location to blame.

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

def primitive(name: str) -> PrimitiveSignature:
    """Look up a primitive by name.

    Parameters
    ----------
    name : str
        The nominal name.

    Returns
    -------
    PrimitiveSignature
        The primitive's signature.

    Raises
    ------
    KeyError
        If no primitive has the name. Callers turn this into a
        source-located diagnostic; the registry itself has no location to
        blame.
    """
    try:
        return PRIMITIVES[name]
    except KeyError as error:
        raise KeyError(f"unknown QIEC primitive {name!r}") from error