Afterglowpy: Fast GRB Afterglow Modeling

• Afterglowpy is a Python package that computes gamma-ray burst afterglow light curves using a fast, semi-analytic model for structured jets and arbitrary viewing angles.
• It employs a single-shell blast-wave model with relativistic Doppler beaming and equal-arrival-time integration to approximate complex hydrodynamic processes efficiently.
• Afterglowpy accelerates inference in GRB, multimessenger, and orphan-afterglow studies while supporting Bayesian parameter estimation and surrogate machine learning workflows.

afterglowpy is a public, open-source Python package for on-the-fly computation of gamma-ray burst afterglow light curves and spectra, especially for structured jets and arbitrary viewing angles. It was introduced as a fast semi-analytic alternative to full relativistic hydrodynamic calculations, with a single-shell blast-wave model, synchrotron radiation from shock-accelerated electrons, relativistic beaming, and equal-arrival-time integration, and it was explicitly designed to be fast enough for intensive inference tasks such as Markov Chain Monte Carlo parameter estimation (Ryan et al., 2019). Subsequent work uses afterglowpy as a forward model for GRB afterglows, gravitational-wave counterparts, orphan-afterglow searches, population studies, and joint afterglow–kilonova inference (Roxburgh et al., 2023, Singh et al., 29 Dec 2025, Dimitrova et al., 16 Jun 2026).

1. Historical development and software identity

afterglowpy was presented as a Python package whose integration core is written in C and wrapped for Python; it is available on PyPI and its source code is publicly available on GitHub (Ryan et al., 2019). The original package paper framed it as a numerical model for structured jets in the multi-messenger era, motivated by the need to extend common on-axis top-hat GRB afterglow models to larger inclinations such as those revealed by GW170817 (Ryan et al., 2019).

The code’s design goal was not to replace full relativistic hydrodynamics, but to provide a much faster semi-analytic approximation that remains usable inside posterior-sampling workflows. This positioning remained central in later work. The GWAPA webtool paper describes afterglowpy v0.7.3 as the physical engine behind an interactive browser-based interface for rapid exploratory analysis of GW and GRB afterglows, while the fiesta paper treats afterglowpy as one of the state-of-the-art base models for machine-learned surrogates that can reduce inference runtimes from hours to minutes or seconds (Eyles-Ferris et al., 2024, Koehn et al., 18 Jul 2025).

A substantial methodological extension appeared in the long-term GW170817 analysis, which incorporated into afterglowpy astrometric centroid modeling, Poisson likelihoods for faint X-ray data, and treatment of a trans-relativistic electron population through a Deep Newtonian prescription added in afterglowpy v0.8.0 (Ryan et al., 2023). This suggests an evolution from a light-curve generator into a broader inference framework for nearby, off-axis, and long-lived afterglows.

2. Dynamical and radiative formulation

The basic physical picture in afterglowpy is a single-shell approximation in which the ejecta mass, contact discontinuity, and forward shock are treated as one fluid element with uniform radial structure (Ryan et al., 2019). The dynamics include trans-relativistic evolution, a smooth equation of state connecting ultra-relativistic and Newtonian limits, an approximate prescription for jet spreading, relativistic Doppler beaming, and equal-arrival-time surface effects (Ryan et al., 2019). The GWAPA description adds that structured jets are handled as sums of many top-hat components, each evolved through ordinary differential equations for shock radius, dimensionless four-velocity, and time-dependent jet opening angle (Eyles-Ferris et al., 2024).

In the original formulation, the dynamical state is evolved through ordinary differential equations for the shock radius $R(t)$, fluid four-velocity $u(t)$, and effective jet opening angle $\theta_j(t)$. The shock propagation is written as

$\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$

and the opening-angle evolution is treated through a lateral spreading prescription that is switched on only once the flow becomes sufficiently slow (Ryan et al., 2019). The code solves these equations numerically with a fourth-order Runge–Kutta scheme on a logarithmic burster-frame time grid; the user-facing parameter tRes controls grid points per decade, with default 1000 (Ryan et al., 2019).

The observed flux density is computed from the synchrotron forward-shock model as

$$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$

with the observer-frame arrival time

$t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$

and frequency transformation

$\nu = (1+z)^{-1}\delta \nu'.$

The microphysical parameter set includes $\epsilon_e$, $\epsilon_B$, $\xi_N$, and the electron power-law index $u(t)$0 (Ryan et al., 2019). In later applications, these parameters appear repeatedly as the standard afterglowpy inputs for inference on jet energetics, geometry, and environment (Cunningham et al., 2020, Tandon et al., 2021).

The structured-jet closure-relation paper also derived analytic expressions tying light-curve slopes to angular structure. Its central structure parameter is

$u(t)$1

and the structured-phase temporal slope is

$u(t)$2

For Gaussian jets, an effective approximation is

$u(t)$3

while for power-law jets

$u(t)$4

These relations make viewing-angle and jet-structure effects explicit in the light-curve morphology (Ryan et al., 2019).

3. Jet structures and inferred parameter spaces

afterglowpy was introduced primarily to model structured relativistic jets. The foundational paper describes top-hat, Gaussian, and power-law angular energy profiles, with

$u(t)$5

for a Gaussian jet and

$u(t)$6

for a smooth power-law jet (Ryan et al., 2019). Application papers use the same family of parameterizations, and some extend the menu to Gaussian-with-core, cone, power-law-with-core, smooth power-law, and spherical-outflow models through interfaces built on afterglowpy (Tandon et al., 2021, Eyles-Ferris et al., 2024).

Across the literature, the inferred parameter spaces are variations on a common set: isotropic-equivalent kinetic energy or on-axis energy ($u(t)$7 or $u(t)$8), circumburst density $u(t)$9, electron index $\theta_j(t)$0, microphysical fractions $\theta_j(t)$1 and $\theta_j(t)$2, viewing angle $\theta_j(t)$3 or $\theta_j(t)$4, jet core angle $\theta_j(t)$5 or opening angle $\theta_j(t)$6, wing truncation angle $\theta_j(t)$7, and sometimes the accelerated-electron fraction $\theta_j(t)$8, the participation fraction $\theta_j(t)$9, the initial Lorentz factor $\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$0, redshift $\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$1, or an afterglow-onset delay parameter $\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$2 (Cunningham et al., 2020, Roxburgh et al., 2023, Li et al., 2024, Singh et al., 29 Dec 2025).

The statistical leverage of these parameters depends strongly on the dataset. In broadband modeling of GRB 160625B, afterglowpy combined with EMCEE showed that a Gaussian-shaped jet is preferred over a top-hat at $\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$3–$\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$4 significance based on WAIC comparisons, with inferred opening/core angles in the range $\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$5 (Cunningham et al., 2020). The same study showed that allowing the electron participation fraction $\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$6 to vary can raise the inferred total relativistic energy from $\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$7erg to $\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$8erg, implying a two-order-of-magnitude sensitivity of energetics to microphysical assumptions (Cunningham et al., 2020).

By contrast, sparse single-frequency or single-band datasets often remain highly degenerate. In modeling the putative electromagnetic counterpart of GW190814, Gaussian, top-hat, and cone jets could all reproduce the reported $\dot{R} = \frac{4u\gamma}{4u^2 + 3}c,$9GHz detections/non-detections when combined with $$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$0 degrees and $$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$1Mpc, yet later high-resolution imaging showed a double-lobed radio source inconsistent with a GRB jet (Tandon et al., 2021). The paper’s explicit conclusion was that flux evolution alone is not enough to distinguish jet models and that broadband spectral information plus high-resolution radio imaging are essential (Tandon et al., 2021).

4. Applications to gamma-ray bursts, orphan afterglows, and multimessenger counterparts

afterglowpy has been used both for individual events and for ensemble inference. In the TESS archival search for GRB afterglows, it provided the physical light-curve model used to interpret 11 candidate optical signals temporally coincident with known GRB triggers. The authors fit Gaussian and top-hat models, found that the full Gaussian case did not converge because of strong parameter degeneracies, and adopted simplified top-hat fits with fixed microphysical parameters after Bayesian samplers such as emcee and nestle also failed to converge. A mean explosion-to-afterglow onset delay of $$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$2s was required across the sample, with $$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$3s for the four high-likelihood afterglows, and the need for the ad hoc shift parameter $$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$4 was tied directly to the fact that afterglowpy does not include an initial coasting phase (Roxburgh et al., 2023).

For GRB 220101A, a multiband fit using optical, near-infrared, and X-ray data adopted a top-hat jet and fixed on-axis viewing angle $$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$5, excluding the $$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$6 and $$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$7 bands because of Lyman-$$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$8 forest absorption. The reported best-fit parameters were $$F_\nu(t_{\rm obs},\nu) = \frac{1+z}{4\pi d_L^2}\int d\Omega\, R^2\, \Delta R\, \delta^2\, \epsilon'_{\nu'},$$9erg, $t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$0rad $t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$1, $t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$2cm$t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$3, $t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$4, $t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$5, and $t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$6 (Zhu et al., 2023). A later broadband study of the same burst, extending to radio and sub-mm data, fit both top-hat and Gaussian jets for $t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$7 from $t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$8 to $t_{\rm obs} = (1+z)\left(t - \mu R(t)/c\right),$9 and found that including the radio forced the preferred $\nu = (1+z)^{-1}\delta \nu'.$0 solutions into an extremely low-density regime, with $\nu = (1+z)^{-1}\delta \nu'.$1–$\nu = (1+z)^{-1}\delta \nu'.$2cm$\nu = (1+z)^{-1}\delta \nu'.$3 and a post-break decay index of $\nu = (1+z)^{-1}\delta \nu'.$4 that is at least $\nu = (1+z)^{-1}\delta \nu'.$5 away from the fitted $\nu = (1+z)^{-1}\delta \nu'.$6 values (Roychowdhury et al., 4 Feb 2026).

The package has also become central to the interpretation of optical afterglows without detected prompt gamma rays. Broadband modeling of ZTF21aaeyldq used a top-hat, forward-shock, constant-density ISM model and found $\nu = (1+z)^{-1}\delta \nu'.$7, $\nu = (1+z)^{-1}\delta \nu'.$8rad, $\nu = (1+z)^{-1}\delta \nu'.$9rad, and $\epsilon_e$0, leading to the conclusion that the event was observed on-axis and that the gamma-ray counterpart was probably missed by satellites rather than suppressed by geometry (Gupta et al., 2021). A later consistent analysis of AT2023lcr, AT2020blt, AT2021any, and AT2021lfa tested off-axis jets, low-$\epsilon_e$1 “dirty fireballs,” and ordinary on-axis classical GRBs with missed prompt emission. It found that AT2023lcr, AT2020blt, and AT2021any are consistent with on-axis classical GRBs, whereas AT2021lfa remains consistent with both on-axis low-Lorentz-factor jets and off-axis high-Lorentz-factor jets (Li et al., 2024).

In multimessenger applications, afterglowpy has been used not only for GRB-only fits but also for joint electromagnetic-inference pipelines. The updated GW170817 modeling combined light curves, VLBI/HST astrometry, low-count Chandra observations, Deep Newtonian electrons, and predictive model comparison, finding only weak evidence, less than two sigma, for an additional late-time X-ray component beyond the structured jet (Ryan et al., 2023). In the NMMA framework, afterglowpy was coupled to POSSIS radiative-transfer kilonova models for six merger-driven GRBs, with Bayes-factor model comparison between Gaussian and top-hat jets and between BNS and NSBH progenitors. The favored models were NSBH-TH for GRB 150101B and GRB 191019A, BNS-GS for GRB 170817A, and BNS-TH for GRB 160821B, GRB 211211A, and GRB 230307A (Singh et al., 29 Dec 2025).

5. Computational ecosystem, interfaces, and surrogate acceleration

A notable feature of the afterglowpy literature is the growth of an ecosystem around the base code. GWAPA, the Gravitational Wave AfterglowPy Analysis webtool, is an interactive Bokeh-based interface built on afterglowpy v0.7.3. It accepts uploaded or repository data, supports multi-band plotting from X-ray to radio, lets users vary model parameters interactively, and can download a Python script that runs an emcee-based MCMC using the GWAPA parameter values as initial guesses (Eyles-Ferris et al., 2024).

Bayesian wrappers around afterglowpy are now common. GRB 230204B was modeled through the Redback framework using top-hat, Gaussian, and GaussianCore jets; the top-hat model had the best Bayesian evidence with $\epsilon_e$2, compared with $\epsilon_e$3 for Gaussian and $\epsilon_e$4 for GaussianCore, and the preferred fit implied $\epsilon_e$5cm$\epsilon_e$6, $\epsilon_e$7erg, $\epsilon_e$8, and radiative efficiency $\epsilon_e$9 (Gupta et al., 2024). In NMMA, afterglowpy acts as the non-thermal afterglow component inside a joint afterglow+kilonova Bayesian analysis sampled with PyMultiNest (Singh et al., 29 Dec 2025).

Acceleration by machine learning has become a separate development line. The fiesta package trains surrogates for afterglowpy and pyblastafterglow; for the afterglowpy Gaussian-jet surrogate it used $\epsilon_B$0 flux-density calculations. Two architectures were tested, a feed-forward MLP predicting PCA coefficients and a cVAE operating directly on flux densities, with the cVAE FluxModel adopted as the default. In an afterglowpy injection-recovery benchmark, fiesta on an NVIDIA H100 GPU achieved a total runtime of $\epsilon_B$1s, whereas direct inference with the physical afterglowpy model in nmma with PyMultiNest took $\epsilon_B$2s on 24 Intel Xeon CPUs (Koehn et al., 18 Jul 2025). A different machine-learning workflow used afterglowpy to generate 30,000 synthetic light curves for GRB 210822A, then trained a Keras/TensorFlow network to infer $\epsilon_B$3, $\epsilon_B$4, $\epsilon_B$5, $\epsilon_B$6, $\epsilon_B$7, $\epsilon_B$8, $\epsilon_B$9, and $\xi_N$0 from the observed afterglow (Angulo-Valdez et al., 2023).

Population and survey simulations also rely on afterglowpy as the forward engine. One Rubin/LSST orphan-afterglow study generated a population of short GRBs, simulated their off-axis structured-jet light curves with afterglowpy, propagated them through rubin_sim, and then trained a Scikit-Learn gradient boosting classifier in Fink. Under the strict cut $\xi_N$1, the classifier retained 452 out of 679 orphan afterglows while only 1 out of 10000 ELAsTiCC background events survived (Masson et al., 2024). A later sGRB/BNS world-model study used AfterglowPy to predict Rubin/LSST and Roman afterglow rates, estimating $\xi_N$2 on-axis afterglows and $\xi_N$3 orphan afterglows per year for LSST Wide-Fast-Deep, while emphasizing that discoverable afterglows within the projected aLIGO O5 BNS range remain below one event per year for the considered scenarios (Dimitrova et al., 16 Jun 2026).

6. Limitations, degeneracies, and comparison with more detailed models

The package’s simplifying assumptions are repeatedly emphasized in the application literature. The TESS afterglow study states explicitly that afterglowpy does not include an initial coasting phase, does not include reverse shocks, and assumes a constant-density circumburst medium; these omissions made the onset-delay parameter $\xi_N$4 necessary for fitting very early optical data (Roxburgh et al., 2023). Other studies add that afterglowpy does not account for an external wind medium or synchrotron self-absorption in the relevant modeling setup, and that in some configurations finite $\xi_N$5 disables jet spreading (Gupta et al., 2024, Li et al., 2024).

These assumptions create practical degeneracies. TESS-only optical light curves left $\xi_N$6 and $\xi_N$7 especially degenerate, to the point that broad uniform priors and nonlinear least squares were adopted after Bayesian samplers failed to converge (Roxburgh et al., 2023). Sparse radio data for the GW190814 candidate allowed several jet geometries to fit the light curve, yet morphology later ruled out the GRB interpretation (Tandon et al., 2021). The GRB 160625B analysis showed that even with exceptional broadband coverage, inferred energetics remain highly sensitive to whether $\xi_N$8 is fixed to unity or allowed to vary (Cunningham et al., 2020).

Comparison papers highlight where afterglowpy sits relative to more detailed physical engines. A kinetic TeV-afterglow study compared a modified Katu code to afterglowpy and reported good agreement except at early times off axis, where baryon loading becomes important. In that work, afterglowpy served as the semi-analytical synchrotron benchmark and as the source of best-fit GRB 170817A parameters later rescaled for the kinetic model (Hope et al., 15 Jan 2025). The jetsimpy paper presents a reduced hydrodynamic alternative that accepts arbitrary tabulated angular energy and Lorentz-factor profiles, compares favorably with hydrodynamic simulations and semianalytic methods, and shows generally good agreement with afterglowpy while attributing some differences, particularly for narrow-jet spreading, to its more explicit hydrodynamic treatment (Wang et al., 2024).

A plausible implication is that afterglowpy is most reliable as a fast, physically motivated forward model for structured-jet synchrotron afterglows in regimes where constant-density forward shocks dominate and where the primary scientific task is comparative inference rather than exhaustive microphysical completeness. The same literature also makes clear that robust inference often requires supplemental information—broadband spectra, radio imaging, astrometry, prompt-emission constraints, or joint thermal-nonthermal modeling—because light curves alone frequently do not isolate jet structure, viewing geometry, and microphysical parameters (Tandon et al., 2021, Ryan et al., 2023, Singh et al., 29 Dec 2025).