How-to guides
How-to guides solve calculation, deployment, execution, and diagnosis tasks using FHElium’s current interfaces. Choose the starting representation that fits the application: Eager operations execute CKKS steps immediately; a constructed or captured Program supports caller-composed transformation and linking; a compiled callable adds specialization and a function interface over a calculation. The two Compile entry paths share Programs, passes, materials, and Backend execution.
Each guide states the required setup, the procedure, and the evidence that establishes its outcome. For responsibilities and implementation mechanisms, use the Developer architecture overview.
Describe and execute calculations
Encode, encrypt, and evaluate CKKS dataPrepare keys and packed values, express arithmetic transitions, and measure decoded error.Build and transform a ProgramDescribe IR directly or capture Python, compose passes, and choose an execution product.Compile and reuse a callableSpecialize a function or Program and control preparation, pipelines, and Backend binding.Write and insert a Compilation passCollect analysis or implement a numerical rewrite using the current Compilation.Visualize mixed-level IRRender selected SSA dataflow and compare transformation snapshots.
Parameters and implementations
Choose a preset and chain depthPlan physical slots, rescale groups, actual scales, magnitude range, and precision.Choose operation implementations and loweringsRetain whole operations or expose RNS/NTT work and inspect Backend choices.
Materials and deployment
Provision the minimum required keysetDerive the evaluation-key inventory and preserve parameter identity and key custody.Bind, save, load, and deploy a ProgramSupply numerical materials, persist selected payloads, and link on the destination.Manage artifacts by logical nameStore values under checked immutable generations with defined local durability.Choose and switch a local execution devicePlace factories, values, keys, and compiled execution resources on CPU or CUDA.
Repeated execution and memory
Capture a repeated evaluatorCapture a fixed CUDA schedule, stage changing inputs, and manage borrowed output.Choose a homogeneous batch sizeCompare batch throughput, latency, and working sets across active depths.Choose a Residency control levelSelect direct movement, manager primitives, plans, or admission policy.Stream resources with bounded CUDA memoryChoose fixed buffers and managed residency windows with valid copy and use lifetimes.
Distributed execution
Diagnosis and performance
Diagnose Compile preparation failuresLocate missing facts, materials, implementations, or live execution resources.Diagnose a value-state mismatchReconcile configuration, key relation, depth, scale, representation, and placement.Diagnose a Residency failureInspect endpoint availability, budgets, protections, stale decisions, and partial execution.Diagnose a distributed hangFind divergent collective order, rank membership, placement, and local failures.Inspect runtime, memory, and CUDA topologyRecord installed backend capability and process-visible memory and topology.Screen NTT backends on the target GPURun the retained diagnostic recommender and confirm candidates on the current evaluator.Interpret NTT backend performanceExplain kernel-versus-primitive differences through launch, traffic, and resource costs.Optimize a workload systematicallyMeasure a correct execution path and isolate changes without changing its error criterion.
For the complete benchmark suite and report submission format, see Run and submit a benchmark.
Experimental features
Compose a bootstrap callableAssemble full-slot transforms and periodic reduction with defined coordinates.Implement a bootstrap componentSupply approximation, polynomial, transform, or periodic-reduction strategies.Use multiparty CKKSExercise collective arithmetic on synthetic data under the documented security limitations.