FHElium

Appearance

fhelium.experimental.jit.passes ​

Unified Program passes and pipeline composition.

EliminateDeadValuesPass ​

class View source

python
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 ​

NameTypeDefault/value
namestr'eliminate-dead-values'

run ​

method

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

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

InsertMultiplyNttTransitionsPass ​

class View source

python
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 ​

NameTypeDefault/value
namestr'insert-multiply-ntt-transitions'

run ​

method

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

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

InsertPlaintextPreparationPass ​

class View source

python
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 ​

NameTypeDefault/value
namestr'insert-plaintext-preparation'

run ​

method

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

Prepare recognized public operands across all function blocks.

InsertRelinearizationPass ​

class View source

python
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 ​

NameTypeDefault/value
namestr'insert-relinearization'

run ​

method

python
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

python
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 ​

NameTypeDefault/value
namestr'insert-rescale'

run ​

method

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

Insert ready rescales module-wide and report local blockers.

LateRelinearizationPass ​

class View source

python
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 ​

NameTypeDefault/value
namestr'late-relinearization'

run ​

method

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

Return an unchanged Program with candidate counts and diagnostics.

LateRescalePass ​

class View source

python
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 ​

NameTypeDefault/value
namestr'late-rescale'

run ​

method

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

Return an unchanged Program with candidate counts and diagnostics.

LowerLogicalToCkksPass ​

class View source

python
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 ​

NameTypeDefault/value
namestr'lower-logical-to-ckks'

run ​

method

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

Lower locally ready operations and report retained patterns.

LowerSemanticToLogicalPass ​

class View source

python
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 ​

NameTypeDefault/value
namestr'lower-semantic-to-logical'

run ​

method

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

Lower matching operations while preserving extension dialect IR.

Pass ​

class View source

python
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

python
name: str

Stable name used in pipeline composition and reports.

run ​

method

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

Run one pass and return its Program and behavior evidence.

PassPipeline ​

class View source

python
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 ​

NameTypeDefault/value
passestuple[Pass, ...]()

names ​

property

python
names: tuple[str, ...]

Return pass names in execution order.

run ​

method

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

Run every pass over one clone with retained Workspace identity.

then ​

method

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

Return a pipeline with passes appended in order.

before ​

method

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

Insert passes before one uniquely named existing pass.

after ​

method

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

Insert passes after one uniquely named existing pass.

replace ​

method

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

Replace one uniquely named pass with zero or more passes.

PassReport ​

class View source

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

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

Attributes ​

NameTypeDefault/value
namestr
statsPassStats
diagnosticstuple[str, ...]()

PassResult ​

class View source

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

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

Attributes ​

NameTypeDefault/value
programProgram
statsPassStatsPassStats()
diagnosticstuple[str, ...]()

changed ​

property

python
changed: bool

Whether reported transformation counts changed the Program.

unchanged ​

method

python
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

python
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 ​

NameTypeDefault/value
matchedint0
transformedint0
insertedint0
removedint0
skippedint0

PipelineResult ​

class View source

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

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

Attributes ​

NameTypeDefault/value
programProgram
workspaceMutableMapping[Any, Any]
reportstuple[PassReport, ...]

StateValidator ​

data View source

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

SvgGraphVisualizationPass ​

class View source

python
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 ​

NameTypeDefault/value
output_pathPath
presentationSvgGraphPresentation
overwriteboolFalse
entrystr'main'
rank_directionSvgGraphDirection'TB'
namestr'visualize-svg'

run ​

method

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

Render one entry function and return an unchanged pass result.

ValidateCipherStatesPass ​

class View source

python
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 ​

NameTypeDefault/value
validatorStateValidator
namestr'validate-cipher-states'

run ​

method

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

Validate exact state through the selected service.

ValidateExecutableGraphPass ​

class View source

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

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

Attributes ​

NameTypeDefault/value
entrystr'main'
namestr'validate-executable-graph'

run ​

method

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

Validate entry and return an unchanged Program report.

default_pipeline ​

function View source

python
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.

validate_executable_graph ​

function View source

python
def validate_executable_graph(program: Program, *, entry: str='main', handled_operations: Collection[str]=(), handled_torch_targets: Collection[str]=()) -> None: ...

Validate the exact selected-entry schema consumed by the interpreter.

Validation requires structural module integrity, one selected single-block entry, valid entry input metadata, one final return, cleared scheduling obligations, exact built-in operation arities/roles/attributes, authorized Torch targets, authorized extension operations, and valid captured output metadata. Built-in runtime names are reserved: handled_operations can authorize extension names but cannot replace a built-in schema.

This entry-scoped execution gate complements permissive structural import and module-wide ordinary rewriting passes.

Towards full-stack encrypted execution infrastructures

Released under the MIT License. Copyright VisualDust and FHElium contributors