atomscale.results.embeddings.EmbeddingsResult#

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)

__init__(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]
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)

Methods

__init__(data_id, workflow, kind, ...[, ...])

as_dict()

A JSON serializable dict representation of an object.

from_api(payload, *, data_id, workflow, ...)

Build an EmbeddingsResult from a raw endpoint payload.

from_dict(d)

Reconstruct an MSONable object from a dict.

load(file_path)

Load an instance from a JSON file written by save().

save(json_path[, mkdir, json_kwargs, ...])

Serialize the instance to JSON on disk, pickling fields if needed.

to_json()

Returns a json string representation of the MSONable object.

unsafe_hash()

Return a hash of the current object.

validate_monty_v1(_MSONable__input_value)

Pydantic validator with correct signature for pydantic v1.x.

validate_monty_v2(_MSONable__input_value, _)

Pydantic validator with correct signature for pydantic v2.x.

Attributes

REDIRECT

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

as_dict() → dict

A JSON serializable dict representation of an object.

Return type:

dict

classmethod from_dict(d: dict) → MSONable

Reconstruct an MSONable object from a dict.

Parameters:

d (dict) – Dict representation.

Return type:

MSONable

Returns:

MSONable class.

classmethod load(file_path: PathLike | str) → MSONable

Load an instance from a JSON file written by save().

Parameters:

file_path (PathLike | str) – The JSON file to load from.

Return type:

MSONable

Returns:

An instance of the class being reloaded.

save(json_path: PathLike | str, mkdir: bool = True, json_kwargs: dict | None = None, pickle_kwargs: dict | None = None, strict: bool = True) → None

Serialize the instance to JSON on disk, pickling fields if needed.

For a fully MSONable class, only {save_dir}/class.json is written. For a partially MSONable class, non-serializable attributes are pickled individually into the same directory, keeping the JSON portion readable.

Parameters:

  • json_path (PathLike | str) – The file to which to save the JSON object. A pickled companion file with the same stem but a different extension may also be written if the class is not entirely MSONable.

  • mkdir (bool) – If True, create the target directory (including parents).

  • json_kwargs (dict | None) – Keyword arguments forwarded to the JSON serializer.

  • pickle_kwargs (dict | None) – Keyword arguments forwarded to pickle.dump.

  • strict (bool) – If True, refuse to overwrite existing files.

Return type:

None

to_json() → str

Returns a json string representation of the MSONable object.

Return type:

str

unsafe_hash() → Any

Return a hash of the current object.

This uses a generic but low performance method of converting the object to a dictionary, flattening any nested keys, and then performing a hash on the resulting object.

Return type:

Any

classmethod validate_monty_v1(_MSONable__input_value)

Pydantic validator with correct signature for pydantic v1.x.

classmethod validate_monty_v2(_MSONable__input_value, _)

Pydantic validator with correct signature for pydantic v2.x.