Functions

scan

efemarai.scan(iteration=None, wait=True, show=True, enabled=True)

Context manager for visualizing computational graphs. To visualize the computational graph constructed by the execution of a code fragment, simply put the fragment in a with scan(): block.

Parameters

  • iteration (int, optional) – iteration index that is displayed in the Execution Menu.
  • wait (str, optional) – whether the program execution should be paused once the computational graph is visualized waiting for the user to resume it via the Execution Menu.
  • show (bool, optional) – if set to false the computational graph will be scanned, and visualized only if an assertion error occurs.
  • enabled (bool, optional) – whether the computational graph is to be scanned. Setting it to false is equivalent to removing the entire with statement. Useful, for example, if you want to scan and visualize the graph every N iterations.

Examples:

with ef.scan():
    output = model(data)
    loss = F.cross_entropy(output, target)
    loss.backward()

inspect

efemarai.inspect(tensor, name=None, view=None, colormap=None, wait=False)

Visualize a tensor such that it can be inspected.

Parameters

  • tensor (numpy.ndarray, torch.Tensor, torch.nn.Parameter) – the tensor to be visualized for inspection.
  • name (str, optional) – name of the visualized tensor.
  • view (efemarai.View, optional) – an extra tensor view (other than the default one) to be used for visualizing the tensor.
  • colormap (efemarai.Colormap, optional) – the colormap to be used for the default tensor view.
  • wait (bool, optional) – whether the program execution should be paused once the tensor is visualized waiting for the user to resume it.

Examples:

ef.inspect(torch.rand(10, 10, 10), name="Random tensor")

add_view

efemarai.add_view(tensor, view)

Add a tensor view to a tensor.

Parameters

  • tensor (numpy.ndarray, torch.Tensor, torch.nn.Parameter) – the tensor that is to be visualized with another view.
  • view (efemarai.View) – the new tensor view to be used for visualizing the tensor.

Examples:

 ef.add_view(data, ef.View.Image)

set_name

efemarai.set_name(tensor, name)

When possible the name of a tensor is inferred and set to the name of the Python variable. In cases when the name cannot be automatically determined, or you want to overwrite the default name, then you can use this function.

Parameters

  • tensor (numpy.ndarray, torch.Tensor, torch.nn.Parameter) – the tensor whose name is to be set.
  • name (str) – the new tensor name.

Examples:

 ef.set_name(x, "Input Data")

set_colormap

efemarai.set_colormap(tensor, colormap)

Set the colormap that is to be used for the default view of a tensor.

Parameters

  • tensor (numpy.ndarray, torch.Tensor, torch.nn.Parameter) – the tensor whose colormap is to be set.
  • colormap (efemarai.Colormap) – the colormap that’s to be used.

Examples:

 ef.set_colormap(x, ef.Colormap.Parula)

set_parameters_colormap

efemarai.set_parameters_colormap(colormap)

Set the default colormap that is to be used for parameter tensors. This setting will be overridden by set_colormap when called for a parameter.

Parameters

  • colormap (efemarai.Colormap) – the colormap that’s to be used.

Examples:

 ef.set_parameters_colormap(x, ef.Colormap.Parula)

full_check

efemarai.full_check(
    numeric_stability=True, 
    healthy_activations=True, 
    discrete_loss=True,
):

Register all applicable assertions from the assertions library that ships with Efemarai. Once registered, an assertion is checked automatically when performing scans.

Parameters

  • numeric_stability (bool, optional) – if set to True the following assertions will be automatically registered: [NoExplodingTensors, NoVanishingTensors].
  • healthy_activations (bool, optional) – if set to True the following assertions will be automatically registered: [NoDeadReLULayers, NoSaturatedSigmoidUnits, NoSaturatedTanhUnits].
  • discrete_loss (bool, optional) – if set to True the following assertions will be automatically registered: [ValidInputsDiscreteNLLLoss, ValidInputsDiscretePoissonNLLLoss, ValidInputsDiscreteKLDivLoss].

Examples:

 ef.full_check(discrete_loss=False)

default_check

efemarai.default_check(non_zero_grads=True):

Register the default assertions [NoNansAssertion, NoInfsAssertion] detecting whenever NaN or Inf values occur in the computational graph. These assertions add little computational overhead, while allowing you to immediately detect a large range of problems. You only need to call this function if you want to reset the list of registered assertions after you have made any changes to the list.

Parameters

  • non_zero_grads (bool, optional) – if set to True the NoNonZeroGrads assertion will also be registered. That assertion is violated whenever the backward pass is initiated and there are non-zero gradients present.

no_check

efemarai.no_check():

Do not check any assertions when performing graph scans. This is equivalent to ef.deregister_assertions().

register_assertion

efemarai.register_assertion(assertion)

Register a new assertion which will be automatically checked.

Parameters

  • assertion (efemarai.assertion.EfemaraiAssertion) – the assertion to be registered.

Examples:

 ef.register_assertion(ef.assertions.NoInfsAssertion())

deregister_assertion

efemarai.deregister_assertion(assertion)

Deregister an assertion to no longer check it.

Parameters

  • assertion (efemarai.assertion.EfemaraiAssertion, Type[efemarai.assertion.EfemaraiAssertion]) – the assertion instance or class to be deregistered.

Examples:

 ef.deregister_assertion(ef.assertions.NoInfsAssertion)

deregister_assertions

efemarai.deregister_assertions(tensor_assertions=True, function_assertions=True)

Deregister all assertions.

Parameters

  • tensor_assertions (bool, optional) – if True then all tensor assertions will be deregistered.
  • function_assertions (bool, optional) – if True then all function assertions will be deregistered.

get_registered_assertion

efemarai.get_registered_assertion(assertion) -> EfemaraiAssertion 

Get the registered assertion instance/s of a certain assertion type. This is useful if you need to change the parameters of any already registered assertion.

Parameters

  • assertion (Type[efemarai.assertion.EfemaraiAssertion]) – the type of assertion instance that is to be retrieved.

Examples:

 noinfs = ef.get_registered_assertion(ef.assertions.NoInfsAssertion)

get_registered_assertions

efemarai.get_registered_assertions() -> List

Get a list of all registered assertions.

Returns

A list containing the instances of all assertions that are checked.

init

efemarai.init(port=11811)

Initialize Efemarai and connect to the daemon. You do not need to call this method unless you need to specify another port that the daemon is running at. If you do set another port remember to adjust the corresponding settings when launching Efemarai in the browser.

Parameters

  • port (int, optional) – the port at which to connect to the Efemarai daemon.

notebook

efemarai.notebook()

Initialize Efemarai to work within a notebook. You need to call this function at the beginning of your notebook, before any other calls to Efemarai.

Classes

View

CLASS efemarai.View(Enum)

Enumerates all available tensor views.

Members

  • Raw – the default tensor view.
  • Image – view tensor as image/s. The number of channels must be divisible by 3.

Colormap

CLASS efemarai.Colormap(Enum)

Enumerates all available colormaps. Explore the colormap drop down from the graph menu in order to see what each colormap looks like.

Members

  • Autumn
  • Bone
  • Cool
  • Copper
  • Hot
  • Hsv
  • Jet
  • Parula
  • Pink
  • Spring
  • Summer
  • Winter
  • Apricot
  • ApricotReversed
  • Fern
  • FernReversed
  • Heather
  • HeatherReversed
  • Iris
  • IrisReversed
  • Lavender
  • LavenderReversed
  • Macaroon
  • MacaroonReversed
  • Pistachio
  • PistachioReversed
  • Sky
  • SkyReversed
  • Violet
  • VioletReversed

ExecutionStage

CLASS efemarai.assertion.ExecutionStage(Enum)

Enumerates all possible stages a tensor assertion can be checked at.

Members

  • AfterForward – check assertion after the forward pass.
  • BeforeBackward – check assertion before the backward pass.
  • AfterBackward – check assertion after the backward pass.
  • AfterComplete – check assertion after both the forward and backward passes are complete.

EfemaraiAssertion

CLASS efemarai.assertion.EfemaraiAssertion

Abstract class that all assertion classes inherit from. You must not inherit directly from it.

def __init__(self, message, hint=None, color=None, icon=None)

Initialize the assertion.

Parameters

  • message (str) – the message to be displayed in the Execution Menu if the assertion fails.
  • hint (str, optional) – hint how to fixing the error that is displayed in the Execution Menu.
  • color (str, optional) – the color used to highlight tensors violating the assertion. The default color is "#d7212e" which is red.
  • icon (str, optional) – the icon associated to the assertion. You can choose any icon from the Material Design Icons Cheatsheet. The default icon is "mdi-alert-box".

TensorAssertion

CLASS efemarai.assertion.TensorAssertion(EfemaraiAssertion)

Base class that you should inherit from if you want to implement a tensor assertion. Tensor assertions allow you to run various checks on any tensor that is accessed or computed throughout the construction of the computational graph.

def __init__(self, message, hint=None, color=None, icon=None, check_on=None)

Initialize the tensor assertion.

Parameters

  • message (str) – the message to be displayed in the Execution Menu if the assertion fails.
  • hint (str, optional) – hint how to fixing the error that is displayed in the Execution Menu.
  • color (str, optional) – the color used to highlight tensors violating the assertion. The default color is "#d7212e" which is red.
  • icon (str, optional) – the icon associated to the assertion. You can choose any icon from the Material Design Icons Cheatsheet. The default icon is "mdi-alert-box".
  • check_on (efemarai.assertion.ExecutionStage, Tuple[efemarai.assertion.ExecutionStage], optional) – specifies at what stage/s of the graph scan to check the tensor assertion. The default is (ExecutionStage.AfterForward, ExecutionStage.AfterBackward).

def check(self, tensor) -> bool 

Abstract method that any class inheriting from TensorAssertion must implement. It is automatically called by Efemarai during a graph scan according to the check_on field for every accessed or created tensor.

Parameters

  • tensor (torch.Tensor, torch.nn.Parameter) – the tensor that is to be checked. If the assertion is staged for ExecutionStage.AfterForward the parameter holds tensors accessed or computed during the forward pass. If the assertion is staged for ExecutionStage.BeforeBackward or ExecutionStage.AfterBackward the parameter holds gradient tensors.

Returns

Boolean indicating whether the tensor passes the assertion or not.

ParameterAssertion

CLASS efemarai.assertion.ParameterAssertion(TensorAssertion)

Base class that you should inherit from if you want to implement a parameter assertion. Parameter assertions allow you to express assertions that depend both on the value and the gradient of a parameter.

def __init__(self, message, hint=None, color=None, icon=None)

Initialize the parameter assertion. See EfemaraiAssertion.

def check(self, parameter, gradient) -> bool 

Abstract method that any class inheriting from ParameterAssertion must implement. It is automatically called by Efemarai after a graph scan is complete for every parameter in the computational graph.

Parameters

  • parameter (torch.nn.Parameter) – the parameter that is to be checked.
  • gradient (torch.Tensor) – the calculated gradient for that parameter.

Returns

Boolean indicating whether the parameter passes the assertion or not.

TensorNodeAssertion

CLASS efemarai.assertion.TensorNodeAssertion(TensorAssertion)

Base class that you should inherit from if you want to implement a tensor node assertion. Tensor node assertions allow you to express assertions that depend both on the value and the gradient of any tensor node in the computational graph.

def __init__(self, message, hint=None, color=None, icon=None)

Initialize the tensor node assertion. See EfemaraiAssertion.

def check(self, id, tensor, gradient) -> bool 

Abstract method that any class inheriting from TensorNodeAssertion must implement. It is automatically called by Efemarai after a graph scan is complete for every tensor node in the computational graph.

Parameters

  • id (str) – a unique ID of the tensor node that is preserved throughout consecutive scans of the same computational graph. The ID is especially useful if, for example, you need to track tensor nodes over the course of training.
  • tensor (torch.Tensor, torch.nn.Parameter) – the value of the tensor node that is to be checked.
  • gradient (torch.Tensor, None) – the calculated gradient for that tensor node.

Returns

Boolean indicating whether the tensor node passes the assertion or not.

FunctionAssertion

CLASS efemarai.assertion.FunctionAssertion(EfemaraiAssertion)

Base class that you should inherit from if you want to implement a function assertion. Function assertions allow you to run various checks on any function that is called throughout the process of building the computational graph. Function assertions are checked after the scan of the computational graph is complete (not on the fly as functions are being called).

def __init__(self, targets, message, hint=None, color=None, icon=None)

Initialize the function assertion.

Parameters

  • targets (FunctionType, torch.nn.Module, Type[torch.nn.Module], Tuple) – the target function/s that the assertion will be tested on. Any torch.nn.Module is also treated as a function so you can provide one, or a tuple, of: function, torch.nn.Module instance or torch.nn.Module subclass. If you provide a subclass then the assertion will be ran for any instance of that class.
  • message (str) – the message to be displayed in the Execution Menu if the assertion fails.
  • hint (str, optional) – hint how to fixing the error that is displayed in the Execution Menu.
  • color (str, optional) – the color used to highlight tensors violating the assertion. The default color is "#d7212e" which is red.
  • icon (str, optional) – the icon associated to the assertion. You can choose any icon from the Material Design Icons Cheatsheet. The default icon is "mdi-alert-box".

def check(self, output, *args, **kwargs) -> bool 

Abstract method that any class inheriting from FunctionAssertion must implement. It is automatically called by Efemarai after a graph scan is complete for every function in the computational graph.

Parameters

  • output (Any) – the return value of the target function.
  • *args (Tuple) – the input arguments passed to the function.
  • **kwargs (Dict) – the key word input arguments passed to the function. Efemarai also provides one extra key word argument – a dictionary mapping any input or output tensor to its gradient – that you can access with kwargs["grads"].

Returns

Boolean indicating whether the function passes the assertion or not.