How gwkokab/gwkokab works
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