# Refinement

> USearch for Mojo

`refine` re-runs the neighbor selection over entries already in the graph, returning a `DenseRefineReport`: the entries re-selected and changed, the islands found and reconnected, and the closing audit.
A batch built at a low expansion factor reaches the quality of a slower build afterwards, and `changed` reaching zero is what settled looks like:

```mojo
while index.on(executor).refine(DenseRefineConfig(expansion_factor=128)).changed != 0:
    pass
```

### Absorbing & Splitting

Bigger indexes come from absorbing, never mutating: `absorb` takes its donors by value, appends each one's entries with its graph, then refines across the appended part, and the engine frees each donor it absorbs.
`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.
Both report the closing refines as `refine` does.

```mojo
var donors = List[DenseIndex]()
donors.append(shard^)
_ = index.on(executor).absorb(donors^)
_ = index.on(executor).split(receivers, seed=42)
```

`from usearch import DenseRefineReport, DenseRefineConfig`

## DenseRefineReport

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

```mojo
struct DenseRefineReport
```

- `reselected` `c_size_t`: Entries whose neighbors were selected again, the islands of every heal round included.
- `changed` `c_size_t`: Of those, the entries whose neighbor set gained a member it lacked; zero means settled.
- `islands_found` `c_size_t`: Entries the first audit found not reached both ways.
- `islands_reconnected` `c_size_t`: 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/mojo/executors.md#health) right after would take it.

Conforms to: `Copyable`, `Defaultable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## __init__

Zeroes the report, which is what a failed call leaves.

```mojo
def __init__(out self)
```

## DenseRefineConfig

The knobs of `usearch_dense_refine_t`; zeroed or absent ones derive what the C interface derives.

```mojo
struct DenseRefineConfig[stats_origin: MutOrigin = MutUntrackedOrigin]
```

- `stats_origin` (comptime): The lent telemetry slot's origin, inferred where one is lent.

- `expansion_factor` `Int`: The breadth of the candidates the re-selection walk explores; zero derives.
- `stats` `Optional[Pointer[DenseTraversalStats, stats_origin]]`: Receives this call's traversal telemetry, fully overwritten; absent skips reporting.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## __init__

Names only the knobs that differ from the derived ones.

```mojo
def __init__(
    out self,
    *,
    expansion_factor: Int = Int(0),
    stats: Optional[Pointer[DenseTraversalStats, stats_origin]] = Optional()
)
```

- `expansion_factor`: The breadth of the candidates the re-selection walk explores; zero derives.
- `stats`: Receives this call's traversal telemetry; absent skips reporting.