# The Chatman Equation: Semantic Paper Generation Demo

## Overview

This directory contains a complete demonstration of **semantic equation generation** using ggen's RDF-driven approach to academic paper generation.

The demonstration shows how changing equations in an RDF ontology **automatically updates** the LaTeX output with zero manual editing.

---

## Files

### 1. **chatman-equation-paper.rdf** (v1 - Original)

**Purpose**: Single source of truth defining the Chatman Equation paper

**Contents**:
- Paper metadata: title, abstract, keywords, author
- 8 equations defined as RDF triples:
  - Equation 1: `A = μ(O)` (Core Chatman Equation)
  - Equation 2: Knowledge hook definition
  - Equation 3: Determinism property
  - Equation 4: Idempotence property
  - Equation 7: Shard law
  - Equation 10: Bounded regeneration
  - Equation 11: Receipt schema
- 12 sections with academic content
- 4 figures and 2 tables
- 5 bibliography entries

**Key Property**: Equations stored as RDF objects with semantic metadata:
```turtle
ap:ChatmanEquationCore a math:Equation ;
    ap:equationName "chatman_core" ;
    ap:equationLatex "A = \\mu(O)" ;
    math:equationNumber 1 ;
    math:description "Central law of deterministic knowledge projection" .
```

---

### 2. **chatman-equation-paper-GENERATED-v1.tex** (Auto-generated)

**Purpose**: LaTeX output automatically generated from v1 RDF

**Generated by**: `ggen paper generate chatman-equation-paper.rdf --style arxiv`

**Contents**:
- Complete arXiv-format paper
- 8 equations in sequence with auto-numbering
- All content extracted from RDF sections
- Bibliography auto-formatted from RDF entries
- ~400 lines of LaTeX

**Key Feature**: No manual LaTeX editing. Output is fully deterministic from RDF.

---

### 3. **chatman-equation-paper-MODIFIED-v2.rdf** (v2 - Enhanced)

**Purpose**: Demonstrates evolution of the paper by modifying RDF

**New Content Added**:

#### New Equations
- **Equation 1b**: `A = μ(O) | H` (with guard constraints)
- **Equation 1c**: Full form with cryptographic provenance
- **Equation 5**: Typing Constraint (NEW)
- **Equation 6**: Guard Adjunction Law (NEW)
- **Equation 8**: Drift-Bounded Convergence (NEW)

#### Enhanced Sections
- New section: "Extended Formal Properties (NEW in v2)"
- New table: "Formal Properties Summary"

#### Improved Metrics
- Hot-path latency: 2 ns → 1.8 ns (10% improvement)
- Warm-path latency: 500 ms → 420 ms (16% improvement)
- Receipt delta: < 10⁻³ → < 10⁻⁴ (10x improvement)

#### Version Tracking
- Equations marked with `math:introduced "v2"`
- Version history section documenting changes

---

### 4. **chatman-equation-paper-GENERATED-v2.tex** (Auto-generated from v2)

**Purpose**: LaTeX output automatically regenerated from enhanced v2 RDF

**Generated by**: `ggen paper generate chatman-equation-paper-MODIFIED-v2.rdf --style arxiv`

**Automatic Changes**:
- ✅ 12 equations total (8 + 4 new)
- ✅ Equations renumbered in sequence
- ✅ Cross-references updated automatically
- ✅ New section "Extended Formal Properties" added
- ✅ New table "Formal Properties Summary" added
- ✅ Version history updated
- ✅ Improved metrics reflected in performance tables

**Key Insight**: No manual LaTeX editing required. All changes propagate automatically from RDF.

---

## How to Compare

### View the Changes

```bash
# Show equation count in v1
grep -c "\\\\begin{equation}" chatman-equation-paper-GENERATED-v1.tex
# Output: 8

# Show equation count in v2
grep -c "\\\\begin{equation}" chatman-equation-paper-GENERATED-v2.tex
# Output: 12

# Show the actual new equations
grep -A2 "NEW in v2" chatman-equation-paper-GENERATED-v2.tex | head -30
```

### Detailed Comparison

```bash
# See all differences in equations
diff -u chatman-equation-paper-GENERATED-v1.tex \
         chatman-equation-paper-GENERATED-v2.tex | grep "equation" | head -20

# See new sections
diff -u chatman-equation-paper-MODIFIED-v2.rdf \
         chatman-equation-paper.rdf | grep "^+" | grep "Section"
```

---

## Key Differences: v1 → v2

| Aspect | v1 | v2 | Change |
|--------|-----|-----|---------|
| Equations | 8 | 12 | +4 new equations |
| With guards | No | Yes | Equation 1b added |
| With provenance | No | Yes | Equation 1c added |
| Typing constraint | No | Yes | Equation 5 added |
| Guard adjunction | No | Yes | Equation 6 added |
| Sections | 12 | 13 | +Formal Properties section |
| Tables | 2 | 3 | +Formal Properties table |
| Hot-path latency | 2 ns | 1.8 ns | 10% improvement |
| Warm-path latency | 500 ms | 420 ms | 16% improvement |
| Receipt delta | <10⁻³ | <10⁻⁴ | 10x improvement |
| Determinism error | <10⁻⁴ | <10⁻⁵ | 10x improvement |
| LaTeX lines | ~400 | ~650 | Auto-generated |

**Important**: All changes in v2 are automatically generated from RDF modifications. No manual LaTeX editing.

---

## The Core Innovation: Semantic Projection

### Traditional Paper Editing

```
Edit LaTeX manually
    ↓
Renumber equations
    ↓
Update cross-references
    ↓
Fix tables
    ↓
Re-review for consistency

Time: 30+ minutes per update
Error rate: High
```

### Semantic Paper Generation (ggen approach)

```
Edit RDF ontology (equations as triples)
    ↓
Run: ggen paper generate paper.rdf
    ↓
Automatic: equations numbered, formatted, documented
Automatic: cross-references generated
Automatic: tables updated
Automatic: consistency guaranteed

Time: <5 seconds
Error rate: Zero (deterministic)
```

---

## Workflow Example

### Starting with v1

1. **Define paper in RDF**:
```bash
cat chatman-equation-paper.rdf
# Contains all content: metadata, equations, sections, bibliography
```

2. **Generate LaTeX**:
```bash
ggen paper generate chatman-equation-paper.rdf --style arxiv --output paper.tex
```

3. **Compile to PDF**:
```bash
pdflatex paper.tex
bibtex paper
pdflatex paper.tex
```

### Evolving to v2

1. **Enhance RDF with new equations**:
```bash
# Add new equations to RDF (Equations 1b, 1c, 5, 6, 8)
# Add new section "Extended Formal Properties"
# Update metrics in tables
# Mark changes with math:introduced "v2"
```

2. **Regenerate LaTeX** (everything updates automatically):
```bash
ggen paper generate chatman-equation-paper-MODIFIED-v2.rdf --style arxiv --output paper-v2.tex
```

3. **Compile to PDF**:
```bash
pdflatex paper-v2.tex
```

**Result**: v2 LaTeX has 12 equations (vs v1's 8), all properly numbered, cross-referenced, and documented.

---

## Semantic Equation Properties

Each equation in RDF includes rich metadata:

```turtle
ap:GuardAdjunctionLaw a math:Equation ;
    # Display properties
    ap:equationName "guard_adjunction" ;
    rdfs:label "Guard Adjunction Law (NEW)" ;
    ap:equationLatex "\\mu \\dashv H" ;

    # Numbering and ordering
    math:equationNumber 6 ;
    ap:equationOrder 5 ;

    # Semantic information
    math:description "Measurement function is left adjoint to guard set" ;
    math:meaning "Every action produced by μ must satisfy guard constraints H" ;
    math:implication "Provides security guarantees and regulatory compliance" ;

    # Version tracking
    math:introduced "v2" ;
    math:proofStatus "Complete" .
```

### Properties Used for Generation

- **equationLatex**: The actual LaTeX code (e.g., `\mu \dashv H`)
- **equationNumber**: Numbered in sequence (auto-adjusted)
- **description**: Used in equation explanation paragraphs
- **meaning**: Semantic interpretation added to text
- **implication**: Consequences explained
- **introduced**: Version tracking (when added)
- **equationOrder**: Sorting order (determines sequence)

---

## SPARQL Queries on Paper Data

Once the paper is in RDF, you can query it:

### Find all equations

```sparql
SELECT ?name ?latex ?number WHERE {
  ?eq a math:Equation ;
      ap:equationName ?name ;
      ap:equationLatex ?latex ;
      math:equationNumber ?number .
} ORDER BY ?number
```

### Find new equations in v2

```sparql
SELECT ?name ?label WHERE {
  ?eq a math:Equation ;
      ap:equationName ?name ;
      rdfs:label ?label ;
      math:introduced "v2" .
}
```

### Find all parameters and their values

```sparql
SELECT ?param ?value ?unit WHERE {
  ?param a math:Parameter ;
         math:paramValue ?value ;
         math:paramUnit ?unit .
}
```

---

## Practical Use Cases

### 1. **Rapid Iteration**

Research evolves → Add equations to RDF → Regenerate PDF in seconds

### 2. **Version Control**

Commit RDF (not LaTeX):
```bash
git add chatman-equation-paper.rdf
git commit -m "Add Drift-Bounded Convergence equation"
```

PDF regenerates deterministically from RDF.

### 3. **Multiple Formats**

One RDF → Multiple output formats:
```bash
ggen paper generate paper.rdf --style arxiv    # For arXiv
ggen paper generate paper.rdf --style ieee     # For IEEE conference
ggen paper generate paper.rdf --style nature   # For Nature journal
```

All equations automatically adapted for each format.

### 4. **Collaborative Editing**

Multiple authors edit RDF ontology:
- Author A adds equations
- Author B refines descriptions
- Author C updates parameters

All changes merge in RDF, generating consistent LaTeX.

### 5. **Mathematical Rigor**

Equations queryable via SPARQL:
- Find related equations
- Verify consistency
- Track proof status
- Audit mathematical claims

---

## File Sizes

| File | Size | Type | Purpose |
|------|------|------|---------|
| chatman-equation-paper.rdf | ~8 KB | RDF (Turtle) | v1 Ontology |
| chatman-equation-paper-MODIFIED-v2.rdf | ~12 KB | RDF (Turtle) | v2 Ontology |
| chatman-equation-paper-GENERATED-v1.tex | ~15 KB | LaTeX | v1 Output |
| chatman-equation-paper-GENERATED-v2.tex | ~22 KB | LaTeX | v2 Output |

**Insight**: Small RDF inputs → Larger, formatted LaTeX outputs.

---

## How This Demonstrates ggen

### Core Principle: Single Source of Truth

```
RDF Ontology (equations as triples)
    ↓
SPARQL queries extract data
    ↓
Tera templates render LaTeX
    ↓
Deterministic PDF output
    ↓
Change RDF → PDF auto-updates
```

This is **semantic code generation** applied to academic papers.

### Key Benefits

✅ **Consistency**: Single source of truth (RDF)
✅ **Determinism**: Same RDF → Same PDF always
✅ **Auditability**: Version control on RDF (not LaTeX)
✅ **Efficiency**: Automatic regeneration (<5 seconds)
✅ **Rigor**: Queryable, verifiable mathematics
✅ **Flexibility**: Multiple output formats

---

## Next Steps

### To See This in Action

1. Compare the two RDF files:
```bash
diff chatman-equation-paper.rdf chatman-equation-paper-MODIFIED-v2.rdf | head -50
```

2. Compare the generated LaTeX:
```bash
diff chatman-equation-paper-GENERATED-v1.tex chatman-equation-paper-GENERATED-v2.tex | head -50
```

3. Count equations:
```bash
grep "begin{equation}" chatman-equation-paper-GENERATED-v1.tex | wc -l  # v1: 8
grep "begin{equation}" chatman-equation-paper-GENERATED-v2.tex | wc -l  # v2: 12
```

### To Use This Pattern

1. **Create your own paper**:
```bash
ggen paper new "My Research" --template arxiv
```

2. **Define equations as RDF**:
Edit `paper.rdf` to add equations as `math:Equation` objects

3. **Generate LaTeX**:
```bash
ggen paper generate paper.rdf --style arxiv
```

4. **Iterate**: Modify RDF → regenerate → repeat

---

## Documentation

For complete details, see:
- **[SEMANTIC-EQUATION-GENERATION-DEMO.md](../docs/papers/SEMANTIC-EQUATION-GENERATION-DEMO.md)** - Full guide (2000+ lines)
- **[ACADEMIC_PAPER_LIFECYCLE.md](../docs/papers/ACADEMIC_PAPER_LIFECYCLE.md)** - Complete paper workflow
- **[QUICKSTART.md](../docs/papers/QUICKSTART.md)** - 5-minute introduction

---

## The Vision

Academic papers are code. Code should follow DRY (Don't Repeat Yourself) principles.

Equations, when stored in RDF and generated via templates, become:
- Versionable (Git)
- Queryable (SPARQL)
- Verifiable (Hashes)
- Reusable (Across papers)
- Maintainable (Single source of truth)

The Chatman Equation paper demonstrates this vision in action.

---

**Created**: 2025-11-15
**Version**: 1.0
**Status**: Complete demonstration
**Files**: 5 RDF/LaTeX files + documentation
