dedispulse

dedispulse is an Apple Silicon accelerated dedispersion tool for pulsar SIGPROC filterbank data. It reads .fil files, applies incoherent dedispersion on Metal, and produces folded profiles plus diagnostic artifacts for inspecting the result.

The first built-in target preset is PSR B0329+54:

DM:      26.76 pc cm^-3
period:  0.71452 s
bins:    256

It produces a single composite diagnostic plot for each run:

Setup

Install build and plotting dependencies:

brew install cmake
python3 -m pip install numpy matplotlib

Data

dedispulse is intended for standard SIGPROC .fil files. The current validation dataset is CAMRAS/Dwingeloo B0329+54 data, available here.

Put downloaded CAMRAS files under:

data/camras/

This directory is ignored by git. For the current test dataset, use:

data/camras/2018-03-16-11_50_30_B0329+54.fil
data/camras/2018-03-16-11_50_30_B0329+54.txt

The .txt file is optional but recommended. It contains the human-readable CAMRAS filterbank header, including the folding period and DM:

Folding period             : 0.71457707007
Folding dispersion measure : 26.8644275665

Sidecar auto-detection uses the same basename as the .fil, with .txt. When present, this CAMRAS-specific sidecar overrides the built-in B0329+54 DM and period unless DM= or PERIOD= is passed explicitly.

Make Commands

make help
make build
make test
make inspect
make analyze
make plot

Default input:

data/camras/2018-03-16-11_50_30_B0329+54.fil

Default run directory:

runs/b0329_camras_20180316_1150

Available commands:

# Inspect embedded SIGPROC metadata, plus sidecar metadata when present.
make inspect

# Run Metal dedispersion, fold, write artifacts, and generate sweeps.
make analyze

# Write only the Metal dedispersed time series and supporting metadata.
make dedisperse

# Generate the composite diagnostic overview image.
make plot

# Full local smoke test.
make smoke

Override inputs and output directories:

make analyze FILE=data/camras/other.fil RUN=runs/other
make plot RUN=runs/other

Override sidecar, DM, or period:

make analyze SIDECAR=data/camras/header.txt RUN=runs/with_sidecar
make analyze DM=26.76 PERIOD=0.71452 RUN=runs/manual_values

Output Artifacts

Each run directory contains:

manifest.json              run options, SIGPROC metadata, sidecar metadata
metrics.json               S/N, DM, period, and delay metrics
channel_stats.csv          per-channel mean and RMS before normalization
delays.csv                 channel frequencies and integer delay samples
dedispersed.f32            float32 dedispersed time series
profile.csv                folded pulse profile
dm_sweep.csv               peak S/N vs DM around the chosen DM
period_sweep.csv           peak S/N vs period around the chosen period
dm_period_heatmap.csv      peak S/N grid over DM and period
plots/overview.png         composite diagnostic plot

The overview image includes:

run/header stats
bandpass
channel RMS
dedispersion delay curve
dedispersed time series
folded profile with peak/+3 sigma markers
pulse stack/subintegrations
DM sweep
period sweep
DM-period heatmap

Planned Features

Current scope:

• SIGPROC .fil input
• Incoherent dedispersion
• Period folding
• Profile and S/N output
• Validation with public B0329+54 data

Not included yet:

• Barycentric correction
• RFI excision
• Live SDR capture
• Raw I/Q channelization
• PSRFITS/PSRCHIVE support
• Broad blind search