atomscale.similarity.polling.iter_poll_trajectory#

atomscale.similarity.polling.iter_poll_trajectory(client, source_id: str, *, interval: float = 1.0, last_n: int | None = None, distinct_by: Callable[[DataFrame], Any] | None = None, until: Callable[[DataFrame], bool] | None = None, max_polls: int | None = None, fire_immediately: bool = True, jitter: float = 0.0, on_error: Callable[[BaseException], None] | None = None) → Iterator[DataFrame][source]

Synchronously poll similarity trajectory data, yielding DataFrames.

Parameters:

  • client – API client instance forwarded to the provider.

  • source_id (str) – The data_id or physical_sample_id to poll trajectory for.

  • interval (float) – Seconds between polls. Defaults to 1.0.

  • last_n (int | None) – Last number of trajectory data points to poll. None is all.

  • distinct_by (Callable[[DataFrame], Any] | None) – Optional function mapping a result to a hashable key for deduping. If provided, only results with a new key are yielded.

  • until (Callable[[DataFrame], bool] | None) – Optional predicate; stop when it returns True for a result. If None, defaults to stopping when no trajectory is active (i.e., not df["Active"].any()).

  • max_polls (int | None) – Optional maximum number of polls before stopping.

  • fire_immediately (bool) – If True, perform the first poll immediately; otherwise wait one interval before the first poll. Defaults to True.

  • jitter (float) – Optional random delay (0..jitter) added to each sleep to avoid thundering herds. Clamped at interval. Defaults to 0.0.

  • on_error (Callable[[BaseException], None] | None) – Optional error handler called with the raised exception when a poll fails. Errors are swallowed so polling continues.

Yields:

DataFrame – Trajectory data with multi-index [“Reference ID”, “Time”].

Return type:

Iterator[DataFrame]

Notes

  • Uses drift-corrected scheduling to maintain the requested cadence even if individual polls are slow.

  • Stops when until is satisfied or max_polls is reached (if set).