GW150914 MCP Signal Search

A gravitational wave signal detection and optimization system using the Model Context Protocol (MCP) for efficient parameter space exploration.

🌊 Overview

This project provides tools for analyzing gravitational wave signals, specifically focusing on the GW150914 event. It uses MCP to create a client-server architecture where:

GW Analysis Server (mcp-server/gw_analysis_server.py): Provides gravitational wave analysis tools via MCP
GW Optimization Client (mcp-client/gw_optimization_client.py): Uses AI to optimize signal detection parameters

🚀 Quick Start

Prerequisites

Python 3.9 or higher
UV package manager

Install UV if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Installation

Clone and setup the project:

git clone <repository-url>
cd gw150914-mcp-signal-search
make setup

Configure environment variables:

cp env.template .env
# Edit .env with your OpenAI API key

Install dependencies:

make install-dev

Running the System

Start the analysis server andthe optimization client:

make run-client SERVER_PATH=mcp-server/gw_analysis_server.py

Or run a complete demo (includes both server and client):

make demo

📋 Available Commands

Run make help to see all available commands:

Installation & Setup

make install - Install production dependencies
make install-dev - Install with development dependencies
make setup - Complete development setup
make update - Update all dependencies

Code Quality

make format - Format code with black and isort
make lint - Run linting checks
make check - Run all code quality checks
make test - Run tests

Running Applications

make run-server - Start the GW analysis server
make run-client SERVER_PATH=<path> - Start the optimization client
make demo - Run complete demo

Development

make notebook - Start Jupyter notebook
make dev-shell - Enter development shell
make clean - Clean temporary files

Data Management

make data-info - Show information about data files
make clean-data - Clean temporary data files (keeps strain data)
make backup-data - Create backup of analysis results and logs

🔧 Project Structure

gw150914-mcp-signal-search/
├── data/                            # Gravitational wave data and analysis results
│   ├── H1-1126259446-1126259478.txt    # LIGO Hanford strain data (GW150914)
│   ├── L1-1126259446-1126259478.txt    # LIGO Livingston strain data (GW150914)
│   ├── matched_filter_records.jsonl    # Analysis results and optimization history
│   └── logs/                            # Application logs (auto-generated)
│       ├── server_YYYYMMDD_HHMMSS.log      # Server execution logs
│       ├── client_YYYYMMDD_HHMMSS.log      # Client execution logs
│       └── demo_YYYYMMDD_HHMMSS.log        # Combined demo logs
├── mcp-client/
│   └── gw_optimization_client.py    # AI-powered optimization client
├── mcp-server/
│   └── gw_analysis_server.py        # GW analysis MCP server
├── pyproject.toml                   # Project configuration
├── Makefile                         # Build and deployment commands
├── env.template                     # Environment variables template
└── README.md                        # This file

📊 Data Directory

The data/ directory contains gravitational wave strain data and analysis results for the GW150914 event:

Strain Data Files

H1-1126259446-1126259478.txt: LIGO Hanford (H1) detector strain data
- GPS time range: 1126259446 to 1126259478 (32 seconds around GW150914)
- Format: Two columns - GPS time (seconds) and strain amplitude
- Sample rate: 4096 Hz
- Data points: ~131,072 samples per detector
L1-1126259446-1126259478.txt: LIGO Livingston (L1) detector strain data
- Same format and time range as H1 data
- Contains the gravitational wave signal from the binary black hole merger

Analysis Results

matched_filter_records.jsonl: JSON Lines file containing optimization results
- Each line represents one matched filter analysis result
- Contains SNR values, template parameters, detector responses
- Tracks optimization history and parameter exploration
- Used by the AI client to learn from previous attempts

Application Logs

logs/: Directory containing timestamped execution logs (auto-generated)
- server_YYYYMMDD_HHMMSS.log: Server execution logs with timestamps
- client_YYYYMMDD_HHMMSS.log: Client optimization logs and AI interactions
- demo_YYYYMMDD_HHMMSS.log: Combined logs from demo runs
- All stdout and stderr output is captured with timestamps
- Logs are automatically created when running make run-server, make run-client, or make demo

Data Format Details

Strain Data Format:

GPS_TIME    STRAIN_AMPLITUDE
1.126259446000000000e+09    2.177040281448404468e-19
1.126259446000244141e+09    2.087638998822567751e-19
...

Analysis Results Format:

{
  "timestamp": "010725",
  "max_network_snr": 7.3055496414353565,
  "max_snr_time": 1126259462.4360352,
  "template_parameters": {
    "mass1": 17.0,
    "mass2": 9.5,
    "ra": 0.94,
    "dec": -0.31
  },
  "detector_snrs_at_max": {
    "H1": {"snr_abs": 5.064289109514169},
    "L1": {"snr_abs": 5.2653614670535624}
  }
}

Data Usage

The strain data is automatically loaded by the MCP server for analysis
Results are cached to /tmp/gw-mcp/ during processing
The optimization client uses historical results to guide parameter searches
Data can be visualized using the server's plotting tools
All execution logs are automatically saved to data/logs/ with timestamps for debugging and analysis

🧪 Features

GW Analysis Server Tools

Data Fetching: Download and preprocess GW data from GWOSC
Matched Filter Search: Perform template-based signal detection
Network Analysis: Multi-detector coherent analysis
Visualization: Generate plots and analysis results

Optimization Client

AI-Powered Search: Uses OpenAI GPT for intelligent parameter exploration
4D Parameter Space: Optimizes mass1, mass2, right ascension, declination
Convergence Detection: Automatically stops when optimal SNR is found
Progress Tracking: Visual feedback during optimization

🔬 Scientific Background

This project focuses on the GW150914 event, the first direct detection of gravitational waves:

Event Time: GPS 1126259462.427
Source: Binary black hole merger (~36 + 29 solar masses)
Detectors: LIGO Hanford (H1) and LIGO Livingston (L1)
Peak SNR: ~24 in the network

📈 Results & Validation

This project was developed and validated at the AI for Science Hackathon (Beijing) with promising results demonstrating the effectiveness of LLM-agent powered gravitational wave detection.

Key Findings

Project presentation at AI for Science Hackathon (Beijing) - LLM-agent powered gravitational wave detection and scientific discovery

Reliability Analysis

The system demonstrates consistent convergence behavior across different initial conditions:

Parameter evolution and convergence analysis showing gradual convergence to true values during exploration. The system shows consistent performance under different initial conditions with average iterations of 13.3 ± 3.5 to reach maximum SNR of 19.56.

Detection Performance

The automated system successfully detects and analyzes gravitational wave signals:

Network SNR time series showing successful detection of GW150914 signal. The system achieves peak network SNR of 19.6 at GPS time 1126259462.428, demonstrating automated GW data detection with LLM-agent validation on real GW data.

Validation Results

Convergence: Parameters gradually converge to true values during exploration
Consistency: Model shows consistent performance under different initial conditions
Accuracy: Successfully achieves maximum SNR of ~19.6, matching theoretical expectations
Automation: Fully automated detection pipeline validated on real LIGO data

Technical Report

For detailed methodology, results, and analysis, see: docs/Hackathon.pdf

Presented by He Wang (ICTP-AP, UCAS) and Yiming Dong (PKU) at AI for Science Hackathon (Beijing), August 24, 2025

🛠️ Development

Setting up Development Environment

# Complete development setup
make setup

# Install pre-commit hooks
make pre-commit-install

# Run tests
make test

# Check code quality
make check

Dependencies

Core dependencies:

mcp: Model Context Protocol framework
numpy, scipy: Scientific computing
gwpy, pycbc: Gravitational wave analysis
openai: AI integration
matplotlib: Visualization

📊 Usage Examples

Basic Optimization

# The client will automatically optimize parameters for GW150914
python mcp-client/gw_optimization_client.py mcp-server/gw_analysis_server.py

Custom Parameter Ranges

Edit the optimization query in the client to specify different:

Mass ranges (currently 10-80 solar masses)
Sky location ranges (RA: 0-2π, Dec: -π/2 to π/2)
Convergence criteria

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Run make check to ensure code quality
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

📚 Learning Resources

MCP (Model Context Protocol) Resources

Official MCP Documentation - Complete getting started guide and API reference
DeepLearning.AI MCP Course - "MCP: Build Rich-Context AI Apps with Anthropic" - comprehensive hands-on course by Elie Schoppik
Tutorial on Building AI Scientist Agents with Model Context Protocol - Comprehensive tutorial on building AI scientist agents using MCP framework
MCP.Science Repository - Open source MCP servers for scientific research with 65+ stars
How to Build Your Own MCP Server - Step-by-step tutorial for creating custom MCP servers
Integrate MCP Server Guide - Complete integration guide for MCP servers with AI applications

Scientific Computing & AI Resources

AI4Science Events - Stanford Quantum Science Hackathon and other AI for science events
AI-4-Science Organization - Community and resources for AI applications in scientific research
Project Technical Report - Detailed methodology and results from AI for Science Hackathon (Beijing) validation

Why These Resources Matter

This project demonstrates practical applications of MCP in scientific computing, specifically for gravitational wave analysis. The resources above provide:

Foundation Knowledge: Understanding MCP architecture and implementation
Hands-on Learning: Building and deploying MCP servers and clients
Scientific Context: Real-world applications of AI in physics and astronomy
Community: Connect with researchers and developers working on similar projects

Getting Started with MCP

Start with the official MCP documentation for core concepts
Take the DeepLearning.AI course for practical implementation
Explore the MCP.Science repository for scientific use cases
Use this project as a template for your own gravitational wave or scientific analysis applications

🙏 Acknowledgments

LIGO Scientific Collaboration for gravitational wave data
PyCBC and GWpy communities for analysis tools
Anthropic for MCP framework and protocol development
Path Integral Institute for MCP.Science open source servers
DeepLearning.AI and Elie Schoppik for educational resources

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
data		data
docs		docs
mcp-client		mcp-client
mcp-server		mcp-server
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
env.template		env.template
pyproject.toml		pyproject.toml

License

iphysresearch/gw150914-mcp-signal-search

Folders and files

Latest commit

History

Repository files navigation