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

Functions:
    dipole_antenna(...) -> CalculatorResult
    patch_antenna(...) -> CalculatorResult
    eirp_calculator(...) -> CalculatorResult
    antenna_beamwidth(...) -> CalculatorResult
    yagi_antenna(...) -> CalculatorResult
    horn_antenna(...) -> CalculatorResult
    parabolic_dish_antenna(...) -> CalculatorResult
    loop_antenna(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


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


def dipole_antenna(frequency: float = 433.0, velocityFactor: float = 0.97) -> CalculatorResult:
    """
    Half-Wave Dipole Antenna Calculator

    Category: antenna

    Calculate the physical length, wavelength, gain, radiation resistance, and 50Ω VSWR for a half-wave dipole antenna at any frequency. Supports velocity factor for insulated wire.

    Parameters
    ----------
    frequency : float
        Frequency (MHz) (default: 433.0)
    velocityFactor : float
        Velocity Factor (default: 0.97)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'halfWaveLength_mm', 'quarterWaveLength_mm', 'gainDbi', 'inputImpedance_ohm', 'feedpointVswr_50', 'lambda_m'
    """
    inputs = {"frequency": frequency, "velocityFactor": velocityFactor}
    return _client().calculate('dipole-antenna', inputs)


def patch_antenna(frequency: float = 2.45, dielectricConstant: float = 4.4, substrateHeight: float = 1.6, feedOffset: float = 0.0) -> CalculatorResult:
    """
    Microstrip Patch Antenna Calculator

    Category: antenna

    Calculate rectangular microstrip patch antenna dimensions (width, length) using the Transmission Line Model. Outputs effective dielectric constant, edge-feed impedance, and nominal gain for common substrates like FR4 and Rogers.

    Parameters
    ----------
    frequency : float
        Frequency (GHz) (default: 2.45)
    dielectricConstant : float
        Dielectric Constant (default: 4.4)
    substrateHeight : float
        Substrate Height (mm) (default: 1.6)
    feedOffset : float
        Feed Offset (mm) (default: 0.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'patchWidth_mm', 'patchLength_mm', 'effectiveDielectric', 'edgeFeedImpedance_ohm', 'gainDbi'
    """
    inputs = {"frequency": frequency, "dielectricConstant": dielectricConstant, "substrateHeight": substrateHeight, "feedOffset": feedOffset}
    return _client().calculate('patch-antenna', inputs)


def eirp_calculator(txPower_dbm: float = 20.0, cableLoss_db: float = 1.0, antennaGain_dbi: float = 2.15, regulatoryLimit_dbm: float = 36.0) -> CalculatorResult:
    """
    EIRP / ERP Regulatory Calculator

    Category: antenna

    Calculate Effective Isotropic Radiated Power (EIRP) and ERP from transmit power, cable loss, and antenna gain. Check compliance against FCC, ETSI, and ISM-band regulatory limits.

    Parameters
    ----------
    txPower_dbm : float
        TX Power (dBm) (default: 20.0)
    cableLoss_db : float
        Cable / Connector Loss (dB) (default: 1.0)
    antennaGain_dbi : float
        Antenna Gain (dBi) (default: 2.15)
    regulatoryLimit_dbm : float
        Regulatory EIRP Limit (dBm) (default: 36.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'eirp_dbm', 'erp_dbm', 'eirp_w', 'margin_db', 'maxPermittedGain_dbi'
    """
    inputs = {"txPower_dbm": txPower_dbm, "cableLoss_db": cableLoss_db, "antennaGain_dbi": antennaGain_dbi, "regulatoryLimit_dbm": regulatoryLimit_dbm}
    return _client().calculate('eirp-calculator', inputs)


def antenna_beamwidth(gain: float = 20.0, frequency: float = 10.0, apertureDiameter: float = 0.3, apertureEfficiency: float = 55.0) -> CalculatorResult:
    """
    Antenna Beamwidth & Gain Calculator

    Category: antenna

    Calculate antenna 3dB beamwidth from gain, aperture efficiency, and frequency for aperture antennas

    Parameters
    ----------
    gain : float
        Antenna Gain (dBi) (default: 20.0)
    frequency : float
        Frequency (GHz) (default: 10.0)
    apertureDiameter : float
        Aperture Diameter (m) (default: 0.3)
    apertureEfficiency : float
        Aperture Efficiency (%) (default: 55.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'beamwidthHPBW', 'beamwidthNulls', 'effectiveArea', 'wavelength', 'gainFromAperture'
    """
    inputs = {"gain": gain, "frequency": frequency, "apertureDiameter": apertureDiameter, "apertureEfficiency": apertureEfficiency}
    return _client().calculate('antenna-beamwidth', inputs)


def yagi_antenna(frequency: float = 144.0, numElements: float = 5.0, boomLength: float = 1.0) -> CalculatorResult:
    """
    Yagi-Uda Antenna Design Calculator

    Category: antenna

    Calculate Yagi-Uda antenna element dimensions, gain, and impedance for a given frequency and number of elements

    Parameters
    ----------
    frequency : float
        Frequency (MHz) (default: 144.0)
    numElements : float
        Number of Elements (default: 5.0)
    boomLength : float
        Boom Length (m) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'gain', 'driverLength', 'reflectorLength', 'directorLength', 'spacing', 'impedance'
    """
    inputs = {"frequency": frequency, "numElements": numElements, "boomLength": boomLength}
    return _client().calculate('yagi-antenna', inputs)


def horn_antenna(frequency: float = 10.0, apertureWidth: float = 50.0, apertureHeight: float = 40.0) -> CalculatorResult:
    """
    Horn Antenna Gain & Beamwidth Calculator

    Category: antenna

    Calculate pyramidal horn antenna gain, E-plane and H-plane half-power beamwidths, and effective aperture area for microwave applications

    Parameters
    ----------
    frequency : float
        Frequency (GHz) (default: 10.0)
    apertureWidth : float
        Aperture Width (H-plane) (mm) (default: 50.0)
    apertureHeight : float
        Aperture Height (E-plane) (mm) (default: 40.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'gain', 'hpbwE', 'hpbwH', 'effectiveArea', 'wavelength'
    """
    inputs = {"frequency": frequency, "apertureWidth": apertureWidth, "apertureHeight": apertureHeight}
    return _client().calculate('horn-antenna', inputs)


def parabolic_dish_antenna(frequency: float = 12.0, diameter: float = 1.2, efficiency: float = 55.0) -> CalculatorResult:
    """
    Parabolic Dish Antenna Calculator

    Category: antenna

    Calculate parabolic dish antenna gain, half-power beamwidth (HPBW), effective aperture area, and noise temperature for satellite and microwave links

    Parameters
    ----------
    frequency : float
        Frequency (GHz) (default: 12.0)
    diameter : float
        Dish Diameter (m) (default: 1.2)
    efficiency : float
        Aperture Efficiency (%) (default: 55.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'gain', 'hpbw', 'effectiveArea', 'noiseTemperature'
    """
    inputs = {"frequency": frequency, "diameter": diameter, "efficiency": efficiency}
    return _client().calculate('parabolic-dish-antenna', inputs)


def loop_antenna(frequency: float = 7.0, diameter: float = 1.0, conductorDiam: float = 10.0) -> CalculatorResult:
    """
    Loop Antenna Calculator

    Category: antenna

    Calculate small loop antenna radiation resistance, loss resistance, gain, Q factor, and operating bandwidth for HF and VHF applications

    Parameters
    ----------
    frequency : float
        Frequency (MHz) (default: 7.0)
    diameter : float
        Loop Diameter (m) (default: 1.0)
    conductorDiam : float
        Conductor Diameter (mm) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'circumference', 'radiation_resistance', 'loss_resistance', 'gain', 'bandwidth'
    """
    inputs = {"frequency": frequency, "diameter": diameter, "conductorDiam": conductorDiam}
    return _client().calculate('loop-antenna', inputs)

