atomscale.client#

Main client for interacting with the Atomscale API.

Classes

Client([api_key, endpoint, mute_bars])

Atomic Data Sciences API client

class atomscale.client.Client(api_key: str | None = None, endpoint: str | None = None, mute_bars: bool = False)[source]

Bases: BaseClient

Atomic Data Sciences API client

Parameters:

api_key (str | None)
endpoint (str)
mute_bars (bool)
api_key – API key. Explicit value takes precedence; if None, falls back to AS_API_KEY environment variable.
endpoint – Root API endpoint. Explicit value takes precedence; if None, falls back to AS_API_ENDPOINT environment variable, defaulting to ‘https://api.atomscale.ai/’ if not set.
mute_bars – Whether to mute progress bars. Defaults to False.

search(keywords: str | list[str] | None = None, include_organization_data: bool = True, data_ids: str | list[str] | None = None, physical_sample_ids: str | list[str] | None = None, project_ids: str | list[str] | None = None, data_type: Literal['rheed_image', 'rheed_stationary', 'rheed_rotating', 'xps', 'xrd', 'photoluminescence', 'pl', 'raman', 'recipe', 'optical', 'metrology', 'tool_state', 'ellipsometry', 'all'] = 'all', status: Literal['success', 'pending', 'error', 'running', 'stream_active', 'stream_interrupted', 'stream_finalizing', 'stream_error', 'all'] = 'all', growth_length: tuple[int | None, int | None] = (None, None), upload_datetime: tuple[datetime | None, datetime | None] = (None, None), last_updated: tuple[datetime | None, datetime | None] = (None, None), last_accessed_datetime: tuple[datetime | None, datetime | None] | None = None) → DataFrame[source]

Search and obtain data catalogue entries

Parameters:

keywords (str | list[str] | None) – Keyword or list of keywords to search all data catalogue fields with. This searching is applied after all other explicit filters. Defaults to None.
include_organization_data (bool) – Whether to include catalogue entries from other users in your organization. Defaults to True.
data_ids (str | list[str] | None) – Data ID or list of data IDs. Defaults to None.
physical_sample_ids (str | list[str] | None) – Physical sample ID or list of IDs. Defaults to None.
project_ids (str | list[str] | None) – Project ID or list of IDs. Defaults to None.
data_type (Literal['rheed_image', 'rheed_stationary', 'rheed_rotating', 'xps', 'xrd', 'photoluminescence', 'pl', 'raman', 'recipe', 'optical', 'metrology', 'tool_state', 'ellipsometry', 'all']) – Type of data. "tool_state" is canonical; "metrology" remains accepted as a deprecated compatibility alias.
status (Literal["success", "pending", "error", "running", "all"]) – Analyzed status of the data. Defaults to “all”.
growth_length (tuple[int | None, int | None]) – Minimum and maximum values of the growth length in seconds. Defaults to (None, None) which will include all non-video data.
upload_datetime (tuple[datetime | None, datetime | None]) – Minimum and maximum values of the upload datetime. Defaults to (None, None).
last_updated (tuple[datetime | None, datetime | None]) – Minimum and maximum values of the last updated datetime. Defaults to (None, None).
last_accessed_datetime (tuple[datetime | None, datetime | None] | None) – Deprecated alias for last_updated; will be removed in a future release.

Returns:

Pandas DataFrame containing matched entries in the data catalogue.

Return type:

(DataFrame)

Get analyzed data results

Parameters:: data_ids (str | list[str]) – Data ID or list of data IDs from the data catalogue to obtain analyzed results for.
Returns:: List of result objects
Return type:: list[atomscale.results.RHEEDVideoResult | atomscale.results.RHEEDImageResult | atomscale.results.XPSResult | atomscale.results.XRDResult]

get_changepoints(data_ids: str | list[str], latest_only: bool = True, detection_method: Literal['forecasting', 'clustering', 'intensity_profile'] | None = 'intensity_profile', severity: Literal['info', 'warning', 'critical'] | None = 'critical', as_dataframe: bool = True) → DataFrame | list[ChangepointResult][source]

Get changepoint detection records for one or more data IDs.

Parameters:

data_ids (str | list[str]) – Data ID or list of data IDs from the data catalogue.
latest_only (bool) – If True (default), only return changepoints from the most recently completed detection run for each (data_id, detection_method) pair. If False, return all changepoints from every historical run.
detection_method (str | None) – Filter to a single detection method. One of “forecasting”, “clustering”, “intensity_profile”. Defaults to “intensity_profile”. Pass None to include all detection methods.
severity (str | None) – Filter to a single severity level. One of “info”, “warning”, “critical”. Defaults to “critical”. Pass None to include all severities.
as_dataframe (bool) – If True (default) return a pandas DataFrame. If False return a list of ChangepointResult objects.

Returns:

Changepoint records matching the filters.

Return type:

DataFrame | list[ChangepointResult]

get_similarity_trajectory(source_id: str, *, workflow: str = 'rheed_stationary', last_n: int | None = None, window_span: float | None = None, reference_ids: list[str] | None = None, softmax_mode: str | None = None, reference_n_values: int | None = None) → SimilarityTrajectoryResult[source]

Fetch a one-shot similarity trajectory for a source data_id or physical_sample_id.

Parameters:

source_id (str) – Data ID or physical sample ID the trajectory is computed against.
workflow (str) – Similarity workflow name (e.g. “rheed_stationary”). Defaults to “rheed_stationary”.
last_n (int | None) – If set, only fetch the last N points of the trajectory.
window_span (float | None) – Optional window span parameter forwarded to the provider.
reference_ids (list[str] | None) – Optional list of reference data IDs to compare against.
softmax_mode (str | None) – Optional softmax mode forwarded to the provider.
reference_n_values (int | None) – Optional number of reference values forwarded to the provider.

Return type:

SimilarityTrajectoryResult

Returns:

SimilarityTrajectoryResult with the populated timeseries DataFrame.

query_rheed_embeddings(data_id: str, *, workflow: str = 'rheed_stationary', window_span: float = 60.0, kind: Literal['prototype', 'window'] = 'prototype', top_k: int = 10) → DataFrame[source]

Find RHEED data items whose embeddings are most similar to this one.

Runs k-NN over the embedding index using this item’s own vectors and returns the best-matching other data items (“find similar growths”).

Parameters:

data_id (str) – Data ID whose vectors seed the query.
workflow (str) – Similarity workflow name. Defaults to “rheed_stationary”.
window_span (float) – Embedding window span in seconds (must match an embedded span).
kind (Literal['prototype', 'window']) – “prototype” (coarse, default) or “window” (finer, more queries).
top_k (int) – Max neighbors to return. The backend caps this at 30.

Return type:

DataFrame

Returns:

DataFrame with columns data_id, similarity (1 = identical), and locus columns (source_index, neighbor_index, real_time_seconds, unix_time_ms), sorted by descending similarity. Empty when this item has no embeddings for the given (workflow, window_span).

get_embeddings(data_id: str, *, workflow: str = 'rheed_stationary', window_span: float = 60.0, kind: Literal['window', 'prototype'] = 'window', offset: int = 0, limit: int | None = None) → EmbeddingsResult[source]

Fetch embedding vectors for a data entry.

Parameters:

data_id (str) – Data ID to fetch embeddings for.
workflow (str) – Similarity workflow name. Defaults to "rheed_stationary".
window_span (float) – Window span in seconds. Defaults to 60.0.
kind (Literal['window', 'prototype']) – "window" for one time-resolved vector per window (with real_times / unix_times_ms), or "prototype" for a small set of representative vectors (with cluster_sizes). Defaults to "window".
offset (int) – Number of leading vectors to skip. Defaults to 0.
limit (int | None) – Maximum number of vectors to return. None (default) returns all available vectors.

Returns:

The embedding vectors and associated metadata. When no embeddings are available for this data (workflow / window span), a UserWarning is emitted and an empty result is returned, so loops over many IDs don’t crash. result.count is the total number of vectors available before offset / limit; the number actually returned is len(result.vectors).

Return type:

EmbeddingsResult

get_similarity_matches(source_id: str, *, workflow: str = 'rheed_stationary', window_span: float = 60.0, live_comparison: bool = False, limit: int | None = None) → DataFrame[source]

Fetch the top similarity matches for a source data entry.

Parameters:

source_id (str) – Data ID (or physical sample ID) to find matches for.
workflow (str) – Similarity workflow name. Defaults to "rheed_stationary".
window_span (float) – Window span in seconds. Defaults to 60.0.
live_comparison (bool) – When True, also include the source entry’s most recent (still-streaming) data in the comparison. Defaults to False.
limit (int | None) – Maximum number of matches to return. None (default) uses the server default.

Returns:

Columns ["data_id", "item_name", "similarity"], one row per match. Empty (with those columns) when there are no matches or the source is not found.

Return type:

DataFrame

get_rheed_timeseries(data_id: str, *, property_names: list[str] | None = None, include_low_level_features: bool = False, include_masks: bool = False, last_n: int | None = None, elapsed_seconds: float | None = None) → DataFrame[source]

Fetch the RHEED feature timeseries for a data entry.

Unlike get(), which returns only the standard feature set, this method can also return the full set of low-level features and filter which points are returned.

Parameters:

data_id (str) – Data ID of the RHEED video.
property_names (list[str] | None) – Restrict the result to these feature names. These are the underlying property names (e.g. specular_intensity, referenced_strain), which may differ from the display column names in the returned DataFrame. None (default) returns the standard set.
include_low_level_features (bool) – When True, include the full set of low-level per-point features as additional columns. Defaults to False.
include_masks (bool) – When True, fetch the per-frame RHEED segmentation masks (see get_frame_masks()) and attach them to the DataFrame as mask_rle / mask_height / mask_width columns, joined on the Frame Number axis. Only masks for the frames the returned series spans are fetched, so this respects any last_n / elapsed_seconds window rather than pulling the whole video’s masks. Coverage is sparse (featurized frames only), so rows whose frame has no mask — and all rows when the video has no mask artifact — get NA in those columns. Decode a row’s mask_rle with atomscale.results.decode_mask_rle(). Defaults to False.
last_n (int | None) – If set, only return the last N points.
elapsed_seconds (float | None) – If set, only return points within the last elapsed_seconds of the recording.

Returns:

The RHEED timeseries, indexed by ["Angle", "Frame Number"] when available. Low-level feature columns are included when include_low_level_features=True; mask columns when include_masks=True.

Return type:

DataFrame

get_frame(data_id: str, *, frame_index: int = 0) → RHEEDImageResult | None[source]

Fetch a single extracted RHEED frame as a RHEEDImageResult.

Parameters:

data_id (str) – Data ID of the RHEED video.
frame_index (int) – Index into the video’s extracted-frame list (supports negative indexing). Defaults to 0 (first extracted frame).

Returns:

The frame’s image result, or None if the video has no extracted frames, frame_index is out of range, or the selected frame has no image.

Return type:

RHEEDImageResult | None

get_frame_masks(data_id: str, *, from_frame: int = 0, to_frame: int | None = None, decode: bool = False) → list[dict[str, Any]] | dict[int, ndarray[tuple[Any, ...], dtype[_ScalarT]]][source]

Fetch per-frame RHEED segmentation masks for a processed video.

Each featurized frame of a processed RHEED video carries a binary segmentation mask of the diffraction pattern, encoded as a COCO run-length-encoding (RLE) counts string (the same format as the single-frame get_frame() mask). frame_number is the absolute frame index, keyed identically to the processed video frames and the RHEED timeseries Frame Number axis, so a decoded masks[frame_number] overlays that frame of the video fetched via download().

Coverage is sparse: masks exist only for featurized frames. For stationary videos that is every frame; for rotating / per-azimuth videos it is the sampled subset, so the returned frame numbers are not necessarily contiguous — frames without a mask are simply absent.

Parameters:

data_id (str) – Data ID of the RHEED video (the same id used for the video / timeseries).
from_frame (int) – First absolute frame number to fetch, inclusive. Must be >= 0. Defaults to 0.
to_frame (int | None) – Last absolute frame number to fetch, inclusive. None (default) fetches through the end of the video (every featurized frame from from_frame onward).
decode (bool) – When True, decode each RLE mask into an (H, W) uint8 (0/1) NumPy array and return a dict keyed by frame number. When False (default), return the raw rows with the RLE string intact.

Returns:

When decode=False, a list of row dicts each with data_id, processed_data_id, frame_number, mask_rle, mask_height and mask_width. When decode=True, a dict {frame_number: np.ndarray} of decoded (H, W) uint8 masks. Returns an empty list / dict when the video has no per-frame mask artifact (e.g. a non-RHEED item, or a video processed before per-frame masks were persisted).

Return type:

list[dict] | dict[int, NDArray]

iter_poll_similarity_trajectory(source_id: str, *, interval: float = 1.0, last_n: int | None = None, **kwargs: Any) → Iterator[DataFrame][source]

Synchronously poll similarity trajectory data, yielding DataFrames.

Thin wrapper around atomscale.similarity.iter_poll_trajectory(). See that function for the full set of keyword arguments (distinct_by, until, max_polls, fire_immediately, jitter, on_error).

Parameters:

source_id (str)
interval (float)
last_n (int | None)
kwargs (Any)

Return type:

Iterator[DataFrame]

aiter_poll_similarity_trajectory(source_id: str, *, interval: float = 1.0, last_n: int | None = None, **kwargs: Any) → AsyncIterator[DataFrame][source]

Asynchronously poll similarity trajectory data without blocking the loop.

Thin wrapper around atomscale.similarity.aiter_poll_trajectory().

Parameters:

source_id (str)
interval (float)
last_n (int | None)
kwargs (Any)

Return type:

AsyncIterator[DataFrame]

start_polling_similarity_trajectory_thread(source_id: str, *, interval: float = 1.0, last_n: int | None = None, on_result: Callable[[DataFrame], None], **kwargs: Any) → Event[source]

Start polling similarity trajectory data in a background daemon thread.

Returns a threading.Event that can be set to stop polling.

Parameters:

source_id (str)
interval (float)
last_n (int | None)
on_result (Callable[[DataFrame], None])
kwargs (Any)

Return type:

Event

start_polling_similarity_trajectory_task(source_id: str, *, interval: float = 1.0, last_n: int | None = None, on_result: Callable[[DataFrame], Any] | None = None, **kwargs: Any) → Task[None][source]

Start polling similarity trajectory data as an asyncio.Task.

Parameters:

source_id (str)
interval (float)
last_n (int | None)
on_result (Callable[[DataFrame], Any] | None)
kwargs (Any)

Return type:

Task[None]

list_physical_samples() → DataFrame[source]

List physical samples available to the user.

Return type:: DataFrame

list_projects() → DataFrame[source]

List projects available to the user.

Return type:: DataFrame

get_physical_sample(physical_sample_id: str, *, include_organization_data: bool = True, align: bool | str = False, include_sample_metrics: bool = True) → PhysicalSampleResult[source]

Get all data for a physical sample.

Parameters:

physical_sample_id (str) – Identifier of the physical sample.
include_organization_data (bool) – Whether to include organization data. Defaults to True.
align (bool | str) – Whether to align timeseries data. If truthy, an aligned DataFrame is returned.
include_sample_metrics (bool) – Whether to also fetch the sample-scoped computed timeseries results (rheed_quality, composition_metric, …) and expose them on PhysicalSampleResult.sample_metrics. Defaults to True. This is one extra request; set False to skip it. See get_physical_sample_timeseries().

Return type:

PhysicalSampleResult

get_physical_sample_timeseries(physical_sample_id: str, *, property_names: list[str] | None = None) → DataFrame[source]

Current sample-scoped computed timeseries results for a physical sample.

Returns the latest row per property (rheed_quality, composition_metric, …) from the physical_sample_timeseries_results table — the outputs of per-sample DBOS workflows, content-addressed by their constituent data_id set. These are the headline “sample result,” distinct from get_physical_sample()’s aligned_timeseries, which only re-joins each constituent data item’s own curated RHEED series.

The series are returned faithfully (no scalar reduction): callers wanting a single number reduce the returned series themselves.

Parameters:

physical_sample_id (str) – Identifier of the physical sample.
property_names (list[str] | None) – Restrict the result to these properties, e.g. ["rheed_quality"]. Filtered client-side (the endpoint has no filter param yet). None (default) returns all properties.

Returns:

Long form — one row per (property, sample-point) — with columns property_name, real_time_seconds, value (float, NaN for gaps), result_id, last_updated, and generating_dbos_workflow_id. Long (not wide) because distinct properties can have different axes, so a wide join on real_time_seconds would mis-align them. Per-property constituent_data_ids are in df.attrs["constituent_data_ids"]. A sample with no sample-scoped metrics yields an empty DataFrame.

Return type:

DataFrame

Raises:

ClientError – If the physical sample does not exist (404).

get_project(project_id: str, *, include_organization_data: bool = True, align: bool | str = False) → ProjectResult[source]

Get all data grouped by physical sample for a project.

Parameters:

project_id (str) – Identifier of the project.
include_organization_data (bool) – Whether to include organization data. Defaults to True.
align (bool | str) – Whether to align timeseries at the project level. Defaults to False.

Return type:

ProjectResult

upload(files: list[str | BinaryIO], physical_sample: str | None = None, project: str | None = None) → list[str][source]

Upload and process files.

Parameters:

files (list[str | BinaryIO]) – List containing string paths to files, or BinaryIO objects from open.
physical_sample (str | None) – Physical sample name or UUID to link uploads to. If a name is given and no matching sample exists, one is created automatically.
project (str | None) – Project name or UUID to associate the uploads with. The project must already exist (the SDK does not auto-create projects). When provided, physical_sample is required so the sample can be added to the project’s tracking list via POST /projects/{id}/configuration/tracking_samples.

Returns:

Data IDs assigned to the uploaded files.

Return type:

list[str]

download(data_ids: str | list[str], dest_dir: str | Path | None = None, data_type: Literal['raw', 'processed'] = 'processed')[source]

Download raw or processed files for any data type to disk.

Works for every data_type the platform stores (RHEED video, XPS / XRD / PL / Raman / optical / tool-state / ellipsometry / etc.) — the underlying data_entries/{raw_data|processed_data}/{data_id} endpoint is data-type-agnostic and returns whatever file format the backend has on record.

Parameters:

data_ids (str | list[str]) – One or more data IDs from the data catalogue.
dest_dir (str | Path | None) – Directory to write the files to. Defaults to the current working directory.
data_type (Literal["raw", "processed"]) – Whether to download raw or processed data.

download_videos(data_ids: str | list[str], dest_dir: str | Path | None = None, data_type: Literal['raw', 'processed'] = 'processed')[source]

Deprecated alias for download(). Kept for backwards compatibility.

Parameters:

data_ids (str | list[str])
dest_dir (str | Path | None)
data_type (Literal['raw', 'processed'])

list_growth_instruments() → list[dict[str, Any]][source]

List all growth instruments accessible by the user.

Returns instruments within the user’s organization.

Returns:

List of instruments with keys including:

synth_source_id (int): Unique instrument ID
source_name (str): Display name
synth_source_type (str): Instrument type (mbe, cvd, etc.)
source_manufacturer (str | None): Manufacturer name
source_model (str | None): Model name

Return type:

list[dict]

Example

>>> instruments = client.list_growth_instruments()
>>> for inst in instruments:
...     print(f"{inst['synth_source_id']}: {inst['source_name']}")

create_growth_instrument(label: str, name: str, instrument_type: Literal['mbe', 'cvd', 'pvd', 'sputter', 'ald', 'pld'], serial_id: str | None = None) → int[source]

Create a new growth instrument.

Parameters:

label (str) – Display name for the instrument (e.g., “Main MBE”).
name (str) – Manufacturer and model (e.g., “Veeco GEN10”).
instrument_type (Literal['mbe', 'cvd', 'pvd', 'sputter', 'ald', 'pld']) – Type of instrument.
serial_id (str | None) – Optional serial number or identifier.

Returns:

The synth_source_id of the created instrument.

Return type:

int

Example

>>> instrument_id = client.create_growth_instrument(
...     label="Main MBE",
...     name="Veeco GEN10",
...     instrument_type="mbe",
...     serial_id="SN-12345",
... )

delete_growth_instrument(synth_source_id: int) → None[source]

Delete a growth instrument.

Parameters:: synth_source_id (int) – ID of the instrument to delete.
Raises:: ClientError – If the instrument is not found or not accessible.
Return type:: None

Example

>>> client.delete_growth_instrument(synth_source_id=42)

Project Modules

atomscale.client.Client