q1ss.binalg.binmat

Binary matrices.

MatBitIdx

MatBitIdx

Type alias for the union of index types which result in a single bit being selected when passed to binmat.__getitem__.

alias of tuple[int, int]

MatSubmatIdx

MatSubmatIdx = slice | list[int] | tuple[slice, slice | list[int]] | tuple[slice | list[int], slice]

Type alias for the union of index types which result in a sub-matrix being selected when passed to binmat.__getitem__.

MatSubvecIdx

MatSubvecIdx = int | tuple[int, slice | list[int]] | tuple[slice | list[int], int] | tuple[list[int], list[int]]

Type alias for the union of index types which result in a sub-vector being selected when passed to binmat.__getitem__.

binmat

final class binmat(data, *, readonly=False, copy=False)

Bases: bintensor

A mutable binary matrix.

final class Cols(mat)

Bases: object

View of a binary matrix as a sequence of columns.

__add__(vec)

Returns the matrix obtained by adding the given vector to all columns of the matrix.

Parameters:

vec (binvec)

Return type:

binmat

__getitem__(idx)

Selects a column vector in a matrix, or creates a new matrix by slicing/selecting columns.

Parameters:

idx (int | slice | list[int])

Return type:

binvec | binmat

__mul__(vec)

Returns the matrix obtained by pointwise multiplication of the given vector with all columns of the matrix.

Parameters:

vec (binvec)

Return type:

binmat

static __new__(cls, mat)

Parameters:

mat (binmat)

Return type:

Self

__sub__(vec)

Same as __add__.

Parameters:

vec (binvec)

Return type:

binmat

exception NotInvertibleError

Bases: ZeroDivisionError

Subclass of ZeroDivisionError use when attempting to invert a matrix which is not invertible.

final class Rows(mat)

Bases: object

View of a binary matrix as a sequence of rows.

__add__(vec)

Returns the matrix obtained by adding the given vector to all rows of the matrix.

Parameters:

vec (binvec)

Return type:

binmat

__getitem__(idx)

Selects a row vector in a matrix, or creates a new matrix by slicing/selecting rows.

Parameters:

idx (int | slice | list[int])

Return type:

binvec | binmat

__mul__(vec)

Returns the matrix obtained by pointwise multiplication of the given vector with all rows of the matrix.

Parameters:

vec (binvec)

Return type:

binmat

static __new__(cls, mat)

Parameters:

mat (binmat)

Return type:

Self

__sub__(vec)

Same as __add__.

Parameters:

vec (binvec)

Return type:

binmat

property T

Returns the transpose of the matrix.

Return type:

binmat

__getitem__(idx)

If the index is an integer, returns the corresponding row of the matrix. If the index is a slice or a list/array of integers, returns the binary matrix containing the selected rows.

Parameters:

idx (MatBitIdx | MatSubvecIdx | MatSubmatIdx)

Return type:

Bit | binvec | binmat

__imatmul__(other)

Performs inplace binary matrix-matrix multiplication.

Raises:

ShapeError – if the intermediate dimensions don’t match.

Parameters:

other (binmat)

Return type:

binmat

__invert__()

Same as inverse.

Return type:

binmat

__matmul__(other)

Performs binary matrix-vector or matrix-matrix multiplication, depending on the type of other.

Raises:

ShapeError – if the intermediate dimensions don’t match.

Parameters:

other (binvec | binmat)

Return type:

binvec | binmat

static __new__(cls, data, *, readonly=False, copy=False)

Creates a new matrix from binary data.

If readonly=True, the resulting tensor and its data are readonly. If copy=True, a fresh copy of the given data is used.

Warning

The internal logic of binvec presumes that the given data will not be mutated externally to the binvec object after construction. If a fresh copy is needed, pass copy=True at construction.

Parameters:

• data (npt.ArrayLike)

• readonly (bool; default = False)

• copy (bool; default = False)

Return type:

Self

__or__(other)

Horizontal stacking of two matrices.

Parameters:

other (binmat)

Return type:

binmat

static block(blocks, *, readonly=False)

Creates a block matrix from given submatrices (or vectors).

Parameters:

• blocks (Sequence[Sequence[binmat]])

• readonly (bool; default = False)

Return type:

binmat

static block_diag(blocks, *, readonly=False)

Creates a block-diagonal matrix from given submatrices (or vectors).

Parameters:

• blocks (Sequence[binmat])

• readonly (bool; default = False)

Return type:

binmat

property cols

Returns a view of the matrix as a sequence of column vectors.

Return type:

binmat.Cols

copy(*, readonly=False)

Returns a copy of this tensor. If readonly=True, the resulting copy is readonly.

Parameters:

readonly (bool; default = False)

Return type:

Self

property ext_rcef

Returns the reduced column echelon form (RCEF) r of this matrix, computed modulo 2, together with the matrix m such that m@self == r.

If the matrix is invertible, r is the identity and m is its inverse.

Return type:

tuple[binmat, binmat]

property ext_rref

Returns the reduced row echelon form (RREF) r of this matrix, computed modulo 2, together with the matrix m such that m@self == r.

If the matrix is invertible, r is the identity and m is its inverse.

Return type:

tuple[binmat, binmat]

static eye(dim, *, readonly=False)

The identity matrix in the given dimension.

Parameters:

• dim (int)

• readonly (bool; default = False)

Return type:

binmat

static from_cols(cols, *, readonly=False)

Creates a matrix with the given column vectors.

Parameters:

• cols (Sequence[binvec])

• readonly (bool; default = False)

Return type:

binmat

static from_rows(rows, *, readonly=False)

Creates a matrix with the given row vectors.

Parameters:

• rows (Sequence[binvec])

• readonly (bool; default = False)

Return type:

binmat

static hstack(matrices, *, readonly=False)

Stacks the given matrices (or column vectors) horizontally.

Parameters:

• matrices (Sequence[Union[binmat, binvec]])

• readonly (bool; default = False)

Return type:

binmat

property inverse

The left inverse of this binary matrix, or None if the matrix is not invertible modulo 2.

Return type:

binmat

property is_eye

Whether this is the identity matrix.

Return type:

bool

property is_fullrank

Whether the matrix is full rank.

Return type:

bool

static num_rcef_params(n, m, pivots)

The number of parameters for a RCEF matrix with given data. See rcef_matrix.

Parameters:

• n (int)

• m (int)

• pivots (npt.ArrayLike)

Return type:

int

static num_rref_params(n, m, pivots)

The number of parameters for a RREF matrix with given data. See rref_matrix.

Parameters:

• n (int)

• m (int)

• pivots (npt.ArrayLike)

Return type:

int

static random(n, m, *, rng=None, readonly=False)

Random binary matrix with given shape.

Parameters:

• n (int)

• m (int)

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

• readonly (bool; default = False)

Return type:

binmat

static random_inv(n, *, rng=None, max_attempts=None, readonly=False)

Returns a random invertible matrix with given shape. This is done by rejection sampling, and a max_attempts can be set to limit the number of sampling attempts.

Parameters:

• n (int)

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

• max_attempts (int | None)

• readonly (bool; default = False)

Return type:

tuple[binmat, binmat]

static random_rcef(n, m, rank=None, *, rng=None, readonly=False)

Returns a random RCEF matrix with given shape. The rank of the matrix can be optionally specified (by default, the sampled RCEF matrix is full rank, i.e. rank=min(n,m)).

Warning

The current sampling method does not result in a uniform distribution in the Grasmannian \(\mathbf{Gr}(r,n)\), where \(r\) is the rank and \(n\) the number of rows. This will change in future releases.

Parameters:

• n (int)

• m (int)

• rank (int | None)

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

• readonly (bool; default = False)

Return type:

binmat

static random_rref(n, m, rank=None, *, rng=None, readonly=False)

Returns a random RREF matrix with given shape. The rank of the matrix can be optionally specified (by default, the sampled RREF matrix is full rank, i.e. rank=min(n,m)).

Warning

The current sampling method does not result in a uniform distribution in the Grasmannian \(\mathbf{Gr}(r,m)\), where \(r\) is the rank and \(m\) the number of cols. This will change in future releases.

Parameters:

• n (int)

• m (int)

• rank (int | None)

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

• readonly (bool; default = False)

Return type:

binmat

property rank

Computes and returns the matrix rank.

Return type:

int

property rcef

Returns the reduced column echelon form (RCEF) of this matrix, computed modulo 2.

Return type:

binmat

static rcef_matrix(n, m, pivot_rows, params=None, *, readonly=False)

Returns a n-by-m matrix in RCEF with the given pivot rows. The available degrees of freedom are filled with the given params vector entries, or set to zero if params is not given.

Raises:

• ValueError – if the pivot rows are not in range, not strictly ascending, or not the same number.

• ValueError – if params is given and it is not a 1D array with the number of parameters specified by num_rcef_params.

Parameters:

• n (int)

• m (int)

• pivot_rows (npt.ArrayLike)

• params (npt.ArrayLike | None)

• readonly (bool; default = False)

Return type:

binmat

property rows

Returns a view of the matrix as a sequence of row vectors.

Return type:

binmat.Rows

property rref

Returns the reduced row echelon form (RREF) of this matrix, computed modulo 2.

Return type:

binmat

static rref_matrix(n, m, pivot_cols, params=None, *, readonly=False)

Returns a n-by-m matrix in RCEF with the given pivot rows. The available degrees of freedom are filled with the given params vector entries, or set to zero if params is not given.

Raises:

• ValueError – if the pivot rows are not in range, not strictly ascending, or not the same number.

• ValueError – if params is given and it is not a 1D array with the number of parameters specified by num_rref_params.

Parameters:

• n (int)

• m (int)

• pivot_cols (npt.ArrayLike)

• params (npt.ArrayLike | None)

• readonly (bool; default = False)

Return type:

binmat

static trunc_eye(n, m, *, readonly=False)

The truncated identity matrix with the given shape

Parameters:

• n (int)

• m (int)

• readonly (bool; default = False)

Return type:

binmat

static validate_rcef_args(n, m, pivots, params=None)

Validates the arguments for a RCEF matrix with given data. See rcef_matrix. Returns the number of parameters expected (the length of params, if given).

Parameters:

• n (int)

• m (int)

• pivots (npt.ArrayLike)

• params (npt.ArrayLike | None)

Return type:

int

static validate_rref_args(n, m, pivots, params=None)

Validates the arguments for a RREF matrix with given data. See rref_matrix. Returns the number of parameters expected (the length of params, if given).

Parameters:

• n (int)

• m (int)

• pivots (npt.ArrayLike)

• params (npt.ArrayLike | None)

Return type:

int

static vstack(matrices, *, readonly=False)

Stacks the given matrices (or row vectors) vertically.

Parameters:

• matrices (Sequence[Union[binmat, binvec]])

• readonly (bool; default = False)

Return type:

binmat

static zeros(n, m, *, readonly=False)

Constructs a zero binary matrix with given shape.

Parameters:

• n (int)

• m (int)

• readonly (bool; default = False)

Return type:

binmat