feat: add an oscilloscope simulator tool

CHANGELOG.md

@@ -36,3 +36,4 @@ All notable changes to this project will be documented in this file.
 - Let DataLab's generic launcher run the recipes on Desktop, replacing the two-channel role dialog; reference and measured channels are still proposed from their labels.
 - Pair the laser warm-up demonstration with both the stability and single-channel campaign methods; example parameter values are now keyed by method.
 - Document how to set shot numbers and channel labels on your own signals with DataLab's Add metadata dialog (`doc/preparing-signals.md`).
+- Add an oscilloscope simulator tool, in DataLab Desktop and DataLab-Web: a laser pulse, an amplifier step or a delayed pulse pair seen through a time base, vertical scales and an n-bit ADC, with a live view, and acquisitions tagged for the Pulse methods (`doc/oscilloscope-simulator.md`).

README.md

@@ -14,6 +14,8 @@ The plugin offers five methods, each with its own generated demonstration:
 
 The new methods are documented in [`doc/shot-stability.md`](doc/shot-stability.md), [`doc/step-response.md`](doc/step-response.md), [`doc/two-channel-delay.md`](doc/two-channel-delay.md) and [`doc/pulse-height-spectrum.md`](doc/pulse-height-spectrum.md). Every demonstration is validated against its simulator truth in `tests/validation`. None of these conventions claims compliance with a standard.
 
+In DataLab Desktop and DataLab-Web, the **Oscilloscope simulator** tool acquires laser pulses, amplifier steps or delayed pulse pairs through a time base, vertical scales and an n-bit ADC, with a live view of the screen. Its acquisitions carry the shot and channel metadata the methods expect. See [`doc/oscilloscope-simulator.md`](doc/oscilloscope-simulator.md).
+
 ## Development
 
 ```bash

doc/oscilloscope-simulator.md

@@ -0,0 +1,47 @@
+# Oscilloscope Simulator
+
+The Pulse application includes a simulated oscilloscope. It is a DataLab tool: open it from the Pulse page of the **Applications** catalog (**Tools** section), or from the **Plugins > Pulse & Transient Characterization** menu of the signal panel. It works the same way in DataLab Desktop and DataLab-Web.
+
+The window shows the oscilloscope screen on the left and the settings on the right. Every change of a setting refreshes the screen. **Live** refreshes it continuously: each refresh is a new trigger, so jitter and noise show as on a real oscilloscope. **Acquire** records a series of triggers and adds them to the workspace, in a new group per acquisition; the window stays open for the next acquisition.
+
+## Settings
+
+Connect a source first (**Source** tab), then set the oscilloscope (**Oscilloscope** tab). Settings that do not apply to the selected source are greyed out.
+
+- **Source.**
+  - Laser pulse seen by a photodiode: Gaussian or asymmetric pulse, with an optional linear drift of its time and amplitude over one acquisition.
+  - Amplifier step response: response of a second-order system, set by its natural frequency and damping ratio.
+  - Pulse pair: a reference pulse on CH1 and the delayed, wider pulse of a detector on CH2.
+  - For every source: amplitude, amplitude jitter and trigger jitter. The pulse pair adds the detector delay, gain, pulse width and its own jitter.
+- **Oscilloscope.**
+  - Horizontal: time base (ns/div, ten divisions), sample rate and trigger position. The trigger is at t = 0; the trigger position is the part of the record before it.
+  - Vertical: scale (V/div, eight divisions) and offset of CH1 and CH2, ADC resolution and input noise. The offset is the voltage at the center of the screen.
+  - Acquisition: number of triggers per acquisition, and the random seed.
+
+The ADC codes the screen only: a trace that leaves the screen is clipped, then quantized on 2^bits levels. The summary below the screen gives the peak of each channel and its number of clipped samples. Times are in ns and voltages in V, for every source.
+
+The seed and the acquisition number fix the noise and jitter of each acquisition: the same settings give the same acquisitions in a new session.
+
+One acquisition is limited to 5 million samples (all signals together), which keeps DataLab-Web within the browser memory.
+
+## Acquired Signals
+
+Signals are named `CH1 shot 001`, `CH1 shot 002`, and so on; with the pulse pair, the CH2 signals follow the CH1 ones. Each signal carries the metadata the Pulse methods expect:
+
+- `plugin.org.datalab.pulse-characterization.shot`: the trigger number, from 1;
+- `plugin.org.datalab.pulse-characterization.channel`: `CH1` or `CH2`;
+- `plugin.org.datalab.pulse-characterization.synthetic` and `.simulation_seed`, which record the simulated origin.
+
+So an acquisition can be analyzed right away:
+
+| Source | Methods |
+| --- | --- |
+| Laser pulse | Single-channel pulse campaign, shot-to-shot stability |
+| Amplifier step response | Step response |
+| Pulse pair | Two-channel delay and jitter |
+
+The two-channel method measures the delay between 50 % crossings. With the default asymmetric detector pulse, this delay is shorter than the delay between pulse peaks set in the source.
+
+## Limits
+
+The trigger is external and synchronized with the source: there is no trigger level, slope or rearm logic. There is no bandwidth limit, no probe model and no acquisition mode other than a series of single triggers. The simulator helps learning the methods and checking a workflow; it does not replace measurements on a real bench.

doc/simulation.md

@@ -5,6 +5,8 @@ exact settings used for every waveform. It is designed to exercise the normal
 Sigima-backed analysis path with reproducible drift, jitter, noise, and quality
 failures. It is not a calibrated oscilloscope model.
 
+In DataLab, the oscilloscope simulator tool acquires pulses, amplifier steps and delayed pulse pairs interactively, through a time base and a digitizing front end. See [`oscilloscope-simulator.md`](oscilloscope-simulator.md).
+
 ## Waveform Model
 
 Every acquisition uses the same evenly sampled X axis. Regular shots alternate

src/datalab_pulse_characterization/adapters/desktop.py

@@ -25,6 +25,7 @@
     TWO_CHANNEL_DEMO,
     materialize_generated_example,
 )
+from ..simulator import OSCILLOSCOPE_SIMULATOR_TOOL, OscilloscopeSimulator
 from ..workflow import (
     PULSE_CAMPAIGN_RECIPE,
     PULSE_HEIGHT_RECIPE,
@@ -59,6 +60,7 @@ class PulseTransientCharacterizationPlugin(PluginBase):
     )
     RECIPES = WORKFLOW_RECIPES
     EXAMPLES = DEMO_EXAMPLES
+    TOOLS = (OSCILLOSCOPE_SIMULATOR_TOOL,)
     WELCOME_TILES = (
         WelcomeTile(
             id="application",
@@ -81,6 +83,10 @@ def materialize_example(cls, example_id: str) -> PluginExampleData | None:
         cls.get_example(example_id)
         return materialize_generated_example(example_id)
 
+    def oscilloscope_simulator(self) -> OscilloscopeSimulator:
+        """Return a new oscilloscope simulator."""
+        return OscilloscopeSimulator()
+
     def open_demo_campaign(self) -> PluginExample | None:
         """Open the demonstration campaign from the plugin menu."""
         return self.launch_example(PULSE_DEMO.id)

src/datalab_pulse_characterization/adapters/web.py

@@ -24,6 +24,7 @@
     build_simulated_campaign,
     materialize_generated_example,
 )
+from ..simulator import OSCILLOSCOPE_SIMULATOR_TOOL, OscilloscopeSimulator
 from ..workflow import (
     PULSE_CAMPAIGN_RECIPE,
     PulseCampaignRecipeParameters,
@@ -55,10 +56,15 @@ class PulseTransientCharacterizationWebPlugin(PluginBase):
     )
     RECIPES = WORKFLOW_RECIPES
     EXAMPLES = DEMO_EXAMPLES
+    TOOLS = (OSCILLOSCOPE_SIMULATOR_TOOL,)
 
     def create_actions(self) -> None:
         """Application actions are provided by DataLab-Web's generic host."""
 
+    def oscilloscope_simulator(self) -> OscilloscopeSimulator:
+        """Return a new oscilloscope simulator."""
+        return OscilloscopeSimulator()
+
     @classmethod
     def materialize_example(cls, example_id: str) -> PluginExampleData | None:
         """Build one deterministic generated example in memory."""