Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
210 changes: 160 additions & 50 deletions crates/analysis/src/density.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -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<F>(
threads: usize,
points: &[(Coord, f64)],
grid: &mut [f64],
w: usize,
Expand All @@ -164,52 +177,76 @@ fn accumulate_density<F>(
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)) };

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Performance / possible bug (medium confidence, from reading the code, not measured). The work cap scales with threads on the assumption that the threads share the cell visits evenly. Here the strips are equal in rows, but the visits are not: a point's visits fall only in the strips its kernel reaches. Points clustered in one or two strips leave the other threads idle. The run then takes roughly as long as the whole scaled cap on one thread, up to about 16 times the one-thread budget. The new docs paragraph ("can take up to about twice as long as a one-thread run at its own") does not hold for this case.

Example: the PR's own 200,000-point run (540 million visits, 0.37 s on all cores) would take about 2.7 s at roughly 5 ns per visit if its points were clustered in a few strips.

Suggestion: split the strips by estimated work, not rows. Count each row's visits with a difference array over the points' row ranges (O(points + rows)), then cut the strips at equal cumulative counts. Alternatively, size the cap from the largest strip's share. Either way, add a test with clustered points that checks the speed-up or the cap.

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; `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),
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() {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Performance (low confidence). Every strip scans all points, and computes each point's column and row bounds again, so the scan costs about strips × points steps. total_work leaves that scan out. A run with many points and small kernels (for example 1 million points, each reaching about 36 cells) can spend more time in the scan than in the cell visits, and that can cancel the gain from threads. Computing each point's bounds once (a Vec of four usize per point, or a per-strip list of the points that reach it) would remove the repeated work. Worth a benchmark on that shape before merging.

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.
Expand All @@ -221,6 +258,20 @@ pub fn kernel_density(
kernel: KernelType,
name: &str,
crs: Crs,
) -> Result<Raster, String> {
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<usize>,
points: &[(Coord, f64)],
custom_extent: Option<&Extent>,
cell_size: f64,
bandwidth: f64,
kernel: KernelType,
name: &str,
crs: Crs,
) -> Result<Raster, String> {
if points.is_empty() {
return Err("kernel density requires at least one point".into());
Expand Down Expand Up @@ -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);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
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()
));
}
Expand All @@ -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.
Expand All @@ -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()
});
})?;
}
}

Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -558,4 +616,56 @@ 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::<Vec<_>>();
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));
}

/// 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}");
}
}
}
55 changes: 50 additions & 5 deletions crates/analysis/src/rasterops.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<Vec<f32>, 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<usize>, r: &Raster, bands: &[usize], k: usize, iterations: usize) -> Result<Vec<f32>, String> {
let k = k.clamp(2, 50);
let data: Vec<&[f32]> = bands.iter().map(|b| band(r, *b)).collect::<Result<_, _>>()?;
if data.is_empty() {
Expand Down Expand Up @@ -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(&centres.get(*b).and_then(|c| c.first())).unwrap_or(std::cmp::Ordering::Equal)
});
let rank: Vec<usize> = (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, &centres)).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, &centres)).copied().unwrap_or(0) + 1) as f32;
}
}
},
)?;
Ok(out)
}

Expand Down Expand Up @@ -1263,6 +1287,27 @@ 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<f32>| v.into_iter().map(f32::to_bits).collect::<Vec<_>>();
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
/// one thread (#1252): no-data, NaN and values that come out non-finite included.
#[test]
Expand Down
6 changes: 4 additions & 2 deletions docs/user-guide/analysis.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 whose
points' search windows (the square around each point's radius) cover more than 50 million cells. On the desktop they run on several

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit (docs wording, and this line is much longer than its neighbours): the limit is on the sum over all points of each point's search window, so overlapping windows count once per point. "whose points' search windows cover more than 50 million cells" reads as the union of the windows. Something like "whose search windows, counted for each point, come to more than 50 million cells" would match the code. Also rewrap this paragraph at the same width as the rest.

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.
Expand Down
Loading