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

Functions:
    voltage_divider(...) -> CalculatorResult
    led_resistor(...) -> CalculatorResult
    buck_converter(...) -> CalculatorResult
    ldo_thermal(...) -> CalculatorResult
    battery_life(...) -> CalculatorResult
    power_factor(...) -> CalculatorResult
    boost_converter(...) -> CalculatorResult
    three_phase_power(...) -> CalculatorResult
    pwm_duty_cycle(...) -> CalculatorResult
    mosfet_power_dissipation(...) -> CalculatorResult
    solar_panel_sizing(...) -> CalculatorResult
    battery_charge_time(...) -> CalculatorResult
    inrush_current_limiter(...) -> CalculatorResult
    charge_pump_voltage(...) -> CalculatorResult
    switching_regulator_ripple(...) -> CalculatorResult
    linear_regulator_dropout(...) -> CalculatorResult
    transformer_turns_ratio(...) -> CalculatorResult
    flyback_converter(...) -> CalculatorResult
    supercapacitor_backup(...) -> CalculatorResult
    battery_internal_resistance(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


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


def voltage_divider(vin: float = 5.0, r1: float = 10000.0, r2: float = 10000.0) -> CalculatorResult:
    """
    Voltage Divider Calculator

    Category: power

    Calculate voltage divider output voltage, current, Thévenin impedance, and power dissipation from Vin, R1, and R2. Ideal for bias networks and level shifting.

    Parameters
    ----------
    vin : float
        Input Voltage (V) (default: 5.0)
    r1 : float
        R1 (top) (Ω) (default: 10000.0)
    r2 : float
        R2 (bottom) (Ω) (default: 10000.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'vout', 'ratio', 'current', 'rThev', 'powerR1', 'powerR2'
    """
    inputs = {"vin": vin, "r1": r1, "r2": r2}
    return _client().calculate('voltage-divider', inputs)


def led_resistor(vSupply: float = 5.0, vForward: float = 2.0, iForward: float = 20.0) -> CalculatorResult:
    """
    LED Current Limiting Resistor Calculator

    Category: power

    Calculate the correct current limiting resistor for an LED. Shows exact value, nearest E24 standard, actual current, and power dissipation.

    Parameters
    ----------
    vSupply : float
        Supply Voltage (V) (default: 5.0)
    vForward : float
        LED Forward Voltage (V) (default: 2.0)
    iForward : float
        Desired Current (mA) (default: 20.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'rExact', 'rNearest', 'iActual', 'power', 'pNearest'
    """
    inputs = {"vSupply": vSupply, "vForward": vForward, "iForward": iForward}
    return _client().calculate('led-resistor', inputs)


def buck_converter(vin: float = 12.0, vout: float = 5.0, iout: float = 1.0, fsw: float = 500.0, deltaIL: float = 30.0, deltaVout: float = 1.0) -> CalculatorResult:
    """
    Buck Converter Design Calculator

    Category: power

    Design a synchronous buck (step-down) converter: calculate duty cycle, inductor value, output capacitor, input capacitor, and theoretical efficiency.

    Parameters
    ----------
    vin : float
        Input Voltage (V) (default: 12.0)
    vout : float
        Output Voltage (V) (default: 5.0)
    iout : float
        Output Current (A) (default: 1.0)
    fsw : float
        Switching Frequency (kHz) (default: 500.0)
    deltaIL : float
        Inductor Current Ripple (%) (default: 30.0)
    deltaVout : float
        Output Voltage Ripple (%) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'dutyCycle', 'inductorUH', 'coutUF', 'cinUF', 'ilPeak', 'efficiency'
    """
    inputs = {"vin": vin, "vout": vout, "iout": iout, "fsw": fsw, "deltaIL": deltaIL, "deltaVout": deltaVout}
    return _client().calculate('buck-converter', inputs)


def ldo_thermal(vin: float = 5.0, vout: float = 3.3, iload: float = 500.0, thetaJA: float = 50.0, tamb: float = 25.0, tjMax: float = 125.0) -> CalculatorResult:
    """
    LDO Thermal Calculator

    Category: power

    Calculate LDO regulator power dissipation, junction temperature, thermal margin, and minimum dropout voltage for thermal design validation.

    Parameters
    ----------
    vin : float
        Input Voltage (V) (default: 5.0)
    vout : float
        Output Voltage (V) (default: 3.3)
    iload : float
        Load Current (mA) (default: 500.0)
    thetaJA : float
        Thermal Resistance θJA (°C/W) (default: 50.0)
    tamb : float
        Ambient Temperature (°C) (default: 25.0)
    tjMax : float
        Max Junction Temperature (°C) (default: 125.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'pdiss', 'tj', 'margin', 'dropoutV', 'efficiencyPct'
    """
    inputs = {"vin": vin, "vout": vout, "iload": iload, "thetaJA": thetaJA, "tamb": tamb, "tjMax": tjMax}
    return _client().calculate('ldo-thermal', inputs)


def battery_life(capacity: float = 2000.0, avgCurrent: float = 100.0, dutyCycle: float = 100.0, selfDischarge: float = 2.0, cutoffSoc: float = 20.0) -> CalculatorResult:
    """
    Battery Life Calculator

    Category: power

    Estimate battery runtime for IoT and portable devices given average current draw, duty cycle, self-discharge rate, and depth-of-discharge cutoff. Suitable for LiPo, alkaline, NiMH, and coin-cell batteries.

    Parameters
    ----------
    capacity : float
        Battery Capacity (mAh) (default: 2000.0)
    avgCurrent : float
        Average Current Draw (mA) (default: 100.0)
    dutyCycle : float
        Duty Cycle (%) (default: 100.0)
    selfDischarge : float
        Self-Discharge Rate (%/month) (default: 2.0)
    cutoffSoc : float
        Cutoff State of Charge (%) (default: 20.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'runtimeHours', 'runtimeDays', 'effectiveCurrent', 'usableCapacityMAh'
    """
    inputs = {"capacity": capacity, "avgCurrent": avgCurrent, "dutyCycle": dutyCycle, "selfDischarge": selfDischarge, "cutoffSoc": cutoffSoc}
    return _client().calculate('battery-life', inputs)


def power_factor(apparentPower: float = 1000.0, powerFactor: float = 0.8, voltage: float = 230.0, frequency: float = 50.0, targetPF: float = 0.95) -> CalculatorResult:
    """
    Power Factor Calculator

    Category: power

    Calculate power factor, reactive power, and correction capacitor for AC circuits

    Parameters
    ----------
    apparentPower : float
        Apparent Power (VA) (default: 1000.0)
    powerFactor : float
        Power Factor (default: 0.8)
    voltage : float
        Supply Voltage (V) (default: 230.0)
    frequency : float
        Frequency (Hz) (default: 50.0)
    targetPF : float
        Target Power Factor (default: 0.95)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'realPower', 'reactivePower', 'pfAngle', 'correctionCapacitor'
    """
    inputs = {"apparentPower": apparentPower, "powerFactor": powerFactor, "voltage": voltage, "frequency": frequency, "targetPF": targetPF}
    return _client().calculate('power-factor', inputs)


def boost_converter(inputVoltage: float = 5.0, outputVoltage: float = 12.0, outputCurrent: float = 0.5, switchFreq: float = 100.0, ripplePct: float = 30.0, efficiency: float = 88.0) -> CalculatorResult:
    """
    Boost Converter Design Calculator

    Category: power

    Calculate duty cycle, inductor value, and output capacitor for boost (step-up) DC-DC converter design

    Parameters
    ----------
    inputVoltage : float
        Input Voltage (V) (default: 5.0)
    outputVoltage : float
        Output Voltage (V) (default: 12.0)
    outputCurrent : float
        Output Current (A) (default: 0.5)
    switchFreq : float
        Switching Frequency (kHz) (default: 100.0)
    ripplePct : float
        Inductor Current Ripple (%) (default: 30.0)
    efficiency : float
        Estimated Efficiency (%) (default: 88.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'dutyCycle', 'inductorCurrent', 'inductorValue', 'outputCapacitor', 'peakCurrent'
    """
    inputs = {"inputVoltage": inputVoltage, "outputVoltage": outputVoltage, "outputCurrent": outputCurrent, "switchFreq": switchFreq, "ripplePct": ripplePct, "efficiency": efficiency}
    return _client().calculate('boost-converter', inputs)


def three_phase_power(connectionType: float = 0.0, lineVoltage: float = 400.0, current: float = 10.0, powerFactor: float = 0.85) -> CalculatorResult:
    """
    Three-Phase Power Calculator

    Category: power

    Calculate three-phase real power, reactive power, apparent power, current, and power factor from line or phase values

    Parameters
    ----------
    connectionType : float
        Connection Type (default: 0.0)
    lineVoltage : float
        Line Voltage (V) (default: 400.0)
    current : float
        Line Current (A) (default: 10.0)
    powerFactor : float
        Power Factor (default: 0.85)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'phaseVoltage', 'realPower', 'reactivePower', 'apparentPower', 'pfAngle'
    """
    inputs = {"connectionType": connectionType, "lineVoltage": lineVoltage, "current": current, "powerFactor": powerFactor}
    return _client().calculate('three-phase-power', inputs)


def pwm_duty_cycle(onTime: float = 5.0, period: float = 10.0, supplyVoltage: float = 3.3) -> CalculatorResult:
    """
    PWM Duty Cycle Calculator

    Category: power

    Calculate PWM duty cycle, frequency, average voltage, off-time, and RMS voltage from on-time and period parameters

    Parameters
    ----------
    onTime : float
        On Time (μs) (default: 5.0)
    period : float
        Period (μs) (default: 10.0)
    supplyVoltage : float
        Supply Voltage (V) (default: 3.3)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'dutyCycle', 'frequency', 'avgVoltage', 'offTime', 'rmsVoltage'
    """
    inputs = {"onTime": onTime, "period": period, "supplyVoltage": supplyVoltage}
    return _client().calculate('pwm-duty-cycle', inputs)


def mosfet_power_dissipation(drainCurrent: float = 5.0, rdson: float = 10.0, vds: float = 12.0, frequency: float = 100.0, riseTime: float = 20.0, fallTime: float = 20.0, rthJA: float = 40.0, tAmbient: float = 25.0) -> CalculatorResult:
    """
    MOSFET Power Dissipation Calculator

    Category: power

    Calculate MOSFET conduction loss, switching loss, total power dissipation, junction temperature, and efficiency for power electronics design

    Parameters
    ----------
    drainCurrent : float
        Drain Current (A) (default: 5.0)
    rdson : float
        On-Resistance (mΩ) (default: 10.0)
    vds : float
        Drain-Source Voltage (V) (default: 12.0)
    frequency : float
        Switching Frequency (kHz) (default: 100.0)
    riseTime : float
        Rise Time (ns) (default: 20.0)
    fallTime : float
        Fall Time (ns) (default: 20.0)
    rthJA : float
        Thermal Resistance (Rth J-A) (°C/W) (default: 40.0)
    tAmbient : float
        Ambient Temperature (°C) (default: 25.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'conductionLoss', 'switchingLoss', 'totalLoss', 'junctionTemp', 'efficiency'
    """
    inputs = {"drainCurrent": drainCurrent, "rdson": rdson, "vds": vds, "frequency": frequency, "riseTime": riseTime, "fallTime": fallTime, "rthJA": rthJA, "tAmbient": tAmbient}
    return _client().calculate('mosfet-power-dissipation', inputs)


def solar_panel_sizing(loadPower: float = 100.0, peakSunHours: float = 5.0, systemVoltage: float = 12.0, batteryCapacity: float = 100.0, daysAutonomy: float = 3.0) -> CalculatorResult:
    """
    Solar Panel Sizing Calculator

    Category: power

    Calculate solar panel wattage, battery capacity, and charge controller current for off-grid photovoltaic systems based on load and sun hours

    Parameters
    ----------
    loadPower : float
        Load Power (W) (default: 100.0)
    peakSunHours : float
        Peak Sun Hours (hr) (default: 5.0)
    systemVoltage : float
        System Voltage (V) (default: 12.0)
    batteryCapacity : float
        Battery Capacity (reference) (Ah) (default: 100.0)
    daysAutonomy : float
        Days of Autonomy (default: 3.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'energyPerDay', 'panelWattage', 'panelCurrent', 'batteryAh', 'chargeControllerAmps'
    """
    inputs = {"loadPower": loadPower, "peakSunHours": peakSunHours, "systemVoltage": systemVoltage, "batteryCapacity": batteryCapacity, "daysAutonomy": daysAutonomy}
    return _client().calculate('solar-panel-sizing', inputs)


def battery_charge_time(capacity: float = 3000.0, chargeCurrentC: float = 1.0, initialSoc: float = 20.0, targetSoc: float = 80.0, chargingVoltage: float = 4.2, battVoltage: float = 3.7) -> CalculatorResult:
    """
    Battery Charge Time Calculator

    Category: power

    Calculate Li-ion battery charge time using CC/CV method, including CC phase duration, total charge time, energy input, and charging efficiency

    Parameters
    ----------
    capacity : float
        Battery Capacity (mAh) (default: 3000.0)
    chargeCurrentC : float
        Charge Rate (C-rate) (C) (default: 1.0)
    initialSoc : float
        Initial State of Charge (%) (default: 20.0)
    targetSoc : float
        Target State of Charge (%) (default: 80.0)
    chargingVoltage : float
        Charging Voltage (V) (default: 4.2)
    battVoltage : float
        Nominal Battery Voltage (V) (default: 3.7)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'chargeCurrent', 'ccTime', 'chargeTime', 'energyIn', 'chargingEfficiency'
    """
    inputs = {"capacity": capacity, "chargeCurrentC": chargeCurrentC, "initialSoc": initialSoc, "targetSoc": targetSoc, "chargingVoltage": chargingVoltage, "battVoltage": battVoltage}
    return _client().calculate('battery-charge-time', inputs)


def inrush_current_limiter(supplyVoltage: float = 12.0, filterCapacitance: float = 1000.0, targetInrush: float = 5.0, ntcResistanceHot: float = 0.5) -> CalculatorResult:
    """
    Inrush Current Limiter (NTC) Calculator

    Category: power

    Calculate NTC thermistor requirements for inrush current limiting, including cold resistance, peak inrush current, time constant, and energy absorbed

    Parameters
    ----------
    supplyVoltage : float
        Supply Voltage (V) (default: 12.0)
    filterCapacitance : float
        Filter Capacitance (μF) (default: 1000.0)
    targetInrush : float
        Target Inrush Current (A) (default: 5.0)
    ntcResistanceHot : float
        NTC Resistance (Hot) (Ω) (default: 0.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'ntcResistanceCold', 'peakInrush', 'timeConstant', 'energyAbsorbed', 'limitingResistor'
    """
    inputs = {"supplyVoltage": supplyVoltage, "filterCapacitance": filterCapacitance, "targetInrush": targetInrush, "ntcResistanceHot": ntcResistanceHot}
    return _client().calculate('inrush-current-limiter', inputs)


def charge_pump_voltage(inputVoltage: float = 3.3, stages: float = 2.0, pumpCurrent: float = 10.0, frequency: float = 100.0, capacitance: float = 1.0) -> CalculatorResult:
    """
    Charge Pump Voltage Multiplier Calculator

    Category: power

    Calculate Dickson charge pump output voltage, loaded voltage, output ripple, and efficiency for switched-capacitor voltage multiplier circuits

    Parameters
    ----------
    inputVoltage : float
        Input Voltage (V) (default: 3.3)
    stages : float
        Number of Stages (default: 2.0)
    pumpCurrent : float
        Output Current (mA) (default: 10.0)
    frequency : float
        Switching Frequency (kHz) (default: 100.0)
    capacitance : float
        Pump Capacitance (μF) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'openCircuitVoltage', 'loadedVoltage', 'outputRipple', 'efficiency'
    """
    inputs = {"inputVoltage": inputVoltage, "stages": stages, "pumpCurrent": pumpCurrent, "frequency": frequency, "capacitance": capacitance}
    return _client().calculate('charge-pump-voltage', inputs)


def switching_regulator_ripple(inputVoltage: float = 12.0, outputVoltage: float = 5.0, frequency: float = 500.0, inductance: float = 10.0, capacitance: float = 100.0, esr: float = 20.0) -> CalculatorResult:
    """
    Switching Regulator Output Ripple Calculator

    Category: power

    Calculate buck converter output voltage ripple, inductor current ripple, and ESR contribution for switching regulator design

    Parameters
    ----------
    inputVoltage : float
        Input Voltage (V) (default: 12.0)
    outputVoltage : float
        Output Voltage (V) (default: 5.0)
    frequency : float
        Switching Frequency (kHz) (default: 500.0)
    inductance : float
        Inductance (μH) (default: 10.0)
    capacitance : float
        Output Capacitance (μF) (default: 100.0)
    esr : float
        Capacitor ESR (mΩ) (default: 20.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'dutyCycle', 'inductorRippleCurrent', 'capacitorRipple', 'inductorRipple', 'peakToPeakRipple'
    """
    inputs = {"inputVoltage": inputVoltage, "outputVoltage": outputVoltage, "frequency": frequency, "inductance": inductance, "capacitance": capacitance, "esr": esr}
    return _client().calculate('switching-regulator-ripple', inputs)


def linear_regulator_dropout(inputVoltage: float = 5.0, outputVoltage: float = 3.3, loadCurrent: float = 500.0, dropoutVoltage: float = 300.0, thetaJA: float = 50.0) -> CalculatorResult:
    """
    LDO Linear Regulator Dropout Calculator

    Category: power

    Calculate LDO regulator power dissipation, junction temperature rise, minimum input voltage, efficiency, and headroom for linear regulator design

    Parameters
    ----------
    inputVoltage : float
        Input Voltage (V) (default: 5.0)
    outputVoltage : float
        Output Voltage (V) (default: 3.3)
    loadCurrent : float
        Load Current (mA) (default: 500.0)
    dropoutVoltage : float
        Dropout Voltage (mV) (default: 300.0)
    thetaJA : float
        Thermal Resistance θJA (°C/W) (default: 50.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'powerDissipation', 'junctionTempRise', 'minInputVoltage', 'efficiency', 'headroom'
    """
    inputs = {"inputVoltage": inputVoltage, "outputVoltage": outputVoltage, "loadCurrent": loadCurrent, "dropoutVoltage": dropoutVoltage, "thetaJA": thetaJA}
    return _client().calculate('linear-regulator-dropout', inputs)


def transformer_turns_ratio(vPrimary: float = 120.0, vSecondary: float = 12.0, iPrimary: float = 0.1, efficiency: float = 95.0) -> CalculatorResult:
    """
    Transformer Turns Ratio Calculator

    Category: power

    Calculate transformer turns ratio, secondary current, apparent power, and real power delivered. Accounts for transformer efficiency.

    Parameters
    ----------
    vPrimary : float
        Primary Voltage (V) (default: 120.0)
    vSecondary : float
        Secondary Voltage (V) (default: 12.0)
    iPrimary : float
        Primary Current (A) (default: 0.1)
    efficiency : float
        Transformer Efficiency (%) (default: 95.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'turnsRatio', 'iSecondary', 'apparentPower', 'realPower', 'couplingFactor'
    """
    inputs = {"vPrimary": vPrimary, "vSecondary": vSecondary, "iPrimary": iPrimary, "efficiency": efficiency}
    return _client().calculate('transformer-turns-ratio', inputs)


def flyback_converter(vin: float = 48.0, vout: float = 12.0, iout: float = 1.0, efficiency: float = 85.0, fsw: float = 100.0, dutyCycle: float = 40.0) -> CalculatorResult:
    """
    Flyback Converter Calculator

    Category: power

    Calculate flyback converter turns ratio, peak primary and secondary currents, and power levels for isolated DC-DC converter design.

    Parameters
    ----------
    vin : float
        Input Voltage (V) (default: 48.0)
    vout : float
        Output Voltage (V) (default: 12.0)
    iout : float
        Output Current (A) (default: 1.0)
    efficiency : float
        Efficiency (%) (default: 85.0)
    fsw : float
        Switching Frequency (kHz) (default: 100.0)
    dutyCycle : float
        Duty Cycle (%) (default: 40.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'turnsRatio', 'iinAvg', 'ipPeak', 'isecPeak', 'outputPower'
    """
    inputs = {"vin": vin, "vout": vout, "iout": iout, "efficiency": efficiency, "fsw": fsw, "dutyCycle": dutyCycle}
    return _client().calculate('flyback-converter', inputs)


def supercapacitor_backup(capacitance: float = 10.0, vMax: float = 5.5, vMin: float = 3.0, iLoad: float = 100.0) -> CalculatorResult:
    """
    Supercapacitor Backup Time Calculator

    Category: power

    Calculate supercapacitor backup time, stored energy, and charge time for power backup applications using ultracapacitors.

    Parameters
    ----------
    capacitance : float
        Capacitance (F) (default: 10.0)
    vMax : float
        Maximum Voltage (V) (default: 5.5)
    vMin : float
        Minimum Operating Voltage (V) (default: 3.0)
    iLoad : float
        Load Current (mA) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'energy', 'backupTime', 'backupTimeMin', 'chargeTime', 'selfDischarge'
    """
    inputs = {"capacitance": capacitance, "vMax": vMax, "vMin": vMin, "iLoad": iLoad}
    return _client().calculate('supercapacitor-backup', inputs)


def battery_internal_resistance(vocv: float = 12.6, vLoad: float = 11.8, iLoad: float = 4.0, temperature: float = 25.0) -> CalculatorResult:
    """
    Battery Internal Resistance Calculator

    Category: power

    Calculate battery internal resistance from open-circuit and loaded voltage measurements, determine power loss and maximum short-circuit current.

    Parameters
    ----------
    vocv : float
        Open Circuit Voltage (V) (default: 12.6)
    vLoad : float
        Loaded Voltage (V) (default: 11.8)
    iLoad : float
        Load Current (A) (default: 4.0)
    temperature : float
        Temperature (°C) (default: 25.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'rinternal', 'powerLoss', 'efficiency', 'maxCurrentShort'
    """
    inputs = {"vocv": vocv, "vLoad": vLoad, "iLoad": iLoad, "temperature": temperature}
    return _client().calculate('battery-internal-resistance', inputs)

