scico.trace

Call tracing of scico functions and methods.

JIT must be disabled for tracing to function correctly (set environment variable JAX_DISABLE_JIT=1, or call jax.config.update('jax_disable_jit', True) before importing jax or scico). Call trace_scico_calls to initialize tracing, and call register_variable to associate a name with a variable so that it can be referenced by name in the call trace.

The call trace is color-code as follows if colorama is installed:

• module and class names: light red

• function and method names: dark red

• arguments and return values: light blue

• names of registered variables: light yellow

When a method defined in a class is called for an object of a derived class type, the class of that object is displayed in light magenta, in square brackets. Function names and return values are distinguished by initial >> and << characters respectively.

A usage example is provided in the script trace_example.py.

Functions

apply_decorator(module, decorator[, ...])	Apply a decorator function to all functions in a scico module.
call_trace(func)	Print log of calls to func.
register_variable(var, name)	Register a variable name for call tracing.
trace_scico_calls([verbose])	Enable tracing of calls to all significant scico functions/methods.

scico.trace.register_variable(var, name)

Register a variable name for call tracing.

Any hashable object (or numpy array, with the memory address used as a hash) may be registered. JAX arrays may not be registered since they are not hashable and there is no clear mechanism for associating them with a unique memory address.

Parameters:

• var (Any) – The variable to be registered.

• name (str) – The name to be associated with the variable.

scico.trace.call_trace(func)

Print log of calls to func.

Decorator for printing a log of calls to the wrapped function. A record of call levels is maintained so that call nesting is indicated by call log indentation.

Return type:

Callable

scico.trace.apply_decorator(module, decorator, recursive=True, skip=None, seen=None, verbose=False, level=0)

Apply a decorator function to all functions in a scico module.

Apply a decorator function to all functions in a scico module, including methods of classes in that module.

Parameters:

• module (ModuleType) – The module containing the functions/methods to be decorated.

• decorator (Callable) – The decorator function to apply to each module function/method.

• recursive (bool) – Flag indicating whether to recurse into submodules of the specified module. (Hidden modules with a name starting with an underscore are ignored.)

• skip (Optional[Sequence]) – A list of class/function/method names to be skipped.

• seen (Optional[defaultdict[str, int]]) – A defaultdict providing a count of the number of times each function/method was seen.

• verbose (bool) – Flag indicating whether to print a log of functions as they are encountered.

• level (int) – Counter for recursive call levels.

Return type:

defaultdict[str, int]

Returns:

A defaultdict providing a count of the number of times each function/method was seen.

scico.trace.trace_scico_calls(verbose=False)

Enable tracing of calls to all significant scico functions/methods.

Enable tracing of calls to all significant scico functions and methods. Note that JIT should be disabled to ensure correct functioning of the tracing mechanism.