Python API Reference

Overview

The Python API provides a user-friendly interface to VegasAfterglow’s C++ core, enabling easy model setup, simulation execution, and result analysis. All major C++ components are exposed through Python bindings with an intuitive interface.

Key Components

The Python API is organized into several core components:

  • Data Representation: Classes for handling observational data and model parameters

  • MCMC Framework: Tools for parameter fitting and posterior exploration

  • Model Configuration: Classes for setting up the physical model

  • Results Processing: Tools for handling simulation outputs

Core Classes

ObsData

The ObsData class is used to store and manage observational data, including light curves and spectra. It provides methods to add observational data from various sources.

Example:

from VegasAfterglow import ObsData

# Create an instance to store observational data
data = ObsData()

# Add light curve data
data.add_light_curve(nu_cgs=4.84e14, t_cgs=time_data, Fnu_cgs=flux_data, Fnu_err=flux_error)

# Add spectrum data
data.add_spectrum(t_cgs=3000, nu_cgs=nu_data, Fnu_cgs=spectrum_data, Fnu_err=spectrum_error)

Setups

The Setups class defines global properties and environment settings for the model. These settings remain fixed during the MCMC process.

Example:

from VegasAfterglow import Setups

# Create configuration
cfg = Setups()

# Source properties
cfg.lumi_dist = 3.364e28    # Luminosity distance [cm]
cfg.z = 1.58               # Redshift

# Physical model configuration
cfg.medium = "wind"        # Ambient medium: "wind", "ISM", or "user"
cfg.jet = "powerlaw"       # Jet structure: "powerlaw", "gaussian", "tophat", or "user"

ModelParams

The ModelParams class stores the physical parameters that define the GRB afterglow model. These parameters are varied during the MCMC fitting process.

ParamDef and Scale

These classes are used to define parameters for MCMC exploration, including their name, initial value, prior range, and sampling scale:

Example:

from VegasAfterglow import ParamDef, Scale

mc_params = [
    ParamDef("E_iso",    1e52,  1e50,  1e54,  Scale.LOG),       # Isotropic energy [erg]
    ParamDef("Gamma0",     30,     5,  1000,  Scale.LOG),       # Lorentz factor at the core
    ParamDef("theta_c",   0.2,   0.0,   0.5,  Scale.LINEAR),    # Core half-opening angle [rad]
    ParamDef("theta_v",   0.,  None,  None,   Scale.FIXED),     # Viewing angle [rad]
    ParamDef("p",         2.5,     2,     3,  Scale.LINEAR),    # Shocked electron power law index
    ParamDef("eps_e",     0.1,  1e-2,   0.5,  Scale.LOG),       # Electron energy fraction
    ParamDef("eps_B",    1e-2,  1e-4,   0.5,  Scale.LOG),       # Magnetic field energy fraction
    ParamDef("A_star",   0.01,  1e-3,     1,  Scale.LOG),       # Wind parameter
]

For wind medium models, you would use the A_star parameter as shown above.

For ISM medium models, you would use the density parameter instead:

ParamDef("n_ism",     0.1,  1e-3,    10,  Scale.LOG),       # ISM density [cm^-3]

Fitter

The Fitter class provides a high-level interface for MCMC fitting of GRB afterglow models to observational data.

Example:

from VegasAfterglow import Fitter

# Create the fitter object
fitter = Fitter(data, cfg)

# Run the MCMC fitting
result = fitter.fit(
    param_defs=mc_params,          # Parameter definitions
    resolution=(24, 24, 24),       # Grid resolution (phi, theta, time)
    total_steps=10000,             # Total number of MCMC steps
    burn_frac=0.3,                 # Fraction of steps to discard as burn-in
    thin=1                         # Thinning factor
)

# Generate light curves with best-fit parameters
lc_best = fitter.light_curves(result.best_params, t_out, bands)

# Generate spectra with best-fit parameters
spec_best = fitter.spectra(result.best_params, nu_out, times)

FitResult

The FitResult class stores the results of an MCMC fit, including the posterior samples, log probabilities, and best-fit parameters.

VegasMC

The VegasMC class is the core calculator for MCMC sampling, providing efficient computation of model likelihood based on the specified parameters.

Documenting Python Code

When contributing to the Python codebase, please follow these documentation guidelines:

Class and Function Documentation

Use NumPy-style docstrings for all classes and functions:

def function(param1, param2):
    """
    Brief description of the function.

    Detailed description of the function's behavior, expected inputs,
    outputs, and any other relevant information.

    Parameters
    ----------
    param1 : type
        Description of param1
    param2 : type
        Description of param2

    Returns
    -------
    type
        Description of the return value

    Examples
    --------
    >>> function(1, 2)
    3
    """

Example Class

Here’s an example of a well-documented class:

class ParamDef:
    """
    Single-parameter definition for MCMC.

    This class defines a parameter to be used in MCMC fitting, including
    its name, initial value, prior range, and sampling scale.

    Parameters
    ----------
    name : str
        The parameter name
    init : float
        Initial value for the parameter
    lower : float, optional
        Lower bound for the parameter (not needed for FIXED scale)
    upper : float, optional
        Upper bound for the parameter (not needed for FIXED scale)
    scale : Scale, optional
        Sampling scale (LINEAR, LOG, or FIXED), default is LINEAR

    Notes
    -----
    When scale=LOG, we sample log10(x), then transform via 10**v.
    When scale=FIXED, the parameter never appears in the sampler.
    """

For more details on NumPy-style docstrings, see the Contributing page.