API documentation

This section describes the main entry points for the emulator API. While most users will be using the emu-send program, the sender code can be embedded directly into arbitrary python programs, like in the case of the CBF-SDP Emulator TANGO Devices.

ska_sdp_cbf_emulator.packetiser module

Primary send functions for ska-sdp-cbf-emulator

class ska_sdp_cbf_emulator.packetiser.SdpConfigDbConfig(host: str = '127.0.0.1', port: int = 2379, backend: str = 'etcd3')

Set of options used to establish a connection to the SDP Configuration DB.

backend: str = 'etcd3'

The backend to use

host: str = '127.0.0.1'

The host to connect to.

port: int = 2379

The port to connect to

class ska_sdp_cbf_emulator.packetiser.SenderConfig(scan_id: int = 1, subarray_id: int = 1, beam_id: int = 1, zoom_window_id: int = 1, time_interval: float = 0, ms: ~ska_sdp_cbf_emulator.data_source.measurement_set.MeasurementSetDataSourceConfig | None = None, hardcoded: ~ska_sdp_cbf_emulator.data_source.hardcoded.HardcodedDataSourceConfig | None = None, transmission: ~ska_sdp_cbf_emulator.transmitters._config.Config = <factory>, sdp_config_db: ~ska_sdp_cbf_emulator.packetiser.SdpConfigDbConfig = <factory>, hardware_id: int = 48879)

Configuration for a data sending operation

beam_id: int = 1

If emulating LOW, the station beam id

hardcoded: HardcodedDataSourceConfig | None = None

The configuration for generating hardcoded visibilities

hardware_id: int = 48879

The hardware id of the emulator

ms: MeasurementSetDataSourceConfig | None = None

The configuration for reading the input MS.

scan_id: int = 1

The Scan ID to use for all payloads in transmission.

sdp_config_db: SdpConfigDbConfig

The configuration to connect to the SDP Configuration Database

subarray_id: int = 1

If emulating LOW, the subarray id

time_interval: float = 0

The period of time to wait between sending data for successive data dumps. Positive values are used as-is. A value of 0 means to use the time differences in the successive visibility time steps. Negative values mean to not wait, sending data as fast as possible.

transmission: Config

The configuration for transmitting data over the network.

zoom_window_id: int = 1

If emulating LOW, the zoom window id

async ska_sdp_cbf_emulator.packetiser.packetise(config: SenderConfig)

Reads data off a Measurement Set and transmits it using the transmitter specified in the configuration.

Uses the vis_reader get data from the measurement set then gives it to the transmitter for packaging and transmission. This code is transmission protocol agnostic.

async ska_sdp_cbf_emulator.packetiser.packetise_visibilities(config: SenderConfig, data_source: CorrelatedDataSource)

Reads data from the provided data source and transmits it using transmitter specified in the configuration.

ska_sdp_cbf_emulator.packetiser.to_sender_config(dict_config: dict) → SenderConfig

Turn a dictionary into a SenderConfig object.

ska_sdp_cbf_emulator.emulator module

Asynchronous cbf emulator runners.

async ska_sdp_cbf_emulator.emulator.arun_cbf_emulator(scan_monitor_or_exec_block_id: SdpConfigScanMonitor | str, config: SenderConfig)

Asynchronously runs a scan monitor and scan sender until the last packet is sent after the monitor detects the execution block has been ended.

Either a ScanMonitor object or an Execution Block ID can be given as the first parameter. In the latter case, a ScanMonitor object is automatically created and used.

ska_sdp_cbf_emulator.transmitters module

class ska_sdp_cbf_emulator.transmitters.Config(method: str = 'spead2_transmitters')

Base configuration for all transmitters

method: str = 'spead2_transmitters'

The method used to transmit

ska_sdp_cbf_emulator.transmitters.spead2_transmitters module

Implementation for the SPEAD2 network transport

This module contains the logic to take ICD Payloads and transmit them using the SPEAD protocol.

class ska_sdp_cbf_emulator.transmitters.spead2_transmitters.Spead2SenderPayload(telescope: Telescope, init_data: TransmitterInitData, first_channel_id: int, channel_idxs: slice)

SPEAD2 payload following the CSP-SDP interface document

property baseline_count

The number of baselines in this payload

property channel_count

The number of channels contained in this payload

get_data_heap()

Returns a data heap to be sent over the network.

get_end_heap()

Returns an end-of-stream heap to be sent over the network.

get_start_heap()

Returns a start-of-stream heap to be sent over the network.

property hardware_id

The ID of the hardware source of this payload

property scan_id

The ID of the scan of this payload

class ska_sdp_cbf_emulator.transmitters.spead2_transmitters.Spead2TransmissionConfig(method: str = 'spead2_transmitters', telescope: Telescope = Telescope.MID, max_packet_size: int = 1472, rate: float = 1073741824.0, max_heaps: int = 1, num_streams: int | None = None, channels_per_stream: int = 0, sender_threads: int = 1, delay_start_of_stream_heaps: int = 0, endpoints: str | None = None, target_host: str | None = '127.0.0.1', target_port_start: int | None = 41000, buffer_size: int | None = None, transport_protocol: TransportProtocol = TransportProtocol.UDP)

Configuration for transmission of data using spead2

buffer_size: int | None = None

The socket buffer size, used by spead2. If not given, a default value is calculated based on the default value set by spead2, and the limits imposed by the OS.

channels_per_stream: int = 0

DEPRECATED, use num_streams instead.

Number of channels for which data will be sent in a single stream. 0 means to send all channels over one stream.

delay_start_of_stream_heaps: int = 0

The number of data heaps to send on each stream before sending the corresponding start-of-stream (SOS) heaps. 0 (default) means don’t delay the sending of the SOS heaps, < 0 means never send the SOS heaps. Note that non-zero values emulate out-of-order transmission for the SOS heaps.

endpoints: str | None = None

The endpoints where data will be sent to. If present, target_host and target_port_start are ignored. If given, is a comma-separated list of endpoint specifications, where each endpoint specification takes the form of host:ports, where ports is either a single number, or a range like start-end. For example, 127.0.0.1:8000,127.0.0.1:8001 and 127.0.0.1:8000-8001 are equivalent.

get_endpoints(num_streams) → Iterator[Tuple[str, int]]

An iterator over all endpoints, however they were defined by the user.

max_heaps: int = 1

The maximum number of heaps that can be in-flight.

max_packet_size: int = 1472

The maximum size of packets to build, used by spead2

method: str = 'spead2_transmitters'

The method used to transmit

num_streams: int | None = None

Number of streams this sender should use to send data through. This option should be preferred over channels_per_stream (which is now deprecated).

When the number of streams is more than the number of channels to send, this value is adjusted to be the same as the number of channels to avoid creating streams where data is never sent. Also, if this value is not an exact divisor of the number of channels, channels are distributed as evenly as possible across streams, with more channels assigned to the first streams in the list of streams.

rate: float = 1073741824.0

The send data rate, in [bytes/s]. Declared as a float both for convenience (e.g. users can specify 1e9 instead of 1000000000) and backwards compatibility, but cast to an integer when used. 0 means send as fast as possible.

sender_threads: int = 1

Number of threads to use for network operations.

target_host: str | None = '127.0.0.1'

The host where data will be sent to.

target_port_start: int | None = 41000

The first port where data will be sent to.

telescope: Telescope = 'mid'

The telescope to emulate.

transport_protocol: TransportProtocol = 'udp'

The network transport protocol used by spead2.

class ska_sdp_cbf_emulator.transmitters.spead2_transmitters.TransportProtocol(value)

An enumeration of supported transport protocols for transmission.

ska_sdp_cbf_emulator.transmitters.spead2_transmitters.parse_endpoints(endpoints_spec)

Parse endpoint specifications.

Each endpoint is a colon-separated host and port pair, and multiple endpoints are separated by commas. A port can be a single number or a range specified as “start-end”, both inclusive.

class ska_sdp_cbf_emulator.transmitters.spead2_transmitters.transmitter(config: Spead2TransmissionConfig)

SPEAD2 transmitter

This class uses the spead2 library to transmit visibilities over multiple spead2 streams. Each visibility set given to this class’ send method is broken down by channel range (depending on the configuration parameters), and each channel range is sent through a different stream.

property channels_per_stream

Utility property containing the number of channels sent in all streams. This is only valid if all streams send the same number of channels, so it must be used with care.

async close()

Sends the end-of-stream message

config_class

alias of Spead2TransmissionConfig

async prepare(init_data: TransmitterInitData)

Create the sending SPEAD streams

async send(datum: CorrelatedDatum)

Send a visibility set through all SPEAD2 streams

Parameters:

• timestamp – the visibilities’ timestamp as a UNIX timestamp.

• vis – the visibilities, in ICD order, assumed to start from channel_id=0

• corr_data_frac – the correlated fraction of the visibilities, in ICD order