From c459393faac7c04af4fc760d23e0b7ee3a4e367b Mon Sep 17 00:00:00 2001 From: Dominik Strebel Date: Tue, 3 Nov 2026 15:38:18 +0100 Subject: [PATCH 1/2] perf(analysis): k-means and Kernel Density make their rows on several cores (#1252) k-means finds its centres on a sample of the pixels; the pass that gives every pixel its nearest centre now runs on parallel::for_each_row. Kernel Density cuts its rows into strips, a few per thread. Each strip takes the points that reach it in their order, so every cell adds the same contributions in the same order as on one thread: the result is bit for bit the same. Its work limit now scales with the threads (parallel::work_cap), as Viewshed's, IDW's and Kriging's do, and its error names the limit and the threads counted. A cancelled run comes back as cancelled rather than as an unfinished grid. --- crates/analysis/src/density.rs | 197 +++++++++++++++++++++++-------- crates/analysis/src/rasterops.rs | 50 +++++++- docs/user-guide/analysis.md | 6 +- 3 files changed, 196 insertions(+), 57 deletions(-) diff --git a/crates/analysis/src/density.rs b/crates/analysis/src/density.rs index b7f7e1bd91..bbac3e6303 100644 --- a/crates/analysis/src/density.rs +++ b/crates/analysis/src/density.rs @@ -38,9 +38,17 @@ impl KernelType { /// Upper limit on total output raster cells to prevent memory exhaustion (64 MB for f32). pub const MAX_DENSITY_CELLS: usize = 16_000_000; -/// Upper limit on aggregate cell visits across all points to prevent CPU exhaustion. +/// Upper limit on aggregate cell visits across all points on one thread, to prevent CPU +/// exhaustion; a run on several threads may take as many times more +/// ([`crate::parallel::work_cap`]). pub const MAX_DENSITY_WORK: usize = 50_000_000; +/// The points between two counts of a strip's progress and checks for a cancel. +const PROGRESS_POINTS: usize = 4096; +/// The cells the points' kernels reach (a few milliseconds of them) after which a strip counts its +/// progress and checks for a cancel sooner: a few points with large kernels. +const PROGRESS_CELLS: usize = 1 << 20; + /// Default target grid resolution along the longer side of the extent when pixel size is not specified. const DEFAULT_GRID_STEPS: f64 = 250.0; @@ -153,7 +161,12 @@ pub fn resolve_grid_extent(pt_extent: &Extent, bandwidth: f64, custom_extent: Op Ok(base_extent) } +/// Adds each point's kernel (`eval`) to the cells of `grid` it reaches, on `threads` threads. The +/// rows are cut into strips, a few per thread so that strips that cost more are shared out; each +/// strip takes the points that reach it in their order, so every cell adds them up as one thread +/// does (#1252). Progress counts each strip's points. fn accumulate_density( + threads: usize, points: &[(Coord, f64)], grid: &mut [f64], w: usize, @@ -164,52 +177,76 @@ fn accumulate_density( bandwidth: f64, h_sq: f64, eval: F, -) where - F: Fn(f64, f64) -> f64, +) -> Result<(), crate::control::Cancelled> +where + F: Fn(f64, f64) -> f64 + Sync, { - crate::control::begin(points.len()); - for (i, &(p, wgt)) in points.iter().enumerate() { - if crate::control::cancelled() { - return; - } - crate::control::reached(i); - if wgt <= 0.0 || !wgt.is_finite() || !p.is_finite() { - continue; - } - - let col_min = (((p.x - bandwidth - origin_x) / cell_size).floor() as isize).clamp(0, (w - 1) as isize) as usize; - let col_max = (((p.x + bandwidth - origin_x) / cell_size).ceil() as isize).clamp(0, (w - 1) as isize) as usize; - - let row_min = (((origin_y - (p.y + bandwidth)) / cell_size).floor() as isize).clamp(0, (h_rows - 1) as isize) as usize; - let row_max = (((origin_y - (p.y - bandwidth)) / cell_size).ceil() as isize).clamp(0, (h_rows - 1) as isize) as usize; - - for row in row_min..=row_max { - let y_cell = origin_y - (row as f64 + 0.5) * cell_size; - let dy = p.y - y_cell; - let dy_sq = dy * dy; - if dy_sq >= h_sq { - continue; - } - let rem_sq = h_sq - dy_sq; - let row_offset = row * w; - - for col in col_min..=col_max { - let x_cell = origin_x + (col as f64 + 0.5) * cell_size; - let dx = p.x - x_cell; - let dx_sq = dx * dx; - if dx_sq >= rem_sq { + let strips = if threads <= 1 { 1 } else { h_rows.min(threads.saturating_mul(4)) }; + let strip_rows = h_rows.div_ceil(strips.max(1)).max(1); + // The strips the rows make (fewer than asked for when they don't divide evenly). + let strips = h_rows.div_ceil(strip_rows); + // Each strip counts its points as it goes, and once more when done. + crate::control::begin(strips.saturating_mul(points.len().saturating_add(1))); + crate::parallel::for_each_row( + grid.chunks_mut(w * strip_rows), + threads, + || (), + |_, s, strip: &mut [f64]| { + let first = s * strip_rows; + let last = first + strip.len() / w - 1; + let (mut counted, mut cells) = (0, 0usize); + for (i, &(p, wgt)) in points.iter().enumerate() { + if i - counted == PROGRESS_POINTS || cells >= PROGRESS_CELLS { + if crate::control::cancelled() { + return; + } + crate::control::advance(i - counted); + (counted, cells) = (i, 0); + } + if wgt <= 0.0 || !wgt.is_finite() || !p.is_finite() { continue; } - let d_sq = dx_sq + dy_sq; - let contrib = eval(d_sq, wgt); - - if let Some(cell) = grid.get_mut(row_offset + col) { - *cell += contrib; + let col_min = (((p.x - bandwidth - origin_x) / cell_size).floor() as isize).clamp(0, (w - 1) as isize) as usize; + let col_max = (((p.x + bandwidth - origin_x) / cell_size).ceil() as isize).clamp(0, (w - 1) as isize) as usize; + + let row_min = (((origin_y - (p.y + bandwidth)) / cell_size).floor() as isize).clamp(0, (h_rows - 1) as isize) as usize; + let row_max = (((origin_y - (p.y - bandwidth)) / cell_size).ceil() as isize).clamp(0, (h_rows - 1) as isize) as usize; + + let (top, bottom) = (row_min.max(first), row_max.min(last)); + cells = cells.saturating_add((bottom + 1).saturating_sub(top).saturating_mul((col_max + 1).saturating_sub(col_min))); + for row in top..=bottom { + let y_cell = origin_y - (row as f64 + 0.5) * cell_size; + let dy = p.y - y_cell; + let dy_sq = dy * dy; + if dy_sq >= h_sq { + continue; + } + let rem_sq = h_sq - dy_sq; + let row_offset = (row - first) * w; + + for col in col_min..=col_max { + let x_cell = origin_x + (col as f64 + 0.5) * cell_size; + let dx = p.x - x_cell; + let dx_sq = dx * dx; + if dx_sq >= rem_sq { + continue; + } + + let d_sq = dx_sq + dy_sq; + let contrib = eval(d_sq, wgt); + + if let Some(cell) = strip.get_mut(row_offset + col) { + *cell += contrib; + } + } } } - } - } + crate::control::advance(points.len() - counted); + }, + )?; + // A strip stopped part of the way leaves the grid unfinished: it is not the result. + crate::control::check() } /// Generates a continuous kernel density raster from weighted points in a projected CRS. @@ -221,6 +258,20 @@ pub fn kernel_density( kernel: KernelType, name: &str, crs: Crs, +) -> Result { + kernel_density_on(None, points, custom_extent, cell_size, bandwidth, kernel, name, crs) +} + +/// [`kernel_density`] on `threads` threads (none: as many as pay off). +fn kernel_density_on( + threads: Option, + points: &[(Coord, f64)], + custom_extent: Option<&Extent>, + cell_size: f64, + bandwidth: f64, + kernel: KernelType, + name: &str, + crs: Crs, ) -> Result { if points.is_empty() { return Err("kernel density requires at least one point".into()); @@ -270,9 +321,12 @@ pub fn kernel_density( total_cells }; let total_work = points.len().saturating_mul(cells_per_point); - if total_work > MAX_DENSITY_WORK { + // A cell visit is some 5 ns, a sixth of `MIN_ROW_WORK`'s unit. + let threads = threads.unwrap_or_else(|| crate::parallel::threads_for_rows(h_rows, total_work / 6, 0)); + let cap = crate::parallel::work_cap(MAX_DENSITY_WORK, threads); + if total_work > cap { return Err(format!( - "{w} × {h_rows} cells from {} points is too much work; choose a larger pixel size or a smaller search radius", + "{w} × {h_rows} cells from {} points is too much work, more than the {cap} cell visits this computer takes on {threads} thread(s); choose a larger pixel size or a smaller search radius", points.len() )); } @@ -292,10 +346,10 @@ pub fn kernel_density( if !factor.is_normal() { return Err("search radius is out of range".into()); } - accumulate_density(points, &mut grid, w, h_rows, origin_x, origin_y, cell_size, bandwidth, h_sq, |d_sq, wgt| { + accumulate_density(threads, points, &mut grid, w, h_rows, origin_x, origin_y, cell_size, bandwidth, h_sq, |d_sq, wgt| { let val = 1.0 - d_sq / h_sq; wgt * factor * val * val - }); + })?; } KernelType::Gaussian => { // Truncate at 3σ = bandwidth and renormalise so the kernel integrates to 1 over the disk. @@ -309,9 +363,9 @@ pub fn kernel_density( if !factor.is_normal() { return Err("search radius is out of range".into()); } - accumulate_density(points, &mut grid, w, h_rows, origin_x, origin_y, cell_size, bandwidth, h_sq, |d_sq, wgt| { + accumulate_density(threads, points, &mut grid, w, h_rows, origin_x, origin_y, cell_size, bandwidth, h_sq, |d_sq, wgt| { wgt * factor * (-d_sq / two_sigma_sq).exp() - }); + })?; } } @@ -480,11 +534,15 @@ mod tests { #[test] fn excessive_workload_is_rejected() { - // 50,000 points in a 100x100 grid (10,000 cells <= MAX_DENSITY_CELLS) with large radius + // 50,000 points in a 100x100 grid (10,000 cells <= MAX_DENSITY_CELLS) with large radius: + // 500 million cell visits, more than one thread takes (several may take them). let pts: Vec<(Coord, f64)> = (0..50_000).map(|_| (Coord::new(500.0, 500.0), 1.0)).collect(); let ext = Extent::new(0.0, 0.0, 1000.0, 1000.0); - let err = kernel_density(&pts, Some(&ext), 10.0, 1000.0, KernelType::Quartic, "huge", Crs::WebMercator).unwrap_err(); - assert!(err.contains("too much work"), "{err}"); + let err = kernel_density_on(Some(1), &pts, Some(&ext), 10.0, 1000.0, KernelType::Quartic, "huge", Crs::WebMercator).unwrap_err(); + assert!( + err.contains("too much work") && err.contains(&format!("the {MAX_DENSITY_WORK} cell visits")) && err.contains("1 thread(s)"), + "{err}" + ); } #[test] @@ -558,4 +616,43 @@ mod tests { let err = kernel_density(&[(pt, 1e42)], None, 5.0, 50.0, KernelType::Quartic, "huge_weight", Crs::WebMercator).unwrap_err(); assert!(err.contains("calculated density values produced non-finite numbers"), "{err}"); } + + /// A density made on several threads is the one made on one, bit for bit (#1252): each strip + /// of rows adds the points that reach it in their order, as one thread adds them to a cell. + #[test] + fn kernel_density_on_several_threads_is_on_one() { + // 3,000 points, weighed, clustered and spread, so kernels cross the strips' edges. + let mut x = 12_345u64; + let mut next = || { + x = x.wrapping_mul(6_364_136_223_846_793_005).wrapping_add(1_442_695_040_888_963_407); + (x >> 11) as f64 / (1u64 << 53) as f64 + }; + let points: Vec<(Coord, f64)> = (0..3000) + .map(|i| { + let (cx, cy) = if i % 3 == 0 { (2_000.0, 3_000.0) } else { (0.0, 0.0) }; + (Coord::new(cx + next() * 5_000.0, cy + next() * 4_000.0), 0.5 + next() * 3.0) + }) + .collect(); + for kernel in [KernelType::Quartic, KernelType::Gaussian] { + let make = |threads| kernel_density_on(Some(threads), &points, None, 20.0, 300.0, kernel, "d", Crs::WebMercator).unwrap(); + let (one, many) = (make(1), make(4)); + assert!(one.height > 100, "{}", one.height); + let bits = |r: &Raster| r.bands[0].data.iter().map(|v| v.to_bits()).collect::>(); + assert_eq!(bits(&one), bits(&many), "{kernel:?}"); + } + } + + /// Progress counts every strip's points to the end, also when the rows don't cut into as many + /// strips as asked for (101 rows on 16 threads make 51 strips of 2, not 64). + #[test] + fn kernel_density_progress_ends_at_its_total() { + let points: Vec<(Coord, f64)> = (0..5000).map(|i| (Coord::new(f64::from(i % 100) * 10.0, f64::from(i / 50) * 10.0), 1.0)).collect(); + let ext = Extent::new(0.0, 0.0, 1000.0, 1010.0); + let run = crate::control::Control::new(); + let _installed = crate::control::install(Some(run.clone())); + let r = kernel_density_on(Some(16), &points, Some(&ext), 10.0, 30.0, KernelType::Quartic, "p", Crs::WebMercator).unwrap(); + assert_eq!(r.height, 101); + let (done, total) = run.progress().unwrap(); + assert_eq!((done, total), (total, 51 * 5001)); + } } diff --git a/crates/analysis/src/rasterops.rs b/crates/analysis/src/rasterops.rs index 4bc78de16b..6a8a41379e 100644 --- a/crates/analysis/src/rasterops.rs +++ b/crates/analysis/src/rasterops.rs @@ -568,6 +568,13 @@ fn idw_on( /// Unsupervised k-means classes (1..=k) of the pixels over the given bands. pub fn kmeans(r: &Raster, bands: &[usize], k: usize, iterations: usize) -> Result, String> { + kmeans_on(None, r, bands, k, iterations) +} + +/// [`kmeans`] on `threads` threads (none: as many as pay off). The centres are found on a sample +/// of the pixels; then each pixel takes its nearest, on its own, so rows go on several threads +/// (#1252). +fn kmeans_on(threads: Option, r: &Raster, bands: &[usize], k: usize, iterations: usize) -> Result, String> { let k = k.clamp(2, 50); let data: Vec<&[f32]> = bands.iter().map(|b| band(r, *b)).collect::>()?; if data.is_empty() { @@ -632,11 +639,28 @@ pub fn kmeans(r: &Raster, bands: &[usize], k: usize, iterations: usize) -> Resul centres.get(*a).and_then(|c| c.first()).partial_cmp(¢res.get(*b).and_then(|c| c.first())).unwrap_or(std::cmp::Ordering::Equal) }); let rank: Vec = (0..centres.len()).map(|c| order.iter().position(|o| *o == c).unwrap_or(0)).collect(); - let mut p = Vec::with_capacity(data.len()); - let mut out = grid(r.width as usize, r.height as usize)?; - out.extend( - (0..n).map(|i| if pixel_into(i, &mut p) { (rank.get(nearest(&p, ¢res)).copied().unwrap_or(0) + 1) as f32 } else { NODATA }), - ); + let (w, h) = (r.width as usize, r.height as usize); + let mut out = new_band(w, h, NODATA)?; + if w == 0 { + return Ok(out); + } + // A pixel's distance to every centre over every band, a few nanoseconds per pair: in + // `MIN_ROW_WORK`'s units (some 30 ns), about one per eight pairs. + let work = n.saturating_mul(centres.len().saturating_mul(data.len()) / 8 + 1); + let threads = threads.unwrap_or_else(|| crate::parallel::threads_for_rows(h, work, 0)); + crate::control::begin(h); + crate::parallel::for_each_row( + out.chunks_mut(w), + threads, + || Vec::with_capacity(data.len()), + |p, row, line: &mut [f32]| { + for (col, o) in line.iter_mut().enumerate() { + if pixel_into(row * w + col, p) { + *o = (rank.get(nearest(p, ¢res)).copied().unwrap_or(0) + 1) as f32; + } + } + }, + )?; Ok(out) } @@ -1263,6 +1287,22 @@ mod tests { } } + /// k-means classes made on several threads are those made on one (#1252), no-data pixels + /// included. + #[test] + fn kmeans_on_several_threads_is_kmeans_on_one() { + let (w, h) = (240u32, 180u32); + let n = (w * h) as usize; + let band = |k: usize| (0..n).map(|i| if i % 97 == 0 { -9999.0 } else { ((i * (5 + k) + i / 240 * 11) % 200) as f32 }).collect(); + let gt = GeoTransform { origin_x: 0.0, origin_y: 180.0, pixel_width: 1.0, pixel_height: -1.0 }; + let r = + Raster::new("k", w, h, vec![band(0), band(1), band(2)], gt, Crs::LonLat, Some(-9999.0), ColorHint::Gray, "Float32").unwrap(); + let bits = |v: Vec| v.into_iter().map(f32::to_bits).collect::>(); + let one = bits(kmeans_on(Some(1), &r, &[0, 1, 2], 7, 10).unwrap()); + assert_eq!(one, bits(kmeans_on(Some(4), &r, &[0, 1, 2], 7, 10).unwrap())); + assert!(one.contains(&NODATA.to_bits()) && one.contains(&7.0f32.to_bits())); + } + /// Band math and per-cell rows made on several threads give the same cells, bit for bit, as /// one thread (#1252): no-data, NaN and values that come out non-finite included. #[test] diff --git a/docs/user-guide/analysis.md b/docs/user-guide/analysis.md index b8320385f0..f856a7d9a0 100644 --- a/docs/user-guide/analysis.md +++ b/docs/user-guide/analysis.md @@ -71,10 +71,12 @@ tables or a file is still made). Opening another project drops the run. Scripts, Assistant, the command line and the web app wait for each tool to finish. **Viewshed**, **IDW Interpolation** and **Kriging** refuse a run that would take more than a second -or two of work on one thread (a ray step, a cell-point pair). On the desktop they run on several +or two of work on one thread (a ray step, a cell-point pair), and **Kernel Density** one that +reaches more than 50 million cells with the points' kernels. On the desktop they run on several cores (up to 16), and they take as many times more work as the threads they run on. Threads share cores and memory, so a run at that limit can take up to about twice as long as a one-thread run at -its own; in the web app, on one thread, the limits stay as they are. The error names the +its own (measured on one machine, a Xeon Silver 4114; it can be longer on others); in the web app, +on one thread, the limits stay as they are. The error names the limit on this computer and the threads it counted. A tool's own default cell size still follows the one-thread limit, so it makes the same grid on any computer; a finer cell size given is what the larger limit lets through. From 94417a2aa9c93f0bc5f4073b7c9a56cd5975c5f6 Mon Sep 17 00:00:00 2001 From: Dominik Strebel Date: Tue, 3 Nov 2026 16:07:04 +0100 Subject: [PATCH 2/2] test(analysis): a cancelled k-means or Kernel Density gives no result; review notes The guide says what Kernel Density's limit counts (each point's search window), and the progress comment names the count for_each_row adds. --- crates/analysis/src/density.rs | 15 ++++++++++++++- crates/analysis/src/rasterops.rs | 5 +++++ docs/user-guide/analysis.md | 4 ++-- 3 files changed, 21 insertions(+), 3 deletions(-) diff --git a/crates/analysis/src/density.rs b/crates/analysis/src/density.rs index bbac3e6303..298fcdddde 100644 --- a/crates/analysis/src/density.rs +++ b/crates/analysis/src/density.rs @@ -185,7 +185,7 @@ where let strip_rows = h_rows.div_ceil(strips.max(1)).max(1); // The strips the rows make (fewer than asked for when they don't divide evenly). let strips = h_rows.div_ceil(strip_rows); - // Each strip counts its points as it goes, and once more when done. + // Each strip counts its points as it goes; `for_each_row` counts the strip itself once more. crate::control::begin(strips.saturating_mul(points.len().saturating_add(1))); crate::parallel::for_each_row( grid.chunks_mut(w * strip_rows), @@ -655,4 +655,17 @@ mod tests { let (done, total) = run.progress().unwrap(); assert_eq!((done, total), (total, 51 * 5001)); } + + /// A cancelled run comes back as cancelled, on one thread and on several, not as a grid. + #[test] + fn a_cancelled_kernel_density_is_no_grid() { + let points: Vec<(Coord, f64)> = (0..200).map(|i| (Coord::new(f64::from(i) * 5.0, f64::from(i % 20) * 5.0), 1.0)).collect(); + for threads in [1, 4] { + let run = crate::control::Control::new(); + run.cancel(); + let _installed = crate::control::install(Some(run)); + let e = kernel_density_on(Some(threads), &points, None, 5.0, 50.0, KernelType::Quartic, "c", Crs::WebMercator).unwrap_err(); + assert_eq!(e, crate::control::CANCELLED, "{threads}"); + } + } } diff --git a/crates/analysis/src/rasterops.rs b/crates/analysis/src/rasterops.rs index 6a8a41379e..1937c5fecc 100644 --- a/crates/analysis/src/rasterops.rs +++ b/crates/analysis/src/rasterops.rs @@ -1301,6 +1301,11 @@ mod tests { let one = bits(kmeans_on(Some(1), &r, &[0, 1, 2], 7, 10).unwrap()); assert_eq!(one, bits(kmeans_on(Some(4), &r, &[0, 1, 2], 7, 10).unwrap())); assert!(one.contains(&NODATA.to_bits()) && one.contains(&7.0f32.to_bits())); + // A cancelled run gives no classes. + let run = crate::control::Control::new(); + run.cancel(); + let _installed = crate::control::install(Some(run)); + assert_eq!(kmeans_on(Some(4), &r, &[0, 1, 2], 7, 10).unwrap_err(), crate::control::CANCELLED); } /// Band math and per-cell rows made on several threads give the same cells, bit for bit, as diff --git a/docs/user-guide/analysis.md b/docs/user-guide/analysis.md index f856a7d9a0..80049b20d9 100644 --- a/docs/user-guide/analysis.md +++ b/docs/user-guide/analysis.md @@ -71,8 +71,8 @@ tables or a file is still made). Opening another project drops the run. Scripts, Assistant, the command line and the web app wait for each tool to finish. **Viewshed**, **IDW Interpolation** and **Kriging** refuse a run that would take more than a second -or two of work on one thread (a ray step, a cell-point pair), and **Kernel Density** one that -reaches more than 50 million cells with the points' kernels. On the desktop they run on several +or two of work on one thread (a ray step, a cell-point pair), and **Kernel Density** one whose +points' search windows (the square around each point's radius) cover more than 50 million cells. On the desktop they run on several cores (up to 16), and they take as many times more work as the threads they run on. Threads share cores and memory, so a run at that limit can take up to about twice as long as a one-thread run at its own (measured on one machine, a Xeon Silver 4114; it can be longer on others); in the web app,