# mdikifahriza/adaptssp architecture

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

- Interactive diagram: https://gitdiagram.com/mdikifahriza/adaptssp
- Repository: https://github.com/mdikifahriza/adaptssp

## Overview

adaptssp is a command-line 1D subset-sum solver. Its main workflow reads and validates a .prb instance, dispatches to TER or Schroeppel–Shamir, verifies and writes a solution, and can optionally explore related solutions through zero-sum swaps. The graph also shows TER’s internal join stages and the optional GPU paths. Several dispatch and output calls fall in omitted source excerpts; those connections are supported by the README, while GPU implementation details are documented there rather than shown in sampled kernel source.

Main entry points: [`src/ter_solver.cpp`](https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_solver.cpp) (TER pipeline), [`src/main.cpp`](https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp) (Verified solution), [`src/ter_kernel.cu`](https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_kernel.cu) (TER CUDA matching), [`src/ss_kernel.cu`](https://github.com/mdikifahriza/adaptssp/blob/main/src/ss_kernel.cu) (GPU quarter sorting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["CLI and results"]
  node_parse["Instance parser<br/>[main.cpp]"]
  node_dispatch["Solver dispatch<br/>[main.cpp]"]
  node_solution["Verified solution<br/>[main.cpp]"]
  node_outputs["Solution files<br/>[main.cpp]"]
end

subgraph group_ter["TER solver"]
  node_tercore["TER pipeline<br/>[ter_solver.cpp]"]
  node_basepool["L3 base pools<br/>[ter_solver.cpp]"]
  node_l2["L2 joins<br/>[ter_solver.cpp]"]
  node_l1["L1 joins<br/>[ter_solver.cpp]"]
  node_tergpu["TER CUDA matching<br/>[ter_kernel.cu]"]
end

subgraph group_ss["Schroeppel–Shamir"]
  node_sscore["SS cardinality search<br/>[main.cpp]"]
  node_quarters["Quarter sums<br/>[main.cpp]"]
  node_heap["Heap pair search<br/>[main.cpp]"]
  node_ssgpu["GPU quarter sorting<br/>[ss_kernel.cu]"]
end

subgraph group_swap["Solution exploration"]
  node_swap["Zero-sum swap BFS<br/>[zero_sum_swap.h]"]
end

subgraph group_support["Shared internals"]
  node_pairs["Pair bookkeeping<br/>[pairs_tuple.hpp]"]
  node_profiler["Phase profiler<br/>[profiler.hpp]"]
end

node_user(("CLI user"))
node_instance["Instance input"]

node_user -->|"provides path"| node_parse
node_instance -->|"is read by"| node_parse
node_parse -->|"supplies instance"| node_dispatch
node_dispatch -->|"selects TER"| node_tercore
node_dispatch -->|"selects SS"| node_sscore
node_tercore -->|"builds"| node_basepool
node_basepool -->|"feeds"| node_l2
node_l2 -->|"feeds"| node_l1
node_l1 -.->|"uses optional GPU matching"| node_tergpu
node_sscore -->|"sets cardinalities"| node_quarters
node_quarters -->|"feeds sorted streams"| node_heap
node_sscore -->|"optionally sorts quarters"| node_ssgpu
node_heap -->|"records matching pairs"| node_pairs
node_tercore -->|"returns verified result"| node_solution
node_heap -->|"returns verified result"| node_solution
node_solution -->|"seeds exploration"| node_swap
node_solution -->|"writes bitstring"| node_outputs
node_tercore -->|"profiles phases"| node_profiler

click node_parse "https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp"
click node_dispatch "https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp"
click node_solution "https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp"
click node_tercore "https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_solver.cpp"
click node_basepool "https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_solver.cpp"
click node_l2 "https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_solver.cpp"
click node_l1 "https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_solver.cpp"
click node_tergpu "https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_kernel.cu"
click node_sscore "https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp"
click node_quarters "https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp"
click node_heap "https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp"
click node_ssgpu "https://github.com/mdikifahriza/adaptssp/blob/main/src/ss_kernel.cu"
click node_swap "https://github.com/mdikifahriza/adaptssp/blob/main/src/zero_sum_swap.h"
click node_pairs "https://github.com/mdikifahriza/adaptssp/blob/main/src/pairs_tuple.hpp"
click node_profiler "https://github.com/mdikifahriza/adaptssp/blob/main/src/profiler.hpp"
click node_outputs "https://github.com/mdikifahriza/adaptssp/blob/main/src/main.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_parse,node_dispatch,node_solution,node_outputs,node_user toneBlue
class node_tercore,node_basepool,node_l2,node_l1,node_tergpu toneAmber
class node_sscore,node_quarters,node_heap,node_ssgpu toneMint
class node_swap toneRose
class node_pairs,node_profiler,node_instance toneIndigo
```

## Components

### CLI and results

- [Instance parser](https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp): `src/main.cpp`
- [Solver dispatch](https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp): `src/main.cpp`
- [Verified solution](https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp): `src/main.cpp`
- [Solution files](https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp): `src/main.cpp`

### TER solver

- [TER pipeline](https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_solver.cpp): `src/ter_solver.cpp`
- [L3 base pools](https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_solver.cpp): `src/ter_solver.cpp`
- [L2 joins](https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_solver.cpp): `src/ter_solver.cpp`
- [L1 joins](https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_solver.cpp): `src/ter_solver.cpp`
- [TER CUDA matching](https://github.com/mdikifahriza/adaptssp/blob/main/src/ter_kernel.cu): `src/ter_kernel.cu`

### Schroeppel–Shamir

- [SS cardinality search](https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp): `src/main.cpp`
- [Quarter sums](https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp): `src/main.cpp`
- [Heap pair search](https://github.com/mdikifahriza/adaptssp/blob/main/src/main.cpp): `src/main.cpp`
- [GPU quarter sorting](https://github.com/mdikifahriza/adaptssp/blob/main/src/ss_kernel.cu): `src/ss_kernel.cu`

### Solution exploration

- [Zero-sum swap BFS](https://github.com/mdikifahriza/adaptssp/blob/main/src/zero_sum_swap.h): `src/zero_sum_swap.h`

### Shared internals

- [Pair bookkeeping](https://github.com/mdikifahriza/adaptssp/blob/main/src/pairs_tuple.hpp): `src/pairs_tuple.hpp`
- [Phase profiler](https://github.com/mdikifahriza/adaptssp/blob/main/src/profiler.hpp): `src/profiler.hpp`

### Other components

- **CLI user**
- **Instance input**

## Connections

- CLI user → Instance parser: provides path (evidence: `README.md`)
- Instance input → Instance parser: is read by (evidence: `src/main.cpp`)
- Instance parser → Solver dispatch: supplies instance (evidence: `README.md`)
- Solver dispatch → TER pipeline: selects TER (evidence: `README.md`)
- Solver dispatch → SS cardinality search: selects SS (evidence: `README.md`)
- TER pipeline → L3 base pools: builds (evidence: `README.md`)
- L3 base pools → L2 joins: feeds (evidence: `src/ter_solver.cpp`)
- L2 joins → L1 joins: feeds (evidence: `src/ter_solver.cpp`)
- L1 joins → TER CUDA matching: uses optional GPU matching (evidence: `README.md`)
- SS cardinality search → Quarter sums: sets cardinalities (evidence: `README.md`)
- Quarter sums → Heap pair search: feeds sorted streams (evidence: `README.md`)
- SS cardinality search → GPU quarter sorting: optionally sorts quarters (evidence: `README.md`)
- Heap pair search → Pair bookkeeping: records matching pairs (evidence: `src/main.cpp`)
- TER pipeline → Verified solution: returns verified result (evidence: `README.md`)
- Heap pair search → Verified solution: returns verified result (evidence: `README.md`)
- Verified solution → Zero-sum swap BFS: seeds exploration (evidence: `README.md`)
- Verified solution → Solution files: writes bitstring (evidence: `README.md`)
- TER pipeline → Phase profiler: profiles phases (evidence: `src/ter_solver.cpp`)