Dealer Class Documentation

The Dealer is a lightweight client to all the Players. It allows one script to control all the Players from one machine. The only requirement for the Dealer is the Dealer code itself, a current ZeroMQ python installation, and access to the dibas.conf configuration file.

When first run, the Dealer connects to each Player specified in dibas.conf, and dynamically obtains all the control functions exported by the Player, including KATCP and Valon functions, needed to run each Player (thus updates to the Player code will show up in the Dealer automatically). The user can then script all the Players at once, or address each one individually.

Figure 1: Dealer class diagram

Dealer documentation:

class dealer.Dealer(players=None)

Dealer brings together all Player Bank objects in one script, allowing them to be coordinated and to operate as one instrument.

add_active_player(*args)

Adds the player(s) specified in in the argument list to the active list. The arguments must be strings, the names of the players:

d.add_active_player('BANKA', 'BANKB')

add_switching_state(duration, blank=False, cal=False, sig_ref_1=False)

add_switching_state(duration, blank, cal, sig_ref_1):

Add a description of one switching phase (backend dependent).

duration

the length of this phase in seconds,

blank

the state of the blanking signal (True = blank, False = no blank)

cal

is the state of the cal signal (True = cal, False = no cal)

sig_ref_1

the state of the sig_ref_1 signal (True = ref, false = sig)

Example to set up a 8 phase signal (4-phase if blanking is not considered) with blanking, cal, and sig/ref, total of 400 mS:

d.clear_switching_states()                                                 # Bl Cal SR1
d.add_switching_state(0.01, blank = True,  cal = True,  sig_ref_1 = True)  # --   |   |
d.add_switching_state(0.09, blank = False, cal = True,  sig_ref_1 = True)  # |    |   |
d.add_switching_state(0.01, blank = True,  cal = True,  sig_ref_1 = False) # --   | |
d.add_switching_state(0.09, blank = False, cal = True,  sig_ref_1 = False) # |    | |
d.add_switching_state(0.01, blank = True,  cal = False, sig_ref_1 = True)  # -- |     |
d.add_switching_state(0.09, blank = False, cal = False, sig_ref_1 = True)  # |  |     |
d.add_switching_state(0.01, blank = True,  cal = False, sig_ref_1 = False) # -- |   |
d.add_switching_state(0.09, blank = False, cal = False, sig_ref_1 = False) # |  |   |

clear_switching_states()

resets/deletes the switching_states (backend dependent)

earliest_start()

earliest_start(self):

Returns the earliest time that all backends can be safely started. This is done by querying all the backends and selecting the furthest starttime in the future.

get_mode()

get_mode(self):

Returns the current mode, if all players agree. If not, returns a tuple consisting of (False, {bank:mode, bank:mode...})

get_param(param)

Returns the value a specified parameters, or a dictionary of parameters with their values if param is None.

param: A valid parameter name. Should be None if values for

all parameters is desired.

get_status(keys=None)

Returns the specified key’s value, or the values of several keys, or the entire contents of the shared memory status buffer. Which operation is performed depends on the type of keys:

• keys is None: The entire buffer is returned, as a dictionary containing the key/value pairs.
• keys is a list of strings: returns a dictionary containing the requested subset of key/value pairs.
• keys is a single string: a single value will be looked up and returned using ‘keys’ as the single key.

help_param(param=None)

Returns the help doc string for a specified parameters, or a dictionary of parameters with their doc strings if param is None.

param:

A valid parameter name. Should be None if help for all parameters is desired.

increment_scan_number()

Increments the current scan number

list_active_players()

Lists the players selected for use from the available player pool.

list_available_players()

Lists the available players.

list_modes()

list_modes():

Returns a list of modes available.

monitor(self)

monitor() requests that the DAQ program go into monitor mode. This is handy for troubleshooting issues like no data. In monitor mode the DAQ’s net thread starts receiving data but does not do anything with that data. However the thread’s status may be read in the status memory: NETSTAT will say ‘receiving’ if packets are arriving, ‘waiting’ if not.

prepare()

Perform calculations for the current set of parameter settings

remove_active_player(*args)

Removes the named player(s) from the active player list. The player arguments must be strings:

d.remove_active_player('BANKA', 'BANKB')

scan_status()

scan_status(self):

Returns the state of currently running scan. The return type is a dictionary of tuples, backend dependent. Each dictionary key is the Player’s name.

set_gbt_ss(period, ss_list)

set_gbt_ss(period, ss_list):

adds a complete GBT style switching signal description.

period: The complete period length of the switching signal. ss_list: A list of GBT phase components. Each component is a tuple: (phase_start, sig_ref, cal, blanking_time) There is one of these tuples per GBT style phase.

Example:

d.set_gbt_ss(period = 0.1,
             ss_list = ((0.0, SWbits.SIG, SWbits.CALON, 0.025),
                        (0.25, SWbits.SIG, SWbits.CALOFF, 0.025),
                        (0.5, SWbits.REF, SWbits.CALON, 0.025),
                        (0.75, SWbits.REF, SWbits.CALOFF, 0.025))
            )

set_mode(mode, frequency = False, force=False)

Sets the operating mode for the roach. Does this by programming the roach.

mode:

The mode name, a string; A keyword which is one of the ‘[MODEX]’ sections of the configuration file, which must have been loaded earlier.

bandwidth:

The valon frequency for this mode. If not provided, last one used on this mode will be reused. The value is originally specified in the config file.

force:

A boolean flag; if ‘True’ and the new mode is the same as the current mode, the mode will be reloaded. It is set to ‘False’ by default, in which case the new mode will not be reloaded if it is already the current mode.

Returns a dictionary of tuples, where the keys are the Player names, and the values consists of (status, ‘msg’) where ‘status’ is a boolean, ‘True’ if the mode was loaded, ‘False’ otherwise; and ‘msg’ explains the error if any.

Example:

rval = d.set_mode('MODE1')
rval = d.set_mode(mode='MODE1', force=True)

set_param(**kvpairs)

A pass-thru method which conveys a backend specific parameter to the modes parameter engine.

Example usage:

d.set_param(exposure=x,switch_period=1.0, ...)

NOTE: set_param() will set all players the same way. To set each player differently, use d (where ‘d’ is the dealer) d.players[player].set_param() for each player.

set_scan_number(scan_number)

Sets the scan number to ‘num’

set_status(self, **kwargs)

Updates the values for the keys specified in the parameter list as keyword value pairs. So:

d.set_status(PROJID='JUNK', OBS_MODE='HBW')

would set those two parameters.

start(self, starttime = None)

starttime:

a datetime with the desired start time, which should be in UTC, as that is how the player will interpret it. Default is None, in which case the start time will be negotiated with the players.

NOTE: starttime must be an offset-aware datetime. That

is, it must have time-zone information set. As it must also be UTC. For example:

import pytz
from datetime import datetime
s = datetime.utcnow()
s = s.replace(tzinfo=pytz.utc)

NOTE: start() will abort any currently running scan and restart!

stop()

Stops a running scan, or exits monitor mode.

wait_for_scan(verbose=False)

Blocks while a scan is in progress, returning only when the scan is over, or on user input.

verbose: If True will print status information every 3

seconds.