Fold multi-GPU CAGRA build into train(), delete trainMultiGpu

Summary:
TLDR: `GpuIndexCagra` had two multi-GPU build entry points totalling 16 positional
arguments, neither of which fits the `Index` API. This removes one and folds the
other into `train()`.

**Usage.** Listing more than one device in the config selects the multi-GPU
build; `train()` routes to it:

```python
devices = faiss.Int32Vector()
for i in range(8):
    devices.push_back(i)

an = faiss.AllNeighborsCagraConfig()
an.n_clusters = 16                  # 0 = auto: max(2 * n_devices, 4)
an.overlap_factor = 2
an.multi_gpu_optimize = True        # shard graph pruning across devices
an.ivf_pq_search_batch_size = 8192  # 0 = cuVS default; caps IVF-PQ workspace

config = faiss.GpuIndexCagraConfig()
config.graph_degree = 32
config.intermediate_graph_degree = 32
config.build_algo = faiss.graph_build_algo_IVF_PQ
config.refine_rate = 2.0
config.devices = devices            # >1 device selects the multi-GPU build
config.all_neighbors_params = an

index = faiss.GpuIndexCagra(res, d, faiss.METRIC_L2, config)
index.train(xb)          # xb must stay alive until copyTo() completes

cpu_index = faiss.IndexHNSWCagra()
cpu_index.base_level_only = True
index.copyTo(cpu_index)  # required: the GPU index is not searchable on this path
# Then we can serialize:
faiss.write_index(cpu_index, "out.faiss")
```

That path is Float32-only, does not copy `x`, and leaves `index_` empty, so
`copyTo()` is the only valid follow-up. Single-GPU behaviour is unchanged when
`devices` is empty.

**Deleted `trainMultiGpu`.** Sharded SNMG CAGRA produces per-shard graphs with
zero cross-shard edges by construction, so it needs post-hoc stitching (GPU
brute-force or CPU HNSW) just to be usable, and it lost to the `all_neighbors`
path on both build time and recall. It had no callers outside the benchmark and
one test.

**Folded `trainAllNeighbors` into `train()`.** It was a 9-argument method whose
6 trailing bare scalars now live in the constructor-time config struct, which is
the established Faiss GPU convention:

| Old argument | Now |
| --- | --- |
| `devices` | `GpuIndexCagraConfig::devices`, also the dispatch predicate |
| `build_algo` (0/1/2) | `GpuIndexCagraConfig::build_algo` |
| `refinement_rate` | `GpuIndexCagraConfig::refine_rate` |
| `n_clusters`, `overlap_factor`, `multi_gpu_optimize`, `ivfpq_search_batch` | new `AllNeighborsCagraConfig` |

This also kills a live footgun: `trainAllNeighbors` took an `int build_algo`
whose encoding (0=NN-descent, 1=brute-force, 2=IVF-PQ) disagreed with the
`graph_build_algo` enum in the same header (0=IVF_PQ, 1=NN_DESCENT). Both callers
set `config.build_algo` and then passed an unrelated int, and the config field
was silently dead on that path. `BRUTE_FORCE` is appended to `graph_build_algo`
(at the end, so existing values do not renumber) and the config field is now the
single source of truth.

**Collapsed the benchmark to one path.** With the stitching approaches gone,
`bench_approaches.py` kept an `IndexShards` baseline purely for comparison. The
architecture decision is settled, so the benchmark is now a single-path tool for
validating and tuning the production build: no `--approaches` flag, no
per-approach labelling, no `IndexShards` handling in the eval helpers.

Deliberately *not* merged into the config:

- `ivf_pq_params` / `ivf_pq_search_params` are still not consulted on this path.
  cuVS derives `n_lists`, `pq_dim` and the kmeans trainset fraction from the
  dataset shape (`n_lists = n/2000`, i.e. 50000 at 100M vectors, versus the
  static default of 1024). Applying `IVFPQ*CagraConfig` wholesale would discard
  that tuning. The IVF-PQ search batch cap therefore keeps its own field, with 0
  meaning "leave cuVS's dataset-derived default".
- `faiss::cagra_build_algo` only has `{IVF_PQ, NN_DESCENT}`, so a `BRUTE_FORCE`
  config would silently degrade to NN-descent on the single-GPU path;
  `train_ex()` now rejects it there. `GpuIndexBinaryCagra` shares this config
  struct and has no multi-GPU build, so it rejects `devices.size() > 1` rather
  than silently building on one device.

Behaviour change: the default `build_algo` on the multi-GPU path is now `IVF_PQ`
(the config default) rather than NN-descent (the old argument default). That
matches the single-GPU path and the recommended large-scale config.

Differential Revision: D114685755

Author: Michael Norris

faiss/gpu/GpuIndexBinaryCagra.cu

@@ -78,6 +78,14 @@ std::shared_ptr<GpuResources> GpuIndexBinaryCagra::getResources() {
 }
 
 void GpuIndexBinaryCagra::train(idx_t n, const uint8_t* x) {
+    // GpuIndexCagraConfig is shared with the float index, whose multi-GPU
+    // build path has no binary equivalent. Reject rather than silently
+    // building on one device.
+    FAISS_THROW_IF_MSG(
+            cagraConfig_.devices.size() > 1,
+            "binary CAGRA has no multi-GPU build; "
+            "GpuIndexCagraConfig::devices must name at most one device");
+
     DeviceScope scope(cagraConfig_.device);
     if (this->is_trained) {
         FAISS_ASSERT(index_);