Trial#

class Trial(trialName, config, isLoad)#

Bases: handle, matlab.mixin.SetGetExactNames, dynamicprops

Trial is an abstract base class for orchestrating experiments/simulations.

Provides lifecycle management for a single run series: configuration loading, data folder setup, database logging (writer/reader), serial numbering, optional GUI integration, and file system watching to trigger analysis.

Example:

% Constructing a concrete trial
t = MyConcreteTrial("Test", "MyConfigName");
t.update();  % persist object and DB

Events:

NewRunFinishedevent
Emitted when a new data file group has been detected and completed.

Notes:

Subclasses must implement writeDatabase(), updateDatabase(), setFolder(), and setConfigProperty().

Constructor Summary

Trial(trialName, config, isLoad)#

Construct a Trial object.

Parameters:

trialName (string) – Alphanumeric name for the trial type.
config (string | table | struct) – Configuration identifier or data. If string, loads from Config.mat.

Raises:

error
If trialName is not alphanumeric or configuration cannot be found.

Property Summary

DataPath string = "."#: Full path to the trial’s data storage directory

DateTime datetime#: Date and time when the experiment or simulation was initiated

Description string = "This is a test trial."#: Human-readable description of the trial purpose and setup

Is2DScan logical#: True for two-dimensional parameter scans (computed from ScannedVariable2)

IsCompleted logical#: True when all planned runs have been completed successfully

NCompletedRun int32 = 0#: Number of experimental runs completed successfully

NRun int32 = 1#: Total number of runs planned for this trial

Name string#: Trial name identifier matching the configuration entry

ObjectPath string#: Full path to the saved trial object .mat file

ScannedVariable string#: Primary scanned parameter name (must be implemented by subclasses)

ScannedVariable2 string#: Secondary scanned parameter name for 2D scans (must be implemented by subclasses)

ScannedVariableUnit string#: Primary scanned parameter unit string (must be implemented by subclasses)

ScannedVariableUnit2 string#: Secondary scanned parameter unit string for 2D scans (must be implemented by subclasses)

SerialNumber int32#: Unique database-generated identifier for this trial instance

Method Summary

createWatcher()#

Create a file system watcher that emits :event:`NewRunFinished` per group.

Watches DataPath for created files matching DataFormat and accumulates until DataGroupSize files are seen, then notifies.

displayLog(str, logType)#

Display a log message, routed to GUI if available.

Parameters:

str (string) – Message text.
logType (string, optional) – One of “normal”, “warning”, or “error”.

static loadobj()#

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

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

struct()#

Create a plain struct snapshot of public properties for logging/DB.

Returns:: Public, serializable properties with heavy objects mapped to names.
Return type:: struct

update()#

Persist object changes and synchronize the database record.

Calls updateObject() and updateDatabase(), and writes a short description file into DataPath.

updateObject()#: Save the current object to ObjectPath.