fhelium.backend

Resolve and execute Program operations with registered implementations.

BackendWorkspace

class View source

BackendWorkspace(named_resources: ResourceBindings = field(default_factory=ResourceBindings), materializer: ResourceMaterializer | None = None)

Hold one Backend instance's non-Tensor execution handles.

Attributes

Name	Type	Default/value
named_resources	ResourceBindings	field(default_factory=ResourceBindings)
materializer	ResourceMaterializer | None	None

with_named_resources

method

def with_named_resources(resources: ResourceBindings, *, override: bool=True) -> BackendWorkspace: ...

Return this workspace with an overlaid named-resource table.

TorchBroadcastImplementation

class View source

TorchBroadcastImplementation(name: str = 'torch-broadcast', supports_in_place: bool = False, operation_types: tuple[type[Operation], ...] = (distributed.BroadcastOp,))

Bases: _OperandResourceImplementation

Functionally broadcast one equal-layout Tensor from a group rank.

Attributes

Name	Type	Default/value
name	str	'torch-broadcast'
supports_in_place	bool	False
operation_types	tuple[type[Operation], ...]	(distributed.BroadcastOp,)

execute

method

def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

TorchCiphertextAddAllReduceImplementation

class View source

TorchCiphertextAddAllReduceImplementation(combine: Callable[[torch.Tensor, torch.Tensor, torch.Tensor], torch.Tensor], name: str = 'torch-ciphertext-add-all-reduce', supports_in_place: bool = False, operation_types: tuple[type[Operation], ...] = (distributed.AllReduceAddCiphertextOp,))

Bases: _OperandResourceImplementation

Reduce ciphertext payloads with an injected Backend Tensor addition.

Attributes

Name	Type	Default/value
combine	Callable[[torch.Tensor, torch.Tensor, torch.Tensor], torch.Tensor]	field(repr=False, compare=False)
name	str	'torch-ciphertext-add-all-reduce'
supports_in_place	bool	False
operation_types	tuple[type[Operation], ...]	(distributed.AllReduceAddCiphertextOp,)

execute

method

def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

DEVICE_RESOURCE_KIND

constant View source

DEVICE_RESOURCE_KIND = 'execution-device'

TorchGenericAllReduceImplementation

class View source

TorchGenericAllReduceImplementation(name: str = 'torch-generic-all-reduce', supports_in_place: bool = False, operation_types: tuple[type[Operation], ...] = (distributed.AllReduceOp,))

Bases: _OperandResourceImplementation

Fold all rank-local payloads with the operation's combine region.

Attributes

Name	Type	Default/value
name	str	'torch-generic-all-reduce'
supports_in_place	bool	False
operation_types	tuple[type[Operation], ...]	(distributed.AllReduceOp,)

execute

method

def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

execute_regions

method

def execute_regions(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], regions: tuple[TensorRegion, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

ImplementationRegistry

class View source

ImplementationRegistry(implementations: Sequence[ImplementationT]=(), *, category: str)

Store named implementations by operation class and identity.

The registry has no module-discovery or import-time mutation behavior. Backend components construct implementation objects beside their kernels, and an assembly function passes those objects to this registry.

operation_types

property

operation_types: tuple[type[Operation], ...]

Return operation classes in first declaration order.

implementations

property

implementations: tuple[ImplementationT, ...]

Return implementation contributions in construction order.

available

method

def available(operation_type: type[Operation]) -> tuple[str, ...]: ...

Return implementation names in declaration order.

supports

method

def supports(operation_type: type[Operation], *, name: str | None=None) -> bool: ...

Return whether at least one matching implementation is registered.

resolve

method

def resolve(operation_type: type[Operation], *, requested: str | None) -> ImplementationT: ...

Resolve one named implementation, refusing ambiguous defaults.

TorchMemoryTransferImplementation

class View source

TorchMemoryTransferImplementation(name: str = 'torch-memory-transfer', operation_types: tuple[type[memory.TransferOp], ...] = (memory.TransferOp,), supports_in_place: bool = False)

Move one Tensor payload to a caller-bound device and memory space.

Attributes

Name	Type	Default/value
name	str	'torch-memory-transfer'
operation_types	tuple[type[memory.TransferOp], ...]	(memory.TransferOp,)
supports_in_place	bool	False

resource_requirements

method

def resource_requirements(invocation: OperationInvocation) -> tuple[ResourceRequirement, ...]: ...

execute

method

def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], /, *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

OperationBackend

class View source

OperationBackend(registry: OperationImplementationRegistry | None=None, workspace: BackendWorkspace | None=None, *, named_resources: ResourceBindings | None=None, materializer: ResourceMaterializer | None=None)

Own operation implementations and one live Backend workspace.

Attributes

Name	Type	Default/value
registry	OperationImplementationRegistry
workspace	BackendWorkspace

named_resources

property

named_resources: ResourceBindings

Return named low-level resources configured before linking.

with_named_resources

method

def with_named_resources(resources: ResourceBindings, *, override: bool=True) -> OperationBackend: ...

Return this implementation set with an extended resource table.

diagnostics

method

def diagnostics(operation: Operation, *, implementation: str | None=None, in_place: bool=False) -> tuple[str, ...]: ...

Report implementation or resource binding failures.

link

method

def link(compilation: Compilation, *, pipeline: Pipeline | None=None) -> ProgramExecutable: ...

Link one Compilation with this workspace into an executable.

OperationDispatch

class View source

OperationDispatch(invocation: OperationInvocation, implementation: OperationImplementation, requirements: tuple[ResourceRequirement, ...], effect: OperationEffect, in_place: bool = False, prepared_regions: bool = False)

Hold one operation's resolved Backend call before resource linking.

Attributes

Name	Type	Default/value
invocation	OperationInvocation
implementation	OperationImplementation
requirements	tuple[ResourceRequirement, ...]
effect	OperationEffect
in_place	bool	False
prepared_regions	bool	False

OperationImplementation

class View source

OperationImplementation()

Bases: Protocol

Execute one or more registered operations on Tensor payloads.

name

property

name: str

operation_types

property

operation_types: tuple[type[Operation], ...]

supports_in_place

property

supports_in_place: bool

resource_requirements

method

def resource_requirements(invocation: OperationInvocation) -> tuple[ResourceRequirement, ...]: ...

execute

method

def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], /, *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

OperationImplementationRegistry

class View source

OperationImplementationRegistry(implementations: Sequence[OperationImplementation]=(), *, operation_specs: OperationSpecRegistry=DEFAULT_OPERATION_SPECS)

Resolve implementations by operation class and identity.

operation_types

property

operation_types: tuple[type[Operation], ...]

implementations

property

implementations: tuple[OperationImplementation, ...]

Return implementation contributions in construction order.

with_implementations

method

def with_implementations(implementations: Sequence[OperationImplementation]) -> OperationImplementationRegistry: ...

Return this registry extended by caller-supplied contributions.

available

method

def available(operation_type: type[Operation]) -> tuple[str, ...]: ...

supports

method

def supports(operation: Operation, *, implementation: str | None=None) -> bool: ...

resolve

method

def resolve(operation: Operation, *, requested: str | None, in_place: bool=False) -> OperationImplementation: ...

resolve_type

method

def resolve_type(operation_type: type[Operation], *, requested: str | None, in_place: bool=False) -> OperationImplementation: ...

effect

method

def effect(operation_type: type[Operation]) -> OperationEffect: ...

Return the registered effect of one operation class.

OperationInvocation

class View source

OperationInvocation(operation_type: type[Operation], operand_count: int, result_count: int, attributes: Mapping[str, object] = field(default_factory=dict), operand_prime_ids: tuple[tuple[int, ...] | None, ...] = (), operand_bases: tuple[str | None, ...] = (), operand_components: tuple[int | None, ...] = (), result_prime_ids: tuple[tuple[int, ...] | None, ...] = ())

Describe a backend operation call without an SSA graph.

Attributes

Name	Type	Default/value
operation_type	type[Operation]
operand_count	int
result_count	int
attributes	Mapping[str, object]	field(default_factory=dict)
operand_prime_ids	tuple[tuple[int, ...] | None, ...]	()
operand_bases	tuple[str | None, ...]	()
operand_components	tuple[int | None, ...]	()
result_prime_ids	tuple[tuple[int, ...] | None, ...]	()

ProgramDispatchTable

class View source

ProgramDispatchTable(operations: Mapping[Operation, OperationDispatch])

Map executable Program operations to resolved Backend calls.

Attributes

Name	Type	Default/value
operations	Mapping[Operation, OperationDispatch]

ProgramExecutable

class View source

ProgramExecutable(program: Program, dispatch_table: ProgramDispatchTable, resources: tuple[BoundResource, ...], resource_indices: Mapping[Operation, tuple[int, ...]], bound_resources: Mapping[Operation, BoundResource], bound_materials: Mapping[Operation, object])

Execute host control flow prepared from one linked Program.

Calls and external bindings are resolved once. Generated local variables preserve dataflow, and flat-block temporaries are released at last use. host_source exposes the prepared control flow without serializing its bound objects. Tensor storage and aliases retain ordinary PyTorch ownership.

Attributes

Name	Type	Default/value
program	Program
dispatch_table	ProgramDispatchTable
resources	tuple[BoundResource, ...]
resource_indices	Mapping[Operation, tuple[int, ...]]
bound_resources	Mapping[Operation, BoundResource]
bound_materials	Mapping[Operation, object]
host_source	str	field(init=False, repr=False, compare=False)

manifest

property

manifest: Mapping[str, object]

run

method

def run(*inputs: object) -> object: ...

ResourceMaterializer

class View source

ResourceMaterializer()

Bases: Protocol

Create missing live resources for one whole Program.

materialize

method

def materialize(requirements: tuple[ResourceRequirement, ...], /) -> ResourceBindings: ...

Return bindings that satisfy the requested missing resources.

ProcessGroupExecutionResource

class View source

ProcessGroupExecutionResource(group: torch.distributed.ProcessGroup | None = None)

Expose one initialized rank-local process group to Backend operations.

group=None names PyTorch's default process group. Ranks represented by distributed IR are process-group ranks; conversion to a global rank occurs only when a PyTorch collective requires it.

Attributes

Name	Type	Default/value
group	torch.distributed.ProcessGroup | None	None

rank

property

rank: int

Return this process's rank within the selected group.

size

property

size: int

Return the number of participating group ranks.

global_rank

method

def global_rank(group_rank: int) -> int: ...

Map one group-relative rank to its process-global rank.

TorchProcessGroupQueryImplementation

class View source

TorchProcessGroupQueryImplementation(name: str = 'torch-process-group-query', supports_in_place: bool = False, operation_types: tuple[type[Operation], ...] = (distributed.RankOp, distributed.GroupSizeOp))

Bases: _OperandResourceImplementation

Read group rank and size as scalar index Tensors.

Attributes

Name	Type	Default/value
name	str	'torch-process-group-query'
supports_in_place	bool	False
operation_types	tuple[type[Operation], ...]	(distributed.RankOp, distributed.GroupSizeOp)

execute

method

def execute(invocation: OperationInvocation, inputs: tuple[torch.Tensor, ...], resources: tuple[BoundResource, ...], *, in_place: bool) -> tuple[torch.Tensor, ...]: ...

distributed_operation_contributions

function View source

def distributed_operation_contributions(*, ciphertext_add: Callable[[torch.Tensor, torch.Tensor, torch.Tensor], torch.Tensor] | None=None) -> tuple[TorchProcessGroupQueryImplementation | TorchBroadcastImplementation | TorchGenericAllReduceImplementation | TorchCiphertextAddAllReduceImplementation, ...]: ...

Return distributed implementations for one execution owner.

The specialized ciphertext-add implementation is contributed only when an execution owner supplies addition through its existing Tensor Backend. A Compile pass may instead lower the specialized operation to generic all-reduce with a visible combine region.

prepare_ciphertext_add_combine

function View source

def prepare_ciphertext_add_combine(backend: OperationBackend, *, modulus_basis: str='Q', implementation: str | None=None) -> Callable[[torch.Tensor, torch.Tensor, torch.Tensor], torch.Tensor]: ...

Bind ciphertext addition through an existing operation backend.

The returned callable owns no Engine or public CKKS value. It reuses the execution owner's selected RNS implementation and concrete arithmetic parameters supplied by each distributed reduction.

requested_implementation

function View source

def requested_implementation(operation: Operation, caller_selection: str | None=None) -> str | None: ...

Return the implementation recorded in IR or selected by the caller.

An assignment written by a Compile pass is a hard constraint. A caller may select an unassigned operation, but it may not contradict the Program.