# colmtalbot/gwmemory architecture

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

- Interactive diagram: https://gitdiagram.com/colmtalbot/gwmemory
- Repository: https://github.com/colmtalbot/gwmemory

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Scripts/Examples
    subgraph "External Scripts/Examples"
        Gen["generate_gamma_data.py"]:::external
    end

    %% Waveform Models
    subgraph "Waveform Models"
        WB["WaveformBase"]:::waveform
        AW["ApproximantWaveform"]:::waveform
        NR["NRWaveform / NRSurrogateWaveform"]:::waveform
        MW["MinimalWaveformModel"]:::waveform
        SW["SurrogateWaveform"]:::waveform
    end

    %% Core Memory Calculator
    MC["MemoryCalculator"]:::core

    %% Utilities
    subgraph "Utilities"
        HM["Harmonics"]:::util
        AG["Angles"]:::util
        QN["QNM (QNMLoader)"]:::util
        UT["IOUtils / TimeIntegrator"]:::util
    end

    %% Data Flow & Calls
    Gen -->|calls| QN
    Gen -->|calls| UT

    WB -->|implements| MC
    AW -->|implements| MC
    NR -->|implements| MC
    MW -->|implements| MC
    SW -->|implements| MC

    WB -->|calls| HM
    AW -->|calls| HM
    NR -->|calls| HM
    MW -->|calls| HM
    SW -->|calls| HM

    WB -->|calls| AG
    AW -->|calls| AG
    NR -->|calls| AG
    MW -->|calls| AG
    SW -->|calls| AG

    HM -.->|data| MC
    AG -.->|data| MC

    MC -->|uses| QN
    MC -->|uses| UT

    MC -->|"outputs memory waveform"| Output["Memory Waveform"]

    %% Click Events
    click WB "https://github.com/colmtalbot/gwmemory/blob/master/gwmemory/waveforms/base.py"
    click AW "https://github.com/colmtalbot/gwmemory/blob/master/gwmemory/waveforms/approximant.py"
    click NR "https://github.com/colmtalbot/gwmemory/blob/master/gwmemory/waveforms/nr.py"
    click MW "https://github.com/colmtalbot/gwmemory/blob/master/gwmemory/waveforms/mwm.py"
    click SW "https://github.com/colmtalbot/gwmemory/blob/master/gwmemory/waveforms/surrogate.py"
    click MC "https://github.com/colmtalbot/gwmemory/blob/master/gwmemory/gwmemory.py"
    click HM "https://github.com/colmtalbot/gwmemory/blob/master/gwmemory/harmonics.py"
    click AG "https://github.com/colmtalbot/gwmemory/blob/master/gwmemory/angles.py"
    click QN "https://github.com/colmtalbot/gwmemory/blob/master/gwmemory/qnms.py"
    click UT "https://github.com/colmtalbot/gwmemory/blob/master/gwmemory/utils.py"
    click Gen "https://github.com/colmtalbot/gwmemory/blob/master/bin/generate_gamma_data.py"

    %% Styles
    classDef waveform fill:#D0E1FF,stroke:#1E4F8A,color:#1E4F8A,stroke-width:1px
    classDef core fill:#D0FFD8,stroke:#1E7A1E,color:#1E7A1E,stroke-width:1px
    classDef util fill:#FFE7B3,stroke:#C77C00,color:#C77C00,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#6E6E6E,color:#6E6E6E,stroke-width:1px
    classDef default stroke:#333,stroke-width:1px
```
