phased-array-systems 0.1.0__py3-none-any.whl

phased_array_systems/io/schema.py

@@ -0,0 +1,145 @@
+"""Configuration schema definitions using Pydantic."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from phased_array_systems.architecture import (
+    Architecture,
+    ArrayConfig,
+    CostConfig,
+    RFChainConfig,
+)
+from phased_array_systems.requirements import Requirement, RequirementSet
+from phased_array_systems.scenarios import CommsLinkScenario, RadarDetectionScenario
+from phased_array_systems.types import ComparisonOp, Severity
+
+
+class RequirementConfig(BaseModel):
+    """Configuration for a single requirement."""
+
+    id: str
+    name: str
+    metric_key: str
+    op: ComparisonOp
+    value: float
+    units: str | None = None
+    severity: Severity = "must"
+
+    def to_requirement(self) -> Requirement:
+        """Convert to Requirement object."""
+        return Requirement(
+            id=self.id,
+            name=self.name,
+            metric_key=self.metric_key,
+            op=self.op,
+            value=self.value,
+            units=self.units,
+            severity=self.severity,
+        )
+
+
+class DesignVariableConfig(BaseModel):
+    """Configuration for a design variable in DOE studies."""
+
+    name: str = Field(description="Variable name (e.g., 'array.nx')")
+    type: Literal["int", "float", "categorical"] = "float"
+    low: float | None = Field(default=None, description="Lower bound")
+    high: float | None = Field(default=None, description="Upper bound")
+    values: list[Any] | None = Field(default=None, description="Categorical values")
+
+
+class DOEConfig(BaseModel):
+    """Configuration for Design of Experiments."""
+
+    method: Literal["grid", "random", "lhs"] = "lhs"
+    n_samples: int = Field(default=100, ge=1, description="Number of samples")
+    seed: int | None = Field(default=None, description="Random seed")
+    variables: list[DesignVariableConfig] = Field(default_factory=list)
+
+
+class StudyConfig(BaseModel):
+    """Top-level configuration for a study.
+
+    Supports both single-case evaluation and DOE trade studies.
+
+    Example YAML:
+        ```yaml
+        name: "Comms Array Study"
+        architecture:
+          array:
+            nx: 8
+            ny: 8
+            dx_lambda: 0.5
+          rf:
+            tx_power_w_per_elem: 1.0
+        scenario:
+          type: comms
+          freq_hz: 10e9
+          bandwidth_hz: 10e6
+          range_m: 100e3
+          required_snr_db: 10.0
+        requirements:
+          - id: REQ-001
+            name: Minimum EIRP
+            metric_key: eirp_dbw
+            op: ">="
+            value: 40.0
+        ```
+    """
+
+    name: str = Field(default="Unnamed Study", description="Study name")
+    version: str = Field(default="1.0", description="Config version")
+
+    # Architecture configuration
+    architecture: Architecture | None = None
+    array: ArrayConfig | None = Field(default=None, description="Array config (shorthand)")
+    rf: RFChainConfig | None = Field(default=None, description="RF config (shorthand)")
+    cost: CostConfig | None = Field(default=None, description="Cost config (shorthand)")
+
+    # Scenario configuration
+    scenario: dict[str, Any] | None = Field(default=None, description="Scenario definition")
+
+    # Requirements
+    requirements: list[RequirementConfig] = Field(default_factory=list)
+
+    # DOE configuration (optional, for trade studies)
+    doe: DOEConfig | None = None
+
+    # Output configuration
+    output_dir: str = Field(default="./results", description="Output directory")
+    output_format: Literal["parquet", "csv", "json"] = "parquet"
+
+    def get_architecture(self) -> Architecture:
+        """Get the Architecture object, building from shorthand if needed."""
+        if self.architecture is not None:
+            return self.architecture
+
+        # Build from shorthand configs
+        array = self.array or ArrayConfig(nx=8, ny=8)
+        rf = self.rf or RFChainConfig(tx_power_w_per_elem=1.0)
+        cost = self.cost or CostConfig()
+
+        return Architecture(array=array, rf=rf, cost=cost, name=self.name)
+
+    def get_scenario(self) -> CommsLinkScenario | RadarDetectionScenario | None:
+        """Get the Scenario object from config."""
+        if self.scenario is None:
+            return None
+
+        scenario_dict = self.scenario.copy()
+        scenario_type = scenario_dict.pop("type", "comms")
+
+        if scenario_type == "comms":
+            return CommsLinkScenario(**scenario_dict)
+        elif scenario_type == "radar":
+            return RadarDetectionScenario(**scenario_dict)
+        else:
+            raise ValueError(f"Unknown scenario type: {scenario_type}")
+
+    def get_requirement_set(self) -> RequirementSet:
+        """Get RequirementSet from config."""
+        req_set = RequirementSet(name=f"{self.name} Requirements")
+        for req_config in self.requirements:
+            req_set.add(req_config.to_requirement())
+        return req_set

phased_array_systems/models/__init__.py

@@ -0,0 +1,5 @@
+"""Model blocks for system analysis."""
+
+from phased_array_systems.models.base import ModelBlock
+
+__all__ = ["ModelBlock"]

phased_array_systems/models/antenna/__init__.py

@@ -0,0 +1,15 @@
+"""Antenna modeling adapter wrapping phased-array-modeling."""
+
+from phased_array_systems.models.antenna.adapter import PhasedArrayAdapter
+from phased_array_systems.models.antenna.metrics import (
+    compute_beamwidth,
+    compute_scan_loss,
+    compute_sidelobe_level,
+)
+
+__all__ = [
+    "PhasedArrayAdapter",
+    "compute_beamwidth",
+    "compute_scan_loss",
+    "compute_sidelobe_level",
+]

phased_array_systems/models/antenna/adapter.py

@@ -0,0 +1,190 @@
+"""Adapter wrapping phased-array-modeling for consistent metric extraction."""
+
+from typing import Any
+
+import numpy as np
+
+from phased_array_systems.architecture import Architecture
+from phased_array_systems.models.antenna.metrics import (
+    compute_beamwidth,
+    compute_directivity_rectangular,
+    compute_scan_loss,
+    compute_sidelobe_level,
+)
+from phased_array_systems.types import MetricsDict, Scenario
+
+# Try to import phased-array-modeling, fall back to stub if not available
+try:
+    from phased_array_modeling import (
+        RectangularArray,
+        compute_array_factor,
+    )
+
+    HAS_PAM = True
+except ImportError:
+    HAS_PAM = False
+
+
+class PhasedArrayAdapter:
+    """Adapter for phased-array-modeling library.
+
+    Provides a consistent interface for computing antenna pattern metrics
+    using the phased-array-modeling library, with fallback to analytical
+    approximations when the library is not available.
+
+    Attributes:
+        name: Model block name for identification
+        use_analytical_fallback: If True, use analytical approximations
+            when phased-array-modeling is not available
+    """
+
+    name: str = "antenna"
+
+    def __init__(self, use_analytical_fallback: bool = True):
+        """Initialize the adapter.
+
+        Args:
+            use_analytical_fallback: Use analytical methods if PAM unavailable
+        """
+        self.use_analytical_fallback = use_analytical_fallback
+
+        if not HAS_PAM and not use_analytical_fallback:
+            raise ImportError(
+                "phased-array-modeling not installed. Install with: "
+                "pip install phased-array-modeling"
+            )
+
+    def evaluate(
+        self, arch: Architecture, scenario: Scenario, context: dict[str, Any]
+    ) -> MetricsDict:
+        """Evaluate antenna performance metrics.
+
+        Args:
+            arch: Architecture configuration
+            scenario: Scenario with frequency and scan angle info
+            context: Additional context (unused)
+
+        Returns:
+            Dictionary with antenna metrics:
+                - g_peak_db: Peak array gain (dB)
+                - beamwidth_az_deg: Azimuth beamwidth (degrees)
+                - beamwidth_el_deg: Elevation beamwidth (degrees)
+                - sll_db: Peak sidelobe level (dB, negative)
+                - scan_loss_db: Scan loss at operating angle (dB)
+                - directivity_db: Array directivity (dB)
+                - n_elements: Number of array elements
+        """
+        # Extract scan angle from scenario if available
+        scan_angle_deg = getattr(scenario, "scan_angle_deg", 0.0)
+
+        if HAS_PAM:
+            return self._evaluate_with_pam(arch, scenario, scan_angle_deg)
+        else:
+            return self._evaluate_analytical(arch, scenario, scan_angle_deg)
+
+    def _evaluate_with_pam(
+        self, arch: Architecture, scenario: Scenario, scan_angle_deg: float
+    ) -> MetricsDict:
+        """Evaluate using phased-array-modeling library."""
+        wavelength_m = scenario.wavelength_m if hasattr(scenario, "wavelength_m") else None
+
+        if wavelength_m is None:
+            from phased_array_systems.constants import C
+            wavelength_m = C / scenario.freq_hz
+
+        # Create array object
+        array = RectangularArray(
+            nx=arch.array.nx,
+            ny=arch.array.ny,
+            dx=arch.array.dx_lambda * wavelength_m,
+            dy=arch.array.dy_lambda * wavelength_m,
+        )
+
+        # Compute array factor over theta range
+        theta_deg = np.linspace(-90, 90, 361)
+        theta_rad = np.radians(theta_deg)
+
+        # Compute AF at phi=0 (azimuth cut)
+        af_az = compute_array_factor(
+            array,
+            theta_rad,
+            phi=0,
+            wavelength=wavelength_m,
+            scan_theta=np.radians(scan_angle_deg),
+            scan_phi=0,
+        )
+        af_az_db = 20 * np.log10(np.abs(af_az) + 1e-12)
+        af_az_db = af_az_db - np.max(af_az_db)  # Normalize to peak
+
+        # Compute AF at phi=90 (elevation cut)
+        af_el = compute_array_factor(
+            array,
+            theta_rad,
+            phi=np.pi / 2,
+            wavelength=wavelength_m,
+            scan_theta=np.radians(scan_angle_deg),
+            scan_phi=0,
+        )
+        af_el_db = 20 * np.log10(np.abs(af_el) + 1e-12)
+        af_el_db = af_el_db - np.max(af_el_db)
+
+        # Extract metrics
+        beamwidth_az = compute_beamwidth(af_az_db, theta_deg)
+        beamwidth_el = compute_beamwidth(af_el_db, theta_deg)
+        sll = compute_sidelobe_level(af_az_db, theta_deg)
+        scan_loss = compute_scan_loss(scan_angle_deg)
+        directivity = compute_directivity_rectangular(
+            arch.array.nx, arch.array.ny, arch.array.dx_lambda, arch.array.dy_lambda
+        )
+        g_peak = directivity - scan_loss  # Account for scan loss
+
+        return {
+            "g_peak_db": g_peak,
+            "beamwidth_az_deg": beamwidth_az,
+            "beamwidth_el_deg": beamwidth_el,
+            "sll_db": sll,
+            "scan_loss_db": scan_loss,
+            "directivity_db": directivity,
+            "n_elements": arch.array.n_elements,
+        }
+
+    def _evaluate_analytical(
+        self, arch: Architecture, scenario: Scenario, scan_angle_deg: float
+    ) -> MetricsDict:
+        """Evaluate using analytical approximations.
+
+        Uses standard phased array formulas when the full simulation
+        library is not available.
+        """
+        # Directivity from aperture size
+        directivity_db = compute_directivity_rectangular(
+            arch.array.nx, arch.array.ny, arch.array.dx_lambda, arch.array.dy_lambda
+        )
+
+        # Scan loss
+        scan_loss = compute_scan_loss(scan_angle_deg)
+
+        # Peak gain (accounting for scan)
+        g_peak = directivity_db - scan_loss
+
+        # Beamwidth approximations for uniform rectangular array
+        # BW ≈ 0.886 * lambda / (N * d) in radians, for uniform taper
+        # With d in wavelengths: BW ≈ 0.886 / (N * d_lambda) radians
+        bw_az_rad = 0.886 / (arch.array.nx * arch.array.dx_lambda)
+        bw_el_rad = 0.886 / (arch.array.ny * arch.array.dy_lambda)
+
+        beamwidth_az_deg = np.degrees(bw_az_rad)
+        beamwidth_el_deg = np.degrees(bw_el_rad)
+
+        # Sidelobe level for uniform taper (theoretical: -13.2 dB)
+        sll_db = -13.2
+
+        return {
+            "g_peak_db": g_peak,
+            "beamwidth_az_deg": beamwidth_az_deg,
+            "beamwidth_el_deg": beamwidth_el_deg,
+            "sll_db": sll_db,
+            "scan_loss_db": scan_loss,
+            "directivity_db": directivity_db,
+            "n_elements": arch.array.n_elements,
+        }

phased_array_systems/models/antenna/metrics.py

@@ -0,0 +1,166 @@
+"""Antenna pattern metric extraction utilities."""
+
+import math
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def compute_beamwidth(
+    pattern_db: NDArray[np.floating],
+    angles_deg: NDArray[np.floating],
+    level_db: float = -3.0,
+) -> float:
+    """Compute beamwidth at specified level below peak.
+
+    Args:
+        pattern_db: Pattern magnitude in dB
+        angles_deg: Corresponding angles in degrees
+        level_db: Level below peak to measure (default -3 dB)
+
+    Returns:
+        Beamwidth in degrees, or NaN if not found
+    """
+    peak_db = np.max(pattern_db)
+    threshold = peak_db + level_db  # level_db is negative
+
+    # Find peak index
+    peak_idx = np.argmax(pattern_db)
+
+    # Search left from peak
+    left_idx = peak_idx
+    for i in range(peak_idx, -1, -1):
+        if pattern_db[i] < threshold:
+            left_idx = i
+            break
+
+    # Search right from peak
+    right_idx = peak_idx
+    for i in range(peak_idx, len(pattern_db)):
+        if pattern_db[i] < threshold:
+            right_idx = i
+            break
+
+    if left_idx == peak_idx or right_idx == peak_idx:
+        return float("nan")
+
+    # Linear interpolation for more accurate crossing points
+    left_angle = np.interp(threshold, [pattern_db[left_idx], pattern_db[left_idx + 1]],
+                           [angles_deg[left_idx], angles_deg[left_idx + 1]])
+    right_angle = np.interp(threshold, [pattern_db[right_idx], pattern_db[right_idx - 1]],
+                            [angles_deg[right_idx], angles_deg[right_idx - 1]])
+
+    return abs(right_angle - left_angle)
+
+
+def compute_sidelobe_level(
+    pattern_db: NDArray[np.floating],
+    angles_deg: NDArray[np.floating],
+    main_lobe_width_deg: float | None = None,
+) -> float:
+    """Compute peak sidelobe level relative to main beam.
+
+    Args:
+        pattern_db: Pattern magnitude in dB
+        angles_deg: Corresponding angles in degrees
+        main_lobe_width_deg: Width of main lobe to exclude (auto-detected if None)
+
+    Returns:
+        Peak sidelobe level in dB (negative value)
+    """
+    peak_db = np.max(pattern_db)
+    peak_idx = np.argmax(pattern_db)
+    peak_angle = angles_deg[peak_idx]
+
+    # Auto-detect main lobe width if not provided
+    if main_lobe_width_deg is None:
+        bw = compute_beamwidth(pattern_db, angles_deg, -3.0)
+        if np.isnan(bw):
+            bw = 10.0  # Default fallback
+        main_lobe_width_deg = bw * 2  # Use 2x beamwidth as exclusion zone
+
+    # Mask out main lobe region
+    half_width = main_lobe_width_deg / 2
+    mask = np.abs(angles_deg - peak_angle) > half_width
+
+    if not np.any(mask):
+        return float("-inf")
+
+    sidelobe_pattern = pattern_db[mask]
+    peak_sidelobe_db = np.max(sidelobe_pattern)
+
+    return peak_sidelobe_db - peak_db
+
+
+def compute_scan_loss(scan_angle_deg: float, model: str = "cosine") -> float:
+    """Compute scan loss for a phased array at given scan angle.
+
+    Args:
+        scan_angle_deg: Scan angle from boresight (degrees)
+        model: Scan loss model ("cosine" or "cosine_squared")
+
+    Returns:
+        Scan loss in dB (positive value representing loss)
+    """
+    if scan_angle_deg >= 90:
+        return float("inf")
+
+    scan_rad = math.radians(scan_angle_deg)
+
+    if model == "cosine":
+        # Standard cos(theta) scan loss
+        loss_linear = math.cos(scan_rad)
+    elif model == "cosine_squared":
+        # More aggressive cos^2(theta) model
+        loss_linear = math.cos(scan_rad) ** 2
+    else:
+        raise ValueError(f"Unknown scan loss model: {model}")
+
+    if loss_linear <= 0:
+        return float("inf")
+
+    return -10 * math.log10(loss_linear)
+
+
+def compute_array_gain(n_elements: int, element_gain_db: float = 0.0) -> float:
+    """Compute ideal array gain.
+
+    Args:
+        n_elements: Number of array elements
+        element_gain_db: Individual element gain (dB)
+
+    Returns:
+        Array gain in dB
+    """
+    if n_elements < 1:
+        raise ValueError("n_elements must be >= 1")
+
+    array_factor_db = 10 * math.log10(n_elements)
+    return element_gain_db + array_factor_db
+
+
+def compute_directivity_rectangular(
+    nx: int, ny: int, dx_lambda: float, dy_lambda: float
+) -> float:
+    """Estimate directivity for a rectangular array.
+
+    Uses the approximation: D = pi * (2*nx*dx) * (2*ny*dy) for large arrays.
+
+    Args:
+        nx: Number of elements in x
+        ny: Number of elements in y
+        dx_lambda: Element spacing in x (wavelengths)
+        dy_lambda: Element spacing in y (wavelengths)
+
+    Returns:
+        Directivity in dB
+    """
+    # Aperture dimensions in wavelengths
+    lx = nx * dx_lambda
+    ly = ny * dy_lambda
+
+    # Directivity approximation for uniform aperture
+    # D ≈ 4*pi*A/lambda^2 = 4*pi*Lx*Ly (when Lx, Ly in wavelengths)
+    directivity_linear = 4 * math.pi * lx * ly
+
+    return 10 * math.log10(directivity_linear)

phased_array_systems/models/base.py

@@ -0,0 +1,30 @@
+"""Base model block protocol and utilities."""
+
+from typing import Any, Protocol, runtime_checkable
+
+from phased_array_systems.types import MetricsDict, Scenario
+
+
+@runtime_checkable
+class ModelBlock(Protocol):
+    """Protocol for model blocks that evaluate architecture/scenario combinations.
+
+    All model blocks must implement evaluate() and return a flat metrics dictionary.
+    The metrics dictionary uses the canonical metric keys defined in the package
+    documentation.
+    """
+
+    name: str
+
+    def evaluate(self, arch: Any, scenario: Scenario, context: dict[str, Any]) -> MetricsDict:
+        """Evaluate the model and return metrics.
+
+        Args:
+            arch: Architecture configuration object
+            scenario: Scenario configuration object
+            context: Additional context (e.g., results from other models)
+
+        Returns:
+            Dictionary of metric_name -> value pairs
+        """
+        ...

phased_array_systems/models/comms/__init__.py

@@ -0,0 +1,9 @@
+"""Communications link budget models."""
+
+from phased_array_systems.models.comms.link_budget import CommsLinkModel
+from phased_array_systems.models.comms.propagation import compute_fspl
+
+__all__ = [
+    "CommsLinkModel",
+    "compute_fspl",
+]