# rftools/calculators/rf.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 'rf' category (26 calculators).

Functions:
    microstrip_impedance(...) -> CalculatorResult
    rf_link_budget(...) -> CalculatorResult
    vswr_return_loss(...) -> CalculatorResult
    db_converter(...) -> CalculatorResult
    noise_figure_cascade(...) -> CalculatorResult
    skin_depth(...) -> CalculatorResult
    wavelength_frequency(...) -> CalculatorResult
    coax_impedance(...) -> CalculatorResult
    coax_loss(...) -> CalculatorResult
    ism_coexistence(...) -> CalculatorResult
    attenuator_designer(...) -> CalculatorResult
    smith_chart(...) -> CalculatorResult
    q_factor(...) -> CalculatorResult
    waveguide_cutoff(...) -> CalculatorResult
    free_space_path_loss(...) -> CalculatorResult
    radar_range_equation(...) -> CalculatorResult
    power_amplifier_efficiency(...) -> CalculatorResult
    intermodulation_distortion(...) -> CalculatorResult
    phase_noise_to_jitter(...) -> CalculatorResult
    vibration_phase_noise(...) -> CalculatorResult
    return_loss_error(...) -> CalculatorResult
    fresnel_zone(...) -> CalculatorResult
    power_density(...) -> CalculatorResult
    balun_transformer(...) -> CalculatorResult
    link_margin(...) -> CalculatorResult
    mixer_spur_calculator(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


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


def microstrip_impedance(traceWidth: float = 1.2, substrateHeight: float = 1.6, dielectricConstant: float = 4.2, copperThickness: float = 35.0) -> CalculatorResult:
    """
    Microstrip Impedance Calculator

    Category: rf

    Calculate microstrip transmission line impedance using Hammerstad-Jensen equations. Get Z₀, effective dielectric constant, and propagation delay for PCB trace design.

    Parameters
    ----------
    traceWidth : float
        Trace Width (mm) (default: 1.2)
    substrateHeight : float
        Substrate Height (mm) (default: 1.6)
    dielectricConstant : float
        Dielectric Constant (default: 4.2)
    copperThickness : float
        Copper Thickness (μm) (default: 35.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'impedance', 'effectiveDielectric', 'propagationDelay'
    """
    inputs = {"traceWidth": traceWidth, "substrateHeight": substrateHeight, "dielectricConstant": dielectricConstant, "copperThickness": copperThickness}
    return _client().calculate('microstrip-impedance', inputs)


def rf_link_budget(txPower: float = 30.0, txGain: float = 3.0, txCableLoss: float = 1.0, frequency: float = 2400.0, distance: float = 1.0, rainFade: float = 0.0, atmosphericLoss: float = 0.5, pointingLoss: float = 0.0, rxGain: float = 3.0, rxCableLoss: float = 1.0, rxSensitivity: float = -90.0) -> CalculatorResult:
    """
    RF Link Budget Calculator

    Category: rf

    Calculate RF link budget: transmit power, free space path loss, antenna gains, and received signal level. Determine link margin and maximum range.

    Parameters
    ----------
    txPower : float
        TX Power (dBm) (default: 30.0)
    txGain : float
        TX Antenna Gain (dBi) (default: 3.0)
    txCableLoss : float
        TX Cable Loss (dB) (default: 1.0)
    frequency : float
        Frequency (MHz) (default: 2400.0)
    distance : float
        Distance (km) (default: 1.0)
    rainFade : float
        Rain Fade (dB) (default: 0.0)
    atmosphericLoss : float
        Atmospheric Loss (dB) (default: 0.5)
    pointingLoss : float
        Pointing Loss (dB) (default: 0.0)
    rxGain : float
        RX Antenna Gain (dBi) (default: 3.0)
    rxCableLoss : float
        RX Cable Loss (dB) (default: 1.0)
    rxSensitivity : float
        RX Sensitivity (dBm) (default: -90.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'fspl', 'eirp', 'rxPower', 'linkMargin', 'maxRangeKm', 'totalAdditionalLoss'
    """
    inputs = {"txPower": txPower, "txGain": txGain, "txCableLoss": txCableLoss, "frequency": frequency, "distance": distance, "rainFade": rainFade, "atmosphericLoss": atmosphericLoss, "pointingLoss": pointingLoss, "rxGain": rxGain, "rxCableLoss": rxCableLoss, "rxSensitivity": rxSensitivity}
    return _client().calculate('rf-link-budget', inputs)


def vswr_return_loss(vswr: float = 1.5) -> CalculatorResult:
    """
    VSWR & Return Loss Calculator

    Category: rf

    Convert between VSWR, return loss, reflection coefficient, mismatch loss, and reflected/transmitted power percentage for RF impedance matching.

    Parameters
    ----------
    vswr : float
        VSWR (:1) (default: 1.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'returnLoss', 'gamma', 'mismatchLoss', 'reflectedPct', 'transmittedPct'
    """
    inputs = {"vswr": vswr}
    return _client().calculate('vswr-return-loss', inputs)


def db_converter(dbm: float = 0.0, impedance: float = 50.0) -> CalculatorResult:
    """
    dBm Power Converter

    Category: rf

    Convert dBm to watts, milliwatts, dBW, dBμV, and volts RMS. Essential RF power unit conversion tool for signal levels and link budgets.

    Parameters
    ----------
    dbm : float
        Power Level (dBm) (default: 0.0)
    impedance : float
        System Impedance (Ω) (default: 50.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'dbw', 'watts', 'mwatts', 'uwatts', 'vrms', 'mvrms', 'dbuv'
    """
    inputs = {"dbm": dbm, "impedance": impedance}
    return _client().calculate('db-converter', inputs)


def noise_figure_cascade(numStages: float = 3.0, stage1NF: float = 1.5, stage1Gain: float = 15.0, stage1IIP3: float = -5.0, stage2NF: float = 8.0, stage2Gain: float = -6.0, stage2IIP3: float = 10.0, stage3NF: float = 6.0, stage3Gain: float = 20.0, stage3IIP3: float = 20.0, stage4NF: float = 3.0, stage4Gain: float = 10.0, stage4IIP3: float = 25.0) -> CalculatorResult:
    """
    Cascaded Noise Figure Calculator

    Category: rf

    Calculate cascaded noise figure for a chain of RF stages using the Friis formula. Essential for LNA and receiver chain design.

    Parameters
    ----------
    numStages : float
        Number of Stages (default: 3.0)
    stage1NF : float
        Stage 1 Noise Figure (dB) (default: 1.5)
    stage1Gain : float
        Stage 1 Gain (dB) (default: 15.0)
    stage1IIP3 : float
        Stage 1 IIP3 (dBm) (default: -5.0)
    stage2NF : float
        Stage 2 Noise Figure (dB) (default: 8.0)
    stage2Gain : float
        Stage 2 Gain (dB) (default: -6.0)
    stage2IIP3 : float
        Stage 2 IIP3 (dBm) (default: 10.0)
    stage3NF : float
        Stage 3 Noise Figure (dB) (default: 6.0)
    stage3Gain : float
        Stage 3 Gain (dB) (default: 20.0)
    stage3IIP3 : float
        Stage 3 IIP3 (dBm) (default: 20.0)
    stage4NF : float
        Stage 4 Noise Figure (dB) (default: 3.0)
    stage4Gain : float
        Stage 4 Gain (dB) (default: 10.0)
    stage4IIP3 : float
        Stage 4 IIP3 (dBm) (default: 25.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'cascadedNF', 'cascadedF', 'stage1Contribution', 'stage2Contribution', 'stage3Contribution', 'cascadedIIP3', 'cascadedOIP3'
    """
    inputs = {"numStages": numStages, "stage1NF": stage1NF, "stage1Gain": stage1Gain, "stage1IIP3": stage1IIP3, "stage2NF": stage2NF, "stage2Gain": stage2Gain, "stage2IIP3": stage2IIP3, "stage3NF": stage3NF, "stage3Gain": stage3Gain, "stage3IIP3": stage3IIP3, "stage4NF": stage4NF, "stage4Gain": stage4Gain, "stage4IIP3": stage4IIP3}
    return _client().calculate('noise-figure-cascade', inputs)


def skin_depth(frequency: float = 1000.0, conductivity: float = 58000000.0, relativePermeability: float = 1.0) -> CalculatorResult:
    """
    Skin Depth Calculator

    Category: rf

    Calculate the skin depth (penetration depth) of electromagnetic fields in conductors as a function of frequency and material properties.

    Parameters
    ----------
    frequency : float
        Frequency (MHz) (default: 1000.0)
    conductivity : float
        Conductivity (S/m) (default: 58000000.0)
    relativePermeability : float
        Relative Permeability (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'skinDepthUm', 'skinDepthNm', 'surfaceResistance'
    """
    inputs = {"frequency": frequency, "conductivity": conductivity, "relativePermeability": relativePermeability}
    return _client().calculate('skin-depth', inputs)


def wavelength_frequency(frequency: float = 2400.0, medium: float = 1.0) -> CalculatorResult:
    """
    Wavelength & Frequency Calculator

    Category: rf

    Convert between frequency, wavelength, and wave number in free space or medium. Calculate half-wave and quarter-wave lengths for antenna and transmission line design.

    Parameters
    ----------
    frequency : float
        Frequency (MHz) (default: 2400.0)
    medium : float
        Relative Permittivity (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'wavelengthMm', 'actualWavelengthMm', 'halfWaveMm', 'quarterWaveMm', 'wavenumber'
    """
    inputs = {"frequency": frequency, "medium": medium}
    return _client().calculate('wavelength-frequency', inputs)


def coax_impedance(innerDiameter: float = 0.9, outerDiameter: float = 2.95, dielectricConstant: float = 2.2) -> CalculatorResult:
    """
    Coaxial Cable Impedance Calculator

    Category: rf

    Calculate coaxial cable characteristic impedance, capacitance, inductance per unit length, and cutoff frequency from inner/outer conductor dimensions and dielectric.

    Parameters
    ----------
    innerDiameter : float
        Inner Conductor Diameter (mm) (default: 0.9)
    outerDiameter : float
        Outer Conductor Inner Diameter (mm) (default: 2.95)
    dielectricConstant : float
        Dielectric Constant (default: 2.2)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'impedance', 'capacitancePFm', 'inductanceNHm', 'velocityFactor', 'cutoffFreqGHz'
    """
    inputs = {"innerDiameter": innerDiameter, "outerDiameter": outerDiameter, "dielectricConstant": dielectricConstant}
    return _client().calculate('coax-impedance', inputs)


def coax_loss(cableIndex: float = 0.0, frequencyMHz: float = 435.0, lengthM: float = 10.0) -> CalculatorResult:
    """
    Coaxial Cable Loss Calculator

    Category: rf

    Calculate RF attenuation for common coaxial cables (LMR-400, RG-58, RG-213, and more). Enter cable type, frequency, and run length to get insertion loss in dB.

    Parameters
    ----------
    cableIndex : float
        Cable Type (default: 0.0)
    frequencyMHz : float
        Frequency (MHz) (default: 435.0)
    lengthM : float
        Cable Length (m) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'attenuation_dB', 'lossPer100m', 'powerRemaining_pct', 'voltageRemaining_pct'
    """
    inputs = {"cableIndex": cableIndex, "frequencyMHz": frequencyMHz, "lengthM": lengthM}
    return _client().calculate('coax-loss', inputs)


def ism_coexistence(bandIndex: float = 0.0, dutyCycle1_pct: float = 50.0, channels1: float = 3.0, dutyCycle2_pct: float = 5.0, channels2: float = 37.0, txPowerOffset_dB: float = 10.0) -> CalculatorResult:
    """
    ISM Band Wireless Coexistence Calculator

    Category: rf

    Estimate collision probability and throughput impact when WiFi, Bluetooth, Zigbee, LoRa, or other protocols share the same ISM band. Enter duty cycles, channel counts, and power offset.

    Parameters
    ----------
    bandIndex : float
        ISM Band (default: 0.0)
    dutyCycle1_pct : float
        Protocol 1 Duty Cycle (%) (default: 50.0)
    channels1 : float
        Protocol 1 Channels (default: 3.0)
    dutyCycle2_pct : float
        Protocol 2 Duty Cycle (%) (default: 5.0)
    channels2 : float
        Protocol 2 Channels (default: 37.0)
    txPowerOffset_dB : float
        TX Power Offset (P1−P2) (dB) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'effectiveCollision_pct', 'collisionProb_pct', 'throughputImpact_pct', 'sharedChannelFraction'
    """
    inputs = {"bandIndex": bandIndex, "dutyCycle1_pct": dutyCycle1_pct, "channels1": channels1, "dutyCycle2_pct": dutyCycle2_pct, "channels2": channels2, "txPowerOffset_dB": txPowerOffset_dB}
    return _client().calculate('ism-coexistence', inputs)


def attenuator_designer(attenuation: float = 6.0, impedance: float = 50.0) -> CalculatorResult:
    """
    RF Attenuator Designer

    Category: rf

    Design Pi (π) and T attenuator pads for any attenuation value and impedance. Returns standard resistor values for both topologies with nearest E24 values.

    Parameters
    ----------
    attenuation : float
        Attenuation (dB) (default: 6.0)
    impedance : float
        System Impedance (Ω) (default: 50.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'piR1', 'piR1Nearest', 'piR2', 'piR2Nearest', 'tR1', 'tR1Nearest', 'tR2', 'tR2Nearest'
    """
    inputs = {"attenuation": attenuation, "impedance": impedance}
    return _client().calculate('attenuator-designer', inputs)


def smith_chart(resistance: float = 50.0, reactance: float = 0.0, referenceImpedance: float = 50.0, frequency: float = 1000.0) -> CalculatorResult:
    """
    Smith Chart Calculator

    Category: rf

    Interactive Smith Chart for impedance matching and RF network analysis. Enter load impedance to visualize reflection coefficient, VSWR circle, and normalized impedance.

    Parameters
    ----------
    resistance : float
        Resistance (Ω) (default: 50.0)
    reactance : float
        Reactance (Ω) (default: 0.0)
    referenceImpedance : float
        Reference Impedance (Ω) (default: 50.0)
    frequency : float
        Frequency (MHz) (default: 1000.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'gamma_mag', 'gamma_ang', 'vswr', 'returnLoss', 'mismatchLoss', 'normalizedR', 'normalizedX'
    """
    inputs = {"resistance": resistance, "reactance": reactance, "referenceImpedance": referenceImpedance, "frequency": frequency}
    return _client().calculate('smith-chart', inputs)


def q_factor(componentType: float = 0.0, value: float = 10.0, esr: float = 0.5, frequency: float = 10.0) -> CalculatorResult:
    """
    Q Factor Calculator for Inductors & Capacitors

    Category: rf

    Calculate quality factor (Q) for inductors and capacitors, resonant circuit bandwidth, and equivalent series resistance

    Parameters
    ----------
    componentType : float
        Component Type (default: 0.0)
    value : float
        Inductance / Capacitance (μH / nF) (default: 10.0)
    esr : float
        Equivalent Series Resistance (Ω) (default: 0.5)
    frequency : float
        Frequency (MHz) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'qFactor', 'reactance', 'bandwidth', 'halfPowerFreqLow', 'halfPowerFreqHigh'
    """
    inputs = {"componentType": componentType, "value": value, "esr": esr, "frequency": frequency}
    return _client().calculate('q-factor', inputs)


def waveguide_cutoff(width: float = 22.86, height: float = 10.16, frequency: float = 10.0, modeM: float = 1.0, modeN: float = 0.0) -> CalculatorResult:
    """
    Rectangular Waveguide Cutoff Frequency Calculator

    Category: rf

    Calculate cutoff frequencies for rectangular waveguide TE and TM modes, guide wavelength, and phase velocity

    Parameters
    ----------
    width : float
        Waveguide Width (mm) (default: 22.86)
    height : float
        Waveguide Height (mm) (default: 10.16)
    frequency : float
        Operating Frequency (GHz) (default: 10.0)
    modeM : float
        Mode Index m (default: 1.0)
    modeN : float
        Mode Index n (default: 0.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'cutoffFreq', 'guideWavelength', 'phaseVelocity', 'groupVelocity', 'betaPropagates'
    """
    inputs = {"width": width, "height": height, "frequency": frequency, "modeM": modeM, "modeN": modeN}
    return _client().calculate('waveguide-cutoff', inputs)


def free_space_path_loss(frequency: float = 2400.0, distance: float = 1.0) -> CalculatorResult:
    """
    Free-Space Path Loss Calculator

    Category: rf

    Calculate free-space path loss (FSPL) using the Friis transmission equation for wireless link budget analysis

    Parameters
    ----------
    frequency : float
        Frequency (MHz) (default: 2400.0)
    distance : float
        Distance (km) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'fspl_dB', 'fspl_linear'
    """
    inputs = {"frequency": frequency, "distance": distance}
    return _client().calculate('free-space-path-loss', inputs)


def radar_range_equation(peakPower: float = 100.0, gain: float = 30.0, frequency: float = 3.0, rcs: float = 1.0, noiseFigure: float = 6.0, bandwidth: float = 1.0) -> CalculatorResult:
    """
    Radar Range Equation Calculator

    Category: rf

    Calculate maximum radar detection range using the radar range equation, including RCS, antenna gain, noise figure, and bandwidth parameters

    Parameters
    ----------
    peakPower : float
        Peak Transmit Power (kW) (default: 100.0)
    gain : float
        Antenna Gain (dBi) (default: 30.0)
    frequency : float
        Frequency (GHz) (default: 3.0)
    rcs : float
        Radar Cross Section (RCS) (m²) (default: 1.0)
    noiseFigure : float
        Receiver Noise Figure (dB) (default: 6.0)
    bandwidth : float
        Receiver Bandwidth (MHz) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'maxRange', 'snrAtMaxRange', 'receivedPower'
    """
    inputs = {"peakPower": peakPower, "gain": gain, "frequency": frequency, "rcs": rcs, "noiseFigure": noiseFigure, "bandwidth": bandwidth}
    return _client().calculate('radar-range-equation', inputs)


def power_amplifier_efficiency(outputPower: float = 30.0, inputPower: float = 0.0, dcVoltage: float = 5.0, dcCurrent: float = 500.0) -> CalculatorResult:
    """
    Power Amplifier Efficiency Calculator (PAE & Drain Efficiency)

    Category: rf

    Calculate RF power amplifier efficiency including power-added efficiency (PAE), drain efficiency, DC power consumption, and heat dissipation

    Parameters
    ----------
    outputPower : float
        Output Power (dBm) (default: 30.0)
    inputPower : float
        Input Power (dBm) (default: 0.0)
    dcVoltage : float
        DC Supply Voltage (V) (default: 5.0)
    dcCurrent : float
        DC Supply Current (mA) (default: 500.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'gain', 'dcPower', 'pae', 'drainEfficiency', 'dissipatedPower'
    """
    inputs = {"outputPower": outputPower, "inputPower": inputPower, "dcVoltage": dcVoltage, "dcCurrent": dcCurrent}
    return _client().calculate('power-amplifier-efficiency', inputs)


def intermodulation_distortion(outputPower: float = 10.0, inputPower: float = 0.0, oip3: float = 30.0, oip2: float = 50.0, freq1: float = 100.0, freq2: float = 101.0) -> CalculatorResult:
    """
    Intermodulation Distortion & IP3 Calculator

    Category: rf

    Calculate third-order intercept point (IP3), intermodulation distortion products, and spurious-free dynamic range for RF amplifiers and mixers

    Parameters
    ----------
    outputPower : float
        Output Power (dBm) (default: 10.0)
    inputPower : float
        Input Power (dBm) (default: 0.0)
    oip3 : float
        Output IP3 (OIP3) (dBm) (default: 30.0)
    oip2 : float
        Output IP2 (OIP2) (dBm) (default: 50.0)
    freq1 : float
        Tone 1 Frequency (MHz) (default: 100.0)
    freq2 : float
        Tone 2 Frequency (MHz) (default: 101.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'iip3', 'im3Power', 'im3Ratio', 'dynamicRange', 'iip2', 'im2Power', 'im2Ratio', 'im3Low', 'im3High', 'im2Sum', 'im2Diff', 'toneSpacing'
    """
    inputs = {"outputPower": outputPower, "inputPower": inputPower, "oip3": oip3, "oip2": oip2, "freq1": freq1, "freq2": freq2}
    return _client().calculate('intermodulation-distortion', inputs)


def phase_noise_to_jitter(carrierFreq: float = 100.0, phaseNoise: float = -120.0, offsetFreqLow: float = 1.0, offsetFreqHigh: float = 10000.0, profileMode: float = 0.0, offset2: float = 10.0, pn2: float = -140.0, offset3: float = 100.0, pn3: float = -155.0, offset4: float = 1000.0, pn4: float = -165.0) -> CalculatorResult:
    """
    Phase Noise to Jitter Converter

    Category: rf

    Convert oscillator phase noise (dBc/Hz) to RMS jitter and cycle-to-cycle jitter by integrating over a specified offset frequency range

    Parameters
    ----------
    carrierFreq : float
        Carrier Frequency (MHz) (default: 100.0)
    phaseNoise : float
        Phase Noise (dBc/Hz) (default: -120.0)
    offsetFreqLow : float
        Integration Start (Offset Low) (kHz) (default: 1.0)
    offsetFreqHigh : float
        Integration End (Offset High) (kHz) (default: 10000.0)
    profileMode : float
        Profile Mode (default: 0.0)
    offset2 : float
        Offset Point 2 (kHz) (default: 10.0)
    pn2 : float
        Phase Noise Point 2 (dBc/Hz) (default: -140.0)
    offset3 : float
        Offset Point 3 (kHz) (default: 100.0)
    pn3 : float
        Phase Noise Point 3 (dBc/Hz) (default: -155.0)
    offset4 : float
        Offset Point 4 (kHz) (default: 1000.0)
    pn4 : float
        Phase Noise Point 4 (dBc/Hz) (default: -165.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'rmsJitter', 'cycleToCycleJitter', 'phaseNoisePower', 'rmsPhaseError', 'adcSnrLimit'
    """
    inputs = {"carrierFreq": carrierFreq, "phaseNoise": phaseNoise, "offsetFreqLow": offsetFreqLow, "offsetFreqHigh": offsetFreqHigh, "profileMode": profileMode, "offset2": offset2, "pn2": pn2, "offset3": offset3, "pn3": pn3, "offset4": offset4, "pn4": pn4}
    return _client().calculate('phase-noise-to-jitter', inputs)


def vibration_phase_noise(carrierFreq: float = 10.0, vibSensitivity: float = 1.0, vibAccel: float = 1.0, vibFreq: float = 100.0) -> CalculatorResult:
    """
    Phase Noise Under Vibrations Calculator

    Category: rf

    Calculate vibration-induced phase noise degradation for oscillators on defense, aerospace, and mobile platforms using acceleration sensitivity (Gamma) and vibration profiles

    Parameters
    ----------
    carrierFreq : float
        Carrier Frequency (GHz) (default: 10.0)
    vibSensitivity : float
        Acceleration Sensitivity (ppb/g) (default: 1.0)
    vibAccel : float
        Vibration Acceleration (g rms) (default: 1.0)
    vibFreq : float
        Vibration Frequency (Hz) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'lvib', 'lRandom', 'freqDev', 'degradation'
    """
    inputs = {"carrierFreq": carrierFreq, "vibSensitivity": vibSensitivity, "vibAccel": vibAccel, "vibFreq": vibFreq}
    return _client().calculate('vibration-phase-noise', inputs)


def return_loss_error(dutReturnLoss: float = 20.0, directivity: float = 35.0, sourceMatch: float = 30.0) -> CalculatorResult:
    """
    Return Loss Measurement Error Calculator

    Category: rf

    Calculate measurement uncertainty for return loss measurements using directional couplers or bridges. Accounts for coupler directivity and source match errors critical for VNA and test engineering.

    Parameters
    ----------
    dutReturnLoss : float
        DUT Return Loss (dB) (default: 20.0)
    directivity : float
        Coupler Directivity (dB) (default: 35.0)
    sourceMatch : float
        Source Match (dB) (default: 30.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'rlMax', 'rlMin', 'uncertaintyDb', 'dirError'
    """
    inputs = {"dutReturnLoss": dutReturnLoss, "directivity": directivity, "sourceMatch": sourceMatch}
    return _client().calculate('return-loss-error', inputs)


def fresnel_zone(frequency: float = 5.8, distance: float = 1.0, n: float = 1.0) -> CalculatorResult:
    """
    Fresnel Zone Calculator

    Category: rf

    Calculate Fresnel zone radius at the midpoint of an RF line-of-sight link. Determine required clearance above obstructions for reliable microwave and WiFi links.

    Parameters
    ----------
    frequency : float
        Frequency (GHz) (default: 5.8)
    distance : float
        Link Distance (km) (default: 1.0)
    n : float
        Fresnel Zone Number (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'radiusM', 'clearanceM', 'wavelengthM'
    """
    inputs = {"frequency": frequency, "distance": distance, "n": n}
    return _client().calculate('fresnel-zone', inputs)


def power_density(eirp: float = 30.0, distance: float = 10.0, frequency: float = 2.4) -> CalculatorResult:
    """
    RF Power Density Calculator

    Category: rf

    Calculate RF power density (W/m²), electric field strength (V/m), and magnetic field strength (A/m) from EIRP and distance. Useful for EMF exposure and safety analysis.

    Parameters
    ----------
    eirp : float
        EIRP (dBm) (default: 30.0)
    distance : float
        Distance (m) (default: 10.0)
    frequency : float
        Frequency (GHz) (default: 2.4)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'powerDensity', 'efield', 'hfield', 'planeWaveImpedance'
    """
    inputs = {"eirp": eirp, "distance": distance, "frequency": frequency}
    return _client().calculate('power-density', inputs)


def balun_transformer(zSource: float = 50.0, zLoad: float = 200.0, frequency: float = 100.0, bandwidth: float = 10.0) -> CalculatorResult:
    """
    Balun & RF Transformer Calculator

    Category: rf

    Calculate balun and RF transformer turns ratio, impedance transformation ratio, and insertion loss for balanced/unbalanced feed line matching.

    Parameters
    ----------
    zSource : float
        Source Impedance (Ω) (default: 50.0)
    zLoad : float
        Load Impedance (Ω) (default: 200.0)
    frequency : float
        Frequency (MHz) (default: 100.0)
    bandwidth : float
        Bandwidth (MHz) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'turnsRatio', 'impedanceRatio', 'insertionLoss', 'vswr'
    """
    inputs = {"zSource": zSource, "zLoad": zLoad, "frequency": frequency, "bandwidth": bandwidth}
    return _client().calculate('balun-transformer', inputs)


def link_margin(txPower: float = 20.0, txGain: float = 3.0, rxGain: float = 3.0, distance: float = 1.0, frequency: float = 2.4, sensitivity: float = -90.0, cableLoss: float = 1.0) -> CalculatorResult:
    """
    RF Link Margin Calculator

    Category: rf

    Calculate RF link margin from TX power, antenna gains, free-space path loss, and receiver sensitivity. Determines maximum range and fade margin for wireless links.

    Parameters
    ----------
    txPower : float
        TX Power (dBm) (default: 20.0)
    txGain : float
        TX Antenna Gain (dBi) (default: 3.0)
    rxGain : float
        RX Antenna Gain (dBi) (default: 3.0)
    distance : float
        Link Distance (km) (default: 1.0)
    frequency : float
        Frequency (GHz) (default: 2.4)
    sensitivity : float
        RX Sensitivity (dBm) (default: -90.0)
    cableLoss : float
        Cable/Connector Loss (dB) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'fspl', 'receivedPower', 'linkMargin', 'maxRange'
    """
    inputs = {"txPower": txPower, "txGain": txGain, "rxGain": rxGain, "distance": distance, "frequency": frequency, "sensitivity": sensitivity, "cableLoss": cableLoss}
    return _client().calculate('link-margin', inputs)


def mixer_spur_calculator(rfFreq: float = 915.0, loFreq: float = 1000.0, maxOrder: float = 5.0) -> CalculatorResult:
    """
    Mixer Spur Calculator

    Category: rf

    Calculate mixer spurious products (m×fLO ± n×fRF) for superheterodyne receiver design. Identify problematic spurs near the IF passband and optimize LO/IF frequency planning.

    Parameters
    ----------
    rfFreq : float
        RF Frequency (MHz) (default: 915.0)
    loFreq : float
        LO Frequency (MHz) (default: 1000.0)
    maxOrder : float
        Maximum Spur Order (default: 5.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'ifLow', 'ifHigh', 'im3Low', 'im3High', 'im3RfLow', 'im3RfHigh', 'totalSpurs', 'spursNearIf'
    """
    inputs = {"rfFreq": rfFreq, "loFreq": loFreq, "maxOrder": maxOrder}
    return _client().calculate('mixer-spur-calculator', inputs)

