# benjaminveysi/pulsarx architecture

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

- Interactive diagram: https://gitdiagram.com/benjaminveysi/pulsarx
- Repository: https://github.com/benjaminveysi/pulsarx

## Overview

PulsarX is a native execution engine for arithmetic pipelines over record streams. A user supplies a pipeline and records; the engine selects a scalar, SIMD, or JIT execution strategy, runs it, and can tune choices against the host. Its documented capabilities also include trace JIT, metamorphic code generation, and polynomial optimizations. The two gate programs exercise and verify engine behavior. The excerpts show only parts of the engine and gates; links not directly evidenced by those excerpts are based on README statements or the source index.

Main entry points: [`pulsarX_ASM.c`](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c) (Execution engine), [`metamorphic_shield_gate.c`](https://github.com/benjaminveysi/pulsarx/blob/main/metamorphic_shield_gate.c) (Metamorphic shield gate), [`scientific_gate.c`](https://github.com/benjaminveysi/pulsarx/blob/main/scientific_gate.c) (Scientific gate), [`pulsar_numa_compat.h`](https://github.com/benjaminveysi/pulsarx/blob/main/pulsar_numa_compat.h) (NUMA allocation shim)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Pipeline runtime"]
  node_engine["Execution engine<br/>[pulsarX_ASM.c]"]
  node_pipeline["Record pipeline<br/>[pulsarX_ASM.c]"]
  node_cpu_dispatch["CPU dispatch<br/>[pulsarX_ASM.c]"]
  node_numa["NUMA allocation shim"]
end

subgraph group_kernels["Execution kernels"]
  node_scalar["Scalar kernel<br/>[pulsarX_ASM.c]"]
  node_simd["SIMD kernels<br/>[pulsarX_ASM.c]"]
  node_jit["Native JIT<br/>[pulsarX_ASM.c]"]
  node_trace["Trace JIT<br/>[pulsarX_ASM.c]"]
  node_meta_jit["Metamorphic JIT<br/>[pulsarX_ASM.c]"]
end

subgraph group_optimization["Optimization"]
  node_autotuner["Online autotuner<br/>[pulsarX_ASM.c]"]
  node_poly_reduce["Kempner reduction<br/>[pulsarX_ASM.c]"]
  node_estrin["Estrin kernels<br/>[pulsarX_ASM.c]"]
end

subgraph group_verification["Verification gates"]
  node_shield_gate["Metamorphic shield gate"]
  node_scientific_gate["Scientific gate<br/>[scientific_gate.c]"]
end

node_user(("Pipeline user"))

node_user -->|"submits pipeline"| node_engine
node_engine -->|"executes pipeline"| node_pipeline
node_engine -->|"selects strategy"| node_cpu_dispatch
node_cpu_dispatch -->|"dispatches to"| node_scalar
node_cpu_dispatch -->|"dispatches to"| node_simd
node_cpu_dispatch -->|"dispatches to"| node_jit
node_cpu_dispatch -->|"dispatches to"| node_meta_jit
node_engine -->|"supports"| node_trace
node_engine -->|"tunes kernels"| node_autotuner
node_engine -->|"reduces polynomials"| node_poly_reduce
node_engine -->|"uses polynomial kernels"| node_estrin
node_engine -->|"imports compatibility shim"| node_numa
node_shield_gate -->|"compiles and tests"| node_engine
node_scientific_gate -->|"builds and verifies"| node_engine

click node_engine "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_pipeline "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_cpu_dispatch "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_scalar "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_simd "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_jit "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_trace "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_meta_jit "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_autotuner "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_poly_reduce "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_estrin "https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c"
click node_numa "https://github.com/benjaminveysi/pulsarx/blob/main/pulsar_numa_compat.h"
click node_shield_gate "https://github.com/benjaminveysi/pulsarx/blob/main/metamorphic_shield_gate.c"
click node_scientific_gate "https://github.com/benjaminveysi/pulsarx/blob/main/scientific_gate.c"

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_engine,node_pipeline,node_cpu_dispatch,node_numa,node_user toneBlue
class node_scalar,node_simd,node_jit,node_trace,node_meta_jit toneAmber
class node_autotuner,node_poly_reduce,node_estrin toneMint
class node_shield_gate,node_scientific_gate toneRose
```

## Components

### Pipeline runtime

- [Execution engine](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`
- [Record pipeline](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`
- [CPU dispatch](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`
- [NUMA allocation shim](https://github.com/benjaminveysi/pulsarx/blob/main/pulsar_numa_compat.h): `pulsar_numa_compat.h`

### Execution kernels

- [Scalar kernel](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`
- [SIMD kernels](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`
- [Native JIT](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`
- [Trace JIT](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`
- [Metamorphic JIT](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`

### Optimization

- [Online autotuner](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`
- [Kempner reduction](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`
- [Estrin kernels](https://github.com/benjaminveysi/pulsarx/blob/main/pulsarX_ASM.c): `pulsarX_ASM.c`

### Verification gates

- [Metamorphic shield gate](https://github.com/benjaminveysi/pulsarx/blob/main/metamorphic_shield_gate.c): `metamorphic_shield_gate.c`
- [Scientific gate](https://github.com/benjaminveysi/pulsarx/blob/main/scientific_gate.c): `scientific_gate.c`

### Other components

- **Pipeline user**

## Connections

- Pipeline user → Execution engine: submits pipeline (evidence: `README.md`)
- Execution engine → Record pipeline: executes pipeline (evidence: `README.md`)
- Execution engine → CPU dispatch: selects strategy (evidence: `README.md`)
- CPU dispatch → Scalar kernel: dispatches to (evidence: `pulsarX_ASM.c`)
- CPU dispatch → SIMD kernels: dispatches to (evidence: `pulsarX_ASM.c`)
- CPU dispatch → Native JIT: dispatches to (evidence: `README.md`)
- CPU dispatch → Metamorphic JIT: dispatches to (evidence: `README.md`)
- Execution engine → Trace JIT: supports (evidence: `README.md`)
- Execution engine → Online autotuner: tunes kernels (evidence: `README.md`)
- Execution engine → Kempner reduction: reduces polynomials (evidence: `README.md`)
- Execution engine → Estrin kernels: uses polynomial kernels (evidence: `README.md`)
- Execution engine → NUMA allocation shim: imports compatibility shim (evidence: `pulsarX_ASM.c`)
- Metamorphic shield gate → Execution engine: compiles and tests (evidence: `metamorphic_shield_gate.c`)
- Scientific gate → Execution engine: builds and verifies (evidence: `scientific_gate.c`)
