Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

 TraceTree

Source Notebook

Generate a tree of all expressions in an evaluation chain

Contributed by: Ian Ford (Wolfram Research)

ResourceFunction["TraceTree"][expr]

generates a tree of all expressions used in the evaluation of expr.

ResourceFunction["TraceTree"][expr,form]

includes only those expressions that match form.

ResourceFunction["TraceTree"][expr,s]

includes all evaluations that use transformation rules associated with the symbol s.

Details and Options

In general, form in ResourceFunction["TraceTree"][expr,form] is compared both with each complete expression that is evaluated and with the tag associated with an transformation rule used in the evaluation.
ResourceFunction["TraceTree"][expr,lhs→rhs] picks out expressions that match lhs, then replaces them with rhs in the tree returned.
All expressions in the tree returned by ResourceFunction["TraceTree"] are wrapped in HoldForm.
ResourceFunction["TraceTree"] returns a Tree object. Each non-leaf subtree corresponds to a single evaluation chain, which contains the sequence of forms found for a particular expression. Subtrees have branches that give histories of subsidiary evaluations.
A rounded rectangular node is used for the first form in an evaluation chain. An unlabeled circular node is used as a placeholder when the first form is not included.
Rectangular nodes are used for all forms in an evaluation chain after the first form. An unlabeled square node is used as a placeholder when the last form is not included.
Options for ResourceFunction["TraceTree"] include:
MatchLocalNamesTruewhether to allow x to stand for x$nnn
TraceAboveFalsewhether to show evaluation chains that contain the chain containing form
TraceBackwardFalsewhether to show expressions preceding form in the evaluation chain
TraceDepthInfinityhow many levels of nested evaluations to include
TraceForwardFalsewhether to show expressions following form in the evaluation chain
TraceOffNoneforms within which to switch off tracing
TraceOn_forms within which to switch on tracing
TraceOriginalFalsewhether to look at expressions before their heads and arguments are evaluated
During the execution of ResourceFunction["TraceTree"], the settings for the form argument, and for the options TraceOn and TraceOff, can be modified by resetting the values of the global variables $TracePattern, $TraceOn, and $TraceOff, respectively.

Examples

Basic Examples (2) 

Trace each step in an evaluation:

In[1]:=
ResourceFunction["TraceTree"][u = 2; Do[u = u*u, {3}]; u]
Out[1]=

Trace only the computations with head Times:

In[2]:=
ResourceFunction["TraceTree"][u = 2; Do[u = u*u, {3}]; u, Times]
Out[2]=

Scope (10) 

Trace an empty evaluation chain:

In[3]:=
ResourceFunction["TraceTree"][1]
Out[3]=

Trace a single step evaluation:

In[4]:=
ResourceFunction["TraceTree"][1 + 2]
Out[4]=

Trace each branch in an evaluation:

In[5]:=
ResourceFunction["TraceTree"][2*3 + 4*5 + 6*7]
Out[5]=

Trace evaluations given by definitions:

In[6]:=
a = 1; b = 2; f[x_, y_] := x + y;
In[7]:=
ResourceFunction["TraceTree"][f[a, b]]
Out[7]=

Trace each step in an evaluation:

In[8]:=
ResourceFunction["TraceTree"][a = 2; b = 3; a + b]
Out[8]=

Trace the operation of FoldList:

In[9]:=
ResourceFunction["TraceTree"][FoldList[Plus, 0, {3, 2, 1}]]
Out[9]=

Trace the steps in a non-standard evaluation:

In[10]:=
ResourceFunction["TraceTree"][List @@ Join[Hold[1 + 1], Hold[2 + 2]]]
Out[10]=

Trace each step in an evaluation:

In[11]:=
ResourceFunction["TraceTree"][(2 + 3)^(2 + 3) + (4 + 5)^(4 + 5)]
Out[11]=

Include only those expressions that match _Plus:

In[12]:=
ResourceFunction[ "TraceTree"][(2 + 3)^(2 + 3) + (4 + 5)^(4 + 5), _Plus]
Out[12]=

Trace the computations with head Plus:

In[13]:=
ResourceFunction["TraceTree"][(2 + 3)^(2 + 3) + (4 + 5)^(4 + 5), Plus]
Out[13]=

Apply a transformation rule to expressions that match a pattern:

In[14]:=
fib[1] = fib[2] = 1; fib[n_] := fib[n - 1] + fib[n - 2];
In[15]:=
ResourceFunction["TraceTree"][fib[5], fib[n_] :> n]
Out[15]=

Modify the setting for the form argument during the execution of TraceTree[expr,form] by resetting the value of the global variable $TracePattern:

In[16]:=
ResourceFunction[ "TraceTree"][(1 + 1)^(2 + 2); $TracePattern = Power; (1 + 1)^(2 + 2), _]
Out[16]=

Options (23) 

MatchLocalNames (2) 

By default, symbols such as x match symbols with local names of the form x$nnn:

In[17]:=
f[x_] := 1/(1 + x^2)
In[18]:=
ResourceFunction["TraceTree"][f[x] + Module[{x}, f[x]], f[x]]
Out[18]=

With MatchLocalNames→False, only an explicit match of x will show up:

In[19]:=
ResourceFunction["TraceTree"][f[x] + Module[{x}, f[x]], f[x], MatchLocalNames -> False]
Out[19]=

TraceAbove (4) 

A recursive definition for finding Fibonacci numbers:

In[20]:=
fib[1] = fib[2] = 1; fib[n_] := fib[n - 1] + fib[n - 2];

Show only what sums of fib are encountered:

In[21]:=
ResourceFunction["TraceTree"][fib[4], fib[x_] + fib[y_]]
Out[21]=

Show the beginning of the evaluation chain that leads to each sum of fib:

In[22]:=
ResourceFunction["TraceTree"][fib[4], fib[x_] + fib[y_], TraceAbove -> True]
Out[22]=

Show the entire evaluation chain that leads to each sum of fib:

In[23]:=
ResourceFunction["TraceTree"][fib[4], fib[x_] + fib[y_], TraceAbove -> All]
Out[23]=

TraceBackward (4) 

A recursive definition for finding Fibonacci numbers:

In[24]:=
fib[1] = fib[2] = 1; fib[n_] := fib[n - 1] + fib[n - 2];

Show only what additions of positive integers are required:

In[25]:=
ResourceFunction["TraceTree"][fib[4], Plus[__Integer?Positive]]
Out[25]=

Show the beginning of the evaluation chain that leads to each addition:

In[26]:=
ResourceFunction["TraceTree"][fib[3], Plus[__Integer?Positive], TraceBackward -> True]
Out[26]=

Show all intermediate evaluations that led to each addition:

In[27]:=
ResourceFunction["TraceTree"][fib[3], Plus[__Integer?Positive], TraceBackward -> All]
Out[27]=

TraceDepth (3) 

A recursive definition for finding Fibonacci numbers:

In[28]:=
fib[1] = fib[2] = 1; fib[n_] := fib[n - 1] + fib[n - 2];

Trace only evaluations through depth 3:

In[29]:=
ResourceFunction["TraceTree"][fib[4], TraceDepth -> 2]
Out[29]=

Trace all evaluations:

In[30]:=
ResourceFunction["TraceTree"][fib[4]]
Out[30]=

TraceForward (4) 

A recursive definition for finding Fibonacci numbers:

In[31]:=
fib[1] = fib[2] = 1; fib[n_] := fib[n - 1] + fib[n - 2];

Show only what evaluations of fib are encountered:

In[32]:=
ResourceFunction["TraceTree"][fib[4], _fib]
Out[32]=

Show only the evaluations of fib and the results:

In[33]:=
ResourceFunction["TraceTree"][fib[4], _fib, TraceForward -> True]
Out[33]=

Show all intermediate evaluations between calls of fib and the result:

In[34]:=
ResourceFunction["TraceTree"][fib[4], _fib, TraceForward -> All]
Out[34]=

TraceOff (2) 

Trace evaluation of an expression that evaluates a function g:

In[35]:=
g[x_] := x^2 + 1;
In[36]:=
ResourceFunction["TraceTree"][(1 + g[1] + g[2])^3]
Out[36]=

Omit evaluations required to get the values of g:

In[37]:=
ResourceFunction["TraceTree"][(1 + g[1] + g[2])^3, TraceOff -> _g]
Out[37]=

TraceOn (2) 

Trace evaluation of an expression that evaluates a function g:

In[38]:=
g[x_] := x^2 + 1;
In[39]:=
ResourceFunction["TraceTree"][(1 + g[1] + g[2])^3]
Out[39]=

Trace only evaluation inside of g:

In[40]:=
ResourceFunction["TraceTree"][(1 + g[1] + g[2])^3, TraceOn -> _g]
Out[40]=

TraceOriginal (2) 

Trace evaluation of an expression showing evaluation chains for expressions that change:

In[41]:=
ResourceFunction["TraceTree"][f[1, 2 + 3]]
Out[41]=

Show evaluation chains even for expressions that do not change:

In[42]:=
ResourceFunction["TraceTree"][f[1, 2 + 3], TraceOriginal -> True]
Out[42]=

Properties and Relations (2) 

TraceTree[expr] traces each step in the evaluation of expr:

In[43]:=
fib[1] = fib[2] = 1; fib[n_] := fib[n - 1] + fib[n - 2];
In[44]:=
ResourceFunction["TraceTree"][fib[4]]
Out[44]=

TraceTree[expr,form] includes only those expressions that match form:

In[45]:=
ResourceFunction["TraceTree"][fib[4], _fib]
Out[45]=

This corresponds to deleting all expressions that do not match form, then deleting empty evaluation chains:

In[46]:=
Trace[fib[4]]
Out[46]=
In[47]:=
DeleteCases[%, HoldForm[Except[_fib]], Infinity]
Out[47]=
In[48]:=
ReplaceAll[{} -> Nothing] /@ %
Out[48]=
In[49]:=
% === Trace[fib[4], _fib]
Out[49]=

All expressions in the tree returned by TraceTree are wrapped in HoldForm to prevent evaluation:

In[50]:=
ResourceFunction["TraceTree"][2^3 + 4]
Out[50]=

Version History

  • 1.0.0 – 15 July 2022

Related Resources

License Information