JinWu Documentation

Joint Inference for high-energy transient light-curve & spectral analysis with Unifying physical modeling.

JinWu (金乌) is a comprehensive Python toolkit for X-ray and gamma-ray astrophysics, bringing together spectral and temporal analysis with unified physical modeling. Named after the mythical three-legged golden crow dwelling in the sun — a fitting symbol for a package that shines light on the most energetic transients in the Universe.

Contents

• Quick Start Guide
  • Reading OGIP FITS Files
  • Working with Energy Bands
  • Computing Net Data
  • Next Steps
• API Reference
  • Core Package
  • jinwu.core Package
  • Datasets & Net Data
  • jinwu.core.datasets Module
  • Lightcurve Analysis
  • jinwu.lightcurve Package
  • Background Modeling
  • jinwu.background Package
  • Spectral Analysis
  • jinwu.spectrum Package
  • Response Matrix Utilities
  • jinwu.response Package
  • Timing Analysis
  • jinwu.timing Package
  • Model Components
  • jinwu.model Package
  • Physics Utilities
  • jinwu.physics Package
  • ftools (Pure-Python HEASOFT Equivalents)
  • jinwu.ftools Package
  • Einstein Probe
  • jinwu.ep Package
  • Fermi/GBM
  • jinwu.fermi Package
  • Swift
  • jinwu.swift Package
  • Application Layer
  • jinwu.application Package
• Light-curve Fitting
  • Example
• Spectral Fitting
  • Basic Fit
  • Chain Analysis
• Upper Limits
  • Example
• Galactic NH (nhtot)
  • Why nhtot?
  • Usage
  • Reference
• RedshiftExtrapolator 使用与原理说明
  • 1. 问题背景与目标
  • 2. 物理论证与关键公式
  • 3. 计算流程（逐步说明）
  • 4. 推导要点回顾（为何这样做）
  • 5. 使用示例
  • 6. 常见问题与注意事项
  • 7. 验证方法
  • 8. 后续改进建议
• Changelog
  • v0.0.27 (2026-06-03)
  • v0.0.26 (2026-05)
  • Earlier Releases

---

Key Features

• OGIP FITS I/O — Read and write ARF, RMF, PHA, lightcurve, and event files

• Lightcurve & Spectral Analysis — Background modeling, trigger evaluation, XSPEC-inspired components

• Multi-mission Support — Einstein Probe (EP), Fermi/GBM, Swift/BAT, and more

• Unified Physical Modeling — Consistent framework across bands and messengers

• Pure-Python ftools — HEASOFT-compatible tools written entirely in Python

• Upper Limit Computation — Bayesian & frequentist upper limits for faint transients

Installation

JinWu’s spectral fitting and XSPEC integration depend on HEASoft/PyXspec and XSPEC model data. We recommend installing these via the HEASARC conda channel, though any working HEASoft installation is fine.

# 1. Install HEASoft + XSPEC + model data via conda
conda create -n hea -c https://heasarc.gsfc.nasa.gov/docs/software/lheasoft/conda \\
    heasoft xspec xspec-data
conda activate hea

# 2. Install JinWu
pip install jinwu

If you already have HEASoft installed outside conda (e.g. from source), JinWu can still use it — call jinwu.core.heasoft.HeasoftEnvManager to initialize the environment:

from jinwu.core.heasoft import HeasoftEnvManager
mgr = HeasoftEnvManager()      # auto-detects HEADAS from env / rc files
mgr.init_heasoft()

For development:

conda activate hea
git clone https://github.com/xinxiangsun/jinwu
cd jinwu
pip install -e ".[docs]"

Note

The HeasoftEnvManager also works in Jupyter notebooks — use HeasoftEnvManager.init_heasoft_in_notebook().

Quick Start

import jinwu as jw

# Read OGIP FITS files
pha = jw.read_pha("source.pha")
lc  = jw.read_lc("lightcurve.fits")

# Work with energy bands
band = jw.EnergyBand(0.3, 10.0, unit="keV")

# General net data computation
net = jw.netdata(src=src_counts, bkg=bkg_counts, exposure=exposure)

Indices and tables

• Index

• Module Index