# Refinement

> USearch for Zig

`refine` re-selects the neighbors of every stored entry against the finished graph and returns a `DenseRefineReport`: the entries re-selected and changed, the islands found and reconnected, and the closing audit.
A cheap insertion pass followed by one refinement reaches a better graph in less total time than one expensive insertion pass.
Zero `changed` means the graph has settled, and on a RAM index searches may run throughout.

```zig
while ((try index.on(executor).refine(.{ .expansion_factor = 128 })).changed != 0) {}
```

### Absorbing

`absorb` moves donor handles into one index, one after another, keeping their graphs rather than re-inserting their vectors, then refines every shard that took one across the appended part.
A donor must share the index's residency, scalar, metric and geometry, or the call answers `Error.ConfigMismatch`.
Each donor it absorbs is consumed and nulled in place, so freeing every donor afterwards is safe, and a stop between donors, or a failure, leaves the rest live for their `deinit` to free.

```zig
var donors = [_]usearch.DenseIndex{ first, second };
_ = try index.on(executor).absorb(&donors, .{});
for (&donors) |*donor| donor.deinit(); // frees only the donors a stop or a failure left live
```

`split` is the inverse: it hands graph-local parts of the index to empty receivers of the same configuration, one part each, keeping their edges and leaving the index empty but live.
It reports the receivers' closing refines as `refine` does.

```zig
const report = try index.on(executor).split(&receivers, .{ .seed = 42 });
```

`const usearch = @import("usearch");`

## DenseRefineReport

What one [`refine`](https://www.unum.cloud/docs/usearch/zig/metrics.md#refine), [`absorb`](https://www.unum.cloud/docs/usearch/zig/metrics.md#absorb) or [`split`](https://www.unum.cloud/docs/usearch/zig/metrics.md#split) did to the graph.

```zig
pub const DenseRefineReport = extern struct
```

Mirrors `usearch_refine_report_t`.

- `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.
- `islands_found` `usize`: Entries the first audit found not reached both ways.
- `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 [`health`](https://www.unum.cloud/docs/usearch/zig/metrics.md#health) right after would take it.

## DenseRefineConfig

Optional settings of [`DenseIndex.refine`](https://www.unum.cloud/docs/usearch/zig/metrics.md#refine).

```zig
pub const DenseRefineConfig = struct
```

- `expansion_factor` `usize`: The breadth of the candidates the re-selection walk explores; zero derives.
- `progress` `ProgressCallback`: Called with nodes swept; a stop is a time budget rather than a failure.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `?*DenseTraversalStats`

## DenseAbsorbConfig

Optional settings of [`DenseIndex.absorb`](https://www.unum.cloud/docs/usearch/zig/metrics.md#absorb).

```zig
pub const DenseAbsorbConfig = struct
```

- `progress` `ProgressCallback`: Called with donors absorbed; a stop between donors keeps those already absorbed.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.

## DenseSplitConfig

Optional settings of [`DenseIndex.split`](https://www.unum.cloud/docs/usearch/zig/metrics.md#split).

```zig
pub const DenseSplitConfig = struct
```

- `seed` `u64`: Picks the part roots: equal seeds over an unchanged index split equally.
- `expansion_factor` `usize`: The breadth of the candidates of the closing refines' walks; zero derives.
- `progress` `ProgressCallback`: Called with nodes the closing refines re-selected; a stop never undoes a move.
- `progress_steps` `usize`: Reports the call makes at most, the last at completion; zero derives to ten.
- `stats` `?*DenseTraversalStats`

## DenseRefine

One [`DenseIndex.refine`](https://www.unum.cloud/docs/usearch/zig/metrics.md#refine), as a [`Deferred`](https://www.unum.cloud/docs/usearch/zig/executors.md#Deferred) holds it.

```zig
pub const DenseRefine = struct
```

- `config` `DenseRefineConfig`
- `report` `DenseRefineReport`
- `outcome` `Outcome`

## DenseAbsorb

One [`DenseIndex.absorb`](https://www.unum.cloud/docs/usearch/zig/metrics.md#absorb), as a [`Deferred`](https://www.unum.cloud/docs/usearch/zig/executors.md#Deferred) holds it.

```zig
pub const DenseAbsorb = struct
```

- `donors` `[]DenseIndex`
- `config` `DenseAbsorbConfig`
- `report` `DenseRefineReport`
- `outcome` `Outcome`

## DenseSplit

One [`DenseIndex.split`](https://www.unum.cloud/docs/usearch/zig/metrics.md#split), as a [`Deferred`](https://www.unum.cloud/docs/usearch/zig/executors.md#Deferred) holds it.

```zig
pub const DenseSplit = struct
```

- `receivers` `[]const DenseIndex`
- `config` `DenseSplitConfig`
- `report` `DenseRefineReport`
- `outcome` `Outcome`