q1ss.ap.generated

Generated affine partitions.

APMatrixGen

class APMatrixGen(ambient_dim, max_label_dim=None)

Bases: ABC

Abstract base class for generators of invertible matrices, used to construct instances of GenAP.

__call__(label)

Given a k-dimensional label vector, returns the pair of a (n-k)-dimensional matrix and its inverse, where n is the ambient dimension for the generator.

Parameters:

label (binvec)

Return type:

tuple[binmat, binmat]

abstractmethod _get_matrix(label)

Abstract method to be implemented by subclasses.

Given a k-dimensional label vector, returns the pair of a n-k-dimensional matrix and its inverse, where n is the ambient_dim for the generator.

The label vector has already been validated, and is guaranteed to have dimension between 0 and max_label_dim, both inclusive.

Parameters:

label (binvec)

Return type:

tuple[binmat, binmat]

property ambient_dim

The dimension of the ambient space for the generated matrices.

Return type:

int

static eye(ambient_dim)

Generator of identity matrices.

Parameters:

ambient_dim (int)

Return type:

EyeAPMatrixGen

property max_label_dim

The maximum dimension of labels for which matrices can be generated. Maximum is ambient_dim minus 1.

Return type:

int

static random(ambient_dim, *, seed=None)

Generator of random invertible matrices.

Parameters:

• ambient_dim (int)

• seed (np.random.Generator | int | None)

Return type:

RandomAPMatrixGen

EyeAPMatrixGen

class EyeAPMatrixGen(ambient_dim)

Bases: APMatrixGen

Generator of identity matrices.

static __new__(cls, ambient_dim)

Constructs a generator of identity matrices with given ambient dim.

Parameters:

ambient_dim (int)

Return type:

Self

_get_matrix(label)

On a k-dimensional label, returns a pair of (n-k)-dimensional identity matrices, where n is the ambient_dim.

Parameters:

label (binvec)

Return type:

tuple[binmat, binmat]

GenAP

final class GenAP(subsp_dim, generator)

Bases: AP

Class for ordered balanced affine partitions of n-bitstrings defined by a generator of invertible matrices for partial labels.

static __new__(cls, subsp_dim, generator)

Constructs a new affine partition from the given labelled matrix generator.

Parameters:

• subsp_dim (int)

• generator (APMatrixGen)

Return type:

Self

_get_subspace(label)

Returns the affine subspace corresponding to the given label, providing the underlying logic for __getitem__.

Let k be the label_dim and n be the ambient_dim for this generator, so that n-k is the subsp_dim.

1. Start from the standard affine subspace spanned by the first n-k standard basis vectors. The basepoint is given by a vector which is zero on the first n-k components, and is the reverse of the label on the remaining k components.

2. Generate a sequence of k-1 (matrix, inverse) pairs using partial labels, starting from label[:-1] and ending with the empty binary vector binvec([]).

3. Transform the standard subspace using the inverse matrices in the sequence, where matrix at index i acts on the subspace spanned by the first n-k+1+i std. basis vectors (n-k+1 -> n).

Uses the AffineSubspace.transform method with partial=True.

Parameters:

label (binvec)

Return type:

AffineSubspace

_label(vec)

Returns the label of the given vector in this affine partition, providing the underlying logic for label.

Let k be the label_dim and n be the ambient_dim for this generator.

1. Start from the given vector.

2. For each i in range(k), generates a matrix using the last i bits of the vector, read in reverse, then applies the matrix to the first n-i bits of the vector.

3. Returns the last k bits of the resulting vector, read in reverse.

Note that each matrix application keeps fixed the bits of the vector upon which the matrix itself depended.

Parameters:

vec (binvec)

Return type:

binvec

property generator

The labelled matrix generator for this affine partition.

Return type:

APMatrixGen

static random(subsp_dim, ambient_dim, *, seed=None)

Creates random GenAP for given subspace and ambient dimension, using APMatrixGen.random to create a random generator.

Parameters:

• subsp_dim (int)

• ambient_dim (int)

• seed (np.random.Generator | int | None)

Return type:

GenAP

RandomAPMatrixGen

class RandomAPMatrixGen(ambient_dim, seed)

Bases: APMatrixGen

Generator of random invertible matrices.

Warning

Currently, this is based on NumPy’s pseudo-random generator: it is not possible to generate oracles for affine partitions based on this class of generators.

In the future, an optional circuit property will be included in the APMatrixGen class, allowing for the automatic generation of oracles for GenAP instances. The functionality of this class will be extended to support circuit-defined pseudorandom functions, and NumPy’s random number generator will be deprecated.

static __new__(cls, ambient_dim, seed)

Constructs a generator of random invertible matrices with given ambient dimension and seed.

Parameters:

• ambient_dim (int)

• seed (int)

Return type:

Self

_get_matrix(label)

On a k-dimensional label, returns the pair of a random (n-k)-dimensional invertible matrix and its invers, where n is the ambient_dim.

The matrix and its inverse are sampled using binmat.random_inv, using a random number generator seeded by a combination of the label, the ambient dimension, and the seed provided.

Parameters:

label (binvec)

Return type:

tuple[binmat, binmat]

property seed

The seed used for generating random matrices.

Return type:

int