System Variables¶

In addition to being a central component of user-created experiments, variables play a crucial role in the overall configuration and function of MWorks. The following system-defined variables are always present (even before an experiment has been loaded) and serve a variety of purposes.

Configuration¶

#allowAltFailover¶

Controls MWorks’ behavior when an I/O device fails to initialize but specifies an alternative, “failover” device in its alt parameter. If this variable is set to a true value (e.g 1 or true), MWorks will attempt to use the failover device in place of the failed one. Otherwise, the failover device is ignored.

#mainScreenInfo¶

The value of this variable is a dictionary whose key/value pairs describe and configure the stimulus display.

The following keys are recognized. If a key is omitted, the default value is used:

Key	Description	Default value
`display_to_use`	Integer indicating which physical display to use as the main stimulus display. 0 indicates the primary display (e.g. where the macOS dock is located), 1 or greater selects a secondary display, and a negative value indicates that only the mirror window should be used (useful for testing experiments on a laptop).	`0`
`width`	Width of the main display (in arbitrary units)
`height`	Height of the main display (in the same units as `width`)
`distance`	Distance from the center of the main display to the experimental subject’s eye (in the same units as `width` and `height`)
`refresh_rate_hz`	Refresh rate of the main display in hertz (required, but currently unused)
`always_display_mirror_window`	True or false, indicating whether the stimulus display mirror window should be enabled or disabled. When enabled, the mirror window “mirrors” the main stimulus display, allowing you to observe the stimulus presentation even if the main display is in another room or otherwise not visible.	`false`
`mirror_window_base_height`	Height of the mirror window in points. The width is chosen to match the aspect ratio specified by `width` and `height`.
`use_color_management`	True or false, indicating whether the stimulus display pipeline should perform color management. If color management is enabled, stimuli are rendered in a “linearized” sRGB color space, and each frame is converted to the target display’s color space before being presented. Otherwise, rendering takes place in the (typically non-linear) color space of the display, and no color conversion is performed.	`true`
`set_display_gamma`	True or false, indicating if the display’s gamma function should be set using the values specified by `red_gamma`, `green_gamma`, and `blue_gamma`. Applies only when `use_color_management` is false.	`false`
`red_gamma`	Inverse of red channel gamma (must be greater than zero)
`green_gamma`	Inverse of green channel gamma (must be greater than zero)
`blue_gamma`	Inverse of blue channel gamma (must be greater than zero)
`make_window_opaque`	True or false, indicating whether the stimulus display window should be opaque. If the window is not opaque, and the experiment includes a Stimulus Display device whose `background_alpha_multiplier` parameter is less than 1, then the display background and/or application windows beneath the stimulus window will show through it. Does not affect the mirror window, which is always opaque.	`true`

The width, height, and distance values are used to compute the angular field of view covered by the main display. The bounds of the field of view (in degrees) are reported by MWorks when the experiment is loaded, e.g.:

Display bounds set to (-26.4631 left, 26.4631 right, 16.5394 top, -16.5394 bottom)

Within an experiment, the bounds can be obtained via the display_bounds function. Visual stimuli are drawn within these bounds, with their position and size given in degrees.

Changes to this variable affect the next experiment loaded.

#realtimeComponents¶

The value of this variable is a dictionary, where each key identifies a core realtime service (clock, scheduler, or state system), and the corresponding value is the name of a plugin that provides that service.

The following keys and values are allowed. If a key is omitted, the default value is used:

Key	Default value	Alternative value(s)
`clock`	`HighPrecisionClock`	`SimpleClock`
`scheduler`	`ZenScheduler`
`state_system`	`ZenStateSystem`

Changes to this varible take effect when the server is restarted.

#serverName¶

The value of this variable is a string containing an arbitrary, user-specified name for the system running MWServer. This name is displayed by MWClient when connected to the server.

#stopOnError¶

If this variable is set to a true value, a running experiment will stop automatically when an error is reported.

#warnOnSkippedRefresh¶

If this variable is set to a true value, a warning is issued whenever the stimulus presentation skips a display refresh cycle.

Experiment State¶

#announceAssertion¶

When an assertion fails, the value of this variable is set to a string containing the associated error message.

#announceBlock¶

The initial value of this variable is 0. When the running experiment enters a block, the value is increased by 1. When execution of the block is complete, the value is decreased by 1. Hence, the value indicates the number of (nested) blocks currently executing.

#announceCalibrator¶

Used to announce changes to the state of a calibrator, e.g. acquistion of a new sample or recalculation of fit parameters. The value is a dictionary containing the name of the calibrator, the type of update, and the relevant sample data or parameter values.

#announceCurrentState¶

When the experiment is running, this variable contains the numeric identifier of the component (i.e. paradigm component or action) that is currently executing. The component codec provides the mapping between numeric component identifiers and component names.

#announceMessage¶

Used to log messages (generated by the system or the user) to the event stream. The value of this variable is a dictionary containing the message text, plus some metadata for internal use.

#announceSound¶

Used to announce that a sound has started playing. The value of this variable is a dictionary containing the name and parameters of the relevant sound stimulus.

#announceTrial¶

The initial value of this variable is 0. When the running experiment enters a trial, the value is increased by 1. When execution of the trial is complete, the value is decreased by 1. Hence, the value indicates the number of (nested) trials currently executing.

#loadedExperiment¶

Used to record the source file(s) of the currently-loaded experiment to the event stream and event file.

If the current experiment was loaded from an XML source file, the value of this variable is a string containing the file’s content.

If the current experiment was loaded from an MWEL source file, the value of this variable is a dictionary. The keys in the dictionary are file paths, and the values are strings containing the corresponding file’s content. The dictionary includes entries for both the primary source file and any files it includes (either directly or indirectly).

#state_system_mode¶

Used to announce the execution state of the current experiment. The value of this variable is an integer, corresponding to one of four possible states:

Value	State	Description
`0`	Idle	Experiment is not executing
`1`	Stopping	Experiment execution is ending. I/O devices and other components should perform shutdown and cleanup tasks as needed.
`2`	Running	Experiment is currently executing
`3`	Paused	Experiment is executing, but execution is currently paused. Stimulus presentation and sound playback are paused, but I/O devices continue to operate normally.

#stimDisplayUpdate¶

Used to announce updates to the visual stimulus presentation.

The value of this variable is a list. Each element in the list is a dictionary containing the name and parameters of a stimulus that is currently being displayed. The order of the list matches the draw order of the stimuli.

The time stamp of a #stimDisplayUpdate event is the operating system’s best guess for when the rendered frame containing the reported stimuli will start to appear on the display.

Internal¶

#experimentLoadProgress¶

Used to provide MWClient with an estimate of the fraction of an experiment that has been loaded.

#requestCalibrator¶

Used by MWClient’s eye calibrator window to request updates to a calibrator’s parameters.

System Event Codes¶

The following event codes have no associated variables but do appear in the event stream and event file:

Code	Internal name	Description
0	RESERVED_CODEC_CODE	Used to announce the variable codec (i.e. the mapping from event codes to variables)
1	RESERVED_SYSTEM_EVENT_CODE	Used for internal communication between MWServer and MWClient
2	RESERVED_COMPONENT_CODEC_CODE	Used to announce the component codec (i.e. the mapping from numeric component identifiers to component names)
3	RESERVED_TERMINATION_CODE	Last event sent to the event stream or recorded to the event file before the stream or file is closed. Has no associated value.