Represents a matrix of elements of the given type T. More...

#include <maths/matrix.h>

Inheritance diagram for regina::Matrix< T, ring >:

Public Types
using	value_type = T
	The type of element that is stored in this matrix. More...

Public Member Functions
	Matrix ()
	Creates a new uninitialised matrix. More...

	Matrix (size_t size)
	Creates a new square matrix of the given size. More...

	Matrix (size_t rows, size_t cols)
	Creates a new matrix of the given size. More...

	Matrix (std::initializer_list< std::initializer_list< T > > data)
	Creates a new matrix containing the given hard-coded entries. More...

	Matrix (const Matrix &src)
	Creates a new matrix that is a clone of the given matrix. More...

	Matrix (Matrix &&src) noexcept
	Moves the given matrix into this new matrix. More...

	~Matrix ()
	Destroys this matrix. More...

Matrix &	operator= (const Matrix &src)
	Copies the given matrix into this matrix. More...

Matrix &	operator= (Matrix &&src) noexcept
	Moves the given matrix into this matrix. More...

void	initialise (const T &value)
	Sets every entry in the matrix to the given value. More...

void	swap (Matrix &other) noexcept
	Swaps the contents of this and the given matrix. More...

size_t	rows () const
	Returns the number of rows in this matrix. More...

size_t	columns () const
	Returns the number of columns in this matrix. More...

T &	entry (size_t row, size_t column)
	Returns a read-write reference to the entry at the given row and column. More...

const T &	entry (size_t row, size_t column) const
	Returns a read-only reference to the entry at the given row and column. More...

void	set (size_t row, size_t column, const T &value)
	Python-only routine that sets the entry at the given row and column. More...

Matrix< T >	transpose () const
	Returns the transpose of this matrix. More...

bool	operator== (const Matrix &other) const
	Determines whether this and the given matrix are identical. More...

bool	operator!= (const Matrix &other) const
	Determines whether this and the given matrix are different. More...

void	swapRows (size_t first, size_t second)
	Swaps the elements of the two given rows in the matrix. More...

void	swapCols (size_t first, size_t second, size_t fromRow=0)
	Swaps the elements of the two given columns in the matrix. More...

void	writeTextShort (std::ostream &out) const
	Writes a short text representation of this object to the given output stream. More...

void	writeTextLong (std::ostream &out) const
	Writes a detailed text representation of this object to the given output stream. More...

void	makeIdentity ()
	Turns this matrix into an identity matrix. More...

bool	isIdentity () const
	Determines whether this matrix is a square identity matrix. More...

bool	isZero () const
	Determines whether this is the zero matrix. More...

void	addRow (size_t source, size_t dest)
	Adds the given source row to the given destination row. More...

void	addRowFrom (size_t source, size_t dest, size_t fromCol)
	Adds a portion of the given source row to the given destination row. More...

void	addRow (size_t source, size_t dest, T copies, size_t fromCol=0)
	Adds the given number of copies of the given source row to the given destination row. More...

void	addCol (size_t source, size_t dest)
	Adds the given source column to the given destination column. More...

void	addColFrom (size_t source, size_t dest, size_t fromRow=0)
	Adds a portion of the given source column to the given destination column. More...

void	addCol (size_t source, size_t dest, T copies, size_t fromRow=0)
	Adds the given number of copies of the given source column to the given destination column. More...

void	multRow (size_t row, T factor, size_t fromCol=0)
	Multiplies the given row by the given factor. More...

void	multCol (size_t column, T factor, size_t fromRow=0)
	Multiplies the given column by the given factor. More...

void	combRows (size_t row1, size_t row2, T coeff11, T coeff12, T coeff21, T coeff22, size_t fromCol=0)
	Rewrites two rows as linear combinations of those two rows. More...

void	combCols (size_t col1, size_t col2, T coeff11, T coeff12, T coeff21, T coeff22, size_t fromRow=0)
	Rewrites two columns as linear combinations of those two columns. More...

template<typename U >
Matrix< decltype(T() *U())>	operator* (const Matrix< U, true > &other) const
	Multiplies this by the given matrix, and returns the result. More...

template<typename U >
Vector< decltype(T() *U())>	operator* (const Vector< U > &other) const
	Multiplies this matrix by the given vector, and returns the result. More...

T	det () const
	Evaluates the determinant of the matrix. More...

void	divRowExact (size_t row, const T &divBy)
	Divides all elements of the given row by the given integer. More...

void	divColExact (size_t col, const T &divBy)
	Divides all elements of the given column by the given integer. More...

T	gcdRow (size_t row)
	Computes the greatest common divisor of all elements of the given row. More...

T	gcdCol (size_t col)
	Computes the greatest common divisor of all elements of the given column. More...

void	reduceRow (size_t row)
	Reduces the given row by dividing all its elements by their greatest common divisor. More...

void	reduceCol (size_t col)
	Reduces the given column by dividing all its elements by their greatest common divisor. More...

size_t	rowEchelonForm ()
	Transforms this matrix into row echelon form. More...

size_t	columnEchelonForm ()
	Transforms this matrix into column echelon form. More...

std::string	str () const
	Returns a short text representation of this object. More...

std::string	utf8 () const
	Returns a short text representation of this object using unicode characters. More...

std::string	detail () const
	Returns a detailed text representation of this object. More...

Static Public Member Functions
static Matrix	identity (size_t size)
	Returns an identity matrix of the given size. More...

Detailed Description

template<class T, bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>
class regina::Matrix< T, ring >

Represents a matrix of elements of the given type T.

As of Regina 5.96, the old subclasses of Matrix have now been merged into a single Matrix class. The additional member functions that the old subclasses MatrixRing and MatrixIntDomain used to provide are now part of Matrix, and are enabled or disabled according to the Matrix template parameters.

It is generally safe to just use the type Matrix<T>, since the ring argument has a sensible default. At present, ring defaults to true (thereby enabling member functions designed for matrices over rings) when T is one of the following types:

native C++ integer types (i.e., where std::is_integral_v<T> is true and T is not bool); or
Regina's own types Integer, LargeInteger, NativeInteger<...>, and Rational.

Other types may be added to this list in future versions of Regina.

There are several requirements for the underlying type T. For all matrix types:

T must have a default constructor and an assignment operator.
An element t of type T must be writable to an output stream using the standard stream operator <<.

If ring is true, then in addition to this:

T must support binary operators +, - and *, and unary operators +=, -= and *=.
T must be able to be constructed or assigned to from the integers 0 and 1 (representing the additive and multiplicative identities in the ring respectively). Likewise, T must be able to be tested for equality or inequality against 0 or 1 also.

In particular, all of Regina's integer and rational types (Integer, LargeInteger, NativeInteger<...> and Rational) satisfy all of these requirements, and will set ring to true by default.

The header maths/matrixops.h contains several other algorithms that work with the specific class Matrix<Integer>.

This class implements C++ move semantics and adheres to the C++ Swappable requirement. It is designed to avoid deep copies wherever possible, even when passing or returning objects by value.

Python: Only the specific types Matrix<Integer> and Matrix<bool> are available, under the names MatrixInt and MatrixBool respectively.

Template Parameters

T	the type of each individual matrix element.
ring	`true` if we should enable member functions that only work when T represents an element of a ring. This has a sensible default; see above in the class documentation for details.

Member Typedef Documentation

◆ value_type

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

using regina::Matrix< T, ring >::value_type = T

The type of element that is stored in this matrix.

Constructor & Destructor Documentation

◆ Matrix() [1/6]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

regina::Matrix< T, ring >::Matrix ( )

inline

Creates a new uninitialised matrix.

You must initialise this matrix using the assignment operator before you can use it for any purpose. The only exceptions are:

you can safely destroy an uninitialised matrix;
you can safely assign an uninitialised matrix to another matrix (either via an assignment operator or copy constructor), in which case the other matrix will become uninitialised also and subject to similar constraints.

Python: Not present. This is because the C++ assignment operators are not accessible to Python.

◆ Matrix() [2/6]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

regina::Matrix< T, ring >::Matrix ( size_t size )

inline

Creates a new square matrix of the given size.

Both the number of rows and the number of columns will be set to size.

All entries will be initialised using their default constructors. In particular, this means that for Regina's own integer classes (Integer, LargeInteger and NativeInteger), all entries will be initialised to zero.

Warning: If T is a native C++ integer type (such as int or long), then the matrix elements will not be initialised to any particular value.

Precondition: The given size is strictly positive.

Parameters

size	the number of rows and columns in the new matrix.

◆ Matrix() [3/6]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

regina::Matrix< T, ring >::Matrix	(	size_t	rows,
		size_t	cols
	)

inline

Creates a new matrix of the given size.

All entries will be initialised using their default constructors. In particular, this means that for Regina's own integer classes (Integer, LargeInteger and NativeInteger), all entries will be initialised to zero.

Warning: If T is a native C++ integer type (such as int or long), then the matrix elements will not be initialised to any particular value.

Precondition: The given number of rows and columns are both strictly positive.

Parameters

rows	the number of rows in the new matrix.
cols	the number of columns in the new matrix.

◆ Matrix() [4/6]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

regina::Matrix< T, ring >::Matrix ( std::initializer_list< std::initializer_list< T > > data )

inline

Creates a new matrix containing the given hard-coded entries.

This constructor can be used (for example) to create hard-coded examples directly in C++ code.

Each element of the initialiser list data describes a single row of the matrix.

Precondition: The list data is non-empty (i.e., the number of rows is positive), and each of its elements is non-empty (i.e., the number of columns is positive).; All elements of data (representing the rows of the matrix) are lists of the same size.

Python: The argument data should be a Python list of Python lists.

Parameters

data	the rows of the matrix, each given as a list of elements.

◆ Matrix() [5/6]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

regina::Matrix< T, ring >::Matrix ( const Matrix< T, ring > & src )

inline

Creates a new matrix that is a clone of the given matrix.

This constructor induces a deep copy of src.

This routine is safe to call even if src is uninitialised (in which case this matrix will become uninitialised also).

Parameters

src	the matrix to clone.

◆ Matrix() [6/6]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

regina::Matrix< T, ring >::Matrix ( Matrix< T, ring > && src )

inlinenoexcept

Moves the given matrix into this new matrix.

This is a fast (constant time) operation.

The matrix that is passed (src) will no longer be usable.

This routine is safe to call even if src is uninitialised (in which case this matrix will become uninitialised also).

Parameters

src	the matrix to move.

◆ ~Matrix()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

regina::Matrix< T, ring >::~Matrix ( )

inline

Destroys this matrix.

This destructor is safe to call even if src is uninitialised.

Member Function Documentation

◆ addCol() [1/2]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::addCol	(	size_t	source,
		size_t	dest
	)

inline

Adds the given source column to the given destination column.

This routine is only available when the template argument ring is true.

Warning: If you only wish to add a portion of a column, be careful: you cannot just pass the usual fromRow argument, since this will be interpreted as a coefficient to be used with the other version of addCol() that adds several copies of the source column. Instead you will need to call addColFrom().

Precondition: The two given columns are distinct and between 0 and columns()-1 inclusive.

Parameters

source	the columns to add.
dest	the column that will be added to.

◆ addCol() [2/2]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::addCol	(	size_t	source,
		size_t	dest,
		T	copies,
		size_t	fromRow = `0`
	)

inline

Adds the given number of copies of the given source column to the given destination column.

Note that copies is passed by value in case it is an element of the row to be changed.

If the optional argument fromRow is passed, then the operation will only be performed for the elements from that row down to the bottom of the column (inclusive).

This routine is only available when the template argument ring is true.

Precondition: The two given columns are distinct and between 0 and columns()-1 inclusive.; If passed, fromRow is between 0 and rows() -1 inclusive.

Parameters

source	the columns to add.
dest	the column that will be added to.
copies	the number of copies of source to add to dest.
fromRow	the starting point in the column from which the operation will be performed.

◆ addColFrom()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::addColFrom	(	size_t	source,
		size_t	dest,
		size_t	fromRow = `0`
	)

inline

Adds a portion of the given source column to the given destination column.

This is similar to addCol(), except that the operation will only be performed for the elements from the row fromRow down to the bottom of the column (inclusive).

This routine is only available when the template argument ring is true.

Precondition: The two given columns are distinct and between 0 and columns()-1 inclusive.; If passed, fromRow is between 0 and rows() -1 inclusive.

Parameters

source	the columns to add.
dest	the column that will be added to.
fromRow	the starting point in the column from which the operation will be performed.

◆ addRow() [1/2]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::addRow	(	size_t	source,
		size_t	dest
	)

inline

Adds the given source row to the given destination row.

This routine is only available when the template argument ring is true.

Precondition: The two given rows are distinct and between 0 and rows()-1 inclusive.

Warning: If you only wish to add a portion of a row, be careful: you cannot just pass the usual fromCol argument, since this will be interpreted as a coefficient to be used with the other version of addRow() that adds several copies of the source row. Instead you will need to call addRowFrom().

Parameters

source	the row to add.
dest	the row that will be added to.

◆ addRow() [2/2]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::addRow	(	size_t	source,
		size_t	dest,
		T	copies,
		size_t	fromCol = `0`
	)

inline

Adds the given number of copies of the given source row to the given destination row.

Note that copies is passed by value in case it is an element of the row to be changed.

If the optional argument fromCol is passed, then the operation will only be performed for the elements from that column to the rightmost end of the row (inclusive).

This routine is only available when the template argument ring is true.

Precondition: The two given rows are distinct and between 0 and rows()-1 inclusive.; If passed, fromCol is between 0 and columns() -1 inclusive.

Parameters

source	the row to add.
dest	the row that will be added to.
copies	the number of copies of source to add to dest.
fromCol	the starting point in the row from which the operation will be performed.

◆ addRowFrom()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::addRowFrom	(	size_t	source,
		size_t	dest,
		size_t	fromCol
	)

inline

Adds a portion of the given source row to the given destination row.

This is similar to addRow(), except that the operation will only be performed for the elements from the column fromCol to the rightmost end of the row (inclusive).

This routine is only available when the template argument ring is true.

Precondition: The two given rows are distinct and between 0 and rows()-1 inclusive.; If passed, fromCol is between 0 and columns() -1 inclusive.

Parameters

source	the row to add.
dest	the row that will be added to.
fromCol	the starting point in the row from which the operation will be performed.

◆ columnEchelonForm()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

size_t regina::Matrix< T, ring >::columnEchelonForm ( )

inline

Transforms this matrix into column echelon form.

The transformation will perform only column operations.

This is simpler than the global routine regina::columnEchelonForm(): it does not return the change of basis matrices, and it processes all rows in order from left to right (instead of passing a custom row list).

Our convention is that a matrix is in column echelon form if:

each column is either zero or there is a first non-zero entry which is positive;
moving from the left column to the right, these first non-zero entries have strictly increasing row indices;
for each first non-zero column entry, in that row all the elements to the left are smaller and non-negative (and all elements to the right are already zero by the previous condition);
all the zero columns are at the right hand end of the matrix.

This routine is only available when T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).

Returns: the rank of this matrix, i.e., the number of non-zero columns remaining.

◆ columns()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

size_t regina::Matrix< T, ring >::columns ( ) const

inline

Returns the number of columns in this matrix.

Returns: the number of columns.

◆ combCols()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::combCols	(	size_t	col1,
		size_t	col2,
		T	coeff11,
		T	coeff12,
		T	coeff21,
		T	coeff22,
		size_t	fromRow = `0`
	)

inline

Rewrites two columns as linear combinations of those two columns.

Specifically, if C1 and C2 are the original values of columns col1 and col2 respectively, then:

Column col1 will become coeff11 * C1 + coeff12 * C2;
Column col2 will become coeff21 * C1 + coeff22 * C2.

The four coefficients are passed by value, in case they are elements of the columns to be changed.

If the optional argument fromRow is passed, then the operation will only be performed for the elements from that column down to the bottom of each column (inclusive).

This routine is only available when the template argument ring is true.

Precondition: The two given columns are distinct and between 0 and columns()-1 inclusive.; If passed, fromCol is between 0 and columns() -1 inclusive.

Parameters

col1	the first column to operate on.
col2	the second column to operate on.
coeff11	the coefficient of column col1 to use when rewriting column col1.
coeff12	the coefficient of column col2 to use when rewriting column col1.
coeff21	the coefficient of column col1 to use when rewriting column col2.
coeff22	the coefficient of column col2 to use when rewriting column col2.
fromRow	the starting point in the columns from which the operation will be performed.

◆ combRows()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::combRows	(	size_t	row1,
		size_t	row2,
		T	coeff11,
		T	coeff12,
		T	coeff21,
		T	coeff22,
		size_t	fromCol = `0`
	)

inline

Rewrites two rows as linear combinations of those two rows.

Specifically, if R1 and R2 are the original values of rows row1 and row2 respectively, then:

Row row1 will become coeff11 * R1 + coeff12 * R2;
Row row2 will become coeff21 * R1 + coeff22 * R2.

The four coefficients are passed by value, in case they are elements of the rows to be changed.

If the optional argument fromCol is passed, then the operation will only be performed for the elements from that column to the rightmost end of each row (inclusive).

This routine is only available when the template argument ring is true.

Precondition: The two given rows are distinct and between 0 and rows()-1 inclusive.; If passed, fromCol is between 0 and columns() -1 inclusive.

Parameters

row1	the first row to operate on.
row2	the second row to operate on.
coeff11	the coefficient of row row1 to use when rewriting row row1.
coeff12	the coefficient of row row2 to use when rewriting row row1.
coeff21	the coefficient of row row1 to use when rewriting row row2.
coeff22	the coefficient of row row2 to use when rewriting row row2.
fromCol	the starting point in the rows from which the operation will be performed.

◆ det()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

T regina::Matrix< T, ring >::det ( ) const

inline

Evaluates the determinant of the matrix.

This algorithm has quartic complexity, and uses the dynamic programming approach of Mahajan and Vinay. For further details, see Meena Mahajan and V. Vinay, "Determinant: Combinatorics, algorithms, and complexity", Chicago J. Theor. Comput. Sci., Vol. 1997, Article 5.

Although the Matrix class does not formally support empty matrices, if this is found to be a 0-by-0 matrix then the determinant returned will be 1.

This routine is only available when the template argument ring is true.

Precondition: This is a square matrix.

Exceptions

FailedPrecondition This matrix is not square.

Returns: the determinant of this matrix.

◆ detail()

std::string regina::Output< Matrix< T > , false >::detail ( ) const

inherited

Returns a detailed text representation of this object.

This text may span many lines, and should provide the user with all the information they could want. It should be human-readable, should not contain extremely long lines (which cause problems for users reading the output in a terminal), and should end with a final newline. There are no restrictions on the underlying character set.

Returns: a detailed text representation of this object.

◆ divColExact()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::divColExact	(	size_t	col,
		const T &	divBy
	)

inline

Divides all elements of the given column by the given integer.

This can only be used when the given integer divides into all column elements exactly (with no remainder). For the Integer class, this may be much faster than ordinary division.

This routine is only available when T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).

Precondition: The argument divBy is neither zero nor infinity, and none of the elements of the given column are infinity.; The argument divBy divides exactly into every element of the given column (i.e., it leaves no remainder).; The given column number is between 0 and columns()-1 inclusive.

Parameters

col	the index of the column whose elements should be divided by divBy.
divBy	the integer to divide each column element by.

◆ divRowExact()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::divRowExact	(	size_t	row,
		const T &	divBy
	)

inline

Divides all elements of the given row by the given integer.

This can only be used when the given integer divides into all row elements exactly (with no remainder). For the Integer class, this may be much faster than ordinary division.

This routine is only available when T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).

Precondition: The argument divBy is neither zero nor infinity, and none of the elements of the given row are infinity.; The argument divBy divides exactly into every element of the given row (i.e., it leaves no remainder).; The given row number is between 0 and rows()-1 inclusive.

Parameters

row	the index of the row whose elements should be divided by divBy.
divBy	the integer to divide each row element by.

◆ entry() [1/2]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

T & regina::Matrix< T, ring >::entry	(	size_t	row,
		size_t	column
	)

inline

Returns a read-write reference to the entry at the given row and column.

Rows and columns are numbered beginning at zero.

Python: In general, to assign values to matrix elements you should use the Python-only set() routine. This entry() routine does give read-write access to matrix elements in Python, but it does not allow them to be set using the assignment operator. In other words, code such as matrix.entry(r, c).negate() will work, but matrix.entry(r, c) = value will not; instead you will need to call matrix.set(r, c, value).

Parameters

row	the row of the desired entry; this must be between 0 and rows()-1 inclusive.
column	the column of the desired entry; this must be between 0 and columns()-1 inclusive.

Returns: a reference to the entry in the given row and column.

◆ entry() [2/2]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

const T & regina::Matrix< T, ring >::entry	(	size_t	row,
		size_t	column
	)		const

inline

Returns a read-only reference to the entry at the given row and column.

Rows and columns are numbered beginning at zero.

Parameters

row	the row of the desired entry; this must be between 0 and rows()-1 inclusive.
column	the column of the desired entry; this must be between 0 and columns()-1 inclusive.

Returns: a reference to the entry in the given row and column.

◆ gcdCol()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

T regina::Matrix< T, ring >::gcdCol ( size_t col )

inline

Computes the greatest common divisor of all elements of the given column.

The value returned is guaranteed to be non-negative.

This routine is only available when T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).

Precondition: The given column number is between 0 and columns()-1 inclusive.

Parameters

col	the index of the column whose gcd should be computed.

Returns: the greatest common divisor of all elements of this column.

◆ gcdRow()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

T regina::Matrix< T, ring >::gcdRow ( size_t row )

inline

Computes the greatest common divisor of all elements of the given row.

The value returned is guaranteed to be non-negative.

This routine is only available when T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).

Precondition: The given row number is between 0 and rows()-1 inclusive.

Parameters

row	the index of the row whose gcd should be computed.

Returns: the greatest common divisor of all elements of this row.

◆ identity()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

static Matrix regina::Matrix< T, ring >::identity ( size_t size )

inlinestatic

Returns an identity matrix of the given size.

The matrix returned will have size rows and size columns.

This routine is only available when the template argument ring is true.

Parameters

size	the number of rows and columns of the matrix to build.

Returns: an identity matrix of the given size.

◆ initialise()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::initialise ( const T & value )

inline

Sets every entry in the matrix to the given value.

Parameters

value the value to assign to each entry.

◆ isIdentity()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

bool regina::Matrix< T, ring >::isIdentity ( ) const

inline

Determines whether this matrix is a square identity matrix.

If this matrix is square, isIdentity() will return true if and only if the matrix has ones in the main diagonal and zeroes everywhere else.

If this matrix is not square, isIdentity() will always return false (even if makeIdentity() was called earlier).

This routine is only available when the template argument ring is true.

Returns: true if and only if this is a square identity matrix.

◆ isZero()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

bool regina::Matrix< T, ring >::isZero ( ) const

inline

Determines whether this is the zero matrix.

This routine is only available when the template argument ring is true.

Returns: true if and only if all entries in the matrix are zero.

◆ makeIdentity()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::makeIdentity ( )

inline

Turns this matrix into an identity matrix.

This matrix need not be square; after this routine it will have entry(r,c) equal to 1 if r == c and 0 otherwise.

This routine is only available when the template argument ring is true.

◆ multCol()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::multCol	(	size_t	column,
		T	factor,
		size_t	fromRow = `0`
	)

inline

Multiplies the given column by the given factor.

Note that factor is passed by value in case it is an element of the row to be changed.

If the optional argument fromRow is passed, then the operation will only be performed for the elements from that row down to the bottom of the column (inclusive).

This routine is only available when the template argument ring is true.

Precondition: The given column is between 0 and columns()-1 inclusive.; If passed, fromRow is between 0 and rows() -1 inclusive.

Parameters

column	the column to work with.
factor	the factor by which to multiply the given column.
fromRow	the starting point in the column from which the operation will be performed.

◆ multRow()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::multRow	(	size_t	row,
		T	factor,
		size_t	fromCol = `0`
	)

inline

Multiplies the given row by the given factor.

Note that factor is passed by value in case it is an element of the row to be changed.

If the optional argument fromCol is passed, then the operation will only be performed for the elements from that column to the rightmost end of the row (inclusive).

This routine is only available when the template argument ring is true.

Precondition: The given row is between 0 and rows()-1 inclusive.; If passed, fromCol is between 0 and columns() -1 inclusive.

Parameters

row	the row to work with.
factor	the factor by which to multiply the given row.
fromCol	the starting point in the row from which the operation will be performed.

◆ operator!=()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

bool regina::Matrix< T, ring >::operator!= ( const Matrix< T, ring > & other ) const

inline

Determines whether this and the given matrix are different.

Two matrices are different if either (i) their dimensions differ, or (ii) the corresponding elements of each matrix differ in at least one location.

Note that this routine can happily deal with two matrices of different dimensions (in which case it will always return true).

This routine returns true if and only if the equality operator (==) returns false.

Precondition: The type T provides an equality operator (==).

Parameters

other the matrix to compare with this.

Returns: true if the matrices are different as described above, or false otherwise.

◆ operator*() [1/2]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

template<typename U >

Matrix< decltype(T() *U())> regina::Matrix< T, ring >::operator* ( const Matrix< U, true > & other ) const

inline

Multiplies this by the given matrix, and returns the result.

This matrix is not changed.

The two matrices being multiplied may use different underlying types (e.g., you can multiply a matrix of LargeInteger objects with a matrix of native C++ long integers). The type of object that is stored in the resulting matrix will be deduced accordingly (specifically, it will be the type obtained by multiplying objects of types T and U using the binary multiplication operator).

This routine is only available when the template argument ring is true.

Precondition: The number of columns in this matrix equals the number of rows in the given matrix.

Parameters

other the other matrix to multiply this matrix by.

Returns: the product matrix this * other.

◆ operator*() [2/2]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

template<typename U >

Vector< decltype(T() *U())> regina::Matrix< T, ring >::operator* ( const Vector< U > & other ) const

inline

Multiplies this matrix by the given vector, and returns the result.

The given vector is treated as a column vector.

The matrix and vector may use different underlying types (e.g., you can multiply a matrix of LargeInteger objects with a vector of native C++ long integers). The type of object that is stored in the resulting vector will be deduced accordingly (specifically, it will be the type obtained by multiplying objects of types T and U using the binary multiplication operator).

This routine is only available when the template argument ring is true.

Precondition: The length of the given vector is precisely the number of columns in this matrix.

Parameters

other the vector to multiply this matrix by.

Returns: the product this * other, which will be a vector whose length is the number of rows in this matrix.

◆ operator=() [1/2]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

Matrix & regina::Matrix< T, ring >::operator= ( const Matrix< T, ring > & src )

inline

Copies the given matrix into this matrix.

It does not matter if this and the given matrix have different sizes; if they do then this matrix will be resized as a result.

This operator induces a deep copy of src.

This routine is safe to call even if src is uninitialised (in which case this matrix will become uninitialised also).

Parameters

src	the matrix to copy.

Returns: a reference to this matrix.

◆ operator=() [2/2]

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

Matrix & regina::Matrix< T, ring >::operator= ( Matrix< T, ring > && src )

inlinenoexcept

Moves the given matrix into this matrix.

This is a fast (constant time) operation.

It does not matter if this and the given matrix have different sizes; if they do then this matrix will be resized as a result.

The matrix that is passed (src) will no longer be usable.

This routine is safe to call even if src is uninitialised (in which case this matrix will become uninitialised also).

Parameters

src	the matrix to move.

Returns: a reference to this matrix.

◆ operator==()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

bool regina::Matrix< T, ring >::operator== ( const Matrix< T, ring > & other ) const

inline

Determines whether this and the given matrix are identical.

Two matrices are identical if and only if (i) their dimensions are the same, and (ii) the corresponding elements of each matrix are equal.

Note that this routine can happily deal with two matrices of different dimensions (in which case it will always return false).

This routine returns true if and only if the inequality operator (!=) returns false.

Precondition: The type T provides an equality operator (==).

Parameters

other the matrix to compare with this.

Returns: true if the matrices are equal as described above, or false otherwise.

◆ reduceCol()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::reduceCol ( size_t col )

inline

Reduces the given column by dividing all its elements by their greatest common divisor.

It is guaranteed that, if the column is changed at all, it will be divided by a positive integer.

This routine is only available when T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).

Precondition: The given column number is between 0 and columns()-1 inclusive.

Parameters

col	the index of the column to reduce.

◆ reduceRow()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::reduceRow ( size_t row )

inline

Reduces the given row by dividing all its elements by their greatest common divisor.

It is guaranteed that, if the row is changed at all, it will be divided by a positive integer.

This routine is only available when T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).

Precondition: The given row number is between 0 and rows()-1 inclusive.

Parameters

row	the index of the row to reduce.

◆ rowEchelonForm()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

size_t regina::Matrix< T, ring >::rowEchelonForm ( )

inline

Transforms this matrix into row echelon form.

The transformation will perform only row operations.

This is simpler than the global routine regina::columnEchelonForm(): it does not return the change of basis matrices, and it processes all columns in order from left to right (instead of passing a custom column list).

Our convention is that a matrix is in row echelon form if:

each row is either zero or there is a first non-zero entry which is positive;
moving from the top row to the bottom, these first non-zero entries have strictly increasing column indices;
for each first non-zero row entry, in that column all the elements above are smaller and non-negative (and all elements below are already zero by the previous condition);
all the zero rows are at the bottom of the matrix.

This routine is only available when T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).

Returns: the rank of this matrix, i.e., the number of non-zero rows remaining.

◆ rows()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

size_t regina::Matrix< T, ring >::rows ( ) const

inline

Returns the number of rows in this matrix.

Returns: the number of rows.

◆ set()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::set	(	size_t	row,
		size_t	column,
		const T &	value
	)

Python-only routine that sets the entry at the given row and column.

Rows and columns are numbered beginning at zero.

C++: Not present. For C++ users, entry() is used for both reading and writing: just write entry(row, column) = value.

Python: In general, to assign values to matrix elements you should use the syntax matrix.set(row, column, value). The entry() routine does give read-write access to matrix elements in Python, but it does not allow them to be set using the assignment operator. In other words, code such as matrix.entry(r, c).negate() will work, but matrix.entry(r, c) = value will not.

Parameters

row	the row of the entry to set; this must be between 0 and rows()-1 inclusive.
column	the column of the entry to set; this must be between 0 and columns()-1 inclusive.
value	the new entry to place in the given row and column.

◆ str()

std::string regina::Output< Matrix< T > , false >::str ( ) const

inherited

Returns a short text representation of this object.

This text should be human-readable, should use plain ASCII characters where possible, and should not contain any newlines.

Within these limits, this short text ouptut should be as information-rich as possible, since in most cases this forms the basis for the Python __str__() and __repr__() functions.

Python: The Python "stringification" function __str__() will use precisely this function, and for most classes the Python __repr__() function will incorporate this into its output.

Returns: a short text representation of this object.

◆ swap()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::swap ( Matrix< T, ring > & other )

inlinenoexcept

Swaps the contents of this and the given matrix.

Parameters

other the matrix whose contents are to be swapped with this.

◆ swapCols()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::swapCols	(	size_t	first,
		size_t	second,
		size_t	fromRow = `0`
	)

inline

Swaps the elements of the two given columns in the matrix.

This operation is linear time (unlike swapping rows, which is constant time).

If the optional argument fromRow is passed, then the operation will only be performed for the elements from that row down to the bottom of each column (inclusive).

Precondition: The two given columns are between 0 and columns()-1 inclusive.; If passed, fromRow is between 0 and rows() -1 inclusive.

Parameters

first	the first column to swap.
second	the second column to swap.
fromRow	the starting point in each column from which the operation will be performed.

◆ swapRows()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::swapRows	(	size_t	first,
		size_t	second
	)

inline

Swaps the elements of the two given rows in the matrix.

This operation is constant time (unlike swapping columns, which is linear time).

Unlike swapCols(), this operation does not take a fromCol argument. This is because swapping rows is already as fast possible (internally, just a single pointer swap), and so iterating along only part of the row would slow the routine down considerably.

Precondition: The two given rows are between 0 and rows()-1 inclusive.

Parameters

first	the first row to swap.
second	the second row to swap.

◆ transpose()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

Matrix< T > regina::Matrix< T, ring >::transpose ( ) const

inline

Returns the transpose of this matrix.

This matrix is not changed.

Returns: the transpose.

◆ utf8()

std::string regina::Output< Matrix< T > , false >::utf8 ( ) const

inherited

Returns a short text representation of this object using unicode characters.

Like str(), this text should be human-readable, should not contain any newlines, and (within these constraints) should be as information-rich as is reasonable.

Unlike str(), this function may use unicode characters to make the output more pleasant to read. The string that is returned will be encoded in UTF-8.

Returns: a short text representation of this object.

◆ writeTextLong()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::writeTextLong ( std::ostream & out ) const

inline

Writes a detailed text representation of this object to the given output stream.

Python: Not present. Use detail() instead.

Parameters

out	the output stream to which to write.

◆ writeTextShort()

template<class T , bool ring = ((std::is_integral_v<T> && ! std::is_same_v<T, bool>) || IsReginaInteger<T>::value || std::is_same_v<T, Rational>)>

void regina::Matrix< T, ring >::writeTextShort ( std::ostream & out ) const

inline

Writes a short text representation of this object to the given output stream.

Python: Not present. Use str() instead.

Parameters

out	the output stream to which to write.

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

algebra/abeliangroup.h
maths/matrix.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ value_type

Constructor & Destructor Documentation

◆ Matrix() [1/6]

◆ Matrix() [2/6]

◆ Matrix() [3/6]

◆ Matrix() [4/6]

◆ Matrix() [5/6]

◆ Matrix() [6/6]

◆ ~Matrix()

Member Function Documentation

◆ addCol() [1/2]

◆ addCol() [2/2]

◆ addColFrom()

◆ addRow() [1/2]

◆ addRow() [2/2]

◆ addRowFrom()

◆ columnEchelonForm()

◆ columns()

◆ combCols()

◆ combRows()

◆ det()

◆ detail()

◆ divColExact()

◆ divRowExact()

◆ entry() [1/2]

◆ entry() [2/2]

◆ gcdCol()

◆ gcdRow()

◆ identity()

◆ initialise()

◆ isIdentity()

◆ isZero()

◆ makeIdentity()

◆ multCol()

◆ multRow()

◆ operator!=()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ reduceCol()

◆ reduceRow()

◆ rowEchelonForm()

◆ rows()

◆ set()

◆ str()

◆ swap()

◆ swapCols()

◆ swapRows()

◆ transpose()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()