pyglaze 0.4.7__tar.gz → 0.5.0__tar.gz

{pyglaze-0.4.7/src/pyglaze.egg-info → pyglaze-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyglaze
-Version: 0.4.7
+Version: 0.5.0
 Summary: Pyglaze is a library used to operate the devices of Glaze Technologies
 Author: GLAZE Technologies ApS
 License: BSD 3-Clause License

{pyglaze-0.4.7 → pyglaze-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyglaze"
-version = "0.4.7"
+version = "0.5.0"
 description = "Pyglaze is a library used to operate the devices of Glaze Technologies"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -103,7 +103,7 @@ convention = "google"
 ]
 
 [tool.bumpver]
-current_version = "0.4.7"
+current_version = "0.5.0"
 version_pattern = "MAJOR.MINOR.PATCH[-TAG]"
 commit_message = "BUMP VERSION {old_version} -> {new_version}"
 tag_message = "v{new_version}"

pyglaze-0.5.0/src/pyglaze/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"

{pyglaze-0.4.7 → pyglaze-0.5.0}/src/pyglaze/datamodels/waveform.py

@@ -182,7 +182,9 @@ class _TimestampedWaveform:
     Args:
         timestamp: The timestamp of the pulse given by the Toptica server.
         waveform: The terahertz pulse received from the Toptica server.
+        phase_estimate: The phase estimate from the lock-in phase estimator at the time of this scan.
     """
 
     timestamp: datetime
     waveform: UnprocessedWaveform
+    phase_estimate: float | None = None

{pyglaze-0.4.7 → pyglaze-0.5.0}/src/pyglaze/devtools/mock_device.py

@@ -226,7 +226,7 @@ class LeMockDevice(MockDevice):
             numbers = np.concatenate(
                 (
                     np.array(self.scanning_list) * 100e-12,  # mock time values
-                    self.rng.random(2 * len(self.scanning_list)),
+                    self.rng.random(2 * len(self.scanning_list)) + 1,
                 )
             )
 

{pyglaze-0.4.7 → pyglaze-0.5.0}/src/pyglaze/helpers/_lockin.py

@@ -115,9 +115,20 @@ class _LockinPhaseEstimator:
     def __init__(
         self: _LockinPhaseEstimator,
         confidence_threshold: float = 0.8,
+        initial_phase_estimate: float | None = None,
     ) -> None:
+        """Initialize the lock-in phase estimator.
+
+        Args:
+            confidence_threshold: Minimum confidence (0-1) required to update phase estimate.
+            initial_phase_estimate: Optional initial phase in radians. If provided, sets the
+                initial phase estimate to this value (wrapped to [-π, π]).
+        """
         self.confidence_threshold = confidence_threshold
-        self.phase_estimate: float | None = None
+        if initial_phase_estimate is not None:
+            self.phase_estimate = _wrap_to_pi(float(initial_phase_estimate))
+        else:
+            self.phase_estimate: float | None = None  # Phase estimate in radians
 
     def update_estimate(
         self: _LockinPhaseEstimator, Xs: FloatArray, Ys: FloatArray

{pyglaze-0.4.7 → pyglaze-0.5.0}/src/pyglaze/scanning/_asyncscanner.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
 from multiprocessing import Event, Pipe, Process, Queue, synchronize
 from queue import Empty, Full
 from typing import TYPE_CHECKING
@@ -45,20 +45,38 @@ class _AsyncScanner:
     _SCAN_TIMEOUT: float = field(init=False)
     _stop_signal: synchronize.Event = field(init=False)
     _scanner_conn: Connection = field(init=False)
+    _initial_phase_estimate: float | None = field(init=False, default=None)
+    _cached_phase_estimate: float | None = field(init=False, default=None)
 
-    def start_scan(self: _AsyncScanner, config: DeviceConfiguration) -> None:
+    def start_scan(
+        self: _AsyncScanner,
+        config: DeviceConfiguration,
+        initial_phase_estimate: float | None = None,
+    ) -> None:
         """Starts continuously scanning in new process.
 
         Args:
-            config: Device configurtaion
+            config: Device configuration
+            initial_phase_estimate: Optional initial phase estimate in radians for lock-in detection.
+                Use this to maintain consistent polarity across scanner instances.
         """
+        self._initial_phase_estimate = initial_phase_estimate
+        self._cached_phase_estimate = (
+            initial_phase_estimate  # Initialize cache with initial value
+        )
         self._SCAN_TIMEOUT = config._sweep_length_ms * 2e-3 + 1  # noqa: SLF001, access to private attribute for backwards compatibility
         self._shared_mem = Queue(maxsize=self.queue_maxsize)
         self._stop_signal = Event()
         self._scanner_conn, child_conn = Pipe()
         self._child_process = Process(
             target=_AsyncScanner._run_scanner,
-            args=[config, self._shared_mem, self._stop_signal, child_conn],
+            args=[
+                config,
+                self._shared_mem,
+                self._stop_signal,
+                child_conn,
+                initial_phase_estimate,
+            ],
         )
         self._child_process.start()
 
@@ -90,7 +108,7 @@ class _AsyncScanner:
         self.is_scanning = False
 
     def get_scans(self: _AsyncScanner, n_pulses: int) -> list[UnprocessedWaveform]:
-        call_time = datetime.now()  # noqa: DTZ005
+        call_time = datetime.now(tz=timezone.utc)
         stamped_pulse = self._get_scan()
 
         while stamped_pulse.timestamp < call_time:
@@ -114,9 +132,23 @@ class _AsyncScanner:
 
         return self._metadata.firmware_version
 
+    def get_phase_estimate(self: _AsyncScanner) -> float | None:
+        """Get the current phase estimate from the scanner.
+
+        Returns the cached phase estimate from the most recently received waveform.
+        This method returns instantly without blocking and can be called even after
+        the scanner has stopped, allowing phase estimates to be extracted and reused.
+
+        Returns:
+            float | None: The current phase estimate in radians, or None if not yet estimated.
+        """
+        return self._cached_phase_estimate
+
     def _get_scan(self: _AsyncScanner) -> _TimestampedWaveform:
         try:
-            return self._shared_mem.get(timeout=self._SCAN_TIMEOUT)
+            waveform = self._shared_mem.get(timeout=self._SCAN_TIMEOUT)
+            # Cache the phase estimate from this waveform
+            self._cached_phase_estimate = waveform.phase_estimate
         except Exception as err:
             scanner_err: Exception | None = None
             if self._scanner_conn.poll(timeout=self.startup_timeout):
@@ -127,6 +159,8 @@ class _AsyncScanner:
             if scanner_err:
                 raise scanner_err from err
             raise
+        else:
+            return waveform
 
     @staticmethod
     def _run_scanner(
@@ -134,9 +168,12 @@ class _AsyncScanner:
         shared_mem: Queue[_TimestampedWaveform],
         stop_signal: synchronize.Event,
         parent_conn: Connection,
+        initial_phase_estimate: float | None = None,
     ) -> None:
         try:
-            scanner = Scanner(config=config)
+            scanner = Scanner(
+                config=config, initial_phase_estimate=initial_phase_estimate
+            )
             device_metadata = _ScannerMetadata(
                 serial_number=scanner.get_serial_number(),
                 firmware_version=scanner.get_firmware_version(),
@@ -149,7 +186,13 @@ class _AsyncScanner:
 
         while not stop_signal.is_set():
             try:
-                waveform = _TimestampedWaveform(datetime.now(), scanner.scan())  # noqa: DTZ005
+                scanned_waveform = scanner.scan()
+                phase = scanner.get_phase_estimate()
+                waveform = _TimestampedWaveform(
+                    datetime.now(tz=timezone.utc),
+                    scanned_waveform,
+                    phase,
+                )
             except Exception as e:  # noqa: BLE001
                 parent_conn.send(
                     _ScannerHealth(is_alive=False, is_healthy=False, error=e)

{pyglaze-0.4.7 → pyglaze-0.5.0}/src/pyglaze/scanning/client.py

@@ -28,16 +28,19 @@ class GlazeClient:
 
     Args:
         config: Configuration to use for scans
+        initial_phase_estimate: Optional initial phase estimate in radians for lock-in detection.
+            Use this to maintain consistent polarity across scanning sessions.
     """
 
     config: DeviceConfiguration
+    initial_phase_estimate: float | None = None
     _scanner: _AsyncScanner = field(init=False)
 
     def __enter__(self: Self) -> Self:
         """Start the scanner and return the client."""
         self._scanner = _AsyncScanner()
         try:
-            self._scanner.start_scan(self.config)
+            self._scanner.start_scan(self.config, self.initial_phase_estimate)
         except (TimeoutError, serialutil.SerialException) as e:
             self.__exit__(e)
         return self
@@ -73,3 +76,21 @@ class GlazeClient:
         except AttributeError as e:
             msg = "No connection to device."
             raise SerialException(msg) from e
+
+    def get_phase_estimate(self: GlazeClient) -> float | None:
+        """Get the current phase estimate from the lock-in phase estimator.
+
+        Can be called even after the client has been stopped, allowing phase estimates
+        to be extracted and reused for maintaining consistent polarity across sessions.
+
+        Returns:
+            float | None: The current phase estimate in radians, or None if not yet estimated.
+
+        Raises:
+            SerialException: If the scanner was never started.
+        """
+        try:
+            return self._scanner.get_phase_estimate()
+        except AttributeError as e:
+            msg = "No connection to device."
+            raise SerialException(msg) from e

{pyglaze-0.4.7 → pyglaze-0.5.0}/src/pyglaze/scanning/scanner.py

@@ -47,13 +47,27 @@ class _ScannerImplementation(ABC, Generic[TConfig]):
     def get_firmware_version(self: _ScannerImplementation) -> str:
         pass
 
+    @abstractmethod
+    def get_phase_estimate(self: _ScannerImplementation) -> float | None:
+        pass
+
 
 class Scanner:
-    """A synchronous scanner for Glaze terahertz devices."""
+    """A synchronous scanner for Glaze terahertz devices.
+
+    Args:
+        config: Device configuration for the scanner.
+        initial_phase_estimate: Optional initial phase estimate in radians for lock-in detection.
+            Use this to maintain consistent polarity across scanner instances.
+    """
 
-    def __init__(self: Scanner, config: TConfig) -> None:
+    def __init__(
+        self: Scanner,
+        config: TConfig,
+        initial_phase_estimate: float | None = None,
+    ) -> None:
         self._scanner_impl: _ScannerImplementation[DeviceConfiguration] = (
-            _scanner_factory(config)
+            _scanner_factory(config, initial_phase_estimate)
         )
 
     @property
@@ -101,19 +115,35 @@ class Scanner:
         """
         return self._scanner_impl.get_firmware_version()
 
+    def get_phase_estimate(self: Scanner) -> float | None:
+        """Get the current phase estimate from the lock-in phase estimator.
+
+        Returns:
+            float | None: The current phase estimate in radians, or None if not yet estimated.
+        """
+        return self._scanner_impl.get_phase_estimate()
+
 
 class LeScanner(_ScannerImplementation[LeDeviceConfiguration]):
     """Perform synchronous terahertz scanning using a given DeviceConfiguration.
 
     Args:
         config: A DeviceConfiguration to use for the scan.
+        initial_phase_estimate: Optional initial phase estimate in radians for lock-in detection.
+            Use this to maintain consistent polarity across scanner instances.
     """
 
-    def __init__(self: LeScanner, config: LeDeviceConfiguration) -> None:
+    def __init__(
+        self: LeScanner,
+        config: LeDeviceConfiguration,
+        initial_phase_estimate: float | None = None,
+    ) -> None:
         self._config: LeDeviceConfiguration
         self._ampcom: _LeAmpCom | None = None
         self.config = config
-        self._phase_estimator = _LockinPhaseEstimator()
+        self._phase_estimator = _LockinPhaseEstimator(
+            initial_phase_estimate=initial_phase_estimate
+        )
 
     @property
     def config(self: LeScanner) -> LeDeviceConfiguration:
@@ -194,10 +224,20 @@ class LeScanner(_ScannerImplementation[LeDeviceConfiguration]):
             raise ScanError(msg)
         return self._ampcom.get_firmware_version()
 
+    def get_phase_estimate(self: LeScanner) -> float | None:
+        """Get the current phase estimate from the lock-in phase estimator.
+
+        Returns:
+            float | None: The current phase estimate in radians, or None if not yet estimated.
+        """
+        return self._phase_estimator.phase_estimate
+
 
-def _scanner_factory(config: DeviceConfiguration) -> _ScannerImplementation:
+def _scanner_factory(
+    config: DeviceConfiguration, initial_phase_estimate: float | None = None
+) -> _ScannerImplementation:
     if isinstance(config, LeDeviceConfiguration):
-        return LeScanner(config)
+        return LeScanner(config, initial_phase_estimate)
 
     msg = f"Unsupported configuration type: {type(config).__name__}"
     raise TypeError(msg)

{pyglaze-0.4.7 → pyglaze-0.5.0/src/pyglaze.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyglaze
-Version: 0.4.7
+Version: 0.5.0
 Summary: Pyglaze is a library used to operate the devices of Glaze Technologies
 Author: GLAZE Technologies ApS
 License: BSD 3-Clause License

pyglaze-0.4.7/src/pyglaze/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.4.7"