Backend

The DIBAS is a multi-mode instrument. Modes are selected by programming the FPGA with new BOF files and initializing them according to the needs for that mode.

Each BOF file has its own set of registers which do not necessarily do the same things and are not named the same way accross BOF files. The Backend classes exist to abstract away the differences and provide a common interface to all the BOF files.

The Bank class uses a strategy pattern [strategy] to deal with each different BOF file. When a mode is selected an object that derives from Backend is constructed and handles all requests to the Backend functions. Each Backend class implements the Backend interface as appropriate. There are currently 8 backend classes:

• Backend: the base class
• GuppiBackend: incoherent mode pulsar backend based on GBT GUPPI instrument
• GuppiCODDBackend: Coherent de-dispersion mode pulsar backend, based on GBT GUPPI instrument.
• VegasBackend: Base class for the spectral line modes, based on GBT VEGAS spectrometer
• VegasHBWBackend: Instance class for the wide band spectral line modes (modes 1-3)
• VegasLBWBackend: Base class for the narrow band spectral line modes (modes 4-29)
• VegasL1LBWBackend: Instance class for the L1 lbw modes. These modes provide a fixed narrow-band window.
• VegasL8LBWBackend: Instance class for the L8 lbw modes. These modes provide 1 or 8 movable narrow-band windows.

The base class provides the interface and a fair amount of common functionality (gettting/setting status memory, roach registers, etc.) The individual derived backend classes provide the functionality that must be specific to each backend.

class Backend

class Backend.Backend(theBank, theMode, theRoach=None, theValon=None, hpc_macs=None, unit_test=False)

A base class which implements some of the common backend calculations (e.g switching).

Backend(theBank, theMode, theRoach, theValon, unit_test) Where:

theBank:

TheBankData object for this mode, containing all the data required by this backend.

theMode:

The ModeData object for this mode, containing all the data required for this mode.

theRoach:

(optional) This is a katcp_wrapper object that allows the bank to communicate with the ROACH.

theValon:

(optional) The Valon synth object.

unit_test:

(optional) True if the class was created for unit testing purposes.

_execute_phase(phase)

execute_phase(self, phase)

A super simple interpreter of commands to do things to the FPGA, such as resetting the ROACH, arming it, etc. By interpreting the string list ‘phase’ the specific sequence of commands can then be stored in a configuration file instead of being hard-coded in the code.

self: This object.

phase: a sequence of string tuples, where the first element of the tuple is the command, and the second element the parameter: [(“sg_sync, “0x12”), (“wait”, “0.5”), (“arm”, “0”), (“arm”, “1”), ...]

_ip_string_to_int(self, ip)

Converts an IP string, ie ‘170.0.0.1’, and returns an integer. If ‘ip’ is already an int, returns it.

_wait_for_status(self, reg, expected, max_delay)

Waits for the shared memory status register ‘reg’ to read value ‘expected’. Returns True if that value appears within ‘max_delay’ (milliseconds), False if not. ‘wait’ returns the actual time waited (mS), within 100 mS.

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

add_switching_state(duration, blank, cal, sig):

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

duration

the length of this phase in seconds,

blank

is 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

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

If any of the named parameters is not provided, that parameter defaults to False.

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:

be = Backend(None) # no real backend needed for example
be.clear_switching_states()
be.add_switching_state(0.01, blank = True, cal = True, sig = True)
be.add_switching_state(0.09, cal = True, sig = True)
be.add_switching_state(0.01, blank = True, cal = True)
be.add_switching_state(0.09, cal = True)
be.add_switching_state(0.01, blank = True, sig = True)
be.add_switching_state(0.09, sig = True)
be.add_switching_state(0.01, blank = True)
be.add_switching_state(0.09)

arm_roach()

arm_roach(self):

Sends a sequence of commands to arm the ROACH. This is mode dependent and mode should have been specified in advance, as the sequence of commands is obtained from the ‘MODEX’ section of the configuration file.

cleanup()

This explicitly cleans up any child processes. This will be called by the player before deleting the backend object.

clear_switching_states()

resets/deletes the switching_states (backend dependent)

disarm_roach()

disarm_roach(self):

Sends a sequence of commands to disarm the ROACH. This is mode dependent and mode should have been specified in advance, as the sequence of commands is obtained from the ‘MODEX’ section of the configuration file.

getI2CValue(addr, nbytes)

getI2CValue(addr, nbytes, data):

addr:

The I2C address

nbytes:

the number of bytes to get

Returns the IF bits used to set the input filter.

Example:

bits = self.getI2CValue(0x38, 1)

get_param(self, param)

Return the value of a parameter, if available, or None if the parameter does not exist.

param:

The parameter, a string. If not provided, or if set to None, help_param() will return a dictionary of all parameters and their doc strings.

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.

keys == None: The entire buffer is returned, as a dictionary containing the key/value pairs.

keys is a list or tuple of keys: 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(self, param)

Returns the doc string of the Backend member function that is responsible for setting the value of param, or, returns a list of all params with their doc string.

param:

The parameter, a string. If not provided, or if set to None, help_param() will return a dictionary of all parameters and their doc strings.

Returns a string, the doc string for the specified parameter, or a dictinary of all parameters with their doc strings.

hpc_cmd(cmd)

Opens the named pipe to the HPC program, sends ‘cmd’, and closes the pipe. This takes care to not block on the fifo.

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.

net_config(self, roach_ip = None, port = None)

Configures the 10Gb/s interface on the roach. This consists of sending the tap-start katcp command to initialize the FPGA’s 10Gb/s interface, and updating a couple of registers on the ROACH2 with the destination IP address and port of the HPC computer.

All the parameters to this function have ‘None’ as default values; if any is ommitted from the call the function will use the corresponding value loaded from the configuration file.

data_ip:

The IP address. Can be a string (ie ‘10.17.0.71’), or an integer of the same value (for that IP, it would be 168886343) If given as a string, is converted to the integer representation.

data_port:

The ROACH 10Gb/s port number. An integer with a 16-bit value; that is, not to exceed 65535.

dest_ip:

the IP address to send packets to; this is the 10Gb/s IP address of the HPC computer. Same format as ‘data_ip’.

dest_port:

The 10Gb/s port on the HPC machine to send data to.

prepare()

Perform calculations for the current set of parameter settings

progdev(bof=None)

progdev(self, bof, frequency):

Programs the ROACH2 with boffile ‘bof’.

bof:

A string, the name of the bof file. This parameter defaults to ‘None’; if no bof file is specified, the function will load the bof file specified for the current mode, which is specified in that mode’s section of the configuration file.. A ‘KeyError’ will result if the current mode is not set.

reset_roach()

reset_roach(self):

Sends a sequence of commands to reset the ROACH. This is mode dependent and mode should have been specified in advance, as the sequence of commands is obtained from the MODE sections of the configuration file.

round_second_up(the_datetime)

Round the provided time up to the nearest second.

the_datetime:

A time as represented by a datetime object.

scan_status()

Returns the current state of a scan.

setCalFreq(cal_freq)

This parameter records the cal on/off frequency used on the telescope, in Hz.

setFilterBandwidth(fbw)

Filter bandwidth. Must be a value in [450, 1450, 1900]

setI2CValue(addr, nbytes, data)

setI2CValue(addr, nbytes, data):

addr:

the I2C address

nbytes:

the number of bytes to send

data:

the data to send

Sets the IF bits used to set the input filter.

Example:

self.setI2CValue(0x38, 1, 0x25)

setNoiseSource(noise_source)

Turns the noise source on or off

noise_source:

one of NoiseSource.OFF (or 0), NoiseSource.ON (or 1)

setNoiseTone1(noise_tone)

Selects the noise source or test tone for channel 1

noise_tone:

one of NoiseTone.NOISE (or 0), NoiseTone.TONE (or 1)

setNoiseTone2(noise_tone)

Selects the noise source or test tone for channel 2

noise_tone:

one of NoiseTone.NOISE (or 0), NoiseTone.TONE (or 1)

setObserver(observer)

Sets the observer keyword in FITS headers and status memory.

setProjectId(project)

Sets the project id for the session. This becomes part of the directory path for the backend data in the form:

$DIBAS_DATA/<projectid>/<backend>/<data file>

setScanLength(length)

This parameter controls how long the scan will last in seconds.

setSource(source)

This parameter sets the SRC_NAME shared memory value.

setSourceRADec(radec)

This parameter sets the source’s RA & Dec.

Source RA/Dec may be specified as a string:

set_param(source_ra_dec="J141213.23+161252.12")

or:

set_param(source_ra_dec="03:14:15.9 +26:37:10.11")

setTelescope(telescope)

This parameter sets the TELESCOP shared memory value.

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:

b.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_if_bits()

Programs the I2C based on bandwidth, noise source, and noise tones. Intended to be called from Backend’s ‘prepare’ function.

set_param(self, param, value)

The DIBAS backends are directly controlled by setting registers in the FPGA, setting key/value pairs in status memory, setting the Valon and I2C controllers, etc. Low level interfaces to do all these things exist. However, there are often time and value dependencies associated between these values. set_param() provides a way to set values at a higher level of abstraction so that when the low-level values are set, the dependencies are computed and the values are set in the proper order. This is therefore a high-level method of setting instrument parameters.

Once all parameters are set a call to prepare() will cause the dependencies to be computed and the values sent to their respective destinations.

If a parameter is given that does not exist, the function will throw an exception that includes a list of the available parameters (see help_param() as well).

This function is normally called by the Bank.set_param(**kvpairs) member.

param:

A keyword (string) representing a parameter.

value:

The value associated with the parameter

Example:

self.set_param('exposure', 0.05)

set_register(self, **kwargs)

Updates the named roach registers with the values for the keys specified in the parameter list as keyword value pairs.

This is a low-level function that directly sets FPGA registers. Use set_param() where possible.

Example:

self.set_register(FFT_SHIFT=0xaaaaaaaa, N_CHAN=6)

This sets the FFT_SHIFT and N_CHAN registers.

Note: Only integer values are supported.

set_status(self, **kwargs)

Modifies the local status dictionary

This is a low-level function that will set any arbitrary key to any value in status shared memory. Use set_param() where possible.

Example:

self.set_status(PROJID='JUNK', OBS_MODE='HBW')
# or, equivalent
d = {'PROJID':'JUNK', 'OBS_MODE'='HBW'}
self.set_status(**d)

start(self, starttime = None)

starttime:

a datetime object

–OR–

starttime:

a tuple or list(for ease of JSON serialization) of datetime compatible values: (year, month, day, hour, minute, second, microsecond).

Sets up the system for a measurement and kicks it off at the appropriate time, based on ‘starttime’. If ‘starttime’ is not on a PPS boundary it is bumped up to the next PPS boundary. If ‘starttime’ is not given, the earliest possible start time is used.

start() will require a needed arm delay time, which is specified in every mode section of the configuration file as needed_arm_delay. During this delay it tells the HPC program to start its net, accum and disk threads, and waits for the HPC program to report that it is receiving data. It then calculates the time it needs to sleep until just after the penultimate PPS signal. At that time it wakes up and arms the ROACH. The ROACH should then send the initial packet at that time.

Because the child backend start procedure is time consuming, this start merely records the start time, sets a flag, and returns. This allows the Dealer to issue starts quickly to every Player. The player’s watchdog will then pick up on the start flag, and perform the lengthy start procedure more-or-less in parallel.

start_hpc()

Starts the HPC program running. Stops any previously running instance.

stop_hpc()

Stop the hpc program and make it exit. To stop an observation use ‘stop()’ instead.

write_registers(**kwargs)

Writes the contents of the local roach register dictionary to the roach. These values will have been previously set by ‘set_register()’.

This function should only be called by instantiated class objects, not by classes that act as parent classes. It will only do something if self.roach is not None, and if the object is not in unit-test mode.

write_status(**kwargs)

Writes the contents ‘kwargs’ to status memory.

This function does something only if the status memory object exists, and not in unit-test mode. It should only be called from instantiated classes, never parent classes.

class GuppiBackend

class GuppiBackend.GuppiBackend(theBank, theMode, theRoach, theValon, hpc_macs, unit_test=False)

A class which implements some of the GUPPI specific parameter calculations. This class is specific to the Incoherent BOF designs.

GuppiBackend(theBank, theMode, theRoach, theValon, unit_test)

theBank:

A BankData object, bank data from the configuration file.

theMode:

A ModeData object, mode data from the configuration file

theRoach:

A katcp_wrapper object, the katcp client to the FPGA

theValon:

A ValonKATCP object, the interface to the ROACH’s Valon synthesizer

hpc_macs:

A dict of mac addresses for the HPC computers, keyed by the last octet of the IP address

unit_test:

Unit test flag; set to True if unit testing, False if not. Allows unit testing without involving the hardware.

_acc_len_dep()

Calculates the hardware accumulation length. The register values must be in the range of 0 to 65535, in even powers of two, minus one.

_chan_bw_dep()

Calculates the CHAN_BW status keyword Result is bandwidth of each channel in MHz

_ds_freq_dep()

Calculate the DS_FREQ status keyword. This is used only when an observer wants to reduce the number of channels in software, while using a higher number of hardware channels in SEARCH or COHERENT_SEARCH modes.

_ds_time_dep()

Calculate the down-sampling time status keyword

_fft_params_dep()

Calculate the FFTLEN, and BLOCSIZE status keywords

_hw_nchan_dep()

Can’t find direct evidence for this, but seemed logical ...

_node_bandwidth_dep()

Calculations the bandwidth seen by this HPC node

_npol_dep()

Calculates the number of polarizations to be recorded. Most cases it is all four, except in FAST4K, or when the user has indicated they only want 1 stokes product)

_only_I_dep()

Calculates the ONLY_I status keyword

_packet_format_dep()

Calculates the PKTFMT status keyword

_pfb_overlap_dep()

Randy/Jason indicated that the new guppi designs will have 12 taps in all modes.

_pol_type_dep()

Calculates the POL_TYPE status keyword. Depends upon a synthetic mode name having FAST4K for that mode, otherwise non-4k coherent mode is assumed.

_set_status_keys()

Collect the status keywords

_tbin_dep()

Calculates the TBIN status keyword

earliest_start()

Returns the earliest time this backend can start.

integration_time = None

Parameter ‘integration_time’: Lenght of integration, in seconds.

monitor()

Tells DAQ program to enter monitor mode.

nchan = None

Parameter ‘nchan’: Number of channels

obs_mode = None

Parameter ‘obs_mode’: GUPPI observation mode

prepare()

A place to hang the dependency methods.

scan_status()

Returns the current state of a scan, as a tuple: (scan_running (bool), ‘NETSTAT=’ (string), and ‘DISKSTAT=’ (string))

setFeedPolarization(polar)

Sets the FD_POLN (feed polarization) keyword in status memory and PSR FITS files. Legal values are ‘LIN’ (linear) or ‘CIRC’ (circular)

set_chan_dm(dm)

Sets the dispersion measure for coherent search modes. Other modes should have this set to zero.

set_integration_time(integ_time)

Sets the integration time. The actual value used may be adjusted to make the interval be an even multiple of the hardware accumulation rate. (Actual value in TBIN keyword.)

set_nbin(nbin)

For cal and fold modes, this sets the number of bins in a pulse profile. Ignored in other modes.

set_obs_frequency(f)

Sets the center frequency of the observing band.

set_obs_mode(mode)

Sets the observing mode. Legal values for the currently selected mode are: SEARCH, FOLD, CAL, or RAW

set_only_i(only_i)

Controls whether to ‘record only summed polarizations’ mode. Zero indicates that full stokes data should be recorded. One means to record only summed polarizations. This will be set to zero when using the ‘FAST4K’ observing mode.

set_par_file(file)

Sets the pulsar profile ephemeris file

set_scale(v)

Sets all the saling factors with one parameter.

set_scale_I(v)

Sets the hardware scaling factor for the I stokes parameter. Range is 0.0 through 65535.99998.

set_scale_Q(v)

Sets the hardware scaling factor for the Q stokes parameter. Range is 0.0 through 65535.99998.

set_scale_U(v)

Sets the hardware scaling factor for the U stokes parameter. Range is 0.0 through 65535.99998.

set_scale_V(v)

Sets the hardware scaling factor for the V stokes parameter. Range is 0.0 through 65535.99998.

set_tfold(tf)

Sets the software integration time per profile for all folding and cal modes. This is ignored in other modes.

start(self, starttime = None)

starttime:

a datetime object

–OR–

starttime:

a tuple or list(for ease of JSON serialization) of datetime compatible values: (year, month, day, hour, minute, second, microsecond), UTC.

Sets up the system for a measurement and kicks it off at the appropriate time, based on starttime. If starttime is not on a PPS boundary it is bumped up to the next PPS boundary. If starttime is not given, the earliest possible start time is used.

start() will require a needed arm delay time, which is specified in every mode section of the configuration file as ‘needed_arm_delay’. During this delay it tells the HPC program to start its net, accum and disk threads, and waits for the HPC program to report that it is receiving data. It then calculates the time it needs to sleep until just after the penultimate PPS signal. At that time it wakes up and arms the ROACH. The ROACH should then send the initial packet at that time.

stop()

Stops a scan.

class GuppiCODDBackend

class GuppiCODDBackend.GuppiCODDBackend(theBank, theMode, theRoach, theValon, hpc_macs, unit_test=False)

A class which implements some of the GUPPI specific parameter calculations. This class is specific to the coherent mode BOF designs.

GuppiCODDBackend(theBank, theMode, theRoach, theValon, unit_test)

theBank:

A BankData object, bank data from the configuration file.

theMode:

A ModeData object, mode data from the configuration file

theRoach:

A katcp_wrapper object, the katcp client to the FPGA

theValon:

A ValonKATCP object, the interface to the ROACH’s Valon synthesizer

unit_test:

Unit test flag; set to True if unit testing, False if not. Allows unit testing without involving the hardware.

_acc_len_dep()

In CODD mode, acc_len is always 1

_chan_bw_dep()

Calculates the CHAN_BW status keyword Result is bandwidth of each PFM channel in MHz

_dm_dep()

Read DM from the parfile if COHERENT_FOLD mode, otherwise keep the user-set value.

_ds_freq_dep()

Calculate the DS_FREQ status keyword. This is used only when an observer wants to reduce the number of channels in software, while using a higher number of hardware channels in SEARCH or COHERENT_SEARCH modes.

_ds_time_dep()

Calculate the down-sampling time status keyword

_fft_params_dep()

Calculate the OVERLAP, FFTLEN, and BLOCSIZE status keywords

_node_bandwidth_dep()

Calculates the bandwidth seen by this HPC node

_node_nchan_dep()

Calculates the number of channels received by this node. This is always the total number of channels divided by the number of nodes for coherent modes.

_node_rf_frequency_dep()

The band is divided amoung the various nodes like so:

^       ^^       ^^     ctr freq    ^^
|       ||       ||        ^        ||
+-------++-------++-----------------++--------- ...
   c0       c1            c2             c3

So to mark each node’s ctr freq c0...cn:

where:

rf_frequency

is the center band center at the rx

total_bandwidth

is the number of nodes * node_bandwidth of each node

chan_bw

is the calculated number from the node_bandwidth and number of node channels

_npol_dep()

Calculates the number of polarizations to be recorded. Most cases it is all four, except in FAST4K, or when the user has indicated they only want 1 stokes product)

_only_I_dep()

Calculates the ONLY_I status keyword

_packet_format_dep()

Calculates the PKTFMT status keyword

_pfb_overlap_dep()

Randy/Jason indicated that the new guppi designs will have 12 taps in all modes.

_pol_type_dep()

Calculates the POL_TYPE status keyword. This is always AABBCRCI for coherent modes.

_set_status_keys()

Collect and set the status memory keywords

_tbin_dep()

Calculates the TBIN status keyword

cdd_master()

Returns ‘True’ if this is a CoDD backend and it is master. False otherwise.

dm_from_parfile(parfile)

dm_from_parfile(self,parfile):

Read DM value out of a parfile and return it.

fft_size_params(rf, bw, nchan, dm, max_databuf_mb=128)

fft_size_params(rf,bw,nchan,dm,max_databuf_mb=128):

Returns a tuple of size parameters (fftlen, overlap, blocsize) given the input rf (center of band) in MHz, bw, nchan, DM, and optional max databuf size in MB.

monitor()

Tells DAQ program to enter monitor mode.

net_config(self, data_i = None, data_port = None, dest_ip = None, dest_port = None)

This function overrides the base class Backend net_config for a CoDD backend. If the CoDD backend is master, it will program the roach for output on 8 adapters, as configured in the config file.

prepare()

A place to hang the dependency methods.

scan_status()

Returns the current state of a scan, as a tuple: (scan_running (bool), ‘NETSTAT=’ (string), and ‘DISKSTAT=’ (string))

setFeedPolarization(polar)

Sets the FD_POLN (feed polarization) keyword in status memory and PSR FITS files. Legal values are ‘LIN’ (linear) or ‘CIRC’ (circular)

set_bandwidth(bandwidth)

Sets the bandwidth in MHz. This value should match the valon output frequency. (The sampling rate being twice the valon frequency.)

set_dm(dm)

Sets the dispersion measure for COHERENT_SEARCH mode.

set_integration_time(int_time)

Sets the integration time

set_nbin(nbin)

For cal and fold modes, this sets the number of bins in a pulse profile. Ignored in other modes.

set_nchannels(nchan)

This overrides the config file value nchan – should not be used.

set_obs_frequency(f)

Sets the center frequency of the observing band.

set_obs_mode(mode)

Sets the observing mode. Legal values for the currently selected mode are: COHERENT_SEARCH, COHERENT_FOLD, COHERENT_CAL, and RAW

set_only_i(only_i)

Controls whether to ‘record only summed polarizations’ mode. Zero indicates that full stokes data should be recorded. One means to record only summed polarizations. This will be set to zero when using the ‘FAST4K’ observing mode.

set_par_file(file)

Sets the pulsar profile ephemeris file

set_registers()

Set the coherent design registers

set_scale_P0(p)

Sets the hardware scaling factor for the p0 polarization. Range is 0.0 through 65535.99998.

set_scale_P1(p)

Sets the hardware scaling factor for the p1 polarization. Range is 0.0 through 65535.99998.

set_tfold(tf)

Sets the software integration time per profile for all folding and cal modes. This is ignored in other modes.

start(self, starttime = None)

starttime:

a datetime object

–OR–

starttime:

a tuple or list(for ease of JSON serialization) of datetime compatible values: (year, month, day, hour, minute, second, microsecond), UTC.

Sets up the system for a measurement and kicks it off at the appropriate time, based on ‘starttime’. If ‘starttime’ is not on a PPS boundary it is bumped up to the next PPS boundary. If ‘starttime’ is not given, the earliest possible start time is used.

start() will require a needed arm delay time, which is specified in every mode section of the configuration file as ‘needed_arm_delay’. During this delay it tells the HPC program to start its net, accum and disk threads, and waits for the HPC program to report that it is receiving data. It then calculates the time it needs to sleep until just after the penultimate PPS signal. At that time it wakes up and arms the ROACH. The ROACH should then send the initial packet at that time.

stop()

Stops a scan.

class VegasBackend

class VegasBackend.VegasBackend(theBank, theMode, theRoach, theValon, hpc_macs, unit_test=False)

A class which implements some of the VEGAS specific parameter calculations.

VegasBackend(theBank, theMode, theRoach = None, theValon = None)

Where:

• theBank: Instance of specific bank configuration data BankData.
• theMode: Instance of specific mode configuration data ModeData.
• theRoach: Instance of katcp_wrapper
• theValon: instance of ValonKATCP
• unit_test: Set to true to unit test. Will not attempt to talk to roach, shared memory, etc.

_exposure_dep()

Computes the actual exposure, based on the requested integration time. If the number of switching phases is > 1, then the actual exposure will be an integer multiple of the switching period. If the number of switching phases is == 1, then the exposure will be an integer multiple of hwexposr.

_fpga_clock_dep()

Computes the FPGA clock.

_obs_bw_dep()

Observation bandwidth dependency

_sampler_frequency_dep()

Computes the effective frequency of the A/D sampler based on mode

_setEcal(cals)

External CAL

cals is a list of integers where 1 indicates the external cal is ON 0 indicates the external cal is OFF

_setEsigRef1(sr)

External Sig/Ref 1

sr is a list of integers where 1 indicates REF 0 indicates SIG

_setEsigRef2(sr)

External Sig/Ref 2

sr is a list of integers where 1 indicates REF 0 indicates SIG

_setIcal(cals)

Internal CAL

cals is a list of integers where 1 indicates the external cal is ON 0 indicates the external cal is OFF

_setIsigRef1(sr)

Internal Sig/Ref 1

sr is a list of integers where 1 indicates REF 0 indicates SIG

_setIsigRef2(sr)

Internal Sig/Ref 2

sr is a list of integers where 1 indicates REF 0 indicates SIG

_set_state_table_keywords()

Gather status sets here Not yet sure what to place here...

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. Where:

• duration is the length of this phase in seconds,
• blank is 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 is the state of the sig_ref 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:

be = Backend(None) # no real backend needed for example
be.clear_switching_states()
be.add_switching_state(0.01, blank = True,  cal = True,  sig_ref_1 = True)
be.add_switching_state(0.09, blank = False, cal = True,  sig_ref_1 = True)
be.add_switching_state(0.01, blank = True,  cal = True,  sig_ref_1 = False)
be.add_switching_state(0.09, blank = False, cal = True,  sig_ref_1 = False)
be.add_switching_state(0.01, blank = True,  cal = False, sig_ref_1 = True)
be.add_switching_state(0.09, blank = False, cal = False, sig_ref_1 = True)
be.add_switching_state(0.01, blank = True,  cal = False, sig_ref_1 = False)
be.add_switching_state(0.09, blank = False, cal = False, sig_ref_1 = False)

cleanup()

This explicitly cleans up any child processes. This will be called by the player before deleting the backend object.

clear_switching_states()

resets/deletes the switching_states

computeSpecTick()

Returns the spec_tick value for this backend (the HBW value)

earliest_start()

Reports earliest possible start time, in UTC, for this backend.

fits_writer_cmd(cmd)

Opens the named pipe to the fits_writer_cmd program, sends ‘cmd’, and closes the pipe. Takes care not to block on an unconnected fifo.

monitor()

Tells DAQ program to enter monitor mode.

needs_reset()

For some BOF’s there is a status register which can flag an error state.

prepare()

This command writes calculated values to the hardware and status memory. This command should be run prior to the first scan to properly setup the hardware.

The sequence of commands to set up a measurement is thus typically:

be.set_param(...)
be.set_param(...)
...
be.set_param(...)
be.prepare()

scan_status()

Returns the current state of a scan, as a tuple: (scan_running (bool), ‘NETSTAT=’ (string), and ‘DISKSTAT=’ (string))

setADCsnap(snap)

setHwExposr(hwexposr)

Sets the hwexposr value, usually the value is set from the dibas.conf configuration file. Also sets the acc_len, which falls out of the computation to ensure hwexposure is an even multiple of spec_ticks (that multiple is acc_len).

setIntegrationTime(int_time)

Sets the integration time for each integration.

setNumberChannels(nchan)

Sets the number of channels used by this mode. This is bof specific, and should match the requirements of the bof.

setNumberSpectra(nspectra)

Number of sub-bands.

setPolarization(self, polar)

x is a string ‘CROSS’, ‘SELF1’, ‘SELF2’, or ‘SELF’

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:

b.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))
            )

start(self, starttime = None)

starttime: a datetime object, representing a UTC start time.

–OR–

starttime: a tuple or list(for ease of JSON serialization) of datetime compatible values: (year, month, day, hour, minute, second, microsecond), UTC.

Sets up the system for a measurement and kicks it off at the appropriate time, based on starttime. If starttime is not on a PPS boundary it is bumped up to the next PPS boundary. If starttime is not given, the earliest possible start time is used.

start() will require a needed arm delay time, which is specified in every mode section of the configuration file as needed_arm_delay. During this delay it tells the HPC program to start its net, accum and disk threads, and waits for the HPC program to report that it is receiving data. It then calculates the time it needs to sleep until just after the penultimate PPS signal. At that time it wakes up and arms the ROACH. The ROACH should then send the initial packet at that time.

If this function cannot start the measurement by starttime, an exception is thrown.

start_fits_writer()

Starts the fits writer program running. Stops any previously running instance.

stop()

Stops a scan.

stop_fits_writer()

Stops the fits writer program and make it exit. To stop an observation use ‘stop()’ instead.

class VegasHBWBackend

class VegasHBWBackend.VegasHBWBackend(theBank, theMode, theRoach, theValon, hpc_macs, unit_test=False)

A class which implements the VEGAS HBW mode specific functionality, and which communicates with the roach and with the HPC programs via shared memory.

VegasHBWBackend(theBank, theMode, theRoach = None, theValon = None)

Where:

• theBank: Instance of specific bank configuration data BankData.
• theMode: Instance of specific mode configuration data ModeData.
• theRoach: Instance of katcp_wrapper
• theValon: instance of ValonKATCP
• unit_test: Set to true to unit test. Will not attempt to talk to roach, shared memory, etc.

_sampler_frequency_dep()

Computes the effective frequency of the A/D sampler for HBW mode

_set_state_table_keywords()

Gather status sets here Not yet sure what to place here...

prepare()

This command writes calculated values to the hardware and status memory. This command should be run prior to the first scan to properly setup the hardware.

The sequence of commands to set up a measurement is thus typically:

be.set_param(...)
be.set_param(...)
...
be.set_param(...)
be.prepare()

class VegasLBWBackend

class VegasLBWBackend.VegasLBWBackend(theBank, theMode, theRoach, theValon, hpc_macs, unit_test=False)

A class which implements the VEGAS LBW-specific parameter calculations.

VegasLBWBackend(theBank, theMode, theRoach = None, theValon = None)

Where:

• theBank: Instance of specific bank configuration data BankData.
• theMode: Instance of specific mode configuration data ModeData.
• theRoach: Instance of katcp_wrapper
• theValon: instance of ValonKATCP
• unit_test: Set to true to unit test. Will not attempt to talk to roach, shared memory, etc.

_init_gpu_resources()

When resources change (e.g. number of channels, subbands, etc.) We clear the initialize indicator and tell the HPC to reallocate resources.

_set_state_table_keywords()

Gather status sets here for LBW cases.

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. The LBW modes require computing the length in spec_ticks for blanking phases differntly from other phases. This function takes care of this.

• duration is the length of this phase in seconds,
• blank is 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 is the state of the sig_ref 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:

be = Backend(None) # no real backend needed for example
be.clear_switching_states()
be.add_switching_state(0.01, blank = True,  cal = True,  sig_ref_1 = True)
be.add_switching_state(0.09, blank = False, cal = True,  sig_ref_1 = True)
be.add_switching_state(0.01, blank = True,  cal = True,  sig_ref_1 = False)
be.add_switching_state(0.09, blank = False, cal = True,  sig_ref_1 = False)
be.add_switching_state(0.01, blank = True,  cal = False, sig_ref_1 = True)
be.add_switching_state(0.09, blank = False, cal = False, sig_ref_1 = True)
be.add_switching_state(0.01, blank = True,  cal = False, sig_ref_1 = False)
be.add_switching_state(0.09, blank = False, cal = False, sig_ref_1 = False)

computeSpecTick()

Returns the spec_tick value for this backend (the LBW value)

setLBWGain(gain)

Sets the gain to a new value.

• gain: the new value. May be a scalar, in which case it is

  assumed to be the first element of the ‘gain’ property. This works for all modes, but you should be aware that for modes 20-29 you need 8 gain elements. In that case ‘gain’ should be a list with 8 gain values.

class VegasL1LBWBackend

class VegasL1LBWBackend.VegasL1LBWBackend(theBank, theMode, theRoach, theValon, hpc_macs, unit_test=False)

A class which implements the VEGAS L1LBW1-specific parameter calculations.

VegasL1LBWBackend(theBank, theMode, theRoach = None, theValon = None)

Where:

• theBank: Instance of specific bank configuration data BankData.
• theMode: Instance of specific mode configuration data ModeData.
• theRoach: Instance of katcp_wrapper
• theValon: instance of ValonKATCP
• unit_test: Set to true to unit test. Will not attempt to talk to roach, shared memory, etc.

_sampler_frequency_dep()

Computes the effective frequency of the A/D sampler based on mode

prepare()

This command writes calculated values to the hardware and status memory. This command should be run prior to the first scan to properly setup the hardware.

The sequence of commands to set up a measurement is thus typically:

be.set_param(...)
be.set_param(...)
...
be.set_param(...)
be.prepare()

class VegasL8LBWBackend

class VegasL8LBWBackend.VegasL8LBWBackend(theBank, theMode, theRoach=None, theValon=None, hpc_macs=None, unit_test=False)

A class which implements some of the VEGAS specific parameter calculations for the L8LBW1 and L8LBW8 modes.

VegasL8LBWBackend(theBank, theMode, theRoach = None, theValon = None)

Where:

• theBank: Instance of specific bank configuration data BankData.
• theMode: Instance of specific mode configuration data ModeData.
• theRoach: Instance of katcp_wrapper
• theValon: instance of ValonKATCP
• unit_test: Set to true to unit test. Will not attempt to talk to roach, shared memory, etc.

_gain_dep()

Do the quantization gain calculation and append the result to the register dictionary

_mixer_cnt_dep()

This is a calculated non-user-settable parameter, which specifies the length of the LO bram tables. For now this should be the bram_size - 2 i.e. (1<<10) - 2 In the 8 subwindow mode, all mixer_cnt registers are set, in the 1 subwindow mode, only the first mixer_cnt register is set.

_mode_select_dep()

Sets the mode_sel register based on the number of subbands Zero specifies 8 band mode, 1 specifies 1 band mode

_sampler_frequency_dep()

Computes the effective frequency of the A/D sampler based on mode

_setNumberSubbands(nsubbands)

Selects the Number of subbands. Legal values are 1 or 8. NOTE: This should not be a user parameter, better to have it specified by config file/mode.

_setSubbandFreq(subbandfreq)

A list specifying the frequencies for each subband for a given bank. Should probably check to verify len(subbandfreq) is consistent with current mode.

_set_state_table_keywords()

Update status memory keywords. Calls the base class version first to get a dictionary with the default base class values set, then adds/modifies kvpairs specific to this mode, and finally writes the data to shared memory.

_subfreq_dep()

Compute the baseband frequencies for each sub-band.

prepare()

This command writes calculated values to the hardware and status memory. This command should be run prior to the first scan to properly setup the hardware.

The sequence of commands to set up a measurement is thus typically:

be.set_param(...)
be.set_param(...)
...
be.set_param(...)
be.prepare()

[strategy]

Design Patterns by Erich Gamma et al.