# yonko-sid/rutherford-experiment-simulation architecture

> Architecture diagram of the GitHub repository yonko-sid/rutherford-experiment-simulation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yonko-sid/rutherford-experiment-simulation
- Repository: https://github.com/yonko-sid/rutherford-experiment-simulation

## Overview

#### Purpose and executable entry point
This is a native C++20/SDL3 desktop simulation of Rutherford gold-foil scattering. It visually launches alpha particles toward a central gold-atom column, numerically applies Coulomb repulsion, and renders deflected trajectories. The application entry point, SDL initialization, event loop, camera behavior, and rendering reside in `rutherford.cpp`.

#### Build and runtime boundary
CMake builds one SDL3-linked executable from the simulation/UI and physics translation units. The project targets C++20 and requires SDL3 for windowing, input, and 2D rendering. Build configuration is in `Cmakelists.txt`; it includes an MSYS2-oriented prefix-path assumption that may need adjustment outside Windows.

#### Physics domain model
The physics API defines physical constants, particle/nucleus state, and simulation-facing declarations in `physics.h`. It models positively charged alpha particles and gold nuclei using real-scale quantities: charge, mass, nuclear radii, particle speed, detector boundary, and Coulomb’s constant.

#### Force calculation and collision boundary
`physics.cpp` is the numerical core. For each alpha/nucleus interaction it calculates Coulomb repulsion from separation distance. A minimum separation equal to the combined nuclear/alpha radii clamps close approaches, preventing singular forces and numerical tunneling through a nucleus. Gold nuclei act as fixed scattering centers; alpha particles are the moving entities.

#### Time integration and lifecycle
The renderer-driven frame loop in `rutherford.cpp` advances active particles through the physics module in `physics.cpp`. Each simulation frame is split into 1,000 micro-steps using a tuned femtosecond-scale timestep, prioritizing stability at high alpha velocity and femtometer nuclear distances. Particles exceeding roughly 1.05 times the detector radius are removed to bound memory growth.

#### Input, control flow, and visualization
SDL events in `rutherford.cpp` control particle emission, pausing, camera pan/zoom, view tilt, reset, and exit. Pause gates physics advancement but leaves event processing and rendering active, enabling inspection of existing trajectories. The rendering layer converts the physical scene—foil/nuclei, detector boundary, and particle trajectories—into screen-space using camera state.

#### Primary flow
1. SDL setup and scene initialization occur in `rutherford.cpp`.
2. User input emits alpha particles or changes simulation/camera state.
3. When unpaused, `rutherford.cpp` invokes physics updates from `physics.cpp`.
4. Physics applies sub-stepped Coulomb acceleration, clamping, integration, and out-of-bound cleanup.
5. The updated particle collection is rendered through SDL3 each frame.

Main entry points: [`rutherford.cpp`](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp) (Application entry & frame loop), [`physics.h`](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.h) (Alpha particles), [`physics.cpp`](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.cpp) (Physics update), [`Cmakelists.txt`](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/Cmakelists.txt) (CMake build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["SDL Application"]
  node_main["Application entry &amp; frame loop<br/>simulation controller<br/>[rutherford.cpp]"]
  node_events["Input controls<br/>event handling<br/>[rutherford.cpp]"]
  node_scene["Scene state<br/>simulation state<br/>[rutherford.cpp]"]
  node_pause["Pause gate<br/>simulation control<br/>[rutherford.cpp]"]
  node_camera["Camera transform<br/>view state<br/>[rutherford.cpp]"]
  node_renderer["SDL scene renderer<br/>visualization<br/>[rutherford.cpp]"]
end

subgraph group_physics["Physics Engine"]
  node_api["Physics API &amp; model<br/>domain declarations<br/>[physics.h]"]
  node_particles["Alpha particles<br/>moving entities<br/>[physics.h]"]
  node_nuclei["Gold nuclei<br/>fixed scatterers<br/>[physics.h]"]
  node_update["Physics update<br/>numerical simulation<br/>[physics.cpp]"]
  node_force["Coulomb force &amp; clamp<br/>force calculation<br/>[physics.cpp]"]
  node_integrator["Micro-step integration<br/>time integration<br/>[physics.cpp]"]
  node_cleanup["Detector-bound cleanup<br/>particle lifecycle<br/>[physics.cpp]"]
end

subgraph group_build["Build &amp; Runtime"]
  node_cmake["CMake build<br/>build configuration<br/>[Cmakelists.txt]"]
  node_sdl3{{"SDL3<br/>desktop runtime"}}
end

node_cmake -->|"builds"| node_main
node_cmake -->|"builds"| node_update
node_cmake -->|"links"| node_sdl3
node_main -->|"initializes and uses"| node_sdl3
node_main -->|"processes"| node_events
node_events -->|"changes"| node_scene
node_events -->|"toggles"| node_pause
node_events -->|"controls"| node_camera
node_events -->|"emits"| node_particles
node_main -->|"checks"| node_pause
node_pause -->|"gates advancement"| node_update
node_main -->|"advances each frame"| node_update
node_api -->|"declares interface and state"| node_update
node_update -->|"calculates"| node_force
node_force -->|"supplies acceleration"| node_integrator
node_integrator -->|"updates position and velocity"| node_particles
node_nuclei -->|"repels"| node_force
node_particles -->|"interacts with"| node_force
node_integrator -->|"passes updated particles"| node_cleanup
node_cleanup -->|"removes out-of-bounds"| node_particles
node_main -->|"renders each frame"| node_renderer
node_scene -->|"provides physical scene"| node_renderer
node_camera -->|"provides screen transform"| node_renderer
node_particles -->|"draws trajectories"| node_renderer
node_nuclei -->|"draws foil"| node_renderer

click node_cmake "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/Cmakelists.txt"
click node_main "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp"
click node_events "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp"
click node_scene "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp"
click node_pause "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp"
click node_camera "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp"
click node_renderer "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp"
click node_api "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.h"
click node_particles "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.h"
click node_nuclei "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.h"
click node_update "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.cpp"
click node_force "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.cpp"
click node_integrator "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.cpp"
click node_cleanup "https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.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_main,node_events,node_scene,node_pause,node_camera,node_renderer toneBlue
class node_api,node_particles,node_nuclei,node_update,node_force,node_integrator,node_cleanup toneAmber
class node_cmake,node_sdl3 toneMint
```

## Components

### SDL Application

- [Application entry & frame loop](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp): simulation controller · Owns SDL setup, events, frame advancement, and rendering. · `rutherford.cpp`
- [Input controls](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp): event handling · Controls emission, pause, reset, exit, and camera state. · `rutherford.cpp`
- [Scene state](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp): simulation state · Contains particles, nuclei, detector, and camera state. · `rutherford.cpp`
- [Pause gate](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp): simulation control · Stops physics advancement while events and rendering continue. · `rutherford.cpp`
- [Camera transform](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp): view state · Maps physical coordinates to screen space with pan, zoom, and tilt. · `rutherford.cpp`
- [SDL scene renderer](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/rutherford.cpp): visualization · Draws foil nuclei, detector boundary, and trajectories. · `rutherford.cpp`

### Physics Engine

- [Physics API & model](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.h): domain declarations · Defines constants plus alpha-particle and gold-nucleus state. · `physics.h`
- [Alpha particles](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.h): moving entities · Positively charged particles launched toward the foil. · `physics.h`
- [Gold nuclei](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.h): fixed scatterers · Fixed positively charged Coulomb centers. · `physics.h`
- [Physics update](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.cpp): numerical simulation · Advances active alpha particles against fixed nuclei. · `physics.cpp`
- [Coulomb force & clamp](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.cpp): force calculation · Clamps separation to combined radii to avoid singular forces. · `physics.cpp`
- [Micro-step integration](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.cpp): time integration · Uses 1,000 femtosecond-scale sub-steps per frame. · `physics.cpp`
- [Detector-bound cleanup](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/physics.cpp): particle lifecycle · Removes particles beyond about 1.05 detector radii. · `physics.cpp`

### Build & Runtime

- [CMake build](https://github.com/yonko-sid/rutherford-experiment-simulation/blob/main/Cmakelists.txt): build configuration · Builds the C++20 SDL3 executable. · `Cmakelists.txt`
- **SDL3**: desktop runtime · Provides windowing, events, and 2D rendering.

## Connections

- CMake build → Application entry & frame loop: builds
- CMake build → Physics update: builds
- CMake build → SDL3: links
- Application entry & frame loop → SDL3: initializes and uses
- Application entry & frame loop → Input controls: processes
- Input controls → Scene state: changes
- Input controls → Pause gate: toggles
- Input controls → Camera transform: controls
- Input controls → Alpha particles: emits
- Application entry & frame loop → Pause gate: checks
- Pause gate → Physics update: gates advancement
- Application entry & frame loop → Physics update: advances each frame
- Physics API & model → Physics update: declares interface and state
- Physics update → Coulomb force & clamp: calculates
- Coulomb force & clamp → Micro-step integration: supplies acceleration
- Micro-step integration → Alpha particles: updates position and velocity
- Gold nuclei → Coulomb force & clamp: repels
- Alpha particles → Coulomb force & clamp: interacts with
- Micro-step integration → Detector-bound cleanup: passes updated particles
- Detector-bound cleanup → Alpha particles: removes out-of-bounds
- Application entry & frame loop → SDL scene renderer: renders each frame
- Scene state → SDL scene renderer: provides physical scene
- Camera transform → SDL scene renderer: provides screen transform
- Alpha particles → SDL scene renderer: draws trajectories
- Gold nuclei → SDL scene renderer: draws foil