BecExp#

class BecExp(trialName, config, isLoad)#

Bases: Trial

BecExp run orchestration for BEC experiments with real-time analysis.

Wires together acquisition, ROI selection, analysis modules, logging, and database updates. Supports automatic or file-watcher acquisition, 1D/2D parameter scans, figure/GUI management, and error handling for Cicero and hardware logs.

Workflow:

start(): set hardware, start acquisition or watcher, enable analyzer, initialize figures
On each run (listener): fetch/move Cicero log, update hardware/scope data, update figures
stop()/fastStop(): stop acquisition, unlock, refresh/save/close analysis figures
refresh(): recompute and redraw analysis
show()/browserShow(): display figures/GUI on chosen monitor(s)

Constructor Summary

BecExp(trialName, config, isLoad)#

Construct BecExp trial orchestrator.

Initializes atom and acquisition settings, ROI, analysis modules, log paths, and optional auto-load. When not loading, performs an initial update to set up figures and internal state.

Parameters:

trialName (string) – Human-readable trial name
config (string, optional) – Configuration entry name (default: “BecExpSetting”)
isLoad (logical, optional) – If true, construct from a saved object struct

Property Summary

Acquisition Acquisition#: Acquisition settings and hardware interface helpers

AnalysisMethod string#: Ordered list of active analysis module names

Atom Atom#: Atom object containing atomic species properties for the experiment

AveragingMethod string = "StdErr"#: Data averaging method: “None”|”StdErr”|”Std”

CiceroData struct#: Aggregated Cicero sequence variables per run from log files

CloudCenter double#: Cloud center coordinates [\(y_0\), \(x_0\)] from previous measurement [pixels]

HardwareData struct#: Aggregated hardware measurement values per run from device logs

IsDensityAverage logical = false#: Flag to control averaging when saving Od and Ad data and figures

Roi Roi#: Roi defining main region of interest for image analysis

ScannedVariable string#: Primary scanned variable name from VariableUnitSetting

ScannedVariable2 string#: Secondary scanned variable name for 2D parameter scans

ScannedVariableUnit string#: Primary scanned variable unit string

ScannedVariableUnit2 string#: Secondary scanned variable unit string for 2D scans

ScopeData struct#: Aggregated oscilloscope-derived measurement values per run

SubRoi Roi#: Optional collection of sub-ROIs for multi-region analysis

Method Summary

ScannedVariableLabel(runNumber)#

Build label strings for scanned variable names and values.

Parameters:: runNumber (double) – Run index
Returns:: [names, values] joined for display
Return type:: string

addAnalysis(newAnalysisList)#

Add new analysis modules to the experiment pipeline.

Instantiates analysis objects, applies configuration settings, and sorts them according to AnalysisOrder dependencies.

Parameters:: newAnalysisList (string) – Names of analysis modules to add

browserShow()#

Display analysis windows in browser-style layout on secondary monitor.

Arranges analysis figures and GUIs on the secondary monitor (if available) in a browser-like tiled layout for better multi-monitor workflows. Falls back to primary monitor if only one display is available.

countExistedLog()#

Count existing Cicero and hardware log files in origin directories.

Updates counters for pre-existing log files to distinguish new files generated during the current experiment run.

coutExistedHardwareLog()#

Count existing hardware log files for all configured devices.

Updates the hardware log file counters by checking each device’s data path for pre-existing log files.

deleteRun(runIdx)#

Delete run data (images, logs) and update in-memory tables.

Parameters:: runIdx (double|double[]) – Run index or indices to delete

exportToStruct(propertyFilter, opts)#

Recursively converts the class object’s properties to a struct

propertyFilter only returns object properites explicitly listed in the cell unless it is empty. Filters can be nested: Ex. {depth0_prop1, {depth0_prop2, {depth1_prop1, depth1_prop2}}} If the propertyFilter is empty {}, All object properties are returned

opts filters object properties by attribute and depth. opts will filter out elements in the propertyFilter if they have an excluded attribute

adData is only accessible after it has been written to the file AdData.mat at the DataAnalysisPath

fastStop()#

Fast stop without forced refresh; save and close analysis figures.

Similar to stop() but skips the final analysis refresh step to save time. Still performs cleanup, saves figures, and updates the database. Useful when immediate shutdown is needed.

fetchCiceroLog(runIdx)#

Wait for and move new Cicero log file from origin to trial directory.

Monitors the origin directory for new .clg files, waits up to 10 seconds for file creation, then attempts to move it to the trial log folder with proper naming convention.

Parameters:: runIdx (double) – Run number for file naming
Returns:: True if log file was successfully fetched and moved
Return type:: logical

fetchHardwareLog(runIdx)#

Trigger scope data collection and fetch hardware log files.

Commands the hardware control panel to read current scope data, then searches for and moves new hardware log files from device directories to the trial hardware log folder.

Parameters:: runIdx (double) – Run number for file naming

getVariableList(varName)#

loadScope(sName, runIdx)#

static loadobj(s)#

Reconnect DB writer and GUI handle when the object is loaded.

Returns:: Loaded object with transient handles restored when possible.
Return type:: Trial

pause()#

Pause data acquisition and disable real-time analysis.

Temporarily stops camera acquisition or file watcher and disables the analysis pipeline without closing figures or losing state.

readCiceroLog(runIdx)#

Read and deserialize Cicero log files for specified runs.

Loads binary Cicero log files (.clg) and extracts sequence variables using .NET binary formatter. Handles file access errors gracefully.

Parameters:: runIdx (double) – Run index or indices to read
Returns:: Structure with sequence variables per run, and success flag
Return type:: struct, logical

readRun(runIdx)#

Read raw image data for specified run indices.

Loads atom, light, and dark images from disk, applies bad pixel correction, and returns as a 4D array.

Parameters:: runIdx (double) – Run index or indices to read
Returns:: Image data with shape (\(N_y\), \(N_x\), \(N_\mathrm{run}\), 3)
Return type:: double

readRunRoi(runIdx)#

Read ROI-cropped image data for specified run indices.

Similar to readRun() but returns only the ROI-selected regions to reduce memory usage and improve processing speed. Uses parallel processing when available.

Parameters:: runIdx (double) – Run index or indices to read
Returns:: ROI-cropped image data with shape (\(N_{y,\mathrm{ROI}}\), \(N_{x,\mathrm{ROI}}\), \(N_\mathrm{run}\), 3)
Return type:: double

refresh(anaylsisName, isRefreshData)#

Recompute analysis data and refresh visualizations.

Reprocesses all run data through the analysis pipeline and updates figures. Can refresh all modules or start from a specific module (refreshing it and all downstream dependencies).

Parameters:: anaylsisName (string, optional) – Analysis module to start refresh from (default: all)

refreshData(anaylsisName)#

refreshFigure()#

Update all analysis figures with current data without recomputing.

Refreshes the visual display of all analysis modules using existing processed data. Faster than refresh() since it skips data recomputation.

removeAnalysis(removeAnalysisList)#

Remove analysis modules from the experiment pipeline.

Closes associated figures and removes modules from the active analysis list, then re-sorts the remaining modules.

Parameters:: removeAnalysisList (string) – Names of analysis modules to remove

resume()#

Resume data acquisition and re-enable real-time analysis.

Restarts camera acquisition or file watcher, updates log file counts, and re-enables the analysis pipeline from the paused state.

save()#

setAnalyzer()#

Set up event listener for automated analysis upon run completion.

Creates a listener that triggers analysis pipeline when new run data becomes available. The analyzer handles image renaming, log fetching, hardware updates, and figure refreshing.

setHardware()#

Configure hardware settings and upload to hardware control panel.

Reads trial-specific hardware associations from the database, updates hardware settings, and uploads configurations to the hardware control panel application.

setParameterTable()#

Load static parameter lookup tables used by the trial.

Initializes configuration tables for variable mappings, hardware settings, current values, and trial associations from the database.

show()#

Display all analysis windows on the current monitor.

Makes all analysis figure windows and GUIs visible using their default positioning and sizing settings.

sortAnalysis()#

Sort analysis modules according to execution dependencies.

Arranges active analysis modules in the order specified by AnalysisOrder to ensure proper data flow (e.g., Od before Ad).

Returns:: Sorted list of analysis module names
Return type:: string

start()#

Initialize hardware and begin data acquisition or file watching.

Sets up hardware associations, starts camera acquisition (if auto mode) or file watcher, enables the analysis pipeline, and initializes all analysis figure windows.

stop()#

Stop acquisition, finalize analysis, and clean up resources.

Stops camera or file watcher, unlocks phase locks, performs final analysis refresh (with fringe removal if enabled), saves all figures, and updates the trial database. Deletes empty trials with no runs.

unlock()#

Unlock phase locks through hardware control panel.

Attempts to disable phase locks via the hardware control panel application. Issues a warning if unlocking fails due to hardware connection issues.

updateDatabase()#

Update existing database entry with current trial state.

Updates the database record with current trial metadata, Cicero data, and hardware data using the trial’s serial number as key.

updateHardware()#: Read current hardware values into HardwareData and update UI.

updateScopeData()#

Update scope-derived measurement values from hardware logs.

Reads oscilloscope data from hardware log files and extracts measurement values (RMS, peak, etc.) for channels specified in the scanned variables or scope value analysis.

writeDatabase()#

Write trial metadata to PostgreSQL database.

Converts trial object to table format and writes to database, excluding transient analysis method references.