# SignalGenerator Block

## Description

The SignalGenerator block is a versatile signal source that generates various types of time-varying signals for simulation and testing purposes. It can produce sinusoidal waves, cosine waves, square waves, sawtooth waves, and triangular waves. This block is essential for creating test signals, reference inputs, and periodic disturbances in control systems and signal processing applications.

The SignalGenerator operates as a time-based function generator, producing output signals based on the current simulation time and the configured parameters. It has no input ports and continuously outputs the generated signal to its single output port.

## Mathematical Model

All signals share the base argument:
```
θ(t) = 2π × f × t + φ
```
where `φ` is the phase converted from degrees to radians.

The normalized position within the cycle is:
```
n = ((θ / 2π) mod 1 + 1) mod 1
```

### Sinusoidal Signal
```
y(t) = A × sin(θ) + offset
```

### Cosine Signal
```
y(t) = A × cos(θ) + offset
```

### Square Wave Signal
```
y(t) = A      if n < dutyCycle
y(t) = -A     if n >= dutyCycle
y(t) += offset
```

### Sawtooth Wave Signal
```
y(t) = A × (2n - 1) + offset
```
Rises linearly from -A to +A over one period.

### Triangular Wave Signal
```
y(t) = A × (4n - 1)       if n < 0.5
y(t) = A × (3 - 4n)       if n >= 0.5
y(t) += offset
```
Rises from -A to +A in the first half, falls from +A to -A in the second half.

Where:
- `y(t)` is the output signal at time t
- `A` is the amplitude parameter
- `f` is the frequency parameter (Hz)
- `φ` is the phase parameter (degrees, converted to radians internally)
- `offset` is the DC offset parameter
- `n` is the normalized position in the cycle (0 to 1)

## Parameters

### signalType
The type of waveform to generate.
- **Type**: select
- **Options**: sine, cosine, square, sawtooth, triangle
- **Default**: sine
- **Tooltip**: Type of periodic signal to generate
- **sine**: Smooth sinusoidal waveform (ideal for continuous systems)
- **cosine**: Cosine waveform (90° phase-shifted sine)
- **square**: Square wave with configurable duty cycle (digital signals, PWM)
- **sawtooth**: Linear rising ramp (oscilloscope sweep, modulation)
- **triangle**: Symmetric triangular waveform (function generation)

### amplitude
The peak amplitude of the generated signal. Controls the maximum deviation from the offset value.
- **Type**: number
- **Symbol**: A
- **Range**: 0.001 to 1000000
- **Default**: 1
- **Tooltip**: Peak amplitude of the signal

### frequency
The frequency of the generated signal in Hertz (Hz).
- **Type**: number
- **Symbol**: f
- **Range**: 0.001 to 100000 Hz
- **Default**: 1
- **Tooltip**: Signal frequency in Hertz

### offset
The DC offset added to the signal. Shifts the entire signal up or down.
- **Type**: number
- **Default**: 0
- **Tooltip**: DC offset added to the signal

### phase
The phase offset of the signal in degrees (0-360). The phase is converted to radians internally: `φ_rad = phase × π / 180`. A phase of 90° on a sine wave produces a cosine wave.
- **Type**: number
- **Symbol**: φ
- **Range**: 0 to 360 degrees
- **Default**: 0
- **Tooltip**: Initial phase offset in degrees

### dutyCycle
The fraction of the period during which the square wave is at +amplitude. Only visible when signalType is "square".
- **Type**: number
- **Range**: 0 to 1
- **Default**: 0.5
- **Tooltip**: Duty cycle for square wave (0-1)
- `dutyCycle = 0.5`: symmetric square wave (equal high/low time)
- `dutyCycle = 0.25`: high for 25% of the period, low for 75%
- `dutyCycle = 0.9`: high for 90% of the period (wide pulse)

## Examples

### 1Hz Sine Wave
Generate a basic unit-amplitude sine wave:
```
SignalGenerator (signalType: "sine", frequency: 1) → NumericDisplay
```

### PWM Signal
Generate a 10Hz PWM signal with 30% duty cycle:
```
SignalGenerator (signalType: "square", frequency: 10, dutyCycle: 0.3) → Controller
```

### Phase-Shifted Cosine
Two equivalent ways to generate a cosine:
```
SignalGenerator (signalType: "cosine", frequency: 1) → Scope
SignalGenerator (signalType: "sine", frequency: 1, phase: 90) → Scope
```

## Remarks

- **Phase Convention**: Phase is specified in degrees (0-360) and shifts the signal forward in time. A positive phase advances the waveform.
- **Time-Based**: Signals are calculated from the current simulation time. The block is stateless — output depends only on `time` and parameters.
- **WASM Optimized**: Implemented in Rust for high-frequency signal generation without performance lag.
- **Negative Time Handling**: The normalized position uses double-modulo `((x % 1 + 1) % 1)` to handle negative argument values correctly.
- **Duty Cycle Clamping**: The duty cycle value is clamped to [0, 1] regardless of the input value.

## See Also

- **PulseGenerator**: For unipolar pulses
- **Constant**: For steady DC signals
- **Step**: For a single transition event