# dspsr

## 1.0 Purpose

The Digital Signal Processing for Pulsars (`dspsr`) program
reduces radio pulsar astronomical time series, producing one or more
folded pulse profiles. The main features of this program are as
follows:

* makes optimal use of multiple core architectures using POSIX threads;
* can attach to the
  [PSRDADA](http://psrdada.sourceforge.net)
  shared memory ring buffer to [process data directly from RAM](dspsr/shm.md);
* processes both phase-coherent and detected data;
* Jenet & Anderson (1998) dynamic output level setting;
* phase-coherent dispersion removal;
* filterbank generation (with simultaneous dispersion removal);
* full-polarimetric detection;
* profile folding using a constant period, tempo polyco, tempo2
  predictor, or acceleration search parameters;
* data may be divided into sub-integrations of arbitrary length,
  including single pulses;
* multiple pulsars (e.g. globular cluster) may be folded simultaneously;
* folded profiles can be output in PSRFITS format.

## 2.0 Usage

The default behaviour of dspsr depends upon the state of the input
data. If the input data

* have already been detected, then dspsr will simply fold the data
  into the given number of polarization and frequency channels.
* are undetected voltages, then dspsr will perform phase-coherent
  dispersion removal before detecting (full-polarization, if possible)
  and folding.

There are a number of different options and uses for dspsr.
The following pages describe how to

* [download and process some example data;](dspsr/example.md)
* Process data in different file formats, including
  + [data with a PSRDADA header](dspsr/dada.md)
  + [VLBI Data Interchange Format (VDIF)](dspsr/vdif.md)
* [optimize FFT performance;](dspsr/optimize.md)
* [configure dspsr to use GPU acceleration;](dspsr/gpu.md)
* [read data from a ring buffer in shared memory;](dspsr/shm.md)
* [configure spectral-kurtosis based RFI mitigation](dspsr/sk-config/index.md)
* [fold survey candidates;](dspsr/survey.md)
* [perform polarimetric calibration;](label-psrsh-calibration)
* [search for giant pulses;](label-psrsh-giant-pulse)
* [perform a matched-filter search for pulses; and](label-psrsh-matched-filter)
* [write floating point time series to file](dspsr/dump.md)

```{toctree}
:hidden:

dspsr/example
dspsr/dada
dspsr/vdif
dspsr/optimize
dspsr/gpu
dspsr/shm
dspsr/sk-config/index
dspsr/survey
dspsr/psrsh
dspsr/dump
```

## 3.0 Algorithms

## 4.0 Testing and examples

## 5.0 Known bugs and features that require implementation

* It would be great if dspsr could compute the cyclostationary
  statistics of the electric field