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

Functions:
    ohms_law(...) -> CalculatorResult
    resistor_color_code(...) -> CalculatorResult
    rc_time_constant(...) -> CalculatorResult
    series_parallel_resistor(...) -> CalculatorResult
    lc_resonance(...) -> CalculatorResult
    opamp_gain(...) -> CalculatorResult
    wire_gauge(...) -> CalculatorResult
    capacitor_energy(...) -> CalculatorResult
    zener_diode(...) -> CalculatorResult
    inductor_energy(...) -> CalculatorResult
    bjt_bias_point(...) -> CalculatorResult
    mosfet_operating_point(...) -> CalculatorResult
    comparator_hysteresis(...) -> CalculatorResult
    555_timer(...) -> CalculatorResult
    transistor_switch(...) -> CalculatorResult
    current_mirror(...) -> CalculatorResult
    schmitt_trigger(...) -> CalculatorResult
    crystal_load_capacitance(...) -> CalculatorResult
    opamp_bandwidth(...) -> CalculatorResult
    lm317_resistors(...) -> CalculatorResult
    voltage_regulator_dropout(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


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


def ohms_law(voltage: float = 5.0, current: float = -1.0, resistance: float = 1000.0, power: float = -1.0) -> CalculatorResult:
    """
    Ohm's Law Calculator

    Category: general

    Calculate voltage, current, resistance, and power using Ohm's Law. Enter any two values to solve for the remaining two quantities.

    Parameters
    ----------
    voltage : float
        Voltage (V) (default: 5.0)
    current : float
        Current (A) (default: -1.0)
    resistance : float
        Resistance (Ω) (default: 1000.0)
    power : float
        Power (W) (default: -1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'voltage', 'current', 'resistance', 'power'
    """
    inputs = {"voltage": voltage, "current": current, "resistance": resistance, "power": power}
    return _client().calculate('ohms-law', inputs)


def resistor_color_code(numBands: float = 4.0, band1: float = 1.0, band2: float = 0.0, band3: float = 4.0, multiplier: float = 2.0, tolerance: float = 10.0) -> CalculatorResult:
    """
    Resistor Color Code Calculator

    Category: general

    Decode resistor color bands to resistance value and tolerance. Supports 4-band, 5-band, and 6-band resistors. Instant color band to ohms conversion.

    Parameters
    ----------
    numBands : float
        Number of Bands (default: 4.0)
    band1 : float
        Band 1 (1st digit) (default: 1.0)
    band2 : float
        Band 2 (2nd digit) (default: 0.0)
    band3 : float
        Band 3 (3rd digit / multiplier for 4-band) (default: 4.0)
    multiplier : float
        Multiplier Band (default: 2.0)
    tolerance : float
        Tolerance Band (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'resistance', 'tolerance', 'minResistance', 'maxResistance'
    """
    inputs = {"numBands": numBands, "band1": band1, "band2": band2, "band3": band3, "multiplier": multiplier, "tolerance": tolerance}
    return _client().calculate('resistor-color-code', inputs)


def rc_time_constant(resistance: float = 10000.0, capacitance: float = 100.0) -> CalculatorResult:
    """
    RC Time Constant Calculator

    Category: general

    Calculate RC circuit time constant τ, charge time to 63.2% and 99%, and −3dB cutoff frequency. Essential for filter and timing circuit design.

    Parameters
    ----------
    resistance : float
        Resistance (Ω) (default: 10000.0)
    capacitance : float
        Capacitance (nF) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'tauUs', 't63us', 't99us', 'f3db'
    """
    inputs = {"resistance": resistance, "capacitance": capacitance}
    return _client().calculate('rc-time-constant', inputs)


def series_parallel_resistor(r1: float = 1000.0, r2: float = 1000.0, r3: float = 0.0, r4: float = 0.0, componentType: float = 0.0) -> CalculatorResult:
    """
    Series / Parallel Resistor, Capacitor & Inductor Calculator

    Category: general

    Calculate the equivalent series and parallel combination of up to four resistors, capacitors, or inductors. Also computes the voltage divider ratio for two-resistor networks.

    Parameters
    ----------
    r1 : float
        R1 (or C1 in nF / L1 in μH) (Ω) (default: 1000.0)
    r2 : float
        R2 (or C2 in nF / L2 in μH) (Ω) (default: 1000.0)
    r3 : float
        R3 (optional) (Ω) (default: 0.0)
    r4 : float
        R4 (optional) (Ω) (default: 0.0)
    componentType : float
        Component Type (default: 0.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'seriesTotal', 'parallelTotal', 'voltDividerRatio'
    """
    inputs = {"r1": r1, "r2": r2, "r3": r3, "r4": r4, "componentType": componentType}
    return _client().calculate('series-parallel-resistor', inputs)


def lc_resonance(inductance: float = 10.0, capacitance: float = 100.0, resistance: float = 0.0, circuitType: float = 0.0) -> CalculatorResult:
    """
    LC Resonance Calculator

    Category: general

    Calculate the resonant frequency, characteristic impedance, Q factor, and bandwidth of a series or parallel LC tank circuit. Enter inductance, capacitance, and optional series resistance.

    Parameters
    ----------
    inductance : float
        Inductance (μH) (default: 10.0)
    capacitance : float
        Capacitance (pF) (default: 100.0)
    resistance : float
        Series Resistance (Ω) (default: 0.0)
    circuitType : float
        Circuit Type (default: 0.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'f0_MHz', 'characteristicImpedance_ohm', 'qFactor', 'bandwidth_kHz', 'wavelength_m'
    """
    inputs = {"inductance": inductance, "capacitance": capacitance, "resistance": resistance, "circuitType": circuitType}
    return _client().calculate('lc-resonance', inputs)


def opamp_gain(configuration: float = 1.0, r1: float = 10.0, r2: float = 1.0, gbwProduct: float = 1.0, supplyVoltage: float = 15.0) -> CalculatorResult:
    """
    Op-Amp Gain & Bandwidth Calculator

    Category: general

    Calculate op-amp voltage gain, gain in dB, −3 dB bandwidth, and input impedance for inverting, non-inverting, and differential amplifier configurations.

    Parameters
    ----------
    configuration : float
        Amplifier Configuration (default: 1.0)
    r1 : float
        R1 (feedback resistor Rf) (kΩ) (default: 10.0)
    r2 : float
        R2 (input resistor Rin) (kΩ) (default: 1.0)
    gbwProduct : float
        Gain-Bandwidth Product (MHz) (default: 1.0)
    supplyVoltage : float
        Supply Voltage (total) (V) (default: 15.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'gain', 'gainDb', 'f3db_kHz', 'inputImpedance_kohm', 'maxOutputVpp'
    """
    inputs = {"configuration": configuration, "r1": r1, "r2": r2, "gbwProduct": gbwProduct, "supplyVoltage": supplyVoltage}
    return _client().calculate('opamp-gain', inputs)


def wire_gauge(awg: float = 22.0, current: float = 1.0, length: float = 1.0, resistivity: float = 0.01724) -> CalculatorResult:
    """
    Wire Gauge Calculator (AWG)

    Category: general

    Convert between AWG and mm², calculate wire current capacity, resistance, and voltage drop

    Parameters
    ----------
    awg : float
        Wire Gauge (AWG) (default: 22.0)
    current : float
        Current (A) (default: 1.0)
    length : float
        Wire Length (m) (default: 1.0)
    resistivity : float
        Resistivity (Ω·mm²/m) (default: 0.01724)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'diameter', 'crossSection', 'resistance', 'voltageDrop', 'currentCapacity'
    """
    inputs = {"awg": awg, "current": current, "length": length, "resistivity": resistivity}
    return _client().calculate('wire-gauge', inputs)


def capacitor_energy(capacitance: float = 100.0, voltage: float = 12.0, chargeTime: float = 10.0) -> CalculatorResult:
    """
    Capacitor Energy & Charge Calculator

    Category: general

    Calculate energy stored, charge, and current in capacitors for power supply design

    Parameters
    ----------
    capacitance : float
        Capacitance (μF) (default: 100.0)
    voltage : float
        Voltage (V) (default: 12.0)
    chargeTime : float
        Charge Time (ms) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'energy', 'charge', 'avgChargeCurrent', 'chargePower'
    """
    inputs = {"capacitance": capacitance, "voltage": voltage, "chargeTime": chargeTime}
    return _client().calculate('capacitor-energy', inputs)


def zener_diode(inputVoltage: float = 12.0, zenerVoltage: float = 5.1, loadCurrent: float = 20.0, zenerCurrentMin: float = 5.0, zenerPowerMax: float = 500.0) -> CalculatorResult:
    """
    Zener Diode Voltage Regulator Calculator

    Category: general

    Calculate series resistor, power dissipation, and load current for zener diode voltage regulators

    Parameters
    ----------
    inputVoltage : float
        Input Voltage (V) (default: 12.0)
    zenerVoltage : float
        Zener Voltage (V) (default: 5.1)
    loadCurrent : float
        Load Current (mA) (default: 20.0)
    zenerCurrentMin : float
        Minimum Zener Current (mA) (default: 5.0)
    zenerPowerMax : float
        Max Zener Power Rating (mW) (default: 500.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'seriesResistor', 'zenerCurrent', 'zenerPower', 'totalCurrent', 'e24Resistor'
    """
    inputs = {"inputVoltage": inputVoltage, "zenerVoltage": zenerVoltage, "loadCurrent": loadCurrent, "zenerCurrentMin": zenerCurrentMin, "zenerPowerMax": zenerPowerMax}
    return _client().calculate('zener-diode', inputs)


def inductor_energy(inductance: float = 100.0, current: float = 1.0, resistance: float = 10.0, targetCurrent: float = 63.2) -> CalculatorResult:
    """
    Inductor Energy & Time Constant Calculator

    Category: general

    Calculate energy stored in an inductor, L/R time constant, and current rise time

    Parameters
    ----------
    inductance : float
        Inductance (μH) (default: 100.0)
    current : float
        Current (A) (default: 1.0)
    resistance : float
        Series Resistance (Ω) (default: 10.0)
    targetCurrent : float
        Target Current (%) (default: 63.2)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'energy', 'timeConst', 'riseTime', 'peakVoltage', 'saturationCheck'
    """
    inputs = {"inductance": inductance, "current": current, "resistance": resistance, "targetCurrent": targetCurrent}
    return _client().calculate('inductor-energy', inputs)


def bjt_bias_point(vcc: float = 12.0, r1: float = 10.0, r2: float = 4.7, rc: float = 2.2, re: float = 470.0, beta: float = 100.0, vbe: float = 0.7) -> CalculatorResult:
    """
    BJT Transistor Bias Point Calculator

    Category: general

    Calculate BJT voltage divider bias Q-point including collector current, base voltage, VCE, power dissipation, and operating region

    Parameters
    ----------
    vcc : float
        Supply Voltage (VCC) (V) (default: 12.0)
    r1 : float
        R1 (upper bias resistor) (kΩ) (default: 10.0)
    r2 : float
        R2 (lower bias resistor) (kΩ) (default: 4.7)
    rc : float
        Collector Resistor (kΩ) (default: 2.2)
    re : float
        Emitter Resistor (Ω) (default: 470.0)
    beta : float
        Current Gain (β / hFE) (default: 100.0)
    vbe : float
        Base-Emitter Voltage (V) (default: 0.7)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'vb', 've', 'vc', 'ic', 'ib', 'vce', 'powerDissipation', 'operatingRegion'
    """
    inputs = {"vcc": vcc, "r1": r1, "r2": r2, "rc": rc, "re": re, "beta": beta, "vbe": vbe}
    return _client().calculate('bjt-bias-point', inputs)


def mosfet_operating_point(vgs: float = 5.0, vth: float = 2.0, kn: float = 100.0, vds: float = 10.0, vdd: float = 12.0, rdLoad: float = 1.0) -> CalculatorResult:
    """
    MOSFET Operating Point Calculator

    Category: general

    Calculate MOSFET drain current, saturation voltage, transconductance, and operating region (cutoff, triode, saturation) for NMOS transistors

    Parameters
    ----------
    vgs : float
        Gate-Source Voltage (V) (default: 5.0)
    vth : float
        Threshold Voltage (V) (default: 2.0)
    kn : float
        Process Transconductance (kn) (mA/V²) (default: 100.0)
    vds : float
        Drain-Source Voltage (V) (default: 10.0)
    vdd : float
        Supply Voltage (V) (default: 12.0)
    rdLoad : float
        Drain Load Resistance (kΩ) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'id', 'vdsSat', 'powerDissipation', 'gm', 'region'
    """
    inputs = {"vgs": vgs, "vth": vth, "kn": kn, "vds": vds, "vdd": vdd, "rdLoad": rdLoad}
    return _client().calculate('mosfet-operating-point', inputs)


def comparator_hysteresis(vref: float = 2.5, supplyVoltage: float = 5.0, r1: float = 10.0, r2: float = 100.0, hystPercent: float = 5.0) -> CalculatorResult:
    """
    Comparator Hysteresis (Schmitt Trigger) Calculator

    Category: general

    Calculate comparator hysteresis trip points for Schmitt trigger circuits, upper and lower threshold voltages, and design resistor values for a desired hysteresis percentage

    Parameters
    ----------
    vref : float
        Reference Voltage (V) (default: 2.5)
    supplyVoltage : float
        Supply Voltage (V) (default: 5.0)
    r1 : float
        R1 (feedback resistor) (kΩ) (default: 10.0)
    r2 : float
        R2 (input resistor) (kΩ) (default: 100.0)
    hystPercent : float
        Desired Hysteresis (%) (default: 5.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'vTrip_high', 'vTrip_low', 'hysteresis', 'r1Calc', 'r2Calc'
    """
    inputs = {"vref": vref, "supplyVoltage": supplyVoltage, "r1": r1, "r2": r2, "hystPercent": hystPercent}
    return _client().calculate('comparator-hysteresis', inputs)


def 555_timer(mode: float = 0.0, ra: float = 10.0, rb: float = 10.0, c: float = 0.1, vcc: float = 5.0) -> CalculatorResult:
    """
    555 Timer Calculator (Astable & Monostable)

    Category: general

    Calculate 555 timer frequency, period, duty cycle, and pulse width for both astable oscillator and monostable one-shot configurations

    Parameters
    ----------
    mode : float
        Timer Mode (default: 0.0)
    ra : float
        Resistor RA (kΩ) (default: 10.0)
    rb : float
        Resistor RB (kΩ) (default: 10.0)
    c : float
        Timing Capacitor (μF) (default: 0.1)
    vcc : float
        Supply Voltage (V) (default: 5.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'frequency', 'period', 'pulseWidth', 'dutyCycle', 'highTime', 'lowTime'
    """
    inputs = {"mode": mode, "ra": ra, "rb": rb, "c": c, "vcc": vcc}
    return _client().calculate('555-timer', inputs)


def transistor_switch(vcc: float = 5.0, loadResistor: float = 100.0, inputVoltage: float = 3.3, beta: float = 100.0, vbe: float = 0.7, vce_sat: float = 0.2, overdriveFactor: float = 5.0) -> CalculatorResult:
    """
    BJT Transistor Switch Calculator

    Category: general

    Calculate BJT transistor switch parameters including load current, required base current, base resistor value, saturation check, and power dissipation

    Parameters
    ----------
    vcc : float
        Supply Voltage (V) (default: 5.0)
    loadResistor : float
        Load Resistance (Ω) (default: 100.0)
    inputVoltage : float
        Input Drive Voltage (V) (default: 3.3)
    beta : float
        Current Gain (β) (default: 100.0)
    vbe : float
        Base-Emitter Voltage (V) (default: 0.7)
    vce_sat : float
        Saturation Voltage VCE(sat) (V) (default: 0.2)
    overdriveFactor : float
        Overdrive Factor (×) (default: 5.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'loadCurrent', 'ib_required', 'rb', 'ib_actual', 'powerDissipation', 'switchingState'
    """
    inputs = {"vcc": vcc, "loadResistor": loadResistor, "inputVoltage": inputVoltage, "beta": beta, "vbe": vbe, "vce_sat": vce_sat, "overdriveFactor": overdriveFactor}
    return _client().calculate('transistor-switch', inputs)


def current_mirror(refCurrent: float = 1.0, ratio: float = 2.0, vcc: float = 5.0, beta: float = 100.0, vt: float = 26.0) -> CalculatorResult:
    """
    Current Mirror Calculator

    Category: general

    Calculate current mirror output current, beta error, reference resistor, power consumption, and Widlar mirror resistor for analog IC and bias circuit design

    Parameters
    ----------
    refCurrent : float
        Reference Current (mA) (default: 1.0)
    ratio : float
        Mirror Ratio (Iout/Iref) (×) (default: 2.0)
    vcc : float
        Supply Voltage (V) (default: 5.0)
    beta : float
        Transistor β (hFE) (default: 100.0)
    vt : float
        Thermal Voltage (mV) (default: 26.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'outputCurrent', 'refResistor', 'powerRef', 'error', 'widlarResistor'
    """
    inputs = {"refCurrent": refCurrent, "ratio": ratio, "vcc": vcc, "beta": beta, "vt": vt}
    return _client().calculate('current-mirror', inputs)


def schmitt_trigger(vcc: float = 5.0, r1: float = 10.0, r2: float = 10.0, r3: float = 100.0) -> CalculatorResult:
    """
    Schmitt Trigger Calculator

    Category: general

    Calculate non-inverting Schmitt trigger threshold voltages and hysteresis band for comparator circuits with positive feedback.

    Parameters
    ----------
    vcc : float
        Supply Voltage (V) (default: 5.0)
    r1 : float
        R1 (Lower) (kΩ) (default: 10.0)
    r2 : float
        R2 (Upper) (kΩ) (default: 10.0)
    r3 : float
        R3 (Feedback) (kΩ) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'vth_high', 'vth_low', 'hysteresis', 'centerVoltage'
    """
    inputs = {"vcc": vcc, "r1": r1, "r2": r2, "r3": r3}
    return _client().calculate('schmitt-trigger', inputs)


def crystal_load_capacitance(cl: float = 18.0, cstray: float = 3.0, c1: float = 22.0, c2: float = 22.0) -> CalculatorResult:
    """
    Crystal Load Capacitance Calculator

    Category: general

    Calculate actual load capacitance seen by a crystal oscillator, estimate frequency error from spec, and find recommended external capacitor values.

    Parameters
    ----------
    cl : float
        Crystal Load Capacitance (spec) (pF) (default: 18.0)
    cstray : float
        Stray / Parasitic Capacitance (pF) (default: 3.0)
    c1 : float
        External Cap C1 (pF) (default: 22.0)
    c2 : float
        External Cap C2 (pF) (default: 22.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'clActual', 'clError', 'freqError', 'c_recommended'
    """
    inputs = {"cl": cl, "cstray": cstray, "c1": c1, "c2": c2}
    return _client().calculate('crystal-load-capacitance', inputs)


def opamp_bandwidth(gbw: float = 1.0, gain: float = 10.0, phase_margin: float = 45.0) -> CalculatorResult:
    """
    Op-Amp Closed-Loop Bandwidth Calculator

    Category: general

    Calculate op-amp closed-loop -3dB bandwidth from the gain-bandwidth product (GBW), determine rise time, and verify phase margin.

    Parameters
    ----------
    gbw : float
        Gain-Bandwidth Product (MHz) (default: 1.0)
    gain : float
        Closed-Loop Gain (V/V) (default: 10.0)
    phase_margin : float
        Phase Margin (°) (default: 45.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'bandwidth', 'riseTime', 'slewLimited', 'gainDb'
    """
    inputs = {"gbw": gbw, "gain": gain, "phase_margin": phase_margin}
    return _client().calculate('opamp-bandwidth', inputs)


def lm317_resistors(vout: float = 5.0, r1: float = 240.0, iadj: float = 50.0) -> CalculatorResult:
    """
    LM317 Resistor Calculator

    Category: general

    Calculate R2 resistor value for LM317/LM338 adjustable voltage regulator output voltage, with actual Vout and resistor power dissipation.

    Parameters
    ----------
    vout : float
        Desired Output Voltage (V) (default: 5.0)
    r1 : float
        R1 (Ω) (default: 240.0)
    iadj : float
        ADJ Pin Current (μA) (default: 50.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'r2', 'voutActual', 'powerR1', 'powerR2'
    """
    inputs = {"vout": vout, "r1": r1, "iadj": iadj}
    return _client().calculate('lm317-resistors', inputs)


def voltage_regulator_dropout(vout: float = 3.3, iload: float = 500.0, vdropout: float = 300.0, rds_on: float = 0.0, vin: float = 5.0) -> CalculatorResult:
    """
    LDO Dropout Voltage Calculator

    Category: general

    Calculate LDO minimum input voltage from dropout specification, determine power dissipation, and estimate efficiency at a given supply voltage.

    Parameters
    ----------
    vout : float
        Output Voltage (V) (default: 3.3)
    iload : float
        Load Current (mA) (default: 500.0)
    vdropout : float
        Dropout Voltage (mV) (default: 300.0)
    rds_on : float
        MOSFET Rds(on) (mΩ) (default: 0.0)
    vin : float
        Actual Supply Voltage (V) (default: 5.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'vinMin', 'vinRec', 'powerDiss', 'efficiency'
    """
    inputs = {"vout": vout, "iload": iload, "vdropout": vdropout, "rds_on": rds_on, "vin": vin}
    return _client().calculate('voltage-regulator-dropout', inputs)

