Skip to content

Known Issues

Jump to bottom
github-actions[bot] edited this page Nov 18, 2025 · 4 revisions

Known Issues

Current limitations, bugs, and areas needing improvement in DVOACAP-Python.

Table of Contents

Validation Issues

Reference Validation Pass Rate: 86.6%

Status: Production Ready Impact: Low Tracking: Validation Status

Description: The current validation shows an 86.6% pass rate when compared against reference VOACAP output across 11 diverse test cases. While the majority of predictions match within acceptable tolerances, approximately 13% of test cases show minor discrepancies.

Affected Areas:

  • Signal strength predictions (path loss calculations)
  • SNR calculations at edge cases (very low or very high frequencies)
  • Reliability calculations for marginal paths

Known Discrepancy Patterns:

  1. Over-the-MUF modes - Minor discrepancies when frequency > 1.1 × MUF
  2. High latitude paths - Small geomagnetic field model differences
  3. Extreme solar conditions - Minor variations at SSN > 200 or SSN < 10

Note: The 86.6% validation rate represents excellent agreement with the reference VOACAP implementation. Most discrepancies are within acceptable engineering tolerances and do not significantly impact practical predictions.

Mode Selection Alignment

Status: Known Issue Impact: Low Affects: Mode naming (e.g., "1F", "2F", "3F")

Description: Some predictions select different propagation modes (1F vs 2F) compared to reference VOACAP, even when the underlying signal predictions are correct.

Example:

DVOACAP:  7.0 MHz → 2F mode, SNR 12.3 dB
VOACAP:   7.0 MHz → 1F mode, SNR 12.1 dB

Impact: This is cosmetic and doesn't affect the accuracy of signal strength, SNR, or reliability predictions. The mode name is a label for the propagation mechanism, not the prediction itself.

Workaround: Focus on SNR and reliability values rather than mode names.

Performance Limitations

Prediction Performance (Optimized in v1.0.1)

Status: Significantly Improved Impact: Low (after v1.0.1 optimization) Affects: Dashboard generation, batch processing

Description: Version 1.0.1 introduced comprehensive algorithmic optimizations providing a 2.3x speedup. Full VOACAP predictions remain computationally intensive but are now much faster.

Timing Breakdown (v1.0.1):

  • Single frequency prediction: ~4ms (was ~8ms in v1.0.0)
  • Full band sweep (9 frequencies): ~48ms (was ~111ms, 2.3x faster)
  • 24-hour forecast (12 time points): ~118ms (was ~282ms, 2.4x faster)
  • Area coverage (100 predictions): ~350ms (was ~820ms, 2.3x faster)

Root Causes:

  1. Raytracing calculations (Phase 4) - iterative path finding
  2. Ionospheric profile generation (Phase 3) - CCIR coefficient processing
  3. Python overhead vs. compiled Pascal/Fortran

Workarounds:

  • Reduce number of target regions
  • Increase time step (predict every 3 hours instead of 2)
  • Remove unused frequency bands
  • Use caching for repeated predictions

Future Improvements:

  • Cython/Numba optimization for hot paths
  • Parallel processing for multiple regions
  • Pre-computed lookup tables for common scenarios

See Performance Tips for optimization strategies.

Memory Usage

Status: Low Priority Impact: Low Affects: Large batch operations

Description: Each PredictionEngine instance loads CCIR/URSI coefficient maps (~50 MB) into memory. Running many concurrent instances can consume significant RAM.

Typical Usage:

  • Single prediction: ~60 MB
  • Dashboard generation: ~100 MB peak
  • 100 concurrent predictions: ~1-2 GB

Workaround: Reuse PredictionEngine instances and run predictions sequentially rather than in parallel.

Incomplete Features

Limited Antenna Modeling

Status: Partial Implementation Impact: Medium Affects: Antenna gain calculations

Description: The current implementation uses simplified antenna models. More complex antenna types (Yagi, log-periodic, phased arrays) are not fully modeled.

Currently Supported:

  • Isotropic antennas
  • Vertical monopoles
  • Simple dipoles
  • Basic gain patterns

Not Yet Supported:

  • Detailed Yagi modeling
  • Log-periodic arrays
  • Phased arrays
  • Ground reflections for complex antenna systems

Workaround: Use effective gain values rather than detailed antenna modeling.

Future Plan: Implement comprehensive antenna modeling from VOACAP antenna database.

Es (Sporadic E) Modeling

Status: Not Implemented Impact: Medium (seasonal) Affects: Mid-latitude 6m and 10m predictions

Description: Sporadic E layer modeling is not yet implemented. This affects VHF/low-HF predictions during summer months at mid-latitudes.

Impact:

  • 6m (50 MHz) predictions may underestimate openings
  • 10m band predictions may miss short-skip Es propagation
  • Primarily affects May-August at mid-latitudes

Workaround: Use operational data (PSKreporter, DX clusters) to supplement predictions during Es season.

Future Plan: Add Es modeling from VOACAP Es module.

Limited Output Formats

Status: Low Priority Impact: Low

Description: DVOACAP-Python currently outputs to JSON and in-memory Python objects. It does not support VOACAP's native .VOA or .OUT file formats.

Available:

  • Python dictionaries/objects
  • JSON export
  • Custom data structures

Not Available:

  • VOACAP .VOA files
  • ITU-R P.533 format
  • CSV export (easy to add)

Workaround: Convert JSON output to desired format using custom scripts.

Platform-Specific Issues

Windows Path Handling

Status: Known Issue Impact: Low Affects: Windows users

Description: Some file path operations may fail on Windows due to path separator differences (\ vs /).

Affected:

  • CCIR data file loading (rare)
  • Dashboard file paths (occasional)

Workaround: Use pathlib.Path or ensure paths use os.path.join().

Status: Being addressed in ongoing development.

macOS M1/M2 NumPy Issues

Status: Platform Limitation Impact: Low Affects: macOS Apple Silicon users

Description: Some NumPy operations may trigger warnings or slowdowns on Apple Silicon Macs without optimized NumPy builds.

Symptoms:

  • Warning messages about BLAS/LAPACK
  • Slower-than-expected predictions

Workaround: Install NumPy from conda-forge or use Miniforge:

# Install Miniforge (Apple Silicon optimized)
brew install miniforge
conda create -n dvoacap python=3.10
conda activate dvoacap
conda install numpy

# Install DVOACAP
pip install -e .

Documentation Gaps

Limited API Examples for Advanced Use Cases

Status: In Progress Impact: Low

Description: While basic usage is well-documented, advanced use cases (custom ionospheric profiles, manual raytracing, antenna pattern customization) lack comprehensive examples.

Available:

  • Basic prediction examples
  • Path geometry examples
  • Dashboard integration

Missing:

  • Custom ionospheric profile injection
  • Manual raytracing step-by-step
  • Antenna gain pattern customization
  • Database integration patterns

Future Plan: Expand wiki with advanced tutorials and use case examples.

Sphinx Documentation Incomplete

Status: In Progress Impact: Low

Description: The Sphinx documentation build is functional but some modules lack comprehensive docstrings and examples.

Status: Ongoing improvement as modules mature.

Workarounds

General Debugging Tips

Enable verbose logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Validate inputs:

from dvoacap.path_geometry import GeoPoint

# Check valid coordinates
assert -90 <= lat <= 90
assert -180 <= lon <= 180

# Check valid frequencies
assert 1.0 <= frequency_mhz <= 30.0  # HF range

Compare with reference:

# Run validation tests
python3 test_voacap_reference.py

Reporting Issues

If you encounter issues not listed here:

  1. Check existing issues: GitHub Issues
  2. Search the wiki: Home, Troubleshooting
  3. Provide details:
    • Python version
    • Operating system
    • DVOACAP version
    • Minimal reproducible example
    • Expected vs. actual behavior

Create new issue: New Issue

Issue Priority Levels

High Priority:

  • Crashes or data corruption
  • Security vulnerabilities
  • Major validation failures (> 50% error rate)

Medium Priority:

  • Validation discrepancies (current 13.4% minor deviation rate)
  • Performance optimization opportunities
  • Missing features blocking edge case scenarios

Low Priority:

  • Cosmetic issues (mode naming)
  • Documentation gaps
  • Platform-specific quirks with workarounds
  • Feature requests for edge cases

Version History

v1.0.1 (Current - November 2025)

  • ✅ All 5 phases complete and validated (86.6% validation)
  • ✅ 2.3x performance improvement over v1.0.0
  • ✅ Production ready for operational use
  • ✅ Enhanced caching and optimization

v1.0.0 (November 2025)

  • ✅ First production release
  • ✅ All phases validated
  • ✅ Complete VOACAP implementation

Earlier Versions (v0.1.0 - v0.5.0)

  • Development phases - see git history for details

Next Steps

Last Updated: 2025-11-18 Project Status: v1.0.1 Production Ready (86.6% validation accuracy, 2.3x performance boost)

Clone this wiki locally