Utilities¶

Exceptions¶

Custom exception hierarchy for PyFE4AI.

All scheme-level exceptions inherit from FEError, allowing consumers to catch broad (except FEError) or narrow (except FEValidationError).

exception pyfe4ai.utils.exceptions.FEError[source]¶

Bases: Exception

Base exception for all PyFE4AI errors.

exception pyfe4ai.utils.exceptions.FEConfigError[source]¶

Bases: FEError

Configuration or parameter file error (missing, invalid, corrupt).

exception pyfe4ai.utils.exceptions.FEKeyError[source]¶

Bases: FEError

Missing or invalid cryptographic keys / credentials.

exception pyfe4ai.utils.exceptions.FEValidationError[source]¶

Bases: FEError, ValueError

Input validation failure (bound exceeded, shape mismatch, etc.).

exception pyfe4ai.utils.exceptions.FESchemeError[source]¶

Bases: FEError, RuntimeError

Internal scheme logic error (unexpected state, unsupported operation).

Crypto Utilities¶

Core cryptographic primitives: safe random generation, group/prime generation, and hashing.

pyfe4ai.utils.crypto_utils.generate_group_primes(bits)[source]¶

Generates two safe prime numbers with the restriction:p=2q+1.

Parameters:: bits (int) – security parameters
Returns:: p, q
Return type:: tuple

pyfe4ai.utils.crypto_utils.group_generator_threshold_fe(bits, r=2)[source]¶

Generate a safe prime and generator for threshold FE.

Parameters:

bits (int) – Security parameter (bit length).
r (int, default: 2) – Cofactor (default 2).

pyfe4ai.utils.crypto_utils.group_generator_paillier(bits)[source]¶

Generates an integer group (p,q,n), where n = pq, and p, q are prime numbers.

Parameters:: bits (int) – the length of the prime number.
Returns:: p, q, n
Return type:: tuple

pyfe4ai.utils.crypto_utils.group_generator_fe(bits, r=2)[source]¶

Generate an RSA modulus and generator for FE schemes.

Parameters:

bits (int) – Security parameter (bit length).
r (int, default: 2) – Cofactor (default 2).

Return type:

tuple

pyfe4ai.utils.crypto_utils.md5_hash(v, p)[source]¶

Compute the MD5 hash of a string and return the result modulo p.

Parameters:

v (str) – Input string.
p (mpz) – Prime modulus.

Return type:

mpz

Crypto Constants¶

Scheme-type constants and default parameter values used across PyFE4AI.

class pyfe4ai.utils.crypto_constants.CryptoCONST[source]¶

Bases: object

TYPE_NONE = 'None'¶

TYPE_SIFE = 'SIFE'¶

TYPE_MIFE = 'MIFE'¶

TYPE_MCFE = 'MCFE'¶

TYPE_DMCFE = 'dMCFE'¶

TYPE_DMCFE_LWE = 'dMCFE_LWE'¶

TYPE_DMCFE_RING_LWE = 'dMCFE_RING_LWE'¶

TYPE_DMCFE_FH_MULTI_IPE = 'dMCFE_FH_MULTI_IPE'¶

TYPE_TMCFE = 'tMCFE'¶

TYPE_TMCFE_LWE = 'tMCFE_LWE'¶

TYPE_TMCFE_RING_LWE = 'tMCFE_RING_LWE'¶

TYPE_TMCFE_FH_MULTI_IPE = 'tMCFE_FH_MULTI_IPE'¶

TYPE_TMIFE = 'tMIFE'¶

TYPE_TMIFE_LWE = 'tMIFE_LWE'¶

TYPE_SIFE_PAILLIER = 'SIFE_PAILLIER'¶

TYPE_SIFE_DAMGARD = 'SIFE_DAMGARD'¶

TYPE_SIFE_LWE = 'SIFE_LWE'¶

TYPE_SIFE_FULLYSEC_LWE = 'SIFE_FULLYSEC_LWE'¶

TYPE_SIFE_RING_LWE = 'SIFE_RING_LWE'¶

TYPE_SIFE_FH_IPE = 'SIFE_FH_IPE'¶

TYPE_SIFE_PART_FH_IPE = 'SIFE_PART_FH_IPE'¶

TYPE_QUADRATIC_SGP = 'QUADRATIC_SGP'¶

TYPE_QUADRATIC_QUAD = 'QUADRATIC_QUAD'¶

TYPE_MIFE_PAILLIER = 'MIFE_PAILLIER'¶

TYPE_MIFE_DAMGARD = 'MIFE_DAMGARD'¶

TYPE_MIFE_LWE = 'MIFE_LWE'¶

TYPE_MIFE_FULLYSEC_LWE = 'MIFE_FULLYSEC_LWE'¶

TYPE_MIFE_FH_IPE = 'MIFE_FH_IPE'¶

TYPE_MIFE_FH_MULTI_IPE = 'MIFE_FH_MULTI_IPE'¶

TYPE_MIFE_RING_LWE = 'MIFE_RING_LWE'¶

TYPE_MCFE_PAILLIER = 'MCFE_PAILLIER'¶

TYPE_MCFE_DAMGARD = 'MCFE_DAMGARD'¶

TYPE_MCFE_LWE = 'MCFE_LWE'¶

TYPE_MCFE_FULLYSEC_LWE = 'MCFE_FULLYSEC_LWE'¶

TYPE_MCFE_RING_LWE = 'MCFE_RING_LWE'¶

TYPE_MCFE_FH_MULTI_IPE = 'MCFE_FH_MULTI_IPE'¶

DEC_STAGE_1 = 'partial_decryption'¶

DEC_STAGE_2 = 'final_decryption'¶

CT_STAGE_1 = 'ct_original'¶

CT_STAGE_2 = 'ct_prime'¶

SEC_PARAM = 128¶

SIFE_DEFAULT_ETA = 5¶

MIFE_ETA = 1¶

MCFE_ETA = 1¶

tMIFE_ETA = 1¶

tMIFE_T = 2¶

tMCFE_ETA = 1¶

tMCFE_N = 5¶

tMCFE_S = 3¶

tMCFE_T = 2¶

Sampling Utilities¶

Random sampling utilities: uniform vectors/matrices and discrete Gaussians.

pyfe4ai.utils.sampling_utils.random_below(maximum)[source]¶

Parameters:: maximum (mpz)
Return type:: mpz

pyfe4ai.utils.sampling_utils.rand_uniform_matrix(rows, cols, modulus)[source]¶

Generate a random matrix with entries uniform in [0, modulus).

Parameters:

rows (int) – Number of rows.
cols (int) – Number of columns.
modulus (mpz) – Modulus for the arithmetic operation.

Return type:

list[list[mpz]]

pyfe4ai.utils.sampling_utils.rand_uniform_vector(length, modulus)[source]¶

Generate a random vector with entries uniform in [0, modulus).

Parameters:

length (int) – Length of the vector.
modulus (mpz) – Modulus for the arithmetic operation.

Return type:

list[mpz]

pyfe4ai.utils.sampling_utils.rand_bit_vector(length)[source]¶

Parameters:: length (int)
Return type:: list[mpz]

pyfe4ai.utils.sampling_utils.discrete_gaussian_matrix(rows, cols, sigma)[source]¶

Sample a matrix from the (rounded) discrete Gaussian distribution.

Samples are drawn from a CSPRNG (random.SystemRandom, i.e. OS entropy) and rounded to the nearest integer, so this sampler is suitable for LWE noise and secret-key material. Note it is a rounded continuous Gaussian rather than a true discrete-Gaussian sampler, and it is not constant-time; this is adequate for a research prototype but not for production side-channel resistance.

Args:
rows: Number of rows. cols: Number of columns. sigma: Standard deviation for the Gaussian distribution.

Parameters:

rows (int)
cols (int)
sigma (float)

Return type:

list[list[mpz]]

Matrix Utilities¶

Integer matrix/vector arithmetic under a modulus.

pyfe4ai.utils.matrix_utils.matmul_mod(left, right, modulus)[source]¶

Multiply two matrices modulo a given modulus.

Parameters:

left (list[list[mpz]]) – Left operand matrix or vector.
right (list[list[mpz]]) – Right operand matrix or vector.
modulus (mpz) – Modulus for the arithmetic operation.

Return type:

list[list[mpz]]

pyfe4ai.utils.matrix_utils.transpose(matrix)[source]¶

Parameters:: matrix (list[list[mpz]])
Return type:: list[list[mpz]]

pyfe4ai.utils.matrix_utils.matvec_mod(matrix, vector, modulus)[source]¶

Multiply a matrix by a vector modulo a given modulus.

Parameters:

matrix (list[list[mpz]]) – Input matrix.
vector (list[mpz]) – Input vector.
modulus (mpz) – Modulus for the arithmetic operation.

Return type:

list[mpz]

pyfe4ai.utils.matrix_utils.vecdot_mod(left, right, modulus)[source]¶

Compute the dot product of two vectors modulo a given modulus.

Parameters:

left (list[mpz]) – Left operand matrix or vector.
right (list[mpz]) – Right operand matrix or vector.
modulus (mpz) – Modulus for the arithmetic operation.

Return type:

mpz

pyfe4ai.utils.matrix_utils.matrix_to_digits(matrix)[source]¶

Parameters:: matrix (list[list[mpz]])
Return type:: list[list[str]]

pyfe4ai.utils.matrix_utils.digits_to_matrix(matrix)[source]¶

Parameters:: matrix (list[list[str]])
Return type:: list[list[mpz]]

pyfe4ai.utils.matrix_utils.vector_to_digits(vector)[source]¶

Parameters:: vector (list[mpz])
Return type:: list[str]

pyfe4ai.utils.matrix_utils.digits_to_vector(vector)[source]¶

Parameters:: vector (list[str])
Return type:: list[mpz]

Modular Arithmetic¶

Modular arithmetic helpers for signed-exponent modular exponentiation.

pyfe4ai.utils.modular_utils.pow_signed(base, exponent, modulus)[source]¶

Compute modular exponentiation with signed exponent support.

Parameters:

base (mpz) – Base for modular exponentiation.
exponent (mpz) – Exponent value.
modulus (mpz) – Modulus for the arithmetic operation.

Return type:

mpz

LWE Utilities¶

LWE parameter derivation, vector centering, and inner-product decoding.

pyfe4ai.utils.lwe_utils.derive_lwe_parameters(max_plain_bound, bound_y, eta, lwe_n, extra_dimension=None)[source]¶

Derive LWE scheme parameters from plaintext and weight bounds.

Parameters:

max_plain_bound (mpz) – Maximum plaintext bound.
bound_y (mpz) – Bound on weight values.
eta (int) – Inner-product vector dimension.
lwe_n (int) – LWE lattice dimension.
extra_dimension (int | None, default: None) – Extra dimension flag.

Return type:

tuple[mpz, mpz, int, float, mpz]

pyfe4ai.utils.lwe_utils.derive_fullysec_lwe_parameters(bound_x, bound_y, eta, lwe_n)[source]¶

Derive fully-secure LWE parameters with multiple noise levels.

Parameters:

bound_x (mpz) – Bound on plaintext values.
bound_y (mpz) – Bound on weight values.
eta (int) – Inner-product vector dimension.
lwe_n (int) – LWE lattice dimension.

Return type:

tuple[mpz, mpz, int, float, mpz, float, mpz, float, mpz]

pyfe4ai.utils.lwe_utils.center_lwe_vector(vector, p, q)[source]¶

Scale and center a vector for LWE message extraction.

Parameters:

vector (list[int] | list[mpz]) – Input vector.
p (mpz) – Prime modulus.
q (mpz) – Modulus (or second prime).

Return type:

list[mpz]

pyfe4ai.utils.lwe_utils.decode_lwe_inner_product(value, p, q)[source]¶

Extract a plaintext value from an LWE inner-product ciphertext.

Parameters:

value (mpz) – Input value.
p (mpz) – Prime modulus.
q (mpz) – Modulus (or second prime).

Return type:

int

pyfe4ai.utils.lwe_utils.label_scalar_from_hash(hash_value, label_modulus)[source]¶

Convert a hash value to a centered label scalar.

Parameters:

hash_value (mpz) – Hash digest value.
label_modulus (int) – Modulus for centering the label scalar.

Return type:

mpz

pyfe4ai.utils.lwe_utils.decode_fullysec_lwe_inner_product(value, k, q)[source]¶

Extract a plaintext from a fully-secure LWE ciphertext.

Parameters:

value (mpz) – Input value.
k (mpz) – Inner-product bound.
q (mpz) – Modulus (or second prime).

Return type:

int

Ring-LWE Utilities¶

Ring-LWE helper functions shared across SIFE / MIFE / MCFE Ring-LWE schemes.

These were originally private helpers in sife/ring_lwe.py. They are extracted here so that cross-package imports reference utils rather than reaching into another scheme family’s private namespace.

Changed in version 0.2: Added NTT-based polynomial multiplication (O(n log n)) alongside the original naive O(n²) implementation.

Changed in version 0.3: Added next_ntt_prime for NTT-friendly parameter generation, poly_mul auto-dispatch with cached root of unity.

pyfe4ai.utils.ring_lwe_utils.ntt_forward(a, q, root)[source]¶

In-place iterative Cooley-Tukey NTT (decimation-in-time).

Parameters:

a (list[mpz]) – First polynomial (coefficient vector).
q (mpz) – Modulus (or second prime).
root (mpz) – Primitive root of unity for NTT.

Return type:

list[mpz]

pyfe4ai.utils.ring_lwe_utils.ntt_inverse(a, q, root)[source]¶

Inverse NTT: transform back to coefficient domain.

Parameters:

a (list[mpz]) – First polynomial (coefficient vector).
q (mpz) – Modulus (or second prime).
root (mpz) – Primitive root of unity for NTT.

Return type:

list[mpz]

pyfe4ai.utils.ring_lwe_utils.poly_mul_ntt(a, b, q, root)[source]¶

Polynomial multiplication in Z_q[X]/(X^n+1) via NTT.

Parameters:

a (list[mpz]) – First polynomial (coefficient vector).
b (list[mpz]) – Second polynomial (coefficient vector).
q (mpz) – Modulus (or second prime).
root (mpz) – Primitive root of unity for NTT.

Return type:

list[mpz]

pyfe4ai.utils.ring_lwe_utils.poly_mul(a, b, q)[source]¶

Polynomial multiplication with automatic NTT acceleration.

Parameters:

a (list[mpz]) – First polynomial (coefficient vector).
b (list[mpz]) – Second polynomial (coefficient vector).
q (mpz) – Modulus (or second prime).

Return type:

list[mpz]

pyfe4ai.utils.ring_lwe_utils.next_ntt_prime(lower_bound, ring_n)[source]¶

Find the smallest prime q >= lower_bound with q ≡ 1 (mod 2·ring_n).

Parameters:

lower_bound (mpz) – Lower bound for the search.
ring_n (int) – Polynomial ring dimension.

Return type:

mpz

pyfe4ai.utils.ring_lwe_utils.poly_add(a, b, q)[source]¶

Add two polynomials element-wise modulo q.

Parameters:

a (list[mpz]) – First polynomial (coefficient vector).
b (list[mpz]) – Second polynomial (coefficient vector).
q (mpz) – Modulus (or second prime).

Return type:

list[mpz]

pyfe4ai.utils.ring_lwe_utils.poly_neg(a, q)[source]¶

Negate a polynomial modulo q.

Parameters:

a (list[mpz]) – First polynomial (coefficient vector).
q (mpz) – Modulus (or second prime).

Return type:

list[mpz]

pyfe4ai.utils.ring_lwe_utils.poly_mul_negacyclic(a, b, q)[source]¶

Multiply two polynomials in the negacyclic ring Z_q[X]/(X^n+1).

Parameters:

a (list[mpz]) – First polynomial (coefficient vector).
b (list[mpz]) – Second polynomial (coefficient vector).
q (mpz) – Modulus (or second prime).

Return type:

list[mpz]

pyfe4ai.utils.ring_lwe_utils.matrix_check_bound(matrix, bound)[source]¶

Check whether all matrix entries have absolute value within the bound.

Parameters:

matrix (list[list[int]]) – Input matrix.
bound (mpz) – Upper bound on absolute values.

Return type:

bool

pyfe4ai.utils.ring_lwe_utils.transpose(matrix)[source]¶

Parameters:: matrix (list[list[int | mpz]])
Return type:: list[list[mpz]]

pyfe4ai.utils.ring_lwe_utils.mat_vec_mul(matrix, vec, q)[source]¶

Multiply a matrix by a polynomial vector modulo q.

Parameters:

matrix (list[list[mpz]]) – Input matrix.
vec (list[mpz]) – Input vector.
q (mpz) – Modulus (or second prime).

Return type:

list[mpz]

pyfe4ai.utils.ring_lwe_utils.center_matrix(matrix, p, q, ring_n)[source]¶

Scale and round matrix entries for LWE decoding.

Parameters:

matrix (list[list[int]]) – Input matrix.
p (mpz) – Prime modulus.
q (mpz) – Modulus (or second prime).
ring_n (int) – Polynomial ring dimension.

Return type:

list[list[mpz]]

pyfe4ai.utils.ring_lwe_utils.decode_vector(poly, p, q, k)[source]¶

Extract the first k plaintext coefficients by rounding.

Parameters:

poly (list[mpz]) – Input polynomial coefficient vector.
p (mpz) – Prime modulus.
q (mpz) – Modulus (or second prime).
k (int) – Inner-product bound.

Return type:

list[int]

Discrete-Log Solver¶

Discrete logarithm solvers with JSON-backed caching for integer and pairing groups.

Provides two strategies:

Dlog table (default): precompute a lookup table of size O(√n) and persist it to a JSON cache file. Subsequent solves are O(√n) lookups against the cached table. Best when the same group parameters are reused across many decrypt calls.
Baby-step giant-step (BSGS) (optional): compute baby-step and giant-step values on the fly without any disk cache. O(√n) time and space per invocation. Useful for one-off solves or when disk caching is undesirable.

pyfe4ai.utils.dlog_solver.dlog_build_table(g_str, p_str, bound)[source]¶

Build a dlog lookup table for discrete log in [-bound, bound].

Parameters:

g_str (str) – Group generator as a digit string.
p_str (str) – Prime modulus as a digit string.
bound (int) – Upper bound on absolute values.

Return type:

tuple[dict, int, mpz]

pyfe4ai.utils.dlog_solver.dlog_table_solve(value, g_str, p_str, bound, table, m, giant)[source]¶

Solve g^x ≡ value (mod p) with x ∈ [-bound, bound].

Parameters:

value – Input value.
g_str (str) – Group generator as a digit string.
p_str (str) – Prime modulus as a digit string.
bound (int) – Upper bound on absolute values.
table (dict) – See implementation for details.
m (int) – See implementation for details.
giant (mpz) – See implementation for details.

Return type:

int

pyfe4ai.utils.dlog_solver.load_or_build_dlog_table(filepath, g_str, p_str, bound)[source]¶

Load a cached dlog table, or generate + save one if stale/missing.

Parameters:

filepath (str) – Path to the cache file.
g_str (str) – Group generator as a digit string.
p_str (str) – Prime modulus as a digit string.
bound (int) – Upper bound on absolute values.

Return type:

tuple[dict, int, int, mpz]

pyfe4ai.utils.dlog_solver.bsgs_solve_int(value, g_str, p_str, bound)[source]¶

Solve g^x ≡ value (mod p) with x ∈ [-bound, bound] via BSGS.

Uses the standard two-pass approach (matching GoFE / CiFEr reference implementations): search [0, bound] with g, then search [0, bound] with g⁻¹ to cover negative solutions.

Unlike the dlog-table approach, this computes baby-step and giant-step values entirely on the fly without reading or writing any disk cache. Suitable for one-off discrete-log recovery or when caching is undesirable.

Complexity: O(√bound) time and space.

Parameters:

value – Target group element g^x mod p.
g_str (str) – Generator as a gmpy2.digits() string.
p_str (str) – Modulus as a gmpy2.digits() string.
bound (int) – Search range [-bound, bound].

Return type:

int

Returns:

The discrete logarithm x.

Raises:

ValueError – If no solution is found within the bound.

pyfe4ai.utils.dlog_solver.bsgs_solve_pairing(target, g, h, pairing_group_param, bound)[source]¶

Solve e(g, h)^x = target in a pairing group via on-the-fly BSGS.

Uses the standard approach (matching CiFEr’s cfe_baby_giant_FP12): build one baby-step table for e(g,h) and simultaneously check both target and target⁻¹ in each giant step, covering [-bound, bound] in a single loop.

Computes baby-step and giant-step values entirely in memory without persisting any lookup table.

Parameters:

target – The target element in GT (output of a pairing).
g – Generator in G1.
h – Generator in G2.
pairing_group_param (str) – PBC pairing parameter name (e.g. "MNT224").
bound (int) – Search range [-bound, bound].

Return type:

int

Returns:

The discrete logarithm x.

Raises:

ValueError – If no solution is found within the bound.

class pyfe4ai.utils.dlog_solver.PairingDLogCacheMixin[source]¶

Bases: object

Bounded discrete-log recovery helper for pairing-based IPFE-style schemes.

Uses a cached dlog lookup table by default. An on-the-fly BSGS fallback is available via _solve_dlog_bsgs().

This mixin is intentionally separate from higher-level policy composition: policy composition and numeric recovery are different concerns.

scheme_type: str¶

config_folder: str¶

precision: int¶

pp: dict¶

ML Adapter¶

ML framework adapter layer for PyFE4AI.

Provides two high-level APIs that hide FE complexity from ML engineers:

FL aggregation (eta=1, ndarray helpers):

Encrypt per-element gradients from n clients, aggregate with weights.

>>> wrapper = FESchemeWrapper("mcfe", "lwe", keygen_cfg, crypto_cfg)
>>> enc = encrypt_gradient(grad_array, wrapper, label="round-1")
>>> result = aggregate_gradients(
...     {"c0": enc0, "c1": enc1}, wrapper, weights, label="round-1")

Encrypted inference (eta=feature_dim, vector mode):

Encrypt a feature vector, compute ⟨x, w⟩ without revealing x.

>>> wrapper = FESchemeWrapper("sife", "lwe", keygen_cfg, crypto_cfg)
>>> enc = encrypt_features(feature_vec, wrapper)
>>> score = compute_linear(enc, wrapper, model_weights)

PyTorch is optional — functions accept both numpy.ndarray and torch.Tensor inputs.

pyfe4ai.utils.ml_adapter.tensor_to_ndarray(t)[source]¶

Convert a PyTorch tensor to a numpy array (detach + cpu + numpy).

Parameters:: t (Any)
Return type:: ndarray

pyfe4ai.utils.ml_adapter.ndarray_to_tensor(arr)[source]¶

Convert a numpy array to a PyTorch tensor.

Parameters:: arr (ndarray)
Return type:: Any

class pyfe4ai.utils.ml_adapter.FESchemeWrapper(scheme_type, variant, keygen_config, *, precision=0, qmode='decimal')[source]¶

Bases: object

Unified wrapper around any PyFE4AI scheme.

Manages the KeyGenerator lifecycle (setup + key distribution) and provides a consistent encrypt / decrypt surface regardless of the underlying scheme family.

Parameters¶

scheme_typestr: "sife", "mcfe", "mife", or "quadratic".
variantstr: "ddh", "lwe", "paillier", "damgard", "ring_lwe", "quad", or "sgp".
keygen_configdict: Configuration dict for the KeyGenerator (sec_param, eta, n, bound_x, etc.).
precisionint: Quantization precision (default 0 — no quantization).
qmodestr: Quantization mode: "decimal" or "binary" (default "decimal").

param scheme_type:
type scheme_type:: str
param variant:
type variant:: str
param keygen_config:
type keygen_config:: dict
param precision:
type precision:: int, default: 0
param qmode:
type qmode:: str, default: 'decimal'

__init__(scheme_type, variant, keygen_config, *, precision=0, qmode='decimal')[source]¶

Perform the __init__ operation.

Parameters:

scheme_type (str) – See implementation for details.
variant (str) – See implementation for details.
keygen_config (dict) – See implementation for details.
precision (int, default: 0) – See implementation for details.
qmode (str, default: 'decimal') – See implementation for details.

Return type:

None

get_decryption_keys(sid, **credentials)[source]¶

Derive functional decryption keys.

Parameters:: sid (str) – Session / decryption-key identifier.
Return type:: dict

Parameters:

scheme_type (str)
variant (str)
keygen_config (dict)
precision (int)
qmode (str)

class pyfe4ai.utils.ml_adapter.EncryptedGradient(ciphertexts, shape, precision, mode, nid)[source]¶

Bases: object

Encrypted gradient array for FL aggregation.

Produced by encrypt_gradient().

Parameters:

ciphertexts (list)
shape (tuple)
precision (int)
mode (str)
nid (str)

ciphertexts: list¶

shape: tuple¶

precision: int¶

mode: str¶

nid: str¶

to_dict()[source]¶

Serialise for network transfer (e.g. federated learning).

Return type:: dict

classmethod from_dict(d)[source]¶

Deserialise from dict.

Parameters:: d (dict)
Return type:: EncryptedGradient

class pyfe4ai.utils.ml_adapter.EncryptedFeatures(ciphertext, dim, precision, mode)[source]¶

Bases: object

Encrypted feature vector for inference.

Produced by encrypt_features().

Parameters:

ciphertext (dict)
dim (int)
precision (int)
mode (str)

ciphertext: dict¶

dim: int¶

precision: int¶

mode: str¶

to_dict()[source]¶

Return type:: dict

classmethod from_dict(d)[source]¶

Parameters:: d (dict)
Return type:: EncryptedFeatures

pyfe4ai.utils.ml_adapter.encrypt_gradient(gradient, wrapper, *, nid='nid_default', label=None)[source]¶

Encrypt a gradient array for federated aggregation.

Parameters:

gradient (ndarray | Any) – See implementation for details.
wrapper (FESchemeWrapper) – FE scheme wrapper instance.
nid (str, default: 'nid_default') – Node identifier.
label (str | None, default: None) – Encryption label for replay protection.

Return type:

EncryptedGradient

pyfe4ai.utils.ml_adapter.aggregate_gradients(encrypted, wrapper, weights, *, sid='sid_agg', label=None)[source]¶

Decrypt and aggregate encrypted gradients from multiple clients.

Parameters:

encrypted (dict[str, EncryptedGradient]) – Encrypted data container.
wrapper (FESchemeWrapper) – FE scheme wrapper instance.
weights (dict[str, float | int | list]) – Weight vector or dict.
sid (str, default: 'sid_agg') – Session / decryption-key identifier.
label (str | None, default: None) – Encryption label for replay protection.

Return type:

ndarray

pyfe4ai.utils.ml_adapter.encrypt_features(features, wrapper, *, nid='nid_default')[source]¶

Encrypt a feature vector for privacy-preserving inference.

Parameters:

features (ndarray | Any) – See implementation for details.
wrapper (FESchemeWrapper) – FE scheme wrapper instance.
nid (str, default: 'nid_default') – Node identifier.

Return type:

EncryptedFeatures

pyfe4ai.utils.ml_adapter.compute_linear(encrypted, wrapper, weights, *, sid='sid_infer')[source]¶

Compute ⟨features, weights⟩ on encrypted features.

Parameters:

encrypted (EncryptedFeatures) – Encrypted data container.
wrapper (FESchemeWrapper) – FE scheme wrapper instance.
weights (ndarray | Any) – Weight vector or dict.
sid (str, default: 'sid_infer') – Session / decryption-key identifier.

Return type:

float

Quantization¶

Precision management toolkit for functional encryption on real-valued data.

FE schemes operate on integers, but AI/ML workloads use floats. This module provides three tools to bridge the gap:

QuantizationConfig — float↔int conversion with configurable scaling (decimal or binary mode).
estimate_bounds() — auto-compute bound_x, bound_y and discrete-log table requirements from sample data.
analyze_precision_loss() — report quantization error metrics.

class pyfe4ai.utils.quantization.QuantizationConfig(precision=3, mode='decimal')[source]¶

Bases: object

Immutable quantization strategy for float↔int conversion.

Parameters¶

precisionint: Number of fractional digits (decimal) or bits (binary) to preserve.
modestr: "decimal" scales by 10**precision (compatible with existing PyFE4AI ndarray helpers). "binary" scales by 2**precision (avoids base-10 rounding artefacts, better for ML weights).

param precision:
type precision:: int, default: 3
param mode:
type mode:: str, default: 'decimal'

precision: int = 3¶

mode: str = 'decimal'¶

property scale_factor: int¶: Multiplicative factor used to shift floats into integer domain.

quantize(value)[source]¶

Convert a single float to an integer via rounding.

Parameters:: value (float)
Return type:: int

dequantize(value, order=1)[source]¶

Convert an integer back to float.

Parameters:

value (int) – Input value.
order (int, default: 1) – Group order (or exponent order for dequantization).

Return type:

float

quantize_array(arr)[source]¶

Quantize an entire array in one vectorised operation.

Uses np.round (banker’s rounding) instead of truncation to minimise systematic bias. Returns int64 array.

Parameters:: arr (ndarray)
Return type:: ndarray

dequantize_array(arr, order=1)[source]¶

De-quantize an integer array back to float64.

Parameters:

arr (ndarray) – Input array.
order (int, default: 1) – Group order (or exponent order for dequantization).

Return type:

ndarray

Parameters:

precision (int)
mode (str)

pyfe4ai.utils.quantization.estimate_bounds(x_data, y_weights, precision, eta=None, mode='decimal')[source]¶

Auto-compute safe FE bounds from sample data.

Parameters:

x_data (ndarray) – See implementation for details.
y_weights (ndarray) – See implementation for details.
precision (int) – Quantization precision.
eta (int | None, default: None) – Inner-product vector dimension.
mode (str, default: 'decimal') – See implementation for details.

Return type:

dict

pyfe4ai.utils.quantization.validate_bounds(bound_x, bound_y, eta, precision)[source]¶

Check whether configured bounds are safe for FE operations.

Parameters:

bound_x (int) – Bound on plaintext values.
bound_y (int) – Bound on weight values.
eta (int) – Inner-product vector dimension.
precision (int) – Quantization precision.

Return type:

list[str]

pyfe4ai.utils.quantization.analyze_precision_loss(original, precision, mode='decimal')[source]¶

Report quantization error metrics for the given data and precision.

Parameters:

original (ndarray) – See implementation for details.
precision (int) – Quantization precision.
mode (str, default: 'decimal') – See implementation for details.

Return type:

dict

Pairing Backend¶

Helpers for optional pairing-based dependencies.

pyfe4ai.utils.pairing_backend.require_pairing_backend()[source]¶

Raise a clear error if the optional pairing backend is unavailable.

Return type:: None

Pairing Utilities¶

Pairing-based helper functions shared across FH-IPE / FH-Multi-IPE / Quadratic schemes.

These were originally private helpers in sife/fh_ipe_pairing.py and mife/fh_multi_ipe_pairing.py. They are extracted here so that cross-package imports reference utils rather than reaching into another scheme family’s private namespace.

pyfe4ai.utils.pairing_utils.transpose_mod(matrix)[source]¶

Parameters:: matrix (list[list[mpz]])
Return type:: list[list[mpz]]

pyfe4ai.utils.pairing_utils.mat_vec_mod(matrix, vector, modulus)[source]¶

Multiply a matrix by a vector modulo a given modulus.

Parameters:

matrix (list[list[mpz]]) – Input matrix.
vector (list[mpz]) – Input vector.
modulus (mpz) – Modulus for the arithmetic operation.

Return type:

list[mpz]

pyfe4ai.utils.pairing_utils.vector_add_mod(lhs, rhs, modulus)[source]¶

Add two vectors element-wise modulo a given modulus.

Parameters:

lhs (list[mpz]) – Left-hand side vector.
rhs (list[mpz]) – Right-hand side vector.
modulus (mpz) – Modulus for the arithmetic operation.

Return type:

list[mpz]

pyfe4ai.utils.pairing_utils.vector_scalar_mod(vector, scalar, modulus)[source]¶

Multiply a vector by a scalar modulo a given modulus.

Parameters:

vector (list[mpz]) – Input vector.
scalar (mpz) – Scalar multiplier.
modulus (mpz) – Modulus for the arithmetic operation.

Return type:

list[mpz]

pyfe4ai.utils.pairing_utils.random_nonzero_zr(group)[source]¶

Parameters:: group (None)

pyfe4ai.utils.pairing_utils.to_zr(group, value)[source]¶

Convert an integer to a ZR element in the pairing group.

Parameters:

group (None) – Pairing group instance.
value (mpz | int) – Input value.

pyfe4ai.utils.pairing_utils.matrix_inverse_mod(matrix, modulus)[source]¶

Compute the modular inverse of a matrix via Gaussian elimination.

Parameters:

matrix (list[list[mpz]]) – Input matrix.
modulus (mpz) – Modulus for the arithmetic operation.

Return type:

tuple[list[list[mpz]], mpz]

pyfe4ai.utils.pairing_utils.bounded_discrete_log_gt(group, base, target, bound)[source]¶

Solve a bounded discrete logarithm in GT via baby-step giant-step.

Parameters:

group (None) – Pairing group instance.
base – Base for modular exponentiation.
target – Target group element.
bound (int) – Upper bound on absolute values.

Return type:

int

pyfe4ai.utils.pairing_utils.serialize_matrix_g(group, matrix)[source]¶

Serialize a matrix of group elements to strings.

Parameters:

group (None) – Pairing group instance.
matrix – Input matrix.

Return type:

list[list[str]]

pyfe4ai.utils.pairing_utils.deserialize_matrix_g(group, matrix)[source]¶

Deserialize a matrix of strings back to group elements.

Parameters:

group (None) – Pairing group instance.
matrix (list[list[str]]) – Input matrix.