Update docstring for Node and KerasHistory with more details.
@@ -31,18 +31,33 @@ _CONSTANT_VALUE = '_CONSTANT_VALUE'
class Node:
- """A `Node` describes the connectivity between two layers.
+ """A `Node` describes a layer `__call__()` event.
- Each time a layer is connected to some new input,
- a node is added to `layer._inbound_nodes`.
- Each time the output of a layer is used by another layer,
- a node is added to `layer._outbound_nodes`.
+ A Functional model is a DAG with `Node` instances as nodes, and `KerasTensor`
+ instances as edges. Nodes aren't `Layer` instances, because a single layer
+ could be called multiple times, which would result in graph cycles.
+
+ A `__call__()` event involves input tensors (and other input arguments),
+ the layer that was called, and the resulting output tensors.
+ A `Node` will include all this information.
+
+ Since a single `Layer` could be called multiple times, the `Node` instances
+ are stored on layers as a list. Each time a layer is called
+ a node is added to `layer._inbound_nodes`. Each time the output of a layer is
+ used by another layer, a node is added to `layer._outbound_nodes`.
+
+ Every `KerasTensor` instance has a `KerasHistory` object attached,
+ which tracks the `Node` that records the `__call__()` event that created
+ the tensor. By recursively walking through `Node` instances
+ via the `KerasHistory` metadata of `KerasTensor` instances, once can
+ retrieve the entire DAG of a Functional model.
Args:
- layer: The Layer for the Layer.__call__ this node represents.
- call_args: The positional arguments the Layer was called with.
- call_kwargs: The keyword arguments the Layer was called with.
- outputs: The outputs of the Layer.__call__
+ layer: The layer that was called in the `Layer.__call__()`
+ event that this node represents.
+ call_args: The positional arguments the layer was called with.
+ call_kwargs: The keyword arguments the layer was called with.
+ outputs: The output tensors of the `Layer.__call__()`
"""
def __init__(self,
@@ -273,7 +288,9 @@ class KerasHistory(
layer: The Layer that produced the Tensor.
node_index: The specific call to the Layer that produced this Tensor. Layers
can be called multiple times in order to share weights. A new node is
- created every time a Layer is called.
+ created every time a Layer is called. The corresponding node that
+ represents the call event that produced the Tensor can be found at
+ `layer._inbound_nodes[node_index]`.
tensor_index: The output index for this Tensor. Always zero if the Layer
that produced this Tensor only has one output. Nested structures of
Tensors are deterministically assigned an index via `nest.flatten`.
