# aag2dot.py -- Gate-Level Circuit Diagram

## Purpose

Converts an ASCII AIGER (`.aag`) file into a Graphviz DOT representation
showing the raw gate-level circuit topology. Unlike `trace_aiger.py` which
shows the behavioral state machine, this shows the actual hardware structure:
AND gates, latches, and wiring.

## Usage

```bash
python3 scripts/aag2dot.py circuits/SPEC.aag | dot -Tsvg -o diagrams/SPEC_gates.svg
```

## How It Works

### `parse_aag(text)`

Same AIGER parsing logic as `trace_aiger.py` (see that documentation for
format details). Returns a dictionary of inputs, latches, outputs, and AND
gates.

### `lit_node(lit)`

Maps an AIGER literal to a Graphviz node ID and negation flag:

- Literal `14` -> `("n7", False)` -- variable 7, positive
- Literal `15` -> `("n7", True)` -- variable 7, negated

### `to_dot(aag)`

Generates the DOT string with:

- **Input nodes** (light blue boxes): environment signals
- **Latch nodes** (yellow rounded boxes): state registers
- **AND gate nodes** (white circles): combinational logic
- **Output nodes** (green boxes): controller outputs
- **Solid edges**: positive connections
- **Dashed red edges** with `~` label: negated connections
- **Feedback edges** (constraint=false): latch next-state wiring, drawn
  backward to show the feedback loop

## When to Use

The gate-level view is useful for:

- Verifying the circuit structure matches expectations
- Understanding how the synthesizer encoded the state transitions
- Debugging unexpected behavior by tracing signals through gates
- Presentations where you want to show "this is real hardware"

For understanding the controller's behavior (which mode transitions to
which, under what conditions), use `trace_aiger.py` instead.

## Future Improvements

- **Signal propagation highlighting**: Color-code paths from a specific
  input to the outputs it affects.
- **Latch grouping**: Visually group latches and their feedback logic
  into subclusters.
- **Gate count summary**: Print statistics (number of each gate type,
  circuit depth, fan-in/fan-out).