<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [Performance Characteristics: Understanding Code Generation Speed](#performance-characteristics-understanding-code-generation-speed)
  - [Generation Performance Profile](#generation-performance-profile)
    - [Typical Performance Metrics](#typical-performance-metrics)
    - [Scaling Characteristics](#scaling-characteristics)
  - [Memory Usage Patterns](#memory-usage-patterns)
    - [Memory Profile During Generation](#memory-profile-during-generation)
    - [Memory by Language](#memory-by-language)
  - [Where Time Is Spent](#where-time-is-spent)
    - [Breakdown for Typical Project](#breakdown-for-typical-project)
    - [The 80/20 Rule](#the-8020-rule)
  - [Optimization Techniques](#optimization-techniques)
    - [1. Caching: Avoid Reparsing](#1-caching-avoid-reparsing)
    - [2. Parallelization: Generate Multiple Languages](#2-parallelization-generate-multiple-languages)
    - [3. Incremental Generation: Only Changed Classes](#3-incremental-generation-only-changed-classes)
    - [4. Template Optimization: Minimize Complexity](#4-template-optimization-minimize-complexity)
    - [5. Graph Pruning: Remove Unused Classes](#5-graph-pruning-remove-unused-classes)
  - [Bottleneck Analysis](#bottleneck-analysis)
    - [Bottleneck 1: RDF Parsing is Slow?](#bottleneck-1-rdf-parsing-is-slow)
    - [Bottleneck 2: Template Rendering is Slow?](#bottleneck-2-template-rendering-is-slow)
    - [Bottleneck 3: Generated Code Compilation is Slow?](#bottleneck-3-generated-code-compilation-is-slow)
  - [Real-World Performance Cases](#real-world-performance-cases)
    - [Case 1: Microservices Platform](#case-1-microservices-platform)
    - [Case 2: Large Monolith](#case-2-large-monolith)
  - [Performance Tuning Checklist](#performance-tuning-checklist)
  - [Performance Under Constraints](#performance-under-constraints)
    - [When System Resources are Limited](#when-system-resources-are-limited)
    - [When Network is Slow](#when-network-is-slow)
  - [Summary](#summary)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# Performance Characteristics: Understanding Code Generation Speed

How ggen performs and where to optimize.

## Generation Performance Profile

### Typical Performance Metrics

| Operation | Duration | Bottleneck |
|-----------|----------|-----------|
| Parse Turtle RDF (100 classes) | 200ms | RDF parsing library |
| SPARQL query (simple) | 50ms | Graph traversal |
| Template rendering (100 classes) | 300ms | Template engine |
| Code generation (full cycle) | 600ms | Template I/O |
| TypeScript compilation | 1-2s | TypeScript compiler |
| Rust compilation | 5-15s | Rust compiler |

**Total for full workflow**: 2-20 seconds (mostly language compilation, not ggen)

### Scaling Characteristics

| Metric | 10 Classes | 100 Classes | 1000 Classes |
|--------|-----------|------------|------------|
| Parse time | 20ms | 200ms | 2.5s |
| Query time | 5ms | 50ms | 500ms |
| Generation time | 50ms | 300ms | 3s |
| **Total** | **75ms** | **550ms** | **6s** |

**Insight**: Generation scales linearly (O(n)) with ontology size.

## Memory Usage Patterns

### Memory Profile During Generation

```
Parsing RDF:      50MB (graph representation)
Template engine:  20MB (AST, variables)
Generated code:   10-100MB (depends on output language)
Peak memory:      ~150MB for 1000-class ontology
```

### Memory by Language

| Language | Simple Model | Complex Model |
|----------|-------------|--------------|
| TypeScript | 5MB | 50MB |
| Python | 3MB | 30MB |
| Rust | 8MB | 80MB |

## Where Time Is Spent

### Breakdown for Typical Project

```
RDF Parsing:     33%  ████████████░░░░░░░░░░░░░░░░
Template Render: 50%  ████████████████░░░░░░░░░░░░
I/O Operations:  17%  ██████░░░░░░░░░░░░░░░░░░░░░░
─────────────────────────────────────────────
Total:           600ms
```

### The 80/20 Rule

Optimize the **top 3** bottlenecks:
1. **RDF Parsing** (33%): Cache, split large files
2. **Template Rendering** (50%): Optimize templates, reduce classes
3. **I/O** (17%): Batch writes, use RAM disk for temp files

## Optimization Techniques

### 1. Caching: Avoid Reparsing

**Without cache** (every build):
```bash
time ggen ontology generate schema.ttl \
  --language typescript \
  --output models.ts
# Real 0.8s, User 0.6s
```

**With cache** (subsequent runs):
```bash
time ggen ontology generate schema.ttl \
  --language python \
  --output models.py \
  --cache  # Reuse parsed RDF
# Real 0.2s, User 0.1s (4x faster)
```

### 2. Parallelization: Generate Multiple Languages

**Sequential** (600ms × 3):
```bash
ggen ontology generate schema.ttl --language rust --output models.rs
ggen ontology generate schema.ttl --language typescript --output models.ts
ggen ontology generate schema.ttl --language python --output models.py
# Total: 1.8 seconds
```

**Parallel** (~600ms total):
```bash
(ggen ontology generate schema.ttl --language rust --output models.rs) &
(ggen ontology generate schema.ttl --language typescript --output models.ts) &
(ggen ontology generate schema.ttl --language python --output models.py) &
wait
# Total: 0.6 seconds (3x faster)
```

### 3. Incremental Generation: Only Changed Classes

**Full regeneration**:
```bash
ggen ontology generate schema.ttl --output models.ts
# Processes all 200 classes: 1.2 seconds
```

**Incremental** (if only 5 classes changed):
```bash
ggen ontology generate schema.ttl \
  --output models.ts \
  --incremental \
  --changed-classes User,Product,Order
# Only processes changed classes: 0.1 seconds (12x faster)
```

### 4. Template Optimization: Minimize Complexity

**Complex template** (lots of conditionals):
```liquid
{% for class in classes %}
  {% if class.is_abstract %}
    {% if config.include_docs %}
      {% for parent in class.parents %}
        {# Complex nested logic #}
      {% endfor %}
    {% endif %}
  {% endif %}
{% endfor %}
```

**Optimized template** (pre-computed, simpler):
```liquid
{# Pre-filter in code rather than in template #}
{% for class in abstract_classes %}
  {% if class.should_render %}
    {# Direct rendering, no nesting #}
  {% endif %}
{% endfor %}
```

### 5. Graph Pruning: Remove Unused Classes

**Before**: 500 total classes, 200 actually used
```bash
ggen ontology generate schema.ttl \
  --output models.ts
# Processes all 500: 3 seconds
```

**After**: Generate only used classes
```bash
ggen ontology generate schema.ttl \
  --include-classes User,Product,Order \
  --output models.ts
# Processes only 3: 0.05 seconds (60x faster!)
```

## Bottleneck Analysis

### Bottleneck 1: RDF Parsing is Slow?

**Symptom**: Takes > 1 second to parse

**Solutions**:
```bash
# 1. Check file size
du -h schema.ttl
# If > 10MB, split into modules

# 2. Use binary format (faster than Turtle)
ggen ontology convert schema.ttl schema.rdf --format binary

# 3. Cache parsed results
ggen ontology generate schema.ttl --cache

# 4. Measure actual time
time ggen ontology validate schema.ttl
# Shows breakdown
```

### Bottleneck 2: Template Rendering is Slow?

**Symptom**: Generation takes > 2 seconds after parsing

**Solutions**:
```bash
# 1. Simplify template logic
# Remove deeply nested conditionals

# 2. Pre-process data
# Compute in ontology, not in template

# 3. Use template fragments
# Split large templates into smaller ones

# 4. Profile template
GGEN_PROFILE=true ggen ontology generate schema.ttl --output models.ts
```

### Bottleneck 3: Generated Code Compilation is Slow?

**Symptom**: npm run compile or cargo build slow

**Solution**: Not a ggen issue! It's the language compiler.
```bash
# TypeScript
npm run compile -- --incremental

# Rust
cargo build --incremental

# Python
# Usually fast, no compilation needed
```

## Real-World Performance Cases

### Case 1: Microservices Platform

**Setup**: 5 services, each with 50-class ontology

**Original approach** (sequential generation):
```bash
for service in service-{1..5}; do
  for lang in rust typescript python; do
    ggen ontology generate "$service.ttl" --language $lang
  done
done
# 15 × 0.6s = 9 seconds per build
```

**Optimized approach** (parallel + cache):
```bash
# All languages, all services in parallel
for service in service-{1..5}; do
  (ggen ontology generate "$service.ttl" --language rust --cache) &
  (ggen ontology generate "$service.ttl" --language typescript --cache) &
  (ggen ontology generate "$service.ttl" --language python --cache) &
done
wait
# 3 × 0.6s = 1.8 seconds per build (5x faster)
```

### Case 2: Large Monolith

**Setup**: 500-class ontology for monolithic app

**Incremental workflow**:
```bash
# Build system knows which files changed
CHANGED_CLASSES=$(git diff HEAD~ --name-only | grep -o '[a-z-]*\.ttl')

ggen ontology generate schema.ttl \
  --changed-classes $CHANGED_CLASSES \
  --incremental \
  --output models.ts

# Only regenerate affected classes
# 0.2s instead of 1.5s for full generation
```

## Performance Tuning Checklist

- [ ] Profile baseline: `time ggen ontology generate...`
- [ ] Check file size: `du -h ontology.ttl`
- [ ] Enable caching: `--cache` flag
- [ ] Parallelize languages: `(gen rust) & (gen ts) & (gen py) & wait`
- [ ] Use incremental if available
- [ ] Simplify templates: Remove nested conditionals
- [ ] Prune unused classes: `--include-classes user,product`
- [ ] Monitor memory: System not swapping?
- [ ] Check compiler: TypeScript/Rust compiler may be bottleneck

## Performance Under Constraints

### When System Resources are Limited

**Scenario**: CI/CD environment with 2GB RAM

```bash
# Reduce memory usage
ggen ontology generate schema.ttl \
  --output models.ts \
  --streaming \
  --chunk-size 10  # Process in 10-class chunks
```

### When Network is Slow

**Scenario**: Cloud CI with slow disk I/O

```bash
# Use RAM disk
mkramdisk 500M /mnt/ramdisk
ggen ontology generate schema.ttl \
  --temp-dir /mnt/ramdisk \
  --output models.ts  # Final output to network disk

# Generate to RAM, copy once to persistent storage
```

## Summary

Performance insights:
- ✅ Generation is **linear O(n)** - scales well
- ✅ Typical 1000-class ontology: **6 seconds**
- ✅ **Parallelization**: 3-5x speedup
- ✅ **Caching**: 4-10x speedup
- ✅ **Incremental**: 12-60x speedup (if available)
- ✅ **Main bottleneck**: Language compilation (not ggen)

Your generation pipeline is fast!
