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

oscura/compliance/testing.py

@@ -0,0 +1,298 @@
+"""EMC compliance testing implementation.
+
+This module provides compliance testing against regulatory limit masks.
+
+
+Example:
+    >>> from oscura.compliance import load_limit_mask, test_compliance
+    >>> mask = load_limit_mask('FCC_Part15_ClassB')
+    >>> result = test_compliance(trace, mask)
+    >>> print(f"Status: {result.status}")
+
+References:
+    CISPR 16-1-1 (Measuring Apparatus)
+    ANSI C63.2 (Instrumentation)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    from oscura.compliance.masks import LimitMask
+    from oscura.core.types import WaveformTrace
+
+
+class DetectorType(Enum):
+    """EMC measurement detector types."""
+
+    PEAK = "peak"
+    QUASI_PEAK = "quasi-peak"
+    AVERAGE = "average"
+    RMS = "rms"
+
+
+@dataclass
+class ComplianceViolation:
+    """Single compliance violation record.
+
+    Attributes:
+        frequency: Violation frequency in Hz
+        measured_level: Measured level in mask unit (dBuV, etc.)
+        limit_level: Limit level at this frequency
+        excess_db: Amount exceeding limit (positive = violation)
+        detector: Detector type used
+        severity: Severity classification
+    """
+
+    frequency: float
+    measured_level: float
+    limit_level: float
+    excess_db: float
+    detector: str = "peak"
+    severity: str = "FAIL"
+
+    def __str__(self) -> str:
+        """Format violation as string."""
+        freq_mhz = self.frequency / 1e6
+        return (
+            f"{freq_mhz:.3f} MHz: {self.measured_level:.1f} dB "
+            f"(limit: {self.limit_level:.1f} dB, excess: {self.excess_db:.1f} dB)"
+        )
+
+
+@dataclass
+class ComplianceResult:
+    """Compliance test result.
+
+    Attributes:
+        status: Overall status ('PASS' or 'FAIL')
+        mask_name: Name of limit mask used
+        violations: List of violations
+        margin_to_limit: Minimum margin in dB (negative = failing)
+        worst_frequency: Frequency with worst margin
+        worst_margin: Worst margin value in dB
+        spectrum_freq: Tested frequency array
+        spectrum_level: Measured level array
+        limit_level: Limit level array (interpolated to spectrum frequencies)
+        detector: Detector type used
+        metadata: Additional result metadata
+    """
+
+    status: str
+    mask_name: str
+    violations: list[ComplianceViolation]
+    margin_to_limit: float
+    worst_frequency: float
+    worst_margin: float
+    spectrum_freq: NDArray[np.float64]
+    spectrum_level: NDArray[np.float64]
+    limit_level: NDArray[np.float64]
+    detector: str = "peak"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def passed(self) -> bool:
+        """Return True if compliance test passed."""
+        return self.status == "PASS"
+
+    @property
+    def violation_count(self) -> int:
+        """Return number of violations."""
+        return len(self.violations)
+
+    def summary(self) -> str:
+        """Generate text summary of result."""
+        lines = [
+            f"EMC Compliance Test: {self.mask_name}",
+            f"Status: {self.status}",
+            f"Margin to limit: {self.margin_to_limit:.1f} dB",
+            f"Worst frequency: {self.worst_frequency / 1e6:.3f} MHz",
+            f"Worst margin: {self.worst_margin:.1f} dB",
+        ]
+
+        if self.violations:
+            lines.append(f"\nViolations ({len(self.violations)}):")
+            for v in self.violations[:10]:  # Limit to first 10
+                lines.append(f"  - {v}")
+            if len(self.violations) > 10:
+                lines.append(f"  ... and {len(self.violations) - 10} more")
+
+        return "\n".join(lines)
+
+
+def check_compliance(
+    trace_or_spectrum: WaveformTrace | tuple[NDArray[np.float64], NDArray[np.float64]],
+    mask: LimitMask,
+    *,
+    detector: DetectorType | str = DetectorType.PEAK,
+    frequency_range: tuple[float, float] | None = None,
+    unit_conversion: str | None = None,
+) -> ComplianceResult:
+    """Check signal against EMC limit mask.
+
+    Args:
+        trace_or_spectrum: Either a WaveformTrace to analyze, or a tuple of
+            (frequency_array, magnitude_array) if spectrum already computed.
+        mask: LimitMask to test against.
+        detector: Detector type to use ('peak', 'quasi-peak', 'average', 'rms').
+        frequency_range: Optional (min, max) frequency range to test.
+        unit_conversion: Optional unit conversion ('V_to_dBuV', 'W_to_dBm', etc.)
+
+    Returns:
+        ComplianceResult with pass/fail status and violation details.
+
+    Example:
+        >>> mask = load_limit_mask('FCC_Part15_ClassB')
+        >>> result = check_compliance(trace, mask)
+        >>> print(result.summary())
+    """
+    from oscura.core.types import WaveformTrace
+
+    # Handle detector type
+    if isinstance(detector, str):
+        detector = DetectorType(detector.lower().replace("-", "_").replace(" ", "_"))
+
+    # Get spectrum
+    if isinstance(trace_or_spectrum, WaveformTrace):
+        freq, mag = _compute_spectrum(trace_or_spectrum, detector)
+    else:
+        freq, mag = trace_or_spectrum
+
+    # Convert to dB if needed
+    if unit_conversion == "V_to_dBuV":
+        # dBuV = 20*log10(V * 1e6)
+        spectrum_level = 20 * np.log10(np.abs(mag) * 1e6 + 1e-12)
+    elif unit_conversion == "W_to_dBm":
+        # dBm = 10*log10(W * 1000)
+        spectrum_level = 10 * np.log10(np.abs(mag) * 1000 + 1e-12)
+    elif mag.max() > 0 and mag.max() < 10:
+        # Assume linear voltage, convert to dBuV
+        spectrum_level = 20 * np.log10(np.abs(mag) * 1e6 + 1e-12)
+    else:
+        # Assume already in dB
+        spectrum_level = mag
+
+    # Apply frequency range filter
+    if frequency_range is not None:
+        f_min, f_max = frequency_range
+        mask_filter = (freq >= f_min) & (freq <= f_max)
+        freq = freq[mask_filter]
+        spectrum_level = spectrum_level[mask_filter]
+
+    # Limit to mask frequency range
+    mask_f_min, mask_f_max = mask.frequency_range
+    in_range = (freq >= mask_f_min) & (freq <= mask_f_max)
+    freq = freq[in_range]
+    spectrum_level = spectrum_level[in_range]
+
+    if len(freq) == 0:
+        # No data in mask range
+        return ComplianceResult(
+            status="PASS",
+            mask_name=mask.name,
+            violations=[],
+            margin_to_limit=np.inf,
+            worst_frequency=0.0,
+            worst_margin=np.inf,
+            spectrum_freq=np.array([]),
+            spectrum_level=np.array([]),
+            limit_level=np.array([]),
+            detector=detector.value,
+        )
+
+    # Interpolate limit to spectrum frequencies
+    limit_level = mask.interpolate(freq)
+
+    # Calculate margin (positive = passing)
+    margin = limit_level - spectrum_level
+
+    # Find violations
+    violations: list[ComplianceViolation] = []
+    violation_mask = margin < 0
+    if np.any(violation_mask):
+        violation_indices = np.where(violation_mask)[0]
+        for idx in violation_indices:
+            violations.append(
+                ComplianceViolation(
+                    frequency=float(freq[idx]),
+                    measured_level=float(spectrum_level[idx]),
+                    limit_level=float(limit_level[idx]),
+                    excess_db=float(-margin[idx]),
+                    detector=detector.value,
+                    severity="FAIL",
+                )
+            )
+
+    # Overall results
+    status = "FAIL" if violations else "PASS"
+    margin_to_limit = float(np.min(margin))
+    worst_idx = int(np.argmin(margin))
+    worst_frequency = float(freq[worst_idx])
+    worst_margin = float(margin[worst_idx])
+
+    return ComplianceResult(
+        status=status,
+        mask_name=mask.name,
+        violations=violations,
+        margin_to_limit=margin_to_limit,
+        worst_frequency=worst_frequency,
+        worst_margin=worst_margin,
+        spectrum_freq=freq,
+        spectrum_level=spectrum_level,
+        limit_level=limit_level,
+        detector=detector.value,
+        metadata={
+            "unit": mask.unit,
+            "distance": mask.distance,
+            "regulatory_body": mask.regulatory_body,
+        },
+    )
+
+
+def _compute_spectrum(
+    trace: WaveformTrace,
+    detector: DetectorType,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Compute spectrum from trace with specified detector.
+
+    Args:
+        trace: Input waveform trace.
+        detector: Detector type.
+
+    Returns:
+        (frequency, magnitude) arrays.
+    """
+    from oscura.analyzers.waveform.spectral import fft, psd
+
+    if detector == DetectorType.PEAK:
+        # Use FFT for peak detection
+        freq, mag = fft(trace)  # type: ignore[misc]
+        return freq, np.abs(mag)
+    elif detector == DetectorType.AVERAGE:
+        # Use Welch PSD for averaging
+        freq, mag = psd(trace, method="welch")  # type: ignore[call-arg]
+        return freq, np.sqrt(mag)  # Convert PSD to magnitude
+    elif detector == DetectorType.QUASI_PEAK:
+        # Quasi-peak requires special weighting (simplified here)
+        # Real implementation would use CISPR 16 weighting network
+        freq, mag = fft(trace)  # type: ignore[misc]
+        # Apply simplified quasi-peak envelope
+        return freq, np.abs(mag) * 0.8  # Approximate QP < peak
+    else:  # RMS
+        freq, mag = psd(trace, method="welch")  # type: ignore[call-arg]
+        return freq, np.sqrt(mag)
+
+
+__all__ = [
+    "ComplianceResult",
+    "ComplianceViolation",
+    "DetectorType",
+    "check_compliance",
+]

oscura/component/__init__.py

@@ -0,0 +1,38 @@
+"""Component analysis module for Oscura.
+
+This module provides TDR-based impedance extraction, capacitance/inductance
+measurement, parasitic extraction, and transmission line analysis.
+"""
+
+from oscura.component.impedance import (
+    discontinuity_analysis,
+    extract_impedance,
+    impedance_profile,
+)
+from oscura.component.reactive import (
+    extract_parasitics,
+    measure_capacitance,
+    measure_inductance,
+)
+from oscura.component.transmission_line import (
+    characteristic_impedance,
+    propagation_delay,
+    transmission_line_analysis,
+    velocity_factor,
+)
+
+__all__ = [
+    "characteristic_impedance",
+    "discontinuity_analysis",
+    # Impedance
+    "extract_impedance",
+    "extract_parasitics",
+    "impedance_profile",
+    # Reactive
+    "measure_capacitance",
+    "measure_inductance",
+    "propagation_delay",
+    # Transmission line
+    "transmission_line_analysis",
+    "velocity_factor",
+]

oscura/component/impedance.py

@@ -0,0 +1,365 @@
+"""TDR impedance extraction for Oscura.
+
+This module provides impedance extraction from Time Domain Reflectometry
+(TDR) measurements, including impedance profiling and discontinuity analysis.
+
+
+Example:
+    >>> from oscura.component import extract_impedance
+    >>> z0, z_profile = extract_impedance(tdr_trace)
+
+References:
+    IPC-TM-650 2.5.5.7: Characteristic Impedance of Lines on PCBs
+    IEEE 370-2020: Electrical Characterization of Interconnects
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+from scipy import signal as sp_signal
+
+from oscura.core.exceptions import InsufficientDataError
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    from oscura.core.types import WaveformTrace
+
+
+@dataclass
+class ImpedanceProfile:
+    """Impedance profile from TDR measurement.
+
+    Attributes:
+        distance: Distance axis in meters.
+        time: Time axis in seconds.
+        impedance: Impedance values in ohms.
+        z0_source: Source impedance (reference).
+        velocity: Propagation velocity used (m/s).
+        statistics: Additional statistics.
+    """
+
+    distance: NDArray[np.float64]
+    time: NDArray[np.float64]
+    impedance: NDArray[np.float64]
+    z0_source: float
+    velocity: float
+    statistics: dict = field(default_factory=dict)  # type: ignore[type-arg]
+
+    @property
+    def mean_impedance(self) -> float:
+        """Mean impedance value."""
+        return float(np.mean(self.impedance))
+
+    @property
+    def max_impedance(self) -> float:
+        """Maximum impedance value."""
+        return float(np.max(self.impedance))
+
+    @property
+    def min_impedance(self) -> float:
+        """Minimum impedance value."""
+        return float(np.min(self.impedance))
+
+
+@dataclass
+class Discontinuity:
+    """A detected impedance discontinuity.
+
+    Attributes:
+        position: Position in meters.
+        time: Time position in seconds.
+        impedance_before: Impedance before discontinuity.
+        impedance_after: Impedance after discontinuity.
+        magnitude: Magnitude of change (ohms).
+        reflection_coeff: Reflection coefficient (rho).
+        discontinuity_type: Type of discontinuity.
+    """
+
+    position: float
+    time: float
+    impedance_before: float
+    impedance_after: float
+    magnitude: float
+    reflection_coeff: float
+    discontinuity_type: Literal["capacitive", "inductive", "resistive", "unknown"]
+
+
+def extract_impedance(
+    trace: WaveformTrace,
+    *,
+    z0_source: float = 50.0,
+    velocity: float | None = None,
+    velocity_factor: float = 0.66,
+    start_time: float | None = None,
+    end_time: float | None = None,
+) -> tuple[float, ImpedanceProfile]:
+    """Extract impedance profile from TDR waveform.
+
+    Calculates the impedance profile from a TDR reflection measurement
+    using the relationship between incident and reflected waves.
+
+    Args:
+        trace: TDR reflection waveform.
+        z0_source: Source/reference impedance (default 50 ohms).
+        velocity: Propagation velocity in m/s. If None, calculated from
+            velocity_factor.
+        velocity_factor: Fraction of speed of light (default 0.66 for FR4).
+        start_time: Start time for analysis window (seconds).
+        end_time: End time for analysis window (seconds).
+
+    Returns:
+        Tuple of (characteristic_impedance, impedance_profile).
+
+    Raises:
+        InsufficientDataError: If trace has fewer than 10 samples.
+
+    Example:
+        >>> z0, profile = extract_impedance(tdr_trace, z0_source=50)
+        >>> print(f"Z0 = {z0:.1f} ohms")
+
+    References:
+        IPC-TM-650 2.5.5.7
+    """
+    data = trace.data.astype(np.float64)
+    sample_rate = trace.metadata.sample_rate
+    dt = 1.0 / sample_rate
+
+    if len(data) < 10:
+        raise InsufficientDataError(
+            "TDR analysis requires at least 10 samples",
+            required=10,
+            available=len(data),
+            analysis_type="tdr_impedance",
+        )
+
+    # Calculate propagation velocity
+    c = 299792458.0  # Speed of light in m/s
+    if velocity is None:
+        velocity = c * velocity_factor
+
+    # Create time and distance axes
+    time_axis = np.arange(len(data)) * dt
+    # TDR: distance is velocity * time / 2 (round trip)
+    distance_axis = velocity * time_axis / 2.0
+
+    # Apply time window if specified
+    start_idx = 0
+    end_idx = len(data)
+    if start_time is not None:
+        start_idx = int(start_time * sample_rate)
+    if end_time is not None:
+        end_idx = int(end_time * sample_rate)
+
+    start_idx = max(0, min(start_idx, len(data) - 1))
+    end_idx = max(start_idx + 1, min(end_idx, len(data)))
+
+    # Find the incident step level in TDR data
+    # For TDR with a matched load (Z = Z0), the steady-state voltage is V_source/2
+    incident_level = _find_incident_level(data)
+
+    # Calculate reflection coefficient from TDR waveform
+    # For TDR: V_measured = V_incident * (1 + rho)
+    # where rho is the reflection coefficient
+    # So: rho = (V_measured / V_incident) - 1
+
+    if incident_level > 0:
+        rho = (data / incident_level) - 1.0
+    else:
+        # Fallback: assume data is already normalized
+        rho = data - 1.0
+
+    # Calculate impedance from reflection coefficient
+    # Z = Z0 * (1 + rho) / (1 - rho)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        impedance = z0_source * (1 + rho) / (1 - rho)
+        # Clip unreasonable values
+        impedance = np.clip(impedance, 1.0, 10000.0)
+
+    # Extract characteristic impedance from stable region
+    stable_region = impedance[start_idx:end_idx]
+    z0 = float(np.median(stable_region))
+
+    # Create profile
+    profile = ImpedanceProfile(
+        distance=distance_axis,
+        time=time_axis,
+        impedance=impedance,
+        z0_source=z0_source,
+        velocity=velocity,
+        statistics={
+            "z0_measured": z0,
+            "z0_std": float(np.std(stable_region)),
+            "z0_min": float(np.min(stable_region)),
+            "z0_max": float(np.max(stable_region)),
+            "analysis_start_m": float(distance_axis[start_idx]),
+            "analysis_end_m": float(distance_axis[end_idx - 1]),
+        },
+    )
+
+    return z0, profile
+
+
+def impedance_profile(
+    trace: WaveformTrace,
+    *,
+    z0_source: float = 50.0,
+    velocity_factor: float = 0.66,
+    smooth_window: int = 0,
+) -> ImpedanceProfile:
+    """Get impedance profile from TDR waveform.
+
+    Convenience function that returns just the impedance profile.
+
+    Args:
+        trace: TDR reflection waveform.
+        z0_source: Source/reference impedance.
+        velocity_factor: Fraction of speed of light.
+        smooth_window: Smoothing window size (0 = no smoothing).
+
+    Returns:
+        ImpedanceProfile object.
+    """
+    _, profile = extract_impedance(
+        trace,
+        z0_source=z0_source,
+        velocity_factor=velocity_factor,
+    )
+
+    if smooth_window > 0:
+        # Apply smoothing
+        kernel = np.ones(smooth_window) / smooth_window
+        profile.impedance = np.convolve(profile.impedance, kernel, mode="same")
+
+    return profile
+
+
+def discontinuity_analysis(
+    trace: WaveformTrace,
+    *,
+    z0_source: float = 50.0,
+    velocity_factor: float = 0.66,
+    threshold: float = 5.0,
+    min_separation: float = 1e-12,
+) -> list[Discontinuity]:
+    """Analyze impedance discontinuities in TDR waveform.
+
+    Detects and characterizes impedance discontinuities along a
+    transmission line from TDR measurements.
+
+    Args:
+        trace: TDR reflection waveform.
+        z0_source: Source/reference impedance.
+        velocity_factor: Fraction of speed of light.
+        threshold: Minimum impedance change to detect (ohms).
+        min_separation: Minimum time between discontinuities (seconds).
+
+    Returns:
+        List of detected Discontinuity objects.
+
+    Example:
+        >>> disconts = discontinuity_analysis(tdr_trace)
+        >>> for d in disconts:
+        ...     print(f"{d.position*1000:.1f}mm: {d.magnitude:.1f} ohms")
+    """
+    # Get impedance profile
+    _, profile = extract_impedance(
+        trace,
+        z0_source=z0_source,
+        velocity_factor=velocity_factor,
+    )
+
+    impedance = profile.impedance
+    time_axis = profile.time
+    distance_axis = profile.distance
+
+    # Find discontinuities using derivative
+    derivative = np.abs(np.diff(impedance))
+
+    # Smooth derivative
+    if len(derivative) > 5:
+        kernel = np.ones(5) / 5
+        derivative = np.convolve(derivative, kernel, mode="same")
+
+    # Find peaks in derivative (discontinuities)
+    sample_rate = trace.metadata.sample_rate
+    min_samples = int(min_separation * sample_rate)
+
+    peaks, _properties = sp_signal.find_peaks(
+        derivative,
+        height=threshold,
+        distance=max(1, min_samples),
+    )
+
+    # Analyze each discontinuity
+    discontinuities = []
+    for peak_idx in peaks:
+        if peak_idx < 1 or peak_idx >= len(impedance) - 1:
+            continue
+
+        z_before = float(np.mean(impedance[max(0, peak_idx - 5) : peak_idx]))
+        z_after = float(np.mean(impedance[peak_idx + 1 : min(len(impedance), peak_idx + 6)]))
+
+        magnitude = z_after - z_before
+        position = float(distance_axis[peak_idx])
+        time_pos = float(time_axis[peak_idx])
+
+        # Calculate reflection coefficient
+        rho = (z_after - z_before) / (z_after + z_before) if z_before + z_after > 0 else 0.0
+
+        # Determine discontinuity type
+        if magnitude > 0:
+            # Increasing impedance
+            if abs(magnitude) > 20:
+                disc_type: Literal["capacitive", "inductive", "resistive", "unknown"] = "inductive"
+            else:
+                disc_type = "resistive"
+        # Decreasing impedance
+        elif abs(magnitude) > 20:
+            disc_type = "capacitive"
+        else:
+            disc_type = "resistive"
+
+        discontinuities.append(
+            Discontinuity(
+                position=position,
+                time=time_pos,
+                impedance_before=z_before,
+                impedance_after=z_after,
+                magnitude=magnitude,
+                reflection_coeff=float(rho),
+                discontinuity_type=disc_type,
+            )
+        )
+
+    return discontinuities
+
+
+def _find_incident_level(data: NDArray[np.float64]) -> float:
+    """Find the incident step level in TDR data.
+
+    Looks for the stable level after the initial edge and before
+    any reflections return.
+
+    Args:
+        data: TDR waveform data array.
+
+    Returns:
+        Median voltage level in the incident region.
+    """
+    if len(data) < 10:
+        return float(np.max(data))
+
+    # Look at first 10-20% of data for incident level
+    search_end = len(data) // 5
+    search_start = len(data) // 20
+
+    if search_end <= search_start:
+        return float(np.max(data[:search_end]))
+
+    # Find stable region using variance
+    stable_data = data[search_start:search_end]
+    return float(np.median(stable_data))