Troubleshooting

This page addresses common issues and questions that users encounter when working with VegasAfterglow.

Common Issues

Model Setup and Calculation

Q: My light curve has strange spikes or discontinuities

A: This is usually caused by one of the following:

  • Time array ordering: Ensure your time array is in ascending order when using specific_flux(). Use specific_flux_sorted_series() for better performance with sorted arrays.

  • Resolution too low: Increase the resolution parameters in Model(resolutions=(phi_ppd, theta_ppd, t_ppd))

  • User-defined profiles: For custom jet/medium profiles, ensure they are smooth and well-behaved

Q: My calculation is extremely slow

A: Performance can be improved by:

  • Reducing resolution: Use resolutions=(0.1, 3, 5) for speed, (0.3, 5, 10) for accuracy

  • Limiting frequency/time ranges: Calculate only the bands and times you need

  • Using built-in profiles: Built-in jet structures are faster than user-defined Python functions

  • For MCMC: Consider using fewer parameters or coarser resolution

Q: I get numerical errors or NaN values

A: Check for:

  • Extreme parameter values: Ensure parameters are within physically reasonable ranges

  • Zero or negative values: Some parameters (like energies, densities) must be positive

  • Resolution mismatch: Very fine resolution with short time arrays can cause issues

Q: My model doesn’t match basic expectations (wrong slope, normalization)

A: Verify:

  • Units: All inputs should be in CGS units (see parameter reference table)

  • Observer frame vs source frame: Times and frequencies are in observer frame

  • Jet opening angle: theta_c is in radians, not degrees

MCMC Fitting Issues

Q: MCMC chains don’t converge or get stuck

A: Try the following:

  • Check parameter ranges: Ensure prior ranges include the true values

  • Use better initial guesses: Set ParamDef initial values closer to expected results

  • Increase burn-in: Use burn_frac=0.5 or higher for difficult problems

  • More walkers: Use n_walkers > 2 * n_parameters (emcee recommendation)

  • Check data quality: Ensure observational uncertainties are realistic

Q: MCMC is too slow for practical use

A: Optimization strategies:

  • Reduce resolution: Use resolution=(0.5, 3, 5) for initial exploration

  • Fewer parameters: Fix some parameters with Scale.FIXED

  • Coarser time/frequency grids: Use fewer data points for initial fits

  • Parallel processing: Ensure you’re using multiple cores

Q: Parameter constraints seem unrealistic

A: Check:

  • Parameter scaling: Use Scale.LOG for parameters spanning orders of magnitude

  • Prior ranges: Ensure they’re physically motivated and not too restrictive

  • Model degeneracies: Some parameters may be strongly correlated

  • Data coverage: Limited frequency/time coverage can lead to poor constraints

Data and File Issues

Q: I can’t load my observational data

A: Common data loading issues:

  • File format: Ensure CSV files have the expected column names (t, Fv_obs, Fv_err, nu)

  • Units: Data should be in CGS units (times in seconds, frequencies in Hz, fluxes in erg/cm²/s/Hz)

  • Missing values: Remove or interpolate NaN/infinite values

  • File paths: Use absolute paths or ensure files are in the correct directory

Q: Error messages about missing dependencies

A: Install required packages:

pip install numpy scipy matplotlib pandas corner emcee

For specific features:

pip install jupyter  # For notebook examples
pip install h5py     # For saving large datasets

Installation and Environment

Q: Installation fails on my system

A: Platform-specific solutions:

  • macOS Apple Silicon: Try pip install --no-deps VegasAfterglow then install dependencies separately

  • Windows: Ensure Visual Studio Build Tools are installed

  • Linux: May need development packages (python3-dev, build-essential)

  • Conda environments: Use pip within conda, not conda install

Q: ImportError when importing VegasAfterglow

A: Check:

  • Python version: VegasAfterglow requires Python 3.8+

  • Virtual environment: Ensure you’re in the correct environment

  • Installation location: Try pip show VegasAfterglow to verify installation

  • Conflicting packages: Try installing in a clean environment

Performance Guidelines

Resolution Parameters

The resolutions parameter in Model() controls computational accuracy vs speed:

Resolution Guidelines

Use Case

Resolution

Speed

Accuracy

Initial exploration

(0.1, 3, 5)

Very Fast

Low

Standard calculations

(0.3, 3, 5)

Fast

Good

MCMC fitting

(0.3, 5, 10)

Moderate

High

Publication quality

(0.3, 10, 15)

Slow

Very High

Where resolutions=(phi_ppd, theta_ppd, t_ppd):

  • phi_ppd: Points per degree in azimuthal direction

  • theta_ppd: Points per degree in polar direction

  • t_ppd: Points per decade in time direction

Memory Usage

For large parameter studies or high-resolution calculations:

  • Limit output arrays: Calculate only needed times/frequencies

  • Use generators: Process results in chunks rather than storing everything

  • Clear variables: Use del to free memory between calculations

  • Monitor usage: Use htop or Task Manager to monitor memory consumption

Getting Help

If you encounter issues not covered here:

  1. Check the examples: The Examples page covers many common use cases

  2. Search existing issues: Visit our GitHub Issues

  3. Create a new issue: Include:

    • VegasAfterglow version: import VegasAfterglow; print(VegasAfterglow.__version__)

    • Python version and platform

    • Minimal code example that reproduces the problem

    • Full error traceback

  4. Discussion forum: For general questions about GRB physics or methodology

Best Practices

Model Development Workflow

  1. Start simple: Begin with built-in jet types and standard parameters

  2. Validate physics: Check that results match analytical expectations for simple cases

  3. Parameter exploration: Use direct model calculations before MCMC

  4. Incremental complexity: Add features (reverse shock, IC, etc.) one at a time

  5. Resolution testing: Verify results are converged by increasing resolution