Matrix API

The matrix_api.py module provides the main NumPy-compatible interface. Key functions include:

add(a, b) - Element-wise addition
multiply(a, b) - Element-wise multiplication
matmul(a, b) - Matrix multiplication
sum(a, axis=None, keepdims=False) - Sum reduction
mean(a, axis=None, keepdims=False) - Mean calculation
cumulative_sum(a, axis=None) - Cumulative sum
transpose(a, axes=None) - Transpose operation
roll(a, shift, axis=None) - Roll/shift elements

matrix_api.py

Handles documenting and the public interface of the matrix operation.

This module provides NumPy-compatible matrix operations that can be performed on encrypted data using homomorphic encryption. Functions follow NumPy naming conventions and similar signatures where possible.

All functions use the tensor_function_api decorator to handle different tensor types and dispatch to the appropriate backend implementation.

openfhe_numpy.operations.matrix_api.add(a, b)[source]

Return type:

TypeAliasType

Element-wise addition of two arrays (or array and scalar).

Parameters:

a (ArrayLike)
b (ArrayLike)

See also

numpy.add

openfhe_numpy.operations.matrix_api.subtract(a, b)[source]

Return type:

TypeAliasType

Element-wise subtraction of two arrays (or array and scalar).

Parameters:

a (ArrayLike)
b (ArrayLike)

See also

numpy.subtract

openfhe_numpy.operations.matrix_api.multiply(a, b)[source]

Element-wise multiplication of two arrays (or array and scalar).

Parameters:

a (TypeAliasType) – First operand.
b (TypeAliasType) – Second operand (array or scalar).

Returns:

out – Element-wise product.

Return type:

TypeAliasType

See also

numpy.multiply: Corresponding NumPy function.

Examples

>>> multiply([1, 2], [3, 4])
array([3, 8])

openfhe_numpy.operations.matrix_api.pow(a, exponent)[source]

For each element of the tensor, it raises that element to the given power.

Note

This only supports integer exponents due to homomorphic-encryption constraints.

Parameters:

a (TypeAliasType) – Base tensor.
exponent (int) – Non-negative integer exponent.

Returns:

out – Element-wise ‘a’ raised to ‘exponent’.

Return type:

TypeAliasType

See also

numpy.pow: Corresponding element-wise power function.
numpy.linalg.matrix_power: Repeated matrix multiplication for square matrices.

Examples

>>> power([1, 2, 3], 2)
array([1, 4, 9])

openfhe_numpy.operations.matrix_api.dot(a, b)[source]

Dot product / matrix multiplication.

1-D inputs: inner product
2-D inputs: matrix product

Parameters:

a (TypeAliasType) – Operands.
b (TypeAliasType) – Operands.

Returns:

Result of the dot product.

Return type:

TypeAliasType

See also

numpy.dot

Examples

>>> dot([1, 2], [3, 4])
11
>>> import numpy as np
>>> A = np.array([[1, 2], [3, 4]])
>>> B = np.array([[5, 6], [7, 8]])
>>> dot(A, B)
array([[19, 22],
       [43, 50]])

openfhe_numpy.operations.matrix_api.matmul(a, b)[source]

Matrix multiply two tensors.

Parameters:

a (TypeAliasType) – First operand.
b (TypeAliasType) – Second operand.

Returns:

out – Matrix product of ‘a’ and ‘b’.

Return type:

TypeAliasType

See also

numpy.matmul: Corresponding NumPy function.

Examples

>>> import numpy as np
>>> matmul(np.array([[1, 2], [3, 4]]), np.array([[5, 6], [7, 8]]))
array([[19, 22],
       [43, 50]])

openfhe_numpy.operations.matrix_api.transpose(a)[source]

Transpose array axes (for 2-D: swap rows and columns). For 1-D inputs (vectors), the array is returned unchanged. :param a: Input tensor. :type a: TypeAliasType

Returns:: out – Transposed tensor.
Return type:: TypeAliasType
Parameters:: a (ArrayLike)

See also

numpy.transpose: Corresponding NumPy function.

Examples

>>> import numpy as np
>>> transpose(np.array([[1, 2], [3, 4]]))
array([[1, 3],
       [2, 4]])

openfhe_numpy.operations.matrix_api.cumulative_sum(x, /, *, axis=None)[source]

Compute the cumulative sum of tensor elements along a specified axis. - For 1D inputs, axis must be None. - For 2D inputs, axis must be 0 or 1. - The include_initial argument is not supported.

Parameters:

a (ArrayLike) – Input tensor.
axis (Optional[int]) – Axis along which to compute the sum. Default is 0.
x (ArrayLike)

Returns:

out – Cumulative sum along an axis.

Return type:

TypeAliasType

See also

numpy.cumulative_sum: Corresponding NumPy function.

Examples

>>> import numpy as onp
>>> cumulative_sum(np.array([[1, 2], [3, 4]]), axis=1)
array([[1, 3],
       [3, 7]])

openfhe_numpy.operations.matrix_api.cumulative_reduce(a, axis=0, keepdims=False)[source]

Compute the cumulative reduction of tensor elements along a specified axis. - For 1D inputs, axis must be None.

For 2D inputs, axis must be 0 or 1.
The include_initial argument is not supported.

Parameters:

a (TypeAliasType) – Input tensor.
axis (int) – Axis along which to compute the reduction. Default is 0.
keepdims (bool)

Returns:

out – Cumulative reduction of ‘a’.

Return type:

TypeAliasType

See also

numpy.cumulative_sum: Similar operation for sum.

Examples

>>> import numpy as np
>>> cumulative_reduce(np.array([[1, 2, 3], [4, 5, 6]]), axis=0)
array([[1, 2, 3],
       [-3, -3, -3]])

openfhe_numpy.operations.matrix_api.sum(a, /, *, axis=None, keepdims=False)[source]

Sum of elements over an axis or all.

Parameters:

a (TypeAliasType) – Input tensor.
axis (Optional[int]) – Axis along which to compute the sum. Default is 0. 0: sum over rows 1: sum over cols
keepdims (bool) – If True, retains reduced dimensions. Default is False.

Returns:

out – Sum of ‘a’ elements.

Return type:

TypeAliasType

See also

numpy.sum: Corresponding NumPy function.

Examples

>>> import numpy as np
>>> a = np.array([[1, 2], [3, 4]])
>>> sum(a)
10
>>> sum(a, axis=0)
array([4, 6])
>>> sum(a, axis=1)
array([3, 7])

openfhe_numpy.operations.matrix_api.mean(a, /, *, axis=None, dtype=None, out=None, keepdims=False)[source]

Compute the arithmetic mean along an axis or all elements.

Returns the average of the array elements. The average is taken over the flattened array by default, otherwise over the specified axis.

Parameters:

a (TypeAliasType) – Input tensor.
axis (Optional[int]) – Axis along which to compute the mean. Default is 0.
keepdims (bool) – If True, retains reduced dimensions. Default is False.

Returns:

out – Mean of ‘a’ elements.

Return type:

TypeAliasType

See also

numpy.mean: Corresponding NumPy function.

Examples

>>> import numpy as np
>>> a = np.array([[1, 2], [3, 4]])
>>> mean(a)
2.5
>>> mean(a, axis=0)
array([2., 3.])
>>> mean(a, axis=1)
array([1.5, 3.5])

openfhe_numpy.operations.matrix_api.roll(a, shift, axis=None)[source]

Roll array elements along a given axis.

Elements that roll beyond the last position are re-introduced at the first.

Parameters:

a (TypeAliasType) – Input array.
shift (int or tuple of ints) – The number of places by which elements are shifted. If a tuple, then axis must be a tuple of the same size, and each of the given axes is shifted by the corresponding number. If an int while axis is a tuple of ints, then the same value is used for all given axes.
axis (Optional[int]) – Axis or axes along which elements are shifted. By default, the array is flattened before shifting, after which the original shape is restored.

Returns:

res – Output array, with the same shape as a.

Return type:

TypeAliasType

See also

numpy.roll: Corresponding NumPy function.

Examples

>>> import numpy as np
>>> x = np.arange(10)
>>> roll(x, 2)
array([8, 9, 0, 1, 2, 3, 4, 5, 6, 7])
>>> x2 = np.reshape(x, (2, 5))
>>> roll(x2, 1, axis=0)
array([[5, 6, 7, 8, 9],
       [0, 1, 2, 3, 4]])
>>> roll(x2, (1, 1), axis=(1, 0))  # Multiple axes
array([[9, 5, 6, 7, 8],
       [4, 0, 1, 2, 3]])