How colmtalbot/gwmemory works
Project type and purpose
• This is an open-source scientific Python library for computing the nonlinear gravitational-wave memory signal from arbitrary time-domain waveforms.
• It provides a pipeline: take a waveform → decompose into spin-weighted harmonics → apply quasinormal‐mode expansions → compute memory → output a waveform.
File structure
Top level:
• bin/ → utility scripts (e.g. generate_gamma_data.py)
• gwmemory/ → core library code, organized by functionality
– angles.py
– gwmemory.py
– harmonics.py
– qnms.py
– utils.py
– waveforms/ → subpackage with modules for different waveform models
• examples/ → Jupyter demos
• test/ → unit tests
• docs/ → Sphinx documentation
• configuration: pyproject.toml, requirements.txt, GitHub Actions workflows, etc.
README
• Describes supported waveform sources (NRSur7dq2, lalsuite, minimal models, gwsurrogate)
• Installation and usage examples
• Links to online docs and examples
Main components & classes
A. Waveform Loader & Interface (gwmemory/waveforms)
– WaveformBase (in base.py)
– ApproximantWaveform (in approximant.py)
– NRSurrogateWaveform or NRWaveform (in nr.py)
– MinimalWaveformModel (in mwm.py)
– SurrogateWaveform (in surrogate.py)
B. Memory Calculator (gwmemory/gwmemory.py)
– MemoryCalculator (or similarly named class)
• Orchestrates the pipeline: takes a WaveformBase instance, calls harmonics & qnms & utils to produce memory waveform.
C. Harmonic & Angular utilities
– Harmonics (in harmonics.py)
– Angles (in angles.py)
D. Quasinormal‐Mode utilities (gwmemory/qnms.py)
– QNMLoader or QNM
E. Supporting utilities (gwmemory/utils.py)
– IOUtils, TimeIntegrator, etc. (whatever classes/functions are defined)
F. External I/O & Scripting
– Script generate_gamma_data.py calls into gwmemory.qnms and gwmemory.utils.
Relationships & Data‐Flow
• Waveform → (instantiates) WaveformBase subclass → calls
↳ Harmonics (decompose into ℓ,m modes)
↳ Angles (compute orientation weighting)
• Decomposed modes → MemoryCalculator
↳ MemoryCalculator uses QNM loader → corrects ringdown modes
↳ MemoryCalculator uses Utils → integration, interpolation
• MemoryCalculator → outputs memory waveform (time series)
• Tests & examples import the same classes to validate and demonstrate usage.
Architectural patterns & design principles
• Strategy pattern for waveform models: a common WaveformBase interface with multiple implementations.
• Separation of concerns:
– Data‐loading (waveforms/)
– Computation (gwmemory.py)
– Utilities (harmonics, angles, qnms, utils)
• Extensibility point: new waveform model → subclass WaveformBase and register in factory.
– Clear component labels with exact class/module names