Regina Calculation Engine
|
Represents an element of a cyclotomic field. More...
#include <maths/ncyclotomic.h>
Public Member Functions | |
NCyclotomic () | |
Creates an uninitialised field element. More... | |
NCyclotomic (size_t field) | |
Creates the zero element of the given cyclotomic field. More... | |
NCyclotomic (size_t field, int value) | |
Creates the given integer element within the given cyclotomic field. More... | |
NCyclotomic (size_t field, const NRational &value) | |
Creates the given rational element within the given cyclotomic field. More... | |
NCyclotomic (const NCyclotomic &value) | |
Creates a copy of the given field element, within the same cyclotomic field. More... | |
~NCyclotomic () | |
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 NRational & | operator[] (size_t exp) const |
Returns an individual rational coefficient of the polynomial representation of this field element. More... | |
NRational & | operator[] (size_t exp) |
Offers access to an individual rational coefficient of the polynomial representation of this field element. More... | |
NPolynomial< NRational > * | 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 NCyclotomic &rhs) const |
Tests whether or not this and the given argument are the same element of the same cyclotomic field. More... | |
bool | operator!= (const NCyclotomic &rhs) const |
Tests whether or not this and the given argument are the same element of the same cyclotomic field. More... | |
NCyclotomic & | operator= (const NCyclotomic &value) |
Sets this to a copy of the given field element. More... | |
NCyclotomic & | operator= (const NRational &scalar) |
Sets this field element to the given rational. More... | |
void | negate () |
Negates this field element. More... | |
void | invert () |
Inverts this field element. More... | |
NCyclotomic & | operator*= (const NRational &scalar) |
Multiplies this field element by the given rational. More... | |
NCyclotomic & | operator/= (const NRational &scalar) |
Divides this field element by the given rational. More... | |
NCyclotomic & | operator+= (const NCyclotomic &other) |
Adds the given field element to this. More... | |
NCyclotomic & | operator-= (const NCyclotomic &other) |
Subtracts the given field element from this. More... | |
NCyclotomic & | operator*= (const NCyclotomic &other) |
Multiplies this by the given field element. More... | |
NCyclotomic & | operator/= (const NCyclotomic &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... | |
REGINA_DEPRECATED std::string | toString () const |
A deprecated alias for str(). More... | |
REGINA_DEPRECATED std::string | toStringLong () const |
A deprecated alias for detail(). More... | |
Static Public Member Functions | |
static const NPolynomial< NInteger > & | cyclotomic (size_t n) |
Returns the nth cyclotomic polynomial Φ_n . More... | |
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.
|
inline |
|
inlineexplicit |
Creates the zero element of the given cyclotomic field.
field | the order of the underlying cyclotomic field; this must be strictly positive. |
|
inline |
Creates the given integer element within the given cyclotomic field.
The polynomial representation of this element will simply be an integer constant.
field | the order of the underlying cyclotomic field; this must be strictly positive. |
value | the value of this element; that is, the integer constant. |
|
inline |
Creates the given rational element within the given cyclotomic field.
The polynomial representation of this element will simply be a rational constant.
field | the order of the underlying cyclotomic field; this must be strictly positive. |
value | the value of this element; that is, the rational constant. |
|
inline |
Creates a copy of the given field element, within the same cyclotomic field.
value | the field element to copy. |
|
inline |
Destroys this field element.
This is safe even if the field element was never initialised.
|
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.
n | indicates which cyclotomic polynomial to return. |
Φ_n
.
|
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).
|
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.
std::complex<double> regina::NCyclotomic::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 NCyclotomic 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.
whichRoot | indicates which root of unity will be used to convert the polynomial representation of this field element into a complex number. |
|
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).
|
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.
field | the order of the cyclotomic field to which this field element will now belong; this must be strictly positive. |
void regina::NCyclotomic::invert | ( | ) |
Inverts this field element.
|
inline |
Negates this field element.
|
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
.
rhs | the value to compare with this. |
false
if this and rhs are the same element of the same cyclotomic field, or true
if they are not.
|
inline |
Multiplies this field element by the given rational.
This has the effect of multiplying the polynomial representation by a scalar constant.
scalar | the rational to multiply this by. |
NCyclotomic& regina::NCyclotomic::operator*= | ( | const NCyclotomic & | other | ) |
Multiplies this by the given field element.
other | the field element to multiply this by. |
|
inline |
Adds the given field element to this.
other | the field element to add to this. |
|
inline |
Subtracts the given field element from this.
other | the field element to subtract from this. |
|
inline |
Divides this field element by the given rational.
This has the effect of dividing the polynomial representation by a scalar constant.
scalar | the rational to divide this by. |
|
inline |
Divides this by the given field element.
other | the field element to divide this by. |
|
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.
value | the new value to assign to this field element. |
|
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.
scalar | the new rational value of this field element. |
|
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
.
rhs | the value to compare with this. |
true
if and only if this and rhs are the same element of the same cyclotomic field.
|
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 NCyclotomic 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.
exp | indicates which coefficient to return; this must be between 0 and degree()-1 inclusive. |
|
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 NCyclotomic 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.
exp | indicates which coefficient to access; this must be between 0 and degree()-1 inclusive. |
|
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 NCyclotomic class notes for further details.
This routine returns the polynomial representation as a newly allocated NPolynomial<NRational> object. The caller of this routine is responsible for destroying this new polynomial.
The new polynomial will become independent of this NCyclotomic field element: if you subsequently change this field element then the new NPolynomial object will not change, and likewise if you change the new NPolynomial object then this NCyclotomic field element will not change.
|
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.
__str__()
.
|
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()
.
variable | the symbol to use for the polynomial variable. This may be null , in which case the default variable x will be used. |
|
inherited |
A deprecated alias for str().
|
inherited |
A deprecated alias for detail().
|
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.
|
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.
variable | the symbol to use for the polynomial variable. This may be null , in which case the default variable x will be used. |
|
inlineinherited |
A default implementation for detailed output.
This routine simply calls T::writeTextShort() and appends a final newline.
out | the output stream to which to write. |
void regina::NCyclotomic::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.
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. |