English | 简体中文

AstroFlow 🌌

One stop realtime GPU-accelerated single-pulse/FRB search pipeline

• ⚡ GPU-Accelerated Processing - CUDA dedispersion with advanced optimizations (FMA, shared memory, loop unrolling)
• 🤖 AI-Powered Detection - YOLOv11n trained on 100k+ sim FRBs dataset with high accuracy
• 🧹 Complete RFI Mitigation - RFI removal with PSRFITS & FILTERBANK support
• ⚙️ User-Friendly Pipeline - Simple YAML configuration with Docker deployment and bilingual interface

Feedback: use Issues or Discussions.

Updates

• Sep 10, 2025 - feat: GPU-accelerated IQRM algorithm implementation based on Bhardwaj et al. (2022) with enhanced RFI configuration
• Aug 22, 2025 - feat: Add GPU-accelerated RFI marking and decouple CPU/GPU implementations
• Aug 21, 2025 — Public preview of astroflow CLI ; CUDA dedispersion and YOLO-based detector integrated.
• Aug 20, 2025 — Docker image (CUDA 12.x, PyTorch) and end-to-end benchmark scripts.

Preview

Methods

pip install

1. Python 3.10–3.12 recommended.

2. Install:

   pip install pulseflow

3. Quick start: see quick start

source code

1. cudatoolkit>=12.0 glibc>=2.27 gcc/gxx>=11.0 ubutnu18.04+.

2. git clone

   git clone https://github.com/lintian233/astroflow 
   cd astroflow

3. build from soure

   source configure.sh

4. pip install

   pip install -e .

Citation

If you use AstroFlow in your research, please cite our work:

Note

Our scientific paper describing the AstroFlow pipeline is currently in preparation. We will update this section with the proper paper citation once our manuscript is published. Please check back for updates or watch this repository for announcements. In the meantime, please cite this repository:

@misc{astroflow2025,
  title={AstroFlow: GPU-accelerated single-pulse/FRB search pipeline},
  author={lintian233},
  year={2025},
  url={https://github.com/lintian233/astroflow},
  note={Software pipeline for fast radio burst detection and analysis}
}

YAML Configuration

Below are the commonly used YAML configuration options:

Basic Configuration

Option	Description	Example	Required
input	Input file path or directory	B0534+2200.fil/fits	✓
output	Output directory path	B0534+2200_results	✓
mode	Processing mode	single/multi/monitor/dataset	✓
candpath	Candidate file path (for dataset mode)	candidates.csv	Only for dataset mode

GPU and Processing

Option	Description	Example	Default
dedgpu	GPU ID for dedispersion	0	0
detgpu	GPU ID for detection	1	0
cputhread	Number of CPU threads	64	8
plotworker	Number of plot workers	16	4

Detection Parameters

Option	Description	Example	Default
confidence	Detection confidence threshold	0.4	0.372
snrhold	SNR threshold	5	5
modelname	Detector model type	current only yolov11n
modelpath	Path to customodel weights	model.pt	-
timedownfactor	Time downsampling factor	8	1

Time and DM Configuration

Option	Description	Example
tsample	Time sampling configurations	See below
dm_limt	DM limit ranges	See below
dmrange	DM search ranges	See below

tsample:
  - name: t0
    t: 0.5  # seconds (for single pulse)

dm_limt:
  - name: limt1
    dm_low: 50
    dm_high: 60
  - name: limt4
    dm_low: 100
    dm_high: 700

dmrange:
  - name: dm1
    dm_low: 50
    dm_high: 60
    dm_step: 0.018
  - name: dm3
    dm_low: 80
    dm_high: 700
    dm_step: 1

Frequency Configuration

Option	Description	Example
freqrange	Frequency ranges for processing	See below

freqrange:
  - name: freq1
    freq_start: 1030  # MHz
    freq_end: 1445    # MHz (full band)
  - name: freq2
    freq_start: 1030
    freq_end: 1250    # MHz (sub-band 1)
  - name: freq3
    freq_start: 1250
    freq_end: 1445    # MHz (sub-band 2)
    # For FAST data
  - name: freq3
    freq_start: 1000
    freq_end: 1499.5  # MHz

RFI Mitigation

Option	Description	Example	Default
rfi	RFI configuration	See below	-
maskfile	Single RFI mask file	/path/to/file	-
maskdir	Directory containing RFI masks	/path/to/RFI_MASK/	-

RFI Configuration:

rfi:
  use_mask: 0      # Use external mask files (0/1)
  use_iqrm: 1      # Use IQRM algorithm for RFI detection (0/1)
  use_zero_dm: 1   # Use zero-DM for RFI detection (0/1)

iqrm:
  mode: 1            # Statistical mode: 0=mean, 1=std
  radius_frac: 0.10  # Radius fraction for lag selection
  nsigma: 3.0        # Sigma threshold for outlier detection
  geofactor: 1.5     # Geometric factor for lag progression
  win_sec: 0         # Window size in seconds (0 for full data)
  hop_sec: 1.0       # Hop size in seconds for sliding windows
  include_tail: true # Include remaining data at the end

# Traditional mask-based RFI mitigation
maskfile: /path/to/maskdfile.bad_chans
# OR use directory for multiple files
maskdir: /path/to/maskdir

RFI IQRM Algorithm: AstroFlow implements the IQRM (Iterative Quartile Range Mitigation) algorithm described in Bhardwaj et al. (2022) with full GPU acceleration.

Plotting Configuration

Option	Description	Example
dmtconfig	DMT Plot Config	See below

dmtconfig:
  minpercentile: 0           # Minimum percentile for scaling
  maxpercentile: 100         # Maximum percentile (99.9 for FAST data)
  meadianbulr: 1 3          # Median blur for DMT plot
  guassion: 1 5             # Gaussian filter for DMT plot

Option	Description	Example
specconfig	Spectrum Plot Config	See below

specconfig:
  minpercentile: 0          # Minimum percentile for scaling
  maxpercentile: 100        # Maximum percentile for scaling
  tband: 20                 # Time band in ms (120 for FAST data)
  mode: subband             # Plot mode: subband/standard

Real Examples

FAST_PREX Dataset Processing:

For a detailed guide on processing this dataset, see the FAST PREX Dataset Tutorial.

Single Pulsar Observation (Crab):

input: B0534+2200_20250413_194909_ant01p0.fil 
output: B0534+2200_20250413_194909
mode: single

timedownfactor: 1
confidence: 0.4
dedgpu: 0
detgpu: 1
cputhread: 32

snrhold: 5
modelname: yolov11n
# use default
# modelpath: yolo11n_0816_v1.pt 

rfi:
  use_mask: 0
  use_iqrm: 1
  use_zero_dm: 1

iqrm:
  mode: 1
  radius_frac: 0.10
  nsigma: 3.0
  geofactor: 1.5
  win_sec: 0
  hop_sec: 1.0
  include_tail: true

# Optional: external mask file
# maskfile: file.bad_chans

tsample:
  - name: t0
    t: 0.05

dm_limt:
  - name: limt1
    dm_low: 50
    dm_high: 60

dmrange:
  - name: dm1
    dm_low: 50
    dm_high: 60
    dm_step: 0.018

dmtconfig:
  minpercentile: 0
  maxpercentile: 99.9
  meadianbulr: 1 3
  guassion: 1 5

specconfig:
  minpercentile: 0    
  maxpercentile: 100
  tband: 10 #ms
  mode: subband # subband/standard

Contributors

Star History