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

Functions:
    ntc_thermistor(...) -> CalculatorResult
    rtd_temperature(...) -> CalculatorResult
    wheatstone_bridge(...) -> CalculatorResult
    hall_effect_sensor(...) -> CalculatorResult
    strain_gauge_bridge(...) -> CalculatorResult
    pt100_resistance(...) -> CalculatorResult
    thermocouple_voltage(...) -> CalculatorResult
    load_cell_amplifier(...) -> CalculatorResult
    photodiode_transimpedance(...) -> CalculatorResult
    capacitive_proximity(...) -> CalculatorResult
    current_shunt(...) -> CalculatorResult
    accelerometer_sensitivity(...) -> CalculatorResult
    pressure_bridge_output(...) -> CalculatorResult
    sensor_accuracy_budget(...) -> CalculatorResult
    optical_sensor_range(...) -> CalculatorResult
    lvdt_sensitivity(...) -> CalculatorResult
    4_20ma_transmitter(...) -> CalculatorResult
"""
from __future__ import annotations
import rftools as _rftools
from rftools.types import CalculatorResult


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


def ntc_thermistor(resistance: float = 10000.0, beta: float = 3950.0, T0: float = 25.0, R0: float = 10000.0) -> CalculatorResult:
    """
    NTC Thermistor Temperature Calculator

    Category: sensor

    Calculate temperature from NTC thermistor resistance using the Steinhart-Hart beta equation. Useful for PT100/PT1000 and generic NTC thermistors.

    Parameters
    ----------
    resistance : float
        Measured Resistance (Ω) (default: 10000.0)
    beta : float
        Beta Coefficient (K) (default: 3950.0)
    T0 : float
        Reference Temperature (°C) (default: 25.0)
    R0 : float
        Reference Resistance (Ω) (default: 10000.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'temperature', 'temperatureK'
    """
    inputs = {"resistance": resistance, "beta": beta, "T0": T0, "R0": R0}
    return _client().calculate('ntc-thermistor', inputs)


def rtd_temperature(resistance: float = 119.4, r0: float = 100.0, alpha: float = 0.003851) -> CalculatorResult:
    """
    RTD Temperature Calculator (PT100/PT1000)

    Category: sensor

    Calculate temperature from PT100 or PT1000 RTD (Resistance Temperature Detector) measured resistance using the linear Callendar-Van Dusen approximation.

    Parameters
    ----------
    resistance : float
        Measured Resistance (Ω) (default: 119.4)
    r0 : float
        Nominal Resistance (R₀) (Ω) (default: 100.0)
    alpha : float
        Temperature Coefficient (°C⁻¹) (default: 0.003851)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'temperature', 'resistanceAt100C'
    """
    inputs = {"resistance": resistance, "r0": r0, "alpha": alpha}
    return _client().calculate('rtd-temperature', inputs)


def wheatstone_bridge(vin: float = 5.0, r1: float = 1000.0, r2: float = 1000.0, r3: float = 1000.0, r4: float = 1000.0) -> CalculatorResult:
    """
    Wheatstone Bridge Calculator

    Category: sensor

    Calculate Wheatstone bridge output voltage, balance condition, and sensitivity. Used for strain gauges, RTDs, and precision resistance measurements.

    Parameters
    ----------
    vin : float
        Supply Voltage (V) (default: 5.0)
    r1 : float
        R1 (top-left) (Ω) (default: 1000.0)
    r2 : float
        R2 (top-right) (Ω) (default: 1000.0)
    r3 : float
        R3 (bottom-left) (Ω) (default: 1000.0)
    r4 : float
        R4 (bottom-right) (Ω) (default: 1000.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'vout', 'voutMv', 'balance', 'sensitivity'
    """
    inputs = {"vin": vin, "r1": r1, "r2": r2, "r3": r3, "r4": r4}
    return _client().calculate('wheatstone-bridge', inputs)


def hall_effect_sensor(current: float = 100.0, Bfield: float = 100.0, thickness: float = 0.5, carrierDensity: float = 8.5) -> CalculatorResult:
    """
    Hall Effect Sensor Calculator

    Category: sensor

    Calculate Hall voltage, Hall coefficient, and sensitivity for Hall effect sensors. Useful for magnetic field measurement, current sensing, and position detection.

    Parameters
    ----------
    current : float
        Control Current (mA) (default: 100.0)
    Bfield : float
        Magnetic Field (mT) (default: 100.0)
    thickness : float
        Element Thickness (mm) (default: 0.5)
    carrierDensity : float
        Carrier Density (×10²³) (×10²³/m³) (default: 8.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'hallVoltage', 'hallCoefficient', 'sensitivity'
    """
    inputs = {"current": current, "Bfield": Bfield, "thickness": thickness, "carrierDensity": carrierDensity}
    return _client().calculate('hall-effect-sensor', inputs)


def strain_gauge_bridge(vin: float = 5.0, gaugeFactor: float = 2.1, strain: float = 1000.0, bridgeConfig: float = 1.0) -> CalculatorResult:
    """
    Strain Gauge Bridge Calculator

    Category: sensor

    Calculate Wheatstone bridge output voltage for strain gauges. Supports quarter, half, and full bridge configurations for structural monitoring and load cell design.

    Parameters
    ----------
    vin : float
        Excitation Voltage (V) (default: 5.0)
    gaugeFactor : float
        Gauge Factor (default: 2.1)
    strain : float
        Applied Strain (με) (default: 1000.0)
    bridgeConfig : float
        Bridge Configuration (active arms) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'vout', 'resistance_change', 'strain_SI'
    """
    inputs = {"vin": vin, "gaugeFactor": gaugeFactor, "strain": strain, "bridgeConfig": bridgeConfig}
    return _client().calculate('strain-gauge-bridge', inputs)


def pt100_resistance(r0: float = 100.0, temperature: float = 25.0) -> CalculatorResult:
    """
    PT100/PT1000 Resistance vs Temperature

    Category: sensor

    Calculate PT100 or PT1000 RTD resistance at any temperature using the ITS-90 Callendar-Van Dusen equation.

    Parameters
    ----------
    r0 : float
        R₀ (at 0°C) (Ω) (default: 100.0)
    temperature : float
        Temperature (°C) (default: 25.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'resistance', 'sensitivityOhmPerDeg'
    """
    inputs = {"r0": r0, "temperature": temperature}
    return _client().calculate('pt100-resistance', inputs)


def thermocouple_voltage(type_: float = 0.0, temperature: float = 200.0, coldJunctionTemp: float = 25.0) -> CalculatorResult:
    """
    Thermocouple Voltage & Temperature

    Category: sensor

    Calculate thermocouple EMF voltage from hot junction temperature and cold junction compensation for Type K, J, T, and E thermocouples.

    Parameters
    ----------
    type_ : float
        Thermocouple Type (default: 0.0)
    temperature : float
        Hot Junction Temperature (°C) (default: 200.0)
    coldJunctionTemp : float
        Cold Junction Temperature (°C) (default: 25.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'voltage', 'coldJunctionCorrection', 'seebeck', 'deltaT'
    """
    inputs = {"type": type_, "temperature": temperature, "coldJunctionTemp": coldJunctionTemp}
    return _client().calculate('thermocouple-voltage', inputs)


def load_cell_amplifier(excitationVoltage: float = 5.0, sensitivity: float = 2.0, fullScaleLoad: float = 10.0, gain: float = 500.0) -> CalculatorResult:
    """
    Load Cell Amplifier Gain

    Category: sensor

    Calculate load cell output voltage, required amplifier gain, and sensitivity for Wheatstone bridge load cells.

    Parameters
    ----------
    excitationVoltage : float
        Excitation Voltage (V) (default: 5.0)
    sensitivity : float
        Load Cell Sensitivity (mV/V) (default: 2.0)
    fullScaleLoad : float
        Full-Scale Load (kg) (default: 10.0)
    gain : float
        Amplifier Gain (V/V) (default: 500.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'fullScaleOutputMv', 'amplifiedOutput', 'sensitivityPerUnit', 'requiredGain'
    """
    inputs = {"excitationVoltage": excitationVoltage, "sensitivity": sensitivity, "fullScaleLoad": fullScaleLoad, "gain": gain}
    return _client().calculate('load-cell-amplifier', inputs)


def photodiode_transimpedance(photocurrent: float = 10.0, feedbackResistance: float = 100.0, feedbackCapacitance: float = 10.0) -> CalculatorResult:
    """
    Photodiode Transimpedance Amplifier

    Category: sensor

    Calculate transimpedance amplifier (TIA) output voltage, bandwidth, and noise for photodiode signal conditioning.

    Parameters
    ----------
    photocurrent : float
        Photocurrent (μA) (default: 10.0)
    feedbackResistance : float
        Feedback Resistor (Rf) (kΩ) (default: 100.0)
    feedbackCapacitance : float
        Feedback Capacitor (Cf) (pF) (default: 10.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'outputVoltageV', 'bandwidth', 'noiseVoltage'
    """
    inputs = {"photocurrent": photocurrent, "feedbackResistance": feedbackResistance, "feedbackCapacitance": feedbackCapacitance}
    return _client().calculate('photodiode-transimpedance', inputs)


def capacitive_proximity(plateArea: float = 1.0, gapDistance: float = 5.0, permittivity: float = 1.0) -> CalculatorResult:
    """
    Capacitive Proximity Sensor

    Category: sensor

    Calculate capacitance between sensor plate and target, and sensitivity (pF/mm) for capacitive proximity sensor design.

    Parameters
    ----------
    plateArea : float
        Sensor Plate Area (cm²) (default: 1.0)
    gapDistance : float
        Gap to Target (mm) (default: 5.0)
    permittivity : float
        Relative Permittivity (εᵣ) (default: 1.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'capacitancePf', 'sensitivity'
    """
    inputs = {"plateArea": plateArea, "gapDistance": gapDistance, "permittivity": permittivity}
    return _client().calculate('capacitive-proximity', inputs)


def current_shunt(current: float = 10.0, shuntResistance: float = 10.0, amplifierGain: float = 50.0, adcVoltage: float = 3.3) -> CalculatorResult:
    """
    Current Shunt Resistor

    Category: sensor

    Calculate shunt resistor voltage drop, amplifier output, power dissipation, and ADC resolution for current sensing.

    Parameters
    ----------
    current : float
        Measured Current (A) (default: 10.0)
    shuntResistance : float
        Shunt Resistance (mΩ) (default: 10.0)
    amplifierGain : float
        Amplifier Gain (V/V) (default: 50.0)
    adcVoltage : float
        ADC Reference Voltage (V) (default: 3.3)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'shuntVoltage', 'amplifiedVoltage', 'powerDissipation', 'adcResolutionCurrent'
    """
    inputs = {"current": current, "shuntResistance": shuntResistance, "amplifierGain": amplifierGain, "adcVoltage": adcVoltage}
    return _client().calculate('current-shunt', inputs)


def accelerometer_sensitivity(sensitivity: float = 300.0, fullScaleRange: float = 3.0, supplyVoltage: float = 3.3, adcBits: float = 12.0) -> CalculatorResult:
    """
    Accelerometer Range & Sensitivity

    Category: sensor

    Calculate accelerometer output voltage, ADC resolution, and mg per LSB from sensitivity and full-scale range specifications.

    Parameters
    ----------
    sensitivity : float
        Sensitivity (mV/g) (default: 300.0)
    fullScaleRange : float
        Full-Scale Range (g) (default: 3.0)
    supplyVoltage : float
        Supply Voltage (V) (default: 3.3)
    adcBits : float
        ADC Resolution (bits) (default: 12.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'fullScaleVoltage', 'voltagePerCount', 'accelerationMgPerCount'
    """
    inputs = {"sensitivity": sensitivity, "fullScaleRange": fullScaleRange, "supplyVoltage": supplyVoltage, "adcBits": adcBits}
    return _client().calculate('accelerometer-sensitivity', inputs)


def pressure_bridge_output(excitationVoltage: float = 5.0, bridgeSensitivity: float = 10.0, appliedPressure: float = 50.0, fullScalePressure: float = 100.0) -> CalculatorResult:
    """
    Pressure Sensor Bridge Output

    Category: sensor

    Calculate Wheatstone bridge output voltage for piezoresistive pressure sensors from excitation, sensitivity, and applied pressure.

    Parameters
    ----------
    excitationVoltage : float
        Bridge Excitation Voltage (V) (default: 5.0)
    bridgeSensitivity : float
        Bridge Sensitivity (mV/V) (default: 10.0)
    appliedPressure : float
        Applied Pressure (kPa) (default: 50.0)
    fullScalePressure : float
        Full-Scale Pressure (kPa) (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'bridgeOutputMv', 'fullScaleOutput', 'fractionalDeflection'
    """
    inputs = {"excitationVoltage": excitationVoltage, "bridgeSensitivity": bridgeSensitivity, "appliedPressure": appliedPressure, "fullScalePressure": fullScalePressure}
    return _client().calculate('pressure-bridge-output', inputs)


def sensor_accuracy_budget(offsetError: float = 0.1, gainError: float = 0.2, nonlinearity: float = 0.1, resolution: float = 0.05, tempDrift: float = 0.005, tempRange: float = 40.0) -> CalculatorResult:
    """
    Sensor Accuracy Budget

    Category: sensor

    Calculate total sensor system accuracy using RSS and worst-case methods from offset, gain, nonlinearity, resolution, and temperature drift errors.

    Parameters
    ----------
    offsetError : float
        Offset Error (% FS) (default: 0.1)
    gainError : float
        Gain/Sensitivity Error (% FS) (default: 0.2)
    nonlinearity : float
        Nonlinearity (% FS) (default: 0.1)
    resolution : float
        Resolution Error (% FS) (default: 0.05)
    tempDrift : float
        Temp Drift (% FS/°C) (default: 0.005)
    tempRange : float
        Temperature Range (°C) (default: 40.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'tempError', 'totalRss', 'totalWorstCase'
    """
    inputs = {"offsetError": offsetError, "gainError": gainError, "nonlinearity": nonlinearity, "resolution": resolution, "tempDrift": tempDrift, "tempRange": tempRange}
    return _client().calculate('sensor-accuracy-budget', inputs)


def optical_sensor_range(emitterPower: float = 10.0, detectorSensitivity: float = 0.6, targetReflectivity: float = 90.0, safetyFactor: float = 1.5) -> CalculatorResult:
    """
    Optical Proximity Sensor Range

    Category: sensor

    Compare optical proximity sensor configurations using a relative detection factor derived from emitter power, detector responsivity, and target reflectivity. The output is dimensionless — use it to rank or compare configurations, not as an absolute distance.

    Parameters
    ----------
    emitterPower : float
        Emitter Power (mW) (default: 10.0)
    detectorSensitivity : float
        Detector Responsivity (A/W) (default: 0.6)
    targetReflectivity : float
        Target Reflectivity (%) (default: 90.0)
    safetyFactor : float
        Safety Factor (default: 1.5)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'maxRange', 'normalizedRange'
    """
    inputs = {"emitterPower": emitterPower, "detectorSensitivity": detectorSensitivity, "targetReflectivity": targetReflectivity, "safetyFactor": safetyFactor}
    return _client().calculate('optical-sensor-range', inputs)


def lvdt_sensitivity(excitationVoltage: float = 5.0, sensitivity: float = 4.0, coreDisplacement: float = 5.0, fullScaleRange: float = 25.0) -> CalculatorResult:
    """
    LVDT Sensitivity & Range

    Category: sensor

    Calculate LVDT (Linear Variable Differential Transformer) output voltage, sensitivity in mV/mm, and linear range from excitation and stroke.

    Parameters
    ----------
    excitationVoltage : float
        Excitation Voltage (RMS) (V) (default: 5.0)
    sensitivity : float
        Sensitivity (mV/V/%FS) (default: 4.0)
    coreDisplacement : float
        Core Displacement (mm) (default: 5.0)
    fullScaleRange : float
        Full-Scale Range (±) (mm) (default: 25.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'outputVoltage', 'fullScaleOutput', 'sensitivityMvMm', 'linearRange'
    """
    inputs = {"excitationVoltage": excitationVoltage, "sensitivity": sensitivity, "coreDisplacement": coreDisplacement, "fullScaleRange": fullScaleRange}
    return _client().calculate('lvdt-sensitivity', inputs)


def 4_20ma_transmitter(supplyVoltage: float = 24.0, loopCurrent: float = 12.0, loopResistance: float = 250.0, sensorRangeMin: float = 0.0, sensorRangeMax: float = 100.0) -> CalculatorResult:
    """
    4–20 mA Loop Transmitter

    Category: sensor

    Calculate 4–20 mA current loop voltage budget, sensor value from current, and maximum loop resistance for industrial sensor transmitters.

    Parameters
    ----------
    supplyVoltage : float
        Loop Supply Voltage (V) (default: 24.0)
    loopCurrent : float
        Loop Current (mA) (default: 12.0)
    loopResistance : float
        Loop Resistance (Ω) (default: 250.0)
    sensorRangeMin : float
        Sensor Range Min (default: 0.0)
    sensorRangeMax : float
        Sensor Range Max (default: 100.0)

    Returns
    -------
    CalculatorResult
        ``values`` dict keys: 'sensorValue', 'voltageAtLoad', 'availableVoltage', 'maxLoopResistance'
    """
    inputs = {"supplyVoltage": supplyVoltage, "loopCurrent": loopCurrent, "loopResistance": loopResistance, "sensorRangeMin": sensorRangeMin, "sensorRangeMax": sensorRangeMax}
    return _client().calculate('4-20ma-transmitter', inputs)

