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

phased_array_systems/models/comms/link_budget.py

@@ -0,0 +1,171 @@
+"""Communications link budget model."""
+
+import math
+from typing import Any
+
+from phased_array_systems.architecture import Architecture
+from phased_array_systems.constants import K_B, W_TO_DBW
+from phased_array_systems.models.comms.propagation import compute_fspl
+from phased_array_systems.scenarios import CommsLinkScenario
+from phased_array_systems.types import MetricsDict
+
+
+class CommsLinkModel:
+    """Communications link budget calculator.
+
+    Computes EIRP, received power, noise power, SNR, and link margin
+    for a point-to-point or satellite communications link.
+
+    Link Budget Equations:
+        EIRP = P_tx_total + G_tx - L_tx
+        P_rx = EIRP - L_path + G_rx
+        N = 10*log10(k*T*B) + NF
+        SNR = P_rx - N
+        Margin = SNR - required_SNR
+
+    Attributes:
+        name: Model block name for identification
+    """
+
+    name: str = "comms_link"
+
+    def evaluate(
+        self,
+        arch: Architecture,
+        scenario: CommsLinkScenario,
+        context: dict[str, Any],
+    ) -> MetricsDict:
+        """Evaluate communications link budget.
+
+        Args:
+            arch: Architecture configuration
+            scenario: Communications link scenario
+            context: Additional context, may include antenna metrics:
+                - g_peak_db: Antenna gain (uses this if provided)
+                - scan_loss_db: Scan loss (uses this if provided)
+
+        Returns:
+            Dictionary with link budget metrics:
+                - tx_power_total_dbw: Total transmit power (dBW)
+                - tx_power_per_elem_dbw: TX power per element (dBW)
+                - g_tx_db: Transmit antenna gain (dB)
+                - eirp_dbw: Effective Isotropic Radiated Power (dBW)
+                - path_loss_db: Total path loss (dB)
+                - g_rx_db: Receive antenna gain (dB)
+                - rx_power_dbw: Received power (dBW)
+                - noise_power_dbw: Noise power (dBW)
+                - snr_rx_db: Received SNR (dB)
+                - link_margin_db: Link margin (dB)
+        """
+        # Get transmit power
+        n_elements = arch.array.n_elements
+        tx_power_per_elem_w = arch.rf.tx_power_w_per_elem
+        tx_power_total_w = tx_power_per_elem_w * n_elements
+        tx_power_total_dbw = W_TO_DBW(tx_power_total_w)
+        tx_power_per_elem_dbw = W_TO_DBW(tx_power_per_elem_w)
+
+        # Get antenna gain from context or compute approximate
+        if "g_peak_db" in context:
+            g_tx_db = context["g_peak_db"]
+        else:
+            # Approximate gain for uniform array
+            # G = 4*pi*A/lambda^2 ≈ pi * nx * dx * ny * dy * 4
+            aperture_area_lambda_sq = (
+                arch.array.nx * arch.array.dx_lambda *
+                arch.array.ny * arch.array.dy_lambda
+            )
+            g_tx_linear = 4 * math.pi * aperture_area_lambda_sq
+            g_tx_db = 10 * math.log10(g_tx_linear)
+
+            # Apply scan loss if provided
+            if "scan_loss_db" in context:
+                g_tx_db -= context["scan_loss_db"]
+
+        # Transmit losses (feed network + system)
+        tx_loss_db = arch.rf.feed_loss_db + arch.rf.system_loss_db
+
+        # EIRP
+        eirp_dbw = tx_power_total_dbw + g_tx_db - tx_loss_db
+
+        # Path loss
+        if scenario.path_loss_model == "fspl":
+            path_loss_db = compute_fspl(scenario.freq_hz, scenario.range_m)
+        else:
+            raise ValueError(f"Unknown path loss model: {scenario.path_loss_model}")
+
+        # Add extra losses
+        total_path_loss_db = path_loss_db + scenario.total_extra_loss_db
+
+        # Receive antenna gain (isotropic if not specified)
+        g_rx_db = scenario.rx_antenna_gain_db if scenario.rx_antenna_gain_db is not None else 0.0
+
+        # Received power
+        rx_power_dbw = eirp_dbw - total_path_loss_db + g_rx_db
+
+        # Noise power: N = k*T*B
+        noise_power_w = K_B * scenario.rx_noise_temp_k * scenario.bandwidth_hz
+        noise_power_dbw = W_TO_DBW(noise_power_w)
+
+        # Add receiver noise figure
+        noise_power_dbw += arch.rf.noise_figure_db
+
+        # SNR
+        snr_rx_db = rx_power_dbw - noise_power_dbw
+
+        # Link margin
+        link_margin_db = snr_rx_db - scenario.required_snr_db
+
+        return {
+            "tx_power_total_dbw": tx_power_total_dbw,
+            "tx_power_per_elem_dbw": tx_power_per_elem_dbw,
+            "g_tx_db": g_tx_db,
+            "eirp_dbw": eirp_dbw,
+            "path_loss_db": total_path_loss_db,
+            "fspl_db": path_loss_db,
+            "g_rx_db": g_rx_db,
+            "rx_power_dbw": rx_power_dbw,
+            "noise_power_dbw": noise_power_dbw,
+            "snr_rx_db": snr_rx_db,
+            "link_margin_db": link_margin_db,
+            "required_snr_db": scenario.required_snr_db,
+        }
+
+
+def compute_link_margin(
+    eirp_dbw: float,
+    path_loss_db: float,
+    g_rx_db: float,
+    noise_temp_k: float,
+    bandwidth_hz: float,
+    noise_figure_db: float,
+    required_snr_db: float,
+) -> dict[str, float]:
+    """Standalone link margin calculation.
+
+    Convenience function for quick link budget calculations
+    without full Architecture/Scenario objects.
+
+    Args:
+        eirp_dbw: Effective Isotropic Radiated Power (dBW)
+        path_loss_db: Total path loss (dB)
+        g_rx_db: Receive antenna gain (dB)
+        noise_temp_k: System noise temperature (K)
+        bandwidth_hz: Signal bandwidth (Hz)
+        noise_figure_db: Receiver noise figure (dB)
+        required_snr_db: Required SNR for demodulation (dB)
+
+    Returns:
+        Dictionary with rx_power_dbw, noise_power_dbw, snr_db, margin_db
+    """
+    rx_power_dbw = eirp_dbw - path_loss_db + g_rx_db
+    noise_power_w = K_B * noise_temp_k * bandwidth_hz
+    noise_power_dbw = W_TO_DBW(noise_power_w) + noise_figure_db
+    snr_db = rx_power_dbw - noise_power_dbw
+    margin_db = snr_db - required_snr_db
+
+    return {
+        "rx_power_dbw": rx_power_dbw,
+        "noise_power_dbw": noise_power_dbw,
+        "snr_db": snr_db,
+        "margin_db": margin_db,
+    }

phased_array_systems/models/comms/propagation.py

@@ -0,0 +1,84 @@
+"""Propagation loss models for communications links."""
+
+import math
+
+from phased_array_systems.constants import C
+
+
+def compute_fspl(freq_hz: float, range_m: float) -> float:
+    """Compute Free Space Path Loss (FSPL).
+
+    FSPL = 20*log10(4*pi*d*f/c)
+         = 20*log10(d) + 20*log10(f) + 20*log10(4*pi/c)
+         = 20*log10(d) + 20*log10(f) - 147.55 (with d in m, f in Hz)
+
+    Args:
+        freq_hz: Frequency in Hz
+        range_m: Range/distance in meters
+
+    Returns:
+        Free space path loss in dB (positive value)
+    """
+    if freq_hz <= 0:
+        raise ValueError("Frequency must be positive")
+    if range_m <= 0:
+        raise ValueError("Range must be positive")
+
+    wavelength = C / freq_hz
+    fspl_linear = (4 * math.pi * range_m / wavelength) ** 2
+    return 10 * math.log10(fspl_linear)
+
+
+def compute_fspl_wavelength(wavelength_m: float, range_m: float) -> float:
+    """Compute FSPL given wavelength directly.
+
+    Args:
+        wavelength_m: Wavelength in meters
+        range_m: Range/distance in meters
+
+    Returns:
+        Free space path loss in dB (positive value)
+    """
+    if wavelength_m <= 0:
+        raise ValueError("Wavelength must be positive")
+    if range_m <= 0:
+        raise ValueError("Range must be positive")
+
+    fspl_linear = (4 * math.pi * range_m / wavelength_m) ** 2
+    return 10 * math.log10(fspl_linear)
+
+
+def compute_two_ray_path_loss(
+    freq_hz: float,
+    range_m: float,
+    h_tx_m: float,
+    h_rx_m: float,
+) -> float:
+    """Compute two-ray ground reflection path loss.
+
+    At short ranges, behaves like FSPL. At long ranges (beyond crossover
+    distance), follows d^4 attenuation.
+
+    Args:
+        freq_hz: Frequency in Hz
+        range_m: Horizontal range in meters
+        h_tx_m: Transmitter height in meters
+        h_rx_m: Receiver height in meters
+
+    Returns:
+        Path loss in dB (positive value)
+    """
+    wavelength = C / freq_hz
+
+    # Crossover distance
+    d_cross = 4 * h_tx_m * h_rx_m / wavelength
+
+    if range_m < d_cross:
+        # Use FSPL in near region
+        return compute_fspl(freq_hz, range_m)
+    else:
+        # Two-ray model: PL = 40*log10(d) - 20*log10(ht*hr)
+        # Normalized to match FSPL at crossover
+        pl_cross = compute_fspl(freq_hz, d_cross)
+        pl_two_ray = pl_cross + 40 * math.log10(range_m / d_cross)
+        return pl_two_ray

phased_array_systems/models/swapc/__init__.py

@@ -0,0 +1,9 @@
+"""Size, Weight, Power, and Cost (SWaP-C) models."""
+
+from phased_array_systems.models.swapc.cost import CostModel
+from phased_array_systems.models.swapc.power import PowerModel
+
+__all__ = [
+    "CostModel",
+    "PowerModel",
+]

phased_array_systems/models/swapc/cost.py

@@ -0,0 +1,98 @@
+"""Cost models for phased array systems."""
+
+from typing import Any
+
+from phased_array_systems.architecture import Architecture
+from phased_array_systems.types import MetricsDict, Scenario
+
+
+class CostModel:
+    """Parametric cost model for phased array systems.
+
+    Computes recurring and non-recurring costs based on
+    array size and cost parameters.
+
+    Cost Equations:
+        Recurring_cost = n_elements * cost_per_element
+        Total_cost = Recurring_cost + NRE + Integration
+
+    Attributes:
+        name: Model block name for identification
+    """
+
+    name: str = "cost"
+
+    def evaluate(
+        self,
+        arch: Architecture,
+        scenario: Scenario,
+        context: dict[str, Any],
+    ) -> MetricsDict:
+        """Evaluate cost metrics.
+
+        Args:
+            arch: Architecture configuration
+            scenario: Scenario (unused for basic cost model)
+            context: Additional context (unused)
+
+        Returns:
+            Dictionary with cost metrics:
+                - recurring_cost_usd: Element-based recurring cost (USD)
+                - nre_usd: Non-recurring engineering cost (USD)
+                - integration_cost_usd: System integration cost (USD)
+                - total_cost_usd: Total system cost (USD)
+                - cost_per_element_usd: Cost per element (USD)
+                - n_elements: Number of elements
+        """
+        n_elements = arch.array.n_elements
+        cost_per_elem = arch.cost.cost_per_elem_usd
+        nre = arch.cost.nre_usd
+        integration = arch.cost.integration_cost_usd
+
+        # Recurring cost (scales with elements)
+        recurring_cost = n_elements * cost_per_elem
+
+        # Total cost
+        total_cost = recurring_cost + nre + integration
+
+        return {
+            "recurring_cost_usd": recurring_cost,
+            "nre_usd": nre,
+            "integration_cost_usd": integration,
+            "total_cost_usd": total_cost,
+            "cost_per_element_usd": cost_per_elem,
+            "cost_usd": total_cost,  # Canonical metric name
+            "n_elements": n_elements,
+        }
+
+
+def compute_cost_per_watt(total_cost_usd: float, rf_power_w: float) -> float:
+    """Compute cost per Watt of RF power.
+
+    Args:
+        total_cost_usd: Total system cost (USD)
+        rf_power_w: RF output power (W)
+
+    Returns:
+        Cost per Watt (USD/W)
+    """
+    if rf_power_w <= 0:
+        return float("inf")
+    return total_cost_usd / rf_power_w
+
+
+def compute_cost_per_db(total_cost_usd: float, eirp_dbw: float) -> float:
+    """Compute cost per dBW of EIRP.
+
+    Useful for comparing cost-effectiveness of different architectures.
+
+    Args:
+        total_cost_usd: Total system cost (USD)
+        eirp_dbw: Effective Isotropic Radiated Power (dBW)
+
+    Returns:
+        Cost per dBW (USD/dBW)
+    """
+    if eirp_dbw <= 0:
+        return float("inf")
+    return total_cost_usd / eirp_dbw

phased_array_systems/models/swapc/power.py

@@ -0,0 +1,102 @@
+"""Power consumption models for phased array systems."""
+
+from typing import Any
+
+from phased_array_systems.architecture import Architecture
+from phased_array_systems.types import MetricsDict, Scenario
+
+
+class PowerModel:
+    """Power consumption calculator for phased array systems.
+
+    Computes DC power, RF power, and prime power based on
+    architecture parameters and efficiency factors.
+
+    Power Equations:
+        RF_power = n_elements * tx_power_per_elem
+        DC_power = RF_power / pa_efficiency
+        Prime_power = DC_power * (1 + overhead_factor)
+
+    Attributes:
+        name: Model block name for identification
+        overhead_factor: Additional power overhead (cooling, control, etc.)
+    """
+
+    name: str = "power"
+
+    def __init__(self, overhead_factor: float = 0.2):
+        """Initialize power model.
+
+        Args:
+            overhead_factor: Fraction of DC power for overhead (default 20%)
+        """
+        self.overhead_factor = overhead_factor
+
+    def evaluate(
+        self,
+        arch: Architecture,
+        scenario: Scenario,
+        context: dict[str, Any],
+    ) -> MetricsDict:
+        """Evaluate power metrics.
+
+        Args:
+            arch: Architecture configuration
+            scenario: Scenario (may influence duty cycle)
+            context: Additional context (unused)
+
+        Returns:
+            Dictionary with power metrics:
+                - rf_power_w: Total RF output power (W)
+                - dc_power_w: DC power consumption (W)
+                - prime_power_w: Prime/wall power (W)
+                - pa_efficiency: Power amplifier efficiency
+                - n_elements: Number of array elements
+        """
+        n_elements = arch.array.n_elements
+        tx_power_per_elem = arch.rf.tx_power_w_per_elem
+        pa_efficiency = arch.rf.pa_efficiency
+
+        # RF power
+        rf_power_w = n_elements * tx_power_per_elem
+
+        # DC power (accounting for PA efficiency)
+        dc_power_w = rf_power_w / pa_efficiency
+
+        # Prime power (including overhead)
+        prime_power_w = dc_power_w * (1 + self.overhead_factor)
+
+        return {
+            "rf_power_w": rf_power_w,
+            "dc_power_w": dc_power_w,
+            "prime_power_w": prime_power_w,
+            "pa_efficiency": pa_efficiency,
+            "n_elements": n_elements,
+        }
+
+
+def compute_thermal_load(
+    dc_power_w: float,
+    rf_power_w: float,
+    additional_dissipation_w: float = 0.0,
+) -> dict[str, float]:
+    """Compute thermal dissipation for heat management.
+
+    Args:
+        dc_power_w: Total DC power consumption (W)
+        rf_power_w: RF power radiated (W)
+        additional_dissipation_w: Other heat sources (W)
+
+    Returns:
+        Dictionary with thermal metrics:
+            - heat_dissipation_w: Total heat to remove (W)
+            - rf_efficiency: Fraction of DC converted to RF
+    """
+    # Heat = DC input - RF output + additional sources
+    heat_dissipation_w = dc_power_w - rf_power_w + additional_dissipation_w
+    rf_efficiency = rf_power_w / dc_power_w if dc_power_w > 0 else 0.0
+
+    return {
+        "heat_dissipation_w": heat_dissipation_w,
+        "rf_efficiency": rf_efficiency,
+    }

phased_array_systems/requirements/__init__.py

@@ -0,0 +1,15 @@
+"""Requirements capture and verification subsystem."""
+
+from phased_array_systems.requirements.core import (
+    Requirement,
+    RequirementResult,
+    RequirementSet,
+    VerificationReport,
+)
+
+__all__ = [
+    "Requirement",
+    "RequirementResult",
+    "RequirementSet",
+    "VerificationReport",
+]