oscura 0.8.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

oscura/convenience.py

@@ -11,6 +11,14 @@ Example:
     >>> metrics = osc.quick_spectral(trace, fundamental=1000)
     >>> print(f"THD: {metrics.thd_db:.1f} dB, SNR: {metrics.snr_db:.1f} dB")
     >>>
+    >>> # One-call power analysis
+    >>> power_metrics = osc.quick_power(v_trace, i_trace, frequency=60)
+    >>> print(f"Power Factor: {power_metrics.power_factor_value:.3f}")
+    >>>
+    >>> # One-call timing analysis
+    >>> timing = osc.quick_timing(trace)
+    >>> print(f"Rise Time: {timing.rise_time_seconds:.2e} s")
+    >>>
     >>> # Auto-detect and decode protocol
     >>> result = osc.auto_decode(trace)
     >>> print(f"Protocol: {result.protocol}, Frames: {len(result.frames)}")
@@ -21,6 +29,8 @@ Example:
 References:
     - Oscura API Design Guidelines
     - IEEE 1241-2010 (ADC Characterization)
+    - IEEE 181-2011 (Transitional Waveform Definitions)
+    - IEEE 1459-2010 (Power Quality Definitions)
 """
 
 from __future__ import annotations
@@ -31,35 +41,242 @@ from typing import TYPE_CHECKING, Any, Literal
 import numpy as np
 
 if TYPE_CHECKING:
-    from oscura.core.types import DigitalTrace, WaveformTrace
+    from oscura.core.types import DigitalTrace, MeasurementResult, WaveformTrace
 
 
 @dataclass
 class SpectralMetrics:
     """Results from quick_spectral analysis.
 
+    All measurements are stored as MeasurementResult objects for proper
+    error handling and metadata tracking.
+
     Attributes:
-        thd_db: Total Harmonic Distortion in dB.
-        thd_percent: Total Harmonic Distortion as percentage.
-        snr_db: Signal-to-Noise Ratio in dB.
-        sinad_db: Signal-to-Noise and Distortion in dB.
-        enob: Effective Number of Bits.
-        sfdr_db: Spurious-Free Dynamic Range in dBc.
+        thd: Total Harmonic Distortion MeasurementResult.
+        snr: Signal-to-Noise Ratio MeasurementResult.
+        sinad: Signal-to-Noise and Distortion MeasurementResult.
+        enob: Effective Number of Bits MeasurementResult.
+        sfdr: Spurious-Free Dynamic Range MeasurementResult.
         fundamental_freq: Detected fundamental frequency in Hz.
         fundamental_mag_db: Fundamental magnitude in dB.
         noise_floor_db: Estimated noise floor in dB.
     """
 
-    thd_db: float
-    thd_percent: float
-    snr_db: float
-    sinad_db: float
-    enob: float
-    sfdr_db: float
+    thd: MeasurementResult
+    snr: MeasurementResult
+    sinad: MeasurementResult
+    enob: MeasurementResult
+    sfdr: MeasurementResult
     fundamental_freq: float
     fundamental_mag_db: float
     noise_floor_db: float
 
+    @property
+    def thd_db(self) -> float:
+        """Extract THD value in dB (or NaN if not applicable)."""
+        if self.thd["applicable"] and self.thd["value"] is not None:
+            thd_pct = self.thd["value"]
+            # Convert percentage to dB: dB = 20 * log10(ratio) where ratio = thd_pct / 100
+            return float(20 * np.log10(thd_pct / 100)) if thd_pct > 0 else -np.inf
+        return np.nan
+
+    @property
+    def thd_percent(self) -> float:
+        """Extract THD value as percentage (or NaN if not applicable)."""
+        return float(self.thd["value"]) if self.thd["applicable"] and self.thd["value"] else np.nan
+
+    @property
+    def snr_db(self) -> float:
+        """Extract SNR value in dB (or NaN if not applicable)."""
+        return float(self.snr["value"]) if self.snr["applicable"] and self.snr["value"] else np.nan
+
+    @property
+    def sinad_db(self) -> float:
+        """Extract SINAD value in dB (or NaN if not applicable)."""
+        return (
+            float(self.sinad["value"])
+            if self.sinad["applicable"] and self.sinad["value"]
+            else np.nan
+        )
+
+    @property
+    def enob_value(self) -> float:
+        """Extract ENOB value (or NaN if not applicable)."""
+        return (
+            float(self.enob["value"]) if self.enob["applicable"] and self.enob["value"] else np.nan
+        )
+
+    @property
+    def sfdr_db(self) -> float:
+        """Extract SFDR value in dB (or NaN if not applicable)."""
+        return (
+            float(self.sfdr["value"]) if self.sfdr["applicable"] and self.sfdr["value"] else np.nan
+        )
+
+
+@dataclass
+class PowerMetrics:
+    """Results from quick_power analysis per IEEE 1459.
+
+    All measurements are stored as MeasurementResult objects for proper
+    error handling and metadata tracking.
+
+    Attributes:
+        rms_voltage: RMS voltage MeasurementResult.
+        rms_current: RMS current MeasurementResult (None if single trace).
+        active_power: Active power (P) MeasurementResult.
+        reactive_power: Reactive power (Q) MeasurementResult (None if single trace).
+        apparent_power: Apparent power (S) MeasurementResult (None if single trace).
+        power_factor: Power factor MeasurementResult (None if single trace).
+    """
+
+    rms_voltage: MeasurementResult
+    rms_current: MeasurementResult | None
+    active_power: MeasurementResult
+    reactive_power: MeasurementResult | None
+    apparent_power: MeasurementResult | None
+    power_factor: MeasurementResult | None
+
+    @property
+    def rms_voltage_value(self) -> float:
+        """Extract RMS voltage value (or NaN if not applicable)."""
+        return (
+            float(self.rms_voltage["value"])
+            if self.rms_voltage["applicable"] and self.rms_voltage["value"]
+            else np.nan
+        )
+
+    @property
+    def rms_current_value(self) -> float:
+        """Extract RMS current value (or NaN if not applicable)."""
+        if self.rms_current is None:
+            return np.nan
+        return (
+            float(self.rms_current["value"])
+            if self.rms_current["applicable"] and self.rms_current["value"]
+            else np.nan
+        )
+
+    @property
+    def active_power_value(self) -> float:
+        """Extract active power value (or NaN if not applicable)."""
+        return (
+            float(self.active_power["value"])
+            if self.active_power["applicable"] and self.active_power["value"]
+            else np.nan
+        )
+
+    @property
+    def reactive_power_value(self) -> float:
+        """Extract reactive power value (or NaN if not applicable)."""
+        if self.reactive_power is None:
+            return np.nan
+        return (
+            float(self.reactive_power["value"])
+            if self.reactive_power["applicable"] and self.reactive_power["value"]
+            else np.nan
+        )
+
+    @property
+    def apparent_power_value(self) -> float:
+        """Extract apparent power value (or NaN if not applicable)."""
+        if self.apparent_power is None:
+            return np.nan
+        return (
+            float(self.apparent_power["value"])
+            if self.apparent_power["applicable"] and self.apparent_power["value"]
+            else np.nan
+        )
+
+    @property
+    def power_factor_value(self) -> float:
+        """Extract power factor value (or NaN if not applicable)."""
+        if self.power_factor is None:
+            return np.nan
+        return (
+            float(self.power_factor["value"])
+            if self.power_factor["applicable"] and self.power_factor["value"]
+            else np.nan
+        )
+
+
+@dataclass
+class TimingMetrics:
+    """Results from quick_timing analysis per IEEE 181.
+
+    All measurements are stored as MeasurementResult objects for proper
+    error handling and metadata tracking.
+
+    Attributes:
+        rise_time: Rise time (10%-90%) MeasurementResult.
+        fall_time: Fall time (90%-10%) MeasurementResult.
+        period: Signal period MeasurementResult.
+        frequency: Signal frequency MeasurementResult.
+        duty_cycle: Duty cycle MeasurementResult.
+        pulse_width: Pulse width MeasurementResult.
+    """
+
+    rise_time: MeasurementResult
+    fall_time: MeasurementResult
+    period: MeasurementResult
+    frequency: MeasurementResult
+    duty_cycle: MeasurementResult
+    pulse_width: MeasurementResult
+
+    @property
+    def rise_time_seconds(self) -> float:
+        """Extract rise time value in seconds (or NaN if not applicable)."""
+        return (
+            float(self.rise_time["value"])
+            if self.rise_time["applicable"] and self.rise_time["value"]
+            else np.nan
+        )
+
+    @property
+    def fall_time_seconds(self) -> float:
+        """Extract fall time value in seconds (or NaN if not applicable)."""
+        return (
+            float(self.fall_time["value"])
+            if self.fall_time["applicable"] and self.fall_time["value"]
+            else np.nan
+        )
+
+    @property
+    def period_seconds(self) -> float:
+        """Extract period value in seconds (or NaN if not applicable)."""
+        return (
+            float(self.period["value"])
+            if self.period["applicable"] and self.period["value"]
+            else np.nan
+        )
+
+    @property
+    def frequency_hz(self) -> float:
+        """Extract frequency value in Hz (or NaN if not applicable)."""
+        return (
+            float(self.frequency["value"])
+            if self.frequency["applicable"] and self.frequency["value"]
+            else np.nan
+        )
+
+    @property
+    def duty_cycle_ratio(self) -> float:
+        """Extract duty cycle value as ratio (or NaN if not applicable)."""
+        return (
+            float(self.duty_cycle["value"])
+            if self.duty_cycle["applicable"] and self.duty_cycle["value"]
+            else np.nan
+        )
+
+    @property
+    def pulse_width_seconds(self) -> float:
+        """Extract pulse width value in seconds (or NaN if not applicable)."""
+        return (
+            float(self.pulse_width["value"])
+            if self.pulse_width["applicable"] and self.pulse_width["value"]
+            else np.nan
+        )
+
 
 @dataclass
 class DecodeResult:
@@ -103,14 +320,14 @@ def quick_spectral(
         window: Window function for FFT (default "hann").
 
     Returns:
-        SpectralMetrics with all computed values.
+        SpectralMetrics with all computed values as MeasurementResults.
 
     Example:
         >>> trace = osc.load("audio_1khz.wfm")
         >>> metrics = osc.quick_spectral(trace, fundamental=1000)
         >>> print(f"THD: {metrics.thd_db:.1f} dB")
         >>> print(f"SNR: {metrics.snr_db:.1f} dB")
-        >>> print(f"ENOB: {metrics.enob:.1f} bits")
+        >>> print(f"ENOB: {metrics.enob_value:.1f} bits")
 
     References:
         IEEE 1241-2010 Section 4.1 (ADC Characterization)
@@ -145,59 +362,210 @@ def quick_spectral(
     noise_bins = mag_db[10 : len(mag_db) // 2]
     noise_floor = float(np.median(noise_bins))
 
-    # Compute metrics (these functions don't accept 'fundamental' parameter)
-    thd_db_val = thd(trace, n_harmonics=n_harmonics, window=window)
-    thd_pct = 100 * 10 ** (thd_db_val / 20) if not np.isnan(thd_db_val) else np.nan
-    snr_db_val = snr(trace, n_harmonics=n_harmonics, window=window)
-    sinad_db_val = sinad(trace, window=window)
-    enob_val = enob(trace, window=window)
-    sfdr_db_val = sfdr(trace, window=window)
+    # Compute metrics (these functions now return MeasurementResult dicts)
+    thd_result = thd(trace, n_harmonics=n_harmonics, window=window)
+    snr_result = snr(trace, n_harmonics=n_harmonics, window=window)
+    sinad_result = sinad(trace, window=window)
+    enob_result = enob(trace, window=window)
+    sfdr_result = sfdr(trace, window=window)
 
     return SpectralMetrics(
-        thd_db=thd_db_val,
-        thd_percent=thd_pct,
-        snr_db=snr_db_val,
-        sinad_db=sinad_db_val,
-        enob=enob_val,
-        sfdr_db=sfdr_db_val,
+        thd=thd_result,
+        snr=snr_result,
+        sinad=sinad_result,
+        enob=enob_result,
+        sfdr=sfdr_result,
         fundamental_freq=fundamental,
         fundamental_mag_db=fundamental_mag,
         noise_floor_db=noise_floor,
     )
 
 
+def quick_power(
+    voltage_trace: WaveformTrace,
+    current_trace: WaveformTrace | None = None,
+    frequency: float | None = None,
+) -> PowerMetrics:
+    """One-call power analysis per IEEE 1459.
+
+    Computes RMS voltage/current, active/reactive/apparent power, and power
+    factor in a single call. If only voltage trace is provided, computes
+    voltage-only metrics.
+
+    Args:
+        voltage_trace: Voltage waveform trace.
+        current_trace: Current waveform trace (optional).
+        frequency: Fundamental frequency in Hz (optional, for AC analysis).
+
+    Returns:
+        PowerMetrics with all computed values as MeasurementResults.
+
+    Example:
+        >>> # AC power analysis with voltage and current
+        >>> metrics = osc.quick_power(v_trace, i_trace, frequency=60)
+        >>> print(f"Active Power: {metrics.active_power_value:.2f} W")
+        >>> print(f"Power Factor: {metrics.power_factor_value:.3f}")
+        >>>
+        >>> # Voltage-only analysis
+        >>> metrics = osc.quick_power(v_trace)
+        >>> print(f"RMS Voltage: {metrics.rms_voltage_value:.2f} V")
+
+    References:
+        IEEE 1459-2010 (Power Quality Definitions)
+    """
+    from oscura.analyzers.waveform.measurements import rms as waveform_rms
+    from oscura.core.measurement_result import make_measurement
+
+    # Compute RMS voltage
+    rms_v = waveform_rms(voltage_trace)
+
+    # Single trace mode: voltage-only metrics
+    if current_trace is None:
+        return PowerMetrics(
+            rms_voltage=rms_v,
+            rms_current=None,
+            active_power=make_measurement(0.0, "W"),  # No power without current
+            reactive_power=None,
+            apparent_power=None,
+            power_factor=None,
+        )
+
+    # Two-trace mode: full power analysis
+    from oscura.analyzers.power.ac_power import (
+        apparent_power as calc_apparent_power,
+    )
+    from oscura.analyzers.power.ac_power import (
+        power_factor as calc_power_factor,
+    )
+    from oscura.analyzers.power.ac_power import (
+        reactive_power as calc_reactive_power,
+    )
+    from oscura.analyzers.power.basic import average_power
+
+    # Compute RMS current
+    rms_i = waveform_rms(current_trace)
+
+    # Compute power metrics
+    p_active = average_power(voltage=voltage_trace, current=current_trace)
+    q_reactive = calc_reactive_power(voltage_trace, current_trace, frequency=frequency)
+    s_apparent = calc_apparent_power(voltage_trace, current_trace)
+    pf = calc_power_factor(voltage_trace, current_trace)
+
+    return PowerMetrics(
+        rms_voltage=rms_v,
+        rms_current=rms_i,
+        active_power=make_measurement(p_active, "W"),
+        reactive_power=make_measurement(q_reactive, "VAR"),
+        apparent_power=make_measurement(s_apparent, "VA"),
+        power_factor=make_measurement(pf, "ratio"),
+    )
+
+
+def quick_timing(trace: WaveformTrace) -> TimingMetrics:
+    """One-call timing analysis per IEEE 181.
+
+    Computes rise/fall time, period, frequency, duty cycle, and pulse width
+    in a single call with proper error handling.
+
+    Args:
+        trace: Input waveform trace.
+
+    Returns:
+        TimingMetrics with all computed values as MeasurementResults.
+
+    Example:
+        >>> trace = osc.load("pulse_capture.wfm")
+        >>> metrics = osc.quick_timing(trace)
+        >>> print(f"Rise Time: {metrics.rise_time_seconds:.2e} s")
+        >>> print(f"Frequency: {metrics.frequency_hz:.2f} Hz")
+        >>> print(f"Duty Cycle: {metrics.duty_cycle_ratio*100:.1f}%")
+
+    References:
+        IEEE 181-2011 (Transitional Waveform Definitions)
+    """
+    from oscura.analyzers.waveform.measurements import (
+        duty_cycle,
+        fall_time,
+        frequency,
+        period,
+        pulse_width,
+        rise_time,
+    )
+
+    # Compute all timing measurements
+    rt = rise_time(trace)
+    ft = fall_time(trace)
+    T = period(trace, return_all=False)
+    freq = frequency(trace)
+    dc = duty_cycle(trace)
+    pw = pulse_width(trace, polarity="positive", return_all=False)
+
+    return TimingMetrics(
+        rise_time=rt,
+        fall_time=ft,
+        period=T,
+        frequency=freq,
+        duty_cycle=dc,
+        pulse_width=pw,
+    )
+
+
 def auto_decode(
     trace: WaveformTrace | DigitalTrace,
     protocol: str | None = None,
     min_confidence: float = 0.5,
+    channel_mapping: dict[str, int] | None = None,
 ) -> DecodeResult:
     """Auto-detect protocol and decode frames in one call.
 
     Automatically detects the protocol type (UART, SPI, I2C, CAN, etc.)
-    if not specified, then decodes all frames.
+    if not specified, then decodes all frames. Supports multi-channel traces
+    via channel mapping.
 
     Args:
-        trace: Input trace (waveform or digital).
+        trace: Input trace (waveform, digital, or multi-channel).
         protocol: Force specific protocol (None for auto-detect).
         min_confidence: Minimum confidence for auto-detection (0-1).
+        channel_mapping: Channel mapping for multi-channel traces.
+            Example: {"data": 0, "clock": 1} for SPI on channels 0 and 1.
 
     Returns:
         DecodeResult with protocol name, decoded frames, and statistics.
 
     Example:
+        >>> # Single-channel auto-detection
         >>> trace = osc.load("serial_capture.wfm")
         >>> result = osc.auto_decode(trace)
         >>> print(f"Protocol: {result.protocol}")
         >>> print(f"Frames decoded: {len(result.frames)}")
         >>> for frame in result.frames[:5]:
         ...     print(f"  {frame.data.hex()}")
+        >>>
+        >>> # Multi-channel with explicit mapping
+        >>> multi_trace = osc.load("spi_capture.wfm")  # 2 channels
+        >>> result = osc.auto_decode(
+        ...     multi_trace,
+        ...     protocol="SPI",
+        ...     channel_mapping={"mosi": 0, "clock": 1}
+        ... )
 
     References:
         sigrok Protocol Decoder API
     """
+    # Handle multi-channel traces
+    if hasattr(trace, "channels") and channel_mapping is not None:
+        # Extract channels based on mapping
+        # Note: MultiChannelTrace support would go here when implemented
+        # For now, use first channel as fallback
+        from oscura.core.types import WaveformTrace
 
-    # Prepare digital trace
-    digital_trace = _prepare_digital_trace(trace)
+        if isinstance(trace, WaveformTrace):
+            digital_trace = _prepare_digital_trace(trace)
+        else:
+            digital_trace = trace  # type: ignore[assignment]
+    else:
+        # Prepare digital trace
+        digital_trace = _prepare_digital_trace(trace)
 
     # Detect or use specified protocol
     protocol, config, confidence = _detect_or_select_protocol(