# aritrash/atd-sim architecture

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

- Interactive diagram: https://gitdiagram.com/aritrash/atd-sim
- Repository: https://github.com/aritrash/atd-sim

## Overview

ATD-Sim is a C++ terminal laboratory for acoustic time-difference-of-arrival localization. The user selects an audio source and configures a run; the documented workflow propagates the signal to a four-microphone array, estimates pairwise TDOAs, checks physical feasibility, solves for a source position, then validates against truth. An optional Monte Carlo campaign evaluates noisy trials separately. The TUI presents animated chamber, signal diagnostics, and results. README documents capabilities beyond the sampled implementation excerpts, so those links reflect the documented pipeline; detailed runtime dispatch is not fully verifiable here.

Main entry points: [`src/presentation/tui.cpp`](https://github.com/aritrash/atd-sim/blob/main/src/presentation/tui.cpp) (Terminal UI), [`src/simulation/tdoa_estimation.cpp`](https://github.com/aritrash/atd-sim/blob/main/src/simulation/tdoa_estimation.cpp) (GCC-PHAT TDOA), [`src/dsp/waveform.cpp`](https://github.com/aritrash/atd-sim/blob/main/src/dsp/waveform.cpp) (Waveform loading), [`src/simulation/engine.cpp`](https://github.com/aritrash/atd-sim/blob/main/src/simulation/engine.cpp) (Acoustic propagation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and setup"]
  node_picker["File picker<br/>[file_picker.cpp]"]
  node_configuration["Run configuration<br/>[configuration.cpp]"]
  node_waveform["Waveform loading<br/>[waveform.cpp]"]
end

subgraph group_model["Acoustic processing"]
  node_propagation["Acoustic propagation<br/>[engine.cpp]"]
  node_fourier["Fourier transforms<br/>[fourier.cpp]"]
  node_estimation["GCC-PHAT TDOA"]
  node_diagnostics["Signal diagnostics<br/>[diagnostics.hpp]"]
end

subgraph group_evaluation["Localization evaluation"]
  node_feasibility["Physical feasibility<br/>[gauss_newton.cpp]"]
  node_solver["Spherical solver<br/>[gauss_newton.cpp]"]
  node_validation["Result validation<br/>[localization.cpp]"]
  node_montecarlo["Monte Carlo<br/>[monte_carlo.cpp]"]
end

subgraph group_interface["Terminal experience"]
  node_app["Application entry<br/>[main.cpp]"]
  node_tui["Terminal UI<br/>[tui.cpp]"]
  node_animation["Animation engine"]
  node_chamber["Acoustic chamber"]
  node_geometry["Scene rendering<br/>[geometry_scene.cpp]"]
  node_pixels["Pixel rendering<br/>[pixel_renderer.cpp]"]
  node_results["Results presentation<br/>[tui.cpp]"]
  node_terminalcaps["Terminal capabilities<br/>[terminal.cpp]"]
end

node_user(("User"))
node_audio["Audio file"]
node_terminal["Terminal"]
node_ffprobe["ffprobe"]

node_user -->|"starts"| node_app
node_app -->|"launches"| node_tui
node_user -->|"configures run"| node_tui
node_tui -->|"requests source"| node_picker
node_audio -->|"selects"| node_picker
node_picker -->|"provides path"| node_waveform
node_waveform -->|"reads"| node_audio
node_waveform -.->|"probes MP3 metadata"| node_ffprobe
node_user -->|"sets parameters"| node_configuration
node_tui -->|"submits settings"| node_configuration
node_tui -->|"runs simulation"| node_propagation
node_configuration -->|"supplies geometry"| node_propagation
node_waveform -->|"supplies samples"| node_estimation
node_propagation -->|"supplies propagation context"| node_estimation
node_estimation -->|"computes correlations"| node_fourier
node_estimation -->|"provides measured TDOAs"| node_feasibility
node_feasibility -->|"passes valid pairs"| node_solver
node_solver -->|"returns estimate"| node_validation
node_propagation -->|"provides ground truth"| node_validation
node_estimation -->|"provides observed TDOAs"| node_montecarlo
node_validation -->|"provides run outcome"| node_montecarlo
node_estimation -->|"captures curves and envelopes"| node_diagnostics
node_tui -->|"updates run display"| node_animation
node_diagnostics -->|"injects diagnostics"| node_animation
node_animation -->|"renders state"| node_chamber
node_chamber -->|"builds scene"| node_geometry
node_geometry -->|"draws pixels"| node_pixels
node_tui -->|"presents outcome"| node_results
node_validation -->|"supplies position and status"| node_results
node_montecarlo -->|"supplies statistics"| node_results
node_tui -->|"detects capabilities"| node_terminalcaps
node_results -->|"renders pages"| node_terminal
node_chamber -->|"renders animation"| node_terminal

click node_app "https://github.com/aritrash/atd-sim/blob/main/src/main.cpp"
click node_tui "https://github.com/aritrash/atd-sim/blob/main/src/presentation/tui.cpp"
click node_picker "https://github.com/aritrash/atd-sim/blob/main/src/platform/file_picker.cpp"
click node_configuration "https://github.com/aritrash/atd-sim/blob/main/src/core/configuration.cpp"
click node_waveform "https://github.com/aritrash/atd-sim/blob/main/src/dsp/waveform.cpp"
click node_propagation "https://github.com/aritrash/atd-sim/blob/main/src/simulation/engine.cpp"
click node_fourier "https://github.com/aritrash/atd-sim/blob/main/src/dsp/fourier.cpp"
click node_estimation "https://github.com/aritrash/atd-sim/blob/main/src/simulation/tdoa_estimation.cpp"
click node_diagnostics "https://github.com/aritrash/atd-sim/blob/main/include/atdsim/simulation/diagnostics.hpp"
click node_feasibility "https://github.com/aritrash/atd-sim/blob/main/src/localization/gauss_newton.cpp"
click node_solver "https://github.com/aritrash/atd-sim/blob/main/src/localization/gauss_newton.cpp"
click node_validation "https://github.com/aritrash/atd-sim/blob/main/src/localization/localization.cpp"
click node_montecarlo "https://github.com/aritrash/atd-sim/blob/main/src/simulation/monte_carlo.cpp"
click node_animation "https://github.com/aritrash/atd-sim/blob/main/src/presentation/animation_engine.cpp"
click node_chamber "https://github.com/aritrash/atd-sim/blob/main/src/presentation/acoustic_chamber.cpp"
click node_geometry "https://github.com/aritrash/atd-sim/blob/main/src/presentation/geometry_scene.cpp"
click node_pixels "https://github.com/aritrash/atd-sim/blob/main/src/presentation/pixel_renderer.cpp"
click node_results "https://github.com/aritrash/atd-sim/blob/main/src/presentation/tui.cpp"
click node_terminalcaps "https://github.com/aritrash/atd-sim/blob/main/src/platform/terminal.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_picker,node_configuration,node_waveform,node_user toneBlue
class node_propagation,node_fourier,node_estimation,node_diagnostics toneAmber
class node_feasibility,node_solver,node_validation,node_montecarlo toneMint
class node_app,node_tui,node_animation,node_chamber,node_geometry,node_pixels,node_results,node_terminalcaps toneRose
class node_audio,node_terminal,node_ffprobe toneIndigo
```

## Components

### Inputs and setup

- [File picker](https://github.com/aritrash/atd-sim/blob/main/src/platform/file_picker.cpp): `src/platform/file_picker.cpp`
- [Run configuration](https://github.com/aritrash/atd-sim/blob/main/src/core/configuration.cpp): `src/core/configuration.cpp`
- [Waveform loading](https://github.com/aritrash/atd-sim/blob/main/src/dsp/waveform.cpp): `src/dsp/waveform.cpp`

### Acoustic processing

- [Acoustic propagation](https://github.com/aritrash/atd-sim/blob/main/src/simulation/engine.cpp): `src/simulation/engine.cpp`
- [Fourier transforms](https://github.com/aritrash/atd-sim/blob/main/src/dsp/fourier.cpp): `src/dsp/fourier.cpp`
- [GCC-PHAT TDOA](https://github.com/aritrash/atd-sim/blob/main/src/simulation/tdoa_estimation.cpp): `src/simulation/tdoa_estimation.cpp`
- [Signal diagnostics](https://github.com/aritrash/atd-sim/blob/main/include/atdsim/simulation/diagnostics.hpp): `include/atdsim/simulation/diagnostics.hpp`

### Localization evaluation

- [Physical feasibility](https://github.com/aritrash/atd-sim/blob/main/src/localization/gauss_newton.cpp): `src/localization/gauss_newton.cpp`
- [Spherical solver](https://github.com/aritrash/atd-sim/blob/main/src/localization/gauss_newton.cpp): `src/localization/gauss_newton.cpp`
- [Result validation](https://github.com/aritrash/atd-sim/blob/main/src/localization/localization.cpp): `src/localization/localization.cpp`
- [Monte Carlo](https://github.com/aritrash/atd-sim/blob/main/src/simulation/monte_carlo.cpp): `src/simulation/monte_carlo.cpp`

### Terminal experience

- [Application entry](https://github.com/aritrash/atd-sim/blob/main/src/main.cpp): `src/main.cpp`
- [Terminal UI](https://github.com/aritrash/atd-sim/blob/main/src/presentation/tui.cpp): `src/presentation/tui.cpp`
- [Animation engine](https://github.com/aritrash/atd-sim/blob/main/src/presentation/animation_engine.cpp): `src/presentation/animation_engine.cpp`
- [Acoustic chamber](https://github.com/aritrash/atd-sim/blob/main/src/presentation/acoustic_chamber.cpp): `src/presentation/acoustic_chamber.cpp`
- [Scene rendering](https://github.com/aritrash/atd-sim/blob/main/src/presentation/geometry_scene.cpp): `src/presentation/geometry_scene.cpp`
- [Pixel rendering](https://github.com/aritrash/atd-sim/blob/main/src/presentation/pixel_renderer.cpp): `src/presentation/pixel_renderer.cpp`
- [Results presentation](https://github.com/aritrash/atd-sim/blob/main/src/presentation/tui.cpp): `src/presentation/tui.cpp`
- [Terminal capabilities](https://github.com/aritrash/atd-sim/blob/main/src/platform/terminal.cpp): `src/platform/terminal.cpp`

### Other components

- **User**
- **Audio file**
- **Terminal**
- **ffprobe**

## Connections

- User → Application entry: starts
- Application entry → Terminal UI: launches
- User → Terminal UI: configures run
- Terminal UI → File picker: requests source
- Audio file → File picker: selects
- File picker → Waveform loading: provides path
- Waveform loading → Audio file: reads
- Waveform loading → ffprobe: probes MP3 metadata
- User → Run configuration: sets parameters
- Terminal UI → Run configuration: submits settings
- Terminal UI → Acoustic propagation: runs simulation
- Run configuration → Acoustic propagation: supplies geometry
- Waveform loading → GCC-PHAT TDOA: supplies samples
- Acoustic propagation → GCC-PHAT TDOA: supplies propagation context
- GCC-PHAT TDOA → Fourier transforms: computes correlations
- GCC-PHAT TDOA → Physical feasibility: provides measured TDOAs
- Physical feasibility → Spherical solver: passes valid pairs
- Spherical solver → Result validation: returns estimate
- Acoustic propagation → Result validation: provides ground truth
- GCC-PHAT TDOA → Monte Carlo: provides observed TDOAs
- Result validation → Monte Carlo: provides run outcome
- GCC-PHAT TDOA → Signal diagnostics: captures curves and envelopes
- Terminal UI → Animation engine: updates run display
- Signal diagnostics → Animation engine: injects diagnostics
- Animation engine → Acoustic chamber: renders state
- Acoustic chamber → Scene rendering: builds scene
- Scene rendering → Pixel rendering: draws pixels
- Terminal UI → Results presentation: presents outcome
- Result validation → Results presentation: supplies position and status
- Monte Carlo → Results presentation: supplies statistics
- Terminal UI → Terminal capabilities: detects capabilities
- Results presentation → Terminal: renders pages
- Acoustic chamber → Terminal: renders animation