FHElium

Appearance

fhelium.ir ​

Represent and inspect permissive mixed-level FHElium programs.

The package owns xDSL module structure, registered dialects, open FHElium value/reference types, read-only Program analyses, and formatting.

DependencyKind ​

type alias View source

python
DependencyKind: TypeAlias = Literal['element', 'reindexed', 'mixing', 'unknown']

ValueDependency ​

class View source

python
ValueDependency(result_index: int, operand_index: int, axes: Mapping[str, DependencyKind] = field(default_factory=dict))

Describe one result's access to one operand along named logical axes.

element reads the corresponding position; reindexed reads a mapped position, including selection and broadcast; mixing may read multiple positions. Missing axes have unknown relationships. Axis names refer to coordinates at the operation's IR level, such as slot, coefficient, limb, or component. The coefficient axis is the last RNS payload dimension in both coefficient and NTT form.

Attributes ​

NameTypeDefault/value
result_indexint
operand_indexint
axesMapping[str, DependencyKind]field(default_factory=dict)

OperationDependencies ​

class View source

python
OperationDependencies(relations: tuple[ValueDependency, ...] = ())

Collect partial element relationships between results and operands.

An omitted pair or axis is unknown. Descriptions bound possible reads; they need not enumerate the elements read for each numerical input.

Attributes ​

NameTypeDefault/value
relationstuple[ValueDependency, ...]()

axes ​

method

python
def axes(result_index: int, operand_index: int) -> Mapping[str, DependencyKind]: ...

Return known axis relationships for one result/operand pair.

kind ​

method

python
def kind(result_index: int, operand_index: int, axis: str) -> DependencyKind: ...

Read one relationship, retaining unknown pairs and axes.

operation_dependencies ​

function View source

python
def operation_dependencies(operation: Operation) -> OperationDependencies: ...

Resolve the registered element relationships of a current IR instance.

DIALECT_VERSION ​

constant View source

python
DIALECT_VERSION = '0.2'

DIALECT_VERSION_ATTRIBUTE ​

constant View source

python
DIALECT_VERSION_ATTRIBUTE = 'fhelium.dialect_version'

SCHEMA_VERSION ​

constant View source

python
SCHEMA_VERSION = '1'

SCHEMA_VERSION_ATTRIBUTE ​

constant View source

python
SCHEMA_VERSION_ATTRIBUTE = 'fhelium.schema_version'

EncryptedType ​

class View source

python
EncryptedType()

Bases: OpenStateType

Encrypted value with partial scheme and representation state.

Attributes ​

NameTypeDefault/value
name'fhelium.encrypted'
ROLEClassVar[ValueRole]'encrypted'

EXECUTION_IMPLEMENTATION_ATTRIBUTE ​

constant View source

python
EXECUTION_IMPLEMENTATION_ATTRIBUTE = 'fhelium.execution.implementation'

FHElium ​

data View source

python
FHElium = Dialect('fhelium', [MaterialRefOp, ResourceRefOp, ConstantOp], [EncryptedType, MessageType, PlaintextType, MaterialType, ResourceType])

FHEliumCkks ​

data View source

python
FHEliumCkks = Dialect('fhelium_ckks', [PrepareCompressedPlaintextOp, EncodeOp, DecodeOp, IntegerCoefficientsToRnsOp, EncryptOp, DecryptOp, NegateOp, RotateOp, RotateManyOp, GroupedRotationWeightedSumOp, ToNttOp, FromNttOp, ToMontgomeryResiduesOp, ToStandardResiduesOp, AddOp, SumBatchOp, SubtractOp, MultiplyOp, AddScalarOp, MultiplyScalarOp, MultiplyIntegerScalarOp, AddPlaintextOp, MultiplyPlaintextOp, AddCompressedPlaintextOp, MultiplyCompressedPlaintextOp, RelinearizeOp, SwitchKeyOp, ConjugateOp, RescaleOp, ModSwitchOp, ReinterpretScaleOp, PrepareAddMessageOp, PrepareAddPlaintextOp, PrepareAddStaticOp, PrepareMultiplyMessageOp, PrepareMultiplyPlaintextOp, PrepareMultiplyStaticOp], [CiphertextType, PlaintextType, CompressedPlaintextType, EvaluationKeyType])

FHEliumLogical ​

data View source

python
FHEliumLogical = Dialect('fhelium_logical', [*_LOGICAL_OPERATION_TYPES], [EncryptedType, PublicType])

FHEliumSemantic ​

data View source

python
FHEliumSemantic = Dialect('fhelium_semantic', [AddOp, SubtractOp, MultiplyOp, NegateOp, RollOp], [SecretType, PublicType])

InferredValueState ​

class View source

python
InferredValueState(value: SSAValue, fields: Mapping[str, StateFact] = field(default_factory=dict))

Describe inferred state for one SSA value without modifying its IR type.

Attributes ​

NameTypeDefault/value
valueSSAValue
fieldsMapping[str, StateFact]field(default_factory=dict)

field ​

method

python
def field(name: str) -> StateFact: ...

Return one field or a dynamic placeholder when it is not represented.

with_fields ​

method

python
def with_fields(**updates: StateFact) -> InferredValueState: ...

Return the same SSA identity with updated analysis fields.

MaterialRefOp ​

class View source

python
MaterialRefOp(result_type: Attribute | None=None, *, symbol: str | StringAttr | None=None, kind: str | StringAttr | None=None, attributes: Mapping[str, Attribute] | None=None)

Bases: IRDLOperation

Reference an external Tensor by its entry in the material table.

Missing Tensor dimensions or state may remain unknown in a saved Program. The symbol names data; it does not select a resource class or a factory.

Attributes ​

NameTypeDefault/value
name'fhelium.material.ref'
valueresult_def()
symbolopt_attr_def(StringAttr)
kindopt_attr_def(StringAttr)
traitstraits_def(Pure())

MaterialType ​

class View source

python
MaterialType()

Bases: OpenStateType

Symbolic reference type for graph-external material.

Attributes ​

NameTypeDefault/value
name'fhelium.material'

REGISTERED_DIALECTS ​

constant View source

python
REGISTERED_DIALECTS = (FHElium, FHEliumSemantic, FHEliumLogical, FHEliumCkks, FHEliumRns, FHEliumNtt, FHEliumMemory, FHEliumDistributed, FHEliumFusion, Torch)

MessageType ​

class View source

python
MessageType()

Bases: OpenStateType

Public value with optional frontend and tensor metadata.

Attributes ​

NameTypeDefault/value
name'fhelium.message'
ROLEClassVar[ValueRole]'message'

DEFAULT_OPERATION_SPECS ​

constant View source

python
DEFAULT_OPERATION_SPECS = OperationSpecRegistry((*_DIALECT_OPERATION_SPECS, *_BRIDGE_OPERATION_SPECS))

OperationEffect ​

type alias View source

python
OperationEffect = Literal['pure', 'rng-write', 'mutation', 'opaque']

OperationSpec ​

class View source

python
OperationSpec(name: str, family: str, operand_arity: int | None, result_arity: int | None, operand_roles: tuple[str | None, ...] = (), result_roles: tuple[str | None, ...] = (), effect: OperationEffect = 'pure', validator: OperationValidator | None = None, operation_type: type[Operation] | None = None, dependencies: DependencyDescription = None)

Describe one operation's family, signature, roles, and effects.

Attributes ​

NameTypeDefault/value
namestr
familystr
operand_arityint | None
result_arityint | None
operand_rolestuple[str | None, ...]()
result_rolestuple[str | None, ...]()
effectOperationEffect'pure'
validatorOperationValidator | NoneNone
operation_typetype[Operation] | NoneNone
dependenciesDependencyDescriptionNone

resolve_dependencies ​

method

python
def resolve_dependencies(operation: Operation) -> OperationDependencies: ...

Resolve fixed or instance-dependent element relationships.

diagnostics ​

method

python
def diagnostics(operation: Operation) -> tuple[str, ...]: ...

Return local signature and role mismatches for operation.

OperationSpecRegistry ​

class View source

python
OperationSpecRegistry(specifications: Iterable[OperationSpec]=())

Immutable lookup of uniquely named semantic operation specifications.

names ​

property

python
names: tuple[str, ...]

Return registered operation names in declaration order.

get ​

method

python
def get(name: str) -> OperationSpec | None: ...

Return a specification, or None for permissive unknown IR.

require ​

method

python
def require(name: str) -> OperationSpec: ...

Return a specification or raise a lookup error.

OperationValidator ​

data View source

python
OperationValidator: TypeAlias = Callable[[Operation], tuple[str, ...]]

PlaintextType ​

class View source

python
PlaintextType()

Bases: OpenStateType

Encoded plaintext with partial representation state.

Attributes ​

NameTypeDefault/value
name'fhelium.plaintext'
ROLEClassVar[ValueRole]'plaintext'

Program ​

class View source

python
Program(module: ModuleOp)

Own one structurally valid, mixed-level xDSL module.

The module may contain registered FHElium operations, unknown extension dialects, partial state, and operations from several abstraction levels. Numerical analysis, transformation, backend coverage, and execution are responsibilities of consumers rather than this representation object.

material_descriptions ​

property

python
material_descriptions: dict[str, dict[str, object]]

Return saved material annotations, independently of live bindings.

Descriptions are open JSON objects. They explain data to callers and preparation tools; numerical execution does not validate against them. Mutate descriptions with set_material_description.

set_material_description ​

method

python
def set_material_description(symbol: str, description: Mapping[str, object]) -> None: ...

Set an annotation without checking binding identity or correctness.

empty ​

method

python
def empty(operations: Iterable[Operation]=(), *, attributes: Mapping[str, Attribute] | None=None) -> Program: ...

Construct a structurally valid module with default version marks.

from_function ​

method

python
def from_function(block: Block, result_types: Sequence[Attribute]=(), *, name: str='main', visibility: str | None=None, module_attributes: Mapping[str, Attribute] | None=None) -> Program: ...

Wrap one caller-built block in a top-level function.

parse ​

method

python
def parse(text: str, *, source_name: str='<unknown>') -> Program: ...

Parse structural IR while preserving unknown dialect content.

load ​

method

python
def load(path: str | PathLike[str]) -> Program: ...

Load one UTF-8 textual module.

to_text ​

method

python
def to_text(*, generic: bool=False, include_locations: bool=False) -> str: ...

Return xDSL text for the current module.

save ​

method

python
def save(path: str | PathLike[str]) -> None: ...

Write the current module and symbolic references as UTF-8 text.

clone ​

method

python
def clone() -> Program: ...

Return a structurally independent copy.

verify_structure ​

method

python
def verify_structure() -> None: ...

Run xDSL structural verification on the current module.

walk ​

method

python
def walk(*, include_module: bool=False) -> Iterator[Operation]: ...

Traverse operations in structural preorder.

functions ​

property

python
functions: tuple[FuncOp, ...]

Return registered top-level functions in module order.

function ​

method

python
def function(name: str='main') -> FuncOp: ...

Return the uniquely named top-level registered function.

single_block ​

method

python
def single_block(name: str='main') -> Block: ...

Return one function's block when a consumer needs that form.

ProgramFormatDetail ​

type alias View source

python
ProgramFormatDetail = Literal['summary', 'full']

ProgramInventory ​

class View source

python
ProgramInventory(operation_counts: Mapping[str, int], dialects: frozenset[str], functions: tuple[str, ...])

Operation counts and dialect/function names found in a Program.

operation_counts counts every walked operation by its registered or textual name. dialects contains the first namespace component of those names. functions preserves top-level function order. The inventory does not classify semantic validity, backend support, or executability.

Attributes ​

NameTypeDefault/value
operation_countsMapping[str, int]
dialectsfrozenset[str]
functionstuple[str, ...]

ResourceRefOp ​

class View source

python
ResourceRefOp(result_type: Attribute | None=None, *, symbol: str | StringAttr | None=None, kind: str | StringAttr | None=None, attributes: Mapping[str, Attribute] | None=None)

Bases: IRDLOperation

Reference an execution resource supplied by Backend binding.

The operation returns the bound value without materializing or mutating it. An unused reference can be removed with its unused resource requirement.

Attributes ​

NameTypeDefault/value
name'fhelium.resource.ref'
valueresult_def()
symbolopt_attr_def(StringAttr)
kindopt_attr_def(StringAttr)
traitstraits_def(Pure())

ResourceType ​

class View source

python
ResourceType()

Bases: OpenStateType

Symbolic reference type for graph-external execution resources.

Attributes ​

NameTypeDefault/value
name'fhelium.resource'

StateFact ​

class View source

python
StateFact(status: StateStatus, value: object | None = None, conflicting_values: tuple[str, ...] = ())

Record one known, symbolic, dynamic, or conflicting state property.

Attributes ​

NameTypeDefault/value
statusStateStatus
valueobject | NoneNone
conflicting_valuestuple[str, ...]()

known ​

method

python
def known(value: object) -> StateFact: ...

Construct one represented or inferred known state property.

symbolic ​

method

python
def symbolic(operator: str, *operands: object) -> StateFact: ...

Construct one symbolic state equation.

dynamic ​

method

python
def dynamic() -> StateFact: ...

Construct one property that requires later specialization.

conflict ​

method

python
def conflict(*conflicting_values: str) -> StateFact: ...

Construct one property from incompatible represented values.

StateStatus ​

type alias View source

python
StateStatus = Literal['known', 'symbolic', 'dynamic', 'conflict']

SymbolicExpression ​

class View source

python
SymbolicExpression(operator: str, operands: tuple[object, ...])

Represent a state equation whose operands are not all compile-time values.

Attributes ​

NameTypeDefault/value
operatorstr
operandstuple[object, ...]

Torch ​

data View source

python
Torch = Dialect('torch', [CallOp, TensorCallOp], [])

ValueRole ​

type alias View source

python
ValueRole = Literal['encrypted', 'message', 'plaintext', 'static']

ValueState ​

class View source

python
ValueState(role: str | None, type: Attribute, metadata: Mapping[str, Attribute])

Expose one SSA value's type, known role, and open metadata.

Attributes ​

NameTypeDefault/value
rolestr | None
typeAttribute
metadataMapping[str, Attribute]

analyze_evaluation_key_requirements ​

function View source

python
def analyze_evaluation_key_requirements(program: Program, *, entry: str='main') -> EvaluationKeyRequirements: ...

List the evaluation-key capabilities requested by entry.

The analysis reads logical/CKKS operations and lowered evaluation-key operand uses from the selected single-block function and its nested regions. It returns symbolic requirements only; it does not generate, load, bind, or validate key objects. Re-run it after any transformation that may add or remove those operations. Unresolved logical rolls contribute their integer shift; resolved rotation operations contribute the normalized step represented by their key operand. entry must name one single-block function. Generic key switching remains caller-named and is not representable by EvaluationKeyRequirements.

analyze_state_flow ​

function View source

python
def analyze_state_flow(program: Program, *, function: str='main') -> Mapping[SSAValue, InferredValueState]: ...

Infer shared value-state equations through one single-block function.

Missing properties remain dynamic and incompatible represented properties become conflicts. The analysis does not reject or rewrite the Program.

inventory_program ​

function View source

python
def inventory_program(program: Program) -> ProgramInventory: ...

Count operations and list dialect and function names in program.

The result contains operation counts, dialect namespace prefixes, and ordered top-level function names. This read-only inspection does not validate CKKS state, derive resource requirements, query backend coverage, or modify the Program.

analyze_value_states ​

function View source

python
def analyze_value_states(program: Program, *, function: str='main') -> Mapping[SSAValue, ValueState]: ...

Return represented state for one single-block function's SSA values.

create_dialect_context ​

function View source

python
def create_dialect_context() -> XdslContext: ...

Create an xDSL context containing every registered IR dialect.

Structural registration and preservation are independent of lowering readiness. Unknown application and vendor vocabulary remains legal and can coexist with operations from any registered abstraction level.

create_operation ​

function View source

python
def create_operation(context: XdslContext, name: str, *, operands: Sequence[SSAValue]=(), result_types: Sequence[Attribute]=(), attributes: Mapping[str, Attribute] | None=None, properties: Mapping[str, Attribute] | None=None, location: LocationAttr | None=None) -> Operation: ...

Construct a registered or preserved unknown operation by textual name.

dialects ​

module

fhelium.ir.dialects

format_program ​

function View source

python
def format_program(program: Program, *, detail: ProgramFormatDetail='summary', generic: bool=False, include_locations: bool=False) -> str: ...

Format a Program for reading rather than parsing or persistence.

JSON payloads stored in machine-oriented string attributes are rendered as nested attribute dictionaries and arrays. summary also omits duplicated module/material metadata; full includes every field. Use Program.to_text when output must round-trip through the parser.

load ​

function View source

python
def load(path: str) -> Program: ...

Load one textual mixed-level Program.

operation_name ​

function View source

python
def operation_name(operation: Operation) -> str: ...

Return the textual name of a registered or unknown operation.

parse ​

function View source

python
def parse(text: str, *, source_name: str='<unknown>') -> Program: ...

Parse one textual mixed-level Program.

value_role ​

function View source

python
def value_role(value_or_type: SSAValue | Attribute) -> ValueRole | None: ...

Return a registered value role, or None for non-value types.

value_type ​

function View source

python
def value_type(role: ValueRole, state: DictionaryAttr | Mapping[str, Attribute] | None=None) -> Attribute: ...

Construct the preserved open core type for a known value role.