Wolfram Mathematica Tutorial Collection

CORE LANGUAGE

For use with Wolfram Mathematica 7.0 and later.

For the latest updates and corrections to this manual:visit reference.wolfram.comFor information on additional copies of this documentation:visit the Customer Service website at www.wolfram.com/services/customerserviceor email Customer Service at info@wolfram.comComments on this manual are welcomed at:comments@wolfram.comPrinted in the United States of America.15 14 13 12 11 10 9 8 7 6 5 4 3 2

2008 Wolfram Research, Inc.

All rights reserved. No part of this document may be reproduced or transmitted, in any form or by any means,electronic, mechanical, photocopying, recording or otherwise, without the prior written permission of the copyrightholder.Wolfram Research is the holder of the copyright to the Wolfram Mathematica software system ("Software") describedin this document, including without limitation such aspects of the system as its code, structure, sequence,organization, look and feel, programming language, and compilation of command names. Use of the Softwareunless pursuant to the terms of a license granted by Wolfram Research or as otherwise authorized by law is aninfringement of the copyright.Wolfram Research, Inc. and Wolfram Media, Inc. ("Wolfram") make no representations, express,statutory, or implied, with respect to the Software (or any aspect thereof), including, without limitation,any implied warranties of merchantability, interoperability, or fitness for a particular purpose, all of whichare expressly disclaimed. Wolfram does not warrant that the functions of the Software will meet yourrequirements or that the operation of the Software will be uninterrupted or error free. As such, Wolframdoes not recommend the use of the software described in this document for applications in which errorsor omissions could threaten life, injury or significant loss.Mathematica, MathLink, and MathSource are registered trademarks of Wolfram Research, Inc. J/Link, MathLM,.NET/Link, and webMathematica are trademarks of Wolfram Research, Inc. Windows is a registered trademark ofMicrosoft Corporation in the United States and other countries. Macintosh is a registered trademark of AppleComputer, Inc. All other trademarks used herein are the property of their respective owners. Mathematica is notassociated with Mathematica Policy Research, Inc.

Building Up CalculationsUsing Previous ResultsIn doing calculations, you will often need to use previous results that you have got. In Mathemat ica, % always stands for your last result.

the last result generated

%%

the next-to-last result

%% % Hk timesL

the kth previous result

%n

the result on output line Out@nD (to be used with care)

Ways to refer to your previous results.

Here is the first result.In[1]:=

77 ^ 2

Out[1]= 5929

This adds 1 to the last result.

In[2]:=Out[2]=

%+15930

This uses both the last result, and the result before that.In[3]:=Out[3]=

3 % + % ^ 2 + %%35 188 619

You will have noticed that all the input and output lines in Mathematica are numbered. You canuse these numbers to refer to previous results.This adds the results on lines 2 and 3 above.In[4]:=Out[4]=

%2 + %335 194 549

If you use a text-based interface to Mathematica, then successive input and output lines willalways appear in order. However, if you use a notebook interface to Mathematica, as discussedin "Notebook Interfaces", then successive input and output lines need not appear in order. Youcan for example "scroll back" and insert your next calculation wherever you want in the note-

Core Language

If you use a text-based interface to Mathematica, then successive input and output lines willalways appear in order. However, if you use a notebook interface to Mathematica, as discussedin "Notebook Interfaces", then successive input and output lines need not appear in order. Youcan for example "scroll back" and insert your next calculation wherever you want in the notebook. You should realize that % is always defined to be the last result that Mathematica generated. This may or may not be the result that appears immediately above your present positionin the notebook. With a notebook interface, the only way to tell when a particular result wasgenerated is to look at the Out@nD label that it has. Because you can insert and delete anywhere in a notebook, the textual ordering of results in a notebook need have no relation to theorder in which the results were generated.

Defining VariablesWhen you do long calculations, it is often convenient to give names to your intermediateresults. Just as in standard mathematics, or in other computer languages, you can do this byintroducing named variables.This sets the value of the variable x to be 5.In[1]:=

x=5

Out[1]= 5

Whenever x appears, Mathematica now replaces it with the value 5.

In[2]:=

x^2

Out[2]= 25

This assigns a new value to x.

In[3]:=

x = 7+4

Out[3]= 11

pi is set to be the numerical value of p to 40-digit accuracy.

In[4]:=

pi = N@Pi, 40D

Out[4]= 3.141592653589793238462643383279502884197

Core Language

Here is the value you defined for pi.

In[5]:=

pi

Out[5]= 3.141592653589793238462643383279502884197

This gives the numerical value of p2 , to the same accuracy as pi.

In[6]:=

pi ^ 2

Out[6]= 9.86960440108935861883449099987615113531

x=value

assign a value to the variable x

x=y=value

assign a value to both x and y

x=. or Clear@xD

remove any value assigned to x

Assigning values to variables.

It is very important to realize that values you assign to variables are permanent. Once youhave assigned a value to a particular variable, the value will be kept until you explicitly removeit. The value will, of course, disappear if you start a whole new Mathematica session.Forgetting about definitions you made earlier is the single most common cause of mistakeswhen using Mathematica. If you set x = 5, Mathematica assumes that you always want x tohave the value 5, until or unless you explicitly tell it otherwise. To avoid mistakes, you shouldremove values you have defined as soon as you have finished using them. Remove values you assign to variables as soon as you finish using them.A useful principle in using Mathematica.

The variables you define can have almost any name. There is no limit on the length of theirnames. One constraint, however, is that variable names can never start with numbers. Forexample, x2 could be a variable, but 2 x means 2 * x.Mathematica uses both uppercase and lowercase letters. There is a convention that built-inMathematica objects always have names starting with uppercase (capital) letters. To avoidconfusion, you should always choose names for your own variables that start with lowercaseletters.

Core Language

aaaaa

a variable name containing only lowercase letters

Aaaaa

a built-in object whose name begins with a capital letter

Naming conventions.

You can type formulas involving variables in Mathematica almost exactly as you would in mathematics. There are a few important points to watch, however. x y means x times y. xy with no space is the variable with name xy. 5 x means 5 times x. x ^ 2 y means Hx ^ 2L y, not x ^ H2 yL.Some points to watch when using variables in Mathematica.

Values for Symbols

When Mathematica transforms an expression such as x + x into 2 x, it is treating the variable xin a purely symbolic or formal fashion. In such cases, x is a symbol which can stand for anyexpression.Often, however, you need to replace a symbol like x with a definite value. Sometimes thisvalue will be a number; often it will be another expression.To take an expression such as 1 + 2 x and replace the symbol x that appears in it with a definitevalue, you can create a Mathematica transformation rule, and then apply this rule to the expression. To replace x with the value 3, you would create the transformation rule x -> 3. You musttype -> as a pair of characters, with no space in between. You can think of x -> 3 as being arule in which x goes to 3.To apply a transformation rule to a particular Mathematica expression, you type expr . rule. Thereplacement operator . is typed as a pair of characters, with no space in between.This uses the transformation rule x -> 3 in the expression 1 + 2 x.In[1]:=Out[1]=

1 + 2 x . x -> 37

Core Language

You can replace x with any expression. Here every occurrence of x is replaced by 2 - y.In[2]:=Out[2]=

1 + x + x ^ 2 . x -> 2 - y3 + H2 - yL2 - y

Here is a transformation rule. Mathematica treats it like any other symbolic expression.In[3]:=Out[3]=

x -> 3 + yx3+y

This applies the transformation rule on the previous line to the expression x ^ 2 - 9.In[4]:=Out[4]=

x ^ 2 - 9 . %-9 + H3 + yL2

expr.x->value

replace x by value in the expression expr

expr.8x->xval,y->yval<

perform several replacements

Replacing symbols by values in expressions.

You can apply rules together by putting the rules in a list.In[5]:=Out[5]=

Hx + yL Hx - yL ^ 2 . 8x -> 3, y -> 1 - a<

H4 - aL H2 + aL2

The replacement operator . allows you to apply transformation rules to a particular expression. Sometimes, however, you will want to define transformation rules that should always beapplied. For example, you might want to replace x with 3 whenever x occurs.As discussed in "Defining Variables", you can do this by assigning the value 3 to x using x = 3.Once you have made the assignment x = 3, x will always be replaced by 3, whenever itappears.This assigns the value 3 to x.In[6]:=Out[6]=

x=33

Now x will automatically be replaced by 3 wherever it appears.

In[7]:=Out[7]=

x^2 - 18

This assigns the expression 1 + a to be the value of x.

Core Language

This assigns the expression 1 + a to be the value of x.

In[8]:=Out[8]=

x = 1+a1+a

Now x is replaced by 1 + a.In[9]:=Out[9]=

x^2 - 1-1 + H1 + aL2

You can define the value of a symbol to be any expression, not just a number. You shouldrealize that once you have given such a definition, the definition will continue to be used whenever the symbol appears, until you explicitly change or remove the definition. For most people,forgetting to remove values you have assigned to symbols is the single most common source ofmistakes in using Mathematica.

x=value

define a value for x which will always be used

x=.

remove any value defined for x

Assigning values to symbols.

The symbol x still has the value you assigned to it.In[10]:=Out[10]=

x+5-2x6 + a - 2 H1 + aL

This removes the value you assigned to x.

In[11]:=

x =.Now x has no value defined, so it can be used as a purely symbolic variable.

In[12]:=

x+5-2x

Out[12]= 5 - x

A symbol such as x can serve many different purposes in Mathematica, and in fact, much of theflexibility of Mathematica comes from being able to mix these purposes at will. However, youneed to keep some of the different uses of x straight in order to avoid making mistakes. Themost important distinction is between the use of x as a name for another expression, and as asymbolic variable that stands only for itself.Traditional programming languages that do not support symbolic computation allow variables tobe used only as names for objects, typically numbers, that have been assigned as values forthem. In Mathematica, however, x can also be treated as a purely formal variable, to whichvarious transformation rules can be applied. Of course, if you explicitly give a definition, such as

Core Language

Traditional programming languages that do not support symbolic computation allow variables tobe used only as names for objects, typically numbers, that have been assigned as values forthem. In Mathematica, however, x can also be treated as a purely formal variable, to whichvarious transformation rules can be applied. Of course, if you explicitly give a definition, such asx = 3, then x will always be replaced by 3, and can no longer serve as a formal variable.You should understand that explicit definitions such as x = 3 have a global effect. On the otherhand, a replacement such as expr . x -> 3 affects only the specific expression expr. It is usuallymuch easier to keep things straight if you avoid using explicit definitions except when absolutely necessary.You can always mix replacements with assignments. With assignments, you can give names toexpressions in which you want to do replacements, or to rules that you want to use to do thereplacements.This assigns a value to the symbol t.In[13]:=Out[13]=

t = 1 + x^21 + x2

This finds the value of t, and then replaces x by 2 in it.

In[14]:=

t . x -> 2

Out[14]= 5

This finds the value of t for a different value of x.

In[15]:=Out[15]=

t . x -> 5 a1 + 25 a2

This finds the value of t when x is replaced by Pi , and then evaluates the result numerically.In[16]:=Out[16]=

t . x -> Pi N10.8696

Core Language

The Four Kinds of Bracketing in Mathematica

There are four kinds of bracketing used in Mathematica. Each kind of bracketing has a verydifferent meaning. It is important that you remember all of them.

HtermL

parentheses for grouping

f @xD

square brackets for functions

8a,b,c<

curly braces for lists

v@@iDD

double brackets for indexing (Part@v, iD)

The four kinds of bracketing in Mathematica.

When the expressions you type in are complicated, it is often a good idea to put extra spaceinside each set of brackets. This makes it somewhat easier for you to see matching pairs ofbrackets. v@@ 8a, b< DD is, for example, easier to recognize than v@@8a, b<DD.

Sequences of OperationsIn doing a calculation with Mathematica, you usually go through a sequence of steps. If youwant to, you can do each step on a separate line. Often, however, you will find it convenient toput several steps on the same line. You can do this simply by separating the pieces of input youwant to give with semicolons.

expr1 ;expr2 ;expr3

do several operations, and give the result of the last one

expr1 ;expr2 ;

do the operations, but print no output

Ways to do sequences of operations in Mathematica.

This does three operations on the same line. The result is the result from the last operation.In[1]:=Out[1]=

x = 4; y = 6; z = y + 612

If you end your input with a semicolon, it is as if you are giving a sequence of operations, withan empty one at the end. This has the effect of making Mathematica perform the operationsyou specify, but display no output.

Core Language

do an operation, but display no output

expr;Inhibiting output.

Putting a semicolon at the end of the line tells Mathematica to show no output.In[2]:=

x = 67 - 5;You can still use % to get the output that would have been shown.

In[3]:=Out[3]=

%62

10

Core Language

ListsMaking Lists of ObjectsIn doing calculations, it is often convenient to collect together several objects, and treat themas a single entity. Lists give you a way to make collections of objects in Mathematica. As youwill see later, lists are very important and general structures in Mathematica.A list such as 83, 5, 1< is a collection of three objects. But in many ways, you can treat thewhole list as a single object. You can, for example, do arithmetic on the whole list at once, orassign the whole list to be the value of a variable.Here is a list of three numbers.In[1]:=

83, 5, 1<

Out[1]= 83, 5, 1<

This squares each number in the list, and adds 1 to it.

In[2]:=Out[2]=

83, 5, 1< ^ 2 + 1810, 26, 2<

This takes differences between corresponding elements in the two lists. The lists must be thesame length.In[3]:=Out[3]=

86, 7, 8< - 83.5, 4, 2.5<

82.5, 3, 5.5<

The value of % is the whole list.

In[4]:=Out[4]=

%82.5, 3, 5.5<

You can apply any of the mathematical functions in "Some Mathematical Functions" to wholelists.In[5]:=Out[5]=

Exp@%D N812.1825, 20.0855, 244.692<

Just as you can set variables to be numbers, so also you can set them to be lists.This assigns v to be a list.

Core Language

11

This assigns v to be a list.

In[6]:=Out[6]=

v = 82, 4, 3.1<82, 4, 3.1<

Wherever v appears, it is replaced by the list.

In[7]:=Out[7]=

v Hv - 1L:2,

, 1.47619>

Collecting Objects Together

We first encountered lists in "Making Lists of Objects" as a way of collecting numbers together.Here, we shall see many different ways to use lists. You will find that lists are some of the mostflexible and powerful objects in Mathematica. You will see that lists in Mathematica representgeneralizations of several standard concepts in mathematics and computer science.At a basic level, what a Mathematica list essentially does is to provide a way for you to collecttogether several expressions of any kind.Here is a list of numbers.In[1]:=Out[1]=

82, 3, 4<82, 3, 4<

This gives a list of symbolic expressions.

In[2]:=Out[2]=

x^% - 19-1 + x2 , -1 + x3 , -1 + x4 =

You can differentiate these expressions.

In[3]:=Out[3]=

D@%, xD92 x, 3 x2 , 4 x3 =

And then you can find values when x is replaced with 3.

In[4]:=Out[4]=

% . x -> 386, 27, 108<

The mathematical functions that are built into Mathematica are mostly set up to be "listable" sothat they act separately on each element of a list. This is, however, not true of all functions inMathematica. Unless you set it up specially, a new function f that you introduce will treat lists

12

Core Language

The mathematical functions that are built into Mathematica are mostly set up to be "listable" sothat they act separately on each element of a list. This is, however, not true of all functions inMathematica. Unless you set it up specially, a new function f that you introduce will treat listsjust as single objects. "Applying Functions to Parts of Expressions" and "Structural Operations"will describe how you can use Map and Thread to apply a function like this separately to eachelement in a list.

Making Tables of Values

You can use lists as tables of values. You can generate the tables, for example, by evaluatingan expression for a sequence of different parameter values.This gives a table of the values of i2 , with i running from 1 to 6.In[1]:=Out[1]=

Table@i ^ 2, 8i, 6<D

81, 4, 9, 16, 25, 36<

Here is a table of sinHn 5L for n from 0 to 4.

In[2]:=Out[2]=

Table@Sin@n 5D, 8n, 0, 4<D

1234:0, SinB F, SinB F, SinB F, SinB F>5555

This gives the numerical values.

In[3]:=

N@%D

Out[3]= 80., 0.198669, 0.389418, 0.564642, 0.717356<

You can also make tables of formulas.

In[4]:=Out[4]=

Table@x ^ i + 2 i, 8i, 5<D

92 + x, 4 + x2 , 6 + x3 , 8 + x4 , 10 + x5 =

Table uses exactly the same iterator notation as the functions Sum and Product , which arediscussed in "Sums and Products".In[5]:=Out[5]=

Product@x ^ i + 2 i, 8i, 5<D

H2 + xL I4 + x2 M I6 + x3 M I8 + x4 M I10 + x5 M

Core Language

13

This makes a table with values of x running from 0 to 1 in steps of 0.25.

In[6]:=Out[6]=

Table@Sqrt@xD, 8x, 0, 1, 0.25<D

80, 0.5, 0.707107, 0.866025, 1.<

You can perform other operations on the lists you get from Table .In[7]:=Out[7]=

%^2 + 383, 3.25, 3.5, 3.75, 4.<

TableForm displays lists in a "tabular" format. Notice that both words in the name TableFormbegin with capital letters.In[8]:=

% TableForm

33.25Out[8]//TableForm= 3.53.754.

All the examples so far have been of tables obtained by varying a single parameter. You canalso make tables that involve several parameters. These multidimensional tables are specifiedusing the standard Mathematica iterator notation, discussed in "Sums and Products".This makes a table of x i + y j with i running from 1 to 3 and j running from 1 to 2.In[9]:=Out[9]=

Table@x ^ i + y ^ j, 8i, 3<, 8j, 2<D

99x + y, x + y2 =, 9x2 + y, x2 + y2 =, 9x3 + y, x3 + y2 ==

The table in this example is a list of lists. The elements of the outer list correspond to successive values of i. The elements of each inner list correspond to successive values of j, with ifixed.Sometimes you may want to generate a table by evaluating a particular expression manytimes, without incrementing any variables.This creates a list containing four copies of the symbol x.In[10]:=Out[10]=

Table@x, 84<D8x, x, x, x<

14

Core Language

This gives a list of four pairs of numbers sampled from 81, 2, 3, 4<. Table re-evaluatesRandomSample @81, 2, 3, 4<, 2D for each element in the list, so that you get four differentsamples.Table@RandomSample@81, 2, 3, 4<, 2D, 84<D

In[11]:=

Out[11]= 883, 2<, 84, 2<, 84, 3<, 82, 1<<

This evaluatesTableB

In[12]:=

i for each of the values of i in the list 81, 4, 9, 16<.

i , 8i, 81, 4, 9, 16<<F

Out[12]= 81, 2, 3, 4<

This creates a 32 table.

Table@i + 2 j, 8i, 3<, 8j, 2<D

In[13]:=

Out[13]= 883, 5<, 84, 6<, 85, 7<<

In this table, the length of the rows depends on the more slowly varying iterator variable, i.Table@i + 2 j, 8i, 3<, 8j, i<D

In[14]:=

Out[14]= 883<, 84, 6<, 85, 7, 9<<

You can use Table to generate arrays with any number of dimensions.This generates a three-dimensional 222 array. It is a list of lists of lists.Table@i j ^ 2 k ^ 3, 8i, 2<, 8j, 2<, 8k, 2<D

In[15]:=Out[15]=

8881, 8<, 84, 32<<, 882, 16<, 88, 64<<<

Table@ f ,8imax <D

give a list of imax values of f

Table@ f ,8i,imax <D

give a list of the values of f as i runs from 1 to imax

Table@ f ,8i,imin ,imax <D

give a list of values with i running from imin to imax

Table@ f ,8i,imin ,imax ,di<D

use steps of di

Table@ f ,8i,imin ,imax <,8 j, jmin , jmax <,D

generate a multidimensional table

Table@ f ,8i,8i1 ,i2 ,<E

give a list of the values of f as i successively takes the

values i1 , i2 ,

TableForm@listD

display a list in tabular form

Functions for generating tables.

You can use the operations discussed in "Manipulating Elements of Lists" to extract elements ofthe table.

Core Language

15

You can use the operations discussed in "Manipulating Elements of Lists" to extract elements ofthe table.This creates a table and gives it the name sq.In[16]:=

sq = Table@j ^ 2, 8j, 7<D

Out[16]= 81, 4, 9, 16, 25, 36, 49<

This gives the third part of the table.

In[17]:=

sq@@3DD

Out[17]= 9

This gives a list of the third through fifth parts.

In[18]:=

sq@@3 ;; 5DD

Out[18]= 89, 16, 25<

This creates a 22 table, and gives it the name m.

In[19]:=

m = Table@i - j, 8i, 2<, 8j, 2<D

Out[19]= 880, -1<, 81, 0<<

This extracts the first sublist from the list of lists that makes up the table.In[20]:=Out[20]=

m@@1DD80, -1<

This extracts the second element of that sublist.

In[21]:=

%@@2DD

Out[21]= -1

This does the two operations together.

In[22]:=Out[22]=

m@@1, 2DD-1

This displays m in a "tabular" form.

In[23]:=

TableForm@mD

Out[23]//TableForm=

0 -11 0

16

Core Language

t@@iDD or Part@t,iD

give the ith sublist in t (also input as tPiT)

t@@i;; jDD or Part@t,i;; jD

give a list of the parts i through j

t@@8i1 ,i2 ,<DD or

Part@t,8i1 ,i2 ,<D

give a list of the i1 th , i2 th , parts of t

t@@i, j,DD or Part@t,i, j,D

give the part of t corresponding to t@@iDD@@ jDD Ways to extract parts of tables.

As mentioned in "Manipulating Elements of Lists", you can think of lists in Mathematica as beinganalogous to "arrays". Lists of lists are then like two-dimensional arrays. When you lay themout in a tabular form, the two indices of each element are like its x and y coordinates.

Manipulating Elements of Lists

Many of the most powerful list manipulation operations in Mathematica treat whole lists assingle objects. Sometimes, however, you need to pick out or set individual elements in a list.You can refer to an element of a Mathematica list by giving its "index". The elements are numbered in order, starting at 1.

8a,b,c<

a list

Part@list,iD or list@@iDD

the ith element of list (the first element is list@@1DD)

Part@list,8i, j,<Dor list@@8i, j,<DD

a list of the ith , jth , elements of list

Part@list,i;; jD

a list of the ith through jth elements of list

Operations on list elements.

This extracts the second element of the list.In[1]:=Out[1]=

85, 8, 6, 9<@@2DD8

This extracts a list of elements.

In[2]:=Out[2]=

85, 8, 6, 9<@@83, 1, 3, 2, 4<DD

86, 5, 6, 8, 9<

Core Language

17

This assigns the value of v to be a list.

v = 82, 4, 7<

In[3]:=Out[3]=

82, 4, 7<

You can extract elements of v.

v@@2DD

In[4]:=Out[4]=

By assigning a variable to be a list, you can use Mathematica lists much like "arrays" in othercomputer languages. Thus, for example, you can reset an element of a list by assigning a valueto v@@iDD.

Part@v,iD or v@@iDD

extract the ith element of a list

Part@v,iD=value or v@@iDD=value

reset the ith element of a list

Array-like operations on lists.

Here is a list.In[5]:=Out[5]=

v = 84, - 1, 8, 7<84, -1, 8, 7<

This resets the third element of the list.

In[6]:=Out[6]=

v@@3DD = 00

Now the list assigned to v has been modified.

In[7]:=

Out[7]= 84, -1, 0, 7<

Vectors and Matrices

Vectors and matrices in Mathematica are simply represented by lists and by lists of lists, respectively.

18

Core Language

8a,b,c<

vector Ha, b, cL

88a,b<,8c,d<<

matrix

a bc d

The representation of vectors and matrices by lists.

This is a 22 matrix.In[1]:=

m = 88a, b<, 8c, d<<

Out[1]= 88a, b<, 8c, d<<

Here is the first row.

In[2]:=

m@@1DD

Out[2]= 8a, b<

Here is the element m12 .

In[3]:=

m@@1, 2DD

Out[3]= b

This is a two-component vector.

In[4]:=

v = 8x, y<

Out[4]= 8x, y<

The objects p and q are treated as scalars.

In[5]:=

pv+q

Out[5]= 8q + p x, q + p y<

Vectors are added component by component.

In[6]:=

v + 8xp, yp< + 8xpp, ypp<

Out[6]= 8x + xp + xpp, y + yp + ypp<

This gives the dot (scalar) product of two vectors.

In[7]:=

8x, y<.8xp, yp<

Out[7]= x xp + y yp

Core Language

19

You can also multiply a matrix by a vector.

In[8]:=

m.v

Out[8]= 8a x + b y, c x + d y<

Or a matrix by a matrix.In[9]:=

m.m

22Out[9]= 99a + b c, a b + b d=, 9a c + c d, b c + d ==

Or a vector by a matrix.In[10]:=

v.m

Out[10]= 8a x + c y, b x + d y<

This combination makes a scalar.

In[11]:=

v.m.v

Out[11]= x Ha x + c yL + y Hb x + d yL

Because of the way Mathematica uses lists to represent vectors and matrices, you never haveto distinguish between "row" and "column" vectors.

Table@ f ,8i,n<D

build a length-n vector by evaluating f with i = 1, 2, , n

Array@a,nD

build a length-n vector of the form 8a@1D, a@2D, <

Range@nD

create the list 81, 2, 3, , n<

Range@n1 ,n2 D

create the list 8n1 , n1 + 1, , n2 <

Range@n1 ,n2 ,dnD

create the list 8n1 , n1 + dn, , n2 <

list@@iDD or Part@list,iD

give the ith element in the vector list

Length@listD

give the number of elements in list

c v

multiply a vector by a scalar

a.b

dot product of two vectors

Cross@a,bD

cross product of two vectors (also input as a b)

Norm@vD

Euclidean norm of a vector

Functions for vectors.

20

Core Language

Table@ f ,8i,m<,8 j,n<D

build an mn matrix by evaluating f with i ranging from 1

to m and j ranging from 1 to n

Array@a,8m,n<D

build an mn matrix with i, jth element a@i, jD

IdentityMatrix@nD

generate an nn identity matrix

DiagonalMatrix@listD

generate a square matrix with the elements in list on the

main diagonal

list@@iDD or Part@list,iD

give the ith row in the matrix list

listAAAll, jEE or PartAlist,All, jE

give the jth column in the matrix list

list@@i, jDD or Part@list,i, jD

give the i, jth element in the matrix list

Dimensions@listD

give the dimensions of a matrix represented by list

Functions for matrices.

Column@listD

display the elements of list in a column

MatrixForm@listD

display list in matrix form

Formatting constructs for vectors and matrices.

This builds a 33 matrix s with elements si j = i + j.In[12]:=

s = Table@i + j, 8i, 3<, 8j, 3<D

Out[12]= 882, 3, 4<, 83, 4, 5<, 84, 5, 6<<

This displays s in standard two-dimensional matrix format.

In[13]:=

MatrixForm@sD

Out[13]//MatrixForm=

2 3 43 4 54 5 6

This gives a vector with symbolic elements. You can use this in deriving general formulas thatare valid with any choice of vector components.In[14]:=

Array@a, 4D

Out[14]= 8a@1D, a@2D, a@3D, a@4D<

This gives a 32 matrix with symbolic elements. "Building Lists from Functions" discusses howyou can produce other kinds of elements with Array .In[15]:=

Array@p, 83, 2<D

Out[15]= 88p@1, 1D, p@1, 2D<, 8p@2, 1D, p@2, 2D<, 8p@3, 1D, p@3, 2D<<

Here are the dimensions of the matrix on the previous line.

Core Language

Here are the dimensions of the matrix on the previous line.

In[16]:=

Dimensions@%D

Out[16]= 83, 2<

This generates a 33 diagonal matrix.

In[17]:=

DiagonalMatrix@8a, b, c<D

Out[17]= 88a, 0, 0<, 80, b, 0<, 80, 0, c<<

c m

multiply a matrix by a scalar

a.b

dot product of two matrices

Inverse@mD

matrix inverse

MatrixPower @m,nD

nth power of a matrix

Det@mD

determinant

Tr@mD

trace

Transpose@mD

transpose

Eigenvalues @mD

eigenvalues

Eigenvectors@mD

eigenvectors

Some mathematical operations on matrices.

Here is the 22 matrix of symbolic variables that was defined.In[18]:=

Out[18]= 88a, b<, 8c, d<<

This gives its determinant.

In[19]:=

Det@mD

Out[19]= -b c + a d

Here is the transpose of m.

In[20]:=

Transpose@mD

Out[20]= 88a, c<, 8b, d<<

This gives the inverse of m in symbolic form.

In[21]:=

Inverse@mD

Out[21]= ::

d-b c + a d

, -

b-b c + a d

>, :-

c-b c + a d

Here is a 33 rational matrix.

a-b c + a d

>>

21

22

Core Language

Here is a 33 rational matrix.

In[22]:=

h = Table@1 Hi + j - 1L, 8i, 3<, 8j, 3<D

1

Out[22]= ::1,

1 1 11 1 1>, : , , >, : , , >>32 3 43 4 5

This gives its inverse.

In[23]:=

Inverse@hD

Out[23]= 889, -36, 30<, 8-36, 192, -180<, 830, -180, 180<<

Taking the dot product of the inverse with the original matrix gives the identity matrix.In[24]:=

%.h

Out[24]= 881, 0, 0<, 80, 1, 0<, 80, 0, 1<<

Here is a 33 matrix.In[25]:=

r = Table@i + j + 1, 8i, 3<, 8j, 3<D

Out[25]= 883, 4, 5<, 84, 5, 6<, 85, 6, 7<<

Eigenvalues gives the eigenvalues of the matrix.

In[26]:=

Eigenvalues@rD

Out[26]= :

15 +

249

15 -

249

, 0>

This gives a numerical approximation to the matrix.

In[27]:=

rn = N@rD

Out[27]= 883., 4., 5.<, 84., 5., 6.<, 85., 6., 7.<<

Here are numerical approximations to the eigenvalues.

In[28]:=

Eigenvalues@rnD

-16Out[28]= 915.3899, -0.389867, -1.49955 10 =

"Linear Algebra in Mathematica" discusses many other matrix operations that are built intoMathematica.

Core Language

Getting Pieces of Lists

First@listD

the first element in list

Last@listD

the last element

Part@list,nD or list@@nDD

the nth element

Part@list,-nD or list@@-nDD

the nth element from the end

Part@list,m;;nD

elements m through n

Part@list,8n1 ,n2 ,<D or list@@8n1 ,n2 ,<DD

the list of elements at positions n1 , n2 , Picking out elements of lists.We will use this list for the examples.In[1]:=

t = 8a, b, c, d, e, f, g<

Out[1]= 8a, b, c, d, e, f, g<

Here is the last element of t.

In[2]:=Out[2]=

Last@tDg

This gives the third element.

In[3]:=

t@@3DD

Out[3]= c

This gives the list of elements 3 through 6.

In[4]:=

t@@3 ;; 6DD

Out[4]= 8c, d, e, f<

This gives a list of the first and fourth elements.

In[5]:=Out[5]=

t@@81, 4<DD8a, d<

23

24

Core Language

Take@list,nD

the first n elements in list

Take@list,-nD

the last n elements

Take@list,8m,n<D

elements m through n (inclusive)

Rest@listD

list with its first element dropped

Drop@list,nD

list with its first n elements dropped

Most@listD

list with its last element dropped

Drop@list,-nD

list with its last n elements dropped

Drop@list,8m,n<D

list with elements m through n dropped

Picking out sequences in lists.

This gives the first three elements of the list t defined above.In[6]:=Out[6]=

Take@t, 3D8a, b, c<

This gives the last three elements.

In[7]:=

Take@t, - 3D

Out[7]= 8e, f, g<

This gives elements 2 through 5 inclusive.

In[8]:=Out[8]=

Take@t, 82, 5<D

8b, c, d, e<

This gives elements 3 through 7 in steps of 2.

In[9]:=Out[9]=

Take@t, 83, 7, 2<D

8c, e, g<

This gives t with the first element dropped.

In[10]:=

Rest@tD

Out[10]= 8b, c, d, e, f, g<

This gives t with its first three elements dropped.

In[11]:=Out[11]=

Drop@t, 3D8d, e, f, g<

Core Language

25

This gives t with only its third element dropped.

In[12]:=Out[12]=

Drop@t, 83, 3<D

8a, b, d, e, f, g<

"Manipulating Expressions like Lists" shows how all the functions here can be generalized towork not only on lists, but on any Mathematica expressions.The functions here allow you to pick out pieces that occur at particular positions in lists."Finding Expressions That Match a Pattern" shows how you can use functions like Select andCases to pick out elements of lists based not on their positions, but instead on their properties.

Testing and Searching List Elements

Position@list, formD

the positions at which form occurs in list

Count@list, formD

the number of times form appears as an element of list

MemberQ@list, formD

test whether form is an element of list

FreeQ@list, formD

test whether form occurs nowhere in list

Testing and searching for elements of lists.

"Getting Pieces of Lists" discusses how to extract pieces of lists based on their positions orindices. Mathematica also has functions that search and test for elements of lists, based on thevalues of those elements.This gives a list of the positions at which a appears in the list.In[1]:=Out[1]=

Position@8a, b, c, a, b<, aD881<, 84<<

Count counts the number of occurrences of a.

In[2]:=Out[2]=

Count@8a, b, c, a, b<, aD2

This shows that a is an element of 8a, b, c<.

In[3]:=Out[3]=

MemberQ@8a, b, c<, aDTrue

26

Core Language

On the other hand, d is not.

In[4]:=Out[4]=

MemberQ@8a, b, c<, dDFalse

This assigns m to be the 33 identity matrix.

In[5]:=Out[5]=

m = IdentityMatrix@3D881, 0, 0<, 80, 1, 0<, 80, 0, 1<<

This shows that 0 does occur somewhere in m.

In[6]:=Out[6]=

FreeQ@m, 0DFalse

This gives a list of the positions at which 0 occurs in m.

In[7]:=Out[7]=

Position@m, 0D881, 2<, 81, 3<, 82, 1<, 82, 3<, 83, 1<, 83, 2<<

As discussed in "Finding Expressions That Match a Pattern", the functions Count and Position,as well as MemberQ and FreeQ, can be used not only to search for particular list elements, butalso to search for classes of elements which match specific patterns.

Adding, Removing and Modifying List Elements

Prepend@list,elementD

add element at the beginning of list

Append@list,elementD

add element at the end of list

Insert@list,element,iD

insert element at position i in list

Insert@list,element,-iD

insert at position i counting from the end of list

Riffle@list,elementD

interleave element between the entries of list

Delete@list,iD

delete the element at position i in list

ReplacePart @list,i->newD

replace the element at position i in list with new

ReplacePart @list,8i, j<->newD

replace list@@i, jDD with new

Functions for manipulating elements in explicit lists.

Core Language

27

This gives a list with x prepended.

In[1]:=Out[1]=

Prepend@8a, b, c<, xD8x, a, b, c<

This inserts x so that it becomes element number 2.

In[2]:=Out[2]=

Insert@8a, b, c<, x, 2D8a, x, b, c<

This interleaves x between the entries of the list.

In[3]:=

Riffle@8a, b, c<, xD

Out[3]= 8a, x, b, x, c<

This replaces the third element in the list with x.

In[4]:=Out[4]=

ReplacePart@8a, b, c, d<, 3 -> xD

8a, b, x, d<

This replaces the 1, 2 element in a 22 matrix.

In[5]:=

ReplacePart@88a, b<, 8c, d<<, 81, 2< -> xD

Out[5]= 88a, x<, 8c, d<<

Functions like ReplacePart take explicit lists and give you new lists. Sometimes, however, youmay want to modify a list in place, without explicitly generating a new list.

v=8e1 ,e2 ,<

assign a variable to be a list

v@@iDD=new

assign a new value to the ith element

Resetting list elements.

This defines v to be a list.In[6]:=Out[6]=

v = 8a, b, c, d<8a, b, c, d<

This sets the third element to be x.

In[7]:=

v@@3DD = x

Out[7]= x

Now v has been changed.

28

Core Language

Now v has been changed.

In[8]:=Out[8]=

v8a, b, x, d<

m@@i, jDD=new

replace the Hi, jLth element of a matrix

m@@iDD=new

replace the ith row

mAAAll,iEE=new

replace the ith column

Resetting pieces of matrices.

This defines m to be a matrix.In[9]:=

m = 88a, b<, 8c, d<<

Out[9]= 88a, b<, 8c, d<<

This sets the first column of the matrix.

In[10]:=Out[10]=

m@@All, 1DD = 8x, y<; m

88x, b<, 8y, d<<

This sets every element in the first column to be 0.

In[11]:=Out[11]=

m@@All, 1DD = 0; m880, b<, 80, d<<

Combining ListsJoin@list1 ,list2 ,D

concatenate lists together

Union@list1 ,list2 ,D

combine lists, removing repeated elements and sorting the

result

Riffle@list1 ,list2 D

interleave elements of list1 and list2

Functions for combining lists.

Join concatenates any number of lists together.

In[1]:=Out[1]=

Join@8a, b, c<, 8x, y<, 8t, u<D

8a, b, c, x, y, t, u<

Union combines lists, keeping only distinct elements.

Core Language

29

Union combines lists, keeping only distinct elements.

In[2]:=Out[2]=

Union@8a, b, c<, 8c, a, d<, 8a, d<D

8a, b, c, d<

Riffle combines lists by interleaving their elements.

In[3]:=

Riffle@8a, b, c<, 8x, y, z<D

Out[3]= 8a, x, b, y, c, z<

Lists as SetsMathematica usually keeps the elements of a list in exactly the order you originally enteredthem. If you want to treat a Mathematica list like a mathematical set, however, you may wantto ignore the order of elements in the list.

Union@list1 ,list2 ,D

give a list of the distinct elements in the listi

Intersection@list1 ,list2 ,D

give a list of the elements that are common to all the listi

Complement@universal,list1 ,D

give a list of the elements that are in universal, but not in

any of the listi

Subsets@listD

give a list of all subsets of the elements in list

DeleteDuplicates@listD

delete all duplicates from list

Set theoretical functions.

Union gives the elements that occur in any of the lists.

In[1]:=

Union@8c, a, b<, 8d, a, c<, 8a, e<D

Out[1]= 8a, b, c, d, e<

Intersection gives only elements that occur in all the lists.

In[2]:=

Intersection@8a, c, b<, 8b, a, d, a<D

Out[2]= 8a, b<

Complement gives elements that occur in the first list, but not in any of the others.In[3]:=

Complement@8a, b, c, d<, 8a, d<D

Out[3]= 8b, c<

This gives all the subsets of the list.

30

Core Language

This gives all the subsets of the list.

In[4]:=

Subsets@8a, b, c<D

Out[4]= 88<, 8a<, 8b<, 8c<, 8a, b<, 8a, c<, 8b, c<, 8a, b, c<<

DeleteDuplicates deletes all duplicate elements from the list.

In[5]:=

DeleteDuplicates@8a, b, c, a<D

Out[5]= 8a, b, c<

Rearranging ListsSort@listD

sort the elements of list into a standard order

Union@listD

sort elements, removing any duplicates

Reverse@listD

reverse the order of elements in list

RotateLeft@list,nD

rotate the elements of list n places to the left

RotateRight @list,nD

rotate n places to the right

Functions for rearranging lists.

This sorts the elements of a list into a standard order. In simple cases like this, the order isalphabetical or numerical.In[1]:=Out[1]=

Sort@8b, a, c, a, b<D8a, a, b, b, c<

This sorts the elements, removing any duplicates.

In[2]:=Out[2]=

Union@8b, a, c, a, b<D8a, b, c<

This rotates (shifts) the elements in the list two places to the left.In[3]:=Out[3]=

RotateLeft@8a, b, c, d, e<, 2D8c, d, e, a, b<

You can rotate to the right by giving a negative displacement, or by using RotateRight .In[4]:=Out[4]=

RotateLeft@8a, b, c, d, e<, - 2D8d, e, a, b, c<

Core Language

PadLeft@list,len,xD

pad list on the left with x to make it length len

PadRight@list,len,xD

pad list on the right

Padding lists.This pads a list with xs to make it length 10.In[5]:=Out[5]=

PadLeft@8a, b, c<, 10, xD

8x, x, x, x, x, x, x, a, b, c<

Grouping and Combining Elements of Lists

Partition@list,nD

partition list into n-element pieces

Partition@list,n,dD

use offset d for successive pieces

Split@listD

split list into pieces consisting of runs of identical elements

Functions for grouping together elements of lists.

Here is a list.In[1]:=Out[1]=

t = 8a, b, c, d, e, f, g<8a, b, c, d, e, f, g<

This groups the elements of the list in pairs, throwing away the single element left at the end.In[2]:=Out[2]=

Partition@t, 2D88a, b<, 8c, d<, 8e, f<<

This groups elements in triples. There is no overlap between the triples.

In[3]:=Out[3]=

Partition@t, 3D88a, b, c<, 8d, e, f<<

This makes triples of elements, with each successive triple offset by just one element.In[4]:=Out[4]=

generate all possible n-tuples of elements from list

Tuples@8list1 ,list2 ,<D

generate all tuples whose ith element is from listi

Finding possible tuples of elements in lists.

This gives all possible ways of picking two elements out of the list.In[6]:=Out[6]=

Tuples@8a, b<, 2D88a, a<, 8a, b<, 8b, a<, 8b, b<<

This gives all possible ways of picking one element from each list.In[7]:=Out[7]=

Tuples@88a, b<, 81, 2, 3<<D

88a, 1<, 8a, 2<, 8a, 3<, 8b, 1<, 8b, 2<, 8b, 3<<

Ordering in ListsSort@listD

sort the elements of list into order

Ordering@listD

the positions in list of the elements in Sort@listD

Ordering@list,nD

the first n elements of Ordering@listD

Ordering@list,-nD

the last n elements of Ordering@listD

Permutations@listD

all possible orderings of list

Min@listD

the smallest element in list

Max@listD

the largest element in list

Ordering in lists.Here is a list of numbers.In[1]:=

t = 817, 21, 14, 9, 18<

Out[1]= 817, 21, 14, 9, 18<

Core Language

33

This gives the elements of t in sorted order.

In[2]:=

Sort@tD

Out[2]= 89, 14, 17, 18, 21<

This gives the positions of the elements of t, from the position of the smallest to that of thelargest.In[3]:=

Ordering@tD

Out[3]= 84, 3, 1, 5, 2<

This is the same as Sort@tD.

In[4]:=

t@@%DD

Out[4]= 89, 14, 17, 18, 21<

This gives the smallest element in the list.

In[5]:=Out[5]=

Min@tD9

Rearranging Nested Lists

You will encounter nested lists if you use matrices or generate multidimensional arrays andtables. Mathematica provides many functions for handling such lists.

Flatten@listD

flatten out all levels in list

Flatten@list,nD

flatten out the top n levels in list

Partition@list,8n1 ,n2 ,<D

partition into blocks of size n1 n2

Transpose@listD

interchange the top two levels of lists

RotateLeft@list,8n1 ,n2 ,<D

rotate successive levels by ni places

PadLeft@list,8n1 ,n2 ,<D

pad successive levels to be length ni

A few functions for rearranging nested lists.

This flattens out sublists. You can think of it as effectively just removing all inner braces.In[1]:=Out[1]=

Flatten@88a<, 8b, 8c<<, 8d<<D

8a, b, c, d<

34

Core Language

This flattens out only one level of sublists.

In[2]:=Out[2]=

Flatten@88a<, 8b, 8c<<, 8d<<, 1D

8a, b, 8c<, d<

There are many other operations you can perform on nested lists. More operations are discussed in "Manipulating Lists".

Core Language

Manipulating ListsConstructing ListsLists are widely used in Mathematica, and there are many ways to construct them.

Range@nD

the list 81, 2, 3, , n<

Table@expr,8i,n<D

the values of expr with i from 1 to n

Array@ f ,nD

the list 8 f @1D, f @2D, , f @nD<

NestList@ f ,x,nD

8x, f @xD, f @ f @xDD, < with up to n nestings

NormalASparseArray @8i1 ->v1 ,<,nDE

a length n list with element ik being vk

Apply@List, f @e1 ,e2 ,DD

the list 8e1 , e2 , <

Some explicit ways to construct lists.

This gives a table of the first five powers of two.In[1]:=Out[1]=

Table@2 ^ i, 8i, 5<D

82, 4, 8, 16, 32<

Here is another way to get the same result.

In[2]:=

Array@2 ^ &, 5D

Out[2]= 82, 4, 8, 16, 32<

This gives a similar list.

In[3]:=Out[3]=

NestList@2 &, 1, 5D81, 2, 4, 8, 16, 32<

SparseArray lets you specify values at particular positions.

In[4]:=Out[4]=

Normal@SparseArray@83 -> x, 4 -> y<, 5DD

80, 0, x, y, 0<

35

36

Core Language

You can also use patterns to specify values.

In[5]:=Out[5]=

Normal@SparseArray@8i_ -> 2 ^ i<, 5DD

82, 4, 8, 16, 32<

Often you will know in advance how long a list is supposed to be, and how each of its elementsshould be generated. And often you may get one list from another.

Table@expr,8i,list<D

the values of expr with i taking on values from list

Map@ f ,listD

apply f to each element of list

MapIndexed@ f ,listD

give f @elem, 8i<D for the ith element

Cases@list, formD

give elements of list that match form

Select@list,testD

select elements for which test@elemD is True

Pick@list,sel, formD

pick out elements of list for which the corresponding

elements of sel match form

TakeWhile@list,testD

give elements ei from the beginning of list as long as test@ei D

is True

list@@8i1 ,i2 ,<DD or Part@list,8i1 ,i2 ,<D

give a list of the specified parts of listConstructing lists from other lists.This selects elements less than 5.In[6]:=

Select@81, 3, 7, 4, 10, 2<, < 5 &D

Out[6]= 81, 3, 4, 2<

This takes elements up to the first element that is not less than 5.In[7]:=

TakeWhile@81, 3, 7, 4, 10, 2<, < 5 &D

Out[7]= 81, 3<

This explicitly gives numbered parts.

In[8]:=Out[8]=

8a, b, c, d<@@82, 1, 4<DD

8b, a, d<

This picks out elements indicated by a 1 in the second list.

In[9]:=Out[9]=

Pick@8a, b, c, d<, 81, 0, 1, 1<, 1D

8a, c, d<

Sometimes you may want to accumulate a list of results during the execution of a program. Youcan do this using Sow and Reap.

Core Language

37

Sometimes you may want to accumulate a list of results during the execution of a program. Youcan do this using Sow and Reap.

Sow@valD

sow the value val for the nearest enclosing Reap

Reap@exprD

evaluate expr, returning also a list of values sown by Sow

Using Sow and Reap .

This program iteratively squares a number.In[10]:=Out[10]=

Nest@ ^ 2 &, 2, 6D18 446 744 073 709 551 616

This does the same computation, but accumulating a list of intermediate results above 1000.In[11]:=Out[11]=

Reap@Nest@HIf@ > 1000, Sow@DD; ^ 2L &, 2, 6DD

818 446 744 073 709 551 616, 8865 536, 4 294 967 296<<<

An alternative but less efficient approach involves introducing a temporary variable, then starting with t = 8<, and successively using AppendTo@t, elemD.

Manipulating Lists by Their Indices

Part@list,specD or

list@@specDD

part or parts of a list

Part@list,spec1 ,spec2 ,Dor list@@spec1 ,spec2 ,DD

part or parts of a nested list

the nth part from the beginning

-n

the nth part from the end

8i1 ,i2 ,<

a list of parts

m;;n

parts m through n

All

all parts

Getting parts of lists.

This gives a list of parts 1 and 3.In[1]:=

8a, b, c, d<@@81, 3<DD

Out[1]= 8a, c<

38

Core Language

Here is a nested list.

In[2]:=

m = 88a, b, c<, 8d, e<, 8f, g, h<<;

This gives a list of its first and third parts.

In[3]:=Out[3]=

m@@81, 3<DD88a, b, c<, 8f, g, h<<

This gives a list of the first part of each of these.

In[4]:=Out[4]=

m@@81, 3<, 1DD

8a, f<

And this gives a list of the first two parts.

In[5]:=Out[5]=

m@@81, 3<, 81, 2<DD

88a, b<, 8f, g<<

This gives the first two parts of m.

In[6]:=

m@@1 ;; 2DD

Out[6]= 88a, b, c<, 8d, e<<

This gives the last part of each of these.

In[7]:=

m@@1 ;; 2, - 1DD

Out[7]= 8c, e<

This gives the second part of all sublists.

In[8]:=Out[8]=

m@@All, 2DD8b, e, g<

This gives the last two parts of all sublists.

In[9]:=

m@@All, - 2 ;; - 1DD

Out[9]= 88b, c<, 8d, e<, 8g, h<<

You can always reset one or more pieces of a list by doing an assignment like m@@DD = value.

Core Language

39

This resets part 1,2 of m.

In[10]:=Out[10]=

m@@1, 2DD = xx

This is now the form of m.

In[11]:=Out[11]=

m88a, x, c<, 8d, e<, 8f, g, h<<

This resets part 1 to x and part 3 to y.

In[12]:=Out[12]=

m@@81, 3<DD = 8x, y<; m

8x, 8d, e<, y<

This resets parts 1 and 3 both to p.

In[13]:=Out[13]=

m@@81, 3<DD = p; m8p, 8d, e<, p<

This restores the original form of m.

In[14]:=

m = 88a, b, c<, 8d, e<, 8f, g, h<<;

This now resets all parts specified by m@@81, 3<, 81, 2<DD.

In[15]:=Out[15]=

m@@81, 3<, 81, 2<DD = x; m

88x, x, c<, 8d, e<, 8x, x, h<<

You can use ;; to indicate all indices in a given range.

In[16]:=

m@@1 ;; 3, 2DD = y; m

Out[16]= 88x, y, c<, 8d, y<, 8x, y, h<<

It is sometimes useful to think of a nested list as being laid out in space, with each elementbeing at a coordinate position given by its indices. There is then a direct geometrical interpretation for list@@spec1 , spec2 , DD. If a given speck is a single integer, then it represents extracting asingle slice in the kth dimension, while if it is a list, it represents extracting a list of parallelslices. The final result for list@@spec1 , spec2 , DD is then the collection of elements obtained byslicing in each successive dimension.

40

Core Language

Here is a nested list laid out as a two-dimensional array.

In[17]:=

Hm = 88a, b, c<, 8d, e, f<, 8g, h, i<<L TableForm

Out[17]//TableForm=

a b cd e fg h i

This picks out rows 1 and 3, then columns 1 and 2.

In[18]:=

m@@81, 3<, 81, 2<DD TableForm

Out[18]//TableForm=

a bg h

Part is set up to make it easy to pick out structured slices of nested lists. Sometimes, however,you may want to pick out arbitrary collections of individual parts. You can do this convenientlywith Extract.

Part@list,8i1 ,i2 ,<D

the list 8list@@i1 DD, list@@i2 DD, <

Extract@list,8i1 ,i2 ,<D

the element list@@i1 , i2 , DD

Part@list,spec1 ,spec2 ,D

parts specified by successive slicing

Extract@list,88i1 ,i2 ,<,8 j1 , j2 ,<,<D

the list of individual parts

8list@@i1 , i2 , DD, list@@ j1 , j2 , DD, <

Getting slices versus lists of individual parts.

This extracts the individual parts 1,3 and 1,2.In[19]:=Out[19]=

Extract@m, 881, 3<, 81, 2<<D

8c, b<

An important feature of Extract is that it takes lists of part positions in the same form as theyare returned by functions like Position.This sets up a nested list.In[20]:=

m = 88a@1D, a@2D, b@1D<, 8b@2D, c@1D<, 88b@3D<<<;

This gives a list of positions in m.

In[21]:=Out[21]=

Position@m, b@_DD881, 3<, 82, 1<, 83, 1, 1<<

Core Language

41

This extracts the elements at those positions.

Extract@m, %D

In[22]:=Out[22]=

8b@1D, b@2D, b@3D<

Take@list,specD

take the specified parts of a list

Drop@list,specD

drop the specified parts of a list

Take@list,spec1 ,spec2 ,D, Drop@list,spec1 ,spec2 ,D

take or drop specified parts at each level in nested lists

the first n elements

-n

the last n elements

8n<

element n only

8m,n<

elements m through n (inclusive)

8m,n,s<

elements m through n in steps of s

All

all parts

None

no parts

Taking and dropping sequences of elements in lists.

This takes every second element starting at position 2.In[23]:=

Take@8a, b, c, d, e, f, g<, 82, - 1, 2<D

Out[23]= 8b, d, f<

This drops every second element.

In[24]:=Out[24]=

Drop@8a, b, c, d, e, f, g<, 82, - 1, 2<D

8a, c, e, g<

Much like Part, Take and Drop can be viewed as picking out sequences of slices at successivelevels in a nested list. You can use Take and Drop to work with blocks of elements in arrays.Here is a 33 array.In[25]:=

Hm = 88a, b, c<, 8d, e, f<, 8g, h, i<<L TableForm

Out[25]//TableForm=

a b cd e fg h i

42

Core Language

Here is the first 22 subarray.

In[26]:=

Take@m, 2, 2D TableForm

Out[26]//TableForm=

a bd e

This takes all elements in the first two columns.

In[27]:=

Take@m, All, 2D TableForm

Out[27]//TableForm=

a bd eg h

This leaves no elements from the first two columns.

In[28]:=

Drop@m, None, 2D TableForm

Out[28]//TableForm=

Prepend@list,elemD

add element at the beginning of list

Append@list,elemD

add element at the end of list

Insert@list,elem,iD

insert element at position i

Insert@list,elem,8i, j,<D

insert at position 8i, j, <

Delete@list,iD

delete the element at position i

Delete@list,8i, j,<D

delete at position 8i, j, <

Adding and deleting elements in lists.

This makes the 2,1 element of the list be x.In[29]:=Out[29]=

Insert@88a, b, c<, 8d, e<<, x, 82, 1<D

88a, b, c<, 8x, d, e<<

This deletes the element again.

In[30]:=

Delete@%, 82, 1<D

Out[30]= 88a, b, c<, 8d, e<<

Core Language

ReplacePart @list,i->newD

replace the element at position i in list with new

ReplacePart @list,8i, j,<->newD

replace list@@i, j, DD with new

ReplacePart @list,8i1 ->new1 ,i2 ->new2 ,<D

replaces parts at positions in by newn

ReplacePart @list,88i1 , j1 ,<->new1 ,<D

replace parts at positions 8in , jn , < by newn

ReplacePart @list,88i1 , j1 ,<,<->newD

replace all parts list@@ik , jk , DD with new

43

Replacing parts of lists.

This replaces the third element in the list with x.In[31]:=Out[31]=

ReplacePart@8a, b, c, d<, 3 -> xD

8a, b, x, d<

This replaces the first and fourth parts of the list. Notice the need for double lists in specifyingmultiple parts to replace.In[32]:=Out[32]=

ReplacePart@8a, b, c, d<, 881<, 84<< -> xD

8x, b, c, x<

Here is a 33 identity matrix.

In[33]:=Out[33]=

IdentityMatrix@3D881, 0, 0<, 80, 1, 0<, 80, 0, 1<<

This replaces the 2,2 component of the matrix by x.

In[34]:=

ReplacePart@%, 82, 2< -> xD

Out[34]= 881, 0, 0<, 80, x, 0<, 80, 0, 1<<

It is important to understand that ReplacePart always creates a new list. It does not modify alist that has already been assigned to a symbol, the way m@@DD = val does.This assigns a list of values to alist.In[35]:=

alist = 8a, b, c, d<

Out[35]= 8a, b, c, d<

44

Core Language

This gives a copy of the list in which the third element has been replaced with x.In[36]:=

ReplacePart@alist, 3 -> xD

Out[36]= 8a, b, x, d<

The value of alist has not changed.

In[37]:=

alist

Out[37]= 8a, b, c, d<

Nested Lists8list1 ,list2 ,<

list of lists

Table@expr,8i,m<,8 j,n<,D

mn table of values of expr

Array@ f ,8m,n,<D

mn array of values f @i, j, D

NormalASparseArray @88i1 , j1 ,<->v1 ,<,8m,n,<DE

mn array with element 8is , js , < being vsOuter@ f ,list1 ,list2 ,D

generalized outer product with elements combined using f

Tuples@list,8m,n,<D

all possible mn arrays of elements from list

Ways to construct nested lists.

This generates a table corresponding to a 23 nested list.In[1]:=Out[1]=

Table@x ^ i + j, 8i, 2<, 8j, 3<D

981 + x, 2 + x, 3 + x<, 91 + x2 , 2 + x2 , 3 + x2 ==

This generates an array corresponding to the same nested list.

In[2]:=Out[2]=

Array@x ^ 1 + 2 &, 82, 3<D

981 + x, 2 + x, 3 + x<, 91 + x2 , 2 + x2 , 3 + x2 ==

Elements not explicitly specified in the sparse array are taken to be 0.

In[3]:=Out[3]=

Normal@SparseArray@881, 3< -> 3 + x<, 82, 3<DD

880, 0, 3 + x<, 80, 0, 0<<

Core Language

45

Each element in the final list contains one element from each input list.In[4]:=Out[4]=

Outer@f, 8a, b<, 8c, d<D

88f@a, cD, f@a, dD<, 8f@b, cD, f@b, dD<<

Functions like Array, SparseArray and Outer always generate full arrays, in which all sublistsat a particular level are the same length.

Dimensions@listD

the dimensions of a full array

ArrayQ@listD

test whether all sublists at a given level are the same

length

ArrayDepth@listD

the depth to which all sublists are the same length

Functions for full arrays.

Mathematica can handle arbitrary nested lists. There is no need for the lists to form a full array.You can easily generate ragged arrays using Table.This generates a triangular array.In[5]:=Out[5]=

Table@x ^ i + j, 8i, 3<, 8j, i<D

981 + x<, 91 + x2 , 2 + x2 =, 91 + x3 , 2 + x3 , 3 + x3 ==

Flatten@listD

flatten out all levels of list

Flatten@list,nD

flatten out the top n levels

ArrayFlatten@list,rankD

create a flattened array from an array of arrays

Flattening out sublists and subarrays.

This generates a 23 array.In[6]:=

Array@a, 82, 3<D

Out[6]= 88a@1, 1D, a@1, 2D, a@1, 3D<, 8a@2, 1D, a@2, 2D, a@2, 3D<<

Flatten in effect puts elements in lexicographic order of their indices.

The offset can be larger than the block size.

This splits into runs of identical elements.

This splits into runs where adjacent elements are unequal.

In[5]:=Out[5]=

Split@81, 4, 1, 1, 1, 2, 2, 3, 3<, UnequalD

881, 4, 1<, 81<, 81, 2<, 82, 3<, 83<<

Partition in effect goes through a list, grouping successive elements into sublists. By default itdoes not include any sublists that would "overhang" the original list.This stops before any overhang occurs.In[6]:=Out[6]=

Partition@8a, b, c, d, e<, 2D88a, b<, 8c, d<<

The same is true here.

In[7]:=

Partition@8a, b, c, d, e<, 3, 1D

Out[7]= 88a, b, c<, 8b, c, d<, 8c, d, e<<

You can tell Partition to include sublists that overhang the ends of the original list. By default,it fills in additional elements by treating the original list as cyclic. It can also treat it as beingpadded with elements that you specify.This includes additional sublists, treating the original list as cyclic.In[8]:=Out[8]=

Partition@8a, b, c, d, e<, 3, 1, 81, 1<D

88a, b, c<, 8b, c, d<, 8c, d, e<, 8d, e, a<, 8e, a, b<<

Core Language

49

Now the original list is treated as being padded with the element x.In[9]:=Out[9]=

Partition@8a, b, c, d, e<, 3, 1, 81, 1<, xD

88a, b, c<, 8b, c, d<, 8c, d, e<, 8d, e, x<, 8e, x, x<<

This pads cyclically with elements x and y.

In[10]:=Out[10]=

Partition@8a, b, c, d, e<, 3, 1, 81, 1<, 8x, y<D

88a, b, c<, 8b, c, d<, 8c, d, e<, 8d, e, y<, 8e, y, x<<

This introduces no padding, yielding sublists of differing lengths.

In[11]:=Out[11]=

Partition@8a, b, c, d, e<, 3, 1, 81, 1<, 8<D

88a, b, c<, 8b, c, d<, 8c, d, e<, 8d, e<, 8e<<

You can think of Partition as extracting sublists by sliding a template along and picking outelements from the original list. You can tell Partition where to start and stop this process.This gives all sublists that overlap the original list.In[12]:=Out[12]=

Partition@8a, b, c, d<, 3, 1, 8- 1, 1<, xD

88x, x, a<, 8x, a, b<, 8a, b, c<, 8b, c, d<, 8c, d, x<, 8d, x, x<<

This allows overlaps only at the beginning.

In[13]:=Out[13]=

Partition@8a, b, c, d<, 3, 1, 8- 1, - 1<, xD

88x, x, a<, 8x, a, b<, 8a, b, c<, 8b, c, d<<

Partition@list,n,dD orPartition@list,n,d,81,-1<D

keep only sublists with no overhangs

Partition@list,n,d,81,1<D

allow an overhang at the end

Partition@list,n,d,8-1,-1<D

allow an overhang at the beginning

Partition@list,n,d,8-1,1<D

allow overhangs at both the beginning and end

Partition@list,n,d,8kL ,kR <D

specify alignments of first and last sublists

Partition@list,n,d,specD

pad by cyclically repeating elements in list

Partition@list,n,d,spec,xD

pad by repeating the element x

Partition@list,n,d,spec,8x1 ,x2 ,<D

pad by cyclically repeating the xi

Partition@list,n,d,spec,8<D

use no padding

Specifying alignment and padding.

An alignment specification 8kL , kR < tells Partition to give the sequence of sublists in which thefirst element of the original list appears at position kL in the first sublist, and the last element of

50

Core Language

An alignment specification 8kL , kR < tells Partition to give the sequence of sublists in which thefirst element of the original list appears at position kL in the first sublist, and the last element ofthe original list appears at position kR in the last sublist.This makes a appear at position 1 in the first sublist.In[14]:=Out[14]=

This fills in padding cyclically from the list given.

Partition@8a, b, c, d<, 3, 1, 84, 1<, 8x, y<D

Functions like ListConvolve use the same alignment and padding specifications as Partition.In some cases it may be convenient to insert explicit padding into a list. You can do this usingPadLeft and PadRight.

PadLeft@list,nD

pad to length n by inserting zeros on the left

PadLeft@list,n,xD

pad by repeating the element x

PadLeft@list,n,8x1 ,x2 ,<D

pad by cyclically repeating the xi

PadLeft@list,n,listD

pad by cyclically repeating list

PadLeft@list,n,padding,mD

leave a margin of m elements on the right

PadRight@list,nD

pad by inserting zeros on the right

Padding a list.This pads the list to make it length 6.In[18]:=Out[18]=

Here is a list containing only padding.

In[24]:=Out[24]=

PadLeft@88<<, 84, 4<, 88x, y<, 8z, w<<D

88x, y, x, y<, 8z, w, z, w<, 8x, y, x, y<, 8z, w, z, w<<

Sparse Arrays: Manipulating Lists

Lists are normally specified in Mathematica just by giving explicit lists of their elements. Butparticularly in working with large arrays, it is often useful instead to be able to say what thevalues of elements are only at certain positions, with all other elements taken to have a defaultvalue, usually zero. You can do this in Mathematica using SparseArray objects.

This shows the rules used in the sparse array.

Out[9]= 883< a, 85< b, 8_< x<

This creates a banded matrix.

SparseArray@8Band@81, 1<D x, Band@82, 1<D y<, 85, 5<D MatrixForm

An important feature of SparseArray is that the positions you specify can be patterns.This specifies a 44 sparse array with 1 at every position matching 8i_, i_<.In[11]:=Out[11]=

SparseArray@8i_, i_< -> 1, 84, 4<D

SparseArray@<4>, 84, 4<D

The result is a 44 identity matrix.

In[12]:=Out[12]=

Normal@%D881, 0, 0, 0<, 80, 1, 0, 0<, 80, 0, 1, 0<, 80, 0, 0, 1<<

Here is an identity matrix with an extra element.

53

54

Core Language

Here is an identity matrix with an extra element.

In[13]:=Out[13]=

Normal@SparseArray@881, 3< -> a, 8i_, i_< -> 1<, 84, 4<DD

881, 0, a, 0<, 80, 1, 0, 0<, 80, 0, 1, 0<, 80, 0, 0, 1<<

This makes the whole third column be a.

In[14]:=Out[14]=

Normal@SparseArray@88_, 3< -> a, 8i_, i_< -> 1<, 84, 4<DD

881, 0, a, 0<, 80, 1, a, 0<, 80, 0, a, 0<, 80, 0, a, 1<<

You can think of SparseArray @rulesD as taking all possible position specifications, then applyingrules to determine values in each case. As usual, rules given earlier in the list will be tried first.This generates a random diagonal matrix.In[15]:=

Normal@SparseArray@8Band@81, 1<D 82, 4, 6, 8, 10<,

For many purposes, Mathematica treats SparseArray objects just like the ordinary lists towhich they correspond. Thus, for example, if you ask for parts of a sparse array object, Mathematica will operate as if you had asked for parts in the corresponding ordinary list.This generates a sparse array object.In[22]:=Out[22]=

s = SparseArray@82 -> a, 4 -> b, 5 -> c<, 10D

SparseArray@<3>, 810<D

Here is the corresponding ordinary list.

In[23]:=Out[23]=

Normal@sD80, a, 0, b, c, 0, 0, 0, 0, 0<

Parts of the sparse array are just like parts of the corresponding ordinary list.In[24]:=Out[24]=

s@@2DDa

This part has the default value 0.

In[25]:=Out[25]=

s@@3DD0

Many operations treat SparseArray objects just like ordinary lists. When possible, they givesparse arrays as results.This gives a sparse array.In[26]:=Out[26]=

3s+xSparseArray@<3>, 810<, xD

Here is the corresponding ordinary list.

In[27]:=Out[27]=

Normal@%D8x, 3 a + x, x, 3 b + x, 3 c + x, x, x, x, x, x<

56

Core Language

Dot works directly with sparse array objects.

In[28]:=Out[28]=

s.sa2 + b2 + c2

You can mix sparse arrays and ordinary lists.

In[29]:=Out[29]=

s.Range@10D2a+4b+5c

Mathematica represents sparse arrays as expressions with head SparseArray . Whenever a

sparse array is evaluated, it is automatically converted to an optimized standard form withstructure SparseArray @Automatic, dims, val, D.This structure is, however, rarely evident, since even operations like Length are set up to giveresults for the corresponding ordinary list, not for the raw SparseArray expression structure.This generates a sparse array.In[30]:=Out[30]=

t = SparseArray@81 -> a, 5 -> b<, 10D

SparseArray@<2>, 810<D

Here is the underlying optimized expression structure.

In[31]:=

InputForm@%D

Out[31]//InputForm=

SparseArray[Automatic, {10}, 0,

{1, {{0, 2}, {{1}, {5}}}, {a, b}}]

Length gives the length of the corresponding ordinary list.

In[32]:=Out[32]=

Length@tD10

Map also operates on individual values.

ExpressionsEverything Is an ExpressionMathematica handles many different kinds of things: mathematical formulas, lists and graphics,to name a few. Although they often look very different, Mathematica represents all of thesethings in one uniform way. They are all expressions.A prototypical example of a Mathematica expression is f@x, yD. You might use f@x, yD torepresent a mathematical function f Hx, yL. The function is named f, and it has two arguments, xand y.You do not always have to write expressions in the form f @x, y, D. For example, x + y is alsoan expression. When you type in x + y, Mathematica converts it to the standard formPlus@x, yD. Then, when it prints it out again, it gives it as x + y.The same is true of other "operators", such as ^ (Power) and (Divide).In fact, everything you type into Mathematica is treated as an expression.

x+y+z

Plus@x,y,zD

xyz

Times@x,y,zD

x^n

Power@x,nD

8a,b,c<

List@a,b,cD

a->b

Rule@a,bD

a=b

Set@a,bD

Some examples of Mathematica expressions.

You can see the full form of any expression by using FullForm@exprD.Here is an expression.In[1]:=Out[1]=

x+y+zx+y+z

58

Core Language

This is the full form of the expression.

In[2]:=

FullForm@%D

Out[2]//FullForm=

Plus@x, y, zD

Here is another expression.

In[3]:=Out[3]=

1 + x ^ 2 + Hy + zL ^ 21 + x2 + Hy + zL2

Its full form has several nested pieces.

In[4]:=

FullForm@%D

Out[4]//FullForm=

Plus@1, Power@x, 2D, Power@Plus@y, zD, 2DD

The object f in an expression f @x, y, D is known as the head of the expression. You canextract it using Head@exprD. Particularly when you write programs in Mathematica, you will oftenwant to test the head of an expression to find out what kind of thing the expression is.Head gives the "function name" f.In[5]:=Out[5]=

Head@f@x, yDDf

Here Head gives the name of the "operator".

In[6]:=Out[6]=

Head@a + b + cDPlus

Everything has a head.

In[7]:=Out[7]=

Head@8a, b, c<DList

Numbers also have heads.

In[8]:=Out[8]=

Head@23 432DInteger

You can distinguish different kinds of numbers by their heads.

In[9]:=Out[9]=

Head@345.6DReal

Core Language

Head@exprD

give the head of an expression: the f in f @x, yD

FullForm@exprD

display an expression in the full form used by Mathematica

59

Functions for manipulating expressions.

The Meaning of Expressions

The notion of expressions is a crucial unifying principle in Mathematica. It is the fact that everyobject in Mathematica has the same underlying structure that makes it possible for Mathematica to cover so many areas with a comparatively small number of basic operations.Although all expressions have the same basic structure, there are many different ways thatexpressions can be used. Here are a few of the interpretations you can give to the parts of anexpression.meaning of f

meaning of

examples

x, y, FunctionCommandOperatorHeadObject type

arguments orparametersarguments orparametersoperandselementscontents

Sin@xD , f@x,yDExpand@Hx+1L^2Dx+y , a=b8a,b,c<RGBColor@r,g,bD

Some interpretations of parts of expressions.

Expressions in Mathematica are often used to specify operations. So, for example, typing in2 + 3 causes 2 and 3 to be added together, while Factor@x ^ 6 - 1D performs factorization.Perhaps an even more important use of expressions in Mathematica, however, is to maintain astructure, which can then be acted on by other functions. An expression like 8a, b, c< does notspecify an operation. It merely maintains a list structure, which contains a collection of threeelements. Other functions, such as Reverse or Dot, can act on this structure.The full form of the expression 8a, b, c< is List@a, b, cD. The head List performs no operations. Instead, its purpose is to serve as a tag to specify the type of the structure.You can use expressions in Mathematica to create your own structures. For example, you mightwant to represent points in three-dimensional space, specified by three coordinates. You couldgive each point as point@x, y, zD. The function point again performs no operation. It servesmerely to collect the three coordinates together, and to label the resulting object as a point.

60

Core Language

You can use expressions in Mathematica to create your own structures. For example, you mightwant to represent points in three-dimensional space, specified by three coordinates. You couldgive each point as point@x, y, zD. The function point again performs no operation. It servesmerely to collect the three coordinates together, and to label the resulting object as a point.You can think of expressions like point@x, y, zD as being packets of data, tagged with aparticular head. Even though all expressions have the same basic structure, you can distinguishdifferent types of expressions by giving them different heads. You can then set up transformation rules and programs which treat different types of expressions in different ways.

Special Ways to Input Expressions

Mathematica allows you to use special notation for many common operators. For example,although internally Mathematica represents a sum of two terms as Plus@x, yD, you can enterthis expression in the much more convenient form x + y.The Mathematica language has a definite grammar which specifies how your input should beconverted to internal form. One aspect of the grammar is that it specifies how pieces of yourinput should be grouped. For example, if you enter an expression such as a + b ^ c, the Mathematica grammar specifies that this should be considered, following standard mathematical notation,as a + Hb ^ cL rather than Ha + bL ^ c. Mathematica chooses this grouping because it treats theoperator ^ as having a higher precedence than +. In general, the arguments of operators withhigher precedence are grouped before those of operators with lower precedence.You should realize that absolutely every special input form in Mathematica is assigned a definiteprecedence. This includes not only the traditional mathematical operators, but also forms suchas ->, := or the semicolons used to separate expressions in a Mathematica program.The table in "Operator Input Forms" gives all the operators of Mathematica in order of decreasing precedence. The precedence is arranged, where possible, to follow standard mathematicalusage, and to minimize the number of parentheses that are usually needed.You will find, for example, that relational operators such as < have lower precedence thanarithmetic operators such as +. This means that you can write expressions such as x + y > 7without using parentheses.There are nevertheless many cases where you do have to use parentheses. For example, since; has a lower precedence than =, you need to use parentheses to write x = Ha; bL. Mathematicainterprets the expression x = a; b as Hx = aL; b. In general, it can never hurt to include extraparentheses, but it can cause a great deal of trouble if you leave parentheses out, and Mathe-

Core Language

61

There are nevertheless many cases where you do have to use parentheses. For example, since; has a lower precedence than =, you need to use parentheses to write x = Ha; bL. Mathematicainterprets the expression x = a; b as Hx = aL; b. In general, it can never hurt to include extraparentheses, but it can cause a great deal of trouble if you leave parentheses out, and Mathematica interprets your input in a way you do not expect.

f @x,yD

standard form for f @x, yD

f x

prefix form for f @xD

x f

postfix form for f @xD

x~ f ~y

infix form for f @x, yD

Four ways to write expressions in Mathematica.

There are several common types of operators in Mathematica. The + in x + y is an infix operator. The - in - p is a prefix operator. Even when you enter an expression such as f @x, y, DMathematica allows you to do it in ways that mimic infix, prefix and postfix forms.This postfix form is exactly equivalent to f@x + yD.In[1]:=Out[1]=

x + y ff@x + yD

You will often want to add functions like N as afterthoughts, and give them in postfix form.In[2]:=

3 ^ H1 4L + 1 N

Out[2]= 2.31607

It is sometimes easier to understand what a function is doing when you write it in infix form.In[3]:=Out[3]=

8a, b, c< ~ Join ~ 8d, e<

8a, b, c, d, e<

You should notice that has very low precedence. If you put f at the end of any expression containing arithmetic or logical operators, the f is applied to the whole expression. So, forexample, x + y f means f@x + yD, not x + f@yD.The prefix form has a much higher precedence. f x + y is equivalent to f@xD + y, not f@x + yD.You can write f@x + yD in prefix form as f Hx + yL.

62

Core Language

Parts of ExpressionsSince lists are just a particular kind of expression, it will come as no surprise that you can referto parts of any expression much as you refer to parts of a list.This gets the second element in the list 8a, b, c<.In[1]:=Out[1]=

8a, b, c<@@2DDb

You can use the same method to get the second element in the sum x + y + z.In[2]:=Out[2]=

Hx + y + zL@@2DDy

This gives the last element in the sum.

In[3]:=

Hx + y + zL@@- 1DD

Out[3]= z

Part 0 is the head.

In[4]:=Out[4]=

Hx + y + zL@@0DDPlus

You can refer to parts of an expression such as f @g@aD, g@bDD just as you refer to parts ofnested lists.This is part 1.In[5]:=Out[5]=

f@g@aD, g@bDD@@1DDg@aD

This is part 81, 1<.

In[6]:=Out[6]=

f@g@aD, g@bDD@@1, 1DD

a

This extracts part 82, 1< of the expression 1 + x ^ 2.

In[7]:=Out[7]=

H1 + x ^ 2L@@2, 1DDx

To see what part is 82, 1<, you can look at the full form of the expression.

Core Language

63

To see what part is 82, 1<, you can look at the full form of the expression.In[8]:=

FullForm@1 + x ^ 2D

Out[8]//FullForm=

Plus@1, Power@x, 2DD

You should realize that the assignment of indices to parts of expressions is done on the basis ofthe internal Mathematica forms of the expression, as shown by FullForm. These forms do notalways correspond directly with what you see printed out. This is particularly true for algebraicexpressions, where Mathematica uses a standard internal form, but prints the expressions inspecial ways.Here is the internal form of x y.In[9]:=

FullForm@x yD

Out[9]//FullForm=

Times@x, Power@y, -1DD

It is the internal form that is used in specifying parts.

In[10]:=Out[10]=

Hx yL@@2DD1y

You can manipulate parts of expressions just as you manipulate parts of lists.This replaces the third part of a + b + c + d by x ^ 2. Note that the sum is automatically rearranged when the replacement is done.In[11]:=

ReplacePart@a + b + c + d, 3 -> x ^ 2D

2Out[11]= a + b + d + x

Here is an expression.In[12]:=Out[12]=

t = 1 + H3 + xL ^ 2 y1+

H3 + xL2y

This is the full form of t.

In[13]:=

FullForm@tD

Out[13]//FullForm=

Plus@1, Times@Power@Plus@3, xD, 2D, Power@y, -1DDD

64

Core Language

This resets a part of the expression t.

In[14]:=Out[14]=

t@@2, 1, 1DD = xx

Now the form of t has been changed.

In[15]:=Out[15]=

t1+

x2y

Part@expr,nD or expr@@nDD

the nth part of expr

Part@expr,8n1 ,n2 ,<D or expr@@8n1 ,n2 ,<DD

a combination of parts of an expression

Part@expr,n1 ;;n2 D

parts n1 through n2 of an expression

ReplacePart @expr,n->elemD

replace the nth part of expr by elem

Functions for manipulating parts of expressions.

"Manipulating Elements of Lists" discusses how you can use lists of indices to pick out severalelements of a list at a time. You can use the same procedure to pick out several parts in anexpression at a time.This picks out elements 2 and 4 in the list, and gives a list of these elements.In[16]:=Out[16]=

8a, b, c, d, e<@@82, 4<DD

8b, d<

This picks out parts 2 and 4 of the sum, and gives a sum of these elements.In[17]:=Out[17]=

Ha + b + c + d + eL@@82, 4<DDb+d

Any part in an expression can be viewed as being an argument of some function. When youpick out several parts by giving a list of indices, the parts are combined using the same functionas in the expression.This picks out parts 2 through 4 of the list.In[18]:=

8a, b, c, d, e<@@2 ;; 4DD

Out[18]= 8b, c, d<

Manipulating Expressions like Lists

Core Language

65

Manipulating Expressions like Lists

You can use most of the list operations discussed in "Lists" on any kind of Mathematica expression. By using these operations, you can manipulate the structure of expressions in many ways.Here is an expression that corresponds to a sum of terms.In[1]:=Out[1]=

t = 1 + x + x^2 + y^21 + x + x2 + y2

Take@t, 2D takes the first two elements from t, just as if t were a list.In[2]:=Out[2]=

Take@t, 2D1+x

Length gives the number of elements in t.

In[3]:=

Length@tD

Out[3]= 4

You can use FreeQ@expr, formD to test whether form appears nowhere in expr.In[4]:=Out[4]=

FreeQ@t, xDFalse

This gives a list of the positions at which x appears in t.

In[5]:=Out[5]=

Position@t, xD882<, 83, 1<<

You should remember that all functions which manipulate the structure of expressions act onthe internal forms of these expressions. You can see these forms using FullForm@exprD. Theymay not be what you would expect from the printed versions of the expressions.Here is a function with four arguments.In[6]:=Out[6]=

f@a, b, c, dDf@a, b, c, dD

66

Core Language

You can add an argument using Append.

In[7]:=Out[7]=

Append@%, eDf@a, b, c, d, eD

This reverses the arguments.

In[8]:=Out[8]=

Reverse@%Df@e, d, c, b, aD

There are a few extra functions that can be used with expressions, as discussed in "StructuralOperations".

Expressions as TreesHere is an expression in full form.In[1]:=

FullForm@x ^ 3 + H1 + xL ^ 2D

Out[1]//FullForm= Plus@Power@x, 3D, Power@Plus@1, xD, 2DD

TreeForm prints out expressions to show their tree structure.

In[2]:=

TreeForm@x ^ 3 + H1 + xL ^ 2DPlus

Power

Power

Out[2]//TreeForm=

Plus

You can think of any Mathematica expression as a tree. In the expression above, the top nodein the tree consists of a Plus. From this node come two branches, x ^ 3 and H1 + xL ^ 2. Fromthe x ^ 3 node, there are then two branches, x and 3, which can be viewed as leaves of thetree.This matrix is a simple tree with just two levels.

Core Language

67

This matrix is a simple tree with just two levels.

In[3]:=

TreeForm@88a, b<, 8c, d<<D

List

Out[3]//TreeForm=

List

List

Here is a more complicated expression.

In[4]:=

88a b, c d ^ 2<, 8x ^ 3 y ^ 4<<

23 4Out[4]= 99a b, c d =, 9x y ==

The tree for this expression has several levels. The representation of the tree here was too longto fit on a single line, so it had to be broken onto two lines.In[5]:=

TreeForm@%DList

List

Out[5]//TreeForm=

Times

List

Times

Times

Power

Power

Power

The indices that label each part of an expression have a simple interpretation in terms of trees.Descending from the top node of the tree, each index specifies which branch to take in order toreach the part you want.

68

Core Language

Levels in ExpressionsThe Part function allows you to access specific parts of Mathematica expressions. But particularly when your expressions have fairly uniform structure, it is often convenient to be able torefer to a whole collection of parts at the same time.Levels provide a general way of specifying collections of parts in Mathematica expressions.Many Mathematica functions allow you to specify the levels in an expression on which theyshould act.Here is a simple expression, displayed in tree form.In[1]:=

Ht = 8x, 8x, y<, y<L TreeForm

List

Out[1]//TreeForm=

List

This searches for x in the expression t down to level 1. It finds only one occurrence.In[2]:=

Position@t, x, 1D

Out[2]= 881<<

This searches down to level 2. Now it finds both occurrences of x.

In[3]:=

Position@t, x, 2D

Out[3]= 881<, 82, 1<<

Core Language

69

This searches only at level 2. It finds just one occurrence of x.

In[4]:=

Position@t, x, 82<D

Out[4]= 882, 1<<

Position@expr, form,nD

give the positions at which form occurs in expr down to

level n

Position@expr, form,8n<D

give the positions exactly at level n

Controlling Position using levels.

You can think of levels in expressions in terms of trees. The level of a particular part in anexpression is simply the distance down the tree at which that part appears, with the top of thetree considered as level 0.It is equivalent to say that the parts which appear at level n are those that can be specified by asequence of exactly n indices.

levels 1 through n

Infinity

all levels (except 0)

8n<

level n only

8n1 ,n2 <

levels n1 through n2

Heads->True

include heads

Heads->False

exclude heads

Level specifications.

70

Core Language

Here is an expression, displayed in tree form.

In[5]:=

Hu = f@f@g@aD, aD, a, h@aD, fDL TreeForm

f

Out[5]//TreeForm=

This searches for a at levels from 2 downward.

In[6]:=

Position@u, a, 82, Infinity<D

Out[6]= 881, 1, 1<, 81, 2<, 83, 1<<

This shows where f appears other than in the head of an expression.

In[7]:=

Position@u, f, Heads -> FalseD

Out[7]= 884<<

This includes occurrences of f in heads of expressions.

In[8]:=

Position@u, f, Heads -> TrueD

Out[8]= 880<, 81, 0<, 84<<

Level@expr,levD

a list of the parts of expr at the levels specified by lev

Depth@exprD

the total number of levels in expr

Testing and extracting levels.

This gives a list of all parts of u that occur down to level 2.

Core Language

71

This gives a list of all parts of u that occur down to level 2.

In[9]:=

Level@u, 2D

Out[9]= 8g@aD, a, f@g@aD, aD, a, a, h@aD, f<

Here are the parts specifically at level 2.

In[10]:=

Level@u, 82<D

Out[10]= 8g@aD, a, a<

When you have got the hang of ordinary levels, you can try thinking about negative levels.Negative levels label parts of expressions starting at the bottom of the tree. Level -1 containsall the leaves of the tree: objects like symbols and numbers.This shows the parts of u at level -1.In[11]:=

Level@u, 8- 1<D

Out[11]= 8a, a, a, a, f<

You can think of expressions as having a "depth", as shown by TreeForm. In general, level - nin an expression is defined to consist of all subexpressions whose depth is n.The depth of g@aD is 2.In[12]:=

Depth@g@aDD

Out[12]= 2

The parts of u at level -2 are those that have depth exactly 2.

In[13]:=

Level@u, 8- 2<D

Out[13]= 8g@aD, h@aD<

72

Core Language

PatternsIntroduction to PatternsPatterns are used throughout Mathematica to represent classes of expressions. A simple example of a pattern is the expression f@x_D. This pattern represents the class of expressions withthe form f@anythingD.The main power of patterns comes from the fact that many operations in Mathematica can bedone not only with single expressions, but also with patterns that represent whole classes ofexpressions.You can use patterns in transformation rules to specify how classes of expressions should betransformed.In[1]:=Out[1]=

f@aD + f@bD . f@x_D -> x ^ 2

a2 + b2

You can use patterns to find the positions of all expressions in a particular class.In[2]:=

Position@8f@aD, g@bD, f@cD<, f@x_DD

Out[2]= 881<, 83<<

The basic object that appears in almost all Mathematica patterns is _ (traditionally calledblank by Mathematica programmers). The fundamental rule is simply that _ stands for anyexpression. On most keyboards the _ underscore character appears as the shifted version ofthe - dash character.Thus, for example, the pattern f@_D stands for any expression of the form f@anythingD. Thepattern f@x_D also stands for any expression of the form f@anythingD, but gives the name x tothe expression anything, allowing you to refer to it on the right-hand side of a transformationrule.You can put blanks anywhere in an expression. What you get is a pattern which matches allexpressions that can be made by filling in the blanks in any way.

Core Language

f@n_D

f with any argument, named n

f@n_,m_D

f with two arguments, named n and m

x^n_

x to any power, with the power named n

x_^n_

any expression to any power

a_+b_

a sum of two expressions

8a1_,a2_<

a list of two expressions

f@n_,n_D

f with two identical arguments

73

Some examples of patterns.

One of the most common uses of patterns is for destructuring function arguments. If youmake a definition for f@list_D, then you need to use functions like Part explicitly in order topick out elements of the list. But if you know for example that the list will always have twoelements, then it is usually much more convenient instead to give a definition instead forf@8x_, y_<D. Then you can refer to the elements of the list directly as x and y. In addition,Mathematica will not use the definition you have given unless the argument of f really is of therequired form of a list of two expressions.Here is one way to define a function which takes a list of two elements, and evaluates the firstelement raised to the power of the second element.In[4]:=

g@list_D := Part@list, 1D ^ Part@list, 2D

Here is a much more elegant way to make the definition, using a pattern.

In[5]:=

h@8x_, y_<D := x ^ y

A crucial point to understand is that Mathematica patterns represent classes of expressions witha given structure. One pattern will match a particular expression if the structure of the patternis the same as the structure of the expression, in the sense that by filling in blanks in the pattern you can get the expression. Even though two expressions may be mathematically equal,they cannot be represented by the same Mathematica pattern unless they have the samestructure.Thus, for example, the pattern H1 + x_L ^ 2 can stand for expressions like H1 + aL ^ 2 orH1 + b ^ 3L ^ 2 that have the same structure. However, it cannot stand for the expression1 + 2 a + a ^ 2. Although this expression is mathematically equal to H1 + aL ^ 2, it does not havethe same structure as the pattern H1 + x_L ^ 2.

74

Core Language

Thus, for example, the pattern H1 + x_L ^ 2 can stand for expressions like H1 + aL ^ 2 orH1 + b ^ 3L ^ 2 that have the same structure. However, it cannot stand for the expression1 + 2 a + a ^ 2. Although this expression is mathematically equal to H1 + aL ^ 2, it does not havethe same structure as the pattern H1 + x_L ^ 2.The fact that patterns in Mathematica specify the structure of expressions is crucial in making itpossible to set up transformation rules which change the structure of expressions, while leavingthem mathematically equal.It is worth realizing that in general it would be quite impossible for Mathematica to matchpatterns by mathematical, rather than structural, equivalence. In the case of expressions likeH1 + aL ^ 2 and 1 + 2 a + a ^ 2, you can determine equivalence just by using functions like Expandand Factor. But, as discussed in "Reducing Expressions to Their Standard Form" there is nogeneral way to find out whether an arbitrary pair of mathematical expressions are equal.As another example, the pattern x ^ _ will match the expression x ^ 2. It will not, however,match the expression 1, even though this could be considered as x ^ 0. "Optional and DefaultArguments" discusses how to construct a pattern for which this particular case will match. Butyou should understand that in all cases pattern matching in Mathematica is fundamentallystructural.The x ^ n_ matches only x ^ 2 and x ^ 3. 1 and x can mathematically be written as xn , but do nothave the same structure.In[6]:=Out[6]=

81, x, x ^ 2, x ^ 3< . x ^ n_ -> r@nD

81, x, r@2D, r@3D<

Another point to realize is that the structure Mathematica uses in pattern matching is the fullform of expressions printed by FullForm. Thus, for example, an object such as 1 x, whose fullform is Power@x, - 1D will be matched by the pattern x_ ^ n_, but not by the pattern x_ y_,whose full form is Times@x_, Power@y_, - 1DD. Again, "Optional and Default Arguments" willdiscuss how you can construct patterns which can match all these cases.The expressions in the list contain explicit powers of b, so the transformation rule can beapplied.In[7]:=

8a b, 1 b ^ 2, 2 b ^ 2< . b ^ n_ -> d@nD

Out[7]= 8a d@-1D, d@-2D, 2 d@-2D<

Core Language

75

Here is the full form of the list.

In[8]:=

FullForm@8a b, 1 b ^ 2, 2 b ^ 2<D

Out[8]//FullForm=

List@Times@a, Power@b, -1DD, Power@b, -2D, Times@2, Power@b, -2DDD

Although Mathematica does not use mathematical equivalences such as x1 = x when matchingpatterns, it does use certain structural equivalences. Thus, for example, Mathematica takesaccount of properties such as commutativity and associativity in pattern matching.To apply this transformation rule, Mathematica makes use of the commutativity and associativity of addition.In[9]:=Out[9]=

f@a + bD + f@a + cD + f@b + dD . f@a + x_D + f@c + y_D -> p@x, yD

f@b + dD + p@b, aD

The discussion considers only pattern objects such as x_ which can stand for any single expression. Other Tutorials discuss the constructs that Mathematica uses to extend and restrict theclasses of expressions represented by patterns.

Finding Expressions That Match a Pattern

Cases@list, formD

give the elements of list that match form

Count@list, formD

give the number of elements in list that match form

Position@list, form,81<D

give the positions of elements in list that match form

Select@list,testD

give the elements of list on which test gives True

Pick@list,sel, formD

give the elements of list for which the corresponding

elements of sel match form

Finding elements that match a pattern.

This gives the elements of the list which match the pattern x ^ _.In[1]:=Out[1]=

Cases@83, 4, x, x ^ 2, x ^ 3<, x ^ _D9x2 , x3 =

Here is the total number of elements which match the pattern.

In[2]:=Out[2]=

Count@83, 4, x, x ^ 2, x ^ 3<, x ^ _D2

You can apply functions like Cases not only to lists, but to expressions of any kind. In addition,you can specify the level of parts at which you want to look.

76

Core Language

You can apply functions like Cases not only to lists, but to expressions of any kind. In addition,you can specify the level of parts at which you want to look.

Cases@expr,lhs->rhsD

find elements of expr that match lhs, and give a list of theresults of applying the transformation rule to them

Cases@expr,lhs->rhs,levD

test parts of expr at levels specified by lev

Count@expr, form,levD

give the total number of parts that match form at levels

specified by lev

Position@expr, form,levD

give the positions of parts that match form at levels specified by lev

Searching for parts of expressions that match a pattern.

This returns a list of the exponents n.In[3]:=Out[3]=

Cases@83, 4, x, x ^ 2, x ^ 3<, x ^ n_ -> nD

82, 3<

The pattern _Integer matches any integer. This gives a list of integers appearing at any level.In[4]:=Out[4]=

Cases@83, 4, x, x ^ 2, x ^ 3<, _Integer, InfinityD

83, 4, 2, 3<

Cases@expr, form,lev,nD

find only the first n parts that match form

Position@expr, form,lev,nD

give the positions of the first n parts that match form

Limiting the number of parts to search for.

This gives the positions of the first two powers of x appearing at any level.In[5]:=Out[5]=

Position@84, 4 + x ^ a, x ^ b, 6 + x ^ 5<, x ^ _, Infinity, 2D

882, 2<, 83<<

The positions are specified in exactly the form used by functions such as Extract andReplacePart discussed in "Lists".In[6]:=Out[6]=

ReplacePart@84, 4 + x ^ a, x ^ b, 6 + x ^ 5<, zzz, %D

94, 4 + zzz, zzz, 6 + x5 =

Core Language

DeleteCases @expr, formD

delete elements of expr that match form

DeleteCases @expr, form,levD

delete parts of expr that match form at levels specified by

77

levDeleting parts of expressions that match a pattern.This deletes the elements which match x ^ n_.In[7]:=Out[7]=

DeleteCases@83, 4, x, x ^ 2, x ^ 3<, x ^ n_D

83, 4, x<

This deletes all integers appearing at any level.

In[8]:=Out[8]=

DeleteCases@83, 4, x, 2 + x, 3 + x<, _Integer, InfinityD

8x, x, x<

ReplaceList @expr,lhs->rhsD

find all ways that expr can match lhs

Finding arrangements of an expression that match a pattern.

This finds all ways that the sum can be written in two parts.In[9]:=Out[9]=

ReplaceList@a + b + c, x_ + y_ -> g@x, yDD

This finds all pairs of identical elements. The pattern ___ stands for any sequence of elements.In[10]:=Out[10]=

ReplaceList@8a, b, b, b, c, c, a<, 8___, x_, x_, ___< -> xD

8b, b, c<

Naming Pieces of Patterns

Particularly when you use transformation rules, you often need to name pieces of patterns. Anobject like x_ stands for any expression, but gives the expression the name x. You can then, forexample, use this name on the right-hand side of a transformation rule.An important point is that when you use x_, Mathematica requires that all occurrences of blankswith the same name x in a particular expression must stand for the same expression.Thus f@x_, x_D can only stand for expressions in which the two arguments of f are exactly thesame. f@_, _D, on the other hand, can stand for any expression of the form f@x, yD, where xand y need not be the same.

78

Core Language

Thus f@x_, x_D can only stand for expressions in which the two arguments of f are exactly thesame. f@_, _D, on the other hand, can stand for any expression of the form f@x, yD, where xand y need not be the same.The transformation rule applies only to cases where the two arguments of f are identical.8f@a, aD, f@a, bD< . f@x_, x_D -> p@xD

In[1]:=Out[1]=

8p@aD, f@a, bD<

Mathematica allows you to give names not just to single blanks, but to any piece of a pattern.The object x : pattern in general represents a pattern which is assigned the name x. In transformation rules, you can use this mechanism to name exactly those pieces of a pattern that you needto refer to on the right-hand side of the rule.

any expression

x_

any expression, to be named x

x:pattern

an expression to be named x, matching pattern

Patterns with names.

This gives a name to the complete form _ ^ _ so you can refer to it as a whole on the right-handside of the transformation rule.In[2]:=Out[2]=

f@a ^ bD . f@x : _ ^ _D -> p@xD

pAab E

Here the exponent is named n, while the whole object is x.

In[3]:=Out[3]=

f@a ^ bD . f@x : _ ^ n_D -> p@x, nD

pAab , bE

When you give the same name to two pieces of a pattern, you constrain the pattern to matchonly those expressions in which the corresponding pieces are identical.Here the pattern matches both cases.In[4]:=Out[4]=

8f@h@4D, h@4DD, f@h@4D, h@5DD< . f@h@_D, h@_DD -> q

8q, q<

Core Language

79

Now both arguments of f are constrained to be the same, and only the first case matches.In[5]:=Out[5]=

8f@h@4D, h@4DD, f@h@4D, h@5DD< . f@x : h@_D, x_D -> r@xD

8r@h@4DD, f@h@4D, h@5DD<

Specifying Types of Expression in Patterns

You can tell a lot about what type of expression something is by looking at its head. Thus, forexample, an integer has head Integer, while a list has head List.In a pattern, _h and x_h represent expressions that are constrained to have head h. Thus, forexample, _Integer represents any integer, while _List represents any list.

x_h

an expression with head h

x_Integer

an integer

x_Real

an approximate real number

x_Complex

a complex number

x_List

a list

x_Symbol

a symbol

Patterns for objects with specified heads.

This replaces just those elements that are integers.In[1]:=Out[1]=

8a, 4, 5, b< . x_Integer -> p@xD

8a, p@4D, p@5D, b<

You can think of making an assignment for f@x_IntegerD as like defining a function f thatmust take an argument of type Integer.This defines a value for the function gamma when its argument is an integer.In[2]:=

gamma@n_IntegerD := Hn - 1L !The definition applies only when the argument of gamma is an integer.

In[3]:=Out[3]=

gamma@4D + gamma@xD6 + gamma@xD

80

Core Language

The object 4. has head Real , so the definition does not apply.In[4]:=Out[4]=

gamma@4.Dgamma@4.D

This defines values for expressions with integer exponents.

In[5]:=

d@x_ ^ n_IntegerD := n x ^ Hn - 1LThe definition is used only when the exponent is an integer.

In[6]:=Out[6]=

d@x ^ 4D + d@Ha + bL ^ 3D + d@x ^ H1 2LD

3 Ha + bL2 + 4 x3 + dB x F

Putting Constraints on Patterns

Mathematica provides a general mechanism for specifying constraints on patterns. All you needdo is to put ; condition at the end of a pattern to signify that it applies only when the specifiedcondition is True. You can read the operator ; as "slash-semi", "whenever" or "provided that".

pattern;condition

a pattern that matches only when a condition is satisfied

lhs:>rhs;condition

a rule that applies only when a condition is satisfied

lhs:=rhs;condition

a definition that applies only when a condition is satisfied

Putting conditions on patterns and transformation rules.

This gives a definition for fac that applies only when its argument n is positive.In[1]:=

fac@n_ ; n > 0D := n !The definition for fac is used only when the argument is positive.

In[2]:=Out[2]=

fac@6D + fac@- 4D720 + fac@-4D

This gives the negative elements in the list.

In[3]:=

Cases@83, - 4, 5, - 2<, x_ ; x < 0D

Out[3]= 8-4, -2<

You can use ; on whole definitions and transformation rules, as well as on individual patterns.In general, you can put ; condition at the end of any := definition or :> rule to tell Mathematicathat the definition or rule applies only when the specified condition holds. Note that ; conditions should not usually be put at the end of = definitions or -> rules, since they will then be

Core Language

81

You can use ; on whole definitions and transformation rules, as well as on individual patterns.In general, you can put ; condition at the end of any := definition or :> rule to tell Mathematicathat the definition or rule applies only when the specified condition holds. Note that ; conditions should not usually be put at the end of = definitions or -> rules, since they will then beevaluated immediately, as discussed in "Immediate and Delayed Definitions".Here is another way to give a definition which applies only when its argument n is positive.In[4]:=

You can use the ; operator to implement arbitrary mathematical constraints on the applicability of rules. In typical cases, you give patterns which structurally match a wide range of expressions, but then use mathematical constraints to reduce the range of expressions to a muchsmaller set.This rule applies only to expressions that have the structure v@x_, 1 - x_D.In[6]:=

v@x_, 1 - x_D := p@xD

This expression has the appropriate structure, so the rule applies.

In[7]:=Out[7]=

v@a ^ 2, 1 - a ^ 2DpAa2 E

This expression, while mathematically of the correct form, does not have the appropriatestructure, so the rule does not apply.In[8]:=Out[8]=

v@4, - 3Dv@4, -3D

This rule applies to any expression of the form w@x_, y_D, with the added restriction that

y == 1 - x.In[9]:=

w@x_, y_D := p@xD ; y == 1 - x

The new rule does apply to this expression.

In[10]:=Out[10]=

w@4, - 3Dp@4D

In setting up patterns and transformation rules, there is often a choice of where to put ;conditions. For example, you can put a ; condition on the right-hand side of a rule in the form

82

Core Language

In setting up patterns and transformation rules, there is often a choice of where to put ;conditions. For example, you can put a ; condition on the right-hand side of a rule in the formlhs :> rhs ; condition, or you can put it on the left-hand side in the form lhs ; condition -> rhs. Youmay also be able to insert the condition inside the expression lhs. The only constraint is that allthe names of patterns that you use in a particular condition must appear in the pattern to whichthe condition is attached. If this is not the case, then some of the names needed to evaluatethe condition may not yet have been "bound" in the pattern-matching process. If this happens,then Mathematica uses the global values for the corresponding variables, rather than the valuesdetermined by pattern matching.Thus, for example, the condition in f@x_, y_D ; Hx + y < 2L will use values for x and y that arefound by matching f@x_, y_D, but the condition in f@x_ ; x + y < 2, y_D will use the globalvalue for y, rather than the one found by matching the pattern.As long as you make sure that the appropriate names are defined, it is usually most efficient toput ; conditions on the smallest possible parts of patterns. The reason for this is that Mathematica matches pieces of patterns sequentially, and the sooner it finds a ; condition whichfails, the sooner it can reject a match.Putting the ; condition around the x_ is slightly more efficient than putting it around thewhole pattern.In[11]:=Out[11]=

Cases@8z@1, 1D, z@- 1, 1D, z@- 2, 2D<, z@x_ ; x < 0, y_DD

8z@-1, 1D, z@-2, 2D<

You need to put parentheses around the ; piece in a case like this.In[12]:=Out[12]=

81 + a, 2 + a, - 3 + a< . Hx_ ; x < 0L + a -> p@xD

81 + a, 2 + a, p@-3D<

It is common to use ; to set up patterns and transformation rules that apply only to expressions with certain properties. There is a collection of functions built into Mathematica for testingthe properties of expressions. It is a convention that functions of this kind have names that endwith the letter Q, indicating that they "ask a question".

Core Language

IntegerQ@exprD

integer

EvenQ@exprD

even number

OddQ@exprD

odd number

PrimeQ@exprD

prime number

NumberQ@exprD

explicit number of any kind

NumericQ@exprD

numeric quantity

83

PolynomialQ @expr,8x1 ,x2 ,<D

polynomial in x1 , x2 , ...

VectorQ@exprD

a list representing a vector

MatrixQ@exprD

a list of lists representing a matrix

VectorQAexpr,NumericQE , MatrixQAexpr,NumericQEvectors and matrices where all elements are numeric

VectorQ@expr,testD , MatrixQ@expr,testDvectors and matrices for which the function test yieldsTrue on every elementfull array with depth matching d

ArrayQ@expr,dD

Some functions for testing mathematical properties of expressions.

The rule applies to all elements of the list that are numbers.In[13]:=Out[13]=

82.3, 4, 7 8, a, b< . Hx_ ; NumberQ@xDL -> x ^ 2

:5.29, 16,

49

, a, b>

64

This definition applies only to vectors of integers.

In[14]:=

mi@list_D := list ^ 2 ; VectorQ@list, IntegerQD

The definition is now used only in the first case.

In[15]:=Out[15]=

8mi@82, 3<D, mi@82.1, 2.2<D, mi@8a, b<D<

884, 9<, mi@82.1, 2.2<D, mi@8a, b<D<

An important feature of all the Mathematica property-testing functions whose names end in Q isthat they always return False if they cannot determine whether the expression you give has aparticular property.

84

Core Language

4561 is an integer, so this returns True .

In[16]:=Out[16]=

IntegerQ@4561DTrue

This returns False , since x is not known to be an integer.

In[17]:=Out[17]=

IntegerQ@xDFalse

Functions like IntegerQ@xD test whether x is explicitly an integer. With assertions like x Integers you can use Refine, Simplify and related functions to make inferences aboutsymbolic variables x.SameQAx,yE or x===y

You can use FreeQ to define a "linearity" rule for h.

h@a_ b_, x_D := a h@b, xD ; FreeQ@a, xD

a pattern which matches an expression only if test yields

True when applied to the expression

Another way to constrain patterns.

The construction pattern ; condition allows you to evaluate a condition involving pattern namesto determine whether there is a match. The construction pattern ? test instead applies a functiontest to the whole expression matched by pattern to determine whether there is a match. Using ?instead of ; sometimes leads to more succinct definitions.With this definition matches for x_ are tested with the function NumberQ .In[23]:=

p@4.5D + p@3 2D + p@uD

Here is a more complicated definition. Do not forget the parentheses around the pure function.In[25]:=

q@8x_Integer, y_Integer< ? HFunction@v, v.v > 4DLD := qp@x + yD

The definition applies only in certain cases.

In[26]:=Out[26]=

8q@83, 4<D, q@81, 1<D, q@8- 5, - 7<D<

8qp@7D, q@81, 1<D, qp@-12D<

Except@cD

a pattern which matches any expression except c

Except@c,pattD

a pattern which matches patt but not c

Patterns with exceptions.

86

Core Language

This gives all elements except 0.

In[27]:=Out[27]=

Cases@81, 0, 2, 0, 3<, Except@0DD

81, 2, 3<

Except can take a pattern as an argument.

In[28]:=Out[28]=

Cases@8a, b, 0, 1, 2, x, y<, Except@_IntegerDD

8a, b, x, y<

This picks out integers that are not 0.

In[29]:=Out[29]=

Cases@8a, b, 0, 1, 2, x, y<, Except@0, _IntegerDD

81, 2<

Except@cD is in a sense a very general pattern: it matches anything except c. In many situations you instead need to use Except@c, pattD, which starts from expressions matching patt,then excludes ones that match c.

Patterns Involving Alternatives

a pattern that can have one of several forms

patt1 patt2

Specifying patterns that involve alternatives.

This defines h to give p when its argument is either a or b.In[1]:=

h@a

bD := p

The first two cases give p.

In[2]:=Out[2]=

8h@aD, h@bD, h@cD, h@dD<

8p, p, h@cD, h@dD<

You can also use alternatives in transformation rules.

In[3]:=Out[3]=

8a, b, c, d< . Ha8p, p, c, d<

bL -> p

Core Language

87

Here is another example, in which one of the alternatives is itself a pattern.

In[4]:=Out[4]=

81, x, x ^ 2, x ^ 3, y ^ 2< . Hx

x ^ _L -> q

91, q, q, q, y2 =

When you use alternatives in patterns, you should make sure that the same set of namesappear in each alternative. When a pattern like Ha@x_D

b@x_DL matches an expression, there

will always be a definite expression that corresponds to the object x. If you try to match apattern like Ha@x_D

b@y_DL, then there still will be definite expressions corresponding to x and

y, but the unmatched one will be Sequence@ D.

Here f is used to name the head, which can be either a or b.In[5]:=Out[5]=

8a@2D, b@3D, c@4D, a@5D< . Hf : Ha

bLL@x_D -> r@f, xD

8r@a, 2D, r@b, 3D, c@4D, r@a, 5D<

Pattern SequencesIn some cases you may need to specify pattern sequences that are more intricate than thingslike x__ or x ..; for such situations you can use PatternSequence@p1 , p2 , D.

PatternSequence@p1 ,p2 ,D

a sequence of arguments matching p1 , p2 ,

Pattern sequences.This defines a function with two or more arguments, grouping the first two.In[1]:=

f@x : PatternSequence@_, _D, y___D := p@8x<, 8y<D

Evaluate the function for different numbers of arguments.

In[2]:=

8f@1D, f@1, 2D, f@1, 2, 3, 4, 5D<

Out[2]= 8f@1D, p@81, 2<, 8<D, p@81, 2<, 83, 4, 5<D<

This picks out the longest run of the sequence a, b in the list.In[3]:=

Out[3]= 8a, b, a, b<

The empty sequence, PatternSequence@D, is sometimes useful to specify an optional argument.

This picks out expressions with exactly one or two arguments.

88

Core Language

This picks out expressions with exactly one or two arguments.

In[4]:=

8g@D, g@1D, g@1, 2D, g@1, 2, 3D< . x : g@_, _

PatternSequence@DD p@xD

Out[4]= 8g@D, p@g@1DD, p@g@1, 2DD, g@1, 2, 3D<

Flat and Orderless Functions

Although Mathematica matches patterns in a purely structural fashion, its notion of structuralequivalence is quite sophisticated. In particular, it takes account of properties such as commutativity and associativity in functions like Plus and Times.This means, for example, that Mathematica considers the expressions x + y and y + x equivalentfor the purposes of pattern matching. As a result, a pattern like g@x_ + y_, x_D can match notonly g@a + b, aD, but also g@a + b, bD.This expression has exactly the same form as the pattern.In[1]:=Out[1]=

g@a + b, aD . g@x_ + y_, x_D -> p@x, yD

p@a, bD

In this case, the expression has to be put in the form g@b + a, bD in order to have the samestructure as the pattern.In[2]:=Out[2]=

g@a + b, bD . g@x_ + y_, x_D -> p@x, yD

p@b, aD

Whenever Mathematica encounters an orderless or commutative function such as Plus or

Times in a pattern, it effectively tests all the possible orders of arguments to try and find amatch. Sometimes, there may be several orderings that lead to matches. In such cases, Mathematica just uses the first ordering it finds. For example, h@x_ + y_, x_ + z_D could matchh@a + b, a + bD with xa, yb, zb or with xb, ya, za. Mathematica tries the case xa,yb, zb first, and so uses this match.This can match either with x a or with x b. Mathematica tries x a first, and so uses thismatch.In[3]:=Out[3]=

h@a + b, a + bD . h@x_ + y_, x_ + z_D -> p@x, y, zD

p@a, b, bD

Core Language

89

ReplaceList shows both possible matches.

In[4]:=Out[4]=

ReplaceList@h@a + b, a + bD, h@x_ + y_, x_ + z_D -> p@x, y, zDD

8p@a, b, bD, p@b, a, aD<

As discussed in "Attributes", Mathematica allows you to assign certain attributes to functions,

which specify how those functions should be treated in evaluation and pattern matching. Functions can for example be assigned the attribute Orderless, which specifies that they should betreated as commutative or symmetric, and allows their arguments to be rearranged in trying tomatch patterns.

Plus has attributes Orderless and Flat , as well as others.

This defines q to be an orderless or commutative function.

SetAttributes@q, OrderlessDThe arguments of q are automatically sorted into order.

In[7]:=Out[7]=

q@b, a, cDq@a, b, cD

Mathematica rearranges the arguments of q functions to find a match.

In[8]:=

f@q@a, bD, q@b, cDD . f@q@x_, y_D, q@x_, z_DD -> p@x, y, zD

Out[8]= p@b, a, cD

In addition to being orderless, functions like Plus and Times also have the property of beingflat or associative. This means that you can effectively parenthesize their arguments in anyway, so that, for example, x + Hy + zL is equivalent to x + y + z, and so on.

90

Core Language

In addition to being orderless, functions like Plus and Times also have the property of beingflat or associative. This means that you can effectively parenthesize their arguments in anyway, so that, for example, x + Hy + zL is equivalent to x + y + z, and so on.Mathematica takes account of flatness in matching patterns. As a result, a pattern likeg@x_ + y_D can match g@a + b + cD, with x a and y Hb + cL.The argument of g is written as a + Hb + cL so as to match the pattern.In[9]:=Out[9]=

g@a + b + cD . g@x_ + y_D -> p@x, yD

p@a, b + cD

If there are no other constraints, Mathematica will match x_ to the first element of the sum.In[10]:=

g@a + b + c + dD . g@x_ + y_D -> p@x, yD

Out[10]= p@a, b + c + dD

This shows all the possible matches.

In[11]:=Out[11]=

ReplaceList@g@a + b + cD, g@x_ + y_D -> p@x, yDD

Here x_ is forced to match b + d.

In[12]:=Out[12]=

g@a + b + c + d, b + dD . g@x_ + y_, x_D -> p@x, yD

p@b + d, a + cD

Mathematica can usually apply a transformation rule to a function only if the pattern in the rulecovers all the arguments in the function. However, if you have a flat function, it is sometimespossible to apply transformation rules even though not all the arguments are covered.This rule applies even though it does not cover all the terms in the sum.In[13]:=

a + b + c . a + c -> p

Out[13]= b + p

This combines two of the terms in the sum.

In[14]:=Out[14]=

u@aD + u@bD + v@cD + v@dD . u@x_D + u@y_D -> u@x + yD

u@a + bD + v@cD + v@dD

Functions like Plus and Times are both flat and orderless. There are, however, some functions,such as Dot, which are flat, but not orderless.Both x_ and y_ can match any sequence of terms in the dot product.

Core Language

91

Both x_ and y_ can match any sequence of terms in the dot product.In[15]:=Out[15]=

a.b.c.d.a.b . x_.y_.x_ -> p@x, yD

p@a.b, c.dD

This assigns the attribute Flat to the function r.

In[16]:=

SetAttributes@r, FlatDMathematica writes the expression in the form r@r@a, bD, r@a, bDD to match the pattern.

In[17]:=Out[17]=

r@a, b, a, bD . r@x_, x_D -> rp@xD

rp@r@a, bDD

Mathematica writes this expression in the form r@a, r@r@bD, r@bDD, cD to match the pattern.In[18]:=Out[18]=

r@a, b, b, cD . r@x_, x_D -> rp@xD

r@a, rp@r@bDD, cD

In an ordinary function that is not flat, a pattern such as x_ matches an individual argument ofthe function. But in a function f @a, b, c, D that is flat, x_ can match objects such as f @b, cDwhich effectively correspond to a sequence of arguments. However, in the case where x_matches a single argument in a flat function, the question comes up as to whether the object itmatches is really just the argument a itself, or f @aD. Mathematica chooses the first of thesecases if the function carries the attribute OneIdentity , and chooses the second case otherwise.This adds the attribute OneIdentity to the function r.In[19]:=

r@a, b, b, cD . r@x_, x_D -> rp@xD

r@a, rp@bD, cD

The functions Plus, Times and Dot all have the attribute OneIdentity , reflecting the fact thatPlus@xD is equivalent to x, and so on. However, in representing mathematical objects, it isoften convenient to deal with flat functions that do not have the attribute OneIdentity .

92

Core Language

Functions with Variable Numbers of Arguments

Unless f is a flat function, a pattern like f @x_, y_D stands only for instances of the function withexactly two arguments. Sometimes you need to set up patterns that can allow any number ofarguments.You can do this using multiple blanks. While a single blank such as x_ stands for a single Mathematica expression, a double blank such as x__ stands for a sequence of one or more expressions.Here x__ stands for the sequence of expressions Ha, b, cL.In[1]:=

f@a, b, cD . f@x__D -> p@x, x, xD

Out[1]= p@a, b, c, a, b, c, a, b, cD

Here is a more complicated definition, which picks out pairs of duplicated elements in h.In[2]:=

h@a___, x_, b___, x_, c___D := hh@xD h@a, b, cD

The definition is applied twice, picking out the two paired elements.

In[3]:=

h@2, 3, 2, 4, 5, 3D

Out[3]= h@4, 5D hh@2D hh@3D

Double blanks __ stand for sequences of one or more expressions. Triple blanks ___ standfor sequences of zero or more expressions. You should be very careful whenever you use tripleblank patterns. It is easy to make a mistake that can lead to an infinite loop. For example, ifyou define p@x_, y___D := p@xD q@yD, then typing in p@aD will lead to an infinite loop, with yrepeatedly matching a sequence with zero elements. Unless you are sure you want to includethe case of zero elements, you should always use double blanks rather than triple blanks.

Core Language

any single expression

x_

any single expression, to be named x

__

any sequence of one or more expressions

x __

sequence named x

x __ h

sequence of expressions, all of whose heads are h

___

any sequence of zero or more expressions

x ___

sequence of zero or more expressions named x

x ___ h

sequence of zero or more expressions, all of whose heads

are h

93

More kinds of pattern objects.

Notice that with flat functions such as Plus and Times, Mathematica automatically handlesvariable numbers of arguments, so you do not explicitly need to use double or triple blanks, asdiscussed in "Flat and Orderless Functions".When you use multiple blanks, there are often several matches that are possible for a particularexpression. By default, Mathematica tries first those matches that assign the shortestsequences of arguments to the first multiple blanks that appear in the pattern. You can changethis order by wrapping Longest or Shortest around parts of the pattern.

Longest@pD

match the longest sequence consistent with the pattern p

Shortest@pD

match the shortest sequence consistent with the pattern p

Controlling the order in which matches are tried.

This gives a list of all the matches that Mathematica tries.In[4]:=

ReplaceList@f@a, b, c, dD, f@x__, y__D -> g@8x<, 8y<DD

Out[4]= 8g@8a<, 8b, c, d<D, g@8a, b<, 8c, d<D, g@8a, b, c<, 8d<D<

This forces Mathematica to try the longest matches for x__ first.In[5]:=

ReplaceList@f@a, b, c, dD, f@Longest@x__D, y__D -> g@8x<, 8y<DD

Out[5]= 8g@8a, b, c<, 8d<D, g@8a, b<, 8c, d<D, g@8a<, 8b, c, d<D<

Many kinds of enumeration can be done by using ReplaceList with various kinds of patterns.In[6]:=

This tries the shortest matches for x__ first.

ReplaceList@f@a, b, c, dD, f@___, Shortest@x__D, ___D -> g@xDD

Optional and Default Arguments

Sometimes you may want to set up functions where certain arguments, if omitted, are given"default values". The pattern x_: v stands for an object that can be omitted, and if so, will bereplaced by the default value v.This defines a function j with a required argument x, and optional arguments y and z, withdefault values 1 and 2, respectively.In[1]:=

j@x_, y_: 1, z_: 2D := jp@x, y, zD

The default value of z is used here.

In[2]:=Out[2]=

j@a, bDjp@a, b, 2D

Now the default values of both y and z are used.

In[3]:=Out[3]=

j@aDjp@a, 1, 2D

x _:v

an expression which, if omitted, is taken to have default

value v

x _ h:v

an expression with head h and default value v

x _.

an expression with a built-in default value

Pattern objects with default values.

Some common Mathematica functions have built-in default values for their arguments. In suchcases, you need not explicitly give the default value in x_: v, but instead you can use the moreconvenient notation x_. in which a built-in default value is assumed.

Core Language

x_+y_.

default for y is 0

x_ y_.

default for y is 1

x_^y_.

default for y is 1

95

Some patterns with optional pieces.

Here a matches the pattern x_ + y_. with y taken to have the default value 0.In[4]:=Out[4]=

8f@aD, f@a + bD< . f@x_ + y_.D -> p@x, yD

8p@a, 0D, p@b, aD<

Because Plus is a flat function, a pattern such as x_ + y_ can match a sum with any number ofterms. This pattern cannot, however, match a single term such as a. However, the patternx_ + y_. contains an optional piece, and can match either an explicit sum of terms in which bothx_ and y_ appear, or a single term x_, with y taken to be 0.Using constructs such as x_., you can easily construct single patterns that match expressionswith several different structures. This is particularly useful when you want to match severalmathematically equal forms that do not have the same structure.The pattern matches g@a ^ 2D, but not g@a + bD.In[5]:=Out[5]=

8g@a ^ 2D, g@a + bD< . g@x_ ^ n_D -> p@x, nD

8p@a, 2D, g@a + bD<

By giving a pattern in which the exponent is optional, you can match both cases.In[6]:=

8g@a ^ 2D, g@a + bD< . g@x_ ^ n_.D -> p@x, nD

Out[6]= 8p@a, 2D, p@a + b, 1D<

The pattern a_. + b_. x_ matches any linear function of x_.

In[7]:=

lin@a_. + b_. x_, x_D := p@a, bD

In this case, b 1.

In[8]:=Out[8]=

lin@1 + x, xDp@1, 1D

96

Core Language

Here b 1 and a 0.In[9]:=Out[9]=

lin@y, yDp@0, 1D

Standard Mathematica functions such as Plus and Times have built-in default values for theirarguments. You can also set up defaults for your own functions, as described in "Patterns".Sometimes it is convenient not to assign a default value to an optional argument; such arguments can be specified with the help of PatternSequence@D.

p PatternSequence@D

optional pattern p with no default value

Optional argument without a default value.

The pattern matches an optional second argument of 2, without a default value.In[10]:=

8g@1D, g@1, 1D, g@1, 2D< . g@x_, 2

PatternSequence@DD p@xD

Out[10]= 8p@1D, g@1, 1D, p@1D<

Setting Up Functions with Optional Arguments

When you define a complicated function, you will often want to let some of the arguments ofthe function be optional. If you do not give those arguments explicitly, you want them to takeon certain default values.Built-in Mathematica functions use two basic methods for dealing with optional arguments. Youcan choose between the same two methods when you define your own functions in Mathematica.The first method is to have the meaning of each argument determined by its position, and thento allow one to drop arguments, replacing them by default values. Almost all built-in Mathematica functions that use this method drop arguments from the end. For example, the built-infunction Flatten@list, nD allows you to drop the second argument, which is taken to have adefault value of Infinity.You can implement this kind of positional argument using _ : patterns.

Core Language

f @x_,k_: kdef D:=value

97

a typical definition for a function whose second argument

is optional, with default value kdef

Defining a function with positional arguments.

This defines a function with an optional second argument. When the second argument is omitted, it is taken to have the default value Infinity .In[1]:=

f@list_, n_: InfinityD := f0@list, nD

Here is a function with two optional arguments.

In[2]:=

fx@list_, n1_: 1, n2_: 2D := fx0@list, n1, n2D

Mathematica assumes that arguments are dropped from the end. As a result m here gives thevalue of n1, while n2 has its default value of 2.

In[3]:=Out[3]=

fx@k, mDfx0@k, m, 2D

The second method that built-in Mathematica functions use for dealing with optional argumentsis to give explicit names to the optional arguments, and then to allow their values to be givenusing transformation rules. This method is particularly convenient for functions like Plot whichhave a very large number of optional parameters, only a few of which usually need to be set inany particular instance.The typical arrangement is that values for named optional arguments can be specified byincluding the appropriate transformation rules at the end of the arguments to a particularfunction. Thus, for example, the rule Joined -> True, which specifies the setting for the namedoptional argument Joined, could appear as ListPlot@list, Joined -> TrueD.When you set up named optional arguments for a function f , it is conventional to store thedefault values of these arguments as a list of transformation rules assigned to Options@ f D.

f Ax_,OptionsPattern@DE:=value

a typical definition for a function with zero or more named

optional arguments

OptionValue @nameD

the value of a named optional argument in the body of the

function

Named arguments.

98

Core Language

This sets up default values for two named optional arguments opt1 and opt2 in the functionfn.In[4]:=Out[4]=

Options@fnD = 8opt1 -> 1, opt2 -> 2<

8opt1 1, opt2 2<

Here is the definition for a function fn which allows zero or more named optional arguments tobe specified.In[5]:=

fn@x_, OptionsPattern@DD := k@x, OptionValue@opt2DD

With no optional arguments specified, the default rule for opt2 is used.

In[6]:=

fn@4D

Out[6]= k@4, 2D

If you explicitly give a rule for opt2, it will override the default rules stored in Options@fnD.In[7]:=

fn@4, opt2 -> 7D

Out[7]= k@4, 7D

FilterRules Aopts,Options@nameDE

the rules in opts used as options by the function f

FilterRules Aopts,ExceptAOptions@nameDEEthe rules in opts not used as options by the function fFiltering options.

Sometimes when you write a function you will want to pass on options to functions that it calls.Here is a simple function that solves a differential equation numerically and plots its solution.In[8]:=

With no options given, the default options for NDSolve and Plot are used.In[9]:=

odeplot@8y ''@xD + y@xD == 0, y@0D 1, y '@0D 0<, y@xD, 8x, 0, 10<D

Out[9]=

This changes the method used by NDSolve and the color in the plot.In[10]:=

odeplot@8y ''@xD + y@xD == 0, y@0D 1, y '@0D 0<,

y@xD, 8x, 0, 10<, Method "ExplicitRungeKutta", PlotStyle RedD

Out[10]=

Repeated Patternsexpr..

a pattern or other expression repeated one or more times

expr...

a pattern or other expression repeated zero or more times

Repeated patterns.

Multiple blanks such as x__ allow you to give patterns in which sequences of arbitrary expressions can occur. The Mathematica pattern repetition operators .. and ... allow you to construct patterns in which particular forms can be repeated any number of times. Thus, for example, f@a ..D represents any expression of the form f@aD, f@a, aD, f@a, a, aD, and so on.The pattern f@a ..D allows the argument a to be repeated any number of times.In[1]:=Out[1]=

Cases@8f@aD, f@a, b, aD, f@a, a, aD<, f@a ..DD

8f@aD, f@a, a, aD<

This pattern allows any number of a arguments, followed by any number of b arguments.In[2]:=Out[2]=

Here each argument can be either a or b.

Cases@8f@aD, f@a, b, aD, f@a, c, aD<, f@Ha

In[3]:=Out[3]=

bL ..DD

8f@aD, f@a, b, aD<

You can use .. and ... to represent repetitions of any pattern. If the pattern contains namedparts, then each instance of these parts must be identical.This defines a function whose argument must consist of a list of pairs.v@x : 88_, _< ..<D := Transpose@xD

In[4]:=

The definition applies in this case.

v@88a1, b1<, 8a2, b2<, 8a3, b3<<D

In[5]:=Out[5]=

88a1, a2, a3<, 8b1, b2, b3<<

With this definition, the second elements of all the pairs must be the same.vn@x : 88_, n_< ..<D := Transpose@xD

In[6]:=

The definition applies in this case.

vn@88a, 2<, 8b, 2<, 8c, 2<<D

In[7]:=Out[7]=

88a, b, c<, 82, 2, 2<<

The pattern x .. can be extended to two arguments to control the number of repetitions moreprecisely.p .. or Repeated@pD

Out[8]= 8f@a, aD, f@a, a, aD<

an expression that must be matched verbatim

Verbatim patterns.Here the x_ in the rule matches any expression.In[1]:=Out[1]=

8f@2D, f@aD, f@x_D, f@y_D< . f@x_D -> x ^ 2

94, a2 , x_2 , y_2 =

The Verbatim tells Mathematica that only the exact expression x_ should be matched.In[2]:=Out[2]=

8f@2D, f@aD, f@x_D, f@y_D< . f@Verbatim@x_DD -> x ^ 2

9f@2D, f@aD, x2 , f@y_D=

Patterns for Some Common Types of Expression

Using the objects described above, you can set up patterns for many kinds of expressions. Inall cases, you must remember that the patterns must represent the structure of the expressionsin Mathematica internal form, as shown by FullForm.Especially for some common kinds of expressions, the standard output format used by Mathematica is not particularly close to the full internal form. But it is the internal form that you mustuse in setting up patterns.

102

Core Language

n _Integer

an integer n

x _Real

an approximate real number x

z _Complex

a complex number z

Complex@x _,y _D

a complex number x + i y

Complex@x _Integer,y _IntegerD

a complex number where both real and imaginary parts

are integers

Hr _Rational r _IntegerL

rational number or integer r

Rational@n _,d _D

a rational number

Hx _;NumberQ@xD&&Im@xD==0L

a real number of any kind

Hx _;NumberQ@xDL

a number of any kind

nd

Some typical patterns for numbers.

Here are the full forms of some numbers.In[1]:=

82, 2.5, 2.5 + I, 2 7< FullForm

Out[1]//FullForm=

List@2, 2.5`, Complex@2.5`, 1D, Rational@2, 7DD

The rule picks out each piece of the complex numbers.

In[2]:=Out[2]=

82.5 - I, 3 + I< . Complex@x_, y_D -> p@x, yD

8p@2.5, -1D, p@3, 1D<

The fact that these expressions have different full forms means that you cannot use x_ + I y_ tomatch a complex number.In[3]:=

82.5 - I, x + I y< FullForm

Out[3]//FullForm=

List@Complex@2.5`, -1D, Plus@x, Times@Complex@0, 1D, yDDD

The pattern here matches both ordinary integers, and complex numbers where both the realand imaginary parts are integers.In[4]:=Out[4]=

Cases@82.5 - I, 2, 3 + I, 2 - 0.5 I, 2 + 2 I<, _Integer

Complex@_Integer, _IntegerDD

82, 3 + , 2 + 2 <

As discussed in "Symbolic Computation", Mathematica puts all algebraic expressions into a

standard form, in which they are written essentially as a sum of products of powers. In addition, ratios are converted into products of powers, with denominator terms having negativeexponents, and differences are converted into sums with negated terms. To construct patternsfor algebraic expressions, you must use this standard form. This form often differs from theway Mathematica prints out the algebraic expressions. But in all cases, you can find the fullinternal form using FullForm@exprD.

Core Language

103

for algebraic expressions, you must use this standard form. This form often differs from theway Mathematica prints out the algebraic expressions. But in all cases, you can find the fullinternal form using FullForm@exprD.Here is a typical algebraic expression.In[5]:=Out[5]=

- 1 z ^ 2 - z y + 2 Hx zL ^ 2 y-

1z

+ 2 x2 y z 2

This is the full internal form of the expression.

In[6]:=

FullForm@%D

Out[6]//FullForm=

Plus@Times@-1, Power@z, -2DD,

Times@-1, Power@y, -1D, zD, Times@2, Power@x, 2D, y, Power@z, 2DDD

This is what you get by applying a transformation rule to all powers in the expression.In[7]:=

% . x_ ^ n_ -> e@x, nD

Out[7]= -z e@y, -1D - e@z, -2D + 2 y e@x, 2D e@z, 2D

x _+y _

a sum of two or more terms

x _+y _.

a single term or a sum of terms

n _Integer x_

an expression with an explicit integer multiplier

a _.+b _. x _

a linear expression a + b x

x _^n _

xn with n0, 1

x _^n _.

xn with n0

a _.+b _. x _+c _. x _^2

a quadratic expression with nonzero linear term

Some typical patterns for algebraic expressions.

This pattern picks out linear functions of x.In[8]:=Out[8]=

81, a, x, 2 x, 1 + 2 x< . a_. + b_. x -> p@a, bD

81, a, p@0, 1D, p@0, 2D, p@1, 2D<

104

Core Language

x_List

or

x:8___<

a list

x _List;VectorQ@xD

a vector containing no sublists

x _List;VectorQAx,NumberQE

a vector of numbers

x:8___List<

a list of lists

or

x:88___<...<

x _List;MatrixQ@xD

a matrix containing no sublists

x _List;MatrixQAx,NumberQE

a matrix of numbers

x:88_,_<...<

a list of pairs

Some typical patterns for lists.

This defines a function whose argument must be a list containing lists with either one or twoelements.In[9]:=

h@x : 8H8_<

8_, _<L ...<D := q

The definition applies in the second and third cases.

In[10]:=Out[10]=

8h@8a, b<D, h@88a<, 8b<<D, h@88a<, 8b, c<<D<

8h@8a, b<D, q, q<

An Example: Defining Your Own Integration Function

Now that we have introduced the basic features of patterns in Mathematica, we can use themto give a more or less complete example. We will show how you could define your own simpleintegration function in Mathematica.From a mathematical point of view, the integration function is defined by a sequence of mathematical relations. By setting up transformation rules for patterns, you can implement thesemathematical relations quite directly in Mathematica.

expr.8lhs1 ->rhs1 ,lhs2 ->rhs2 ,<

try a sequence of rules on each part of expr

Applying transformation rules.

You can give a list of rules to apply. Each rule will be tried once on each part of the expression.In[2]:=

x + y . 8x -> a, y -> b<

Out[2]= a + b

expr.8rules1 ,rules2 ,<

give a list of the results from applying each of the rulesi to

exprApplying lists of transformation rules.If you give a list of lists of rules, you get a list of results.In[3]:=

x + y . 88x -> 1, y -> 2<, 8x -> 4, y -> 2<<

Out[3]= 83, 6<

Functions such as Solve and NSolve return lists whose elements are lists of rules, eachrepresenting a solution.In[4]:=

Solve@x ^ 3 - 5 x ^ 2 + 2 x + 8 == 0, xD

Out[4]= 88x -1<, 8x 2<, 8x 4<<

When you apply these rules, you get a list of results, one corresponding to each solution.In[5]:=

x ^ 2 + 6 . %

Out[5]= 87, 10, 22<

When you use expr . rules, each rule is tried in turn on each part of expr. As soon as a ruleapplies, the appropriate transformation is made, and the resulting part is returned.

108

Core Language

When you use expr . rules, each rule is tried in turn on each part of expr. As soon as a ruleapplies, the appropriate transformation is made, and the resulting part is returned.The rule for x ^ 3 is tried first; if it does not apply, the rule for x ^ n_ is used.In[6]:=

8x ^ 2, x ^ 3, x ^ 4< . 8x ^ 3 -> u, x ^ n_ -> p@nD<

Out[6]= 8p@2D, u, p@4D<

A result is returned as soon as the rule has been applied, so the inner instance of h is notreplaced.In[7]:=

h@x + h@yDD . h@u_D -> u ^ 2

2Out[7]= Hx + h@yDL

The replacement expr . rules tries each rule just once on each part of expr.Since each rule is tried just once, this serves to swap x and y.In[8]:=

8x ^ 2, y ^ 3< . 8x -> y, y -> x<

23Out[8]= 9y , x =

You can use this notation to apply one set of rules, followed by another.In[9]:=

x ^ 2 . x -> H1 + yL . y -> b

2Out[9]= H1 + bL

Sometimes you may need to go on applying rules over and over again, until the expression youare working on no longer changes. You can do this using the repeated replacement operationexpr . rules (or ReplaceRepeated@expr, rulesD).

expr.rules

try rules once on each part of expr

expr.rules

try rules repeatedly until the result no longer changes

Single and repeated rule application.

With the single replacement operator . each rule is tried only once on each part of the expression.In[10]:=

x ^ 2 + y ^ 6 . 8x -> 2 + a, a -> 3<

26Out[10]= H2 + aL + y

Core Language

109

With the repeated replacement operator . the rules are tried repeatedly until the expressionno longer changes.In[11]:=

x ^ 2 + y ^ 6 . 8x -> 2 + a, a -> 3<

6Out[11]= 25 + y

Here the rule is applied only once.

In[12]:=

log@a b c dD . log@x_ y_D -> log@xD + log@yD

Out[12]= log@aD + log@b c dD

With the repeated replacement operator, the rule is applied repeatedly, until the result nolonger changes.In[13]:=

log@a b c dD . log@x_ y_D -> log@xD + log@yD

Out[13]= log@aD + log@bD + log@cD + log@dD

When you use . (pronounced slash-slash-dot), Mathematica repeatedly passes through

your expression, trying each of the rules given. It goes on doing this until it gets the sameresult on two successive passes.If you give a set of rules that is circular, then . can keep on getting different results forever.In practice, the maximum number of passes that . makes on a particular expression is determined by the setting for the option MaxIterations. If you want to keep going for as long aspossible, you can use ReplaceRepeated@expr, rules, MaxIterations -> InfinityD. You canalways stop by explicitly interrupting Mathematica.By setting the option MaxIterations , you can explicitly tell ReplaceRepeated how manytimes to try the rules you give.In[14]:=

ReplaceRepeated@x, x -> x + 1, MaxIterations -> 1000D

ReplaceRepeated::rrlim : Exiting after x scanned 1000 times.

Out[14]= 1000 + x

The replacement operators . and . share the feature that they try each rule on every subpart of your expression. On the other hand, Replace@expr, rulesD tries the rules only on thewhole of expr, and not on any of its subparts.You can use Replace, together with functions like Map and MapAt, to control exactly which partsof an expression a replacement is applied to. Remember that you can use the functionReplacePart @expr, new, posD to replace part of an expression with a specific object.The operator . applies rules to all subparts of an expression.

110

Core Language

The operator . applies rules to all subparts of an expression.

In[15]:=

x ^ 2 . x -> a

2Out[15]= a

Without a level specification, Replace applies rules only to the whole expression.In[16]:=

Replace@x ^ 2, x ^ 2 -> bD

Out[16]= b

No replacement is done here.

In[17]:=

Replace@x ^ 2, x -> aD

2Out[17]= x

This applies rules down to level 2, and so replaces x.

In[18]:=

Replace@x ^ 2, x -> a, 2D

2Out[18]= a

expr.rules

apply rules to all subparts of expr

Replace@expr,rulesD

apply rules to the whole of expr only

Replace@expr,rules,levspecD

apply rules to parts of expr on levels specified by levspec

Applying rules to whole expressions.

Replace returns the result from using the first rule that applies.In[19]:=

Replace@f@uD, 8f@x_D -> x ^ 2, f@x_D -> x ^ 3<D

2Out[19]= u

ReplaceList gives a list of the results from every rule that applies.In[20]:=

ReplaceList@f@uD, 8f@x_D -> x ^ 2, f@x_D -> x ^ 3<D

23Out[20]= 9u , u =

If a single rule can be applied in several ways, ReplaceList gives a list of all the results.In[21]:=

Out[23]= 8g@a, 8b, c<D, g@b, 8c, a, d<D, g@d, 8b<D<

Replace@expr,rulesD

apply rules in one way only

ReplaceList @expr,rulesD

apply rules in all possible ways

Applying rules in one way or all possible ways.

Manipulating Sets of Transformation Rules

You can manipulate lists of transformation rules in Mathematica just like other symbolic expressions. It is common to assign a name to a rule or set of rules.This assigns the name sinexp to the trigonometric expansion rule.In[1]:=Out[1]=

sinexp = Sin@2 x_D -> 2 Sin@xD Cos@xD

Sin@2 x_D 2 Cos@xD Sin@xD

You can now request the rule by name.

In[2]:=Out[2]=

Sin@2 H1 + xL ^ 2D . sinexp2 CosAH1 + xL2 E SinAH1 + xL2 E

You can use lists of rules to represent mathematical and other relations. Typically you will findit convenient to give names to the lists, so that you can easily specify the list you want in aparticular case.In most situations, it is only one rule from any given list that actually applies to a particularexpression. Nevertheless, the . operator tests each of the rules in the list in turn. If the list isvery long, this process can take a long time.Mathematica allows you to preprocess lists of rules so that . can operate more quickly onthem. You can take any list of rules and apply the function Dispatch to them. The result is arepresentation of the original list of rules, but including dispatch tables which allow . todispatch to potentially applicable rules immediately, rather than testing all the rules in turn.

112

Core Language

Mathematica allows you to preprocess lists of rules so that . can operate more quickly onthem. You can take any list of rules and apply the function Dispatch to them. The result is arepresentation of the original list of rules, but including dispatch tables which allow . todispatch to potentially applicable rules immediately, rather than testing all the rules in turn.Here is a list of rules for the first five factorials.In[3]:=Out[3]=

facs = Table@f@iD -> i !, 8i, 5<D

8f@1D 1, f@2D 2, f@3D 6, f@4D 24, f@5D 120<

This sets up dispatch tables that make the rules faster to use.In[4]:=

You can apply the rules using the . operator.

In[5]:=Out[5]=

f@4D . dfacs24

Dispatch@rulesD

create a representation of a list of rules that includes

dispatch tables

expr.drules

apply rules that include dispatch tables

Creating and using dispatch tables.

For long lists of rules, you will find that setting up dispatch tables makes replacement operations much faster. This is particularly true when your rules are for individual symbols or otherexpressions that do not involve pattern objects. Once you have built dispatch tables in suchcases, you will find that the . operator takes a time that is more or less independent of thenumber of rules you have. Without dispatch tables, however, . will take a time directly proportional to the total number of rules.

Making DefinitionsThe replacement operator . allows you to apply transformation rules to a specific expression.Often, however, you want to have transformation rules automatically applied whenever possible.You can do this by assigning explicit values to Mathematica expressions and patterns. Eachassignment specifies a transformation rule to be applied whenever an expression of the appropriate form occurs.

Core Language

113

You can do this by assigning explicit values to Mathematica expressions and patterns. Eachassignment specifies a transformation rule to be applied whenever an expression of the appropriate form occurs.

expr.lhs->rhs

apply a transformation rule to a specific expression

lhs=rhs

assign a value which defines a transformation rule to be

used whenever possible

Manual and automatic application of transformation rules.

This applies a transformation rule for x to a specific expression.In[1]:=Out[1]=

H1 + xL ^ 6 . x -> 3 - aH4 - aL6

By assigning a value to x, you tell Mathematica to apply a transformation rule for x wheneverpossible.In[2]:=Out[2]=

x = 3-a3-a

Now x is transformed automatically.

In[3]:=Out[3]=

H1 + xL ^ 7H4 - aL7

You should realize that except inside constructs like Module and Block, all assignments youmake in a Mathematica session are permanent. They continue to be used for the duration of thesession, unless you explicitly clear or overwrite them.The fact that assignments are permanent means that they must be made with care. Probablythe single most common mistake in using Mathematica is to make an assignment for a variablelike x at one point in your session, and then later to use x having forgotten about the assignment you made.There are several ways to avoid this kind of mistake. First, you should avoid using assignmentswhenever possible, and instead use more controlled constructs such as the . replacementoperator. Second, you should explicitly use the deassignment operator =. or the function Clearto remove values you have assigned when you have finished with them.Another important way to avoid mistakes is to think particularly carefully before assigningvalues to variables with common or simple names. You will often want to use a variable such asx as a symbolic parameter. But if you make an assignment such as x = 3, then x will bereplaced by 3 whenever it occurs, and you can no longer use x as a symbolic parameter.

114

Core Language

Another important way to avoid mistakes is to think particularly carefully before assigningvalues to variables with common or simple names. You will often want to use a variable such asx as a symbolic parameter. But if you make an assignment such as x = 3, then x will bereplaced by 3 whenever it occurs, and you can no longer use x as a symbolic parameter.In general, you should be sure not to assign permanent values to any variables that you mightwant to use for more than one purpose. If at one point in your session you wanted the variablec to stand for the speed of light, you might assign it a value such as 3. * 10 ^ 8. But then youcannot use c later in your session to stand, say, for an undetermined coefficient. One way toavoid this kind of problem is to make assignments only for variables with more explicit names,such as SpeedOfLight.

x=.

remove the value assigned to the object x

Clear@x,y,D

clear all the values of x, y,

Removing assignments.This does not give what you might expect, because x still has the value you assigned it above.In[4]:=Out[4]=

Factor@x ^ 2 - 1DH-4 + aL H-2 + aL

This removes any value assigned to x.

In[5]:=

Clear@xDNow this gives the result you expect.

In[6]:=Out[6]=

Factor@x ^ 2 - 1DH-1 + xL H1 + xL

Special Forms of Assignment

Particularly when you write procedural programs in Mathematica, you will often need to modifythe value of a particular variable repeatedly. You can always do this by constructing the newvalue and explicitly performing an assignment such as x = value. Mathematica, however, provides special notations for incrementing the values of variables, and for some other commoncases.

Core Language

i++

increment the value of i by 1

i--

decrement i

++i

pre-increment i

--i

pre-decrement i

i+=di

add di to the value of i

i-=di

subtract di from i

x*=c

multiply x by c

x=c

divide x by c

Modifying values of variables.

This assigns the value 7 x to the variable t.In[1]:=Out[1]=

t = 7x7x

This increments the value of t by 18 x.

In[2]:=Out[2]=

t += 18 x25 x

The value of t has been modified.

In[3]:=Out[3]=

t25 x

This sets t to 8, multiplies its value by 7, then gives the final value of t.In[4]:=Out[4]=

t = 8; t *= 7; t56

The value of i ++ is the value of i before the increment is done.

In[5]:=

i = 5; Print@i ++D; Print@iD

56

115

116

Core Language

The value of ++i is the value of i after the increment.

In[6]:=

i = 5; Print@++iD; Print@iD

66x=y=value

assign the same value to both x and y

8x,y<=8value1 ,value2 <

assign different values to x and y

8x,y<=8y,x<

interchange the values of x and y

Assigning values to several variables at a time.

This assigns the value 5 to x and 8 to y.In[7]:=Out[7]=

8x, y< = 85, 8<

85, 8<

This interchanges the values of x and y.

In[8]:=Out[8]=

8x, y< = 8y, x<

88, 5<

Now x has value 8.

In[9]:=

Out[9]= 8

And y has value 5.

In[10]:=Out[10]=

y5

You can use assignments to lists to permute values of variables in any way.In[11]:=Out[11]=

8a, b, c< = 81, 2, 3<; 8b, a, c< = 8a, c, b<; 8a, b, c<83, 1, 2<

When you write programs in Mathematica, you will sometimes find it convenient to take a list,and successively add elements to it. You can do this using the functions PrependTo andAppendTo.

Core Language

PrependTo@v,elemD

prepend elem to the value of v

AppendTo@v,elemD

append elem

v=8v,elem<

make a nested list containing elem

117

Assignments for modifying lists.

This assigns the value of v to be the list 85, 7, 9<.In[12]:=Out[12]=

v = 85, 7, 9<85, 7, 9<

This appends the element 11 to the value of v.

In[13]:=

AppendTo@v, 11D

Out[13]= 85, 7, 9, 11<

Now the value of v has been modified.

In[14]:=Out[14]=

v85, 7, 9, 11<

Although AppendTo@v, elemD is always equivalent to v = Append@v, elemD, it is often a convenient

notation. However, you should realize that because of the way Mathematica stores lists, it isusually less efficient to add a sequence of elements to a particular list than to create a nestedstructure that consists, for example, of lists of length 2 at each level. When you have built upsuch a structure, you can always reduce it to a single list using Flatten.This sets up a nested list structure for w.In[15]:=Out[15]=

w = 81<; Do@w = 8w, k ^ 2<, 8k, 1, 4<D; w

888881<, 1<, 4<, 9<, 16<

You can use Flatten to unravel the structure.

In[16]:=Out[16]=

Flatten@wD81, 1, 4, 9, 16<

118

Core Language

Making Definitions for Indexed Objects

In many kinds of calculations, you need to set up "arrays" which contain sequences of expressions, each specified by a certain index. One way to implement arrays in Mathematica is byusing lists. You can define a list, say a = 8x, y, z, <, then access its elements using a@@iDD, ormodify them using a@@iDD = value. This approach has a drawback, however, in that it requiresyou to fill in all the elements when you first create the list.Often, it is more convenient to set up arrays in which you can fill in only those elements thatyou need at a particular time. You can do this by making definitions for expressions such asa@iD.This defines a value for a@1D.In[1]:=

a@1D = 9

Out[1]= 9

This defines a value for a@2D.

In[2]:=

a@2D = 7

Out[2]= 7

This shows all the values you have defined for expressions associated with a so far.In[3]:=

?a

Global`aa@1D = 9a@2D = 7You can define a value for a@5D, even though you have not yet given values to a@3D and a@4D.In[4]:=

a@5D = 0

Out[4]= 0

This generates a list of the values of the a@iD.

In[5]:=

Table@a@iD, 8i, 5<D

Out[5]= 89, 7, a@3D, a@4D, 0<

You can think of the expression a@iD as being like an "indexed" or "subscripted" variable.

Core Language

119

You can think of the expression a@iD as being like an "indexed" or "subscripted" variable.

a@iD=value

add or overwrite a value

a@iD

access a value

a@iD=.

remove a value

?a

show all defined values

Clear@aD

clear all defined values

Table@a@iD,8i,1,n<Dor Array@a,nD

convert to an explicit List

Manipulating indexed variables.

When you have an expression of the form a@iD, there is no requirement that the "index" i be anumber. In fact, Mathematica allows the index to be any expression whatsoever. By usingindices that are symbols, you can for example build up simple databases in Mathematica.This defines the "object" area with "index" square to have value 1.In[6]:=

area@squareD = 1

Out[6]= 1

This adds another result to the area "database".

In[7]:=Out[7]=

area@triangleD = 1 212

Here are the entries in the area database so far.

In[8]:=

? area

Global`areaarea@squareD = 1area@triangleD =

12

You can use these definitions wherever you want. You have not yet assigned a value forarea@pentagonD.In[9]:=

4 area@squareD + area@pentagonD

Out[9]= 4 + area@pentagonD

Making Definitions for Functions

120

Core Language

Making Definitions for Functions

"Defining Functions" discusses how you can define functions in Mathematica. In a typical case,you would type in f@x_D = x ^ 2 to define a function f. (Actually, the definitions in "DefiningFunctions" use the := operator, rather than the = one. "Immediate and Delayed Definitions"explains exactly when to use each of the := and = operators.)The definition f@x_D = x ^ 2 specifies that whenever Mathematica encounters an expressionwhich matches the pattern f@x_D, it should replace the expression by x ^ 2. Since the patternf@x_D matches all expressions of the form f@anythingD, the definition applies to functions f withany "argument".Function definitions like f@x_D = x ^ 2 can be compared with definitions like f@aD = b for indexedvariables discussed in "Making Definitions for Indexed Objects". The definition f@aD = b specifiesthat whenever the particular expression f@aD occurs, it is to be replaced by b. But the definitionsays nothing about expressions such as f@yD, where f appears with another "index".To define a "function", you need to specify values for expressions of the form f@xD, where theargument x can be anything. You can do this by giving a definition for the pattern f@x_D, wherethe pattern object x_ stands for any expression.

f@xD=value

definition for a specific expression x

f@x _D=value

definition for any expression, referred to as x

The difference between defining an indexed variable and a function.

Making definitions for f@2D or f@aD can be thought of as being like giving values to variouselements of an "array" named f. Making a definition for f@x_D is like giving a value for a set of"array elements" with arbitrary "indices". In fact, you can actually think of any function asbeing like an array with an arbitrarily variable index.In mathematical terms, you can think of f as a mapping. When you define values for, say, f@1Dand f@2D, you specify the image of this mapping for various discrete points in its domain.Defining a value for f@x_D specifies the image of f on a continuum of points.

Core Language

121

This defines a transformation rule for the specific expression f@xD.

f@xD = u

In[1]:=Out[1]=

When the specific expression f@xD appears, it is replaced by u. Other expressions of the formf@argumentD are, however, not modified.f@xD + f@yD

In[2]:=Out[2]=

u + f@yD

This defines a value for f with any expression as an "argument".

f@x_D = x ^ 2

In[3]:=Out[3]=

x2

The old definition for the specific expression f@xD is still used, but the new general definitionfor f@x_D is now used to find a value for f@yD.f@xD + f@yD

In[4]:=Out[4]=

u + y2

This removes all definitions for f.

In[5]:=

Clear@fD

Mathematica allows you to define transformation rules for any expression or pattern. You canmix definitions for specific expressions such as f@1D or f@aD with definitions for patterns suchas f@x_D.Many kinds of mathematical functions can be set up by mixing specific and general definitionsin Mathematica. As an example, consider the factorial function. This particular function is in factbuilt into Mathematica (it is written n !). But you can use Mathematica definitions to set up thefunction for yourself.The standard mathematical definition for the factorial function can be entered almost directlyinto Mathematica, in the form: f@n_D := n f@n - 1D; f@1D = 1. This definition specifies that forany n, f@nD should be replaced by n f@n - 1D, except that when n is 1, f@1D should simply bereplaced by 1.

122

Core Language

Here is the value of the factorial function with argument 1.

In[6]:=Out[6]=

f@1D = 11

Here is the general recursion relation for the factorial function.

In[7]:=

f@n_D := n f@n - 1DNow you can use these definitions to find values for the factorial function.

In[8]:=Out[8]=

f@10D3 628 800

The results are the same as you get from the built-in version of factorial.In[9]:=Out[9]=

10 !3 628 800

The Ordering of Definitions

When you make a sequence of definitions in Mathematica, some may be more general thanothers. Mathematica follows the principle of trying to put more general definitions after morespecific ones. This means that special cases of rules are typically tried before more generalcases.This behavior is crucial to the factorial function example given in "Making Definitions for Functions". Regardless of the order in which you entered them, Mathematica will always put the rulefor the special case f@1D ahead of the rule for the general case f@n_D. This means that whenMathematica looks for the value of an expression of the form f@nD, it tries the special case f@1Dfirst, and only if this does not apply, it tries the general case f@n_D. As a result, when you askfor f@5D, Mathematica will keep on using the general rule until the end condition rule for f@1Dapplies. Mathematica tries to put specific definitions before more general definitions.Treatment of definitions in Mathematica.

If Mathematica did not follow the principle of putting special rules before more general ones,then the special rules would always be shadowed by more general ones. In the factorialexample, if the rule for f@n_D was ahead of the rule for f@1D, then even when Mathematicatried to evaluate f@1D, it would use the general f@n_D rule, and it would never find the special

Core Language

123

If Mathematica did not follow the principle of putting special rules before more general ones,then the special rules would always be shadowed by more general ones. In the factorialexample, if the rule for f@n_D was ahead of the rule for f@1D, then even when Mathematicatried to evaluate f@1D, it would use the general f@n_D rule, and it would never find the specialf@1D rule.Here is a general definition for f@n_D.In[1]:=

f@n_D := n f@n - 1DHere is a definition for the special case f@1D.

In[2]:=

f@1D = 1

Out[2]= 1

Mathematica puts the special case before the general one.

In[3]:=

?f

Global`ff@1D = 1f@n_D := n f@n - 1DIn the factorial function example used above, it is clear which rule is more general. Often,however, there is no definite ordering in generality of the rules you give. In such cases, Mathematica simply tries the rules in the order you give them.These rules have no definite ordering in generality.In[4]:=

log@x_ y_D := log@xD + log@yD; log@x_ ^ n_D := n log@xD

Mathematica stores the rules in the order you gave them.

In[5]:=

? log

Global`loglog@x_ y_D := log@xD + log@yDlog@x_n_ D := n log@xD

124

Core Language

This rule is a special case of the rule for log@x_ y_D.

In[6]:=

log@2 x_D := log@xD + log2

Mathematica puts the special rule before the more general one.

In[7]:=

? log

Global`loglog@2 x_D := log@xD + log2log@x_ y_D := log@xD + log@yDlog@x_n_ D := n log@xDAlthough in many practical cases, Mathematica can recognize when one rule is more generalthan another, you should realize that this is not always possible. For example, if two rules bothcontain complicated ; conditions, it may not be possible to work out which is more general,and, in fact, there may not be a definite ordering. Whenever the appropriate ordering is notclear, Mathematica stores rules in the order you give them.

Immediate and Delayed Definitions

You may have noticed that there are two different ways to make assignments in Mathematica:lhs = rhs and lhs := rhs. The basic difference between these forms is when the expression rhs isevaluated. lhs = rhs is an immediate assignment, in which rhs is evaluated at the time when theassignment is made. lhs := rhs, on the other hand, is a delayed assignment, in which rhs is notevaluated when the assignment is made, but is instead evaluated each time the value of lhs isrequested.lhs=rhs (immediate assignment)

rhs is evaluated when the assignment is made

lhs:=rhs (delayed assignment)

rhs is evaluated each time the value of lhs is requested

The two types of assignments in Mathematica.

This uses the := operator to define the function ex.In[1]:=

ex@x_D := Expand@H1 + xL ^ 2D

Core Language

125

Because := was used, the definition is maintained in an unevaluated form.

In[2]:=

? ex

Global`exex@x_D := ExpandAH1 + xL2 EWhen you make an assignment with the = operator, the right-hand side is evaluated immediately.In[3]:=Out[3]=

The definition now stored is the result of the Expand command.

iex simply substitutes its argument into the already expanded form, giving a different answer.In[6]:=Out[6]=

iex@y + 2D1 + 2 H2 + yL + H2 + yL2

As you can see from the example above, both = and := can be useful in defining functions, butthey have different meanings, and you must be careful about which one to use in a particularcase.One rule of thumb is the following. If you think of an assignment as giving the final value ofan expression, use the = operator. If instead you think of the assignment as specifying acommand for finding the value, use the := operator. If in doubt, it is usually better to use the:= operator than the = one.

126

Core Language

lhs=rhs

rhs is intended to be the final value of lhs (e.g.,

f @x_D = 1 - x ^ 2)

lhs:=rhs

rhs gives a command or program to be executed

Interpretations of assignments with the = and := operators.

Although := is probably used more often than = in defining functions, there is one importantcase in which you must use = to define a function. If you do a calculation, and get an answer interms of a symbolic parameter x, you often want to go on and find results for various specificvalues of x. One way to do this is to use the . operator to apply appropriate rules for x in eachcase. It is usually more convenient, however, to use = to define a function whose argument is x.Here is an expression involving x.In[7]:=

D@Log@Sin@xDD ^ 2, xD

Out[7]= 2 Cot@xD Log@Sin@xDD

This defines a function whose argument is the value to be taken for x.

In[8]:=Out[8]=

dlog@x_D = %2 Cot@xD Log@Sin@xDD

Here is the result when x is taken to be 1 + a.

In[9]:=Out[9]=

dlog@1 + aD2 Cot@1 + aD Log@Sin@1 + aDD

An important point to notice in the example above is that there is nothing special about thename x that appears in the x_ pattern. It is just a symbol, indistinguishable from an x thatappears in any other expression.

f @x _D=expr

define a function which gives the value expr for any particular value of x

Defining functions for evaluating expressions.

Core Language

127

You can use = and := not only to define functions, but also to assign values to variables. If youtype x = value, then value is immediately evaluated, and the result is assigned to x. On the otherhand, if you type x := value, then value is not immediately evaluated. Instead, it is maintained inan unevaluated form, and is evaluated afresh each time x is used.This evaluates RandomReal@D to find a pseudorandom number, then assigns this number tor1.In[10]:=Out[10]=

r1 = RandomReal@D0.0560708

Here RandomReal@D is maintained in an unevaluated form, to be evaluated afresh each time

r2 is used.In[11]:=

r2 := RandomReal@DHere are values for r1 and r2.

In[12]:=Out[12]=

8r1, r2<80.0560708, 0.6303<

The value of r1 never changes. Every time r2 is used, however, a new pseudorandom numberis generated.In[13]:=

8r1, r2<

Out[13]= 80.0560708, 0.359894<

The distinction between immediate and delayed assignments is particularly important when youset up chains of assignments.This defines a to be 1.In[14]:=

a=1

Out[14]= 1

Here a + 2 is evaluated to give 3, and the result is assigned to be the value of ri.In[15]:=Out[15]=

ri = a + 23

Here a + 2 is maintained in an unevaluated form, to be evaluated every time the value of rd is

requested.In[16]:=

rd := a + 2

128

Core Language

In this case, ri and rd give the same values.

In[17]:=Out[17]=

8ri, rd<83, 3<

Now the value of a is changed.

In[18]:=Out[18]=

a=22

Now rd uses the new value for a, while ri keeps its original value.In[19]:=Out[19]=

8ri, rd<83, 4<

You can use delayed assignments such as t := rhs to set up variables whose values you can findin a variety of different environments. Every time you ask for t, the expression rhs is evaluated using the current values of the objects on which it depends.The right-hand side of the delayed assignment is maintained in an unevaluated form.In[20]:=

t := 8a, Factor@x ^ a - 1D<

This sets a to 4, then finds the value of t.

In[21]:=Out[21]=

a = 4; t94, H-1 + xL H1 + xL I1 + x2 M=

Here a is 6.In[22]:=Out[22]=

a = 6; t96, H-1 + xL H1 + xL I1 - x + x2 M I1 + x + x2 M=

In the example above, the symbol a acts as a global variable, whose value affects the valueof t. When you have a large number of parameters, many of which change only occasionally,you may find this kind of setup convenient. However, you should realize that implicit or hiddendependence of one variable on others can often become quite confusing. When possible, youshould make all dependencies explicit, by defining functions which take all necessary parameters as arguments.

Core Language

lhs->rhs

rhs is evaluated when the rule is given

lhs:>rhs

rhs is evaluated when the rule is used

129

Two types of transformation rules in Mathematica.

Just as you can make immediate and delayed assignments in Mathematica, so you can also setup immediate and delayed transformation rules.The right-hand side of this rule is evaluated when you give the rule.In[23]:=Out[23]=

f@x_D -> Expand@H1 + xL ^ 2D

f@x_D 1 + 2 x + x2

A rule like this is probably not particularly useful.

In[24]:=Out[24]=

f@x_D -> Expand@xD

f@x_D x

Here the right-hand side of the rule is maintained in an unevaluated form, to be evaluatedevery time the rule is used.In[25]:=Out[25]=

f@x_D :> Expand@xD

f@x_D Expand@xD

Applying the rule causes the expansion to be done.

In[26]:=Out[26]=

f@H1 + pL ^ 2D . f@x_D :> Expand@xD

1 + 2 p + p2

In analogy with assignments, you should typically use -> when you want to replace an expression with a definite value, and you should use :> when you want to give a command for findingthe value.

Functions That Remember Values They Have Found

When you make a function definition using :=, the value of the function is recomputed everytime you ask for it. In some kinds of calculations, you may end up asking for the same functionvalue many times. You can save time in these cases by having Mathematica remember all thefunction values it finds. Here is an idiom for defining a function that does this.

130

Core Language

f@x _D:=f@xD=rhs

define a function which remembers values that it finds

Defining a function that remembers values it finds.

This defines a function f which stores all values that it finds.In[1]:=

You can see how a definition like f@x_D := f@xD = f@x - 1D + f@x - 2D works. The function f@x_Dis defined to be the program f@xD = f@x - 1D + f@x - 2D. When you ask for a value of thefunction

f,

the

program

is

executed.

The

program

first

calculates

the

value

of

f@x - 1D + f@x - 2D, then saves the result as f@xD.

It is often a good idea to use functions that remember values when you implement mathematical recursion relations in Mathematica. In a typical case, a recursion relation gives the value ofa function f with an integer argument x in terms of values of the same function with argumentsx - 1, x - 2, etc. The Fibonacci function definition f HxL = f Hx - 1L + f Hx - 2L used above is an exampleof this kind of recursion relation. The point is that if you calculate say f H10L by just applying therecursion relation over and over again, you end up having to recalculate quantities like f H5Lmany times. In a case like this, it is therefore better just to remember the value of f H5L, andlook it up when you need it, rather than having to recalculate it.There is of course a trade-off involved in remembering values. It is faster to find a particularvalue, but it takes more memory space to store all of them. You should usually define functionsto remember values only if the total number of different values that will be produced is comparatively small, or the expense of recomputing them is very great.

Associating Definitions with Different Symbols

132

Core Language

Associating Definitions with Different Symbols

When you make a definition in the form f @argsD = rhs or f @argsD := rhs, Mathematica associatesyour definition with the object f . This means, for example, that such definitions are displayedwhen you type ? f . In general, definitions for expressions in which the symbol f appears as thehead are termed downvalues of f .Mathematica however also supports upvalues, which allow definitions to be associated withsymbols that do not appear directly as their head.Consider for example a definition like Exp@g@x_DD := rhs. One possibility is that this definitioncould be associated with the symbol Exp, and considered as a downvalue of Exp. This is however probably not the best thing either from the point of view of organization or efficiency.Better is to consider Exp@g@x_DD := rhs to be associated with g, and to correspond to an upvalue of g.

f @argsD:=rhs

define a downvalue for f

f @g@argsD,D^:=rhs

define an upvalue for g

Associating definitions with different symbols.

This is taken to define a downvalue for f.In[1]:=

f@g@x_DD := fg@xDYou can see the definition when you ask about f.

In[2]:=

?f

Global`ff@g@x_DD := fg@xDThis defines an upvalue for g.In[3]:=

Exp@g@x_DD ^:= expg@xD

The definition is associated with g.

In[4]:=

?g

Core Language

133

Global`gg@x_D ^:= expg@xDIt is not associated with Exp.In[5]:=

?? Exp

Exp@zD is the exponential function.

Attributes@ExpD = 8Listable, NumericFunction, Protected, ReadProtectedThe definition is used to evaluate this expression.In[6]:=

Exp@g@5DD

Out[6]= expg@5D

In simple cases, you will get the same answers to calculations whether you give a definition forf @g@xDD as a downvalue for f or an upvalue for g. However, one of the two choices is usuallymuch more natural and efficient than the other.A good rule of thumb is that a definition for f @g@xDD should be given as an upvalue for g incases where the function f is more common than g. Thus, for example, in the case ofExp@g@xDD, Exp is a built-in Mathematica function, while g is presumably a function you haveadded. In such a case, you will typically think of definitions for Exp@g@xDD as giving relationssatisfied by g. As a result, it is more natural to treat the definitions as upvalues for g than asdownvalues for Exp.This gives the definition as an upvalue for g.In[7]:=

g : g@x_D + g@y_D := gplus@x, yD

Here are the definitions for g so far.

In[8]:=

?g

Global`gg@x_D ^:= expg@xDg@x_D + g@y_D ^:= gplus@x, yD

134

Core Language

The definition for a sum of gs is used whenever possible.

In[9]:=

g@5D + g@7D

Out[9]= gplus@5, 7D

Since the full form of the pattern g@x_D + g@y_D is Plus@g@x_D, g@y_DD, a definition for thispattern could be given as a downvalue for Plus. It is almost always better, however, to givethe definition as an upvalue for g.In general, whenever Mathematica encounters a particular function, it tries all the definitionsyou have given for that function. If you had made the definition for g@x_D + g@y_D a downvaluefor Plus, then Mathematica would have tried this definition whenever Plus occurs. The definition would thus be tested every time Mathematica added expressions together, making thisvery common operation slower in all cases.However, by giving a definition for g@x_D + g@y_D as an upvalue for g, you associate the definition with g. In this case, Mathematica only tries the definition when it finds a g inside a functionsuch as Plus. Since g presumably occurs much less frequently than Plus, this is a much moreefficient procedure.f @gD^=value or

f @g@argsDD^=valuemake assignments to be associated with g, rather than f

f @gD^:=value or

f @g@argsDD^:=valuemake delayed assignments associated with g

f @arg1 ,arg2 ,D^=value

make assignments associated with the heads of all the argi

Shorter ways to define upvalues.

A typical use of upvalues is in setting up a "database" of properties of a particular object. With

upvalues, you can associate each definition you make with the object that it concerns, ratherthan with the property you are specifying.This defines an upvalue for square which gives its area.In[10]:=

area@squareD ^= 1

Out[10]= 1

Core Language

135

This adds a definition for the perimeter.

In[11]:=

perimeter@squareD ^= 4

Out[11]= 4

Both definitions are now associated with the object square.

In[12]:=

? square

Global`squarearea@squareD ^= 1perimeter@squareD ^= 4In general, you can associate definitions for an expression with any symbol that occurs at asufficiently high level in the expression. With an expression of the form f @argsD, you can definean upvalue for a symbol g so long as either g itself, or an object with head g, occurs in args. If goccurs at a lower level in an expression, however, you cannot associate definitions with it.g occurs as the head of an argument, so you can associate a definition with it.In[13]:=

g : h@w@x_D, g@y_DD := hwg@x, yD

Here g appears too deep in the left-hand side for you to associate a definition with it.

In[14]:=

g : h@w@g@x_DD, y_D := hw@x, yD

TagSetDelayed::tagpos : Tag g in h@w@g@x_DD, y_D is too deep for an assigned rule to be found.

Out[14]= $Failed

f @D:=rhs

downvalue for f

f : f @g@DD@D:=rhs

downvalue for f

g: f @,g,D:=rhs

upvalue for g

g: f @,g@D,D:=rhs

upvalue for g

Possible positions for symbols in definitions.

As discussed in "The Meaning of Expressions", you can use Mathematica symbols as "tags", toindicate the "type" of an expression. For example, complex numbers in Mathematica are represented internally in the form Complex@x, yD, where the symbol Complex serves as a tag toindicate that the object is a complex number.Upvalues provide a convenient mechanism for specifying how operations act on objects that aretagged to have a certain type. For example, you might want to introduce a class of abstractmathematical objects of type quat. You can represent each object of this type by a Mathemat-

136

Core Language

Upvalues provide a convenient mechanism for specifying how operations act on objects that aretagged to have a certain type. For example, you might want to introduce a class of abstractmathematical objects of type quat. You can represent each object of this type by a Mathematica expression of the form quat@dataD.In a typical case, you might want quat objects to have special properties with respect to arithmetic operations such as addition and multiplication. You can set up such properties by definingupvalues for quat with respect to Plus and Times.This defines an upvalue for quat with respect to Plus .In[15]:=

quat@x_D + quat@y_D ^:= quat@x + yD

The upvalue you have defined is used to simplify this expression.

In[16]:=

quat@aD + quat@bD + quat@cD

Out[16]= quat@a + b + cD

When you define an upvalue for quat with respect to an operation like Plus, what you areeffectively doing is to extend the domain of the Plus operation to include quat objects. You aretelling Mathematica to use special rules for addition in the case where the things to be addedtogether are quat objects.In defining addition for quat objects, you could always have a special addition operation, sayquatPlus, to which you assign an appropriate downvalue. It is usually much more convenient,however, to use the standard Mathematica Plus operation to represent addition, but then to"overload" this operation by specifying special behavior when quat objects are encountered.You can think of upvalues as a way to implement certain aspects of object-oriented programming. A symbol like quat represents a particular type of object. Then the various upvalues forquat specify "methods" that define how quat objects should behave under certain operations,or on receipt of certain "messages".

Defining Numerical Values

If you make a definition such as f@x_D := value, Mathematica will use the value you give for anyf function it encounters. In some cases, however, you may want to define a value that is to beused specifically when you ask for numerical values.

Core Language

expr=value

define a value to be used whenever possible

N@exprD=value

define a value to be used for numerical approximation

137

Defining ordinary and numerical values.

This defines a numerical value for the function f.In[1]:=

N@f@x_DD := Sum@x ^ - i i ^ 2, 8i, 20<D

Defining the numerical value does not tell Mathematica anything about the ordinary value of f.

In[2]:=Out[2]=

f@2D + f@5Df@2D + f@5D

If you ask for a numerical approximation, however, Mathematica uses the numerical values youhave defined.In[3]:=Out[3]=

N@%D0.793244

You can define numerical values for both functions and symbols. The numerical values are usedby all numerical Mathematica functions, including NIntegrate, FindRoot and so on.

N@exprD=value

define a numerical value to be used when default numerical precision is requested

NAexpr,9n,Infinity=E=value

define a numerical value to be used when n-digit precision

and any accuracy is requested

Defining numerical values that depend on numerical precision.

This defines a numerical value for the symbol const, using 4 n + 5 terms in the product for ndigit precision.In[4]:=

N@const, 8n_, Infinity<D := Product@1 - 2 ^ - i, 8i, 2, 4 n + 5<D

Here is the value of const, computed to 30-digit precision using the value you specified.

Modifying Built-in Functions

138

Core Language

Modifying Built-in Functions

Mathematica allows you to define transformation rules for any expression. You can define suchrules not only for functions that you add to Mathematica, but also for intrinsic functions that arealready built into Mathematica. As a result, you can enhance, or modify, the features of built-inMathematica functions.This capability is powerful, but potentially dangerous. Mathematica will always follow the rulesyou give it. This means that if the rules you give are incorrect, then Mathematica will give youincorrect answers.To avoid the possibility of changing built-in functions by mistake, Mathematica protects allbuilt-in functions from redefinition. If you want to give a definition for a built-in function, youhave to remove the protection first. After you give the definition, you should usually restore theprotection, to prevent future mistakes.

Unprotect@ f D

remove protection

Protect@ f D

add protection

Protection for functions.

Built-in functions are usually protected, so you cannot redefine them.In[1]:=

Log@7D = 2Set::write : Tag Log in Log@7D is Protected.

Out[1]= 2

This removes protection for Log.

In[2]:=

Unprotect@LogD

Out[2]= 8Log<

Now you can give your own definitions for Log. This particular definition is not mathematicallycorrect, but Mathematica will still allow you to give it.In[3]:=

Log@7D = 2

Out[3]= 2

Core Language

139

Mathematica will use your definitions whenever it can, whether they are mathematically corrector not.In[4]:=

Log@7D + Log@3D

Out[4]= 2 + Log@3D

This removes the incorrect definition for Log.

In[5]:=

Log@7D =.This restores the protection for Log.

In[6]:=

Protect@LogD

Out[6]= 8Log<

Definitions you give can override built-in features of Mathematica. In general, Mathematica triesto use your definitions before it uses built-in definitions.The rules that are built into Mathematica are intended to be appropriate for the broadest rangeof calculations. In specific cases, however, you may not like what the built-in rules do. In suchcases, you can give your own rules to override the ones that are built in.There is a built-in rule for simplifying Exp@Log@exprDD.In[7]:=

Exp@Log@yDD

Out[7]= y

You can give your own rule for Exp@Log@exprDD, overriding the built-in rule.In[8]:=

HUnprotect@ExpD; Exp@Log@expr_DD := explog@exprD; Protect@ExpD;L

Now your rule is used, rather than the built-in one.

In[9]:=

Exp@Log@yDD

Out[9]= explog@yD

140

Core Language

Manipulating Value Lists

DownValues@ f D

give the list of downvalues of f

UpValues@ f D

give the list of upvalues of f

DownValues@ f D=rules

set the downvalues of f

UpValues@ f D=rules

set the upvalues of f

Finding and setting values of symbols.

Mathematica effectively stores all definitions you give as lists of transformation rules. When aparticular symbol is encountered, the lists of rules associated with it are tried.Under most circumstances, you do not need direct access to the actual transformation rulesassociated with definitions you have given. Instead, you can simply use lhs = rhs and lhs =. toadd and remove rules. In some cases, however, you may find it useful to have direct access tothe actual rules.Here is a definition for f.In[1]:=

f@x_D := x ^ 2This gives the explicit rule corresponding to the definition you made for f.

In[2]:=Out[2]=

DownValues@fD9HoldPattern@f@x_DD x2 =

Notice that the rules returned by DownValues and UpValues are set up so that neither theirleft- nor right-hand sides get evaluated. The left-hand sides are wrapped in HoldPattern , andthe rules are delayed, so that the right-hand sides are not immediately evaluated.As discussed in "Making Definitions for Functions", Mathematica tries to order definitions so thatmore specific ones appear before more general ones. In general, however, there is no uniqueway to make this ordering, and you may want to choose a different ordering from the one thatMathematica chooses by default. You can do this by reordering the list of rules obtained fromDownValues or UpValues.Here are some definitions for the object g.In[3]:=

This reverses the order of the definitions for g.

Functions and Programs

Defining FunctionsThere are many functions that are built into Mathematica. This tutorial discusses how you canadd your own simple functions to Mathematica.As a first example, consider adding a function called f which squares its argument. The Mathematica command to define this function is f@x_D := x ^ 2. The _ (referred to as "blank") on theleft-hand side is very important; what it means will be discussed below. For now, just remember to put a _ on the left-hand side, but not on the right-hand side, of your definition.This defines the function f. Notice the _ on the left-hand side.In[1]:=

f@x_D := x ^ 2

f squares its argument.

In[2]:=

f@a + 1D

2Out[2]= H1 + aL

The argument can be a number.

In[3]:=

f@4D

Out[3]= 16

Or it can be a more complicated expression.

In[4]:=

f@3 x + x ^ 2D

2Out[4]= I3 x + x M

You can use f in a calculation.

In[5]:=

Expand@f@Hx + 1 + yLDD

22Out[5]= 1 + 2 x + x + 2 y + 2 x y + y

This shows the definition you made for f.

In[6]:=

?f

Core Language

143

Global`ff@x_D := x2f@x_D:=x^2

define the function f

?f

show the definition of f

Clear@fD

clear all definitions for f

Defining a function in Mathematica.

The names like f that you use for functions in Mathematica are just symbols. Because of this,you should make sure to avoid using names that begin with capital letters, to prevent confusionwith built-in Mathematica functions. You should also make sure that you have not used thenames for anything else earlier in your session.Mathematica functions can have any number of arguments.In[7]:=

hump@x_, xmax_D := Hx - xmaxL ^ 2 xmax

You can use the hump function just as you would any of the built-in functions.

In[8]:=

2 + hump@x, 3.5D

2Out[8]= 2 + 0.285714 H-3.5 + xL

This gives a new definition for hump, which overwrites the previous one.In[9]:=

hump@x_, xmax_D := Hx - xmaxL ^ 4

When you have finished with a particular function, it is always a good idea to clear definitionsyou have made for it. If you do not do this, then you will run into trouble if you try to use thesame function for a different purpose later in your Mathematica session. You can clear all definitions you have made for a function or symbol f by using Clear@ f D.

Functions as ProceduresIn many kinds of calculations, you may find yourself typing the same input to Mathematica overand over again. You can save yourself a lot of typing by defining a function that contains yourinput commands.This constructs a product of three terms, and expands out the result.In[1]:=Out[1]=

Expand@Product@x + i, 8i, 3<DD

6 + 11 x + 6 x2 + x3

This does the same thing, but with four terms.

In[2]:=Out[2]=

Expand@Product@x + i, 8i, 4<DD

24 + 50 x + 35 x2 + 10 x3 + x4

This defines a function exprod which constructs a product of n terms, then expands it out.In[3]:=

exprod@n_D := Expand@Product@x + i, 8i, 1, n<DD

Every time you use the function, it will execute the Product and Expand operations.

In[4]:=Out[4]=

exprod@5D120 + 274 x + 225 x2 + 85 x3 + 15 x4 + x5

The functions you define in Mathematica are essentially procedures that execute the commandsyou give. You can have several steps in your procedures, separated by semicolons.The result you get from the whole function is simply the last expression in the procedure. Noticethat you have to put parentheses around the procedure when you define it like this.In[5]:=

cex@n_, i_D := Ht = exprod@nD; Coefficient@t, x ^ iDL

This runs the procedure.

In[6]:=Out[6]=

cex@5, 3D85

Core Language

expr1 ;expr2 ;

a sequence of expressions to evaluate

Module@8a,b,<,procD

a procedure with local variables a, b,

145

Constructing procedures.

When you write procedures in Mathematica, it is usually a good idea to make variables you useinside the procedures local, so that they do not interfere with things outside the procedures.You can do this by setting up your procedures as modules, in which you give a list of variablesto be treated as local.The function cex defined above is not a module, so the value of t escapes, and exists evenafter the function returns.In[7]:=Out[7]=

t120 + 274 x + 225 x2 + 85 x3 + 15 x4 + x5

This function is defined as a module with local variable u.

In[8]:=

ncex@n_, i_D := Module@8u<, u = exprod@nD; Coefficient@u, x ^ iDD

The function gives the same result as before.

In[9]:=Out[9]=

ncex@5, 3D85

Now, however, the value of u does not escape from the function.In[10]:=Out[10]=

uu

Manipulating OptionsThere are a number of functions built into Mathematica which, like Plot, have various optionsyou can set. Mathematica provides some general mechanisms for handling such options.If you do not give a specific setting for an option to a function like Plot, then Mathematica willautomatically use a default value for the option. The function Options@ function, optionD allowsyou to find out the default value for a particular option. You can reset the default usingSetOptions@ function, option -> valueD. Note that if you do this, the default value you have givenwill stay until you explicitly change it.

146

Core Language

Options@ functionD

give a list of the current default settings for all options

Options@ function,optionD

give the default setting for a particular option

SetOptions@ function,option->value,D

reset defaults

Manipulating default settings for options.

Here is the default setting for the PlotRange option of Plot .In[1]:=

Options@Plot, PlotRangeD

Out[1]= 8PlotRange 8Full, Automatic<<

This resets the default for the PlotRange option. The semicolon stops Mathematica fromprinting out the rather long list of options for Plot .In[2]:=

SetOptions@Plot, PlotRange -> AllD;

Until you explicitly reset it, the default for the PlotRange option will now be All.

In[3]:=

Options@Plot, PlotRangeD

Out[3]= 8PlotRange All<

The graphics objects that you get from Plot or Show store information on the options they use.You can get this information by applying the Options function to these graphics objects.

Options@plotD

show all the options used for a particular plot

Options@plot,optionD

show the setting for a specific option

AbsoluteOptions@plot,optionD

show the absolute form used for a specific option, even if

the setting for the option is Automatic or All

Getting information on options used in plots.

Here is a plot, with default settings for all options.In[4]:=

Out[4]=

g = Plot@SinIntegral@xD, 8x, 0, 20<D

Core Language

147

The setting used for the PlotRange option was All.

In[5]:=

Options@g, PlotRangeD

Out[5]= 8PlotRange 8All, All<<

AbsoluteOptions gives the absolute automatically chosen values used for PlotRange.In[6]:=

AbsoluteOptions@g, PlotRangeD

-7-7Out[6]= 9PlotRange 994.08163 10 , 20.=, 94.08163 10 , 1.85194===

While it is often convenient to use a variable to represent a graphic as in the above examples,the graphic itself can be evaluated directly. The typical ways to do this in the notebook interfaceare to copy and paste the graphic or to simply begin typing in the graphical output cell, atwhich point the output cell will be converted into a new input cell.When a plot created with no explicit ImageSize is placed into an input cell, it will automaticallyshrink to more easily accommodate input.The following input cell was created by copying and pasting the graphical output created in theprevious example.In[7]:=

AbsoluteOptionsB

1.5

1.0, PlotRangeF

0.5

10

15

-7-7Out[7]= 9PlotRange 994.08163 10 , 20.=, 94.08163 10 , 1.85194===

20

148

Core Language

Repetitive OperationsIn using Mathematica, you sometimes need to repeat an operation many times. There aremany ways to do this. Often the most natural is in fact to set up a structure such as a list withmany elements, and then apply your operation to each of the elements.Another approach is to use the Mathematica function Do, which works much like the iterationconstructs in languages such as C and Fortran. Do uses the same Mathematica iterator notationas Sum and Product, described in "Sums and Products".

Do@expr,8i,imax <D

evaluate expr with i running from 1 to imax

Do@expr,8i,imin ,imax ,di<D

evaluate expr with i running from imin to imax in steps of di

Print@exprD

print expr

Table@expr,8i,imax <D

make a list of the values of expr with i running from 1 to

imax

Implementing repetitive operations.

This prints out the values of the first five factorials.In[1]:=

Do@Print@i !D, 8i, 5<D

12624120It is often more useful to have a list of results, which you can then manipulate further.In[2]:=Out[2]=

Table@i !, 8i, 5<D

81, 2, 6, 24, 120<

If you do not give an iteration variable, Mathematica simply repeats the operation you havespecified, without changing anything.In[3]:=Out[3]=

r = 1; Do@r = 1 H1 + rL, 8100<D; r

573 147 844 013 817 084 101927 372 692 193 078 999 176

Transformation Rules for Functions

Core Language

149

Transformation Rules for Functions

"Values for Symbols" discussed how you can use transformation rules of the form x -> value toreplace symbols by values. The notion of transformation rules in Mathematica is, however, quitegeneral. You can set up transformation rules not only for symbols, but for any Mathematicaexpression.Applying the transformation rule x -> 3 replaces x by 3.In[1]:=Out[1]=

1 + f@xD + f@yD . x -> 3

1 + f@3D + f@yD

You can also use a transformation rule for f@xD. This rule does not affect f@yD.In[2]:=

1 + f@xD + f@yD . f@xD -> p

Out[2]= 1 + p + f@yD

f@t_D is a pattern that stands for f with any argument.

In[3]:=Out[3]=

1 + f@xD + f@yD . f@t_D -> t ^ 2

1 + x2 + y2

Probably the most powerful aspect of transformation rules in Mathematica is that they caninvolve not only literal expressions, but also patterns. A pattern is an expression such as f@t_Dwhich contains a blank (underscore). The blank can stand for any expression. Thus, a transformation rule for f@t_D specifies how the function f with any argument should be transformed.Notice that, in contrast, a transformation rule for f@xD without a blank, specifies only how theliteral expression f@xD should be transformed, and does not, for example, say anything aboutthe transformation of f@yD.When you give a function definition such as f@t_D := t ^ 2, all you are doing is telling Mathematica to automatically apply the transformation rule f@t_D -> t ^ 2 whenever possible.You can set up transformation rules for expressions of any form.In[4]:=Out[4]=

f@a bD + f@c dD . f@x_ y_D -> f@xD + f@yD

f@aD + f@bD + f@cD + f@dD

150

Core Language

This uses a transformation rule for x ^ p_.

In[5]:=Out[5]=

1 + x ^ 2 + x ^ 4 . x ^ p_ -> f@pD1 + f@2D + f@4D

"Patterns" and "Transformation Rules and Definitions" will explain in detail how to set up patterns and transformation rules for any kind of expression. Suffice it to say here that in Mathematica all expressions have a definite symbolic structure; transformation rules allow you totransform parts of that structure.

Core Language

151

Functional OperationsFunction Names as ExpressionsIn an expression like f @xD, the function name f is itself an expression, and you can treat it asyou would any other expression.You can replace names of functions using transformation rules.In[1]:=

f@xD + f@1 - xD . f -> g

Out[1]= g@1 - xD + g@xD

Any assignments you have made are used on function names.

In[2]:=Out[2]=

p1 = p2; p1@x, yDp2@x, yD

This defines a function which takes a function name as an argument.

In[3]:=

pf@f_, x_D := f@xD + f@1 - xD

This gives Log as the function name to use.

In[4]:=Out[4]=

pf@Log, qDLog@1 - qD + Log@qD

The ability to treat the names of functions just like other kinds of expressions is an importantconsequence of the symbolic nature of the Mathematica language. It makes possible the wholerange of functional operations.Ordinary Mathematica functions such as Log or Integrate typically operate on data such asnumbers and algebraic expressions. Mathematica functions that represent functional operations, however, can operate not only on ordinary data, but also on functions themselves. Thus,for example, the functional operation InverseFunction takes a Mathematica function name asan argument, and represents the inverse of that function.

152

Core Language

InverseFunction is a functional operation: it takes a Mathematica function as an argument,

and returns another function which represents its inverse.In[5]:=Out[5]=

InverseFunction@ArcSinDSin

The result obtained from InverseFunction is a function which you can apply to data.In[6]:=Out[6]=

%@xDSin@xD

You can also use InverseFunction in a purely symbolic way.

In[7]:=Out[7]=

InverseFunction@fD@xDfH-1L @xD

There are many kinds of functional operations in Mathematica. Some represent mathematicaloperations; others represent various kinds of procedures and algorithms.Unless you are familiar with advanced symbolic languages, you will probably not recognizemost of the functional operations discussed. At first, the operations may seem difficult to understand. But it is worth persisting. Functional operations provide one of the most conceptually andpractically efficient ways to use Mathematica.

Applying Functions Repeatedly

Many programs you write will involve operations that need to be iterated several times. Nestand NestList are powerful constructs for doing this.

Nest@ f ,x,nD

apply the function f nested n times to x

NestList@ f ,x,nD

generate the list 8x, f @xD, f @ f @xDD, <, where f is nested up

to n deep

Applying functions of one argument repeatedly.

Nest@ f , x, nD takes the name f of a function, and applies the function n times to x.In[1]:=Out[1]=

Nest@f, x, 4Df@f@f@f@xDDDD

Core Language

153

This makes a list of each successive nesting.

In[2]:=Out[2]=

NestList@f, x, 4D8x, f@xD, f@f@xDD, f@f@f@xDDD, f@f@f@f@xDDDD<

Here is a simple function.

In[3]:=

recip@x_D := 1 H1 + xLYou can iterate the function using Nest .

In[4]:=

Nest@recip, x, 3D1

Out[4]=

1+

11+

11+x

Nest and NestList allow you to apply functions a fixed number of times. Often you may wantto apply functions until the result no longer changes. You can do this using FixedPoint andFixedPointList.

NestWhile@ f ,x,test,mD , NestWhileList@ f ,x,test,mD

NestWhileA f ,x,test,AllE , NestWhileListA f ,x,test,AllE

supply all results so far as arguments for testApplying functions repeatedly until a test fails.Here is a function which divides a number by 2.In[9]:=

divide2@n_D := n 2This repeatedly applies divide2 until the result is no longer an even number.

In[10]:=Out[10]=

NestWhileList@divide2, 123 456, EvenQD

8123 456, 61 728, 30 864, 15 432, 7716, 3858, 1929<

This repeatedly applies newton3, stopping when two successive results are no longer considered unequal, just as in FixedPointList.In[11]:=Out[11]=

NestWhileList@newton3, 1.0, Unequal, 2D

81., 2., 1.75, 1.73214, 1.73205, 1.73205, 1.73205<

This goes on until the first time a result that has been seen before reappears.In[12]:=Out[12]=

NestWhileList@Mod@5 , 7D &, 1, Unequal, AllD

81, 5, 4, 6, 2, 3, 1<

Operations such as Nest take a function f of one argument, and apply it repeatedly. At eachstep, they use the result of the previous step as the new argument of f .It is important to generalize this notion to functions of two arguments. You can again apply thefunction repeatedly, but now each result you get supplies only one of the new arguments youneed. A convenient approach is to get the other argument at each step from the successiveelements of a list.

Core Language

155

It is important to generalize this notion to functions of two arguments. You can again apply thefunction repeatedly, but now each result you get supplies only one of the new arguments youneed. A convenient approach is to get the other argument at each step from the successiveelements of a list.

FoldList@ f ,x,8a,b,<D

create the list 8x, f @x, aD, f @ f @x, aD, bD, <

Fold@ f ,x,8a,b,<D

give the last element of the list produced by

FoldList@ f , x, 8a, b, <D

Ways to repeatedly apply functions of two arguments.Here is an example of what FoldList does.In[13]:=Out[13]=

FoldList@f, x, 8a, b, c<D

8x, f@x, aD, f@f@x, aD, bD, f@f@f@x, aD, bD, cD<

Fold gives the last element of the list produced by FoldList .

In[14]:=Out[14]=

Fold@f, x, 8a, b, c<D

f@f@f@x, aD, bD, cD

This gives a list of cumulative sums.

In[15]:=

FoldList@Plus, 0, 8a, b, c<D

Out[15]= 80, a, a + b, a + b + c<

Using Fold and FoldList you can write many elegant and efficient programs in Mathematica.In some cases, you may find it helpful to think of Fold and FoldList as producing a simplenesting of a family of functions indexed by their second argument.This defines a function nextdigit.In[16]:=

nextdigit@a_, b_D := 10 a + bThis is now like the built-in function FromDigits .

In[17]:=

fromdigits@digits_D := Fold@nextdigit, 0, digitsD

Here is an example of the function in action.

In[18]:=Out[18]=

fromdigits@81, 3, 7, 2, 9, 1<D137 291

Applying Functions to Lists and Other Expressions

156

Core Language

Applying Functions to Lists and Other Expressions

In an expression like f@8a, b, c<D you are giving a list as the argument to a function. Oftenyou need instead to apply a function directly to the elements of a list, rather than to the list asa whole. You can do this in Mathematica using Apply.This makes each element of the list an argument of the function f.In[1]:=

Apply@f, 8a, b, c<D

Out[1]= f@a, b, cD

This gives Times@a, b, cD which yields the product of the elements in the list.In[2]:=

Apply@Times, 8a, b, c<D

Out[2]= a b c

Here is a definition of a function that works like the built-in function GeometricMean , writtenusing Apply .In[3]:=

geom@list_D := Apply@Times, listD ^ H1 Length@listDL

apply f to a list, giving f @a, b, D

Apply@ f ,8a,b,<DApply@ f ,exprD

or

Apply@ f ,expr,81<D

f expr

apply f to the top level of an expression

or

apply f at the first level in an expression

f expr

Apply@ f ,expr,levD

apply f at the specified levels in an expression

Applying functions to lists and other expressions.

What Apply does in general is to replace the head of an expression with the function youspecify. Here it replaces Plus by List .In[4]:=Out[4]=

Apply@List, a + b + cD8a, b, c<

Here is a matrix.In[5]:=Out[5]=

m = 88a, b, c<, 8b, c, d<<

88a, b, c<, 8b, c, d<<

Core Language

157

Using Apply without an explicit level specification replaces the top-level list with f.In[6]:=Out[6]=

Apply@f, mDf@8a, b, c<, 8b, c, d<D

This applies f only to parts of m at level 1.

In[7]:=Out[7]=

Apply@f, m, 81<D8f@a, b, cD, f@b, c, dD<

This applies f at levels 0 through 1.

In[8]:=Out[8]=

Apply@f, m, 80, 1<D

f@f@a, b, cD, f@b, c, dDD

Applying Functions to Parts of Expressions

If you have a list of elements, it is often important to be able to apply a function separately toeach of the elements. You can do this in Mathematica using Map.This applies f separately to each element in a list.In[1]:=Out[1]=

Map@f, 8a, b, c<D

8f@aD, f@bD, f@cD<

This defines a function which takes the first two elements from a list.In[2]:=

take2@list_D := Take@list, 2DYou can use Map to apply take2 to each element of a list.

In[3]:=Out[3]=

Map@take2, 881, 3, 4<, 85, 6, 7<, 82, 1, 6, 6<<D

881, 3<, 85, 6<, 82, 1<<

Map@ f ,8a,b,<D

apply f to each element in a list, giving 8 f @aD, f @bD, <

Applying a function to each element in a list.

What Map@ f , exprD effectively does is to wrap the function f around each element of theexpression expr. You can use Map on any expression, not just a list.

158

Core Language

This applies f to each element in the sum.

In[4]:=Out[4]=

Map@f, a + b + cDf@aD + f@bD + f@cD

This applies Sqrt to each argument of g.

In[5]:=Out[5]=

Map@Sqrt, g@x ^ 2, x ^ 3DD

gB

x2 ,

x3 F

Map@ f , exprD applies f to the first level of parts in expr. You can use MapAll@ f , exprD to apply fto all the parts of expr.This defines a 2x2 matrix m.In[6]:=Out[6]=

m = 88a, b<, 8c, d<<

88a, b<, 8c, d<<

Map applies f to the first level of m, in this case the rows of the matrix.In[7]:=Out[7]=

Map@f, mD8f@8a, b<D, f@8c, d<D<

MapAll applies f at all levels in m. If you look carefully at this expression, you will see an fwrapped around every part.In[8]:=Out[8]=

MapAll@f, mDf@8f@8f@aD, f@bD<D, f@8f@cD, f@dD<D<D

In general, you can use level specifications as described in "Levels in Expressions" to tell Map towhich parts of an expression to apply your function.This applies f only to the parts of m at level 2.In[9]:=Out[9]=

Map@f, m, 82<D88f@aD, f@bD<, 8f@cD, f@dD<<

Setting the option Heads -> True wraps f around the head of each part, as well as its elements.In[10]:=Out[10]=

Map@f, m, Heads -> TrueD

f@ListD@f@8a, b<D, f@8c, d<DD

Core Language

Map@ f ,exprD or f expr

apply f to the first-level parts of expr

MapAll@ f ,exprD or f expr

apply f to all parts of expr

Map@ f ,expr,levD

apply f to each part of expr at levels specified by lev

159

Ways to apply a function to different parts of expressions.

Level specifications allow you to tell Map to which levels of parts in an expression you want afunction applied. With MapAt, however, you can instead give an explicit list of parts where youwant a function applied. You specify each part by giving its indices, as discussed in "Parts ofExpressions".Here is a 2x3 matrix.In[11]:=Out[11]=

mm = 88a, b, c<, 8b, c, d<<

88a, b, c<, 8b, c, d<<

This applies f to parts 81, 2< and 82, 3<.

In[12]:=Out[12]=

MapAt@f, mm, 881, 2<, 82, 3<<D

88a, f@bD, c<, 8b, c, f@dD<<

This gives a list of the positions at which b occurs in mm.

In[13]:=Out[13]=

Position@mm, bD881, 2<, 82, 1<<

You can feed the list of positions you get from Position directly into MapAt .In[14]:=Out[14]=

MapAt@f, mm, %D88a, f@bD, c<, 8f@bD, c, d<<

To avoid ambiguity, you must put each part specification in a list, even when it involves onlyone index.In[15]:=Out[15]=

MapAt@f, 8a, b, c, d<, 882<, 83<<D

8a, f@bD, f@cD, d<

MapAt@ f ,expr,8part1 ,part2 ,<D

apply f to specified parts of expr

Applying a function to specific parts of an expression.

160

Core Language

Here is an expression.In[16]:=Out[16]=

t = 1 + H3 + xL ^ 2 x1+

H3 + xL2x

This is the full form of t.

In[17]:=

FullForm@tD

Out[17]//FullForm=

Plus@1, Times@Power@x, -1D, Power@Plus@3, xD, 2DDD

You can use MapAt on any expression. Remember that parts are numbered on the basis of thefull forms of expressions.In[18]:=

MapAt@f, t, 882, 1, 1<, 82, 2<<D

fAH3 + xL2 E

Out[18]=

1+f@xD

MapIndexed@ f ,exprD

apply f to the elements of an expression, giving the part

specification of each element as a second argument to f

MapIndexed@ f ,expr,levD

apply f to parts at specified levels, giving the list of indices

for each part as a second argument to f

Applying a function to parts and their indices.

This applies f to each element in a list, giving the index of the element as a second argumentto f.In[19]:=Out[19]=

MapIndexed@f, 8a, b, c<D

8f@a, 81<D, f@b, 82<D, f@c, 83<D<

This applies f to both levels in a matrix.

In[20]:=Out[20]=

MapIndexed@f, 88a, b<, 8c, d<<, 2D

Map allows you to apply a function of one argument to parts of an expression. Sometimes,however, you may instead want to apply a function of several arguments to correspondingparts of several different expressions. You can do this using MapThread.

Core Language

MapThread@ f ,8expr1 ,expr2 ,<D

apply f to corresponding elements in each of the expri

MapThread@ f ,8expr1 ,expr2 ,<,levD

apply f to parts of the expri at the specified level

161

Applying a function to several expressions at once.

This applies f to corresponding pairs of list elements.In[21]:=Out[21]=

MapThread@f, 88a, b, c<, 8ap, bp, cp<<D

8f@a, apD, f@b, bpD, f@c, cpD<

MapThread works with any number of expressions, so long as they have the same structure.In[22]:=Out[22]=

MapThread@f, 88a, b<, 8ap, bp<, 8app, bpp<<D

8f@a, ap, appD, f@b, bp, bppD<

Functions like Map allow you to create expressions with parts modified. Sometimes you simplywant to go through an expression, and apply a particular function to some parts of it, withoutbuilding a new expression. A typical case is when the function you apply has certain sideeffects, such as making assignments, or generating output.

Scan@ f ,exprD

evaluate f applied to each element of expr in turn

Scan@ f ,expr,levD

evaluate f applied to parts of expr on levels specified by lev

Evaluating functions on parts of expressions.

Map constructs a new list in which f has been applied to each element of the list.In[23]:=Out[23]=

Map@f, 8a, b, c<D

8f@aD, f@bD, f@cD<

Scan evaluates the result of applying a function to each element, but does not construct a newexpression.In[24]:=

Scan@Print, 8a, b, c<D

abc

162

Core Language

Scan visits the parts of an expression in a depth-first walk, with the leaves visited first.In[25]:=

Scan@Print, 1 + x ^ 2, InfinityD

1x2x2

Pure FunctionsFunction@x,bodyD

a pure function in which x is replaced by any argument you

provide

Function@8x1 ,x2 ,<,bodyD

a pure function that takes several arguments

body&

a pure function in which arguments are specified as or

1, 2, 3, etc.

Pure functions.

When you use functional operations such as Nest and Map, you always have to specify a function to apply. In all the examples above, we have used the "name" of a function to specify thefunction. Pure functions allow you to give functions which can be applied to arguments, withouthaving to define explicit names for the functions.This defines a function h.In[1]:=

h@x_D := f@xD + g@xD

Having defined h, you can now use its name in Map.

In[2]:=Out[2]=

Map@h, 8a, b, c<D

8f@aD + g@aD, f@bD + g@bD, f@cD + g@cD<

Here is a way to get the same result using a pure function.

In[3]:=Out[3]=

Map@f@D + g@D &, 8a, b, c<D

8f@aD + g@aD, f@bD + g@bD, f@cD + g@cD<

There are several equivalent ways to write pure functions in Mathematica. The idea in all casesis to construct an object which, when supplied with appropriate arguments, computes a particular function. Thus, for example, if fun is a pure function, then fun@aD evaluates the function withargument a.

Core Language

163

There are several equivalent ways to write pure functions in Mathematica. The idea in all casesis to construct an object which, when supplied with appropriate arguments, computes a particular function. Thus, for example, if fun is a pure function, then fun@aD evaluates the function withargument a.Here is a pure function which represents the operation of squaring.In[4]:=Out[4]=

Function@x, x ^ 2DFunctionAx, x2 E

Supplying the argument n to the pure function yields the square of n.

In[5]:=Out[5]=

%@nDn2

You can use a pure function wherever you would usually give the name of a function.You can use a pure function in Map.In[6]:=Out[6]=

Map@Function@x, x ^ 2D, a + b + cDa2 + b2 + c2

Or in Nest .In[7]:=

Nest@Function@q, 1 H1 + qLD, x, 3D1

Out[7]=

1+

11+

11+x

This sets up a pure function with two arguments and then applies the function to the argumentsa and b.In[8]:=Out[8]=

Function@8x, y<, x ^ 2 + y ^ 3D@a, bD

a2 + b3

If you are going to use a particular function repeatedly, then you can define the function usingf @x_D := body, and refer to the function by its name f . On the other hand, if you only intend touse a function once, you will probably find it better to give the function in pure function form,without ever naming it.If you are familiar with formal logic or the LISP programming language, you will recognizeMathematica pure functions as being like l expressions or anonymous functions. Pure functionsare also close to the pure mathematical notion of operators.

164

Core Language

the first variable in a pure function

the nth variable in a pure function

the sequence of all variables in a pure function

the sequence of variables starting with the nth one

Short forms for pure functions.

Just as the name of a function is irrelevant if you do not intend to refer to the function again, soalso the names of arguments in a pure function are irrelevant. Mathematica allows you to avoidusing explicit names for the arguments of pure functions, and instead to specify the argumentsby giving "slot numbers" n. In a Mathematica pure function, n stands for the nth argumentyou supply. stands for the first argument. ^ 2 & is a short form for a pure function that squares its argument.In[9]:=Out[9]=

Map@ ^ 2 &, a + b + cDa2 + b2 + c2

This applies a function that takes the first two elements from each list. By using a pure function,you avoid having to define the function separately.In[10]:=Out[10]=

Map@Take@, 2D &, 882, 1, 7<, 84, 1, 5<, 83, 1, 2<<D

882, 1<, 84, 1<, 83, 1<<

Using short forms for pure functions, you can simplify the definition of fromdigits givenin "Applying Functions Repeatedly".In[11]:=

fromdigits@digits_D := Fold@H10 1 + 2L &, 0, digitsD

When you use short forms for pure functions, it is very important that you do not forget theampersand. If you leave the ampersand out, Mathematica will not know that the expression yougive is to be used as a pure function.When you use the ampersand notation for pure functions, you must be careful about the grouping of pieces in your input. As shown in "Operator Input Forms" the ampersand notation hasfairly low precedence, which means that you can type expressions like 1 + 2 & without parentheses. On the other hand, if you want, for example, to set an option to be a pure function, youneed to use parentheses, as in option -> H fun &L.Pure functions in Mathematica can take any number of arguments. You can use to stand forall the arguments that are given, and n to stand for the nth and subsequent arguments. stands for all arguments.

Core Language

stands for all arguments.

In[12]:=Out[12]=

f@, D &@x, yDf@x, y, x, yD

2 stands for all arguments except the first one.

In[13]:=Out[13]=

Apply@f@2, 1D &, 88a, b, c<, 8ap, bp<<, 81<D

8f@b, c, aD, f@bp, apD<

Building Lists from Functions

Array@ f ,nD

generate a length n list of the form 8 f @1D, f @2D, <

Array@ f ,8n1 ,n2 ,<D

generate an n1 n2 nested list, each of whose entries

consists of f applied to its indices

NestList@ f ,x,nD

generate a list of the form 8x, f @xD, f @ f @xDD, <,

where f is nested up to n deep

FoldList@ f ,x,8a,b,<D

generate a list of the form

8x, f @x, aD, f @ f @x, aD, bD, <

ComposeList @8 f1 , f2 ,<,xD

generate a list of the form 8x, f1 @xD, f2 @ f1 @xDD, <

Making lists from functions.

This makes a list of 5 elements, each of the form p@iD.In[1]:=Out[1]=

Array@p, 5D8p@1D, p@2D, p@3D, p@4D, p@5D<

Here is another way to produce the same list.

In[2]:=

Table@p@iD, 8i, 5<D

Out[2]= 8p@1D, p@2D, p@3D, p@4D, p@5D<

This produces a list whose elements are i + i2 .

In[3]:=Out[3]=

Array@ + ^ 2 &, 5D82, 6, 12, 20, 30<

165

166

Core Language

This generates a 23 matrix whose entries are m@i, jD.

In[4]:=Out[4]=

Array@m, 82, 3<D

88m@1, 1D, m@1, 2D, m@1, 3D<, 8m@2, 1D, m@2, 2D, m@2, 3D<<

This generates a 33 matrix whose elements are the squares of the sums of their indices.In[5]:=Out[5]=

Array@Plus@D ^ 2 &, 83, 3<D

884, 9, 16<, 89, 16, 25<, 816, 25, 36<<

NestList and FoldList were discussed in "Applying Functions Repeatedly". Particularly by

using them with pure functions, you can construct some very elegant and efficient Mathematicaprograms.This gives a list of results obtained by successively differentiating xn with respect to x.In[6]:=Out[6]=

Selecting Parts of Expressions with Functions

"Manipulating Elements of Lists" shows how you can pick out elements of lists based on theirpositions. Often, however, you will need to select elements based not on where they are, butrather on what they are.Select@list, f D selects elements of list using the function f as a criterion. Select applies f toeach element of list in turn, and keeps only those for which the result is True.This selects the elements of the list for which the pure function yields True , i.e., those numerically greater than 4.In[1]:=Out[1]=

Select@82, 15, 1, a, 16, 17<, > 4 &D

815, 16, 17<

You can use Select to pick out pieces of any expression, not just elements of a list.This gives a sum of terms involving x, y and z.In[2]:=Out[2]=

t = Expand@Hx + y + zL ^ 2Dx2 + 2 x y + y 2 + 2 x z + 2 y z + z 2

Core Language

167

You can use Select to pick out only those terms in the sum that do not involve the symbol x.In[3]:=Out[3]=

Select@t, FreeQ@, xD &D

y2 + 2 y z + z 2

Select@expr, f D

select the elements in expr for which the function f gives

TrueSelect@expr, f ,nD

select the first n elements in expr for which the function f

gives True

Selecting pieces of expressions.

"Putting Constraints on Patterns" discusses some predicates that are often used as criteria inSelect.This gives the first element which satisfies the criterion you specify.In[4]:=Out[4]=

Select@8- 1, 3, 10, 12, 14<, > 3 &, 1D

810<

Expressions with Heads That Are Not Symbols

In most cases, you want the head f of a Mathematica expression like f @xD to be a singlesymbol. There are, however, some important applications of heads that are not symbols.This expression has f@3D as a head. You can use heads like this to represent indexed functions.In[1]:=Out[1]=

f@3D@x, yDf@3D@x, yD

You can use any expression as a head. Remember to put in the necessary parentheses.In[2]:=Out[2]=

Ha + bL@xDHa + bL@xD

One case where we have already encountered the use of complicated expressions as heads is inworking with pure functions in "Pure Functions". By giving Function@vars, bodyD as the head ofan expression, you specify a function of the arguments to be evaluated.

168

Core Language

With the head Function@x, x ^ 2D, the value of the expression is the square of the argument.In[3]:=Out[3]=

Function@x, x ^ 2D@a + bDHa + bL2

There are several constructs in Mathematica which work much like pure functions, but whichrepresent specific kinds of functions, typically numerical ones. In all cases, the basic mechanisminvolves giving a head which contains complete information about the function you want to use.

compiled numerical function (generated by Compile )

LinearSolveFunction@dataD@vecDmatrix solution function (generated by LinearSolve )Some expressions which have heads that are not symbols.

NDSolve returns a list of rules that give y as an InterpolatingFunction object.

In[4]:=Out[4]=

NDSolve@8y ''@xD == y@xD, y@0D == y '@0D == 1<, y, 8x, 0, 5<D

88y InterpolatingFunction@880., 5.<<, <>D<<

Here is the InterpolatingFunction object.

In[5]:=

y . First@%D

Out[5]= InterpolatingFunction@880., 5.<<, <>D

You can use the InterpolatingFunction object as a head to get numerical approximationsto values of the function y.In[6]:=Out[6]=

%@3.8D44.7012

Another important use of more complicated expressions as heads is in implementing functionals

and functional operators in mathematics.

Core Language

169

As one example, consider the operation of differentiation. As discussed in "The Representation

of Derivatives", an expression like f ' represents a derivative function, obtained from f byapplying a functional operator to it. In Mathematica, f ' is represented as Derivative@1D@fD:the functional operator Derivative@1D is applied to f to give another function, representedas f '.This expression has a head which represents the application of the functional operatorDerivative@1D to the function f.In[7]:=

f '@xD FullForm

Out[7]//FullForm=

Derivative@1D@fD@xD

You can replace the head f ' with another head, such as fp. This effectively takes fp to be aderivative function obtained from f.In[8]:=Out[8]=

% . f ' -> fpfp@xD

Working with Operators

You can think of an expression like f @xD as being formed by applying an operator f to the expression x. You can think of an expression like f @g@xDD as the result of composing the operators f andg, and applying the result to x.

Composition @ f ,g,D

the composition of functions f , g,

InverseFunction@ f D

the inverse of a function f

Identity

the identity function

Some functional operations.

This represents the composition of the functions f , g and h.In[1]:=Out[1]=

You can manipulate compositions of functions symbolically.

The composition is evaluated explicitly when you supply a specific argument.

In[3]:=Out[3]=

%@xDqH-1L AhH-1L AgH-1L AfH-1L @xDEEE

You can get the sum of two expressions in Mathematica just by typing x + y. Sometimes it isalso worthwhile to consider performing operations like addition on operators.You can think of this as containing a sum of two operators f and g.In[4]:=Out[4]=

Hf + gL@xDHf + gL@xD

Using Through , you can convert the expression to a more explicit form.In[5]:=

Through@%, PlusD

Out[5]= f@xD + g@xD

This corresponds to the mathematical operator 1 +

In[6]:=Out[6]=

.x

Identity + HD@, xD &L

Identity + Hx 1 &L

Mathematica does not automatically apply the separate pieces of the operator to an expression.In[7]:=Out[7]=

%@x ^ 2DHIdentity + Hx 1 &LLAx2 E

You can use Through to apply the operator.

In[8]:=Out[8]=

Through@%, PlusD2 x + x2

Identity@exprD

the identity function

Through@p@ f1 , f2 D@xD,qD

give p@ f1 @xD, f2 @xDD if p is the same as q

Operate@p, f @xDD

give p@ f D@xD

Operate@p, f @xD,nD

apply p at level n in f

MapAllAp,expr,Heads->TrueE

apply p to all parts of expr, including heads

Operations for working with operators.

Core Language

171

This has a complicated expression as a head.

In[9]:=Out[9]=

t = HH1 + aL H1 + bLL@xDHH1 + aL H1 + bLL@xD

Functions like Expand do not automatically go inside heads of expressions.

In[10]:=Out[10]=

Expand@%DHH1 + aL H1 + bLL@xD

With the Heads option set to True , MapAll goes inside heads.In[11]:=Out[11]=

MapAll@Expand, t, Heads -> TrueD

H1 + a + b + a bL@xD

The replacement operator . does go inside heads of expressions.

In[12]:=Out[12]=

t . a -> 1H2 H1 + bLL@xD

You can use Operate to apply a function specifically to the head of an expression.In[13]:=

Operate@p, tD

Out[13]= p@H1 + aL H1 + bLD@xD

Structural OperationsMathematica contains some powerful primitives for making structural changes to expressions.You can use these primitives both to implement mathematical properties such as associativityand distributivity, and to provide the basis for some succinct and efficient programs.Here we describe various operations that you can explicitly perform on expressions. "Attributes"describes how some of these operations can be performed automatically on all expressions witha particular head by assigning appropriate attributes to that head.You can use the Mathematica function Sort@exprD to sort elements not only of lists, but ofexpressions with any head. In this way, you can implement the mathematical properties ofcommutativity or symmetry for arbitrary functions.

172

Core Language

You can use Sort to put the arguments of any function into a standard order.In[1]:=Out[1]=

Sort@f@c, a, bDDf@a, b, cD

Sort@exprD

sort the elements of a list or other expression into a

standard order

Sort@expr,predD

sort using the function pred to determine whether pairs are

in order

Ordering@exprD

give the ordering of elements when sorted

Ordering@expr,nD

give the ordering of the first n elements when sorted

Ordering@expr,n,predD

use the function pred to determine whether pairs are in

order

OrderedQ@exprD

give True if the elements of expr are in standard order,

and False otherwise

Order@expr1 ,expr2 D

give 1 if expr1 comes before expr2 in standard order, and

- 1 if it comes afterSorting into order.The second argument to Sort is a function used to determine whether pairs are in order. Thissorts numbers into descending order.In[2]:=Out[2]=

Sort@85, 1, 8, 2<, H2 < 1L &D

88, 5, 2, 1<

This sorting criterion puts elements that do not depend on x before those that do.In[3]:=Out[3]=

Sort@8x ^ 2, y, x + y, y - 2<, FreeQ@1, xD &D

9y, -2 + y, x + y, x2 =

Flatten@exprD

flatten out all nested functions with the same head as expr

Flatten@expr,nD

flatten at most n levels of nesting

Flatten@expr,n,hD

flatten functions with head h

FlattenAt@expr,iD

flatten only the ith element of expr

Flattening out expressions.

Core Language

173

Flatten removes nested occurrences of a function.

In[4]:=Out[4]=

Flatten@f@a, f@b, cD, f@f@dDDDD

f@a, b, c, dD

You can use Flatten to splice sequences of elements into lists or other expressions.In[5]:=Out[5]=

Flatten@8a, f@b, cD, f@a, b, dD<, 1, fD

8a, b, c, a, b, d<

You can use Flatten to implement the mathematical property of associativity. The functionDistribute allows you to implement properties such as distributivity and linearity.

Distribute@ f @a+b+,DD

distribute f over sums to give f @a, D + f @b, D +

Distribute@ f @argsD,gD

distribute f over any arguments which have head g

Distribute@expr,g, f D

distribute only when the head is f

Distribute@expr,g, f ,gp, fpD

distribute f over g, replacing them with fp and gp,

respectively

Applying distributive laws.

This distributes f over a + b.In[6]:=

Distribute@f@a + bDD

Out[6]= f@aD + f@bD

Here is a more complicated example.

In[7]:=Out[7]=

Distribute@f@a + b, c + dDDf@a, cD + f@a, dD + f@b, cD + f@b, dD

In general, if f is distributive over Plus, then an expression like f @a + bD can be expanded to

give f @aD + f @bD. The function Expand does this kind of expansion for standard algebraic operators such as Times. Distribute allows you to perform the same kind of expansion for arbitraryoperators.Expand uses the distributivity of Times over Plus to perform algebraic expansions.In[8]:=Out[8]=

Expand@Ha + bL Hc + dLDac+bc+ad+bd

174

Core Language

This applies distributivity over lists, rather than sums. The result contains all possible pairs ofarguments.In[9]:=Out[9]=

Distribute@f@8a, b<, 8c, d<D, ListD

8f@a, cD, f@a, dD, f@b, cD, f@b, dD<

This distributes over lists, but does so only if the head of the whole expression is f.In[10]:=Out[10]=

Distribute@f@8a, b<, 8c, d<D, List, fD

8f@a, cD, f@a, dD, f@b, cD, f@b, dD<

This distributes over lists, making sure that the head of the whole expression is f. In the result,it uses gp in place of List , and fp in place of f.In[11]:=Out[11]=

Distribute@f@8a, b<, 8c, d<D, List, f, gp, fpD

gp@fp@a, cD, fp@a, dD, fp@b, cD, fp@b, dDD

Related to Distribute is the function Thread. What Thread effectively does is to apply a function in parallel to all the elements of a list or other expression.

Thread@ f @8a1 ,a2 <,8b1 ,b2 <DD

thread f over lists to give 8 f @a1 , b1 D, f @a2 , b2 D<

Thread@ f @argsD,gD

thread f over objects with head g in args

Functions for threading expressions.

Here is a function whose arguments are lists.In[12]:=Out[12]=

f@8a1, a2<, 8b1, b2<D

f@8a1, a2<, 8b1, b2<D

Thread applies the function in parallel to each element of the lists.

In[13]:=Out[13]=

Thread@%D8f@a1, b1D, f@a2, b2D<

Arguments that are not lists get repeated.

In[14]:=Out[14]=

Thread@f@8a1, a2<, 8b1, b2<, c, dDD

8f@a1, b1, c, dD, f@a2, b2, c, dD<

Core Language

175

As mentioned in "Collecting Objects Together", and discussed in more detail in "Attributes",

many built-in Mathematica functions have the property of being listable, so that they areautomatically threaded over any lists that appear as arguments.Built-in mathematical functions such as Log are listable, so that they are automaticallythreaded over lists.In[15]:=Out[15]=

Log@8a, b, c<D8Log@aD, Log@bD, Log@cD<

Log is, however, not automatically threaded over equations.

In[16]:=

Log@x == yD

Out[16]= Log@x yD

You can use Thread to get functions applied to both sides of an equation.In[17]:=Out[17]=

Thread@%, EqualDLog@xD Log@yD

Outer@ f ,list1 ,list2 D

generalized outer product

Inner@ f ,list1 ,list2 ,gD

generalized inner product

Generalized outer and inner products.

Outer@ f , list1 , list2 D takes all possible combinations of elements from list1 and list2 , and combines them with f . Outer can be viewed as a generalization of a Cartesian product for tensors,as discussed in "Tensors".Outer forms all possible combinations of elements, and applies f to them.In[18]:=Out[18]=

Outer@f, 8a, b<, 81, 2, 3<D

88f@a, 1D, f@a, 2D, f@a, 3D<, 8f@b, 1D, f@b, 2D, f@b, 3D<<

Here Outer produces a lower-triangular Boolean matrix.

In[19]:=Out[19]=

Outer@Greater, 81, 2, 3<, 81, 2, 3<D

88False, False, False<, 8True, False, False<, 8True, True, False<<

176

Core Language

You can use Outer on any sequence of expressions with the same head.In[20]:=Out[20]=

Outer@g, f@a, bD, f@c, dDD

f@f@g@a, cD, g@a, dDD, f@g@b, cD, g@b, dDDD

Outer, like Distribute, constructs all possible combinations of elements. On the other hand,Inner, like Thread, constructs only combinations of elements that have corresponding positionsin the expressions it acts on.Here is a structure built by Inner .In[21]:=Out[21]=

Inner@f, 8a, b<, 8c, d<, gD

g@f@a, cD, f@b, dDD

Inner is a generalization of Dot.

In[22]:=Out[22]=

Inner@Times, 8a, b<, 8c, d<, PlusD

ac+bd

SequencesThe function Flatten allows you to explicitly flatten out all sublists.In[1]:=Out[1]=

Flatten@8a, 8b, c<, 8d, e<<D

8a, b, c, d, e<

FlattenAt lets you specify at what positions you want sublists flattened.In[2]:=Out[2]=

FlattenAt@8a, 8b, c<, 8d, e<<, 2D

8a, b, c, 8d, e<<

Sequence objects automatically get spliced in, and do not require any explicit flattening.In[3]:=Out[3]=

8a, Sequence@b, cD, Sequence@d, eD<

8a, b, c, d, e<

Core Language

Sequence@e1 ,e2 ,D

a sequence of arguments that will automatically be spliced

into any function

Representing sequences of arguments in functions.

Sequence works in any function.

In[4]:=Out[4]=

f@Sequence@a, bD, cDf@a, b, cD

This includes functions with special input forms.

In[5]:=Out[5]=

a == Sequence@b, cDabc

Here is a common way that Sequence is used.

In[6]:=Out[6]=

8a, b, f@x, yD, g@wD, f@z, yD< . f -> Sequence

8a, b, x, y, g@wD, z, y<

177

178

Core Language

Modularity and the Naming of Things

Modules and Local VariablesMathematica normally assumes that all your variables are global. This means that every timeyou use a name like x, Mathematica normally assumes that you are referring to the sameobject.Particularly when you write programs, however, you may not want all your variables to beglobal. You may, for example, want to use the name x to refer to two quite different variablesin two different programs. In this case, you need the x in each program to be treated as a localvariable.You can set up local variables in Mathematica using modules. Within each module, you can givea list of variables which are to be treated as local to the module.

Module@8x,y,<,bodyD

a module with local variables x, y,

Creating modules in Mathematica.

This defines the global variable t to have value 17.In[1]:=Out[1]=

t = 1717

The t inside the module is local, so it can be treated independently of the global t.In[2]:=

Module@8t<, t = 8; Print@tDD

8The global t still has value 17.In[3]:=Out[3]=

t17

The most common way that modules are used is to set up temporary or intermediate variablesinside functions you define. It is important to make sure that such variables are kept local. Ifthey are not, then you will run into trouble whenever their names happen to coincide with thenames of other variables.The intermediate variable t is specified to be local to the module.

Core Language

179

The intermediate variable t is specified to be local to the module.

In[4]:=

f@v_D := Module@8t<, t = H1 + vL ^ 2; t = Expand@tDD

This runs the function f.

In[5]:=Out[5]=

f@a + bD1 + 2 a + a2 + 2 b + 2 a b + b2

The global t still has value 17.

In[6]:=Out[6]=

t17

You can treat local variables in modules just like other symbols. Thus, for example, you can usethem as names for local functions, you can assign attributes to them, and so on.This sets up a module which defines a local function f.In[7]:=

In this case, f is set up as a generalized factorial.

In[9]:=Out[9]=

gfac10@2D8 841 802

When you set up a local variable in a module, Mathematica initially assigns no value to thevariable. This means that you can use the variable in a purely symbolic way, even if there wasa global value defined for the variable outside the module.This uses the global value of t defined above, and so yields a number.In[10]:=Out[10]=

Expand@H1 + tL ^ 3D5832

Here Length simply receives a number as its argument.

In[11]:=Out[11]=

Length@Expand@H1 + tL ^ 3DD0

The local variable t has no value, so it acts as a symbol, and Expand produces the anticipatedalgebraic result.

180

Core Language

The local variable t has no value, so it acts as a symbol, and Expand produces the anticipatedalgebraic result.In[12]:=Out[12]=

Module@8t<, Length@Expand@H1 + tL ^ 3DDD

4

Module@8x=x0 ,y=y0 ,<,bodyD

a module with initial values for local variablesAssigning initial values to local variables.This specifies t to be a local variable, with initial value u.In[13]:=

g@u_D := Module@8t = u<, t += t H1 + uLD

This uses the definition of g.

In[14]:=Out[14]=

g@aDa+

a1+a

You can define initial values for any of the local variables in a module. The initial values arealways evaluated before the module is executed. As a result, even if a variable x is defined aslocal to the module, the global x will be used if it appears in an expression for an initial value.The initial value of u is taken to be the global value of t.In[15]:=Out[15]=

Module@8t = 6, u = t<, u ^ 2D289

lhs:=Module@vars,rhs;condD

share local variables between rhs and cond

Using local variables in definitions with conditions.

When you set up ; conditions for definitions, you often need to introduce temporary variables.In many cases, you may want to share these temporary variables with the body of the righthand side of the definition. Mathematica allows you to enclose the whole right-hand side of yourdefinition in a module, including the condition.This defines a function with a condition attached.In[16]:=

h@x_D := Module@8t<, t ^ 2 - 1 ; Ht = x - 4L > 1D

Core Language

181

Mathematica shares the value of the local variable t between the condition and the body of theright-hand side.In[17]:=Out[17]=

h@10D35

Local ConstantsWith@8x=x0 ,y=y0 ,<,bodyD

define local constants x, y,

Defining local constants.

Module allows you to set up local variables, to which you can assign values and then changethem. Often, however, all you really need are local constants, to which you assign a value onlyonce. The Mathematica With construct allows you to set up such local constants.This defines a global value for t.In[1]:=Out[1]=

t = 1717

This defines a function using t as a local constant.

In[2]:=

w@x_D := With@8t = x + 1<, t + t ^ 3D

This uses the definition of w.

In[3]:=Out[3]=

w@aD1 + a + H1 + aL3

t still has its global value.

In[4]:=

Out[4]= 17

Just as in Module, the initial values you define in With are evaluated before With is executed.The expression t + 1 which gives the value of the local constant t is evaluated using the globalt.In[5]:=Out[5]=

With@8t = t + 1<, t ^ 2D324

The way With@8x = x0 , <, bodyD works is to take body, and replace every occurrence of x, etc.in it by x0 , etc. You can think of With as a generalization of the . operator, suitable for applica-

182

Core Language

The way With@8x = x0 , <, bodyD works is to take body, and replace every occurrence of x, etc.in it by x0 , etc. You can think of With as a generalization of the . operator, suitable for application to Mathematica code instead of other expressions.This replaces x with a.In[6]:=Out[6]=

With@8x = a<, x = 5D5

After the replacement, the body of With is a = 5, so a gets the global value 5.In[7]:=Out[7]=

a5

This clears the value of a.

In[8]:=

Clear@aD

In some respects, With is like a special case of Module, in which each local variable is assigneda value exactly once.One of the main reasons for using With rather than Module is that it typically makes the Mathematica programs you write easier to understand. In a module, if you see a local variable x at aparticular point, you potentially have to trace through all of the code in the module to work outthe value of x at that point. In a With construct, however, you can always find out the value ofa local constant simply by looking at the initial list of values, without having to trace throughspecific code.If you have several With constructs, it is always the innermost one for a particular variable thatis in effect. You can mix Module and With. The general rule is that the innermost one for aparticular variable is the one that is in effect.With nested With constructs, the innermost one is always the one in effect.In[9]:=Out[9]=

With@8t = 8<, With@8t = 9<, t ^ 2DD

81

You can mix Module and With constructs.

In[10]:=Out[10]=

Module@8t = 8<, With@8t = 9<, t ^ 2DD

81

Local variables in inner constructs do not mask ones outside unless the names conflict.

Core Language

183

Local variables in inner constructs do not mask ones outside unless the names conflict.In[11]:=Out[11]=

With@8t = a<, With@8u = b<, t + uDD

a+b

Except for the question of when x and body are evaluated, With@8x = x0 , <, bodyD works essentially like body . x -> x0 . However, With behaves in a special way when the expression bodyitself contains With or Module constructs. The main issue is to prevent the local constants inthe various With constructs from conflicting with each other, or with global objects. The detailsof how this is done are discussed in "How Modules Work".The y in the inner With is renamed to prevent it from conflicting with the global y.In[12]:=

With@8x = 2 + y<, Hold@With@8y = 4<, x + yDDD

Out[12]= Hold@With@8y$ = 4<, H2 + yL + y$DD

How Modules Work

The way modules work in Mathematica is basically very simple. Every time any module is used,a new symbol is created to represent each of its local variables. The new symbol is given aunique name which cannot conflict with any other names. The name is formed by taking thename you specify for the local variable, followed by $, with a unique serial number appended.The serial number is found from the value of the global variable $ModuleNumber. This variablecounts the total number of times any Module of any form has been used.Module generates symbols with names of the form x$nnn to represent each local variable.The basic principle of modules in Mathematica.This shows the symbol generated for t within the module.In[1]:=

Module@8t<, Print@tDD

t$1The symbols are different every time any module is used.In[2]:=

Module@8t, u<, Print@tD; Print@uDD

t$2u$2For most purposes, you will never have to deal directly with the actual symbols generatedinside modules. However, if for example you start up a dialog while a module is being executed,

184

Core Language

For most purposes, you will never have to deal directly with the actual symbols generatedinside modules. However, if for example you start up a dialog while a module is being executed,then you will see these symbols. The same is true whenever you use functions like Trace towatch the evaluation of modules.You see the symbols that are generated inside modules when you use Trace .In[3]:=Out[3]=

Trace@Module@8t<, t = 3DD8Module@8t<, t = 3D, 8t$3 = 3, 3<, 3<

This starts a dialog inside a module.

In[4]:=

Module@8t<, t = 6; Dialog@DDInside the dialog, you see the symbols generated for local variables such as t.

In[5]:=Out[5]=

Stack@_D8Module@8t<, t = 6; Dialog@DD, t$4 = 6; Dialog@D, Dialog@D<

You can work with these symbols as you would with any other symbols.In[6]:=Out[6]=

t$4 + 17

This returns from the dialog.

In[7]:=Out[7]=

Return@t$4 ^ 2D36

Under some circumstances, it is convenient explicitly to return symbols that are generatedinside modules.You can explicitly return symbols that are generated inside modules.In[8]:=Out[8]=

Module@8t<, tDt$6

You can treat these symbols as you would any others.

In[9]:=Out[9]=

%^2 + 11 + t$62

Core Language

185

generate a new symbol with a unique name of the form

Unique@xD

x$nnnUnique@8x,y,<D

generate a list of new symbols

Generating new symbols with unique names.

The function Unique allows you to generate new symbols in the same way as Module does.Each time you call Unique, $ModuleNumber is incremented, so that the names of new symbolsare guaranteed to be unique.This generates a unique new symbol whose name starts with x.In[10]:=Out[10]=

Unique@xDx$7

Each time you call Unique you get a symbol with a larger serial number.In[11]:=Out[11]=

8Unique@xD, Unique@xD, Unique@xD<

8x$8, x$9, x$10<

If you call Unique with a list of names, you get the same serial number for each of thesymbols.In[12]:=Out[12]=

Unique@8x, xa, xb<D

8x$11, xa$11, xb$11<

You can use the standard Mathematica ? name mechanism to get information on symbols thatwere generated inside modules or by the function Unique.Executing this module generates the symbol q$nnn.In[13]:=Out[13]=

Module@8q<, q ^ 2 + 1D1 + q$122

You can see the generated symbol here.

In[14]:=

? q*

q$12

186

Core Language

Symbols generated by Module behave in exactly the same way as other symbols for the purposes of evaluation. However, these symbols carry the attribute Temporary, which specifiesthat they should be removed completely from the system when they are no longer used. Thusmost symbols that are generated inside modules are removed when the execution of thosemodules is finished. The symbols survive only if they are explicitly returned.This shows a new q variable generated inside a module.In[15]:=

Module@8q<, Print@qDD

q$13The new variable is removed when the execution of the module is finished, so it does not showup here.In[16]:=

? q*

q$12

You should realize that the use of names such as x$nnn for generated symbols is purely a convention. You can in principle give any symbol a name of this form. But if you do, the symbol maycollide with one that is produced by Module.An important point to note is that symbols generated by Module are in general unique onlywithin a particular Mathematica session. The variable $ModuleNumber which determines theserial numbers for these symbols is always reset at the beginning of each session.This means in particular that if you save expressions containing generated symbols in a file,and then read them into another session, there is no guarantee that conflicts will not occur.One way to avoid such conflicts is explicitly to set $ModuleNumber differently at the beginning ofeach session. In particular, if you set $ModuleNumber = 10 ^ 10 $SessionID, you should avoidany conflicts. The global variable $SessionID should give a unique number which characterizesa particular Mathematica session on a particular computer. The value of this variable is determined from such quantities as the absolute date and time, the ID of your computer, and, ifappropriate, the ID of the particular Mathematica process.

$ModuleNumber

the serial number for symbols generated by Module and

$SessionID

a number that should be different for every Mathematica

session

Unique

Variables to be used in determining serial numbers for generated symbols.

Having generated appropriate symbols to represent the local variables you have specified,Module@vars, bodyD then has to evaluate body using these symbols. The first step is to take the

Core Language

187

Having generated appropriate symbols to represent the local variables you have specified,Module@vars, bodyD then has to evaluate body using these symbols. The first step is to take theactual expression body as it appears inside the module, and effectively to use With to replace alloccurrences of each local variable name with the appropriate generated symbol. After this isdone, Module actually performs the evaluation of the resulting expression.An important point to note is that Module@vars, bodyD inserts generated symbols only into theactual expression body. It does not, for example, insert such symbols into code that is calledfrom body, but does not explicitly appear in body."Blocks and Local Values" discusses how you can use Block to set up local values which workin a different way.Since x does not appear explicitly in the body of the module, the local value is not used.In[17]:=Out[17]=

tmp = x ^ 2 + 1; Module@8x = 4<, tmpD

1 + x2

Most of the time, you will probably set up modules by giving explicit Mathematica input of theform Module@vars, bodyD. Since the function Module has the attribute HoldAll, the form of bodywill usually be kept unevaluated until the module is executed.It is, however, possible to build modules dynamically in Mathematica. The generation of newsymbols, and their insertion into body are always done only when a module is actually executed,not when the module is first given as Mathematica input.This evaluates the body of the module immediately, making x appear explicitly.In[18]:=Out[18]=

tmp = x ^ 2 + 1; Module@8x = 4<, Evaluate@tmpDD

17

Variables in Pure Functions and Rules

Module and With allow you to give a specific list of symbols whose names you want to treat aslocal. In some situations, however, you want to automatically treat certain symbol names aslocal.For example, if you use a pure function such as Function@8x<, x + aD, you want x to be treatedas a formal parameter, whose specific name is local. The same is true of the x that appears ina rule like f@x_D -> x ^ 2, or a definition like f@x_D := x ^ 2.Mathematica uses a uniform scheme to make sure that the names of formal parameters which

188

Core Language

Mathematica uses a uniform scheme to make sure that the names of formal parameters whichappear in constructs like pure functions and rules are kept local, and are never confused withglobal names. The basic idea is to replace formal parameters when necessary by symbols withnames of the form x$. By convention, x$ is never used as a global name.Here is a nested pure function.In[1]:=Out[1]=

Function@8x<, Function@8y<, x + yDD

The resulting pure function behaves as it should.

In[3]:=Out[3]=

%@aDa+2y

In general, Mathematica renames the formal parameters in an object like Function@vars, bodyDwhenever body is modified in any way by the action of another pure function.The formal parameter y is renamed because the body of the inner pure function was changed.In[4]:=Out[4]=

Function@8x<, Function@8y<, x + yDD@aD

Function@8y$<, a + y$D

Since the body of the inner function does not change, the formal parameter is not renamed.In[5]:=Out[5]=

Function@8x<, x + Function@8y<, y ^ 2DD@aD

a + FunctionA8y<, y2 E

Mathematica renames formal parameters in pure functions more liberally than is strictly necessary. In principle, renaming could be avoided if the names of the formal parameters in a particular function do not actually conflict with parts of expressions substituted into the body of thepure function. For uniformity, however, Mathematica still renames formal parameters even insuch cases.

Core Language

189

In this case, the formal parameter x in the inner function shields the body of the function, so norenaming is needed.In[6]:=Out[6]=

Function@8x<, Function@8x<, x + yDD@aD

Function@8x<, x + yD

Here are three nested functions.

In[7]:=Out[7]=

Function@8x<, Function@8y<, Function@8z<, x + y + zDDD

Function@8x<, Function@8y<, Function@8z<, x + y + zDDD

Both inner functions are renamed in this case.

In[8]:=Out[8]=

%@aDFunction@8y$<, Function@8z$<, a + y$ + z$DD

As mentioned in "Pure Functions", pure functions in Mathematica are like l expressions in

lhs->rhs and lhs:>rhs

local pattern names

lhs=rhs and lhs:=rhs

local pattern names

With@8x=x0 ,<,bodyD

local constants

Module@8x,<,bodyD

local variables

Scoping constructs in Mathematica.

Mathematica has several scoping constructs in which certain names are treated as local.When you mix these constructs in any way, Mathematica does appropriate renamings to avoidconflicts.Mathematica renames the formal parameter of the pure function to avoid a conflict.In[9]:=Out[9]=

With@8x = a<, Function@8a<, a + xDD

Function@8a$<, a$ + aD

Here the local constant in the inner With is renamed to avoid a conflict.In[10]:=Out[10]=

With@8x = y<, Hold@With@8y = 4<, x + yDDD

Hold@With@8y$ = 4<, y + y$DD

There is no conflict between names in this case, so no renaming is done.

190

Core Language

There is no conflict between names in this case, so no renaming is done.

In[11]:=Out[11]=

With@8x = y<, Hold@With@8z = x + 2<, z + 2DDD

Hold@With@8z = y + 2<, z + 2DD

The local variable y in the module is renamed to avoid a conflict.

In[12]:=Out[12]=

With@8x = y<, Hold@Module@8y<, x + yDDD

Hold@Module@8y$<, y + y$DD

If you execute the module, however, the local variable is renamed again to make its nameunique.In[13]:=Out[13]=

ReleaseHold@%Dy + y$1

Mathematica treats transformation rules as scoping constructs, in which the names you give topatterns are local. You can set up named patterns either using x_, x__ and so on, or usingx : patt.The x in the h goes with the x_, and is considered local to the rule.In[14]:=Out[14]=

With@8x = 5<, g@x_, xD -> h@xDD

g@x_, 5D h@xD

In a rule like f@x_D -> x + y, the x which appears on the right-hand side goes with the name ofthe x_ pattern. As a result, this x is treated as a variable local to the rule, and cannot be modified by other scoping constructs.The y, on the other hand, is not local to the rule, and can be modified by other scoping constructs. When this happens, Mathematica renames the patterns in the rule to prevent thepossibility of a conflict.Mathematica renames the x in the rule to prevent a conflict.In[15]:=Out[15]=

With@8w = x<, f@x_D -> w + xD

f@x$_D x + x$

When you use With on a scoping construct, Mathematica automatically performs appropriaterenamings. In some cases, however, you may want to make substitutions inside scoping constructs, without any renaming. You can do this using the . operator.When you substitute for y using With , the x in the pure function is renamed to prevent aconflict.

Core Language

191

When you substitute for y using With , the x in the pure function is renamed to prevent aconflict.In[16]:=Out[16]=

With@8y = x + a<, Function@8x<, x + yDD

Function@8x$<, x$ + Ha + xLD

If you use . rather than With , no such renaming is done.

In[17]:=Out[17]=

Function@8x<, x + yD . y -> a + xFunction@8x<, x + Ha + xLD

When you apply a rule such as f @x_D -> rhs, or use a definition such as f @x_D := rhs, Mathematica implicitly has to substitute for x everywhere in the expression rhs. It effectively does thisusing the . operator. As a result, such substitution does not respect scoping constructs. However, when the insides of a scoping construct are modified by the substitution, the other variables in the scoping construct are renamed.This defines a function for creating pure functions.In[18]:=

mkfun@var_, body_D := Function@8var<, bodyD

The x and x ^ 2 are explicitly inserted into the pure function, effectively by using the . operator.

In[19]:=Out[19]=

mkfun@x, x ^ 2DFunctionA8x<, x2 E

This defines a function that creates a pair of nested pure functions.

In[20]:=

mkfun2@var_, body_D := Function@8x<, Function@8var<, body + xDD

The x in the outer pure function is renamed in this case.

In[21]:=Out[21]=

mkfun2@x, x ^ 2DFunctionA8x$<, FunctionA8x<, x2 + x$EE

Dummy Variables in Mathematics

When you set up mathematical formulas, you often have to introduce various kinds of localobjects or "dummy variables". You can treat such dummy variables using modules and otherMathematica scoping constructs.Integration variables are a common example of dummy variables in mathematics. When youwrite down a formal integral, conventional notation requires you to introduce an integrationvariable with a definite name. This variable is essentially "local" to the integral, and its name,

192

Core Language

Integration variables are a common example of dummy variables in mathematics. When youwrite down a formal integral, conventional notation requires you to introduce an integrationvariable with a definite name. This variable is essentially "local" to the integral, and its name,while arbitrary, must not conflict with any other names in your mathematical expression.Here is a function for evaluating an integral.In[1]:=

p@n_D := Integrate@f@sD s ^ n, 8s, 0, 1<D

The s here conflicts with the integration variable.

In[2]:=

p@s + 1D1

Out[2]=

1+sf@sD s s0

Here is a definition with the integration variable specified as local to a module.

In[3]:=

pm@n_D := Module@8s<, Integrate@f@sD s ^ n, 8s, 0, 1<DD

Since you have used a module, Mathematica automatically renames the integration variable toavoid a conflict.

In[4]:=

pm@s + 1D1

Out[4]=

1+sf@s$20D s$20 s$200

In many cases, the most important issue is that dummy variables should be kept local, andshould not interfere with other variables in your mathematical expression. In some cases,however, what is instead important is that different uses of the same dummy variable shouldnot conflict.Repeated dummy variables often appear in products of vectors and tensors. With the"summation convention", any vector or tensor index that appears exactly twice is summed overall its possible values. The actual name of the repeated index never matters, but if there aretwo separate repeated indices, it is essential that their names do not conflict.This sets up the repeated index j as a dummy variable.In[5]:=

q@i_D := Module@8j<, a@i, jD b@jDD

The module gives different instances of the dummy variable different names.

In[6]:=

q@i1D q@i2D

Out[6]= a@i1, j$29D a@i2, j$30D b@j$29D b@j$30D

There are many situations in mathematics where you need to have variables with uniquenames. One example is in representing solutions to equations. With an equation like cosHxL = 1,

Core Language

193

There are many situations in mathematics where you need to have variables with uniquenames. One example is in representing solutions to equations. With an equation like cosHxL = 1,there are an infinite number of solutions, each of the form x = 2 p n, where n is a dummy variablethat can be equal to any integer.When Mathematica solves this equation, it creates a dummy variable.In[7]:=

Reduce@Cos@xD == 1, xD

Out[7]= C@1D Integers && x 2 p C@1D

Here is a way to make the dummy variable unique.

In[8]:=

Reduce@Cos@xD == 1, x, GeneratedParameters :> Unique@CDD

Out[8]= C$489@1D Integers && x 2 p C$489@1D

Another place where unique objects are needed is in representing "constants of integration".When you do an integral, you are effectively solving an equation for a derivative. In general,there are many possible solutions to the equation, differing by additive "constants of integration". The standard Mathematica Integrate function always returns a solution with no constantof integration. But if you were to introduce constants of integration, you would need to usemodules to make sure that they are always unique.

Blocks and Local Values

Modules in Mathematica allow you to treat the names of variables as local. Sometimes, however, you want the names to be global, but values to be local. You can do this in Mathematicausing Block.

Block@8x,y,<,bodyD

evaluate body using local values for x, y,

Block@8x=x0 ,y=y0 ,<,bodyD

assign initial values to x, y,

Setting up local values.

Here is an expression involving x.In[1]:=Out[1]=

x^2 + 33 + x2

194

Core Language

This evaluates the previous expression, using a local value for x.

In[2]:=Out[2]=

Block@8x = a + 1<, %D3 + H1 + aL2

There is no global value for x.

In[3]:=Out[3]=

xx

As described in "Modules and Local Variables", the variable x in a module such as

Module@8x<, bodyD is always set up to refer to a unique symbol, different each time the moduleis used, and distinct from the global symbol x. The x in a block such as Block@8x<, bodyD is,however, taken to be the global symbol x. What the block does is to make the value of x local.The value x had when you entered the block is always restored when you exit the block. Andduring the execution of the block, x can take on any value.This sets the symbol t to have value 17.In[4]:=Out[4]=

t = 1717

Variables in modules have unique local names.

In[5]:=

Module@8t<, Print@tDD

t$1In blocks, variables retain their global names, but can have local values.In[6]:=

Block@8t<, Print@tDD

tt is given a local value inside the block.In[7]:=Out[7]=

Block@8t<, t = 6; t ^ 4 + 1D1297

When the execution of the block is over, the previous value of t is restored.In[8]:=

Out[8]= 17

Blocks in Mathematica effectively allow you to set up "environments" in which you can temporarily change the values of variables. Expressions you evaluate at any point during the executionof a block will use the values currently defined for variables in the block. This is true whether

Core Language

195

Blocks in Mathematica effectively allow you to set up "environments" in which you can temporarily change the values of variables. Expressions you evaluate at any point during the executionof a block will use the values currently defined for variables in the block. This is true whetherthe expressions appear directly as part of the body of the block, or are produced at any point inits evaluation.This defines a delayed value for the symbol u.In[9]:=

You can specify a temporary value for t to use inside the block.In[11]:=Out[11]=

Block@8t = 5<, u + 7D32 + x2

An important implicit use of Block in Mathematica is for iteration constructs such as Do, Sumand Table. Mathematica effectively uses Block to set up local values for the iteration variablesin all of these constructs.Sum automatically makes the value of the iterator t local.In[12]:=Out[12]=

Sum@t ^ 2, 8t, 10<D

385

The local values in iteration constructs are slightly more general than in Block . They handlevariables such as a@1D, as well as pure symbols.In[13]:=Out[13]=

Sum@a@1D ^ 2, 8a@1D, 10<D

385

When you set up functions in Mathematica, it is sometimes convenient to have "global variables" which can affect the functions without being given explicitly as arguments. Thus, forexample, Mathematica itself has a global variable $RecursionLimit which affects the evaluation of all functions, but is never explicitly given as an argument.Mathematica will usually keep any value you define for a global variable until you explicitlychange it. Often, however, you want to set up values which last only for the duration of aparticular computation, or part of a computation. You can do this by making the values local toa Mathematica block.

196

Core Language

Mathematica will usually keep any value you define for a global variable until you explicitlychange it. Often, however, you want to set up values which last only for the duration of aparticular computation, or part of a computation. You can do this by making the values local toa Mathematica block.This defines a function which depends on the "global variable" t.In[14]:=

f@x_D := x ^ 2 + tIn this case, the global value of t is used.

In[15]:=Out[15]=

f@aD17 + a2

Inside a block, you can set up a local value for t.

In[16]:=Out[16]=

Block@8t = 2<, f@bDD

2 + b2

You can use global variables not only to set parameters in functions, but also to accumulateresults from functions. By setting up such variables to be local to a block, you can arrange toaccumulate results only from functions called during the execution of the block.This function increments the global variable t, and returns its current value.In[17]:=

h@x_D := Ht += x ^ 2LIf you do not use a block, evaluating h@aD changes the global value of t.

In[18]:=Out[18]=

h@aD17 + a2

With a block, only the local value of t is affected.

In[19]:=Out[19]=

Block@8t = 0<, h@cDD

c2

The global value of t remains unchanged.

In[20]:=Out[20]=

t17 + a2

When you enter a block such as Block@8x<, bodyD, any value for x is removed. This means thatyou can in principle treat x as a "symbolic variable" inside the block. However, if you explicitlyreturn x from the block, it will be replaced by its value outside the block as soon as it is evaluated.

Core Language

197

When you enter a block such as Block@8x<, bodyD, any value for x is removed. This means thatyou can in principle treat x as a "symbolic variable" inside the block. However, if you explicitlyreturn x from the block, it will be replaced by its value outside the block as soon as it is evaluated.The value of t is removed when you enter the block.In[21]:=

Block@8t<, Print@Expand@Ht + 1L ^ 2DDD

1 + 2 t + t2If you return an expression involving t, however, it is evaluated using the global value for t.In[22]:=Out[22]=

Block@8t<, t ^ 2 - 3D-3 + I17 + a2 M

Blocks Compared with Modules

When you write a program in Mathematica, you should always try to set it up so that its partsare as independent as possible. In this way, the program will be easier for you to understand,maintain and add to.One of the main ways to ensure that different parts of a program do not interfere is to givetheir variables only a certain "scope". Mathematica provides two basic mechanisms for limitingthe scope of variables: modules and blocks.In writing actual programs, modules are far more common than blocks. When scoping isneeded in interactive calculations, however, blocks are often convenient.

Module@vars,bodyD

lexical scoping

Block@vars,bodyD

dynamic scoping

Mathematica variable scoping mechanisms.

Most traditional computer languages use a so-called "lexical scoping" mechanism for variables,which is analogous to the module mechanism in Mathematica. Some symbolic computer languages such as LISP also allow "dynamic scoping", analogous to Mathematica blocks.When lexical scoping is used, variables are treated as local to a particular section of the code ina program. In dynamic scoping, the values of variables are local to a part of the executionhistory of the program.In compiled languages like C and Java, there is a very clear distinction between "code" and"execution history". The symbolic nature of Mathematica makes this distinction slightly less

198

Core Language

In compiled languages like C and Java, there is a very clear distinction between "code" and"execution history". The symbolic nature of Mathematica makes this distinction slightly lessclear, since "code" can in principle be built up dynamically during the execution of a program.What Module@vars, bodyD does is to treat the form of the expression body at the time when themodule is executed as the "code" of a Mathematica program. Then when any of the vars explicitly appears in this "code", it is considered to be local.Block@vars, bodyD does not look at the form of the expression body. Instead, throughout theevaluation of body, the block uses local values for the vars.This defines m in terms of i.In[1]:=Out[1]=

m = i^2i2

The local value for i in the block is used throughout the evaluation of i + m.In[2]:=Out[2]=

Block@8i = a<, i + mDa + a2

Here only the i that appears explicitly in i + m is treated as a local variable.

In[3]:=Out[3]=

Module@8i = a<, i + mDa + i2

ContextsIt is always a good idea to give variables and functions names that are as explicit as possible.Sometimes, however, such names may get inconveniently long.In Mathematica, you can use the notion of "contexts" to organize the names of symbols. Contexts are particularly important in Mathematica packages which introduce symbols whosenames must not conflict with those of any other symbols. If you write Mathematica packages,or make sophisticated use of packages that others have written, then you will need to knowabout contexts.The basic idea is that the full name of any symbol is broken into two parts: a context and ashort name. The full name is written as context`short, where the ` is the backquote or graveaccent character (ASCII decimal code 96), called a "context mark" in Mathematica.Here is a symbol with short name x, and context aaaa.

Core Language

199

Here is a symbol with short name x, and context aaaa.

In[1]:=

aaaa`x

Out[1]= aaaa`x

You can use this symbol just like any other symbol.In[2]:=

%^2 - %

2Out[2]= -aaaa`x + aaaa`x

You can for example define a value for the symbol.

In[3]:=

aaaa`x = 78

Out[3]= 78

Mathematica treats a`x and b`x as completely different symbols.

In[4]:=

a`x == b`x

Out[4]= a`x b`x

It is typical to have all the symbols that relate a particular topic in a particular context. Thus,for example, symbols that represent physical units might have a context PhysicalUnits`. Suchsymbols might have full names like PhysicalUnits`Joule or PhysicalUnits`Mole.Although you can always refer to a symbol by its full name, it is often convenient to use ashorter name.At any given point in a Mathematica session, there is always a current context $Context. Youcan refer to symbols that are in this context simply by giving their short names, unless thesymbol is shadowed by the symbol with the same short name on the $ContextPath. If asymbol with the given short name exists on the context path, it will be used instead of thesymbol in the current context.The default context for Mathematica sessions is Global`.In[5]:=

$Context

Out[5]= Global`

Short names are sufficient for symbols that are in the current context.In[6]:=

8x, Global`x<

Out[6]= 8x, x<

Contexts in Mathematica work somewhat like file directories in many operating systems. Youcan always specify a particular file by giving its complete name, including its directory. But at

200

Core Language

Contexts in Mathematica work somewhat like file directories in many operating systems. Youcan always specify a particular file by giving its complete name, including its directory. But atany given point, there is usually a current working directory, analogous to the current Mathematica context. Files that are in this directory can then be specified just by giving their shortnames.Like directories in many operating systems, contexts in Mathematica can be hierarchical. Thus,for example, the full name of a symbol can involve a sequence of context names, as inc1 `c2 `c3 `name.context ` name or c1 ` c2 ` ` name

a symbol in an explicitly specified context

` name

a symbol in the current context

` context ` name or` c1 ` c2 ` ` name

a symbol in a specific context relative to the current context

name

a symbol in the current context, or found on the context

search path

Specifying symbols in various contexts.

Here is a symbol in the context a`b`.In[7]:=

a`b`x

Out[7]= a`b`x

When you start a Mathematica session, the default current context is Global`. Symbols thatyou introduce will usually be in this context. However, built-in symbols such as Pi are in thecontext System`.In order to let you easily access not only symbols in the context Global`, but also in contextssuch as System`, Mathematica supports the notion of a context search path. At any point in aMathematica session, there is both a current context $Context, and also a current contextsearch path $ContextPath. The idea of the search path is to allow you to type in the shortname of a symbol, then have Mathematica search in a sequence of contexts to find a symbolwith that short name.The context search path for symbols in Mathematica is analogous to the "search path" forprogram files provided in operating systems.

Core Language

201

The default context path includes the contexts for system-defined symbols.In[8]:=

$ContextPath

Out[8]= 8System`, Global`<

When you type in Pi , Mathematica interprets it as the symbol with full name System`Pi.In[9]:=

Context@PiD

Out[9]= System`

Context@sD

the context of a symbol

$Context

the current context in a Mathematica session

$ContextPath

the current context search path

Contexts@D

a list of all contexts

Finding contexts and context search paths.

When you use contexts in Mathematica, there is no reason that two symbols which are in different contexts cannot have the same short name. Thus, for example, you can have symbols withthe

short

name

Mole

both

in

the

context

PhysicalUnits`

and

in

the

context

BiologicalOrganisms`.There is, however, then the question of which symbol you actually get when you type in onlythe short name Mole. The answer to this question is determined by which of the contextscomes first in the sequence of contexts listed in the context search path.This introduces two symbols, both with short name Mole.In[10]:=

8PhysicalUnits`Mole, BiologicalOrganisms`Mole<

Out[10]= 8PhysicalUnits`Mole, BiologicalOrganisms`Mole<

This adds two additional contexts to $ContextPath . Typically, Mathematica adds new contextsto the beginning of $ContextPath .In[11]:=

Out[11]= 8PhysicalUnits`, BiologicalOrganisms`, System`, Global`<

Now if you type in Mole, you get the symbol in the context PhysicalUnits`.In[12]:=

Context@MoleD

Out[12]= PhysicalUnits`

In general, when you type in a short name for a symbol, Mathematica assumes that you wantthe symbol with that name whose context appears earliest in the context search path. As aresult, symbols with the same short name whose contexts appear later in the context search

202

Core Language

In general, when you type in a short name for a symbol, Mathematica assumes that you wantthe symbol with that name whose context appears earliest in the context search path. As aresult, symbols with the same short name whose contexts appear later in the context searchpath are effectively "shadowed". To refer to these symbols, you need to use their full names.Mathematica issues a message when you introduce new symbols that "shadow" existing symbols with your current choice for $ContextPath. In addition, in the notebook front end Mathematica warns you of shadowed symbols by coloring them red.This introduces a symbol with short name Mole in the context Global`. Mathematica warnsyou that the new symbol shadows existing symbols with short name Mole.In[13]:=

Global`MoleGlobal`Mole::shdw :Symbol Mole appears in multiple contexts 8Global`, PhysicalUnits`, BiologicalOrganisms`<;definitions in context Global` may shadow or be shadowed by other definitions.

Out[13]= Global`Mole

Now when you type in Mole, you get the symbol that appears first in the context path,PhysicalUnits`.In[14]:=

Context@MoleD

Out[14]= PhysicalUnits`

If you once introduce a symbol which shadows existing symbols, it will continue to do so untilyou either rearrange $ContextPath, or explicitly remove the symbol. You should realize that itis not sufficient to clear the value of the symbol; you need to actually remove the symbolcompletely from Mathematica. You can do this using the function Remove@sD.

Clear@sD

clear the values of a symbol

Remove@sD

remove a symbol completely from the system

Clearing and removing symbols in Mathematica.

This removes the symbol PhysicalUnits`Mole.In[15]:=

Remove@MoleD

Core Language

203

Now if you type in Mole, you get the symbol BiologicalOrganisms`Mole.

In[16]:=

Context@MoleD

Out[16]= BiologicalOrganisms`

When Mathematica prints out the name of a symbol, it has to choose whether to give the fullname, or just the short name. What it does is to give whatever version of the name you wouldhave to type in to get the particular symbol, given your current settings for $Context and$ContextPath.The short name is printed for the first symbol, so this would give that symbol if you typed it in.In[17]:=

8BiologicalOrganisms`Mole, Global`Mole<

Out[17]= 8Mole, Global`Mole<

If you type in a short name for which there is no symbol either in the current context, or in anycontext on the context search path, then Mathematica has to create a new symbol with thisname. It always puts new symbols of this kind in the current context, as specified by $Context.This introduces the new symbol with short name tree.In[18]:=

tree

Out[18]= tree

Mathematica puts tree in the current context Global`.

In[19]:=

Context@treeD

Out[19]= Global`

Contexts and Packages

A typical package written in Mathematica introduces several new symbols intended for useoutside the package. These symbols may correspond for example to new functions or newobjects defined in the package.There is a general convention that all new symbols introduced in a particular package are putinto a context whose name is related to the name of the package. When you read in the package, it adds this context at the beginning of your context search path $ContextPath.

This reads in a package for proving primality.

Out[2]= 8PrimalityProving`, System`, Global`<

The symbol ProvablePrimeQ is in the context set up by the package.

In[3]:=

Context@ProvablePrimeQD

Out[3]= PrimalityProving`

You can refer to the symbol using its short name.

In[4]:=

ProvablePrimeQ@2143D

Out[4]= True

The full names of symbols defined in packages are often quite long. In most cases, however,you will only need to use their short names. The reason for this is that after you have read in apackage, its context is added to $ContextPath, so the context is automatically searched whenever you type in a short name.There is a complication, however, when two symbols with the same short name appear in twodifferent packages. In such a case, Mathematica will warn you when you read in the secondpackage. It will tell you which symbols will be "shadowed" by the new symbols that are beingintroduced.The symbol ProvablePrimeQ in the context PrimalityProving` is shadowed by the symbolwith the same short name in the new package.In[5]:=

<< NewPrimalityProving`ProvablePrimeQ::shdw :Symbol ProvablePrimeQ appears in multiple contexts 8NewPrimalityProving`, PrimalityProving`<;definitions in context NewPrimalityProving` may shadow or be shadowed by other definitions.

You can access the shadowed symbol by giving its full name.In[6]:=

PrimalityProving`ProvablePrimeQ@2143D

Out[6]= True

Core Language

205

Conflicts can occur not only between symbols in different packages, but also between symbolsin packages and symbols that you introduce directly in your Mathematica session. If you definea symbol in your current context, then this symbol may become shadowed by another symbolwith the same short name in packages that you read in. The reason for this is that Mathematicasearches for symbols in contexts on the context search path before looking in the current context.This defines a function in the current context.In[7]:=Out[7]=

Div@f_D = 1 f1f

The Div function in your current context will be shadowed by the one in the package.In[8]:=

This sets up the coordinate system for vector analysis.

In[9]:=

SetCoordinates@Cartesian@x, y, zDD

Out[9]= Cartesian@x, y, zD

The Div from the package is used.

In[10]:=

Div@8x, y ^ 2, x<D

Out[10]= 1 + 2 y

If you get into the situation where unwanted symbols are shadowing the symbols you want, thebest thing to do is usually to get rid of the unwanted symbols using Remove@sD. An alternativethat is sometimes appropriate is to rearrange the entries in $ContextPath and to reset thevalue of $Context so as to make the contexts that contain the symbols you want be the onesthat are searched first.

$PackagesGetting a list of packages.

a list of the contexts corresponding to all packages loaded

into your Mathematica session

206

Core Language

Mathematica PackagesOne of the most important features of Mathematica is that it is an extensible system. There is acertain amount of mathematical and other functionality that is built into Mathematica. But byusing the Mathematica language, it is always possible to add more functionality.For many kinds of calculations, what is built into the standard version of Mathematica will bequite sufficient. However, if you work in a particular specialized area, you may find that youoften need to use certain functions that are not built into Mathematica.In such cases, you may well be able to find a Mathematica package that contains the functionsyou need. Mathematica packages are files written in the Mathematica language. They consist ofcollections of Mathematica definitions which "teach" Mathematica about particular applicationareas.

<<package

read in a Mathematica package

Reading in Mathematica packages.

If you want to use functions from a particular package, you must first read the package intoMathematica. The details of how to do this are discussed in "External Programs". There arevarious conventions that govern the names you should use to refer to packages.This command reads in a particular Mathematica package.In[1]:=

<< PrimalityProving`The ProvablePrimeQ function is defined in the package.

In[2]:=

ProvablePrimeQ@1093D

Out[2]= True

There are a number of subtleties associated with such issues as conflicts between names offunctions in different packages. These are discussed in "Contexts and Packages". One point tonote, however, is that you should not refer to a function that you will read from a packagebefore actually reading in the package. If you do this by mistake, Mathematica will issue amessage warning about the duplicate names and use the one last defined. This means thatyour version of the function will not be used; it will be the one from the package. You canexecute the command Remove@"name"D to get rid of the package function.

Core Language

Remove@"name"D

207

remove a function that has been introduced in error

Making sure that Mathematica uses correct definitions from packages.

The fact that Mathematica can be extended using packages means that the boundary of exactlywhat is "part of Mathematica" is quite blurred. As far as usage is concerned, there is actually nodifference between functions defined in packages and functions that are fundamentally builtinto Mathematica.In fact, a fair number of the functions built into the core Mathematica system are actuallyimplemented as Mathematica packages. However, on most Mathematica systems, the necessary packages have been preloaded, so that the functions they define are always present.To blur the boundary of what is part of Mathematica even further, "Automatic Loading of Packages" describes how you can tell Mathematica automatically to load a particular package if youever try to use a certain function. If you never use that function, then it will not be present. Butas soon as you try to use it, its definition will be read in from a Mathematica package.As a practical matter, the functions that should be considered "part of Mathematica" are probably those that are present in all Mathematica systems. It is these functions that are primarilydiscussed in this documentation.Nevertheless, most versions of Mathematica come with a standard set of Mathematica packages, which contain definitions for many more functions. To use these functions, you mustusually read in the necessary packages explicitly.

208

Core Language

You can use the Documentation Center to get information on Mathematica 7 Standard ExtraPackages.

It is possible to set your Mathematica system up so that particular packages are preloaded, orare automatically loaded when needed. If you do this, then there may be many functions thatappear as standard in your version of Mathematica, but which are not documented in the Mathematica system reference pages.One point that should be mentioned is the relationship between packages and notebooks. Bothare stored as files on your computer system, and both can be read into Mathematica. However,a notebook is intended to be displayed, typically with a notebook interface, while a package isintended only to be used as Mathematica input. Many notebooks in fact contain sections thatcan be considered as packages, and which contain sequences of definitions intended for input toMathematica. There are also capabilities that allow packages set up to correspond to notebooksto be maintained automatically.

Core Language

209

intended only to be used as Mathematica input. Many notebooks in fact contain sections thatcan be considered as packages, and which contain sequences of definitions intended for input toMathematica. There are also capabilities that allow packages set up to correspond to notebooksto be maintained automatically.

Setting Up Mathematica Packages

In a typical Mathematica package, there are generally two kinds of new symbols that are introduced. The first kind are ones that you want to export for use outside the package. The second kind are ones that you want to use only internally within the package. You can distinguishthese two kinds of symbols by putting them in different contexts.The usual convention is to put symbols intended for export in a context with a name Package`that corresponds to the name of the package. Whenever the package is read in, it adds thiscontext to the context search path, so that the symbols in this context can be referred to bytheir short names.Symbols that are not intended for export, but are instead intended only for internal use withinthe package, are conventionally put into a context with the name Package`Private`. This context is not added to the context search path. As a result, the symbols in this context cannot beaccessed except by giving their full names.

Package `

symbols for export

Package `Private`

symbols for internal use only

System`

built-in Mathematica symbols

Needed1 ` , Needed2 ` ,

other contexts needed in the package

Contexts conventionally used in Mathematica packages.

There is a standard sequence of Mathematica commands that is typically used to set up thecontexts in a package. These commands set the values of $Context and $ContextPath so thatthe new symbols which are introduced are created in the appropriate contexts.

210

Core Language

BeginPackage@"Package`"D

set Package ` to be the current context, and put only

System` on the context search path

f ::usage="text" ,

introduce the objects intended for export (and no others)

Begin@"`Private`"D

set the current context to Package `Private`

f AargsE=value ,

give the main body of definitions in the package

End@D

revert to the previous context (here Package `)

EndPackage@D

end the package, prepending the Package ` to the context

search path

The standard sequence of context control commands in a package.

BeginPackage["Collatz`"]Collatz::usage ="Collatz[n] gives a list of the iterates in the 3n+1 problem,starting from n. The conjecture is that this sequence alwaysterminates."Begin["`Private`"]Collatz[1] := {1}Collatz[n_Integer]

:= Prepend[Collatz[3 n + 1], n] /; OddQ[n] && n > 0

Collatz[n_Integer] := Prepend[Collatz[n/2], n] /; EvenQ[n] && n > 0

End[ ]EndPackage[ ]The sample package Collatz.m.

Defining usage messages at the beginning of a package is the standard way of making surethat symbols you want to export are created in the appropriate context. The way this works isthat in defining these messages, the only symbols you mention are exactly the ones you wantto export. These symbols are then created in the context Package`, which is then current.In the actual definitions of the functions in a package, there are typically many new symbols,introduced as parameters, temporary variables, and so on. The convention is to put all thesesymbols in the context Package`Private`, which is not put on the context search path when thepackage is read in.

Core Language

211

This reads in the sample package given above.

In[1]:=

<< ExampleData/Collatz.mThe EndPackage command in the package adds the context associated with the package to thecontext search path.

In[2]:=Out[2]=

$ContextPath8Collatz`, Global`, System`<

The Collatz function was created in the context Collatz`.

In[3]:=Out[3]=

Context@CollatzDCollatz`

The parameter n is put in the private context Collatz`Private`.

In[4]:=

? Collatz`Private`*

Collatz`Private`nIn the Collatz package, the functions that are defined depend only on built-in Mathematicafunctions. Often, however, the functions defined in one package may depend on functionsdefined in another package.Two things are needed to make this work. First, the other package must be read in, so that thefunctions needed are defined. And second, the context search path must include the contextthat these functions are in.You can explicitly tell Mathematica to read in a package at any point using the command<< context`. ("Files for Packages" discusses the tricky issue of translation from system-independent context names to system-dependent file names.) Often, however, you want to set it up sothat a particular package is read in only if it is needed. The command Needs@"context`"D tellsMathematica to read in a package if the context associated with that package is not already inthe list $Packages.

212

Core Language

GetA"context`"E or <<context `

read in the package corresponding to the specified context

Needs@"context`"D

read in the package if the specified context is not already

in $Packages

BeginPackage@"Package`",8" Needed1 ` ", <D

begin a package, specifying that certain contexts in addition to System` are neededFunctions for specifying interdependence of packages.

If you use BeginPackage@"Package`"D with a single argument, Mathematica puts on the contextsearch path only the Package` context and the contexts for built-in Mathematica symbols. If thedefinitions you give in your package involve functions from other packages, you must makesure that the contexts for these packages are also included in your context search path. Youcan do this by giving a list of the additional contexts as a second argument to BeginPackage.BeginPackage automatically calls Needs on these contexts, reading in the corresponding packages if necessary, and then making sure that the contexts are on the context search path.

Begin@"context`"D

switch to a new current context

End@D

revert to the previous context

Context manipulation functions.

Executing a function like Begin which manipulates contexts changes the way that Mathematicainterprets names you type in. However, you should realize that the change is effective only insubsequent expressions that you type in. The point is that Mathematica always reads in acomplete input expression, and interprets the names in it, before it executes any part of theexpression. As a result, by the time Begin is executed in a particular expression, the names inthe expression have already been interpreted, and it is too late for Begin to have an effect.The fact that context manipulation functions do not have an effect until the next completeexpression is read in means that you must be sure to give those functions as separate expressions, typically on separate lines, when you write Mathematica packages.The name x is interpreted before this expression is executed, so the Begin has no effect.In[5]:=

Begin@"a`"D; Print@Context@xDD; End@D

Global`Out[5]= a`

Context manipulation functions are used primarily as part of packages intended to be read intoMathematica. Sometimes, however, you may find it convenient to use such functions interactively.

Core Language

213

Context manipulation functions are used primarily as part of packages intended to be read intoMathematica. Sometimes, however, you may find it convenient to use such functions interactively.This can happen, for example, if you go into a dialog, say using TraceDialog , while executing afunction defined in a package. The parameters and temporary variables in the function aretypically in a private context associated with the package. Since this context is not on yourcontext search path, Mathematica will print out the full names of the symbols, and will requireyou to type in these full names in order to refer to the symbols. You can however useBegin@"Package`Private`"D to make the private context of the package your current context.This will make Mathematica print out short names for the symbols, and allow you to refer to thesymbols by their short names.

Files for Packages

When you create or use Mathematica packages, you will often want to refer to files in a systemindependent way. You can use contexts to do this.The basic idea is that on every computer system there is a convention about how files corresponding to Mathematica contexts should be named. Then, when you refer to a file using acontext, the particular version of Mathematica you are using converts the context name to thefile name appropriate for the computer system you are on.

<<context`

read in the file corresponding to the specified context

Using contexts to specify files.

This reads in one of the standard packages that come with Mathematica.In[1]:=

<< VectorAnalysis`

name.mx

file in DumpSave format

name.mx$SystemIDname.mx

file in DumpSave format for your computer system

name.m

file in Mathematica source format

nameinit.m

initialization file for a particular directory

dir

files in other directories specified by $Path

The typical sequence of files looked for by << name`.

Mathematica is set up so that << name` will automatically try to load the appropriate version of afile. It will first try to load a name.mx file that is optimized for your particular computer system.

214

Core Language

Mathematica is set up so that << name` will automatically try to load the appropriate version of afile. It will first try to load a name.mx file that is optimized for your particular computer system.If it finds no such file, then it will try to load a name.m file containing ordinary system-independent Mathematica input.If name is a directory, then Mathematica will try to load the initialization file init.m in thatdirectory. The purpose of the init.m file is to provide a convenient way to set up Mathematicapackages that involve many separate files. The idea is to allow you to give just the command<< name`, but then to load init.m to initialize the whole package, reading in whatever otherfiles are necessary.

Automatic Loading of Packages

Other tutorials have discussed explicit loading of Mathematica packages using << package andNeeds@packageD. Sometimes, however, you may want to set Mathematica up so that it automatically loads a particular package when the package is needed.You can use DeclarePackage to give the names of symbols which are defined in a particularpackage. Then, when one of these symbols is actually used, Mathematica will automatically loadthe package where the symbol is defined.

DeclarePackage@"context`",8"name1 ","name2 ",<D

declare that a package should automatically be loaded if asymbol with any of the names namei is usedArranging for automatic loading of packages.This specifies that the symbols Div, Grad and Curl are defined in VectorAnalysis` .In[1]:=

DeclarePackage@"VectorAnalysis`", 8"Div", "Grad", "Curl"<D

Out[1]= VectorAnalysis`

When you first use Grad , Mathematica automatically loads the package that defines it.In[2]:=

Grad@x ^ 2 + y ^ 2, Cartesian@x, y, zDD

Out[2]= 82 x, 2 y, 0<

When you set up a large collection of Mathematica packages, it is often a good idea to create anadditional names file which contains a sequence of DeclarePackage commands, specifyingpackages to load when particular names are used. Within a particular Mathematica session, youthen need to load explicitly only the names file. When you have done this, all the other packages will automatically be loaded if and when they are needed.

Core Language

215

When you set up a large collection of Mathematica packages, it is often a good idea to create anadditional names file which contains a sequence of DeclarePackage commands, specifyingpackages to load when particular names are used. Within a particular Mathematica session, youthen need to load explicitly only the names file. When you have done this, all the other packages will automatically be loaded if and when they are needed.DeclarePackage works by immediately creating symbols with the names you specify, but givingeach of these symbols the special attribute Stub. Whenever Mathematica finds a symbol withthe Stub attribute, it automatically loads the package corresponding to the context of thesymbol, in an attempt to find the definition of the symbol.

Manipulating Symbols and Contexts by Name

Symbol@"name"D

construct a symbol with a given name

SymbolName@symbD

find the name of a symbol

Converting between symbols and their names.

Here is the symbol x.In[1]:=

x InputForm

Out[1]//InputForm= x

Its name is a string.

In[2]:=

SymbolName@xD InputForm

Out[2]//InputForm= "x"

This gives the symbol x again.

In[3]:=

Symbol@"x"D InputForm

Out[3]//InputForm= x

Once you have made an assignment such as x = 2, then whenever x is evaluated, it is replacedby 2. Sometimes, however, you may want to continue to refer to x itself, without immediatelygetting the value of x.You can do this by referring to x by name. The name of the symbol x is the string "x", andeven though x itself may be replaced by a value, the string "x" will always stay the same.The names of the symbols x and xp are the strings "x" and "xp".

216

Core Language

The names of the symbols x and xp are the strings "x" and "xp".In[4]:=

t = 8SymbolName@xD, SymbolName@xpD< InputForm

Out[4]//InputForm= {"x", "xp"}

This assigns a value to x.

In[5]:=

x=2

Out[5]= 2

Whenever you enter x it is now replaced by 2.

In[6]:=

8x, xp< InputForm

Out[6]//InputForm= {2, xp}

The name "x" is not affected, however.

In[7]:=

t InputForm

Out[7]//InputForm= InputForm[{"x", "xp"}]

NameQ@" form"D

test whether any symbol has a name which matches form

Names@" form"D

give a list of all symbol names which match form

Contexts@" form`"D

give a list of all context names which match form

Referring to symbols and contexts by name.

x and xp are symbols that have been created in this Mathematica session; xpp is not.In[8]:=

8NameQ@"x"D, NameQ@"xp"D, NameQ@"xpp"D<

Out[8]= 8True, True, False<

You can specify the form of symbol names using string patterns of the kind discussed in "StringPatterns". "x*" stands, for example, for all names that start with x.This gives a list of all symbol names in this Mathematica session that begin with x.In[9]:=

clear the values of all symbols in the specified context

remove completely all symbols whose names match form

remove completely all symbols in the specified context

Getting rid of symbols by name.

This clears the values of all symbols whose names start with x.In[12]:=

Clear@"x*"DThe name "x" is still known, however.

In[13]:=

Names@"x*"D

Out[13]= 8x, xp<

But the value of x has been cleared.

In[14]:=

8x, xp<

Out[14]= 8x, xp<

This removes completely all symbols whose names start with x.

In[15]:=

Remove@"x*"DNow not even the name "x" is known.

In[16]:=

Names@"x*"D

Out[16]= 8<

Remove@"Global`*"D

remove completely all symbols in the Global` context

Removing all symbols you have introduced.

If you do not set up any additional contexts, then all the symbols that you introduce in a Mathematica session will be placed in the Global` context. You can remove these symbols completelyusing Remove@"Global`*"D. Built-in Mathematica objects are in the System` context, and arethus unaffected by this.

Intercepting the Creation of New Symbols

218

Core Language

Intercepting the Creation of New Symbols

Mathematica creates a new symbol when you first enter a particular name. Sometimes it isuseful to intercept the process of creating a new symbol. Mathematica provides several waysto do this.

OnAGeneral::newsymE

print a message whenever a new symbol is created

OffAGeneral::newsymE

switch off the message printed when new symbols are

created

Printing a message when new symbols are created.

This tells Mathematica to print a message whenever a new symbol is created.In[1]:=

On@General::newsymDMathematica now prints a message about each new symbol that it creates.

This switches off the message.

In[3]:=

Off@General::newsymD

Generating a message when Mathematica creates a new symbol is often a good way to catchtyping mistakes. Mathematica itself cannot tell the difference between an intentionally newname, and a misspelling of a name it already knows. But by reporting all new names it encounters, Mathematica allows you to see whether any of them are mistakes.

$NewSymbol

a function to be applied to the name and context of new

symbols which are created

Performing operations when new symbols are created.

Core Language

219

When Mathematica creates a new symbol, you may want it not just to print a message, butinstead to perform some other action. Any function you specify as the value of the global variable $NewSymbol will automatically be applied to strings giving the name and context of eachnew symbol that Mathematica creates.This defines a function to be applied to each new symbol which is created.In[4]:=

$NewSymbol = Print@"Name: ", 1, " Context: ", 2D &

Out[4]= Print@Name: , 1,

Context: , 2D &

The function is applied once to v and once to w.

In[5]:=

v+w

Name: v Context: Global`

Name: w Context: Global`Out[5]= v + w

220

Core Language

Strings and Characters

Properties of StringsMuch of what Mathematica does revolves around manipulating structured expressions. But youcan also use Mathematica as a system for handling unstructured strings of text.a string containing arbitrary text

"text"Text strings.

When you input a string of text to Mathematica you must always enclose it in quotes. However,when Mathematica outputs the string it usually does not explicitly show the quotes.You can see the quotes by asking for the input form of the string. In addition, in a Mathematicanotebook, quotes will typically appear automatically as soon as you start to edit a string.When Mathematica outputs a string, it usually does not explicitly show the quotes.In[1]:=Out[1]=

"This is a string."This is a string.

You can see the quotes, however, by asking for the input form of the string.In[2]:=

InputForm@%D

Out[2]//InputForm=

"This is a string."

The fact that Mathematica does not usually show explicit quotes around strings makes it possible for you to use strings to specify quite directly the textual output you want.The strings are printed out here without explicit quotes.In[3]:=

Print@"The value is ", 567, "."D

The value is 567.

You should understand, however, that even though the string "x" often appears as x in output,it is still a quite different object from the symbol x.

Core Language

221

The string "x" is not the same as the symbol x.

In[4]:=Out[4]=

"x" === xFalse

You can test whether any particular expression is a string by looking at its head. The head ofany string is always String.All strings have head String.In[5]:=Out[5]=

Head@"x"DString

The pattern _String matches any string.

In[6]:=

Cases@8"ab", x, "a", y<, _StringD

Out[6]= 8ab, a<

You can use strings just like other expressions as elements of patterns and transformations.Note, however, that you cannot assign values directly to strings.This gives a definition for an expression that involves a string.In[7]:=

z@"gold"D = 79

Out[7]= 79

This replaces each occurrence of the string "aa" by the symbol x.

In[8]:=Out[8]=

8"aaa", "aa", "bb", "aa"< . "aa" -> x

8aaa, x, bb, x<

Operations on StringsMathematica provides a variety of functions for manipulating strings. Most of these functionsare based on viewing strings as a sequence of characters, and many of the functions are analogous to ones for manipulating lists.

222

Core Language

s1 <>s2 <> orStringJoin@8s1 ,s2 ,<D

join several strings together

StringLength@sD

give the number of characters in a string

StringReverse@sD

reverse the characters in a string

Operations on complete strings.

You can join together any number of strings using <>.In[1]:=

"aaaaaaa" <> "bbb" <> "cccccccccc"

Out[1]= aaaaaaabbbcccccccccc

StringLength gives the number of characters in a string.

In[2]:=

StringLength@%D

Out[2]= 20

StringReverse reverses the characters in a string.

In[3]:=

StringReverse@"A string."D

Out[3]= .gnirts A

StringTake@s,nD

make a string by taking the first n characters from s

StringTake@s,8n<D

take the nth character from s

StringTake@s,8n1 ,n2 <D

take characters n1 through n2

StringDrop@s,nD

make a string by dropping the first n characters in s

StringDrop@s,8n1 ,n2 <D

drop characters n1 through n2

Taking and dropping substrings.

StringTake and StringDrop are the analogs for strings of Take and Drop for lists. Like Takeand Drop, they use standard Mathematica sequence specifications, so that, for example, negative numbers count character positions from the end of a string. Note that the first character ofa string is taken to have position 1.Here is a sample string.In[4]:=

alpha = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"

Out[4]= ABCDEFGHIJKLMNOPQRSTUVWXYZ

Core Language

223

This takes the first five characters from alpha.

In[5]:=

StringTake@alpha, 5D

Out[5]= ABCDE

Here is the fifth character in alpha.

In[6]:=

StringTake@alpha, 85<D

Out[6]= E

This drops the characters 10 through 2, counting from the end of the string.In[7]:=

StringDrop@alpha, 8- 10, - 2<D

Out[7]= ABCDEFGHIJKLMNOPZ

StringInsert@s,snew,nD

insert the string snew at position n in s

StringInsert@s,snew,8n1 ,n2 ,<D

insert several copies of snew into sInserting into a string.

StringInsert@s, snew, nD is set up to produce a string whose nth character is the first characterof snew.This produces a new string whose fourth character is the first character of the string "XX".In[8]:=

StringInsert@"abcdefgh", "XX", 4D

Out[8]= abcXXdefgh

Negative positions are counted from the end of the string.

In[9]:=

StringInsert@"abcdefgh", "XXX", - 1D

Out[9]= abcdefghXXX

Each copy of "XXX" is inserted at the specified position in the original string.In[10]:=

StringInsert@"abcdefgh", "XXX", 82, 4, - 1<D

Out[10]= aXXXbcXXXdefghXXX

This uses Riffle to add a space between the words in a list.

In[11]:=

StringJoin@Riffle@8"cat", "in", "the", "hat"<, " "DD

Out[11]= cat in the hat

224

Core Language

StringReplacePart@s,snew,8m,n<D

replace the characters at positions m through n in s by the

string snew

StringReplacePart@s,snew,88m1 ,n1 <,8m2 ,n2 <,<D

replace several substrings in s by snew

StringReplacePart@s,8snew1 ,snew2 ,<,88m1 ,n1 <,8m2 ,n2 <,<D

replace substrings in s by the corresponding snewi

Replacing parts of a string.

This replaces characters 2 through 6 by the string "XXX".In[12]:=

StringReplacePart@"abcdefgh", "XXX", 82, 6<D

Out[12]= aXXXgh

This replaces two runs of characters by the string "XXX".

In[13]:=

StringReplacePart@"abcdefgh", "XXX", 882, 3<, 85, - 1<<D

Out[13]= aXXXdXXX

Now the two runs of characters are replaced by different strings.

In[14]:=

StringReplacePart@"abcdefgh", 8"XXX", "YYYY"<, 882, 3<, 85, - 1<<D

Out[14]= aXXXdYYYY

StringPosition@s,subD

give a list of the starting and ending positions at which sub

appears as a substring of s

StringPosition@s,sub,kD

include only the first k occurrences of sub in s

StringPosition@s,8sub1 ,sub2 ,<D

include occurrences of any of the subiFinding positions of substrings.

You can use StringPosition to find where a particular substring appears within a given string.StringPosition returns a list, each of whose elements corresponds to an occurrence of thesubstring. The elements consist of lists giving the starting and ending character positions forthe substring. These lists are in the form used as sequence specifications in StringTake,StringDrop and StringReplacePart.

Core Language

This gives a list of the positions of the substring "abc".

In[15]:=

StringPosition@"abcdabcdaabcabcd", "abc"D

Out[15]= 881, 3<, 85, 7<, 810, 12<, 813, 15<<

This gives only the first occurrence of "abc".

In[16]:=

StringPosition@"abcdabcdaabcabcd", "abc", 1D

Out[16]= 881, 3<<

This shows where both "abc" and "cd" appear. By default, overlaps are included.In[17]:=

StringPosition@"abcdabcdcd", 8"abc", "cd"<D

Out[17]= 881, 3<, 83, 4<, 85, 7<, 87, 8<, 89, 10<<

This does not include overlaps.

In[18]:=

StringPosition@"abcdabcdcd", 8"abc", "cd"<, Overlaps -> FalseD

Out[18]= 881, 3<, 85, 7<, 89, 10<<

StringCount @s,subD

count the occurrences of sub in s

StringCount @s,8sub1 ,sub2 ,<D

count occurrences of any of the subi

StringFreeQ @s,subD

test whether s is free of sub

StringFreeQ @s,8sub1 ,sub2 ,<D

test whether s is free of all the subi

Testing for substrings.

This counts occurrences of either substring, by default not including overlaps.In[19]:=

StringCount@"abcdabcdcd", 8"abc", "cd"<D

Out[19]= 3

StringReplace@s,sb->sbnewD

replace sb by sbnew wherever it appears in s

StringReplace@s,8sb1 ->sbnew1 ,sb2 ->sbnew2 ,<D

replace sbi by the corresponding sbnewi

StringReplace@s,rules,nD

do at most n replacements

StringReplaceList@s,rulesD

give a list of the strings obtained by making each possible

single replacement

StringReplaceList@s,rules,nD

give at most n results

Replacing substrings according to rules.

This replaces all occurrences of the character a by the string XX.

225

226

Core Language

This replaces all occurrences of the character a by the string XX.

In[20]:=

StringReplace@"abcdabcdaabcabcd", "a" -> "XX"D

Out[20]= XXbcdXXbcdXXXXbcXXbcd

This replaces abc by Y, and d by XXX.

In[21]:=

StringReplace@"abcdabcdaabcabcd", 8"abc" -> "Y", "d" -> "XXX"<D

Out[21]= YXXXYXXXaYYXXX

The first occurrence of cde is not replaced because it overlaps with abc.In[22]:=

StringReplace@"abcde abacde", 8"abc" -> "X", "cde" -> "Y"<D

Out[22]= Xde abaY

StringReplace scans a string from left to right, doing all the replacements it can, and thenreturning the resulting string. Sometimes, however, it is useful to see what all possible singlereplacements would give. You can get a list of all these results using StringReplaceList.This gives a list of the results of replacing each of the as.In[23]:=

StringReplaceList@"aaaaa", "a" -> "X"D

Out[23]= 8Xaaaa, aXaaa, aaXaa, aaaXa, aaaaX<

This shows the results of all possible single replacements.

In[24]:=

StringReplaceList@"abcde abacde", 8"abc" -> "X", "cde" -> "Y"<D

Out[24]= 8Xde abacde, abY abacde, abcde abaY<

StringSplit @sD

split s into substrings delimited by whitespace

StringSplit @s,delD

split at delimiter del

StringSplit @s,8del1 ,del2 ,<D

split at any of the deli

StringSplit @s,del,nD

split into at most n substrings

Splitting strings.This splits the string at every run of spaces.In[25]:=

StringSplit@"a b::c d::e f g"D

Out[25]= 8a, b::c, d::e, f, g<

Core Language

This splits at each "::".

In[26]:=

StringSplit@"a b::c d::e f g", "::"D

Out[26]= 8a b, c d, e f g<

This splits at each colon or space.

In[27]:=

StringSplit@"a b::c d::e f g", 8":", " "<D

Out[27]= 8a, b, , c, d, , e, f, g<

StringSplit @s,del->rhsD

insert rhs at the position of each delimiter

StringSplit @s,8del1 ->rhs1 ,del2 ->rhs2 ,<D

insert rhsi at the position of the corresponding deli

Splitting strings with replacements for delimiters.

This inserts 8x, y< at each :: delimiter.In[28]:=

StringSplit@"a b::c d::e f g", "::" -> 8x, y<D

Out[28]= 8a b, 8x, y<, c d, 8x, y<, e f g<

sort a list of strings

Sort@8s1 ,s2 ,s3 ,<D

Sorting strings.

Sort sorts strings into standard dictionary order.

In[29]:=

Sort@8"cat", "fish", "catfish", "Cat"<D

Out[29]= 8cat, Cat, catfish, fish<

StringTrim@sD

trims whitespace from the beginning and end of s

StringTrim@s,pattD

trims substrings matching patt from the beginning and end

Remove whitespace from ends of string.

In[30]:=

StringTrim@"

abcabc

"D FullForm

Out[30]//FullForm= "abcabc"

SequenceAlignment@s1 ,s2 D

finds an optimal alignment of s1 and s2

227

228

Core Language

Find an optimal alignment of two strings.

In[31]:=

SequenceAlignment@"abcXabcXabc", "abcYabcYabc"D

Out[31]= 8abc, 8X, Y<, abc, 8X, Y<, abc<

Characters in StringsCharacters@"string"D

convert a string to a list of characters

StringJoin@8"c1 ","c2 ",<D

convert a list of characters to a string

Converting between strings and lists of characters.

This gives a list of the characters in the string.In[1]:=Out[1]=

Characters@"A string."D8A,

, s, t, r, i, n, g, .<

You can apply standard list manipulation operations to this list.

In[2]:=Out[2]=

RotateLeft@%, 3D8t, r, i, n, g, ., A,

, s<

StringJoin converts the list of characters back to a single string.

In[3]:=Out[3]=

StringJoin@%Dtring.A s

DigitQ@stringD

test whether all characters in a string are digits

LetterQ@stringD

test whether all characters in a string are letters

UpperCaseQ@stringD

test whether all characters in a string are uppercase letters

LowerCaseQ@stringD

test whether all characters in a string are lowercase letters

Testing characters in a string.

All characters in the string given are letters.In[4]:=Out[4]=

LetterQ@"Mixed"DTrue

Core Language

229

Not all the letters are uppercase, so the result is False .

In[5]:=Out[5]=

UpperCaseQ@"Mixed"DFalse

ToUpperCase @stringD

generate a string in which all letters are uppercase

ToLowerCase @stringD

generate a string in which all letters are lowercase

Converting between upper and lower case.

This converts all letters to upper case.In[6]:=Out[6]=

ToUpperCase@"Mixed Form"DMIXED FORM

CharacterRange@"c1 ","c2 "D

generate a list of all characters from c1 and c2

Generating ranges of characters.

This generates a list of lowercase letters in alphabetical order.In[7]:=Out[7]=

CharacterRange@"a", "h"D8a, b, c, d, e, f, g, h<

Here is a list of uppercase letters.

In[8]:=

CharacterRange@"T", "Z"D

Out[8]= 8T, U, V, W, X, Y, Z<

Here are some digits.

In[9]:=Out[9]=

CharacterRange@"0", "7"D80, 1, 2, 3, 4, 5, 6, 7<

CharacterRange will usually give meaningful results for any range of characters that have anatural ordering. The way CharacterRange works is by using the character codes that Mathemat ica internally assigns to every character.This shows the ordering defined by the internal character codes used by Mathematica.In[10]:=Out[10]=

String PatternsAn important feature of string manipulation functions like StringReplace is that they handlenot only literal strings but also patterns for collections of strings.This replaces b or c by X.In[1]:=Out[1]=

StringReplace@"abcd abcd", "b"

"c" -> "X"D

aXXd aXXd

This replaces any character by u.

In[2]:=Out[2]=

StringReplace@"abcd abcd", _ -> "u"D

uuuuuuuuu

You can specify patterns for strings by using string expressions that contain ordinary stringsmixed with Mathematica symbolic pattern objects.s1 ~~s2 ~~ or

StringExpression@s1 ,s2 ,Da sequence of strings and pattern objects

String expressions.Here is a string expression that represents the string ab followed by any single character.In[3]:=

"ab" ~~ _

Out[3]= ab ~~ _

This makes a replacement for each occurrence of the string pattern.

In[4]:=Out[4]=

StringReplace@"abc abcb abdc", "ab" ~~ _ -> "X"D

X Xb Xc

Core Language

StringMatchQ@"s",pattD

test whether "s" matches patt

StringFreeQ @"s",pattD

test whether "s" is free of substrings matching patt

StringCases @"s",pattD

give a list of the substrings of "s" that match patt

StringCases @"s",lhs->rhsD

replace each case of lhs by rhs

StringPosition@"s",pattD

give a list of the positions of substrings that match patt

StringCount @"s",pattD

count how many substrings match patt

StringReplace@"s",lhs->rhsD

replace every substring that matches lhs

231

StringReplaceList@"s",lhs->rhsDgive a list of all ways of replacing lhs

StringSplit @"s",pattD

split s at every substring that matches patt

StringSplit @"s",lhs->rhsD

split at lhs, inserting rhs in its place

Functions that support string patterns.

This gives all cases of the pattern that appear in the string.In[5]:=Out[5]=

StringCases@"abc abcb abdc", "ab" ~~ _D

8abc, abc, abd<

This gives each character that appears after an "ab" string.

In[6]:=Out[6]=

StringCases@"abc abcb abdc", "ab" ~~ x_ -> xD

8c, c, d<

This gives all pairs of identical characters in the string.

In[7]:=

StringCases@"abbcbccaabbabccaa", x_ ~~ x_D

Out[7]= 8bb, cc, aa, bb, cc, aa<

You can use all the standard Mathematica pattern objects in string patterns. Single blanks (_)always stand for single characters. Double blanks (__) stand for sequences of one or morecharacters.Single blank (_) stands for any single character.In[8]:=Out[8]=

StringReplace@8"ab", "abc", "abcd"<, "b" ~~ _ -> "X"D

8ab, aX, aXd<

232

Core Language

Double blank (__) stands for any sequence of one or more characters.StringReplace@8"ab", "abc", "abcd"<, "b" ~~ __ -> "X"D

This picks out all characters except digits.

This picks out all runs of one or more digits.

StringCases@"a6;b23c456", DigitCharacter ..D

86, 23, 456<

The results are strings.

In[20]:=

InputForm@%D

Out[20]//InputForm=

{"6", "23", "456"}

This converts the strings to numbers.

In[21]:=Out[21]=

ToExpression@%D + 187, 24, 457<

String patterns are often used as a way to extract structure from strings of textual data. Typically this works by having different parts of a string pattern match substrings that correspondto different parts of the structure.This picks out each = followed by a number.In[22]:=Out[22]=

ToExpression converts them to ordinary symbols and numbers.

In many situations, textual data may contain sequences of spaces, newlines or tabs that shouldbe considered whitespace, and perhaps ignored. In Mathematica, the symbol Whitespace

Core Language

235

In many situations, textual data may contain sequences of spaces, newlines or tabs that shouldbe considered whitespace, and perhaps ignored. In Mathematica, the symbol Whitespacestands for any such sequence.This removes all whitespace from the string.In[26]:=Out[26]=

StringReplace@"aa b cc d", Whitespace -> ""D

aabccd

This replaces each sequence of spaces by a single comma.

In[27]:=Out[27]=

StringReplace@"aa b cc d", Whitespace -> ","D

aa,b,cc,d

String patterns normally apply to substrings that appear at any position in a given string. Sometimes, however, it is convenient to specify that patterns can apply only to substrings at particular positions. You can do this by including symbols such as StartOfString in your string patterns.

StartOfString

start of the whole string

EndOfString

end of the whole string

StartOfLine

start of a line

EndOfLine

end of a line

WordBoundary

boundary between word characters and others

ExceptAStartOfStringE , etc.

anywhere except at the particular positions

StartOfString , etc.

Constructs representing special positions in a string.

This replaces "a" wherever it appears in a string.In[28]:=Out[28]=

StringReplace@8"abc", "baca"<, "a" -> "XX"D

8XXbc, bXXcXX<

This replaces "a" only when it immediately follows the start of a string.In[29]:=Out[29]=

StringReplace@8"abc", "baca"<, StartOfString ~~ "a" -> "XX"D

8XXbc, baca<

236

Core Language

This replaces all occurrences of the substring "the".

In[30]:=Out[30]=

StringReplace@"the others", "the" -> "XX"D

XX oXXrs

This replaces only occurrences that have a word boundary on both sides.In[31]:=Out[31]=

String patterns allow the same kind of ; and other conditions as ordinary Mathematica patterns.This gives cases of unequal successive characters in the string.In[32]:=

StringCases@"aaabbcaaaabaaa", x_ ~~ y_ ; x != yD

Out[32]= 8ab, bc, ab<

When you give an object such as x__ or e .. in a string pattern, Mathematica normally assumesthat you want this to match the longest possible sequence of characters. Sometimes, however,you may instead want to match the shortest possible sequence of characters. You can specifythis using Shortest@pD.

Longest@pD

the longest consistent match for p (default)

Shortest@pD

the shortest consistent match for p

Objects representing longest and shortest matches.

The string pattern by default matches the longest possible sequence of characters.In[33]:=

StringCases@"-HaL--HbbL--HcL-", "H" ~~ __ ~~ "L"D

Out[33]= 8HaL--HbbL--HcL<

Shortest specifies that instead the shortest possible match should be found.In[34]:=Out[34]=

StringCases@"-HaL--HbbL--HcL-", Shortest@"H" ~~ __ ~~ "L"DD

8HaL, HbbL, HcL<

Mathematica by default treats characters such "X" and "x" as distinct. But by setting the optionIgnoreCase -> True in string manipulation operations, you can tell Mathematica to treat allsuch uppercase and lowercase letters as equivalent.

Core Language

237

treat uppercase and lowercase letters as equivalent

IgnoreCase->True

Specifying case-independent string operations.

This replaces all occurrences of "the", independent of case.In[35]:=Out[35]=

StringCases@"abcd", __, Overlaps -> FalseD

This yields a succession of overlapping matches.

StringCases@"abcd", __, Overlaps -> TrueD

This includes all possible overlapping matches.

but

238

Core Language

This includes all possible overlapping matches.

In[41]:=Out[41]=

StringCases@"abcd", __, Overlaps -> AllD

8abcd, abc, ab, a, bcd, bc, b, cd, c, d<

Regular ExpressionsGeneral Mathematica patterns provide a powerful way to do string manipulation. But particularly if you are familiar with specialized string manipulation languages, you may sometimes findit convenient to specify string patterns using regular expression notation. You can do this inMathematica with RegularExpression objects.

RegularExpression@"regex"D

a regular expression specified by "regex"

Using regular expression notation in Mathematica.

This replaces all occurrences of a or b.In[1]:=Out[1]=

StringReplace@"abcd acbd", RegularExpression@"@abD"D -> "XX"D

XXXXcd XXcXXd

This specifies the same operation using a general Mathematica string pattern.In[2]:=Out[2]=

Basic constructs in Mathematica regular expressions.

This does the same operation with a general Mathematica string pattern.In[5]:=Out[5]=

StringCases@"abcddbbbacbbaa", H"a"

"bb"L ..D

8a, bb, a, bbaa<

There is a close correspondence between many regular expression constructs and basic generalMathematica string pattern constructs.

240

Core Language

_ (strictly Except@"n"D )

@c1 c2 D

Characters@" c1 c2 "D

@c1 -c2 D

CharacterRange@"c1 ","c2 "D

@^c1 c2 D

ExceptACharacters@" c1 c2 "DE

p*p+

p...p..

p?

p ""

p*?, p+?, p ??Hp1 p2 Lp1 p2

Shortest@pD,Hp1 ~~p2 ~~Lp1 p2

Correspondences between regular expression and general string pattern constructs.

Just as in general Mathematica string patterns, there are special notations in regular expressions for various common classes of characters. Note that you need to use double backslashes( ) to enter most of these notations in Mathematica regular expression strings.

\\ d

digit 0|9 (DigitCharacter)

\\ D

non-digit (Except@DigitCharacterD)

\\ s

space, newline, tab or other whitespace character

(WhitespaceCharacter )

\\ S

non-whitespace character(Except@WhitespaceCharacterD)

\\ w

word character (letter, digit or _) (WordCharacter )

\\ W

non-word character (Except@WordCharacterD)

@@:class:DD

characters in a named class

@^@:class:DD

characters not in a named class

Regular expression notations for classes of characters.

This gives each occurrence of a followed by digit characters.In[6]:=Out[6]=

StringCases@"a10b6a77a3a", RegularExpression@"a\\d+"DD8a10, a77, a3<

Here is the same thing done with a general Mathematica string pattern.In[7]:=Out[7]=

This does the same thing.

StringCases@"AaBBccDDeefG", CharacterRange@"A", "Z"D ..D

the beginning of the string (StartOfString )

the end of the string (EndOfString )

\\ b

word boundary (WordBoundary )

\\ B

anywhere except a word boundary

(Except@WordBoundaryD)

Regular expression notations for positions in strings.

In general Mathematica patterns, you can use constructs like x_ and x : patt to give arbitrarynames to objects that are matched. In regular expressions, there is a way to do somethingsomewhat like this using numbering: the nth parenthesized pattern object HpL in a regularexpression can be referred to as \\ n within the body of the pattern, and $n outside it.This finds pairs of identical letters that appear together.In[10]:=Out[10]=

This does the same thing using a general Mathematica string pattern.In[11]:=Out[11]=

StringCases@"aaabcccabbaacba", x_ ~~ x_D8aa, cc, bb, aa<

The $1 refers to the letter matched by H.L.

In[12]:=Out[12]=

StringCases@"aaabcccabbaacba", RegularExpression@"H.L\\1"D -> "$1"D

8a, c, b, a<

242

Core Language

Here is the Mathematica pattern version.

In[13]:=Out[13]=

StringCases@"aaabcccabbaacba", x_ ~~ x_ -> xD8a, c, b, a<

Special CharactersIn addition to the ordinary characters that appear on a standard keyboard, you can include inMathematica strings any of the special characters that are supported by Mathematica.Here is a string containing special characters.In[1]:=

"ab"

Out[1]= ab

You can manipulate this string just as you would any other.In[2]:=

StringReplace@%, "" -> " "D

Out[2]= a b

Here is the list of the characters in the string.

In[3]:=

Characters@%D

Out[3]= 8a,

, , ,

, b,

, , ,

, <

In a Mathematica notebook, a special character such as a can always be displayed directly. Butif you use a text-based interface, then typically the only characters that can readily be displayed are the ones that appear on your keyboard.As a result, what Mathematica does in such situations is to try to approximate special characters by similar-looking sequences of ordinary characters. And when this is not practical, Mathematica just gives the full name of the special character.In a Mathematica notebook using StandardForm , special characters can be displayed directly.In[4]:=

"Lam ab+"

Out[4]= Lam ab+

Core Language

243

In OutputForm , however, the special characters are approximated when possible by sequencesof ordinary ones.In[5]:=

% OutputForm

Out[5]//OutputForm= Lam ab+

Mathematica always uses full names for special characters in InputForm. This means that whenspecial characters are written out to files or external programs, they are by default representedpurely as sequences of ordinary characters.This uniform representation is crucial in allowing special characters in Mathematica to be usedin a way that does not depend on the details of particular computer systems.In InputForm the full names of all special characters are always written out explicitly.In[6]:=

"Lam ab+" InputForm

Out[6]//InputForm= "Lam ab+"

a literal character

@NameD

a character specified using its full name

"

a " to be included in a string

a to be included in a string

Ways to enter characters in a string.

You have to use to escape any " or characters in strings that you enter.In[7]:=

"Strings can contain \"quotes\" and \\ characters."

Out[7]= Strings can contain "quotes" and \ characters.

produces a literal rather than forming part of the specification of a.

In[8]:=

"\\@AlphaD is a."

Out[8]= \[Alpha] is a.

This breaks the string into a list of individual characters.

In[9]:=

Characters@%D

Out[9]= 9\, @, A, l, p, h, a, D,

, i, s,

, a, .=

244

Core Language

This creates a list of the characters in the full name of a.

In[10]:=

Characters@ToString@FullForm@"a"DDD

Out[10]= 9", \, @, A, l, p, h, a, D, "=

And this produces a string consisting of an actual a from its full name.In[11]:=

ToExpression@"\"\\@" <> "Alpha" <> "D\""D

Out[11]= a

Newlines and Tabs in Strings

n

a newline (line feed) to be included in a string

a tab to be included in a string

Explicit representations of newlines and tabs in strings.

This prints on two lines.In[1]:=Out[1]=

"First line.\nSecond line."

First line.Second line.

In InputForm there is an explicit n to represent the newline.

In[2]:=

InputForm@%D

Out[2]//InputForm=

"First line.\nSecond line."

Mathematica keeps line breaks entered within a string.

In[3]:=

"A string ontwo lines."

Out[3]= A string on

two lines.

There is a newline in the string.

In[4]:=

InputForm@%D

Out[4]//InputForm= "A string on \ntwo lines."

Core Language

245

With a single backslash at the end of a line, Mathematica ignores the line break.In[5]:=

"A string on \one line."

Out[5]= A string on one line.

You should realize that even though it is possible to achieve some formatting of Mathematicaoutput by creating strings which contain raw tabs and newlines, this is rarely a good idea.Typically a much better approach is to use the higher-level Mathematica formatting primitivesdiscussed in "String-Oriented Output Formats", "Output Formats for Numbers", and "Tables andMatrices". These primitives will always yield consistent output, independent of such issues asthe positions of tab settings on a particular device.In strings with newlines, text is always aligned on the left.In[6]:=Out[6]=

8"Here is\na string\non several lines.", "Here is\nanother"<

8Here isa stringon several lines., Here isanother<

The front end formatting construct Column gives more control. Here text is aligned on the right.In[7]:=

Column@8"First line", "Second", "Third"<, RightD

First lineSecondOut[7]=Third

And here the text is centered.

In[8]:=

Out[8]=

Column@8"First line", "Second", "Third"<, CenterD

First lineSecondThird

246

Core Language

Character CodesToCharacterCode@"string"D

give a list of the character codes for the characters in a

string

FromCharacterCode@nD

construct a character from its character code

FromCharacterCode@8n1 ,n2 ,<D

construct a string of characters from a list of charactercodesConverting to and from character codes.

Mathematica assigns every character that can appear in a string a unique character code. Thiscode is used internally as a way to represent the character.This gives the character codes for the characters in the string.In[1]:=

ToCharacterCode@"ABCD abcd"D

Out[1]= 865, 66, 67, 68, 32, 97, 98, 99, 100<

FromCharacterCode reconstructs the original string.

In[2]:=

FromCharacterCode@%D

Out[2]= ABCD abcd

Special characters also have character codes.

In[3]:=

ToCharacterCode@"aG"D

Out[3]= 8945, 8853, 915, 8854, 8709<

CharacterRange@"c1 ","c2 "D

generate a list of characters with successive character

codes

Generating sequences of characters.

This gives part of the English alphabet.In[4]:=

CharacterRange@"a", "k"D

Out[4]= 8a, b, c, d, e, f, g, h, i, j, k<

Core Language

247

Here is the Greek alphabet.

Mathematica assigns names such as @AlphaD to a large number of special characters. Thismeans that you can always refer to such characters just by giving their names, without everhaving to know their character codes.This generates a string of special characters from their character codes.In[6]:=

FromCharacterCode@88706, 8709, 8711, 8712<D

Out[6]=

You can always refer to these characters by their names, without knowing their charactercodes.In[7]:=

FullForm@%D

Out[7]//FullForm= "\@PartialDD\[EmptySet]\@DelD\@ElementD"

Mathematica has names for all the common characters that are used in mathematical notationand in standard European languages. But for a language such as Japanese, there are more than3,000 additional characters, and Mathematica does not assign an explicit name to each ofthem. Instead, it refers to such characters by standardized character codes.Here is a string containing Japanese characters.In[8]:=

""

Out[8]=

In FullForm , these characters are referred to by standardized character codes. The charactercodes are given in hexadecimal.In[9]:=

FullForm@%D

Out[9]//FullForm= "\:6570\:5b66"

248

Core Language

The notebook front end for Mathematica is typically set up so that when you enter a characterin a particular font, Mathematica will automatically work out the character code for that character.Sometimes, however, you may find it convenient to be able to enter characters directly usingcharacter codes.

.nn

a character with hexadecimal code nn

\:nnnn

a character with hexadecimal code nnnn

Ways to enter characters directly in terms of character codes.

For characters with character codes below 256, you can use \.nn. For characters with charactercodes above 256, you must use \:nnnn. Note that in all cases you must give a fixed number ofhexadecimal digits, padding with leading 0s if necessary.This gives character codes in hexadecimal for a few characters.In[10]:=

BaseForm@ToCharacterCode@"Aa"D, 16D

Out[10]//BaseForm=

84116 , e016 , 3b116 , 213516 <

This enters the characters using their character codes. Note the leading 0 inserted in the character code for a.In[11]:=Out[11]=

"Aa"Aa

In assigning codes to characters, Mathematica follows three compatible standards: ASCII, ISOLatin-1, and Unicode. ASCII covers the characters on a normal American English keyboard. ISOLatin-1 covers characters in many European languages. Unicode is a more general standardwhich defines character codes for several tens of thousands of characters used in languagesand notations around the world.

Here are some ISO Latin-1 letters.

Here are some special characters used in mathematical notation. The empty boxes correspondto characters not available in the current font.In[14]:=Out[14]=

FromCharacterCode@Range@8704, 8750DD"$'-,IJflfi

Here are a few Japanese characters.

In[15]:=Out[15]=

FromCharacterCode@Range@30 000, 30 030DD

Raw Character Encodings

250

Core Language

Raw Character Encodings

Mathematica always allows you to refer to special characters by using names such as @AlphaD or explicit hexadecimal codes such as : 03 b1. And when Mathematica writes outfiles, it by default uses these names or hexadecimal codes.But sometimes you may find it convenient to use raw encodings for at least some special characters. What this means is that rather than representing special characters by names or explicithexadecimal codes, you instead represent them by raw bit patterns appropriate for a particularcomputer system or particular font.

$CharacterEncoding=None

use printable ASCII names for all special characters

$CharacterEncoding="name"

use the raw character encoding specified by name

$SystemCharacterEncoding

the default raw character encoding for your particular

computer system

Setting up raw character encodings.

When you press a key or combination of keys on your keyboard, the operating system of yourcomputer sends a certain bit pattern to Mathematica. How this bit pattern is interpreted as acharacter within Mathematica will depend on the character encoding that has been set up.The notebook front end for Mathematica typically takes care of setting up the appropriatecharacter encoding automatically for whatever font you are using. But if you use Mathematicawith a text-based interface or via files or pipes, then you may need to set $CharacterEncodingexplicitly.By specifying an appropriate value for $CharacterEncoding you will typically be able to getMathematica to handle raw text generated by whatever language-specific text editor or operating system you use.You should realize, however, that while the standard representation of special characters usedin Mathematica is completely portable across different computer systems, any representationthat involves raw character encodings will inevitably not be.

Core Language

251

"PrintableASCII"

printable ASCII characters only (default)

"ASCII"

all ASCII including control characters

"ISOLatin1"

characters for common western European languages

"ISOLatin2"

characters for central and eastern European languages

"ISOLatin3"

characters for additional European languages (e.g. Catalan, Turkish)

"ISOLatin4"

characters for other additional European languages (e.g.

Estonian, Lappish)

"ISOLatinCyrillic"

English and Cyrillic characters

"AdobeStandard"

Adobe standard PostScript font encoding

"MacintoshRoman"

Macintosh roman font encoding

"WindowsANSI"

Windows standard font encoding

"Symbol"

symbol font encoding

"ZapfDingbats"

Zapf dingbats font encoding

"ShiftJIS"

shift-JIS for Japanese (mixture of 8- and 16-bit)

"EUC"

extended Unix code for Japanese (mixture of 8- and 16-bit)

"UTF8"

Unicode transformation format encoding

"Unicode"

raw 16-bit Unicode bit patterns

Some raw character encodings supported by Mathematica.

Mathematica knows about various raw character encodings, appropriate for different computersystems and different languages. Copying of characters between the Mathematica notebookinterface and user interface environment on your computer generally uses the native characterencoding for that environment. Mathematica characters which are not included in the nativeencoding will be written out using standard Mathematica full names or hexadecimal codes.The Mathematica kernel can use any character encoding you specify when it writes or readstext files. By default, Put and PutAppend produce an ASCII representation for reliable portability of Mathematica language files from one system to another.This writes a string to the file tmp.In[1]:=

"a b c a p " >> tmp

Special characters are written out using full names or explicit hexadecimal codes.

In[2]:=

Read@"tmp", StringD

Out[2]= "a b c \[EAcute] \[Alpha] \[Pi] \:2766"

Mathematica supports both 8- and 16-bit raw character encodings. In an encoding such as"ISOLatin1", all characters are represented by bit patterns containing 8 bits. But in an encoding such as "ShiftJIS" some characters instead involve bit patterns containing 16 bits.

252

Core Language

Mathematica supports both 8- and 16-bit raw character encodings. In an encoding such as"ISOLatin1", all characters are represented by bit patterns containing 8 bits. But in an encoding such as "ShiftJIS" some characters instead involve bit patterns containing 16 bits.Most of the raw character encodings supported by Mathematica include basic ASCII as a subset.This means that even when you are using such encodings, you can still give ordinary Mathematica input in the usual way, and you can specify special characters using @ and : sequences.Some raw character encodings, however, do not include basic ASCII as a subset. An example isthe "Symbol" encoding, in which the character codes normally used for a and b are insteadused for a and b.This gives the usual ASCII character codes for a few English letters.In[3]:=

ToCharacterCode@"abcdefgh"D

Out[3]= 897, 98, 99, 100, 101, 102, 103, 104<

In the "Symbol" encoding, these character codes are used for Greek letters.In[4]:=

FromCharacterCode@%, "Symbol"D

Out[4]= abcdefgh

ToCharacterCode@"string"D

generate codes for characters using the standard Mathemat ica encoding

ToCharacterCode@"string","encoding"Dgenerate codes for characters using the specified encoding

FromCharacterCode@8n1 ,n2 ,<D

generate characters from codes using the standard Mathe matica encoding

FromCharacterCode@8n1 ,n2 ,<,"encoding"D

generate characters from codes using the specifiedencodingHandling character codes with different encodings.This gives the codes assigned to various characters by Mathematica.In[5]:=

ToCharacterCode@"abcp"D

Out[5]= 897, 98, 99, 233, 960<

Core Language

253

Here are the codes assigned to the same characters in the Macintosh roman encoding.In[6]:=

ToCharacterCode@"abcp", "MacintoshRoman"D

Out[6]= 897, 98, 99, 142, 185<

Here are the codes in the Windows standard encoding. There is no code for @PiD in thatencoding.In[7]:=

ToCharacterCode@"abcp", "WindowsANSI"D

Out[7]= 897, 98, 99, 233, None<

The character codes used internally by Mathematica are based on Unicode. But externallyMathematica by default always uses plain ASCII sequences such as @NameD or : nnnn torefer to special characters. By telling it to use the raw "Unicode" character encoding, however,you can get Mathematica to read and write characters in raw 16-bit Unicode form.

254

Core Language

Evaluation of ExpressionsPrinciples of EvaluationThe fundamental operation that Mathematica performs is evaluation. Whenever you enter anexpression, Mathematica evaluates the expression, then returns the result.Evaluation in Mathematica works by applying a sequence of definitions. The definitions caneither be ones you explicitly entered, or ones that are built into Mathematica.Thus, for example, Mathematica evaluates the expression 6 + 7 using a built-in procedure foradding integers. Similarly, Mathematica evaluates the algebraic expression x - 3 x + 1 using abuilt-in simplification procedure. If you had made the definition x = 5, then Mathematica woulduse this definition to reduce x - 3 x + 1 to - 9.The two most central concepts in Mathematica are probably expressions and evaluation."Expressions" discusses how all the different kinds of objects that Mathematica handles arerepresented in a uniform way using expressions. This tutorial describes how all the operationsthat Mathematica can perform can also be viewed in a uniform way as examples of evaluation.Computation

5 + 6 11

Simplification

x - 3 x + 11 - 2 x

Execution

x = 55

Some interpretations of evaluation.

Mathematica is an infinite evaluation system. When you enter an expression, Mathematica willkeep on using definitions it knows until it gets a result to which no definitions apply.This defines x1 in terms of x2, and then defines x2.In[1]:=Out[1]=

x1 = x2 + 2; x2 = 77

If you ask for x1, Mathematica uses all the definitions it knows to give you a result.In[2]:=

x1

Out[2]= 9

Here is a recursive definition in which the factorial function is defined in terms of itself.

Core Language

255

Here is a recursive definition in which the factorial function is defined in terms of itself.In[3]:=

fac@1D = 1; fac@n_D := n fac@n - 1D

If you ask for fac@10D, Mathematica will keep on applying the definitions you have given untilthe result it gets no longer changes.

In[4]:=Out[4]=

fac@10D3 628 800

When Mathematica has used all the definitions it knows, it gives whatever expression it hasobtained as the result. Sometimes the result may be an object such as a number. But usuallythe result is an expression in which some objects are represented in a symbolic form.Mathematica uses its built-in definitions for simplifying sums, but knows no definitions for f@3D,so leaves this in symbolic form.In[5]:=Out[5]=

f@3D + 4 f@3D + 11 + 5 f@3D

Mathematica follows the principle of applying definitions until the result it gets no longerchanges. This means that if you take the final result that Mathematica gives, and enter it asMathematica input, you will get back the same result again. (There are some subtle casesdiscussed in "Controlling Infinite Evaluation" in which this does not occur.)If you type in a result from Mathematica, you get back the same expression again.In[6]:=Out[6]=

1 + 5 f@3D1 + 5 f@3D

At any given time, Mathematica can only use those definitions that it knows at that time. If youadd more definitions later, however, Mathematica will be able to use these. The results you getfrom Mathematica may change in this case.Here is a new definition for the function f.In[7]:=Out[7]=

f@x_D = x ^ 2x2

With the new definition, the results you get can change.In[8]:=Out[8]=

1 + 5 f@3D46

The simplest examples of evaluation involve using definitions such as f@x_D = x ^ 2 which transform one expression directly into another. But evaluation is also the process used to execute

256

Core Language

The simplest examples of evaluation involve using definitions such as f@x_D = x ^ 2 which transform one expression directly into another. But evaluation is also the process used to executeprograms written in Mathematica. Thus, for example, if you have a procedure consisting of asequence of Mathematica expressions, some perhaps representing conditionals and loops, theexecution of this procedure corresponds to the evaluation of these expressions. Sometimes theevaluation process may involve evaluating a particular expression several times, as in a loop.The expression Print@zzzzD is evaluated three times during the evaluation of the Do expression.In[9]:=

Do@Print@zzzzD, 83<D

zzzzzzzzzzzz

Reducing Expressions to Their Standard Form

The built-in functions in Mathematica operate in a wide variety of ways. But many of the mathematical functions share an important approach: they are set up so as to reduce classes ofmathematical expressions to standard forms.The built-in definitions for the Plus function, for example, are set up to write any sum of termsin a standard unparenthesized form. The associativity of addition means that expressions likeHa + bL + c, a + Hb + cL and a + b + c are all equivalent. But for many purposes it is convenient forall these forms to be reduced to the single standard form a + b + c. The built-in definitions forPlus are set up to do this.Through the built-in definitions for Plus , this expression is reduced to a standard unparenthesized form.In[1]:=Out[1]=

Ha + bL + ca+b+c

Whenever Mathematica knows that a function is associative, it tries to remove parentheses (ornested invocations of the function) to get the function into a standard flattened form.A function like addition is not only associative, but also commutative, which means that expressions like a + c + b and a + b + c with terms in different orders are equal. Once again, Mathematica tries to put all such expressions into a standard form. The standard form it chooses is theone in which all the terms are in a definite order, corresponding roughly to alphabetical order.

Core Language

257

A function like addition is not only associative, but also commutative, which means that expressions like a + c + b and a + b + c with terms in different orders are equal. Once again, Mathematica tries to put all such expressions into a standard form. The standard form it chooses is theone in which all the terms are in a definite order, corresponding roughly to alphabetical order.Mathematica sorts the terms in this sum into a standard order.In[2]:=Out[2]=

c+a+ba+b+c

flat (associative)

f[f[a,b],c] is equivalent to f[a,b,c], etc.

orderless (commutative)

f[b,a] is equivalent to f[a,b], etc.

Two important properties that Mathematica uses in reducing certain functions to standard form.

There are several reasons to try to put expressions into standard forms. The most important isthat if two expressions are really in standard form, it is obvious whether or not they are equal.When the two sums are put into standard order, they are immediately seen to be equal, so thattwo fs cancel, leaving the result 0.In[3]:=Out[3]=

f@a + c + bD - f@c + a + bD0

You could imagine finding out whether a + c + b was equal to c + a + b by testing all possibleorderings of each sum. It is clear that simply reducing both sums to standard form is a muchmore efficient procedure.One might think that Mathematica should somehow automatically reduce all mathematicalexpressions to a single standard canonical form. With all but the simplest kinds of expressions,however, it is quite easy to see that you do not want the same standard form for all purposes.For polynomials, for example, there are two obvious standard forms, which are good for different purposes. The first standard form for a polynomial is a simple sum of terms, as would begenerated in Mathematica by applying the function Expand. This standard form is most appropriate if you need to add and subtract polynomials.There is, however, another possible standard form that you can use for polynomials. By applying Factor, you can write any polynomial as a product of irreducible factors. This canonicalform is useful if you want to do operations like division.Expanded and factored forms are in a sense both equally good standard forms for polynomials.Which one you decide to use simply depends on what you want to use it for. As a result, Mathematica does not automatically put polynomials into one of these two forms. Instead, it gives

258

Core Language

Expanded and factored forms are in a sense both equally good standard forms for polynomials.Which one you decide to use simply depends on what you want to use it for. As a result, Mathematica does not automatically put polynomials into one of these two forms. Instead, it givesyou functions like Expand and Factor that allow you explicitly to put polynomials in whateverform you want.Here is a list of two polynomials that are mathematically equal.In[4]:=Out[4]=

t = 8x ^ 2 - 1, Hx + 1L Hx - 1L<9-1 + x2 , H-1 + xL H1 + xL=

You can write both of them in expanded form just by applying Expand. In this form, the equality of the polynomials is obvious.In[5]:=Out[5]=

Expand@tD9-1 + x2 , -1 + x2 =

You can also see that the polynomials are equal by writing them both in factored form.In[6]:=Out[6]=

Factor@tD8H-1 + xL H1 + xL, H-1 + xL H1 + xL<

Although it is clear that you do not always want expressions reduced to the same standardform, you may wonder whether it is at least possible to reduce all expressions to some standardform.There is a basic result in the mathematical theory of computation which shows that this is, infact, not always possible. You cannot guarantee that any finite sequence of transformations willtake any two arbitrarily chosen expressions to a standard form.In a sense, this is not particularly surprising. If you could in fact reduce all mathematical expressions to a standard form, then it would be quite easy to tell whether any two expressions wereequal. The fact that so many of the difficult problems of mathematics can be stated as questions about the equality of expressions suggests that this can in fact be difficult.

Core Language

259

AttributesDefinitions such as f@x_D = x ^ 2 specify values for functions. Sometimes, however, you need tospecify general properties of functions, without necessarily giving explicit values.Mathematica provides a selection of attributes that you can use to specify various properties offunctions. For example, you can use the attribute Flat to specify that a particular function is"flat", so that nested invocations are automatically flattened, and it behaves as if it were associative.This assigns the attribute Flat to the function f.In[1]:=

SetAttributes@f, FlatDNow f behaves as a flat, or associative, function, so that nested invocations are automaticallyflattened.

In[2]:=

f@f@a, bD, cD

Out[2]= f@a, b, cD

Attributes like Flat can affect not only evaluation, but also operations such as pattern matching. If you give definitions or transformation rules for a function, you must be sure to havespecified the attributes of the function first.Here is a definition for the flat function f.In[3]:=

f@x_, x_D := f@xD

Because f is flat, the definition is automatically applied to every subsequence of arguments.

In[4]:=

f@a, a, a, b, b, b, c, cD

Out[4]= f@a, b, cD

Attributes@ f D

give the attributes of f

Attributes@ f D=8attr1 ,attr2 ,<

set the attributes of f

Attributes@ f D=8<

set f to have no attributes

SetAttributes@ f ,attrD

add attr to the attributes of f

ClearAttributes@ f ,attrD

remove attr from the attributes of f

Manipulating attributes of symbols.

260

Core Language

This shows the attributes assigned to f.

Attributes@fD

In[5]:=

Out[5]= 8Flat<

This removes the attributes assigned to f.

In[6]:=

Attributes@fD = 8<

Out[6]= 8<

Orderless

orderless, commutative function (arguments are sorted

into standard order)

Flat

flat, associative function (arguments are "flattened out")

OneIdentity

f @ f @aDD, etc. are equivalent to a for pattern matching

Listable

f is automatically "threaded" over lists that appear as

arguments (e.g., f @8a, b<D becomes 8 f @aD, f @bD<)

Constant

all derivatives of f are zero

NumericFunction

f is assumed to have a numerical value when its arguments are numeric quantities

Protected

values of f cannot be changed

Locked

attributes of f cannot be changed

ReadProtected

values of f cannot be read

HoldFirst

the first argument of f is not evaluated

HoldRest

all but the first argument of f is not evaluated

HoldAll

none of the arguments of f are evaluated

HoldAllComplete

the arguments of f are treated as completely inert

NHoldFirst

the first argument of f is not affected by N

NHoldRest

all but the first argument of f is not affected by N

NHoldAll

none of the arguments of f are affected by N

SequenceHold

Sequence objects appearing in the arguments of f are not

flattened out

Temporary

f is a local variable, removed when no longer used

Stub

Needs is automatically called if f is ever explicitly input

The complete list of attributes for symbols in Mathematica.

Core Language

261

Here are the attributes for the built-in function Plus .

An important attribute assigned to built-in mathematical functions in Mathematica is the

attribute Listable. This attribute specifies that a function should automatically be distributedor "threaded" over lists that appear as its arguments. This means that the function effectivelygets applied separately to each element in any lists that appear as its arguments.The built-in Log function is Listable .In[8]:=

Log@85, 8, 11<D

Out[8]= 8Log@5D, Log@8D, Log@11D<

This defines the function p to be listable.

In[9]:=

SetAttributes@p, ListableDNow p is automatically threaded over lists that appear as its arguments.

In[10]:=

p@8a, b, c<, dD

Out[10]= 8p@a, dD, p@b, dD, p@c, dD<

Many of the attributes you can assign to functions in Mathematica directly affect the evaluationof those functions. Some attributes, however, affect only other aspects of the treatment offunctions. For example, the attribute OneIdentity affects only pattern matching, as discussedin "Flat and Orderless Functions". Similarly, the attribute Constant is only relevant in differentiation, and operations that rely on differentiation.The Protected attribute affects assignments. Mathematica does not allow you to make anydefinition associated with a symbol that carries this attribute. The functions Protect andUnprotect discussed in "Modifying Built-in Functions" can be used as alternatives toSetAttributes and ClearAttributes to set and clear this attribute. As discussed in "ModifyingBuilt-in Functions" most built-in Mathematica objects are initially protected so that you do notmake definitions for them by mistake.Here is a definition for the function g.In[11]:=

g@x_D = x + 1

Out[11]= 1 + x

This sets the Protected attribute for g.

262

Core Language

This sets the Protected attribute for g.

In[12]:=

Protect@gD

Out[12]= 8g<

Now you cannot modify the definition of g.

In[13]:=

g@x_D = xSet::write : Tag g in g@x_D is Protected.

Out[13]= x

You can usually see the definitions you have made for a particular symbol by typing ? f , or byusing a variety of built-in Mathematica functions. However, if you set the attributeReadProtected, Mathematica will not allow you to look at the definition of a particular symbol.It will nevertheless continue to use the definitions in performing evaluation.Although you cannot modify it, you can still look at the definition of g.In[14]:=

SetAttributes@g, ReadProtectedDNow you can no longer read the definition of g.

In[16]:=

?g

Global`gAttributes@gD = 8Protected, ReadProtected<Functions like SetAttributes and ClearAttributes usually allow you to modify the attributesof a symbol in any way. However, if you once set the Locked attribute on a symbol, then Mathematica will not allow you to modify the attributes of that symbol for the remainder of yourMathematica session. Using the Locked attribute in addition to Protected or ReadProtected,you can arrange for it to be impossible for users to modify or read definitions.

Core Language

Clear@ f D

remove values for f , but not attributes

ClearAll@ f D

remove both values and attributes of f

263

Clearing values and attributes.

This clears values and attributes of p which was given attribute Listable above.In[17]:=

ClearAll@pDNow p is no longer listable.

In[18]:=

p@8a, b, c<, dD

Out[18]= p@8a, b, c<, dD

By defining attributes for a function you specify properties that Mathematica should assumewhenever that function appears. Often, however, you want to assume the properties only in aparticular instance. In such cases, you will be better off not to use attributes, but instead to calla particular function to implement the transformation associated with the attributes.By explicitly calling Thread, you can implement the transformation that would be done automatically if p were listable.In[19]:=

Thread@p@8a, b, c<, dDD

Out[19]= 8p@a, dD, p@b, dD, p@c, dD<

Orderless

Sort@ f @argsDD

Flat

Flatten@ f @argsDD

Listable

Thread@ f @argsDD

Constant

DtAexpr,Constants-> f E

Functions that perform transformations associated with some attributes.

Attributes in Mathematica can only be permanently defined for single symbols. However, Mathematica also allows you to set up pure functions which behave as if they carry attributes.

Function@vars,body,8attr1 ,<D

a pure function with attributes attr1 ,

Pure functions with attributes.

This pure function applies p to the whole list.In[20]:=

Function@8x<, p@xDD@8a, b, c<D

Out[20]= p@8a, b, c<D

By adding the attribute Listable , the function gets distributed over the elements of the list

264

Core Language

By adding the attribute Listable , the function gets distributed over the elements of the listbefore applying p.In[21]:=

Function@8x<, p@xD, 8Listable<D@8a, b, c<D

Out[21]= 8p@aD, p@bD, p@cD<

The Standard Evaluation Procedure

Here we describe the standard procedure used by Mathematica to evaluate expressions. Thisprocedure is the one followed for most kinds of expression. There are however some kinds ofexpressions, such as those used to represent Mathematica programs and control structures,which are evaluated in a nonstandard way.In the standard evaluation procedure, Mathematica first evaluates the head of an expression,and then evaluates each element of the expressions. These elements are in general themselvesexpressions, to which the same evaluation procedure is recursively applied.The three Print functions are evaluated in turn, each printing its argument, then returning thevalue Null .In[1]:=

8Print@1D, Print@2D, Print@3D<

123Out[1]= 8Null, Null, Null<

This assigns the symbol ps to be Plus .

In[2]:=Out[2]=

ps = PlusPlus

The head ps is evaluated first, so this expression behaves just like a sum of terms.In[3]:=Out[3]=

ps@ps@a, bD, cDa+b+c

Core Language

265

As soon as Mathematica has evaluated the head of an expression, it sees whether the head is asymbol that has attributes. If the symbol has the attributes Orderless, Flat or Listable, thenimmediately after evaluating the elements of the expression Mathematica performs the transformations associated with these attributes.The next step in the standard evaluation procedure is to use definitions that Mathematicaknows for the expression it is evaluating. Mathematica first tries to use definitions that youhave made, and if there are none that apply, it tries built-in definitions.If Mathematica finds a definition that applies, it performs the corresponding transformation onthe expression. The result is another expression, which must then in turn be evaluated according to the standard evaluation procedure. Evaluate the head of the expression. Evaluate each element in turn. Apply transformations associated with the attributes Orderless, Listable and Flat . Apply any definitions that you have given. Apply any built-in definitions. Evaluate the result.The standard evaluation procedure.

As discussed in "Principles of Evaluation", Mathematica follows the principle that each expression is evaluated until no further definitions apply. This means that Mathematica must continuere-evaluating results until it gets an expression which remains unchanged through the evaluation procedure.Here is an example that shows how the standard evaluation procedure works on a simple expres sion. We assume that a = 7.

266

Core Language

2 a x+a^2+1

here is the original expression

Plus@Times@2,a,xD,Power@a,2D,1Dthis is the internal form

Times@2,a,xD

this is evaluated first

Times@2,7,xD

a is evaluated to give 7

Times@14,xD

built-in definitions for Times give this result

Power@a,2D

this is evaluated next

Power@7,2D

here is the result after evaluating a

49

built-in definitions for Power give this result

Plus@Times@14,xD,49,1D

here is the result after the arguments of Plus have been

evaluated

Plus@50,Times@14,xDD

built-in definitions for Plus give this result

50+14 x

the result is printed like this

A simple example of evaluation in Mathematica.

Mathematica provides various ways to trace the evaluation process, as discussed in "TracingEvaluation". The function Trace@exprD gives a nested list showing each subexpression generated during evaluation. (Note that the standard evaluation traverses the expression tree in adepth-first way, so that the smallest subparts of the expression appear first in the results ofTrace.)First set a to 7.In[4]:=Out[4]=

a=77

This gives a nested list of all the subexpressions generated during the evaluation of the expression.In[5]:=Out[5]=

The order in which Mathematica applies different kinds of definitions is important. The fact thatMathematica applies definitions you have given before it applies built-in definitions means thatyou can give definitions which override the built-in ones, as discussed in "Modifying Built-inFunctions".

Core Language

267

This expression is evaluated using the built-in definition for ArcSin.

In[6]:=Out[6]=

ArcSin@1Dp2

You can give your own definitions for ArcSin. You need to remove the protection attribute first.In[7]:=

Unprotect@ArcSinD; ArcSin@1D = 5 Pi 2;Your definition is used before the one that is built in.

In[8]:=Out[8]=

ArcSin@1D5p2

As discussed in "Associating Definitions with Different Symbols", you can associate definitionswith symbols either as upvalues or downvalues. Mathematica always tries upvalue definitionsbefore downvalue ones.If you have an expression like f @g@xDD, there are in general two sets of definitions that couldapply: downvalues associated with f , and upvalues associated with g. Mathematica tries thedefinitions associated with g before those associated with f .This ordering follows the general strategy of trying specific definitions before more generalones. By applying upvalues associated with arguments before applying downvalues associatedwith a function, Mathematica allows you to make definitions for special arguments which override the general definitions for the function with any arguments.This defines a rule for f@g@x_DD, to be associated with f.In[9]:=

f : f@g@x_DD := frule@xDThis defines a rule for f@g@x_DD, to be associated with g.

If you remove rules associated with g, the rule associated with f is used.In[12]:=Out[12]=

Clear@gD; f@g@1DDfrule@1D

Definitions associated with g are applied before definitions associated with f in the expressionf @g@xDD.The order in which definitions are applied.

Most functions such as Plus that are built into Mathematica have downvalues. There are, however, some objects in Mathematica which have built-in upvalues. For example, SeriesDataobjects, which represent power series, have built-in upvalues with respect to various mathematical operations.For an expression like f @g@xDD, the complete sequence of definitions that are tried in the standard evaluation procedure is: Definitions you have given associated with g; Built-in definitions associated with g; Definitions you have given associated with f ; Built-in definitions associated with f .The fact that upvalues are used before downvalues is important in many situations. In a typicalcase, you might want to define an operation such as composition. If you give upvalues forvarious objects with respect to composition, these upvalues will be used whenever such objectsappear. However, you can also give a general procedure for composition, to be used if nospecial objects are present. You can give this procedure as a downvalue for composition. Sincedownvalues are tried after upvalues, the general procedure will be used only if no objects withupvalues are present.Here is a definition associated with q for composition of q objects.In[13]:=

q : comp@q@x_D, q@y_DD := qcomp@x, yD

Here is a general rule for composition, associated with comp.

In[14]:=

comp@f_@x_D, f_@y_DD := gencomp@f, x, yD

Core Language

269

If you compose two q objects, the rule associated with q is used.

In[15]:=Out[15]=

comp@q@1D, q@2DDqcomp@1, 2D

If you compose r objects, the general rule associated with comp is used.In[16]:=Out[16]=

comp@r@1D, r@2DDgencomp@r, 1, 2D

In general, there can be several objects that have upvalues in a particular expression. Mathematica first looks at the head of the expression, and tries any upvalues associated with it. Then itsuccessively looks at each element of the expression, trying any upvalues that exist. Mathematica performs this procedure first for upvalues that you have explicitly defined, and then forupvalues that are built-in. The procedure means that in a sequence of elements, upvaluesassociated with earlier elements take precedence over those associated with later elements.This defines an upvalue for p with respect to c.In[17]:=

p : c@l___, p@x_D, r___D := cp@x, 8l, r<D

This defines an upvalue for q.

In[18]:=

q : c@l___, q@x_D, r___D := cq@x, 8l, r<D

Which upvalue is used depends on which occurs first in the sequence of arguments to c.

In[19]:=Out[19]=

8c@p@1D, q@2DD, c@q@1D, p@2DD<

8cp@1, 8q@2D<D, cq@1, 8p@2D<D<

Non-Standard EvaluationWhile most built-in Mathematica functions follow the standard evaluation procedure, someimportant ones do not. For example, most of the Mathematica functions associated with theconstruction and execution of programs use non-standard evaluation procedures. In typicalcases, the functions either never evaluate some of their arguments, or do so in a special wayunder their own control.

270

Core Language

x=y

do not evaluate the left-hand side

If@p,a,bD

evaluate a if p is True , and b if it is False

Do@expr,8n<D

evaluate expr n times

Plot@ f ,8x,<D

evaluate f with a sequence of numerical values for x

Function@8x<,bodyD

do not evaluate until the function is applied

Some functions that use non-standard evaluation procedures.

When you give a definition such as a = 1, Mathematica does not evaluate the a that appears onthe left-hand side. You can see that there would be trouble if the a was evaluated. The reasonis that if you had previously set a = 7, then evaluating a in the definition a = 1 would put thedefinition into the nonsensical form 7 = 1.In the standard evaluation procedure, each argument of a function is evaluated in turn. This isprevented by setting the attributes HoldFirst, HoldRest and HoldAll. These attributes makeMathematica hold particular arguments in an unevaluated form.

HoldFirst

do not evaluate the first argument

HoldRest

evaluate only the first argument

HoldAll

evaluate none of the arguments

Attributes for holding function arguments in unevaluated form.

With the standard evaluation procedure, all arguments to a function are evaluated.In[1]:=Out[1]=

f@1 + 1, 2 + 4Df@2, 6D

This assigns the attribute HoldFirst to h.

In[2]:=

SetAttributes@h, HoldFirstDThe first argument to h is now held in an unevaluated form.

In[3]:=Out[3]=

h@1 + 1, 2 + 4Dh@1 + 1, 6D

When you use the first argument to h like this, it will get evaluated.In[4]:=Out[4]=

h@1 + 1, 2 + 4D . h@x_, y_D -> x ^ y

64

Built-in functions like Set carry attributes such as HoldFirst.

Core Language

271

Built-in functions like Set carry attributes such as HoldFirst.

In[5]:=Out[5]=

Attributes@SetD8HoldFirst, Protected, SequenceHold<

Even though a function may have attributes which specify that it should hold certain argumentsunevaluated, you can always explicitly tell Mathematica to evaluate those arguments by givingthe arguments in the form Evaluate@argD.Evaluate effectively overrides the HoldFirst attribute, and causes the first argument to beevaluated.In[6]:=Out[6]=

h@Evaluate@1 + 1D, 2 + 4Dh@2, 6D

f @Evaluate@argDD

evaluate arg immediately, even though attributes of f may

specify that it should be held

Forcing the evaluation of function arguments.

By holding its arguments, a function can control when those arguments are evaluated. By usingEvaluate, you can force the arguments to be evaluated immediately, rather than being evaluated under the control of the function. This capability is useful in a number of circumstances.The Mathematica Set function holds its first argument, so the symbol a is not evaluated in thiscase.In[7]:=Out[7]=

a=bb

You can make Set evaluate its first argument using Evaluate . In this case, the result is theobject which is the value of a, namely b is set to 6.In[8]:=Out[8]=

Evaluate@aD = 66

b has now been set to 6.

In[9]:=Out[9]=

b6

In most cases, you want all expressions you give to Mathematica to be evaluated. Sometimes,however, you may want to prevent the evaluation of certain expressions. For example, if youwant to manipulate pieces of a Mathematica program symbolically, then you must preventthose pieces from being evaluated while you are manipulating them.

272

Core Language

In most cases, you want all expressions you give to Mathematica to be evaluated. Sometimes,however, you may want to prevent the evaluation of certain expressions. For example, if youwant to manipulate pieces of a Mathematica program symbolically, then you must preventthose pieces from being evaluated while you are manipulating them.You can use the functions Hold and HoldForm to keep expressions unevaluated. These functions work simply by carrying the attribute HoldAll, which prevents their arguments frombeing evaluated. The functions provide wrappers inside which expressions remain unevaluated.The difference between Hold@exprD and HoldForm@exprD is that in standard Mathematica outputformat, Hold is printed explicitly, while HoldForm is not. If you look at the full internal Mathematica form, you can however see both functions.Hold maintains expressions in an unevaluated form.In[10]:=Out[10]=

Hold@1 + 1DHold@1 + 1D

HoldForm also keeps expressions unevaluated, but is invisible in standard Mathematica outputformat.In[11]:=Out[11]=

HoldForm@1 + 1D1+1

HoldForm is still present internally.

In[12]:=

FullForm@%D

Out[12]//FullForm=

HoldForm@Plus@1, 1DD

The function ReleaseHold removes Hold and HoldForm , so the expressions they contain getevaluated.In[13]:=

ReleaseHold@%D

Out[13]= 2

Core Language

Hold@exprD

keep expr unevaluated

HoldComplete@exprD

keep expr unevaluated and prevent upvalues associated

with expr from being used

HoldForm@exprD

keep expr unevaluated, and print without HoldForm

ReleaseHold @exprD

remove Hold and HoldForm in expr

ExtractAexpr,index,HoldE

get a part of expr, wrapping it with Hold to prevent

evaluation

273

Functions for handling unevaluated expressions.

Parts of expressions are usually evaluated as soon as you extract them.In[14]:=Out[14]=

Extract@Hold@1 + 1, 2 + 3D, 2D5

This extracts a part and immediately wraps it with Hold , so it does not get evaluated.In[15]:=Out[15]=

Extract@Hold@1 + 1, 2 + 3D, 2, HoldD

Hold@2 + 3D

f @,Unevaluated @exprD,D

give expr unevaluated as an argument to f

Temporary prevention of argument evaluation.

1 + 1 evaluates to 2, and Length@2D gives 0.

In[16]:=Out[16]=

Length@1 + 1D0

This gives the unevaluated form 1 + 1 as the argument of Length.

In[17]:=

Length@Unevaluated@1 + 1DD

Out[17]= 2

Unevaluated @exprD effectively works by temporarily giving a function an attribute like

HoldFirst, and then supplying expr as an argument to the function.

SequenceHold

do not flatten out Sequence objects that appear as

arguments

HoldAllComplete

treat all arguments as completely inert

Attributes for preventing other aspects of evaluation.

By setting the attribute HoldAll, you can prevent Mathematica from evaluating the argumentsof a function. But even with this attribute set, Mathematica will still do some transformations on

274

Core Language

By setting the attribute HoldAll, you can prevent Mathematica from evaluating the argumentsof a function. But even with this attribute set, Mathematica will still do some transformations onthe arguments. By setting SequenceHold you can prevent it from flattening out Sequenceobjects that appear in the arguments. And by setting HoldAllComplete you can also inhibit thestripping of Unevaluated , and prevent Mathematica from using any upvalues it finds associatedwith the arguments.

Evaluation in Patterns, Rules and Definitions

There are a number of important interactions in Mathematica between evaluation and patternmatching. The first observation is that pattern matching is usually done on expressions thathave already been at least partly evaluated. As a result, it is usually appropriate that the patterns to which these expressions are matched should themselves be evaluated.The fact that the pattern is evaluated means that it matches the expression given.In[1]:=

f@k ^ 2D . f@x_ ^ H1 + 1LD -> p@xD

Out[1]= p@kD

The right-hand side of the ; condition is not evaluated until it is used during pattern matching.In[2]:=

f@8a, b<D . f@list_ ; Length@listD > 1D -> list ^ 2

22Out[2]= 9a , b =

There are some cases, however, where you may want to keep all or part of a pattern unevaluated. You can do this by wrapping the parts you do not want to evaluate with HoldPattern . Ingeneral, whenever HoldPattern @pattD appears within a pattern, this form is taken to be equivalent to patt for the purpose of pattern matching, but the expression patt is maintained unevaluated.

HoldPattern @pattD

equivalent to patt for pattern matching, with patt kept

unevaluated

Preventing evaluation in patterns.

One application for HoldPattern is in specifying patterns which can apply to unevaluatedexpressions, or expressions held in an unevaluated form.

Core Language

275

HoldPattern keeps the 1 + 1 from being evaluated, and allows it to match the 1 + 1 on theleft-hand side of the . operator.In[3]:=

Hold@u@1 + 1DD . HoldPattern@1 + 1D -> x

Out[3]= Hold@u@xDD

Notice that while functions like Hold prevent evaluation of expressions, they do not affect themanipulation of parts of those expressions with . and other operators.This defines values for r whenever its argument is not an atomic object.In[4]:=

However, the pattern r@x_D is transformed according to the definition for r.

In[6]:=

r@x_D

2Out[6]= x_

You need to wrap HoldPattern around r@x_D to prevent it from being evaluated.In[7]:=

8r@3D, r@5D< . HoldPattern@r@x_DD -> x

Out[7]= 83, 5<

As illustrated above, the left-hand sides of transformation rules such as lhs -> rhs are usuallyevaluated immediately, since the rules are usually applied to expressions which have alreadybeen evaluated. The right-hand side of lhs -> rhs is also evaluated immediately. With thedelayed rule lhs :> rhs, however, the expression rhs is not evaluated.The right-hand side is evaluated immediately in -> but not :> rules.In[8]:=

88x -> 1 + 1<, 8x :> 1 + 1<<

Out[8]= 88x 2<, 8x 1 + 1<<

Here are the results of applying the rules. The right-hand side of the :> rule gets inserted insidethe Hold without evaluation.In[9]:=

8x ^ 2, Hold@xD< . %

Out[9]= 884, Hold@2D<, 84, Hold@1 + 1D<<

276

Core Language

lhs->rhs

evaluate both lhs and rhs

lhs:>rhs

evaluate lhs but not rhs

Evaluation in transformation rules.

While the left-hand sides of transformation rules are usually evaluated, the left-hand sides ofdefinitions are usually not. The reason for the difference is as follows. Transformation rules aretypically applied using . to expressions that have already been evaluated. Definitions, however, are used during the evaluation of expressions, and are applied to expressions that havenot yet been completely evaluated. To work on such expressions, the left-hand sides of definitions must be maintained in a form that is at least partially unevaluated.Definitions for symbols are the simplest case. As discussed in "Non-Standard Evaluation", asymbol on the left-hand side of a definition such as x = value is not evaluated. If x had previouslybeen assigned a value y, then if the left-hand side of x = value were evaluated, it would turn intothe quite unrelated definition y = value.Here is a definition. The symbol on the left-hand side is not evaluated.In[10]:=

k = w@3D

Out[10]= w@3D

This redefines the symbol.

In[11]:=

k = w@4D

Out[11]= w@4D

If you evaluate the left-hand side, then you define not the symbol k, but the value w@4D of thesymbol k.In[12]:=

Evaluate@kD = w@5D

Out[12]= w@5D

Now w@4D has value w@5D.

In[13]:=

w@4D

Out[13]= w@5D

Although individual symbols that appear on the left-hand sides of definitions are not evaluated,more complicated expressions are partially evaluated. In an expression such as f @argsD on theleft-hand side of a definition, the args are evaluated.The 1 + 1 is evaluated, so that a value is defined for g@2D.

Core Language

277

The 1 + 1 is evaluated, so that a value is defined for g@2D.

In[14]:=

g@1 + 1D = 5

Out[14]= 5

This shows the value defined for g.

In[15]:=

?g

Global`gg@2D = 5You can see why the arguments of a function that appears on the left-hand side of a definitionmust be evaluated by considering how the definition is used during the evaluation of an expression. As discussed in "Principles of Evaluation", when Mathematica evaluates a function, it firstevaluates each of the arguments, then tries to find definitions for the function. As a result, bythe time Mathematica applies any definition you have given for a function, the arguments of thefunction must already have been evaluated. An exception to this occurs when the function inquestion has attributes which specify that it should hold some of its arguments unevaluated.

symbol=value

symbol is not evaluated; value is evaluated

symbol:=value

neither symbol nor value is evaluated

f @argsD=value

args are evaluated; left-hand side as a whole is not

f @HoldPattern @argDD=value

f[arg] is assigned, without evaluating arg

Evaluate@lhsD=value

left-hand side is evaluated completely

Evaluation in definitions.

While in most cases it is appropriate for the arguments of a function that appears on the lefthand side of a definition to be evaluated, there are some situations in which you do not wantthis to happen. In such cases, you can wrap HoldPattern around the parts that you do notwant to be evaluated.

Evaluation in Iteration Functions

The built-in Mathematica iteration functions such as Table and Sum evaluate their arguments ina slightly special way.When evaluating an expression like Table@ f , 8i, imax <D, the first step, as discussed in "Blocksand Local Values", is to make the value of i local. Next, the limit imax in the iterator specificationis evaluated. The expression f is maintained in an unevaluated form, but is repeatedly evalu-

278

Core Language

When evaluating an expression like Table@ f , 8i, imax <D, the first step, as discussed in "Blocksand Local Values", is to make the value of i local. Next, the limit imax in the iterator specificationis evaluated. The expression f is maintained in an unevaluated form, but is repeatedly evaluated as a succession of values are assigned to i. When this is finished, the global value of i isrestored.The function RandomReal@D is evaluated four separate times here, so four different pseudorandom numbers are generated.In[1]:=

Table@RandomReal@D, 84<D

Out[1]= 80.300949, 0.450179, 0.831238, 0.161379<

This evaluates RandomReal@D before feeding it to Table . The result is a list of four identicalnumbers.In[2]:=

Table@Evaluate@RandomReal@DD, 84<D

Out[2]= 80.653098, 0.653098, 0.653098, 0.653098<

In most cases, it is convenient for the function f in an expression like Table@ f , 8i, imax <D to bemaintained in an unevaluated form until specific values have been assigned to i. This is true inparticular if a complete symbolic form for f valid for any i cannot be found.This defines fac to give the factorial when it has an integer argument, and to give NaN(standing for Not a Number) otherwise.In[3]:=

fac@n_IntegerD := n !; fac@x_D := NaN

In this form, fac@iD is not evaluated until an explicit integer value has been assigned to i.

In[4]:=Out[4]=

Table@fac@iD, 8i, 5<D

81, 2, 6, 24, 120<

Using Evaluate forces fac@iD to be evaluated with i left as a symbolic object.

In[5]:=Out[5]=

Table@Evaluate@fac@iDD, 8i, 5<D

8NaN, NaN, NaN, NaN, NaN<

In cases where a complete symbolic form for f with arbitrary i in expressions such asTable@ f , 8i, imax <D can be found, it is often more efficient to compute this form first, and thenfeed it to Table. You can do this using Table@Evaluate@ f D, 8i, imax <D.

Core Language

279

The Sum in this case is evaluated separately for each value of i.

In[6]:=Out[6]=

Table@Sum@i ^ k, 8k, 4<D, 8i, 8<D

84, 30, 120, 340, 780, 1554, 2800, 4680<

It is however possible to get a symbolic formula for the sum, valid for any value of i.In[7]:=Out[7]=

Sum@i ^ k, 8k, 4<D

i + i2 + i3 + i4

By inserting Evaluate , you tell Mathematica first to evaluate the sum symbolically, then toiterate over i.In[8]:=Out[8]=

Table@Evaluate@Sum@i ^ k, 8k, 4<DD, 8i, 8<D

84, 30, 120, 340, 780, 1554, 2800, 4680<

Table@ f ,8i,imax <D

keep f unevaluated until specific values are assigned to i

TableAEvaluate@ f D,8i,imax <E

evaluate f first with i left symbolic

Evaluation in iteration functions.

ConditionalsMathematica provides various ways to set up conditionals, which specify that particular expressions should be evaluated only if certain conditions hold.

lhs:=rhs;test

use the definition only if test evaluates to True

If@test,then,elseD

evaluate then if test is True , and else if it is False

Which@test1 ,value1 ,test2 ,D

evaluate the testi in turn, giving the value associated with

the first one that is True

Switch@expr, form1 ,value1 , form2 ,D

compare expr with each of the formi , giving the value

associated with the first form it matches

Switch@expr, form1 ,value1 , form2 ,,_,def D

use def as a default value

Piecewise@88value1 ,test1 <,<,def D

give the value corresponding to the first testi which yields

TrueConditional constructs.

280

Core Language

The test gives False , so the "else" expression y is returned.

In[1]:=

If@7 > 8, x, yD

Out[1]= y

Only the "else" expression is evaluated in this case.

In[2]:=

If@7 > 8, Print@xD, Print@yDD

yWhen you write programs in Mathematica, you will often have a choice between making asingle definition whose right-hand side involves several branches controlled by If functions, ormaking several definitions, each controlled by an appropriate ; condition. By using severaldefinitions, you can often produce programs that are both clearer, and easier to modify.This defines a step function, with value 1 for x > 0, and - 1 otherwise.In[3]:=

f@x_D := If@x > 0, 1, - 1D

This defines the positive part of the step function using a ; condition.

Global`gg@x_D := 1 ; x > 0g@x_D := - 1 ; x 0The function If provides a way to choose between two alternatives. Often, however, there willbe more than two alternatives. One way to handle this is to use a nested set of If functions.Usually, however, it is instead better to use functions like Which and Switch.This defines a function with three regions. Using True as the third test makes this the defaultcase.In[7]:=

h@x_D := Which@x < 0, x ^ 2, x > 5, x ^ 3, True, 0D

This uses the first case in the Which .

Core Language

281

This uses the first case in the Which .

In[8]:=

h@- 5D

Out[8]= 25

This uses the third case.

In[9]:=

h@2D

Out[9]= 0

This defines a function that depends on the values of its argument modulo 3.In[10]:=

r@x_D := Switch@Mod@x, 3D, 0, a, 1, b, 2, cD

Mod@7, 3D is 1, so this uses the second case in the Switch.

In[11]:=

r@7D

Out[11]= b

17 matches neither 0 nor 1, but does match _.

In[12]:=

Switch@17, 0, a, 1, b, _, qD

Out[12]= q

An important point about symbolic systems such as Mathematica is that the conditions you givemay yield neither True nor False. Thus, for example, the condition x == y does not yield Trueor False unless x and y have specific values, such as numerical ones.In this case, the test gives neither True nor False , so both branches in the If remain unevaluated.In[13]:=

If@x == y, a, bD

Out[13]= If@x y, a, bD

You can add a special fourth argument to If , which is used if the test does not yield True orFalse .In[14]:=

Functions for dealing with symbolic conditions.

Unlike ==, === tests whether two expressions are manifestly identical. In this case, they arenot.In[17]:=

x === y

Out[17]= False

The main difference between lhs === rhs and lhs == rhs is that === always returns True or False,whereas == can leave its input in symbolic form, representing a symbolic equation, as discussedin "Equations". You should typically use === when you want to test the structure of an expression, and == if you want to test mathematical equality. The Mathematica pattern matcher effectively uses === to determine when one literal expression matches another.You can use === to test the structure of expressions.In[18]:=

Head@a + b + cD === Times

Out[18]= False

The == operator gives a less useful result.

In[19]:=

Head@a + b + cD == Times

Out[19]= Plus Times

In setting up conditionals, you will often need to use combinations of tests, such astest1 && test2 && . An important point is that the result from this combination of tests will be

Core Language

283

In setting up conditionals, you will often need to use combinations of tests, such astest1 && test2 && . An important point is that the result from this combination of tests will beFalse if any of the testi yield False. Mathematica always evaluates the testi in turn, stopping ifany of the testi yield False.

expr1 &&expr2 &&expr3

evaluate until one of the expri is found to be False

expr1 expr2 expr3

evaluate until one of the expri is found to be True

Evaluation of logical expressions.

This function involves a combination of two tests.In[20]:=

t@x_D := Hx != 0 && 1 x < 3L

Here both tests are evaluated.

In[21]:=

t@2D

Out[21]= True

Here the first test yields False , so the second test is not tried. The second test would involve1 0, and would generate an error.In[22]:=

t@0D

Out[22]= False

The way that Mathematica evaluates logical expressions allows you to combine sequences oftests where later tests may make sense only if the earlier ones are satisfied. The behavior,which is analogous to that found in languages such as C, is convenient in constructing manykinds of Mathematica programs.

Loops and Control Structures

The execution of a Mathematica program involves the evaluation of a sequence of Mathematicaexpressions. In simple programs, the expressions to be evaluated may be separated by semicolons, and evaluated one after another. Often, however, you need to evaluate expressionsseveral times, in some kind of "loop".

284

Core Language

Do@expr,8i,imax <D

evaluate expr repetitively, with i varying from 1 to imax in

steps of 1

Do@expr,8i,imin ,imax ,di<D

evaluate expr with i varying from imin to imax in steps of di

Do@expr,8i,list<D

evaluate expr with i taking on values from list

Do@expr,8n<D

evaluate expr n times

Simple looping constructs.

This evaluates Print@i ^ 2D, with i running from 1 to 4.In[1]:=

Do@Print@i ^ 2D, 8i, 4<D

14916This executes an assignment for t in a loop with k running from 2 to 6 in steps of 2.In[2]:=

t = x; Do@t = 1 H1 + k tL, 8k, 2, 6, 2<D; t

1

Out[2]=

1+1+

41+2 x

The way iteration is specified in Do is exactly the same as in functions like Table and Sum . Justas in those functions, you can set up several nested loops by giving a sequence of iterationspecifications to Do.This loops over values of i from 1 to 4, and for each value of i, loops over j from 1 to i - 1.In[3]:=

Do@Print@8i, j<D, 8i, 4<, 8j, i - 1<D

82, 1<83, 1<83, 2<84, 1<84, 2<84, 3<Sometimes you may want to repeat a particular operation a certain number of times, withoutchanging the value of an iteration variable. You can specify this kind of repetition in Do just asyou can in Table and other iteration functions.

Core Language

285

Sometimes you may want to repeat a particular operation a certain number of times, withoutchanging the value of an iteration variable. You can specify this kind of repetition in Do just asyou can in Table and other iteration functions.This repeats the assignment t = 1 H1 + tL three times.In[4]:=

t = x; Do@t = 1 H1 + tL, 83<D; t

1

Out[4]=

1+

11+

11+x

You can put a procedure inside Do .

In[5]:=

t = 67; Do@Print@tD; t = Floor@t 2D, 83<D

673316Nest@ f ,expr,nD

apply f to expr n times

FixedPoint@ f ,exprD

start with expr, and apply f repeatedly until the result no

longer changes

NestWhile@ f ,expr,testD

start with expr, and apply f repeatedly until applying test to

the result no longer yields True

Applying functions repetitively.

Do allows you to repeat operations by evaluating a particular expression many times withdifferent values for iteration variables. Often, however, you can make more elegant and efficient programs using the functional programming constructs discussed in "Applying FunctionsRepeatedly". Nest@ f , x, nD, for example, allows you to apply a function repeatedly to an expression.This nests f three times.In[6]:=Out[6]=

Nest@f, x, 3Df@f@f@xDDD

286

Core Language

By nesting a pure function, you can get the same result as in the example with Do above.In[7]:=

Nest@Function@t, 1 H1 + tLD, x, 3D1

Out[7]=

1+

1+

11+x

Nest allows you to apply a function a specified number of times. Sometimes, however, you maysimply want to go on applying a function until the results you get no longer change. You can dothis using FixedPoint@ f , xD.FixedPoint goes on applying a function until the result no longer changes.In[8]:=

FixedPoint@Function@t, Print@tD; Floor@t 2DD, 67D

67331684210Out[8]=

You can use FixedPoint to imitate the evaluation process in Mathematica, or the operation offunctions such as expr . rules. FixedPoint goes on until two successive results it gets are thesame. NestWhile allows you to go on until an arbitrary function no longer yields True.

Catch@exprD

evaluate expr until Throw@valueD is encountered, then

return value

Catch@expr, formD

evaluate expr until Throw@value, tagD is encountered,

where form matches tag

Catch@expr, form, f D

return f @value, tagD instead of value

Non local control of evaluation.

When the Throw is encountered, evaluation stops, and the current value of i is returned as thevalue of the enclosing Catch .In[9]:=

Catch@Do@Print@iD; If@i > 3, Throw@iDD, 8i, 10<DD

Core Language

287

1234Out[9]=

Throw and Catch provide a flexible way to control the process of evaluation in Mathematica.The basic idea is that whenever a Throw is encountered, the evaluation that is then being doneis stopped, and Mathematica immediately returns to the nearest appropriate enclosing Catch.Scan applies the function Print to each successive element in the list, and in the end justreturns Null .In[10]:=

Scan@Print, 87, 6, 5, 4<D

7654The evaluation of Scan stops as soon as Throw is encountered, and the enclosing Catchreturns as its value the argument of Throw .In[11]:=

Catch@Scan@HPrint@D; If@ < 6, Throw@DDL &, 87, 6, 5, 4<DD

765Out[11]= 5

The same result is obtained with Map, even though Map would have returned a list if its evaluation had not been stopped by encountering a Throw .In[12]:=

Catch@Map@HPrint@D; If@ < 6, Throw@DDL &, 87, 6, 5, 4<DD

765Out[12]=

You can use Throw and Catch to divert the operation of functional programming constructs,allowing for example the evaluation of such constructs to continue only until some condition hasbeen met. Note that if you stop evaluation using Throw, then the structure of the result you getmay be quite different from what you would have got if you had allowed the evaluation to

288

Core Language

You can use Throw and Catch to divert the operation of functional programming constructs,allowing for example the evaluation of such constructs to continue only until some condition hasbeen met. Note that if you stop evaluation using Throw, then the structure of the result you getmay be quite different from what you would have got if you had allowed the evaluation tocomplete.Here is a list generated by repeated application of a function.In[13]:=Out[13]=

NestList@1 H + 1L &, - 2.5, 6D

8-2.5, -0.666667, 3., 0.25, 0.8, 0.555556, 0.642857<

Since there is no Throw encountered, the result here is just as before.

In[14]:=Out[14]=

Catch@NestList@1 H + 1L &, - 2.5, 6DD

8-2.5, -0.666667, 3., 0.25, 0.8, 0.555556, 0.642857<

Now the evaluation of the NestList is diverted, and the single number given as the argumentof Throw is returned.In[15]:=Out[15]=

Catch@NestList@If@ > 1, Throw@D, 1 H + 1LD &, - 2.5, 6DD

3.

Throw and Catch operate in a completely global way: it does not matter how or where a Throwis generated~it will always stop evaluation and return to the enclosing Catch.The Throw stops the evaluation of f, and causes the Catch to return just a, with no trace of fleft.In[16]:=

Catch@f@Throw@aDDD

Out[16]= a

This defines a function which generates a Throw when its argument is larger than 10.In[17]:=

g@x_D := If@x > 10, Throw@overflowD, x !D

No Throw is generated here.

In[18]:=Out[18]=

Catch@g@4DD24

But here the Throw generated inside the evaluation of g returns to the enclosing Catch .In[19]:=Out[19]=

Catch@g@40DDoverflow

In small programs, it is often adequate to use Throw@valueD and Catch@exprD in their simplestform. But particularly if you write larger programs that contain many separate pieces, it is

Core Language

289

In small programs, it is often adequate to use Throw@valueD and Catch@exprD in their simplestform. But particularly if you write larger programs that contain many separate pieces, it isusually much better to use Throw@value, tagD and Catch@expr, formD. By keeping the expressionstag and form local to a particular piece of your program, you can then ensure that your Throwand Catch will also operate only within that piece.Here the Throw is caught by the inner Catch .In[20]:=Out[20]=

Catch@f@Catch@Throw@x, aD, aDD, bD

f@xD

But here it is caught only by the outer Catch .

In[21]:=Out[21]=

Catch@f@Catch@Throw@x, bD, aDD, bD

x

You can use patterns in specifying the tags which a particular Catch should catch.In[22]:=Out[22]=

Catch@Throw@x, aD, a

bD

This keeps the tag a completely local.

In[23]:=Out[23]=

Module@8a<, Catch@Throw@x, aD, aDD

x

You should realize that there is no need for the tag that appears in Throw to be a constant; ingeneral it can be any expression.Here the inner Catch catches all throws with tags less than 4, and continues the Do . But assoon as the tag reaches 4, the outer Catch is needed.In[24]:=Out[24]=

Catch@Do@Catch@Throw@i ^ 2, iD, n_ ; n < 4D, 8i, 10<D, _D

16

When you use Catch@expr, formD with Throw@value, tagD, the value returned by Catch is simplythe expression value given in the Throw. If you use Catch@expr, form, f D, however, then thevalue returned by Catch is instead f @value, tagD.Here f is applied to the value and tag in the Throw .In[25]:=Out[25]=

Catch@Throw@x, aD, a, fDf@x, aD

If there is no Throw , f is never used.

290

Core Language

If there is no Throw , f is never used.

In[26]:=Out[26]=

Catch@x, a, fDx

While@test,bodyD

evaluate body repetitively, so long as test is True

For@start,test,incr,bodyD

evaluate start, then repetitively evaluate body and incr, until

test fails

General loop constructs.

Functions like Do, Nest and FixedPoint provide structured ways to make loops in Mathematicaprograms, while Throw and Catch provide opportunities for modifying this structure. Sometimes, however, you may want to create loops that even from the outset have less structure.And in such cases, you may find it convenient to use the functions While and For, which perform operations repeatedly, stopping when a specified condition fails to be true.The While loop continues until the condition fails.In[27]:=

n = 17; While@Hn = Floor@n 2DL != 0, Print@nDD

8421The functions While and For in Mathematica are similar to the control structures while and forin languages such as C. Notice, however, that there are a number of important differences. Forexample, the roles of comma and semicolon are reversed in Mathematica For loops relative toC language ones.This is a very common form for a For loop. i ++ increments the value of i.In[28]:=

For@i = 1, i < 4, i ++, Print@iDD

123

Core Language

291

Here is a more complicated For loop. Notice that the loop terminates as soon as the testi ^ 2 < 10 fails.In[29]:=

For@i = 1; t = x, i ^ 2 < 10, i ++, t = t ^ 2 + i; Print@tDD

1 + x22 + I1 + x2 M

2 2

3 + J2 + I1 + x2 M N

In Mathematica, both While and For always evaluate the loop test before evaluating the bodyof the loop. As soon as the loop test fails to be True, While and For terminate. The body of theloop is thus only evaluated in situations where the loop test is True.The loop test fails immediately, so the body of the loop is never evaluated.In[30]:=

While@False, Print@xDD

In a While or For loop, or in general in any Mathematica procedure, the Mathematica expressions you give are evaluated in a definite sequence. You can think of this sequence as definingthe "flow of control" in the execution of a Mathematica program.In most cases, you should try to keep the flow of control in your Mathematica programs assimple as possible. The more the flow of control depends for example on specific values generated during the execution of the program, the more difficult you will typically find it to understand the structure and operation of the program.Functional programming constructs typically involve very simple flow of control. While and Forloops are always more complicated, since they are set up to make the flow of control depend onthe values of the expressions given as tests. Nevertheless, even in such loops, the flow ofcontrol does not usually depend on the values of expressions given in the body of the loop.In some cases, however, you may need to construct Mathematica programs in which the flow ofcontrol is affected by values generated during the execution of a procedure or of the body of aloop. One way to do this, which fits in with functional programming ideas, is to use Throw andCatch. But Mathematica also provides various functions for modifying the flow of control whichwork like in languages such as C.

292

Core Language

Break@D

exit the nearest enclosing loop

Continue@D

go to the next step in the current loop

Return@exprD

return the value expr, exiting all procedures and loops in a

function

Goto@nameD

go to the element Label@nameD in the current procedure

Throw@valueD

return value as the value of the nearest enclosing Catch

(non-local return)

Control flow functions.

The Break@D causes the loop to terminate as soon as t exceeds 19.In[31]:=

t = 1; Do@t *= k; Print@tD; If@t > 19, Break@DD, 8k, 10<D

t = 1; Do@t *= k; Print@tD; If@k < 3, Continue@DD; t += 2, 8k, 10<D

126321701032723857 920521 2985 213 000Return@exprD allows you to exit a particular function, returning a value. You can think of Throwas a kind of non-local return which allows you to exit a whole sequence of nested functions.Such behavior can be convenient for handling certain error conditions.Here is an example of the use of Return. This particular procedure could equally well havebeen written without using Return.

Core Language

293

Here is an example of the use of Return. This particular procedure could equally well havebeen written without using Return.In[33]:=

f@x_D := HIf@x > 5, Return@bigDD; t = x ^ 3; Return@t - 7DL

When the argument is greater than 5, the first Return in the procedure is used.

In[34]:=Out[34]=

f@10Dbig

This function "throws" error if its argument is negative.

In[35]:=

h@x_D := If@x < 0, Throw@errorD, Sqrt@xDD

No Throw is generated here.

In[36]:=Out[36]=

Catch@h@6D + 2D2+

But in this case a Throw is generated, and the whole Catch returns the value error.In[37]:=

Catch@h@- 6D + 2D

Out[37]= error

Functions like Continue@D and Break@D allow you to "transfer control" to the beginning or endof a loop in a Mathematica program. Sometimes you may instead need to transfer control to aparticular element in a Mathematica procedure. If you give a Label as an element in a procedure, you can use Goto to transfer control to this element.This goes on looping until q exceeds 6.In[38]:=

Hq = 2; Label@beginD; Print@qD; q += 3; If@q < 6, Goto@beginDDL

25Note that you can use Goto in a particular Mathematica procedure only when the Label itspecifies occurs as an element of the same Mathematica procedure. In general, use of Gotoreduces the degree of structure that can readily be perceived in a program, and thereforemakes the operation of the program more difficult to understand.

294

Core Language

Collecting Expressions During Evaluation

In many computations one is concerned only with the final result of evaluating the expressiongiven as input. But sometimes one also wants to collect expressions that were generated in thecourse of the evaluation. You can do this using Sow and Reap.

Sow@valD

sow the value val for the nearest enclosing Reap

Reap@exprD

evaluate expr, returning also a list of values sown by Sow

Using Sow and Reap .

Here the output contains only the final result.In[1]:=

a = 3; a += a ^ 2 + 1; a = Sqrt@a + a ^ 2D

Out[1]=

182

Here two intermediate results are also given.

In[2]:=

Reap@Sow@a = 3D; a += Sow@a ^ 2 + 1D; a = Sqrt@a + a ^ 2DD

Out[2]= :

182 , 883, 10<<>

This computes a sum, collecting all terms that are even.

In[3]:=

Reap@Sum@If@EvenQ@D, Sow@D, D &@i ^ 2 + 1D, 8i, 10<DD

Out[3]= 8395, 882, 10, 26, 50, 82<<<

Like Throw and Catch, Sow and Reap can be used anywhere in a computation.This defines a function that can do a Sow.In[4]:=

f@x_D := HIf@x < 1 2, Sow@xDD; 3.5 x H1 - xLL

This nests the function, reaping all cases below 1/2.

In[5]:=

Reap@Nest@f, 0.8, 10DD

Out[5]= 80.868312, 880.415332, 0.446472, 0.408785, 0.456285<<<

Core Language

Sow@val,tagD

sow val with a tag to indicate when to reap

Sow@val,8tag1 ,tag2 ,<D

sow val for each of the tagi

Reap@expr, formD

reap all values whose tags match form

Reap@expr,8 form1 , form2 ,<D

make separate lists for each of the formi

Reap@expr,8 form1 ,<, f D

apply f to each distinct tag and list of values

Sowing and reaping with tags.

This reaps only values sown with tag x.In[6]:=

Reap@Sow@1, xD; Sow@2, yD; Sow@3, xD, xD

Out[6]= 83, 881, 3<<<

Here 1 is sown twice with tag x.

In[7]:=

Reap@Sow@1, 8x, x<D; Sow@2, yD; Sow@3, xD, xD

Out[7]= 83, 881, 1, 3<<<

Values sown with different tags always appear in different sublists.

In[8]:=

Reap@Sow@1, 8x, x<D; Sow@2, yD; Sow@3, xDD

Out[8]= 83, 881, 1, 3<, 82<<<

The makes a sublist for each form of tag being reaped.

In[9]:=

Reap@Sow@1, 8x, x<D; Sow@2, yD; Sow@3, xD, 8x, x, y<D

Out[9]= 83, 8881, 1, 3<<, 881, 1, 3<<, 882<<<<

This applies f to each distinct tag and list of values.

In[10]:=Out[10]=

Reap@Sow@1, 8x, x<D; Sow@2, yD; Sow@3, xD, _, fD

83, 8f@x, 81, 1, 3<D, f@y, 82<D<<

The tags can be part of the computation.

In[11]:=

Reap@Do@Sow@i j, GCD@i, jDD, 8i, 4<, 8j, i<DD

Out[11]= :Null, ::1, 2, 3,

32

, 4,

43

>, 81, 2<, 81<, 81<>>

295

296

Core Language

Tracing EvaluationThe standard way in which Mathematica works is to take any expression you give as input,evaluate the expression completely, and then return the result. When you are trying to understand what Mathematica is doing, however, it is often worthwhile to look not just at the finalresult of evaluation, but also at intermediate steps in the evaluation process.

Trace@exprD

generate a list of all expressions used in the evaluation of

exprTrace@expr, formD

include only expressions which match the pattern form

Tracing the evaluation of expressions.

The expression 1 + 1 is evaluated immediately to 2.In[1]:=Out[1]=

Trace@1 + 1D81 + 1, 2<

The 2 ^ 3 is evaluated before the addition is done.

In[2]:=Out[2]=

Trace@2 ^ 3 + 4D9923 , 8=, 8 + 4, 12=

The evaluation of each subexpression is shown in a separate sublist.

In[3]:=Out[3]=

Trace@2 ^ 3 + 4 ^ 2 + 1D9923 , 8=, 942 , 16=, 8 + 16 + 1, 25=

Trace@exprD gives a list which includes all the intermediate expressions involved in the evaluation of expr. Except in rather simple cases, however, the number of intermediate expressionsgenerated in this way is typically very large, and the list returned by Trace is difficult to understand.Trace@expr, formD allows you to filter the expressions that Trace records, keeping only thosewhich match the pattern form.Here is a recursive definition of a factorial function.In[4]:=Out[4]=

fac@n_D := n fac@n - 1D; fac@1D = 1

1

This gives all the intermediate expressions generated in the evaluation of fac@3D. The result isquite complicated.

Core Language

297

This gives all the intermediate expressions generated in the evaluation of fac@3D. The result isquite complicated.In[5]:=Out[5]=

This shows only intermediate expressions of the form fac@n_D.

In[6]:=Out[6]=

Trace@fac@3D, fac@n_DD8fac@3D, 8fac@2D, 8fac@1D<<<

You can specify any pattern in Trace .

In[7]:=Out[7]=

Trace@fac@10D, fac@n_ ; n > 5DD

8fac@10D, 8fac@9D, 8fac@8D, 8fac@7D, 8fac@6D<<<<<

Trace@expr, formD effectively works by intercepting every expression that is about to be evaluated during the evaluation of expr, and picking out those that match the pattern form.If you want to trace calls to a function like fac, you can do so simply by telling Trace to pickout expressions of the form fac@n_D. You can also use patterns like f@n_, 2D to pick out callswith particular argument structure.A typical Mathematica program, however, consists not only of function calls like fac@nD, butalso of other elements, such as assignments to variables, control structures, and so on. All ofthese elements are represented as expressions. As a result, you can use patterns in Trace topick out any kind of Mathematica program element. Thus, for example, you can use a patternlike k = _ to pick out all assignments to the symbol k.This shows the sequence of assignments made for k.In[8]:=Out[8]=

Trace@Hk = 2; For@i = 1, i < 4, i ++, k = i kD; kL, k = _D

:8k = 2<, ::k =

>, 8k = 4<, :k =

>>>

Trace@expr, formD can pick out expressions that occur at any time in the evaluation of expr. Theexpressions need not, for example, appear directly in the form of expr that you give. They mayinstead occur, say, during the evaluation of functions that are called as part of the evaluation ofexpr.Here is a function definition.In[9]:=

h@n_D := Hk = n 2; Do@k = i k, 8i, n<D; kL

You can look for expressions generated during the evaluation of h.

298

Core Language

You can look for expressions generated during the evaluation of h.

In[10]:=Out[10]=

Trace@h@3D, k = _D::k =

>, ::k =

>, 8k = 3<, 8k = 1<>>

Trace allows you to monitor intermediate steps in the evaluation not only of functions that youdefine, but also of some functions that are built into Mathematica. You should realize, however,that the specific sequence of intermediate steps followed by built-in Mathematica functionsdepends in detail on their implementation and optimization in a particular version of Mathematica.

Trace@expr, f @___DD

show all calls to the function f

Trace@expr,i=_D

show assignments to i

Trace@expr,_=_D

show all assignments

Trace@expr,Message@___DD

show messages generated

Some ways to use Trace .

The function Trace returns a list that represents the history of a Mathematica computation.The expressions in the list are given in the order that they were generated during the computation. In most cases, the list returned by Trace has a nested structure, which represents thestructure of the computation.The basic idea is that each sublist in the list returned by Trace represents the evaluationchain for a particular Mathematica expression. The elements of this chain correspond to different forms of the same expression. Usually, however, the evaluation of one expression requiresthe evaluation of a number of other expressions, often subexpressions. Each subsidiary evaluation is represented by a sublist in the structure returned by Trace.Here is a sequence of assignments.In[11]:=Out[11]=

a@1D = a@2D; a@2D = a@3D; a@3D = a@4D

a@4D

This yields an evaluation chain reflecting the sequence of transformations for a@iD used.In[12]:=Out[12]=

Trace@a@1DD8a@1D, a@2D, a@3D, a@4D<

The successive forms generated in the simplification of y + x + y show up as successive elements in its evaluation chain.

Core Language

299

The successive forms generated in the simplification of y + x + y show up as successive elements in its evaluation chain.In[13]:=Out[13]=

Trace@y + x + yD8y + x + y, x + y + y, x + 2 y<

Each argument of the function f has a separate evaluation chain, given in a sublist.In[14]:=Out[14]=

The evaluation chain for each subexpression is given in a separate sublist.

In[15]:=Out[15]=

Trace@x x + y yD99x x, x2 =, 9y y, y2 =, x2 + y2 =

Tracing the evaluation of a nested expression yields a nested list.

In[16]:=Out[16]=

Trace@f@f@f@1 + 1DDDD88881 + 1, 2<, f@2D<, f@f@2DD<, f@f@f@2DDD<

There are two basic ways that subsidiary evaluations can be required during the evaluation of aMathematica expression. The first way is that the expression may contain subexpressions, eachof which has to be evaluated. The second way is that there may be rules for the evaluation ofthe expression that involve other expressions which themselves must be evaluated. Both kindsof subsidiary evaluations are represented by sublists in the structure returned by Trace.The subsidiary evaluations here come from evaluation of the arguments of f and g.In[17]:=Out[17]=

You often get nested lists when you trace the evaluation of functions that are definedrecursively in terms of other instances of themselves. The reason is typically that each newinstance of the function appears as a subexpression in the expressions obtained by evaluatingprevious instances of the function.

300

Core Language

You often get nested lists when you trace the evaluation of functions that are definedrecursively in terms of other instances of themselves. The reason is typically that each newinstance of the function appears as a subexpression in the expressions obtained by evaluatingprevious instances of the function.Thus, for example, with the definition fac@n_D := n fac@n - 1D, the evaluation of fac@6D yieldsthe expression 6 fac@5D, which contains fac@5D as a subexpression.The successive instances of fac generated appear in successively nested sublists.In[20]:=Out[20]=

fp@nD never appears in a subexpression, so no sublists are generated.

Here is the recursive definition of the Fibonacci numbers.

fib@n_D := fib@n - 1D + fib@n - 2D

Here are the end conditions for the recursion.

In[24]:=Out[24]=

fib@0D = fib@1D = 11

This shows all the steps in the recursive evaluation of fib@5D.

In[25]:=

Trace@fib@5D, fib@_DD

Out[25]=

Each step in the evaluation of any Mathematica expression can be thought of as the result ofapplying a particular transformation rule. As discussed in "Associating Definitions with DifferentSymbols", all the rules that Mathematica knows are associated with specific symbols or tags.You can use Trace@expr, f D to see all the steps in the evaluation of expr that are performedusing transformation rules associated with the symbol f . In this case, Trace gives not only theexpressions to which each rule is applied, but also the results of applying the rules.In general, Trace@expr, formD picks out all the steps in the evaluation of expr where formmatches either the expression about to be evaluated, or the tag associated with the rule used.

Core Language

301

In general, Trace@expr, formD picks out all the steps in the evaluation of expr where formmatches either the expression about to be evaluated, or the tag associated with the rule used.

Trace@expr, f D

show all evaluations which use transformation rules associated with the symbol f

Trace@expr, f gD

show all evaluations associated with either f or g

Tracing evaluations associated with particular tags.

This shows only intermediate expressions that match fac@_D.In[26]:=Out[26]=

Trace@fac@3D, fac@_DD8fac@3D, 8fac@2D, 8fac@1D<<<

This shows all evaluations that use transformation rules associated with the symbol fac.In[27]:=Out[27]=

Trace@log@a b c dD, logD

TraceAexpr, form,TraceOn->oformEswitch on tracing only within forms matching oform

TraceAexpr, form,TraceOff->oformEswitch off tracing within any form matching oformSwitching off tracing inside certain forms.

Trace@expr, formD allows you to trace expressions matching form generated at any point in theevaluation of expr. Sometimes, you may want to trace only expressions generated during certainparts of the evaluation of expr.By setting the option TraceOn -> oform, you can specify that tracing should be done only duringthe evaluation of forms which match oform. Similarly, by setting TraceOff -> oform, you canspecify that tracing should be switched off during the evaluation of forms which match oform.This shows all steps in the evaluation.

This shows all steps in the evaluation.

This shows only those steps that occur during the evaluation of fac.In[31]:=Out[31]=

Trace@log@fac@2D xD, TraceOn -> facD

888fac@2D, 2 fac@2 - 1D, 882 - 1, 1<, fac@1D, 1<, 2 1, 2<<<

This shows only those steps that do not occur during the evaluation of fac.In[32]:=Out[32]=

Trace@log@fac@2D xD, TraceOff -> facD

888fac@2D, 2<, 2 x<, log@2 xD, log@2D + log@xD<

Trace@expr,lhs->rhsD

find all expressions matching lhs that arise during the

evaluation of expr, and replace them with rhs

Applying rules to expressions encountered during evaluation.

This tells Trace to return only the arguments of fib used in the evaluation of fib@5D.In[33]:=

Trace@fib@5D, fib@n_D -> nD

Out[33]=

A powerful aspect of the Mathematica Trace function is that the object it returns is basically astandard Mathematica expression which you can manipulate using other Mathematica functions.One important point to realize, however, is that Trace wraps all expressions that appear in thelist it produces with HoldForm to prevent them from being evaluated. The HoldForm is notdisplayed in standard Mathematica output format, but it is still present in the internal structureof the expression.This shows the expressions generated at intermediate stages in the evaluation process.In[34]:=Out[34]=

Trace@1 + 3 ^ 2D9932 , 9=, 1 + 9, 10=

The expressions are wrapped with HoldForm to prevent them from evaluating.In[35]:=

Trace@1 + 3 ^ 2D InputForm

Out[35]//InputForm=

{{HoldForm[3^2], HoldForm[9]}, HoldForm[1 + 9],

HoldForm[10]}

In standard Mathematica output format, it is sometimes difficult to tell which lists are associated with the structure returned by Trace , and which are expressions being evaluated.

Core Language

303

In standard Mathematica output format, it is sometimes difficult to tell which lists are associated with the structure returned by Trace , and which are expressions being evaluated.In[36]:=Out[36]=

Trace@81 + 1, 2 + 3<D881 + 1, 2<, 82 + 3, 5<, 82, 5<<

Looking at the input form resolves any ambiguities.

In[37]:=

InputForm@%D

Out[37]//InputForm=

{{HoldForm[1 + 1], HoldForm[2]},

{HoldForm[2 + 3], HoldForm[5]}, HoldForm[{2, 5}]}

When you use a transformation rule in Trace , the result is evaluated before being wrappedwith HoldForm .In[38]:=Out[38]=

Trace@fac@4D, fac@n_D -> n + 1D

85, 84, 83, 82<<<<

For sophisticated computations, the list structures returned by Trace can be quite complicated.When you use Trace@expr, formD, Trace will include as elements in the lists only those expressions which match the pattern form. But whatever pattern you give, the nesting structure of thelists remains the same.This shows all occurrences of fib@_D in the evaluation of fib@3D.In[39]:=Out[39]=

Trace@fib@3D, fib@_DD8fib@3D, 8fib@2D, 8fib@1D<, 8fib@0D<<, 8fib@1D<<

This shows only occurrences of fib@1D, but the nesting of the lists is the same as for fib@_D.In[40]:=Out[40]=

Trace@fib@3D, fib@1DD888fib@1D<<, 8fib@1D<<

You can set the option TraceDepth -> n to tell Trace to include only lists nested at most nlevels deep. In this way, you can often pick out the big steps in a computation, without seeingthe details. Note that by setting TraceDepth or TraceOff you can avoid looking at many of thesteps in a computation, and thereby significantly speed up the operation of Trace for thatcomputation.This shows only steps that appear in lists nested at most two levels deep.In[41]:=

Trace@fib@3D, fib@_D, TraceDepth -> 2D

Out[41]= 8fib@3D, 8fib@1D<<

304

Core Language

TraceAexpr, form,TraceDepth->nEtrace the evaluation of expr, ignoring steps that lead to listsnested more than n levels deepRestricting the depth of tracing.

When you use Trace@expr, formD, you get a list of all the expressions which match form produced during the evaluation of expr. Sometimes it is useful to see not only these expressions,but also the results that were obtained by evaluating them. You can do this by setting theoption TraceForward -> True in Trace.This shows not only expressions which match fac@_D, but also the results of evaluating thoseexpressions.In[42]:=

Trace@fac@4D, fac@_D, TraceForward -> TrueD

Out[42]= 8fac@4D, 8fac@3D, 8fac@2D, 8fac@1D, 1<, 2<, 6<, 24<

Expressions picked out using Trace@expr, formD typically lie in the middle of an evaluationchain. By setting TraceForward -> True, you tell Trace to include also the expression obtainedat the end of the evaluation chain. If you set TraceForward -> All, Trace will include all theexpressions that occur after the expression matching form on the evaluation chain.With TraceForward -> All, all elements on the evaluation chain after the one that matchesfac@_D are included.In[43]:=Out[43]=

Trace@fac@4D, fac@_D, TraceForward -> AllD

By setting the option TraceForward, you can effectively see what happens to a particular formof expression during an evaluation. Sometimes, however, you want to find out not what happens to a particular expression, but instead how that expression was generated. You can do thisby setting the option TraceBackward. What TraceBackward does is to show you what precededa particular form of expression on an evaluation chain.This shows that the number 120 came from the evaluation of fac@5D during the evaluation offac@10D.In[44]:=Out[44]=

Trace@fac@10D, 120, TraceBackward -> TrueD

888888fac@5D, 120<<<<<<

Core Language

305

Here is the whole evaluation chain associated with the generation of the number 120.In[45]:=Out[45]=

Trace@fac@10D, 120, TraceBackward -> AllD

888888fac@5D, 5 fac@5 - 1D, 5 24, 120<<<<<<

TraceForward and TraceBackward allow you to look forward and backward in a particularevaluation chain. Sometimes, you may also want to look at the evaluation chains within whichthe particular evaluation chain occurs. You can do this using TraceAbove. If you set the optionTraceAbove -> True, then Trace will include the initial and final expressions in all the relevantevaluation chains. With TraceAbove -> All, Trace includes all the expressions in all theseevaluation chains.This includes the initial and final expressions in all evaluation chains which contain the chainthat contains 120.In[46]:=Out[46]=

Trace@fac@7D, 120, TraceAbove -> TrueD

8fac@7D, 8fac@6D, 8fac@5D, 120<, 720<, 5040<

This shows all the ways that fib@2D is generated during the evaluation of fib@5D.In[47]:=

Trace@fib@5D, fib@2D, TraceAbove -> TrueD

Out[47]=

Trace@expr, form,optsD

trace the evaluation of expr using the specified options

TraceForward->True

include the final expression in the evaluation chain contain ing form

TraceForward->All

include all expressions following form in the evaluation

chain

TraceBackward->True

include the first expression in the evaluation chain contain ing form

TraceBackward->All

include all expressions preceding form in the evaluation

chain

TraceAbove->True

include the first and last expressions in all evaluation

chains which contain the chain containing form

TraceAbove->All

include all expressions in all evaluation chains which

contain the chain containing form

Option settings for including extra steps in trace lists.

The basic way that Trace@expr, D works is to intercept each expression encountered duringthe evaluation of expr, and then to use various criteria to determine whether this expressionshould be recorded. Normally, however, Trace intercepts expressions only after function arguments have been evaluated. By setting TraceOriginal -> True, you can get Trace also to lookat expressions before function arguments have been evaluated.

306

Core Language

The basic way that Trace@expr, D works is to intercept each expression encountered duringthe evaluation of expr, and then to use various criteria to determine whether this expressionshould be recorded. Normally, however, Trace intercepts expressions only after function arguments have been evaluated. By setting TraceOriginal -> True, you can get Trace also to lookat expressions before function arguments have been evaluated.This includes expressions which match fac@_D both before and after argument evaluation.In[48]:=Out[48]=

Trace@fac@3D, fac@_D, TraceOriginal -> TrueD

8fac@3D, 8fac@3 - 1D, fac@2D, 8fac@2 - 1D, fac@1D<<<

The list structure produced by Trace normally includes only expressions that constitute steps innon-trivial evaluation chains. Thus, for example, individual symbols that evaluate to themselvesare not normally included. Nevertheless, if you set TraceOriginal -> True, then Trace looksat absolutely every expression involved in the evaluation process, including those that havetrivial evaluation chains.In this case, Trace includes absolutely all expressions, even those with trivial evaluationchains.In[49]:=Out[49]=

Trace@fac@1D, TraceOriginal -> TrueD

8fac@1D, 8fac<, 81<, fac@1D, 1<

option name

default value

TraceForward

False

TraceBackward

False

TraceAbove

False

TraceOriginal

False

whether to show expressions following form

in the evaluation chainwhether to show expressions precedingform in the evaluation chainwhether to show evaluation chains leadingto the evaluation chain containing formwhether to look at expressions before theirheads and arguments are evaluated

Additional options for Trace .

When you use Trace to study the execution of a program, there is an issue about how localvariables in the program should be treated. As discussed in "How Modules Work", Mathematicascoping constructs such as Module create symbols with new names to represent local variables.Thus, even if you called a variable x in the original code for your program, the variable mayeffectively be renamed x$nnn when the program is executed.Trace@expr, formD is set up so that by default a symbol x that appears in form will match allsymbols with names of the form x$nnn that arise in the execution of expr. As a result, you canfor example use Trace@expr, x = _D to trace assignment to all variables, local and global, that

Core Language

307

Trace@expr, formD is set up so that by default a symbol x that appears in form will match allsymbols with names of the form x$nnn that arise in the execution of expr. As a result, you canfor example use Trace@expr, x = _D to trace assignment to all variables, local and global, thatwere named x in your original program.

TraceAexpr, form,MatchLocalNames->FalseEinclude all steps in the execution of expr that match form,with no replacements for local variable names allowedPreventing the matching of local variables.

In some cases, you may want to trace only the global variable x, and not any local variablesthat were originally named x. You can do this by setting the option MatchLocalNames -> False.This traces assignments to all variables with names of the form x$nnn.In[50]:=Out[50]=

Trace@Module@8x<, x = 5D, x = _D88x$1 = 5<<

This traces assignments only to the specific global variable x.

In[51]:=Out[51]=

Trace@Module@8x<, x = 5D, x = _, MatchLocalNames -> FalseD

8<

The function Trace performs a complete computation, then returns a structure which represents the history of the computation. Particularly in very long computations, it is howeversometimes useful to see traces of the computation as it proceeds. The function TracePrintworks essentially like Trace, except that it prints expressions when it encounters them, ratherthan saving up all of the expressions to create a list structure.

308

Core Language

This prints expressions encountered in the evaluation of fib@3D.

The sequence of expressions printed by TracePrint corresponds to the sequence of expressions given in the list structure returned by Trace. Indentation in the output from TracePrintcorresponds to nesting in the list structure from Trace. You can use the Trace optionsTraceOn, TraceOff and TraceForward in TracePrint. However, since TracePrint producesoutput as it goes, it cannot support the option TraceBackward. In addition, TracePrint is setup so that TraceOriginal is effectively always set to True.

Trace@expr,D

trace the evaluation of expr, returning a list structure

containing the expressions encountered

TracePrint@expr,D

trace the evaluation of expr, printing the expressions

encountered

TraceDialog @expr,D

trace the evaluation of expr, initiating a dialog when each

specified expression is encountered

TraceScan@ f ,expr,D

trace the evaluation of expr, applying f to HoldForm of

each expression encountered

Functions for tracing evaluation.

This enters a dialog when fac@5D is encountered during the evaluation of fac@10D.In[53]:=

Inside the dialog you can for example find out where you are by looking at the stack.

Core Language

309

Inside the dialog you can for example find out where you are by looking at the stack.In[54]:=

Stack@D

Out[54]= 8TraceDialog, Times, Times, Times, Times, Times, fac<

This returns from the dialog, and gives the final result from the evaluation of fac@10D.In[55]:=

Return@DTraceDialog::dgend : Exiting Dialog.

Out[55]=

3 628 800

The function TraceDialog effectively allows you to stop in the middle of a computation, andinteract with the Mathematica environment that exists at that time. You can for example findvalues of intermediate variables in the computation, and even reset those values. There arehowever a number of subtleties, mostly associated with pattern and module variables.What TraceDialog does is to call the function Dialog on a sequence of expressions. TheDialog function is discussed in detail in "Dialogs". When you call Dialog, you are effectivelystarting a subsidiary Mathematica session with its own sequence of input and output lines.In general, you may need to apply arbitrary functions to the expressions you get while tracingan evaluation. TraceScan@ f , expr, D applies f to each expression that arises. The expressionis wrapped with HoldForm to prevent it from evaluating.In TraceScan@ f , expr, D, the function f is applied to expressions before they are evaluated.TraceScan@ f , expr, patt, fpD applies f before evaluation, and fp after evaluation.

The Evaluation Stack

Throughout any computation, Mathematica maintains an evaluation stack containing the expressions it is currently evaluating. You can use the function Stack to look at the stack. Thismeans, for example, that if you interrupt Mathematica in the middle of a computation, you canuse Stack to find out what Mathematica is doing.The expression that Mathematica most recently started to evaluate always appears as the lastelement of the evaluation stack. The previous elements of the stack are the other expressionswhose evaluation is currently in progress.Thus at the point when x is being evaluated, the stack associated with the evaluation of anexpression like f @g@xDD will have the form 8 f @g@xDD, g@xD, x<.

310

Core Language

Thus at the point when x is being evaluated, the stack associated with the evaluation of anexpression like f @g@xDD will have the form 8 f @g@xDD, g@xD, x<.Stack@_D gives the expressions that are being evaluated at the time when it is called, in thiscase including the Print function.In[1]:=

f@g@Print@Stack@_DDDD;

8f@g@Print@Stack@_DDDD;, f@g@Print@Stack@_DDDD,g@Print@Stack@_DDD, Print@Stack@_DD<Stack@D gives the tags associated with the evaluations that are being done when it is called.In[2]:=

f@g@Print@Stack@DDDD;

8CompoundExpression, f, g, Print<In general, you can think of the evaluation stack as showing what functions called what otherfunctions to get to the point Mathematica is at in your computation. The sequence of expressions corresponds to the first elements in the successively nested lists returned by Trace withthe option TraceAbove set to True.

Stack@D

give a list of the tags associated with evaluations that are

currently being done

Stack@_D

give a list of all expressions currently being evaluated

Stack@ formD

include only expressions which match form

Looking at the evaluation stack.

It is rather rare to call Stack directly in your main Mathematica session. More often, you willwant to call Stack in the middle of a computation. Typically, you can do this from within adialog, or subsidiary session, as discussed in "Dialogs".Here is the standard recursive definition of the factorial function.In[3]:=

fac@1D = 1; fac@n_D := n fac@n - 1D

This shows what objects were being evaluated when the dialog was started.In[5]:=Out[5]=

Stack@D8TraceDialog, Times, Times, Times, Times, Times, Times, fac<

This ends the dialog.

In[6]:=

Return@DTraceDialog::dgend : Exiting Dialog.

Out[6]=

3 628 800

In the simplest cases, the Mathematica evaluation stack is set up to record all expressionscurrently being evaluated. Under some circumstances, however, this may be inconvenient. Forexample, executing Print@Stack@DD will always show a stack with Print as the last function.The function StackInhibit allows you to avoid this kind of problem. StackInhibit@exprDevaluates expr without modifying the stack.StackInhibit prevents Print from being included on the stack.In[7]:=Out[7]=

f@g@StackInhibit@Print@Stack@DDDDD;8CompoundExpression, f, g<

Functions like TraceDialog automatically call StackInhibit each time they start a dialog. Thismeans that Stack does not show functions that are called within the dialog, only those outside.

StackInhibit@exprD

evaluate expr without modifying the stack

StackBegin@exprD

evaluate expr with a fresh stack

StackComplete@exprD

evaluate expr with intermediate expressions in evaluation

chains included on the stack

Controlling the evaluation stack.

By using StackInhibit and StackBegin, you can control which parts of the evaluation processare recorded on the stack. StackBegin@exprD evaluates expr, starting a fresh stack. This meansthat during the evaluation of expr, the stack does not include anything outside the StackBegin.Functions like TraceDialog @expr, D call StackBegin before they begin evaluating expr, so thatthe stack shows how expr is evaluated, but not how TraceDialog was called.

312

Core Language

StackBegin@exprD uses a fresh stack in the evaluation of expr.

In[8]:=

f@StackBegin@g@h@StackInhibit@Print@Stack@DDDDDDD

8g, h<Out[8]=

f@g@h@NullDDD

Stack normally shows you only those expressions that are currently being evaluated. As aresult, it includes only the latest form of each expression. Sometimes, however, you may find ituseful also to see earlier forms of the expressions. You can do this using StackComplete.What StackComplete@exprD effectively does is to keep on the stack the complete evaluationchain for each expression that is currently being evaluated. In this case, the stack correspondsto the sequence of expressions obtained from Trace with the option TraceBackward -> All aswell as TraceAbove -> True.

Controlling Infinite Evaluation

The general principle that Mathematica follows in evaluating expressions is to go on applyingtransformation rules until the expressions no longer change. This means, for example, that ifyou make an assignment like x = x + 1, Mathematica should go into an infinite loop. In fact,Mathematica stops after a definite number of steps, determined by the value of the globalvariable $RecursionLimit. You can always stop Mathematica earlier by explicitly interruptingit.This assignment could cause an infinite loop. Mathematica stops after a number of steps determined by $RecursionLimit .In[1]:=

x = x+1$RecursionLimit::reclim : Recursion depth of 256 exceeded.

Out[1]= 255 + Hold@1 + xD

When Mathematica stops without finishing evaluation, it returns a held result. You can continuethe evaluation by explicitly calling ReleaseHold .In[2]:=

8a, b< = 8b, a<

Out[3]= 8Hold@bD, Hold@aD<

The variables $RecursionLimit and $IterationLimit control the two basic ways that anevaluation can become infinite in Mathematica. $RecursionLimit limits the maximum depth ofthe evaluation stack, or equivalently, the maximum nesting depth that would occur in the liststructure produced by Trace. $IterationLimit limits the maximum length of any particularevaluation chain, or the maximum length of any single list in the structure produced by Trace.$RecursionLimit and $IterationLimit are by default set to values that are appropriate formost computations, and most computer systems. You can, however, reset these variables toany integer (above a lower limit), or to Infinity. Note that on most computer systems, youshould never set $RecursionLimit = Infinity, as discussed in "Memory Management".This resets $RecursionLimit and $IterationLimit to 20.In[4]:=

$RecursionLimit = $IterationLimit = 20

Out[4]= 20

Now infinite definitions like this are stopped after just 20 steps.In[5]:=

t = 8t<$RecursionLimit::reclim : Recursion depth of 20 exceeded.

Out[5]=

Without an end condition, this recursive definition leads to infinite computations.

In[6]:=

fn@n_D := 8fn@n - 1D, n<

314

Core Language

A fairly large structure is built up before the computation is stopped.

In[7]:=

fn@10D$RecursionLimit::reclim : Recursion depth of 20 exceeded.

Out[7]=

Here is another recursive definition.

In[8]:=

fm@n_D := fm@n - 1DIn this case, no complicated structure is built up, and the computation is stopped by$IterationLimit .

In[9]:=

fm@0D$IterationLimit::itlim : Iteration limit of 20 exceeded.

Out[9]= Hold@fm@-19 - 1DD

It is important to realize that infinite loops can take up not only time but also computer memory. Computations limited by $IterationLimit do not normally build up large intermediatestructures. But those limited by $RecursionLimit often do. In many cases, the size of thestructures produced is a linear function of the value of $RecursionLimit. But in some cases,the size can grow exponentially, or worse, with $RecursionLimit.An assignment like x = x + 1 is obviously circular. When you set up more complicated recursivedefinitions, however, it can be much more difficult to be sure that the recursion terminates, andthat you will not end up in an infinite loop. The main thing to check is that the right-hand sidesof your transformation rules will always be different from the left-hand sides. This ensures thatevaluation will always make progress, and Mathematica will not simply end up applying thesame transformation rule to the same expression over and over again.Some of the trickiest cases occur when you have rules that depend on complicated ; conditions (see "Putting Constraints on Patterns"). One particularly awkward case is when the condition involves a global variable. Mathematica may think that the evaluation is finished becausethe expression did not change. However, a side effect of some other operation could change thevalue of the global variable, and so should lead to a new result in the evaluation. The best wayto avoid this kind of difficulty is not to use global variables in ; conditions. If all else fails, youcan type Update@sD to tell Mathematica to update all expressions involving s. Update@D tellsMathematica to update absolutely all expressions.

Interrupts and Aborts

Core Language

315

Interrupts and Aborts

"Interrupting Calculations" describes how you can interrupt a Mathematica computation bypressing appropriate keys on your keyboard.In some cases, you may want to simulate such interrupts from within a Mathematica program.In general, executing Interrupt@D has the same effect as pressing interrupt keys. On a typicalsystem, a menu of options is displayed, as discussed in "Interrupting Calculations".

Interrupt@D

interrupt a computation

Abort@D

abort a computation

CheckAbort@expr, failexprD

evaluate expr and return the result, or failexpr if an abort

occurs

AbortProtect@exprD

evaluate expr, masking the effect of aborts until the evaluation is complete

Interrupts and aborts.

The function Abort@D has the same effect as interrupting a computation, and selecting theabort option in the interrupt menu.You can use Abort@D to implement an emergency stop in a program. In almost all cases,however, you should try to use functions like Return and Throw, which lead to more controlledbehavior.Abort terminates the computation, so only the first Print is executed.Print@aD; Abort@D; Print@bD

In[1]:=

aOut[1]=

$Aborted

If you abort at any point during the evaluation of a Mathematica expression, Mathematicanormally abandons the evaluation of the whole expression, and returns the value $Aborted.You can, however, catch aborts using the function CheckAbort. If an abort occurs during theevaluation of expr in CheckAbort@expr, failexprD, then CheckAbort returns failexpr, but the abortpropagates no further. Functions like Dialog use CheckAbort in this way to contain the effectof aborts.

CheckAbort@Print@aD; Abort@D; Print@bD, Print@cD; abortedD

acOut[2]=

aborted

The effect of the Abort is contained by CheckAbort , so b is printed.

In[3]:=

CheckAbort@Print@aD; Abort@D, Print@cD; abortedD; Print@bD

acbWhen you construct sophisticated programs in Mathematica, you may sometimes want toguarantee that a particular section of code in a program cannot be aborted, either interactivelyor by calling Abort. The function AbortProtect allows you to evaluate an expression, savingup any aborts until after the evaluation of the expression is complete.The Abort is saved up until AbortProtect is finished.In[4]:=

AbortProtect@Abort@D; Print@aDD; Print@bD

aOut[4]=

$Aborted

The CheckAbort sees the abort, but does not propagate it further.In[5]:=

AbortProtect@Abort@D; CheckAbort@Print@aD, xDD; Print@bD

bEven inside AbortProtect, CheckAbort will see any aborts that occur, and will return theappropriate failexpr. Unless this failexpr itself contains Abort@D, the aborts will be absorbed bythe CheckAbort.

Core Language

317

Compiling Mathematica Expressions

If you make a definition like f@x_D := x Sin@xD, Mathematica will store the expression x Sin@xDin a form that can be evaluated for any x. Then when you give a particular value for x, Mathematica substitutes this value into x Sin@xD, and evaluates the result. The internal code thatMathematica uses to perform this evaluation is set up to work equally well whether the valueyou give for x is a number, a list, an algebraic object, or any other kind of expression.Having to take account of all these possibilities inevitably makes the evaluation process slower.However, if Mathematica could assume that x will be a machine number, then it could avoidmany steps, and potentially evaluate an expression like x Sin@xD much more quickly.Using Compile, you can construct compiled functions in Mathematica, which evaluate Mathematica expressions assuming that all the parameters which appear are numbers (or logical variables). Compile@8x1 , x2 , <, exprD takes an expression expr and returns a "compiled function"which evaluates this expression when given arguments x1 , x2 , .In general, Compile creates a CompiledFunction object which contains a sequence of simpleinstructions for evaluating the compiled function. The instructions are chosen to be close tothose found in the machine code of a typical computer, and can thus be executed quickly.

Compile@8x1 ,x2 ,<,exprD

create a compiled function which evaluates expr for numerical values of the xi

Creating compiled functions.

This defines f to be a pure function which evaluates x Sin@xD for any x.In[1]:=

f = Function@8x<, x Sin@xDD

Out[1]= Function@8x<, x Sin@xDD

This creates a compiled function for evaluating x Sin@xD.

In[2]:=

fc = Compile@8x<, x Sin@xDD

Out[2]= CompiledFunction@8x<, x Sin@xD, -CompiledCode-D

f and fc yield the same results, but fc runs faster when the argument you give is a number.In[3]:=

8f@2.5D, fc@2.5D<

Out[3]= 81.49618, 1.49618<

Compile is useful in situations where you have to evaluate a particular numerical or logicalexpression many times. By taking the time to call Compile, you can get a compiled function

318

Core Language

Compile is useful in situations where you have to evaluate a particular numerical or logicalexpression many times. By taking the time to call Compile, you can get a compiled functionwhich can be executed more quickly than an ordinary Mathematica function.For simple expressions such as x Sin@xD, there is usually little difference between the executionspeed for ordinary and compiled functions. However, as the size of the expressions involvedincreases, the advantage of compilation also increases. For large expressions, compilation canspeed up execution by a factor as large as 20.Compilation makes the biggest difference for expressions containing a large number of simple,say arithmetic, functions. For more complicated functions, such as BesselK or Eigenvalues ,most of the computation time is spent executing internal Mathematica algorithms, on whichcompilation has no effect.This creates a compiled function for finding values of the tenth Legendre polynomial. TheEvaluate tells Mathematica to construct the polynomial explicitly before doing compilation.In[4]:=

pc = Compile@8x<, Evaluate@LegendreP@10, xDDD

This finds the value of the tenth Legendre polynomial with argument 0.4.In[5]:=

pc@0.4D

Out[5]= 0.0968391

This uses built-in numerical code.

In[6]:=

LegendreP@10, 0.4D

Out[6]= 0.0968391

Even though you can use compilation to speed up numerical functions that you write, youshould still try to use built-in Mathematica functions whenever possible. Built-in functions willusually run faster than any compiled Mathematica programs you can create. In addition, theytypically use more extensive algorithms, with more complete control over numerical precisionand so on.

Core Language

319

You should realize that built-in Mathematica functions quite often themselves use Compile.Thus, for example, NIntegrate by default automatically uses Compile on the expression youtell it to integrate. Similarly, functions like Plot and Plot3D use Compile on the expressionsyou ask them to plot. Built-in functions that use Compile typically have the option Compiled.Setting Compiled -> False tells the functions not to use Compile.

Compile@88x1 ,t1 <,8x2 ,t2 <,<,exprD

compile expr assuming that xi is of type ti

Compile@88x1 ,t1 ,n1 <,8x2 ,t2 ,n2 <,<,exprD

compile expr assuming that xi is a rank ni array of objectseach of type ti

Compile@vars,expr,88p1 ,pt1 <,<D

compile expr, assuming that subexpressions which match

pi are of type pti

_Integer

machine-size integer

_Real

machine-precision approximate real number

_Complex

machine-precision approximate complex number

True False

logical variable

Specifying types for compilation.

Compile works by making assumptions about the types of objects that occur in evaluating theexpression you give. The default assumption is that all variables in the expression are approximate real numbers.Compile nevertheless also allows integers, complex numbers and logical variables (True orFalse), as well as arrays of numbers. You can specify the type of a particular variable by givinga pattern which matches only values that have that type. Thus, for example, you can use thepattern _Integer to specify the integer type. Similarly, you can use True

False to specify a

logical variable that must be either True or False.

This compiles the expression 5 i + j with the assumption that i and j are integers.In[7]:=

Compile@88i, _Integer<, 8j, _Integer<<, 5 i + jD

Out[7]= CompiledFunction@8i, j<, 5 i + j, -CompiledCode-D

320

Core Language

This yields an integer result.

In[8]:=

%@8, 7D

Out[8]= 47

This compiles an expression that performs an operation on a matrix of integers.

In[9]:=

Compile@88m, _Integer, 2<<, Apply@Plus, Flatten@mDDD

Out[9]= CompiledFunction@8m<, Plus Flatten@mD, -CompiledCode-D

The list operations are now carried out in a compiled way, and the result is an integer.In[10]:=

%@881, 2, 3<, 87, 8, 9<<D

Out[10]= 30

The types that Compile handles correspond essentially to the types that computers typicallyhandle at a machine-code level. Thus, for example, Compile can handle approximate realnumbers that have machine precision, but it cannot handle arbitrary-precision numbers. Inaddition, if you specify that a particular variable is an integer, Compile generates code only forthe case when the integer is of "machine size", typically between 231 .When the expression you ask to compile involves only standard arithmetic and logical operations, Compile can deduce the types of objects generated at every step simply from the typesof the input variables. However, if you call other functions, Compile will typically not know whattype of value they return. If you do not specify otherwise, Compile assumes that any otherfunction yields an approximate real number value. You can, however, also give an explicit list ofpatterns, specifying what type to assume for an expression that matches a particular pattern.This defines a function which yields an integer result when given an integer argument.In[11]:=

Compile@8x, 8i, _Integer<<, x ^ com@iD, 88com@_D, _Integer<<D

com@iD, -CompiledCode-EOut[12]= CompiledFunctionA8x, i<, x

This evaluates the compiled function.

In[13]:=

%@5.6, 1D

Out[13]= 31.36

The idea of Compile is to create a function which is optimized for certain types of arguments.Compile is nevertheless set up so that the functions it creates work with whatever types ofarguments they are given. When the optimization cannot be used, a standard Mathematica

Core Language

321

The idea of Compile is to create a function which is optimized for certain types of arguments.Compile is nevertheless set up so that the functions it creates work with whatever types ofarguments they are given. When the optimization cannot be used, a standard Mathematicaexpression is evaluated to find the value of the function.Here is a compiled function for taking the square root of a variable.In[14]:=

sq = Compile@8x<, Sqrt@xDD

Out[14]= CompiledFunctionB8x<,

x , -CompiledCode-F

If you give a real number argument, optimized code is used.

In[15]:=

sq@4.5D

Out[15]= 2.12132

The compiled code cannot be used, so Mathematica prints a warning, then just evaluates theoriginal symbolic expression.In[16]:=

The compiled code generated by Compile must make assumptions not only about the types ofarguments you will supply, but also about the types of all objects that arise during the execution of the code. Sometimes these types depend on the actual values of the arguments youspecify. Thus, for example, Sqrt@xD yields a real number result for real x if x is not negative,but yields a complex number if x is negative.Compile always makes a definite assumption about the type returned by a particular function.If this assumption turns out to be invalid in a particular case when the code generated byCompile is executed, then Mathematica simply abandons the compiled code in this case, andevaluates an ordinary Mathematica expression to get the result.

322

Core Language

The compiled code does not expect a complex number, so Mathematica has to revert to explicitly evaluating the original symbolic expression.In[17]:=

An important feature of Compile is that it can handle not only mathematical expressions, butalso various simple Mathematica programs. Thus, for example, Compile can handle conditionalsand control flow structures.In all cases, Compile@vars, exprD holds its arguments unevaluated. This means that you canexplicitly give a "program" as the expression to compile.This creates a compiled version of a Mathematica program which implements Newtons approximation to square roots.In[18]:=

Out[18]= CompiledFunctionB8x, n<, ModuleB8t<, t = x; DoBt =

12

t+

, 8n<F; tF, -CompiledCode-F

This executes the compiled code.

In[19]:=

newt@2.4, 6D

Out[19]= 1.54919

Manipulating Compiled Code

If you use compiled code created by Compile only within Mathematica itself, then you shouldnever need to know the details of its internal form. Nevertheless, the compiled code can berepresented by an ordinary Mathematica expression, and it is sometimes useful to manipulateit.For example, you can take compiled code generated by Compile, and feed it to external programs or devices. You can also create CompiledFunction objects yourself, then execute themin Mathematica.In all of these cases, you need to know the internal form of CompiledFunction objects. Thefirst element of a CompiledFunction object is always a list of patterns which specifies the typesof arguments accepted by the object. The fifth element of a CompiledFunction object is aMathematica pure function that is used if the compiled code instruction stream fails for anyreason to give a result.

Core Language

323

In all of these cases, you need to know the internal form of CompiledFunction objects. Thefirst element of a CompiledFunction object is always a list of patterns which specifies the typesof arguments accepted by the object. The fifth element of a CompiledFunction object is aMathematica pure function that is used if the compiled code instruction stream fails for anyreason to give a result.

The structure of a compiled code object.

{{1, 5}, {7, 2, 0}, {94, 264, 3, 0, 0, 2, 0, 0, 3, 0, 1}, {2}},

Function[{x}, x^2], Evaluate]

The instruction stream in a CompiledFunction object consists of a list of instructions for a

simple idealized computer. The computer is assumed to have numbered "registers", on whichoperations can be performed. There are five basic types of registers: logical, integer, real,complex and tensor. For each of these basic types it is then possible to have either a singlescalar register or an array of registers of any rank. A list of the total number of registers ofeach type required to evaluate a particular CompiledFunction object is given as the secondelement of the object.The actual instructions in the compiled code object are given as lists. The first element is aninteger "opcode" which specifies what operation should be performed. Subsequent elements areeither the numbers of registers of particular types, or literal constants. Typically the last element of the list is the number of a "destination register", into which the result of the operationshould be put.

324

Core Language

Appendix: Language Structure

Basic ObjectsExpressionsExpressions are the main type of data in Mathematica.Expressions can be written in the form h@e1 , e2 , D. The object h is known generically as thehead of the expression. The ei are termed the elements of the expression. Both the head andthe elements may themselves be expressions.The parts of an expression can be referred to by numerical indices. The head has index 0;element ei has index i. Part@expr, iD or expr@@iDD gives the part of expr with index i. Negativeindices count from the end.Part@expr, i1 , i2 , D, expr@@i1 , i2 , DD, or Extract@expr, 8i1 , i2 , <D gives the piece of exprfound by successively extracting parts of subexpressions with indices i1 , i2 , . If you think ofexpressions as trees, the indices specify which branch to take at each node as you descendfrom the root.The pieces of an expression that are specified by giving a sequence of exactly n indices aredefined to be at level n in the expression. You can use levels to determine the domain of application of functions like Map. Level 0 corresponds to the whole expression.The depth of an expression is defined to be the maximum number of indices needed to specifyany part of the expression, plus one. A negative level number - n refers to all parts of an expression that have depth n.

SymbolsSymbols are the basic named objects in Mathematica.The name of a symbol must be a sequence of letters, letter-like forms and digits, not startingwith a digit. Uppercase and lowercase letters are always distinguished in Mathematica.

Core Language

aaaaa

user-defined symbol

Aaaaa

system-defined symbol

$Aaaa

global or internal system-defined symbol

aaaa$

symbol renamed in a scoping construct

aa$nn

unique local symbol generated in a module

325

Conventions for symbol names.

Essentially all system-defined symbols have names that contain only ordinary English letters,together with numbers and $. The exceptions are p, , , and .System-defined symbols conventionally have names that consist of one or more completeEnglish words. The first letter of each word is capitalized, and the words are run together.Once created, an ordinary symbol in Mathematica continues to exist unless it is explicitlyremoved using Remove. However, symbols created automatically in scoping constructs such asModule carry the attribute Temporary which specifies that they should automatically beremoved as soon as they no longer appear in any expression.When a new symbol is to be created, Mathematica first applies any value that has beenassigned to $NewSymbol to strings giving the name of the symbol, and the context in which thesymbol would be created.If the message General::newsym is switched on, then Mathematica reports new symbols thatare created. This message is switched off by default. Symbols created automatically in scopingconstructs are not reported.

ContextsThe full name of any symbol in Mathematica consists of two parts: a context and a short name.The full name is written in the form context`name. The context context` can contain the samecharacters as the short name. It may also contain any number of context mark characters `,and must end with a context mark.At any point in a Mathematica session, there is a current context $Context and a contextsearch path $ContextPath consisting of a list of contexts. Symbols in the current context, or incontexts on the context search path, can be specified by giving only their short names, provided they are not shadowed by another symbol with the same short name.

326

Core Language

name

search $ContextPath , then $Context ; create in

$Context if necessary

` name

search $Context only; create there if necessary

context ` name

search context only; create there if necessary

` context ` name

search $Context` context only; create there if necessary

Contexts used for various specifications of symbols.

With Mathematica packages, it is conventional to associate contexts whose names correspond

to the names of the packages. Packages typically use BeginPackage and EndPackage to defineobjects in the appropriate context, and to add the context to the global $ContextPath.EndPackage prints a warning about any symbols that were created in a package but which are"shadowed" by existing symbols on the context search path.The context is included in the printed form of a symbol only if it would be needed to specify thesymbol at the time of printing.

Atomic ObjectsAll expressions in Mathematica are ultimately made up from a small number of basic or atomictypes of objects.These objects have heads which are symbols that can be thought of as "tagging" their types.The objects contain "raw data", which can usually be accessed only by functions specific to theparticular type of object. You can extract the head of the object using Head, but you cannotdirectly extract any of its other parts.

Symbol

symbol (extract name using SymbolName )

String

character string "cccc" (extract characters using

Characters )

Integer

integer (extract digits using IntegerDigits )

Real

approximate real number (extract digits using

RealDigits )

Rational

rational number (extract parts using Numerator and

Denominator )

Complex

complex number (extract parts using Re and Im )

Atomic objects.

Atomic objects in Mathematica are considered to have depth 0 and yield True when tested withAtomQ.

Core Language

327

Atomic objects in Mathematica are considered to have depth 0 and yield True when tested withAtomQ.

NumbersInteger

integer nnnn

Real

approximate real number nnn.nnn

Rational

rational number nnn nnn

Complex

complex number nnn + nnn I

Basic types of numbers.

All numbers in Mathematica can contain any number of digits. Mathematica does exact computations when possible with integers and rational numbers, and with complex numbers whose realand imaginary parts are integers or rational numbers.There are two types of approximate real numbers in Mathematica: arbitrary precision andmachine precision. In manipulating arbitrary-precision numbers, Mathematica tries to modifythe precision so as to ensure that all digits actually given are correct.With machine-precision numbers, all computations are done to the same fixed precision, sosome digits given may not be correct.Unless otherwise specified, Mathematica treats as machine-precision numbers all approximatereal numbers that lie between $MinMachineNumber and $MaxMachineNumber and that are inputwith less than $MachinePrecision digits.In InputForm, Mathematica prints machine-precision numbers with $MachinePrecision digits,except when trailing digits are zero.In any implementation of Mathematica, the magnitudes of numbers (except 0) must liebetween $MinNumber and $MaxNumber. Numbers with magnitudes outside this range are represented by Underflow@D and Overflow@D.

Character StringsCharacter strings in Mathematica can contain any sequence of characters. They are input in theform "ccccc".The individual characters can be printable ASCII (with character codes between 32 and 126), orin general any 8- or 16-bit characters. Mathematica uses the Unicode character encoding for 16bit characters.

328

Core Language

The individual characters can be printable ASCII (with character codes between 32 and 126), orin general any 8- or 16-bit characters. Mathematica uses the Unicode character encoding for 16bit characters.In input form, 16-bit characters are represented when possible in the form @nameD, and otherwise as : nnnn.Null bytes can appear at any point within Mathematica strings.

Input SyntaxEntering Characters Enter it directly (e.g. +) Enter it by full name (e.g. @AlphaD) Enter it by alias (e.g. Esc a Esc) (notebook front end only) Enter it by choosing from a palette (notebook front end only) Enter it by character code (e.g. : 03 b1)Typical ways to enter characters.

All printable ASCII characters can be entered directly. Those that are not alphanumeric areassigned explicit names in Mathematica, allowing them to be entered even on keyboards wherethey do not explicitly appear.

Full names for non-alphanumeric printable ASCII characters.

All characters which are entered into the Mathematica kernel are interpreted according to thesetting for the CharacterEncoding option for the stream from which they came.

@NameD

a character with the specified full name

nnn

a character with octal code nnn

.nn

a character with hexadecimal code nn

:nnnn

a character with hexadecimal code nnnn

Ways to enter characters.

Codes for characters can be generated using ToCharacterCode. The Unicode standard is followed, with various extensions.8-bit characters have codes less than 256; 16-bit characters have codes between 256 and65535. Approximately 900 characters are assigned explicit names in Mathematica. Other characters must be entered using their character codes.

single backslash (decimal code 92)

single space (decimal code 32)

"

double-quote (decimal code 34)

backspace or Ctrl+H (decimal code 8)

tab or Ctrl+I (decimal code 9)

newline or Ctrl+J (decimal code 10; full name

@NewLineD)

form feed or Ctrl+L (decimal code 12)

carriage return or Ctrl+M (decimal code 13)

000

null byte (code 0)

Some special 8-bit characters.

330

Core Language

Types of Input Syntax

The standard input syntax used by Mathematica is the one used by default in InputForm andStandardForm.

You

can

modify

the

syntax

by

making

definitions

for

MakeExpression@expr, formD.Options can be set to specify what form of input should be accepted by a particular cell in anotebook or from a particular stream.The input syntax in TraditionalForm, for example, is different from that in InputForm andStandardForm.In general, what input syntax does is to determine how a particular string or collection of boxesshould be interpreted as an expression. When boxes are set up, say with the notebook frontend, there can be hidden InterpretationBox or TagBox objects which modify the interpretation of the boxes.

Character Strings"characters"

a character string

"

a literal " in a character string

a literal in a character string

(at end of line)

ignore the following newline

! H L

a substring representing two-dimensional boxes

Entering character strings.

Character strings can contain any sequence of 8- or 16-bit characters. Characters entered byname or character code are stored the same as if they were entered directly.In a notebook front end, text pasted into a string by default automatically has appropriate characters inserted so that the string stored in Mathematica reproduces the text that waspasted.Within ! H L any box structures represented using backslash sequences can be used.StringExpression objects can be used to represent strings that contain symbolic constructs,such as pattern elements.

Symbol Names and Contexts

Core Language

331

Symbol Names and Contexts

name

symbol name

`name

symbol name in current context

context`name

symbol name in specified context

context`

context name

context1`context2`

compound context name

`context`

context relative to the current context

Symbol names and contexts.

Symbol names and contexts can contain any characters that are treated by Mathematica asletters or letter-like forms. They can contain digits but cannot start with them. Contexts mustend in a backquote `.

Numbersdigits

integer

digits.digits

approximate number

base^^digits

integer in specified base

base^^digits.digits

approximate number in specified base

mantissa*^n

scientific notation (mantissa10n )

base^^mantissa*^n

scientific notation in specified base (mantissabasen )

number`

machine-precision approximate number

number`s

arbitrary-precision number with precision s

number``s

arbitrary-precision number with accuracy s

Input forms for numbers.

Numbers can be entered with the notation base ^ ^ digits in any base from 2 to 36. The base itselfis given in decimal. For bases larger than 10, additional digits are chosen from the letters a|z orA|Z. Upper- and lower-case letters are equivalent for these purposes. Floating-point numberscan be specified by including . in the digits sequence.In scientific notation, mantissa can contain ` marks. The exponent n must always be an integer,specified in decimal.The precision or accuracy s can be any real number; it does not need to be an integer.In the form base ^ ^ number`s the precision s is given in decimal, but it gives the effective numberof digits of precision in the specified base, not in base 10.

332

Core Language

In the form base ^ ^ number`s the precision s is given in decimal, but it gives the effective numberof digits of precision in the specified base, not in base 10.An approximate number x is taken to be machine precision if the number of digits given in it isCeiling@$MachinePrecisionD + 1 or less. If more digits are given, then x is taken to be anarbitrary-precision number. The accuracy of x is taken to be the number of digits that appear tothe right of the decimal point, while its precision is taken to be Log@10, Abs@xDD + Accuracy@xD.A number entered in the form 0`` s is taken to have precision 0 and accuracy s.

Bracketed ObjectsBracketed objects use explicit left and right delimiters to indicate their extent. They can appearanywhere within Mathematica input, and can be nested in any way.The delimiters in bracketed objects are matchfix operators. But since these delimiters explicitlyenclose all operands, no precedence need be assigned to such operators.

H*any text*L

comment

HexprL

parenthesization: grouping of input

Bracketed objects without comma-separated elements.

Comments can be nested, and can continue for any number of lines. They can contain any 8- or16-bit characters.Parentheses must enclose a single complete expression; neither He, eL nor HL are allowed.

8e1 ,e2 ,<

List@e1 ,e2 ,D

Xe1 ,e2 ,\

AngleBracket@e1 ,e2 ,D

dexprt

Floor@exprD

`exprp

Ceiling@exprD

e1 ,e2 ,

BracketingBar@e1 ,e2 ,D

e1 ,e2 ,

DoubleBracketingBar@e1 ,e2 ,D

HinputL

input or grouping of boxes

Bracketed objects that allow comma-separated elements.

Core Language

333

The notation is used to stand for any sequence of expressions.

8e1 , e2 , < can include any number of elements, with successive elements separated by commas.8< is List@D, a list with zero elements.Xe1 , e2 , \ can be entered as @LeftAngleBracketD e1 , e2 , @RightAngleBracketD.The character @InvisibleCommaD can be used interchangeably with ordinary commas; theonly difference is that @InvisibleCommaD will not be displayed.When the delimiters are special characters, it is a convention that they are named @LeftNameD and @RightNameD. H L is used to enter boxes using one-dimensional strings. Note that within the outermost H L in a piece of input the syntax used is slightly different from outside, as describedin "Input of Boxes".

h@e1 ,e2 ,D

standard expression

e@@i1 ,i2 ,DD

Part@e,i1 ,i2 ,D

ePi1 ,i2 ,T

Part@e,i1 ,i2 ,D

Bracketed objects with heads.

Bracketed objects with heads explicitly delimit all their operands except the head. A precedencemust be assigned to define the extent of the head.The precedence of h@eD is high enough that ! h@eD is interpreted as Not@h@eDD. However, h_s@eDis interpreted as Hh_sL@eD.

334

Core Language

Two-Dimensional Input Forms

xyxy

a11a21

a12a22

Power@x, yDDivide@x, yD

Sqrt@xD

Power@x, 1 nD

x yx, y

xmax

min

y x

xmax y wxzmin

xmax

88a11 , a12 , <, 8a21 , a22 , <<

Integrate@y, 8x, xmin , xmax <D

Integrate@y w z, 8x, xmin , xmax <DSum @y, 8x, xmin , xmax <D

x=xminxmax

Product@y, 8x, xmin , xmax <D

x=xmin

D@y, xDD@y, x, D

Two-dimensional input forms with built-in evaluation rules.

Any array of expressions represented by a GridBox is interpreted as a list of lists. Even if theGridBox has only one row, the interpretation is still 88a1 , a2 , <<.x

Two-dimensional input forms without built-in evaluation rules.

There is no issue of precedence for forms such as

spanned by the operator. For forms such as xy and x a left precedence does need to be specified, so such forms are included in the main table of precedences above.

Core Language

335

Input of Boxes Use a palette Use control keysWays to input boxes.

Control KeysCtrl+2 or Ctrl+@

square root

Ctrl+5 or Ctrl+%

switch to alternate position (e.g. subscript to superscript)

Ctrl+6 or Ctrl+^

superscript

Ctrl+7 or Ctrl+&

overscript

Ctrl+9 or Ctrl+(

begin a new cell within an existing cell

Ctrl+0 or Ctrl+)

end a new cell within an existing cell

Ctrl+- or Ctrl+_

subscript

Ctrl+= or Ctrl+Plus

underscript

Ctrl+Enter

create a new row in a table

Ctrl+,

create a new column in a table

Ctrl+.

expand current selection

Ctrl+/

fraction

Ctrl+Space

return from current position or state

Ctrl+, Ctrl+, Ctrl+, Ctrl+

move an object by minimal increments on the screenStandard control keys.

On English-language keyboards both forms will work where alternates are given. On otherkeyboards the first form should work but the second may not.

Boxes Constructed from Text

When textual input that you give is used to construct boxes, as in StandardForm orTraditionalForm cells in a notebook, the input is handled slightly differently from when it isfed directly to the kernel.The input is broken into tokens, and then each token is included in the box structure as aseparate character string. Thus, for example, xx + yyy is broken into the tokens "xx", "+","yyy".

336

Core Language

symbol name (e.g. x123)

A RowBox is constructed to hold each operator and its operands. The nesting of RowBox objectsis determined by the precedence of the operators in standard Mathematica syntax.Note that spacing characters are not automatically discarded. Instead, each sequence of consecutive such characters is made into a separate token.

String-Based InputHL

input raw boxes

!HL

input and interpret boxes

Inputting raw and interpreted boxes.

Any textual input that you give between \H and \L is taken to specify boxes to construct. Theboxes are only interpreted if you specify with \! that this should be done. Otherwise x \^ y isleft for example as SuperscriptBox@x, yD, and is not converted to Power@x, yD.Within the outermost \H L, further \H L specify grouping and lead to the insertion ofRowBox objects.

Core Language

Hbox1 ,box2 ,L

RowBox@box1 ,box2 ,D

box1 ^box2

SuperscriptBox@box1 ,box2 D

box1 _ box2

SubscriptBox@box1 ,box2 D

box1 _ box2 % box3

SubsuperscriptBox@box1 ,box2 ,box3 D

box1 & box2

OverscriptBox@box1 ,box2 D

box1 +box2

UnderscriptBox@box1 ,box2 D

box1 +box2 % box3

UnderoverscriptBox@box1 ,box2 ,box3 D

box1 box2

FractionBox @box1 ,box2 D

\box

SqrtBox@boxD

form` box

FormBox@box, formD

\*input

construct box by interpreting input

insert a space

\n

insert a newline

\t

indent at the beginning of a line

337

String-based ways of constructing raw boxes.

In string-based input between \H and \L spaces, tabs and newlines are discarded. can beused

to

insert

single

space.

Special

spacing

characters

such

as

\[ThinSpace] ,

\[ThickSpace] or \[NegativeThinSpace] are not discarded.

When you input typesetting forms into a string, the internal representation of the string usesthe above forms. The front end displays the typeset form, but uses the \H L notation whensaving the content to a file or when sending the string to the kernel for evaluation.

The Extent of Input Expressions

Mathematica will treat all input that you give on a single line as being part of the same expression.Mathematica allows a single expression to continue for several lines. In general, it treats theinput that you give on successive lines as belonging to the same expression whenever no complete expression would be formed without doing this.Thus, for example, if one line ends with =, then Mathematica will assume that the expressionmust continue on the next line. It will do the same if for example parentheses or other matchfixoperators remain open at the end of the line.If at the end of a particular line the input you have given so far corresponds to a completeexpression, then Mathematica will normally begin immediately to process that expression.

338

Core Language

If at the end of a particular line the input you have given so far corresponds to a completeexpression, then Mathematica will normally begin immediately to process that expression.You can however explicitly tell Mathematica that a particular expression is incomplete byputting a or a (\[Continuation] ) at the end of the line. Mathematica will then include thenext line in the same expression, discarding any spaces or tabs that occur at the beginning ofthat line.

Special Input?symbol

get information

??symbol

get more information

?s1 s2

get information on several objects

!command

execute an external command (text-based interface only)

!! file

display the contents of an external file (text-based interface only)

Special input lines.

In most implementations of Mathematica, you can give a line of special input anywhere in yourinput. The only constraint is that the special input must start at the beginning of a line.Some implementations of Mathematica may not allow you to execute external commands using! command.

Front End Files

Notebook files as well as front end initialization files can contain a subset of standard Mathematica language syntax. This syntax includes: Any Mathematica expression in FullForm. Lists in 8< form. The operators ->, :> and &. Function slots in form. Various Mathematica operators such as +, *, ;, etc. Special characters in @NameD, : nnnn or .xx form. String representation of boxes involving H, L and other backslash operators. Mathematica comments delimited by H* and *L.

Some General Notations and Conventions

Core Language

339

Some General Notations and Conventions

Function NamesThe names of built-in functions follow some general guidelines. The name consists of complete English words, or standard mathematical abbreviations.American spelling is used. The first letter of each word is capitalized. Functions whose names end with Q usually ask a question, and return either True orFalse. Mathematical functions that are named after people usually have names in Mathematica ofthe form PersonSymbol.

Function ArgumentsThe main expression or object on which a built-in function acts is usually given as the firstargument to the function. Subsidiary parameters appear as subsequent arguments.The following are exceptions: In functions like Map and Apply, the function to apply comes before the expression it is tobe applied to. In scoping constructs such as Module and Function, local variables and parameter namescome before bodies. In functions like Write and Export, the name of the file is given before the objects to bewritten to it.For mathematical functions, arguments that are written as subscripts in standard mathematicalnotation are given before those that are written as superscripts.

340

Core Language

OptionsSome built-in functions can take options. Each option has a name, represented as a symbol, orin some cases a string. Options are set by giving rules of the form name -> value or name :> value.Such rules must appear after all the other arguments in a function. Rules for different optionscan be given in any order. If you do not explicitly give a rule for a particular option, a defaultsetting for that option is used.

Options@ f D

give the default rules for all options associated with f

Options@exprD

give the options set in a particular expression

Options@expr,nameD

give the setting for the option name in an expression

AbsoluteOptions@expr,nameD

give the absolute setting for name, even if its actual settingis Automatic

SetOptions@ f ,name->value,D

set default rules for options associated with f

CurrentValue@nameD

give the option setting for the front end option name; canbe used on the left-hand side of an assignment to set theoption

elements m through n (inclusive)

elements m through n in steps of s

Specifications for sequences of parts.

largest element not greater than n.Sequence specifications are used in the functions Drop, Ordering, StringDrop, StringTake,Take and Thread.

Level Specificationsn

levels 1 through n

Infinity

levels 1 through Infinity

8n<

level n only

8n1 ,n2 <

levels n1 through n2

Heads->True

include heads of expressions

Heads->False

do not include heads of expressions

Level specifications.

The level in an expression corresponding to a non-negative integer n is defined to consist of

parts specified by n indices. A negative level number - n represents all parts of an expressionthat have depth n. The depth of an expression, Depth@exprD, is the maximum number of indicesneeded to specify any part, plus one. Levels do not include heads of expressions, except withthe option setting Heads -> True. Level 0 is the whole expression. Level - 1 contains all symbolsand other objects that have no subparts.Ranges of levels specified by 8n1 , n2 < contain all parts that are neither above level n1 , nor belowlevel n2 in the tree. The ni need not have the same sign. Thus, for example, 82, - 2< specifiessubexpressions which occur anywhere below the top level, but above the leaves, of the expression tree.

342

Core Language

Ranges of levels specified by 8n1 , n2 < contain all parts that are neither above level n1 , nor belowlevel n2 in the tree. The ni need not have the same sign. Thus, for example, 82, - 2< specifiessubexpressions which occur anywhere below the top level, but above the leaves, of the expression tree.Level specifications are used by functions such as Apply, Cases, Count, FreeQ, Level, Map,MapIndexed, Position, Replace and Scan. Note, however, that the default level specificationsare not the same for all of these functions.

Iterators8imax <

iterate imax times

8i,imax <

i goes from 1 to imax in steps of 1

8i,imin ,imax <

i goes from imin to imax in steps of 1

8i,imin ,imax ,di<

i goes from imin to imax in steps of di

8i,list<

i takes on the successive values in list

8i,imin ,imax <,8 j, jmin , jmax <,

i goes from imin to imax , and for each value of i, j goes fromjmin to jmax , etc.

Iterator notation.

Iterators are used in such functions as Sum , Table, Do and Range.

The iteration parameters imin , imax and di do not need to be integers. The variable i is given asequence of values starting at imin , and increasing in steps of di, stopping when the next value ofi would be greater than imax . The iteration parameters can be arbitrary symbolic expressions, solong as Himax - imin L di is a number.When several iteration variables are used, the limits for the later ones can depend on the values of earlier ones.The variable i can be any symbolic expression; it need not be a single symbol. The value of i isautomatically set up to be local to the iteration function. This is effectively done by wrapping aBlock construct containing i around the iteration function.The procedure for evaluating iteration functions is described in "Evaluation".

Scoping Constructs

Core Language

343

Scoping ConstructsFunction@8x,<,bodyD

local parameters

lhs->rhs and lhs:>rhs

local pattern names

lhs=rhs and lhs:=rhs

local pattern names

With@8x=x0 ,<,bodyD

local constants

Module@8x,<,bodyD

local variables

Block@8x,<,bodyD

local values of global variables

DynamicModule@8x,<,bodyD

local variables in a Dynamic interface

Scoping constructs in Mathematica. Functions in the first group scope variables lexically.

Scoping constructs allow the names or values of certain symbols to be local.

Some scoping contracts scope lexically, meaning that literal instances of the specified variablesor patterns are replaced with appropriate values. When local variable names are required,symbols with names of the form xxx are generally renamed to xxx$. When nested scoping constructs are evaluated, new symbols are automatically generated in the inner scoping constructsso as to avoid name conflicts with symbols in outer scoping constructs.When a transformation rule or definition is used, ReplaceAll (.) is effectively used to replacethe pattern names that appear on the right-hand side. Nevertheless, new symbols are generated when necessary to represent other objects that appear in scoping constructs on the righthand side.Each time it is evaluated, Module generates symbols with unique names of the form xxx$nnn asreplacements for all local variables that appear in its body.Block localizes the value of global variables. Any evaluations in the body of a block which relyon the global variable will use the locally specified value even if the variable does not explicitlyappear in the body, but is only referenced through subsequent evaluation. The body of theBlock may also make changes to the global variable, but any such changes will only persistuntil the Block has finished executing.DynamicModule localizes its variables to each instance of the DynamicModule output in a notebook. This means each copy of a DynamicModule output created using copy and paste will useits own localized variables.

Ordering of Expressions

344

Core Language

Ordering of ExpressionsThe canonical ordering of expressions used automatically with the attribute Orderless and infunctions such as Sort satisfies the following rules: Integers, rational and approximate real numbers are ordered by their numerical values. Complex numbers are ordered by their real parts, and in the event of a tie, by the absolutevalues of their imaginary parts. Symbols are ordered according to their names, and in the event of a tie, by their contexts. Expressions are usually ordered by comparing their parts in a depth-first manner. Shorterexpressions come first. Powers and products are treated specially, and are ordered to correspond to terms in apolynomial. Strings are ordered as they would be in a dictionary, with the uppercase versions of letterscoming after lowercase ones.Ordinary letters appear first, followed in order by script, Gothic, double-struck, Greek andHebrew. Mathematical operators appear in order of decreasing precedence.

Mathematical FunctionsThe mathematical functions such as Log@xD and BesselJ@n, xD that are built into Mathematicahave a number of features in common. They carry the attribute Listable, so that they are automatically threaded over any liststhat appear as arguments. They carry the attribute NumericFunction, so that they are assumed to give numericalvalues when their arguments are numerical. They give exact results in terms of integers, rational numbers and algebraic expressions inspecial cases.

Core Language

345

Except for functions whose arguments are always integers, mathematical functions inMathematica can be evaluated to any numerical precision, with any complex numbers asarguments. If a function is undefined for a particular set of arguments, it is returned insymbolic form in this case. Numerical evaluation leads to results of a precision no higher than can be justified on thebasis of the precision of the arguments. Thus N@Gamma@27 10D, 100D yields a high-precision result, but N@Gamma@2.7D, 100D cannot. When possible, symbolic derivatives, integrals and series expansions of built-in mathematical functions are evaluated in terms of other built-in functions.

Mathematical ConstantsMathematical constants such as E and Pi that are built into Mathematica have the followingproperties: They do not have values as such. They have numerical values that can be found to any precision. They are treated as numeric quantities in NumericQ and elsewhere. They carry the attribute Constant, and so are treated as constants in derivatives.

ProtectionMathematica allows you to make assignments that override the standard operation and meaning of built-in Mathematica objects.To make it difficult to make such assignments by mistake, most built-in Mathematica objectshave the attribute Protected. If you want to make an assignment for a built-in object, youmust first remove this attribute. You can do this by calling the function Unprotect.There are a few fundamental Mathematica objects to which you absolutely cannot assign yourown values. These objects carry the attribute Locked, as well as Protected. The Lockedattribute prevents you from changing any of the attributes, and thus from removing theProtected attribute.

346

Core Language

Abbreviated String Patterns

Functions such as StringMatchQ, Names and Remove allow you to give abbreviated string patterns, as well as full string patterns specified by StringExpression. Abbreviated string patterns can contain certain metacharacters, which can stand for sequences of ordinary characters.

zero or more characters

one or more characters excluding uppercase letters

\\*, etc.

literal *, etc.

Metacharacters used in abbreviated string patterns.

EvaluationThe Standard Evaluation SequenceThe following is the sequence of steps that Mathematica follows in evaluating an expression likeh@e1 , e2 D. Every time the expression changes, Mathematica effectively starts the evaluationsequence over again. If the expression is a raw object (e.g., Integer, String, etc.), leave it unchanged. Evaluate the head h of the expression. Evaluate each element ei of the expression in turn. If h is a symbol with attributesHoldFirst, HoldRest, HoldAll or HoldAllComplete, then skip evaluation of certain elements. Unless h has attribute HoldAllComplete, strip the outermost of any Unevaluated wrappersthat appear in the ei . Unless h has attribute SequenceHold, flatten out all Sequence objects that appear amongthe ei . If h has attribute Flat, then flatten out all nested expressions with head h. If h has attribute Listable, then thread through any ei that are lists. If h has attribute Orderless, then sort the ei into order. Unless h has attribute HoldAllComplete, use any applicable transformation rules associatedwith f that you have defined for objects of the form h@ f @e1 , D, D. Use any built-in transformation rules associated withh@ f @e1 , D, D.

for objects of the form

Core Language

Use any built-in transformation rules associated with

h@ f @e1 , D, D.

347

for objects of the form

Use any applicable transformation rules that you have defined for h@ f @e1 , e2 , D, D or forh@D@D. Use any built-in transformation rules for h@e1 , e2 , D or for h@D@D.

Nonstandard Argument Evaluation

There are a number of built-in Mathematica functions that evaluate their arguments in specialways. The control structure While is an example. The symbol While has the attribute HoldAll.As a result, the arguments of While are not evaluated as part of the standard evaluation process. Instead, the internal code for While evaluates the arguments in a special way. In the caseof While, the code evaluates the arguments repeatedly, so as to implement a loop.Control structures

arguments evaluated in a sequence determined by control

flow (e.g., CompoundExpression )

Conditionals

arguments evaluated only when they correspond to

branches that are taken (e.g., If , Which )

Logical operations

arguments evaluated only when they are needed in determining the logical result (e.g., And, Or )

Iteration functions

first argument evaluated for each step in the iteration

(e.g., Do , Sum , Plot )

Tracing functions

form never evaluated (e.g., Trace )

Assignments

first argument only partially evaluated (e.g., Set, AddTo )

Pure functions

function body not evaluated (e.g., Function )

Scoping constructs

variable specifications not evaluated (e.g., Module, Block )

Holding functions

argument maintained in unevaluated form (e.g., Hold ,

HoldPattern )

Built-in functions that evaluate their arguments in special ways.

Logical OperationsIn an expression of the form e1 && e2 && e3 the ei are evaluated in order. As soon as any ei isfound to be False, evaluation is stopped, and the result False is returned. This means that youcan use the ei to represent different branches in a program, with a particular branch beingevaluated only if certain conditions are met.The Or function works much like And; it returns True as soon as it finds any argument that isTrue. Xor, on the other hand, always evaluates all its arguments.

348

Core Language

The Or function works much like And; it returns True as soon as it finds any argument that isTrue. Xor, on the other hand, always evaluates all its arguments.

Iteration FunctionsAn iteration function such as Do@ f , 8i, imin , imax <D is evaluated as follows: The limits imin , imax are evaluated. The value of the iteration variable i is made local, effectively using Block. imin and imax are used to determine the sequence of values to be assigned to the iterationvariable i. The iteration variable is successively set to each value, and f is evaluated in each case. The local values assigned to i are cleared.If there are several iteration variables, the same procedure is followed for each variable in turn,for every value of all the preceding variables.Unless otherwise specified, f is not evaluated until a specific value has been assigned to i, andis then evaluated for each value of i chosen. You can use Evaluate@ f D to make f be evaluatedimmediately, rather than only after a specific value has been assigned to i.

AssignmentsThe left-hand sides of assignments are only partially evaluated. If the left-hand side is a symbol, no evaluation is performed. If the left-hand side is a function without hold attributes, the arguments of the function areevaluated, but the function itself is not evaluated.The right-hand side is evaluated for immediate (=), but not for delayed (:=), assignments.Any subexpression of the form HoldPattern @exprD that appears on the left-hand side of anassignment is not evaluated. When the subexpression is used for pattern matching, it matchesas though it were expr without the HoldPattern .

Core Language

349

Overriding Nonstandard Argument Evaluation

f A,Evaluate@exprD,E

evaluates the argument expr, whether or not f has a

HoldFirst, HoldRest , or HoldAll attribute specifyingthat it should be held

Overriding holding of arguments.

By using Evaluate, you can get any argument of a function evaluated immediately, even if theargument would usually be evaluated later under the control of the function. An exception tothis is when the function has the HoldComplete attribute; in this case, the contents of thefunction are not modified by the evaluator.

Preventing EvaluationMathematica provides various functions which act as wrappers to prevent the expressionsthey contain from being evaluated.

Hold@exprD

treated as Hold@exprD in all cases

HoldComplete@exprD

treated as HoldComplete@exprD with upvalues disabled

HoldForm@exprD

treated as expr for printing

HoldPattern @exprD

treated as expr in rules, definitions and patterns

Unevaluated @exprD

treated as expr when arguments are passed to a function

Wrappers that prevent expressions from being evaluated.

Global Control of Evaluation

In the evaluation procedure described so far, two basic kinds of steps are involved: Iteration: evaluate a particular expression until it no longer changes. Recursion: evaluate subsidiary expressions needed to find the value of a particularexpression.Iteration leads to evaluation chains in which successive expressions are obtained by the application of various transformation rules.Trace shows evaluation chains as lists, and shows subsidiary evaluations corresponding torecursion in sublists.

350

Core Language

Trace shows evaluation chains as lists, and shows subsidiary evaluations corresponding torecursion in sublists.The expressions associated with the sequence of subsidiary evaluations which lead to an expression currently being evaluated are given in the list returned by Stack@D.

$RecursionLimit

maximum recursion depth

$IterationLimit

maximum number of iterations

Global variables controlling the evaluation of expressions.

AbortsYou can ask Mathematica to abort at any point in a computation, either by calling the functionAbort@D, or by typing appropriate interrupt keys.When asked to abort, Mathematica will terminate the computation as quickly as possible. If theanswer obtained would be incorrect or incomplete, then Mathematica returns $Aborted insteadof giving that answer.Aborts can be caught using CheckAbort, and can be postponed using AbortProtect.

a pattern repeated according to spec

a pattern which matches at least one of the patterni

a pattern for which cond evaluates to True

a pattern not evaluated

an expression to be matched verbatim

OptionsPattern@D

a sequence of options

Longest@patternD

the longest sequence consistent with pattern

Shortest@patternD

the shortest sequence consistent with pattern

Pattern objects.When several pattern objects with the same name occur in a single pattern, all the objectsmust stand for the same expression. Thus f@x_, x_D can stand for f@2, 2D but not f@2, 3D.In a pattern object such as _h, the head h can be any expression, but cannot itself be a pattern.A pattern object such as x__ stands for a sequence of expressions. So, for example, f@x__D canstand for f@a, b, cD, with x being Sequence@a, b, cD. If you use x, say in the result of a trans-

352

Core Language

A pattern object such as x__ stands for a sequence of expressions. So, for example, f@x__D canstand for f@a, b, cD, with x being Sequence@a, b, cD. If you use x, say in the result of a transformation rule, the sequence will be spliced into the function in which x appears. Thusg@u, x, uD would become g@u, a, b, c, uD.When the pattern objects x_: v and x_. appear as arguments of functions, they representarguments which may be omitted. When the argument corresponding to x_: v is omitted, x istaken to have value v. When the argument corresponding to x_. is omitted, x is taken to have adefault value that is associated with the function in which it appears. You can specify thisdefault value by making assignments for Default@ f D and so on.

Default@ f D

default value for x _. when it appears as any argument of

the function f

Default@ f ,nD

default value for x _. when it appears as the nth argument

(negative n count from the end)

Default@ f ,n,totD

default value for the nth argument when there are a total oftot arguments

Default values.A pattern like f@x__, y__, z__D can match an expression like f@a, b, c, d, eD with severaldifferent choices of x, y and z. The choices with x and y of minimum length are tried first. Ingeneral, when there are multiple __ or ___ in a single function, the case that is tried first takesall the __ and ___ to stand for sequences of minimum length, except the last one, which standsfor "the rest" of the arguments.When x_: v or x_. are present, the case that is tried first is the one in which none of themcorrespond to omitted arguments. Cases in which later arguments are dropped are tried next.The order in which the different cases are tried can be changed using Shortest and Longest.

Orderless

f @x, yD and f @y, xD are equivalent

Flat

f @ f @xD, yD and f @x, yD are equivalent

OneIdentity

f @xD and x are equivalent

Attributes used in matching patterns.

Pattern objects like x_ can represent any sequence of arguments in a function f with attributeFlat. The value of x in this case is f applied to the sequence of arguments. If f has theattribute OneIdentity , then e is used instead of f @eD when x corresponds to a sequence of justone argument.

Core Language

353

Pattern objects like x_ can represent any sequence of arguments in a function f with attributeFlat. The value of x in this case is f applied to the sequence of arguments. If f has theattribute OneIdentity , then e is used instead of f @eD when x corresponds to a sequence of justone argument.

Assignmentslhs=rhs

immediate assignment: rhs is evaluated at the time of

assignment

lhs:=rhs

delayed assignment: rhs is evaluated when the value of lhs

is requested

The two basic types of assignment in Mathematica.

Assignments in Mathematica specify transformation rules for expressions. Every assignment

that you make must be associated with a particular Mathematica symbol.

f @argsD=rhs

assignment is associated with f (downvalue)

t: f @argsD=rhs

assignment is associated with t (upvalue)

f @g@argsDD^=rhs

assignment is associated with g (upvalue)

Assignments associated with different symbols.

In the case of an assignment like f @argsD = rhs, Mathematica looks at f , then the head of f , thenthe head of that, and so on, until it finds a symbol with which to associate the assignment.When you make an assignment like lhs ^= rhs, Mathematica will set up transformation rulesassociated with each distinct symbol that occurs either as an argument of lhs, or as the head ofan argument of lhs.The transformation rules associated with a particular symbol s are always stored in a definiteorder, and are tested in that order when they are used. Each time you make an assignment,the corresponding transformation rule is inserted at the end of the list of transformation rulesassociated with s, except in the following cases:

354

Core Language

The left-hand side of the transformation rule is identical to a transformation rule that hasalready been stored, and any ; conditions on the right-hand side are also identical. In thiscase, the new transformation rule is inserted in place of the old one. Mathematica determines that the new transformation rule is more specific than a rulealready present, and would never be used if it were placed after this rule. In this case, thenew rule is placed before the old one. Note that in many cases it is not possible to determine whether one rule is more specific than another; in such cases, the new rule is alwaysinserted at the end.

Types of ValuesAttributesA f E

attributes of f

DefaultValuesA f E

default values for arguments of f

DownValuesA f E

values for f @D, f @D@D, etc.

FormatValuesA f E

print forms associated with f

MessagesA f E

messages associated with f

NValuesA f E

numerical values associated with f

OptionsA f E

defaults for options associated with f

OwnValuesA f E

values for f itself

UpValuesA f E

values for @, f @D, D

Types of values associated with symbols.

Clearing and Removing Objects

expr=.

clear a value defined for expr

f :expr=.

clear a value associated with f defined for expr

Clear@s1 ,s2 ,D

clear all values for the symbols si , except for attributes,

messages and defaults

ClearAll@s1 ,s2 ,D

clear all values for the si , including attributes, messages

and defaults

Remove@s1 ,s2 ,D

clear all values, and then remove the names of the si

Ways to clear and remove objects.

In Clear, ClearAll and Remove, each argument can be either a symbol or the name of asymbol as a string. String arguments can contain the metacharacters * and @ to specify actionon all symbols whose names match the pattern.

Core Language

355

In Clear, ClearAll and Remove, each argument can be either a symbol or the name of asymbol as a string. String arguments can contain the metacharacters * and @ to specify actionon all symbols whose names match the pattern.Clear, ClearAll and Remove do nothing to symbols with the attribute Protected.

Transformation Ruleslhs->rhs

immediate rule: rhs is evaluated when the rule is first given

lhs:>rhs

delayed rule: rhs is evaluated when the rule is used

The two basic types of transformation rules in Mathematica.

Replacements for pattern variables that appear in transformation rules are effectively doneusing ReplaceAll (the . operator).

Files and Streams

File Namesname.m

Mathematica language source file

name.nb

Mathematica notebook file

name.ma

Mathematica notebook file from before Version 3

name.mx

Mathematica expression dump

name.exe

MathLink executable program

name.tm

MathLink template file

name.ml

MathLink stream file

Conventions for file names.

Most files used by Mathematica are completely system independent. .mx and .exe files arehowever system dependent. For these files, there is a convention that bundles of versions fordifferent computer systems have names with forms such as name $SystemID name.

356

Core Language

In general, when you refer to a file, Mathematica tries to resolve its name as follows: If the name starts with !, Mathematica treats the remainder of the name as an externalcommand, and uses a pipe to this command. If the name contains metacharacters used by your operating system, then Mathematicapasses the name directly to the operating system for interpretation. Unless the file is to be used for input, no further processing on the name is done. Unless the name given is an absolute file name under your operating system, Mathematicawill search each of the directories specified in the list $Path. If what is found is a directory rather than a file, then Mathematica will look for a filename $SystemID name.For names of the form name` the following further translations are done in Get and relatedfunctions: A file name.mx is used if it exists. If name.mx is a directory, then name.mx $SystemID name.mx is used if it exists. A file name.m is used if it exists. If name is a directory, then the file name init.m is used if it exists.In Install, name` is taken to refer to a file or directory named name.exe.

Core Language

StreamsInputStream @"name",nD

input from a file or pipe

OutputStream@"name",nD

output to a file or pipe

Types of streams.

option name

default value

CharacterEncodingBinaryFormat

AutomaticFalse

FormatTypePageWidthTotalWidth

InputForm78Infinity

encoding to use for special characters

whether to treat the file as being in binaryformatdefault format for expressionsnumber of characters per linemaximum number of characters in a singleexpression

Options for output streams.

You can test options for streams using Options, and reset them using SetOptions.