Saturation Profiling Examples

Getting Started

What: example material for the examples topic.
Why: it gives a concrete graph or fixture before you need to understand the full runtime implementation.
How: read one small example first, then run the matching test or benchmark only when you need executable confirmation.
Next: use examples to learn shape; use source READMEs to change behavior.

Quick Start

Example 1: Basic Profiling

cargo run --release --bin profile-phi3-saturation -- \
  --knot /tmp/phi3-mini.knot \
  --output report.csv

Example 2: Extended Profiling (200 prompts)

cargo run --release --bin profile-phi3-saturation -- \
  --knot /tmp/phi3-mini.knot \
  --num-prompts 200 \
  --output /tmp/saturation-detailed.csv

Sample Output

See phi3-saturation-sample.csv for an example report. Key observations:

Early layers (0-7): ~4-20% saturation
- Interpretation: Early layers perform basic feature extraction
- Less opportunity for pruning
Mid layers (8-15): ~20-50% saturation
- Transition zone where redundancy increases
- Some pruning opportunity
Late layers (16-31): ~40-54% saturation
- High redundancy observed
- Maximum pruning potential
- Estimated speedup: 1.8-2.2x if neurons could be completely removed

Interpreting Results

Row Example: Layer 31

Layer,Neurons,LowVarGate%,LowVarUp%,LowVarFFN%,Saturated%,...,EstSpeedup
31,8192,47.8,47.3,52.8,54.1,...,2.19x

Meaning:

47.8% of gate neurons have low variance (repetitive activation)
47.3% of up neurons are frozen
52.8% of FFN outputs are near-constant
Combined saturation: 54.1%
Theoretical speedup if all saturated neurons removed: 2.19x

Practical interpretation:

Over half the neurons in layer 31 are redundant
Could potentially remove ~4400 neurons out of 8192
Actual speedup depends on:
- Sparse kernel efficiency (may not be 2.19x)
- Retraining impact (fine-tune after pruning)
- Quantization (Q4_K may compress redundancy differently)

What's Considered "Saturated"?

A neuron meets saturation criteria if:

Low Variance (< 0.01): Activations are nearly identical across inputs

Activation A: [0.5, 0.505, 0.498, 0.502, ...]  ← Low variance neuron
Activation B: [0.1, 0.9, 0.2, 0.8, ...]        ← High variance neuron

Zero Gradient (|mean| < 0.001): Neuron contributes near-zero signal

Mean activation A: 0.0005 ← Would have tiny gradient
Mean activation B: 0.5   ← Normal gradient flow

Low Activity (< 0.1 threshold > 80% of time): Gate suppresses output

Output A: [0.0, 0.02, 0.01, 0.03, ...]  ← Mostly near-zero (suppressed by SwiGLU)
Output B: [0.5, 0.6, 0.4, 0.7, ...]     ← Active neuron

Decision Framework

If Average Saturation < 10%

Recommendation: Focus on other optimizations

Quantization (Q4_K already applied)
Distillation
Architecture changes
Pruning ROI is too low

If Average Saturation 10-30%

Recommendation: Selective pruning of late layers

Prune layers 20-31 (highest saturation)
Fine-tune with knowledge distillation
Expected real speedup: 1.1-1.3x
Implementation effort: Medium

If Average Saturation > 30%

Recommendation: Full pruning pipeline

Structured pruning (remove entire neurons)
Magnitude-based or activation-based selection
Retraining with layer-wise distillation
Expected real speedup: 1.2-1.8x
Implementation effort: High

Extending the Analysis

1. Domain-Specific Profiling

Profile on domain-specific prompts to see if saturation changes:

# Generate 100 code completion prompts
code_prompts = [
    "def fibonacci(n):",
    "import torch\nmodel = torch.nn.Linear(",
    "SELECT * FROM users WHERE",
    # ... more code
]

# Profile with code domain
# Compare with general domain

2. Quantization Comparison

Compare F32 vs Q4_K saturation patterns:

# F32 variant (if available)
cargo run --release --bin profile-phi3-saturation -- \
  --knot /tmp/phi3-mini-f32.knot \
  --output report-f32.csv

# Q4K variant
cargo run --release --bin profile-phi3-saturation -- \
  --knot /tmp/phi3-mini-q4k.knot \
  --output report-q4k.csv

Expected outcome: Q4_K may reduce saturation if quantization "activates" different neurons.

3. Length-Dependent Saturation

Profile on varying sequence lengths to see if saturation changes:

# Short prompts (10 tokens)
short_prompts = [...]

# Long prompts (512 tokens)
long_prompts = [...]

# Check: Does saturation increase/decrease with sequence length?

Real-World Results (Expected)

Based on similar LLM pruning studies:

Metric	Early Layers	Late Layers
% Saturated	5-15%	40-60%
Variance	High	Low
Zero gradients	2-5%	30-50%
Pruning ROI	Low	High
Estimated speedup	1.01x	1.5-2.0x

Next Steps

Run profiler on real Phi-3-mini model
Analyze results using the decision framework above
Prototype pruning on identified saturated layers
Measure actual speedup (may differ from estimate)
Fine-tune with knowledge distillation if needed

forkjoin-ai/gnosis