Documentation

Introduction

Real and complex numbers can only be stored in the computer effectively in

approximations. Magma provides a number of facilities for calculating with such approximations. Most of these facilities are based upon the C libraries MPFR, which provides algorithms for manipulating real numbers with exact rounding, and MPC, an extension of MPFR to handle complex numbers. More specifically, the MFPR library extends the semantics of the ANSI/IEEE-754 standard for double-precision numbers --- which are used in virtually all major programming languages --- to handle real numbers of arbitrary precision. The precise semantics of MPFR give the user fine control over precision loss, which is a tremendous advantage when working with reals and complexes. Magma currently uses MPFR 2.4.1 and MPC 0.8. Documentation for algorithms used in MPFR can be found at mpfr.org.

As MPFR and MPC are works in progress, they do not yet provide a complete framework for working with the reals and complexes. For those functions that these libraries are missing, Magma falls back to algorithms taken from Pari. The documentation of MFPR and MPC provide a list of the functions that they provide. Assume that each intrinsic uses MPFR unless otherwise stated.

Although we use the terms real field and complex field for Magma structures containing real or complex

approximations, it should be noted that such a subset of the real or complex field may not even form a commutative ring. Never the less, the real and complex fields are considered to be fields by Magma, they comprise objects of type FldRe and FldCom with elements of type FldReElt and FldComElt respectively.

Real Numbers in Magma

Real numbers are stored internally as a sign bit and an expansion ∑b_i 2ⁱ with b_i∈(0, 1). Note that MPFR has both positive and negative zeros. Complex numbers consist of a pair of real numbers of identical precision. Each real or complex number is associated with a corresponding field structure, which has the same precision as all of its elements. Magma stores a list of real and complex fields that have been created during a session, and it is guaranteed that any two fields of the same fixed precision are the same. This means in particular that changing the name of Sqrt( - 1) (see AssignNames below) on one of the complex fields of precision r will change the name on every complex field of that same precision. As a convenience, Magma allows real and complex numbers of differing precisions to be used in the same expression; internally, Magma implicitly reduces the precision of the higher precision element to the precision of the lower element.

While internally we store real numbers in base two, when creating real or complex fields the precision is by default specified in the number of decimal digits, not binary digits, required. It is possible to specify the precision in binary digits if needed see the documentation for RealField for details).

Example `FldRe_RealIntro (H26E1)`

We show how to create and manipulate real numbers. In particular, note that there is an inherent loss of precision in the conversion between base 10 and base 2 representations of some real numbers.

> S1 := RealField(20);
> S2 := RealField(10);
> a := S1 ! 0.5;
> a;
0.50000000000000000000
> b := S2 ! 0.05;
> b;
0.05000000000
> a + b;
0.5500000000
> Precision(a + b);
10

A warning is in place here; in the examples above, the real number on the right hand side had to be constructed in some real field before it could be coerced into S₁ and S₂. That real field is the so-called default real field. In these examples it is assumed that the default field has sufficiently large precision to store the real numbers on the right accurately to the last digit.

Coercion

Automatic coercion ensures that all functions listed below that

take an element of some real field as an argument, will also accept an integer or a rational number as an argument; in this case the integer or rational number will be coerced automatically into the default real field. For the binary operations (such as +, *) coercion also takes place: if one argument is real and the other is integral or rational, automatic coercion will put them both in the parent field of the real argument. If the arguments are real numbers of different fixed precision, the result will have the smaller precision of the two.

The same coercion rules

apply for functions taking a complex number as an argument; in that case real numbers will be valid input as well: if necessary reals, rationals or integers will be coerced into the appropriate complex field.

Elements of quadratic and cyclotomic fields that are real can be coerced into any real field using !; any quadratic or

cyclotomic field element can be coerced by ! into any complex field. Functions taking real or complex arguments will not automatically coerce such arguments though.

Homomorphisms

The only homomorphisms that have a real field or a complex field

as domain are the coercion functions. Therefore, homomorphisms from the reals or complexes may be specified as follows.

hom< R -> S | > : FldRe, Str -> Map

Here S must be a structure into which all elements of the real or complex field R are coercible, such as another real or complex field, or a polynomial ring over one of these. These homomorphisms can also be obtained as map by using the function Coercion, also called Bang.

Example `FldRe_Homomorphisms (H26E2)`

Here are two equivalent ways of creating the embedding function from a real field into a polynomial ring over some complex field.

> Re := RealField(20);
> PC<x, y> := PolynomialRing(ComplexField(8), 2);
> f := hom< Re -> PC | >;
> bangf := Bang(Re, PC);
> f(Pi(Re));
3.1415927
> f(Pi(Re)) eq bangf(Pi(Re));
true

Special Options

When Magma is started up, real and complex fields of precision 30 are created by default. They serve (among other things) as a parent for reals that are created as literals, such as 1.2345, in the same way as the default ring of integers is the parent for literal integers. It is possible to change this default real field with SetDefaultRealField.

Finally, AssignNames can be used to change the name for Sqrt( - 1) in a complex field.

SetDefaultRealField(R) : FldRe ->

Procedure to change the default parent for literal real numbers to the real field R. This parent is the real field of precision 30 by default.

GetDefaultRealField() : -> FldRe

Return the current parent for literal real numbers.

AssignNames(~C, [s]) : FldCom, [ MonStgElt ]) ->

Procedure to change the name of the purely imaginary element Sqrt( - 1) in the complex field C to the contents of the string s. When C is created, the name is "C.1"; suitable choices of s might be "i", "I" or "j".
This procedure only changes the name used in printing the elements of C. It does not assign to an identifier called s the value of Sqrt( - 1) in C; to do this, use an assignment statement, or use angle brackets when creating the field.
Note that since this is a procedure that modifies C, it is necessary to have a reference ~C to C in the call to this function.

Name(C, 1) : FldCom, RngIntElt -> FldComElt

Given a complex field C, return the element which has the name attached to it, that is, return the purely imaginary element Sqrt( - 1) of C.

Version Functions

The following intrinsics retrieve the versions of MPFR, MPC and GMP which the current Magma is using.