182 lines
6.8 KiB
Markdown
182 lines
6.8 KiB
Markdown
# RFCP 3.8.0 — Vectorize Per-Point Coverage Calculations
|
||
|
||
## Context
|
||
|
||
Iteration 3.7.0 added GPU precompute for distances + base path loss (Phase 2.5).
|
||
But Phase 3 (per-point loop) still runs on CPU, one point at a time across workers.
|
||
This is where 95% of time goes on Full preset (195s for 6,642 points).
|
||
|
||
Current pipeline:
|
||
```
|
||
Phase 2.5 (GPU, 0.01s): distances + base path_loss → precomputed arrays
|
||
Phase 3 (CPU, 195s): per-point terrain_loss, building_loss, reflections, vegetation
|
||
```
|
||
|
||
Goal: Vectorize the heavy per-point calculations so GPU handles them in bulk.
|
||
|
||
## Architecture
|
||
|
||
The key insight: `_calculate_point_sync` (line ~1127) does these steps per point:
|
||
|
||
1. **Terrain LOS check** — get elevation profile between site and point, check clearance
|
||
2. **Diffraction loss** — knife-edge based on Fresnel zone clearance
|
||
3. **Building obstruction** — find buildings between site and point, calculate penetration loss
|
||
4. **Materials penalty** — add loss based on building material type
|
||
5. **Dominant path analysis** — LOS vs reflection vs diffraction
|
||
6. **Street canyon** — check if point is in urban canyon
|
||
7. **Reflections** — find reflection paths off buildings (most expensive!)
|
||
8. **Vegetation loss** — check vegetation between site and point
|
||
9. **Final RSRP** — tx_power - path_loss - terrain_loss - building_loss - veg_loss + gains
|
||
|
||
## Strategy: Vectorize in Stages
|
||
|
||
NOT everything can be vectorized equally. Prioritize by time spent:
|
||
|
||
### Stage 1: Terrain LOS + Diffraction (HIGH IMPACT)
|
||
Currently: For each point, sample ~50-100 elevation values along radial path,
|
||
find min clearance, compute knife-edge diffraction.
|
||
|
||
**Vectorize**: Create 2D elevation profiles for ALL points at once.
|
||
- All points share the same site location
|
||
- For N points, create N terrain profiles (each M samples)
|
||
- Compute Fresnel clearance for all profiles vectorized
|
||
- Compute diffraction loss vectorized
|
||
|
||
```python
|
||
# Instead of per-point:
|
||
for point in grid:
|
||
profile = get_terrain_profile(site, point, num_samples=50)
|
||
clearance = min_clearance(profile)
|
||
loss = diffraction_loss(clearance, freq)
|
||
|
||
# Vectorized:
|
||
xp = gpu_manager.get_array_module()
|
||
# all_profiles shape: (N_points, M_samples)
|
||
all_profiles = get_terrain_profiles_batch(site, all_points, num_samples=50)
|
||
all_clearances = compute_clearances_batch(all_profiles, site_elev, point_elevs, distances)
|
||
all_terrain_loss = diffraction_loss_batch(all_clearances, freq)
|
||
```
|
||
|
||
### Stage 2: Building Obstruction (HIGH IMPACT)
|
||
Currently: For each point, find nearby buildings, check if they obstruct path.
|
||
|
||
**Vectorize**: Use spatial indexing but batch the geometry checks.
|
||
- Pre-compute building bounding boxes as GPU arrays
|
||
- For each point, ray-building intersection can be done as matrix operation
|
||
- Building penetration loss is simple lookup after intersection
|
||
|
||
NOTE: This is harder to vectorize because each point has different number of
|
||
nearby buildings. Options:
|
||
a) Pad to max buildings per point (wastes memory but simple)
|
||
b) Use sparse representation
|
||
c) Keep per-point but use GPU for the geometry math
|
||
|
||
Recommend option (c) initially — keep the spatial query on CPU but move
|
||
the trig/geometry calculations to GPU.
|
||
|
||
### Stage 3: Reflections (MEDIUM IMPACT, only on Full preset)
|
||
Currently: For each point with buildings, compute reflection paths.
|
||
This is the most complex calculation and hardest to vectorize.
|
||
|
||
**Approach**: Keep reflections per-point for now, but optimize the inner math
|
||
with vectorized operations.
|
||
|
||
### Stage 4: Vegetation Loss (LOW IMPACT)
|
||
Simple lookup — not worth GPU overhead.
|
||
|
||
## Implementation Plan
|
||
|
||
### Step 1: Batch terrain profiling
|
||
Add to coverage_service.py a new method:
|
||
```python
|
||
def _batch_terrain_profiles(self, site_lat, site_lon, site_elev,
|
||
grid_lats, grid_lons, grid_elevs,
|
||
distances, frequency, num_samples=50):
|
||
"""Compute terrain LOS and diffraction loss for all points at once."""
|
||
xp = gpu_manager.get_array_module()
|
||
N = len(grid_lats)
|
||
|
||
# Interpolate terrain profiles for all points
|
||
# Each profile: site → point, num_samples elevation values
|
||
# Use terrain tile data directly
|
||
|
||
# Compute Fresnel zone clearance for each profile
|
||
# Compute knife-edge diffraction loss
|
||
|
||
return terrain_losses # shape (N,)
|
||
```
|
||
|
||
### Step 2: Batch building check
|
||
Add method:
|
||
```python
|
||
def _batch_building_obstruction(self, site_lat, site_lon,
|
||
grid_lats, grid_lons,
|
||
distances, buildings_spatial_index,
|
||
all_buildings):
|
||
"""Compute building loss for all points at once."""
|
||
# For each point, query spatial index (CPU)
|
||
# Batch the geometry intersection math (GPU)
|
||
# Return losses
|
||
|
||
return building_losses # shape (N,)
|
||
```
|
||
|
||
### Step 3: Replace _run_point_loop
|
||
Instead of ProcessPool workers, do:
|
||
```python
|
||
# In calculate_coverage, after Phase 2.5:
|
||
terrain_losses = self._batch_terrain_profiles(...)
|
||
building_losses = self._batch_building_obstruction(...)
|
||
|
||
# Final RSRP is now fully vectorized:
|
||
rsrp = tx_power - precomputed_path_loss - terrain_losses - building_losses - veg_losses
|
||
# + antenna_gains + reflection_gains
|
||
```
|
||
|
||
### Step 4: Keep worker fallback
|
||
If GPU not available or for very complex calculations (reflections),
|
||
fall back to the existing per-point ProcessPool approach.
|
||
|
||
## Important Notes
|
||
|
||
1. **GPU code only in main process** — learned from 3.7.0, never import gpu_manager in workers
|
||
2. **Terrain data access** — terrain tiles are in memory, need efficient sampling for batch profiles
|
||
3. **CuPy ↔ NumPy bridge** — use `xp.asnumpy()` or `.get()` to convert back to CPU
|
||
4. **Memory** — 6,642 points × 50 terrain samples = 332,100 floats = 2.5 MB on GPU, no problem
|
||
5. **Accuracy** — results must match existing per-point calculation within 1 dB
|
||
|
||
## Testing
|
||
|
||
```powershell
|
||
cd D:\root\rfcp\backend
|
||
pyinstaller ..\installer\rfcp-server-gpu.spec --noconfirm
|
||
.\dist\rfcp-server\rfcp-server.exe
|
||
```
|
||
|
||
Compare Full preset:
|
||
- Before (3.7.0): ~195s for 6,642 points
|
||
- Target (3.8.0): <30s for same calculation
|
||
- Stretch goal: <10s
|
||
|
||
Verify accuracy:
|
||
- Run same location with GPU and CPU backend
|
||
- Compare RSRP values — should be within 1 dB
|
||
- Coverage percentages (Excellent/Good/Fair/Weak) should be very close
|
||
|
||
## What NOT to Change
|
||
|
||
- Don't modify propagation model math (Okumura-Hata, COST-231, Free-Space formulas)
|
||
- Don't change API endpoints or response format
|
||
- Don't remove the ProcessPool fallback — keep it for CPU-only mode
|
||
- Don't change OSM fetching or caching
|
||
- Don't modify the frontend
|
||
|
||
## Success Criteria
|
||
|
||
- [ ] Full preset completes in <30s (was 195s)
|
||
- [ ] Standard preset completes in <5s (was 7.2s)
|
||
- [ ] No CuPy errors in worker processes
|
||
- [ ] CPU fallback still works
|
||
- [ ] Results match within 1 dB accuracy
|
||
- [ ] GPU utilization visible in Task Manager during calculation
|