Skip to content

FAQ

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

Frequently Asked Questions (FAQ)

Common questions about DVOACAP-Python and HF propagation prediction.

Table of Contents

General Questions

What is DVOACAP-Python?

DVOACAP-Python is a Python port of the DVOACAP HF propagation prediction engine, originally written in Delphi/Pascal by Alex Shovkoplyas (VE3NEA). It implements the VOACAP ionospheric propagation model for predicting HF radio propagation conditions.

Key Features:

  • Predicts MUF (Maximum Usable Frequency)
  • Calculates signal strength and reliability
  • Models E/F1/F2 ionospheric layers
  • Performs raytracing through the ionosphere
  • Provides SNR and service probability estimates

What is VOACAP?

VOACAP (Voice of America Coverage Analysis Program) is a professional-grade HF propagation prediction tool developed by the Institute for Telecommunication Sciences (ITS) for Voice of America. It's based on decades of ionospheric research and is considered the gold standard for HF propagation prediction.

DVOACAP is a Delphi/Pascal port of VOACAP by VE3NEA, and DVOACAP-Python is a Python port of DVOACAP.

Why Python instead of the original Fortran/Delphi?

Advantages of the Python port:

  • ✅ Accessibility: Easier for modern developers to understand and use
  • ✅ Integration: Works with Python scientific stack (NumPy, SciPy, Matplotlib)
  • ✅ Documentation: Clear, modern documentation
  • ✅ Maintainability: Easier to extend and modify
  • ✅ Cross-platform: Works on Windows, macOS, Linux without compilation

Trade-offs:

  • ⚠️ Performance: Python is slower than compiled Fortran/Pascal (but still usable)
  • ⚠️ Maturity: VOACAP has 40+ years of validation; DVOACAP-Python is in active development

How accurate is DVOACAP-Python?

Current validation status (v1.0.1):

  • Phase 1-4 (Geometry, Solar, Ionosphere, Raytracing): >95% validation pass rate
  • Phase 5 (Signal Predictions): 86.6% validation pass rate

This means 86.6% of predictions match reference VOACAP output within acceptable tolerances. The remaining 13.4% show minor discrepancies at edge cases.

See Validation Status and Known Issues for details.

Can I trust DVOACAP-Python for critical applications?

Short answer: For most amateur radio use cases, yes.

Detailed answer:

  • Amateur radio planning: ✅ Excellent
  • Contest planning: ✅ Very good
  • DXpedition planning: ✅ Good (cross-check with VOACAP Online)
  • Broadcast planning: ⚠️ Use production VOACAP (Fortran version)
  • Military/critical comms: ⚠️ Use validated production tools

Recommendation: For critical applications, validate predictions against operational data or cross-check with the original VOACAP.

Is DVOACAP-Python free?

Yes! DVOACAP-Python is open source under the MIT License. You can use it freely for personal, commercial, or educational purposes.

How does DVOACAP-Python compare to other propagation tools?

Tool Accuracy Speed Ease of Use Cost
VOACAP (Fortran) ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐ Free
DVOACAP (Delphi) ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐ Free
DVOACAP-Python ⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐⭐⭐ Free
VOACAP Online ⭐⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐⭐⭐ Free
PropPy ⭐⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐⭐ Free
ITU-R P.533 ⭐⭐⭐ ⭐⭐⭐⭐⭐ ⭐⭐⭐ Free

DVOACAP-Python's niche: Easy integration into Python applications with good accuracy.

Installation & Setup

What are the system requirements?

Minimum:

  • Python 3.11 or higher
  • 200 MB disk space
  • 512 MB RAM

Recommended:

  • Python 3.11 or higher
  • 500 MB disk space (with dependencies)
  • 1 GB RAM

Operating Systems:

  • ✅ Linux (Ubuntu, Debian, Fedora, etc.)
  • ✅ macOS (Intel and Apple Silicon)
  • ✅ Windows 10/11

How do I install DVOACAP-Python?

Basic installation:

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

With dashboard:

pip install -e ".[dashboard]"

With all extras (development):

pip install -e ".[all]"

See Getting Started for detailed instructions.

Do I need the original VOACAP installed?

No! DVOACAP-Python is a standalone implementation. You don't need VOACAP, DVOACAP, or any other external propagation software.

The only data files needed are the CCIR/URSI coefficient maps, which are included in the repository (DVoaData/ directory).

Can I install DVOACAP-Python with pip from PyPI?

Not yet. DVOACAP-Python v1.0.1 is production-ready but not yet published to PyPI. Install from source using:

pip install -e .

PyPI publication is planned for a future release:

pip install dvoacap  # Planned future release

Usage Questions

How do I run a basic prediction?

from dvoacap import PredictionEngine
from dvoacap.path_geometry import GeoPoint
import numpy as np

# Create engine
engine = PredictionEngine()

# Configure
engine.params.ssn = 100.0
engine.params.month = 6
engine.params.tx_location = GeoPoint.from_degrees(40.0, -75.0)  # Philadelphia

# Run prediction
rx_location = GeoPoint.from_degrees(51.5, -0.1)  # London
engine.predict(rx_location=rx_location, utc_time=0.5, frequencies=[14.0])

# Get results
print(f"MUF: {engine.muf_calculator.muf:.2f} MHz")
print(f"SNR: {engine.predictions[0].signal.snr_db:.1f} dB")

See Quick Examples for more examples.

What frequency range does DVOACAP-Python support?

HF range: 1.6 MHz - 30 MHz (160m through 10m bands)

Tested bands:

  • 160m (1.8 MHz) ✅
  • 80m (3.5 MHz) ✅
  • 40m (7 MHz) ✅
  • 30m (10 MHz) ✅
  • 20m (14 MHz) ✅
  • 17m (18 MHz) ✅
  • 15m (21 MHz) ✅
  • 12m (24 MHz) ✅
  • 10m (28 MHz) ✅

Note: Frequencies > 30 MHz may work but are less validated.

What solar and geomagnetic parameters do I need?

Required parameters:

  • Month: 1-12
  • UTC time: 0-24 hours

Automatically fetched (when using Dashboard):

  • SFI (Solar Flux Index): Fetched live from NOAA SWPC (F10.7 cm flux)
  • SSN (Sunspot Number): Fetched live from NOAA SWPC (observed solar cycle indices)
  • Kp index: Fetched live from NOAA SWPC (planetary K-index)
  • A-index: Fetched live from NOAA SWPC (predicted A-index)

For manual API usage:

  • SSN (Sunspot Number): 0-300 (typical: 0-200)
  • Kp index: 0-9 (typical: 0-5, defaults to 2 for quiet conditions)
  • A-index: 0-400 (typical: 0-50, defaults to 10 for low absorption)

Data Sources:

Can I predict long-path propagation?

Yes! The PathGeometry module supports both short-path and long-path calculations.

from dvoacap.path_geometry import PathGeometry, GeoPoint

tx = GeoPoint.from_degrees(40.0, -75.0)
rx = GeoPoint.from_degrees(51.5, -0.1)

path = PathGeometry()
path.set_tx_rx(tx, rx)

# Short path (default)
short_distance = path.get_distance_km()
print(f"Short path: {short_distance:.0f} km")

# Long path
long_distance = (2 * 3.14159 * 6370) - short_distance
print(f"Long path: {long_distance:.0f} km")

How do I specify antenna characteristics?

Currently: DVOACAP-Python uses simplified antenna models. You can specify:

  • Transmit power (watts)
  • Basic antenna gain patterns

Future: Full antenna modeling (Yagi, log-periodic, etc.) is planned.

Accuracy & Validation

Why is the validation pass rate 86.6%?

The 86.6% pass rate for Phase 5 indicates that 86.6% of predictions match reference VOACAP within tolerances across 11 diverse test cases. The remaining 13.4% show minor discrepancies due to:

  1. Numerical differences - Python vs. Pascal floating-point operations
  2. Mode selection variations - Different propagation mode choices
  3. Edge cases - Extreme solar conditions, high latitudes, very short/long paths
  4. Over-the-MUF handling - Different approaches when frequency > MUF

Important: This validation rate exceeds the 85% target threshold and is considered production-ready. Even "failed" test cases typically show acceptable operational differences.

See Known Issues for details.

How do I validate predictions against real-world data?

Methods:

  1. Compare with operational results - Check predictions against actual QSOs
  2. PSKreporter integration - Compare with real-time reception reports
  3. Contest log analysis - Analyze QSO logs vs. predictions
  4. Cross-check with VOACAP Online - Verify against reference implementation

The dashboard includes optional PSKreporter validation.

Performance

How fast are predictions in v1.0.1?

DVOACAP v1.0.1 delivers a 2.3x performance boost over v1.0.0 through algorithmic optimizations. While predictions remain computationally intensive (full raytracing through 3D ionospheric model), they are now much faster.

Typical times (v1.0.1):

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

Computational bottlenecks:

  • Iterative raytracing (Phase 4)
  • CCIR coefficient processing (Phase 3)
  • Python overhead vs. compiled code

See Performance Tips for optimization strategies and benchmarks.

Can I speed up predictions?

Yes! Several approaches:

  1. Reduce number of regions/frequencies:

    # Fewer regions = faster
TARGET_REGIONS = {'EU': ..., 'JA': ...}  # Instead of 10 regions

  2. Increase time step:

    # Predict every 3 hours instead of 2
utc_hours = [0, 3, 6, 9, 12, 15, 18, 21]

  3. Reuse PredictionEngine:

    engine = PredictionEngine()  # Create once
# Reuse for multiple predictions

  4. Cache results: Predictions for the same conditions are identical - cache and reuse.

See Performance Tips for details.

Dashboard Questions

How do I access the dashboard?

Method 1: Flask Server (Recommended)

cd Dashboard
python3 server.py

# Visit http://localhost:8000

Method 2: Static Files

cd Dashboard
python3 generate_predictions.py
open dashboard.html

See Dashboard Guide for complete setup.

How often should I update predictions?

Recommended update frequency:

  • Normal conditions: Every 2-4 hours
  • After solar events: Immediately (flares, CMEs)
  • Before operating sessions: Generate fresh predictions
  • Automated setup: Every 2 hours via cron/scheduler

Solar conditions change slowly (hours to days), so updating every 2-4 hours is sufficient.

Can I customize the dashboard for my station?

Yes! Edit Dashboard/generate_predictions.py:

MY_QTH = {
    'call': 'YOUR_CALL',
    'lat': YOUR_LATITUDE,
    'lon': YOUR_LONGITUDE,
    'grid': 'YOUR_GRID',
    'antenna': 'Your Antenna Description',
}

TARGET_REGIONS = {
    # Add your target regions
}

BANDS = {
    # Configure your bands
}

See Dashboard Guide for details.

Can multiple users share one dashboard?

Current version: No, the dashboard is single-user.

Future plan: A multi-user web service is planned. See Dashboard/ISSUE_MULTI_USER_WEB_APP.md for the roadmap.

Development

How can I contribute to DVOACAP-Python?

We welcome contributions! Areas needing help:

  • Validation: Identify and fix failing test cases
  • Performance: Optimize hot paths (Cython, Numba)
  • Features: Es modeling, antenna patterns, output formats
  • Documentation: Examples, tutorials, API docs
  • Testing: Add test coverage

See Contributing Guide for guidelines.

What development tools do I need?

Essential:

  • Python 3.11+
  • pytest (testing)
  • black (formatting)
  • flake8 (linting)

Install all dev tools:

pip install -e ".[dev]"

See Development Setup for complete setup.

How do I run tests?

# Run all tests
pytest

# Run with coverage
pytest --cov=dvoacap tests/

# Run validation
python3 test_voacap_reference.py

See Testing Guide for details.

Troubleshooting

"ModuleNotFoundError: No module named 'dvoacap'"

Cause: Package not installed or not in Python path.

Solution:

# From repository root
pip install -e .

Dashboard shows "No data available"

Cause: Predictions haven't been generated.

Solution:

cd Dashboard
python3 generate_predictions.py

Predictions fail with "Path not feasible"

Cause: The propagation path is not possible under current conditions (e.g., frequency too high, path too long).

Solution:

  • Try a lower frequency
  • Check MUF and use frequencies below FOT (Frequency of Optimum Traffic)
  • Verify solar conditions are reasonable

Tests fail after installation

Cause: Missing test dependencies or data files.

Solution:

# Install dev dependencies
pip install -e ".[dev]"

# Ensure you're in repository root
cd /path/to/dvoacap-python
pytest

Dashboard "Refresh Predictions" button fails

Cause: Missing dependencies or import errors.

Solution:

# Install dashboard dependencies
pip install -e ".[dashboard]"

# Test generator directly
cd Dashboard
python3 generate_predictions.py

Still Have Questions?

Resources:

Contact:

  • Open an issue on GitHub
  • Check existing issues for similar questions
  • See README for project links

73! Happy HF propagation predicting! 📻

Clone this wiki locally