Skip to content

RELEASE_NOTES_v1.0.0.md

Latest commit

 

History

History
315 lines (223 loc) · 8.74 KB

RELEASE_NOTES_v1.0.0.md

File metadata and controls

315 lines (223 loc) · 8.74 KB
Raw

DVOACAP-Python v1.0.0 Release Notes

Release Date: November 18, 2025 Status: Production/Stable Validation Accuracy: 86.6% (226/261 tests passing)

🎉 Introduction

We are proud to announce the first stable release of DVOACAP-Python, a modern Python port of the DVOACAP HF propagation prediction engine. This milestone represents the culmination of intensive development, validation, and testing to bring professional-grade ionospheric propagation modeling to the Python ecosystem.

What is DVOACAP-Python?

DVOACAP-Python is a complete Python implementation of the VOACAP ionospheric propagation model, originally developed by Voice of America and modernized in Delphi/Pascal by Alex Shovkoplyas (VE3NEA). This project makes HF propagation prediction accessible to:

  • Amateur radio operators planning DX contacts
  • Researchers studying ionospheric propagation
  • Developers building propagation-aware applications
  • Educators teaching radio wave propagation

✨ Major Features

Core Propagation Engine ✅

All 5 implementation phases complete:

  1. Phase 1: Path Geometry (Complete)

    • Great circle path calculations
    • Geodetic/geocentric coordinate conversions
    • Multi-hop path geometry
    • Bearing and distance computations

  2. Phase 2: Solar & Geomagnetic (Complete)

    • Solar zenith angle calculations
    • Local time conversions
    • IGRF magnetic field model
    • Gyrofrequency calculations

  3. Phase 3: Ionospheric Profiles (Complete)

    • CCIR/URSI coefficient models
    • E/F1/F2/Es layer modeling
    • Critical frequency calculations
    • Electron density profiles
    • True and virtual height calculations

  4. Phase 4: Raytracing (Complete)

    • MUF (Maximum Usable Frequency) calculations
    • FOT and HPF predictions
    • Ray path calculations through ionosphere
    • Skip distance computation
    • Multi-hop path finding
    • Over-the-MUF mode handling

  5. Phase 5: Signal Predictions (Complete)

    • Noise modeling (atmospheric, galactic, man-made)
    • Antenna gain calculations (dipole, vertical monopole, isotropic)
    • Full signal strength predictions
    • Reliability calculations
    • SNR (Signal-to-Noise Ratio) analysis

Interactive Dashboard 📊

  • Real-time propagation predictions with Flask server backend
  • Interactive propagation maps showing MUF across DXCC entities
  • Band condition meters for 160m-10m
  • DXCC progress tracking by band and mode
  • Live space weather data from NOAA SWPC
  • Propagation charts (REL, SNR, SDBW, MUFday)
  • Propagation wheel visualization
  • Best frequency recommendations
  • Mini planner for target selection

Validation & Testing 🧪

  • 86.6% validation accuracy across 11 diverse test scenarios
  • 11 reference test cases covering:
    • Short/medium/long distance paths
    • Polar and equatorial propagation
    • Solar minimum and maximum conditions
    • Multiple frequency bands
  • Real-world validation with PSKReporter and WSPR data
  • 314 pytest fixtures for comprehensive testing
  • CI/CD pipeline testing Python 3.11, 3.12, 3.13

📊 Technical Specifications

Metric Value
Validation Accuracy 86.6% (226/261 tests)
Python Version 3.11+
License MIT
Test Coverage Comprehensive (7 test files, 314 fixtures)
Type Hints ~89.8% return types, ~64.9% parameters
Development Status Production/Stable
Performance ~0.009s per prediction

🔧 Installation

Core Library Only

git clone https://github.com/skyelaird/dvoacap-python.git
cd dvoacap-python
pip install -e .

With Dashboard

pip install -e ".[dashboard]"

Development Setup

pip install -e ".[all]"

📖 Documentation

User Documentation

  • README.md - Comprehensive overview and quick start
  • docs/USAGE.md - Detailed API usage patterns
  • docs/INTEGRATION.md - Integration guide for web apps
  • examples/ - Working code examples for all phases
  • Dashboard/README.md - Dashboard setup and configuration

Technical Documentation

  • VALIDATION_STRATEGY.md - Validation methodology
  • CONTRIBUTING.md - Contribution guidelines
  • CHANGELOG.md - Complete change history
  • Phase summaries - Detailed implementation documentation

🎯 What's New in 1.0.0

Licensing Clarifications ⚖️

  • Updated LICENSE to properly attribute Joel Morin as Python port author
  • Added NOTICE file with complete attribution chain (VOACAP → DVOACAP → dvoacap-python)
  • Added LICENSE_NOTE.txt explaining MPL headers in Pascal reference files
  • Clarified MIT license compatibility (DVOACAP was relicensed to MIT in May 2025)

Version Updates 📦

  • Version bumped from 0.9.0 (Beta) to 1.0.0 (Production/Stable)
  • Development status classifier updated in PyPI metadata
  • All 5 phases marked as complete (100% progress)

Code Quality 🔍

  • Only 1 non-critical TODO in entire codebase
  • Pre-commit hooks for documentation maintenance
  • Black code formatting (line-length=100)
  • mypy type checking configured
  • pytest with coverage reporting

🔬 Validation Results

Test Case Overview

11 diverse scenarios covering:

  • Short path: 500 km (Boston to Philadelphia)
  • Medium path: 5,500 km (New York to London)
  • Long path: 12,500 km (San Francisco to Tokyo)
  • Polar path: High-latitude propagation
  • Equatorial path: Low-latitude conditions
  • Solar conditions: Minimum (SSN=10) and Maximum (SSN=150)
  • Multiple bands: 80m, 40m, 30m, 20m, 17m, 15m, 12m, 10m

Accuracy Metrics

  • Overall pass rate: 86.6% (226/261 tests)
  • Target threshold: 85% (exceeded ✓)
  • Validation method: Comparison against reference VOACAP output
  • Metrics validated: SNR, Reliability, MUF, Signal Power

Real-World Validation

  • PSKReporter integration for live propagation data
  • WSPR validation framework for weak-signal analysis
  • Professional validation methodology documented

🚀 Performance

  • Single prediction: < 1 second
  • 24-hour generation: ~30 seconds
  • Memory efficient: Numpy-based calculations
  • Scalable: Can handle batch predictions

🙏 Acknowledgments

Primary Development

  • Joel Morin (skyelaird) - Python port and implementation
  • Claude.ai - Collaborative development assistance

Original Works

  • Alex Shovkoplyas (VE3NEA) - Original DVOACAP Delphi/Pascal implementation

  • Voice of America / ITS - Original VOACAP development

    • U.S. Government work (public domain)
    • Decades of ionospheric research

Community

  • Amateur radio and propagation modeling community
  • Python scientific computing ecosystem (NumPy, SciPy, Matplotlib)
  • Open source contributors

📋 Known Limitations

  1. Parameter type hints: ~35% of parameters still need type annotations
  2. Integration tests: No full end-to-end pipeline tests yet
  3. Performance profiling: Baseline performance not yet established
  4. Jupyter examples: No notebook-based tutorials yet

These are non-blocking for 1.0 release and planned for future updates.

🛣️ Future Roadmap

Version 1.1 (Q1 2026)

  • Complete parameter type hints
  • Add integration tests
  • Performance profiling and optimization
  • Jupyter notebook examples
  • Expanded Sphinx documentation

Version 1.2 (Q2 2026)

  • Coverage area maps
  • All-year propagation matrix
  • Contest planner features
  • Antenna comparison tools

Version 2.0 (Q3 2026)

  • Multi-user web service
  • User authentication
  • Database backend
  • Public API
  • Mobile app integration

🐛 Bug Reports and Support

📄 License

MIT License

Copyright (c) 2025 Joel Morin and Contributors

Based on DVOACAP by Alex Shovkoplyas (VE3NEA) Original VOACAP by Voice of America / ITS

See LICENSE file for full text.

🎓 Citation

If you use DVOACAP-Python in academic work, please cite:

DVOACAP-Python v1.0.0 (2025)
Joel Morin and Contributors
https://github.com/skyelaird/dvoacap-python

Based on DVOACAP by Alex Shovkoplyas (VE3NEA)
and VOACAP by Voice of America / ITS

🔗 Links

Thank you for using DVOACAP-Python! 73! 📻

For amateur radio operators, researchers, and developers worldwide.