Developer Guide

The Developer Guide explains how FHElium is implemented: Python CKKS orchestration, PyTorch operator dispatch, CPU and CUDA arithmetic, distributed transport, reusable execution, persistent artifacts, live Residency, JIT lowering, source ownership, and contributor validation.

Implementation map

Repository and implementation mapLocate values, engine algorithms, native registrations, runtime subsystems, generated interfaces, and focused tests.→Python-to-native execution stackFollow the Python API, generated wrappers, torch.ops schemas, PyTorch dispatch, CPU/OpenMP execution, CUDA kernels, and native ABI loading.→Arithmetic internalsInspect RNS/NTT layouts, multiplication, key switching, rescale, compressed plaintexts, and bootstrapping.→Distributed internalsTrace torch.distributed initialization, exact-value descriptors, payload collectives, limb reconstruction, and modular ciphertext reduction.→Buffers and CUDA GraphsInspect exact execution signatures, fixed-address value buffers, CUDA-event copy lifetime, graph capture, replay, and output ownership.→JIT internalsInspect the xDSL vocabulary, pass interfaces, executable schemas, readiness, and extension handling.→Storage and residencySeparate durable ArtifactStore generations from process-local live materializations, accounting, plans, leases, and admission.→

Contributor workflows

Contributor guidePrepare the source tree, preserve state and numerical requirements, and select the relevant validation surface.→Mathematical and state invariantsUse the canonical symbols, tensor axes, CKKS states, scale laws, and frontend-to-backend terminology.→Native operator workflowChange one torch.ops schema coherently across Python, generated wrappers, CPU/CUDA registrations, kernels, and ABI tests.→Documentation workflowChoose the right documentation family, maintain source ownership, and validate VitePress, Mermaid, generated API pages, and examples.→Binary packaging and releaseBuild the exact Torch and CUDA wheel matrix, publish immutable artifacts and cumulative package indexes, and operate the self-hosted release workflow.→

Cross-layer rule

A native operation is implemented as one cross-layer path:

Expanded diagram

100%

Changes to shape, mutation, row mapping, polynomial domain, modulus basis, or residue range must be represented consistently at every layer.

Start from an execution path

Before changing an implementation, trace one concrete path from its public entry point to the storage or native operation that performs the work. Record:

• public method and typed input state;
• Python orchestration and parameter/table selection;
• torch.ops schema and CPU/CUDA registrations when native;
• tensor axes, mutation, allocation, thread, and stream behavior;
• source commit and loaded native ABI manifest;
• smallest correctness oracle and focused tests.

For numerical work, retain the exact preset, level, scale, NTT backend, and first failing stage. Synchronize only around the suspected CUDA stage when locating asynchronous failures.