phased-array-systems 0.3.0__tar.gz → 0.9.0__tar.gz

phased_array_systems-0.9.0/.claude/settings.local 2.json

@@ -0,0 +1,45 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 -m pip install:*)",
+      "Bash(pyenv versions:*)",
+      "Bash(pyenv local:*)",
+      "Bash(python3 -m pytest:*)",
+      "Bash(python3 -m ruff check:*)",
+      "Bash(python3:*)",
+      "Bash(git init:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(ruff check:*)",
+      "Bash(pytest:*)",
+      "Bash(gh run:*)",
+      "Bash(gh release create v0.1.0 --title \"v0.1.0 - Initial Release\" --notes \"$\\(cat <<''EOF''\n## phased-array-systems v0.1.0\n\nInitial release of the phased array antenna system design and optimization package.\n\n### Features\n\n- **Architecture Configuration**: Pydantic models for array, RF chain, and cost configurations\n- **Communications Link Budget**: EIRP, path loss, SNR, and link margin calculations\n- **Requirements Verification**: Define and verify system requirements with pass/fail margins\n- **DOE Trade Studies**: Latin Hypercube Sampling, grid, and random sampling methods\n- **Pareto Analysis**: Extract and rank Pareto-optimal designs\n- **Batch Evaluation**: Parallel evaluation with caching and progress tracking\n- **Visualization**: Pareto plots and scatter matrices\n- **Config I/O**: YAML/JSON configuration loading and results export \\(Parquet, CSV\\)\n\n### Installation\n\n```bash\npip install phased-array-systems\n```\n\n### Documentation\n\nSee the [README]\\(https://github.com/jman4162/phased-array-systems#readme\\) and example scripts in the `examples/` directory.\nEOF\n\\)\")",
+      "Bash(gh release create:*)",
+      "Bash(pip install:*)",
+      "Bash(python -c:*)",
+      "Bash(python:*)",
+      "Bash(pasys --help:*)",
+      "Bash(wc:*)",
+      "Bash(mkdocs serve:*)",
+      "Bash(pkill:*)",
+      "Bash(gh api:*)",
+      "Bash(perl -i -pe:*)",
+      "Bash(mkdocs build:*)",
+      "Bash(curl:*)",
+      "Bash(grep:*)",
+      "Bash(perl -i -p0e:*)",
+      "Bash(ls:*)",
+      "Bash(find:*)",
+      "Bash(git remote add:*)",
+      "Bash(done)",
+      "Bash(gh release view:*)",
+      "Bash(gh release list:*)",
+      "Bash(gh issue close:*)",
+      "Bash(pip index:*)",
+      "WebFetch(domain:jman4162.github.io)",
+      "Bash(ruff format:*)",
+      "Bash(pip list:*)",
+      "Bash(awk -F: '{s+=$2} END{print s}')"
+    ]
+  }
+}

{phased_array_systems-0.3.0 → phased_array_systems-0.9.0}/.github/workflows/ci.yml

@@ -25,13 +25,18 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          pip install -e ".[dev,mdao,plotting]"
           pip install pyarrow  # For parquet tests
 
       - name: Run linting with Ruff
         run: |
           ruff check . --output-format=github
 
+      - name: Run type checking with mypy
+        if: matrix.python-version == '3.12'
+        run: |
+          mypy src/phased_array_systems
+
       - name: Run tests with pytest
         run: |
           pytest tests/ -v --tb=short --cov=phased_array_systems --cov-report=xml

phased_array_systems-0.9.0/.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

{phased_array_systems-0.3.0 → phased_array_systems-0.9.0}/.gitignore

@@ -145,3 +145,6 @@ results/
 *.csv
 !examples/configs/*.yaml
 package_design_and_requirements.txt
+
+# slopcheck virtualenv
+scripts/.slopvenv/

phased_array_systems-0.9.0/CHANGELOG.md

@@ -0,0 +1,216 @@
+# Changelog
+
+All notable changes to phased-array-systems will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.9.0] - 2026-07-22
+
+### Added
+- True multi-objective optimization: `optimize_pareto()` (trades/moo.py)
+  runs mixed-variable NSGA-II via pymoo and returns the nondominated set
+  with full metrics; must-severity requirements become normalized
+  inequality constraints. CLI: `pasys optimize --method nsga2`
+- Optional `[mdao]` extra (pymoo, SALib); core install unchanged
+- Constraint-aware DOE: `generate_doe(validate="architecture")` rejection-
+  samples against Architecture construction with adaptive oversampling,
+  eliminating per-case construction errors from batch studies
+- Sobol global sensitivity: `sobol_sensitivity()` with S1/ST indices and
+  confidence intervals; `pasys sensitivity --sens-method sobol`
+- Search timeline metrics: radar scenarios accept prf_hz, search extents,
+  beam overhead, and frame budget; antenna beamwidths and n_pulses/PRF
+  dwell time drive dwell_time_ms, n_beam_positions, search_frame_time_s,
+  search_update_rate_hz, timeline_occupancy
+- Thermal-reliability coupling: `reliability.thermal_resistance_c_per_w`
+  + `ambient_temp_c` estimate junction temperature from dissipated power
+  and feed the Arrhenius MTBF derating (new junction_temp_c metric)
+- Interactive plotly plots (`viz/interactive.py`, [plotting] extra) and
+  self-contained interactive Pareto embeds in HTML reports
+
+### Changed
+- Weighted-sum optimizer penalty normalizes margins by requirement scale
+  (mixed-unit requirements previously biased the penalty)
+- `interleaved_timeline` uses deterministic priority-weighted round-robin
+  instead of the placeholder priority sort
+- mypy analysis target is 3.12 (numpy 2.2+ stubs); runtime 3.10 support
+  unchanged, still tested in CI
+
+## [0.8.0] - 2026-07-22
+
+### Added
+- `models/propagation/` package: full ITU-R P.676-13 Annex 1 line-by-line
+  gaseous attenuation (44 O2 + 35 H2O vendored spectroscopic lines) and
+  ITU-R P.838-3 rain k/alpha for H and V polarization; ITU-R P.530
+  effective rain path length; all coefficient data vendored, no new
+  dependencies
+- NRL sea clutter model (Gregers-Hansen & Mittal 2012, fitted to the
+  Nathanson tables) and Barton constant-gamma ground clutter
+- `swerling` field on `RadarDetectionScenario`; required SNR, integration
+  gain, and achieved Pd all use the exact detection statistics
+- `models/antenna/errors.py`: Ruze gain loss, phase-quantization RMS and
+  loss, average sidelobe floor, beam-pointing estimate; wired into both
+  antenna adapter paths so `phase_bits` and taper affect metrics in
+  analytic mode
+- `generate_taper_weights()` from scipy window functions; taper losses
+  computed from real windows
+- Reproducibility: `evaluate_case(seed=...)` threads the element-failure
+  RNG seed; `meta.seed`, `meta.package_version`, `meta.pam_version`
+  stamped per case; batch results sorted by case_id; `pasys doe --cache
+  PATH --resume`
+- Validation suite (`tests/test_validation.py`, 35 tests) asserting
+  models against their published sources; `docs/theory/validation.md`
+  documents every reference and tolerance
+- mypy at zero errors, enforced as a blocking CI step
+
+### Changed (numeric results shift)
+- Atmospheric and rain losses now come from the real ITU models (the
+  previous 2-line/polynomial fits were hand-set approximations);
+  elevation handling uses equivalent-height slant columns (the previous
+  scale factor always evaluated to 1)
+- Required radar SNR uses the exact Marcum-Q inversion instead of
+  Albersheim (golden case: 13.115 -> 13.183 dB, margin -0.24 dB)
+- One noise convention: `rx_noise_temp_k` is antenna temperature and
+  T_sys = T_ant + 290*(F-1); identical at 290 K, corrects low-sky-temp
+  satcom cases; the radar equation now honors cascaded NF like the comms
+  path (golden case: +1.16 dB SNR with its 1.84 dB cascade)
+- CA-CFAR loss follows the analytic universal curve, so Pfa now matters
+  (N=16 at 1e-6: 2.0 dB, unchanged; other Pfa values shift)
+- Clutter sigma0 values shift to the published models
+- `friis_noise_figure` reports `stage_contribution_pct` (sums to 100)
+  and `stage_nf_delta_db` instead of per-stage dB values that did not
+  sum; `cascade_analysis` key renamed to `stage_nf_contribution_pct`
+
+### Removed
+- `compute_cost_per_db` (USD per dB is not a meaningful ratio)
+- `swerling_snr_adjustment` and `cfar_required_snr_adjustment` empirical
+  step tables (superseded by exact statistics and the universal curve)
+- Hand-fit taper-loss polynomials, GIT-style clutter constants, and the
+  fabricated rain-cell extent model
+
+## [0.7.0] - 2026-07-22
+
+### Added
+- `digitization_level` (element / subarray / analog) on `DigitalConfig`; ADC count, beamformer data rate, compute, and power now follow the digitized channel count (`Architecture.n_digital_channels`) instead of assuming one ADC per element
+- ADC aperture-jitter model: `adc_effective_snr()` combines quantization and jitter noise; new `adc_jitter_ps_rms` and `adc_input_freq_hz` config fields and `adc_enob_effective` metric
+- System dynamic range metric `dynamic_range_system_db` including the 10*log10(N_channels) array processing gain
+- Digital section power in the DC budget: ADC power from the Walden figure of merit (`adc_fom_fj`) and beamformer power from `dsp_efficiency_gops_per_w`
+- Receive chain power per element (`rf.rx_power_w_per_elem`) and radar transmit `duty_cycle` in the power model; new metrics `rf_avg_power_w`, `pa_dc_power_w`, `rx_dc_power_w`, `adc_power_w`, `dsp_power_w`
+- Exact Swerling 1-4 detection probabilities via gamma-mixture of the noncentral chi-square detector statistics
+- Example `06_dbf_architecture_trade.py` and config `dbf_architecture_doe.yaml`: digitization-level trade study with Pareto extraction
+- Golden-case regression test (`tests/test_golden_case.py` + `tests/data/golden_dbf_case.json`)
+
+### Fixed
+- `default_architecture_builder` silently dropped `digital.*` and `reliability.*` DOE variables, so batch studies could not vary digital or reliability parameters
+- `augment_doe` reused the caller's seed and duplicated the original samples instead of drawing new points
+- Swerling 0 Pd used a Gaussian-tail approximation with identical dead-code branches; replaced with the exact Marcum Q (noncentral chi-square survival function)
+- Radar equation double-counted pulse integration: an empirical n^0.8 gain was added on top of Albersheim's own n-pulse law; required SNR and integration gain now come from a single consistent law
+
+## [0.6.0] - 2026-03-21
+
+### Added
+- Design optimization module (`trades/optimization.py`) with `optimize_design()` using scipy solvers
+- `OptimizationResult` dataclass with best architecture, metrics, convergence info, and optional history
+- Three solver backends: `differential_evolution`, `dual_annealing`, `minimize` (L-BFGS-B)
+- Weighted multi-objective scalarization and requirement-based constraint penalties
+- CLI `pasys optimize` command with `--objective`, `--sense`, `--method`, `--max-iter` options
+- Unit tests for RF cascade models (`test_rf_cascade.py`): Friis NF, IIP3/OIP3, SFDR, MDS, cascade analysis
+- Unit tests for digital models (`test_digital.py`): converters, bandwidth, beamformer ops, scheduling
+- Optimization tests (`test_optimization.py`): single/multi-objective, constraints, integer vars, CLI E2E
+- Example script `05_optimization.py`: DOE baseline vs optimizer comparison
+
+## [0.5.0] - 2026-03-21
+
+### Added
+- Digital beamformer integration: `DigitalConfig` for ADC ENOB, data rate, and FPGA processing margin
+- Radar YAML configs: `radar_basic.yaml` and `radar_doe.yaml` examples
+- CLI end-to-end tests for run, doe, report, pareto, and sensitivity commands
+- I/O round-trip tests for Parquet, CSV, and JSON export/import
+- Digital metrics in reports (HTML and Markdown): `adc_enob`, `bf_data_rate_gbps`, `processing_margin_db`
+
+### Fixed
+- CLI `pasys doe` command: was reading nonexistent `config.design_space` instead of `config.doe`
+- CLI `pasys sensitivity` command: same `design_space` bug, now reads DOE variables correctly
+
+## [0.4.0] - 2026-02-01
+
+### Added
+- Digital array model for digital beamforming calculations
+- RF cascade model for noise figure and gain cascade analysis
+- Documentation site with MkDocs Material
+- API reference with mkdocstrings
+- User guides for all major features
+- Tutorials for communications and radar trade studies
+- Theory documentation for phased arrays and link budgets
+
+### Fixed
+- Ruff linting errors in models module
+- MathJax rendering in documentation
+- Markdown list formatting in documentation
+
+## [0.3.0] - 2024-01-15
+
+### Added
+- Radar detection model with pulse integration
+- `RadarDetectionScenario` for radar trade studies
+- Radar equation calculator with Swerling models
+- Detection probability and false alarm rate computations
+- CLI commands: `pasys run`, `pasys doe`, `pasys report`, `pasys pareto`
+- HTML and Markdown report generation
+- Example: `03_radar_detection_trade.py`
+
+### Changed
+- Improved Pareto extraction algorithm efficiency
+- Enhanced visualization with 3D trade space plots
+
+### Fixed
+- Hypervolume calculation for 3+ objectives
+
+## [0.2.0] - 2024-01-01
+
+### Added
+- Design of Experiments (DOE) generation with LHS, random, and grid methods
+- `BatchRunner` for parallel evaluation with progress tracking
+- Pareto frontier extraction and ranking (weighted sum, TOPSIS)
+- Scatter matrix visualization
+- Parquet and CSV export functionality
+- Requirements verification with pass/fail and margins
+- `DesignSpace` for defining variable bounds and types
+
+### Changed
+- Refactored architecture configuration to use Pydantic v2
+- Improved error handling for batch evaluation
+
+### Fixed
+- Array gain calculation for non-square arrays
+- Case ID generation collision in augmented DOE
+
+## [0.1.0] - 2023-12-15
+
+### Added
+- Initial release
+- `Architecture` configuration: `ArrayConfig`, `RFChainConfig`, `CostConfig`
+- `CommsLinkScenario` for communications link analysis
+- Communications link budget model (`CommsLinkModel`)
+- Free space path loss propagation model
+- Power and cost models for SWaP-C analysis
+- `Requirement` and `RequirementSet` for requirements management
+- Pareto plot visualization
+- YAML/JSON configuration loading
+- Example: `01_comms_single_case.py`
+- Example: `02_comms_doe_trade.py`
+- Tutorial Jupyter notebook
+
+### Dependencies
+- Requires `phased-array-modeling>=1.2.0`
+- Python 3.10+
+
+[Unreleased]: https://github.com/jman4162/phased-array-systems/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/jman4162/phased-array-systems/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/jman4162/phased-array-systems/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/jman4162/phased-array-systems/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/jman4162/phased-array-systems/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/jman4162/phased-array-systems/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/jman4162/phased-array-systems/releases/tag/v0.1.0

phased_array_systems-0.9.0/CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`phased-array-systems` is an open-source Python package for phased array antenna system design, optimization, and performance visualization for wireless communications and radar applications. It implements an MBSE/MDAO workflow: requirements → architecture → analytical models → trade studies → Pareto selection → reporting.
+
+**Core dependency:** `phased-array-modeling>=1.2.0` (provides array geometries, steering, tapering, impairments, and pattern visualization)
+
+**Project status:** v0.9.0 - MDAO capability complete (NSGA-II, Sobol, constraint-aware DOE, timeline and thermal coupling) on top of the validated reference models. See `package_design_and_requirements.txt` for the original SDD and `CHANGELOG.md` for release history.
+
+## Git Attribution
+
+All GitHub commits and attributions for this repository should be attributed to:
+
+- **Name:** John Hodge
+- **GitHub:** jman4162
+- **Email:** jhodge007@gmail.com
+
+Do NOT commit as jah70@vt.edu: GitHub maps that email to the account
+@jman41, which wrongly appears as a separate contributor.
+
+## Build & Development Commands
+
+```bash
+# Installation
+pip install -e .                            # Editable install
+pip install -e ".[dev]"                     # Development deps (pytest, ruff, mypy)
+pip install -e ".[plotting]"                # Visualization (plotly, kaleido)
+
+# Testing
+pytest tests/                               # Run all tests
+pytest tests/test_comms_link_budget.py -v   # Run specific test file
+pytest tests/ --cov=phased_array_systems    # With coverage
+
+# Linting & Formatting
+ruff check .
+ruff format .
+mypy src/phased_array_systems
+
+# CLI
+pasys run config.yaml                       # Single case evaluation
+pasys doe config.yaml                       # DOE batch study
+pasys optimize config.yaml --objective eirp_dbw --sense maximize  # Optimization
+pasys pareto results.parquet --x cost_usd --y eirp_dbw  # Pareto analysis
+pasys report results.parquet -o report.html # Generate HTML report
+```
+
+## Architecture
+
+### Layer Structure
+- **Layer 0:** `phased-array-modeling` (external) - EM/pattern computations
+- **Layer 1:** This package - system models, trade studies, optimization
+- **Layer 2:** Interfaces - Python API, CLI, config I/O
+
+### Package Layout (`src/phased_array_systems/`)
+- `requirements/` - Constraint/objective definitions, verification reports
+- `architecture/` - ArrayConfig, RFChainConfig, CostConfig, DigitalConfig, ReliabilityConfig
+- `models/antenna/` - Adapter wrapping `phased-array-modeling`, pattern metrics extraction
+- `models/comms/` - Link budget (SNR, margin, EIRP), propagation models
+- `models/radar/` - Radar equation, PD/PFA threshold helpers, integration gains
+- `models/swapc/` - Power, thermal, and cost models
+- `models/rf/` - RF cascade analysis (Friis NF, IIP3, SFDR), TRM reliability models
+- `models/digital/` - ADC/DAC converters, beamformer bandwidth/ops, scheduling
+- `trades/` - DOE generation, batch runner, Pareto extraction, optimization solvers
+- `viz/` - Plots (Pareto, scatter-matrix), HTML/Markdown report generation
+- `io/` - Config loading (YAML/JSON), results export (Parquet/CSV)
+- `cli.py` - `pasys` command entrypoint
+
+### Core Contracts
+
+**ModelBlock Protocol:**
+```python
+class ModelBlock(Protocol):
+    name: str
+    def evaluate(self, arch: Architecture, scenario: Scenario, context: dict) -> dict:
+        """Returns flat metrics dict"""
+```
+
+**Canonical Metrics Dictionary** (universal exchange format):
+- Antenna: `g_peak_db`, `beamwidth_az_deg`, `beamwidth_el_deg`, `sll_db`, `scan_loss_db`
+- Comms: `eirp_dbw`, `path_loss_db`, `snr_rx_db`, `link_margin_db`
+- Radar: `snr_single_pulse_db`, `snr_required_db`, `snr_margin_db`, `pd`, `pfa`
+- RF Cascade: `cascade_nf_db`, `cascade_gain_db`, `cascade_iip3_dbm`, `cascade_oip3_dbm`, `cascade_sfdr_db`, `cascade_mds_dbm`
+- Digital: `adc_enob`, `adc_snr_db`, `bf_data_rate_gbps`, `bf_compute_gops`, `processing_margin_db`, `fpga_utilization_pct`
+- Reliability: `trm_mtbf_hours`, `array_mtbf_hours`, `expected_failed_elements`, `array_availability`
+- SWaP-C: `prime_power_w`, `weight_kg`, `cost_usd`
+- Metadata: `meta.case_id`, `meta.runtime_s`, `meta.seed`, `meta.error`
+
+### Data Flow
+```
+Config (YAML/JSON) → Pydantic validation → [Architecture + Scenario + RequirementSet]
+    → DOE case generation → Batch evaluation (parallel, cached)
+    → Requirement verification → Pareto extraction → Optimization → Visualization/Reports
+```
+
+## Design Principles
+
+1. **Requirements as first-class objects** - Every run produces pass/fail + margins with traceability
+2. **Trade-space first** - DOE + Pareto over single-point designs; grey-out infeasible cases
+3. **Flat metrics dictionary** - All models return consistent `dict[str, float]` for interchange
+4. **Config-driven reproducibility** - Stable case IDs, seed control, version stamping
+5. **Safe configs** - No `eval()`, data-driven configs only
+6. **Case-level error handling** - DOE runs never crash for single-case failures
+
+## Implementation Phases
+
+All phases are complete as of v0.4.0, with v0.5.0 adding digital/RF models and v0.6.0 adding optimization:
+
+1. **Phase 1 (MVP):** ✅ Complete
+   - Pydantic schemas for Architecture, Scenario, RequirementSet
+   - YAML/JSON config loader with validation
+   - Requirements verification with pass/fail and margin reporting
+   - Antenna adapter wrapping `phased-array-modeling`
+   - Comms link budget model (EIRP, path loss, SNR, margins)
+
+2. **Phase 2:** ✅ Complete
+   - DOE generator with full-factorial and Latin hypercube sampling
+   - Batch runner with parallel execution and resume capability
+   - Pareto extraction for multi-objective optimization
+   - Interactive plots (Pareto fronts, scatter matrices)
+   - Parquet/CSV export for results
+
+3. **Phase 3:** ✅ Complete
+   - Radar equation model (SNR, detection range)
+   - Detection threshold helpers (PD/PFA calculations)
+   - Integration gain for pulse integration
+   - Radar trade study examples
+
+4. **Phase 4:** ✅ Complete
+   - `pasys` CLI with run, doe, pareto, and report commands
+   - HTML and Markdown report generation
+   - Ready for PyPI publish
+
+5. **Phase 5 (v0.5.0):** ✅ Complete
+   - RF cascade analysis (Friis NF, IIP3, SFDR, MDS)
+   - TRM reliability and graceful degradation models
+   - Digital beamformer models (ADC/DAC, bandwidth, scheduling)
+   - DigitalConfig and ReliabilityConfig in Architecture
+
+6. **Phase 6 (v0.6.0):** ✅ Complete
+   - Design optimization via scipy solvers (DE, dual annealing, L-BFGS-B)
+   - Weighted multi-objective scalarization with constraint penalties
+   - `pasys optimize` CLI command
+   - Unit tests for RF cascade and digital models
+
+## Future Goals
+
+**Interactive Web Application:** The package is designed to eventually power an interactive Streamlit or Vercel webapp for browser-based trade studies and visualization. Keep the core logic decoupled from CLI/reporting concerns to facilitate web integration.