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

oscura/analyzers/power/efficiency.py

@@ -0,0 +1,297 @@
+"""Power efficiency calculations for TraceKit.
+
+Provides efficiency calculations for power converters and systems.
+
+
+Example:
+    >>> from oscura.analyzers.power.efficiency import efficiency
+    >>> eta = efficiency(v_in, i_in, v_out, i_out)
+    >>> print(f"Efficiency: {eta*100:.1f}%")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from oscura.analyzers.power.basic import average_power, instantaneous_power
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    from oscura.core.types import WaveformTrace
+
+
+def efficiency(
+    v_in: WaveformTrace,
+    i_in: WaveformTrace,
+    v_out: WaveformTrace,
+    i_out: WaveformTrace,
+) -> float:
+    """Calculate power conversion efficiency.
+
+    eta = P_out / P_in * 100%
+
+    Args:
+        v_in: Input voltage trace.
+        i_in: Input current trace.
+        v_out: Output voltage trace.
+        i_out: Output current trace.
+
+    Returns:
+        Efficiency as a ratio (0 to 1).
+
+    Example:
+        >>> eta = efficiency(v_in, i_in, v_out, i_out)
+        >>> print(f"Efficiency: {eta*100:.1f}%")
+    """
+    p_in = average_power(voltage=v_in, current=i_in)
+    p_out = average_power(voltage=v_out, current=i_out)
+
+    if p_in <= 0:
+        return 0.0
+
+    return p_out / p_in
+
+
+def power_conversion_efficiency(
+    p_in: float,
+    p_out: float,
+) -> float:
+    """Calculate efficiency from power values.
+
+    Args:
+        p_in: Input power in Watts.
+        p_out: Output power in Watts.
+
+    Returns:
+        Efficiency as a ratio (0 to 1).
+
+    Example:
+        >>> eta = power_conversion_efficiency(p_in=100, p_out=90)
+        >>> print(f"Efficiency: {eta*100:.1f}%")
+    """
+    if p_in <= 0:
+        return 0.0
+    return p_out / p_in
+
+
+def multi_output_efficiency(
+    v_in: WaveformTrace,
+    i_in: WaveformTrace,
+    outputs: list[tuple[WaveformTrace, WaveformTrace]],
+) -> dict[str, float]:
+    """Calculate efficiency for multi-output power supply.
+
+    Args:
+        v_in: Input voltage trace.
+        i_in: Input current trace.
+        outputs: List of (v_out, i_out) trace tuples for each output.
+
+    Returns:
+        Dictionary with:
+        - total_efficiency: Overall efficiency
+        - output_N_efficiency: Per-output efficiency (contribution)
+        - output_N_power: Per-output power
+        - total_output_power: Sum of all output powers
+        - input_power: Input power
+        - losses: Power losses (P_in - P_out_total)
+
+    Example:
+        >>> outputs = [(v1, i1), (v2, i2), (v3, i3)]
+        >>> result = multi_output_efficiency(v_in, i_in, outputs)
+        >>> print(f"Total efficiency: {result['total_efficiency']*100:.1f}%")
+    """
+    p_in = average_power(voltage=v_in, current=i_in)
+
+    result = {
+        "input_power": p_in,
+    }
+
+    total_output = 0.0
+    for idx, (v_out, i_out) in enumerate(outputs):
+        p_out = average_power(voltage=v_out, current=i_out)
+        result[f"output_{idx + 1}_power"] = p_out
+        result[f"output_{idx + 1}_efficiency"] = p_out / p_in if p_in > 0 else 0.0
+        total_output += p_out
+
+    result["total_output_power"] = total_output
+    result["total_efficiency"] = total_output / p_in if p_in > 0 else 0.0
+    result["losses"] = p_in - total_output
+
+    return result
+
+
+def efficiency_vs_load(
+    v_in: WaveformTrace,
+    i_in: WaveformTrace,
+    v_out: WaveformTrace,
+    i_out: WaveformTrace,
+    *,
+    n_points: int = 100,
+) -> dict[str, NDArray[np.float64]]:
+    """Calculate efficiency across the load range.
+
+    Segments the waveforms and calculates efficiency at each load level.
+
+    Args:
+        v_in: Input voltage trace.
+        i_in: Input current trace.
+        v_out: Output voltage trace.
+        i_out: Output current trace.
+        n_points: Number of load points to evaluate.
+
+    Returns:
+        Dictionary with:
+        - load_percent: Load levels as percentage of max
+        - efficiency: Efficiency at each load level
+        - output_power: Output power at each load level
+        - input_power: Input power at each load level
+
+    Example:
+        >>> result = efficiency_vs_load(v_in, i_in, v_out, i_out)
+        >>> plt.plot(result['load_percent'], result['efficiency'] * 100)
+    """
+    # Calculate instantaneous power
+    p_out_trace = instantaneous_power(v_out, i_out)
+    p_in_trace = instantaneous_power(v_in, i_in)
+
+    p_out_data = p_out_trace.data
+    p_in_data = p_in_trace.data[: len(p_out_data)]
+
+    # Sort by output power to get load curve
+    sort_idx = np.argsort(p_out_data)
+    p_out_sorted = p_out_data[sort_idx]
+    p_in_sorted = p_in_data[sort_idx]
+
+    # Divide into bins
+    bin_size = len(p_out_sorted) // n_points
+    bin_size = max(bin_size, 1)
+
+    load_pct = []
+    efficiency_vals = []
+    p_out_vals = []
+    p_in_vals = []
+
+    max_p_out = np.max(p_out_data)
+
+    for i in range(0, len(p_out_sorted), bin_size):
+        bin_p_out = np.mean(p_out_sorted[i : i + bin_size])
+        bin_p_in = np.mean(p_in_sorted[i : i + bin_size])
+
+        load_pct.append(bin_p_out / max_p_out * 100 if max_p_out > 0 else 0)
+        p_out_vals.append(bin_p_out)
+        p_in_vals.append(bin_p_in)
+        efficiency_vals.append(bin_p_out / bin_p_in if bin_p_in > 0 else 0)
+
+    return {
+        "load_percent": np.array(load_pct),
+        "efficiency": np.array(efficiency_vals),
+        "output_power": np.array(p_out_vals),
+        "input_power": np.array(p_in_vals),
+    }
+
+
+def loss_breakdown(
+    v_in: WaveformTrace,
+    i_in: WaveformTrace,
+    v_out: WaveformTrace,
+    i_out: WaveformTrace,
+    *,
+    switching_loss: float = 0.0,
+    conduction_loss: float = 0.0,
+    magnetic_loss: float = 0.0,
+    gate_drive_loss: float = 0.0,
+) -> dict[str, float]:
+    """Break down power losses by category.
+
+    Args:
+        v_in: Input voltage trace.
+        i_in: Input current trace.
+        v_out: Output voltage trace.
+        i_out: Output current trace.
+        switching_loss: Known switching losses in Watts.
+        conduction_loss: Known conduction losses in Watts.
+        magnetic_loss: Known magnetic (core/copper) losses in Watts.
+        gate_drive_loss: Known gate drive losses in Watts.
+
+    Returns:
+        Dictionary with loss breakdown.
+
+    Example:
+        >>> result = loss_breakdown(v_in, i_in, v_out, i_out,
+        ...     switching_loss=2.0, conduction_loss=1.5, magnetic_loss=0.5)
+        >>> print(f"Other losses: {result['other_loss']:.2f} W")
+    """
+    p_in = average_power(voltage=v_in, current=i_in)
+    p_out = average_power(voltage=v_out, current=i_out)
+    total_loss = p_in - p_out
+
+    known_losses = switching_loss + conduction_loss + magnetic_loss + gate_drive_loss
+    other_loss = total_loss - known_losses
+
+    eta = p_out / p_in if p_in > 0 else 0.0
+
+    return {
+        "input_power": p_in,
+        "output_power": p_out,
+        "efficiency": eta,
+        "total_loss": total_loss,
+        "switching_loss": switching_loss,
+        "conduction_loss": conduction_loss,
+        "magnetic_loss": magnetic_loss,
+        "gate_drive_loss": gate_drive_loss,
+        "other_loss": max(0, other_loss),  # Clamp to non-negative
+        "switching_loss_percent": switching_loss / total_loss * 100 if total_loss > 0 else 0,
+        "conduction_loss_percent": conduction_loss / total_loss * 100 if total_loss > 0 else 0,
+        "magnetic_loss_percent": magnetic_loss / total_loss * 100 if total_loss > 0 else 0,
+    }
+
+
+def thermal_efficiency(
+    p_in: float,
+    p_out: float,
+    ambient_temp: float,
+    case_temp: float,
+    thermal_resistance: float,
+) -> dict[str, float]:
+    """Calculate thermal-related efficiency metrics.
+
+    Args:
+        p_in: Input power in Watts.
+        p_out: Output power in Watts.
+        ambient_temp: Ambient temperature in Celsius.
+        case_temp: Case/junction temperature in Celsius.
+        thermal_resistance: Thermal resistance (Rth_j-a) in C/W.
+
+    Returns:
+        Dictionary with thermal analysis.
+
+    Example:
+        >>> result = thermal_efficiency(100, 90, 25, 65, 2.5)
+        >>> print(f"Estimated losses: {result['estimated_losses']:.1f} W")
+    """
+    losses = p_in - p_out
+    eta = p_out / p_in if p_in > 0 else 0.0
+
+    # Estimate losses from thermal measurement
+    thermal_losses = (case_temp - ambient_temp) / thermal_resistance
+
+    return {
+        "efficiency": eta,
+        "electrical_losses": losses,
+        "thermal_estimated_losses": thermal_losses,
+        "temperature_rise": case_temp - ambient_temp,
+        "loss_discrepancy": abs(losses - thermal_losses),
+    }
+
+
+__all__ = [
+    "efficiency",
+    "efficiency_vs_load",
+    "loss_breakdown",
+    "multi_output_efficiency",
+    "power_conversion_efficiency",
+    "thermal_efficiency",
+]

oscura/analyzers/power/ripple.py

@@ -0,0 +1,356 @@
+"""Ripple measurement for TraceKit.
+
+Provides AC ripple analysis for DC power supply outputs.
+
+
+Example:
+    >>> from oscura.analyzers.power.ripple import ripple, ripple_statistics
+    >>> r_pp, r_rms = ripple(dc_output_trace)
+    >>> print(f"Ripple: {r_pp*1e3:.2f} mV pp, {r_rms*1e3:.2f} mV rms")
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import signal
+
+from oscura.core.exceptions import AnalysisError
+from oscura.core.types import WaveformTrace
+
+
+def ripple(
+    trace: WaveformTrace,
+    *,
+    dc_coupling: bool = False,
+) -> tuple[float, float]:
+    """Measure AC ripple on a DC signal.
+
+    Isolates the AC component from the DC offset and measures
+    peak-to-peak and RMS ripple.
+
+    Args:
+        trace: DC voltage/current waveform with AC ripple.
+        dc_coupling: If True, include DC component in measurement.
+                    If False (default), remove DC for pure AC ripple.
+
+    Returns:
+        Tuple of (ripple_pp, ripple_rms) in signal units.
+
+    Example:
+        >>> vpp, vrms = ripple(output_voltage)
+        >>> print(f"Ripple: {vpp*1e3:.2f} mV pp, {vrms*1e3:.2f} mV rms")
+
+    References:
+        IEC 61000-4-7 (power quality)
+    """
+    data = trace.data
+
+    if dc_coupling:
+        ac_component = data
+    else:
+        # Remove DC (mean)
+        ac_component = data - np.mean(data)
+
+    ripple_pp = float(np.max(ac_component) - np.min(ac_component))
+    ripple_rms = float(np.sqrt(np.mean(ac_component**2)))
+
+    return ripple_pp, ripple_rms
+
+
+def ripple_percentage(
+    trace: WaveformTrace,
+) -> tuple[float, float]:
+    """Measure ripple as percentage of DC level.
+
+    Args:
+        trace: DC voltage/current waveform with AC ripple.
+
+    Returns:
+        Tuple of (ripple_pp_percent, ripple_rms_percent).
+
+    Example:
+        >>> pp_pct, rms_pct = ripple_percentage(output_voltage)
+        >>> print(f"Ripple: {pp_pct:.2f}% pp, {rms_pct:.2f}% rms")
+    """
+    dc_level = float(np.mean(trace.data))
+
+    if dc_level == 0:
+        return np.nan, np.nan
+
+    r_pp, r_rms = ripple(trace)
+
+    return (r_pp / dc_level * 100, r_rms / dc_level * 100)
+
+
+def ripple_frequency(
+    trace: WaveformTrace,
+    *,
+    min_frequency: float | None = None,
+    max_frequency: float | None = None,
+) -> float:
+    """Find dominant ripple frequency.
+
+    Args:
+        trace: DC voltage waveform with AC ripple.
+        min_frequency: Minimum frequency to consider (Hz).
+        max_frequency: Maximum frequency to consider (Hz).
+
+    Returns:
+        Dominant ripple frequency in Hz.
+
+    Example:
+        >>> f_ripple = ripple_frequency(output_voltage)
+        >>> print(f"Ripple frequency: {f_ripple/1e3:.2f} kHz")
+    """
+    data = trace.data
+    sample_rate = trace.metadata.sample_rate
+
+    # Remove DC
+    ac_data = data - np.mean(data)
+
+    # FFT
+    n = len(ac_data)
+    fft_result = np.abs(np.fft.rfft(ac_data))
+    freqs = np.fft.rfftfreq(n, 1 / sample_rate)
+
+    # Apply frequency limits
+    freq_mask = np.ones(len(freqs), dtype=bool)
+    if min_frequency is not None:
+        freq_mask &= freqs >= min_frequency
+    if max_frequency is not None:
+        freq_mask &= freqs <= max_frequency
+
+    # Exclude DC
+    freq_mask[0] = False
+
+    if not np.any(freq_mask):
+        return 0.0
+
+    # Find peak
+    masked_fft = fft_result.copy()
+    masked_fft[~freq_mask] = 0
+    peak_idx = np.argmax(masked_fft)
+
+    return float(freqs[peak_idx])
+
+
+def ripple_harmonics(
+    trace: WaveformTrace,
+    fundamental_freq: float | None = None,
+    n_harmonics: int = 10,
+) -> dict[int, float]:
+    """Analyze ripple harmonics.
+
+    Args:
+        trace: DC voltage waveform with AC ripple.
+        fundamental_freq: Fundamental ripple frequency. If None, auto-detect.
+        n_harmonics: Number of harmonics to analyze.
+
+    Returns:
+        Dictionary mapping harmonic number to amplitude.
+
+    Example:
+        >>> harmonics = ripple_harmonics(output_voltage)
+        >>> for h, amp in harmonics.items():
+        ...     print(f"H{h}: {amp*1e3:.2f} mV")
+    """
+    data = trace.data
+    sample_rate = trace.metadata.sample_rate
+
+    # Remove DC
+    ac_data = data - np.mean(data)
+
+    # Find fundamental if not provided
+    if fundamental_freq is None:
+        fundamental_freq = ripple_frequency(trace)
+
+    if fundamental_freq <= 0:
+        return {}
+
+    # FFT
+    n = len(ac_data)
+    fft_result = np.abs(np.fft.rfft(ac_data)) * 2 / n  # Scale for amplitude
+    freqs = np.fft.rfftfreq(n, 1 / sample_rate)
+
+    harmonics = {}
+    for h in range(1, n_harmonics + 1):
+        target_freq = h * fundamental_freq
+        # Find closest bin
+        idx = np.argmin(np.abs(freqs - target_freq))
+        if idx < len(fft_result):
+            harmonics[h] = float(fft_result[idx])
+
+    return harmonics
+
+
+def ripple_statistics(
+    trace: WaveformTrace,
+) -> dict[str, float]:
+    """Calculate comprehensive ripple statistics.
+
+    Args:
+        trace: DC voltage waveform with AC ripple.
+
+    Returns:
+        Dictionary with:
+        - dc_level: DC (mean) level
+        - ripple_pp: Peak-to-peak ripple
+        - ripple_rms: RMS ripple
+        - ripple_pp_percent: Peak-to-peak as % of DC
+        - ripple_rms_percent: RMS as % of DC
+        - ripple_frequency: Dominant ripple frequency
+        - crest_factor: Ripple peak / ripple RMS
+
+    Example:
+        >>> stats = ripple_statistics(output_voltage)
+        >>> print(f"DC: {stats['dc_level']:.2f} V")
+        >>> print(f"Ripple: {stats['ripple_pp']*1e3:.2f} mV pp")
+    """
+    data = trace.data
+    dc_level = float(np.mean(data))
+    ac_data = data - dc_level
+
+    r_pp = float(np.max(ac_data) - np.min(ac_data))
+    r_rms = float(np.sqrt(np.mean(ac_data**2)))
+    r_peak = float(np.max(np.abs(ac_data)))
+
+    crest_factor = r_peak / r_rms if r_rms > 0 else 0.0
+
+    if dc_level != 0:
+        r_pp_pct = r_pp / dc_level * 100
+        r_rms_pct = r_rms / dc_level * 100
+    else:
+        r_pp_pct = np.nan
+        r_rms_pct = np.nan
+
+    return {
+        "dc_level": dc_level,
+        "ripple_pp": r_pp,
+        "ripple_rms": r_rms,
+        "ripple_pp_percent": r_pp_pct,
+        "ripple_rms_percent": r_rms_pct,
+        "ripple_frequency": ripple_frequency(trace),
+        "crest_factor": crest_factor,
+    }
+
+
+def extract_ripple(
+    trace: WaveformTrace,
+    *,
+    high_pass_freq: float | None = None,
+    filter_order: int = 4,
+) -> WaveformTrace:
+    """Extract AC ripple component from DC signal.
+
+    Args:
+        trace: DC voltage waveform with AC ripple.
+        high_pass_freq: High-pass filter cutoff. If None, uses simple DC removal.
+        filter_order: Order of the Butterworth high-pass filter (default: 4).
+            Higher orders give sharper cutoff but more phase distortion.
+
+    Returns:
+        Waveform trace containing only the AC ripple component.
+
+    Raises:
+        AnalysisError: If high_pass_freq exceeds Nyquist frequency
+
+    Example:
+        >>> ac_ripple = extract_ripple(output_voltage)
+        >>> # Now analyze or plot just the ripple
+        >>> # With custom filter order for sharper cutoff:
+        >>> ac_ripple = extract_ripple(output_voltage, high_pass_freq=10, filter_order=6)
+    """
+    data = trace.data
+    sample_rate = trace.metadata.sample_rate
+
+    if high_pass_freq is not None:
+        # Use high-pass filter
+        nyquist = sample_rate / 2
+        if high_pass_freq >= nyquist:
+            raise AnalysisError(
+                f"High-pass frequency {high_pass_freq} Hz must be less than "
+                f"Nyquist frequency {nyquist} Hz"
+            )
+
+        sos = signal.butter(filter_order, high_pass_freq / nyquist, btype="high", output="sos")
+        ac_data = signal.sosfiltfilt(sos, data)
+    else:
+        # Simple DC removal
+        ac_data = data - np.mean(data)
+
+    return WaveformTrace(
+        data=ac_data.astype(np.float64),
+        metadata=trace.metadata,
+    )
+
+
+def ripple_envelope(
+    trace: WaveformTrace,
+    *,
+    method: str = "hilbert",
+    peak_window_size: int | None = None,
+) -> WaveformTrace:
+    """Extract ripple envelope (for amplitude modulation analysis).
+
+    Args:
+        trace: DC voltage waveform with AC ripple.
+        method: Envelope detection method ("hilbert" or "peak").
+        peak_window_size: Window size for peak envelope detection (samples).
+            If None, defaults to a size that covers approximately one ripple period.
+            Only used when method="peak".
+
+    Returns:
+        Waveform trace containing the ripple envelope.
+
+    Raises:
+        AnalysisError: If unknown envelope method specified
+
+    Example:
+        >>> envelope = ripple_envelope(output_voltage)
+        >>> # Analyze envelope for beat frequencies, etc.
+        >>> # With custom peak window size:
+        >>> envelope = ripple_envelope(output_voltage, method="peak", peak_window_size=200)
+    """
+    # First extract AC component
+    ac_trace = extract_ripple(trace)
+    ac_data = ac_trace.data
+
+    if method == "hilbert":
+        analytic_signal = signal.hilbert(ac_data)
+        envelope = np.abs(analytic_signal)
+    elif method == "peak":
+        # Simple peak detection
+        from scipy.ndimage import maximum_filter1d
+
+        # Determine window size
+        if peak_window_size is None:
+            # Default: scale to signal frequency if possible
+            # Try to detect ripple frequency and use ~1 period
+            ripple_freq = ripple_frequency(trace)
+            sample_rate = trace.metadata.sample_rate
+            if ripple_freq > 0:
+                # Use approximately one period of the ripple
+                peak_window_size = max(10, int(sample_rate / ripple_freq))
+            else:
+                # Fallback: use 1% of signal length, min 10, max 1000
+                peak_window_size = max(10, min(1000, len(ac_data) // 100))
+
+        envelope = maximum_filter1d(np.abs(ac_data), size=peak_window_size)
+    else:
+        raise AnalysisError(f"Unknown envelope method: {method}")
+
+    return WaveformTrace(
+        data=envelope.astype(np.float64),
+        metadata=trace.metadata,
+    )
+
+
+__all__ = [
+    "extract_ripple",
+    "ripple",
+    "ripple_envelope",
+    "ripple_frequency",
+    "ripple_harmonics",
+    "ripple_percentage",
+    "ripple_statistics",
+]