TorchSig: Signal Processing Machine Learning Toolkit

Signal builders combine modulation functions with a subclass of torchsig.signals.builder.BaseSignalGenerator.

Implementation Steps:

1. Modulation Functions: Place these in focused modules under torchsig/signals/builders/. They should perform the waveform math, accept explicit parameters (sample counts, rates, etc.), and return a 1D NumPy array (ideally TorchSigComplexDataType). Avoid global random state.
2. Generator Class: Inherit from BaseSignalGenerator.
   • Define required_metadata_fields.
   • Use set_default_class_name("name") to set a stable class name.
   • Implement generate(), which must return a torchsig.signals.signal_types.Signal containing waveform data and accurate metadata.
   • Access metadata via self["field_name"] to allow inheritance from parent datasets.

Registration: To make a builder selectable by name in torchsig.datasets.datasets.TorchSigIterableDataset, you must update:

• torchsig/utils/signal_building.py: Add to signal_generator_lookup_table using _add_signal_generator.
• _family_name and family_names for new families.
• torchsig/signals/signal_lists.py: Add to CLASS_FAMILY_DICT and extend TorchSigSignalLists if necessary.
• Export the class/functions in the module's __all__.

class ExampleSignalGenerator(BaseSignalGenerator):
    """Generate an example waveform."""

    def __init__(self, **kwargs) -> None:
        super().__init__(**kwargs)
        self.required_metadata_fields = [
            "signal_duration_in_samples_min",
            "signal_duration_in_samples_max",
        ]
        self.set_default_class_name("example")

    def generate(self) -> Signal:
        num_samples = self.random_generator.integers(
            self["signal_duration_in_samples_min"],
            self["signal_duration_in_samples_max"] + 1,
        )
        data = example_modulator(num_samples, rng=self.random_generator)
        return Signal(data=data, center_freq=0, bandwidth=1)

Transforms in TorchSig operate on torchsig.signals.signal_types.Signal objects. Implementation is split into two parts to separate numerical logic from state management:

1. Functional Layer (torchsig/transforms/functional.py): Contains pure, array-level signal processing. Functions should accept explicit values, return an array, and use an optional numpy.random.Generator for randomness instead of global state. They must validate inputs with exceptions and preserve shape and NumPy dtypes.
2. Wrapper Layer (torchsig/transforms/transforms.py): A stateful class inheriting from torchsig.transforms.transforms.SignalTransform. This layer handles parameter sampling, validation, metadata updates, and dtype enforcement. You implement the logic inside the __apply__ method.

Randomness in Transforms: Transforms use torchsig.utils.random.Seedable. Use self.random_generator for direct draws or self.get_distribution(value_or_range) for configurable values. Supported distribution conventions:

• List: Uniform selection from entries.
• Tuple: Uniform sampling between two bounds.
• Scalar: Uniform sampling from zero to the value.
• scaling="log10": Applied to a tuple for logarithmic sampling.

def scale_amplitude(data: np.ndarray, gain: float) -> np.ndarray:
    """Scale complex IQ samples by a linear gain."""
    if not np.isfinite(gain) or gain < 0:
        raise ValueError("gain must be finite and nonnegative")
    return (data * gain).astype(data.dtype, copy=False)

class ScaleAmplitude(SignalTransform):
    """Scale a signal by a fixed linear gain."""

    def __init__(self, gain: float, **kwargs) -> None:
        super().__init__(data_dtype=TorchSigComplexDataType, **kwargs)
        self.gain = gain

    def __apply__(self, signal: Signal) -> Signal:
        signal.data = F.scale_amplitude(signal.data, self.gain)
        return signal

Unlike standard signal builders (e.g., FSK, PSK, OFDM) which emit streams of random symbols, Structured Signals model explicit protocol frame layouts. They include recognizable temporal and spectral structures such as fixed sync words, training preambles, signaling headers, and pilots.

Key Characteristics:

• Structural Models: They provide faithful framing, preambles, modulation, pulse shaping, and per-frame symbol counts.
• RFML Optimized: They intentionally skip bit-exact field encoding (like FEC or scrambling) and use random payload symbols. This makes them ideal for RF Machine Learning (RFML) datasets where temporal structure is more important than bit-level decodability.
• Parameter Constraints: Structured signals may inherently break standard parameter contracts for burst lengths or bandwidths. Always verify the specific signal builder implementation and its output for your use case.

TorchSig provides three HDF5 readers. You must use the reader that matches the specific layout used when the dataset was written; layouts are not interchangeable.

Note on array content: While Packed and Homogeneous files can contain narrowband IQ, wideband IQ, spectrograms, and other non-object NumPy arrays, HomogeneousHDF5Reader requires that all top-level arrays share the same shape and dtype. Component counts, shapes, and dtypes within those components may still vary.