LLM-NTT Examples

This repository packages extracted Number Theoretic Transform RTL variants from YATA and HOGE with small Verilator tests that compare against the current TFHEpp C++ reference headers.

Contents

• variants/yata-raintt: YATA compressed 27-bit RAINTT NTT and INTT.
• variants/hoge-streaming: HOGE streaming 64-bit INTT plus an NTT wrapper.
• variants/hoge-externalproduct: HOGE ExternalProduct pipeline used as the executable forward NTT oracle.
• variants/hoge-nttid: HOGE full-vector NTT/INTT identity pipeline.
• third_party/TFHEpp: TFHEpp submodule used as the C++ reference.
• docs/ntt-module-specs.md: top-level module specifications for generating replacement Verilog that passes the included tests.
• tasks/: machine-readable benchmark task manifests for architecture search.
• docs/architecture-search-space.md and docs/scoring.md: search knobs and evaluation rules.
• examples/autontt/: AutoNTT-oriented mapping notes and custom reduction examples.

The copied YATA and HOGE RTL is AGPL-3.0 licensed. See NOTICE.md and licenses/.

Native Run

Install sbt, cmake, ninja, clang++, and verilator, then run:

git submodule update --init --recursive
scripts/run_all.sh

The script generates Verilog with sbt run, configures CMake with Clang, builds the Verilator harnesses, and runs CTest.

Apptainer Run

Build the container:

apptainer build --mksquashfs-args "-processors 1" llm-ntt.sif apptainer/llm-ntt.def

Run the same build and test flow inside the container:

apptainer run --no-home --pwd /work --bind "$(pwd):/work" llm-ntt.sif

The %runscript expects the repository to be mounted at /work. The single-threaded squashfs argument avoids mksquashfs orderer failures observed on some unprivileged Apptainer hosts.

Manual Steps

Generate Verilog only:

scripts/gen_verilog.sh

Build and test after Verilog generation:

cmake -S . -B build -G Ninja -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang
cmake --build build
ctest --test-dir build --output-on-failure

Evaluate a single benchmark task, using the extracted RTL as the baseline:

scripts/evaluate_candidate.sh --task hoge_streaming_intt_1024_p64

Evaluate candidate Verilog in a directory:

scripts/evaluate_candidate.sh \
  --task hoge_streaming_intt_1024_p64 \
  --verilog-dir candidate/hoge-intt

Add an optional flattened Yosys structural estimate:

scripts/evaluate_candidate.sh \
  --task hoge_externalproduct_ntt_1024_p64 \
  --with-yosys

Test Targets

• yata_raintt_reference_test: compares streamed YATA INTT and NTT against raintt::TwistINTT/raintt::TwistNTT with USE_COMPRESS. INTT input lane l at cycle c carries coefficient l * 8 + c; NTT output lane l at cycle c corresponds to coefficient l * 8 + c.
• hoge_streaming_reference_test: drives HOGE INTTWrap and compares against cuHEpp::TwistINTT.
• hoge_externalproduct_ntt_reference_test: drives HOGE ExternalProductWrap and compares the final 32-bit torus output against TFHEpp ExternalProduct<lvl1param>, whose final boundary is TwistNTT.
• hoge_nttid_identity_test: drives HOGE NTTid and checks that the combined INTT/NTT pipeline returns the original polynomial modulo P.

The HOGE forward NTTWrap manifest, hoge_streaming_ntt_1024_p64, is a lint-only tier0 interface task. Use hoge_externalproduct_ntt_1024_p64 for HOGE forward NTT arithmetic and latency comparisons.