fhelium.experimental.jit

Capture, import, transform, and execute mixed-dialect xDSL programs.

Program is the package's single source-independent graph abstraction. PyTorch capture, textual import, and direct xDSL construction all produce this same representation. Program construction and import perform structural verification while registered and unregistered dialect content remains available for interchange. check_readiness and run perform the separate numerical and execution checks for one selected entry. Pass implementations may use interim states while mutating a module, but each returned Program must be structurally valid: PassPipeline verifies every pass result, and the execution gate verifies structure again.

Programs contain serializable IR and symbolic references. Workspace retains live materials, resources, handlers, cryptographic services, and pass analyses outside that IR. Built-in transformation passes normally inspect every direct operation in every top-level function block, whereas requirement analysis, readiness, execution, and entry-oriented utilities operate on the selected selected entry function.

BatchMode

type alias View source

BatchMode = Literal['none', 'any']

BindingResolver

data View source

BindingResolver = Callable[[str, str | None, object, MutableMapping[Any, Any]], object]

CaptureResult

class View source

CaptureResult(program: Program, workspace: MutableMapping[Any, Any], function: Callable[..., ReturnT], signature: inspect.Signature, specs: Mapping[str, InputSpec], fx_code: str)

Bases: Generic[ReturnT]

Pair one captured Program with retained frontend and runtime state.

program is the same canonical Program used by textual import and direct construction and contains serializable IR. Captured Tensor constants appear in the graph as symbolic material operations; their live values are retained in workspace['materials']. function, signature, specs, and fx_code are capture-result attachments. The Program itself remains source-independent.

Attributes

Name	Type	Default/value
program	Program
workspace	MutableMapping[Any, Any]
function	Callable[..., ReturnT]
signature	inspect.Signature
specs	Mapping[str, InputSpec]
fx_code	str

runtime_signature

property

runtime_signature: inspect.Signature

Return the callable signature after specialized static inputs.

reference

method

def reference(*args: object, **kwargs: object) -> ReturnT: ...

Execute the captured Python callable with static inputs restored.

EliminateDeadValuesPass

class View source

EliminateDeadValuesPass(name: str = 'eliminate-dead-values')

Delete dead operations from a closed set of pure names.

Every unknown or extension operation is an effectful liveness root. Known operations carrying properties, regions, or successors are also retained, so this module-wide pass preserves unclassified and structural effects.

Attributes

Name	Type	Default/value
name	str	'eliminate-dead-values'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Compute module-wide SSA liveness from returns and effect roots.

InferredValueState

class View source

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

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

Attributes

Name	Type	Default/value
role	str | None
type	Attribute
metadata	Mapping[str, Attribute]

InputSpec

class View source

InputSpec(role: ValueRole, level: int = 0, scale: float | None = None, slots: SlotExtent = 'full', batch_mode: BatchMode = 'none', static_value: StaticValue = None)

Declare one function input's role in the PyTorch-to-FHE interface.

encrypted declares a logical slot extent, batch policy, level, and scale for a runtime Tensor or core Ciphertext. message declares public Python/PyTorch data passed through directly until an plaintext-preparation operation consumes it. plaintext declares a caller-owned core Plaintext whose state is validated at its encrypted consumer. static declares an immutable scalar specialized during capture and removed from the Program's runtime argument list.

Attributes

Name	Type	Default/value
role	ValueRole
level	int	0
scale	float | None	None
slots	SlotExtent	'full'
batch_mode	BatchMode	'none'
static_value	StaticValue	None

InsertMultiplyNttTransitionsPass

class View source

InsertMultiplyNttTransitionsPass(name: str = 'insert-multiply-ntt-transitions')

Insert ciphertext NTT transitions for logical multiplication.

Each encrypted operand of an unmarked binary multiply receives one fhelium.ckks.to_ntt operation. This covers both ciphertext-ciphertext and ciphertext-plaintext multiplication and records an idempotence marker. Malformed matches remain unchanged as successful skipped operations.

Attributes

Name	Type	Default/value
name	str	'insert-multiply-ntt-transitions'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Insert transitions module-wide or return a legal no-op report.

InsertPlaintextPreparationPass

class View source

InsertPlaintextPreparationPass(name: str = 'insert-plaintext-preparation')

Insert a plaintext-preparation operation for each logical mixed op.

The operation records whether addition uses the consumer ciphertext scale, multiplication encodes a message/static value at the engine default scale, or multiplication retains a caller-owned Plaintext's runtime scale. An operation marker makes repeated application idempotent.

Attributes

Name	Type	Default/value
name	str	'insert-plaintext-preparation'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Prepare recognized public operands across all function blocks.

InsertRelinearizationPass

class View source

InsertRelinearizationPass(name: str = 'insert-relinearization')

Materialize local relinearization obligations.

Each eligible single-result operation receives an immediately following relinearize operation; existing uses are redirected to that result and any remaining scheduling obligations are transferred to it.

Attributes

Name	Type	Default/value
name	str	'insert-relinearization'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Insert marked key switches module-wide or return a legal no-op.

InsertRescalePass

class View source

InsertRescalePass(name: str = 'insert-rescale')

Materialize locally ready rescale obligations at their source.

A single-result operation with only a rescale obligation receives an immediately following rescale operation. Other obligations and malformed conditional-rescale inputs retain the source operation and produce skipped diagnostics.

Attributes

Name	Type	Default/value
name	str	'insert-rescale'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Insert ready rescales module-wide and report local blockers.

JitError

class View source

JitError()

Bases: FHEliumError

Base error for JIT capture, transformation, and execution.

JitInputError

class View source

JitInputError()

Bases: JitError, ValueError

An input role, shape, or runtime value violates its declared requirements.

JitPassError

class View source

JitPassError()

Bases: JitError, RuntimeError

A graph pass, pipeline, or explicit validation gate failed.

JitPlanningError

class View source

JitPlanningError()

Bases: JitError, RuntimeError

A valid captured graph cannot satisfy the requested CKKS state plan.

JitTraceError

class View source

JitTraceError()

Bases: JitError, RuntimeError

A Python or PyTorch construct cannot be captured safely.

LateRelinearizationPass

class View source

LateRelinearizationPass(name: str = 'late-relinearization')

Count explicit relinearization candidates and preserve their placement.

Relinearization movement changes key-switch error scheduling and requires backend-specific legality analysis. This module-wide reporting step returns a legal no-op with every candidate counted as both matched and skipped, plus one explanatory diagnostic when candidates exist. A caller composes a backend optimizer to perform any authorized movement.

Attributes

Name	Type	Default/value
name	str	'late-relinearization'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Return an unchanged Program with candidate counts and diagnostics.

LateRescalePass

class View source

LateRescalePass(name: str = 'late-rescale')

Count explicit rescale candidates and preserve their placement.

Rescale movement changes CKKS rounding and accumulation behavior and requires backend-specific legality analysis. This module-wide reporting step returns a legal no-op with every candidate counted as both matched and skipped, plus one explanatory diagnostic when candidates exist. A caller composes a backend optimizer to perform any authorized movement.

Attributes

Name	Type	Default/value
name	str	'late-rescale'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Return an unchanged Program with candidate counts and diagnostics.

LowerLogicalToCkksPass

class View source

LowerLogicalToCkksPass(name: str = 'lower-logical-to-ckks')

Lower logical operations with local CKKS prerequisites.

Recognized operations are rewritten across all top-level function blocks. Locally unresolved patterns are retained and counted as skipped, allowing later specialized passes to supply policy or extension handling.

Attributes

Name	Type	Default/value
name	str	'lower-logical-to-ckks'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Lower locally ready operations and report retained patterns.

LowerSemanticToLogicalPass

class View source

LowerSemanticToLogicalPass(name: str = 'lower-semantic-to-logical')

Classify recognized encrypted semantic operations by operand roles.

The pass scans every top-level function block and rewrites only supported single-result local FHElium semantic operations. Other names, unknown roles, regions, successors, and unsupported arities remain structurally intact and are reported as skipped where they match the semantic surface.

Attributes

Name	Type	Default/value
name	str	'lower-semantic-to-logical'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Lower matching operations while preserving extension dialect IR.

OperationHandler

data View source

OperationHandler = Callable[[Operation, tuple[object, ...], MutableMapping[Any, Any]], object]

Pass

class View source

Pass()

Bases: Protocol

Define one named Program transformation or analysis step.

A successful implementation may return the input Program unchanged when no operation matches or when matched operations lack local prerequisites.

name

property

name: str

Stable name used in pipeline composition and reports.

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Run one pass and return its Program and behavior evidence.

PassPipeline

class View source

PassPipeline(passes: tuple[Pass, ...] = ())

Run an inspectable ordered tuple of independent Program passes.

One clone is made before the first pass, preserving the caller's source Program while allowing xDSL rewriters to mutate the private module in place. Every pass receives the exact same Workspace object, including when a pass returns a replacement Program. The pipeline retains all Workspace entries with their caller- or pass-defined interpretation and invalidation policy. After each pass, xDSL structural verification checks the returned Program; numerical and execution readiness remain separate decisions.

Attributes

Name	Type	Default/value
passes	tuple[Pass, ...]	()

names

property

names: tuple[str, ...]

Return pass names in execution order.

run

method

def run(program: Program, workspace: MutableMapping[Any, Any] | None=None) -> PipelineResult: ...

Run every pass over one clone with retained Workspace identity.

then

method

def then(*passes: Pass) -> PassPipeline: ...

Return a pipeline with passes appended in order.

before

method

def before(target: str, *passes: Pass) -> PassPipeline: ...

Insert passes before one uniquely named existing pass.

after

method

def after(target: str, *passes: Pass) -> PassPipeline: ...

Insert passes after one uniquely named existing pass.

replace

method

def replace(target: str, *passes: Pass) -> PassPipeline: ...

Replace one uniquely named pass with zero or more passes.

PassReport

class View source

PassReport(name: str, stats: PassStats, diagnostics: tuple[str, ...] = ())

Persist one named pass's counts and diagnostics as compact evidence.

Attributes

Name	Type	Default/value
name	str
stats	PassStats
diagnostics	tuple[str, ...]	()

PassResult

class View source

PassResult(program: Program, stats: PassStats = PassStats(), diagnostics: tuple[str, ...] = ())

Carry one pass's Program, activity counts, and diagnostics.

Attributes

Name	Type	Default/value
program	Program
stats	PassStats	PassStats()
diagnostics	tuple[str, ...]	()

changed

property

changed: bool

Whether reported transformation counts changed the Program.

unchanged

method

def unchanged(program: Program, *, matched: int=0, skipped: int=0, diagnostics: tuple[str, ...]=()) -> PassResult: ...

Record a successful pass invocation that preserved the Program.

PassStats

class View source

PassStats(matched: int = 0, transformed: int = 0, inserted: int = 0, removed: int = 0, skipped: int = 0)

Count one pass's local matching and rewrite activity.

Attributes

Name	Type	Default/value
matched	int	0
transformed	int	0
inserted	int	0
removed	int	0
skipped	int	0

PipelineResult

class View source

PipelineResult(program: Program, workspace: MutableMapping[Any, Any], reports: tuple[PassReport, ...])

Return the transformed Program, retained workspace, and pass reports.

Attributes

Name	Type	Default/value
program	Program
workspace	MutableMapping[Any, Any]
reports	tuple[PassReport, ...]

Program

class View source

Program(module: ModuleOp)

Wrap one mixed-dialect xDSL module as the canonical JIT graph.

Capture, textual import, direct construction, and extension frontends all produce this graph abstraction. Construction verifies the supplied xDSL module. Passes may subsequently mutate the exposed module in place and own the validity of their result. Readiness re-verifies structure and checks parameter/key capabilities, material/resource bindings, operation support, and the selected entry's executable schema; execution enforces runtime input and CKKS numerical requirements.

empty

method

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

Construct a structurally verified, versioned canonical module.

from_function

method

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 versioned top-level function.

block supplies the arguments, operations, and terminator; xDSL verification establishes structural integrity. CKKS state, parameters, graph-external bindings, scheduling obligations, and executable-schema validation are evaluated by selected passes or readiness checks.

parse

method

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

Parse mixed-dialect xDSL and verify its structural integrity.

The parser registers builtin, func, and FHElium structural vocabulary and preserves other dialects as unregistered xDSL objects. Numerical and execution readiness remains a later operation.

load

method

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

Load and structurally verify one UTF-8 textual module from path.

to_text

method

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

Serialize the current module state as xDSL text.

save

method

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

Write Program IR and symbolic references as UTF-8 xDSL text.

Live material and resource bindings remain in the graph-external Workspace and are therefore absent from the serialized module.

clone

method

def clone() -> Program: ...

Return a structurally independent clone of the canonical module.

walk

method

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

Traverse operations in structural preorder.

functions

property

functions: tuple[FuncOp, ...]

Return top-level registered func operations in module order.

entry_function

method

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

Return the uniquely named top-level registered function.

A Program is a structurally valid interchange module with any legal top-level contents. Entry-oriented consumers select a callable function and receive a precise lookup failure for zero or multiple matches.

entry_block

method

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

Return the unique block of one selected entry function.

requirements

method

def requirements(*, entry: str='main') -> ProgramRequirements: ...

Scan entry for symbolic bindings and runtime capabilities.

readiness

method

def readiness(workspace: Mapping[Any, Any] | None=None, *, entry: str='main') -> ReadinessReport: ...

Compare entry with graph-external execution capabilities.

transform

method

def transform(program_pass: Pass | PassPipeline, *additional_passes: Pass, workspace: MutableMapping[Any, Any] | None=None) -> PipelineResult: ...

Run selected passes over one Program clone and retain workspace.

The pipeline clones this Program exactly once, then passes the same mutable Workspace object to every pass and returns that identical object in PipelineResult. Passes may report a legal no-op, and pipeline completion alone makes no claim about execution readiness.

run

method

def run(*args: object, workspace: MutableMapping[Any, Any] | None=None, entry: str='main', **kwargs: object) -> Any: ...

Readiness-check and execute entry with dynamic result typing.

Runtime argument binding, role-specific input materialization, symbolic reference resolution, and interpretation occur for the selected entry. The return type is Any because imported and directly constructed Programs carry runtime IR structure rather than a Python callable type.

ProgramNotReadyError

class View source

ProgramNotReadyError(report: ReadinessReport)

Bases: JitError, RuntimeError

Reject one Program.run(...) request while preserving its full report.

ProgramRequirements

class View source

ProgramRequirements(operations: frozenset[str], unknown_operations: frozenset[str], materials: frozenset[str], resources: frozenset[str], torch_targets: frozenset[str], malformed_references: tuple[str, ...], rotation_steps: frozenset[int], requires_relinearization: bool, requires_engine: bool, return_count: int | None)

Describe symbolic runtime capabilities referenced by one entry.

analyze_requirements derives this immutable record from Program IR. Workspace comparison, materialization, parameter selection, and the final readiness decision are separate operations.

Attributes

Name	Type	Default/value
operations	frozenset[str]
unknown_operations	frozenset[str]
materials	frozenset[str]
resources	frozenset[str]
torch_targets	frozenset[str]
malformed_references	tuple[str, ...]
rotation_steps	frozenset[int]
requires_relinearization	bool
requires_engine	bool
return_count	int | None

ReadinessDiagnostic

class View source

ReadinessDiagnostic(code: str, message: str, subject: str | None = None, severity: Literal['error', 'warning'] = 'error')

Describe one concrete missing or malformed execution requirement.

Attributes

Name	Type	Default/value
code	str
message	str
subject	str | None	None
severity	Literal['error', 'warning']	'error'

ReadinessReport

class View source

ReadinessReport(requirements: ProgramRequirements, diagnostics: tuple[ReadinessDiagnostic, ...])

Carry selected-entry requirements and readiness diagnostics.

runnable is true exactly when diagnostics contains no item whose severity is "error". Warnings, including a missing version marker, are preserved as evidence and permit execution.

Attributes

Name	Type	Default/value
requirements	ProgramRequirements
diagnostics	tuple[ReadinessDiagnostic, ...]

runnable

property

runnable: bool

Whether this report contains no execution-blocking diagnostic.

missing_operations

property

missing_operations: frozenset[str]

Return operation or Torch targets lacking compatible handlers.

missing_materials

property

missing_materials: frozenset[str]

Return symbolic material names lacking Workspace bindings.

missing_resources

property

missing_resources: frozenset[str]

Return symbolic resource names lacking Workspace bindings.

SlotExtent

data View source

SlotExtent = int | Literal['full']

StateValidator

data View source

StateValidator = Callable[[Program, MutableMapping[Any, Any]], None]

StaticValue

data View source

StaticValue = bool | int | float | complex | str | None

SvgGraphVisualizationPass

class View source

SvgGraphVisualizationPass(output_path: str | PathLike[str], *, overwrite: bool=False, entry: str='main', presentation: SvgGraphPresentation | None=None, rank_direction: SvgGraphDirection='TB', name: str='visualize-svg')

Write one selected entry's SSA/dataflow graph to an SVG file.

The pass owns entry traversal, stable SSA naming, dependency edges, Graphviz construction, overwrite policy, and SVG production. A composed SvgGraphPresentation owns operation rows, tooltips, color classification, and theme values. Rendering returns the Program unchanged and does not establish execution readiness or numerical correctness.

Parameters

• output_path: Exact .svg file to write.
• overwrite: Replace an existing output file when true.
• entry: Unique single-block function entry to render.
• presentation: Operation evidence and theme policy. None constructs the default presentation.
• rank_direction: Graphviz rank direction: top-to-bottom, bottom-to-top, left-to-right, or right-to-left.
• name: Diagnostic pass name.

Attributes

Name	Type	Default/value
output_path	Path
presentation	SvgGraphPresentation
overwrite	bool	False
entry	str	'main'
rank_direction	SvgGraphDirection	'TB'
name	str	'visualize-svg'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Render one entry function and return an unchanged pass result.

ValidateCipherStatesPass

class View source

ValidateCipherStatesPass(validator: StateValidator, name: str = 'validate-cipher-states')

Apply one caller-selected numerical ciphertext-state validator.

The validator receives the current Program and retained Workspace and owns backend-specific policy for engines, parameter sets, and exact CKKS state. Successful validation returns the Program unchanged and reports the number of direct module-wide operation candidates.

Attributes

Name	Type	Default/value
validator	StateValidator
name	str	'validate-cipher-states'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Validate exact state through the selected service.

ValidateExecutableGraphPass

class View source

ValidateExecutableGraphPass(entry: str = 'main', name: str = 'validate-executable-graph')

Apply the selected-entry operation/schema/obligation execution gate.

Attributes

Name	Type	Default/value
entry	str	'main'
name	str	'validate-executable-graph'

run

method

def run(program: Program, workspace: MutableMapping[Any, Any]) -> PassResult: ...

Validate entry and return an unchanged Program report.

Workspace

class View source

Workspace()

Bases: dict[Any, Any]

Retain graph-external state across JIT passes and execution.

Callers and passes may exchange analyses, policies, diagnostics, caches, and extension-defined objects through arbitrary keys. The JIT runtime reserves materials, resources, handlers, torch_handlers, engine, evaluation_keys, public_key, material_resolver, and resource_resolver for execution bindings and services.

A Program stores only material and resource symbols. Readiness verifies that each selected symbol has a binding and that supplied resolvers are callable; it leaves both bindings and resolvers untouched. Execution calls the corresponding resolver when each reference operation is encountered, passing (symbol, kind, binding, workspace). The resolver's return value becomes that operation's runtime value. Pipeline and execution APIs retain the exact Workspace object supplied by the caller.

analyze_evaluation_key_requirements

function View source

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

Derive entry's key requirements from explicit CKKS operations.

analyze_requirements

function View source

def analyze_requirements(program: Program, *, entry: str='main') -> ProgramRequirements: ...

Collect runtime capabilities referenced by the selected entry block.

The scan covers entry arguments and direct operations in entry's unique block. It records operation names, extension operations, Torch targets, material/resource symbols, malformed references, CKKS engine use, rotation steps, relinearization, and return arity. Unknown and not-yet-lowered operations remain requirements. return_count=None represents a missing entry, a multi-block entry, or a non-unique return for subsequent readiness diagnostics.

Standard transformation passes may scan all top-level function blocks; this analysis intentionally describes only the entry selected for execution.

analyze_value_states

function View source

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

Return structural type metadata for entry arguments and results.

The mapping exposes open role/type attributes exactly as represented in IR. Specialized numerical state or parameter passes may publish richer analyses in the caller's Workspace while retaining this structural view.

check_readiness

function View source

def check_readiness(program: Program, workspace: Mapping[Any, Any] | None=None, *, entry: str='main') -> ReadinessReport: ...

Assess whether entry has the capabilities required to execute.

The assessment verifies Workspace binding container types, resolver callability, Program schema and dialect versions, a single-block entry with one final return, entry argument and built-in operation schemas, cleared scheduling obligations, callable handlers for extension operations and Torch targets, symbolic material/resource membership, a CKKS engine, and required rotation/relinearization keys compatible with that engine.

Readiness reserves the built-in runtime operation names for the interpreter; workspace['handlers'] authorizes extension operations only and cannot override a built-in schema or implementation. torch.call operations that touch encrypted or plaintext values require a bound callable in workspace['torch_handlers']. Pure-public Torch calls may instead use the runtime's audited target set.

This function reads Program and Workspace state without mutation. Material and resource bindings are checked by name, while resolver and handler calls, runtime argument validation, online-public-key requirements, and operation execution occur only in run_program.

default_pipeline

function View source

def default_pipeline() -> PassPipeline: ...

Return the standard semantic-to-CKKS lowering and scheduling policy.

The ordered passes scan all top-level function blocks, remove dead known-pure values, lower recognized semantic operations, and materialize plaintext preparation, NTT transitions, relinearization, and rescale obligations. The late-rescale and late-relinearization steps are reporting-only legal no-ops that count existing candidates and retain the Program unchanged. Callers add backend-specific movement optimizers and an validation pass according to their execution policy; run also performs its independent selected-entry readiness gate.

encrypted

function View source

def encrypted(*, level: int=0, scale: float | None=None, slots: SlotExtent='full', batch_mode: BatchMode='none') -> InputSpec: ...

Declare a secret slot tensor bound from Tensor or Ciphertext.

level and a non-None scale define the exact runtime CKKS input state; scale=None selects the bound engine's default scale. slots specifies either the engine's full capacity or an exact final-axis extent. batch_mode='none' requires a one-dimensional Tensor and an unbatched Ciphertext; 'any' permits leading batch axes.

Runtime Tensor inputs are encrypted online and therefore require workspace['engine'] and workspace['public_key']. Runtime Ciphertext inputs must match the engine's context, device, dtype, ring dimension, level, scale, and batch policy. A fixed non-full logical slot extent cannot be verified from an opaque Ciphertext, so this input form accepts Tensor input only. The retained Python reference callable consumes its ordinary public Tensor argument.

load

function View source

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

Load and structurally verify one textual mixed-dialect Program.

message

function View source

def message() -> InputSpec: ...

Declare public Tensor/scalar data processed by ordinary PyTorch.

Message-only subgraphs execute as public calls. A mixed encrypted operation introduces operation-specific encoding and plaintext preparation; that preparation derives the required CKKS representation from its ciphertext consumer.

parse

function View source

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

Parse and structurally verify one textual mixed-dialect Program.

plaintext

function View source

def plaintext() -> InputSpec: ...

Declare a caller-owned FHElium Plaintext with exact runtime state.

JIT execution requires a core Plaintext entry value and validates its level, scale, basis, domain, residues, prime identities, and batch requirements at its exact encrypted consumer. The retained Python reference callable consumes the corresponding public Tensor or scalar shadow supplied by the caller.

run

function View source

def run(program: Program, *args: object, workspace: MutableMapping[Any, Any] | None=None, entry: str='main', **kwargs: object) -> Any: ...

Readiness-check and execute entry from the supplied Program.

The result type is dynamic because textual and directly constructed Programs have no associated Python callable return annotation. A captured callable retains its static return type on CaptureResult.reference; execution reconstructs the runtime value described by Program output IR.

static

function View source

def static(value: StaticValue) -> InputSpec: ...

Specialize an immutable scalar Python input during capture.

A finite bool, int, float, complex, str, or None value participates in Python control and graph construction. Capture stores its serialized value in Program metadata and removes the parameter from CaptureResult.runtime_signature and Program execution inputs.

capture

function View source

def capture(function: Callable[..., ReturnT], *, inputs: Mapping[str, InputSpec], workspace: MutableMapping[Any, Any] | None=None) -> CaptureResult[ReturnT]: ...

Trace a Python callable into the canonical mixed-dialect Program.

inputs declares every parameter's encrypted, message, plaintext, or static role. Capture specializes static values, records Tensor constants as symbolic materials in the retained Workspace, lowers recognized arithmetic to semantic FHElium operations, and preserves other FX calls as torch.call operations. This structural frontend accepts pure-public and partially lowered graphs. Readiness and execution evaluate CKKS state, handlers, bindings, services, parameters, and keys for a selected entry.

validate_executable_graph

module

fhelium.experimental.jit.passes.validate_executable_graph