atomscale 0.19.0__tar.gz → 0.20.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. {atomscale-0.19.0/src/atomscale.egg-info → atomscale-0.20.0}/PKG-INFO +1 -1
  2. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/client.py +173 -0
  3. atomscale-0.20.0/src/atomscale/rheed_metadata.py +127 -0
  4. atomscale-0.20.0/src/atomscale/samples.py +292 -0
  5. {atomscale-0.19.0 → atomscale-0.20.0/src/atomscale.egg-info}/PKG-INFO +1 -1
  6. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale.egg-info/SOURCES.txt +3 -0
  7. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale.egg-info/scm_file_list.json +3 -0
  8. atomscale-0.20.0/src/atomscale.egg-info/scm_version.json +8 -0
  9. atomscale-0.20.0/tests/test_samples.py +421 -0
  10. atomscale-0.19.0/src/atomscale.egg-info/scm_version.json +0 -8
  11. {atomscale-0.19.0 → atomscale-0.20.0}/.github/workflows/release.yml +0 -0
  12. {atomscale-0.19.0 → atomscale-0.20.0}/.github/workflows/testing.yml +0 -0
  13. {atomscale-0.19.0 → atomscale-0.20.0}/.github/workflows/upgrade_dependencies.yml +0 -0
  14. {atomscale-0.19.0 → atomscale-0.20.0}/.gitignore +0 -0
  15. {atomscale-0.19.0 → atomscale-0.20.0}/.pre-commit-config.yaml +0 -0
  16. {atomscale-0.19.0 → atomscale-0.20.0}/CHANGELOG.md +0 -0
  17. {atomscale-0.19.0 → atomscale-0.20.0}/LICENSE +0 -0
  18. {atomscale-0.19.0 → atomscale-0.20.0}/MANIFEST.in +0 -0
  19. {atomscale-0.19.0 → atomscale-0.20.0}/README.md +0 -0
  20. {atomscale-0.19.0 → atomscale-0.20.0}/atomicds-shim-dist/pyproject.toml +0 -0
  21. {atomscale-0.19.0 → atomscale-0.20.0}/docs/Makefile +0 -0
  22. {atomscale-0.19.0 → atomscale-0.20.0}/docs/_static/AtomscaleLogoFull.png +0 -0
  23. {atomscale-0.19.0 → atomscale-0.20.0}/docs/_static/custom.css +0 -0
  24. {atomscale-0.19.0 → atomscale-0.20.0}/docs/_templates/custom-class-template.rst +0 -0
  25. {atomscale-0.19.0 → atomscale-0.20.0}/docs/_templates/custom-module-template.rst +0 -0
  26. {atomscale-0.19.0 → atomscale-0.20.0}/docs/conf.py +0 -0
  27. {atomscale-0.19.0 → atomscale-0.20.0}/docs/guides/analysis-results.rst +0 -0
  28. {atomscale-0.19.0 → atomscale-0.20.0}/docs/guides/monitor-live.rst +0 -0
  29. {atomscale-0.19.0 → atomscale-0.20.0}/docs/guides/quickstart.rst +0 -0
  30. {atomscale-0.19.0 → atomscale-0.20.0}/docs/guides/search-and-download.rst +0 -0
  31. {atomscale-0.19.0 → atomscale-0.20.0}/docs/guides/stream-rheed.rst +0 -0
  32. {atomscale-0.19.0 → atomscale-0.20.0}/docs/guides/stream-timeseries.rst +0 -0
  33. {atomscale-0.19.0 → atomscale-0.20.0}/docs/guides/upload-files.rst +0 -0
  34. {atomscale-0.19.0 → atomscale-0.20.0}/docs/index.rst +0 -0
  35. {atomscale-0.19.0 → atomscale-0.20.0}/docs/make.bat +0 -0
  36. {atomscale-0.19.0 → atomscale-0.20.0}/docs/modules.rst +0 -0
  37. {atomscale-0.19.0 → atomscale-0.20.0}/examples/changepoints.ipynb +0 -0
  38. {atomscale-0.19.0 → atomscale-0.20.0}/examples/general_use.ipynb +0 -0
  39. {atomscale-0.19.0 → atomscale-0.20.0}/examples/rheed_streaming.ipynb +0 -0
  40. {atomscale-0.19.0 → atomscale-0.20.0}/examples/timeseries_polling.ipynb +0 -0
  41. {atomscale-0.19.0 → atomscale-0.20.0}/examples/vxwse2-placeholder/task1_films.ipynb +0 -0
  42. {atomscale-0.19.0 → atomscale-0.20.0}/examples/vxwse2-placeholder/task1_sapphire.ipynb +0 -0
  43. {atomscale-0.19.0 → atomscale-0.20.0}/examples/vxwse2-placeholder/task2_composition.ipynb +0 -0
  44. {atomscale-0.19.0 → atomscale-0.20.0}/pyproject.toml +0 -0
  45. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.10.txt +0 -0
  46. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.10_extras.txt +0 -0
  47. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.11.txt +0 -0
  48. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.11_extras.txt +0 -0
  49. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.12.txt +0 -0
  50. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.12_extras.txt +0 -0
  51. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.13.txt +0 -0
  52. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.13_extras.txt +0 -0
  53. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.10.txt +0 -0
  54. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.10_extras.txt +0 -0
  55. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.11.txt +0 -0
  56. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.11_extras.txt +0 -0
  57. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.12.txt +0 -0
  58. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.12_extras.txt +0 -0
  59. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.13.txt +0 -0
  60. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.13_extras.txt +0 -0
  61. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.10.txt +0 -0
  62. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.10_extras.txt +0 -0
  63. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.11.txt +0 -0
  64. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.11_extras.txt +0 -0
  65. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.12.txt +0 -0
  66. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.12_extras.txt +0 -0
  67. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.13.txt +0 -0
  68. {atomscale-0.19.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.13_extras.txt +0 -0
  69. {atomscale-0.19.0 → atomscale-0.20.0}/scripts/ci_auth_preflight.py +0 -0
  70. {atomscale-0.19.0 → atomscale-0.20.0}/setup.cfg +0 -0
  71. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomicds/__init__.py +0 -0
  72. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/__init__.py +0 -0
  73. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/core/__init__.py +0 -0
  74. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/core/client.py +0 -0
  75. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/core/files.py +0 -0
  76. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/core/utils.py +0 -0
  77. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/__init__.py +0 -0
  78. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/changepoint.py +0 -0
  79. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/ellipsometry.py +0 -0
  80. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/embeddings.py +0 -0
  81. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/group.py +0 -0
  82. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/metrology.py +0 -0
  83. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/optical.py +0 -0
  84. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/photoluminescence.py +0 -0
  85. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/raman.py +0 -0
  86. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/recipe.py +0 -0
  87. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/rheed_image.py +0 -0
  88. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/rheed_video.py +0 -0
  89. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/similarity_trajectory.py +0 -0
  90. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/tool_state.py +0 -0
  91. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/unknown.py +0 -0
  92. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/xps.py +0 -0
  93. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/results/xrd.py +0 -0
  94. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/similarity/__init__.py +0 -0
  95. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/similarity/embedding_provider.py +0 -0
  96. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/similarity/polling.py +0 -0
  97. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/similarity/provider.py +0 -0
  98. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/streaming/Cargo.lock +0 -0
  99. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/streaming/Cargo.toml +0 -0
  100. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/streaming/__init__.py +0 -0
  101. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/streaming/rheed_stream.py +0 -0
  102. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/streaming/rheed_stream.pyi +0 -0
  103. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/streaming/src/initialize.rs +0 -0
  104. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/streaming/src/lib.rs +0 -0
  105. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/streaming/src/timeseries.rs +0 -0
  106. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/streaming/src/upload.rs +0 -0
  107. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/streaming/src/utils.rs +0 -0
  108. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/__init__.py +0 -0
  109. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/_polling_utils.py +0 -0
  110. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/align.py +0 -0
  111. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/ellipsometry.py +0 -0
  112. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/metrology.py +0 -0
  113. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/optical.py +0 -0
  114. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/physical_sample.py +0 -0
  115. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/polling.py +0 -0
  116. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/provider.py +0 -0
  117. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/recipe.py +0 -0
  118. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/registry.py +0 -0
  119. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/rheed.py +0 -0
  120. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/sample.py +0 -0
  121. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale/timeseries/tool_state.py +0 -0
  122. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale.egg-info/dependency_links.txt +0 -0
  123. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale.egg-info/requires.txt +0 -0
  124. {atomscale-0.19.0 → atomscale-0.20.0}/src/atomscale.egg-info/top_level.txt +0 -0
  125. {atomscale-0.19.0 → atomscale-0.20.0}/tests/__init__.py +0 -0
  126. {atomscale-0.19.0 → atomscale-0.20.0}/tests/_mock_http_server.py +0 -0
  127. {atomscale-0.19.0 → atomscale-0.20.0}/tests/conftest.py +0 -0
  128. {atomscale-0.19.0 → atomscale-0.20.0}/tests/data/test_rheed.mp4 +0 -0
  129. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_align.py +0 -0
  130. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_atomicds_alias.py +0 -0
  131. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_changepoint.py +0 -0
  132. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_client.py +0 -0
  133. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_core.py +0 -0
  134. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_ellipsometry.py +0 -0
  135. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_embeddings.py +0 -0
  136. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_metrology.py +0 -0
  137. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_optical.py +0 -0
  138. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_photoluminescence.py +0 -0
  139. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_physical_sample_timeseries.py +0 -0
  140. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_polling.py +0 -0
  141. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_raman.py +0 -0
  142. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_recipe.py +0 -0
  143. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_rheed_embedding.py +0 -0
  144. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_rheed_image.py +0 -0
  145. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_rheed_stream.py +0 -0
  146. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_rheed_timeseries.py +0 -0
  147. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_rheed_video.py +0 -0
  148. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_similarity_matches.py +0 -0
  149. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_similarity_trajectory.py +0 -0
  150. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_timeseries_stream.py +0 -0
  151. {atomscale-0.19.0 → atomscale-0.20.0}/tests/test_xps.py +0 -0
  152. {atomscale-0.19.0 → atomscale-0.20.0}/uv.lock +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: atomscale
3
- Version: 0.19.0
3
+ Version: 0.20.0
4
4
  Summary: Python SDK for Atomscale.
5
5
  Author-email: Atomscale <info@atomscale.ai>
6
6
  License: GPL-3.0-only
@@ -40,6 +40,13 @@ from atomscale.results import (
40
40
  decode_mask_rle,
41
41
  )
42
42
  from atomscale.results.group import PhysicalSampleResult, ProjectResult
43
+ from atomscale.rheed_metadata import rheed_azimuths_to_dataframe
44
+ from atomscale.samples import (
45
+ ai_summaries_to_dataframe,
46
+ ai_summary_row,
47
+ process_steps_to_dataframe,
48
+ spatial_annotations_to_dataframe,
49
+ )
43
50
  from atomscale.timeseries.align import align_timeseries
44
51
  from atomscale.timeseries.physical_sample import (
45
52
  physical_sample_timeseries_to_dataframe,
@@ -720,6 +727,39 @@ class Client(BaseClient):
720
727
  ts_df = provider.attach_frame_masks(ts_df, mask_rows) # type: ignore[arg-type]
721
728
  return ts_df
722
729
 
730
+ def get_rheed_azimuths(self, data_ids: str | list[str]) -> DataFrame:
731
+ """Per-azimuth metadata for rotating RHEED recordings.
732
+
733
+ For each seed frame of a rotating video this returns both the rotation
734
+ angle it sits at and the crystallographic azimuth the production
735
+ classifier assigned it. The angle depends on where the substrate happened
736
+ to be parked, so the same azimuth appears at different angles in different
737
+ recordings of one sample; the label is the stable identity, and so the
738
+ right key for aligning or concatenating series across recordings.
739
+
740
+ Args:
741
+ data_ids: Data ID or list of data IDs of rotating RHEED videos.
742
+
743
+ Returns:
744
+ DataFrame: One row per (data item, seed frame) with columns
745
+ ``data_id``, ``seed_frame``, ``angle_degrees``, ``azimuth_label``
746
+ (``"100"`` / ``"110"`` / ``"210"``, or ``None`` when the classifier
747
+ could not call it), ``label_confidence``, ``crystal_system`` and
748
+ ``surface_miller``. Data items with no rotating configuration
749
+ contribute no rows.
750
+ """
751
+ if isinstance(data_ids, str):
752
+ data_ids = [data_ids]
753
+
754
+ payload = self._get(
755
+ sub_url="configuration/rheed/video/", params={"data_ids": data_ids}
756
+ )
757
+ if payload is None:
758
+ return rheed_azimuths_to_dataframe([])
759
+ return rheed_azimuths_to_dataframe(
760
+ payload if isinstance(payload, list) else [payload]
761
+ )
762
+
723
763
  def get_frame(
724
764
  self,
725
765
  data_id: str,
@@ -1207,6 +1247,139 @@ class Client(BaseClient):
1207
1247
  raw, property_names=property_names
1208
1248
  )
1209
1249
 
1250
+ def get_process_steps(self, physical_sample_id: str) -> DataFrame:
1251
+ """The physical sample's process steps — its temporal phases.
1252
+
1253
+ A step groups the data items whose acquisition windows cluster together,
1254
+ so one sample's run splits into the phases it actually went through
1255
+ (e.g. a substrate anneal, then a growth, then a cooldown). Steps are the
1256
+ natural scope for a per-run report: the newest step is "this run", and
1257
+ the earlier ones are its history.
1258
+
1259
+ Args:
1260
+ physical_sample_id: Identifier of the physical sample.
1261
+
1262
+ Returns:
1263
+ DataFrame: One row per step ordered by ``step_index``, with columns
1264
+ ``step_index``, ``process_step_id``, ``name`` (the human/material
1265
+ label, ``None`` until set), ``start_unix_ms_utc`` /
1266
+ ``end_unix_ms_utc``, ``duration_seconds``, the tz-aware
1267
+ ``start_datetime`` / ``end_datetime``, ``n_data_ids``, ``data_ids``
1268
+ (tuple of the step's data items), and ``last_updated``. A sample
1269
+ whose steps have never been computed yields an empty DataFrame.
1270
+
1271
+ Raises:
1272
+ ClientError: If the physical sample does not exist (404).
1273
+ """
1274
+ raw = self._get(sub_url=f"physical_samples/{physical_sample_id}/process_steps")
1275
+ if raw is None:
1276
+ raise ClientError(
1277
+ f"No physical sample found with id '{physical_sample_id}' "
1278
+ "(physical_samples/{id}/process_steps returned 404).",
1279
+ status_code=404,
1280
+ )
1281
+ return process_steps_to_dataframe(raw) # type: ignore[arg-type]
1282
+
1283
+ def get_spatial_annotations(
1284
+ self,
1285
+ physical_sample_id: str,
1286
+ *,
1287
+ property_name: str | None = None,
1288
+ char_source_type: str | None = None,
1289
+ x_range: tuple[float | None, float | None] = (None, None),
1290
+ y_range: tuple[float | None, float | None] = (None, None),
1291
+ ) -> DataFrame:
1292
+ """Spatially-resolved property values pinned to a sample's surface.
1293
+
1294
+ Each annotation is one property measured at one position on the sample —
1295
+ an XPS composition ratio stepped across a wafer, a thickness from a
1296
+ mapped ellipsometry scan — which is what a spatial (wafer-map) view of a
1297
+ run is built from.
1298
+
1299
+ Args:
1300
+ physical_sample_id: Identifier of the physical sample.
1301
+ property_name: Restrict to a single property, e.g. ``"sr_ti_ratio"``.
1302
+ char_source_type: Restrict to the technique that produced the values,
1303
+ e.g. ``"xps"``.
1304
+ x_range: Inclusive ``(min, max)`` bounding-box filter on ``coord_x``.
1305
+ The endpoint applies a coordinate filter only when *both* bounds
1306
+ are given, so a half-open range is ignored server-side.
1307
+ y_range: Inclusive ``(min, max)`` bounding-box filter on ``coord_y``,
1308
+ with the same both-bounds requirement as ``x_range``.
1309
+
1310
+ Returns:
1311
+ DataFrame: One row per annotated point with columns
1312
+ ``annotation_id``, ``data_id``, ``char_source_type``,
1313
+ ``property_name``, ``property_value``, ``property_unit``,
1314
+ ``coord_x`` / ``coord_y`` / ``coord_z``, ``coord_ref_frame``,
1315
+ ``coord_units``, ``metadata``, and ``last_updated``. Sorted by
1316
+ property then position. A sample with no annotations — or a filter
1317
+ that matches none — yields an empty DataFrame.
1318
+
1319
+ Raises:
1320
+ ClientError: If the physical sample does not exist (404).
1321
+ """
1322
+ raw = self._get(
1323
+ sub_url=f"physical_samples/{physical_sample_id}/annotations/",
1324
+ params={
1325
+ "property_name": property_name,
1326
+ "char_source_type": char_source_type,
1327
+ "x_min": x_range[0],
1328
+ "x_max": x_range[1],
1329
+ "y_min": y_range[0],
1330
+ "y_max": y_range[1],
1331
+ },
1332
+ )
1333
+ # An existing sample with no annotations returns ``[]``, which ``_get``
1334
+ # hands back as an empty list; only a missing sample 404s to ``None``.
1335
+ if raw is None:
1336
+ raise ClientError(
1337
+ f"No physical sample found with id '{physical_sample_id}' "
1338
+ "(physical_samples/{id}/annotations/ returned 404).",
1339
+ status_code=404,
1340
+ )
1341
+ return spatial_annotations_to_dataframe(raw) # type: ignore[arg-type]
1342
+
1343
+ def get_ai_summaries(self, data_ids: str | list[str]) -> DataFrame:
1344
+ """Agent-written summaries for one or more data items.
1345
+
1346
+ The summary is generated asynchronously, so every requested data id gets
1347
+ a row carrying its ``task_status``: ``"available"`` when a summary
1348
+ exists, ``"pending"`` while the summarization workflow is still running,
1349
+ and ``"not_found"`` when neither is true. That makes an un-summarized
1350
+ item visible to a caller rendering a report rather than silently absent.
1351
+
1352
+ Args:
1353
+ data_ids: Data ID or list of data IDs from the data catalogue.
1354
+
1355
+ Returns:
1356
+ DataFrame: One row per requested data id, in request order, with
1357
+ columns ``data_id``, ``task_status``, ``summary_id``, ``content``
1358
+ (the prose summary), ``structured_content`` (the agent's full
1359
+ structured output), ``generation_model``, ``generation_timestamp``,
1360
+ ``user_feedback``, and ``workflow_id``. Summary-note columns are
1361
+ ``None`` for rows whose status is not ``"available"``.
1362
+ """
1363
+ if isinstance(data_ids, str):
1364
+ data_ids = [data_ids]
1365
+
1366
+ # The endpoint is per-data-item, so fan the requests out rather than
1367
+ # walking them serially.
1368
+ with _make_progress(self.mute_bars, False) as progress:
1369
+ payloads = self._multi_thread(
1370
+ lambda data_id: self._get(sub_url=f"summary/{data_id}"),
1371
+ [{"data_id": data_id} for data_id in data_ids],
1372
+ progress,
1373
+ progress_description="Obtaining AI summaries",
1374
+ )
1375
+
1376
+ return ai_summaries_to_dataframe(
1377
+ [
1378
+ ai_summary_row(data_id, payload)
1379
+ for data_id, payload in zip(data_ids, payloads, strict=True)
1380
+ ]
1381
+ )
1382
+
1210
1383
  def get_project(
1211
1384
  self,
1212
1385
  project_id: str,
@@ -0,0 +1,127 @@
1
+ """Parse per-azimuth RHEED metadata for a rotating-substrate recording.
2
+
3
+ ``GET /configuration/rheed/video/`` carries, for each seed frame of a rotating
4
+ video, both the rotation angle the frame sits at (``seed_frame_angles``) and the
5
+ crystallographic azimuth the production classifier assigned it
6
+ (``api_configuration.azimuth_labels`` — one of ``"100"`` / ``"110"`` / ``"210"``,
7
+ or ``None`` when it could not be called), plus the fit detail behind that call in
8
+ ``azimuth_label_meta``.
9
+
10
+ The distinction matters when comparing recordings: the rotation angle is a
11
+ property of how the substrate happened to be parked, so the *same* azimuth turns
12
+ up at different angles in different recordings of the same sample. The
13
+ crystallographic label is the stable identity, and therefore the correct key for
14
+ aligning or concatenating series across recordings.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ from collections.abc import Mapping, Sequence
20
+ from typing import Any
21
+
22
+ import pandas as pd
23
+ from pandas import DataFrame
24
+
25
+ # One row per (data item, seed frame).
26
+ RHEED_AZIMUTH_COLUMNS: tuple[str, ...] = (
27
+ "data_id",
28
+ "seed_frame",
29
+ "angle_degrees",
30
+ "azimuth_label",
31
+ "label_confidence",
32
+ "crystal_system",
33
+ "surface_miller",
34
+ )
35
+
36
+
37
+ def _empty() -> DataFrame:
38
+ frame = DataFrame({c: [] for c in RHEED_AZIMUTH_COLUMNS})
39
+ frame["seed_frame"] = frame["seed_frame"].astype("int64")
40
+ frame["angle_degrees"] = frame["angle_degrees"].astype("float64")
41
+ frame["label_confidence"] = frame["label_confidence"].astype("float64")
42
+ return frame
43
+
44
+
45
+ def rheed_azimuths_to_dataframe(payload: Sequence[Mapping[str, Any]]) -> DataFrame:
46
+ """Convert a ``list[RheedVideoConfigurationResponse]`` to one row per azimuth.
47
+
48
+ Args:
49
+ payload: Decoded response body — one entry per requested data id, each
50
+ with ``data_id``, ``seed_frame_angles`` (seed frame -> degrees) and an
51
+ ``api_configuration`` carrying ``azimuth_labels`` (seed frame ->
52
+ label) and ``azimuth_label_meta`` (seed frame -> fit detail).
53
+
54
+ Returns:
55
+ DataFrame: The columns in :data:`RHEED_AZIMUTH_COLUMNS`, sorted by
56
+ ``data_id`` then ``seed_frame``. ``azimuth_label`` is ``None`` for a seed
57
+ frame the classifier could not label, so callers can fall back to the
58
+ angle rather than inventing an identity. Non-rotating or unconfigured
59
+ entries contribute no rows; an empty payload yields an empty frame.
60
+ """
61
+ rows: list[dict[str, Any]] = []
62
+ for entry in payload or []:
63
+ data_id = entry.get("data_id")
64
+ angles = entry.get("seed_frame_angles") or {}
65
+ api_configuration = entry.get("api_configuration") or {}
66
+ labels = api_configuration.get("azimuth_labels") or {}
67
+ meta = api_configuration.get("azimuth_label_meta") or {}
68
+
69
+ # Seed frames come from the angle map: it is the endpoint's own record of
70
+ # which frames this recording actually has, whereas the label map may be
71
+ # partial (an unlabelled azimuth is simply absent).
72
+ for seed_frame, angle in angles.items():
73
+ detail = meta.get(seed_frame) or {}
74
+ surface = detail.get("surface")
75
+ rows.append(
76
+ {
77
+ "data_id": str(data_id),
78
+ "seed_frame": int(seed_frame),
79
+ "angle_degrees": float(angle)
80
+ if angle is not None
81
+ else float("nan"),
82
+ "azimuth_label": labels.get(seed_frame),
83
+ "label_confidence": (
84
+ float(detail["confidence"])
85
+ if detail.get("confidence") is not None
86
+ else float("nan")
87
+ ),
88
+ "crystal_system": detail.get("system"),
89
+ # A Miller index arrives as a list; join it so the column stays
90
+ # scalar and groupable.
91
+ "surface_miller": (
92
+ "".join(str(_i) for _i in surface)
93
+ if isinstance(surface, list | tuple)
94
+ else surface
95
+ ),
96
+ }
97
+ )
98
+
99
+ if not rows:
100
+ return _empty()
101
+
102
+ return (
103
+ DataFrame(rows)[list(RHEED_AZIMUTH_COLUMNS)]
104
+ .sort_values(["data_id", "seed_frame"], kind="stable")
105
+ .reset_index(drop=True)
106
+ )
107
+
108
+
109
+ def azimuth_label_by_seed_frame(
110
+ azimuths: DataFrame, data_id: str
111
+ ) -> dict[int, str | None]:
112
+ """``{seed_frame: azimuth_label}`` for one data item, for joining onto series.
113
+
114
+ Args:
115
+ azimuths: A frame from :func:`rheed_azimuths_to_dataframe`.
116
+ data_id: The data item to select.
117
+
118
+ Returns:
119
+ dict: Seed frame -> label, including seed frames whose label is ``None``.
120
+ """
121
+ if not len(azimuths):
122
+ return {}
123
+ mine = azimuths[azimuths["data_id"].astype(str) == str(data_id)]
124
+ return {
125
+ int(row.seed_frame): (None if pd.isna(row.azimuth_label) else row.azimuth_label)
126
+ for row in mine.itertuples()
127
+ }
@@ -0,0 +1,292 @@
1
+ """Parse the sample-scoped payloads that are *not* timeseries.
2
+
3
+ Three read endpoints describe a physical sample without returning a series:
4
+
5
+ * ``GET /physical_samples/{id}/process_steps`` — the sample's temporal phases
6
+ (one growth/anneal/cooldown segment each), derived by clustering its data
7
+ items' acquisition windows.
8
+ * ``GET /physical_samples/{id}/annotations/`` — spatially-resolved property
9
+ values pinned to surface coordinates (e.g. an XPS ``sr_ti_ratio`` measured
10
+ every 22.5 mm across a wafer).
11
+ * ``GET /summary/{data_id}`` — the agent-written summary of one data item,
12
+ together with the status of the summarization workflow.
13
+
14
+ Each helper converts one decoded response body into a flat DataFrame. Sample
15
+ timeseries live in :mod:`atomscale.timeseries.physical_sample` instead; these
16
+ payloads are metadata and event records, so they share no axis and are kept
17
+ apart.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ from collections.abc import Mapping, Sequence
23
+ from typing import Any
24
+
25
+ import pandas as pd
26
+ from pandas import DataFrame
27
+
28
+ # Process steps: one row per step, ordered by ``step_index``.
29
+ #
30
+ # ``data_ids`` stays in-frame as a tuple rather than moving to ``DataFrame.attrs``
31
+ # (the convention :mod:`atomscale.timeseries.physical_sample` uses for its
32
+ # provenance ids) because step membership *is* the payload here — callers fetch
33
+ # steps precisely to learn which data items belong to which phase — and a step
34
+ # with no members has to survive as a row.
35
+ PROCESS_STEP_COLUMNS: tuple[str, ...] = (
36
+ "step_index",
37
+ "process_step_id",
38
+ "name",
39
+ "start_unix_ms_utc",
40
+ "end_unix_ms_utc",
41
+ "duration_seconds",
42
+ "start_datetime",
43
+ "end_datetime",
44
+ "n_data_ids",
45
+ "data_ids",
46
+ "last_updated",
47
+ )
48
+
49
+ # Spatial annotations: one row per annotated point.
50
+ SPATIAL_ANNOTATION_COLUMNS: tuple[str, ...] = (
51
+ "annotation_id",
52
+ "data_id",
53
+ "char_source_type",
54
+ "property_name",
55
+ "property_value",
56
+ "property_unit",
57
+ "coord_x",
58
+ "coord_y",
59
+ "coord_z",
60
+ "coord_ref_frame",
61
+ "coord_units",
62
+ "metadata",
63
+ "last_updated",
64
+ )
65
+
66
+ # AI summaries: one row per *requested* data id, so a data item with no summary
67
+ # is visible as a ``task_status`` row rather than a missing row.
68
+ AI_SUMMARY_COLUMNS: tuple[str, ...] = (
69
+ "data_id",
70
+ "task_status",
71
+ "summary_id",
72
+ "content",
73
+ "structured_content",
74
+ "generation_model",
75
+ "generation_timestamp",
76
+ "user_feedback",
77
+ "workflow_id",
78
+ )
79
+
80
+ _FLOAT_COLUMNS: Mapping[str, tuple[str, ...]] = {
81
+ "process_steps": (
82
+ "start_unix_ms_utc",
83
+ "end_unix_ms_utc",
84
+ "duration_seconds",
85
+ ),
86
+ "annotations": ("property_value", "coord_x", "coord_y", "coord_z"),
87
+ }
88
+
89
+ # Absolute-timestamp columns per payload. Parsed with ``utc=True`` so offset-free
90
+ # values land tz-aware (UTC) rather than tz-naive, keeping them comparable with
91
+ # each other and with the UTC ``start_datetime`` / ``end_datetime`` bounds — a
92
+ # tz-naive column would raise on subtraction/comparison against a tz-aware one.
93
+ _DATETIME_COLUMNS: Mapping[str, tuple[str, ...]] = {
94
+ "process_steps": ("start_datetime", "end_datetime", "last_updated"),
95
+ "annotations": ("last_updated",),
96
+ "summaries": ("generation_timestamp",),
97
+ }
98
+
99
+
100
+ def _empty(
101
+ columns: Sequence[str],
102
+ float_columns: Sequence[str] = (),
103
+ datetime_columns: Sequence[str] = (),
104
+ ) -> DataFrame:
105
+ """Empty frame carrying the full column set, with typed float/datetime columns.
106
+
107
+ Datetime columns are typed tz-aware (UTC) so an empty return shares the dtype
108
+ the populated path produces (see :data:`_DATETIME_COLUMNS`).
109
+ """
110
+ frame = DataFrame({c: [] for c in columns})
111
+ for column in float_columns:
112
+ frame[column] = frame[column].astype("float64")
113
+ for column in datetime_columns:
114
+ frame[column] = frame[column].astype("datetime64[ns, UTC]")
115
+ return frame
116
+
117
+
118
+ def _as_float(value: Any) -> float:
119
+ """Coerce a JSON number (or ``None``) to ``float``, ``None`` -> ``NaN``."""
120
+ return float("nan") if value is None else float(value)
121
+
122
+
123
+ def process_steps_to_dataframe(payload: Mapping[str, Any]) -> DataFrame:
124
+ """Convert a ``ProcessStepsResponse`` payload to one row per process step.
125
+
126
+ Args:
127
+ payload: Decoded response body, with a ``"process_steps"`` list whose
128
+ entries carry ``id``, ``step_index``, ``name``,
129
+ ``start_unix_ms_utc`` / ``end_unix_ms_utc`` (float epoch
130
+ milliseconds, UTC), ``data_ids``, and ``last_updated``.
131
+
132
+ Returns:
133
+ DataFrame: The columns in :data:`PROCESS_STEP_COLUMNS`, sorted by
134
+ ``step_index``. ``duration_seconds`` and the tz-aware
135
+ ``start_datetime`` / ``end_datetime`` are derived from the epoch-ms
136
+ bounds for convenience; the raw bounds are kept so callers aligning
137
+ against absolute-time series (RHEED shutter times, tool state) never
138
+ have to round-trip through a datetime. A sample with no steps yields an
139
+ empty frame, never an error.
140
+ """
141
+ steps = list(payload.get("process_steps") or [])
142
+ if not steps:
143
+ return _empty(
144
+ PROCESS_STEP_COLUMNS,
145
+ _FLOAT_COLUMNS["process_steps"],
146
+ _DATETIME_COLUMNS["process_steps"],
147
+ )
148
+
149
+ rows = []
150
+ for step in steps:
151
+ start = _as_float(step.get("start_unix_ms_utc"))
152
+ end = _as_float(step.get("end_unix_ms_utc"))
153
+ data_ids = tuple(step.get("data_ids") or ())
154
+ rows.append(
155
+ {
156
+ "step_index": step.get("step_index"),
157
+ "process_step_id": step.get("id"),
158
+ "name": step.get("name"),
159
+ "start_unix_ms_utc": start,
160
+ "end_unix_ms_utc": end,
161
+ "duration_seconds": (end - start) / 1000.0,
162
+ "n_data_ids": len(data_ids),
163
+ "data_ids": data_ids,
164
+ "last_updated": step.get("last_updated"),
165
+ }
166
+ )
167
+
168
+ frame = DataFrame(rows)
169
+ frame["start_datetime"] = pd.to_datetime(
170
+ frame["start_unix_ms_utc"], unit="ms", utc=True
171
+ )
172
+ frame["end_datetime"] = pd.to_datetime(
173
+ frame["end_unix_ms_utc"], unit="ms", utc=True
174
+ )
175
+ frame["last_updated"] = pd.to_datetime(
176
+ frame["last_updated"], errors="coerce", utc=True
177
+ )
178
+ return (
179
+ frame[list(PROCESS_STEP_COLUMNS)]
180
+ .sort_values("step_index", kind="stable")
181
+ .reset_index(drop=True)
182
+ )
183
+
184
+
185
+ def spatial_annotations_to_dataframe(payload: Sequence[Mapping[str, Any]]) -> DataFrame:
186
+ """Convert a ``list[SpatialAnnotationRead]`` payload to one row per point.
187
+
188
+ Args:
189
+ payload: Decoded response body — a list of annotation objects, each with
190
+ ``id``, ``property_name``, ``property_value``, optional
191
+ ``property_unit`` / ``char_source_type`` / ``data_id``, the
192
+ ``coord_x`` / ``coord_y`` / ``coord_z`` surface position with its
193
+ ``coord_ref_frame`` and ``coord_units``, and ``metadata``.
194
+
195
+ Returns:
196
+ DataFrame: The columns in :data:`SPATIAL_ANNOTATION_COLUMNS`, sorted by
197
+ ``property_name`` then position so a scan reads left-to-right. The
198
+ server-side ``id`` is exposed as ``annotation_id`` to keep it distinct
199
+ from ``data_id``. No annotations yields an empty frame, never an error.
200
+ """
201
+ records = list(payload or [])
202
+ if not records:
203
+ return _empty(
204
+ SPATIAL_ANNOTATION_COLUMNS,
205
+ _FLOAT_COLUMNS["annotations"],
206
+ _DATETIME_COLUMNS["annotations"],
207
+ )
208
+
209
+ rows = [
210
+ {
211
+ "annotation_id": record.get("id"),
212
+ "data_id": record.get("data_id"),
213
+ "char_source_type": record.get("char_source_type"),
214
+ "property_name": record.get("property_name"),
215
+ "property_value": _as_float(record.get("property_value")),
216
+ "property_unit": record.get("property_unit"),
217
+ "coord_x": _as_float(record.get("coord_x")),
218
+ "coord_y": _as_float(record.get("coord_y")),
219
+ "coord_z": _as_float(record.get("coord_z")),
220
+ "coord_ref_frame": record.get("coord_ref_frame"),
221
+ "coord_units": record.get("coord_units"),
222
+ "metadata": record.get("metadata"),
223
+ "last_updated": record.get("last_updated"),
224
+ }
225
+ for record in records
226
+ ]
227
+
228
+ frame = DataFrame(rows)
229
+ frame["last_updated"] = pd.to_datetime(
230
+ frame["last_updated"], errors="coerce", utc=True
231
+ )
232
+ return (
233
+ frame[list(SPATIAL_ANNOTATION_COLUMNS)]
234
+ .sort_values(
235
+ ["property_name", "coord_x", "coord_y"], kind="stable", na_position="last"
236
+ )
237
+ .reset_index(drop=True)
238
+ )
239
+
240
+
241
+ def ai_summary_row(data_id: str, payload: Mapping[str, Any] | None) -> dict[str, Any]:
242
+ """Flatten one ``GetSummaryResponse`` into an :data:`AI_SUMMARY_COLUMNS` row.
243
+
244
+ Args:
245
+ data_id: The data id the response was fetched for; carried through so a
246
+ batch of rows stays attributable.
247
+ payload: Decoded response body with ``summary`` (the note, or ``None``),
248
+ ``task_status`` (``"available"`` / ``"pending"`` / ``"not_found"``),
249
+ and ``workflow_id``. ``None`` — a 404 from the endpoint — is
250
+ reported as ``task_status="not_found"``, matching how the endpoint
251
+ reports an un-summarized data item that does exist.
252
+
253
+ Returns:
254
+ dict: One flat row; summary-note fields are ``None`` unless the note is
255
+ present.
256
+ """
257
+ body = payload or {}
258
+ summary = body.get("summary") or {}
259
+ return {
260
+ "data_id": data_id,
261
+ "task_status": body.get("task_status") or "not_found",
262
+ "summary_id": summary.get("id"),
263
+ "content": summary.get("content"),
264
+ "structured_content": summary.get("structured_content"),
265
+ "generation_model": summary.get("generation_model"),
266
+ "generation_timestamp": summary.get("generation_timestamp"),
267
+ "user_feedback": summary.get("user_feedback"),
268
+ "workflow_id": body.get("workflow_id"),
269
+ }
270
+
271
+
272
+ def ai_summaries_to_dataframe(rows: Sequence[Mapping[str, Any]]) -> DataFrame:
273
+ """Assemble :func:`ai_summary_row` outputs into a frame.
274
+
275
+ Args:
276
+ rows: One row per requested data id, in the caller's request order.
277
+
278
+ Returns:
279
+ DataFrame: The columns in :data:`AI_SUMMARY_COLUMNS`, request order
280
+ preserved, with ``generation_timestamp`` parsed to datetime. An empty
281
+ ``rows`` yields an empty frame.
282
+ """
283
+ if not rows:
284
+ return _empty(
285
+ AI_SUMMARY_COLUMNS, datetime_columns=_DATETIME_COLUMNS["summaries"]
286
+ )
287
+
288
+ frame = DataFrame(list(rows))[list(AI_SUMMARY_COLUMNS)]
289
+ frame["generation_timestamp"] = pd.to_datetime(
290
+ frame["generation_timestamp"], errors="coerce", utc=True
291
+ )
292
+ return frame
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: atomscale
3
- Version: 0.19.0
3
+ Version: 0.20.0
4
4
  Summary: Python SDK for Atomscale.
5
5
  Author-email: Atomscale <info@atomscale.ai>
6
6
  License: GPL-3.0-only
@@ -61,6 +61,8 @@ scripts/ci_auth_preflight.py
61
61
  src/atomicds/__init__.py
62
62
  src/atomscale/__init__.py
63
63
  src/atomscale/client.py
64
+ src/atomscale/rheed_metadata.py
65
+ src/atomscale/samples.py
64
66
  src/atomscale.egg-info/PKG-INFO
65
67
  src/atomscale.egg-info/SOURCES.txt
66
68
  src/atomscale.egg-info/dependency_links.txt
@@ -139,6 +141,7 @@ tests/test_rheed_image.py
139
141
  tests/test_rheed_stream.py
140
142
  tests/test_rheed_timeseries.py
141
143
  tests/test_rheed_video.py
144
+ tests/test_samples.py
142
145
  tests/test_similarity_matches.py
143
146
  tests/test_similarity_trajectory.py
144
147
  tests/test_timeseries_stream.py
@@ -83,6 +83,8 @@
83
83
  "src/atomscale/results/unknown.py",
84
84
  "src/atomscale/results/xps.py",
85
85
  "src/atomscale/results/xrd.py",
86
+ "src/atomscale/rheed_metadata.py",
87
+ "src/atomscale/samples.py",
86
88
  "src/atomscale/similarity/__init__.py",
87
89
  "src/atomscale/similarity/embedding_provider.py",
88
90
  "src/atomscale/similarity/polling.py",
@@ -134,6 +136,7 @@
134
136
  "tests/test_rheed_stream.py",
135
137
  "tests/test_rheed_timeseries.py",
136
138
  "tests/test_rheed_video.py",
139
+ "tests/test_samples.py",
137
140
  "tests/test_similarity_matches.py",
138
141
  "tests/test_similarity_trajectory.py",
139
142
  "tests/test_timeseries_stream.py",
@@ -0,0 +1,8 @@
1
+ {
2
+ "tag": "0.20.0",
3
+ "distance": 0,
4
+ "node": "g1159e731e4e1425c21f6cbb436a135ea50d15173",
5
+ "dirty": false,
6
+ "branch": "HEAD",
7
+ "node_date": "2026-09-03"
8
+ }