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

#include <maths/matrix.h>

Inheritance diagram for regina::Matrix< typename >:

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

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

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

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

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

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

template<typename U >
	Matrix (const Matrix< U > &src)
	Creates a new clone of the given matrix, which may hold objects of a different type.

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

	~Matrix ()
	Destroys this matrix.

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

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

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

void	initialise (const T &value)
	Deprecated function that sets every entry in the matrix to the given value.

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

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

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

bool	initialised () const
	Determines whether this matrix is initialised or uninitialised.

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

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

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

Matrix	transpose () const
	Returns the transpose of this matrix.

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

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

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

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

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

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

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

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

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

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

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.

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

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.

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.

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

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

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.

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.

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

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

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

void	negateRow (size_t row)
	Negates all elements in the given row.

void	negateCol (size_t col)
	Negates all elements in the given column.

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

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

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

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

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

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

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

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

size_t	rank () const &
	A non-destructive routine that returns the rank of this matrix whilst preserving the contents of the matrix.

size_t	rank () &&
	A destructive routine that returns the rank of this matrix.

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

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

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

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

Detailed Description

template<typename>
class regina::Matrix< typename >

Represents a matrix of elements of the given type T.

As of Regina 7.4, the extra boolean ring template parameter is gone; instead the relevant functions are only enabled in scenarios where T is a ring type (in particular, when the specialisation RingTraits<T> is available). Nowadays you should always just use the type Matrix<T>.

The header maths/matrixops.h contains several additional 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: The C++ types Matrix<Integer>, Matrix<bool> and Matrix<double> are available using the Python names MatrixInt, MatrixBool and MatrixReal respectively.

Template Parameters

T	the type of each individual matrix element. This type should have a default constructor and an assignment operator, and should be writeable to an output stream using the standard stream operator `<<`.

Member Typedef Documentation

◆ value_type

template<typename >

using regina::Matrix< typename >::value_type = T

The type of element that is stored in this matrix.

Constructor & Destructor Documentation

◆ Matrix() [1/7]

template<typename >

regina::Matrix< typename >::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;
you can safely call initialised() to test whether a matrix is initialised or not.

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

◆ Matrix() [2/7]

template<typename >

regina::Matrix< typename >::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/7]

template<typename >

regina::Matrix< typename >::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/7]

template<typename >

regina::Matrix< typename >::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/7]

template<typename >

regina::Matrix< typename >::Matrix ( const Matrix< typename > & 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/7]

template<typename >

template<typename U >

regina::Matrix< typename >::Matrix ( const Matrix< U > & src )

inlineexplicit

Creates a new clone of the given matrix, which may hold objects of a different type.

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

This constructor is marked as explicit in the hope of avoiding accidental (and unintentional) mixing of matrix classes.

Python: Not present.

Template Parameters

U	the type of object held by the given matrix src. It must be possible to assign an object of type U to an object of type T.

Parameters

src	the matrix to clone.

◆ Matrix() [7/7]

template<typename >

regina::Matrix< typename >::Matrix ( Matrix< typename > && 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<typename >

regina::Matrix< typename >::~Matrix ( )

inline

Destroys this matrix.

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

Member Function Documentation

◆ addCol() [1/2]

template<typename >

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

inline

Adds the given source column to the given destination column.

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: T is a ring type; in particular, the specialisation RingTraits<T> is available.; 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<typename >

void regina::Matrix< typename >::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).

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.; 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<typename >

void regina::Matrix< typename >::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).

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.; 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<typename >

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

inline

Adds the given source row to the given destination row.

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.; 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<typename >

void regina::Matrix< typename >::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).

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.; 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<typename >

void regina::Matrix< typename >::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).

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.; 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<typename >

size_t regina::Matrix< typename >::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.

Precondition: Type 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<typename >

size_t regina::Matrix< typename >::columns ( ) const

inline

Returns the number of columns in this matrix.

Returns: the number of columns.

◆ combCols()

template<typename >

void regina::Matrix< typename >::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).

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.; 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<typename >

void regina::Matrix< typename >::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).

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.; 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<typename >

T regina::Matrix< typename >::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.

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.; This is a square matrix.

Exceptions

FailedPrecondition This matrix is not square.

Returns: the determinant of this matrix.

◆ detail()

std::string regina::Output< 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<typename >

void regina::Matrix< typename >::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.

Precondition: Type T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).; 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<typename >

void regina::Matrix< typename >::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.

Precondition: Type T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).; 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<typename >

T & regina::Matrix< typename >::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<typename >

const T & regina::Matrix< typename >::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.

◆ fill()

template<typename >

void regina::Matrix< typename >::fill ( const T & value )

inline

Sets every entry in the matrix to the given value.

Parameters

value the value to assign to each entry.

◆ gcdCol()

template<typename >

T regina::Matrix< typename >::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.

Precondition: Type T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).; 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<typename >

T regina::Matrix< typename >::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.

Precondition: Type T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).; 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<typename >

static Matrix regina::Matrix< typename >::identity ( size_t size )

inlinestatic

Returns an identity matrix of the given size.

The matrix returned will have size rows and size columns.

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.

Parameters

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

Returns: an identity matrix of the given size.

◆ initialise()

template<typename >

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

inline

Deprecated function that sets every entry in the matrix to the given value.

Deprecated: This routine has been renamed to fill(), to make it clear that it has nothing to do with initialised versus uninitialised matrices.

Parameters

value the value to assign to each entry.

◆ initialised()

template<typename >

bool regina::Matrix< typename >::initialised ( ) const

inline

Determines whether this matrix is initialised or uninitialised.

The only ways for a matrix to be uninitialised are:

it was created using the default constructor, and has not yet been initialised using the assignment operator;
it was the result of assignment or copy construction from some other uninitialised matrix.

Returns: true if this matrix is initialised, or false if it is uninitialised.

◆ isIdentity()

template<typename >

bool regina::Matrix< typename >::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).

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.

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

◆ isZero()

template<typename >

bool regina::Matrix< typename >::isZero ( ) const

inline

Determines whether this is the zero matrix.

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.

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

◆ makeIdentity()

template<typename >

void regina::Matrix< typename >::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.

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.

◆ multCol()

template<typename >

void regina::Matrix< typename >::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).

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.; 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<typename >

void regina::Matrix< typename >::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).

Precondition: T is a ring type; in particular, the specialisation RingTraits<T> is available.; 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.

◆ negateCol()

template<typename >

void regina::Matrix< typename >::negateCol ( size_t col )

inline

Negates all elements in the given column.

Precondition: Type T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).; The given column number is between 0 and columns()-1 inclusive.

Parameters

col	the index of the column whose elements should be negated.

◆ negateRow()

template<typename >

void regina::Matrix< typename >::negateRow ( size_t row )

inline

Negates all elements in the given row.

Precondition: Type T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).; The given row number is between 0 and rows()-1 inclusive.

Parameters

row	the index of the row whose elements should be negated.

◆ operator*() [1/2]

template<typename >

template<typename U >

Matrix< decltype(T() *U())> regina::Matrix< typename >::operator* ( const Matrix< U > & 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).

Precondition: The element type E for the matrix that is returned is a ring type; in particular, the specialisation RingTraits<E> is available. (In many cases, E will just be the matrix element type T.); 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<typename >

template<typename U >

Vector< decltype(T() *U())> regina::Matrix< typename >::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).

Precondition: The element type E for the vector that is returned is a ring type; in particular, the specialisation RingTraits<E> is available. (In many cases, E will just be the matrix element type T.); 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<typename >

Matrix & regina::Matrix< typename >::operator= ( const Matrix< typename > & 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<typename >

Matrix & regina::Matrix< typename >::operator= ( Matrix< typename > && 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<typename >

bool regina::Matrix< typename >::operator== ( const Matrix< typename > & 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.

◆ rank() [1/2]

template<typename >

size_t regina::Matrix< typename >::rank ( ) &&

inline

A destructive routine that returns the rank of this matrix.

Here "destructive" means that this routine modifies the matrix directly as it performs the rank computation. For this reason, it is declared as an rvalue reference member function: it should only be used if you do not care about the contents of the matrix afterwards.

To use this destructive rank computation, you can call std::move(matrix).rank().

If you need to preserve the contents of the matrix, you should instead call the const version of this function, which you can simply access as matrix.rank(). The (minor) cost of this constness will be the extra overhead of an internal deep copy.

Precondition: Type T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).

Python: Not present. Only the const version of rank() is available for Python users.

Returns: the rank of this matrix.

◆ rank() [2/2]

template<typename >

size_t regina::Matrix< typename >::rank ( ) const &

inline

A non-destructive routine that returns the rank of this matrix whilst preserving the contents of the matrix.

Normally, a rank computation would involve modifying the matrix directly (e.g., by converting it to row echelon form). In contrast, this routine will leave the matrix unchanged. The cost is an extra deep copy in the implementation.

If your matrix is disposable (i.e., you will never need to use it again), then it is faster to use the rvalue reference version of this routine, which will avoid the extra overhead of the deep copy. To do this, replace matrix.rank() with std::move(matrix).rank().

Precondition: Type T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).

Python: Only the const version of rank() (i.e., this version) is available for Python users.

Returns: the rank of this matrix.

◆ reduceCol()

template<typename >

void regina::Matrix< typename >::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.

Precondition: Type T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).; The given column number is between 0 and columns()-1 inclusive.

Parameters

col	the index of the column to reduce.

◆ reduceRow()

template<typename >

void regina::Matrix< typename >::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.

Precondition: Type T is one of Regina's own integer classes (Integer, LargeInteger, or NativeIntgeger).; The given row number is between 0 and rows()-1 inclusive.

Parameters

row	the index of the row to reduce.

◆ rowEchelonForm()

template<typename >

size_t regina::Matrix< typename >::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.

Precondition: Type 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<typename >

size_t regina::Matrix< typename >::rows ( ) const

inline

Returns the number of rows in this matrix.

Returns: the number of rows.

◆ set()

template<typename >

void regina::Matrix< typename >::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< 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<typename >

void regina::Matrix< typename >::swap ( Matrix< typename > & 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<typename >

void regina::Matrix< typename >::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<typename >

void regina::Matrix< typename >::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<typename >

Matrix regina::Matrix< typename >::transpose ( ) const

inline

Returns the transpose of this matrix.

This matrix is not changed.

Returns: the transpose.

◆ utf8()

std::string regina::Output< 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<typename >

void regina::Matrix< typename >::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<typename >

void regina::Matrix< typename >::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
angle/anglestructure.h
enumerate/treelp.h
hypersurface/normalhypersurface.h
maths/matrix.h
snappea/snappeatriangulation.h
surface/normalsurface.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ value_type

Constructor & Destructor Documentation

◆ Matrix() [1/7]

◆ Matrix() [2/7]

◆ Matrix() [3/7]

◆ Matrix() [4/7]

◆ Matrix() [5/7]

◆ Matrix() [6/7]

◆ Matrix() [7/7]

◆ ~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]

◆ fill()

◆ gcdCol()

◆ gcdRow()

◆ identity()

◆ initialise()

◆ initialised()

◆ isIdentity()

◆ isZero()

◆ makeIdentity()

◆ multCol()

◆ multRow()

◆ negateCol()

◆ negateRow()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ rank() [1/2]

◆ rank() [2/2]

◆ reduceCol()

◆ reduceRow()

◆ rowEchelonForm()

◆ rows()

◆ set()

◆ str()

◆ swap()

◆ swapCols()

◆ swapRows()

◆ transpose()

◆ utf8()

◆ writeTextLong()

◆ writeTextShort()