itpp::GF2mat Class Reference

Class for dense GF(2) matrices. More...

`#include <itpp/base/gf2mat.h>`

## Public Member Functions

| GF2mat ()
| Default constructor (gives an empty 1 x 1 matrix)
| GF2mat (int m, int n)
| Construct an empty (all-zero) m x n matrix.
| GF2mat (const GF2mat_sparse &X)
| Construct a dense GF(2) matrix from a sparse GF(2) matrix.
| GF2mat (const GF2mat_sparse &X, int m1, int n1, int m2, int n2)
| Constructor, from subset of sparse GF(2) matrix.
| GF2mat (const GF2mat_sparse &X, const ivec &columns)
| Constructor, from subset of sparse GF(2) matrix.
| GF2mat (const bvec &x, bool is_column=true)
| Create a dense GF(2) matrix from a single vector.
| GF2mat (const bmat &X)
| Create a dense GF(2) matrix from a bmat.
void | set_size (int m, int n, bool copy=false)
| Set size of GF(2) matrix. If copy = true, keep data before resizing.
GF2mat_sparse | sparsify () const
| Create a sparse GF(2) matrix from a dense GF(2) matrix.
bvec | bvecify () const
| Create a bvec from a GF(2) matrix (must have one column or one row)
bin | get (int i, int j) const
| Getting element.
bin | operator() (int i, int j) const
| Getting element.
void | set (int i, int j, bin s)
| Set element i,j to s (0 or 1)
void | addto_element (int i, int j, bin s)
| Add s (0 or 1) to element (i,j)
void | set_col (int j, bvec x)
| Set column j to a binary vector x.
void | set_row (int i, bvec x)
| Set row i to a binary vector x.
bool | is_zero () const
| Check whether the matrix is identical to zero.
void | swap_rows (int i, int j)
| Swap rows i and j.
void | swap_cols (int i, int j)
| Swap columns i and j.
void | permute_rows (ivec &perm, bool I)
| Multiply from left with permutation matrix (permute rows).
void | permute_cols (ivec &perm, bool I)
| Multiply a matrix from right with a permutation matrix (i.e., permute the columns).
GF2mat | transpose () const
| Transpose.
GF2mat | get_submatrix (int m1, int n1, int m2, int n2) const
| Submatrix from (m1,n1) to (m2,n2)
GF2mat | concatenate_horizontal (const GF2mat &X) const
| Concatenate horizontally (append X on the right side of matrix)
GF2mat | concatenate_vertical (const GF2mat &X) const
| Concatenate vertically (append X underneath)
bvec | get_row (int i) const
| Get row.
bvec | get_col (int j) const
| Get column.
double | density () const
| Compute the matrix density (fraction of elements equal to "1")
int | rows () const
| Get number of rows.
int | cols () const
| Get number of columns.
void | add_rows (int i, int j)
| Add (or equivalently, subtract) rows.
GF2mat | inverse () const
| Inversion.
int | row_rank () const
| Returns the number of linearly independent rows.
int | T_fact (GF2mat &T, GF2mat &U, ivec &P) const
| TXP factorization.
int | T_fact_update_bitflip (GF2mat &T, GF2mat &U, ivec &P, int rank, int r, int c) const
| TXP factorization update, when bit is flipped.
bool | T_fact_update_addcol (GF2mat &T, GF2mat &U, ivec &P, bvec newcol) const
| TXP factorization update, when column is added.
void | operator= (const GF2mat &X)
| Assignment operator.
bool | operator== (const GF2mat &X) const
| Check if equal.

## Friends

ITPP_EXPORT GF2mat | operator* (const GF2mat &X, const GF2mat &Y)
| Multiplication operator.
ITPP_EXPORT bvec | operator* (const GF2mat &X, const bvec &y)
| Multiplication operator with binary vector.
ITPP_EXPORT GF2mat | operator+ (const GF2mat &X, const GF2mat &Y)
| Addition operator.
ITPP_EXPORT std::ostream & | operator<< (std::ostream &os, const GF2mat &X)
| Output stream operator (plain text)
ITPP_EXPORT it_file & | operator<< (it_file &f, const GF2mat &X)
| Write the matrix to file.
ITPP_EXPORT it_ifile & | operator>> (it_ifile &f, GF2mat &X)
| Read the matrix from file.
ITPP_EXPORT GF2mat | mult_trans (const GF2mat &X, const GF2mat &Y)
| Multiplication X*Y' where X and Y are GF(2) matrices.

## Related Symbols

(Note that these are not member symbols.)
ITPP_EXPORT GF2mat | operator* (const GF2mat &X, const GF2mat &Y)
| GF(2) matrix multiplication.
ITPP_EXPORT bvec | operator* (const GF2mat &X, const bvec &y)
| GF(2) matrix multiplication with "regular" binary vector.
ITPP_EXPORT GF2mat | operator+ (const GF2mat &X, const GF2mat &Y)
| GF(2) matrix addition.
ITPP_EXPORT std::ostream & | operator<< (std::ostream &os, const GF2mat &X)
| Output stream (plain text) operator for dense GF(2) matrices.
ITPP_EXPORT GF2mat | gf2dense_eye (int m)
| GF(2) Identity matrix.
ITPP_EXPORT GF2mat | mult_trans (const GF2mat &X, const GF2mat &Y)
| Multiplication X*Y' where X and Y are GF(2) matrices.

## Detailed Description

Class for dense GF(2) matrices.

Author
  Erik G. Larsson

This class can be used as an alternative to `bmat` to represent GF(2) matrices. It extends the functionality of `bmat` in two ways:

- `GF2mat` makes more efficient use of computer memory than `bmat` (one bit in the matrix requires one bit of memory)
- `GF2mat` provides several functions for linear algebra and matrix factorizations

See also `GF2mat_sparse` which offers an efficient representation of sparse GF(2) matrices, and `GF2mat_sparse_alist` for a parameterized representation of sparse GF(2) matrices.

Definition at line 171 of file gf2mat.h.

## Constructor & Destructor Documentation

## GF2mat() [1/7]

itpp::GF2mat::GF2mat | ( |  | ) |

Default constructor (gives an empty 1 x 1 matrix)

Definition at line 288 of file gf2mat.cpp.

References itpp::Mat< Num_T >::clear(), and itpp::Mat< Num_T >::set_size().

Referenced by T_fact_update_addcol().

## GF2mat() [2/7]

itpp::GF2mat::GF2mat | ( | int | m,
|  | int | n
| ) |  |

Construct an empty (all-zero) m x n matrix.

Definition at line 281 of file gf2mat.cpp.

References itpp::Mat< Num_T >::clear(), and itpp::Mat< Num_T >::set_size().

## GF2mat() [3/7]

itpp::GF2mat::GF2mat | ( | const GF2mat_sparse & | X | ) |

Construct a dense GF(2) matrix from a sparse GF(2) matrix.

Definition at line 332 of file gf2mat.cpp.

References set(), and itpp::Mat< Num_T >::set_size().

## GF2mat() [4/7]

itpp::GF2mat::GF2mat | ( | const GF2mat_sparse & | X,
|  | int | m1,
|  | int | n1,
|  | int | m2,
|  | int | n2
| ) |  |

Constructor, from subset of sparse GF(2) matrix.

This constructor forms a dense GF(2) matrix from a subset (m1,n1) to (m2,n2) of a sparse GF(2) matrix

Definition at line 352 of file gf2mat.cpp.

References it_assert, set(), and itpp::Mat< Num_T >::set_size().

## GF2mat() [5/7]

itpp::GF2mat::GF2mat | ( | const GF2mat_sparse & | X,
|  | const ivec & | columns
| ) |  |

Constructor, from subset of sparse GF(2) matrix.

This constructor forms a dense GF(2) matrix from a subset of columns in sparse GF(2) matrix

Parameters

  X | matrix to copy from
  columns | subset of columns to copy

Definition at line 379 of file gf2mat.cpp.

References it_assert, itpp::length(), itpp::max(), itpp::min(), set(), and itpp::Mat< Num_T >::set_size().

## GF2mat() [6/7]

itpp::GF2mat::GF2mat | ( | const bvec & | x,
|  | bool | is_column = `true`
| ) |  |

Create a dense GF(2) matrix from a single vector.

Parameters

  x | The input vector
  is_column | A parameter that indicates whether the result should be a row vector (false), or a column vector (true - default)

Definition at line 294 of file gf2mat.cpp.

References itpp::Mat< Num_T >::clear(), itpp::length(), set(), and itpp::Mat< Num_T >::set_size().

## GF2mat() [7/7]

itpp::GF2mat::GF2mat | ( | const bmat & | X | ) |

Create a dense GF(2) matrix from a bmat.

Definition at line 319 of file gf2mat.cpp.

References itpp::Mat< Num_T >::clear(), set(), and itpp::Mat< Num_T >::set_size().

## Member Function Documentation

## set_size()

void itpp::GF2mat::set_size | ( | int | m,
|  | int | n,
|  | bool | copy = `false`
| ) |  |

Set size of GF(2) matrix. If copy = true, keep data before resizing.

Definition at line 406 of file gf2mat.cpp.

References itpp::Mat< Num_T >::clear(), and itpp::Mat< Num_T >::set_size().

## sparsify()

GF2mat_sparse itpp::GF2mat::sparsify | ( |  | ) | const

Create a sparse GF(2) matrix from a dense GF(2) matrix.

Definition at line 417 of file gf2mat.cpp.

References get(), and itpp::Sparse_Mat< T >::set().

## bvecify()

bvec itpp::GF2mat::bvecify | ( |  | ) | const

Create a bvec from a GF(2) matrix (must have one column or one row)

Definition at line 431 of file gf2mat.cpp.

References get(), and it_assert.

## get()

bin itpp::GF2mat::get | ( | int | i,
|  | int | j
| ) |  | const

inline

Getting element.

Definition at line 498 of file gf2mat.h.

References it_assert_debug.

Referenced by bvecify(), concatenate_horizontal(), density(), get_col(), get_row(), get_submatrix(), sparsify(), T_fact_update_bitflip(), and transpose().

## operator()()

bin itpp::GF2mat::operator() | ( | int | i,
|  | int | j
| ) |  | const

inline

Getting element.

Definition at line 229 of file gf2mat.h.

## set()

void itpp::GF2mat::set | ( | int | i,
|  | int | j,
|  | bin | s
| ) |  |

inline

Set element i,j to s (0 or 1)

Definition at line 505 of file gf2mat.h.

References it_assert_debug.

Referenced by gf2dense_eye(), GF2mat(), GF2mat(), GF2mat(), GF2mat(), GF2mat(), itpp::BLDPC_Generator::load(), set_col(), and set_row().

## addto_element()

void itpp::GF2mat::addto_element | ( | int | i,
|  | int | j,
|  | bin | s
| ) |  |

inline

Add s (0 or 1) to element (i,j)

Definition at line 490 of file gf2mat.h.

References it_assert_debug.

## set_col()

void itpp::GF2mat::set_col | ( | int | j,
|  | bvec | x
| ) |  |

Set column j to a binary vector x.

Definition at line 460 of file gf2mat.cpp.

References it_assert, itpp::length(), and set().

Referenced by permute_cols(), and swap_cols().

## set_row()

void itpp::GF2mat::set_row | ( | int | i,
|  | bvec | x
| ) |  |

Set row i to a binary vector x.

Definition at line 451 of file gf2mat.cpp.

References it_assert, itpp::length(), and set().

Referenced by T_fact_update_bitflip().

## is_zero()

bool itpp::GF2mat::is_zero | ( |  | ) | const

Check whether the matrix is identical to zero.

Definition at line 779 of file gf2mat.cpp.

## swap_rows()

void itpp::GF2mat::swap_rows | ( | int | i,
|  | int | j
| ) |  |

Swap rows i and j.

Definition at line 818 of file gf2mat.cpp.

References it_assert.

Referenced by itpp::BLDPC_Generator::construct(), T_fact(), T_fact_update_addcol(), and T_fact_update_bitflip().

## swap_cols()

void itpp::GF2mat::swap_cols | ( | int | i,
|  | int | j
| ) |  |

Swap columns i and j.

Definition at line 829 of file gf2mat.cpp.

References get_col(), it_assert, and set_col().

## permute_rows()

void itpp::GF2mat::permute_rows | ( | ivec & | perm,
|  | bool | I
| ) |  |

Multiply from left with permutation matrix (permute rows).

Parameters

  perm | Permutation vector
  I | Parameter that determines permutation. I=0: apply permutation, I=1: apply inverse permutation

Definition at line 980 of file gf2mat.cpp.

References itpp::Array< T >::data, it_assert, and itpp::length().

Referenced by inverse().

## permute_cols()

void itpp::GF2mat::permute_cols | ( | ivec & | perm,
|  | bool | I
| ) |  |

Multiply a matrix from right with a permutation matrix (i.e., permute the columns).

Parameters

  perm | Permutation vector
  I | Parameter that determines permutation. I=0: apply permutation, I=1: apply inverse permutation

Definition at line 964 of file gf2mat.cpp.

References it_assert, itpp::length(), and set_col().

## transpose()

GF2mat itpp::GF2mat::transpose | ( |  | ) | const

Transpose.

Definition at line 935 of file gf2mat.cpp.

References get().

Referenced by itpp::LDPC_Generator_Systematic::construct().

## get_submatrix()

GF2mat itpp::GF2mat::get_submatrix | ( | int | m1,
|  | int | n1,
|  | int | m2,
|  | int | n2
| ) |  | const

Submatrix from (m1,n1) to (m2,n2)

Definition at line 479 of file gf2mat.cpp.

References get(), and it_assert.

Referenced by itpp::BLDPC_Generator::save().

## concatenate_horizontal()

GF2mat itpp::GF2mat::concatenate_horizontal | ( | const GF2mat & | X | ) | const

Concatenate horizontally (append X on the right side of matrix)

Definition at line 519 of file gf2mat.cpp.

References get(), and it_assert.

## concatenate_vertical()

GF2mat itpp::GF2mat::concatenate_vertical | ( | const GF2mat & | X | ) | const

Concatenate vertically (append X underneath)

Definition at line 496 of file gf2mat.cpp.

References itpp::Array< T >::data, and it_assert.

Referenced by itpp::BLDPC_Generator::load().

## get_row()

bvec itpp::GF2mat::get_row | ( | int | i | ) | const

Get row.

Definition at line 540 of file gf2mat.cpp.

References get().

Referenced by itpp::BLDPC_Generator::save(), and T_fact_update_bitflip().

## get_col()

bvec itpp::GF2mat::get_col | ( | int | j | ) | const

Get column.

Definition at line 550 of file gf2mat.cpp.

References get().

Referenced by swap_cols().

## density()

double itpp::GF2mat::density | ( |  | ) | const

Compute the matrix density (fraction of elements equal to "1")

Definition at line 1018 of file gf2mat.cpp.

References get().

## rows()

int itpp::GF2mat::rows | ( |  | ) | const

inline

Get number of rows.

Definition at line 291 of file gf2mat.h.

Referenced by itpp::BLDPC_Generator::construct(), and T_fact_update_addcol().

## cols()

int itpp::GF2mat::cols | ( |  | ) | const

inline

Get number of columns.

Definition at line 294 of file gf2mat.h.

Referenced by itpp::BLDPC_Generator::construct(), itpp::LDPC_Generator_Systematic::encode(), and T_fact_update_addcol().

## add_rows()

void itpp::GF2mat::add_rows | ( | int | i,
|  | int | j
| ) |  |

Add (or equivalently, subtract) rows.

This function updates row i according to row_i = row_i+row_j

Parameters

  i | Row to add to. This row will be modified
  j | Row to add. This row will not be modified.

Definition at line 809 of file gf2mat.cpp.

References it_assert.

Referenced by itpp::BLDPC_Generator::construct(), inverse(), T_fact(), T_fact_update_addcol(), and T_fact_update_bitflip().

## inverse()

GF2mat itpp::GF2mat::inverse | ( |  | ) | const

Inversion.

The matrix must be invertible, otherwise the function will terminate with an error.

Definition at line 748 of file gf2mat.cpp.

References add_rows(), it_assert, permute_rows(), itpp::rank(), and T_fact().

## row_rank()

int itpp::GF2mat::row_rank | ( |  | ) | const

Returns the number of linearly independent rows.

Definition at line 771 of file gf2mat.cpp.

References itpp::rank(), and T_fact().

## T_fact()

int itpp::GF2mat::T_fact | ( | GF2mat & | T,
|  | GF2mat & | U,
|  | ivec & | P
| ) |  | const

TXP factorization.

Given X, compute a factorization of the form U=TXP, where U is upper triangular, T is square and invertible, and P is a permutation matrix. This is basically an "LU"-factorization, but not called so here because T is not necessarily lower triangular. The matrix X may have any dimension. The permutation matrix P is represented as a permutation vector.

The function returns the row rank of X. (If X is full row rank, then the number of rows is returned.)

The function uses Gaussian elimination combined with permutations. The computational complexity is O(m*m*n) for an m*n matrix.

Definition at line 561 of file gf2mat.cpp.

References add_rows(), itpp::floor_i(), gf2dense_eye(), it_info_debug, swap_rows(), and itpp::zeros_i().

Referenced by inverse(), and row_rank().

## T_fact_update_bitflip()

int itpp::GF2mat::T_fact_update_bitflip | ( | GF2mat & | T,
|  | GF2mat & | U,
|  | ivec & | P,
|  | int | rank,
|  | int | r,
|  | int | c
| ) |  | const

TXP factorization update, when bit is flipped.

Update upper triangular factor U in the TXP-factorization (U=TXP) when the bit at position (r,c) is changed (0->1 or 1->0). The purpose of this function is to avoid re-running a complete T-factorization when a single bit is changed. The function assumes that T, U, and P already exist and that U=TXP before the function is called. The function also assumes that the rank provided is correct. The function updates T, U and P these matrices. The function returns the new rank of the matrix after the bitflip.

Note
  T, U, P and the rank value supplied to the function must be correct one. This is not checked by the function (for reasons of efficiency).

The function works by performing permutations to bring the matrix to a form where the Gaussian eliminated can be restarted from the point (rank-1,rank-1). The function is very fast for matrices with close to full rank but it is generally slower for non-full rank matrices.

Definition at line 614 of file gf2mat.cpp.

References add_rows(), get(), get_row(), it_error, itpp::rank(), set_row(), and swap_rows().

## T_fact_update_addcol()

bool itpp::GF2mat::T_fact_update_addcol | ( | GF2mat & | T,
|  | GF2mat & | U,
|  | ivec & | P,
|  | bvec | newcol
| ) |  | const

TXP factorization update, when column is added.

Update upper triangular factor U in the T-factorization (U=TXP) when a column (newcol) is appended at the right side of the matrix. The purpose of this function is to avoid re-running a complete T-factorization when a column is added. The function ONLY adds the column if it improves the rank of the matrix (nothing is done otherwise). The function returns "true" if the column was added, and "false" otherwise.

Note
  This function does not actually add the column newcol to the GF2 matrix. It only checks whether doing so would increase the rank, and if this is the case, it updates the T-factorization. A typical calling sequence would be
  bool rank_will_improve = X.T_fact_update_addcol(T,U,perm,c);
  if (rank_will_improve) { X = X.concatenate_horizontal(c); }
  itpp::Array
  General array class.
  Definition array.h:105

The complexity is O(m^2) for an m*n matrix.

Definition at line 697 of file gf2mat.cpp.

References add_rows(), cols(), GF2mat(), it_assert, it_assert_debug, itpp::length(), rows(), itpp::Array< T >::set_length(), and swap_rows().

## operator=()

void itpp::GF2mat::operator= | ( | const GF2mat & | X | ) |

Assignment operator.

Definition at line 839 of file gf2mat.cpp.

References itpp::Array< T >::data.

## operator==()

bool itpp::GF2mat::operator== | ( | const GF2mat & | X | ) | const

Check if equal.

Definition at line 791 of file gf2mat.cpp.

References itpp::Array< T >::data, and it_assert.

## Friends And Related Symbol Documentation

## operator* [1/4]

ITPP_EXPORT GF2mat operator* | ( | const GF2mat & | X,
|  | const GF2mat & | Y
| ) |  |

friend

Multiplication operator.

Definition at line 847 of file gf2mat.cpp.

## operator* [2/4]

ITPP_EXPORT bvec operator* | ( | const GF2mat & | X,
|  | const bvec & | y
| ) |  |

friend

Multiplication operator with binary vector.

Definition at line 873 of file gf2mat.cpp.

## operator+ [1/2]

ITPP_EXPORT GF2mat operator+ | ( | const GF2mat & | X,
|  | const GF2mat & | Y
| ) |  |

friend

Addition operator.

Subtraction is not implemented because it is equivalent to addition.

Definition at line 948 of file gf2mat.cpp.

## operator<< [1/3]

ITPP_EXPORT std::ostream & operator<< | ( | std::ostream & | os,
|  | const GF2mat & | X
| ) |  |

friend

Output stream operator (plain text)

Definition at line 1001 of file gf2mat.cpp.

## operator<< [2/3]

ITPP_EXPORT it_file & operator<< | ( | it_file & | f,
|  | const GF2mat & | X
| ) |  |

friend

Write the matrix to file.

/relatesalso GF2mat /brief Write GF(2) matrix to file.

Definition at line 1032 of file gf2mat.cpp.

## operator>>

ITPP_EXPORT it_ifile & operator>> | ( | it_ifile & | f,
|  | GF2mat & | X
| ) |  |

friend

Read the matrix from file.

/relatesalso GF2mat /brief Read GF(2) matrix from file.

Definition at line 1050 of file gf2mat.cpp.

## mult_trans [1/2]

ITPP_EXPORT GF2mat mult_trans | ( | const GF2mat & | X,
|  | const GF2mat & | Y
| ) |  |

friend

Multiplication X*Y' where X and Y are GF(2) matrices.

Definition at line 903 of file gf2mat.cpp.

## operator*() [3/4]

ITPP_EXPORT GF2mat operator* | ( | const GF2mat & | X,
|  | const GF2mat & | Y
| ) |  |

related

GF(2) matrix multiplication.

Definition at line 847 of file gf2mat.cpp.

## operator*() [4/4]

ITPP_EXPORT bvec operator* | ( | const GF2mat & | X,
|  | const bvec & | y
| ) |  |

related

GF(2) matrix multiplication with "regular" binary vector.

Definition at line 873 of file gf2mat.cpp.

## operator+() [2/2]

ITPP_EXPORT GF2mat operator+ | ( | const GF2mat & | X,
|  | const GF2mat & | Y
| ) |  |

related

GF(2) matrix addition.

Definition at line 948 of file gf2mat.cpp.

## operator<<() [3/3]

ITPP_EXPORT std::ostream & operator<< | ( | std::ostream & | os,
|  | const GF2mat & | X
| ) |  |

related

Output stream (plain text) operator for dense GF(2) matrices.

Definition at line 1001 of file gf2mat.cpp.

## gf2dense_eye()

ITPP_EXPORT GF2mat gf2dense_eye | ( | int | m | ) |

related

GF(2) Identity matrix.

Definition at line 470 of file gf2mat.cpp.

References set().

Referenced by T_fact().

## mult_trans() [2/2]

ITPP_EXPORT GF2mat mult_trans | ( | const GF2mat & | X,
|  | const GF2mat & | Y
| ) |  |

related

Multiplication X*Y' where X and Y are GF(2) matrices.

Definition at line 903 of file gf2mat.cpp.

The documentation for this class was generated from the following files:

- itpp/base/gf2mat.h
- itpp/base/gf2mat.cpp

Generated on Mon Jun 10 2024 11:49:35 for IT++ by Doxygen 1.9.8