Combinatorics

concrete_fhe_toolkit.math.combinatorics

Bounded combinatorial functions evaluated through encrypted indices.

make_factorial

make_factorial(max_n: int) -> UnaryFunction

Create n! for an encrypted n in [0, max_n].

Parameters:

Name	Type	Description	Default
max_n	int	The maximum value for the encrypted integer n.	required

Returns:

Name	Type	Description
UnaryFunction	UnaryFunction	A unary function that computes the factorial.

Example

from concrete_fhe_toolkit.math.combinatorics import make_factorial

factorial_fn = make_factorial(max_n=5)
# Use `factorial_fn(n)` inside an FHE program compilation

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def make_factorial(max_n: int) -> UnaryFunction:
    """Create n! for an encrypted n in [0, max_n].

    Args:
        max_n (int): The maximum value for the encrypted integer n.

    Returns:
        UnaryFunction: A unary function that computes the factorial.

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import make_factorial

        factorial_fn = make_factorial(max_n=5)
        # Use `factorial_fn(n)` inside an FHE program compilation
        ```
    """
    values = _factorials(max_n)
    return make_unary_lookup(values, 0)

compile_factorial

compile_factorial(max_n: int, *, allow_large_lookup: bool = False, configuration: Optional[Configuration] = None) -> fhe.Circuit

Compile n! for an encrypted n in [0, max_n].

Parameters:

Name	Type	Description	Default
max_n	int	The maximum value for the encrypted integer n.	required
allow_large_lookup	bool	Whether to allow large table lookups (may be slow).	False
configuration	Optional[Configuration]	Optional FHE compiler configuration object.	None

Returns:

Type	Description
Circuit	fhe.Circuit: The compiled FHE circuit for factorial computation.

Example

from concrete_fhe_toolkit.math.combinatorics import compile_factorial

circuit = compile_factorial(max_n=5)
print(circuit.encrypt_run_decrypt(4))  # 24

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def compile_factorial(
    max_n: int,
    *,
    allow_large_lookup: bool = False,
    configuration: Optional[fhe.Configuration] = None,
) -> fhe.Circuit:
    """Compile n! for an encrypted n in [0, max_n].

    Args:
        max_n (int): The maximum value for the encrypted integer n.
        allow_large_lookup (bool): Whether to allow large table lookups (may be slow).
        configuration (Optional[fhe.Configuration]): Optional FHE compiler configuration object.

    Returns:
        fhe.Circuit: The compiled FHE circuit for factorial computation.

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import compile_factorial

        circuit = compile_factorial(max_n=5)
        print(circuit.encrypt_run_decrypt(4))  # 24
        ```
    """
    check_lookup_domain('compile_factorial', (0, max_n), allow_large_lookup=allow_large_lookup)
    maximum = _validate_maximum("max_n", max_n)
    values = _factorials(maximum)
    return compile_unary_lookup(
        "compile_factorial",
        values,
        0,
        maximum,
        allow_large_lookup=allow_large_lookup,
        configuration=configuration,
    )

make_fibonacci

make_fibonacci(max_n: int) -> UnaryFunction

Create the nth Fibonacci number for encrypted n in [0, max_n].

Parameters:

Name	Type	Description	Default
max_n	int	The maximum value for the encrypted integer n.	required

Returns:

Name	Type	Description
UnaryFunction	UnaryFunction	A unary function that computes the nth Fibonacci number.

Example

from concrete_fhe_toolkit.math.combinatorics import make_fibonacci

fib_fn = make_fibonacci(max_n=10)
# Use `fib_fn(n)` inside an FHE program compilation

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def make_fibonacci(max_n: int) -> UnaryFunction:
    """Create the nth Fibonacci number for encrypted n in [0, max_n].

    Args:
        max_n (int): The maximum value for the encrypted integer n.

    Returns:
        UnaryFunction: A unary function that computes the nth Fibonacci number.

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import make_fibonacci

        fib_fn = make_fibonacci(max_n=10)
        # Use `fib_fn(n)` inside an FHE program compilation
        ```
    """
    values = _fibonacci_values(max_n)
    return make_unary_lookup(values, 0)

compile_fibonacci

compile_fibonacci(max_n: int, *, allow_large_lookup: bool = False, configuration: Optional[Configuration] = None) -> fhe.Circuit

Compile the nth Fibonacci number for encrypted n in [0, max_n].

Parameters:

Name	Type	Description	Default
max_n	int	The maximum value for the encrypted integer n.	required
allow_large_lookup	bool	Whether to allow large table lookups (may be slow).	False
configuration	Optional[Configuration]	Optional FHE compiler configuration object.	None

Returns:

Type	Description
Circuit	fhe.Circuit: The compiled FHE circuit for Fibonacci computation.

Example

from concrete_fhe_toolkit.math.combinatorics import compile_fibonacci

circuit = compile_fibonacci(max_n=10)
print(circuit.encrypt_run_decrypt(6))  # 8

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def compile_fibonacci(
    max_n: int,
    *,
    allow_large_lookup: bool = False,
    configuration: Optional[fhe.Configuration] = None,
) -> fhe.Circuit:
    """Compile the nth Fibonacci number for encrypted n in [0, max_n].

    Args:
        max_n (int): The maximum value for the encrypted integer n.
        allow_large_lookup (bool): Whether to allow large table lookups (may be slow).
        configuration (Optional[fhe.Configuration]): Optional FHE compiler configuration object.

    Returns:
        fhe.Circuit: The compiled FHE circuit for Fibonacci computation.

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import compile_fibonacci

        circuit = compile_fibonacci(max_n=10)
        print(circuit.encrypt_run_decrypt(6))  # 8
        ```
    """
    check_lookup_domain('compile_fibonacci', (0, max_n), allow_large_lookup=allow_large_lookup)
    maximum = _validate_maximum("max_n", max_n)
    values = _fibonacci_values(maximum)
    return compile_unary_lookup(
        "compile_fibonacci",
        values,
        0,
        maximum,
        allow_large_lookup=allow_large_lookup,
        configuration=configuration,
    )

make_power

make_power(base: int, max_exponent: int) -> UnaryFunction

Create public-base exponentiation for an encrypted exponent.

Parameters:

Name	Type	Description	Default
base	int	The base to raise to the power of the exponent.	required
max_exponent	int	The maximum value for the encrypted exponent.	required

Returns:

Name	Type	Description
UnaryFunction	UnaryFunction	A unary function that computes base**exponent.

Example

from concrete_fhe_toolkit.math.combinatorics import make_power

pow_fn = make_power(base=2, max_exponent=10)
# Use `pow_fn(exponent)` inside an FHE program compilation

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def make_power(base: int, max_exponent: int) -> UnaryFunction:
    """Create public-base exponentiation for an encrypted exponent.

    Args:
        base (int): The base to raise to the power of the exponent.
        max_exponent (int): The maximum value for the encrypted exponent.

    Returns:
        UnaryFunction: A unary function that computes base**exponent.

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import make_power

        pow_fn = make_power(base=2, max_exponent=10)
        # Use `pow_fn(exponent)` inside an FHE program compilation
        ```
    """
    normalized_base = validate_integer("base", base)
    maximum = _validate_maximum("max_exponent", max_exponent)
    values = [normalized_base**exponent for exponent in range(maximum + 1)]
    return make_unary_lookup(values, 0)

compile_power

compile_power(base: int, max_exponent: int, *, allow_large_lookup: bool = False, configuration: Optional[Configuration] = None) -> fhe.Circuit

Compile public-base exponentiation for an encrypted exponent.

Parameters:

Name	Type	Description	Default
base	int	The base to raise to the power of the exponent.	required
max_exponent	int	The maximum value for the encrypted exponent.	required
allow_large_lookup	bool	Whether to allow large table lookups (may be slow).	False
configuration	Optional[Configuration]	Optional FHE compiler configuration object.	None

Returns:

Type	Description
Circuit	fhe.Circuit: The compiled FHE circuit for exponentiation.

Example

from concrete_fhe_toolkit.math.combinatorics import compile_power

circuit = compile_power(base=2, max_exponent=10)
print(circuit.encrypt_run_decrypt(3))  # 8

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def compile_power(
    base: int,
    max_exponent: int,
    *,
    allow_large_lookup: bool = False,
    configuration: Optional[fhe.Configuration] = None,
) -> fhe.Circuit:
    """Compile public-base exponentiation for an encrypted exponent.

    Args:
        base (int): The base to raise to the power of the exponent.
        max_exponent (int): The maximum value for the encrypted exponent.
        allow_large_lookup (bool): Whether to allow large table lookups (may be slow).
        configuration (Optional[fhe.Configuration]): Optional FHE compiler configuration object.

    Returns:
        fhe.Circuit: The compiled FHE circuit for exponentiation.

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import compile_power

        circuit = compile_power(base=2, max_exponent=10)
        print(circuit.encrypt_run_decrypt(3))  # 8
        ```
    """
    check_lookup_domain('compile_power', (0, max_exponent), allow_large_lookup=allow_large_lookup)
    normalized_base = validate_integer("base", base)
    maximum = _validate_maximum("max_exponent", max_exponent)
    values = [normalized_base**exponent for exponent in range(maximum + 1)]
    return compile_unary_lookup(
        "compile_power",
        values,
        0,
        maximum,
        allow_large_lookup=allow_large_lookup,
        configuration=configuration,
    )

make_comb

make_comb(max_n: int, *, invalid_result: int = 0) -> BinaryFunction

Create math.comb(n, r), returning invalid_result when r > n.

Parameters:

Name	Type	Description	Default
max_n	int	The maximum value for the encrypted integers n and r.	required
invalid_result	int	The result to return when r > n. Defaults to 0.	0

Returns:

Name	Type	Description
BinaryFunction	BinaryFunction	A binary function that computes math.comb(n, r).

Example

from concrete_fhe_toolkit.math.combinatorics import make_comb

comb_fn = make_comb(max_n=5, invalid_result=0)
# Use `comb_fn(n, r)` inside an FHE program compilation

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def make_comb(max_n: int, *, invalid_result: int = 0) -> BinaryFunction:
    """Create math.comb(n, r), returning invalid_result when r > n.

    Args:
        max_n (int): The maximum value for the encrypted integers n and r.
        invalid_result (int): The result to return when r > n. Defaults to 0.

    Returns:
        BinaryFunction: A binary function that computes math.comb(n, r).

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import make_comb

        comb_fn = make_comb(max_n=5, invalid_result=0)
        # Use `comb_fn(n, r)` inside an FHE program compilation
        ```
    """
    return _make_n_r_lookup(_comb_value, max_n, invalid_result)

compile_comb

compile_comb(max_n: int, *, invalid_result: int = 0, allow_large_lookup: bool = False, configuration: Optional[Configuration] = None) -> fhe.Circuit

Compile math.comb(n, r) for encrypted n and r in [0, max_n].

Parameters:

Name	Type	Description	Default
max_n	int	The maximum value for the encrypted integers n and r.	required
invalid_result	int	The result to return when r > n. Defaults to 0.	0
allow_large_lookup	bool	Whether to allow large table lookups (may be slow).	False
configuration	Optional[Configuration]	Optional FHE compiler configuration object.	None

Returns:

Type	Description
Circuit	fhe.Circuit: The compiled FHE circuit for combinations.

Example

from concrete_fhe_toolkit.math.combinatorics import compile_comb

circuit = compile_comb(max_n=5)
print(circuit.encrypt_run_decrypt(5, 2))  # 10

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def compile_comb(
    max_n: int,
    *,
    invalid_result: int = 0,
    allow_large_lookup: bool = False,
    configuration: Optional[fhe.Configuration] = None,
) -> fhe.Circuit:
    """Compile math.comb(n, r) for encrypted n and r in [0, max_n].

    Args:
        max_n (int): The maximum value for the encrypted integers n and r.
        invalid_result (int): The result to return when r > n. Defaults to 0.
        allow_large_lookup (bool): Whether to allow large table lookups (may be slow).
        configuration (Optional[fhe.Configuration]): Optional FHE compiler configuration object.

    Returns:
        fhe.Circuit: The compiled FHE circuit for combinations.

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import compile_comb

        circuit = compile_comb(max_n=5)
        print(circuit.encrypt_run_decrypt(5, 2))  # 10
        ```
    """
    check_lookup_domain(
        "compile_comb",
        (0, max_n),
        (0, max_n),
        allow_large_lookup=allow_large_lookup,
    )
    maximum = _validate_maximum("max_n", max_n)
    invalid = validate_integer("invalid_result", invalid_result)
    values = binary_values(
        lambda n, r: _comb_value(n, r, invalid),
        0,
        maximum,
        0,
        maximum,
    )
    return compile_binary_lookup(
        "compile_comb",
        values,
        0,
        maximum,
        0,
        maximum,
        allow_large_lookup=allow_large_lookup,
        configuration=configuration,
    )

make_perm

make_perm(max_n: int, *, invalid_result: int = 0) -> BinaryFunction

Create math.perm(n, r), returning invalid_result when r > n.

Parameters:

Name	Type	Description	Default
max_n	int	The maximum value for the encrypted integers n and r.	required
invalid_result	int	The result to return when r > n. Defaults to 0.	0

Returns:

Name	Type	Description
BinaryFunction	BinaryFunction	A binary function that computes math.perm(n, r).

Example

from concrete_fhe_toolkit.math.combinatorics import make_perm

perm_fn = make_perm(max_n=5, invalid_result=0)
# Use `perm_fn(n, r)` inside an FHE program compilation

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def make_perm(max_n: int, *, invalid_result: int = 0) -> BinaryFunction:
    """Create math.perm(n, r), returning invalid_result when r > n.

    Args:
        max_n (int): The maximum value for the encrypted integers n and r.
        invalid_result (int): The result to return when r > n. Defaults to 0.

    Returns:
        BinaryFunction: A binary function that computes math.perm(n, r).

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import make_perm

        perm_fn = make_perm(max_n=5, invalid_result=0)
        # Use `perm_fn(n, r)` inside an FHE program compilation
        ```
    """
    return _make_n_r_lookup(_perm_value, max_n, invalid_result)

compile_perm

compile_perm(max_n: int, *, invalid_result: int = 0, allow_large_lookup: bool = False, configuration: Optional[Configuration] = None) -> fhe.Circuit

Compile math.perm(n, r) for encrypted n and r in [0, max_n].

Parameters:

Name	Type	Description	Default
max_n	int	The maximum value for the encrypted integers n and r.	required
invalid_result	int	The result to return when r > n. Defaults to 0.	0
allow_large_lookup	bool	Whether to allow large table lookups (may be slow).	False
configuration	Optional[Configuration]	Optional FHE compiler configuration object.	None

Returns:

Type	Description
Circuit	fhe.Circuit: The compiled FHE circuit for permutations.

Example

from concrete_fhe_toolkit.math.combinatorics import compile_perm

circuit = compile_perm(max_n=5)
print(circuit.encrypt_run_decrypt(5, 2))  # 20

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def compile_perm(
    max_n: int,
    *,
    invalid_result: int = 0,
    allow_large_lookup: bool = False,
    configuration: Optional[fhe.Configuration] = None,
) -> fhe.Circuit:
    """Compile math.perm(n, r) for encrypted n and r in [0, max_n].

    Args:
        max_n (int): The maximum value for the encrypted integers n and r.
        invalid_result (int): The result to return when r > n. Defaults to 0.
        allow_large_lookup (bool): Whether to allow large table lookups (may be slow).
        configuration (Optional[fhe.Configuration]): Optional FHE compiler configuration object.

    Returns:
        fhe.Circuit: The compiled FHE circuit for permutations.

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import compile_perm

        circuit = compile_perm(max_n=5)
        print(circuit.encrypt_run_decrypt(5, 2))  # 20
        ```
    """
    check_lookup_domain(
        "compile_perm",
        (0, max_n),
        (0, max_n),
        allow_large_lookup=allow_large_lookup,
    )
    maximum = _validate_maximum("max_n", max_n)
    invalid = validate_integer("invalid_result", invalid_result)
    values = binary_values(
        lambda n, r: _perm_value(n, r, invalid),
        0,
        maximum,
        0,
        maximum,
    )
    return compile_binary_lookup(
        "compile_perm",
        values,
        0,
        maximum,
        0,
        maximum,
        allow_large_lookup=allow_large_lookup,
        configuration=configuration,
    )

make_powmod

make_powmod(base: int, modulus: int, max_exponent: int) -> UnaryFunction

Create pow(base, exponent, modulus) with a public base and modulus.

The exponent is encrypted and bounded by max_exponent; the result stays below the modulus, so the output bit width is small even for large exponents.

Parameters:

Name	Type	Description	Default
base	int	The base to raise to the power of the exponent.	required
modulus	int	The modulus for the operation.	required
max_exponent	int	The maximum value for the encrypted exponent.	required

Returns:

Name	Type	Description
UnaryFunction	UnaryFunction	A unary function that computes pow(base, exponent, modulus).

Example

from concrete_fhe_toolkit.math.combinatorics import make_powmod

powmod_fn = make_powmod(base=2, modulus=5, max_exponent=10)
# Use `powmod_fn(exponent)` inside an FHE program compilation

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def make_powmod(base: int, modulus: int, max_exponent: int) -> UnaryFunction:
    """Create pow(base, exponent, modulus) with a public base and modulus.

    The exponent is encrypted and bounded by ``max_exponent``; the result
    stays below the modulus, so the output bit width is small even for
    large exponents.

    Args:
        base (int): The base to raise to the power of the exponent.
        modulus (int): The modulus for the operation.
        max_exponent (int): The maximum value for the encrypted exponent.

    Returns:
        UnaryFunction: A unary function that computes pow(base, exponent, modulus).

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import make_powmod

        powmod_fn = make_powmod(base=2, modulus=5, max_exponent=10)
        # Use `powmod_fn(exponent)` inside an FHE program compilation
        ```
    """
    normalized_base = validate_integer("base", base)
    normalized_modulus = validate_integer("modulus", modulus, minimum=1)
    maximum = _validate_maximum("max_exponent", max_exponent)
    values = [
        pow(normalized_base, exponent, normalized_modulus)
        for exponent in range(maximum + 1)
    ]
    return make_unary_lookup(values, 0)

compile_powmod

compile_powmod(base: int, modulus: int, max_exponent: int, *, allow_large_lookup: bool = False, configuration: Optional[Configuration] = None) -> fhe.Circuit

Compile pow(base, exponent, modulus) with a public base and modulus.

Parameters:

Name	Type	Description	Default
base	int	The base to raise to the power of the exponent.	required
modulus	int	The modulus for the operation.	required
max_exponent	int	The maximum value for the encrypted exponent.	required
allow_large_lookup	bool	Whether to allow large table lookups (may be slow).	False
configuration	Optional[Configuration]	Optional FHE compiler configuration object.	None

Returns:

Type	Description
Circuit	fhe.Circuit: The compiled FHE circuit for modular exponentiation.

Example

from concrete_fhe_toolkit.math.combinatorics import compile_powmod

circuit = compile_powmod(base=2, modulus=5, max_exponent=10)
print(circuit.encrypt_run_decrypt(3))  # 3

Source code in src/concrete_fhe_toolkit/math/combinatorics.py

def compile_powmod(
    base: int,
    modulus: int,
    max_exponent: int,
    *,
    allow_large_lookup: bool = False,
    configuration: Optional[fhe.Configuration] = None,
) -> fhe.Circuit:
    """Compile pow(base, exponent, modulus) with a public base and modulus.

    Args:
        base (int): The base to raise to the power of the exponent.
        modulus (int): The modulus for the operation.
        max_exponent (int): The maximum value for the encrypted exponent.
        allow_large_lookup (bool): Whether to allow large table lookups (may be slow).
        configuration (Optional[fhe.Configuration]): Optional FHE compiler configuration object.

    Returns:
        fhe.Circuit: The compiled FHE circuit for modular exponentiation.

    Example:
        ```python
        from concrete_fhe_toolkit.math.combinatorics import compile_powmod

        circuit = compile_powmod(base=2, modulus=5, max_exponent=10)
        print(circuit.encrypt_run_decrypt(3))  # 3
        ```
    """
    check_lookup_domain('compile_powmod', (0, max_exponent), allow_large_lookup=allow_large_lookup)
    normalized_base = validate_integer("base", base)
    normalized_modulus = validate_integer("modulus", modulus, minimum=1)
    maximum = _validate_maximum("max_exponent", max_exponent)
    values = [
        pow(normalized_base, exponent, normalized_modulus)
        for exponent in range(maximum + 1)
    ]
    return compile_unary_lookup(
        "compile_powmod",
        values,
        0,
        maximum,
        allow_large_lookup=allow_large_lookup,
        configuration=configuration,
    )