Optional "pulse" waveform option for galvo (#1226)

* Optional "pulse" waveform option for galvo

Pretty basic pulse, delayed by camera delay and lasting sweep time duration.

Goal is to have a simple pulse which can run the resonant galvo while acquiring.

* Document and correct galvo pulse waveform

Expose the new galvo pulse waveform in the configuration selector and user documentation so NI and synthetic galvo users can choose it explicitly.

The underlying single_pulse waveform expects delay and pulse_width values as percentages of the sweep, but the galvo pulse branch was passing camera_delay / sweep_time as a fractional ratio. Convert the camera delay to percent before calling single_pulse and derive the remaining pulse width from that percent value.

Add a regression test that uses the real SyntheticGalvo adjust path with a 10 ms camera delay over a 100 ms sweep. The test verifies the pulse starts after the expected delay and remains active for the rest of the sweep.

Validation: python -m pytest -o addopts='' test/model/devices/galvo/test_galvo_base.py test/model/test_waveforms.py -q; ruff check/format on changed Python files; git diff --check.

* Need [0] at the end of single_pulse

Last sample in single_pulse must be zero to clear the buffer, or else the galvo never shuts off.

I did this before by making the pulse width max 99%, but better to just set the last sample to zero.

---------

Co-authored-by: Kevin M. Dean <kevin.dean@utsouthwestern.edu>

Author: conorhughmcfadden

docs/source/02_user_guide/01_supported_hardware/galvo.rst

@@ -15,7 +15,12 @@ National Instruments
 Multiple types of galvanometers have been used, including Cambridge Technologies/Novanta, Thorlabs, and ScannerMAX. Each of these devices are externally controlled via analog signals delivered from an NI-based data acquisition card.
 
 For NI and synthetic galvos, the software supports the following waveform options:
-``sawtooth``, ``sine``, ``halfsaw``, ``quadratic``, and ``centered_cubic``.
+``sawtooth``, ``sine``, ``halfsaw``, ``quadratic``, ``centered_cubic``, and
+``pulse``.
+
+The ``pulse`` waveform is useful for resonant galvos and other devices that need
+a constant analog command during acquisition. It waits for the configured camera
+delay, then holds the configured galvo amplitude for the rest of the sweep.
 
 .. collapse:: Configuration File
 
@@ -38,7 +43,7 @@ For NI and synthetic galvos, the software supports the following waveform option
                   channel: PXI6259/ao1
                   min: -1.0
                   max: 1.0
-                waveform: square
+                waveform: pulse
                 phase: 0
 
 |
@@ -118,7 +123,7 @@ galvo.
                   channel: PXI6259/ao1
                   min: -1.0
                   max: 1.0
-                waveform: square
+                waveform: pulse
                 phase: 0
 
 |

src/navigate/config/configuration_database.py

@@ -492,6 +492,7 @@
     "Sine": "sine",
     "Sawtooth": "sawtooth",
     "Square": "square",
+    "Pulse": "pulse",
 }
 
 galvo_hardware_widgets = {

src/navigate/model/devices/galvo/base.py

@@ -38,7 +38,13 @@
 # Third Party Imports
 
 # Local Imports
-from navigate.model.waveforms import centered_cubic, quadratic, sawtooth, sine_wave
+from navigate.model.waveforms import (
+    centered_cubic,
+    quadratic,
+    sawtooth,
+    sine_wave,
+    single_pulse,
+)
 from navigate.tools.decorators import log_initialization
 
 # # Logger Setup
@@ -173,7 +179,6 @@ def adjust(
 
             # Only proceed if it is enabled in the GUI
             if channel["is_selected"] is True:
-
                 # Get the Waveform Parameters - Assumes ETL Delay < Camera Delay.
                 # Should Assert.
                 exposure_time = exposure_times[channel_key]
@@ -190,7 +195,7 @@ def adjust(
                     factor_name = None
                     if galvo_factor == "channel":
                         factor_name = (
-                            f"Channel {channel_key[channel_key.index('_')+1:]}"
+                            f"Channel {channel_key[channel_key.index('_') + 1 :]}"
                         )
                     elif galvo_factor == "laser":
                         factor_name = channel["laser"]
@@ -247,6 +252,19 @@ def adjust(
                         offset=galvo_offset,
                         phase=self.device_config["phase"],
                     )
+                elif self.galvo_waveform == "pulse":
+                    pulse_delay = 100 * self.camera_delay / self.sweep_time
+                    pulse_width = 100 - pulse_delay
+                    pulse_wave = single_pulse(
+                        sample_rate=self.sample_rate,
+                        sweep_time=self.sweep_time,
+                        pulse_width=pulse_width,
+                        amplitude=galvo_amplitude,
+                        offset=galvo_offset,
+                        delay=pulse_delay,
+                    )
+                    pulse_wave[-1] = 0
+                    self.waveform_dict[channel_key] = pulse_wave
                 elif self.galvo_waveform == "halfsaw":
                     new_wave = sawtooth(
                         sample_rate=self.sample_rate,

test/model/devices/galvo/test_galvo_base.py

@@ -229,6 +229,32 @@ def test_adjust_halfsaw_uses_expected_extreme(amplitude, source_wave):
     assert waveforms["channel_1"][1] == pytest.approx(source_wave[1])
 
 
+def test_adjust_pulse_waveform_respects_camera_delay():
+    config = build_base_configuration(
+        waveform="pulse",
+        amplitude="1.0",
+        offset="0.0",
+        max_voltage=10,
+        min_voltage=-10,
+        channel_2_selected=False,
+    )
+    config["configuration"]["microscopes"]["TestScope"]["camera"]["delay"] = 10
+    config["configuration"]["microscopes"]["TestScope"]["daq"]["sample_rate"] = 1000
+    galvo = build_synthetic_galvo(config)
+
+    waveforms = galvo.adjust(
+        exposure_times={"channel_1": 0.2},
+        sweep_times={"channel_1": 0.1},
+    )
+
+    waveform = waveforms["channel_1"]
+    high_indices = np.flatnonzero(waveform > 0.5)
+    assert waveform.shape == (100,)
+    assert high_indices[0] == 10
+    assert high_indices[-1] == 99
+    assert len(high_indices) == 90
+
+
 def test_adjust_unknown_waveform_sets_channel_to_none():
     config = build_base_configuration(waveform="banana", channel_2_selected=False)
     galvo = build_synthetic_galvo(config)