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

Functions:
    heatsink_calculator(...) -> CalculatorResult
    pcb_trace_temp(...) -> CalculatorResult
    thermal_resistance_network(...) -> CalculatorResult
    junction_temperature(...) -> CalculatorResult
    heatsink_selection(...) -> CalculatorResult
    thermal_via_array(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


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


def heatsink_calculator(powerDissipation: float = 5.0, maxJunctionTemp: float = 125.0, ambientTemp: float = 25.0, thetaJC: float = 2.0, thetaCS: float = 0.5) -> CalculatorResult:
    """
    Heatsink Calculator

    Category: thermal

    Calculate required heatsink thermal resistance and junction temperature for power devices

    Parameters
    ----------
    powerDissipation : float
        Power Dissipation (W) (default: 5.0)
    maxJunctionTemp : float
        Max Junction Temperature (°C) (default: 125.0)
    ambientTemp : float
        Ambient Temperature (°C) (default: 25.0)
    thetaJC : float
        Junction-to-Case Resistance (°C/W) (default: 2.0)
    thetaCS : float
        Case-to-Heatsink Resistance (°C/W) (default: 0.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'thetaSA_required', 'junctionTemp', 'thetaJA_total', 'tempRise'
    """
    inputs = {"powerDissipation": powerDissipation, "maxJunctionTemp": maxJunctionTemp, "ambientTemp": ambientTemp, "thetaJC": thetaJC, "thetaCS": thetaCS}
    return _client().calculate('heatsink-calculator', inputs)


def pcb_trace_temp(current: float = 3.0, traceWidth: float = 2.0, copperWeight: float = 1.0, ambientTemp: float = 25.0, traceLength: float = 100.0) -> CalculatorResult:
    """
    PCB Trace Temperature Rise

    Category: thermal

    Calculate PCB copper trace temperature rise under load current using IPC-2152

    Parameters
    ----------
    current : float
        Current (A) (default: 3.0)
    traceWidth : float
        Trace Width (mm) (default: 2.0)
    copperWeight : float
        Copper Weight (oz) (default: 1.0)
    ambientTemp : float
        Ambient Temperature (°C) (default: 25.0)
    traceLength : float
        Trace Length (mm) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'tempRise', 'maxTemp', 'traceResistance', 'powerDissipated', 'currentCapacity'
    """
    inputs = {"current": current, "traceWidth": traceWidth, "copperWeight": copperWeight, "ambientTemp": ambientTemp, "traceLength": traceLength}
    return _client().calculate('pcb-trace-temp', inputs)


def thermal_resistance_network(powerDissipation: float = 5.0, thetaJC: float = 2.0, thetaCS: float = 0.5, thetaSA: float = 10.0, ambientTemp: float = 25.0) -> CalculatorResult:
    """
    Thermal Resistance Network Calculator

    Category: thermal

    Calculate junction, case, and heatsink temperatures through a series thermal resistance network (θJC + θCS + θSA) for component thermal management

    Parameters
    ----------
    powerDissipation : float
        Power Dissipation (W) (default: 5.0)
    thetaJC : float
        Junction-to-Case (θJC) (°C/W) (default: 2.0)
    thetaCS : float
        Case-to-Heatsink (θCS) (°C/W) (default: 0.5)
    thetaSA : float
        Heatsink-to-Ambient (θSA) (°C/W) (default: 10.0)
    ambientTemp : float
        Ambient Temperature (°C) (default: 25.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'junctionTemp', 'caseTemp', 'heatsinkTemp', 'totalThetaJA', 'thermalMargin'
    """
    inputs = {"powerDissipation": powerDissipation, "thetaJC": thetaJC, "thetaCS": thetaCS, "thetaSA": thetaSA, "ambientTemp": ambientTemp}
    return _client().calculate('thermal-resistance-network', inputs)


def junction_temperature(pd: float = 1.0, ta: float = 25.0, thetaJC: float = 5.0, thetaCS: float = 0.5, thetaSA: float = 10.0) -> CalculatorResult:
    """
    Junction Temperature Calculator

    Category: thermal

    Calculate semiconductor junction temperature from power dissipation and thermal resistance chain (θJC + θCS + θSA). Essential for transistor, MOSFET, and IC thermal design.

    Parameters
    ----------
    pd : float
        Power Dissipation (W) (default: 1.0)
    ta : float
        Ambient Temperature (°C) (default: 25.0)
    thetaJC : float
        θ_JC (Junction-to-Case) (°C/W) (default: 5.0)
    thetaCS : float
        θ_CS (Case-to-Heatsink) (°C/W) (default: 0.5)
    thetaSA : float
        θ_SA (Heatsink-to-Ambient) (°C/W) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'thetaJA', 'tj', 'tc', 'ts', 'margin'
    """
    inputs = {"pd": pd, "ta": ta, "thetaJC": thetaJC, "thetaCS": thetaCS, "thetaSA": thetaSA}
    return _client().calculate('junction-temperature', inputs)


def heatsink_selection(pd: float = 5.0, ta: float = 40.0, tjMax: float = 125.0, thetaJC: float = 3.0, thetaCS: float = 0.5) -> CalculatorResult:
    """
    Heatsink Selection Calculator

    Category: thermal

    Calculate the required heatsink thermal resistance (θSA) to keep a device junction below its maximum temperature. Use this to select an appropriate heatsink.

    Parameters
    ----------
    pd : float
        Power Dissipation (W) (default: 5.0)
    ta : float
        Ambient Temperature (°C) (default: 40.0)
    tjMax : float
        Max Junction Temperature (°C) (default: 125.0)
    thetaJC : float
        θ_JC (Junction-to-Case) (°C/W) (default: 3.0)
    thetaCS : float
        θ_CS (Case-to-Heatsink) (°C/W) (default: 0.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'thetaSARequired', 'tjActual', 'deltaTJ'
    """
    inputs = {"pd": pd, "ta": ta, "tjMax": tjMax, "thetaJC": thetaJC, "thetaCS": thetaCS}
    return _client().calculate('heatsink-selection', inputs)


def thermal_via_array(numVias: float = 9.0, viaDiameter: float = 0.3, platingThickness: float = 25.0, pcbThickness: float = 1.6, copperThermal: float = 385.0, drillFill: float = 0.0) -> CalculatorResult:
    """
    Thermal Via Array Calculator

    Category: thermal

    Calculate thermal resistance of a PCB thermal via array for heat spreading from SMD packages to inner copper planes or heatsinks.

    Parameters
    ----------
    numVias : float
        Number of Vias (vias) (default: 9.0)
    viaDiameter : float
        Via Drill Diameter (mm) (default: 0.3)
    platingThickness : float
        Copper Plating (μm) (default: 25.0)
    pcbThickness : float
        PCB Thickness (mm) (default: 1.6)
    copperThermal : float
        Thermal Conductivity (W/m·K) (default: 385.0)
    drillFill : float
        Fill Fraction (default: 0.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'thetaPerVia', 'thetaArray', 'effectiveConductance'
    """
    inputs = {"numVias": numVias, "viaDiameter": viaDiameter, "platingThickness": platingThickness, "pcbThickness": pcbThickness, "copperThermal": copperThermal, "drillFill": drillFill}
    return _client().calculate('thermal-via-array', inputs)

