atomscale.results.embeddings#

Result object for similarity embedding vectors.

Classes

EmbeddingsResult(data_id, workflow, kind, ...)

Embedding vectors for a single data entry.
class atomscale.results.embeddings.EmbeddingsResult(data_id: UUID | str, workflow: str, kind: str, window_span: float, vectors: ndarray[tuple[Any, ...], dtype[_ScalarT]], dimension: int, count: int, truncated: bool, offset: int = 0, real_times: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None, unix_times_ms: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None, cluster_sizes: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None)[source]

Bases: MSONable

Embedding vectors for a single data entry.

Returned by atomscale.Client.get_embeddings(). The vectors are held as a dense (n_returned, dimension) float array in vectors, with parallel metadata arrays. The two kind variants carry different metadata:

  • kind="window": one time-resolved vector per window. real_times (relative seconds) and unix_times_ms (absolute milliseconds) give the point in time each vector corresponds to.

  • kind="prototype": a small set of representative vectors. cluster_sizes gives how many windows each one summarizes.

Metadata arrays not relevant to the returned kind are None.

data_id

Data ID the embeddings were computed for.

Type:

UUID | str

workflow

Similarity workflow name (e.g. "rheed_stationary").

Type:

str

kind

"window" or "prototype".

Type:

str

window_span

Window span (seconds) the vectors were computed at.

Type:

float

vectors

(n_returned, dimension) array of embedding vectors, where n_returned == len(vectors).

Type:

NDArray

dimension

Length of each embedding vector (0 when the result is empty).

Type:

int

count

Total vectors available for this data_id before offset/limit — may exceed len(vectors). The number actually returned is len(vectors).

Type:

int

offset

Number of leading vectors skipped (window kind).

Type:

int

truncated

True when more vectors are available than were returned, so the result is incomplete.

Type:

bool

real_times

(n_returned,) relative time in seconds (window kind).

Type:

NDArray | None

unix_times_ms

(n_returned,) absolute unix time in ms (window kind).

Type:

NDArray | None

cluster_sizes

(n_returned,) windows summarized per vector (prototype kind).

Type:

NDArray | None

Parameters:

  • data_id (UUID | str)

  • workflow (str)

  • kind (str)

  • window_span (float)

  • vectors (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]])

  • dimension (int)

  • count (int)

  • truncated (bool)

  • offset (int)

  • real_times (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | None)

  • unix_times_ms (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | None)

  • cluster_sizes (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | None)

classmethod from_api(payload: dict[str, Any] | None, *, data_id: UUID | str, workflow: str, kind: str, window_span: float) → EmbeddingsResult[source]

Build an EmbeddingsResult from a raw endpoint payload.

When no embeddings are available for the given workflow / window span, this emits a UserWarning and returns an empty result so loops over many IDs don’t crash.

Parameters:

  • payload (dict[str, Any] | None)

  • data_id (UUID | str)

  • workflow (str)

  • kind (str)

  • window_span (float)

Return type:

EmbeddingsResult