# rpd-512/trace architecture

> Architecture diagram of the GitHub repository rpd-512/trace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rpd-512/trace
- Repository: https://github.com/rpd-512/trace

## Overview

TRACE is a C++ tool for evolving combinational circuits with Cartesian Genetic Programming, using truth-table correctness and area, delay, and power objectives. The main workflow builds a target truth table, loads a Liberty cell library, creates and optionally seeds a population, then evolves and reports a best circuit. The graph also shows circuit serialization and the ATLAS evaluation dependency. The repository tree does not contain ATLAS, and the configured seed filenames are absent from the tree; those limits are reflected below.

Main entry points: [`main.cpp`](https://github.com/rpd-512/trace/blob/main/main.cpp) (TRACE Entry), [`includes/cgp_utils.h`](https://github.com/rpd-512/trace/blob/main/includes/cgp_utils.h) (CGP Evolution), [`includes/io_utils.h`](https://github.com/rpd-512/trace/blob/main/includes/io_utils.h) (Circuit Reporting), [`includes/random_utils.h`](https://github.com/rpd-512/trace/blob/main/includes/random_utils.h) (Circuit Operators)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Problem Setup"]
  node_entry["TRACE Entry<br/>[main.cpp]"]
  node_targets["Target Tables<br/>[main.cpp]"]
  node_library["Liberty Cells"]
end

subgraph group_evolution["Circuit Evolution"]
  node_initializer["Population Initialization<br/>[cgp_utils.h]"]
  node_genetics["Circuit Operators<br/>[random_utils.h]"]
  node_evolver["CGP Evolution<br/>[cgp_utils.h]"]
end

subgraph group_evaluation["Evaluation"]
  node_fitness["Fitness Scoring<br/>[cgp_utils.h]"]
  node_atlas["ATLAS Circuit Engine"]
end

subgraph group_io["Circuit I/O"]
  node_seedloader["Seed Loading<br/>[io_utils.h]"]
  node_seedfiles["Seed Netlist<br/>[netlist.json]"]
  node_reporting["Circuit Reporting<br/>[io_utils.h]"]
  node_formatting["Circuit Formatter<br/>[debug_utils.h]"]
  node_bestfile["Best Circuit Output"]
end

node_engineer(("Circuit Designer"))

node_engineer -->|"starts"| node_entry
node_entry -->|"builds"| node_targets
node_entry -->|"parses"| node_library
node_entry -->|"generates"| node_initializer
node_entry -->|"loads seeds"| node_seedloader
node_entry -->|"starts evolution"| node_evolver
node_entry -->|"checks result"| node_fitness
node_seedloader -->|"parses netlist"| node_seedfiles
node_initializer -->|"creates circuits"| node_genetics
node_initializer -.->|"uses cell data"| node_library
node_evolver -->|"mutates and crosses"| node_genetics
node_evolver -->|"scores offspring"| node_fitness
node_evolver -.->|"restarts population"| node_initializer
node_fitness -.->|"compares outputs"| node_targets
node_fitness -->|"evaluates circuits"| node_atlas
node_genetics -->|"selects usable cells"| node_library
node_evolver -->|"saves reports"| node_reporting
node_reporting -->|"writes circuit"| node_formatting
node_reporting -->|"saves best circuit"| node_bestfile

click node_entry "https://github.com/rpd-512/trace/blob/main/main.cpp"
click node_targets "https://github.com/rpd-512/trace/blob/main/main.cpp"
click node_library "https://github.com/rpd-512/trace/blob/main/liberty/sky130_fd_sc_hd__tt_025C_1v80.lib"
click node_initializer "https://github.com/rpd-512/trace/blob/main/includes/cgp_utils.h"
click node_genetics "https://github.com/rpd-512/trace/blob/main/includes/random_utils.h"
click node_evolver "https://github.com/rpd-512/trace/blob/main/includes/cgp_utils.h"
click node_seedloader "https://github.com/rpd-512/trace/blob/main/includes/io_utils.h"
click node_seedfiles "https://github.com/rpd-512/trace/blob/main/seed_directory/netlist.json"
click node_fitness "https://github.com/rpd-512/trace/blob/main/includes/cgp_utils.h"
click node_reporting "https://github.com/rpd-512/trace/blob/main/includes/io_utils.h"
click node_formatting "https://github.com/rpd-512/trace/blob/main/includes/debug_utils.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_targets,node_library toneBlue
class node_initializer,node_genetics,node_evolver toneAmber
class node_fitness,node_atlas toneMint
class node_seedloader,node_seedfiles,node_reporting,node_formatting,node_bestfile toneRose
class node_engineer toneIndigo
```

## Components

### Problem Setup

- [TRACE Entry](https://github.com/rpd-512/trace/blob/main/main.cpp): `main.cpp`
- [Target Tables](https://github.com/rpd-512/trace/blob/main/main.cpp): `main.cpp`
- [Liberty Cells](https://github.com/rpd-512/trace/blob/main/liberty/sky130_fd_sc_hd__tt_025C_1v80.lib): `liberty/sky130_fd_sc_hd__tt_025C_1v80.lib`

### Circuit Evolution

- [Population Initialization](https://github.com/rpd-512/trace/blob/main/includes/cgp_utils.h): `includes/cgp_utils.h`
- [Circuit Operators](https://github.com/rpd-512/trace/blob/main/includes/random_utils.h): `includes/random_utils.h`
- [CGP Evolution](https://github.com/rpd-512/trace/blob/main/includes/cgp_utils.h): `includes/cgp_utils.h`

### Evaluation

- [Fitness Scoring](https://github.com/rpd-512/trace/blob/main/includes/cgp_utils.h): `includes/cgp_utils.h`
- **ATLAS Circuit Engine**

### Circuit I/O

- [Seed Loading](https://github.com/rpd-512/trace/blob/main/includes/io_utils.h): `includes/io_utils.h`
- [Seed Netlist](https://github.com/rpd-512/trace/blob/main/seed_directory/netlist.json): `seed_directory/netlist.json`
- [Circuit Reporting](https://github.com/rpd-512/trace/blob/main/includes/io_utils.h): `includes/io_utils.h`
- [Circuit Formatter](https://github.com/rpd-512/trace/blob/main/includes/debug_utils.h): `includes/debug_utils.h`
- **Best Circuit Output**

### Other components

- **Circuit Designer**

## Connections

- Circuit Designer → TRACE Entry: starts (evidence: `main.cpp`)
- TRACE Entry → Target Tables: builds (evidence: `main.cpp`)
- TRACE Entry → Liberty Cells: parses (evidence: `main.cpp`)
- TRACE Entry → Population Initialization: generates (evidence: `main.cpp`)
- TRACE Entry → Seed Loading: loads seeds (evidence: `main.cpp`)
- TRACE Entry → CGP Evolution: starts evolution (evidence: `main.cpp`)
- TRACE Entry → Fitness Scoring: checks result (evidence: `main.cpp`)
- Seed Loading → Seed Netlist: parses netlist (evidence: `includes/io_utils.h`)
- Population Initialization → Circuit Operators: creates circuits (evidence: `includes/cgp_utils.h`)
- Population Initialization → Liberty Cells: uses cell data
- CGP Evolution → Circuit Operators: mutates and crosses (evidence: `includes/cgp_utils.h`)
- CGP Evolution → Fitness Scoring: scores offspring (evidence: `includes/cgp_utils.h`)
- CGP Evolution → Population Initialization: restarts population (evidence: `includes/cgp_utils.h`)
- Fitness Scoring → Target Tables: compares outputs (evidence: `main.cpp`)
- Fitness Scoring → ATLAS Circuit Engine: evaluates circuits (evidence: `includes/cgp_utils.h`)
- Circuit Operators → Liberty Cells: selects usable cells (evidence: `includes/random_utils.h`)
- CGP Evolution → Circuit Reporting: saves reports (evidence: `includes/cgp_utils.h`)
- Circuit Reporting → Circuit Formatter: writes circuit (evidence: `includes/io_utils.h`)
- Circuit Reporting → Best Circuit Output: saves best circuit
