Investigate VOACAP prediction performance issues

[skyelaird]

Summary

Investigated claims in the Known Issues wiki page and found MAJOR inaccuracies in performance and memory usage documentation.

Key Findings

Performance Claims - COMPLETELY WRONG

• Wiki claims: 60-90 seconds for dashboard (840 predictions)
• Actual measured: 5.31 seconds
• Reality: 11-17x FASTER than documented

Performance details:

• Single prediction: 5-6 ms (wiki claimed 200-500 ms)
• Dashboard generation: 5.3s (wiki claimed 60-90s)
• Throughput: 158 predictions/second

Memory Claims - COMPLETELY WRONG

• Wiki claims: ~50 MB for CCIR/URSI maps
• Actual on-disk size: 556 KB total
• Reality: 50-100x LOWER than documented

Memory details:

• CCIR/URSI data: 556 KB on disk, ~1 MB in memory
• Single prediction: ~10-20 MB total process (wiki claimed 60 MB)
• Dashboard: ~20-30 MB peak (wiki claimed 100 MB)

Antenna Support - PARTIALLY WRONG

• Wiki claims Yagi antennas are "Not Yet Supported"
• Reality: ThreeElementYagi class EXISTS and is functional
• Only complex multi-element Yagi arrays are unsupported

Accurate Claims

• ✓ Es (Sporadic E) modeling not implemented (confirmed)
• ✓ 86.6% validation pass rate (appears accurate)

Files Added

1. WIKI_ACCURACY_REPORT.md - Detailed analysis of wiki inaccuracies
2. KNOWN_ISSUES_CORRECTED.md - Corrected version of Known Issues
3. test_dashboard_performance.py - Benchmark for dashboard scenario
4. test_memory_usage.py - Memory profiling test

Recommendations

The Known Issues wiki page requires immediate correction:

• Remove "Performance Limitations" as a major issue
• Update all timing claims to reflect actual performance
• Correct memory usage claims (50MB → 1MB)
• Move Yagi from "not supported" to "supported"
• Reframe performance as a STRENGTH, not a weakness

Test Results

Dashboard Scenario (10 regions × 7 bands × 12 hours = 840 predictions):
Total time: 5.31 seconds
Average: 6.32 ms per prediction
Rate: 158.3 predictions/second
Wiki claim: 60-90 seconds
Speedup: 11-17x faster than claimed

Issue: None (investigation only)

Description

A clear and concise description of what this PR does.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Code refactoring
• Test coverage improvement

Related Issues

Closes #(issue number)
Related to #(issue number)

Changes Made

• Change 1
• Change 2
• Change 3

Testing

Describe the tests you've run to verify your changes:

Test Configuration

• Python version:
• Operating System:
• NumPy/SciPy versions:

Test Results

# Command used to test
python -m pytest tests/

# Or validation command
python test_voacap_reference.py

• All existing tests pass
• New tests added for new functionality
• Validation pass rate maintained or improved
• No performance regression

Validation Checklist

• Code follows PEP 8 style guidelines
• Docstrings added/updated for public functions
• Type hints added where appropriate
• Comments added for complex logic
• Documentation updated (README, USAGE, etc.)
• CHANGELOG.md updated
• No new warnings or errors introduced

Performance Impact

• No performance impact
• Performance improved (provide benchmarks)
• Minor performance regression (justified because...)
• Not applicable

Benchmarks (if applicable)

Before: X seconds
After: Y seconds
Change: Z% improvement/regression

Breaking Changes

If this PR introduces breaking changes, describe:

1. What breaks
2. Migration path for users
3. Why this change is necessary

Screenshots/Output (if applicable)

For dashboard changes or output format changes, include before/after screenshots or sample output.

Additional Notes

Any additional information that reviewers should know:

• Assumptions made
• Trade-offs considered
• Future work needed
• Dependencies added/removed

Reviewer Checklist

For maintainers reviewing this PR:

• Code quality is acceptable
• Tests are comprehensive
• Documentation is clear
• Validation results are acceptable
• No security issues introduced
• Backward compatibility maintained (or breaking changes justified)