# ai4eps/gamma architecture

> Architecture diagram of the GitHub repository ai4eps/gamma, 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/ai4eps/gamma
- Repository: https://github.com/ai4eps/gamma

## Overview

GaMMA associates seismic phase picks with earthquake events, returning event locations and pick assignments. Its main runtime path normalizes picks and station metadata, optionally segments picks with DBSCAN, fits a seismic-aware Gaussian mixture, and filters candidate events before producing a catalog. The package also supports amplitude-based estimates and uniform or 1D eikonal travel-time models. The FastAPI adapter is sampled; several internal details and documented integrations are not, so uncertain wiring is omitted.

Main entry points: [`gamma/utils.py`](https://github.com/ai4eps/gamma/blob/main/gamma/utils.py) (Association orchestrator), [`gamma/_gaussian_mixture.py`](https://github.com/ai4eps/gamma/blob/main/gamma/_gaussian_mixture.py) (Gaussian mixture), [`gamma/_bayesian_mixture.py`](https://github.com/ai4eps/gamma/blob/main/gamma/_bayesian_mixture.py) (Bayesian mixture), [`app.py`](https://github.com/ai4eps/gamma/blob/main/app.py) (FastAPI adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Entry points"]
  node_api["FastAPI adapter<br/>[app.py]"]
  node_public_api["Package exports<br/>[__init__.py]"]
end

subgraph group_association["Association workflow"]
  node_association["Association orchestrator<br/>[utils.py]"]
  node_segmentation["DBSCAN segmentation<br/>[utils.py]"]
  node_event_filter["Event filtering<br/>[utils.py]"]
end

subgraph group_models["Mixture models"]
  node_gmm["Gaussian mixture"]
  node_bgmm["Bayesian mixture"]
  node_mixture_base["EM base<br/>[_base.py]"]
end

subgraph group_seismic["Seismic calculations"]
  node_seismic_ops["Travel-time and location<br/>[seismic_ops.py]"]
end

node_user(("API user"))
node_python_caller(("Python caller"))
node_phase_data["Picks and stations"]
node_catalog["Events and assignments"]
node_scikit_learn["scikit-learn"]
node_scientific_stack["NumPy and SciPy"]

node_user -->|"submits picks"| node_api
node_phase_data -->|"provides input"| node_api
node_api -->|"calls association"| node_association
node_api -->|"returns results"| node_catalog
node_python_caller -->|"imports models"| node_public_api
node_python_caller -->|"calls association"| node_association
node_association -->|"segments picks"| node_segmentation
node_association -->|"fits model"| node_gmm
node_association -->|"fits model"| node_bgmm
node_association -->|"filters candidates"| node_event_filter
node_association -->|"initializes travel model"| node_seismic_ops
node_event_filter -->|"emits events and assignments"| node_catalog
node_gmm -->|"inherits"| node_mixture_base
node_bgmm -->|"inherits"| node_mixture_base
node_bgmm -->|"uses Gaussian helpers"| node_gmm
node_gmm -->|"optimizes locations"| node_seismic_ops
node_gmm -->|"uses utilities"| node_scikit_learn
node_bgmm -->|"uses utilities"| node_scikit_learn
node_mixture_base -->|"uses estimator utilities"| node_scikit_learn
node_seismic_ops -->|"computes travel times"| node_scientific_stack

click node_api "https://github.com/ai4eps/gamma/blob/main/app.py"
click node_public_api "https://github.com/ai4eps/gamma/blob/main/gamma/__init__.py"
click node_association "https://github.com/ai4eps/gamma/blob/main/gamma/utils.py"
click node_segmentation "https://github.com/ai4eps/gamma/blob/main/gamma/utils.py"
click node_event_filter "https://github.com/ai4eps/gamma/blob/main/gamma/utils.py"
click node_gmm "https://github.com/ai4eps/gamma/blob/main/gamma/_gaussian_mixture.py"
click node_bgmm "https://github.com/ai4eps/gamma/blob/main/gamma/_bayesian_mixture.py"
click node_mixture_base "https://github.com/ai4eps/gamma/blob/main/gamma/_base.py"
click node_seismic_ops "https://github.com/ai4eps/gamma/blob/main/gamma/seismic_ops.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_api,node_public_api,node_user toneBlue
class node_association,node_segmentation,node_event_filter toneAmber
class node_gmm,node_bgmm,node_mixture_base toneMint
class node_seismic_ops toneRose
class node_python_caller,node_phase_data,node_catalog,node_scikit_learn,node_scientific_stack toneIndigo
```

## Components

### Entry points

- [FastAPI adapter](https://github.com/ai4eps/gamma/blob/main/app.py): `app.py`
- [Package exports](https://github.com/ai4eps/gamma/blob/main/gamma/__init__.py): `gamma/__init__.py`

### Association workflow

- [Association orchestrator](https://github.com/ai4eps/gamma/blob/main/gamma/utils.py): `gamma/utils.py`
- [DBSCAN segmentation](https://github.com/ai4eps/gamma/blob/main/gamma/utils.py): `gamma/utils.py`
- [Event filtering](https://github.com/ai4eps/gamma/blob/main/gamma/utils.py): `gamma/utils.py`

### Mixture models

- [Gaussian mixture](https://github.com/ai4eps/gamma/blob/main/gamma/_gaussian_mixture.py): `gamma/_gaussian_mixture.py`
- [Bayesian mixture](https://github.com/ai4eps/gamma/blob/main/gamma/_bayesian_mixture.py): `gamma/_bayesian_mixture.py`
- [EM base](https://github.com/ai4eps/gamma/blob/main/gamma/_base.py): `gamma/_base.py`

### Seismic calculations

- [Travel-time and location](https://github.com/ai4eps/gamma/blob/main/gamma/seismic_ops.py): `gamma/seismic_ops.py`

### Other components

- **API user**
- **Python caller**
- **Picks and stations**
- **Events and assignments**
- **scikit-learn**
- **NumPy and SciPy**

## Connections

- API user → FastAPI adapter: submits picks
- Picks and stations → FastAPI adapter: provides input
- FastAPI adapter → Association orchestrator: calls association
- FastAPI adapter → Events and assignments: returns results
- Python caller → Package exports: imports models
- Python caller → Association orchestrator: calls association
- Association orchestrator → DBSCAN segmentation: segments picks
- Association orchestrator → Gaussian mixture: fits model
- Association orchestrator → Bayesian mixture: fits model
- Association orchestrator → Event filtering: filters candidates
- Association orchestrator → Travel-time and location: initializes travel model
- Event filtering → Events and assignments: emits events and assignments
- Gaussian mixture → EM base: inherits
- Bayesian mixture → EM base: inherits
- Bayesian mixture → Gaussian mixture: uses Gaussian helpers
- Gaussian mixture → Travel-time and location: optimizes locations
- Gaussian mixture → scikit-learn: uses utilities
- Bayesian mixture → scikit-learn: uses utilities
- EM base → scikit-learn: uses estimator utilities
- Travel-time and location → NumPy and SciPy: computes travel times