Causality Visualization

Causality Visualization in NeuralDBG is the process of transforming abstract semantic events and detected training failures into structured, human-readable visual representations. Unlike traditional deep learning monitoring tools that focus on raw tensor inspection or line charts, this system visualizes the causal chain of events—identifying how a shift in one layer's activation regime might propagate into gradient health transitions in subsequent layers.

The primary medium for this visualization is the generation of Mermaid diagrams, which map the temporal and structural relationships between training anomalies. This allows researchers to identify root causes and understand the propagation of instabilities throughout the neural network.
Sources: README.md:12-25, visualize_causality.py:5-10, infrastructure_planning/CODEBASE_GUIDE.md:14-19

Architectural Integration

The visualization system acts as a "spoke" in the project's modular architecture, consuming data generated by the core reasoning engine. The NeuralDbg class extracts high-level semantic events during the PyTorch forward and backward passes and stores them in a non-invasive manner. These events are then processed by a visualizer to create a logical graph of the failure.

The following diagram illustrates the data flow from raw training dynamics to the final causal visualization:

This flow ensures that visualization is decoupled from the heavy computation of the training loop, operating as a post-mortem or diagnostic tool.
Sources: logic_graph.md:7-22, infrastructure_planning/CODEBASE_GUIDE.md:104-118, neuraldbg.py:100-110

Causal Graph Generation

The core mechanism for visualization is the export_mermaid_causal_graph method. This function iterates through the captured SemanticEvent objects and uses pattern matching to establish links between them.

Mapping Semantic Events

Each node in the visualization represents a SemanticEvent, containing the transition type, layer name, and training step. The system distinguishes between different event types to provide context to the user.

Sources: neuraldbg.py:27-33, neuraldbg.py:46-59, logic_graph.md:24-32

Relationship Linking Logic

The visualizer identifies three primary types of relationships between nodes:

1. Temporal Flow: Connecting sequential events occurring within the same layer.
2. Coupled Failures: Linking events across different layers that occur within a specific temporal window (e.g., within 5 steps).
3. Causal Propagation: Explicitly marking when an activation shift (trigger) is followed by a gradient failure (consequence).

Export Utilities and API

NeuralDBG provides both programmatic and CLI-based tools for generating visualizations. The visualize_causality.py utility serves as a standalone entry point for exporting causal chains to Markdown files.

Key API Methods

The following methods within the NeuralDbg class facilitate the creation of causal diagrams:

• export_mermaid_causal_graph(): The primary engine for generating the Mermaid syntax string from the internal self.events list.
• detect_coupled_failures(window): A helper method that identifies events that are likely related based on timing and layer proximity.
• trace_causal_chain(event_type): Filters and traces the specific sequence of a particular failure type for targeted visualization.

Sources: neuraldbg.py:339-345, neuraldbg.py:348-355, visualize_causality.py:12-25

CLI Usage Example

The visualization utility can be invoked to save a diagram to an external file:

python3 visualize_causality.py causal_report.md

Sources: visualize_causality.py:22-24

Summary of Visualized States

The visualization system utilizes specific classification logic to label nodes with the "health" of the layer at the time of the event.

Sources: neuraldbg.py:35-44, infrastructure_planning/CODEBASE_GUIDE.md:45-50

Conclusion

Causality Visualization in NeuralDBG transforms complex training metrics into an intuitive logic graph. By focusing on semantic transitions rather than raw data, it provides developers with a clear visual path from the initial anomaly to the final training failure, significantly reducing the time required for post-mortem analysis of deep learning models.