Numbers
=======

Introduction to Numbers
-----------------------

Complex numbers
---------------

A complex expression is specified in Maxima by adding the real part of the expression to %i times the imaginary part.  Thus the roots of the equation x^2 - 4*x + 13 = 0 are 2 + 3*%i and 2 - 3*%i. Note that simplification of products of complex expressions can be effected by expanding the product.  Simplification of quotients, roots, and other functions of complex expressions can usually be accomplished by using the realpart, imagpart, rectform, polarform, abs, carg functions.

Complex variables

Floating point numbers
----------------------

Maxima has two types of floating point number. The first is just called a ``float'' (but will be called a ``machine float'' for the rest of this section to avoid ambiguity). This is stored in the underlying lisp's DOUBLE-FLOAT type which will almost certainly be IEEE 754 double precision floating point. To type a literal floating point number, just type its decimal expansion (for example, 0.01) or type it with an explicit exponent (such as 1e-2 or 0.1e-1).

The second type of floating point number in Maxima is called a ``bigfloat''. Bigfloats are stored as a mantissa and exponent in the same way as machine floats but the exponent is an arbitrary precision integer, so they can represent arbitrarily large or small numbers. The user can also customise the precision of bigfloat arithmetic (which corresponds to choosing the range of the mantissa). See fpprec for more information. To type a literal bigfloat, use the exponent notation as above but with the character b in place of e. The example of 0.01 from above could be entered as a bigfloat with 1b-2 or 0.001b0.

Calculations using machine floats can be significantly faster than using bigfloats since modern computer processors have dedicated hardware for them. This is particularly noticeable with compiled Maxima code. However, machine floats suffer from the problem of overflow, where a number can become too large for its exponent to be represented in the bits available. In interpreted code, the default behaviour is that a calculation that would cause a floating point overflow instead generates a bigfloat number. To configure this, see the promote_float_to_bigfloat variable.

Functions and Variables for Numbers
-----------------------------------

 -- Function: bfloat (EXPR)

     Converts all numbers and functions of numbers in EXPR to bigfloat numbers. The number of significant digits in the resulting bigfloats is specified by the global variable fpprec

     When float2bf is false a warning message is printed when a floating point number is converted into a bigfloat number (since this may lead to loss of precision).

     Numerical evaluation

 -- Function: bfloatp (EXPR)

     Returns true if EXPR is a bigfloat number, otherwise false.

     Numerical evaluation Predicate functions

 -- Option variable: bftorat
     Default value: false

     bftorat controls the conversion of bfloats to rational numbers.  When bftorat is false, ratepsilon will be used to control the conversion (this results in relatively small rational numbers).  When bftorat is true, the rational number generated will accurately represent the bfloat.

     Note: bftorat has no effect on the transformation to rational numbers with the function rationalize

     Example:

          (%i1) ratepsilon:1e-4;
          (%o1)                         1.e-4
          (%i2) rat(bfloat(11111/111111)), bftorat:false;
          `rat' replaced 9.99990999991B-2 by 1/10 = 1.0B-1
                                         1
          (%o2)/R/                       --
                                         10
          (%i3) rat(bfloat(11111/111111)), bftorat:true;
          `rat' replaced 9.99990999991B-2 by 11111/111111 = 9.99990999991B-2
                                       11111
          (%o3)/R/                     ------
                                       111111

     Numerical evaluation

 -- Option variable: bftrunc
     Default value: true

     bftrunc causes trailing zeroes in non-zero bigfloat numbers not to be displayed.  Thus, if bftrunc is false, bfloat (1) displays as 1.000000000000000B0.  Otherwise, this is displayed as 1.0B0.

     Numerical evaluation

 -- Function: evenp (EXPR)

     Returns true if EXPR is an even integer. false is returned in all other cases.

     Predicate functions

 -- Function: float (EXPR)

     Converts integers, rational numbers and bigfloats in EXPR to floating point numbers.  It is also an evflag float causes non-integral rational numbers and bigfloat numbers to be converted to floating point.

     Numerical evaluation Evaluation flags

 -- Option variable: float2bf
     Default value: true

     When float2bf is false, a warning message is printed when a floating point number is converted into a bigfloat number (since this may lead to loss of precision).

     Numerical evaluation

 -- Function: floatnump (EXPR)

     Returns true if EXPR is a floating point number, otherwise false.

     Numerical evaluation Predicate functions

 -- Option variable: fpprec
     Default value: 16

     fpprec is the number of significant digits for arithmetic on bigfloat numbers.  fpprec does not affect computations on ordinary floating point numbers.

     See also bfloat and fpprintprec

     Numerical evaluation

 -- Option variable: fpprintprec
     Default value: 0

     fpprintprec is the number of digits to print when printing an ordinary float or bigfloat number.

     For ordinary floating point numbers, when fpprintprec has a value between 2 and 16 (inclusive), the number of digits printed is equal to fpprintprec. Otherwise, fpprintprec is 0, or greater than 16, and the number of digits printed is 16.

     For bigfloat numbers, when fpprintprec has a value between 2 and fpprec (inclusive), the number of digits printed is equal to fpprintprec. Otherwise, fpprintprec is 0, or greater than fpprec, and the number of digits printed is equal to fpprec.

     For both ordinary floats and bigfloats, trailing zero digits are suppressed. The actual number of digits printed is less than fpprintprec if there are trailing zero digits.

     fpprintprec cannot be 1.

     Numerical evaluation Display flags and variables

 -- Function: integerp (EXPR)

     Returns true if EXPR is a literal numeric integer, otherwise false.

     integerp returns false if its argument is a symbol, even if the argument is declared integer.

     Examples:

          (%i1) integerp (0);
          (%o1)                         true
          (%i2) integerp (1);
          (%o2)                         true
          (%i3) integerp (-17);
          (%o3)                         true
          (%i4) integerp (0.0);
          (%o4)                         false
          (%i5) integerp (1.0);
          (%o5)                         false
          (%i6) integerp (%pi);
          (%o6)                         false
          (%i7) integerp (n);
          (%o7)                         false
          (%i8) declare (n, integer);
          (%o8)                         done
          (%i9) integerp (n);
          (%o9)                         false

     Predicate functions

 -- Option variable: m1pbranch
     Default value: false

     m1pbranch is the principal branch for -1 to a power. Quantities such as (-1)^(1/3) (that is, an "odd" rational exponent) and (-1)^(1/4) (that is, an "even" rational exponent) are handled as follows:

                        domain:real

          (-1)^(1/3):      -1
          (-1)^(1/4):   (-1)^(1/4)

                       domain:complex
          m1pbranch:false          m1pbranch:true
          (-1)^(1/3)               1/2+%i*sqrt(3)/2
          (-1)^(1/4)              sqrt(2)/2+%i*sqrt(2)/2

     Expressions Global flags

 -- Function: nonnegintegerp (N)

     Return true if and only if N >= 0 and N is an integer.

     Package linearalgebra Predicate functions

 -- Function: numberp (EXPR)

     Returns true if EXPR is a literal integer, rational number, floating point number, or bigfloat, otherwise false.

     numberp returns false if its argument is a symbol, even if the argument is a symbolic number such as %pi or %i, or declared to be even, odd, integer, rational, irrational, real, imaginary, or complex.

     Examples:

          (%i1) numberp (42);
          (%o1)                         true
          (%i2) numberp (-13/19);
          (%o2)                         true
          (%i3) numberp (3.14159);
          (%o3)                         true
          (%i4) numberp (-1729b-4);
          (%o4)                         true
          (%i5) map (numberp, [%e, %pi, %i, %phi, inf, minf]);
          (%o5)      [false, false, false, false, false, false]
          (%i6) declare (a, even, b, odd, c, integer, d, rational,
               e, irrational, f, real, g, imaginary, h, complex);
          (%o6)                         done
          (%i7) map (numberp, [a, b, c, d, e, f, g, h]);
          (%o7) [false, false, false, false, false, false, false, false]

     Predicate functions

 -- Option variable: numer

     numer causes some mathematical functions (including exponentiation) with numerical arguments to be evaluated in floating point.  It causes variables in expr which have been given numerals to be replaced by their values.  It also sets the float switch on.

     See also %enumer

     Examples:

          (%i1) [sqrt(2), sin(1), 1/(1+sqrt(3))];
                                                  1
          (%o1)            [sqrt(2), sin(1), -----------]
                                             sqrt(3) + 1
          (%i2) [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
          (%o2) [1.414213562373095, .8414709848078965, .3660254037844387]

     Numerical evaluation Evaluation flags

 -- Option variable: numer_pbranch
     Default value: false

     The option variable numer_pbranch controls the numerical evaluation of the power of a negative integer, rational, or floating point number.  When numer_pbranch is true and the exponent is a floating point number or the option variable numer is true too, Maxima evaluates the numerical result using the principal branch.  Otherwise a simplified, but not an evaluated result is returned.

     Examples:

          (%i1) (-2)^0.75;
          (%o1) (-2)^0.75

          (%i2) (-2)^0.75,numer_pbranch:true;
          (%o2) 1.189207115002721*%i-1.189207115002721

          (%i3) (-2)^(3/4);
          (%o3) (-1)^(3/4)*2^(3/4)

          (%i4) (-2)^(3/4),numer;
          (%o4) 1.681792830507429*(-1)^0.75

          (%i5) (-2)^(3/4),numer,numer_pbranch:true;
          (%o5) 1.189207115002721*%i-1.189207115002721

     Numerical evaluation

 -- Function: numerval (X_1, EXPR_1, ..., VAR_N, EXPR_N)

     Declares the variables x_1, ..., X_N to have numeric values equal to expr_1, ..., expr_n. The numeric value is evaluated and substituted for the variable in any expressions in which the variable occurs if the numer flag is true.  See also ev

     The expressions expr_1, ..., expr_n can be any expressions, not necessarily numeric.

     Declarations and inferences Numerical evaluation

 -- Function: oddp (EXPR)

     is true if EXPR is an odd integer. false is returned in all other cases.

     Predicate functions

 -- Option variable: promote_float_to_bigfloat
     Default value: true

     When promote_float_to_bigfloat is true, the result of any floating point calculation that would normally cause a floating point overflow is replaced by a bigfloat number that represents the result. Note that this automatic promotion only happens in interpreted code: compiled code is not affected.

     This automatic conversion is often convenient, but can be unhelpful in some cases. For example, it can actually cause a loss of precision if fpprec is currently smaller than the precision in a floating point number. To disable this behaviour, set promote_float_to_bigfloat to false.

     Numerical evaluation

 -- Option variable: ratepsilon
     Default value: 2.0e-15

     ratepsilon is the tolerance used in the conversion of floating point numbers to rational numbers, when the option variable bftorat has the value false.  See bftorat for an example.

     Numerical evaluation Rational expressions

 -- Function: rationalize (EXPR)

     Convert all double floats and big floats in the Maxima expression EXPR to their exact rational equivalents.  If you are not familiar with the binary representation of floating point numbers, you might be surprised that rationalize (0.1) does not equal 1/10.  This behavior isn't special to Maxima -- the number 1/10 has a repeating, not a terminating, binary representation.

          (%i1) rationalize (0.5);
                                          1
          (%o1)                           -
                                          2
          (%i2) rationalize (0.1);
                                         1
          (%o2)                          --
                                         10
          (%i3) fpprec : 5$
          (%i4) rationalize (0.1b0);
                                       209715
          (%o4)                        -------
                                       2097152
          (%i5) fpprec : 20$
          (%i6) rationalize (0.1b0);
                               236118324143482260685
          (%o6)                ----------------------
                               2361183241434822606848
          (%i7) rationalize (sin (0.1*x + 5.6));
                                        x    28
          (%o7)                     sin(-- + --)
                                        10   5

     Numerical evaluation

 -- Function: ratnump (EXPR)

     Returns true if EXPR is a literal integer or ratio of literal integers, otherwise false.

     Predicate functions Rational expressions

Strings
=======

Introduction to Strings
-----------------------

Strings (quoted character sequences) are enclosed in double quote marks " for input, and displayed with or without the quote marks, depending on the global variable stringdisp

Strings may contain any characters, including embedded tab, newline, and carriage return characters.  The sequence \" is recognized as a literal double quote, and \\ as a literal backslash.  When backslash appears at the end of a line, the backslash and the line termination (either newline or carriage return and newline) are ignored, so that the string continues with the next line.  No other special combinations of backslash with another character are recognized; when backslash appears before any character other than ", \, or a line termination, the backslash is ignored.  There is no way to represent a special character (such as tab, newline, or carriage return) except by embedding the literal character in the string.

There is no character type in Maxima; a single character is represented as a one-character string.

The stringproc add-on package contains many functions for working with strings.

Examples:

     (%i1) s_1 : "This is a string.";
     (%o1)               This is a string.
     (%i2) s_2 : "Embedded \"double quotes\" and backslash \\ characters.";
     (%o2) Embedded "double quotes" and backslash \ characters.
     (%i3) s_3 : "Embedded line termination
     in this string.";
     (%o3) Embedded line termination
     in this string.
     (%i4) s_4 : "Ignore the \
     line termination \
     characters in \
     this string.";
     (%o4) Ignore the line termination characters in this string.
     (%i5) stringdisp : false;
     (%o5)                         false
     (%i6) s_1;
     (%o6)                   This is a string.
     (%i7) stringdisp : true;
     (%o7)                         true
     (%i8) s_1;
     (%o8)                  "This is a string."

Syntax

Functions and Variables for Strings
-----------------------------------

 -- Function: concat (ARG_1, ARG_2, ...)

     Concatenates its arguments.  The arguments must evaluate to atoms.  The return value is a symbol if the first argument is a symbol and a string otherwise.

     concat evaluates its arguments.  The single quote ' prevents evaluation.

          (%i1) y: 7$
          (%i2) z: 88$
          (%i3) concat (y, z/2);
          (%o3)                          744
          (%i4) concat ('y, z/2);
          (%o4)                          y44

     A symbol constructed by concat may be assigned a value and appear in expressions.  The :: (double colon) assignment operator evaluates its left-hand side.

          (%i5) a: concat ('y, z/2);
          (%o5)                          y44
          (%i6) a:: 123;
          (%o6)                          123
          (%i7) y44;
          (%o7)                          123
          (%i8) b^a;

                                         y44
          (%o8)                         b

          (%i9) %, numer;
                                         123
          (%o9)                         b

     Note that although concat (1, 2) looks like a number, it is a string.

          (%i10) concat (1, 2) + 3;
          (%o10)                       12 + 3

     Expressions Strings

 -- Function: sconcat (ARG_1, ARG_2, ...)

     Concatenates its arguments into a string.  Unlike concat the arguments do not need to be atoms.

          (%i1) sconcat ("xx[", 3, "]:", expand ((x+y)^3));
          (%o1)               xx[3]:y^3+3*x*y^2+3*x^2*y+x^3

     Expressions Strings

 -- Function: string (EXPR)

     Converts expr to Maxima's linear notation just as if it had been typed in.

     The return value of string is a string, and thus it cannot be used in a computation.

     Strings

 -- Option variable: stringdisp
     Default value: false

     When stringdisp is true, strings are displayed enclosed in double quote marks.  Otherwise, quote marks are not displayed.

     stringdisp is always true when displaying a function definition.

     Examples:

          (%i1) stringdisp: false$
          (%i2) "This is an example string.";
          (%o2)              This is an example string.

          (%i3) foo () :=
                print ("This is a string in a function definition.");

          (%o3) foo() :=
                        print("This is a string in a function definition.")
          (%i4) stringdisp: true$
          (%i5) "This is an example string.";
          (%o5)             "This is an example string."

     Display flags and variables