Signals

Synthetic signal creation tools and builders used by both torchsig.datasets.wideband.NewWideband and torchsig.datasets.narrowband.NewNarrowband for dataset creation.

Signal Class Types

Signal and Signal Metadata classes.

This module defines the Signal and SignalMetadata classes and their associated functionality, which are used to represent and manipulate signal data and metadata.

Examples

Signal:
>>> from torchsig.signals import Signal, SignalMetadata
>>> d = [1.0, 2.0]
>>> m = SignalMetadata(...)
>>> new_sig = Signal(data = d, metadata = m)
class torchsig.signals.signal_types.SignalMetadata(dataset_metadata: DatasetMetadata = None, center_freq: float = None, bandwidth: float = None, start_in_samples: int = None, duration_in_samples: int = None, snr_db: float = None, class_name: str = None, class_index: int = None)[source]

Bases: object

Represents metadata associated with a signal.

dataset_metadata

The dataset metadata for the signal. Defaults to None.

Type:

DatasetMetadata

center_freq

The center frequency of the signal in Hz. Defaults to 0.0.

Type:

float

bandwidth

The bandwidth of the signal in Hz. Defaults to 0.0.

Type:

float

start_in_samples

The start time of the signal in terms of samples. Defaults to 0.

Type:

int

duration_in_samples

The duration of the signal in terms of samples. Defaults to 0.

Type:

int

snr_db

The Signal-to-Noise Ratio in dB. Defaults to 0.0.

Type:

float

class_name

The class name of the signal (e.g., modulation type). Defaults to “None”.

Type:

str

class_index

The class index of the signal in the dataset. Defaults to -1.

Type:

int

property dataset_metadata: DatasetMetadata

Returns the dataset metadata for the signal.

Returns:

The dataset metadata.

Return type:

DatasetMetadata

property sample_rate: float

Signal sample rate

Returns:

sample rate

Return type:

float

property num_samples: int

Signal number of IQ samples

Returns:

number of IQ samples

Return type:

int

property start: float

Signal start normalized to duration of signal

Returns signal start as a percentage of total time, ex: start=0.5 means the signal starts 50% of the way into the dataset IQ samples.

Returns:

signal start

Return type:

float

property stop: float

Signal stop normalized to duration of signal

Returns signal stop as a percentage of total time, ex: stop=0.5 means the signal stops 50% of the way into the dataset IQ samples.

Returns:

signal stop

Return type:

float

property duration: float

Signal duration (normalized)

Returns signal duration normalized from 0.0 to 1.0

Returns:

signal duration

Return type:

float

property stop_in_samples: int

Signal stop in samples

Returns the index where the signal stops in the dataset IQ.

Returns:

signal stop

Return type:

int

property upper_freq: float

Calculates the upper frequency of a signal

Calculates the upper frequency edge, or highest frequency, associated with the bandwidth of the signal.

Returns:

upper frequency

Return type:

float

property lower_freq: float

Calculates the lower frequency of a signal

Calculates the lower frequency edge, or lowest frequency, associated with the bandwidth of the signal.

Returns:

lower frequency

Return type:

float

property oversampling_rate: float

Calculates the oversampling rate for a signal

Calculates the oversampling rate for a signal. If a signal’s bandwidth is 1/2 the sampling rate, the oversampling rate is 2.

Returns:

oversampling rate

Return type:

float

property samples_per_baud: float

Calculates the samples per baud for a signal

Calculates the samples per baud for some signals. Samples per baud is not universal but is accurate for QAM and PSK modulation familes. If the signal’s bandwidth is 1/2 the sampling rate then the samples per baud is 2.

Returns:

samples per baud

Return type:

float

to_dict() → dict[source]

Returns SignalMetadata as a full dictionary

deepcopy() → SignalMetadata[source]

Returns a deep copy of itself

Returns:

Deep copy of SignalMetadata

Return type:

SignalMetadata

verify() → None[source]

Verifies Signal Metadata fields

Raises:

  • MissingSignalMetadata – Metadata missing.

  • InvalidSignalMetadata – Metadata invalid.

class torchsig.signals.signal_types.Signal(data: ndarray = array([], dtype=float64), metadata: SignalMetadata | None = None)[source]

Bases: object

Initializes the Signal with data and metadata.

Parameters:

  • data (np.ndarray, optional) – Signal IQ data. Defaults to np.array([]).

  • metadata (SignalMetadata, optional) – Signal metadata. Defaults to an empty instance of SignalMetadata().

verify()[source]

Verifies data and metadata are valid.

Raises:

ValueError – Data or metadata is invalid.

class torchsig.signals.signal_types.DatasetSignal(data: np.ndarray = array([], dtype=float64), signals: List[Signal] | Signal | List[SignalMetadata] | SignalMetadata | List[Dict[str, Any]] = None, dataset_metadata: DatasetMetadata = None)[source]

Bases: object

DatasetSignal class. Represents a signal within a dataset with metadata.

data

The IQ data of the signal.

Type:

np.ndarray

metadata

The metadata associated with the signal.

Type:

List[SignalMetadata]

Parameters:

  • data (np.ndarray, optional) – The IQ data for the signal. Defaults to np.array([]).

  • signals (List[Signal] | Signal | List[SignalMetadata] | SignalMetadata | List[Dict[str, Any]], optional) – The list of signals or metadata objects associated with the dataset signal.

  • dataset_metadata (DatasetMetadata, optional) – The dataset metadata. Defaults to None.

verify()[source]

Verifies data and metadata are valid.

Raises:

ValueError – Data or metadata is invalid.

class torchsig.signals.signal_types.DatasetDict(signal: DatasetSignal)[source]

Bases: object

DatasetDict class. Represents a dictionary containing signal data and metadata.

data

The IQ data of the signal.

Type:

np.ndarray

metadata

The list of metadata dictionaries associated with the signal.

Type:

List[dict]

index

The index of the signal in the dataset. Defaults to None.

Type:

int, optional

Parameters:

signal (DatasetSignal) – The DatasetSignal instance to extract data and metadata from.

verify()[source]

Verifies data and metadata are valid.

Raises:

ValueError – Data or metadata is invalid.

Signal Builders

Builder

Signal and Composite Signal Builders

Examples
Signal Builder
>>> from torchsig.signals import SignalBuilder
>>> sb = SignalBuilder()
>>> sb.data = np.array([1.0, 2.0])
>>> sb.sample_rate = 1.5
>>> ...
>>> new_signal = sb.build()
Composite Signal Builder
>>> from torchsig.signals import CompositeSignalBuilder, SignalBuilder
>>> builder1 = SignalBuilder()
>>> builder1.data = [1.0, 2.0]
>>> ...
>>> csb = CompositeSignalBuilder()
>>> csb.builders.append(builder1)
>>> csb.sample_rate = 2.0
>>> ...
>>> new_composite_signal = csb.build()
class torchsig.signals.builder.Builder(name: str = 'Builder')[source]

Bases: ABC

Abstract builder class for signals

name

Builder name. Defaults to “Builder”.

Type:

str

abstract build() → Signal[source]

Build and Return Signal() object. To be implemented by subclasses.

Returns:

signal being built.

Return type:

Signal

abstract reset() → None[source]

Resets builder. To be implemented by subclasses.

class torchsig.signals.builder.SignalBuilder(dataset_metadata: DatasetMetadata, class_name: str, **kwargs)[source]

Bases: Builder, Seedable

Signal Builder. Creates a Signal.

dataset_metadata

Dataset metadata for signal.

Type:

DatasetMetadata

class_name

Name of the specific waveform to build, ex: 2fsk, qpsk, ofdm-1024

Type:

str

name

Signal builder name. Defaults to “class_name Signal Builder”

Type:

str

supported_classes

Defines what classes builder supports. Defaults to [].

Type:

List[str]

supported_classes

List of signal class names that the builder supports. Set to [].

Type:

List[str]

supported_classes = []
build() → Signal[source]

Builds and returns Signal

The Builder() __init__ calls reset() which initializes the signal metadata according to default values defined within dataset metadata. _update_metadata() then updates signal-specific metadata fields as needed. _update_data() creates the IQ samples and assigns them to the Signal() data field. _correct_bandwidth_and_snr() sets the power of the signal based on the PSD estimate to have the appropriate SNR and then estimates the total occupied bandwidth of the signal, including sidelobes, to develop a more accurate bounding box. .verify() ensures that the metadata values are withing the appropriate bounds. The Signal() object is then stored for the return call, and reset() is called to reset the signal metadata fields to their dataset metadata defaults.

In order, calls: - _update_metadata() - _update_data() - _correct_bandwidth_and_snr() - _signal.verify() - reset()

Returns:

Signal being built.

Return type:

Signal

reset() → None[source]

Resets _signal according to defaults defined by dataset metadata.

Signal metadata is generated according to the default values as defined by the dataset metadata. The signal data is set to noise samples.

These metadata value can be overridden if a particular modulator or special signal requires it. For example, the bandwidth of a tone is dependent on the signal duration and therefore requires recalculation and an update to the signal metadata inside _update_metadata() in the tone builder class. Similarly, the minimum duration for a constellation based signal must be at least 1 symbol, which requires recomputation in the _update_metadata() field for the constellation builder class.

This method is called by the parent Builder() __init__ and after build().

Specific Signal Builders

class torchsig.signals.builders.ToneSignalBuilder(dataset_metadata: DatasetMetadata, class_name: str = 'tone', **kwargs)[source]

Bases: SignalBuilder

Implements SignalBuilder() for tone waveform.

dataset_metadata

Parameters describing the dataset required for signal generation.

Type:

DatasetMetadata

supported_classes

List of supported signal classes. Set to [“tone”].

Type:

List[str]

supported_classes = ['tone']
class torchsig.signals.builders.ConstellationSignalBuilder(dataset_metadata: DatasetMetadata, class_name: str, **kwargs)[source]

Bases: SignalBuilder

Implements the Constellation family signal generator.

Implements SignalBuilder() for the linearly modulated constellation-based families: QAM, PSK, PAM, ASK, OOK.

dataset_metadata

Parameters describing the dataset required for signal generation.

Type:

DatasetMetadata

supported_classes

List of supported signal classes. Set to TorchSigSignalLists.constellation_signals.

Type:

List[str]

supported_classes = ['ook', 'bpsk', '4ask', 'qpsk', '8ask', '8psk', '16qam', '16ask', '16psk', '32qam', '32qam_cross', '32ask', '32psk', '64qam', '64ask', '64psk', '128qam_cross', '256qam', '512qam_cross', '1024qam']
class torchsig.signals.builders.TestSignalBuilder(dataset_metadata: DatasetMetadata, class_name: str = 'testsignal', **kwargs)[source]

Bases: SignalBuilder

Implements the test signal generator.

Implements SignalBuilder() for a test waveform which is shaped noise. The waveform is useful in development but is not a practical signal.

dataset_metadata

Parameters describing the dataset required for signal generation.

Type:

DatasetMetadata

supported_classes

List of supported signal classes. Set to [“testsignal”].

Type:

List[str]

supported_classes = ['testsignal']
class torchsig.signals.builders.FMSignalBuilder(dataset_metadata: DatasetMetadata, class_name: str = 'fm', **kwargs)[source]

Bases: SignalBuilder

Implements SignalBuilder() for frequency modulation (FM) waveform.

dataset_metadata

Parameters describing the dataset required for signal generation.

Type:

DatasetMetadata

supported_classes

List of supported signal classes. Set to [“fm”].

Type:

List[str]

supported_classes = ['fm']
class torchsig.signals.builders.AMSignalBuilder(dataset_metadata: DatasetMetadata, class_name='am-dsb-sc', **kwargs)[source]

Bases: SignalBuilder

Implements SignalBuilder() for amplitude modulation (AM) waveform.

dataset_metadata

Parameters describing the dataset required for signal generation.

Type:

DatasetMetadata

supported_classes

List of supported signal classes. Set to [“am-dsb-sc”].

Type:

List[str]

supported_classes = ['am-dsb-sc', 'am-dsb', 'am-lsb', 'am-usb']
class torchsig.signals.builders.FSKSignalBuilder(dataset_metadata: DatasetMetadata, class_name: str = '2fsk', **kwargs)[source]

Bases: SignalBuilder

Implements SignalBuilder() for frequency shift keying modulation (FSK) waveform.

dataset_metadata

Parameters describing the dataset required for signal generation.

Type:

DatasetMetadata

supported_classes

List of supported signal classes. Set to [“2fsk”].

Type:

List[str]

supported_classes = ['2fsk', '2gfsk', '2msk', '2gmsk', '4fsk', '4gfsk', '4msk', '4gmsk', '8fsk', '8gfsk', '8msk', '8gmsk', '16fsk', '16gfsk', '16msk', '16gmsk']
class torchsig.signals.builders.LFMSignalBuilder(dataset_metadata: DatasetMetadata, class_name: str = 'lfm_data', **kwargs)[source]

Bases: SignalBuilder

Implements SignalBuilder() for linear frequency modulation (LFM) waveform.

dataset_metadata

Parameters describing the dataset required for signal generation.

Type:

DatasetMetadata

supported_classes

List of supported signal classes. Set to [“lfm_data”].

Type:

List[str]

supported_classes = ['lfm_data', 'lfm_radar']
class torchsig.signals.builders.ChirpSSSignalBuilder(dataset_metadata: DatasetMetadata, class_name: str = 'chirpss_data', **kwargs)[source]

Bases: SignalBuilder

Implements SignalBuilder() for chirp spread spectrum waveform.

dataset_metadata

Parameters describing the dataset required for signal generation.

Type:

DatasetMetadata

supported_classes

List of supported signal classes. Set to [“chirpss_data”].

Type:

List[str]

supported_classes = ['chirpss']
class torchsig.signals.builders.OFDMSignalBuilder(dataset_metadata: DatasetMetadata, class_name: str, **kwargs)[source]

Bases: SignalBuilder

Implements the OFDM family signal generator.

Implements SignalBuilder() for the OFDM signals.

dataset_metadata

Parameters describing the dataset required for signal generation.

Type:

DatasetMetadata

supported_classes

List of supported signal classes. Set to TorchSigSignalLists.ofdm_signals.

Type:

List[str]

supported_classes = ['ofdm-64', 'ofdm-72', 'ofdm-128', 'ofdm-180', 'ofdm-256', 'ofdm-300', 'ofdm-512', 'ofdm-600', 'ofdm-900', 'ofdm-1024', 'ofdm-1200', 'ofdm-2048']

Signal Modulation Classes

Config File that includes dictionaries of signal classes. Includes the default modulations.

class torchsig.signals.signal_lists.TorchSigSignalLists[source]

Bases: object

Various lists of signals available within TorchSig

all_signals

List of all signal types.

Type:

list[str]

family_dict (dict[str, str]]

List dict which contains all signal types and their associated signal family

family_list

(list[str]): List of all the values from family_dict

Type:

ClassVar[list[str]]

fsk_signals

Frequency shift keying and FSK-related signals; FSK, GFSK, MSK, GMSK

Type:

list[str]

ofdm_signals

Orthogonal frequency division multiplexing signals OFDM-64, OFDM-600, OFDM-1024, and others.

Type:

list[str]

constellation_signals

Linearly modulated constellation-based signals, contains QAM, PSK, ASK and OOK signals.

Type:

list[str]

am_signals

Amplitude modulation-based signals: AM-DSB, AM-DSB-SC, AM-USB, AM-LSB

Type:

list[str]

fm_signals

Frequency Modulated signal

Type:

list[str]

lfm_signals

Linearly frequency modulated signals, includes LFM data and LFM radar

Type:

list[str]

chirpss_signals

Chirp spread-spectrum signal

Type:

list[str]

tone_signals

Tone signal

Type:

list[str]

Example

Access this list::
>>> from torchsig.signals.signal_lists import TorchSigSignalLists
>>> TorchSigSignalLists.all_signals
>>> TorchSigSignalLists.family_dict
all_signals: ClassVar[list[str]] = ['ook', 'bpsk', '4ask', 'qpsk', '8ask', '8psk', '16qam', '16ask', '16psk', '32qam', '32qam_cross', '32ask', '32psk', '64qam', '64ask', '64psk', '128qam_cross', '256qam', '512qam_cross', '1024qam', '2fsk', '2gfsk', '2msk', '2gmsk', '4fsk', '4gfsk', '4msk', '4gmsk', '8fsk', '8gfsk', '8msk', '8gmsk', '16fsk', '16gfsk', '16msk', '16gmsk', 'ofdm-64', 'ofdm-72', 'ofdm-128', 'ofdm-180', 'ofdm-256', 'ofdm-300', 'ofdm-512', 'ofdm-600', 'ofdm-900', 'ofdm-1024', 'ofdm-1200', 'ofdm-2048', 'fm', 'am-dsb-sc', 'am-dsb', 'am-lsb', 'am-usb', 'lfm_data', 'lfm_radar', 'chirpss', 'tone']
family_dict: ClassVar[Dict[str, str]] = {'1024qam': 'qam', '128qam_cross': 'qam', '16ask': 'ask', '16fsk': 'fsk', '16gfsk': 'fsk', '16gmsk': 'fsk', '16msk': 'fsk', '16psk': 'psk', '16qam': 'qam', '256qam': 'qam', '2fsk': 'fsk', '2gfsk': 'fsk', '2gmsk': 'fsk', '2msk': 'fsk', '32ask': 'ask', '32psk': 'psk', '32qam': 'qam', '32qam_cross': 'qam', '4ask': 'ask', '4fsk': 'fsk', '4gfsk': 'fsk', '4gmsk': 'fsk', '4msk': 'fsk', '512qam_cross': 'qam', '64ask': 'ask', '64psk': 'psk', '64qam': 'qam', '8ask': 'ask', '8fsk': 'fsk', '8gfsk': 'fsk', '8gmsk': 'fsk', '8msk': 'fsk', '8psk': 'psk', 'am-dsb': 'am', 'am-dsb-sc': 'am', 'am-lsb': 'am', 'am-usb': 'am', 'bpsk': 'psk', 'chirpss': 'chirp', 'fm': 'fm', 'lfm_data': 'chirp', 'lfm_radar': 'chirp', 'ofdm-1024': 'ofdm', 'ofdm-1200': 'ofdm', 'ofdm-128': 'ofdm', 'ofdm-180': 'ofdm', 'ofdm-2048': 'ofdm', 'ofdm-256': 'ofdm', 'ofdm-300': 'ofdm', 'ofdm-512': 'ofdm', 'ofdm-600': 'ofdm', 'ofdm-64': 'ofdm', 'ofdm-72': 'ofdm', 'ofdm-900': 'ofdm', 'ook': 'ook', 'qpsk': 'psk', 'tone': 'tone'}
family_list: ClassVar[list[str]] = ['am', 'ask', 'chirp', 'fm', 'fsk', 'ofdm', 'ook', 'psk', 'qam', 'tone']
fsk_signals = ['2fsk', '2gfsk', '2msk', '2gmsk', '4fsk', '4gfsk', '4msk', '4gmsk', '8fsk', '8gfsk', '8msk', '8gmsk', '16fsk', '16gfsk', '16msk', '16gmsk']
ofdm_signals = ['ofdm-64', 'ofdm-72', 'ofdm-128', 'ofdm-180', 'ofdm-256', 'ofdm-300', 'ofdm-512', 'ofdm-600', 'ofdm-900', 'ofdm-1024', 'ofdm-1200', 'ofdm-2048']
constellation_signals = ['ook', 'bpsk', '4ask', 'qpsk', '8ask', '8psk', '16qam', '16ask', '16psk', '32qam', '32qam_cross', '32ask', '32psk', '64qam', '64ask', '64psk', '128qam_cross', '256qam', '512qam_cross', '1024qam']
am_signals = ['am-dsb-sc', 'am-dsb', 'am-lsb', 'am-usb']
fm_signals = ['fm']
lfm_signals = ['lfm_data', 'lfm_radar']
chirpss_signals = ['chirpss']
tone_signals = ['tone']
fsk_names = ['fsk', 'msk']
ofdm_names = ['ofdm']
constellation_names = ['ask', 'qam', 'psk', 'ook']
am_names = ['am-dsb', 'am-lsb', 'am-usb']
lfm_names = ['lfm_']
ofdm_subcarrier_modulations = ['bpsk', 'qpsk', '16qam', '64qam', '256qam', '1024qam']
name = 'tone'
class torchsig.signals.signal_lists.RadioML2018[source]

Bases: object

Radio ML 2016 dataclass, containing family class names list family_class_list

Example

Access this list::
>>> from torchsig.signals.signal_lists import radioml2018
>>> radioml2018.family_class_list
family_class_list: ClassVar[list[str]] = ['OOK', '4ASK', '8ASK', 'BPSK', 'QPSK', '8PSK', '16PSK', '32PSK', '16APSK', '32APSK', '64APSK', '128APSK', '16QAM', '32QAM', '64QAM', '128QAM', '256QAM', 'AM-SSB-WC', 'AM-SSB-SC', 'AM-DSB-WC', 'AM-DSB-SC', 'FM', 'GMSK', 'OQPSK']