oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/workflows/compliance.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Literal
 
 import numpy as np
+from numpy.typing import NDArray
 
 from oscura.core.exceptions import AnalysisError
 
@@ -69,19 +70,6 @@ def emc_compliance_test(
         - limit_freq: Frequency array for limit mask
         - limit_mag: Magnitude array for limit mask
 
-    Returns:
-        Dictionary containing:
-        - status: 'PASS' or 'FAIL'
-        - standard: Standard tested against
-        - violations: List of frequency violations
-        - margin_to_limit: Minimum margin in dB (negative if failing)
-        - worst_frequency: Frequency with worst margin
-        - worst_margin: Worst margin value in dB
-        - spectrum_freq: Frequency array for spectrum
-        - spectrum_mag: Magnitude array for spectrum (dBµV or dBm)
-        - limit_freq: Frequency array for limit mask
-        - limit_mag: Magnitude array for limit mask
-
     Example:
         >>> trace = osc.load('radiated_emissions.wfm')
         >>> result = osc.emc_compliance_test(trace, standard='FCC_Part15_ClassB')
@@ -95,65 +83,33 @@ def emc_compliance_test(
         CISPR 22/32 (Information Technology Equipment EMC)
         MIL-STD-461G (Military EMC Requirements)
     """
-    # Import spectral analysis
     from oscura.analyzers.waveform.spectral import fft
 
-    # Calculate spectrum
+    # Calculate spectrum and convert to dBµV
     freq, mag_db = fft(trace)  # type: ignore[misc]
-    # Note: fft() returns magnitude_db (already in dB relative to 1V)
-
-    # Convert to dBµV (typical EMC unit)
-    # mag_db is in dBV, convert to dBµV: dBµV = dBV + 120
-    # (since 1µV = 1e-6 V, and 20*log10(1e6) = 120 dB)
-    spectrum_dbuv = mag_db + 120
+    spectrum_dbuv = mag_db + 120  # Convert dBV to dBµV
 
-    # Load limit mask for standard
+    # Load limit and apply frequency range
     limit_freq, limit_mag = _load_emc_mask(standard)
+    freq, spectrum_dbuv = _apply_frequency_range(freq, spectrum_dbuv, frequency_range)
 
-    # Apply frequency range if specified
-    if frequency_range is not None:
-        f_min, f_max = frequency_range
-        mask = (freq >= f_min) & (freq <= f_max)
-        freq = freq[mask]
-        spectrum_dbuv = spectrum_dbuv[mask]
-
-    # Interpolate limit to spectrum frequencies
+    # Check compliance
     limit_interp = np.interp(freq, limit_freq, limit_mag)
-
-    # Find violations (spectrum exceeds limit)
     margin = limit_interp - spectrum_dbuv
-    violations_mask = margin < 0
-
-    # Build violations list
-    violations = []
-    if np.any(violations_mask):
-        violation_indices = np.where(violations_mask)[0]
-        for idx in violation_indices:
-            violations.append(
-                {
-                    "frequency": freq[idx],
-                    "measured_dbuv": spectrum_dbuv[idx],
-                    "limit_dbuv": limit_interp[idx],
-                    "excess_db": -margin[idx],  # Positive value for excess
-                }
-            )
-
-    # Overall status
+    violations = _build_violations_list(freq, spectrum_dbuv, limit_interp, margin)
     status = "FAIL" if violations else "PASS"
 
     # Margin analysis
     margin_to_limit = np.min(margin)
     worst_idx = np.argmin(margin)
-    worst_frequency = freq[worst_idx]
-    worst_margin = margin[worst_idx]
 
     result = {
         "status": status,
         "standard": standard,
         "violations": violations,
         "margin_to_limit": margin_to_limit,
-        "worst_frequency": worst_frequency,
-        "worst_margin": worst_margin,
+        "worst_frequency": freq[worst_idx],
+        "worst_margin": margin[worst_idx],
         "spectrum_freq": freq,
         "spectrum_mag": spectrum_dbuv,
         "limit_freq": limit_freq,
@@ -161,13 +117,47 @@ def emc_compliance_test(
         "detector": detector,
     }
 
-    # Generate report if requested
     if report is not None:
         _generate_compliance_report(result, report)
 
     return result
 
 
+def _apply_frequency_range(
+    freq: NDArray[Any],
+    spectrum: NDArray[Any],
+    frequency_range: tuple[float, float] | None,
+) -> tuple[NDArray[Any], NDArray[Any]]:
+    """Apply frequency range filter if specified."""
+    if frequency_range is not None:
+        f_min, f_max = frequency_range
+        mask = (freq >= f_min) & (freq <= f_max)
+        return freq[mask], spectrum[mask]
+    return freq, spectrum
+
+
+def _build_violations_list(
+    freq: NDArray[Any],
+    spectrum_dbuv: NDArray[Any],
+    limit_interp: NDArray[Any],
+    margin: NDArray[Any],
+) -> list[dict[str, float]]:
+    """Build list of compliance violations."""
+    violations = []
+    violations_mask = margin < 0
+    if np.any(violations_mask):
+        for idx in np.where(violations_mask)[0]:
+            violations.append(
+                {
+                    "frequency": freq[idx],
+                    "measured_dbuv": spectrum_dbuv[idx],
+                    "limit_dbuv": limit_interp[idx],
+                    "excess_db": -margin[idx],
+                }
+            )
+    return violations
+
+
 def _load_emc_mask(
     standard: str,
 ) -> tuple[np.ndarray[Any, np.dtype[np.float64]], np.ndarray[Any, np.dtype[np.float64]]]:

oscura/workflows/digital.py

@@ -85,17 +85,67 @@ def characterize_buffer(
         IEEE 181-2011 Section 5.2 (Edge timing)
         JEDEC Standard No. 65B (Logic family specifications)
     """
-    # Import here to avoid circular dependencies
-    from oscura.analyzers.waveform.measurements import (
-        fall_time,
-        overshoot,
-        rise_time,
-        undershoot,
+    # Detect or use specified logic family
+    logic_family, confidence, voh, vol = _determine_logic_family(trace, logic_family)
+
+    # Measure timing parameters
+    t_rise, t_fall = _measure_timing_params(trace)
+
+    # Measure voltage overshoots
+    v_overshoot, v_undershoot, overshoot_pct, undershoot_pct = _measure_overshoots(trace, voh, vol)
+
+    # Calculate noise margins
+    logic_specs = _get_logic_specs(logic_family)
+    noise_margin_high = voh - logic_specs["vih"]
+    noise_margin_low = logic_specs["vil"] - vol
+
+    # Measure propagation delay if reference provided
+    propagation_delay = _measure_propagation_delay(reference_trace, trace)
+
+    # Determine pass/fail status
+    status = _evaluate_pass_fail(t_rise, t_fall, overshoot_pct, thresholds, logic_specs)
+
+    # Build result dictionary
+    result = _build_result_dict(
+        logic_family,
+        confidence,
+        t_rise,
+        t_fall,
+        propagation_delay,
+        v_overshoot,
+        overshoot_pct,
+        v_undershoot,
+        undershoot_pct,
+        noise_margin_high,
+        noise_margin_low,
+        voh,
+        vol,
+        status,
+        reference_trace,
     )
-    from oscura.inference.logic import detect_logic_family
 
-    # Auto-detect logic family if not specified
+    # Generate report if requested
+    if report is not None:
+        _generate_buffer_report(result, report)
+
+    return result
+
+
+def _determine_logic_family(
+    trace: WaveformTrace, logic_family: str | None
+) -> tuple[str, float, float, float]:
+    """Determine logic family and voltage levels.
+
+    Args:
+        trace: Input waveform trace.
+        logic_family: Optional logic family override.
+
+    Returns:
+        Tuple of (logic_family, confidence, voh, vol).
+    """
     if logic_family is None:
+        from oscura.inference.logic import detect_logic_family
+
         detection = detect_logic_family(trace)
         logic_family = detection["primary"]["name"]
         confidence = detection["primary"]["confidence"]
@@ -103,67 +153,167 @@ def characterize_buffer(
         vol = detection["primary"]["vol"]
     else:
         confidence = 1.0
-        # Measure VOH/VOL from trace
         voh = np.percentile(trace.data, 95)
         vol = np.percentile(trace.data, 5)
 
-    # Measure timing parameters
+    return logic_family, confidence, voh, vol
+
+
+def _measure_timing_params(trace: WaveformTrace) -> tuple[float, float]:
+    """Measure rise and fall times.
+
+    Args:
+        trace: Input waveform trace.
+
+    Returns:
+        Tuple of (rise_time, fall_time).
+
+    Raises:
+        AnalysisError: If measurement fails.
+    """
+    from oscura.analyzers.waveform.measurements import fall_time, rise_time
+
     try:
-        t_rise = rise_time(trace)
-        t_fall = fall_time(trace)
+        t_rise_raw = rise_time(trace)
+        t_fall_raw = fall_time(trace)
+        t_rise: float = float(t_rise_raw)
+        t_fall: float = float(t_fall_raw)
     except Exception as e:
         raise AnalysisError(f"Failed to measure rise/fall time: {e}") from e
 
-    # Measure overshoot/undershoot
-    v_overshoot = overshoot(trace)
-    v_undershoot = undershoot(trace)
+    return t_rise, t_fall
+
+
+def _measure_overshoots(
+    trace: WaveformTrace, voh: float, vol: float
+) -> tuple[float, float, float, float]:
+    """Measure voltage overshoots and undershoots.
+
+    Args:
+        trace: Input waveform trace.
+        voh: High voltage level.
+        vol: Low voltage level.
+
+    Returns:
+        Tuple of (v_overshoot, v_undershoot, overshoot_pct, undershoot_pct).
+    """
+    from oscura.analyzers.waveform.measurements import overshoot, undershoot
+
+    v_overshoot_raw = overshoot(trace)
+    v_undershoot_raw = undershoot(trace)
+    v_overshoot: float = float(v_overshoot_raw)
+    v_undershoot: float = float(v_undershoot_raw)
 
-    # Calculate percentages
     swing = voh - vol
     if swing > 0:
-        overshoot_pct = (v_overshoot / swing) * 100.0
-        undershoot_pct = (v_undershoot / swing) * 100.0
+        overshoot_pct: float = (v_overshoot / swing) * 100.0
+        undershoot_pct: float = (v_undershoot / swing) * 100.0
     else:
         overshoot_pct = 0.0
         undershoot_pct = 0.0
 
-    # Calculate noise margins (simplified - uses typical values)
-    # In a real implementation, these would come from LOGIC_FAMILIES constants
-    logic_specs = _get_logic_specs(logic_family)
-    noise_margin_high = voh - logic_specs["vih"]
-    noise_margin_low = logic_specs["vil"] - vol
+    return v_overshoot, v_undershoot, overshoot_pct, undershoot_pct
+
+
+def _measure_propagation_delay(
+    reference_trace: WaveformTrace | None, trace: WaveformTrace
+) -> float | None:
+    """Measure propagation delay if reference trace provided.
+
+    Args:
+        reference_trace: Optional reference trace.
+        trace: Output trace.
+
+    Returns:
+        Propagation delay in seconds, or None if not measurable.
+    """
+    if reference_trace is None:
+        return None
+
+    try:
+        from oscura.analyzers.digital.timing import propagation_delay as prop_delay
+
+        delay_raw = prop_delay(reference_trace, trace)
+        delay: float = float(delay_raw)
+        return delay
+    except Exception:
+        return None
+
 
-    # Propagation delay if reference provided
-    propagation_delay = None
-    timing_drift = None
-    if reference_trace is not None:
-        try:
-            from oscura.analyzers.digital.timing import (
-                propagation_delay as prop_delay,
-            )
-
-            propagation_delay = prop_delay(reference_trace, trace)
-        except Exception:
-            # If propagation delay measurement fails, set to None
-            propagation_delay = None
-
-    # Apply thresholds and determine pass/fail
-    status = "PASS"
+def _evaluate_pass_fail(
+    t_rise: float,
+    t_fall: float,
+    overshoot_pct: float,
+    thresholds: dict[str, float] | None,
+    logic_specs: dict[str, float],
+) -> str:
+    """Evaluate pass/fail status based on thresholds.
+
+    Args:
+        t_rise: Rise time measurement.
+        t_fall: Fall time measurement.
+        overshoot_pct: Overshoot percentage.
+        thresholds: Optional custom thresholds.
+        logic_specs: Logic family specifications.
+
+    Returns:
+        "PASS" or "FAIL" status string.
+    """
     if thresholds is not None:
         if "rise_time" in thresholds and t_rise > thresholds["rise_time"]:
-            status = "FAIL"
+            return "FAIL"
         if "fall_time" in thresholds and t_fall > thresholds["fall_time"]:
-            status = "FAIL"
+            return "FAIL"
         if "overshoot_percent" in thresholds and overshoot_pct > thresholds["overshoot_percent"]:
-            status = "FAIL"
+            return "FAIL"
     else:
-        # Use logic family defaults
         if t_rise > logic_specs.get("max_rise_time", float("inf")):
-            status = "FAIL"
+            return "FAIL"
         if t_fall > logic_specs.get("max_fall_time", float("inf")):
-            status = "FAIL"
+            return "FAIL"
+
+    return "PASS"
+
+
+def _build_result_dict(
+    logic_family: str,
+    confidence: float,
+    t_rise: float,
+    t_fall: float,
+    propagation_delay: float | None,
+    v_overshoot: float,
+    overshoot_pct: float,
+    v_undershoot: float,
+    undershoot_pct: float,
+    noise_margin_high: float,
+    noise_margin_low: float,
+    voh: float,
+    vol: float,
+    status: str,
+    reference_trace: WaveformTrace | None,
+) -> dict[str, Any]:
+    """Build result dictionary.
 
-    # Build result dictionary
+    Args:
+        logic_family: Logic family name.
+        confidence: Detection confidence.
+        t_rise: Rise time.
+        t_fall: Fall time.
+        propagation_delay: Propagation delay measurement.
+        v_overshoot: Overshoot voltage.
+        overshoot_pct: Overshoot percentage.
+        v_undershoot: Undershoot voltage.
+        undershoot_pct: Undershoot percentage.
+        noise_margin_high: High noise margin.
+        noise_margin_low: Low noise margin.
+        voh: High output voltage.
+        vol: Low output voltage.
+        status: Pass/fail status.
+        reference_trace: Optional reference trace.
+
+    Returns:
+        Result dictionary with all measurements.
+    """
     result = {
         "logic_family": logic_family,
         "confidence": confidence,
@@ -185,13 +335,9 @@ def characterize_buffer(
     if reference_trace is not None and propagation_delay is not None:
         result["reference_comparison"] = {
             "propagation_delay": propagation_delay,
-            "timing_drift": timing_drift,
+            "timing_drift": None,
         }
 
-    # Generate report if requested
-    if report is not None:
-        _generate_buffer_report(result, report)
-
     return result
 
 

oscura/workflows/legacy/__init__.py

@@ -0,0 +1,12 @@
+"""Legacy workflow patterns for backward compatibility.
+
+This module provides legacy workflow execution patterns that have been
+superseded by modern composition patterns. Kept for backward compatibility
+with existing code and tests.
+
+For new code, use the modern workflow patterns in the parent module.
+"""
+
+from oscura.workflows.legacy.dag import TaskNode, WorkflowDAG
+
+__all__ = ["TaskNode", "WorkflowDAG"]

oscura/{workflow → workflows/legacy}/dag.py

@@ -2,6 +2,9 @@
 
 This module provides DAG-based workflow execution with automatic dependency
 resolution and parallel execution of independent tasks.
+
+NOTE: This is legacy API for backward compatibility.
+For new code, use the modern workflow composition patterns.
 """
 
 from __future__ import annotations
@@ -51,7 +54,7 @@ class WorkflowDAG:
     with automatic parallelization of independent tasks.
 
     Example:
-        >>> from oscura.workflow.dag import WorkflowDAG
+        >>> from oscura.workflows.legacy.dag import WorkflowDAG
         >>> dag = WorkflowDAG()
         >>> dag.add_task('load', load_trace, depends_on=[])
         >>> dag.add_task('fft', compute_fft, depends_on=['load'])

oscura/workflows/multi_trace.py

@@ -107,7 +107,7 @@ class MultiTraceWorkflow:
         if not self.pattern:
             return
 
-        paths = glob_func(self.pattern)  # noqa: PTH207
+        paths = glob_func(self.pattern)
         if not paths:
             raise OscuraError(f"No files match pattern: {self.pattern}")
 
@@ -131,20 +131,20 @@ class MultiTraceWorkflow:
 
         try:
             if ext == ".csv":
-                from oscura.loaders.csv import (  # type: ignore[import-not-found]
-                    load_csv,  # type: ignore[import-not-found]
+                from oscura.loaders.csv import (
+                    load_csv,
                 )
 
                 return load_csv(str(path))
             elif ext == ".bin":
-                from oscura.loaders.binary import (  # type: ignore[import-not-found]
-                    load_binary,  # type: ignore[import-not-found]
+                from oscura.loaders.binary import (
+                    load_binary,
                 )
 
                 return load_binary(str(path))
             elif ext in (".h5", ".hdf5"):
-                from oscura.loaders.hdf5 import (  # type: ignore[import-not-found]
-                    load_hdf5,  # type: ignore[import-not-found]
+                from oscura.loaders.hdf5 import (
+                    load_hdf5,
                 )
 
                 return load_hdf5(str(path))
@@ -152,7 +152,7 @@ class MultiTraceWorkflow:
                 raise OscuraError(f"Unsupported format: {ext}")
 
         except ImportError as e:
-            raise OscuraError(f"Loader not available for {ext}: {e}")  # noqa: B904
+            raise OscuraError(f"Loader not available for {ext}: {e}")
 
     def _iter_traces(self, lazy: bool = False) -> Iterator[tuple[str, Any]]:
         """Iterate over traces.
@@ -495,7 +495,7 @@ def load_all(pattern: str, lazy: bool = True) -> list[Any]:
     Raises:
         OscuraError: If no traces found
     """
-    paths = glob_func(pattern)  # noqa: PTH207
+    paths = glob_func(pattern)
     if not paths:
         raise OscuraError(f"No files match pattern: {pattern}")
 

oscura/workflows/power.py

@@ -38,12 +38,7 @@ def power_analysis(
 ) -> dict[str, Any]:
     """Comprehensive power consumption analysis.
 
-    Analyzes power consumption from voltage and current measurements:
-    - Instantaneous power calculation
-    - Average, RMS, and peak power
-    - Energy consumption
-    - Efficiency (if input power provided)
-    - Power profile generation
+    Analyzes power consumption from voltage and current measurements.
 
     Args:
         voltage: Output voltage trace.
@@ -53,56 +48,47 @@ def power_analysis(
         report: Optional path to save HTML report.
 
     Returns:
-        Dictionary containing:
-        - power_trace: WaveformTrace of instantaneous power P(t)
-        - average_power: Mean power in watts
-        - output_power_avg: Average output power (same as average_power)
-        - output_power_rms: RMS output power in watts
-        - peak_power: Maximum power in watts
-        - min_power: Minimum power in watts
-        - energy: Total energy in joules
-        - duration: Measurement duration in seconds
-        - efficiency: Efficiency percentage (if input provided)
-        - power_loss: Power loss in watts (if input provided)
-        - input_power_avg: Average input power (if input provided)
+        Dictionary with power_trace, average_power, output_power_avg, output_power_rms,
+        peak_power, min_power, energy, duration, and optionally efficiency, power_loss, input_power_avg.
 
     Raises:
-        AnalysisError: If traces have incompatible sample rates or lengths.
+        AnalysisError: If traces have incompatible sample rates.
 
     Example:
-        >>> voltage = osc.load('vout.wfm')
-        >>> current = osc.load('iout.wfm')
-        >>> result = osc.power_analysis(voltage, current)
+        >>> result = osc.power_analysis(v_trace, i_trace)
         >>> print(f"Average: {result['average_power']*1e3:.2f} mW")
-        >>> print(f"Peak: {result['peak_power']*1e3:.2f} mW")
-        >>> print(f"Energy: {result['energy']*1e6:.2f} µJ")
 
     References:
-        IEC 61000-4-7: Harmonics and interharmonics measurement
-        IEEE 1459-2010: Definitions for measurement of electric power
+        IEC 61000-4-7, IEEE 1459-2010
     """
-    # Import power analysis functions
-    from oscura.analyzers.power.basic import (
-        instantaneous_power,
-        power_statistics,
-    )
+    from oscura.analyzers.power.basic import instantaneous_power, power_statistics
 
-    # Validate traces
+    _validate_sample_rates(voltage, current)
+    power_trace = instantaneous_power(voltage, current)
+    stats = power_statistics(power_trace)
+
+    result = _build_power_result(power_trace, stats)
+
+    if input_voltage is not None and input_current is not None:
+        result.update(_calculate_efficiency(input_voltage, input_current, stats["average"]))
+
+    if report is not None:
+        _generate_power_report(result, report)
+
+    return result
+
+
+def _validate_sample_rates(voltage: WaveformTrace, current: WaveformTrace) -> None:
+    """Validate that traces have matching sample rates."""
     if voltage.metadata.sample_rate != current.metadata.sample_rate:
-        # Would need interpolation in real implementation
         raise AnalysisError(
-            "Voltage and current traces must have same sample rate. "
-            f"Got {voltage.metadata.sample_rate} and {current.metadata.sample_rate}"
+            f"Sample rate mismatch: {voltage.metadata.sample_rate} vs {current.metadata.sample_rate}"
         )
 
-    # Calculate instantaneous power
-    power_trace = instantaneous_power(voltage, current)
-
-    # Calculate power statistics
-    stats = power_statistics(power_trace)
 
-    # Build result with output power
-    result = {
+def _build_power_result(power_trace: WaveformTrace, stats: dict[str, Any]) -> dict[str, Any]:
+    """Build power analysis result dictionary."""
+    return {
         "power_trace": power_trace,
         "average_power": stats["average"],
         "output_power_avg": stats["average"],
@@ -113,30 +99,24 @@ def power_analysis(
         "duration": stats["duration"],
     }
 
-    # Calculate efficiency if input provided
-    if input_voltage is not None and input_current is not None:
-        input_power_trace = instantaneous_power(input_voltage, input_current)
-        input_stats = power_statistics(input_power_trace)
 
-        input_power_avg = input_stats["average"]
-        output_power_avg = stats["average"]
+def _calculate_efficiency(
+    input_voltage: WaveformTrace, input_current: WaveformTrace, output_power_avg: float
+) -> dict[str, float]:
+    """Calculate power efficiency metrics."""
+    from oscura.analyzers.power.basic import instantaneous_power, power_statistics
 
-        if input_power_avg > 0:
-            efficiency = (output_power_avg / input_power_avg) * 100.0
-            power_loss = input_power_avg - output_power_avg
-        else:
-            efficiency = 0.0
-            power_loss = 0.0
+    input_power_trace = instantaneous_power(input_voltage, input_current)
+    input_stats = power_statistics(input_power_trace)
+    input_power_avg = input_stats["average"]
 
-        result["efficiency"] = efficiency
-        result["power_loss"] = power_loss
-        result["input_power_avg"] = input_power_avg
+    if input_power_avg > 0:
+        efficiency = (output_power_avg / input_power_avg) * 100.0
+        power_loss = input_power_avg - output_power_avg
+    else:
+        efficiency = power_loss = 0.0
 
-    # Generate report if requested
-    if report is not None:
-        _generate_power_report(result, report)
-
-    return result
+    return {"efficiency": efficiency, "power_loss": power_loss, "input_power_avg": input_power_avg}
 
 
 def _generate_power_report(result: dict[str, Any], output_path: str) -> None: