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

Functions:
    trace_width_current(...) -> CalculatorResult
    trace_resistance(...) -> CalculatorResult
    differential_pair(...) -> CalculatorResult
    via_calculator(...) -> CalculatorResult
    stackup_builder(...) -> CalculatorResult
    controlled_impedance(...) -> CalculatorResult
    pcb_crosstalk(...) -> CalculatorResult
    decoupling_capacitor(...) -> CalculatorResult
    pcb_trace_inductance(...) -> CalculatorResult
    via_thermal_resistance(...) -> CalculatorResult
    power_plane_impedance(...) -> CalculatorResult
    via_stub_resonance(...) -> CalculatorResult
    solder_paste_volume(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


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


def trace_width_current(current: float = 1.0, copperWeight: float = 1.0, tempRise: float = 10.0, traceLength: float = 100.0, isExternal: float = 1.0) -> CalculatorResult:
    """
    PCB Trace Width Calculator (IPC-2221 / IPC-2152)

    Category: pcb

    Calculate minimum PCB trace width for a given current, copper weight, and temperature rise per IPC-2221 and IPC-2152 standards. Includes resistance and voltage drop.

    Parameters
    ----------
    current : float
        Current (A) (default: 1.0)
    copperWeight : float
        Copper Weight (oz) (default: 1.0)
    tempRise : float
        Temperature Rise (°C) (default: 10.0)
    traceLength : float
        Trace Length (mm) (default: 100.0)
    isExternal : float
        Layer Type (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'width2221mm', 'width2152mm', 'resistance', 'voltageDrop', 'powerDiss'
    """
    inputs = {"current": current, "copperWeight": copperWeight, "tempRise": tempRise, "traceLength": traceLength, "isExternal": isExternal}
    return _client().calculate('trace-width-current', inputs)


def trace_resistance(traceWidth: float = 0.5, traceLength: float = 100.0, copperThickness: float = 35.0, temperature: float = 25.0) -> CalculatorResult:
    """
    PCB Trace Resistance Calculator

    Category: pcb

    Calculate PCB copper trace DC resistance from width, length, thickness, and temperature. Includes sheet resistance and temperature coefficient.

    Parameters
    ----------
    traceWidth : float
        Trace Width (mm) (default: 0.5)
    traceLength : float
        Trace Length (mm) (default: 100.0)
    copperThickness : float
        Copper Thickness (μm) (default: 35.0)
    temperature : float
        Temperature (°C) (default: 25.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'resistance', 'resistanceMOhm', 'sheetResistance'
    """
    inputs = {"traceWidth": traceWidth, "traceLength": traceLength, "copperThickness": copperThickness, "temperature": temperature}
    return _client().calculate('trace-resistance', inputs)


def differential_pair(traceWidth: float = 0.15, traceSpacing: float = 0.15, substrateHeight: float = 0.1, dielectricConstant: float = 4.2, copperThickness: float = 17.5) -> CalculatorResult:
    """
    Differential Pair Impedance Calculator

    Category: pcb

    Calculate differential (Zdiff) and common-mode (Zcom) impedance for edge-coupled microstrip differential pairs used in USB, HDMI, Ethernet, and high-speed serial interfaces.

    Parameters
    ----------
    traceWidth : float
        Trace Width (mm) (default: 0.15)
    traceSpacing : float
        Trace Spacing (edge-to-edge) (mm) (default: 0.15)
    substrateHeight : float
        Substrate Height (mm) (default: 0.1)
    dielectricConstant : float
        Dielectric Constant (default: 4.2)
    copperThickness : float
        Copper Thickness (μm) (default: 17.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'zdiff', 'zcom', 'z0single', 'zodd', 'zeven'
    """
    inputs = {"traceWidth": traceWidth, "traceSpacing": traceSpacing, "substrateHeight": substrateHeight, "dielectricConstant": dielectricConstant, "copperThickness": copperThickness}
    return _client().calculate('differential-pair', inputs)


def via_calculator(viaDiameter: float = 0.3, padDiameter: float = 0.6, boardThickness: float = 1.6, dielectricConstant: float = 4.2, copperThickness: float = 25.0, signalLayer: float = 0.0) -> CalculatorResult:
    """
    PCB Via Calculator

    Category: pcb

    Calculate PCB via impedance, capacitance, inductance, current capacity, aspect ratio, and DFM warnings. Covers through-hole and blind/buried vias.

    Parameters
    ----------
    viaDiameter : float
        Via Drill Diameter (mm) (default: 0.3)
    padDiameter : float
        Pad Diameter (mm) (default: 0.6)
    boardThickness : float
        Board Thickness (mm) (default: 1.6)
    dielectricConstant : float
        Dielectric Constant (default: 4.2)
    copperThickness : float
        Copper Plating Thickness (μm) (default: 25.0)
    signalLayer : float
        Signal Layer (default: 0.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'impedance', 'capacitancePF', 'inductanceNH', 'aspectRatio', 'currentCapacityA'
    """
    inputs = {"viaDiameter": viaDiameter, "padDiameter": padDiameter, "boardThickness": boardThickness, "dielectricConstant": dielectricConstant, "copperThickness": copperThickness, "signalLayer": signalLayer}
    return _client().calculate('via-calculator', inputs)


def stackup_builder(layerCount: float = 4.0, targetImpedance: float = 50.0, dielectricH1: float = 0.2, dielectricH2: float = 1.2, dielectricH3: float = 0.2, copperWeight: float = 1.0, dielectricConstant: float = 4.2) -> CalculatorResult:
    """
    PCB Stackup Impedance Calculator

    Category: pcb

    Calculate characteristic impedance for common PCB stackup configurations. Select layer count, dielectric thickness, and copper weight to get target trace width for 50Ω or custom impedance.

    Parameters
    ----------
    layerCount : float
        Layer Count (default: 4.0)
    targetImpedance : float
        Target Impedance (Ω) (default: 50.0)
    dielectricH1 : float
        Dielectric H1 (L1 to L2) (mm) (default: 0.2)
    dielectricH2 : float
        Dielectric H2 (L2 to L3 core) (mm) (default: 1.2)
    dielectricH3 : float
        Dielectric H3 (L3 to L4) (mm) (default: 0.2)
    copperWeight : float
        Copper Weight (oz) (default: 1.0)
    dielectricConstant : float
        Dielectric Constant (default: 4.2)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'traceWidthL1mm', 'traceWidthL3mm', 'achievedImpedanceL1', 'achievedImpedanceL3', 'totalThicknessMm'
    """
    inputs = {"layerCount": layerCount, "targetImpedance": targetImpedance, "dielectricH1": dielectricH1, "dielectricH2": dielectricH2, "dielectricH3": dielectricH3, "copperWeight": copperWeight, "dielectricConstant": dielectricConstant}
    return _client().calculate('stackup-builder', inputs)


def controlled_impedance(traceType: float = 0.0, traceWidth: float = 1.8, substrateHeight: float = 0.2, dielectricConst: float = 4.4, copperThickness: float = 35.0, coverHeight: float = 0.1) -> CalculatorResult:
    """
    PCB Controlled Impedance Calculator

    Category: pcb

    Calculate characteristic impedance for surface microstrip, embedded microstrip, and stripline PCB traces

    Parameters
    ----------
    traceType : float
        Trace Type (default: 0.0)
    traceWidth : float
        Trace Width (mm) (default: 1.8)
    substrateHeight : float
        Substrate Height (mm) (default: 0.2)
    dielectricConst : float
        Dielectric Constant (default: 4.4)
    copperThickness : float
        Copper Thickness (μm) (default: 35.0)
    coverHeight : float
        Cover Layer Height (mm) (default: 0.1)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'impedance', 'effectiveDielectric', 'propagationDelay', 'traceWidthFor50'
    """
    inputs = {"traceType": traceType, "traceWidth": traceWidth, "substrateHeight": substrateHeight, "dielectricConst": dielectricConst, "copperThickness": copperThickness, "coverHeight": coverHeight}
    return _client().calculate('controlled-impedance', inputs)


def pcb_crosstalk(traceWidth: float = 0.2, traceSpacing: float = 0.2, dielectricHeight: float = 0.1, frequency: float = 100.0, traceLength: float = 50.0) -> CalculatorResult:
    """
    PCB Crosstalk Calculator

    Category: pcb

    Estimate PCB trace crosstalk coupling coefficient, NEXT, FEXT, and critical coupling length for signal integrity analysis on PCB layouts

    Parameters
    ----------
    traceWidth : float
        Trace Width (mm) (default: 0.2)
    traceSpacing : float
        Trace Spacing (edge-to-edge) (mm) (default: 0.2)
    dielectricHeight : float
        Dielectric Height (mm) (default: 0.1)
    frequency : float
        Signal Frequency (MHz) (default: 100.0)
    traceLength : float
        Parallel Trace Length (mm) (default: 50.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'couplingCoeff', 'next_dB', 'fext_dB', 'criticalLength'
    """
    inputs = {"traceWidth": traceWidth, "traceSpacing": traceSpacing, "dielectricHeight": dielectricHeight, "frequency": frequency, "traceLength": traceLength}
    return _client().calculate('pcb-crosstalk', inputs)


def decoupling_capacitor(capacitance: float = 100.0, esr: float = 50.0, esl: float = 1.0, targetFreq: float = 100.0, supplyImpedance: float = 10.0) -> CalculatorResult:
    """
    Decoupling Capacitor Selection Calculator

    Category: pcb

    Calculate decoupling capacitor self-resonant frequency, impedance at target frequency, effective bypass range, and number of capacitors needed for power integrity

    Parameters
    ----------
    capacitance : float
        Capacitance (nF) (default: 100.0)
    esr : float
        ESR (mΩ) (default: 50.0)
    esl : float
        ESL (nH) (default: 1.0)
    targetFreq : float
        Target Frequency (MHz) (default: 100.0)
    supplyImpedance : float
        Target Supply Impedance (mΩ) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'selfResonantFreq', 'impedanceAtSrf', 'impedanceAtTarget', 'effectiveRange', 'numCapacitors'
    """
    inputs = {"capacitance": capacitance, "esr": esr, "esl": esl, "targetFreq": targetFreq, "supplyImpedance": supplyImpedance}
    return _client().calculate('decoupling-capacitor', inputs)


def pcb_trace_inductance(traceLength: float = 10.0, traceWidth: float = 0.2, thickness: float = 35.0) -> CalculatorResult:
    """
    PCB Trace Inductance Calculator

    Category: pcb

    Calculate PCB trace parasitic inductance using the Ruehli formula, including inductance per unit length and inductive impedance at key frequencies

    Parameters
    ----------
    traceLength : float
        Trace Length (mm) (default: 10.0)
    traceWidth : float
        Trace Width (mm) (default: 0.2)
    thickness : float
        Copper Thickness (μm) (default: 35.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'inductance', 'inductancePerLength', 'impedanceAt100MHz', 'impedanceAt1GHz'
    """
    inputs = {"traceLength": traceLength, "traceWidth": traceWidth, "thickness": thickness}
    return _client().calculate('pcb-trace-inductance', inputs)


def via_thermal_resistance(viaDiameter: float = 0.3, platingThickness: float = 25.0, boardThickness: float = 1.6, numVias: float = 4.0, viaFill: float = 0.0) -> CalculatorResult:
    """
    Via Thermal Resistance Calculator

    Category: pcb

    Calculate PCB via thermal resistance, array thermal resistance, thermal conductance, and current-carrying capacity for thermal via design

    Parameters
    ----------
    viaDiameter : float
        Via Diameter (mm) (default: 0.3)
    platingThickness : float
        Plating Thickness (μm) (default: 25.0)
    boardThickness : float
        Board Thickness (mm) (default: 1.6)
    numVias : float
        Number of Vias (default: 4.0)
    viaFill : float
        Via Fill (default: 0.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'viaResistance', 'arrayResistance', 'thermalConductance', 'currentCapacity'
    """
    inputs = {"viaDiameter": viaDiameter, "platingThickness": platingThickness, "boardThickness": boardThickness, "numVias": numVias, "viaFill": viaFill}
    return _client().calculate('via-thermal-resistance', inputs)


def power_plane_impedance(length: float = 100.0, width: float = 80.0, dielectric: float = 0.1, er: float = 4.4, frequency: float = 100.0) -> CalculatorResult:
    """
    PCB Power Plane Impedance Calculator

    Category: pcb

    Calculate PCB power plane spreading impedance, plane capacitance, inductance, and self-resonant frequency for PDN (power delivery network) design.

    Parameters
    ----------
    length : float
        Plane Length (mm) (default: 100.0)
    width : float
        Plane Width (mm) (default: 80.0)
    dielectric : float
        Dielectric Thickness (mm) (default: 0.1)
    er : float
        Dielectric Constant (default: 4.4)
    frequency : float
        Frequency (MHz) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'capacitance', 'impedance', 'resonantFrequency', 'inductance'
    """
    inputs = {"length": length, "width": width, "dielectric": dielectric, "er": er, "frequency": frequency}
    return _client().calculate('power-plane-impedance', inputs)


def via_stub_resonance(pcbThickness: float = 1.6, layer: float = 4.0, totalLayers: float = 8.0, er: float = 4.3) -> CalculatorResult:
    """
    PCB Via Stub Resonance Calculator

    Category: pcb

    Calculate PCB via stub length, stub resonant frequency that causes signal notch, and frequency improvement from back-drilling.

    Parameters
    ----------
    pcbThickness : float
        PCB Thickness (mm) (default: 1.6)
    layer : float
        Signal Exit Layer (default: 4.0)
    totalLayers : float
        Total PCB Layers (default: 8.0)
    er : float
        Dielectric Constant (default: 4.3)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'stubLength', 'resonantFreq', 'notchDepth', 'backdrillBenefit'
    """
    inputs = {"pcbThickness": pcbThickness, "layer": layer, "totalLayers": totalLayers, "er": er}
    return _client().calculate('via-stub-resonance', inputs)


def solder_paste_volume(padLength: float = 1.5, padWidth: float = 0.8, stencilThickness: float = 0.12, apertureReduction: float = 10.0) -> CalculatorResult:
    """
    Solder Paste Volume Calculator

    Category: pcb

    Calculate SMD solder paste volume, stencil aperture area, and IPC-7525A area ratio for stencil printing and reflow soldering process.

    Parameters
    ----------
    padLength : float
        Pad Length (mm) (default: 1.5)
    padWidth : float
        Pad Width (mm) (default: 0.8)
    stencilThickness : float
        Stencil Thickness (mm) (default: 0.12)
    apertureReduction : float
        Aperture Reduction (%) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'apertureArea', 'pasteVolume', 'pasteVolumeMl', 'areaRatio'
    """
    inputs = {"padLength": padLength, "padWidth": padWidth, "stencilThickness": stencilThickness, "apertureReduction": apertureReduction}
    return _client().calculate('solder-paste-volume', inputs)

