Sage Logo

Getting Started

  • Installation
    • Option A — conda (recommended for GPU clusters)
    • Option B — pip only
    • Verifying the installation
  • Quick Start
    • Getting started
    • Colab tutorials
    • Repository layout
  • Collaboration
    • What we can do together
    • The Sage Team
    • Get in touch
    • Citing Sage
  • Frequently Asked Questions
  • Troubleshooting
  • Hardware & Compute Guide
    • Minimum Requirements
    • Recommended Configurations
      • Development (small-scale experiments)
      • Production (full O3b run)
    • Throughput Estimates
    • Storage Layout
      • Observing Run data download
      • Checkpoint storage
    • Cluster Setup
      • SLURM example
      • Environment modules
    • Tips for Low-VRAM Systems

User Guide

  • Overview
    • How to use this guide
    • Modules
    • Architecture
    • Training pipeline
    • Waveform generation
    • Signal processing
    • Noise handling
  • Configuration Reference
    • Run configuration (config.py)
      • RunCFG
      • DataCFG
    • Signal prior configuration (gwconfig.yaml)
      • variable_params
      • priors
      • constraints
      • waveform_transforms
    • Training graph (train.py)
      • Signal sampler
      • Noise sampler
      • Preprocessor
    • Model and optimisation (train.py)
  • Downloading Data & Priming Sage
    • Getting Segments
      • Listing available detectors and runs
      • Creating a timeline query
    • Cleaning the Timeline
      • Options
      • Why remove events?
      • Inspecting the result
    • Splitting into Mini-Segments
      • Buffer calculation
      • Splitting
      • Sanity check
    • Downloading from GWOSC
      • Key parameters
      • Output files
        • HDF5 structure
        • Binary format
  • Noise Dataset Generation
    • Sampling Noise Batches
      • Single-segment sampler
      • Batched sampler
      • Performance
    • Fiducial PSDs & Recolouring PSDs
      • Setup
      • Estimating segment PSDs
      • Estimating raw (recolouring) PSDs
      • Reading PSD files
      • Spline smoothing
    • Recolouring Noise & Returning FD Batches
      • Setting up the recolouring postprocess
      • Sampling a batch
      • Performance
  • Signal Dataset Generation
    • IMRPhenomD on GPU
      • Parameters
      • Comparison with LALSuite
    • IMRPhenomPv2 on GPU
      • Parameters
      • Setting up the signal sampler
      • Calling the sampler
      • Comparison with LALSuite
  • Whitening Noisy Signals
    • Assembling a noisy batch
    • Loading the fiducial PSDs
    • Whitening
    • Whitening pure noise vs. pure signal
  • Multirate Sampling
    • Initialising the sampler
    • How the bins work
    • Applying multirate sampling
      • Applying to the whitened noisy signal
      • Applying to pure signal
  • Optimal Network SNR Estimation
    • Output shapes
    • SNR-based injection rescaling
  • BBH Parameter Distributions on GPU
    • Available Distributions
      • uniform
      • uniform_angle
      • sin_angle
      • uniform_sky
      • uniform_solidangle
      • uniform_radius
    • Writing gwconfig.yaml
      • Complete reference example
      • Section reference
        • variable_params
        • priors
        • constraints
        • waveform_transforms
    • Sampling Parameters & Plotting Distributions
      • Building the sampler
      • Inspecting the sampler
      • Drawing a large batch
      • Plotting all parameter distributions
      • Normalisation and standardisation
  • On-the-Fly Data Generation Pipeline
    • Signal sampler with SNR rescaling
      • Changing the SNR distribution
    • Noise sampler with recolouring
    • Assembling a full batch manually
    • Controlling randomness and reproducibility
  • Data Transforms
    • Building the preprocessor
    • Applying the preprocessor
    • What each transform does
    • Passing the preprocessor to the training loop
  • Network Architectures
    • Frontend: Multi-Scale 1D CNN
      • ConcatBlockConv5 — the multi-scale block
      • ConvBlock — the per-detector frontend
      • Parameters
      • Weight initialisation
    • Backend: 2D ResNet with CBAM
      • ResNet variants
      • CBAM attention
      • Feature pooling and output
      • Input format
    • Complete Networks
      • MSCNN1D_2DResNetCBAM
      • MSCNN1D_2DResNetCBAM_Heteroscedastic
      • Compiling with torch.compile
      • Parameter count
      • Normalisation choice
  • Custom Loss Functions
    • BCEWithPEregLoss
      • Formula
      • Parameters
      • Outputs
      • When to use
    • BCEWithPEsigmaLoss
      • Three-term formula
      • Parameters
      • Outputs
      • When to use
  • Optimisers & Schedulers
    • Setting up the optimiser
    • Learning rate scheduler
    • ManageScheduler — step-mode adapter
    • AMP gradient scaler
    • Gradient clipping
  • Training
    • Initialisation
      • Constructor arguments
    • What happens inside each batch
    • Running the training loop
    • Inspecting loss components
    • Logging losses to HDF5
  • Validation
    • Initialisation
    • Running validation
    • What is saved to HDF5
    • Reading the HDF5 output
    • Downstream diagnostics
    • Checkpointing
  • Production Run — Full Code
    • Phase 1: Dataset preparation
    • Phase 2: Configuration
    • Phase 3: Training loop
    • Running the full pipeline
    • Export directory layout

Learning Guide

  • Learning Guide
    • What Will Be Here
      • GW Physics Primer (for ML readers)
      • ML Primer (for GW readers)
      • Step-by-Step Tutorials
      • Worked Examples
      • Exercises
        • Guide for Complete Beginners
  • Guide for Complete Beginners
    • How to get started with zero programming experience
    • What you will need (eventually)

Developer Guide

  • Developer Guide
    • What Will Be Here
      • Development Environment
      • Code Conventions
      • Extending Sage
      • Testing
      • CI / CD Pipeline
      • Release Process
      • Contributing Guidelines

Reviewer Guide

  • Reviewer Guide
    • What Will Be Here
      • Automated Review Tools
      • Reproducing the Paper Results
      • Data Availability
      • Common Reviewer Questions
      • Getting Help

Reference

  • Benchmarks — MLGWSC-1 Results
    • Sensitive distance vs. false alarm rate
    • ROC curves
    • Per-parameter detection comparisons
  • Citation & Acknowledgements
    • Citing Sage
    • Acknowledgements
  • Changelog
    • Changelog
      • [Unreleased]
      • [0.1.0] - 2026-05-25
        • Added — package structure
        • Added — DSP
        • Added — data and noise mining
        • Added — usability and documentation
        • Fixed
      • [0.0.1] - 2025-11-01
        • Added
  • Glossary
  • Search & Index
  • sage
    • Submodules
      • sage.architecture
        • Submodules
      • sage.benchmark
        • Submodules
      • sage.core
        • Submodules
      • sage.data
        • Submodules
      • sage.debug
        • Submodules
      • sage.dsp
        • Submodules
      • sage.exec
        • Submodules
      • sage.factory
        • Submodules
      • sage.plotting
        • Submodules
      • sage.presets
        • Submodules
      • sage.utils
        • Submodules
Sage

Search the full Sage documentation — user guides, API reference, glossary, and more.

Not sure where to start? Try one of these:

  • Pipeline overview — what each module does and how they fit together
  • Configuration reference — every field in RunCFG, DataCFG, and gwconfig.yaml
  • Glossary — definitions for GW and ML terms used throughout the docs
  • Troubleshooting — common errors and how to fix them
  • API reference — full auto-generated documentation for every module
  • Search

© Copyright 2026, Narenraju Nagarajan.

Built with Sphinx using a theme provided by Read the Docs.