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

Functions:
    shielding_effectiveness(...) -> CalculatorResult
    ferrite_bead(...) -> CalculatorResult
    emi_filter_lc(...) -> CalculatorResult
    esd_tvs_diode(...) -> CalculatorResult
    common_mode_choke(...) -> CalculatorResult
    decoupling_capacitor_emc(...) -> CalculatorResult
    esd_clamp_selection(...) -> CalculatorResult
    radiated_emission_estimate(...) -> CalculatorResult
    ground_plane_impedance(...) -> CalculatorResult
    pcb_crosstalk_emc(...) -> CalculatorResult
    power_supply_ripple_filter(...) -> CalculatorResult
    cable_shield_effectiveness(...) -> CalculatorResult
    chassis_resonance(...) -> CalculatorResult
    emi_margin_budget(...) -> CalculatorResult
    conducted_emissions_filter(...) -> CalculatorResult
    differential_mode_filter(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


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


def shielding_effectiveness(frequency: float = 1000.0, thickness: float = 1.0, conductivity: float = 59.6, permeability: float = 1.0) -> CalculatorResult:
    """
    Shielding Effectiveness Calculator

    Category: emc

    Calculate electromagnetic shielding effectiveness of conductive enclosures

    Parameters
    ----------
    frequency : float
        Frequency (MHz) (default: 1000.0)
    thickness : float
        Shield Thickness (mm) (default: 1.0)
    conductivity : float
        Conductivity (MS/m) (default: 59.6)
    permeability : float
        Relative Permeability (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'absorptionLoss', 'reflectionLoss', 'totalSE', 'skinDepth', 'thicknessVsSkin'
    """
    inputs = {"frequency": frequency, "thickness": thickness, "conductivity": conductivity, "permeability": permeability}
    return _client().calculate('shielding-effectiveness', inputs)


def ferrite_bead(impedance100MHz: float = 600.0, dcResistance: float = 0.3, loadImpedance: float = 50.0, frequency: float = 100.0) -> CalculatorResult:
    """
    Ferrite Bead Filter Calculator

    Category: emc

    Calculate ferrite bead filter effectiveness, impedance at frequency, and insertion loss for EMI suppression

    Parameters
    ----------
    impedance100MHz : float
        Impedance at 100 MHz (Ω) (default: 600.0)
    dcResistance : float
        DC Resistance (Ω) (default: 0.3)
    loadImpedance : float
        Load Impedance (Ω) (default: 50.0)
    frequency : float
        Frequency (MHz) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'beadImpedance', 'insertionLoss', 'voltageDivider', 'dcVoltageDrop'
    """
    inputs = {"impedance100MHz": impedance100MHz, "dcResistance": dcResistance, "loadImpedance": loadImpedance, "frequency": frequency}
    return _client().calculate('ferrite-bead', inputs)


def emi_filter_lc(fc: float = 150.0, attenuationNeeded: float = 40.0, zSource: float = 50.0, zLoad: float = 50.0) -> CalculatorResult:
    """
    LC EMI Filter Design Calculator

    Category: emc

    Design an LC low-pass EMI filter for conducted emissions suppression — calculate inductance, capacitance, filter order, and attenuation at the stop band.

    Parameters
    ----------
    fc : float
        Cutoff Frequency (kHz) (default: 150.0)
    attenuationNeeded : float
        Required Attenuation (dB) (default: 40.0)
    zSource : float
        Source Impedance (Ω) (default: 50.0)
    zLoad : float
        Load Impedance (Ω) (default: 50.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'inductance', 'capacitance', 'filterOrder', 'actualAttenuation', 'impedanceMatching'
    """
    inputs = {"fc": fc, "attenuationNeeded": attenuationNeeded, "zSource": zSource, "zLoad": zLoad}
    return _client().calculate('emi-filter-lc', inputs)


def esd_tvs_diode(vwm: float = 5.0, esd_level: float = 2.0, clampMultiplier: float = 1.3) -> CalculatorResult:
    """
    ESD TVS Diode Selection Calculator

    Category: emc

    Calculate TVS diode clamping voltage, breakdown voltage, peak pulse current, and power rating for ESD protection circuit design.

    Parameters
    ----------
    vwm : float
        Working Voltage (V) (default: 5.0)
    esd_level : float
        ESD Level (default: 2.0)
    clampMultiplier : float
        Clamp Voltage Multiplier (default: 1.3)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'vclamp', 'vBR', 'ipp', 'ppwr', 'energy'
    """
    inputs = {"vwm": vwm, "esd_level": esd_level, "clampMultiplier": clampMultiplier}
    return _client().calculate('esd-tvs-diode', inputs)


def common_mode_choke(inductance: float = 1000.0, frequency: float = 150000.0, dcr: float = 0.5) -> CalculatorResult:
    """
    Common Mode Choke Impedance

    Category: emc

    Calculate common mode choke impedance, insertion loss, and Q factor at a given frequency for EMC filter design.

    Parameters
    ----------
    inductance : float
        Inductance (μH) (default: 1000.0)
    frequency : float
        Frequency (Hz) (default: 150000.0)
    dcr : float
        DC Resistance (DCR) (Ω) (default: 0.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'impedance', 'attenuation', 'qualityFactor'
    """
    inputs = {"inductance": inductance, "frequency": frequency, "dcr": dcr}
    return _client().calculate('common-mode-choke', inputs)


def decoupling_capacitor_emc(capacitance: float = 100.0, esr: float = 0.05, frequency: float = 100.0, packageInductance: float = 1.0) -> CalculatorResult:
    """
    Decoupling Capacitor EMC Selection

    Category: emc

    Calculate decoupling capacitor impedance at frequency and self-resonant frequency for EMC power supply decoupling.

    Parameters
    ----------
    capacitance : float
        Capacitance (nF) (default: 100.0)
    esr : float
        ESR (Ω) (default: 0.05)
    frequency : float
        Target Frequency (kHz) (default: 100.0)
    packageInductance : float
        Package Inductance (nH) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'xc', 'impedance', 'srf'
    """
    inputs = {"capacitance": capacitance, "esr": esr, "frequency": frequency, "packageInductance": packageInductance}
    return _client().calculate('decoupling-capacitor-emc', inputs)


def esd_clamp_selection(esdVoltage: float = 4000.0, clampVoltage: float = 15.0, lineImpedance: float = 330.0) -> CalculatorResult:
    """
    ESD Clamp Diode Selection

    Category: emc

    Calculate ESD clamp diode peak current, power dissipation, and clamping ratio to verify protection for IEC 61000-4-2 compliance.

    Parameters
    ----------
    esdVoltage : float
        ESD Strike Voltage (V) (default: 4000.0)
    clampVoltage : float
        Clamp Voltage (V_cl) (V) (default: 15.0)
    lineImpedance : float
        Line Impedance (Ω) (default: 330.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'peakCurrent', 'clampPower', 'voltageMargin', 'clampingRatio'
    """
    inputs = {"esdVoltage": esdVoltage, "clampVoltage": clampVoltage, "lineImpedance": lineImpedance}
    return _client().calculate('esd-clamp-selection', inputs)


def radiated_emission_estimate(current: float = 10.0, loopArea: float = 1.0, frequency: float = 100.0, distance: float = 3.0) -> CalculatorResult:
    """
    Radiated Emission Estimate

    Category: emc

    Estimate far-field radiated emissions from a PCB current loop using the small-loop antenna model. Compare against CISPR 22/FCC Class B limits.

    Parameters
    ----------
    current : float
        Loop Current (peak) (mA) (default: 10.0)
    loopArea : float
        Loop Area (cm²) (default: 1.0)
    frequency : float
        Frequency (MHz) (default: 100.0)
    distance : float
        Measurement Distance (m) (default: 3.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'eFieldDbuvM', 'margin'
    """
    inputs = {"current": current, "loopArea": loopArea, "frequency": frequency, "distance": distance}
    return _client().calculate('radiated-emission-estimate', inputs)


def ground_plane_impedance(length: float = 100.0, width: float = 50.0, thickness: float = 35.0, frequency: float = 10.0, conductivity: float = 58.0) -> CalculatorResult:
    """
    Ground Plane Impedance vs Frequency

    Category: emc

    Calculate PCB ground plane AC impedance, skin depth, and inductive reactance at high frequencies for EMC analysis.

    Parameters
    ----------
    length : float
        Plane Length (mm) (default: 100.0)
    width : float
        Plane Width (mm) (default: 50.0)
    thickness : float
        Copper Thickness (μm) (default: 35.0)
    frequency : float
        Frequency (MHz) (default: 10.0)
    conductivity : float
        Conductivity (MS/m) (default: 58.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'dcResistance', 'skinDepth', 'acResistance', 'inductance', 'totalImpedance'
    """
    inputs = {"length": length, "width": width, "thickness": thickness, "frequency": frequency, "conductivity": conductivity}
    return _client().calculate('ground-plane-impedance', inputs)


def pcb_crosstalk_emc(aggressorVoltage: float = 3.3, mutualCapacitance: float = 20.0, mutualInductance: float = 10.0, frequency: float = 100.0, lineImpedance: float = 50.0) -> CalculatorResult:
    """
    PCB Trace Crosstalk (EMC)

    Category: emc

    Estimate PCB trace crosstalk (capacitive and inductive coupling) for EMC pre-compliance analysis.

    Parameters
    ----------
    aggressorVoltage : float
        Aggressor Voltage (V) (default: 3.3)
    mutualCapacitance : float
        Mutual Capacitance (pF) (default: 20.0)
    mutualInductance : float
        Mutual Inductance (nH) (default: 10.0)
    frequency : float
        Frequency (MHz) (default: 100.0)
    lineImpedance : float
        Victim Line Impedance (Ω) (default: 50.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'capacitiveCoupling', 'inductiveCoupling', 'totalCrosstalk', 'crosstalkDb'
    """
    inputs = {"aggressorVoltage": aggressorVoltage, "mutualCapacitance": mutualCapacitance, "mutualInductance": mutualInductance, "frequency": frequency, "lineImpedance": lineImpedance}
    return _client().calculate('pcb-crosstalk-emc', inputs)


def power_supply_ripple_filter(inputRipple: float = 100.0, frequency: float = 100.0, inductance: float = 10.0, capacitance: float = 10.0) -> CalculatorResult:
    """
    Power Supply Ripple Filter

    Category: emc

    Calculate LC filter attenuation and output ripple voltage for power supply EMC filtering. Find the resonant frequency and ripple rejection.

    Parameters
    ----------
    inputRipple : float
        Input Ripple Voltage (mV) (default: 100.0)
    frequency : float
        Ripple Frequency (kHz) (default: 100.0)
    inductance : float
        Inductor Value (μH) (default: 10.0)
    capacitance : float
        Capacitor Value (μF) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'resonantFreq', 'attenuation', 'outputRipple'
    """
    inputs = {"inputRipple": inputRipple, "frequency": frequency, "inductance": inductance, "capacitance": capacitance}
    return _client().calculate('power-supply-ripple-filter', inputs)


def cable_shield_effectiveness(shieldResistance: float = 10.0, cableLength: float = 2.0, frequency: float = 10.0) -> CalculatorResult:
    """
    Cable Shield Effectiveness

    Category: emc

    Calculate coaxial cable or shielded cable shield effectiveness (shielding factor) vs frequency using the transfer impedance model.

    Parameters
    ----------
    shieldResistance : float
        Shield DC Resistance (mΩ/m) (default: 10.0)
    cableLength : float
        Cable Length (m) (default: 2.0)
    frequency : float
        Frequency (MHz) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'shieldingEffectDb', 'transferImpedance'
    """
    inputs = {"shieldResistance": shieldResistance, "cableLength": cableLength, "frequency": frequency}
    return _client().calculate('cable-shield-effectiveness', inputs)


def chassis_resonance(length: float = 30.0, width: float = 20.0, height: float = 10.0) -> CalculatorResult:
    """
    Chassis Resonant Frequency

    Category: emc

    Calculate the lowest resonant frequency of a metallic enclosure (cavity resonator) to identify potential EMC problems.

    Parameters
    ----------
    length : float
        Length (cm) (default: 30.0)
    width : float
        Width (cm) (default: 20.0)
    height : float
        Height (cm) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'fLowest', 'f101MHz', 'f110MHz', 'wavelengthAtResonance'
    """
    inputs = {"length": length, "width": width, "height": height}
    return _client().calculate('chassis-resonance', inputs)


def emi_margin_budget(measuredLevel: float = 30.0, limitLevel: float = 40.0, measurementUncertainty: float = 6.0, safetyMargin: float = 6.0) -> CalculatorResult:
    """
    EMI Margin Budget

    Category: emc

    Calculate EMI compliance margin accounting for measurement uncertainty and safety margin to predict pre-compliance test pass/fail.

    Parameters
    ----------
    measuredLevel : float
        Measured Emission Level (dBμV/m) (default: 30.0)
    limitLevel : float
        Regulatory Limit (dBμV/m) (default: 40.0)
    measurementUncertainty : float
        Measurement Uncertainty (dB) (default: 6.0)
    safetyMargin : float
        Design Safety Margin (dB) (default: 6.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'rawMargin', 'adjustedMargin', 'requiredReduction'
    """
    inputs = {"measuredLevel": measuredLevel, "limitLevel": limitLevel, "measurementUncertainty": measurementUncertainty, "safetyMargin": safetyMargin}
    return _client().calculate('emi-margin-budget', inputs)


def conducted_emissions_filter(emissionLevel: float = 80.0, frequency: float = 150.0, targetAttenuation: float = 20.0, loadImpedance: float = 50.0) -> CalculatorResult:
    """
    Conducted Emissions LC Filter

    Category: emc

    Design an LC filter to meet CISPR 22/FCC conducted emissions limits by calculating required L and C values for a target attenuation.

    Parameters
    ----------
    emissionLevel : float
        Measured Emission (dBμV) (default: 80.0)
    frequency : float
        Problem Frequency (kHz) (default: 150.0)
    targetAttenuation : float
        Required Attenuation (dB) (default: 20.0)
    loadImpedance : float
        Load Impedance (Ω) (default: 50.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'requiredF0', 'cValue', 'lValue', 'outputLevel'
    """
    inputs = {"emissionLevel": emissionLevel, "frequency": frequency, "targetAttenuation": targetAttenuation, "loadImpedance": loadImpedance}
    return _client().calculate('conducted-emissions-filter', inputs)


def differential_mode_filter(inductance: float = 47.0, capacitance: float = 0.47, frequency: float = 150.0) -> CalculatorResult:
    """
    Differential Mode EMI Filter

    Category: emc

    Design a differential mode LC EMI filter: calculate corner frequency, attenuation, and characteristic impedance for SMPS output filtering.

    Parameters
    ----------
    inductance : float
        Differential Mode Inductance (μH) (default: 47.0)
    capacitance : float
        Differential Mode Capacitance (μF) (default: 0.47)
    frequency : float
        Problem Frequency (kHz) (default: 150.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'cornerFreq', 'attenuation', 'characteristicImpedance'
    """
    inputs = {"inductance": inductance, "capacitance": capacitance, "frequency": frequency}
    return _client().calculate('differential-mode-filter', inputs)

