# Refinement

> USearch for Rust

`refine` re-runs the neighbor selection over entries already in the graph and returns a `RefineReport` of the nodes re-selected, those whose neighbors `changed`, the islands found and reconnected, and the `reachability` audit closing the heal, so a batch built at a low expansion factor reaches the quality of a slower build afterwards.
`changed` reaching zero is what settled looks like.
On a RAM handle searches may run throughout, on a VRAM one they may not, and insertions never may.

```rust
let receiver = index.on(&executor);
while receiver.refine(DenseRefineConfig { expansion_factor: 128, ..DenseRefineConfig::default() })?.changed != 0 {}
```

### Absorbing & Splitting

`absorb` takes donor indexes, handed over by value, one after another, keeping their graphs rather than re-inserting their entries and linking each in by walks across the appended part.
Readers of a RAM index may keep searching throughout, while a VRAM one admits no overlapping search.

```rust
index.on(&executor).absorb([first_shard, second_shard])?;
index.on(&executor).split(&[&left, &right][..])?; // two empty receivers take a part each
```

A stopped `absorb` cuts only its closing refinement, every donor already moved, and reports `Status::Cancelled`.
`split` is its inverse, leaving the source empty and live; both answer a `RefineReport`.

`use usearch::DenseAbsorbConfig;`

`use usearch::DenseRefineConfig;`

`use usearch::DenseSplitConfig;`

`use usearch::RefineReport;`

## DenseAbsorbConfig

The donors an absorb consumes and the handler counting them; see [`DenseVerbs::absorb`](https://www.unum.cloud/docs/usearch/rust/metrics.md#absorb).

```rust
pub struct DenseAbsorbConfig<'config, Donors>
```

- `donors` `Donors`: The indexes absorbed, consumed whether or not the absorb succeeds.
- `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the nodes the closing refinement re-selected and stops it wherever it says to.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.

Implements: `From<Donors>`

## DenseRefineConfig

The knobs of [`DenseVerbs::refine`](https://www.unum.cloud/docs/usearch/rust/metrics.md#refine).

```rust
pub struct DenseRefineConfig<'config>
```

- `expansion_factor` `usize`: The breadth of the candidates the walk explores; zero derives it from the geometry.
- `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the nodes swept and stops wherever it says to.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `Option<&'config mut DenseTraversalStats>`: Where the traversal telemetry lands, overwritten by the call.

Implements: `Default`

## DenseSplitConfig

The receivers a split fills and the knobs of its closing refinements; see [`DenseVerbs::split`](https://www.unum.cloud/docs/usearch/rust/metrics.md#split).

```rust
pub struct DenseSplitConfig<'config>
```

- `receivers` `&'config [&'config DenseIndex]`: At least two empty indexes of the source's residency, scalar, class, metric, geometry and
shard count, each receiving one part.
- `expansion_factor` `usize`: The breadth of the closing refinements' walks; zero derives it from the geometry.
- `seed` `u64`: Picks the part roots: equal seeds over an unchanged index split equally.
- `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the nodes the closing refinements re-selected and stops them wherever it says to.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `Option<&'config mut DenseTraversalStats>`: Where the traversal telemetry lands, overwritten by the call.

Implements: `From<&'config [&'config [DenseIndex](https://www.unum.cloud/docs/usearch/rust/metrics.md#DenseIndex)]>`

## RefineReport

What one refine-family call did to the graph: [`DenseVerbs::refine`](https://www.unum.cloud/docs/usearch/rust/metrics.md#refine), [`DenseVerbs::absorb`](https://www.unum.cloud/docs/usearch/rust/metrics.md#absorb) and [`DenseVerbs::split`](https://www.unum.cloud/docs/usearch/rust/metrics.md#split) land it.

```rust
pub struct RefineReport
```

- `reselected` `usize`: Entries whose neighbors were selected again, the islands of every heal round included.
- `changed` `usize`: Of those, the entries whose neighbor set gained a member it lacked; never above
`reselected`.
- `islands_found` `usize`: Entries the first audit found not reached both ways, counted once.
- `islands_reconnected` `usize`: Links written between an island and an entry the audit reached both ways.
- `reachability` `DenseReachability`: The audit closing the heal, as a fresh [`DenseVerbs::health`](https://www.unum.cloud/docs/usearch/rust/metrics.md#health) right after would take it.

Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`