Regina Calculation Engine
Classes | Typedefs | Functions | Variables
Mathematical Support

Underlying mathematical gruntwork. More...

Classes

class  regina::Cyclotomic
 Represents an element of a cyclotomic field. More...
 
class  regina::NativeInteger< bytes >
 A wrapper class for a native, fixed-precision integer type of the given size. More...
 
struct  regina::InfinityBase< supportInfinity >
 Internal base classes for use with IntegerBase, templated on whether we should support infinity as an allowed value. More...
 
class  regina::IntegerBase< supportInfinity >
 Represents an arbitrary precision integer. More...
 
class  regina::Matrix< T >
 Represents a matrix of elements of the given type T. More...
 
class  regina::MatrixRing< T >
 Represents a matrix of elements from a given ring T. More...
 
class  regina::MatrixIntDomain< T >
 Represents a matrix of elements from a given integral domain T. More...
 
class  regina::Matrix2
 Represents a 2-by-2 integer matrix. More...
 
class  regina::Perm< n >
 Represents a permutation of {0,1,...,n-1}. More...
 
class  regina::Polynomial< T >
 Represents a single-variable polynomial with coefficients of type T. More...
 
class  regina::Primes
 A helper class for finding primes and factorising integers. More...
 
class  regina::Rational
 Represents an arbitrary precision rational number. More...
 
class  regina::Ray
 A fast class for storing a ray rooted at the origin whose coordinates are rational. More...
 
class  regina::Perm< 2 >
 Represents a permutation of {0,1}. More...
 
class  regina::Perm< 3 >
 Represents a permutation of {0,1,2}. More...
 
class  regina::Perm< 4 >
 Represents a permutation of {0,1,2,3}. More...
 
class  regina::Perm< 5 >
 Represents a permutation of {0,1,2,3,4}. More...
 
class  regina::Vector< T >
 An optimised vector class of elements from a given ring T. More...
 

Typedefs

typedef Cyclotomic regina::NCyclotomic
 Deprecated typedef for backward compatibility. More...
 
typedef IntegerBase< true > regina::LargeInteger
 LargeInteger is a typedef for IntegerBase<true>, which offers arbitrary precision integers with support for infinity. More...
 
typedef IntegerBase< false > regina::Integer
 Integer is a typedef for IntegerBase<false>, which offers arbitrary precision integers without support for infinity. More...
 
typedef NativeInteger< sizeof(long)> regina::NNativeLong
 NNativeLong is a typedef for the NativeInteger template class whose underlying integer type is a native long. More...
 
typedef Integer regina::NInteger
 Deprecated typedef for backward compatibility. More...
 
typedef LargeInteger regina::NLargeInteger
 Deprecated typedef for backward compatibility. More...
 
template<int bytes>
using regina::NNativeInteger = NativeInteger< bytes >
 Deprecated typedef for backward compatibility. More...
 
template<class T >
using regina::NMatrix = Matrix< T >
 Deprecated typedef for backward compatibility. More...
 
template<class T >
using regina::NMatrixRing = MatrixRing< T >
 Deprecated typedef for backward compatibility. More...
 
typedef MatrixInt regina::NMatrixInt
 Deprecated typedef for backward compatibility. More...
 
typedef Matrix2 regina::NMatrix2
 Deprecated typedef for backward compatibility. More...
 
template<int n>
using regina::NPerm = Perm< n >
 Deprecated typedef for backward compatibility. More...
 
template<typename T >
using regina::NPolynomial = Polynomial< T >
 Deprecated typedef for backward compatibility. More...
 
typedef Primes regina::NPrimes
 Deprecated typedef for backward compatibility. More...
 
typedef Rational regina::NRational
 Deprecated typedef for backward compatibility. More...
 
typedef Ray regina::NRay
 Deprecated typedef for backward compatibility. More...
 
typedef Perm< 2 > regina::NPerm2
 Deprecated typedef for backward compatibility. More...
 
typedef Perm< 3 > regina::NPerm3
 Deprecated typedef for backward compatibility. More...
 
typedef Perm< 4 > regina::NPerm4
 Deprecated typedef for backward compatibility. More...
 
typedef Perm< 5 > regina::NPerm5
 Deprecated typedef for backward compatibility. More...
 
template<class T >
using regina::NVector = Vector< T >
 Deprecated typedef for backward compatibility. More...
 

Functions

template<class R >
bool regina::isZero (R x)
 Deprecated routine for managing floating-point roundoff errors. More...
 
template<class R >
bool regina::isNonZero (R x)
 Deprecated routine for managing floating-point roundoff errors. More...
 
template<class R >
bool regina::isPositive (R x)
 Deprecated routine for managing floating-point roundoff errors. More...
 
template<class R >
bool regina::isNegative (R x)
 Deprecated routine for managing floating-point roundoff errors. More...
 
template<class R >
bool regina::isNonNegative (R x)
 Deprecated routine for managing floating-point roundoff errors. More...
 
template<class R >
bool regina::isNonPositive (R x)
 Deprecated routine for managing floating-point roundoff errors. More...
 
template<bool supportInfinity>
std::ostream & regina::operator<< (std::ostream &out, const IntegerBase< supportInfinity > &i)
 Writes the given integer to the given output stream. More...
 
template<bool supportInfinity>
IntegerBase< supportInfinity > regina::operator+ (long lhs, const IntegerBase< supportInfinity > &rhs)
 Adds the given native integer to the given large integer. More...
 
template<bool supportInfinity>
IntegerBase< supportInfinity > regina::operator* (long lhs, const IntegerBase< supportInfinity > &rhs)
 Multiplies the given native integer with the given large integer. More...
 
template<int bytes>
std::ostream & regina::operator<< (std::ostream &out, const NativeInteger< bytes > &i)
 Writes the given integer to the given output stream. More...
 
std::ostream & regina::operator<< (std::ostream &out, const Matrix2 &mat)
 Writes the given matrix to the given output stream. More...
 
bool regina::simpler (const Matrix2 &m1, const Matrix2 &m2)
 Determines whether the first given matrix is more aesthetically pleasing than the second. More...
 
bool regina::simpler (const Matrix2 &pair1first, const Matrix2 &pair1second, const Matrix2 &pair2first, const Matrix2 &pair2second)
 Determines whether the first given pair of matrices is more aesthetically pleasing than the second pair. More...
 
void regina::smithNormalForm (MatrixInt &matrix)
 Transforms the given integer matrix into Smith normal form. More...
 
void regina::smithNormalForm (MatrixInt &matrix, MatrixInt &rowSpaceBasis, MatrixInt &rowSpaceBasisInv, MatrixInt &colSpaceBasis, MatrixInt &colSpaceBasisInv)
 A Smith normal form algorithm that also returns change of basis matrices. More...
 
void regina::metricalSmithNormalForm (MatrixInt &matrix, MatrixInt *rowSpaceBasis=0, MatrixInt *rowSpaceBasisInv=0, MatrixInt *colSpaceBasis=0, MatrixInt *colSpaceBasisInv=0)
 An alternative Smith normal form algorithm that also returns change of basis matrices. More...
 
unsigned regina::rowBasis (MatrixInt &matrix)
 Find a basis for the row space of the given matrix. More...
 
unsigned regina::rowBasisAndOrthComp (MatrixInt &input, MatrixInt &complement)
 Finds a basis for the row space of the given matrix, as well as an "incremental" basis for its orthogonal complement. More...
 
void regina::columnEchelonForm (MatrixInt &M, MatrixInt &R, MatrixInt &Ri, const std::vector< unsigned > &rowList)
 Transforms a given matrix into column echelon form with respect to a collection of rows. More...
 
std::unique_ptr< MatrixIntregina::preImageOfLattice (const MatrixInt &hom, const std::vector< Integer > &sublattice)
 Given a homomorphism from Z^n to Z^k and a sublattice of Z^k, compute the preimage of this sublattice under this homomorphism. More...
 
std::unique_ptr< MatrixIntregina::torsionAutInverse (const MatrixInt &input, const std::vector< Integer > &invF)
 Given an automorphism of an abelian group, this procedure computes the inverse automorphism. More...
 
long regina::reducedMod (long k, long modBase)
 Reduces k modulo modBase to give the smallest possible absolute value. More...
 
long regina::gcd (long a, long b)
 Calculates the greatest common divisor of two signed integers. More...
 
long regina::gcdWithCoeffs (long a, long b, long &u, long &v)
 Calculates the greatest common divisor of two given integers and finds the smallest coefficients with which these integers combine to give their gcd. More...
 
long regina::lcm (long a, long b)
 Calculates the lowest common multiple of two signed integers. More...
 
unsigned long regina::modularInverse (unsigned long n, unsigned long k)
 Calculates the multiplicative inverse of one integer modulo another. More...
 
constexpr char regina::digit (int i)
 Returns the character used to express the integer i in a permutation. More...
 
constexpr int64_t regina::factorial (int n)
 Returns the factorial of n. More...
 
template<int n>
std::ostream & regina::operator<< (std::ostream &out, const Perm< n > &p)
 Writes a string representation of the given permutation to the given output stream. More...
 
std::ostream & regina::operator<< (std::ostream &out, const Rational &rat)
 Writes the given rational to the given output stream. More...
 
template<class T >
std::ostream & regina::operator<< (std::ostream &out, const Vector< T > &vector)
 Writes the given vector to the given output stream. More...
 

Variables

const double regina::epsilon
 Deprecated constant for managing floating-point roundoff errors. More...
 
static T regina::Vector< T >::zero
 Zero in the underlying number system. More...
 
static T regina::Vector< T >::one
 One in the underlying number system. More...
 
static T regina::Vector< T >::minusOne
 Negative one in the underlying number system. More...
 

Detailed Description

Underlying mathematical gruntwork.

Typedef Documentation

◆ Integer

typedef IntegerBase<false> regina::Integer

Integer is a typedef for IntegerBase<false>, which offers arbitrary precision integers without support for infinity.

Python:
This typedef is available in Python.

◆ LargeInteger

LargeInteger is a typedef for IntegerBase<true>, which offers arbitrary precision integers with support for infinity.

Python:
This typedef is available in Python.

◆ NCyclotomic

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NCyclotomic has now been renamed to Cyclotomic.

◆ NInteger

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NInteger has now been renamed to Integer.

◆ NLargeInteger

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NLargeInteger has now been renamed to LargeInteger.

◆ NMatrix

template<class T >
using regina::NMatrix = typedef Matrix<T>

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NMatrix has now been renamed to Matrix.

◆ NMatrix2

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NMatrix2 has now been renamed to Matrix2.

◆ NMatrixInt

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NMatrixInt has now been renamed to MatrixInt.

◆ NMatrixRing

template<class T >
using regina::NMatrixRing = typedef MatrixRing<T>

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NMatrixRing has now been renamed to MatrixRing.

◆ NNativeInteger

template<int bytes>
using regina::NNativeInteger = typedef NativeInteger<bytes>

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NNativeInteger has now been renamed to NativeInteger.

◆ NNativeLong

typedef NativeInteger<sizeof(long)> regina::NNativeLong

NNativeLong is a typedef for the NativeInteger template class whose underlying integer type is a native long.

Python:
Not present.

◆ NPerm

template<int n>
using regina::NPerm = typedef Perm<n>

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NPerm has now been renamed to Perm.

◆ NPerm2

typedef Perm<2> regina::NPerm2

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NPerm2 has now been renamed to Perm<2>.

◆ NPerm3

typedef Perm<3> regina::NPerm3

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NPerm3 has now been renamed to Perm<3>.

◆ NPerm4

typedef Perm<4> regina::NPerm4

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NPerm4 has now been renamed to Perm<4>.

◆ NPerm5

typedef Perm<5> regina::NPerm5

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NPerm5 has now been renamed to Perm<5>.

◆ NPolynomial

template<typename T >
using regina::NPolynomial = typedef Polynomial<T>

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NPolynomial has now been renamed to Polynomial.

◆ NPrimes

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NPrimes has now been renamed to Primes.

◆ NRational

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NRational has now been renamed to Rational.

◆ NRay

typedef Ray regina::NRay

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NRay has now been renamed to Ray.

◆ NVector

template<class T >
using regina::NVector = typedef Vector<T>

Deprecated typedef for backward compatibility.

This typedef will be removed in a future release of Regina.

Deprecated:
The class NVector has now been renamed to Vector.

Function Documentation

◆ columnEchelonForm()

void regina::columnEchelonForm ( MatrixInt M,
MatrixInt R,
MatrixInt Ri,
const std::vector< unsigned > &  rowList 
)

Transforms a given matrix into column echelon form with respect to a collection of rows.

Given the matrix M and the list rowList of rows from M, this algorithm puts M in column echelon form with respect to the rows in rowList. The only purpose of rowList is to clarify and/or weaken precisely what is meant by "column echelon form"; all rows of M are affected by the resulting column operations that take place.

This routine also returns the corresponding change of coordinate matrices R and Ri:

  • If R and Ri are passed as identity matrices, the returned matrices will be such that original_M * R = final_M and final_M * Ri = original_M (and of course final_M is in column echelon form with respect to the given row list).
  • If R and Ri are already non-trivial coordinate transformations, they are modified appropriately by the algorithm.

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

  1. each column is either zero or there is a first non-zero entry which is positive (but see the note regarding rowList below);
  2. moving from the leftmost column to the rightmost column, the rows containing the first non-zero entries for these columns have strictly increasing indices in rowList;
  3. given a first non-zero column entry, in that row all the elements to the left are smaller and non-negative (all elements to the right are already zero by the previous condition);
  4. all the zero columns are on the right hand side of the matrix.

By a "zero column" here we simply mean "zero for every row in \a rowList". Likewise, by "first non-zero entry" we mean "first row in \a rowList with a non-zero entry".

In a pinch, you can also use this routine to compute the inverse of an invertible square matrix.

Precondition
Both R and Ri are square matrices with side length M.columns(), and these matrices are inverses of each other.
Python:
The argument rowList should be supplied as a python list.
Parameters
Mthe matrix to reduce.
Rused to return the row-reduction matrix, as described above.
Riused to return the inverse of R.
rowListthe rows to pay attention to. This list must contain distinct integers, all between 0 and M.rows()-1 inclusive. The integers may appear in any order (though changing the order will change the resulting column echelon form).
Author
Ryan Budney

◆ digit()

constexpr char regina::digit ( int  i)
inline

Returns the character used to express the integer i in a permutation.

  • For i = 0,...,9, this will be the usual digit representing i.
  • For i ≥ 10, this will be a lower-case letter. In particular, for i = 10,...,15, this will be the usual hexadecimal digit representing i.
  • At present, this routine only supports integers i < 36.
Parameters
ithe integer to represent; this must be between 0 and 35 inclusive.
Returns
the single character used to represent i.

◆ factorial()

constexpr int64_t regina::factorial ( int  n)
inline

Returns the factorial of n.

Parameters
nany non-negative integer; this must be at most 20 (since otherwise the factorial will overflow).
Returns
the factorial of n..

◆ gcd()

long regina::gcd ( long  a,
long  b 
)

Calculates the greatest common divisor of two signed integers.

This routine is not recursive.

Although the arguments may be negative, the result is guaranteed to be non-negative. As a special case, gcd(0,0) is considered to be zero.

Parameters
aone of the two integers to work with.
bthe other integer with which to work.
Returns
the greatest common divisor of a and b.

◆ gcdWithCoeffs()

long regina::gcdWithCoeffs ( long  a,
long  b,
long &  u,
long &  v 
)

Calculates the greatest common divisor of two given integers and finds the smallest coefficients with which these integers combine to give their gcd.

This routine is not recursive.

Note that the given integers need not be non-negative. However, the gcd returned is guaranteed to be non-negative. As a special case, gcd(0,0) is considered to be zero.

If d is the gcd of a and b, the values placed in u and v will be those for which u*a + v*b = d, -abs(a)/d < v*sign(b) <= 0 and 1 <= u*sign(a) <= abs(b)/d.

In the special case where one of the given integers is zero, the corresponding coefficient will also be zero and the other coefficient will be 1 or -1 so that u*a + v*b = d still holds. If both given integers are zero, both of the coefficients will be set to zero.

Parameters
aone of the integers to work with.
bthe other integer with which to work.
ua variable into which the final coefficient of a will be placed.
va variable into which the final coefficient of b will be placed.
Returns
the greatest common divisor of a and b.

◆ isNegative()

template<class R >
bool regina::isNegative ( x)
inline

Deprecated routine for managing floating-point roundoff errors.

Determines whether the given real number is strictly negative. Any number within regina::epsilon of zero is considered to be zero.

Precondition
R must be of a floating point real type.
Deprecated:
This method of using a hard-coded epsilon is very blunt. Currently Regina does not provide alternative methods for managing round-off error, though since Regina's computations are exact, this should not be necessary.
Python:
Not present.
Parameters
xthe number to examine.
Returns
true if and only if the given number is strictly negative.

◆ isNonNegative()

template<class R >
bool regina::isNonNegative ( x)
inline

Deprecated routine for managing floating-point roundoff errors.

Determines whether the given real number is non-negative. Any number within regina::epsilon of zero is considered to be zero.

Precondition
R must be of a floating point real type.
Deprecated:
This method of using a hard-coded epsilon is very blunt. Currently Regina does not provide alternative methods for managing round-off error, though since Regina's computations are exact, this should not be necessary.
Python:
Not present.
Parameters
xthe number to examine.
Returns
true if and only if the given number is non-negative.

◆ isNonPositive()

template<class R >
bool regina::isNonPositive ( x)
inline

Deprecated routine for managing floating-point roundoff errors.

Determines whether the given real number is non-positive. Any number within regina::epsilon of zero is considered to be zero.

Precondition
R must be of a floating point real type.
Deprecated:
This method of using a hard-coded epsilon is very blunt. Currently Regina does not provide alternative methods for managing round-off error, though since Regina's computations are exact, this should not be necessary.
Python:
Not present.
Parameters
xthe number to examine.
Returns
true if and only if the given number is non-positive.

◆ isNonZero()

template<class R >
bool regina::isNonZero ( x)
inline

Deprecated routine for managing floating-point roundoff errors.

Determines whether the given real number is non-zero. Any number within regina::epsilon of zero is considered to be zero.

Precondition
R must be of a floating point real type.
Deprecated:
This method of using a hard-coded epsilon is very blunt. Currently Regina does not provide alternative methods for managing round-off error, though since Regina's computations are exact, this should not be necessary.
Python:
Not present.
Parameters
xthe number to examine.
Returns
true if and only if the given number is approximately non-zero.

◆ isPositive()

template<class R >
bool regina::isPositive ( x)
inline

Deprecated routine for managing floating-point roundoff errors.

Determines whether the given real number is strictly positive. Any number within regina::epsilon of zero is considered to be zero.

Precondition
R must be of a floating point real type.
Deprecated:
This method of using a hard-coded epsilon is very blunt. Currently Regina does not provide alternative methods for managing round-off error, though since Regina's computations are exact, this should not be necessary.
Python:
Not present.
Parameters
xthe number to examine.
Returns
true if and only if the given number is strictly positive.

◆ isZero()

template<class R >
bool regina::isZero ( x)
inline

Deprecated routine for managing floating-point roundoff errors.

Determines whether the given real number is zero. Any number within regina::epsilon of zero is considered to be zero.

Precondition
R must be of a floating point real type.
Deprecated:
This method of using a hard-coded epsilon is very blunt. Currently Regina does not provide alternative methods for managing round-off error, though since Regina's computations are exact, this should not be necessary.
Python:
Not present.
Parameters
xthe number to examine.
Returns
true if and only if the given number is approximately zero.

◆ lcm()

long regina::lcm ( long  a,
long  b 
)

Calculates the lowest common multiple of two signed integers.

Although the arguments may be negative, the result is guaranteed to be non-negative.

If either of the arguments is zero, the return value will also be zero.

Regarding possible overflow: This routine does not create any temporary integers that are larger than the final LCM.

Parameters
aone of the two integers to work with.
bthe other integer with which to work.
Returns
the lowest common multiple of a and b.

◆ metricalSmithNormalForm()

void regina::metricalSmithNormalForm ( MatrixInt matrix,
MatrixInt rowSpaceBasis = 0,
MatrixInt rowSpaceBasisInv = 0,
MatrixInt colSpaceBasis = 0,
MatrixInt colSpaceBasisInv = 0 
)

An alternative Smith normal form algorithm that also returns change of basis matrices.

This routine may be preferable for extremely large matrices. This is a variant of Hafner-McCurley and Havas-Holt-Rees's description of pivoting methods.

The only input argument is matrix. The four remaining arguments (the change of basis matrices), if passed, will be refilled, though they must be constructed with the correct dimensions as seen in the preconditions below. All five arguments are used to return information as follows.

Let M be the initial value of matrix, and let S be the Smith normal form of M. After this routine exits:

  • The argument matrix will contain the Smith normal form S;
  • colSpaceBasis * M * rowSpaceBasis = S;
  • colSpaceBasisInv * S * rowSpaceBasisInv = M;
  • colSpaceBasis * colSpaceBasisInv and rowSpaceBasis * rowSpaceBasisInv are both identity matrices.

Thus, one obtains the Smith normal form the original matrix by multiplying on the left by ColSpaceBasis and on the right by RowSpaceBasis.

Precondition
The matrices rowSpaceBasis and rowSpaceBasisInv, if passed, must be square with side length matrix.columns().
The matrices colSpaceBasis and colSpaceBasisInv, if passed, must be square, with side length matrix.rows().
Parameters
matrixthe original matrix to put into Smith Normal Form (this need not be square). When the algorithm terminates, this matrix is in its Smith Normal Form.
rowSpaceBasisused to return a change of basis matrix (see above for details). This is optional; you may pass a null pointer instead.
rowSpaceBasisInvused to return the inverse of rowSpaceBasis. This is optional; you may pass a null pointer instead.
colSpaceBasisused to return a change of basis matrix (see above for details). This is optional; you may pass a null pointer instead.
colSpaceBasisInvused to return the inverse of colSpaceBasis. This is optional; you may pass a null pointer instead.
Author
Ryan Budney

◆ modularInverse()

unsigned long regina::modularInverse ( unsigned long  n,
unsigned long  k 
)

Calculates the multiplicative inverse of one integer modulo another.

The inverse returned will be between 0 and n-1 inclusive.

Precondition
n and k are both strictly positive;
n and k have no common factors.
Parameters
nthe modular base in which to work.
kthe number whose multiplicative inverse should be found.
Returns
the inverse v for which k * v == 1 (mod n).

◆ operator*()

template<bool supportInfinity>
IntegerBase< supportInfinity > regina::operator* ( long  lhs,
const IntegerBase< supportInfinity > &  rhs 
)
inline

Multiplies the given native integer with the given large integer.

If the large integer is infinite, the result will also be infinity.

Python:
Not available.
Parameters
lhsthe native integer to multiply.
rhsthe large integer to multiply.
Returns
the product lhs times rhs.

◆ operator+()

template<bool supportInfinity>
IntegerBase< supportInfinity > regina::operator+ ( long  lhs,
const IntegerBase< supportInfinity > &  rhs 
)
inline

Adds the given native integer to the given large integer.

If the large integer is infinite, the result will also be infinity.

Python:
Not available.
Parameters
lhsthe native integer to add.
rhsthe large integer to add.
Returns
the sum lhs plus rhs.

◆ operator<<() [1/6]

std::ostream & regina::operator<< ( std::ostream &  out,
const Matrix2 mat 
)
inline

Writes the given matrix to the given output stream.

The matrix will be written entirely on a single line, with the first row followed by the second row.

Parameters
outthe output stream to which to write.
matthe matrix to write.
Returns
a reference to out.

◆ operator<<() [2/6]

template<class T >
std::ostream& regina::operator<< ( std::ostream &  out,
const Vector< T > &  vector 
)

Writes the given vector to the given output stream.

The vector will be written on a single line with elements separated by a single space. No newline will be written.

Python:
Not present.
Parameters
outthe output stream to which to write.
vectorthe vector to write.
Returns
a reference to out.

◆ operator<<() [3/6]

std::ostream& regina::operator<< ( std::ostream &  out,
const Rational rat 
)

Writes the given rational to the given output stream.

Infinity will be written as Inf. Undefined will be written as Undef. A rational with denominator one will be written as a single integer. All other rationals will be written in the form r/s.

Parameters
outthe output stream to which to write.
ratthe rational to write.
Returns
a reference to out.

◆ operator<<() [4/6]

template<int n>
std::ostream& regina::operator<< ( std::ostream &  out,
const Perm< n > &  p 
)
inline

Writes a string representation of the given permutation to the given output stream.

The format will be the same as is used by Perm::str().

Parameters
outthe output stream to which to write.
pthe permutation to write.
Returns
a reference to out.
Template Parameters
nthe number of objects being permuted. This must be between 3 and 16 inclusive.

◆ operator<<() [5/6]

template<bool supportInfinity>
std::ostream& regina::operator<< ( std::ostream &  out,
const IntegerBase< supportInfinity > &  i 
)

Writes the given integer to the given output stream.

Parameters
outthe output stream to which to write.
ithe integer to write.
Returns
a reference to out.

◆ operator<<() [6/6]

template<int bytes>
std::ostream & regina::operator<< ( std::ostream &  out,
const NativeInteger< bytes > &  i 
)
inline

Writes the given integer to the given output stream.

Parameters
outthe output stream to which to write.
ithe integer to write.
Returns
a reference to out.

◆ preImageOfLattice()

std::unique_ptr<MatrixInt> regina::preImageOfLattice ( const MatrixInt hom,
const std::vector< Integer > &  sublattice 
)

Given a homomorphism from Z^n to Z^k and a sublattice of Z^k, compute the preimage of this sublattice under this homomorphism.

The homomorphism from Z^n to Z^k is described by the given k by n matrix hom. The sublattice is of the form (p1 Z) * (p2 Z) * ... * (pk Z), where the non-negative integers p1, ..., pk are passed in the given list sublattice.

An equivalent problem is to consider hom to be a homomorphism from Z^n to Z_p1 + ... + Z_pk; this routine then finds the kernel of this homomorphism.

The preimage of the sublattice (equivalently, the kernel described above) is some rank n lattice in Z^n. This algorithm finds and returns a basis for the lattice.

Python:
The argument sublattice should be supplied as a python list.
Parameters
homthe matrix representing the homomorphism from Z^n to Z^k; this must be a k by n matrix.
sublatticea list of length k describing the sublattice of Z^k; the elements of this list must be the non-negative integers p1, ..., pk as described above.
Returns
a new matrix whose columns are a basis for the preimage lattice. This matrix will have precisely n rows.
Author
Ryan Budney

◆ reducedMod()

long regina::reducedMod ( long  k,
long  modBase 
)

Reduces k modulo modBase to give the smallest possible absolute value.

For instance, reducedMod(4,10) = 4 but reducedMod(6,10) = -4. In the case of a tie, the positive solution is taken.

Precondition
modBase is strictly positive.
Parameters
kthe number to reduce modulo modBase.
modBasethe modular base in which to work.

◆ rowBasis()

unsigned regina::rowBasis ( MatrixInt matrix)

Find a basis for the row space of the given matrix.

This routine will rearrange the rows of the given matrix so that the first rank rows form a basis for the row space (where rank is the rank of the matrix). The rank itself will be returned. No other changes will be made to the matrix aside from swapping rows.

Although this routine takes an integer matrix (and only uses integer operations), we consider the row space to be over the rationals. That is, although we never divide, we act as though we could if we wanted to.

Parameters
matrixthe matrix to examine and rearrange.
Returns
the rank of the given matrix.

◆ rowBasisAndOrthComp()

unsigned regina::rowBasisAndOrthComp ( MatrixInt input,
MatrixInt complement 
)

Finds a basis for the row space of the given matrix, as well as an "incremental" basis for its orthogonal complement.

This routine takes an (r by c) matrix input, as well as a square (c by c) matrix complement, and does the following:

  • The rows of input are rearranged so that the first rank rows form a basis for the row space (where rank is the rank of the matrix). No other changes are made to this matrix aside from swapping rows.
  • The matrix complement is re-filled (any previous contents are thrown away) so that, for any i between 0 and rank-1 inclusive, the final (c - i) rows of complement form a basis for the orthogonal complement of the first i rows of the rearranged input.
  • The rank of the matrix input is returned from this routine.

This routine can help with larger procedures that need to build up a row space and simultaneously cut down the complement one dimension at a time.

Although this routine takes integer matrices (and only uses integer operations), we consider all bases to be over the rationals. That is, although we never divide, we act as though we could if we wanted to.

Precondition
The matrix complement is a square matrix, whose size is equal to the number of columns in input.
Parameters
inputthe input matrix whose row space we will describe; this matrix will be changed (though only by swapping rows).
complementthe square matrix that will be re-filled with the "incremental" basis for the orthogonal complement of input.
Returns
the rank of the given matrix input.

◆ simpler() [1/2]

bool regina::simpler ( const Matrix2 m1,
const Matrix2 m2 
)

Determines whether the first given matrix is more aesthetically pleasing than the second.

The way in which this judgement is made is purely aesthetic on the part of the author, and is subject to change in future versions of Regina.

Parameters
m1the first matrix to examine.
m2the second matrix to examine.
Returns
true if m1 is deemed to be more pleasing than m2, or false if either the matrices are equal or m2 is more pleasing than m1.

◆ simpler() [2/2]

bool regina::simpler ( const Matrix2 pair1first,
const Matrix2 pair1second,
const Matrix2 pair2first,
const Matrix2 pair2second 
)

Determines whether the first given pair of matrices is more aesthetically pleasing than the second pair.

The way in which this judgement is made is purely aesthetic on the part of the author, and is subject to change in future versions of Regina.

Note that pairs are ordered, so the pair (M, N) may be more (or perhaps less) pleasing than the pair (N, M).

Parameters
pair1firstthe first matrix of the first pair to examine.
pair1secondthe second matrix of the first pair to examine.
pair2firstthe first matrix of the second pair to examine.
pair2secondthe second matrix of the second pair to examine.
Returns
true if the first pair is deemed to be more pleasing than the second pair, or false if either the ordered pairs are equal or the second pair is more pleasing than the first.

◆ smithNormalForm() [1/2]

void regina::smithNormalForm ( MatrixInt matrix)

Transforms the given integer matrix into Smith normal form.

Note that the given matrix need not be square and need not be of full rank.

Reading down the diagonal, the final Smith normal form will have a series of non-negative, non-decreasing invariant factors followed by zeroes. "Invariant factor" refers to the convention that the ith term divides the (i+1)th term, and so they are unique.

The algorithm used is due to Hafner and McCurley (1991). It does not use modular arithmetic to control the intermediate coefficient explosion.

Parameters
matrixthe matrix to transform.

◆ smithNormalForm() [2/2]

void regina::smithNormalForm ( MatrixInt matrix,
MatrixInt rowSpaceBasis,
MatrixInt rowSpaceBasisInv,
MatrixInt colSpaceBasis,
MatrixInt colSpaceBasisInv 
)

A Smith normal form algorithm that also returns change of basis matrices.

This is a modification of the one-argument smithNormalForm(MatrixInt&). As well as converting the given matrix matrix into Smith normal form, it also returns the appropriate change-of-basis matrices corresponding to all the row and column operations that were performed.

The only input argument is matrix. The four remaining arguments (the change of basis matrices) will be refilled, though they must be constructed with the correct dimensions as seen in the preconditions below. All five arguments are used to return information as follows.

Let M be the initial value of matrix, and let S be the Smith normal form of M. After this routine exits:

  • The argument matrix will contain the Smith normal form S;
  • colSpaceBasis * M * rowSpaceBasis = S;
  • colSpaceBasisInv * S * rowSpaceBasisInv = M;
  • colSpaceBasis * colSpaceBasisInv and rowSpaceBasis * rowSpaceBasisInv are both identity matrices.

Thus, one obtains the Smith normal form the original matrix by multiplying on the left by ColSpaceBasis and on the right by RowSpaceBasis.

Precondition
The matrices rowSpaceBasis and rowSpaceBasisInv that are passed are square, with side length matrix.columns().
The matrices colSpaceBasis and colSpaceBasisInv that are passed are square, with side length matrix.rows().
Parameters
matrixthe original matrix to put into Smith Normal Form (this need not be square). When the algorithm terminates, this matrix is in its Smith Normal Form.
rowSpaceBasisused to return a change of basis matrix (see above for details).
rowSpaceBasisInvused to return the inverse of rowSpaceBasis.
colSpaceBasisused to return a change of basis matrix (see above for details).
colSpaceBasisInvused to return the inverse of colSpaceBasis.
Author
Ryan Budney

◆ torsionAutInverse()

std::unique_ptr<MatrixInt> regina::torsionAutInverse ( const MatrixInt input,
const std::vector< Integer > &  invF 
)

Given an automorphism of an abelian group, this procedure computes the inverse automorphism.

The abelian group is of the form Z_p1 + Z_p2 + ... + Z_pn. The input is an n-by-n matrix A which represents a lift of the automorphism to just some n-by-n matrix. Specifically, you have a little commutative diagram with Z^n –A–> Z^n covering the automorphism of Z_p1 + Z_p2 + ... + Z_pn, where the maps down are the direct sum of the standard quotients Z –> Z_pi. So if you want this procedure to give you meaningful output, A must be a lift of a genuine automorphism of Z_p1 + ... + Z_pn.

Precondition
The list p1, p2, ..., pn is a list of invariant factors, which means that p1|p2, ..., p{n-1}|pn.
Python:
The argument invF should be supplied as a python list.
Parameters
inputthe n-by-n matrix A, which must be a lift of a genuine automorphism as described above.
invFthe list p1, p2, ..., pn.
Returns
the inverse automorphism, also described as an n-by-n matrix as per the discussion above.
Author
Ryan Budney

Variable Documentation

◆ epsilon

const double regina::epsilon

Deprecated constant for managing floating-point roundoff errors.

A very small positive real designed to accommodate for rounding error. Any two numbers within epsilon of each other are considered to be equal by the generic zero-testing and sign-testing routines defined in this file (isZero(), isPositive(), isNonNegative() and so on).

Deprecated:
This method of using a hard-coded epsilon is very blunt. Currently Regina does not provide alternative methods for managing round-off error, though since Regina's computations are exact, this should not be necessary.
Python:
Not present.

◆ minusOne

template<class T>
T regina::Vector< T >::minusOne
static

Negative one in the underlying number system.

This would be const if it weren't for the fact that some compilers don't like this. It should never be modified!

◆ one

template<class T>
T regina::Vector< T >::one
static

One in the underlying number system.

This would be const if it weren't for the fact that some compilers don't like this. It should never be modified!

◆ zero

template<class T>
T regina::Vector< T >::zero
static

Zero in the underlying number system.

This would be const if it weren't for the fact that some compilers don't like this. It should never be modified!


Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).