atomscale 0.8.3__tar.gz → 0.9.0__tar.gz

atomscale-0.9.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: atomscale
+Version: 0.9.0
+Summary: Python SDK for Atomscale.
+Author-email: Atomscale <info@atomscale.ai>
+License: GPL-3.0-only
+Project-URL: Homepage, https://www.atomscale.ai
+Project-URL: Documentation, https://atomscale-ai.github.io/sdk
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: monty
+Requires-Dist: pillow
+Requires-Dist: networkx
+Requires-Dist: requests
+Requires-Dist: rich
+Requires-Dist: matplotlib
+Requires-Dist: pycocotools
+Requires-Dist: trackpy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-httpserver; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-order; extra == "dev"
+Requires-Dist: pytest-dependency; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff>=0.9.0; extra == "dev"
+Requires-Dist: ty; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Requires-Dist: pre-commit>=4.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.2; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.24; extra == "docs"
+Requires-Dist: sphinxawesome-theme>=5.0; extra == "docs"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/_static/AtomscaleLogoFull.png" alt="Atomscale" width="300">
+</p>
+
+<h1 align="center">Python SDK</h1>
+
+<p align="center">
+  <a href="https://github.com/atomscale-ai/sdk/actions/workflows/testing.yml?query=branch%3Amain"><img src="https://github.com/atomscale-ai/sdk/actions/workflows/testing.yml/badge.svg?branch=main" alt="Testing"></a>
+  <a href="https://github.com/atomscale-ai/sdk/releases/"><img src="https://img.shields.io/github/tag/atomscale-ai/sdk?include_prereleases=&sort=semver&color=blue" alt="GitHub tag"></a>
+  <img src="https://img.shields.io/badge/Python-3.10+-blue.svg?logo=python&logoColor=white" alt="Python">
+  <a href="#license"><img src="https://img.shields.io/badge/License-MPL_2.0-blue" alt="License"></a>
+</p>
+
+<p align="center">
+  <a href="https://atomscale-ai.github.io/sdk/"><img src="https://img.shields.io/badge/view-Documentation-blue?style=for-the-badge" alt="Documentation"></a>
+</p>
+
+---
+
+The official Python SDK for the [Atomscale](https://www.atomscale.ai) platform. Upload RHEED videos, stream live data, search the catalogue, and retrieve analysis results programmatically.
+
+## Features
+
+- **Unified Client** – Single interface for uploads, search, and downloads
+- **Live Streaming** – Push or pull RHEED frames in real-time
+- **Flexible Search** – Filter by keywords, data type, status, or time bounds
+- **Rich Results** – Access timeseries, diffraction graphs, and processed videos
+- **Polling Utilities** – Sync, async, and threaded options for monitoring updates
+
+## Installation
+
+```bash
+pip install atomscale
+```
+
+> **Note:** The package was renamed from `atomicds`. Importing `atomicds` still works but emits a `DeprecationWarning`.
+
+## Quick Start
+
+```python
+from atomscale import Client
+
+# Create a client (reads AS_API_KEY from environment)
+client = Client()
+
+# Upload files
+client.upload(files=["rheed_video.mp4"])
+
+# Search the catalogue
+results = client.search(keywords=["GaN"], status="success")
+
+# Fetch analysis results
+items = client.get(results["Data ID"].to_list())
+for item in items:
+    print(item.timeseries_data.tail())
+```
+
+## Documentation
+
+Full documentation is available at **[atomscale-ai.github.io/sdk](https://atomscale-ai.github.io/sdk/)**.
+
+- [Quickstart Guide](https://atomscale-ai.github.io/sdk/guides/quickstart.html)
+- [Upload Data](https://atomscale-ai.github.io/sdk/guides/upload-data.html)
+- [Search the Catalogue](https://atomscale-ai.github.io/sdk/guides/search-data.html)
+- [Stream RHEED Video](https://atomscale-ai.github.io/sdk/guides/stream-rheed.html)
+- [API Reference](https://atomscale-ai.github.io/sdk/modules.html)
+
+## License
+
+This project is licensed under the [Mozilla Public License 2.0](LICENSE).

atomscale-0.9.0/README.md

@@ -0,0 +1,70 @@
+<p align="center">
+  <img src="docs/_static/AtomscaleLogoFull.png" alt="Atomscale" width="300">
+</p>
+
+<h1 align="center">Python SDK</h1>
+
+<p align="center">
+  <a href="https://github.com/atomscale-ai/sdk/actions/workflows/testing.yml?query=branch%3Amain"><img src="https://github.com/atomscale-ai/sdk/actions/workflows/testing.yml/badge.svg?branch=main" alt="Testing"></a>
+  <a href="https://github.com/atomscale-ai/sdk/releases/"><img src="https://img.shields.io/github/tag/atomscale-ai/sdk?include_prereleases=&sort=semver&color=blue" alt="GitHub tag"></a>
+  <img src="https://img.shields.io/badge/Python-3.10+-blue.svg?logo=python&logoColor=white" alt="Python">
+  <a href="#license"><img src="https://img.shields.io/badge/License-MPL_2.0-blue" alt="License"></a>
+</p>
+
+<p align="center">
+  <a href="https://atomscale-ai.github.io/sdk/"><img src="https://img.shields.io/badge/view-Documentation-blue?style=for-the-badge" alt="Documentation"></a>
+</p>
+
+---
+
+The official Python SDK for the [Atomscale](https://www.atomscale.ai) platform. Upload RHEED videos, stream live data, search the catalogue, and retrieve analysis results programmatically.
+
+## Features
+
+- **Unified Client** – Single interface for uploads, search, and downloads
+- **Live Streaming** – Push or pull RHEED frames in real-time
+- **Flexible Search** – Filter by keywords, data type, status, or time bounds
+- **Rich Results** – Access timeseries, diffraction graphs, and processed videos
+- **Polling Utilities** – Sync, async, and threaded options for monitoring updates
+
+## Installation
+
+```bash
+pip install atomscale
+```
+
+> **Note:** The package was renamed from `atomicds`. Importing `atomicds` still works but emits a `DeprecationWarning`.
+
+## Quick Start
+
+```python
+from atomscale import Client
+
+# Create a client (reads AS_API_KEY from environment)
+client = Client()
+
+# Upload files
+client.upload(files=["rheed_video.mp4"])
+
+# Search the catalogue
+results = client.search(keywords=["GaN"], status="success")
+
+# Fetch analysis results
+items = client.get(results["Data ID"].to_list())
+for item in items:
+    print(item.timeseries_data.tail())
+```
+
+## Documentation
+
+Full documentation is available at **[atomscale-ai.github.io/sdk](https://atomscale-ai.github.io/sdk/)**.
+
+- [Quickstart Guide](https://atomscale-ai.github.io/sdk/guides/quickstart.html)
+- [Upload Data](https://atomscale-ai.github.io/sdk/guides/upload-data.html)
+- [Search the Catalogue](https://atomscale-ai.github.io/sdk/guides/search-data.html)
+- [Stream RHEED Video](https://atomscale-ai.github.io/sdk/guides/stream-rheed.html)
+- [API Reference](https://atomscale-ai.github.io/sdk/modules.html)
+
+## License
+
+This project is licensed under the [Mozilla Public License 2.0](LICENSE).

atomscale-0.9.0/docs/_static/custom.css

@@ -0,0 +1,38 @@
+/* Override hardcoded logo dimensions */
+img[alt="Logo"] {
+    height: 48px !important;
+    width: auto !important;
+    max-height: none !important;
+}
+
+/* Target the header/nav area logo specifically */
+header img[alt="Logo"],
+nav img[alt="Logo"],
+a img[alt="Logo"] {
+    height: 25px !important;
+    width: auto !important;
+    position: relative;
+    top: -5px;
+}
+
+/* Force badges to display inline horizontally */
+p > a.reference.external,
+p > img {
+    display: inline !important;
+    margin-right: 4px;
+}
+
+p > a.reference.external > img {
+    display: inline !important;
+    vertical-align: middle;
+}
+
+/* Reduce space between h1 and badges, add space below badges */
+section > h1 {
+    margin-bottom: 0.25rem !important;
+}
+
+section > p:first-of-type {
+    margin-top: 0 !important;
+    margin-bottom: 1.5rem !important;
+}

{atomscale-0.8.3 → atomscale-0.9.0}/docs/conf.py

@@ -72,37 +72,21 @@ pygments_style = "sphinx"
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "alabaster"
-# html_static_path = ['_static']
+html_theme = "sphinxawesome_theme"
+
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_logo = "_static/AtomscaleLogoFull.png"
+html_title = "Python SDK"
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
 html_theme_options = {
-    "github_button": True,
-    "github_type": "star&v=2",
-    "github_user": "atomic-data-sciences",
-    "github_repo": "api-client",
-    "github_banner": True,
-    "description": "Python SDK",
+    "show_breadcrumbs": True,
+    "show_prev_next": True,
+    "logo_light": "_static/AtomscaleLogoFull.png",
+    "logo_dark": "_static/AtomscaleLogoFull.png",
 }
 
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
-#
-html_sidebars = {
-    "**": [
-        "about.html",
-        "navigation.html",
-        "searchbox.html",
-    ]
-}
+html_permalinks_icon = "<span>#</span>"
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

{atomscale-0.8.3 → atomscale-0.9.0}/docs/guides/index.rst

@@ -13,3 +13,4 @@ single workflow so you can jump straight to what you need.
    inspect-results
    stream-rheed
    poll-timeseries
+   poll-trajectory

{atomscale-0.8.3 → atomscale-0.9.0}/docs/guides/inspect-results.rst

@@ -21,6 +21,11 @@ Each item in ``analysed`` is a subclass of
 :class:`atomscale.results.RHEEDVideoResult` or
 :class:`atomscale.results.RHEEDImageResult`, depending on the source data.
 
+.. note::
+
+   The :meth:`get` call fetches metadata and analysis artefacts for each ID.
+   For large result sets, consider batching or filtering first.
+
 Inspect time series data
 ------------------------
 
@@ -34,6 +39,21 @@ Inspect time series data
 The timeseries frame contains specular intensity, strain metrics, cluster IDs,
 and other summary features for every frame in the video.
 
+.. list-table:: Common timeseries columns
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Column
+     - Description
+   * - ``timestamp``
+     - Frame timestamp in seconds
+   * - ``specular_intensity``
+     - Specular spot brightness
+   * - ``strain``
+     - Computed strain metric
+   * - ``cluster_id``
+     - Pattern cluster assignment
+
 Work with extracted frames
 --------------------------
 
@@ -47,6 +67,11 @@ Work with extracted frames
 ``pattern_graph`` exposes the detected diffraction network as a NetworkX graph,
 while :meth:`get_pattern_dataframe` returns a tidy table describing each spot.
 
+.. tip::
+
+   Use ``figure.savefig("snapshot.png")`` to export plots for reports or
+   publications.
+
 Download processed videos
 -------------------------
 
@@ -58,3 +83,13 @@ Download processed videos
    )
 
 The files are saved as MP4 (one per data ID) and mirror what you see in the UI.
+
+.. caution::
+
+   Downloaded videos can be large. Ensure you have sufficient disk space and
+   consider filtering to only the IDs you need.
+
+.. seealso::
+
+   - :doc:`poll-timeseries` – Poll for live timeseries updates
+   - :doc:`poll-trajectory` – Poll similarity trajectory data

{atomscale-0.8.3 → atomscale-0.9.0}/docs/guides/poll-timeseries.rst

@@ -14,6 +14,12 @@ analysis. This guide summarises the four helper entry points in
 - **Async background task** with :func:`start_polling_task` – fire-and-forget
   inside an asyncio application.
 
+.. tip::
+
+   For similarity trajectory data that tracks structure-property relationships,
+   see :doc:`poll-trajectory` instead. That API auto-stops when the trajectory
+   completes.
+
 Shared setup
 ------------
 
@@ -41,9 +47,7 @@ Synchronous polling
 
 Loop over :func:`iter_poll` to fetch fresh rows on a fixed cadence. The helper
 waits ``interval`` seconds between polls so a simple ``for`` loop is enough to
-keep the script going. Use ``distinct_by`` to avoid duplicates,
-``max_polls`` to stop automatically, and ``fire_immediately=False`` to skip the
-first immediate request if you only want timed polls.
+keep the script going.
 
 .. code-block:: python
 
@@ -61,13 +65,19 @@ first immediate request if you only want timed polls.
        print(f"Poll {idx}: latest timestamp -> {latest_timestamp(result)}")
        print(result.tail())
 
+.. note::
+
+   The iterator uses **drift-corrected scheduling** to maintain accurate timing
+   even when individual polls are slow. Use ``distinct_by`` to avoid processing
+   duplicate data, and ``fire_immediately=False`` to skip the initial poll.
+
 Background thread helper
 ------------------------
 
 Use :func:`start_polling_thread` when you want updates but cannot block the
 main thread (for example, inside a GUI or acquisition loop). The helper spawns
 a daemon thread, starts polling immediately, and forwards each update to your
-callback. Call ``stop_event.set()`` to shut it down cleanly.
+callback.
 
 .. code-block:: python
 
@@ -91,6 +101,11 @@ callback. Call ``stop_event.set()`` to shut it down cleanly.
 
    # Call stop_event.set() to terminate early.
 
+.. caution::
+
+   The callback runs in the polling thread, not the main thread. If you need to
+   update UI elements, use thread-safe mechanisms (e.g., ``queue.Queue``).
+
 Async utilities
 ---------------
 
@@ -101,6 +116,8 @@ Two helpers integrate with asyncio:
 * :func:`start_polling_task` creates a background task that awaits the poller
   in parallel and invokes an (optional) async handler for each result.
 
+**Async iterator**
+
 .. code-block:: python
 
    import asyncio
@@ -121,6 +138,8 @@ Two helpers integrate with asyncio:
 
    asyncio.run(stream_updates())
 
+**Background task**
+
 .. code-block:: python
 
    async def handle_async(result):
@@ -141,3 +160,7 @@ Two helpers integrate with asyncio:
 
 
    asyncio.run(main())
+
+.. tip::
+
+   Cancel the task with ``task.cancel()`` to stop polling early in async code.

atomscale-0.9.0/docs/guides/poll-trajectory.rst

@@ -0,0 +1,219 @@
+Poll Similarity Trajectory
+==========================
+
+This guide covers the polling helpers in :mod:`atomscale.similarity.polling` for
+monitoring similarity trajectory data. These functions mirror the timeseries
+polling API but are tailored for trajectory workflows:
+
+- **Manual loop** with :func:`iter_poll_trajectory` – ideal for scripts that can
+  block until each poll finishes.
+- **Background thread** with :func:`start_polling_trajectory_thread` – keeps
+  polling while your main thread keeps working.
+- **Async iterator** with :func:`aiter_poll_trajectory` – awaits each update
+  inside an async function.
+- **Async background task** with :func:`start_polling_trajectory_task` –
+  fire-and-forget inside an asyncio application.
+
+.. tip::
+
+   If you're polling generic timeseries data (e.g., RHEED intensity), see
+   :doc:`poll-timeseries` instead. Use this guide for similarity trajectory
+   workflows that track structure-property relationships across experiments.
+
+Key differences from timeseries polling
+---------------------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 35 35
+
+   * - Feature
+     - Timeseries polling
+     - Trajectory polling
+   * - Identifier
+     - ``data_id``
+     - ``source_id`` (data_id or physical_sample_id)
+   * - Stop condition
+     - Manual (``max_polls`` or custom ``until``)
+     - Auto-stops when ``Active`` is ``False``
+   * - Return format
+     - DataFrame with timeseries data
+     - DataFrame with ``Active`` column
+
+.. important::
+
+   **Default stop condition**: Polling stops automatically when no trajectory is
+   active (``not df["Active"].any()``). Override this behavior with the ``until``
+   parameter if you need custom termination logic.
+
+Shared setup
+------------
+
+.. code-block:: python
+
+   from atomscale.client import Client
+   from atomscale.similarity.polling import (
+       iter_poll_trajectory,
+       aiter_poll_trajectory,
+       start_polling_trajectory_thread,
+       start_polling_trajectory_task,
+   )
+
+   client = Client(api_key="YOUR_API_KEY")
+   source_id = "YOUR_SOURCE_ID"  # data_id or physical_sample_id
+
+Synchronous polling
+-------------------
+
+Loop over :func:`iter_poll_trajectory` to fetch trajectory updates on a fixed
+cadence. Polling stops automatically when the trajectory is no longer active,
+or you can set ``max_polls`` to limit iterations.
+
+.. code-block:: python
+
+   for idx, result in enumerate(
+       iter_poll_trajectory(
+           client,
+           source_id=source_id,
+           interval=5.0,
+           last_n=10,
+           max_polls=10,
+       ),
+       start=1,
+   ):
+       print(f"Poll {idx}: {len(result)} rows, active={result['Active'].any()}")
+       print(result.tail())
+
+.. note::
+
+   The iterator uses **drift-corrected scheduling** to maintain accurate timing
+   even when individual polls are slow.
+
+Background thread helper
+------------------------
+
+Use :func:`start_polling_trajectory_thread` when you want updates but cannot
+block the main thread (e.g., inside a GUI or acquisition loop). The helper
+spawns a daemon thread and forwards each update to your callback.
+
+.. code-block:: python
+
+   collected = []
+
+
+   def on_result(result):
+       print(f"Thread received {len(result)} rows")
+       collected.append(result)
+
+
+   stop_event = start_polling_trajectory_thread(
+       client,
+       source_id=source_id,
+       interval=10.0,
+       last_n=10,
+       on_result=on_result,
+   )
+
+   # Polling stops automatically when trajectory is inactive.
+   # Call stop_event.set() to terminate early.
+
+.. caution::
+
+   The callback runs in the polling thread, not the main thread. If you need to
+   update UI elements, use thread-safe mechanisms (e.g., ``queue.Queue``).
+
+Async utilities
+---------------
+
+Two helpers integrate with asyncio:
+
+* :func:`aiter_poll_trajectory` yields results without blocking the event loop.
+* :func:`start_polling_trajectory_task` creates a background task that invokes
+  an (optional) async handler for each result.
+
+**Async iterator**
+
+.. code-block:: python
+
+   import asyncio
+
+
+   async def stream_updates():
+       async for result in aiter_poll_trajectory(
+           client,
+           source_id=source_id,
+           interval=5.0,
+           last_n=10,
+       ):
+           print(f"Async poll received {len(result)} rows")
+           if not result["Active"].any():
+               print("Trajectory complete")
+
+
+   asyncio.run(stream_updates())
+
+**Background task**
+
+.. code-block:: python
+
+   async def handle_async(result):
+       print(f"Task handler received {len(result)} rows")
+
+
+   async def main():
+       task = start_polling_trajectory_task(
+           client,
+           source_id=source_id,
+           interval=5.0,
+           last_n=5,
+           on_result=handle_async,
+       )
+       await task
+
+
+   asyncio.run(main())
+
+.. tip::
+
+   Cancel the task with ``task.cancel()`` to stop polling early in async code.
+
+Custom stop conditions
+----------------------
+
+Override the default stop condition with the ``until`` parameter:
+
+.. code-block:: python
+
+   # Stop after receiving at least 100 data points
+   for result in iter_poll_trajectory(
+       client,
+       source_id=source_id,
+       interval=5.0,
+       until=lambda df: len(df) >= 100,
+   ):
+       print(f"Received {len(result)} rows")
+
+Error handling
+--------------
+
+Use the ``on_error`` callback to handle transient failures without stopping the
+poll loop:
+
+.. code-block:: python
+
+   def handle_error(exc):
+       print(f"Poll failed: {exc}, retrying...")
+
+
+   for result in iter_poll_trajectory(
+       client,
+       source_id=source_id,
+       interval=5.0,
+       on_error=handle_error,
+   ):
+       print(f"Received {len(result)} rows")
+
+.. warning::
+
+   Errors are swallowed when ``on_error`` is provided. If you need to fail fast,
+   omit the callback and handle exceptions in your loop.

{atomscale-0.8.3 → atomscale-0.9.0}/docs/guides/quickstart.rst

@@ -7,9 +7,13 @@ for calling the Atomscale API.
 Prerequisites
 -------------
 
-- Python 3.10 or newer
-- An active Atomscale account
-- An API key from the Atomscale web app (Profile → Account Management)
+.. important::
+
+   Before you begin, make sure you have:
+
+   - Python 3.10 or newer
+   - An active Atomscale account
+   - An API key from the Atomscale web app (Profile → Account Management)
 
 Install the client
 ------------------
@@ -34,7 +38,12 @@ explicitly if you prefer.
 
    client = Client()
 
-Override the endpoint when pointing at staging or a private deployment.
+.. tip::
+
+   Set ``AS_API_KEY`` in your shell profile (e.g., ``.bashrc`` or ``.zshrc``)
+   to avoid hardcoding credentials in scripts.
+
+Override the endpoint when pointing at staging or a private deployment:
 
 .. code-block:: python
 
@@ -43,9 +52,16 @@ Override the endpoint when pointing at staging or a private deployment.
        endpoint="https://api.atomscale.ai/",
    )
 
+.. warning::
+
+   Never commit API keys to version control. Use environment variables or a
+   secrets manager instead.
+
 Next steps
 ----------
 
-- Upload files with :doc:`upload-data`
-- Find items in the catalogue with :doc:`search-data`
-- Explore results and plots with :doc:`inspect-results`
+.. seealso::
+
+   - :doc:`upload-data` – Upload RHEED videos, images, or XPS files
+   - :doc:`search-data` – Find items in the catalogue
+   - :doc:`inspect-results` – Explore results and plots