Signals

Synthetic signal creation tools and builders used by torchsig.datasets.datasets.TorchSigIterableDataset for dataset creation.

Signal Class Types

Signal and Signal Metadata classes. This module defines the Signal class and its associated functionality, which is used to represent and manipulate signal data and metadata.

Examples

Signal:

>>> from torchsig.signals import Signal
>>> import numpy as np
>>> data = np.array([1.0, 2.0])
>>> new_sig = Signal(data=data)

class torchsig.signals.signal_types.SignalMetadataObject(**kwargs: Any)

Bases: HierarchicalMetadataObject

Represents metadata associated with a signal.

This class extends HierarchicalMetadataObject to provide signal-specific metadata properties and calculations.

property start: float

Signal start normalized to duration of signal.

Returns:

Signal start as a percentage of total time (0-1).

Return type:

float

property stop: float

Signal stop normalized to duration of signal.

Returns:

Signal stop as a percentage of total time (0-1).

Return type:

float

property duration: float

Signal duration normalized to 0-1.0.

Returns:

Signal duration as a percentage of total time (0-1).

Return type:

float

property stop_in_samples: int

Signal stop in samples.

Returns:

Signal stop time in samples.

Return type:

int

property upper_freq: float

Calculates the upper frequency of a signal.

Returns:

Upper frequency in Hz.

Return type:

float

Raises:

ValueError – If center_freq or bandwidth are not available.

property lower_freq: float

Calculates the lower frequency of a signal.

Returns:

Lower frequency in Hz.

Return type:

float

Raises:

ValueError – If center_freq or bandwidth are not available.

property oversampling_rate: float

Calculates the oversampling rate for a signal.

Returns:

Oversampling rate (sample_rate / bandwidth).

Return type:

float

to_dict() → dict[str, Any]

Returns SignalMetadataExternal as a full dictionary.

Returns:

Dictionary containing all metadata attributes.

Return type:

Dict[str, Any]

class torchsig.signals.signal_types.Signal(data: ndarray | None = None, component_signals: list[Signal] = [], **kwargs: Any)

Bases: SignalMetadataObject

Represents a signal with data and metadata.

This class extends SignalMetadataObject to include actual signal data and component signals.

Parameters:

• data – Signal IQ data. Defaults to empty numpy array.

• component_signals – List of component signals. Defaults to empty list.

• **kwargs – Additional metadata key-value pairs.

copy() → Signal

Returns a copy of the Signal.

Note

Parent relationships are not guaranteed to be preserved across copies.

Returns:

A new Signal instance with copied data and metadata.

Return type:

Signal

Signal Builders

Builder

class torchsig.signals.builder.BaseSignalGenerator(transforms: list[Any] = [], **kwargs: dict[str, Any])

Bases: HierarchicalMetadataObject

Defines a callable object which takes no arguments and returns a Signal.

Takes a metadata object in init to specify values for things like min and max bandwidth.

metadata

A metadata object to be used in signal generation.

transforms

Transforms to be applied to generated signals before returning them in the __call__() method

set_default_class_name(name: str) → None

Sets the class_name to name if there wasn’t already a class name set.

Parameters:

name – The class name to set if no class name exists.

copy() → BaseSignalGenerator

Creates a deep copy of the SignalGenerator with copied transforms.

Returns:

A new instance of the SignalGenerator with copied metadata and transforms.

validate_metadata_fields() → None

Validates that all required metadata fields are present.

Throws an exception if required_metadata_fields are not filled. Does nothing if required_metadata_fields is not set.

Raises:

• TypeError – If any required metadata field names are not strings.

• ValueError – If any required metadata fields are missing.

generate() → Signal

Generates a new signal.

This method must be implemented by subclasses.

Returns:

A new Signal object.

Raises:

NotImplementedError – If the method is not implemented by a subclass.

class torchsig.signals.builder.ConcatSignalGenerator(signal_generators: list[BaseSignalGenerator], **kwargs: dict[str, Any])

Bases: BaseSignalGenerator

A Signal Generator that wraps other signal generators and returns one of their outputs at random when called.

This generator randomly selects one of the provided signal generators and returns its output. Each wrapped signal generator must be a valid BaseSignalGenerator instance.

signal_generators

List of BaseSignalGenerator instances to choose from.

random_generator

Random number generator used to select a signal generator.

copy() → ConcatSignalGenerator

Creates a deep copy of the ConcatSignalGenerator with copied signal generators.

Returns:

A new instance of ConcatSignalGenerator with copied metadata and signal generators.

validate_metadata_fields() → bool

Validates metadata fields for all wrapped signal generators.

Calls validate_metadata_fields() on each wrapped signal generator.

Returns:

True if all validations pass.

Return type:

bool

Raises:

ValueError – If any of the wrapped signal generators are missing required metadata fields.

generate() → Signal

Generates a signal by randomly selecting one of the wrapped generators.

Returns:

The output of a randomly selected signal generator.

Return type:

Signal

Specific Signal Builders

Signal Modulation Classes

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

class torchsig.signals.signal_lists.TorchSigSignalLists

Bases: object

Various lists of signals available within TorchSig.

all_signals

List of all signal types.

Type:

ClassVar[list[str]]

family_dict

Dictionary containing all signal types and their associated signal family.

Type:

ClassVar[dict[str, str]]

family_list

List of all signal families.

Type:

ClassVar[list[str]]

fsk_signals

Frequency shift keying and FSK-related signals.

Type:

ClassVar[list[str]]

ofdm_signals

Orthogonal frequency division multiplexing signals.

Type:

ClassVar[list[str]]

constellation_signals

Linearly modulated constellation-based signals.

Type:

ClassVar[list[str]]

am_signals

Amplitude modulation-based signals.

Type:

ClassVar[list[str]]

fm_signals

Frequency Modulated signal.

Type:

ClassVar[list[str]]

lfm_signals

Linearly frequency modulated signals.

Type:

ClassVar[list[str]]

chirpss_signals

Chirp spread-spectrum signal.

Type:

ClassVar[list[str]]

tone_signals

Tone signal.

Type:

ClassVar[list[str]]

all_signals: ClassVar[list[str]] = ['ook', '4ask', '8ask', '16ask', '32ask', '64ask', '2fsk', '2gfsk', '2msk', '2gmsk', '4fsk', '4gfsk', '4msk', '4gmsk', '8fsk', '8gfsk', '8msk', '8gmsk', '16fsk', '16gfsk', '16msk', '16gmsk', 'bpsk', 'qpsk', '8psk', '16psk', '32psk', '64psk', '16qam', '32qam', '32qam_cross', '64qam', '128qam_cross', '256qam', '512qam_cross', '1024qam', '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: ClassVar[list[str]] = []

ofdm_signals: ClassVar[list[str]] = []

constellation_signals: ClassVar[list[str]] = []

am_signals: ClassVar[list[str]] = []

fm_signals: ClassVar[list[str]] = []

lfm_signals: ClassVar[list[str]] = []

chirpss_signals: ClassVar[list[str]] = []

tone_signals: ClassVar[list[str]] = []

fsk_names: ClassVar[list[str]] = ['fsk', 'msk']

ofdm_names: ClassVar[list[str]] = ['ofdm']

constellation_names: ClassVar[list[str]] = ['ask', 'qam', 'psk', 'ook']

am_names: ClassVar[list[str]] = ['am-']

lfm_names: ClassVar[list[str]] = ['lfm_']

ofdm_subcarrier_modulations: ClassVar[list[str]] = ['bpsk', 'qpsk', '16qam', '64qam', '256qam', '1024qam']

Signal Utilities

Utility functions for dealing with the Signal type

torchsig.signals.signal_utils.check_signal_class(name: str, possible_names: list[str]) → bool

Check if the provided signal name matches any of the possible signal names.

This function performs a substring match against each possible name.

Parameters:

• name – The signal name to check.

• possible_names – A list of possible signal names to compare against.

Returns:

True if the signal name matches any of the possible names, otherwise False.

Return type:

bool

Examples

>>> check_signal_class("4fsk", ["fsk", "msk"])
True
>>> check_signal_class("am-dsb", ["am-"])
True
>>> check_signal_class("ofdm-64", ["ofdm"])
True

torchsig.signals.signal_utils.random_limiting_filter_design(bandwidth: float, sample_rate: float, rng: Generator | None = None) → ndarray

Design a coarse bandwidth limiting filter with randomized parameters.

Uses TorchSig’s iterative designer function to create a low-pass filter with randomized cutoff and transition bandwidth parameters.

Parameters:

• bandwidth – Occupied bandwidth for signal (Hz).

• sample_rate – Signal sampling rate (Hz).

• rng – Random number generator. If None, creates a new default generator.

Returns:

Filter taps of designed low-pass filter.

Return type:

np.ndarray

Raises:

• ValueError – If bandwidth or sample_rate are not positive.

• ValueError – If bandwidth is greater than sample_rate/2.

Examples

>>> rng = np.random.default_rng(42)
>>> lpf = random_limiting_filter_design(1000, 10000, rng)
>>> lpf.shape
(101,)