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

phased_array_systems/__about__.py

@@ -0,0 +1,4 @@
+"""Version and metadata for phased-array-systems."""
+
+__version__ = "0.1.0"
+__author__ = "phased-array-systems contributors"

phased_array_systems/__init__.py

@@ -0,0 +1,10 @@
+"""
+phased-array-systems: Phased array antenna system design, optimization, and visualization.
+
+This package implements an MBSE/MDAO workflow for phased array system design:
+requirements -> architecture -> analytical models -> trade studies -> Pareto selection -> reporting.
+"""
+
+from phased_array_systems.__about__ import __version__
+
+__all__ = ["__version__"]

phased_array_systems/architecture/__init__.py

@@ -0,0 +1,15 @@
+"""Architecture configuration subsystem."""
+
+from phased_array_systems.architecture.config import (
+    Architecture,
+    ArrayConfig,
+    CostConfig,
+    RFChainConfig,
+)
+
+__all__ = [
+    "Architecture",
+    "ArrayConfig",
+    "CostConfig",
+    "RFChainConfig",
+]

phased_array_systems/architecture/config.py

@@ -0,0 +1,152 @@
+"""Architecture configuration models using Pydantic."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ArrayConfig(BaseModel):
+    """Configuration for the antenna array geometry.
+
+    Attributes:
+        geometry: Array geometry type
+        nx: Number of elements in x-direction
+        ny: Number of elements in y-direction
+        dx_lambda: Element spacing in x-direction (wavelengths)
+        dy_lambda: Element spacing in y-direction (wavelengths)
+        scan_limit_deg: Maximum scan angle from boresight (degrees)
+    """
+
+    geometry: Literal["rectangular", "circular", "triangular"] = "rectangular"
+    nx: int = Field(ge=1, description="Number of elements in x-direction")
+    ny: int = Field(ge=1, description="Number of elements in y-direction")
+    dx_lambda: float = Field(default=0.5, gt=0, description="Element spacing in x (wavelengths)")
+    dy_lambda: float = Field(default=0.5, gt=0, description="Element spacing in y (wavelengths)")
+    scan_limit_deg: float = Field(
+        default=60.0, ge=0, le=90, description="Maximum scan angle (degrees)"
+    )
+
+    @property
+    def n_elements(self) -> int:
+        """Total number of elements in the array."""
+        return self.nx * self.ny
+
+
+class RFChainConfig(BaseModel):
+    """Configuration for the RF chain.
+
+    Attributes:
+        tx_power_w_per_elem: Transmit power per element (Watts)
+        pa_efficiency: Power amplifier efficiency (0-1)
+        noise_figure_db: Receiver noise figure (dB)
+        n_tx_beams: Number of simultaneous transmit beams
+        feed_loss_db: Feed network loss (dB)
+        system_loss_db: Additional system losses (dB)
+    """
+
+    tx_power_w_per_elem: float = Field(gt=0, description="TX power per element (W)")
+    pa_efficiency: float = Field(
+        default=0.3, gt=0, le=1, description="PA efficiency (0-1)"
+    )
+    noise_figure_db: float = Field(
+        default=3.0, ge=0, description="Noise figure (dB)"
+    )
+    n_tx_beams: int = Field(default=1, ge=1, description="Number of TX beams")
+    feed_loss_db: float = Field(default=1.0, ge=0, description="Feed network loss (dB)")
+    system_loss_db: float = Field(default=0.0, ge=0, description="Additional system losses (dB)")
+
+    @field_validator("pa_efficiency")
+    @classmethod
+    def validate_efficiency(cls, v: float) -> float:
+        if not 0 < v <= 1:
+            raise ValueError("PA efficiency must be between 0 and 1")
+        return v
+
+
+class CostConfig(BaseModel):
+    """Configuration for cost modeling.
+
+    Attributes:
+        cost_per_elem_usd: Recurring cost per element (USD)
+        nre_usd: Non-recurring engineering cost (USD)
+        integration_cost_usd: System integration cost (USD)
+    """
+
+    cost_per_elem_usd: float = Field(default=100.0, ge=0, description="Cost per element (USD)")
+    nre_usd: float = Field(default=0.0, ge=0, description="NRE cost (USD)")
+    integration_cost_usd: float = Field(
+        default=0.0, ge=0, description="Integration cost (USD)"
+    )
+
+
+class Architecture(BaseModel):
+    """Complete system architecture configuration.
+
+    This is the top-level configuration object that contains all
+    subsystem configurations.
+
+    Attributes:
+        array: Antenna array configuration
+        rf: RF chain configuration
+        cost: Cost model configuration
+        name: Optional name for this architecture
+    """
+
+    array: ArrayConfig
+    rf: RFChainConfig
+    cost: CostConfig = Field(default_factory=CostConfig)
+    name: str | None = Field(default=None, description="Architecture name")
+
+    @property
+    def n_elements(self) -> int:
+        """Total number of elements (convenience property)."""
+        return self.array.n_elements
+
+    def model_dump_flat(self) -> dict:
+        """Return a flattened dictionary of all configuration values.
+
+        Useful for DOE case generation where we need flat parameter names.
+        """
+        flat = {}
+        for prefix, config in [
+            ("array", self.array),
+            ("rf", self.rf),
+            ("cost", self.cost),
+        ]:
+            for key, value in config.model_dump().items():
+                flat[f"{prefix}.{key}"] = value
+        if self.name:
+            flat["name"] = self.name
+        return flat
+
+    @classmethod
+    def from_flat(cls, flat_dict: dict) -> "Architecture":
+        """Create an Architecture from a flattened dictionary.
+
+        Args:
+            flat_dict: Dictionary with keys like "array.nx", "rf.tx_power_w_per_elem"
+
+        Returns:
+            Architecture instance
+        """
+        array_dict = {}
+        rf_dict = {}
+        cost_dict = {}
+        name = None
+
+        for key, value in flat_dict.items():
+            if key == "name":
+                name = value
+            elif key.startswith("array."):
+                array_dict[key.replace("array.", "")] = value
+            elif key.startswith("rf."):
+                rf_dict[key.replace("rf.", "")] = value
+            elif key.startswith("cost."):
+                cost_dict[key.replace("cost.", "")] = value
+
+        return cls(
+            array=ArrayConfig(**array_dict),
+            rf=RFChainConfig(**rf_dict),
+            cost=CostConfig(**cost_dict) if cost_dict else CostConfig(),
+            name=name,
+        )

phased_array_systems/cli.py

@@ -0,0 +1,25 @@
+"""Command-line interface for phased-array-systems.
+
+Planned for Phase 4 implementation.
+"""
+
+import sys
+
+
+def main():
+    """Entry point for the pasys CLI."""
+    print("phased-array-systems CLI")
+    print("=" * 40)
+    print("CLI implementation planned for Phase 4.")
+    print()
+    print("For now, use the Python API directly:")
+    print("  - Single case: examples/01_comms_single_case.py")
+    print("  - DOE study: examples/02_comms_doe_trade.py")
+    print()
+    print("See documentation at:")
+    print("  https://github.com/phased-array-systems/phased-array-systems")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

phased_array_systems/constants.py

@@ -0,0 +1,55 @@
+"""Physical constants used throughout the package."""
+
+import math
+
+# Speed of light in vacuum [m/s]
+C = 299_792_458.0
+
+# Boltzmann constant [J/K]
+K_B = 1.380649e-23
+
+# Standard reference temperature [K]
+T_REF = 290.0
+
+# Pi (for convenience)
+PI = math.pi
+
+
+# Conversion functions
+def db_to_linear(db: float) -> float:
+    """Convert dB to linear scale (power)."""
+    return 10 ** (db / 10)
+
+
+def linear_to_db(linear: float) -> float:
+    """Convert linear scale to dB (power)."""
+    return 10 * math.log10(linear) if linear > 0 else float("-inf")
+
+
+def dbw_to_w(dbw: float) -> float:
+    """Convert dBW to Watts."""
+    return 10 ** (dbw / 10)
+
+
+def w_to_dbw(w: float) -> float:
+    """Convert Watts to dBW."""
+    return 10 * math.log10(w) if w > 0 else float("-inf")
+
+
+def db_to_linear_voltage(db: float) -> float:
+    """Convert dB to linear scale (voltage/amplitude)."""
+    return 10 ** (db / 20)
+
+
+def linear_to_db_voltage(linear: float) -> float:
+    """Convert linear scale to dB (voltage/amplitude)."""
+    return 20 * math.log10(linear) if linear > 0 else float("-inf")
+
+
+# Backward-compatible aliases (uppercase)
+DB_TO_LINEAR = db_to_linear
+LINEAR_TO_DB = linear_to_db
+DBW_TO_W = dbw_to_w
+W_TO_DBW = w_to_dbw
+DB_TO_LINEAR_VOLTAGE = db_to_linear_voltage
+LINEAR_TO_DB_VOLTAGE = linear_to_db_voltage

phased_array_systems/evaluate.py

@@ -0,0 +1,136 @@
+"""Single-case evaluation orchestrator."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+from phased_array_systems.architecture import Architecture
+from phased_array_systems.models.antenna import PhasedArrayAdapter
+from phased_array_systems.models.comms import CommsLinkModel
+from phased_array_systems.models.swapc import CostModel, PowerModel
+from phased_array_systems.requirements import RequirementSet, VerificationReport
+from phased_array_systems.scenarios import CommsLinkScenario, RadarDetectionScenario
+from phased_array_systems.types import MetricsDict, Scenario
+
+if TYPE_CHECKING:
+    from phased_array_systems.io.schema import StudyConfig
+
+
+def evaluate_case(
+    arch: Architecture,
+    scenario: Scenario,
+    requirements: RequirementSet | None = None,
+    case_id: str | None = None,
+) -> MetricsDict:
+    """Evaluate a single architecture/scenario case.
+
+    Runs all applicable models and returns merged metrics dictionary.
+    Optionally verifies against requirements and includes verification results.
+
+    Args:
+        arch: Architecture configuration
+        scenario: Scenario configuration (CommsLinkScenario or RadarDetectionScenario)
+        requirements: Optional requirement set for verification
+        case_id: Optional case identifier for tracking
+
+    Returns:
+        Dictionary containing all computed metrics plus metadata:
+            - All antenna metrics (g_peak_db, beamwidth_*, sll_db, etc.)
+            - All link/radar metrics (eirp_dbw, snr_*, margin_*, etc.)
+            - All SWaP-C metrics (power_*, cost_*)
+            - Verification results if requirements provided
+            - Metadata (case_id, runtime_s)
+    """
+    start_time = time.perf_counter()
+    metrics: MetricsDict = {}
+
+    # Add case ID if provided
+    if case_id is not None:
+        metrics["meta.case_id"] = case_id
+
+    # Initialize models
+    antenna_model = PhasedArrayAdapter(use_analytical_fallback=True)
+    power_model = PowerModel()
+    cost_model = CostModel()
+
+    # Evaluate antenna model first (provides gain for link budget)
+    antenna_metrics = antenna_model.evaluate(arch, scenario, {})
+    metrics.update(antenna_metrics)
+
+    # Create context with antenna results for downstream models
+    context: dict[str, Any] = dict(antenna_metrics)
+
+    # Evaluate SWaP-C models
+    power_metrics = power_model.evaluate(arch, scenario, context)
+    metrics.update(power_metrics)
+
+    cost_metrics = cost_model.evaluate(arch, scenario, context)
+    metrics.update(cost_metrics)
+
+    # Evaluate scenario-specific models
+    if isinstance(scenario, CommsLinkScenario):
+        comms_model = CommsLinkModel()
+        comms_metrics = comms_model.evaluate(arch, scenario, context)
+        metrics.update(comms_metrics)
+    elif isinstance(scenario, RadarDetectionScenario):
+        # Radar model placeholder (Phase 3)
+        metrics["meta.warning"] = "Radar model not yet implemented"
+
+    # Verify requirements if provided
+    if requirements is not None and len(requirements) > 0:
+        report = requirements.verify(metrics)
+        metrics["verification.passes"] = 1.0 if report.passes else 0.0
+        metrics["verification.must_pass_count"] = float(report.must_pass_count)
+        metrics["verification.must_total_count"] = float(report.must_total_count)
+        metrics["verification.failed_ids"] = ",".join(report.failed_ids) if report.failed_ids else ""
+
+    # Add timing metadata
+    elapsed = time.perf_counter() - start_time
+    metrics["meta.runtime_s"] = elapsed
+
+    return metrics
+
+
+def evaluate_case_with_report(
+    arch: Architecture,
+    scenario: Scenario,
+    requirements: RequirementSet,
+    case_id: str | None = None,
+) -> tuple[MetricsDict, VerificationReport]:
+    """Evaluate a case and return both metrics and full verification report.
+
+    Args:
+        arch: Architecture configuration
+        scenario: Scenario configuration
+        requirements: Requirement set for verification
+        case_id: Optional case identifier
+
+    Returns:
+        Tuple of (metrics dict, VerificationReport)
+    """
+    metrics = evaluate_case(arch, scenario, requirements, case_id)
+    report = requirements.verify(metrics)
+    return metrics, report
+
+
+def evaluate_config(config: StudyConfig) -> MetricsDict:
+    """Evaluate a case from a StudyConfig object.
+
+    Convenience function for config-driven evaluation.
+
+    Args:
+        config: StudyConfig object with architecture, scenario, requirements
+
+    Returns:
+        Metrics dictionary
+    """
+
+    arch = config.get_architecture()
+    scenario = config.get_scenario()
+    requirements = config.get_requirement_set()
+
+    if scenario is None:
+        raise ValueError("StudyConfig must have a scenario defined")
+
+    return evaluate_case(arch, scenario, requirements, case_id=config.name)

phased_array_systems/io/__init__.py

@@ -0,0 +1,13 @@
+"""Configuration I/O and data export utilities."""
+
+from phased_array_systems.io.config_loader import load_config
+from phased_array_systems.io.exporters import export_results, get_export_metadata, load_results
+from phased_array_systems.io.schema import StudyConfig
+
+__all__ = [
+    "StudyConfig",
+    "load_config",
+    "export_results",
+    "load_results",
+    "get_export_metadata",
+]

phased_array_systems/io/config_loader.py

@@ -0,0 +1,86 @@
+"""Configuration file loading utilities."""
+
+import json
+from pathlib import Path
+
+import yaml
+
+from phased_array_systems.io.schema import StudyConfig
+
+
+def load_config(path: str | Path) -> StudyConfig:
+    """Load a study configuration from a YAML or JSON file.
+
+    Args:
+        path: Path to configuration file (.yaml, .yml, or .json)
+
+    Returns:
+        Validated StudyConfig object
+
+    Raises:
+        FileNotFoundError: If config file doesn't exist
+        ValueError: If file format is not supported
+        ValidationError: If config validation fails
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Configuration file not found: {path}")
+
+    suffix = path.suffix.lower()
+
+    if suffix in (".yaml", ".yml"):
+        with open(path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    elif suffix == ".json":
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+    else:
+        raise ValueError(f"Unsupported config format: {suffix}. Use .yaml, .yml, or .json")
+
+    return StudyConfig.model_validate(data)
+
+
+def load_config_from_string(content: str, format: str = "yaml") -> StudyConfig:
+    """Load a study configuration from a string.
+
+    Args:
+        content: Configuration content as string
+        format: Format of the content ("yaml" or "json")
+
+    Returns:
+        Validated StudyConfig object
+    """
+    if format.lower() in ("yaml", "yml"):
+        data = yaml.safe_load(content)
+    elif format.lower() == "json":
+        data = json.loads(content)
+    else:
+        raise ValueError(f"Unsupported format: {format}")
+
+    return StudyConfig.model_validate(data)
+
+
+def save_config(config: StudyConfig, path: str | Path, format: str | None = None) -> None:
+    """Save a study configuration to a file.
+
+    Args:
+        config: StudyConfig object to save
+        path: Output file path
+        format: Output format (auto-detected from extension if None)
+    """
+    path = Path(path)
+
+    if format is None:
+        format = path.suffix.lower().lstrip(".")
+
+    data = config.model_dump(exclude_none=True)
+
+    if format in ("yaml", "yml"):
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+    elif format == "json":
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+    else:
+        raise ValueError(f"Unsupported format: {format}")

phased_array_systems/io/exporters.py

@@ -0,0 +1,171 @@
+"""Results export utilities."""
+
+import json
+from pathlib import Path
+from typing import Literal
+
+import pandas as pd
+
+
+def export_results(
+    results: pd.DataFrame,
+    path: str | Path,
+    format: Literal["parquet", "csv", "json"] | None = None,
+    include_metadata: bool = True,
+) -> Path:
+    """Export evaluation results to file.
+
+    Args:
+        results: DataFrame with evaluation results
+        path: Output file path
+        format: Output format (auto-detected from extension if None)
+        include_metadata: Include export metadata (timestamp, version)
+
+    Returns:
+        Path to exported file
+    """
+    path = Path(path)
+
+    if format is None:
+        suffix = path.suffix.lower()
+        if suffix == ".parquet":
+            format = "parquet"
+        elif suffix == ".csv":
+            format = "csv"
+        elif suffix == ".json":
+            format = "json"
+        else:
+            format = "parquet"  # Default
+
+    # Ensure parent directory exists
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if format == "parquet":
+        _export_parquet(results, path, include_metadata)
+    elif format == "csv":
+        _export_csv(results, path)
+    elif format == "json":
+        _export_json(results, path, include_metadata)
+    else:
+        raise ValueError(f"Unknown format: {format}")
+
+    return path
+
+
+def _export_parquet(
+    results: pd.DataFrame,
+    path: Path,
+    include_metadata: bool,
+) -> None:
+    """Export to Parquet format with optional metadata."""
+    import pyarrow as pa
+    import pyarrow.parquet as pq
+
+    table = pa.Table.from_pandas(results)
+
+    if include_metadata:
+        from datetime import datetime
+
+        from phased_array_systems import __version__
+
+        custom_meta = {
+            "export_timestamp": datetime.now().isoformat(),
+            "package_version": __version__,
+            "n_cases": str(len(results)),
+        }
+
+        existing_meta = table.schema.metadata or {}
+        merged_meta = {**existing_meta, **{k.encode(): v.encode() for k, v in custom_meta.items()}}
+        table = table.replace_schema_metadata(merged_meta)
+
+    pq.write_table(table, path)
+
+
+def _export_csv(results: pd.DataFrame, path: Path) -> None:
+    """Export to CSV format."""
+    results.to_csv(path, index=False)
+
+
+def _export_json(
+    results: pd.DataFrame,
+    path: Path,
+    include_metadata: bool,
+) -> None:
+    """Export to JSON format."""
+    data = results.to_dict(orient="records")
+
+    if include_metadata:
+        from datetime import datetime
+
+        from phased_array_systems import __version__
+
+        output = {
+            "metadata": {
+                "export_timestamp": datetime.now().isoformat(),
+                "package_version": __version__,
+                "n_cases": len(results),
+            },
+            "results": data,
+        }
+    else:
+        output = {"results": data}
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(output, f, indent=2, default=str)
+
+
+def load_results(path: str | Path) -> pd.DataFrame:
+    """Load previously exported results.
+
+    Args:
+        path: Path to results file
+
+    Returns:
+        DataFrame with results
+    """
+    path = Path(path)
+    suffix = path.suffix.lower()
+
+    if suffix == ".parquet":
+        return pd.read_parquet(path)
+    elif suffix == ".csv":
+        return pd.read_csv(path)
+    elif suffix == ".json":
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        if "results" in data:
+            return pd.DataFrame(data["results"])
+        else:
+            return pd.DataFrame(data)
+    else:
+        raise ValueError(f"Unknown format: {suffix}")
+
+
+def get_export_metadata(path: str | Path) -> dict | None:
+    """Get metadata from an exported results file.
+
+    Args:
+        path: Path to results file
+
+    Returns:
+        Metadata dictionary or None if no metadata
+    """
+    path = Path(path)
+    suffix = path.suffix.lower()
+
+    if suffix == ".parquet":
+        import pyarrow.parquet as pq
+
+        meta = pq.read_metadata(path)
+        if meta.schema.metadata:
+            return {k.decode(): v.decode() for k, v in meta.schema.metadata.items()
+                    if k.decode().startswith(("export_", "package_", "n_"))}
+        return None
+
+    elif suffix == ".json":
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        return data.get("metadata")
+
+    else:
+        return None