MetaPulsar User Guide

Quick Start

MetaPulsar combines pulsar timing data from multiple PTA collaborations into unified objects for gravitational wave detection.

Basic Usage

from metapulsar import MetaPulsarFactory, FileDiscoveryService

# Create file discovery service
discovery = FileDiscoveryService()

# Discover files for a pulsar
file_data = discovery.discover_all_files_in_ptas(["epta_dr2", "ppta_dr3"])

# Create factory
factory = MetaPulsarFactory()

# Create MetaPulsar
metapulsar = factory.create_metapulsar(
    file_data,
    combination_strategy="consistent"
)

Core Concepts

Combination Strategies

Consistent: Astrophysical consistency across PTAs
- Aligns parameters to reference PTA values
- Suitable for unified gravitational wave analysis
Composite: Multi-PTA composition
- Uses raw par files without modification
- Preserves PTA-specific parameter differences
- Suitable for ‘Borg’ or ‘FrankenStat’ analysis methods

File Discovery

from metapulsar import FileDiscoveryService

# Create file discovery service
discovery = FileDiscoveryService()

# List available PTAs
ptas = discovery.list_ptas()
print(f"Available PTAs: {ptas}")

# Discover files for specific PTAs
files = discovery.discover_all_files_in_ptas(["epta_dr2", "ppta_dr3"])

Parameter Management

from metapulsar import ParameterManager

# Assuming file_data is obtained from FileDiscoveryService
# and contains paths to par/tim files for multiple PTAs
# For example:
file_data = {
    "epta_dr2": [{"par": "path/to/epta.par", "tim": "path/to/epta.tim"}],
    "ppta_dr3": [{"par": "path/to/ppta.par", "tim": "path/to/ppta.tim"}],
}

param_manager = ParameterManager(
    file_data=file_data,
    reference_pta="epta_dr2",
    combine_components=["astrometry", "spindown", "binary", "dispersion"],
    add_dm_derivatives=True
)

mapping = param_manager.build_parameter_mappings(
    merge_astrometry=True,
    merge_spin=True,
    merge_binary=False
)

Advanced Usage

Custom PTA Configuration

# Add custom PTA
discovery.add_pta("custom_pta", {
    "base_dir": "/data/custom_pta/",
    "par_pattern": r"([BJ]\d{4}[+-]\d{2,4})_custom\.par",
    "tim_pattern": r"([BJ]\d{4}[+-]\d{2,4})_custom\.tim",
    "timing_package": "pint",
    "priority": 1,
    "description": "Custom PTA for demonstration"
})

Enterprise Integration

from metapulsar import create_staggered_selection

# Create staggered selection for Enterprise
selection = create_staggered_selection(
    flags=flags,
    freqs=freqs,
    primary_flag="telescope",
    fallback_flags=["backend", "freq_band"],
    freq_bands={"low": (50, 200), "mid": (200, 800), "high": (800, 2000)}
)

Examples

See the examples/ directory for comprehensive usage examples:

basic_workflow.py - Complete workflow tutorial
parameter_management.py - Parameter management strategies
custom_pta_configuration.py - Custom PTA setup
enterprise_integration.py - Enterprise framework integration

API Reference

For detailed API documentation, see API Reference.

Troubleshooting

For common issues and solutions, see Troubleshooting Guide.