EXTENSION REFERENCE

Register exact contracts.

The extension API describes operation structure, exact backend signatures, callback invocation, numerical metadata, and immutable catalogue descriptions.

BUILDERS AND CALLBACKS

Define, register, then seal.

hyperfold.ContextBuilder

ContextBuilder(**context_options)

Collects built-ins, Python extensions and explicitly loaded binary plug-ins. extension(id) returns an extension registrar, load_plugin(path) loads one shared library by explicit path transactionally and returns the builder, and build() seals the catalogue into a Context. A builder is single-use after sealing. Binary plug-ins use the development C ABI: their first registered kernel defines the operation contract, with shape checks inside callbacks. Python extensions still declare operations and kernels separately.

hyperfold.ExtensionRegistrar

register_operation(operation) -> ExtensionRegistrar
register_kernel(kernel) -> ExtensionRegistrar

Owns one dotted operation namespace. Registration methods return the registrar for chaining. Duplicate contracts, incompatible kernels and identifiers outside the registrar namespace are rejected before the context is built.

hyperfold.OperationId

OperationId(name: str, major: int = 1)
OperationId.parse(value: str | OperationId) -> OperationId

An immutable dotted name and non-zero major version. canonical renders name@major. Unversioned strings select major version 1.

hyperfold.OperandSpec

OperandSpec(role, kind, access=OperandAccess.READ)

Declares one logical operation operand. Inputs must be read-only; outputs must be write or read-write.

hyperfold.OperationSpec

OperationSpec(operation, operands, validator=None, numerics=None)

Declares ordered inputs and mandatory outputs. output aliases Output0; outputs, output_count and output_roles expose all outputs. preserves_output(role=OUTPUT) reports read-write output access. A validator receives an immutable role map and must return None.

hyperfold.BackendOperandSpec

BackendOperandSpec(role, kind, access=READ, dtype="float32", matrix_layout=None, compute_dtype=None)

Declares one exact Python kernel operand. Storage dtype, compute dtype, kind, access and matrix layout participate in exact dispatch. Omitted compute dtype uses the storage dtype’s default policy.

hyperfold.KernelSpec

KernelSpec(operation, backend, operands, callback, numerics=None)

Registers a synchronous Python callback for an exact backend signature. The callback accepts one Invocation, writes every output, and returns None.

hyperfold.Invocation

Invocation.bindings: Mapping[OperandRole, Any]
Invocation.backend: BackendKind
Invocation.cuda_device: int | None
Invocation.stream: int | None
Invocation.compute_dtypes: Mapping[OperandRole, str]

An immutable callback view. CUDA callbacks enqueue work on stream; Hyperfold synchronises it before returning. Bindings and compute dtype mappings are read-only.

ENUMERATIONS

Use explicit roles, storage and provenance.

Type	Members and contract
OperandAccess	`READ`, `WRITE`, `READ_WRITE`.
OperandRole	`INPUT_0`…`INPUT_2`, `OUTPUT`/`OUTPUT_0`…`OUTPUT_2`. `input(index)` and `output(index)` create roles through index 0x7fffffff; `input_index` and `output_index` validate the role direction.
OperandKind	`SCALAR`, `VECTOR`, `MATRIX`, `LU`, `EIGEN`.
BackendKind	`CPU_SCALAR`, `CPU_SIMD`, `CUDA`.
MatrixLayout	`ROW_MAJOR`, `COLUMN_MAJOR`.
ExtensionKind	`BUILTIN`, `PYTHON`, `NATIVE`.
DataLocation	`PAGEABLE_HOST`, `PINNED_HOST`, `CUDA_DEVICE`.
StorageFormat	`DENSE`, `SPARSE`, `DIAGONAL`, `CSR`, `CSC`, `COO`.
ComplexLayout	`NONE`, `SPLIT`, `INTERLEAVED`.

CATALOGUE DESCRIPTIONS

Read immutable registered state.

ExtensionProvenance

ExtensionProvenance(kind, id, version=None)

Identifies a built-in, Python, or native owner. Built-ins report the Hyperfold version; Python records use their registrar ID; native plug-ins use their declared ID and version.

OperationOperandDescription

OperationOperandDescription(role, access, kind)

Describes one contract role. kind may be absent for an untyped contract.

ImplementationOperandDescription

ImplementationOperandDescription(role, access, kind, dtype, location, storage_format, complex_layout, matrix_layout, compute_dtype=None)

Describes one directly registered kernel operand, including logical storage and compute dtypes, residency and layouts.

OperationImplementation

OperationImplementation(backend, operands, provenance, numerics=None)

Groups an exact direct signature with its backend, owner and optional algorithm metadata.

OperationDescription

OperationDescription(id, operands, provenance, implementations, numerics=None)

The complete result of Context.describe(): versioned identity, logical contract, owner, direct implementations and optional contract-level numerical metadata.

NUMERICAL METADATA

Describe shapes, algorithms and uncertainty.

Enum	Members
SymbolicOperator	`UNKNOWN`, `CONSTANT`, `SYMBOL`, `OPERAND_DIMENSION`, `OPERAND_VALUE`, `ADD`, `MULTIPLY`, `POWER`, `DIVIDE`, `MINIMUM`, `MAXIMUM`, `LOG2`.
ShapeRelation	`EQUAL`, `LESS_EQUAL`, `GREATER_EQUAL`, `DIVISIBLE_BY`.
NumericalRequirementKind	`FINITE`, `NONZERO`, `NONNEGATIVE`, `POSITIVE`, `NONSINGULAR`, `HERMITIAN`, `NORMAL`, `POSITIVE_DEFINITE`, `UNIQUE_DOMINANT_EIGENVALUE`.
RequirementPurpose	`EXECUTION`, `DEFINED_RESULT`, `UNIQUE_RESULT`, `ACCURACY`.
RequirementEnforcement	`CHECKED`, `GUARANTEED_BY_OPERAND`, `CALLER_RESPONSIBILITY`.
Stability	`EXACT`, `BACKWARD_STABLE`, `CONDITIONALLY_STABLE`, `NOT_GUARANTEED`, `UNKNOWN`.
PrecisionMode	`EXACT`, `NATIVE`, `WIDENED`, `MIXED`, `UNKNOWN`.
ReductionOrder	`NOT_APPLICABLE`, `SEQUENTIAL`, `PAIRWISE`, `PARALLEL_TREE`, `LIBRARY_DEFINED`, `UNKNOWN`.

SymbolicExpression

SymbolicExpression(operator, operands=(), integer=None, name=None, role=None, axis=None)

Immutable validated expression tree. Prefer unknown(), constant(value), symbol(name), dimension(role, axis), scalar_value(role), and operation(operator, *operands). canonical and str() return its stable representation.

OperandShape

OperandShape(role, rank)

Assigns a non-negative descriptor rank to one role.

ShapeConstraint

ShapeConstraint(left, relation, right)

Relates two symbolic shape or scalar expressions.

NumericalRequirement

NumericalRequirement(kind, roles, purpose, enforcement, note)

Records one non-empty, unique role set and whether the implementation checks, guarantees, or delegates the requirement.

OperationNumerics

OperationNumerics(shapes, constraints=(), requirements=(), notes=())

Contract-level ranks, shape relations and numerical preconditions. The shape block must cover every role exactly once.

ComplexityDescription

ComplexityDescription(work, auxiliary_space, notes=())

Symbolic asymptotic work and auxiliary storage; it is not a timing promise.

PrecisionDescription

PrecisionDescription(mode, accumulation_dtype, reduction_order, notes=())

Records arithmetic mode, optional accumulation dtype and reduction ordering.

AlgorithmParameter

AlgorithmParameter(name, value, description)

A named integer, floating or string parameter exposed by an implementation.

ImplementationNumerics

ImplementationNumerics(algorithm, stability, complexity, precision, parameters=(), notes=())

Direct algorithm identity, qualitative stability, complexity, precision, parameters and caveats. Use UNKNOWN rather than inventing unsupported claims.

Metadata is declarative. It does not run validators, alter dispatch, or replace executable numerical checks.

STRUCTURED OPERANDS

Own LU and eigen storage.

hyperfold.LUOperand

LUOperand(value: int | Any, *, dtype=None, compute_dtype=None)

Creates owned NumPy LU storage from a matrix or size. A size defaults to complex64; float16 and bfloat16 matrix storage promotes factor storage to float32. Read-only properties are dtype, compute_dtype, size, pivots, factors, and swaps.

hyperfold.EigenOperand

EigenOperand(size: int, *, dtype=np.complex64, compute_dtype=None)

Creates owned NumPy eigenvalue and column-oriented eigenvector storage. Read-only properties are dtype, compute_dtype, size, values, and vectors. Exported arrays retain the owning operand and exact strides.