pyglaze 0.4.6__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyglaze
-Version: 0.4.6
+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
@@ -38,11 +38,34 @@ Project-URL: Issues, https://github.com/GlazeTech/pyglaze/issues
 Requires-Python: <3.14,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy>=1.26.4
+Requires-Dist: numpy<2.0.0,>=1.26.4
 Requires-Dist: pyserial>=3.5
 Requires-Dist: scipy>=1.7.3
 Requires-Dist: bitstring>=4.1.2
 Requires-Dist: typing_extensions>=4.12.2
+Provides-Extra: build
+Requires-Dist: build>=1.2.1; extra == "build"
+Requires-Dist: twine>=5.1.1; extra == "build"
+Requires-Dist: bumpver>=2023.1129; extra == "build"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.1; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.2.3; extra == "docs"
+Requires-Dist: mkdocs-material>=8.2.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.18.1; extra == "docs"
+Requires-Dist: mike>=1.1.2; extra == "docs"
+Requires-Dist: Pygments>=2.12.0; extra == "docs"
+Requires-Dist: matplotlib>=3.7.0; extra == "docs"
+Requires-Dist: bumpver>=2023.1129; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.14.10; extra == "dev"
+Requires-Dist: ty>=0.0.13; extra == "dev"
+Requires-Dist: pytest>=7.0.1; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: semver>=2.13.0; extra == "dev"
+Requires-Dist: types-pyserial>=3.5.0.8; extra == "dev"
+Requires-Dist: bumpver>=2023.1129; extra == "dev"
 Dynamic: license-file
 
 # Pyglaze

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

@@ -1,6 +1,6 @@
 [project]
 name = "pyglaze"
-version = "0.4.6"
+version = "0.5.0"
 description = "Pyglaze is a library used to operate the devices of Glaze Technologies"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -10,13 +10,42 @@ authors = [
 requires-python = ">=3.9,<3.14"
 
 dependencies = [
-    "numpy>=1.26.4",
+    "numpy>=1.26.4,<2.0.0",
     "pyserial>=3.5",
     "scipy>=1.7.3",
     "bitstring>=4.1.2",
     "typing_extensions>=4.12.2"
 ]
 
+[project.optional-dependencies]
+build = [
+    "build>=1.2.1",
+    "twine>=5.1.1",
+    "bumpver>=2023.1129",
+]
+test = [
+    "pytest>=7.0.1",
+    "pytest-cov>=4.0.0",
+]
+docs = [
+    "mkdocs>=1.2.3",
+    "mkdocs-material>=8.2.5",
+    "mkdocstrings[python]>=0.18.1",
+    "mike>=1.1.2",
+    "Pygments>=2.12.0",
+    "matplotlib>=3.7.0",
+    "bumpver>=2023.1129",
+]
+dev = [
+    "ruff>=0.14.10",
+    "ty>=0.0.13",
+    "pytest>=7.0.1",
+    "pytest-cov>=4.0.0",
+    "semver>=2.13.0",
+    "types-pyserial>=3.5.0.8",
+    "bumpver>=2023.1129",
+]
+
 [project.urls]
 Homepage = "https://www.glazetech.dk/"
 Documentation = "https://glazetech.github.io/pyglaze/latest"
@@ -74,7 +103,7 @@ convention = "google"
 ]
 
 [tool.bumpver]
-current_version = "0.4.6"
+current_version = "0.5.0"
 version_pattern = "MAJOR.MINOR.PATCH[-TAG]"
 commit_message = "BUMP VERSION {old_version} -> {new_version}"
 tag_message = "v{new_version}"
@@ -97,3 +126,9 @@ push = false
     '**Documentation Version**: {version}'
 ]
 
+[tool.ty.rules]
+unused-ignore-comment = "error"
+
+[tool.ty.terminal]
+error-on-warning = true
+

pyglaze-0.5.0/src/pyglaze/__init__.py

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

{pyglaze-0.4.6 → pyglaze-0.5.0}/src/pyglaze/datamodels/pulse.py

@@ -115,7 +115,7 @@ class Pulse:
 
         Note that the energy is not the same as the physical energy of the pulse, but rather the integral of the square of the pulse.
         """
-        return cast("float", np.trapezoid(self.signal * self.signal, x=self.time))  # type: ignore[attr-defined, unused-ignore]
+        return cast("float", np.trapz(self.signal * self.signal, x=self.time))  # noqa: NPY201
 
     @classmethod
     def from_dict(
@@ -585,7 +585,7 @@ def _estimate_bw_idx(x: FloatArray, y: FloatArray, segments: int) -> int:
     target = np.log(y)
 
     def L1(x: FloatArray, y: FloatArray) -> FloatArray:
-        return np.sum(np.abs(y - x))  # type: ignore[no-any-return]
+        return np.sum(np.abs(y - x))
 
     def model(pars: list[float]) -> FloatArray:
         idx = np.searchsorted(x, pars[0])

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

@@ -6,6 +6,8 @@ from typing import TYPE_CHECKING, Literal
 import numpy as np
 from scipy.interpolate import CubicSpline
 
+from pyglaze.helpers._lockin import _estimate_IQ_phase, _polar_to_IQ, _rotate_inphase
+
 from .pulse import Pulse
 
 if TYPE_CHECKING:
@@ -43,16 +45,37 @@ class UnprocessedWaveform:
         Args:
             time: The time values recorded by the lock-in amp during the scan.
             radius: The radius values recorded by the lock-in amp during the scan.
-            theta: The theta values recorded by the lock-in amp during the scan (in degrees).
-            rotation_angle: The angle to rotate lockin signal to align along x-axis. If not given, will use the angle at the maximum value of R.
+            theta: The theta values recorded by the lock-in amp during the scan (in radians).
+            rotation_angle: The angle to rotate lockin signal to align along x-axis. If not given, will estimate phase from data.
         """
-        _rot_ang = (
-            theta[np.argmax(radius)] if rotation_angle is None else rotation_angle
-        )
+        if rotation_angle is None:
+            rotation_angle, _ = _estimate_IQ_phase(*_polar_to_IQ(radius, theta))
 
         # rotate such that all signal lies along X
-        new_theta = theta - _rot_ang
-        signal = radius * np.cos(new_theta * np.pi / 180.0)
+        new_theta = theta - rotation_angle
+        signal = radius * np.cos(new_theta)
+        return cls(time, signal)
+
+    @classmethod
+    def from_inphase_quadrature(
+        cls: type[UnprocessedWaveform],
+        time: FloatArray,
+        X: FloatArray,
+        Y: FloatArray,
+        rotation_angle: float | None = None,
+    ) -> UnprocessedWaveform:
+        """Create an UnprocessedWaveform object from raw lock-in amp output.
+
+        Args:
+            time: The time values recorded by the lock-in amp during the scan.
+            X: The in-phase values recorded by the lock-in amp during the scan.
+            Y: The quadrature values recorded by the lock-in amp during the scan.
+            rotation_angle: The angle to rotate lockin signal to align along x-axis. If not given, will estimate phase from data.
+        """
+        if rotation_angle is None:
+            rotation_angle, _ = _estimate_IQ_phase(X, Y)
+
+        signal = _rotate_inphase(X, Y, rotation_angle)
         return cls(time, signal)
 
     @classmethod
@@ -159,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.6 → pyglaze-0.5.0}/src/pyglaze/device/ampcom.py

@@ -119,9 +119,7 @@ class _LeAmpCom:
         self._encode_send_response(self.START_COMMAND)
         self._await_scan_finished()
         times, Xs, Ys = self._read_scan()
-
-        radii, angles = self._convert_to_r_angle(Xs, Ys)
-        return self.START_COMMAND, np.array(times), np.array(radii), np.array(angles)
+        return self.START_COMMAND, np.array(times), np.array(Xs), np.array(Ys)
 
     def disconnect(self: _LeAmpCom) -> None:
         """Closes connection when class instance goes out of scope."""
@@ -145,13 +143,6 @@ class _LeAmpCom:
         """Intervals squished into effective DAC range."""
         return self.config.scan_intervals or [Interval(lower=0.0, upper=1.0)]
 
-    def _convert_to_r_angle(
-        self: _LeAmpCom, Xs: list, Ys: list
-    ) -> tuple[FloatArray, FloatArray]:
-        r = np.sqrt(np.array(Xs) ** 2 + np.array(Ys) ** 2)
-        angle = np.arctan2(np.array(Ys), np.array(Xs))
-        return r, np.rad2deg(angle)
-
     def _encode_send_response(
         self: _LeAmpCom, command: str, *, check_ack: bool = True
     ) -> str:

{pyglaze-0.4.6 → 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.5.0/src/pyglaze/helpers/_lockin.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from pyglaze.helpers._types import FloatArray
+
+
+def _wrap_to_pi(a: float) -> float:
+    """Map angle (in radians) to (-pi, pi]."""
+    return (a + np.pi) % (2 * np.pi) - np.pi
+
+
+def _angular_distance(a: float, b: float) -> float:
+    """Smallest absolute distance between angles a and b (in radians)."""
+    return abs(_wrap_to_pi(a - b))
+
+
+def _choose_pi_branch(theta: float, ref: float) -> float:
+    """Choose between theta and theta+pi (mod 2pi) to be closest to ref.
+
+    This prevents accidental polarity flips.
+    """
+    d0 = _angular_distance(theta, ref)
+    d1 = _angular_distance(theta + np.pi, ref)
+    return theta if d0 <= d1 else (theta + np.pi)
+
+
+def _rotate_inphase(X: FloatArray, Y: FloatArray, phi: float) -> FloatArray:
+    """Compute in-phase after rotation by phi."""
+    return X * np.cos(phi) + Y * np.sin(phi)
+
+
+def _polar_to_IQ(r: FloatArray, theta: FloatArray) -> tuple[FloatArray, FloatArray]:
+    """Convert polar coordinates to IQ (X,Y) coordinates."""
+    X = r * np.cos(theta)
+    Y = r * np.sin(theta)
+    return X, Y
+
+
+def _choose_branch_by_strongest_point(
+    theta: float, X: FloatArray, Y: FloatArray, strength: FloatArray | None = None
+) -> float:
+    """Choose between theta and theta+pi so the strongest sample projects positive on the in-phase axis.
+
+    strength can be r or r² because only ordering matters
+    """
+    if strength is None:
+        strength = X * X + Y * Y
+    k = int(np.argmax(strength))
+    proj = X[k] * np.cos(theta) + Y[k] * np.sin(theta)  # in-phase at strongest point
+    return theta if proj >= 0 else (theta + np.pi)
+
+
+def _eigenvalues_symmetric_2D(
+    Sxx: float, Sxy: float, Syy: float
+) -> tuple[float, float]:
+    """Compute the eigenvalues of a symmetric 2D matrix."""
+    trace = Sxx + Syy
+    D = float(np.sqrt((Sxx - Syy) ** 2 + 4.0 * (Sxy**2)))
+    eig1 = 0.5 * (trace + D)
+    eig2 = 0.5 * (trace - D)
+    # Numerical hygiene: symmetric PSD should be >=0, but float noise can create tiny negatives
+    eig1 = float(max(eig1, 0.0))
+    eig2 = float(max(eig2, 0.0))
+    return eig1, eig2
+
+
+def _estimate_IQ_phase(
+    X: FloatArray, Y: FloatArray, w: FloatArray | None = None
+) -> tuple[float, float]:
+    """Estimate the constant lock-in phase (orientation, modulo π) from many (X, Y) lock-in samples by fitting the dominant axis of the IQ cloud.
+
+    This treats each sample as a point in the IQ plane: z_i = X_i + j Y_i, and
+    finds the rotation angle φ such that rotating all points by -φ makes the
+    energy in the quadrature channel minimal (equivalently: maximizes the energy
+    along the in-phase axis). Because this estimates an *axis* rather than a
+    directed angle, the result is naturally defined modulo π.
+
+    Estimates phase by calculating a weighted PCA / eigenvector estimate of the first
+    principal component direction in 2D. The angle of this direction is the estimated
+    lock-in phase.
+    """
+    # Weighted second moment matrix components - a weighted, scaled covariance matrix without mean subtraction
+    if w is None:
+        w = X * X + Y * Y
+
+    Sxx = np.sum(w * X * X)
+    Sxy = np.sum(w * X * Y)
+    Syy = np.sum(w * Y * Y)
+
+    # weighted cov matrix defines an ellipse; find its principal axis angle (see: https://en.wikipedia.org/wiki/Ellipse#General_ellipse)
+    phi_estimate = 0.5 * np.arctan2(2.0 * Sxy, (Sxx - Syy))
+
+    # The squareroot of the eigenvalues correspond to the semi-axis lengths of the ellipse defined by the weighted cov matrix
+    # When very line-like, we've succesfully mapped all signal into one axis, corresponding to high confidence in phase estimate
+    eig1, eig2 = _eigenvalues_symmetric_2D(Sxx, Sxy, Syy)
+
+    # If the matrix is (near) zero or non-finite, the phase is not meaningful
+    if not np.isfinite(eig1) or not np.isfinite(eig2) or eig1 <= 0.0:
+        return phi_estimate, 0.0
+
+    axis_ratio = float(np.sqrt(eig2 / eig1))  # in [0, 1] ideally
+    if not np.isfinite(axis_ratio):
+        return phi_estimate, 0.0
+
+    confidence = np.clip(1.0 - axis_ratio, 0, 1)  # 0 (circle) to 1 (line)
+
+    return phi_estimate, confidence
+
+
+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
+        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
+    ) -> None:
+        """Update the phase estimate based on new in-phase (X) and quadrature (Y) data.
+
+        Args:
+            Xs: Array of in-phase (X) values from the lock-in amplifier.
+            Ys: Array of quadrature (Y) values from the lock-in amplifier.
+        """
+        r_squared = Xs * Xs + Ys * Ys
+        phase_estimate, confidence = _estimate_IQ_phase(Xs, Ys, r_squared)
+
+        # Don't update if confidence is too low
+        if confidence < self.confidence_threshold:
+            return
+
+        # First estimate
+        if self.phase_estimate is None:
+            self._set_estimate(
+                _choose_branch_by_strongest_point(phase_estimate, Xs, Ys, r_squared)
+            )
+            return
+
+        # Resolve the pi ambiguity using previous estimate
+        branched_phase_estimate = _choose_pi_branch(phase_estimate, self.phase_estimate)
+        self._set_estimate(branched_phase_estimate)
+
+    def _set_estimate(self: _LockinPhaseEstimator, phase: float) -> None:
+        self.phase_estimate = _wrap_to_pi(float(phase))

{pyglaze-0.4.6 → pyglaze-0.5.0}/src/pyglaze/helpers/utilities.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import time
 from dataclasses import dataclass
 from functools import wraps
-from typing import TYPE_CHECKING, Callable, cast
+from typing import TYPE_CHECKING, Callable
 
 import serial
 import serial.tools.list_ports
@@ -57,19 +57,20 @@ class _BackoffRetry:
 
         @wraps(func)
         def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            func_name = getattr(func, "__name__", "function")
             for tries in range(self.max_tries - 1):
                 try:
-                    return cast("T", func(*args, **kwargs))
+                    return func(*args, **kwargs)
                 except (KeyboardInterrupt, SystemExit):
                     raise
                 except Exception as e:  # noqa: BLE001
                     self._log(
-                        f"{func.__name__} failed {tries + 1} time(s) with: '{e}'. Trying again"
+                        f"{func_name} failed {tries + 1} time(s) with: '{e}'. Trying again"
                     )
                 backoff = min(self.backoff_base * 2**tries, self.max_backoff)
                 time.sleep(backoff)
-            self._log(f"{func.__name__}: Last try ({tries + 2}).")
-            return cast("T", func(*args, **kwargs))
+            self._log(f"{func_name}: Last try ({tries + 2}).")
+            return func(*args, **kwargs)
 
         return wrapper
 

{pyglaze-0.4.6 → 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.6 → 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.6 → pyglaze-0.5.0}/src/pyglaze/scanning/scanner.py

@@ -1,18 +1,14 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Generic, TypeVar
-
-import numpy as np
+from typing import Generic, TypeVar
 
 from pyglaze.datamodels import UnprocessedWaveform
 from pyglaze.device.ampcom import _LeAmpCom
 from pyglaze.device.configuration import DeviceConfiguration, LeDeviceConfiguration
+from pyglaze.helpers._lockin import _LockinPhaseEstimator
 from pyglaze.scanning._exceptions import ScanError
 
-if TYPE_CHECKING:
-    from pyglaze.helpers._types import FloatArray
-
 TConfig = TypeVar("TConfig", bound=DeviceConfiguration)
 
 
@@ -51,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
@@ -105,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:
@@ -154,11 +180,10 @@ class LeScanner(_ScannerImplementation[LeDeviceConfiguration]):
         if self._ampcom is None:
             msg = "Scanner not configured"
             raise ScanError(msg)
-        _, time, radius, theta = self._ampcom.start_scan()
-        self._phase_estimator.update_estimate(radius=radius, theta=theta)
-
-        return UnprocessedWaveform.from_polar_coords(
-            time, radius, theta, self._phase_estimator.phase_estimate
+        _, time, Xs, Ys = self._ampcom.start_scan()
+        self._phase_estimator.update_estimate(Xs=Xs, Ys=Ys)
+        return UnprocessedWaveform.from_inphase_quadrature(
+            time, Xs, Ys, self._phase_estimator.phase_estimate
         )
 
     def update_config(self: LeScanner, new_config: LeDeviceConfiguration) -> None:
@@ -199,45 +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)
-
-
-class _LockinPhaseEstimator:
-    def __init__(
-        self: _LockinPhaseEstimator,
-        r_threshold_for_update: float = 2.0,
-        theta_threshold_for_adjustment: float = 1.0,
-    ) -> None:
-        self.r_threshold_for_update = r_threshold_for_update
-        self.theta_threshold_for_adjustment = theta_threshold_for_adjustment
-        self.phase_estimate: float | None = None
-        self._radius_of_est: float | None = None
-
-    def update_estimate(
-        self: _LockinPhaseEstimator, radius: FloatArray, theta: FloatArray
-    ) -> None:
-        r_argmax = np.argmax(radius)
-        r_max = radius[r_argmax]
-        theta_at_max = theta[r_argmax]
-        if self._radius_of_est is None:
-            self._set_estimates(theta_at_max, r_max)
-            return
-
-        if r_max > self.r_threshold_for_update * self._radius_of_est or (
-            r_max > self._radius_of_est
-            and abs(theta_at_max - self.phase_estimate)
-            < self.theta_threshold_for_adjustment
-        ):
-            self._set_estimates(theta_at_max, r_max)
-
-    def _set_estimates(
-        self: _LockinPhaseEstimator, phase: float, radius: float
-    ) -> None:
-        self.phase_estimate = phase
-        self._radius_of_est = radius

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyglaze
-Version: 0.4.6
+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
@@ -38,11 +38,34 @@ Project-URL: Issues, https://github.com/GlazeTech/pyglaze/issues
 Requires-Python: <3.14,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy>=1.26.4
+Requires-Dist: numpy<2.0.0,>=1.26.4
 Requires-Dist: pyserial>=3.5
 Requires-Dist: scipy>=1.7.3
 Requires-Dist: bitstring>=4.1.2
 Requires-Dist: typing_extensions>=4.12.2
+Provides-Extra: build
+Requires-Dist: build>=1.2.1; extra == "build"
+Requires-Dist: twine>=5.1.1; extra == "build"
+Requires-Dist: bumpver>=2023.1129; extra == "build"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.1; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.2.3; extra == "docs"
+Requires-Dist: mkdocs-material>=8.2.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.18.1; extra == "docs"
+Requires-Dist: mike>=1.1.2; extra == "docs"
+Requires-Dist: Pygments>=2.12.0; extra == "docs"
+Requires-Dist: matplotlib>=3.7.0; extra == "docs"
+Requires-Dist: bumpver>=2023.1129; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.14.10; extra == "dev"
+Requires-Dist: ty>=0.0.13; extra == "dev"
+Requires-Dist: pytest>=7.0.1; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: semver>=2.13.0; extra == "dev"
+Requires-Dist: types-pyserial>=3.5.0.8; extra == "dev"
+Requires-Dist: bumpver>=2023.1129; extra == "dev"
 Dynamic: license-file
 
 # Pyglaze

{pyglaze-0.4.6 → pyglaze-0.5.0}/src/pyglaze.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ src/pyglaze/devtools/__init__.py
 src/pyglaze/devtools/mock_device.py
 src/pyglaze/devtools/thz_pulse.py
 src/pyglaze/helpers/__init__.py
+src/pyglaze/helpers/_lockin.py
 src/pyglaze/helpers/_types.py
 src/pyglaze/helpers/utilities.py
 src/pyglaze/interpolation/__init__.py

pyglaze-0.5.0/src/pyglaze.egg-info/requires.txt

@@ -0,0 +1,32 @@
+numpy<2.0.0,>=1.26.4
+pyserial>=3.5
+scipy>=1.7.3
+bitstring>=4.1.2
+typing_extensions>=4.12.2
+
+[build]
+build>=1.2.1
+twine>=5.1.1
+bumpver>=2023.1129
+
+[dev]
+ruff>=0.14.10
+ty>=0.0.13
+pytest>=7.0.1
+pytest-cov>=4.0.0
+semver>=2.13.0
+types-pyserial>=3.5.0.8
+bumpver>=2023.1129
+
+[docs]
+mkdocs>=1.2.3
+mkdocs-material>=8.2.5
+mkdocstrings[python]>=0.18.1
+mike>=1.1.2
+Pygments>=2.12.0
+matplotlib>=3.7.0
+bumpver>=2023.1129
+
+[test]
+pytest>=7.0.1
+pytest-cov>=4.0.0

pyglaze-0.4.6/src/pyglaze/__init__.py

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

pyglaze-0.4.6/src/pyglaze.egg-info/requires.txt

@@ -1,5 +0,0 @@
-numpy>=1.26.4
-pyserial>=3.5
-scipy>=1.7.3
-bitstring>=4.1.2
-typing_extensions>=4.12.2