opto.trace¶

GRAPH `module-attribute` ¶

GRAPH = Graph()

ExecutionError ¶

ExecutionError(exception_node: ExceptionNode)

Bases: Exception

Base class for execution error in code tracing.

exception_node `instance-attribute` ¶

exception_node = exception_node

Module ¶

Bases: ParameterContainer

Module is a ParameterContainer which has a forward method.

forward ¶

forward(*args, **kwargs)

save ¶

save(file_name: str)

Save the parameters of the model to a pickle file.

load ¶

load(file_name)

Load the parameters of the model from a pickle file.

NodeContainer ¶

An identifier for a container of nodes.

Node ¶

Node(
    value: Any,
    *,
    name: str = None,
    trainable: bool = False,
    description: str = None,
    info: Union[None, Dict] = None
)

Bases: AbstractNode[T]

A data node in a directed graph, this is a basic data structure of Trace.

Args: value (Any): The value to be assigned to the node. name (str, optional): The name of the node. trainable (bool, optional): Whether the node is trainable or not. Defaults to False. description (str, optional): String describing the node which acts as a soft constraint. Defaults to None. info (Union[None, Dict], optional): Dictionary containing additional information about the node. Defaults to None.

Attributes: trainable (bool): Whether the node is trainable or not. _feedback (dict): Dictionary of feedback from children nodes. _description (str): String describing the node. Defaults to "[Node]". _backwarded (bool): Whether the backward method has been called. _info (dict): Dictionary containing additional information about the node. _dependencies (dict): Dictionary of dependencies on parameters and expandable nodes.

Notes: The Node class extends AbstractNode to represent a data node in a directed graph. It includes attributes and methods to handle feedback, description, and dependencies. The node can be marked as trainable and store feedback from children nodes. The feedback mechanism is analogous to gradients in machine learning and propagates information back through the graph. The feedback mechanism supports non-commutative aggregation, so feedback should be handled carefully to maintain correct operation order. The node can track dependencies on parameters and expandable nodes (nodes that depend on parameters not visible in the current graph level).

trainable `instance-attribute` ¶

trainable = trainable

feedback `property` ¶

feedback

The feedback from children nodes.

description `property` ¶

description

A textual description of the node.

op_name `property` ¶

op_name

The operator type of the node, extracted from the description.

info `property` ¶

info

Additional information about the node.

type `property` ¶

type

The type of the data stored in the node.

parameter_dependencies `property` ¶

parameter_dependencies

The depended parameters.

Notes: Ensure that the '_dependencies' attribute is properly initialized and contains a 'parameter' key with a corresponding value before calling the parameter_dependencies function to avoid potential KeyError exceptions.

expandable_dependencies `property` ¶

expandable_dependencies

The depended expandable nodes.

Notes: Expandable nodes are those who depend on parameters not visible in the current graph level. Ensure that the '_dependencies' attribute is properly initialized and contains an 'expandable' key with a corresponding value before calling the expandable_dependencies function to avoid potential KeyError exceptions.

zero_feedback ¶

zero_feedback()

Zero out the feedback of the node.

Notes: zero_feedback should be used judiciously within the feedback propagation process to avoid unintended loss of feedback data. It is specifically designed to be used after feedback has been successfully propagated to parent nodes.

backward ¶

backward(
    feedback: Any = "",
    propagator=None,
    retain_graph=False,
    visualize=False,
    simple_visualization=True,
    reverse_plot=False,
    print_limit=100,
)

Performs a backward pass in a computational graph.

This function propagates feedback from the current node to its parents, updates the graph visualization if required, and returns the resulting graph.

Args: feedback: The feedback given to the current node. propagator: A function that takes in a node and a feedback, and returns a dict of {parent: parent_feedback}. If not provided, a default GraphPropagator object is used. retain_graph: If True, the graph will be retained after backward pass. visualize: If True, the graph will be visualized using graphviz. simple_visualization: If True, identity operators will be skipped in the visualization. reverse_plot: If True, plot the graph in reverse order (from child to parent). print_limit: The maximum number of characters to print for node descriptions and content.

Returns: digraph: The visualization graph object if visualize=True, None otherwise.

Raises: AttributeError: If the node has already been backwarded.

Notes: The function checks if the current node has already been backwarded. If it has, an AttributeError is raised. For root nodes (no parents), only visualization is performed if enabled. For non-root nodes, feedback is propagated through the graph using a priority queue to ensure correct ordering. The propagator computes feedback for parent nodes based on the current node's description, data and feedback. Visualization is handled using graphviz if enabled, with options to simplify the graph by skipping identity operators.

clone ¶

clone()

Create and return a duplicate of the current Node object.

Returns: Node: A clone of the current node.

detach ¶

detach()

Create and return a deep copy of the current instance of the Node class.

Returns: Node: A deep copy of the current node.

getattr ¶

getattr(key)

Get the attribute of the node with the specified key.

Args: key: The key of the attribute to get.

Returns: Node: A node containing the requested attribute.

call ¶

call(fun: str, *args, **kwargs)

Call the function with the specified arguments and keyword arguments.

Args: fun: The function to call. args: The arguments to pass to the function. *kwargs: The keyword arguments to pass to the function.

Returns: Node: The result of the function call wrapped in a node.

len ¶

len()

Return the length of the node.

Returns: Node: A node containing the length value.

Notes: We overload magic methods that return a value. This method returns a MessageNode.

eq ¶

eq(other)

Check if the node is equal to another value.

Args: other: The value to compare the node to.

Returns: Node: A node containing the comparison result.

Notes: If a logic operator is used in an if-statement, it will return a boolean value. Otherwise, it will return a MessageNode.

neq ¶

neq(other)

Check if the node is not equal to another value.

Args: other: The value to compare the node to.

Returns: Node: A node containing the comparison result.

Notes: If a logic operator is used in an if-statement, it will return a boolean value. Otherwise, it will return a MessageNode.

format ¶

format(*args, **kwargs)

capitalize ¶

capitalize()

lower ¶

lower()

upper ¶

upper()

swapcase ¶

swapcase()

title ¶

title()

split ¶

split(sep=None, maxsplit=-1)

strip ¶

strip(chars=None)

replace ¶

replace(old, new, count=-1)

join ¶

join(seq)

items ¶

items()

values ¶

values()

keys ¶

keys()

pop ¶

pop(__index=-1)

append ¶

append(*args, **kwargs)

stop_tracing ¶

A contextmanager to disable tracing.

model ¶

model(cls)

Wrap a class with this decorator. This helps collect parameters for the optimizer. This decorated class cannot be pickled.

apply_op ¶

apply_op(op, output, *args, **kwargs)

A broadcasting operation that applies an op to container of Nodes.

Args: op (callable): the operator to be applied. output (Any): the container to be updated. args (Any): the positional inputs of the operator. *kwargs (Any): the keyword inputs of the operator.

node ¶

node(data, name=None, trainable=False, description=None)

Create a Node object from data.

Args: data: The data to create the Node from. name (str, optional): The name of the Node. trainable (bool, optional): Whether the Node is trainable. Defaults to False. description (str, optional): A string describing the data.

Returns: Node: A Node object containing the data.

Notes: If trainable=True: - If data is already a Node, extracts underlying data and updates name - Creates ParameterNode with extracted data, name, trainable=True

If trainable=False:
    - If data is already a Node, returns it (with warning if name provided)
    - Otherwise creates new Node with data, name