Regina Calculation Engine
Public Member Functions | Static Public Member Functions | List of all members
regina::Cyclotomic Class Reference

Represents an element of a cyclotomic field. More...

#include <maths/cyclotomic.h>

Inheritance diagram for regina::Cyclotomic:
regina::ShortOutput< Cyclotomic, true > regina::Output< Cyclotomic, supportsUtf8 >

Public Member Functions

 Cyclotomic ()
 Creates an uninitialised field element. More...
 
 Cyclotomic (size_t field)
 Creates the zero element of the given cyclotomic field. More...
 
 Cyclotomic (size_t field, int value)
 Creates the given integer element within the given cyclotomic field. More...
 
 Cyclotomic (size_t field, const Rational &value)
 Creates the given rational element within the given cyclotomic field. More...
 
 Cyclotomic (const Cyclotomic &value)
 Creates a copy of the given field element, within the same cyclotomic field. More...
 
 ~Cyclotomic ()
 Destroys this field element. More...
 
void init (size_t field)
 Initialises this to be the zero element of the given cyclotomic field. More...
 
size_t field () const
 Returns the order n of the underlying cyclotomic field to which this element belongs. More...
 
size_t degree () const
 Returns the degree of the polynomial that defines the underlying cyclotomic field. More...
 
const Rationaloperator[] (size_t exp) const
 Returns an individual rational coefficient of the polynomial representation of this field element. More...
 
Rationaloperator[] (size_t exp)
 Offers access to an individual rational coefficient of the polynomial representation of this field element. More...
 
Polynomial< Rational > * polynomial () const
 Returns the full polynomial representation of this field element. More...
 
std::complex< double > evaluate (size_t whichRoot=1) const
 Returns the value of this cyclotomic field element as a complex number. More...
 
bool operator== (const Cyclotomic &rhs) const
 Tests whether or not this and the given argument are the same element of the same cyclotomic field. More...
 
bool operator!= (const Cyclotomic &rhs) const
 Tests whether or not this and the given argument are the same element of the same cyclotomic field. More...
 
Cyclotomicoperator= (const Cyclotomic &value)
 Sets this to a copy of the given field element. More...
 
Cyclotomicoperator= (const Rational &scalar)
 Sets this field element to the given rational. More...
 
void negate ()
 Negates this field element. More...
 
void invert ()
 Inverts this field element. More...
 
Cyclotomicoperator*= (const Rational &scalar)
 Multiplies this field element by the given rational. More...
 
Cyclotomicoperator/= (const Rational &scalar)
 Divides this field element by the given rational. More...
 
Cyclotomicoperator+= (const Cyclotomic &other)
 Adds the given field element to this. More...
 
Cyclotomicoperator-= (const Cyclotomic &other)
 Subtracts the given field element from this. More...
 
Cyclotomicoperator*= (const Cyclotomic &other)
 Multiplies this by the given field element. More...
 
Cyclotomicoperator/= (const Cyclotomic &other)
 Divides this by the given field element. More...
 
void writeTextShort (std::ostream &out, bool utf8=false, const char *variable=0) const
 Writes this field element to the given output stream, using the given variable name instead of x. More...
 
std::string str (const char *variable) const
 Returns this field element as a human-readable string, using the given variable name instead of x. More...
 
std::string utf8 (const char *variable) const
 Returns this field element as a human-readable string using unicode characters, using the given variable name instead of x. More...
 
void writeTextLong (std::ostream &out) const
 A default implementation for detailed output. More...
 
std::string str () const
 Returns a short text representation of this object. More...
 
std::string utf8 () const
 Returns a short text representation of this object using unicode characters. More...
 
std::string detail () const
 Returns a detailed text representation of this object. More...
 

Static Public Member Functions

static const Polynomial< Integer > & cyclotomic (size_t n)
 Returns the nth cyclotomic polynomial Φ_n. More...
 

Detailed Description

Represents an element of a cyclotomic field.

The cyclotomic field of order n extends the rationals with a primitive nth root of unity. This is isomorphic to the polynomial field ℚ[x]/Φ_n, where Φ_n is the nth cyclotomic polynomial.

Using this isomorphism, each element of the cyclotomic field can be uniquely represented as a rational polynomial of degree strictly less than deg(Φ_n) = φ(n), where φ denotes Euler's totient function. This class stores field elements using such a polynomial representation, and does not store complex numbers directly. If you require the complex value of a field element (as a floating point approximation), you can call evaluate().

Each object of this class stores both the value of the field element and the order n of the underlying field. This means that you can freely work with elements of different fields simultaneously, though of course most operations (such as addition, multplication and so on) require all operands to belong to the same field.

This class requires that the order n is strictly positive.

Although this class makes use of global data in its implementation, all of its methods are thread-safe.

Constructor & Destructor Documentation

§ Cyclotomic() [1/5]

regina::Cyclotomic::Cyclotomic ( )
inline

Creates an uninitialised field element.

This element must be initialised using either init() or the assignment operator before it can be used.

The underlying cyclotomic field is not yet known; this will also be specified during the call to init() or the assignment operator.

§ Cyclotomic() [2/5]

regina::Cyclotomic::Cyclotomic ( size_t  field)
inlineexplicit

Creates the zero element of the given cyclotomic field.

Parameters
fieldthe order of the underlying cyclotomic field; this must be strictly positive.

§ Cyclotomic() [3/5]

regina::Cyclotomic::Cyclotomic ( size_t  field,
int  value 
)
inline

Creates the given integer element within the given cyclotomic field.

The polynomial representation of this element will simply be an integer constant.

Parameters
fieldthe order of the underlying cyclotomic field; this must be strictly positive.
valuethe value of this element; that is, the integer constant.

§ Cyclotomic() [4/5]

regina::Cyclotomic::Cyclotomic ( size_t  field,
const Rational value 
)
inline

Creates the given rational element within the given cyclotomic field.

The polynomial representation of this element will simply be a rational constant.

Parameters
fieldthe order of the underlying cyclotomic field; this must be strictly positive.
valuethe value of this element; that is, the rational constant.

§ Cyclotomic() [5/5]

regina::Cyclotomic::Cyclotomic ( const Cyclotomic value)
inline

Creates a copy of the given field element, within the same cyclotomic field.

Parameters
valuethe field element to copy.

§ ~Cyclotomic()

regina::Cyclotomic::~Cyclotomic ( )
inline

Destroys this field element.

This is safe even if the field element was never initialised.

Member Function Documentation

§ cyclotomic()

static const Polynomial<Integer>& regina::Cyclotomic::cyclotomic ( size_t  n)
static

Returns the nth cyclotomic polynomial Φ_n.

Cyclotomic polynomials are cached after they are computed, and so after the first call to cyclotomic(n), all subsequent calls with the same value of n will be essentially instantaneous.

Although it queries and manipulates a global cache, this routine is thread-safe.

Precondition
The given integer n must be strictly positive.
Python:
This routine returns a newly allocated polynomial (not a constant reference). Moreover, since Python exposes the class Polynomial<Rational> but not Polynomial<Integer>, this routine returns an object of type Polynomial<Rational> instead.
Parameters
nindicates which cyclotomic polynomial to return.
Returns
the cyclotomic polynomial Φ_n.

§ degree()

size_t regina::Cyclotomic::degree ( ) const
inline

Returns the degree of the polynomial that defines the underlying cyclotomic field.

This is the degree of the cyclotomic polynomial Φ_n, and also the value of Euler's totient function φ(n), where n is the order of the field as returned by field().

A value of zero indicates that this field element has not yet been initialised (for instance, it was created using the default constructor).

Returns
the degree of the polynomial that defines the underlying field.

§ detail()

std::string regina::Output< Cyclotomic , supportsUtf8 >::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.

§ evaluate()

std::complex<double> regina::Cyclotomic::evaluate ( size_t  whichRoot = 1) const

Returns the value of this cyclotomic field element as a complex number.

The evaluation depends upon which primitive root of unity is used to build the underlying cyclotomic field of order n. This ambiguity is resolved as follows.

Suppose the polynomial representation of this field element in ℚ[x]/Φ_n (as described in the Cyclotomic class notes) is f(x). Then the evaluation of this field element will be f(ρ), where ρ is the nth root of unity ρ = exp(2πi × k/n), and where k is the argument whichRoot as passed to this routine.

Precondition
The argument whichRoot is coprime to n (the order of the underlying cyclotomic field).
This field element has been initialised (either through a non-default constructor, an assignment operator, or by calling init()).
Warning
This routine uses floating point arithmetic, and so the value that it returns is subject to the usual floating point error.
Parameters
whichRootindicates which root of unity will be used to convert the polynomial representation of this field element into a complex number.
Returns
a floating-point approximation of this cyclotomic field element as a complex number.

§ field()

size_t regina::Cyclotomic::field ( ) const
inline

Returns the order n of the underlying cyclotomic field to which this element belongs.

A value of zero indicates that this field element has not yet been initialised (for instance, it was created using the default constructor).

Returns
the order of the underlying cyclotomic field.

§ init()

void regina::Cyclotomic::init ( size_t  field)
inline

Initialises this to be the zero element of the given cyclotomic field.

This is safe even if this element was previously initialised as an element of a different field - all prior information about this field element will be safely discarded.

Parameters
fieldthe order of the cyclotomic field to which this field element will now belong; this must be strictly positive.

§ invert()

void regina::Cyclotomic::invert ( )

Inverts this field element.

Precondition
This field element has already been initialised (and so it already has specified an underlying cyclotomic field).
This field element is non-zero.

§ negate()

void regina::Cyclotomic::negate ( )
inline

Negates this field element.

§ operator!=()

bool regina::Cyclotomic::operator!= ( const Cyclotomic rhs) const
inline

Tests whether or not this and the given argument are the same element of the same cyclotomic field.

If this and rhs have different underlying fields then this test will always return true (indicating that the elements are not equal), even if they take the same numerical value when evaluated as complex numbers.

If either this or rhs have not been initialised (typically because they were created using the default constructor), then this comparison will return true. If both field elements have not been initialised, then this comparison will return false.

Parameters
rhsthe value to compare with this.
Returns
false if this and rhs are the same element of the same cyclotomic field, or true if they are not.

§ operator*=() [1/2]

Cyclotomic & regina::Cyclotomic::operator*= ( const Rational scalar)
inline

Multiplies this field element by the given rational.

This has the effect of multiplying the polynomial representation by a scalar constant.

Parameters
scalarthe rational to multiply this by.
Returns
a reference to this field element.

§ operator*=() [2/2]

Cyclotomic& regina::Cyclotomic::operator*= ( const Cyclotomic other)

Multiplies this by the given field element.

Precondition
The argument other belongs to the same cyclotomic field as this.
Parameters
otherthe field element to multiply this by.
Returns
a reference to this field element.

§ operator+=()

Cyclotomic & regina::Cyclotomic::operator+= ( const Cyclotomic other)
inline

Adds the given field element to this.

Precondition
The argument other belongs to the same cyclotomic field as this.
Parameters
otherthe field element to add to this.
Returns
a reference to this field element.

§ operator-=()

Cyclotomic & regina::Cyclotomic::operator-= ( const Cyclotomic other)
inline

Subtracts the given field element from this.

Precondition
The argument other belongs to the same cyclotomic field as this.
Parameters
otherthe field element to subtract from this.
Returns
a reference to this field element.

§ operator/=() [1/2]

Cyclotomic & regina::Cyclotomic::operator/= ( const Rational scalar)
inline

Divides this field element by the given rational.

This has the effect of dividing the polynomial representation by a scalar constant.

Precondition
The given rational is non-zero.
Parameters
scalarthe rational to divide this by.
Returns
a reference to this field element.

§ operator/=() [2/2]

Cyclotomic & regina::Cyclotomic::operator/= ( const Cyclotomic other)
inline

Divides this by the given field element.

Precondition
The argument other is non-zero.
The argument other belongs to the same cyclotomic field as this.
Parameters
otherthe field element to divide this by.
Returns
a reference to this field element.

§ operator=() [1/2]

Cyclotomic & regina::Cyclotomic::operator= ( const Cyclotomic value)
inline

Sets this to a copy of the given field element.

This assignment operator is safe even if this and value belong to different cyclotomic fields, or if this and/or value has not yet been initialised. The underlying field for this element will simply be changed to match the underlying field for value, and all old information stored for this element (if any) will be safely discarded. If value is uninitialised then this field element will become uninitialised also.

Parameters
valuethe new value to assign to this field element.
Returns
a reference to this field element.

§ operator=() [2/2]

Cyclotomic & regina::Cyclotomic::operator= ( const Rational scalar)
inline

Sets this field element to the given rational.

The underlying cyclotomic field will be left unchanged.

The polynomial representation for this field element will simply be a constant.

Precondition
This field element has already been initialised (and so it already has specified an underlying cyclotomic field).
Parameters
scalarthe new rational value of this field element.
Returns
a reference to this field element.

§ operator==()

bool regina::Cyclotomic::operator== ( const Cyclotomic rhs) const
inline

Tests whether or not this and the given argument are the same element of the same cyclotomic field.

If this and rhs have different underlying fields then this test will always return false, even if they take the same numerical value when evaluated as complex numbers.

If either this or rhs have not been initialised (typically because they were created using the default constructor), then this comparison will return false. If both field elements have not been initialised, then this comparison will return true.

Parameters
rhsthe value to compare with this.
Returns
true if and only if this and rhs are the same element of the same cyclotomic field.

§ operator[]() [1/2]

const Rational & regina::Cyclotomic::operator[] ( size_t  exp) const
inline

Returns an individual rational coefficient of the polynomial representation of this field element.

The polynomial representation expresses this field element as a member of ℚ[x]/Φ_n, using a rational polynomial of degree strictly less than deg(Φ_n) = φ(n); that is, strictly less than the value returned by degree(). See the Cyclotomic class notes for further details.

In particular, for a field element e, the operator e[i] will return the coefficient of x^i in this polynomial representation.

This is a constant (read-only) routine; note that there is a non-constant (read-write) variant of this routine also.

Parameters
expindicates which coefficient to return; this must be between 0 and degree()-1 inclusive.
Returns
a constant reference to the corresponding rational coefficient.

§ operator[]() [2/2]

Rational & regina::Cyclotomic::operator[] ( size_t  exp)
inline

Offers access to an individual rational coefficient of the polynomial representation of this field element.

The polynomial representation expresses this field element as a member of ℚ[x]/Φ_n, using a rational polynomial of degree strictly less than deg(Φ_n) = φ(n); that is, strictly less than the value returned by degree(). See the Cyclotomic class notes for further details.

In particular, for a field element e, the operator e[i] will give access to the coefficient of x^i in this polynomial representation.

This routine returns a non-constant reference: you can use this to directly edit the coefficients (and therefore the value of the field element). Note that there is also a constant (read-only) variant of this routine.

Parameters
expindicates which coefficient to access; this must be between 0 and degree()-1 inclusive.
Returns
a reference to the corresponding rational coefficient.

§ polynomial()

Polynomial< Rational > * regina::Cyclotomic::polynomial ( ) const
inline

Returns the full polynomial representation of this field element.

The polynomial representation expresses this field element as a member of ℚ[x]/Φ_n, using a rational polynomial of degree strictly less than deg(Φ_n) = φ(n); that is, strictly less than the value returned by degree(). See the Cyclotomic class notes for further details.

This routine returns the polynomial representation as a newly allocated Polynomial<Rational> object. The caller of this routine is responsible for destroying this new polynomial.

The new polynomial will become independent of this Cyclotomic field element: if you subsequently change this field element then the new Polynomial object will not change, and likewise if you change the new Polynomial object then this Cyclotomic field element will not change.

Precondition
This field element has been initialised (either through a non-default constructor, an assignment operator, or by calling init()).
Returns
a new polynomial giving the full polynomial representation of this field element.

§ str() [1/2]

std::string regina::Output< Cyclotomic , supportsUtf8 >::str ( ) const
inherited

Returns a short text representation of this object.

This text should be human-readable, should fit on a single line, and should not end with a newline. Where possible, it should use plain ASCII characters.

Python:
In addition to str(), this is also used as the Python "stringification" function __str__().
Returns
a short text representation of this object.

§ str() [2/2]

std::string regina::Cyclotomic::str ( const char *  variable) const
inline

Returns this field element as a human-readable string, using the given variable name instead of x.

The field element will be written using its rational polynomial representation. The underlying field will not be indicated in the output, since this is often already understood. If required, it can be accessed by calling c.field().

Note
There is also the usual variant of str() which takes no arguments; that variant is inherited from the Output class.
Parameters
variablethe symbol to use for the polynomial variable. This may be null, in which case the default variable x will be used.
Returns
this field element as a human-readable string.

§ utf8() [1/2]

std::string regina::Output< Cyclotomic , supportsUtf8 >::utf8 ( ) const
inherited

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

Like str(), this text should be human-readable, should fit on a single line, and should not end with a newline. In addition, it may use unicode characters to make the output more pleasant to read. This string will be encoded in UTF-8.

Returns
a short text representation of this object.

§ utf8() [2/2]

std::string regina::Cyclotomic::utf8 ( const char *  variable) const
inline

Returns this field element as a human-readable string using unicode characters, using the given variable name instead of x.

The field element will be written using its rational polynomial representation. The underlying field will not be indicated in the output, since this is often already understood. If required, it can be accessed by calling c.field().

This is similar to the output from str(), except that it uses unicode characters to make the output more pleasant to read. In particular, it makes use of superscript digits for exponents.

The string is encoded in UTF-8.

Note
There is also the usual variant of utf8() which takes no arguments; that variant is inherited from the Output class.
Parameters
variablethe symbol to use for the polynomial variable. This may be null, in which case the default variable x will be used.
Returns
this field element as a unicode-enabled human-readable string.

§ writeTextLong()

void regina::ShortOutput< Cyclotomic , supportsUtf8 >::writeTextLong ( std::ostream &  out) const
inlineinherited

A default implementation for detailed output.

This routine simply calls T::writeTextShort() and appends a final newline.

Python:
Not present.
Parameters
outthe output stream to which to write.

§ writeTextShort()

void regina::Cyclotomic::writeTextShort ( std::ostream &  out,
bool  utf8 = false,
const char *  variable = 0 
) const

Writes this field element to the given output stream, using the given variable name instead of x.

The field element will be written using its rational polynomial representation. The underlying field will not be indicated in the output, since this is often already understood. If required, it can be accessed by calling c.field().

If utf8 is passed as true then unicode superscript characters will be used for exponents; these will be encoded using UTF-8. This will make the output nicer, but will require more complex fonts to be available on the user's machine.

Python:
Not present.
Parameters
outthe output stream to which to write.
utf8true if unicode superscript characters may be used.
variablethe symbol to use for the polynomial variable. This may be null, in which case the default variable x will be used.
Returns
a reference to the given output stream.

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

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