ska_pst.common

This package provides common classes used by the different submodules of ska-pst.

class ska_pst.common.ChannelisationStage(*, num_frequency_channels: int, oversampling_ratio: Union[Tuple[int, int], List[int]])[source]

A data class used to store the configuration for a channelisation stage.

num_frequency_channels: int: Number of channels used in the channelisation stage.

oversampling_ratio: Union[Tuple[int, int], List[int]]

The oversampling ratio for the channelisation stage.

This is represented as a tuple like (4, 3) or a list with only 2 elements.

class ska_pst.common.FrequencyBandConfig(*, udp_format: str, tsamp: float, udp_nchan: int, udp_nsamp: int, wt_nsamp: int, nbit: int, oversampling_ratio: ~typing.Union[~typing.Tuple[int, int], ~typing.List[int]], max_chan: int, rf_freq_bottom_mhz: float, rf_freq_top_mhz: float, rf_bw_mhz: float, chan_separation_khz: float, first_stage_channel_bw_mhz: float, ring_buffer_config: ~ska_pst.common.frequency_band.RingBufferConfig, channelisation_stages: ~typing.List[~ska_pst.common.frequency_band.ChannelisationStage] = <factory>, ndim: int = 2, npol: int = 2)[source]

A data class used to represent frequency band constants.

This class also includes utility methods that can be used to calculate values like nchan, and bytes_per_sec given other values.

bandwidth_mhz(nchan: Optional[int] = None) → float[source]

Get the bandwidth given the number of channels.

If nchan == None then this value will return the maximium bandwidth based on the max_chan property.

Parameters: nchan (int | None, optional) – the number of channels, defaults to the max_chan value of the configuration.
Returns: the calculated bandwidth, in MHz, given the configuration.
Return type: float

calculate_channel_range(bandwidth_mhz: float, centre_freq_mhz: float) → Tuple[int, int][source]

Calculate the start and end channel given a centre frequency and bandwidth.

The total number of channels is calculated from the bandwidth, tsamp and oversampling ratio of the frequency band configuration.

Parameters

bandwidth_mhz (float) – the required bandwidth of the RF signal, in MHz.
centre_freq_mhz (float) – the centre frequency of the RF signal, in MHz.

Returns

a tuple representing the range of the channels, inclusive of the start channel but exclusive of the end channel: [start_chan, end_chan)

Return type

Tuple[int, int]

centre_freq_mhz(start_chan: int = 0, nchan: Optional[int] = None) → float[source]

Get the centre frequency, in MHz, based on the start channel and the number of channels.

Parameters

start_chan (int, optional) – the start channel, defaults to 0
nchan (int | None, optional) – the number of channels, defaults to the max_chan value of the configuration.

Returns

the calculated centre frequency given the channel separation, bottom frequency, starting channel, and number of channels.

Return type

float

chan_separation_khz: float: The frequency separation between the start and end of a channel, in kHz.

property channel_0_start_freq_mhz: float: Get the effective start frequency of channel 0.

channelisation_stages: List[ChannelisationStage]: The configuration used in the channelisation of the RF signal by the CBF.

data_rate(nchan: Optional[int] = None) → float[source]

Get the data rate, in bytes/second, for the given number of channels.

If nchan == None then this value will return the maximium data rate based on the max_chan property.

Parameters: nchan (int | None, optional) – the number of channels, defaults to the max_chan value of the configuration.
Returns: the calculated number of bytes per second.
Return type: float

first_stage_channel_bw_mhz: float: The bandwidth of the first stage channelised channels, in MHz.

max_chan: int: The maximum number of channels for the frequency band.

nbit: int: The number of bits per sample.

nchan_for_bandwidth(bandwidth_mhz: float) → int[source]

Get the number of channels closest to the given bandwidth.

This determines the number of channels the given bandwidth, in MHz, would be equivalent to given the tsamp and oversampling_ratio.

The output number of channels is given as a multiple of udp_nchan.

Parameters: bandwidth_mhz (float) – the desired bandwidth, in MHz.
Returns: the closest number of channels, as a multiple of udp_nchan that span the given bandwidth.
Return type: int

nchan_for_data_rate(data_rate: float) → int[source]

Calculate the number of channels given a input data rate.

The calculation of the input bytes per seconds is given by:

data_rate = nchan * npol * nbit * ndim / 8 / (tsamp / 1e6)

However, this method ensures the output nchan is not greater than the max_chan value but is also a multiple of udp_nchan.

Parameters: data_rate (float) – the requested input data rate, in bytes per second.
Returns: the number of channels needed to get to a data rate close to data_rate
Return type: int

ndim: int = 2

The number of dimensions of the input data.

If the value is 1, then the input data is real valued. If the value is 2 then the input data is complex valued. The default is 2 (i.e. complex valued data).

npol: int = 2

The number of polarisations of the input data.

The default is 2.

property num_channelisation_stages: int: Get the number of stages of channelisation for the frequency band.

oversampling_ratio: Union[Tuple[int, int], List[int]]

The oversampling ratio for the frequency band.

This is represented as a tuple like (4, 3) or a list with only 2 elements.

rf_bw_mhz: float: The bandwidth of the band, in MHz.

rf_freq_bottom_mhz: float: The bottom end of the frequency band, in MHz.

rf_freq_top_mhz: float: The top end of the frequency band, in MHz.

ring_buffer_config: RingBufferConfig: Configuration specific for setting up ring buffers.

tsamp: float: The time per sample, in microseconds.

udp_format: str: The UDP format for the given frequency band.

udp_nchan: int: The number of channels in an UDP packet.

udp_nsamp: int

The number of samples per channel in an UDP packet.

For each of the udp_nchan channels in an UDP packet there are this many samples.

wt_nsamp: int

The number of samples per weight per channel in an UDP packet.

This value should be the same as udp_nsamp

class ska_pst.common.RingBufferConfig(*, num_buffers: int, packets_per_buffer: int)[source]

A data class used to store ring buffer (RB) configuration for a frequency band.

An element within the RB is configured to be large enough to capture all the channels of the subband for packets_per_buffer number of packets.

num_buffers: int: Number of buffers withing a ring buffer.

packets_per_buffer: int: The number of UDP packets per buffer that a channel needs be recorded for.

ska_pst.common.get_frequency_band_config(frequency_band: Optional[str] = None, **kwargs: Any) → FrequencyBandConfig[source]

Get the configuration specific for a frequency band.

This will return the configuration that is specific to a frequency band. The standard for SKA is that if the frequency_band is only set or is “low” then it corresponds to the Low telescope, which has only one band. Frequency bands of 1, 2, 3, 4, 5a, or 5b will return specific configuration.

Parameters: frequency_band (Optional[str], optional) – the frequency band to get configuration for, defaults to None
Returns: configuration for the frequency band.
Return type: FrequencyBandConfig

ska_pst.common.get_udp_nsamp_for_format(udp_format: str) → int[source]

Get the UDP_NSAMP for a given UDP Format.

Returns: the UDP_NSAMP for the given UDP format.
Return type: FrequencyBandConfig
Raises: AssertionError – if there UDP format is unknown.