oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/analyzers/power/basic.py

@@ -0,0 +1,383 @@
+"""Basic power analysis for TraceKit.
+
+Provides fundamental power calculations including instantaneous power,
+average power, RMS power, peak power, and energy.
+
+
+Example:
+    >>> from oscura.analyzers.power.basic import instantaneous_power, power_statistics
+    >>> power_trace = instantaneous_power(voltage_trace, current_trace)
+    >>> stats = power_statistics(power_trace)
+    >>> print(f"Average: {stats['average']:.2f} W, Peak: {stats['peak']:.2f} W")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from scipy import interpolate
+
+from oscura.core.exceptions import AnalysisError
+from oscura.core.types import TraceMetadata, WaveformTrace
+
+
+def instantaneous_power(
+    voltage: WaveformTrace,
+    current: WaveformTrace,
+    *,
+    interpolate_if_needed: bool = True,
+) -> WaveformTrace:
+    """Calculate instantaneous power from voltage and current traces.
+
+    P(t) = V(t) * I(t)
+
+    Args:
+        voltage: Voltage waveform trace.
+        current: Current waveform trace.
+        interpolate_if_needed: If True, interpolate if sample rates differ.
+
+    Returns:
+        Power waveform trace (in Watts if inputs are V and A).
+
+    Raises:
+        AnalysisError: If sample rates mismatch and interpolation disabled.
+
+    Example:
+        >>> power = instantaneous_power(v_trace, i_trace)
+        >>> print(f"Peak power: {np.max(power.data):.2f} W")
+
+    References:
+        IEC 61000-4-7 (power measurements)
+    """
+    v_data = voltage.data
+    i_data = current.data
+    v_rate = voltage.metadata.sample_rate
+    i_rate = current.metadata.sample_rate
+
+    # Handle different sample rates
+    if v_rate != i_rate:
+        if not interpolate_if_needed:
+            raise AnalysisError(
+                f"Sample rate mismatch: voltage={v_rate}, current={i_rate}. "
+                "Set interpolate_if_needed=True to interpolate."
+            )
+
+        # Use higher sample rate and interpolate the other
+        if v_rate > i_rate:
+            # Interpolate current to voltage sample rate
+            t_current = np.arange(len(i_data)) / i_rate
+            t_voltage = np.arange(len(v_data)) / v_rate
+            interp = interpolate.interp1d(
+                t_current, i_data, kind="linear", fill_value="extrapolate"
+            )
+            i_data = interp(t_voltage)
+            sample_rate = v_rate
+        else:
+            # Interpolate voltage to current sample rate
+            t_voltage = np.arange(len(v_data)) / v_rate
+            t_current = np.arange(len(i_data)) / i_rate
+            interp = interpolate.interp1d(
+                t_voltage, v_data, kind="linear", fill_value="extrapolate"
+            )
+            v_data = interp(t_current)
+            sample_rate = i_rate
+    else:
+        sample_rate = v_rate
+
+    # Handle different lengths
+    min_len = min(len(v_data), len(i_data))
+    v_data = v_data[:min_len]
+    i_data = i_data[:min_len]
+
+    # Calculate instantaneous power
+    power_data = v_data * i_data
+
+    return WaveformTrace(
+        data=power_data.astype(np.float64),
+        metadata=TraceMetadata(sample_rate=sample_rate),
+    )
+
+
+def average_power(
+    power: WaveformTrace | None = None,
+    *,
+    voltage: WaveformTrace | None = None,
+    current: WaveformTrace | None = None,
+) -> float:
+    """Calculate average (mean) power.
+
+    P_avg = (1/T) * integral(P(t) dt)
+
+    Args:
+        power: Power trace (if already calculated).
+        voltage: Voltage trace (alternative to power).
+        current: Current trace (alternative to power).
+
+    Returns:
+        Average power in Watts.
+
+    Raises:
+        AnalysisError: If neither power nor both voltage and current provided.
+
+    Example:
+        >>> p_avg = average_power(power_trace)
+        >>> # or
+        >>> p_avg = average_power(voltage=v, current=i)
+    """
+    if power is None:
+        if voltage is None or current is None:
+            raise AnalysisError("Either power trace or both voltage and current traces required")
+        power = instantaneous_power(voltage, current)
+
+    return float(np.mean(power.data))
+
+
+def rms_power(
+    power: WaveformTrace | None = None,
+    *,
+    voltage: WaveformTrace | None = None,
+    current: WaveformTrace | None = None,
+) -> float:
+    """Calculate RMS power.
+
+    P_rms = sqrt(mean(P(t)^2))
+
+    Args:
+        power: Power trace.
+        voltage: Voltage trace (alternative).
+        current: Current trace (alternative).
+
+    Returns:
+        RMS power in Watts.
+
+    Raises:
+        AnalysisError: If neither power nor both voltage and current provided.
+
+    Example:
+        >>> p_rms = rms_power(power_trace)
+    """
+    if power is None:
+        if voltage is None or current is None:
+            raise AnalysisError("Either power trace or both voltage and current traces required")
+        power = instantaneous_power(voltage, current)
+
+    return float(np.sqrt(np.mean(power.data**2)))
+
+
+def peak_power(
+    power: WaveformTrace | None = None,
+    *,
+    voltage: WaveformTrace | None = None,
+    current: WaveformTrace | None = None,
+    absolute: bool = True,
+) -> float:
+    """Calculate peak power.
+
+    Args:
+        power: Power trace.
+        voltage: Voltage trace (alternative).
+        current: Current trace (alternative).
+        absolute: If True, return absolute maximum. If False, maximum value.
+
+    Returns:
+        Peak power in Watts.
+
+    Raises:
+        AnalysisError: If neither power nor both voltage and current provided.
+
+    Example:
+        >>> p_peak = peak_power(power_trace)
+    """
+    if power is None:
+        if voltage is None or current is None:
+            raise AnalysisError("Either power trace or both voltage and current traces required")
+        power = instantaneous_power(voltage, current)
+
+    if absolute:
+        return float(np.max(np.abs(power.data)))
+    return float(np.max(power.data))
+
+
+def energy(
+    power: WaveformTrace | None = None,
+    *,
+    voltage: WaveformTrace | None = None,
+    current: WaveformTrace | None = None,
+    start_time: float | None = None,
+    end_time: float | None = None,
+) -> float:
+    """Calculate energy (integral of power over time).
+
+    E = integral(P(t) dt)
+
+    Args:
+        power: Power trace.
+        voltage: Voltage trace (alternative).
+        current: Current trace (alternative).
+        start_time: Start time for integration (seconds).
+        end_time: End time for integration (seconds).
+
+    Returns:
+        Energy in Joules.
+
+    Raises:
+        AnalysisError: If neither power nor both voltage and current provided.
+
+    Example:
+        >>> e = energy(power_trace)
+        >>> print(f"Total energy: {e*1e3:.2f} mJ")
+    """
+    if power is None:
+        if voltage is None or current is None:
+            raise AnalysisError("Either power trace or both voltage and current traces required")
+        power = instantaneous_power(voltage, current)
+
+    data = power.data
+    sample_period = power.metadata.time_base
+
+    # Apply time limits
+    if start_time is not None or end_time is not None:
+        time_vector = np.arange(len(data)) * sample_period
+        if start_time is not None:
+            mask = time_vector >= start_time
+        else:
+            mask = np.ones(len(data), dtype=bool)
+        if end_time is not None:
+            mask &= time_vector <= end_time
+        data = data[mask]
+
+    # Integrate using trapezoidal rule (scipy is stable across versions)
+    from scipy.integrate import trapezoid
+
+    return float(trapezoid(data, dx=sample_period))
+
+
+def power_statistics(
+    power: WaveformTrace | None = None,
+    *,
+    voltage: WaveformTrace | None = None,
+    current: WaveformTrace | None = None,
+) -> dict[str, float]:
+    """Calculate comprehensive power statistics.
+
+    Args:
+        power: Power trace.
+        voltage: Voltage trace (alternative).
+        current: Current trace (alternative).
+
+    Returns:
+        Dictionary with:
+        - average: Mean power
+        - rms: RMS power
+        - peak: Peak power (absolute)
+        - peak_positive: Maximum positive power
+        - peak_negative: Maximum negative power (regeneration)
+        - energy: Total energy
+        - min: Minimum power value
+        - std: Standard deviation
+
+    Raises:
+        AnalysisError: If neither power nor both voltage and current provided.
+
+    Example:
+        >>> stats = power_statistics(voltage=v, current=i)
+        >>> print(f"Average: {stats['average']:.2f} W")
+        >>> print(f"Peak: {stats['peak']:.2f} W")
+        >>> print(f"Energy: {stats['energy']*1e3:.2f} mJ")
+    """
+    if power is None:
+        if voltage is None or current is None:
+            raise AnalysisError("Either power trace or both voltage and current traces required")
+        power = instantaneous_power(voltage, current)
+
+    data = power.data
+    sample_period = power.metadata.time_base
+
+    # Use scipy trapezoid for stable API across NumPy versions
+    from scipy.integrate import trapezoid
+
+    return {
+        "average": float(np.mean(data)),
+        "rms": float(np.sqrt(np.mean(data**2))),
+        "peak": float(np.max(np.abs(data))),
+        "peak_positive": float(np.max(data)),
+        "peak_negative": float(np.min(data)),
+        "energy": float(trapezoid(data, dx=sample_period)),
+        "min": float(np.min(data)),
+        "std": float(np.std(data)),
+    }
+
+
+def power_profile(
+    voltage: WaveformTrace,
+    current: WaveformTrace,
+    *,
+    window_size: int | None = None,
+) -> dict[str, Any]:
+    """Generate power profile with rolling statistics.
+
+    Args:
+        voltage: Voltage trace.
+        current: Current trace.
+        window_size: Window size for rolling calculations. If None, auto-select.
+
+    Returns:
+        Dictionary with:
+        - power_trace: Instantaneous power trace
+        - rolling_avg: Rolling average power
+        - rolling_peak: Rolling peak power
+        - cumulative_energy: Cumulative energy over time
+        - statistics: Overall power statistics
+    """
+    power = instantaneous_power(voltage, current)
+    data = power.data
+    sample_period = power.metadata.time_base
+
+    if window_size is None:
+        # Auto-select: ~1% of total samples or 100, whichever is larger
+        window_size = max(100, len(data) // 100)
+
+    # Ensure window size is odd for centered window
+    if window_size % 2 == 0:
+        window_size += 1
+
+    # Rolling average
+    kernel = np.ones(window_size) / window_size
+    rolling_avg = np.convolve(data, kernel, mode="same")
+
+    # Rolling peak (using scipy.ndimage.maximum_filter would be faster but numpy-only)
+    from scipy.ndimage import maximum_filter1d
+
+    rolling_peak = maximum_filter1d(np.abs(data), size=window_size)
+
+    # Cumulative energy
+    cumulative_energy = np.cumsum(data) * sample_period
+
+    return {
+        "power_trace": power,
+        "rolling_avg": WaveformTrace(
+            data=rolling_avg.astype(np.float64),
+            metadata=power.metadata,
+        ),
+        "rolling_peak": WaveformTrace(
+            data=rolling_peak.astype(np.float64),
+            metadata=power.metadata,
+        ),
+        "cumulative_energy": WaveformTrace(
+            data=cumulative_energy.astype(np.float64),
+            metadata=power.metadata,
+        ),
+        "statistics": power_statistics(power),
+    }
+
+
+__all__ = [
+    "average_power",
+    "energy",
+    "instantaneous_power",
+    "peak_power",
+    "power_profile",
+    "power_statistics",
+    "rms_power",
+]

oscura/analyzers/power/conduction.py

@@ -0,0 +1,314 @@
+"""Conduction loss analysis for TraceKit.
+
+Provides conduction loss calculations for power semiconductor devices
+during their on-state.
+
+
+Example:
+    >>> from oscura.analyzers.power.conduction import conduction_loss
+    >>> p_cond = conduction_loss(v_on_trace, i_d_trace, duty_cycle=0.5)
+    >>> print(f"Conduction loss: {p_cond:.2f} W")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from oscura.core.exceptions import AnalysisError
+
+if TYPE_CHECKING:
+    from oscura.core.types import WaveformTrace
+
+
+def conduction_loss(
+    voltage: WaveformTrace,
+    current: WaveformTrace,
+    duty_cycle: float | None = None,
+) -> float:
+    """Calculate conduction loss during on-state.
+
+    P_cond = V_on * I_on * D (steady state)
+    or
+    P_cond = mean(V(t) * I(t)) over on-state periods
+
+    Args:
+        voltage: On-state voltage trace (V_ds(on) or V_ce(sat)).
+        current: On-state current trace.
+        duty_cycle: Duty cycle (0 to 1). If None, calculates from waveforms.
+
+    Returns:
+        Conduction loss in Watts.
+
+    Example:
+        >>> p_cond = conduction_loss(v_on, i_d, duty_cycle=0.5)
+        >>> print(f"Conduction loss: {p_cond:.2f} W")
+
+    References:
+        Infineon Application Note AN-9010
+    """
+    v_data = voltage.data
+    i_data = current.data
+
+    # Ensure same length
+    min_len = min(len(v_data), len(i_data))
+    v_data = v_data[:min_len]
+    i_data = i_data[:min_len]
+
+    if duty_cycle is not None:
+        # Use average values and duty cycle
+        v_on = float(np.mean(v_data))
+        i_on = float(np.mean(i_data))
+        return v_on * i_on * duty_cycle
+    else:
+        # Calculate instantaneous power and average
+        power = v_data * i_data
+        return float(np.mean(power))
+
+
+def on_resistance(
+    voltage: WaveformTrace,
+    current: WaveformTrace,
+    *,
+    min_current: float | None = None,
+    min_current_fraction: float = 0.1,
+) -> float:
+    """Calculate on-state resistance (R_ds(on) or R_ce(sat)).
+
+    R_on = V_on / I_on
+
+    Args:
+        voltage: On-state voltage trace.
+        current: On-state current trace.
+        min_current: Minimum current threshold (to avoid division by small values).
+            If None, uses min_current_fraction * peak current.
+        min_current_fraction: Fraction of peak current to use as minimum threshold
+            when min_current is None (default: 0.1 = 10% of peak).
+
+    Returns:
+        On-state resistance in Ohms.
+
+    Example:
+        >>> r_on = on_resistance(v_ds, i_d)
+        >>> print(f"R_ds(on): {r_on*1e3:.2f} mOhm")
+        >>> # With tighter threshold (5% of peak):
+        >>> r_on = on_resistance(v_ds, i_d, min_current_fraction=0.05)
+    """
+    v_data = voltage.data
+    i_data = current.data
+
+    min_len = min(len(v_data), len(i_data))
+    v_data = v_data[:min_len]
+    i_data = i_data[:min_len]
+
+    # Filter by minimum current
+    if min_current is None:
+        min_current = min_current_fraction * np.max(np.abs(i_data))
+
+    mask = np.abs(i_data) >= min_current
+    if not np.any(mask):
+        return np.nan  # type: ignore[no-any-return]
+
+    v_on = v_data[mask]
+    i_on = i_data[mask]
+
+    # Linear fit to get resistance
+    # V = I * R -> slope is R
+    coeffs = np.polyfit(i_on, v_on, 1)
+    return float(coeffs[0])
+
+
+def forward_voltage(
+    voltage: WaveformTrace,
+    current: WaveformTrace,
+    *,
+    current_threshold: float | None = None,
+    current_threshold_fraction: float = 0.1,
+    threshold_window: float = 0.1,
+) -> float:
+    """Calculate forward voltage drop (for diodes or IGBT V_ce(sat)).
+
+    Extracts the voltage at a reference current level.
+
+    Args:
+        voltage: Forward voltage trace.
+        current: Forward current trace.
+        current_threshold: Current level at which to measure Vf.
+            If None, uses current_threshold_fraction * peak current.
+        current_threshold_fraction: Fraction of peak current to use as threshold
+            when current_threshold is None (default: 0.1 = 10% of peak).
+        threshold_window: Tolerance window around the current threshold,
+            as a fraction of the threshold (default: 0.1 = +/-10% window).
+            Samples within this window are averaged to compute Vf.
+
+    Returns:
+        Forward voltage in Volts.
+
+    Example:
+        >>> vf = forward_voltage(v_f, i_f)
+        >>> print(f"Forward voltage: {vf:.2f} V")
+        >>> # With tighter window for more precise measurement:
+        >>> vf = forward_voltage(v_f, i_f, threshold_window=0.05)
+    """
+    v_data = voltage.data
+    i_data = current.data
+
+    min_len = min(len(v_data), len(i_data))
+    v_data = v_data[:min_len]
+    i_data = i_data[:min_len]
+
+    if current_threshold is None:
+        current_threshold = current_threshold_fraction * np.max(np.abs(i_data))
+
+    # Find samples near the current threshold
+    near_threshold = np.abs(i_data - current_threshold) < threshold_window * current_threshold
+    if not np.any(near_threshold):
+        # Interpolate
+        idx = np.argmin(np.abs(i_data - current_threshold))
+        return float(v_data[idx])
+
+    return float(np.mean(v_data[near_threshold]))
+
+
+def duty_cycle_weighted_loss(
+    losses: list[tuple[float, float]],
+) -> float:
+    """Calculate total loss from multiple operating points.
+
+    Useful for variable duty cycle or multi-mode operation.
+
+    Args:
+        losses: List of (loss_watts, duty_cycle) tuples.
+
+    Returns:
+        Total weighted average loss in Watts.
+
+    Raises:
+        AnalysisError: If total duty cycle exceeds 1.0
+
+    Example:
+        >>> # 10W at 30% duty, 5W at 50% duty
+        >>> total = duty_cycle_weighted_loss([(10, 0.3), (5, 0.5)])
+    """
+    total = 0.0
+    total_duty = 0.0
+
+    for loss, duty in losses:
+        total += loss * duty
+        total_duty += duty
+
+    if total_duty > 1.0:
+        raise AnalysisError(f"Total duty cycle exceeds 1.0: {total_duty}")
+
+    return total
+
+
+def temperature_derating(
+    r_on_25c: float,
+    temperature: float,
+    temp_coefficient: float = 0.004,
+) -> float:
+    """Calculate temperature-derated on-resistance.
+
+    R_on(T) = R_on(25C) * (1 + alpha * (T - 25))
+
+    Args:
+        r_on_25c: On-resistance at 25C in Ohms.
+        temperature: Operating temperature in Celsius.
+        temp_coefficient: Temperature coefficient (default 0.4%/C for Si MOSFET).
+
+    Returns:
+        Derated on-resistance in Ohms.
+
+    Example:
+        >>> r_on_100c = temperature_derating(0.010, 100)  # 10mOhm at 25C
+        >>> print(f"R_on at 100C: {r_on_100c*1e3:.2f} mOhm")
+    """
+    return r_on_25c * (1 + temp_coefficient * (temperature - 25))
+
+
+def mosfet_conduction_loss(
+    i_rms: float,
+    r_ds_on: float,
+    temperature: float = 25.0,
+    temp_coefficient: float = 0.004,
+) -> float:
+    """Calculate MOSFET conduction loss.
+
+    P_cond = I_rms^2 * R_ds(on)
+
+    Args:
+        i_rms: RMS drain current in Amps.
+        r_ds_on: On-state resistance at 25C in Ohms.
+        temperature: Junction temperature in Celsius.
+        temp_coefficient: Temperature coefficient.
+
+    Returns:
+        Conduction loss in Watts.
+
+    Example:
+        >>> p = mosfet_conduction_loss(i_rms=10, r_ds_on=0.010, temperature=100)
+    """
+    r_on = temperature_derating(r_ds_on, temperature, temp_coefficient)
+    return i_rms**2 * r_on
+
+
+def diode_conduction_loss(
+    i_avg: float,
+    i_rms: float,
+    v_f: float,
+    r_d: float = 0.0,
+) -> float:
+    """Calculate diode conduction loss.
+
+    P_cond = V_f * I_avg + r_d * I_rms^2
+
+    Args:
+        i_avg: Average forward current in Amps.
+        i_rms: RMS forward current in Amps.
+        v_f: Forward voltage drop in Volts.
+        r_d: Dynamic resistance in Ohms.
+
+    Returns:
+        Conduction loss in Watts.
+
+    Example:
+        >>> p = diode_conduction_loss(i_avg=5, i_rms=7, v_f=0.7, r_d=0.01)
+    """
+    return v_f * i_avg + r_d * i_rms**2
+
+
+def igbt_conduction_loss(
+    i_c: float,
+    v_ce_sat: float,
+    r_c: float = 0.0,
+) -> float:
+    """Calculate IGBT conduction loss.
+
+    P_cond = V_ce(sat) * I_c + r_c * I_c^2
+
+    Args:
+        i_c: Collector current in Amps.
+        v_ce_sat: Collector-emitter saturation voltage in Volts.
+        r_c: Collector resistance in Ohms.
+
+    Returns:
+        Conduction loss in Watts.
+
+    Example:
+        >>> p = igbt_conduction_loss(i_c=50, v_ce_sat=2.0, r_c=0.01)
+    """
+    return v_ce_sat * i_c + r_c * i_c**2
+
+
+__all__ = [
+    "conduction_loss",
+    "diode_conduction_loss",
+    "duty_cycle_weighted_loss",
+    "forward_voltage",
+    "igbt_conduction_loss",
+    "mosfet_conduction_loss",
+    "on_resistance",
+    "temperature_derating",
+]