Add concurrency guard for sweeps and update docs

Introduces a concurrency guard to ensure only one non-queued sweep runs at a time, with exceptions for related (parent/child) sweeps and those launched via SweepQueue. Adds `start_force()` to forcibly kill unrelated active sweeps before starting, and `list_active_sweeps()` for debugging. Updates documentation and tutorial notebooks to reflect new concurrency behavior and error handling.

Author: caidish

README.md

@@ -22,6 +22,7 @@ See related projects:
 
 ### Key Components
 - **Base Classes**: `BaseSweep` provides the foundation with parameter following, measurement creation, and thread management
+- **Sweep Concurrency Guard**: Only one non-queued sweep can run at a time; `SweepQueue` bypasses this guard, and internal ramp/inner sweeps are allowed via parent relationships. Use `start_force()` to kill unrelated active sweeps before starting.
 - **Measurement Types**: 
   - 0D (time-based measurements)
   - 1D (single parameter sweep) 

docs/source/start/index.rst

@@ -68,6 +68,22 @@ Sweep Logging
   The helper marshals log messages from background Qt threads back onto the
   IPython event loop so they show up alongside your notebook output.
 
+Sweep Concurrency
+-----------------
+
+- Only one non-queued sweep may run at a time. Calling ``start()`` on a new
+  sweep while another is running raises ``RuntimeError``.
+- Resuming a paused sweep while another is running also raises ``RuntimeError``.
+- Sweeps launched by :class:`~measureit.tools.sweep_queue.SweepQueue` bypass
+  this guard (``is_queued=True``).
+- Internal sweeps (inner sweeps and ramp sweeps) are allowed via the parent
+  relationship between sweeps.
+- To force-start a sweep (killing unrelated active sweeps first), use
+  ``start_force()``.
+- For debugging or recovery (e.g., you lost a Python reference), use
+  ``BaseSweep.list_active_sweeps()`` to inspect running/paused sweeps and
+  regain access to them.
+
 Example notebooks
 -----------------
 

examples/Tutorial.ipynb

@@ -35,7 +35,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.9"
+   "version": "3.11.14"
   }
  },
  "nbformat": 4,

examples/content/quick start.ipynb

@@ -5,6 +5,7 @@
 import time
 import threading
 import warnings
+import weakref
 from decimal import ROUND_HALF_EVEN, Decimal, localcontext
 from functools import partial
 from typing import Optional, Tuple
@@ -20,6 +21,72 @@
 from ..tools.util import _autorange_srs, is_numeric_parameter, safe_get, safe_set
 from .progress import ProgressState, SweepState
 
+_ACTIVE_SWEEPS = weakref.WeakSet()
+_ACTIVE_SWEEPS_LOCK = threading.Lock()
+
+
+def _register_active_sweep(sweep: "BaseSweep") -> None:
+    with _ACTIVE_SWEEPS_LOCK:
+        _ACTIVE_SWEEPS.add(sweep)
+
+
+def _deregister_active_sweep(sweep: "BaseSweep") -> None:
+    with _ACTIVE_SWEEPS_LOCK:
+        _ACTIVE_SWEEPS.discard(sweep)
+
+
+def _iter_parent_chain(sweep: "BaseSweep"):
+    seen = set()
+    current = getattr(sweep, "parent", None)
+    while current is not None and current not in seen:
+        yield current
+        seen.add(current)
+        current = getattr(current, "parent", None)
+
+
+def _is_related_sweep(a: "BaseSweep", b: "BaseSweep") -> bool:
+    if a is b:
+        return True
+    for parent in _iter_parent_chain(a):
+        if parent is b:
+            return True
+    for parent in _iter_parent_chain(b):
+        if parent is a:
+            return True
+    return False
+
+
+def _has_other_active_sweep(sweep: "BaseSweep") -> bool:
+    with _ACTIVE_SWEEPS_LOCK:
+        active = list(_ACTIVE_SWEEPS)
+    for other in active:
+        if other is sweep:
+            continue
+        state = getattr(getattr(other, "progressState", None), "state", None)
+        if state in (SweepState.RUNNING, SweepState.RAMPING):
+            if _is_related_sweep(sweep, other):
+                continue
+            return True
+    return False
+
+
+def _kill_other_active_sweeps(sweep: "BaseSweep") -> int:
+    """Kill all unrelated active sweeps and return how many were killed."""
+    with _ACTIVE_SWEEPS_LOCK:
+        active = list(_ACTIVE_SWEEPS)
+    killed = 0
+    for other in active:
+        if other is sweep:
+            continue
+        if _is_related_sweep(sweep, other):
+            continue
+        try:
+            other.kill()
+            killed += 1
+        except Exception:
+            pass
+    return killed
+
 
 class BaseSweep(QObject):
     """The parent class for the 0D, 1D and 2D sweep classes.
@@ -376,6 +443,7 @@ def _enter_running_state(self, *, reset_elapsed: bool) -> float:
         self._mark_done_deferred = False
         self._run_started_at = now
         self.progressState.state = SweepState.RUNNING
+        _register_active_sweep(self)
         return now
 
     def pause(self):
@@ -388,6 +456,15 @@ def pause(self):
             self._add_runtime_since_last_resume()
         self.progressState.state = SweepState.PAUSED
         self.send_updates()
+        # If this is an inner/child sweep, pause the parent as well to keep states consistent
+        parent = getattr(self, "parent", None)
+        if parent is not None and parent is not self:
+            try:
+                parent_state = getattr(getattr(parent, "progressState", None), "state", None)
+                if parent_state in (SweepState.RUNNING, SweepState.RAMPING):
+                    parent.pause()
+            except Exception:
+                pass
 
     def stop(self):
         """Stop/pause the sweep. Alias for pause() for backward compatibility.
@@ -411,6 +488,7 @@ def kill(self):
         # ERROR state transitions to KILLED since user explicitly called kill()
         if progress_state is not None and progress_state.state not in (SweepState.DONE, SweepState.KILLED):
             self.progressState.state = SweepState.KILLED
+        _deregister_active_sweep(self)
         if hasattr(self, "_error_completion_pending"):
             self._error_completion_pending = False  # Clear to prevent stale flag
 
@@ -454,6 +532,29 @@ def check_running(self):
         """Returns the status of the sweep."""
         return self.progressState.state in (SweepState.RUNNING, SweepState.RAMPING)
 
+    def start_force(self, *args, **kwargs):
+        """Kill other unrelated active sweeps, then start this sweep."""
+        if not self.progressState.is_queued:
+            _kill_other_active_sweeps(self)
+        return self.start(*args, **kwargs)
+
+    @staticmethod
+    def list_active_sweeps():
+        """Return a snapshot of active sweeps for debugging."""
+        with _ACTIVE_SWEEPS_LOCK:
+            active = list(_ACTIVE_SWEEPS)
+        info = []
+        for sweep in active:
+            state = getattr(getattr(sweep, "progressState", None), "state", None)
+            info.append(
+                {
+                    "type": sweep.__class__.__name__,
+                    "state": state.name if state is not None else None,
+                    "sweep": sweep,
+                }
+            )
+        return info
+
     def start(self, persist_data=None, ramp_to_start=False):
         """Starts the sweep by creating and running the worker threads.
 
@@ -465,6 +566,10 @@ def start(self, persist_data=None, ramp_to_start=False):
             Optional argument which gradually ramps each parameter to the starting
             point of its sweep. Default is true for Sweep1D and Sweep2D.
         """
+        if not self.progressState.is_queued and _has_other_active_sweep(self):
+            raise RuntimeError(
+                "Another sweep is already running. Stop or kill it before starting a new sweep, use start_force() to kill others, or use SweepQueue to stack sweeps."
+            )
         if self.progressState.state in (SweepState.RUNNING, SweepState.RAMPING):
             self.print_main.emit("We are already running, can't start while running.")
             return
@@ -540,6 +645,10 @@ def start(self, persist_data=None, ramp_to_start=False):
     def resume(self):
         """Restarts the sweep after it has been paused."""
         if self.progressState.state == SweepState.PAUSED:
+            if not self.progressState.is_queued and _has_other_active_sweep(self):
+                raise RuntimeError(
+                    "Another sweep is already running. Stop or kill it before resuming this sweep, use start_force() to kill others, or use SweepQueue to stack sweeps."
+                )
             self._enter_running_state(reset_elapsed=False)
             self.send_updates(no_sp=True)
         else:
@@ -614,6 +723,7 @@ def mark_done(self) -> None:
         if self.progressState.state == SweepState.RUNNING:
             self._add_runtime_since_last_resume()
         self.progressState.state = SweepState.DONE
+        _deregister_active_sweep(self)
         self.send_updates()
         self.completed.emit()
 
@@ -639,6 +749,7 @@ def mark_error(self, error_message: str, _from_runner: bool = False) -> None:
             self._add_runtime_since_last_resume()
         self.progressState.state = SweepState.ERROR
         self.progressState.error_message = error_message
+        _deregister_active_sweep(self)
 
         # Propagate error to parent sweep (e.g., Sweep2D when inner Sweep1D fails)
         parent = getattr(self, "parent", None)

src/measureit/sweep/base_sweep.py

@@ -405,6 +405,7 @@ def ramp_to(self, vals_dict, start_on_finish=False, persist=None, multiplier=1):
             ),
             suppress_output=self.suppress_output,
         )
+        self.ramp_sweep.parent = self
         # Only follow parameters that are not being ramped to avoid circular dependencies
         follow_params = [p for p in self._params if p not in ramp_params_dict.keys()]
         if follow_params:

src/measureit/sweep/simul_sweep.py

@@ -506,6 +506,7 @@ def ramp_to(self, value, start_on_finish=False, persist=None, multiplier=1):
             save_data=False,
             plot_data=self.plot_data,
         )
+        self.ramp_sweep.parent = self
         self.ramp_sweep.follow_param(self._params)
 
         self.progressState.state = SweepState.RAMPING

src/measureit/sweep/sweep1d.py

@@ -401,6 +401,7 @@ def ramp_to(self, value, start_on_finish=False, persist=None, multiplier=1):
             save_data=False,
             plot_data=self.plot_data,
         )
+        self.ramp_sweep.parent = self
 
         self.progressState.state = SweepState.RAMPING
         self.ramp_sweep.start(ramp_to_start=False)

src/measureit/sweep/sweep1d_listening.py

@@ -673,6 +673,7 @@ def ramp_to(self, value, start_on_finish=False, multiplier=1):
             save_data=False,
             plot_data=True,
         )
+        self.ramp_sweep.parent = self
         for p in self._params:
             if p is not self.set_param:
                 self.ramp_sweep.follow_param(p)
@@ -705,6 +706,7 @@ def ramp_to_zero(self):
             inter_delay=self.inter_delay,
             complete_func=self.done_ramping,
         )
+        self.ramp_sweep.parent = self
         self.ramp_sweep.follow_param(self._params)
         self.progressState.state = SweepState.RAMPING
         self.outer_ramp = True

src/measureit/sweep/sweep2d.py

@@ -134,6 +134,28 @@ def close_qcodes_instruments_between_tests():
             pass
 
 
+@pytest.fixture(autouse=True, scope="function")
+def clear_active_sweeps():
+    """Clear the active sweeps registry before and after each test.
+
+    This prevents the concurrency guard from blocking tests that create
+    multiple sweeps across different test functions.
+    """
+    try:
+        from measureit.sweep.base_sweep import _ACTIVE_SWEEPS, _ACTIVE_SWEEPS_LOCK
+        with _ACTIVE_SWEEPS_LOCK:
+            _ACTIVE_SWEEPS.clear()
+    except ImportError:
+        pass
+    yield
+    try:
+        from measureit.sweep.base_sweep import _ACTIVE_SWEEPS, _ACTIVE_SWEEPS_LOCK
+        with _ACTIVE_SWEEPS_LOCK:
+            _ACTIVE_SWEEPS.clear()
+    except ImportError:
+        pass
+
+
 @pytest.fixture(autouse=True, scope="function")
 def cleanup_qt_threads():
     """Clean up any lingering QThreads after each test to prevent segfaults.