Quantcast

Documentation Center

  • Trial Software
  • Product Updates

prog::trace

Observe functions

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

prog::trace(obj, <Recursive = FALSE>)
prog::trace({obj1, obj2, …}, <Recursive = FALSE>)
prog::trace(options)

Description

prog::trace(obj) manipulates the MuPAD® object obj to observe entering and exiting this object.

    Note:   prog::trace has a new syntax and a new set of options. The old syntax has been removed.

prog::trace lets you observe functions, domains, domain methods, and function environments. Use the prog::trace function for debugging. See Example 1.

prog::trace lets you specify a set of functions, domains, methods, or function environments that you want to observe. See Example 2.

prog::trace lets you observe the relations between calls to the traced objects.

To trace the object obj, use the function call prog::trace(obj). After that call, every time the function call enters or exits the object obj, MuPAD prints a message and returns the arguments and the return value of that call. See Example 3.

prog::trace lets you observe a domain or a function environment. When you call the prog::trace function for a domain, the function observes all methods of the domain. When you call prog::trace for a function environment, it observes all slots of the function environment. To trace only particular methods (slots), provide a set of these methods (slots). See the slot help page for more details. See Example 8.

To prevent tracing of all slots of a function environment, set the value of the Recursive option to FALSE. See Example 7.

The function prog::untrace(obj) terminates tracing of an object obj. Here obj is a function, a set of functions, a domain, a domain method, or a function environment. The function prog::traced detects whether the system currently traces a particular object.

Examples

Example 1

Define a function f, and observe this function:

f := x -> if x > 0 then x else -f(-x) end:
prog::trace(f):
f(-2)
enter f(-2)
  enter f(2)
  computed 2
computed -2

Change the function, and reassign the new function to f. Although you use the same function name (f), MuPAD does not trace the new function:

f := x -> if x > 0 then x else f(-x) end:
f(-2)

To trace the new function, call prog::trace again. Now, the trace mechanism observes the updated function:

prog::trace(f):
f(-2)
enter f(-2)
  enter f(2)
  computed 2
computed 2

For further computations, stop observation of the function:

prog::untrace(f)

Example 2

If you want to trace more than one function, use a set to specify these functions in one function call:

prog::trace({sin, cos, exp}):
sin(5*PI/2);
cos(5*PI);
exp(5)
enter sin((5*PI)/2)
  enter sin(PI/2)
  remembered 1
computed 1


enter cos(5*PI)
  enter cos(PI)
  remembered -1
computed -1


enter exp(5)
computed exp(5)

To stop observation of all functions, use prog::untrace without arguments:

prog::untrace()

Example 3

Define a short function that calls itself recursively, and observe the calls:

fib:= proc(n)
      begin
        if n < 2 then
          n
        else
          fib(n - 1) + fib(n - 2)
        end_if
      end_proc:
prog::trace(fib):
fib(3)
enter fib(3)
  enter fib(2)
    enter fib(1)
    computed 1
    enter fib(0)
    computed 0
  computed 1
  enter fib(1)
  computed 1
computed 2

To limit the number of the nested function calls displayed by prog::trace, use the Depth option. To specify the value of Depth, use a separate prog::trace function call:

prog::trace(fib):
prog::trace(Depth = 2);
fib(12)
enter fib(12)
  enter fib(11)
  computed 89
  enter fib(10)
  computed 55
computed 144

The Depth option is independent of the fib procedure. Now, if you use prog::trace to trace any other procedure, prog::trace displays the nested calls to that procedure using Depth = 2. Remove this global option for further computations:

prog::untrace(fib):
prog::trace(Depth = 0)

Example 4

To display memory usage, use the Mem option:

prog::trace(Mem):
prog::trace(sin):
sin(3/2*PI)
enter
remember::sin((3*PI)/2) [mem: 3267052]   enter remember::sin(PI/2)
[mem: 4033596]   remembered 1 [mem: 4033436] computed -1 [mem: 4033072]
   -1 

The Mem option is independent of the traced procedure. Now, if you use prog::trace to trace any other procedure, prog::trace displays memory usage in every step of that procedure. Remove this global option for further computations::

prog::untrace(sin):
prog::trace(Mem = FALSE)

Example 5

The NoArgs option suppresses the output of arguments of traced objects:

prog::trace(linalg):
prog::trace(NoArgs);
linalg::eigenvalues(matrix([[1,  0, 0],
                            [0, -1, 2],
                            [0,  1, 1]]))
enter linalg::eigenvalues
  enter linalg::checkForFloats
  return
  enter linalg::charpoly
    enter linalg::charpolyBerkowitz
    return
  return
return

The NoArgs option is independent of the traced procedure. Now, if you use prog::trace to trace any other procedure, prog::trace hides arguments in every step of that procedure. Remove this global option for further computations:

prog::untrace(linalg):
prog::trace(NoArgs = FALSE)

Example 6

If you use the Parent option, prog::trace shows the name of the procedure that calls the traced object:

prog::trace(cos):
prog::trace(Parent):
f := x -> cos(2*x):
g := (x, y) -> f(x) + f(y):
g(3/2*PI, -3/2*PI)
enter cos(3*PI) (called from f)
  enter cos(PI) (called from cos)
  remembered -1
computed -1
enter cos(-3*PI) (called from f)
  enter cos(3*PI) (called from cos)
  remembered -1
computed -1

prog::trace(f):
prog::trace(g):
g(-PI, PI)
enter g(-PI, PI)
  enter f(-PI) (called from g)
    enter cos(-2*PI) (called from f)
      enter cos(2*PI) (called from cos)
        enter cos(0) (called from cos)
        remembered 1
      computed 1
    computed 1
  computed 1
  enter f(PI) (called from g)
    enter cos(2*PI) (called from f)
    remembered 1
  computed 1
computed 2

The Parent option is independent of the traced procedures. Now, if you use prog::trace to trace any other object, prog::trace shows relations between calls to the traced objects. Remove this global option for further computations:

prog::untrace(cos):
prog::trace(Parent = FALSE)

Example 7

By default, the prog::trace function traces all slots of a function environment. For example, trace the besselJ function and observe the following function call:

prog::trace(besselJ);
besselJ(1, 2.3)
enter besselJ(1, 2.3)
  enter besselJ::float(1, 2.3)
  computed 0.5398725326
computed 0.5398725326

To omit tracing of all slots, set the value of the Recursive option to FALSE:

prog::untrace(besselJ);
prog::trace(besselJ, Recursive=FALSE);
besselJ(1, 4.5)
enter besselJ(1, 4.5)
computed -0.2310604319

For further computations, stop observation of the besselJ function:

prog::untrace(besselJ)

Example 8

You can trace domains and domain methods. For example, create the following small domain:

T := newDomain("T"):
T::new := proc(h, m = 0) name T; begin new(T, h*60 + m) end:
T::intern := x -> [op(x) div 60, op(x) mod 60]:
T::print := x -> expr2text(T::intern(x)[1]).":".
                 substring(expr2text(100 + T::intern(x)[2]), 2, 2):
T::_plus := () -> new(T, _plus(map(args(), op))):
T::expr := op:
T::_mult := () -> new(T, _mult(map(args(), expr))):
prog::trace(T):
T(1, 30) + T(0, 45)*T(1, 05)
enter T(1, 30)
computed 1:30
enter T(0, 45)
computed 0:45
enter T(1, 5)
computed 1:05
enter T::_mult(0:45, 1:05)
computed 48:45
enter T::_plus(1:30, 48:45)
computed 50:15

MuPAD does not trace the process of displaying traced outputs. Therefore, the T::intern and T::print methods do not appear in the traced outputs.

Now, trace the arithmetic methods only. When specifying the methods to trace, use their slot names, such as slot(T, "_plus") or T::_plus:

prog::untrace():
prog::trace({T::_plus, T::_mult}):
T(1, 30) + T(0, 45)*T(1, 05)
enter T::_mult(0:45, 1:05)
computed 48:45
enter T::_plus(1:30, 48:45)
computed 50:15

prog::untrace():

Parameters

obj

A MuPAD function, a domain, a method, or a function environment to observe. Specify methods by their slot names (strings).

{obj1, obj2, …}

A set of MuPAD functions, domains, methods, or function environments to observe.

Options

Depth

Option, specified as Depth = level

Display nested function calls only up to the recursion depth level. Here level is a positive integer. After you set this option, all new and regenerated outputs for traced objects show the nested function calls only up to the specified recursion depth. See Example 3.

Mem

Show the current memory usage. After you set this option, all new and regenerated outputs for traced objects show the information about the current memory usage. See Example 4.

NoArgs

Do not show the arguments of calls to traced objects and the returned values. Without this option, all outputs for traced objects show the arguments and returned values for each call of a traced object. See Example 5.

Parent

Show the name of the procedure that calls the traced object. After you set this option, all new and regenerated outputs for traced objects show the names of the procedures that call the traced objects. See Example 6.

Recursive

Option, specified as Recursive = FALSE

Do not trace all slots of a function environment or domain. By default, Recursive = TRUE. See Example 7.

Return Values

prog::trace returns the void object null().

See Also

MuPAD Functions

Was this topic helpful?