1  What planning buys: points

Start with what already works, because it shows what is at stake.

A lazy array is cheap to hold and expensive to ask. Every question becomes chunks to fetch, and for a remote store the cost is round trips. If R hands over a whole question, the array can work out the distinct chunks it needs and fetch them together. If R asks piece by piece, the array answers piece by piece.

For points, R hands over the whole question. A matrix subscript, x[cbind(i, j, k)], is turned into linear positions and passed to the ALTREP Extract_subset method in one call.

1.1 The example

A synthetic array laid out like the Copernicus global waves store (chunks of 4 x 8 cells, long in time), where each fetch call takes 50 ms. Three hundred scattered points, read two ways.

# 01-points.R -- values at 300 scattered (x, y, t) points. ASCII only.
#
# A synthetic array with the layout of the CMEMS global waves Zarr (chunks
# of 4 lon x 8 lat x many time steps), shortened in time. The same job two
# ways: one x[cbind(i, j, k)], and a loop of x[i, j, k].
here <- function() {
  f <- sub("^--file=", "", grep("^--file=", commandArgs(FALSE), value = TRUE))
  if (length(f)) dirname(f[1]) else "scripts"
}
source(file.path(here(), "_bench.R"))

x <- synthetic(c(1800, 851, 4000), c(4, 8, 1000))

set.seed(1)
n <- 300
idx <- cbind(sample(1201:1700, n, replace = TRUE),   # 60E to 160E
             sample(76:176, n, replace = TRUE),      # 65S to 45S
             sample(4000, n, replace = TRUE))

a <- bench("300 points: one x[cbind(i, j, k)]", x, x[idx])
b <- bench("300 points: a loop of x[i, j, k]", x,
           vapply(seq_len(n), function(p) x[idx[p, 1], idx[p, 2], idx[p, 3]],
                  numeric(1)))
stopifnot(identical(a, b))
stopifnot(a[1] == (idx[1, 1] - 1) + (idx[1, 2] - 1) * 1800 +
            (idx[1, 3] - 1) * 1800 * 851)
finish()
2026-11-22 04:34 UTC on a5af98a4c685; R-devel patched r90638, stock r90638
Read Values Chunks Fetch calls, stock Fetch calls, patched Seconds, stock Seconds, patched Faster by Same values
300 points: one x[cbind(i, j, k)] 300 287 1 1 0.23 0.23 1.0x yes
300 points: a loop of x[i, j, k] 300 287 287 287 14.59 14.61 1.0x yes

The two reads touch the same chunks. The matrix subscript is one batch; the loop is one fetch call per chunk it had not seen yet. And the two builds of R agree: nothing in this chapter needs the patch.

1.2 On a real store

The same shape of read against the live Copernicus waves Zarr (1800 x 899 x 136,360 values of significant wave height, 3-hourly since 1980), run from a workstation on 2026-11-13 with examples/xyt-points: 300 points in the Southern Ocean were one fetch call for 268 chunks in 23 seconds at 8 connections, 15 seconds at 16 and 11 at 32. Done point by point it is 268 round trips in series.

A layer-oriented reader can reach the same byte count, by grouping points by chunk, reading each group as a slab and picking out each point’s layer. That is the planner written by hand. Here it is what x[idx] does.

1.3 So what is missing

Points are the case R already gets right. The rest of the book is about the reads next to it: a time series at a station, x[i, j, ]; a map, x[, , t]; a box, x[i0:i1, j0:j1, t0:t1]. Those are the everyday array reads, and they are the ones R takes apart.