# Fingerprints

> StringZilla for Python

`from stringzilla import OverlapEngine`

## OverlapEngine

Hash a batch of queries into one window forest and probe it with many candidates.

```python
class OverlapEngine
```

A window is a fixed-width byte n-gram, and a score is the share of a candidate's windows
that the query also spells, in [0, 1]. The score is asymmetric in the two sides.

Example:

engine = sz.OverlapEngine(sz.Strings(['abcdef']), [3, 4])
out = memoryview(bytearray(8)).cast('f', (1, 1, 2))
engine.scores(sz.Strings(['abcdefg']), out)
0.0 <= out[0, 0, 0] <= 1.0
True

## OverlapEngine

```python
OverlapEngine(
    queries: Strings,
    widths: Sequence[int],
    *,
    candidates_budget: int = 0,
    capabilities: Capability | None = None,
    stream: int | None = None,
)
```

## scores

scores(candidates, out, *, radius=None, stream=None) -> None

```python
def scores(
    candidates: Strings,
    out: _Buffer,
    *,
    radius: float | None = None,
    stream: int | None = None,
) -> None
```

Score every prepared query against every candidate, at every width, into `out`.

Example:

engine = sz.OverlapEngine(sz.Strings(['abcdef']), [3])
out = memoryview(bytearray(4)).cast('f', (1, 1, 1))
engine.scores(sz.Strings(['abcdef']), out)
out[0, 0, 0]
1.0

- `candidates`: Texts whose windows probe the forest, from [`Strings.copy`](https://www.unum.cloud/docs/stringzilla/python/hashing-and-checksums.md#copy) on a GPU.
- `out`: Writable 3-D buffer of 32-bit floats, at least
(len(queries), len(candidates), len(widths)), contiguous along its width axis.
- `radius`: The furthest distance a pair may lie at and still score exactly,
a distance being the windows it misses over its longer side's, summed over every width.
A pair past it scores 0.0 at every width, and None or 1.0 keep every score exact.
- `stream`: A stream of the engine's device as an integer, or None for the
default. A device engine joins it before returning, so `out` must be device-reachable;
a host engine ignores it.