Acquisition Module¶

Data acquisition functions for logging data from soundcards and National Instruments DAQ devices.

Main Acquisition Function¶

log_data ¶

log_data(settings, test_name=None, rec=None, output=None)

Acquire one block of time-domain data and return it as a DataSet.

Two call modes depending on settings.pretrig_samples:

No pretrigger (pretrig_samples is None): starts / reuses a stream, sleeps for settings.stored_time seconds, and returns the most recent stored_time * fs samples from the circular buffer. If output is supplied it is played in parallel (soundcard play is blocking; NI play is non-blocking and synchronized against stored_time via WaitUntilTaskDone).
Pretrigger armed (pretrig_samples set): waits up to settings.pretrig_timeout seconds for the monitored channel to cross settings.pretrig_threshold. On trigger, returns a window of stored_time * fs samples straddling the trigger sample so that pretrig_samples of pre-trigger data appears at the start of the returned buffer. On timeout with no trigger the function does not raise — it falls back to returning the tail of the buffer (same as the no-pretrigger path) with trigger_detected = False.

Parameters¶

settings : MySettings Acquisition configuration. See pydvma.options.MySettings. test_name : str or None Stored on the returned TimeData for labelling. rec : Recorder-like or None Ignored. Retained for backward compatibility with callers (the GUI's LogDataThread) that still pass a cached recorder. log_data now always rebuilds the stream via streams.start_stream(settings) so that switching device or backend between calls doesn't leave a stale recorder. output : ndarray (N_samples, output_channels) or None Optional playback signal in volts. For NI it's passed through as-is (must stay within ±output_VmaxNI). For soundcard it's divided by output_VmaxSC to recover the ±1 normalised units sounddevice expects.

Returns¶

DataSet A DataSet containing one TimeData in volts. If settings.use_output_as_ch0 is True and output was supplied, the output signal is prepended as an extra channel.

Notes¶

A clipping warning is printed when |data| > 0.95 * Vmax anywhere in the capture, where Vmax is VmaxNI on the NI path and VmaxSC on the soundcard path. Both default to behaviour equivalent to the old ±1-normalised check when the user hasn't overridden them.

Pretrigger positioning (both backends, identical logic)¶

On a successful trigger, the returned buffer is stored_time * fs samples long and the first sample exceeding pretrig_threshold sits at exactly index pretrig_samples — samples [0, pretrig_samples) are pre-trigger context. See streams.Recorder for the state machine that gives this invariant.

pretrig_samples is capped at chunk_size (validated at call-time with a ValueError); the recorder only retains that much pre-trigger context. Larger windows require a larger chunk_size.

On a trigger timeout (pretrig_timeout elapses with nothing above threshold), the function does not raise — it returns the tail of the buffer (same shape as the no-pretrigger path), leaves trigger_detected False, and prints a "not detected" message.

Signal Generation¶

output_signal ¶

output_signal(settings, output)

Play output (in volts) on the configured AO device.

For soundcard, divides by output_VmaxSC to recover the ±1 normalised float sounddevice expects. For NI, the voltage array is passed straight through to setup_output_NI (the AO task is configured with ±output_VmaxNI rails).

signal_generator ¶

signal_generator(settings, sig='gaussian', T=1, amplitude=0.1, f=None, selected_channels='all')

Create an output-ready waveform.

amplitude is in volts — the generated signal is bounded to ±amplitude and, as a safety ceiling, clipped to ±settings.output_vmax() (i.e. output_VmaxNI on the NI path, output_VmaxSC on the soundcard path). Returns (t, y) where y is shape (N, output_channels) in volts, ready to hand to log_data(..., output=y) or output_signal.

Stream Monitoring¶

stream_snapshot ¶

stream_snapshot(rec)

Capture the live oscilloscope buffer as a TimeData.

Unlike log_data, which blocks for stored_time seconds and returns a fresh capture, this is a non-blocking snapshot of the oscilloscope-side circular buffer (osc_time_data) — i.e. the most recent num_chunks * chunk_size samples already in memory. Useful for "what is the stream doing right now?" diagnostics from a notebook while a stream is running.

Parameters¶

rec : Recorder-like Retained for backward compatibility; the actual snapshot is always taken from the module-level streams.REC. Callers can pass any value (typically streams.REC itself).

Returns¶

TimeData A single TimeData instance with test_name='stream_snapshot', carrying the oscilloscope axis and the live buffer. No channel_cal_factors or units are attached (this is meant as a quick-look tool, not a calibrated capture).

Notes¶

Requires a live stream: call streams.start_stream(settings) first, or use a function like log_data that does so internally. On the soundcard path the buffer holds voltages scaled by settings.VmaxSC; on the NI path it holds raw volts.