CONTEXTS

Control execution.

From version 0.1.1

A Context owns execution policy and a sealed operation catalogue. Pass one to high-level operations to control CPU workers, memory placement, CUDA device scope, streams and scheduling.

ConfigurationCPU + CUDA

cpu = hyperfold.Context(
    cpu_threads=8,
    parallel_work_threshold=65536,
    numa_policy="auto",
    pinning_policy="auto",
)
product = hyperfold.matmul(a, b, context=cpu)

gpu = hyperfold.Context(
    cuda_devices=0,
    stream_pool_size=32,
    scheduling="auto",
    cross_device="reject",
)

OPTIONS

Execution policy, made explicit.

cpu_threads

0 selects the automatic default. Positive values set the CPU worker count.

parallel_work_threshold

Minimum work size before Hyperfold uses parallel CPU execution; default 32768.

numa_policy

"disabled", "auto" or "strict" host placement.

pinning_policy

"disabled", "auto" or "strict" worker pinning.

cuda_devices

One CUDA device ID, a sequence of IDs, or None for lazy selection.

stream_pool_size

CUDA stream pool size; at least two, default 32.

external_stream

Caller-owned CUDA stream pointer that must outlive each call.

scheduling

"auto", "first_input" or "preferred".

cross_device

"reject", "peer_copy" or "staged_host".

CONTEXT REFERENCE

Construct and reuse execution policy.

Context(*, cpu_threads=0, parallel_work_threshold=32768, numa_policy="auto", pinning_policy="auto", cuda_devices=None, stream_pool_size=32, external_stream=None, scheduling="auto", cross_device="reject")

Every constructor argument is also exposed as a read-only-by-convention instance attribute. Native CPU state and the sealed catalogue are created with the context; per-device CUDA state is created lazily when the first CUDA operand is used.

Validation	Failure
`cpu_threads` and `parallel_work_threshold`	Must be non-negative integers.
`stream_pool_size`	Must be at least 2.
`external_stream`	Must be `None` or a non-negative native stream pointer.
`cuda_devices`	Must be one non-negative ID or a non-empty sequence of non-negative IDs; booleans are not IDs.
Policy strings	Must use one of the values listed in the options table.

Calls without context= share a lazily created process-wide default context. Pass an explicit context when execution policy, device scope, catalogue contents, or lifetime must be controlled.

DIRECT EXECUTION

Dispatch a registered operation.

Context.operations

operations() -> tuple[OperationId, ...]

Returns every operation in the sealed context in canonical order. Listing the catalogue does not initialise a CUDA device.

Context.describe

describe(operation: str | OperationId) -> OperationDescription

Returns the immutable structural contract, direct registered implementations, provenance, layouts, dtypes and optional numerical metadata. An unknown operation raises KeyError.

Context.execute

execute(operation, bindings: Mapping[OperandRole, Any], *, compute_dtypes=None) -> Any

Validates a complete role-keyed binding map and dispatches an exact native or Python implementation. A single output returns the caller-owned output object; multiple outputs return those objects as an ordered tuple.

Binding names and raw integers are not accepted. Inputs precede outputs in increasing role order. Every declared output is mandatory. compute_dtypes selects an exact registered storage/compute pair without casting storage; omitted array roles use the compiled default compute policy.

bindings = {
    hyperfold.OperandRole.INPUT_0: source,
    hyperfold.OperandRole.OUTPUT: destination,
}
result = context.execute("acme.copy@1", bindings)
assert result is destination

CUDA EXECUTION

Scope devices and streams.

cuda_devices=None permits lazy selection from the first CUDA operand. An explicit device or sequence limits the context; an operand outside that scope raises BackendError. Every individual operation selects one execution device.

Policy	Behaviour
scheduling="auto"	Uses output-device scheduling where applicable.
scheduling="first_input"	Prefers the first GPU input as execution device.
scheduling="preferred"	Uses the preferred device selected by the native execution policy.
cross_device="reject"	Requires all GPU operands on the selected execution device.
cross_device="peer_copy"	Uses CUDA peer copies when peer access is available; otherwise rejects the call.
cross_device="staged_host"	Moves cross-device data through pinned host staging storage.

A non-default external_stream is caller-owned and binds the context to the first CUDA device on which it is used. It must outlive every call. High-level Python calls and Python callbacks synchronise the selected stream before returning.

INTROSPECTION

Inspect the sealed catalogue.

operations() returns canonical operation IDs in stable order. describe() exposes operand roles, implementations, provenance and numerical metadata without initialising a CUDA device.

for operation_id in cpu.operations():
    description = cpu.describe(operation_id)
    print(description.id, description.provenance)
    for implementation in description.implementations:
        print(implementation.backend, implementation.operands)

Descriptions expose exact registered implementations rather than all adaptations that dispatch may construct. They describe compiled catalogue support, not the hardware currently visible to the process. Missing metadata is None; explicit uncertainty uses the relevant UNKNOWN enum member.

See the extension reference for every returned record and enum.