py4sci

Table Of Contents

Previous topic

Log Data

Next topic

Table Scan

This Page

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?
  • readbackFalse 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?
  • readbackFalse 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