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

phased_array_systems/requirements/core.py

@@ -0,0 +1,244 @@
+"""Core requirement and verification classes."""
+
+from dataclasses import dataclass, field
+
+from phased_array_systems.types import ComparisonOp, MetricsDict, Severity
+
+
+@dataclass(frozen=True)
+class Requirement:
+    """A single requirement specification.
+
+    Attributes:
+        id: Unique identifier for the requirement (e.g., "REQ-001")
+        name: Human-readable name
+        metric_key: The key in the metrics dictionary to check
+        op: Comparison operator
+        value: Threshold value to compare against
+        units: Optional units string for documentation
+        severity: Importance level ("must", "should", "nice")
+    """
+
+    id: str
+    name: str
+    metric_key: str
+    op: ComparisonOp
+    value: float
+    units: str | None = None
+    severity: Severity = "must"
+
+    def check(self, actual_value: float) -> bool:
+        """Check if the actual value satisfies this requirement.
+
+        Args:
+            actual_value: The measured/computed value to check
+
+        Returns:
+            True if requirement is satisfied, False otherwise
+        """
+        if self.op == ">=":
+            return actual_value >= self.value
+        elif self.op == "<=":
+            return actual_value <= self.value
+        elif self.op == "==":
+            return actual_value == self.value
+        elif self.op == ">":
+            return actual_value > self.value
+        elif self.op == "<":
+            return actual_value < self.value
+        else:
+            raise ValueError(f"Unknown operator: {self.op}")
+
+    def compute_margin(self, actual_value: float) -> float:
+        """Compute the margin to the requirement threshold.
+
+        Positive margin means the requirement is satisfied with room to spare.
+        Negative margin means the requirement is not met.
+
+        Args:
+            actual_value: The measured/computed value
+
+        Returns:
+            Margin value (interpretation depends on operator)
+        """
+        if self.op in (">=", ">"):
+            return actual_value - self.value
+        elif self.op in ("<=", "<"):
+            return self.value - actual_value
+        else:  # ==
+            return -abs(actual_value - self.value)
+
+
+@dataclass
+class RequirementResult:
+    """Result of checking a single requirement.
+
+    Attributes:
+        requirement: The requirement that was checked
+        actual_value: The actual value from metrics (None if metric missing)
+        passes: Whether the requirement passed
+        margin: Margin to the threshold
+        error: Error message if metric was missing or check failed
+    """
+
+    requirement: Requirement
+    actual_value: float | None
+    passes: bool
+    margin: float | None
+    error: str | None = None
+
+
+@dataclass
+class VerificationReport:
+    """Complete verification report for a set of requirements.
+
+    Attributes:
+        passes: True if ALL 'must' requirements pass
+        results: List of individual requirement results
+        failed_ids: List of requirement IDs that failed
+        must_pass_count: Number of must requirements that passed
+        must_total_count: Total number of must requirements
+        should_pass_count: Number of should requirements that passed
+        should_total_count: Total number of should requirements
+    """
+
+    passes: bool
+    results: list[RequirementResult]
+    failed_ids: list[str]
+    must_pass_count: int = 0
+    must_total_count: int = 0
+    should_pass_count: int = 0
+    should_total_count: int = 0
+
+    def to_dict(self) -> dict:
+        """Convert report to dictionary for serialization."""
+        return {
+            "passes": self.passes,
+            "failed_ids": self.failed_ids,
+            "must_pass_count": self.must_pass_count,
+            "must_total_count": self.must_total_count,
+            "should_pass_count": self.should_pass_count,
+            "should_total_count": self.should_total_count,
+            "results": [
+                {
+                    "id": r.requirement.id,
+                    "name": r.requirement.name,
+                    "metric_key": r.requirement.metric_key,
+                    "threshold": r.requirement.value,
+                    "operator": r.requirement.op,
+                    "actual_value": r.actual_value,
+                    "passes": r.passes,
+                    "margin": r.margin,
+                    "severity": r.requirement.severity,
+                    "error": r.error,
+                }
+                for r in self.results
+            ],
+        }
+
+
+@dataclass
+class RequirementSet:
+    """A collection of requirements with verification capabilities.
+
+    Attributes:
+        requirements: List of requirements
+        name: Optional name for the requirement set
+    """
+
+    requirements: list[Requirement] = field(default_factory=list)
+    name: str | None = None
+
+    def add(self, requirement: Requirement) -> None:
+        """Add a requirement to the set."""
+        self.requirements.append(requirement)
+
+    def verify(self, metrics: MetricsDict) -> VerificationReport:
+        """Verify all requirements against provided metrics.
+
+        Args:
+            metrics: Dictionary of metric_name -> value
+
+        Returns:
+            VerificationReport with pass/fail status and margins
+        """
+        results: list[RequirementResult] = []
+        failed_ids: list[str] = []
+        must_pass = 0
+        must_total = 0
+        should_pass = 0
+        should_total = 0
+
+        for req in self.requirements:
+            # Track totals by severity
+            if req.severity == "must":
+                must_total += 1
+            elif req.severity == "should":
+                should_total += 1
+
+            # Check if metric exists
+            if req.metric_key not in metrics:
+                result = RequirementResult(
+                    requirement=req,
+                    actual_value=None,
+                    passes=False,
+                    margin=None,
+                    error=f"Metric '{req.metric_key}' not found in results",
+                )
+                failed_ids.append(req.id)
+            else:
+                actual = metrics[req.metric_key]
+                if actual is None or not isinstance(actual, (int, float)):
+                    result = RequirementResult(
+                        requirement=req,
+                        actual_value=None,
+                        passes=False,
+                        margin=None,
+                        error=f"Metric '{req.metric_key}' has invalid value: {actual}",
+                    )
+                    failed_ids.append(req.id)
+                else:
+                    actual_float = float(actual)
+                    passes = req.check(actual_float)
+                    margin = req.compute_margin(actual_float)
+                    result = RequirementResult(
+                        requirement=req,
+                        actual_value=actual_float,
+                        passes=passes,
+                        margin=margin,
+                    )
+                    if not passes:
+                        failed_ids.append(req.id)
+                    else:
+                        if req.severity == "must":
+                            must_pass += 1
+                        elif req.severity == "should":
+                            should_pass += 1
+
+            results.append(result)
+
+        # Overall pass requires all "must" requirements to pass
+        all_must_pass = must_pass == must_total
+
+        return VerificationReport(
+            passes=all_must_pass,
+            results=results,
+            failed_ids=failed_ids,
+            must_pass_count=must_pass,
+            must_total_count=must_total,
+            should_pass_count=should_pass,
+            should_total_count=should_total,
+        )
+
+    def get_by_id(self, req_id: str) -> Requirement | None:
+        """Get a requirement by its ID."""
+        for req in self.requirements:
+            if req.id == req_id:
+                return req
+        return None
+
+    def __len__(self) -> int:
+        return len(self.requirements)
+
+    def __iter__(self):
+        return iter(self.requirements)

phased_array_systems/scenarios/__init__.py

@@ -0,0 +1,11 @@
+"""Scenario definitions for communications and radar applications."""
+
+from phased_array_systems.scenarios.base import ScenarioBase
+from phased_array_systems.scenarios.comms import CommsLinkScenario
+from phased_array_systems.scenarios.radar import RadarDetectionScenario
+
+__all__ = [
+    "ScenarioBase",
+    "CommsLinkScenario",
+    "RadarDetectionScenario",
+]

phased_array_systems/scenarios/base.py

@@ -0,0 +1,30 @@
+"""Base scenario class and utilities."""
+
+from pydantic import BaseModel, Field
+
+from phased_array_systems.constants import C
+
+
+class ScenarioBase(BaseModel):
+    """Base class for all scenario types.
+
+    All scenarios must have a frequency, which is used to compute
+    wavelength and other frequency-dependent parameters.
+
+    Attributes:
+        freq_hz: Operating frequency in Hz
+        name: Optional name for the scenario
+    """
+
+    freq_hz: float = Field(gt=0, description="Operating frequency (Hz)")
+    name: str | None = Field(default=None, description="Scenario name")
+
+    @property
+    def wavelength_m(self) -> float:
+        """Wavelength in meters."""
+        return C / self.freq_hz
+
+    @property
+    def freq_ghz(self) -> float:
+        """Frequency in GHz."""
+        return self.freq_hz / 1e9

phased_array_systems/scenarios/comms.py

@@ -0,0 +1,56 @@
+"""Communications link scenario definition."""
+
+from typing import Literal
+
+from pydantic import Field
+
+from phased_array_systems.scenarios.base import ScenarioBase
+
+
+class CommsLinkScenario(ScenarioBase):
+    """Scenario for communications link budget analysis.
+
+    Defines the parameters needed for a point-to-point or
+    satellite communications link budget calculation.
+
+    Attributes:
+        freq_hz: Operating frequency (Hz)
+        bandwidth_hz: Signal bandwidth (Hz)
+        range_m: Link range/distance (meters)
+        required_snr_db: Required SNR for demodulation (dB)
+        scan_angle_deg: Beam scan angle from boresight (degrees)
+        rx_antenna_gain_db: Receive antenna gain (dB), None for isotropic
+        rx_noise_temp_k: Receive system noise temperature (K)
+        path_loss_model: Propagation model to use
+        atmospheric_loss_db: Additional atmospheric losses (dB)
+        rain_loss_db: Rain fade margin (dB)
+        polarization_loss_db: Polarization mismatch loss (dB)
+    """
+
+    bandwidth_hz: float = Field(gt=0, description="Signal bandwidth (Hz)")
+    range_m: float = Field(gt=0, description="Link range (m)")
+    required_snr_db: float = Field(description="Required SNR (dB)")
+    scan_angle_deg: float = Field(
+        default=0.0, ge=0, le=90, description="Scan angle from boresight (deg)"
+    )
+    rx_antenna_gain_db: float | None = Field(
+        default=None, description="RX antenna gain (dB), None for isotropic"
+    )
+    rx_noise_temp_k: float = Field(
+        default=290.0, gt=0, description="RX system noise temperature (K)"
+    )
+    path_loss_model: Literal["fspl"] = Field(
+        default="fspl", description="Path loss model"
+    )
+    atmospheric_loss_db: float = Field(
+        default=0.0, ge=0, description="Atmospheric loss (dB)"
+    )
+    rain_loss_db: float = Field(default=0.0, ge=0, description="Rain loss margin (dB)")
+    polarization_loss_db: float = Field(
+        default=0.0, ge=0, description="Polarization loss (dB)"
+    )
+
+    @property
+    def total_extra_loss_db(self) -> float:
+        """Total additional losses beyond free space path loss."""
+        return self.atmospheric_loss_db + self.rain_loss_db + self.polarization_loss_db

phased_array_systems/scenarios/radar.py

@@ -0,0 +1,42 @@
+"""Radar detection scenario definition (stub for Phase 3)."""
+
+from typing import Literal
+
+from pydantic import Field
+
+from phased_array_systems.scenarios.base import ScenarioBase
+
+
+class RadarDetectionScenario(ScenarioBase):
+    """Scenario for radar detection analysis.
+
+    Note: Full implementation planned for Phase 3.
+
+    Attributes:
+        freq_hz: Operating frequency (Hz)
+        bandwidth_hz: Signal bandwidth (Hz)
+        range_m: Target range (meters)
+        target_rcs_dbsm: Target radar cross section (dBsm)
+        pfa: Probability of false alarm
+        pd_required: Required probability of detection
+        n_pulses: Number of pulses integrated
+        scan_angle_deg: Beam scan angle from boresight (degrees)
+        integration_type: Coherent or non-coherent integration
+    """
+
+    bandwidth_hz: float = Field(gt=0, description="Signal bandwidth (Hz)")
+    range_m: float = Field(gt=0, description="Target range (m)")
+    target_rcs_dbsm: float = Field(description="Target RCS (dBsm)")
+    pfa: float = Field(
+        default=1e-6, gt=0, lt=1, description="Probability of false alarm"
+    )
+    pd_required: float = Field(
+        default=0.9, gt=0, lt=1, description="Required probability of detection"
+    )
+    n_pulses: int = Field(default=1, ge=1, description="Number of pulses integrated")
+    scan_angle_deg: float = Field(
+        default=0.0, ge=0, le=90, description="Scan angle from boresight (deg)"
+    )
+    integration_type: Literal["coherent", "noncoherent"] = Field(
+        default="noncoherent", description="Integration type"
+    )

phased_array_systems/trades/__init__.py

@@ -0,0 +1,16 @@
+"""Trade study tools: DOE, batch evaluation, Pareto analysis."""
+
+from phased_array_systems.trades.design_space import DesignSpace, DesignVariable
+from phased_array_systems.trades.doe import generate_doe
+from phased_array_systems.trades.pareto import extract_pareto, filter_feasible, rank_pareto
+from phased_array_systems.trades.runner import BatchRunner
+
+__all__ = [
+    "DesignSpace",
+    "DesignVariable",
+    "generate_doe",
+    "BatchRunner",
+    "extract_pareto",
+    "filter_feasible",
+    "rank_pareto",
+]

phased_array_systems/trades/design_space.py

@@ -0,0 +1,241 @@
+"""Design space definition for DOE studies."""
+
+from typing import Any, Literal
+
+import numpy as np
+import pandas as pd
+from pydantic import BaseModel, Field, model_validator
+
+
+class DesignVariable(BaseModel):
+    """Definition of a single design variable.
+
+    Supports continuous (float), discrete (int), and categorical variables.
+
+    Attributes:
+        name: Variable name, typically a dot-path like "array.nx"
+        type: Variable type ("int", "float", or "categorical")
+        low: Lower bound for continuous/discrete variables
+        high: Upper bound for continuous/discrete variables
+        values: List of allowed values for categorical variables
+    """
+
+    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")
+
+    @model_validator(mode="after")
+    def validate_bounds_or_values(self) -> "DesignVariable":
+        """Ensure proper bounds/values are set based on type."""
+        if self.type in ("int", "float"):
+            if self.low is None or self.high is None:
+                raise ValueError(f"Variable '{self.name}': low and high required for {self.type}")
+            if self.low > self.high:
+                raise ValueError(f"Variable '{self.name}': low must be <= high")
+        elif self.type == "categorical":
+            if not self.values or len(self.values) < 1:
+                raise ValueError(f"Variable '{self.name}': values required for categorical")
+        return self
+
+    def sample_uniform(self, n: int, rng: np.random.Generator) -> np.ndarray:
+        """Generate uniform random samples.
+
+        Args:
+            n: Number of samples
+            rng: NumPy random generator
+
+        Returns:
+            Array of sampled values
+        """
+        if self.type == "float":
+            return rng.uniform(self.low, self.high, n)
+        elif self.type == "int":
+            return rng.integers(int(self.low), int(self.high) + 1, n)
+        else:  # categorical
+            indices = rng.integers(0, len(self.values), n)
+            return np.array([self.values[i] for i in indices])
+
+    def scale_from_unit(self, unit_values: np.ndarray) -> np.ndarray:
+        """Scale values from [0, 1] to actual variable range.
+
+        Args:
+            unit_values: Values in [0, 1]
+
+        Returns:
+            Scaled values in variable's actual range
+        """
+        if self.type == "float":
+            return self.low + unit_values * (self.high - self.low)
+        elif self.type == "int":
+            scaled = self.low + unit_values * (self.high - self.low + 1)
+            return np.floor(scaled).astype(int).clip(int(self.low), int(self.high))
+        else:  # categorical
+            indices = np.floor(unit_values * len(self.values)).astype(int)
+            indices = indices.clip(0, len(self.values) - 1)
+            return np.array([self.values[i] for i in indices])
+
+    def get_grid_values(self, n_levels: int) -> list[Any]:
+        """Get grid values for this variable.
+
+        Args:
+            n_levels: Number of levels for grid
+
+        Returns:
+            List of values at each level
+        """
+        if self.type == "float":
+            return list(np.linspace(self.low, self.high, n_levels))
+        elif self.type == "int":
+            # For integers, use actual integer values
+            all_ints = list(range(int(self.low), int(self.high) + 1))
+            if len(all_ints) <= n_levels:
+                return all_ints
+            # Subsample evenly
+            indices = np.linspace(0, len(all_ints) - 1, n_levels).astype(int)
+            return [all_ints[i] for i in indices]
+        else:  # categorical
+            return list(self.values)
+
+
+class DesignSpace(BaseModel):
+    """Collection of design variables defining a design space.
+
+    Provides methods for sampling the design space using various
+    DOE methods (grid, random, LHS).
+
+    Attributes:
+        variables: List of design variables
+        name: Optional name for the design space
+    """
+
+    variables: list[DesignVariable] = Field(default_factory=list)
+    name: str | None = None
+
+    def add_variable(
+        self,
+        name: str,
+        type: Literal["int", "float", "categorical"] = "float",
+        low: float | None = None,
+        high: float | None = None,
+        values: list[Any] | None = None,
+    ) -> "DesignSpace":
+        """Add a variable to the design space (fluent interface).
+
+        Args:
+            name: Variable name
+            type: Variable type
+            low: Lower bound
+            high: Upper bound
+            values: Categorical values
+
+        Returns:
+            Self for chaining
+        """
+        var = DesignVariable(name=name, type=type, low=low, high=high, values=values)
+        self.variables.append(var)
+        return self
+
+    @property
+    def n_dims(self) -> int:
+        """Number of dimensions (variables) in the design space."""
+        return len(self.variables)
+
+    @property
+    def variable_names(self) -> list[str]:
+        """List of variable names."""
+        return [v.name for v in self.variables]
+
+    def sample(
+        self,
+        method: Literal["grid", "random", "lhs"] = "lhs",
+        n_samples: int = 100,
+        seed: int | None = None,
+        grid_levels: int | list[int] | None = None,
+    ) -> pd.DataFrame:
+        """Sample the design space.
+
+        Args:
+            method: Sampling method ("grid", "random", "lhs")
+            n_samples: Number of samples (ignored for grid method)
+            seed: Random seed for reproducibility
+            grid_levels: Number of levels per variable for grid method
+
+        Returns:
+            DataFrame with columns for each variable plus 'case_id'
+        """
+        if method == "grid":
+            return self._sample_grid(grid_levels)
+        elif method == "random":
+            return self._sample_random(n_samples, seed)
+        elif method == "lhs":
+            return self._sample_lhs(n_samples, seed)
+        else:
+            raise ValueError(f"Unknown sampling method: {method}")
+
+    def _sample_grid(self, grid_levels: int | list[int] | None) -> pd.DataFrame:
+        """Generate full factorial grid."""
+        if grid_levels is None:
+            grid_levels = 3  # Default
+
+        if isinstance(grid_levels, int):
+            levels_per_var = [grid_levels] * len(self.variables)
+        else:
+            levels_per_var = grid_levels
+
+        # Generate grid values for each variable
+        var_values = []
+        for var, n_levels in zip(self.variables, levels_per_var, strict=True):
+            var_values.append(var.get_grid_values(n_levels))
+
+        # Create full factorial grid using meshgrid
+        grids = np.meshgrid(*var_values, indexing="ij")
+        flat_grids = [g.flatten() for g in grids]
+
+        # Build DataFrame
+        data = {var.name: flat_grids[i] for i, var in enumerate(self.variables)}
+        df = pd.DataFrame(data)
+
+        # Add case IDs
+        df.insert(0, "case_id", [f"case_{i:05d}" for i in range(len(df))])
+
+        return df
+
+    def _sample_random(self, n_samples: int, seed: int | None) -> pd.DataFrame:
+        """Generate random samples."""
+        rng = np.random.default_rng(seed)
+
+        data = {}
+        for var in self.variables:
+            data[var.name] = var.sample_uniform(n_samples, rng)
+
+        df = pd.DataFrame(data)
+        df.insert(0, "case_id", [f"case_{i:05d}" for i in range(len(df))])
+
+        return df
+
+    def _sample_lhs(self, n_samples: int, seed: int | None) -> pd.DataFrame:
+        """Generate Latin Hypercube samples."""
+        from scipy.stats import qmc
+
+        # Generate LHS in unit hypercube
+        sampler = qmc.LatinHypercube(d=len(self.variables), seed=seed)
+        unit_samples = sampler.random(n_samples)
+
+        # Scale to actual variable ranges
+        data = {}
+        for i, var in enumerate(self.variables):
+            data[var.name] = var.scale_from_unit(unit_samples[:, i])
+
+        df = pd.DataFrame(data)
+        df.insert(0, "case_id", [f"case_{i:05d}" for i in range(len(df))])
+
+        return df
+
+    def get_variable(self, name: str) -> DesignVariable | None:
+        """Get a variable by name."""
+        for var in self.variables:
+            if var.name == name:
+                return var
+        return None