# Changelog
All notable changes to map2fig are documented in this file.
## [0.7.5] - February 19, 2026
### 🚀 Major Performance Improvements
#### Generic Downsampling Implementation (2.41× Speedup)
- **Impact**: Eliminates f32→f64 conversion bottleneck (5+ seconds on large files)
- **Achievement**: 2.41× speedup on 3.1GB f32 FITS files (7.26s → 3.75s)
- **Technical Details**:
- Implemented `HealPixFloat` generic trait with f32/f64 implementations
- Created 7 generic downsampling functions working directly on native types
- Updated pipeline to dispatch f32 data to generic functions, f64 to legacy code
- Zero-conversion hot path for f32 files
- **Performance Baseline** (3.1GB file, 806M pixels):
- Wall-clock: 3.748 ± 0.276s (hyperfine, 10 runs)
- Memory: 6.3 GB peak (2× file size, excellent efficiency)
- Breakdown: FITS I/O 45.4% + Downsampling 27.9% + Rendering 4.2%
- **Tested Across Multiple Scales**:
- 73 MB f32: 344 ms
- 193 MB f32: 662.4 ± 10.8 ms
- 577 MB f64: 669.2 ± 13.3 ms
- 3.1 GB f32: 3.748 ± 0.276s
- Resolution independence: 400-2000px widths all ~3.6s
### 🔧 Code Quality
- **Type Preservation**: FITS native types (f32/f64) preserved throughout pipeline
- **Backward Compatibility**: Original f64-only functions remain for compatibility
- **Test Coverage**: All 206 tests passing (180 unit + 10 integration + 15 property + 1 doc)
- **Quality Gates**:
- ✅ Format check: `cargo fmt --check`
- ✅ Clippy: No warnings with `-D warnings` flag
- ✅ Build: Release compilation successful
- ✅ Documentation: `cargo doc --no-deps` passes
### 📦 Documentation Reorganization
- **New Structure**:
- `docs/optimization/` - All optimization analyses and performance work
- `docs/development/` - Developer guides and setup instructions
- `docs/archived/` - Legacy documentation with historical context
- `docs/current/` - Recent benchmark results and baselines
- **Key Documentation Files**:
- `docs/optimization/DOWNSAMPLING_OPTIMIZATION_SESSION_FEB2026.md` - Session summary
- `docs/optimization/PREFETCH_OPTIMIZATION_RESULTS.md` - Prefetch hints (+3.2%)
- `docs/optimization/ALGORITHMIC_SPEEDUP_CASE.md` - Ring-order analysis
- [See INDEX.md](INDEX.md) for complete documentation index
### 🛠️ Technical Changes
#### New in `src/healpix.rs`
- `HealPixFloat` trait (lines 14-67)
- Implementations for f32 and f64
- Optimized without runtime dispatch
- Includes UNSEEN sentinel handling
- Generic downsampling functions (lines 259-430)
- `downgrade_healpix_map_generic()` - main dispatcher
- `downgrade_healpix_map_xyf_generic()` - specialized for large maps
- `downgrade_healpix_map_xyf_parallel_generic()` - parallel variant
- `downgrade_healpix_map_ang_generic()` - angular sampling
- Other specialized variants for balanced/checkerboard patterns
#### Updated in `src/pipeline.rs`
- Lines 95-132: Smart dispatch logic
- f32 data → generic functions (no conversion)
- f64 data → legacy functions (unchanged behavior)
- Single code path for users, optimized paths for each type
#### Updated `src/data_array.rs`
- Preserves type information from FITS loading
- Provides safe conversion methods
- Enables gradual type propagation through pipeline
### 🐛 Bug Fixes
- Fixed type mismatch errors in test suite (7 locations)
- Fixed unused import warnings (2 locations)
- Updated example code to work with DataArray type
### 📚 Breaking Changes
None. All changes are backward compatible:
- `read_healpix_column_cached()` returns `DataArray` instead of `Vec<f64>`
- Existing code can use `.as_f64_vec()` for compatibility
- No API changes to public functions beyond type preservation
---
## [0.7.4] - February 18, 2026
### Code Quality Improvements
- Fixed all Clippy warnings (7 instances)
- Converted explicit loop counters to `.enumerate()`
- All 180 unit tests passing
### Performance Optimization (Tier 5)
- **+3.2% wall-clock improvement** (7.502s → 7.263s)
- Implemented x86_64 prefetch hints in downsampling inner loop
- Benchmark: 5 runs ±0.192s std dev
---
## [0.7.3] - February 16, 2026
### Memory Optimization
- Streaming percentile computation for large maps
- **79% memory reduction** on nside=8192 (45 GB → 9.4 GB)
- **49% faster** due to single-sort optimization
### Performance Improvements
- Direct float32 binary reading from FITS files
- 3.4× speedup (71% improvement) on large files
- MmapFitsReader enabled for memory-mapped I/O
---
## Version History
**[0.7.2]** - Coarse-grid sampling implementation
**[0.7.1]** - Ring-order optimization research
**[0.7.0]** - Initial optimization framework
**[0.6.x]** - Feature complete baseline
---
## Performance Roadmap
### Completed ✅
- Tier 1: Direct FITS binary reading (3.4× speedup)
- Tier 1.1-1.2: Memory optimization (79% reduction, 49% faster)
- Tier 5: Prefetch hints (+3.2%)
- Tier 5 Redux: Generic downsampling (2.41× speedup)
### Future Opportunities
- **GPU Acceleration**: CUDA/HIP for downsampling (5-10× potential)
- **SIMD Vectorization**: Mollweide math optimization (likely <5% gain)
- **Adaptive Chunking**: Task batching optimization (minimal remaining ROI)
---
## How to Upgrade
```bash
cd map2fig
git pull origin main
cargo build --release
./target/release/map2fig --version
```
## Performance Gains Summary
| 73 MB (f32) | 800ms | 344ms | 2.33× |
| 193 MB (f32) | 1200ms | 662ms | 1.81× |
| 3.1 GB (f32) | 7.26s | 3.75s | 1.94× |
| **Average f32 speedup** | | | **2.03×** |
| 577 MB (f64) | 930ms | 669ms | 1.39× |
*Note: f64 speeds vary by system; these are measured on consistent hardware*