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

Functions:
    dc_motor_speed(...) -> CalculatorResult
    stepper_motor(...) -> CalculatorResult
    bldc_motor(...) -> CalculatorResult
    servo_motor(...) -> CalculatorResult
    gear_ratio(...) -> CalculatorResult
    pwm_duty_cycle_motor(...) -> CalculatorResult
    torque_unit_converter(...) -> CalculatorResult
    motor_efficiency(...) -> CalculatorResult
    induction_motor_slip(...) -> CalculatorResult
    motor_inrush_current(...) -> CalculatorResult
    motor_heat_dissipation(...) -> CalculatorResult
    encoder_resolution(...) -> CalculatorResult
    motor_starting_torque(...) -> CalculatorResult
    battery_runtime_motor(...) -> CalculatorResult
    motor_winding_resistance(...) -> CalculatorResult
    h_bridge_selection(...) -> CalculatorResult
    motor_driver_power(...) -> CalculatorResult
    pid_tuning(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


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


def dc_motor_speed(voltage: float = 12.0, resistance: float = 0.5, backEmfConst: float = 0.01, torqueConst: float = 0.1, loadTorque: float = 0.1, efficiency: float = 85.0) -> CalculatorResult:
    """
    DC Motor Speed Calculator

    Category: motor

    Calculate DC motor speed, torque, power, and efficiency from electrical parameters

    Parameters
    ----------
    voltage : float
        Supply Voltage (V) (default: 12.0)
    resistance : float
        Armature Resistance (Ω) (default: 0.5)
    backEmfConst : float
        Back-EMF Constant (V/RPM) (default: 0.01)
    torqueConst : float
        Torque Constant (N·m/A) (default: 0.1)
    loadTorque : float
        Load Torque (N·m) (default: 0.1)
    efficiency : float
        Mechanical Efficiency (%) (default: 85.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'noLoadSpeed', 'loadSpeed', 'current', 'outputPower', 'inputPower', 'torque', 'efficiencyPct'
    """
    inputs = {"voltage": voltage, "resistance": resistance, "backEmfConst": backEmfConst, "torqueConst": torqueConst, "loadTorque": loadTorque, "efficiency": efficiency}
    return _client().calculate('dc-motor-speed', inputs)


def stepper_motor(stepsPerRev: float = 200.0, microstepping: float = 16.0, targetRPM: float = 60.0, leadScrewPitch: float = 2.0) -> CalculatorResult:
    """
    Stepper Motor Calculator

    Category: motor

    Calculate stepper motor speed, step frequency, and travel per revolution

    Parameters
    ----------
    stepsPerRev : float
        Steps per Revolution (steps) (default: 200.0)
    microstepping : float
        Microstepping Divisor (default: 16.0)
    targetRPM : float
        Target Speed (RPM) (default: 60.0)
    leadScrewPitch : float
        Lead Screw Pitch (mm/rev) (default: 2.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'stepFrequency', 'effectiveSteps', 'linearSpeed', 'stepAngle'
    """
    inputs = {"stepsPerRev": stepsPerRev, "microstepping": microstepping, "targetRPM": targetRPM, "leadScrewPitch": leadScrewPitch}
    return _client().calculate('stepper-motor', inputs)


def bldc_motor(kvRating: float = 1000.0, voltage: float = 12.0, motorResistance: float = 50.0, noLoadCurrent: float = 0.5, propDiameter: float = 5.0) -> CalculatorResult:
    """
    BLDC Motor Performance Calculator

    Category: motor

    Calculate brushless DC motor no-load RPM, stall torque, maximum efficiency, input power, and propeller thrust from Kv rating and electrical parameters

    Parameters
    ----------
    kvRating : float
        Motor Kv Rating (RPM/V) (default: 1000.0)
    voltage : float
        Operating Voltage (V) (default: 12.0)
    motorResistance : float
        Motor Winding Resistance (mΩ) (default: 50.0)
    noLoadCurrent : float
        No-Load Current (A) (default: 0.5)
    propDiameter : float
        Propeller Diameter (inch) (default: 5.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'noLoadRpm', 'stallTorque', 'maxEfficiency', 'inputPower', 'thrust'
    """
    inputs = {"kvRating": kvRating, "voltage": voltage, "motorResistance": motorResistance, "noLoadCurrent": noLoadCurrent, "propDiameter": propDiameter}
    return _client().calculate('bldc-motor', inputs)


def servo_motor(voltage: float = 5.0, current: float = 0.5, speed: float = 500.0, loadTorque: float = 0.05, armRes: float = 2.0) -> CalculatorResult:
    """
    Servo Motor Torque & Speed

    Category: motor

    Calculate servo motor torque, speed, efficiency, and back-EMF from electrical and load parameters.

    Parameters
    ----------
    voltage : float
        Supply Voltage (V) (default: 5.0)
    current : float
        Operating Current (A) (default: 0.5)
    speed : float
        No-Load Speed (RPM) (default: 500.0)
    loadTorque : float
        Load Torque (N·m) (default: 0.05)
    armRes : float
        Winding Resistance (Ω) (default: 2.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'inputPower', 'outputPower', 'efficiency', 'backEmf', 'stallTorque'
    """
    inputs = {"voltage": voltage, "current": current, "speed": speed, "loadTorque": loadTorque, "armRes": armRes}
    return _client().calculate('servo-motor', inputs)


def gear_ratio(driverTeeth: float = 10.0, drivenTeeth: float = 40.0, inputSpeed: float = 1000.0, inputTorque: float = 0.5, efficiency: float = 95.0) -> CalculatorResult:
    """
    Gear Ratio Calculator

    Category: motor

    Calculate gear ratio, output speed, torque multiplication, and power transmission efficiency for gear trains.

    Parameters
    ----------
    driverTeeth : float
        Driver (Input) Teeth (teeth) (default: 10.0)
    drivenTeeth : float
        Driven (Output) Teeth (teeth) (default: 40.0)
    inputSpeed : float
        Input Speed (RPM) (default: 1000.0)
    inputTorque : float
        Input Torque (N·m) (default: 0.5)
    efficiency : float
        Gear Efficiency (%) (default: 95.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'gearRatio', 'outputSpeed', 'outputTorque', 'inputPower', 'outputPower'
    """
    inputs = {"driverTeeth": driverTeeth, "drivenTeeth": drivenTeeth, "inputSpeed": inputSpeed, "inputTorque": inputTorque, "efficiency": efficiency}
    return _client().calculate('gear-ratio', inputs)


def pwm_duty_cycle_motor(supplyVoltage: float = 12.0, dutyCycle: float = 75.0, motorKv: float = 100.0, motorResistance: float = 1.5) -> CalculatorResult:
    """
    PWM Duty Cycle to Motor Voltage

    Category: motor

    Convert PWM duty cycle to effective motor voltage, calculate no-load speed and stall current for DC motor PWM control.

    Parameters
    ----------
    supplyVoltage : float
        Supply Voltage (V) (default: 12.0)
    dutyCycle : float
        Duty Cycle (%) (default: 75.0)
    motorKv : float
        Motor Kv Constant (RPM/V) (default: 100.0)
    motorResistance : float
        Winding Resistance (Ω) (default: 1.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'effectiveVoltage', 'noLoadSpeed', 'stallCurrent', 'peakPower', 'rippleVoltageFactor'
    """
    inputs = {"supplyVoltage": supplyVoltage, "dutyCycle": dutyCycle, "motorKv": motorKv, "motorResistance": motorResistance}
    return _client().calculate('pwm-duty-cycle-motor', inputs)


def torque_unit_converter(nm: float = 1.0) -> CalculatorResult:
    """
    Torque Unit Converter

    Category: motor

    Convert torque between Newton-metres, pound-feet, pound-inches, oz·in, kg·cm and dyne·cm — covers all motor datasheet units.

    Parameters
    ----------
    nm : float
        Torque (N·m) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'lbFt', 'lbIn', 'ozIn', 'kgCm', 'kgM', 'dyneCm'
    """
    inputs = {"nm": nm}
    return _client().calculate('torque-unit-converter', inputs)


def motor_efficiency(inputVoltage: float = 12.0, inputCurrent: float = 2.0, outputPowerW: float = 18.0) -> CalculatorResult:
    """
    Motor Input/Output Efficiency

    Category: motor

    Calculate motor efficiency, power losses, and heat dissipation from electrical input and mechanical output measurements.

    Parameters
    ----------
    inputVoltage : float
        Supply Voltage (V) (default: 12.0)
    inputCurrent : float
        Supply Current (A) (default: 2.0)
    outputPowerW : float
        Mechanical Output Power (W) (default: 18.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'inputPower', 'efficiency', 'losses', 'heatDissipation'
    """
    inputs = {"inputVoltage": inputVoltage, "inputCurrent": inputCurrent, "outputPowerW": outputPowerW}
    return _client().calculate('motor-efficiency', inputs)


def induction_motor_slip(frequency: float = 60.0, poles: float = 4.0, rotorSpeed: float = 1750.0, syncSpeed: float = 0.0) -> CalculatorResult:
    """
    Induction Motor Slip

    Category: motor

    Calculate induction motor slip, synchronous speed, slip frequency, and rotor speed for AC induction motors.

    Parameters
    ----------
    frequency : float
        Supply Frequency (Hz) (default: 60.0)
    poles : float
        Number of Poles (default: 4.0)
    rotorSpeed : float
        Rotor Speed (actual) (RPM) (default: 1750.0)
    syncSpeed : float
        Synchronous Speed (override) (RPM) (default: 0.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'effectiveSyncSpeed', 'slipPercent', 'slipRPM', 'slipFrequency'
    """
    inputs = {"frequency": frequency, "poles": poles, "rotorSpeed": rotorSpeed, "syncSpeed": syncSpeed}
    return _client().calculate('induction-motor-slip', inputs)


def motor_inrush_current(ratedCurrent: float = 5.0, inrushMultiplier: float = 6.0, startupDuration: float = 0.1, supplyVoltage: float = 120.0, lineResistance: float = 0.5) -> CalculatorResult:
    """
    Motor Inrush Current

    Category: motor

    Calculate motor inrush current, voltage drop during startup, and I²t value for fuse/breaker selection.

    Parameters
    ----------
    ratedCurrent : float
        Rated Full-Load Current (A) (default: 5.0)
    inrushMultiplier : float
        Inrush Multiplier (×) (default: 6.0)
    startupDuration : float
        Startup Duration (s) (default: 0.1)
    supplyVoltage : float
        Supply Voltage (V) (default: 120.0)
    lineResistance : float
        Line Resistance (Ω) (default: 0.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'inrushCurrent', 'voltageDropAtInrush', 'voltageDropPercent', 'fuseISquaredT', 'peakPower'
    """
    inputs = {"ratedCurrent": ratedCurrent, "inrushMultiplier": inrushMultiplier, "startupDuration": startupDuration, "supplyVoltage": supplyVoltage, "lineResistance": lineResistance}
    return _client().calculate('motor-inrush-current', inputs)


def motor_heat_dissipation(inputPower: float = 50.0, efficiency: float = 80.0, ambientTemp: float = 25.0, thermalResistance: float = 2.5) -> CalculatorResult:
    """
    Motor Heat Dissipation

    Category: motor

    Calculate motor heat dissipation, temperature rise, and operating temperature from input power and efficiency.

    Parameters
    ----------
    inputPower : float
        Input Power (W) (default: 50.0)
    efficiency : float
        Motor Efficiency (%) (default: 80.0)
    ambientTemp : float
        Ambient Temperature (°C) (default: 25.0)
    thermalResistance : float
        Thermal Resistance (motor) (°C/W) (default: 2.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'losses', 'tempRise', 'motorTemp', 'outputPower'
    """
    inputs = {"inputPower": inputPower, "efficiency": efficiency, "ambientTemp": ambientTemp, "thermalResistance": thermalResistance}
    return _client().calculate('motor-heat-dissipation', inputs)


def encoder_resolution(ppr: float = 1000.0, quadrature: float = 1.0, gearRatio: float = 1.0, motorMaxRpm: float = 3000.0) -> CalculatorResult:
    """
    Encoder Resolution Calculator

    Category: motor

    Calculate encoder counts per revolution, angular resolution, and maximum frequency for quadrature and single-channel encoders.

    Parameters
    ----------
    ppr : float
        Pulses Per Revolution (PPR) (pulses) (default: 1000.0)
    quadrature : float
        Quadrature (×4) (default: 1.0)
    gearRatio : float
        Gear Ratio (:1) (default: 1.0)
    motorMaxRpm : float
        Max Motor Speed (RPM) (default: 3000.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'countsMechanicalRev', 'countsPerOutputRev', 'degreePerCount', 'maxFrequency'
    """
    inputs = {"ppr": ppr, "quadrature": quadrature, "gearRatio": gearRatio, "motorMaxRpm": motorMaxRpm}
    return _client().calculate('encoder-resolution', inputs)


def motor_starting_torque(voltage: float = 12.0, resistance: float = 0.5, torqueConst: float = 0.05, backEmfConst: float = 0.01) -> CalculatorResult:
    """
    Motor Starting Torque

    Category: motor

    Calculate DC motor starting (stall) torque, stall current, no-load speed, and peak power at startup.

    Parameters
    ----------
    voltage : float
        Supply Voltage (V) (default: 12.0)
    resistance : float
        Winding Resistance (Ω) (default: 0.5)
    torqueConst : float
        Torque Constant (N·m/A) (default: 0.05)
    backEmfConst : float
        Back-EMF Constant (V/RPM) (default: 0.01)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'startingTorque', 'stallCurrent', 'noLoadSpeed', 'powerAtStall'
    """
    inputs = {"voltage": voltage, "resistance": resistance, "torqueConst": torqueConst, "backEmfConst": backEmfConst}
    return _client().calculate('motor-starting-torque', inputs)


def battery_runtime_motor(batteryCapacityMah: float = 2000.0, batteryVoltage: float = 3.7, motorCurrentA: float = 0.5, efficiency: float = 85.0, depthOfDischarge: float = 80.0) -> CalculatorResult:
    """
    Battery Runtime (Motor Load)

    Category: motor

    Calculate battery runtime for motor-driven systems accounting for motor current draw, efficiency, and depth of discharge.

    Parameters
    ----------
    batteryCapacityMah : float
        Battery Capacity (mAh) (default: 2000.0)
    batteryVoltage : float
        Battery Voltage (V) (default: 3.7)
    motorCurrentA : float
        Motor Current (avg) (A) (default: 0.5)
    efficiency : float
        Drive Efficiency (%) (default: 85.0)
    depthOfDischarge : float
        Depth of Discharge (%) (default: 80.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'runtimeHours', 'runtimeMinutes', 'usableCapacityMah', 'energyWh'
    """
    inputs = {"batteryCapacityMah": batteryCapacityMah, "batteryVoltage": batteryVoltage, "motorCurrentA": motorCurrentA, "efficiency": efficiency, "depthOfDischarge": depthOfDischarge}
    return _client().calculate('battery-runtime-motor', inputs)


def motor_winding_resistance(resistance25: float = 1.0, temperature: float = 80.0, tempCoeff: float = 0.00393) -> CalculatorResult:
    """
    Winding Resistance vs Temperature

    Category: motor

    Calculate motor winding resistance at operating temperature using the copper temperature coefficient of resistance.

    Parameters
    ----------
    resistance25 : float
        Resistance at 25°C (Ω) (default: 1.0)
    temperature : float
        Operating Temperature (°C) (default: 80.0)
    tempCoeff : float
        Temperature Coefficient (/°C) (default: 0.00393)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'resistanceAtTemp', 'resistanceChange', 'resistanceChangePercent'
    """
    inputs = {"resistance25": resistance25, "temperature": temperature, "tempCoeff": tempCoeff}
    return _client().calculate('motor-winding-resistance', inputs)


def h_bridge_selection(motorCurrent: float = 2.0, motorVoltage: float = 12.0, inrushMultiplier: float = 6.0, pwmFrequency: float = 20000.0, mosfetRdson: float = 0.01) -> CalculatorResult:
    """
    H-Bridge MOSFET Selection

    Category: motor

    Calculate H-bridge MOSFET requirements including peak current, conduction losses, and minimum current rating for DC motor drivers.

    Parameters
    ----------
    motorCurrent : float
        Motor Rated Current (A) (default: 2.0)
    motorVoltage : float
        Motor Supply Voltage (V) (default: 12.0)
    inrushMultiplier : float
        Inrush Multiplier (×) (default: 6.0)
    pwmFrequency : float
        PWM Frequency (Hz) (default: 20000.0)
    mosfetRdson : float
        MOSFET RDS(on) (Ω) (default: 0.01)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'peakCurrent', 'mosfetCurrentRating', 'conductionLoss', 'switchingLoss', 'totalLoss'
    """
    inputs = {"motorCurrent": motorCurrent, "motorVoltage": motorVoltage, "inrushMultiplier": inrushMultiplier, "pwmFrequency": pwmFrequency, "mosfetRdson": mosfetRdson}
    return _client().calculate('h-bridge-selection', inputs)


def motor_driver_power(motorCurrent: float = 2.0, supplyVoltage: float = 12.0, rdson: float = 0.015, dutyCycle: float = 75.0, switchingFreq: float = 20000.0, gateCharge: float = 30.0) -> CalculatorResult:
    """
    Motor Driver Power Dissipation

    Category: motor

    Calculate motor driver IC or discrete MOSFET power dissipation including conduction loss and switching loss at a given PWM frequency.

    Parameters
    ----------
    motorCurrent : float
        Motor Current (RMS) (A) (default: 2.0)
    supplyVoltage : float
        Supply Voltage (V) (default: 12.0)
    rdson : float
        RDS(on) (Ω) (default: 0.015)
    dutyCycle : float
        PWM Duty Cycle (%) (default: 75.0)
    switchingFreq : float
        Switching Frequency (Hz) (default: 20000.0)
    gateCharge : float
        Gate Charge Qg (nC) (default: 30.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'conductionLoss', 'switchingLoss', 'totalLossPerFet', 'totalLossBridge', 'efficiency'
    """
    inputs = {"motorCurrent": motorCurrent, "supplyVoltage": supplyVoltage, "rdson": rdson, "dutyCycle": dutyCycle, "switchingFreq": switchingFreq, "gateCharge": gateCharge}
    return _client().calculate('motor-driver-power', inputs)


def pid_tuning(processGain: float = 1.5, deadTime: float = 0.1, timeConstant: float = 1.0) -> CalculatorResult:
    """
    PID Controller Tuning (Ziegler-Nichols)

    Category: motor

    Calculate PID controller gains using the Ziegler-Nichols open-loop (reaction curve) method from process gain, dead time, and time constant.

    Parameters
    ----------
    processGain : float
        Process Gain (K) (default: 1.5)
    deadTime : float
        Dead Time (L) (s) (default: 0.1)
    timeConstant : float
        Time Constant (τ) (s) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'kpPID', 'kiPID', 'kdPID', 'kpPI', 'tiPI'
    """
    inputs = {"processGain": processGain, "deadTime": deadTime, "timeConstant": timeConstant}
    return _client().calculate('pid-tuning', inputs)

