Maxima 5.42.455.gc5fa8d39c Manual

Category: Debugging · Category: Global variables

Option variable: testsuite_files

testsuite_files is the set of tests to be run by run_testsuite. It is a list of names of the files containing the tests to run. If some of the tests in a file are known to fail, then instead of listing the name of the file, a list containing the file name and the test numbers that fail is used.

For example, this is a part of the default set of tests:

 ["rtest13s", ["rtest14", 57, 63]]

This specifies the testsuite consists of the files "rtest13s" and "rtest14", but "rtest14" contains two tests that are known to fail: 57 and 63.

Option variable: share_testsuite_files

share_testsuite_files is the set of tests from the share directory that is run as a part of the test suite by run_testsuite..

Category: Debugging · Category: Global variables

Function: bug_report ()

Prints out Maxima and Lisp version numbers, and gives a link to the Maxima project bug report web page. The version information is the same as reported by build_info.

When a bug is reported, it is helpful to copy the Maxima and Lisp version information into the bug report.

bug_report returns an empty string "".

Category: Console interaction

Function: build_info ()

Returns a summary of the parameters of the Maxima build, as a Maxima structure (defined by defstruct). The fields of the structure are: version, timestamp, host, lisp_name, and lisp_version. When the pretty-printer is enabled (via display2d), the structure is displayed as a short table.

3 Help

3.1 Documentation

The Maxima on-line user’s manual can be viewed in different forms. From the Maxima interactive prompt, the user’s manual is viewed as plain text by the ? command (i.e., the describe function). The user’s manual is viewed as info hypertext by the info viewer program and as a web page by any ordinary web browser.

example displays examples for many Maxima functions. For example,

(%i1) example (integrate);

yields

(%i2) test(f):=block([u],u:integrate(f,x),ratsimp(f-diff(u,x)))
(%o2) test(f) := block([u], u : integrate(f, x),
                                         ratsimp(f - diff(u, x)))
(%i3) test(sin(x))
(%o3)                           0
(%i4) test(1/(x+1))
(%o4)                           0
(%i5) test(1/(x^2+1))
(%o5)                           0

and additional output.

3.2 Functions and Variables for Help

Function: apropos (string)

Searches for Maxima names which have string appearing anywhere within them. Thus, apropos (exp) returns a list of all the flags and functions which have exp as part of their names, such as expand, exp, and exponentialize. Thus if you can only remember part of the name of something you can use this command to find the rest of the name. Similarly, you could say apropos (tr_) to find a list of many of the switches relating to the translator, most of which begin with tr_.

apropos("") returns a list with all Maxima names.

apropos returns the empty list [], if no name is found.

Example:

Show all Maxima symbols which have "gamma" in the name:

(%i1) apropos("gamma");
(%o1) [%gamma, gamma, gammalim, gamma_expand, gamma_incomplete_lower, 
gamma_incomplete, gamma_incomplete_generalized, 
gamma_incomplete_regularized, Gamma, log_gamma, makegamma, 
prefer_gamma_incomplete, gamma-incomplete, 
gamma_incomplete_generalized_regularized]

Category: Help

Function: demo (filename)

Evaluates Maxima expressions in filename and displays the results. demo pauses after evaluating each expression and continues after the user enters a carriage return. (If running in Xmaxima, demo may need to see a semicolon ; followed by a carriage return.)

demo searches the list of directories file_search_demo to find filename. If the file has the suffix dem, the suffix may be omitted. See also file_search.

demo evaluates its argument. demo returns the name of the demonstration file.

Example:

(%i1) demo ("disol");

batching /home/wfs/maxima/share/simplification/disol.dem
 At the _ prompt, type ';' followed by enter to get next demo
(%i2)                      load("disol")

_
(%i3)           exp1 : a (e (g + f) + b (d + c))
(%o3)               a (e (g + f) + b (d + c))

_
(%i4)                disolate(exp1, a, b, e)
(%t4)                         d + c

(%t5)                         g + f

(%o5)                   a (%t5 e + %t4 b)

_

Category: Help · Category: Console interaction · Category: File input

Function: describe
    describe (string)
    describe (string, exact)
    describe (string, inexact)

describe(string) is equivalent to describe(string, exact).

describe(string, exact) finds an item with title equal (case-insensitive) to string, if there is any such item.

describe(string, inexact) finds all documented items which contain string in their titles. If there is more than one such item, Maxima asks the user to select an item or items to display.

At the interactive prompt, ? foo (with a space between ? and foo) is equivalent to describe("foo", exact), and ?? foo is equivalent to describe("foo", inexact).

describe("", inexact) yields a list of all topics documented in the on-line manual.

describe quotes its argument. describe returns true if some documentation is found, otherwise false.

4 Command Line

4.1 Introduction to Command Line

4.2 Functions and Variables for Command Line

System variable: __

__ is the input expression currently being evaluated. That is, while an input expression expr is being evaluated, __ is expr.

__ is assigned the input expression before the input is simplified or evaluated. However, the value of __ is simplified (but not evaluated) when it is displayed.

__ is recognized by batch and load. In a file processed by batch, __ has the same meaning as at the interactive prompt. In a file processed by load, __ is bound to the input expression most recently entered at the interactive prompt or in a batch file; __ is not bound to the input expressions in the file being processed. In particular, when load (filename) is called from the interactive prompt, __ is bound to load (filename) while the file is being processed.

4.3 Functions and Variables for Display

Option variable: %edispflag

Default value: false

When %edispflag is true, Maxima displays %e to a negative exponent as a quotient. For example, %e^-x is displayed as 1/%e^x. See also exptdispflag.

Example:

(%i1) %e^-10;
                               - 10
(%o1)                        %e

(%i2) %edispflag:true$

(%i3) %e^-10;
                               1
(%o3)                         ----
                                10
                              %e

Category: Exponential and logarithm functions · Category: Display flags and variables

Option variable: absboxchar

Default value: !

absboxchar is the character used to draw absolute value signs around expressions which are more than one line tall.

Example:

(%i1) abs((x^3+1));
                            ! 3    !
(%o1)                       !x  + 1!

Category: Display flags and variables

Function: disp (expr_1, expr_2, …)

is like display but only the value of the arguments are displayed rather than equations. This is useful for complicated arguments which don’t have names or where only the value of the argument is of interest and not the name.

5 Data Types and Structures

5.1 Numbers

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

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

Category: Numerical evaluation · Category: Predicate functions

Function: bfloatp (expr)

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

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

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.

Category: Predicate functions

Function: evenp (expr)

Returns true if expr is a literal even integer, otherwise false.

evenp returns false if expr is a symbol, even if expr is declared even.

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.

Category: Numerical evaluation · Category: 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).

Category: Numerical evaluation · Category: Predicate functions

Function: floatnump (expr)

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

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.

5.2 Strings

5.2.1 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
(%o3) Embedded line termination
in this string.

(%i4) in this string.";
(%o4) Ignore the line termination characters in this string.

(%i5) s_4 : "Ignore the \
(%o5)                         false

(%i6) line termination \
(%o6)                   This is a string.

(%i7) characters in \
(%o7)                         true

(%i8) this string.";
(%o8)                  "This is a string."

(%i9) stringdisp : false;

Category: Syntax

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

5.3 Constants

5.3.1 Functions and Variables for Constants

Constant: %e

%e represents the base of the natural logarithm, also known as Euler’s number. The numeric value of %e is the double-precision floating-point value 2.718281828459045d0.

Constant: %i

%i represents the imaginary unit, sqrt(- 1).

Constant: false

false represents the Boolean constant of the same name. Maxima implements false by the value NIL in Lisp.

Constant: %gamma

The Euler-Mascheroni constant, 0.5772156649015329 ....

Category: Expressions · Category: Arrays

Constant: ind

ind represents a bounded, indefinite result.

5.4 Lists

5.4.1 Introduction to Lists

Lists are the basic building block for Maxima and Lisp. All data types other than arrays, hashed arrays and numbers are represented as Lisp lists, These Lisp lists have the form

((MPLUS) $A 2)

to indicate an expression a+2. At Maxima level one would see the infix notation a+2. Maxima also has lists which are printed as

[1, 2, 7, x+y]

for a list with 4 elements. Internally this corresponds to a Lisp list of the form

((MLIST) 1 2 7 ((MPLUS) $X $Y))

The flag which denotes the type field of the Maxima expression is a list itself, since after it has been through the simplifier the list would become

((MLIST SIMP) 1 2 7 ((MPLUS SIMP) $X $Y))

5.4.2 Functions and Variables for Lists

Operator: [

Operator: ]

[ and ] mark the beginning and end, respectively, of a list.

[ and ] also enclose the subscripts of a list, array, hashed array, or memoizing function. Note that other than for arrays accessing the nth element of a list may need an amount of time that is roughly proportional to n, See Performance considerations for Lists.

Note that if an element of a subscripted variable is written to before a list or an array of this name is declared a hashed array (see Arrays) is created, not a list.

Examples:

(%i1) x: [a, b, c];
(%o1)                       [a, b, c]

(%i2) x[3];
(%o2)                           c

(%i3) array (y, fixnum, 3);
(%o3)                           y

(%i4) y[2]: %pi;
(%o4)                          %pi

(%i5) y[2];
(%o5)                          %pi

(%i6) z['foo]: 'bar;
(%o6)                          bar

(%i7) z['foo];
(%o7)                          bar

(%i8) g[k] := 1/(k^2+1);
                                  1
(%o8)                     g  := ------
                           k     2
                                k  + 1

(%i9) g[10];
                                1
(%o9)                          ---
                               101

Category: Lists · Category: Operators

Function: append (list_1, …, list_n)

Returns a single list of the elements of list_1 followed by the elements of list_2, … append also works on general expressions, e.g. append (f(a,b), f(c,d,e)); yields f(a,b,c,d,e).

5.4.3 Performance considerations for Lists

Lists provide efficient ways of appending and removing elements. They can be created without knowing their final dimensions. Lisp provides efficient means of copying and handling lists. Also nested lists do not need to be strictly rectangular. These advantages over declared arrays come with the drawback that the amount of time needed for accessing a random element within a list may be roughly proportional to the element’s distance from its beginning. Efficient traversal of lists is still possible, though, by using the list as a stack or a fifo:

(%i1) l:[Test,1,2,3,4];
(%o1)                  [Test, 1, 2, 3, 4]

(%i2) while l # [] do
   disp(pop(l));
                              Test

                                1

                                2

                                3

                                4

(%o2)                         done

Another even faster example would be:

(%i1) l:[Test,1,2,3,4];
(%o1)                  [Test, 1, 2, 3, 4]

(%i2) for i in l do
   disp(pop(l));
                              Test

                                1

                                2

                                3

                                4

(%o2)                         done

Beginning traversal with the last element of a list is possible after reversing the list using reverse (). If the elements of a long list need to be processed in a different order performance might be increased by converting the list into a declared array first.

It is also to note that the ending condition of for loops is tested for every iteration which means that the result of a length should be cached if it is used in the ending condition:

(%i1) l:makelist(i,i,1,100000)$

(%i2) lngth:length(l);
(%o2)                        100000

(%i3) x:1;
(%o3)                           1

(%i4) for i:1 thru lngth do
    x:x+1$

(%i5) x;
(%o5)                        100001

5.5 Arrays

Maxima supports 3 array-like constructs:

If one tries to write to an indexed variable without creating a list first an undeclared array (also named hashed array) is created that grows dynamically and allows numbers, symbols and strings as indices:
```
(%i1) a["feww"]:1;
(%o1)                           1
```
```
(%i2) a[qqwdqwd]:3;
(%o2)                           3
```
```
(%i3) a[5]:99;
(%o3)                          99
```
```
(%i4) a[qqwdqwd];
(%o4)                           3
```
```
(%i5) a[5];
(%o5)                          99
```
```
(%i6) a["feww"];
(%o6)                           1
```
Since lisp handles hashed arrays and memoizing functions similar to arrays many of the functions that can be applied to arrays can be applied to them, as well.
Lists (see makelist allow for fast addition and removal of elements, can be created without knowing their final size.
Declared arrays that allow fast access to random elements at the cost that their size needs to be known at construction time. (See Performance considerations for Lists.)

5.5.1 Functions and Variables for Arrays

Function: array
    array (name, dim_1, …, dim_n)
    array (name, type, dim_1, …, dim_n)
    array ([name_1, …, name_m], dim_1, …, dim_n)

Creates an n-dimensional array. n may be less than or equal to 5. The subscripts for the i’th dimension are the integers running from 0 to dim_i.

array (name, dim_1, ..., dim_n) creates a general array.

array (name, type, dim_1, ..., dim_n) creates an array, with elements of a specified type. type can be fixnum for integers of limited size or flonum for floating-point numbers.

array ([name_1, ..., name_m], dim_1, ..., dim_n) creates m arrays, all of the same dimensions.

See also arraymake, arrayinfo and make_array.

Category: Arrays

Function: arrayapply (A, [i_1, …, i_n])

Evaluates A [i_1, ..., i_n], where A is an array and i_1, …, i_n are integers.

This is reminiscent of apply, except the first argument is an array instead of a function.

Function: arrayinfo (A)

Returns information about the array A. The argument A may be a declared array, a hashed array, a memoizing function, or a subscripted function.

For declared arrays, arrayinfo returns a list comprising the atom declared, the number of dimensions, and the size of each dimension. The elements of the array, both bound and unbound, are returned by listarray.

For undeclared arrays (hashed arrays), arrayinfo returns a list comprising the atom hashed, the number of subscripts, and the subscripts of every element which has a value. The values are returned by listarray.

For memoizing functions, arrayinfo returns a list comprising the atom hashed, the number of subscripts, and any subscript values for which there are stored function values. The stored function values are returned by listarray.

For subscripted functions, arrayinfo returns a list comprising the atom hashed, the number of subscripts, and any subscript values for which there are lambda expressions. The lambda expressions are returned by listarray.

5.6 Structures

5.6.1 Introduction to Structures

Maxima provides a simple data aggregate called a structure. A structure is an expression in which arguments are identified by name (the field name) and the expression as a whole is identified by its operator (the structure name). A field value can be any expression.

A structure is defined by the defstruct function; the global variable structures is the list of user-defined structures. The function new creates instances of structures. The @ operator refers to fields. kill(S) removes the structure definition S, and kill(x@ a) unbinds the field a of the structure instance x.

In the pretty-printing console display (with display2d equal to true), structure instances are displayed with the value of each field represented as an equation, with the field name on the left-hand side and the value on the right-hand side. (The equation is only a display construct; only the value is actually stored.) In 1-dimensional display (via grind or with display2d equal to false), structure instances are displayed without the field names.

There is no way to use a field name as a function name, although a field value can be a lambda expression. Nor can the values of fields be restricted to certain types; any field can be assigned any kind of expression. There is no way to make some fields accessible or inaccessible in different contexts; all fields are always visible.

5.6.2 Functions and Variables for Structures

Global variable: structures

structures is the list of user-defined structures defined by defstruct.

Category: Structures · Category: Global variables

Function: defstruct
defstruct (S(a_1, …, a_n))
defstruct (S(a_1 = v_1, …, a_n = v_n))

Define a structure, which is a list of named fields a_1, …, a_n associated with a symbol S. An instance of a structure is just an expression which has operator S and exactly n arguments. new(S) creates a new instance of structure S.

An argument which is just a symbol a specifies the name of a field. An argument which is an equation a = v specifies the field name a and its default value v. The default value can be any expression.

defstruct puts S on the list of user-defined structures, structures.

kill(S) removes S from the list of user-defined structures, and removes the structure definition.

Examples:

(%i1) defstruct (foo (a, b, c));
(%o1)                    [foo(a, b, c)]
(%i2) structures;
(%o2)                    [foo(a, b, c)]
(%i3) new (foo);
(%o3)                     foo(a, b, c)
(%i4) defstruct (bar (v, w, x = 123, y = %pi));
(%o4)             [bar(v, w, x = 123, y = %pi)]
(%i5) structures;
(%o5)      [foo(a, b, c), bar(v, w, x = 123, y = %pi)]
(%i6) new (bar);
(%o6)              bar(v, w, x = 123, y = %pi)
(%i7) kill (foo);
(%o7)                         done
(%i8) structures;
(%o8)             [bar(v, w, x = 123, y = %pi)]

Category: Structures

Function: new
new (S)
new (S (v_1, …, v_n))

new creates new instances of structures.

new(S) creates a new instance of structure S in which each field is assigned its default value, if any, or no value at all if no default was specified in the structure definition.

new(S(v_1, ..., v_n)) creates a new instance of S in which fields are assigned the values v_1, …, v_n.

Examples:

(%i1) defstruct (foo (w, x = %e, y = 42, z));
(%o1)              [foo(w, x = %e, y = 42, z)]
(%i2) new (foo);
(%o2)               foo(w, x = %e, y = 42, z)
(%i3) new (foo (1, 2, 4, 8));
(%o3)            foo(w = 1, x = 2, y = 4, z = 8)

Category: Structures

Operator: @

@ is the structure field access operator. The expression x@ a refers to the value of field a of the structure instance x. The field name is not evaluated.

If the field a in x has not been assigned a value, x@ a evaluates to itself.

kill(x@ a) removes the value of field a in x.

Examples:

(%i1) defstruct (foo (x, y, z));
(%o1)                    [foo(x, y, z)]
(%i2) u : new (foo (123, a - b, %pi));
(%o2)           foo(x = 123, y = a - b, z = %pi)
(%i3) u@z;
(%o3)                          %pi
(%i4) u@z : %e;
(%o4)                          %e
(%i5) u;
(%o5)            foo(x = 123, y = a - b, z = %e)
(%i6) kill (u@z);
(%o6)                         done
(%i7) u;
(%o7)              foo(x = 123, y = a - b, z)
(%i8) u@z;
(%o8)                          u@z

The field name is not evaluated.

(%i1) defstruct (bar (g, h));
(%o1)                      [bar(g, h)]
(%i2) x : new (bar);
(%o2)                       bar(g, h)
(%i3) x@h : 42;
(%o3)                          42
(%i4) h : 123;
(%o4)                          123
(%i5) x@h;
(%o5)                          42
(%i6) x@h : 19;
(%o6)                          19
(%i7) x;
(%o7)                    bar(g, h = 19)
(%i8) h;
(%o8)                          123

Category: Structures · Category: Operators

6 Expressions

6.1 Introduction to Expressions

There are a number of reserved words which should not be used as variable names. Their use would cause a possibly cryptic syntax error.

integrate            next           from                 diff            
in                   at             limit                sum             
for                  and            elseif               then            
else                 do             or                   if              
unless               product        while                thru            
step

Most things in Maxima are expressions. A sequence of expressions can be made into an expression by separating them by commas and putting parentheses around them. This is similar to the C comma expression.

(%i1) x: 3$
(%i2) (x: x+1, x: x^2);
(%o2)                          16
(%i3) (if (x > 17) then 2 else 4);
(%o3)                           4
(%i4) (if (x > 17) then x: 2 else y: 4, y+x);
(%o4)                          20

Even loops in Maxima are expressions, although the value they return is the not too useful done.

(%i1) y: (x: 1, for i from 1 thru 10 do (x: x*i))$
(%i2) y;
(%o2)                         done

Whereas what you really want is probably to include a third term in the comma expression which actually gives back the value.

(%i3) y: (x: 1, for i from 1 thru 10 do (x: x*i), x)$
(%i4) y;
(%o4)                        3628800

6.2 Nouns and Verbs

Maxima distinguishes between operators which are "nouns" and operators which are "verbs". A verb is an operator which can be executed. A noun is an operator which appears as a symbol in an expression, without being executed. By default, function names are verbs. A verb can be changed into a noun by quoting the function name or applying the nounify function. A noun can be changed into a verb by applying the verbify function. The evaluation flag nouns causes ev to evaluate nouns in an expression.

The verb form is distinguished by a leading dollar sign $ on the corresponding Lisp symbol. In contrast, the noun form is distinguished by a leading percent sign % on the corresponding Lisp symbol. Some nouns have special display properties, such as 'integrate and 'derivative (returned by diff), but most do not. By default, the noun and verb forms of a function are identical when displayed. The global flag noundisp causes Maxima to display nouns with a leading quote mark '.

See also noun, nouns, nounify, and verbify.

Examples:

(%i1) foo (x) := x^2;
                                     2
(%o1)                     foo(x) := x

(%i2) foo (42);
(%o2)                         1764

(%i3) 'foo (42);
(%o3)                        foo(42)

(%i4) 'foo (42), nouns;
(%o4)                         1764

(%i5) declare (bar, noun);
(%o5)                         done

(%i6) bar (x) := x/17;
                                    x
(%o6)                     bar(x) := --
                                    17

(%i7) bar (52);
(%o7)                        bar(52)

(%i8) bar (52), nouns;
(%o8)                        bar(52)

(%i9) integrate (1/x, x, 1, 42);
(%o9)                        log(42)

(%i10) 'integrate (1/x, x, 1, 42);
                             42
                            /
                            [   1
(%o10)                      I   - dx
                            ]   x
                            /
                             1

(%i11) ev (%, nouns);
(%o11)                       log(42)

Category: Evaluation · Category: Nouns and verbs

6.3 Identifiers

Maxima identifiers may comprise alphabetic characters, plus the numerals 0 through 9, plus any special character preceded by the backslash \ character.

A numeral may be the first character of an identifier if it is preceded by a backslash. Numerals which are the second or later characters need not be preceded by a backslash.

Characters may be declared alphabetic by the declare function. If so declared, they need not be preceded by a backslash in an identifier. The alphabetic characters are initially A through Z, a through z, %, and _.

Maxima is case-sensitive. The identifiers foo, FOO, and Foo are distinct. See Lisp and Maxima for more on this point.

A Maxima identifier is a Lisp symbol which begins with a dollar sign $. Any other Lisp symbol is preceded by a question mark ? when it appears in Maxima. See Lisp and Maxima for more on this point.

Examples:

(%i1) %an_ordinary_identifier42;
(%o1)               %an_ordinary_identifier42

(%i2) embedded\ spaces\ in\ an\ identifier;
(%o2)           embedded spaces in an identifier

(%i3) symbolp (%);
(%o3)                         true

(%i4) [foo+bar, foo\+bar];
(%o4)                 [foo + bar, foo+bar]

(%i5) [1729, \1729];
(%o5)                     [1729, 1729]

(%i6) [symbolp (foo\+bar), symbolp (\1729)];
(%o6)                     [true, true]

(%i7) [is (foo\+bar = foo+bar), is (\1729 = 1729)];
(%o7)                    [false, false]

(%i8) baz\~quux;
(%o8)                       baz~quux

(%i9) declare ("~", alphabetic);
(%o9)                         done

(%i10) baz~quux;
(%o10)                      baz~quux

(%i11) [is (foo = FOO), is (FOO = Foo), is (Foo = foo)];
(%o11)                [false, false, false]

(%i12) :lisp (defvar *my-lisp-variable* '$foo)
*MY-LISP-VARIABLE*

(%i12) ?\*my\-lisp\-variable\*;
(%o12)                         foo

Category: Syntax

6.4 Inequality

Maxima has the inequality operators <, <=, >=, >, #, and notequal. See if for a description of conditional expressions.

6.5 Functions and Variables for Expressions

Function: alias (new_name_1, old_name_1, …, new_name_n, old_name_n)

provides an alternate name for a (user or system) function, variable, array, etc. Any even number of arguments may be used.

Category: Declarations and inferences · Category: Global variables

System variable: aliases

Default value: []

aliases is the list of atoms which have a user defined alias (set up by the alias, ordergreat, orderless functions or by declaring the atom a noun with declare.)

Keyword: allbut

works with the part commands (i.e. part, inpart, substpart, substinpart, dpart, and lpart). For example,

(%i1) expr : e + d + c + b + a;
(%o1)                   e + d + c + b + a

(%i2) part (expr, [2, 5]);
(%o2)                         d + a

while

(%i1) expr : e + d + c + b + a;
(%o1)                   e + d + c + b + a

(%i2) part (expr, allbut (2, 5));
(%o2)                       e + c + b

allbut is also recognized by kill.

(%i1) [aa : 11, bb : 22, cc : 33, dd : 44, ee : 55];
(%o1)                 [11, 22, 33, 44, 55]

(%i2) kill (allbut (cc, dd));
(%o0)                         done

(%i1) [aa, bb, cc, dd];
(%o1)                   [aa, bb, 33, 44]

kill(allbut(a_1, a_2, ...)) has the effect of kill(all) except that it does not kill the symbols a_1, a_2, …

Function: args (expr)

Returns the list of arguments of expr, which may be any kind of expression other than an atom. Only the arguments of the top-level operator are extracted; subexpressions of expr appear as elements or subexpressions of elements of the list of arguments.

The order of the items in the list may depend on the global flag inflag.

args (expr) is equivalent to substpart ("[", expr, 0). See also substpart, apply, funmake, and op.

How to convert a matrix to a nested list:

(%i1) M:matrix([1,2],[3,4]);
                            [ 1  2 ]
(%o1)                       [      ]
                            [ 3  4 ]

(%i2) args(M);
(%o2)                   [[1, 2], [3, 4]]

Since maxima internally treats a sum of n terms as a summation command with n arguments args() can extract the list of terms in a sum:

(%i1) a+b+c;
(%o1)                       c + b + a

(%i2) args(%);
(%o2)                       [c, b, a]

Category: Expressions · Category: Predicate functions

Function: atom (expr)

Returns true if expr is atomic (i.e. a number, name or string) else false. Thus atom(5) is true while atom(a[1]) and atom(sin(x)) are false (assuming a[1] and x are unbound).

Function: box
box (expr)
box (expr, a)

Returns expr enclosed in a box. The return value is an expression with box as the operator and expr as the argument. A box is drawn on the display when display2d is true.

box (expr, a) encloses expr in a box labelled by the symbol a. The label is truncated if it is longer than the width of the box.

box evaluates its argument. However, a boxed expression does not evaluate to its content, so boxed expressions are effectively excluded from computations. rembox removes the box again.

boxchar is the character used to draw the box in box and in the dpart and lpart functions.

7 Operators

7.1 Introduction to operators

It is possible to define new operators with specified precedence, to undefine existing operators, or to redefine the precedence of existing operators. An operator may be unary prefix or unary postfix, binary infix, n-ary infix, matchfix, or nofix. "Matchfix" means a pair of symbols which enclose their argument or arguments, and "nofix" means an operator which takes no arguments. As examples of the different types of operators, there are the following.

unary prefix: negation - a
unary postfix: factorial a!
binary infix: exponentiation a^b
n-ary infix: addition a + b
matchfix: list construction [a, b]

(There are no built-in nofix operators; for an example of such an operator, see nofix.)

The mechanism to define a new operator is straightforward. It is only necessary to declare a function as an operator; the operator function might or might not be defined.

An example of user-defined operators is the following. Note that the explicit function call "dd" (a) is equivalent to dd a, likewise "<-" (a, b) is equivalent to a <- b. Note also that the functions "dd" and "<-" are undefined in this example.

(%i1) prefix ("dd");
(%o1)                          dd
(%i2) dd a;
(%o2)                         dd a
(%i3) "dd" (a);
(%o3)                         dd a
(%i4) infix ("<-");
(%o4)                          <-
(%i5) a <- dd b;
(%o5)                      a <- dd b
(%i6) "<-" (a, "dd" (b));
(%o6)                      a <- dd b

The Maxima functions which define new operators are summarized in this table, stating the default left and right binding powers (lbp and rbp, respectively). (Binding power determines operator precedence. However, since left and right binding powers can differ, binding power is somewhat more complicated than precedence.) Some of the operation definition functions take additional arguments; see the function descriptions for details.

prefix: rbp=180
postfix: lbp=180
infix: lbp=180, rbp=180
nary: lbp=180, rbp=180
matchfix: (binding power not applicable)
nofix: (binding power not applicable)

For comparison, here are some built-in operators and their left and right binding powers.

Operator   lbp     rbp

  :        180     20 
  ::       180     20 
  :=       180     20 
  ::=      180     20 
  !        160
  !!       160
  ^        140     139 
  .        130     129 
  *        120
  /        120     120 
  +        100     100 
  -        100     134 
  =        80      80 
  #        80      80 
  >        80      80 
  >=       80      80 
  <        80      80 
  <=       80      80 
  not              70 
  and      65
  or       60
  ,        10
  $        -1
  ;        -1

remove and kill remove operator properties from an atom. remove ("a", op) removes only the operator properties of a. kill ("a") removes all properties of a, including the operator properties. Note that the name of the operator must be enclosed in quotation marks.

(%i1) infix ("##");
(%o1)                          ##
(%i2) "##" (a, b) := a^b;
                                     b
(%o2)                     a ## b := a
(%i3) 5 ## 3;
(%o3)                          125
(%i4) remove ("##", op);
(%o4)                         done
(%i5) 5 ## 3;
Incorrect syntax: # is not a prefix operator
5 ##
  ^
(%i5) "##" (5, 3);
(%o5)                          125
(%i6) infix ("##");
(%o6)                          ##
(%i7) 5 ## 3;
(%o7)                          125
(%i8) kill ("##");
(%o8)                         done
(%i9) 5 ## 3;
Incorrect syntax: # is not a prefix operator
5 ##
  ^
(%i9) "##" (5, 3);
(%o9)                       ##(5, 3)

7.2 Arithmetic operators

Operator: +

Operator: -

Operator: *

Operator: /

Operator: ^

The symbols + * / and ^ represent addition, multiplication, division, and exponentiation, respectively. The names of these operators are "+" "*" "/" and "^", which may appear where the name of a function or operator is required.

The symbols + and - represent unary addition and negation, respectively, and the names of these operators are "+" and "-", respectively.

Subtraction a - b is represented within Maxima as addition, a + (- b). Expressions such as a + (- b) are displayed as subtraction. Maxima recognizes "-" only as the name of the unary negation operator, and not as the name of the binary subtraction operator.

Division a / b is represented within Maxima as multiplication, a * b^(- 1). Expressions such as a * b^(- 1) are displayed as division. Maxima recognizes "/" as the name of the division operator.

Addition and multiplication are n-ary, commutative operators. Division and exponentiation are binary, noncommutative operators.

Maxima sorts the operands of commutative operators to construct a canonical representation. For internal storage, the ordering is determined by orderlessp. For display, the ordering for addition is determined by ordergreatp, and for multiplication, it is the same as the internal ordering.

Arithmetic computations are carried out on literal numbers (integers, rationals, ordinary floats, and bigfloats). Except for exponentiation, all arithmetic operations on numbers are simplified to numbers. Exponentiation is simplified to a number if either operand is an ordinary float or bigfloat or if the result is an exact integer or rational; otherwise an exponentiation may be simplified to sqrt or another exponentiation or left unchanged.

Floating-point contagion applies to arithmetic computations: if any operand is a bigfloat, the result is a bigfloat; otherwise, if any operand is an ordinary float, the result is an ordinary float; otherwise, the operands are rationals or integers and the result is a rational or integer.

Arithmetic computations are a simplification, not an evaluation. Thus arithmetic is carried out in quoted (but simplified) expressions.

Arithmetic operations are applied element-by-element to lists when the global flag listarith is true, and always applied element-by-element to matrices. When one operand is a list or matrix and another is an operand of some other type, the other operand is combined with each of the elements of the list or matrix.

Examples:

Addition and multiplication are n-ary, commutative operators. Maxima sorts the operands to construct a canonical representation. The names of these operators are "+" and "*".

(%i1) c + g + d + a + b + e + f;
(%o1)               g + f + e + d + c + b + a
(%i2) [op (%), args (%)];
(%o2)              [+, [g, f, e, d, c, b, a]]
(%i3) c * g * d * a * b * e * f;
(%o3)                     a b c d e f g
(%i4) [op (%), args (%)];
(%o4)              [*, [a, b, c, d, e, f, g]]
(%i5) apply ("+", [a, 8, x, 2, 9, x, x, a]);
(%o5)                    3 x + 2 a + 19
(%i6) apply ("*", [a, 8, x, 2, 9, x, x, a]);
                                 2  3
(%o6)                       144 a  x

Division and exponentiation are binary, noncommutative operators. The names of these operators are "/" and "^".

(%i1) [a / b, a ^ b];
                              a   b
(%o1)                        [-, a ]
                              b
(%i2) [map (op, %), map (args, %)];
(%o2)              [[/, ^], [[a, b], [a, b]]]
(%i3) [apply ("/", [a, b]), apply ("^", [a, b])];
                              a   b
(%o3)                        [-, a ]
                              b

Subtraction and division are represented internally in terms of addition and multiplication, respectively.

(%i1) [inpart (a - b, 0), inpart (a - b, 1), inpart (a - b, 2)];
(%o1)                      [+, a, - b]
(%i2) [inpart (a / b, 0), inpart (a / b, 1), inpart (a / b, 2)];
                                   1
(%o2)                       [*, a, -]
                                   b

Computations are carried out on literal numbers. Floating-point contagion applies.

(%i1) 17 + b - (1/2)*29 + 11^(2/4);
                                       5
(%o1)                   b + sqrt(11) + -
                                       2
(%i2) [17 + 29, 17 + 29.0, 17 + 29b0];
(%o2)                   [46, 46.0, 4.6b1]

Arithmetic computations are a simplification, not an evaluation.

(%i1) simp : false;
(%o1)                         false
(%i2) '(17 + 29*11/7 - 5^3);
                              29 11    3
(%o2)                    17 + ----- - 5
                                7
(%i3) simp : true;
(%o3)                         true
(%i4) '(17 + 29*11/7 - 5^3);
                                437
(%o4)                         - ---
                                 7

Arithmetic is carried out element-by-element for lists (depending on listarith) and matrices.

(%i1) matrix ([a, x], [h, u]) - matrix ([1, 2], [3, 4]);

                        [ a - 1  x - 2 ]
(%o1)                   [              ]
                        [ h - 3  u - 4 ]

(%i2) 5 * matrix ([a, x], [h, u]);
                          [ 5 a  5 x ]
(%o2)                     [          ]
                          [ 5 h  5 u ]
(%i3) listarith : false;
(%o3)                         false
(%i4) [a, c, m, t] / [1, 7, 2, 9];
                          [a, c, m, t]
(%o4)                     ------------
                          [1, 7, 2, 9]
(%i5) [a, c, m, t] ^ x;
                                      x
(%o5)                     [a, c, m, t]
(%i6) listarith : true;
(%o6)                         true
(%i7) [a, c, m, t] / [1, 7, 2, 9];
                              c  m  t
(%o7)                     [a, -, -, -]
                              7  2  9
(%i8) [a, c, m, t] ^ x;
                          x   x   x   x
(%o8)                   [a , c , m , t ]

Operator: **

Exponentiation operator. Maxima recognizes ** as the same operator as ^ in input, and it is displayed as ^ in 1-dimensional output, or by placing the exponent as a superscript in 2-dimensional output.

The fortran function displays the exponentiation operator as **, whether it was input as ** or ^.

Examples:

(%i1) is (a**b = a^b);
(%o1)                         true
(%i2) x**y + x^z;
                              z    y
(%o2)                        x  + x
(%i3) string (x**y + x^z);
(%o3)                        x^z+x^y
(%i4) fortran (x**y + x^z);
      x**z+x**y
(%o4)                         done

Operator: ^^

Noncommutative exponentiation operator. ^^ is the exponentiation operator corresponding to noncommutative multiplication ., just as the ordinary exponentiation operator ^ corresponds to commutative multiplication *.

Noncommutative exponentiation is displayed by ^^ in 1-dimensional output, and by placing the exponent as a superscript within angle brackets < > in 2-dimensional output.

Examples:

(%i1) a . a . b . b . b + a * a * a * b * b;
                        3  2    <2>    <3>
(%o1)                  a  b  + a    . b
(%i2) string (a . a . b . b . b + a * a * a * b * b);
(%o2)                  a^3*b^2+a^^2 . b^^3

Operator: .

The dot operator, for matrix (non-commutative) multiplication. When "." is used in this way, spaces should be left on both sides of it, e.g. A . B This distinguishes it plainly from a decimal point in a floating point number.

See also Dot, dot0nscsimp, dot0simp, dot1simp, dotassoc, dotconstrules, dotdistrib, dotexptsimp, dotident, and dotscrules.

7.3 Relational operators

Operator: <

Operator: <=

Operator: >=

Operator: >

The symbols < <= >= and > represent less than, less than or equal, greater than or equal, and greater than, respectively. The names of these operators are "<" "<=" ">=" and ">", which may appear where the name of a function or operator is required.

These relational operators are all binary operators; constructs such as a < b < c are not recognized by Maxima.

Relational expressions are evaluated to Boolean values by the functions is and maybe, and the programming constructs if, while, and unless. Relational expressions are not otherwise evaluated or simplified to Boolean values, although the arguments of relational expressions are evaluated (when evaluation is not otherwise prevented by quotation).

When a relational expression cannot be evaluated to true or false, the behavior of is and if are governed by the global flag prederror. When prederror is true, is and if trigger an error. When prederror is false, is returns unknown, and if returns a partially-evaluated conditional expression.

maybe always behaves as if prederror were false, and while and unless always behave as if prederror were true.

Relational operators do not distribute over lists or other aggregates.

See also =, #, equal, and notequal.

Examples:

Relational expressions are evaluated to Boolean values by some functions and programming constructs.

(%i1) [x, y, z] : [123, 456, 789];
(%o1)                    [123, 456, 789]
(%i2) is (x < y);
(%o2)                         true
(%i3) maybe (y > z);
(%o3)                         false
(%i4) if x >= z then 1 else 0;
(%o4)                           0
(%i5) block ([S], S : 0, for i:1 while i <= 100 do S : S + i, 
             return (S));
(%o5)                         5050

Relational expressions are not otherwise evaluated or simplified to Boolean values, although the arguments of relational expressions are evaluated.

(%o1)                    [123, 456, 789]
(%i2) [x < y, y <= z, z >= y, y > z];
(%o2)    [123 < 456, 456 <= 789, 789 >= 456, 456 > 789]
(%i3) map (is, %);
(%o3)               [true, true, true, false]

7.4 Logical operators

Operator: and

The logical conjunction operator. and is an n-ary infix operator; its operands are Boolean expressions, and its result is a Boolean value.

and forces evaluation (like is) of one or more operands, and may force evaluation of all operands.

Operands are evaluated in the order in which they appear. and evaluates only as many of its operands as necessary to determine the result. If any operand is false, the result is false and no further operands are evaluated.

The global flag prederror governs the behavior of and when an evaluated operand cannot be determined to be true or false. and prints an error message when prederror is true. Otherwise, operands which do not evaluate to true or false are accepted, and the result is a Boolean expression.

and is not commutative: a and b might not be equal to b and a due to the treatment of indeterminate operands.

Operator: not

The logical negation operator. not is a prefix operator; its operand is a Boolean expression, and its result is a Boolean value.

not forces evaluation (like is) of its operand.

The global flag prederror governs the behavior of not when its operand cannot be determined to be true or false. not prints an error message when prederror is true. Otherwise, operands which do not evaluate to true or false are accepted, and the result is a Boolean expression.

Operator: or

The logical disjunction operator. or is an n-ary infix operator; its operands are Boolean expressions, and its result is a Boolean value.

or forces evaluation (like is) of one or more operands, and may force evaluation of all operands.

Operands are evaluated in the order in which they appear. or evaluates only as many of its operands as necessary to determine the result. If any operand is true, the result is true and no further operands are evaluated.

The global flag prederror governs the behavior of or when an evaluated operand cannot be determined to be true or false. or prints an error message when prederror is true. Otherwise, operands which do not evaluate to true or false are accepted, and the result is a Boolean expression.

or is not commutative: a or b might not be equal to b or a due to the treatment of indeterminate operands.

7.5 Operators for Equations

Operator: #

Represents the negation of syntactic equality =.

Note that because of the rules for evaluation of predicate expressions (in particular because not expr causes evaluation of expr), not a = b is equivalent to is(a # b), instead of a # b.

Examples:

(%i1) a = b;
(%o1)                         a = b
(%i2) is (a = b);
(%o2)                         false
(%i3) a # b;
(%o3)                         a # b
(%i4) not a = b;
(%o4)                         true
(%i5) is (a # b);
(%o5)                         true
(%i6) is (not a = b);
(%o6)                         true

Operator: =

The equation operator.

An expression a = b, by itself, represents an unevaluated equation, which might or might not hold. Unevaluated equations may appear as arguments to solve and algsys or some other functions.

The function is evaluates = to a Boolean value. is(a = b) evaluates a = b to true when a and b are identical. That is, a and b are atoms which are identical, or they are not atoms and their operators are identical and their arguments are identical. Otherwise, is(a = b) evaluates to false; it never evaluates to unknown. When is(a = b) is true, a and b are said to be syntactically equal, in contrast to equivalent expressions, for which is(equal(a, b)) is true. Expressions can be equivalent and not syntactically equal.

The negation of = is represented by #. As with =, an expression a # b, by itself, is not evaluated. is(a # b) evaluates a # b to true or false.

In addition to is, some other operators evaluate = and # to true or false, namely if, and, or, and not.

Note that because of the rules for evaluation of predicate expressions (in particular because not expr causes evaluation of expr), not a = b is equivalent to is(a # b), instead of a # b.

rhs and lhs return the right-hand and left-hand sides, respectively, of an equation or inequation.

7.6 Assignment operators

Operator: :

Assignment operator.

When the left-hand side is a simple variable (not subscripted), : evaluates its right-hand side and associates that value with the left-hand side.

When the left-hand side is a subscripted element of a list, matrix, declared Maxima array, or Lisp array, the right-hand side is assigned to that element. The subscript must name an existing element; such objects cannot be extended by naming nonexistent elements.

When the left-hand side is a subscripted element of a hashed array, the right-hand side is assigned to that element, if it already exists, or a new element is allocated, if it does not already exist.

When the left-hand side is a list of simple and/or subscripted variables, the right-hand side must evaluate to a list, and the elements of the right-hand side are assigned to the elements of the left-hand side, in parallel.

See also kill and remvalue, which undo the association between the left-hand side and its value.

Examples:

Assignment to a simple variable.

(%i1) a;
(%o1)                           a
(%i2) a : 123;
(%o2)                          123
(%i3) a;
(%o3)                          123

Assignment to an element of a list.

(%i1) b : [1, 2, 3];
(%o1)                       [1, 2, 3]
(%i2) b[3] : 456;
(%o2)                          456
(%i3) b;
(%o3)                      [1, 2, 456]

Assignment to a variable that neither is the name of a list nor of an array creates a hashed array.

(%i1) c[99] : 789;
(%o1)                          789
(%i2) c[99];
(%o2)                          789
(%i3) c;
(%o3)                           c
(%i4) arrayinfo (c);
(%o4)                   [hashed, 1, [99]]
(%i5) listarray (c);
(%o5)                         [789]

Multiple assignment.

(%i1) [a, b, c] : [45, 67, 89];
(%o1)                     [45, 67, 89]
(%i2) a;
(%o2)                          45
(%i3) b;
(%o3)                          67
(%i4) c;
(%o4)                          89

Multiple assignment is carried out in parallel. The values of a and b are exchanged in this example.

(%i1) [a, b] : [33, 55];
(%o1)                       [33, 55]
(%i2) [a, b] : [b, a];
(%o2)                       [55, 33]
(%i3) a;
(%o3)                          55
(%i4) b;
(%o4)                          33

Operator: ::

Assignment operator.

:: is the same as : (which see) except that :: evaluates its left-hand side as well as its right-hand side.

Examples:

(%i1) x : 'foo;
(%o1)                          foo
(%i2) x :: 123;
(%o2)                          123
(%i3) foo;
(%o3)                          123
(%i4) x : '[a, b, c];
(%o4)                       [a, b, c]
(%i5) x :: [11, 22, 33];
(%o5)                     [11, 22, 33]
(%i6) a;
(%o6)                          11
(%i7) b;
(%o7)                          22
(%i8) c;
(%o8)                          33

Category: Function definition · Category: Operators

Operator: ::=

Macro function definition operator. ::= defines a function (called a "macro" for historical reasons) which quotes its arguments, and the expression which it returns (called the "macro expansion") is evaluated in the context from which the macro was called. A macro function is otherwise the same as an ordinary function.

macroexpand returns a macro expansion (without evaluating it). macroexpand (foo (x)) followed by ''% is equivalent to foo (x) when foo is a macro function.

::= puts the name of the new macro function onto the global list macros. kill, remove, and remfunction unbind macro function definitions and remove names from macros.

fundef or dispfun return a macro function definition or assign it to a label, respectively.

Macro functions commonly contain buildq and splice expressions to construct an expression, which is then evaluated.

Examples

A macro function quotes its arguments, so message (1) shows y - z, not the value of y - z. The macro expansion (the quoted expression '(print ("(2) x is equal to", x))) is evaluated in the context from which the macro was called, printing message (2).

(%i1) x: %pi$
(%i2) y: 1234$
(%i3) z: 1729 * w$
(%i4) printq1 (x) ::= block (print ("(1) x is equal to", x),
      '(print ("(2) x is equal to", x)))$
(%i5) printq1 (y - z);
(1) x is equal to y - z
(2) x is equal to %pi
(%o5)                                 %pi

An ordinary function evaluates its arguments, so message (1) shows the value of y - z. The return value is not evaluated, so message (2) is not printed until the explicit evaluation ''%.

(%i1) x: %pi$
(%i2) y: 1234$
(%i3) z: 1729 * w$
(%i4) printe1 (x) := block (print ("(1) x is equal to", x),
      '(print ("(2) x is equal to", x)))$
(%i5) printe1 (y - z);
(1) x is equal to 1234 - 1729 w
(%o5)                     print((2) x is equal to, x)
(%i6) ''%;
(2) x is equal to %pi
(%o6)                                 %pi

macroexpand returns a macro expansion. macroexpand (foo (x)) followed by ''% is equivalent to foo (x) when foo is a macro function.

(%i1) x: %pi$
(%i2) y: 1234$
(%i3) z: 1729 * w$
(%i4) g (x) ::= buildq ([x], print ("x is equal to", x))$
(%i5) macroexpand (g (y - z));
(%o5)                     print(x is equal to, y - z)
(%i6) ''%;
x is equal to 1234 - 1729 w
(%o6)                            1234 - 1729 w
(%i7) g (y - z);
x is equal to 1234 - 1729 w
(%o7)                            1234 - 1729 w

Operator: :=

The function definition operator.

f(x_1, ..., x_n) := expr defines a function named f with arguments x_1, …, x_n and function body expr. := never evaluates the function body (unless explicitly evaluated by quote-quote ''). The function body is evaluated every time the function is called.

f[x_1, ..., x_n] := expr defines a so-called memoizing function. Its function body is evaluated just once for each distinct value of its arguments, and that value is returned, without evaluating the function body, whenever the arguments have those values again. (A function of this kind is also known as a “array function”.)

f[x_1, ..., x_n](y_1, ..., y_m) := expr is a special case of a memoizing function. f[x_1, ..., x_n] is a memoizing function which returns a lambda expression with arguments y_1, ..., y_m. The function body is evaluated once for each distinct value of x_1, ..., x_n, and the body of the lambda expression is that value.

When the last or only function argument x_n is a list of one element, the function defined by := accepts a variable number of arguments. Actual arguments are assigned one-to-one to formal arguments x_1, …, x_(n - 1), and any further actual arguments, if present, are assigned to x_n as a list.

All function definitions appear in the same namespace; defining a function f within another function g does not automatically limit the scope of f to g. However, local(f) makes the definition of function f effective only within the block or other compound expression in which local appears.

If some formal argument x_k is a quoted symbol, the function defined by := does not evaluate the corresponding actual argument. Otherwise all actual arguments are evaluated.

7.7 User defined operators

Function: infix
    infix (op)
    infix (op, lbp, rbp)
    infix (op, lbp, rbp, lpos, rpos, pos)

Declares op to be an infix operator. An infix operator is a function of two arguments, with the name of the function written between the arguments. For example, the subtraction operator - is an infix operator.

infix (op) declares op to be an infix operator with default binding powers (left and right both equal to 180) and parts of speech (left and right both equal to any).

infix (op, lbp, rbp) declares op to be an infix operator with stated left and right binding powers and default parts of speech (left and right both equal to any).

infix (op, lbp, rbp, lpos, rpos, pos) declares op to be an infix operator with stated left and right binding powers and parts of speech lpos, rpos, and pos for the left operand, the right operand, and the operator result, respectively.

"Part of speech", in reference to operator declarations, means expression type. Three types are recognized: expr, clause, and any, indicating an algebraic expression, a Boolean expression, or any kind of expression, respectively. Maxima can detect some syntax errors by comparing the declared part of speech to an actual expression.

The precedence of op with respect to other operators derives from the left and right binding powers of the operators in question. If the left and right binding powers of op are both greater the left and right binding powers of some other operator, then op takes precedence over the other operator. If the binding powers are not both greater or less, some more complicated relation holds.

The associativity of op depends on its binding powers. Greater left binding power (lbp) implies an instance of op is evaluated before other operators to its left in an expression, while greater right binding power (rbp) implies an instance of op is evaluated before other operators to its right in an expression. Thus greater lbp makes op right-associative, while greater rbp makes op left-associative. If lbp is equal to rbp, op is left-associative.

Category: Operators · Category: Declarations and inferences · Category: Syntax

Examples:

If the left and right binding powers of op are both greater the left and right binding powers of some other operator, then op takes precedence over the other operator.

(%i1) :lisp (get '$+ 'lbp)
100
(%i1) :lisp (get '$+ 'rbp)
100
(%i1) infix ("##", 101, 101);
(%o1)                          ##
(%i2) "##"(a, b) := sconcat("(", a, ",", b, ")");
(%o2)       (a ## b) := sconcat("(", a, ",", b, ")")
(%i3) 1 + a ## b + 2;
(%o3)                       (a,b) + 3
(%i4) infix ("##", 99, 99);
(%o4)                          ##
(%i5) 1 + a ## b + 2;
(%o5)                       (a+1,b+2)

Greater lbp makes op right-associative, while greater rbp makes op left-associative.

(%i1) infix ("##", 100, 99);
(%o1)                          ##
(%i2) "##"(a, b) := sconcat("(", a, ",", b, ")")$
(%i3) foo ## bar ## baz;
(%o3)                    (foo,(bar,baz))
(%i4) infix ("##", 100, 101);
(%o4)                          ##
(%i5) foo ## bar ## baz;
(%o5)                    ((foo,bar),baz)

Maxima can detect some syntax errors by comparing the declared part of speech to an actual expression.

(%i1) infix ("##", 100, 99, expr, expr, expr);
(%o1)                          ##
(%i2) if x ## y then 1 else 0;
Incorrect syntax: Found algebraic expression where logical
expression expected
if x ## y then 
             ^
(%i2) infix ("##", 100, 99, expr, expr, clause);
(%o2)                          ##
(%i3) if x ## y then 1 else 0;
(%o3)                if x ## y then 1 else 0

Function: matchfix
matchfix (ldelimiter, rdelimiter)
matchfix (ldelimiter, rdelimiter, arg_pos, pos)

Declares a matchfix operator with left and right delimiters ldelimiter and rdelimiter. The delimiters are specified as strings.

A "matchfix" operator is a function of any number of arguments, such that the arguments occur between matching left and right delimiters. The delimiters may be any strings, so long as the parser can distinguish the delimiters from the operands and other expressions and operators. In practice this rules out unparseable delimiters such as %, ,, $ and ;, and may require isolating the delimiters with white space. The right delimiter can be the same or different from the left delimiter.

A left delimiter can be associated with only one right delimiter; two different matchfix operators cannot have the same left delimiter.

An existing operator may be redeclared as a matchfix operator without changing its other properties. In particular, built-in operators such as addition + can be declared matchfix, but operator functions cannot be defined for built-in operators.

The command matchfix (ldelimiter, rdelimiter, arg_pos, pos) declares the argument part-of-speech arg_pos and result part-of-speech pos, and the delimiters ldelimiter and rdelimiter.

The function to carry out a matchfix operation is an ordinary user-defined function. The operator function is defined in the usual way with the function definition operator := or define. The arguments may be written between the delimiters, or with the left delimiter as a quoted string and the arguments following in parentheses. dispfun (ldelimiter) displays the function definition.

The only built-in matchfix operator is the list constructor [ ]. Parentheses ( ) and double-quotes " " act like matchfix operators, but are not treated as such by the Maxima parser.

matchfix evaluates its arguments. matchfix returns its first argument, ldelimiter.

Examples:

Delimiters may be almost any strings.

(%i1) matchfix ("@@", "~");
(%o1)                          @@
(%i2) @@ a, b, c ~;
(%o2)                      @@a, b, c~
(%i3) matchfix (">>", "<<");
(%o3)                          >>
(%i4) >> a, b, c <<;
(%o4)                      >>a, b, c<<
(%i5) matchfix ("foo", "oof");
(%o5)                          foo
(%i6) foo a, b, c oof;
(%o6)                     fooa, b, coof
(%i7) >> w + foo x, y oof + z << / @@ p, q ~;
                     >>z + foox, yoof + w<<
(%o7)                ----------------------
                            @@p, q~

Matchfix operators are ordinary user-defined functions.

(%i1) matchfix ("!-", "-!");
(%o1)                         "!-"
(%i2) !- x, y -! := x/y - y/x;
                                    x   y
(%o2)                   !-x, y-! := - - -
                                    y   x
(%i3) define (!-x, y-!, x/y - y/x);
                                    x   y
(%o3)                   !-x, y-! := - - -
                                    y   x
(%i4) define ("!-" (x, y), x/y - y/x);
                                    x   y
(%o4)                   !-x, y-! := - - -
                                    y   x
(%i5) dispfun ("!-");
                                    x   y
(%t5)                   !-x, y-! := - - -
                                    y   x

(%o5)                         done
(%i6) !-3, 5-!;
                                16
(%o6)                         - --
                                15
(%i7) "!-" (3, 5);
                                16
(%o7)                         - --
                                15

Category: Syntax · Category: Operators

Function: nary
nary (op)
nary (op, bp, arg_pos, pos)

An nary operator is used to denote a function of any number of arguments, each of which is separated by an occurrence of the operator, e.g. A+B or A+B+C. The nary("x") function is a syntax extension function to declare x to be an nary operator. Functions may be declared to be nary. If declare(j,nary); is done, this tells the simplifier to simplify, e.g. j(j(a,b),j(c,d)) to j(a, b, c, d).

Function: nofix
nofix (op)
nofix (op, pos)

nofix operators are used to denote functions of no arguments. The mere presence of such an operator in a command will cause the corresponding function to be evaluated. For example, when one types "exit;" to exit from a Maxima break, "exit" is behaving similar to a nofix operator. The function nofix("x") is a syntax extension function which declares x to be a nofix operator.

Function: postfix
postfix (op)
postfix (op, lbp, lpos, pos)

postfix operators like the prefix variety denote functions of a single argument, but in this case the argument immediately precedes an occurrence of the operator in the input string, e.g. 3!. The postfix("x") function is a syntax extension function to declare x to be a postfix operator.

Function: prefix
prefix (op)
prefix (op, rbp, rpos, pos)

A prefix operator is one which signifies a function of one argument, which argument immediately follows an occurrence of the operator. prefix("x") is a syntax extension function to declare x to be a prefix operator.

8 Evaluation

8.1 Functions and Variables for Evaluation

Operator: '

The single quote operator ' prevents evaluation.

Applied to a symbol, the single quote prevents evaluation of the symbol.

Applied to a function call, the single quote prevents evaluation of the function call, although the arguments of the function are still evaluated (if evaluation is not otherwise prevented). The result is the noun form of the function call.

Applied to a parenthesized expression, the single quote prevents evaluation of all symbols and function calls in the expression. E.g., '(f(x)) means do not evaluate the expression f(x). 'f(x) (with the single quote applied to f instead of f(x)) means return the noun form of f applied to [x].

The single quote does not prevent simplification.

When the global flag noundisp is true, nouns display with a single quote. This switch is always true when displaying function definitions.

See also the quote-quote operator '' and nouns.

Examples:

Applied to a symbol, the single quote prevents evaluation of the symbol.

(%i1) aa: 1024;
(%o1)                         1024
(%i2) aa^2;
(%o2)                        1048576
(%i3) 'aa^2;
                                 2
(%o3)                          aa
(%i4) ''%;
(%o4)                        1048576

Applied to a function call, the single quote prevents evaluation of the function call. The result is the noun form of the function call.

(%i1) x0: 5;
(%o1)                           5
(%i2) x1: 7;
(%o2)                           7
(%i3) integrate (x^2, x, x0, x1);
                               218
(%o3)                          ---
                                3
(%i4) 'integrate (x^2, x, x0, x1);

                             7
                            /
                            [   2
(%o4)                       I  x  dx
                            ]
                            /
                             5

(%i5) %, nouns;
                               218
(%o5)                          ---
                                3

Applied to a parenthesized expression, the single quote prevents evaluation of all symbols and function calls in the expression.

(%i1) aa: 1024;
(%o1)                         1024
(%i2) bb: 19;
(%o2)                          19
(%i3) sqrt(aa) + bb;
(%o3)                          51
(%i4) '(sqrt(aa) + bb);
(%o4)                     bb + sqrt(aa)
(%i5) ''%;
(%o5)                          51

The single quote does not prevent simplification.

(%i1) sin (17 * %pi) + cos (17 * %pi);
(%o1)                          - 1
(%i2) '(sin (17 * %pi) + cos (17 * %pi));
(%o2)                          - 1

Maxima considers floating point operations by its in-built mathematical functions to be a simplification.

(%i1) sin(1.0);
(%o1)                          .8414709848078965
(%i2) '(sin(1.0));
(%o2)                          .8414709848078965

When the global flag noundisp is true, nouns display with a single quote.

(%i1) x:%pi;
(%o1)                                 %pi
(%i2) bfloat(x);
(%o2)                         3.141592653589793b0
(%i3) sin(x);
(%o3)                                  0
(%i4) noundisp;
(%o4)                                false
(%i5) 'bfloat(x);
(%o5)                             bfloat(%pi)
(%i6) bfloat('x);
(%o6)                                  x
(%i7) 'sin(x);
(%o7)                                  0
(%i8) sin('x);
(%o8)                               sin(x)
(%i9) noundisp : not noundisp;
(%o9)                                true
(%i10) 'bfloat(x);
(%o10)                           'bfloat(%pi)
(%i11) bfloat('x);
(%o11)                                 x
(%i12) 'sin(x);
(%o12)                                 0
(%i13) sin('x);
(%o13)                              sin(x)
(%i14)

Operator: ''

The quote-quote operator '' (two single quote marks) modifies evaluation in input expressions.

Applied to a general expression expr, quote-quote causes the value of expr to be substituted for expr in the input expression.

Applied to the operator of an expression, quote-quote changes the operator from a noun to a verb (if it is not already a verb).

The quote-quote operator is applied by the input parser; it is not stored as part of a parsed input expression. The quote-quote operator is always applied as soon as it is parsed, and cannot be quoted. Thus quote-quote causes evaluation when evaluation is otherwise suppressed, such as in function definitions, lambda expressions, and expressions quoted by single quote '.

Quote-quote is recognized by batch and load.

See also ev, the single-quote operator ' and nouns.

Examples:

Applied to a general expression expr, quote-quote causes the value of expr to be substituted for expr in the input expression.

(%i1) expand ((a + b)^3);
                     3        2      2      3
(%o1)               b  + 3 a b  + 3 a  b + a
(%i2) [_, ''_];
                         3    3        2      2      3
(%o2)     [expand((b + a) ), b  + 3 a b  + 3 a  b + a ]
(%i3) [%i1, ''%i1];
                         3    3        2      2      3
(%o3)     [expand((b + a) ), b  + 3 a b  + 3 a  b + a ]
(%i4) [aa : cc, bb : dd, cc : 17, dd : 29];
(%o4)                   [cc, dd, 17, 29]
(%i5) foo_1 (x) := aa - bb * x;
(%o5)                 foo_1(x) := aa - bb x
(%i6) foo_1 (10);
(%o6)                      cc - 10 dd
(%i7) ''%;
(%o7)                         - 273
(%i8) ''(foo_1 (10));
(%o8)                         - 273
(%i9) foo_2 (x) := ''aa - ''bb * x;
(%o9)                 foo_2(x) := cc - dd x
(%i10) foo_2 (10);
(%o10)                        - 273
(%i11) [x0 : x1, x1 : x2, x2 : x3];
(%o11)                    [x1, x2, x3]
(%i12) x0;
(%o12)                         x1
(%i13) ''x0;
(%o13)                         x2
(%i14) '' ''x0;
(%o14)                         x3

Applied to the operator of an expression, quote-quote changes the operator from a noun to a verb (if it is not already a verb).

(%i1) declare (foo, noun);
(%o1)                         done
(%i2) foo (x) := x - 1729;
(%o2)                 ''foo(x) := x - 1729
(%i3) foo (100);
(%o3)                       foo(100)
(%i4) ''foo (100);
(%o4)                        - 1629

The quote-quote operator is applied by the input parser; it is not stored as part of a parsed input expression.

(%i1) [aa : bb, cc : dd, bb : 1234, dd : 5678];
(%o1)                 [bb, dd, 1234, 5678]
(%i2) aa + cc;
(%o2)                        dd + bb
(%i3) display (_, op (_), args (_));
                           _ = cc + aa

                         op(cc + aa) = +

                    args(cc + aa) = [cc, aa]

(%o3)                         done
(%i4) ''(aa + cc);
(%o4)                         6912
(%i5) display (_, op (_), args (_));
                           _ = dd + bb

                         op(dd + bb) = +

                    args(dd + bb) = [dd, bb]

(%o5)                         done

Quote-quote causes evaluation when evaluation is otherwise suppressed, such as in function definitions, lambda expressions, and expressions quoted by single quote '.

(%i1) foo_1a (x) := ''(integrate (log (x), x));
(%o1)               foo_1a(x) := x log(x) - x
(%i2) foo_1b (x) := integrate (log (x), x);
(%o2)           foo_1b(x) := integrate(log(x), x)
(%i3) dispfun (foo_1a, foo_1b);
(%t3)               foo_1a(x) := x log(x) - x

(%t4)           foo_1b(x) := integrate(log(x), x)

(%o4)                      [%t3, %t4]
(%i5) integrate (log (x), x);
(%o5)                     x log(x) - x
(%i6) foo_2a (x) := ''%;
(%o6)               foo_2a(x) := x log(x) - x
(%i7) foo_2b (x) := %;
(%o7)                    foo_2b(x) := %
(%i8) dispfun (foo_2a, foo_2b);
(%t8)               foo_2a(x) := x log(x) - x

(%t9)                    foo_2b(x) := %

(%o9)                      [%t7, %t8]
(%i10) F : lambda ([u], diff (sin (u), u));
(%o10)             lambda([u], diff(sin(u), u))
(%i11) G : lambda ([u], ''(diff (sin (u), u)));
(%o11)                  lambda([u], cos(u))
(%i12) '(sum (a[k], k, 1, 3) + sum (b[k], k, 1, 3));
(%o12)         sum(b , k, 1, 3) + sum(a , k, 1, 3)
                    k                  k
(%i13) '(''(sum (a[k], k, 1, 3)) + ''(sum (b[k], k, 1, 3)));
(%o13)             b  + a  + b  + a  + b  + a
                    3    3    2    2    1    1

Category: Operators · Category: Declarations and inferences

Function: ev (expr, arg_1, …, arg_n)

Evaluates the expression expr in the environment specified by the arguments arg_1, …, arg_n. The arguments are switches (Boolean flags), assignments, equations, and functions. ev returns the result (another expression) of the evaluation.

The evaluation is carried out in steps, as follows.

First the environment is set up by scanning the arguments which may be any or all of the following.
- simp causes expr to be simplified regardless of the setting of the switch simp which inhibits simplification if false.
- noeval suppresses the evaluation phase of ev (see step (4) below). This is useful in conjunction with the other switches and in causing expr to be resimplified without being reevaluated.
- nouns causes the evaluation of noun forms (typically unevaluated functions such as 'integrate or 'diff) in expr.
- expand causes expansion.
- expand (m, n) causes expansion, setting the values of maxposex and maxnegex to m and n respectively.
- detout causes any matrix inverses computed in expr to have their determinant kept outside of the inverse rather than dividing through each element.
- diff causes all differentiations indicated in expr to be performed.
- derivlist (x, y, z, ...) causes only differentiations with respect to the indicated variables. See also derivlist.
- risch causes integrals in expr to be evaluated using the Risch algorithm. See risch. The standard integration routine is invoked when using the special symbol nouns.
- float causes non-integral rational numbers to be converted to floating point.
- 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 numervals to be replaced by their values. It also sets the float switch on.
- pred causes predicates (expressions which evaluate to true or false) to be evaluated.
- eval causes an extra post-evaluation of expr to occur. (See step (5) below.) eval may occur multiple times. For each instance of eval, the expression is evaluated again.
- A where A is an atom declared to be an evaluation flag evflag causes A to be bound to true during the evaluation of expr.
- V: expression (or alternately V=expression) causes V to be bound to the value of expression during the evaluation of expr. Note that if V is a Maxima option, then expression is used for its value during the evaluation of expr. If more than one argument to ev is of this type then the binding is done in parallel. If V is a non-atomic expression then a substitution rather than a binding is performed.
- F where F, a function name, has been declared to be an evaluation function evfun causes F to be applied to expr.
- Any other function names, e.g. sum, cause evaluation of occurrences of those names in expr as though they were verbs.
- In addition a function occurring in expr (say F(x)) may be defined locally for the purpose of this evaluation of expr by giving F(x) := expression as an argument to ev.
- If an atom not mentioned above or a subscripted variable or subscripted expression was given as an argument, it is evaluated and if the result is an equation or assignment then the indicated binding or substitution is performed. If the result is a list then the members of the list are treated as if they were additional arguments given to ev. This permits a list of equations to be given (e.g. [X=1, Y=A**2]) or a list of names of equations (e.g., [%t1, %t2] where %t1 and %t2 are equations) such as that returned by solve.
The arguments of ev may be given in any order with the exception of substitution equations which are handled in sequence, left to right, and evaluation functions which are composed, e.g., ev (expr, ratsimp, realpart) is handled as realpart (ratsimp (expr)).

The simp, numer, and float switches may also be set locally in a block, or globally in Maxima so that they will remain in effect until being reset.

If expr is a canonical rational expression (CRE), then the expression returned by ev is also a CRE, provided the numer and float switches are not both true.
During step (1), a list is made of the non-subscripted variables appearing on the left side of equations in the arguments or in the value of some arguments if the value is an equation. The variables (subscripted variables which do not have associated memoizing functions as well as non-subscripted variables) in the expression expr are replaced by their global values, except for those appearing in this list. Usually, expr is just a label or % (as in %i2 in the example below), so this step simply retrieves the expression named by the label, so that ev may work on it.
If any substitutions are indicated by the arguments, they are carried out now.
The resulting expression is then re-evaluated (unless one of the arguments was noeval) and simplified according to the arguments. Note that any function calls in expr will be carried out after the variables in it are evaluated and that ev(F(x)) thus may behave like F(ev(x)).
For each instance of eval in the arguments, steps (3) and (4) are repeated.

9 Simplification

9.1 Introduction to Simplification

Maxima performs a cycle of actions in response to each new user-typed command. This consists of four steps: reading or "parsing" the input, evaluation, simplification and output. Parsing converts a syntactically valid sequence of typed characters into a data structure to be used for the rest of the operations. Evaluation includes replacing names with their assigned values. Simplification means rewriting an expression to be easier for the user or other programs to understand. Output includes displaying computational results in a variety of different formats and notations.

Evaluation and simplification sometimes appear to have similar functionality as they both have the goal of removing "complexity" and system designers have sometimes divided a task so that it is performed partly in each. For example, integrate(x,x) evaluates the answer as x*x/2, which is then simplified to x^2/2.

Evaluation is always present: it is the consequence of having a programming system with functions, subroutines, variables, values, loops, assignments and so on. In the evaluation step, built-in or user-defined function names are replaced by their definitions, variables are replaced by their values. This is largely the same as activities of a conventional programming language, but extended to work with symbolic mathematical data. Because of the generality of the mathematics at hand, there are different possible models of evaluation and so the systems has optional "flags" that can steer the process of evaluation. See Functions and Variables for Evaluation.

By contrast, the intent of simplification is to maintain the value of an expression while re-formulating its representation to be smaller, simpler to understand, or to conform to particular specifications (like factored, expanded). For example, sin(0) to 0 or x+x to 2*x. There are several powerful tools to alter the results of simplification, since it is largely in this part of the system that a user can incorporate knowledge of newly introduced functions or symbolic notation into Maxima.

Simplification is generally done at four different levels:

The internal, built-in automated simplifier,
Built-in simplification routines that can be explicitly called by the user at selected places in a program or command sequence,
User-written simplification routines, linked to the simplifier by using "tellsimp" or "tellsimpafter" and called automatically,
User-written routines that can be explicitly called by the user at selected places in a program or command sequence.

The internal simplifier belongs to the heart of Maxima. It is a large and complicated collection of programs, and it has been refined over many years and by thousands of users. Nevertheless, especially if you are trying out novel ideas or unconventional notation, you may find it helpful to make small (or large) changes to the program yourself. For details see for example the paper at the end of https://people.eecs.berkeley.edu/~fateman/papers/intro5.txt.

Maxima internally represents expressions as "trees" with operators or "roots" like +, * , = and operands ("leaves") which are variables like x, y, z, functions or sub-trees, like x*y. Each operator has a simplification program associated with it. + (which also covers binary - since a-b = a+(-1)*b) and * (which also covers / since a/b = a*b^(-1)) have rather elaborate simplification programs. These simplification programs (simplus, simptimes, simpexpt, etc.) are called whenever the simplifier encounters the respective arithmetic operators in an expression tree to be analyzed.

The structure of the simplifier dates back to 1965, and many hands have worked on it through the years. The structure turns out to be, in modern jargon, data- directed, or object-oriented. The program dispatches to the appropriate routine depending on the root of some sub-tree of the expression, recursively. This general notion means you can make modifications to the simplification process by very local changes to the program. In many cases it is conceptually straightforward to add an operator and add its simplification routine without disturbing existing code.

We note that in addition to this general simplifier operating on algebraic expression trees, there are several other representations of expressions in Maxima which have separate methods and simplifiers. For example, the rat function converts polynomials to vectors of coefficients to assist in rapid manipulation of such forms. Other representations include Taylor series and the (rarely used) Poisson series.

All operators introduced by the user initially have no simplification programs associated with them. Maxima does not know anything about function "f" and so typing f(a,b) will result in simplifying a,b, but not f. Even some built-in operators have no simplifications. For example, = does not "simplify" – it is a place-holder with no simplification semantics other than to simplify its two arguments, in this case referred to as the left and right sides. Other parts of Maxima such as the solve program take special note of equations, that is, trees with = as the root. (Note – in Maxima, the assignment operation is : . That is, q: 4 sets the value of the symbol q to 4. Function definition is done with :=. )

The general simplifier returns results with an internal flag indicating the expression and each sub-expression has been simplified. This does not guarantee that it is unique over all possible equivalent expressions. That’s too hard (theoretically, not possible given the generality of what can be expressed in Maxima). However, some aspects of the expression, such as the ordering of terms in a sum or product, are made uniform. This is important for the other programs to work properly.

You can set a number of option variables which direct Maxima’s processing to favor particular kinds of patterns as being goals. You can even use the most extreme option which is to turn the simplifier off by simp:false. We do not recommend this since many internal routines expect their arguments to be simplified. (About the only time it seems plausible to turn off the simplifier is in the rare case that you want to over-ride a built-in simplification. In that case you might temporarily disable the simplifier, put in the new transformation via tellsimp, and then re-enable the simplifier by simp:true.)

It is more plausible for you to associate user-defined symbolic function names or operators with properties (additive, lassociative, oddfun, antisymmetric, linear, outative, commutative, multiplicative, rassociative, evenfun, nary and symmetric). These options steer the simplifier processing in systematic directions.

For example, declare(f,oddfun) specifies that f is an odd function. Maxima will simplify f(-x) to -f(x). In the case of an even function, that is declare(g,evenfun), Maxima will simplify g(-x) to g(x). You can also associate a programming function with a name such as h(x):=x^2+1. In that case the evaluator will immediately replace h(3) by 10, and h(a+1) by (a+1)^2+1, so any properties of h will be ignored.

In addition to these directly related properties set up by the user, facts and properties from the actual context may have an impact on the simplifier’s behavior, too. See Introduction to Maximas Database.

Example: sin(n*%pi) is simplified to zero, if n is an integer.

(%i1) sin(n*%pi);
(%o1)                      sin(%pi n)

(%i2) declare(n, integer);
(%o2)                         done

(%i3) sin(n*%pi);
(%o3)                           0

If automated simplification is not sufficient, you can consider a variety of built-in, but explicitly called simplfication functions (ratsimp, expand, factor, radcan and others). There are also flags that will push simplification into one or another direction. Given demoivre:true the simplifier rewrites complex exponentials as trigonometric forms. Given exponentialize:true the simplifier tries to do the reverse: rewrite trigonometric forms as complex exponentials.

As everywhere in Maxima, by writing your own functions (be it in the Maxima user language or in the implementation language Lisp) and explicitly calling them at selected places in the program, you can respond to your individual simplification needs. Lisp gives you a handle on all the internal mechanisms, but you rarely need this full generality. "Tellsimp" is designed to generate much of the Lisp internal interface into the simplifier automatically. See See Rules and Patterns.

Over the years (Maxima/Macsyma’s origins date back to about 1966!) users have contributed numerous application packages and tools to extend or alter its functional behavior. Various non-standard and "share" packages exist to modify or extend simplification as well. You are invited to look into this more experimental material where work is still in progress See simplification-pkg.

The following appended material is optional on a first reading, and reading it is not necessary for productive use of Maxima. It is for the curious user who wants to understand what is going on, or the ambitious programmer who might wish to change the (open-source) code. Experimentation with redefining Maxima Lisp code is easily possible: to change the definition of a Lisp program (say the one that simplifies cos(), named simp%cos), you simply load into Maxima a text file that will overwrite the simp%cos function from the maxima package.

9.2 Functions and Variables for Simplification

Property: additive

If declare(f,additive) has been executed, then:

(1) If f is univariate, whenever the simplifier encounters f applied to a sum, f will be distributed over that sum. I.e. f(y+x) will simplify to f(y)+f(x).

(2) If f is a function of 2 or more arguments, additivity is defined as additivity in the first argument to f, as in the case of sum or integrate, i.e. f(h(x)+g(x),x) will simplify to f(h(x),x)+f(g(x),x). This simplification does not occur when f is applied to expressions of the form sum(x[i],i,lower-limit,upper-limit).

Example:

(%i1) F3 (a + b + c);
(%o1)                     F3(c + b + a)

(%i2) declare (F3, additive);
(%o2)                         done

(%i3) F3 (a + b + c);
(%o3)                 F3(c) + F3(b) + F3(a)

Property: antisymmetric

If declare(h,antisymmetric) is done, this tells the simplifier that h is antisymmetric. E.g. h(x,z,y) will simplify to - h(x, y, z). That is, it will give (-1)^n times the result given by symmetric or commutative, where n is the number of interchanges of two arguments necessary to convert it to that form.

Examples:

(%i1) S (b, a);
(%o1)                        S(b, a)

(%i2) declare (S, symmetric);
(%o2)                         done

(%i3) S (b, a);
(%o3)                        S(a, b)

(%i4) S (a, c, e, d, b);
(%o4)                   S(a, b, c, d, e)

(%i5) T (b, a);
(%o5)                        T(b, a)

(%i6) declare (T, antisymmetric);
(%o6)                         done

(%i7) T (b, a);
(%o7)                       - T(a, b)

(%i8) T (a, c, e, d, b);
(%o8)                   T(a, b, c, d, e)

Category: Operators · Category: Declarations and inferences

Function: combine (expr)

Simplifies the sum expr by combining terms with the same denominator into a single term.

Example:

(%i1) 1*f/2*b + 2*c/3*a + 3*f/4*b +c/5*b*a;
                      5 b f   a b c   2 a c
(%o1)                 ----- + ----- + -----
                        4       5       3

(%i2) combine (%);
                  75 b f + 4 (3 a b c + 10 a c)
(%o2)             -----------------------------
                               60

Category: Operators · Category: Declarations and inferences

Property: commutative

If declare(h, commutative) is done, this tells the simplifier that h is a commutative function. E.g. h(x, z, y) will simplify to h(x, y, z). This is the same as symmetric.

Exemplo:

(%i1) S (b, a);
(%o1)                        S(b, a)

(%i2) S (a, b) + S (b, a);
(%o2)                   S(b, a) + S(a, b)

(%i3) declare (S, commutative);
(%o3)                         done

(%i4) S (b, a);
(%o4)                        S(a, b)

(%i5) S (a, b) + S (b, a);
(%o5)                       2 S(a, b)

(%i6) S (a, c, e, d, b);
(%o6)                   S(a, b, c, d, e)

Function: demoivre (expr)

Option variable: demoivre

The function demoivre (expr) converts one expression without setting the global variable demoivre.

When the variable demoivre is true, complex exponentials are converted into equivalent expressions in terms of circular functions: exp (a + b*%i) simplifies to %e^a * (cos(b) + %i*sin(b)) if b is free of %i. a and b are not expanded.

The default value of demoivre is false.

exponentialize converts circular and hyperbolic functions to exponential form. demoivre and exponentialize cannot both be true at the same time.

Category: Complex variables · Category: Trigonometric functions · Category: Hyperbolic functions

Function: distrib (expr)

Distributes sums over products. It differs from expand in that it works at only the top level of an expression, i.e., it doesn’t recurse and it is faster than expand. It differs from multthru in that it expands all sums at that level.

Examples:

(%i1) distrib ((a+b) * (c+d));
(%o1)                 b d + a d + b c + a c
(%i2) multthru ((a+b) * (c+d));
(%o2)                 (b + a) d + (b + a) c
(%i3) distrib (1/((a+b) * (c+d)));
                                1
(%o3)                    ---------------
                         (b + a) (d + c)
(%i4) expand (1/((a+b) * (c+d)), 1, 0);
                                1
(%o4)                 ---------------------
                      b d + a d + b c + a c

Option variable: distribute_over

Default value: true

distribute_over controls the mapping of functions over bags like lists, matrices, and equations. At this time not all Maxima functions have this property. It is possible to look up this property with the command properties.

The mapping of functions is switched off, when setting distribute_over to the value false.

Examples:

The sin function maps over a list:

(%i1) sin([x,1,1.0]);
(%o1)         [sin(x), sin(1), 0.8414709848078965]

mod is a function with two arguments which maps over lists. Mapping over nested lists is possible too:

(%i1) mod([x,11,2*a],10);
(%o1)             [mod(x, 10), 1, 2 mod(a, 5)]

(%i2) mod([[x,y,z],11,2*a],10);
(%o2) [[mod(x, 10), mod(y, 10), mod(z, 10)], 1, 2 mod(a, 5)]

Mapping of the floor function over a matrix and an equation:

(%i1) floor(matrix([a,b],[c,d]));
                     [ floor(a)  floor(b) ]
(%o1)                [                    ]
                     [ floor(c)  floor(d) ]

(%i2) floor(a=b);
(%o2)                  floor(a) = floor(b)

Functions with more than one argument map over any of the arguments or all arguments:

(%i1) expintegral_e([1,2],[x,y]);
(%o1) [[expintegral_e(1, x), expintegral_e(1, y)], 
                      [expintegral_e(2, x), expintegral_e(2, y)]]

Check if a function has the property distribute_over:

(%i1) properties(abs);
(%o1) [integral, rule, distributes over bags, noun, gradef, 
                                                 system function]

The mapping of functions is switched off, when setting distribute_over to the value false.

(%i1) distribute_over;
(%o1)                         true

(%i2) sin([x,1,1.0]);
(%o2)         [sin(x), sin(1), 0.8414709848078965]

(%i3) distribute_over : not distribute_over;
(%o3)                         false

(%i4) sin([x,1,1.0]);
(%o4)                   sin([x, 1, 1.0])

Option variable: domain

Default value: real

When domain is set to complex, sqrt (x^2) will remain sqrt (x^2) instead of returning abs(x).

Property: evenfun

Property: oddfun

declare(f, evenfun) or declare(f, oddfun) tells Maxima to recognize the function f as an even or odd function.

Examples:

(%i1) o (- x) + o (x);
(%o1)                     o(x) + o(- x)
(%i2) declare (o, oddfun);
(%o2)                         done
(%i3) o (- x) + o (x);
(%o3)                           0
(%i4) e (- x) - e (x);
(%o4)                     e(- x) - e(x)
(%i5) declare (e, evenfun);
(%o5)                         done
(%i6) e (- x) - e (x);
(%o6)                           0

Function: expand
expand (expr)
expand (expr, p, n)

Expand expression expr. Products of sums and exponentiated sums are multiplied out, numerators of rational expressions which are sums are split into their respective terms, and multiplication (commutative and non-commutative) are distributed over addition at all levels of expr.

For polynomials one should usually use ratexpand which uses a more efficient algorithm.

maxnegex and maxposex control the maximum negative and positive exponents, respectively, which will expand.

expand (expr, p, n) expands expr, using p for maxposex and n for maxnegex. This is useful in order to expand part but not all of an expression.

expon - the exponent of the largest negative power which is automatically expanded (independent of calls to expand). For example if expon is 4 then (x+1)^(-5) will not be automatically expanded.

expop - the highest positive exponent which is automatically expanded. Thus (x+1)^3, when typed, will be automatically expanded only if expop is greater than or equal to 3. If it is desired to have (x+1)^n expanded where n is greater than expop then executing expand ((x+1)^n) will work only if maxposex is not less than n.

expand(expr, 0, 0) causes a resimplification of expr. expr is not reevaluated. In distinction from ev(expr, noeval) a special representation (e. g. a CRE form) is removed. See also ev.

The expand flag used with ev causes expansion.

The file share/simplification/facexp.mac contains several related functions (in particular facsum, factorfacsum and collectterms, which are autoloaded) and variables (nextlayerfactor and facsum_combine) that provide the user with the ability to structure expressions by controlled expansion. Brief function descriptions are available in simplification/facexp.usg. A demo is available by doing demo("facexp").

Examples:

(%i1) expr:(x+1)^2*(y+1)^3;
                               2        3
(%o1)                   (x + 1)  (y + 1)

(%i2) expand(expr);
       2  3        3    3      2  2        2      2      2
(%o2) x  y  + 2 x y  + y  + 3 x  y  + 6 x y  + 3 y  + 3 x  y
                                                      2
                                     + 6 x y + 3 y + x  + 2 x + 1

(%i3) expand(expr,2);
               2        3              3          3
(%o3)         x  (y + 1)  + 2 x (y + 1)  + (y + 1)

(%i4) expr:(x+1)^-2*(y+1)^3;
                                   3
                            (y + 1)
(%o4)                       --------
                                   2
                            (x + 1)

(%i5) expand(expr);
            3               2
           y             3 y            3 y             1
(%o5) ------------ + ------------ + ------------ + ------------
       2              2              2              2
      x  + 2 x + 1   x  + 2 x + 1   x  + 2 x + 1   x  + 2 x + 1

(%i6) expand(expr,2,2);
                                   3
                            (y + 1)
(%o6)                     ------------
                           2
                          x  + 2 x + 1

Resimplify an expression without expansion:

(%i1) expr:(1+x)^2*sin(x);
                                2
(%o1)                    (x + 1)  sin(x)

(%i2) exponentialize:true;
(%o2)                         true

(%i3) expand(expr,0,0);
                            2    %i x     - %i x
                  %i (x + 1)  (%e     - %e      )
(%o3)           - -------------------------------
                                 2

Function: expandwrt (expr, x_1, …, x_n)

Expands expression expr with respect to the variables x_1, …, x_n. All products involving the variables appear explicitly. The form returned will be free of products of sums of expressions that are not free of the variables. x_1, …, x_n may be variables, operators, or expressions.

By default, denominators are not expanded, but this can be controlled by means of the switch expandwrt_denom.

This function is autoloaded from simplification/stopex.mac.

Option variable: expandwrt_denom

Default value: false

expandwrt_denom controls the treatment of rational expressions by expandwrt. If true, then both the numerator and denominator of the expression will be expanded according to the arguments of expandwrt, but if expandwrt_denom is false, then only the numerator will be expanded in that way.

Function: expandwrt_factored (expr, x_1, …, x_n)

is similar to expandwrt, but treats expressions that are products somewhat differently. expandwrt_factored expands only on those factors of expr that contain the variables x_1, …, x_n.

This function is autoloaded from simplification/stopex.mac.

Option variable: expon

Default value: 0

expon is the exponent of the largest negative power which is automatically expanded (independent of calls to expand). For example, if expon is 4 then (x+1)^(-5) will not be automatically expanded.

Category: Complex variables · Category: Trigonometric functions · Category: Hyperbolic functions

Function: exponentialize (expr)

Option variable: exponentialize

The function exponentialize (expr) converts circular and hyperbolic functions in expr to exponentials, without setting the global variable exponentialize.

When the variable exponentialize is true, all circular and hyperbolic functions are converted to exponential form. The default value is false.

demoivre converts complex exponentials into circular functions. exponentialize and demoivre cannot both be true at the same time.

Option variable: expop

Default value: 0

expop is the highest positive exponent which is automatically expanded. Thus (x + 1)^3, when typed, will be automatically expanded only if expop is greater than or equal to 3. If it is desired to have (x + 1)^n expanded where n is greater than expop then executing expand ((x + 1)^n) will work only if maxposex is not less than n.

Category: Declarations and inferences · Category: Operators · Category: Simplification

Property: lassociative

declare (g, lassociative) tells the Maxima simplifier that g is left-associative. E.g., g (g (a, b), g (c, d)) will simplify to g (g (g (a, b), c), d).

Property: linear

One of Maxima’s operator properties. For univariate f so declared, "expansion" f(x + y) yields f(x) + f(y), f(a*x) yields a*f(x) takes place where a is a "constant". For functions of two or more arguments, "linearity" is defined to be as in the case of sum or integrate, i.e., f (a*x + b, x) yields a*f(x,x) + b*f(1,x) for a and b free of x.

Example:

(%i1) declare (f, linear);
(%o1)                         done

(%i2) f(x+y);
(%o2)                      f(y) + f(x)

(%i3) declare (a, constant);
(%o3)                         done

(%i4) f(a*x);
(%o4)                        a f(x)

linear is equivalent to additive and outative. See also opproperties.

Example:

(%i1) 'sum (F(k) + G(k), k, 1, inf);
                       inf
                       ====
                       \
(%o1)                   >    (G(k) + F(k))
                       /
                       ====
                       k = 1

(%i2) declare (nounify (sum), linear);
(%o2)                         done

(%i3) 'sum (F(k) + G(k), k, 1, inf);
                     inf          inf
                     ====         ====
                     \            \
(%o3)                 >    G(k) +  >    F(k)
                     /            /
                     ====         ====
                     k = 1        k = 1

Category: Declarations and inferences · Category: Operators · Category: Simplification

Option variable: maxnegex

Default value: 1000

maxnegex is the largest negative exponent which will be expanded by the expand command, see also maxposex.

Option variable: maxposex

Default value: 1000

maxposex is the largest exponent which will be expanded with the expand command, see also maxnegex.

Category: Declarations and inferences · Category: Expressions · Category: Simplification

Property: multiplicative

declare(f, multiplicative) tells the Maxima simplifier that f is multiplicative.

If f is univariate, whenever the simplifier encounters f applied to a product, f distributes over that product. E.g., f(x*y) simplifies to f(x)*f(y). This simplification is not applied to expressions of the form f('product(...)).
If f is a function of 2 or more arguments, multiplicativity is defined as multiplicativity in the first argument to f, e.g., f (g(x) * h(x), x) simplifies to f (g(x) ,x) * f (h(x), x).

declare(nounify(product), multiplicative) tells Maxima to simplify symbolic products.

Example:

(%i1) F2 (a * b * c);
(%o1)                       F2(a b c)

(%i2) declare (F2, multiplicative);
(%o2)                         done

(%i3) F2 (a * b * c);
(%o3)                   F2(a) F2(b) F2(c)

declare(nounify(product), multiplicative) tells Maxima to simplify symbolic products.

(%i1) product (a[i] * b[i], i, 1, n);
                             n
                           /===\
                            ! !
(%o1)                       ! !  a  b
                            ! !   i  i
                           i = 1

(%i2) declare (nounify (product), multiplicative);
(%o2)                         done

(%i3) product (a[i] * b[i], i, 1, n);
                          n         n
                        /===\     /===\
                         ! !       ! !
(%o3)                  ( ! !  a )  ! !  b
                         ! !   i   ! !   i
                        i = 1     i = 1

Function: multthru
multthru (expr)
multthru (expr_1, expr_2)

Multiplies a factor (which should be a sum) of expr by the other factors of expr. That is, expr is f_1 f_2 ... f_n where at least one factor, say f_i, is a sum of terms. Each term in that sum is multiplied by the other factors in the product. (Namely all the factors except f_i). multthru does not expand exponentiated sums. This function is the fastest way to distribute products (commutative or noncommutative) over sums. Since quotients are represented as products multthru can be used to divide sums by products as well.

multthru (expr_1, expr_2) multiplies each term in expr_2 (which should be a sum or an equation) by expr_1. If expr_1 is not itself a sum then this form is equivalent to multthru (expr_1*expr_2).

(%i1) x/(x-y)^2 - 1/(x-y) - f(x)/(x-y)^3;
                      1        x         f(x)
(%o1)             - ----- + -------- - --------
                    x - y          2          3
                            (x - y)    (x - y)
(%i2) multthru ((x-y)^3, %);
                           2
(%o2)             - (x - y)  + x (x - y) - f(x)
(%i3) ratexpand (%);
                           2
(%o3)                   - y  + x y - f(x)
(%i4) ((a+b)^10*s^2 + 2*a*b*s + (a*b)^2)/(a*b*s^2);
                        10  2              2  2
                 (b + a)   s  + 2 a b s + a  b
(%o4)            ------------------------------
                                  2
                             a b s
(%i5) multthru (%);  /* note that this does not expand (b+a)^10 */
                                        10
                       2   a b   (b + a)
(%o5)                  - + --- + ---------
                       s    2       a b
                           s
(%i6) multthru (a.(b+c.(d+e)+f));
(%o6)            a . f + a . c . (e + d) + a . b
(%i7) expand (a.(b+c.(d+e)+f));
(%o7)         a . f + a . c . e + a . c . d + a . b

Property: nary

declare(f, nary) tells Maxima to recognize the function f as an n-ary function.

The nary declaration is not the same as calling the nary function. The sole effect of declare(f, nary) is to instruct the Maxima simplifier to flatten nested expressions, for example, to simplify foo(x, foo(y, z)) to foo(x, y, z). See also declare.

Example:

(%i1) H (H (a, b), H (c, H (d, e)));
(%o1)               H(H(a, b), H(c, H(d, e)))
(%i2) declare (H, nary);
(%o2)                         done
(%i3) H (H (a, b), H (c, H (d, e)));
(%o3)                   H(a, b, c, d, e)

Option variable: negdistrib

Default value: true

When negdistrib is true, -1 distributes over an expression. E.g., -(x + y) becomes - y - x. Setting it to false will allow - (x + y) to be displayed like that. This is sometimes useful but be very careful: like the simp flag, this is one flag you do not want to set to false as a matter of course or necessarily for other than local use in your Maxima.

Example:

(%i1) negdistrib;
(%o1)                         true

(%i2) -(x+y);
(%o2)                       (- y) - x

(%i3) negdistrib : not negdistrib ;
(%o3)                         false

(%i4) -(x+y);
(%o4)                       - (y + x)

Category: Operators · Category: Simplification

System variable: opproperties

opproperties is the list of the special operator properties recognized by the Maxima simplifier.

Items are added to the opproperties list by the function define_opproperty.

Example:

(%i1) opproperties;
(%o1) [linear, additive, multiplicative, outative, evenfun, 
oddfun, commutative, symmetric, antisymmetric, nary, 
lassociative, rassociative]

Category: Global variables · Category: Operators · Category: Simplification

Function: define_opproperty (property_name, simplifier_fn)

Declares the symbol property_name to be an operator property, which is simplified by simplifier_fn, which may be the name of a Maxima or Lisp function or a lambda expression. After define_opproperty is called, functions and operators may be declared to have the property_name property, and simplifier_fn is called to simplify them.

simplifier_fn must be a function of one argument, which is an expression in which the main operator is declared to have the property_name property.

simplifier_fn is called with the global flag simp disabled. Therefore simplifier_fn must be able to carry out its simplification without making use of the general simplifier.

define_opproperty appends property_name to the global list opproperties.

define_opproperty returns done.

Example:

Declare a new property, identity, which is simplified by simplify_identity. Declare that f and g have the new property.

(%i1) define_opproperty (identity, simplify_identity);
(%o1)                         done

(%i2) simplify_identity(e) := first(e);
(%o2)           simplify_identity(e) := first(e)

(%i3) declare ([f, g], identity);
(%o3)                         done

(%i4) f(10 + t);
(%o4)                        t + 10

(%i5) g(3*u) - f(2*u);
(%o5)                           u

Property: outative

declare(f, outative) tells the Maxima simplifier that constant factors in the argument of f can be pulled out.

If f is univariate, whenever the simplifier encounters f applied to a product, that product will be partitioned into factors that are constant and factors that are not and the constant factors will be pulled out. E.g., f(a*x) will simplify to a*f(x) where a is a constant. Non-atomic constant factors will not be pulled out.
If f is a function of 2 or more arguments, outativity is defined as in the case of sum or integrate, i.e., f (a*g(x), x) will simplify to a * f(g(x), x) for a free of x.

sum, integrate, and limit are all outative.

Example:

(%i1) F1 (100 * x);
(%o1)                       F1(100 x)

(%i2) declare (F1, outative);
(%o2)                         done

(%i3) F1 (100 * x);
(%o3)                       100 F1(x)

(%i4) declare (zz, constant);
(%o4)                         done

(%i5) F1 (zz * y);
(%o5)                       zz F1(y)

Category: Declarations and inferences · Category: Operators

Function: radcan (expr)

Simplifies expr, which can contain logs, exponentials, and radicals, by converting it into a form which is canonical over a large class of expressions and a given ordering of variables; that is, all functionally equivalent forms are mapped into a unique form. For a somewhat larger class of expressions, radcan produces a regular form. Two equivalent expressions in this class do not necessarily have the same appearance, but their difference can be simplified by radcan to zero.

For some expressions radcan is quite time consuming. This is the cost of exploring certain relationships among the components of the expression for simplifications based on factoring and partial-fraction expansions of exponents.

Examples:

(%i1) radcan((log(x+x^2)-log(x))^a/log(1+x)^(a/2));
                                    a/2
(%o1)                     log(x + 1)

(%i2) radcan((log(1+2*a^x+a^(2*x))/log(1+a^x)));
(%o2)                           2

(%i3) radcan((%e^x-1)/(1+%e^(x/2)));
                              x/2
(%o3)                       %e    - 1

Category: Simplification functions

Option variable: radexpand

Default value: true

radexpand controls some simplifications of radicals.

When radexpand is all, causes nth roots of factors of a product which are powers of n to be pulled outside of the radical. E.g. if radexpand is all, sqrt (16*x^2) simplifies to 4*x.

More particularly, consider sqrt (x^2).

If radexpand is all or assume (x > 0) has been executed, sqrt(x^2) simplifies to x.
If radexpand is true and domain is real (its default), sqrt(x^2) simplifies to abs(x).
If radexpand is false, or radexpand is true and domain is complex, sqrt(x^2) is not simplified.

Note that domain only matters when radexpand is true.

Category: Declarations and inferences · Category: Operators

Property: rassociative

declare (g, rassociative) tells the Maxima simplifier that g is right-associative. E.g., g(g(a, b), g(c, d)) simplifies to g(a, g(b, g(c, d))).

Function: scsimp (expr, rule_1, …, rule_n)

Sequential Comparative Simplification (method due to Stoute). scsimp attempts to simplify expr according to the rules rule_1, …, rule_n. If a smaller expression is obtained, the process repeats. Otherwise after all simplifications are tried, it returns the original answer.

example (scsimp) displays some examples.

Category: Simplification functions

Option variable: simp

Default value: true

simp enables simplification. This is the default. simp is also an evflag, which is recognized by the function ev. See ev.

When simp is used as an evflag with a value false, the simplification is suppressed only during the evaluation phase of an expression. The flag does not suppress the simplification which follows the evaluation phase.

Many Maxima functions and operations require simplification to be enabled to work normally. When simplification is disabled, many results will be incomplete, and in addition there may be incorrect results or program errors.

Examples:

The simplification is switched off globally. The expression sin(1.0) is not simplified to its numerical value. The simp-flag switches the simplification on.

(%i1) simp:false;
(%o1)                         false

(%i2) sin(1.0);
(%o2)                       sin(1.0)

(%i3) sin(1.0),simp;
(%o3)                  0.8414709848078965

The simplification is switched on again. The simp-flag cannot suppress the simplification completely. The output shows a simplified expression, but the variable x has an unsimplified expression as a value, because the assignment has occurred during the evaluation phase of the expression.

(%i1) simp:true;
(%o1)                         true

(%i2) x:sin(1.0),simp:false;
(%o2)                  0.8414709848078965

(%i3) :lisp $x
((%SIN) 1.0)

Category: Evaluation flags

Property: symmetric

declare (h, symmetric) tells the Maxima simplifier that h is a symmetric function. E.g., h (x, z, y) simplifies to h (x, y, z).

commutative is synonymous with symmetric.

Category: Declarations and inferences · Category: Operators

Function: xthru (expr)

Combines all terms of expr (which should be a sum) over a common denominator without expanding products and exponentiated sums as ratsimp does. xthru cancels common factors in the numerator and denominator of rational expressions but only if the factors are explicit.

Sometimes it is better to use xthru before ratsimping an expression in order to cause explicit factors of the gcd of the numerator and denominator to be canceled thus simplifying the expression to be ratsimped.

Examples:

(%i1) ((x+2)^20 - 2*y)/(x+y)^20 + (x+y)^(-19) - x/(x+y)^20;
                                20
                 1       (x + 2)   - 2 y       x
(%o1)        --------- + --------------- - ---------
                    19             20             20
             (y + x)        (y + x)        (y + x)

(%i2) xthru (%);
                                 20
                          (x + 2)   - y
(%o2)                     -------------
                                   20
                            (y + x)

10 Mathematical Functions

10.1 Functions for Numbers

Function: abs (z)

The abs function represents the mathematical absolute value function and works for both numerical and symbolic values. If the argument, z, is a real or complex number, abs returns the absolute value of z. If possible, symbolic expressions using the absolute value function are also simplified.

Maxima can differentiate, integrate and calculate limits for expressions containing abs. The abs_integrate package further extends Maxima’s ability to calculate integrals involving the abs function. See (%i12) in the examples below.

When applied to a list or matrix, abs automatically distributes over the terms. Similarly, it distributes over both sides of an equation. To alter this behaviour, see the variable distribute_over.

10.2 Functions for Complex Numbers

Function: cabs (expr)

Calculates the absolute value of an expression representing a complex number. Unlike the function abs, the cabs function always decomposes its argument into a real and an imaginary part. If x and y represent real variables or expressions, the cabs function calculates the absolute value of x + %i*y as

(%i1) cabs (1);
(%o1)                           1

(%i2) cabs (1 + %i);
(%o2)                        sqrt(2)

(%i3) cabs (exp (%i));
(%o3)                           1

(%i4) cabs (exp (%pi * %i));
(%o4)                           1

(%i5) cabs (exp (3/2 * %pi * %i));
(%o5)                           1

(%i6) cabs (17 * exp (2 * %i));
(%o6)                          17

If cabs returns a noun form this most commonly is caused by some properties of the variables involved not being known:

(%i1) cabs (a+%i*b);
                                2    2
(%o1)                     sqrt(b  + a )

(%i2) declare(a,real,b,real);
(%o2)                         done

(%i3) cabs (a+%i*b);
                                2    2
(%o3)                     sqrt(b  + a )

(%i4) assume(a>0,b>0);
(%o4)                    [a > 0, b > 0]

(%i5) cabs (a+%i*b);
                                2    2
(%o5)                     sqrt(b  + a )

The cabs function can use known properties like symmetry properties of complex functions to help it calculate the absolute value of an expression. If such identities exist, they can be advertised to cabs using function properties. The symmetries that cabs understands are: mirror symmetry, conjugate function and complex characteristic.

cabs is a verb function and is not suitable for symbolic calculations. For such calculations (including integration, differentiation and taking limits of expressions containing absolute values), use abs.

The result of cabs can include the absolute value function, abs, and the arc tangent, atan2.

When applied to a list or matrix, cabs automatically distributes over the terms. Similarly, it distributes over both sides of an equation.

For further ways to compute with complex numbers, see the functions rectform, realpart, imagpart, carg, conjugate and polarform.

Examples:

Examples with sqrt and sin.

(%i1) cabs(sqrt(1+%i*x));
                             2     1/4
(%o1)                      (x  + 1)
(%i2) cabs(sin(x+%i*y));
                    2        2         2        2
(%o2)       sqrt(cos (x) sinh (y) + sin (x) cosh (y))

The error function, erf, has mirror symmetry, which is used here in the calculation of the absolute value with a complex argument:

(%i3) cabs(erf(x+%i*y));
                                          2
           (erf(%i y + x) - erf(%i y - x))
(%o3) sqrt(--------------------------------
                          4
                                                               2
                                (erf(%i y + x) + erf(%i y - x))
                              - --------------------------------)
                                               4

Maxima knows complex identities for the Bessel functions, which allow it to compute the absolute value for complex arguments. Here is an example for bessel_j.

(%i4) cabs(bessel_j(1,%i));
(%o4)                 abs(bessel_j(1, %i))

Function: carg (z)

Returns the complex argument of z. The complex argument is an angle theta in (-%pi, %pi] such that r exp (theta %i) = z where r is the magnitude of z.

carg is a computational function, not a simplifying function.

See also abs (complex magnitude), polarform, rectform, realpart, and imagpart.

Examples:

(%i1) carg (1);
(%o1)                           0

(%i2) carg (1 + %i);
                               %pi
(%o2)                          ---
                                4

(%i3) carg (exp (%i));
                               sin(1)
(%o3)                     atan(------)
                               cos(1)

(%i4) carg (exp (%pi * %i));
(%o4)                          %pi

(%i5) carg (exp (3/2 * %pi * %i));
                                %pi
(%o5)                         - ---
                                 2

(%i6) carg (17 * exp (2 * %i));
                            sin(2)
(%o6)                  atan(------) + %pi
                            cos(2)

If carg returns a noun form this most communly is caused by some properties of the variables involved not being known:

(%i1) carg (a+%i*b);
(%o1)                      atan2(b, a)

(%i2) declare(a,real,b,real);
(%o2)                         done

(%i3) carg (a+%i*b);
(%o3)                      atan2(b, a)

(%i4) assume(a>0,b>0);
(%o4)                    [a > 0, b > 0]

(%i5) carg (a+%i*b);
                                  b
(%o5)                        atan(-)
                                  a

Function: conjugate (x)

Returns the complex conjugate of x.

(%i1) declare ([aa, bb], real, cc, complex, ii, imaginary);
(%o1)                         done

(%i2) conjugate (aa + bb*%i);
(%o2)                      aa - %i bb

(%i3) conjugate (cc);
(%o3)                     conjugate(cc)

(%i4) conjugate (ii);
(%o4)                         - ii

(%i5) conjugate (xx + yy);
(%o5)                        yy + xx

Function: imagpart (expr)

Returns the imaginary part of the expression expr.

imagpart is a computational function, not a simplifying function.

See also abs, carg, polarform, rectform, and realpart.

Example:

(%i1) imagpart (a+b*%i);
(%o1)                           b

(%i2) imagpart (1+sqrt(2)*%i);
(%o2)                        sqrt(2)

(%i3) imagpart (1);
(%o3)                           0

(%i4) imagpart (sqrt(2)*%i);
(%o4)                        sqrt(2)

Category: Complex variables · Category: Exponential and logarithm functions

Function: polarform (expr)

Returns an expression r %e^(%i theta) equivalent to expr, such that r and theta are purely real.

Example:

(%i1) polarform(a+b*%i);
                       2    2    %i atan2(b, a)
(%o1)            sqrt(b  + a ) %e

(%i2) polarform(1+%i);
                                  %i %pi
                                  ------
                                    4
(%o2)                   sqrt(2) %e

(%i3) polarform(1+2*%i);
                                %i atan(2)
(%o3)                 sqrt(5) %e

Function: realpart (expr)

Returns the real part of expr. realpart and imagpart will work on expressions involving trigonometric and hyperbolic functions, as well as square root, logarithm, and exponentiation.

Example:

(%i1) realpart (a+b*%i);
(%o1)                           a

(%i2) realpart (1+sqrt(2)*%i);
(%o2)                           1

(%i3) realpart (sqrt(2)*%i);
(%o3)                           0

(%i4) realpart (1);
(%o4)                           1

Function: rectform (expr)

Returns an expression a + b %i equivalent to expr, such that a and b are purely real.

Example:

(%i1) rectform(sqrt(2)*%e^(%i*%pi/4));
(%o1)                        %i + 1

(%i2) rectform(sqrt(b^2+a^2)*%e^(%i*atan2(b, a)));
(%o2)                       %i b + a

(%i3) rectform(sqrt(5)*%e^(%i*atan(2)));
(%o3)                       2 %i + 1

Category: Gamma and factorial functions · Category: Operators

10.3 Combinatorial Functions

Operator: !!

The double factorial operator.

For an integer, float, or rational number n, n!! evaluates to the product n (n-2) (n-4) (n-6) ... (n - 2 (k-1)) where k is equal to entier (n/2), that is, the largest integer less than or equal to n/2. Note that this definition does not coincide with other published definitions for arguments which are not integers.

For an even (or odd) integer n, n!! evaluates to the product of all the consecutive even (or odd) integers from 2 (or 1) through n inclusive.

For an argument n which is not an integer, float, or rational, n!! yields a noun form genfact (n, n/2, 2).

Function: binomial (x, y)

The binomial coefficient x!/(y! (x - y)!). If x and y are integers, then the numerical value of the binomial coefficient is computed. If y, or x - y, is an integer, the binomial coefficient is expressed as a polynomial.

Examples:

(%i1) binomial (11, 7);
(%o1)                          330

(%i2) 11! / 7! / (11 - 7)!;
(%o2)                          330

(%i3) binomial (x, 7);
        (x - 6) (x - 5) (x - 4) (x - 3) (x - 2) (x - 1) x
(%o3)   -------------------------------------------------
                              5040

(%i4) binomial (x + 7, x);
      (x + 1) (x + 2) (x + 3) (x + 4) (x + 5) (x + 6) (x + 7)
(%o4) -------------------------------------------------------
                               5040

(%i5) binomial (11, y);
(%o5)                    binomial(11, y)

Category: Number theory

Function: factcomb (expr)

Tries to combine the coefficients of factorials in expr with the factorials themselves by converting, for example, (n + 1)*n! into (n + 1)!.

sumsplitfact if set to false will cause minfactorial to be applied after a factcomb.

Example:

(%i1) sumsplitfact;
(%o1)                         true

(%i2) (n + 1)*(n + 1)*n!;
                                  2
(%o2)                      (n + 1)  n!

(%i3) factcomb (%);
(%o3)                  (n + 2)! - (n + 1)!

(%i4) sumsplitfact: not sumsplitfact;
(%o4)                         false

(%i5) (n + 1)*(n + 1)*n!;
                                  2
(%o5)                      (n + 1)  n!

(%i6) factcomb (%);
(%o6)                 n (n + 1)! + (n + 1)!

Category: Gamma and factorial functions

Function: factorial

Operator: !

Represents the factorial function. Maxima treats factorial (x) the same as x!.

For any complex number x, except for negative integers, x! is defined as gamma(x+1).

For an integer x, x! simplifies to the product of the integers from 1 to x inclusive. 0! simplifies to 1. For a real or complex number in float or bigfloat precision x, x! simplifies to the value of gamma (x+1). For x equal to n/2 where n is an odd integer, x! simplifies to a rational factor times sqrt (%pi) (since gamma (1/2) is equal to sqrt (%pi)).

The option variables factlim and gammalim control the numerical evaluation of factorials for integer and rational arguments. The functions minfactorial and factcomb simplifies expressions containing factorials.

The functions gamma, bffac, and cbffac are varieties of the gamma function. bffac and cbffac are called internally by gamma to evaluate the gamma function for real and complex numbers in bigfloat precision.

makegamma substitutes gamma for factorials and related functions.

Maxima knows the derivative of the factorial function and the limits for specific values like negative integers.

The option variable factorial_expand controls the simplification of expressions like (n+x)!, where n is an integer.

10.4 Root, Exponential and Logarithmic Functions

Option variable: %e_to_numlog

Default value: false

When true, r some rational number, and x some expression, %e^(r*log(x)) will be simplified into x^r . It should be noted that the radcan command also does this transformation, and more complicated transformations of this ilk as well. The logcontract command "contracts" expressions containing log.

Category: Exponential and logarithm functions · Category: Simplification flags and variables

Option variable: %emode

Default value: true

When %emode is true, %e^(%pi %i x) is simplified as follows.

%e^(%pi %i x) simplifies to cos (%pi x) + %i sin (%pi x) if x is a floating point number, an integer, or a multiple of 1/2, 1/3, 1/4, or 1/6, and then further simplified.

For other numerical x, %e^(%pi %i x) simplifies to %e^(%pi %i y) where y is x - 2 k for some integer k such that abs(y) < 1.

When %emode is false, no special simplification of %e^(%pi %i x) is carried out.

(%i1) %emode;
(%o1)                         true

(%i2) %e^(%pi*%i*1);
(%o2)                          - 1

(%i3) %e^(%pi*%i*216/144);
(%o3)                         - %i

(%i4) %e^(%pi*%i*192/144);
                          sqrt(3) %i    1
(%o4)                  (- ----------) - -
                              2         2

(%i5) %e^(%pi*%i*180/144);
                           %i          1
(%o5)                 (- -------) - -------
                         sqrt(2)    sqrt(2)

(%i6) %e^(%pi*%i*120/144);
                          %i   sqrt(3)
(%o6)                     -- - -------
                          2       2

(%i7) %e^(%pi*%i*121/144);
                            121 %i %pi
                            ----------
                               144
(%o7)                     %e

Category: Exponential and logarithm functions · Category: Simplification flags and variables

Option variable: %enumer

Default value: false

When %enumer is true, %e is replaced by its numeric value 2.718… whenever numer is true.

When %enumer is false, this substitution is carried out only if the exponent in %e^x evaluates to a number.

10.5 Trigonometric Functions

10.5.1 Introduction to Trigonometric

Maxima has many trigonometric functions defined. Not all trigonometric identities are programmed, but it is possible for the user to add many of them using the pattern matching capabilities of the system. The trigonometric functions defined in Maxima are: acos, acosh, acot, acoth, acsc, acsch, asec, asech, asin, asinh, atan, atanh, cos, cosh, cot, coth, csc, csch, sec, sech, sin, sinh, tan, and tanh. There are a number of commands especially for handling trigonometric functions, see trigexpand, trigreduce, and the switch trigsign. Two share packages extend the simplification rules built into Maxima, ntrig and atrig1. Do describe(command) for details.

Category: Trigonometric functions · Category: Simplification flags and variables

10.5.2 Functions and Variables for Trigonometric

Option variable: %piargs

Default value: true

When %piargs is true, trigonometric functions are simplified to algebraic constants when the argument is an integer multiple of %pi, %pi/2, %pi/3, %pi/4, or %pi/6.

Maxima knows some identities which can be applied when %pi, etc., are multiplied by an integer variable (that is, a symbol declared to be integer).

Examples:

(%i1) %piargs : false$

(%i2) [sin (%pi), sin (%pi/2), sin (%pi/3)];
                                %pi       %pi
(%o2)            [sin(%pi), sin(---), sin(---)]
                                 2         3

(%i3) [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
                      %pi       %pi       %pi
(%o3)            [sin(---), sin(---), sin(---)]
                       4         5         6

(%i4) %piargs : true$

(%i5) [sin (%pi), sin (%pi/2), sin (%pi/3)];
                                sqrt(3)
(%o5)                    [0, 1, -------]
                                   2

(%i6) [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
                         1         %pi   1
(%o6)                [-------, sin(---), -]
                      sqrt(2)       5    2

(%i7) [cos (%pi/3), cos (10*%pi/3), tan (10*%pi/3),
       cos (sqrt(2)*%pi/3)];
                1    1               sqrt(2) %pi
(%o7)          [-, - -, sqrt(3), cos(-----------)]
                2    2                    3

Some identities are applied when %pi and %pi/2 are multiplied by an integer variable.

(%i1) declare (n, integer, m, even)$

(%i2) [sin (%pi * n), cos (%pi * m), sin (%pi/2 * m),
       cos (%pi/2 * m)];
                                      m/2
(%o2)                  [0, 1, 0, (- 1)   ]

Option variable: %iargs

Default value: true

When %iargs is true, trigonometric functions are simplified to hyperbolic functions when the argument is apparently a multiple of the imaginary unit %i.

Even when the argument is demonstrably real, the simplification is applied; Maxima considers only whether the argument is a literal multiple of %i.

Examples:

(%i1) %iargs : false$

(%i2) [sin (%i * x), cos (%i * x), tan (%i * x)];
(%o2)           [sin(%i x), cos(%i x), tan(%i x)]

(%i3) %iargs : true$

(%i4) [sin (%i * x), cos (%i * x), tan (%i * x)];
(%o4)           [%i sinh(x), cosh(x), %i tanh(x)]

Even when the argument is demonstrably real, the simplification is applied.

(%i1) declare (x, imaginary)$

(%i2) [featurep (x, imaginary), featurep (x, real)];
(%o2)                     [true, false]

(%i3) sin (%i * x);
(%o3)                      %i sinh(x)

Category: Trigonometric functions · Category: Hyperbolic functions · Category: Simplification flags and variables

Function: acos (x)

– Arc Cosine.

Function: acosh (x)

– Hyperbolic Arc Cosine.

Function: acot (x)

– Arc Cotangent.

Function: acoth (x)

– Hyperbolic Arc Cotangent.

Function: acsc (x)

– Arc Cosecant.

Function: acsch (x)

– Hyperbolic Arc Cosecant.

Function: asec (x)

– Arc Secant.

Function: asech (x)

– Hyperbolic Arc Secant.

Function: asin (x)

– Arc Sine.

Function: asinh (x)

– Hyperbolic Arc Sine.

Category: Random numbers · Category: Numerical methods

Function: atan (x)

– Arc Tangent.

10.6 Random Numbers

Function: make_random_state
    make_random_state (n)
    make_random_state (s)
    make_random_state (true)
    make_random_state (false)

A random state object represents the state of the random number generator. The state comprises 627 32-bit words.

make_random_state (n) returns a new random state object created from an integer seed value equal to n modulo 2^32. n may be negative.

make_random_state (s) returns a copy of the random state s.

make_random_state (true) returns a new random state object, using the current computer clock time as the seed.

make_random_state (false) returns a copy of the current state of the random number generator.

Category: Random numbers

Function: set_random_state (s)

Copies s to the random number generator state.

set_random_state always returns done.

Category: Random numbers

Function: random (x)

Returns a pseudorandom number. If x is an integer, random (x) returns an integer from 0 through x - 1 inclusive. If x is a floating point number, random (x) returns a nonnegative floating point number less than x. random complains with an error if x is neither an integer nor a float, or if x is not positive.

The functions make_random_state and set_random_state maintain the state of the random number generator.

The Maxima random number generator is an implementation of the Mersenne twister MT 19937.

Examples:

(%i1) s1: make_random_state (654321)$

(%i2) set_random_state (s1);
(%o2)                         done

(%i3) random (1000);
(%o3)                          768

(%i4) random (9573684);
(%o4)                        7657880

(%i5) random (2^75);
(%o5)                11804491615036831636390

(%i6) s2: make_random_state (false)$

(%i7) random (1.0);
(%o7)                  0.2310127244107132

(%i8) random (10.0);
(%o8)                   4.394553645870825

(%i9) random (100.0);
(%o9)                   32.28666704056853

(%i10) set_random_state (s2);
(%o10)                        done

(%i11) random (1.0);
(%o11)                 0.2310127244107132

(%i12) random (10.0);
(%o12)                  4.394553645870825

(%i13) random (100.0);
(%o13)                  32.28666704056853

11 Maximas Database

11.1 Introduction to Maximas Database

11.2 Functions and Variables for Properties

Property: alphabetic

alphabetic is a property type recognized by declare. The expression declare(s, alphabetic) tells Maxima to recognize as alphabetic all of the characters in s, which must be a string.

See also declare.

Example:

(%i1) declare(n, integer, x, noninteger);
(%o1)                         done
(%i2) askinteger(n);
(%o2)                          yes
(%i3) askinteger(x);
(%o3)                          no

Property: integervalued

declare(f, integervalued) tells Maxima to recognize f as an integer-valued function.

See also declare.

Example:

(%i1) exp(%i)^f(x);
                              %i f(x)
(%o1)                      (%e  )
(%i2) declare(f, integervalued);
(%o2)                         done
(%i3) exp(%i)^f(x);
                              %i f(x)
(%o3)                       %e

Property: nonarray

The command declare(a, nonarray) tells Maxima to consider a not an array. This declaration prevents multiple evaluation, if a is a subscripted variable.

See also declare.

Example:

(%i1) a:'b$ b:'c$ c:'d$

(%i4) a[x];
(%o4)                          d
                                x
(%i5) declare(a, nonarray);
(%o5)                         done
(%i6) a[x];
(%o6)                          a
                                x

Category: Declarations and inferences · Category: Vectors · Category: Matrices

Property: nonscalar

Makes atoms behave as does a list or matrix with respect to the dot operator.

See also declare.

Function: nonscalarp (expr)

Returns true if expr is a non-scalar, i.e., it contains atoms declared as non-scalars, lists, or matrices.

See also the predicate function scalarp and declare.

Category: Predicate functions · Category: Vectors · Category: Matrices

Property: posfun

declare (f, posfun) declares f to be a positive function. is (f(x) > 0) yields true.

See also declare.

Category: Declarations and inferences · Category: Operators

Function: printprops
    printprops (a, i)
    printprops ([a_1, …, a_n], i)
    printprops (all, i)

Displays the property with the indicator i associated with the atom a. a may also be a list of atoms or the atom all in which case all of the atoms with the given property will be used. For example, printprops ([f, g], atvalue). printprops is for properties that cannot otherwise be displayed, i.e. for atvalue, atomgrad, gradef, and matchdeclare.

Category: Declarations and inferences · Category: Display functions

Function: properties (a)

Returns a list of the names of all the properties associated with the atom a.

Category: Declarations and inferences · Category: Global variables

System variable: props

Default value: []

props are atoms which have any property other than those explicitly mentioned in infolists, such as specified by atvalue, matchdeclare, etc., as well as properties specified in the declare function.

Function: propvars (prop)

Returns a list of those atoms on the props list which have the property indicated by prop. Thus propvars (atvalue) returns a list of atoms which have atvalues.

Function: put (atom, value, indicator)

Assigns value to the property (specified by indicator) of atom. indicator may be the name of any property, not just a system-defined property.

rem reverses the effect of put.

put evaluates its arguments. put returns value.

See also declare.

Property: real

Property: imaginary

Property: complex

declare(a, real), declare(a, imaginary), or declare(a, complex) tells Maxima to recognize a as a real, pure imaginary, or complex variable.

See also declare.

Function: rem (atom, indicator)

Removes the property indicated by indicator from atom. rem reverses the effect of put.

rem returns done if atom had an indicator property when rem was called, or false if it had no such property.

Function: remove
    remove (a_1, p_1, …, a_n, p_n)
    remove ([a_1, …, a_m], [p_1, …, p_n], …)
    remove ("a", operator)
    remove (a, transfun)
    remove (all, p)

Removes properties associated with atoms.

remove (a_1, p_1, ..., a_n, p_n) removes property p_k from atom a_k.

remove ([a_1, ..., a_m], [p_1, ..., p_n], ...) removes properties p_1, ..., p_n from atoms a_1, …, a_m. There may be more than one pair of lists.

remove (all, p) removes the property p from all atoms which have it.

The removed properties may be system-defined properties such as function, macro, or mode_declare. remove does not remove properties defined by put.

A property may be transfun to remove the translated Lisp version of a function. After executing this, the Maxima version of the function is executed rather than the translated version.

remove ("a", operator) or, equivalently, remove ("a", op) removes from a the operator properties declared by prefix, infix, nary, postfix, matchfix, or nofix. Note that the name of the operator must be written as a quoted string.

remove always returns done whether or not an atom has a specified property. This behavior is unlike the more specific remove functions remvalue, remarray, remfunction, and remrule.

remove quotes its arguments.

Property: scalar

declare(a, scalar) tells Maxima to consider a a scalar variable.

See also declare.

Function: scalarp (expr)

Returns true if expr is a number, constant, or variable declared scalar with declare, or composed entirely of numbers, constants, and such variables, but not containing matrices or lists.

See also the predicate function nonscalarp.

Category: Predicate functions · Category: Vectors · Category: Matrices

11.3 Functions and Variables for Facts

Function: activate (context_1, …, context_n)

Activates the contexts context_1, …, context_n. The facts in these contexts are then available to make deductions and retrieve information. The facts in these contexts are not listed by facts ().

The variable activecontexts is the list of contexts which are active by way of the activate function.

System variable: activecontexts

Default value: []

activecontexts is a list of the contexts which are active by way of the activate function, as opposed to being active because they are subcontexts of the current context.

Function: askinteger
    askinteger (expr, integer)
    askinteger (expr)
    askinteger (expr, even)
    askinteger (expr, odd)

askinteger (expr, integer) attempts to determine from the assume database whether expr is an integer. askinteger prompts the user if it cannot tell otherwise, and attempt to install the information in the database if possible. askinteger (expr) is equivalent to askinteger (expr, integer).

askinteger (expr, even) and askinteger (expr, odd) likewise attempt to determine if expr is an even integer or odd integer, respectively.

Function: asksign (expr)

First attempts to determine whether the specified expression is positive, negative, or zero. If it cannot, it asks the user the necessary questions to complete its deduction. The user’s answer is recorded in the data base for the duration of the current computation. The return value of asksign is one of pos, neg, or zero.

Function: assume (pred_1, …, pred_n)

Adds predicates pred_1, …, pred_n to the current context. If a predicate is inconsistent or redundant with the predicates in the current context, it is not added to the context. The context accumulates predicates from each call to assume.

assume returns a list whose elements are the predicates added to the context or the atoms redundant or inconsistent where applicable.

The predicates pred_1, …, pred_n can only be expressions with the relational operators < <= equal notequal >= and >. Predicates cannot be literal equality = or literal inequality # expressions, nor can they be predicate functions such as integerp.

Compound predicates of the form pred_1 and ... and pred_n are recognized, but not pred_1 or ... or pred_n. not pred_k is recognized if pred_k is a relational predicate. Expressions of the form not (pred_1 and pred_2) and not (pred_1 or pred_2) are not recognized.

Maxima’s deduction mechanism is not very strong; there are many obvious consequences which cannot be determined by is. This is a known weakness.

assume does not handle predicates with complex numbers. If a predicate contains a complex number assume returns inconsistent or redunant.

assume evaluates its arguments.

See also is, facts, forget, context, and declare.

Examples:

(%i1) assume (xx > 0, yy < -1, zz >= 0);
(%o1)              [xx > 0, yy < - 1, zz >= 0]
(%i2) assume (aa < bb and bb < cc);
(%o2)                  [bb > aa, cc > bb]
(%i3) facts ();
(%o3)     [xx > 0, - 1 > yy, zz >= 0, bb > aa, cc > bb]
(%i4) is (xx > yy);
(%o4)                         true
(%i5) is (yy < -yy);
(%o5)                         true
(%i6) is (sinh (bb - aa) > 0);
(%o6)                         true
(%i7) forget (bb > aa);
(%o7)                       [bb > aa]
(%i8) prederror : false;
(%o8)                         false
(%i9) is (sinh (bb - aa) > 0);
(%o9)                        unknown
(%i10) is (bb^2 < cc^2);
(%o10)                       unknown

Option variable: assumescalar

Default value: true

assumescalar helps govern whether expressions expr for which nonscalarp (expr) is false are assumed to behave like scalars for certain transformations.

Let expr represent any expression other than a list or a matrix, and let [1, 2, 3] represent any list or matrix. Then expr . [1, 2, 3] yields [expr, 2 expr, 3 expr] if assumescalar is true, or scalarp (expr) is true, or constantp (expr) is true.

If assumescalar is true, such expressions will behave like scalars only for commutative operators, but not for noncommutative multiplication ..

When assumescalar is false, such expressions will behave like non-scalars.

When assumescalar is all, such expressions will behave like scalars for all the operators listed above.

Option variable: assume_pos

Default value: false

When assume_pos is true and the sign of a parameter x cannot be determined from the current context or other considerations, sign and asksign (x) return true. This may forestall some automatically-generated asksign queries, such as may arise from integrate or other computations.

By default, a parameter is x such that symbolp (x) or subvarp (x). The class of expressions considered parameters can be modified to some extent via the variable assume_pos_pred.

sign and asksign attempt to deduce the sign of expressions from the sign of operands within the expression. For example, if a and b are both positive, then a + b is also positive.

However, there is no way to bypass all asksign queries. In particular, when the asksign argument is a difference x - y or a logarithm log(x), asksign always requests an input from the user, even when assume_pos is true and assume_pos_pred is a function which returns true for all arguments.

Category: Mathematical functions

Option variable: assume_pos_pred

Default value: false

When assume_pos_pred is assigned the name of a function or a lambda expression of one argument x, that function is called to determine whether x is considered a parameter for the purpose of assume_pos. assume_pos_pred is ignored when assume_pos is false.

The assume_pos_pred function is called by sign and asksign with an argument x which is either an atom, a subscripted variable, or a function call expression. If the assume_pos_pred function returns true, x is considered a parameter for the purpose of assume_pos.

By default, a parameter is x such that symbolp (x) or subvarp (x).

11.4 Functions and Variables for Predicates

Function: charfun (p)

Return 0 when the predicate p evaluates to false; return 1 when the predicate evaluates to true. When the predicate evaluates to something other than true or false (unknown), return a noun form.

Examples:

(%i1) charfun (x < 1);
(%o1)                    charfun(x < 1)
(%i2) subst (x = -1, %);
(%o2)                           1
(%i3) e : charfun ('"and" (-1 < x, x < 1))$
(%i4) [subst (x = -1, e), subst (x = 0, e), subst (x = 1, e)];
(%o4)                       [0, 1, 0]

Function: compare (x, y)

Return a comparison operator op (<, <=, >, >=, =, or #) such that is (x op y) evaluates to true; when either x or y depends on %i and x # y, return notcomparable; when there is no such operator or Maxima isn’t able to determine the operator, return unknown.

Examples:

(%i1) compare (1, 2);
(%o1)                           <
(%i2) compare (1, x);
(%o2)                        unknown
(%i3) compare (%i, %i);
(%o3)                           =
(%i4) compare (%i, %i + 1);
(%o4)                     notcomparable
(%i5) compare (1/x, 0);
(%o5)                           #
(%i6) compare (x, abs(x));
(%o6)                          <=

The function compare doesn’t try to determine whether the real domains of its arguments are nonempty; thus

(%i1) compare (acos (x^2 + 1), acos (x^2 + 1) + 1);
(%o1)                           <

The real domain of acos (x^2 + 1) is empty.

Function: equal (a, b)

Represents equivalence, that is, equal value.

By itself, equal does not evaluate or simplify. The function is attempts to evaluate equal to a Boolean value. is(equal(a, b)) returns true (or false) if and only if a and b are equal (or not equal) for all possible values of their variables, as determined by evaluating ratsimp(a - b); if ratsimp returns 0, the two expressions are considered equivalent. Two expressions may be equivalent even if they are not syntactically equal (i.e., identical).

When is fails to reduce equal to true or false, the result is governed by the global flag prederror. When prederror is true, is complains with an error message. Otherwise, is returns unknown.

In addition to is, some other operators evaluate equal and notequal to true or false, namely if, and, or, and not.

The negation of equal is notequal.

Examples:

By itself, equal does not evaluate or simplify.

(%i1) equal (x^2 - 1, (x + 1) * (x - 1));
                        2
(%o1)            equal(x  - 1, (x - 1) (x + 1))
(%i2) equal (x, x + 1);
(%o2)                    equal(x, x + 1)
(%i3) equal (x, y);
(%o3)                      equal(x, y)

The function is attempts to evaluate equal to a Boolean value. is(equal(a, b)) returns true when ratsimp(a - b) returns 0. Two expressions may be equivalent even if they are not syntactically equal (i.e., identical).

(%i1) ratsimp (x^2 - 1 - (x + 1) * (x - 1));
(%o1)                           0
(%i2) is (equal (x^2 - 1, (x + 1) * (x - 1)));
(%o2)                         true
(%i3) is (x^2 - 1 = (x + 1) * (x - 1));
(%o3)                         false
(%i4) ratsimp (x - (x + 1));
(%o4)                          - 1
(%i5) is (equal (x, x + 1));
(%o5)                         false
(%i6) is (x = x + 1);
(%o6)                         false
(%i7) ratsimp (x - y);
(%o7)                         x - y
(%i8) is (equal (x, y));
(%o8)                        unknown
(%i9) is (x = y);
(%o9)                         false

When is fails to reduce equal to true or false, the result is governed by the global flag prederror.

(%i1) [aa : x^2 + 2*x + 1, bb : x^2 - 2*x - 1];
                    2             2
(%o1)             [x  + 2 x + 1, x  - 2 x - 1]
(%i2) ratsimp (aa - bb);
(%o2)                        4 x + 2
(%i3) prederror : true;
(%o3)                         true
(%i4) is (equal (aa, bb));
Maxima was unable to evaluate the predicate:
       2             2
equal(x  + 2 x + 1, x  - 2 x - 1)
 -- an error.  Quitting.  To debug this try debugmode(true);
(%i5) prederror : false;
(%o5)                         false
(%i6) is (equal (aa, bb));
(%o6)                        unknown

Some operators evaluate equal and notequal to true or false.

(%i1) if equal (y, y - 1) then FOO else BAR;
(%o1)                          BAR
(%i2) eq_1 : equal (x, x + 1);
(%o2)                    equal(x, x + 1)
(%i3) eq_2 : equal (y^2 + 2*y + 1, (y + 1)^2);
                         2                   2
(%o3)             equal(y  + 2 y + 1, (y + 1) )
(%i4) [eq_1 and eq_2, eq_1 or eq_2, not eq_1];
(%o4)                  [false, true, true]

Because not expr causes evaluation of expr, not equal(a, b) is equivalent to is(notequal(a, b)).

(%i1) [notequal (2*z, 2*z - 1), not equal (2*z, 2*z - 1)];
(%o1)            [notequal(2 z, 2 z - 1), true]
(%i2) is (notequal (2*z, 2*z - 1));
(%o2)                         true

Function: notequal (a, b)

Represents the negation of equal(a, b).

Examples:

(%i1) equal (a, b);
(%o1)                      equal(a, b)
(%i2) maybe (equal (a, b));
(%o2)                        unknown
(%i3) notequal (a, b);
(%o3)                    notequal(a, b)
(%i4) not equal (a, b);
(%o4)                    notequal(a, b)
(%i5) maybe (notequal (a, b));
(%o5)                        unknown
(%i6) assume (a > b);
(%o6)                        [a > b]
(%i7) equal (a, b);
(%o7)                      equal(a, b)
(%i8) maybe (equal (a, b));
(%o8)                         false
(%i9) notequal (a, b);
(%o9)                    notequal(a, b)
(%i10) maybe (notequal (a, b));
(%o10)                        true

Category: Predicate functions · Category: Simplification functions

Function: unknown (expr)

Returns true if and only if expr contains an operator or function not recognized by the Maxima simplifier.

Function: zeroequiv (expr, v)

Tests whether the expression expr in the variable v is equivalent to zero, returning true, false, or dontknow.

zeroequiv has these restrictions:

Do not use functions that Maxima does not know how to differentiate and evaluate.
If the expression has poles on the real line, there may be errors in the result (but this is unlikely to occur).
If the expression contains functions which are not solutions to first order differential equations (e.g. Bessel functions) there may be incorrect results.
The algorithm uses evaluation at randomly chosen points for carefully selected subexpressions. This is always a somewhat hazardous business, although the algorithm tries to minimize the potential for error.

For example zeroequiv (sin(2 * x) - 2 * sin(x) * cos(x), x) returns true and zeroequiv (%e^x + x, x) returns false. On the other hand zeroequiv (log(a * b) - log(a) - log(b), a) returns dontknow because of the presence of an extra parameter b.

Category: Predicate functions

12 Plotting

12.1 Introduction to Plotting

Maxima uses an external plotting package to make the plots (see the section on Plotting Formats). The plotting functions calculate a set of points and pass them to the plotting package together with a set of commands. That information can be passed to the external program either through a pipe or by calling the program with the name of a file where the data has been saved. The data file is given the name maxout_xxx.format, where xxx is a number that is unique to every concurrently-running instance of Maxima and format is the name of the plotting format being used (gnuplot, xmaxima, mgnuplot, gnuplot_pipes or geomview).

There are to save the plot in a graphic format file. In those cases, the file maxout_xxx.format created by Maxima includes commands that will make the external plotting program save the result in a graphic file. The default name for that graphic file is maxplot.extension, where extension is the extension normally used for the kind of graphic file selected.

The maxout_xxx.format and maxplot.extension files are created in the directory specified by the system variable maxima_tempdir. That location can be changed by assigning to that variable (or to the environment variable MAXIMA_TEMPDIR) a string that represents a valid directory where Maxima can create new files. The output of the Maxima plotting command will be a list with the names of the file(s) created, including their complete path.

If the format used is either gnuplot or xmaxima, the external programs gnuplot or xmaxima can be run, giving it the file maxout_xxx.format as argument, in order to view again a plot previously created in Maxima. Thus, when a Maxima plotting command fails, the format can be set to gnuplot or xmaxima and the plain-text file maxout_xxx.gnuplot (or maxout_xxx.xmaxima) can be inspected to look for the source of the problem.

The additional package draw provides functions similar to the ones described in this section with some extra features. Note that some plotting options have the same name in both plotting packages, but their syntax and behavior is different. To view the documentation for a graphic option opt, type ?? opt in order to choose the information for either of those two packages.

12.2 Plotting Formats

Maxima can use either Gnuplot, Xmaxima or Geomview as graphics program. Gnuplot and Geomview are external programs which must be installed separately, while Xmaxima is distributed with Maxima. There are various different formats for those programs, which can be selected with the option plot_format (see also the Plotting Options section).

The plotting formats are the following:

gnuplot (default on Windows)
Used to launch the external program gnuplot, which must be installed in your system. All plotting commands and data are saved into the file maxout_xxx.gnuplot.
gnuplot_pipes (default on non-Windows platforms)
This format is not available in Windows platforms. It is similar to the gnuplot format except that the commands are sent to gnuplot through a pipe, while the data are saved into the file maxout_xxx.gnuplot_pipes. A single gnuplot process is kept open and subsequent plot commands will be sent to the same process, replacing previous plots, unless the gnuplot pipe is closed with the function gnuplot_close. When this format is used, the function gnuplot_replot can be used to modify a plot that has already displayed on the screen.

This format is only used to plot to the screen; whenever graphic files are created, the format is silently switched to gnuplot and the commands needed to create the graphic file are saved with the data in file maxout_xxx.gnuplot.
mgnuplot
Mgnuplot is a Tk-based wrapper around gnuplot. It is included in the Maxima distribution. Mgnuplot offers a rudimentary GUI for gnuplot, but has fewer overall features than the plain gnuplot interface. Mgnuplot requires an external gnuplot installation and, in Unix systems, the Tcl/Tk system.
xmaxima
Xmaxima is a Tcl/Tk graphical interface for Maxima that can also be used to display plots created when Maxima is run from the console or from other graphical interfaces. To use this format, the xmaxima program, which is distributed together with Maxima, must be installed. If Maxima is being run from the Xmaxima console, the data and commands are passed to xmaxima through the same socket used for the communication between Maxima and the Xmaxima console. When used from a terminal or from graphical interfaces different from Xmaxima, the commands and data are saved in the file maxout_xxx.xmaxima and xmaxima is run with the name of that file as argument.

In previous versions this format used to be called openmath; that old name still works as a synonym for xmaxima.
geomview
Geomview, a Motif based interactive 3D viewing program for Unix, can also be used to display plots created by Maxima. To use this format, the geomview program must be installed.

12.3 Functions and Variables for Plotting

Function: contour_plot (expr, x_range, y_range, options, …)

It plots the contours (curves of equal value) of expr over the region x_range by y_range. Any additional arguments are treated the same as in plot3d.

This function only works when the plot format is either gnuplot or gnuplot_pipes. The additional package implicit_plot, which works in any graphic format, can also be used to plot contours but a separate expression must be given for each contour.

Examples:

(%i1) contour_plot (x^2 + y^2, [x, -4, 4], [y, -4, 4])$

You can add any options accepted by plot3d; for instance, the option legend with a value of false, to remove the legend. By default, Gnuplot chooses and displays 3 contours. To increase the number of contours, it is necessary to use a custom gnuplot_preamble, as in the next example:

(%i1) contour_plot (u^3 + v^2, [u, -4, 4], [v, -4, 4],
              [legend,false],
              [gnuplot_preamble, "set cntrparam levels 12"])$

System variable: geomview_command

This variable stores the name of the command used to run the geomview program when the plot format is geomview. Its default value is "geomview". If the geomview program is not found unless you give its complete path or if you want to try a different version of it, you may change the value of this variable. For instance,

(%i1) geomview_command: "/usr/local/bin/my_geomview"$

Function: get_plot_option (keyword, index)

Returns the current default value of the option named keyword, which is a list. The optional argument index must be a positive integer which can be used to extract only one element from the list (element 1 is the name of the option).

See also set_plot_option, remove_plot_option and the section on Plotting Options.

System variable: gnuplot_command

This variable stores the name of the command used to run the gnuplot program when the plot format is gnuplot. Its default value is "gnuplot". If the gnuplot program is not found unless you give its complete path or if you want to try a different version of it, you may change the value of this variable. For instance,

(%i1) gnuplot_command: "/usr/local/bin/my_gnuplot"$

System variable: gnuplot_file_args

When a graphic file is going to be created using gnuplot, this variable is used to specify the way the file name should be passed to gnuplot. Its default value is "~s", which means that the name of the file will be passed directly. The contents of this variable can be changed in order to add options for the gnuplot program, adding those options before the format directive "~s".

System variable: gnuplot_view_args

This variable is used to parse the argument that will be passed to the gnuplot program when the plot format is gnuplot. Its default value is "-persist ~s", where "~s" will be replaced with the name of the file where the gnuplot commands have been written (usually "maxout_xxx.gnuplot"). The option -persist tells gnuplot to exit after the commands in the file have been executed, without closing the window that displays the plot.

Those familiar with gnuplot, might want to change the value of this variable. For example, by changing it to:

(%i1) gnuplot_view_args: "~s -"$

gnuplot will not be closed after the commands in the file have been executed; thus, the window with the plot will remain, as well as the gnuplot interactive shell where other commands can be issued in order to modify the plot.

In Windows versions of Gnuplot older than 4.6.3 the behavior of "~s -" and "-persist ~s" were the opposite; namely, "-persist ~s" made the plot window and the gnuplot interactive shell remain, while "~s -" closed the gnuplot shell keeping the plot window. Therefore, when older gnuplot versions are used in Windows, it might be necessary to adjust the value of gnuplot_view_args.

Category: Plotting · Category: Share packages · Category: Package implicit_plot

Function: implicit_plot
implicit_plot (expr, x_range, y_range)
implicit_plot ([expr_1, …, expr_n], x_range, y_range)

Displays a plot of a function on the real plane, defined implicitly by the expression expr. The domain in the plane is defined by x_range and y_range. Several functions can be represented on the same plot, giving a list [expr_1, …, expr_n] of expressions that define them. This function uses the global format options set up with the set_plot_option. Additional options can also be given as extra arguments for the implicit_plot command.

The method used by implicit_plot consists of tracking sign changes on the domain given and it can fail for complicated expressions.

load(implicit_plot) loads this function.

Example:

(%i1) load(implicit_plot)$
(%i2) implicit_plot (x^2 = y^3 - 3*y + 1, [x, -4, 4], [y, -4, 4])$

Function: julia (x, y, ...options...)

Creates a graphic representation of the Julia set for the complex number (x + i y). The two mandatory parameters x and y must be real. This program is part of the additional package dynamics, but that package does not have to be loaded; the first time julia is used, it will be loaded automatically.

Each pixel in the grid is given a color corresponding to the number of iterations it takes the sequence that starts at that point to move out of the convergence circle of radius 2 centered at the origin. The number of pixels in the grid is controlled by the grid plot option (default 30 by 30). The maximum number of iterations is set with the option iterations. The program uses its own default palette: magenta,violet, blue, cyan, green, yellow, orange, red, brown and black, but it can be changed by adding an explicit palette option in the command.

The default domain used goes from -2 to 2 in both axes and can be changed with the x and y options. By default, the two axes are shown with the same scale, unless the option yx_ratio is used or the option same_xy is disabled. Other general plot options are also accepted.

The following example shows a region of the Julia set for the number -0.55 + i0.6. The option color_bar_tics is used to prevent Gnuplot from adjusting the color box up to 40, in which case the points corresponding the maximum 36 iterations would not be black.

(%i1) julia (-0.55, 0.6, [iterations, 36], [x, -0.3, 0.2],
      [y, 0.3, 0.9], [grid, 400, 400], [color_bar_tics, 0, 6, 36])$

Function: make_transform ([var1, var2, var3], fx, fy, fz)

Returns a function suitable to be used in the option transform_xy of plot3d. The three variables var1, var2, var3 are three dummy variable names, which represent the 3 variables given by the plot3d command (first the two independent variables and then the function that depends on those two variables). The three functions fx, fy, fz must depend only on those 3 variables, and will give the corresponding x, y and z coordinates that should be plotted. There are two transformations defined by default: polar_to_xy and spherical_to_xyz. See the documentation for those two transformations.

Function: mandelbrot (options)

Creates a graphic representation of the Mandelbrot set. This program is part of the additional package dynamics, but that package does not have to be loaded; the first time mandelbrot is used, the package will be loaded automatically.

This program can be called without any arguments, in which case it will use a default value of 9 iterations per point, a grid with dimensions set by the grid plot option (default 30 by 30) and a region that extends from -2 to 2 in both axes. The options are all the same that plot2d accepts, plus an option iterations to change the number of iterations.

Each pixel in the grid is given a color corresponding to the number of iterations it takes the sequence starting at zero to move out of the convergence circle of radius 2, centered at the origin. The maximum number of iterations is set by the option iterations. The program uses its own default palette: magenta,violet, blue, cyan, green, yellow, orange, red, brown and black, but it can be changed by adding an explicit palette option in the command. By default, the two axes are shown with the same scale, unless the option yx_ratio is used or the option same_xy is disabled.

Example:

[grid,400,400])$

(%i1) mandelbrot ([iterations, 30], [x, -2, 1], [y, -1.2, 1.2],
            [grid,400,400])$

System function: polar_to_xy

It can be given as value for the transform_xy option of plot3d. Its effect will be to interpret the two independent variables in plot3d as the distance from the z axis and the azimuthal angle (polar coordinates), and transform them into x and y coordinates.

Function: plot2d
    plot2d (plot, x_range, …, options, …)
    plot2d ([plot_1, …, plot_n], …, options, …)
    plot2d ([plot_1, …, plot_n], x_range, …, options, …)

Where plot, plot_1, …, plot_n can be either expressions, function names or a list with the any of the forms: [discrete, [x1, ..., xn], [y1, ..., yn]], [discrete, [[x1, y1], ..., [xn, ..., yn]]] or [parametric, x_expr, y_expr, t_range].

Displays a plot of one or more expressions as a function of one variable or parameter.

plot2d displays one or several plots in two dimensions. When expressions or function name are used to define the plots, they should all depend on only one variable var and the use of x_range will be mandatory, to provide the name of the variable and its minimum and maximum values; the syntax for x_range is: [variable, min, max].

A plot can also be defined in the discrete or parametric forms. The discrete form is used to plot a set of points with given coordinates. A discrete plot is defined by a list starting with the keyword discrete, followed by one or two lists of values. If two lists are given, they must have the same length; the first list will be interpreted as the x coordinates of the points to be plotted and the second list as the y coordinates. If only one list is given after the discrete keyword, each element on the list could also be a list with two values that correspond to the x and y coordinates of a point, or it could be a sequence of numerical values which will be plotted at consecutive integer values (1,2,3,...) on the x axis.

A parametric plot is defined by a list starting with the keyword parametric, followed by two expressions or function names and a range for the parameter. The range for the parameter must be a list with the name of the parameter followed by its minimum and maximum values: [param, min, max]. The plot will show the path traced out by the point with coordinates given by the two expressions or functions, as param increases from min to max.

A range for the vertical axis is an optional argument with the form: [y, min, max] (the keyword y is always used for the vertical axis). If that option is used, the plot will show that exact vertical range, independently of the values reached by the plot. If the vertical range is not specified, it will be set up according to the minimum and maximum values of the second coordinate of the plot points.

All other options should also be lists, starting with a keyword and followed by one or more values. See plot_options.

If there are several plots to be plotted, a legend will be written to identity each of the expressions. The labels that should be used in that legend can be given with the option legend. If that option is not used, Maxima will create labels from the expressions or function names.

Examples:

Plot of a common function:

(%i1) plot2d (sin(x), [x, -%pi, %pi])$

If the function grows too fast, it might be necessary to limit the values in the vertical axis using the y option:

(%i1) plot2d (sec(x), [x, -2, 2], [y, -20, 20])$

When the plot box is disabled, no labels are created for the axes. In that case, instead of using xlabel and ylabel to set the names of the axes, it is better to use option label, which allows more flexibility. Option yx_ratio is used to change the default rectangular shape of the plot; in this example the plot will fill a square.

(%i1) plot2d ( x^2 - 1, [x, -3, 3], [box, false], grid2d,
      [yx_ratio, 1], [axes, solid], [xtics, -2, 4, 2],
      [ytics, 2, 2, 6], [label, ["x", 2.9, -0.3],
      ["x^2-1", 0.1, 8]], [title, "A parabola"])$

A plot with a logarithmic scale in the vertical axis:

(%i1) plot2d (exp(3*s), [s, -2, 2], logy)$

Plotting functions by name:

(%i1) F(x) := x^2 $

(%i2) :lisp (defun |$g| (x) (m* x x x))
$g

(%i2) H(x) := if x < 0 then x^4 - 1 else 1 - x^5 $
(%i3) plot2d ([F, G, H], [u, -1, 1], [y, -1.5, 1.5])$

A plot of the butterfly curve, defined parametrically:

(%i1) r: (exp(cos(t))-2*cos(4*t)-sin(t/12)^5)$
(%i2) plot2d([parametric, r*sin(t), r*cos(t), [t, -8*%pi, 8*%pi]])$

Plot of a circle, using its parametric representation, together with the function -|x|. The circle will only look like a circle if the scale in the two axes is the same, which is done with the option same_xy.

(%i1) plot2d([[parametric, cos(t), sin(t), [t,0,2*%pi]], -abs(x)],
         [x, -sqrt(2), sqrt(2)], same_xy)$

A plot of 200 random numbers between 0 and 9:

(%i1) plot2d ([discrete, makelist ( random(10), 200)])$

A plot of a discrete set of points, defining x and y coordinates separately:

(%i1) plot2d ([discrete, makelist(i*%pi, i, 1, 5),
                            [0.6, 0.9, 0.2, 1.3, 1]])$

In the next example a table with three columns is saved in a file “data.txt” which is then read and the second and third column are plotted on the two axes:

(%i1) with_stdout ("data.txt", for x:0 thru 10 do
                             print (x, x^2, x^3))$

(%i2) data: read_matrix ("data.txt")$

(%i3) plot2d ([discrete, transpose(data)[2], transpose(data)[3]],
  [style,points], [point_type,diamond], [color,red])$

A plot of discrete data points together with a continuous function:

(%i1) xy: [[10, .6], [20, .9], [30, 1.1], [40, 1.3], [50, 1.4]]$

(%i2) plot2d([[discrete, xy], 2*%pi*sqrt(l/980)], [l,0,50],
        [style, points, lines], [color, red, blue],
        [point_type, asterisk],
        [legend, "experiment", "theory"],
        [xlabel, "pendulum's length (cm)"],
        [ylabel, "period (s)"])$

See also the section about Plotting Options.

Function: plot3d
plot3d (expr, x_range, y_range, …, options, …)
plot3d ([expr_1, …, expr_n], x_range, y_range, …, options, …)

Displays a plot of one or more surfaces defined as functions of two variables or in parametric form.

The functions to be plotted may be specified as expressions or function names. The mouse can be used to rotate the plot looking at the surface from different sides.

Examples:

Plot of a function of two variables:

(%i1) plot3d (u^2 - v^2, [u, -2, 2], [v, -3, 3], [grid, 100, 100],
        [mesh_lines_color,false])$

Use of the z option to limit a function that goes to infinity (in this case the function is minus infinity on the x and y axes); this also shows how to plot with only lines and no shading:

(%i1) plot3d ( log ( x^2*y^2 ), [x, -2, 2], [y, -2, 2], [z, -8, 4],
         [palette, false], [color, magenta])$

The infinite values of z can also be avoided by choosing a grid that does not fall on any points where the function is undefined, as in the next example, which also shows how to change the palette and how to include a color bar that relates colors to values of the z variable:

(%i1) plot3d (log (x^2*y^2), [x, -2, 2], [y, -2, 2],[grid, 29, 29],
       [palette, [gradient, red, orange, yellow, green]],
       color_bar, [xtics, 1], [ytics, 1], [ztics, 4],
       [color_bar_tics, 4])$

Two surfaces in the same plot. Ranges specific to one of the surfaces can be given by placing each expression and its ranges in a separate list; global ranges for the complete plot are also given after the functions definitions.

(%i1) plot3d ([[-3*x - y, [x, -2, 2], [y, -2, 2]],
   4*sin(3*(x^2 + y^2))/(x^2 + y^2), [x, -3, 3], [y, -3, 3]],
   [x, -4, 4], [y, -4, 4])$

Plot of a Klein bottle, defined parametrically:

(%i1) expr_1: 5*cos(x)*(cos(x/2)*cos(y)+sin(x/2)*sin(2*y)+3)-10$
(%i2) expr_2: -5*sin(x)*(cos(x/2)*cos(y)+sin(x/2)*sin(2*y)+3)$
(%i3) expr_3: 5*(-sin(x/2)*cos(y)+cos(x/2)*sin(2*y))$

(%i4) plot3d ([expr_1, expr_2, expr_3], [x, -%pi, %pi],
        [y, -%pi, %pi], [grid, 50, 50])$

Plot of a “spherical harmonic” function, using the predefined transformation, spherical_to_xyz to transform from spherical coordinates to rectangular coordinates. See the documentation for spherical_to_xyz.

(%i1) plot3d (sin(2*theta)*cos(phi), [theta, 0, %pi],
        [phi, 0, 2*%pi],
        [transform_xy, spherical_to_xyz], [grid,30,60],
   [legend,false])$

Use of the pre-defined function polar_to_xy to transform from cylindrical to rectangular coordinates. See the documentation for polar_to_xy.

(%i1) plot3d (r^.33*cos(th/3), [r,0,1], [th,0,6*%pi], [box, false],
   [grid, 12, 80], [transform_xy, polar_to_xy], [legend, false])$

Plot of a sphere using the transformation from spherical to rectangular coordinates. Option same_xyz is used to get the three axes scaled in the same proportion. When transformations are used, it is not convenient to eliminate the mesh lines, because Gnuplot will not show the surface correctly.

(%i1) plot3d ( 5, [theta, 0, %pi], [phi, 0, 2*%pi], same_xyz,
  [transform_xy, spherical_to_xyz], [mesh_lines_color,blue],
  [palette,[gradient,"#1b1b4e", "#8c8cf8"]], [legend, false])$

Definition of a function of two-variables using a matrix. Notice the single quote in the definition of the function, to prevent plot3d from failing when it realizes that the matrix will require integer indices.

(%i1) M: matrix([1,2,3,4], [1,2,3,2], [1,2,3,4], [1,2,3,3])$
(%i2) f(x, y) := float('M [round(x), round(y)])$

(%i3) plot3d (f(x,y), [x,1,4],[y,1,4],[grid,3,3],[legend,false])$

By setting the elevation equal to zero, a surface can be seen as a map in which each color represents a different level.

(%i1) plot3d (cos (-x^2 + y^3/4), [x,-4,4], [y,-4,4], [zlabel,""],
       [mesh_lines_color,false], [elevation,0], [azimuth,0],
       color_bar, [grid,80,80], [ztics,false], [color_bar_tics,1])$

See also the section about Plotting Options.

System variable: plot_options

This option is being kept for compatibility with older versions, but its use is deprecated. To set global plotting options, see their current values or remove options, use set_plot_option, get_plot_option and remove_plot_option.

Function: remove_plot_option (name)

Removes the default value of an option. The name of the option must be given.

See also set_plot_option, get_plot_option and the section on Plotting Options.

Function: set_plot_option (option)

Accepts any of the options listed in the section Plotting Options, and saves them for use in plotting commands. The values of the options set in each plotting command will have precedence, but if those options are not given, the default values set with this function will be used.

set_plot_option evaluates its argument and returns the complete list of options (after modifying the option given). If called without any arguments, it will simply show the list of current default options.

See also remove_plot_option, get_plot_option and the section on Plotting Options.

Example:

Modification of the grid values.

(%i1) set_plot_option ([grid, 30, 40]);
(%o1) [[plot_format, gnuplot_pipes], [grid, 30, 40], 
[run_viewer, true], [axes, true], [nticks, 29], [adapt_depth, 5], 
[color, blue, red, green, magenta, black, cyan], 
[point_type, bullet, box, triangle, plus, times, asterisk], 
[palette, [gradient, green, cyan, blue, violet], 
[gradient, magenta, violet, blue, cyan, green, yellow, orange, 
red, brown, black]], [gnuplot_preamble, ], [gnuplot_term, default]]

System function: spherical_to_xyz

It can be given as value for the transform_xy option of plot3d. Its effect will be to interpret the two independent variables and the function in plot3d as the spherical coordinates of a point (first, the angle with the z axis, then the angle of the xy projection with the x axis and finally the distance from the origin) and transform them into x, y and z coordinates.

12.4 Plotting Options

All options consist of a list starting with one of the keywords in this section, followed by one or more values. Some of the options may have different effects in different plotting commands as it will be pointed out in the following list. The options that accept among their possible values true or false, can also be set to true by simply writing their names. For instance, typing logx as an option is equivalent to writing [logx, true].

Plot option: adapt_depth [adapt_depth, integer]

Default value: 5

The maximum number of splittings used by the adaptive plotting routine.

Plot option: axes [axes, symbol]

Default value: true

Where symbol can be either true, false, x, y or solid. If false, no axes are shown; if equal to x or y only the x or y axis will be shown; if it is equal to true, both axes will be shown and solid will show the two axes with a solid line, rather than the default broken line. This option does not have any effect in the 3 dimensional plots.

Plot option: azimuth [azimuth, number]

Default value: 30

A plot3d plot can be thought of as starting with the x and y axis in the horizontal and vertical axis, as in plot2d, and the z axis coming out of the screen. The z axis is then rotated around the x axis through an angle equal to elevation and then the new xy plane is rotated around the new z axis through an angle azimuth. This option sets the value for the azimuth, in degrees.

12.5 Gnuplot Options

There are several plot options specific to gnuplot. All of them consist of a keyword (the name of the option), followed by a string that should be a valid gnuplot command, to be passed directly to gnuplot. In most cases, there exist a corresponding plotting option that will produce a similar result and whose use is more recommended than the gnuplot specific option.

Plot option: gnuplot_term [gnuplot_term, terminal_name]

Sets the output terminal type for gnuplot. The argument terminal_name can be a string or one of the following 3 special symbols

default (default value)
Gnuplot output is displayed in a separate graphical window and the gnuplot terminal used will be specified by the value of the option gnuplot_default_term_command.
dumb
Gnuplot output is saved to a file maxout_xxx.gnuplot using "ASCII art" approximation to graphics. If the option gnuplot_out_file is set to filename, the plot will be saved there, instead of the default maxout_xxx.gnuplot. The settings for the “dumb” terminal of Gnuplot are given by the value of option gnuplot_dumb_term_command. If option run_viewer is set to true and the plot_format is gnuplot that ASCII representation will also be shown in the Maxima or Xmaxima console.
ps
Gnuplot generates commands in the PostScript page description language. If the option gnuplot_out_file is set to filename, gnuplot writes the PostScript commands to filename. Otherwise, it is saved as maxplot.ps file. The settings for this terminal are given by the value of the option gnuplot_dumb_term_command.
A string representing any valid gnuplot term specification
Gnuplot can generate output in many other graphical formats such as png, jpeg, svg etc. To use those formats, option gnuplot_term can be set to any supported gnuplot term name (which must be a symbol) or even a full gnuplot term specification with any valid options (which must be a string). For example [gnuplot_term, png] creates output in PNG (Portable Network Graphics) format while [gnuplot_term, "png size 1000,1000"] creates PNG of 1000 x 1000 pixels size. If the option gnuplot_out_file is set to filename, gnuplot writes the output to filename. Otherwise, it is saved as maxplot.term file, where term is gnuplot terminal name.

Plot option: gnuplot_out_file [gnuplot_out_file, file_name]

It can be used to replace the default name for the file that contains the commands that will interpreted by gnuplot, when the terminal is set to default, or to replace the default name of the graphic file that gnuplot creates, when the terminal is different from default. If it contains one or more slashes, “/”, the name of the file will be left as it is; otherwise, it will be appended to the path of the temporary directory. The complete name of the files created by the plotting commands is always sent as output of those commands so they can be seen if the command is ended by semi-colon.

When used in conjunction with the gnuplot_term option, it can be used to save the plot in a file, in one of the graphic formats supported by Gnuplot. To create PNG, PDF, Postscript or SVG, it is easier to use options png_file, pdf_file, ps_file, or svg_file.

Plot option: gnuplot_pm3d [gnuplot_pm3d, value]

With a value of false, it can be used to disable the use of PM3D mode, which is enabled by default.

Plot option: gnuplot_preamble [gnuplot_preamble, string]

This option inserts gnuplot commands before any other commands sent to Gnuplot. Any valid gnuplot commands may be used. Multiple commands should be separated with a semi-colon. See also gnuplot_postamble.

Plot option: gnuplot_postamble [gnuplot_postamble, string]

This option inserts gnuplot commands after other commands sent to Gnuplot and right before the plot command is sent. Any valid gnuplot commands may be used. Multiple commands should be separated with a semi-colon. See also gnuplot_preamble.

Plot option: gnuplot_default_term_command

[gnuplot_default_term_command, command]

The gnuplot command to set the terminal type for the default terminal. It this option is not set, the command used will be: "set term wxt size 640,480 font \",12\"; set term pop".

Plot option: gnuplot_dumb_term_command

[gnuplot_dumb_term_command, command]

The gnuplot command to set the terminal type for the dumb terminal. It this option is not set, the command used will be: "set term dumb 79 22", which makes the text output 79 characters by 22 characters.

Plot option: gnuplot_pdf_term_command [gnuplot_pdf_term_command, command]

The gnuplot command to set the terminal type for the PDF terminal. If this option is not set, the command used will be: "set term pdfcairo color solid lw 3 size 17.2 cm, 12.9 cm font \",18\"". See the gnuplot documentation for more information.

Plot option: gnuplot_png_term_command [gnuplot_png_term_command, command]

The gnuplot command to set the terminal type for the PNG terminal. If this option is not set, the command used will be: "set term pngcairo font \",12\"". See the gnuplot documentation for more information.

Plot option: gnuplot_ps_term_command [gnuplot_ps_term_command, command]

The gnuplot command to set the terminal type for the PostScript terminal. If this option is not set, the command used will be: "set term postscript eps color solid lw 2 size 16.4 cm, 12.3 cm font \",24\"". See the gnuplot documentation for set term postscript for more information.

Plot option: gnuplot_svg_term_command [gnuplot_svg_term_command, command]

The gnuplot command to set the terminal type for the SVG terminal. If this option is not set, the command used will be: "set term svg font \",14\"". See the gnuplot documentation for more information.

Plot option: gnuplot_curve_titles

This is an obsolete option that has been replaced legend described above.

Plot option: gnuplot_curve_styles

This is an obsolete option that has been replaced by style.

12.6 Gnuplot_pipes Format Functions

Function: gnuplot_start ()

Opens the pipe to gnuplot used for plotting with the gnuplot_pipes format. Is not necessary to manually open the pipe before plotting.

Function: gnuplot_close ()

Closes the pipe to gnuplot which is used with the gnuplot_pipes format.

Function: gnuplot_restart ()

Closes the pipe to gnuplot which is used with the gnuplot_pipes format and opens a new pipe.

Function: gnuplot_replot
gnuplot_replot ()
gnuplot_replot (s)

Updates the gnuplot window. If gnuplot_replot is called with a gnuplot command in a string s, then s is sent to gnuplot before reploting the window.

Function: gnuplot_reset ()

Resets the state of gnuplot used with the gnuplot_pipes format. To update the gnuplot window call gnuplot_replot after gnuplot_reset.

Category: File output · Category: Console interaction

13 File Input and Output

13.1 Comments

A comment in Maxima input is any text between /* and */.

The Maxima parser treats a comment as whitespace for the purpose of finding tokens in the input stream; a token always ends at a comment. An input such as a/* foo */b contains two tokens, a and b, and not a single token ab. Comments are otherwise ignored by Maxima; neither the content nor the location of comments is stored in parsed input expressions.

Comments can be nested to arbitrary depth. The /* and */ delimiters form matching pairs. There must be the same number of /* as there are */.

Examples:

(%i1) /* aa is a variable of interest */  aa : 1234;
(%o1)                         1234
(%i2) /* Value of bb depends on aa */  bb : aa^2;
(%o2)                        1522756
(%i3) /* User-defined infix operator */  infix ("b");
(%o3)                           b
(%i4) /* Parses same as a b c, not abc */  a/* foo */b/* bar */c;
(%o4)                         a b c
(%i5) /* Comments /* can be nested /* to any depth */ */ */  1 + xyz;
(%o5)                        xyz + 1

Category: Syntax

13.2 Files

A file is simply an area on a particular storage device which contains data or text. Files on the disks are figuratively grouped into "directories". A directory is just a list of files. Commands which deal with files are:

   appendfile           batch                 batchload
   closefile            file_output_append    filename_merge
   file_search          file_search_maxima    file_search_lisp
   file_search_demo     file_search_usage     file_search_tests
   file_type            file_type_lisp        file_type_maxima
   load                 load_pathname         loadfile
   loadprint            pathname_directory    pathname_name
   pathname_type        printfile             save
   stringout            with_stdout           writefile

When a file name is passed to functions like plot2d, save, or writefile and the file name does not include a path, Maxima stores the file in the current working directory. The current working directory depends on the system like Windows or Linux and on the installation.

13.3 Functions and Variables for File Input and Output

Function: appendfile (filename)

Appends a console transcript to filename. appendfile is the same as writefile, except that the transcript file, if it exists, is always appended.

closefile closes the transcript file opened by appendfile or writefile.

Function: batch
batch (filename)
batch (filename, option)

batch(filename) reads Maxima expressions from filename and evaluates them. batch searches for filename in the list file_search_maxima. See also file_search.

batch(filename, demo) is like demo(filename). In this case batch searches for filename in the list file_search_demo. See demo.

batch(filename, test) is like run_testsuite with the option display_all=true. For this case batch searches filename in the list file_search_maxima and not in the list file_search_tests like run_testsuite. Furthermore, run_testsuite runs tests which are in the list testsuite_files. With batch it is possible to run any file in a test mode, which can be found in the list file_search_maxima. This is useful, when writing a test file.

filename comprises a sequence of Maxima expressions, each terminated with ; or $. The special variable % and the function %th refer to previous results within the file. The file may include :lisp constructs. Spaces, tabs, and newlines in the file are ignored. A suitable input file may be created by a text editor or by the stringout function.

batch reads each input expression from filename, displays the input to the console, computes the corresponding output expression, and displays the output expression. Input labels are assigned to the input expressions and output labels are assigned to the output expressions. batch evaluates every input expression in the file unless there is an error. If user input is requested (by asksign or askinteger, for example) batch pauses to collect the requisite input and then continue.

It may be possible to halt batch by typing control-C at the console. The effect of control-C depends on the underlying Lisp implementation.

batch has several uses, such as to provide a reservoir for working command lines, to give error-free demonstrations, or to help organize one’s thinking in solving complex problems.

batch evaluates its argument. batch returns the path of filename as a string, when called with no second argument or with the option demo. When called with the option test, the return value is a an empty list [] or a list with filename and the numbers of the tests which have failed.

See also load, batchload, and demo.

Category: Session management · Category: File input

Function: batchload (filename)

Reads Maxima expressions from filename and evaluates them, without displaying the input or output expressions and without assigning labels to output expressions. Printed output (such as produced by print or describe)) is displayed, however.

The special variable % and the function %th refer to previous results from the interactive interpreter, not results within the file. The file cannot include :lisp constructs.

batchload returns the path of filename, as a string. batchload evaluates its argument.

13.4 Functions and Variables for TeX Output

Note that the built-in TeX output functionality of wxMaxima makes no use of the functions described here but uses its own implementation instead.

Function: tex
    tex (expr)
    tex (expr, destination)
    tex (expr, false)
    tex (label)
    tex (label, destination)
    tex (label, false)

Prints a representation of an expression suitable for the TeX document preparation system. The result is a fragment of a document, which can be copied into a larger document but not processed by itself.

tex (expr) prints a TeX representation of expr on the console.

tex (label) prints a TeX representation of the expression named by label and assigns it an equation label (to be displayed to the left of the expression). The TeX equation label is the same as the Maxima label.

destination may be an output stream or file name. When destination is a file name, tex appends its output to the file. The functions openw and opena create output streams.

tex (expr, false) and tex (label, false) return their TeX output as a string.

tex evaluates its first argument after testing it to see if it is a label. Quote-quote '' forces evaluation of the argument, thereby defeating the test and preventing the label.

13.5 Functions and Variables for Fortran Output

Option variable: fortindent

Default value: 0

fortindent controls the left margin indentation of expressions printed out by the fortran command. 0 gives normal printout (i.e., 6 spaces), and positive values will causes the expressions to be printed farther to the right.

Category: Translation and compilation

Function: fortran (expr)

Prints expr as a Fortran statement. The output line is indented with spaces. If the line is too long, fortran prints continuation lines. fortran prints the exponentiation operator ^ as **, and prints a complex number a + b %i in the form (a,b).

expr may be an equation. If so, fortran prints an assignment statement, assigning the right-hand side of the equation to the left-hand side. In particular, if the right-hand side of expr is the name of a matrix, then fortran prints an assignment statement for each element of the matrix.

If expr is not something recognized by fortran, the expression is printed in grind format without complaint. fortran does not know about lists, arrays, or functions.

fortindent controls the left margin of the printed lines. 0 is the normal margin (i.e., indented 6 spaces). Increasing fortindent causes expressions to be printed further to the right.

When fortspaces is true, fortran fills out each printed line with spaces to 80 columns.

fortran evaluates its arguments; quoting an argument defeats evaluation. fortran always returns done.

See also the function f90 for printing one or more expressions as a Fortran 90 program.

Examples:

(%i1) expr: (a + b)^12$
(%i2) fortran (expr);
      (b+a)**12                                                                 
(%o2)                         done
(%i3) fortran ('x=expr);
      x = (b+a)**12                                                             
(%o3)                         done
(%i4) fortran ('x=expand (expr));
      x = b**12+12*a*b**11+66*a**2*b**10+220*a**3*b**9+495*a**4*b**8+792
     1   *a**5*b**7+924*a**6*b**6+792*a**7*b**5+495*a**8*b**4+220*a**9*b
     2   **3+66*a**10*b**2+12*a**11*b+a**12
(%o4)                         done
(%i5) fortran ('x=7+5*%i);
      x = (7,5)                                                                 
(%o5)                         done
(%i6) fortran ('x=[1,2,3,4]);
      x = [1,2,3,4]                                                             
(%o6)                         done
(%i7) f(x) := x^2$
(%i8) fortran (f);
      f                                                                         
(%o8)                         done

Category: Translation and compilation

Option variable: fortspaces

Default value: false

When fortspaces is true, fortran fills out each printed line with spaces to 80 columns.

Category: Translation and compilation

14 Polynomials

14.1 Introduction to Polynomials

Polynomials are stored in Maxima either in General Form or as Canonical Rational Expressions (CRE) form. The latter is a standard form, and is used internally by operations such as factor, ratsimp, and so on.

Canonical Rational Expressions constitute a kind of representation which is especially suitable for expanded polynomials and rational functions (as well as for partially factored polynomials and rational functions when ratfac is set to true). In this CRE form an ordering of variables (from most to least main) is assumed for each expression.

Polynomials are represented recursively by a list consisting of the main variable followed by a series of pairs of expressions, one for each term of the polynomial. The first member of each pair is the exponent of the main variable in that term and the second member is the coefficient of that term which could be a number or a polynomial in another variable again represented in this form. Thus the principal part of the CRE form of 3*x^2-1 is (X 2 3 0 -1) and that of 2*x*y+x-3 is (Y 1 (X 1 2) 0 (X 1 1 0 -3)) assuming y is the main variable, and is (X 1 (Y 1 2 0 1) 0 -3) assuming x is the main variable. "Main"-ness is usually determined by reverse alphabetical order.

The "variables" of a CRE expression needn’t be atomic. In fact any subexpression whose main operator is not +, -, *, / or ^ with integer power will be considered a "variable" of the expression (in CRE form) in which it occurs. For example the CRE variables of the expression x+sin(x+1)+2*sqrt(x)+1 are x, sqrt(X), and sin(x+1). If the user does not specify an ordering of variables by using the ratvars function Maxima will choose an alphabetic one.

In general, CRE’s represent rational expressions, that is, ratios of polynomials, where the numerator and denominator have no common factors, and the denominator is positive. The internal form is essentially a pair of polynomials (the numerator and denominator) preceded by the variable ordering list. If an expression to be displayed is in CRE form or if it contains any subexpressions in CRE form, the symbol /R/ will follow the line label.

See the rat function for converting an expression to CRE form.

An extended CRE form is used for the representation of Taylor series. The notion of a rational expression is extended so that the exponents of the variables can be positive or negative rational numbers rather than just positive integers and the coefficients can themselves be rational expressions as described above rather than just polynomials. These are represented internally by a recursive polynomial form which is similar to and is a generalization of CRE form, but carries additional information such as the degree of truncation. As with CRE form, the symbol /T/ follows the line label of such expressions.

Category: Polynomials · Category: Rational expressions

14.2 Functions and Variables for Polynomials

Option variable: algebraic

Default value: false

algebraic must be set to true in order for the simplification of algebraic integers to take effect.

Category: Bessel functions · Category: Airy functions · Category: Special functions

Option variable: berlefact

Default value: true

When berlefact is false then the Kronecker factoring algorithm will be used otherwise the Berlekamp algorithm, which is the default, will be used.

Category: Polynomials

Function: bezout (p1, p2, x)

an alternative to the resultant command. It returns a matrix. determinant of this matrix is the desired resultant.

Examples:

(%i1) bezout(a*x+b, c*x^2+d, x);
                         [ b c  - a d ]
(%o1)                    [            ]
                         [  a     b   ]
(%i2) determinant(%);
                            2      2
(%o2)                      a  d + b  c
(%i3) resultant(a*x+b, c*x^2+d, x);
                            2      2
(%o3)                      a  d + b  c

Category: Polynomials

Function: bothcoef (expr, x)

Returns a list whose first member is the coefficient of x in expr (as found by ratcoef if expr is in CRE form otherwise by coeff) and whose second member is the remaining part of expr. That is, [A, B] where expr = A*x + B.

Example:

(%i1) islinear (expr, x) := block ([c],
        c: bothcoef (rat (expr, x), x),
        is (freeof (x, c) and c[1] # 0))$
(%i2) islinear ((r^2 - (x - r)^2)/x, x);
(%o2)                         true

Category: Polynomials

Function: coeff
coeff (expr, x, n)
coeff (expr, x)

Returns the coefficient of x^n in expr, where expr is a polynomial or a monomial term in x. Other than ratcoef coeff is a strictly syntactical operation and will only find literal instances of x^n in the internal representation of expr.

coeff(expr, x^n) is equivalent to coeff(expr, x, n). coeff(expr, x, 0) returns the remainder of expr which is free of x. If omitted, n is assumed to be 1.

x may be a simple variable or a subscripted variable, or a subexpression of expr which comprises an operator and all of its arguments.

It may be possible to compute coefficients of expressions which are equivalent to expr by applying expand or factor. coeff itself does not apply expand or factor or any other function.

coeff distributes over lists, matrices, and equations.

15 Special Functions

15.1 Introduction to Special Functions

Special function notation follows:

bessel_j (index, expr)         Bessel function, 1st kind
bessel_y (index, expr)         Bessel function, 2nd kind
bessel_i (index, expr)         Modified Bessel function, 1st kind
bessel_k (index, expr)         Modified Bessel function, 2nd kind

hankel_1 (v,z)                 Hankel function of the 1st kind
hankel_2 (v,z)                 Hankel function of the 2nd kind
struve_h (v,z)                 Struve H function
struve_l (v,z)                 Struve L function

assoc_legendre_p[v,u] (z)      Legendre function of degree v and order u 
assoc_legendre_q[v,u] (z)      Legendre function, 2nd kind

%f[p,q] ([], [], expr)         Generalized Hypergeometric function
gamma (z)                      Gamma function
gamma_incomplete_lower (a,z)   Lower incomplete gamma function
gamma_incomplete (a,z)         Tail of incomplete gamma function
hypergeometric (l1, l2, z)     Hypergeometric function
slommel
%m[u,k] (z)                    Whittaker function, 1st kind
%w[u,k] (z)                    Whittaker function, 2nd kind
erfc (z)                       Complement of the erf function

expintegral_e (v,z)            Exponential integral E
expintegral_e1 (z)             Exponential integral E1
expintegral_ei (z)             Exponential integral Ei
expintegral_li (z)             Logarithmic integral Li
expintegral_si (z)             Exponential integral Si
expintegral_ci (z)             Exponential integral Ci
expintegral_shi (z)            Exponential integral Shi
expintegral_chi (z)            Exponential integral Chi

kelliptic (z)                  Complete elliptic integral of the first 
                               kind (K)
parabolic_cylinder_d (v,z)     Parabolic cylinder D function

15.2 Bessel Functions

Function: bessel_j (v, z)

The Bessel function of the first kind of order v and argument z.

bessel_j is defined as

                inf
                ====       k  - v - 2 k  v + 2 k
                \     (- 1)  2          z
                 >    --------------------------
                /        k! gamma(v + k + 1)
                ====
                k = 0

although the infinite series is not used for computations.

Category: Bessel functions · Category: Special functions

Function: bessel_y (v, z)

The Bessel function of the second kind of order v and argument z.

bessel_y is defined as

              cos(%pi v) bessel_j(v, z) - bessel_j(-v, z)
              -------------------------------------------
                             sin(%pi v)

when v is not an integer. When v is an integer n, the limit as v approaches n is taken.

Category: Bessel functions · Category: Special functions

Function: bessel_i (v, z)

The modified Bessel function of the first kind of order v and argument z.

bessel_i is defined as

                    inf
                    ====   - v - 2 k  v + 2 k
                    \     2          z
                     >    -------------------
                    /     k! gamma(v + k + 1)
                    ====
                    k = 0

although the infinite series is not used for computations.

Category: Bessel functions · Category: Special functions

Function: bessel_k (v, z)

The modified Bessel function of the second kind of order v and argument z.

bessel_k is defined as

           %pi csc(%pi v) (bessel_i(-v, z) - bessel_i(v, z))
           -------------------------------------------------
                                  2

when v is not an integer. If v is an integer n, then the limit as v approaches n is taken.

Category: Bessel functions · Category: Special functions

Function: hankel_1 (v, z)

The Hankel function of the first kind of order v and argument z (A&S 9.1.3). hankel_1 is defined as

   bessel_j(v,z) + %i * bessel_y(v,z)

Maxima evaluates hankel_1 numerically for a complex order v and complex argument z in float precision. The numerical evaluation in bigfloat precision is not supported.

When besselexpand is true, hankel_1 is expanded in terms of elementary functions when the order v is half of an odd integer. See besselexpand.

Maxima knows the derivative of hankel_1 wrt the argument z.

Examples:

Numerical evaluation:

(%i1) hankel_1(1,0.5);
(%o1)        0.24226845767487 - 1.471472392670243 %i

(%i2) hankel_1(1,0.5+%i);
(%o2)       - 0.25582879948621 %i - 0.23957560188301

Expansion of hankel_1 when besselexpand is true:

(%i1) hankel_1(1/2,z),besselexpand:true;
               sqrt(2) sin(z) - sqrt(2) %i cos(z)
(%o1)          ----------------------------------
                       sqrt(%pi) sqrt(z)

Derivative of hankel_1 wrt the argument z. The derivative wrt the order v is not supported. Maxima returns a noun form:

(%i1) diff(hankel_1(v,z),z);
             hankel_1(v - 1, z) - hankel_1(v + 1, z)
(%o1)        ---------------------------------------
                                2

(%i2) diff(hankel_1(v,z),v);
                       d
(%o2)                  -- (hankel_1(v, z))
                       dv

Category: Bessel functions · Category: Special functions

Function: hankel_2 (v, z)

The Hankel function of the second kind of order v and argument z (A&S 9.1.4). hankel_2 is defined as

   bessel_j(v,z) - %i * bessel_y(v,z)

Maxima evaluates hankel_2 numerically for a complex order v and complex argument z in float precision. The numerical evaluation in bigfloat precision is not supported.

When besselexpand is true, hankel_2 is expanded in terms of elementary functions when the order v is half of an odd integer. See besselexpand.

Maxima knows the derivative of hankel_2 wrt the argument z.

For examples see hankel_1.

Category: Bessel functions · Category: Special functions

Option variable: besselexpand

Default value: false

Controls expansion of the Bessel functions when the order is half of an odd integer. In this case, the Bessel functions can be expanded in terms of other elementary functions. When besselexpand is true, the Bessel function is expanded.

(%i1) besselexpand: false$
(%i2) bessel_j (3/2, z);
                                    3
(%o2)                      bessel_j(-, z)
                                    2
(%i3) besselexpand: true$
(%i4) bessel_j (3/2, z);
                                        sin(z)   cos(z)
                       sqrt(2) sqrt(z) (------ - ------)
                                           2       z
                                          z
(%o4)                  ---------------------------------
                                   sqrt(%pi)

Category: Bessel functions · Category: Simplification flags and variables · Category: Special functions

Function: scaled_bessel_i (v, z)

The scaled modified Bessel function of the first kind of order v and argument z. That is, scaled_bessel_i(v,z) = exp(-abs(z))*bessel_i(v, z). This function is particularly useful for calculating bessel_i for large z, which is large. However, maxima does not otherwise know much about this function. For symbolic work, it is probably preferable to work with the expression exp(-abs(z))*bessel_i(v, z).

Category: Bessel functions

Function: scaled_bessel_i0 (z)

Identical to scaled_bessel_i(0,z).

Category: Bessel functions · Category: Special functions

Function: scaled_bessel_i1 (z)

Identical to scaled_bessel_i(1,z).

· Category: Bessel functions · Category: Special functions

Function: %s [u,v] (z)

Lommel’s little s[u,v](z) function. Probably Gradshteyn & Ryzhik 8.570.1.

· Category: Bessel functions · Category: Special functions

15.3 Airy Functions

The Airy functions Ai(x) and Bi(x) are defined in Abramowitz and Stegun, Handbook of Mathematical Functions, Section 10.4.

y = Ai(x) and y = Bi(x) are two linearly independent solutions of the Airy differential equation diff (y(x), x, 2) - x y(x) = 0.

If the argument x is a real or complex floating point number, the numerical value of the function is returned.

Function: airy_ai (x)

The Airy function Ai(x). (A&S 10.4.2)

The derivative diff (airy_ai(x), x) is airy_dai(x).

See also airy_bi, airy_dai, airy_dbi.

Category: Airy functions · Category: Special functions

Function: airy_dai (x)

The derivative of the Airy function Ai airy_ai(x).

See airy_ai.

Category: Airy functions · Category: Special functions

Function: airy_bi (x)

The Airy function Bi(x). (A&S 10.4.3)

The derivative diff (airy_bi(x), x) is airy_dbi(x).

See airy_ai, airy_dbi.

Category: Airy functions · Category: Special functions

Function: airy_dbi (x)

The derivative of the Airy Bi function airy_bi(x).

See airy_ai and airy_bi.

Category: Airy functions · Category: Special functions

15.4 Gamma and factorial Functions

The gamma function and the related beta, psi and incomplete gamma functions are defined in Abramowitz and Stegun, Handbook of Mathematical Functions, Chapter 6.

Function: bffac (expr, n)

Bigfloat version of the factorial (shifted gamma) function. The second argument is how many digits to retain and return, it’s a good idea to request a couple of extra.

Category: Gamma and factorial functions · Category: Numerical evaluation

Function: bfpsi (n, z, fpprec)

Function: bfpsi0 (z, fpprec)

bfpsi is the polygamma function of real argument z and integer order n. bfpsi0 is the digamma function. bfpsi0 (z, fpprec) is equivalent to bfpsi (0, z, fpprec).

These functions return bigfloat values. fpprec is the bigfloat precision of the return value.

Category: Gamma and factorial functions · Category: Numerical evaluation

Function: cbffac (z, fpprec)

Complex bigfloat factorial.

load ("bffac") loads this function.

Category: Gamma and factorial functions · Category: Complex variables · Category: Numerical evaluation

Function: gamma (z)

The basic definition of the gamma function (A&S 6.1.1) is

                         inf
                        /
                        [     z - 1   - t
             gamma(z) = I    t      %e    dt
                        ]
                        /
                         0

Maxima simplifies gamma for positive integer and positive and negative rational numbers. For half integral values the result is a rational number times sqrt(%pi). The simplification for integer values is controlled by factlim. For integers greater than factlim the numerical result of the factorial function, which is used to calculate gamma, will overflow. The simplification for rational numbers is controlled by gammalim to avoid internal overflow. See factlim and gammalim.

For negative integers gamma is not defined.

Maxima can evalute gamma numerically for real and complex values in float and bigfloat precision.

gamma has mirror symmetry.

When gamma_expand is true, Maxima expands gamma for arguments z+n and z-n where n is an integer.

Maxima knows the derivate of gamma.

Examples:

Simplification for integer, half integral, and rational numbers:

(%i1) map('gamma,[1,2,3,4,5,6,7,8,9]);
(%o1)        [1, 1, 2, 6, 24, 120, 720, 5040, 40320]
(%i2) map('gamma,[1/2,3/2,5/2,7/2]);
                    sqrt(%pi)  3 sqrt(%pi)  15 sqrt(%pi)
(%o2)   [sqrt(%pi), ---------, -----------, ------------]
                        2           4            8
(%i3) map('gamma,[2/3,5/3,7/3]);
                                  2           1
                          2 gamma(-)  4 gamma(-)
                      2           3           3
(%o3)          [gamma(-), ----------, ----------]
                      3       3           9

Numerical evaluation for real and complex values:

(%i4) map('gamma,[2.5,2.5b0]);
(%o4)     [1.329340388179137, 1.3293403881791370205b0]
(%i5) map('gamma,[1.0+%i,1.0b0+%i]);
(%o5) [0.498015668118356 - .1549498283018107 %i, 
          4.9801566811835604272b-1 - 1.5494982830181068513b-1 %i]

gamma has mirror symmetry:

(%i6) declare(z,complex)$
(%i7) conjugate(gamma(z));
(%o7)                  gamma(conjugate(z))

Maxima expands gamma(z+n) and gamma(z-n), when gamma_expand is true:

(%i8) gamma_expand:true$

(%i9) [gamma(z+1),gamma(z-1),gamma(z+2)/gamma(z+1)];
                               gamma(z)
(%o9)             [z gamma(z), --------, z + 1]
                                z - 1

The deriviative of gamma:

(%i10) diff(gamma(z),z);
(%o10)                  psi (z) gamma(z)
                           0

15.5 Exponential Integrals

The Exponential Integral and related funtions are defined in Abramowitz and Stegun, Handbook of Mathematical Functions, Chapter 5

Function: expintegral_e1 (z)

The Exponential Integral E1(z) (A&S 5.1.1) defined as

Category: Exponential Integrals · Category: Special functions

Function: expintegral_ei (z)

The Exponential Integral Ei(z) (A&S 5.1.2)

Category: Exponential Integrals · Category: Special functions

Function: expintegral_li (z)

The Exponential Integral Li(z) (A&S 5.1.3)

Category: Exponential Integrals · Category: Special functions

Function: expintegral_e (n,z)

The Exponential Integral En(z) (A&S 5.1.4) defined as

Category: Exponential Integrals · Category: Special functions

Function: expintegral_si (z)

The Exponential Integral Si(z) (A&S 5.2.1) defined as

Category: Exponential Integrals · Category: Special functions

Function: expintegral_ci (z)

The Exponential Integral Ci(z) (A&S 5.2.2) defined as

Category: Exponential Integrals · Category: Special functions

Function: expintegral_shi (z)

The Exponential Integral Shi(z) (A&S 5.2.3) defined as

Category: Exponential Integrals · Category: Special functions

Function: expintegral_chi (z)

The Exponential Integral Chi(z) (A&S 5.2.4) defined as

Category: Exponential Integrals · Category: Special functions

Option variable: expintrep

Default value: false

Change the representation of one of the exponential integrals, expintegral_e(m, z), expintegral_e1, or expintegral_ei to an equivalent form if possible.

Possible values for expintrep are false, gamma_incomplete, expintegral_e1, expintegral_ei, expintegral_li, expintegral_trig, or expintegral_hyp.

false means that the representation is not changed. Other values indicate the representation is to be changed to use the function specified where expintegral_trig means expintegral_si, expintegral_ci, and expintegral_hyp means expintegral_shi or expintegral_chi.

Category: Exponential Integrals

Option variable: expintexpand

Default value: false

Expand the Exponential Integral E[n](z) for half integral values in terms of Erfc or Erf and for positive integers in terms of Ei

· Category: Exponential Integrals

15.6 Error Function

The Error function and related funtions are defined in Abramowitz and Stegun, Handbook of Mathematical Functions, Chapter 7

Function: erf (z)

The Error Function erf(z) (A&S 7.1.1)

15.7 Struve Functions

The Struve functions are defined in Abramowitz and Stegun, Handbook of Mathematical Functions, Chapter 12.

Function: struve_h (v, z)

The Struve Function H of order v and argument z. (A&S 12.1.1)

Category: Special functions

Function: struve_l (v, z)

The Modified Struve Function L of order v and argument z. (A&S 12.2.1)

Category: Special functions

15.8 Hypergeometric Functions

The Hypergeometric Functions are defined in Abramowitz and Stegun, Handbook of Mathematical Functions, Chapters 13 and 15.

Maxima has very limited knowledge of these functions. They can be returned from function hgfred.

Function: %m [k,u] (z)

Whittaker M function M[k,u](z) = exp(-z/2)*z^(1/2+u)*M(1/2+u-k,1+2*u,z). (A&S 13.1.32)

· Category: Special functions

Function: %w [k,u] (z)

Whittaker W function. (A&S 13.1.33)

· Category: Special functions

Function: %f [p,q] ([a],[b],z)

The pFq(a1,a2,..ap;b1,b2,..bq;z) hypergeometric function, where a a list of length p and b a list of length q.

· Category: Bessel functions · Category: Special functions

Function: hypergeometric ([a1, ..., ap],[b1, ... ,bq], x)

The hypergeometric function. Unlike Maxima’s %f hypergeometric function, the function hypergeometric is a simplifying function; also, hypergeometric supports complex double and big floating point evaluation. For the Gauss hypergeometric function, that is p = 2 and q = 1, floating point evaluation outside the unit circle is supported, but in general, it is not supported.

When the option variable expand_hypergeometric is true (default is false) and one of the arguments a1 through ap is a negative integer (a polynomial case), hypergeometric returns an expanded polynomial.

Examples:

(%i1)  hypergeometric([],[],x);
(%o1) %e^x

Polynomial cases automatically expand when expand_hypergeometric is true:

(%i2) hypergeometric([-3],[7],x);
(%o2) hypergeometric([-3],[7],x)

(%i3) hypergeometric([-3],[7],x), expand_hypergeometric : true;
(%o3) -x^3/504+3*x^2/56-3*x/7+1

Both double float and big float evaluation is supported:

(%i4) hypergeometric([5.1],[7.1 + %i],0.42);
(%o4)       1.346250786375334 - 0.0559061414208204 %i
(%i5) hypergeometric([5,6],[8], 5.7 - %i);
(%o5)     .007375824009774946 - .001049813688578674 %i
(%i6) hypergeometric([5,6],[8], 5.7b0 - %i), fpprec : 30;
(%o6) 7.37582400977494674506442010824b-3
                          - 1.04981368857867315858055393376b-3 %i

15.9 Parabolic Cylinder Functions

The Parabolic Cylinder Functions are defined in Abramowitz and Stegun, Handbook of Mathematical Functions, Chapter 19.

Maxima has very limited knowledge of these functions. They can be returned from function hgfred.

Function: parabolic_cylinder_d (v, z)

The parabolic cylinder function parabolic_cylinder_d(v,z). (A&S 19.3.1)

· Category: Special functions

15.10 Functions and Variables for Special Functions

Function: specint (exp(- s*t) * expr, t)

Compute the Laplace transform of expr with respect to the variable t. The integrand expr may contain special functions. The parameter s maybe be named something else; it is determined automatically, as the examples below show where p is used in some places.

The following special functions are handled by specint: incomplete gamma function, error functions (but not the error function erfi, it is easy to transform erfi e.g. to the error function erf), exponential integrals, bessel functions (including products of bessel functions), hankel functions, hermite and the laguerre polynomials.

Furthermore, specint can handle the hypergeometric function %f[p,q]([],[],z), the whittaker function of the first kind %m[u,k](z) and of the second kind %w[u,k](z).

The result may be in terms of special functions and can include unsimplified hypergeometric functions.

When laplace fails to find a Laplace transform, specint is called. Because laplace knows more general rules for Laplace transforms, it is preferable to use laplace and not specint.

demo("hypgeo") displays several examples of Laplace transforms computed by specint.

Examples:

(%i1) assume (p > 0, a > 0)$

(%i2) specint (t^(1/2) * exp(-a*t/4) * exp(-p*t), t);
                           sqrt(%pi)
(%o2)                     ------------
                                 a 3/2
                          2 (p + -)
                                 4

(%i3) specint (t^(1/2) * bessel_j(1, 2 * a^(1/2) * t^(1/2))
              * exp(-p*t), t);
                                   - a/p
                         sqrt(a) %e
(%o3)                    ---------------
                                2
                               p

Examples for exponential integrals:

(%i4) assume(s>0,a>0,s-a>0)$
(%i5) ratsimp(specint(%e^(a*t)
                      *(log(a)+expintegral_e1(a*t))*%e^(-s*t),t));
                             log(s)
(%o5)                        ------
                             s - a
(%i6) logarc:true$

(%i7) gamma_expand:true$

radcan(specint((cos(t)*expintegral_si(t)
                     -sin(t)*expintegral_ci(t))*%e^(-s*t),t));
                             log(s)
(%o8)                        ------
                              2
                             s  + 1
ratsimp(specint((2*t*log(a)+2/a*sin(a*t)
                      -2*t*expintegral_ci(a*t))*%e^(-s*t),t));
                               2    2
                          log(s  + a )
(%o9)                     ------------
                                2
                               s

Results when using the expansion of gamma_incomplete and when changing the representation to expintegral_e1:

(%i10) assume(s>0)$
(%i11) specint(1/sqrt(%pi*t)*unit_step(t-k)*%e^(-s*t),t);
                                            1
                            gamma_incomplete(-, k s)
                                            2
(%o11)                      ------------------------
                               sqrt(%pi) sqrt(s)

(%i12) gamma_expand:true$
(%i13) specint(1/sqrt(%pi*t)*unit_step(t-k)*%e^(-s*t),t);
                              erfc(sqrt(k) sqrt(s))
(%o13)                        ---------------------
                                     sqrt(s)

(%i14) expintrep:expintegral_e1$
(%i15) ratsimp(specint(1/(t+a)^2*%e^(-s*t),t));
                              a s
                        a s %e    expintegral_e1(a s) - 1
(%o15)                - ---------------------------------
                                        a

Category: Laplace transform

Function: hypergeometric_simp (e)

hypergeometric_simp simplifies hypergeometric functions by applying hgfred to the arguments of any hypergeometric functions in the expression e.

Only instances of hypergeometric are affected; any %f, %w, and %m in the expression e are not affected. Any unsimplified hypergeometric functions are returned unchanged (instead of changing to %f as hgfred would).

load(hypergeometric); loads this function.

16 Elliptic Functions

16.1 Introduction to Elliptic Functions and Integrals

Maxima includes support for Jacobian elliptic functions and for complete and incomplete elliptic integrals. This includes symbolic manipulation of these functions and numerical evaluation as well. Definitions of these functions and many of their properties can by found in Abramowitz and Stegun, Chapter 16–17. As much as possible, we use the definitions and relationships given there.

In particular, all elliptic functions and integrals use the parameter m instead of the modulus k or the modular angle \alpha. This is one area where we differ from Abramowitz and Stegun who use the modular angle for the elliptic functions. The following relationships are true:

The elliptic functions and integrals are primarily intended to support symbolic computation. Therefore, most of derivatives of the functions and integrals are known. However, if floating-point values are given, a floating-point result is returned.

Support for most of the other properties of elliptic functions and integrals other than derivatives has not yet been written.

Some examples of elliptic functions:

(%i1) jacobi_sn (u, m);
(%o1)                    jacobi_sn(u, m)
(%i2) jacobi_sn (u, 1);
(%o2)                        tanh(u)
(%i3) jacobi_sn (u, 0);
(%o3)                        sin(u)
(%i4) diff (jacobi_sn (u, m), u);
(%o4)            jacobi_cn(u, m) jacobi_dn(u, m)
(%i5) diff (jacobi_sn (u, m), m);
(%o5) jacobi_cn(u, m) jacobi_dn(u, m)

      elliptic_e(asin(jacobi_sn(u, m)), m)
 (u - ------------------------------------)/(2 m)
                     1 - m

            2
   jacobi_cn (u, m) jacobi_sn(u, m)
 + --------------------------------
              2 (1 - m)

Some examples of elliptic integrals:

(%i1) elliptic_f (phi, m);
(%o1)                  elliptic_f(phi, m)
(%i2) elliptic_f (phi, 0);
(%o2)                          phi
(%i3) elliptic_f (phi, 1);
                               phi   %pi
(%o3)                  log(tan(--- + ---))
                                2     4
(%i4) elliptic_e (phi, 1);
(%o4)                       sin(phi)
(%i5) elliptic_e (phi, 0);
(%o5)                          phi
(%i6) elliptic_kc (1/2);
                                     1
(%o6)                    elliptic_kc(-)
                                     2
(%i7) makegamma (%);
                                 2 1
                            gamma (-)
                                   4
(%o7)                      -----------
                           4 sqrt(%pi)
(%i8) diff (elliptic_f (phi, m), phi);
                                1
(%o8)                 ---------------------
                                    2
                      sqrt(1 - m sin (phi))
(%i9) diff (elliptic_f (phi, m), m);
       elliptic_e(phi, m) - (1 - m) elliptic_f(phi, m)
(%o9) (-----------------------------------------------
                              m

                                 cos(phi) sin(phi)
                             - ---------------------)/(2 (1 - m))
                                             2
                               sqrt(1 - m sin (phi))

Support for elliptic functions and integrals was written by Raymond Toy. It is placed under the terms of the General Public License (GPL) that governs the distribution of Maxima.

16.2 Functions and Variables for Elliptic Functions

Function: jacobi_sn (u, m)

The Jacobian elliptic function sn(u,m).

Function: jacobi_cn (u, m)

The Jacobian elliptic function cn(u,m).

Function: jacobi_dn (u, m)

The Jacobian elliptic function dn(u,m).

Function: jacobi_ns (u, m)

The Jacobian elliptic function ns(u,m) = 1/sn(u,m).

Function: jacobi_sc (u, m)

The Jacobian elliptic function sc(u,m) = sn(u,m)/cn(u,m).

Function: jacobi_sd (u, m)

The Jacobian elliptic function sd(u,m) = sn(u,m)/dn(u,m).

Function: jacobi_nc (u, m)

The Jacobian elliptic function nc(u,m) = 1/cn(u,m).

Function: jacobi_cs (u, m)

The Jacobian elliptic function cs(u,m) = cn(u,m)/sn(u,m).

Function: jacobi_cd (u, m)

The Jacobian elliptic function cd(u,m) = cn(u,m)/dn(u,m).

Function: jacobi_nd (u, m)

The Jacobian elliptic function nd(u,m) = 1/dn(u,m).

Function: jacobi_ds (u, m)

The Jacobian elliptic function ds(u,m) = dn(u,m)/sn(u,m).

Function: jacobi_dc (u, m)

The Jacobian elliptic function dc(u,m) = dn(u,m)/cn(u,m).

Function: inverse_jacobi_sn (u, m)

The inverse of the Jacobian elliptic function sn(u,m).

Function: inverse_jacobi_cn (u, m)

The inverse of the Jacobian elliptic function cn(u,m).

Function: inverse_jacobi_dn (u, m)

The inverse of the Jacobian elliptic function dn(u,m).

Function: inverse_jacobi_ns (u, m)

The inverse of the Jacobian elliptic function ns(u,m).

Function: inverse_jacobi_sc (u, m)

The inverse of the Jacobian elliptic function sc(u,m).

Function: inverse_jacobi_sd (u, m)

The inverse of the Jacobian elliptic function sd(u,m).

Function: inverse_jacobi_nc (u, m)

The inverse of the Jacobian elliptic function nc(u,m).

Function: inverse_jacobi_cs (u, m)

The inverse of the Jacobian elliptic function cs(u,m).

Function: inverse_jacobi_cd (u, m)

The inverse of the Jacobian elliptic function cd(u,m).

Function: inverse_jacobi_nd (u, m)

The inverse of the Jacobian elliptic function nd(u,m).

Function: inverse_jacobi_ds (u, m)

The inverse of the Jacobian elliptic function ds(u,m).

Function: inverse_jacobi_dc (u, m)

The inverse of the Jacobian elliptic function dc(u,m).

16.3 Functions and Variables for Elliptic Integrals

Function: elliptic_f (phi, m)

The incomplete elliptic integral of the first kind, defined as

integrate(1/sqrt(1 - m*sin(x)^2), x, 0, phi)

17 Limits

17.1 Functions and Variables for Limits

Option variable: lhospitallim

Default value: 4

lhospitallim is the maximum number of times L’Hospital’s rule is used in limit. This prevents infinite looping in cases like limit (cot(x)/csc(x), x, 0).

Function: limit
    limit (expr, x, val, dir)
    limit (expr, x, val)
    limit (expr)

Computes the limit of expr as the real variable x approaches the value val from the direction dir. dir may have the value plus for a limit from above, minus for a limit from below, or may be omitted (implying a two-sided limit is to be computed).

limit uses the following special symbols: inf (positive infinity) and minf (negative infinity). On output it may also use und (undefined), ind (indefinite but bounded) and infinity (complex infinity).

infinity (complex infinity) is returned when the limit of the absolute value of the expression is positive infinity, but the limit of the expression itself is not positive infinity or negative infinity. This includes cases where the limit of the complex argument is a constant, as in limit(log(x), x, minf), cases where the complex argument oscillates, as in limit((-2)^x, x, inf), and cases where the complex argument is different for either side of a two-sided limit, as in limit(1/x, x, 0) and limit(log(x), x, 0).

lhospitallim is the maximum number of times L’Hospital’s rule is used in limit. This prevents infinite looping in cases like limit (cot(x)/csc(x), x, 0).

tlimswitch when true will allow the limit command to use Taylor series expansion when necessary.

limsubst prevents limit from attempting substitutions on unknown forms. This is to avoid bugs like limit (f(n)/f(n+1), n, inf) giving 1. Setting limsubst to true will allow such substitutions.

limit with one argument is often called upon to simplify constant expressions, for example, limit (inf-1).

example (limit) displays some examples.

For the method see Wang, P., "Evaluation of Definite Integrals by Symbolic Manipulation", Ph.D. thesis, MAC TR-92, October 1971.

Option variable: limsubst

Default value: false

prevents limit from attempting substitutions on unknown forms. This is to avoid bugs like limit (f(n)/f(n+1), n, inf) giving 1. Setting limsubst to true will allow such substitutions.

Function: tlimit
    tlimit (expr, x, val, dir)
    tlimit (expr, x, val)
    tlimit (expr)

Take the limit of the Taylor series expansion of expr in x at val from direction dir.

Option variable: tlimswitch

Default value: true

When tlimswitch is true, the limit command will use a Taylor series expansion if the limit of the input expression cannot be computed directly. This allows evaluation of limits such as limit(x/(x-1)-1/log(x),x,1,plus). When tlimswitch is false and the limit of input expression cannot be computed directly, limit will return an unevaluated limit expression.

18 Differentiation

18.1 Functions and Variables for Differentiation

Function: antid (expr, x, u(x))

Returns a two-element list, such that an antiderivative of expr with respect to x can be constructed from the list. The expression expr may contain an unknown function u and its derivatives.

Let L, a list of two elements, be the return value of antid. Then L[1] + 'integrate (L[2], x) is an antiderivative of expr with respect to x.

When antid succeeds entirely, the second element of the return value is zero. Otherwise, the second element is nonzero, and the first element is nonzero or zero. If antid cannot make any progress, the first element is zero and the second nonzero.

load ("antid") loads this function. The antid package also defines the functions nonzeroandfreeof and linear.

antid is related to antidiff as follows. Let L, a list of two elements, be the return value of antid. Then the return value of antidiff is equal to L[1] + 'integrate (L[2], x) where x is the variable of integration.

Examples:

(%i1) load ("antid")$
(%i2) expr: exp (z(x)) * diff (z(x), x) * y(x);
                            z(x)  d
(%o2)                y(x) %e     (-- (z(x)))
                                  dx
(%i3) a1: antid (expr, x, z(x));
                       z(x)      z(x)  d
(%o3)          [y(x) %e    , - %e     (-- (y(x)))]
                                       dx
(%i4) a2: antidiff (expr, x, z(x));
                            /
                     z(x)   [   z(x)  d
(%o4)         y(x) %e     - I %e     (-- (y(x))) dx
                            ]         dx
                            /
(%i5) a2 - (first (a1) + 'integrate (second (a1), x));
(%o5)                           0
(%i6) antid (expr, x, y(x));
                             z(x)  d
(%o6)             [0, y(x) %e     (-- (z(x)))]
                                   dx
(%i7) antidiff (expr, x, y(x));
                  /
                  [        z(x)  d
(%o7)             I y(x) %e     (-- (z(x))) dx
                  ]              dx
                  /

Function: antidiff (expr, x, u(x))

Returns an antiderivative of expr with respect to x. The expression expr may contain an unknown function u and its derivatives.

When antidiff succeeds entirely, the resulting expression is free of integral signs (that is, free of the integrate noun). Otherwise, antidiff returns an expression which is partly or entirely within an integral sign. If antidiff cannot make any progress, the return value is entirely within an integral sign.

load ("antid") loads this function. The antid package also defines the functions nonzeroandfreeof and linear.

antidiff is related to antid as follows. Let L, a list of two elements, be the return value of antid. Then the return value of antidiff is equal to L[1] + 'integrate (L[2], x) where x is the variable of integration.

Examples:

(%i1) load ("antid")$
(%i2) expr: exp (z(x)) * diff (z(x), x) * y(x);
                            z(x)  d
(%o2)                y(x) %e     (-- (z(x)))
                                  dx
(%i3) a1: antid (expr, x, z(x));
                       z(x)      z(x)  d
(%o3)          [y(x) %e    , - %e     (-- (y(x)))]
                                       dx
(%i4) a2: antidiff (expr, x, z(x));
                            /
                     z(x)   [   z(x)  d
(%o4)         y(x) %e     - I %e     (-- (y(x))) dx
                            ]         dx
                            /
(%i5) a2 - (first (a1) + 'integrate (second (a1), x));
(%o5)                           0
(%i6) antid (expr, x, y(x));
                             z(x)  d
(%o6)             [0, y(x) %e     (-- (z(x)))]
                                   dx
(%i7) antidiff (expr, x, y(x));
                  /
                  [        z(x)  d
(%o7)             I y(x) %e     (-- (z(x))) dx
                  ]              dx
                  /

Category: Evaluation · Category: Differential equations

Function: at at (expr, [eqn_1, …, eqn_n]) at (expr, eqn)

Evaluates the expression expr with the variables assuming the values as specified for them in the list of equations [eqn_1, ..., eqn_n] or the single equation eqn.

If a subexpression depends on any of the variables for which a value is specified but there is no atvalue specified and it can’t be otherwise evaluated, then a noun form of the at is returned which displays in a two-dimensional form.

at carries out multiple substitutions in parallel.

See also atvalue. For other functions which carry out substitutions, see also subst and ev.

Examples:

(%i1) atvalue (f(x,y), [x = 0, y = 1], a^2);
                                2
(%o1)                          a

(%i2) atvalue ('diff (f(x,y), x), x = 0, 1 + y);
(%o2)                        @2 + 1

(%i3) printprops (all, atvalue);
                                !
                  d             !
                 --- (f(@1, @2))!       = @2 + 1
                 d@1            !
                                !@1 = 0

                                     2
                          f(0, 1) = a

(%o3)                         done

(%i4) diff (4*f(x, y)^2 - u(x, y)^2, x);
                  d                          d
(%o4)  8 f(x, y) (-- (f(x, y))) - 2 u(x, y) (-- (u(x, y)))
                  dx                         dx

(%i5) at (%, [x = 0, y = 1]);
                                            !
                 2              d           !
(%o5)        16 a  - 2 u(0, 1) (-- (u(x, 1))!     )
                                dx          !
                                            !x = 0

Note that in the last line y is treated differently to x as y isn’t used as a differentiation variable.

The difference between subst, at and ev can be seen in the following example:

(%i1) e1:I(t)=C*diff(U(t),t)$
(%i2) e2:U(t)=L*diff(I(t),t)$

(%i3) at(e1,e2);
                               !
                      d        !
(%o3)       I(t) = C (-- (U(t))!                    )
                      dt       !          d
                               !U(t) = L (-- (I(t)))
                                          dt

(%i4) subst(e2,e1);
                            d      d
(%o4)             I(t) = C (-- (L (-- (I(t)))))
                            dt     dt

(%i5) ev(e1,e2,diff);
                                  2
                                 d
(%o5)                I(t) = C L (--- (I(t)))
                                   2
                                 dt

Property: atomgrad

atomgrad is the atomic gradient property of an expression. This property is assigned by gradef.

Category: Differential calculus

Function: atvalue
atvalue (expr, [x_1 = a_1, …, x_m = a_m], c)
atvalue (expr, x_1 = a_1, c)

Assigns the value c to expr at the point x = a. Typically boundary values are established by this mechanism.

expr is a function evaluation, f(x_1, ..., x_m), or a derivative, diff (f(x_1, ..., x_m), x_1, n_1, ..., x_n, n_m) in which the function arguments explicitly appear. n_i is the order of differentiation with respect to x_i.

The point at which the atvalue is established is given by the list of equations [x_1 = a_1, ..., x_m = a_m]. If there is a single variable x_1, the sole equation may be given without enclosing it in a list.

printprops ([f_1, f_2, ...], atvalue) displays the atvalues of the functions f_1, f_2, ... as specified by calls to atvalue. printprops (f, atvalue) displays the atvalues of one function f. printprops (all, atvalue) displays the atvalues of all functions for which atvalues are defined.

The symbols @1, @2, … represent the variables x_1, x_2, … when atvalues are displayed.

atvalue evaluates its arguments. atvalue returns c, the atvalue.

19 Integration

19.1 Introduction to Integration

Maxima has several routines for handling integration. The integrate function makes use of most of them. There is also the antid package, which handles an unspecified function (and its derivatives, of course). For numerical uses, there is a set of adaptive integrators from QUADPACK, named quad_qag, quad_qags, etc., which are described under the heading QUADPACK. Hypergeometric functions are being worked on, see specint for details. Generally speaking, Maxima only handles integrals which are integrable in terms of the "elementary functions" (rational functions, trigonometrics, logs, exponentials, radicals, etc.) and a few extensions (error function, dilogarithm). It does not handle integrals in terms of unknown functions such as g(x) and h(x).

19.2 Functions and Variables for Integration

Function: changevar (expr, f(x,y), y, x)

Makes the change of variable given by f(x,y) = 0 in all integrals occurring in expr with integration with respect to x. The new variable is y.

The change of variable can also be written f(x) = g(y).

(%i1) assume(a > 0)$

(%i2) 'integrate (%e**sqrt(a*y), y, 0, 4);
                      4
                     /
                     [    sqrt(a) sqrt(y)
(%o2)                I  %e                dy
                     ]
                     /
                      0

(%i3) changevar (%, y-z^2/a, z, y);
                      0
                     /
                     [                abs(z)
                   2 I            z %e       dz
                     ]
                     /
                      - 2 sqrt(a)
(%o3)            - ----------------------------
                                a

An expression containing a noun form, such as the instances of 'integrate above, may be evaluated by ev with the nouns flag. For example, the expression returned by changevar above may be evaluated by ev (%o3, nouns).

changevar may also be used to changes in the indices of a sum or product. However, it must be realized that when a change is made in a sum or product, this change must be a shift, i.e., i = j+ ..., not a higher degree function. E.g.,

(%i4) sum (a[i]*x^(i-2), i, 0, inf);
                         inf
                         ====
                         \         i - 2
(%o4)                     >    a  x
                         /      i
                         ====
                         i = 0

(%i5) changevar (%, i-2-n, n, i);
                        inf
                        ====
                        \               n
(%o5)                    >      a      x
                        /        n + 2
                        ====
                        n = - 2

Function: dblint (f, r, s, a, b)

A double-integral routine which was written in top-level Maxima and then translated and compiled to machine code. Use load ("dblint") to access this package. It uses the Simpson’s rule method in both the x and y directions to calculate

/b /s(x)
|  |
|  |    f(x,y) dy dx
|  |
/a /r(x)

The function f must be a translated or compiled function of two variables, and r and s must each be a translated or compiled function of one variable, while a and b must be floating point numbers. The routine has two global variables which determine the number of divisions of the x and y intervals: dblint_x and dblint_y, both of which are initially 10, and can be changed independently to other integer values (there are 2*dblint_x+1 points computed in the x direction, and 2*dblint_y+1 in the y direction). The routine subdivides the X axis and then for each value of X it first computes r(x) and s(x); then the Y axis between r(x) and s(x) is subdivided and the integral along the Y axis is performed using Simpson’s rule; then the integral along the X axis is done using Simpson’s rule with the function values being the Y-integrals. This procedure may be numerically unstable for a great variety of reasons, but is reasonably fast: avoid using it on highly oscillatory functions and functions with singularities (poles or branch points in the region). The Y integrals depend on how far apart r(x) and s(x) are, so if the distance s(x) - r(x) varies rapidly with X, there may be substantial errors arising from truncation with different step-sizes in the various Y integrals. One can increase dblint_x and dblint_y in an effort to improve the coverage of the region, at the expense of computation time. The function values are not saved, so if the function is very time-consuming, you will have to wait for re-computation if you change anything (sorry). It is required that the functions f, r, and s be either translated or compiled prior to calling dblint. This will result in orders of magnitude speed improvement over interpreted code in many cases!

demo ("dblint") executes a demonstration of dblint applied to an example problem.

Function: defint (expr, x, a, b)

Attempts to compute a definite integral. defint is called by integrate when limits of integration are specified, i.e., when integrate is called as integrate (expr, x, a, b). Thus from the user’s point of view, it is sufficient to call integrate.

defint returns a symbolic expression, either the computed integral or the noun form of the integral. See quad_qag and related functions for numerical approximation of definite integrals.

Option variable: erfflag

Default value: true

When erfflag is false, prevents risch from introducing the erf function in the answer if there were none in the integrand to begin with.

Category: Laplace transform

Function: ilt (expr, s, t)

Computes the inverse Laplace transform of expr with respect to s and parameter t. expr must be a ratio of polynomials whose denominator has only linear and quadratic factors. By using the functions laplace and ilt together with the solve or linsolve functions the user can solve a single differential or convolution integral equation or a set of them.

(%i1) 'integrate (sinh(a*x)*f(t-x), x, 0, t) + b*f(t) = t**2;
              t
             /
             [                                    2
(%o1)        I  f(t - x) sinh(a x) dx + b f(t) = t
             ]
             /
              0

(%i2) laplace (%, t, s);
                               a laplace(f(t), t, s)   2
(%o2)  b laplace(f(t), t, s) + --------------------- = --
                                       2    2           3
                                      s  - a           s

(%i3) linsolve ([%], ['laplace(f(t), t, s)]);
                                        2      2
                                     2 s  - 2 a
(%o3)     [laplace(f(t), t, s) = --------------------]
                                    5         2     3
                                 b s  + (a - a  b) s

(%i4) ilt (rhs (first (%)), s, t);
Is  a b (a b - 1)  positive, negative, or zero?

pos;
               sqrt(a b (a b - 1)) t
        2 cosh(---------------------)       2
                         b               a t
(%o4) - ----------------------------- + -------
              3  2      2               a b - 1
             a  b  - 2 a  b + a

                                                       2
                                             + ------------------
                                                3  2      2
                                               a  b  - 2 a  b + a

Option variable: intanalysis

Default value: true

When true, definite integration tries to find poles in the integrand in the interval of integration. If there are, then the integral is evaluated appropriately as a principal value integral. If intanalysis is false, this check is not performed and integration is done assuming there are no poles.

19.3 Introduction to QUADPACK

QUADPACK is a collection of functions for the numerical computation of one-dimensional definite integrals. It originated from a joint project of R. Piessens ¹, E. de Doncker ², C. Ueberhuber ³, and D. Kahaner ⁴.

The QUADPACK library included in Maxima is an automatic translation (via the program f2cl) of the Fortran source code of QUADPACK as it appears in the SLATEC Common Mathematical Library, Version 4.1 ⁵. The SLATEC library is dated July 1993, but the QUADPACK functions were written some years before. There is another version of QUADPACK at Netlib ⁶; it is not clear how that version differs from the SLATEC version.

The QUADPACK functions included in Maxima are all automatic, in the sense that these functions attempt to compute a result to a specified accuracy, requiring an unspecified number of function evaluations. Maxima’s Lisp translation of QUADPACK also includes some non-automatic functions, but they are not exposed at the Maxima level.

Further information about QUADPACK can be found in the QUADPACK book ⁷.

19.3.1 Overview

quad_qag

Integration of a general function over a finite interval. quad_qag implements a simple globally adaptive integrator using the strategy of Aind (Piessens, 1973). The caller may choose among 6 pairs of Gauss-Kronrod quadrature formulae for the rule evaluation component. The high-degree rules are suitable for strongly oscillating integrands.

quad_qags

Integration of a general function over a finite interval. quad_qags implements globally adaptive interval subdivision with extrapolation (de Doncker, 1978) by the Epsilon algorithm (Wynn, 1956).

quad_qagi

Integration of a general function over an infinite or semi-infinite interval. The interval is mapped onto a finite interval and then the same strategy as in quad_qags is applied.

quad_qawo

Integration of cos(omega x) f(x) or sin(omega x) f(x) over a finite interval, where omega is a constant. The rule evaluation component is based on the modified Clenshaw-Curtis technique. quad_qawo applies adaptive subdivision with extrapolation, similar to quad_qags.

quad_qawf

Calculates a Fourier cosine or Fourier sine transform on a semi-infinite interval. The same approach as in quad_qawo is applied on successive finite intervals, and convergence acceleration by means of the Epsilon algorithm (Wynn, 1956) is applied to the series of the integral contributions.

quad_qaws

Integration of w(x) f(x) over a finite interval [a, b], where w is a function of the form (x - a)^alpha (b - x)^beta v(x) and v(x) is 1 or log(x - a) or log(b - x) or log(x - a) log(b - x), and alpha > -1 and beta > -1.

A globally adaptive subdivision strategy is applied, with modified Clenshaw-Curtis integration on the subintervals which contain a or b.

quad_qawc

Computes the Cauchy principal value of f(x)/(x - c) over a finite interval (a, b) and specified c. The strategy is globally adaptive, and modified Clenshaw-Curtis integration is used on the subranges which contain the point x = c.

quad_qagp

Basically the same as quad_qags but points of singularity or discontinuity of the integrand must be supplied. This makes it easier for the integrator to produce a good solution.

Category: Integral calculus · Category: Numerical methods · Category: Share packages · Category: Package quadpack

19.4 Functions and Variables for QUADPACK

Function: quad_qag
quad_qag (f(x), x, a, b, key, [epsrel, epsabs, limit])
quad_qag (f, x, a, b, key, [epsrel, epsabs, limit])

quad_qag computes the integral

integrate (f(x), x, a, b)

The function to be integrated is f(x), with dependent variable x, and the function is to be integrated between the limits a and b. key is the integrator to be used and should be an integer between 1 and 6, inclusive. The value of key selects the order of the Gauss-Kronrod integration rule. High-order rules are suitable for strongly oscillating integrands.

The integrand may be specified as the name of a Maxima or Lisp function or operator, a Maxima lambda expression, or a general Maxima expression.

The numerical integration is done adaptively by subdividing the integration region into sub-intervals until the desired accuracy is achieved.

The keyword arguments are optional and may be specified in any order. They all take the form key=val. The keyword arguments are:

epsrel: Desired relative error of approximation. Default is 1d-8.
epsabs: Desired absolute error of approximation. Default is 0.
limit: Size of internal work array. limit is the maximum number of subintervals to use. Default is 200.

quad_qag returns a list of four elements:

an approximation to the integral,
the estimated absolute error of the approximation,
the number integrand evaluations,
an error code.

The error code (fourth element of the return value) can have the values:

0: if no problems were encountered;
1: if too many sub-intervals were done;
2: if excessive roundoff error is detected;
3: if extremely bad integrand behavior occurs;
6: if the input is invalid.

Examples:

(%i1) quad_qag (x^(1/2)*log(1/x), x, 0, 1, 3, 'epsrel=5d-8);
(%o1)    [.4444444444492108, 3.1700968502883E-9, 961, 0]

(%i2) integrate (x^(1/2)*log(1/x), x, 0, 1);
                                4
(%o2)                           -
                                9

Category: Numerical methods · Category: Package quadpack

Function: quad_qags
quad_qags (f(x), x, a, b, [epsrel, epsabs, limit])
quad_qags (f, x, a, b, [epsrel, epsabs, limit])

Integration of a general function over a finite interval. quad_qags implements globally adaptive interval subdivision with extrapolation (de Doncker, 1978) by the Epsilon algorithm (Wynn, 1956).

quad_qags computes the integral

integrate (f(x), x, a, b)

The function to be integrated is f(x), with dependent variable x, and the function is to be integrated between the limits a and b.

The integrand may be specified as the name of a Maxima or Lisp function or operator, a Maxima lambda expression, or a general Maxima expression.

The keyword arguments are optional and may be specified in any order. They all take the form key=val. The keyword arguments are:

epsrel: Desired relative error of approximation. Default is 1d-8.
epsabs: Desired absolute error of approximation. Default is 0.
limit: Size of internal work array. limit is the maximum number of subintervals to use. Default is 200.

quad_qags returns a list of four elements:

an approximation to the integral,
the estimated absolute error of the approximation,
the number integrand evaluations,
an error code.

The error code (fourth element of the return value) can have the values:

0: no problems were encountered;
1: too many sub-intervals were done;
2: excessive roundoff error is detected;
3: extremely bad integrand behavior occurs;
4: failed to converge
5: integral is probably divergent or slowly convergent
6: if the input is invalid.

Examples:

(%i1) quad_qags (x^(1/2)*log(1/x), x, 0, 1, 'epsrel=1d-10);
(%o1)   [.4444444444444448, 1.11022302462516E-15, 315, 0]

Note that quad_qags is more accurate and efficient than quad_qag for this integrand.

Category: Numerical methods · Category: Package quadpack

Function: quad_qagi
quad_qagi (f(x), x, a, b, [epsrel, epsabs, limit])
quad_qagi (f, x, a, b, [epsrel, epsabs, limit])

Integration of a general function over an infinite or semi-infinite interval. The interval is mapped onto a finite interval and then the same strategy as in quad_qags is applied.

quad_qagi evaluates one of the following integrals

integrate (f(x), x, a, inf)

integrate (f(x), x, minf, a)

integrate (f(x), x, minf, inf)

using the Quadpack QAGI routine. The function to be integrated is f(x), with dependent variable x, and the function is to be integrated over an infinite range.

The integrand may be specified as the name of a Maxima or Lisp function or operator, a Maxima lambda expression, or a general Maxima expression.

One of the limits of integration must be infinity. If not, then quad_qagi will just return the noun form.

The keyword arguments are optional and may be specified in any order. They all take the form key=val. The keyword arguments are:

epsrel: Desired relative error of approximation. Default is 1d-8.
epsabs: Desired absolute error of approximation. Default is 0.
limit: Size of internal work array. limit is the maximum number of subintervals to use. Default is 200.

quad_qagi returns a list of four elements:

an approximation to the integral,
the estimated absolute error of the approximation,
the number integrand evaluations,
an error code.

The error code (fourth element of the return value) can have the values:

0: no problems were encountered;
1: too many sub-intervals were done;
2: excessive roundoff error is detected;
3: extremely bad integrand behavior occurs;
4: failed to converge
5: integral is probably divergent or slowly convergent
6: if the input is invalid.

Examples:

(%i1) quad_qagi (x^2*exp(-4*x), x, 0, inf, 'epsrel=1d-8);
(%o1)        [0.03125, 2.95916102995002E-11, 105, 0]

(%i2) integrate (x^2*exp(-4*x), x, 0, inf);
                               1
(%o2)                          --
                               32

Category: Numerical methods · Category: Package quadpack

Function: quad_qawc
quad_qawc (f(x), x, c, a, b, [epsrel, epsabs, limit])
quad_qawc (f, x, c, a, b, [epsrel, epsabs, limit])

Computes the Cauchy principal value of f(x)/(x - c) over a finite interval. The strategy is globally adaptive, and modified Clenshaw-Curtis integration is used on the subranges which contain the point x = c.

quad_qawc computes the Cauchy principal value of

integrate (f(x)/(x - c), x, a, b)

using the Quadpack QAWC routine. The function to be integrated is f(x)/(x - c), with dependent variable x, and the function is to be integrated over the interval a to b.

The integrand may be specified as the name of a Maxima or Lisp function or operator, a Maxima lambda expression, or a general Maxima expression.

The keyword arguments are optional and may be specified in any order. They all take the form key=val. The keyword arguments are:

epsrel: Desired relative error of approximation. Default is 1d-8.
epsabs: Desired absolute error of approximation. Default is 0.
limit: Size of internal work array. limit is the maximum number of subintervals to use. Default is 200.

quad_qawc returns a list of four elements:

an approximation to the integral,
the estimated absolute error of the approximation,
the number integrand evaluations,
an error code.

The error code (fourth element of the return value) can have the values:

0: no problems were encountered;
1: too many sub-intervals were done;
2: excessive roundoff error is detected;
3: extremely bad integrand behavior occurs;
6: if the input is invalid.

Examples:

’epsrel=1d-7); x, 0, 5);

(%i1) quad_qawc (2^(-5)*((x-1)^2+4^(-5))^(-1), x, 2, 0, 5,
                 'epsrel=1d-7);
(%o1)    [- 3.130120337415925, 1.306830140249558E-8, 495, 0]

(%i2) integrate (2^(-alpha)*(((x-1)^2 + 4^(-alpha))*(x-2))^(-1),
      x, 0, 5);
Principal Value
                       alpha
        alpha       9 4                 9
       4      log(------------- + -------------)
                      alpha           alpha
                  64 4      + 4   64 4      + 4
(%o2) (-----------------------------------------
                        alpha
                     2 4      + 2

       3 alpha                       3 alpha
       -------                       -------
          2            alpha/2          2          alpha/2
    2 4        atan(4 4       )   2 4        atan(4       )   alpha
  - --------------------------- - -------------------------)/2
              alpha                        alpha
           2 4      + 2                 2 4      + 2

(%i3) ev (%, alpha=5, numer);
(%o3)                    - 3.130120337415917

Category: Numerical methods · Category: Package quadpack

Function: quad_qawf
quad_qawf (f(x), x, a, omega, trig, [epsabs, limit, maxp1, limlst])
quad_qawf (f, x, a, omega, trig, [epsabs, limit, maxp1, limlst])

Calculates a Fourier cosine or Fourier sine transform on a semi-infinite interval using the Quadpack QAWF function. The same approach as in quad_qawo is applied on successive finite intervals, and convergence acceleration by means of the Epsilon algorithm (Wynn, 1956) is applied to the series of the integral contributions.

quad_qawf computes the integral

integrate (f(x)*w(x), x, a, inf)

The weight function w is selected by trig:

cos: w(x) = cos (omega x)
sin: w(x) = sin (omega x)

The integrand may be specified as the name of a Maxima or Lisp function or operator, a Maxima lambda expression, or a general Maxima expression.

The keyword arguments are optional and may be specified in any order. They all take the form key=val. The keyword arguments are:

epsabs: Desired absolute error of approximation. Default is 1d-10.
limit: Size of internal work array. (limit - limlst)/2 is the maximum number of subintervals to use. Default is 200.
maxp1: Maximum number of Chebyshev moments. Must be greater than 0. Default is 100.
limlst: Upper bound on the number of cycles. Must be greater than or equal to 3. Default is 10.

quad_qawf returns a list of four elements:

an approximation to the integral,
the estimated absolute error of the approximation,
the number integrand evaluations,
an error code.

The error code (fourth element of the return value) can have the values:

0: no problems were encountered;
1: too many sub-intervals were done;
2: excessive roundoff error is detected;
3: extremely bad integrand behavior occurs;
6: if the input is invalid.

Examples:

(%i1) quad_qawf (exp(-x^2), x, 0, 1, 'cos, 'epsabs=1d-9);
(%o1)   [.6901942235215714, 2.84846300257552E-11, 215, 0]

(%i2) integrate (exp(-x^2)*cos(x), x, 0, inf);
                          - 1/4
                        %e      sqrt(%pi)
(%o2)                   -----------------
                                2

(%i3) ev (%, numer);
(%o3)                   .6901942235215714

Category: Numerical methods · Category: Package quadpack

Function: quad_qawo
quad_qawo (f(x), x, a, b, omega, trig, [epsrel, epsabs, limit, maxp1, limlst])
quad_qawo (f, x, a, b, omega, trig, [epsrel, epsabs, limit, maxp1, limlst])

Integration of cos (omega x) f(x) or sin (omega x) f(x) over a finite interval, where omega is a constant. The rule evaluation component is based on the modified Clenshaw-Curtis technique. quad_qawo applies adaptive subdivision with extrapolation, similar to quad_qags.

quad_qawo computes the integral using the Quadpack QAWO routine:

integrate (f(x)*w(x), x, a, b)

The weight function w is selected by trig:

cos: w(x) = cos (omega x)
sin: w(x) = sin (omega x)

The integrand may be specified as the name of a Maxima or Lisp function or operator, a Maxima lambda expression, or a general Maxima expression.

The keyword arguments are optional and may be specified in any order. They all take the form key=val. The keyword arguments are:

epsrel: Desired relative error of approximation. Default is 1d-8.
epsabs: Desired absolute error of approximation. Default is 0.
limit: Size of internal work array. limit/2 is the maximum number of subintervals to use. Default is 200.
maxp1: Maximum number of Chebyshev moments. Must be greater than 0. Default is 100.
limlst: Upper bound on the number of cycles. Must be greater than or equal to 3. Default is 10.

quad_qawo returns a list of four elements:

an approximation to the integral,
the estimated absolute error of the approximation,
the number integrand evaluations,
an error code.

The error code (fourth element of the return value) can have the values:

0: no problems were encountered;
1: too many sub-intervals were done;
2: excessive roundoff error is detected;
3: extremely bad integrand behavior occurs;
6: if the input is invalid.

Examples:

x, 0, inf));

(%i1) quad_qawo (x^(-1/2)*exp(-2^(-2)*x), x, 1d-8, 20*2^2, 1, cos);
(%o1)     [1.376043389877692, 4.72710759424899E-11, 765, 0]

(%i2) rectform (integrate (x^(-1/2)*exp(-2^(-alpha)*x) * cos(x),
      x, 0, inf));
                   alpha/2 - 1/2            2 alpha
        sqrt(%pi) 2              sqrt(sqrt(2        + 1) + 1)
(%o2)   -----------------------------------------------------
                               2 alpha
                         sqrt(2        + 1)

(%i3) ev (%, alpha=2, numer);
(%o3)                     1.376043390090716

Category: Numerical methods · Category: Package quadpack

Function: quad_qaws
quad_qaws (f(x), x, a, b, alpha, beta, wfun, [epsrel, epsabs, limit])
quad_qaws (f, x, a, b, alpha, beta, wfun, [epsrel, epsabs, limit])

Integration of w(x) f(x) over a finite interval, where w(x) is a certain algebraic or logarithmic function. A globally adaptive subdivision strategy is applied, with modified Clenshaw-Curtis integration on the subintervals which contain the endpoints of the interval of integration.

quad_qaws computes the integral using the Quadpack QAWS routine:

integrate (f(x)*w(x), x, a, b)

The weight function w is selected by wfun:

1: w(x) = (x - a)^alpha (b - x)^beta
2: w(x) = (x - a)^alpha (b - x)^beta log(x - a)
3: w(x) = (x - a)^alpha (b - x)^beta log(b - x)
4: w(x) = (x - a)^alpha (b - x)^beta log(x - a) log(b - x)

The integrand may be specified as the name of a Maxima or Lisp function or operator, a Maxima lambda expression, or a general Maxima expression.

The keyword arguments are optional and may be specified in any order. They all take the form key=val. The keyword arguments are:

epsrel: Desired relative error of approximation. Default is 1d-8.
epsabs: Desired absolute error of approximation. Default is 0.
limit: Size of internal work array. limitis the maximum number of subintervals to use. Default is 200.

quad_qaws returns a list of four elements:

an approximation to the integral,
the estimated absolute error of the approximation,
the number integrand evaluations,
an error code.

The error code (fourth element of the return value) can have the values:

0: no problems were encountered;
1: too many sub-intervals were done;
2: excessive roundoff error is detected;
3: extremely bad integrand behavior occurs;
6: if the input is invalid.

Examples:

’epsabs=1d-9);

(%i1) quad_qaws (1/(x+1+2^(-4)), x, -1, 1, -0.5, -0.5, 1,
                 'epsabs=1d-9);
(%o1)     [8.750097361672832, 1.24321522715422E-10, 170, 0]

(%i2) integrate ((1-x*x)^(-1/2)/(x+1+2^(-alpha)), x, -1, 1);
       alpha
Is  4 2      - 1  positive, negative, or zero?

pos;
                          alpha         alpha
                   2 %pi 2      sqrt(2 2      + 1)
(%o2)              -------------------------------
                               alpha
                            4 2      + 2

(%i3) ev (%, alpha=4, numer);
(%o3)                     8.750097361672829

Category: Numerical methods · Category: Package quadpack

Function: quad_qagp
quad_qagp (f(x), x, a, b, points, [epsrel, epsabs, limit])
quad_qagp (f, x, a, b, points, [epsrel, epsabs, limit])

Integration of a general function over a finite interval. quad_qagp implements globally adaptive interval subdivision with extrapolation (de Doncker, 1978) by the Epsilon algorithm (Wynn, 1956).

quad_qagp computes the integral

integrate (f(x), x, a, b)

The function to be integrated is f(x), with dependent variable x, and the function is to be integrated between the limits a and b.

The integrand may be specified as the name of a Maxima or Lisp function or operator, a Maxima lambda expression, or a general Maxima expression.

To help the integrator, the user must supply a list of points where the integrand is singular or discontinous.

The keyword arguments are optional and may be specified in any order. They all take the form key=val. The keyword arguments are:

epsrel: Desired relative error of approximation. Default is 1d-8.
epsabs: Desired absolute error of approximation. Default is 0.
limit: Size of internal work array. limit is the maximum number of subintervals to use. Default is 200.

quad_qagp returns a list of four elements:

an approximation to the integral,
the estimated absolute error of the approximation,
the number integrand evaluations,
an error code.

The error code (fourth element of the return value) can have the values:

0: no problems were encountered;
1: too many sub-intervals were done;
2: excessive roundoff error is detected;
3: extremely bad integrand behavior occurs;
4: failed to converge
5: integral is probably divergent or slowly convergent
6: if the input is invalid.

Examples:

(%i1) quad_qagp(x^3*log(abs((x^2-1)*(x^2-2))),x,0,3,[1,sqrt(2)]);
(%o1)   [52.74074838347143, 2.6247632689546663e-7, 1029, 0]

(%i2) quad_qags(x^3*log(abs((x^2-1)*(x^2-2))), x, 0, 3);
(%o2)   [52.74074847951494, 4.088443219529836e-7, 1869, 0]

The integrand has singularities at 1 and sqrt(2) so we supply these points to quad_qagp. We also note that quad_qagp is more accurate and more efficient that quad_qags.

Category: Numerical methods · Category: Package quadpack

Function: quad_control (parameter, [value])

Control error handling for quadpack. The parameter should be one of the following symbols:

current_error: The current error number
control: Controls if messages are printed or not. If it is set to zero or less, messages are suppressed.
max_message: The maximum number of times any message is to be printed.

If value is not given, then the current value of the parameter is returned. If value is given, the value of parameter is set to the given value.

Category: Numerical methods · Category: Package quadpack

20 Equations

20.1 Functions and Variables for Equations

System variable: %rnum

Default value: 0

%rnum is the counter for the %r variables introduced in solutions by solve and algsys.. The next %r variable is numbered %rnum+1.

21 Differential Equations

21.1 Introduction to Differential Equations

This section describes the functions available in Maxima to obtain analytic solutions for some specific types of first and second-order equations. To obtain a numerical solution for a system of differential equations, see the additional package dynamics. For graphical representations in phase space, see the additional package plotdf.

21.2 Functions and Variables for Differential Equations

Function: bc2 (solution, xval1, yval1, xval2, yval2)

Solves a boundary value problem for a second order differential equation. Here: solution is a general solution to the equation, as found by ode2; xval1 specifies the value of the independent variable in a first point, in the form x = x1, and yval1 gives the value of the dependent variable in that point, in the form y = y1. The expressions xval2 and yval2 give the values for these variables at a second point, using the same form.

See ode2 for an example of its usage.

Category: Differential equations · Category: Laplace transform

Function: desolve
desolve (eqn, x)
desolve ([eqn_1, ..., eqn_n], [x_1, ..., x_n])

The function desolve solves systems of linear ordinary differential equations using Laplace transform. Here the eqn’s are differential equations in the dependent variables x_1, ..., x_n. The functional dependence of x_1, ..., x_n on an independent variable, for instance x, must be explicitly indicated in the variables and its derivatives. For example, this would not be the correct way to define two equations:

eqn_1: 'diff(f,x,2) = sin(x) + 'diff(g,x);
eqn_2: 'diff(f,x) + x^2 - f = 2*'diff(g,x,2);

The correct way would be:

eqn_1: 'diff(f(x),x,2) = sin(x) + 'diff(g(x),x);
eqn_2: 'diff(f(x),x) + x^2 - f(x) = 2*'diff(g(x),x,2);

The call to the function desolve would then be

desolve([eqn_1, eqn_2], [f(x),g(x)]);

If initial conditions at x=0 are known, they can be supplied before calling desolve by using atvalue.

(%i1) 'diff(f(x),x)='diff(g(x),x)+sin(x);
                 d           d
(%o1)            -- (f(x)) = -- (g(x)) + sin(x)
                 dx          dx
(%i2) 'diff(g(x),x,2)='diff(f(x),x)-cos(x);

                  2
                 d            d
(%o2)            --- (g(x)) = -- (f(x)) - cos(x)
                   2          dx
                 dx

(%i3) atvalue('diff(g(x),x),x=0,a);
(%o3)                           a
(%i4) atvalue(f(x),x=0,1);
(%o4)                           1
(%i5) desolve([%o1,%o2],[f(x),g(x)]);
                  x
(%o5) [f(x) = a %e  - a + 1, g(x) = 

                                                x
                                   cos(x) + a %e  - a + g(0) - 1]
(%i6) [%o1,%o2],%o5,diff;
             x       x      x                x
(%o6)   [a %e  = a %e , a %e  - cos(x) = a %e  - cos(x)]

If desolve cannot obtain a solution, it returns false.

Function: ic1 (solution, xval, yval)

Solves initial value problems for first order differential equations. Here solution is a general solution to the equation, as found by ode2, xval gives an initial value for the independent variable in the form x = x0, and yval gives the initial value for the dependent variable in the form y = y0.

See ode2 for an example of its usage.

Function: ic2 (solution, xval, yval, dval)

Solves initial value problems for second-order differential equations. Here solution is a general solution to the equation, as found by ode2, xval gives the initial value for the independent variable in the form x = x0, yval gives the initial value of the dependent variable in the form y = y0, and dval gives the initial value for the first derivative of the dependent variable with respect to independent variable, in the form diff(y,x) = dy0 (diff does not have to be quoted).

See ode2 for an example of its usage.

Function: ode2 (eqn, dvar, ivar)

The function ode2 solves an ordinary differential equation (ODE) of first or second order. It takes three arguments: an ODE given by eqn, the dependent variable dvar, and the independent variable ivar. When successful, it returns either an explicit or implicit solution for the dependent variable. %c is used to represent the integration constant in the case of first-order equations, and %k1 and %k2 the constants for second-order equations. The dependence of the dependent variable on the independent variable does not have to be written explicitly, as in the case of desolve, but the independent variable must always be given as the third argument.

If ode2 cannot obtain a solution for whatever reason, it returns false, after perhaps printing out an error message. The methods implemented for first order equations in the order in which they are tested are: linear, separable, exact - perhaps requiring an integrating factor, homogeneous, Bernoulli’s equation, and a generalized homogeneous method. The types of second-order equations which can be solved are: constant coefficients, exact, linear homogeneous with non-constant coefficients which can be transformed to constant coefficients, the Euler or equi-dimensional equation, equations solvable by the method of variation of parameters, and equations which are free of either the independent or of the dependent variable so that they can be reduced to two first order linear equations to be solved sequentially.

In the course of solving ODE’s, several variables are set purely for informational purposes: method denotes the method of solution used (e.g., linear), intfactor denotes any integrating factor used, odeindex denotes the index for Bernoulli’s method or for the generalized homogeneous method, and yp denotes the particular solution for the variation of parameters technique.

In order to solve initial value problems (IVP) functions ic1 and ic2 are available for first and second order equations, and to solve second-order boundary value problems (BVP) the function bc2 can be used.

Example:

(%i1) x^2*'diff(y,x) + 3*y*x = sin(x)/x;
                      2 dy           sin(x)
(%o1)                x  -- + 3 x y = ------
                        dx             x
(%i2) ode2(%,y,x);
                             %c - cos(x)
(%o2)                    y = -----------
                                  3
                                 x
(%i3) ic1(%o2,x=%pi,y=0);
                              cos(x) + 1
(%o3)                   y = - ----------
                                   3
                                  x
(%i4) 'diff(y,x,2) + y*'diff(y,x)^3 = 0;
                         2
                        d y      dy 3
(%o4)                   --- + y (--)  = 0
                          2      dx
                        dx
(%i5) ode2(%,y,x);
                      3
                     y  + 6 %k1 y
(%o5)                ------------ = x + %k2
                          6
(%i6) ratsimp(ic2(%o5,x=0,y=0,'diff(y,x)=2));

                             3
                          2 y  - 3 y
(%o6)                   - ---------- = x
                              6

(%i7) bc2(%o5,x=0,y=1,x=1,y=3);
                         3
                        y  - 10 y       3
(%o7)                   --------- = x - -
                            6           2

Category: Package fft · Category: Complex variables

22 Numerical

22.1 Introduction to fast Fourier transform

The fft package comprises functions for the numerical (not symbolic) computation of the fast Fourier transform.

Category: Fourier transform · Category: Numerical methods · Category: Share packages · Category: Package fft

22.2 Functions and Variables for fast Fourier transform

Function: polartorect (r, t)

Translates complex values of the form r %e^(%i t) to the form a + b %i, where r is the magnitude and t is the phase. r and t are 1-dimensional arrays of the same size. The array size need not be a power of 2.

The original values of the input arrays are replaced by the real and imaginary parts, a and b, on return. The outputs are calculated as

a = r cos(t)
b = r sin(t)

polartorect is the inverse function of recttopolar.

load(fft) loads this function. See also fft.

Function: recttopolar (a, b)

Translates complex values of the form a + b %i to the form r %e^(%i t), where a is the real part and b is the imaginary part. a and b are 1-dimensional arrays of the same size. The array size need not be a power of 2.

The original values of the input arrays are replaced by the magnitude and angle, r and t, on return. The outputs are calculated as

r = sqrt(a^2 + b^2)
t = atan2(b, a)

The computed angle is in the range -%pi to %pi.

recttopolar is the inverse function of polartorect.

load(fft) loads this function. See also fft.

Category: Package fft · Category: Complex variables

Function: inverse_fft (y)

Computes the inverse complex fast Fourier transform. y is a list or array (named or unnamed) which contains the data to transform. The number of elements must be a power of 2. The elements must be literal numbers (integers, rationals, floats, or bigfloats) or symbolic constants, or expressions a + b*%i where a and b are literal numbers or symbolic constants.

inverse_fft returns a new object of the same type as y, which is not modified. Results are always computed as floats or expressions a + b*%i where a and b are floats. If bigfloat precision is needed the function bf_inverse_fft can be used instead as a drop-in replacement of inverse_fft that is slower, but supports bfloats.

The inverse discrete Fourier transform is defined as follows. Let x be the output of the inverse transform. Then for j from 0 through n - 1,

x[j] = sum(y[k] exp(-2 %i %pi j k / n), k, 0, n - 1)

As there are various sign and normalization conventions possible, this definition of the transform may differ from that used by other mathematical software.

load(fft) loads this function.

See also fft (forward transform), recttopolar, and polartorect.

Examples:

Real data.

(%i1) load ("fft") $
(%i2) fpprintprec : 4 $
(%i3) L : [1, 2, 3, 4, -1, -2, -3, -4] $
(%i4) L1 : inverse_fft (L);
(%o4) [0.0, 14.49 %i - .8284, 0.0, 2.485 %i + 4.828, 0.0, 
                       4.828 - 2.485 %i, 0.0, - 14.49 %i - .8284]
(%i5) L2 : fft (L1);
(%o5) [1.0, 2.0 - 2.168L-19 %i, 3.0 - 7.525L-20 %i, 
4.0 - 4.256L-19 %i, - 1.0, 2.168L-19 %i - 2.0, 
7.525L-20 %i - 3.0, 4.256L-19 %i - 4.0]
(%i6) lmax (abs (L2 - L));
(%o6)                       3.545L-16

Complex data.

(%i1) load ("fft") $
(%i2) fpprintprec : 4 $                 
(%i3) L : [1, 1 + %i, 1 - %i, -1, -1, 1 - %i, 1 + %i, 1] $
(%i4) L1 : inverse_fft (L);
(%o4) [4.0, 2.711L-19 %i + 4.0, 2.0 %i - 2.0, 
- 2.828 %i - 2.828, 0.0, 5.421L-20 %i + 4.0, - 2.0 %i - 2.0, 
2.828 %i + 2.828]
(%i5) L2 : fft (L1);
(%o5) [4.066E-20 %i + 1.0, 1.0 %i + 1.0, 1.0 - 1.0 %i, 
1.55L-19 %i - 1.0, - 4.066E-20 %i - 1.0, 1.0 - 1.0 %i, 
1.0 %i + 1.0, 1.0 - 7.368L-20 %i]
(%i6) lmax (abs (L2 - L));                    
(%o6)                       6.841L-17

Function: fft (x)

Computes the complex fast Fourier transform. x is a list or array (named or unnamed) which contains the data to transform. The number of elements must be a power of 2. The elements must be literal numbers (integers, rationals, floats, or bigfloats) or symbolic constants, or expressions a + b*%i where a and b are literal numbers or symbolic constants.

fft returns a new object of the same type as x, which is not modified. Results are always computed as floats or expressions a + b*%i where a and b are floats. If bigfloat precision is needed the function bf_fft can be used instead as a drop-in replacement of fft that is slower, but supports bfloats. In addition if it is known that the input consists of only real values (no imaginary parts), real_fft can be used which is potentially faster.

The discrete Fourier transform is defined as follows. Let y be the output of the transform. Then for k from 0 through n - 1,

y[k] = (1/n) sum(x[j] exp(+2 %i %pi j k / n), j, 0, n - 1)

As there are various sign and normalization conventions possible, this definition of the transform may differ from that used by other mathematical software.

When the data x are real, real coefficients a and b can be computed such that

x[j] = sum(a[k]*cos(2*%pi*j*k/n)+b[k]*sin(2*%pi*j*k/n), k, 0, n/2)

with

a[0] = realpart (y[0])
b[0] = 0

and, for k from 1 through n/2 - 1,

a[k] = realpart (y[k] + y[n - k])
b[k] = imagpart (y[n - k] - y[k])

and

a[n/2] = realpart (y[n/2])
b[n/2] = 0

load(fft) loads this function.

See also inverse_fft (inverse transform), recttopolar, and polartorect.. See real_fft for FFTs of a real-valued input, and bf_fft and bf_real_fft for operations on bigfloat values.

Examples:

Real data.

(%i1) load ("fft") $
(%i2) fpprintprec : 4 $
(%i3) L : [1, 2, 3, 4, -1, -2, -3, -4] $
(%i4) L1 : fft (L);
(%o4) [0.0, - 1.811 %i - .1036, 0.0, .6036 - .3107 %i, 0.0, 
                         .3107 %i + .6036, 0.0, 1.811 %i - .1036]
(%i5) L2 : inverse_fft (L1);
(%o5) [1.0, 2.168L-19 %i + 2.0, 7.525L-20 %i + 3.0, 
4.256L-19 %i + 4.0, - 1.0, - 2.168L-19 %i - 2.0, 
- 7.525L-20 %i - 3.0, - 4.256L-19 %i - 4.0]
(%i6) lmax (abs (L2 - L));
(%o6)                       3.545L-16

Complex data.

(%i1) load ("fft") $
(%i2) fpprintprec : 4 $
(%i3) L : [1, 1 + %i, 1 - %i, -1, -1, 1 - %i, 1 + %i, 1] $
(%i4) L1 : fft (L);
(%o4) [0.5, .3536 %i + .3536, - 0.25 %i - 0.25, 
0.5 - 6.776L-21 %i, 0.0, - .3536 %i - .3536, 0.25 %i - 0.25, 
0.5 - 3.388L-20 %i]
(%i5) L2 : inverse_fft (L1);
(%o5) [1.0 - 4.066E-20 %i, 1.0 %i + 1.0, 1.0 - 1.0 %i, 
- 1.008L-19 %i - 1.0, 4.066E-20 %i - 1.0, 1.0 - 1.0 %i, 
1.0 %i + 1.0, 1.947L-20 %i + 1.0]
(%i6) lmax (abs (L2 - L));
(%o6)                       6.83L-17

Computation of sine and cosine coefficients.

(%i1) load ("fft") $
(%i2) fpprintprec : 4 $
(%i3) L : [1, 2, 3, 4, 5, 6, 7, 8] $
(%i4) n : length (L) $
(%i5) x : make_array (any, n) $
(%i6) fillarray (x, L) $
(%i7) y : fft (x) $
(%i8) a : make_array (any, n/2 + 1) $
(%i9) b : make_array (any, n/2 + 1) $
(%i10) a[0] : realpart (y[0]) $
(%i11) b[0] : 0 $
(%i12) for k : 1 thru n/2 - 1 do
   (a[k] : realpart (y[k] + y[n - k]),
    b[k] : imagpart (y[n - k] - y[k]));
(%o12)                        done
(%i13) a[n/2] : y[n/2] $
(%i14) b[n/2] : 0 $
(%i15) listarray (a);
(%o15)          [4.5, - 1.0, - 1.0, - 1.0, - 0.5]
(%i16) listarray (b);
(%o16)           [0, - 2.414, - 1.0, - .4142, 0]
(%i17) f(j) := sum (a[k]*cos(2*%pi*j*k/n) + b[k]*sin(2*%pi*j*k/n), 
                    k, 0, n/2) $
(%i18) makelist (float (f (j)), j, 0, n - 1);
(%o18)      [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]

Function: real_fft (x)

Computes the fast Fourier transform of a real-valued sequence x. This is equivalent to performing fft(x), except that only the first N/2+1 results are returned, where N is the length of x. N must be power of two.

No check is made that x contains only real values.

The symmetry properites of the Fourier transform of real sequences to reduce he complexity. In particular the first and last output values of real_fft are purely real. For larger sequencyes, real_fft may be computed more quickly than fft.

Since the output length is short, the normal inverse_fft cannot be directly used. Use inverse_real_fft to compute the inverse.

· Category: Package fft

Function: inverse_real_fft (y)

Computes the inverse Fourier transfrom of y, which must have a length of N/2+1 where N is a power of two. That is, the input x is expected to be the output of real_fft.

No check is made to ensure that the input has the correct format. (The first and last elements must be purely real.)

Function: bf_inverse_fft (y)

Computes the inverse complex fast Fourier transform. This is the bigfloat version of inverse_fft that converts the input to bigfloats and returns a bigfloat result.

· Category: Package fft

Function: bf_fft (y)

Computes the forward complex fast Fourier transform. This is the bigfloat version of fft that converts the input to bigfloats and returns a bigfloat result.

· Category: Package fft

Function: bf_real_fft (x)

Computes the forward fast Fourier transform of a real-valued input returning a bigfloat result. This is the bigfloat version of real_fft.

Function: bf_inverse_real_fft (y)

Computes the inverse fast Fourier transfrom with a real-valued bigfloat output. This is the bigfloat version of inverse_real_fft.

Category: Numerical methods

22.3 Functions for numerical solution of equations

Function: horner
horner (expr, x)
horner (expr)

Returns a rearranged representation of expr as in Horner’s rule, using x as the main variable if it is specified. x may be omitted in which case the main variable of the canonical rational expression form of expr is used.

horner sometimes improves stability if expr is to be numerically evaluated. It is also useful if Maxima is used to generate programs to be run in Fortran. See also stringout.

(%i1) expr: 1e-155*x^2 - 5.5*x + 5.2e155;
                           2
(%o1)             1.e-155 x  - 5.5 x + 5.2e+155
(%i2) expr2: horner (%, x), keepfloat: true;
(%o2)         1.0 ((1.e-155 x - 5.5) x + 5.2e+155)
(%i3) ev (expr, x=1e155);
Maxima encountered a Lisp error:

 arithmetic error FLOATING-POINT-OVERFLOW signalled

Automatically continuing.
To enable the Lisp debugger set *debugger-hook* to nil.
(%i4) ev (expr2, x=1e155);
(%o4)                 7.00000000000001e+154

Function: find_root (expr, x, a, b, [abserr, relerr])

Function: find_root (f, a, b, [abserr, relerr])

Function: bf_find_root (expr, x, a, b, [abserr, relerr])

Function: bf_find_root (f, a, b, [abserr, relerr])

Option variable: find_root_error

Option variable: find_root_abs

Option variable: find_root_rel

Finds a root of the expression expr or the function f over the closed interval [a, b]. The expression expr may be an equation, in which case find_root seeks a root of lhs(expr) - rhs(expr).

Given that Maxima can evaluate expr or f over [a, b] and that expr or f is continuous, find_root is guaranteed to find the root, or one of the roots if there is more than one.

find_root initially applies binary search. If the function in question appears to be smooth enough, find_root applies linear interpolation instead.

bf_find_root is a bigfloat version of find_root. The function is computed using bigfloat arithmetic and a bigfloat result is returned. Otherwise, bf_find_root is identical to find_root, and the following description is equally applicable to bf_find_root.

The accuracy of find_root is governed by abserr and relerr, which are optional keyword arguments to find_root. These keyword arguments take the form key=val. The keyword arguments are

abserr: Desired absolute error of function value at root. Default is find_root_abs.
relerr: Desired relative error of root. Default is find_root_rel.

find_root stops when the function in question evaluates to something less than or equal to abserr, or if successive approximants x_0, x_1 differ by no more than relerr * max(abs(x_0), abs(x_1)). The default values of find_root_abs and find_root_rel are both zero.

find_root expects the function in question to have a different sign at the endpoints of the search interval. When the function evaluates to a number at both endpoints and these numbers have the same sign, the behavior of find_root is governed by find_root_error. When find_root_error is true, find_root prints an error message. Otherwise find_root returns the value of find_root_error. The default value of find_root_error is true.

If f evaluates to something other than a number at any step in the search algorithm, find_root returns a partially-evaluated find_root expression.

The order of a and b is ignored; the region in which a root is sought is [min(a, b), max(a, b)].

Examples:

(%i1) f(x) := sin(x) - x/2;
                                        x
(%o1)                  f(x) := sin(x) - -
                                        2
(%i2) find_root (sin(x) - x/2, x, 0.1, %pi);
(%o2)                   1.895494267033981
(%i3) find_root (sin(x) = x/2, x, 0.1, %pi);
(%o3)                   1.895494267033981
(%i4) find_root (f(x), x, 0.1, %pi);
(%o4)                   1.895494267033981
(%i5) find_root (f, 0.1, %pi);
(%o5)                   1.895494267033981
(%i6) find_root (exp(x) = y, x, 0, 100);
                            x
(%o6)           find_root(%e  = y, x, 0.0, 100.0)
(%i7) find_root (exp(x) = y, x, 0, 100), y = 10;
(%o7)                   2.302585092994046
(%i8) log (10.0);
(%o8)                   2.302585092994046
(%i9) fpprec:32;
(%o9)                           32
(%i10) bf_find_root (exp(x) = y, x, 0, 100), y = 10;
(%o10)                  2.3025850929940456840179914546844b0
(%i11) log(10b0);
(%o11)                  2.3025850929940456840179914546844b0

Category: Algebraic equations · Category: Numerical methods

Function: newton (expr, x, x_0, eps)

Returns an approximate solution of expr = 0 by Newton’s method, considering expr to be a function of one variable, x. The search begins with x = x_0 and proceeds until abs(expr) < eps (with expr evaluated at the current value of x).

newton allows undefined variables to appear in expr, so long as the termination test abs(expr) < eps evaluates to true or false. Thus it is not necessary that expr evaluate to a number.

load(newton1) loads this function.

See also realroots, allroots, find_root and mnewton-pkg

Examples:

(%i1) load ("newton1");
(%o1)  /maxima/share/numeric/newton1.mac
(%i2) newton (cos (u), u, 1, 1/100);
(%o2)                   1.570675277161251
(%i3) ev (cos (u), u = %);
(%o3)                 1.2104963335033529e-4
(%i4) assume (a > 0);
(%o4)                        [a > 0]
(%i5) newton (x^2 - a^2, x, a/2, a^2/100);
(%o5)                  1.00030487804878 a
(%i6) ev (x^2 - a^2, x = %);
                                           2
(%o6)                6.098490481853958e-4 a

Category: Algebraic equations · Category: Numerical methods

22.4 Introduction to numerical solution of differential equations

The Ordinary Differential Equations (ODE) solved by the functions in this section should have the form,

       dy
       -- = F(x,y)
       dx

which is a first-order ODE. Higher order differential equations of order n must be written as a system of n first-order equations of that kind. For instance, a second-order ODE should be written as a system of two equations

       dx               dy
       -- = G(x,y,t)    -- = F(x,y,t) 
       dt               dt

The first argument in the functions will be a list with the expressions on the right-side of the ODE’s. The variables whose derivatives are represented by those expressions should be given in a second list. In the case above those variables are x and y. The independent variable, t in the examples above, might be given in a separated option. If the expressions given do not depend on that independent variable, the system is called autonomous.

Category: Differential equations · Category: Numerical methods · Category: Plotting

22.5 Functions for numerical solution of differential equations

Function: plotdf
    plotdf (dydx, options…)
    plotdf (dvdu, [u,v], options…)
    plotdf ([dxdt,cdydt], options…)
    plotdf ([dudt,cdvdt], [u,cv], options…)

The function plotdf creates a two-dimensional plot of the direction field (also called slope field) for a first-order Ordinary Differential Equation (ODE) or a system of two autonomous first-order ODE’s.

Plotdf requires Xmaxima, even if its run from a Maxima session in a console, since the plot will be created by the Tk scripts in Xmaxima. If Xmaxima is not installed plotdf will not work.

dydx, dxdt and dydt are expressions that depend on x and y. dvdu, dudt and dvdt are expressions that depend on u and v. In addition to those two variables, the expressions can also depend on a set of parameters, with numerical values given with the parameters option (the option syntax is given below), or with a range of allowed values specified by a sliders option.

Several other options can be given within the command, or selected in the menu. Integral curves can be obtained by clicking on the plot, or with the option trajectory_at. The direction of the integration can be controlled with the direction option, which can have values of forward, backward or both. The number of integration steps is given by nsteps; at each integration step the time increment will be adjusted automatically to produce displacements much smaller than the size of the plot window. The numerical method used is 4th order Runge-Kutta with variable time steps.

Plot window menu:

The menu bar of the plot window has the following seven icons:

An X. Can be used to close the plot window.

A wrench and a screwdriver. Opens the configuration menu with several fields that show the ODE(s) in use and various other settings. If a pair of coordinates are entered in the field Trajectory at and the enter key is pressed, a new integral curve will be shown, in addition to the ones already shown.

Two arrows following a circle. Replots the direction field with the new settings defined in the configuration menu and replots only the last integral curve that was previously plotted.

Hard disk drive with an arrow. Used to save a copy of the plot, in Postscript format, in the file specified in a field of the box that appears when that icon is clicked.

Magnifying glass with a plus sign. Zooms in the plot.

Magnifying glass with a minus sign. Zooms out the plot. The plot can be displaced by holding down the right mouse button while the mouse is moved.

Icon of a plot. Opens another window with a plot of the two variables in terms of time, for the last integral curve that was plotted.

Plot options:

Options can also be given within the plotdf itself, each one being a list of two or more elements. The first element in each option is the name of the option, and the remainder is the value or values assigned to the option.

The options which are recognized by plotdf are the following:

nsteps defines the number of steps that will be used for the independent variable, to compute an integral curve. The default value is 100.
direction defines the direction of the independent variable that will be followed to compute an integral curve. Possible values are forward, to make the independent variable increase nsteps times, with increments tstep, backward, to make the independent variable decrease, or both that will lead to an integral curve that extends nsteps forward, and nsteps backward. The keywords right and left can be used as synonyms for forward and backward. The default value is both.
tinitial defines the initial value of variable t used to compute integral curves. Since the differential equations are autonomous, that setting will only appear in the plot of the curves as functions of t. The default value is 0.
versus_t is used to create a second plot window, with a plot of an integral curve, as two functions x, y, of the independent variable t. If versus_t is given any value different from 0, the second plot window will be displayed. The second plot window includes another menu, similar to the menu of the main plot window. The default value is 0.
trajectory_at defines the coordinates xinitial and yinitial for the starting point of an integral curve. The option is empty by default.
parameters defines a list of parameters, and their numerical values, used in the definition of the differential equations. The name and values of the parameters must be given in a string with a comma-separated sequence of pairs name=value.
sliders defines a list of parameters that will be changed interactively using slider buttons, and the range of variation of those parameters. The names and ranges of the parameters must be given in a string with a comma-separated sequence of elements name=min:max
xfun defines a string with semi-colon-separated sequence of functions of x to be displayed, on top of the direction field. Those functions will be parsed by Tcl and not by Maxima.
x should be followed by two numbers, which will set up the minimum and maximum values shown on the horizontal axis. If the variable on the horizontal axis is not x, then this option should have the name of the variable on the horizontal axis. The default horizontal range is from -10 to 10.
y should be followed by two numbers, which will set up the minimum and maximum values shown on the vertical axis. If the variable on the vertical axis is not y, then this option should have the name of the variable on the vertical axis. The default vertical range is from -10 to 10.
xaxislabel will be used to identify the horizontal axis. Its default value is the name of the first state variable.
yaxislabel will be used to identify the vertical axis. Its default value is the name of the second state variable.
number_of_arrows should be set to a square number and defines the approximate density of the arrows being drawn. The default value is 225.

Examples:

To show the direction field of the differential equation y' = exp(-x) + y and the solution that goes through (2, -0.1):
```
(%i1) plotdf(exp(-x)+y,[trajectory_at,2,-0.1])$
```
To obtain the direction field for the equation diff(y,x) = x - y^2 and the solution with initial condition y(-1) = 3, we can use the command:
```
(%i1) plotdf(x-y^2,[xfun,"sqrt(x);-sqrt(x)"],
         [trajectory_at,-1,3], [direction,forward],
         [y,-5,5], [x,-4,16])$
```
The graph also shows the function y = sqrt(x).
The following example shows the direction field of a harmonic oscillator, defined by the two equations dz/dt = v and dv/dt = -k*z/m, and the integral curve through (z,v) = (6,0), with a slider that will allow you to change the value of m interactively (k is fixed at 2):
```
(%i1) plotdf([v,-k*z/m], [z,v], [parameters,"m=2,k=2"],
           [sliders,"m=1:5"], [trajectory_at,6,0])$
```

To plot the direction field of the Duffing equation, m*x''+c*x'+k*x+b*x^3 = 0, we introduce the variable y=x' and use:

(%i1) plotdf([y,-(k*x + c*y + b*x^3)/m],
             [parameters,"k=-1,m=1.0,c=0,b=1"],
             [sliders,"k=-2:2,m=-1:1"],[tstep,0.1])$

The direction field for a damped pendulum, including the solution for the given initial conditions, with a slider that can be used to change the value of the mass m, and with a plot of the two state variables as a function of time:

(%i1) plotdf([w,-g*sin(a)/l - b*w/m/l], [a,w],
        [parameters,"g=9.8,l=0.5,m=0.3,b=0.05"],
        [trajectory_at,1.05,-9],[tstep,0.01],
        [a,-10,2], [w,-14,14], [direction,forward],
        [nsteps,300], [sliders,"m=0.1:1"], [versus_t,1])$

Category: Differential equations · Category: Plotting · Category: Numerical methods

Function: ploteq (exp, ...options...)

Plots equipotential curves for exp, which should be an expression depending on two variables. The curves are obtained by integrating the differential equation that define the orthogonal trajectories to the solutions of the autonomous system obtained from the gradient of the expression given. The plot can also show the integral curves for that gradient system (option fieldlines).

This program also requires Xmaxima, even if its run from a Maxima session in a console, since the plot will be created by the Tk scripts in Xmaxima. By default, the plot region will be empty until the user clicks in a point (or gives its coordinate with in the set-up menu or via the trajectory_at option).

Most options accepted by plotdf can also be used for ploteq and the plot interface is the same that was described in plotdf.

Example:

(%i1) V: 900/((x+1)^2+y^2)^(1/2)-900/((x-1)^2+y^2)^(1/2)$
(%i2) ploteq(V,[x,-2,2],[y,-2,2],[fieldlines,"blue"])$

Clicking on a point will plot the equipotential curve that passes by that point (in red) and the orthogonal trajectory (in blue).

Category: Differential equations · Category: Plotting · Category: Numerical methods

Function: rk rk (ODE, var, initial, domain) rk ([ODE1, …, ODEm], [v1, …, vm], [init1, …, initm], domain)

The first form solves numerically one first-order ordinary differential equation, and the second form solves a system of m of those equations, using the 4th order Runge-Kutta method. var represents the dependent variable. ODE must be an expression that depends only on the independent and dependent variables and defines the derivative of the dependent variable with respect to the independent variable.

The independent variable is specified with domain, which must be a list of four elements as, for instance:

[t, 0, 10, 0.1]

the first element of the list identifies the independent variable, the second and third elements are the initial and final values for that variable, and the last element sets the increments that should be used within that interval.

If m equations are going to be solved, there should be m dependent variables v1, v2, ..., vm. The initial values for those variables will be init1, init2, ..., initm. There will still be just one independent variable defined by domain, as in the previous case. ODE1, ..., ODEm are the expressions that define the derivatives of each dependent variable in terms of the independent variable. The only variables that may appear in those expressions are the independent variable and any of the dependent variables. It is important to give the derivatives ODE1, ..., ODEm in the list in exactly the same order used for the dependent variables; for instance, the third element in the list will be interpreted as the derivative of the third dependent variable.

The program will try to integrate the equations from the initial value of the independent variable until its last value, using constant increments. If at some step one of the dependent variables takes an absolute value too large, the integration will be interrupted at that point. The result will be a list with as many elements as the number of iterations made. Each element in the results list is itself another list with m+1 elements: the value of the independent variable, followed by the values of the dependent variables corresponding to that point.

To solve numerically the differential equation

          dx/dt = t - x^2

With initial value x(t=0) = 1, in the interval of t from 0 to 8 and with increments of 0.1 for t, use:

(%i1) results: rk(t-x^2,x,1,[t,0,8,0.1])$
(%i2) plot2d ([discrete, results])$

the results will be saved in the list results and the plot will show the solution obtained, with t on the horizontal axis and x on the vertical axis.

To solve numerically the system:

        dx/dt = 4-x^2-4*y^2     dy/dt = y^2-x^2+1

for t between 0 and 4, and with values of -1.25 and 0.75 for x and y at t=0:

(%i1) sol: rk([4-x^2-4*y^2,y^2-x^2+1],[x,y],[-1.25,0.75],[t,0,4,0.02])$
(%i2) plot2d ([discrete,makelist([p[1],p[3]],p,sol)], [xlabel,"t"],[ylabel,"y"])$

The plot will show the solution for variable y as a function of t.

Category: Differential equations · Category: Numerical methods

23 Matrices and Linear Algebra

23.1 Introduction to Matrices and Linear Algebra

23.1.1 Dot

The operator . represents noncommutative multiplication and scalar product. When the operands are 1-column or 1-row matrices a and b, the expression a.b is equivalent to sum (a[i]*b[i], i, 1, length(a)). If a and b are not complex, this is the scalar product, also called the inner product or dot product, of a and b. The scalar product is defined as conjugate(a).b when a and b are complex; innerproduct in the eigen package provides the complex scalar product.

When the operands are more general matrices, the product is the matrix product a and b. The number of rows of b must equal the number of columns of a, and the result has number of rows equal to the number of rows of a and number of columns equal to the number of columns of b.

To distinguish . as an arithmetic operator from the decimal point in a floating point number, it may be necessary to leave spaces on either side. For example, 5.e3 is 5000.0 but 5 . e3 is 5 times e3.

There are several flags which govern the simplification of expressions involving ., namely dot0nscsimp, dot0simp, dot1simp, dotassoc, dotconstrules, dotdistrib, dotexptsimp, dotident, and dotscrules.

23.1.2 Matrices

Matrices are handled with speed and memory-efficiency in mind. This means that assigning a matrix to a variable will create a reference to, not a copy of the matrix. If the matrix is modified all references to the matrix point to the modified object (See copymatrix for a way of avoiding this):

(%i1) M1:matrix([0,0],[0,0]);
                            [ 0  0 ]
(%o1)                       [      ]
                            [ 0  0 ]

(%i2) M2:M1;
                            [ 0  0 ]
(%o2)                       [      ]
                            [ 0  0 ]

(%i3) M1[1][1]:2;
(%o3)                           2

(%i4) M2;
                            [ 2  0 ]
(%o4)                       [      ]
                            [ 0  0 ]

Converting a matrix to nested lists and vice versa works the following way:

(%i1) l:[[1,2],[3,4]];
(%o1)                   [[1, 2], [3, 4]]

(%i2) M1:apply('matrix,l);
                            [ 1  2 ]
(%o2)                       [      ]
                            [ 3  4 ]

(%i3) M2:transpose(M1);
                            [ 1  3 ]
(%o3)                       [      ]
                            [ 2  4 ]

(%i4) args(M2);
(%o4)                   [[1, 3], [2, 4]]

23.1.3 Vectors

vect is a package of functions for vector analysis. load ("vect") loads this package, and demo ("vect") displays a demonstration.

The vector analysis package can combine and simplify symbolic expressions including dot products and cross products, together with the gradient, divergence, curl, and Laplacian operators. The distribution of these operators over sums or products is governed by several flags, as are various other expansions, including expansion into components in any specific orthogonal coordinate systems. There are also functions for deriving the scalar or vector potential of a field.

The vect package contains these functions: vectorsimp, scalefactors, express, potential, and vectorpotential.

By default the vect package does not declare the dot operator to be a commutative operator. To get a commutative dot operator ., the command declare(".", commutative) must be executed.

Category: Vectors · Category: Share packages · Category: Package vect

23.1.4 eigen

The package eigen contains several functions devoted to the symbolic computation of eigenvalues and eigenvectors. Maxima loads the package automatically if one of the functions eigenvalues or eigenvectors is invoked. The package may be loaded explicitly as load ("eigen").

demo ("eigen") displays a demonstration of the capabilities of this package. batch ("eigen") executes the same demonstration, but without the user prompt between successive computations.

The functions in the eigen package are:
innerproduct, unitvector, columnvector, gramschmidt, eigenvalues,
eigenvectors, uniteigenvectors, and similaritytransform.

Category: Vectors · Category: Matrices · Category: Share packages · Category: Package eigen

23.2 Functions and Variables for Matrices and Linear Algebra

Function: addcol (M, list_1, …, list_n)

Appends the column(s) given by the one or more lists (or matrices) onto the matrix M.

24 Affine

24.1 Introduction to Affine

affine is a package to work with groups of polynomials.

Category: Polynomials · Category: Groebner bases · Category: Share packages · Category: Package affine

24.2 Functions and Variables for Affine

Function: fast_linsolve ([expr_1, …, expr_m], [x_1, …, x_n])

Solves the simultaneous linear equations expr_1, …, expr_m for the variables x_1, …, x_n. Each expr_i may be an equation or a general expression; if given as a general expression, it is treated as an equation of the form expr_i = 0.

The return value is a list of equations of the form [x_1 = a_1, …, x_n = a_n] where a_1, …, a_n are all free of x_1, …, x_n.

fast_linsolve is faster than linsolve for system of equations which are sparse.

load("affine") loads this function.

Function: grobner_basis ([expr_1, …, expr_m])

Returns a Groebner basis for the equations expr_1, …, expr_m. The function polysimp can then be used to simplify other functions relative to the equations.

grobner_basis ([3*x^2+1, y*x])$

polysimp (y^2*x + x^3*9 + 2) ==> -3*x + 2

polysimp(f) yields 0 if and only if f is in the ideal generated by expr_1, …, expr_m, that is, if and only if f is a polynomial combination of the elements of expr_1, …, expr_m.

load("affine") loads this function.

Function: set_up_dot_simplifications
set_up_dot_simplifications (eqns, check_through_degree)
set_up_dot_simplifications (eqns)

The eqns are polynomial equations in non commutative variables. The value of current_variables is the list of variables used for computing degrees. The equations must be homogeneous, in order for the procedure to terminate.

If you have checked overlapping simplifications in dot_simplifications above the degree of f, then the following is true: dotsimp (f) yields 0 if and only if f is in the ideal generated by the equations, i.e., if and only if f is a polynomial combination of the elements of the equations.

The degree is that returned by nc_degree. This in turn is influenced by the weights of individual variables.

load("affine") loads this function.

Function: declare_weights (x_1, w_1, …, x_n, w_n)

Assigns weights w_1, …, w_n to x_1, …, x_n, respectively. These are the weights used in computing nc_degree.

load("affine") loads this function.

Function: nc_degree (p)

Returns the degree of a noncommutative polynomial p. See declare_weights.

load("affine") loads this function.

Function: dotsimp (f)

Returns 0 if and only if f is in the ideal generated by the equations, i.e., if and only if f is a polynomial combination of the elements of the equations.

load("affine") loads this function.

Function: fast_central_elements ([x_1, …, x_n], n)

If set_up_dot_simplifications has been previously done, finds the central polynomials in the variables x_1, …, x_n in the given degree, n.

For example:

set_up_dot_simplifications ([y.x + x.y], 3);
fast_central_elements ([x, y], 2);
[y.y, x.x];

load("affine") loads this function.

Function: check_overlaps (n, add_to_simps)

Checks the overlaps thru degree n, making sure that you have sufficient simplification rules in each degree, for dotsimp to work correctly. This process can be speeded up if you know before hand what the dimension of the space of monomials is. If it is of finite global dimension, then hilbert should be used. If you don’t know the monomial dimensions, do not specify a rank_function. An optional third argument reset, false says don’t bother to query about resetting things.

load("affine") loads this function.

Function: mono ([x_1, …, x_n], n)

Returns the list of independent monomials relative to the current dot simplifications of degree n in the variables x_1, …, x_n.

load("affine") loads this function.

Function: monomial_dimensions (n)

Compute the Hilbert series through degree n for the current algebra.

load("affine") loads this function.

Function: extract_linear_equations ([p_1, …, p_n], [m_1, …, m_n])

Makes a list of the coefficients of the noncommutative polynomials p_1, …, p_n of the noncommutative monomials m_1, …, m_n. The coefficients should be scalars. Use list_nc_monomials to build the list of monomials.

load("affine") loads this function.

Function: list_nc_monomials
list_nc_monomials ([p_1, …, p_n])
list_nc_monomials (p)

Returns a list of the non commutative monomials occurring in a polynomial p or a list of polynomials p_1, …, p_n.

load("affine") loads this function.

Option variable: all_dotsimp_denoms

Default value: false

When all_dotsimp_denoms is a list, the denominators encountered by dotsimp are appended to the list. all_dotsimp_denoms may be initialized to an empty list [] before calling dotsimp.

By default, denominators are not collected by dotsimp.

Category: Display functions

25 itensor

25.1 Introduction to itensor

Maxima implements symbolic tensor manipulation of two distinct types: component tensor manipulation (ctensor package) and indicial tensor manipulation (itensor package).

Nota bene: Please see the note on ’new tensor notation’ below.

Component tensor manipulation means that geometrical tensor objects are represented as arrays or matrices. Tensor operations such as contraction or covariant differentiation are carried out by actually summing over repeated (dummy) indices with do statements. That is, one explicitly performs operations on the appropriate tensor components stored in an array or matrix.

Indicial tensor manipulation is implemented by representing tensors as functions of their covariant, contravariant and derivative indices. Tensor operations such as contraction or covariant differentiation are performed by manipulating the indices themselves rather than the components to which they correspond.

These two approaches to the treatment of differential, algebraic and analytic processes in the context of Riemannian geometry have various advantages and disadvantages which reveal themselves only through the particular nature and difficulty of the user’s problem. However, one should keep in mind the following characteristics of the two implementations:

The representation of tensors and tensor operations explicitly in terms of their components makes ctensor easy to use. Specification of the metric and the computation of the induced tensors and invariants is straightforward. Although all of Maxima’s powerful simplification capacity is at hand, a complex metric with intricate functional and coordinate dependencies can easily lead to expressions whose size is excessive and whose structure is hidden. In addition, many calculations involve intermediate expressions which swell causing programs to terminate before completion. Through experience, a user can avoid many of these difficulties.

Because of the special way in which tensors and tensor operations are represented in terms of symbolic operations on their indices, expressions which in the component representation would be unmanageable can sometimes be greatly simplified by using the special routines for symmetrical objects in itensor. In this way the structure of a large expression may be more transparent. On the other hand, because of the special indicial representation in itensor, in some cases the user may find difficulty with the specification of the metric, function definition, and the evaluation of differentiated "indexed" objects.

The itensor package can carry out differentiation with respect to an indexed variable, which allows one to use the package when dealing with Lagrangian and Hamiltonian formalisms. As it is possible to differentiate a field Lagrangian with respect to an (indexed) field variable, one can use Maxima to derive the corresponding Euler-Lagrange equations in indicial form. These equations can be translated into component tensor (ctensor) programs using the ic_convert function, allowing us to solve the field equations in a particular coordinate representation, or to recast the equations of motion in Hamiltonian form. See einhil.dem and bradic.dem for two comprehensive examples. The first, einhil.dem, uses the Einstein-Hilbert action to derive the Einstein field tensor in the homogeneous and isotropic case (Friedmann equations) and the spherically symmetric, static case (Schwarzschild solution.) The second, bradic.dem, demonstrates how to compute the Friedmann equations from the action of Brans-Dicke gravity theory, and also derives the Hamiltonian associated with the theory’s scalar field.

Category: Tensors · Category: Share packages · Category: Package itensor

25.1.1 New tensor notation

Earlier versions of the itensor package in Maxima used a notation that sometimes led to incorrect index ordering. Consider the following, for instance:

(%i2) imetric(g);
(%o2)                                done
(%i3) ishow(g([],[j,k])*g([],[i,l])*a([i,j],[]))$
                                 i l  j k
(%t3)                           g    g    a
                                           i j
(%i4) ishow(contract(%))$
                                      k l
(%t4)                                a

This result is incorrect unless a happens to be a symmetric tensor. The reason why this happens is that although itensor correctly maintains the order within the set of covariant and contravariant indices, once an index is raised or lowered, its position relative to the other set of indices is lost.

To avoid this problem, a new notation has been developed that remains fully compatible with the existing notation and can be used interchangeably. In this notation, contravariant indices are inserted in the appropriate positions in the covariant index list, but with a minus sign prepended. Functions like contract_Itensor and ishow are now aware of this new index notation and can process tensors appropriately.

In this new notation, the previous example yields a correct result:

(%i5) ishow(g([-j,-k],[])*g([-i,-l],[])*a([i,j],[]))$
                                 i l       j k
(%t5)                           g    a    g
                                      i j
(%i6) ishow(contract(%))$
                                      l k
(%t6)                                a

Presently, the only code that makes use of this notation is the lc2kdt function. Through this notation, it achieves consistent results as it applies the metric tensor to resolve Levi-Civita symbols without resorting to numeric indices.

Since this code is brand new, it probably contains bugs. While it has been tested to make sure that it doesn’t break anything using the "old" tensor notation, there is a considerable chance that "new" tensors will fail to interoperate with certain functions or features. These bugs will be fixed as they are encountered... until then, caveat emptor!

25.1.2 Indicial tensor manipulation

The indicial tensor manipulation package may be loaded by load("itensor"). Demos are also available: try demo("tensor").

In itensor a tensor is represented as an "indexed object" . This is a function of 3 groups of indices which represent the covariant, contravariant and derivative indices. The covariant indices are specified by a list as the first argument to the indexed object, and the contravariant indices by a list as the second argument. If the indexed object lacks either of these groups of indices then the empty list [] is given as the corresponding argument. Thus, g([a,b],[c]) represents an indexed object called g which has two covariant indices (a,b), one contravariant index (c) and no derivative indices.

The derivative indices, if they are present, are appended as additional arguments to the symbolic function representing the tensor. They can be explicitly specified by the user or be created in the process of differentiation with respect to some coordinate variable. Since ordinary differentiation is commutative, the derivative indices are sorted alphanumerically, unless iframe_flag is set to true, indicating that a frame metric is being used. This canonical ordering makes it possible for Maxima to recognize that, for example, t([a],[b],i,j) is the same as t([a],[b],j,i). Differentiation of an indexed object with respect to some coordinate whose index does not appear as an argument to the indexed object would normally yield zero. This is because Maxima would not know that the tensor represented by the indexed object might depend implicitly on the corresponding coordinate. By modifying the existing Maxima function diff in itensor, Maxima now assumes that all indexed objects depend on any variable of differentiation unless otherwise stated. This makes it possible for the summation convention to be extended to derivative indices. It should be noted that itensor does not possess the capabilities of raising derivative indices, and so they are always treated as covariant.

The following functions are available in the tensor package for manipulating indexed objects. At present, with respect to the simplification routines, it is assumed that indexed objects do not by default possess symmetry properties. This can be overridden by setting the variable allsym[false] to true, which will result in treating all indexed objects completely symmetric in their lists of covariant indices and symmetric in their lists of contravariant indices.

The itensor package generally treats tensors as opaque objects. Tensorial equations are manipulated based on algebraic rules, specifically symmetry and contraction rules. In addition, the itensor package understands covariant differentiation, curvature, and torsion. Calculations can be performed relative to a metric of moving frame, depending on the setting of the iframe_flag variable.

A sample session below demonstrates how to load the itensor package, specify the name of the metric, and perform some simple calculations.

(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) imetric(g);
(%o2)                                done
(%i3) components(g([i,j],[]),p([i,j],[])*e([],[]))$
(%i4) ishow(g([k,l],[]))$
(%t4)                               e p
                                       k l
(%i5) ishow(diff(v([i],[]),t))$
(%t5)                                  0
(%i6) depends(v,t);
(%o6)                               [v(t)]
(%i7) ishow(diff(v([i],[]),t))$
                                    d
(%t7)                               -- (v )
                                    dt   i
(%i8) ishow(idiff(v([i],[]),j))$
(%t8)                                v
                                      i,j
(%i9) ishow(extdiff(v([i],[]),j))$
(%t9)                             v    - v
                                   j,i    i,j
                                  -----------
                                       2
(%i10) ishow(liediff(v,w([i],[])))$
                               %3          %3
(%t10)                        v   w     + v   w
                                   i,%3    ,i  %3
(%i11) ishow(covdiff(v([i],[]),j))$
                                              %4
(%t11)                        v    - v   ichr2
                               i,j    %4      i j
(%i12) ishow(ev(%,ichr2))$
                %4 %5
(%t12) v    - (g      v   (e p       + e   p     - e p       - e    p
        i,j            %4     j %5,i    ,i  j %5      i j,%5    ,%5  i j

                                         + e p       + e   p    ))/2
                                              i %5,j    ,j  i %5
(%i13) iframe_flag:true;
(%o13)                               true
(%i14) ishow(covdiff(v([i],[]),j))$
                                             %6
(%t14)                        v    - v   icc2
                               i,j    %6     i j
(%i15) ishow(ev(%,icc2))$
                                             %6
(%t15)                        v    - v   ifc2
                               i,j    %6     i j
(%i16) ishow(radcan(ev(%,ifc2,ifc1)))$
             %6 %7                    %6 %7
(%t16) - (ifg      v   ifb       + ifg      v   ifb       - 2 v
                    %6    j %7 i             %6    i j %7      i,j

                                             %6 %7
                                        - ifg      v   ifb      )/2
                                                    %6    %7 i j
(%i17) ishow(canform(s([i,j],[])-s([j,i])))$
(%t17)                            s    - s
                                   i j    j i
(%i18) decsym(s,2,0,[sym(all)],[]);
(%o18)                               done
(%i19) ishow(canform(s([i,j],[])-s([j,i])))$
(%t19)                                 0
(%i20) ishow(canform(a([i,j],[])+a([j,i])))$
(%t20)                            a    + a
                                   j i    i j
(%i21) decsym(a,2,0,[anti(all)],[]);
(%o21)                               done
(%i22) ishow(canform(a([i,j],[])+a([j,i])))$
(%t22)                                 0

25.2 Functions and Variables for itensor

25.2.1 Managing indexed objects

Function: dispcon
dispcon (tensor_1, tensor_2, …)
dispcon (all)

Displays the contraction properties of its arguments as were given to defcon. dispcon (all) displays all the contraction properties which were defined.

Function: entertensor (name)

is a function which, by prompting, allows one to create an indexed object called name with any number of tensorial and derivative indices. Either a single index or a list of indices (which may be null) is acceptable input (see the example under covdiff).

Function: changename (old, new, expr)

will change the name of all indexed objects called old to new in expr. old may be either a symbol or a list of the form [name, m, n] in which case only those indexed objects called name with m covariant and n contravariant indices will be renamed to new.

Function: listoftens

Lists all tensors in a tensorial expression, complete with their indices. E.g.,


(%i6) ishow(a([i,j],[k])*b([u],[],v)+c([x,y],[])*d([],[])*e)$
                                         k
(%t6)                        d e c    + a    b
                                  x y    i j  u,v
(%i7) ishow(listoftens(%))$
                               k
(%t7)                        [a   , b   , c   , d]
                               i j   u,v   x y

Function: ishow (expr)

displays expr with the indexed objects in it shown having their covariant indices as subscripts and contravariant indices as superscripts. The derivative indices are displayed as subscripts, separated from the covariant indices by a comma (see the examples throughout this document).

Function: indices (expr)

Returns a list of two elements. The first is a list of the free indices in expr (those that occur only once). The second is the list of the dummy indices in expr (those that occur exactly twice) as the following example demonstrates.


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) ishow(a([i,j],[k,l],m,n)*b([k,o],[j,m,p],q,r))$
                                k l      j m p
(%t2)                          a        b
                                i j,m n  k o,q r
(%i3) indices(%);
(%o3)                 [[l, p, i, n, o, q, r], [k, j, m]]

A tensor product containing the same index more than twice is syntactically illegal. indices attempts to deal with these expressions in a reasonable manner; however, when it is called to operate upon such an illegal expression, its behavior should be considered undefined.

Function: rename
rename (expr)
rename (expr, count)

Returns an expression equivalent to expr but with the dummy indices in each term chosen from the set [%1, %2,...], if the optional second argument is omitted. Otherwise, the dummy indices are indexed beginning at the value of count. Each dummy index in a product will be different. For a sum, rename will operate upon each term in the sum resetting the counter with each term. In this way rename can serve as a tensorial simplifier. In addition, the indices will be sorted alphanumerically (if allsym is true) with respect to covariant or contravariant indices depending upon the value of flipflag. If flipflag is false then the indices will be renamed according to the order of the contravariant indices. If flipflag is true the renaming will occur according to the order of the covariant indices. It often happens that the combined effect of the two renamings will reduce an expression more than either one by itself.


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) allsym:true;
(%o2)                                true
(%i3) g([],[%4,%5])*g([],[%6,%7])*ichr2([%1,%4],[%3])*
ichr2([%2,%3],[u])*ichr2([%5,%6],[%1])*ichr2([%7,r],[%2])-
g([],[%4,%5])*g([],[%6,%7])*ichr2([%1,%2],[u])*
ichr2([%3,%5],[%1])*ichr2([%4,%6],[%3])*ichr2([%7,r],[%2]),noeval$
(%i4) expr:ishow(%)$

       %4 %5  %6 %7      %3         u          %1         %2
(%t4) g      g      ichr2      ichr2      ichr2      ichr2
                         %1 %4      %2 %3      %5 %6      %7 r

        %4 %5  %6 %7      u          %1         %3         %2
     - g      g      ichr2      ichr2      ichr2      ichr2
                          %1 %2      %3 %5      %4 %6      %7 r

(%i5) flipflag:true;
(%o5)                                true
(%i6) ishow(rename(expr))$
       %2 %5  %6 %7      %4         u          %1         %3
(%t6) g      g      ichr2      ichr2      ichr2      ichr2
                         %1 %2      %3 %4      %5 %6      %7 r

        %4 %5  %6 %7      u          %1         %3         %2
     - g      g      ichr2      ichr2      ichr2      ichr2
                          %1 %2      %3 %4      %5 %6      %7 r
(%i7) flipflag:false;
(%o7)                                false
(%i8) rename(%th(2));
(%o8)                                  0
(%i9) ishow(rename(expr))$
       %1 %2  %3 %4      %5         %6         %7        u
(%t9) g      g      ichr2      ichr2      ichr2     ichr2
                         %1 %6      %2 %3      %4 r      %5 %7

        %1 %2  %3 %4      %6         %5         %7        u
     - g      g      ichr2      ichr2      ichr2     ichr2
                          %1 %3      %2 %6      %4 r      %5 %7

Category: Package itensor · Category: Display functions

Function: show (expr)

Displays expr with the indexed objects in it shown having covariant indices as subscripts, contravariant indices as superscripts. The derivative indices are displayed as subscripts, separated from the covariant indices by a comma.

Option variable: flipflag

Default value: false

If false then the indices will be renamed according to the order of the contravariant indices, otherwise according to the order of the covariant indices.

If flipflag is false then rename forms a list of the contravariant indices as they are encountered from left to right (if true then of the covariant indices). The first dummy index in the list is renamed to %1, the next to %2, etc. Then sorting occurs after the rename-ing (see the example under rename).

Function: defcon
defcon (tensor_1)
defcon (tensor_1, tensor_2, tensor_3)

gives tensor_1 the property that the contraction of a product of tensor_1 and tensor_2 results in tensor_3 with the appropriate indices. If only one argument, tensor_1, is given, then the contraction of the product of tensor_1 with any indexed object having the appropriate indices (say my_tensor) will yield an indexed object with that name, i.e. my_tensor, and with a new set of indices reflecting the contractions performed. For example, if imetric:g, then defcon(g) will implement the raising and lowering of indices through contraction with the metric tensor. More than one defcon can be given for the same indexed object; the latest one given which applies in a particular contraction will be used. contractions is a list of those indexed objects which have been given contraction properties with defcon.

Function: remcon
remcon (tensor_1, ..., tensor_n)
remcon (all)

Removes all the contraction properties from the (tensor_1, ..., tensor_n). remcon(all) removes all contraction properties from all indexed objects.

Function: contract (expr)

Carries out the tensorial contractions in expr which may be any combination of sums and products. This function uses the information given to the defcon function. For best results, expr should be fully expanded. ratexpand is the fastest way to expand products and powers of sums if there are no variables in the denominators of the terms. The gcd switch should be false if GCD cancellations are unnecessary.

Function: indexed_tensor (tensor)

Must be executed before assigning components to a tensor for which a built in value already exists as with ichr1, ichr2, icurvature. See the example under icurvature.

Function: components (tensor, expr)

permits one to assign an indicial value to an expression expr giving the values of the components of tensor. These are automatically substituted for the tensor whenever it occurs with all of its indices. The tensor must be of the form t([...],[...]) where either list may be empty. expr can be any indexed expression involving other objects with the same free indices as tensor. When used to assign values to the metric tensor wherein the components contain dummy indices one must be careful to define these indices to avoid the generation of multiple dummy indices. Removal of this assignment is given to the function remcomps.

It is important to keep in mind that components cares only about the valence of a tensor, not about any particular index ordering. Thus assigning components to, say, x([i,-j],[]), x([-j,i],[]), or x([i],[j]) all produce the same result, namely components being assigned to a tensor named x with valence (1,1).

Components can be assigned to an indexed expression in four ways, two of which involve the use of the components command:

1) As an indexed expression. For instance:

(%i2) components(g([],[i,j]),e([],[i])*p([],[j]))$
(%i3) ishow(g([],[i,j]))$
                                      i  j
(%t3)                                e  p

2) As a matrix:


(%i5) lg:-ident(4)$lg[1,1]:1$lg;

                            [ 1   0    0    0  ]
                            [                  ]
                            [ 0  - 1   0    0  ]
(%o5)                       [                  ]
                            [ 0   0   - 1   0  ]
                            [                  ]
                            [ 0   0    0   - 1 ]

(%i6) components(g([i,j],[]),lg);
(%o6)                                done
(%i7) ishow(g([i,j],[]))$
(%t7)                                g
                                      i j
(%i8) g([1,1],[]);
(%o8)                                  1
(%i9) g([4,4],[]);
(%o9)                                 - 1

3) As a function. You can use a Maxima function to specify the components of a tensor based on its indices. For instance, the following code assigns kdelta to h if h has the same number of covariant and contravariant indices and no derivative indices, and g otherwise:


(%i4) h(l1,l2,[l3]):=if length(l1)=length(l2) and length(l3)=0
  then kdelta(l1,l2) else apply(g,append([l1,l2], l3))$
(%i5) ishow(h([i],[j]))$
                                          j
(%t5)                               kdelta
                                          i
(%i6) ishow(h([i,j],[k],l))$
                                     k
(%t6)                               g
                                     i j,l

4) Using Maxima’s pattern matching capabilities, specifically the defrule and applyb1 commands:


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) matchdeclare(l1,listp);
(%o2)                                done
(%i3) defrule(r1,m(l1,[]),(i1:idummy(),
      g([l1[1],l1[2]],[])*q([i1],[])*e([],[i1])))$

(%i4) defrule(r2,m([],l1),(i1:idummy(),
      w([],[l1[1],l1[2]])*e([i1],[])*q([],[i1])))$

(%i5) ishow(m([i,n],[])*m([],[i,m]))$

                                    i m
(%t5)                              m    m
                                         i n

(%i6) ishow(rename(applyb1(%,r1,r2)))$
                           %1  %2  %3 m
(%t6)                     e   q   w     q   e   g
                                         %1  %2  %3 n

Function: remcomps (tensor)

Unbinds all values from tensor which were assigned with the components function.

Function: showcomps (tensor)

Shows component assignments of a tensor, as made using the components command. This function can be particularly useful when a matrix is assigned to an indicial tensor using components, as demonstrated by the following example:


(%i1) load(ctensor);
(%o1)       /share/tensor/ctensor.mac
(%i2) load("itensor");
(%o2)      /share/tensor/itensor.lisp
(%i3) lg:matrix([sqrt(r/(r-2*m)),0,0,0],[0,r,0,0],
                [0,0,sin(theta)*r,0],[0,0,0,sqrt((r-2*m)/r)]);
               [         r                                     ]
               [ sqrt(-------)  0       0              0       ]
               [      r - 2 m                                  ]
               [                                               ]
               [       0        r       0              0       ]
(%o3)          [                                               ]
               [       0        0  r sin(theta)        0       ]
               [                                               ]
               [                                      r - 2 m  ]
               [       0        0       0        sqrt(-------) ]
               [                                         r     ]
(%i4) components(g([i,j],[]),lg);
(%o4)                                done
(%i5) showcomps(g([i,j],[]));
                  [         r                                     ]
                  [ sqrt(-------)  0       0              0       ]
                  [      r - 2 m                                  ]
                  [                                               ]
                  [       0        r       0              0       ]
(%t5)      g    = [                                               ]
            i j   [       0        0  r sin(theta)        0       ]
                  [                                               ]
                  [                                      r - 2 m  ]
                  [       0        0       0        sqrt(-------) ]
                  [                                         r     ]
(%o5)                                false

The showcomps command can also display components of a tensor of rank higher than 2.

Function: idummy ()

Increments icounter and returns as its value an index of the form %n where n is a positive integer. This guarantees that dummy indices which are needed in forming expressions will not conflict with indices already in use (see the example under indices).

Option variable: idummyx

Default value: %

Is the prefix for dummy indices (see the example under indices).

Option variable: icounter

Default value: 1

Determines the numerical suffix to be used in generating the next dummy index in the tensor package. The prefix is determined by the option idummy (default: %).

Function: kdelta (L1, L2)

is the generalized Kronecker delta function defined in the itensor package with L1 the list of covariant indices and L2 the list of contravariant indices. kdelta([i],[j]) returns the ordinary Kronecker delta. The command ev(expr,kdelta) causes the evaluation of an expression containing kdelta([],[]) to the dimension of the manifold.

In what amounts to an abuse of this notation, itensor also allows kdelta to have 2 covariant and no contravariant, or 2 contravariant and no covariant indices, in effect providing a co(ntra)variant "unit matrix" capability. This is strictly considered a programming aid and not meant to imply that kdelta([i,j],[]) is a valid tensorial object.

Function: kdels (L1, L2)

Symmetrized Kronecker delta, used in some calculations. For instance:


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) kdelta([1,2],[2,1]);
(%o2)                                 - 1
(%i3) kdels([1,2],[2,1]);
(%o3)                                  1
(%i4) ishow(kdelta([a,b],[c,d]))$
                             c       d         d       c
(%t4)                  kdelta  kdelta  - kdelta  kdelta
                             a       b         a       b
(%i4) ishow(kdels([a,b],[c,d]))$
                             c       d         d       c
(%t4)                  kdelta  kdelta  + kdelta  kdelta
                             a       b         a       b

Function: levi_civita (L)

is the permutation (or Levi-Civita) tensor which yields 1 if the list L consists of an even permutation of integers, -1 if it consists of an odd permutation, and 0 if some indices in L are repeated.

Function: lc2kdt (expr)

Simplifies expressions containing the Levi-Civita symbol, converting these to Kronecker-delta expressions when possible. The main difference between this function and simply evaluating the Levi-Civita symbol is that direct evaluation often results in Kronecker expressions containing numerical indices. This is often undesirable as it prevents further simplification. The lc2kdt function avoids this problem, yielding expressions that are more easily simplified with rename or contract.


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) expr:ishow('levi_civita([],[i,j])
                 *'levi_civita([k,l],[])*a([j],[k]))$
                                  i j  k
(%t2)                  levi_civita    a  levi_civita
                                       j            k l
(%i3) ishow(ev(expr,levi_civita))$
                                  i j  k       1 2
(%t3)                       kdelta    a  kdelta
                                  1 2  j       k l
(%i4) ishow(ev(%,kdelta))$
             i       j         j       i   k
(%t4) (kdelta  kdelta  - kdelta  kdelta ) a
             1       2         1       2   j

                               1       2         2       1
                        (kdelta  kdelta  - kdelta  kdelta )
                               k       l         k       l
(%i5) ishow(lc2kdt(expr))$
                     k       i       j    k       j       i
(%t5)               a  kdelta  kdelta  - a  kdelta  kdelta
                     j       k       l    j       k       l
(%i6) ishow(contract(expand(%)))$
                                 i           i
(%t6)                           a  - a kdelta
                                 l           l

The lc2kdt function sometimes makes use of the metric tensor. If the metric tensor was not defined previously with imetric, this results in an error.


(%i7) expr:ishow('levi_civita([],[i,j])
                 *'levi_civita([],[k,l])*a([j,k],[]))$

                                 i j            k l
(%t7)                 levi_civita    levi_civita    a
                                                     j k

(%i8) ishow(lc2kdt(expr))$
Maxima encountered a Lisp error:

 Error in $IMETRIC [or a callee]:
 $IMETRIC [or a callee] requires less than two arguments.

Automatically continuing.
To reenable the Lisp debugger set *debugger-hook* to nil.
(%i9) imetric(g);
(%o9)                                done
(%i10) ishow(lc2kdt(expr))$
         %3 i       k   %4 j       l     %3 i       l   %4 j
(%t10) (g     kdelta   g     kdelta   - g     kdelta   g    
                    %3             %4               %3
              k
        kdelta  ) a
              %4   j k
(%i11) ishow(contract(expand(%)))$
                                  l i    l i  j
(%t11)                           a    - g    a
                                              j

Function: lc_l

Simplification rule used for expressions containing the unevaluated Levi-Civita symbol (levi_civita). Along with `lc_u', it can be used to simplify many expressions more efficiently than the evaluation of levi_civita. For example:


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) el1:ishow('levi_civita([i,j,k],[])*a([],[i])*a([],[j]))$
                             i  j
(%t2)                       a  a  levi_civita
                                             i j k
(%i3) el2:ishow('levi_civita([],[i,j,k])*a([i])*a([j]))$
                                       i j k
(%t3)                       levi_civita      a  a
                                              i  j
(%i4) canform(contract(expand(applyb1(el1,lc_l,lc_u))));
(%t4)                                  0
(%i5) canform(contract(expand(applyb1(el2,lc_l,lc_u))));
(%t5)                                  0

Function: lc_u

Simplification rule used for expressions containing the unevaluated Levi-Civita symbol (levi_civita). Along with lc_u, it can be used to simplify many expressions more efficiently than the evaluation of levi_civita. For details, see lc_l.

Function: canten (expr)

Simplifies expr by renaming (see rename) and permuting dummy indices. rename is restricted to sums of tensor products in which no derivatives are present. As such it is limited and should only be used if canform is not capable of carrying out the required simplification.

The canten function returns a mathematically correct result only if its argument is an expression that is fully symmetric in its indices. For this reason, canten returns an error if allsym is not set to true.

Function: concan (expr)

Similar to canten but also performs index contraction.

25.2.2 Tensor symmetries

Option variable: allsym

Default value: false

If true then all indexed objects are assumed symmetric in all of their covariant and contravariant indices. If false then no symmetries of any kind are assumed in these indices. Derivative indices are always taken to be symmetric unless iframe_flag is set to true.

Function: decsym (tensor, m, n, [cov_1, cov_2, ...], [contr_1, contr_2, ...])

Declares symmetry properties for tensor of m covariant and n contravariant indices. The cov_i and contr_i are pseudofunctions expressing symmetry relations among the covariant and contravariant indices respectively. These are of the form symoper(index_1, index_2,...) where symoper is one of sym, anti or cyc and the index_i are integers indicating the position of the index in the tensor. This will declare tensor to be symmetric, antisymmetric or cyclic respectively in the index_i. symoper(all) is also an allowable form which indicates all indices obey the symmetry condition. For example, given an object b with 5 covariant indices, decsym(b,5,3,[sym(1,2),anti(3,4)],[cyc(all)]) declares b symmetric in its first and second and antisymmetric in its third and fourth covariant indices, and cyclic in all of its contravariant indices. Either list of symmetry declarations may be null. The function which performs the simplifications is canform as the example below illustrates.


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) expr:contract( expand( a([i1, j1, k1], [])
           *kdels([i, j, k], [i1, j1, k1])))$
(%i3) ishow(expr)$

(%t3)         a      + a      + a      + a      + a      + a
               k j i    k i j    j k i    j i k    i k j    i j k

(%i4) decsym(a,3,0,[sym(all)],[]);
(%o4)                                done
(%i5) ishow(canform(expr))$
(%t5)                              6 a
                                      i j k
(%i6) remsym(a,3,0);
(%o6)                                done
(%i7) decsym(a,3,0,[anti(all)],[]);
(%o7)                                done
(%i8) ishow(canform(expr))$
(%t8)                                  0
(%i9) remsym(a,3,0);
(%o9)                                done
(%i10) decsym(a,3,0,[cyc(all)],[]);
(%o10)                               done
(%i11) ishow(canform(expr))$
(%t11)                        3 a      + 3 a
                                 i k j      i j k
(%i12) dispsym(a,3,0);
(%o12)                     [[cyc, [[1, 2, 3]], []]]

Function: remsym (tensor, m, n)

Removes all symmetry properties from tensor which has m covariant indices and n contravariant indices.

Function: canform
canform (expr)
canform (expr, rename)

Simplifies expr by renaming dummy indices and reordering all indices as dictated by symmetry conditions imposed on them. If allsym is true then all indices are assumed symmetric, otherwise symmetry information provided by decsym declarations will be used. The dummy indices are renamed in the same manner as in the rename function. When canform is applied to a large expression the calculation may take a considerable amount of time. This time can be shortened by calling rename on the expression first. Also see the example under decsym. Note: canform may not be able to reduce an expression completely to its simplest form although it will always return a mathematically correct result.

The optional second parameter rename, if set to false, suppresses renaming.

25.2.3 Indicial tensor calculus

Function: diff (expr, v_1, [n_1, [v_2, n_2] ...])

is the usual Maxima differentiation function which has been expanded in its abilities for itensor. It takes the derivative of expr with respect to v_1 n_1 times, with respect to v_2 n_2 times, etc. For the tensor package, the function has been modified so that the v_i may be integers from 1 up to the value of the variable dim. This will cause the differentiation to be carried out with respect to the v_ith member of the list vect_coords. If vect_coords is bound to an atomic variable, then that variable subscripted by v_i will be used for the variable of differentiation. This permits an array of coordinate names or subscripted names like x[1], x[2], ... to be used.

A further extension adds the ability to diff to compute derivatives with respect to an indexed variable. In particular, the tensor package knows how to differentiate expressions containing combinations of the metric tensor and its derivatives with respect to the metric tensor and its first and second derivatives. This capability is particularly useful when considering Lagrangian formulations of a gravitational theory, allowing one to derive the Einstein tensor and field equations from the action principle.

Function: idiff (expr, v_1, [n_1, [v_2, n_2] ...])

Indicial differentiation. Unlike diff, which differentiates with respect to an independent variable, idiff) can be used to differentiate with respect to a coordinate. For an indexed object, this amounts to appending the v_i as derivative indices. Subsequently, derivative indices will be sorted, unless iframe_flag is set to true.

idiff can also differentiate the determinant of the metric tensor. Thus, if imetric has been bound to G then idiff(determinant(g),k) will return 2 * determinant(g) * ichr2([%i,k],[%i]) where the dummy index %i is chosen appropriately.

Function: liediff (v, ten)

Computes the Lie-derivative of the tensorial expression ten with respect to the vector field v. ten should be any indexed tensor expression; v should be the name (without indices) of a vector field. For example:


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) ishow(liediff(v,a([i,j],[])*b([],[k],l)))$
       k    %2            %2          %2
(%t2) b   (v   a       + v   a     + v   a    )
       ,l       i j,%2    ,j  i %2    ,i  %2 j

                          %1  k        %1  k      %1  k
                      + (v   b      - b   v    + v   b   ) a
                              ,%1 l    ,l  ,%1    ,l  ,%1   i j

Function: rediff (ten)

Evaluates all occurrences of the idiff command in the tensorial expression ten.

Function: undiff (expr)

Returns an expression equivalent to expr but with all derivatives of indexed objects replaced by the noun form of the idiff function. Its arguments would yield that indexed object if the differentiation were carried out. This is useful when it is desired to replace a differentiated indexed object with some function definition resulting in expr and then carry out the differentiation by saying ev(expr, idiff).

Function: evundiff (expr)

Equivalent to the execution of undiff, followed by ev and rediff.

The point of this operation is to easily evalute expressions that cannot be directly evaluated in derivative form. For instance, the following causes an error:

(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) icurvature([i,j,k],[l],m);
Maxima encountered a Lisp error:

 Error in $ICURVATURE [or a callee]:
 $ICURVATURE [or a callee] requires less than three arguments.

Automatically continuing.
To reenable the Lisp debugger set *debugger-hook* to nil.

However, if icurvature is entered in noun form, it can be evaluated using evundiff:

(%i3) ishow('icurvature([i,j,k],[l],m))$
                                         l
(%t3)                          icurvature
                                         i j k,m
(%i4) ishow(evundiff(%))$
             l              l         %1           l           %1
(%t4) - ichr2        - ichr2     ichr2      - ichr2       ichr2
             i k,j m        %1 j      i k,m        %1 j,m      i k

             l              l         %1           l           %1
      + ichr2        + ichr2     ichr2      + ichr2       ichr2
             i j,k m        %1 k      i j,m        %1 k,m      i j

Note: In earlier versions of Maxima, derivative forms of the Christoffel-symbols also could not be evaluated. This has been fixed now, so evundiff is no longer necessary for expressions like this:

(%i5) imetric(g);
(%o5)                                done
(%i6) ishow(ichr2([i,j],[k],l))$
       k %3
      g     (g         - g         + g        )
              j %3,i l    i j,%3 l    i %3,j l
(%t6) -----------------------------------------
                          2

                         k %3
                        g     (g       - g       + g      )
                         ,l     j %3,i    i j,%3    i %3,j
                      + -----------------------------------
                                         2

Function: flush (expr, tensor_1, tensor_2, ...)

Set to zero, in expr, all occurrences of the tensor_i that have no derivative indices.

Function: flushd (expr, tensor_1, tensor_2, ...)

Set to zero, in expr, all occurrences of the tensor_i that have derivative indices.

Function: flushnd (expr, tensor, n)

Set to zero, in expr, all occurrences of the differentiated object tensor that have n or more derivative indices as the following example demonstrates.


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) ishow(a([i],[J,r],k,r)+a([i],[j,r,s],k,r,s))$
                                J r      j r s
(%t2)                          a      + a
                                i,k r    i,k r s
(%i3) ishow(flushnd(%,a,3))$
                                     J r
(%t3)                               a
                                     i,k r

Function: coord (tensor_1, tensor_2, ...)

Gives tensor_i the coordinate differentiation property that the derivative of contravariant vector whose name is one of the tensor_i yields a Kronecker delta. For example, if coord(x) has been done then idiff(x([],[i]),j) gives kdelta([i],[j]). coord is a list of all indexed objects having this property.

Function: remcoord
remcoord (tensor_1, tensor_2, ...)
remcoord (all)

Removes the coordinate differentiation property from the tensor_i that was established by the function coord. remcoord(all) removes this property from all indexed objects.

Function: makebox (expr)

Display expr in the same manner as show; however, any tensor d’Alembertian occurring in expr will be indicated using the symbol []. For example, []p([m],[n]) represents g([],[i,j])*p([m],[n],i,j).

Function: conmetderiv (expr, tensor)

Simplifies expressions containing ordinary derivatives of both covariant and contravariant forms of the metric tensor (the current restriction). For example, conmetderiv can relate the derivative of the contravariant metric tensor with the Christoffel symbols as seen from the following:


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) ishow(g([],[a,b],c))$
                                      a b
(%t2)                                g
                                      ,c
(%i3) ishow(conmetderiv(%,g))$
                         %1 b      a       %1 a      b
(%t3)                 - g     ichr2     - g     ichr2
                                   %1 c              %1 c

Function: simpmetderiv
simpmetderiv (expr)
simpmetderiv (expr[, stop])

Simplifies expressions containing products of the derivatives of the metric tensor. Specifically, simpmetderiv recognizes two identities:


   ab        ab           ab                 a
  g   g   + g   g     = (g   g  )   = (kdelta )   = 0
   ,d  bc        bc,d         bc ,d          c ,d

hence


   ab          ab
  g   g   = - g   g
   ,d  bc          bc,d

and


  ab          ab
 g   g     = g   g
  ,j  ab,i    ,i  ab,j

which follows from the symmetries of the Christoffel symbols.

The simpmetderiv function takes one optional parameter which, when present, causes the function to stop after the first successful substitution in a product expression. The simpmetderiv function also makes use of the global variable flipflag which determines how to apply a “canonical” ordering to the product indices.

Put together, these capabilities can be used to achieve powerful simplifications that are difficult or impossible to accomplish otherwise. This is demonstrated through the following example that explicitly uses the partial simplification features of simpmetderiv to obtain a contractible expression:


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) imetric(g);
(%o2)                                done
(%i3) ishow(g([],[a,b])*g([],[b,c])*g([a,b],[],d)*g([b,c],[],e))$
                             a b  b c
(%t3)                       g    g    g      g
                                       a b,d  b c,e
(%i4) ishow(canform(%))$

errexp1 has improper indices
 -- an error.  Quitting.  To debug this try debugmode(true);
(%i5) ishow(simpmetderiv(%))$
                             a b  b c
(%t5)                       g    g    g      g
                                       a b,d  b c,e
(%i6) flipflag:not flipflag;
(%o6)                                true
(%i7) ishow(simpmetderiv(%th(2)))$
                               a b  b c
(%t7)                         g    g    g    g
                               ,d   ,e   a b  b c
(%i8) flipflag:not flipflag;
(%o8)                                false
(%i9) ishow(simpmetderiv(%th(2),stop))$
                               a b  b c
(%t9)                       - g    g    g      g
                                    ,e   a b,d  b c
(%i10) ishow(contract(%))$
                                    b c
(%t10)                           - g    g
                                    ,e   c b,d

See also weyl.dem for an example that uses simpmetderiv and conmetderiv together to simplify contractions of the Weyl tensor.

Function: flush1deriv (expr, tensor)

Set to zero, in expr, all occurrences of tensor that have exactly one derivative index.

25.2.4 Tensors in curved spaces

Function: imetric (g)

System variable: imetric

Specifies the metric by assigning the variable imetric:g in addition, the contraction properties of the metric g are set up by executing the commands defcon(g), defcon(g, g, kdelta). The variable imetric (unbound by default), is bound to the metric, assigned by the imetric(g) command.

Function: idim (n)

Sets the dimensions of the metric. Also initializes the antisymmetry properties of the Levi-Civita symbols for the given dimension.

Function: ichr1 ([i, j, k])

Yields the Christoffel symbol of the first kind via the definition

       (g      + g      - g     )/2 .
         ik,j     jk,i     ij,k

To evaluate the Christoffel symbols for a particular metric, the variable imetric must be assigned a name as in the example under chr2.

Function: ichr2 ([i, j], [k])

Yields the Christoffel symbol of the second kind defined by the relation

                       ks
   ichr2([i,j],[k]) = g    (g      + g      - g     )/2
                             is,j     js,i     ij,s

Function: icurvature ([i, j, k], [h])

Yields the Riemann curvature tensor in terms of the Christoffel symbols of the second kind (ichr2). The following notation is used:

            h             h            h         %1         h
  icurvature     = - ichr2      - ichr2     ichr2    + ichr2
            i j k         i k,j        %1 j      i k        i j,k
                            h          %1
                     + ichr2      ichr2
                            %1 k       i j

Function: covdiff (expr, v_1, v_2, ...)

Yields the covariant derivative of expr with respect to the variables v_i in terms of the Christoffel symbols of the second kind (ichr2). In order to evaluate these, one should use ev(expr,ichr2).


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) entertensor()$
Enter tensor name: a;
Enter a list of the covariant indices: [i,j];
Enter a list of the contravariant indices: [k];
Enter a list of the derivative indices: [];
                                      k
(%t2)                                a
                                      i j
(%i3) ishow(covdiff(%,s))$
             k         %1     k         %1     k
(%t3)     - a     ichr2    - a     ichr2    + a
             i %1      j s    %1 j      i s    i j,s

             k     %1
      + ichr2     a
             %1 s  i j
(%i4) imetric:g;
(%o4)                                  g
(%i5) ishow(ev(%th(2),ichr2))$
         %1 %4  k
        g      a     (g       - g       + g      )
                i %1   s %4,j    j s,%4    j %4,s
(%t5) - ------------------------------------------
                            2

    %1 %3  k
   g      a     (g       - g       + g      )
           %1 j   s %3,i    i s,%3    i %3,s
 - ------------------------------------------
                       2
    k %2  %1
   g     a    (g        - g        + g       )
          i j   s %2,%1    %1 s,%2    %1 %2,s     k
 + ------------------------------------------- + a
                        2                         i j,s

(%i6)

Function: lorentz_gauge (expr)

Imposes the Lorentz condition by substituting 0 for all indexed objects in expr that have a derivative index identical to a contravariant index.

Function: igeodesic_coords (expr, name)

Causes undifferentiated Christoffel symbols and first derivatives of the metric tensor vanish in expr. The name in the `igeodesic_coords' function refers to the metric name (if it appears in expr) while the connection coefficients must be called with the names ichr1 and/or ichr2. The following example demonstrates the verification of the cyclic identity satisfied by the Riemann curvature tensor using the igeodesic_coords function.


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) ishow(icurvature([r,s,t],[u]))$
             u            u         %1         u     
(%t2) - ichr2      - ichr2     ichr2    + ichr2      
             r t,s        %1 s      r t        r s,t 

                                              u         %1
                                       + ichr2     ichr2
                                              %1 t      r s
(%i3) ishow(igeodesic_coords(%,ichr2))$
                                 u            u
(%t3)                       ichr2      - ichr2
                                 r s,t        r t,s
(%i4) ishow(igeodesic_coords(icurvature([r,s,t],[u]),ichr2)+
            igeodesic_coords(icurvature([s,t,r],[u]),ichr2)+
            igeodesic_coords(icurvature([t,r,s],[u]),ichr2))$
             u            u            u            u
(%t4) - ichr2      + ichr2      + ichr2      - ichr2
             t s,r        t r,s        s t,r        s r,t

                                             u            u
                                      - ichr2      + ichr2
                                             r t,s        r s,t
(%i5) canform(%);
(%o5)                                  0

25.2.5 Moving frames

Maxima now has the ability to perform calculations using moving frames. These can be orthonormal frames (tetrads, vielbeins) or an arbitrary frame.

To use frames, you must first set iframe_flag to true. This causes the Christoffel-symbols, ichr1 and ichr2, to be replaced by the more general frame connection coefficients icc1 and icc2 in calculations. Speficially, the behavior of covdiff and icurvature is changed.

The frame is defined by two tensors: the inverse frame field (ifri, the dual basis tetrad), and the frame metric ifg. The frame metric is the identity matrix for orthonormal frames, or the Lorentz metric for orthonormal frames in Minkowski spacetime. The inverse frame field defines the frame base (unit vectors). Contraction properties are defined for the frame field and the frame metric.

When iframe_flag is true, many itensor expressions use the frame metric ifg instead of the metric defined by imetric for raising and lowerind indices.

IMPORTANT: Setting the variable iframe_flag to true does NOT undefine the contraction properties of a metric defined by a call to defcon or imetric. If a frame field is used, it is best to define the metric by assigning its name to the variable imetric and NOT invoke the imetric function.

Maxima uses these two tensors to define the frame coefficients (ifc1 and ifc2) which form part of the connection coefficients (icc1 and icc2), as the following example demonstrates:


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) iframe_flag:true;
(%o2)                                true
(%i3) ishow(covdiff(v([],[i]),j))$
                               i        i     %1
(%t3)                         v   + icc2     v
                               ,j       %1 j
(%i4) ishow(ev(%,icc2))$
                               %1     i       i
(%t4)                         v   ifc2     + v
                                      %1 j    ,j
(%i5) ishow(ev(%,ifc2))$
                          %1    i %2                i
(%t5)                    v   ifg     ifc1        + v
                                         %1 j %2    ,j
(%i6) ishow(ev(%,ifc1))$

            %1    i %2
           v   ifg     (ifb        - ifb        + ifb       )
                           j %2 %1      %2 %1 j      %1 j %2     i
(%t6)      -------------------------------------------------- + v
                                   2                             ,j

(%i7) ishow(ifb([a,b,c]))$
                                                   %3    %4
(%t7)               (ifri        - ifri       ) ifr   ifr
                         a %3,%4       a %4,%3     b     c

An alternate method is used to compute the frame bracket (ifb) if the iframe_bracket_form flag is set to false:


(%i8) block([iframe_bracket_form:false],ishow(ifb([a,b,c])))$
                                %6    %5        %5      %6
(%t8)              ifri     (ifr   ifr     - ifr     ifr  )
                       a %5     b     c,%6      b,%6    c

Function: iframes ()

Since in this version of Maxima, contraction identities for ifr and ifri are always defined, as is the frame bracket (ifb), this function does nothing.

Variable: ifb

The frame bracket. The contribution of the frame metric to the connection coefficients is expressed using the frame bracket:


          - ifb      + ifb      + ifb
               c a b      b c a      a b c
ifc1    = --------------------------------
    abc                  2

The frame bracket itself is defined in terms of the frame field and frame metric. Two alternate methods of computation are used depending on the value of frame_bracket_form. If true (the default) or if the itorsion_flag is true:


          d      e                                      f
ifb =  ifr    ifr   (ifri      - ifri      - ifri    itr   )
   abc    b      c       a d,e       a e,d       a f    d e

Otherwise:


             e      d        d      e
ifb    = (ifr    ifr    - ifr    ifr   ) ifri
   abc       b      c,e      b,e    c        a d

Variable: icc1

Connection coefficients of the first kind. In itensor, defined as


icc1    = ichr1    - ikt1    - inmc1
    abc        abc       abc        abc

In this expression, if iframe_flag is true, the Christoffel-symbol ichr1 is replaced with the frame connection coefficient ifc1. If itorsion_flag is false, ikt1 will be omitted. It is also omitted if a frame base is used, as the torsion is already calculated as part of the frame bracket. Lastly, of inonmet_flag is false, inmc1 will not be present.

Variable: icc2

Connection coefficients of the second kind. In itensor, defined as


    c         c        c         c
icc2   = ichr2   - ikt2   - inmc2
    ab        ab       ab        ab

In this expression, if iframe_flag is true, the Christoffel-symbol ichr2 is replaced with the frame connection coefficient ifc2. If itorsion_flag is false, ikt2 will be omitted. It is also omitted if a frame base is used, as the torsion is already calculated as part of the frame bracket. Lastly, of inonmet_flag is false, inmc2 will not be present.

Variable: ifc1

Frame coefficient of the first kind (also known as Ricci-rotation coefficients.) This tensor represents the contribution of the frame metric to the connection coefficient of the first kind. Defined as:


          - ifb      + ifb      + ifb
               c a b      b c a      a b c
ifc1    = --------------------------------
    abc                   2

Variable: ifc2

Frame coefficient of the second kind. This tensor represents the contribution of the frame metric to the connection coefficient of the second kind. Defined as a permutation of the frame bracket (ifb) with the appropriate indices raised and lowered as necessary:


    c       cd
ifc2   = ifg   ifc1
    ab             abd

Variable: ifr

The frame field. Contracts with the inverse frame field (ifri) to form the frame metric (ifg).

Variable: ifri

The inverse frame field. Specifies the frame base (dual basis vectors). Along with the frame metric, it forms the basis of all calculations based on frames.

Variable: ifg

The frame metric. Defaults to kdelta, but can be changed using components.

Variable: ifgi

The inverse frame metric. Contracts with the frame metric (ifg) to kdelta.

Option variable: iframe_bracket_form

Default value: true

Specifies how the frame bracket (ifb) is computed.

25.2.6 Torsion and nonmetricity

Maxima can now take into account torsion and nonmetricity. When the flag itorsion_flag is set to true, the contribution of torsion is added to the connection coefficients. Similarly, when the flag inonmet_flag is true, nonmetricity components are included.

Variable: inm

The nonmetricity vector. Conformal nonmetricity is defined through the covariant derivative of the metric tensor. Normally zero, the metric tensor’s covariant derivative will evaluate to the following when inonmet_flag is set to true:


g     =- g  inm
 ij;k     ij   k

Variable: inmc1

Covariant permutation of the nonmetricity vector components. Defined as


           g   inm  - inm  g   - g   inm
            ab    c      a  bc    ac    b
inmc1    = ------------------------------
     abc                 2

(Substitute ifg in place of g if a frame metric is used.)

Variable: inmc2

Contravariant permutation of the nonmetricity vector components. Used in the connection coefficients if inonmet_flag is true. Defined as:


                      c         c         cd
          -inm  kdelta  - kdelta  inm  + g   inm  g
     c        a       b         a    b          d  ab
inmc2   = -------------------------------------------
     ab                        2

(Substitute ifg in place of g if a frame metric is used.)

Variable: ikt1

Covariant permutation of the torsion tensor (also known as contorsion). Defined as:


                  d           d       d
          -g   itr  - g    itr   - itr   g
            ad    cb    bd    ca      ab  cd
ikt1    = ----------------------------------
    abc                   2

(Substitute ifg in place of g if a frame metric is used.)

Variable: ikt2

Contravariant permutation of the torsion tensor (also known as contorsion). Defined as:


    c     cd
ikt2   = g   ikt1
    ab           abd

(Substitute ifg in place of g if a frame metric is used.)

Variable: itr

The torsion tensor. For a metric with torsion, repeated covariant differentiation on a scalar function will not commute, as demonstrated by the following example:


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) imetric:g;
(%o2)                                  g
(%i3) covdiff( covdiff( f( [], []), i), j)
                      - covdiff( covdiff( f( [], []), j), i)$
(%i4) ishow(%)$
                                   %4              %2
(%t4)                    f    ichr2    - f    ichr2
                          ,%4      j i    ,%2      i j
(%i5) canform(%);
(%o5)                                  0
(%i6) itorsion_flag:true;
(%o6)                                true
(%i7) covdiff( covdiff( f( [], []), i), j)
                      - covdiff( covdiff( f( [], []), j), i)$
(%i8) ishow(%)$
                           %8             %6
(%t8)             f    icc2    - f    icc2    - f     + f
                   ,%8     j i    ,%6     i j    ,j i    ,i j
(%i9) ishow(canform(%))$
                                   %1             %1
(%t9)                     f    icc2    - f    icc2
                           ,%1     j i    ,%1     i j
(%i10) ishow(canform(ev(%,icc2)))$
                                   %1             %1
(%t10)                    f    ikt2    - f    ikt2
                           ,%1     i j    ,%1     j i
(%i11) ishow(canform(ev(%,ikt2)))$
                      %2 %1                    %2 %1
(%t11)          f    g      ikt1       - f    g      ikt1
                 ,%2            i j %1    ,%2            j i %1
(%i12) ishow(factor(canform(rename(expand(ev(%,ikt1))))))$
                           %3 %2            %1       %1
                     f    g      g      (itr    - itr   )
                      ,%3         %2 %1     j i      i j
(%t12)               ------------------------------------
                                      2
(%i13) decsym(itr,2,1,[anti(all)],[]);
(%o13)                               done
(%i14) defcon(g,g,kdelta);
(%o14)                               done
(%i15) subst(g,nounify(g),%th(3))$
(%i16) ishow(canform(contract(%)))$
                                           %1
(%t16)                           - f    itr
                                    ,%1    i j

Category: Package itensor · Category: Operators

25.2.7 Exterior algebra

The itensor package can perform operations on totally antisymmetric covariant tensor fields. A totally antisymmetric tensor field of rank (0,L) corresponds with a differential L-form. On these objects, a multiplication operation known as the exterior product, or wedge product, is defined.

Unfortunately, not all authors agree on the definition of the wedge product. Some authors prefer a definition that corresponds with the notion of antisymmetrization: in these works, the wedge product of two vector fields, for instance, would be defined as

            a a  - a a
             i j    j i
 a  /\ a  = -----------
  i     j        2

More generally, the product of a p-form and a q-form would be defined as

                       1     k1..kp l1..lq
A       /\ B       = ------ D              A       B
 i1..ip     j1..jq   (p+q)!  i1..ip j1..jq  k1..kp  l1..lq

where D stands for the Kronecker-delta.

Other authors, however, prefer a “geometric” definition that corresponds with the notion of the volume element:

a  /\ a  = a a  - a a
 i     j    i j    j i

and, in the general case

                       1    k1..kp l1..lq
A       /\ B       = ----- D              A       B
 i1..ip     j1..jq   p! q!  i1..ip j1..jq  k1..kp  l1..lq

Since itensor is a tensor algebra package, the first of these two definitions appears to be the more natural one. Many applications, however, utilize the second definition. To resolve this dilemma, a flag has been implemented that controls the behavior of the wedge product: if igeowedge_flag is false (the default), the first, "tensorial" definition is used, otherwise the second, "geometric" definition will be applied.

Operator: ~

The wedge product operator is denoted by the tilde ~. This is a binary operator. Its arguments should be expressions involving scalars, covariant tensors of rank one, or covariant tensors of rank l that have been declared antisymmetric in all covariant indices.

The behavior of the wedge product operator is controlled by the igeowedge_flag flag, as in the following example:

(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) ishow(a([i])~b([j]))$
                                 a  b  - b  a
                                  i  j    i  j
(%t2)                            -------------
                                       2
(%i3) decsym(a,2,0,[anti(all)],[]);
(%o3)                                done
(%i4) ishow(a([i,j])~b([k]))$
                          a    b  + b  a    - a    b
                           i j  k    i  j k    i k  j
(%t4)                     ---------------------------
                                       3
(%i5) igeowedge_flag:true;
(%o5)                                true
(%i6) ishow(a([i])~b([j]))$
(%t6)                            a  b  - b  a
                                  i  j    i  j
(%i7) ishow(a([i,j])~b([k]))$
(%t7)                     a    b  + b  a    - a    b
                           i j  k    i  j k    i k  j

Operator: |

The vertical bar | denotes the "contraction with a vector" binary operation. When a totally antisymmetric covariant tensor is contracted with a contravariant vector, the result is the same regardless which index was used for the contraction. Thus, it is possible to define the contraction operation in an index-free manner.

In the itensor package, contraction with a vector is always carried out with respect to the first index in the literal sorting order. This ensures better simplification of expressions involving the | operator. For instance:

(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) decsym(a,2,0,[anti(all)],[]);
(%o2)                                done
(%i3) ishow(a([i,j],[])|v)$
                                    %1
(%t3)                              v   a
                                        %1 j
(%i4) ishow(a([j,i],[])|v)$
                                     %1
(%t4)                             - v   a
                                         %1 j

Note that it is essential that the tensors used with the | operator be declared totally antisymmetric in their covariant indices. Otherwise, the results will be incorrect.

Category: Package itensor · Category: Operators

Function: extdiff (expr, i)

Computes the exterior derivative of expr with respect to the index i. The exterior derivative is formally defined as the wedge product of the partial derivative operator and a differential form. As such, this operation is also controlled by the setting of igeowedge_flag. For instance:

(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) ishow(extdiff(v([i]),j))$
                                  v    - v
                                   j,i    i,j
(%t2)                             -----------
                                       2
(%i3) decsym(a,2,0,[anti(all)],[]);
(%o3)                                done
(%i4) ishow(extdiff(a([i,j]),k))$
                           a      - a      + a
                            j k,i    i k,j    i j,k
(%t4)                      ------------------------
                                      3
(%i5) igeowedge_flag:true;
(%o5)                                true
(%i6) ishow(extdiff(v([i]),j))$
(%t6)                             v    - v
                                   j,i    i,j
(%i7) ishow(extdiff(a([i,j]),k))$
(%t7)                    - (a      - a      + a     )
                             k j,i    k i,j    j i,k

Function: hodge (expr)

Compute the Hodge-dual of expr. For instance:


(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) imetric(g);
(%o2)                            done
(%i3) idim(4);
(%o3)                            done
(%i4) icounter:100;
(%o4)                             100
(%i5) decsym(A,3,0,[anti(all)],[])$

(%i6) ishow(A([i,j,k],[]))$
(%t6)                           A
                                 i j k
(%i7) ishow(canform(hodge(%)))$
                          %1 %2 %3 %4
               levi_civita            g        A
                                       %1 %102  %2 %3 %4
(%t7)          -----------------------------------------
                                   6
(%i8) ishow(canform(hodge(%)))$
                 %1 %2 %3 %8            %4 %5 %6 %7
(%t8) levi_civita            levi_civita            g       
                                                     %1 %106
                             g        g        g      A         /6
                              %2 %107  %3 %108  %4 %8  %5 %6 %7
(%i9) lc2kdt(%)$

(%i10) %,kdelta$

(%i11) ishow(canform(contract(expand(%))))$
(%t11)                     - A
                              %106 %107 %108

Option variable: igeowedge_flag

Default value: false

Controls the behavior of the wedge product and exterior derivative. When set to false (the default), the notion of differential forms will correspond with that of a totally antisymmetric covariant tensor field. When set to true, differential forms will agree with the notion of the volume element.

Category: Package itensor · Category: TeX output

25.2.8 Exporting TeX expressions

The itensor package provides limited support for exporting tensor expressions to TeX. Since itensor expressions appear as function calls, the regular Maxima tex command will not produce the expected output. You can try instead the tentex command, which attempts to translate tensor expressions into appropriately indexed TeX objects.

Function: tentex (expr)

To use the tentex function, you must first load tentex, as in the following example:

(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) load(tentex);
(%o2)       /share/tensor/tentex.lisp
(%i3) idummyx:m;
(%o3)                                  m
(%i4) ishow(icurvature([j,k,l],[i]))$
            m1       i           m1       i           i
(%t4)  ichr2    ichr2     - ichr2    ichr2     - ichr2
            j k      m1 l        j l      m1 k        j l,k

                                                      i
                                               + ichr2
                                                      j k,l
(%i5) tentex(%)$
$$\Gamma_{j\,k}^{m_1}\,\Gamma_{l\,m_1}^{i}-\Gamma_{j\,l}^{m_1}\,
 \Gamma_{k\,m_1}^{i}-\Gamma_{j\,l,k}^{i}+\Gamma_{j\,k,l}^{i}$$

Note the use of the idummyx assignment, to avoid the appearance of the percent sign in the TeX expression, which may lead to compile errors.

NB: This version of the tentex function is somewhat experimental.

25.2.9 Interfacing with ctensor

The itensor package has the ability to generate Maxima code that can then be executed in the context of the ctensor package. The function that performs this task is ic_convert.

Function: ic_convert (eqn)

Converts the itensor equation eqn to a ctensor assignment statement. Implied sums over dummy indices are made explicit while indexed objects are transformed into arrays (the array subscripts are in the order of covariant followed by contravariant indices of the indexed objects). The derivative of an indexed object will be replaced by the noun form of diff taken with respect to ct_coords subscripted by the derivative index. The Christoffel symbols ichr1 and ichr2 will be translated to lcs and mcs, respectively and if metricconvert is true then all occurrences of the metric with two covariant (contravariant) indices will be renamed to lg (ug). In addition, do loops will be introduced summing over all free indices so that the transformed assignment statement can be evaluated by just doing ev. The following examples demonstrate the features of this function.

(%i1) load("itensor");
(%o1)      /share/tensor/itensor.lisp
(%i2) eqn:ishow(t([i,j],[k])=f([],[])*g([l,m],[])*a([],[m],j)
      *b([i],[l,k]))$
                             k        m   l k
(%t2)                       t    = f a   b    g
                             i j      ,j  i    l m
(%i3) ic_convert(eqn);
(%o3) for i thru dim do (for j thru dim do (
       for k thru dim do
        t        : f sum(sum(diff(a , ct_coords ) b
         i, j, k                   m           j   i, l, k

 g    , l, 1, dim), m, 1, dim)))
  l, m
(%i4) imetric(g);
(%o4)                                done
(%i5) metricconvert:true;
(%o5)                                true
(%i6) ic_convert(eqn);
(%o6) for i thru dim do (for j thru dim do (
       for k thru dim do
        t        : f sum(sum(diff(a , ct_coords ) b
         i, j, k                   m           j   i, l, k

 lg    , l, 1, dim), m, 1, dim)))
   l, m

Category: Package itensor · Category: Package ctensor

25.2.10 Reserved words

The following Maxima words are used by the itensor package internally and should not be redefined:

  Keyword    Comments
  ------------------------------------------
  indices2() Internal version of indices()
  conti      Lists contravariant indices
  covi       Lists covariant indices of a indexed object
  deri       Lists derivative indices of an indexed object
  name       Returns the name of an indexed object
  concan
  irpmon
  lc0
  _lc2kdt0
  _lcprod
  _extlc

26 ctensor

26.1 Introduction to ctensor

ctensor is a component tensor manipulation package. To use the ctensor package, type load("ctensor"). To begin an interactive session with ctensor, type csetup(). You are first asked to specify the dimension of the manifold. If the dimension is 2, 3 or 4 then the list of coordinates defaults to [x,y], [x,y,z] or [x,y,z,t] respectively. These names may be changed by assigning a new list of coordinates to the variable ct_coords (described below) and the user is queried about this. Care must be taken to avoid the coordinate names conflicting with other object definitions.

Next, the user enters the metric either directly or from a file by specifying its ordinal position. The metric is stored in the matrix lg. Finally, the metric inverse is computed and stored in the matrix ug. One has the option of carrying out all calculations in a power series.

A sample protocol is begun below for the static, spherically symmetric metric (standard coordinates) which will be applied to the problem of deriving Einstein’s vacuum equations (which lead to the Schwarzschild solution) as an example. Many of the functions in ctensor will be displayed for the standard metric as examples.

(%i1) load("ctensor");
(%o1)      /share/tensor/ctensor.mac
(%i2) csetup();
Enter the dimension of the coordinate system:
4;
Do you wish to change the coordinate names?
n;
Do you want to
1. Enter a new metric?

2. Enter a metric from a file?

3. Approximate a metric with a Taylor series?
1;

Is the matrix  1. Diagonal  2. Symmetric  3. Antisymmetric  4. General
Answer 1, 2, 3 or 4
1;
Row 1 Column 1:
a;
Row 2 Column 2:
x^2;
Row 3 Column 3:
x^2*sin(y)^2;
Row 4 Column 4:
-d;

Matrix entered.
Enter functional dependencies with the DEPENDS function or 'N' if none
depends([a,d],x);
Do you wish to see the metric?
y;
                          [ a  0       0        0  ]
                          [                        ]
                          [     2                  ]
                          [ 0  x       0        0  ]
                          [                        ]
                          [         2    2         ]
                          [ 0  0   x  sin (y)   0  ]
                          [                        ]
                          [ 0  0       0       - d ]
(%o2)                                done
(%i3) christof(mcs);
                                            a
                                             x
(%t3)                          mcs        = ---
                                  1, 1, 1   2 a

                                             1
(%t4)                           mcs        = -
                                   1, 2, 2   x

                                             1
(%t5)                           mcs        = -
                                   1, 3, 3   x

                                            d
                                             x
(%t6)                          mcs        = ---
                                  1, 4, 4   2 d

                                              x
(%t7)                          mcs        = - -
                                  2, 2, 1     a

                                           cos(y)
(%t8)                         mcs        = ------
                                 2, 3, 3   sin(y)

                                               2
                                          x sin (y)
(%t9)                      mcs        = - ---------
                              3, 3, 1         a

(%t10)                   mcs        = - cos(y) sin(y)
                            3, 3, 2

                                            d
                                             x
(%t11)                         mcs        = ---
                                  4, 4, 1   2 a
(%o11)                               done

Category: Tensors · Category: Share packages · Category: Package ctensor

26.2 Functions and Variables for ctensor

26.2.1 Initialization and setup

Function: csetup ()

A function in the ctensor (component tensor) package which initializes the package and allows the user to enter a metric interactively. See ctensor for more details.

Function: cmetric
cmetric (dis)
cmetric ()

A function in the ctensor (component tensor) package that computes the metric inverse and sets up the package for further calculations.

If cframe_flag is false, the function computes the inverse metric ug from the (user-defined) matrix lg. The metric determinant is also computed and stored in the variable gdet. Furthermore, the package determines if the metric is diagonal and sets the value of diagmetric accordingly. If the optional argument dis is present and not equal to false, the user is prompted to see the metric inverse.

If cframe_flag is true, the function expects that the values of fri (the inverse frame matrix) and lfg (the frame metric) are defined. From these, the frame matrix fr and the inverse frame metric ufg are computed.

Function: ct_coordsys
ct_coordsys (coordinate_system, extra_arg)
ct_coordsys (coordinate_system)

Sets up a predefined coordinate system and metric. The argument coordinate_system can be one of the following symbols:


 SYMBOL             Dim Coordinates     Description/comments
 ------------------------------------------------------------------
 cartesian2d           2  [x,y]             Cartesian 2D coordinate
                                            system
 polar                 2  [r,phi]           Polar coordinate system
 elliptic              2  [u,v]             Elliptic coord. system
 confocalelliptic      2  [u,v]             Confocal elliptic
                                            coordinates
 bipolar               2  [u,v]             Bipolar coord. system
 parabolic             2  [u,v]             Parabolic coord. system
 cartesian3d           3  [x,y,z]           Cartesian 3D coordinate
                                            system
 polarcylindrical      3  [r,theta,z]       Polar 2D with
                                            cylindrical z
 ellipticcylindrical   3  [u,v,z]           Elliptic 2D with
                                            cylindrical z
 confocalellipsoidal   3  [u,v,w]           Confocal ellipsoidal
 bipolarcylindrical    3  [u,v,z]           Bipolar 2D with
                                            cylindrical z
 paraboliccylindrical  3  [u,v,z]           Parabolic 2D with
                                            cylindrical z
 paraboloidal          3  [u,v,phi]         Paraboloidal coords.
 conical               3  [u,v,w]           Conical coordinates
 toroidal              3  [phi,u,v]         Toroidal coordinates
 spherical             3  [r,theta,phi]     Spherical coord. system
 oblatespheroidal      3  [u,v,phi]         Oblate spheroidal
                                            coordinates
 oblatespheroidalsqrt  3  [u,v,phi]
 prolatespheroidal     3  [u,v,phi]         Prolate spheroidal
                                            coordinates
 prolatespheroidalsqrt 3  [u,v,phi]
 ellipsoidal           3  [r,theta,phi]     Ellipsoidal coordinates
 cartesian4d           4  [x,y,z,t]         Cartesian 4D coordinate
                                            system
 spherical4d           4  [r,theta,eta,phi] Spherical 4D coordinate
                                            system
 exteriorschwarzschild 4  [t,r,theta,phi]   Schwarzschild metric
 interiorschwarzschild 4  [t,z,u,v]         Interior Schwarzschild
                                            metric
 kerr_newman           4  [t,r,theta,phi]   Charged axially
                                            symmetric metric

coordinate_system can also be a list of transformation functions, followed by a list containing the coordinate variables. For instance, you can specify a spherical metric as follows:


(%i1) load("ctensor");
(%o1)       /share/tensor/ctensor.mac
(%i2) ct_coordsys([r*cos(theta)*cos(phi),r*cos(theta)*sin(phi),
      r*sin(theta),[r,theta,phi]]);
(%o2)                                done
(%i3) lg:trigsimp(lg);
                           [ 1  0         0        ]
                           [                       ]
                           [     2                 ]
(%o3)                      [ 0  r         0        ]
                           [                       ]
                           [         2    2        ]
                           [ 0  0   r  cos (theta) ]
(%i4) ct_coords;
(%o4)                           [r, theta, phi]
(%i5) dim;
(%o5)                                  3

Transformation functions can also be used when cframe_flag is true:


(%i1) load("ctensor");
(%o1)       /share/tensor/ctensor.mac
(%i2) cframe_flag:true;
(%o2)                                true
(%i3) ct_coordsys([r*cos(theta)*cos(phi),r*cos(theta)*sin(phi),
      r*sin(theta),[r,theta,phi]]);
(%o3)                                done
(%i4) fri;
(%o4)
 [cos(phi)cos(theta) -cos(phi) r sin(theta) -sin(phi) r cos(theta)]
 [                                                                ]
 [sin(phi)cos(theta) -sin(phi) r sin(theta)  cos(phi) r cos(theta)]
 [                                                                ]
 [    sin(theta)           r cos(theta)                0          ]

(%i5) cmetric();
(%o5)                                false
(%i6) lg:trigsimp(lg);
                           [ 1  0         0        ]
                           [                       ]
                           [     2                 ]
(%o6)                      [ 0  r         0        ]
                           [                       ]
                           [         2    2        ]
                           [ 0  0   r  cos (theta) ]

The optional argument extra_arg can be any one of the following:

cylindrical tells ct_coordsys to attach an additional cylindrical coordinate.

minkowski tells ct_coordsys to attach an additional coordinate with negative metric signature.

all tells ct_coordsys to call cmetric and christof(false) after setting up the metric.

If the global variable verbose is set to true, ct_coordsys displays the values of dim, ct_coords, and either lg or lfg and fri, depending on the value of cframe_flag.

Function: init_ctensor ()

Initializes the ctensor package.

The init_ctensor function reinitializes the ctensor package. It removes all arrays and matrices used by ctensor, resets all flags, resets dim to 4, and resets the frame metric to the Lorentz-frame.

26.2.2 The tensors of curved space

The main purpose of the ctensor package is to compute the tensors of curved space(time), most notably the tensors used in general relativity.

When a metric base is used, ctensor can compute the following tensors:


 lg  -- ug
   \      \
    lcs -- mcs -- ric -- uric
              \      \       \
               \      tracer - ein -- lein
                \
                 riem -- lriem -- weyl
                     \
                      uriem

ctensor can also work using moving frames. When cframe_flag is set to true, the following tensors can be calculated:


 lfg -- ufg
     \
 fri -- fr -- lcs -- mcs -- lriem -- ric -- uric
      \                       |  \      \       \
       lg -- ug               |   weyl   tracer - ein -- lein
                              |\
                              | riem
                              |
                              \uriem

Function: christof (dis)

A function in the ctensor (component tensor) package. It computes the Christoffel symbols of both kinds. The argument dis determines which results are to be immediately displayed. The Christoffel symbols of the first and second kinds are stored in the arrays lcs[i,j,k] and mcs[i,j,k] respectively and defined to be symmetric in the first two indices. If the argument to christof is lcs or mcs then the unique non-zero values of lcs[i,j,k] or mcs[i,j,k], respectively, will be displayed. If the argument is all then the unique non-zero values of lcs[i,j,k] and mcs[i,j,k] will be displayed. If the argument is false then the display of the elements will not occur. The array elements mcs[i,j,k] are defined in such a manner that the final index is contravariant.

Function: ricci (dis)

A function in the ctensor (component tensor) package. ricci computes the covariant (symmetric) components ric[i,j] of the Ricci tensor. If the argument dis is true, then the non-zero components are displayed.

Function: uricci (dis)

This function first computes the covariant components ric[i,j] of the Ricci tensor. Then the mixed Ricci tensor is computed using the contravariant metric tensor. If the value of the argument dis is true, then these mixed components, uric[i,j] (the index i is covariant and the index j is contravariant), will be displayed directly. Otherwise, ricci(false) will simply compute the entries of the array uric[i,j] without displaying the results.

Function: scurvature ()

Returns the scalar curvature (obtained by contracting the Ricci tensor) of the Riemannian manifold with the given metric.

Function: einstein (dis)

A function in the ctensor (component tensor) package. einstein computes the mixed Einstein tensor after the Christoffel symbols and Ricci tensor have been obtained (with the functions christof and ricci). If the argument dis is true, then the non-zero values of the mixed Einstein tensor ein[i,j] will be displayed where j is the contravariant index. The variable rateinstein will cause the rational simplification on these components. If ratfac is true then the components will also be factored.

Function: leinstein (dis)

Covariant Einstein-tensor. leinstein stores the values of the covariant Einstein tensor in the array lein. The covariant Einstein-tensor is computed from the mixed Einstein tensor ein by multiplying it with the metric tensor. If the argument dis is true, then the non-zero values of the covariant Einstein tensor are displayed.

Function: riemann (dis)

A function in the ctensor (component tensor) package. riemann computes the Riemann curvature tensor from the given metric and the corresponding Christoffel symbols. The following index conventions are used:

                l      _l       _l       _l   _m    _l   _m
 R[i,j,k,l] =  R    = |      - |      + |    |   - |    |
                ijk     ij,k     ik,j     mk   ij    mj   ik

This notation is consistent with the notation used by the itensor package and its icurvature function. If the optional argument dis is true, the unique non-zero components riem[i,j,k,l] will be displayed. As with the Einstein tensor, various switches set by the user control the simplification of the components of the Riemann tensor. If ratriemann is true, then rational simplification will be done. If ratfac is true then each of the components will also be factored.

If the variable cframe_flag is false, the Riemann tensor is computed directly from the Christoffel-symbols. If cframe_flag is true, the covariant Riemann-tensor is computed first from the frame field coefficients.

Function: lriemann (dis)

Covariant Riemann-tensor (lriem[]).

Computes the covariant Riemann-tensor as the array lriem. If the argument dis is true, unique non-zero values are displayed.

If the variable cframe_flag is true, the covariant Riemann tensor is computed directly from the frame field coefficients. Otherwise, the (3,1) Riemann tensor is computed first.

For information on index ordering, see riemann.

Function: uriemann (dis)

Computes the contravariant components of the Riemann curvature tensor as array elements uriem[i,j,k,l]. These are displayed if dis is true.

Function: rinvariant ()

Forms the Kretchmann-invariant (kinvariant) obtained by contracting the tensors

lriem[i,j,k,l]*uriem[i,j,k,l].

This object is not automatically simplified since it can be very large.

Function: weyl (dis)

Computes the Weyl conformal tensor. If the argument dis is true, the non-zero components weyl[i,j,k,l] will be displayed to the user. Otherwise, these components will simply be computed and stored. If the switch ratweyl is set to true, then the components will be rationally simplified; if ratfac is true then the results will be factored as well.

26.2.3 Taylor series expansion

The ctensor package has the ability to truncate results by assuming that they are Taylor-series approximations. This behavior is controlled by the ctayswitch variable; when set to true, ctensor makes use internally of the function ctaylor when simplifying results.

The ctaylor function is invoked by the following ctensor functions:


    Function     Comments
    ---------------------------------
    christof()   For mcs only
    ricci()
    uricci()
    einstein()
    riemann()
    weyl()
    checkdiv()

Function: ctaylor ()

The ctaylor function truncates its argument by converting it to a Taylor-series using taylor, and then calling ratdisrep. This has the combined effect of dropping terms higher order in the expansion variable ctayvar. The order of terms that should be dropped is defined by ctaypov; the point around which the series expansion is carried out is specified in ctaypt.

As an example, consider a simple metric that is a perturbation of the Minkowski metric. Without further restrictions, even a diagonal metric produces expressions for the Einstein tensor that are far too complex:


(%i1) load("ctensor");
(%o1)       /share/tensor/ctensor.mac
(%i2) ratfac:true;
(%o2)                                true
(%i3) derivabbrev:true;
(%o3)                                true
(%i4) ct_coords:[t,r,theta,phi];
(%o4)                         [t, r, theta, phi]
(%i5) lg:matrix([-1,0,0,0],[0,1,0,0],[0,0,r^2,0],
                [0,0,0,r^2*sin(theta)^2]);
                        [ - 1  0  0         0        ]
                        [                            ]
                        [  0   1  0         0        ]
                        [                            ]
(%o5)                   [          2                 ]
                        [  0   0  r         0        ]
                        [                            ]
                        [              2    2        ]
                        [  0   0  0   r  sin (theta) ]
(%i6) h:matrix([h11,0,0,0],[0,h22,0,0],[0,0,h33,0],[0,0,0,h44]);
                            [ h11   0    0    0  ]
                            [                    ]
                            [  0   h22   0    0  ]
(%o6)                       [                    ]
                            [  0    0   h33   0  ]
                            [                    ]
                            [  0    0    0   h44 ]
(%i7) depends(l,r);
(%o7)                               [l(r)]
(%i8) lg:lg+l*h;
      [ h11 l - 1      0          0                 0            ]
      [                                                          ]
      [     0      h22 l + 1      0                 0            ]
      [                                                          ]
(%o8) [                        2                                 ]
      [     0          0      r  + h33 l            0            ]
      [                                                          ]
      [                                    2    2                ]
      [     0          0          0       r  sin (theta) + h44 l ]
(%i9) cmetric(false);
(%o9)                                done
(%i10) einstein(false);
(%o10)                               done
(%i11) ntermst(ein);
[[1, 1], 62]
[[1, 2], 0]
[[1, 3], 0]
[[1, 4], 0]
[[2, 1], 0]
[[2, 2], 24]
[[2, 3], 0]
[[2, 4], 0]
[[3, 1], 0]
[[3, 2], 0]
[[3, 3], 46]
[[3, 4], 0]
[[4, 1], 0]
[[4, 2], 0]
[[4, 3], 0]
[[4, 4], 46]
(%o12)                               done

However, if we recompute this example as an approximation that is linear in the variable l, we get much simpler expressions:


(%i14) ctayswitch:true;
(%o14)                               true
(%i15) ctayvar:l;
(%o15)                                 l
(%i16) ctaypov:1;
(%o16)                                 1
(%i17) ctaypt:0;
(%o17)                                 0
(%i18) christof(false);
(%o18)                               done
(%i19) ricci(false);
(%o19)                               done
(%i20) einstein(false);
(%o20)                               done
(%i21) ntermst(ein);
[[1, 1], 6]
[[1, 2], 0]
[[1, 3], 0]
[[1, 4], 0]
[[2, 1], 0]
[[2, 2], 13]
[[2, 3], 2]
[[2, 4], 0]
[[3, 1], 0]
[[3, 2], 2]
[[3, 3], 9]
[[3, 4], 0]
[[4, 1], 0]
[[4, 2], 0]
[[4, 3], 0]
[[4, 4], 9]
(%o21)                               done
(%i22) ratsimp(ein[1,1]);
                         2      2  4               2     2
(%o22) - (((h11 h22 - h11 ) (l )  r  - 2 h33 l    r ) sin (theta)
                              r               r r

                            2               2      4    2
              - 2 h44 l    r  - h33 h44 (l ) )/(4 r  sin (theta))
                       r r                r

This capability can be useful, for instance, when working in the weak field limit far from a gravitational source.

26.2.4 Frame fields

When the variable cframe_flag is set to true, the ctensor package performs its calculations using a moving frame.

Function: frame_bracket (fr, fri, diagframe)

The frame bracket (fb[]).

Computes the frame bracket according to the following definition:

   c          c         c        d     e
ifb   = ( ifri    - ifri    ) ifr   ifr
   ab         d,e       e,d      a     b

26.2.5 Algebraic classification

A new feature (as of November, 2004) of ctensor is its ability to compute the Petrov classification of a 4-dimensional spacetime metric. For a demonstration of this capability, see the file share/tensor/petrov.dem.

Function: nptetrad ()

Computes a Newman-Penrose null tetrad (np) and its raised-index counterpart (npi). See petrov for an example.

The null tetrad is constructed on the assumption that a four-dimensional orthonormal frame metric with metric signature (-,+,+,+) is being used. The components of the null tetrad are related to the inverse frame matrix as follows:


np  = (fri  + fri ) / sqrt(2)
  1       1      2

np  = (fri  - fri ) / sqrt(2)
  2       1      2

np  = (fri  + %i fri ) / sqrt(2)
  3       3         4

np  = (fri  - %i fri ) / sqrt(2)
  4       3         4

Function: psi (dis)

Computes the five Newman-Penrose coefficients psi[0]...psi[4]. If dis is set to true, the coefficients are displayed. See petrov for an example.

These coefficients are computed from the Weyl-tensor in a coordinate base. If a frame base is used, the Weyl-tensor is first converted to a coordinate base, which can be a computationally expensive procedure. For this reason, in some cases it may be more advantageous to use a coordinate base in the first place before the Weyl tensor is computed. Note however, that constructing a Newman-Penrose null tetrad requires a frame base. Therefore, a meaningful computation sequence may begin with a frame base, which is then used to compute lg (computed automatically by cmetric) and then ug. See petrov for an example. At this point, you can switch back to a coordinate base by setting cframe_flag to false before beginning to compute the Christoffel symbols. Changing to a frame base at a later stage could yield inconsistent results, as you may end up with a mixed bag of tensors, some computed in a frame base, some in a coordinate base, with no means to distinguish between the two.

Function: petrov ()

Computes the Petrov classification of the metric characterized by psi[0]...psi[4].

For example, the following demonstrates how to obtain the Petrov-classification of the Kerr metric:

(%i1) load("ctensor");
(%o1)       /share/tensor/ctensor.mac
(%i2) (cframe_flag:true,gcd:spmod,ctrgsimp:true,ratfac:true);
(%o2)                                true
(%i3) ct_coordsys(exteriorschwarzschild,all);
(%o3)                                done
(%i4) ug:invert(lg)$
(%i5) weyl(false);
(%o5)                                done
(%i6) nptetrad(true);
(%t6) np =

[ sqrt(r - 2 m)           sqrt(r)                                 ]
[---------------   ---------------------    0            0        ]
[sqrt(2) sqrt(r)   sqrt(2) sqrt(r - 2 m)                          ]
[                                                                 ]
[ sqrt(r - 2 m)            sqrt(r)                                ]
[---------------  - ---------------------   0            0        ]
[sqrt(2) sqrt(r)    sqrt(2) sqrt(r - 2 m)                         ]
[                                                                 ]
[                                          r      %i r sin(theta) ]
[       0                    0          -------   --------------- ]
[                                       sqrt(2)       sqrt(2)     ]
[                                                                 ]
[                                          r       %i r sin(theta)]
[       0                    0          -------  - ---------------]
[                                       sqrt(2)        sqrt(2)    ]

                             sqrt(r)         sqrt(r - 2 m)
(%t7) npi = matrix([- ---------------------,---------------, 0, 0],
                      sqrt(2) sqrt(r - 2 m) sqrt(2) sqrt(r)

          sqrt(r)            sqrt(r - 2 m)
[- ---------------------, - ---------------, 0, 0],
   sqrt(2) sqrt(r - 2 m)    sqrt(2) sqrt(r)

           1               %i
[0, 0, ---------, --------------------],
       sqrt(2) r  sqrt(2) r sin(theta)

           1                 %i
[0, 0, ---------, - --------------------])
       sqrt(2) r    sqrt(2) r sin(theta)

(%o7)                                done
(%i7) psi(true);
(%t8)                              psi  = 0
                                      0

(%t9)                              psi  = 0
                                      1

                                          m
(%t10)                             psi  = --
                                      2    3
                                          r

(%t11)                             psi  = 0
                                      3

(%t12)                             psi  = 0
                                      4
(%o12)                               done
(%i12) petrov();
(%o12)                                 D

The Petrov classification function is based on the algorithm published in "Classifying geometries in general relativity: III Classification in practice" by Pollney, Skea, and d’Inverno, Class. Quant. Grav. 17 2885-2902 (2000). Except for some simple test cases, the implementation is untested as of December 19, 2004, and is likely to contain errors.

26.2.6 Torsion and nonmetricity

ctensor has the ability to compute and include torsion and nonmetricity coefficients in the connection coefficients.

The torsion coefficients are calculated from a user-supplied tensor tr, which should be a rank (2,1) tensor. From this, the torsion coefficients kt are computed according to the following formulae:


              m          m      m
       - g  tr   - g   tr   - tr   g
          im  kj    jm   ki     ij  km
kt   = -------------------------------
  ijk                 2


  k     km
kt   = g   kt
  ij         ijm

Note that only the mixed-index tensor is calculated and stored in the array kt.

The nonmetricity coefficients are calculated from the user-supplied nonmetricity vector nm. From this, the nonmetricity coefficients nmc are computed as follows:


             k    k        km
       -nm  D  - D  nm  + g   nm  g
   k      i  j    i   j         m  ij
nmc  = ------------------------------
   ij                2

where D stands for the Kronecker-delta.

When ctorsion_flag is set to true, the values of kt are subtracted from the mixed-indexed connection coefficients computed by christof and stored in mcs. Similarly, if cnonmet_flag is set to true, the values of nmc are subtracted from the mixed-indexed connection coefficients.

If necessary, christof calls the functions contortion and nonmetricity in order to compute kt and nm.

Function: contortion (tr)

Computes the (2,1) contortion coefficients from the torsion tensor tr.

Function: nonmetricity (nm)

Computes the (2,1) nonmetricity coefficients from the nonmetricity vector nm.

26.2.7 Miscellaneous features

Function: ctransform (M)

A function in the ctensor (component tensor) package which will perform a coordinate transformation upon an arbitrary square symmetric matrix M. The user must input the functions which define the transformation. (Formerly called transform.)

Function: findde (A, n)

returns a list of the unique differential equations (expressions) corresponding to the elements of the n dimensional square array A. Presently, n may be 2 or 3. deindex is a global list containing the indices of A corresponding to these unique differential equations. For the Einstein tensor (ein), which is a two dimensional array, if computed for the metric in the example below, findde gives the following independent differential equations:

(%i1) load("ctensor");
(%o1)       /share/tensor/ctensor.mac
(%i2) derivabbrev:true;
(%o2)                                true
(%i3) dim:4;
(%o3)                                  4
(%i4) lg:matrix([a, 0, 0, 0], [ 0, x^2, 0, 0],
                              [0, 0, x^2*sin(y)^2, 0], [0,0,0,-d]);
                          [ a  0       0        0  ]
                          [                        ]
                          [     2                  ]
                          [ 0  x       0        0  ]
(%o4)                     [                        ]
                          [         2    2         ]
                          [ 0  0   x  sin (y)   0  ]
                          [                        ]
                          [ 0  0       0       - d ]
(%i5) depends([a,d],x);
(%o5)                            [a(x), d(x)]
(%i6) ct_coords:[x,y,z,t];
(%o6)                            [x, y, z, t]
(%i7) cmetric();
(%o7)                                done
(%i8) einstein(false);
(%o8)                                done
(%i9) findde(ein,2);
                                            2
(%o9) [d  x - a d + d, 2 a d d    x - a (d )  x - a  d d  x
        x                     x x         x        x    x

                                              2          2
                          + 2 a d d   - 2 a  d , a  x + a  - a]
                                   x       x      x
(%i10) deindex;
(%o10)                     [[1, 1], [2, 2], [4, 4]]

Function: cograd ()

Computes the covariant gradient of a scalar function allowing the user to choose the corresponding vector name as the example under contragrad illustrates.

Function: contragrad ()

Computes the contravariant gradient of a scalar function allowing the user to choose the corresponding vector name as the example below for the Schwarzschild metric illustrates:

(%i1) load("ctensor");
(%o1)       /share/tensor/ctensor.mac
(%i2) derivabbrev:true;
(%o2)                                true
(%i3) ct_coordsys(exteriorschwarzschild,all);
(%o3)                                done
(%i4) depends(f,r);
(%o4)                               [f(r)]
(%i5) cograd(f,g1);
(%o5)                                done
(%i6) listarray(g1);
(%o6)                            [0, f , 0, 0]
                                      r
(%i7) contragrad(f,g2);
(%o7)                                done
(%i8) listarray(g2);
                               f  r - 2 f  m
                                r        r
(%o8)                      [0, -------------, 0, 0]
                                     r

Function: dscalar ()

computes the tensor d’Alembertian of the scalar function once dependencies have been declared upon the function. For example:

(%i1) load("ctensor");
(%o1)       /share/tensor/ctensor.mac
(%i2) derivabbrev:true;
(%o2)                                true
(%i3) ct_coordsys(exteriorschwarzschild,all);
(%o3)                                done
(%i4) depends(p,r);
(%o4)                               [p(r)]
(%i5) factor(dscalar(p));

                          2
                    p    r  - 2 m p    r + 2 p  r - 2 m p
                     r r           r r        r          r
(%o5)               --------------------------------------
                                       2
                                      r

Function: checkdiv ()

computes the covariant divergence of the mixed second rank tensor (whose first index must be covariant) by printing the corresponding n components of the vector field (the divergence) where n = dim. If the argument to the function is g then the divergence of the Einstein tensor will be formed and must be zero. In addition, the divergence (vector) is given the array name div.

Function: cgeodesic (dis)

A function in the ctensor (component tensor) package. cgeodesic computes the geodesic equations of motion for a given metric. They are stored in the array geod[i]. If the argument dis is true then these equations are displayed.

Function: bdvac (f)

generates the covariant components of the vacuum field equations of the Brans- Dicke gravitational theory. The scalar field is specified by the argument f, which should be a (quoted) function name with functional dependencies, e.g., 'p(x).

The components of the second rank covariant field tensor are represented by the array bd.

Function: invariant1 ()

generates the mixed Euler- Lagrange tensor (field equations) for the invariant density of R^2. The field equations are the components of an array named inv1.

Function: invariant2 ()

*** NOT YET IMPLEMENTED ***

generates the mixed Euler- Lagrange tensor (field equations) for the invariant density of ric[i,j]*uriem[i,j]. The field equations are the components of an array named inv2.

Function: bimetric ()

*** NOT YET IMPLEMENTED ***

generates the field equations of Rosen’s bimetric theory. The field equations are the components of an array named rosen.

Category: Package ctensor · Category: Predicate functions

26.2.8 Utility functions

Function: diagmatrixp (M,n)

Returns true if the first n rows and n columns of M form a diagonal matrix or (2D) array.

Function: symmetricp (M, n)

Returns true if M is a n by n symmetric matrix or two-dimensional array, otherwise false.

If n is less than the size of M, symmetricp considers only the n by n submatrix (respectively, subarray) comprising rows 1 through n and columns 1 through n.

Category: Package ctensor · Category: Predicate functions

Function: ntermst (f)

gives the user a quick picture of the "size" of the doubly subscripted tensor (array) f. It prints two element lists where the second element corresponds to NTERMS of the components specified by the first elements. In this way, it is possible to quickly find the non-zero expressions and attempt simplification.

Function: cdisplay (ten)

displays all the elements of the tensor ten, as represented by a multidimensional array. Tensors of rank 0 and 1, as well as other types of variables, are displayed as with ldisplay. Tensors of rank 2 are displayed as 2-dimensional matrices, while tensors of higher rank are displayed as a list of 2-dimensional matrices. For instance, the Riemann-tensor of the Schwarzschild metric can be viewed as:

(%i1) load("ctensor");
(%o1)       /share/tensor/ctensor.mac
(%i2) ratfac:true;
(%o2)                                true
(%i3) ct_coordsys(exteriorschwarzschild,all);
(%o3)                                done
(%i4) riemann(false);
(%o4)                                done
(%i5) cdisplay(riem);
          [ 0               0                   0           0     ]
          [                                                       ]
          [                              2                        ]
          [      3 m (r - 2 m)   m    2 m                         ]
          [ 0  - ------------- + -- - ----      0           0     ]
          [            4          3     4                         ]
          [           r          r     r                          ]
          [                                                       ]
riem    = [                                m (r - 2 m)            ]
    1, 1  [ 0               0              -----------      0     ]
          [                                     4                 ]
          [                                    r                  ]
          [                                                       ]
          [                                           m (r - 2 m) ]
          [ 0               0                   0     ----------- ]
          [                                                4      ]
          [                                               r       ]

                                [    2 m (r - 2 m)       ]
                                [ 0  -------------  0  0 ]
                                [          4             ]
                                [         r              ]
                     riem     = [                        ]
                         1, 2   [ 0        0        0  0 ]
                                [                        ]
                                [ 0        0        0  0 ]
                                [                        ]
                                [ 0        0        0  0 ]

                                [         m (r - 2 m)    ]
                                [ 0  0  - -----------  0 ]
                                [              4         ]
                                [             r          ]
                     riem     = [                        ]
                         1, 3   [ 0  0        0        0 ]
                                [                        ]
                                [ 0  0        0        0 ]
                                [                        ]
                                [ 0  0        0        0 ]

                                [            m (r - 2 m) ]
                                [ 0  0  0  - ----------- ]
                                [                 4      ]
                                [                r       ]
                     riem     = [                        ]
                         1, 4   [ 0  0  0        0       ]
                                [                        ]
                                [ 0  0  0        0       ]
                                [                        ]
                                [ 0  0  0        0       ]

                               [       0         0  0  0 ]
                               [                         ]
                               [       2 m               ]
                               [ - ------------  0  0  0 ]
                    riem     = [    2                    ]
                        2, 1   [   r  (r - 2 m)          ]
                               [                         ]
                               [       0         0  0  0 ]
                               [                         ]
                               [       0         0  0  0 ]

             [     2 m                                         ]
             [ ------------  0        0               0        ]
             [  2                                              ]
             [ r  (r - 2 m)                                    ]
             [                                                 ]
             [      0        0        0               0        ]
             [                                                 ]
  riem     = [                         m                       ]
      2, 2   [      0        0  - ------------        0        ]
             [                     2                           ]
             [                    r  (r - 2 m)                 ]
             [                                                 ]
             [                                         m       ]
             [      0        0        0         - ------------ ]
             [                                     2           ]
             [                                    r  (r - 2 m) ]

                                [ 0  0       0        0 ]
                                [                       ]
                                [            m          ]
                                [ 0  0  ------------  0 ]
                     riem     = [        2              ]
                         2, 3   [       r  (r - 2 m)    ]
                                [                       ]
                                [ 0  0       0        0 ]
                                [                       ]
                                [ 0  0       0        0 ]

                                [ 0  0  0       0       ]
                                [                       ]
                                [               m       ]
                                [ 0  0  0  ------------ ]
                     riem     = [           2           ]
                         2, 4   [          r  (r - 2 m) ]
                                [                       ]
                                [ 0  0  0       0       ]
                                [                       ]
                                [ 0  0  0       0       ]

                                      [ 0  0  0  0 ]
                                      [            ]
                                      [ 0  0  0  0 ]
                                      [            ]
                           riem     = [ m          ]
                               3, 1   [ -  0  0  0 ]
                                      [ r          ]
                                      [            ]
                                      [ 0  0  0  0 ]

                                      [ 0  0  0  0 ]
                                      [            ]
                                      [ 0  0  0  0 ]
                                      [            ]
                           riem     = [    m       ]
                               3, 2   [ 0  -  0  0 ]
                                      [    r       ]
                                      [            ]
                                      [ 0  0  0  0 ]

                               [   m                      ]
                               [ - -   0   0       0      ]
                               [   r                      ]
                               [                          ]
                               [        m                 ]
                               [  0   - -  0       0      ]
                    riem     = [        r                 ]
                        3, 3   [                          ]
                               [  0    0   0       0      ]
                               [                          ]
                               [              2 m - r     ]
                               [  0    0   0  ------- + 1 ]
                               [                 r        ]

                                    [ 0  0  0    0   ]
                                    [                ]
                                    [ 0  0  0    0   ]
                                    [                ]
                         riem     = [            2 m ]
                             3, 4   [ 0  0  0  - --- ]
                                    [             r  ]
                                    [                ]
                                    [ 0  0  0    0   ]

                                [       0        0  0  0 ]
                                [                        ]
                                [       0        0  0  0 ]
                                [                        ]
                     riem     = [       0        0  0  0 ]
                         4, 1   [                        ]
                                [      2                 ]
                                [ m sin (theta)          ]
                                [ -------------  0  0  0 ]
                                [       r                ]

                                [ 0        0        0  0 ]
                                [                        ]
                                [ 0        0        0  0 ]
                                [                        ]
                     riem     = [ 0        0        0  0 ]
                         4, 2   [                        ]
                                [         2              ]
                                [    m sin (theta)       ]
                                [ 0  -------------  0  0 ]
                                [          r             ]

                              [ 0  0          0          0 ]
                              [                            ]
                              [ 0  0          0          0 ]
                              [                            ]
                   riem     = [ 0  0          0          0 ]
                       4, 3   [                            ]
                              [                2           ]
                              [         2 m sin (theta)    ]
                              [ 0  0  - ---------------  0 ]
                              [                r           ]

           [        2                                             ]
           [   m sin (theta)                                      ]
           [ - -------------         0                0         0 ]
           [         r                                            ]
           [                                                      ]
           [                         2                            ]
           [                    m sin (theta)                     ]
riem     = [        0         - -------------         0         0 ]
    4, 4   [                          r                           ]
           [                                                      ]
           [                                          2           ]
           [                                   2 m sin (theta)    ]
           [        0                0         ---------------  0 ]
           [                                          r           ]
           [                                                      ]
           [        0                0                0         0 ]

(%o5)                                done

Function: deleten (L, n)

Returns a new list consisting of L with the n’th element deleted.

26.2.9 Variables used by `ctensor`

Option variable: dim

Default value: 4

An option in the ctensor (component tensor) package. dim is the dimension of the manifold with the default 4. The command dim: n will reset the dimension to any other value n.

Option variable: diagmetric

Default value: false

An option in the ctensor (component tensor) package. If diagmetric is true special routines compute all geometrical objects (which contain the metric tensor explicitly) by taking into consideration the diagonality of the metric. Reduced run times will, of course, result. Note: this option is set automatically by csetup if a diagonal metric is specified.

Category: Package ctensor · Category: Simplification flags and variables

Option variable: ctrgsimp

Causes trigonometric simplifications to be used when tensors are computed. Presently, ctrgsimp affects only computations involving a moving frame.

Option variable: cframe_flag

Causes computations to be performed relative to a moving frame as opposed to a holonomic metric. The frame is defined by the inverse frame array fri and the frame metric lfg. For computations using a Cartesian frame, lfg should be the unit matrix of the appropriate dimension; for computations in a Lorentz frame, lfg should have the appropriate signature.

Option variable: ctorsion_flag

Causes the contortion tensor to be included in the computation of the connection coefficients. The contortion tensor itself is computed by contortion from the user-supplied tensor tr.

Option variable: cnonmet_flag

Causes the nonmetricity coefficients to be included in the computation of the connection coefficients. The nonmetricity coefficients are computed from the user-supplied nonmetricity vector nm by the function nonmetricity.

Option variable: ctayswitch

If set to true, causes some ctensor computations to be carried out using Taylor-series expansions. Presently, christof, ricci, uricci, einstein, and weyl take into account this setting.

Option variable: ctayvar

Variable used for Taylor-series expansion if ctayswitch is set to true.

Option variable: ctaypov

Maximum power used in Taylor-series expansion when ctayswitch is set to true.

Option variable: ctaypt

Point around which Taylor-series expansion is carried out when ctayswitch is set to true.

System variable: gdet

The determinant of the metric tensor lg. Computed by cmetric when cframe_flag is set to false.

Option variable: ratchristof

Causes rational simplification to be applied by christof.

Option variable: rateinstein

Default value: true

If true rational simplification will be performed on the non-zero components of Einstein tensors; if ratfac is true then the components will also be factored.

Option variable: ratriemann

Default value: true

One of the switches which controls simplification of Riemann tensors; if true, then rational simplification will be done; if ratfac is true then each of the components will also be factored.

Option variable: ratweyl

Default value: true

If true, this switch causes the weyl function to apply rational simplification to the values of the Weyl tensor. If ratfac is true, then the components will also be factored.

Variable: lfg

The covariant frame metric. By default, it is initialized to the 4-dimensional Lorentz frame with signature (+,+,+,-). Used when cframe_flag is true.

Variable: ufg

The inverse frame metric. Computed from lfg when cmetric is called while cframe_flag is set to true.

Variable: riem

The (3,1) Riemann tensor. Computed when the function riemann is invoked. For information about index ordering, see the description of riemann.

If cframe_flag is true, riem is computed from the covariant Riemann-tensor lriem.

Variable: lriem

The covariant Riemann tensor. Computed by lriemann.

Variable: uriem

The contravariant Riemann tensor. Computed by uriemann.

Variable: ric

The covariant Ricci-tensor. Computed by ricci.

Variable: uric

The mixed-index Ricci-tensor. Computed by uricci.

Variable: lg

The metric tensor. This tensor must be specified (as a dim by dim matrix) before other computations can be performed.

Variable: ug

The inverse of the metric tensor. Computed by cmetric.

Variable: weyl

The Weyl tensor. Computed by weyl.

Variable: fb

Frame bracket coefficients, as computed by frame_bracket.

Variable: kinvariant

The Kretchmann invariant. Computed by rinvariant.

Variable: np

A Newman-Penrose null tetrad. Computed by nptetrad.

Variable: npi

The raised-index Newman-Penrose null tetrad. Computed by nptetrad. Defined as ug.np. The product np.transpose(npi) is constant:

(%i39) trigsimp(np.transpose(npi));
                              [  0   - 1  0  0 ]
                              [                ]
                              [ - 1   0   0  0 ]
(%o39)                        [                ]
                              [  0    0   0  1 ]
                              [                ]
                              [  0    0   1  0 ]

Variable: tr

User-supplied rank-3 tensor representing torsion. Used by contortion.

Variable: kt

The contortion tensor, computed from tr by contortion.

Variable: nm

User-supplied nonmetricity vector. Used by nonmetricity.

Variable: nmc

The nonmetricity coefficients, computed from nm by nonmetricity.

System variable: tensorkill

Variable indicating if the tensor package has been initialized. Set and used by csetup, reset by init_ctensor.

Option variable: ct_coords

Default value: []

An option in the ctensor (component tensor) package. ct_coords contains a list of coordinates. While normally defined when the function csetup is called, one may redefine the coordinates with the assignment ct_coords: [j1, j2, ..., jn] where the j’s are the new coordinate names. See also csetup.

26.2.10 Reserved names

The following names are used internally by the ctensor package and should not be redefined:

  Name         Description
  ---------------------------------------------------------------------
  _lg()        Evaluates to lfg if frame metric used, lg otherwise
  _ug()        Evaluates to ufg if frame metric used, ug otherwise
  cleanup()    Removes items drom the deindex list
  contract4()  Used by psi()
  filemet()    Used by csetup() when reading the metric from a file
  findde1()    Used by findde()
  findde2()    Used by findde()
  findde3()    Used by findde()
  kdelt()      Kronecker-delta (not generalized)
  newmet()     Used by csetup() for setting up a metric interactively
  setflags()   Used by init_ctensor()
  readvalue()
  resimp()
  sermet()     Used by csetup() for entering a metric as Taylor-series
  txyzsum()
  tmetric()    Frame metric, used by cmetric() when cframe_flag:true
  triemann()   Riemann-tensor in frame base, used when cframe_flag:true
  tricci()     Ricci-tensor in frame base, used when cframe_flag:true
  trrc()       Ricci rotation coefficients, used by christof()
  yesp()

26.2.11 Changes

In November, 2004, the ctensor package was extensively rewritten. Many functions and variables have been renamed in order to make the package compatible with the commercial version of Macsyma.

  New Name     Old Name        Description
  ---------------------------------------------------------------------
  ctaylor()    DLGTAYLOR()     Taylor-series expansion of an expression
  lgeod[]      EM              Geodesic equations
  ein[]        G[]             Mixed Einstein-tensor
  ric[]        LR[]            Mixed Ricci-tensor
  ricci()      LRICCICOM()     Compute the mixed Ricci-tensor
  ctaypov      MINP            Maximum power in Taylor-series expansion
  cgeodesic()  MOTION          Compute geodesic equations
  ct_coords    OMEGA           Metric coordinates
  ctayvar      PARAM           Taylor-series expansion variable
  lriem[]      R[]             Covariant Riemann-tensor
  uriemann()   RAISERIEMANN()  Compute the contravariant Riemann-tensor
  ratriemann   RATRIEMAN       Rational simplif. of the Riemann-tensor
  uric[]       RICCI[]         Contravariant Ricci-tensor
  uricci()     RICCICOM()      Compute the contravariant Ricci-tensor
  cmetric()    SETMETRIC()     Set up the metric
  ctaypt       TAYPT           Point for Taylor-series expansion
  ctayswitch   TAYSWITCH       Taylor-series setting switch
  csetup()     TSETUP()        Start interactive setup session
  ctransform() TTRANSFORM()    Interactive coordinate transformation
  uriem[]      UR[]            Contravariant Riemann-tensor
  weyl[]       W[]             (3,1) Weyl-tensor

27 atensor

27.1 Introduction to atensor

atensor is an algebraic tensor manipulation package. To use atensor, type load("atensor"), followed by a call to the init_atensor function.

The essence of atensor is a set of simplification rules for the noncommutative (dot) product operator ("."). atensor recognizes several algebra types; the corresponding simplification rules are put into effect when the init_atensor function is called.

The capabilities of atensor can be demonstrated by defining the algebra of quaternions as a Clifford-algebra Cl(0,2) with two basis vectors. The three quaternionic imaginary units are then the two basis vectors and their product, i.e.:

    i = v     j = v     k = v  . v
         1         2         1    2

Although the atensor package has a built-in definition for the quaternion algebra, it is not used in this example, in which we endeavour to build the quaternion multiplication table as a matrix:

(%i1) load("atensor");
(%o1)       /share/tensor/atensor.mac
(%i2) init_atensor(clifford,0,0,2);
(%o2)                                done
(%i3) atensimp(v[1].v[1]);
(%o3)                                 - 1
(%i4) atensimp((v[1].v[2]).(v[1].v[2]));
(%o4)                                 - 1
(%i5) q:zeromatrix(4,4);
                                [ 0  0  0  0 ]
                                [            ]
                                [ 0  0  0  0 ]
(%o5)                           [            ]
                                [ 0  0  0  0 ]
                                [            ]
                                [ 0  0  0  0 ]
(%i6) q[1,1]:1;
(%o6)                                  1
(%i7) for i thru adim do q[1,i+1]:q[i+1,1]:v[i];
(%o7)                                done
(%i8) q[1,4]:q[4,1]:v[1].v[2];
(%o8)                               v  . v
                                     1    2
(%i9) for i from 2 thru 4 do for j from 2 thru 4 do
      q[i,j]:atensimp(q[i,1].q[1,j]);
(%o9)                                done
(%i10) q;

                   [    1        v         v      v  . v  ]
                   [              1         2      1    2 ]
                   [                                      ]
                   [   v         - 1     v  . v    - v    ]
                   [    1                 1    2      2   ]
(%o10)             [                                      ]
                   [   v      - v  . v     - 1      v     ]
                   [    2        1    2              1    ]
                   [                                      ]
                   [ v  . v      v        - v       - 1   ]
                   [  1    2      2          1            ]

atensor recognizes as base vectors indexed symbols, where the symbol is that stored in asymbol and the index runs between 1 and adim. For indexed symbols, and indexed symbols only, the bilinear forms sf, af, and av are evaluated. The evaluation substitutes the value of aform[i,j] in place of fun(v[i],v[j]) where v represents the value of asymbol and fun is either af or sf; or, it substitutes v[aform[i,j]] in place of av(v[i],v[j]).

Needless to say, the functions sf, af and av can be redefined.

When the atensor package is loaded, the following flags are set:

dotscrules:true;
dotdistrib:true;
dotexptsimp:false;

If you wish to experiment with a nonassociative algebra, you may also consider setting dotassoc to false. In this case, however, atensimp will not always be able to obtain the desired simplifications.

Category: Tensors · Category: Share packages · Category: Package atensor

27.2 Functions and Variables for atensor

Function: init_atensor
init_atensor (alg_type, opt_dims)
init_atensor (alg_type)

Initializes the atensor package with the specified algebra type. alg_type can be one of the following:

universal: The universal algebra has no commutation rules.

grassmann: The Grassman algebra is defined by the commutation relation u.v+v.u=0.

clifford: The Clifford algebra is defined by the commutation relation u.v+v.u=-2*sf(u,v) where sf is a symmetric scalar-valued function. For this algebra, opt_dims can be up to three nonnegative integers, representing the number of positive, degenerate, and negative dimensions of the algebra, respectively. If any opt_dims values are supplied, atensor will configure the values of adim and aform appropriately. Otherwise, adim will default to 0 and aform will not be defined.

symmetric: The symmetric algebra is defined by the commutation relation u.v-v.u=0.

symplectic: The symplectic algebra is defined by the commutation relation u.v-v.u=2*af(u,v) where af is an antisymmetric scalar-valued function. For the symplectic algebra, opt_dims can be up to two nonnegative integers, representing the nondegenerate and degenerate dimensions, respectively. If any opt_dims values are supplied, atensor will configure the values of adim and aform appropriately. Otherwise, adim will default to 0 and aform will not be defined.

lie_envelop: The algebra of the Lie envelope is defined by the commutation relation u.v-v.u=2*av(u,v) where av is an antisymmetric function.

The init_atensor function also recognizes several predefined algebra types:

complex implements the algebra of complex numbers as the Clifford algebra Cl(0,1). The call init_atensor(complex) is equivalent to init_atensor(clifford,0,0,1).

quaternion implements the algebra of quaternions. The call init_atensor (quaternion) is equivalent to init_atensor (clifford,0,0,2).

pauli implements the algebra of Pauli-spinors as the Clifford-algebra Cl(3,0). A call to init_atensor(pauli) is equivalent to init_atensor(clifford,3).

dirac implements the algebra of Dirac-spinors as the Clifford-algebra Cl(3,1). A call to init_atensor(dirac) is equivalent to init_atensor(clifford,3,0,1).

Category: Package atensor · Category: Simplification functions

Function: atensimp (expr)

Simplifies an algebraic tensor expression expr according to the rules configured by a call to init_atensor. Simplification includes recursive application of commutation relations and resolving calls to sf, af, and av where applicable. A safeguard is used to ensure that the function always terminates, even for complex expressions.

Function: alg_type

The algebra type. Valid values are universal, grassmann, clifford, symmetric, symplectic and lie_envelop.

Category: Package atensor · Category: Global variables

Variable: adim

Default value: 0

The dimensionality of the algebra. atensor uses the value of adim to determine if an indexed object is a valid base vector. See abasep.

Variable: aform

Default value: ident(3)

Default values for the bilinear forms sf, af, and av. The default is the identity matrix ident(3).

Category: Package atensor · Category: Global variables

Variable: asymbol

Default value: v

The symbol for base vectors.

Category: Package atensor · Category: Global variables

Function: sf (u, v)

A symmetric scalar function that is used in commutation relations. The default implementation checks if both arguments are base vectors using abasep and if that is the case, substitutes the corresponding value from the matrix aform.

Function: af (u, v)

An antisymmetric scalar function that is used in commutation relations. The default implementation checks if both arguments are base vectors using abasep and if that is the case, substitutes the corresponding value from the matrix aform.

Function: av (u, v)

An antisymmetric function that is used in commutation relations. The default implementation checks if both arguments are base vectors using abasep and if that is the case, substitutes the corresponding value from the matrix aform.

For instance:

(%i1) load("atensor");
(%o1)       /share/tensor/atensor.mac
(%i2) adim:3;
(%o2)                                  3
(%i3) aform:matrix([0,3,-2],[-3,0,1],[2,-1,0]);
                               [  0    3   - 2 ]
                               [               ]
(%o3)                          [ - 3   0    1  ]
                               [               ]
                               [  2   - 1   0  ]
(%i4) asymbol:x;
(%o4)                                  x
(%i5) av(x[1],x[2]);
(%o5)                                 x
                                       3

Category: Package atensor · Category: Predicate functions

Function: abasep (v)

Checks if its argument is an atensor base vector. That is, if it is an indexed symbol, with the symbol being the same as the value of asymbol, and the index having a numeric value between 1 and adim.

28 Sums, Products, and Series

28.1 Functions and Variables for Sums and Products

Function: bashindices (expr)

Transforms the expression expr by giving each summation and product a unique index. This gives changevar greater precision when it is working with summations or products. The form of the unique index is jnumber. The quantity number is determined by referring to gensumnum, which can be changed by the user. For example, gensumnum:0$ resets it.

Function: lsum (expr, x, L)

Represents the sum of expr for each element x in L. A noun form 'lsum is returned if the argument L does not evaluate to a list.

Examples:

(%i1) lsum (x^i, i, [1, 2, 7]);
                            7    2
(%o1)                      x  + x  + x
(%i2) lsum (i^2, i, rootsof (x^3 - 1, x));

                     ====
                     \      2
(%o2)                 >    i
                     /
                     ====
                                   3
                     i in rootsof(x  - 1, x)

Function: intosum (expr)

Moves multiplicative factors outside a summation to inside. If the index is used in the outside expression, then the function tries to find a reasonable index, the same as it does for sumcontract. This is essentially the reverse idea of the outative property of summations, but note that it does not remove this property, it only bypasses it.

In some cases, a scanmap (multthru, expr) may be necessary before the intosum.

Category: Sums and products · Category: Simplification flags and variables

Option variable: simpproduct

Default value: false

When simpproduct is true, the result of a product is simplified. This simplification may sometimes be able to produce a closed form. If simpproduct is false or if the quoted form 'product is used, the value is a product noun form which is a representation of the pi notation used in mathematics.

Function: product (expr, i, i_0, i_1)

Represents a product of the values of expr as the index i varies from i_0 to i_1. The noun form 'product is displayed as an uppercase letter pi.

product evaluates expr and lower and upper limits i_0 and i_1, product quotes (does not evaluate) the index i.

If the upper and lower limits differ by an integer, expr is evaluated for each value of the index i, and the result is an explicit product.

Otherwise, the range of the index is indefinite. Some rules are applied to simplify the product. When the global variable simpproduct is true, additional rules are applied. In some cases, simplification yields a result which is not a product; otherwise, the result is a noun form 'product.

28.2 Introduction to Series

Maxima contains functions taylor and powerseries for finding the series of differentiable functions. It also has tools such as nusum capable of finding the closed form of some series. Operations such as addition and multiplication work as usual on series. This section presents the global variables which control the expansion.

28.3 Functions and Variables for Series

Option variable: cauchysum

Default value: false

When multiplying together sums with inf as their upper limit, if sumexpand is true and cauchysum is true then the Cauchy product will be used rather than the usual product. In the Cauchy product the index of the inner summation is a function of the index of the outer one rather than varying independently.

Example:

(%i1) sumexpand: false$
(%i2) cauchysum: false$

(%i3) s: sum (f(i), i, 0, inf) * sum (g(j), j, 0, inf);
                      inf         inf
                      ====        ====
                      \           \
(%o3)                ( >    f(i))  >    g(j)
                      /           /
                      ====        ====
                      i = 0       j = 0

(%i4) sumexpand: true$
(%i5) cauchysum: true$

(%i6) expand(s,0,0);
                 inf     i1
                 ====   ====
                 \      \
(%o6)             >      >     g(i1 - i2) f(i2)
                 /      /
                 ====   ====
                 i1 = 0 i2 = 0

Function: deftaylor (f_1(x_1), expr_1, …, f_n(x_n), expr_n)

For each function f_i of one variable x_i, deftaylor defines expr_i as the Taylor series about zero. expr_i is typically a polynomial in x_i or a summation; more general expressions are accepted by deftaylor without complaint.

powerseries (f_i(x_i), x_i, 0) returns the series defined by deftaylor.

deftaylor returns a list of the functions f_1, …, f_n. deftaylor evaluates its arguments.

Example:

(%i1) deftaylor (f(x), x^2 + sum(x^i/(2^i*i!^2), i, 4, inf));
(%o1)                          [f]
(%i2) powerseries (f(x), x, 0);
                      inf
                      ====      i1
                      \        x         2
(%o2)                  >     -------- + x
                      /       i1    2
                      ====   2   i1!
                      i1 = 4
(%i3) taylor (exp (sqrt (f(x))), x, 0, 4);
                      2         3          4
                     x    3073 x    12817 x
(%o3)/T/     1 + x + -- + ------- + -------- + . . .
                     2     18432     307200

Option variable: maxtayorder

Default value: true

When maxtayorder is true, then during algebraic manipulation of (truncated) Taylor series, taylor tries to retain as many terms as are known to be correct.

Function: niceindices (expr)

Renames the indices of sums and products in expr. niceindices attempts to rename each index to the value of niceindicespref[1], unless that name appears in the summand or multiplicand, in which case niceindices tries the succeeding elements of niceindicespref in turn, until an unused variable is found. If the entire list is exhausted, additional indices are constructed by appending integers to the value of niceindicespref[1], e.g., i0, i1, i2, …

niceindices returns an expression. niceindices evaluates its argument.

Example:

(%i1) niceindicespref;
(%o1)                  [i, j, k, l, m, n]
(%i2) product (sum (f (foo + i*j*bar), foo, 1, inf), bar, 1, inf);
                 inf    inf
                /===\   ====
                 ! !    \
(%o2)            ! !     >      f(bar i j + foo)
                 ! !    /
                bar = 1 ====
                        foo = 1
(%i3) niceindices (%);

                     inf  inf
                    /===\ ====
                     ! !  \
(%o3)                ! !   >    f(i j l + k)
                     ! !  /
                    l = 1 ====
                          k = 1

Option variable: niceindicespref

Default value: [i, j, k, l, m, n]

niceindicespref is the list from which niceindices takes the names of indices for sums and products.

The elements of niceindicespref are typically names of variables, although that is not enforced by niceindices.

Example:

(%i1) niceindicespref: [p, q, r, s, t, u]$
(%i2) product (sum (f (foo + i*j*bar), foo, 1, inf), bar, 1, inf);
                 inf    inf
                /===\   ====
                 ! !    \
(%o2)            ! !     >      f(bar i j + foo)
                 ! !    /
                bar = 1 ====
                        foo = 1
(%i3) niceindices (%);
                     inf  inf
                    /===\ ====
                     ! !  \
(%o3)                ! !   >    f(i j q + p)
                     ! !  /
                    q = 1 ====
                          p = 1

Function: nusum (expr, x, i_0, i_1)

Carries out indefinite hypergeometric summation of expr with respect to x using a decision procedure due to R.W. Gosper. expr and the result must be expressible as products of integer powers, factorials, binomials, and rational functions.

The terms "definite" and "indefinite summation" are used analogously to "definite" and "indefinite integration". To sum indefinitely means to give a symbolic result for the sum over intervals of variable length, not just e.g. 0 to inf. Thus, since there is no formula for the general partial sum of the binomial series, nusum can’t do it.

nusum and unsum know a little about sums and differences of finite products. See also unsum.

Examples:

(%i1) nusum (n*n!, n, 0, n);

Dependent equations eliminated:  (1)
(%o1)                     (n + 1)! - 1
(%i2) nusum (n^4*4^n/binomial(2*n,n), n, 0, n);
                     4        3       2              n
      2 (n + 1) (63 n  + 112 n  + 18 n  - 22 n + 3) 4      2
(%o2) ------------------------------------------------ - ------
                    693 binomial(2 n, n)                 3 11 7
(%i3) unsum (%, n);
                              4  n
                             n  4
(%o3)                   ----------------
                        binomial(2 n, n)
(%i4) unsum (prod (i^2, i, 1, n), n);
                    n - 1
                    /===\
                     ! !   2
(%o4)              ( ! !  i ) (n - 1) (n + 1)
                     ! !
                    i = 1
(%i5) nusum (%, n, 1, n);

Dependent equations eliminated:  (2 3)
                            n
                          /===\
                           ! !   2
(%o5)                      ! !  i  - 1
                           ! !
                          i = 1

Function: pade (taylor_series, numer_deg_bound, denom_deg_bound)

Returns a list of all rational functions which have the given Taylor series expansion where the sum of the degrees of the numerator and the denominator is less than or equal to the truncation level of the power series, i.e. are "best" approximants, and which additionally satisfy the specified degree bounds.

taylor_series is a univariate Taylor series. numer_deg_bound and denom_deg_bound are positive integers specifying degree bounds on the numerator and denominator.

taylor_series can also be a Laurent series, and the degree bounds can be inf which causes all rational functions whose total degree is less than or equal to the length of the power series to be returned. Total degree is defined as numer_deg_bound + denom_deg_bound. Length of a power series is defined as "truncation level" + 1 - min(0, "order of series").

(%i1) taylor (1 + x + x^2 + x^3, x, 0, 3);
                              2    3
(%o1)/T/             1 + x + x  + x  + . . .
(%i2) pade (%, 1, 1);
                                 1
(%o2)                       [- -----]
                               x - 1
(%i3) t: taylor(-(83787*x^10 - 45552*x^9 - 187296*x^8
                   + 387072*x^7 + 86016*x^6 - 1507328*x^5
                   + 1966080*x^4 + 4194304*x^3 - 25165824*x^2
                   + 67108864*x - 134217728)
       /134217728, x, 0, 10);
                    2    3       4       5       6        7
             x   3 x    x    15 x    23 x    21 x    189 x
(%o3)/T/ 1 - - + ---- - -- - ----- + ----- - ----- - ------
             2    16    32   1024    2048    32768   65536

                                  8         9          10
                            5853 x    2847 x    83787 x
                          + ------- + ------- - --------- + . . .
                            4194304   8388608   134217728
(%i4) pade (t, 4, 4);
(%o4)                          []

There is no rational function of degree 4 numerator/denominator, with this power series expansion. You must in general have degree of the numerator and degree of the denominator adding up to at least the degree of the power series, in order to have enough unknown coefficients to solve.

(%i5) pade (t, 5, 5);
                     5                4                 3
(%o5) [- (520256329 x  - 96719020632 x  - 489651410240 x

                  2
 - 1619100813312 x  - 2176885157888 x - 2386516803584)

               5                 4                  3
/(47041365435 x  + 381702613848 x  + 1360678489152 x

                  2
 + 2856700692480 x  + 3370143559680 x + 2386516803584)]

Function: powerseries (expr, x, a)

Returns the general form of the power series expansion for expr in the variable x about the point a (which may be inf for infinity):

           inf
           ====
           \               n
            >    b  (x - a)
           /      n
           ====
           n = 0

If powerseries is unable to expand expr, taylor may give the first several terms of the series.

When verbose is true, powerseries prints progress messages.

(%i1) verbose: true$
(%i2) powerseries (log(sin(x)/x), x, 0);
can't expand 
                                 log(sin(x))
so we'll try again after applying the rule:
                                        d
                                      / -- (sin(x))
                                      [ dx
                        log(sin(x)) = i ----------- dx
                                      ]   sin(x)
                                      /
in the first simplification we have returned:
                             /
                             [
                             i cot(x) dx - log(x)
                             ]
                             /
                    inf
                    ====        i1  2 i1             2 i1
                    \      (- 1)   2     bern(2 i1) x
                     >     ------------------------------
                    /                i1 (2 i1)!
                    ====
                    i1 = 1
(%o2)                -------------------------------------
                                      2

Category: Display flags and variables

Option variable: psexpand

Default value: false

When psexpand is true, an extended rational function expression is displayed fully expanded. The switch ratexpand has the same effect.

When psexpand is false, a multivariate expression is displayed just as in the rational function package.

When psexpand is multi, then terms with the same total degree in the variables are grouped together.

Function: revert (expr, x)

Function: revert2 (expr, x, n)

These functions return the reversion of expr, a Taylor series about zero in the variable x. revert returns a polynomial of degree equal to the highest power in expr. revert2 returns a polynomial of degree n, which may be greater than, equal to, or less than the degree of expr.

load ("revert") loads these functions.

Examples:

(%i1) load ("revert")$
(%i2) t: taylor (exp(x) - 1, x, 0, 6);
                   2    3    4    5     6
                  x    x    x    x     x
(%o2)/T/      x + -- + -- + -- + --- + --- + . . .
                  2    6    24   120   720
(%i3) revert (t, x);
               6       5       4       3       2
           10 x  - 12 x  + 15 x  - 20 x  + 30 x  - 60 x
(%o3)/R/ - --------------------------------------------
                                60
(%i4) ratexpand (%);
                     6    5    4    3    2
                    x    x    x    x    x
(%o4)             - -- + -- - -- + -- - -- + x
                    6    5    4    3    2
(%i5) taylor (log(x+1), x, 0, 6);
                    2    3    4    5    6
                   x    x    x    x    x
(%o5)/T/       x - -- + -- - -- + -- - -- + . . .
                   2    3    4    5    6
(%i6) ratsimp (revert (t, x) - taylor (log(x+1), x, 0, 6));
(%o6)                           0
(%i7) revert2 (t, x, 4);
                          4    3    2
                         x    x    x
(%o7)                  - -- + -- - -- + x
                         4    3    2

Function: taylor
    taylor (expr, x, a, n)
    taylor (expr, [x_1, x_2, …], a, n)
    taylor (expr, [x, a, n, 'asymp])
    taylor (expr, [x_1, x_2, …], [a_1, a_2, …], [n_1, n_2, …])
    taylor (expr, [x_1, a_1, n_1], [x_2, a_2, n_2], …)

taylor (expr, x, a, n) expands the expression expr in a truncated Taylor or Laurent series in the variable x around the point a, containing terms through (x - a)^n.

If expr is of the form f(x)/g(x) and g(x) has no terms up to degree n then taylor attempts to expand g(x) up to degree 2 n. If there are still no nonzero terms, taylor doubles the degree of the expansion of g(x) so long as the degree of the expansion is less than or equal to n 2^taylordepth.

taylor (expr, [x_1, x_2, ...], a, n) returns a truncated power series of degree n in all variables x_1, x_2, … about the point (a, a, ...).

taylor (expr, [x_1, a_1, n_1], [x_2, a_2, n_2], ...) returns a truncated power series in the variables x_1, x_2, … about the point (a_1, a_2, ...), truncated at n_1, n_2, …

taylor (expr, [x_1, x_2, ...], [a_1, a_2, ...], [n_1, n_2, ...]) returns a truncated power series in the variables x_1, x_2, … about the point (a_1, a_2, ...), truncated at n_1, n_2, …

taylor (expr, [x, a, n, 'asymp]) returns an expansion of expr in negative powers of x - a. The highest order term is (x - a)^-n.

When maxtayorder is true, then during algebraic manipulation of (truncated) Taylor series, taylor tries to retain as many terms as are known to be correct.

When psexpand is true, an extended rational function expression is displayed fully expanded. The switch ratexpand has the same effect. When psexpand is false, a multivariate expression is displayed just as in the rational function package. When psexpand is multi, then terms with the same total degree in the variables are grouped together.

See also the taylor_logexpand switch for controlling expansion.

Examples:

(%i1) taylor (sqrt (sin(x) + a*x + 1), x, 0, 3);
                           2             2
             (a + 1) x   (a  + 2 a + 1) x
(%o1)/T/ 1 + --------- - -----------------
                 2               8

                                   3      2             3
                               (3 a  + 9 a  + 9 a - 1) x
                             + -------------------------- + . . .
                                           48
(%i2) %^2;
                                    3
                                   x
(%o2)/T/           1 + (a + 1) x - -- + . . .
                                   6
(%i3) taylor (sqrt (x + 1), x, 0, 5);
                       2    3      4      5
                  x   x    x    5 x    7 x
(%o3)/T/      1 + - - -- + -- - ---- + ---- + . . .
                  2   8    16   128    256
(%i4) %^2;
(%o4)/T/                  1 + x + . . .
(%i5) product ((1 + x^i)^2.5, i, 1, inf)/(1 + x^2);

                         inf
                        /===\
                         ! !    i     2.5
                         ! !  (x  + 1)
                         ! !
                        i = 1
(%o5)                   -----------------
                              2
                             x  + 1

(%i6) ev (taylor(%, x,  0, 3), keepfloat);
                               2           3
(%o6)/T/    1 + 2.5 x + 3.375 x  + 6.5625 x  + . . .
(%i7) taylor (1/log (x + 1), x, 0, 3);
                               2       3
                 1   1   x    x    19 x
(%o7)/T/         - + - - -- + -- - ----- + . . .
                 x   2   12   24    720
(%i8) taylor (cos(x) - sec(x), x, 0, 5);
                                4
                           2   x
(%o8)/T/                - x  - -- + . . .
                               6
(%i9) taylor ((cos(x) - sec(x))^3, x, 0, 5);
(%o9)/T/                    0 + . . .
(%i10) taylor (1/(cos(x) - sec(x))^3, x, 0, 5);
                                               2          4
            1     1       11      347    6767 x    15377 x
(%o10)/T/ - -- + ---- + ------ - ----- - ------- - --------
             6      4        2   15120   604800    7983360
            x    2 x    120 x

                                                          + . . .
(%i11) taylor (sqrt (1 - k^2*sin(x)^2), x, 0, 6);
               2  2       4      2   4
              k  x    (3 k  - 4 k ) x
(%o11)/T/ 1 - ----- - ----------------
                2            24

                                    6       4       2   6
                               (45 k  - 60 k  + 16 k ) x
                             - -------------------------- + . . .
                                          720
(%i12) taylor ((x + 1)^n, x, 0, 4);

                      2       2     3      2         3
                    (n  - n) x    (n  - 3 n  + 2 n) x
(%o12)/T/ 1 + n x + ----------- + --------------------
                         2                 6

                               4      3       2         4
                             (n  - 6 n  + 11 n  - 6 n) x
                           + ---------------------------- + . . .
                                          24

(%i13) taylor (sin (y + x), x, 0, 3, y, 0, 3);
               3                 2
              y                 y
(%o13)/T/ y - -- + . . . + (1 - -- + . . .) x
              6                 2

                    3                       2
               y   y            2      1   y            3
          + (- - + -- + . . .) x  + (- - + -- + . . .) x  + . . .
               2   12                  6   12
(%i14) taylor (sin (y + x), [x, y], 0, 3);
                     3        2      2      3
                    x  + 3 y x  + 3 y  x + y
(%o14)/T/   y + x - ------------------------- + . . .
                                6
(%i15) taylor (1/sin (y + x), x, 0, 3, y, 0, 3);
          1   y              1    1               1            2
(%o15)/T/ - + - + . . . + (- -- + - + . . .) x + (-- + . . .) x
          y   6               2   6                3
                             y                    y

                                           1            3
                                      + (- -- + . . .) x  + . . .
                                            4
                                           y
(%i16) taylor (1/sin (y + x), [x, y], 0, 3);
                             3         2       2        3
            1     x + y   7 x  + 21 y x  + 21 y  x + 7 y
(%o16)/T/ ----- + ----- + ------------------------------- + . . .
          x + y     6                   360

Option variable: taylordepth

Default value: 3

If there are still no nonzero terms, taylor doubles the degree of the expansion of g(x) so long as the degree of the expansion is less than or equal to n 2^taylordepth.

Function: taylorinfo (expr)

Returns information about the Taylor series expr. The return value is a list of lists. Each list comprises the name of a variable, the point of expansion, and the degree of the expansion.

taylorinfo returns false if expr is not a Taylor series.

Example:

(%i1) taylor ((1 - y^2)/(1 - x), x, 0, 3, [y, a, inf]);
                  2                       2
(%o1)/T/ - (y - a)  - 2 a (y - a) + (1 - a )

         2                        2
 + (1 - a  - 2 a (y - a) - (y - a) ) x

         2                        2   2
 + (1 - a  - 2 a (y - a) - (y - a) ) x

         2                        2   3
 + (1 - a  - 2 a (y - a) - (y - a) ) x  + . . .
(%i2) taylorinfo(%);
(%o2)               [[y, a, inf], [x, 0, 3]]

Category: Predicate functions · Category: Power series

Function: taylorp (expr)

Returns true if expr is a Taylor series, and false otherwise.

Option variable: taylor_logexpand

Default value: true

taylor_logexpand controls expansions of logarithms in taylor series.

When taylor_logexpand is true, all logarithms are expanded fully so that zero-recognition problems involving logarithmic identities do not disturb the expansion process. However, this scheme is not always mathematically correct since it ignores branch information.

When taylor_logexpand is set to false, then the only expansion of logarithms that occur is that necessary to obtain a formal power series.

Category: Power series · Category: Exponential and logarithm functions

Option variable: taylor_order_coefficients

Default value: true

taylor_order_coefficients controls the ordering of coefficients in a Taylor series.

When taylor_order_coefficients is true, coefficients of taylor series are ordered canonically.

Function: taylor_simplifier (expr)

Simplifies coefficients of the power series expr. taylor calls this function.

Option variable: taylor_truncate_polynomials

Default value: true

When taylor_truncate_polynomials is true, polynomials are truncated based upon the input truncation levels.

Otherwise, polynomials input to taylor are considered to have infinite precison.

Category: Power series · Category: Rational expressions

Function: taytorat (expr)

Converts expr from taylor form to canonical rational expression (CRE) form. The effect is the same as rat (ratdisrep (expr)), but faster.

Function: trunc (expr)

Annotates the internal representation of the general expression expr so that it is displayed as if its sums were truncated Taylor series. expr is not otherwise modified.

Example:

(%i1) expr: x^2 + x + 1;
                            2
(%o1)                      x  + x + 1
(%i2) trunc (expr);
                                2
(%o2)                  1 + x + x  + . . .
(%i3) is (expr = trunc (expr));
(%o3)                         true

Category: Fourier transform · Category: Share packages · Category: Package fourie

Function: unsum (f, n)

Returns the first backward difference f(n) - f(n - 1). Thus unsum in a sense is the inverse of sum.

28.4 Introduction to Fourier series

The fourie package comprises functions for the symbolic computation of Fourier series. There are functions in the fourie package to calculate Fourier integral coefficients and some functions for manipulation of expressions.

28.5 Functions and Variables for Fourier series

Function: equalp (x, y)

Returns true if equal (x, y) otherwise false (doesn’t give an error message like equal (x, y) would do in this case).

Function: remfun
remfun (f, expr)
remfun (f, expr, x)

remfun (f, expr) replaces all occurrences of f (arg) by arg in expr.

remfun (f, expr, x) replaces all occurrences of f (arg) by arg in expr only if arg contains the variable x.

Function: funp
funp (f, expr)
funp (f, expr, x)

funp (f, expr) returns true if expr contains the function f.

funp (f, expr, x) returns true if expr contains the function f and the variable x is somewhere in the argument of one of the instances of f.

Category: Package fourie · Category: Integral calculus

Function: absint
    absint (f, x, halfplane)
    absint (f, x)
    absint (f, x, a, b)

absint (f, x, halfplane) returns the indefinite integral of f with respect to x in the given halfplane (pos, neg, or both). f may contain expressions of the form abs (x), abs (sin (x)), abs (a) * exp (-abs (b) * abs (x)).

absint (f, x) is equivalent to absint (f, x, pos).

absint (f, x, a, b) returns the definite integral of f with respect to x from a to b. f may include absolute values.

Function: fourier (f, x, p)

Returns a list of the Fourier coefficients of f(x) defined on the interval [-p, p].

Category: Package fourie · Category: Trigonometric functions · Category: Simplification functions

Function: foursimp (l)

Simplifies sin (n %pi) to 0 if sinnpiflag is true and cos (n %pi) to (-1)^n if cosnpiflag is true.

Option variable: sinnpiflag

Default value: true

See foursimp.

Option variable: cosnpiflag

Default value: true

See foursimp.

Function: fourexpand (l, x, p, limit)

Constructs and returns the Fourier series from the list of Fourier coefficients l up through limit terms (limit may be inf). x and p have same meaning as in fourier.

Function: fourcos (f, x, p)

Returns the Fourier cosine coefficients for f(x) defined on [0, p].

Function: foursin (f, x, p)

Returns the Fourier sine coefficients for f(x) defined on [0, p].

Function: totalfourier (f, x, p)

Returns fourexpand (foursimp (fourier (f, x, p)), x, p, 'inf).

Function: fourint (f, x)

Constructs and returns a list of the Fourier integral coefficients of f(x) defined on [minf, inf].

Function: fourintcos (f, x)

Returns the Fourier cosine integral coefficients for f(x) on [0, inf].

Function: fourintsin (f, x)

Returns the Fourier sine integral coefficients for f(x) on [0, inf].

28.6 Functions and Variables for Poisson series

Function: intopois (a)

Converts a into a Poisson encoding.

Function: outofpois (a)

Converts a from Poisson encoding to general representation. If a is not in Poisson form, outofpois carries out the conversion, i.e., the return value is outofpois (intopois (a)). This function is thus a canonical simplifier for sums of powers of sine and cosine terms of a particular type.

Function: poisdiff (a, b)

Differentiates a with respect to b. b must occur only in the trig arguments or only in the coefficients.

Function: poisexpt (a, b)

Functionally identical to intopois (a^b). b must be a positive integer.

Function: poisint (a, b)

Integrates in a similarly restricted sense (to poisdiff). Non-periodic terms in b are dropped if b is in the trig arguments.

Option variable: poislim

Default value: 5

poislim determines the domain of the coefficients in the arguments of the trig functions. The initial value of 5 corresponds to the interval [-2^(5-1)+1,2^(5-1)], or [-15,16], but it can be set to [-2^(n-1)+1, 2^(n-1)].

Function: poismap (series, sinfn, cosfn)

will map the functions sinfn on the sine terms and cosfn on the cosine terms of the Poisson series given. sinfn and cosfn are functions of two arguments which are a coefficient and a trigonometric part of a term in series respectively.

Function: poisplus (a, b)

Is functionally identical to intopois (a + b).

Function: poissimp (a)

Converts a into a Poisson series for a in general representation.

Special symbol: poisson

The symbol /P/ follows the line label of Poisson series expressions.

Function: poissubst (a, b, c)

Substitutes a for b in c. c is a Poisson series.

(1) Where B is a variable u, v, w, x, y, or z, then a must be an expression linear in those variables (e.g., 6*u + 4*v).

(2) Where b is other than those variables, then a must also be free of those variables, and furthermore, free of sines or cosines.

poissubst (a, b, c, d, n) is a special type of substitution which operates on a and b as in type (1) above, but where d is a Poisson series, expands cos(d) and sin(d) to order n so as to provide the result of substituting a + d for b in c. The idea is that d is an expansion in terms of a small parameter. For example, poissubst (u, v, cos(v), %e, 3) yields cos(u)*(1 - %e^2/2) - sin(u)*(%e - %e^3/6).

Function: poistimes (a, b)

Is functionally identical to intopois (a*b).

Function: poistrim ()

is a reserved function name which (if the user has defined it) gets applied during Poisson multiplication. It is a predicate function of 6 arguments which are the coefficients of the u, v, ..., z in a term. Terms for which poistrim is true (for the coefficients of that term) are eliminated during multiplication.

Category: Poisson series · Category: Display functions

Function: printpois (a)

Prints a Poisson series in a readable format. In common with outofpois, it will convert a into a Poisson encoding first, if necessary.

29 Number Theory

29.1 Functions and Variables for Number Theory

Function: bern (n)

Returns the n’th Bernoulli number for integer n. Bernoulli numbers equal to zero are suppressed if zerobern is false.

30 Symmetries

30.1 Introduction to Symmetries

sym is a package for working with symmetric groups of polynomials.

It was written for Macsyma-Symbolics by Annick Valibouze (http://www-calfor.lip6.fr/~avb/). The algorithms are described in the following papers:

Fonctions symétriques et changements de bases. Annick Valibouze. EUROCAL’87 (Leipzig, 1987), 323–332, Lecture Notes in Comput. Sci 378. Springer, Berlin, 1989.
http://www.stix.polytechnique.fr/publications/1984-1994.html
Résolvantes et fonctions symétriques. Annick Valibouze. Proceedings of the ACM-SIGSAM 1989 International Symposium on Symbolic and Algebraic Computation, ISSAC’89 (Portland, Oregon). ACM Press, 390-399, 1989.
http://www-calfor.lip6.fr/~avb/DonneesTelechargeables/MesArticles/issac89ACMValibouze.pdf
Symbolic computation with symmetric polynomials, an extension to Macsyma. Annick Valibouze. Computers and Mathematics (MIT, USA, June 13-17, 1989), Springer-Verlag, New York Berlin, 308-320, 1989.
http://www.stix.polytechnique.fr/publications/1984-1994.html
Théorie de Galois Constructive. Annick Valibouze. Mémoire d’habilitation à diriger les recherches (HDR), Université P. et M. Curie (Paris VI), 1994.

Category: Group theory · Category: Polynomials · Category: Share packages · Category: Package sym

30.2 Functions and Variables for Symmetries

30.2.1 Changing bases

Function: comp2pui (n, L)

implements passing from the complete symmetric functions given in the list L to the elementary symmetric functions from 0 to n. If the list L contains fewer than n+1 elements, it will be completed with formal values of the type h1, h2, etc. If the first element of the list L exists, it specifies the size of the alphabet, otherwise the size is set to n.

(%i1) comp2pui (3, [4, g]);
                        2                    2
(%o1)    [4, g, 2 h2 - g , 3 h3 - g h2 + g (g  - 2 h2)]

Function: ele2pui (m, L)

goes from the elementary symmetric functions to the complete functions. Similar to comp2ele and comp2pui.

Other functions for changing bases: comp2ele.

Function: ele2comp (m, L)

Goes from the elementary symmetric functions to the compete functions. Similar to comp2ele and comp2pui.

Other functions for changing bases: comp2ele.

Function: elem (ele, sym, lvar)

decomposes the symmetric polynomial sym, in the variables contained in the list lvar, in terms of the elementary symmetric functions given in the list ele. If the first element of ele is given, it will be the size of the alphabet, otherwise the size will be the degree of the polynomial sym. If values are missing in the list ele, formal values of the type e1, e2, etc. will be added. The polynomial sym may be given in three different forms: contracted (elem should then be 1, its default value), partitioned (elem should be 3), or extended (i.e. the entire polynomial, and elem should then be 2). The function pui is used in the same way.

On an alphabet of size 3 with e1, the first elementary symmetric function, with value 7, the symmetric polynomial in 3 variables whose contracted form (which here depends on only two of its variables) is x^4-2*x*y decomposes as follows in elementary symmetric functions:

(%i1) elem ([3, 7], x^4 - 2*x*y, [x, y]);
(%o1) 7 (e3 - 7 e2 + 7 (49 - e2)) + 21 e3

                                         + (- 2 (49 - e2) - 2) e2

(%i2) ratsimp (%);
                              2
(%o2)             28 e3 + 2 e2  - 198 e2 + 2401

Other functions for changing bases: comp2ele.

Function: mon2schur (L)

The list L represents the Schur function S_L: we have L = [i_1, i_2, ..., i_q], with i_1 <= i_2 <= ... <= i_q. The Schur function S_[i_1, i_2, ..., i_q] is the minor of the infinite matrix h_[i-j], i <= 1, j <= 1, consisting of the q first rows and the columns 1 + i_1, 2 + i_2, ..., q + i_q.

This Schur function can be written in terms of monomials by using treinat and kostka. The form returned is a symmetric polynomial in a contracted representation in the variables x_1,x_2,...

(%i1) mon2schur ([1, 1, 1]);
(%o1)                       x1 x2 x3

(%i2) mon2schur ([3]);
                                  2        3
(%o2)                x1 x2 x3 + x1  x2 + x1

(%i3) mon2schur ([1, 2]);
                                      2
(%o3)                  2 x1 x2 x3 + x1  x2

which means that for 3 variables this gives:

   2 x1 x2 x3 + x1^2 x2 + x2^2 x1 + x1^2 x3 + x3^2 x1
    + x2^2 x3 + x3^2 x2

Other functions for changing bases: comp2ele.

Function: multi_elem (l_elem, multi_pc, l_var)

decomposes a multi-symmetric polynomial in the multi-contracted form multi_pc in the groups of variables contained in the list of lists l_var in terms of the elementary symmetric functions contained in l_elem.

(%i1) multi_elem ([[2, e1, e2], [2, f1, f2]], a*x + a^2 + x^3,
      [[x, y], [a, b]]);
                                                  3
(%o1)         - 2 f2 + f1 (f1 + e1) - 3 e1 e2 + e1

(%i2) ratsimp (%);
                         2                       3
(%o2)         - 2 f2 + f1  + e1 f1 - 3 e1 e2 + e1

Other functions for changing bases: comp2ele.

Function: multi_pui

is to the function pui what the function multi_elem is to the function elem.

(%i1) multi_pui ([[2, p1, p2], [2, t1, t2]], a*x + a^2 + x^3,
      [[x, y], [a, b]]);
                                            3
                                3 p1 p2   p1
(%o1)              t2 + p1 t1 + ------- - ---
                                   2       2

Function: pui (L, sym, lvar)

decomposes the symmetric polynomial sym, in the variables in the list lvar, in terms of the power functions in the list L. If the first element of L is given, it will be the size of the alphabet, otherwise the size will be the degree of the polynomial sym. If values are missing in the list L, formal values of the type p1, p2 , etc. will be added. The polynomial sym may be given in three different forms: contracted (elem should then be 1, its default value), partitioned (elem should be 3), or extended (i.e. the entire polynomial, and elem should then be 2). The function pui is used in the same way.

(%i1) pui;
(%o1)                           1

(%i2) pui ([3, a, b], u*x*y*z, [x, y, z]);
                       2
                   a (a  - b) u   (a b - p3) u
(%o2)              ------------ - ------------
                        6              3

(%i3) ratsimp (%);
                                       3
                      (2 p3 - 3 a b + a ) u
(%o3)                 ---------------------
                                6

Other functions for changing bases: comp2ele.

Function: pui2comp (n, lpui)

renders the list of the first n complete functions (with the length first) in terms of the power functions given in the list lpui. If the list lpui is empty, the cardinal is n, otherwise it is its first element (as in comp2ele and comp2pui).

(%i1) pui2comp (2, []);
                                       2
                                p2 + p1
(%o1)                   [2, p1, --------]
                                   2

(%i2) pui2comp (3, [2, a1]);
                                            2
                                 a1 (p2 + a1 )
                         2  p3 + ------------- + a1 p2
                  p2 + a1              2
(%o2)     [2, a1, --------, --------------------------]
                     2                  3

(%i3) ratsimp (%);
                            2                     3
                     p2 + a1   2 p3 + 3 a1 p2 + a1
(%o3)        [2, a1, --------, --------------------]
                        2               6

Other functions for changing bases: comp2ele.

Function: pui2ele (n, lpui)

effects the passage from power functions to the elementary symmetric functions. If the flag pui2ele is girard, it will return the list of elementary symmetric functions from 1 to n, and if the flag is close, it will return the n-th elementary symmetric function.

Other functions for changing bases: comp2ele.

Function: puireduc (n, lpui)

lpui is a list whose first element is an integer m. puireduc gives the first n power functions in terms of the first m.

(%i1) puireduc (3, [2]);
                                         2
                                   p1 (p1  - p2)
(%o1)          [2, p1, p2, p1 p2 - -------------]
                                         2

(%i2) ratsimp (%);
                                           3
                               3 p1 p2 - p1
(%o2)              [2, p1, p2, -------------]
                                     2

Function: schur2comp (P, l_var)

P is a polynomial in the variables of the list l_var. Each of these variables represents a complete symmetric function. In l_var the i-th complete symmetric function is represented by the concatenation of the letter h and the integer i: hi. This function expresses P in terms of Schur functions.

(%i1) schur2comp (h1*h2 - h3, [h1, h2, h3]);
(%o1)                         s
                               1, 2

(%i2) schur2comp (a*h3, [h3]);
(%o2)                         s  a
                               3

30.2.2 Changing representations

Function: cont2part (pc, lvar)

returns the partitioned polynomial associated to the contracted form pc whose variables are in lvar.

(%i1) pc: 2*a^3*b*x^4*y + x^5;
                           3    4      5
(%o1)                   2 a  b x  y + x

(%i2) cont2part (pc, [x, y]);
                                   3
(%o2)              [[1, 5, 0], [2 a  b, 4, 1]]

Function: contract (psym, lvar)

returns a contracted form (i.e. a monomial orbit under the action of the symmetric group) of the polynomial psym in the variables contained in the list lvar. The function explose performs the inverse operation. The function tcontract tests the symmetry of the polynomial.

(%i1) psym: explose (2*a^3*b*x^4*y, [x, y, z]);
         3      4      3      4      3    4        3    4
(%o1) 2 a  b y z  + 2 a  b x z  + 2 a  b y  z + 2 a  b x  z

                                           3      4      3    4
                                      + 2 a  b x y  + 2 a  b x  y

(%i2) contract (psym, [x, y, z]);
                              3    4
(%o2)                      2 a  b x  y

Function: explose (pc, lvar)

returns the symmetric polynomial associated with the contracted form pc. The list lvar contains the variables.

(%i1) explose (a*x + 1, [x, y, z]);
(%o1)                  a z + a y + a x + 1

Function: part2cont (ppart, lvar)

goes from the partitioned form to the contracted form of a symmetric polynomial. The contracted form is rendered with the variables in lvar.

(%i1) part2cont ([[2*a^3*b, 4, 1]], [x, y]);
                              3    4
(%o1)                      2 a  b x  y

Function: partpol (psym, lvar)

psym is a symmetric polynomial in the variables of the list lvar. This function retturns its partitioned representation.

(%i1) partpol (-a*(x + y) + 3*x*y, [x, y]);
(%o1)               [[3, 1, 1], [- a, 1, 0]]

Function: tcontract (pol, lvar)

tests if the polynomial pol is symmetric in the variables of the list lvar. If so, it returns a contracted representation like the function contract.

Function: tpartpol (pol, lvar)

tests if the polynomial pol is symmetric in the variables of the list lvar. If so, it returns its partitioned representation like the function partpol.

30.2.3 Groups and orbits

Function: direct ([p_1, ..., p_n], y, f, [lvar_1, ..., lvar_n])

calculates the direct image (see M. Giusti, D. Lazard et A. Valibouze, ISSAC 1988, Rome) associated to the function f, in the lists of variables lvar_1, ..., lvar_n, and in the polynomials p_1, ..., p_n in a variable y. The arity of the function f is important for the calulation. Thus, if the expression for f does not depend on some variable, it is useless to include this variable, and not including it will also considerably reduce the amount of computation.

(%i1) direct ([z^2  - e1* z + e2, z^2  - f1* z + f2],
              z, b*v + a*u, [[u, v], [a, b]]);
       2
(%o1) y  - e1 f1 y

                                 2            2             2   2
                  - 4 e2 f2 - (e1  - 2 e2) (f1  - 2 f2) + e1  f1
                + -----------------------------------------------
                                         2

(%i2) ratsimp (%);
              2                2                   2
(%o2)        y  - e1 f1 y + (e1  - 4 e2) f2 + e2 f1

(%i3) ratsimp (direct ([z^3-e1*z^2+e2*z-e3,z^2  - f1* z + f2],
              z, b*v + a*u, [[u, v], [a, b]]));
       6            5         2                        2    2   4
(%o3) y  - 2 e1 f1 y  + ((2 e1  - 6 e2) f2 + (2 e2 + e1 ) f1 ) y

                          3                               3   3
 + ((9 e3 + 5 e1 e2 - 2 e1 ) f1 f2 + (- 2 e3 - 2 e1 e2) f1 ) y

         2       2        4    2
 + ((9 e2  - 6 e1  e2 + e1 ) f2

                    2       2       2                   2    4
 + (- 9 e1 e3 - 6 e2  + 3 e1  e2) f1  f2 + (2 e1 e3 + e2 ) f1 )

  2          2                      2     3          2
 y  + (((9 e1  - 27 e2) e3 + 3 e1 e2  - e1  e2) f1 f2

                 2            2    3                5
 + ((15 e2 - 2 e1 ) e3 - e1 e2 ) f1  f2 - 2 e2 e3 f1 ) y

           2                   3           3     2   2    3
 + (- 27 e3  + (18 e1 e2 - 4 e1 ) e3 - 4 e2  + e1  e2 ) f2

         2      3                   3    2   2
 + (27 e3  + (e1  - 9 e1 e2) e3 + e2 ) f1  f2

                   2    4        2   6
 + (e1 e2 e3 - 9 e3 ) f1  f2 + e3  f1

Finding the polynomial whose roots are the sums a+u where a is a root of z^2 - e_1 z + e_2 and u is a root of z^2 - f_1 z + f_2.

(%i1) ratsimp (direct ([z^2 - e1* z + e2, z^2 - f1* z + f2],
                          z, a + u, [[u], [a]]));
       4                    3             2
(%o1) y  + (- 2 f1 - 2 e1) y  + (2 f2 + f1  + 3 e1 f1 + 2 e2

     2   2                              2               2
 + e1 ) y  + ((- 2 f1 - 2 e1) f2 - e1 f1  + (- 2 e2 - e1 ) f1

                  2                     2            2
 - 2 e1 e2) y + f2  + (e1 f1 - 2 e2 + e1 ) f2 + e2 f1  + e1 e2 f1

     2
 + e2

direct accepts two flags: elementaires and puissances (default) which allow decomposing the symmetric polynomials appearing in the calculation into elementary symmetric functions, or power functions, respectively.

Functions of sym used in this function:

multi_orbit (so orbit), pui_direct, multi_elem (so elem), multi_pui (so pui), pui2ele, ele2pui (if the flag direct is in puissances).

Function: multi_orbit (P, [lvar_1, lvar_2,..., lvar_p])

P is a polynomial in the set of variables contained in the lists lvar_1, lvar_2, ..., lvar_p. This function returns the orbit of the polynomial P under the action of the product of the symmetric groups of the sets of variables represented in these p lists.

(%i1) multi_orbit (a*x + b*y, [[x, y], [a, b]]);
(%o1)                [b y + a x, a y + b x]

(%i2) multi_orbit (x + y + 2*a, [[x, y], [a, b, c]]);
(%o2)        [y + x + 2 c, y + x + 2 b, y + x + 2 a]

Also see: orbit for the action of a single symmetric group.

Function: multsym (ppart_1, ppart_2, n)

returns the product of the two symmetric polynomials in n variables by working only modulo the action of the symmetric group of order n. The polynomials are in their partitioned form.

Given the 2 symmetric polynomials in x, y: 3*(x + y) + 2*x*y and 5*(x^2 + y^2) whose partitioned forms are [[3, 1], [2, 1, 1]] and [[5, 2]], their product will be

(%i1) multsym ([[3, 1], [2, 1, 1]], [[5, 2]], 2);
(%o1)         [[10, 3, 1], [15, 3, 0], [15, 2, 1]]

that is 10*(x^3*y + y^3*x) + 15*(x^2*y + y^2*x) + 15*(x^3 + y^3).

Functions for changing the representations of a symmetric polynomial:

contract, cont2part, explose, part2cont, partpol, tcontract, tpartpol.

Function: orbit (P, lvar)

computes the orbit of the polynomial P in the variables in the list lvar under the action of the symmetric group of the set of variables in the list lvar.

(%i1) orbit (a*x + b*y, [x, y]);
(%o1)                [a y + b x, b y + a x]

(%i2) orbit (2*x + x^2, [x, y]);
                        2         2
(%o2)                 [y  + 2 y, x  + 2 x]

See also multi_orbit for the action of a product of symmetric groups on a polynomial.

Function: pui_direct (orbite, [lvar_1, ..., lvar_n], [d_1, d_2, ..., d_n])

Let f be a polynomial in n blocks of variables lvar_1, ..., lvar_n. Let c_i be the number of variables in lvar_i, and SC be the product of n symmetric groups of degree c_1, ..., c_n. This group acts naturally on f. The list orbite is the orbit, denoted SC(f), of the function f under the action of SC. (This list may be obtained by the function multi_orbit.) The di are integers s.t. c_1 <= d_1, c_2 <= d_2, ..., c_n <= d_n.

Let SD be the product of the symmetric groups S_[d_1] x S_[d_2] x ... x S_[d_n]. The function pui_direct returns the first n power functions of SD(f) deduced from the power functions of SC(f), where n is the size of SD(f).

The result is in multi-contracted form w.r.t. SD, i.e. only one element is kept per orbit, under the action of SD.

(%i1) l: [[x, y], [a, b]];
(%o1)                   [[x, y], [a, b]]

(%i2) pui_direct (multi_orbit (a*x + b*y, l), l, [2, 2]);
                                       2  2
(%o2)               [a x, 4 a b x y + a  x ]

(%i3) pui_direct (multi_orbit (a*x + b*y, l), l, [3, 2]);
                             2  2     2    2        3  3
(%o3) [2 a x, 4 a b x y + 2 a  x , 3 a  b x  y + 2 a  x , 

    2  2  2  2      3    3        4  4
12 a  b  x  y  + 4 a  b x  y + 2 a  x , 

    3  2  3  2      4    4        5  5
10 a  b  x  y  + 5 a  b x  y + 2 a  x , 

    3  3  3  3       4  2  4  2      5    5        6  6
40 a  b  x  y  + 15 a  b  x  y  + 6 a  b x  y + 2 a  x ]

(%i4) pui_direct ([y + x + 2*c, y + x + 2*b, y + x + 2*a],
      [[x, y], [a, b, c]], [2, 3]);
                             2              2
(%o4) [3 x + 2 a, 6 x y + 3 x  + 4 a x + 4 a , 

                 2                   3        2       2        3
              9 x  y + 12 a x y + 3 x  + 6 a x  + 12 a  x + 8 a ]

30.2.4 Partitions

Function: kostka (part_1, part_2)

written by P. Esperet, calculates the Kostka number of the partition part_1 and part_2.

(%i1) kostka ([3, 3, 3], [2, 2, 2, 1, 1, 1]);
(%o1)                           6

Function: lgtreillis (n, m)

returns the list of partitions of weight n and length m.

(%i1) lgtreillis (4, 2);
(%o1)                   [[3, 1], [2, 2]]

Also see: ltreillis, treillis and treinat.

Function: ltreillis (n, m)

returns the list of partitions of weight n and length less than or equal to m.

(%i1) ltreillis (4, 2);
(%o1)               [[4, 0], [3, 1], [2, 2]]

Also see: lgtreillis, treillis and treinat.

Function: treillis (n)

returns all partitions of weight n.

(%i1) treillis (4);
(%o1)    [[4], [3, 1], [2, 2], [2, 1, 1], [1, 1, 1, 1]]

See also: lgtreillis, ltreillis and treinat.

Function: treinat (part)

retruns the list of partitions inferior to the partition part w.r.t. the natural order.

(%i1) treinat ([5]);
(%o1)                         [[5]]

(%i2) treinat ([1, 1, 1, 1, 1]);
(%o2) [[5], [4, 1], [3, 2], [3, 1, 1], [2, 2, 1], [2, 1, 1, 1], 

                                                 [1, 1, 1, 1, 1]]

(%i3) treinat ([3, 2]);
(%o3)                 [[5], [4, 1], [3, 2]]

See also: lgtreillis, ltreillis and treillis.

30.2.5 Polynomials and their roots

Function: ele2polynome (L, z)

returns the polynomial in z s.t. the elementary symmetric functions of its roots are in the list L = [n, e_1, ..., e_n], where n is the degree of the polynomial and e_i the i-th elementary symmetric function.

(%i1) ele2polynome ([2, e1, e2], z);
                          2
(%o1)                    z  - e1 z + e2

(%i2) polynome2ele (x^7 - 14*x^5 + 56*x^3  - 56*x + 22, x);
(%o2)          [7, 0, - 14, 0, 56, 0, - 56, - 22]

(%i3) ele2polynome ([7, 0, -14, 0, 56, 0, -56, -22], x);
                  7       5       3
(%o3)            x  - 14 x  + 56 x  - 56 x + 22

The inverse: polynome2ele (P, z).

Also see: polynome2ele, pui2polynome.

Function: polynome2ele (P, x)

gives the list l = [n, e_1, ..., e_n] where n is the degree of the polynomial P in the variable x and e_i is the i-the elementary symmetric function of the roots of P.

(%i1) polynome2ele (x^7 - 14*x^5 + 56*x^3 - 56*x + 22, x);
(%o1)          [7, 0, - 14, 0, 56, 0, - 56, - 22]

(%i2) ele2polynome ([7, 0, -14, 0, 56, 0, -56, -22], x);
                  7       5       3
(%o2)            x  - 14 x  + 56 x  - 56 x + 22

The inverse: ele2polynome (l, x)

Function: prodrac (L, k)

L is a list containing the elementary symmetric functions on a set A. prodrac returns the polynomial whose roots are the k by k products of the elements of A.

Also see somrac.

Function: pui2polynome (x, lpui)

calculates the polynomial in x whose power functions of the roots are given in the list lpui.

(%i1) pui;
(%o1)                           1

(%i2) kill(labels);
(%o0)                         done

(%i1) polynome2ele (x^3 - 4*x^2 + 5*x - 1, x);
(%o1)                     [3, 4, 5, 1]

(%i2) ele2pui (3, %);
(%o2)                     [3, 4, 6, 7]

(%i3) pui2polynome (x, %);
                        3      2
(%o3)                  x  - 4 x  + 5 x - 1

See also: polynome2ele, ele2polynome.

Function: somrac (L, k)

The list L contains elementary symmetric functions of a polynomial P . The function computes the polynomial whose roots are the k by k distinct sums of the roots of P.

Also see prodrac.

30.2.6 Resolvents

Function: resolvante (P, x, f, [x_1,..., x_d])

calculates the resolvent of the polynomial P in x of degree n >= d by the function f expressed in the variables x_1, ..., x_d. For efficiency of computation it is important to not include in the list [x_1, ..., x_d] variables which do not appear in the transformation function f.

To increase the efficiency of the computation one may set flags in resolvante so as to use appropriate algorithms:

If the function f is unitary:

A polynomial in a single variable,
linear,
alternating,
a sum,
symmetric,
a product,

the function of the Cayley resolvent (usable up to degree 5)

(x1*x2 + x2*x3 + x3*x4 + x4*x5 + x5*x1 -
     (x1*x3 + x3*x5 + x5*x2 + x2*x4 + x4*x1))^2

general,

the flag of resolvante may be, respectively:

unitaire,
lineaire,
alternee,
somme,
produit,
cayley,
generale.

(%i1) resolvante: unitaire$

(%i2) resolvante (x^7 - 14*x^5 + 56*x^3 - 56*x + 22, x, x^3 - 1,
      [x]);

" resolvante unitaire " [7, 0, 28, 0, 168, 0, 1120, - 154, 7840,
                         - 2772, 56448, - 33880, 

413952, - 352352, 3076668, - 3363360, 23114112, - 30494464, 

175230832, - 267412992, 1338886528, - 2292126760] 
  3       6      3       9      6      3
[x  - 1, x  - 2 x  + 1, x  - 3 x  + 3 x  - 1, 

 12      9      6      3       15      12       9       6      3
x   - 4 x  + 6 x  - 4 x  + 1, x   - 5 x   + 10 x  - 10 x  + 5 x

       18      15       12       9       6      3
 - 1, x   - 6 x   + 15 x   - 20 x  + 15 x  - 6 x  + 1, 

 21      18       15       12       9       6      3
x   - 7 x   + 21 x   - 35 x   + 35 x  - 21 x  + 7 x  - 1] 
[- 7, 1127, - 6139, 431767, - 5472047, 201692519, - 3603982011] 
       7      6        5         4          3           2
(%o2) y  + 7 y  - 539 y  - 1841 y  + 51443 y  + 315133 y

                                              + 376999 y + 125253

(%i3) resolvante: lineaire$

(%i4) resolvante (x^4 - 1, x, x1 + 2*x2 + 3*x3, [x1, x2, x3]);

" resolvante lineaire " 
       24       20         16            12             8
(%o4) y   + 80 y   + 7520 y   + 1107200 y   + 49475840 y

                                                    4
                                       + 344489984 y  + 655360000

(%i5) resolvante: general$

(%i6) resolvante (x^4 - 1, x, x1 + 2*x2 + 3*x3, [x1, x2, x3]);

" resolvante generale " 
       24       20         16            12             8
(%o6) y   + 80 y   + 7520 y   + 1107200 y   + 49475840 y

                                                    4
                                       + 344489984 y  + 655360000

(%i7) resolvante (x^4 - 1, x, x1 + 2*x2 + 3*x3, [x1, x2, x3, x4]);

" resolvante generale " 
       24       20         16            12             8
(%o7) y   + 80 y   + 7520 y   + 1107200 y   + 49475840 y

                                                    4
                                       + 344489984 y  + 655360000

(%i8) direct ([x^4 - 1], x, x1 + 2*x2 + 3*x3, [[x1, x2, x3]]);
       24       20         16            12             8
(%o8) y   + 80 y   + 7520 y   + 1107200 y   + 49475840 y

                                                    4
                                       + 344489984 y  + 655360000

(%i9) resolvante :lineaire$

(%i10) resolvante (x^4 - 1, x, x1 + x2 + x3, [x1, x2, x3]);

" resolvante lineaire " 
                              4
(%o10)                       y  - 1

(%i11) resolvante: symetrique$

(%i12) resolvante (x^4 - 1, x, x1 + x2 + x3, [x1, x2, x3]);

" resolvante symetrique " 
                              4
(%o12)                       y  - 1

(%i13) resolvante (x^4 + x + 1, x, x1 - x2, [x1, x2]);

" resolvante symetrique " 
                           6      2
(%o13)                    y  - 4 y  - 1

(%i14) resolvante: alternee$

(%i15) resolvante (x^4 + x + 1, x, x1 - x2, [x1, x2]);

" resolvante alternee " 
            12      8       6        4        2
(%o15)     y   + 8 y  + 26 y  - 112 y  + 216 y  + 229

(%i16) resolvante: produit$

(%i17) resolvante (x^7 - 7*x + 3, x, x1*x2*x3, [x1, x2, x3]);

" resolvante produit "
        35      33         29        28         27        26
(%o17) y   - 7 y   - 1029 y   + 135 y   + 7203 y   - 756 y

         24           23          22            21           20
 + 1323 y   + 352947 y   - 46305 y   - 2463339 y   + 324135 y

          19           18             17              15
 - 30618 y   - 453789 y   - 40246444 y   + 282225202 y

             14              12             11            10
 - 44274492 y   + 155098503 y   + 12252303 y   + 2893401 y

              9            8            7             6
 - 171532242 y  + 6751269 y  + 2657205 y  - 94517766 y

            5             3
 - 3720087 y  + 26040609 y  + 14348907

(%i18) resolvante: symetrique$

(%i19) resolvante (x^7 - 7*x + 3, x, x1*x2*x3, [x1, x2, x3]);

" resolvante symetrique " 
        35      33         29        28         27        26
(%o19) y   - 7 y   - 1029 y   + 135 y   + 7203 y   - 756 y

         24           23          22            21           20
 + 1323 y   + 352947 y   - 46305 y   - 2463339 y   + 324135 y

          19           18             17              15
 - 30618 y   - 453789 y   - 40246444 y   + 282225202 y

             14              12             11            10
 - 44274492 y   + 155098503 y   + 12252303 y   + 2893401 y

              9            8            7             6
 - 171532242 y  + 6751269 y  + 2657205 y  - 94517766 y

            5             3
 - 3720087 y  + 26040609 y  + 14348907

(%i20) resolvante: cayley$

(%i21) resolvante (x^5 - 4*x^2 + x + 1, x, a, []);

" resolvante de Cayley "
        6       5         4          3            2
(%o21) x  - 40 x  + 4080 x  - 92928 x  + 3772160 x  + 37880832 x

                                                       + 93392896

For the Cayley resolvent, the 2 last arguments are neutral and the input polynomial must necessarily be of degree 5.

Function: resolvante_alternee1 (P, x)

calculates the transformation P(x) of degree n by the function product(x_i - x_j, 1 <= i < j <= n - 1).

Function: resolvante_bipartite (P, x)

calculates the transformation of P(x) of even degree n by the function x_1 x_2 ... x_[n/2] + x_[n/2 + 1] ... x_n.

(%i1) resolvante_bipartite (x^6 + 108, x);
              10        8           6             4
(%o1)        y   - 972 y  + 314928 y  - 34012224 y

Function: resolvante_diedrale (P, x)

calculates the transformation of P(x) by the function x_1 x_2 + x_3 x_4.

(%i1) resolvante_diedrale (x^5 - 3*x^4 + 1, x);
       15       12       11       10        9         8         7
(%o1) x   - 21 x   - 81 x   - 21 x   + 207 x  + 1134 x  + 2331 x

        6         5          4          3          2
 - 945 x  - 4970 x  - 18333 x  - 29079 x  - 20745 x  - 25326 x

 - 697

Function: resolvante_klein (P, x)

calculates the transformation of P(x) by the function x_1 x_2 x_4 + x_4.

Function: resolvante_klein3 (P, x)

calculates the transformation of P(x) by the function x_1 x_2 x_4 + x_4.

Function: resolvante_produit_sym (P, x)

calculates the list of all product resolvents of the polynomial P(x).

(%i1) resolvante_produit_sym (x^5 + 3*x^4 + 2*x - 1, x);
        5      4             10      8       7       6       5
(%o1) [y  + 3 y  + 2 y - 1, y   - 2 y  - 21 y  - 31 y  - 14 y

    4       3      2       10      8       7    6       5       4
 - y  + 14 y  + 3 y  + 1, y   + 3 y  + 14 y  - y  - 14 y  - 31 y

       3      2       5      4
 - 21 y  - 2 y  + 1, y  - 2 y  - 3 y - 1, y - 1]

(%i2) resolvante: produit$

(%i3) resolvante (x^5 + 3*x^4 + 2*x - 1, x, a*b*c, [a, b, c]);

" resolvante produit "
       10      8       7    6        5       4       3     2
(%o3) y   + 3 y  + 14 y  - y  - 14 y  - 31 y  - 21 y  - 2 y  + 1

Function: resolvante_unitaire (P, Q, x)

computes the resolvent of the polynomial P(x) by the polynomial Q(x).

Function: resolvante_vierer (P, x)

computes the transformation of P(x) by the function x_1 x_2 - x_3 x_4.

30.2.7 Miscellaneous

Function: multinomial (r, part)

where r is the weight of the partition part. This function returns the associate multinomial coefficient: if the parts of part are i_1, i_2, ..., i_k, the result is r!/(i_1! i_2! ... i_k!).

Category: Package sym · Category: Lists

Function: permut (L)

returns the list of permutations of the list L.

31 Groups

31.1 Functions and Variables for Groups

Function: todd_coxeter
todd_coxeter (relations, subgroup)
todd_coxeter (relations)

Find the order of G/H where G is the Free Group modulo relations, and H is the subgroup of G generated by subgroup. subgroup is an optional argument, defaulting to []. In doing this it produces a multiplication table for the right action of G on G/H, where the cosets are enumerated [H,Hg2,Hg3,...]. This can be seen internally in the variable todd_coxeter_state.

Example:

(%i1) symet(n):=create_list(
        if (j - i) = 1 then (p(i,j))^^3 else
            if (not i = j) then (p(i,j))^^2 else
                p(i,i) , j, 1, n-1, i, 1, j);
                                                       <3>
(%o1) symet(n) := create_list(if j - i = 1 then p(i, j)

                                <2>
 else (if not i = j then p(i, j)    else p(i, i)), j, 1, n - 1,

i, 1, j)
(%i2) p(i,j) := concat(x,i).concat(x,j);
(%o2)        p(i, j) := concat(x, i) . concat(x, j)
(%i3) symet(5);
         <2>           <3>    <2>           <2>           <3>
(%o3) [x1   , (x1 . x2)   , x2   , (x1 . x3)   , (x2 . x3)   ,

            <2>           <2>           <2>           <3>    <2>
          x3   , (x1 . x4)   , (x2 . x4)   , (x3 . x4)   , x4   ]
(%i4) todd_coxeter(%o3);

Rows tried 426
(%o4)                          120
(%i5) todd_coxeter(%o3,[x1]);

Rows tried 213
(%o5)                          60
(%i6) todd_coxeter(%o3,[x1,x2]);

Rows tried 71
(%o6)                          20

Category: Group theory

32 Runtime Environment

32.1 Introduction for Runtime Environment

maxima-init.mac is a file which is loaded automatically when Maxima starts. You can use maxima-init.mac to customize your Maxima environment. maxima-init.mac, if it exists, is typically placed in the directory named by maxima_userdir, although it can be in any directory searched by the function file_search.

Here is an example maxima-init.mac file:

setup_autoload ("specfun.mac", ultraspherical, assoc_legendre_p);
showtime:all;

In this example, setup_autoload tells Maxima to load the specified file (specfun.mac) if any of the functions (ultraspherical, assoc_legendre_p) are called but not yet defined. Thus you needn’t remember to load the file before calling the functions.

The statement showtime: all tells Maxima to set the showtime variable. The maxima-init.mac file can contain any other assignments or other Maxima statements.

Category: Session management

32.2 Interrupts

The user can stop a time-consuming computation with the ^C (control-C) character. The default action is to stop the computation and print another user prompt. In this case, it is not possible to restart a stopped computation.

If the Lisp variable *debugger-hook* is set to nil, by executing

:lisp (setq *debugger-hook* nil)

then upon receiving ^C, Maxima will enter the Lisp debugger, and the user may use the debugger to inspect the Lisp environment. The stopped computation can be restarted by entering continue in the Lisp debugger. The means of returning to Maxima from the Lisp debugger (other than running the computation to completion) is different for each version of Lisp.

On Unix systems, the character ^Z (control-Z) causes Maxima to stop altogether, and control is returned to the shell prompt. The fg command causes Maxima to resume from the point at which it was stopped.

Category: Console interaction

32.3 Functions and Variables for Runtime Environment

System variable: maxima_tempdir

maxima_tempdir names the directory in which Maxima creates some temporary files. In particular, temporary files for plotting are created in maxima_tempdir.

The initial value of maxima_tempdir is the user’s home directory, if Maxima can locate it; otherwise Maxima makes a guess about a suitable directory.

maxima_tempdir may be assigned a string which names a directory.

Category: Global variables

System variable: maxima_userdir

maxima_userdir names a directory which Maxima searches to find Maxima and Lisp files. (Maxima searches some other directories as well; file_search_maxima and file_search_lisp are the complete lists.)

The initial value of maxima_userdir is a subdirectory of the user’s home directory, if Maxima can locate it; otherwise Maxima makes a guess about a suitable directory.

maxima_userdir may be assigned a string which names a directory. However, assigning to maxima_userdir does not automatically change file_search_maxima and file_search_lisp; those variables must be changed separately.

Category: Global variables

Function: room
    room ()
    room (true)
    room (false)

Prints out a description of the state of storage and stack management in Maxima. room calls the Lisp function of the same name.

room () prints out a moderate description.
room (true) prints out a verbose description.
room (false) prints out a terse description.

Function: sstatus (keyword, item)

When keyword is the symbol feature, item is put on the list of system features. After sstatus (keyword, item) is executed, status (feature, item) returns true. If keyword is the symbol nofeature, item is deleted from the list of system features. This can be useful for package writers, to keep track of what features they have loaded in.

33 Miscellaneous Options

33.1 Introduction to Miscellaneous Options

In this section various options are discussed which have a global effect on the operation of Maxima. Also various lists such as the list of all user defined functions, are discussed.

33.2 Share

The Maxima "share" directory contains programs and other files of interest to Maxima users, but not part of the core implementation of Maxima. These programs are typically loaded via load or setup_autoload.

:lisp *maxima-sharedir* displays the location of the share directory within the user’s file system.

printfile ("share.usg") prints an out-of-date list of share packages. Users may find it more informative to browse the share directory using a file system browser.

33.3 Functions and Variables for Miscellaneous Options

System variable: askexp

When asksign is called, askexp is the expression asksign is testing.

At one time, it was possible for a user to inspect askexp by entering a Maxima break with control-A.

Option variable: genindex

Default value: i

genindex is the alphabetic prefix used to generate the next variable of summation when necessary.

Option variable: gensumnum

Default value: 0

gensumnum is the numeric suffix used to generate the next variable of summation. If it is set to false then the index will consist only of genindex with no numeric suffix.

Category: Translation flags and variables

Function: gensym
gensym ()
gensym (x)

gensym() creates and returns a fresh symbol.

The name of the new symbol is the concatenation of a prefix, which defaults to "g", and a suffix, which is an integer that defaults to the value of an internal counter.

If x is supplied, and is a string, then that string is used as a prefix instead of "g" for this call to gensym only.

If x is supplied, and is a nonnegative integer, then that integer, instead of the value of the internal counter, is used as the suffix for this call to gensym only.

If and only if no explicit suffix is supplied, the internal counter is incremented after it is used.

Examples:

(%i1) gensym();
(%o1)                         g887
(%i2) gensym("new");
(%o2)                        new888
(%i3) gensym(123);
(%o3)                         g123

Option variable: packagefile

Default value: false

Package designers who use save or translate to create packages (files) for others to use may want to set packagefile: true to prevent information from being added to Maxima’s information-lists (e.g. values, functions) except where necessary when the file is loaded in. In this way, the contents of the package will not get in the user’s way when he adds his own data. Note that this will not solve the problem of possible name conflicts. Also note that the flag simply affects what is output to the package file. Setting the flag to true is also useful for creating Maxima init files.

Function: remvalue
remvalue (name_1, …, name_n)
remvalue remvalue (all)

Removes the values of user variables name_1, …, name_n (which can be subscripted) from the system.

remvalue (all) removes the values of all variables in values, the list of all variables given names by the user (as opposed to those which are automatically assigned by Maxima).

34 Rules and Patterns

34.1 Introduction to Rules and Patterns

This section describes user-defined pattern matching and simplification rules. There are two groups of functions which implement somewhat different pattern matching schemes. In one group are tellsimp, tellsimpafter, defmatch, defrule, apply1, applyb1, and apply2. In the other group are let and letsimp. Both schemes define patterns in terms of pattern variables declared by matchdeclare.

Pattern-matching rules defined by tellsimp and tellsimpafter are applied automatically by the Maxima simplifier. Rules defined by defmatch, defrule, and let are applied by an explicit function call.

There are additional mechanisms for rules applied to polynomials by tellrat, and for commutative and noncommutative algebra in affine package.

Category: Simplification · Category: Rules and patterns

34.2 Functions and Variables for Rules and Patterns

Function: apply1 (expr, rule_1, …, rule_n)

Repeatedly applies rule_1 to expr until it fails, then repeatedly applies the same rule to all subexpressions of expr, left to right, until rule_1 has failed on all subexpressions. Call the result of transforming expr in this manner expr_2. Then rule_2 is applied in the same fashion starting at the top of expr_2. When rule_n fails on the final subexpression, the result is returned.

maxapplydepth is the depth of the deepest subexpressions processed by apply1 and apply2.

35 Sets

35.1 Introduction to Sets

Maxima provides set functions, such as intersection and union, for finite sets that are defined by explicit enumeration. Maxima treats lists and sets as distinct objects. This feature makes it possible to work with sets that have members that are either lists or sets.

In addition to functions for finite sets, Maxima provides some functions related to combinatorics; these include the Stirling numbers of the first and second kind, the Bell numbers, multinomial coefficients, partitions of nonnegative integers, and a few others. Maxima also defines a Kronecker delta function.

35.1.1 Usage

To construct a set with members a_1, ..., a_n, write set(a_1, ..., a_n) or {a_1, ..., a_n}; to construct the empty set, write set() or {}. In input, set(...) and { ... } are equivalent. Sets are always displayed with curly braces.

If a member is listed more than once, simplification eliminates the redundant member.

(%i1) set();
(%o1)                          {}
(%i2) set(a, b, a);
(%o2)                        {a, b}
(%i3) set(a, set(b));
(%o3)                       {a, {b}}
(%i4) set(a, [b]);
(%o4)                       {a, [b]}
(%i5) {};
(%o5)                          {}
(%i6) {a, b, a};
(%o6)                        {a, b}
(%i7) {a, {b}};
(%o7)                       {a, {b}}
(%i8) {a, [b]};
(%o8)                       {a, [b]}

Two would-be elements x and y are redundant (i.e., considered the same for the purpose of set construction) if and only if is(x = y) yields true. Note that is(equal(x, y)) can yield true while is(x = y) yields false; in that case the elements x and y are considered distinct.

(%i1) x: a/c + b/c;
                              b   a
(%o1)                         - + -
                              c   c
(%i2) y: a/c + b/c;
                              b   a
(%o2)                         - + -
                              c   c
(%i3) z: (a + b)/c;
                              b + a
(%o3)                         -----
                                c
(%i4) is (x = y);
(%o4)                         true
(%i5) is (y = z);
(%o5)                         false
(%i6) is (equal (y, z));
(%o6)                         true
(%i7) y - z;
                           b + a   b   a
(%o7)                    - ----- + - + -
                             c     c   c
(%i8) ratsimp (%);
(%o8)                           0
(%i9) {x, y, z};
                          b + a  b   a
(%o9)                    {-----, - + -}
                            c    c   c

To construct a set from the elements of a list, use setify.

(%i1) setify ([b, a]);
(%o1)                        {a, b}

Set members x and y are equal provided is(x = y) evaluates to true. Thus rat(x) and x are equal as set members; consequently,

(%i1) {x, rat(x)};
(%o1)                          {x}

Further, since is((x - 1)*(x + 1) = x^2 - 1) evaluates to false, (x - 1)*(x + 1) and x^2 - 1 are distinct set members; thus

(%i1) {(x - 1)*(x + 1), x^2 - 1};
                                       2
(%o1)               {(x - 1) (x + 1), x  - 1}

To reduce this set to a singleton set, apply rat to each set member:

(%i1) {(x - 1)*(x + 1), x^2 - 1};
                                       2
(%o1)               {(x - 1) (x + 1), x  - 1}
(%i2) map (rat, %);
                              2
(%o2)/R/                    {x  - 1}

To remove redundancies from other sets, you may need to use other simplification functions. Here is an example that uses trigsimp:

(%i1) {1, cos(x)^2 + sin(x)^2};
                            2         2
(%o1)                {1, sin (x) + cos (x)}
(%i2) map (trigsimp, %);
(%o2)                          {1}

A set is simplified when its members are non-redundant and sorted. The current version of the set functions uses the Maxima function orderlessp to order sets; however, future versions of the set functions might use a different ordering function.

Some operations on sets, such as substitution, automatically force a re-simplification; for example,

(%i1) s: {a, b, c}$
(%i2) subst (c=a, s);
(%o2)                        {a, b}
(%i3) subst ([a=x, b=x, c=x], s);
(%o3)                          {x}
(%i4) map (lambda ([x], x^2), set (-1, 0, 1));
(%o4)                        {0, 1}

Maxima treats lists and sets as distinct objects; functions such as union and intersection complain if any argument is not a set. If you need to apply a set function to a list, use the setify function to convert it to a set. Thus

(%i1) union ([1, 2], {a, b});
Function union expects a set, instead found [1,2]
 -- an error.  Quitting.  To debug this try debugmode(true);
(%i2) union (setify ([1, 2]), {a, b});
(%o2)                     {1, 2, a, b}

To extract all set elements of a set s that satisfy a predicate f, use subset(s, f). (A predicate is a boolean-valued function.) For example, to find the equations in a given set that do not depend on a variable z, use

(%i1) subset ({x + y + z, x - y + 4, x + y - 5},
                                    lambda ([e], freeof (z, e)));
(%o1)               {- y + x + 4, y + x - 5}

The section Functions and Variables for Sets has a complete list of the set functions in Maxima.

Category: Sets

35.1.2 Set Member Iteration

There two ways to to iterate over set members. One way is the use map; for example:

(%i1) map (f, {a, b, c});
(%o1)                  {f(a), f(b), f(c)}

The other way is to use for x in s do

(%i1) s: {a, b, c};
(%o1)                       {a, b, c}
(%i2) for si in s do print (concat (si, 1));
a1 
b1 
c1 
(%o2)                         done

The Maxima functions first and rest work correctly on sets. Applied to a set, first returns the first displayed element of a set; which element that is may be implementation-dependent. If s is a set, then rest(s) is equivalent to disjoin(first(s), s). Currently, there are other Maxima functions that work correctly on sets. In future versions of the set functions, first and rest may function differently or not at all.

Maxima’s orderless and ordergreat mechanisms are incompatible with the set functions. If you need to use either orderless or ordergreat, call those functions before constructing any sets, and do not call unorder.

35.1.3 Authors

Stavros Macrakis of Cambridge, Massachusetts and Barton Willis of the University of Nebraska at Kearney (UNK) wrote the Maxima set functions and their documentation.

35.2 Functions and Variables for Sets

Function: adjoin (x, a)

Returns the union of the set a with {x}.

adjoin complains if a is not a literal set.

adjoin(x, a) and union(set(x), a) are equivalent; however, adjoin may be somewhat faster than union.

36 Function Definition

36.1 Introduction to Function Definition

36.2 Function

Category: Function definition · Category: Programming

36.2.1 Ordinary functions

To define a function in Maxima you use the := operator. E.g.

f(x) := sin(x)

defines a function f. Anonymous functions may also be created using lambda. For example

lambda ([i, j], ...)

can be used instead of f where

f(i,j) := block ([], ...);
map (lambda ([i], i+1), l)

would return a list with 1 added to each term.

You may also define a function with a variable number of arguments, by having a final argument which is assigned to a list of the extra arguments:

(%i1) f ([u]) := u;
(%o1)                      f([u]) := u
(%i2) f (1, 2, 3, 4);
(%o2)                     [1, 2, 3, 4]
(%i3) f (a, b, [u]) := [a, b, u];
(%o3)               f(a, b, [u]) := [a, b, u]
(%i4) f (1, 2, 3, 4, 5, 6);
(%o4)                 [1, 2, [3, 4, 5, 6]]

The right hand side of a function is an expression. Thus if you want a sequence of expressions, you do

f(x) := (expr1, expr2, ...., exprn);

and the value of exprn is what is returned by the function.

If you wish to make a return from some expression inside the function then you must use block and return.

block ([], expr1, ..., if (a > 10) then return(a), ..., exprn)

is itself an expression, and so could take the place of the right hand side of a function definition. Here it may happen that the return happens earlier than the last expression.

The first [] in the block, may contain a list of variables and variable assignments, such as [a: 3, b, c: []], which would cause the three variables a,b,and c to not refer to their global values, but rather have these special values for as long as the code executes inside the block, or inside functions called from inside the block. This is called dynamic binding, since the variables last from the start of the block to the time it exits. Once you return from the block, or throw out of it, the old values (if any) of the variables will be restored. It is certainly a good idea to protect your variables in this way. Note that the assignments in the block variables, are done in parallel. This means, that if you had used c: a in the above, the value of c would have been the value of a at the time you just entered the block, but before a was bound. Thus doing something like

block ([a: a], expr1, ... a: a+3, ..., exprn)

will protect the external value of a from being altered, but would let you access what that value was. Thus the right hand side of the assignments, is evaluated in the entering context, before any binding occurs. Using just block ([x], ...) would cause the x to have itself as value, just as if it would have if you entered a fresh Maxima session.

The actual arguments to a function are treated in exactly same way as the variables in a block. Thus in

f(x) := (expr1, ..., exprn);

and

f(1);

we would have a similar context for evaluation of the expressions as if we had done

block ([x: 1], expr1, ..., exprn)

Inside functions, when the right hand side of a definition, may be computed at runtime, it is useful to use define and possibly buildq.

36.2.2 Memoizing Functions

A memoizing function caches the result the first time it is called with a given argument, and returns the stored value, without recomputing it, when that same argument is given. Memoizing functions are often called array function and are in fact handled like arrays in many ways:

The names of memoizing functions are appended to the global list arrays (not the global list functions). arrayinfo returns the list of arguments for which there are stored values, and listarray returns the stored values. dispfun and fundef return the array function definition.

arraymake constructs an array function call, analogous to funmake for ordinary functions. arrayapply applies an array function to its arguments, analogous to apply for ordinary functions. There is nothing exactly analogous to map for array functions, although map(lambda([x], a[x]), L) or makelist(a[x], x, L), where L is a list, are not too far off the mark.

remarray removes an array function definition (including any stored function values), analogous to remfunction for ordinary functions.

kill(a[x]) removes the value of the array function a stored for the argument x; the next time a is called with argument x, the function value is recomputed. However, there is no way to remove all of the stored values at once, except for kill(a) or remarray(a), which also remove the function definition.

Examples

If evaluating the function needs much time and only a limited number of points is ever evaluated (which means not much time is spent looking up results in a long list of cached results) Memoizing functions can speed up calculations considerably.

(%i1) showtime:true$
Evaluation took 0.0000 seconds (0.0000 elapsed) using 0 bytes.

(%i2) a[x]:=float(sum(sin(x*t),t,1,10000));
Evaluation took 0.0000 seconds (0.0000 elapsed) using 0 bytes.
(%o2)        a  := float(sum(sin(x t), t, 1, 10000))
              x

(%i3) a[1];
Evaluation took 5.1250 seconds (5.1260 elapsed) using 775.250 MB.
(%o3)                   1.633891021792447

(%i4) a[1];
Evaluation took 0.0000 seconds (0.0000 elapsed) using 0 bytes.
(%o4)                   1.633891021792447

As the memoizing function is only evaluated once for each input value changes in variables the memoizing function uses are not considered for values that are already cached:

(%i1) a[x]:=b*x;
(%o1)                       a  := b x
                             x

(%i2) b:1;
(%o2)                           1

(%i3) a[2];
(%o3)                           2

(%i4) b:2;
(%o4)                           2

(%i5) a[1];
(%o5)                           2

(%i6) a[2];
(%o6)                           2

36.3 Macros

Function: buildq (L, expr)

Substitutes variables named by the list L into the expression expr, in parallel, without evaluating expr. The resulting expression is simplified, but not evaluated, after buildq carries out the substitution.

The elements of L are symbols or assignment expressions symbol: value, evaluated in parallel. That is, the binding of a variable on the right-hand side of an assignment is the binding of that variable in the context from which buildq was called, not the binding of that variable in the variable list L. If some variable in L is not given an explicit assignment, its binding in buildq is the same as in the context from which buildq was called.

Then the variables named by L are substituted into expr in parallel. That is, the substitution for every variable is determined before any substitution is made, so the substitution for one variable has no effect on any other.

If any variable x appears as splice (x) in expr, then x must be bound to a list, and the list is spliced (interpolated) into expr instead of substituted.

Any variables in expr not appearing in L are carried into the result verbatim, even if they have bindings in the context from which buildq was called.

Examples

a is explicitly bound to x, while b has the same binding (namely 29) as in the calling context, and c is carried through verbatim. The resulting expression is not evaluated until the explicit evaluation ''%.

(%i1) (a: 17, b: 29, c: 1729)$

(%i2) buildq ([a: x, b], a + b + c);
(%o2)                      x + c + 29

(%i3) ''%;
(%o3)                       x + 1758

e is bound to a list, which appears as such in the arguments of foo, and interpolated into the arguments of bar.

(%i1) buildq ([e: [a, b, c]], foo (x, e, y));
(%o1)                 foo(x, [a, b, c], y)

(%i2) buildq ([e: [a, b, c]], bar (x, splice (e), y));
(%o2)                  bar(x, a, b, c, y)

The result is simplified after substitution. If simplification were applied before substitution, these two results would be the same.

(%i1) buildq ([e: [a, b, c]], splice (e) + splice (e));
(%o1)                    2 c + 2 b + 2 a

(%i2) buildq ([e: [a, b, c]], 2 * splice (e));
(%o2)                        2 a b c

The variables in L are bound in parallel; if bound sequentially, the first result would be foo (b, b). Substitutions are carried out in parallel; compare the second result with the result of subst, which carries out substitutions sequentially.

(%i1) buildq ([a: b, b: a], foo (a, b));
(%o1)                       foo(b, a)

(%i2) buildq ([u: v, v: w, w: x, x: y, y: z, z: u],
              bar (u, v, w, x, y, z));
(%o2)                 bar(v, w, x, y, z, u)

(%i3) subst ([u=v, v=w, w=x, x=y, y=z, z=u],
             bar (u, v, w, x, y, z));
(%o3)                 bar(u, u, u, u, u, u)

Construct a list of equations with some variables or expressions on the left-hand side and their values on the right-hand side. macroexpand shows the expression returned by show_values.

(%i1) show_values ([L]) ::= buildq ([L], map ("=", 'L, L));
(%o1)   show_values([L]) ::= buildq([L], map("=", 'L, L))

(%i2) (a: 17, b: 29, c: 1729)$

(%i3) show_values (a, b, c - a - b);
(%o3)          [a = 17, b = 29, c - b - a = 1683]

(%i4) macroexpand (show_values (a, b, c - a - b));
(%o4)    map(=, '([a, b, c - b - a]), [a, b, c - b - a])

Given a function of several arguments, create another function for which some of the arguments are fixed.

(%i1) curry (f, [a]) :=
        buildq ([f, a], lambda ([[x]], apply (f, append (a, x))))$

(%i2) by3 : curry ("*", 3);
(%o2)        lambda([[x]], apply(*, append([3], x)))

(%i3) by3 (a + b);
(%o3)                       3 (b + a)

Category: Function definition

Function: macroexpand (expr)

Returns the macro expansion of expr without evaluating it, when expr is a macro function call. Otherwise, macroexpand returns expr.

If the expansion of expr yields another macro function call, that macro function call is also expanded.

macroexpand quotes its argument. However, if the expansion of a macro function call has side effects, those side effects are executed.

See also ::=, macros, and macroexpand1..

Examples

(%i1) g (x) ::= x / 99;
                                    x
(%o1)                      g(x) ::= --
                                    99

(%i2) h (x) ::= buildq ([x], g (x - a));
(%o2)            h(x) ::= buildq([x], g(x - a))

(%i3) a: 1234;
(%o3)                         1234

(%i4) macroexpand (h (y));
                              y - a
(%o4)                         -----
                               99

(%i5) h (y);
                            y - 1234
(%o5)                       --------
                               99

Category: Function application

Function: macroexpand1 (expr)

Returns the macro expansion of expr without evaluating it, when expr is a macro function call. Otherwise, macroexpand1 returns expr.

macroexpand1 quotes its argument. However, if the expansion of a macro function call has side effects, those side effects are executed.

If the expansion of expr yields another macro function call, that macro function call is not expanded.

See also ::=, macros, and macroexpand.

Examples

(%i1) g (x) ::= x / 99;
                                    x
(%o1)                      g(x) ::= --
                                    99

(%i2) h (x) ::= buildq ([x], g (x - a));
(%o2)            h(x) ::= buildq([x], g(x - a))

(%i3) a: 1234;
(%o3)                         1234

(%i4) macroexpand1 (h (y));
(%o4)                       g(y - a)

(%i5) h (y);
                            y - 1234
(%o5)                       --------
                               99

Category: Function application

Global variable: macros

Default value: []

macros is the list of user-defined macro functions. The macro function definition operator ::= puts a new macro function onto this list, and kill, remove, and remfunction remove macro functions from the list.

36.4 Functions and Variables for Function Definition

Function: apply (F, [x_1, …, x_n])

Constructs and evaluates an expression F(arg_1, ..., arg_n).

apply does not attempt to distinguish a memoizing function from an ordinary function; when F is the name of a memoizing function, apply evaluates F(...) (that is, a function call with parentheses instead of square brackets). arrayapply evaluates a function call with square brackets in this case.

37 Program Flow

37.1 Lisp and Maxima

Maxima is a fairly complete programming language. But since it is written in Lisp, it additionally can provide easy access to Lisp functions and variables from Maxima and vice versa. Lisp and Maxima symbols are distinguished by a naming convention. A Lisp symbol which begins with a dollar sign $ corresponds to a Maxima symbol without the dollar sign.

A Maxima symbol which begins with a question mark ? corresponds to a Lisp symbol without the question mark. For example, the Maxima symbol foo corresponds to the Lisp symbol $FOO, while the Maxima symbol ?foo corresponds to the Lisp symbol FOO. Note that ?foo is written without a space between ? and foo; otherwise it might be mistaken for describe ("foo").

Hyphen -, asterisk *, or other special characters in Lisp symbols must be escaped by backslash \ where they appear in Maxima code. For example, the Lisp identifier *foo-bar* is written ?\*foo\-bar\* in Maxima.

Lisp code may be executed from within a Maxima session. A single line of Lisp (containing one or more forms) may be executed by the special command :lisp. For example,

(%i1) :lisp (foo $x $y)

calls the Lisp function foo with Maxima variables x and y as arguments. The :lisp construct can appear at the interactive prompt or in a file processed by batch or demo, but not in a file processed by load, batchload, translate_file, or compile_file.

The function to_lisp opens an interactive Lisp session. Entering (to-maxima) closes the Lisp session and returns to Maxima.

Lisp functions and variables which are to be visible in Maxima as functions and variables with ordinary names (no special punctuation) must have Lisp names beginning with the dollar sign $.

Maxima is case-sensitive, distinguishing between lowercase and uppercase letters in identifiers. There are some rules governing the translation of names between Lisp and Maxima.

A Lisp identifier not enclosed in vertical bars corresponds to a Maxima identifier in lowercase. Whether the Lisp identifier is uppercase, lowercase, or mixed case, is ignored. E.g., Lisp $foo, $FOO, and $Foo all correspond to Maxima foo. But this is because $foo, $FOO and $Foo are converted by the Lisp reader by default to the Lisp symbol $FOO.
A Lisp identifier which is all uppercase or all lowercase and enclosed in vertical bars corresponds to a Maxima identifier with case reversed. That is, uppercase is changed to lowercase and lowercase to uppercase. E.g., Lisp |$FOO| and |$foo| correspond to Maxima foo and FOO, respectively.
A Lisp identifier which is mixed uppercase and lowercase and enclosed in vertical bars corresponds to a Maxima identifier with the same case. E.g., Lisp |$Foo| corresponds to Maxima Foo.

The #$ Lisp macro allows the use of Maxima expressions in Lisp code. #$expr$ expands to a Lisp expression equivalent to the Maxima expression expr.

(msetq $foo #$[x, y]$)

This has the same effect as entering

(%i1) foo: [x, y];

The Lisp function displa prints an expression in Maxima format.

(%i1) :lisp #$[x, y, z]$ 
((MLIST SIMP) $X $Y $Z)
(%i1) :lisp (displa '((MLIST SIMP) $X $Y $Z))
[x, y, z]
NIL

Functions defined in Maxima are not ordinary Lisp functions. The Lisp function mfuncall calls a Maxima function. For example:

(%i1) foo(x,y) := x*y$
(%i2) :lisp (mfuncall '$foo 'a 'b)
((MTIMES SIMP) A B)

Some Lisp functions are shadowed in the Maxima package, namely the following.

   complement     continue      //
   float          functionp     array
   exp            listen        signum
   atan           asin          acos
   asinh          acosh         atanh
   tanh           cosh          sinh
   tan            break         gcd

Category: Programming

37.2 Garbage Collection

One of the advantages of using lisp is that it uses “Garbage Collection”. In other words it automatically takes care of freeing memory occupied for example of intermediate results that were used during symbolic computation.

Garbage Collection avoids many errors frequently found in C programs (memory being freed too early, multiple times or not at all).

Function: garbage_collect ()

Tries to manually trigger the lisp’s garbage collection. This rarely is necessary as the lisp will employ an excellent algorithm for determining when to start garbage collection.

If maxima knows how to do manually trigger the garbage collection for the current lisp garbage_collect returns true, else false.

Category: Programming

37.3 Introduction to Program Flow

Maxima provides a do loop for iteration, as well as more primitive constructs such as go.

37.4 Functions and Variables for Program Flow

Function: backtrace
backtrace ()
backtrace (n)

Prints the call stack, that is, the list of functions which called the currently active function.

backtrace () prints the entire call stack.

backtrace (n) prints the n most recent functions, including the currently active function.

backtrace can be called from a script, a function, or the interactive prompt (not only in a debugging context).

Examples:

backtrace () prints the entire call stack.

(%i1) h(x) := g(x/7)$
(%i2) g(x) := f(x-11)$
(%i3) f(x) := e(x^2)$
(%i4) e(x) := (backtrace(), 2*x + 13)$
(%i5) h(10);
#0: e(x=4489/49)
#1: f(x=-67/7)
#2: g(x=10/7)
#3: h(x=10)
                              9615
(%o5)                         ----
                               49

backtrace (n) prints the n most recent functions, including the currently active function.

(%i1) h(x) := (backtrace(1), g(x/7))$
(%i2) g(x) := (backtrace(1), f(x-11))$
(%i3) f(x) := (backtrace(1), e(x^2))$
(%i4) e(x) := (backtrace(1), 2*x + 13)$
(%i5) h(10);
#0: h(x=10)
#0: g(x=10/7)
#0: f(x=-67/7)
#0: e(x=4489/49)
                              9615
(%o5)                         ----
                               49

Special operator: do

Special operator: while

Special operator: unless

Special operator: for

Special operator: from

Special operator: thru

Special operator: step

Special operator: next

Special operator: in

The do statement is used for performing iteration. The general form of the do statements maxima supports is:

for variable: initial_value step increment thru limit do body
for variable: initial_value step increment while condition do body
for variable: initial_value step increment unless condition do body
for variable in list do body

If the loop is expected to generate a list as output the command makelist may be the appropriate command to use instead, See Performance considerations for Lists.

initial_value, increment, limit, and body can be any expression. list is a list. If the increment is 1 then "step 1" may be omitted; As always, if body needs to contain more than one command these commands can be specified as a comma-separated list surrounded by parenthesis or as a block. Due to its great generality the do statement will be described in two parts. The first form of the do statement (which is shown in the first three items above) is analogous to that used in several other programming languages (Fortran, Algol, PL/I, etc.); then the other features will be mentioned.

The execution of the do statement proceeds by first assigning the initial_value to the variable (henceforth called the control-variable). Then: (1) If the control-variable has exceeded the limit of a thru specification, or if the condition of the unless is true, or if the condition of the while is false then the do terminates. (2) The body is evaluated. (3) The increment is added to the control-variable. The process from (1) to (3) is performed repeatedly until the termination condition is satisfied. One may also give several termination conditions in which case the do terminates when any of them is satisfied.

In general the thru test is satisfied when the control-variable is greater than the limit if the increment was non-negative, or when the control-variable is less than the limit if the increment was negative. The increment and limit may be non-numeric expressions as long as this inequality can be determined. However, unless the increment is syntactically negative (e.g. is a negative number) at the time the do statement is input, Maxima assumes it will be positive when the do is executed. If it is not positive, then the do may not terminate properly.

Note that the limit, increment, and termination condition are evaluated each time through the loop. Thus if any of these involve much computation, and yield a result that does not change during all the executions of the body, then it is more efficient to set a variable to their value prior to the do and use this variable in the do form.

The value normally returned by a do statement is the atom done. However, the function return may be used inside the body to exit the do prematurely and give it any desired value. Note however that a return within a do that occurs in a block will exit only the do and not the block. Note also that the go function may not be used to exit from a do into a surrounding block.

The control-variable is always local to the do and thus any variable may be used without affecting the value of a variable with the same name outside of the do. The control-variable is unbound after the do terminates.

(%i1) for a:-3 thru 26 step 7 do display(a)$
                             a = - 3

                              a = 4

                             a = 11

                             a = 18

                             a = 25

(%i1) s: 0$
(%i2) for i: 1 while i <= 10 do s: s+i;
(%o2)                         done
(%i3) s;
(%o3)                          55

Note that the condition while i <= 10 is equivalent to unless i > 10 and also thru 10.

(%i1) series: 1$
(%i2) term: exp (sin (x))$
(%i3) for p: 1 unless p > 7 do
          (term: diff (term, x)/p, 
           series: series + subst (x=0, term)*x^p)$
(%i4) series;
                  7    6     5    4    2
                 x    x     x    x    x
(%o4)            -- - --- - -- - -- + -- + x + 1
                 90   240   15   8    2

which gives 8 terms of the Taylor series for e^sin(x).

(%i1) poly: 0$
(%i2) for i: 1 thru 5 do
          for j: i step -1 thru 1 do
              poly: poly + i*x^j$
(%i3) poly;
                  5      4       3       2
(%o3)          5 x  + 9 x  + 12 x  + 14 x  + 15 x
(%i4) guess: -3.0$
(%i5) for i: 1 thru 10 do
          (guess: subst (guess, x, 0.5*(x + 10/x)),
           if abs (guess^2 - 10) < 0.00005 then return (guess));
(%o5)                  - 3.162280701754386

This example computes the negative square root of 10 using the Newton- Raphson iteration a maximum of 10 times. Had the convergence criterion not been met the value returned would have been done.

Instead of always adding a quantity to the control-variable one may sometimes wish to change it in some other way for each iteration. In this case one may use next expression instead of step increment. This will cause the control-variable to be set to the result of evaluating expression each time through the loop.

(%i6) for count: 2 next 3*count thru 20 do display (count)$
                            count = 2

                            count = 6

                           count = 18

As an alternative to for variable: value ...do... the syntax for variable from value ...do... may be used. This permits the from value to be placed after the step or next value or after the termination condition. If from value is omitted then 1 is used as the initial value.

Sometimes one may be interested in performing an iteration where the control-variable is never actually used. It is thus permissible to give only the termination conditions omitting the initialization and updating information as in the following example to compute the square-root of 5 using a poor initial guess.

(%i1) x: 1000$
(%i2) thru 20 do x: 0.5*(x + 5.0/x)$
(%i3) x;
(%o3)                   2.23606797749979
(%i4) sqrt(5), numer;
(%o4)                   2.23606797749979

If it is desired one may even omit the termination conditions entirely and just give do body which will continue to evaluate the body indefinitely. In this case the function return should be used to terminate execution of the do.

(%i1) newton (f, x):= ([y, df, dfx], df: diff (f ('x), 'x),
          do (y: ev(df), x: x - f(x)/y, 
              if abs (f (x)) < 5e-6 then return (x)))$
(%i2) sqr (x) := x^2 - 5.0$
(%i3) newton (sqr, 1000);
(%o3)                   2.236068027062195

(Note that return, when executed, causes the current value of x to be returned as the value of the do. The block is exited and this value of the do is returned as the value of the block because the do is the last statement in the block.)

One other form of the do is available in Maxima. The syntax is:

for variable in list end_tests do body

The elements of list are any expressions which will successively be assigned to the variable on each iteration of the body. The optional termination tests end_tests can be used to terminate execution of the do; otherwise it will terminate when the list is exhausted or when a return is executed in the body. (In fact, list may be any non-atomic expression, and successive parts are taken.)

(%i1)  for f in [log, rho, atan] do ldisp(f(1))$
(%t1)                                  0
(%t2)                                rho(1)
                                     %pi
(%t3)                                 ---
                                      4
(%i4) ev(%t3,numer);
(%o4)                             0.78539816

Category: Programming

Function: errcatch (expr_1, …, expr_n)

Evaluates expr_1, …, expr_n one by one and returns [expr_n] (a list) if no error occurs. If an error occurs in the evaluation of any argument, errcatch prevents the error from propagating and returns the empty list [] without evaluating any more arguments.

errcatch is useful in batch files where one suspects an error might occur which would terminate the batch if the error weren’t caught.

38 Debugging

38.1 Source Level Debugging

Maxima has a built-in source level debugger. The user can set a breakpoint at a function, and then step line by line from there. The call stack may be examined, together with the variables bound at that level.

The command :help or :h shows the list of debugger commands. (In general, commands may be abbreviated if the abbreviation is unique. If not unique, the alternatives will be listed.) Within the debugger, the user can also use any ordinary Maxima functions to examine, define, and manipulate variables and expressions.

A breakpoint is set by the :br command at the Maxima prompt. Within the debugger, the user can advance one line at a time using the :n (“next”) command. The :bt (“backtrace”) command shows a list of stack frames. The :r (“resume”) command exits the debugger and continues with execution. These commands are demonstrated in the example below.

(%i1) load ("/tmp/foobar.mac");

(%o1)                           /tmp/foobar.mac

(%i2) :br foo
Turning on debugging debugmode(true)
Bkpt 0 for foo (in /tmp/foobar.mac line 1) 

(%i2) bar (2,3);
Bkpt 0:(foobar.mac 1)
/tmp/foobar.mac:1::

(dbm:1) :bt                        <-- :bt typed here gives a backtrace
#0: foo(y=5)(foobar.mac line 1)
#1: bar(x=2,y=3)(foobar.mac line 9)

(dbm:1) :n                         <-- Here type :n to advance line
(foobar.mac 2)
/tmp/foobar.mac:2::

(dbm:1) :n                         <-- Here type :n to advance line
(foobar.mac 3)
/tmp/foobar.mac:3::

(dbm:1) u;                         <-- Investigate value of u
28

(dbm:1) u: 33;                     <-- Change u to be 33
33

(dbm:1) :r                         <-- Type :r to resume the computation

(%o2)                                1094

The file /tmp/foobar.mac is the following:

foo(y) := block ([u:y^2],
  u: u+3,
  u: u^2,
  u);
 
bar(x,y) := (
  x: x+2,
  y: y+2,
  x: foo(y),
  x+y);

USE OF THE DEBUGGER THROUGH EMACS

If the user is running the code under GNU emacs in a shell window (dbl shell), or is running the graphical interface version, Xmaxima, then if he stops at a break point, he will see his current position in the source file which will be displayed in the other half of the window, either highlighted in red, or with a little arrow pointing at the right line. He can advance single lines at a time by typing M-n (Alt-n).

Under Emacs you should run in a dbl shell, which requires the dbl.el file in the elisp directory. Make sure you install the elisp files or add the Maxima elisp directory to your path: e.g., add the following to your .emacs file or the site-init.el

(setq load-path (cons "/usr/share/maxima/5.9.1/emacs" load-path))
(autoload 'dbl "dbl")

then in emacs

M-x dbl

should start a shell window in which you can run programs, for example Maxima, gcl, gdb etc. This shell window also knows about source level debugging, and display of source code in the other window.

The user may set a break point at a certain line of the file by typing C-x space. This figures out which function the cursor is in, and then it sees which line of that function the cursor is on. If the cursor is on, say, line 2 of foo, then it will insert in the other window the command, “:br foo 2”, to break foo at its second line. To have this enabled, the user must have maxima-mode.el turned on in the window in which the file foobar.mac is visiting. There are additional commands available in that file window, such as evaluating the function into the Maxima, by typing Alt-Control-x.

38.2 Keyword Commands

Keyword commands are special keywords which are not interpreted as Maxima expressions. A keyword command can be entered at the Maxima prompt or the debugger prompt, although not at the break prompt. Keyword commands start with a colon, ’:’. For example, to evaluate a Lisp form you may type :lisp followed by the form to be evaluated.

(%i1) :lisp (+ 2 3) 
5

The number of arguments taken depends on the particular command. Also, you need not type the whole command, just enough to be unique among the break keywords. Thus :br would suffice for :break.

The keyword commands are listed below.

:break F n: Set a breakpoint in function F at line offset n from the beginning of the function. If F is given as a string, then it is assumed to be a file, and n is the offset from the beginning of the file. The offset is optional. If not given, it is assumed to be zero (first line of the function or file).
:bt: Print a backtrace of the stack frames
:continue: Continue the computation
:delete: Delete the specified breakpoints, or all if none are specified
:disable: Disable the specified breakpoints, or all if none are specified
:enable: Enable the specified breakpoints, or all if none are specified
:frame n: Print stack frame n, or the current frame if none is specified
:help: Print help on a debugger command, or all commands if none is specified
:info: Print information about item
:lisp some-form: Evaluate some-form as a Lisp form
:lisp-quiet some-form: Evaluate Lisp form some-form without any output
:next: Like :step, except :next steps over function calls
:quit: Quit the current debugger level without completing the computation
:resume: Continue the computation
:step: Continue the computation until it reaches a new source line
:top: Return to the Maxima prompt (from any debugger level) without completing the computation

Category: Debugging · Category: Global flags

38.3 Functions and Variables for Debugging

Option variable: debugmode

Default value: false

When a Maxima error occurs, Maxima will start the debugger if debugmode is true. The user may enter commands to examine the call stack, set breakpoints, step through Maxima code, and so on. See debugging for a list of debugger commands.

Enabling debugmode will not catch Lisp errors.

Option variable: refcheck

Default value: false

When refcheck is true, Maxima prints a message each time a bound variable is used for the first time in a computation.

Category: Evaluation · Category: Console interaction · Category: Global flags

Option variable: setcheck

Default value: false

If setcheck is set to a list of variables (which can be subscripted), Maxima prints a message whenever the variables, or subscripted occurrences of them, are bound with the ordinary assignment operator :, the :: assignment operator, or function argument binding, but not the function assignment := nor the macro assignment ::= operators. The message comprises the name of the variable and the value it is bound to.

setcheck may be set to all or true thereby including all variables.

Each new assignment of setcheck establishes a new list of variables to check, and any variables previously assigned to setcheck are forgotten.

The names assigned to setcheck must be quoted if they would otherwise evaluate to something other than themselves. For example, if x, y, and z are already bound, then enter

setcheck: ['x, 'y, 'z]$

to put them on the list of variables to check.

No printout is generated when a variable on the setcheck list is assigned to itself, e.g., X: 'X.

Category: Console interaction · Category: Global flags

Option variable: setcheckbreak

Default value: false

When setcheckbreak is true, Maxima will present a break prompt whenever a variable on the setcheck list is assigned a new value. The break occurs before the assignment is carried out. At this point, setval holds the value to which the variable is about to be assigned. Hence, one may assign a different value by assigning to setval.

39 alt-display

39.1 Introduction to alt-display

The alt-display package provides a means to change the way that Maxima displays its output. The *alt-display1d* and *alt-display2d* Lisp hooks were introduced to Maxima in 2002, but were not easily accessible from the Maxima REPL until the introduction of this package.

The package provides a general purpose function to define alternative display functions, and a separate function to set the display function. The package also provides customized display functions to produce output in TeX, Texinfo, XML and all three output formats within Texinfo.

Here is a sample session:

(%i1) load("alt-display.mac")$
(%i2) set_alt_display(2,tex_display)$

(%i3) x/(x^2+y^2) = 1;
\mbox{\tt\red({\it \%o_3}) \black}$${{x}\over{y^2+x^2}}=1$$

(%i4) set_alt_display(2,mathml_display)$

(%i5) x/(x^2+y^2) = 1;
<math xmlns="http://www.w3.org/1998/Math/MathML"> <mi>mlabel</mi> 
<mfenced separators=""><msub><mi>%o</mi> <mn>5</mn></msub> 
<mo>,</mo><mfrac><mrow><mi>x</mi> </mrow> <mrow><msup><mrow>
<mi>y</mi> </mrow> <mn>2</mn> </msup> <mo>+</mo> <msup><mrow>
<mi>x</mi> </mrow> <mn>2</mn> </msup> </mrow></mfrac> <mo>=</mo> 
<mn>1</mn> </mfenced> </math>

(%i6) set_alt_display(2,multi_display_for_texinfo)$

(%i7) x/(x^2+y^2) = 1;

@iftex
@tex
\mbox{\tt\red({\it \%o_7}) \black}$${{x}\over{y^2+x^2}}=1$$
@end tex
@end iftex
@ifhtml
@html

<math xmlns="http://www.w3.org/1998/Math/MathML"> <mi>mlabel</mi> 
<mfenced separators=""><msub><mi>%o</mi> <mn>7</mn></msub> 
<mo>,</mo><mfrac><mrow><mi>x</mi> </mrow> <mrow><msup><mrow>
<mi>y</mi> </mrow> <mn>2</mn> </msup> <mo>+</mo> <msup><mrow>
<mi>x</mi> </mrow> <mn>2</mn> </msup> </mrow></mfrac> <mo>=</mo> 
<mn>1</mn> </mfenced> </math>
@end html
@end ifhtml
@ifinfo
@example
(%o7) x/(y^2+x^2) = 1
@end example
@end ifinfo

If the alternative display function causes an error, the error is trapped and the display function is reset to the default display. In the following example, the error function is set to display the output. This throws an error, which is handled by resetting the 2d-display to the default.

(%i8) set_alt_display(2,?error)$

(%i9) x;

Error in *alt-display2d*.
Messge: Condition designator ((MLABEL) $%O9 $X) is not of type (OR SYMBOL STRING
                                                             FUNCTION).
*alt-display2d* reset to nil.
 -- an error. To debug this try: debugmode(true);

(%i10) x;
(%o10)                                 x

39.2 Functions and Variables for alt-display

Function: define_alt_display (function(input), expr)

This function is similar to define: it evaluates its arguments and expands into a function definition. The function is a function of a single input input. For convenience, a substitution is applied to expr after evaluation, to provide easy access to Lisp variable names.

Set a time-stamp on each prompt:

(%i1) load("alt-display.mac")$

(%i2) display2d:false$

(%i3) define_alt_display(time_stamp(x),
                   block([alt_display1d:false,alt_display2d:false],
                         prompt_prefix:printf(false,"~a~%",timedate()),
                         displa(x)));

(%o3) time_stamp(x):=block([\*alt\-display1d\*:false,
                            \*alt\-display2d\*:false],
                 \*prompt\-prefix\*:printf(false,"~a~%",timedate()),displa(x))
(%i4) set_alt_display(1,time_stamp);

(%o4) done
2017-11-27 16:15:58-06:00
(%i5)

The input line %i3 defines time_stamp using define_alt_display. The output line %o3 shows that the Maxima variable names alt_display1d, alt_display2d and prompt_prefix have been replaced by their Lisp translations, as has displa been replaced by ?displa (the display function).

The display variables alt_display1d and alt_display2d are both bound to false in the body of time_stamp to prevent an infinite recursion in displa.

Function: info_display (form)

This is an alias for the default 1-d display function. It may be used as an alternative 1-d or 2-d display function.

(%i1) load("alt-display.mac")$

(%i2) set_alt_display(2,info_display);

(%o2) done
(%i3) x/y;

(%o3) x/y

Function: mathml_display (form)

Produces MathML output.

(%i1) load("alt-display.mac")$

(%i2) set_alt_display(2,mathml_display);
<math xmlns="http://www.w3.org/1998/Math/MathML"> <mi>mlabel</mi> 
 <mfenced separators=""><msub><mi>%o</mi> <mn>2</mn></msub> 
 <mo>,</mo><mi>done</mi> </mfenced> </math>

Function: tex_display (form)

Produces TeX output.

(%i2) set_alt_display(2,tex_display);
\mbox{\tt\red({\it \%o_2}) \black}$$\mathbf{done}$$
(%i3) x/(x^2+y^2);
\mbox{\tt\red({\it \%o_3}) \black}$${{x}\over{y^2+x^2}}$$

Function: multi_display_for_texinfo (form)

Produces Texinfo output using all three display functions.

(%i2) set_alt_display(2,multi_display_for_texinfo)$

(%i3) x/(x^2+y^2);

@iftex
@tex
\mbox{\tt\red({\it \%o_3}) \black}$${{x}\over{y^2+x^2}}$$
@end tex
@end iftex
@ifhtml
@html

   <math xmlns="http://www.w3.org/1998/Math/MathML"> <mi>mlabel</mi> 
   <mfenced separators=""><msub><mi>%o</mi> <mn>3</mn></msub> 
   <mo>,</mo><mfrac><mrow><mi>x</mi> </mrow> <mrow><msup><mrow>
   <mi>y</mi> </mrow> <mn>2</mn> </msup> <mo>+</mo> <msup><mrow>
   <mi>x</mi> </mrow> <mn>2</mn> </msup> </mrow></mfrac> </mfenced> </math>
@end html
@end ifhtml
@ifinfo
@example
(%o3) x/(y^2+x^2)
@end example
@end ifinfo

Functions: reset_displays ()

Resets the prompt prefix and suffix to the empty string, and sets both 1-d and 2-d display functions to the default.

Function: set_alt_display (num, display-function)

The input num is the display to set; it may be either 1 or 2. The second input display-function is the display function to use. The display function may be either a Maxima function or a lambda expression.

Here is an example where the display function is a lambda expression; it just displays the result as TeX.

(%i1) load("alt-display.mac")$

(%i2) set_alt_display(2, lambda([form], tex(?caddr(form))))$

(%i3) integrate(exp(-t^2),t,0,inf);
$${{\sqrt{\pi}}\over{2}}$$

A user-defined display function should take care that it prints its output. A display function that returns a string will appear to display nothing, nor cause any errors.

Function: set_prompt (fix, expr)

Set the prompt prefix or suffix to expr. The input fix must evaluate to one of prefix, suffix, general, prolog or epilog. The input expr must evaluate to either a string or false; if false, the fix is reset to the default value.

(%i1) load("alt-display.mac")$
(%i2) set_prompt('prefix,printf(false,"It is now: ~a~%",timedate()))$

It is now: 2014-01-07 15:23:23-05:00
(%i3)

The following example shows the effect of each option, except prolog. Note that the epilog prompt is printed as Maxima closes down. The general is printed between the end of input and the output, unless the input line ends in $.

Here is an example to show where the prompt strings are placed.

(%i1) load("alt-display.mac")$

(%i2) set_prompt(prefix,"<<prefix>> ",suffix,"<<suffix>> ",general,
           printf(false,"<<general>>~%"),epilog,printf(false,"<<epilog>>~%"));

(%o2)                                done
<<prefix>> (%i3) <<suffix>> x/y;
<<general>>
                                       x
(%o3)                                  -
                                       y
<<prefix>> (%i4) <<suffix>> quit();
<<general>>
<<epilog>>

Here is an example that shows how to colorize the input and output when Maxima is running in a terminal or terminal emulator like Emacs⁸.

Each prompt string starts with the ASCII escape character (27) followed by an open square bracket (91); each string ends with a lower-case m (109). The webpages http://misc.flogisoft.com/bash/tip_colors_and_formatting and http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html provide information on how to use control strings to set the terminal colors.

Category: Number theory · Category: Binary operations · Category: Package bitwise

40 asympa

40.1 Introduction to asympa

Function: asympa

asympa is a package for asymptotic analysis. The package contains simplification functions for asymptotic analysis, including the “big O” and “little o” functions that are widely used in complexity analysis and numerical analysis.

load ("asympa") loads this package.

Category: Package asympa

40.2 Functions and variables for asympa

41 augmented_lagrangian

41.1 Functions and Variables for augmented_lagrangian

Function: augmented_lagrangian_method
    augmented_lagrangian_method (FOM, xx, C, yy)
    augmented_lagrangian_method (FOM, xx, C, yy, optional_args)
    augmented_lagrangian_method ([FOM, grad], xx, C, yy)
    augmented_lagrangian_method ([FOM, grad], xx, C, yy, optional_args)

Returns an approximate minimum of the expression FOM with respect to the variables xx, holding the constraints C equal to zero. yy is a list of initial guesses for xx. The method employed is the augmented Lagrangian method (see Refs [1] and [2]).

grad, if present, is the gradient of FOM with respect to xx, represented as a list of expressions, one for each variable in xx. If not present, the gradient is constructed automatically.

FOM and each element of grad, if present, must be ordinary expressions, not names of functions or lambda expressions.

optional_args represents additional arguments, specified as symbol = value. The optional arguments recognized are:

niter: Number of iterations of the augmented Lagrangian algorithm
lbfgs_tolerance: Tolerance supplied to LBFGS
iprint: IPRINT parameter (a list of two integers which controls verbosity) supplied to LBFGS
%lambda: Initial value of %lambda to be used for calculating the augmented Lagrangian

This implementation minimizes the augmented Lagrangian by applying the limited-memory BFGS (LBFGS) algorithm, which is a quasi-Newton algorithm.

load("augmented_lagrangian") loads this function.

42 Bernstein

42.1 Functions and Variables for Bernstein

Function: bernstein_poly (k, n, x)

Provided k is not a negative integer, the Bernstein polynomials are defined by bernstein_poly(k,n,x) = binomial(n,k) x^k (1-x)^(n-k); for a negative integer k, the Bernstein polynomial bernstein_poly(k,n,x) vanishes. When either k or n are non integers, the option variable bernstein_explicit controls the expansion of the Bernstein polynomials into its explicit form; example:

(%i1) load("bernstein")$

(%i2) bernstein_poly(k,n,x);
(%o2)                bernstein_poly(k, n, x)
(%i3) bernstein_poly(k,n,x), bernstein_explicit : true;
                                       n - k  k
(%o3)            binomial(n, k) (1 - x)      x

The Bernstein polynomials have both a gradef property and an integrate property:

(%i4) diff(bernstein_poly(k,n,x),x);
(%o4) (bernstein_poly(k - 1, n - 1, x)
                                 - bernstein_poly(k, n - 1, x)) n
(%i5) integrate(bernstein_poly(k,n,x),x);
(%o5) 
                                                            k + 1
 hypergeometric([k + 1, k - n], [k + 2], x) binomial(n, k) x
 ----------------------------------------------------------------
                              k + 1

For numeric inputs, both real and complex, the Bernstein polynomials evaluate to a numeric result:

(%i6) bernstein_poly(5,9, 1/2 + %i);
                        39375 %i   39375
(%o6)                   -------- + -----
                          128       256
(%i7) bernstein_poly(5,9, 0.5b0 + %i);
(%o7)           3.076171875b2 %i + 1.5380859375b2

To use bernstein_poly, first load("bernstein").

Variable: bernstein_explicit

Default value: false

When either k or n are non integers, the option variable bernstein_explicit controls the expansion of bernstein(k,n,x) into its explicit form; example:

(%i1) bernstein_poly(k,n,x);
(%o1)                bernstein_poly(k, n, x)
(%i2) bernstein_poly(k,n,x), bernstein_explicit : true;
                                       n - k  k
(%o2)            binomial(n, k) (1 - x)      x

When both k and n are explicitly integers, bernstein(k,n,x) always expands to its explicit form.

Function: multibernstein_poly ([k1,k2,…, kp], [n1,n2,…, np], [x1,x2,…, xp])

The multibernstein polynomial multibernstein_poly ([k1, k2, ..., kp], [n1, n2, ..., np], [x1, x2, ..., xp]) is the product of bernstein polynomials bernstein_poly(k1, n1, x1) bernstein_poly(k2, n2, x2) ... bernstein_poly(kp, np, xp).

To use multibernstein_poly, first load("bernstein").

Function: bernstein_approx (f, [x1, x1, …, xn], n)

Return the n-th order uniform Bernstein polynomial approximation for the function (x1, x2, ..., xn) |--> f. Examples

(%i1) bernstein_approx(f(x),[x], 2);
                 2       1                          2
(%o1)      f(1) x  + 2 f(-) (1 - x) x + f(0) (1 - x)
                         2
(%i2) bernstein_approx(f(x,y),[x,y], 2);
               2  2       1                2
(%o2) f(1, 1) x  y  + 2 f(-, 1) (1 - x) x y
                          2
                  2  2          1   2
 + f(0, 1) (1 - x)  y  + 2 f(1, -) x  (1 - y) y
                                2
       1  1                               1         2
 + 4 f(-, -) (1 - x) x (1 - y) y + 2 f(0, -) (1 - x)  (1 - y) y
       2  2                               2
            2        2       1                      2
 + f(1, 0) x  (1 - y)  + 2 f(-, 0) (1 - x) x (1 - y)
                             2
                  2        2
 + f(0, 0) (1 - x)  (1 - y)

To use bernstein_approx, first load("bernstein").

Function: bernstein_expand (e, [x1, x1, …, xn])

Express the polynomial e exactly as a linear combination of multi-variable Bernstein polynomials.

(%i1) bernstein_expand(x*y+1,[x,y]);
(%o1)    2 x y + (1 - x) y + x (1 - y) + (1 - x) (1 - y)
(%i2) expand(%);
(%o2)                        x y + 1

Maxima signals an error when the first argument isn’t a polynomial.

To use bernstein_expand, first load("bernstein").

43 bitwise

The package bitwise provides functions that allow to manipulate bits of integer constants. As always maxima attempts to simplify the result of the operation if the actual value of a constant isn’t known considering attributes that might be known for the variables, see the declare mechanism.

43.1 Functions and Variables for bitwise

Function: bit_not (int)

Inverts all bits of a signed integer. The result of this action reads -int - 1.

(%i1) load("bitwise")$

(%i2) bit_not(i);
(%o2)                      bit_not(i)

(%i3) bit_not(bit_not(i));
(%o3)                           i

(%i4) bit_not(3);
(%o4)                          - 4

(%i5) bit_not(100);
(%o5)                         - 101

(%i6) bit_not(-101);
(%o6)                          100

Function: bit_and (int1, ...)

This function calculates a bitwise and of two or more signed integers.

(%i1) load("bitwise")$

(%i2) bit_and(i,i);
(%o2)                           i

(%i3) bit_and(i,i,i);
(%o3)                           i

(%i4) bit_and(1,3);
(%o4)                           1

(%i5) bit_and(-7,7);
(%o5)                           1

If it is known if one of the parameters to bit_and is even this information is taken into consideration by the function.

(%i1) load("bitwise")$

(%i2) declare(e,even,o,odd);
(%o2)                         done

(%i3) bit_and(1,e);
(%o3)                           0

(%i4) bit_and(1,o);
(%o4)                           1

Category: Number theory · Category: Binary operations · Category: Package bitwise

Function: bit_or (int1, ...)

This function calculates a bitwise or of two or more signed integers.

(%i1) load("bitwise")$

(%i2) bit_or(i,i);
(%o2)                           i

(%i3) bit_or(i,i,i);
(%o3)                           i

(%i4) bit_or(1,3);
(%o4)                           3

(%i5) bit_or(-7,7);
(%o5)                          - 1

If it is known if one of the parameters to bit_or is even this information is taken into consideration by the function.

(%i1) load("bitwise")$

(%i2) declare(e,even,o,odd);
(%o2)                         done

(%i3) bit_or(1,e);
(%o3)                         e + 1

(%i4) bit_or(1,o);
(%o4)                           o

Category: Number theory · Category: Binary operations · Category: Package bitwise

Function: bit_xor (int1, ...)

This function calculates a bitwise or of two or more signed integers.

(%i1) load("bitwise")$

(%i2) bit_xor(i,i);
(%o2)                           0

(%i3) bit_xor(i,i,i);
(%o3)                           i

(%i4) bit_xor(1,3);
(%o4)                           2

(%i5) bit_xor(-7,7);
(%o5)                          - 2

If it is known if one of the parameters to bit_xor is even this information is taken into consideration by the function.

(%i1) load("bitwise")$

(%i2) declare(e,even,o,odd);
(%o2)                         done

(%i3) bit_xor(1,e);
(%o3)                         e + 1

(%i4) bit_xor(1,o);
(%o4)                         o - 1

Category: Number theory · Category: Binary operations · Category: Package bitwise

Function: bit_lsh (int, nBits)

This function shifts all bits of the signed integer int to the left by nBits bits. The width of the integer is extended by nBits for this process. The result of bit_lsh therefore is int * 2.

(%i1) load("bitwise")$

(%i2) bit_lsh(0,1);
(%o2)                           0

(%i3) bit_lsh(1,0);
(%o3)                           1

(%i4) bit_lsh(1,1);
(%o4)                           2

(%i5) bit_lsh(1,i);
(%o5)                     bit_lsh(1, i)

(%i6) bit_lsh(-3,1);
(%o6)                          - 6

(%i7) bit_lsh(-2,1);
(%o7)                          - 4

Category: Number theory · Category: Binary operations · Category: Package bitwise

Function: bit_rsh (int, nBits)

This function shifts all bits of the signed integer int to the right by nBits bits. The width of the integer is reduced by nBits for this process.

(%i1) load("bitwise")$

(%i2) bit_rsh(0,1);
(%o2)                           0

(%i3) bit_rsh(2,0);
(%o3)                           2

(%i4) bit_rsh(2,1);
(%o4)                           1

(%i5) bit_rsh(2,2);
(%o5)                           0

(%i6) bit_rsh(-3,1);
(%o6)                          - 2

(%i7) bit_rsh(-2,1);
(%o7)                          - 1

(%i8) bit_rsh(-2,2);
(%o8)                          - 1

Category: Number theory · Category: Binary operations · Category: Package bitwise

Function: bit_length (int)

determines how many bits a variable needs to be long in order to store the number int. This function only operates on positive numbers.

(%i1) load("bitwise")$

(%i2) bit_length(0);
(%o2)                           0

(%i3) bit_length(1);
(%o3)                           1

(%i4) bit_length(7);
(%o4)                           3

(%i5) bit_length(8);
(%o5)                           4

Category: Number theory · Category: Binary operations · Category: Package bitwise

Function: bit_onep (int, nBit)

determines if bits nBit is set in the signed integer int.

(%i1) load("bitwise")$

(%i2) bit_onep(85,0);
(%o2)                         true

(%i3) bit_onep(85,1);
(%o3)                         false

(%i4) bit_onep(85,2);
(%o4)                         true

(%i5) bit_onep(85,3);
(%o5)                         false

(%i6) bit_onep(85,100);
(%o6)                         false

(%i7) bit_onep(i,100);
(%o7)                   bit_onep(i, 100)

For signed numbers the sign bit is interpreted to be more than nBit to the left of the leftmost bit of int that reads 1.

(%i1) load("bitwise")$

(%i2) bit_onep(-2,0);
(%o2)                         false

(%i3) bit_onep(-2,1);
(%o3)                         true

(%i4) bit_onep(-2,2);
(%o4)                         true

(%i5) bit_onep(-2,3);
(%o5)                         true

(%i6) bit_onep(-2,4);
(%o6)                         true

If it is known if the number to be tested is even this information is taken into consideration by the function.

(%i1) load("bitwise")$

(%i2) declare(e,even,o,odd);
(%o2)                         done

(%i3) bit_onep(e,0);
(%o3)                         false

(%i4) bit_onep(o,0);
(%o4)                         true

Category: Number theory · Category: Binary operations · Category: Package bitwise

44 bode

44.1 Functions and Variables for bode

Function: bode_gain (H, range, ...plot_opts...)

Function to draw Bode gain plots.

Examples (1 through 7 from

http://www.swarthmore.edu/NatSci/echeeve1/Ref/Bode/BodeHow.html,

8 from Ron Crummett):

(%i1) load("bode")$

(%i2) H1 (s) := 100 * (1 + s) / ((s + 10) * (s + 100))$

(%i3) bode_gain (H1 (s), [w, 1/1000, 1000])$

(%i4) H2 (s) := 1 / (1 + s/omega0)$

(%i5) bode_gain (H2 (s), [w, 1/1000, 1000]), omega0 = 10$

(%i6) H3 (s) := 1 / (1 + s/omega0)^2$

(%i7) bode_gain (H3 (s), [w, 1/1000, 1000]), omega0 = 10$

(%i8) H4 (s) := 1 + s/omega0$

(%i9) bode_gain (H4 (s), [w, 1/1000, 1000]), omega0 = 10$

(%i10) H5 (s) := 1/s$

(%i11) bode_gain (H5 (s), [w, 1/1000, 1000])$

(%i12) H6 (s) := 1/((s/omega0)^2 + 2 * zeta * (s/omega0) + 1)$

(%i13) bode_gain (H6 (s), [w, 1/1000, 1000]), 
                  omega0 = 10, zeta = 1/10$

(%i14) H7 (s) := (s/omega0)^2 + 2 * zeta * (s/omega0) + 1$

(%i15) bode_gain (H7 (s), [w, 1/1000, 1000]),
                  omega0 = 10, zeta = 1/10$

(%i16) H8 (s) := 0.5 / (0.0001 * s^3 + 0.002 * s^2 + 0.01 * s)$

(%i17) bode_gain (H8 (s), [w, 1/1000, 1000])$

To use this function write first load("bode"). See also bode_phase.

Category: Plotting · Category: Package bode

Function: bode_phase (H, range, ...plot_opts...)

Function to draw Bode phase plots.

Examples (1 through 7 from

http://www.swarthmore.edu/NatSci/echeeve1/Ref/Bode/BodeHow.html,

8 from Ron Crummett):

(%i1) load("bode")$

(%i2) H1 (s) := 100 * (1 + s) / ((s + 10) * (s + 100))$

(%i3) bode_phase (H1 (s), [w, 1/1000, 1000])$

(%i4) H2 (s) := 1 / (1 + s/omega0)$

(%i5) bode_phase (H2 (s), [w, 1/1000, 1000]), omega0 = 10$

(%i6) H3 (s) := 1 / (1 + s/omega0)^2$

(%i7) bode_phase (H3 (s), [w, 1/1000, 1000]), omega0 = 10$

(%i8) H4 (s) := 1 + s/omega0$

(%i9) bode_phase (H4 (s), [w, 1/1000, 1000]), omega0 = 10$

(%i10) H5 (s) := 1/s$

(%i11) bode_phase (H5 (s), [w, 1/1000, 1000])$

(%i12) H6 (s) := 1/((s/omega0)^2 + 2 * zeta * (s/omega0) + 1)$

(%i13) bode_phase (H6 (s), [w, 1/1000, 1000]), 
                   omega0 = 10, zeta = 1/10$

(%i14) H7 (s) := (s/omega0)^2 + 2 * zeta * (s/omega0) + 1$

(%i15) bode_phase (H7 (s), [w, 1/1000, 1000]), 
                   omega0 = 10, zeta = 1/10$

(%i16) H8 (s) := 0.5 / (0.0001 * s^3 + 0.002 * s^2 + 0.01 * s)$

(%i17) bode_phase (H8 (s), [w, 1/1000, 1000])$

(%i18) block ([bode_phase_unwrap : false],
              bode_phase (H8 (s), [w, 1/1000, 1000]));

(%i19) block ([bode_phase_unwrap : true], 
              bode_phase (H8 (s), [w, 1/1000, 1000]));

To use this function write first load("bode"). See also bode_gain.

Category: Plotting · Category: Package bode

45 celine

45.1 Introduction to celine

Maxima implementation of Sister Celine’s method. Barton Willis wrote this code. It is released under the Creative Commons CC0 license.

Celine’s method is described in Sections 4.1–4.4 of the book "A=B", by Marko Petkovsek, Herbert S. Wilf, and Doron Zeilberger. This book is available at http://www.math.rutgers.edu/~zeilberg/AeqB.pdf

Let f = F(n,k). The function celine returns a set of recursion relations for F of the form

p_0(n) * fff(n,k) + p_1(n) * fff(n+1,k) + ... + p_p(n) * fff(n+p,k+q),

where p_0 through p_p are polynomials. If Maxima is unable to determine that sum(sum(a(i,j) * F(n+i,k+j),i,0,p),j,0,q) / F(n,k) is a rational function of n and k, celine returns the empty set. When f involves parameters (variables other than n or k), celine might make assumptions about these parameters. Using ’put’ with a key of ’proviso,’ Maxima saves these assumptions on the input label.

To use this function, first load the package integer_sequence, opsubst, and to_poly_solve.

Examples:

(%i1) load("integer_sequence")$
(%i2) load("opsubst")$
(%i3) load("to_poly_solve")$
(%i4) load("celine")$

(%i5) celine(n!,n,k,1,0);
(%o5)       {fff(n + 1, k) - n fff(n, k) - fff(n, k)}

Verification that this result is correct:

(%i1) load("integer_sequence")$
(%i2) load("opsubst")$
(%i3) load("to_poly_solve")$
(%i4) load("celine")$

(%i5) g1:{fff(n+1,k)-n*fff(n,k)-fff(n,k)};
(%o5)       {fff(n + 1, k) - n fff(n, k) - fff(n, k)}

(%i6) ratsimp(minfactorial(first(g1))),fff(n,k) := n!;
(%o6)                           0

An example with parameters including the test that the result of the example is correct:

(%i1) load("integer_sequence")$
(%i2) load("opsubst")$
(%i3) load("to_poly_solve")$
(%i4) load("celine")$

(%i5) e : pochhammer(a,k) * pochhammer(-k,n) / (pochhammer(b,k));
                           (a)  (- k)
                              k      n
(%o5)                      -----------
                              (b)
                                 k

(%i6) recur : celine(e,n,k,2,1);
(%o6) {fff(n + 2, k + 1) - fff(n + 2, k) - b fff(n + 1, k + 1)
 + n ((- fff(n + 1, k + 1)) + 2 fff(n + 1, k) - a fff(n, k)
 - fff(n, k)) + a (fff(n + 1, k) - fff(n, k)) + 2 fff(n + 1, k)
    2
 - n  fff(n, k)}

(%i7) /* Test this result for correctness */
(%i8) first(%), fff(n,k) := ''(e)$

(%i9) makefact(makegamma(%))$
(%o9)                           0

(%i10) minfactorial(factor(minfactorial(factor(%))));

The proviso data suggests that setting a = b may result in a lower order recursion which is shown by the following example:

(%i1) load("integer_sequence")$
(%i2) load("opsubst")$
(%i3) load("to_poly_solve")$
(%i4) load("celine")$

(%i5) e : pochhammer(a,k) * pochhammer(-k,n) / (pochhammer(b,k));
                           (a)  (- k)
                              k      n
(%o5)                      -----------
                              (b)
                                 k

(%i6) recur : celine(e,n,k,2,1);
(%o6) {fff(n + 2, k + 1) - fff(n + 2, k) - b fff(n + 1, k + 1)
 + n ((- fff(n + 1, k + 1)) + 2 fff(n + 1, k) - a fff(n, k)
 - fff(n, k)) + a (fff(n + 1, k) - fff(n, k)) + 2 fff(n + 1, k)
    2
 - n  fff(n, k)}

(%i7) get('%,'proviso);
(%o7)                         false

(%i8) celine(subst(b=a,e),n,k,1,1);
(%o8) {fff(n + 1, k + 1) - fff(n + 1, k) + n fff(n, k)
                                                     + fff(n, k)}

46 clebsch_gordan

46.1 Functions and Variables for clebsch_gordan

Function: clebsch_gordan (j1, j2, m1, m2, j, m)

Compute the Clebsch-Gordan coefficient <j1, j2, m1, m2 | j, m>.

Function: racah_v (a, b, c, a1, b1, c1)

Compute Racah’s V coefficient (computed in terms of a related Clebsch-Gordan coefficient).

Function: racah_w (j1, j2, j5, j4, j3, j6)

Compute Racah’s W coefficient (computed in terms of a Wigner 6j symbol)

Function: wigner_3j (j1, j2, j3, m1, m2, m3)

Compute Wigner’s 3j symbol (computed in terms of a related Clebsch-Gordan coefficient).

Function: wigner_6j (j1, j2, j3, j4, j5, j6)

Compute Wigner’s 6j symbol.

Function: wigner_9j (a, b, c, d, e, f, g, h, i, j,)

Compute Wigner’s 9j symbol.

Category: Share packages · Category: Package combinatorics

47 cobyla

47.1 Introduction to cobyla

fmin_cobyla is a Common Lisp translation (via f2cl) of the Fortran constrained optimization routine COBYLA by Powell[1][2][3].

COBYLA minimizes an objective function F(X) subject to M inequality constraints of the form g(X) >= 0 on X, where X is a vector of variables that has N components.

Equality constraints g(X)=0 can often be implemented by a pair of inequality constraints g(X)>=0 and -g(X)>= 0. Maxima’s interface to COBYLA allows equality constraints and internally converts the equality constraints to a pair of inequality constraints.

The algorithm employs linear approximations to the objective and constraint functions, the approximations being formed by linear interpolation at N+1 points in the space of the variables. The interpolation points are regarded as vertices of a simplex. The parameter RHO controls the size of the simplex and it is reduced automatically from RHOBEG to RHOEND. For each RHO the subroutine tries to achieve a good vector of variables for the current size, and then RHO is reduced until the value RHOEND is reached. Therefore RHOBEG and RHOEND should be set to reasonable initial changes to and the required accuracy in the variables respectively, but this accuracy should be viewed as a subject for experimentation because it is not guaranteed. The routine treats each constraint individually when calculating a change to the variables, rather than lumping the constraints together into a single penalty function. The name of the subroutine is derived from the phrase Constrained Optimization BY Linear Approximations.

References:

[1] Fortran Code is from http://plato.asu.edu/sub/nlores.html#general

[2] M. J. D. Powell, "A direct search optimization method that models the objective and constraint functions by linear interpolation," in Advances in Optimization and Numerical Analysis, eds. S. Gomez and J.-P. Hennart (Kluwer Academic: Dordrecht, 1994), p. 51-67.

[3] M. J. D. Powell, "Direct search algorithms for optimization calculations," Acta Numerica 7, 287-336 (1998). Also available as University of Cambridge, Department of Applied Mathematics and Theoretical Physics, Numerical Analysis Group, Report NA1998/04 from http://www.damtp.cam.ac.uk/user/na/reports.html

Category: Numerical methods · Category: Optimization · Category: Share packages · Category: Package cobyla

47.2 Functions and Variables for cobyla

Function: fmin_cobyla
fmin_cobyla (F, X, Y)
fmin_cobyla (F, X, Y, optional_args)

Returns an approximate minimum of the expression F with respect to the variables X, subject to an optional set of constraints. Y is a list of initial guesses for X.

F must be an ordinary expressions, not names of functions or lambda expressions.

optional_args represents additional arguments, specified as symbol = value. The optional arguments recognized are:

constraints

List of inequality and equality constraints that must be satisfied by X. The inequality constraints must be actual inequalities of the form g(X) >= h(X) or g(X) <= h(X). The equality constraints must be of the form g(X) = h(X).

rhobeg

Initial value of the internal RHO variable which controls the size of simplex. (Defaults to 1.0)

rhoend

The desired final value rho parameter. It is approximately the accuracy in the variables. (Defaults to 1d-6.)

iprint

Verbose output level. (Defaults to 0)

0 - No output
1 - Summary at the end of the calculation
2 - Each new value of RHO and SIGMA is printed, including the vector of variables, some function information when RHO is reduced.
3 - Like 2, but information is printed when F(X) is computed.

maxfun

The maximum number of function evaluations. (Defaults to 1000).

On return, a vector is given:

The value of the variables giving the minimum. This is a list of elements of the form var = value for each of the variables listed in X.
The minimized function value
The number of function evaluations.
Return code with the following meanings
1. 0 - No errors.
2. 1 - Limit on maximum number of function evaluations reached.
3. 2 - Rounding errors inhibiting progress.

load("fmin_cobyla") loads this function.

Function: bf_fmin_cobyla
bf_fmin_cobyla (F, X, Y)
bf_fmin_cobyla (F, X, Y, optional_args)

This function is identical to fmin_cobyla, except that bigfloat operations are used, and the default value for rhoend is 10^(fpprec/2).

See fmin_cobyla for more information.

load("bf_fmin_cobyla") loads this function.

47.3 Examples for cobyla

Minimize x1*x2 with 1-x1^2-x2^2 >= 0. The theoretical solution is x1 = 1/sqrt(2), x2 = -1/sqrt(2).

(%i1) load("fmin_cobyla")$

(%i2) fmin_cobyla(x1*x2, [x1, x2], [1,1], 
                  constraints = [x1^2+x2^2<=1], iprint=1);

   Normal return from subroutine COBYLA

   NFVALS =   66   F =-5.000000E-01    MAXCV = 1.999845E-12
   X = 7.071058E-01  -7.071077E-01
(%o2) [[x1 = 0.70710584934848, x2 = - 0.7071077130248], 
       - 0.49999999999926, [[-1.999955756559757e-12],[]], 66]

There are additional examples in the share/cobyla/ex directory.

48 combinatorics

48.1 Package combinatorics

The combinatorics package provides several functions to work with permutations and to permute elements of a list. The permutations of degree n are all the n! possible orderings of the first n positive integers, 1, 2, …, n. The functions in this packages expect a permutation to be represented by a list of those integers.

Cycles are represented as a list of two or more integers i_1, i_2, …, i_m, all different. Such a list represents a permutation where the integer i_2 appears in the i_1th position, the integer i_3 appears in the i_2th position and so on, until the integer i_1, which appears in the i_mth position.

For instance, [4, 2, 1, 3] is one of the 24 permutations of degree four, which can also be represented by the cycle [1, 4, 3]. The functions where cycles are used to represent permutations also require the order of the permutation to avoid ambiguity. For instance, the same cycle [1, 4, 3] could refer to the permutation of order 6: [4, 2, 1, 3, 5, 6]. A product of cycles must be represented by a list of cycles; the cycles at the end of the list are applied first. For example, [[2, 4], [1, 3, 6, 5]] is equivalent to the permutation [3, 4, 6, 2, 1, 5].

A cycle can be written in several ways. for instance, [1, 3, 6, 5], [3, 6, 5, 1] and [6, 5, 1, 3] are all equivalent. The canonical form used in the package is the one that places the lowest index in the first place. A cycle with only two indices is also called a transposition and if the two indices are consecutive, it is called an adjacent transposition.

To run an interactive tutorial, use the command demo (combinatorics). Since this is an additional package, it must be loaded with the command load("combinatorics").

48.2 Functions and Variables for Combinatorics

Function: apply_cycles (cl,l)

Permutes the list or set l applying to it the list of cycles cl. The cycles at the end of the list are applied first and the first cycle in the list cl is the last one to be applied.

See also perm_decomp.

Example:

(%i1) load("combinatorics")$

(%i2) perm_cycles ([4, 6, 3, 1, 7, 5, 2, 8]);
(%o2)                 [[1, 4], [2, 6, 5, 7]]

Function: perm_decomp (p)

Returns the minimum set of adjacent transpositions whose product equals the given permutation p.

See also perm_decomp.

Example:

(%i1) load("combinatorics")$

(%i2) perm_length ([4, 6, 3, 1, 7, 5, 2, 8]);
(%o2)                           12

Function: perm_lex_next (p)

Returns the permutation that comes after the given permutation p, in the sequence of permutations in lexicographic order.

Example:

(%i1) load("combinatorics")$

(%i2) perm_lex_next ([4, 6, 3, 1, 7, 5, 2, 8]);
(%o2)                [4, 6, 3, 1, 7, 5, 8, 2]

Function: perm_lex_rank (p)

Finds the position of permutation p, an integer from 1 to the degree n of the permutation, in the sequence of permutations in lexicographic order.

See also perm_lex_unrank and perms_lex.

Example:

(%i1) load("combinatorics")$

(%i2) perm_lex_rank ([4, 6, 3, 1, 7, 5, 2, 8]);
(%o2)                          18255

Function: perm_lex_unrank (n, i)

Returns the n-degree permutation at position i (from 1 to n!) in the lexicographic ordering of permutations.

See also perm_lex_rank and perms_lex.

Example:

(%i1) load("combinatorics")$

(%i2) perm_lex_unrank (8, 18255);
(%o2)                [4, 6, 3, 1, 7, 5, 2, 8]

Function: perm_next (p)

Returns the permutation that comes after the given permutation p, in the sequence of permutations in Trotter-Johnson order.

See also perm_decomp.

Example:

(%i1) load("combinatorics")$

(%i2) perm_parity ([4, 6, 3, 1, 7, 5, 2, 8]);
(%o2)                            0

Function: perm_rank (p)

Finds the position of permutation p, an integer from 1 to the degree n of the permutation, in the sequence of permutations in Trotter-Johnson order.

See also perm_decomp.

Example:

(%i1) load("combinatorics")$

(%i2) perm_undecomp ([[1,6],[2,6,5,7]], 8);
(%o2)                [5, 6, 3, 4, 7, 1, 2, 8]

Category: Differential equations · Category: Share packages · Category: Package contrib_ode

Function: perm_unrank (n, i)

Returns the n-degree permutation at position i (from 1 to n!) in the Trotter-Johnson ordering of permutations.

49 contrib_ode

49.1 Introduction to contrib_ode

Maxima’s ordinary differential equation (ODE) solver ode2 solves elementary linear ODEs of first and second order. The function contrib_ode extends ode2 with additional methods for linear and non-linear first order ODEs and linear homogeneous second order ODEs. The code is still under development and the calling sequence may change in future releases. Once the code has stabilized it may be moved from the contrib directory and integrated into Maxima.

This package must be loaded with the command load('contrib_ode) before use.

The calling convention for contrib_ode is identical to ode2. It takes three arguments: an ODE (only the left hand side need be given if the right hand side is 0), the dependent variable, and the independent variable. When successful, it returns a list of solutions.

The form of the solution differs from ode2. As non-linear equations can have multiple solutions, contrib_ode returns a list of solutions. Each solution can have a number of forms:

an explicit solution for the dependent variable,
an implicit solution for the dependent variable,
a parametric solution in terms of variable %t, or
a tranformation into another ODE in variable %u.

%c is used to represent the constant of integration for first order equations. %k1 and %k2 are the constants for second order equations. If contrib_ode cannot obtain a solution for whatever reason, it returns false, after perhaps printing out an error message.

It is necessary to return a list of solutions, as even first order non-linear ODEs can have multiple solutions. For example:

(%i1) load('contrib_ode)$

(%i2) eqn:x*'diff(y,x)^2-(1+x*y)*'diff(y,x)+y=0;
                    dy 2             dy
(%o2)            x (--)  - (1 + x y) -- + y = 0
                    dx               dx

(%i3) contrib_ode(eqn,y,x);
                    dy 2             dy
(%t3)            x (--)  - (1 + x y) -- + y = 0
                    dx               dx

              first order equation not linear in y'

                                             x
(%o3)             [y = log(x) + %c, y = %c %e ]

(%i4) method;
(%o4)                        factor

Nonlinear ODEs can have singular solutions without constants of integration, as in the second solution of the following example:

(%i1) load('contrib_ode)$

(%i2) eqn:'diff(y,x)^2+x*'diff(y,x)-y=0;
                       dy 2     dy
(%o2)                 (--)  + x -- - y = 0
                       dx       dx

(%i3) contrib_ode(eqn,y,x);
                       dy 2     dy
(%t3)                 (--)  + x -- - y = 0
                       dx       dx

              first order equation not linear in y'

                                           2
                                 2        x
(%o3)              [y = %c x + %c , y = - --]
                                          4

(%i4) method;
(%o4)                       clairault

The following ODE has two parametric solutions in terms of the dummy variable %t. In this case the parametric solutions can be manipulated to give explicit solutions.

(%i1) load('contrib_ode)$

(%i2) eqn:'diff(y,x)=(x+y)^2;
                          dy          2
(%o2)                     -- = (x + y)
                          dx

(%i3) contrib_ode(eqn,y,x);
(%o3) [[x = %c - atan(sqrt(%t)), y = (- x) - sqrt(%t)], 
                     [x = atan(sqrt(%t)) + %c, y = sqrt(%t) - x]]

(%i4) method;
(%o4)                       lagrange

The following example (Kamke 1.112) demonstrates an implicit solution.

(%i1) load('contrib_ode)$

(%i2) assume(x>0,y>0);
(%o2)                    [x > 0, y > 0]

(%i3) eqn:x*'diff(y,x)-x*sqrt(y^2+x^2)-y;
                     dy           2    2
(%o3)              x -- - x sqrt(y  + x ) - y
                     dx

(%i4) contrib_ode(eqn,y,x);
                                  y
(%o4)                  [x - asinh(-) = %c]
                                  x

(%i5) method;
(%o5)                          lie

The following Riccati equation is transformed into a linear second order ODE in the variable %u. Maxima is unable to solve the new ODE, so it is returned unevaluated.

(%i1) load('contrib_ode)$

(%i2) eqn:x^2*'diff(y,x)=a+b*x^n+c*x^2*y^2;
                    2 dy      2  2      n
(%o2)              x  -- = c x  y  + b x  + a
                      dx

(%i3) contrib_ode(eqn,y,x);
               d%u
               ---                            2
               dx        2  a       n - 2    d %u
(%o3)  [[y = - ----, %u c  (-- + b x     ) + ---- c = 0]]
               %u c          2                 2
                            x                dx

(%i4) method;
(%o4)                        riccati

For first order ODEs contrib_ode calls ode2. It then tries the following methods: factorization, Clairault, Lagrange, Riccati, Abel and Lie symmetry methods. The Lie method is not attempted on Abel equations if the Abel method fails, but it is tried if the Riccati method returns an unsolved second order ODE.

For second order ODEs contrib_ode calls ode2 then odelin.

Extensive debugging traces and messages are displayed if the command put('contrib_ode,true,'verbose) is executed.

49.2 Functions and Variables for contrib_ode

Function: contrib_ode (eqn, y, x)

Returns a list of solutions of the ODE eqn with independent variable x and dependent variable y.

Function: odelin (eqn, y, x)

odelin solves linear homogeneous ODEs of first and second order with independent variable x and dependent variable y. It returns a fundamental solution set of the ODE.

For second order ODEs, odelin uses a method, due to Bronstein and Lafaille, that searches for solutions in terms of given special functions.

(%i1) load('contrib_ode)$

(%i2) odelin(x*(x+1)*'diff(y,x,2)+(x+5)*'diff(y,x,1)+(-4)*y,y,x);
       gauss_a(- 6, - 2, - 3, - x)  gauss_b(- 6, - 2, - 3, - x)
(%o2) {---------------------------, ---------------------------}
                    4                            4
                   x                            x

Function: ode_check (eqn, soln)

Returns the value of ODE eqn after substituting a possible solution soln. The value is equivalent to zero if soln is a solution of eqn.

(%i1) load('contrib_ode)$

(%i2) eqn:'diff(y,x,2)+(a*x+b)*y;
                         2
                        d y
(%o2)                   --- + (b + a x) y
                          2
                        dx

(%i3) ans:[y = bessel_y(1/3,2*(a*x+b)^(3/2)/(3*a))*%k2*sqrt(a*x+b)
         +bessel_j(1/3,2*(a*x+b)^(3/2)/(3*a))*%k1*sqrt(a*x+b)];
                                  3/2
                    1  2 (b + a x)
(%o3) [y = bessel_y(-, --------------) %k2 sqrt(a x + b)
                    3       3 a
                                          3/2
                            1  2 (b + a x)
                 + bessel_j(-, --------------) %k1 sqrt(a x + b)]
                            3       3 a

(%i4) ode_check(eqn,ans[1]);
(%o4)                           0

System variable: method

The variable method is set to the successful solution method.

Variable: %c

%c is the integration constant for first order ODEs.

Variable: %k1

%k1 is the first integration constant for second order ODEs.

Variable: %k2

%k2 is the second integration constant for second order ODEs.

Function: gauss_a (a, b, c, x)

gauss_a(a,b,c,x) and gauss_b(a,b,c,x) are 2F1 geometric functions. They represent any two independent solutions of the hypergeometric differential equation x(1-x) diff(y,x,2) + [c-(a+b+1)x] diff(y,x) - aby = 0 (A&S 15.5.1).

The only use of these functions is in solutions of ODEs returned by odelin and contrib_ode. The definition and use of these functions may change in future releases of Maxima.

See also gauss_b, dgauss_a and gauss_b.

Function: gauss_b (a, b, c, x)

See gauss_a.

Function: dgauss_a (a, b, c, x)

The derivative with respect to x of gauss_a(a, b, c, x).

Function: dgauss_b (a, b, c, x)

The derivative with respect to x of gauss_b(a, b, c, x).

Function: kummer_m (a, b, x)

Kummer’s M function, as defined in Abramowitz and Stegun, Handbook of Mathematical Functions, Section 13.1.2.

The only use of this function is in solutions of ODEs returned by odelin and contrib_ode. The definition and use of this function may change in future releases of Maxima.

See also kummer_u, dkummer_m, and dkummer_u.

Function: kummer_u (a, b, x)

Kummer’s U function, as defined in Abramowitz and Stegun, Handbook of Mathematical Functions, Section 13.1.3.

See kummer_m.

Function: dkummer_m (a, b, x)

The derivative with respect to x of kummer_m(a, b, x).

Function: dkummer_u (a, b, x)

The derivative with respect to x of kummer_u(a, b, x).

Category: Package contrib_ode · Category: Bessel functions · Category: Special functions

Function: bessel_simplify (expr)

Simplifies expressions containing Bessel functions bessel_j, bessel_y, bessel_i, bessel_k, hankel_1, hankel_2, strauve_h and strauve_l. Recurrence relations (given in Abramowitz and Stegun, Handbook of Mathematical Functions, Section 9.1.27) are used to replace functions of highest order n by functions of order n-1 and n-2.

This process repeated until all the orders differ by less than 2.

(%i1) load('contrib_ode)$

(%i2) bessel_simplify(4*bessel_j(n,x^2)*(x^2-n^2/x^2)
  +x*((bessel_j(n-2,x^2)-bessel_j(n,x^2))*x
  -(bessel_j(n,x^2)-bessel_j(n+2,x^2))*x)
  -2*bessel_j(n+1,x^2)+2*bessel_j(n-1,x^2));
(%o2)                           0

(%i3) bessel_simplify(-2*bessel_j(1,z)*z^3-10*bessel_j(2,z)*z^2
 +15*%pi*bessel_j(1,z)*struve_h(3,z)*z-15*%pi*struve_h(1,z)*bessel_j(3,z)*z
 -15*%pi*bessel_j(0,z)*struve_h(2,z)*z+15*%pi*struve_h(0,z)*bessel_j(2,z)*z
 -30*%pi*bessel_j(1,z)*struve_h(2,z)+30*%pi*struve_h(1,z)*bessel_j(2,z));
(%o3)                           0

Function: expintegral_e_simplify (expr)

Simplify expressions containing exponential integral expintegral_e using the recurrence (A&S 5.1.14).

expintegral_e(n+1,z) = (1/n) * (exp(-z)-z*expintegral_e(n,z)) n = 1,2,3 ....

Category: Package contrib_ode · Category: Exponential Integrals · Category: Special functions

49.3 Possible improvements to contrib_ode

These routines are work in progress. I still need to:

Extend the FACTOR method ode1_factor to work for multiple roots.
Extend the FACTOR method ode1_factor to attempt to solve higher order factors. At present it only attemps to solve linear factors.
Fix the LAGRANGE routine ode1_lagrange to prefer real roots over complex roots.
Add additional methods for Riccati equations.
Improve the detection of Abel equations of second kind. The exisiting pattern matching is weak.
Work on the Lie symmetry group routine ode1_lie. There are quite a few problems with it: some parts are unimplemented; some test cases seem to run forever; other test cases crash; yet others return very complex "solutions". I wonder if it really ready for release yet.
Add more test cases.

49.4 Test cases for contrib_ode

The routines have been tested on a approximately one thousand test cases from Murphy, Kamke, Zwillinger and elsewhere. These are included in the tests subdirectory.

The Clairault routine ode1_clairault finds all known solutions, including singular solutions, of the Clairault equations in Murphy and Kamke.
The other routines often return a single solution when multiple solutions exist.
Some of the "solutions" from ode1_lie are overly complex and impossible to check.
There are some crashes.

49.5 References for contrib_ode

E. Kamke, Differentialgleichungen Losungsmethoden und Losungen, Vol 1, Geest & Portig, Leipzig, 1961
G. M. Murphy, Ordinary Differential Equations and Their Solutions, Van Nostrand, New York, 1960
D. Zwillinger, Handbook of Differential Equations, 3rd edition, Academic Press, 1998
F. Schwarz, Symmetry Analysis of Abel’s Equation, Studies in Applied Mathematics, 100:269-294 (1998)
F. Schwarz, Algorithmic Solution of Abel’s Equation, Computing 61, 39-49 (1998)
E. S. Cheb-Terrab, A. D. Roche, Symmetries and First Order ODE Patterns, Computer Physics Communications 113 (1998), p 239. (http://lie.uwaterloo.ca/papers/ode_vii.pdf)
E. S. Cheb-Terrab, T. Kolokolnikov, First Order ODEs, Symmetries and Linear Transformations, European Journal of Applied Mathematics, Vol. 14, No. 2, pp. 231-246 (2003). (http://arxiv.org/abs/math-ph/0007023,
http://lie.uwaterloo.ca/papers/ode_iv.pdf)
G. W. Bluman, S. C. Anco, Symmetry and Integration Methods for Differential Equations, Springer, (2002)
M. Bronstein, S. Lafaille, Solutions of linear ordinary differential equations in terms of special functions, Proceedings of ISSAC 2002, Lille, ACM Press, 23-28. (http://www-sop.inria.fr/cafe/Manuel.Bronstein/publications/issac2002.pdf)

50 descriptive

50.1 Introduction to descriptive

Package descriptive contains a set of functions for making descriptive statistical computations and graphing. Together with the source code there are three data sets in your Maxima tree: pidigits.data, wind.data and biomed.data.

Any statistics manual can be used as a reference to the functions in package descriptive.

For comments, bugs or suggestions, please contact me at ’riotorto AT yahoo DOT com’.

Here is a simple example on how the descriptive functions in descriptive do they work, depending on the nature of their arguments, lists or matrices,

(%i1) load ("descriptive")$

(%i2) /* univariate sample */   mean ([a, b, c]);
                            c + b + a
(%o2)                       ---------
                                3

(%i3) matrix ([a, b], [c, d], [e, f]);
                            [ a  b ]
                            [      ]
(%o3)                       [ c  d ]
                            [      ]
                            [ e  f ]

(%i4) /* multivariate sample */ mean (%);
                      e + c + a  f + d + b
(%o4)                [---------, ---------]
                          3          3

Note that in multivariate samples the mean is calculated for each column.

In case of several samples with possible different sizes, the Maxima function map can be used to get the desired results for each sample,

(%i1) load ("descriptive")$

(%i2) map (mean, [[a, b, c], [d, e]]);
                        c + b + a  e + d
(%o2)                  [---------, -----]
                            3        2

In this case, two samples of sizes 3 and 2 were stored into a list.

Univariate samples must be stored in lists like

(%i1) s1 : [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5];
(%o1)           [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5]

and multivariate samples in matrices as in

(%i1) s2 : matrix ([13.17, 9.29], [14.71, 16.88], [18.50, 16.88],
             [10.58, 6.63], [13.33, 13.25], [13.21,  8.12]);
                        [ 13.17  9.29  ]
                        [              ]
                        [ 14.71  16.88 ]
                        [              ]
                        [ 18.5   16.88 ]
(%o1)                   [              ]
                        [ 10.58  6.63  ]
                        [              ]
                        [ 13.33  13.25 ]
                        [              ]
                        [ 13.21  8.12  ]

In this case, the number of columns equals the random variable dimension and the number of rows is the sample size.

Data can be introduced by hand, but big samples are usually stored in plain text files. For example, file pidigits.data contains the first 100 digits of number %pi:

In order to load these digits in Maxima,

(%i1) s1 : read_list (file_search ("pidigits.data"))$

(%i2) length (s1);
(%o2)                          100

On the other hand, file wind.data contains daily average wind speeds at 5 meteorological stations in the Republic of Ireland (This is part of a data set taken at 12 meteorological stations. The original file is freely downloadable from the StatLib Data Repository and its analysis is discused in Haslett, J., Raftery, A. E. (1989) Space-time Modelling with Long-memory Dependence: Assessing Ireland’s Wind Power Resource, with Discussion. Applied Statistics 38, 1-50). This loads the data:

(%i1) s2 : read_matrix (file_search ("wind.data"))$

(%i2) length (s2);
(%o2)                          100

(%i3) s2 [%]; /* last record */
(%o3)            [3.58, 6.0, 4.58, 7.62, 11.25]

Some samples contain non numeric data. As an example, file biomed.data (which is part of another bigger one downloaded from the StatLib Data Repository) contains four blood measures taken from two groups of patients, A and B, of different ages,

(%i1) s3 : read_matrix (file_search ("biomed.data"))$

(%i2) length (s3);
(%o2)                          100

(%i3) s3 [1]; /* first record */
(%o3)            [A, 30, 167.0, 89.0, 25.6, 364]

The first individual belongs to group A, is 30 years old and his/her blood measures were 167.0, 89.0, 25.6 and 364.

One must take care when working with categorical data. In the next example, symbol a is assigned a value in some previous moment and then a sample with categorical value a is taken,

(%i1) a : 1$

(%i2) matrix ([a, 3], [b, 5]);
                            [ 1  3 ]
(%o2)                       [      ]
                            [ b  5 ]

Category: Descriptive statistics · Category: Share packages · Category: Package descriptive

50.2 Functions and Variables for data manipulation

Function: build_sample
build_sample (list)
build_sample (matrix)

Builds a sample from a table of absolute frequencies. The input table can be a matrix or a list of lists, all of them of equal size. The number of columns or the length of the lists must be greater than 1. The last element of each row or list is interpreted as the absolute frequency. The output is always a sample in matrix form.

Examples:

Univariate frequency table.

(%i1) load ("descriptive")$
(%i2) sam1: build_sample([[6,1], [j,2], [2,1]]);
                       [ 6 ]
                       [   ]
                       [ j ]
(%o2)                  [   ]
                       [ j ]
                       [   ]
                       [ 2 ]
(%i3) mean(sam1);
                      2 j + 8
(%o3)                [-------]
                         4
(%i4) barsplot(sam1) $

Multivariate frequency table.

(%i1) load ("descriptive")$
(%i2) sam2: build_sample([[6,3,1], [5,6,2], [u,2,1],[6,8,2]]) ;
                           [ 6  3 ]
                           [      ]
                           [ 5  6 ]
                           [      ]
                           [ 5  6 ]
(%o2)                      [      ]
                           [ u  2 ]
                           [      ]
                           [ 6  8 ]
                           [      ]
                           [ 6  8 ]
(%i3) cov(sam2);
       [   2                 2                            ]
       [  u  + 158   (u + 28)     2 u + 174   11 (u + 28) ]
       [  -------- - ---------    --------- - ----------- ]
(%o3)  [     6          36            6           12      ]
       [                                                  ]
       [ 2 u + 174   11 (u + 28)            21            ]
       [ --------- - -----------            --            ]
       [     6           12                 4             ]
(%i4) barsplot(sam2, grouping=stacked) $

Function: continuous_freq
continuous_freq (data)
continuous_freq (data, m)

The first argument of continuous_freq must be a list or 1-dimensional array (as created by make_array) of numbers. Divides the range in intervals and counts how many values are inside them. The second argument is optional and either equals the number of classes we want, 10 by default, or equals a list containing the class limits and the number of classes we want, or a list containing only the limits.

If sample values are all equal, this function returns only one class of amplitude 2.

Examples:

Optional argument indicates the number of classes we want. The first list in the output contains the interval limits, and the second the corresponding counts: there are 16 digits inside the interval [0, 1.8], 24 digits in (1.8, 3.6], and so on.

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$
(%i3) continuous_freq (s1, 5);
(%o3) [[0, 1.8, 3.6, 5.4, 7.2, 9.0], [16, 24, 18, 17, 25]]

Optional argument indicates we want 7 classes with limits -2 and 12:

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$
(%i3) continuous_freq (s1, [-2,12,7]);
(%o3) [[- 2, 0, 2, 4, 6, 8, 10, 12], [8, 20, 22, 17, 20, 13, 0]]

Optional argument indicates we want the default number of classes with limits -2 and 12:

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$
(%i3) continuous_freq (s1, [-2,12]);
                3  4  11  18     32  39  46  53
(%o3)  [[- 2, - -, -, --, --, 5, --, --, --, --, 12], 
                5  5  5   5      5   5   5   5
               [0, 8, 20, 12, 18, 9, 8, 25, 0, 0]]

The first argument may be an array.

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$
(%i3) a1 : make_array (fixnum, length (s1)) $
(%i4) fillarray (a1, s1);
(%o4) {Lisp Array: 
#(3 1 4 1 5 9 2 6 5 3 5 8 9 7 9 3 2 3 8 4 6 2 6 4 3 3 8 3 2 7 9 \
5 0 2 8 8 4 1 9 7 1 6 9 3 9 9 3 7 5 1 0 5 8 2 0 9 7 4 9 4 4 5 9
  2 3 0 7 8 1 6 4 0 6 2 8 6 2 0 8 9 9 8 6 2 8 0 3 4 8 2 5 3 4 2 \
1 1 7 0 6 7)}
(%i5) continuous_freq (a1);
           9   9  27  18  9  27  63  36  81
(%o5) [[0, --, -, --, --, -, --, --, --, --, 9], 
           10  5  10  5   2  5   10  5   10
                             [8, 8, 12, 12, 10, 8, 9, 8, 12, 13]]

Function: discrete_freq (data)

Counts absolute frequencies in discrete samples, both numeric and categorical. Its unique argument is a list, or 1-dimensional array (as created by make_array).

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$

(%i3) discrete_freq (s1);
(%o3) [[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], 
                             [8, 8, 12, 12, 10, 8, 9, 8, 12, 13]]

The first list gives the sample values and the second their absolute frequencies. Commands ? col and ? transpose should help you to understand the last input.

The argument may be an array.

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$
(%i3) a1 : make_array (fixnum, length (s1)) $
(%i4) fillarray (a1, s1);
(%o4) {Lisp Array: 
#(3 1 4 1 5 9 2 6 5 3 5 8 9 7 9 3 2 3 8 4 6 2 6 4 3 3 8 3 2 7 9 \
5 0 2 8 8 4 1 9 7 1 6 9 3 9 9 3 7 5 1 0 5 8 2 0 9 7 4 9 4 4 5 9
  2 3 0 7 8 1 6 4 0 6 2 8 6 2 0 8 9 9 8 6 2 8 0 3 4 8 2 5 3 4 2 \
1 1 7 0 6 7)}
(%i5) discrete_freq (a1);
(%o5) [[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], 
                             [8, 8, 12, 12, 10, 8, 9, 8, 12, 13]]

Function: standardize
standardize (list)
standardize (matrix)

Subtracts to each element of the list the sample mean and divides the result by the standard deviation. When the input is a matrix, standardize subtracts to each row the multivariate mean, and then divides each component by the corresponding standard deviation.

Function: subsample
subsample (data_matrix, predicate_function)
subsample (data_matrix, predicate_function, col_num1, col_num2, ...)

This is a sort of variant of the Maxima submatrix function. The first argument is the data matrix, the second is a predicate function and optional additional arguments are the numbers of the columns to be taken. Its behaviour is better understood with examples.

These are multivariate records in which the wind speed in the first meteorological station were greater than 18. See that in the lambda expression the i-th component is referred to as v[i].

(%i1) load ("descriptive")$
(%i2) s2 : read_matrix (file_search ("wind.data"))$

(%i3) subsample (s2, lambda([v], v[1] > 18));
              [ 19.38  15.37  15.12  23.09  25.25 ]
              [                                   ]
              [ 18.29  18.66  19.08  26.08  27.63 ]
(%o3)         [                                   ]
              [ 20.25  21.46  19.95  27.71  23.38 ]
              [                                   ]
              [ 18.79  18.96  14.46  26.38  21.84 ]

In the following example, we request only the first, second and fifth components of those records with wind speeds greater or equal than 16 in station number 1 and less than 25 knots in station number 4. The sample contains only data from stations 1, 2 and 5. In this case, the predicate function is defined as an ordinary Maxima function.

(%i1) load ("descriptive")$
(%i2) s2 : read_matrix (file_search ("wind.data"))$
(%i3) g(x):= x[1] >= 16 and x[4] < 25$

(%i4) subsample (s2, g, 1, 2, 5);
                     [ 19.38  15.37  25.25 ]
                     [                     ]
                     [ 17.33  14.67  19.58 ]
(%o4)                [                     ]
                     [ 16.92  13.21  21.21 ]
                     [                     ]
                     [ 17.25  18.46  23.87 ]

Here is an example with the categorical variables of biomed.data. We want the records corresponding to those patients in group B who are older than 38 years.

(%i1) load ("descriptive")$
(%i2) s3 : read_matrix (file_search ("biomed.data"))$
(%i3) h(u):= u[1] = B and u[2] > 38 $

(%i4) subsample (s3, h);
                [ B  39  28.0  102.3  17.1  146 ]
                [                               ]
                [ B  39  21.0  92.4   10.3  197 ]
                [                               ]
                [ B  39  23.0  111.5  10.0  133 ]
                [                               ]
                [ B  39  26.0  92.6   12.3  196 ]
(%o4)           [                               ]
                [ B  39  25.0  98.7   10.0  174 ]
                [                               ]
                [ B  39  21.0  93.2   5.9   181 ]
                [                               ]
                [ B  39  18.0  95.0   11.3  66  ]
                [                               ]
                [ B  39  39.0  88.5   7.6   168 ]

Probably, the statistical analysis will involve only the blood measures,

(%i1) load ("descriptive")$
(%i2) s3 : read_matrix (file_search ("biomed.data"))$

(%i3) subsample (s3, lambda([v], v[1] = B and v[2] > 38),
                 3, 4, 5, 6);
                   [ 28.0  102.3  17.1  146 ]
                   [                        ]
                   [ 21.0  92.4   10.3  197 ]
                   [                        ]
                   [ 23.0  111.5  10.0  133 ]
                   [                        ]
                   [ 26.0  92.6   12.3  196 ]
(%o3)              [                        ]
                   [ 25.0  98.7   10.0  174 ]
                   [                        ]
                   [ 21.0  93.2   5.9   181 ]
                   [                        ]
                   [ 18.0  95.0   11.3  66  ]
                   [                        ]
                   [ 39.0  88.5   7.6   168 ]

This is the multivariate mean of s3,

(%i1) load ("descriptive")$
(%i2) s3 : read_matrix (file_search ("biomed.data"))$

(%i3) mean (s3);
       65 B + 35 A  317          6 NA + 8144.999999999999
(%o3) [-----------, ---, 87.178, ------------------------, 
           100      10                     100
                                                    3 NA + 19587
                                            18.123, ------------]
                                                        100

Here, the first component is meaningless, since A and B are categorical, the second component is the mean age of individuals in rational form, and the fourth and last values exhibit some strange behaviour. This is because symbol NA is used here to indicate non available data, and the two means are nonsense. A possible solution would be to take out from the matrix those rows with NA symbols, although this deserves some loss of information.

(%i1) load ("descriptive")$
(%i2) s3 : read_matrix (file_search ("biomed.data"))$
(%i3) g(v):= v[4] # NA and v[6] # NA $

(%i4) mean (subsample (s3, g, 3, 4, 5, 6));
(%o4) [79.4923076923077, 86.2032967032967, 16.93186813186813, 
                                                            2514
                                                            ----]
                                                             13

Function: transform_sample (matrix, varlist, exprlist)

Transforms the sample matrix, where each column is called according to varlist, following expressions in exprlist.

Examples:

The second argument assigns names to the three columns. With these names, a list of expressions define the transformation of the sample.

(%i1) load ("descriptive")$
(%i2) data: matrix([3,2,7],[3,7,2],[8,2,4],[5,2,4]) $

(%i3) transform_sample(data, [a,b,c], [c, a*b, log(a)]);
                               [ 7  6   log(3) ]
                               [               ]
                               [ 2  21  log(3) ]
(%o3)                          [               ]
                               [ 4  16  log(8) ]
                               [               ]
                               [ 4  10  log(5) ]

Add a constant column and remove the third variable.

(%i1) load ("descriptive")$
(%i2) data: matrix([3,2,7],[3,7,2],[8,2,4],[5,2,4]) $
(%i3) transform_sample(data, [a,b,c], [makelist(1,k,length(data)),a,b]);

                                  [ 1  3  2 ]
                                  [         ]
                                  [ 1  3  7 ]
(%o3)                             [         ]
                                  [ 1  8  2 ]
                                  [         ]
                                  [ 1  5  2 ]

50.3 Functions and Variables for descriptive statistics

Function: mean
mean (list)
mean (matrix)

This is the sample mean, defined as

                       n
                     ====
             _   1   \
             x = -    >    x
                 n   /      i
                     ====
                     i = 1

Example:

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$

(%i3) mean (s1);
                               471
(%o3)                          ---
                               100

(%i4) %, numer;
(%o4)                         4.71

(%i5) s2 : read_matrix (file_search ("wind.data"))$

(%i6) mean (s2);
(%o6)     [9.9485, 10.1607, 10.8685, 15.7166, 14.8441]

Function: var
var (list)
var (matrix)

This is the sample variance, defined as

                     n
                   ====
           2   1   \          _ 2
          s  = -    >    (x - x)
               n   /       i
                   ====
                   i = 1

Example:

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$

(%i3) var (s1), numer;
(%o3)                   8.425899999999999

50.4 Functions and Variables for statistical graphs

Function: barsplot (data1, data2, …, option_1, option_2, …)

Plots bars diagrams for discrete statistical variables, both for one or multiple samples.

data can be a list of outcomes representing one sample, or a matrix of m rows and n columns, representing n samples of size m each.

Available options are:

box_width (default, 3/4): relative width of rectangles. This value must be in the range [0,1].
grouping (default, clustered): indicates how multiple samples are shown. Valid values are: clustered and stacked.
groups_gap (default, 1): a positive integer number representing the gap between two consecutive groups of bars.
bars_colors (default, []): a list of colors for multiple samples. When there are more samples than specified colors, the extra necessary colors are chosen at random. See color to learn more about them.
frequency (default, absolute): indicates the scale of the ordinates. Possible values are: absolute, relative, and percent.
ordering (default, orderlessp): possible values are orderlessp or ordergreatp, indicating how statistical outcomes should be ordered on the x-axis.
sample_keys (default, []): a list with the strings to be used in the legend. When the list length is other than 0 or the number of samples, an error message is returned.
start_at (default, 0): indicates where the plot begins to be plotted on the x axis.
All global draw options, except xtics, which is internally assigned by barsplot. If you want to set your own values for this option or want to build complex scenes, make use of barsplot_description. See example below.
The following local draw-pkg options: key, color_draw, fill_color, fill_density and line_width. See also barsplot.

There is also a function wxbarsplot for creating embedded histograms in interfaces wxMaxima and iMaxima. barsplot in a multiplot context.

Examples:

Univariate sample in matrix form. Absolute frequencies.

(%i1) load ("descriptive")$
(%i2) m : read_matrix (file_search ("biomed.data"))$

(%i3) barsplot(
        col(m,2),
        title        = "Ages",
        xlabel       = "years",
        box_width    = 1/2,
        fill_density = 3/4)$

Two samples of different sizes, with relative frequencies and user declared colors.

(%i1) load ("descriptive")$
(%i2) l1:makelist(random(10),k,1,50)$
(%i3) l2:makelist(random(10),k,1,100)$

(%i4) barsplot(
        l1,l2,
        box_width    = 1,
        fill_density = 1,
        bars_colors  = [black, grey],
        frequency = relative,
        sample_keys = ["A", "B"])$

Four non numeric samples of equal size.

(%i1) load ("descriptive")$

(%i2) barsplot(
        makelist([Yes, No, Maybe][random(3)+1],k,1,50),
        makelist([Yes, No, Maybe][random(3)+1],k,1,50),
        makelist([Yes, No, Maybe][random(3)+1],k,1,50),
        makelist([Yes, No, Maybe][random(3)+1],k,1,50),
        title  = "Asking for something to four groups",
        ylabel = "# of individuals",
        groups_gap   = 3,
        fill_density = 0.5,
        ordering     = ordergreatp)$

Stacked bars.

(%i1) load ("descriptive")$

(%i2) barsplot(
        makelist([Yes, No, Maybe][random(3)+1],k,1,50),
        makelist([Yes, No, Maybe][random(3)+1],k,1,50),
        makelist([Yes, No, Maybe][random(3)+1],k,1,50),
        makelist([Yes, No, Maybe][random(3)+1],k,1,50),
        title  = "Asking for something to four groups",
        ylabel = "# of individuals",
        grouping     = stacked,
        fill_density = 0.5,
        ordering     = ordergreatp)$

For bars diagrams related options, see barsplot of package draw-pkg See also functions histogram and piechart.

Function: barsplot_description (…)

Function barsplot_description creates a graphic object suitable for creating complex scenes, together with other graphic objects.

Example: barsplot in a multiplot context.

(%i1) load ("descriptive")$
(%i2) l1:makelist(random(10),k,1,50)$
(%i3) l2:makelist(random(10),k,1,100)$
(%i4) bp1 : 
        barsplot_description(
         l1,
         box_width = 1,
         fill_density = 0.5,
         bars_colors = [blue],
         frequency = relative)$
(%i5) bp2 : 
        barsplot_description(
         l2,
         box_width = 1,
         fill_density = 0.5,
         bars_colors = [red],
         frequency = relative)$
(%i6) draw(gr2d(bp1), gr2d(bp2))$

Function: boxplot (data)
boxplot (data, option_1, option_2, …)

This function plots box-and-whisker diagrams. Argument data can be a list, which is not of great interest, since these diagrams are mainly used for comparing different samples, or a matrix, so it is possible to compare two or more components of a multivariate statistical variable. But it is also allowed data to be a list of samples with possible different sample sizes, in fact this is the only function in package descriptive that admits this type of data structure.

The box is plotted from the first quartile to the third, with an horizontal segment situated at the second quartile or median. By default, lower and upper whiskers are plotted at the minimum and maximum values, respectively. Option range can be used to indicate that values greater than quantile(x,3/4)+range*(quantile(x,3/4)-quantile(x,1/4)) or less than quantile(x,1/4)-range*(quantile(x,3/4)-quantile(x,1/4)) must be considered as outliers, in which case they are plotted as isolated points, and the whiskers are located at the extremes of the rest of the sample.

Available options are:

box_width (default, 3/4): relative width of boxes. This value must be in the range [0,1].
box_orientation (default, vertical): possible values: vertical and horizontal.
range (default, inf): positive coefficient of the interquartilic range to set outliers boundaries.
outliers_size (default, 1): circle size for isolated outliers.
All draw options, except points_joined, point_size, point_type, xtics, ytics, xrange, and yrange, which are internally assigned by boxplot. If you want to set your own values for this options or want to build complex scenes, make use of boxplot_description.
The following local draw options: key, color, and line_width.

There is also a function wxboxplot for creating embedded histograms in interfaces wxMaxima and iMaxima.

Examples:

Box-and-whisker diagram from a multivariate sample.

(%i1) load ("descriptive")$
(%i2) s2 : read_matrix(file_search("wind.data"))$

(%i3) boxplot(s2,
        box_width  = 0.2,
        title      = "Windspeed in knots",
        xlabel     = "Stations",
        color      = red,
        line_width = 2)$

Box-and-whisker diagram from three samples of different sizes.

(%i1) load ("descriptive")$

(%i2) A :
       [[6, 4, 6, 2, 4, 8, 6, 4, 6, 4, 3, 2],
        [8, 10, 7, 9, 12, 8, 10],
        [16, 13, 17, 12, 11, 18, 13, 18, 14, 12]]$

(%i3) boxplot (A, box_orientation = horizontal)$

Option range can be used to handle outliers.

(%i1) load ("descriptive")$
(%i2) B: [[7, 15, 5, 8, 6, 5, 7, 3, 1],
          [10, 8, 12, 8, 11, 9, 20],
          [23, 17, 19, 7, 22, 19]] $

(%i3) boxplot (B, range=1)$
(%i4) boxplot (B, range=1.5, box_orientation = horizontal)$

(%i5) draw2d(
        boxplot_description(
          B,
          range            = 1.5,
          line_width       = 3,
          outliers_size    = 2,
          color            = red,
          background_color = light_gray),
        xtics = {["Low",1],["Medium",2],["High",3]}) $

Function: boxplot_description (…)

Function boxplot_description creates a graphic object suitable for creating complex scenes, together with other graphic objects.

Function: histogram
    histogram (list)
    histogram (list, option_1, option_2, …)
    histogram (one_column_matrix)
    histogram (one_column_matrix, option_1, option_2, …)
    histogram (one_row_matrix)
    histogram (one_row_matrix, option_1, option_2, …)

This function plots an histogram from a continuous sample. Sample data must be stored in a list of numbers or a one dimensional matrix.

Available options are:

nclasses (default, 10): number of classes of the histogram, or a list indicating the limits of the classes and the number of them, or only the limits. This option also accepts bounds for varying bin widths, or a symbol with the name of one of the three optimal algorithms available for the number of classes: 'fd (Freedman, D. and Diaconis, P. (1981) On the histogram as a density estimator: L_2 theory. Zeitschrift fuer Wahrscheinlichkeitstheorie und verwandte Gebiete 57, 453-476.), 'scott (Scott, D. W. (1979) On optimal and data-based histograms. Biometrika 66, 605-610.), and 'sturges (Sturges, H. A. (1926) The choice of a class interval. Journal of the American Statistical Association 21, 65-66).
frequency (default, absolute): indicates the scale of the ordinates. Possible values are: absolute, relative, percent, and density. With density, the histogram area has a total area of one.
htics (default, auto): format of the histogram tics. Possible values are: auto, endpoints, intervals, or a list of labels.
All global draw options, except xrange, yrange, and xtics, which are internally assigned by histogram. If you want to set your own values for these options, make use of histogram_description. See examples bellow.
The following local draw-pkg options: key, color, fill_color, fill_density and line_width. See also barsplot.

There is also a function wxhistogram for creating embedded histograms in interfaces wxMaxima and iMaxima.

Examples:

A simple with eight classes:

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$
(%i3) histogram (
           s1,
           nclasses     = 8,
           title        = "pi digits",
           xlabel       = "digits",
           ylabel       = "Absolute frequency",
           fill_color   = grey,
           fill_density = 0.6)$

Setting the limits of the histogram to -2 and 12, with 3 classes. Also, we introduce predefined tics:

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$
(%i3) histogram (
           s1,
           nclasses     = [-2,12,3],
           htics        = ["A", "B", "C"],
           terminal     = png,
           fill_color   = "#23afa0",
           fill_density = 0.6)$

Bounds for varying bin widths.

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$
(%i3) histogram (s1, nclasses = {0,3,6,7,11})$

Freedmann - Diakonis robust method for optimal search of the number of classes.

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$
(%i3) histogram(s1, nclasses=fd) $

Function: histogram_description (…)

Function histogram_description creates a graphic object suitable for creating complex scenes, together with other graphic objects. We make use of histogram_description for setting the xrange and adding an explicit curve into the scene:

(%i1) load ("descriptive")$
(%i2) ( load("distrib"),
        m: 14, s: 2,
        s2: random_normal(m, s, 1000) ) $
(%i3) draw2d(
        grid   = true,
        xrange = [5, 25],
        histogram_description(
          s2,
          nclasses     = 9,
          frequency    = density,
          fill_density = 0.5),
        explicit(pdf_normal(x,m,s), x, m - 3*s, m + 3* s))$

Function: piechart
    piechart (list)
    piechart (list, option_1, option_2, …)
    piechart (one_column_matrix)
    piechart (one_column_matrix, option_1, option_2, …)
    piechart (one_row_matrix)
    piechart (one_row_matrix, option_1, option_2, …)

Similar to barsplot, but plots sectors instead of rectangles.

Available options are:

sector_colors (default, []): a list of colors for sectors. When there are more sectors than specified colors, the extra necessary colors are chosen at random. See color to learn more about them.
pie_center (default, [0,0]): diagram’s center.
pie_radius (default, 1): diagram’s radius.
All global draw options, except key, which is internally assigned by piechart. If you want to set your own values for this option or want to build complex scenes, make use of piechart_description.
The following local draw options: key, color, fill_density and line_width. See also ellipse

There is also a function wxpiechart for creating embedded histograms in interfaces wxMaxima and iMaxima.

Example:

(%i1) load ("descriptive")$
(%i2) s1 : read_list (file_search ("pidigits.data"))$
(%i3) piechart(
        s1,
        xrange  = [-1.1, 1.3],
        yrange  = [-1.1, 1.1],
        title   = "Digit frequencies in pi")$

51 diag

51.1 Functions and Variables for diag

Function: diag (lm)

Constructs a matrix that is the block sum of the elements of lm. The elements of lm are assumed to be matrices; if an element is scalar, it treated as a 1 by 1 matrix.

The resulting matrix will be square if each of the elements of lm is square.

Example:

(%i1) load("diag")$

(%i2) a1:matrix([1,2,3],[0,4,5],[0,0,6])$

(%i3) a2:matrix([1,1],[1,0])$

(%i4) diag([a1,x,a2]);
                   [ 1  2  3  0  0  0 ]
                   [                  ]
                   [ 0  4  5  0  0  0 ]
                   [                  ]
                   [ 0  0  6  0  0  0 ]
(%o4)              [                  ]
                   [ 0  0  0  x  0  0 ]
                   [                  ]
                   [ 0  0  0  0  1  1 ]
                   [                  ]
                   [ 0  0  0  0  1  0 ]
(%i5) diag ([matrix([1,2]), 3]);
                        [ 1  2  0 ]
(%o5)                   [         ]
                        [ 0  0  3 ]

To use this function write first load("diag").

Category: Matrices · Category: Share packages · Category: Package diag

Function: JF (lambda,n)

Returns the Jordan cell of order n with eigenvalue lambda.

Example:

(%i1) load("diag")$

(%i2) JF(2,5);
                    [ 2  1  0  0  0 ]
                    [               ]
                    [ 0  2  1  0  0 ]
                    [               ]
(%o2)               [ 0  0  2  1  0 ]
                    [               ]
                    [ 0  0  0  2  1 ]
                    [               ]
                    [ 0  0  0  0  2 ]
(%i3) JF(3,2);
                         [ 3  1 ]
(%o3)                    [      ]
                         [ 0  3 ]

To use this function write first load("diag").

Function: jordan (mat)

Returns the Jordan form of matrix mat, encoded as a list in a particular format. To get the corresponding matrix, call the function dispJordan using the output of jordan as the argument.

The elements of the returned list are themselves lists. The first element of each is an eigenvalue of mat. The remaining elements are positive integers which are the lengths of the Jordan blocks for this eigenvalue. These integers are listed in decreasing order. Eigenvalues are not repeated.

The functions dispJordan, minimalPoly and ModeMatrix expect the output of a call to jordan as an argument. If you construct this argument by hand, rather than by calling jordan, you must ensure that each eigenvalue only appears once and that the block sizes are listed in decreasing order, otherwise the functions might give incorrect answers.

Example:

(%i1) load("diag")$

(%i2) A: matrix([2,0,0,0,0,0,0,0],
                [1,2,0,0,0,0,0,0],
                [-4,1,2,0,0,0,0,0],
                [2,0,0,2,0,0,0,0],
                [-7,2,0,0,2,0,0,0],
                [9,0,-2,0,1,2,0,0],
                [-34,7,1,-2,-1,1,2,0],
                [145,-17,-16,3,9,-2,0,3])$

(%i3) jordan (A);
(%o3)                [[2, 3, 3, 1], [3, 1]]

(%i4) dispJordan (%);
                   [ 2  1  0  0  0  0  0  0 ]
                   [                        ]
                   [ 0  2  1  0  0  0  0  0 ]
                   [                        ]
                   [ 0  0  2  0  0  0  0  0 ]
                   [                        ]
                   [ 0  0  0  2  1  0  0  0 ]
(%o4)              [                        ]
                   [ 0  0  0  0  2  1  0  0 ]
                   [                        ]
                   [ 0  0  0  0  0  2  0  0 ]
                   [                        ]
                   [ 0  0  0  0  0  0  2  0 ]
                   [                        ]
                   [ 0  0  0  0  0  0  0  3 ]

To use this function write first load("diag"). See also dispJordan and minimalPoly.

Function: dispJordan (l)

Returns a matrix in Jordan canonical form (JCF) corresponding to the list of eigenvalues and multiplicities given by l. This list should be in the format given by the jordan function. See jordan for details of this format.

Example:

(%i1) load("diag")$

(%i2) b1:matrix([0,0,1,1,1],
                [0,0,0,1,1],
                [0,0,0,0,1],
                [0,0,0,0,0],
                [0,0,0,0,0])$

(%i3) jordan(b1);
(%o3)                  [[0, 3, 2]]
(%i4) dispJordan(%);
                    [ 0  1  0  0  0 ]
                    [               ]
                    [ 0  0  1  0  0 ]
                    [               ]
(%o4)               [ 0  0  0  0  0 ]
                    [               ]
                    [ 0  0  0  0  1 ]
                    [               ]
                    [ 0  0  0  0  0 ]

To use this function write first load("diag"). See also jordan and minimalPoly.

Function: minimalPoly (l)

Returns the minimal polynomial of the matrix whose Jordan form is described by the list l. This list should be in the format given by the jordan function. See jordan for details of this format.

Example:

(%i1) load("diag")$

(%i2) a:matrix([2,1,2,0],
               [-2,2,1,2],
               [-2,-1,-1,1],
               [3,1,2,-1])$

(%i3) jordan(a);
(%o3)               [[- 1, 1], [1, 3]]
(%i4) minimalPoly(%);
                            3
(%o4)                (x - 1)  (x + 1)

To use this function write first load("diag"). See also jordan and dispJordan.

Function: ModeMatrix (A, [jordan_info])

Returns an invertible matrix M such that (M^^-1).A.M is the Jordan form of A.

To calculate this, Maxima must find the Jordan form of A, which might be quite computationally expensive. If that has already been calculated by a previous call to jordan, pass it as a second argument, jordan_info. See jordan for details of the required format.

Example:

(%i1) load("diag")$
(%i2) A: matrix([2,1,2,0], [-2,2,1,2], [-2,-1,-1,1], [3,1,2,-1])$
(%i3) M: ModeMatrix (A);
                      [  1    - 1   1   1 ]
                      [                   ]
                      [   1               ]
                      [ - -   - 1   0   0 ]
                      [   9               ]
                      [                   ]
(%o3)                 [   13              ]
                      [ - --   1   - 1  0 ]
                      [   9               ]
                      [                   ]
                      [  17               ]
                      [  --   - 1   1   1 ]
                      [  9                ]

(%i4) is ((M^^-1) . A . M = dispJordan (jordan (A)));
(%o4)                         true

Note that, in this example, the Jordan form of A is computed twice. To avoid this, we could have stored the output of jordan(A) in a variable and passed that to both ModeMatrix and dispJordan.

To use this function write first load("diag"). See also jordan and dispJordan.

Function: mat_function (f,A)

Returns f(A), where f is an analytic function and A a matrix. This computation is based on the Taylor expansion of f. It is not efficient for numerical evaluation, but can give symbolic answers for small matrices.

Example 1:

The exponential of a matrix. We only give the first row of the answer, since the output is rather large.

(%i1) load("diag")$
(%i2) A: matrix ([0,1,0], [0,0,1], [-1,-3,-3])$

(%i3) ratsimp (mat_function (exp, t*A)[1]);
           2              - t                   2   - t
         (t  + 2 t + 2) %e       2        - t  t  %e
(%o3)   [--------------------, (t  + t) %e   , --------]
                  2                               2

Example 2:

Comparison with the Taylor series for the exponential and also comparing exp(%i*A) with sine and cosine.

(%i1) load("diag")$

(%i2) A: matrix ([0,1,1,1],
                 [0,0,0,1],
                 [0,0,0,1],
                 [0,0,0,0])$

(%i3) ratsimp (mat_function (exp, t*A));
                       [           2     ]
                       [ 1  t  t  t  + t ]
                       [                 ]
(%o3)                  [ 0  1  0    t    ]
                       [                 ]
                       [ 0  0  1    t    ]
                       [                 ]
                       [ 0  0  0    1    ]

(%i4) minimalPoly (jordan (A));
                                3
(%o4)                          x

(%i5) ratsimp (ident(4) + t*A + 1/2*(t^2)*A^^2);
                       [           2     ]
                       [ 1  t  t  t  + t ]
                       [                 ]
(%o5)                  [ 0  1  0    t    ]
                       [                 ]
                       [ 0  0  1    t    ]
                       [                 ]
                       [ 0  0  0    1    ]

(%i6) ratsimp (mat_function (exp, %i*t*A));
                  [                        2 ]
                  [ 1  %i t  %i t  %i t - t  ]
                  [                          ]
(%o6)             [ 0   1     0      %i t    ]
                  [                          ]
                  [ 0   0     1      %i t    ]
                  [                          ]
                  [ 0   0     0        1     ]

(%i7) ratsimp (mat_function (cos, t*A) + %i*mat_function (sin, t*A));
                  [                        2 ]
                  [ 1  %i t  %i t  %i t - t  ]
                  [                          ]
(%o7)             [ 0   1     0      %i t    ]
                  [                          ]
                  [ 0   0     1      %i t    ]
                  [                          ]
                  [ 0   0     0        1     ]

Example 3:

Power operations.

(%i1) load("diag")$
(%i2) A: matrix([1,2,0], [0,1,0], [1,0,1])$
(%i3) integer_pow(x) := block ([k], declare (k, integer), x^k)$

(%i4) mat_function (integer_pow, A);
                       [ 1     2 k     0 ]
                       [                 ]
(%o4)                  [ 0      1      0 ]
                       [                 ]
                       [ k  (k - 1) k  1 ]

(%i5) A^^20;
                         [ 1   40   0 ]
                         [            ]
(%o5)                    [ 0    1   0 ]
                         [            ]
                         [ 20  380  1 ]

To use this function write first load("diag").

Category: Statistical functions · Category: Share packages · Category: Package distrib

52 distrib

52.1 Introduction to distrib

Package distrib contains a set of functions for making probability computations on both discrete and continuous univariate models.

What follows is a short reminder of basic probabilistic related definitions.

Let f(x) be the density function of an absolute continuous random variable X. The distribution function is defined as

                       x
                      /
                      [
               F(x) = I     f(u) du
                      ]
                      /
                       minf

which equals the probability Pr(X <= x).

The mean value is a localization parameter and is defined as

                     inf
                    /
                    [
           E[X]  =  I   x f(x) dx
                    ]
                    /
                     minf

The variance is a measure of variation,

                 inf
                /
                [                    2
         V[X] = I     f(x) (x - E[X])  dx
                ]
                /
                 minf

which is a positive real number. The square root of the variance is the standard deviation, D[X]=sqrt(V[X]), and it is another measure of variation.

The skewness coefficient is a measure of non-symmetry,

                 inf
                /
            1   [                    3
  SK[X] = ----- I     f(x) (x - E[X])  dx
              3 ]
          D[X]  /
                 minf

And the kurtosis coefficient measures the peakedness of the distribution,

                 inf
                /
            1   [                    4
  KU[X] = ----- I     f(x) (x - E[X])  dx - 3
              4 ]
          D[X]  /
                 minf

If X is gaussian, KU[X]=0. In fact, both skewness and kurtosis are shape parameters used to measure the non–gaussianity of a distribution.

If the random variable X is discrete, the density, or probability, function f(x) takes positive values within certain countable set of numbers x_i, and zero elsewhere. In this case, the distribution function is

                       ====
                       \
                F(x) =  >    f(x )
                       /        i
                       ====
                      x <= x
                       i

The mean, variance, standard deviation, skewness coefficient and kurtosis coefficient take the form

                       ====
                       \
                E[X] =  >  x  f(x ) ,
                       /    i    i
                       ====
                        x 
                         i

                ====
                \                     2
        V[X] =   >    f(x ) (x - E[X])  ,
                /        i    i
                ====
                 x
                  i

               D[X] = sqrt(V[X]),

                     ====
              1      \                     3
  SK[X] =  -------    >    f(x ) (x - E[X])  
           D[X]^3    /        i    i
                     ====
                      x
                       i

and

                     ====
              1      \                     4
  KU[X] =  -------    >    f(x ) (x - E[X])   - 3 ,
           D[X]^4    /        i    i
                     ====
                      x
                       i

respectively.

There is a naming convention in package distrib. Every function name has two parts, the first one makes reference to the function or parameter we want to calculate,

Functions:
   Density function            (pdf_*)
   Distribution function       (cdf_*)
   Quantile                    (quantile_*)
   Mean                        (mean_*)
   Variance                    (var_*)
   Standard deviation          (std_*)
   Skewness coefficient        (skewness_*)
   Kurtosis coefficient        (kurtosis_*)
   Random variate              (random_*)

The second part is an explicit reference to the probabilistic model,

Continuous distributions:
   Normal              (*normal)
   Student             (*student_t)
   Chi^2               (*chi2)
   Noncentral Chi^2    (*noncentral_chi2)
   F                   (*f)
   Exponential         (*exp)
   Lognormal           (*lognormal)
   Gamma               (*gamma)
   Beta                (*beta)
   Continuous uniform  (*continuous_uniform)
   Logistic            (*logistic)
   Pareto              (*pareto)
   Weibull             (*weibull)
   Rayleigh            (*rayleigh)
   Laplace             (*laplace)
   Cauchy              (*cauchy)
   Gumbel              (*gumbel)

Discrete distributions:
   Binomial             (*binomial)
   Poisson              (*poisson)
   Bernoulli            (*bernoulli)
   Geometric            (*geometric)
   Discrete uniform     (*discrete_uniform)
   hypergeometric       (*hypergeometric)
   Negative binomial    (*negative_binomial)
   Finite discrete      (*general_finite_discrete)

For example, pdf_student_t(x,n) is the density function of the Student distribution with n degrees of freedom, std_pareto(a,b) is the standard deviation of the Pareto distribution with parameters a and b and kurtosis_poisson(m) is the kurtosis coefficient of the Poisson distribution with mean m.

In order to make use of package distrib you need first to load it by typing

(%i1) load("distrib")$

For comments, bugs or suggestions, please contact the author at ’riotorto AT yahoo DOT com’.

52.2 Functions and Variables for continuous distributions

Function: pdf_normal (x,m,s)

Returns the value at x of the density function of a Normal(m,s) random variable, with s>0. To make use of this function, write first load("distrib").

Function: cdf_normal (x,m,s)

Returns the value at x of the distribution function of a Normal(m,s) random variable, with s>0. This function is defined in terms of Maxima’s built-in error function erf.

(%i1) load ("distrib")$
(%i2) cdf_normal(x,m,s);
                                    x - m
                              erf(---------)
                                  sqrt(2) s    1
(%o2)                         -------------- + -
                                    2          2

52.3 Functions and Variables for discrete distributions

Function: pdf_general_finite_discrete (x,v)

Returns the value at x of the probability function of a general finite discrete random variable, with vector probabilities v, such that Pr(X=i) = v_i. Vector v can be a list of nonnegative expressions, whose components will be normalized to get a vector of probabilities. To make use of this function, write first load("distrib").

(%i1) load ("distrib")$
(%i2) pdf_general_finite_discrete(2, [1/7, 4/7, 2/7]);
                                4
(%o2)                           -
                                7
(%i3) pdf_general_finite_discrete(2, [1, 4, 2]);
                                4
(%o3)                           -
                                7

Function: cdf_general_finite_discrete (x,v)

Returns the value at x of the distribution function of a general finite discrete random variable, with vector probabilities v.

See pdf_general_finite_discrete for more details.

(%i1) load ("distrib")$
(%i2) cdf_general_finite_discrete(2, [1/7, 4/7, 2/7]);
                                5
(%o2)                           -
                                7
(%i3) cdf_general_finite_discrete(2, [1, 4, 2]);
                                5
(%o3)                           -
                                7
(%i4) cdf_general_finite_discrete(2+1/2, [1, 4, 2]);
                                5
(%o4)                           -
                                7

Function: quantile_general_finite_discrete (q,v)

Returns the q-quantile of a general finite discrete random variable, with vector probabilities v.

See pdf_general_finite_discrete for more details.

Function: mean_general_finite_discrete (v)

Returns the mean of a general finite discrete random variable, with vector probabilities v.

See pdf_general_finite_discrete for more details.

Function: var_general_finite_discrete (v)

Returns the variance of a general finite discrete random variable, with vector probabilities v.

See pdf_general_finite_discrete for more details.

Function: std_general_finite_discrete (v)

Returns the standard deviation of a general finite discrete random variable, with vector probabilities v.

See pdf_general_finite_discrete for more details.

Function: skewness_general_finite_discrete (v)

Returns the skewness coefficient of a general finite discrete random variable, with vector probabilities v.

See pdf_general_finite_discrete for more details.

Function: kurtosis_general_finite_discrete (v)

Returns the kurtosis coefficient of a general finite discrete random variable, with vector probabilities v.

See pdf_general_finite_discrete for more details.

Category: Package distrib · Category: Random numbers

Function: random_general_finite_discrete (v)
random_general_finite_discrete (v,m)

Returns a general finite discrete random variate, with vector probabilities v. Calling random_general_finite_discrete with a second argument m, a random sample of size m will be simulated.

See pdf_general_finite_discrete for more details.

(%i1) load ("distrib")$
(%i2) random_general_finite_discrete([1,3,1,5]);
(%o2)                          4
(%i3) random_general_finite_discrete([1,3,1,5], 10);
(%o3)           [4, 2, 2, 3, 2, 4, 4, 1, 2, 2]

Function: pdf_binomial (x,n,p)

Returns the value at x of the probability function of a Binomial(n,p) random variable, with 0 \leq p \leq 1 and n a positive integer. To make use of this function, write first load("distrib").

Function: cdf_binomial (x,n,p)

Returns the value at x of the distribution function of a Binomial(n,p) random variable, with 0 \leq p \leq 1 and n a positive integer.

(%i1) load ("distrib")$
(%i2) cdf_binomial(5,7,1/6);
                            7775
(%o2)                       ----
                            7776
(%i3) float(%);
(%o3)               .9998713991769548

Function: quantile_binomial (q,n,p)

Returns the q-quantile of a Binomial(n,p) random variable, with 0 \leq p \leq 1 and n a positive integer; in other words, this is the inverse of cdf_binomial. Argument q must be an element of [0,1]. To make use of this function, write first load("distrib").

Function: mean_binomial (n,p)

Returns the mean of a Binomial(n,p) random variable, with 0 \leq p \leq 1 and n a positive integer. To make use of this function, write first load("distrib").

Function: var_binomial (n,p)

Returns the variance of a Binomial(n,p) random variable, with 0 \leq p \leq 1 and n a positive integer. To make use of this function, write first load("distrib").

Function: std_binomial (n,p)

Returns the standard deviation of a Binomial(n,p) random variable, with 0 \leq p \leq 1 and n a positive integer. To make use of this function, write first load("distrib").

Function: skewness_binomial (n,p)

Returns the skewness coefficient of a Binomial(n,p) random variable, with 0 \leq p \leq 1 and n a positive integer. To make use of this function, write first load("distrib").

Function: kurtosis_binomial (n,p)

Returns the kurtosis coefficient of a Binomial(n,p) random variable, with 0 \leq p \leq 1 and n a positive integer. To make use of this function, write first load("distrib").

Category: Package distrib · Category: Random numbers

Function: random_binomial (n,p)
random_binomial (n,p,m)

Returns a Binomial(n,p) random variate, with 0 \leq p \leq 1 and n a positive integer. Calling random_binomial with a third argument m, a random sample of size m will be simulated.

The implemented algorithm is based on the one described in Kachitvichyanukul, V. and Schmeiser, B.W. (1988) Binomial Random Variate Generation. Communications of the ACM, 31, Feb., 216.

To make use of this function, write first load("distrib").

Function: pdf_poisson (x,m)

Returns the value at x of the probability function of a Poisson(m) random variable, with m>0. To make use of this function, write first load("distrib").

Function: cdf_poisson (x,m)

Returns the value at x of the distribution function of a Poisson(m) random variable, with m>0.

(%i1) load ("distrib")$
(%i2) cdf_poisson(3,5);
(%o2)       gamma_incomplete_regularized(4, 5)
(%i3) float(%);
(%o3)               .2650259152973623

Function: quantile_poisson (q,m)

Returns the q-quantile of a Poisson(m) random variable, with m>0; in other words, this is the inverse of cdf_poisson. Argument q must be an element of [0,1]. To make use of this function, write first load("distrib").

Function: mean_poisson (m)

Returns the mean of a Poisson(m) random variable, with m>0. To make use of this function, write first load("distrib").

Function: var_poisson (m)

Returns the variance of a Poisson(m) random variable, with m>0. To make use of this function, write first load("distrib").

Function: std_poisson (m)

Returns the standard deviation of a Poisson(m) random variable, with m>0. To make use of this function, write first load("distrib").

Function: skewness_poisson (m)

Returns the skewness coefficient of a Poisson(m) random variable, with m>0. To make use of this function, write first load("distrib").

Function: kurtosis_poisson (m)

Returns the kurtosis coefficient of a Poisson random variable Poi(m), with m>0. To make use of this function, write first load("distrib").

Category: Package distrib · Category: Random numbers

Function: random_poisson (m)
random_poisson (m,n)

Returns a Poisson(m) random variate, with m>0. Calling random_poisson with a second argument n, a random sample of size n will be simulated.

The implemented algorithm is the one described in Ahrens, J.H. and Dieter, U. (1982) Computer Generation of Poisson Deviates From Modified Normal Distributions. ACM Trans. Math. Software, 8, 2, June,163-179.

To make use of this function, write first load("distrib").

Function: pdf_bernoulli (x,p)

Returns the value at x of the probability function of a Bernoulli(p) random variable, with 0 \leq p \leq 1.

The Bernoulli(p) random variable is equivalent to the Binomial(1,p).

(%i1) load ("distrib")$
(%i2) pdf_bernoulli(1,p);
(%o2)                           p

Function: cdf_bernoulli (x,p)

Returns the value at x of the distribution function of a Bernoulli(p) random variable, with 0 \leq p \leq 1. To make use of this function, write first load("distrib").

Function: quantile_bernoulli (q,p)

Returns the q-quantile of a Bernoulli(p) random variable, with 0 \leq p \leq 1; in other words, this is the inverse of cdf_bernoulli. Argument q must be an element of [0,1]. To make use of this function, write first load("distrib").

Function: mean_bernoulli (p)

Returns the mean of a Bernoulli(p) random variable, with 0 \leq p \leq 1.

The Bernoulli(p) random variable is equivalent to the Binomial(1,p).

(%i1) load ("distrib")$
(%i2) mean_bernoulli(p);
(%o2)                           p

Function: var_bernoulli (p)

Returns the variance of a Bernoulli(p) random variable, with 0 \leq p \leq 1.

The Bernoulli(p) random variable is equivalent to the Binomial(1,p).

(%i1) load ("distrib")$
(%i2) var_bernoulli(p);
(%o2)                       (1 - p) p

Function: std_bernoulli (p)

Returns the standard deviation of a Bernoulli(p) random variable, with 0 \leq p \leq 1.

The Bernoulli(p) random variable is equivalent to the Binomial(1,p).

(%i1) load ("distrib")$
(%i2) std_bernoulli(p);
(%o2)                           sqrt((1 - p) p)

Function: skewness_bernoulli (p)

Returns the skewness coefficient of a Bernoulli(p) random variable, with 0 \leq p \leq 1.

The Bernoulli(p) random variable is equivalent to the Binomial(1,p).

(%i1) load ("distrib")$
(%i2) skewness_bernoulli(p);
                                    1 - 2 p
(%o2)                           ---------------
                                sqrt((1 - p) p)

Function: kurtosis_bernoulli (p)

Returns the kurtosis coefficient of a Bernoulli(p) random variable, with 0 \leq p \leq 1.

The Bernoulli(p) random variable is equivalent to the Binomial(1,p).

(%i1) load ("distrib")$
(%i2) kurtosis_bernoulli(p);
                         1 - 6 (1 - p) p
(%o2)                    ---------------
                            (1 - p) p

Category: Package distrib · Category: Random numbers

Function: random_bernoulli (p)
random_bernoulli (p,n)

Returns a Bernoulli(p) random variate, with 0 \leq p \leq 1. Calling random_bernoulli with a second argument n, a random sample of size n will be simulated.

This is a direct application of the random built-in Maxima function.

See also random. To make use of this function, write first load("distrib").

Function: pdf_geometric (x,p)

Returns the value at x of the probability function of a Geometric(p) random variable, with 0 < p <= 1.

The probability function is defined as p (1 - p)^x. This is interpreted as the probability of x failures before the first success.

load("distrib") loads this function.

Function: cdf_geometric (x,p)

Returns the value at x of the distribution function of a Geometric(p) random variable, with 0 < p <= 1.

The probability from which the distribution function is derived is defined as p (1 - p)^x. This is interpreted as the probability of x failures before the first success.

load("distrib") loads this function.

Function: quantile_geometric (q,p)

Returns the q-quantile of a Geometric(p) random variable, with 0 < p <= 1; in other words, this is the inverse of cdf_geometric. Argument q must be an element of [0,1].

The probability from which the quantile is derived is defined as p (1 - p)^x. This is interpreted as the probability of x failures before the first success.

load("distrib") loads this function.

Function: mean_geometric (p)

Returns the mean of a Geometric(p) random variable, with 0 < p <= 1.

The probability from which the mean is derived is defined as p (1 - p)^x. This is interpreted as the probability of x failures before the first success.

load("distrib") loads this function.

Function: var_geometric (p)

Returns the variance of a Geometric(p) random variable, with 0 < p <= 1.

The probability from which the variance is derived is defined as p (1 - p)^x. This is interpreted as the probability of x failures before the first success.

load("distrib") loads this function.

Function: std_geometric (p)

Returns the standard deviation of a Geometric(p) random variable, with 0 < p <= 1.

The probability from which the standard deviation is derived is defined as p (1 - p)^x. This is interpreted as the probability of x failures before the first success.

load("distrib") loads this function.

Function: skewness_geometric (p)

Returns the skewness coefficient of a Geometric(p) random variable, with 0 < p <= 1.

The probability from which the skewness is derived is defined as p (1 - p)^x. This is interpreted as the probability of x failures before the first success.

load("distrib") loads this function.

Function: kurtosis_geometric (p)

Returns the kurtosis coefficient of a geometric random variable Geometric(p), with 0 < p <= 1.

The probability from which the kurtosis is derived is defined as p (1 - p)^x. This is interpreted as the probability of x failures before the first success.

load("distrib") loads this function.

Category: Package distrib · Category: Random numbers

Function: random_geometric (p)
random_geometric (p,n)

random_geometric(p) returns one random sample from a Geometric(p) distribution, with 0 < p <= 1.

random_geometric(p, n) returns a list of n random samples.

The algorithm is based on simulation of Bernoulli trials.

The probability from which the random sample is derived is defined as p (1 - p)^x. This is interpreted as the probability of x failures before the first success.

load("distrib") loads this function.

Function: pdf_discrete_uniform (x,n)

Returns the value at x of the probability function of a Discrete Uniform(n) random variable, with n a strictly positive integer. To make use of this function, write first load("distrib").

Function: cdf_discrete_uniform (x,n)

Returns the value at x of the distribution function of a Discrete Uniform(n) random variable, with n a strictly positive integer. To make use of this function, write first load("distrib").

Function: quantile_discrete_uniform (q,n)

Returns the q-quantile of a Discrete Uniform(n) random variable, with n a strictly positive integer; in other words, this is the inverse of cdf_discrete_uniform. Argument q must be an element of [0,1]. To make use of this function, write first load("distrib").

Function: mean_discrete_uniform (n)

Returns the mean of a Discrete Uniform(n) random variable, with n a strictly positive integer. To make use of this function, write first load("distrib").

Function: var_discrete_uniform (n)

Returns the variance of a Discrete Uniform(n) random variable, with n a strictly positive integer. To make use of this function, write first load("distrib").

Function: std_discrete_uniform (n)

Returns the standard deviation of a Discrete Uniform(n) random variable, with n a strictly positive integer. To make use of this function, write first load("distrib").

Function: skewness_discrete_uniform (n)

Returns the skewness coefficient of a Discrete Uniform(n) random variable, with n a strictly positive integer. To make use of this function, write first load("distrib").

Function: kurtosis_discrete_uniform (n)

Returns the kurtosis coefficient of a Discrete Uniform(n) random variable, with n a strictly positive integer. To make use of this function, write first load("distrib").

Category: Package distrib · Category: Random numbers

Function: random_discrete_uniform (n)
random_discrete_uniform (n,m)

Returns a Discrete Uniform(n) random variate, with n a strictly positive integer. Calling random_discrete_uniform with a second argument m, a random sample of size m will be simulated.

This is a direct application of the random built-in Maxima function.

See also random. To make use of this function, write first load("distrib").

Function: pdf_hypergeometric (x,n1,n2,n)

Returns the value at x of the probability function of a Hypergeometric(n1,n2,n) random variable, with n1, n2 and n non negative integers and n<=n1+n2. Being n1 the number of objects of class A, n2 the number of objects of class B, and n the size of the sample without replacement, this function returns the probability of event "exactly x objects are of class A".

To make use of this function, write first load("distrib").

Function: cdf_hypergeometric (x,n1,n2,n)

Returns the value at x of the distribution function of a Hypergeometric(n1,n2,n) random variable, with n1, n2 and n non negative integers and n<=n1+n2. See pdf_hypergeometric for a more complete description.

To make use of this function, write first load("distrib").

Function: quantile_hypergeometric (q,n1,n2,n)

Returns the q-quantile of a Hypergeometric(n1,n2,n) random variable, with n1, n2 and n non negative integers and n<=n1+n2; in other words, this is the inverse of cdf_hypergeometric. Argument q must be an element of [0,1]. To make use of this function, write first load("distrib").

Function: mean_hypergeometric (n1,n2,n)

Returns the mean of a discrete uniform random variable Hyp(n1,n2,n), with n1, n2 and n non negative integers and n<=n1+n2. To make use of this function, write first load("distrib").

Function: var_hypergeometric (n1,n2,n)

Returns the variance of a hypergeometric random variable Hyp(n1,n2,n), with n1, n2 and n non negative integers and n<=n1+n2. To make use of this function, write first load("distrib").

Function: std_hypergeometric (n1,n2,n)

Returns the standard deviation of a Hypergeometric(n1,n2,n) random variable, with n1, n2 and n non negative integers and n<=n1+n2. To make use of this function, write first load("distrib").

Function: skewness_hypergeometric (n1,n2,n)

Returns the skewness coefficient of a Hypergeometric(n1,n2,n) random variable, with n1, n2 and n non negative integers and n<=n1+n2. To make use of this function, write first load("distrib").

Function: kurtosis_hypergeometric (n1,n2,n)

Returns the kurtosis coefficient of a Hypergeometric(n1,n2,n) random variable, with n1, n2 and n non negative integers and n<=n1+n2. To make use of this function, write first load("distrib").

Category: Package distrib · Category: Random numbers

Function: random_hypergeometric (n1,n2,n)
random_hypergeometric (n1,n2,n,m)

Returns a Hypergeometric(n1,n2,n) random variate, with n1, n2 and n non negative integers and n<=n1+n2. Calling random_hypergeometric with a fourth argument m, a random sample of size m will be simulated.

Algorithm described in Kachitvichyanukul, V., Schmeiser, B.W. (1985) Computer generation of hypergeometric random variates. Journal of Statistical Computation and Simulation 22, 127-145.

To make use of this function, write first load("distrib").

Function: pdf_negative_binomial (x,n,p)

Returns the value at x of the probability function of a Negative Binomial(n,p) random variable, with 0 < p \leq 1 and n a positive number. To make use of this function, write first load("distrib").

Function: cdf_negative_binomial (x,n,p)

Returns the value at x of the distribution function of a Negative Binomial(n,p) random variable, with 0 < p \leq 1 and n a positive number.

(%i1) load ("distrib")$
(%i2) cdf_negative_binomial(3,4,1/8);
                            3271
(%o2)                      ------
                           524288

Function: quantile_negative_binomial (q,n,p)

Returns the q-quantile of a Negative Binomial(n,p) random variable, with 0 < p \leq 1 and n a positive number; in other words, this is the inverse of cdf_negative_binomial. Argument q must be an element of [0,1]. To make use of this function, write first load("distrib").

Function: mean_negative_binomial (n,p)

Returns the mean of a Negative Binomial(n,p) random variable, with 0 < p \leq 1 and n a positive number. To make use of this function, write first load("distrib").

Function: var_negative_binomial (n,p)

Returns the variance of a Negative Binomial(n,p) random variable, with 0 < p \leq 1 and n a positive number. To make use of this function, write first load("distrib").

Function: std_negative_binomial (n,p)

Returns the standard deviation of a Negative Binomial(n,p) random variable, with 0 < p \leq 1 and n a positive number. To make use of this function, write first load("distrib").

Function: skewness_negative_binomial (n,p)

Returns the skewness coefficient of a Negative Binomial(n,p) random variable, with 0 < p \leq 1 and n a positive number. To make use of this function, write first load("distrib").

Function: kurtosis_negative_binomial (n,p)

Returns the kurtosis coefficient of a Negative Binomial(n,p) random variable, with 0 < p \leq 1 and n a positive number. To make use of this function, write first load("distrib").

Category: Package distrib · Category: Random numbers

Function: random_negative_binomial (n,p)
random_negative_binomial (n,p,m)

Returns a Negative Binomial(n,p) random variate, with 0 < p \leq 1 and n a positive number. Calling random_negative_binomial with a third argument m, a random sample of size m will be simulated.

Algorithm described in Devroye, L. (1986) Non-Uniform Random Variate Generation. Springer Verlag, p. 480.

To make use of this function, write first load("distrib").

53 draw

53.1 Introduction to draw

draw is a Maxima-Gnuplot and a Maxima-vtk interface.

There are three main functions to be used at Maxima level:

draw2d, draws a single 2D scene.
draw3d, draws a single 3D scene.
draw, can be filled with multiple gr2d and gr3d commands that each creates a draw scene all sharing the same window.

Each scene can contain any number of objects and key=value pairs with options for the scene or the following objects.

A selection of useful objects a scene can be made up from are:

explicit plots a function.
implicit plots all points an equation is true at.
points plots points that are connected by lines if the option points_joined was set to true in a previous line of the current scene.
parametric allows to specify separate expressions that calculate the x, y (and in 3d plots also for the z) variable.

A short description of all draw commands and options including example plots (in the html and pdf version of this manual) can be found in the section See Functions and Variables for draw. A online version of the html manual can be found at maxima.sourceforge.net/docs/manual/maxima_singlepage.html#draw. More elaborated examples of this package can be found at the following locations:

http://tecnostats.net/Maxima/gnuplot
http://tecnostats.net/Maxima/vtk

Example:

(%i1) draw2d(
          title="Two simple plots",
          xlabel="x",ylabel="y",grid=true,

          color=red,key="A sinus",
          explicit(sin(x),x,1,10),
          color=blue,line_type=dots,key="A cosinus",
          explicit(cos(x),x,1,10)
)$

You need Gnuplot 4.2 or newer to run draw; If you are using wxMaxima as a front end wxdraw, wxdraw2d and wxdraw3d are drop-in replacements for draw that do the same as draw, draw2d and draw3d but embed the resulting plot in the worksheet.

Category: Plotting · Category: Share packages · Category: Package draw

53.2 Functions and Variables for draw

53.2.1 Scenes

Scene constructor: gr2d (argument_1, ...)

Function gr2d builds an object describing a 2D scene. Arguments are graphic options, graphic objects, or lists containing both graphic options and objects. This scene is interpreted sequentially: graphic options affect those graphic objects placed on its right. Some graphic options affect the global appearance of the scene.

This is the list of graphic objects available for scenes in two dimensions: bars, ellipse, explicit, image, implicit, label, parametric, points, polar, polygon, quadrilateral, rectangle, triangle, vector and geomap (this one defined in package worldmap).

53.2.2 Functions

Function: draw (<arg_1>, ...)

Plots a series of scenes; its arguments are gr2d and/or gr3d objects, together with some options, or lists of scenes and options. By default, the scenes are put together in one column.

Besides scenes the function draw accepts the following global options: terminal, columns, dimensions, file_name and delay.

Functions draw2d and draw3d short cuts that can be used when only one scene is required, in two or three dimensions, respectively.

53.2.3 Graphics options

Graphic option: adapt_depth

Default value: 10

adapt_depth is the maximum number of splittings used by the adaptive plotting routine.

This option is relevant only for 2d explicit functions.

53.2.4 Graphics objects

Graphic object: bars ([x1,h1,w1], [x2,h2,w2, ...])

Draws vertical bars in 2D.

bars ([x1,h1,w1], [x2,h2,w2, ...]) draws bars centered at values x1, x2, ... with heights h1, h2, ... and widths w1, w2, ...

This object is affected by the following graphic options: key, fill_color, fill_density and line_width.

Example:

(%i1) draw2d(
       key          = "Group A",
       fill_color   = blue,
       fill_density = 0.2,
       bars([0.8,5,0.4],[1.8,7,0.4],[2.8,-4,0.4]),
       key          = "Group B",
       fill_color   = red,
       fill_density = 0.6,
       line_width   = 4,
       bars([1.2,4,0.4],[2.2,-2,0.4],[3.2,5,0.4]),
       xaxis = true);

Graphic object: cylindrical (radius, z, minz, maxz, azi, minazi, maxazi)

Draws 3D functions defined in cylindrical coordinates.

cylindrical(radius, z, minz, maxz, azi, minazi, maxazi) plots the function radius(z, azi) defined in cylindrical coordinates, with variable z taking values from minz to maxz and azimuth azi taking values from minazi to maxazi.

This object is affected by the following graphic options: xu_grid, yv_grid, line_type, key, wired_surface, enhanced3d and color

Example:

(%i1) draw3d(cylindrical(1,z,-2,2,az,0,2*%pi))$

Graphic object: elevation_grid (mat,x0,y0,width,height)

Draws matrix mat in 3D space. z values are taken from mat, the abscissas range from x0 to x0 + width and ordinates from y0 to y0 + height. Element a(1,1) is projected on point (x0,y0+height), a(1,n) on (x0+width,y0+height), a(m,1) on (x0,y0), and a(m,n) on (x0+width,y0).

This object is affected by the following graphic options: line_type,, line_width key, wired_surface, enhanced3d and color

In older versions of Maxima, elevation_grid was called mesh. See also mesh.

Example:

(%i1) m: apply(
            matrix,
            makelist(makelist(random(10.0),k,1,30),i,1,20)) $
(%i2) draw3d(
         color = blue,
         elevation_grid(m,0,0,3,2),
         xlabel = "x",
         ylabel = "y",
         surface_hide = true);

Graphic object: ellipse (xc, yc, a, b, ang1, ang2)

Draws ellipses and circles in 2D.

ellipse (xc, yc, a, b, ang1, ang2) plots an ellipse centered at [xc, yc] with horizontal and vertical semi axis a and b, respectively, starting at angle ang1 with an amplitude equal to angle ang2.

This object is affected by the following graphic options: nticks, transparent, fill_color, border, line_width, line_type, key and color

Example:

(%i1) draw2d(transparent = false,
             fill_color  = red,
             color       = gray30,
             transparent = false,
             line_width  = 5,
             ellipse(0,6,3,2,270,-270),
             /* center (x,y), a, b, start & end in degrees */
             transparent = true,
             color       = blue,
             line_width  = 3,
             ellipse(2.5,6,2,3,30,-90),
             xrange      = [-3,6],
             yrange      = [2,9] )$

Graphic object: errors ([x1, x2, …], [y1, y2, …])

Draws points with error bars, horizontally, vertically or both, depending on the value of option error_type.

If error_type = x, arguments to errors must be of the form [x, y, xdelta] or [x, y, xlow, xhigh]. If error_type = y, arguments must be of the form [x, y, ydelta] or [x, y, ylow, yhigh]. If error_type = xy or error_type = boxes, arguments to errors must be of the form [x, y, xdelta, ydelta] or [x, y, xlow, xhigh, ylow, yhigh].

53.3 Functions and Variables for pictures

Function: get_pixel (pic,x,y)

Returns pixel from picture. Coordinates x and y range from 0 to width-1 and height-1, respectively.

Function: make_level_picture
make_level_picture (data)
make_level_picture (data,width,height)

Returns a levels picture object. make_level_picture (data) builds the picture object from matrix data. make_level_picture (data,width,height) builds the object from a list of numbers; in this case, both the width and the height must be given.

The returned picture object contains the following four parts:

symbol level
image width
image height
an integer array with pixel data ranging from 0 to 255. Argument data must contain only numbers ranged from 0 to 255; negative numbers are substituted by 0, and those which are greater than 255 are set to 255.

Example:

Level picture from matrix.

(%i1) make_level_picture(matrix([3,2,5],[7,-9,3000]));
(%o1)         picture(level, 3, 2, {Array:  #(3 2 5 7 0 255)})

Level picture from numeric list.

(%i1) make_level_picture([-2,0,54,%pi],2,2);
(%o1)            picture(level, 2, 2, {Array:  #(0 0 54 3)})

Function: make_rgb_picture (redlevel,greenlevel,bluelevel)

Returns an rgb-coloured picture object. All three arguments must be levels picture; with red, green and blue levels.

The returned picture object contains the following four parts:

symbol rgb
image width
image height
an integer array of length 3*width*height with pixel data ranging from 0 to 255. Each pixel is represented by three consecutive numbers (red, green, blue).

Example:

(%i1) red: make_level_picture(matrix([3,2],[7,260]));
(%o1)           picture(level, 2, 2, {Array:  #(3 2 7 255)})
(%i2) green: make_level_picture(matrix([54,23],[73,-9]));
(%o2)           picture(level, 2, 2, {Array:  #(54 23 73 0)})
(%i3) blue: make_level_picture(matrix([123,82],[45,32.5698]));
(%o3)          picture(level, 2, 2, {Array:  #(123 82 45 33)})
(%i4) make_rgb_picture(red,green,blue);
(%o4) picture(rgb, 2, 2, 
              {Array:  #(3 54 123 2 23 82 7 73 45 255 0 33)})

Function: negative_picture (pic)

Returns the negative of a (level or rgb) picture.

Category: Package draw · Category: Predicate functions

Function: picture_equalp (x,y)

Returns true in case of equal pictures, and false otherwise.

Function: picturep (x)

Returns true if the argument is a well formed image, and false otherwise.

Category: Package draw · Category: Predicate functions

Function: read_xpm (xpm_file)

Reads a file in xpm and returns a picture object.

Function: rgb2level (pic)

Transforms an rgb picture into a level one by averaging the red, green and blue channels.

Function: take_channel (im,color)

If argument color is red, green or blue, function take_channel returns the corresponding color channel of picture im. Example:

(%i1) red: make_level_picture(matrix([3,2],[7,260]));
(%o1)           picture(level, 2, 2, {Array:  #(3 2 7 255)})
(%i2) green: make_level_picture(matrix([54,23],[73,-9]));
(%o2)           picture(level, 2, 2, {Array:  #(54 23 73 0)})
(%i3) blue: make_level_picture(matrix([123,82],[45,32.5698]));
(%o3)          picture(level, 2, 2, {Array:  #(123 82 45 33)})
(%i4) make_rgb_picture(red,green,blue);
(%o4) picture(rgb, 2, 2, 
              {Array:  #(3 54 123 2 23 82 7 73 45 255 0 33)})
(%i5) take_channel(%,'green);  /* simple quote!!! */
(%o5)           picture(level, 2, 2, {Array:  #(54 23 73 0)})

53.4 Functions and Variables for worldmap

53.4.1 Variables and Functions

Global variable: boundaries_array

Default value: false

boundaries_array is where the graphic object geomap looks for boundaries coordinates.

Each component of boundaries_array is an array of floating point quantities, the coordinates of a polygonal segment or map boundary.

53.4.2 Graphic objects

Graphic object: geomap
geomap (numlist)
geomap (numlist,3Dprojection)

Draws cartographic maps in 2D and 3D.

This function works together with global variable boundaries_array.

Argument numlist is a list containing numbers or lists of numbers. All these numbers must be integers greater or equal than zero, representing the components of global array boundaries_array.

Each component of boundaries_array is an array of floating point quantities, the coordinates of a polygonal segment or map boundary.

geomap (numlist) flattens its arguments and draws the associated boundaries in boundaries_array.

This object is affected by the following graphic options: line_width, line_type and color.

Examples:

A simple map defined by hand:

(%i1) load(worldmap)$
(%i2) /* Vertices of boundary #0: {(1,1),(2,5),(4,3)} */
   ( bnd0: make_array(flonum,6),
     bnd0[0]:1.0, bnd0[1]:1.0, bnd0[2]:2.0,
     bnd0[3]:5.0, bnd0[4]:4.0, bnd0[5]:3.0 )$
(%i3) /* Vertices of boundary #1: {(4,3),(5,4),(6,4),(5,1)} */
   ( bnd1: make_array(flonum,8),
     bnd1[0]:4.0, bnd1[1]:3.0, bnd1[2]:5.0, bnd1[3]:4.0,
     bnd1[4]:6.0, bnd1[5]:4.0, bnd1[6]:5.0, bnd1[7]:1.0)$
(%i4) /* Vertices of boundary #2: {(5,1), (3,0), (1,1)} */
   ( bnd2: make_array(flonum,6),
     bnd2[0]:5.0, bnd2[1]:1.0, bnd2[2]:3.0,
     bnd2[3]:0.0, bnd2[4]:1.0, bnd2[5]:1.0 )$
(%i5) /* Vertices of boundary #3: {(1,1), (4,3)} */
   ( bnd3: make_array(flonum,4),
     bnd3[0]:1.0, bnd3[1]:1.0, bnd3[2]:4.0, bnd3[3]:3.0)$
(%i6) /* Vertices of boundary #4: {(4,3), (5,1)} */
   ( bnd4: make_array(flonum,4),
     bnd4[0]:4.0, bnd4[1]:3.0, bnd4[2]:5.0, bnd4[3]:1.0)$
(%i7) /* Pack all together in boundaries_array */
   ( boundaries_array: make_array(any,5),
     boundaries_array[0]: bnd0, boundaries_array[1]: bnd1,
     boundaries_array[2]: bnd2, boundaries_array[3]: bnd3,
     boundaries_array[4]: bnd4 )$
(%i8) draw2d(geomap([0,1,2,3,4]))$

The auxiliary package worldmap sets the global variable boundaries_array to real world boundaries in (longitude, latitude) coordinates. These data are in the public domain and come from https://web.archive.org/web/20100310124019/http://www-cger.nies.go.jp/grid-e/gridtxt/grid19.html. Package worldmap defines also boundaries for countries, continents and coastlines as lists with the necessary components of boundaries_array (see file share/draw/worldmap.mac for more information). Package worldmap automatically loads package worldmap.

(%i1) load(worldmap)$
(%i2) c1: gr2d(geomap([Canada,United_States,
                       Mexico,Cuba]))$
(%i3) c2: gr2d(geomap(Africa))$
(%i4) c3: gr2d(geomap([Oceania,China,Japan]))$
(%i5) c4: gr2d(geomap([France,Portugal,Spain,
                       Morocco,Western_Sahara]))$
(%i6) draw(columns  = 2,
           c1,c2,c3,c4)$

Package worldmap is also useful for plotting countries as polygons. In this case, graphic object geomap is no longer necessary and the polygon object is used instead. Since lists are now used and not arrays, maps rendering will be slower. See also make_poly_country and make_poly_continent to understand the following code.

(%i1) load(worldmap)$
(%i2) mymap: append(
   [color      = white],  /* borders are white */
   [fill_color = red],             make_poly_country(Bolivia),
   [fill_color = cyan],            make_poly_country(Paraguay),
   [fill_color = green],           make_poly_country(Colombia),
   [fill_color = blue],            make_poly_country(Chile),
   [fill_color = "#23ab0f"],       make_poly_country(Brazil),
   [fill_color = goldenrod],       make_poly_country(Argentina),
   [fill_color = "midnight-blue"], make_poly_country(Uruguay))$
(%i3) apply(draw2d, mymap)$

geomap (numlist) projects map boundaries on the sphere of radius 1 centered at (0,0,0). It is possible to change the sphere or the projection type by using geomap (numlist,3Dprojection).

Available 3D projections:

[spherical_projection,x,y,z,r]: projects map boundaries on the sphere of radius r centered at (x,y,z).

(%i1) load(worldmap)$
(%i2) draw3d(geomap(Australia), /* default projection */
             geomap(Australia,
                    [spherical_projection,2,2,2,3]))$

[cylindrical_projection,x,y,z,r,rc]: re-projects spherical map boundaries on the cylinder of radius rc and axis passing through the poles of the globe of radius r centered at (x,y,z).
```
(%i1) load(worldmap)$
(%i2) draw3d(geomap([America_coastlines,Eurasia_coastlines],
                    [cylindrical_projection,2,2,2,3,4]))$
```
[conic_projection,x,y,z,r,alpha]: re-projects spherical map boundaries on the cones of angle alpha, with axis passing through the poles of the globe of radius r centered at (x,y,z). Both the northern and southern cones are tangent to sphere.
```
(%i1) load(worldmap)$
(%i2) draw3d(geomap(World_coastlines,
                    [conic_projection,0,0,0,1,90]))$
```

See also http://riotorto.users.sf.net/gnuplot/geomap for more elaborated examples.

Category: Dynamical systems · Category: Share packages · Category: Package dynamics

54 drawdf

54.1 Introduction to drawdf

The function drawdf draws the direction field of a first-order Ordinary Differential Equation (ODE) or a system of two autonomous first-order ODE’s.

Since this is an additional package, in order to use it you must first load it with load("drawdf"). Drawdf is built upon the draw package, which requires Gnuplot 4.2.

To plot the direction field of a single ODE, the ODE must be written in the form:

       dy
       -- = F(x,y)
       dx

and the function F should be given as the argument for drawdf. If the independent and dependent variables are not x, and y, as in the equation above, then those two variables should be named explicitly in a list given as an argument to the drawdf command (see the examples).

To plot the direction field of a set of two autonomous ODE’s, they must be written in the form

       dx             dy
       -- = G(x,y)    -- = F(x,y) 
       dt             dt

and the argument for drawdf should be a list with the two functions G and F, in that order; namely, the first expression in the list will be taken to be the time derivative of the variable represented on the horizontal axis, and the second expression will be the time derivative of the variable represented on the vertical axis. Those two variables do not have to be x and y, but if they are not, then the second argument given to drawdf must be another list naming the two variables, first the one on the horizontal axis and then the one on the vertical axis.

If only one ODE is given, drawdf will implicitly admit x=t, and G(x,y)=1, transforming the non-autonomous equation into a system of two autonomous equations.

Category: Differential equations · Category: Plotting · Category: Share packages · Category: Package drawdf · Category: Package draw

54.2 Functions and Variables for drawdf

54.2.1 Functions

Function: drawdf
    drawdf (dydx, ...options and objects...)
    drawdf (dvdu, [u,v], ...options and objects...)
    drawdf (dvdu, [u,umin,umax], [v,vmin,vmax], ...options and objects...)
    drawdf ([dxdt,dydt], ...options and objects...)
    drawdf ([dudt,dvdt], [u,v], ...options and objects...)
    drawdf ([dudt,dvdt], [u,umin,umax], [v,vmin,vmax], ...options and objects...)

Function drawdf draws a 2D direction field with optional solution curves and other graphics using the draw package.

The first argument specifies the derivative(s), and must be either an expression or a list of two expressions. dydx, dxdt and dydt are expressions that depend on x and y. dvdu, dudt and dvdt are expressions that depend on u and v.

If the independent and dependent variables are not x and y, then their names must be specified immediately following the derivative(s), either as a list of two names [u,v], or as two lists of the form [u,umin,umax] and [v,vmin,vmax].

The remaining arguments are graphic options, graphic objects, or lists containing graphic options and objects, nested to arbitrary depth. The set of graphic options and objects supported by drawdf is a superset of those supported by draw2d and gr2d from the draw package.

The arguments are interpreted sequentially: graphic options affect all following graphic objects. Furthermore, graphic objects are drawn on the canvas in order specified, and may obscure graphics drawn earlier. Some graphic options affect the global appearance of the scene.

The additional graphic objects supported by drawdf include: solns_at, points_at, saddles_at, soln_at, point_at, and saddle_at.

The additional graphic options supported by drawdf include: field_degree, soln_arrows, field_arrows, field_grid, field_color, show_field, tstep, nsteps, duration, direction, field_tstep, field_nsteps, and field_duration.

Commonly used graphic objects inherited from the draw package include: explicit, implicit, parametric, polygon, points, vector, label, and all others supported by draw2d and gr2d.

Commonly used graphic options inherited from the draw package include:
points_joined, color, point_type, point_size, line_width, line_type, key, title, xlabel, ylabel, user_preamble, terminal, dimensions, file_name, and all others supported by draw2d and gr2d.

55 dynamics

55.1 The dynamics package

Package dynamics includes functions for 3D visualization, animations, graphical analysis of differential and difference equations and numerical solution of differential equations. The functions for differential equations are described in the section on Numerical Methods and the functions to plot the Mandelbrot and Julia sets are described in the section on Plotting.

All the functions in this package will be loaded automatically the first time they are used.

55.2 Graphical analysis of discrete dynamical systems

Function: chaosgame ([[x1, y1]…[xm, ym]], [x0, y0], b, n, options, …);

Implements the so-called chaos game: the initial point (x0, y0) is plotted and then one of the m points [x1, y1]…xm, ym] will be selected at random. The next point plotted will be on the segment from the previous point plotted to the point chosen randomly, at a distance from the random point which will be b times that segment’s length. The procedure is repeated n times. The options are the same as for plot2d.

Example. A plot of Sierpinsky’s triangle:

(%i1) chaosgame([[0, 0], [1, 0], [0.5, sqrt(3)/2]], [0.1, 0.1], 1/2,
                 30000, [style, dots]);

Function: evolution (F, y0, n, …, options, …);

Draws n+1 points in a two-dimensional graph, where the horizontal coordinates of the points are the integers 0, 1, 2, ..., n, and the vertical coordinates are the corresponding values y(n) of the sequence defined by the recurrence relation

        y(n+1) = F(y(n))

With initial value y(0) equal to y0. F must be an expression that depends only on one variable (in the example, it depend on y, but any other variable can be used), y0 must be a real number and n must be a positive integer. This function accepts the same options as plot2d.

Example.

(%i1) evolution(cos(y), 2, 11);

Function: evolution2d ([F, G], [u, v], [u0, y0], n, options, …);

Shows, in a two-dimensional plot, the first n+1 points in the sequence of points defined by the two-dimensional discrete dynamical system with recurrence relations

        u(n+1) = F(u(n), v(n))    v(n+1) = G(u(n), v(n))

With initial values u0 and v0. F and G must be two expressions that depend only on two variables, u and v, which must be named explicitly in a list. The options are the same as for plot2d.

Example. Evolution of a two-dimensional discrete dynamical system:

(%i1) f: 0.6*x*(1+2*x)+0.8*y*(x-1)-y^2-0.9$
(%i2) g: 0.1*x*(1-6*x+4*y)+0.1*y*(1+9*y)-0.4$
(%i3) evolution2d([f,g], [x,y], [-0.5,0], 50000, [style,dots]);

And an enlargement of a small region in that fractal:

(%i9) evolution2d([f,g], [x,y], [-0.5,0], 300000, [x,-0.8,-0.6],
                  [y,-0.4,-0.2], [style, dots]);

Function: ifs ([r1, …, rm], [A1,…, Am], [[x1, y1], …, [xm, ym]], [x0, y0], n, options, …);

Implements the Iterated Function System method. This method is similar to the method described in the function chaosgame. but instead of shrinking the segment from the current point to the randomly chosen point, the 2 components of that segment will be multiplied by the 2 by 2 matrix Ai that corresponds to the point chosen randomly.

The random choice of one of the m attractive points can be made with a non-uniform probability distribution defined by the weights r1,...,rm. Those weights are given in cumulative form; for instance if there are 3 points with probabilities 0.2, 0.5 and 0.3, the weights r1, r2 and r3 could be 2, 7 and 10. The options are the same as for plot2d.

Example. Barnsley’s fern, obtained with 4 matrices and 4 points:

(%i1) a1: matrix([0.85,0.04],[-0.04,0.85])$
(%i2) a2: matrix([0.2,-0.26],[0.23,0.22])$
(%i3) a3: matrix([-0.15,0.28],[0.26,0.24])$
(%i4) a4: matrix([0,0],[0,0.16])$
(%i5) p1: [0,1.6]$
(%i6) p2: [0,1.6]$
(%i7) p3: [0,0.44]$
(%i8) p4: [0,0]$
(%i9) w: [85,92,99,100]$
(%i10) ifs(w, [a1,a2,a3,a4], [p1,p2,p3,p4], [5,0], 50000, [style,dots]);

Function: orbits (F, y0, n1, n2, [x, x0, xf, xstep], options, …);

Draws the orbits diagram for a family of one-dimensional discrete dynamical systems, with one parameter x; that kind of diagram is used to study the bifurcations of a one-dimensional discrete system.

The function F(y) defines a sequence with a starting value of y0, as in the case of the function evolution, but in this case that function will also depend on a parameter x that will take values in the interval from x0 to xf with increments of xstep. Each value used for the parameter x is shown on the horizontal axis. The vertical axis will show the n2 values of the sequence y(n1+1),..., y(n1+n2+1) obtained after letting the sequence evolve n1 iterations. In addition to the options accepted by plot2d, it accepts an option pixels that sets up the maximum number of different points that will be represented in the vertical direction.

Example. Orbits diagram of the quadratic map, with a parameter a:

(%i1) orbits(x^2+a, 0, 50, 200, [a, -2, 0.25], [style, dots]);

To enlarge the region around the lower bifurcation near x = -1.25 use:

(%i2) orbits(x^2+a, 0, 100, 400, [a,-1,-1.53], [x,-1.6,-0.8],
             [nticks, 400], [style,dots]);

Function: staircase (F, y0, n,options,…);

Draws a staircase diagram for the sequence defined by the recurrence relation

        y(n+1) = F(y(n))

The interpretation and allowed values of the input parameters is the same as for the function evolution. A staircase diagram consists of a plot of the function F(y), together with the line G(y) = y. A vertical segment is drawn from the point (y0, y0) on that line until the point where it intersects the function F. From that point a horizontal segment is drawn until it reaches the point (y1, y1) on the line, and the procedure is repeated n times until the point (yn, yn) is reached. The options are the same as for plot2d.

Example.

(%i1) staircase(cos(y), 1, 11, [y, 0, 1.2]);

55.3 Visualization with VTK

Function scene creates 3D images and animations using the Visualization ToolKit (VTK) software. In order to use that function, Xmaxima and VTK should be installed in your system (including the TCL bindings of VTK, which in some system might come in a separate package).

Function: scene (objects, …, options, …);

Accepts an empty list or a list of several objects and options. The program launches Xmaxima, which opens an external window representing the given objects in a 3-dimensional space and applying the options given. Each object must belong to one of the following 4 classes: sphere, cube, cylinder or cone (see Scene objects). Objects are identified by giving their name or by a list in which the first element is the class name and the following elements are options for that object.

Example. A hexagonal pyramid with a blue background:

(%i1) scene(cone, [background,"#9980e5"])$

By holding down the left button of the mouse while it is moved on the graphics window, the camera can be rotated showing different views of the pyramid. The two plot options elevation and azimuth can also be used to change the initial orientation of the viewing camera. The camera can be moved by holding the middle mouse button while moving it and holding the right-side mouse button while moving it up or down will zoom in or out.

Each object option should be a list starting with the option name, followed by its value. The list of allowed options can be found in the Scene object's options section.

Example. This will show a sphere falling to the ground and bouncing off without losing any energy. To start or pause the animation, press the play/pause button.

(%i1) p: makelist ([0,0,2.1- 9.8*t^2/2], t, 0, 0.64, 0.01)$

(%i2) p: append (p, reverse(p))$

(%i3) ball: [sphere, [radius,0.1], [thetaresolution,20],
  [phiresolution,20], [position,0,0,2.1], [color,red],
  [animate,position,p]]$

(%i4) ground: [cube, [xlength,2], [ylength,2], [zlength,0.2],
  [position,0,0,-0.1],[color,violet]]$

(%i5) scene (ball, ground, restart)$

The restart option was used to make the animation restart automatically every time the last point in the position list is reached. The accepted values for the colors are the same as for the color option of plot2d.

55.3.1 Scene options

Scene option: azimuth [azimuth, angle]

Default value: 135

The rotation of the camera on the horizontal (x, y) plane. angle must be a real number; an angle of 0 means that the camera points in the direction of the y axis and the x axis will appear on the right.

Scene option: background [background, color]

Default value: black

The color of the graphics window’s background. It accepts color names or hexadecimal red-green-blue strings (see the color option of plot2d).

Scene option: elevation [elevation, angle]

Default value: 30

The vertical rotation of the camera. The angle must be a real number; an angle of 0 means that the camera points on the horizontal, and the default angle of 30 means that the camera is pointing 30 degrees down from the horizontal.

Scene option: height [height, pixels]

Default value: 500

The height, in pixels, of the graphics window. pixels must be a positive integer number.

Scene option: restart [restart, value]

Default value: false

A true value means that animations will restart automatically when the end of the list is reached. Writing just “restart” is equivalent to [restart, true].

Scene option: tstep [tstep, time]

Default value: 10

The amount of time, in mili-seconds, between iterations among consecutive animation frames. time must be a real number.

Scene option: width [width, pixels]

Default value: 500

The width, in pixels, of the graphics window. pixels must be a positive integer number.

Scene option: windowname [windowtitle, name]

Default value: .scene

name must be a string that can be used as the name of the Tk window created by Xmaxima for the scene graphics. The default value .scene implies that a new top level window will be created.

Scene option: windowtitle [windowtitle, name]

Default value: Xmaxima: scene

name must be a string that will be written in the title of the window created by scene.

55.3.2 Scene objects

Scene object: cone [cone, options]

Creates a regular pyramid with height equal to 1 and a hexagonal base with vertices 0.5 units away from the axis. Options height and radius can be used to change those defaults and option resolution can be used to change the number of edges of the base; higher values will make it look like a cone. By default, the axis will be along the x axis, the middle point of the axis will be at the origin and the vertex on the positive side of the x axis; use options orientation and center to change those defaults.

Example. This shows a pyramid that starts rotating around the z axis when the play button is pressed.

(%i1) scene([cone, [orientation,0,30,0], [tstep,100],
   [animate,orientation,makelist([0,30,i],i,5,360,5)]], restart)$

Scene object: cube [cube, options]

A cube with edges of 1 unit and faces parallel to the xy, xz and yz planes. The lengths of the three edges can be changed with options xlength, ylength and zlength, turning it into a rectangular box and the faces can be rotated with option orientation.

Scene object: cylinder [cylinder, options]

Creates a regular prism with height equal to 1 and a hexagonal base with vertices 0.5 units away from the axis. Options height and radius can be used to change those defaults and option resolution can be used to change the number of edges of the base; higher values will make it look like a cylinder. The default height can be changed with the option height. By default, the axis will be along the x axis and the middle point of the axis will be at the origin; use options orientation and center to change those defaults.

Scene object: sphere [sphere, options]

A sphere with default radius of 0.5 units and center at the origin.

Category: Physical units · Category: Share packages · Category: Package ezunits

55.3.3 Scene object’s options

Object option: animation [animation, property, positions]

property should be one of the following 4 object’s properties: origin, scale, position or orientation and positions should be a list of points. When the play button is pressed, the object property will be changed sequentially through all the values in the list, at intervals of time given by the option tstep. The rewind button can be used to point at the start of the sequence making the animation restart after the play button is pressed again.

56 engineering-format

Engineering-format changes the way maxima outputs floating-point numbers to the notation engineers are used to: a*10^b with b dividable by three.

56.1 Functions and Variables for engineering-format

Option variable: engineering_format_floats

Default value: true

This variable allows to temporarily switch off engineering-format.

(%i1) load("engineering-format");
(%o1) /home/gunter/src/maxima-code/share/contrib/engineering-for\
mat.lisp

(%i2) float(sin(10)/10000);
(%o2)                - 54.40211108893698e-6

(%i3) engineering_format_floats:false$

(%i4) float(sin(10)/10000);
(%o4)                - 5.440211108893698e-5

56.2 Known Bugs

The output routine of SBCL 1.3.0 has a bug that sometimes causes the exponent not to be dividable by three. The value of the displayed number is still valid in this case.

57 ezunits

57.1 Introduction to ezunits

ezunits is a package for working with dimensional quantities, including some functions for dimensional analysis. ezunits can carry out arithmetic operations on dimensional quantities and unit conversions. The built-in units include Systeme Internationale (SI) and US customary units, and other units can be declared. See also physical_constants, a collection of physical constants.

load("ezunits") loads this package. demo("ezunits") displays several examples. The convenience function known_units returns a list of the built-in and user-declared units, while display_known_unit_conversions displays the set of known conversions in an easy-to-read format.

An expression a ` b represents a dimensional quantity, with a indicating a nondimensional quantity and b indicating the dimensional units. A symbol can be used as a unit without declaring it as such; unit symbols need not have any special properties. The quantity and unit of an expression a ` b can be extracted by the qty and units functions, respectively.

A symbol may be declared to be a dimensional quantity, with specified quantity or specified units or both.

An expression a ` b `` c converts from unit b to unit c. ezunits has built-in conversions for SI base units, SI derived units, and some non-SI units. Unit conversions not already known to ezunits can be declared. The unit conversions known to ezunits are specified by the global variable known_unit_conversions, which comprises built-in and user-defined conversions. Conversions for products, quotients, and powers of units are derived from the set of known unit conversions.

As Maxima generally prefers exact numbers (integers or rationals) to inexact (float or bigfloat), so ezunits preserves exact numbers when they appear in dimensional quantities. All built-in unit conversions are expressed in terms of exact numbers; inexact numbers in declared conversions are coerced to exact.

There is no preferred system for display of units; input units are not converted to other units unless conversion is explicitly indicated. ezunits recognizes the prefixes m-, k-, M, and G- (for milli-, kilo-, mega-, and giga-) as applied to SI base units and SI derived units, but such prefixes are applied only when indicated by an explicit conversion.

Arithmetic operations on dimensional quantities are carried out by conventional rules for such operations.

(x ` a) * (y ` b) is equal to (x * y) ` (a * b).
(x ` a) + (y ` a) is equal to (x + y) ` a.
(x ` a)^y is equal to x^y ` a^y when y is nondimensional.

ezunits does not require that units in a sum have the same dimensions; such terms are not added together, and no error is reported.

ezunits includes functions for elementary dimensional analysis, namely the fundamental dimensions and fundamental units of a dimensional quantity, and computation of dimensionless quantities and natural units. The functions for dimensional analysis were adapted from similar functions in another package, written by Barton Willis.

For the purpose of dimensional analysis, a list of fundamental dimensions and an associated list of fundamental units are maintained; by default the fundamental dimensions are length, mass, time, charge, temperature, and quantity, and the fundamental units are the associated SI units, but other fundamental dimensions and units can be declared.

57.2 Introduction to physical_constants

physical_constants is a collection of physical constants, copied from CODATA 2006 recommended values (http://physics.nist.gov/constants). load ("physical_constants") loads this package, and loads ezunits also, if it is not already loaded.

A physical constant is represented as a symbol which has a property which is the constant value. The constant value is a dimensional quantity, as represented by ezunits. The function constvalue fetches the constant value; the constant value is not the ordinary value of the symbol, so symbols of physical constants persist in evaluated expressions until their values are fetched by constvalue.

physical_constants includes some auxiliary information, namely, a description string for each constant, an estimate of the error of its numerical value, and a property for TeX display. To identify physical constants, each symbol has the physical_constant property; propvars(physical_constant) therefore shows the list of all such symbols.

physical_constants comprises the following constants.

%c: speed of light in vacuum
%mu_0: magnetic constant
%e_0: electric constant
%Z_0: characteristic impedance of vacuum
%G: Newtonian constant of gravitation
%h: Planck constant
%h_bar: Planck constant
%m_P: Planck mass
%T_P: Planck temperature
%l_P: Planck length
%t_P: Planck time
%%e: elementary charge
%Phi_0: magnetic flux quantum
%G_0: conductance quantum
%K_J: Josephson constant
%R_K: von Klitzing constant
%mu_B: Bohr magneton
%mu_N: nuclear magneton
%alpha: fine-structure constant
%R_inf: Rydberg constant
%a_0: Bohr radius
%E_h: Hartree energy
%ratio_h_me: quantum of circulation
%m_e: electron mass
%N_A: Avogadro constant
%m_u: atomic mass constant
%F: Faraday constant
%R: molar gas constant
%%k: Boltzmann constant
%V_m: molar volume of ideal gas
%n_0: Loschmidt constant
%ratio_S0_R: Sackur-Tetrode constant (absolute entropy constant)
%sigma: Stefan-Boltzmann constant
%c_1: first radiation constant
%c_1L: first radiation constant for spectral radiance
%c_2: second radiation constant
%b: Wien displacement law constant
%b_prime: Wien displacement law constant

Reference: http://physics.nist.gov/constants

Examples:

The list of all symbols which have the physical_constant property.

(%i1) load ("physical_constants")$
(%i2) propvars (physical_constant);
(%o2) [%c, %mu_0, %e_0, %Z_0, %G, %h, %h_bar, %m_P, %T_P, %l_P, 
%t_P, %%e, %Phi_0, %G_0, %K_J, %R_K, %mu_B, %mu_N, %alpha, 
%R_inf, %a_0, %E_h, %ratio_h_me, %m_e, %N_A, %m_u, %F, %R, %%k, 
%V_m, %n_0, %ratio_S0_R, %sigma, %c_1, %c_1L, %c_2, %b, %b_prime]

Properties of the physical constant %c.

(%i1) load ("physical_constants")$
(%i2) constantp (%c);
(%o2)                         true
(%i3) get (%c, description);
(%o3)               speed of light in vacuum
(%i4) constvalue (%c);
                                      m
(%o4)                     299792458 ` -
                                      s
(%i5) get (%c, RSU);
(%o5)                           0
(%i6) tex (%c);
$$c$$
(%o6)                         false

The energy equivalent of 1 pound-mass. The symbol %c persists until its value is fetched by constvalue.

(%i1) load ("physical_constants")$
(%i2) m * %c^2;
                                2
(%o2)                         %c  m
(%i3) %, m = 1 ` lbm;
                              2
(%o3)                       %c  ` lbm
(%i4) constvalue (%);
                                            2
                                       lbm m
(%o4)              89875517873681764 ` ------
                                          2
                                         s
(%i5) E : % `` J;
Computing conversions to base units; may take a moment. 
                     366838848464007200
(%o5)                ------------------ ` J
                             9
(%i6) E `` GJ;
                      458548560580009
(%o6)                 --------------- ` GJ
                         11250000
(%i7) float (%);
(%o7)              4.0759872051556356e+7 ` GJ

Category: Physical units · Category: Share packages · Category: Package physical_constants

57.3 Functions and Variables for ezunits

Operator: `

The dimensional quantity operator. An expression a ` b represents a dimensional quantity, with a indicating a nondimensional quantity and b indicating the dimensional units. A symbol can be used as a unit without declaring it as such; unit symbols need not have any special properties. The quantity and unit of an expression a ` b can be extracted by the qty and units functions, respectively.

Arithmetic operations on dimensional quantities are carried out by conventional rules for such operations.

(x ` a) * (y ` b) is equal to (x * y) ` (a * b).
(x ` a) + (y ` a) is equal to (x + y) ` a.
(x ` a)^y is equal to x^y ` a^y when y is nondimensional.

ezunits does not require that units in a sum have the same dimensions; such terms are not added together, and no error is reported.

load ("ezunits") enables this operator.

Examples:

SI (Systeme Internationale) units.

(%i1) load ("ezunits")$
(%i2) foo : 10 ` m;
(%o2)                        10 ` m
(%i3) qty (foo);
(%o3)                          10
(%i4) units (foo);
(%o4)                           m
(%i5) dimensions (foo);
(%o5)                        length

"Customary" units.

(%i1) load ("ezunits")$
(%i2) bar : x ` acre;
(%o2)                       x ` acre
(%i3) dimensions (bar);
                                   2
(%o3)                        length
(%i4) fundamental_units (bar);
                                2
(%o4)                          m

Units ad hoc.

(%i1) load ("ezunits")$
(%i2) baz : 3 ` sheep + 8 ` goat + 1 ` horse;
(%o2)           8 ` goat + 3 ` sheep + 1 ` horse
(%i3) subst ([sheep = 3*goat, horse = 10*goat], baz);
(%o3)                       27 ` goat
(%i4) baz2 : 1000`gallon/fortnight;
                                gallon
(%o4)                   1000 ` ---------
                               fortnight
(%i5) subst (fortnight = 14*day, baz2);
                          500   gallon
(%o5)                     --- ` ------
                           7     day

Arithmetic operations on dimensional quantities.

(%i1) load ("ezunits")$
(%i2) 100 ` kg + 200 ` kg;
(%o2)                       300 ` kg
(%i3) 100 ` m^3 - 100 ` m^3;
                                  3
(%o3)                        0 ` m
(%i4) (10 ` kg) * (17 ` m/s^2);
                                 kg m
(%o4)                      170 ` ----
                                   2
                                  s
(%i5) (x ` m) / (y ` s);
                              x   m
(%o5)                         - ` -
                              y   s
(%i6) (a ` m)^2;
                              2    2
(%o6)                        a  ` m

Operator: ``

The unit conversion operator. An expression a ` b `` c converts from unit b to unit c. ezunits has built-in conversions for SI base units, SI derived units, and some non-SI units. Unit conversions not already known to ezunits can be declared. The unit conversions known to ezunits are specified by the global variable known_unit_conversions, which comprises built-in and user-defined conversions. Conversions for products, quotients, and powers of units are derived from the set of known unit conversions.

There is no preferred system for display of units; input units are not converted to other units unless conversion is explicitly indicated. ezunits does not attempt to simplify units by prefixes (milli-, centi-, deci-, etc) unless such conversion is explicitly indicated.

load ("ezunits") enables this operator.

Examples:

The set of known unit conversions.

(%i1) load ("ezunits")$
(%i2) display2d : false$
(%i3) known_unit_conversions;
(%o3) {acre = 4840*yard^2,Btu = 1055*J,cfm = feet^3/minute,
       cm = m/100,day = 86400*s,feet = 381*m/1250,ft = feet,
       g = kg/1000,gallon = 757*l/200,GHz = 1000000000*Hz,
       GOhm = 1000000000*Ohm,GPa = 1000000000*Pa,
       GWb = 1000000000*Wb,Gg = 1000000*kg,Gm = 1000000000*m,
       Gmol = 1000000*mol,Gs = 1000000000*s,ha = hectare,
       hectare = 100*m^2,hour = 3600*s,Hz = 1/s,inch = feet/12,
       km = 1000*m,kmol = 1000*mol,ks = 1000*s,l = liter,
       lbf = pound_force,lbm = pound_mass,liter = m^3/1000,
       metric_ton = Mg,mg = kg/1000000,MHz = 1000000*Hz,
       microgram = kg/1000000000,micrometer = m/1000000,
       micron = micrometer,microsecond = s/1000000,
       mile = 5280*feet,minute = 60*s,mm = m/1000,
       mmol = mol/1000,month = 2629800*s,MOhm = 1000000*Ohm,
       MPa = 1000000*Pa,ms = s/1000,MWb = 1000000*Wb,
       Mg = 1000*kg,Mm = 1000000*m,Mmol = 1000000000*mol,
       Ms = 1000000*s,ns = s/1000000000,ounce = pound_mass/16,
       oz = ounce,Ohm = s*J/C^2,
       pound_force = 32*ft*pound_mass/s^2,
       pound_mass = 200*kg/441,psi = pound_force/inch^2,
       Pa = N/m^2,week = 604800*s,Wb = J/A,yard = 3*feet,
       year = 31557600*s,C = s*A,F = C^2/J,GA = 1000000000*A,
       GC = 1000000000*C,GF = 1000000000*F,GH = 1000000000*H,
       GJ = 1000000000*J,GK = 1000000000*K,GN = 1000000000*N,
       GS = 1000000000*S,GT = 1000000000*T,GV = 1000000000*V,
       GW = 1000000000*W,H = J/A^2,J = m*N,kA = 1000*A,
       kC = 1000*C,kF = 1000*F,kH = 1000*H,kHz = 1000*Hz,
       kJ = 1000*J,kK = 1000*K,kN = 1000*N,kOhm = 1000*Ohm,
       kPa = 1000*Pa,kS = 1000*S,kT = 1000*T,kV = 1000*V,
       kW = 1000*W,kWb = 1000*Wb,mA = A/1000,mC = C/1000,
       mF = F/1000,mH = H/1000,mHz = Hz/1000,mJ = J/1000,
       mK = K/1000,mN = N/1000,mOhm = Ohm/1000,mPa = Pa/1000,
       mS = S/1000,mT = T/1000,mV = V/1000,mW = W/1000,
       mWb = Wb/1000,MA = 1000000*A,MC = 1000000*C,
       MF = 1000000*F,MH = 1000000*H,MJ = 1000000*J,
       MK = 1000000*K,MN = 1000000*N,MS = 1000000*S,
       MT = 1000000*T,MV = 1000000*V,MW = 1000000*W,
       N = kg*m/s^2,R = 5*K/9,S = 1/Ohm,T = J/(m^2*A),V = J/C,
       W = J/s}

Elementary unit conversions.

(%i1) load ("ezunits")$
(%i2) 1 ` ft `` m;
Computing conversions to base units; may take a moment. 
                            381
(%o2)                       ---- ` m
                            1250
(%i3) %, numer;
(%o3)                      0.3048 ` m
(%i4) 1 ` kg `` lbm;
                            441
(%o4)                       --- ` lbm
                            200
(%i5) %, numer;
(%o5)                      2.205 ` lbm
(%i6) 1 ` W `` Btu/hour;
                           720   Btu
(%o6)                      --- ` ----
                           211   hour
(%i7) %, numer;
                                        Btu
(%o7)               3.412322274881517 ` ----
                                        hour
(%i8) 100 ` degC `` degF;
(%o8)                      212 ` degF
(%i9) -40 ` degF `` degC;
(%o9)                     (- 40) ` degC
(%i10) 1 ` acre*ft `` m^3;
                        60228605349    3
(%o10)                  ----------- ` m
                         48828125
(%i11) %, numer;
                                          3
(%o11)                1233.48183754752 ` m

Coercing quantities in feet and meters to one or the other.

(%i1) load ("ezunits")$
(%i2) 100 ` m + 100 ` ft;
(%o2)                  100 ` m + 100 ` ft
(%i3) (100 ` m + 100 ` ft) `` ft;
Computing conversions to base units; may take a moment. 
                           163100
(%o3)                      ------ ` ft
                            381
(%i4) %, numer;
(%o4)                428.0839895013123 ` ft
(%i5) (100 ` m + 100 ` ft) `` m;
                            3262
(%o5)                       ---- ` m
                             25
(%i6) %, numer;
(%o6)                      130.48 ` m

Dimensional analysis to find fundamental dimensions and fundamental units.

(%i1) load ("ezunits")$
(%i2) foo : 1 ` acre * ft;
(%o2)                      1 ` acre ft
(%i3) dimensions (foo);
                                   3
(%o3)                        length
(%i4) fundamental_units (foo);
                                3
(%o4)                          m
(%i5) foo `` m^3;
Computing conversions to base units; may take a moment. 
                        60228605349    3
(%o5)                   ----------- ` m
                         48828125
(%i6) %, numer;
                                          3
(%o6)                 1233.48183754752 ` m

Declared unit conversions.

(%i1) load ("ezunits")$
(%i2) declare_unit_conversion (MMBtu = 10^6*Btu, kW = 1000*W);
(%o2)                         done
(%i3) declare_unit_conversion (kWh = kW*hour, MWh = 1000*kWh,
                               bell = 1800*s);
(%o3)                         done
(%i4) 1 ` kW*s `` MWh;
Computing conversions to base units; may take a moment. 
                             1
(%o4)                     ------- ` MWh
                          3600000
(%i5) 1 ` kW/m^2 `` MMBtu/bell/ft^2;
                       1306449      MMBtu
(%o5)                 ---------- ` --------
                      8242187500          2
                                   bell ft

Function: constvalue (x)

Shows the value and the units of one of the constants declared by package physical_constants, which includes a list of physical constants, or of a new constant declared in package ezunits (see declare_constvalue).

Note that constant values as recognized by constvalue are separate from values declared by numerval and recognized by constantp.

Example:

(%i1) load ("physical_constants")$
(%i2) constvalue (%G);
                                     3
                                    m
(%o2)                    6.67428 ` -----
                                       2
                                   kg s
(%i3) get ('%G, 'description);
(%o3)           Newtonian constant of gravitation

Function: declare_constvalue (a, x)

Declares the value of a constant to be used in package ezunits. This function should be loaded with load ("ezunits").

Example:

(%i1) load ("ezunits")$
(%i2) declare_constvalue (FOO, 100 ` lbm / acre);
                                 lbm
(%o2)                      100 ` ----
                                 acre
(%i3) FOO * (50 ` acre);
(%o3)                     50 FOO ` acre
(%i4) constvalue (%);
(%o4)                      5000 ` lbm

Function: remove_constvalue (a)

Reverts the effect of declare_constvalue. This function should be loaded with load ("ezunits").

Function: units (x)

Returns the units of a dimensional quantity x, or returns 1 if x is nondimensional.

x may be a literal dimensional expression a ` b, a symbol with declared units via declare_units, or an expression containing either or both of those.

This function should be loaded with load ("ezunits").

Example:

(%i1) load ("ezunits")$
(%i2) foo : 100 ` kg;
(%o2)                       100 ` kg
(%i3) bar : x ` m/s;
                                  m
(%o3)                         x ` -
                                  s
(%i4) units (foo);
(%o4)                          kg
(%i5) units (bar);
                                m
(%o5)                           -
                                s
(%i6) units (foo * bar);
                              kg m
(%o6)                         ----
                               s
(%i7) units (foo / bar);
                              kg s
(%o7)                         ----
                               m
(%i8) units (foo^2);
                                 2
(%o8)                          kg

Function: declare_units (a, u)

Declares that units should return units u for a, where u is an expression. This function should be loaded with load ("ezunits").

Example:

(%i1) load ("ezunits")$
(%i2) units (aa);
(%o2)                           1
(%i3) declare_units (aa, J);
(%o3)                           J
(%i4) units (aa);
(%o4)                           J
(%i5) units (aa^2);
                                2
(%o5)                          J
(%i6) foo : 100 ` kg;
(%o6)                       100 ` kg
(%i7) units (aa * foo);
(%o7)                         kg J

Function: qty (x)

Returns the nondimensional part of a dimensional quantity x, or returns x if x is nondimensional. x may be a literal dimensional expression a ` b, a symbol with declared quantity, or an expression containing either or both of those.

This function should be loaded with load ("ezunits").

Example:

(%i1) load ("ezunits")$
(%i2) foo : 100 ` kg;
(%o2)                       100 ` kg
(%i3) qty (foo);
(%o3)                          100
(%i4) bar : v ` m/s;
                                  m
(%o4)                         v ` -
                                  s
(%i5) foo * bar;
                                  kg m
(%o5)                     100 v ` ----
                                   s
(%i6) qty (foo * bar);
(%o6)                         100 v

Function: declare_qty (a, x)

Declares that qty should return x for symbol a, where x is a nondimensional quantity. This function should be loaded with load ("ezunits").

Example:

(%i1) load ("ezunits")$
(%i2) declare_qty (aa, xx);
(%o2)                          xx
(%i3) qty (aa);
(%o3)                          xx
(%i4) qty (aa^2);
                                 2
(%o4)                          xx
(%i5) foo : 100 ` kg;
(%o5)                       100 ` kg
(%i6) qty (aa * foo);
(%o6)                        100 xx

Function: unitp (x)

Returns true if x is a literal dimensional expression, a symbol declared dimensional, or an expression in which the main operator is declared dimensional. unitp returns false otherwise.

load ("ezunits") loads this function.

Examples:

unitp applied to a literal dimensional expression.

(%i1) load ("ezunits")$
(%i2) unitp (100 ` kg);
(%o2)                         true

unitp applied to a symbol declared dimensional.

(%i1) load ("ezunits")$
(%i2) unitp (foo);
(%o2)                         false
(%i3) declare (foo, dimensional);
(%o3)                         done
(%i4) unitp (foo);
(%o4)                         true

unitp applied to an expression in which the main operator is declared dimensional.

(%i1) load ("ezunits")$
(%i2) unitp (bar (x, y, z));
(%o2)                         false
(%i3) declare (bar, dimensional);
(%o3)                         done
(%i4) unitp (bar (x, y, z));
(%o4)                         true

Function: declare_unit_conversion (u = v, ...)

Appends equations u = v, ... to the list of unit conversions known to the unit conversion operator ``. u and v are both multiplicative terms, in which any variables are units, or both literal dimensional expressions.

At present, it is necessary to express conversions such that the left-hand side of each equation is a simple unit (not a multiplicative expression) or a literal dimensional expression with the quantity equal to 1 and the unit being a simple unit. This limitation might be relaxed in future versions.

known_unit_conversions is the list of known unit conversions.

This function should be loaded with load ("ezunits").

Examples:

Unit conversions expressed by equations of multiplicative terms.

(%i1) load ("ezunits")$
(%i2) declare_unit_conversion (nautical_mile = 1852 * m,
                               fortnight = 14 * day);
(%o2)                         done
(%i3) 100 ` nautical_mile / fortnight `` m/s;
Computing conversions to base units; may take a moment. 
                            463    m
(%o3)                       ---- ` -
                            3024   s

Unit conversions expressed by equations of literal dimensional expressions.

(%i1) load ("ezunits")$
(%i2) declare_unit_conversion (1 ` fluid_ounce = 2 ` tablespoon);
(%o2)                         done
(%i3) declare_unit_conversion (1 ` tablespoon = 3 ` teaspoon);
(%o3)                         done
(%i4) 15 ` fluid_ounce `` teaspoon;
Computing conversions to base units; may take a moment. 
(%o4)                     90 ` teaspoon

Function: declare_dimensions (a_1, d_1, ..., a_n, d_n)

Declares a_1, ..., a_n to have dimensions d_1, ..., d_n, respectively.

Each a_k is a symbol or a list of symbols. If it is a list, then every symbol in a_k is declared to have dimension d_k.

load ("ezunits") loads these functions.

Examples:

(%i1) load ("ezunits") $
(%i2) declare_dimensions ([x, y, z], length, [t, u], time);
(%o2)                         done
(%i3) dimensions (y^2/u);
                                   2
                             length
(%o3)                        -------
                              time
(%i4) fundamental_units (y^2/u);
0 errors, 0 warnings
                                2
                               m
(%o4)                          --
                               s

Function: remove_dimensions (a_1, ..., a_n)

Reverts the effect of declare_dimensions. This function should be loaded with load ("ezunits").

Function: declare_fundamental_dimensions (d_1, d_2, d_3, ...)

Function: remove_fundamental_dimensions (d_1, d_2, d_3, ...)

Global variable: fundamental_dimensions

declare_fundamental_dimensions declares fundamental dimensions. Symbols d_1, d_2, d_3, ... are appended to the list of fundamental dimensions, if they are not already on the list.

remove_fundamental_dimensions reverts the effect of declare_fundamental_dimensions.

fundamental_dimensions is the list of fundamental dimensions. By default, the list comprises several physical dimensions.

load ("ezunits") loads these functions.

Examples:

(%i1) load ("ezunits") $
(%i2) fundamental_dimensions;
(%o2) [length, mass, time, current, temperature, quantity]
(%i3) declare_fundamental_dimensions (money, cattle, happiness);
(%o3)                         done
(%i4) fundamental_dimensions;
(%o4) [length, mass, time, current, temperature, quantity, 
                                        money, cattle, happiness]
(%i5) remove_fundamental_dimensions (cattle, happiness);
(%o5)                         done
(%i6) fundamental_dimensions;
(%o6) [length, mass, time, current, temperature, quantity, money]

Function: declare_fundamental_units (u_1, d_1, ..., u_n, d_n)

Function: remove_fundamental_units (u_1, ..., u_n)

declare_fundamental_units declares u_1, ..., u_n to have dimensions d_1, ..., d_n, respectively. All arguments must be symbols.

After calling declare_fundamental_units, dimensions(u_k) returns d_k for each argument u_1, ..., u_n, and fundamental_units(d_k) returns u_k for each argument d_1, ..., d_n.

remove_fundamental_units reverts the effect of declare_fundamental_units.

load ("ezunits") loads these functions.

Examples:

(%i1) load ("ezunits") $
(%i2) declare_fundamental_dimensions (money, cattle, happiness);
(%o2)                         done
(%i3) declare_fundamental_units (dollar, money, goat, cattle,
                                 smile, happiness);
(%o3)                 [dollar, goat, smile]
(%i4) dimensions (100 ` dollar/goat/km^2);
                             money
(%o4)                    --------------
                                      2
                         cattle length
(%i5) dimensions (x ` smile/kg);
                            happiness
(%o5)                       ---------
                              mass
(%i6) fundamental_units (money*cattle/happiness);
0 errors, 0 warnings
                           dollar goat
(%o6)                      -----------
                              smile

Function: dimensions (x)

Function: dimensions_as_list (x)

dimensions returns the dimensions of the dimensional quantity x as an expression comprising products and powers of base dimensions.

dimensions_as_list returns the dimensions of the dimensional quantity x as a list, in which each element is an integer which indicates the power of the corresponding base dimension in the dimensions of x.

load ("ezunits") loads these functions.

Examples:

(%i1) load ("ezunits")$
(%i2) dimensions (1000 ` kg*m^2/s^3);
                                2
                          length  mass
(%o2)                     ------------
                                 3
                             time
(%i3) declare_units (foo, acre*ft/hour);
                             acre ft
(%o3)                        -------
                              hour
(%i4) dimensions (foo);
                                   3
                             length
(%o4)                        -------
                              time

(%i1) load ("ezunits")$
(%i2) fundamental_dimensions;
(%o2)  [length, mass, time, charge, temperature, quantity]
(%i3) dimensions_as_list (1000 ` kg*m^2/s^3);
(%o3)                 [2, 1, - 3, 0, 0, 0]
(%i4) declare_units (foo, acre*ft/hour);
                             acre ft
(%o4)                        -------
                              hour
(%i5) dimensions_as_list (foo);
(%o5)                 [3, 0, - 1, 0, 0, 0]

Function: fundamental_units
fundamental_units (x)
fundamental_units ()

fundamental_units(x) returns the units associated with the fundamental dimensions of x. as determined by dimensions(x).

x may be a literal dimensional expression a ` b, a symbol with declared units via declare_units, or an expression containing either or both of those.

fundamental_units() returns the list of all known fundamental units, as declared by declare_fundamental_units.

load ("ezunits") loads this function.

Examples:

(%i1) load ("ezunits")$
(%i2) fundamental_units ();
(%o2)                 [m, kg, s, A, K, mol]
(%i3) fundamental_units (100 ` mile/hour);
                                m
(%o3)                           -
                                s
(%i4) declare_units (aa, g/foot^2);
                                g
(%o4)                         -----
                                  2
                              foot
(%i5) fundamental_units (aa);
                               kg
(%o5)                          --
                                2
                               m

Function: dimensionless (L)

Returns a basis for the dimensionless quantities which can be formed from a list L of dimensional quantities.

load ("ezunits") loads this function.

Examples:

(%i1) load ("ezunits") $
(%i2) dimensionless ([x ` m, y ` m/s, z ` s]);
0 errors, 0 warnings
0 errors, 0 warnings
                               y z
(%o2)                         [---]
                                x

Dimensionless quantities derived from fundamental physical quantities. Note that the first element on the list is proportional to the fine-structure constant.

(%i1) load ("ezunits") $
(%i2) load ("physical_constants") $
(%i3) dimensionless([%h_bar, %m_e, %m_P, %%e, %c, %e_0]);
0 errors, 0 warnings
0 errors, 0 warnings
                              2
                           %%e        %m_e
(%o3)                [--------------, ----]
                      %c %e_0 %h_bar  %m_P

Function: natural_unit (expr, [v_1, ..., v_n])

Finds exponents e_1, ..., e_n such that dimension(expr) = dimension(v_1^e_1 ... v_n^e_n).

load ("ezunits") loads this function.

Examples:

Category: Share packages · Category: Package f90

58 f90

58.1 Package f90

Option variable: f90_output_line_length_max

Default value: 65

f90_output_line_length_max is the maximum number of characters of Fortran code which are output by f90 per line. Longer lines of code are divided, and printed with an ampersand & at the end of an output line and an ampersand at the beginning of the following line.

f90_output_line_length_max must be a positive integer.

Example:

(%i1) load ("f90")$
(%i2) foo : expand ((xxx + yyy + 7)^4);
         4            3         3        2    2             2
(%o2) yyy  + 4 xxx yyy  + 28 yyy  + 6 xxx  yyy  + 84 xxx yyy
          2        3             2
 + 294 yyy  + 4 xxx  yyy + 84 xxx  yyy + 588 xxx yyy + 1372 yyy
      4         3          2
 + xxx  + 28 xxx  + 294 xxx  + 1372 xxx + 2401
(%i3) f90_output_line_length_max;
(%o3)                          65
(%i4) f90 ('foo = foo);
foo = yyy**4+4*xxx*yyy**3+28*yyy**3+6*xxx**2*yyy**2+84*xxx*yyy**2&
&+294*yyy**2+4*xxx**3*yyy+84*xxx**2*yyy+588*xxx*yyy+1372*yyy+xxx**&
&4+28*xxx**3+294*xxx**2+1372*xxx+2401
(%o4)                         false
(%i5) f90_output_line_length_max : 40 $
(%i6) f90 ('foo = foo);
foo = yyy**4+4*xxx*yyy**3+28*yyy**3+6*xx&
&x**2*yyy**2+84*xxx*yyy**2+294*yyy**2+4*x&
&xx**3*yyy+84*xxx**2*yyy+588*xxx*yyy+1372&
&*yyy+xxx**4+28*xxx**3+294*xxx**2+1372*xx&
&x+2401
(%o6)                         false

Category: Global variables · Category: Translation and compilation · Category: Package f90

Function: f90 (expr_1, …, expr_n)

Prints one or more expressions expr_1, …, expr_n as a Fortran 90 program. Output is printed to the standard output.

f90 prints output in the so-called "free form" input format for Fortran 90: there is no special attention to column positions. Long lines are split at a fixed width with the ampersand & continuation character; the number of output characters per line, not including ampersands, is specified by f90_output_line_length_max. f90 outputs an ampersand at the end of a split line and another at the beginning of the next line.

load("f90") loads this function. See also the function fortran.

Examples:

(%i1) load ("f90")$
(%i2) foo : expand ((xxx + yyy + 7)^4);
         4            3         3        2    2             2
(%o2) yyy  + 4 xxx yyy  + 28 yyy  + 6 xxx  yyy  + 84 xxx yyy
          2        3             2
 + 294 yyy  + 4 xxx  yyy + 84 xxx  yyy + 588 xxx yyy + 1372 yyy
      4         3          2
 + xxx  + 28 xxx  + 294 xxx  + 1372 xxx + 2401
(%i3) f90 ('foo = foo);
foo = yyy**4+4*xxx*yyy**3+28*yyy**3+6*xxx**2*yyy**2+84*xxx*yyy**2&
&+294*yyy**2+4*xxx**3*yyy+84*xxx**2*yyy+588*xxx*yyy+1372*yyy+xxx**&
&4+28*xxx**3+294*xxx**2+1372*xxx+2401
(%o3)                         false

Multiple expressions. Capture standard output into a file via the with_stdout function.

(%i1) load ("f90")$
(%i2) foo : sin (3*x + 1) - cos (7*x - 2);
(%o2)              sin(3 x + 1) - cos(7 x - 2)
(%i3) with_stdout ("foo.f90",
                   f90 (x=0.25, y=0.625, 'foo=foo, 'stop, 'end));
(%o3)                         false
(%i4) printfile ("foo.f90");
x = 0.25
y = 0.625
foo = sin(3*x+1)-cos(7*x-2)
stop
end
(%o4)                        foo.f90

Category: Translation and compilation · Category: Package f90

59 finance

59.1 Introduction to finance

This is the Finance Package (Ver 0.1).

In all the functions, rate is the compound interest rate, num is the number of periods and must be positive and flow refers to cash flow so if you have an Output the flow is negative and positive for Inputs.

Note that before using the functions defined in this package, you have to load it writing load(finance)$.

Author: Nicolas Guarin Zapata.

59.2 Functions and Variables for finance

Function: days360 (year1,month1,day1,year2,month2,day2)

Calculates the distance between 2 dates, assuming 360 days years, 30 days months.

Example:

(%i1) load("finance")$
(%i2) days360(2008,12,16,2007,3,25);
(%o2)                      - 621

Function: fv (rate,PV,num)

We can calculate the future value of a Present one given a certain interest rate. rate is the interest rate, PV is the present value and num is the number of periods.

Example:

(%i1) load("finance")$
(%i2) fv(0.12,1000,3);
(%o2)                     1404.928

Function: pv (rate,FV,num)

We can calculate the present value of a Future one given a certain interest rate. rate is the interest rate, FV is the future value and num is the number of periods.

Example:

(%i1) load("finance")$
(%i2) pv(0.12,1000,3);
(%o2)                711.7802478134108

Function: graph_flow (val)

Plots the money flow in a time line, the positive values are in blue and upside; the negative ones are in red and downside. The direction of the flow is given by the sign of the value. val is a list of flow values.

Example:

(%i1) load("finance")$
(%i2) graph_flow([-5000,-3000,800,1300,1500,2000])$

Function: annuity_pv (rate,PV,num)

We can calculate the annuity knowing the present value (like an amount), it is a constant and periodic payment. rate is the interest rate, PV is the present value and num is the number of periods.

Example:

(%i1) load("finance")$
(%i2) annuity_pv(0.12,5000,10);
(%o2)                884.9208207992202

Function: annuity_fv (rate,FV,num)

We can calculate the annuity knowing the desired value (future value), it is a constant and periodic payment. rate is the interest rate, FV is the future value and num is the number of periods.

Example:

(%i1) load("finance")$
(%i2) annuity_fv(0.12,65000,10);
(%o2)                3703.970670389863

Function: geo_annuity_pv (rate,growing_rate,PV,num)

We can calculate the annuity knowing the present value (like an amount), in a growing periodic payment. rate is the interest rate, growing_rate is the growing rate, PV is the present value and num is the number of periods.

Example:

(%i1) load("finance")$
(%i2) geo_annuity_pv(0.14,0.05,5000,10);
(%o2)                802.6888176505123

Function: geo_annuity_fv (rate,growing_rate,FV,num)

We can calculate the annuity knowing the desired value (future value), in a growing periodic payment. rate is the interest rate, growing_rate is the growing rate, FV is the future value and num is the number of periods.

Example:

(%i1) load("finance")$
(%i2) geo_annuity_fv(0.14,0.05,5000,10);
(%o2)                216.5203395312695

Function: amortization (rate,amount,num)

Amortization table determined by a specific rate. rate is the interest rate, amount is the amount value, and num is the number of periods.

Example:

(%i1) load("finance")$
(%i2) amortization(0.05,56000,12)$
      "n"    "Balance"     "Interest"   "Amortization"  "Payment"      
     0.000     56000.000         0.000         0.000         0.000  
     1.000     52481.777      2800.000      3518.223      6318.223  
     2.000     48787.643      2624.089      3694.134      6318.223  
     3.000     44908.802      2439.382      3878.841      6318.223  
     4.000     40836.019      2245.440      4072.783      6318.223  
     5.000     36559.597      2041.801      4276.422      6318.223  
     6.000     32069.354      1827.980      4490.243      6318.223  
     7.000     27354.599      1603.468      4714.755      6318.223  
     8.000     22404.106      1367.730      4950.493      6318.223  
     9.000     17206.088      1120.205      5198.018      6318.223  
    10.000     11748.170       860.304      5457.919      6318.223  
    11.000      6017.355       587.408      5730.814      6318.223  
    12.000         0.000       300.868      6017.355      6318.223

Function: arit_amortization (rate,increment,amount,num)

The amortization table determined by a specific rate and with growing payment can be claculated by arit_amortization. Notice that the payment is not constant, it presents an arithmetic growing, increment is then the difference between two consecutive rows in the "Payment" column. rate is the interest rate, increment is the increment, amount is the amount value, and num is the number of periods.

Example:

(%i1) load("finance")$
(%i2) arit_amortization(0.05,1000,56000,12)$
      "n"    "Balance"     "Interest"   "Amortization"  "Payment"      
     0.000     56000.000         0.000         0.000         0.000  
     1.000     57403.679      2800.000     -1403.679      1396.321  
     2.000     57877.541      2870.184      -473.863      2396.321  
     3.000     57375.097      2893.877       502.444      3396.321  
     4.000     55847.530      2868.755      1527.567      4396.321  
     5.000     53243.586      2792.377      2603.945      5396.321  
     6.000     49509.443      2662.179      3734.142      6396.321  
     7.000     44588.594      2475.472      4920.849      7396.321  
     8.000     38421.703      2229.430      6166.892      8396.321  
     9.000     30946.466      1921.085      7475.236      9396.321  
    10.000     22097.468      1547.323      8848.998     10396.321  
    11.000     11806.020      1104.873     10291.448     11396.321  
    12.000        -0.000       590.301     11806.020     12396.321

Function: geo_amortization (rate,growing_rate,amount,num)

The amortization table determined by rate, amount, and number of periods can be found by geo_amortization. Notice that the payment is not constant, it presents a geometric growing, growing_rate is then the quotient between two consecutive rows in the "Payment" column. rate is the interest rate, amount is the amount value, and num is the number of periods.

Example:

(%i1) load("finance")$
(%i2) geo_amortization(0.05,0.03,56000,12)$
      "n"    "Balance"     "Interest"   "Amortization"  "Payment"      
     0.000     56000.000         0.000         0.000         0.000  
     1.000     53365.296      2800.000      2634.704      5434.704  
     2.000     50435.816      2668.265      2929.480      5597.745  
     3.000     47191.930      2521.791      3243.886      5765.677  
     4.000     43612.879      2359.596      3579.051      5938.648  
     5.000     39676.716      2180.644      3936.163      6116.807  
     6.000     35360.240      1983.836      4316.475      6300.311  
     7.000     30638.932      1768.012      4721.309      6489.321  
     8.000     25486.878      1531.947      5152.054      6684.000  
     9.000     19876.702      1274.344      5610.176      6884.520  
    10.000     13779.481       993.835      6097.221      7091.056  
    11.000      7164.668       688.974      6614.813      7303.787  
    12.000         0.000       358.233      7164.668      7522.901

Function: saving (rate,amount,num)

The table that represents the values in a constant and periodic saving can be found by saving. amount represents the desired quantity and num the number of periods to save.

Example:

(%i1) load("finance")$
(%i2) saving(0.15,12000,15)$
      "n"    "Balance"     "Interest"   "Payment"      
     0.000         0.000         0.000         0.000  
     1.000       252.205         0.000       252.205  
     2.000       542.240        37.831       252.205  
     3.000       875.781        81.336       252.205  
     4.000      1259.352       131.367       252.205  
     5.000      1700.460       188.903       252.205  
     6.000      2207.733       255.069       252.205  
     7.000      2791.098       331.160       252.205  
     8.000      3461.967       418.665       252.205  
     9.000      4233.467       519.295       252.205  
    10.000      5120.692       635.020       252.205  
    11.000      6141.000       768.104       252.205  
    12.000      7314.355       921.150       252.205  
    13.000      8663.713      1097.153       252.205  
    14.000     10215.474      1299.557       252.205  
    15.000     12000.000      1532.321       252.205

Function: npv (rate,val)

Calculates the present value of a value series to evaluate the viability in a project. val is a list of varying cash flows.

Example:

(%i1) load("finance")$
(%i2) npv(0.25,[100,500,323,124,300]);
(%o2)                714.4703999999999

Function: irr (val,IO)

IRR (Internal Rate of Return) is the value of rate which makes Net Present Value zero. flowValues is a list of varying cash flows, I0 is the initial investment.

Example:

(%i1) load("finance")$
(%i2) res:irr([-5000,0,800,1300,1500,2000],0)$
(%i3) rhs(res[1][1]);
(%o3)                .03009250374237132

Function: benefit_cost (rate,input,output)

Calculates the ratio Benefit/Cost. Benefit is the Net Present Value (NPV) of the inputs, and Cost is the Net Present Value (NPV) of the outputs. Notice that if there is not an input or output value in a specific period, the input/output would be a zero for that period. rate is the interest rate, input is a list of input values, and output is a list of output values.

Example:

(%i1) load("finance")$
(%i2) benefit_cost(0.24,[0,300,500,150],[100,320,0,180]);
(%o2)               1.427249324905784

60 fractals

60.1 Introduction to fractals

This package defines some well known fractals:

- with random IFS (Iterated Function System): the Sierpinsky triangle, a Tree and a Fern

- Complex Fractals: the Mandelbrot and Julia Sets

- the Koch snowflake sets

- Peano maps: the Sierpinski and Hilbert maps

Author: José Ramírez Labrador.

For questions, suggestions and bugs, please feel free to contact me at

pepe DOT ramirez AAATTT uca DOT es

60.2 Definitions for IFS fractals

Some fractals can be generated by iterative applications of contractive affine transformations in a random way; see

Hoggar S. G., "Mathematics for computer graphics", Cambridge University Press 1994.

We define a list with several contractive affine transformations, and we randomly select the transformation in a recursive way. The probability of the choice of a transformation must be related with the contraction ratio.

You can change the transformations and find another fractal

Function: sierpinskiale (n)

Sierpinski Triangle: 3 contractive maps; .5 contraction constant and translations; all maps have the same contraction ratio. Argument n must be great enougth, 10000 or greater.

Example:

(%i1) load("fractals")$
(%i2) n: 10000$
(%i3) plot2d([discrete,sierpinskiale(n)], [style,dots])$

Function: treefale (n)

3 contractive maps all with the same contraction ratio. Argument n must be great enougth, 10000 or greater.

Example:

(%i1) load("fractals")$
(%i2) n: 10000$
(%i3) plot2d([discrete,treefale(n)], [style,dots])$

Function: fernfale (n)

4 contractive maps, the probability to choice a transformation must be related with the contraction ratio. Argument n must be great enougth, 10000 or greater.

Example:

(%i1) load("fractals")$
(%i2) n: 10000$
(%i3) plot2d([discrete,fernfale(n)], [style,dots])$

60.3 Definitions for complex fractals

Function: mandelbrot_set (x, y)

Mandelbrot set.

Example:

This program is time consuming because it must make a lot of operations; the computing time is also related with the number of grid points.

(%i1) load("fractals")$
(%i2) plot3d (mandelbrot_set, [x, -2.5, 1], [y, -1.5, 1.5],
                [gnuplot_preamble, "set view map"],
                [gnuplot_pm3d, true],
                [grid, 150, 150])$

Function: julia_set (x, y)

Julia sets.

This program is time consuming because it must make a lot of operations; the computing time is also related with the number of grid points.

Example:

(%i1) load("fractals")$
(%i2) plot3d (julia_set, [x, -2, 1], [y, -1.5, 1.5],
                [gnuplot_preamble, "set view map"],
                [gnuplot_pm3d, true],
                [grid, 150, 150])$

60.4 Definitions for Koch snowflakes

Function: snowmap (ent, nn)

Koch snowflake sets. Function snowmap plots the snow Koch map over the vertex of an initial closed polygonal, in the complex plane. Here the orientation of the polygon is important. Argument nn is the number of recursive applications of Koch transformation; nn must be small (5 or 6).

Examples:

(%i1) load("fractals")$
(%i2) plot2d([discrete,
              snowmap([1,exp(%i*%pi*2/3),exp(-%i*%pi*2/3),1],4)])$
(%i3) plot2d([discrete,
              snowmap([1,exp(-%i*%pi*2/3),exp(%i*%pi*2/3),1],4)])$
(%i4) plot2d([discrete, snowmap([0,1,1+%i,%i,0],4)])$
(%i5) plot2d([discrete, snowmap([0,%i,1+%i,1,0],4)])$

60.5 Definitions for Peano maps

Continuous curves that cover an area. Warning: the number of points exponentially grows with n.

Function: hilbertmap (nn)

Hilbert map. Argument nn must be small (5, for example). Maxima can crash if nn is 7 or greater.

Example:

(%i1) load("fractals")$
(%i2) plot2d([discrete,hilbertmap(6)])$

Function: sierpinskimap (nn)

Sierpinski map. Argument nn must be small (5, for example). Maxima can crash if nn is 7 or greater.

Example:

(%i1) load("fractals")$
(%i2) plot2d([discrete,sierpinskimap(6)])$

Category: Share packages · Category: Package graphs

61 ggf

61.1 Functions and Variables for ggf

Option variable: GGFINFINITY

Default value: 3

This is an option variable for function ggf.

When computing the continued fraction of the generating function, a partial quotient having a degree (strictly) greater than GGFINFINITY will be discarded and the current convergent will be considered as the exact value of the generating function; most often the degree of all partial quotients will be 0 or 1; if you use a greater value, then you should give enough terms in order to make the computation accurate enough.

62 graphs

62.1 Introduction to graphs

The graphs package provides graph and digraph data structure for Maxima. Graphs and digraphs are simple (have no multiple edges nor loops), although digraphs can have a directed edge from u to v and a directed edge from v to u.

Internally graphs are represented by adjacency lists and implemented as a lisp structures. Vertices are identified by their ids (an id is an integer). Edges/arcs are represented by lists of length 2. Labels can be assigned to vertices of graphs/digraphs and weights can be assigned to edges/arcs of graphs/digraphs.

There is a draw_graph function for drawing graphs. Graphs are drawn using a force based vertex positioning algorithm. draw_graph can also use graphviz programs available from http://www.graphviz.org. draw_graph is based on the maxima draw package.

To use the graphs package, first load it with load("graphs").

62.2 Functions and Variables for graphs

62.2.1 Building graphs

Function: create_graph
    create_graph (v_list, e_list)
    create_graph (n, e_list)
    create_graph (v_list, e_list, directed)

Creates a new graph on the set of vertices v_list and with edges e_list.

v_list is a list of vertices ([v1, v2,..., vn]) or a list of vertices together with vertex labels ([[v1,l1], [v2,l2],..., [vn,ln]]).

n is the number of vertices. Vertices will be identified by integers from 0 to n-1.

e_list is a list of edges ([e1, e2,..., em]) or a list of edges together with edge-weights ([[e1, w1], ..., [em, wm]]).

If directed is not false, a directed graph will be returned.

Example 1: create a cycle on 3 vertices:

(%i1) load ("graphs")$
(%i2) g : create_graph([1,2,3], [[1,2], [2,3], [1,3]])$
(%i3) print_graph(g)$
Graph on 3 vertices with 3 edges.
Adjacencies:
  3 :  1  2
  2 :  3  1
  1 :  3  2

Example 2: create a cycle on 3 vertices with edge weights:

(%i1) load ("graphs")$
(%i2) g : create_graph([1,2,3], [[[1,2], 1.0], [[2,3], 2.0],
                          [[1,3], 3.0]])$
(%i3) print_graph(g)$
Graph on 3 vertices with 3 edges.
Adjacencies:
  3 :  1  2
  2 :  3  1
  1 :  3  2

Example 3: create a directed graph:

(%i1) load ("graphs")$
(%i2) d : create_graph(
        [1,2,3,4],
        [
         [1,3], [1,4],
         [2,3], [2,4]
        ],
        'directed = true)$
(%i3) print_graph(d)$
Digraph on 4 vertices with 4 arcs.
Adjacencies:
  4 :
  3 :
  2 :  4  3
  1 :  4  3

Category: Package graphs · Category: Package graphs - constructions

Function: copy_graph (g)

Returns a copy of the graph g.

Function: circulant_graph (n, d)

Returns the circulant graph with parameters n and d.

Example:

(%i1) load ("graphs")$
(%i2) g : circulant_graph(10, [1,3])$
(%i3) print_graph(g)$
Graph on 10 vertices with 20 edges.
Adjacencies:
  9 :  2  6  0  8
  8 :  1  5  9  7
  7 :  0  4  8  6
  6 :  9  3  7  5
  5 :  8  2  6  4
  4 :  7  1  5  3
  3 :  6  0  4  2
  2 :  9  5  3  1
  1 :  8  4  2  0
  0 :  7  3  9  1

Category: Package graphs · Category: Package graphs - constructions

Function: clebsch_graph ()

Returns the Clebsch graph.

Category: Package graphs · Category: Package graphs - constructions

Function: complement_graph (g)

Returns the complement of the graph g.

Category: Package graphs · Category: Package graphs - constructions

Function: complete_bipartite_graph (n, m)

Returns the complete bipartite graph on n+m vertices.

Category: Package graphs · Category: Package graphs - constructions

Function: complete_graph (n)

Returns the complete graph on n vertices.

Category: Package graphs · Category: Package graphs - constructions

Function: cycle_digraph (n)

Returns the directed cycle on n vertices.

Category: Package graphs · Category: Package graphs - constructions

Function: cycle_graph (n)

Returns the cycle on n vertices.

Category: Package graphs · Category: Package graphs - constructions

Function: cuboctahedron_graph (n)

Returns the cuboctahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: cube_graph (n)

Returns the n-dimensional cube.

Category: Package graphs · Category: Package graphs - constructions

Function: dodecahedron_graph ()

Returns the dodecahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: empty_graph (n)

Returns the empty graph on n vertices.

Category: Package graphs · Category: Package graphs - constructions

Function: flower_snark (n)

Returns the flower graph on 4n vertices.

Example:

(%i1) load ("graphs")$
(%i2) f5 : flower_snark(5)$
(%i3) chromatic_index(f5);
(%o3)                           4

Category: Package graphs · Category: Package graphs - constructions

Function: from_adjacency_matrix (A)

Returns the graph represented by its adjacency matrix A.

Category: Package graphs · Category: Package graphs - constructions

Function: frucht_graph ()

Returns the Frucht graph.

Category: Package graphs · Category: Package graphs - constructions

Function: graph_product (g1, g1)

Returns the direct product of graphs g1 and g2.

Example:

(%i1) load ("graphs")$
(%i2) grid : graph_product(path_graph(3), path_graph(4))$
(%i3) draw_graph(grid)$

Category: Package graphs · Category: Package graphs - constructions

Function: graph_union (g1, g1)

Returns the union (sum) of graphs g1 and g2.

Category: Package graphs · Category: Package graphs - constructions

Function: grid_graph (n, m)

Returns the n x m grid.

Category: Package graphs · Category: Package graphs - constructions

Function: great_rhombicosidodecahedron_graph ()

Returns the great rhombicosidodecahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: great_rhombicuboctahedron_graph ()

Returns the great rhombicuboctahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: grotzch_graph ()

Returns the Grotzch graph.

Category: Package graphs · Category: Package graphs - constructions

Function: heawood_graph ()

Returns the Heawood graph.

Category: Package graphs · Category: Package graphs - constructions

Function: icosahedron_graph ()

Returns the icosahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: icosidodecahedron_graph ()

Returns the icosidodecahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: induced_subgraph (V, g)

Returns the graph induced on the subset V of vertices of the graph g.

Example:

(%i1) load ("graphs")$
(%i2) p : petersen_graph()$
(%i3) V : [0,1,2,3,4]$
(%i4) g : induced_subgraph(V, p)$
(%i5) print_graph(g)$
Graph on 5 vertices with 5 edges.
Adjacencies:
  4 :  3  0
  3 :  2  4
  2 :  1  3
  1 :  0  2
  0 :  1  4

Category: Package graphs · Category: Package graphs - constructions

Function: line_graph (g)

Returns the line graph of the graph g.

Category: Package graphs · Category: Package graphs - constructions

Function: make_graph
make_graph (vrt, f)
make_graph (vrt, f, oriented)

Creates a graph using a predicate function f.

vrt is a list/set of vertices or an integer. If vrt is an integer, then vertices of the graph will be integers from 1 to vrt.

f is a predicate function. Two vertices a and b will be connected if f(a,b)=true.

If directed is not false, then the graph will be directed.

Example 1:

(%i1) load("graphs")$
(%i2) g : make_graph(powerset({1,2,3,4,5}, 2), disjointp)$
(%i3) is_isomorphic(g, petersen_graph());
(%o3)                         true
(%i4) get_vertex_label(1, g);
(%o4)                        {1, 2}

Example 2:

(%i1) load("graphs")$
(%i2) f(i, j) := is (mod(j, i)=0)$
(%i3) g : make_graph(20, f, directed=true)$
(%i4) out_neighbors(4, g);
(%o4)                    [8, 12, 16, 20]
(%i5) in_neighbors(18, g);
(%o5)                    [1, 2, 3, 6, 9]

Category: Package graphs · Category: Package graphs - constructions

Function: mycielski_graph (g)

Returns the mycielskian graph of the graph g.

Category: Package graphs · Category: Package graphs - constructions

Function: new_graph ()

Returns the graph with no vertices and no edges.

Category: Package graphs · Category: Package graphs - constructions

Function: path_digraph (n)

Returns the directed path on n vertices.

Category: Package graphs · Category: Package graphs - constructions

Function: path_graph (n)

Returns the path on n vertices.

Category: Package graphs · Category: Package graphs - constructions

Function: petersen_graph
petersen_graph ()
petersen_graph (n, d)

Returns the petersen graph P_{n,d}. The default values for n and d are n=5 and d=2.

Category: Package graphs · Category: Package graphs - constructions

Function: random_bipartite_graph (a, b, p)

Returns a random bipartite graph on a+b vertices. Each edge is present with probability p.

Category: Package graphs · Category: Package graphs - constructions

Function: random_digraph (n, p)

Returns a random directed graph on n vertices. Each arc is present with probability p.

Category: Package graphs · Category: Package graphs - constructions

Function: random_regular_graph
random_regular_graph (n)
random_regular_graph (n, d)

Returns a random d-regular graph on n vertices. The default value for d is d=3.

Category: Package graphs · Category: Package graphs - constructions

Function: random_graph (n, p)

Returns a random graph on n vertices. Each edge is present with probability p.

Category: Package graphs · Category: Package graphs - constructions

Function: random_graph1 (n, m)

Returns a random graph on n vertices and random m edges.

Category: Package graphs · Category: Package graphs - constructions

Function: random_network (n, p, w)

Returns a random network on n vertices. Each arc is present with probability p and has a weight in the range [0,w]. The function returns a list [network, source, sink].

Example:

(%i1) load ("graphs")$
(%i2) [net, s, t] : random_network(50, 0.2, 10.0);
(%o2)                   [DIGRAPH, 50, 51]
(%i3) max_flow(net, s, t)$
(%i4) first(%);
(%o4)                   27.65981397932507

Category: Package graphs · Category: Package graphs - constructions

Function: random_tournament (n)

Returns a random tournament on n vertices.

Category: Package graphs · Category: Package graphs - constructions

Function: random_tree (n)

Returns a random tree on n vertices.

Category: Package graphs · Category: Package graphs - constructions

Function: small_rhombicosidodecahedron_graph ()

Returns the small rhombicosidodecahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: small_rhombicuboctahedron_graph ()

Returns the small rhombicuboctahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: snub_cube_graph ()

Returns the snub cube graph.

Category: Package graphs · Category: Package graphs - constructions

Function: snub_dodecahedron_graph ()

Returns the snub dodecahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: truncated_cube_graph ()

Returns the truncated cube graph.

Category: Package graphs · Category: Package graphs - constructions

Function: truncated_dodecahedron_graph ()

Returns the truncated dodecahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: truncated_icosahedron_graph ()

Returns the truncated icosahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: truncated_tetrahedron_graph ()

Returns the truncated tetrahedron graph.

Category: Package graphs · Category: Package graphs - constructions

Function: tutte_graph ()

Returns the Tutte graph.

Category: Package graphs · Category: Package graphs - constructions

Function: underlying_graph (g)

Returns the underlying graph of the directed graph g.

Category: Package graphs · Category: Package graphs - constructions

Function: wheel_graph (n)

Returns the wheel graph on n+1 vertices.

Category: Package graphs · Category: Package graphs - constructions

62.2.2 Graph properties

Function: adjacency_matrix (gr)

Returns the adjacency matrix of the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) c5 : cycle_graph(4)$
(%i3) adjacency_matrix(c5);
                         [ 0  1  0  1 ]
                         [            ]
                         [ 1  0  1  0 ]
(%o3)                    [            ]
                         [ 0  1  0  1 ]
                         [            ]
                         [ 1  0  1  0 ]

Category: Package graphs · Category: Package graphs - properties

Function: average_degree (gr)

Returns the average degree of vertices in the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) average_degree(grotzch_graph());
                               40
(%o2)                          --
                               11

Category: Package graphs · Category: Package graphs - properties

Function: biconnected_components (gr)

Returns the (vertex sets of) 2-connected components of the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) g : create_graph(
            [1,2,3,4,5,6,7],
            [
             [1,2],[2,3],[2,4],[3,4],
             [4,5],[5,6],[4,6],[6,7]
            ])$
(%i3) biconnected_components(g);
(%o3)        [[6, 7], [4, 5, 6], [1, 2], [2, 3, 4]]

Category: Package graphs · Category: Package graphs - properties

Function: bipartition (gr)

Returns a bipartition of the vertices of the graph gr or an empty list if gr is not bipartite.

Example:

(%i1) load ("graphs")$
(%i2) h : heawood_graph()$
(%i3) [A,B]:bipartition(h);
(%o3)  [[8, 12, 6, 10, 0, 2, 4], [13, 5, 11, 7, 9, 1, 3]]
(%i4) draw_graph(h, show_vertices=A, program=circular)$

Category: Package graphs · Category: Package graphs - properties

Function: chromatic_index (gr)

Returns the chromatic index of the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) p : petersen_graph()$
(%i3) chromatic_index(p);
(%o3)                           4

Category: Package graphs · Category: Package graphs - properties

Function: chromatic_number (gr)

Returns the chromatic number of the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) chromatic_number(cycle_graph(5));
(%o2)                           3
(%i3) chromatic_number(cycle_graph(6));
(%o3)                           2

Category: Package graphs · Category: Package graphs - properties

Function: clear_edge_weight (e, gr)

Removes the weight of the edge e in the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) g : create_graph(3, [[[0,1], 1.5], [[1,2], 1.3]])$
(%i3) get_edge_weight([0,1], g);
(%o3)                          1.5
(%i4) clear_edge_weight([0,1], g)$
(%i5) get_edge_weight([0,1], g);
(%o5)                           1

Category: Package graphs · Category: Package graphs - properties

Function: clear_vertex_label (v, gr)

Removes the label of the vertex v in the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) g : create_graph([[0,"Zero"], [1, "One"]], [[0,1]])$
(%i3) get_vertex_label(0, g);
(%o3)                         Zero
(%i4) clear_vertex_label(0, g);
(%o4)                         done
(%i5) get_vertex_label(0, g);
(%o5)                         false

Category: Package graphs · Category: Package graphs - properties

Function: connected_components (gr)

Returns the (vertex sets of) connected components of the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) g: graph_union(cycle_graph(5), path_graph(4))$
(%i3) connected_components(g);
(%o3)            [[1, 2, 3, 4, 0], [8, 7, 6, 5]]

Category: Package graphs · Category: Package graphs - properties

Function: diameter (gr)

Returns the diameter of the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) diameter(dodecahedron_graph());
(%o2)                           5

Category: Package graphs · Category: Package graphs - properties

Function: edge_coloring (gr)

Returns an optimal coloring of the edges of the graph gr.

The function returns the chromatic index and a list representing the coloring of the edges of gr.

Example:

(%i1) load ("graphs")$
(%i2) p : petersen_graph()$
(%i3) [ch_index, col] : edge_coloring(p);
(%o3) [4, [[[0, 5], 3], [[5, 7], 1], [[0, 1], 1], [[1, 6], 2], 
[[6, 8], 1], [[1, 2], 3], [[2, 7], 4], [[7, 9], 2], [[2, 3], 2], 
[[3, 8], 3], [[5, 8], 2], [[3, 4], 1], [[4, 9], 4], [[6, 9], 3], 
[[0, 4], 2]]]
(%i4) assoc([0,1], col);
(%o4)                           1
(%i5) assoc([0,5], col);
(%o5)                           3

Category: Package graphs · Category: Package graphs - properties

Function: degree_sequence (gr)

Returns the list of vertex degrees of the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) degree_sequence(random_graph(10, 0.4));
(%o2)            [2, 2, 2, 2, 2, 2, 3, 3, 3, 3]

Category: Package graphs · Category: Package graphs - properties

Function: edge_connectivity (gr)

Returns the edge-connectivity of the graph gr.

62.2.3 Modifying graphs

Function: add_edge (e, gr)

Adds the edge e to the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) p : path_graph(4)$
(%i3) neighbors(0, p);
(%o3)                          [1]
(%i4) add_edge([0,3], p);
(%o4)                         done
(%i5) neighbors(0, p);
(%o5)                        [3, 1]

Category: Package graphs · Category: Package graphs - modifications

Function: add_edges (e_list, gr)

Adds all edges in the list e_list to the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) g : empty_graph(3)$
(%i3) add_edges([[0,1],[1,2]], g)$
(%i4) print_graph(g)$
Graph on 3 vertices with 2 edges.
Adjacencies:
  2 :  1
  1 :  2  0
  0 :  1

Category: Package graphs · Category: Package graphs - modifications

Function: add_vertex (v, gr)

Adds the vertex v to the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) g : path_graph(2)$
(%i3) add_vertex(2, g)$
(%i4) print_graph(g)$
Graph on 3 vertices with 1 edges.
Adjacencies:
  2 :
  1 :  0
  0 :  1

Category: Package graphs · Category: Package graphs - modifications

Function: add_vertices (v_list, gr)

Adds all vertices in the list v_list to the graph gr.

Category: Package graphs · Category: Package graphs - modifications

Function: connect_vertices (v_list, u_list, gr)

Connects all vertices from the list v_list with the vertices in the list u_list in the graph gr.

v_list and u_list can be single vertices or lists of vertices.

Example:

(%i1) load ("graphs")$
(%i2) g : empty_graph(4)$
(%i3) connect_vertices(0, [1,2,3], g)$
(%i4) print_graph(g)$
Graph on 4 vertices with 3 edges.
Adjacencies:
  3 :  0
  2 :  0
  1 :  0
  0 :  3  2  1

Category: Package graphs · Category: Package graphs - modifications

Function: contract_edge (e, gr)

Contracts the edge e in the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) g: create_graph(
      8, [[0,3],[1,3],[2,3],[3,4],[4,5],[4,6],[4,7]])$
(%i3) print_graph(g)$
Graph on 8 vertices with 7 edges.
Adjacencies:
  7 :  4
  6 :  4
  5 :  4
  4 :  7  6  5  3
  3 :  4  2  1  0
  2 :  3
  1 :  3
  0 :  3
(%i4) contract_edge([3,4], g)$
(%i5) print_graph(g)$
Graph on 7 vertices with 6 edges.
Adjacencies:
  7 :  3
  6 :  3
  5 :  3
  3 :  5  6  7  2  1  0
  2 :  3
  1 :  3
  0 :  3

Category: Package graphs · Category: Package graphs - modifications

Function: remove_edge (e, gr)

Removes the edge e from the graph gr.

Example:

(%i1) load ("graphs")$
(%i2) c3 : cycle_graph(3)$
(%i3) remove_edge([0,1], c3)$
(%i4) print_graph(c3)$
Graph on 3 vertices with 2 edges.
Adjacencies:
  2 :  0  1
  1 :  2
  0 :  2

Category: Package graphs · Category: Package graphs - modifications

Function: remove_vertex (v, gr)

Removes the vertex v from the graph gr.

Category: Package graphs · Category: Package graphs - io

62.2.4 Reading and writing to files

Function: dimacs_export
dimacs_export (gr, fl)
dimacs_export (gr, fl, comment1, ..., commentn)

Exports the graph into the file fl in the DIMACS format. Optional comments will be added to the top of the file.

Function: dimacs_import (fl)

Returns the graph from file fl in the DIMACS format.

Category: Package graphs · Category: Package graphs - io

Function: graph6_decode (str)

Returns the graph encoded in the graph6 format in the string str.

Category: Package graphs · Category: Package graphs - io

Function: graph6_encode (gr)

Returns a string which encodes the graph gr in the graph6 format.

Category: Package graphs · Category: Package graphs - io

Function: graph6_export (gr_list, fl)

Exports graphs in the list gr_list to the file fl in the graph6 format.

Category: Package graphs · Category: Package graphs - io

Function: graph6_import (fl)

Returns a list of graphs from the file fl in the graph6 format.

Category: Package graphs · Category: Package graphs - io

Function: sparse6_decode (str)

Returns the graph encoded in the sparse6 format in the string str.

Category: Package graphs · Category: Package graphs - io

Function: sparse6_encode (gr)

Returns a string which encodes the graph gr in the sparse6 format.

Category: Package graphs · Category: Package graphs - io

Function: sparse6_export (gr_list, fl)

Exports graphs in the list gr_list to the file fl in the sparse6 format.

Category: Package graphs · Category: Package graphs - io

Function: sparse6_import (fl)

Returns a list of graphs from the file fl in the sparse6 format.

Category: Package graphs · Category: Package graphs - io

62.2.5 Visualization

Function: draw_graph
draw_graph (graph)
draw_graph (graph, option1, ..., optionk)

Draws the graph using the draw-pkg package.

The algorithm used to position vertices is specified by the optional argument program. The default value is program=spring_embedding. draw_graph can also use the graphviz programs for positioning vertices, but graphviz must be installed separately.

Example 1:

(%i1) load ("graphs")$
(%i2) g:grid_graph(10,10)$
(%i3) m:max_matching(g)$
(%i4) draw_graph(g,
   spring_embedding_depth=100,
   show_edges=m, edge_type=dots,
   vertex_size=0)$

Example 2:

(%i1) load ("graphs")$
(%i2) g:create_graph(16,
    [
     [0,1],[1,3],[2,3],[0,2],[3,4],[2,4],
     [5,6],[6,4],[4,7],[6,7],[7,8],[7,10],[7,11],
     [8,10],[11,10],[8,9],[11,12],[9,15],[12,13],
     [10,14],[15,14],[13,14]
    ])$
(%i3) t:minimum_spanning_tree(g)$
(%i4) draw_graph(
    g,
    show_edges=edges(t),
    show_edge_width=4,
    show_edge_color=green,
    vertex_type=filled_square,
    vertex_size=2
    )$

Example 3:

(%i1) load ("graphs")$
(%i2) g:create_graph(16,
    [
     [0,1],[1,3],[2,3],[0,2],[3,4],[2,4],
     [5,6],[6,4],[4,7],[6,7],[7,8],[7,10],[7,11],
     [8,10],[11,10],[8,9],[11,12],[9,15],[12,13],
     [10,14],[15,14],[13,14]
    ])$
(%i3) mi : max_independent_set(g)$
(%i4) draw_graph(
    g,
    show_vertices=mi,
    show_vertex_type=filled_up_triangle,
    show_vertex_size=2,
    edge_color=cyan,
    edge_width=3,
    show_id=true,
    text_color=brown
    )$

Example 4:

(%i1) load ("graphs")$
(%i2) net : create_graph(
    [0,1,2,3,4,5],
    [
     [[0,1], 3], [[0,2], 2],
     [[1,3], 1], [[1,4], 3],
     [[2,3], 2], [[2,4], 2],
     [[4,5], 2], [[3,5], 2]
    ],
    directed=true
    )$
(%i3) draw_graph(
    net,
    show_weight=true,
    vertex_size=0,
    show_vertices=[0,5],
    show_vertex_type=filled_square,
    head_length=0.2,
    head_angle=10,
    edge_color="dark-green",
    text_color=blue
    )$

Example 5:

(%i1) load("graphs")$
(%i2) g: petersen_graph(20, 2);
(%o2)                         GRAPH
(%i3) draw_graph(g, redraw=true, program=planar_embedding);
(%o3)                         done

Example 6:

(%i1) load("graphs")$
(%i2) t: tutte_graph();
(%o2)                         GRAPH
(%i3) draw_graph(t, redraw=true, 
                    fixed_vertices=[1,2,3,4,5,6,7,8,9]);
(%o3)                         done

Category: Package graphs · Category: Package graphs - draw_graphs options

Option variable: draw_graph_program

Default value: spring_embedding

The default value for the program used to position vertices in draw_graph program.

draw_graph option: show_id

Default value: false

If true then ids of the vertices are displayed.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: show_label

Default value: false

If true then labels of the vertices are displayed.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: label_alignment

Default value: center

Determines how to align the labels/ids of the vertices. Can be left, center or right.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: show_weight

Default value: false

If true then weights of the edges are displayed.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: vertex_type

Default value: circle

Defines how vertices are displayed. See the point_type option for the draw package for possible values.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: vertex_size

The size of vertices.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: vertex_color

The color used for displaying vertices.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: show_vertices

Default value: []

Display selected vertices in the using a different color.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: show_vertex_type

Defines how vertices specified in show_vertices are displayed. See the point_type option for the draw package for possible values.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: show_vertex_size

The size of vertices in show_vertices.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: show_vertex_color

The color used for displaying vertices in the show_vertices list.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: vertex_partition

Default value: []

A partition [[v1,v2,...],...,[vk,...,vn]] of the vertices of the graph. The vertices of each list in the partition will be drawn in a different color.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: vertex_coloring

Specifies coloring of the vertices. The coloring col must be specified in the format as returned by vertex_coloring.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: edge_color

The color used for displaying edges.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: edge_width

The width of edges.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: edge_type

Defines how edges are displayed. See the line_type option for the draw package.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: show_edges

Display edges specified in the list e_list using a different color.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: show_edge_color

The color used for displaying edges in the show_edges list.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: show_edge_width

The width of edges in show_edges.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: show_edge_type

Defines how edges in show_edges are displayed. See the line_type option for the draw package.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: edge_partition

A partition [[e1,e2,...],...,[ek,...,em]] of edges of the graph. The edges of each list in the partition will be drawn using a different color.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: edge_coloring

The coloring of edges. The coloring must be specified in the format as returned by the function edge_coloring.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: redraw

Default value: false

If true, vertex positions are recomputed even if the positions have been saved from a previous drawing of the graph.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: head_angle

Default value: 15

The angle for the arrows displayed on arcs (in directed graphs).

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: head_length

Default value: 0.1

The length for the arrows displayed on arcs (in directed graphs).

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: spring_embedding_depth

Default value: 50

The number of iterations in the spring embedding graph drawing algorithm.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: terminal

The terminal used for drawing (see the terminal option in the draw package).

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: file_name

The filename of the drawing if terminal is not screen.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: program

Defines the program used for positioning vertices of the graph. Can be one of the graphviz programs (dot, neato, twopi, circ, fdp), circular, spring_embedding or planar_embedding. planar_embedding is only available for 2-connected planar graphs. When program=spring_embedding, a set of vertices with fixed position can be specified with the fixed_vertices option.

Category: Package graphs · Category: Package graphs - draw_graphs options

draw_graph option: fixed_vertices

Specifies a list of vertices which will have positions fixed along a regular polygon. Can be used when program=spring_embedding.

Category: Package graphs · Category: Package graphs - draw_graphs options

Function: vertices_to_path (v_list)

Converts a list v_list of vertices to a list of edges of the path defined by v_list.

Function: vertices_to_cycle (v_list)

Converts a list v_list of vertices to a list of edges of the cycle defined by v_list.

http://alamos.math.arizona.edu

63 grobner

63.1 Introduction to grobner

grobner is a package for working with Groebner bases in Maxima.

To use the following functions you must load the grobner.lisp package.

load(grobner);

A demo can be started by

demo("grobner.demo");

batch("grobner.demo")

Some of the calculation in the demo will take a lot of time therefore the output grobner-demo.output of the demo can be found in the same directory as the demo file.

63.1.1 Notes on the grobner package

The package was written by

Marek Rychlik

and is released 2002-05-24 under the terms of the General Public License(GPL) (see file grobner.lisp). This documentation was extracted from the files

README, grobner.lisp, grobner.demo, grobner-demo.output

by Günter Nowak. Suggestions for improvement of the documentation can be discussed at the maxima-mailing-list maxima@math.utexas.edu. The code is a little bit out of date now. Modern implementation use the fast F4 algorithm described in

A new efficient algorithm for computing Gröbner bases (F4) 
Jean-Charles Faugère
LIP6/CNRS Université Paris VI 
January 20, 1999

Category: Groebner bases · Category: Share packages · Category: Package grobner

63.1.2 Implementations of admissible monomial orders in grobner

lex
pure lexicographic, default order for monomial comparisons
grlex
total degree order, ties broken by lexicographic
grevlex
total degree, ties broken by reverse lexicographic
invlex
inverse lexicographic order

63.2 Functions and Variables for grobner

63.2.1 Global switches for grobner

Option variable: poly_monomial_order

Default value: lex

This global switch controls which monomial order is used in polynomial and Groebner Bases calculations. If not set, lex will be used.

Option variable: poly_coefficient_ring

Default value: expression_ring

This switch indicates the coefficient ring of the polynomials that will be used in grobner calculations. If not set, maxima’s general expression ring will be used. This variable may be set to ring_of_integers if desired.

Option variable: poly_primary_elimination_order

Default value: false

Name of the default order for eliminated variables in elimination-based functions. If not set, lex will be used.

Option variable: poly_secondary_elimination_order

Default value: false

Name of the default order for kept variables in elimination-based functions. If not set, lex will be used.

Option variable: poly_elimination_order

Default value: false

Name of the default elimination order used in elimination calculations. If set, it overrides the settings in variables poly_primary_elimination_order and poly_secondary_elimination_order. The user must ensure that this is a true elimination order valid for the number of eliminated variables.

Option variable: poly_return_term_list

Default value: false

If set to true, all functions in this package will return each polynomial as a list of terms in the current monomial order rather than a maxima general expression.

Option variable: poly_grobner_debug

Default value: false

If set to true, produce debugging and tracing output.

Option variable: poly_grobner_algorithm

Default value: buchberger

Possible values:

buchberger
parallel_buchberger
gebauer_moeller

The name of the algorithm used to find the Groebner Bases.

Option variable: poly_top_reduction_only

Default value: false

If not false, use top reduction only whenever possible. Top reduction means that division algorithm stops after the first reduction.

63.2.2 Simple operators in grobner

poly_add, poly_subtract, poly_multiply and poly_expt are the arithmetical operations on polynomials. These are performed using the internal representation, but the results are converted back to the maxima general form.

Function: poly_add (poly1, poly2, varlist)

Adds two polynomials poly1 and poly2.


(%i1) poly_add(z+x^2*y,x-z,[x,y,z]);
                                    2
(%o1)                              x  y + x

Function: poly_subtract (poly1, poly2, varlist)

Subtracts a polynomial poly2 from poly1.


(%i1) poly_subtract(z+x^2*y,x-z,[x,y,z]);
                                      2
(%o1)                          2 z + x  y - x

Function: poly_multiply (poly1, poly2, varlist)

Returns the product of polynomials poly1 and poly2.


(%i2) poly_multiply(z+x^2*y,x-z,[x,y,z])-(z+x^2*y)*(x-z),expand;
(%o1)                                  0

Function: poly_s_polynomial (poly1, poly2, varlist)

Returns the syzygy polynomial (S-polynomial) of two polynomials poly1 and poly2.

Function: poly_primitive_part (poly1, varlist)

Returns the polynomial poly divided by the GCD of its coefficients.

(%i1) poly_primitive_part(35*y+21*x,[x,y]);
(%o1)                              5 y + 3 x

Function: poly_normalize (poly, varlist)

Returns the polynomial poly divided by the leading coefficient. It assumes that the division is possible, which may not always be the case in rings which are not fields.

63.2.3 Other functions in grobner

Function: poly_expand (poly, varlist)

This function parses polynomials to internal form and back. It is equivalent to expand(poly) if poly parses correctly to a polynomial. If the representation is not compatible with a polynomial in variables varlist, the result is an error. It can be used to test whether an expression correctly parses to the internal representation. The following examples illustrate that indexed and transcendental function variables are allowed.


(%i1) poly_expand((x-y)*(y+x),[x,y]);
                                     2    2
(%o1)                               x  - y
(%i2) poly_expand((y+x)^2,[x,y]);
                                2            2
(%o2)                          y  + 2 x y + x
(%i3) poly_expand((y+x)^5,[x,y]);
                  5      4         2  3       3  2      4      5
(%o3)            y  + 5 x y  + 10 x  y  + 10 x  y  + 5 x  y + x
(%i4) poly_expand(-1-x*exp(y)+x^2/sqrt(y),[x]);
                                          2
                                  y      x
(%o4)                       - x %e  + ------- - 1
                                       sqrt(y)

(%i5) poly_expand(-1-sin(x)^2+sin(x),[sin(x)]);
                                2
(%o5)                      - sin (x) + sin(x) - 1

Function: poly_expt (poly, number, varlist)

exponentitates poly by a positive integer number. If number is not a positive integer number an error will be raised.


(%i1) poly_expt(x-y,3,[x,y])-(x-y)^3,expand;
(%o1)                                  0

Function: poly_content (poly. varlist)

poly_content extracts the GCD of its coefficients


(%i1) poly_content(35*y+21*x,[x,y]);
(%o1)                                  7

Function: poly_pseudo_divide (poly, polylist, varlist)

Pseudo-divide a polynomial poly by the list of n polynomials polylist. Return multiple values. The first value is a list of quotients a. The second value is the remainder r. The third argument is a scalar coefficient c, such that c*poly can be divided by polylist within the ring of coefficients, which is not necessarily a field. Finally, the fourth value is an integer count of the number of reductions performed. The resulting objects satisfy the equation:

c*poly=sum(a[i]*polylist[i],i=1...n)+r.

Function: poly_exact_divide (poly1, poly2, varlist)

Divide a polynomial poly1 by another polynomial poly2. Assumes that exact division with no remainder is possible. Returns the quotient.

Function: poly_normal_form (poly, polylist, varlist)

poly_normal_form finds the normal form of a polynomial poly with respect to a set of polynomials polylist.

Function: poly_buchberger_criterion (polylist, varlist)

Returns true if polylist is a Groebner basis with respect to the current term order, by using the Buchberger criterion: for every two polynomials h1 and h2 in polylist the S-polynomial S(h1,h2) reduces to 0 modulo polylist.

Function: poly_buchberger (polylist_fl varlist)

poly_buchberger performs the Buchberger algorithm on a list of polynomials and returns the resulting Groebner basis.

63.2.4 Standard postprocessing of Groebner Bases

The k-th elimination Ideal I_k of an Ideal I over K[ x[1],...,x[n] ] is the ideal intersect(I, K[ x[k+1],...,x[n] ]).
The colon ideal I:J is the ideal {h|for all w in J: w*h in I}.
The ideal I:p^inf is the ideal {h| there is a n in N: p^n*h in I}.
The ideal I:J^inf is the ideal {h| there is a n in N and a p in J: p^n*h in I}.
The radical ideal sqrt(I) is the ideal {h| there is a n in N : h^n in I }.

Function: poly_reduction (polylist, varlist)

poly_reduction reduces a list of polynomials polylist, so that each polynomial is fully reduced with respect to the other polynomials.

Function: poly_minimization (polylist, varlist)

Returns a sublist of the polynomial list polylist spanning the same monomial ideal as polylist but minimal, i.e. no leading monomial of a polynomial in the sublist divides the leading monomial of another polynomial.

Function: poly_normalize_list (polylist, varlist)

poly_normalize_list applies poly_normalize to each polynomial in the list. That means it divides every polynomial in a list polylist by its leading coefficient.

Function: poly_grobner (polylist, varlist)

Returns a Groebner basis of the ideal span by the polynomials polylist. Affected by the global flags.

Function: poly_reduced_grobner (polylist, varlist)

Returns a reduced Groebner basis of the ideal span by the polynomials polylist. Affected by the global flags.

Category: Package grobner · Category: Predicate functions

Function: poly_depends_p (poly, var, varlist)

poly_depends tests whether a polynomial depends on a variable var.

Function: poly_elimination_ideal (polylist, number, varlist)

poly_elimination_ideal returns the grobner basis of the number-th elimination ideal of an ideal specified as a list of generating polynomials (not necessarily Groebner basis).

Function: poly_colon_ideal (polylist1, polylist2, varlist)

Returns the reduced Groebner basis of the colon ideal

I(polylist1):I(polylist2)

where polylist1 and polylist2 are two lists of polynomials.

Function: poly_ideal_intersection (polylist1, polylist2, varlist)

poly_ideal_intersection returns the intersection of two ideals.

Function: poly_lcm (poly1, poly2, varlist)

Returns the lowest common multiple of poly1 and poly2.

Function: poly_gcd (poly1, poly2, varlist)

Returns the greatest common divisor of poly1 and poly2.

See also ezgcd, gcd, gcdex, and gcdivide.

Example:

(%i1) p1:6*x^3+19*x^2+19*x+6; 
                        3       2
(%o1)                6 x  + 19 x  + 19 x + 6
(%i2) p2:6*x^5+13*x^4+12*x^3+13*x^2+6*x;
                  5       4       3       2
(%o2)          6 x  + 13 x  + 12 x  + 13 x  + 6 x
(%i3) poly_gcd(p1, p2, [x]);
                            2
(%o3)                    6 x  + 13 x + 6

Function: poly_grobner_equal (polylist1, polylist2, varlist)

poly_grobner_equal tests whether two Groebner Bases generate the same ideal. Returns true if two lists of polynomials polylist1 and polylist2, assumed to be Groebner Bases, generate the same ideal, and false otherwise. This is equivalent to checking that every polynomial of the first basis reduces to 0 modulo the second basis and vice versa. Note that in the example below the first list is not a Groebner basis, and thus the result is false.

(%i1) poly_grobner_equal([y+x,x-y],[x,y],[x,y]);
(%o1)                         false

Category: Package grobner · Category: Predicate functions

Function: poly_grobner_subsetp (polylist1, polylist2, varlist)

poly_grobner_subsetp tests whether an ideal generated by polylist1 is contained in the ideal generated by polylist2. For this test to always succeed, polylist2 must be a Groebner basis.

Function: poly_grobner_member (poly, polylist, varlist)

Returns true if a polynomial poly belongs to the ideal generated by the polynomial list polylist, which is assumed to be a Groebner basis. Returns false otherwise.

poly_grobner_member tests whether a polynomial belongs to an ideal generated by a list of polynomials, which is assumed to be a Groebner basis. Equivalent to normal_form being 0.

Function: poly_ideal_saturation1 (polylist, poly, varlist)

Returns the reduced Groebner basis of the saturation of the ideal

I(polylist):poly^inf

Geometrically, over an algebraically closed field, this is the set of polynomials in the ideal generated by polylist which do not identically vanish on the variety of poly.

Function: poly_ideal_saturation (polylist1, polylist2, varlist)

Returns the reduced Groebner basis of the saturation of the ideal

I(polylist1):I(polylist2)^inf

Geometrically, over an algebraically closed field, this is the set of polynomials in the ideal generated by polylist1 which do not identically vanish on the variety of polylist2.

Function: poly_ideal_polysaturation1 (polylist1, polylist2, varlist)

polylist2 ist a list of n polynomials [poly1,...,polyn]. Returns the reduced Groebner basis of the ideal

I(polylist):poly1^inf:...:polyn^inf

obtained by a sequence of successive saturations in the polynomials of the polynomial list polylist2 of the ideal generated by the polynomial list polylist1.

Function: poly_ideal_polysaturation (polylist, polylistlist, varlist)

polylistlist is a list of n list of polynomials [polylist1,...,polylistn]. Returns the reduced Groebner basis of the saturation of the ideal

I(polylist):I(polylist_1)^inf:...:I(polylist_n)^inf

Function: poly_saturation_extension (poly, polylist, varlist1, varlist2)

poly_saturation_extension implements the famous Rabinowitz trick.

Category: Differential calculus · Category: Share packages · Category: Package impdiff

Function: poly_polysaturation_extension (poly, polylist, varlist1, varlist2): ·
Category: Package grobner

64 impdiff

64.1 Functions and Variables for impdiff

Function: implicit_derivative (f,indvarlist,orderlist,depvar)

This subroutine computes implicit derivatives of multivariable functions. f is an array function, the indexes are the derivative degree in the indvarlist order; indvarlist is the independent variable list; orderlist is the order desired; and depvar is the dependent variable.

To use this function write first load("impdiff").

65 interpol

65.1 Introduction to interpol

Package interpol defines the Lagrangian, the linear and the cubic splines methods for polynomial interpolation.

For comments, bugs or suggestions, please contact me at ’mario AT edu DOT xunta DOT es’.

Category: Numerical methods · Category: Share packages · Category: Package interpol

65.2 Functions and Variables for interpol

Function: lagrange
lagrange (points)
lagrange (points, option)

Computes the polynomial interpolation by the Lagrangian method. Argument points must be either:

a two column matrix, p:matrix([2,4],[5,6],[9,3]),
a list of pairs, p: [[2,4],[5,6],[9,3]],
a list of numbers, p: [4,6,3], in which case the abscissas will be assigned automatically to 1, 2, 3, etc.

In the first two cases the pairs are ordered with respect to the first coordinate before making computations.

With the option argument it is possible to select the name for the independent variable, which is 'x by default; to define another one, write something like varname='z.

Note that when working with high degree polynomials, floating point evaluations are unstable.

See also linearinterpol, cspline, and ratinterpol.

Examples:

(%i1) load("interpol")$
(%i2) p:[[7,2],[8,2],[1,5],[3,2],[6,7]]$
(%i3) lagrange(p);
       (x - 7) (x - 6) (x - 3) (x - 1)
(%o3)  -------------------------------
                     35
   (x - 8) (x - 6) (x - 3) (x - 1)
 - -------------------------------
                 12
   7 (x - 8) (x - 7) (x - 3) (x - 1)
 + ---------------------------------
                  30
   (x - 8) (x - 7) (x - 6) (x - 1)
 - -------------------------------
                 60
   (x - 8) (x - 7) (x - 6) (x - 3)
 + -------------------------------
                 84
(%i4) f(x):=''%;
               (x - 7) (x - 6) (x - 3) (x - 1)
(%o4)  f(x) := -------------------------------
                             35
   (x - 8) (x - 6) (x - 3) (x - 1)
 - -------------------------------
                 12
   7 (x - 8) (x - 7) (x - 3) (x - 1)
 + ---------------------------------
                  30
   (x - 8) (x - 7) (x - 6) (x - 1)
 - -------------------------------
                 60
   (x - 8) (x - 7) (x - 6) (x - 3)
 + -------------------------------
                 84
(%i5) /* Evaluate the polynomial at some points */
      expand(map(f,[2.3,5/7,%pi]));
                                  4          3           2
                    919062  73 %pi    701 %pi    8957 %pi
(%o5)  [- 1.567535, ------, ------- - -------- + ---------
                    84035     420       210         420
                                             5288 %pi   186
                                           - -------- + ---]
                                               105       5
(%i6) %,numer;
(%o6) [- 1.567535, 10.9366573451538, 2.89319655125692]
(%i7) load("draw")$  /* load draw package */
(%i8) /* Plot the polynomial together with points */
      draw2d(
        color      = red,
        key        = "Lagrange polynomial",
        explicit(f(x),x,0,10),
        point_size = 3,
        color      = blue,
        key        = "Sample points",
        points(p))$
(%i9) /* Change variable name */
      lagrange(p, varname=w);
       (w - 7) (w - 6) (w - 3) (w - 1)
(%o9)  -------------------------------
                     35
   (w - 8) (w - 6) (w - 3) (w - 1)
 - -------------------------------
                 12
   7 (w - 8) (w - 7) (w - 3) (w - 1)
 + ---------------------------------
                  30
   (w - 8) (w - 7) (w - 6) (w - 1)
 - -------------------------------
                 60
   (w - 8) (w - 7) (w - 6) (w - 3)
 + -------------------------------
                 84

Category: Package interpol

Function: charfun2 (x, a, b)

The characteristic or indicator function on the half-open interval [a, b), that is, including a and excluding b.

When x >= a and x < b evaluates to true or false, charfun2 returns 1 or 0, respectively.

Otherwise, charfun2 returns a partially-evaluated result in terms of charfun.

Package interpol loads this function.

66 lapack

66.1 Introduction to lapack

lapack is a Common Lisp translation (via the program f2cl) of the Fortran library LAPACK, as obtained from the SLATEC project.

Category: Numerical methods · Category: Share packages · Category: Package lapack

66.2 Functions and Variables for lapack

Function: dgeev
dgeev (A)
dgeev (A, right_p, left_p)

Computes the eigenvalues and, optionally, the eigenvectors of a matrix A. All elements of A must be integer or floating point numbers. A must be square (same number of rows and columns). A might or might not be symmetric.

dgeev(A) computes only the eigenvalues of A. dgeev(A, right_p, left_p) computes the eigenvalues of A and the right eigenvectors when right_p = true and the left eigenvectors when left_p = true.

A list of three items is returned. The first item is a list of the eigenvalues. The second item is false or the matrix of right eigenvectors. The third item is false or the matrix of left eigenvectors.

The right eigenvector v(j) (the j-th column of the right eigenvector matrix) satisfies

A . v(j) = lambda(j) . v(j)

where lambda(j) is the corresponding eigenvalue. The left eigenvector u(j) (the j-th column of the left eigenvector matrix) satisfies

u(j)**H . A = lambda(j) . u(j)**H

where u(j)**H denotes the conjugate transpose of u(j). The Maxima function ctranspose computes the conjugate transpose.

The computed eigenvectors are normalized to have Euclidean norm equal to 1, and largest component has imaginary part equal to zero.

Example:

(%i1) load ("lapack")$
(%i2) fpprintprec : 6;
(%o2)                           6
(%i3) M : matrix ([9.5, 1.75], [3.25, 10.45]);
                         [ 9.5   1.75  ]
(%o3)                    [             ]
                         [ 3.25  10.45 ]
(%i4) dgeev (M);
(%o4)          [[7.54331, 12.4067], false, false]
(%i5) [L, v, u] : dgeev (M, true, true);
                           [ - .666642  - .515792 ]
(%o5) [[7.54331, 12.4067], [                      ], 
                           [  .745378   - .856714 ]
                                        [ - .856714  - .745378 ]
                                        [                      ]]
                                        [  .515792   - .666642 ]
(%i6) D : apply (diag_matrix, L);
                      [ 7.54331     0    ]
(%o6)                 [                  ]
                      [    0     12.4067 ]
(%i7) M . v - v . D;
                [      0.0       - 8.88178E-16 ]
(%o7)           [                              ]
                [ - 8.88178E-16       0.0      ]
(%i8) transpose (u) . M - D . transpose (u);
                     [ 0.0  - 4.44089E-16 ]
(%o8)                [                    ]
                     [ 0.0       0.0      ]

Function: dgeqrf (A)

Computes the QR decomposition of the matrix A. All elements of A must be integer or floating point numbers. A may or may not have the same number of rows and columns.

A list of two items is returned. The first item is the matrix Q, which is a square, orthonormal matrix which has the same number of rows as A. The second item is the matrix R, which is the same size as A, and which has all elements equal to zero below the diagonal. The product Q . R, where "." is the noncommutative multiplication operator, is equal to A (ignoring floating point round-off errors).

(%i1) load ("lapack") $
(%i2) fpprintprec : 6 $
(%i3) M : matrix ([1, -3.2, 8], [-11, 2.7, 5.9]) $
(%i4) [q, r] : dgeqrf (M);
       [ - .0905357  .995893  ]
(%o4) [[                      ], 
       [  .995893    .0905357 ]
                               [ - 11.0454   2.97863   5.15148 ]
                               [                               ]]
                               [     0      - 2.94241  8.50131 ]
(%i5) q . r - M;
         [ - 7.77156E-16   1.77636E-15   - 8.88178E-16 ]
(%o5)    [                                             ]
         [      0.0       - 1.33227E-15   8.88178E-16  ]
(%i6) mat_norm (%, 1);
(%o6)                      3.10862E-15

Category: Package lapack · Category: Linear equations

Function: dgesv (A, b)

Computes the solution x of the linear equation A x = b, where A is a square matrix, and b is a matrix of the same number of rows as A and any number of columns. The return value x is the same size as b.

The elements of A and b must evaluate to real floating point numbers via float; thus elements may be any numeric type, symbolic numerical constants, or expressions which evaluate to floats. The elements of x are always floating point numbers. All arithmetic is carried out as floating point operations.

dgesv computes the solution via the LU decomposition of A.

Examples:

dgesv computes the solution of the linear equation A x = b.

(%i1) A : matrix ([1, -2.5], [0.375, 5]);
                               [   1    - 2.5 ]
(%o1)                          [              ]
                               [ 0.375    5   ]
(%i2) b : matrix ([1.75], [-0.625]);
                                  [  1.75   ]
(%o2)                             [         ]
                                  [ - 0.625 ]
(%i3) x : dgesv (A, b);
                            [  1.210526315789474  ]
(%o3)                       [                     ]
                            [ - 0.215789473684211 ]
(%i4) dlange (inf_norm, b - A.x);
(%o4)                                 0.0

b is a matrix with the same number of rows as A and any number of columns. x is the same size as b.

(%i1) A : matrix ([1, -0.15], [1.82, 2]);
                               [  1    - 0.15 ]
(%o1)                          [              ]
                               [ 1.82    2    ]
(%i2) b : matrix ([3.7, 1, 8], [-2.3, 5, -3.9]);
                              [  3.7   1    8   ]
(%o2)                         [                 ]
                              [ - 2.3  5  - 3.9 ]
(%i3) x : dgesv (A, b);
      [  3.103827540695117  1.20985481742191    6.781786185657722 ]
(%o3) [                                                           ]
      [ -3.974483062032557  1.399032116146062  -8.121425428948527 ]
(%i4) dlange (inf_norm, b - A . x);
(%o4)                       1.1102230246251565E-15

The elements of A and b must evaluate to real floating point numbers.

(%i1) A : matrix ([5, -%pi], [1b0, 11/17]);
                               [   5    - %pi ]
                               [              ]
(%o1)                          [         11   ]
                               [ 1.0b0   --   ]
                               [         17   ]
(%i2) b : matrix ([%e], [sin(1)]);
                                  [   %e   ]
(%o2)                             [        ]
                                  [ sin(1) ]
(%i3) x : dgesv (A, b);
                             [ 0.690375643155986 ]
(%o3)                        [                   ]
                             [ 0.233510982552952 ]
(%i4) dlange (inf_norm, b - A . x);
(%o4)                        2.220446049250313E-16

Function: dgesvd
dgesvd (A)
dgesvd (A, left_p, right_p)

Computes the singular value decomposition (SVD) of a matrix A, comprising the singular values and, optionally, the left and right singular vectors. All elements of A must be integer or floating point numbers. A might or might not be square (same number of rows and columns).

Let m be the number of rows, and n the number of columns of A. The singular value decomposition of A comprises three matrices, U, Sigma, and V^T, such that

A = U . Sigma . V^T

where U is an m-by-m unitary matrix, Sigma is an m-by-n diagonal matrix, and V^T is an n-by-n unitary matrix.

Let sigma[i] be a diagonal element of Sigma, that is, Sigma[i, i] = sigma[i]. The elements sigma[i] are the so-called singular values of A; these are real and nonnegative, and returned in descending order. The first min(m, n) columns of U and V are the left and right singular vectors of A. Note that dgesvd returns the transpose of V, not V itself.

dgesvd(A) computes only the singular values of A. dgesvd(A, left_p, right_p) computes the singular values of A and the left singular vectors when left_p = true and the right singular vectors when right_p = true.

A list of three items is returned. The first item is a list of the singular values. The second item is false or the matrix of left singular vectors. The third item is false or the matrix of right singular vectors.

Example:

(%i1) load ("lapack")$
(%i2) fpprintprec : 6;
(%o2)                           6
(%i3) M: matrix([1, 2, 3], [3.5, 0.5, 8], [-1, 2, -3], [4, 9, 7]);
                        [  1    2    3  ]
                        [               ]
                        [ 3.5  0.5   8  ]
(%o3)                   [               ]
                        [ - 1   2   - 3 ]
                        [               ]
                        [  4    9    7  ]
(%i4) dgesvd (M);
(%o4)      [[14.4744, 6.38637, .452547], false, false]
(%i5) [sigma, U, VT] : dgesvd (M, true, true);
(%o5) [[14.4744, 6.38637, .452547], 
[ - .256731  .00816168   .959029    - .119523 ]
[                                             ]
[ - .526456   .672116   - .206236   - .478091 ]
[                                             ], 
[  .107997   - .532278  - .0708315  - 0.83666 ]
[                                             ]
[ - .803287  - .514659  - .180867    .239046  ]
[ - .374486  - .538209  - .755044 ]
[                                 ]
[  .130623   - .836799   0.5317   ]]
[                                 ]
[ - .917986   .100488    .383672  ]
(%i6) m : length (U);
(%o6)                           4
(%i7) n : length (VT);
(%o7)                           3
(%i8) Sigma:
        genmatrix(lambda ([i, j], if i=j then sigma[i] else 0),
                  m, n);
                  [ 14.4744     0        0    ]
                  [                           ]
                  [    0     6.38637     0    ]
(%o8)             [                           ]
                  [    0        0     .452547 ]
                  [                           ]
                  [    0        0        0    ]
(%i9) U . Sigma . VT - M;
          [  1.11022E-15        0.0       1.77636E-15 ]
          [                                           ]
          [  1.33227E-15    1.66533E-15       0.0     ]
(%o9)     [                                           ]
          [ - 4.44089E-16  - 8.88178E-16  4.44089E-16 ]
          [                                           ]
          [  8.88178E-16    1.77636E-15   8.88178E-16 ]
(%i10) transpose (U) . U;
       [     1.0      5.55112E-17    2.498E-16     2.77556E-17  ]
       [                                                        ]
       [ 5.55112E-17      1.0       5.55112E-17    4.16334E-17  ]
(%o10) [                                                        ]
       [  2.498E-16   5.55112E-17       1.0       - 2.08167E-16 ]
       [                                                        ]
       [ 2.77556E-17  4.16334E-17  - 2.08167E-16       1.0      ]
(%i11) VT . transpose (VT);
          [      1.0           0.0      - 5.55112E-17 ]
          [                                           ]
(%o11)    [      0.0           1.0       5.55112E-17  ]
          [                                           ]
          [ - 5.55112E-17  5.55112E-17       1.0      ]

Function: dlange (norm, A)

Function: zlange (norm, A)

Computes a norm or norm-like function of the matrix A.

max: Compute max(abs(A(i, j))) where i and j range over the rows and columns, respectively, of A. Note that this function is not a proper matrix norm.
one_norm: Compute the L[1] norm of A, that is, the maximum of the sum of the absolute value of elements in each column.
inf_norm: Compute the L[inf] norm of A, that is, the maximum of the sum of the absolute value of elements in each row.
frobenius: Compute the Frobenius norm of A, that is, the square root of the sum of squares of the matrix elements.

Function: dgemm
dgemm (A, B)
dgemm (A, B, options)

Compute the product of two matrices and optionally add the product to a third matrix.

In the simplest form, dgemm(A, B) computes the product of the two real matrices, A and B.

In the second form, dgemm computes the alpha * A * B + beta * C where A, B, C are real matrices of the appropriate sizes and alpha and beta are real numbers. Optionally, A and/or B can be transposed before computing the product. The extra parameters are specifed by optional keyword arguments: The keyword arguments are optional and may be specified in any order. They all take the form key=val. The keyword arguments are:

C: The matrix C that should be added. The default is false, which means no matrix is added.
alpha: The product of A and B is multiplied by this value. The default is 1.
beta: If a matrix C is given, this value multiplies C before it is added. The default value is 0, which implies that C is not added, even if C is given. Hence, be sure to specify a non-zero value for beta.
transpose_a: If true, the transpose of A is used instead of A for the product. The default is false.
transpose_b: If true, the transpose of B is used instead of B for the product. The default is false.

(%i1) load ("lapack")$
(%i2) A : matrix([1,2,3],[4,5,6],[7,8,9]);
                                  [ 1  2  3 ]
                                  [         ]
(%o2)                             [ 4  5  6 ]
                                  [         ]
                                  [ 7  8  9 ]
(%i3) B : matrix([-1,-2,-3],[-4,-5,-6],[-7,-8,-9]);
                               [ - 1  - 2  - 3 ]
                               [               ]
(%o3)                          [ - 4  - 5  - 6 ]
                               [               ]
                               [ - 7  - 8  - 9 ]
(%i4) C : matrix([3,2,1],[6,5,4],[9,8,7]);
                                  [ 3  2  1 ]
                                  [         ]
(%o4)                             [ 6  5  4 ]
                                  [         ]
                                  [ 9  8  7 ]
(%i5) dgemm(A,B);
                         [ - 30.0   - 36.0   - 42.0  ]
                         [                           ]
(%o5)                    [ - 66.0   - 81.0   - 96.0  ]
                         [                           ]
                         [ - 102.0  - 126.0  - 150.0 ]
(%i6) A . B;
                            [ - 30   - 36   - 42  ]
                            [                     ]
(%o6)                       [ - 66   - 81   - 96  ]
                            [                     ]
                            [ - 102  - 126  - 150 ]
(%i7) dgemm(A,B,transpose_a=true);
                         [ - 66.0  - 78.0   - 90.0  ]
                         [                          ]
(%o7)                    [ - 78.0  - 93.0   - 108.0 ]
                         [                          ]
                         [ - 90.0  - 108.0  - 126.0 ]
(%i8) transpose(A) . B;
                           [ - 66  - 78   - 90  ]
                           [                    ]
(%o8)                      [ - 78  - 93   - 108 ]
                           [                    ]
                           [ - 90  - 108  - 126 ]
(%i9) dgemm(A,B,c=C,beta=1);
                         [ - 27.0  - 34.0   - 41.0  ]
                         [                          ]
(%o9)                    [ - 60.0  - 76.0   - 92.0  ]
                         [                          ]
                         [ - 93.0  - 118.0  - 143.0 ]
(%i10) A . B + C;
                            [ - 27  - 34   - 41  ]
                            [                    ]
(%o10)                      [ - 60  - 76   - 92  ]
                            [                    ]
                            [ - 93  - 118  - 143 ]
(%i11) dgemm(A,B,c=C,beta=1, alpha=-1);
                            [ 33.0   38.0   43.0  ]
                            [                     ]
(%o11)                      [ 72.0   86.0   100.0 ]
                            [                     ]
                            [ 111.0  134.0  157.0 ]
(%i12) -A . B + C;
                               [ 33   38   43  ]
                               [               ]
(%o12)                         [ 72   86   100 ]
                               [               ]
                               [ 111  134  157 ]

Function: zgeev
zgeev (A)
zgeev (A, right_p, left_p)

Like dgeev, but the matrix A is complex.

Function: zheev
zheev (A)
zheev (A, eigvec_p)

Like zheev, but the matrix A is assumed to be a square complex Hermitian matrix. If eigvec_p is true, then the eigenvectors of the matrix are also computed.

No check is made that the matrix A is, in fact, Hermitian.

A list of two items is returned, as in dgeev: a list of eigenvalues, and false or the matrix of the eigenvectors.

Category: Differential equations · Category: Share packages · Category: Package lindstedt

67 lbfgs

67.1 Introduction to lbfgs

lbfgs is an implementation of the L-BFGS algorithm [1] to solve unconstrained minimization problems via a limited-memory quasi-Newton (BFGS) algorithm. It is called a limited-memory method because a low-rank approximation of the Hessian matrix inverse is stored instead of the entire Hessian inverse. The program was originally written in Fortran [2] by Jorge Nocedal, incorporating some functions originally written by Jorge J. Moré and David J. Thuente, and translated into Lisp automatically via the program f2cl. The Maxima package lbfgs comprises the translated code plus an interface function which manages some details.

References:

[1] D. Liu and J. Nocedal. "On the limited memory BFGS method for large scale optimization". Mathematical Programming B 45:503–528 (1989)

[2] http://netlib.org/opt/lbfgs_um.shar

Category: Numerical methods · Category: Optimization · Category: Share packages · Category: Package lbfgs

67.2 Functions and Variables for lbfgs

Function: lbfgs
lbfgs (FOM, X, X0, epsilon, iprint)
lbfgs ([FOM, grad] X, X0, epsilon, iprint)

Finds an approximate solution of the unconstrained minimization of the figure of merit FOM over the list of variables X, starting from initial estimates X0, such that norm(grad(FOM)) < epsilon*max(1, norm(X)).

grad, if present, is the gradient of FOM with respect to the variables X. grad may be a list or a function that returns a list, with one element for each element of X. If not present, the gradient is computed automatically by symbolic differentiation. If FOM is a function, the gradient grad must be supplied by the user.

The algorithm applied is a limited-memory quasi-Newton (BFGS) algorithm [1]. It is called a limited-memory method because a low-rank approximation of the Hessian matrix inverse is stored instead of the entire Hessian inverse. Each iteration of the algorithm is a line search, that is, a search along a ray in the variables X, with the search direction computed from the approximate Hessian inverse. The FOM is always decreased by a successful line search. Usually (but not always) the norm of the gradient of FOM also decreases.

iprint controls progress messages printed by lbfgs.

iprint[1]

iprint[1] controls the frequency of progress messages.

iprint[1] < 0: No progress messages.
iprint[1] = 0: Messages at the first and last iterations.
iprint[1] > 0: Print a message every iprint[1] iterations.

iprint[2]

iprint[2] controls the verbosity of progress messages.

iprint[2] = 0: Print out iteration count, number of evaluations of FOM, value of FOM, norm of the gradient of FOM, and step length.
iprint[2] = 1: Same as iprint[2] = 0, plus X0 and the gradient of FOM evaluated at X0.
iprint[2] = 2: Same as iprint[2] = 1, plus values of X at each iteration.
iprint[2] = 3: Same as iprint[2] = 2, plus the gradient of FOM at each iteration.

The columns printed by lbfgs are the following.

I: Number of iterations. It is incremented for each line search.
NFN: Number of evaluations of the figure of merit.
FUNC: Value of the figure of merit at the end of the most recent line search.
GNORM: Norm of the gradient of the figure of merit at the end of the most recent line search.
STEPLENGTH: An internal parameter of the search algorithm.

Additional information concerning details of the algorithm are found in the comments of the original Fortran code [2].

See also lbfgs_nfeval_max and lbfgs_ncorrections.

References:

[1] D. Liu and J. Nocedal. "On the limited memory BFGS method for large scale optimization". Mathematical Programming B 45:503–528 (1989)

[2] http://netlib.org/opt/lbfgs_um.shar

Examples:

The same FOM as computed by FGCOMPUTE in the program sdrive.f in the LBFGS package from Netlib. Note that the variables in question are subscripted variables. The FOM has an exact minimum equal to zero at u[k] = 1 for k = 1, ..., 8.

(%i1) load ("lbfgs")$
(%i2) t1[j] := 1 - u[j];
(%o2)                     t1  := 1 - u
                            j         j
(%i3) t2[j] := 10*(u[j + 1] - u[j]^2);
                                          2
(%o3)                t2  := 10 (u      - u )
                       j         j + 1    j
(%i4) n : 8;
(%o4)                           8
(%i5) FOM : sum (t1[2*j - 1]^2 + t2[2*j - 1]^2, j, 1, n/2);
                 2 2           2              2 2           2
(%o5) 100 (u  - u )  + (1 - u )  + 100 (u  - u )  + (1 - u )
            8    7           7           6    5           5
                     2 2           2              2 2           2
        + 100 (u  - u )  + (1 - u )  + 100 (u  - u )  + (1 - u )
                4    3           3           2    1           1
(%i6) lbfgs (FOM, '[u[1],u[2],u[3],u[4],u[5],u[6],u[7],u[8]],
       [-1.2, 1, -1.2, 1, -1.2, 1, -1.2, 1], 1e-3, [1, 0]);
*************************************************
  N=    8   NUMBER OF CORRECTIONS=25
       INITIAL VALUES
 F=  9.680000000000000D+01   GNORM=  4.657353755084533D+02
*************************************************

 I NFN   FUNC                    GNORM                   STEPLENGTH

 1   3   1.651479526340304D+01   4.324359291335977D+00   7.926153934390631D-04
 2   4   1.650209316638371D+01   3.575788161060007D+00   1.000000000000000D+00
 3   5   1.645461701312851D+01   6.230869903601577D+00   1.000000000000000D+00
 4   6   1.636867301275588D+01   1.177589920974980D+01   1.000000000000000D+00
 5   7   1.612153014409201D+01   2.292797147151288D+01   1.000000000000000D+00
 6   8   1.569118407390628D+01   3.687447158775571D+01   1.000000000000000D+00
 7   9   1.510361958398942D+01   4.501931728123679D+01   1.000000000000000D+00
 8  10   1.391077875774293D+01   4.526061463810630D+01   1.000000000000000D+00
 9  11   1.165625686278198D+01   2.748348965356907D+01   1.000000000000000D+00
10  12   9.859422687859144D+00   2.111494974231706D+01   1.000000000000000D+00
11  13   7.815442521732282D+00   6.110762325764183D+00   1.000000000000000D+00
12  15   7.346380905773044D+00   2.165281166715009D+01   1.285316401779678D-01
13  16   6.330460634066464D+00   1.401220851761508D+01   1.000000000000000D+00
14  17   5.238763939854303D+00   1.702473787619218D+01   1.000000000000000D+00
15  18   3.754016790406625D+00   7.981845727632704D+00   1.000000000000000D+00
16  20   3.001238402313225D+00   3.925482944745832D+00   2.333129631316462D-01
17  22   2.794390709722064D+00   8.243329982586480D+00   2.503577283802312D-01
18  23   2.563783562920545D+00   1.035413426522664D+01   1.000000000000000D+00
19  24   2.019429976373283D+00   1.065187312340952D+01   1.000000000000000D+00
20  25   1.428003167668592D+00   2.475962450735100D+00   1.000000000000000D+00
21  27   1.197874264859232D+00   8.441707983339661D+00   4.303451060697367D-01
22  28   9.023848942003913D-01   1.113189216665625D+01   1.000000000000000D+00
23  29   5.508226405855795D-01   2.380830599637816D+00   1.000000000000000D+00
24  31   3.902893258879521D-01   5.625595817143044D+00   4.834988416747262D-01
25  32   3.207542206881058D-01   1.149444645298493D+01   1.000000000000000D+00
26  33   1.874468266118200D-01   3.632482152347445D+00   1.000000000000000D+00
27  34   9.575763380282112D-02   4.816497449000391D+00   1.000000000000000D+00
28  35   4.085145106760390D-02   2.087009347116811D+00   1.000000000000000D+00
29  36   1.931106005512628D-02   3.886818624052740D+00   1.000000000000000D+00
30  37   6.894000636920714D-03   3.198505769992936D+00   1.000000000000000D+00
31  38   1.443296008850287D-03   1.590265460381961D+00   1.000000000000000D+00
32  39   1.571766574930155D-04   3.098257002223532D-01   1.000000000000000D+00
33  40   1.288011779655132D-05   1.207784334505595D-02   1.000000000000000D+00
34  41   1.806140190993455D-06   4.587890258846915D-02   1.000000000000000D+00
35  42   1.769004612050548D-07   1.790537363138099D-02   1.000000000000000D+00
36  43   3.312164244118216D-10   6.782068546986653D-04   1.000000000000000D+00


 THE MINIMIZATION TERMINATED WITHOUT DETECTING ERRORS.
 IFLAG = 0
(%o6) [u  = 1.000005339816132, u  = 1.000009942840108, 
        1                       2
u  = 1.000005339816132, u  = 1.000009942840108, 
 3                       4
u  = 1.000005339816132, u  = 1.000009942840108, 
 5                       6
u  = 1.000005339816132, u  = 1.000009942840108]
 7                       8

A regression problem. The FOM is the mean square difference between the predicted value F(X[i]) and the observed value Y[i]. The function F is a bounded monotone function (a so-called "sigmoidal" function). In this example, lbfgs computes approximate values for the parameters of F and plot2d displays a comparison of F with the observed data.

(%i1) load ("lbfgs")$
(%i2) FOM : '((1/length(X))*sum((F(X[i]) - Y[i])^2, i, 1,
                                                length(X)));
                               2
               sum((F(X ) - Y ) , i, 1, length(X))
                       i     i
(%o2)          -----------------------------------
                            length(X)
(%i3) X : [1, 2, 3, 4, 5];
(%o3)                    [1, 2, 3, 4, 5]
(%i4) Y : [0, 0.5, 1, 1.25, 1.5];
(%o4)                [0, 0.5, 1, 1.25, 1.5]
(%i5) F(x) := A/(1 + exp(-B*(x - C)));
                                   A
(%o5)            F(x) := ----------------------
                         1 + exp((- B) (x - C))
(%i6) ''FOM;
                A               2            A                2
(%o6) ((----------------- - 1.5)  + (----------------- - 1.25)
          - B (5 - C)                  - B (4 - C)
        %e            + 1            %e            + 1
            A             2            A               2
 + (----------------- - 1)  + (----------------- - 0.5)
      - B (3 - C)                - B (2 - C)
    %e            + 1          %e            + 1
             2
            A
 + --------------------)/5
      - B (1 - C)     2
   (%e            + 1)
(%i7) estimates : lbfgs (FOM, '[A, B, C], [1, 1, 1], 1e-4, [1, 0]);
*************************************************
  N=    3   NUMBER OF CORRECTIONS=25
       INITIAL VALUES
 F=  1.348738534246918D-01   GNORM=  2.000215531936760D-01
*************************************************

I  NFN  FUNC                    GNORM                   STEPLENGTH
1    3  1.177820636622582D-01   9.893138394953992D-02   8.554435968992371D-01  
2    6  2.302653892214013D-02   1.180098521565904D-01   2.100000000000000D+01  
3    8  1.496348495303004D-02   9.611201567691624D-02   5.257340567840710D-01  
4    9  7.900460841091138D-03   1.325041647391314D-02   1.000000000000000D+00  
5   10  7.314495451266914D-03   1.510670810312226D-02   1.000000000000000D+00  
6   11  6.750147275936668D-03   1.914964958023037D-02   1.000000000000000D+00  
7   12  5.850716021108202D-03   1.028089194579382D-02   1.000000000000000D+00  
8   13  5.778664230657800D-03   3.676866074532179D-04   1.000000000000000D+00  
9   14  5.777818823650780D-03   3.010740179797108D-04   1.000000000000000D+00


 THE MINIMIZATION TERMINATED WITHOUT DETECTING ERRORS.
 IFLAG = 0
(%o7) [A = 1.461933911464101, B = 1.601593973254801, 
                                           C = 2.528933072164855]
(%i8) plot2d ([F(x), [discrete, X, Y]], [x, -1, 6]), ''estimates;
(%o8)

Gradient of FOM is specified (instead of computing it automatically). Both the FOM and its gradient are passed as functions to lbfgs.

(%i1) load ("lbfgs")$
(%i2) F(a, b, c) := (a - 5)^2 + (b - 3)^4 + (c - 2)^6$
(%i3) define(F_grad(a, b, c),
             map (lambda ([x], diff (F(a, b, c), x)), [a, b, c]))$
(%i4) estimates : lbfgs ([F, F_grad],
                   [a, b, c], [0, 0, 0], 1e-4, [1, 0]);
*************************************************
  N=    3   NUMBER OF CORRECTIONS=25
       INITIAL VALUES
 F=  1.700000000000000D+02   GNORM=  2.205175729958953D+02
*************************************************

   I  NFN     FUNC                    GNORM                   STEPLENGTH

   1    2     6.632967565917637D+01   6.498411132518770D+01   4.534785987412505D-03  
   2    3     4.368890936228036D+01   3.784147651974131D+01   1.000000000000000D+00  
   3    4     2.685298972775191D+01   1.640262125898520D+01   1.000000000000000D+00  
   4    5     1.909064767659852D+01   9.733664001790506D+00   1.000000000000000D+00  
   5    6     1.006493272061515D+01   6.344808151880209D+00   1.000000000000000D+00  
   6    7     1.215263596054292D+00   2.204727876126877D+00   1.000000000000000D+00  
   7    8     1.080252896385329D-02   1.431637116951845D-01   1.000000000000000D+00  
   8    9     8.407195124830860D-03   1.126344579730008D-01   1.000000000000000D+00  
   9   10     5.022091686198525D-03   7.750731829225275D-02   1.000000000000000D+00  
  10   11     2.277152808939775D-03   5.032810859286796D-02   1.000000000000000D+00  
  11   12     6.489384688303218D-04   1.932007150271009D-02   1.000000000000000D+00  
  12   13     2.075791943844547D-04   6.964319310814365D-03   1.000000000000000D+00  
  13   14     7.349472666162258D-05   4.017449067849554D-03   1.000000000000000D+00  
  14   15     2.293617477985238D-05   1.334590390856715D-03   1.000000000000000D+00  
  15   16     7.683645404048675D-06   6.011057038099202D-04   1.000000000000000D+00


 THE MINIMIZATION TERMINATED WITHOUT DETECTING ERRORS.
 IFLAG = 0
(%o4) [a = 5.000086823042934, b = 3.052395429705181, 
                                           c = 1.927980629919583]

Category: Package lbfgs

Variable: lbfgs_nfeval_max

Default value: 100

lbfgs_nfeval_max is the maximum number of evaluations of the figure of merit (FOM) in lbfgs. When lbfgs_nfeval_max is reached, lbfgs returns the result of the last successful line search.

Category: Package lbfgs

Variable: lbfgs_ncorrections

Default value: 25

lbfgs_ncorrections is the number of corrections applied to the approximate inverse Hessian matrix which is maintained by lbfgs.

Category: Package lbfgs

68 lindstedt

68.1 Functions and Variables for lindstedt

Function: Lindstedt (eq,pvar,torder,ic)

This is a first pass at a Lindstedt code. It can solve problems with initial conditions entered, which can be arbitrary constants, (just not %k1 and %k2) where the initial conditions on the perturbation equations are z[i]=0, z'[i]=0 for i>0. ic is the list of initial conditions.

Problems occur when initial conditions are not given, as the constants in the perturbation equations are the same as the zero order equation solution. Also, problems occur when the initial conditions for the perturbation equations are not z[i]=0, z'[i]=0 for i>0, such as the Van der Pol equation.

Example:

(%i1) load("makeOrders")$

(%i2) load("lindstedt")$

(%i3) Lindstedt('diff(x,t,2)+x-(e*x^3)/6,e,2,[1,0]);
          2
         e  (cos(5 T) - 24 cos(3 T) + 23 cos(T))
(%o3) [[[---------------------------------------
                          36864
   e (cos(3 T) - cos(T))
 - --------------------- + cos(T)],
            192
          2
       7 e    e
T = (- ---- - -- + 1) t]]
       3072   16

To use this function write first load("makeOrders") and load("lindstedt").

69 linearalgebra

69.1 Introduction to linearalgebra

linearalgebra is a collection of functions for linear algebra.

Example:

(%i1) M : matrix ([1, 2], [1, 2]);
                            [ 1  2 ]
(%o1)                       [      ]
                            [ 1  2 ]
(%i2) nullspace (M);
                               [  1  ]
                               [     ]
(%o2)                     span([   1 ])
                               [ - - ]
                               [   2 ]
(%i3) columnspace (M);
                                [ 1 ]
(%o3)                      span([   ])
                                [ 1 ]
(%i4) ptriangularize (M - z*ident(2), z);
                         [ 1   2 - z   ]
(%o4)                    [             ]
                         [           2 ]
                         [ 0  3 z - z  ]
(%i5) M : matrix ([1, 2, 3], [4, 5, 6], [7, 8, 9]) - z*ident(3);
                     [ 1 - z    2      3   ]
                     [                     ]
(%o5)                [   4    5 - z    6   ]
                     [                     ]
                     [   7      8    9 - z ]
(%i6) MM : ptriangularize (M, z);
              [ 4  5 - z            6            ]
              [                                  ]
              [                2                 ]
              [     66        z    102 z   132   ]
              [ 0   --      - -- + ----- + ---   ]
(%o6)         [     49        7     49     49    ]
              [                                  ]
              [               3        2         ]
              [           49 z    245 z    147 z ]
              [ 0    0    ----- - ------ - ----- ]
              [            264      88      44   ]
(%i7) algebraic : true;
(%o7)                         true
(%i8) tellrat (MM [3, 3]);
                         3       2
(%o8)                  [z  - 15 z  - 18 z]
(%i9) MM : ratsimp (MM);
               [ 4  5 - z           6           ]
               [                                ]
               [                2               ]
(%o9)          [     66      7 z  - 102 z - 132 ]
               [ 0   --    - ------------------ ]
               [     49              49         ]
               [                                ]
               [ 0    0             0           ]
(%i10) nullspace (MM);
                        [        1         ]
                        [                  ]
                        [   2              ]
                        [  z  - 14 z - 16  ]
                        [  --------------  ]
(%o10)             span([        8         ])
                        [                  ]
                        [    2             ]
                        [   z  - 18 z - 12 ]
                        [ - -------------- ]
                        [         12       ]
(%i11) M : matrix ([1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12],
                   [13, 14, 15, 16]);
                       [ 1   2   3   4  ]
                       [                ]
                       [ 5   6   7   8  ]
(%o11)                 [                ]
                       [ 9   10  11  12 ]
                       [                ]
                       [ 13  14  15  16 ]
(%i12) columnspace (M);
                           [ 1  ]  [ 2  ]
                           [    ]  [    ]
                           [ 5  ]  [ 6  ]
(%o12)                span([    ], [    ])
                           [ 9  ]  [ 10 ]
                           [    ]  [    ]
                           [ 13 ]  [ 14 ]
(%i13) apply ('orthogonal_complement, args (nullspace (transpose (M))));
                           [ 0 ]  [  1  ]
                           [   ]  [     ]
                           [ 1 ]  [  0  ]
(%o13)                span([   ], [     ])
                           [ 2 ]  [ - 1 ]
                           [   ]  [     ]
                           [ 3 ]  [ - 2 ]

Category: Linear algebra · Category: Share packages · Category: Package linearalgebra

69.2 Functions and Variables for linearalgebra

Function: addmatrices (f, M_1, …, M_n)

Using the function f as the addition function, return the sum of the matrices M_1, …, M_n. The function f must accept any number of arguments (a Maxima nary function).

Examples:

(%i1) m1 : matrix([1,2],[3,4])$
(%i2) m2 : matrix([7,8],[9,10])$
(%i3) addmatrices('max,m1,m2);
(%o3) matrix([7,8],[9,10])
(%i4) addmatrices('max,m1,m2,5*m1);
(%o4) matrix([7,10],[15,20])

Category: Package linearalgebra · Category: Predicate functions

Function: blockmatrixp (M)

Return true if and only if M is a matrix and every entry of M is a matrix.

Function: columnop (M, i, j, theta)

If M is a matrix, return the matrix that results from doing the column operation C_i <- C_i - theta * C_j. If M doesn’t have a row i or j, signal an error.

Function: columnswap (M, i, j)

If M is a matrix, swap columns i and j. If M doesn’t have a column i or j, signal an error.

Function: columnspace (M)

If M is a matrix, return span (v_1, ..., v_n), where the set {v_1, ..., v_n} is a basis for the column space of M. The span of the empty set is {0}. Thus, when the column space has only one member, return span ().

Category: Matrix decompositions · Category: Package linearalgebra

Function: cholesky
cholesky (M)
cholesky (M, field)

Return the Cholesky factorization of the matrix selfadjoint (or hermitian) matrix M. The second argument defaults to ’generalring.’ For a description of the possible values for field, see lu_factor.

Function: ctranspose (M)

Return the complex conjugate transpose of the matrix M. The function ctranspose uses matrix_element_transpose to transpose each matrix element.

Function: diag_matrix (d_1, d_2, …, d_n)

Return a diagonal matrix with diagonal entries d_1, d_2, …, d_n. When the diagonal entries are matrices, the zero entries of the returned matrix are zero matrices of the appropriate size; for example:

(%i1) diag_matrix(diag_matrix(1,2),diag_matrix(3,4));

                            [ [ 1  0 ]  [ 0  0 ] ]
                            [ [      ]  [      ] ]
                            [ [ 0  2 ]  [ 0  0 ] ]
(%o1)                       [                    ]
                            [ [ 0  0 ]  [ 3  0 ] ]
                            [ [      ]  [      ] ]
                            [ [ 0  0 ]  [ 0  4 ] ]
(%i2) diag_matrix(p,q);

                                   [ p  0 ]
(%o2)                              [      ]
                                   [ 0  q ]

Function: dotproduct (u, v)

Return the dotproduct of vectors u and v. This is the same as conjugate (transpose (u)) . v. The arguments u and v must be column vectors.

Category: Matrix decompositions · Category: Package linearalgebra

Function: eigens_by_jacobi
eigens_by_jacobi (A)
eigens_by_jacobi (A, field_type)

Computes the eigenvalues and eigenvectors of A by the method of Jacobi rotations. A must be a symmetric matrix (but it need not be positive definite nor positive semidefinite). field_type indicates the computational field, either floatfield or bigfloatfield. If field_type is not specified, it defaults to floatfield.

The elements of A must be numbers or expressions which evaluate to numbers via float or bfloat (depending on field_type).

Examples:

(%i1) S: matrix([1/sqrt(2), 1/sqrt(2)],[-1/sqrt(2), 1/sqrt(2)]);
                     [     1         1    ]
                     [  -------   ------- ]
                     [  sqrt(2)   sqrt(2) ]
(%o1)                [                    ]
                     [      1        1    ]
                     [ - -------  ------- ]
                     [   sqrt(2)  sqrt(2) ]
(%i2) L : matrix ([sqrt(3), 0], [0, sqrt(5)]);
                      [ sqrt(3)     0    ]
(%o2)                 [                  ]
                      [    0     sqrt(5) ]
(%i3) M : S . L . transpose (S);
            [ sqrt(5)   sqrt(3)  sqrt(5)   sqrt(3) ]
            [ ------- + -------  ------- - ------- ]
            [    2         2        2         2    ]
(%o3)       [                                      ]
            [ sqrt(5)   sqrt(3)  sqrt(5)   sqrt(3) ]
            [ ------- - -------  ------- + ------- ]
            [    2         2        2         2    ]
(%i4) eigens_by_jacobi (M);
The largest percent change was 0.1454972243679
The largest percent change was 0.0
number of sweeps: 2
number of rotations: 1
(%o4) [[1.732050807568877, 2.23606797749979], 
                        [  0.70710678118655   0.70710678118655 ]
                        [                                      ]]
                        [ - 0.70710678118655  0.70710678118655 ]
(%i5) float ([[sqrt(3), sqrt(5)], S]);
(%o5) [[1.732050807568877, 2.23606797749979], 
                        [  0.70710678118655   0.70710678118655 ]
                        [                                      ]]
                        [ - 0.70710678118655  0.70710678118655 ]
(%i6) eigens_by_jacobi (M, bigfloatfield);
The largest percent change was 1.454972243679028b-1
The largest percent change was 0.0b0
number of sweeps: 2
number of rotations: 1
(%o6) [[1.732050807568877b0, 2.23606797749979b0], 
                [  7.071067811865475b-1   7.071067811865475b-1 ]
                [                                              ]]
                [ - 7.071067811865475b-1  7.071067811865475b-1 ]

Function: get_lu_factors (x)

When x = lu_factor (A), then get_lu_factors returns a list of the form [P, L, U], where P is a permutation matrix, L is lower triangular with ones on the diagonal, and U is upper triangular, and A = P L U.

Function: hankel
hankel (col)
hankel (col, row)

Return a Hankel matrix H. The first column of H is col; except for the first entry, the last row of H is row. The default for row is the zero vector with the same length as col.

Category: Differential calculus · Category: Package linearalgebra

Function: hessian (f, x)

Returns the Hessian matrix of f with respect to the list of variables x. The (i, j)-th element of the Hessian matrix is diff(f, x[i], 1, x[j], 1).

Examples:

(%i1) hessian (x * sin (y), [x, y]);
                     [   0       cos(y)   ]
(%o1)                [                    ]
                     [ cos(y)  - x sin(y) ]
(%i2) depends (F, [a, b]);
(%o2)                       [F(a, b)]
(%i3) hessian (F, [a, b]);
                        [   2      2   ]
                        [  d F    d F  ]
                        [  ---   ----- ]
                        [    2   da db ]
                        [  da          ]
(%o3)                   [              ]
                        [   2      2   ]
                        [  d F    d F  ]
                        [ -----   ---  ]
                        [ da db     2  ]
                        [         db   ]

Function: hilbert_matrix (n)

Return the n by n Hilbert matrix. When n isn’t a positive integer, signal an error.

Category: Statistical estimation · Category: Share packages · Category: Package lsquares

Function: identfor
identfor (M)
identfor (M, fld)

Return an identity matrix that has the same shape as the matrix M. The diagonal entries of the identity matrix are the multiplicative identity of the field fld; the default for fld is generalring.

The first argument M should be a square matrix or a non-matrix. When M is a matrix, each entry of M can be a square matrix – thus M can be a blocked Maxima matrix. The matrix can be blocked to any (finite) depth.

70 lsquares

70.1 Introduction to lsquares

lsquares is a collection of functions to implement the method of least squares to estimate parameters for a model from numerical data.

70.2 Functions and Variables for lsquares

Function: lsquares_estimates
lsquares_estimates (D, x, e, a)
lsquares_estimates (D, x, e, a, initial = L, tol = t)

Estimate parameters a to best fit the equation e in the variables x and a to the data D, as determined by the method of least squares. lsquares_estimates first seeks an exact solution, and if that fails, then seeks an approximate solution.

The return value is a list of lists of equations of the form [a = ..., b = ..., c = ...]. Each element of the list is a distinct, equivalent minimum of the mean square error.

The data D must be a matrix. Each row is one datum (which may be called a ‘record’ or ‘case’ in some contexts), and each column contains the values of one variable across all data. The list of variables x gives a name for each column of D, even the columns which do not enter the analysis. The list of parameters a gives the names of the parameters for which estimates are sought. The equation e is an expression or equation in the variables x and a; if e is not an equation, it is treated the same as e = 0.

Additional arguments to lsquares_estimates are specified as equations and passed on verbatim to the function lbfgs which is called to find estimates by a numerical method when an exact result is not found.

If some exact solution can be found (via solve), the data D may contain non-numeric values. However, if no exact solution is found, each element of D must have a numeric value. This includes numeric constants such as %pi and %e as well as literal numbers (integers, rationals, ordinary floats, and bigfloats). Numerical calculations are carried out with ordinary floating-point arithmetic, so all other kinds of numbers are converted to ordinary floats for calculations.

If lsquares_estimates needs excessive amounts of time or runs out of memory lsquares_estimates_approximate, which skips the attempt to find an exact solution, might still succeed.

load(lsquares) loads this function.

Examples:

A problem for which an exact solution is found.

(%i1) load ("lsquares")$
(%i2) M : matrix (
        [1,1,1], [3/2,1,2], [9/4,2,1], [3,2,2], [2,2,1]);
                           [ 1  1  1 ]
                           [         ]
                           [ 3       ]
                           [ -  1  2 ]
                           [ 2       ]
                           [         ]
(%o2)                      [ 9       ]
                           [ -  2  1 ]
                           [ 4       ]
                           [         ]
                           [ 3  2  2 ]
                           [         ]
                           [ 2  2  1 ]

(%i3) lsquares_estimates (
         M, [z,x,y], (z+D)^2 = A*x+B*y+C, [A,B,C,D]);
                  59        27      10921        107
(%o3)     [[A = - --, B = - --, C = -----, D = - ---]]
                  16        16      1024         32

A problem for which no exact solution is found, so lsquares_estimates resorts to numerical approximation.

(%i1) load ("lsquares")$
(%i2) M : matrix ([1, 1], [2, 7/4], [3, 11/4], [4, 13/4]);
                            [ 1  1  ]
                            [       ]
                            [    7  ]
                            [ 2  -  ]
                            [    4  ]
                            [       ]
(%o2)                       [    11 ]
                            [ 3  -- ]
                            [    4  ]
                            [       ]
                            [    13 ]
                            [ 4  -- ]
                            [    4  ]

(%i3) lsquares_estimates (
  M, [x,y], y=a*x^b+c, [a,b,c], initial=[3,3,3], iprint=[-1,0]);
(%o3) [[a = 1.375751433061394, b = 0.7148891534417651, 
                                       c = - 0.4020908910062951]]

Exponential functions aren’t well-conditioned for least min square fitting. In case that fitting to them fails it might be possible to get rid of the exponential function using an logarithm.

(%i1) load ("lsquares")$
(%i2) yvalues:[1,3,5,60,200,203,80]$
(%i3) time:[1,2,4,5,6,8,10]$

(%i4) f:y=a*exp(b*t);
                                   b t
(%o4)                      y = a %e

(%i5) yvalues_log:log(yvalues)$

(%i6) f_log:log(subst(y=exp(y),f));
                                    b t
(%o6)                   y = log(a %e   )

(%i7) lsquares_estimates(
    transpose(matrix(yvalues_log,time)),
    [y,t],
    f_log,
    [a,b]
 );
*************************************************
  N=    2   NUMBER OF CORRECTIONS=25
       INITIAL VALUES
 F=  6.802906290754687D+00   GNORM=  2.851243373781393D+01
*************************************************

   I  NFN     FUNC                    GNORM                   STEPLENGTH

   1    3     1.141838765593467D+00   1.067358003667488D-01   1.390943719972406D-02  
   2    5     1.141118195694385D+00   1.237977833033414D-01   5.000000000000000D+00  
   3    6     1.136945723147959D+00   3.806696991691383D-01   1.000000000000000D+00  
   4    7     1.133958243220262D+00   3.865103550379243D-01   1.000000000000000D+00  
   5    8     1.131725773805499D+00   2.292258231154026D-02   1.000000000000000D+00  
   6    9     1.131625585698168D+00   2.664440547017370D-03   1.000000000000000D+00  
   7   10     1.131620564856599D+00   2.519366958715444D-04   1.000000000000000D+00  

 THE MINIMIZATION TERMINATED WITHOUT DETECTING ERRORS.
 IFLAG = 0
(%o7)   [[a = 1.155904145765554, b = 0.5772666876959847]]

Category: Package lsquares · Category: Numerical methods

Function: lsquares_estimates_exact (MSE, a)

Estimate parameters a to minimize the mean square error MSE, by constructing a system of equations and attempting to solve them symbolically via solve. The mean square error is an expression in the parameters a, such as that returned by lsquares_mse.

The return value is a list of lists of equations of the form [a = ..., b = ..., c = ...]. The return value may contain zero, one, or two or more elements. If two or more elements are returned, each represents a distinct, equivalent minimum of the mean square error.

Example:

(%i1) load ("lsquares")$
(%i2) M : matrix (
         [1,1,1], [3/2,1,2], [9/4,2,1], [3,2,2], [2,2,1]);
                           [ 1  1  1 ]
                           [         ]
                           [ 3       ]
                           [ -  1  2 ]
                           [ 2       ]
                           [         ]
(%o2)                      [ 9       ]
                           [ -  2  1 ]
                           [ 4       ]
                           [         ]
                           [ 3  2  2 ]
                           [         ]
                           [ 2  2  1 ]
(%i3) mse : lsquares_mse (M, [z, x, y], (z + D)^2 = A*x + B*y + C);
         5
        ====
        \                                         2     2
         >    ((- B M    ) - A M     + (M     + D)  - C)
        /            i, 3       i, 2     i, 1
        ====
        i = 1
(%o3)   -------------------------------------------------
                                5

(%i4) lsquares_estimates_exact (mse, [A, B, C, D]);
                  59        27      10921        107
(%o4)     [[A = - --, B = - --, C = -----, D = - ---]]
                  16        16      1024         32

Category: Package lsquares · Category: Numerical methods

Function: lsquares_estimates_approximate (MSE, a, initial = L, tol = t)

Estimate parameters a to minimize the mean square error MSE, via the numerical minimization function lbfgs. The mean square error is an expression in the parameters a, such as that returned by lsquares_mse.

The solution returned by lsquares_estimates_approximate is a local (perhaps global) minimum of the mean square error. For consistency with lsquares_estimates_exact, the return value is a nested list which contains one element, namely a list of equations of the form [a = ..., b = ..., c = ...].

Additional arguments to lsquares_estimates_approximate are specified as equations and passed on verbatim to the function lbfgs.

MSE must evaluate to a number when the parameters are assigned numeric values. This requires that the data from which MSE was constructed comprise only numeric constants such as %pi and %e and literal numbers (integers, rationals, ordinary floats, and bigfloats). Numerical calculations are carried out with ordinary floating-point arithmetic, so all other kinds of numbers are converted to ordinary floats for calculations.

load(lsquares) loads this function.

Example:

(%i1) load ("lsquares")$
(%i2) M : matrix (
         [1,1,1], [3/2,1,2], [9/4,2,1], [3,2,2], [2,2,1]);
                           [ 1  1  1 ]
                           [         ]
                           [ 3       ]
                           [ -  1  2 ]
                           [ 2       ]
                           [         ]
(%o2)                      [ 9       ]
                           [ -  2  1 ]
                           [ 4       ]
                           [         ]
                           [ 3  2  2 ]
                           [         ]
                           [ 2  2  1 ]
(%i3) mse : lsquares_mse (M, [z, x, y], (z + D)^2 = A*x + B*y + C);
         5
        ====
        \                                         2     2
         >    ((- B M    ) - A M     + (M     + D)  - C)
        /            i, 3       i, 2     i, 1
        ====
        i = 1
(%o3)   -------------------------------------------------
                                5

(%i4) lsquares_estimates_approximate (
        mse, [A, B, C, D], iprint = [-1, 0]);
(%o4) [[A = - 3.678504947401971, B = - 1.683070351177937, 
                 C = 10.63469950148714, D = - 3.340357993175297]]

Function: lsquares_mse (D, x, e)

Returns the mean square error (MSE), a summation expression, for the equation e in the variables x, with data D.

The MSE is defined as:

                    n
                   ====
               1   \                        2
               -    >    (lhs(e ) - rhs(e ))
               n   /           i         i
                   ====
                   i = 1

where n is the number of data and e[i] is the equation e evaluated with the variables in x assigned values from the i-th datum, D[i].

load(lsquares) loads this function.

Example:

(%i1) load ("lsquares")$
(%i2) M : matrix (
         [1,1,1], [3/2,1,2], [9/4,2,1], [3,2,2], [2,2,1]);
                           [ 1  1  1 ]
                           [         ]
                           [ 3       ]
                           [ -  1  2 ]
                           [ 2       ]
                           [         ]
(%o2)                      [ 9       ]
                           [ -  2  1 ]
                           [ 4       ]
                           [         ]
                           [ 3  2  2 ]
                           [         ]
                           [ 2  2  1 ]
(%i3) mse : lsquares_mse (M, [z, x, y], (z + D)^2 = A*x + B*y + C);
         5
        ====
        \                                         2     2
         >    ((- B M    ) - A M     + (M     + D)  - C)
        /            i, 3       i, 2     i, 1
        ====
        i = 1
(%o3)   -------------------------------------------------
                                5
(%i4) diff (mse, D);
(%o4) 
      5
     ====
     \                                                     2
   4  >    (M     + D) ((- B M    ) - A M     + (M     + D)  - C)
     /       i, 1             i, 3       i, 2     i, 1
     ====
     i = 1
   --------------------------------------------------------------
                                 5

(%i5) ''mse, nouns;
               2                 2         9 2               2
(%o5) (((D + 3)  - C - 2 B - 2 A)  + ((D + -)  - C - B - 2 A)
                                           4
           2               2         3 2               2
 + ((D + 2)  - C - B - 2 A)  + ((D + -)  - C - 2 B - A)
                                     2
           2             2
 + ((D + 1)  - C - B - A) )/5

(%i3) mse : lsquares_mse (M, [z, x, y], (z + D)^2 = A*x + B*y + C);
           5
          ====
          \                 2                         2
           >    ((D + M    )  - C - M     B - M     A)
          /            i, 1          i, 3      i, 2
          ====
          i = 1
(%o3)     ---------------------------------------------
                                5

(%i4) diff (mse, D);
         5
        ====
        \                             2
      4  >    (D + M    ) ((D + M    )  - C - M     B - M     A)
        /           i, 1         i, 1          i, 3      i, 2
        ====
        i = 1
(%o4) ----------------------------------------------------------
                                  5

(%i5) ''mse, nouns;

               2                 2         9 2               2
(%o5) (((D + 3)  - C - 2 B - 2 A)  + ((D + -)  - C - B - 2 A)
                                           4
           2               2         3 2               2
 + ((D + 2)  - C - B - 2 A)  + ((D + -)  - C - 2 B - A)
                                     2
           2             2
 + ((D + 1)  - C - B - A) )/5

Function: lsquares_residuals (D, x, e, a)

Returns the residuals for the equation e with specified parameters a and data D.

D is a matrix, x is a list of variables, e is an equation or general expression; if not an equation, e is treated as if it were e = 0. a is a list of equations which specify values for any free parameters in e aside from x.

The residuals are defined as:

                        lhs(e ) - rhs(e )
                             i         i

where e[i] is the equation e evaluated with the variables in x assigned values from the i-th datum, D[i], and assigning any remaining free variables from a.

load(lsquares) loads this function.

Example:

(%i1) load ("lsquares")$
(%i2) M : matrix (
         [1,1,1], [3/2,1,2], [9/4,2,1], [3,2,2], [2,2,1]);
                           [ 1  1  1 ]
                           [         ]
                           [ 3       ]
                           [ -  1  2 ]
                           [ 2       ]
                           [         ]
(%o2)                      [ 9       ]
                           [ -  2  1 ]
                           [ 4       ]
                           [         ]
                           [ 3  2  2 ]
                           [         ]
                           [ 2  2  1 ]

(%i3) a : lsquares_estimates (
          M, [z,x,y], (z+D)^2 = A*x+B*y+C, [A,B,C,D]);
                  59        27      10921        107
(%o3)     [[A = - --, B = - --, C = -----, D = - ---]]
                  16        16      1024         32

(%i4) lsquares_residuals (
          M, [z,x,y], (z+D)^2 = A*x+B*y+C, first(a));
                     13    13    13  13  13
(%o4)               [--, - --, - --, --, --]
                     64    64    32  64  64

Function: lsquares_residual_mse (D, x, e, a)

Returns the residual mean square error (MSE) for the equation e with specified parameters a and data D.

The residual MSE is defined as:

                    n
                   ====
               1   \                        2
               -    >    (lhs(e ) - rhs(e ))
               n   /           i         i
                   ====
                   i = 1

where e[i] is the equation e evaluated with the variables in x assigned values from the i-th datum, D[i], and assigning any remaining free variables from a.

load(lsquares) loads this function.

Example:

(%i1) load ("lsquares")$
(%i2) M : matrix (
         [1,1,1], [3/2,1,2], [9/4,2,1], [3,2,2], [2,2,1]);
                           [ 1  1  1 ]
                           [         ]
                           [ 3       ]
                           [ -  1  2 ]
                           [ 2       ]
                           [         ]
(%o2)                      [ 9       ]
                           [ -  2  1 ]
                           [ 4       ]
                           [         ]
                           [ 3  2  2 ]
                           [         ]
                           [ 2  2  1 ]

(%i3) a : lsquares_estimates (
       M, [z,x,y], (z+D)^2 = A*x+B*y+C, [A,B,C,D]);
                  59        27      10921        107
(%o3)     [[A = - --, B = - --, C = -----, D = - ---]]
                  16        16      1024         32

(%i4) lsquares_residual_mse (
       M, [z,x,y], (z + D)^2 = A*x + B*y + C, first (a));
                              169
(%o4)                         ----
                              2560

Category: Package lsquares · Category: Numerical methods

Function: plsquares
    plsquares (Mat,VarList,depvars)
    plsquares (Mat,VarList,depvars,maxexpon)
    plsquares (Mat,VarList,depvars,maxexpon,maxdegree)

Multivariable polynomial adjustment of a data table by the "least squares" method. Mat is a matrix containing the data, VarList is a list of variable names (one for each Mat column, but use "-" instead of varnames to ignore Mat columns), depvars is the name of a dependent variable or a list with one or more names of dependent variables (which names should be in VarList), maxexpon is the optional maximum exponent for each independent variable (1 by default), and maxdegree is the optional maximum polynomial degree (maxexpon by default); note that the sum of exponents of each term must be equal or smaller than maxdegree, and if maxdgree = 0 then no limit is applied.

If depvars is the name of a dependent variable (not in a list), plsquares returns the adjusted polynomial. If depvars is a list of one or more dependent variables, plsquares returns a list with the adjusted polynomial(s). The Coefficients of Determination are displayed in order to inform about the goodness of fit, which ranges from 0 (no correlation) to 1 (exact correlation). These values are also stored in the global variable DETCOEF (a list if depvars is a list).

A simple example of multivariable linear adjustment:

(%i1) load("plsquares")$

(%i2) plsquares(matrix([1,2,0],[3,5,4],[4,7,9],[5,8,10]),
                [x,y,z],z);
     Determination Coefficient for z = .9897039897039897
                       11 y - 9 x - 14
(%o2)              z = ---------------
                              3

The same example without degree restrictions:

(%i3) plsquares(matrix([1,2,0],[3,5,4],[4,7,9],[5,8,10]),
                [x,y,z],z,1,0);
     Determination Coefficient for z = 1.0
                    x y + 23 y - 29 x - 19
(%o3)           z = ----------------------
                              6

How many diagonals does a N-sides polygon have? What polynomial degree should be used?

(%i4) plsquares(matrix([3,0],[4,2],[5,5],[6,9],[7,14],[8,20]),
                [N,diagonals],diagonals,5);
     Determination Coefficient for diagonals = 1.0
                                2
                               N  - 3 N
(%o4)              diagonals = --------
                                  2
(%i5) ev(%, N=9);   /* Testing for a 9 sides polygon */
(%o5)                 diagonals = 27

How many ways do we have to put two queens without they are threatened into a n x n chessboard?

(%i6) plsquares(matrix([0,0],[1,0],[2,0],[3,8],[4,44]),
                [n,positions],[positions],4);
     Determination Coefficient for [positions] = [1.0]

                         4       3      2
                      3 n  - 10 n  + 9 n  - 2 n
(%o6)    [positions = -------------------------]
                                  6

(%i7) ev(%[1], n=8); /* Testing for a (8 x 8) chessboard */
(%o7)                positions = 1288

An example with six dependent variables:

(%i8) mtrx:matrix([0,0,0,0,0,1,1,1],[0,1,0,1,1,1,0,0],
                  [1,0,0,1,1,1,0,0],[1,1,1,1,0,0,0,1])$
(%i8) plsquares(mtrx,[a,b,_And,_Or,_Xor,_Nand,_Nor,_Nxor],
                     [_And,_Or,_Xor,_Nand,_Nor,_Nxor],1,0);
      Determination Coefficient for
[_And, _Or, _Xor, _Nand, _Nor, _Nxor] =
[1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
(%o2) [_And = a b, _Or = - a b + b + a,
_Xor = - 2 a b + b + a, _Nand = 1 - a b,
_Nor = a b - b - a + 1, _Nxor = 2 a b - b - a + 1]

To use this function write first load("lsquares").

71 minpack

71.1 Introduction to minpack

Minpack is a Common Lisp translation (via f2cl) of the Fortran library MINPACK, as obtained from Netlib.

Category: Numerical methods · Category: Optimization · Category: Share packages · Category: Package minpack

71.2 Functions and Variables for minpack

Function: minpack_lsquares (flist, varlist, guess [, tolerance, jacobian])

Compute the point that minimizes the sum of the squares of the functions in the list flist. The variables are in the list varlist. An initial guess of the optimum point must be provided in guess.

The optional keyword arguments, tolerance and jacobian provide some control over the algorithm. tolerance is the estimated relative error desired in the sum of squares. jacobian can be used to specify the Jacobian. If jacobian is not given or is true (the default), the Jacobian is computed from flist. If jacobian is false, a numerical approximation is used.

minpack_lsquares returns a list. The first item is the estimated solution; the second is the sum of squares, and the third indicates the success of the algorithm. The possible values are

0: improper input parameters.
1: algorithm estimates that the relative error in the sum of squares is at most tolerance.
2: algorithm estimates that the relative error between x and the solution is at most tolerance.
3: conditions for info = 1 and info = 2 both hold.
4: fvec is orthogonal to the columns of the jacobian to machine precision.
5: number of calls to fcn with iflag = 1 has reached 100*(n+1).
6: tol is too small. no further reduction in the sum of squares is possible.
7: tol is too small. no further improvement in the approximate solution x is possible.

/* Problem 6: Powell singular function */
(%i1) powell(x1,x2,x3,x4) := 
         [x1+10*x2, sqrt(5)*(x3-x4), (x2-2*x3)^2, 
              sqrt(10)*(x1-x4)^2]$
(%i2) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4], 
                       [3,-1,0,1]);
(%o2) [[1.652117596168394e-17, - 1.652117596168393e-18, 
        2.643388153869468e-18, 2.643388153869468e-18], 
       6.109327859207777e-34, 4]

/* Same problem but use numerical approximation to Jacobian */
(%i3) minpack_lsquares(powell(x1,x2,x3,x4), [x1,x2,x3,x4], 
                       [3,-1,0,1], jacobian = false);
(%o3) [[5.060282149485331e-11, - 5.060282149491206e-12, 
        2.179447843547218e-11, 2.179447843547218e-11], 
       3.534491794847031e-21, 5]

Function: minpack_solve (flist, varlist, guess [, tolerance, jacobian])

Solve a system of n equations in n unknowns. The n equations are given in the list flist, and the unknowns are in varlist. An initial guess of the solution must be provided in guess.

minpack_solve returns a list. The first item is the estimated solution; the second is the sum of squares, and the third indicates the success of the algorithm. The possible values are

0: improper input parameters.
1: algorithm estimates that the relative error in the solution is at most tolerance.
2: number of calls to fcn with iflag = 1 has reached 100*(n+1).
3: tol is too small. no further reduction in the sum of squares is possible.
4: Iteration is not making good progress.

72 makeOrders

72.1 Functions and Variables for makeOrders

Function: makeOrders (indvarlist,orderlist)

Returns a list of all powers for a polynomial up to and including the arguments.

(%i1) load("makeOrders")$

(%i2) makeOrders([a,b],[2,3]);
(%o2) [[0, 0], [0, 1], [0, 2], [0, 3], [1, 0], [1, 1],
            [1, 2], [1, 3], [2, 0], [2, 1], [2, 2], [2, 3]]
(%i3) expand((1+a+a^2)*(1+b+b^2+b^3));
       2  3      3    3    2  2      2    2    2
(%o3) a  b  + a b  + b  + a  b  + a b  + b  + a  b + a b
                                                  2
                                           + b + a  + a + 1

where [0, 1] is associated with the term b and [2, 3] with a^2 b^3.

To use this function write first load("makeOrders").

Category: Polynomials · Category: Share packages · Category: Package makeOrders

73 mnewton

73.1 Introduction to mnewton

mnewton is an implementation of Newton’s method for solving nonlinear equations in one or more variables.

Category: Numerical methods · Category: Share packages · Category: Package mnewton

73.2 Functions and Variables for mnewton

Option variable: newtonepsilon

Default value: 10.0^(-fpprec/2)

Precision to determine when the mnewton function has converged towards the solution. If newtonepsilon is a bigfloat, then mnewton computations are done with bigfloats. See also mnewton.

Category: Package mnewton

Option variable: newtonmaxiter

Default value: 50

Maximum number of iterations to stop the mnewton function if it does not converge or if it converges too slowly.

74 numericalio

74.1 Introduction to numericalio

numericalio is a collection of functions to read and write files and streams. Functions for plain-text input and output can read and write numbers (integer, float, or bigfloat), symbols, and strings. Functions for binary input and output can read and write only floating-point numbers.

If there already exists a list, matrix, or array object to store input data, numericalio input functions can write data into that object. Otherwise, numericalio can guess, to some degree, the structure of an object to store the data, and return that object.

Category: File input · Category: File output · Category: Share packages · Category: Package numericalio

74.1.1 Plain-text input and output

In plain-text input and output, it is assumed that each item to read or write is an atom: an integer, float, bigfloat, string, or symbol, and not a rational or complex number or any other kind of nonatomic expression. The numericalio functions may attempt to do something sensible faced with nonatomic expressions, but the results are not specified here and subject to change.

Atoms in both input and output files have the same format as in Maxima batch files or the interactive console. In particular, strings are enclosed in double quotes, backslash \ prevents any special interpretation of the next character, and the question mark ? is recognized at the beginning of a symbol to mean a Lisp symbol (as opposed to a Maxima symbol). No continuation character (to join broken lines) is recognized.

74.1.2 Separator flag values for input

The functions for plain-text input and output take an optional argument, separator_flag, that tells what character separates data.

For plain-text input, these values of separator_flag are recognized: comma for comma separated values, pipe for values separated by the vertical bar character |, semicolon for values separated by semicolon ;, and space for values separated by space or tab characters. If the file name ends in .csv and separator_flag is not specified, comma is assumed. If the file name ends in something other than .csv and separator_flag is not specified, space is assumed.

In plain-text input, multiple successive space and tab characters count as a single separator. However, multiple comma, pipe, or semicolon characters are significant. Successive comma, pipe, or semicolon characters (with or without intervening spaces or tabs) are considered to have false between the separators. For example, 1234,,Foo is treated the same as 1234,false,Foo.

74.1.3 Separator flag values for output

For plain-text output, tab, for values separated by the tab character, is recognized as a value of separator_flag, as well as comma, pipe, semicolon, and space.

In plain-text output, false atoms are written as such; a list [1234, false, Foo] is written 1234,false,Foo, and there is no attempt to collapse the output to 1234,,Foo.

74.1.4 Binary floating-point input and output

numericalio functions can read and write 8-byte IEEE 754 floating-point numbers. These numbers can be stored either least significant byte first or most significant byte first, according to the global flag set by assume_external_byte_order. If not specified, numericalio assumes the external byte order is most-significant byte first.

Other kinds of numbers are coerced to 8-byte floats; numericalio cannot read or write binary non-numeric data.

Some Lisp implementations do not recognize IEEE 754 special values (positive and negative infinity, not-a-number values, denormalized values). The effect of reading such values with numericalio is undefined.

numericalio includes functions to open a stream for reading or writing a stream of bytes.

74.2 Functions and Variables for plain-text input and output

Function: read_matrix
    read_matrix (S)
    read_matrix (S, M)
    read_matrix (S, separator_flag)
    read_matrix (S, M, separator_flag)

read_matrix(S) reads the source S and returns its entire content as a matrix. The size of the matrix is inferred from the input data; each line of the file becomes one row of the matrix. If some lines have different lengths, read_matrix complains.

read_matrix(S, M) read the source S into the matrix M, until M is full or the source is exhausted. Input data are read into the matrix in row-major order; the input need not have the same number of rows and columns as M.

The source S may be a file name or a stream which for example allows skipping the very first line of a file (that may be useful, if you read CSV data, where the first line often contains the description of the columns):

s : openr("data.txt");
readline(s);  /* skip the first line */
M : read_matrix(s, 'comma);  /* read the following (comma-separated) lines into matrix M */
close(s);

The recognized values of separator_flag are comma, pipe, semicolon, and space. If separator_flag is not specified, the file is assumed space-delimited.

Category: Package numericalio · Category: File input

Function: read_array
read_array (S, A)
read_array (S, A, separator_flag)

Reads the source S into the array A, until A is full or the source is exhausted. Input data are read into the array in row-major order; the input need not conform to the dimensions of A.

The source S may be a file name or a stream.

The recognized values of separator_flag are comma, pipe, semicolon, and space. If separator_flag is not specified, the file is assumed space-delimited.

Category: Package numericalio · Category: File input

Function: read_hash_table
read_hash_table (S, A)
read_hash_table (S, A, separator_flag)

Reads the source S and returns its entire content as a hashed array. The source S may be a file name or a stream.

read_hash_table treats the first item on each line as a hash key, and associates the remainder of the line (as a list) with the key. For example, the line 567 12 17 32 55 is equivalent to A[567]: [12, 17, 32, 55]$. Lines need not have the same numbers of elements.

The recognized values of separator_flag are comma, pipe, semicolon, and space. If separator_flag is not specified, the file is assumed space-delimited.

Category: Package numericalio · Category: File input

Function: read_nested_list
read_nested_list (S)
read_nested_list (S, separator_flag)

Reads the source S and returns its entire content as a nested list. The source S may be a file name or a stream.

read_nested_list returns a list which has a sublist for each line of input. Lines need not have the same numbers of elements. Empty lines are not ignored: an empty line yields an empty sublist.

The recognized values of separator_flag are comma, pipe, semicolon, and space. If separator_flag is not specified, the file is assumed space-delimited.

Category: Package numericalio · Category: File input

Function: read_list
    read_list (S)
    read_list (S, L)
    read_list (S, separator_flag)
    read_list (S, L, separator_flag)

read_list(S) reads the source S and returns its entire content as a flat list.

read_list(S, L) reads the source S into the list L, until L is full or the source is exhausted.

The source S may be a file name or a stream.

The recognized values of separator_flag are comma, pipe, semicolon, and space. If separator_flag is not specified, the file is assumed space-delimited.

Category: Package numericalio · Category: File input

Function: write_data
write_data (X, D)
write_data (X, D, separator_flag)

Writes the object X to the destination D.

write_data writes a matrix in row-major order, with one line per row.

write_data writes an array created by array or make_array in row-major order, with a new line at the end of every slab. Higher-dimensional slabs are separated by additional new lines.

write_data writes a hashed array with each key followed by its associated list on one line.

write_data writes a nested list with each sublist on one line.

write_data writes a flat list all on one line.

The destination D may be a file name or a stream. When the destination is a file name, the global variable file_output_append governs whether the output file is appended or truncated. When the destination is a stream, no special action is taken by write_data after all the data are written; in particular, the stream remains open.

The recognized values of separator_flag are comma, pipe, semicolon, space, and tab. If separator_flag is not specified, the file is assumed space-delimited.

Category: Package numericalio · Category: File output

74.3 Functions and Variables for binary input and output

Function: assume_external_byte_order (byte_order_flag)

Tells numericalio the byte order for reading and writing binary data. Two values of byte_order_flag are recognized: lsb which indicates least-significant byte first, also called little-endian byte order; and msb which indicates most-significant byte first, also called big-endian byte order.

If not specified, numericalio assumes the external byte order is most-significant byte first.

Category: Package numericalio

Function: openr_binary (file_name)

Returns an input stream of 8-bit unsigned bytes to read the file named by file_name.

Category: Package numericalio · Category: File input

Function: openw_binary (file_name)

Returns an output stream of 8-bit unsigned bytes to write the file named by file_name.

Category: Package numericalio · Category: File output

Function: opena_binary (file_name)

Returns an output stream of 8-bit unsigned bytes to append the file named by file_name.

Category: Package numericalio · Category: File output

Function: read_binary_matrix (S, M)

Reads binary 8-byte floating point numbers from the source S into the matrix M until M is full, or the source is exhausted. Elements of M are read in row-major order.

The source S may be a file name or a stream.

The byte order in elements of the source is specified by assume_external_byte_order.

Category: Package numericalio · Category: File input

Function: read_binary_array (S, A)

Reads binary 8-byte floating point numbers from the source S into the array A until A is full, or the source is exhausted. A must be an array created by array or make_array. Elements of A are read in row-major order.

The source S may be a file name or a stream.

The byte order in elements of the source is specified by assume_external_byte_order.

Category: Package numericalio · Category: File input

Function: read_binary_list
read_binary_list (S)
read_binary_list (S, L)

read_binary_list(S) reads the entire content of the source S as a sequence of binary 8-byte floating point numbers, and returns it as a list. The source S may be a file name or a stream.

read_binary_list(S, L) reads 8-byte binary floating point numbers from the source S until the list L is full, or the source is exhausted.

The byte order in elements of the source is specified by assume_external_byte_order.

Category: Package numericalio · Category: File input

Function: write_binary_data (X, D)

Writes the object X, comprising binary 8-byte IEEE 754 floating-point numbers, to the destination D. Other kinds of numbers are coerced to 8-byte floats. write_binary_data cannot write non-numeric data.

The object X may be a list, a nested list, a matrix, or an array created by array or make_array; X cannot be a hashed array or any other type of object. write_binary_data writes nested lists, matrices, and arrays in row-major order.

The destination D may be a file name or a stream. When the destination is a file name, the global variable file_output_append governs whether the output file is appended or truncated. When the destination is a stream, no special action is taken by write_binary_data after all the data are written; in particular, the stream remains open.

The byte order in elements of the destination is specified by assume_external_byte_order.

Category: Package numericalio · Category: File output

75 odepack

75.1 Introduction to ODEPACK

ODEPACK is a collection of Fortran solvers for the initial value problem for ordinary differential equation systems. It consists of nine solvers, namely a basic solver called LSODE and eight variants of it – LSODES, LSODA, LSODAR, LSODPK, LSODKR, LSODI, LSOIBT, and LSODIS. The collection is suitable for both stiff and nonstiff systems. It includes solvers for systems given in explicit form, dy/dt = f(t,y), and also solvers for systems given in linearly implicit form, A(t,y) dy/dt = g(t,y). Two of the solvers use general sparse matrix solvers for the linear systems that arise. Two others use iterative (preconditioned Krylov) methods instead of direct methods for these linear systems. The most recent addition is LSODIS, which solves implicit problems with general sparse treatment of all matrices involved.

⁹

References: [1] Fortran Code is from http://netlib.org/odepack/

Category: Numerical methods · Category: Share packages · Category: Package odepack

75.1.1 Getting Started

Of the eight variants of the solver, maxima currently only has an inteface the dlsode.

Let’s say we have this sytem of equations to solve:

  f1 = -.04d0*y1 + 1d4*y2*y3
  f3 = 3d7*y2*y2
  dy1/dt = f1
  dy2/dt = -f1 - f3
  dy3/dt = f3

The independent variable is t; the dependent variables are y1, y2, and y3,

To start the solution, set up the differential equations to solved:

load("dlsode");
f1: -.04d0*y1 + 1d4*y2*y3$
f3: 3d7*y2*y2$
f2: -f1 - f3$
fex: [f1, f2, f3];

Initialize the solver, where we have selected method 21

(%i6) state : dlsode_init(fex, ['t,y1,y2,y3], 21);
(%o6) [[f, #<Function "LAMBDA ($T $Y1 $Y2 $Y3)" {49DAC061}>], 
[vars, [t, y1, y2, y3]], [mf, 21], [neq, 3], [lrw, 58], [liw, 23], [rwork, {Li\
sp Array: #(0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
               0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
               0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
               0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0)}], 
[iwork, {Lisp Array: #(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)}], 
[fjac, #<Function "LAMBDA ($T $Y1 $Y2 $Y3)" {49D52AC9}>]]

The arrays rwork and iwork carry state between calls to dlsode_step, so they should not be modified by the user. In fact, this state should not be modified by the user at all.

Now that the algorithm has been initialized we can compute solutions to the differential equation, using the state returned above.

For this example, we want to compute the solution at times 0.4*10^k for k from 0 to 11, with the initial values of 1, 0, 0 for the dependent variables and with a relative tolerance of 1d-4 and absolute tolerances of 1e-6, 1e-10, and 1d-6 for the dependent variables.

Then

y: [1d0, 0d0, 0d0];
t: 0d0;
rtol : 1d-4;
atol: [1d-6, 1d-10, 1d-6];
istate: 1;
t:0d0;
tout:.4d0;

for k : 1 thru 12 do
  block([],
    result: dlsode_step(y, t, tout, rtol, atol, istate, state),
    printf(true, "At t = ~12,4,2e   y = ~{~14,6,2e~}~%", result[1], result[2]),
    istate : result[3],
    tout : tout * 10);

This produces the output:

At t =   4.0000e-01   y =   9.851726e-01  3.386406e-05  1.479357e-02
At t =   4.0000e+00   y =   9.055142e-01  2.240418e-05  9.446344e-02
At t =   4.0000e+01   y =   7.158050e-01  9.184616e-06  2.841858e-01
At t =   4.0000e+02   y =   4.504846e-01  3.222434e-06  5.495122e-01
At t =   4.0000e+03   y =   1.831701e-01  8.940379e-07  8.168290e-01
At t =   4.0000e+04   y =   3.897016e-02  1.621193e-07  9.610297e-01
At t =   4.0000e+05   y =   4.935213e-03  1.983756e-08  9.950648e-01
At t =   4.0000e+06   y =   5.159269e-04  2.064759e-09  9.994841e-01
At t =   4.0000e+07   y =   5.306413e-05  2.122677e-10  9.999469e-01
At t =   4.0000e+08   y =   5.494530e-06  2.197824e-11  9.999945e-01
At t =   4.0000e+09   y =   5.129458e-07  2.051784e-12  9.999995e-01
At t =   4.0000e+10   y =  -7.170563e-08 -2.868225e-13  1.000000e+00

75.2 Functions and Variables for odepack

Function: dlsode_init (fex, vars, method)

This must be called before running the solver. This function returns a state object for use in the solver. The user must not modify the state.

The ODE to be solved is given in fex, which is a list of the equations. vars is a list of independent variable and the dependent variables. The list of dependent variables must be in the same order as the equations if fex. Finally, method indicates the method to be used by the solver:

10: Nonstiff (Adams) method, no Jacobian used.
21: Stiff (BDF) method, user-supplied full Jacobian.
22: Stiff method, internally generated full Jacobian.

The returned state object is a list of lists. The sublist is a list of two elements:

f: The compiled function for the ODE.
vars: The list independent and dependent variables (vars).
mf: The method to be used (method).
neq: The number of equations.
lrw: Length of the work vector for real values.
liw: Length of the work vector for integer values.
rwork: Lisp array holding the real-valued work vector.
iwork: Lisp array holding the integer-valued work vector.
fjac: Compiled analytical Jacobian of the eqations

Function: dlsode_step (inity, t, tout, rtol, atol, istate, state)

Performs one step of the solver, returning the values of the independent and dependent variables, a succes or error code.

inity

For the first call (when istate = 1), the initial values

t

Current value of the independent value

tout

Next point where output is desired which must not be equal to t.

rtol

relative tolerance parameter

atol

Absolute tolerance parameter, scalar of vector. If scalar, it applies to all dependent variables. Otherwise it must be the tolerance for each dependent variable.

Use rtol = 0 for pure absolute error and use atol = 0 for pure relative error.

istate

1 for the first call to dlsode, 2 for subsequent calls.

state

state returned by dlsode_init.

The output is a list of the following items:

t

independent variable value

y

list of values of the dependent variables at time t.

istate

Integration status:

1: no work because tout = tt
2: successful result
-1: Excess work done on this call
-2: Excess accuracy requested
-3: Illegal input detected
-4: Repeated error test failures
-5: Repeated convergence failures (perhaps bad Jacobian or wrong choice of mf or tolerances)
-6: Error weight becase zero during problem (solution component i vanishded and atol(i) = 0.

info

association list of various bits of information:

n_steps: total steps taken thus far
n_f_eval: total number of function evals
n_j_eval: total number of Jacobian evals
method_order: method order
len_rwork: Actual length used for real work array
len_iwork: Actual length used for integer work array

76 operatingsystem

76.1 Introduction to operatingsystem

Package operatingsystem contains functions for operatingsystem-tasks, like file system operations.

76.2 Directory operations

Function: chdir (dir): Change to directory dir

Function: mkdir (dir): Create directory dir

Function: rmdir (dir): remove directory dir

Function: getcurrentdirectory ()

returns the current working directory.

76.3 File operations

Function: copy_file (file1, file2): copies file file1 to file2

Function: rename_file (file1, file2): renames file file1 to file2

Function: delete_file (file1): deletes file file1

76.4 Environment operations

Function: getenv (env)

Get the value of the environmentvariable env

Example:

(%i1) load("operatingsystem")$
(%i2) getenv("PATH");
(%o2) /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

77 opsubst

77.1 Functions and Variables for opsubst

Function: opsubst
    opsubst (f,g,e)
    opsubst (g=f,e)
    opsubst ([g1=f1,g2=f2,..., gn=fn],e)

The function opsubst is similar to the function subst, except that opsubst only makes substitutions for the operators in an expression. In general, When f is an operator in the expression e, substitute g for f in the expression e.

To determine the operator, opsubst sets inflag to true. This means opsubst substitutes for the internal, not the displayed, operator in the expression.

Examples:

(%i1) load ("opsubst")$

(%i2) opsubst(f,g,g(g(x)));
(%o2)                     f(f(x))
(%i3) opsubst(f,g,g(g));
(%o3)                       f(g)
(%i4) opsubst(f,g[x],g[x](z));
(%o4)                       f(z)
(%i5) opsubst(g[x],f, f(z));
(%o5)                      g (z)
                            x
(%i6) opsubst(tan, sin, sin(sin));
(%o6)                     tan(sin)
(%i7) opsubst([f=g,g=h],f(x));
(%o7)                       h(x)

Internally, Maxima does not use the unary negation, division, or the subtraction operators; thus:

(%i8) opsubst("+","-",a-b);
(%o8)                     a - b
(%i9) opsubst("f","-",-a);
(%o9)                      - a
(%i10) opsubst("^^","/",a/b);
                             a
(%o10)                       -
                             b

The internal representation of -a*b is *(-1,a,b); thus

(%i11) opsubst("[","*", -a*b);
(%o11)                  [- 1, a, b]

When either operator isn’t a Maxima symbol, generally some other function will signal an error:

(%i12) opsubst(a+b,f, f(x));

Improper name or value in functional position:
b + a
 -- an error.  Quitting.  To debug this try debugmode(true);

However, subscripted operators are allowed:

(%i13) opsubst(g[5],f, f(x));
(%o13)                     g (x)
                            5

To use this function write first load("opsubst").

Category: Expressions · Category: Share packages · Category: Package opsubst

78 orthopoly

78.1 Introduction to orthogonal polynomials

orthopoly is a package for symbolic and numerical evaluation of several kinds of orthogonal polynomials, including Chebyshev, Laguerre, Hermite, Jacobi, Legendre, and ultraspherical (Gegenbauer) polynomials. Additionally, orthopoly includes support for the spherical Bessel, spherical Hankel, and spherical harmonic functions.

For the most part, orthopoly follows the conventions of Abramowitz and Stegun Handbook of Mathematical Functions, Chapter 22 (10th printing, December 1972); additionally, we use Gradshteyn and Ryzhik, Table of Integrals, Series, and Products (1980 corrected and enlarged edition), and Eugen Merzbacher Quantum Mechanics (2nd edition, 1970).

Barton Willis of the University of Nebraska at Kearney (UNK) wrote the orthopoly package and its documentation. The package is released under the GNU General Public License (GPL).

Category: Orthogonal polynomials · Category: Share packages · Category: Package orthopoly

78.1.1 Getting Started with orthopoly

load ("orthopoly") loads the orthopoly package.

To find the third-order Legendre polynomial,

(%i1) legendre_p (3, x);
                      3             2
             5 (1 - x)    15 (1 - x)
(%o1)      - ---------- + ----------- - 6 (1 - x) + 1
                 2             2

To express this as a sum of powers of x, apply ratsimp or rat to the result.

(%i2) [ratsimp (%), rat (%)];
                        3           3
                     5 x  - 3 x  5 x  - 3 x
(%o2)/R/            [----------, ----------]
                         2           2

Alternatively, make the second argument to legendre_p (its “main” variable) a canonical rational expression (CRE).

(%i1) legendre_p (3, rat (x));
                              3
                           5 x  - 3 x
(%o1)/R/                   ----------
                               2

For floating point evaluation, orthopoly uses a running error analysis to estimate an upper bound for the error. For example,

(%i1) jacobi_p (150, 2, 3, 0.2);
(%o1) interval(- 0.062017037936715, 1.533267919277521E-11)

Intervals have the form interval (c, r), where c is the center and r is the radius of the interval. Since Maxima does not support arithmetic on intervals, in some situations, such as graphics, you want to suppress the error and output only the center of the interval. To do this, set the option variable orthopoly_returns_intervals to false.

(%i1) orthopoly_returns_intervals : false;
(%o1)                         false
(%i2) jacobi_p (150, 2, 3, 0.2);
(%o2)                  - 0.062017037936715

Refer to the section see Floating point Evaluation for more information.

Most functions in orthopoly have a gradef property; thus

(%i1) diff (hermite (n, x), x);
(%o1)                     2 n H     (x)
                               n - 1
(%i2) diff (gen_laguerre (n, a, x), x);
              (a)               (a)
           n L   (x) - (n + a) L     (x) unit_step(n)
              n                 n - 1
(%o2)      ------------------------------------------
                               x

The unit step function in the second example prevents an error that would otherwise arise by evaluating with n equal to 0.

(%i3) ev (%, n = 0);
(%o3)                           0

The gradef property only applies to the “main” variable; derivatives with respect other arguments usually result in an error message; for example

(%i1) diff (hermite (n, x), x);
(%o1)                     2 n H     (x)
                               n - 1
(%i2) diff (hermite (n, x), n);

Maxima doesn't know the derivative of hermite with respect the first
argument
 -- an error.  Quitting.  To debug this try debugmode(true);

Generally, functions in orthopoly map over lists and matrices. For the mapping to fully evaluate, the option variables doallmxops and listarith must both be true (the defaults). To illustrate the mapping over matrices, consider

(%i1) hermite (2, x);
                                     2
(%o1)                    - 2 (1 - 2 x )
(%i2) m : matrix ([0, x], [y, 0]);
                            [ 0  x ]
(%o2)                       [      ]
                            [ y  0 ]
(%i3) hermite (2, m);
               [                             2  ]
               [      - 2        - 2 (1 - 2 x ) ]
(%o3)          [                                ]
               [             2                  ]
               [ - 2 (1 - 2 y )       - 2       ]

In the second example, the i, j element of the value is hermite (2, m[i,j]); this is not the same as computing -2 + 4 m . m, as seen in the next example.

(%i4) -2 * matrix ([1, 0], [0, 1]) + 4 * m . m;
                    [ 4 x y - 2      0     ]
(%o4)               [                      ]
                    [     0      4 x y - 2 ]

If you evaluate a function at a point outside its domain, generally orthopoly returns the function unevaluated. For example,

(%i1) legendre_p (2/3, x);
(%o1)                        P   (x)
                              2/3

orthopoly supports translation into TeX; it also does two-dimensional output on a terminal.

(%i1) spherical_harmonic (l, m, theta, phi);
                          m
(%o1)                    Y (theta, phi)
                          l
(%i2) tex (%);
$$Y_{l}^{m}\left(\vartheta,\varphi\right)$$
(%o2)                         false
(%i3) jacobi_p (n, a, a - b, x/2);
                          (a, a - b) x
(%o3)                    P          (-)
                          n          2
(%i4) tex (%);
$$P_{n}^{\left(a,a-b\right)}\left({{x}\over{2}}\right)$$
(%o4)                         false

78.1.2 Limitations

When an expression involves several orthogonal polynomials with symbolic orders, it’s possible that the expression actually vanishes, yet Maxima is unable to simplify it to zero. If you divide by such a quantity, you’ll be in trouble. For example, the following expression vanishes for integers n greater than 1, yet Maxima is unable to simplify it to zero.

(%i1) (2*n - 1) * legendre_p (n - 1, x) * x - n * legendre_p (n, x)
      + (1 - n) * legendre_p (n - 2, x);
(%o1)  (2 n - 1) P     (x) x - n P (x) + (1 - n) P     (x)
                  n - 1           n               n - 2

For a specific n, we can reduce the expression to zero.

(%i2) ev (% ,n = 10, ratsimp);
(%o2)                           0

Generally, the polynomial form of an orthogonal polynomial is ill-suited for floating point evaluation. Here’s an example.

(%i1) p : jacobi_p (100, 2, 3, x)$

(%i2) subst (0.2, x, p);
(%o2)                3.4442767023833592E+35
(%i3) jacobi_p (100, 2, 3, 0.2);
(%o3)  interval(0.18413609135169, 6.8990300925815987E-12)
(%i4) float(jacobi_p (100, 2, 3, 2/10));
(%o4)                   0.18413609135169

The true value is about 0.184; this calculation suffers from extreme subtractive cancellation error. Expanding the polynomial and then evaluating, gives a better result.

(%i5) p : expand(p)$
(%i6) subst (0.2, x, p);
(%o6) 0.18413609766122982

This isn’t a general rule; expanding the polynomial does not always result in an expression that is better suited for numerical evaluation. By far, the best way to do numerical evaluation is to make one or more of the function arguments floating point numbers. By doing that, specialized floating point algorithms are used for evaluation.

Maxima’s float function is somewhat indiscriminate; if you apply float to an expression involving an orthogonal polynomial with a symbolic degree or order parameter, these parameters may be converted into floats; after that, the expression will not evaluate fully. Consider

(%i1) assoc_legendre_p (n, 1, x);
                               1
(%o1)                         P (x)
                               n
(%i2) float (%);
                              1.0
(%o2)                        P   (x)
                              n
(%i3) ev (%, n=2, x=0.9);
                             1.0
(%o3)                       P   (0.9)
                             2

The expression in (%o3) will not evaluate to a float; orthopoly doesn’t recognize floating point values where it requires an integer. Similarly, numerical evaluation of the pochhammer function for orders that exceed pochhammer_max_index can be troublesome; consider

(%i1) x :  pochhammer (1, 10), pochhammer_max_index : 5;
(%o1)                         (1)
                                 10

Applying float doesn’t evaluate x to a float

(%i2) float (x);
(%o2)                       (1.0)
                                 10.0

To evaluate x to a float, you’ll need to bind pochhammer_max_index to 11 or greater and apply float to x.

(%i3) float (x), pochhammer_max_index : 11;
(%o3)                       3628800.0

The default value of pochhammer_max_index is 100; change its value after loading orthopoly.

Finally, be aware that reference books vary on the definitions of the orthogonal polynomials; we’ve generally used the conventions of Abramowitz and Stegun.

Before you suspect a bug in orthopoly, check some special cases to determine if your definitions match those used by orthopoly. Definitions often differ by a normalization; occasionally, authors use “shifted” versions of the functions that makes the family orthogonal on an interval other than (-1, 1). To define, for example, a Legendre polynomial that is orthogonal on (0, 1), define

(%i1) shifted_legendre_p (n, x) := legendre_p (n, 2*x - 1)$

(%i2) shifted_legendre_p (2, rat (x));
                            2
(%o2)/R/                 6 x  - 6 x + 1
(%i3) legendre_p (2, rat (x));
                               2
                            3 x  - 1
(%o3)/R/                    --------
                               2

78.1.3 Floating point Evaluation

Most functions in orthopoly use a running error analysis to estimate the error in floating point evaluation; the exceptions are the spherical Bessel functions and the associated Legendre polynomials of the second kind. For numerical evaluation, the spherical Bessel functions call SLATEC functions. No specialized method is used for numerical evaluation of the associated Legendre polynomials of the second kind.

The running error analysis ignores errors that are second or higher order in the machine epsilon (also known as unit roundoff). It also ignores a few other errors. It’s possible (although unlikely) that the actual error exceeds the estimate.

Intervals have the form interval (c, r), where c is the center of the interval and r is its radius. The center of an interval can be a complex number, and the radius is always a positive real number.

Here is an example.

(%i1) fpprec : 50$

(%i2) y0 : jacobi_p (100, 2, 3, 0.2);
(%o2) interval(0.1841360913516871, 6.8990300925815987E-12)
(%i3) y1 : bfloat (jacobi_p (100, 2, 3, 1/5));
(%o3) 1.8413609135168563091370224958913493690868904463668b-1

Let’s test that the actual error is smaller than the error estimate

(%i4) is (abs (part (y0, 1) - y1) < part (y0, 2));
(%o4)                         true

Indeed, for this example the error estimate is an upper bound for the true error.

Maxima does not support arithmetic on intervals.

(%i1) legendre_p (7, 0.1) + legendre_p (8, 0.1);
(%o1) interval(0.18032072148437508, 3.1477135311021797E-15)
        + interval(- 0.19949294375000004, 3.3769353084291579E-15)

A user could define arithmetic operators that do interval math. To define interval addition, we can define

(%i1) infix ("@+")$

(%i2) "@+"(x,y) := interval (part (x, 1) + part (y, 1), part (x, 2)
      + part (y, 2))$

(%i3) legendre_p (7, 0.1) @+ legendre_p (8, 0.1);
(%o3) interval(- 0.019172222265624955, 6.5246488395313372E-15)

The special floating point routines get called when the arguments are complex. For example,

(%i1) legendre_p (10, 2 + 3.0*%i);
(%o1) interval(- 3.876378825E+7 %i - 6.0787748E+7, 
                                           1.2089173052721777E-6)

Let’s compare this to the true value.

(%i1) float (expand (legendre_p (10, 2 + 3*%i)));
(%o1)          - 3.876378825E+7 %i - 6.0787748E+7

Additionally, when the arguments are big floats, the special floating point routines get called; however, the big floats are converted into double floats and the final result is a double.

(%i1) ultraspherical (150, 0.5b0, 0.9b0);
(%o1) interval(- 0.043009481257265, 3.3750051301228864E-14)

78.1.4 Graphics and `orthopoly`

To plot expressions that involve the orthogonal polynomials, you must do two things:

Set the option variable orthopoly_returns_intervals to false,
Quote any calls to orthopoly functions.

If function calls aren’t quoted, Maxima evaluates them to polynomials before plotting; consequently, the specialized floating point code doesn’t get called. Here is an example of how to plot an expression that involves a Legendre polynomial.

(%i1) plot2d ('(legendre_p (5, x)), [x, 0, 1]),
                        orthopoly_returns_intervals : false;
(%o1)

The entire expression legendre_p (5, x) is quoted; this is different than just quoting the function name using 'legendre_p (5, x).

78.1.5 Miscellaneous Functions

The orthopoly package defines the Pochhammer symbol and a unit step function. orthopoly uses the Kronecker delta function and the unit step function in gradef statements.

To convert Pochhammer symbols into quotients of gamma functions, use makegamma.

(%i1) makegamma (pochhammer (x, n));
                          gamma(x + n)
(%o1)                     ------------
                            gamma(x)
(%i2) makegamma (pochhammer (1/2, 1/2));
                                1
(%o2)                       ---------
                            sqrt(%pi)

Derivatives of the Pochhammer symbol are given in terms of the psi function.

(%i1) diff (pochhammer (x, n), x);
(%o1)             (x)  (psi (x + n) - psi (x))
                     n     0             0
(%i2) diff (pochhammer (x, n), n);
(%o2)                   (x)  psi (x + n)
                           n    0

You need to be careful with the expression in (%o1); the difference of the psi functions has polynomials when x = -1, -2, .., -n. These polynomials cancel with factors in pochhammer (x, n) making the derivative a degree n - 1 polynomial when n is a positive integer.

The Pochhammer symbol is defined for negative orders through its representation as a quotient of gamma functions. Consider

(%i1) q : makegamma (pochhammer (x, n));
                          gamma(x + n)
(%o1)                     ------------
                            gamma(x)
(%i2) sublis ([x=11/3, n= -6], q);
                               729
(%o2)                        - ----
                               2240

Alternatively, we can get this result directly.

(%i1) pochhammer (11/3, -6);
                               729
(%o1)                        - ----
                               2240

The unit step function is left-continuous; thus

(%i1) [unit_step (-1/10), unit_step (0), unit_step (1/10)];
(%o1)                       [0, 0, 1]

If you need a unit step function that is neither left or right continuous at zero, define your own using signum; for example,

(%i1) xunit_step (x) := (1 + signum (x))/2$

(%i2) [xunit_step (-1/10), xunit_step (0), xunit_step (1/10)];
                                1
(%o2)                       [0, -, 1]
                                2

Do not redefine unit_step itself; some code in orthopoly requires that the unit step function be left-continuous.

78.1.6 Algorithms

Generally, orthopoly does symbolic evaluation by using a hypergeometic representation of the orthogonal polynomials. The hypergeometic functions are evaluated using the (undocumented) functions hypergeo11 and hypergeo21. The exceptions are the half-integer Bessel functions and the associated Legendre function of the second kind. The half-integer Bessel functions are evaluated using an explicit representation, and the associated Legendre function of the second kind is evaluated using recursion.

For floating point evaluation, we again convert most functions into a hypergeometic form; we evaluate the hypergeometic functions using forward recursion. Again, the exceptions are the half-integer Bessel functions and the associated Legendre function of the second kind. Numerically, the half-integer Bessel functions are evaluated using the SLATEC code.

78.2 Functions and Variables for orthogonal polynomials

Function: assoc_legendre_p (n, m, x)

The associated Legendre function of the first kind of degree n and order m.

Reference: Abramowitz and Stegun, equations 22.5.37, page 779, 8.6.6 (second equation), page 334, and 8.2.5, page 333.

Function: assoc_legendre_q (n, m, x)

The associated Legendre function of the second kind of degree n and order m.

Reference: Abramowitz and Stegun, equation 8.5.3 and 8.1.8.

Function: chebyshev_t (n, x)

The Chebyshev polynomial of the first kind of degree n.

Reference: Abramowitz and Stegun, equation 22.5.47, page 779.

Function: chebyshev_u (n, x)

The Chebyshev polynomial of the second kind of degree n.

Reference: Abramowitz and Stegun, equation 22.5.48, page 779.

Function: gen_laguerre (n, a, x)

The generalized Laguerre polynomial of degree n.

Reference: Abramowitz and Stegun, equation 22.5.54, page 780.

Function: hermite (n, x)

The Hermite polynomial of degree n.

Reference: Abramowitz and Stegun, equation 22.5.55, page 780.

Category: Package orthopoly · Category: Predicate functions

Function: intervalp (e)

Return true if the input is an interval and return false if it isn’t.

Function: jacobi_p (n, a, b, x)

The Jacobi polynomial.

The Jacobi polynomials are actually defined for all a and b; however, the Jacobi polynomial weight (1 - x)^a (1 + x)^b isn’t integrable for a <= -1 or b <= -1.

Reference: Abramowitz and Stegun, equation 22.5.42, page 779.

Function: laguerre (n, x)

The Laguerre polynomial of degree n.

Reference: Abramowitz and Stegun, equations 22.5.16 and 22.5.54, page 780.

Function: legendre_p (n, x)

The Legendre polynomial of the first kind of degree n.

Reference: Abramowitz and Stegun, equations 22.5.50 and 22.5.51, page 779.

Function: legendre_q (n, x)

The Legendre function of the second kind of degree n.

Reference: Abramowitz and Stegun, equations 8.5.3 and 8.1.8.

Function: orthopoly_recur (f, args)

Returns a recursion relation for the orthogonal function family f with arguments args. The recursion is with respect to the polynomial degree.

(%i1) orthopoly_recur (legendre_p, [n, x]);
                    (2 n + 1) P (x) x - n P     (x)
                               n           n - 1
(%o1)   P     (x) = -------------------------------
         n + 1                   n + 1

The second argument to orthopoly_recur must be a list with the correct number of arguments for the function f; if it isn’t, Maxima signals an error.

(%i1) orthopoly_recur (jacobi_p, [n, x]);

Function jacobi_p needs 4 arguments, instead it received 2
 -- an error.  Quitting.  To debug this try debugmode(true);

Additionally, when f isn’t the name of one of the families of orthogonal polynomials, an error is signalled.

(%i1) orthopoly_recur (foo, [n, x]);

A recursion relation for foo isn't known to Maxima
 -- an error.  Quitting.  To debug this try debugmode(true);

Variable: orthopoly_returns_intervals

Default value: true

When orthopoly_returns_intervals is true, floating point results are returned in the form interval (c, r), where c is the center of an interval and r is its radius. The center can be a complex number; in that case, the interval is a disk in the complex plane.

Function: orthopoly_weight (f, args)

Returns a three element list; the first element is the formula of the weight for the orthogonal polynomial family f with arguments given by the list args; the second and third elements give the lower and upper endpoints of the interval of orthogonality. For example,

(%i1) w : orthopoly_weight (hermite, [n, x]);
                            2
                         - x
(%o1)                 [%e    , - inf, inf]
(%i2) integrate(w[1]*hermite(3, x)*hermite(2, x), x, w[2], w[3]);
(%o2)                           0

The main variable of f must be a symbol; if it isn’t, Maxima signals an error.

Category: Package orthopoly · Category: Gamma and factorial functions

Function: pochhammer (x, n)

The Pochhammer symbol. For nonnegative integers n with n <= pochhammer_max_index, the expression pochhammer (x, n) evaluates to the product x (x + 1) (x + 2) ... (x + n - 1) when n > 0 and to 1 when n = 0. For negative n, pochhammer (x, n) is defined as (-1)^n / pochhammer (1 - x, -n). Thus

(%i1) pochhammer (x, 3);
(%o1)                   x (x + 1) (x + 2)
(%i2) pochhammer (x, -3);
                                 1
(%o2)               - -----------------------
                      (1 - x) (2 - x) (3 - x)

To convert a Pochhammer symbol into a quotient of gamma functions, (see Abramowitz and Stegun, equation 6.1.22) use makegamma; for example

(%i1) makegamma (pochhammer (x, n));
                          gamma(x + n)
(%o1)                     ------------
                            gamma(x)

When n exceeds pochhammer_max_index or when n is symbolic, pochhammer returns a noun form.

(%i1) pochhammer (x, n);
(%o1)                         (x)
                                 n

Variable: pochhammer_max_index

Default value: 100

pochhammer (n, x) expands to a product if and only if n <= pochhammer_max_index.

Examples:

(%i1) pochhammer (x, 3), pochhammer_max_index : 3;
(%o1)                   x (x + 1) (x + 2)
(%i2) pochhammer (x, 4), pochhammer_max_index : 3;
(%o2)                         (x)
                                 4

Reference: Abramowitz and Stegun, equation 6.1.16, page 256.

Category: Package orthopoly · Category: Gamma and factorial functions

Function: spherical_bessel_j (n, x)

The spherical Bessel function of the first kind.

Reference: Abramowitz and Stegun, equations 10.1.8, page 437 and 10.1.15, page 439.

Category: Package orthopoly · Category: Bessel functions

Function: spherical_bessel_y (n, x)

The spherical Bessel function of the second kind.

Reference: Abramowitz and Stegun, equations 10.1.9, page 437 and 10.1.15, page 439.

Category: Package orthopoly · Category: Bessel functions

Function: spherical_hankel1 (n, x)

The spherical Hankel function of the first kind.

Reference: Abramowitz and Stegun, equation 10.1.36, page 439.

Category: Package orthopoly · Category: Bessel functions

Function: spherical_hankel2 (n, x)

The spherical Hankel function of the second kind.

Reference: Abramowitz and Stegun, equation 10.1.17, page 439.

Category: Package orthopoly · Category: Bessel functions

Function: spherical_harmonic (n, m, x, y)

The spherical harmonic function.

Reference: Merzbacher 9.64.

Category: Package orthopoly · Category: Mathematical functions

Function: unit_step (x)

The left-continuous unit step function; thus unit_step (x) vanishes for x <= 0 and equals 1 for x > 0.

If you want a unit step function that takes on the value 1/2 at zero, use (1 + signum (x))/2.

Function: ultraspherical (n, a, x)

The ultraspherical polynomial (also known as the Gegenbauer polynomial).

Reference: Abramowitz and Stegun, equation 22.5.46, page 779.

Category: Rational expressions · Category: Package ratpow

79 ratpow

The package ratpow provides functions that find the exponents of the denominator in a CRE polynomial. If the exponents in the denominator are needed instead ratdenom can be used to extract this denominator first. Returned coefficients are in CRE form except for numbers.

In order to get a list of vars in a CRE polynomial showratvars can be used.

For information about CREs see also rat, ratdisrep and showratvars.

79.1 Functions and Variables for ratpow

Function: ratp_hipow (expr, x)

Finds the highest power of the main variable in ratnumer(expr)

(%i1) load("ratpow")$

(%i2) ratp_hipow( x^(5/2) + x^2 , x);
(%o2)                           2

(%i3) ratp_hipow( x^(5/2) + x^2 , sqrt(x));
(%o3)                           5

Function: ratp_lopow (expr, x)

Finds the lowest power of the main variable in ratnumer(expr)

(%i1) load("ratpow")$

(%i2) ratp_lopow( x^5 + x^2 , x);
(%o2)                           2

The following example will return 0 since 1 equals x^0:

(%i1) load("ratpow")$

(%i2) ratp_lopow( x^5 + x^2 + 1, x);
(%o2)                           0

The CRE form of the following equation contains sqrt(x) and x. Since they are interpreted as independent variables ratp_lopow returns 0 in this case:

(%i1) load("ratpow")$

(%i2) g:sqrt(x)^5 + sqrt(x)^2;
                             5/2
(%o2)                       x    + x

(%i3) showratvars(g);
                              1/2
(%o3)                       [x   , x]

(%i4) ratp_lopow( g, x);
(%o4)                           0

(%i5) ratp_lopow( g, sqrt(x));
(%o5)                           0

Category: Rational expressions · Category: Package ratpow

Function: ratp_coeffs (expr, x)

Generates a list of powers and coefficients of the main variable ratnumer(expr).

(%i1) load("ratpow")$

(%i2) ratp_coeffs( 4*x^3 + x + sqrt(x), x);
(%o2)/R/         [[3, 4], [1, 1], [0, sqrt(x)]]

Category: Rational expressions · Category: Package ratpow

Function: ratp_dense_coeffs (expr, x)

Generates a list of coefficients in ratnumer(expr); returned coefficients are in CRE form except for numbers.

(%i1) load("ratpow")$

(%i2) ratp_dense_coeffs( 4*x^3 + x + sqrt(x), x);
(%o2)/R/               [4, 0, 1, sqrt(x)]

Category: Rational expressions · Category: Package ratpow

80 romberg

80.1 Functions and Variables for romberg

Function: romberg
romberg (expr, x, a, b)
romberg (F, a, b)

Computes a numerical integration by Romberg’s method.

romberg(expr, x, a, b) returns an estimate of the integral integrate(expr, x, a, b). expr must be an expression which evaluates to a floating point value when x is bound to a floating point value.

romberg(F, a, b) returns an estimate of the integral integrate(F(x), x, a, b) where x represents the unnamed, sole argument of F; the actual argument is not named x. F must be a Maxima or Lisp function which returns a floating point value when the argument is a floating point value. F may name a translated or compiled Maxima function.

The accuracy of romberg is governed by the global variables rombergabs and rombergtol. romberg terminates successfully when the absolute difference between successive approximations is less than rombergabs, or the relative difference in successive approximations is less than rombergtol. Thus when rombergabs is 0.0 (the default) only the relative error test has any effect on romberg.

romberg halves the stepsize at most rombergit times before it gives up; the maximum number of function evaluations is therefore 2^rombergit. If the error criterion established by rombergabs and rombergtol is not satisfied, romberg prints an error message. romberg always makes at least rombergmin iterations; this is a heuristic intended to prevent spurious termination when the integrand is oscillatory.

romberg repeatedly evaluates the integrand after binding the variable of integration to a specific value (and not before). This evaluation policy makes it possible to nest calls to romberg, to compute multidimensional integrals. However, the error calculations do not take the errors of nested integrations into account, so errors may be underestimated. Also, methods devised especially for multidimensional problems may yield the same accuracy with fewer function evaluations.

See also Introduction to QUADPACK, a collection of numerical integration functions.

Examples:

A 1-dimensional integration.

(%i1) f(x) := 1/((x - 1)^2 + 1/100) + 1/((x - 2)^2 + 1/1000)
              + 1/((x - 3)^2 + 1/200);
                    1                 1                1
(%o1) f(x) := -------------- + --------------- + --------------
                     2    1           2    1            2    1
              (x - 1)  + ---   (x - 2)  + ----   (x - 3)  + ---
                         100              1000              200

(%i2) rombergtol : 1e-6;
(%o2)                 9.999999999999999e-7

(%i3) rombergit : 15;
(%o3)                          15

(%i4) estimate : romberg (f(x), x, -5, 5);
(%o4)                   173.6730736617464

(%i5) exact : integrate (f(x), x, -5, 5);
        3/2          3/2      3/2          3/2
(%o5) 10    atan(7 10   ) + 10    atan(3 10   )
      3/2         9/2       3/2         5/2
 + 5 2    atan(5 2   ) + 5 2    atan(5 2   ) + 10 atan(60)
 + 10 atan(40)

(%i6) abs (estimate - exact) / exact, numer;
(%o6)                 7.552722451569877e-11

A 2-dimensional integration, implemented by nested calls to romberg.

(%i1) g(x, y) := x*y / (x + y);
                                    x y
(%o1)                   g(x, y) := -----
                                   x + y

(%i2) rombergtol : 1e-6;
(%o2)                 9.999999999999999e-7

(%i3) estimate : romberg (romberg (g(x, y), y, 0, x/2), x, 1, 3);
(%o3)                  0.8193023962835647

(%i4) assume (x > 0);
(%o4)                        [x > 0]

(%i5) integrate (integrate (g(x, y), y, 0, x/2), x, 1, 3);
                                           3
                                     2 log(-) - 1
                    9                      2        9
(%o5)      (- 9 log(-)) + 9 log(3) + ------------ + -
                    2                     6         2

(%i6) exact : radcan (%);
                    26 log(3) - 26 log(2) - 13
(%o6)             - --------------------------
                                3

(%i7) abs (estimate - exact) / exact, numer;
(%o7)                 1.371197987185102e-10

Category: Package romberg · Category: Numerical methods

Option variable: rombergabs

Default value: 0.0

81 simplex

81.1 Introduction to simplex

simplex is a package for linear optimization using the simplex algorithm.

Example:

(%i1) load("simplex")$
(%i2) minimize_lp(x+y, [3*x+2*y>2, x+4*y>3]);
                  9        7       1
(%o2)            [--, [y = --, x = -]]
                  10       10      5

Category: Numerical methods · Category: Optimization · Category: Share packages · Category: Package simplex

81.1.1 Tests for simplex

There are some tests in the directory share/simplex/Tests.

81.1.1.1 klee_minty

The function klee_minty produces input for linear_program, for which exponential time for solving is required without scaling.

Example:

load(klee_minty)$
apply(linear_program, klee_minty(6));

A better approach:

epsilon_sx : 0$
scale_sx : true$
apply(linear_program, klee_minty(10));

81.1.1.2 NETLIB

Some smaller problems from netlib (http://www.netlib.org/lp/data/) test suite are converted to a format, readable by Maxima. Problems are adlittle, afiro, kb2, sc50a and share2b. Each problem has three input files in CSV format for matrix A and vectors b and c.

Example:

A : read_matrix("adlittle_A.csv", 'csv)$
b : read_list("adlittle_b.csv", 'csv)$
c : read_list("adlittle_c.csv", 'csv)$
linear_program(A, b, c)$
%[2];
=> 225494.9631623802

Results:

PROBLEM        MINIMUM                  SCALING
adlittle       +2.2549496316E+05        false
afiro          -4.6475314286E+02        false
kb2            -1.7499001299E+03        true
sc50a          -6.4575077059E+01        false
share2b        -4.1573518187E+02        false

The Netlib website http://www.netlib.org/lp/data/readme lists the values as

PROBLEM        MINIMUM
adlittle       +2.2549496316E+05
afiro          -4.6475314286E+02
kb2            -1.7499001299E+03
sc50a          -6.4575077059E+01
share2b        -4.1573224074E+02

81.2 Functions and Variables for simplex

Option variable: epsilon_lp

Default value: 10^-8

Epsilon used for numerical computations in linear_program; it is set to 0 in linear_program when all inputs are rational.

Example:

(%i1) load(simplex)$

(%i2) minimize_lp(-x, [1e-9*x + y <= 1], [x,y]);
Warning: linear_program(A,b,c): non-rat inputs found, epsilon_lp= 1.0e-8
Warning: Solution may be incorrect.
(%o2)                        Problem not bounded!
(%i3) minimize_lp(-x, [10^-9*x + y <= 1], [x,y]);
(%o3)               [- 1000000000, [y = 0, x = 1000000000]]
(%i4) minimize_lp(-x, [1e-9*x + y <= 1], [x,y]), epsilon_lp=0;
(%o4)     [- 9.999999999999999e+8, [y = 0, x = 9.999999999999999e+8]]

82 simplification

82.1 Introduction to simplification

The directory maxima/share/simplification contains several scripts which implement simplification rules and functions, and also some functions not related to simplification.

82.2 Package absimp

The absimp package contains pattern-matching rules that extend the built-in simplification rules for the abs and signum functions. absimp respects relations established with the built-in assume function and by declarations such as mode_declare (m, even, n, odd) for even or odd integers.

absimp defines unitramp and unitstep functions in terms of abs and signum.

load ("absimp") loads this package. demo ("absimp") shows a demonstration of this package.

Examples:

(%i1) load ("absimp")$

(%i2) (abs (x))^2;
                                2
(%o2)                          x

(%i3) diff (abs (x), x);
                               x
(%o3)                        ------
                             abs(x)

(%i4) cosh (abs (x));
(%o4)                        cosh(x)

Category: Simplification functions · Category: Rules and patterns · Category: Share packages · Category: Package absimp

82.3 Package facexp

The facexp package contains several related functions that provide the user with the ability to structure expressions by controlled expansion. This capability is especially useful when the expression contains variables that have physical meaning, because it is often true that the most economical form of such an expression can be obtained by fully expanding the expression with respect to those variables, and then factoring their coefficients. While it is true that this procedure is not difficult to carry out using standard Maxima functions, additional fine-tuning may also be desirable, and these finishing touches can be more difficult to apply.

The function facsum and its related forms provide a convenient means for controlling the structure of expressions in this way. Another function, collectterms, can be used to add two or more expressions that have already been simplified to this form, without resimplifying the whole expression again. This function may be useful when the expressions are very large.

load ("facexp") loads this package. demo ("facexp") shows a demonstration of this package.

Category: Expressions · Category: Share packages · Category: Package facexp

Function: facsum (expr, arg_1, ..., arg_n)

Returns a form of expr which depends on the arguments arg_1, ..., arg_n. The arguments can be any form suitable for ratvars, or they can be lists of such forms. If the arguments are not lists, then the form returned is fully expanded with respect to the arguments, and the coefficients of the arguments are factored. These coefficients are free of the arguments, except perhaps in a non-rational sense.

If any of the arguments are lists, then all such lists are combined into a single list, and instead of calling factor on the coefficients of the arguments, facsum calls itself on these coefficients, using this newly constructed single list as the new argument list for this recursive call. This process can be repeated to arbitrary depth by nesting the desired elements in lists.

It is possible that one may wish to facsum with respect to more complicated subexpressions, such as log (x + y). Such arguments are also permissible.

Occasionally the user may wish to obtain any of the above forms for expressions which are specified only by their leading operators. For example, one may wish to facsum with respect to all log’s. In this situation, one may include among the arguments either the specific log’s which are to be treated in this way, or alternatively, either the expression operator (log) or 'operator (log). If one wished to facsum the expression expr with respect to the operators op_1, ..., op_n, one would evaluate facsum (expr, operator (op_1, ..., op_n)). The operator form may also appear inside list arguments.

In addition, the setting of the switches facsum_combine and nextlayerfactor may affect the result of facsum.

Global variable: nextlayerfactor

Default value: false

When nextlayerfactor is true, recursive calls of facsum are applied to the factors of the factored form of the coefficients of the arguments.

When false, facsum is applied to each coefficient as a whole whenever recusive calls to facsum occur.

Inclusion of the atom nextlayerfactor in the argument list of facsum has the effect of nextlayerfactor: true, but for the next level of the expression only. Since nextlayerfactor is always bound to either true or false, it must be presented single-quoted whenever it appears in the argument list of facsum.

Global variable: facsum_combine

Default value: true

facsum_combine controls the form of the final result returned by facsum when its argument is a quotient of polynomials. If facsum_combine is false then the form will be returned as a fully expanded sum as described above, but if true, then the expression returned is a ratio of polynomials, with each polynomial in the form described above.

The true setting of this switch is useful when one wants to facsum both the numerator and denominator of a rational expression, but does not want the denominator to be multiplied through the terms of the numerator.

Function: factorfacsum (expr, arg_1, ... arg_n)

Returns a form of expr which is obtained by calling facsum on the factors of expr with arg_1, ... arg_n as arguments. If any of the factors of expr is raised to a power, both the factor and the exponent will be processed in this way.

Category: Share packages · Category: Package functs

Function: collectterms (expr, arg_1, …, arg_n)

Collects all terms that contain arg_1 ... arg_n. If several expressions have been simplified with the following functions facsum, factorfacsum, factenexpand, facexpten or factorfacexpten, and they are to be added together, it may be desirable to combine them using the function collecterms. collecterms can take as arguments all of the arguments that can be given to these other associated functions with the exception of nextlayerfactor, which has no effect on collectterms. The advantage of collectterms is that it returns a form similar to facsum, but since it is adding forms that have already been processed by facsum, it does not need to repeat that effort. This capability is especially useful when the expressions to be summed are very large.

82.4 Package functs

Function: rempart (expr, n)

Removes part n from the expression expr.

If n is a list of the form [l, m] then parts l thru m are removed.

To use this function write first load(functs).

Category: Package functs · Category: Expressions

Function: wronskian ([f_1, ..., f_n], x)

Returns the Wronskian matrix of the list of expressions [f_1, ..., f_n] in the variable x. The determinant of the Wronskian matrix is the Wronskian determinant of the list of expressions.

To use wronskian, first load(functs). Example:

(%i1) load ("functs")$

(%i2) wronskian([f(x), g(x)],x);
                    [   f(x)       g(x)    ]
                    [                      ]
(%o2)               [ d          d         ]
                    [ -- (f(x))  -- (g(x)) ]
                    [ dx         dx        ]

Category: Package functs · Category: Differential calculus

Function: tracematrix (M)

Returns the trace (sum of the diagonal elements) of matrix M.

To use this function write first load(functs).

Category: Package functs · Category: Matrices

Function: rational (z)

Multiplies numerator and denominator of z by the complex conjugate of denominator, thus rationalizing the denominator. Returns canonical rational expression (CRE) form if given one, else returns general form.

To use this function write first load(functs).

Category: Package functs · Category: Expressions

Function: nonzeroandfreeof (x, expr)

Returns true if expr is nonzero and freeof (x, expr) returns true. Returns false otherwise.

To use this function write first load(functs).

Category: Package functs · Category: Expressions

Function: linear (expr, x)

When expr is an expression of the form a*x + b where a is nonzero, and a and b are free of x, linear returns a list of three equations, one for each of the three formal variables b, a, and x. Otherwise, linear returns false.

load(antid) loads this function.

Example:

(%i1) load ("antid");
(%o1)  /maxima/share/integration/antid.mac

(%i2) linear ((1 - w)*(1 - x)*z, z);
(%o2) [bargumentb = 0, aargumenta = (w - 1) x - w + 1, 
                                                  xargumentx = z]

(%i3) linear (cos(u - v) + cos(u + v), u);
(%o3)                         false

Category: Package antid · Category: Expressions

Function: gcdivide (p, q)

When the option variable takegcd is true which is the default, gcdivide divides the polynomials p and q by their greatest common divisor and returns the ratio of the results. gcdivde calls the function ezgcd to divide the polynomials by the greatest common divisor.

When takegcd is false, gcdivide returns the ratio p/q.

To use this function write first load(functs).

See also ezgcd, gcd, gcdex, and poly_gcd.

Example:

(%i1) load(functs)$

(%i2) p1:6*x^3+19*x^2+19*x+6; 
                        3       2
(%o2)                6 x  + 19 x  + 19 x + 6
(%i3) p2:6*x^5+13*x^4+12*x^3+13*x^2+6*x;
                  5       4       3       2
(%o3)          6 x  + 13 x  + 12 x  + 13 x  + 6 x
(%i4) gcdivide(p1, p2);
                             x + 1
(%o4)                        ------
                              3
                             x  + x
(%i5) takegcd:false;
(%o5)                         false
(%i6) gcdivide(p1, p2);
                       3       2
                    6 x  + 19 x  + 19 x + 6
(%o6)          ----------------------------------
                  5       4       3       2
               6 x  + 13 x  + 12 x  + 13 x  + 6 x
(%i7) ratsimp(%);
                             x + 1
(%o7)                        ------
                              3
                             x  + x

Category: Package functs · Category: Polynomials

Function: arithmetic (a, d, n)

Returns the n-th term of the arithmetic series a, a + d, a + 2*d, ..., a + (n - 1)*d.

To use this function write first load(functs).

Category: Package functs · Category: Sums and products

Function: geometric (a, r, n)

Returns the n-th term of the geometric series a, a*r, a*r^2, ..., a*r^(n - 1).

To use this function write first load(functs).

Category: Package functs · Category: Sums and products

Function: harmonic (a, b, c, n)

Returns the n-th term of the harmonic series a/b, a/(b + c), a/(b + 2*c), ..., a/(b + (n - 1)*c).

To use this function write first load(functs).

Category: Package functs · Category: Sums and products

Function: arithsum (a, d, n)

Returns the sum of the arithmetic series from 1 to n.

To use this function write first load(functs).

Category: Package functs · Category: Sums and products

Function: geosum (a, r, n)

Returns the sum of the geometric series from 1 to n. If n is infinity (inf) then a sum is finite only if the absolute value of r is less than 1.

To use this function write first load(functs).

Category: Package functs · Category: Sums and products

Function: gaussprob (x)

Returns the Gaussian probability function %e^(-x^2/2) / sqrt(2*%pi).

To use this function write first load(functs).

Category: Package functs · Category: Mathematical functions

Function: gd (x)

Returns the Gudermannian function 2*atan(%e^x)-%pi/2.

To use this function write first load(functs).

Category: Package functs · Category: Mathematical functions

Function: agd (x)

Returns the inverse Gudermannian function log (tan (%pi/4 + x/2)).

To use this function write first load(functs).

Category: Package functs · Category: Mathematical functions

Function: vers (x)

Returns the versed sine 1 - cos (x).

To use this function write first load(functs).

Category: Package functs · Category: Mathematical functions

Function: covers (x)

Returns the coversed sine 1 - sin (x).

To use this function write first load(functs).

Category: Package functs · Category: Mathematical functions

Function: exsec (x)

Returns the exsecant sec (x) - 1.

To use this function write first load(functs).

Category: Package functs · Category: Mathematical functions

Function: hav (x)

Returns the haversine (1 - cos(x))/2.

To use this function write first load(functs).

Category: Package functs · Category: Mathematical functions

Function: combination (n, r)

Returns the number of combinations of n objects taken r at a time.

To use this function write first load(functs).

Category: Package functs · Category: Mathematical functions

Function: permutation (n, r)

Returns the number of permutations of r objects selected from a set of n objects.

To use this function write first load(functs).

Category: Package functs · Category: Mathematical functions

82.5 Package ineq

The ineq package contains simplification rules for inequalities.

Example session:

(%i1) load(ineq)$
tellsimp: warning: rule will treat '+
                          ' as noncommutative and nonassociative.
tellsimp: warning: rule will treat '+
                          ' as noncommutative and nonassociative.
tellsimp: warning: rule will treat '+
                          ' as noncommutative and nonassociative.
tellsimp: warning: rule will treat '+
                          ' as noncommutative and nonassociative.
tellsimp: warning: rule will treat '+
                          ' as noncommutative and nonassociative.
tellsimp: warning: rule will treat '+
                          ' as noncommutative and nonassociative.
tellsimp: warning: rule will treat '+
                          ' as noncommutative and nonassociative.
tellsimp: warning: rule will treat '+
                          ' as noncommutative and nonassociative.

(%i2) a>=4;  /* a sample inequality */
(%o2)                        a >= 4
(%o3)                     b + a > c + 4
(%o4)                       7 x < 7 y
(%o5)                    - 2 x <= - 6 z
                                 2
(%o6)                      1 <= a  + 1
(%o8)                       2 x < 3 x
(%o9)                        a >= b
(%o10)                   a + 3 >= b + 3
(%o11)                       a >= b
(%o12)                     a >= c - b
(%o13)                     b + a >= c
(%o14)                 (- c) + b + a >= 0
(%o15)                   c - b - a <= 0
                               2
(%o16)                  (z - 1)  > - 2 z
                            2
(%o17)                     z  + 1 > 0
(%o18)                        true

(%i19) (b>c)+%; /* add a second, strict inequality */

Be careful about using parentheses around the inequalities: when the user types in (A > B) + (C = 5) the result is A + C > B + 5, but A > B + C = 5 is a syntax error, and (A > B + C) = 5 is something else entirely.

Do disprule (all) to see a complete listing of the rule definitions.

The user will be queried if Maxima is unable to decide the sign of a quantity multiplying an inequality.

The most common mis-feature is illustrated by:

(%i1) eq: a > b;
(%o1)                         a > b

(%i2) 2*eq;
(%o2)                       2 (a > b)

(%i3) % - eq;
(%o3)                         a > b

Another problem is 0 times an inequality; the default to have this turn into 0 has been left alone. However, if you type X*some_inequality and Maxima asks about the sign of X and you respond zero (or z), the program returns X*some_inequality and not use the information that X is 0. You should do ev (%, x: 0) in such a case, as the database will only be used for comparison purposes in decisions, and not for the purpose of evaluating X.

The user may note a slower response when this package is loaded, as the simplifier is forced to examine more rules than without the package, so you might wish to remove the rules after making use of them. Do kill (rules) to eliminate all of the rules (including any that you might have defined); or you may be more selective by killing only some of them; or use remrule on a specific rule.

Note that if you load this package after defining your own rules you will clobber your rules that have the same name. The rules in this package are: *rule1, ..., *rule8, +rule1, ..., +rule18, and you must enclose the rulename in quotes to refer to it, as in remrule ("+", "+rule1") to specifically remove the first rule on "+" or disprule ("*rule2") to display the definition of the second multiplicative rule.

Category: Simplification functions · Category: Rules and patterns · Category: Share packages · Category: Package ineq

82.6 Package rducon

Category: Expressions · Category: Share packages · Category: Package rducon

Function: reduce_consts (expr)

Replaces constant subexpressions of expr with constructed constant atoms, saving the definition of all these constructed constants in the list of equations const_eqns, and returning the modified expr. Those parts of expr are constant which return true when operated on by the function constantp. Hence, before invoking reduce_consts, one should do

declare ([objects to be given the constant property], constant)$

to set up a database of the constant quantities occurring in your expressions.

If you are planning to generate Fortran output after these symbolic calculations, one of the first code sections should be the calculation of all constants. To generate this code segment, do

map ('fortran, const_eqns)$

Variables besides const_eqns which affect reduce_consts are:

const_prefix (default value: xx) is the string of characters used to prefix all symbols generated by reduce_consts to represent constant subexpressions.

const_counter (default value: 1) is the integer index used to generate unique symbols to represent each constant subexpression found by reduce_consts.

load ("rducon") loads this function. demo ("rducon") shows a demonstration of this function.

Category: Package rducon · Category: Expressions

82.7 Package scifac

Category: Expressions · Category: Share packages · Category: Package scifac

Function: gcfac (expr)

gcfac is a factoring function that attempts to apply the same heuristics which scientists apply in trying to make expressions simpler. gcfac is limited to monomial-type factoring. For a sum, gcfac does the following:

Factors over the integers.
Factors out the largest powers of terms occurring as coefficients, regardless of the complexity of the terms.
Uses (1) and (2) in factoring adjacent pairs of terms.
Repeatedly and recursively applies these techniques until the expression no longer changes.

Item (3) does not necessarily do an optimal job of pairwise factoring because of the combinatorially-difficult nature of finding which of all possible rearrangements of the pairs yields the most compact pair-factored result.

load ("scifac") loads this function. demo ("scifac") shows a demonstration of this function.

Category: Package scifac · Category: Expressions

82.8 Package sqdnst

Function: sqrtdenest (expr)

Denests sqrt of simple, numerical, binomial surds, where possible. E.g.

(%i1) load ("sqdnst")$

(%i2) sqrt(sqrt(3)/2+1)/sqrt(11*sqrt(2)-12);
                             sqrt(3)
                        sqrt(------- + 1)
                                2
(%o2)                 ---------------------
                      sqrt(11 sqrt(2) - 12)

(%i3) sqrtdenest(%);
                           sqrt(3)   1
                           ------- + -
                              2      2
(%o3)                     -------------
                             1/4    3/4
                          3 2    - 2

Sometimes it helps to apply sqrtdenest more than once, on such as (19601-13860 sqrt(2))^(7/4).

load ("sqdnst") loads this function.

Category: Expressions · Category: Share packages · Category: Package sqdnst

83 solve_rec

83.1 Introduction to solve_rec

solve_rec is a package for solving linear recurrences with polynomial coefficients.

A demo is available with demo("solve_rec");.

Example:

(%i1) load("solve_rec")$

(%i2) solve_rec((n+4)*s[n+2] + s[n+1] - (n+1)*s[n], s[n]);
                                    n
                 %k  (2 n + 3) (- 1)          %k
                   1                            2
(%o2)       s  = -------------------- + ---------------
             n     (n + 1) (n + 2)      (n + 1) (n + 2)

Category: Linear recurrences · Category: Share packages · Category: Package solve_rec

83.2 Functions and Variables for solve_rec

Function: reduce_order (rec, sol, var)

Reduces the order of linear recurrence rec when a particular solution sol is known. The reduced reccurence can be used to get other solutions.

Example:

(%i3) rec: x[n+2] = x[n+1] + x[n]/n;
                                      x
                                       n
(%o3)               x      = x      + --
                     n + 2    n + 1   n

(%i4) solve_rec(rec, x[n]);
WARNING: found some hypergeometrical solutions! 
(%o4)                    x  = %k  n
                          n     1

(%i5) reduce_order(rec, n, x[n]);
(%t5)                    x  = n %z
                          n       n

                           n - 1
                           ====
                           \
(%t6)                %z  =  >     %u
                       n   /        %j
                           ====
                           %j = 0

(%o6)             (- n - 2) %u     - %u
                              n + 1     n

(%i6) solve_rec((n+2)*%u[n+1] + %u[n], %u[n]);
                                     n
                            %k  (- 1)
                              1
(%o6)                 %u  = ----------
                        n    (n + 1)!

So the general solution is

             n - 1
             ====        j
             \      (- 1)
       %k  n  >    -------- + %k  n
         2   /     (j + 1)!     1
             ====
             j = 0

Category: Package solve_rec

Option variable: simplify_products

Default value: true

If simplify_products is true, solve_rec will try to simplify products in result.

84 stats

84.1 Introduction to stats

Package stats contains a set of classical statistical inference and hypothesis testing procedures.

All these functions return an inference_result Maxima object which contains the necessary results for population inferences and decision making.

Global variable stats_numer controls whether results are given in floating point or symbolic and rational format; its default value is true and results are returned in floating point format.

Package descriptive contains some utilities to manipulate data structures (lists and matrices); for example, to extract subsamples. It also contains some examples on how to use package numericalio to read data from plain text files. See descriptive and numericalio for more details.

Package stats loads packages descriptive, distrib and inference_result.

For comments, bugs or suggestions, please contact the author at

’mario AT edu DOT xunta DOT es’.

Category: Statistical inference · Category: Share packages · Category: Package stats

84.2 Functions and Variables for inference_result

Function: inference_result (title, values, numbers)

Constructs an inference_result object of the type returned by the stats functions. Argument title is a string with the name of the procedure; values is a list with elements of the form symbol = value and numbers is a list with positive integer numbers ranging from one to length(values), indicating which values will be shown by default.

Example:

This is a simple example showing results concerning a rectangle. The title of this object is the string "Rectangle", it stores five results, named 'base, 'height, 'diagonal, 'area, and 'perimeter, but only the first, second, fifth, and fourth will be displayed. The 'diagonal is stored in this object, but it is not displayed; to access its value, make use of function take_inference.

(%i1) load(inference_result)$
(%i2) b: 3$ h: 2$
(%i3) inference_result("Rectangle",
                        ['base=b,
                         'height=h,
                         'diagonal=sqrt(b^2+h^2),
                         'area=b*h,
                         'perimeter=2*(b+h)],
                        [1,2,5,4] );
                        |   Rectangle
                        |
                        |    base = 3
                        |
(%o3)                   |   height = 2
                        |
                        | perimeter = 10
                        |
                        |    area = 6
(%i4) take_inference('diagonal,%);
(%o4)                        sqrt(13)

84.3 Functions and Variables for stats

Option variable: stats_numer

Default value: true

If stats_numer is true, inference statistical functions return their results in floating point numbers. If it is false, results are given in symbolic and rational format.

Category: Package stats · Category: Numerical evaluation

Function: test_mean
test_mean (x)
test_mean (x, options ...)

This is the mean t-test. Argument x is a list or a column matrix containing a one dimensional sample. It also performs an asymptotic test based on the Central Limit Theorem if option 'asymptotic is true.

Options:

'mean, default 0, is the mean value to be checked.
'alternative, default 'twosided, is the alternative hypothesis; valid values are: 'twosided, 'greater and 'less.
'dev, default 'unknown, this is the value of the standard deviation when it is known; valid values are: 'unknown or a positive expression.
'conflevel, default 95/100, confidence level for the confidence interval; it must be an expression which takes a value in (0,1).
'asymptotic, default false, indicates whether it performs an exact t-test or an asymptotic one based on the Central Limit Theorem; valid values are true and false.

The output of function test_mean is an inference_result Maxima object showing the following results:

'mean_estimate: the sample mean.
'conf_level: confidence level selected by the user.
'conf_interval: confidence interval for the population mean.
'method: inference procedure.
'hypotheses: null and alternative hypotheses to be tested.
'statistic: value of the sample statistic used for testing the null hypothesis.
'distribution: distribution of the sample statistic, together with its parameter(s).
'p_value: p-value of the test.

Examples:

Performs an exact t-test with unknown variance. The null hypothesis is H_0: mean=50 against the one sided alternative H_1: mean<50; according to the results, the p-value is too great, there are no evidence for rejecting H_0.

(%i1) load("stats")$
(%i2) data: [78,64,35,45,45,75,43,74,42,42]$
(%i3) test_mean(data,'conflevel=0.9,'alternative='less,'mean=50);
          |                 MEAN TEST
          |
          |            mean_estimate = 54.3
          |
          |              conf_level = 0.9
          |
          | conf_interval = [minf, 61.51314273502712]
          |
(%o3)     |  method = Exact t-test. Unknown variance.
          |
          | hypotheses = H0: mean = 50 , H1: mean < 50
          |
          |       statistic = .8244705235071678
          |
          |       distribution = [student_t, 9]
          |
          |        p_value = .7845100411786889

This time Maxima performs an asymptotic test, based on the Central Limit Theorem. The null hypothesis is H_0: equal(mean, 50) against the two sided alternative H_1: not equal(mean, 50); according to the results, the p-value is very small, H_0 should be rejected in favor of the alternative H_1. Note that, as indicated by the Method component, this procedure should be applied to large samples.

(%i1) load("stats")$
(%i2) test_mean([36,118,52,87,35,256,56,178,57,57,89,34,25,98,35,
              98,41,45,198,54,79,63,35,45,44,75,42,75,45,45,
              45,51,123,54,151],
              'asymptotic=true,'mean=50);
          |                       MEAN TEST
          |
          |           mean_estimate = 74.88571428571429
          |
          |                   conf_level = 0.95
          |
          | conf_interval = [57.72848600856194, 92.04294256286663]
          |
(%o2)     |    method = Large sample z-test. Unknown variance.
          |
          |       hypotheses = H0: mean = 50 , H1: mean # 50
          |
          |             statistic = 2.842831192874313
          |
          |             distribution = [normal, 0, 1]
          |
          |             p_value = .004471474652002261

Function: test_means_difference
test_means_difference (x1, x2)
test_means_difference (x1, x2, options ...)

This is the difference of means t-test for two samples. Arguments x1 and x2 are lists or column matrices containing two independent samples. In case of different unknown variances (see options 'dev1, 'dev2 and 'varequal bellow), the degrees of freedom are computed by means of the Welch approximation. It also performs an asymptotic test based on the Central Limit Theorem if option 'asymptotic is set to true.

Options:

'alternative, default 'twosided, is the alternative hypothesis; valid values are: 'twosided, 'greater and 'less.
'dev1, default 'unknown, this is the value of the standard deviation of the x1 sample when it is known; valid values are: 'unknown or a positive expression.
'dev2, default 'unknown, this is the value of the standard deviation of the x2 sample when it is known; valid values are: 'unknown or a positive expression.
'varequal, default false, whether variances should be considered to be equal or not; this option takes effect only when 'dev1 and/or 'dev2 are 'unknown.
'conflevel, default 95/100, confidence level for the confidence interval; it must be an expression which takes a value in (0,1).
'asymptotic, default false, indicates whether it performs an exact t-test or an asymptotic one based on the Central Limit Theorem; valid values are true and false.

The output of function test_means_difference is an inference_result Maxima object showing the following results:

'diff_estimate: the difference of means estimate.
'conf_level: confidence level selected by the user.
'conf_interval: confidence interval for the difference of means.
'method: inference procedure.
'hypotheses: null and alternative hypotheses to be tested.
'statistic: value of the sample statistic used for testing the null hypothesis.
'distribution: distribution of the sample statistic, together with its parameter(s).
'p_value: p-value of the test.

Examples:

The equality of means is tested with two small samples x and y, against the alternative H_1: m_1>m_2, being m_1 and m_2 the populations means; variances are unknown and supposed to be different.

(%i1) load("stats")$
(%i2) x: [20.4,62.5,61.3,44.2,11.1,23.7]$
(%i3) y: [1.2,6.9,38.7,20.4,17.2]$
(%i4) test_means_difference(x,y,'alternative='greater);
            |              DIFFERENCE OF MEANS TEST
            |
            |         diff_estimate = 20.31999999999999
            |
            |                 conf_level = 0.95
            |
            |    conf_interval = [- .04597417812882298, inf]
            |
(%o4)       |        method = Exact t-test. Welch approx.
            |
            | hypotheses = H0: mean1 = mean2 , H1: mean1 > mean2
            |
            |           statistic = 1.838004300728477
            |
            |    distribution = [student_t, 8.62758740184604]
            |
            |            p_value = .05032746527991905

The same test as before, but now variances are supposed to be equal.

(%i1) load("stats")$
(%i2) x: [20.4,62.5,61.3,44.2,11.1,23.7]$
(%i3) y: matrix([1.2],[6.9],[38.7],[20.4],[17.2])$
(%i4) test_means_difference(x,y,'alternative='greater,
                                                 'varequal=true);
            |              DIFFERENCE OF MEANS TEST
            |
            |         diff_estimate = 20.31999999999999
            |
            |                 conf_level = 0.95
            |
            |     conf_interval = [- .7722627696897568, inf]
            |
(%o4)       |   method = Exact t-test. Unknown equal variances
            |
            | hypotheses = H0: mean1 = mean2 , H1: mean1 > mean2
            |
            |           statistic = 1.765996124515009
            |
            |           distribution = [student_t, 9]
            |
            |            p_value = .05560320992529344

Function: test_variance
test_variance (x)
test_variance (x, options, ...)

This is the variance chi^2-test. Argument x is a list or a column matrix containing a one dimensional sample taken from a normal population.

Options:

'mean, default 'unknown, is the population’s mean, when it is known.
'alternative, default 'twosided, is the alternative hypothesis; valid values are: 'twosided, 'greater and 'less.
'variance, default 1, this is the variance value (positive) to be checked.
'conflevel, default 95/100, confidence level for the confidence interval; it must be an expression which takes a value in (0,1).

The output of function test_variance is an inference_result Maxima object showing the following results:

'var_estimate: the sample variance.
'conf_level: confidence level selected by the user.
'conf_interval: confidence interval for the population variance.
'method: inference procedure.
'hypotheses: null and alternative hypotheses to be tested.
'statistic: value of the sample statistic used for testing the null hypothesis.
'distribution: distribution of the sample statistic, together with its parameter.
'p_value: p-value of the test.

Examples:

It is tested whether the variance of a population with unknown mean is equal to or greater than 200.

(%i1) load("stats")$
(%i2) x: [203,229,215,220,223,233,208,228,209]$
(%i3) test_variance(x,'alternative='greater,'variance=200);
             |                  VARIANCE TEST
             |
             |              var_estimate = 110.75
             |
             |                conf_level = 0.95
             |
             |     conf_interval = [57.13433376937479, inf]
             |
(%o3)        | method = Variance Chi-square test. Unknown mean.
             |
             |    hypotheses = H0: var = 200 , H1: var > 200
             |
             |                 statistic = 4.43
             |
             |             distribution = [chi2, 8]
             |
             |           p_value = .8163948512777689

Function: test_variance_ratio
test_variance_ratio (x1, x2)
test_variance_ratio (x1, x2, options ...)

This is the variance ratio F-test for two normal populations. Arguments x1 and x2 are lists or column matrices containing two independent samples.

Options:

'alternative, default 'twosided, is the alternative hypothesis; valid values are: 'twosided, 'greater and 'less.
'mean1, default 'unknown, when it is known, this is the mean of the population from which x1 was taken.
'mean2, default 'unknown, when it is known, this is the mean of the population from which x2 was taken.
'conflevel, default 95/100, confidence level for the confidence interval of the ratio; it must be an expression which takes a value in (0,1).

The output of function test_variance_ratio is an inference_result Maxima object showing the following results:

'ratio_estimate: the sample variance ratio.
'conf_level: confidence level selected by the user.
'conf_interval: confidence interval for the variance ratio.
'method: inference procedure.
'hypotheses: null and alternative hypotheses to be tested.
'statistic: value of the sample statistic used for testing the null hypothesis.
'distribution: distribution of the sample statistic, together with its parameters.
'p_value: p-value of the test.

Examples:

The equality of the variances of two normal populations is checked against the alternative that the first is greater than the second.

(%i1) load("stats")$
(%i2) x: [20.4,62.5,61.3,44.2,11.1,23.7]$
(%i3) y: [1.2,6.9,38.7,20.4,17.2]$
(%i4) test_variance_ratio(x,y,'alternative='greater);
              |              VARIANCE RATIO TEST
              |
              |       ratio_estimate = 2.316933391522034
              |
              |               conf_level = 0.95
              |
              |    conf_interval = [.3703504689507268, inf]
              |
(%o4)         | method = Variance ratio F-test. Unknown means.
              |
              | hypotheses = H0: var1 = var2 , H1: var1 > var2
              |
              |         statistic = 2.316933391522034
              |
              |            distribution = [f, 5, 4]
              |
              |          p_value = .2179269692254457

Function: test_proportion
test_proportion (x, n)
test_proportion (x, n, options ...)

Inferences on a proportion. Argument x is the number of successes in n trials in a Bernoulli experiment with unknown probability.

Options:

'proportion, default 1/2, is the value of the proportion to be checked.
'alternative, default 'twosided, is the alternative hypothesis; valid values are: 'twosided, 'greater and 'less.
'conflevel, default 95/100, confidence level for the confidence interval; it must be an expression which takes a value in (0,1).
'asymptotic, default false, indicates whether it performs an exact test based on the binomial distribution, or an asymptotic one based on the Central Limit Theorem; valid values are true and false.
'correct, default true, indicates whether Yates correction is applied or not.

The output of function test_proportion is an inference_result Maxima object showing the following results:

'sample_proportion: the sample proportion.
'conf_level: confidence level selected by the user.
'conf_interval: Wilson confidence interval for the proportion.
'method: inference procedure.
'hypotheses: null and alternative hypotheses to be tested.
'statistic: value of the sample statistic used for testing the null hypothesis.
'distribution: distribution of the sample statistic, together with its parameters.
'p_value: p-value of the test.

Examples:

Performs an exact test. The null hypothesis is H_0: p=1/2 against the one sided alternative H_1: p<1/2.

(%i1) load("stats")$
(%i2) test_proportion(45, 103, alternative = less);
         |            PROPORTION TEST              
         |                                         
         | sample_proportion = .4368932038834951   
         |                                         
         |           conf_level = 0.95             
         |                                         
         | conf_interval = [0, 0.522714149150231]  
         |                                         
(%o2)    |     method = Exact binomial test.       
         |                                         
         | hypotheses = H0: p = 0.5 , H1: p < 0.5  
         |                                         
         |             statistic = 45              
         |                                         
         |  distribution = [binomial, 103, 0.5]    
         |                                         
         |      p_value = .1184509388901454

A two sided asymptotic test. Confidence level is 99/100.

(%i1) load("stats")$
(%i2) fpprintprec:7$
(%i3) test_proportion(45, 103, 
                  conflevel = 99/100, asymptotic=true);
      |                 PROPORTION TEST                  
      |                                                  
      |           sample_proportion = .43689             
      |                                                  
      |                conf_level = 0.99                 
      |                                                  
      |        conf_interval = [.31422, .56749]          
      |                                                  
(%o3) | method = Asympthotic test with Yates correction.
      |                                                  
      |     hypotheses = H0: p = 0.5 , H1: p # 0.5       
      |                                                  
      |               statistic = .43689                 
      |                                                  
      |      distribution = [normal, 0.5, .048872]       
      |                                                  
      |                p_value = .19662

Function: test_proportions_difference
test_proportions_difference (x1, n1, x2, n2)
test_proportions_difference (x1, n1, x2, n2, options …)

Inferences on the difference of two proportions. Argument x1 is the number of successes in n1 trials in a Bernoulli experiment in the first population, and x2 and n2 are the corresponding values in the second population. Samples are independent and the test is asymptotic.

Options:

'alternative, default 'twosided, is the alternative hypothesis; valid values are: 'twosided (p1 # p2), 'greater (p1 > p2) and 'less (p1 < p2).
'conflevel, default 95/100, confidence level for the confidence interval; it must be an expression which takes a value in (0,1).
'correct, default true, indicates whether Yates correction is applied or not.

The output of function test_proportions_difference is an inference_result Maxima object showing the following results:

'proportions: list with the two sample proportions.
'conf_level: confidence level selected by the user.
'conf_interval: Confidence interval for the difference of proportions p1 - p2.
'method: inference procedure and warning message in case of any of the samples sizes is less than 10.
'hypotheses: null and alternative hypotheses to be tested.
'statistic: value of the sample statistic used for testing the null hypothesis.
'distribution: distribution of the sample statistic, together with its parameters.
'p_value: p-value of the test.

Examples:

A machine produced 10 defective articles in a batch of 250. After some maintenance work, it produces 4 defective in a batch of 150. In order to know if the machine has improved, we test the null hypothesis H0:p1=p2, against the alternative H0:p1>p2, where p1 and p2 are the probabilities for one produced article to be defective before and after maintenance. According to the p value, there is not enough evidence to accept the alternative.

(%i1) load("stats")$
(%i2) fpprintprec:7$
(%i3) test_proportions_difference(10, 250, 4, 150,
                                alternative = greater);
      |       DIFFERENCE OF PROPORTIONS TEST         
      |                                              
      |       proportions = [0.04, .02666667]        
      |                                              
      |              conf_level = 0.95               
      |                                              
      |      conf_interval = [- .02172761, 1]        
      |                                              
(%o3) | method = Asymptotic test. Yates correction.  
      |                                              
      |   hypotheses = H0: p1 = p2 , H1: p1 > p2     
      |                                              
      |            statistic = .01333333             
      |                                              
      |    distribution = [normal, 0, .01898069]     
      |                                              
      |             p_value = .2411936

Exact standard deviation of the asymptotic normal distribution when the data are unknown.

(%i1) load("stats")$
(%i2) stats_numer: false$
(%i3) sol: test_proportions_difference(x1,n1,x2,n2)$
(%i4) last(take_inference('distribution,sol));
               1    1                  x2 + x1
              (-- + --) (x2 + x1) (1 - -------)
               n2   n1                 n2 + n1
(%o4)    sqrt(---------------------------------)
                           n2 + n1

Function: test_sign
test_sign (x)
test_sign (x, options …)

This is the non parametric sign test for the median of a continuous population. Argument x is a list or a column matrix containing a one dimensional sample.

Options:

'alternative, default 'twosided, is the alternative hypothesis; valid values are: 'twosided, 'greater and 'less.
'median, default 0, is the median value to be checked.

The output of function test_sign is an inference_result Maxima object showing the following results:

'med_estimate: the sample median.
'method: inference procedure.
'hypotheses: null and alternative hypotheses to be tested.
'statistic: value of the sample statistic used for testing the null hypothesis.
'distribution: distribution of the sample statistic, together with its parameter(s).
'p_value: p-value of the test.

Examples:

Checks whether the population from which the sample was taken has median 6, against the alternative H_1: median > 6.

(%i1) load("stats")$
(%i2) x: [2,0.1,7,1.8,4,2.3,5.6,7.4,5.1,6.1,6]$
(%i3) test_sign(x,'median=6,'alternative='greater);
               |                  SIGN TEST
               |
               |              med_estimate = 5.1
               |
               |      method = Non parametric sign test.
               |
(%o3)          | hypotheses = H0: median = 6 , H1: median > 6
               |
               |                statistic = 7
               |
               |      distribution = [binomial, 10, 0.5]
               |
               |         p_value = .05468749999999989

Function: test_signed_rank
test_signed_rank (x)
test_signed_rank (x, options …)

This is the Wilcoxon signed rank test to make inferences about the median of a continuous population. Argument x is a list or a column matrix containing a one dimensional sample. Performs normal approximation if the sample size is greater than 20, or if there are zeroes or ties.

See also pdf_rank_test and cdf_rank_test

Options:

'median, default 0, is the median value to be checked.
'alternative, default 'twosided, is the alternative hypothesis; valid values are: 'twosided, 'greater and 'less.

The output of function test_signed_rank is an inference_result Maxima object with the following results:

'med_estimate: the sample median.
'method: inference procedure.
'hypotheses: null and alternative hypotheses to be tested.
'statistic: value of the sample statistic used for testing the null hypothesis.
'distribution: distribution of the sample statistic, together with its parameter(s).
'p_value: p-value of the test.

Examples:

Checks the null hypothesis H_0: median = 15 against the alternative H_1: median > 15. This is an exact test, since there are no ties.

(%i1) load("stats")$
(%i2) x: [17.1,15.9,13.7,13.4,15.5,17.6]$
(%i3) test_signed_rank(x,median=15,alternative=greater);
                 |             SIGNED RANK TEST
                 |
                 |           med_estimate = 15.7
                 |
                 |           method = Exact test
                 |
(%o3)            | hypotheses = H0: med = 15 , H1: med > 15
                 |
                 |              statistic = 14
                 |
                 |     distribution = [signed_rank, 6]
                 |
                 |            p_value = 0.28125

Checks the null hypothesis H_0: equal(median, 2.5) against the alternative H_1: not equal(median, 2.5). This is an approximated test, since there are ties.

(%i1) load("stats")$
(%i2) y:[1.9,2.3,2.6,1.9,1.6,3.3,4.2,4,2.4,2.9,1.5,3,2.9,4.2,3.1]$
(%i3) test_signed_rank(y,median=2.5);
             |                 SIGNED RANK TEST
             |
             |                med_estimate = 2.9
             |
             |          method = Asymptotic test. Ties
             |
(%o3)        |    hypotheses = H0: med = 2.5 , H1: med # 2.5
             |
             |                 statistic = 76.5
             |
             | distribution = [normal, 60.5, 17.58195097251724]
             |
             |           p_value = .3628097734643669

Function: test_rank_sum
test_rank_sum (x1, x2)
test_rank_sum (x1, x2, option)

This is the Wilcoxon-Mann-Whitney test for comparing the medians of two continuous populations. The first two arguments x1 and x2 are lists or column matrices with the data of two independent samples. Performs normal approximation if any of the sample sizes is greater than 10, or if there are ties.

Option:

'alternative, default 'twosided, is the alternative hypothesis; valid values are: 'twosided, 'greater and 'less.

The output of function test_rank_sum is an inference_result Maxima object with the following results:

'method: inference procedure.
'hypotheses: null and alternative hypotheses to be tested.
'statistic: value of the sample statistic used for testing the null hypothesis.
'distribution: distribution of the sample statistic, together with its parameters.
'p_value: p-value of the test.

Examples:

Checks whether populations have similar medians. Samples sizes are small and an exact test is made.

(%i1) load("stats")$
(%i2) x:[12,15,17,38,42,10,23,35,28]$
(%i3) y:[21,18,25,14,52,65,40,43]$
(%i4) test_rank_sum(x,y);
              |                 RANK SUM TEST
              |
              |              method = Exact test
              |
              | hypotheses = H0: med1 = med2 , H1: med1 # med2
(%o4)         |
              |                 statistic = 22
              |
              |        distribution = [rank_sum, 9, 8]
              |
              |          p_value = .1995886466474702

Now, with greater samples and ties, the procedure makes normal approximation. The alternative hypothesis is H_1: median1 < median2.

(%i1) load("stats")$
(%i2) x: [39,42,35,13,10,23,15,20,17,27]$
(%i3) y: [20,52,66,19,41,32,44,25,14,39,43,35,19,56,27,15]$
(%i4) test_rank_sum(x,y,'alternative='less);
             |                  RANK SUM TEST
             |
             |          method = Asymptotic test. Ties
             |
             |  hypotheses = H0: med1 = med2 , H1: med1 < med2
(%o4)        |
             |                 statistic = 48.5
             |
             | distribution = [normal, 79.5, 18.95419580097078]
             |
             |           p_value = .05096985666598441

Function: test_normality (x)

Shapiro-Wilk test for normality. Argument x is a list of numbers, and sample size must be greater than 2 and less or equal than 5000, otherwise, function test_normality signals an error message.

Reference:

[1] Algorithm AS R94, Applied Statistics (1995), vol.44, no.4, 547-551

The output of function test_normality is an inference_result Maxima object with the following results:

'statistic: value of the W statistic.
'p_value: p-value under normal assumption.

Examples:

Checks for the normality of a population, based on a sample of size 9.

(%i1) load("stats")$
(%i2) x:[12,15,17,38,42,10,23,35,28]$
(%i3) test_normality(x);
                       |      SHAPIRO - WILK TEST
                       |
(%o3)                  | statistic = .9251055695162436
                       |
                       |  p_value = .4361763918860381

Category: Package stats · Category: Statistical estimation

Function: linear_regression
linear_regression (x)
linear_regression (x option)

Multivariate linear regression, y_i = b0 + b1*x_1i + b2*x_2i + ... + bk*x_ki + u_i, where u_i are N(0,sigma) independent random variables. Argument x must be a matrix with more than one column. The last column is considered as the responses (y_i).

Option:

'conflevel, default 95/100, confidence level for the confidence intervals; it must be an expression which takes a value in (0,1).

The output of function linear_regression is an inference_result Maxima object with the following results:

'b_estimation: regression coefficients estimates.
'b_covariances: covariance matrix of the regression coefficients estimates.
b_conf_int: confidence intervals of the regression coefficients.
b_statistics: statistics for testing coefficient.
b_p_values: p-values for coefficient tests.
b_distribution: probability distribution for coefficient tests.
v_estimation: unbiased variance estimator.
v_conf_int: variance confidence interval.
v_distribution: probability distribution for variance test.
residuals: residuals.
adc: adjusted determination coefficient.
aic: Akaike’s information criterion.
bic: Bayes’s information criterion.

Only items 1, 4, 5, 6, 7, 8, 9 and 11 above, in this order, are shown by default. The rest remain hidden until the user makes use of functions items_inference and take_inference.

Example:

Fitting a linear model to a trivariate sample. The last column is considered as the responses (y_i).

(%i2) load("stats")$
(%i3) X:matrix(
    [58,111,64],[84,131,78],[78,158,83],
    [81,147,88],[82,121,89],[102,165,99],
    [85,174,101],[102,169,102])$
(%i4) fpprintprec: 4$
(%i5) res: linear_regression(X);
             |       LINEAR REGRESSION MODEL         
             |                                       
             | b_estimation = [9.054, .5203, .2397]  
             |                                       
             | b_statistics = [.6051, 2.246, 1.74]   
             |                                       
             | b_p_values = [.5715, .07466, .1423]   
             |                                       
(%o5)        |   b_distribution = [student_t, 5]     
             |                                       
             |         v_estimation = 35.27          
             |                                       
             |     v_conf_int = [13.74, 212.2]       
             |                                       
             |      v_distribution = [chi2, 5]       
             |                                       
             |             adc = .7922               
(%i6) items_inference(res);
(%o6) [b_estimation, b_covariances, b_conf_int, b_statistics, 
b_p_values, b_distribution, v_estimation, v_conf_int, 
v_distribution, residuals, adc, aic, bic]
(%i7) take_inference('b_covariances, res);
                  [  223.9    - 1.12   - .8532  ]
                  [                             ]
(%o7)             [ - 1.12    .05367   - .02305 ]
                  [                             ]
                  [ - .8532  - .02305   .01898  ]
(%i8) take_inference('bic, res);
(%o8)                          30.98
(%i9) load("draw")$
(%i10) draw2d(
    points_joined = true,
    grid = true,
    points(take_inference('residuals, res)) )$

84.4 Functions and Variables for special distributions

Function: pdf_signed_rank (x, n)

Probability density function of the exact distribution of the signed rank statistic. Argument x is a real number and n a positive integer.

85 stirling

85.1 Functions and Variables for stirling

Function: stirling
stirling (z,n)
stirling (z,n,pred)

Replace gamma(x) with the O(1/x^(2n-1)) Stirling formula. when n isn’t a nonnegative integer, signal an error. With the optional third argument pred, the Stirling formula is applied only when pred is true.

Reference: Abramowitz & Stegun, " Handbook of mathematical functions", 6.1.40.

Examples:

(%i1) load ("stirling")$

(%i2) stirling(gamma(%alpha+x)/gamma(x),1);
       1/2 - x             x + %alpha - 1/2
(%o2) x        (x + %alpha)
                                   1           1
                            --------------- - ---- - %alpha
                            12 (x + %alpha)   12 x
                          %e
(%i3) taylor(%,x,inf,1);
                    %alpha       2    %alpha
          %alpha   x       %alpha  - x       %alpha
(%o3)/T/ x       + -------------------------------- + . . .
                                 2 x
(%i4) map('factor,%);
                                       %alpha - 1
         %alpha   (%alpha - 1) %alpha x
(%o4)   x       + -------------------------------
                                  2

The function stirling knows the difference between the variable ’gamma’ and the function gamma:

(%i5) stirling(gamma + gamma(x),0);
                                    x - 1/2   - x
(%o5)    gamma + sqrt(2) sqrt(%pi) x        %e
(%i6) stirling(gamma(y) + gamma(x),0);
                         y - 1/2   - y
(%o6) sqrt(2) sqrt(%pi) y        %e
                                              x - 1/2   - x
                         + sqrt(2) sqrt(%pi) x        %e

To apply the Stirling formula only to terms that involve the variable k, use an optional third argument; for example

(%i7) makegamma(pochhammer(a,k)/pochhammer(b,k));
(%o7) (gamma(b)*gamma(k+a))/(gamma(a)*gamma(k+b))
(%i8) stirling(%,1, lambda([s], not(freeof(k,s))));
(%o8) (%e^(b-a)*gamma(b)*(k+a)^(k+a-1/2)*(k+b)^(-k-b+1/2))/gamma(a)

The terms gamma(a) and gamma(b) are free of k, so the Stirling formula was not applied to these two terms.

To use this function write first load("stirling").

Category: Gamma and factorial functions · Category: Share packages · Category: Package stirling

86 stringproc

86.1 Introduction to String Processing

The package stringproc contains functions for processing strings and characters including formatting, encoding and data streams. This package is completed by some tools for cryptography, e.g. base64 and hash functions.

It can be directly loaded via load(stringproc) or automatically by using one of its functions.

For questions and bug reports please contact the author. The following command prints his e-mail-address.

printf(true, "~{~a~}@gmail.com", split(sdowncase("Volker van Nek")))$

A string is constructed by typing e.g. "Text". When the option variable stringdisp is set to false, which is the default, the double quotes won’t be printed. stringp is a test, if an object is a string.

(%i1) str: "Text";
(%o1)                         Text
(%i2) stringp(str);
(%o2)                         true

Characters are represented by a string of length 1. charp is the corresponding test.

(%i1) char: "e";
(%o1)                           e
(%i2) charp(char);
(%o2)                         true

In Maxima position indices in strings are like in list 1-indexed which results to the following consistency.

(%i1) is(charat("Lisp",1) = charlist("Lisp")[1]);
(%o1)                         true

A string may contain Maxima expressions. These can be parsed with parse_string.

(%i1) map(parse_string, ["42" ,"sqrt(2)", "%pi"]);
(%o1)                   [42, sqrt(2), %pi]
(%i2) map('float, %);
(%o2)        [42.0, 1.414213562373095, 3.141592653589793]

Strings can be processed as characters or in binary form as octets. Functions for conversions are string_to_octets and octets_to_string. Usable encodings depend on the platform, the application and the underlying Lisp. (The following shows Maxima in GNU/Linux, compiled with SBCL.)

(%i1) obase: 16.$
(%i2) string_to_octets("$£€", "cp1252");
(%o2)                     [24, 0A3, 80]
(%i3) string_to_octets("$£€", "utf-8");
(%o3)               [24, 0C2, 0A3, 0E2, 82, 0AC]

Strings may be written to character streams or as octets to binary streams. The following example demonstrates file in and output of characters.

openw returns an output stream to a file, printf writes formatted to that file and by e.g. close all characters contained in the stream are written to the file.

(%i1) s: openw("file.txt");
(%o1)                #<output stream file.txt>
(%i2) printf(s, "~%~d ~f ~a ~a ~f ~e ~a~%", 
42, 1.234, sqrt(2), %pi, 1.0e-2, 1.0e-2, 1.0b-2)$
(%i3) close(s)$

openr then returns an input stream from the previously used file and readline returns the line read as a string. The string may be tokenized by e.g. split or tokens and finally parsed by parse_string.

(%i4) s: openr("file.txt");
(%o4)                 #<input stream file.txt>
(%i5) readline(s);
(%o5)          42 1.234 sqrt(2) %pi 0.01 1.0E-2 1.0b-2
(%i6) map(parse_string, split(%));
(%o6)       [42, 1.234, sqrt(2), %pi, 0.01, 0.01, 1.0b-2]
(%i7) close(s)$

Category: Strings · Category: Share packages · Category: Package stringproc

86.2 Input and Output

Example: Formatted printing to a file.

(%i1) s: openw("file.txt");
(%o1)                      #<output stream file.txt>
(%i2) control: 
"~2tAn atom: ~20t~a~%~2tand a list: ~20t~{~r ~}~%~2t\
and an integer: ~20t~d~%"$
(%i3) printf( s,control, 'true,[1,2,3],42 )$
(%o3)                                false
(%i4) close(s);
(%o4)                                true
(%i5) s: openr("file.txt");
(%o5)                      #<input stream file.txt>
(%i6) while stringp( tmp:readline(s) ) do print(tmp)$
  An atom:          true 
  and a list:       one two three  
  and an integer:   42 
(%i7) close(s)$

Function: close (stream)

Closes stream and returns true if stream had been open.

Category: File input · Category: File output · Category: Package stringproc

Function: flength (stream)

stream has to be an open stream from or to a file. flength then returns the number of bytes which are currently present in this file.

Example: See writebyte .

Category: File input · Category: File output · Category: Package stringproc

Function: flush_output (stream)

Flushes stream where stream has to be an output stream to a file.

Example: See writebyte .

Category: File output · Category: Package stringproc

Function: fposition
fposition (stream)
fposition (stream, pos)

Returns the current position in stream, if pos is not used. If pos is used, fposition sets the position in stream. stream has to be a stream from or to a file and pos has to be a positive number.

Positions in data streams are like in strings or lists 1-indexed, i.e. the first element in stream is in position 1.

Category: File input · Category: File output · Category: Package stringproc

Function: freshline
freshline ()
freshline (stream)

Writes a new line to the standard output stream if the position is not at the beginning of a line und returns true. Using the optional argument stream the new line is written to that stream. There are some cases, where freshline() does not work as expected.

86.3 Characters

Characters are strings of length 1.

Function: adjust_external_format ()

Prints information about the current external format of the Lisp reader and in case the external format encoding differs from the encoding of the application which runs Maxima adjust_external_format tries to adjust the encoding or prints some help or instruction. adjust_external_format returns true when the external format has been changed and false otherwise.

Functions like cint, unicode, octets_to_string and string_to_octets need UTF-8 as the external format of the Lisp reader to work properly over the full range of Unicode characters.

Examples (Maxima on Windows, March 2016): Using adjust_external_format when the default external format is not equal to the encoding provided by the application.

1. Command line Maxima

In case a terminal session is preferred it is recommended to use Maxima compiled with SBCL. Here Unicode support is provided by default and calls to adjust_external_format are unnecessary.

If Maxima is compiled with CLISP or GCL it is recommended to change the terminal encoding from CP850 to CP1252. adjust_external_format prints some help.

CCL reads UTF-8 while the terminal input is CP850 by default. CP1252 is not supported by CCL. adjust_external_format prints instructions for changing the terminal encoding and external format both to iso-8859-1.

2. wxMaxima

In wxMaxima SBCL reads CP1252 by default but the input from the application is UTF-8 encoded. Adjustment is needed.

Calling adjust_external_format and restarting Maxima permanently changes the default external format to UTF-8.

(%i1)adjust_external_format();
The line
(setf sb-impl::*default-external-format* :utf-8)
has been appended to the init file
C:/Users/Username/.sbclrc
Please restart Maxima to set the external format to UTF-8.
(%i1) false

Restarting Maxima.

(%i1) adjust_external_format();
The external format is currently UTF-8
and has not been changed.
(%i1) false

Category: Predicate functions · Category: Package stringproc

Function: alphacharp (char)

Returns true if char is an alphabetic character.

To identify a non-US-ASCII character as an alphabetic character the underlying Lisp must provide full Unicode support. E.g. a German umlaut is detected as an alphabetic character with SBCL in GNU/Linux but not with GCL. (In Windows Maxima, when compiled with SBCL, must be set to UTF-8. See adjust_external_format for more.)

Example: Examination of non-US-ASCII characters.

The underlying Lisp (SBCL, GNU/Linux) is able to convert the typed character into a Lisp character and to examine.

(%i1) alphacharp("ü");
(%o1)                          true

In GCL this is not possible. An error break occurs.

(%i1) alphacharp("u");
(%o1)                          true
(%i2) alphacharp("ü");

package stringproc: ü cannot be converted into a Lisp character.
 -- an error.

Function: alphanumericp (char)

Returns true if char is an alphabetic character or a digit (only corresponding US-ASCII characters are regarded as digits).

Note: See remarks on alphacharp.

Category: Predicate functions · Category: Package stringproc

Function: ascii (int)

Returns the US-ASCII character corresponding to the integer int which has to be less than 128.

See unicode for converting code points larger than 127.

Examples:

(%i1) for n from 0 thru 127 do ( 
        ch: ascii(n), 
        if alphacharp(ch) then sprint(ch),
        if n = 96 then newline() )$
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 
a b c d e f g h i j k l m n o p q r s t u v w x y z

Category: Predicate functions · Category: Package stringproc

Function: cequal (char_1, char_2)

Returns true if char_1 and char_2 are the same character.

Function: cequalignore (char_1, char_2)

Like cequal but ignores case which is only possible for non-US-ASCII characters when the underlying Lisp is able to recognize a character as an alphabetic character. See remarks on alphacharp.

Category: Predicate functions · Category: Package stringproc

Function: cgreaterp (char_1, char_2)

Returns true if the code point of char_1 is greater than the code point of char_2.

Category: Predicate functions · Category: Package stringproc

Function: cgreaterpignore (char_1, char_2)

Like cgreaterp but ignores case which is only possible for non-US-ASCII characters when the underlying Lisp is able to recognize a character as an alphabetic character. See remarks on alphacharp.

Category: Predicate functions · Category: Package stringproc

Function: charp (obj)

Returns true if obj is a Maxima-character. See introduction for example.

Category: Predicate functions · Category: Package stringproc

Function: cint (char)

Returns the Unicode code point of char which must be a Maxima character, i.e. a string of length 1.

Examples: The hexadecimal code point of some characters (Maxima with SBCL on GNU/Linux).

(%i1) obase: 16.$
(%i2) map(cint, ["$","£","€"]);
(%o2)                           [24, 0A3, 20AC]

Warning: It is not possible to enter characters corresponding to code points larger than 16 bit in wxMaxima with SBCL on Windows when the external format has not been set to UTF-8. See adjust_external_format.

CMUCL doesn’t process these characters as one character. cint then returns false. Converting a character to a code point via UTF-8-octets may serve as a workaround:

utf8_to_unicode(string_to_octets(character));

See utf8_to_unicode, string_to_octets.

Category: Predicate functions · Category: Package stringproc

Function: clessp (char_1, char_2)

Returns true if the code point of char_1 is less than the code point of char_2.

Function: clesspignore (char_1, char_2)

Like clessp but ignores case which is only possible for non-US-ASCII characters when the underlying Lisp is able to recognize a character as an alphabetic character. See remarks on alphacharp.

Category: Predicate functions · Category: Package stringproc

Function: constituent (char)

Returns true if char is a graphic character but not a space character. A graphic character is a character one can see, plus the space character. (constituent is defined by Paul Graham. See Paul Graham, ANSI Common Lisp, 1996, page 67.)

(%i1) for n from 0 thru 255 do ( 
tmp: ascii(n), if constituent(tmp) then sprint(tmp) )$
! " #  %  ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B
C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c
d e f g h i j k l m n o p q r s t u v w x y z { | } ~

Category: Predicate functions · Category: Package stringproc

Function: digitcharp (char)

Returns true if char is a digit where only the corresponding US-ASCII-character is regarded as a digit.

Category: Predicate functions · Category: Package stringproc

Function: lowercasep (char)

Returns true if char is a lowercase character.

Note: See remarks on alphacharp.

Category: Predicate functions · Category: Package stringproc

Variable: newline

The newline character (ASCII-character 10).

Category: Global variables · Category: Package stringproc

Variable: space

The space character.

Category: Global variables · Category: Package stringproc

Variable: tab

The tab character.

Category: Global variables · Category: Package stringproc

Function: unicode (arg)

Returns the character defined by arg which might be a Unicode code point or a name string if the underlying Lisp provides full Unicode support.

Example: Characters defined by hexadecimal code points (Maxima with SBCL on GNU/Linux).

(%i1) ibase: 16.$
(%i2) map(unicode, [24, 0A3, 20AC]);
(%o2)                            [$, £, €]

Warning: In wxMaxima with SBCL on Windows it is not possible to convert code points larger than 16 bit to characters when the external format has not been set to UTF-8. See adjust_external_format for more information.

CMUCL doesn’t process code points larger than 16 bit. In these cases unicode returns false. Converting a code point to a character via UTF-8 octets may serve as a workaround:

octets_to_string(unicode_to_utf8(code_point));

See octets_to_string, unicode_to_utf8.

In case the underlying Lisp provides full Unicode support the character might be specified by its name. The following is possible in ECL, CLISP and SBCL, where in SBCL on Windows the external format has to be set to UTF-8. unicode(name) is supported by CMUCL too but again limited to 16 bit characters.

The string argument to unicode is basically the same string returned by printf using the "~@c" specifier. But as shown below the prefix "#\" must be omitted. Underlines might be replaced by spaces and uppercase letters by lowercase ones.

Example (continued): Characters defined by names (Maxima with SBCL on GNU/Linux).

(%i3) printf(false, "~@c", unicode(0DF));
(%o3)                    #\LATIN_SMALL_LETTER_SHARP_S
(%i4) unicode("LATIN_SMALL_LETTER_SHARP_S");
(%o4)                                  ß
(%i5) unicode("Latin small letter sharp s");
(%o5)                                  ß

Function: unicode_to_utf8 (code_point)

Returns a list containing the UTF-8 code corresponding to the Unicode code_point.

Examples: Converting Unicode code points to UTF-8 and vice versa.

(%i1) ibase: obase: 16.$
(%i2) map(cint, ["$","£","€"]);
(%o2)                           [24, 0A3, 20AC]
(%i3) map(unicode_to_utf8, %);
(%o3)                 [[24], [0C2, 0A3], [0E2, 82, 0AC]]
(%i4) map(utf8_to_unicode, %);
(%o4)                           [24, 0A3, 20AC]

Category: Predicate functions · Category: Package stringproc

Function: uppercasep (char)

Returns true if char is an uppercase character.

Note: See remarks on alphacharp.

Variable: us_ascii_only

This option variable affects Maxima when the character encoding provided by the application which runs Maxima is UTF-8 but the external format of the Lisp reader is not equal to UTF-8.

On GNU/Linux this is true when Maxima is built with GCL and on Windows in wxMaxima with GCL- and SBCL-builds. With SBCL it is recommended to change the external format to UTF-8. Setting us_ascii_only is unnecessary then. See adjust_external_format for details.

us_ascii_only is false by default. Maxima itself then (i.e. in the above described situation) parses the UTF-8 encoding.

When us_ascii_only is set to true it is assumed that all strings used as arguments to string processing functions do not contain Non-US-ASCII characters. Given that promise, Maxima avoids parsing UTF-8 and strings can be processed more efficiently.

Category: Global variables · Category: Package stringproc

Function: utf8_to_unicode (list)

Returns a Unicode code point corresponding to the list which must contain the UTF-8 encoding of a single character.

Examples: See unicode_to_utf8.

86.4 String Processing

Position indices in strings are 1-indexed like in Maxima lists. See example in charat.

Function: charat (string, n)

Returns the n-th character of string. The first character in string is returned with n = 1.

(%i1) charat("Lisp",1);
(%o1)                           L
(%i2) charlist("Lisp")[1];
(%o2)                           L

Function: charlist (string)

Returns the list of all characters in string.

(%i1) charlist("Lisp");
(%o1)                     [L, i, s, p]

Function: eval_string (str)

Parse the string str as a Maxima expression and evaluate it. The string str may or may not have a terminator (dollar sign $ or semicolon ;). Only the first expression is parsed and evaluated, if there is more than one.

Complain if str is not a string.

Examples:

(%i1) eval_string ("foo: 42; bar: foo^2 + baz");
(%o1)                       42
(%i2) eval_string ("(foo: 42, bar: foo^2 + baz)");
(%o2)                   baz + 1764

86.5 Octets and Utilities for Cryptography

Function: base64 (arg)

Returns the base64-representation of arg as a string. The argument arg may be a string, a non-negative integer or a list of octets.

Examples:

(%i1) base64: base64("foo bar baz");
(%o1)                          Zm9vIGJhciBiYXo=
(%i2) string: base64_decode(base64);
(%o2)                            foo bar baz
(%i3) obase: 16.$
(%i4) integer: base64_decode(base64, 'number);
(%o4)                       666f6f206261722062617a
(%i5) octets: base64_decode(base64, 'list);
(%o5)            [66, 6F, 6F, 20, 62, 61, 72, 20, 62, 61, 7A]
(%i6) ibase: 16.$
(%i7) base64(octets);
(%o7)                          Zm9vIGJhciBiYXo=

Note that if arg contains umlauts (resp. octets larger than 127) the resulting base64-string is platform dependend. However the decoded string will be equal to the original.

Function: base64_decode
base64_decode (base64-string)
base64_decode (base64-string, return-type)

By default base64_decode decodes the base64-string back to the original string.

The optional argument return-type allows base64_decode to alternatively return the corresponding number or list of octets. return-type may be string, number or list.

Example: See base64.

Function: crc24sum
crc24sum (octets)
crc24sum (octets, return-type)

By default crc24sum returns the CRC24 checksum of an octet-list as a string.

The optional argument return-type allows crc24sum to alternatively return the corresponding number or list of octets. return-type may be string, number or list.

Example:

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

iQEcBAEBAgAGBQJVdCTzAAoJEG/1Mgf2DWAqCSYH/AhVFwhu1D89C3/QFcgVvZTM
wnOYzBUURJAL/cT+IngkLEpp3hEbREcugWp+Tm6aw3R4CdJ7G3FLxExBH/5KnDHi
rBQu+I7+3ySK2hpryQ6Wx5J9uZSa4YmfsNteR8up0zGkaulJeWkS4pjiRM+auWVe
vajlKZCIK52P080DG7Q2dpshh4fgTeNwqCuCiBhQ73t8g1IaLdhDN6EzJVjGIzam
/spqT/sTo6sw8yDOJjvU+Qvn6/mSMjC/YxjhRMaQt9EMrR1AZ4ukBF5uG1S7mXOH
WdiwkSPZ3gnIBhM9SuC076gLWZUNs6NqTeE3UzMjDAFhH3jYk1T7mysCvdtIkms=
=WmeC
-----END PGP SIGNATURE-----

(%i1) ibase : obase : 16.$
(%i2) sig64 : sconcat(
 "iQEcBAEBAgAGBQJVdCTzAAoJEG/1Mgf2DWAqCSYH/AhVFwhu1D89C3/QFcgVvZTM",
 "wnOYzBUURJAL/cT+IngkLEpp3hEbREcugWp+Tm6aw3R4CdJ7G3FLxExBH/5KnDHi",
 "rBQu+I7+3ySK2hpryQ6Wx5J9uZSa4YmfsNteR8up0zGkaulJeWkS4pjiRM+auWVe",
 "vajlKZCIK52P080DG7Q2dpshh4fgTeNwqCuCiBhQ73t8g1IaLdhDN6EzJVjGIzam",
 "/spqT/sTo6sw8yDOJjvU+Qvn6/mSMjC/YxjhRMaQt9EMrR1AZ4ukBF5uG1S7mXOH",
 "WdiwkSPZ3gnIBhM9SuC076gLWZUNs6NqTeE3UzMjDAFhH3jYk1T7mysCvdtIkms=" )$
(%i3) octets: base64_decode(sig64, 'list)$
(%i4) crc24: crc24sum(octets, 'list);
(%o4)                          [5A, 67, 82]
(%i5) base64(crc24);
(%o5)                              WmeC

Function: md5sum
md5sum (arg)
md5sum (arg, return-type)

Returns the MD5 checksum of a string, a non-negative integer or a list of octets. The default return value is a string containing 32 hex characters.

The optional argument return-type allows md5sum to alternatively return the corresponding number or list of octets. return-type may be string, number or list.

Examples:

(%i1) ibase: obase: 16.$
(%i2) msg: "foo bar baz"$
(%i3) string: md5sum(msg);
(%o3)                  ab07acbb1e496801937adfa772424bf7
(%i4) integer: md5sum(msg, 'number);
(%o4)                 0ab07acbb1e496801937adfa772424bf7
(%i5) octets: md5sum(msg, 'list);
(%o5)        [0AB,7,0AC,0BB,1E,49,68,1,93,7A,0DF,0A7,72,42,4B,0F7]
(%i6) sdowncase( printf(false, "~{~2,'0x~^:~}", octets) );
(%o6)           ab:07:ac:bb:1e:49:68:01:93:7a:df:a7:72:42:4b:f7

Note that in case arg contains German umlauts or other non-ASCII characters (resp. octets larger than 127) the MD5 checksum is platform dependend.

Function: mgf1_sha1
mgf1_sha1 (seed, len)
mgf1_sha1 (seed, len, return-type)

Returns a pseudo random number of variable length. By default the returned value is a number with a length of len octets.

The optional argument return-type allows mgf1_sha1 to alternatively return the corresponding list of len octets. return-type may be number or list.

The computation of the returned value is described in RFC 3447, appendix B.2.1 MGF1. SHA1 ist used as hash function, i.e. the randomness of the computed number relies on the randomness of SHA1 hashes.

Example:

(%i1) ibase: obase: 16.$
(%i2) number: mgf1_sha1(4711., 8);
(%o2)                        0e0252e5a2a42fea1
(%i3) octets: mgf1_sha1(4711., 8, 'list);
(%o3)                  [0E0,25,2E,5A,2A,42,0FE,0A1]

Function: number_to_octets (number)

Returns an octet-representation of number as a list of octets. The number must be a non-negative integer.

Example:

(%i1) ibase : obase : 16.$
(%i2) octets: [0ca,0fe,0ba,0be]$
(%i3) number: octets_to_number(octets);
(%o3)                            0cafebabe
(%i4) number_to_octets(number);
(%o4)                      [0CA, 0FE, 0BA, 0BE]

Function: octets_to_number (octets)

Returns a number by concatenating the octets in the list of octets.

Example: See number_to_octets.

Function: octets_to_oid (octets)

Computes an object identifier (OID) from the list of octets.

Example: RSA encryption OID

(%i1) ibase : obase : 16.$
(%i2) oid: octets_to_oid([2A,86,48,86,0F7,0D,1,1,1]);
(%o2)                      1.2.840.113549.1.1.1
(%i3) oid_to_octets(oid);
(%o3)               [2A, 86, 48, 86, 0F7, 0D, 1, 1, 1]

Function: octets_to_string
octets_to_string (octets)
octets_to_string (octets, encoding)

Decodes the list of octets into a string according to current system defaults. When decoding octets corresponding to Non-US-ASCII characters the result depends on the platform, application and underlying Lisp.

Example: Using system defaults (Maxima compiled with GCL, which uses no format definition and simply passes through the UTF-8-octets encoded by the GNU/Linux terminal).

(%i1) octets: string_to_octets("abc");
(%o1)                            [61, 62, 63]
(%i2) octets_to_string(octets);
(%o2)                                 abc
(%i3) ibase: obase: 16.$
(%i4) unicode(20AC);
(%o4)                                  €
(%i5) octets: string_to_octets(%);
(%o5)                           [0E2, 82, 0AC]
(%i6) octets_to_string(octets);
(%o6)                                  €
(%i7) utf8_to_unicode(octets);
(%o7)                                20AC

In case the external format of the Lisp reader is equal to UTF-8 the optional argument encoding allows to set the encoding for the octet to string conversion. If necessary see adjust_external_format for changing the external format.

Some names of supported encodings (see corresponding Lisp manual for more):
CCL, CLISP, SBCL: utf-8, ucs-2be, ucs-4be, iso-8859-1, cp1252, cp850
CMUCL: utf-8, utf-16-be, utf-32-be, iso8859-1, cp1252
ECL: utf-8, ucs-2be, ucs-4be, iso-8859-1, windows-cp1252, dos-cp850

Example (continued): Using the optional encoding argument (Maxima compiled with SBCL, GNU/Linux terminal).

(%i8) string_to_octets("€", "ucs-2be");
(%o8)                              [20, 0AC]

Function: oid_to_octets (oid-string)

Convertes an object identifier (OID) to a list of octets.

Example: See octets_to_oid.

Function: sha1sum
sha1sum (arg)
sha1sum (arg, return-type)

Returns the SHA1 fingerprint of a string, a non-negative integer or a list of octets. The default return value is a string containing 40 hex characters.

The optional argument return-type allows sha1sum to alternatively return the corresponding number or list of octets. return-type may be string, number or list.

Example:

(%i1) ibase: obase: 16.$
(%i2) msg: "foo bar baz"$
(%i3) string: sha1sum(msg);
(%o3)              c7567e8b39e2428e38bf9c9226ac68de4c67dc39
(%i4) integer: sha1sum(msg, 'number);
(%o4)             0c7567e8b39e2428e38bf9c9226ac68de4c67dc39
(%i5) octets: sha1sum(msg, 'list);
(%o5)  [0C7,56,7E,8B,39,0E2,42,8E,38,0BF,9C,92,26,0AC,68,0DE,4C,67,0DC,39]
(%i6) sdowncase( printf(false, "~{~2,'0x~^:~}", octets) );
(%o6)     c7:56:7e:8b:39:e2:42:8e:38:bf:9c:92:26:ac:68:de:4c:67:dc:39

Note that in case arg contains German umlauts or other non-ASCII characters (resp. octets larger than 127) the SHA1 fingerprint is platform dependend.

Function: sha256sum
sha256sum (arg)
sha256sum (arg, return-type)

Returns the SHA256 fingerprint of a string, a non-negative integer or a list of octets. The default return value is a string containing 64 hex characters.

The optional argument return-type allows sha256sum to alternatively return the corresponding number or list of octets (see sha1sum).

Example:

(%i1) string: sha256sum("foo bar baz");
(%o1)  dbd318c1c462aee872f41109a4dfd3048871a03dedd0fe0e757ced57dad6f2d7

Note that in case arg contains German umlauts or other non-ASCII characters (resp. octets larger than 127) the SHA256 fingerprint is platform dependend.

Function: string_to_octets
string_to_octets (string)
string_to_octets (string, encoding)

Encodes a string into a list of octets according to current system defaults. When encoding strings containing Non-US-ASCII characters the result depends on the platform, application and underlying Lisp.

In case the external format of the Lisp reader is equal to UTF-8 the optional argument encoding allows to set the encoding for the string to octet conversion. If necessary see adjust_external_format for changing the external format.

See octets_to_string for examples and some more information.

87 to_poly_solve

87.1 Functions and Variables for to_poly_solve

The packages to_poly and to_poly_solve are experimental; the specifications of the functions in these packages might change or the some of the functions in these packages might be merged into other Maxima functions.

Barton Willis (Professor of Mathematics, University of Nebraska at Kearney) wrote the to_poly and to_poly_solve packages and the English language user documentation for these packages.

Operator: %and

The operator %and is a simplifying nonshort-circuited logical conjunction. Maxima simplifies an %and expression to either true, false, or a logically equivalent, but simplified, expression. The operator %and is associative, commutative, and idempotent. Thus when %and returns a noun form, the arguments of %and form a non-redundant sorted list; for example

(%i1) a %and (a %and b);
(%o1)                       a %and b

If one argument to a conjunction is the explicit the negation of another argument, %and returns false:

(%i2) a %and (not a);
(%o2)                         false

If any member of the conjunction is false, the conjunction simplifies to false even if other members are manifestly non-boolean; for example

(%i3) 42 %and false;
(%o3)                         false

Any argument of an %and expression that is an inequation (that is, an inequality or equation), is simplified using the Fourier elimination package. The Fourier elimination simplifier has a pre-processor that converts some, but not all, nonlinear inequations into linear inequations; for example the Fourier elimination code simplifies abs(x) + 1 > 0 to true, so

(%i4) (x < 1) %and (abs(x) + 1 > 0);
(%o4)                         x < 1

Notes

The option variable prederror does not alter the simplification %and expressions.
To avoid operator precedence errors, compound expressions involving the operators %and, %or, and not should be fully parenthesized.
The Maxima operators and and or are both short-circuited. Thus and isn’t associative or commutative.

Limitations The conjunction %and simplifies inequations locally, not globally. This means that conjunctions such as

(%i5) (x < 1) %and (x > 1);
(%o5)                 (x > 1) %and (x < 1)

do not simplify to false. Also, the Fourier elimination code ignores the fact database;

(%i6) assume(x > 5);
(%o6)                        [x > 5]
(%i7) (x > 1) %and (x > 2);
(%o7)                 (x > 1) %and (x > 2)

Finally, nonlinear inequations that aren’t easily converted into an equivalent linear inequation aren’t simplified.

There is no support for distributing %and over %or; neither is there support for distributing a logical negation over %and.

To use load(to_poly_solve)

Related functions %or, %if, and, or, not

Status The operator %and is experimental; the specifications of this function might change and its functionality might be merged into other Maxima functions.

Operator: %if (bool, a, b)

The operator %if is a simplifying conditional. The conditional bool should be boolean-valued. When the conditional is true, return the second argument; when the conditional is false, return the third; in all other cases, return a noun form.

Maxima inequations (either an inequality or an equality) are not boolean-valued; for example, Maxima does not simplify 5 < 6 to true, and it does not simplify 5 = 6 to false; however, in the context of a conditional to an %if statement, Maxima automatically attempts to determine the truth value of an inequation. Examples:

(%i1) f : %if(x # 1, 2, 8);
(%o1)                 %if(x - 1 # 0, 2, 8)
(%i2) [subst(x = -1,f), subst(x=1,f)];
(%o2)                        [2, 8]

If the conditional involves an inequation, Maxima simplifies it using the Fourier elimination package.

Notes

If the conditional is manifestly non-boolean, Maxima returns a noun form:

(%i3) %if(42,1,2);
(%o3)                     %if(42, 1, 2)

The Maxima operator if is nary, the operator %if isn’t nary.

Limitations The Fourier elimination code only simplifies nonlinear inequations that are readily convertible to an equivalent linear inequation.

To use: load(to_poly_solve)

Status: The operator %if is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Operator: %or

The operator %or is a simplifying nonshort-circuited logical disjunction. Maxima simplifies an %or expression to either true, false, or a logically equivalent, but simplified, expression. The operator %or is associative, commutative, and idempotent. Thus when %or returns a noun form, the arguments of %or form a non-redundant sorted list; for example

(%i1) a %or (a %or b);
(%o1)                        a %or b

If one member of the disjunction is the explicit the negation of another member, %or returns true:

(%i2) a %or (not a);
(%o2)                         true

If any member of the disjunction is true, the disjunction simplifies to true even if other members of the disjunction are manifestly non-boolean; for example

(%i3) 42 %or true;
(%o3)                         true

Any argument of an %or expression that is an inequation (that is, an inequality or equation), is simplified using the Fourier elimination package. The Fourier elimination code simplifies abs(x) + 1 > 0 to true, so we have

(%i4) (x < 1) %or (abs(x) + 1 > 0);
(%o4)                         true

Notes

The option variable prederror does not alter the simplification of %or expressions.
You should parenthesize compound expressions involving the operators %and, %or, and not; the binding powers of these operators might not match your expectations.
The Maxima operators and and or are both short-circuited. Thus or isn’t associative or commutative.

Limitations The conjunction %or simplifies inequations locally, not globally. This means that conjunctions such as

(%i1) (x < 1) %or (x >= 1);
(%o1) (x > 1) %or (x >= 1)

do not simplify to true. Further, the Fourier elimination code ignores the fact database;

(%i2) assume(x > 5);
(%o2)                        [x > 5]
(%i3) (x > 1) %and (x > 2);
(%o3)                 (x > 1) %and (x > 2)

Finally, nonlinear inequations that aren’t easily converted into an equivalent linear inequation aren’t simplified.

The algorithm that looks for terms that cannot both be false is weak; also there is no support for distributing %or over %and; neither is there support for distributing a logical negation over %or.

To use load(to_poly_solve)

Related functions %or, %if, and, or, not

Status The operator %or is experimental; the specifications of this function might change and its functionality might be merged into other Maxima functions.

Function: complex_number_p (x)

The predicate complex_number_p returns true if its argument is either a + %i * b, a, %i b, or %i, where a and b are either rational or floating point numbers (including big floating point); for all other inputs, complex_number_p returns false; for example

(%i1) map('complex_number_p,[2/3, 2 + 1.5 * %i, %i]);
(%o1)                  [true, true, true]
(%i2) complex_number_p((2+%i)/(5-%i));
(%o2)                         false
(%i3) complex_number_p(cos(5 - 2 * %i));
(%o3)                         false

Related functions isreal_p

To use load(to_poly_solve)

Status The operator complex_number_p is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: compose_functions (l)

The function call compose_functions(l) returns a lambda form that is the composition of the functions in the list l. The functions are applied from right to left; for example

(%i1) compose_functions([cos, exp]);
                                        %g151
(%o1)             lambda([%g151], cos(%e     ))
(%i2) %(x);
                                  x
(%o2)                       cos(%e )

When the function list is empty, return the identity function:

(%i3) compose_functions([]);
(%o3)                lambda([%g152], %g152)
(%i4)  %(x);
(%o4)                           x

Notes

When Maxima determines that a list member isn’t a symbol or a lambda form, funmake (not compose_functions) signals an error:

(%i5) compose_functions([a < b]);

funmake: first argument must be a symbol, subscripted symbol,
string, or lambda expression; found: a < b
#0: compose_functions(l=[a < b])(to_poly_solve.mac line 40)
 -- an error. To debug this try: debugmode(true);

To avoid name conflicts, the independent variable is determined by the function new_variable.

(%i6) compose_functions([%g0]);
(%o6)              lambda([%g154], %g0(%g154))
(%i7) compose_functions([%g0]);
(%o7)              lambda([%g155], %g0(%g155))

Although the independent variables are different, Maxima is able to to deduce that these lambda forms are semantically equal:

(%i8) is(equal(%o6,%o7));
(%o8)                         true

To use load(to_poly_solve)

Status The function compose_functions is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: dfloat (x)

The function dfloat is a similar to float, but the function dfloat applies rectform when float fails to evaluate to an IEEE double floating point number; thus

(%i1) float(4.5^(1 + %i));
                               %i + 1
(%o1)                       4.5
(%i2) dfloat(4.5^(1 + %i));
(%o2)        4.48998802962884 %i + .3000124893895671

Notes

The rectangular form of an expression might be poorly suited for numerical evaluation–for example, the rectangular form might needlessly involve the difference of floating point numbers (subtractive cancellation).
The identifier float is both an option variable (default value false) and a function name.

Related functions float, bfloat

To use load(to_poly_solve)

Status The function dfloat is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: elim (l, x)

The function elim eliminates the variables in the set or list x from the equations in the set or list l. Each member of x must be a symbol; the members of l can either be equations, or expressions that are assumed to equal zero.

The function elim returns a list of two lists; the first is the list of expressions with the variables eliminated; the second is the list of pivots; thus, the second list is a list of expressions that elim used to eliminate the variables.

Here is a example of eliminating between linear equations:

(%i1) elim(set(x + y + z = 1, x - y  - z = 8, x - z = 1), 
           set(x,y));
(%o1)            [[2 z - 7], [y + 7, z - x + 1]]

Eliminating x and y yields the single equation 2 z - 7 = 0; the equations y + 7 = 0 and z - z + 1 = 1 were used as pivots. Eliminating all three variables from these equations, triangularizes the linear system:

(%i2) elim(set(x + y + z = 1, x - y  - z = 8, x - z = 1),
           set(x,y,z));
(%o2)           [[], [2 z - 7, y + 7, z - x + 1]]

Of course, the equations needn’t be linear:

(%i3) elim(set(x^2 - 2 * y^3 = 1,  x - y = 5), [x,y]);
                     3    2
(%o3)       [[], [2 y  - y  - 10 y - 24, y - x + 5]]

The user doesn’t control the order the variables are eliminated. Instead, the algorithm uses a heuristic to attempt to choose the best pivot and the best elimination order.

Notes

Unlike the related function eliminate, the function elim does not invoke solve when the number of equations equals the number of variables.
The function elim works by applying resultants; the option variable resultant determines which algorithm Maxima uses. Using sqfr, Maxima factors each resultant and suppresses multiple zeros.
The elim will triangularize a nonlinear set of polynomial equations; the solution set of the triangularized set can be larger than that solution set of the untriangularized set. Thus, the triangularized equations can have spurious solutions.

Related functions elim_allbut, eliminate_using, eliminate

Option variables resultant

To use load(to_poly)

Status The function elim is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: elim_allbut (l, x)

This function is similar to elim, except that it eliminates all the variables in the list of equations l except for those variables that in in the list x

(%i1) elim_allbut([x+y = 1, x - 5*y = 1],[]);
(%o1)                 [[], [y, y + x - 1]]
(%i2) elim_allbut([x+y = 1, x - 5*y = 1],[x]);
(%o2)                [[x - 1], [y + x - 1]]

To use load(to_poly)

Option variables resultant

Related functions elim, eliminate_using, eliminate

Status The function elim_allbut is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: eliminate_using (l, e, x)

Using e as the pivot, eliminate the symbol x from the list or set of equations in l. The function eliminate_using returns a set.

(%i1) eq : [x^2 - y^2 - z^3 , x*y - z^2 - 5, x - y + z];
               3    2    2     2
(%o1)      [- z  - y  + x , - z  + x y - 5, z - y + x]
(%i2) eliminate_using(eq,first(eq),z);
        3              2      2      3    2
(%o2) {y  + (1 - 3 x) y  + 3 x  y - x  - x , 
                        4    3  3       2  2             4
                       y  - x  y  + 13 x  y  - 75 x y + x  + 125}
(%i3) eliminate_using(eq,second(eq),z);
        2            2       4    3  3       2  2             4
(%o3) {y  - 3 x y + x  + 5, y  - x  y  + 13 x  y  - 75 x y + x
                                                           + 125}
(%i4) eliminate_using(eq, third(eq),z);
        2            2       3              2      2      3    2
(%o4) {y  - 3 x y + x  + 5, y  + (1 - 3 x) y  + 3 x  y - x  - x }

Option variables resultant

Related functions elim, eliminate, elim_allbut

To use load(to_poly)

Status The function eliminate_using is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: fourier_elim ([eq1, eq2, …], [var1, var, …])

Fourier elimination is the analog of Gauss elimination for linear inequations (equations or inequalities). The function call fourier_elim([eq1, eq2, ...], [var1, var2, ...]) does Fourier elimination on a list of linear inequations [eq1, eq2, ...] with respect to the variables [var1, var2, ...]; for example

(%i1) fourier_elim([y-x < 5, x - y < 7, 10 < y],[x,y]);
(%o1)            [y - 5 < x, x < y + 7, 10 < y]
(%i2) fourier_elim([y-x < 5, x - y < 7, 10 < y],[y,x]);
(%o2)        [max(10, x - 7) < y, y < x + 5, 5 < x]

Eliminating first with respect to x and second with respect to y yields lower and upper bounds for x that depend on y, and lower and upper bounds for y that are numbers. Eliminating in the other order gives x dependent lower and upper bounds for y, and numerical lower and upper bounds for x.

When necessary, fourier_elim returns a disjunction of lists of inequations:

(%i3) fourier_elim([x # 6],[x]);
(%o3)                  [x < 6] or [6 < x]

When the solution set is empty, fourier_elim returns emptyset, and when the solution set is all reals, fourier_elim returns universalset; for example

(%i4) fourier_elim([x < 1, x > 1],[x]);
(%o4)                       emptyset
(%i5) fourier_elim([minf < x, x < inf],[x]);
(%o5)                     universalset

For nonlinear inequations, fourier_elim returns a (somewhat) simplified list of inequations:

(%i6) fourier_elim([x^3 - 1 > 0],[x]);

               2                             2
(%o6) [1 < x, x  + x + 1 > 0] or [x < 1, - (x  + x + 1) > 0]

(%i7) fourier_elim([cos(x) < 1/2],[x]);
(%o7)                  [1 - 2 cos(x) > 0]

Instead of a list of inequations, the first argument to fourier_elim may be a logical disjunction or conjunction:

(%i8) fourier_elim((x + y < 5) and (x - y >8),[x,y]);
                                              3
(%o8)            [y + 8 < x, x < 5 - y, y < - -]
                                              2
(%i9) fourier_elim(((x + y < 5) and x < 1) or  (x - y >8),[x,y]);
(%o9)          [y + 8 < x] or [x < min(1, 5 - y)]

The function fourier_elim supports the inequation operators <, <=, >, >=, #, and =.

The Fourier elimination code has a preprocessor that converts some nonlinear inequations that involve the absolute value, minimum, and maximum functions into linear in equations. Additionally, the preprocessor handles some expressions that are the product or quotient of linear terms:

(%i10) fourier_elim([max(x,y) > 6, x # 8, abs(y-1) > 12],[x,y]);
(%o10) [6 < x, x < 8, y < - 11] or [8 < x, y < - 11]
 or [x < 8, 13 < y] or [x = y, 13 < y] or [8 < x, x < y, 13 < y]
 or [y < x, 13 < y]
(%i11) fourier_elim([(x+6)/(x-9) <= 6],[x]);
(%o11)           [x = 12] or [12 < x] or [x < 9]
(%i12) fourier_elim([x^2 - 1 # 0],[x]);
(%o12)      [- 1 < x, x < 1] or [1 < x] or [x < - 1]

To use load(fourier_elim)

Function: isreal_p (e)

The predicate isreal_p returns true when Maxima is able to determine that e is real-valued on the entire real line; it returns false when Maxima is able to determine that e isn’t real-valued on some nonempty subset of the real line; and it returns a noun form for all other cases.

(%i1) map('isreal_p, [-1, 0, %i, %pi]);
(%o1)               [true, true, false, true]

Maxima variables are assumed to be real; thus

(%i2) isreal_p(x);
(%o2)                         true

The function isreal_p examines the fact database:

(%i3) declare(z,complex)$

(%i4) isreal_p(z);
(%o4)                      isreal_p(z)

Limitations Too often, isreal_p returns a noun form when it should be able to return false; a simple example: the logarithm function isn’t real-valued on the entire real line, so isreal_p(log(x)) should return false; however

(%i5) isreal_p(log(x));
(%o5)                   isreal_p(log(x))

To use load(to_poly_solve)

Related functions complex_number_p

Status The function isreal_p is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: new_variable (type)

Return a unique symbol of the form %[z,n,r,c,g]k, where k is an integer. The allowed values for type are integer, natural_number, real, natural_number, and general. (By natural number, we mean the nonnegative integers; thus zero is a natural number. Some, but not all,definitions of natural number exclude zero.)

When type isn’t one of the allowed values, type defaults to general. For integers, natural numbers, and complex numbers, Maxima automatically appends this information to the fact database.

(%i1) map('new_variable,
          ['integer, 'natural_number, 'real, 'complex, 'general]);
(%o1)          [%z144, %n145, %r146, %c147, %g148]
(%i2) nicedummies(%);
(%o2)               [%z0, %n0, %r0, %c0, %g0]
(%i3) featurep(%z0, 'integer);
(%o3)                         true
(%i4) featurep(%n0, 'integer);
(%o4)                         true
(%i5) is(%n0 >= 0);
(%o5)                         true
(%i6) featurep(%c0, 'complex);
(%o6)                         true

Note Generally, the argument to new_variable should be quoted. The quote will protect against errors similar to

(%i7) integer : 12$

(%i8) new_variable(integer);
(%o8)                         %g149
(%i9) new_variable('integer);
(%o9)                         %z150

Related functions nicedummies

To use load(to_poly_solve)

Status The function new_variable is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: nicedummies

Starting with zero, the function nicedummies re-indexes the variables in an expression that were introduced by new_variable;

(%i1) new_variable('integer) + 52 * new_variable('integer);
(%o1)                   52 %z136 + %z135
(%i2) new_variable('integer) - new_variable('integer);
(%o2)                     %z137 - %z138
(%i3) nicedummies(%);
(%o3)                       %z0 - %z1

Related functions new_variable

To use load(to_poly_solve)

Status The function nicedummies is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: parg (x)

The function parg is a simplifying version of the complex argument function carg; thus

(%i1) map('parg,[1,1+%i,%i, -1 + %i, -1]);
                        %pi  %pi  3 %pi
(%o1)               [0, ---, ---, -----, %pi]
                         4    2     4

Generally, for a non-constant input, parg returns a noun form; thus

(%i2) parg(x + %i * sqrt(x));
(%o2)                 parg(x + %i sqrt(x))

When sign can determine that the input is a positive or negative real number, parg will return a non-noun form for a non-constant input. Here are two examples:

(%i3) parg(abs(x));
(%o3) 0
(%i4) parg(-x^2-1);
(%o4)                          %pi

Note The sign function mostly ignores the variables that are declared to be complex (declare(x,complex)); for variables that are declared to be complex, the parg can return incorrect values; for example

(%i1) declare(x,complex)$

(%i2) parg(x^2 + 1);
(%o2) 0

Related function carg, isreal_p

To use load(to_poly_solve)

Status The function parg is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: real_imagpart_to_conjugate (e)

The function real_imagpart_to_conjugate replaces all occurrences of realpart and imagpart to algebraically equivalent expressions involving the conjugate.

(%i1) declare(x, complex)$

(%i2) real_imagpart_to_conjugate(realpart(x) +  imagpart(x) = 3);
          conjugate(x) + x   %i (x - conjugate(x))
(%o2)     ---------------- - --------------------- = 3
                 2                     2

To use load(to_poly_solve)

Status The function real_imagpart_to_conjugate is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: rectform_log_if_constant (e)

The function rectform_log_if_constant converts all terms of the form log(c) to rectform(log(c)), where c is either a declared constant expression or explicitly declared constant

(%i1) rectform_log_if_constant(log(1-%i) - log(x - %i));
                                 log(2)   %i %pi
(%o1)            - log(x - %i) + ------ - ------
                                   2        4
(%i2) declare(a,constant, b,constant)$

(%i3) rectform_log_if_constant(log(a + %i*b));
                       2    2
                  log(b  + a )
(%o3)             ------------ + %i atan2(b, a)
                       2

To use load(to_poly_solve)

Status The function rectform_log_if_constant is experimental; the specifications of this function might change might change and its functionality might be merged into other Maxima functions.

Function: simp_inequality (e)

The function simp_inequality applies some simplifications to conjunctions and disjunctions of inequations.

Limitations The function simp_inequality is limited in at least two ways; first, the simplifications are local; thus

(%i1) simp_inequality((x > minf) %and (x < 0));
(%o1) (x>1) %and (x<1)

And second, simp_inequality doesn’t consult the fact database:

(%i2) assume(x > 0)$

(%i3) simp_inequality(x > 0);
(%o3)                         x > 0

To use load(fourier_elim)

Status The function simp_inequality is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: standardize_inverse_trig (e)

This function applies the identities cot(x) = atan(1/x), acsc(x) = asin(1/x), and similarly for asec, acoth, acsch and asech to an expression. See Abramowitz and Stegun, Eqs. 4.4.6 through 4.4.8 and 4.6.4 through 4.6.6.

To use load(to_poly_solve)

Status The function standardize_inverse_trig is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: subst_parallel (l, e)

When l is a single equation or a list of equations, substitute the right hand side of each equation for the left hand side. The substitutions are made in parallel; for example

(%i1) load(to_poly_solve)$

(%i2) subst_parallel([x=y,y=x], [x,y]);
(%o2)                        [y, x]

Compare this to substitutions made serially:

(%i3) subst([x=y,y=x],[x,y]);
(%o3)                        [x, x]

The function subst_parallel is similar to sublis except that subst_parallel allows for substitution of nonatoms; for example

(%i4) subst_parallel([x^2 = a, y = b], x^2 * y);
(%o4)                          a b
(%i5) sublis([x^2 = a, y = b], x^2 * y);

                                                             2
sublis: left-hand side of equation must be a symbol; found: x
 -- an error. To debug this try: debugmode(true);

The substitutions made by subst_parallel are literal, not semantic; thus subst_parallel does not recognize that x * y is a subexpression of x^2 * y

(%i6) subst_parallel([x * y = a], x^2 * y);
                               2
(%o6)                         x  y

The function subst_parallel completes all substitutions before simplifications. This allows for substitutions into conditional expressions where errors might occur if the simplifications were made earlier:

(%i7) subst_parallel([x = 0], %if(x < 1, 5, log(x)));
(%o7)                           5
(%i8) subst([x = 0], %if(x < 1, 5, log(x)));

log: encountered log(0).
 -- an error. To debug this try: debugmode(true);

Related functions subst, sublis, ratsubst

To use load(to_poly_solve_extra.lisp)

Status The function subst_parallel is experimental; the specifications of this function might change might change and its functionality might be merged into other Maxima functions.

Function: to_poly (e, l)

The function to_poly attempts to convert the equation e into a polynomial system along with inequality constraints; the solutions to the polynomial system that satisfy the constraints are solutions to the equation e. Informally, to_poly attempts to polynomialize the equation e; an example might clarify:

(%i1) load(to_poly_solve)$

(%i2) to_poly(sqrt(x) = 3, [x]);
                            2
(%o2) [[%g130 - 3, x = %g130 ], 
                      %pi                               %pi
                   [- --- < parg(%g130), parg(%g130) <= ---], []]
                       2                                 2

The conditions -%pi/2<parg(%g130),parg(%g130)<=%pi/2 tell us that %g130 is in the range of the square root function. When this is true, the solution set to sqrt(x) = 3 is the same as the solution set to %g130-3,x=%g130^2.

To polynomialize trigonometric expressions, it is necessary to introduce a non algebraic substitution; these non algebraic substitutions are returned in the third list returned by to_poly; for example

(%i3) to_poly(cos(x),[x]);
                2                                 %i x
(%o3)    [[%g131  + 1], [2 %g131 # 0], [%g131 = %e    ]]

Constant terms aren’t polynomializied unless the number one is a member of the variable list; for example

(%i4) to_poly(x = sqrt(5),[x]);
(%o4)                [[x - sqrt(5)], [], []]
(%i5) to_poly(x = sqrt(5),[1,x]);
                            2
(%o5) [[x - %g132, 5 = %g132 ], 
                      %pi                               %pi
                   [- --- < parg(%g132), parg(%g132) <= ---], []]
                       2                                 2

To generate a polynomial with sqrt(5) + sqrt(7) as one of its roots, use the commands

(%i6) first(elim_allbut(first(to_poly(x = sqrt(5) + sqrt(7),
                                      [1,x])), [x]));
                          4       2
(%o6)                   [x  - 24 x  + 4]

Related functions to_poly_solve

To use load(to_poly)

Status: The function to_poly is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Function: to_poly_solve (e, l, [options])

The function to_poly_solve tries to solve the equations e for the variables l. The equation(s) e can either be a single expression or a set or list of expressions; similarly, l can either be a single symbol or a list of set of symbols. When a member of e isn’t explicitly an equation, for example x^2 -1, the solver asummes that the expression vanishes.

The basic strategy of to_poly_solve is to convert the input into a polynomial form and to call algsys on the polynomial system. Internally to_poly_solve defaults algexact to true. To change the default for algexact, append ’algexact=false to the to_poly_solve argument list.

When to_poly_solve is able to determine the solution set, each member of the solution set is a list in a %union object:

(%i1) load(to_poly_solve)$

(%i2) to_poly_solve(x*(x-1) = 0, x);
(%o2)               %union([x = 0], [x = 1])

When to_poly_solve is unable to determine the solution set, a %solve nounform is returned (in this case, a warning is printed)

(%i3) to_poly_solve(x^k + 2* x + 1 = 0, x);

Nonalgebraic argument given to 'to_poly'
unable to solve
                          k
(%o3)            %solve([x  + 2 x + 1 = 0], [x])

Subsitution into a %solve nounform can sometimes result in the solution

(%i4) subst(k = 2, %);
(%o4)                   %union([x = - 1])

Especially for trigonometric equations, the solver sometimes needs to introduce an arbitrary integer. These arbitrary integers have the form %zXXX, where XXX is an integer; for example

(%i5) to_poly_solve(sin(x) = 0, x);
(%o5)   %union([x = 2 %pi %z33 + %pi], [x = 2 %pi %z35])

To re-index these variables to zero, use nicedummies:

(%i6) nicedummies(%);
(%o6)    %union([x = 2 %pi %z0 + %pi], [x = 2 %pi %z1])

Occasionally, the solver introduces an arbitrary complex number of the form %cXXX or an arbitrary real number of the form %rXXX. The function nicedummies will re-index these identifiers to zero.

The solution set sometimes involves simplifing versions of various of logical operators including %and, %or, or %if for conjunction, disjuntion, and implication, respectively; for example

(%i7) sol : to_poly_solve(abs(x) = a, x);
(%o7) %union(%if(isnonnegative_p(a), [x = - a], %union()), 
                      %if(isnonnegative_p(a), [x = a], %union()))
(%i8) subst(a = 42, sol);
(%o8)             %union([x = - 42], [x = 42])
(%i9) subst(a = -42, sol);
(%o9)                       %union()

The empty set is represented by %union().

The function to_poly_solve is able to solve some, but not all, equations involving rational powers, some nonrational powers, absolute values, trigonometric functions, and minimum and maximum. Also, some it can solve some equations that are solvable in in terms of the Lambert W function; some examples:

(%i1) load(to_poly_solve)$

(%i2) to_poly_solve(set(max(x,y) = 5, x+y = 2), set(x,y));
(%o2)      %union([x = - 3, y = 5], [x = 5, y = - 3])
(%i3) to_poly_solve(abs(1-abs(1-x)) = 10,x);
(%o3)             %union([x = - 10], [x = 12])
(%i4) to_poly_solve(set(sqrt(x) + sqrt(y) = 5, x + y = 10),
                    set(x,y));
                     3/2               3/2
                    5    %i - 10      5    %i + 10
(%o4) %union([x = - ------------, y = ------------], 
                         2                 2
                                3/2                 3/2
                               5    %i + 10        5    %i - 10
                          [x = ------------, y = - ------------])
                                    2                   2
(%i5) to_poly_solve(cos(x) * sin(x) = 1/2,x,
                    'simpfuncs = ['expand, 'nicedummies]);
                                         %pi
(%o5)              %union([x = %pi %z0 + ---])
                                          4
(%i6) to_poly_solve(x^(2*a) + x^a + 1,x);
                                        2 %i %pi %z81
                                        -------------
                                  1/a         a
                  (sqrt(3) %i - 1)    %e
(%o6) %union([x = -----------------------------------], 
                                  1/a
                                 2

                                                  2 %i %pi %z83
                                                  -------------
                                            1/a         a
                          (- sqrt(3) %i - 1)    %e
                     [x = -------------------------------------])
                                           1/a
                                          2

(%i7) to_poly_solve(x * exp(x) = a, x);
(%o7)              %union([x = lambert_w(a)])

For linear inequalities, to_poly_solve automatically does Fourier elimination:

(%i8) to_poly_solve([x + y < 1, x - y >= 8], [x,y]);
                               7
(%o8) %union([x = y + 8, y < - -], 
                               2
                                                              7
                                 [y + 8 < x, x < 1 - y, y < - -])
                                                              2

Each optional argument to to_poly_solve must be an equation; generally, the order of these options does not matter.

simpfuncs = l, where l is a list of functions. Apply the composition of the members of l to each solution.

(%i1) to_poly_solve(x^2=%i,x);
                               1/4             1/4
(%o1)       %union([x = - (- 1)   ], [x = (- 1)   ])
(%i2) to_poly_solve(x^2= %i,x, 'simpfuncs = ['rectform]);
                      %i         1             %i         1
(%o2) %union([x = - ------- - -------], [x = ------- + -------])
                    sqrt(2)   sqrt(2)        sqrt(2)   sqrt(2)

Sometimes additional simplification can revert a simplification; for example

(%i3) to_poly_solve(x^2=1,x);
(%o3)              %union([x = - 1], [x = 1])
(%i4) to_poly_solve(x^2= 1,x, 'simpfuncs = [polarform]);
                                        %i %pi
(%o4)            %union([x = 1], [x = %e      ]

Maxima doesn’t try to check that each member of the function list l is purely a simplification; thus

(%i5) to_poly_solve(x^2 = %i,x, 'simpfuncs = [lambda([s],s^2)]);
(%o5)                   %union([x = %i])

To convert each solution to a double float, use simpfunc = ['dfloat]:

(%i6) to_poly_solve(x^3 +x + 1 = 0,x, 
                    'simpfuncs = ['dfloat]), algexact : true;
(%o6) %union([x = - .6823278038280178], 
[x = .3411639019140089 - 1.161541399997251 %i], 
[x = 1.161541399997251 %i + .3411639019140089])

use_grobner = true With this option, the function poly_reduced_grobner is applied to the equations before attempting their solution. Primarily, this option provides a workaround for weakness in the function algsys. Here is an example of such a workaround:

(%i7) to_poly_solve([x^2+y^2=2^2,(x-1)^2+(y-1)^2=2^2],[x,y],
                    'use_grobner = true);

                    sqrt(7) - 1      sqrt(7) + 1
(%o7) %union([x = - -----------, y = -----------], 
                         2                2

                                 sqrt(7) + 1        sqrt(7) - 1
                            [x = -----------, y = - -----------])
                                      2                  2
(%i8) to_poly_solve([x^2+y^2=2^2,(x-1)^2+(y-1)^2=2^2],[x,y]);
(%o8)                       %union()

maxdepth = k, where k is a positive integer. This function controls the maximum recursion depth for the solver. The default value for maxdepth is five. When the recursions depth is exceeded, the solver signals an error:
```
(%i9) to_poly_solve(cos(x) = x,x, 'maxdepth = 2);

Unable to solve
Unable to solve
(%o9)        %solve([cos(x) = x], [x], maxdepth = 2)
```

parameters = l, where l is a list of symbols. The solver attempts to return a solution that is valid for all members of the list l; for example:

(%i10) to_poly_solve(a * x = x, x);
(%o10)                   %union([x = 0])
(%i11) to_poly_solve(a * x = x, x, 'parameters = [a]);
(%o11) %union(%if(a - 1 = 0, [x = %c111], %union()), 
                               %if(a - 1 # 0, [x = 0], %union()))

In (%o2), the solver introduced a dummy variable; to re-index the these dummy variables, use the function nicedummies:

(%i12) nicedummies(%);
(%o12) %union(%if(a - 1 = 0, [x = %c0], %union()), 
                               %if(a - 1 # 0, [x = 0], %union()))

The to_poly_solve uses data stored in the hashed array one_to_one_reduce to solve equations of the form f(a) = f(b). The assignment one_to_one_reduce['f,'f] : lambda([a,b], a=b) tells to_poly_solve that the solution set of f(a) = f(b) equals the solution set of a=b; for example

(%i13) one_to_one_reduce['f,'f] : lambda([a,b], a=b)$

(%i14) to_poly_solve(f(x^2-1) = f(0),x);
(%o14)             %union([x = - 1], [x = 1])

More generally, the assignment one_to_one_reduce['f,'g] : lambda([a,b], w(a, b) = 0 tells to_poly_solve that the solution set of f(a) = f(b) equals the solution set of w(a,b) = 0; for example

(%i15) one_to_one_reduce['f,'g] : lambda([a,b], a = 1 + b/2)$

(%i16) to_poly_solve(f(x) - g(x),x);
(%o16)                   %union([x = 2])

Additionally, the function to_poly_solve uses data stored in the hashed array function_inverse to solve equations of the form f(a) = b. The assignment function_inverse['f] : lambda([s], g(s)) informs to_poly_solve that the solution set to f(x) = b equals the solution set to x = g(b); two examples:

(%i17) function_inverse['Q] : lambda([s], P(s))$

(%i18) to_poly_solve(Q(x-1) = 2009,x);
(%o18)              %union([x = P(2009) + 1])
(%i19) function_inverse['G] : lambda([s], s+new_variable(integer));
(%o19)       lambda([s], s + new_variable(integer))
(%i20) to_poly_solve(G(x - a) = b,x);
(%o20)             %union([x = b + a + %z125])

Notes

The solve variables needn’t be symbols; when fullratsubst is able to appropriately make substitutions, the solve variables can be nonsymbols:

(%i1) to_poly_solve([x^2 + y^2 + x * y = 5, x * y = 8],
                    [x^2 + y^2, x * y]);
                                  2    2
(%o1)           %union([x y = 8, y  + x  = - 3])

For equations that involve complex conjugates, the solver automatically appends the conjugate equations; for example

(%i1) declare(x,complex)$

(%i2) to_poly_solve(x + (5 + %i) * conjugate(x) = 1, x);
                                   %i + 21
(%o2)              %union([x = - -----------])
                                 25 %i - 125
(%i3) declare(y,complex)$

(%i4) to_poly_solve(set(conjugate(x) - y = 42 + %i,
                        x + conjugate(y) = 0), set(x,y));
                           %i - 42        %i + 42
(%o4)        %union([x = - -------, y = - -------])
                              2              2

For an equation that involves the absolute value function, the to_poly_solve consults the fact database to decide if the argument to the absolute value is complex valued. When
```
(%i1) to_poly_solve(abs(x) = 6, x);
(%o1)              %union([x = - 6], [x = 6])
(%i2) declare(z,complex)$

(%i3) to_poly_solve(abs(z) = 6, z);
(%o3) %union(%if((%c11 # 0) %and (%c11 conjugate(%c11) - 36 = 
                                       0), [z = %c11], %union()))
```
This is the only situation that the solver consults the fact database. If a solve variable is declared to be an integer, for example, to_poly_solve ignores this declaration.

Relevant option variables algexact, resultant, algebraic

Related functions to_poly

To use load(to_poly_solve)

Status: The function to_poly_solve is experimental; its specifications might change and its functionality might be merged into other Maxima functions.

Operator: %union (soln_1, soln_2, soln_3, ...)

Operator: %union ()

%union(soln_1, soln_2, soln_3, ...) represents the union of its arguments, each of which represents a solution set, as determined by to_poly_solve. %union() represents the empty set.

In many cases, a solution is a list of equations [x = ..., y = ..., z = ...] where x, y, and z are one or more unknowns. In such cases, to_poly_solve returns a %union expression containing one or more such lists.

The solution set sometimes involves simplifing versions of various of logical operators including %and, %or, or %if for conjunction, disjuntion, and implication, respectively.

Examples:

%union(...) represents the union of its arguments, each of which represents a solution set, as determined by to_poly_solve. In many cases, a solution is a list of equations.

(%i1) load ("to_poly_solve") $
(%i2) to_poly_solve ([sqrt(x^2 - y^2), x + y], [x, y]);
(%o2)    %union([x = 0, y = 0], [x = %c13, y = - %c13])

%union() represents the empty set.

(%i1) load ("to_poly_solve") $
(%i2) to_poly_solve (abs(x) = -1, x);
(%o2)                       %union()

The solution set sometimes involves simplifing versions of various of logical operators.

(%i1) load ("to_poly_solve") $
(%i2) sol : to_poly_solve (abs(x) = a, x);
(%o2) %union(%if(isnonnegative_p(a), [x = - a], %union()), 
                      %if(isnonnegative_p(a), [x = a], %union()))
(%i3) subst (a = 42, sol);
(%o3)             %union([x = - 42], [x = 42])
(%i4) subst (a = -42, sol);
(%o4)                       %union()

88 unit

88.1 Introduction to Units

The unit package enables the user to convert between arbitrary units and work with dimensions in equations. The functioning of this package is radically different from the original Maxima units package - whereas the original was a basic list of definitions, this package uses rulesets to allow the user to chose, on a per dimension basis, what unit final answers should be rendered in. It will separate units instead of intermixing them in the display, allowing the user to readily identify the units associated with a particular answer. It will allow a user to simplify an expression to its fundamental Base Units, as well as providing fine control over simplifying to derived units. Dimensional analysis is possible, and a variety of tools are available to manage conversion and simplification options. In addition to customizable automatic conversion, units also provides a traditional manual conversion option.

Note - when unit conversions are inexact Maxima will make approximations resulting in fractions. This is a consequence of the techniques used to simplify units. The messages warning of this type of substitution are disabled by default in the case of units (normally they are on) since this situation occurs frequently and the warnings clutter the output. (The existing state of ratprint is restored after unit conversions, so user changes to that setting will be preserved otherwise.) If the user needs this information for units, they can set unitverbose:on to reactivate the printing of warnings from the unit conversion process.

unit is included in Maxima in the share/contrib/unit directory. It obeys normal Maxima package loading conventions:

(%i1) load("unit")$
*******************************************************************
*                       Units version 0.50                        *
*          Definitions based on the NIST Reference on             *
*              Constants, Units, and Uncertainty                  *
*       Conversion factors from various sources including         *
*                   NIST and the GNU units package                *
*******************************************************************

Redefining necessary functions...
WARNING: DEFUN/DEFMACRO: redefining function TOPLEVEL-MACSYMA-EVAL ...
WARNING: DEFUN/DEFMACRO: redefining function MSETCHK ...
WARNING: DEFUN/DEFMACRO: redefining function KILL1 ...
WARNING: DEFUN/DEFMACRO: redefining function NFORMAT ...
Initializing unit arrays...
Done.

The WARNING messages are expected and not a cause for concern - they indicate the unit package is redefining functions already defined in Maxima proper. This is necessary in order to properly handle units. The user should be aware that if other changes have been made to these functions by other packages those changes will be overwritten by this loading process.

The unit.mac file also loads a lisp file unit-functions.lisp which contains the lisp functions needed for the package.

Clifford Yapp is the primary author. He has received valuable assistance from Barton Willis of the University of Nebraska at Kearney (UNK), Robert Dodier, and other intrepid folk of the Maxima mailing list.

There are probably lots of bugs. Let me know. float and numer don’t do what is expected.

TODO : dimension functionality, handling of temperature, showabbr and friends. Show examples with addition of quantities containing units.

Category: Physical units · Category: Share packages · Category: Package unit

88.2 Functions and Variables for Units

Function: setunits (list)

By default, the unit package does not use any derived dimensions, but will convert all units to the seven fundamental dimensions using MKS units.

(%i2) N;
                                     kg m
(%o2)                                ----
                                       2
                                      s

(%i3) dyn;
                                   1      kg m
(%o3)                           (------) (----)
                                 100000     2
                                           s

(%i4) g;
                                    1
(%o4)                             (----) (kg)
                                   1000

(%i5) centigram*inch/minutes^2;
                                  127        kg m
(%o5)                       (-------------) (----)
                             1800000000000     2
                                              s

In some cases this is the desired behavior. If the user wishes to use other units, this is achieved with the setunits command:

(%i6) setunits([centigram,inch,minute]);
(%o6)                                done

(%i7) N;
                            1800000000000   %in cg
(%o7)                      (-------------) (------)
                                 127            2
                                            %min

(%i8) dyn;
                               18000000   %in cg
(%o8)                         (--------) (------)
                                 127          2
                                          %min

(%i9) g;
(%o9)                             (100) (cg)

(%i10) centigram*inch/minutes^2;
                                    %in cg
(%o10)                              ------
                                        2
                                    %min

The setting of units is quite flexible. For example, if we want to get back to kilograms, meters, and seconds as defaults for those dimensions we can do:

(%i11) setunits([kg,m,s]);
(%o11)                               done

(%i12) centigram*inch/minutes^2;
                                  127        kg m
(%o12)                      (-------------) (----)
                             1800000000000     2
                                              s

Derived units are also handled by this command:

(%i17) setunits(N);
(%o17)                               done

(%i18) N;
(%o18)                                 N

(%i19) dyn;
                                    1
(%o19)                           (------) (N)
                                  100000

(%i20) kg*m/s^2;
(%o20)                                 N

(%i21) centigram*inch/minutes^2;
                                    127
(%o21)                        (-------------) (N)
                               1800000000000

Notice that the unit package recognized the non MKS combination of mass, length, and inverse time squared as a force, and converted it to Newtons. This is how Maxima works in general. If, for example, we prefer dyne to Newtons, we simply do the following:

(%i22) setunits(dyn);
(%o22)                               done

(%i23) kg*m/s^2;
(%o23)                          (100000) (dyn)

(%i24) centigram*inch/minutes^2;
                                  127
(%o24)                         (--------) (dyn)
                                18000000

To discontinue simplifying to any force, we use the uforget command:

(%i26) uforget(dyn);
(%o26)                               false

(%i27) kg*m/s^2;
                                     kg m
(%o27)                               ----
                                       2
                                      s

(%i28) centigram*inch/minutes^2;
                                  127        kg m
(%o28)                      (-------------) (----)
                             1800000000000     2
                                              s

This would have worked equally well with uforget(N) or uforget(%force).

See also uforget. To use this function write first load("unit").

Function: uforget (list)

By default, the unit package converts all units to the seven fundamental dimensions using MKS units. This behavior can be changed with the setunits command. After that, the user can restore the default behavior for a particular dimension by means of the uforget command:

(%i13) setunits([centigram,inch,minute]);
(%o13)                               done

(%i14) centigram*inch/minutes^2;
                                    %in cg
(%o14)                              ------
                                        2
                                    %min

(%i15) uforget([cg,%in,%min]);
(%o15)                      [false, false, false]

(%i16) centigram*inch/minutes^2;
                                  127        kg m
(%o16)                      (-------------) (----)
                             1800000000000     2
                                              s

uforget operates on dimensions, not units, so any unit of a particular dimension will work. The dimension itself is also a legal argument.

See also setunits. To use this function write first load("unit").

Function: convert (expr, list)

When resetting the global environment is overkill, there is the convert command, which allows one time conversions. It can accept either a single argument or a list of units to use in conversion. When a convert operation is done, the normal global evaluation system is bypassed, in order to avoid the desired result being converted again. As a consequence, for inexact calculations "rat" warnings will be visible if the global environment controlling this behavior (ratprint) is true. This is also useful for spot-checking the accuracy of a global conversion. Another feature is convert will allow a user to do Base Dimension conversions even if the global environment is set to simplify to a Derived Dimension.

(%i2) kg*m/s^2;
                                     kg m
(%o2)                                ----
                                       2
                                      s

(%i3) convert(kg*m/s^2,[g,km,s]);
                                     g km
(%o3)                                ----
                                       2
                                      s

(%i4) convert(kg*m/s^2,[g,inch,minute]);

`rat' replaced 39.37007874015748 by 5000/127 = 39.37007874015748
                              18000000000   %in g
(%o4)                        (-----------) (-----)
                                  127           2
                                            %min

(%i5) convert(kg*m/s^2,[N]);
(%o5)                                  N

(%i6) convert(kg*m^2/s^2,[N]);
(%o6)                                 m N

(%i7) setunits([N,J]);
(%o7)                                done

(%i8) convert(kg*m^2/s^2,[N]);
(%o8)                                 m N

(%i9) convert(kg*m^2/s^2,[N,inch]);

`rat' replaced 39.37007874015748 by 5000/127 = 39.37007874015748
                                 5000
(%o9)                           (----) (%in N)
                                 127

(%i10) convert(kg*m^2/s^2,[J]);
(%o10)                                 J

(%i11) kg*m^2/s^2;
(%o11)                                 J

(%i12) setunits([g,inch,s]);
(%o12)                               done

(%i13) kg*m/s^2;
(%o13)                                 N

(%i14) uforget(N);
(%o14)                               false

(%i15) kg*m/s^2;
                                5000000   %in g
(%o15)                         (-------) (-----)
                                  127       2
                                           s

(%i16) convert(kg*m/s^2,[g,inch,s]);

`rat' replaced 39.37007874015748 by 5000/127 = 39.37007874015748
                                5000000   %in g
(%o16)                         (-------) (-----)
                                  127       2
                                           s

See also setunits and uforget. To use this function write first load("unit").

Optional variable: usersetunits

Default value: none

If a user wishes to have a default unit behavior other than that described, they can make use of maxima-init.mac and the usersetunits variable. The unit package will check on startup to see if this variable has been assigned a list. If it has, it will use setunits on that list and take the units from that list to be defaults. uforget will revert to the behavior defined by usersetunits over its own defaults. For example, if we have a maxima-init.mac file containing:

usersetunits : [N,J];

we would see the following behavior:

(%i1) load("unit")$
*******************************************************************
*                       Units version 0.50                        *
*          Definitions based on the NIST Reference on             *
*              Constants, Units, and Uncertainty                  *
*       Conversion factors from various sources including         *
*                   NIST and the GNU units package                *
*******************************************************************

Redefining necessary functions...
WARNING: DEFUN/DEFMACRO: redefining function
 TOPLEVEL-MACSYMA-EVAL ...
WARNING: DEFUN/DEFMACRO: redefining function MSETCHK ...
WARNING: DEFUN/DEFMACRO: redefining function KILL1 ...
WARNING: DEFUN/DEFMACRO: redefining function NFORMAT ...
Initializing unit arrays...
Done.
User defaults found...
User defaults initialized.

(%i2) kg*m/s^2;
(%o2)                                  N

(%i3) kg*m^2/s^2;
(%o3)                                  J

(%i4) kg*m^3/s^2;
(%o4)                                 J m

(%i5) kg*m*km/s^2;
(%o5)                             (1000) (J)

(%i6) setunits([dyn,eV]);
(%o6)                                done

(%i7) kg*m/s^2;
(%o7)                           (100000) (dyn)

(%i8) kg*m^2/s^2;
(%o8)                     (6241509596477042688) (eV)

(%i9) kg*m^3/s^2;
(%o9)                    (6241509596477042688) (eV m)

(%i10) kg*m*km/s^2;
(%o10)                   (6241509596477042688000) (eV)

(%i11) uforget([dyn,eV]);
(%o11)                           [false, false]

(%i12) kg*m/s^2;
(%o12)                                 N

(%i13) kg*m^2/s^2;
(%o13)                                 J

(%i14) kg*m^3/s^2;
(%o14)                                J m

(%i15) kg*m*km/s^2;
(%o15)                            (1000) (J)

Without usersetunits, the initial inputs would have been converted to MKS, and uforget would have resulted in a return to MKS rules. Instead, the user preferences are respected in both cases. Notice these can still be overridden if desired. To completely eliminate this simplification - i.e. to have the user defaults reset to factory defaults - the dontusedimension command can be used. uforget can restore user settings again, but only if usedimension frees it for use. Alternately, kill(usersetunits) will completely remove all knowledge of the user defaults from the session. Here are some examples of how these various options work.

(%i2) kg*m/s^2;
(%o2)                                  N

(%i3) kg*m^2/s^2;
(%o3)                                  J

(%i4) setunits([dyn,eV]);
(%o4)                                done

(%i5) kg*m/s^2;
(%o5)                           (100000) (dyn)

(%i6) kg*m^2/s^2;
(%o6)                     (6241509596477042688) (eV)

(%i7) uforget([dyn,eV]);
(%o7)                          [false, false]

(%i8) kg*m/s^2;
(%o8)                                  N

(%i9) kg*m^2/s^2;
(%o9)                                  J

(%i10) dontusedimension(N);
(%o10)                             [%force]

(%i11) dontusedimension(J);
(%o11)                         [%energy, %force]

(%i12) kg*m/s^2;
                                     kg m
(%o12)                               ----
                                       2
                                      s

(%i13) kg*m^2/s^2;
                                         2
                                     kg m
(%o13)                               -----
                                       2
                                      s

(%i14) setunits([dyn,eV]);
(%o14)                               done

(%i15) kg*m/s^2;
                                     kg m
(%o15)                               ----
                                       2
                                      s

(%i16) kg*m^2/s^2;
                                         2
                                     kg m
(%o16)                               -----
                                       2
                                      s

(%i17) uforget([dyn,eV]);
(%o17)                         [false, false]

(%i18) kg*m/s^2;
                                     kg m
(%o18)                               ----
                                       2
                                      s

(%i19) kg*m^2/s^2;
                                         2
                                     kg m
(%o19)                               -----
                                       2
                                      s

(%i20) usedimension(N);
Done.  To have Maxima simplify to this dimension, use
setunits([unit]) to select a unit.
(%o20)                               true

(%i21) usedimension(J);
Done.  To have Maxima simplify to this dimension, use
setunits([unit]) to select a unit.
(%o21)                               true

(%i22) kg*m/s^2;
                                     kg m
(%o22)                               ----
                                       2
                                      s

(%i23) kg*m^2/s^2;
                                         2
                                     kg m
(%o23)                               -----
                                       2
                                      s

(%i24) setunits([dyn,eV]);
(%o24)                               done

(%i25) kg*m/s^2;
(%o25)                          (100000) (dyn)

(%i26) kg*m^2/s^2;
(%o26)                    (6241509596477042688) (eV)

(%i27) uforget([dyn,eV]);
(%o27)                           [false, false]

(%i28) kg*m/s^2;
(%o28)                                 N

(%i29) kg*m^2/s^2;
(%o29)                                 J

(%i30) kill(usersetunits);
(%o30)                               done

(%i31) uforget([dyn,eV]);
(%o31)                          [false, false]

(%i32) kg*m/s^2;
                                     kg m
(%o32)                               ----
                                       2
                                      s

(%i33) kg*m^2/s^2;
                                         2
                                     kg m
(%o33)                               -----
                                       2
                                      s

Unfortunately this wide variety of options is a little confusing at first, but once the user grows used to them they should find they have very full control over their working environment.

Function: metricexpandall (x)

Rebuilds global unit lists automatically creating all desired metric units. x is a numerical argument which is used to specify how many metric prefixes the user wishes defined. The arguments are as follows, with each higher number defining all lower numbers’ units:

           0 - none. Only base units
           1 - kilo, centi, milli
(default)  2 - giga, mega, kilo, hecto, deka, deci, centi, milli,
               micro, nano
           3 - peta, tera, giga, mega, kilo, hecto, deka, deci,
               centi, milli, micro, nano, pico, femto
           4 - all

Normally, Maxima will not define the full expansion since this results in a very large number of units, but metricexpandall can be used to rebuild the list in a more or less complete fashion. The relevant variable in the unit.mac file is %unitexpand.

Variable: %unitexpand

Default value: 2

This is the value supplied to metricexpandall during the initial loading of unit.

Category: Share packages · Category: Package wrstcse

89 wrstcse

89.1 Introduction to wrstcse

wrstcse is a naive go at interval arithmetics is powerful enough to perform worst case calculations that appear in engineering by applying all combinations of tolerances to all parameters.

This approach isn’t guaranteed to find the exact combination of parameters that results in the worst-case. But it avoids the problems that make a true interval arithmetics affected by the halting problem as an equation can have an infinite number of local minima and maxima and it might be impossible to algorithmically determine which one is the global one.

Tolerances are applied to parameters by providing the parameter with a tol[n] that wrstcase will vary between -1 and 1. Using the same n for two parameters will make both parameters tolerate in the same way.

load ("wrstcse") loads this package.

89.2 Functions and Variables for wrstcse

Function: wc_typicalvalues (expression, [num])

Returns what happens if all tolerances (that are represented by tol [n] that can vary from 0 to 1) happen to be 0.

Example:

(%i1) load("wrstcse")$

(%i2) vals: [
   R_1= 1000.0*(1+tol[1]*.01),
   R_2= 2000.0*(1+tol[2]*.01)
 ];
(%o2) [R_1 = 1000.0 (0.01 tol  + 1), 
                             1
                                    R_2 = 2000.0 (0.01 tol  + 1)]
                                                          2

(%i3) divider:U_Out=U_In*R_1/(R_1+R_2);
                                R_1 U_In
(%o3)                   U_Out = ---------
                                R_2 + R_1

(%i4) wc_typicalvalues(vals);
(%o4)             [R_1 = 1000.0, R_2 = 2000.0]

(%i5) wc_typicalvalues(subst(vals,divider));
(%o5)            U_Out = 0.3333333333333333 U_In

Function: wc_inputvalueranges (expression, [num])

Convenience function: Displays a list which parameter can vary between which values.

Example:

(%i1) load("wrstcse")$

(%i2) vals: [
   R_1= 1000.0*(1+tol[1]*.01),
   R_2= 2000.0*(1+tol[2]*.01)
 ];
(%o2) [R_1 = 1000.0 (0.01 tol  + 1), 
                             1
                                    R_2 = 2000.0 (0.01 tol  + 1)]
                                                          2

(%i3) wc_inputvalueranges(vals);
        [ R_1  min = 990.0   typ = 1000.0  max = 1010.0 ]
(%o3)   [                                               ]
        [ R_2  min = 1980.0  typ = 2000.0  max = 2020.0 ]

Function: wc_systematic (expression, [num])

Systematically introduces num values per parameter into expression and returns a list of the result. If no num is given, num defaults to 3.

90 zeilberger

90.1 Introduction to zeilberger

zeilberger is a implementation of Zeilberger’s algorithm for definite hypergeometric summation, and also Gosper’s algorithm for indefinite hypergeometric summation.

zeilberger makes use of the "filtering" optimization method developed by Axel Riese.

zeilberger was developed by Fabrizio Caruso.

load ("zeilberger") loads this package.

Category: Sums and products · Category: Share packages · Category: Package zeilberger

90.1.1 The indefinite summation problem

zeilberger implements Gosper’s algorithm for indefinite hypergeometric summation. Given a hypergeometric term F_k in k we want to find its hypergeometric anti-difference, that is, a hypergeometric term f_k such that

F_k = f_(k+1) - f_k.

90.1.2 The definite summation problem

zeilberger implements Zeilberger’s algorithm for definite hypergeometric summation. Given a proper hypergeometric term (in n and k) F_(n,k) and a positive integer d we want to find a d-th order linear recurrence with polynomial coefficients (in n) for F_(n,k) and a rational function R in n and k such that

a_0 F_(n,k) + ... + a_d F_(n+d),k = Delta_k(R(n,k) F_(n,k)),

where Delta_k is the k-forward difference operator, i.e., Delta_k(t_k) := t_(k+1) - t_k.

90.1.3 Verbosity levels

There are also verbose versions of the commands which are called by adding one of the following prefixes:

Summary: Just a summary at the end is shown
Verbose: Some information in the intermidiate steps
VeryVerbose: More information
Extra: Even more information including information on the linear system in Zeilberger’s algorithm

For example:
GosperVerbose, parGosperVeryVerbose, ZeilbergerExtra, AntiDifferenceSummary.

90.2 Functions and Variables for zeilberger

Function: AntiDifference (F_k, k)

Returns the hypergeometric anti-difference of F_k, if it exists.
Otherwise AntiDifference returns no_hyp_antidifference.

Function: Gosper (F_k, k)

Returns the rational certificate R(k) for F_k, that is, a rational function such that F_k = R(k+1) F_(k+1) - R(k) F_k, if it exists. Otherwise, Gosper returns no_hyp_sol.

Function: GosperSum (F_k, k, a, b)

Returns the summmation of F_k from k = a to k = b if F_k has a hypergeometric anti-difference. Otherwise, GosperSum returns nongosper_summable.

Examples:

(%i1) load ("zeilberger")$

(%i2) GosperSum ((-1)^k*k / (4*k^2 - 1), k, 1, n);
Dependent equations eliminated:  (1)
                           3       n + 1
                      (n + -) (- 1)
                           2               1
(%o2)               - ------------------ - -
                                  2        4
                      2 (4 (n + 1)  - 1)

(%i3) GosperSum (1 / (4*k^2 - 1), k, 1, n);
                                3
                          - n - -
                                2       1
(%o3)                  -------------- + -
                                2       2
                       4 (n + 1)  - 1

(%i4) GosperSum (x^k, k, 1, n);
                          n + 1
                         x          x
(%o4)                    ------ - -----
                         x - 1    x - 1

(%i5) GosperSum ((-1)^k*a! / (k!*(a - k)!), k, 1, n);
                                n + 1
                a! (n + 1) (- 1)              a!
(%o5)       - ------------------------- - ----------
              a (- n + a - 1)! (n + 1)!   a (a - 1)!

(%i6) GosperSum (k*k!, k, 1, n);
Dependent equations eliminated:  (1)
(%o6)                     (n + 1)! - 1

(%i7) GosperSum ((k + 1)*k! / (k + 1)!, k, 1, n);
                  (n + 1) (n + 2) (n + 1)!
(%o7)             ------------------------ - 1
                          (n + 2)!

(%i8) GosperSum (1 / ((a - k)!*k!), k, 1, n);
(%o8)                  NON_GOSPER_SUMMABLE

Function: parGosper (F_(n,k), k, n, d)

Attempts to find a d-th order recurrence for F_(n,k).

The algorithm yields a sequence [s_1, s_2, ..., s_m] of solutions. Each solution has the form

[R(n, k), [a_0, a_1, ..., a_d]].

parGosper returns [] if it fails to find a recurrence.

Function: Zeilberger (F_(n,k), k, n)

Attempts to compute the indefinite hypergeometric summation of F_(n,k).

Zeilberger first invokes Gosper, and if that fails to find a solution, then invokes parGosper with order 1, 2, 3, ..., up to MAX_ORD. If Zeilberger finds a solution before reaching MAX_ORD, it stops and returns the solution.

The algorithms yields a sequence [s_1, s_2, ..., s_m] of solutions. Each solution has the form

[R(n,k), [a_0, a_1, ..., a_d]].

Zeilberger returns [] if it fails to find a solution.

Zeilberger invokes Gosper only if Gosper_in_Zeilberger is true.

90.3 General global variables

Global variable: MAX_ORD

Default value: 5

MAX_ORD is the maximum recurrence order attempted by Zeilberger.

Global variable: simplified_output

Default value: false

When simplified_output is true, functions in the zeilberger package attempt further simplification of the solution.

Global variable: linear_solver

Default value: linsolve

linear_solver names the solver which is used to solve the system of equations in Zeilberger’s algorithm.

Global variable: warnings

Default value: true

When warnings is true, functions in the zeilberger package print warning messages during execution.

Global variable: Gosper_in_Zeilberger

Default value: true

When Gosper_in_Zeilberger is true, the Zeilberger function calls Gosper before calling parGosper. Otherwise, Zeilberger goes immediately to parGosper.

Global variable: trivial_solutions

Default value: true

When trivial_solutions is true, Zeilberger returns solutions which have certificate equal to zero, or all coefficients equal to zero.

90.4 Variables related to the modular test

Global variable: mod_test

Default value: false

When mod_test is true, parGosper executes a modular test for discarding systems with no solutions.

Global variable: modular_linear_solver

Default value: linsolve

modular_linear_solver names the linear solver used by the modular test in parGosper.

Global variable: ev_point

Default value: big_primes[10]

ev_point is the value at which the variable n is evaluated when executing the modular test in parGosper.

Global variable: mod_big_prime

Default value: big_primes[1]

mod_big_prime is the modulus used by the modular test in parGosper.

Global variable: mod_threshold

Default value: 4

mod_threshold is the greatest order for which the modular test in parGosper is attempted.

91 Error and warning messages

This chapter provides detailed information about the meaning of some error messages or on how to recover from errors.

91.1 Error messages

91.1.1 apply: no such "list" element

One common cause for this error message is that square brackets operator ([ ]) was used trying to access a list element that whose element number was < 1 or > length(list).

91.1.2 argument must be a non-atomic expression

This normally means that a list, a set or something else that consists of more than one element was expected. One possible cause for this error message is a construct of the following type:

(%i1) l:[1,2,3];
(%o1)                       [1, 2, 3]

(%i2) append(l,4);
append: argument must be a non-atomic expression; found 4
 -- an error. To debug this try: debugmode(true);

The correct way to append variables or numbers to a list is to wrap them in a single-element list first:

(%i1) l:[1,2,3];
(%o1)                       [1, 2, 3]

(%i2) append(l,[4]);
(%o2)                     [1, 2, 3, 4]

91.1.3 assignment: cannot assign to <function name>

Maxima supports several assignment operators. When trying to define a function := has to be used.

91.1.4 expt: undefined: 0 to a negative exponent.

This message notifies about a classical division by zero error.

91.1.5 incorrect syntax: , is not a prefix operator

This might be caused by a command starting with a comma (,) or by one comma being directly followed by another one..

91.1.6 incorrect syntax: Illegal use of delimiter )

Common reasons for this error appearing are a closing parenthesis without an opening one or a closing parenthesis directly preceded by a comma.

91.1.7 loadfile: failed to load <filename>

This error message normally indicates that the file exists, but can not be read. If the file is present and readable there is another possible for this error message: Maxima can compile packages to native binary files in order to make them run faster. If after compiling the file something in the system has changed in a way that makes it incompatible with the binary the binary the file cannot be loaded any more. Maxima normally puts binary files it creates from its own packages in a folder named binary within the folder whose name it is printed after typing:

(%i1) maxima_userdir;
(%o1)                 /home/gunter/.maxima

If this directory is missing maxima will recreate it again as soon as it has to compile a package.

91.1.8 makelist: second argument must evaluate to a number

makelist expects the second argument to be the name of the variable whose value is to be stepped. This time instead of the name of a still-undefined variable maxima has found something else, possibly a list or the name of a list.

91.1.9 Only symbols can be bound

The most probable cause for this error is that there was an attempt to either use a number or a variable whose numerical value is known as a loop counter.

91.1.10 operators of arguments must all be the same

One possible reason for this error message to appear is a try to use append in order to add an equation to a list:

(%i1) l:[a=1,b=2,c=3];
(%o1)                 [a = 1, b = 2, c = 3]

(%i2) append(l,d=5);
append: operators of arguments must all be the same.
 -- an error. To debug this try: debugmode(true);

In order to add an equation to a list it has to be wrapped in a single-element list first:

(%i1) l:[a=1,b=2,c=3];
(%o1)                 [a = 1, b = 2, c = 3]

(%i2) append(l,[d=5]);
(%o2)             [a = 1, b = 2, c = 3, d = 5]

91.1.11 Out of memory

Lisp typically handles several types of memory containing at least one stack and a heap that contains user objects. To avoid running out of memory several approaches might be useful:

If possible, the best solution normally is to use an algorithm that is more memory-efficient.
Compiling a function might drastically reduce the amount of memory it needs.
Arrays of a fixed type might be more memory-efficient than lists.
If maxima is run by sbcl sbcl’s memory limit might be set to a value that is too low to solve the current problem. In this case the command-line option --dynamic-space-size <n> allows to tell sbcl to reserve n megabytes for the heap. It is to note, though, that sbcl has to handle several distinct types of memory and therefore might be able to only reserve about half of the available physical memory. Also note that 32-bit processes might only be able to access 2GB of physical memory.

91.1.12 part: fell off the end

part() was used to access the nth item in something that has less than n items.

91.1.13 undefined variable (draw or plot)

A function could not be plotted since it still contained a variable maxima doesn’t know the value of.

In order to find out which variable this could be it is sometimes helpful to temporarily replace the name of the drawing command (draw2d, plot2d or similar) by a random name (for example ddraw2d) that doesn’t coincide with the name of an existing function to make maxima print out what parameters the drawing command sees.

(%i1) load("draw")$
(%i2) f(x):=sin(omega*t);
(%o2) f(x) := sin(omega t)
(%i3) draw2d(
        explicit(
          f(x),
          x,1,10
        )
      );
draw2d (explicit): non defined variable
 -- an error. To debug this try: debugmode(true);
(%i4) ddraw2d(
        explicit(
          f(x),
          x,1,10
        )
      );
(%o4) ddraw2d(explicit(sin(omega t), x, 1, 10))

91.1.14 VTK is not installed, which is required for Scene

This might either mean that VTK is actually not installed - or cannot be found by maxima - or that maxima has no write access to the directory whose name is output if the following maxima command is entered:

(%i1) maxima_tempdir;
(%o1)                         /tmp

91.2 Warning messages

91.2.1 Encountered undefined variable <x> in translation

A function was compiled but the type of the variable x was not known. This means that the compiled command contains additional code that makes it retain all the flexibility maxima provides in respect to this variable. If x isn’t meant as a variable name but just a named option to a command prepending the named option by a single quote (') should resolve this issue.