Pulsar plugin

The EDD.pulsar collection provides GPU-accelerated pulsar timing, search, baseband recording, and LEAP voltage-processing modes. It receives packetized polarization or channelized-voltage streams, stages them through PSRDADA buffers, and invokes DSPSR-family processing tools or disk writers.

This page was verified against collection version 1.0.1 in the supplied repository.

Roles and lifecycle

EDD.pulsar.pulsar: Current general-purpose pulsar pipeline. Default product name is pulsar_pipeline. It is a measuring pipeline and installs pipeline, receiver, DSPSR, and diagnostic-sensor dashboard panels.
EDD.pulsar.rfsoc_pulsar_pipeline: RFSoC-specific role retained in the collection. Its supplied task currently uses legacy mpikat paths and a short common-role name; validate and update it against the pinned core before using it in a new site.

Modes and products

Timing: Coherently dedisperses and folds with dspsr using a generated Tempo2 predictor. Produces pulsar archives and diagnostic profile plots. A readable ephemeris is required; the pipeline can fall back to the installed pulsar catalogue when configured data do not contain one.
Searching: Uses digifits to produce coherently dedispersed PSRFITS search-mode filterbanks with configurable time and frequency resolution.
Baseband: Writes merged voltage data to DADA files for offline processing.
Leap: Captures voltage data with LEAP-specific header and recording behaviour.

All modes use scan-specific telescope metadata to construct headers and output directories. Source name, receiver, frequency, bandwidth, sample clock, synchronization epoch, project or observation ID, and noise-diode state must be available from the stream or Telescope Metadata Interface.

Input formats

The default inputs are two MPIFR_EDD_Packetizer:2 streams, one per polarization. The pipeline also contains handling for channelized formats such as AlveoPFB:1, AlveoPFB:2, and SkarabPFB:1. Channelized input may be distributed across several multicast groups and processing instances.

Input descriptors must have consistent timestamps, sample rates, heap sizes, band ordering, and polarization labels. Incorrect ordering can produce scientifically plausible but invalid polarization or frequency metadata.

Main configuration

Mode and science configuration
Key	Default	Meaning
`mode`	`Timing`	`Timing`, `Searching`, `Baseband`, or `Leap`.
`cdd_dm`	0	Coherent-dedispersion DM. A non-zero value overrides the ephemeris DM.
`nchannels`	512	Archive channels in timing mode.
`nbins`	1024	Pulse-phase bins in timing mode.
`filterbank_nchannels`	512	Search-mode channels before frequency decimation.
`decimation`	1	Search-mode frequency decimation.
`tsamp`	0.0000512 s	Search-mode output time resolution.
`nsblk`	2048	Samples per PSRFITS block.
`npol`	4	Search output products: normally 1 for intensity or 4 for coherences.
`file_length`	empty	Search-file duration. When set, it must be compatible with `tsamp * nsblk`.
`zaplist`	`1200:1230`	MHz ranges blanked in online diagnostic displays.
`single_pol` / `pol_number`	0 / 0	Enable and select single-polarization capture.
`ignore_noise_diode`	0	Disable calibration-diode handling when set.
`effelsberg_cal_convention`	true	Treat the Effelsberg source-name suffix convention as a calibrator flag.

Ephemeris, performance, and output configuration
Key	Default	Meaning
`ephemeris_data_source`	nested mapping	Local path, optional remote and branch, relative par-file path, and pull policy. The role data scope is the normal persistent location.
`tempo2_telescope_name`	`Effelsberg`	Observatory code used to generate a Tempo2 predictor.
`fft_length`	8192	Coherent-dedispersion filter length.
`merge_threads`	2	Threads merging input parts into the processing buffer.
`dspsr_threads`	1	CPU threads allocated to DSPSR processing.
`mkrecv_nthreads`	8	Receiver threads. Validate against stream count and NUMA-local CPUs.
`dbdisk_writing_threads`	2	Baseband disk-writer threads.
`data_directory`	`auto`	Output location or template. `auto` uses the pipeline data scope and telescope metadata.
`stall2error`	false	Promote an unprocessable scan, such as a missing pulsar ephemeris, from stalled to error.
`dummy_input`	false	Test data source; must remain false for observations.

Keys under dada_header_params, dada, dadc, dspsr_params, and digifits_params are expert controls. Changes affect buffer allocation, header semantics, or raw command-line arguments and require a provision test.

Minimal product

{
  "id": "pulsar_pipeline",
  "mode": "Timing",
  "nchannels": 1024,
  "nbins": 1024,
  "input_data_streams": [
    {
      "source": "dig_pack_controller:polarization_0",
      "format": "MPIFR_EDD_Packetizer:2"
    },
    {
      "source": "dig_pack_controller:polarization_1",
      "format": "MPIFR_EDD_Packetizer:2"
    }
  ]
}

Monitoring and operations

The plugin exposes source, central frequency, channel count, phase-bin count, DM, processing time, input and output DADA fill levels, and diagnostic PNG sensors. Image-valued sensors are excluded from InfluxDB and retained through the Redis sidecar. Watch receiver loss and both DADA buffers throughout a scan.

Timing mode stalls when the source is neither a recognized pulsar nor a calibrator and a usable ephemeris cannot be obtained. Search and baseband modes can exhaust storage rapidly; calculate the output rate and verify retention and transfer before capture starts. On measurement stop, confirm that expected files are registered with the pipeline and closed on disk.

Testing

The collection supplies unit tests and the provision-test module edd.pulsar.pulsar_processing_tests. Test each enabled mode separately with the site’s real input format, metadata source, GPU type, and storage mount.