This is documentation for Mathematica 8, which was
based on an earlier version of the Wolfram Language.
View current documentation (Version 11.2)

Tracing Evaluation

The 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 final result of evaluation, but also at intermediate steps in the evaluation process.
Trace[expr]generate a list of all expressions used in the evaluation of expr
Trace[expr,form]include only expressions which match the pattern form

Tracing the evaluation of expressions.

The expression is evaluated immediately to .
Click for copyable input
The is evaluated before the addition is done.
Click for copyable input
The evaluation of each subexpression is shown in a separate sublist.
Click for copyable input
Trace[expr] 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 expressions generated in this way is typically very large, and the list returned by Trace is difficult to understand.
Trace allows you to "filter" the expressions that Trace records, keeping only those which match the pattern form.
Here is a recursive definition of a factorial function.
Click for copyable input
This gives all the intermediate expressions generated in the evaluation of . The result is quite complicated.
Click for copyable input
This shows only intermediate expressions of the form .
Click for copyable input
You can specify any pattern in Trace.
Click for copyable input
Trace 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 , you can do so simply by telling Trace to pick out expressions of the form . You can also use patterns like to pick out calls with particular argument structure.
A typical Mathematica program, however, consists not only of "function calls" like , but also of other elements, such as assignments to variables, control structures, and so on. All of these elements are represented as expressions. As a result, you can use patterns in Trace to pick out any kind of Mathematica program element. Thus, for example, you can use a pattern like to pick out all assignments to the symbol .
This shows the sequence of assignments made for .
Click for copyable input
Trace can pick out expressions that occur at any time in the evaluation of expr. The expressions need not, for example, appear directly in the form of expr that you give. They may instead occur, say, during the evaluation of functions that are called as part of the evaluation of expr.
Here is a function definition.
Click for copyable input
You can look for expressions generated during the evaluation of .
Click for copyable input
Trace allows you to monitor intermediate steps in the evaluation not only of functions that you define, 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 functions depends in detail on their implementation and optimization in a particular version of Mathematica.
Trace[expr,f[___]]show all calls to the function f
Trace[expr,i=_]show assignments to i
Trace[expr,_=_]show all assignments
Trace[expr,Message[___]]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 the "structure" of the computation.
The basic idea is that each sublist in the list returned by Trace represents the "evaluation chain" 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 requires the 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.
Click for copyable input
This yields an evaluation chain reflecting the sequence of transformations for a[i] used.
Click for copyable input
The successive forms generated in the simplification of show up as successive elements in its evaluation chain.
Click for copyable input
Each argument of the function has a separate evaluation chain, given in a sublist.
Click for copyable input
The evaluation chain for each subexpression is given in a separate sublist.
Click for copyable input
Tracing the evaluation of a nested expression yields a nested list.
Click for copyable input
There are two basic ways that subsidiary evaluations can be required during the evaluation of a Mathematica expression. The first way is that the expression may contain subexpressions, each of which has to be evaluated. The second way is that there may be rules for the evaluation of the expression that involve other expressions which themselves must be evaluated. Both kinds of subsidiary evaluations are represented by sublists in the structure returned by Trace.
The subsidiary evaluations here come from evaluation of the arguments of and .
Click for copyable input
Here is a function with a condition attached.
Click for copyable input
The evaluation of involves a subsidiary evaluation associated with the condition.
Click for copyable input
You often get nested lists when you trace the evaluation of functions that are defined "recursively" in terms of other instances of themselves. The reason is typically that each new instance of the function appears as a subexpression in the expressions obtained by evaluating previous instances of the function.
Thus, for example, with the definition , the evaluation of yields the expression , which contains as a subexpression.
The successive instances of generated appear in successively nested sublists.
Click for copyable input
With this definition, is obtained directly as the value of fp[n].
Click for copyable input
fp[n] never appears in a subexpression, so no sublists are generated.
Click for copyable input
Here is the recursive definition of the Fibonacci numbers.
Click for copyable input
Here are the end conditions for the recursion.
Click for copyable input
This shows all the steps in the recursive evaluation of .
Click for copyable input
Each step in the evaluation of any Mathematica expression can be thought of as the result of applying a particular transformation rule. As discussed in "Associating Definitions with Different Symbols", all the rules that Mathematica knows are associated with specific symbols or "tags". You can use Trace to see all the steps in the evaluation of expr that are performed using transformation rules associated with the symbol f. In this case, Trace gives not only the expressions to which each rule is applied, but also the results of applying the rules.
In general, Trace picks out all the steps in the evaluation of expr where form matches either the expression about to be evaluated, or the tag associated with the rule used.
Trace[expr,f]show all evaluations which use transformation rules associated with the symbol f
Trace[expr,f|g]show all evaluations associated with either f or g

Tracing evaluations associated with particular tags.

This shows only intermediate expressions that match .
Click for copyable input
This shows all evaluations that use transformation rules associated with the symbol .
Click for copyable input
Here is a rule for the function.
Click for copyable input
This traces the evaluation of , showing all transformations associated with .
Click for copyable input
Trace[expr,form,TraceOn->oform]switch on tracing only within forms matching oform
Trace[expr,form,TraceOff->oform]switch off tracing within any form matching oform

Switching off tracing inside certain forms.

Trace allows you to trace expressions matching form generated at any point in the evaluation of expr. Sometimes, you may want to trace only expressions generated during certain parts of the evaluation of expr.
By setting the option TraceOn->oform, you can specify that tracing should be done only during the evaluation of forms which match oform. Similarly, by setting TraceOff->oform, you can specify that tracing should be switched off during the evaluation of forms which match oform.
This shows all steps in the evaluation.
Click for copyable input
This shows only those steps that occur during the evaluation of .
Click for copyable input
This shows only those steps that do not occur during the evaluation of .
Click for copyable input
Trace[expr,lhs->rhs]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 used in the evaluation of .
Click for copyable input
A powerful aspect of the Mathematica Trace function is that the object it returns is basically a standard 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 the list it produces with HoldForm to prevent them from being evaluated. The HoldForm is not displayed in standard Mathematica output format, but it is still present in the internal structure of the expression.
This shows the expressions generated at intermediate stages in the evaluation process.
Click for copyable input
The expressions are wrapped with HoldForm to prevent them from evaluating.
Click for copyable input
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.
Click for copyable input
Looking at the input form resolves any ambiguities.
Click for copyable input
When you use a transformation rule in Trace, the result is evaluated before being wrapped with HoldForm.
Click for copyable input
For sophisticated computations, the list structures returned by Trace can be quite complicated. When you use Trace, 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 the lists remains the same.
This shows all occurrences of in the evaluation of .
Click for copyable input
This shows only occurrences of , but the nesting of the lists is the same as for .
Click for copyable input
You can set the option TraceDepth->n to tell Trace to include only lists nested at most n levels deep. In this way, you can often pick out the "big steps" in a computation, without seeing the details. Note that by setting TraceDepth or TraceOff you can avoid looking at many of the steps in a computation, and thereby significantly speed up the operation of Trace for that computation.
This shows only steps that appear in lists nested at most two levels deep.
Click for copyable input
Trace[expr,form,TraceDepth->n]trace the evaluation of expr, ignoring steps that lead to lists nested more than n levels deep

Restricting the depth of tracing.

When you use Trace, 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 the option TraceForward->True in Trace.
This shows not only expressions which match , but also the results of evaluating those expressions.
Click for copyable input
Expressions picked out using Trace typically lie in the middle of an evaluation chain. By setting TraceForward->True, you tell Trace to include also the expression obtained at the end of the evaluation chain. If you set TraceForward->All, Trace will include all the expressions that occur after the expression matching form on the evaluation chain.
With TraceForward->All, all elements on the evaluation chain after the one that matches are included.
Click for copyable input
By setting the option TraceForward, you can effectively see what happens to a particular form of 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 this by setting the option TraceBackward. What TraceBackward does is to show you what preceded a particular form of expression on an evaluation chain.
This shows that the number came from the evaluation of during the evaluation of .
Click for copyable input
Here is the whole evaluation chain associated with the generation of the number .
Click for copyable input
TraceForward and TraceBackward allow you to look forward and backward in a particular evaluation chain. Sometimes, you may also want to look at the evaluation chains within which the particular evaluation chain occurs. You can do this using TraceAbove. If you set the option TraceAbove->True, then Trace will include the initial and final expressions in all the relevant evaluation chains. With TraceAbove->All, Trace includes all the expressions in all these evaluation chains.
This includes the initial and final expressions in all evaluation chains which contain the chain that contains .
Click for copyable input
This shows all the ways that is generated during the evaluation of .
Click for copyable input
Trace[expr,form,opts]trace the evaluation of expr using the specified options
TraceForward->Trueinclude the final expression in the evaluation chain containing form
TraceForward->Allinclude all expressions following form in the evaluation chain
TraceBackward->Trueinclude the first expression in the evaluation chain containing form
TraceBackward->Allinclude all expressions preceding form in the evaluation chain
TraceAbove->Trueinclude the first and last expressions in all evaluation chains which contain the chain containing form
TraceAbove->Allinclude 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 works is to intercept each expression encountered during the evaluation of expr, and then to use various criteria to determine whether this expression should be recorded. Normally, however, Trace intercepts expressions only after function arguments have been evaluated. By setting TraceOriginal->True, you can get Trace also to look at expressions before function arguments have been evaluated.
This includes expressions which match both before and after argument evaluation.
Click for copyable input
The list structure produced by Trace normally includes only expressions that constitute steps in non-trivial evaluation chains. Thus, for example, individual symbols that evaluate to themselves are not normally included. Nevertheless, if you set TraceOriginal->True, then Trace looks at absolutely every expression involved in the evaluation process, including those that have trivial evaluation chains.
In this case, Trace includes absolutely all expressions, even those with trivial evaluation chains.
Click for copyable input
option name
default value
TraceForwardFalsewhether to show expressions following form in the evaluation chain
TraceBackwardFalsewhether to show expressions preceding form in the evaluation chain
TraceAboveFalsewhether to show evaluation chains leading to the evaluation chain containing form
TraceOriginalFalsewhether to look at expressions before their heads 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 local variables in the program should be treated. As discussed in "How Modules Work", Mathematica scoping constructs such as Module create symbols with new names to represent local variables. Thus, even if you called a variable in the original code for your program, the variable may effectively be renamed when the program is executed.
Trace is set up so that by default a symbol x that appears in form will match all symbols with names of the form that arise in the execution of expr. As a result, you can for example use Trace to trace assignment to all variables, local and global, that were named x in your original program.
include all steps in the execution of expr that match form, with no replacements for local variable names allowed

Preventing the matching of local variables.

In some cases, you may want to trace only the global variable x, and not any local variables that 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 .
Click for copyable input
This traces assignments only to the specific global variable x.
Click for copyable input
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 however sometimes useful to see traces of the computation as it proceeds. The function TracePrint works essentially like Trace, except that it prints expressions when it encounters them, rather than saving up all of the expressions to create a list structure.
This prints expressions encountered in the evaluation of .
Click for copyable input
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 TracePrint corresponds to nesting in the list structure from Trace. You can use the Trace options TraceOn, TraceOff and TraceForward in TracePrint. However, since TracePrint produces output as it goes, it cannot support the option TraceBackward. In addition, TracePrint is set up so that TraceOriginal is effectively always set to True.
Trace[expr,...]trace the evaluation of expr, returning a list structure containing the expressions encountered
TracePrint[expr,...]trace the evaluation of expr, printing the expressions encountered
TraceDialog[expr,...]trace the evaluation of expr, initiating a dialog when each specified expression is encountered
TraceScan[f,expr,...]trace the evaluation of expr, applying f to HoldForm of each expression encountered

Functions for tracing evaluation.

This enters a dialog when is encountered during the evaluation of .
Click for copyable input
Inside the dialog you can for example find out where you are by looking at the "stack".
Click for copyable input
This returns from the dialog, and gives the final result from the evaluation of .
Click for copyable input
The function TraceDialog effectively allows you to stop in the middle of a computation, and interact with the Mathematica environment that exists at that time. You can for example find values of intermediate variables in the computation, and even reset those values. There are however 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. The Dialog function is discussed in detail in "Dialogs". When you call Dialog, you are effectively starting 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 tracing an evaluation. TraceScan applies f to each expression that arises. The expression is wrapped with HoldForm to prevent it from evaluating.
In TraceScan, the function f is applied to expressions before they are evaluated. TraceScan applies f before evaluation, and fp after evaluation.