Scan settings¶

Provides information on how to access a device.

Wait for callback completion?
Check a readback?
- Which one? The original device, or a different one?
- Look for exact match, or use a tolrance of +- 0.5?
With what timeout?

When installing the scan client library, derive your site-specific implementation from the ScanSettings class and make it available to all users of this library.

Example¶

from scan.util.scan_settings import ScanSettings, setScanSettings

# Note how we replace the original Set() and Wait() commands with those that utilize ScanSettings
from scan.util.scan_settings import SettingsBasedSet as Set
from scan.util.scan_settings import SettingsBasedWait as Wait

class MyScanSettings(ScanSettings):
    """Example for site-specific scan settings."""
    def __init__(self):
        super(MyScanSettings, self).__init__()

        # Define special settings for some devices
        # based on regular expressions for the PV names
        
        # All temperature controllers use completion, but there's no readback to check
        self.defineDeviceClass(".*temp.*", completion=True, readback=False, timeout=300)

        # Special device with dedicated reachback PV
        self.defineDeviceClass("MyXYZDevice:setpoint", readback="MyXYZDevice:readback",
                               timeout=10, tolerance=0.5)

        # Motors should use completion, and readback.
        # Name of readback is based on motor name, see getReadbackName()
        self.defineDeviceClass("pos.*", completion=True, readback=True, timeout=100)
        
        # When waiting for this counter, use 'increase by' instead of '='
        self.defineDeviceClass("PerpetualCounter", comparison='increase by')
        
    def getReadbackName(self, device_name):
        # Motors use their *.RBV field for readback
        if device_name.startswith("pos"):
            return device_name + ".RBV"
        return device_name

if __name__ == "__main__":
    print "Without scan settings:"
    cmds = [
            Set('temperature', 10),
            Wait('PerpetualCounter', 10),
           ]
    for cmd in cmds:
        print cmd
    # Result:
    # Set('temperature', 10)
    # Wait('PerpetualCounter', 10, comparison='>=')
      
    setScanSettings(MyScanSettings())
    
    print "With scan settings:"
    cmds = [
            Set('temperature', 10),
            Wait('PerpetualCounter', 10),
           ]
    for cmd in cmds:
        print cmd
    # Result:    
    # Set('temperature', 10, completion=True, timeout=300)
    # Wait('PerpetualCounter', 10, comparison='increase by')

API¶

class scan.util.scan_settings.DeviceSettings(name, completion=False, readback=False, readback_value=None, timeout=0.0, tolerance=None, comparison='>=', parallel=False)¶

Describes how a device should be accessed in a scan.

Parameters

name – Device name
completion – True to use completion
readback – False to not use a readback, True to use the primary name, Actual read back name if different from the promary device name.
readback_value – None to check against written value, otherwise custom readback number or string value.
timeout – Time out for callback and readback in seconds. 0 to wait forever.
tolerance – Tolerance for numeric readback comparison.
comparison – Comparison to use in Wait commands
parallel – Perform in parallel?

getComparison()¶

Returns: Comparison for Wait command.

getCompletion()¶

Returns: True when device should be accessed with completion.

getName()¶

Returns: Device name.

getParallel()¶

Returns: To be performed in parallel.

getReadback()¶

Returns: Device name to use for readback, or None.

getReadbackValue()¶

Returns: None to check against written value, otherwise custom readback number or string value.

getTimeout()¶

Returns: Timeout in seconds for both completion and readback.

getTolerance()¶

Returns: Tolerance for numeric readback check. Does not apply to string values.

class scan.util.scan_settings.ScanSettings¶

Base class for site-specific scan settings

defineDeviceClass(name_pattern, completion=False, readback=False, readback_value=None, timeout=0.0, tolerance=None, comparison='>=')¶

Define a class of devices based on name

Call this in the constructor of your derived class.

The order of registration matters. First, define generic settings, for example for “.*” to set the general defaults. Then register more and more specific patterns, until eventually registering specific device names.

Parameters

name_pattern – Device name pattern (regular expression)
completion – True to use completion
readback – False to not use a readback, True to use the primary name, Actual read back name if different from the promary device name.
readback_value – None to check against written value, otherwise custom readback number or string value.
timeout – Time out for callback and readback in seconds. 0 to wait forever.
tolerance – Tolerance for numeric readback comparison.
comparison – Comparison to use in Wait commands.

getDefaultSettings(name)¶

Get the default settings for a device

Parameters: name – Name of device
Returns: DeviceSettings for that device.

getReadbackName(device_name)¶

Override this method to provide custom readback names.

For example, map from device names that match the naming convention for motors at your site and return the associated *.RBV name.

Parameters: device_name – Primary device name
Returns: Corresponding device name for readback check

loadDeviceClasses(json_filename)¶

Load device classes from JSON file

Parameters: json_filename – Name of JSON file

Example file content:

{
   ".*daq.*": { "completion": true },
   "pcharge": { comparison": "increase by" },
   "setpoint": { "completion": true, 
                 "tolerance": 0.1, 
                 "readback": "readback"}
}

parseDeviceSettings(prefixed_device)¶

Parse a device name that may be prefixed with modifiers.

For example, the name ‘SomeMotor’ may ordinarily indicate a motor and by default be accessed with callback completion and readback if you called parseDeviceSettings(‘SomeMotor’).

By adding the prefix ‘-c-r’ or ‘-cr’, the DeviceSettings will exclude the completion and readback: parseDeviceSettings(‘-cr SomeMotor’).

Supported modifiers:

-c: Do not await completion
+c: Do await completion
-r: Do not check readback
+r: Do check readback
+p: Access in parallel

Parameters: prefixed_device – Name of device with optional prefixes
Returns: DeviceSettings

scan.util.scan_settings.SettingsBasedLoop(prefixed_device, start, end, step, body=None, *args, **kwargs)¶

Set a device to various values in a loop.

Optional check of completion and readback verification.

Parameters

device – Device name
start – Initial value
end – Final value
step – Step size
body – One or more commands

Defaults to ScanSettings, but allows overrides for the following parameters:

Parameters

completion – Await callback completion?
readback – False to not check any readback, True to wait for readback from the ‘device’, or name of specific device to check for readback.
tolerance – Tolerance when checking numeric readback. Defaults to 0.
timeout – Timeout in seconds, used for completion and readback check.
errhandler – Error handler

scan.util.scan_settings.SettingsBasedSet(prefixed_device, value, **kwargs)¶

Set a device to a value.

Parameters

device – Device name
value – Value

Defaults to ScanSettings, but allows overrides for the following parameters:

Parameters

completion – Await callback completion?
readback – False to not check any readback, True to wait for readback from the device, or name of specific device to check for readback.
readback_value – None to check against written value, otherwise custom readback number or string value.
tolerance – Tolerance when checking numeric readback.
timeout – Timeout in seconds, used for completion and readback.
errhandler – Error handler

scan.util.scan_settings.SettingsBasedWait(prefixed_device, value, **kwargs)¶

Wait until a condition is met, i.e. a device reaches a value.

Parameters

device – Name of PV or device.
value – Desired value.

Defaults to ScanSettings, but allows overrides for the following parameters:

Parameters

comparison – How current value is compared to the desired value. Options: ‘=’, ‘>’, ‘>=’, ‘<’ , ‘<=’, ‘increase by’,’decrease by’
tolerance – Tolerance used for numeric comparison. Defaults to 0, not used for string values.
timeout – Timeout in seconds. Default 0 to wait ‘forever’.
errhandler – Default None.

scan.util.scan_settings.getScanSettings()¶

Returns: Global scan settings

scan.util.scan_settings.setScanSettings(settings)¶: Set global scan settings :param settings: Desired global scan settings

Table of Contents

Previous topic

Next topic

This Page

Scan settings¶

Example¶

API¶