q1ss.ap.sequence

Affine partitions generated by fixed sequences of matrices.

SeqAP

final class SeqAP(data)

Bases: AP

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

static __new__(cls, data)

Constructs a new affine partition from the given sequences of matrices.

Parameters:

data (SeqAPData)

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. Selects a sequence of k-2 inverse matrices from the data, selecting from data.mats0_inv and data.mats1_inv based on the reverse bits of the label, starting from the penultimate and ending at the first. Then appends data.start_inv as the final matrix in the sequence, which has k-1 matrices in total.

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. Applies the data.start matrix to the vector (unless k is 0, in which case the vector is returned unchanged by this method).

3. For each i in range(k-1), generates a matrix using the bit at position k-i-1 in the vector, selects mats0[i] or mats1[i] based on its value, and applies the matrix to the first n-i-1 bits of the vector.

4. 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 as_generated

Returns the GenAP instance corresponding to this sequence-based affine partition.

Return type:

GenAP

property data

The data used to construct this affine partition.

Return type:

SeqAPData

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

Creates a random SeqAP for given subspace and ambient dimension, using SeqAPData.random to create random data.

Parameters:

• subsp_dim (int)

• ambient_dim (int)

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

Return type:

SeqAP

SeqAPData

final class SeqAPData(ambient_dim, start, mats0, mats1, *, copy=False)

Bases: object

Data used to construct a SeqAP instance:

• an ambient vector space dimension \(n\)

• an \(n \times n\) invertible start matrix

• two sequences mats0 and mats1 of \(m\) invertible matrices, where the matrix at index \(j=0,...,m-1\) in each sequence has size \((n-1-j)\times(n-1-j)\)

The inverses to all matrices above can be supplied, or are otherwise computed, and are stored in start_inv, mats0_inv, and mats1_inv. The subspace dimension for the affine partition is \(n-m-1\).

static __new__(cls, ambient_dim, start, mats0, mats1, *, copy=False)

Creates an empty SeqAP data container for given ambient dimension. Each invertible matrix in start, mats0 and mats1 can be passed as either a single matrix, or a pair of a matrix and its inverse: the inverse is automatically computed in the first case and it is validated in the second case. All matrices are made read-only as part of the constructor: if this is not desirable, the copy parameter can be set to True to make fresh copies of all matrices.

Parameters:

• ambient_dim (int)

• start (binmat | tuple[binmat, binmat])

• mats0 (Sequence[Union[binmat, tuple[binmat, binmat]]])

• mats1 (Sequence[Union[binmat, tuple[binmat, binmat]]])

• copy (bool; default = False)

Return type:

Self

property ambient_dim

The ambient dimension for the affine partition.

Return type:

int

property as_matrix_gen

Returns the matrix generating function for this data.

Return type:

SeqAPMatrixGen

property is_complete

Whether the affine partition data has been completely specified.

Return type:

bool

property label_dim

The label dimension for the affine partition.

Return type:

int

property mats0

The mats0 matrices for this affine partition.

Return type:

tuple[binmat, …]

property mats0_inv

Inverses of the mats0 matrices for this affine partition.

Return type:

tuple[binmat, …]

property mats1

The mats1 matrices for this affine partition.

Return type:

tuple[binmat, …]

property mats1_inv

Inverses of the mats1 matrices for this affine partition.

Return type:

tuple[binmat, …]

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

Creates random SeqAP data for given subspace and ambient dimension, using binmat.random_inv to sample matrix-inverse pairs for all matrices involved.

Warning

For moderately large dimensions, this method is computationally intensive. For example, subsp_dim=128 and ambient_dim=256 takes roughly 20s on a i7-1065G7. This will be optimised in future releases.

Parameters:

• subsp_dim (int)

• ambient_dim (int)

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

Return type:

SeqAPData

property start

The start matrix for this affine partition.

Return type:

binmat

property start_inv

Inverse of the start matrix for this affine partition.

Return type:

binmat

property subsp_dim

The subspace dimension for the affine partition.

Return type:

int

SeqAPMatrixGen

class SeqAPMatrixGen(data)

Bases: APMatrixGen

Matrix generator based on SeqAPData.

static __new__(cls, data)

Creates a new matrix generator using the given SeqAPData

Parameters:

data (SeqAPData)

Return type:

Self

_get_matrix(label)

Generates a (matrix, inverse) pair based on the last bit of the label.

• If label is empty, returns the pair of start and its inverse.

• If the last bit of label is 0, returns the pair of mats0[k-1] and its inverse, where k=len(label).

• If the last bit of label is 1, returns the pair of mats1[k-1] and its inverse, where k=len(label).

Parameters:

label (binvec)

Return type:

tuple[binmat, binmat]

property data

The data used to generate matrices.

Return type:

SeqAPData