gwlss — Gravitational Waves × Large Scale Structure

A modular Python pipeline for cross-correlating gravitational wave catalogs with large-scale structure observables (cosmic voids, stellar metallicity, dark matter maps).

Developed in the context of the QDCB research project (Quantum Decoherence as Dimensional Coherence Bridge) but fully general and theory-agnostic.

---

What it does

GW catalogs     ──┐
(GWTC-3/4/5)     ├──► Filters ──► Probe ──► Stats ──► Report
LSS catalogs    ──┘
(voids, APOGEE,
 DES kappa maps)

Available probes:

• P5_void_border — BBH excess at cosmic void boundaries (DESIVAST DR1)
• P1_metallicity — Correlation between DM density and stellar metallicity (DES + APOGEE)

Key features:

• Automatic footprint detection and filtering
• HEALPix NUNIQ sky map extraction (GWTC-4 PE data release)
• Configurable via YAML — no code needed for new analyses
• Monte Carlo baseline with configurable parameters
• PDF + CSV reports

---

Installation

git clone https://github.com/nbaillif/gwlss.git
cd gwlss
pip install -e .

Dependencies:

astropy >= 5.0
astropy-healpix >= 1.0
numpy >= 1.24
scipy >= 1.10
matplotlib >= 3.7
pyyaml >= 6.0
tqdm >= 4.65

---

Quickstart — P5 (BBH at void boundaries)

# Download data (first time only)
python -m gwlss download --probe p5

# Run analysis
python -m gwlss run configs/p5_default.yaml

# Output: results/p5_report.pdf + results/p5_results.csv

---

Quickstart — P1 (DM × metallicity)

python -m gwlss download --probe p1
python -m gwlss run configs/p1_default.yaml

---

Custom configuration

# my_analysis.yaml
probe: void_border

catalogs:
  gw: GWTC-4                    # GWTC-3 | GWTC-4 | custom
  voids: DESIVAST_DR1            # DESIVAST_DR1 | SDSS_DR7 | custom

filters:
  z_max: 0.24                    # redshift cutoff
  footprint: auto                # auto | manual | none
  mass_min: 10                   # minimum total mass (solar masses)
  border_mpc: 20                 # void boundary thickness (Mpc)
  border_mpc_range: [5, 100]     # scan range (optional)

stats:
  monte_carlo: 10000
  seed: 42
  n_jobs: 4                      # parallel MC

output:
  dir: results/
  plots: true
  report: pdf
  verbose: true

python -m gwlss run my_analysis.yaml

---

Project structure

gwlss/
├── gwlss/
│   ├── catalogs/      — data loaders (GWTC, voids, stellar)
│   ├── filters/       — redshift, footprint, mass, sky
│   ├── probes/        — P5 void border, P1 metallicity
│   ├── stats/         — Monte Carlo, correlation, power
│   ├── viz/           — skymap, radial profile, summary
│   └── cli.py         — command-line interface
├── configs/           — YAML templates
├── notebooks/         — Jupyter examples
├── tests/             — unit tests
└── docs/              — methodology documentation

---

Results — P5 v5 (March 2026)

Version	N	Footprint	Excess	z-score	p-value
v3 GWTC-3, real pos.	18	✗	0.42×	-1.98σ	0.990
v4 GWTC-3+4, random	32	✗	0.55×	-1.61σ	0.973
v5a GWTC-3+4, real	24	✗	0.67×	-0.62σ	0.823
v5b GWTC-3+4, real	13	✓	1.32×	+0.42σ	0.466

With footprint correction applied, the signal moves in the predicted direction. GW231223_202619 shows simultaneous association with 3 void boundaries.

---

Citation

@misc{baillif2026gwlss,
  author = {Baillif, Novan},
  title  = {gwlss: Gravitational Waves × Large Scale Structure Pipeline},
  year   = {2026},
  url    = {https://github.com/nbaillif/gwlss}
}

---

License

MIT — Novan Baillif, Saint-Paul La Réunion, 2026