ARIA Visualization Guide

This document describes the visualization tools for ARIA core outputs. These tools provide read-only analysis and plotting of numeric data from ARIA runs.

Overview

The ARIA visualization package (tools/aria_visualization/) provides visualizers for each ARIA core version:

All tools operate on JSON output from aria_local_loop.py.

Safety Invariants

• Read-only: Visualization tools never modify model behavior
• No identity inference: Outputs are numeric only
• No semantic interpretation: Patterns are displayed, not labeled
• Deterministic: Same input produces same output
• Offline: No network access required

Installation

The visualization tools require:

• Python 3.8+
• matplotlib
• numpy
• networkx (optional, for graph plots)

pip install matplotlib numpy networkx

Quick Start

Unified CLI

The simplest way to generate all visualizations:

# Generate all visualizations
python tools/aria_visualize.py -i run.json -m all -d ./output/

# Generate only symbol visualizations
python tools/aria_visualize.py -i run.json -m symbols -o symbols.png

# Get statistics as JSON
python tools/aria_visualize.py -i run.json --stats

# Show run info
python tools/aria_visualize.py -i run.json --info

Individual Visualizers

Each visualizer can also be used directly:

# Symbol heatmap
python tools/aria_visualization/visual_symbols.py -i run.json -t heatmap -o heatmap.png

# Latent channel traces
python tools/aria_visualization/visual_latents.py -i run.json -t channels -o channels.png

# SSV heatmap
python tools/aria_visualization/visual_state.py -i run.json -t heatmap -o ssv.png

# Relation matrix
python tools/aria_visualization/visual_relations.py -i run.json -t heatmap -o relations.png

Visualizer Details

SymbolVisualizer (ARIA v1)

Visualizes the 8-symbol proto-symbolic layer outputs.

Data Requirements:

• aria_core.symbol_activations - Dict with k_0 through k_7
• aria_core.symbol_entropy - Entropy of symbol distribution
• aria_core.symbol_stability - Temporal stability
• aria_core.dominant_symbol - Index of most active symbol

Plot Types:

Example:

from tools.aria_visualization import SymbolVisualizer
from tools.aria_visualization.utils import load_run_json

data = load_run_json('run.json')
viz = SymbolVisualizer(data)

# Generate single plot
viz.plot_symbol_heatmap('heatmap.png')

# Generate all plots
viz.plot_all('./output/', prefix='symbols')

# Get statistics
stats = viz.get_statistics()
print(f"Mean entropy: {stats['entropy']['mean']:.4f}")

LatentVisualizer (ARIA v0)

Visualizes the 5-dimensional latent field and 4-cluster attractor space.

Data Requirements:

• aria_core.latent_channels - List of 5 floats [L_0, ..., L_4]
• aria_core.cluster_memberships - List of 4 floats (sum to 1.0)
• aria_core.cluster_entropy - Entropy of cluster distribution
• aria_core.stability_gate - Gate state [0, 1]
• aria_core.dominant_cluster - Index of dominant cluster

Plot Types:

Cluster Names:

• Cluster 0: Balanced
• Cluster 1: Coherence-Dominant
• Cluster 2: Energy-Dominant
• Cluster 3: Stability-Dominant

StateVisualizer (ARIA v2)

Visualizes the 12-dimensional System State Vector (SSV).

Data Requirements:

• aria_core.system_state_vector or aria_core.ssv - 12-dim list
• aria_core.state_entropy - SSV entropy
• aria_core.state_stability - SSV temporal stability
• aria_core.drift_index - Aggregate drift measure
• aria_core.coherence_index - Cross-layer coherence
• Change detection: rate_of_change, structural_drift, symbolic_turnover, attractor_transition

SSV Dimensions:

Plot Types:

RelationVisualizer (ARIA v3)

Visualizes the 8x8 relation matrix and 12-dimensional Relational Summary Vector (RSV).

Data Requirements:

• aria_core.relation_matrix - 8x8 matrix of symbol relations
• aria_core.rsv - 12-dim summary vector
• aria_core.relation_entropy - Matrix entropy
• aria_core.plasticity_index - Learning rate indicator
• aria_core.relation_stability - Temporal stability

RSV Dimensions:

Plot Types:

Programmatic Usage

Basic Usage

from tools.aria_visualization import (
    SymbolVisualizer,
    LatentVisualizer,
    StateVisualizer,
    RelationVisualizer,
)
from tools.aria_visualization.utils import load_run_json

# Load data
data = load_run_json('run.json')

# Create visualizers
sym_viz = SymbolVisualizer(data)
lat_viz = LatentVisualizer(data)
state_viz = StateVisualizer(data)
rel_viz = RelationVisualizer(data)

# Extract data for custom analysis
steps, activations = sym_viz.extract_symbol_activations()
steps, ssv_series = state_viz.extract_ssv_time_series()

# Generate plots
sym_viz.plot_all('./output/', prefix='run1')

Custom Plots

import matplotlib.pyplot as plt
import numpy as np

from tools.aria_visualization import StateVisualizer
from tools.aria_visualization.utils import load_run_json

data = load_run_json('run.json')
viz = StateVisualizer(data)

# Get raw data
steps, ssv_series = viz.extract_ssv_time_series()
ssv_array = np.array(ssv_series)

# Custom plot: coherence vs energy
fig, ax = plt.subplots()
ax.scatter(ssv_array[:, 0], ssv_array[:, 11], c=steps, cmap='viridis')
ax.set_xlabel('Substrate Coherence (s0)')
ax.set_ylabel('System Energy (s11)')
ax.set_title('Coherence-Energy Phase Space')
plt.colorbar(ax.collections[0], label='Step')
plt.savefig('coherence_energy.png')

Statistics

from tools.aria_visualization import StateVisualizer
from tools.aria_visualization.utils import load_run_json
import json

data = load_run_json('run.json')
viz = StateVisualizer(data)

stats = viz.get_statistics()
print(json.dumps(stats, indent=2))

Output:

{
  "num_steps": 100,
  "derived_metrics": {
    "state_entropy": {"min": 0.32, "max": 0.68, "mean": 0.52, "std": 0.08},
    "drift_index": {"min": 0.01, "max": 0.18, "mean": 0.07, "std": 0.04}
  },
  "ssv_means": {
    "coh": 0.72,
    "stab": 0.68,
    ...
  }
}

Utility Functions

The utils.py module provides common functions:

from tools.aria_visualization.utils import (
    load_run_json,          # Load JSON file
    extract_snapshots,      # Get snapshots list
    extract_time_series,    # Extract dot-path values
    get_steps,              # Get step numbers
    compute_statistics,     # Min/max/mean/std
    ensure_output_dir,      # Create output directory
    safe_filename,          # Sanitize filenames
    has_detailed_output,    # Check for detailed data
)

Generating Sample Data

For testing without running ARIA:

# Generate test run with aria_local_loop
python tools/aria_local_loop.py \
    --core aria_v3 \
    --steps 100 \
    --dt 0.1 \
    --detailed \
    --output test_run.json

# Visualize
python tools/aria_visualize.py -i test_run.json -m all -d ./viz/

Troubleshooting

"No symbol activations found"

The JSON file may not contain detailed output. Re-run with --detailed:

python tools/aria_local_loop.py --core aria_v1 --detailed -o run.json

"matplotlib not available"

Install visualization dependencies:

pip install matplotlib numpy

"NetworkX required for graph plots"

Install networkx for relation graph visualization:

pip install networkx

Empty plots

Check that snapshots contain the expected fields:

from tools.aria_visualization.utils import load_run_json, has_detailed_output
data = load_run_json('run.json')
print(f"Has detailed output: {has_detailed_output(data)}")
print(f"Num snapshots: {len(data.get('snapshots', []))}")

File Naming

When using plot_all(), files are named as:

{prefix}_{plot_type}.png

For example, with prefix run1:

• run1_heatmap.png
• run1_traces.png
• run1_metrics.png

Integration with aria_local_loop

The visualization tools are designed to work with output from aria_local_loop.py:

# Run ARIA with detailed output
python tools/aria_local_loop.py \
    --core aria_v3 \
    --steps 200 \
    --dt 0.1 \
    --detailed \
    --output my_run.json

# Generate visualizations
python tools/aria_visualize.py \
    -i my_run.json \
    -m all \
    -d ./visualizations/ \
    -p my_run

See Also

• ARIA Core Overview - Core architecture documentation
• ARIA Core v2 Specification - SSV details
• ARIA Core v3 Specification - Relation matrix details