# fortune12376/monte-carlo-electron-avalanche architecture

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

- Interactive diagram: https://gitdiagram.com/fortune12376/monte-carlo-electron-avalanche
- Repository: https://github.com/fortune12376/monte-carlo-electron-avalanche

## Overview

This is a scientific Monte Carlo electron-avalanche simulator for helium in a cylindrical proportional counter. A user selects voltage, starting radius, seed, electron cap, and backend in the Streamlit app, runs transport, then inspects avalanche, chamber, 3D, and cross-section views. The Python/Numba and C99 engines implement the model; the ctypes wrapper adapts C results to the shared Python result interface. The C engine also uses helium physics functions and dynamic storage. Unsampled details are represented only where the README documents them.

Main entry points: [`app.py`](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/app.py) (Controls and results UI), [`simulation.py`](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/simulation.py) (Numba transport engine), [`simulation_c.py`](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/simulation_c.py) (ctypes adapter), [`csrc/simulation.c`](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/csrc/simulation.c) (C transport engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interactive interface"]
  node_app["Controls and results UI<br/>[app.py]"]
  node_views["Scientific visualizations<br/>[app.py]"]
end

subgraph group_python["Python backend"]
  node_pyengine["Numba transport engine<br/>[simulation.py]"]
  node_pyphysics["Python cross-section model<br/>[simulation.py]"]
end

subgraph group_cbackend["C99 backend"]
  node_wrapper["ctypes adapter<br/>[simulation_c.py]"]
  node_cengine["C transport engine<br/>[simulation.c]"]
  node_cphysics["C helium physics<br/>[physics.c]"]
  node_storage["Electron and point storage<br/>[simulation.c]"]
end

subgraph group_shared["Shared model contract"]
  node_result["Simulation result interface<br/>[simulation.py]"]
end

node_user(("Simulator user"))

node_user -->|"sets parameters"| node_app
node_app -->|"runs Numba"| node_pyengine
node_app -->|"runs C99"| node_wrapper
node_pyengine -->|"returns result"| node_result
node_wrapper -->|"calls native"| node_cengine
node_wrapper -->|"builds result"| node_result
node_cengine -->|"calls physics"| node_cphysics
node_cengine -->|"uses storage"| node_storage
node_app -->|"renders views"| node_views
node_app -->|"reads metrics"| node_result
node_pyengine -.->|"uses cross sections"| node_pyphysics

click node_app "https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/app.py"
click node_views "https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/app.py"
click node_pyengine "https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/simulation.py"
click node_pyphysics "https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/simulation.py"
click node_wrapper "https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/simulation_c.py"
click node_cengine "https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/csrc/simulation.c"
click node_cphysics "https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/csrc/physics.c"
click node_storage "https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/csrc/simulation.c"
click node_result "https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/simulation.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_app,node_views,node_user toneBlue
class node_pyengine,node_pyphysics toneAmber
class node_wrapper,node_cengine,node_cphysics,node_storage toneMint
class node_result toneRose
```

## Components

### Interactive interface

- [Controls and results UI](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/app.py): `app.py`
- [Scientific visualizations](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/app.py): `app.py`

### Python backend

- [Numba transport engine](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/simulation.py): `simulation.py`
- [Python cross-section model](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/simulation.py): `simulation.py`

### C99 backend

- [ctypes adapter](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/simulation_c.py): `simulation_c.py`
- [C transport engine](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/csrc/simulation.c): `csrc/simulation.c`
- [C helium physics](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/csrc/physics.c): `csrc/physics.c`
- [Electron and point storage](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/csrc/simulation.c): `csrc/simulation.c`

### Shared model contract

- [Simulation result interface](https://github.com/fortune12376/monte-carlo-electron-avalanche/blob/main/simulation.py): `simulation.py`

### Other components

- **Simulator user**

## Connections

- Simulator user → Controls and results UI: sets parameters (evidence: `app.py`)
- Controls and results UI → Numba transport engine: runs Numba (evidence: `app.py`)
- Controls and results UI → ctypes adapter: runs C99 (evidence: `app.py`)
- Numba transport engine → Simulation result interface: returns result (evidence: `simulation.py`)
- ctypes adapter → C transport engine: calls native (evidence: `simulation_c.py`)
- ctypes adapter → Simulation result interface: builds result (evidence: `simulation_c.py`)
- C transport engine → C helium physics: calls physics (evidence: `csrc/simulation.c`)
- C transport engine → Electron and point storage: uses storage (evidence: `csrc/simulation.c`)
- Controls and results UI → Scientific visualizations: renders views (evidence: `app.py`)
- Controls and results UI → Simulation result interface: reads metrics (evidence: `app.py`)
- Numba transport engine → Python cross-section model: uses cross sections (evidence: `simulation.py`)