The action module

Object-oriented representation of interactions with instruments.

An Action is an operation on an instrument to set data, retrieve data, or both. The following types of actions are supported by this module.

Action:

An Action is some operation which should be performed on an instrument. It serves as the base class of several types of container actions. Normally, an instance of Action will perform some simple read or write operation on the instrument.

ActionScan:

An ActionScan is a container for other Action objects which executes its children at each value of some parameter.

ActionSimultaneous:

An ActionSimultaneous is a container for other Action objects which spawns threads for each of its children and begins those threads at the same time so that they run in parallel.

Parameter:

A Parameter is an atomic input or output. It consists of the value of the input (typically set by the user) or output (typically set by the Instrument which actually carries out the Action which owns the it), information to indicate to the user what it represents, a string to determine how to format its numeric values, and directions regarding how and where the data should be saved.

Classes

Action

class src.core.action.Action(experiment, instrument, name, description, inputs=None, outputs=None, string=None, method=None)

A single action to perform a simple get/set/query on an instrument.

Parameters :

experiment : Experiment

The Experiment object to which this action belongs.

instrument : Instrument

The Instrument object which will perform this action (though not necessarily its children).

name : str

A short name with no special characters except (possibly) an underscore, to use for looking up this action.

description : str

A short phrase to indicate what this action does.

inputs : list of Parameter

A list of Parameter objects which this action will pass to the instrument.

outputs : list of Parameter

A list of Parameter objects which the instrument will fill in and pass back to this action to be processed and, in most cases, written to the appropriate files.

string : str

A template string which can be filled in with input values to provide the user with a specific description of what this action will do.

method : instancemethod

The method bound to instrument which will actually carry out this action.

Methods

allowsChildren()

Return whether this action can have children.

Since members of the Action class (i.e. not a derived class) are simple actions, they cannot have children.

cleanupAfterExecution()

Cleanup after execution.

clone()

Duplicate this action.

Produce a new Action instance—with a new location in memory—which is the same as this one in all respects. This is for copy-and-paste operations.

execute(obeyPause=True)

Execute the action.

If the experiment has been aborted, return. If it is paused, wait. Otherwise, execute the action, and then save the data to the file.

Parameters :

obeyPause : bool

Whether to wait until the experiment is no longer paused before executing the action.

getDescription()

Return the description of the action.

getInputColumns()

Return the input columns.

Returns :

list of str :

A list of strings representing the names of the columns or parameters to which the input values will be saved when the action is executed.

getInputProperties()

Return the input properties for the action.

Returns :

list of dict :

A list of dictionaries containing information about the input parameters. The following keys will be present.

• description
• column (name of the column or parameter)
• value (as a formatted string)
• allowed
• formatString

getInstrument()

Return the instrument bound to this action.

Returns :

Instrument :

The Instrument object bound to this action.

getInstrumentName()

Return the name of the instrument which will perform the action.

Returns :

str :

A string indicating the name of the Instrument which will perform the action.

getName()

Return the name of the action.

getOutputColumns()

Return the output column names.

Returns :

list of str :

A list of strings representing the names of the columns or parameters to which the output values will be saved when the action is executed.

getOutputProperties()

Return the output properties for the action.

Returns :

list of dict :

A list of dictionaries. Each dictionary corresponds to one output and contains the following keys:

• ‘description’
• ‘column’
• ‘allowed’

getTreeString(depth=0)

Return a descriptive string with appropriate indentation.

getXML(indent=0)

Return an XML string representing the action.

Returns :

str :

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

instantiate()

Instantiate all parameters, establishing the necessary data storage.

Create the appropriate data bins—based on the default names of the input/output columns and parameters—in the experiment file (using the instantiate method of the Parameter class).

isEnabled()

Get whether this action will be executed when the experiment is run.

Returns :

bool :

Whether this action will actually be executed.

isEqualEnough(otherSpec)

Determine whether the other action is interchangeable with this one.

To decide whether some action can be reasonably bound to a different instrument, consider whether the two actions have the same description, the same name, and input and output arrays. Two arrays are said to be ‘the same’ if there is a one-to-one mapping of parameters between them where the two parameters have the same name, description, and format strings.

prepareToExecute()

Prepare to execute by creating a substitution dictionary.

printme(depth=0)

Print a descriptive string with appropriate indentation.

replaceStringInInput(inputIndex, original, replacement)

Perform a string replacement in one of the inputs for this action.

The primary purpose of this method is to update expressions (either for calculations or for conditionals) to reflect changes in the names of columns, parameters, or constants.

Parameters :

inputIndex : int

The index in the list of input parameters of the parameter where the replacement should take place.

original : str

The string which should be replaced.

replacement : str

The string which should go in place of original.

setEnabled(enabled)

Set whether this action will actually be executed.

Parameters :

enabled : bool

Whether to execute this action when the experiment is run.

setExperiment(newExperiment)

Set the experiment which owns this action and its parameters.

Parameters :

newExperiment : Experiment

The Experiment object which should own this action.

setInputColumns(inputColumns)

Set the input columns.

Set the column names (or parameter names) to which the input values will be saved when the action is executed.

Parameters :

inputColumns : list of str

A list of strings representing the names of the columns or parameters to which the input values should be saved when the action is executed.

setInputValues(inputValues)

Set the values which will be sent to the Instrument object.

setInstrument(inst)

Bind an new instrument to this action.

Parameters :

inst : Instrument

The Instrument object which will perform the action.

setOutputColumns(outputColumns)

Set the output column names.

Set the column names (or parameter names) to which the output values will be saved when the action is executed.

setStatusMonitor(statusMonitor)

Set the status monitor for the action.

Parameters :

statusMonitor : StatusMonitor

The new StatusMonitor object for this action.

trash()

Destroy the action.

Set all of the bin (column or parameter) names to blanks, which removes them from the owning experiment’s relevant dictionaries.

ActionPostprocessor

class src.core.action.ActionPostprocessor(experiment, instrument, name, description, method, sourceFile)

An action for postprocessor events.

The postprocessor actions all follow the same format. They take a single argument: a list of tuples representing the files created by the experiment. Note that all postprocessor actions are executed together at the end of the experiment.

Methods

clone()

Duplicate this action.

Produce a new Action instance—with a new location in memory—which is the same as this one in all respects. This is for copy-and-paste operations.

execute(obeyPause=True)

Add the action to the experiment’s postprocessor action queue.

Parameters :

obeyPause : bool

Whether to wait until the experiment is no longer paused before executing the action.

executeReal()

Actually execute the action.

If the experiment has been aborted, return. If it is paused, wait. Otherwise, execute the action, and then save the data to the file.

Parameters :

obeyPause : bool

Whether to wait until the experiment is no longer paused before executing the action.

ActionContainer

class src.core.action.ActionContainer(experiment, instrument, name, description, inputs=None, outputs=None, string='Do nothing.', method=None)

An abstract action which may have children.

Parameters :

experiment : Experiment

The Experiment object to which this action belongs.

instrument : Instrument

The Instrument object which will perform this action (though not necessarily its children).

name : str

A short name with no special characters except (possibly) an underscore, to use for looking up this action.

description : str

A short phrase to indicate what this action does.

inputs : list of Parameter

A list of Parameter objects which this action will pass to the instrument.

outputs : list of Parameter

A list of Parameter objects which the instrument will fill in and pass back to this action to be processed and, in most cases, written to the appropriate files.

string : str

A template string which can be filled in with input values to provide the user with a specific description of what this action will do.

method : instancemethod

The method bound to instrument which will actually carry out this action.

Methods

appendChild(child)

Add a child to the end of the list.

Parameters :

child : Action

The child to add to the end of the list.

cleanupAfterExecution()

Cleanup temporary data after execution.

clone()

Copy this action, including its children.

Produce a new Action instance—with a new location in memory—which is the same as this one in all respects. Then do the same for all children, adding them to the new container. This is for copy-and-paste operations.

execute(obeyPause=True)

Execute all children objects sequentially.

executePass(obeyPause=True)

Execute the container using its superclass’s method.

getChildren()

Return the list of children.

Returns :

list of Action :

The list of actions which are considered to be children of this action.

getTreeString(depth=0)

Return a descriptive string for the container, including children.

insertChild(index, child)

Add an action to the list of children at a specified position.

Parameters :

index : int

The position at which to add the child. If index is out of range, the action is appended to the list.

child : Action

The action to add to the list.

insertChildAfter(child, positionAction)

Insert a child before another child.

Parameters :

child : Action

The action which should be inserted.

positionAction : Action

The action after which the new child should be added. If this action does not exist, child will be appended to the list.

insertChildBefore(child, positionAction)

Insert a child before another child.

Parameters :

child : Action

The action which should be inserted.

positionAction : Action

The action before which the new child should be added. If this action does not exist, child will be prepended to the list.

prepareToExecute()

Prepare all children for execution.

Preparing for execution means generating dictionaries for substitution into instrument methods and performing various other relevant optimization-related actions.

prependChild(child)

Add a child to the beginning of the list.

Parameters :

child : Action

The child to add to the beginning of the list.

printme(depth=0)

Return a descriptive string for the container, including children.

removeChild(child)

Remove the a child action from the list.

Parameters :

child : Action

The action to remove from the list.

removeChildByIndex(index)

Remove the action at the specified position.

Parameters :

index : int

The position of the child to remove.

removeChildren()

Empty the list of actions.

replaceChild(index, child)

Replace the child action at a given position

Parameters :

index : int

The position of the action to replace.

child : Action

The action which should go in the specified position.

setChildren(replacementChildren)

Replace the list of children with a new list.

Parameters :

replacementChildren : list of Action

A list of actions which should be used as children of this action. It will replace any actions already considered to be children.

setExperiment(newExperiment)

Set the owner of this action, its children, and its parameters.

Parameters :

newExperiment : Experiment

The Experiment object which should own this action, its children, and its parameters.

setStatusMonitor(newStatusMonitor)

Set the status monitor for the action and its children.

Parameters :

statusMonitor : StatusMonitor

The new StatusMonitor object for this action.

trash()

Destroy all children, then destroy the container.

ActionScan

class src.core.action.ActionScan(experiment, instrument, name, description, inputs=None, outputs=None, string='Do nothing.', method=None)

A action which executes other actions at multiple values of a parameter.

Create a scanning action—one which executes a series of other actions (children) at each value of some varied parameter. The only input should be a list of tuples, where each tuple contains three numbers: the starting and ending bounds and step size for a scan (in that order).

Parameters :

experiment : Experiment

The Experiment object to which this action belongs.

instrument : Instrument

The Instrument object which will perform this action (though not necessarily its children).

name : str

A short name with no special characters except (possibly) an underscore, to use for looking up this action.

description : str

A short phrase to indicate what this action does.

inputs : list of Parameter

A list of Parameter objects which this action will pass to the instrument. For an ActionScan, this list should contain a single element.

outputs : list of Parameter

A list of Parameter objects which the instrument will fill in and pass back to this action to be processed and, in many cases, written to the appropriate files.

string : str

A template string which can be filled in with input values to provide the user with a specific description of what this action will do.

method : instancemethod

The method bound to instrument which will actually carry out this action.

Methods

cleanupAfterExecution()

Cleanup temporary data after execution.

execute(obeyPause=True)

Execute the ActionScan.

Expand the scans into the individual values for which the action’s method will be executed, and then execute the method with each of those values.

prepareToExecute()

Prepare the ActionScan to execute by expanding the range.

static zeroWithinTolerance(dif, tolerance)

Return whether a number is small enough to be treated as zero.

Parameters :

dif : float

The number to compare to zero.

tolerance : float

The maximum difference between two numbers for them to be called equal.

ActionLoopTimed

class src.core.action.ActionLoopTimed(experiment, instrument, name, description, duration)

A container which repeats its children for a specified length of time.

Parameters :

experiment : Experiment

The Experiment instance which owns this loop.

instrument : Instrument

The Instrument which will carry out this action.

name : str

A short name with no special characters except (possibly) an underscore, to use for looking up this action.

description : str

A short phrase to indicate what this action does.

duration : float

The amount of time, in seconds, after which the loop should stop.

Notes

At the end of each cycle, the system determines how much time has elapsed. If the time elapsed is greater than or equal to the specified time, the loop is interrupted and the sequence resumes. Therefore, it is possible (and even likely) that the loop will run somewhat longer than specified. Precisely how much longer will be determined by the run time of the children.

Methods

clone()

Return a copy of this action.

execute(obeyPause=True)

Execute the loop action.

getDuration()

Return the time after which the loop will stop.

Returns :

float :

The time, in seconds, after which the loop will stop running. Depending on the run time of the children, the loop may run longer than the specified time.

setDuration(duration)

Set how long the loop should run.

Parameters :

duration : float

The length of time after which the loop will stop running. The loop may run longer than the specified time, depending on the run time of the children. But after the specified time, no new iterations of the loop will be started.

ActionLoopIterations

class src.core.action.ActionLoopIterations(experiment, instrument, name, description, iterations)

A container which repeats its children a specified number of times.

Parameters :

experiment : Experiment

The Experiment instance which owns this loop.

instrument : Instrument

The Instrument which will carry out the action (though not necessarily its children).

name : str

A short name with no special characters except (possibly) an underscore, to use for looking up this action.

description : str

A short phrase to indicate what this action does.

iterations : int

The number of times the children should be executed.

Methods

clone()

Return a copy of this action.

execute(obeyPause=True)

Execute the loop action.

getIterations()

Return the number of times the loop’s children will be executed.

Returns :

int :

The number of times the children will be executed.

setIterations(iterations)

Set how long the loop should run.

Parameters :

iterations : int

The number of times the children should be executed.

ActionLoopWhile

class src.core.action.ActionLoopWhile(experiment, instrument, name, description, expression, timeout=None)

A container which repeats its children a specified number of times.

Parameters :

experiment : Experiment

The Experiment instance which owns this loop.

instrument : Instrument

The Instrument which will carry out the action (though not necessarily its children).

name : str

A short name with no special characters except (possibly) an underscore, to use for looking up this action.

description : str

A short phrase to indicate what this action does.

expression : str

An expression which can evaluate to a boolean. The loop continues as long as expression evaluates to True.

timeout : float

The maximum amount of time, in seconds, to wait for the expression to evaluate to True. If timeout is set to None, the loop will run until expression becomes false or until the experiment is aborted.

This is a fail-safe to prevent infinite loops (for example, if you set it to run until a desired temperature is reached, but the cryostat is unable to reach that temperature).

Methods

clone()

Return a copy of this action.

execute(obeyPause=True)

Execute the loop action.

getExpression()

Return the conditional which determines the number of iterations.

Returns :

str :

The expression which will be evaluated to a boolean value to determine whether to keep looping. If it evaluates to True, the loop continues. Otherwise, it terminates.

getTimeout()

Return the maximum time to wait for the condition to become False.

Returns :

float :

The maximum time in seconds that the system will wait for the condition to return False. If it is set to None, the loop will run until the condition returns False or until the experiment is aborted.

setExpression(expression)

Set the conditional expression which determines when to stop.

Parameters :

expression : str

The expression which will be evaluated to a boolean value to determine whether to keep looping. If it evaluates to True, the loop continues. Otherwise, it terminates.

setTimeout(timeout)

Set the maximum time to wait for the condition to become false.

Parameters :

timeout : float

The maximum time in seconds that the system will wait for the condition to return False. If it is set to None, the loop will run until the condition returns False or until the experiment is aborted.

ActionLoopUntilInterrupt

class src.core.action.ActionLoopUntilInterrupt(experiment, instrument, name, description)

A container to execute its children until manually interrupted.

Parameters :

experiment : Experiment

The Experiment instance which owns this loop.

instrument : Instrument

The Instrument which will carry out this action.

name : str

A short name with no special characters except (possibly) an underscore, to use for looking up this action.

description : str

A short phrase to indicate what this action does.

Methods

clone()

Return a copy of this action.

execute(obeyPause=True)

Execute the loop action.

setLoopCommands(loopEnterCommands=None, loopExitCommands=None)

Set the commands to execute when the loop begins and finishes.

Parameters :

loopEnterCommands : list of Command

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

loopExitCommands : list of Command

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

ActionSimultaneous

class src.core.action.ActionSimultaneous(experiment, instrument, name, description)

A container which executes all of its children in parallel.

Parameters :

experiment : Experiment

The Experiment object which owns this action container.

instrument : Instrument

The Instrument which will perform this action.

name : str

A short name with no special characters except (possibly) an underscore, to use for looking up this action.

description : str

A short phrase to indicate what this action does.

Methods

clone()

Return a copy of this action.

execute(obeyPause=True)

Execute the children simultaneously.

If the experiment has been stopped, return. If the experiment is paused, wait until it is not. Otherwise, create threads for all of the action’s children. Then tell the Experiment to activate the temporary buffer for storing the data. Then start the threads, and wait for them to finish. Finally, tell the Experiment that the simultaneously- running actions are finished so that it will save the data and empty the buffer.

Parameters :

obeyPause : bool

The indication of whether the action should wait if the experiment is paused.

Parameter

class src.core.action.Parameter(experiment, name, description, formatString='%.6e', binName=None, binType=None, value=0, allowed=None, instantiate=False, isScan=False)

An input/output and information to identify, format, and describe it.

Parameters :

experiment : Experiment

The Experiment object which owns the Action for which this is a parameter.

name : str

A short, one-word name used for substitutions into the Action object’s descriptive template string.

description : str

A relatively short phrase describing the purpose of this parameter.

formatString : str

A standardized string indicating how values should be formated (e.g., “%.3e” for an exponential-format number with three decimal places). If this parameter represents a scan profile, the formatString should end with ‘[]’.

binName : str

The default name of the data column or parameter slot into which this parameter’s data should be saved.

binType : str

The default type of slot for saving data. It may be ‘column’, ‘parameter’, if the data is not to be saved by default, or None or ‘’.

value : various

The default value of the parameter. Its type depends on the parameter (it could be a floating-point number, an integer, a boolean, a string, or a list of 3-tuples of integers or floats).

allowed : list of str

A list of strings representing the allowed values for the parameter. If it is None, any type-appropriate value will be accepted.

instantiate : bool

Whether to immediately alter the experiment’s column or parameter database.

Methods

allowedValues

Return a copy of the list of allowed values.

binName

Return the name of the storage bin.

If the value is to be stored in a column, return the column name simply. If it is to be stored as a parameter, return the parameter name prefixed by the _PARAM_. Return None if the data is not to be saved.

clone()

Return a copy of this parameter.

getFormattedValue()

Return the value formatted as a string.

getXML(indent=0)

Return an XML string representing the parameter.

Returns :

str :

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

instantiate()

Instantiate the parameter.

If this method has not been run previously, set the bin names using the method (as opposed to simply changing the value of the variable), which passes the name change to the experiment to update the data storage dictionaries.

saveData()

Save the parameter to the relevant file (data or parameter).

value

Return a copy of the value of the parameter.

ActionThread

class src.core.action.ActionThread(action, obeyPause=True)

A thread for executing sub-actions without blocking.

Methods

run()

Execute the action.

Functions

src.core.action.constructAction(actionSpec)

Construct an action from an action specification.

Parameters :

actionSpec : ActionSpec

An instance of the namedtuple class ActionSpec.

Returns :

Action :

The instance of Action or one of its subclasses specified by actionSpec.

src.core.action.constructParameter(parameterSpec, isScan=False)

Construct a parameter from a parameter specification.

Parameters :

parameterSpec : ParameterSpec

An instance of the namedtuple class ParameterSpec.

Returns :

Parameter :

The instance of Parameter specified by parameterSpec.

src.core.action.nullFunction()

Do nothing.

src.core.action.cloneParameterList(parameterList)

Clone a list of input or output parameters.

src.core.action.coerceIntThroughFloat(number)

Convert a number to a float and then to an int.

Certain kinds of string literals cannot be cast directly to integers. This function takes such a string and converts it to a float and then to an integer.

Parameters :

number : str

A string containing a number which should be cast to an integer.