Peasoup is a fast, GPU-accelerated time-domain pulsar search pipeline designed to discover compact binary pulsars in high time resolution radio observations. It operates on filterbank files and outputs XML files of candidate detections. It uses the dedisp library (originally written by Ben Barsdell) to perform incoherent dedispersion.
⚠️ Peasoup does not fold candidates. Use tools likepsrfold_fil(recommended),prepfold, ordspsrto fold using candidate outputs.
-
Template Bank Searches:
Peasoupnow supports going beyond acceleration and jerk searches to perform coherent Keplerian binary parameter searches using a template bank. Circular orbit templates use three parameters: orbital angular frequency (ω), projected semi-major axis (τ), and orbital phase (ϕ). Elliptical templates add eccentricity (e) and longitude of periastron (ωₚ), enabling detection of short-period compact orbit binaries. -
CUDA 12.6 Compatibility: Now builds and runs with CUDA versions up to 12.6. Previous issues with legacy texture memory in
dedispare fixed. -
Segmented Acceleration Search Support: Allows you to process specific chunks of a filterbank file using:
--start_sample: Starting sample index.--fft_size: FFT window length.--nsamples(optional): Explicit cap on number of real samples.
What’s the difference?
--fft_size: Total number of samples to use for FFT.--nsamples: Upper bound on how many real samples.
Recommended usage: use
--start_sampleand--fft_size. Use--nsamplesonly when you're intentionally truncating the read segment.Example scenarios:
--start_sample=0.25*total,--fft_size=0.5*total: Peasoup reads25%to75%of the filterbank time samples.--start_sample=0.25*total,--nsamples=0.25*total,--fft_size=0.5*total: Peasoup reads only25%to50%of the filterbank samples, and pads an additional0.25*totalof zeros before searching.
-
Coherent DM Correction (
--cdm): If your filterbank file has been coherently dedispersed to a non-zero DM, you can now inform Peasoup using the--cdmflag. This modifies the acceleration plan, making the search step size finer near the coherent DM value and improving sensitivity. -
Single Precision Harmonic Sums: Enabled via
--single_precision_harmonic_sums. Reduces GPU memory and speeds up harmonic summing. -
Presto-Compatible Dedispersed Time Series: Run Peasoup in "dedispersion-only" mode with
-dand--nosearch. This dumps.datfiles compatible with PRESTO. No barycentric correction is applied. Equivalent to PRESTO’sprepdata -nobary -dm $dm $input_file. -
Live Progress Bar: Useful for multi-day or multi-week searches. Activate it with the
-pflag.
docker pull vishnubk/peasoupapptainer pull docker://vishnubk/peasoupgit clone https://github.com/vishnubk/dedisp.git
cd dedisp
make
make install
cd ..
git clone https://github.com/vishnubk/peasoup.git
cd peasoup
make
make installPeasoup supports GPU architectures from sm_60 to sm_90. If you're using a different architecture, edit Makefile.inc and add the appropriate -gencode flags.
Use --acc_start, --acc_end, and either --dm_file or the --dm_start/--dm_end range.
peasoup -i data.fil \
--fft_size 67108864 \
--limit 100000 \
-m 7.0 \
-o output_dir \
-t 1 \
--acc_start -50.0 \
--acc_end 50.0 \
--dm_file my_dm_trials.txt \
--ram_limit_gb 180.0 \
-n 4 \
-p
⚠️ Always specify--fft_size. Peasoup defaults to the next lowest power-of-two if it's missing. WhilecuFFTsupports efficient FFTs for sizes composed of 2, 3, 5, or 7 as prime factors, performance can vary across GPUs. For large-scale surveys, we recommend benchmarking different FFT sizes and explicitly setting--fft_sizeto avoid issues from observations that fall slightly short of the next optimal size.
Peasoup still supports specifying a DM range using --dm_start and --dm_end, allowing dedisp to generate internal trial steps. However, we strongly recommend using the --dm_file flag to provide full control over dispersion trials.
You can generate dm_file using DDplan.py from PRESTO. An example file is available here.
peasoup -i data.fil \
--start_sample 4194304 \
--fft_size 33554432 \
--acc_start -100.0 \
--acc_end 100.0 \
--dm_file dm_trials.txt \
--cdm 33.0 \
-n 4 -t 1 -p -o output_dirUse the segment_pepoch from Peasoup’s XML output (example here) as the reference epoch.
psrfold_fil -v -t 12 --candfile pulsarx.candfile \
-n 64 -b 64 --template meerkat_fold.template \
-f data.fil --pepoch ${segment_pepoch} -o resultsExample pulsarx.candfile:
#id DM accel F0 F1 F2 S/N
0 46.840000 -38.537781 275.478302 0 0 8.938008
1 46.750000 548.444214 162.808395 0 0 8.425230
Bonus Tip: Use psrfold_fil2 for faster dedispersion+folding of hundreds of candidates.
Convert acceleration to Ṗ and shift period to the start of the FFT:
def a_to_pdot(P_s, acc_ms2):
c = 2.99792458e8
return P_s * acc_ms2 / c
def period_correction_for_prepfold(p0, pdot, tsamp, fft_size):
return p0 - pdot * fft_size * tsamp / 2Then fold:
prepfold -topo -noxwin -p ${corrected_period} -pd ${pdot} -dm ${dm} data.filExample predictor file:
SOURCE: J1546-5431
EPOCH: 55739.5399653
PERIOD: 1.466892342 s
DM: 316.2835
ACC: 1.25571819897
RA: 15:46:48.00
DEC: -54:31:00.216
dspsr -P predictor.txt -O folded_output data.filUse the template_bank_generator repository to create a .txt file with one template per line. Each line should contain Keplerian parameters.
Examples are available here.
peasoup -i data.fil \
--start_sample 4194304 \
--fft_size 33554432 \
-K circular_orbit_template_bank.txt \
--dm_file dm_trials.txt \
--cdm 33.0 \
-n 4 -t 1 -p -o output_dirSegmented template bank searches follow the same logic as segmented acceleration searches described above. Just pass the appropriate template bank file for the observation time corresponding to your search segment using the -K flag.
The segment_pepoch corresponds to the start of the FFT segment. No conversion required.
psrfold_fil -v -t 12 --candfile keplerian_pulsarx.candfile \
-n 64 -b 64 --template meerkat_fold.template \
-f data.fil --pepoch ${segment_pepoch} -o resultsExample keplerian_pulsarx.candfile:
#id DM accel F0 F1 F2 Pb A1 T0 OM ECC S/N
0 20.0 0 399.9958801269538 0 0 0.04166666671427778 2.32141701093094 50000.02083333336 0 0 11.1497869491577
prepfold -topo -noxwin -p ${xml_period} -dm ${dm} -bin \
-pb ${xml_pb} -x ${xml_a1} -To ${xml_t0} -w ${xml_omega} -e ${xml_ecc} data.fil--exact_resampler: Use linear interpolation instead of nearest-neighbor. Slower but helpful for known sources.--distill_circular_orbit_cands: Enables candidate filtering in template bank mode (currently off by default).
Peasoup’s performance scales with FFT size and the number of harmonic sums. The table below shows the measured runtimes (in seconds) per binary trial, per DM trial, per beam on an A100 80 GB GPU.
| FFT Size | 8 Harmonics (-n 3) | 16 Harmonics (-n 4) | 32 Harmonics (-n 5) |
|---|---|---|---|
| 2²⁴ | 0.00087 | 0.00126 | 0.00139 |
| 2²⁵ | 0.00173 | 0.00252 | 0.00277 |
| 2²⁶ | 0.00327 | 0.00477 | 0.00525 |
These numbers are useful baselines when estimating total search runtime. Actual performance may vary depending on your GPU model and the amount of RFI in your data.
Peasoup was developed by Ewan Barr with contributions from Vishnu, Vivek, Prajwal, Yunpeng, and Jiri. It has been used to discover over 200 pulsars. If you use Peasoup in your research, please cite this repository.