Metadata-Version: 2.4
Name: fhelium
Version: 0.30.0
Summary: A tensor-native CKKS framework for fully homomorphic encryption on CPU and NVIDIA CUDA with Python and PyTorch.
Keywords: ckks,cryptography,encrypted computation,fhe,fully homomorphic encryption,homomorphic encryption,pytorch,tensor computing,cpu,cuda
Author-Email: Gavin Gong <gavin@gong.host>, PuQing <me@puqing.work>
Maintainer-Email: Gavin Gong <gavin@gong.host>, PuQing <me@puqing.work>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Project-URL: Homepage, https://fhelium.550w.host
Project-URL: Documentation, https://fhelium.550w.host
Project-URL: Repository, https://github.com/VisualDust/fhelium
Project-URL: Issues, https://github.com/VisualDust/fhelium/issues
Requires-Python: <3.14,>=3.12
Requires-Dist: click>=8.4.2
Requires-Dist: mpmath<1.4,>=1.3.0
Requires-Dist: numpy>=2.5.1
Requires-Dist: pydot<5,>=4.0.1
Requires-Dist: psutil<8,>=6.1
Requires-Dist: rich>=15.0.0
Requires-Dist: safetensors>=0.8.0
Requires-Dist: textual>=8.2.8
Requires-Dist: torch<2.14,>=2.10
Requires-Dist: triton-csprng<0.2,>=0.1.4
Requires-Dist: triton-windows==3.7.1.post27; sys_platform == "win32"
Requires-Dist: xdsl<0.69,>=0.68
Description-Content-Type: text/markdown
Dynamic: Requires-Dist

# FHElium: FHE, built from the tensor up

> Pronounced **“philium”** /ˈfɪliəm/ or **“F-helium”** /ˌɛf ˈhiːliəm/.

[![PyPI version](https://img.shields.io/pypi/v/fhelium)](https://pypi.org/project/fhelium/) [![Python versions](https://img.shields.io/pypi/pyversions/fhelium)](https://pypi.org/project/fhelium/) [![PyPI downloads](https://img.shields.io/pypi/dw/fhelium)](https://pypi.org/project/fhelium/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

**Documentation:** [fhelium.550w.host](https://fhelium.550w.host)

FHElium is a full-stack CKKS framework for Python and PyTorch. It provides native CPU and NVIDIA CUDA execution, tensor-backed encrypted values, immediate Eager evaluation, inspectable Compile Programs, runtime resource management, and rank-local distributed execution.

## Install

FHElium supports CPython 3.12 and 3.13 on Linux x86-64, Windows x86-64, and macOS Apple Silicon. It builds against the PyTorch installation selected by the user. CUDA builds require a compatible CUDA toolkit and C++17 compiler; macOS uses the CPU implementation rather than PyTorch MPS.

Use the [installation selector](https://fhelium.550w.host/#install-fhelium) to choose the operating system, Python version, PyTorch version, and CPU or CUDA configuration. The selector provides a prebuilt-wheel command when that exact combination is published and a source-build command otherwise.

For a source installation, install the intended PyTorch package first, then build FHElium in the same environment:

```bash
python -m pip install "scikit-build-core==1.0.3" "cmake>=3.18" ninja
python -m pip install \
  --no-binary=fhelium \
  --no-build-isolation --no-cache-dir --verbose \
  fhelium
```

`--no-build-isolation` keeps the selected Torch build available to CMake, and `--no-cache-dir` prevents reuse of a wheel compiled for another Torch or CUDA environment. Set `CMAKE_ARGS="-DFHELIUM_NATIVE_BACKENDS=CPU"` for a CPU-only build, `CUDA` for CUDA-only, or `CPU+CUDA` for both implementations.

See the [installation guide](https://fhelium.550w.host/tutorial/installation) for compiler requirements, CUDA architecture selection, and troubleshooting.

## Programming models

FHElium provides two first-class ways to execute CKKS computations:

- `fhelium.eager.Engine` executes each requested operation immediately;
- `fhelium.compile` constructs and transforms source-independent `fhelium.ir.Program` objects.

Both use the same `fhelium.backend` operation implementations and arithmetic resources. Eager follows the public state transition of each called operation and dispatches from operand placement. Compile callers select the passes that assign CKKS state, preserve or lower operations, bind materials and keys, and construct a `ProgramExecutable`.

### Eager execution

```python
import torch
import fhelium as fh
from fhelium.eager import Engine

# Change this to "cuda:0" to create inputs and keys on CUDA.
torch.set_default_device("cpu")
engine = Engine(fh.Preset.slots8192_scale40_depth7_int64)

x = torch.linspace(-0.05, 0.05, 32, dtype=torch.float64)
y = torch.linspace(0.02, -0.02, 32, dtype=torch.float64)

ct_x = engine.encrypt_message(x)
ct_y = engine.encrypt_message(y)

ct_sum = engine.add(ct_x, ct_y)

x_ntt = engine.coefficient_domain_to_ntt_domain(ct_x)
y_ntt = engine.coefficient_domain_to_ntt_domain(ct_y)
product_triplet = engine.multiply(x_ntt, y_ntt)
ct_product = engine.rescale_to_next_depth(
    engine.relinearize(product_triplet)
)

rotation_key = engine.rotation_key(1)
ct_rotated = engine.rotate_with_key(ct_x, rotation_key)

sum_clear = engine.decrypt_message(ct_sum, is_real=True)[: x.numel()]
product_clear = engine.decrypt_message(ct_product, is_real=True)[: x.numel()]

torch.testing.assert_close(sum_clear, x + y, atol=2e-5, rtol=0)
torch.testing.assert_close(product_clear, x * y, atol=2e-5, rtol=0)
```

Each encrypted value records its CKKS level, actual scale, active primes, polynomial domain, modulus basis, residue representation, and component count. Multiplication does not implicitly relinearize or rescale, and operations do not silently move Tensor payloads between devices.

### Compile Programs

Compile captures or imports a source-independent Program and applies the pass sequence selected by the caller:

```python
from fhelium import compile as fh_compile


def workload(secret, public):
    return secret + public


captured = fh_compile.capture(
    workload,
    inputs={
        "secret": fh_compile.encrypted(),
        "public": fh_compile.message(),
    },
)

pipeline = fh_compile.Pipeline(
    (
        fh_compile.EliminateDeadValuesPass(),
        fh_compile.LowerSemanticToLogicalPass(),
    )
)
compiled = pipeline.run(captured)

print(compiled.program.to_text())
print(compiled.reports)
```

A caller can continue from the same `Compilation` with CKKS state assignment, transition placement, CKKS-to-RNS/NTT lowering, key analysis, Backend linking, or custom passes. See [`examples/12_compile_pipeline.py`](./examples/12_compile_pipeline.py) for an encrypted end-to-end execution and [`examples/14_compile_custom_pass.py`](./examples/14_compile_custom_pass.py) for a caller-defined BSGS transformation.

`fh_compile.compile` also provides a bare function decorator that captures Tensor materials and uses the `default_lower_and_fuse_pipeline` recipe when no pipeline is supplied. Backend and pipeline overrides expose finer control over the same compilation stages as the manual path. See [`examples/11_compile_jit.py`](./examples/11_compile_jit.py) for prepared execution and component/NTT fusion.

## Runtime and distributed execution

`fhelium.runtime` provides device observations, reusable value buffers, and CUDA Graph execution. `fhelium.residency` manages live value placement and lifetime accounting. `fhelium.distributed` provides rank-local value transport and CKKS-aware collectives. Bootstrapping and multiparty CKKS interfaces are available under `fhelium.experimental`.

The runtime components can be used independently around an evaluator:

```python
from fhelium.runtime import (
    CpuTopology,
    CudaGraphProgram,
    MemorySnapshot,
    ReusableValueBuffer,
)
from fhelium.residency import PAGEABLE_HOST, ResidencyManager

cpu = CpuTopology.probe()
memory = MemorySnapshot.read("cuda:0")
buffer = ReusableValueBuffer.like(prototype, device="cuda:0")
program = CudaGraphProgram.capture(evaluator, example_inputs=(prototype,))
result = program.replay(next_input, synchronize=True)

residency = ResidencyManager()
weight_handle = residency.adopt(weight, at=PAGEABLE_HOST)
snapshot = residency.snapshot()
```

FHElium uses a single-program, multiple-data (SPMD) model. Each process owns a local device and an Eager Engine; the application chooses its data partition, keys, process groups, and communication schedule.

```python
import torch
import fhelium as fh
import fhelium.distributed as dist
from fhelium.eager import Engine


def main():
    dist.init()
    torch.set_default_device(dist.local_device())
    engine = Engine(fh.Preset.slots32768_scale40_depth34_int64)

    weight = (
        engine.encode(torch.ones(16, dtype=torch.float64))
        if dist.get_rank() == 0
        else None
    )
    weight = dist.broadcast_plaintext(weight, src=0)
    print(
        f"rank={dist.get_rank()} device={weight.device} depth={weight.depth}"
    )
    dist.shutdown()


if __name__ == "__main__":
    main()
```

Save the program as `distributed_example.py` and launch one process per local GPU:

```bash
torchrun --standalone --nproc-per-node=2 distributed_example.py
```

The distributed API supports transport of independent values, modular reduction of additive ciphertext partials, and partitioning/reconstruction of residue-number-system limbs.

## Command-line tools

The `fhelium` command reports the installed version, inspects CUDA devices and peer topology, runs benchmarks, and evaluates NTT backend candidates:

```bash
fhelium version
fhelium cuda info
fhelium cuda topo --bandwidth
fhelium benchmark list
fhelium benchmark run --device cpu --output results/benchmark.json
fhelium benchmark recommend ntt --suite kernel --device cuda:0
```

Running `fhelium benchmark` without a subcommand opens the interactive benchmark interface. See [Inspect runtime and CUDA](https://fhelium.550w.host/how-to/inspect-runtime-and-cuda) and [Benchmark methodology](https://fhelium.550w.host/benchmarks/methodology) for the complete command options and output schemas.

## Documentation and examples

- [Tutorials](https://fhelium.550w.host/tutorial/)
- [Concepts](https://fhelium.550w.host/concepts/)
- [How-to guides](https://fhelium.550w.host/how-to/)
- [Architecture](https://fhelium.550w.host/concepts/architecture/system-overview)
- [API reference](https://fhelium.550w.host/api/)
- [Developer guide](https://fhelium.550w.host/developer/)

Start with [`examples/01_eager_basics.py`](./examples/01_eager_basics.py) or browse [`examples/README.md`](./examples/README.md) for Eager, Compile, value persistence, Runtime, Residency, Distributed, and Experimental examples.

## Development

Create the locked development environment and run the project checks:

```bash
git clone https://github.com/VisualDust/fhelium.git
cd fhelium
uv sync --locked
source .venv/bin/activate
just check
```

The [contributor guide](https://fhelium.550w.host/developer/contributing) documents custom Torch environments, native builds, editor configuration, and the validation workflow.

## Citation

If you use FHElium in research or software, cite the project as:

```bibtex
@software{fhelium2026,
  author  = {Zhaoting Gong and Jiaming Liang and Ran Ran and Wujie Wen},
  title   = {FHElium: A Cross-Stack CKKS Research Framework for CPU and CUDA},
  year    = {2026},
  version = {0.30.0},
  url     = {https://github.com/VisualDust/fhelium}
}
```

The same metadata is available in [`CITATION.cff`](./CITATION.cff).

## License

FHElium is licensed under the [MIT License](./LICENSE).
