MetaPulsar Troubleshooting Guide

Common Issues

Installation Issues

Import Errors

Problem: ModuleNotFoundError: No module named 'metapulsar'

Solutions:

1. Check Python path:

   import sys
   print(sys.path)
   

2. Reinstall package:

   pip uninstall metapulsar
   pip install -e .
   

3. Check virtual environment:

   which python
   pip list | grep metapulsar
   

Missing Dependencies

Problem: ImportError: No module named 'enterprise'

Solutions:

1. Install all dependencies:

   pip install -e ".[dev,libstempo,analysis]"
   

2. Check specific dependency:

   import enterprise
   print(enterprise.__version__)
   

Runtime Issues

File Not Found

Problem: FileNotFoundError when discovering files

Solutions:

1. Check PTA registry configuration

2. Verify file patterns match actual files

3. Ensure base directories exist

Parameter Consistency Errors

Problem: ParameterInconsistencyError

Solutions:

1. Check parameter names across PTAs

2. Verify parameter units

3. Use composite strategy if consistency not needed

Performance Issues

Slow File Discovery

Solutions:

1. Use specific PTA names instead of all PTAs

2. Pre-filter data when possible

3. Cache frequently used objects

Memory Issues

Solutions:

1. Use appropriate data types

2. Clean up large objects

3. Process data in chunks

Getting Help

1. Check this troubleshooting guide

2. Review examples in examples/ directory

3. Check API documentation

4. Report issues on GitHub

FAQ

Q: What’s the difference between composite and consistent strategies?

A: Composite strategy preserves PTA-specific parameter differences, while consistent strategy aligns parameters to a reference PTA for astrophysical consistency.

Q: How do I add a custom PTA?

A: Use the FileDiscoveryService.add_pta() method with a configuration dictionary containing file patterns and settings.

Q: Can I use MetaPulsar without Enterprise?

A: Yes, MetaPulsar is a standalone package. Enterprise integration is optional but recommended for gravitational wave analysis.

Q: How do I handle missing data files?

A: MetaPulsar gracefully handles missing files by filtering out PTAs with no data before creating MetaPulsar objects.

Q: What timing packages are supported?

A: MetaPulsar supports both PINT and TEMPO2 timing packages through the timing_package configuration option.