What are the most common pitfalls awaiting new users?

Question

As you may already know, Mathematica is a wonderful piece of software.
However, it has a few characteristics that tend to confuse new (and sometimes not-so-new) users. That can be clearly seen from the the fact that the same questions keep being posted at this site over and over.

Please help me to identify and explain those pitfalls.

Suggestions for posting answers:

• One topic per answer
• Focus on non-advanced uses (it's intended to be useful for beginners and as a question closing reference)
• Include a self explanatory title in h2 style
• Explain the symptoms, the mechanism behind the scenes and all possible causes and solutions you can think of. Be sure to include a beginner's level explanation (and a more advance one too, if you're in the mood)
• Include a link to your answer by editing the Index below (for quick reference)

Index

• Attempting to make an assignment to the argument of a function
• Avoiding loops
• Basic syntax issues
• Learn how to use the Documentation Center effectively
• Lingering Definitions: when calculations go bad
• Understanding what Set (=) really does
• Understand that semicolon (;) is not a delimiter
• Understand the difference between exact and approximate (Real) numbers
• Understand the difference between Set (or =) and SetDelayed (or :=)
• Using the result of functions that return replacement rules

Answer 1

Avoiding procedural loops

People coming from other languages often translate directly from what they are used to into Mathematica. And that usually means lots of nested For loops and things like that. So "say no to loops" and get programming the Mathematica way!

1. Use Attributes to check if functions are Listable. You can avoid a lot of loops and code complexity by dealing with lists directly, e.g. by adding the lists together directly to get element-by-element addition.
2. Get to know functions like NestList, FoldList, NestWhileList, Inner and Outer. You can use many of these to produce the same results as those complicated nested loops you used to write.
3. Get to know Map (/@), Apply (@@ and @@@), Thread, MapThread and MapIndexed. You'll be able to operate on complex data structures without loops using these.
4. Avoid unpacking/extracting parts of your data (via Part or Extract) and try to handle it as a whole, passing your huge matrix directly to Map or whatever iterative function you use.

keywords: loop for-loop do-loop while-loop nestlist foldlist procedural

Answer 2

Basic syntax issues

1. Avoid single-capital-letter names for your variables, to avoid clashes (consider using the double-struck EscdsAEsc and gothic letters EscgoAEsc instead). Mathematica is case-sensitive. More generally, avoid capitalising your own functions if you can.
2. Mathematica uses square brackets [] for function arguments, unlike most other languages that use round parentheses. See halirutan's exemplary answer for more detail.
3. Learn the difference between Set (=) and SetDelayed (:=). See this question and this tutorial in the Mathematica documentation.
4. Avoid using subscripted symbols in your code. While it can be done, it causes a lot of confusion and is harder to use than just sym[j] or whatever your symbol might be. The reason is that subscripted symbols are not plain symbols, so you can’t assign values (strictly speaking, DownValues) to them directly.
5. When creating matrices and arrays, don't use formatting commands like //TableForm and //MatrixForm in the initial assignment statements. This just won't work if you then want to manipulate your matrix like a normal list. Instead, try defining the matrix, suppressing the output of the definition by putting a semicolon at the end of the line. Then have a command that just reads nameOfMatrix//MatrixForm -- you can even put it on the same line after the semicolon. The reason for this is that if you define the object with a //MatrixForm at the end, it has the form MatrixForm[List[...]], instead of just List[..], and so it can't be manipulated like a list. If you really want to display the output as MatrixForm on the same line you can do (nameOfMatrix=Table[i+j,{i,5},{j,5}])//MatrixForm

Answer 3

Understand that semicolon (;) is not a delimiter

Although it may look to newcomers that semicolons are used in Mathematica as statement terminators as in C or Java, or perhaps as statement separators as in Pascal and its derivatives, in fact, semicolons are the infix form of the function CompoundExpression, just as plus-signs (+) are the infix form of the function Plus.

You can verify this by evaluating

Hold[a; b; c] // FullForm

Hold[CompoundExpression[a, b, c]]

CompoundExpression is necessary to Mathematica because many of the core programming functions such as SetDelayed (:=), Module, Block, and With take only a single expression as their second argument. This second argument is of course the code body and normally requires the evaluation of many expressions. CompoundExpression provides the construct that bundles an indefinite number of expressions into one.

Wolfram Research chose semicolon for the binary operator form of CompoundExpression to make Mathematica code look more like C code, but this only syntactic sugar.

The only true delimiter in Mathematica is comma (,).

Update

One often sees code like the following

data = RandomReal[{0., 10.}, {1000, 2}];

The variable data is probably going to be used as test or example data. The semicolon is added to suppress the output from this Set expression because the output is both very large and no one really cares about its details. Because there is no visible output, it would be easy to assume the expression returns nothing, but that is not true. Mathematica expressions always return something, even if it is only the token Null, which does not print in OutputForm. In the case of CompoundExpression, there is an additional twist -- I quote from the Mathematica documentation:

expr1; expr2; returns value Null. If it is given as input, the resulting output will not be printed. Out[n] will nevertheless be assigned to be the value of expr2.

This the only case I know of where evaluating an expression at toplevel doesn't assign its actual output to Out[n].

keywords delimiter terminator separator semicolon compound-expression

Answer 4

Understand what Set (=) really does

Because Mathematica allows and encourages the use of = as a binary operator for Set, those coming to Mathematica from other languages are likely to retain their well entrenched notion that Set is the equivalent of whatever kind of assignment operator they have previously encountered. It is hard but essential to them to learn that Set actually associates a rewrite rule (an ownvalue) with a symbol. This is a form of symbol binding unlike that in any other programming language in popular use, and eventually leads to shock, dismay, and confusion, when the new user evaluates something like x = x[1]

Mathematica's built-in documentation doesn't do a good job of helping the new user to learn how different its symbol binding really is. The information is all there, but organized almost as if to hide rather than reveal the existence and significance of ownvalues.

What does it mean to say that "Set actually associates a rewrite rule (an ownvalue) with a symbol"? Let's look at what happens when an "assignment" is made to the symbol a; i.e., when Set[a, 40 + 2] is evaluated.

a = 40 + 2

42

The above is just Set[a, 40 + 2] as it is normally written. On the surface all we can see is that the sub-expression 40 + 2 was evaluated to 42 and returned, the binding of a to 42 is a side-effect. In a procedural language, a would now be associated with a chunk of memory containing the value 42. In Mathematica the side effect is to create a new rule called an ownvalue and to associate a with that rule. Mathematica will apply the rule whenever it encounters the symbol a as an atom. Mathematica, being a pretty open system, will let us examine the rule.

OwnValues[a]

{HoldPattern[a] :> 42}

To emphasize how really different this is from procedural assignment, consider

a = a[1]; a

42[1]

Surprised? What happened is the ownvalue we created above caused a to rewritten as 42 on the righthand side of the expression. Then Mathematica made a new ownvalue rule which it used to rewrite the a occurring after the semicolon as 42[1]. Again, we can confirm this:

OwnValues[a]

{HoldPattern[a] :> 42[1]}

An excellent and more detailed explanation of where Mathematica keeps symbol bindings and how it deals with them can be found in the answers to this question. To find out more about this issue within Mathematica's documentation go here.

keywords set assign ownvalue variable-binding

Answer 5

Using the result of functions that return replacement rules

Most new Mathematica users will at some point encounter the seemingly odd formatting of the output given by functions such as Solve or Root.

Let's start with the follwing simple example:

Solve[x^2 == 4, x]

{{x -> -2}, {x -> 2}}

You might find this output strange for two reasons. We'll have a look at both.

What do the arrows mean?

The output that Solve returns, is what is called a replacement rule in Mathematica. A replacement Rule is of the form lhs -> rhs and does not do much on its own. It is used together with other functions that apply the rule to some expression. The arguably most common of these functions is ReplaceAll, which can be written in the short form /.. As the documentation states

expr/.rules

applies a rule or list of rules in an attempt to transform each subpart of an expression expr.

In practice, this looks like the following:

x + 3 /. x -> 2

5

Notice how /. and -> are combined to replace the x in the expression x+3 by 2. And this is also how you can use the Solve output. The simplest form would be:

x /. Solve[x^2 == 4, x]

{-2,2}

Since you will often face more complicated problems and Solve and its ilk might take quite some time to evaluate, it makes sense in theses cases to only calculate the solutions once and save them for later use. Just like many other expressions, replacement rules can be assigned to symbols using Set:

sol = Solve[x^2 == 4, x];
x /. sol

{-2, 2}

Why the nested structure?

At first glance, the nested structure of the output looks strange and you might ask: why is the output of the form {{x -> -2}, {x -> 2}} when it could just could be {x -> -2, x -> 2}?

To understand this, take a look at the following:

x /. {x -> -2, x -> 2}

-2

Replacement rules can be given in lists to make things like x + y /. {x -> 1, y -> 2} work. When only a single list of rules is given (as in the example above), only one replacement is made for each variable. As the result shows, Mathematica replaces x with the first matching rule it finds. In order to have Mathematica make two (or more) replacements and output a list, the rules have to be given as lists of lists.

The nested structure also makes more sense as soon as you start using Solve and other functions with more than one variable.

Solve[{x + y == 6, x^2 == y}, {x, y}]

{{x -> -3, y -> 9}, {x -> 2, y -> 4}}

You can still apply this list of rules to expressions with either x or y or both. If you only want a certain solution you can acces the element you want either before or after replacement, using functions like First, Last or Part (which is usually written in its postfix form [[...]]):

sol2d = Solve[{x + y == 6, x^2 == y}, {x, y}];
First[x - y /. sol2d]
x - y /. First[sol2d]
Last[x - y /. sol2d]
x - y /. sol2d[[2]]

-12

-12

-2

-2

Answer 6

Learn how to use the Documentation Center effectively

Mathematica comes with the most comprehensive documentation I have ever seen in a software product. This documentation contains

• reference pages for every Mathematica function
• tutorials for various topics, which show you step by step how to achieve something
• guide pages to give you an overview of functions about a specific topic
• a categorised function navigator, to help you find appropriate guide pages and reference pages.
• finally, the complete interactive Mathematica book

You can always open the Documentation Center by pressing F1. When the cursor (the I-beam) is anywhere near a function, then the help page of this function is opened. E.g. when your cursor is anywhere at the position where the dots are in .I.n.t.e.g.r.a.t.e., you will be directed to the help page of Integrate.

Reference pages:

A reference page is a help page which is dedicated to exactly one Mathematica function (or symbol). In the image below you see the reference page of the Sin function. Usually, some of the sections are open, but here I closed them so you see all parts at once.

• In yellow, you see the usage. It gives you instantly information about how many arguments the function expects. Often there is more then one usage. Additionally, a short description is given.
• The Details section gives you further information about Options, behavioural details and things which are important to note. In general, this section is only important in a more advanced state.
• The Examples section is the most important, because there you have a lot of examples, showing everything starting from simple use cases to very advanced things. Study this section carefully!
• See Also gives you a list of functions which are related. Very helpful, when a function does not exactly what you want, because most probably you find help in the referenced pages.
• Tutorials shows you tutorials which are related to the function. In the case of Sin it is e.g. the Elementary Transcendental Functions tutorial.
• Related Guides gives you a list of related guide pages.
• Related Links references to material in the web: Demonstrations, MathWorld pages, etc.

In general my recommendation for viewing a help page is the following:

1. Study the usage carefully
2. Look up basic examples. If you don't find what you need, look up all examples
3. Read the Details

And of course if you like the how-to style, you should read the referenced tutorials.

Guide pages:

Guide pages collect all functions which belong to a certain topic and they are an excellent resource when you try to find a function you are not knowing yet.

The guide page itself is often divided into several subsections collecting similar functions. In the image above for instance the Trigonometric Functions. Furthermore, you can find links to tutorials, etc. when you open the Learning Resources tab. At the end of each guide page you find references to related guide pages.

Function navigator and virtual book:

The rest can be explored by just trying and does not need extensive explanation. To reach the function navigator or the book, you can use the buttons on the top of the Documentation Center.

The rest is mostly self-explanatory. The virtual book is a very nice resource when you like to read something from the beginning to the end. In this way you can be sure that you at least scraped every functionality of Mathematica, which you probably miss when you hop between the help pages. But be warned, it is a lot of material!

Final notes:

• Since the complete documentation consists of usual Mathematica notebooks, all calculations and examples can be tested inside the help pages. Of course, you cannot destroy the documentation, because everything is reset when you close a help page.

• You can always search the documentation by typing into the search bar on top of the Documentation Center:

  

• When coming from a different programming language, and you are not sure that a certain Mathematica function is equivalent to what you are used to, be sure to check the Properties & Relations section in the reference page to get ideas on what other functions could be relevant for your case.

Answer 7

Understand the difference between exact and approximate (Real) numbers

Unlike many other computational software, Mathematica allows you to deal with exact integers and rational numbers (heads Integer and Rational), as well as normal floating-point (Real) numbers. While you can use both exact and floating-point numbers in a calculation, using exact quantities where they aren’t required can slow computations down.

Also, mixing the data types up in a single list will mess up packed arrays.

The different data types are represented differently by Mathematica. This means, for example, that integer zero (0) and real zero (0.) only equal numerically (0 == 0. yields True) but not structurally (0 === 0. yields False). In certain cases you have to test for both or you will run into trouble. And you have to make sure that List index numbers (i.e. the arguments to Part) are exact integers not real numbers.

As with any computer language, calculations with real numbers is not exact and will accumulate error. As a consequence, your real-valued calculation might not necessarily return zero even when you think it should. There may be small (less than $10^{-10}$) remainders, which might even be complex valued. If so, you can use Chop to get rid of these. Furthermore, you can carry over the small numerical error, unnoticed:

Floor[(45.3 - 45)*100] - 30   (* ==> -1 instead of 0 *)

In such cases, use exact rational numbers instead of reals:

Floor[(453/10 - 45)*100] - 30  (* ==> 0 *)

Sometimes, if you are doing a calculation containing some zeros and some approximate real numbers, as well as algebraic expressions, you will end up with approximate zeros multiplied by the algebraic elements in the result. But of course you want them to cancel out, right? Again, use Chop, that removes small real numbers close to zero (smaller than $10^{-10}$ according to the default tolerance level).

keywords: real integer number-type machine-precision

Answer 8

Understand the difference between Set (or =) and SetDelayed (or :=)

A common misconception is that = is always used to define variables (such as x = 1) and := is used to define functions (such as f[x_] := x^2). However, there really is no explicit distinction in Mathematica as to what constitutes a "variable" and what constitutes a "function" — they're both symbols, which have different rules associated with them.

Without going into heavy details, be aware of the following important differences (follow the links for more details):

• = is an immediate assignment, whereas := is a delayed assignment. In other words, f = x will assign the value of x to f at definition time, whereas f := x will return the value of x at evaluation time, that is every time f is encountered, x will be recalculated. See also: 1, 2, 3
• If you're plotting a function, whose definition depends on the output of another possibly expensive computation (such as Integrate, DSolve, Sum, etc. and their numerical equivalents) use = or use an Evaluate with :=. Failure to do so will redo the computation for every plot point! This is the #1 reason for "slow plotting". See also: 1, 2

At a slightly more advanced level, you should be aware that:

• = holds only its first argument, whereas := holds all its arguments. This does not mean however that Set or SetDelayed don't evaluate their first argument. In fact, they do, in a special way. See also: 1
• =, in combination with :=, can be used for memoization, which can greatly speed up certain kinds of computations. See also: 1

Here is one discussion which illustrates why normally one should use SetDelayed to define functions. Even for interactive work, making systematic use of this practice pays huge dividends.

keywords: set setdelayed assignment definition function variable

Answer 9

Lingering Definitions: when calculations go bad

One aspect of Mathematica that sometimes confuses new users, and has confused me often enough, is the Lingering Definition Problem. Here's a quick experiment you can do, to see the problem clearly.

1: Launch (or re-launch) Mathematica, create a new notebook, and evaluate the following expression:

x = 2 + 2

2: Now close the notebook document without saving (and without quitting Mathematica), and create another fresh notebook. Evaluate this:

x

The result can be surprising to beginners - after all, you think you've just removed all visible traces of x, closing the only notebook with any record of it, and yet, it still exists, and still has the value 4.

To explain this, you need to know that when you launch the Mathematica application, you're launching two linked but separate components: the visible front-end, which handles the notebooks and user interaction, and the invisible kernel, which is the mathematical engine that underpins the Mathematica system. The notebook interface is like the flight deck or operating console, and the kernel is like the engine, hidden away but ready to provide the necessary power.

So, what happened when you typed the expression x = 2 + 2, is that the front-end sent it to the kernel for evaluation, and received the result back from the kernel for display. The resulting symbol, and its value, is now part of the kernel. You can close documents and open new ones, but the kernel's knowledge of the symbol x is unaffected, until something happens to change that.

And it's these lingering definitions that can confuse you - symbols that are not visible in your current notebook are still present and defined in the kernel, and might affect your current evaluations.

This also affects subscripted expressions - consider the following evaluation, where the initially innocent symbol i is assigned an explicit value:

If you want to use subscripted symbols in a more robust fashion, you should use e.g. the Notation package.

There are a couple of things you can learn to do to avoid problems caused by Lingering Definitions. Before you provide definitions for specific symbols, clear any existing values that you've defined so far in the session, with the Clear function.

Clear[x]

Or you can clear all symbols in the global context, using ClearAll.

ClearAll["Global`*"]

When all else fails, quit the kernel (choose Evaluation>Quit Kernel from the menu or type Quit[], thereby forgetting all the symbols (and everything else) that you've defined in the kernel.

Mathematica allows you to keep your notebooks separate, so that they don't share the same symbols. See this Q and A for more.

Answer 10

Attempting to make an assignment to the argument of a function

Quite frequently new users attempt something like this:

foo[bar_, new_] := AppendTo[bar, new]

x = {1};

foo[x, 2]

To be met with:

AppendTo::rvalue: {1} is not a variable with a value, so its value cannot be changed. >>

Or:

f[x_, y_] := (x = x + y; x)

a = 1;
b = 2;

f[a, b]

Set::setraw: Cannot assign to raw object 1. >>

This is because the value of the symbol x, a, etc. is inserted into the right-hand-side definition.

One needs either a Hold attribute for in-place modification:

SetAttributes[foo, HoldFirst]

foo[bar_, new_] := AppendTo[bar, new]

x = {1};

foo[x, 2];

x

{1, 2}

Passing held arguments to a function with Attributes is similar to passing arguments by reference in other languages (ByRef keyword in VBA, or passing a pointer or a reference in C++ for example).

Or a temporary symbol, typically created with Module, for intermediate calculations:

f[x_, y_] := Module[{t}, t = x + y; t]

a = 1;
b = 2;

f[a, b]

3

(This definition is of course highly contrived for such a simple operation.)

Other Hold attributes include: HoldAll, HoldRest, and HoldAllComplete.

For some more details, see also this discussion.

Answer 11

Assuming commands will have side effects which they don't:

Consider:

In[97]:= list = {1, 2, 3}
Out[97]= {1, 2, 3}

In[98]:= Append[list, 4]
Out[98]= {1, 2, 3, 4}

In[99]:= list
Out[99]= {1, 2, 3}

When I was first learning Mathematica, I assumed that Append[list, 4] would take the list list and append the element 4 to it, overwriting the previous list. But this is not right: Append[] returns the result of appending 4 to list without overwriting the input list.

In general, a command which alters its inputs, or other global variables, is said to have a side effect. Mathematica in general avoids side effects whenever it would be reasonable to do so, encouraging (but not forcing) a functional programming style.

I think it is a safe statement that the Mathematica documentation will always say explicitly when a command has a side effect. For example, the documentation (version 7) for Delete[] reads

Delete[expr,n] deletes the element at position $n$ in $expr$.

If I encountered this sentence in the documentation of a language I had never seen before, I would assume that Delete[] altered the expression expr. However, with experience reading Mathematica documentation, I am confident that if this side effect existed, it would be stated explicitly and, indeed, Delete[] has no side effects.

I remember finding many of the list commands confusing because their names are verbs which, in English, would seem to suggest that the list was being restructured. In particular, note that Append[], Prepend[], Take[], Drop[], Insert[], Delete[], Replace[], ReplacePart[], DeleteDuplicates[], Flatten[], Join[], Transpose[], Reverse[] and Sort[] are all side effect free.

For completeness, I should mention that for some functions there are side-effect-having alternatives, usually with an added prefix at the end of the function name, like AppendTo (for Append), AddTo (for Add), SubtractFrom (for Subtract), TimesBy (for Times), etc. These functions not just perform the calculation but also save the new result into the variable they were called with. Because of this, they must be called with a symbol insted of a number or an explicit list.

Answer 12

Use Consistent Naming Conventions

This is basic, and good practice in any programming language, but Mathematica's slow-to-fail nature makes it in a sense a less forgiving language than others, so those of us who have in the past gotten away with bad habits may run into trouble. Suppose I have a function

loseMemoriesLikeTearsInRain[]

which I later try to invoke thusly:

loseMemoryLikeTearsInRain[]

In some other languages this would result in a compile error, and is easily spotted, but in Mathematica, what usually happens is either

1. the unevaluated expression loseMemoryLikeTearsInRain[] gets passed on to some other function,
2. Mathematica silently moves on without performing the side effects the function is supposed to perform, or
3. both.

For this reason, I have found it especially important to have a consistent set of conventions for naming things. The exact choice is to some extent a matter of taste, but here are some things that have tripped me up:

1. inconsistent capitalization,
2. starting function names with a capital letter (can conflict with predefined Mathematica functions),
3. inconsistent use of singular and plural (I now try to favor the singular whenever possible),
4. names that do not distinguish between pure functions and those with side effects (I now use noun-clauses and verb-clauses respectively),
5. generally inconsistent, idiosyncratic, or poorly thought out use of terminology,
6. attempts to abbreviate beyond what is reasonable or memorable. (One consistent convention is to drop all vowels other than the first letter of the word, whch mks evrythng lk lk ths.)

Answer 13

Undo is not available in general

As the title already claims, there is no overall option to undo certain steps in Mathematica files. Nevertheless, inside the boxes one can undo as long as one stays inside.

Personal recommendations: 1. Never delete some code except if what you were doing was completely wrong. 2. If you want to create a notebook for presentation, take an additional file as sandbox aside where you test all the things that should later appear in the notebook.