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

oscura/{component → utils/component}/impedance.py

@@ -5,7 +5,7 @@ This module provides impedance extraction from Time Domain Reflectometry
 
 
 Example:
-    >>> from oscura.component import extract_impedance
+    >>> from oscura.utils.component import extract_impedance
     >>> z0, z_profile = extract_impedance(tdr_trace)
 
 References:
@@ -124,10 +124,36 @@ def extract_impedance(
     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
+    data, sample_rate = _prepare_tdr_data(trace)
+    velocity_val = _compute_velocity(velocity, velocity_factor)
+    time_axis, distance_axis = _create_axes(data, sample_rate, velocity_val)
+    start_idx, end_idx = _compute_analysis_window(len(data), sample_rate, start_time, end_time)
+    impedance = _compute_impedance_profile(data, z0_source)
+    z0, stats = _extract_impedance_statistics(impedance, start_idx, end_idx, distance_axis)
+    profile = ImpedanceProfile(
+        distance=distance_axis,
+        time=time_axis,
+        impedance=impedance,
+        z0_source=z0_source,
+        velocity=velocity_val,
+        statistics=stats,
+    )
+    return z0, profile
+
+
+def _prepare_tdr_data(trace: WaveformTrace) -> tuple[NDArray[np.float64], float]:
+    """Prepare TDR data for analysis.
+
+    Args:
+        trace: TDR reflection waveform.
+
+    Returns:
+        Tuple of (data array, sample rate).
 
+    Raises:
+        InsufficientDataError: If trace has fewer than 10 samples.
+    """
+    data = trace.data.astype(np.float64)
     if len(data) < 10:
         raise InsufficientDataError(
             "TDR analysis requires at least 10 samples",
@@ -135,72 +161,110 @@ def extract_impedance(
             available=len(data),
             analysis_type="tdr_impedance",
         )
+    return data, trace.metadata.sample_rate
+
+
+def _compute_velocity(velocity: float | None, velocity_factor: float) -> float:
+    """Compute propagation velocity.
+
+    Args:
+        velocity: Explicit velocity or None.
+        velocity_factor: Fraction of speed of light.
 
-    # Calculate propagation velocity
+    Returns:
+        Propagation velocity in m/s.
+    """
+    if velocity is not None:
+        return velocity
     c = 299792458.0  # Speed of light in m/s
-    if velocity is None:
-        velocity = c * velocity_factor
+    return c * velocity_factor
+
+
+def _create_axes(
+    data: NDArray[np.float64], sample_rate: float, velocity: float
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Create time and distance axes for TDR.
+
+    Args:
+        data: TDR data array.
+        sample_rate: Sample rate in Hz.
+        velocity: Propagation velocity in m/s.
 
-    # Create time and distance axes
+    Returns:
+        Tuple of (time_axis, distance_axis).
+    """
+    dt = 1.0 / sample_rate
     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)
+    distance_axis = velocity * time_axis / 2.0  # Round trip
+    return time_axis, distance_axis
+
+
+def _compute_analysis_window(
+    data_len: int, sample_rate: float, start_time: float | None, end_time: float | None
+) -> tuple[int, int]:
+    """Compute analysis window indices.
+
+    Args:
+        data_len: Length of data array.
+        sample_rate: Sample rate in Hz.
+        start_time: Start time in seconds.
+        end_time: End time in seconds.
 
-    # 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
+    Returns:
+        Tuple of (start_idx, end_idx).
+    """
+    start_idx = 0 if start_time is None else int(start_time * sample_rate)
+    end_idx = data_len if end_time is None else int(end_time * sample_rate)
+    start_idx = max(0, min(start_idx, data_len - 1))
+    end_idx = max(start_idx + 1, min(end_idx, data_len))
+    return start_idx, end_idx
+
+
+def _compute_impedance_profile(data: NDArray[np.float64], z0_source: float) -> NDArray[np.float64]:
+    """Compute impedance profile from TDR data.
 
-    if incident_level > 0:
-        rho = (data / incident_level) - 1.0
-    else:
-        # Fallback: assume data is already normalized
-        rho = data - 1.0
+    Args:
+        data: TDR voltage data.
+        z0_source: Source impedance.
 
-    # Calculate impedance from reflection coefficient
-    # Z = Z0 * (1 + rho) / (1 - rho)
+    Returns:
+        Impedance profile array.
+    """
+    incident_level = _find_incident_level(data)
+    rho = (data / incident_level) - 1.0 if incident_level > 0 else data - 1.0
     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)
+        return 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]),
-        },
-    )
+def _extract_impedance_statistics(
+    impedance: NDArray[np.float64],
+    start_idx: int,
+    end_idx: int,
+    distance_axis: NDArray[np.float64],
+) -> tuple[float, dict[str, float]]:
+    """Extract impedance statistics from stable region.
 
-    return z0, profile
+    Args:
+        impedance: Impedance profile.
+        start_idx: Start index of analysis window.
+        end_idx: End index of analysis window.
+        distance_axis: Distance array.
+
+    Returns:
+        Tuple of (characteristic impedance, statistics dict).
+    """
+    stable_region = impedance[start_idx:end_idx]
+    z0 = float(np.median(stable_region))
+    stats = {
+        "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, stats
 
 
 def impedance_profile(

oscura/{component → utils/component}/reactive.py

@@ -5,7 +5,7 @@ waveform data, including parasitic extraction.
 
 
 Example:
-    >>> from oscura.component import measure_capacitance, measure_inductance
+    >>> from oscura.utils.component import measure_capacitance, measure_inductance
     >>> C = measure_capacitance(voltage_trace, current_trace)
     >>> L = measure_inductance(voltage_trace, current_trace)
 
@@ -137,95 +137,95 @@ def measure_capacitance(
         )
 
     if method == "charge" and current_trace is not None:
-        # C = Q / V = integral(I*dt) / delta_V
-        current = current_trace.data.astype(np.float64)
-        min_len = min(len(voltage), len(current))
-        voltage = voltage[:min_len]
-        current = current[:min_len]
-
-        # Integrate current to get charge
-        charge = np.cumsum(current) * dt
-        delta_v = np.max(voltage) - np.min(voltage)
-
-        if delta_v > 1e-10:
-            delta_q = np.max(charge) - np.min(charge)
-            capacitance = delta_q / delta_v
-        else:
-            raise AnalysisError("Voltage change too small for capacitance measurement")
-
-        # Estimate ESR from phase relationship
-        esr = _estimate_esr(voltage, current, sample_rate)
-
-        return CapacitanceMeasurement(
-            capacitance=float(abs(capacitance)),
-            esr=esr,
-            method="charge_integration",
-            confidence=0.9,
-            statistics={
-                "delta_v": delta_v,
-                "delta_q": delta_q,
-                "num_samples": min_len,
-            },
+        return _measure_capacitance_charge(
+            voltage, current_trace.data.astype(np.float64), dt, sample_rate
         )
-
     elif method == "slope" and current_trace is not None:
-        # C = I / (dV/dt)
-        current = current_trace.data.astype(np.float64)
-        min_len = min(len(voltage), len(current))
-        voltage = voltage[:min_len]
-        current = current[:min_len]
-
-        # Calculate dV/dt
-        dv_dt = np.diff(voltage) / dt
-
-        # Find region where dV/dt is significant
-        significant_mask = np.abs(dv_dt) > np.max(np.abs(dv_dt)) * 0.1
-        if np.sum(significant_mask) < 5:
-            raise AnalysisError("Insufficient voltage slope for capacitance measurement")
-
-        # Use corresponding current values
-        current_for_slope = current[:-1][significant_mask]
-        dv_dt_significant = dv_dt[significant_mask]
-
-        # C = I / (dV/dt)
-        capacitance_values = current_for_slope / dv_dt_significant
-        capacitance = float(np.median(np.abs(capacitance_values)))
-
-        return CapacitanceMeasurement(
-            capacitance=capacitance,
-            method="slope",
-            confidence=0.85,
-            statistics={
-                "num_valid_points": int(np.sum(significant_mask)),
-                "capacitance_std": float(np.std(np.abs(capacitance_values))),
-            },
-        )
-
+        return _measure_capacitance_slope(voltage, current_trace.data.astype(np.float64), dt)
     elif method == "frequency":
-        # Extract from RC time constant
-        if resistance is None:
-            raise AnalysisError("Resistance value required for frequency method")
-
-        # Find time constant from step response
-        tau = _extract_time_constant(voltage, sample_rate)
-
-        # C = tau / R
-        capacitance = tau / resistance
-
-        return CapacitanceMeasurement(
-            capacitance=float(capacitance),
-            method="time_constant",
-            confidence=0.8,
-            statistics={
-                "time_constant": tau,
-                "resistance": resistance,
-            },
-        )
-
+        return _measure_capacitance_frequency(voltage, sample_rate, resistance)
     else:
         raise AnalysisError(f"Method '{method}' requires current_trace or resistance parameter")
 
 
+def _measure_capacitance_charge(
+    voltage: NDArray[np.float64],
+    current: NDArray[np.float64],
+    dt: float,
+    sample_rate: float,
+) -> CapacitanceMeasurement:
+    """Measure capacitance using charge integration method."""
+    min_len = min(len(voltage), len(current))
+    voltage, current = voltage[:min_len], current[:min_len]
+
+    charge = np.cumsum(current) * dt
+    delta_v = np.max(voltage) - np.min(voltage)
+
+    if delta_v <= 1e-10:
+        raise AnalysisError("Voltage change too small for capacitance measurement")
+
+    delta_q = np.max(charge) - np.min(charge)
+    capacitance = delta_q / delta_v
+    esr = _estimate_esr(voltage, current, sample_rate)
+
+    return CapacitanceMeasurement(
+        capacitance=float(abs(capacitance)),
+        esr=esr,
+        method="charge_integration",
+        confidence=0.9,
+        statistics={"delta_v": delta_v, "delta_q": delta_q, "num_samples": min_len},
+    )
+
+
+def _measure_capacitance_slope(
+    voltage: NDArray[np.float64],
+    current: NDArray[np.float64],
+    dt: float,
+) -> CapacitanceMeasurement:
+    """Measure capacitance using slope method."""
+    min_len = min(len(voltage), len(current))
+    voltage, current = voltage[:min_len], current[:min_len]
+
+    dv_dt = np.diff(voltage) / dt
+    significant_mask = np.abs(dv_dt) > np.max(np.abs(dv_dt)) * 0.1
+
+    if np.sum(significant_mask) < 5:
+        raise AnalysisError("Insufficient voltage slope for capacitance measurement")
+
+    capacitance_values = current[:-1][significant_mask] / dv_dt[significant_mask]
+    capacitance = float(np.median(np.abs(capacitance_values)))
+
+    return CapacitanceMeasurement(
+        capacitance=capacitance,
+        method="slope",
+        confidence=0.85,
+        statistics={
+            "num_valid_points": int(np.sum(significant_mask)),
+            "capacitance_std": float(np.std(np.abs(capacitance_values))),
+        },
+    )
+
+
+def _measure_capacitance_frequency(
+    voltage: NDArray[np.float64],
+    sample_rate: float,
+    resistance: float | None,
+) -> CapacitanceMeasurement:
+    """Measure capacitance using time constant method."""
+    if resistance is None:
+        raise AnalysisError("Resistance value required for frequency method")
+
+    tau = _extract_time_constant(voltage, sample_rate)
+    capacitance = tau / resistance
+
+    return CapacitanceMeasurement(
+        capacitance=float(capacitance),
+        method="time_constant",
+        confidence=0.8,
+        statistics={"time_constant": tau, "resistance": resistance},
+    )
+
+
 def measure_inductance(
     voltage_trace: WaveformTrace,
     current_trace: WaveformTrace | None = None,
@@ -274,95 +274,92 @@ def measure_inductance(
         )
 
     if method == "flux" and current_trace is not None:
-        # L = flux / I = integral(V*dt) / delta_I
-        current = current_trace.data.astype(np.float64)
-        min_len = min(len(voltage), len(current))
-        voltage = voltage[:min_len]
-        current = current[:min_len]
-
-        # Integrate voltage to get flux linkage
-        flux = np.cumsum(voltage) * dt
-        delta_i = np.max(current) - np.min(current)
-
-        if delta_i > 1e-10:
-            delta_flux = np.max(flux) - np.min(flux)
-            inductance = delta_flux / delta_i
-        else:
-            raise AnalysisError("Current change too small for inductance measurement")
-
-        # Estimate DCR from steady-state
-        dcr = _estimate_dcr(voltage, current)
-
-        return InductanceMeasurement(
-            inductance=float(abs(inductance)),
-            dcr=dcr,
-            method="flux_integration",
-            confidence=0.9,
-            statistics={
-                "delta_i": delta_i,
-                "delta_flux": delta_flux,
-                "num_samples": min_len,
-            },
-        )
-
+        return _measure_inductance_flux(voltage, current_trace.data.astype(np.float64), dt)
     elif method == "slope" and current_trace is not None:
-        # L = V / (dI/dt)
-        current = current_trace.data.astype(np.float64)
-        min_len = min(len(voltage), len(current))
-        voltage = voltage[:min_len]
-        current = current[:min_len]
-
-        # Calculate dI/dt
-        di_dt = np.diff(current) / dt
-
-        # Find region where dI/dt is significant
-        significant_mask = np.abs(di_dt) > np.max(np.abs(di_dt)) * 0.1
-        if np.sum(significant_mask) < 5:
-            raise AnalysisError("Insufficient current slope for inductance measurement")
-
-        # Use corresponding voltage values
-        voltage_for_slope = voltage[:-1][significant_mask]
-        di_dt_significant = di_dt[significant_mask]
-
-        # L = V / (dI/dt)
-        inductance_values = voltage_for_slope / di_dt_significant
-        inductance = float(np.median(np.abs(inductance_values)))
-
-        return InductanceMeasurement(
-            inductance=inductance,
-            method="slope",
-            confidence=0.85,
-            statistics={
-                "num_valid_points": int(np.sum(significant_mask)),
-                "inductance_std": float(np.std(np.abs(inductance_values))),
-            },
-        )
-
+        return _measure_inductance_slope(voltage, current_trace.data.astype(np.float64), dt)
     elif method == "frequency":
-        # Extract from RL time constant
-        if resistance is None:
-            raise AnalysisError("Resistance value required for frequency method")
-
-        # Find time constant from step response
-        tau = _extract_time_constant(voltage, sample_rate)
-
-        # L = tau * R
-        inductance = tau * resistance
-
-        return InductanceMeasurement(
-            inductance=float(inductance),
-            method="time_constant",
-            confidence=0.8,
-            statistics={
-                "time_constant": tau,
-                "resistance": resistance,
-            },
-        )
-
+        return _measure_inductance_frequency(voltage, sample_rate, resistance)
     else:
         raise AnalysisError(f"Method '{method}' requires current_trace or resistance parameter")
 
 
+def _measure_inductance_flux(
+    voltage: NDArray[np.float64],
+    current: NDArray[np.float64],
+    dt: float,
+) -> InductanceMeasurement:
+    """Measure inductance using flux integration method."""
+    min_len = min(len(voltage), len(current))
+    voltage, current = voltage[:min_len], current[:min_len]
+
+    flux = np.cumsum(voltage) * dt
+    delta_i = np.max(current) - np.min(current)
+
+    if delta_i <= 1e-10:
+        raise AnalysisError("Current change too small for inductance measurement")
+
+    delta_flux = np.max(flux) - np.min(flux)
+    inductance = delta_flux / delta_i
+    dcr = _estimate_dcr(voltage, current)
+
+    return InductanceMeasurement(
+        inductance=float(abs(inductance)),
+        dcr=dcr,
+        method="flux_integration",
+        confidence=0.9,
+        statistics={"delta_i": delta_i, "delta_flux": delta_flux, "num_samples": min_len},
+    )
+
+
+def _measure_inductance_slope(
+    voltage: NDArray[np.float64],
+    current: NDArray[np.float64],
+    dt: float,
+) -> InductanceMeasurement:
+    """Measure inductance using slope method."""
+    min_len = min(len(voltage), len(current))
+    voltage, current = voltage[:min_len], current[:min_len]
+
+    di_dt = np.diff(current) / dt
+    significant_mask = np.abs(di_dt) > np.max(np.abs(di_dt)) * 0.1
+
+    if np.sum(significant_mask) < 5:
+        raise AnalysisError("Insufficient current slope for inductance measurement")
+
+    inductance_values = voltage[:-1][significant_mask] / di_dt[significant_mask]
+    inductance = float(np.median(np.abs(inductance_values)))
+
+    return InductanceMeasurement(
+        inductance=inductance,
+        method="slope",
+        confidence=0.85,
+        statistics={
+            "num_valid_points": int(np.sum(significant_mask)),
+            "inductance_std": float(np.std(np.abs(inductance_values))),
+        },
+    )
+
+
+def _measure_inductance_frequency(
+    voltage: NDArray[np.float64],
+    sample_rate: float,
+    resistance: float | None,
+) -> InductanceMeasurement:
+    """Measure inductance using time constant method."""
+    if resistance is None:
+        raise AnalysisError("Resistance value required for frequency method")
+
+    tau = _extract_time_constant(voltage, sample_rate)
+    inductance = tau * resistance
+
+    return InductanceMeasurement(
+        inductance=float(inductance),
+        method="time_constant",
+        confidence=0.8,
+        statistics={"time_constant": tau, "resistance": resistance},
+    )
+
+
 def extract_parasitics(
     voltage_trace: WaveformTrace,
     current_trace: WaveformTrace,
@@ -530,7 +527,7 @@ def _fit_series_rlc(
         # Simple optimization
         from scipy.optimize import minimize
 
-        def objective(params: NDArray[np.float64]) -> np.floating[Any]:  # type: ignore[name-defined]
+        def objective(params: NDArray[np.float64]) -> np.floating[Any]:
             R, L, C = params
             Z_model = model(omega, R, L, C)
             return float(np.sum(np.abs(Z - Z_model) ** 2))  # type: ignore[return-value]
@@ -563,7 +560,7 @@ def _fit_parallel_rlc(
     try:
         from scipy.optimize import minimize
 
-        def objective(params: NDArray[np.float64]) -> np.floating[Any]:  # type: ignore[name-defined]
+        def objective(params: NDArray[np.float64]) -> np.floating[Any]:
             R, L, C = params
             Y_model = 1 / R + 1j * omega * C + 1 / (1j * omega * L + 1e-20)
             Z_model = 1 / (Y_model + 1e-20)

oscura/{component → utils/component}/transmission_line.py

@@ -5,7 +5,7 @@ characteristic impedance, propagation delay, and velocity factor.
 
 
 Example:
-    >>> from oscura.component import transmission_line_analysis
+    >>> from oscura.utils.component import transmission_line_analysis
     >>> result = transmission_line_analysis(tdr_trace)
 
 References:
@@ -79,7 +79,7 @@ def transmission_line_analysis(
         >>> result = transmission_line_analysis(tdr_trace, line_length=0.1)
         >>> print(f"Z0 = {result.z0:.1f} ohms, delay = {result.propagation_delay*1e9:.2f} ns")
     """
-    from oscura.component.impedance import extract_impedance
+    from oscura.utils.component.impedance import extract_impedance
 
     # Speed of light
     c = 299792458.0
@@ -162,7 +162,7 @@ def characteristic_impedance(
         >>> z0 = characteristic_impedance(tdr_trace)
         >>> print(f"Z0 = {z0:.1f} ohms")
     """
-    from oscura.component.impedance import extract_impedance
+    from oscura.utils.component.impedance import extract_impedance
 
     z0, _ = extract_impedance(
         trace,

oscura/{filtering → utils/filtering}/__init__.py

@@ -6,20 +6,20 @@ Bessel, Elliptic), and convenience filters (moving average, median).
 
 
 Example:
-    >>> from oscura.filtering import LowPassFilter, design_filter
+    >>> from oscura.utils.filtering import LowPassFilter, design_filter
     >>> lpf = LowPassFilter(cutoff=1e6, sample_rate=10e6, order=4)
     >>> filtered_trace = lpf.apply(trace)
     >>> w, h = lpf.get_frequency_response()
 """
 
 # Import filters module as namespace for DSL compatibility
-from oscura.filtering import filters
-from oscura.filtering.base import (
+from oscura.utils.filtering import filters
+from oscura.utils.filtering.base import (
     Filter,
     FIRFilter,
     IIRFilter,
 )
-from oscura.filtering.convenience import (
+from oscura.utils.filtering.convenience import (
     band_pass,
     band_stop,
     high_pass,
@@ -30,7 +30,7 @@ from oscura.filtering.convenience import (
     notch_filter,
     savgol_filter,
 )
-from oscura.filtering.design import (
+from oscura.utils.filtering.design import (
     BandPassFilter,
     BandStopFilter,
     BesselFilter,
@@ -43,7 +43,7 @@ from oscura.filtering.design import (
     design_filter,
     design_filter_spec,
 )
-from oscura.filtering.introspection import (
+from oscura.utils.filtering.introspection import (
     FilterIntrospection,
     plot_bode,
     plot_impulse,

oscura/{filtering → utils/filtering}/base.py

@@ -453,7 +453,7 @@ class FIRFilter(Filter):
         # Check symmetry
         symmetric = np.allclose(self._coeffs, self._coeffs[::-1])
         antisymmetric = np.allclose(self._coeffs, -self._coeffs[::-1])
-        return symmetric or antisymmetric  # type: ignore[no-any-return]
+        return symmetric or antisymmetric
 
     def apply(
         self,

oscura/{filtering → utils/filtering}/convenience.py

@@ -5,7 +5,7 @@ moving average, median filter, Savitzky-Golay smoothing, and matched
 filtering.
 
 Example:
-    >>> from oscura.filtering.convenience import low_pass, moving_average
+    >>> from oscura.utils.filtering.convenience import low_pass, moving_average
     >>> filtered = low_pass(trace, cutoff=1e6)
     >>> smoothed = moving_average(trace, window_size=11)
 """
@@ -19,7 +19,7 @@ from scipy import ndimage, signal
 
 from oscura.core.exceptions import AnalysisError
 from oscura.core.types import WaveformTrace
-from oscura.filtering.design import (
+from oscura.utils.filtering.design import (
     BandPassFilter,
     BandStopFilter,
     HighPassFilter,