rheed-realtime-analyzer 0.2.0__tar.gz

rheed_realtime_analyzer-0.2.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: rheed-realtime-analyzer
+Version: 0.2.0
+Summary: Sidecar analytics framework for real-time RHEED monitoring
+Keywords: RHEED,PLD,real-time,analysis,materials
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: notebook>=7.0; extra == "dev"
+Requires-Dist: ipykernel>=6.0; extra == "dev"
+
+# RHEED Real-Time Analyzer
+
+Python sidecar framework for real-time RHEED analytics in a TSST-centered PLD workflow.
+
+## Scope
+
+- Keeps TSST as authoritative control and safety gate.
+- Runs independent analytics and policy logic.
+- Starts in advisory mode, with closed-loop hooks for later bounded control.
+
+## Installation
+
+### Option A: Conda environment (recommended)
+
+```bash
+conda create -n rheed-rt python=3.11 -y
+conda activate rheed-rt
+pip install -r requirements.txt
+pip install -e .
+```
+
+### Option B: Dev environment (tests + notebook + publishing tools)
+
+```bash
+conda create -n rheed-rt-dev python=3.11 -y
+conda activate rheed-rt-dev
+pip install -r requirements-dev.txt
+pip install -e .[dev]
+```
+
+## Quick Start
+
+Run a short dummy sidecar session:
+
+```bash
+rheed-sidecar --duration 10
+```
+
+This writes JSONL events to `logs/events.jsonl` by default.
+
+## Test
+
+```bash
+pytest -q
+```
+
+Detailed test and demo notes are in `tests/README.md`.
+
+## Build And Publish
+
+Detailed release instructions are in `docs/PUBLISHING.md`.
+
+### Automated release via GitHub Actions
+
+This repo includes `.github/workflows/main.yml` with keyword-triggered release on pushes to `main`:
+
+- `#major` -> bump `X.0.0`
+- `#minor` -> bump `x.Y.0`
+- `#patch` -> bump `x.y.Z`
+
+Example commit message:
+
+```text
+feat: add TSST adapter #major
+```
+
+When triggered, the workflow will:
+
+1. bump versions in `pyproject.toml` and `rheed_core/__init__.py`
+2. create/push a release commit and `vX.Y.Z` tag
+3. build and publish to PyPI using `pypa/gh-action-pypi-publish`
+
+Note: configure PyPI Trusted Publishing for this repository/workflow before first automated release.
+
+### Local package build check
+
+```bash
+python -m build
+twine check dist/*
+```
+
+## Current Capabilities
+
+- Dummy real-time collector with noisy oscillatory intensity and synthetic image frames.
+- Rolling preprocessing + feature extraction (signal + image proxies).
+- Oscillation tracker with period/phase/amplitude/confidence estimation.
+- Draft-integrated cycle analysis (peak segmentation + per-cycle relaxation `tau` estimate).
+- Offline reusable analysis pipeline adapted from draft code:
+  - range selection
+  - denoise chain
+  - peak-to-peak cycle splitting
+  - tail/background cleanup
+  - per-cycle relaxation fitting
+- Advisory-first policy engine for drift, frame quality, period instability, and amplitude decay.
+- Replayable JSONL event logging.
+
+## Draft Integration
+
+Legacy analysis ideas from `rheed_core/core/draft codes/` are bridged into the runtime path through:
+
+- `rheed_core/core/draft_bridge.py`: FFT band-pass, median filtering, peak detection, cycle segmentation, and linearized `tau` fitting.
+- `rheed_core/core/preprocess.py`: optional median + FFT filtering in streaming mode.
+- `rheed_core/core/features.py`: Gaussian-moment-like image spread and drift estimation.
+- `rheed_core/core/state.py`: latest cycle relaxation-time tracking.
+- `rheed_core/core/policy.py`: advisory on unstable relaxation-time behavior.
+
+## Notebook Demos
+
+- `tests/demo_draft_bridge.ipynb`: draft-derived signal processing + `tau` fitting utilities.
+- `tests/demo_pipeline_integration.ipynb`: end-to-end sidecar usage with draft-aware config.
+- `tests/demo_offline_analysis.ipynb`: second-pass offline flow mirroring real draft workflow.
+
+## Project Layout
+
+```text
+rheed_core/
+  main.py
+  config.yaml
+  core/
+  io/
+tests/
+docs/
+```
+
+## Roadmap
+
+1. Replace dummy collector with TSST stream adapter.
+2. Validate feature/state outputs against recorded experimental datasets.
+3. Introduce bounded command outputs behind explicit safety constraints.

rheed_realtime_analyzer-0.2.0/README.md

@@ -0,0 +1,129 @@
+# RHEED Real-Time Analyzer
+
+Python sidecar framework for real-time RHEED analytics in a TSST-centered PLD workflow.
+
+## Scope
+
+- Keeps TSST as authoritative control and safety gate.
+- Runs independent analytics and policy logic.
+- Starts in advisory mode, with closed-loop hooks for later bounded control.
+
+## Installation
+
+### Option A: Conda environment (recommended)
+
+```bash
+conda create -n rheed-rt python=3.11 -y
+conda activate rheed-rt
+pip install -r requirements.txt
+pip install -e .
+```
+
+### Option B: Dev environment (tests + notebook + publishing tools)
+
+```bash
+conda create -n rheed-rt-dev python=3.11 -y
+conda activate rheed-rt-dev
+pip install -r requirements-dev.txt
+pip install -e .[dev]
+```
+
+## Quick Start
+
+Run a short dummy sidecar session:
+
+```bash
+rheed-sidecar --duration 10
+```
+
+This writes JSONL events to `logs/events.jsonl` by default.
+
+## Test
+
+```bash
+pytest -q
+```
+
+Detailed test and demo notes are in `tests/README.md`.
+
+## Build And Publish
+
+Detailed release instructions are in `docs/PUBLISHING.md`.
+
+### Automated release via GitHub Actions
+
+This repo includes `.github/workflows/main.yml` with keyword-triggered release on pushes to `main`:
+
+- `#major` -> bump `X.0.0`
+- `#minor` -> bump `x.Y.0`
+- `#patch` -> bump `x.y.Z`
+
+Example commit message:
+
+```text
+feat: add TSST adapter #major
+```
+
+When triggered, the workflow will:
+
+1. bump versions in `pyproject.toml` and `rheed_core/__init__.py`
+2. create/push a release commit and `vX.Y.Z` tag
+3. build and publish to PyPI using `pypa/gh-action-pypi-publish`
+
+Note: configure PyPI Trusted Publishing for this repository/workflow before first automated release.
+
+### Local package build check
+
+```bash
+python -m build
+twine check dist/*
+```
+
+## Current Capabilities
+
+- Dummy real-time collector with noisy oscillatory intensity and synthetic image frames.
+- Rolling preprocessing + feature extraction (signal + image proxies).
+- Oscillation tracker with period/phase/amplitude/confidence estimation.
+- Draft-integrated cycle analysis (peak segmentation + per-cycle relaxation `tau` estimate).
+- Offline reusable analysis pipeline adapted from draft code:
+  - range selection
+  - denoise chain
+  - peak-to-peak cycle splitting
+  - tail/background cleanup
+  - per-cycle relaxation fitting
+- Advisory-first policy engine for drift, frame quality, period instability, and amplitude decay.
+- Replayable JSONL event logging.
+
+## Draft Integration
+
+Legacy analysis ideas from `rheed_core/core/draft codes/` are bridged into the runtime path through:
+
+- `rheed_core/core/draft_bridge.py`: FFT band-pass, median filtering, peak detection, cycle segmentation, and linearized `tau` fitting.
+- `rheed_core/core/preprocess.py`: optional median + FFT filtering in streaming mode.
+- `rheed_core/core/features.py`: Gaussian-moment-like image spread and drift estimation.
+- `rheed_core/core/state.py`: latest cycle relaxation-time tracking.
+- `rheed_core/core/policy.py`: advisory on unstable relaxation-time behavior.
+
+## Notebook Demos
+
+- `tests/demo_draft_bridge.ipynb`: draft-derived signal processing + `tau` fitting utilities.
+- `tests/demo_pipeline_integration.ipynb`: end-to-end sidecar usage with draft-aware config.
+- `tests/demo_offline_analysis.ipynb`: second-pass offline flow mirroring real draft workflow.
+
+## Project Layout
+
+```text
+rheed_core/
+  main.py
+  config.yaml
+  core/
+  io/
+tests/
+docs/
+```
+
+## Roadmap
+
+1. Replace dummy collector with TSST stream adapter.
+2. Validate feature/state outputs against recorded experimental datasets.
+3. Introduce bounded command outputs behind explicit safety constraints.

rheed_realtime_analyzer-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rheed-realtime-analyzer"
+version = "0.2.0"
+description = "Sidecar analytics framework for real-time RHEED monitoring"
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["RHEED", "PLD", "real-time", "analysis", "materials"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering",
+]
+dependencies = [
+  "numpy>=1.24",
+  "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "build>=1.2",
+  "twine>=5.0",
+  "notebook>=7.0",
+  "ipykernel>=6.0",
+]
+
+[project.scripts]
+rheed-sidecar = "rheed_core.main:main"
+
+[tool.setuptools.packages.find]
+include = ["rheed_core*"]
+
+[tool.setuptools.package-data]
+rheed_core = ["config.yaml"]

rheed_realtime_analyzer-0.2.0/rheed_core/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.2.0"

rheed_realtime_analyzer-0.2.0/rheed_core/__main__.py

@@ -0,0 +1,4 @@
+from rheed_core.main import main
+
+if __name__ == "__main__":
+    main()

rheed_realtime_analyzer-0.2.0/rheed_core/config.yaml

@@ -0,0 +1,35 @@
+runtime:
+  duration_s: 20.0
+  loop_sleep_s: 0.01
+
+logging:
+  path: logs/events.jsonl
+
+preprocess:
+  trend_window: 64
+  clip_sigma: 4.0
+  median_kernel_size: 5
+  fft_band: [0.05, 5.0]
+  sample_rate_hz: 20.0
+  fft_window: 128
+
+state:
+  max_points: 400
+  min_period_s: 0.2
+  max_period_s: 30.0
+  tau_peak_prominence: 0.05
+  tau_min_points: 8
+
+policy:
+  drift_threshold: 8.0
+  bad_frame_limit: 5
+  period_cv_threshold: 0.2
+  tau_cv_threshold: 0.35
+  advisory_mode: true
+
+dummy:
+  sample_rate_hz: 20.0
+  frame_rate_hz: 2.0
+  osc_period_s: 4.0
+  noise_std: 0.15
+  seed: 123

rheed_realtime_analyzer-0.2.0/rheed_core/core/buffers.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+"""Lightweight buffering primitives for streaming analytics."""
+
+from collections import deque
+from typing import Deque, Generic, Iterable, TypeVar
+
+T = TypeVar("T")
+
+
+class RingBuffer(Generic[T]):
+    """Typed deque wrapper with convenience helpers for recent-history access."""
+
+    def __init__(self, maxlen: int):
+        """Create a fixed-capacity ring buffer."""
+        if maxlen <= 0:
+            raise ValueError("maxlen must be > 0")
+        self._data: Deque[T] = deque(maxlen=maxlen)
+
+    def append(self, item: T) -> None:
+        """Append one item, evicting the oldest if full."""
+        self._data.append(item)
+
+    def extend(self, items: Iterable[T]) -> None:
+        """Append multiple items in order."""
+        self._data.extend(items)
+
+    def clear(self) -> None:
+        """Remove all items."""
+        self._data.clear()
+
+    def latest(self) -> T | None:
+        """Return most recent item or None when empty."""
+        return self._data[-1] if self._data else None
+
+    def as_list(self) -> list[T]:
+        """Materialize the current buffer contents."""
+        return list(self._data)
+
+    def __len__(self) -> int:
+        """Return current number of buffered items."""
+        return len(self._data)