fhelium.runtime.signature

Describe copy-compatible Tensor topology and FHElium value state.

Signatures are device-independent: matching CPU and CUDA values can share a signature. A ReusableValueBuffer records the target placement separately from its accepted payload signature.

TensorSignature

class View source

TensorSignature(shape: tuple[int, ...], stride: tuple[int, ...], dtype: torch.dtype, layout: torch.layout, requires_grad: bool)

Device-independent tensor topology accepted by one execution buffer.

Shape, stride, dtype, layout, and requires_grad determine copy compatibility with fixed target storage. The owning buffer or program records that storage's device.

Parameters

• shape: Tensor dimensions.
• stride: Element strides required by fixed target storage.
• dtype: Tensor scalar dtype.
• layout: PyTorch tensor layout, normally torch.strided.
• requires_grad: Autograd flag expected by the reusable payload.

Attributes

Name	Type	Default/value
shape	tuple[int, ...]
stride	tuple[int, ...]
dtype	torch.dtype
layout	torch.layout
requires_grad	bool

from_tensor

method

def from_tensor(tensor: torch.Tensor) -> TensorSignature: ...

Build a copy-compatibility signature for tensor.

Parameters

• tensor: Representative tensor whose device-independent topology is captured.

Returns

Signature excluding the tensor's current device.

ValueSignature

class View source

ValueSignature(type_name: str, schema_version: int, metadata: tuple[tuple[str, object], ...], tensors: tuple[tuple[str, TensorSignature], ...])

FHElium value state plus device-independent tensor topology.

The signature combines the serialized value type and schema version, frozen value metadata, and named Tensor signatures. Matching compares these recorded fields.

Parameters

• type_name: Registered serialized-value class name.
• schema_version: Value-serialization schema version.
• metadata: Frozen, deterministically ordered non-tensor state.
• tensors: Ordered tensor names and their device-independent signatures.

Attributes

Name	Type	Default/value
type_name	str
schema_version	int
metadata	tuple[tuple[str, object], ...]
tensors	tuple[tuple[str, TensorSignature], ...]

from_value

method

def from_value(value: TensorResident) -> ValueSignature: ...

Describe one serializable FHElium value.

Parameters

• value: Resident value whose type, metadata, and tensor topology are captured.

Returns

Device-independent value signature.

ValueTreeSignature

class View source

ValueTreeSignature(kind: TreeKind, leaf: TensorSignature | ValueSignature | None = None, children: tuple[ValueTreeSignature, ...] = (), keys: tuple[object, ...] = ())

Structure of tensors and FHElium values in a reusable execution payload.

Supported leaves are torch.Tensor and serializable FHElium fhelium.values.TensorResident values. Lists, tuples, and dictionaries may nest those leaves. Bind Python scalars and control objects statically in the callable.

Each Tensor leaf uses a TensorSignature; each FHElium-value leaf uses a ValueSignature containing its value metadata and Tensor topology.

Parameters

• kind: Node kind: tensor, FHElium value, list, tuple, or dictionary.
• leaf: Tensor/value signature for a leaf node; None for containers.
• children: Ordered signatures nested by a container node.
• keys: Dictionary keys in the same order as children; empty for all other node kinds.

Attributes

Name	Type	Default/value
kind	TreeKind
leaf	TensorSignature | ValueSignature | None	None
children	tuple[ValueTreeSignature, ...]	()
keys	tuple[object, ...]	()

from_value

method

def from_value(value: object) -> ValueTreeSignature: ...

Describe a supported tensor/value tree.

Parameters

• value: Representative tensor/value tree to describe.

Returns

Recursive device-independent structure and state signature.

Raises

• TypeError: If a leaf is not a tensor or serializable FHElium value, or if a container is not a list, tuple, or dictionary.

validate

method

def validate(value: object, *, path: str='value') -> None: ...

Require value to have this structure and state.

Tensor devices may differ because signatures describe transfer compatibility, not residency. Validation completes for the full tree before fhelium.runtime.ReusableValueBuffer copies any payload.

Parameters

• value: Candidate tree to compare with this signature.
• path: Root label used in mismatch diagnostics.

Raises

• ExecutionInputError: If structure, tensor topology, or value metadata differs.