core Package

core Package

NICOS core APIs and classes.

device Module

Base device classes for usage in NICOS.

class nicos.core.device.AutoDevice

Bases: object

Abstract mixin for devices that are created automatically as dependent devices of other devices.

class nicos.core.device.Device(name, **config)

Bases: object

An object that has a list of parameters that are read from the configuration and have default values.

Subclasses can implement:

• doPreinit()
• doInit()
• doShutdown()
• doVersion()

User methods

version()

Return a list of versions for this device.

Parameters

description (str, settable at runtime)

A description of the device. Default value: ''.

loglevel (str, settable at runtime, initialized for preinit)

The logging level of the device. Default value: 'info'.

lowlevel (bool, not shown to user)

Whether the device is not interesting to users. Default value: False.

class nicos.core.device.DeviceMeta

Bases: type

Bases: type

A metaclass that automatically adds properties for the class’ parameters, and determines a list of user methods (“commands”).

It also merges attached_devices, parameters and parameter_overrides defined in the class with those defined in all base classes.

class nicos.core.device.HasLimits(name, **config)

Bases: nicos.core.device.Moveable

Bases: Moveable

Mixin for “simple” continuously moveable devices that have limits.

Parameters

abslimits (a tuple of (float, float), mandatory in setup)

Absolute limits of device value. Unit: same as device value.

userlimits (a tuple of (float, float), settable at runtime)

User defined limits of device value. Default value: (0.0, 0.0). Unit: same as device value.

Parameters inherited from the base classes: description, fixed, fmtstr, loglevel, lowlevel, maxage, pollinterval, target, unit

class nicos.core.device.HasOffset

Bases: object

Mixin class for Readable or Moveable devices that want to provide an ‘offset’ parameter and that can be adjusted via adjust().

This is not directly a feature of Moveable, because providing this transparently this would mean that doRead() returns the un-adjusted value while read() returns the adjusted value. It would also mean that the un-adjusted value is stored in the cache, which is wrong for monitoring purposes.

Instead, each class that provides an offset must inherit this mixin, and subtract/add self.offset in doRead()/doStart().

Parameters

offset (float, settable at runtime)

Offset of device zero to hardware zero. Default value: 0.0. Unit: same as device value.

class nicos.core.device.HasPrecision

Bases: object

Mixin class for Readable and Moveable devices that want to provide a ‘precision’ parameter.

This is mainly useful for user info, and for high-level devices that have to work with limited-precision subordinate devices.

Parameters

precision (float, settable at runtime)

Precision of the device value. Default value: 0.0. Unit: same as device value.

class nicos.core.device.Measurable(name, **config)

Bases: nicos.core.device.Readable

Bases: Readable

Base class for devices used for data acquisition.

Subclasses need to implement:

• doRead()
• doSetPreset(**preset)
• doStart(**preset)
• doStop()
• doIsCompleted()

Subclasses can implement:

• doPause()
• doResume()
• doTime()
• doSimulate()

User methods

isCompleted()

Return true if measurement is complete.

pause()

Pause the measurement, if possible.

read(maxage=None)

Return a tuple with the result(s) of the last measurement.

resume()

Resume paused measurement.

setPreset(**preset)

Set the new standard preset for this detector.

start(**preset)

Start measurement, with either the given preset or the standard

stop()

Stop measurement now.

wait()

Wait for completion of the measurement.

Parameters inherited from the base classes: description, fmtstr, loglevel, lowlevel, maxage, pollinterval, unit

class nicos.core.device.Moveable(name, **config)

Bases: nicos.core.device.Readable

Bases: Readable

Base class for moveable devices.

Subclasses need to implement:

• doStart(value)

Subclasses can implement:

• doStop()
• doWait()
• doIsAllowed()
• doTime()

User methods

fix(reason='')

Fix the device: don’t allow movement anymore.

isAllowed(pos)

Check if the given position can be moved to.

maw(target)

Move to target and wait for completion.

move(pos)

Start movement of the device to a new position.

release()

Release the device, i.e. undo the effect of fix().

start(pos)

Start movement of the device to a new position.

stop()

Stop any movement of the device.

wait()

Wait until movement of device is completed.

Parameters

fixed (str, settable at runtime, not shown to user)

None if the device is not fixed, else a string describing why. Default value: ''.

target (any value)

Last target position of a start() action. Default value: 'unknown'. Unit: same as device value.

Parameters inherited from the base classes: description, fmtstr, loglevel, lowlevel, maxage, pollinterval, unit

class nicos.core.device.Readable(name, **config)

Bases: nicos.core.device.Device

Bases: Device

Base class for all readable devices.

Subclasses need to implement:

• doRead()
• doStatus()

Subclasses can implement:

• doReset()
• doPoll()
• valueInfo()

User methods

read(maxage=None)

Read the (possibly cached) main value of the device.

reset()

Reset the device hardware. Returns the new status afterwards.

status(maxage=None)

Return the (possibly cached) status of the device.

Parameters

fmtstr (str, settable at runtime)

Format string for the device value. Default value: '%.3f'.

maxage (None or a float in the range [0.000000, 86400.000000], settable at runtime)

Maximum age of cached value and status (zero to never use cached values, or None to cache them indefinitely). Default value: 6. Unit: s.

pollinterval (None or a float in the range [0.500000, 86400.000000], settable at runtime)

Polling interval for value and status (or None to disable polling). Default value: 5. Unit: s.

unit (str, settable at runtime, mandatory in setup)

Unit of the device main value.

Parameters inherited from the base classes: description, loglevel, lowlevel

nicos.core.device.requires(**access)

Decorator to implement user access control.

The access is checked based on the keywords given. Currently, the keywords with meaning are:

• 'level': gives the minimum required user access level and can have the values GUEST, USER or ADMIN as defined in the nicos.core.utils module.
• 'mode': gives the required exection mode (“master”, “slave”, “maintenance”, “simulation”).
• 'passcode': only usable in the interactive console: gives a passcode that the user has to type back.

The wrapper function calls Session.checkAccess to verify the requirements. If the check fails, AccessError is raised.

nicos.core.device.usermethod(func)

Decorator that marks a method as a user-visible method.

The method will be shown to the user in the help for a device.

errors Module

Exception classes for usage in NICOS.

class nicos.core.errors.AccessError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when an action is forbidden to the current user.

Used by the requires decorator.

class nicos.core.errors.CacheLockError(locked_by)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when a cache lock cannot be acquired.

class nicos.core.errors.CommunicationError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when some hardware communication fails.

class nicos.core.errors.ComputationError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when a computation fails.

Examples are the conversion of physical values to logical values.

class nicos.core.errors.ConfigurationError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when an error in the setup is detected, or a device is supplied with invalid configuration data.

class nicos.core.errors.HardwareError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised on fatal hardware errors.

class nicos.core.errors.InvalidValueError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when the user gives an invalid value to a device (as a move target or parameter value).

class nicos.core.errors.LimitError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when a requested move target is out of limits.

class nicos.core.errors.ModeError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when an action is not allowed in the current execution mode.

class nicos.core.errors.MoveError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when errors occur while moving a device.

class nicos.core.errors.NicosError(*args, **kwds)

Bases: exceptions.Exception

Bases: Exception

The basic exception class for exceptions raised by NICOS.

Every NicosError subclass has a “category” attribute, a string that is shown to the user instead of the exception class.

The constructor also accepts a Device instance as its first argument, which is then used to display the error to the user as coming from this device. For example:

def doRead(self):
    if not self._ready:
        raise NicosError(self, 'device is not ready')

The constructor accepts a the keyword wikicode with an integer argument to create a link to a wiki page

https://trac.frm2.tum.de/projects/NICOS/wiki/NicosError/<integer>

where more information can be given. The integer should be the Unix timestamp (e.g from date +%%s, to get a uniqe id) of the first use of this specific error. To create the wiki page, log in to trac and enter ‘wiki:NicosError/<integer>’ in the search box on the upper right.

class nicos.core.errors.PositionError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when a device detects an undefined position.

For example, this should be raised when several coders do not agree.

class nicos.core.errors.ProgrammingError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when an error in the code is detected.

This should not occur during normal operation.

class nicos.core.errors.TimeoutError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when a timeout waiting for hardware occurs.

This is not a communication timeout; for that purpose CommunicationError should be used.

class nicos.core.errors.UsageError(*args, **kwds)

Bases: nicos.core.errors.NicosError

Bases: NicosError

Exception to be raised when user commands are used wrongly.

When this exception is caught by the user command handler, the help for the command that was executed is shown.

params Module

Parameter definition helpers and typechecking combinators.

class nicos.core.params.Override(**kw)

Bases: object

This class defines the overridden properties of a base class parameter.

The Device.parameter_overrides attribute contains a mapping of parameter names to instances of this class.

Overriding parameters allows to share parameters with the base class, but still have slightly different behavior for the parameters. For example, for a general Moveable device the unit parameter is mandatory. However, for some subclasses this will not be necessary, since the unit can either be automatically determined from the device, or the value never has any unit. Instead of redefining the unit parameter in subclasses, you only need to override its mandatory property in the subclass like this:

parameter_overrides = {'unit': Override(mandatory=False)}

The constructor takes all keywords that the Param constructor accepts. These properties of the parameter are then overridden compared to the base class.

apply(paraminfo)

class nicos.core.params.Param(description, type=<type 'float'>, default=<object object at 0x4037e760>, mandatory=False, settable=False, volatile=False, unit=None, category=None, preinit=False, prefercache=None, userparam=True)

Bases: object

This class defines the properties of a device parameter.

The Device.parameters attribute contains a mapping of parameter names to instances of this class.

Attributes (equivalent to constructor arguments):

• description: a concise parameter description.
• type: the parameter type; either a standard Python type (int, float, str) or one of the type converter functions from this module that either return a value of the correct type, or raises TypeError or ValueError.
• default: a default value, in case the parameter cannot be read from the hardware or the cache.
• mandatory: true if the parameter must be given in the config file.
• settable: true if the parameter can be set by NICOS or the user after startup.
• volatile: true if the parameter should always be read from hardware. For this, a doReadParamname method on the device is needed.
• unit: unit of the parameter for informational purposes; in there, the substring ‘main’ is replaced by the device unit when presented.
• category: category of the parameter when returned by Device.info() or None to ignore the parameter. See INFO_CATEGORIES for the list of possible categories.
• preinit: whether the parameter must be initialized before Device.preinit() is called.
• prefercache: whether on initialization, a value from the cache is preferred to a value from the config – the default is true for settable parameters and false for non-settable parameters.
• userparam: whether this parameter should be shown to the user (default is True).

formatDoc()

class nicos.core.params.Value(name, type='other', errors='none', unit='', fmtstr='%.3f', active=True)

Bases: object

This class defines the properties of the “value” read from Readable and Measurable classes. Their valueInfo method must return a tuple of instances of this class.

• The name parameter is the name of the value. By convention, if only one value is returned, this is the name of the device. Otherwise, if the values are collected from subdevices, the value names should be the subdevice names. In all other cases, they should be called “devname.valuename” where devname is the device name.
• The type parameter can be one of:
  • 'counter' – some counter value
  • 'monitor' – some monitor value
  • 'time' – some timing value
  • 'other' – other numeric value
  • 'error' – standard error for previous value
  • 'info' – non-numeric info value
• The errors parameter can be one of:
  • 'none' – no errors known
  • 'next' – errors are in next value
  • 'sqrt' – counter-like value: errors are square root
• The unit parameter is the unit of the value, or ‘’ if it has no unit. This will generally be device.unit for Readables.
• The fmtstr parameter selects how to format the value for display. This will generally be device.fmtstr for Readables.
• The active parameter is reserved.

nicos.core.params.anytype(val=None)

any value

nicos.core.params.control_path_relative(val='')

nicos.core.params.convdoc(conv)

nicos.core.params.dictof(keyconv, valconv)

nicos.core.params.floatrange(fr, to)

nicos.core.params.intrange(fr, to)

nicos.core.params.listof(conv)

nicos.core.params.none_or(conv)

nicos.core.params.nonemptylistof(conv)

nicos.core.params.oneof(*vals)

nicos.core.params.oneofdict(vals)

nicos.core.params.tacodev(val=None)

a valid taco device

nicos.core.params.tupleof(*types)

nicos.core.params.vec3(val=[0, 0, 0])

a 3-vector

status Module

Status code definitions.

utils Module

NICOS core utility functions.

nicos.core.utils.formatStatus(st)

nicos.core.utils.multiStatus(devices, maxage=None)

Combine the status of multiple devices to form a single status value.

This is typically called in the doStatus method of “superdevices” that control several attached devices.

The resulting state value is the highest value of all devices’ values (i.e. if all devices are OK, it will be OK, if one is BUSY, it will be BUSY, but if one is ERROR, it will be ERROR).

The resulting state text is a combination of the status texts of all devices.

nicos.core.utils.waitForStatus(device, delay=0.29999999999999999, timeout=None, busystates=(101, ), errorstates=(104, 103))

Wait for the device status to return exit the busy state.

delay is the delay between status inquiries, and busystates gives the state values that are considered as “busy” states; by default only status.BUSY.