docs: 📝 large problems, Resources and the out-of-core test knobs

Assisted-by: Pi:claude-opus-5-5

Author: robertodr

README.md

@@ -87,6 +87,26 @@ The result then pairs with a ket by plain contraction, with no further conjugati
 
 At runtime, pass `device="gpu"` to use GPU acceleration. The library handles backend dispatch automatically.
 
+### Large Problems
+
+Stacks that do not fit on the GPU, or in host memory, still run: the sweep reads the input cores one site at a time (from NumPy arrays, `np.memmap`, zarr or HDF5 datasets), batches every contraction to a memory budget, and keeps the sketched environments on the GPU, in host memory or on local disk. The budgets are detected, or set explicitly with `Resources`:
+
+```python
+from src_method import Resources, src
+
+out = src(
+    N,
+    V,
+    M,
+    U,
+    chi_out=2000,
+    device="gpu",
+    resources=Resources(gpu_memory="36GB", scratch_dir="/local/scratch"),
+)
+```
+
+See [Large problems](docs/large-problems.md) for the budgets, the scratch directory and how to read the logged plan.
+
 ## Installation
 
 ```bash

docs/developer-guide/testing.md

@@ -253,6 +253,19 @@ def test_helper_namespace():
     assert pytest.helpers.foo(True) is True
 ```
 
+### Exercising the out-of-core paths
+
+The batched contractions and the host and disk tiers of the sweep only engage when
+the budgets are tight, so tests force them with tiny budgets: on the CPU,
+`Resources(host_memory="1MB", scratch_dir=tmp_path)` gives small batches and spills
+the environments of a depth-4 stack with bonds of 4 to `tmp_path` (see
+`tests/test_stack.py`). Compare the dense operator of the result with that of a
+default run, not the cores: batching changes the rounding, and with it the cores of
+an ill-conditioned sketch, but not the operator they represent. The planner is a
+pure function, so `tests/test_plan.py` checks batch sizes and tiers from shapes
+alone, and `tests/test_gpu_backend.py` derives GPU budgets from a plan made with
+`make_plan` to reach every tier.
+
 ### How to use logging with tests
 
 Within `aurora`, we adopt a `pytest` configuration that allows to see the output

docs/large-problems.md

@@ -0,0 +1,83 @@
+# Large problems
+
+A single SRC sweep keeps, besides the input and output trains, one sketched
+environment per site. For stacks with a large bond, such as `N . V . M . U` with a
+bond of several thousand in `M`, these environments and the intermediates of the
+contractions no longer fit on a GPU, and often not in host memory either.
+`src_method` then plans the sweep to the memory at hand:
+
+- the input cores are read one site at a time, so a train can live on disk;
+- every contraction runs in batches of sketch columns (or rows), sized to the GPU
+  budget;
+- each environment is kept on the GPU, in host memory or in a scratch directory,
+  the most recent ones on the fastest tier.
+
+None of this changes the result beyond floating-point rounding: the random draws
+and the mathematics are those of a sweep that fits in memory.
+
+## Budgets
+
+The budgets are set with `Resources`, passed to `src`, `apply` or `compress`:
+
+```python
+from src_method import Resources, src
+
+out = src(
+    N, V, M, U,
+    chi_out=2000,
+    dtype=np.complex128,
+    device="gpu",
+    resources=Resources(gpu_memory="36GB", scratch_dir="/local/scratch"),
+)
+```
+
+Every field left unset is detected when the call starts:
+
+| Field | Default |
+|---|---|
+| `gpu_memory` | free device memory, plus the free bytes of CuPy's pool, minus `max(10%, 1 GiB)` |
+| `host_memory` | `MemAvailable` from `/proc/meminfo`, minus 10% |
+| `scratch_dir` | `tempfile.gettempdir()`, which honours `$TMPDIR` |
+
+Sizes are byte counts or strings: `"36GB"` is `36 * 10**9` bytes, `"36GiB"` is
+`36 * 2**30`. On the CPU there is a single budget, `host_memory`. Host memory is
+measured when the call starts, so inputs already held in memory are not counted
+twice.
+
+During the sweep, CuPy's default memory pool is capped at the GPU budget, so that
+an estimate that falls short fails at once rather than when some other allocation
+does; the previous limit is restored afterwards. If a single site does not fit the
+budget even with batches of one column, `src` raises `MemoryError` naming the site.
+
+## Inputs on disk
+
+A train is any sequence of per-site array-likes with `shape`, `dtype` and
+`np.asarray` support: NumPy arrays, `np.memmap`, zarr or HDF5 datasets. Each core
+is read when the sweep reaches its site, once per pass, and a background thread
+reads the next site while the current one is computed. Raw `.npy` files opened with
+`np.load(path, mmap_mode="r")` are the fastest option; compressed formats may be
+limited by decompression.
+
+## The scratch directory
+
+Environments that fit in neither budget are written to a per-process directory,
+`<scratch_dir>/src-<pid>-<id>/`, one file per site. Use node-local disk: at the
+reference size of 50 sites, `D_M = 4000` and `chi_out = 2000` in complex128, up to
+410 GB are written and read back once. The directory is removed when the call
+returns, also after an error; a process killed with `SIGKILL` leaves it behind, and
+its name identifies the process.
+
+## Reading the plan
+
+Every sweep logs its plan at `info`:
+
+- `tiers`: where the environment of each site lives (`device`, `host` or `disk`);
+- `batches`: for each site, the batch of the environment, sketch and projection
+  steps;
+- `device_peak_bytes`, `host_peak_bytes`, `disk_bytes`: the planned peaks;
+- `prefetch`: whether the next site is read ahead.
+
+At the end, `SRC stalls` reports the seconds the sweep waited for input cores
+(`site_seconds`) and for environments (`environment_seconds`). If they are a large
+fraction of the run, the disk is too slow for the compute. Set
+`LOG_LEVEL_SRC=DEBUG` to also get the time of each pass.

mkdocs.yml

@@ -5,6 +5,7 @@ watch:
   - src/src_method
 nav:
   - Home: index.md
+  - 'Large Problems': large-problems.md
   - 'Developer Guide':
     - 'Versioning Scheme': developer-guide/versioning.md
     - 'Managing Dependencies': developer-guide/dependencies.md