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

using	Coefficient = T
	Deprecated alias for the type of element that is stored in this matrix. More...

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

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

	Matrix (unsigned long rows, unsigned long 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	initialise (List allValues)
	A deprecated Python-only routine that fills the matrix with the given set of elements. More...

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

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

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

T &	entry (unsigned long row, unsigned long column)
	Returns the entry at the given row and column. More...

const T &	entry (unsigned long row, unsigned long column) const
	Returns 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	writeMatrix (std::ostream &out) const
	Deprecated function that writes a complete representation of the matrix to the given output stream. More...

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

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

void	swapColumns (unsigned long first, unsigned long second)
	Deprecated routine that 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 (unsigned long source, unsigned long dest)
	Adds the given source row to the given destination row. More...

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

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

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

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

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

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

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

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

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

Matrix	operator* (const Matrix &other) const
	Multiplies this by the given matrix, and returns the result. More...

Vector< T >	operator* (const Vector< T > &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 (unsigned long row, const T &divBy)
	Divides all elements of the given row by the given integer. More...

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

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

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

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

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

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

unsigned long	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 (unsigned long size)
	Returns an identity matrix of the given size. More...

Detailed Description

template<class T, bool ring = ((std::is_integral<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>
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<T>::value 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: Not present in general, although 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

◆ Coefficient

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

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

Deprecated alias for the type of element that is stored in this matrix.

Deprecated:: This has been renamed to value_type, for consistency with regina::Vector and the standard C++ container types.

◆ value_type

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

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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, since the C++ assignment operators are not accessible to Python.

◆ Matrix() [2/6]

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

regina::Matrix< T, ring >::Matrix ( unsigned long 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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

regina::Matrix< T, ring >::Matrix	(	unsigned long	rows,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::addCol	(	unsigned long	source,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::addCol	(	unsigned long	source,
		unsigned long	dest,
		T	copies,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::addColFrom	(	unsigned long	source,
		unsigned long	dest,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::addRow	(	unsigned long	source,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::addRow	(	unsigned long	source,
		unsigned long	dest,
		T	copies,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::addRowFrom	(	unsigned long	source,
		unsigned long	dest,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

unsigned long 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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

unsigned long 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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::combCols	(	unsigned long	col1,
		unsigned long	col2,
		T	coeff11,
		T	coeff12,
		T	coeff21,
		T	coeff22,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::combRows	(	unsigned long	row1,
		unsigned long	row2,
		T	coeff11,
		T	coeff12,
		T	coeff21,
		T	coeff22,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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.

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

Precondition: This is a square matrix.

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::divColExact	(	unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::divRowExact	(	unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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

inline

Returns the entry at the given row and column.

Rows and columns are numbered beginning at zero.

Precondition: row is between 0 and rows()-1 inclusive.; column is between 0 and columns()-1 inclusive.

Python: The entry() routine gives direct read-write access to matrix elements, but 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. To assign values to matrix elements, you should instead use the syntax matrix.set(row, column, value). This set() routine returns nothing, and is provided for python only (i.e., it is not part of the C++ calculation engine).

Parameters

row	the row of the desired entry.
column	the column of the desired entry.

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

◆ entry() [2/2]

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

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

inline

Returns the entry at the given row and column.

Rows and columns are numbered beginning at zero.

Precondition: row is between 0 and rows()-1 inclusive.; column is between 0 and columns()-1 inclusive.

Parameters

row	the row of the desired entry.
column	the column of the desired entry.

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

◆ gcdCol()

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

T regina::Matrix< T, ring >::gcdCol ( unsigned long 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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

T regina::Matrix< T, ring >::gcdRow ( unsigned long 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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

static Matrix regina::Matrix< T, ring >::identity ( unsigned long 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() [1/2]

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

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.

◆ initialise() [2/2]

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

void regina::Matrix< T, ring >::initialise ( List allValues )

A deprecated Python-only routine that fills the matrix with the given set of elements.

The argument allValues must be a Python list of length rows() * columns(). Its values will be inserted into the matrix row by row (i.e., the first row will be filled, then the second row, and so on).

Deprecated:: Use the list-based constructor instead, which is now available to Python users.

C++: Not available; this routine is for Python only.

Parameters

allValues the individual elements to place into the matrix.

◆ isIdentity()

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

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::multCol	(	unsigned long	column,
		T	factor,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::multRow	(	unsigned long	row,
		T	factor,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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

inline

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

This matrix is not changed.

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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

inline

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

The given vector is treated as a column vector.

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::reduceCol ( unsigned long 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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::reduceRow ( unsigned long 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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

unsigned long 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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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

inline

Returns the number of rows in this matrix.

Returns: the number of rows.

◆ 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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

void regina::Matrix< T, ring >::swapCols	(	unsigned long	first,
		unsigned long	second,
		unsigned long	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.

◆ swapColumns()

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

void regina::Matrix< T, ring >::swapColumns	(	unsigned long	first,
		unsigned long	second
	)

inline

Deprecated routine that swaps the elements of the two given columns in the matrix.

Deprecated:: This routine has been renamed to swapCols().

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

Parameters

first	the first column to swap.
second	the second column to swap.

◆ swapRows()

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

void regina::Matrix< T, ring >::swapRows	(	unsigned long	first,
		unsigned long	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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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.

◆ writeMatrix()

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

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

inline

Deprecated function that writes a complete representation of the matrix to the given output stream.

Each row will be written on a separate line with elements in each row separated by single spaces.

Deprecated:: This routine is identical to writeTextLong(). Call writeTextLong() instead, or detail() if you want the text representation in string form.

Python: Not present; use detail() instead.

Parameters

out	the output stream to which to write.

◆ writeTextLong()

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

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<T>::value && ! std::is_same<T, bool>::value) || IsReginaInteger<T>::value || std::is_same<T, Rational>::value)>

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

◆ Coefficient

◆ 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() [1/2]

◆ initialise() [2/2]

◆ isIdentity()

◆ isZero()

◆ makeIdentity()

◆ multCol()

◆ multRow()

◆ operator!=()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ reduceCol()

◆ reduceRow()

◆ rowEchelonForm()

◆ rows()

◆ str()

◆ swap()

◆ swapCols()

◆ swapColumns()

◆ swapRows()

◆ transpose()

◆ utf8()

◆ writeMatrix()

◆ writeTextLong()

◆ writeTextShort()