D-Nary Arrays

`randomsymplectic.DnaryArray`

Bases: ndarray

A subclass of numpy.ndarray for arrays over the integers mod $d$ . Users can specify $d$ using the classmethod DnaryArray.set_d, which will return a subclass of DnaryArray specialized to the given modulus. Instances of that subclass behave as normal numpy arrays, but all outputs will be computed using arithmetic in $\mathbb{Z}_d$ .

Instances can be created from any array-like data acceptable by np.array(...).

Within a given d-nary class, symplectic algebra on matrices and vectors over $\mathbb{Z}_d$ , the modulo- $d$ integers, can be performed:

Validation of symplectic matrices (.is_symplectic_matrix())
Symplectic vector inner products (u | v or u.inner_product_with(v))
Uniform sampling over the group of symplectic arrays of a given size (.random_symplectic(n))
Accessing the defining symplectic array $\Lambda_n$ (either A.Lambda matching the invoking array's dimension, or the classmethod .LambdaN(n) for a given $n$ )

Note

For a given $n>0$ , the symplectic group $\text{Sp}(2n, \mathbb{Z}_d)$ is the group of $2n\times2n$ matrices $A$ such that $A^T \Lambda_n A=\mathbb{I}_{2n},$ where $\Lambda_n=\begin{bmatrix}0 & -\mathbb{I}_n \\ \mathbb{I}_n & 0 \end{bmatrix} \text{ mod } d$ and $\mathbb{I}_n$ is the $n\times n$ identity matrix.

The matrix $\Lambda_n$ may be defined differently in other contexts. The definition used here follows arXiv:quant-ph/0408190. See here for other definitions.

Similarly, the symplectic inner product $\langle v, w\rangle$ between length- $2n$ vectors $v,w$ is defined as $\langle v, w\rangle = v^T\Lambda_n w.$

If $\langle v, w\rangle=-1 \text{ mod } d$ , we say $(v,w)$ is a symplectic pair.

An equivalent definition for a symplectic matrix is the requirement that, for each $0\leq i< n$ , the matrix's $i$ th and $(i+n)$ th columns form a symplectic pair.

Examples:

>>> D3 = DnaryArray.set_d(3)
>>> D3([1, 2, 3, 4])
DnaryArray(d=3)([1, 2, 0, 1])

>>> D3.eye(4)
D3([[1, 0, 0, 0],
    [0, 1, 0, 0],
    [0, 0, 1, 0],
    [0, 0, 0, 1]])

>>> D3.eye(4)-2
D3([[2, 1, 1, 1],
    [1, 2, 1, 1],
    [1, 1, 2, 1],
    [1, 1, 1, 2]])

>>> (D3.eye(4)-2).inverse()
D3([[2, 1, 1, 1],
    [1, 2, 1, 1],
    [1, 1, 2, 1],
    [1, 1, 1, 2]])

>>> import numpy as np
>>> np.linalg.matrix_power(D3.eye(4)-2, 2)
D3([[1, 0, 0, 0],
    [0, 1, 0, 0],
    [0, 0, 1, 0],
    [0, 0, 0, 1]])

>>> MyD6Array = DnaryArray.set_d(6)
>>> (2 * MyD6Array.eye(2)) @ [2,3]
MyD6Array([4, 0])

`Lambda` `property`

Returns:	`Self` – The defining symplectic array matching the invoking object's dimension ( $2n\times 2n$ ). See `.LambdaN`.

`LambdaN(n)` `classmethod`

Returns the defining symplectic array $\Lambda_n$ for any given $n$ using the class modulus $d$ .

See DnaryArray.

Parameters:	`n` (`int`) – $\Lambda_n$ is a $2n\times 2n$ array.

Returns:	`Self` – The $d$ -nary (2n, 2n) array that defines the symplectic group and symplectic inner product.

`Transvection`

A class representing transvections, a class of linear transformations on vectors. Transvections are defined by a vector $\vec u$ and a constant $c$ , and act as $v\mapsto T_{u, c}(v)=v + c\langle v, u\rangle u$ . All arithmetic is mod d. Transvections applied to matrices apply the above transformation column-wise.

Parameters:	`u` (`DnaryArray`) – The vector to transvect by. `c` (`int`) – The constant of the transvection.

`call(vector_or_matrix)`

Apply the transvection to a vector or matrix of the same type as the transvection's vector.

Parameters:	`vector_or_matrix` (`DnaryArray`) – A vector or matrix of the same type as the Transvection's vector.

Returns:	`DnaryArray`( `DnaryArray` ) – The transvection applied to the vector or matrix.

`find_transvection(u, v)` `classmethod`

Returns a tuple of transvections $T_1, T_2$ such that $T_2(T_1(u))=v$ .

Parameters:	`u` (`DnaryArray`) – Vector you are transvecting from. `v` (`DnaryArray`) – Vector you are transvecting to.

Returns:	`(Transvection, Transvection)` – A tuple (T1, T2) such that T2(T1(u))==v

`transvect_matrix_columns(A)`

Apply the transvection to a matrix of the same type as the transvection's vector.

Parameters:	`A` (`DnaryArray`) – A matrix of the same type as the Transvection's vector.

Returns:	`DnaryArray`( `DnaryArray` ) – The transvection applied to the matrix.

`transvect_vector(v)`

Apply the transvection to a vector of the same type as the transvection's vector.

Parameters:	`v` (`DnaryArray`) – A vector of the same type as the Transvection's vector.

Returns:	`DnaryArray`( `DnaryArray` ) – The transvection applied to the vector.

`basis_vector(i, n)` `classmethod`

Generates the $i$ th standard basis vector of length $n$ . This is the vector of all zeros except the $i$ th component equal to $1$ .

Parameters:	`i` (`int`) – The component of the basis vector. `n` (`int`) – The length of the vector

Returns:	`Self` – The $i$ th standard basis vector.

Examples:

>>> class D3(DnaryArray): d=3
>>> D3.basis_vector(1, 5)
D3([0, 1, 0, 0, 0])

`det()`

Alias for .determinant.

Returns:	`int` – The determinant of the array modulo $d$ .

`determinant()`

Returns:	`int` – The determinant of the array modulo d.

`dnary_inverse(n)` `classmethod`

Alias for dnary_inverse(n, cls.d). Calculates the multiplicative inverse of n in $\mathbb{Z}_d$ if it exists.

If $d$ is prime and $n>0$ , the integer is guaranteed to exist. For general $d$ , $n^{-1}$ exists if $\text{gcd}(n,d)=1$ .

Parameters:	`n` (`int`) – The integer to invert.

Returns:	`int` – The integer $n^{-1}$ such that $n n^{-1} \text{ mod } d = 1$ , or `None` if such an integer does not exist.

`dnary_to_int(digits)` `classmethod`

Alias for int_to_dnary(n, cls.d). Given a list of the $d$ -nary digits of a number, return that number in base 10.

See also [randomsymplectic.DnaryArray.int_to_dnary].

Parameters:	`digits` (`list[int]`) – A list of the $d$ -nary digits of a number.

Returns:	`int` – The number in base 10.

`embed_symplectic()`

Embeds a $2n\times 2n$ array into a $(2n+1)\times(2n+1)$ array via the symplecticity-preserving block embedding $\begin{bmatrix} M_{11} & M_{12}\\ M_{21} & M_{22} \end{bmatrix} \mapsto \begin{bmatrix} 1 & 0 & 0 & 0\\ 0& M_{11} & 0 & M_{12}\\ 0 & 0 & 1 & 0\\ 0 & M_{21} & 0 & M_{22} \end{bmatrix},$ which inserts identity rows/columns at indices $0$ and $n$ (Python indexing) and fills the gaps with zeros.

Returns:	`Self` – The embedded array.

`eye(n)` `classmethod`

Returns:	`Self` – The `(n, n)` identity matrix with integer type.

`from_index(index, n)` `classmethod`

Generate an element of the symplectic group from that element's index.

Parameters:	`index` (`int`) – An integer from 0 (inclusive) to the size of the symplectic group (exclusive). See `.symplectic_group_size`. `n` (`int`) – Half the size of the symplectic matrix to be generated, or the number of qubits in the equivalent Clifford group.

Returns:	`Self`( `Self` ) – The symplectic matrix corresponding to the input index.

`inner_product(v1, v2)` `classmethod`

Computes the symplectic inner product of the given vectors.

The symplectic inner product $\langle v, w\rangle$ between length- $2n$ vectors $v,w$ is defined as $\langle v, w\rangle = v^T\Lambda_n w.$

Parameters:	`v1` (`Self \| ndarray`) – The first vector. Will be coerced into the type of the calling class. `v2` (`Self \| ndarray`) – The second vector. Will be coerced into the type of the calling class.

Raises:	`ValueError` – Input arrays are not one-dimensional. `ValueError` – Input arrays are not the same size.

Returns:	`int` – The symplectic inner product of `v1` and `v2`.

Tip

If you've already created a vector v, you can call v.inner_product_with(w) method to compute $\langle v,w\rangle$ .

Note

The modulus $d$ is defined by the calling class. Thus, v1 and v2 can be any array-like data, but they will be coerced into the type of the calling class (by coercing components to integers and modding by $d$ ).

`inner_product_with(other)`

Compute the symplectic inner product of the calling vector with the other vector.

See the .inner_product classmethod.

Parameters:	`other` (`Self`) – The other vector.

Returns:	`int` – The symplectic inner product of the calling vector with the other vector.

Tip

Python's pipe operator | is overloaded with this method, so you can call v1.inner_product_with(v2) as v1 | v2.

Examples:

>>> D3 = DnaryArray.set_d(3)
>>> v1 = D3([1, 0, 0, 0])
>>> v2 = D3([0, 0, 1, 0])
>>> v1 | v2
2

`int_to_dnary(n, result_list_size=None)` `classmethod`

Alias for int_to_dnary(n, cls.d).

Decomposes a base 10 integer into a list of its $d$ -nary digits.

See also [randomsymplectic.DnaryArray.dnary_to_int].

Parameters:	`n` (`int`) – The base 10 integer to be factored into its $d$ -nary digits. `result_list_size` (`int \| None`, default: `None` ) – The length of the list to return; if `None`, will use the minimum number of digits to result the input integer in $d$ -nary. Defaults to `None`.

Raises:	`ValueError` – Invalid input parameters.

Returns:	`list[int]` – A list of the $d$ -nary digits of `n` The list has $L$ elements $l_i$ such that $n=\sum_{i=0}^L l_i d^i.$

`inv(**kwargs)`

Alias for mod_matrix_inv.

Returns:	`Self \| None` – The array's inverse, or `None` if the array is not invertible.

`inverse(**kwargs)`

Alias for mod_matrix_inv.

Returns:	`Self \| None` – The array's inverse, or `None` if the array is not invertible.

`is_invertible()`

Determines if an array is invertible by checking if its determinant is invertible in $\mathbb{Z}_d$ .

Returns:	`bool` – Whether the array is invertible.

`is_matrix` `property`

Returns:	`bool` – Whether this is a 2D array.

`is_nonzero()`

Returns:	`bool` – Whether the array has any nonzero values in it.

`is_symplectic_matrix()`

Returns:	`bool` – Whether the calling array is a symplectic matrix.

`is_symplectic_pair(v1, v2)` `classmethod`

Determine whether a pair of vectors form a symplectic pair.

Two vectors $v, w$ form a symplectic pair if $\langle v, w\rangle = -1 \text{ mod } d.$

`is_symplectic_pair_with(other)`

If the calling object is a vector (i.e. 1D array), determine whether it forms a symplectic pair with another vector.

See the .is_symplectic_pair classmethod.

Raises an exception if the calling object is not a vector.

Parameters:	`other` (`Self`) – The other vector.

Raises:	`TypeError` – Both the calling object and the input must be 1d arrays.

Returns:	`bool` – Whether the two vectors form a symplectic pair.

`is_vector` `property`

Returns:	`bool` – Whether this is a 1D array.

`is_zero()`

Returns:	`bool` – Whether the array is all zero.

`mod_matrix_inv(validate=True, suppress_warnings=True)`

Calculates the matrix inverse in $\mathbb{Z}_d$ -arithmetic using $A^{-1}=\frac{1}{|A|}\text{Adj}(A),$ where $\text{Adj}(A)$ is the matrix adjugate of $A$ and $|A|$ is the determinant.

Parameters:	`validate` (`bool`, default: `True` ) – Whether to validate the result through multiplication. Defaults to True. `suppress_warnings` (`bool`, default: `True` ) – If False, warnings will be raise if the array is not invertible. Defaults to True.

Raises:	`RuntimeError` – If the inversion fails for an invertible array. Theoretically this should never happen.

Returns:	`Self \| None` – The array's inverse, or `None` if the array is not invertible.

`n` `property`

Half of the array size. Will raise an exception for odd-sized arrays.

Defines the defining symplectic array $\Lambda_n$ . See the .Lambda property and the .LambdaN method.

Raises:	`ValueError` – Not accessible for odd-sized arrays.

Returns:	`int` – Half of the array size.

`nn` `property`

Returns:	`int` – The symplectic array size $2n$ .

`random_array(shape, allow_zero=True)` `classmethod`

Returns an array of the given shape with uniform random integers mod $d$ , including the all-zero array unless specified otherwise.

Parameters:	`shape` (`tuple[int]`) – The shape of the array. `allow_zero` (`bool`, default: `True` ) – Whether to allow the zero matrix. Defaults to `True`.

Returns:	`Self` – A uniform random $d$ -nary array.

`random_symplectic(n)` `classmethod`

Generate a uniformly random element of the symplectic group.

Parameters:	`n` (`int`) – Half the size of the symplectic matrix to be generated, or the number of qubits in the equivalent Clifford group.

Returns:	`Self`( `Self` ) – A uniform random $d$ -nary symplectic matrix.

`set_d(d)` `classmethod`

Classmethod for creating a child class with a specific d.

Parameters:	`d` (`int`) – The modulus of the class to create.

Returns:	`_type_`( `type[DnaryArray]` ) – description

`symplectic_group_size(n)` `classmethod`

Returns the size of the symplectic group for a given $n$ . That number is $\prod_{i=1}^n d^{2i-1}(d^{2i}-1).$

Parameters:	`n` (`int`) – Half the size of the symplectic matrix, or the number of qubits in the equivalent Clifford group.

Returns:	`int` – The number of different $2n\times 2n$ symplectic matrices over $\mathbb{Z}_d$ .

`zeros(shape)` `classmethod`

Returns an all-zero array of the given shape.

Parameters:	`shape` (`int \| tuple[int]`) – The shape of the desired array.

Returns:	`Self` – The zero array of the given shape.

randomsymplectic.DnaryArray

Lambda property

LambdaN(n) classmethod

Transvection

__call__(vector_or_matrix)

find_transvection(u, v) classmethod

transvect_matrix_columns(A)

transvect_vector(v)

basis_vector(i, n) classmethod

det()

determinant()

dnary_inverse(n) classmethod

dnary_to_int(digits) classmethod

embed_symplectic()

eye(n) classmethod

from_index(index, n) classmethod

inner_product(v1, v2) classmethod

inner_product_with(other)

int_to_dnary(n, result_list_size=None) classmethod

inv(**kwargs)

inverse(**kwargs)

is_invertible()

is_matrix property

is_nonzero()

is_symplectic_matrix()

is_symplectic_pair(v1, v2) classmethod

is_symplectic_pair_with(other)

is_vector property

is_zero()

mod_matrix_inv(validate=True, suppress_warnings=True)

n property

nn property

random_array(shape, allow_zero=True) classmethod

random_symplectic(n) classmethod

set_d(d) classmethod

symplectic_group_size(n) classmethod

zeros(shape) classmethod

`randomsymplectic.DnaryArray`

`Lambda` `property`

`LambdaN(n)` `classmethod`

`Transvection`

`call(vector_or_matrix)`

`find_transvection(u, v)` `classmethod`

`transvect_matrix_columns(A)`

`transvect_vector(v)`

`basis_vector(i, n)` `classmethod`

`det()`

`determinant()`

`dnary_inverse(n)` `classmethod`

`dnary_to_int(digits)` `classmethod`

`embed_symplectic()`

`eye(n)` `classmethod`

`from_index(index, n)` `classmethod`

`inner_product(v1, v2)` `classmethod`

`inner_product_with(other)`

`int_to_dnary(n, result_list_size=None)` `classmethod`

`inv(**kwargs)`

`inverse(**kwargs)`

`is_invertible()`

`is_matrix` `property`

`is_nonzero()`

`is_symplectic_matrix()`

`is_symplectic_pair(v1, v2)` `classmethod`

`is_symplectic_pair_with(other)`

`is_vector` `property`

`is_zero()`

`mod_matrix_inv(validate=True, suppress_warnings=True)`

`n` `property`

`nn` `property`

`random_array(shape, allow_zero=True)` `classmethod`

`random_symplectic(n)` `classmethod`

`set_d(d)` `classmethod`

`symplectic_group_size(n)` `classmethod`

`zeros(shape)` `classmethod`