```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}
```
