# Metrics

> USearch for Python

`import usearch`

`from usearch import DenseIndex`

## DenseMetric

How a dense index scores two vectors.

```python
class DenseMetric(IntEnum)
```

- `INNER` = `1`: Sum of elementwise products, unnormalized; the one metric the linear-algebra verbs accept.
- `ANGULAR` = `2`: Cosine distance in [0, 2], zero for identical directions and blind to magnitude.
- `EUCLIDEAN` = `3`: L2 distance, non-negative and zero only for identical vectors.
- `HAMMING` = `4`: Count of differing bits, ranging up to the dimensionality.
- `JACCARD` = `5`: Differing bits over union bits in [0, 1], ignoring the zeros both vectors share.

## DenseIndex

Vector search over equidimensional dense embeddings; its verbs run on the calling thread.

```python
class DenseIndex
```

## init_ram

Starts an empty, mutable graph in host memory.

```python
@classmethod
def init_ram(
    dimensions: int,
    metric: DenseMetric = ...,
    quantization: Scalar = ...,
    *,
    connectivity: int = 0,
    values_per_key: int = 0,
    memory_domains: Sequence[int] | None = None,
    cpu_class: CPUClass | None = None,
) -> DenseIndex
```

## init_vram

Starts an empty, mutable graph on CUDA devices.

```python
@classmethod
def init_vram(
    dimensions: int,
    metric: DenseMetric = ...,
    quantization: Scalar = ...,
    *,
    connectivity: int = 0,
    values_per_key: int = 0,
    devices: Sequence[int] | None = None,
    gpu_class: GPUClass | None = None,
) -> DenseIndex
```

## load_ram

Copies a checkpoint into a new, mutable index in host memory.

```python
@classmethod
def load_ram(
    path: _PathLike,
    /,
    *,
    memory_domains: Sequence[int] | None = None,
    executor: Executor | None = None,
    values_per_key: int = 0,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    cpu_class: CPUClass | None = None,
) -> DenseIndex
```

## load_ram_buffer

Copies a monolith out of a buffer into host memory.

```python
@classmethod
def load_ram_buffer(
    buffer: Buffer,
    /,
    *,
    memory_domains: Sequence[int] | None = None,
    executor: Executor | None = None,
    values_per_key: int = 0,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    cpu_class: CPUClass | None = None,
) -> DenseIndex
```

## load_vram

Copies a checkpoint into a new, mutable index on CUDA devices.

```python
@classmethod
def load_vram(
    path: _PathLike,
    /,
    *,
    devices: Sequence[int] | None = None,
    executor: Executor | None = None,
    values_per_key: int = 0,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    gpu_class: GPUClass | None = None,
) -> DenseIndex
```

## load_vram_buffer

Copies a monolith out of a buffer onto CUDA devices.

```python
@classmethod
def load_vram_buffer(
    buffer: Buffer,
    /,
    *,
    devices: Sequence[int] | None = None,
    executor: Executor | None = None,
    values_per_key: int = 0,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    gpu_class: GPUClass | None = None,
) -> DenseIndex
```

## view_ram

Serves a checkpoint in place through a memory mapping, read-only.

```python
@classmethod
def view_ram(path: _PathLike, /) -> DenseIndex
```

## view_nvme

Serves a checkpoint in place from NVMe drives, read-only.

```python
@classmethod
def view_nvme(
    path: _PathLike,
    /,
    *,
    paths: Sequence[_PathLike] | None = None,
    executor: Executor | None = None,
    cpu_class: CPUClass | None = None,
) -> DenseIndex
```

## metadata_read

Reads a checkpoint's geometry without loading it.

```python
@staticmethod
def metadata_read(
    path: _PathLike,
    /,
    *,
    executor: Executor | None = None,
) -> DenseMetadata
```

## metadata_read_buffer

Reads a monolith's geometry.

```python
@staticmethod
def metadata_read_buffer(
    buffer: Buffer,
    /,
    *,
    executor: Executor | None = None,
) -> DenseMetadata
```

## on

A receiver whose verbs block on `executor`.

```python
def on(executor: Executor, /) -> On[DenseIndex]
```

Python-only.

## deferred

A receiver whose verbs submit to `executor`, each answering a [`Deferred`](https://www.unum.cloud/docs/usearch/python/executors.md#Deferred).

```python
def deferred(executor: Executor, /) -> DeferredOn[DenseIndex]
```

Python-only.

## describe

The frozen metadata and current counters.

```python
def describe() -> DenseIndexDescription
```

## reserve

Grows the index to host at least [`capacity`](https://www.unum.cloud/docs/usearch/python/introspection.md#capacity) entries, a hint, since insertions grow it on demand.

```python
def reserve(capacity: int, /) -> None
```

## clear

Drops every entry, keeping the capacity and geometry.

```python
def clear() -> None
```

## insert

Inserts a batch of vectors under their keys, all or nothing.

```python
def insert(
    keys: Sequence[_KeyLike] | _Tensor,
    vectors: _Tensor,
    /,
    *,
    expansion_factor: int = 0,
    dtype: Scalar | None = None,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: DenseTraversalStats | None = None,
) -> None
```

## refine

Re-selects every entry's neighbors, reporting what changed.

```python
def refine(
    *,
    expansion_factor: int = 0,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: DenseTraversalStats | None = None,
) -> RefineReport
```

## health

Audits how much of the graph a search reaches.

```python
def health() -> DenseReachability
```

## search

Finds the `wanted` nearest entries for every query row.

```python
def search(
    queries: _Tensor,
    wanted: int,
    arena: Arena,
    /,
    *,
    expansion_factor: int = 0,
    traversal: Traversal = ...,
    dtype: Scalar | None = None,
    predicate: Callable[[Key], bool] | None = None,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: DenseTraversalStats | None = None,
) -> Matches
```

## count

How many entries share [`key`](https://www.unum.cloud/docs/usearch/python/inputs-and-outputs.md#key).

```python
def count(key: _KeyLike, /) -> int
```

## get

Every vector stored under [`key`](https://www.unum.cloud/docs/usearch/python/inputs-and-outputs.md#key), empty when it is absent.

```python
def get(
    key: _KeyLike,
    arena: Arena,
    /,
    *,
    outputs_dtype: Scalar = ...,
) -> DenseVectors
```

## multiply

Every pair the walk scored, an approximate sparse product.

```python
def multiply(
    rows: _Tensor,
    wanted: int,
    arena: Arena,
    /,
    *,
    expansion_factor: int = 0,
    dtype: Scalar | None = None,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: DenseTraversalStats | None = None,
) -> DenseProducts
```

## attend

Softmax attention folded into the walk, refused on VRAM with [`DeviceError`](https://www.unum.cloud/docs/usearch/python/errors.md#DeviceError).

```python
def attend(
    queries: _Tensor,
    values: _Tensor,
    row_of: Callable[[Key], int | None],
    arena: Arena,
    /,
    *,
    head_count: int = 1,
    expansion_factor: int = 0,
    score_scale: float = 0.0,
    dtype: Scalar | None = None,
    values_dtype: Scalar | None = None,
    outputs_dtype: Scalar | None = None,
    carry: _Tensor | None = None,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: DenseTraversalStats | None = None,
) -> DenseVectors
```

## maxsim

Late interaction over multi-row queries.

```python
def maxsim(
    queries: _Tensor,
    rows_per_query: int,
    wanted: int,
    arena: Arena,
    /,
    *,
    expansion_factor: int = 0,
    traversal: Traversal = ...,
    dtype: Scalar | None = None,
    predicate: Callable[[Key], bool] | None = None,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: DenseTraversalStats | None = None,
) -> DenseProducts
```

## absorb

Absorbs and consumes every donor, one after another.

```python
def absorb(
    *donors: DenseIndex = (),
    progress: _Progress | None = None,
    progress_steps: int = 0,
) -> RefineReport
```

## split

Splits the entries into the empty receivers, leaving this index empty.

```python
def split(
    *receivers: DenseIndex = (),
    expansion_factor: int = 0,
    seed: int = 0,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: DenseTraversalStats | None = None,
) -> RefineReport
```

## sample

Draws keys around `focus`, placed beside the `shown` keys.

```python
def sample(
    wanted: int,
    arena: Arena,
    /,
    *,
    shown: Sequence[_KeyLike] | _Tensor | None = None,
    shown_coordinates: _Tensor | None = None,
    focus: Sequence[_KeyLike] | _Tensor | None = None,
    seed: int = 0,
    expansion_factor: int = 0,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: DenseTraversalStats | None = None,
) -> Sample
```

## save

Writes a checkpoint in the layout the extension picks.

```python
def save(
    path: _PathLike,
    /,
    *,
    progress: _Progress | None = None,
    progress_steps: int = 0,
) -> None
```

## save_buffer

Serializes one monolith into an arena.

```python
def save_buffer(
    arena: Arena,
    /,
    *,
    progress: _Progress | None = None,
    progress_steps: int = 0,
) -> Monolith
```

## cursor

A walk [`DenseCursor.next`](https://www.unum.cloud/docs/usearch/python/retrieval-and-streaming.md#next) pulls in batches, from `starts` when given.

```python
def cursor(
    starts: Sequence[_KeyLike] | _Tensor | None = None,
) -> DenseCursor
```

## search_stream

A resumable stream of matches for one query.

```python
def search_stream(
    query: _Tensor,
    /,
    *,
    expansion_factor: int = 0,
    dtype: Scalar | None = None,
) -> DenseSearchStream
```

## __len__

Stored entries.

```python
def __len__() -> int
```

Python-only.

## __contains__

Whether any entry holds [`key`](https://www.unum.cloud/docs/usearch/python/inputs-and-outputs.md#key).

```python
def __contains__(key: _KeyLike, /) -> bool
```

Python-only.

## capacity

Entries hosted without growing again.

```python
capacity: int
```

## dimensions

Scalars per vector.

```python
dimensions: int
```

## connectivity

Connections per node.

```python
connectivity: int
```

## memory_usage

Bytes the handle holds.

```python
memory_usage: int
```

## cpu_class

The [`CPUClass`](https://www.unum.cloud/docs/usearch/python/introspection.md#CPUClass) dispatch picked on this machine, or None.

```python
cpu_class: CPUClass | None
```

## gpu_class

The [`GPUClass`](https://www.unum.cloud/docs/usearch/python/introspection.md#GPUClass) dispatch picked on the index's devices, or None.

```python
gpu_class: GPUClass | None
```

## shards_count

Live shards.

```python
shards_count: int
```