Choose parameters for a workload.
Connect input range, numerical error, computation budget, backend capacity, and security assumptions.
For application developers · Source guide · 2394fa5
Start with the workload
Write down the input range, the calculation, the required absolute or relative error, the number of packed values, and whether repeated evaluation needs bootstrapping. These determine the arithmetic requirements. A security estimate then constrains the allowable modulus and secret distribution for the selected ring degree.
Bit-granular modulus management removes the need to construct a circuit-specific RNS prime chain. It does not choose a secure parameter set automatically.
| Quantity | Poulpy name | What it controls |
|---|---|---|
| Ring degree N | n | Polynomial dimension; together with the distribution and modulus, part of the security estimate |
| Signed digit width K | base2k | Bits per limb, constrained by the backend’s arithmetic capacity |
| Ciphertext modulus width | k | Total Torus precision; limb count is derived as ceil(k / base2k) |
| Encoding scale | log_delta | Scale applied during CKKS encoding; distinct from measured output accuracy |
| Arithmetic headroom | log_budget | Derived as k - log_delta |
| GLWE rank | rank | Number of mask polynomials; rank one is the usual RLWE shape |
| Gadget granularity | dsize, dnum | Limbs per decomposition digit and number of digits; affects key size, noise, and work |
| Secret and error distributions | Sampling configuration | Required inputs to the security and correctness analysis |
The signed-limb diagrams explain storage and carry propagation. Their small dimensions illustrate the representation; they are not recommended cryptographic parameters.
A worked learning configuration
The standalone example evaluates z = (a + b) × b on 512 complex slots using NTT4x30Ref. It uses N = 1024, K = 52, ciphertext width 156 bits, scale 2^45, and a ternary secret of weight 192.
| Decision | Reason in this example | What an application must check |
|---|---|---|
| a in [−0.5, 0.5), b in [0.25, 0.75) | Small bounded values make error easy to inspect; the result magnitude is below 1 | Bound all intermediate magnitudes for actual inputs |
| One ciphertext multiplication | Exercises relinearization and budget consumption | Count the longest dependent multiplication path, not just the operation total |
| Initial budget = 156 − 45 = 111 bits | Leaves headroom for this small computation | Include alignment, rescaling, evaluation keys, and the desired final scale |
Output error below 1e-9 | The program checks every real slot and the imaginary residual | Choose an application-specific tolerance and test relevant inputs |
| No bootstrap | One small circuit fits the allocated capacity | Plan refreshes if the required dependent depth exceeds the available budget |
This is a correctness demonstration, not a security-rated profile. Its small ring and fixed seeds must not be adopted as application security parameters.
From the example to an application
- Fix the input domain and error tolerance. Check approximation error separately from homomorphic arithmetic error when evaluating functions.
- Choose the computation and packing. Record required rotation, multiplication, and bootstrap keys.
- Select an arithmetic family and its supported limb width using Backends. Size wide accumulators for products and sums.
- Derive ciphertext and evaluation-key widths from the operation plans. Include auxiliary moduli and any encapsulation keys, not only the final ciphertext modulus.
- Estimate security for those widths, the actual rank and dimension, and every relevant secret distribution. Save the estimator revision, attack assumptions, and result.
- Measure correctness, memory use, and performance at that configuration. A small observed error or successful decryption does not prove the chosen security level.
Existing bootstrapping presets
The source-guide baseline includes log_n16::c2s_16_levels and log_n16::s2c_16_levels, described in Bootstrapping → Default presets. They package a circuit and its key/ciphertext layouts.
Use the pinned source to inspect preset bounds and distributions. Constructor validation checks the configured layout and modulus limits; it does not replace a security analysis matching your deployment. PaCo and SHIP need their own distribution-specific analysis.
Record the decision
Keep a parameter record alongside the application: source revision, backend, all widths and distributions, estimator assumptions, input bounds, expected output error, observed error, key bytes, scratch bytes, and timings. The measurement guide provides a reproducible reporting checklist.