phased-array-systems 0.1.0__tar.gz → 0.1.2__tar.gz

{phased_array_systems-0.1.0 → phased_array_systems-0.1.2}/.gitignore

@@ -144,3 +144,4 @@ results/
 *.parquet
 *.csv
 !examples/configs/*.yaml
+package_design_and_requirements.txt

{phased_array_systems-0.1.0 → phased_array_systems-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phased-array-systems
-Version: 0.1.0
+Version: 0.1.2
 Summary: Phased array antenna system design, optimization, and performance visualization
 Project-URL: Homepage, https://github.com/jman4162/phased-array-systems
 Project-URL: Documentation, https://github.com/jman4162/phased-array-systems#readme

{phased_array_systems-0.1.0 → phased_array_systems-0.1.2}/src/phased_array_systems/__about__.py

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

{phased_array_systems-0.1.0 → phased_array_systems-0.1.2}/src/phased_array_systems/models/antenna/metrics.py

@@ -119,7 +119,8 @@ def compute_scan_loss(scan_angle_deg: float, model: str = "cosine") -> float:
     if loss_linear <= 0:
         return float("inf")
 
-    return -10 * math.log10(loss_linear)
+    loss_db = -10 * math.log10(loss_linear)
+    return abs(loss_db) if abs(loss_db) < 1e-10 else loss_db  # Avoid -0.0 display
 
 
 def compute_array_gain(n_elements: int, element_gain_db: float = 0.0) -> float:

phased_array_systems-0.1.0/package_design_and_requirements.txt

@@ -1,531 +0,0 @@
-```markdown
-# Phased Array Systems — Software Design Document (SDD) & Requirements
-**Package name (working):** `phased-array-systems`  
-**Purpose:** Open-source Python package for phased array antenna **system design**, **optimization**, and **performance visualization** for advanced **wireless communications** and **radar** applications.  
-**Core dependency:** [`phased-array-modeling`](https://pypi.org/project/phased-array-modeling/) / [`Phased-Array-Antenna-Model`](https://github.com/jman4162/Phased-Array-Antenna-Model)  
-
----
-
-## Table of Contents
-1. Purpose and Scope  
-2. Design Principles (MBSE/MDAO Inspired)  
-3. Users and Primary Use Cases  
-4. Non-Goals  
-5. System Overview and Architecture  
-   - 5.1 High-level Architecture  
-   - 5.2 Package Structure (Completed)  
-6. Operating Concept and End-to-End Flows  
-7. External Dependencies and Versioning  
-8. System Boundary and Interfaces  
-9. Key Design Decisions  
-10. Canonical Metrics Dictionary Contract  
-11. Error Handling, Logging, and Diagnostics  
-12. Security, Licensing, and Compliance  
-13. Testing, Documentation, and Release Engineering  
-14. Detailed Component Specifications  
-15. Trade Study and Optimization Engine Design  
-16. Visualization and Reporting  
-17. Configuration Schema (YAML/JSON)  
-18. Caching, Performance, and Scaling  
-19. Plugin Architecture (Extensibility)  
-20. Repository Deliverables and Acceptance Criteria  
-21. Build Plan (Agent-Ready Work Breakdown)  
-22. Appendices (Templates, Examples, Future Work)
-
----
-
-## 1) Purpose and Scope
-Build a Python package that supports:
-- **Antenna + beamforming modeling** via `phased-array-modeling`
-- **System-level performance modeling** (comms link budget, radar detection)
-- **SWaP-C + cost modeling** (parametric)
-- **Trade studies** (DOE, sensitivity, Pareto)
-- **Optimization** (constrained, multi-objective optional)
-- **Performance visualization** and **report generation**
-- **Requirements capture & verification** (lightweight MBSE traceability)
-
-This package is meant to encapsulate your model-based engineering / MDAO workflow: connect requirements → architecture → analytical models → trade studies → Pareto selection → reporting.
-
----
-
-## 2) Design Principles (MBSE/MDAO Inspired)
-1. **Traceability:** Requirements are first-class objects; every run produces pass/fail + margins.  
-2. **Composability:** Performance = integrated blocks (antenna + RF + propagation + radar/comms + SWaP-C).  
-3. **Trade-space first:** DOE + constraint filtering + Pareto > single-point “best” design.  
-4. **Fidelity growth:** Start fast with analytical models; optionally import “installed patterns” later.  
-5. **Reproducibility:** Config-driven runs; stable case IDs; seed control; version stamping.
-
----
-
-## 3) Users and Primary Use Cases
-### Personas
-- Phased array systems engineer (architecture trades)
-- Radar engineer (detection / search performance)
-- Wireless comms engineer (link margin, EIRP, multi-beam trades)
-- Researcher/educator (reproducible notebooks)
-
-### Use Cases
-- Comms link feasibility & power–aperture trades
-- Radar detection margin vs range/RCS vs aperture
-- Architecture comparison (element/tile/subarray choices vs requirements)
-- Sensitivity analysis (scatter matrices, correlation, optional Sobol)
-- Constrained optimization (min cost/weight/power while meeting margins)
-
----
-
-## 4) Non-Goals
-- Not a full-wave EM solver (HFSS/CST/FEKO replacement).
-- Not a SysML authoring environment.
-- Not a real-time DSP radar tracker; this is a design-time trade tool.
-
----
-
-## 5) System Overview and Architecture
-
-### 5.1 High-level Architecture
-
-**Layer 0 — Antenna modeling dependency**
-- `phased-array-modeling`: geometry + weights + impairments + pattern + visualization primitives.
-
-**Layer 1 — System models (this package)**
-- Requirements & verification
-- Architecture description (array + RF + SWaP-C + cost)
-- Comms / radar performance models
-- Trade study + optimization engine
-- Visualization + reporting
-
-**Layer 2 — Interfaces**
-- Python API + CLI
-- Config IO (YAML/JSON)
-- Results export (CSV/Parquet/JSON)
-- Optional installed-pattern import adapters
-
----
-
-### 5.2 Package Structure (Completed)
-
-#### A) Top-level repository structure
-```
-
-phased-array-systems/
-├─ README.md
-├─ LICENSE
-├─ CHANGELOG.md
-├─ CITATION.cff
-├─ pyproject.toml
-├─ ruff.toml
-├─ .gitignore
-├─ .github/
-│   └─ workflows/
-│       ├─ ci.yml                 # lint + test + build
-│       └─ publish.yml            # publish to PyPI on tag
-├─ docs/
-│   ├─ index.md
-│   ├─ quickstart.md
-│   ├─ tutorials/
-│   │   ├─ comms_trade_study.md
-│   │   ├─ radar_detection.md
-│   │   ├─ doe_pareto.md
-│   │   └─ impairments_sensitivity.md
-│   └─ sdd.md                     # this document
-├─ examples/
-│   ├─ 01_comms_trade_study.py
-│   ├─ 02_radar_detection_trade.py
-│   ├─ 03_multiobjective_pareto.py
-│   ├─ 04_impairments_sensitivity.py
-│   └─ configs/
-│       ├─ comms_trade.yaml
-│       └─ radar_trade.yaml
-├─ src/
-│   └─ phased_array_systems/
-│       ├─ **init**.py
-│       ├─ **about**.py            # version, metadata
-│       ├─ cli.py                  # pasys entrypoint
-│       ├─ constants.py            # physical constants, defaults
-│       ├─ types.py                # shared type aliases / protocols
-│       ├─ requirements/
-│       │   ├─ **init**.py
-│       │   ├─ core.py             # Requirement, RequirementSet, VerificationReport
-│       │   └─ expressions.py      # declarative ops, safe expression helpers
-│       ├─ architecture/
-│       │   ├─ **init**.py
-│       │   ├─ config.py           # Architecture, ArrayConfig, RFChainConfig, etc.
-│       │   └─ variants.py         # baseline + override support
-│       ├─ scenarios/
-│       │   ├─ **init**.py
-│       │   ├─ base.py             # Scenario protocol/base
-│       │   ├─ comms.py            # CommsLinkScenario schema
-│       │   └─ radar.py            # RadarDetectionScenario schema
-│       ├─ models/
-│       │   ├─ **init**.py
-│       │   ├─ base.py             # ModelBlock protocol (evaluate contract)
-│       │   ├─ antenna/
-│       │   │   ├─ **init**.py
-│       │   │   ├─ adapter.py      # wraps phased-array-modeling
-│       │   │   ├─ metrics.py      # beamwidth/SLL/scan loss extraction
-│       │   │   └─ installed.py    # optional installed-pattern override interface
-│       │   ├─ comms/
-│       │   │   ├─ **init**.py
-│       │   │   ├─ link_budget.py  # SNR, margin, EIRP, noise
-│       │   │   └─ propagation.py  # FSPL default, hooks for ITU-R
-│       │   ├─ radar/
-│       │   │   ├─ **init**.py
-│       │   │   ├─ radar_eq.py     # radar equation utilities
-│       │   │   └─ detection.py    # PD/PFA threshold helpers + integration gains
-│       │   ├─ swapc/
-│       │   │   ├─ **init**.py
-│       │   │   ├─ power.py        # prime power, PA efficiency, beam split
-│       │   │   ├─ thermal.py      # simple thermal models (optional early)
-│       │   │   └─ cost.py         # parametric cost models
-│       │   └─ mission/
-│       │       ├─ **init**.py
-│       │       └─ scoring.py      # optional mission-level scoring functions
-│       ├─ trades/
-│       │   ├─ **init**.py
-│       │   ├─ design_space.py     # variable definitions, bounds, categorical vars
-│       │   ├─ doe.py              # sampling (grid, random, LHS, Sobol optional)
-│       │   ├─ runner.py           # batch eval, parallelism, resume
-│       │   ├─ pareto.py           # pareto extraction, knee points, ranking
-│       │   ├─ optimize.py         # constrained optimization wrappers
-│       │   └─ sensitivity.py      # correlation, scatter-matrix helpers
-│       ├─ viz/
-│       │   ├─ **init**.py
-│       │   ├─ plots.py            # pareto, scatter, constraint shading
-│       │   ├─ dashboards.py       # optional interactive plotly dashboards
-│       │   └─ reports.py          # HTML/Markdown report generation
-│       ├─ io/
-│       │   ├─ **init**.py
-│       │   ├─ schema.py           # pydantic schemas: config + results
-│       │   ├─ config_loader.py    # YAML/JSON load/validate + overrides
-│       │   ├─ exporters.py        # CSV/JSON/Parquet
-│       │   └─ importers.py        # requirements import, installed pattern import
-│       └─ utils/
-│           ├─ **init**.py
-│           ├─ cache.py            # LRU + disk cache
-│           ├─ hashing.py          # stable case IDs
-│           └─ logging.py          # logging setup
-└─ tests/
-├─ test_requirements.py
-├─ test_comms_link_budget.py
-├─ test_radar_equation.py
-├─ test_antenna_adapter_small.py
-├─ test_doe_runner_resume.py
-└─ data/
-├─ golden_case_config.yaml
-└─ golden_case_results.json
-
-````
-
-#### B) Key internal contracts (cross-module)
-- **Metrics dictionary** is the universal exchange format.
-- **ModelBlock** interface: `evaluate(arch, scenario, context) -> metrics`.
-- **RequirementSet** verifies metrics and produces `VerificationReport`.
-- **Runner** orchestrates evaluation pipelines and records metadata, errors, and timing.
-
----
-
-## 6) Operating Concept and End-to-End Flows
-
-### 6.1 Single design evaluation (“Design Report”)
-1. Load/validate config
-2. Build `Architecture` + `Scenario` + `RequirementSet`
-3. Antenna adapter computes pattern metrics
-4. Comms/radar model computes performance metrics
-5. SWaP-C + cost models compute non-performance metrics
-6. Verify requirements
-7. Produce report + exports
-
-### 6.2 DOE trade study flow
-1. Create DOE cases from `DesignSpace`
-2. Evaluate each case (parallel + cached)
-3. Filter infeasible designs
-4. Extract Pareto front + knee point(s)
-5. Plot + report
-
-### 6.3 Optimization flow
-1. Choose solver (scipy baseline; multiobjective optional)
-2. Iterate evaluate → verify → score
-3. Return best design + traceability artifact
-
----
-
-## 7) External Dependencies and Versioning
-
-### Runtime deps (baseline)
-- `phased-array-modeling>=1.2.0`
-- `numpy`, `scipy`
-- `pydantic`
-- `matplotlib`
-- `pandas` *or* `polars` (choose one initially)
-
-### Optional extras
-- `plotly`, `kaleido` (interactive/export)
-- `joblib` (disk cache)
-- `pint` (units)
-- `pymoo` / `nevergrad` (mixed multiobjective)
-
-### Versioning
-- SemVer
-- Outputs always store: package version, dependency versions, seed, and (if available) git SHA.
-
----
-
-## 8) System Boundary and Interfaces
-### In-scope
-- Python API
-- CLI (`pasys`)
-- Config IO (YAML/JSON)
-- Results export (CSV/Parquet/JSON)
-- HTML/Markdown reporting
-
-### Out-of-scope (v0.1)
-- GUI application
-- Direct SysML tool integration (only import/export mappings)
-
----
-
-## 9) Key Design Decisions
-1. Delegate array pattern generation to `phased-array-modeling`.
-2. Use a flat, stable **metrics dictionary** for all model interchange.
-3. Treat requirements as data (declarative ops) with safe extension hooks.
-4. Make DOE+Pareto pipeline first-class and reproducible (case IDs + seeds).
-
----
-
-## 10) Canonical Metrics Dictionary Contract (Keys + Units)
-
-### Antenna
-- `g_peak_db` (dBi-like proxy)
-- `beamwidth_az_deg`, `beamwidth_el_deg`
-- `sll_db`
-- `scan_angle_deg`
-- `scan_loss_db`
-
-### Comms
-- `eirp_dbw`
-- `path_loss_db`
-- `rx_power_dbw`
-- `noise_power_dbw`
-- `snr_rx_db`
-- `required_snr_db`
-- `link_margin_db`
-
-### Radar
-- `snr_single_pulse_db`
-- `snr_required_db`
-- `snr_margin_db`
-- `pd`, `pfa`
-- `rcs_m2`, `range_m`
-
-### SWaP-C
-- `prime_power_w`
-- `dc_power_w`
-- `weight_kg`
-- `cost_usd`
-- `power_density_w_per_kg` (optional)
-
-### Metadata (namespaced)
-- `meta.case_id`
-- `meta.runtime_s`
-- `meta.seed`
-- `meta.error`
-- `meta.error_type`
-- `meta.phased_array_modeling_version`
-- `meta.phased_array_systems_version`
-
----
-
-## 11) Error Handling, Logging, and Diagnostics
-- Single-case runs: raise structured exceptions with context.
-- DOE runs: never crash the whole job for one case; record per-case error fields.
-- Store “failed cases” subset and export minimal reproducer config.
-
----
-
-## 12) Security, Licensing, and Compliance
-- Configs are data-only (no `eval()`).
-- Recommend MIT or BSD-3 (ensure compatible with dependency).
-- Include LICENSE, optional CITATION.cff.
-
----
-
-## 13) Testing, Documentation, and Release Engineering
-### Testing
-- Unit tests: requirements, comms link budget sanity, radar equation sanity, antenna adapter metrics.
-- Regression: golden-case snapshots (config + results).
-- Batch runner test: resume behavior.
-
-### Docs
-- Quickstart
-- Tutorials for comms, radar, DOE+Pareto, impairments sensitivity
-
-### Release
-- GitHub Actions: lint + tests + build
-- Publish to PyPI on version tags
-
----
-
-## 14) Detailed Component Specifications
-
-### 14.1 Requirements (`requirements/`)
-- `Requirement` supports declarative constraints or safe callables for complex logic.
-- `RequirementSet.verify(metrics)` returns pass/fail + per-requirement margins.
-
-### 14.2 Architecture (`architecture/`)
-- `Architecture` contains `ArrayConfig`, `RFChainConfig`, `PowerThermalConfig`, `CostConfig`.
-- Support variants/overrides for trade studies (baseline + deltas).
-
-### 14.3 Antenna adapter (`models/antenna/`)
-- Wrap `phased-array-modeling` to compute patterns and extract consistent metrics.
-- Provide pattern caching keyed by config + angle grid hash.
-
-### 14.4 Comms models (`models/comms/`)
-- Link budget produces SNR + margin and exposes propagation model hooks.
-
-### 14.5 Radar models (`models/radar/`)
-- Radar equation utilities + detection threshold helpers (PD/PFA) with user override option.
-
-### 14.6 SWaP-C + Cost (`models/swapc/`)
-- Parametric power, cost, and (optional early) thermal models; extendable by plugins.
-
----
-
-## 15) Trade Study and Optimization Engine (`trades/`)
-
-### DOE
-- Methods: grid/random/LHS (Sobol optional)
-- Deterministic seeds; stable `case_id`
-
-### Batch runner
-- Parallel evaluation, case-level resume, exception capture
-
-### Pareto
-- Feasibility filter → Pareto front → ranking + knee points
-
-### Optimization
-- Start: `scipy.optimize` (SLSQP/COBYLA)
-- Optional: multiobjective mixed-variable solver extras
-
----
-
-## 16) Visualization and Reporting (`viz/`)
-- Pareto plots, 3D scatter (optional), scatter-matrix, constraint margin histograms
-- Report generator: HTML/Markdown with reproducibility footer
-
----
-
-## 17) Configuration Schema (YAML/JSON)
-
-### Example config (abbreviated)
-```yaml
-study:
-  name: power_aperture_trade
-  seed: 123
-scenario:
-  type: comms_link
-  freq_hz: 1.0e10
-  bandwidth_hz: 1.0e8
-  range_m: 200000
-  required_snr_db: 14
-requirements:
-  - id: REQ_LINK_MARGIN
-    metric_key: link_margin_db
-    op: ">="
-    value: 3
-design_space:
-  variables:
-    nx: {type: int, low: 8, high: 64}
-    ny: {type: int, low: 8, high: 64}
-    tx_power_w_per_elem: {type: float, low: 0.5, high: 10.0}
-doe:
-  method: lhs
-  n_samples: 2000
-objectives:
-  - metric_key: eirp_dbw
-    direction: maximize
-  - metric_key: cost_usd
-    direction: minimize
-````
-
----
-
-## 18) Caching, Performance, and Scaling
-
-* Multi-layer caching: pattern cache + case cache
-* Fidelity presets: `fast`, `balanced`, `fidelity`
-* Resume and disk caching recommended for large DOE runs
-
----
-
-## 19) Plugin Architecture (Extensibility)
-
-* Define `ModelBlock` protocol and allow registry of:
-
-  * propagation models
-  * cost models
-  * thermal models
-  * mission scoring models
-* Optional: setuptools entrypoints for plugin discovery
-
----
-
-## 20) Deliverables and Acceptance Criteria (v0.1)
-
-* `pip install phased-array-systems`
-* One comms DOE example: results + Pareto + report
-* One radar detection example: margin report
-* CI passing
-* Docs + tutorials
-
----
-
-## 21) Build Plan (Agent-Ready Work Breakdown)
-
-### Phase 1: Core scaffolding (MVP)
-
-* schemas + config loader
-* requirements verification
-* antenna adapter wrapper
-* comms link budget model + SWaP-C placeholders
-* single-case report
-
-### Phase 2: Trade + viz
-
-* DOE generator + batch runner + resume
-* Pareto extraction + plots
-* Parquet export
-
-### Phase 3: Radar
-
-* radar equation + detection threshold helpers
-* radar trade example + plots
-
-### Phase 4: CLI + reporting
-
-* `pasys run`, `pasys doe`, `pasys pareto`
-* publish-ready packaging
-
----
-
-## 22) Appendices
-
-### A) Trade Study Templates
-
-* Power–aperture comms trade: maximize EIRP / margin vs minimize power/cost
-* EIRP vs cost vs prime power 3D Pareto exploration
-* Radar detection margin vs range/RCS with integration knobs
-
-### B) Future Work
-
-* Installed-pattern importers for common EM tool exports
-* Beam scheduling/time-sharing models
-* Thermal derating models
-* Calibration / error budgets for radar & comms chains
-
----
-
-**End of document**
-
-```
-::contentReference[oaicite:0]{index=0}
-```