GF2Matrix (Bouncy Castle Library 1.52 API Specification)

org.bouncycastle.pqc.math.linearalgebra

## Class GF2Matrix

- java.lang.Object
- - org.bouncycastle.pqc.math.linearalgebra.Matrix
  - - org.bouncycastle.pqc.math.linearalgebra.GF2Matrix

-     public class GF2Matrix
      extends Matrix

  This class describes some operations with matrices over finite field GF(2) and is used in ecc and MQ-PKC (also has some specific methods and implementation)

- - ### Field Summary

    - ### Fields inherited from class org.bouncycastle.pqc.math.linearalgebra.Matrix

      `MATRIX_TYPE_RANDOM_LT, MATRIX_TYPE_RANDOM_REGULAR, MATRIX_TYPE_RANDOM_UT, MATRIX_TYPE_UNIT, MATRIX_TYPE_ZERO, numColumns, numRows`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GF2Matrix(byte[] enc)` Create the matrix from encoded form.
    `GF2Matrix(GF2Matrix a)` Copy constructor.
    `GF2Matrix(int n, char typeOfMatrix)` Create an nxn matrix of the given type.
    `GF2Matrix(int n, char typeOfMatrix, java.security.SecureRandom sr)` Create an nxn matrix of the given type.
    `GF2Matrix(int numColumns, int[][] matrix)` Create the matrix with the contents of the given array.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Matrix` | `computeInverse()` Compute the inverse of this matrix.
    `Matrix` | `computeTranspose()` Compute the transpose of this matrix.
    `static GF2Matrix[]` | `createRandomRegularMatrixAndItsInverse(int n, java.security.SecureRandom sr)` Create a nxn random regular matrix and its inverse.
    `boolean` | `equals(java.lang.Object other)` Compare this matrix with another object.
    `GF2Matrix` | `extendLeftCompactForm()` Compute the full form matrix `(this | Id)` from this matrix in left compact form, where `Id` is the `k x k` identity matrix and `k` is the number of rows of this matrix.
    `GF2Matrix` | `extendRightCompactForm()` Compute the full form matrix `(Id | this)` from this matrix in right compact form, where `Id` is the `k x k` identity matrix and `k` is the number of rows of this matrix.
    `byte[]` | `getEncoded()` Returns encoded matrix, i.e., this matrix in byte array form
    `double` | `getHammingWeight()` Returns the percentage of the number of "ones" in this matrix.
    `int[][]` | `getIntArray()`
    `GF2Matrix` | `getLeftSubMatrix()` Get the quadratic submatrix of this matrix consisting of the leftmost `numRows` columns.
    `int` | `getLength()`
    `GF2Matrix` | `getRightSubMatrix()` Get the submatrix of this matrix consisting of the rightmost `numColumns-numRows` columns.
    `int[]` | `getRow(int index)` Return the row of this matrix with the given index.
    `int` | `hashCode()`
    `boolean` | `isZero()` Check if this is the zero matrix (i.e., all entries are zero).
    `Matrix` | `leftMultiply(Permutation p)` Compute the product of a permutation matrix (which is generated from an n-permutation) and this matrix.
    `Vector` | `leftMultiply(Vector vec)` compute product a row vector and this matrix
    `Vector` | `leftMultiplyLeftCompactForm(Vector vec)` Compute the product of the matrix `(this | Id)` and a column vector, where `Id` is a `(numRows x numRows)` unit matrix.
    `Matrix` | `rightMultiply(Matrix mat)` Compute the product of this matrix and a matrix A over GF(2).
    `Matrix` | `rightMultiply(Permutation p)` Compute the product of this matrix and a permutation matrix which is generated from an n-permutation.
    `Vector` | `rightMultiply(Vector vec)` Compute the product of this matrix and the given column vector.
    `Vector` | `rightMultiplyRightCompactForm(Vector vec)` Compute the product of the matrix `(Id | this)` and a column vector, where `Id` is a `(numRows x numRows)` unit matrix.
    `java.lang.String` | `toString()`

    - ### Methods inherited from class org.bouncycastle.pqc.math.linearalgebra.Matrix

      `getNumColumns, getNumRows`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### GF2Matrix

          public GF2Matrix(byte[] enc)

      Create the matrix from encoded form.
      Parameters:
        `enc` - the encoded matrix

    - #### GF2Matrix

          public GF2Matrix(int numColumns,
                   int[][] matrix)

      Create the matrix with the contents of the given array. The matrix is not copied. Unused coefficients are masked out.
      Parameters:
        `numColumns` - the number of columns
        `matrix` - the element array

    - #### GF2Matrix

          public GF2Matrix(int n,
                   char typeOfMatrix)

      Create an nxn matrix of the given type.
      Parameters:
        `n` - the number of rows (and columns)
        `typeOfMatrix` - the martix type (see `Matrix` for predefined constants)

    - #### GF2Matrix

          public GF2Matrix(int n,
                   char typeOfMatrix,
                   java.security.SecureRandom sr)

      Create an nxn matrix of the given type.
      Parameters:
        `n` - the matrix size
        `typeOfMatrix` - the matrix type
        `sr` - the source of randomness

    - #### GF2Matrix

          public GF2Matrix(GF2Matrix a)

      Copy constructor.
      Parameters:
        `a` - another `GF2Matrix`

  - ### Method Detail

    - #### createRandomRegularMatrixAndItsInverse

          public static GF2Matrix[] createRandomRegularMatrixAndItsInverse(int n,
                                                           java.security.SecureRandom sr)

      Create a nxn random regular matrix and its inverse.
      Parameters:
        `n` - number of rows (and columns)
        `sr` - source of randomness
      Returns:
        the created random regular matrix and its inverse

    - #### getIntArray

          public int[][] getIntArray()

      Returns:
        the array keeping the matrix elements

    - #### getLength

          public int getLength()

      Returns:
        the length of each array representing a row of this matrix

    - #### getRow

          public int[] getRow(int index)

      Return the row of this matrix with the given index.
      Parameters:
        `index` - the index
      Returns:
        the row of this matrix with the given index

    - #### getEncoded

          public byte[] getEncoded()

      Returns encoded matrix, i.e., this matrix in byte array form
      Specified by:
        `getEncoded` in class `Matrix`
      Returns:
        the encoded matrix

    - #### getHammingWeight

          public double getHammingWeight()

      Returns the percentage of the number of "ones" in this matrix.
      Returns:
        the Hamming weight of this matrix (as a ratio).

    - #### isZero

          public boolean isZero()

      Check if this is the zero matrix (i.e., all entries are zero).
      Specified by:
        `isZero` in class `Matrix`
      Returns:
        `true` if this is the zero matrix

    - #### getLeftSubMatrix

          public GF2Matrix getLeftSubMatrix()

      Get the quadratic submatrix of this matrix consisting of the leftmost `numRows` columns.
      Returns:
        the `(numRows x numRows)` submatrix

    - #### extendLeftCompactForm

          public GF2Matrix extendLeftCompactForm()

      Compute the full form matrix `(this | Id)` from this matrix in left compact form, where `Id` is the `k x k` identity matrix and `k` is the number of rows of this matrix.
      Returns:
        `(this | Id)`

    - #### getRightSubMatrix

          public GF2Matrix getRightSubMatrix()

      Get the submatrix of this matrix consisting of the rightmost `numColumns-numRows` columns.
      Returns:
        the `(numRows x (numColumns-numRows))` submatrix

    - #### extendRightCompactForm

          public GF2Matrix extendRightCompactForm()

      Compute the full form matrix `(Id | this)` from this matrix in right compact form, where `Id` is the `k x k` identity matrix and `k` is the number of rows of this matrix.
      Returns:
        `(Id | this)`

    - #### computeTranspose

          public Matrix computeTranspose()

      Compute the transpose of this matrix.
      Returns:
        `(this)T`

    - #### computeInverse

          public Matrix computeInverse()

      Compute the inverse of this matrix.
      Specified by:
        `computeInverse` in class `Matrix`
      Returns:
        the inverse of this matrix (newly created).
      Throws:
        `java.lang.ArithmeticException` - if this matrix is not invertible.

    - #### leftMultiply

          public Matrix leftMultiply(Permutation p)

      Compute the product of a permutation matrix (which is generated from an n-permutation) and this matrix.
      Parameters:
        `p` - the permutation
      Returns:
        `GF2Matrix` `P*this`

    - #### leftMultiply

          public Vector leftMultiply(Vector vec)

      compute product a row vector and this matrix
      Specified by:
        `leftMultiply` in class `Matrix`
      Parameters:
        `vec` - a vector over GF(2)
      Returns:
        Vector product a*matrix

    - #### leftMultiplyLeftCompactForm

          public Vector leftMultiplyLeftCompactForm(Vector vec)

      Compute the product of the matrix `(this | Id)` and a column vector, where `Id` is a `(numRows x numRows)` unit matrix.
      Parameters:
        `vec` - the vector over GF(2)
      Returns:
        `(this | Id)*vector`

    - #### rightMultiply

          public Matrix rightMultiply(Matrix mat)

      Compute the product of this matrix and a matrix A over GF(2).
      Specified by:
        `rightMultiply` in class `Matrix`
      Parameters:
        `mat` - a matrix A over GF(2)
      Returns:
        matrix product `this*matrixA`

    - #### rightMultiply

          public Matrix rightMultiply(Permutation p)

      Compute the product of this matrix and a permutation matrix which is generated from an n-permutation.
      Specified by:
        `rightMultiply` in class `Matrix`
      Parameters:
        `p` - the permutation
      Returns:
        `GF2Matrix` `this*P`

    - #### rightMultiply

          public Vector rightMultiply(Vector vec)

      Compute the product of this matrix and the given column vector.
      Specified by:
        `rightMultiply` in class `Matrix`
      Parameters:
        `vec` - the vector over GF(2)
      Returns:
        `this*vector`

    - #### rightMultiplyRightCompactForm

          public Vector rightMultiplyRightCompactForm(Vector vec)

      Compute the product of the matrix `(Id | this)` and a column vector, where `Id` is a `(numRows x numRows)` unit matrix.
      Parameters:
        `vec` - the vector over GF(2)
      Returns:
        `(Id | this)*vector`

    - #### equals

          public boolean equals(java.lang.Object other)

      Compare this matrix with another object.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `other` - another object
      Returns:
        the result of the comparison

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        the hash code of this matrix

    - #### toString

          public java.lang.String toString()

      Specified by:
        `toString` in class `Matrix`
      Returns:
        a human readable form of the matrix