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

oscura/cli/characterize.py

@@ -17,6 +17,8 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 import click
+import numpy as np
+from numpy.typing import NDArray
 
 from oscura.cli.main import format_output
 
@@ -26,16 +28,16 @@ if TYPE_CHECKING:
 logger = logging.getLogger("oscura.cli.characterize")
 
 
-@click.command()  # type: ignore[misc]
-@click.argument("file", type=click.Path(exists=True))  # type: ignore[misc]
-@click.option(  # type: ignore[misc]
+@click.command()
+@click.argument("file", type=click.Path(exists=True))
+@click.option(
     "--type",
     "analysis_type",
     type=click.Choice(["buffer", "signal", "power"], case_sensitive=False),
     default="buffer",
     help="Type of characterization to perform.",
 )
-@click.option(  # type: ignore[misc]
+@click.option(
     "--logic-family",
     type=click.Choice(
         ["TTL", "CMOS", "CMOS_3V3", "CMOS_5V", "LVTTL", "LVCMOS", "auto"],
@@ -44,25 +46,25 @@ logger = logging.getLogger("oscura.cli.characterize")
     default="auto",
     help="Logic family for buffer characterization (default: auto-detect).",
 )
-@click.option(  # type: ignore[misc]
+@click.option(
     "--compare",
     type=click.Path(exists=True),
     default=None,
     help="Reference file for comparison analysis.",
 )
-@click.option(  # type: ignore[misc]
+@click.option(
     "--output",
     type=click.Choice(["json", "csv", "html", "table"], case_sensitive=False),
     default="table",
     help="Output format (default: table).",
 )
-@click.option(  # type: ignore[misc]
+@click.option(
     "--save-report",
     type=click.Path(),
     default=None,
     help="Save HTML report to file.",
 )
-@click.pass_context  # type: ignore[misc]
+@click.pass_context
 def characterize(
     ctx: click.Context,
     file: str,
@@ -179,21 +181,37 @@ def _perform_characterization(
     Returns:
         Dictionary of analysis results.
     """
-    import numpy as np
+    results = _build_basic_results(trace, analysis_type, logic_family)
 
-    from oscura.analyzers.waveform.measurements import (
-        fall_time,
-        overshoot,
-        rise_time,
-        undershoot,
-    )
-    from oscura.comparison.compare import compare_traces, similarity_score
-    from oscura.inference import detect_logic_family
+    if analysis_type == "buffer":
+        _add_buffer_results(results, trace, logic_family)
+    elif analysis_type == "signal":
+        _add_signal_results(results, trace.data)
+    elif analysis_type == "power":
+        _add_power_results(results, trace)
+
+    # Add comparison results if reference provided
+    if reference_trace is not None:
+        _add_comparison_results(results, trace, reference_trace)
+
+    return results
+
+
+def _build_basic_results(trace: Any, analysis_type: str, logic_family: str) -> dict[str, Any]:
+    """Build basic results dictionary with metadata.
 
+    Args:
+        trace: Trace to analyze.
+        analysis_type: Type of analysis.
+        logic_family: Logic family string.
+
+    Returns:
+        Dictionary with basic metadata.
+    """
     sample_rate = trace.metadata.sample_rate
     data = trace.data
 
-    results: dict[str, Any] = {
+    return {
         "analysis_type": analysis_type,
         "logic_family": logic_family,
         "sample_rate": f"{sample_rate / 1e6:.1f} MHz",
@@ -201,73 +219,110 @@ def _perform_characterization(
         "duration": f"{len(data) / sample_rate * 1e3:.3f} ms",
     }
 
-    if analysis_type == "buffer":
-        # Buffer characterization using actual workflow (WRK-001)
-        # Functions expect WaveformTrace, not ndarray
-        rt = rise_time(trace)
-        ft = fall_time(trace)
-        os_pct = overshoot(trace)
-        us_pct = undershoot(trace)
-
-        results.update(
-            {
-                "rise_time": f"{rt * 1e9:.2f} ns" if not np.isnan(rt) else "N/A",
-                "fall_time": f"{ft * 1e9:.2f} ns" if not np.isnan(ft) else "N/A",
-                "overshoot": f"{os_pct:.1f} %" if not np.isnan(os_pct) else "N/A",
-                "undershoot": f"{us_pct:.1f} %" if not np.isnan(us_pct) else "N/A",
-                "status": "PASS",
-            }
-        )
 
-        # Logic family detection
-        if logic_family == "auto":
-            detected = detect_logic_family(trace)
-            # detect_logic_family returns dict with 'primary' key
-            primary = detected.get("primary", {})
-            results["logic_family_detected"] = primary.get("name", "unknown")
-            results["confidence"] = f"{primary.get('confidence', 0) * 100:.0f}%"
-        else:
-            results["logic_family_detected"] = logic_family
+def _add_buffer_results(results: dict[str, Any], trace: Any, logic_family: str) -> None:
+    """Add buffer characterization results.
 
-    elif analysis_type == "signal":
-        # Signal analysis
-        results.update(
-            {
-                "amplitude": f"{float(data.max() - data.min()):.3f} V",
-                "peak_to_peak": f"{float(data.max() - data.min()):.3f} V",
-                "mean": f"{float(data.mean()):.3f} V",
-                "rms": f"{float(np.sqrt((data**2).mean())):.3f} V",
-            }
-        )
+    Args:
+        results: Results dict to update.
+        trace: Trace to analyze.
+        logic_family: Logic family string.
+    """
+    import numpy as np
 
-    elif analysis_type == "power":
-        # Power analysis - compute power statistics directly from voltage
-        # Assume voltage trace, compute power (P = V^2/R, assume R=1 for relative)
-        power_data = data**2
-        avg_pwr = float(np.mean(power_data))
-        peak_pwr = float(np.max(power_data))
-        total_energy = float(np.sum(power_data) / sample_rate)
-
-        results.update(
-            {
-                "average_power": f"{avg_pwr * 1e3:.3f} mW",
-                "peak_power": f"{peak_pwr * 1e3:.3f} mW",
-                "energy": f"{total_energy * 1e6:.3f} uJ",
-            }
-        )
+    from oscura.analyzers.waveform.measurements import (
+        fall_time,
+        overshoot,
+        rise_time,
+        undershoot,
+    )
+    from oscura.inference import detect_logic_family
 
-    # Add comparison results if reference provided
-    if reference_trace is not None:
-        ref_data = reference_trace.data
-        # similarity_score expects WaveformTrace objects
-        sim = similarity_score(trace, reference_trace)
-        # compare_traces returns ComparisonResult dataclass
-        comparison_result = compare_traces(trace, reference_trace)
-
-        results["comparison"] = {
-            "correlation": f"{comparison_result.correlation:.4f}",
-            "amplitude_difference": f"{abs(float(data.mean()) - float(ref_data.mean())):.3f} V",
-            "similarity": f"{sim * 100:.1f}%",
+    rt = rise_time(trace)
+    ft = fall_time(trace)
+    os_pct = overshoot(trace)
+    us_pct = undershoot(trace)
+
+    results.update(
+        {
+            "rise_time": f"{rt * 1e9:.2f} ns" if not np.isnan(rt) else "N/A",
+            "fall_time": f"{ft * 1e9:.2f} ns" if not np.isnan(ft) else "N/A",
+            "overshoot": f"{os_pct:.1f} %" if not np.isnan(os_pct) else "N/A",
+            "undershoot": f"{us_pct:.1f} %" if not np.isnan(us_pct) else "N/A",
+            "status": "PASS",
         }
+    )
 
-    return results
+    # Logic family detection
+    if logic_family == "auto":
+        detected = detect_logic_family(trace)
+        primary = detected.get("primary", {})
+        results["logic_family_detected"] = primary.get("name", "unknown")
+        results["confidence"] = f"{primary.get('confidence', 0) * 100:.0f}%"
+    else:
+        results["logic_family_detected"] = logic_family
+
+
+def _add_signal_results(results: dict[str, Any], data: NDArray[np.floating[Any]]) -> None:
+    """Add signal characterization results.
+
+    Args:
+        results: Results dict to update.
+        data: Signal data array.
+    """
+    results.update(
+        {
+            "amplitude": f"{float(data.max() - data.min()):.3f} V",
+            "peak_to_peak": f"{float(data.max() - data.min()):.3f} V",
+            "mean": f"{float(data.mean()):.3f} V",
+            "rms": f"{float(np.sqrt((data**2).mean())):.3f} V",
+        }
+    )
+
+
+def _add_power_results(results: dict[str, Any], trace: Any) -> None:
+    """Add power analysis results.
+
+    Args:
+        results: Results dict to update.
+        trace: Trace to analyze.
+    """
+    import numpy as np
+
+    data = trace.data
+    sample_rate = trace.metadata.sample_rate
+
+    # Compute power (P = V^2/R, assume R=1 for relative)
+    power_data = data**2
+    avg_pwr = float(np.mean(power_data))
+    peak_pwr = float(np.max(power_data))
+    total_energy = float(np.sum(power_data) / sample_rate)
+
+    results.update(
+        {
+            "average_power": f"{avg_pwr * 1e3:.3f} mW",
+            "peak_power": f"{peak_pwr * 1e3:.3f} mW",
+            "energy": f"{total_energy * 1e6:.3f} uJ",
+        }
+    )
+
+
+def _add_comparison_results(results: dict[str, Any], trace: Any, reference_trace: Any) -> None:
+    """Add comparison results to results dictionary.
+
+    Args:
+        results: Results dict to update.
+        trace: Main trace.
+        reference_trace: Reference trace.
+    """
+    from oscura.utils.comparison.compare import compare_traces, similarity_score
+
+    ref_data = reference_trace.data
+    sim = similarity_score(trace, reference_trace)
+    comparison_result = compare_traces(trace, reference_trace)
+
+    results["comparison"] = {
+        "correlation": f"{comparison_result.correlation:.4f}",
+        "amplitude_difference": f"{abs(float(trace.data.mean()) - float(ref_data.mean())):.3f} V",
+        "similarity": f"{sim * 100:.1f}%",
+    }