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

oscura/workflows/compliance.py

@@ -0,0 +1,280 @@
+"""EMC/EMI compliance testing workflow.
+
+This module implements spectral compliance testing against regulatory limits.
+
+
+Example:
+    >>> import oscura as tk
+    >>> trace = tk.load('emissions.wfm')
+    >>> result = tk.emc_compliance_test(trace, standard='FCC_Part15_ClassB')
+    >>> print(f"Status: {result['status']}")
+    >>> print(f"Violations: {len(result['violations'])}")
+
+References:
+    FCC Part 15: Radio Frequency Devices
+    CISPR 22/32: Information Technology Equipment
+    MIL-STD-461: EMI/EMC Requirements
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+import numpy as np
+
+from oscura.core.exceptions import AnalysisError
+
+if TYPE_CHECKING:
+    from oscura.core.types import WaveformTrace
+
+
+def emc_compliance_test(
+    trace: WaveformTrace,
+    *,
+    standard: str = "FCC_Part15_ClassB",
+    frequency_range: tuple[float, float] | None = None,
+    detector: Literal["peak", "quasi-peak", "average"] = "peak",
+    report: str | None = None,
+) -> dict[str, Any]:
+    """EMC/EMI compliance testing against regulatory limits.
+
+    Performs spectral compliance testing:
+    - Computes spectrum (FFT or welch)
+    - Loads regulatory limit mask
+    - Overlays limit lines on spectrum
+    - Identifies violations
+    - Generates compliance report
+
+    Args:
+        trace: Signal to test for emissions.
+        standard: Regulatory standard to test against:
+                  'FCC_Part15_ClassA', 'FCC_Part15_ClassB',
+                  'CE_CISPR22_ClassA', 'CE_CISPR22_ClassB',
+                  'CE_CISPR32_ClassA', 'CE_CISPR32_ClassB',
+                  'MIL_STD_461G_CE102', 'MIL_STD_461G_RE102'
+        frequency_range: Optional frequency range (f_min, f_max) in Hz.
+        detector: Detector type ('peak', 'quasi-peak', 'average').
+        report: Optional path to save HTML compliance report.
+
+    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
+
+    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 = tk.load('radiated_emissions.wfm')
+        >>> result = tk.emc_compliance_test(trace, standard='FCC_Part15_ClassB')
+        >>> print(f"Compliance: {result['status']}")
+        >>> print(f"Margin: {result['margin_to_limit']:.1f} dB")
+        >>> if result['violations']:
+        ...     print(f"Violations at: {[v['frequency']/1e6 for v in result['violations']]} MHz")
+
+    References:
+        FCC Part 15 Subpart B (Unintentional Radiators)
+        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
+    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
+
+    # Load limit mask for standard
+    limit_freq, limit_mag = _load_emc_mask(standard)
+
+    # 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
+    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
+    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,
+        "spectrum_freq": freq,
+        "spectrum_mag": spectrum_dbuv,
+        "limit_freq": limit_freq,
+        "limit_mag": limit_mag,
+        "detector": detector,
+    }
+
+    # Generate report if requested
+    if report is not None:
+        _generate_compliance_report(result, report)
+
+    return result
+
+
+def _load_emc_mask(
+    standard: str,
+) -> tuple[np.ndarray[Any, np.dtype[np.float64]], np.ndarray[Any, np.dtype[np.float64]]]:
+    """Load EMC limit mask for a standard.
+
+    Args:
+        standard: Standard name.
+
+    Returns:
+        Tuple of (frequency array, limit array in dBµV).
+
+    Raises:
+        AnalysisError: If unknown EMC standard.
+    """
+    # Simplified mask data - real implementation would load from data files
+    masks = {
+        "FCC_Part15_ClassB": {
+            # Frequencies in MHz, limits in dBµV at 3m
+            "freq": np.array([0.15, 0.5, 5.0, 30.0, 88.0, 216.0, 1000.0]) * 1e6,
+            "limit": np.array([60, 60, 56, 46, 46, 46, 46]),  # dBµV/m
+        },
+        "FCC_Part15_ClassA": {
+            "freq": np.array([0.15, 0.5, 5.0, 30.0, 88.0, 216.0, 1000.0]) * 1e6,
+            "limit": np.array([70, 70, 66, 56, 56, 56, 56]),
+        },
+        "CE_CISPR22_ClassB": {
+            "freq": np.array([0.15, 0.5, 5.0, 30.0, 230.0, 1000.0]) * 1e6,
+            "limit": np.array([66, 56, 56, 47, 47, 47]),
+        },
+        "CE_CISPR22_ClassA": {
+            "freq": np.array([0.15, 0.5, 5.0, 30.0, 230.0, 1000.0]) * 1e6,
+            "limit": np.array([79, 73, 73, 60, 60, 60]),
+        },
+        "CE_CISPR32_ClassB": {
+            "freq": np.array([0.15, 0.5, 5.0, 30.0, 230.0, 1000.0]) * 1e6,
+            "limit": np.array([66, 56, 56, 47, 47, 47]),
+        },
+        "CE_CISPR32_ClassA": {
+            "freq": np.array([0.15, 0.5, 5.0, 30.0, 230.0, 1000.0]) * 1e6,
+            "limit": np.array([79, 73, 73, 60, 60, 60]),
+        },
+        "MIL_STD_461G_CE102": {
+            "freq": np.array([0.01, 0.15, 10.0, 50.0]) * 1e6,
+            "limit": np.array([90, 80, 80, 80]),
+        },
+        "MIL_STD_461G_RE102": {
+            "freq": np.array([2, 30, 200, 1000, 18000]) * 1e6,
+            "limit": np.array([54, 54, 34, 34, 34]),
+        },
+    }
+
+    if standard not in masks:
+        raise AnalysisError(f"Unknown EMC standard: {standard}")
+
+    mask_data = masks[standard]
+    return mask_data["freq"], mask_data["limit"]
+
+
+def _generate_compliance_report(result: dict[str, Any], output_path: str) -> None:
+    """Generate HTML compliance report.
+
+    Args:
+        result: Compliance test result dictionary.
+        output_path: Path to save HTML report.
+    """
+    status_color = "green" if result["status"] == "PASS" else "red"
+
+    html = f"""
+    <html>
+    <head><title>EMC Compliance Report</title></head>
+    <body>
+    <h1>EMC Compliance Test Report</h1>
+    <h2>Standard: {result["standard"]}</h2>
+    <h2 style="color: {status_color}">Status: {result["status"]}</h2>
+
+    <h3>Summary</h3>
+    <table>
+        <tr><th>Parameter</th><th>Value</th></tr>
+        <tr><td>Margin to Limit</td><td>{result["margin_to_limit"]:.2f} dB</td></tr>
+        <tr><td>Worst Frequency</td><td>{result["worst_frequency"] / 1e6:.2f} MHz</td></tr>
+        <tr><td>Worst Margin</td><td>{result["worst_margin"]:.2f} dB</td></tr>
+        <tr><td>Violations</td><td>{len(result["violations"])}</td></tr>
+    </table>
+    """
+    if result["violations"]:
+        html += """
+        <h3>Violations</h3>
+        <table>
+            <tr><th>Frequency (MHz)</th><th>Measured (dBµV)</th><th>Limit (dBµV)</th><th>Excess (dB)</th></tr>
+        """
+        for v in result["violations"]:
+            html += f"""
+            <tr>
+                <td>{v["frequency"] / 1e6:.2f}</td>
+                <td>{v["measured_dbuv"]:.2f}</td>
+                <td>{v["limit_dbuv"]:.2f}</td>
+                <td>{v["excess_db"]:.2f}</td>
+            </tr>
+            """
+        html += "</table>"
+
+    html += """
+    </body>
+    </html>
+    """
+    with open(output_path, "w") as f:
+        f.write(html)
+
+
+__all__ = ["emc_compliance_test"]

oscura/workflows/digital.py

@@ -0,0 +1,272 @@
+"""Digital buffer characterization workflow.
+
+This module implements complete TTL/CMOS buffer characterization in a single
+function call, with automatic logic family detection.
+
+
+Example:
+    >>> import oscura as tk
+    >>> trace = tk.load('74hc04_output.wfm')
+    >>> result = tk.characterize_buffer(trace)
+    >>> print(f"Logic Family: {result['logic_family']}")
+    >>> print(f"Rise Time: {result['rise_time']:.2f} ns")
+    >>> print(f"Status: {result['status']}")
+
+References:
+    IEEE 181-2011: Standard for Transitional Waveform Definitions
+    JEDEC Standard No. 65B: High-Speed Interface Timing
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from oscura.core.exceptions import AnalysisError
+
+if TYPE_CHECKING:
+    from oscura.core.types import WaveformTrace
+
+
+def characterize_buffer(
+    trace: WaveformTrace,
+    *,
+    reference_trace: WaveformTrace | None = None,
+    logic_family: str | None = None,
+    thresholds: dict[str, float] | None = None,
+    report: str | None = None,
+) -> dict[str, Any]:
+    """Characterize digital buffer timing and quality.
+
+    One-call characterization of digital buffer including:
+    - Automatic logic family detection (if not specified)
+    - Rise/fall time measurements
+    - Propagation delay (if reference provided)
+    - Overshoot/undershoot analysis
+    - Noise margin calculation
+    - Pass/fail against logic family specifications
+
+    Args:
+        trace: Output signal to characterize.
+        reference_trace: Optional reference (input) signal for propagation delay.
+        logic_family: Logic family override (e.g., 'TTL', 'CMOS_3V3', 'CMOS_5V').
+                      If None, auto-detected from signal levels.
+        thresholds: Optional dict of custom pass/fail thresholds
+                    (e.g., {'rise_time': 10e-9} for 10 ns max).
+        report: Optional path to save HTML report.
+
+    Returns:
+        Dictionary containing:
+        - logic_family: Detected or specified logic family
+        - rise_time: 10%-90% rise time in seconds
+        - fall_time: 10%-90% fall time in seconds
+        - propagation_delay: Delay from reference (if provided), in seconds
+        - overshoot: Peak overshoot voltage
+        - overshoot_percent: Overshoot as percentage of swing
+        - undershoot: Peak undershoot voltage
+        - undershoot_percent: Undershoot as percentage of swing
+        - noise_margin_high: High-level noise margin in volts
+        - noise_margin_low: Low-level noise margin in volts
+        - status: 'PASS' or 'FAIL' based on logic family specs
+        - reference_comparison: Dict with timing drift if reference provided
+        - confidence: Confidence score for logic family detection (0-1)
+
+    Raises:
+        AnalysisError: If trace has insufficient transitions for analysis.
+
+    Example:
+        >>> trace = tk.load('74hc04_output.wfm')
+        >>> result = tk.characterize_buffer(trace, logic_family='CMOS_3V3')
+        >>> print(f"Rise Time: {result['rise_time']*1e9:.2f} ns")
+        >>> print(f"Status: {result['status']}")
+
+    References:
+        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,
+    )
+    from oscura.inference.logic import detect_logic_family
+
+    # Auto-detect logic family if not specified
+    if logic_family is None:
+        detection = detect_logic_family(trace)
+        logic_family = detection["primary"]["name"]
+        confidence = detection["primary"]["confidence"]
+        voh = detection["primary"]["voh"]
+        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
+    try:
+        t_rise = rise_time(trace)
+        t_fall = fall_time(trace)
+    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)
+
+    # Calculate percentages
+    swing = voh - vol
+    if swing > 0:
+        overshoot_pct = (v_overshoot / swing) * 100.0
+        undershoot_pct = (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
+
+    # 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"
+    if thresholds is not None:
+        if "rise_time" in thresholds and t_rise > thresholds["rise_time"]:
+            status = "FAIL"
+        if "fall_time" in thresholds and t_fall > thresholds["fall_time"]:
+            status = "FAIL"
+        if "overshoot_percent" in thresholds and overshoot_pct > thresholds["overshoot_percent"]:
+            status = "FAIL"
+    else:
+        # Use logic family defaults
+        if t_rise > logic_specs.get("max_rise_time", float("inf")):
+            status = "FAIL"
+        if t_fall > logic_specs.get("max_fall_time", float("inf")):
+            status = "FAIL"
+
+    # Build result dictionary
+    result = {
+        "logic_family": logic_family,
+        "confidence": confidence,
+        "rise_time": t_rise,
+        "fall_time": t_fall,
+        "propagation_delay": propagation_delay,
+        "overshoot": v_overshoot,
+        "overshoot_percent": overshoot_pct,
+        "undershoot": v_undershoot,
+        "undershoot_percent": undershoot_pct,
+        "noise_margin_high": noise_margin_high,
+        "noise_margin_low": noise_margin_low,
+        "voh": voh,
+        "vol": vol,
+        "status": status,
+        "reference_comparison": None,
+    }
+
+    if reference_trace is not None and propagation_delay is not None:
+        result["reference_comparison"] = {
+            "propagation_delay": propagation_delay,
+            "timing_drift": timing_drift,
+        }
+
+    # Generate report if requested
+    if report is not None:
+        _generate_buffer_report(result, report)
+
+    return result
+
+
+def _get_logic_specs(family: str) -> dict[str, float]:
+    """Get specifications for a logic family.
+
+    Args:
+        family: Logic family name.
+
+    Returns:
+        Dict with VIH, VIL, and timing specs.
+    """
+    specs = {
+        "TTL": {
+            "vih": 2.0,
+            "vil": 0.8,
+            "max_rise_time": 10e-9,
+            "max_fall_time": 10e-9,
+        },
+        "CMOS_5V": {
+            "vih": 3.5,
+            "vil": 1.5,
+            "max_rise_time": 15e-9,
+            "max_fall_time": 15e-9,
+        },
+        "CMOS_3V3": {
+            "vih": 2.0,
+            "vil": 0.8,
+            "max_rise_time": 5e-9,
+            "max_fall_time": 5e-9,
+        },
+        "LVTTL": {
+            "vih": 2.0,
+            "vil": 0.8,
+            "max_rise_time": 3e-9,
+            "max_fall_time": 3e-9,
+        },
+        "LVCMOS": {
+            "vih": 1.7,
+            "vil": 0.7,
+            "max_rise_time": 2e-9,
+            "max_fall_time": 2e-9,
+        },
+    }
+    return specs.get(family, specs["CMOS_3V3"])
+
+
+def _generate_buffer_report(result: dict[str, Any], output_path: str) -> None:
+    """Generate HTML report for buffer characterization.
+
+    Args:
+        result: Characterization result dictionary.
+        output_path: Path to save HTML report.
+    """
+    # Simplified report generation - in real implementation would use
+    # oscura.reporting module
+    html = f"""
+    <html>
+    <head><title>Buffer Characterization Report</title></head>
+    <body>
+    <h1>Buffer Characterization Report</h1>
+    <h2>Logic Family: {result["logic_family"]} (confidence: {result["confidence"]:.1%})</h2>
+    <table>
+        <tr><th>Parameter</th><th>Value</th><th>Units</th></tr>
+        <tr><td>Rise Time</td><td>{result["rise_time"] * 1e9:.2f}</td><td>ns</td></tr>
+        <tr><td>Fall Time</td><td>{result["fall_time"] * 1e9:.2f}</td><td>ns</td></tr>
+        <tr><td>Overshoot</td><td>{result["overshoot_percent"]:.1f}</td><td>%</td></tr>
+        <tr><td>Undershoot</td><td>{result["undershoot_percent"]:.1f}</td><td>%</td></tr>
+        <tr><td>Status</td><td><b>{result["status"]}</b></td><td></td></tr>
+    </table>
+    </body>
+    </html>
+    """
+    with open(output_path, "w") as f:
+        f.write(html)
+
+
+__all__ = ["characterize_buffer"]