phased-array-systems 0.2.0__tar.gz → 0.4.0__tar.gz

phased_array_systems-0.4.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.4.0/CHANGELOG.md

@@ -0,0 +1,77 @@
+# 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]
+
+### Added
+- Comprehensive 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
+
+## [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.3.0...HEAD
+[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.2.0 → phased_array_systems-0.4.0}/CLAUDE.md

@@ -8,30 +8,31 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **Core dependency:** `phased-array-modeling>=1.2.0` (provides array geometries, steering, tapering, impairments, and pattern visualization)
 
-**Project status:** Design phase (no code implemented yet). See `package_design_and_requirements.txt` for the complete SDD.
+**Project status:** v0.4.0 - All 4 implementation phases complete. See `package_design_and_requirements.txt` for the original SDD.
 
 ## Build & Development Commands
 
 ```bash
-# Installation (once implemented)
-pip install phased-array-systems
-pip install phased-array-systems[dev]       # Development deps (pytest, ruff, mypy)
-pip install phased-array-systems[plotting]  # Visualization (plotly, kaleido)
+# 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/
-pytest tests/test_comms_link_budget.py -v
-pytest tests/ --cov=phased_array_systems
+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 (planned)
-pasys run config.yaml      # Single case evaluation
-pasys doe config.yaml      # DOE batch study
-pasys pareto results.parquet --x cost_usd --y eirp_dbw
+# CLI
+pasys run config.yaml                       # Single case evaluation
+pasys doe config.yaml                       # DOE batch study
+pasys pareto results.parquet --x cost_usd --y eirp_dbw  # Pareto analysis
+pasys report results.parquet -o report.html # Generate HTML report
 ```
 
 ## Architecture
@@ -88,10 +89,32 @@ Config (YAML/JSON) → Pydantic validation → [Architecture + Scenario + Requir
 
 ## Implementation Phases
 
-1. **Phase 1 (MVP):** Schemas, config loader, requirements verification, antenna adapter, comms link budget
-2. **Phase 2:** DOE generator, batch runner with resume, Pareto extraction, plots, Parquet export
-3. **Phase 3:** Radar equation, detection threshold helpers, radar trade examples
-4. **Phase 4:** CLI (`pasys`), HTML/Markdown report generation, PyPI publish
+All phases are complete as of v0.4.0:
+
+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
 
 ## Future Goals
 

phased_array_systems-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,210 @@
+# Contributing to phased-array-systems
+
+Thank you for your interest in contributing to phased-array-systems! This document provides guidelines and instructions for contributing.
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions. We welcome contributors of all experience levels.
+
+## Getting Started
+
+### Development Setup
+
+1. **Fork and clone the repository:**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/phased-array-systems.git
+   cd phased-array-systems
+   ```
+
+2. **Create a virtual environment:**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install in development mode:**
+   ```bash
+   pip install -e ".[dev,docs,plotting]"
+   ```
+
+4. **Verify the installation:**
+   ```bash
+   pytest tests/ -v
+   ```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=phased_array_systems
+
+# Run a specific test file
+pytest tests/test_link_budget.py -v
+```
+
+### Code Quality
+
+We use `ruff` for linting and formatting, and `mypy` for type checking:
+
+```bash
+# Lint the codebase
+ruff check .
+
+# Auto-format code
+ruff format .
+
+# Type check
+mypy src/phased_array_systems
+```
+
+## Making Changes
+
+### Branching Strategy
+
+1. Create a feature branch from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes with clear, atomic commits
+
+3. Push to your fork and create a Pull Request
+
+### Commit Messages
+
+Write clear, descriptive commit messages:
+
+```
+Add support for triangular array geometry
+
+- Implement triangular element positioning
+- Add tests for new geometry type
+- Update documentation with examples
+```
+
+### Pull Request Guidelines
+
+- **Title:** Use a clear, descriptive title
+- **Description:** Explain what changes you made and why
+- **Tests:** Add tests for new functionality
+- **Documentation:** Update docs if adding new features
+- **Small PRs:** Keep changes focused; large changes should be split into multiple PRs
+
+## What to Contribute
+
+### Good First Issues
+
+Look for issues labeled `good first issue` - these are ideal for newcomers.
+
+### Areas We Need Help
+
+- **New models:** Additional propagation models, antenna patterns
+- **Documentation:** Tutorials, examples, API docs improvements
+- **Testing:** Increase test coverage, add edge case tests
+- **Performance:** Optimization of batch evaluation, caching improvements
+- **Visualization:** New plot types, interactive visualizations
+
+### Feature Requests
+
+Before starting on a large feature:
+1. Check existing issues to avoid duplicates
+2. Open an issue describing the feature
+3. Wait for discussion/approval before implementing
+
+## Code Style
+
+### Python Style
+
+- Follow PEP 8 (enforced by ruff)
+- Use type hints for all public functions
+- Use Google-style docstrings
+- Keep functions focused and under 50 lines when possible
+
+### Docstring Example
+
+```python
+def compute_link_margin(
+    eirp_dbw: float,
+    path_loss_db: float,
+    required_snr_db: float,
+) -> dict[str, float]:
+    """Compute the communications link margin.
+
+    Calculates received SNR and margin to the required threshold
+    for a point-to-point link.
+
+    Args:
+        eirp_dbw: Effective Isotropic Radiated Power in dBW.
+        path_loss_db: Total path loss in dB.
+        required_snr_db: Required SNR for demodulation in dB.
+
+    Returns:
+        Dictionary containing:
+            - snr_db: Received signal-to-noise ratio
+            - margin_db: Margin above required SNR (positive = passes)
+
+    Raises:
+        ValueError: If any input is NaN or infinite.
+
+    Example:
+        >>> result = compute_link_margin(50.0, 150.0, 10.0)
+        >>> print(f"Margin: {result['margin_db']:.1f} dB")
+    """
+```
+
+### Testing Guidelines
+
+- Test both happy path and edge cases
+- Use descriptive test names: `test_extract_pareto_with_empty_dataframe`
+- Use pytest fixtures for shared setup
+- Mock external dependencies (e.g., `phased-array-modeling`)
+
+## Documentation
+
+### Building Docs Locally
+
+```bash
+# Install docs dependencies
+pip install -e ".[docs]"
+
+# Serve locally with live reload
+mkdocs serve
+
+# Build static site
+mkdocs build
+```
+
+### Documentation Structure
+
+- `docs/getting-started/` - Installation and quickstart
+- `docs/user-guide/` - Detailed usage guides
+- `docs/tutorials/` - Step-by-step tutorials
+- `docs/api/` - API reference (auto-generated from docstrings)
+- `docs/theory/` - Background theory and equations
+
+## Release Process
+
+Releases are managed by maintainers:
+
+1. Update `__about__.py` with new version
+2. Update `CHANGELOG.md`
+3. Create a GitHub release with tag `vX.Y.Z`
+4. GitHub Actions will publish to PyPI
+
+## Getting Help
+
+- **Questions:** Open a GitHub Discussion
+- **Bugs:** Open a GitHub Issue
+- **Security:** Email maintainers directly (do not open public issues)
+
+## Recognition
+
+Contributors are recognized in:
+- The GitHub contributors page
+- Release notes for significant contributions
+- The project README for major contributions
+
+Thank you for contributing to phased-array-systems!

{phased_array_systems-0.2.0 → phased_array_systems-0.4.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: phased-array-systems
-Version: 0.2.0
+Version: 0.4.0
 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
+Project-URL: Documentation, https://jman4162.github.io/phased-array-systems
 Project-URL: Repository, https://github.com/jman4162/phased-array-systems
 Project-URL: Issues, https://github.com/jman4162/phased-array-systems/issues
+Project-URL: Changelog, https://jman4162.github.io/phased-array-systems/changelog
 Author: phased-array-systems contributors
 License-Expression: MIT
 License-File: LICENSE
@@ -35,6 +36,14 @@ Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-gen-files>=0.5; extra == 'docs'
+Requires-Dist: mkdocs-jupyter>=0.24; extra == 'docs'
+Requires-Dist: mkdocs-literate-nav>=0.6; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.4; extra == 'docs'
+Requires-Dist: mkdocs-section-index>=0.3; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
 Provides-Extra: plotting
 Requires-Dist: kaleido>=0.2; extra == 'plotting'
 Requires-Dist: plotly>=5.0; extra == 'plotting'
@@ -43,18 +52,43 @@ Description-Content-Type: text/markdown
 # phased-array-systems
 
 [![CI](https://github.com/jman4162/phased-array-systems/actions/workflows/ci.yml/badge.svg)](https://github.com/jman4162/phased-array-systems/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://jman4162.github.io/phased-array-systems)
 [![PyPI version](https://badge.fury.io/py/phased-array-systems.svg)](https://badge.fury.io/py/phased-array-systems)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 Phased array antenna system design, optimization, and performance visualization for wireless communications and radar applications.
 
+**[Documentation](https://jman4162.github.io/phased-array-systems)** |
+**[Getting Started](https://jman4162.github.io/phased-array-systems/getting-started/quickstart/)** |
+**[API Reference](https://jman4162.github.io/phased-array-systems/api/)**
+
+## Why phased-array-systems?
+
+- **Model-Based Workflow**: MBSE/MDAO approach from requirements through optimized designs
+- **Requirements-Driven**: Every evaluation produces pass/fail with margins and traceability
+- **Trade-Space Exploration**: DOE generation and Pareto analysis for systematic design exploration
+- **Dual Application**: Supports both communications link budgets and radar detection scenarios
+- **Reproducible**: Config-driven workflow with seed control and version stamping
+
+## Workflow
+
+```
+Config (YAML/JSON) → Architecture + Scenario → DOE Generation → Batch Evaluation
+       ↓                                                              ↓
+  Requirements ───────────────────────────────────────────→ Verification
+                                                                   ↓
+                    Reports ← Visualization ← Pareto Extraction ←──┘
+```
+
 ## Features
 
 - **Requirements as first-class objects**: Every run produces pass/fail + margins with traceability
 - **Trade-space exploration**: DOE + Pareto optimization over single-point designs
+- **Communications & Radar**: Link budget analysis and radar detection modeling
 - **Flat metrics dictionary**: All models return consistent `dict[str, float]` for interchange
 - **Config-driven reproducibility**: Stable case IDs, seed control, version stamping
+- **CLI and Python API**: Use from command line or integrate into scripts
 
 ## Installation
 
@@ -169,6 +203,49 @@ pytest tests/ -v
 ruff check .
 ```
 
+## CLI
+
+```bash
+# Single case evaluation
+pasys run config.yaml
+
+# DOE batch study
+pasys doe config.yaml -n 100 --method lhs
+
+# Generate report
+pasys report results.parquet --format html
+
+# Extract Pareto frontier
+pasys pareto results.parquet -x cost_usd -y eirp_dbw --plot
+```
+
+## Documentation
+
+Full documentation is available at **[jman4162.github.io/phased-array-systems](https://jman4162.github.io/phased-array-systems)**:
+
+- [Getting Started](https://jman4162.github.io/phased-array-systems/getting-started/quickstart/) - Installation and quickstart
+- [User Guide](https://jman4162.github.io/phased-array-systems/user-guide/) - Detailed usage guides
+- [Tutorials](https://jman4162.github.io/phased-array-systems/tutorials/) - Step-by-step walkthroughs
+- [API Reference](https://jman4162.github.io/phased-array-systems/api/) - Complete API documentation
+- [Theory](https://jman4162.github.io/phased-array-systems/theory/) - Background equations and theory
+
+## Citation
+
+If you use phased-array-systems in academic work, please cite:
+
+```bibtex
+@software{phased_array_systems,
+  title = {phased-array-systems: Phased Array Antenna System Design and Optimization},
+  author = {{phased-array-systems contributors}},
+  year = {2024},
+  url = {https://github.com/jman4162/phased-array-systems}
+}
+```
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

{phased_array_systems-0.2.0 → phased_array_systems-0.4.0}/README.md

@@ -1,18 +1,43 @@
 # phased-array-systems
 
 [![CI](https://github.com/jman4162/phased-array-systems/actions/workflows/ci.yml/badge.svg)](https://github.com/jman4162/phased-array-systems/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://jman4162.github.io/phased-array-systems)
 [![PyPI version](https://badge.fury.io/py/phased-array-systems.svg)](https://badge.fury.io/py/phased-array-systems)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 Phased array antenna system design, optimization, and performance visualization for wireless communications and radar applications.
 
+**[Documentation](https://jman4162.github.io/phased-array-systems)** |
+**[Getting Started](https://jman4162.github.io/phased-array-systems/getting-started/quickstart/)** |
+**[API Reference](https://jman4162.github.io/phased-array-systems/api/)**
+
+## Why phased-array-systems?
+
+- **Model-Based Workflow**: MBSE/MDAO approach from requirements through optimized designs
+- **Requirements-Driven**: Every evaluation produces pass/fail with margins and traceability
+- **Trade-Space Exploration**: DOE generation and Pareto analysis for systematic design exploration
+- **Dual Application**: Supports both communications link budgets and radar detection scenarios
+- **Reproducible**: Config-driven workflow with seed control and version stamping
+
+## Workflow
+
+```
+Config (YAML/JSON) → Architecture + Scenario → DOE Generation → Batch Evaluation
+       ↓                                                              ↓
+  Requirements ───────────────────────────────────────────→ Verification
+                                                                   ↓
+                    Reports ← Visualization ← Pareto Extraction ←──┘
+```
+
 ## Features
 
 - **Requirements as first-class objects**: Every run produces pass/fail + margins with traceability
 - **Trade-space exploration**: DOE + Pareto optimization over single-point designs
+- **Communications & Radar**: Link budget analysis and radar detection modeling
 - **Flat metrics dictionary**: All models return consistent `dict[str, float]` for interchange
 - **Config-driven reproducibility**: Stable case IDs, seed control, version stamping
+- **CLI and Python API**: Use from command line or integrate into scripts
 
 ## Installation
 
@@ -127,6 +152,49 @@ pytest tests/ -v
 ruff check .
 ```
 
+## CLI
+
+```bash
+# Single case evaluation
+pasys run config.yaml
+
+# DOE batch study
+pasys doe config.yaml -n 100 --method lhs
+
+# Generate report
+pasys report results.parquet --format html
+
+# Extract Pareto frontier
+pasys pareto results.parquet -x cost_usd -y eirp_dbw --plot
+```
+
+## Documentation
+
+Full documentation is available at **[jman4162.github.io/phased-array-systems](https://jman4162.github.io/phased-array-systems)**:
+
+- [Getting Started](https://jman4162.github.io/phased-array-systems/getting-started/quickstart/) - Installation and quickstart
+- [User Guide](https://jman4162.github.io/phased-array-systems/user-guide/) - Detailed usage guides
+- [Tutorials](https://jman4162.github.io/phased-array-systems/tutorials/) - Step-by-step walkthroughs
+- [API Reference](https://jman4162.github.io/phased-array-systems/api/) - Complete API documentation
+- [Theory](https://jman4162.github.io/phased-array-systems/theory/) - Background equations and theory
+
+## Citation
+
+If you use phased-array-systems in academic work, please cite:
+
+```bibtex
+@software{phased_array_systems,
+  title = {phased-array-systems: Phased Array Antenna System Design and Optimization},
+  author = {{phased-array-systems contributors}},
+  year = {2024},
+  url = {https://github.com/jman4162/phased-array-systems}
+}
+```
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.