# rftools/calculators/signal.py
# AUTO-GENERATED by scripts/generate_stubs.py — DO NOT EDIT
# Regenerate with: python scripts/generate_stubs.py --frontend-dir /path/to/frontend
"""
Typed stubs for the 'signal' category (13 calculators).

Functions:
    filter_designer(...) -> CalculatorResult
    sampling_nyquist(...) -> CalculatorResult
    snr_calculator(...) -> CalculatorResult
    adc_snr(...) -> CalculatorResult
    fft_bin_resolution(...) -> CalculatorResult
    johnson_noise(...) -> CalculatorResult
    am_modulation_index(...) -> CalculatorResult
    fm_modulation_index(...) -> CalculatorResult
    oversampling_snr(...) -> CalculatorResult
    digital_filter_order(...) -> CalculatorResult
    pll_loop_filter(...) -> CalculatorResult
    ber_snr(...) -> CalculatorResult
    quantization_noise(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


def _client() -> _rftools.Client:
    return _rftools._get_default_client()


def filter_designer(responseType: float = 0.0, filterType: float = 0.0, fc: float = 1000.0, order: float = 2.0, impedance: float = 50.0, qFactor: float = 1.0, eSeries: float = 0.0) -> CalculatorResult:
    """
    Passive RC/LC Filter Designer

    Category: signal

    Design passive Butterworth and Chebyshev Type I (0.5 dB ripple) low-pass, high-pass, and band-pass filters up to order 10. Calculates all LC ladder element values, time constant, and stopband attenuation.

    Parameters
    ----------
    responseType : float
        Response Type (default: 0.0)
    filterType : float
        Filter Type (default: 0.0)
    fc : float
        Cutoff Frequency (Hz) (default: 1000.0)
    order : float
        Filter Order (default: 2.0)
    impedance : float
        Characteristic Impedance (Ω) (default: 50.0)
    qFactor : float
        Quality Factor (default: 1.0)
    eSeries : float
        E-Series Snapping (default: 0.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'C1_nF', 'L1_uH', 'C3_nF', 'L4_uH', 'C5_nF', 'L6_uH', 'C7_nF', 'L8_uH', 'C9_nF', 'L10_uH', 'tau_ns', 'attenuation_at_2fc', 'bandwidth_Hz', 'fLow_Hz', 'fHigh_Hz', 'maxComponentError', 'fcShiftPercent'
    """
    inputs = {"responseType": responseType, "filterType": filterType, "fc": fc, "order": order, "impedance": impedance, "qFactor": qFactor, "eSeries": eSeries}
    return _client().calculate('filter-designer', inputs)


def sampling_nyquist(signalFreq: float = 10000.0, samplingRate: float = 44100.0, adcBits: float = 16.0, channels: float = 1.0) -> CalculatorResult:
    """
    Nyquist Sampling Theorem Calculator

    Category: signal

    Calculate Nyquist sampling rate, oversampling ratio, aliasing frequency, ADC dynamic range, SNR, and data rate. Verify that your sampling rate satisfies the Nyquist criterion and avoid aliasing in your system.

    Parameters
    ----------
    signalFreq : float
        Signal Bandwidth / Max Frequency (Hz) (default: 10000.0)
    samplingRate : float
        Sampling Rate (Sa/s) (default: 44100.0)
    adcBits : float
        ADC Resolution (bits) (default: 16.0)
    channels : float
        Number of Channels (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'nyquistRate_Hz', 'oversamplingRatio', 'aliasFreq_Hz', 'dynamicRangeDB', 'snr_dB', 'dataRateMbps', 'antiAliasingFC_Hz'
    """
    inputs = {"signalFreq": signalFreq, "samplingRate": samplingRate, "adcBits": adcBits, "channels": channels}
    return _client().calculate('sampling-nyquist', inputs)


def snr_calculator(bandwidth: float = 1.0, noiseFigure: float = 6.0, signalPower: float = -60.0, temperature: float = 290.0) -> CalculatorResult:
    """
    Signal-to-Noise Ratio (SNR) Calculator

    Category: signal

    Calculate SNR, noise floor, sensitivity, and dynamic range for RF receivers and signal chains

    Parameters
    ----------
    bandwidth : float
        Bandwidth (MHz) (default: 1.0)
    noiseFigure : float
        Noise Figure (dB) (default: 6.0)
    signalPower : float
        Signal Power (dBm) (default: -60.0)
    temperature : float
        Temperature (K) (default: 290.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'noiseFloor', 'snr', 'sensitivity', 'dynamicRange', 'thermalNoise'
    """
    inputs = {"bandwidth": bandwidth, "noiseFigure": noiseFigure, "signalPower": signalPower, "temperature": temperature}
    return _client().calculate('snr-calculator', inputs)


def adc_snr(bits: float = 12.0, inputFreq: float = 1.0, samplingFreq: float = 10.0, jitter: float = 1.0) -> CalculatorResult:
    """
    ADC SNR and ENOB Calculator

    Category: signal

    Calculate analog-to-digital converter signal-to-noise ratio, effective number of bits (ENOB), and SFDR including aperture jitter effects

    Parameters
    ----------
    bits : float
        ADC Resolution (bits) (default: 12.0)
    inputFreq : float
        Input Signal Frequency (MHz) (default: 1.0)
    samplingFreq : float
        Sampling Frequency (MHz) (default: 10.0)
    jitter : float
        Aperture Jitter (ps) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'theoreticalSnr', 'snrWithJitter', 'enob', 'sfdr', 'noisePower'
    """
    inputs = {"bits": bits, "inputFreq": inputFreq, "samplingFreq": samplingFreq, "jitter": jitter}
    return _client().calculate('adc-snr', inputs)


def fft_bin_resolution(sampleRate: float = 44.1, fftSize: float = 1024.0, windowType: float = 1.0) -> CalculatorResult:
    """
    FFT Bin Resolution & Spectral Analysis Calculator

    Category: signal

    Calculate FFT frequency bin resolution, Nyquist range, time record length, noise floor processing gain, and window scalloping loss

    Parameters
    ----------
    sampleRate : float
        Sample Rate (kHz) (default: 44.1)
    fftSize : float
        FFT Size (points) (default: 1024.0)
    windowType : float
        Window Function (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'binResolution', 'frequencyRange', 'timeRecord', 'noiseFloor', 'scalloping'
    """
    inputs = {"sampleRate": sampleRate, "fftSize": fftSize, "windowType": windowType}
    return _client().calculate('fft-bin-resolution', inputs)


def johnson_noise(resistance: float = 50.0, temperature: float = 25.0, bandwidth: float = 1.0) -> CalculatorResult:
    """
    Johnson-Nyquist Thermal Noise Calculator

    Category: signal

    Calculate thermal noise voltage, noise power, and noise spectral density for resistors using the Johnson-Nyquist noise formula

    Parameters
    ----------
    resistance : float
        Resistance (Ω) (default: 50.0)
    temperature : float
        Temperature (°C) (default: 25.0)
    bandwidth : float
        Noise Bandwidth (MHz) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'noiseVoltage', 'noisePower', 'noisePowerDensity', 'noiseCurrentDensity'
    """
    inputs = {"resistance": resistance, "temperature": temperature, "bandwidth": bandwidth}
    return _client().calculate('johnson-noise', inputs)


def am_modulation_index(carrierAmplitude: float = 1.0, messageAmplitude: float = 0.5, carrierFreq: float = 1000.0, messageFreq: float = 1.0) -> CalculatorResult:
    """
    AM Modulation Index Calculator

    Category: signal

    Calculate amplitude modulation index, sidebands, bandwidth, and power efficiency for AM radio signals

    Parameters
    ----------
    carrierAmplitude : float
        Carrier Amplitude (V) (default: 1.0)
    messageAmplitude : float
        Message Amplitude (V) (default: 0.5)
    carrierFreq : float
        Carrier Frequency (kHz) (default: 1000.0)
    messageFreq : float
        Message Frequency (kHz) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'modulationIndex', 'upperSideband', 'lowerSideband', 'bandwidth', 'powerEfficiency', 'sidebandsToCarrier'
    """
    inputs = {"carrierAmplitude": carrierAmplitude, "messageAmplitude": messageAmplitude, "carrierFreq": carrierFreq, "messageFreq": messageFreq}
    return _client().calculate('am-modulation-index', inputs)


def fm_modulation_index(frequencyDeviation: float = 75.0, messageFreq: float = 15.0, carrierFreq: float = 100.0) -> CalculatorResult:
    """
    FM Modulation Index & Bandwidth Calculator

    Category: signal

    Calculate FM modulation index, bandwidth using Carson's rule, Bessel bandwidth, and SNR improvement over AM

    Parameters
    ----------
    frequencyDeviation : float
        Frequency Deviation (kHz) (default: 75.0)
    messageFreq : float
        Message Frequency (kHz) (default: 15.0)
    carrierFreq : float
        Carrier Frequency (MHz) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'modulationIndex', 'carsonBandwidth', 'besselBandwidth', 'snrImprovement'
    """
    inputs = {"frequencyDeviation": frequencyDeviation, "messageFreq": messageFreq, "carrierFreq": carrierFreq}
    return _client().calculate('fm-modulation-index', inputs)


def oversampling_snr(bits: float = 12.0, oversamplingRatio: float = 64.0, noiseShapingOrder: float = 1.0) -> CalculatorResult:
    """
    Oversampling & Noise Shaping SNR Calculator

    Category: signal

    Calculate SNR improvement from oversampling and noise shaping for sigma-delta ADCs, including effective bits gained from higher OSR

    Parameters
    ----------
    bits : float
        Base ADC Resolution (bits) (default: 12.0)
    oversamplingRatio : float
        Oversampling Ratio (default: 64.0)
    noiseShapingOrder : float
        Noise Shaping Order (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'baseSnr', 'oversampledSnr', 'effectiveBits', 'snrImprovement'
    """
    inputs = {"bits": bits, "oversamplingRatio": oversamplingRatio, "noiseShapingOrder": noiseShapingOrder}
    return _client().calculate('oversampling-snr', inputs)


def digital_filter_order(passbandFreq: float = 1000.0, stopbandFreq: float = 2000.0, passbandRipple: float = 3.0, stopbandAttenuation: float = 40.0) -> CalculatorResult:
    """
    Digital Filter Order Calculator

    Category: signal

    Calculate minimum filter order for Butterworth, Chebyshev, and elliptic (Cauer) low-pass filters given passband ripple and stopband attenuation requirements

    Parameters
    ----------
    passbandFreq : float
        Passband Edge Frequency (Hz) (default: 1000.0)
    stopbandFreq : float
        Stopband Edge Frequency (Hz) (default: 2000.0)
    passbandRipple : float
        Passband Ripple (dB) (default: 3.0)
    stopbandAttenuation : float
        Stopband Attenuation (dB) (default: 40.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'butterworthOrder', 'chebyshevOrder', 'ellipticOrder', 'transitionRatio'
    """
    inputs = {"passbandFreq": passbandFreq, "stopbandFreq": stopbandFreq, "passbandRipple": passbandRipple, "stopbandAttenuation": stopbandAttenuation}
    return _client().calculate('digital-filter-order', inputs)


def pll_loop_filter(fRef: float = 100.0, loopBW: float = 5.0, phaseMargin: float = 45.0, kvco: float = 20.0, n: float = 100.0, icp: float = 500.0) -> CalculatorResult:
    """
    PLL Loop Filter Designer

    Category: signal

    Design a type-2 second-order PLL passive loop filter. Calculates time constants, capacitor and resistor values for target loop bandwidth and phase margin.

    Parameters
    ----------
    fRef : float
        Reference Frequency (kHz) (default: 100.0)
    loopBW : float
        Loop Bandwidth (kHz) (default: 5.0)
    phaseMargin : float
        Phase Margin (deg) (default: 45.0)
    kvco : float
        VCO Gain (MHz/V) (default: 20.0)
    n : float
        Divider Ratio (default: 100.0)
    icp : float
        Charge Pump Current (μA) (default: 500.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'c1', 'r1', 'c2', 'pmActual', 'bwRatio'
    """
    inputs = {"fRef": fRef, "loopBW": loopBW, "phaseMargin": phaseMargin, "kvco": kvco, "n": n, "icp": icp}
    return _client().calculate('pll-loop-filter', inputs)


def ber_snr(ebN0dB: float = 10.0, modulation: float = 1.0) -> CalculatorResult:
    """
    Bit Error Rate (BER) Calculator

    Category: signal

    Calculate bit error rate (BER) from Eb/N0 for BPSK, QPSK, 8PSK, and 16QAM digital modulations. Essential for digital communications system design.

    Parameters
    ----------
    ebN0dB : float
        Eb/N0 (dB) (default: 10.0)
    modulation : float
        Modulation (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'ber', 'berLog10', 'bitsPerSymbol'
    """
    inputs = {"ebN0dB": ebN0dB, "modulation": modulation}
    return _client().calculate('ber-snr', inputs)


def quantization_noise(bits: float = 12.0, vref: float = 3.3, frequency: float = 1.0, sampleRate: float = 100.0) -> CalculatorResult:
    """
    ADC Quantization Noise Calculator

    Category: signal

    Calculate ADC quantization noise, theoretical SQNR, ENOB, dynamic range, and noise spectral density for analog-to-digital converter design.

    Parameters
    ----------
    bits : float
        ADC Resolution (bits) (default: 12.0)
    vref : float
        Reference Voltage (V) (default: 3.3)
    frequency : float
        Input Frequency (kHz) (default: 1.0)
    sampleRate : float
        Sample Rate (kHz) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'lsb', 'sqnr', 'enob', 'dynamicRange', 'noiseDensity'
    """
    inputs = {"bits": bits, "vref": vref, "frequency": frequency, "sampleRate": sampleRate}
    return _client().calculate('quantization-noise', inputs)

