regina::Cyclotomic Class Reference
Mathematical Support

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

`#include <maths/cyclotomic.h>`

Inheritance diagram for regina::Cyclotomic:

## 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 Rational & | operator[] (size_t exp) const
| Returns an individual rational coefficient of the polynomial representation of this field element. More...
Rational & | operator[] (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...
Cyclotomic & | operator= (const Cyclotomic &value)
| Sets this to a copy of the given field element. More...
Cyclotomic & | operator= (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...
Cyclotomic & | operator*= (const Rational &scalar)
| Multiplies this field element by the given rational. More...
Cyclotomic & | operator/= (const Rational &scalar)
| Divides this field element by the given rational. More...
Cyclotomic & | operator+= (const Cyclotomic &other)
| Adds the given field element to this. More...
Cyclotomic & | operator-= (const Cyclotomic &other)
| Subtracts the given field element from this. More...
Cyclotomic & | operator*= (const Cyclotomic &other)
| Multiplies this by the given field element. More...
Cyclotomic & | operator/= (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 | ) |

inline explicit

Creates the zero element of the given cyclotomic field.

Parameters

  field | the 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

  field | the order of the underlying cyclotomic field; this must be strictly positive.
  value | the 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

  field | the order of the underlying cyclotomic field; this must be strictly positive.
  value | the 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

  value | the 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

  n | indicates 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 `n`th 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

  whichRoot | indicates 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

  field | the 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

  rhs | the 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

  scalar | the 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

  other | the 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

  other | the 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

  other | the 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

  scalar | the 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

  other | the 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

  value | the 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

  scalar | the 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

  rhs | the 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

  exp | indicates 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

  exp | indicates 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

  variable | the 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

  variable | the 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

inline inherited

A default implementation for detailed output.

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

Python:
  Not present.

Parameters

  out | the 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

  out | the output stream to which to write.
  utf8 | `true` if unicode superscript characters may be used.
  variable | the 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:

- maths/cyclotomic.h

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