The experiment module

Experiment data and execution manager.

An Experiment is an object which keeps tracks of all the parts which compose an actual measurement, including instruments, the actions performed on them, the data returned by them, and real-time graphs of the data.

Classes

Experiment

class src.core.experiment.Experiment

The main driver class of an experiment.

The Experiment class is responsible for managing instruments; the actions those instruments should perform; and the collection, storage, saving, and graphing of data.

Methods

abort()

Stop the experiment and run the post-sequence actions.

activateTemporaryBuffer()

Create a temporary buffer for simultaneous blocks.

Create a temporary buffer, with the same keys as the main column dictionary, for storing data while running a simultaneous block. This alleviates the danger of getting goofy garbage in the data file due to, e.g., race conditions. The principal problem this averts is writing data to the file prematurely, which would happen if the actions return in the wrong order.

addDefaultConstants()

Add pi and the natural logarithm base to the constant dictionary.

addGraph(graph)

Add a graph to the experiment.

Store graph in the list, and bind it to the columns which will supply its data.

Parameters :

graph : Graph

A Graph object to add to the experiment.

addInstrument(instrument)

Add an instrument to this experiment.

Parameters :

instrument : Instrument

The Instrument object which should be added to the experiment.

addPostprocessorAction(action)

Add a Postprocessor action to be executed after the experiment.

Parameters :

action : ActionPostprocessor

An action to execute at the end of the experiment.

checkExpression(expr)

Check the syntactic validity of the supplied expression.

Substitute numeric values for columns, constants, and parameters and attempt to evaluate the given expression to determine whether the syntax of the expression is correct.

Parameters :

expr : str

The expression to evaluate in string form.

Returns :

bool :

True if the expression’s syntax is valid, or False otherwise.

deactivateTemporaryBuffer()

Save the data from the temporary buffer, then destroy the buffer.

Take the data stored in the temporary buffer while running the simultaneous block. If the same amount of data has been added for each column, add them to the appropriate column bins. Otherwise, save them as a separate file in the same folder as the data. Then destroy the temporary buffer.

evaluateExpression(expr, conditional=False)

Evaluate a given expression.

Substitute all defined constants and the most recent values of all columns and parameters into expr, evaluate it, and return the outcome.

This is mainly used by the Calculate action from the System class.

Parameters :

expr : str

A string giving the expression which should be evaluated.

conditional : bool

Whether the expression should evaluate to a boolean (True or False). The default is False, meaning that the expression should evaluate to a number.

Returns :

float or bool :

If conditional is True, the boolean to which the supplied expression evaluates when known data have been substituted. Otherwise, the number to which the supplied expression evaluates.

getActionRoot()

Return the root of the action tree.

Returns :

ActionContainer :

The ActionContainer object which serves as the root of the sequence tree.

getAllConstants()

Return a copy of the constants dictionary.

Returns :

dict :

A dictionary of constants in which the keys (str) are the names of the constants, and the values (float) are the values associated with the relevant constant.

getColumnDetails()

Return a formatted string containing a list of column details.

Returns :

str :

A string containing details about the current status of each data column.

getConstant(name)

Return the value of the named constant.

Parameters :

name : str

The name of the constant whose value is desired.

Returns :

float :

The value of the requested constant, or None if the constant does not exist.

getEqualEnoughInstruments(action)

Return a list of instruments which implement the given action.

Sometimes, the user may want to change the instrument which carries out a particular action. However, in order to change the instrument, it is necessary that the new instrument should have the ability to carry out the action.

This method returns a list of dictionaries with information about the instruments (and their respective actions) which could potentially be used as a replacement for the instrument associated with the specified action.

Parameters :

action : Action

The Action instance whose Instrument the user wants to replace.

Returns :

list of dict :

A list of dictionaries. Each dictionary represents information about one Action which could replace action. The elements of the dictionary are the following:

instrument_index

The index of the instrument in the experiment’s list.

instrument

The actual Instrument object.

instrument_name

The name of the instrument.

action_index

The index of the Action object which can replace action. The index corresponds to the location in the list of actions returned by the instrument’s getActions method.

action

An ActionSpec representing the Action which can replace the specified action.

Notes

Two Action objects are said to be “equal enough” if they have the same description and the same parameters. Two Parameter objects are said to be the same if they are identical in all immutable aspects (that is, they have the same name, the same description, and the same format string).

getFiles()

Return a list of all files used so far in the experiment.

Returns :

list of tuple of str :

A list of tuples. Each tuple represents one set of files opened and contains three strings. The first is a data file, the second is a parameter file, and the third is a graph file (the third can be None if no graph file was saved).

getGraph(index)

Return the graph at the specified index.

Parameters :

index : int

The position of the desired graph in the experiment’s list.

Returns :

Graph :

The graph at the specified position.

getGraphStrings()

Return a list of the names of the experiment’s graphs.

Returns :

list of str :

A list of strings, where each string is the name of a graph in the experiment.

getGraphStringsAndStates()

Return the names of graphs and whether each graph is enabled.

Returns :

str :

The title of the graph.

bool :

Whether the graph is enabled.

getInstrument(index)

Return the instrument at the specified index.

Parameters :

index : int

The index of the Instrument which should be returned.

Returns :

Instrument :

The instrument located at the specified position.

getInstrumentStrings()

Return the names of the instruments in this experiment.

Returns :

list of str :

A list of strings representing the names of the Instrument objects which used in this experiment.

getStorageBinNames()

Get the names of all data storage bins.

Returns :

list of str :

A list of the names of all constants in the experiment.

list of str :

A list of the names of all columns in the experiment.

list of str :

A list of the names of all parameters in the experiment.

getStorageBinNamesString()

Return a formatted string representing the storage bin names.

Returns :

str :

A three-line string, where the first line is a list of constants, the second is a list of columns, and the third is a list of parameters.

getXML()

Return an XML string representing the experiment.

Returns :

str :

A string containing XML data representing all of the data related to an experiment, possibly useful as an alternative to pickle.

handleStorageBins(oldName, oldType, newName, newType)

Automatically handle the addition, removal, or renaming of a bin.

If the new name is None or ‘’, delete the old bin. If the old name is None or ‘’, create the new bin. If the old name and the new name are are both non-trivial, the old name is changed to the new name, and the types are switched if necessary.

Parameters :

oldName : str

The name of the column or parameter to be removed. If none is to be removed, this should be either None or an empty string.

oldType : str

The type (“column” or “parameter”) of the bin to be removed. If a bin is to be created and none removed, this value is ignored.

newName : str

The name of the column or parameter to be created. If none is to be created, this should be either None or an empty string.

newType : str

The type (“column” or “parameter”) of the bin to be created. If none is to be created, this value is ignored.

interruptLoop()

Interrupt a running loop.

isInterrupted()

Return whether the next loop should be interrupted.

Returns :

bool :

Whether a loop has been manually interrupted.

isPaused()

Return whether the experiment has been paused.

Returns :

bool :

Whether the experiment is paused.

isRunning()

Return whether the experiment is running.

Returns :Whether the experiment is running. :

classmethod open(filename)

Open an experiment from a file.

pause()

Pause the experiment.

removeConstant(name)

Delete a defined constant.

Parameters :

name : str

The name of the constant which should be deleted.

removeGraph(graph)

Remove a graph from the experiment

First, remove graph from all columns which reference it. Then delete it from the list of graphs.

Parameters :

graph : Graph

The Graph object to remove from the list.

removeInstrument(instrument)

Remove an instrument from this experiment.

Parameters :

instrument : Instrument

The instrument which should be removed from the experiment.

renameConstant(oldName, newName)

Rename the specified constant.

Rename a constant and update all expressions in conditional loops and calculations to reflect the name change.

Parameters :

oldName : str

The name of the constant to whose name should be changed.

newName : str

The new name of the constant.

resume()

Unpause the experiment.

run(errorCheck=True)

Perform the pre-sequence actions and begin the experiment.

Parameters :

errorCheck : bool

Whether to check for errors before beginning execution. The default is True.

Raises :

GeneralExperimentError :

An exception containing a list of warnings and errors about problems with the experiment. This is only raised if errorCheck is True.

classmethod save(experiment, filename)

Save an experiment to a file.

saveData(binType, binName, value)

Add data returned from actions to the appropriate dictionary.

Take the input from the execute commands bound to an Action object and add it to the data column dictionary, the parameter dictionary, or the temporary buffer as appropriate.

Parameters :

binType : str

Where the data should go (either “parameter” or “column”).

binName : str

The name of the column or parameter.

value : str

The formatted value to be saved to the bin specified by the above parameters.

setConstant(name, value)

Set the value of a constant, creating it if necessary.

Parameters :

name : str

The name of the constant whose value should be set.

value : float

The new value for the constant.

setFilenames(basePath)

Set the filenames and open the files.

Use the supplied baseName to generate names for the data and parameter files, as well as the graph image file if applicable, by appending the appropriate extensions. Then open the files. Write the column headers to the data file and dump the parameter buffer into the parameter file.

Important: All folders in the path to the files must already exist.

Parameters :

basePath : str

The path where the data files should be stored. It should include all folders as well as a filename. The extension may be left off, but the only extensions that will be understood are ”.xdat” (the default), ”.txt” and ”.dat”.

setInteractionParameters(**kwargs)

Set how the experiment should communicate with the outside.

These parameters can be set only using keyword arguments.

Any parameter which takes a list can be disabled by setting it to an empty list. Any parameter which takes something else can be disabled by setting it to None.

Parameters :

parentFrame : Frame

A graphical frame which will be passed as the parent for the graph frames, if applicable.

graphManagerClass : GraphManager

A class (not an instance) to use for managing the graph threads, if applicable.

graphManager : GraphManager

A GraphManager object for managing the graph threads. If this is set, it will be preferred over creating a graphManagerClass.

preSequenceCommands : list of Command

A list of Command objects which should be executed immediately before the experiment begins to run.

postSequenceCommands : list of Command

A list of Command objects which should be executed immediately after the experiment has finished.

statusMonitor : statusMonitor

The new StatusMonitor object for the instruments to display information to the user.

loopEnterCommands : list of Command

The Command objects to execute before any other actions when the sequence enters an interruptable loop.

loopExitCommands : list of Command

The Command objects to execute after any other actions when an interruptable loop has been interrupted.

updateGraphColumns(graph)

Fix the column dictionary so that the graph is in the right slots.

Remove the graph from the list (which includes unbinding it from the old columns), and then add it back, automatically placing the graph in the slots for the newly-specified columns.

Parameters :

graph : Graph

The Graph object whose associated columns have changed.

ExecutionThread

class src.core.experiment.ExecutionThread(experiment)

Helper class for executing the sequence without blocking the program.

Methods

run()

Begin executing the main sequence.