Represents a permutation of {0,1,2,3,4,5,6}. More...

#include <maths/spec/perm7.h>

Public Types
using	Index = int
	Denotes a native signed integer type large enough to count all permutations on seven elements. More...

using	ImagePack = uint32_t
	Indicates the native unsigned integer type used to store a single image pack. More...

using	Code1 = ImagePack
	Indicates the native unsigned integer type used to store a first-generation permutation code. More...

using	Code2 = uint16_t
	Indicates the native unsigned integer type used to store a second-generation permutation code. More...

Public Member Functions
constexpr	Perm ()
	Creates the identity permutation. More...

constexpr	Perm (int a, int b)
	Creates the transposition of a and b. More...

constexpr	Perm (int a, int b, int c, int d, int e, int f, int g)
	Creates a permutation mapping (0,1,2,3,4,5,6) to (a,b,c,d,e,f,g) respectively. More...

constexpr	Perm (const std::array< int, 7 > &image)
	Creates a permutation mapping i to image[i] for each i = 0,1,2,3,4,5,6. More...

constexpr	Perm (int a0, int a1, int b0, int b1, int c0, int c1, int d0, int d1, int e0, int e1, int f0, int f1, int g0, int g1)
	Creates a permutation mapping (a0,b0,c0,d0,e0,f0,g0) to (a1,b1,c1,d1,e1,f1,g1) respectively. More...

constexpr	Perm (const Perm< 7 > &cloneMe)=default
	Creates a permutation that is a clone of the given permutation. More...

constexpr Code1	permCode1 () const
	Returns the first-generation code representing this permutation. More...

constexpr Code2	permCode2 () const
	Returns the second-generation code representing this permutation. More...

void	setPermCode1 (Code1 code)
	Sets this permutation to that represented by the given first-generation permutation code. More...

void	setPermCode2 (Code2 code)
	Sets this permutation to that represented by the given second-generation permutation code. More...

constexpr ImagePack	imagePack () const
	Returns the image pack that represents this permutation. More...

Perm< 7 > &	operator= (const Perm< 7 > &cloneMe)=default
	Sets this permutation to be equal to the given permutation. More...

constexpr Perm< 7 >	operator* (const Perm< 7 > &q) const
	Returns the composition of this permutation with the given permutation. More...

Perm< 7 >	cachedComp (const Perm< 7 > &q) const
	Returns the composition of this and the given permutation, using fast precomputed lookup tables. More...

Perm< 7 >	cachedComp (const Perm< 7 > &q, const Perm< 7 > &r) const
	Deprecated function that performs two compositions using fast precomputed lookup tables. More...

constexpr Perm< 7 >	conjugate (const Perm< 7 > &q) const
	Computes the conjugate of this permutation by q. More...

Perm< 7 >	cachedConjugate (const Perm< 7 > &q) const
	Computes the conjugate of this permutation by q, using fast precomputed lookup tables. More...

constexpr Perm< 7 >	inverse () const
	Finds the inverse of this permutation. More...

Perm< 7 >	cachedInverse () const
	An alias for inverse(), provided to assist with writing generic code. More...

constexpr Perm< 7 >	pow (long exp) const
	Computes the given power of this permutation. More...

Perm< 7 >	cachedPow (long exp) const
	Computes the given power of this permutation, using fast precomputed lookup tables. More...

constexpr int	order () const
	Returns the order of this permutation. More...

int	cachedOrder () const
	Returns the order of this permutation, using fast precomputed lookup tables. More...

constexpr Perm< 7 >	reverse () const
	Finds the reverse of this permutation. More...

constexpr int	sign () const
	Determines the sign of this permutation. More...

constexpr int	operator[] (int source) const
	Determines the image of the given integer under this permutation. More...

constexpr int	pre (int image) const
	Determines the preimage of the given integer under this permutation. More...

constexpr bool	operator== (const Perm< 7 > &other) const
	Determines if this is equal to the given permutation. More...

constexpr bool	operator!= (const Perm< 7 > &other) const
	Determines if this differs from the given permutation. More...

constexpr int	compareWith (const Perm< 7 > &other) const
	Lexicographically compares the images of (0,1,2,3,4,5,6) under this and the given permutation. More...

constexpr bool	isIdentity () const
	Determines if this is the identity permutation. More...

Perm< 7 > &	operator++ ()
	A preincrement operator that changes this to be the next permutation in the array Perm<7>::Sn. More...

constexpr Perm< 7 >	operator++ (int)
	A postincrement operator that changes this to be the next permutation in the array Perm<7>::Sn. More...

constexpr bool	operator< (const Perm< 7 > &rhs) const
	Determines if this appears earlier than the given permutation in the array Perm<7>::Sn. More...

std::string	str () const
	Returns a string representation of this permutation. More...

std::string	trunc (int len) const
	Returns a prefix of the string representation of this permutation, containing only the images of the first len integers. More...

void	tightEncode (std::ostream &out) const
	Writes the tight encoding of this permutation to the given output stream. More...

std::string	tightEncoding () const
	Returns the tight encoding of this permutation. More...

void	clear (unsigned from)
	Resets the images of all integers from from onwards to the identity map. More...

constexpr Index	SnIndex () const
	Returns the index of this permutation in the Perm<7>::Sn array. More...

constexpr Index	S7Index () const
	Returns the index of this permutation in the Perm<7>::S7 array. More...

constexpr Index	orderedSnIndex () const
	Returns the lexicographical index of this permutation. More...

constexpr Index	orderedS7Index () const
	Returns the lexicographical index of this permutation. More...

constexpr bool	isConjugacyMinimal () const
	Is this permutation minimal in its conjugacy class? More...

Static Public Member Functions
static void	precompute ()
	Performs the precomputation necessary for using the optimised cachedComp(), cachedPow() and cachedOrder() routines. More...

static constexpr Perm< 7 >	fromPermCode1 (Code1 code)
	Creates a permutation from the given first-generation permutation code. More...

static constexpr Perm< 7 >	fromPermCode2 (Code2 code)
	Creates a permutation from the given second-generation permutation code. More...

static constexpr bool	isPermCode1 (Code1 code)
	Determines whether the given character is a valid first-generation permutation code. More...

static constexpr bool	isPermCode2 (Code2 code)
	Determines whether the given character is a valid second-generation permutation code. More...

static constexpr Perm	fromImagePack (ImagePack pack)
	Creates a permutation from the given image pack. More...

static constexpr bool	isImagePack (ImagePack pack)
	Determines whether the given argument is the image pack of some 7-element permutation. More...

static constexpr Perm	rot (int i)
	Returns the ith rotation. More...

static Perm	rand (bool even=false)
	Returns a random permutation on seven elements. More...

template<class URBG >
static Perm	rand (URBG &&gen, bool even=false)
	Returns a random permutation on seven elements, using the given uniform random bit generator. More...

static Perm	tightDecoding (const std::string &enc)
	Reconstructs a permutation from its given tight encoding. More...

static Perm	tightDecode (std::istream &input)
	Reconstructs a permutation from its given tight encoding. More...

template<int k>
static constexpr Perm< 7 >	extend (Perm< k > p)
	Extends a k-element permutation to a 7-element permutation, where 2 ≤ k < 7. More...

template<int k>
static constexpr Perm< 7 >	contract (Perm< k > p)
	Restricts a k-element permutation to a 7-element permutation, where k > 7. More...

Static Public Attributes
static constexpr PermCodeType	codeType = PERM_CODE_INDEX
	Indicates what type of internal permutation code is used by this instance of the Perm class template. More...

static constexpr Index	nPerms = 5040
	The total number of permutations on seven elements. More...

static constexpr Index	nPerms_1 = 720
	The total number of permutations on six elements. More...

static constexpr int	imageBits = 3
	Indicates the number of bits used in an image pack to store the image of a single integer. More...

static constexpr ImagePack	imageMask
	A bitmask whose lowest imageBits bits are 1, and whose remaining higher order bits are all 0. More...

static constexpr S7Lookup	Sn {}
	Gives fast array-like access to all possible permutations of seven elements. More...

static constexpr S7Lookup	S7 {}
	Gives fast array-like access to all possible permutations of seven elements. More...

static constexpr OrderedS7Lookup	orderedSn {}
	Gives fast array-like access to all possible permutations of seven elements in lexicographical order. More...

static constexpr OrderedS7Lookup	orderedS7 {}
	Gives fast array-like access to all possible permutations of seven elements in lexicographical order. More...

Protected Member Functions
constexpr	Perm (Code2 code)
	Creates a permutation from the given second-generation permutation code. More...

Protected Attributes
Code2	code2_
	The internal second-generation permutation code representing this permutation. More...

Detailed Description

Represents a permutation of {0,1,2,3,4,5,6}.

This is a specialisation of the generic Perm template: it is highly optimised, and also offers some additional functionality. Amongst other things, this permutation class is used to specify how simplices of a 6-dimensional triangulation are glued together.

As with all Perm template classes, these objects are small enough to pass by value and swap with std::swap(), with no need for any specialised move operations or swap functions.

Each permutation has an internal code, which is a single native integer that is sufficient to reconstruct the permutation. Thus the internal code may be a useful means for passing permutation objects to and from the engine. For Perm<7>, the internal permutation codes have changed as of Regina 7.0:

First-generation codes were used internally in Regina 6.0.1 and earlier. These are image packs: integers whose lowest three bits represent the image of 0, whose next lowest three bits represent the image of 1, and so on. The routines permCode1(), setPermCode1(), fromPermCode1() and isPermCode1() continue to work with first-generation codes for backward compatibility. Likewise, the XML data file format continues to use first-generation codes to describe gluings between 6-simplices.
Second-generation codes are used internally in Regina 7.0 and above. These codes are integers between 0 and 5039 inclusive, representing the index of the permutation in the array Perm<7>::S7. The routines permCode2(), setPermCode2(), fromPermCode2() and isPermCode2() work with second-generation codes.

It is highly recommended that, if you need to work with permutation codes at all, you use second-generation codes where possible. This is because the first-generation routines incur additional overhead in converting back and forth between the second-generation codes (which are used internally by Perm<7>).

To use this class, simply include the main permutation header maths/perm.h.

Python: Since Python does not support templates, this class is made available under the name Perm7.

Member Typedef Documentation

◆ Code1

using regina::Perm< 7 >::Code1 = ImagePack

Indicates the native unsigned integer type used to store a first-generation permutation code.

◆ Code2

using regina::Perm< 7 >::Code2 = uint16_t

Indicates the native unsigned integer type used to store a second-generation permutation code.

◆ ImagePack

using regina::Perm< 7 >::ImagePack = uint32_t

Indicates the native unsigned integer type used to store a single image pack.

See the class notes for more information on image packs, and how they are used to build the old first-generation permutation codes.

◆ Index

using regina::Perm< 7 >::Index = int

Denotes a native signed integer type large enough to count all permutations on seven elements.

In other words, this is a native signed integer type large enough to store (7!).

Constructor & Destructor Documentation

◆ Perm() [1/7]

constexpr regina::Perm< 7 >::Perm ( )

inlineconstexpr

Creates the identity permutation.

◆ Perm() [2/7]

constexpr regina::Perm< 7 >::Perm	(	int	a,
		int	b
	)

inlineconstexpr

Creates the transposition of a and b.

Note that a and b need not be distinct.

Precondition: a and b are in {0,1,2,3,4,5,6}.

Parameters

a	the element to switch with b.
b	the element to switch with a.

◆ Perm() [3/7]

constexpr regina::Perm< 7 >::Perm	(	int	a,
		int	b,
		int	c,
		int	d,
		int	e,
		int	f,
		int	g
	)

inlineconstexpr

Creates a permutation mapping (0,1,2,3,4,5,6) to (a,b,c,d,e,f,g) respectively.

Precondition: {a,b,c,d,e,f,g} = {0,1,2,3,4,5,6}.

Parameters

a	the desired image of 0.
b	the desired image of 1.
c	the desired image of 2.
d	the desired image of 3.
e	the desired image of 4.
f	the desired image of 5.
g	the desired image of 6.

◆ Perm() [4/7]

constexpr regina::Perm< 7 >::Perm ( const std::array< int, 7 > & image )

inlineconstexpr

Creates a permutation mapping i to image[i] for each i = 0,1,2,3,4,5,6.

Precondition: The elements of image are 0, 1, 2, 3, 4, 5 and 6 in some order.

Parameters

image the array of images.

◆ Perm() [5/7]

constexpr regina::Perm< 7 >::Perm	(	int	a0,
		int	a1,
		int	b0,
		int	b1,
		int	c0,
		int	c1,
		int	d0,
		int	d1,
		int	e0,
		int	e1,
		int	f0,
		int	f1,
		int	g0,
		int	g1
	)

inlineconstexpr

Creates a permutation mapping (a0,b0,c0,d0,e0,f0,g0) to (a1,b1,c1,d1,e1,f1,g1) respectively.

Precondition: {a0,b0,c0,d0,e0,f0,g0} = {a1,b1,c1,d1,e1,f1,g1} = {0,1,2,3,4,5,6}.

Parameters

a0	the desired preimage of a1.
b0	the desired preimage of b1.
c0	the desired preimage of c1.
d0	the desired preimage of d1.
e0	the desired preimage of e1.
f0	the desired preimage of f1.
g0	the desired preimage of g1.
a1	the desired image of a0.
b1	the desired image of b0.
c1	the desired image of c0.
d1	the desired image of d0.
e1	the desired image of e0.
f1	the desired image of f0.
g1	the desired image of g0.

◆ Perm() [6/7]

constexpr regina::Perm< 7 >::Perm ( const Perm< 7 > & cloneMe )

constexprdefault

Creates a permutation that is a clone of the given permutation.

Parameters

cloneMe the permutation to clone.

◆ Perm() [7/7]

constexpr regina::Perm< 7 >::Perm ( Code2 code )

inlineconstexprprotected

Creates a permutation from the given second-generation permutation code.

Precondition: the given code is a valid second-generation permutation code; see isPermCode2() for details.

Parameters

code	the second-generation code from which the new permutation will be created.

Member Function Documentation

◆ cachedComp() [1/2]

Perm< 7 > regina::Perm< 7 >::cachedComp ( const Perm< 7 > & q ) const

inline

Returns the composition of this and the given permutation, using fast precomputed lookup tables.

The advantage of this routine is speed: calling cachedComp() is a single table lookup, whereas the * operator requires significant computational overhead.

The disadvantages of this routine are that (1) you must remember to call precompute() in advance, and (2) the resulting lookup table will consume roughly 50MB of memory for the lifetime of your program.

The permutation that is returned is the same as you would obtain by calling (*this) * q.

Precondition: You must have called the routine precompute() at least once in the lifetime of this program before using cachedComp(). Otherwise this routine will almost certainly crash your program.

Parameters

q	the permutation to compose this with.

Returns: the composition of both permutations.

◆ cachedComp() [2/2]

Perm< 7 > regina::Perm< 7 >::cachedComp	(	const Perm< 7 > &	q,
		const Perm< 7 > &	r
	)		const

inline

Deprecated function that performs two compositions using fast precomputed lookup tables.

The permutation that is returned is the same as you would obtain by calling (*this) * q * r.

Deprecated:: The three-way cachedComp() was originally written to support conjugation. If you are indeed conjugating, then call cachedConjugate() instead; otherwise just call the two-way cachedComp() twice.

Precondition: You must have called the routine precompute() at least once in the lifetime of this program before using cachedComp(). Otherwise this routine will almost certainly crash your program.

Parameters

q	the first permutation to compose this with.
r	the second permutation to compose this with.

Returns: the composition of both permutations.

◆ cachedConjugate()

Perm< 7 > regina::Perm< 7 >::cachedConjugate ( const Perm< 7 > & q ) const

inline

Computes the conjugate of this permutation by q, using fast precomputed lookup tables.

The advantage of this routine is speed: calling cachedConjugate() is just three table lookups, whereas conjugate() requires significant computational overhead.

The disadvantages of this routine are that (1) you must remember to call precompute() in advance, and (2) the resulting lookup table will consume roughly 50MB of memory for the lifetime of your program.

The permutation that is returned is the same as you would obtain by calling conjugate().

Precondition: You must have called precompute() at least once in the lifetime of this program before calling cachedConjugate(). Otherwise this routine will almost certainly crash your program.

Parameters

q	the permutation to conjugate this by.

Returns: the conjugate of this permutation by q.

◆ cachedInverse()

Perm< 7 > regina::Perm< 7 >::cachedInverse ( ) const

inline

An alias for inverse(), provided to assist with writing generic code.

This specialised Perm<7> class does not use precomputation to compute inverses. The only point of having cachedInverse() in Perm<7> is to make it easier to write generic code that works with Perm<n> for any n.

If you know you are only working with Perm<7>, you should just call inverse() instead.
If you are writing generic code, you must remember to call precompute() at least once in the lifetime of this program before using cachedInverse().

Precondition: You must have called precompute() at least once in the lifetime of this program before calling cachedInverse(). For Perm<7>, precompute() does not affect inverse computations; however, for other Perm<n> classes a failure to do this will almost certainly crash your program.

Returns: the inverse of this permutation.

◆ cachedOrder()

int regina::Perm< 7 >::cachedOrder ( ) const

inline

Returns the order of this permutation, using fast precomputed lookup tables.

In other words; this routine returns the smallest positive integer k for which the kth power of this permutation is the identity.

The advantage of this routine is speed: calling cachedOrder() removes most of the computational overhead required by order().

The disadvantages of this routine are that (1) you must remember to call precompute() in advance, and (2) the resulting lookup tables will consume roughly 50MB of memory for the lifetime of your program. Note that these are the same lookup tables used by cachedComp() and cachedPow(), so if you are already using cachedComp() or cachedPow() then there is no extra cost for using this routine also.

The permutation that is returned is the same as you would obtain by calling order().

Precondition: You must have called the routine precompute() at least once in the lifetime of this program before using cachedOrder(). Otherwise this routine will almost certainly crash your program.

Returns: the order of this permutation.

◆ cachedPow()

Perm< 7 > regina::Perm< 7 >::cachedPow ( long exp ) const

inline

Computes the given power of this permutation, using fast precomputed lookup tables.

This routine runs in constant time.

The advantage of this routine is speed: calling cachedPow() removes most of the significant computational overhead required by pow().

The disadvantages of this routine are that (1) you must remember to call precompute() in advance, and (2) the resulting lookup tables will consume roughly 50MB of memory for the lifetime of your program. Note that these are the same lookup tables used by cachedComp() and cachedOrder(), so if you are already using cachedComp() or cachedOrder() then there is no extra cost for using this routine also.

The permutation that is returned is the same as you would obtain by calling pow(exp).

Precondition: You must have called the routine precompute() at least once in the lifetime of this program before using cachedPow(). Otherwise this routine will almost certainly crash your program.

Parameters

exp	the exponent; this may be positive, zero or negative.

Returns: this permutation raised to the power of exp.

◆ clear()

void regina::Perm< 7 >::clear ( unsigned from )

Resets the images of all integers from from onwards to the identity map.

Specifically, for each i in the range from,...,6, this routine will ensure that image[i] == i. The images of 0,1,...,from-1 will not be altered.

Precondition: The images of from,...,6 are exactly from,...,6, but possibly in a different order.

Parameters

from	the first integer whose image should be reset. This must be between 0 and 7 inclusive.

◆ compareWith()

constexpr int regina::Perm< 7 >::compareWith ( const Perm< 7 > & other ) const

inlineconstexpr

Lexicographically compares the images of (0,1,2,3,4,5,6) under this and the given permutation.

Note that this does not yield the same ordering of permutations as used by the less-than and increment operators. Moreover, compareWith() is slower than the less-than operator to compute.

Parameters

other the permutation with which to compare this.

Returns: -1 if this permutation produces a smaller image, 0 if the permutations are equal and 1 if this permutation produces a greater image.

◆ conjugate()

constexpr Perm< 7 > regina::Perm< 7 >::conjugate ( const Perm< 7 > & q ) const

inlineconstexpr

Computes the conjugate of this permutation by q.

Specifically, calling p.conjugate(q) is equivalent to computing q * p * q.inverse(). The resulting permutation will have the same cycle structure as p, but with the cycle elements translated according to q.

For permutations of five and fewer objects, conjugation is extremely fast because it uses hard-coded lookup tables. However, for Perm<7> these tables would grow too large, and so instead this routine involves significant computational overhead.

If you do need conjugation to be as fast as possible, with no computation required at all, then you can:

call precompute() to precompute a full 5040-by-5040 product table in advance (this will consume roughly 50MB of memory); and then
call cachedConjugate() instead of conjugate() to compute your conjugations.

Parameters

q	the permutation to conjugate this by.

Returns: the conjugate of this permutation by q.

◆ contract()

template<int k>

static constexpr Perm< 7 > regina::Perm< 7 >::contract ( Perm< k > p )

staticconstexpr

Restricts a k-element permutation to a 7-element permutation, where k > 7.

The resulting permutation will map 0,...,6 to their respective images under p, and will ignore the "unused" images p[7],...,p[k-1].

Precondition: The given permutation maps 0,...,6 to 0,...,6 in some order.

Template Parameters

k	the number of elements for the input permutation; this must be strictly greater than 7.

Parameters

p	a permutation on k elements.

Returns: the same permutation restricted to a permutation on 7 elements.

◆ extend()

template<int k>

static constexpr Perm< 7 > regina::Perm< 7 >::extend ( Perm< k > p )

staticconstexpr

Extends a k-element permutation to a 7-element permutation, where 2 ≤ k < 7.

The resulting permutation will map 0,...,k-1 to their respective images under p, and will map the "unused" elements k,...,6 to themselves.

Template Parameters

k	the number of elements for the input permutation; this must be 2, 3, 4, 5 or 6.

Parameters

p	a permutation on k elements.

Returns: the same permutation expressed as a permutation on seven elements.

◆ fromImagePack()

constexpr Perm< 7 > regina::Perm< 7 >::fromImagePack ( ImagePack pack )

inlinestaticconstexpr

Creates a permutation from the given image pack.

See the class notes for more information on image packs, and how they are used to build the old first-generation permutation codes.

For Perm<7>, this routine is identical to fromPermCode1().

Precondition: The argument pack is a valid image pack; see isImagePack() for details.

Parameters

pack	an image pack that describes a permutation.

Returns: the permutation represented by the given image pack.

◆ fromPermCode1()

constexpr Perm< 7 > regina::Perm< 7 >::fromPermCode1 ( Code1 code )

inlinestaticconstexpr

Creates a permutation from the given first-generation permutation code.

Precondition: the given code is a valid first-generation permutation code; see isPermCode1() for details.

Warning: This routine will incur additional overhead, since Perm<7> now uses second-generation codes internally. See the class notes and the routine fromPermCode2() for details.

Parameters

code	the first-generation code for the new permutation.

Returns: the permutation represented by the given code.

◆ fromPermCode2()

constexpr Perm< 7 > regina::Perm< 7 >::fromPermCode2 ( Code2 code )

inlinestaticconstexpr

Creates a permutation from the given second-generation permutation code.

Second-generation codes are fast to work with, since they are used internally by the Perm<7> class.

Precondition: the given code is a valid second-generation permutation code; see isPermCode2() for details.

Parameters

code	the second-generation code for the new permutation.

Returns: the permutation represented by the given code.

◆ imagePack()

constexpr Perm< 7 >::ImagePack regina::Perm< 7 >::imagePack ( ) const

inlineconstexpr

Returns the image pack that represents this permutation.

See the class notes for more information on image packs, and how they are used to build the old first-generation permutation codes.

For Perm<7>, this routine is identical to permCode1().

Returns: the image pack for this permutation.

◆ inverse()

constexpr Perm< 7 > regina::Perm< 7 >::inverse ( ) const

inlineconstexpr

Finds the inverse of this permutation.

Returns: the inverse of this permutation.

◆ isConjugacyMinimal()

constexpr bool regina::Perm< 7 >::isConjugacyMinimal ( ) const

inlineconstexpr

Is this permutation minimal in its conjugacy class?

Here "minimal" means that, amongst all its conjugates, this permutation has the smallest index in the array Perm<7>::Sn.

See Sn for further information on how permutations are indexed.

This routine is extremely fast for Perm<7>, since it essentially uses a hard-coded lookup table.

Returns: true if and only if this permutation is minimal in its conjugacy class.

◆ isIdentity()

constexpr bool regina::Perm< 7 >::isIdentity ( ) const

inlineconstexpr

Determines if this is the identity permutation.

This is true if and only if each of 0, 1, 2, 3, 4, 5 and 6 is mapped to itself.

Returns: true if and only if this is the identity permutation.

◆ isImagePack()

constexpr bool regina::Perm< 7 >::isImagePack ( ImagePack pack )

inlinestaticconstexpr

Determines whether the given argument is the image pack of some 7-element permutation.

See the class notes for more information on image packs, and how they are used to build the old first-generation permutation codes.

For Perm<7>, this routine is identical to isPermCode1().

Parameters

pack	the candidate image pack to test.

Returns: true if and only if pack is a valid image pack.

◆ isPermCode1()

constexpr bool regina::Perm< 7 >::isPermCode1 ( Code1 code )

inlinestaticconstexpr

Determines whether the given character is a valid first-generation permutation code.

Valid first-generation codes can be passed to setPermCode1() or fromPermCode1(), and are returned by permCode1().

Warning: This routine will incur additional overhead, since Perm<7> now uses second-generation codes internally. See the class notes and the routine isPermCode2() for details.

Parameters

code	the permutation code to test.

Returns: true if and only if the given code is a valid first-generation permutation code.

◆ isPermCode2()

constexpr bool regina::Perm< 7 >::isPermCode2 ( Code2 code )

inlinestaticconstexpr

Determines whether the given character is a valid second-generation permutation code.

Valid second-generation codes can be passed to setPermCode2() or fromPermCode2(), and are returned by permCode2().

Second-generation codes are fast to work with, since they are used internally by the Perm<7> class.

Parameters

code	the permutation code to test.

Returns: true if and only if the given code is a valid second-generation permutation code.

◆ operator!=()

constexpr bool regina::Perm< 7 >::operator!= ( const Perm< 7 > & other ) const

inlineconstexpr

Determines if this differs from the given permutation.

This is true if and only if the two permutations have different images for at least one of 0, 1, 2, 3, 4, 5 or 6.

Parameters

other the permutation with which to compare this.

Returns: true if and only if this and the given permutation differ.

◆ operator*()

constexpr Perm< 7 > regina::Perm< 7 >::operator* ( const Perm< 7 > & q ) const

inlineconstexpr

Returns the composition of this permutation with the given permutation.

If this permutation is p, the resulting permutation will be p∘q, and will satisfy (p*q)[x] == p[q[x]].

For permutations of five and fewer objects, composition is extremely fast because it uses hard-coded lookup tables. However, for Perm<7> these tables would grow too large, and so instead this routine involves significant computational overhead.

If you are going to make significant use of the Perm<7> class, you should instead:

call precompute() to precompute a full 5040-by-5040 lookup table in advance (this will consume roughly 50MB of memory); and then
call cachedComp() instead of the * operator to compute your compositions.

Parameters

q	the permutation to compose this with.

Returns: the composition of both permutations.

◆ operator++() [1/2]

Perm< 7 > & regina::Perm< 7 >::operator++ ( )

inline

A preincrement operator that changes this to be the next permutation in the array Perm<7>::Sn.

If this is the last such permutation then this will wrap around to become the first permutation in Perm<7>::Sn, which is the identity.

Python: Not present. The postincrement operator is present in Python as the member function inc().

Returns: a reference to this permutation after the increment.

◆ operator++() [2/2]

constexpr Perm< 7 > regina::Perm< 7 >::operator++ ( int )

inlineconstexpr

A postincrement operator that changes this to be the next permutation in the array Perm<7>::Sn.

If this is the last such permutation then this will wrap around to become the first permutation in Perm<7>::Sn, which is the identity.

Python: This routine is named inc() since python does not support the increment operator.

Returns: a copy of this permutation before the increment took place.

◆ operator<()

constexpr bool regina::Perm< 7 >::operator< ( const Perm< 7 > & rhs ) const

inlineconstexpr

Determines if this appears earlier than the given permutation in the array Perm<7>::Sn.

Note that this is not the same ordering of permutations as the ordering implied by compareWith(). This is, however, consistent with the ordering implied by the ++ operators, and this order is also faster to compute than compareWith().

Parameters

rhs	the permutation to compare this against.

Returns: true if and only if this appears before rhs in Sn.

◆ operator=()

Perm< 7 > & regina::Perm< 7 >::operator= ( const Perm< 7 > & cloneMe )

default

Sets this permutation to be equal to the given permutation.

Parameters

cloneMe the permutation whose value will be assigned to this permutation.

Returns: a reference to this permutation.

◆ operator==()

constexpr bool regina::Perm< 7 >::operator== ( const Perm< 7 > & other ) const

inlineconstexpr

Determines if this is equal to the given permutation.

This is true if and only if both permutations have the same images for 0, 1, 2, 3, 4, 5 and 6.

Parameters

other the permutation with which to compare this.

Returns: true if and only if this and the given permutation are equal.

◆ operator[]()

constexpr int regina::Perm< 7 >::operator[] ( int source ) const

inlineconstexpr

Determines the image of the given integer under this permutation.

Parameters

source the integer whose image we wish to find. This should be between 0 and 6 inclusive.

Returns: the image of source.

◆ order()

constexpr int regina::Perm< 7 >::order ( ) const

inlineconstexpr

Returns the order of this permutation.

In other words; this routine returns the smallest positive integer k for which the kth power of this permutation is the identity.

Unlike the smaller permutation classes, Perm<7>::order() does not use precomputed tables; instead it computes orders on the fly. If you need your order computation to be faster, you can instead:

call precompute() to precompute a full table of orders in advance (though this will also compute the much larger 5040-by-5040 table of products, which consumes roughly 50MB of memory); and then
call cachedOrder() instead of order(), which will now become a fast table lookup.

Returns: the order of this permutation.

◆ orderedS7Index()

constexpr Perm< 7 >::Index regina::Perm< 7 >::orderedS7Index ( ) const

inlineconstexpr

Returns the lexicographical index of this permutation.

This will be the index of this permutation in the Perm<7>::orderedSn array.

This is a dimension-specific alias for orderedSnIndex(). In general, for every n there will be a member function Perm<n>::orderedSnIndex(); however, these numerical aliases Perm<2>::orderedS2Index(), ..., Perm<7>::orderedS7Index() are only available for small n.

See orderedSn for further information on lexicographical ordering.

Returns: the lexicographical index of this permutation. This will be between 0 and 5039 inclusive.

◆ orderedSnIndex()

constexpr Perm< 7 >::Index regina::Perm< 7 >::orderedSnIndex ( ) const

inlineconstexpr

Returns the lexicographical index of this permutation.

This will be the index of this permutation in the Perm<7>::orderedSn array.

See orderedSn for further information on lexicographical ordering.

Returns: the lexicographical index of this permutation. This will be between 0 and 5039 inclusive.

◆ permCode1()

constexpr Perm< 7 >::Code1 regina::Perm< 7 >::permCode1 ( ) const

inlineconstexpr

Returns the first-generation code representing this permutation.

This code is sufficient to reproduce the entire permutation.

The code returned will be a valid first-generation permutation code as determined by isPermCode1().

Warning: This routine will incur additional overhead, since Perm<7> now uses second-generation codes internally. See the class notes and the routine isPermCode2() for details.

Returns: the first-generation permutation code.

◆ permCode2()

constexpr Perm< 7 >::Code2 regina::Perm< 7 >::permCode2 ( ) const

inlineconstexpr

Returns the second-generation code representing this permutation.

This code is sufficient to reproduce the entire permutation.

The code returned will be a valid second-generation permutation code as determined by isPermCode2().

Second-generation codes are fast to work with, since they are used internally by the Perm<7> class.

Returns: the second-generation permutation code.

◆ pow()

constexpr Perm< 7 > regina::Perm< 7 >::pow ( long exp ) const

inlineconstexpr

Computes the given power of this permutation.

This routine runs in constant time.

For Perm<7>, this routine makes use of the composition operator *, which involves significant computational overhead. If you need your powers to be fast, you can instead:

call precompute() to precompute a full 5040-by-5040 product table in advance (this will consume roughly 50MB of memory); and then
call cachedPow() instead of pow() to make full use of this table, which will remove most of the overhead from this routine.

Parameters

exp	the exponent; this may be positive, zero or negative.

Returns: this permutation raised to the power of exp.

◆ pre()

constexpr int regina::Perm< 7 >::pre ( int image ) const

inlineconstexpr

Determines the preimage of the given integer under this permutation.

Parameters

image the integer whose preimage we wish to find. This should be between 0 and 6 inclusive.

Returns: the preimage of image.

◆ precompute()

static void regina::Perm< 7 >::precompute ( )

static

Performs the precomputation necessary for using the optimised cachedComp(), cachedPow() and cachedOrder() routines.

This must be called before calling any of cachedComp(), cachedPow() or cachedOrder().

This only needs to be done once in the lifetime of the program. If you do try to call precompute() a second time then it will do nothing and return immediately.

This routine is thread-safe.

◆ rand() [1/2]

Perm< 7 > regina::Perm< 7 >::rand ( bool even = false )

inlinestatic

Returns a random permutation on seven elements.

All permutations are returned with equal probability.

This routine is thread-safe, and uses RandomEngine for its random number generation.

Warning: This routine is expensive, since it locks and unlocks the mutex protecting Regina's global uniform random bit generator. If you are calling this many times in quick succession, consider creating a single RandomEngine object yourself and then calling rand(randomEngine.engine(), even).

Parameters

even	if `true`, then the resulting permutation is guaranteed to be even (and again all even permutations are returned with equal probability).

Returns: a random permutation.

◆ rand() [2/2]

template<class URBG >

static Perm regina::Perm< 7 >::rand	(	URBG &&	gen,
		bool	even = `false`
	)

static

Returns a random permutation on seven elements, using the given uniform random bit generator.

All permutations are returned with equal probability.

The thread safety of this routine is of course dependent on the thread safety of your uniform random bit generator gen.

Template Parameters

URBG	A type which, once any references are removed, must adhere to the C++ UniformRandomBitGenerator concept.

Python: Not present. Python users are still able to use the non-thread-safe variant without the gen argument.

Parameters

gen	the source of randomness to use (e.g., one of the many options provided in the C++ standard `random` header).
even	if `true`, then the resulting permutation is guaranteed to be even (and again all even permutations are returned with equal probability).

Returns: a random permutation.

◆ reverse()

constexpr Perm< 7 > regina::Perm< 7 >::reverse ( ) const

inlineconstexpr

Finds the reverse of this permutation.

Here reverse means that we reverse the images of 0,...,6. In other words, if permutation q is the reverse of p, then p[i] == q[6 - i] for all i.

◆ rot()

constexpr Perm< 7 > regina::Perm< 7 >::rot ( int i )

inlinestaticconstexpr

Returns the ith rotation.

This maps k to k + i (mod 7) for all k.

Parameters

i	the image of 0; this must be between 0 and 6 inclusive.

Returns: the ith rotation.

◆ S7Index()

constexpr Perm< 7 >::Index regina::Perm< 7 >::S7Index ( ) const

inlineconstexpr

Returns the index of this permutation in the Perm<7>::S7 array.

This is a dimension-specific alias for SnIndex(). In general, for every n there will be a member function Perm<n>::SnIndex(); however, these numerical aliases Perm<2>::S2Index(), ..., Perm<7>::S7Index() are only available for small n.

See Sn for further information on how these permutations are indexed.

Returns: the index i for which this permutation is equal to Perm<7>::S7[i]. This will be between 0 and 5039 inclusive.

◆ setPermCode1()

void regina::Perm< 7 >::setPermCode1 ( Code1 code )

inline

Sets this permutation to that represented by the given first-generation permutation code.

Precondition: the given code is a valid first-generation permutation code; see isPermCode1() for details.

Warning: This routine will incur additional overhead, since Perm<7> now uses second-generation codes internally. See the class notes and the routine setPermCode2() for details.

Parameters

code	the first-generation code that will determine the new value of this permutation.

◆ setPermCode2()

void regina::Perm< 7 >::setPermCode2 ( Code2 code )

inline

Sets this permutation to that represented by the given second-generation permutation code.

Second-generation codes are fast to work with, since they are used internally by the Perm<7> class.

Precondition: the given code is a valid second-generation permutation code; see isPermCode2() for details.

Parameters

code	the second-generation code that will determine the new value of this permutation.

◆ sign()

constexpr int regina::Perm< 7 >::sign ( ) const

inlineconstexpr

Determines the sign of this permutation.

Returns: 1 if this permutation is even, or -1 if this permutation is odd.

◆ SnIndex()

constexpr Perm< 7 >::Index regina::Perm< 7 >::SnIndex ( ) const

inlineconstexpr

Returns the index of this permutation in the Perm<7>::Sn array.

See Sn for further information on how these permutations are indexed.

Returns: the index i for which this permutation is equal to Perm<7>::Sn[i]. This will be between 0 and 5039 inclusive.

◆ str()

std::string regina::Perm< 7 >::str ( ) const

Returns a string representation of this permutation.

The representation will consist of seven adjacent digits representing the images of 0, 1, 2, 3, 4, 5 and 6 respectively. An example of a string representation is 3045261.

Returns: a string representation of this permutation.

◆ tightDecode()

Perm< 7 > regina::Perm< 7 >::tightDecode ( std::istream & input )

inlinestatic

Reconstructs a permutation from its given tight encoding.

See the page on tight encodings for details.

The tight encoding will be read from the given input stream. If the input stream contains leading whitespace then it will be treated as an invalid encoding (i.e., this routine will throw an exception). The input routine may contain further data: if this routine is successful then the input stream will be left positioned immediately after the encoding, without skipping any trailing whitespace.

Tight encodings are fast to work with for small permutation classes (n ≤ 7), but slower for larger permutation classes (8 ≤ n ≤ 16). See tightEncoding() for further details.

Exceptions

InvalidInput The given input stream does not begin with a tight encoding of a 7-element permutation.

Python: Not present. Use tightDecoding() instead, which takes a string as its argument.

Parameters

input an input stream that begins with the tight encoding for a 7-element permutation.

Returns: the permutation represented by the given tight encoding.

◆ tightDecoding()

Perm< 7 > regina::Perm< 7 >::tightDecoding ( const std::string & enc )

inlinestatic

Reconstructs a permutation from its given tight encoding.

See the page on tight encodings for details.

The tight encoding will be given as a string. If this string contains leading whitespace or any trailing characters at all (including trailing whitespace), then it will be treated as an invalid encoding (i.e., this routine will throw an exception).

Tight encodings are fast to work with for small permutation classes (n ≤ 7), but slower for larger permutation classes (8 ≤ n ≤ 16). See tightEncoding() for further details.

Exceptions

InvalidArgument The given string is not a tight encoding of a 7-element permutation.

Parameters

enc	the tight encoding for a 7-element permutation.

Returns: the permutation represented by the given tight encoding.

◆ tightEncode()

void regina::Perm< 7 >::tightEncode ( std::ostream & out ) const

inline

Writes the tight encoding of this permutation to the given output stream.

See the page on tight encodings for details.

For all permutation classes Perm<n>, the tight encoding is based on the index into the full permutation group S_n. For smaller permutation classes (n ≤ 7), such encodings are very fast to work with since the S_n index is used as the internal permutation code. For larger permutation classes however (8 ≤ n ≤ 16), the S_n index requires some non-trivial work to compute.

Python: Not present. Use tightEncoding() instead, which returns a string.

Parameters

out	the output stream to which the encoded string will be written.

◆ tightEncoding()

std::string regina::Perm< 7 >::tightEncoding ( ) const

inline

Returns the tight encoding of this permutation.

See the page on tight encodings for details.

For all permutation classes Perm<n>, the tight encoding is based on the index into the full permutation group S_n. For smaller permutation classes (n ≤ 7), such encodings are very fast to work with since the S_n index is used as the internal permutation code. For larger permutation classes however (8 ≤ n ≤ 16), the S_n index requires some non-trivial work to compute.

Returns: the resulting encoded string.

◆ trunc()

std::string regina::Perm< 7 >::trunc ( int len ) const

Returns a prefix of the string representation of this permutation, containing only the images of the first len integers.

Parameters

len	the length of the prefix required; this must be between 0 and 7 inclusive.

Returns: the corresponding prefix of the string representation of this permutation.

Member Data Documentation

◆ code2_

Code2 regina::Perm< 7 >::code2_

protected

The internal second-generation permutation code representing this permutation.

◆ codeType

constexpr PermCodeType regina::Perm< 7 >::codeType = PERM_CODE_INDEX

staticconstexpr

Indicates what type of internal permutation code is used by this instance of the Perm class template.

◆ imageBits

constexpr int regina::Perm< 7 >::imageBits = 3

staticconstexpr

Indicates the number of bits used in an image pack to store the image of a single integer.

A full image pack combines 7 such images together, and so uses 7 * imageBits bits in total.

◆ imageMask

constexpr ImagePack regina::Perm< 7 >::imageMask

staticconstexpr

Initial value:

=

(static_cast<ImagePack>(1) << imageBits) - 1

regina::Perm< 7 >::ImagePack

uint32_t ImagePack

Indicates the native unsigned integer type used to store a single image pack.

Definition: perm7.h:140

regina::Perm< 7 >::imageBits

static constexpr int imageBits

Indicates the number of bits used in an image pack to store the image of a single integer.

Definition: perm7.h:132

A bitmask whose lowest imageBits bits are 1, and whose remaining higher order bits are all 0.

This may be useful when creating or analysing image packs.

◆ nPerms

constexpr Index regina::Perm< 7 >::nPerms = 5040

staticconstexpr

The total number of permutations on seven elements.

This is the size of the array Sn.

◆ nPerms_1

constexpr Index regina::Perm< 7 >::nPerms_1 = 720

staticconstexpr

The total number of permutations on six elements.

This is the size of the symmetric group S₆.

◆ orderedS7

constexpr OrderedS7Lookup regina::Perm< 7 >::orderedS7 {}

staticconstexpr

Gives fast array-like access to all possible permutations of seven elements in lexicographical order.

This is a dimension-specific alias for Perm<7>::orderedSn; see that member for further information. In general, for every n there will be a static member Perm<n>::orderedSn; however, these numerical aliases Perm<2>::orderedS2, ..., Perm<7>::orderedS7 are only available for small n.

◆ orderedSn

constexpr OrderedS7Lookup regina::Perm< 7 >::orderedSn {}

staticconstexpr

Gives fast array-like access to all possible permutations of seven elements in lexicographical order.

To access the permutation at index i, you simply use the square bracket operator: orderedSn[i]. The index i must be between 0 and 5039 inclusive. This element access is extremely fast (a fact that is not true for the larger permutation classes Perm<n> with n ≥ 8).

Lexicographical ordering treats each permutation p as the ordered pair (p[0], ..., p[6]).

This array is different from Perm<7>::Sn, since orderedSn stores permutations in lexicographical order, whereas Sn alternates between even and odd permutations.

This is a lightweight object, and it is defined in the headers only. In particular, you cannot make a reference to it (but it is cheap to make a copy).

◆ S7

constexpr S7Lookup regina::Perm< 7 >::S7 {}

staticconstexpr

Gives fast array-like access to all possible permutations of seven elements.

This is a dimension-specific alias for Perm<7>::Sn; see that member for further information. In general, for every n there will be a static member Perm<n>::Sn; however, these numerical aliases Perm<2>::S2, ..., Perm<7>::S7 are only available for small n.

◆ Sn

constexpr S7Lookup regina::Perm< 7 >::Sn {}

staticconstexpr

Gives fast array-like access to all possible permutations of seven elements.

To access the permutation at index i, you simply use the square bracket operator: Sn[i]. The index i must be between 0 and 5039 inclusive. This element access is extremely fast (a fact that is not true for the larger permutation classes Perm<n> with n ≥ 8).

The permutations with even indices in the array are the even permutations, and those with odd indices in the array are the odd permutations.

This array is different from Perm<7>::orderedSn, since Sn alternates between even and odd permutations, whereas orderedSn stores permutations in lexicographical order.

This is a lightweight object, and it is defined in the headers only. In particular, you cannot make a reference to it (but it is cheap to make a copy).

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

maths/spec/perm7.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Code1

◆ Code2

◆ ImagePack

◆ Index

Constructor & Destructor Documentation

◆ Perm() [1/7]

◆ Perm() [2/7]

◆ Perm() [3/7]

◆ Perm() [4/7]

◆ Perm() [5/7]

◆ Perm() [6/7]

◆ Perm() [7/7]

Member Function Documentation

◆ cachedComp() [1/2]

◆ cachedComp() [2/2]

◆ cachedConjugate()

◆ cachedInverse()

◆ cachedOrder()

◆ cachedPow()

◆ clear()

◆ compareWith()

◆ conjugate()

◆ contract()

◆ extend()

◆ fromImagePack()

◆ fromPermCode1()

◆ fromPermCode2()

◆ imagePack()

◆ inverse()

◆ isConjugacyMinimal()

◆ isIdentity()

◆ isImagePack()

◆ isPermCode1()

◆ isPermCode2()

◆ operator!=()

◆ operator*()

◆ operator++() [1/2]

◆ operator++() [2/2]

◆ operator<()

◆ operator=()

◆ operator==()

◆ operator[]()

◆ order()

◆ orderedS7Index()

◆ orderedSnIndex()

◆ permCode1()

◆ permCode2()

◆ pow()

◆ pre()

◆ precompute()

◆ rand() [1/2]

◆ rand() [2/2]

◆ reverse()

◆ rot()

◆ S7Index()

◆ setPermCode1()

◆ setPermCode2()

◆ sign()

◆ SnIndex()

◆ str()

◆ tightDecode()

◆ tightDecoding()

◆ tightEncode()

◆ tightEncoding()

◆ trunc()

Member Data Documentation

◆ code2_

◆ codeType

◆ imageBits

◆ imageMask

◆ nPerms

◆ nPerms_1