# gwkokab/gwkokab architecture

> Architecture diagram of the GitHub repository gwkokab/gwkokab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gwkokab/gwkokab
- Repository: https://github.com/gwkokab/gwkokab

## Overview

##### Project type and purpose
- This is an open-source Python toolkit (GWKokab) for gravitational-wave population inference.
- It provides both a programmatic API (via the `src/gwkokab` and `src/kokab` packages) and a set of CLI commands (`src/cli_gwkokab`) to run inference, compute likelihoods, sample models, and produce visualizations using JAX under the hood.

##### File structure
- Top-level directories:
- `.github`, CI/CD workflows and issue/pull‐request templates
- `docs` + `README.md`: documentation site
- `src/cli_gwkokab`: command-line front-end
- `src/gwkokab`: core inference engine (cosmology, models, inference, population, utils, vts)
- `src/kokab`: higher-level model wrappers and utility parsers
- `tests`: unit and integration tests
- Build & deployment files: `pyproject.toml`, `makefile`, `readthedocs.yml`, `pre-commit` config, `github/workflows` for CI and publishing
- Patterns: modular package layout, separation of CLI vs. core logic, layered subpackages for models, utilities, and inference

##### README for additional insights
- Built on JAX for high-performance numerical computation
- Parametric population models, flexible inference pipelines
- Intended to be imported in Python scripts or used via CLI, with integration into existing JAX workflows

a. Main components
1. User Interfaces
– CLI layer (`cli_gwkokab`)
– Programmatic API (import `gwkokab` and `kokab` packages)
2. Core Engine
– Inference module (`gwkokab.inference`): likelihoods, sampler orchestration
– Models module (`gwkokab.models` + `kokab` wrappers): parametric population definitions
– Cosmology module (`gwkokab.cosmology`)
– Population module (`gwkokab.population`): factory and utilities
– VTS module (`gwkokab.vts`): volume-time sensitivity estimation
– Utilities (`gwkokab.utils`, `kokab.utils`)
3. External Libraries & Data
– JAX (computation, auto-diff)
– NumPy/Scipy (numerical routines)
– HDF5 weights (`weights_HLV_O3.hdf5`) and scaler JSON
4. Supporting Infrastructure
– Documentation pipeline (`docs/`, ReadTheDocs)
– CI/CD (GitHub Actions)
– Testing (`tests/`)

b. Relationships & data flows
- User invokes CLI or imports API →
CLI parses arguments →
Core engine loads data and model parameters →
Inference module dispatches likelihood evaluations to JAX →
JAX kernels call model functions and cosmology utilities →
Sampler produces posterior samples →
Results passed back to CLI for plotting or returned to caller →
- VTS routines load precomputed weights/scaler files →
compute sensitivity volumes →
feed into population likelihood

c. Architectural patterns & design principles
- Layered modular design: clear separation between interface, core logic, models, utilities
- Dependency injection: models and likelihoods configured and passed into inference routines
- Extensibility: each new population model lives in its own subpackage under `models` or `kokab`
- Data-flow orientation: JAX functional kernels for stateless, vectorized computation

d. Key technologies & frameworks
- JAX for tensor operations and automatic differentiation
- CLI built with native Python argument parsing
- HDF5/JSON for precomputed data inputs
- ReadTheDocs + Sphinx for documentation
- GitHub Actions for CI, publishing to PyPI

##### Elements
- Interfaces (blue)
- Core logic (green)
- Data/config files (orange)
- External libraries (yellow)

##### Detailing is key
- CI/docs/test pipeline separately: GitHub → Actions → PyPI/docs site
- Avoid over-simplification: highlight where new models plug in, where JAX computations occur, and how outputs return to the user

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Interface Layer
    subgraph "User Interfaces"
        direction TB
        CLI["CLI Layer"]:::interface
        API_Core["Programmatic API (core package)"]:::interface
        API_Wrap["Programmatic API (model wrappers)"]:::interface
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        Inference["Inference Module"]:::core
        Models["Models Module"]:::core
        Cosmology["Cosmology Module"]:::core
        Population["Population Module"]:::core
        VTS["VTS Module"]:::core
        Utils_Core["Core Utilities"]:::core
        Utils_Kokab["Kokab Utilities"]:::core
    end

    %% External Libraries & Data
    subgraph "External Dependencies"
        direction TB
        JAX["JAX"]:::external
        NumPy["NumPy/Scipy"]:::external
    end

    subgraph "Precomputed Data Files"
        direction TB
        Weights["weights_HLV_O3.hdf5"]:::data
        Scaler["scaler_HLV_O3.json"]:::data
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Docs["Documentation Pipeline"]:::infra
        CI["CI/CD Workflows"]:::infra
        Tests["Testing Suite"]:::infra
    end

    %% Data Flows
    CLI -->|"parse args"| Inference
    API_Core -->|"import modules"| Inference
    API_Wrap -->|"import wrappers"| Models

    Inference -->|"dispatch likelihoods"| JAX
    Models -->|calls| JAX
    Cosmology -->|utils| JAX
    Utils_Core -->|helpers| Inference
    Utils_Kokab -->|parsers| Models

    VTS -->|"load weights and scaler"| Weights
    VTS -->|"load weights and scaler"| Scaler
    Weights -->|"sensitivity data"| Population
    Scaler -->|"scaling factors"| Population
    Population -->|"prior factory"| Inference

    JAX -->|"posterior samples"| Inference
    Inference -->|"results"| CLI
    Inference -->|"results"| API_Core

    %% Infrastructure flows
    CI -->|runs tests & build| Tests
    CI -->|build docs| Docs

    %% Click Events
    click CLI "https://github.com/gwkokab/gwkokab/tree/main/src/cli_gwkokab/"
    click API_Core "https://github.com/gwkokab/gwkokab/tree/main/src/gwkokab/"
    click API_Wrap "https://github.com/gwkokab/gwkokab/tree/main/src/kokab/"
    click Inference "https://github.com/gwkokab/gwkokab/tree/main/src/gwkokab/inference/"
    click Models "https://github.com/gwkokab/gwkokab/tree/main/src/gwkokab/models/"
    click Cosmology "https://github.com/gwkokab/gwkokab/tree/main/src/gwkokab/cosmology/"
    click Population "https://github.com/gwkokab/gwkokab/tree/main/src/gwkokab/population/"
    click VTS "https://github.com/gwkokab/gwkokab/tree/main/src/gwkokab/vts/"
    click Utils_Core "https://github.com/gwkokab/gwkokab/tree/main/src/gwkokab/utils/"
    click Utils_Kokab "https://github.com/gwkokab/gwkokab/tree/main/src/kokab/utils/"
    click Weights "https://github.com/gwkokab/gwkokab/blob/main/src/gwkokab/vts/_pdet/weights_HLV_O3.hdf5"
    click Scaler "https://github.com/gwkokab/gwkokab/blob/main/src/gwkokab/vts/_pdet/scaler_HLV_O3.json"
    click Docs "https://github.com/gwkokab/gwkokab/tree/main/docs/"
    click Docs "https://github.com/gwkokab/gwkokab/blob/main/.readthedocs.yml"
    click CI "https://github.com/gwkokab/gwkokab/tree/main/.github/workflows/"
    click Tests "https://github.com/gwkokab/gwkokab/tree/main/tests/"

    %% Styles
    classDef interface fill:#D0E6FF,stroke:#0366D6,stroke-width:1px
    classDef core fill:#E6F4EA,stroke:#238636,stroke-width:1px
    classDef external fill:#FFF5B1,stroke:#735C0F,stroke-width:1px
    classDef data fill:#FFEFD5,stroke:#DE7500,stroke-width:1px
    classDef infra fill:#EDEBF1,stroke:#5A4175,stroke-width:1px
```
