# SineArrayGAM

`SineArrayGAM` is a helper GAM bundled with the UDPStreamer library. It fills a `float32`
output array with a continuous sinusoidal waveform, maintaining phase continuity across
RT cycles. It is intended for testing and demonstrating the UDPStreamer's packed-burst
signal capability.

> **Library:** The class is compiled into `UDPStreamer.so` alongside the UDPStreamer
> DataSource. A `SineArrayGAM.so → UDPStreamer.so` symlink is required for MARTe2's
> auto-loader (created automatically by `Test/MARTeApp/run.sh`).

---

## Configuration

```
+Ch1GAM = {
    Class        = SineArrayGAM
    Frequency    = 1000.0       // Signal frequency [Hz]  (default: 1.0)
    Amplitude    = 1.0          // Peak amplitude           (default: 1.0)
    Offset       = 0.0          // DC offset                (default: 0.0)
    Phase        = 0.0          // Initial phase [radians]  (default: 0.0)
    SamplingRate = 1000000.0    // Sample rate [Hz]         (default: 1000000.0)
                                //   Must match the SamplingRate declared in the
                                //   UDPStreamer signal config.

    OutputSignals = {
        Ch1 = {
            DataSource       = DDB
            Type             = float32
            NumberOfDimensions = 1
            NumberOfElements = 1000   // N samples per RT cycle
        }
    }
}
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `Frequency` | float64 | 1.0 | Signal frequency in Hz |
| `Amplitude` | float64 | 1.0 | Peak amplitude (half peak-to-peak) |
| `Offset` | float64 | 0.0 | DC offset added to every sample |
| `Phase` | float64 | 0.0 | Phase shift in radians |
| `SamplingRate` | float64 | 1 000 000.0 | Sample rate in Hz; must be > 0 |

### Output signal

Exactly **one** output signal of type **`float32`** is required. The signal must have
`NumberOfDimensions = 1` and `NumberOfElements = N` where N ≥ 1.

---

## Waveform formula

Each `Execute()` call fills elements `[0 .. N-1]` using:

```
v[k] = Amplitude × sin(2π × Frequency × (offset_total + k) / SamplingRate + Phase) + Offset
```

where `offset_total` is a cumulative sample counter that increments by `N` after each call.
This guarantees a gapless, phase-continuous waveform across RT cycles.

---

## Bandwidth and fragmentation

For a 1 MSps burst at 10 kHz RT rate with 1000 samples per cycle:

```
N = SamplingRate / RT_rate = 1 000 000 / 1000 = 1000 samples per cycle
Wire bytes = 1000 × 4 (float32) = 4000 B per channel per cycle
At 10 kHz: 4000 × 10 000 = 40 MB/s raw (UDP, before quantization)
```

Using `QuantizedType = uint16` halves the wire bandwidth to 20 MB/s.
With `MaxPayloadSize = 1400` the 4 000-byte payload spans 3 UDP datagrams
(`ceil(4008 / 1383) = 3`).

---

## Example: two-channel quadrature pair

```
+Ch1GAM = {
    Class = SineArrayGAM
    Frequency = 1000.0; Amplitude = 1.0; Phase = 0.0; SamplingRate = 10000000.0
    OutputSignals = {
        Ch1 = { DataSource = DDB; Type = float32; NumberOfDimensions = 1; NumberOfElements = 1000 }
    }
}

+Ch2GAM = {
    Class = SineArrayGAM
    Frequency = 1000.0; Amplitude = 1.0; Phase = 1.5708; SamplingRate = 10000000.0
    OutputSignals = {
        Ch2 = { DataSource = DDB; Type = float32; NumberOfDimensions = 1; NumberOfElements = 1000 }
    }
}
```

This produces two signals 90° out of phase, useful for verifying IQ-style signal chains.