# wolframinstitute/hypergraphrewritingengine architecture

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

- Interactive diagram: https://gitdiagram.com/wolframinstitute/hypergraphrewritingengine
- Repository: https://github.com/wolframinstitute/hypergraphrewritingengine

## Overview

Hypergraph Rewriting Engine evolves a user-supplied initial hypergraph under rewrite rules, producing states, events, and causal/branchial relations. The main CPU workflow is exposed through the Mathematica FFI and driven by the parallel evolution engine, which coordinates matching and rewriting against shared hypergraph state. Canonicalization and quotient reconstruction support is represented alongside the core workflow; CUDA and paclet analyses are documented capabilities whose detailed implementation was not sampled. Arrows are limited to relationships shown by excerpts, the source index, or README; unsampled integration details are omitted.

Main entry points: [`paclet_source/hypergraph_ffi.cpp`](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/hypergraph_ffi.cpp) (LibraryLink FFI), [`hypergraph/include/hypergraph/parallel_evolution.hpp`](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/parallel_evolution.hpp) (Parallel evolution), [`paclet_source/cpu_engine_holder.hpp`](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/cpu_engine_holder.hpp) (CPU engine holder), [`hypergraph/include/hypergraph/pattern_matcher.hpp`](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/pattern_matcher.hpp) (Pattern matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_ffi["LibraryLink FFI<br/>[hypergraph_ffi.cpp]"]
  node_session["Session management<br/>[session.hpp]"]
  node_cpu_holder["CPU engine holder"]
  node_marshal["Graph marshalling<br/>[graph_marshal.hpp]"]
  node_wxf["WXF serialization<br/>[wxf.cpp]"]
end

subgraph group_evolution["Evolution engine"]
  node_evolution["Parallel evolution"]
  node_matching["Pattern matching"]
  node_rules["Rewrite rules<br/>[pattern.hpp]"]
  node_rewriter["Match rewriting<br/>[rewriter.hpp]"]
end

subgraph group_state["State and analysis"]
  node_hypergraph[("Hypergraph state<br/>[hypergraph.hpp]")]
  node_canonicalization["Exact canonicalization<br/>[ir_core.hpp]"]
  node_causal["Causal and branchial data<br/>[causal_graph.hpp]"]
  node_quotient["Quotient reconstruction"]
end

subgraph group_accelerators["Accelerated execution"]
  node_gpu_backend["CUDA backend<br/>[hg_gpu_backend.cpp]"]
  node_gpu_engine["CUDA evolution state<br/>[engine_state.hpp]"]
end

node_mathematica(("Mathematica caller"))

node_mathematica -->|"invokes"| node_ffi
node_ffi -->|"creates CPU engine"| node_cpu_holder
node_ffi -->|"manages sessions"| node_session
node_cpu_holder -->|"drives evolution"| node_evolution
node_evolution -->|"dispatches matches"| node_matching
node_evolution -->|"dispatches rewrites"| node_rewriter
node_matching -.->|"matches patterns"| node_rules
node_rewriter -.->|"applies rules"| node_rules
node_evolution -->|"updates state"| node_hypergraph
node_hypergraph -->|"computes canonical hash"| node_canonicalization
node_evolution -->|"builds relations"| node_causal
node_evolution -->|"reconstructs quotient"| node_quotient
node_ffi -.->|"selects GPU backend"| node_gpu_backend
node_gpu_backend -.->|"uses device state"| node_gpu_engine
node_ffi -.->|"marshals results"| node_marshal
node_ffi -.->|"serializes data"| node_wxf

click node_ffi "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/hypergraph_ffi.cpp"
click node_session "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/session.hpp"
click node_cpu_holder "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/cpu_engine_holder.hpp"
click node_evolution "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/parallel_evolution.hpp"
click node_matching "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/pattern_matcher.hpp"
click node_rules "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/pattern.hpp"
click node_rewriter "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/rewriter.hpp"
click node_hypergraph "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/hypergraph.hpp"
click node_canonicalization "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/common/include/hgcommon/ir_core.hpp"
click node_causal "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/causal_graph.hpp"
click node_quotient "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/common/include/hgcommon/quotient_replay_core.hpp"
click node_gpu_backend "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/hg_gpu_backend.cpp"
click node_gpu_engine "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/gpu/include/hg_gpu/engine_state.hpp"
click node_marshal "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/graph_marshal.hpp"
click node_wxf "https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/wxf/wxf.cpp"

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_ffi,node_session,node_cpu_holder,node_marshal,node_wxf toneBlue
class node_evolution,node_matching,node_rules,node_rewriter toneAmber
class node_hypergraph,node_canonicalization,node_causal,node_quotient toneMint
class node_gpu_backend,node_gpu_engine toneRose
class node_mathematica toneIndigo
```

## Components

### User interface

- [LibraryLink FFI](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/hypergraph_ffi.cpp): `paclet_source/hypergraph_ffi.cpp`
- [Session management](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/session.hpp): `paclet_source/session.hpp`
- [CPU engine holder](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/cpu_engine_holder.hpp): `paclet_source/cpu_engine_holder.hpp`
- [Graph marshalling](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/graph_marshal.hpp): `paclet_source/graph_marshal.hpp`
- [WXF serialization](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/wxf/wxf.cpp): `wxf/wxf.cpp`

### Evolution engine

- [Parallel evolution](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/parallel_evolution.hpp): `hypergraph/include/hypergraph/parallel_evolution.hpp`
- [Pattern matching](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/pattern_matcher.hpp): `hypergraph/include/hypergraph/pattern_matcher.hpp`
- [Rewrite rules](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/pattern.hpp): `hypergraph/include/hypergraph/pattern.hpp`
- [Match rewriting](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/rewriter.hpp): `hypergraph/include/hypergraph/rewriter.hpp`

### State and analysis

- [Hypergraph state](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/hypergraph.hpp): `hypergraph/include/hypergraph/hypergraph.hpp`
- [Exact canonicalization](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/common/include/hgcommon/ir_core.hpp): `common/include/hgcommon/ir_core.hpp`
- [Causal and branchial data](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/hypergraph/include/hypergraph/causal_graph.hpp): `hypergraph/include/hypergraph/causal_graph.hpp`
- [Quotient reconstruction](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/common/include/hgcommon/quotient_replay_core.hpp): `common/include/hgcommon/quotient_replay_core.hpp`

### Accelerated execution

- [CUDA backend](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/paclet_source/hg_gpu_backend.cpp): `paclet_source/hg_gpu_backend.cpp`
- [CUDA evolution state](https://github.com/wolframinstitute/hypergraphrewritingengine/blob/master/gpu/include/hg_gpu/engine_state.hpp): `gpu/include/hg_gpu/engine_state.hpp`

### Other components

- **Mathematica caller**

## Connections

- Mathematica caller → LibraryLink FFI: invokes (evidence: `README.md`)
- LibraryLink FFI → CPU engine holder: creates CPU engine (evidence: `paclet_source/cpu_engine_holder.hpp`)
- LibraryLink FFI → Session management: manages sessions (evidence: `paclet_source/session.hpp`)
- CPU engine holder → Parallel evolution: drives evolution (evidence: `paclet_source/cpu_engine_holder.hpp`)
- Parallel evolution → Pattern matching: dispatches matches (evidence: `hypergraph/include/hypergraph/parallel_evolution.hpp`)
- Parallel evolution → Match rewriting: dispatches rewrites (evidence: `hypergraph/include/hypergraph/parallel_evolution.hpp`)
- Pattern matching → Rewrite rules: matches patterns
- Match rewriting → Rewrite rules: applies rules
- Parallel evolution → Hypergraph state: updates state (evidence: `hypergraph/include/hypergraph/parallel_evolution.hpp`)
- Hypergraph state → Exact canonicalization: computes canonical hash (evidence: `hypergraph/src/hypergraph.cpp`)
- Parallel evolution → Causal and branchial data: builds relations (evidence: `README.md`)
- Parallel evolution → Quotient reconstruction: reconstructs quotient (evidence: `README.md`)
- LibraryLink FFI → CUDA backend: selects GPU backend
- CUDA backend → CUDA evolution state: uses device state
- LibraryLink FFI → Graph marshalling: marshals results
- LibraryLink FFI → WXF serialization: serializes data
