# arima-ch/python-simulations architecture

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

- Interactive diagram: https://gitdiagram.com/arima-ch/python-simulations
- Repository: https://github.com/arima-ch/python-simulations

## Overview

The repository contains two independent runnable physics experiments: a Pygame particle CPU-load test and a cinematic pyglet/ModernGL n-body visualization. The particle workflow initializes a visible simulation and optional worker processes, advances particle collisions, and reports frame counts. The n-body workflow spawns particles, computes gravitational forces with a Barnes–Hut tree, integrates motion, and renders trails and glow. The sampled excerpts do not show all n-body setup and rendering details, so uncertain internal wiring is omitted.

Main entry points: [`nbody_cinematic.py`](https://github.com/arima-ch/python-simulations/blob/main/nbody_cinematic.py) (N-body app), [`particle_simulation.py`](https://github.com/arima-ch/python-simulations/blob/main/particle_simulation.py) (Simulation runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_particle["Particle CPU Test"]
  node_particle_app["Simulation runner"]
  node_worker_pool["Worker pool"]
  node_worker["CPU worker"]
end

subgraph group_nbody["N-Body Visualization"]
  node_nbody_app["N-body app<br/>[nbody_cinematic.py]"]
  node_particle_state["Particle state<br/>[nbody_cinematic.py]"]
end

subgraph group_physics["Physics Core"]
  node_particle_step["Particle step"]
  node_barnes_hut["Barnes-Hut tree<br/>[nbody_cinematic.py]"]
  node_body["Body model<br/>[nbody_cinematic.py]"]
end

node_user(("User"))
node_pygame["Pygame display"]
node_pyglet["Pyglet window"]
node_moderngl["ModernGL renderer"]
node_screen(("Rendered display"))

node_user -->|"runs"| node_particle_app
node_particle_app -->|"starts workers"| node_worker_pool
node_worker_pool -->|"dispatches"| node_worker
node_worker -->|"advances state"| node_particle_step
node_particle_app -->|"advances state"| node_particle_step
node_particle_app -->|"draws particles"| node_pygame
node_user -->|"runs"| node_nbody_app
node_nbody_app -->|"creates window"| node_pyglet
node_nbody_app -->|"creates context"| node_moderngl
node_nbody_app -->|"updates particles"| node_particle_state
node_nbody_app -->|"computes forces"| node_barnes_hut
node_barnes_hut -->|"evaluates force"| node_body
node_moderngl -->|"renders frames"| node_screen

click node_particle_app "https://github.com/arima-ch/python-simulations/blob/main/particle_simulation.py"
click node_worker_pool "https://github.com/arima-ch/python-simulations/blob/main/particle_simulation.py"
click node_worker "https://github.com/arima-ch/python-simulations/blob/main/particle_simulation.py"
click node_particle_step "https://github.com/arima-ch/python-simulations/blob/main/particle_simulation.py"
click node_nbody_app "https://github.com/arima-ch/python-simulations/blob/main/nbody_cinematic.py"
click node_particle_state "https://github.com/arima-ch/python-simulations/blob/main/nbody_cinematic.py"
click node_barnes_hut "https://github.com/arima-ch/python-simulations/blob/main/nbody_cinematic.py"
click node_body "https://github.com/arima-ch/python-simulations/blob/main/nbody_cinematic.py"

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_particle_app,node_worker_pool,node_worker,node_user toneBlue
class node_nbody_app,node_particle_state toneAmber
class node_particle_step,node_barnes_hut,node_body toneMint
class node_pygame,node_pyglet,node_moderngl,node_screen toneIndigo
```

## Components

### Particle CPU Test

- [Simulation runner](https://github.com/arima-ch/python-simulations/blob/main/particle_simulation.py): `particle_simulation.py`
- [Worker pool](https://github.com/arima-ch/python-simulations/blob/main/particle_simulation.py): `particle_simulation.py`
- [CPU worker](https://github.com/arima-ch/python-simulations/blob/main/particle_simulation.py): `particle_simulation.py`

### N-Body Visualization

- [N-body app](https://github.com/arima-ch/python-simulations/blob/main/nbody_cinematic.py): `nbody_cinematic.py`
- [Particle state](https://github.com/arima-ch/python-simulations/blob/main/nbody_cinematic.py): `nbody_cinematic.py`

### Physics Core

- [Particle step](https://github.com/arima-ch/python-simulations/blob/main/particle_simulation.py): `particle_simulation.py`
- [Barnes-Hut tree](https://github.com/arima-ch/python-simulations/blob/main/nbody_cinematic.py): `nbody_cinematic.py`
- [Body model](https://github.com/arima-ch/python-simulations/blob/main/nbody_cinematic.py): `nbody_cinematic.py`

### Other components

- **User**
- **Pygame display**
- **Pyglet window**
- **ModernGL renderer**
- **Rendered display**

## Connections

- User → Simulation runner: runs
- Simulation runner → Worker pool: starts workers
- Worker pool → CPU worker: dispatches
- CPU worker → Particle step: advances state
- Simulation runner → Particle step: advances state
- Simulation runner → Pygame display: draws particles
- User → N-body app: runs
- N-body app → Pyglet window: creates window
- N-body app → ModernGL renderer: creates context
- N-body app → Particle state: updates particles
- N-body app → Barnes-Hut tree: computes forces
- Barnes-Hut tree → Body model: evaluates force
- ModernGL renderer → Rendered display: renders frames