fsc2: 6.8 Pulser Functions

6.8 Pulser Functions

Currently, the following pulser/spectrometer combinations are implemented:

dg2020_f: d Sony/Tektronix DG2020 with support for phase switching (S-band spectrometer, Frankfurt/Main)
dg2020_b: Sony/Tektronix DG2020 (X-band spectrometer, Berlin)
hfs9000: Tektronix HFS9003 (W-band spectrometer, Berlin)
ep385: Bruker EP385 Pulse Programmer (X-band spectrometer, Berlin)
rs690: Interface Technology RS690 (360 GHz spectrometer, Berlin)
rb_pulser_j: Rulbus Pulser for J-band (275 GHz spectrometer), Leiden
rb_pulser_w: Rulbus Pulser for W-band (95 GHz spectrometer), Leiden
tegam2714a_p: TEGAM 2714A Arbitrary Waveform Generator (as single channel pulser)

To use a module in an experiment put its name into the DEVICES section of the EDL script.

Pulsers are rather special and even the EDL syntax for dealing with the pulsers differs slightly. Thus there is a whole chapter dealing with pulsers and how to define and use pulses, see Using Pulsers. Several of the aspects of the following short descriptions of the pulser functions will probably only become understandable after reading the chapter about pulsers and pulses.

Please note:: Most functions for changing pulses will not lead to an immediate change of the pulse sequence the pulser outputs. E.g. calling the function pulser_shift() (for moving pulses) will not shift the pulses immediately. Instead, all changes to pulses are recorded and but only executed when the function pulser_update() gets called.

The reason for this is twofold: Changes to only parts of the pulses might lead to a pulse sequence, which can't be output, e.g. because pulses would collide. Thus it is necessary to wait until all changes of pulse parameters have been done before trying to create a new pulse sequence. The second reason is that updating the pulser can be quite a time-consuming activity and if it would be done whenever only parts of a more complex change of the pulse sequence is finished might increase the time needed to do an experiment a lot.

The only functions that immediately change the pulse sequence are pulser_update(), pulser_reset(), pulser_next_phase() and pulser_phase_reset(). For all other functions the new state of the pulse sequence has to be committed explicitely by calling pulser_update().

List of pulser functions:

`pulser_name()'
`pulser_state()'
`pulser_channel_state()'
`pulser_lock_keyboard()'
`pulser_update()'
`pulser_shift()'
`pulser_increment()'
`pulser_pulse_reset()'
`pulser_next_phase()'
`pulser_phase_reset()'
`pulser_reset()'
`pulser_stop_on_update()'
`pulser_shape_to_defense_minimum_distance()'
`pulser_defense_to_shape_minimum_distance()'
`pulser_automatic_shape_pulses()'
`pulser_automatic_twt_pulses()'
`pulser_minimum_twt_pulse_distance()'
`pulser_keep_all_pulses()'
`pulser_maximum_pattern_length()'
`pulser_phase_switch_delay()'
`pulser_grace_period()'
`pulser_show_pulses()'
`pulser_dump_pulses()'
`pulser_pulse_minimum_specs()'
`pulser_minimum_defense_distance()'
`pulser_defense_pulse_mode()'

Descriptions of pulser functions:

`pulser_name()'

Returns a string with the name of the digitizer being used.

`pulser_state()'

This function can be either used to determine if the pulser is running when called without an argument, in which case either 1 (i.e. the pulser is running) or 0 (pulser is stopped) is returned. if called with either a numerical argument or a string of "ON" or "OFF" the pulser will be started or stopped (a numerical argument of 0 stops the pulser, a non-zero argument starts it).

This function can also be called during the PREPARATIONS section e.g. to keep the pulser to get started immediately at the start of the experiment.

`pulser_channel_state()'

For the Tektronix HFS9003 this function can be used to determine or set the state of individual channels of the pulser. If called with a single integer argument between 1 and 4 the state of the corresponding channel is returned. If called with an additional numeric argument or a string of "ON" or "OFF" the channel can be switched on or off.

`pulser_lock_keyboard()'

Usually, during an experiment the keyboard of the pulser (if it has one) is locked. But for situations where it would be useful to be able to control the pulser also via its keyboard it can be unlocked (and also re-locked) from within the script. To unlock the keyboard call this function with an argument of 0 or "OFF", to re-lock the keyboard call it again with a non-zero argument, "ON" or no argument at all. This command is only available for the Sony/Tektronix DG2020 (dg2020_b and dg2020_f).

`pulser_update()'

This function has to be called after changes have been applied to pulses either via any of the following pulser functions or by changing a pulse property directly. Before this function is called, all changes are only done to the internal representation of the pulser, but not yet send to the pulser. Only by calling the function these changes are committed and the real pulses will change.

`pulser_shift()'

This function can be called with either no argument or with a list of (comma separated) pulse identifiers (pulse numbers will also do). If no argument is given the positions of all pulses which have a DELTA_START defined and are currently active (i.e. don't have a length of 0) are shifted by their respective DELTA_START. If there is only one argument or a list of pulses only the start position of the listed pulses are changed.

`pulser_increment()'

This function can be called with either no argument or with a list of (comma separated) pulse identifiers (pulse numbers will also do). If no argument is given the lengths of all pulses which have a DELTA_LENGTH defined and are currently active (i.e. don't have a length of 0) are incremented by their respective DELTA_LENGTH. If there is only one argument or a list of pulses only the lengths of the listed pulses are changed.

`pulser_pulse_reset()'

This function can be called with either no argument or with a list of (comma separated) pulse identifiers (pulse numbers will also do). If no argument is given all pulses are reset to their initial states, i.e. the states of the pulses set in the PREPARATIONS section. The function also does a reset of all pulse phases, as done by pulser_phase_reset(). It does not update the pulser, if you want to reset all pulses and and also update the pulser use the function pulser_reset() instead.

If called with one argument or a list of pulses only the pulses from the list are set back to their initial states.

`pulser_next_phase()'

When the experiment starts the phases of all pulses are set to the first phase of the phase sequence (defined in the PHASE section) associated with the pulses. By calling this function the phases of the pulses are switched to the next phase. By repeatedly calling the function one can run through the complete list of phases for the pulses.

This function also immediately updates the pulse sequence, as it is done by calling pulser_update().

This function is only available for pulser modules that allow phase cycling, i.e. dg2020_f, dg2020_b, ep385, rs690 and rb_pulser_w.

`pulser_phase_reset()'

This function can be called with either no argument or with a list of PULSE_SETUPs numbers. A PHASE_SETUP (see also Phase channel setup) defines on which output connectors of the pulser the pulses of a function with a certain phase will appear. I.e. if the pulses of the MICROWAVE function are to be phase-cycled one has to specify which of the connectors is to be used to output microwave pulses with an x-phase, which one is to be used for microwave pulses pulses with an y-phase etc. Pulses of not more than two functions can be phase-cycled, so there's a maximum of two PULSE_SETUPs, PULSE_SETUP_1 and PULSE_SETUP_2. By specifying the number 1 or 2 on can restrict resetting the phases of the pulses of the function associated with either PULSE_SETUP_1 or PULSE_SETUP_2.

This function also immediately updates the pulse sequence, as it is done by calling pulser_update().

This function is only available for pulser modules that allow phase cycling, i.e. dg2020_f, dg2020_b, ep385, rs690 and rb_pulser_w.

`pulser_reset()'

This function does not take any arguments at all. It switches the pulser back to the initial state it was in at the start of the experiment. It includes the complete functionality of pulser_pulse_reset() but also immediately updates the pulser as it is done by calling pulser_update().

`pulser_stop_on_update()'

This function exists for the Tektronix HFS9003 only. While doing updates of the pulser to set new pulse positions and length etc. it usually gets switched off. By calling this function with an argument of 0 you can tell to pulser to continue even while doing updates. If called with an argument of 1 you may switch back to the default behavior.

`pulser_shape_to_defense_minimum_distance()'

This function exists for the pulser modules dg2020_b, ep385 and rs690 only, i.e. pulser modules that automatically can create shape pulses. It sets the minimum allowed distance between the end of a pulse shaper pulse and the start of a defense pulse to avoid destroying the detector by excessive microwave power. The default minimum value for this distance is intentionally set to an unreasonably long value and this function allows to reduce (but also enlarge) the value. As another security measure the function requires the user to explicitely confirm the new value before an experiment is started. When running in batch mode this security feature is deactivated, fsc2 will accept any value you set without requesting a confirmation, so be careful.

This function can only be called during the PREPARATIONS section of an EDL script.

`pulser_defense_to_shape_minimum_distance()'

This function exists for the pulser modules dg2020_b, ep385 and rs690 only. It sets the minimum allowed distance between the end of a defense pulse and the start of a pulse shaper pulse to avoid destroying the detector by excessive microwave power. The function also makes sure that the time between the last defense pulse in a sequence and the first shape pulse of the next pulse sequence does not get too short when a very high repetition rate is used.

The default minimum value for this distance is intentionally set to an unreasonably long value and this function allows to reduce (but also enlarge) the value. As another security measure the function requires the user to explicitely confirm the new value before an experiment is started. When running in batch mode this security feature is deactivated, fsc2 will accept any value you set without requesting a confirmation, so be careful.

This function can only be called during the PREPARATIONS section of an EDL script.

`pulser_automatic_shape_pulses()'

This function exists for the pulser modules dg2020_b, ep385 and rs690 only. It tells fsc2 to automatically create shape pulses in the PULSE_SHAPE function. Obviously, this requires that a pod or channel has been assigned to the PULSE_SHAPE function. The first (and required) argument is the function for which shape pulses are to be created, typically this will be MICROWAVE in which case shape pulses are created for all microwave pulses.

The shape pulses have exactly the same length as the pulses they are created for. The pulses the shape pulses are created for in turn are automatically lengthened a bit to make them start before their shape pulses and also to last a bit longer.

The amount of time the pulse a pulse with an automatically generated shape pulse will start earlier than specified in the EDL script ("left padding") can be set by the second function argument, if it is missing a default value (set in the configuration file for the pulser) is used. In the same way the third argument specifies how much longer the pulse lasts ("right padding") than the shape pulse. (It is not a problem if the pulses should become that long that they overlap due to padding, if necessary they are shortened.)

To make this more clear an example. Let's assume that MICROWAVE pulse has been set in the EDL script:

P1:   FUNCTION = MICROWAVE,
      START    = 400 ns,
      LENGTH   = 600 ns;

If now the pulser_automatic_shape_pulses() function is called as

pulser_automatic_shape_pulses( MICROWAVE, 24 ns, 16 ns );

the automatically created shape pulse will start at 400 ns and last for 600 ns but the microwave pulse P1 will now start 24 ns earlier, i.e. at 376 ns, and will have a length of 640 ns.

The function pulser_automatic_shape_pulses() can be called for more than one function (e.g. for both the MICROWAVE and the OTHER_2 function) and also additional shape pulses can be created manually. The only requirement is that the shape pulses (both automatically and manually created ones) for a certain channel don't overlap during the experiment.

This function can only be called during the PREPARATIONS section of an EDL script.

`pulser_automatic_twt_pulses()'

This function exists for the pulser modules dg2020_b, ep385 and rs690 only. It tells fsc2 to automatically create the pulses of the TWT function at the appropriate moments, i.e. to coincide with the microwave pulses. Obviously, this requires that a pod or channel has been assigned to the TWT function. The first (and required) argument is the function for which TWT pulses are to be created, typically this will be MICROWAVE in which case shape pulses are created for all microwave pulses.

Usually, the TWT pulses will have to start before the pulse for which they were created. The amount of time the TWT pulse starts before its associated pulse can be specified as the second argument. If there is no second argument a default value is used as defined in the configuration file for the pulser. The third argument is the time the automatically created TWT pulses last longer than the associated pulse. Again, if not specified a default value is used.

The function pulser_automatic_twt_pulses() can be called for more than one function (e.g. for both the MICROWAVE and the OTHER_2 function) and also additional TWT pulses can be created manually. It isn't a problem if the TWT pulses would overlap, if necessary they are shortenend.

Since TWTs often require a minimum distance between pulses the automatically created pulses will automatically lengthened to cover too short a distance between them. If not set via the function pulser_minimum_twt_pulse_distance() a compile time constant (that can be adjusted in the configuration file for the module) is used as the minimum TWT pulse distance.

This function can only be called during the PREPARATIONS section of an EDL script.

`pulser_minimum_twt_pulse_distance'

This function exists for the pulser modules dg2020_b, ep385 and rs690 only, i.e. pulser modules than can create automatic TWT pulses. It can be used to set or query the minimum time the module allows between automatically generated TWT pulses (if the distance between TWT pulses gets shorter than this minimum time they are automatically lengthened to cover the whole intermediate time interval). If you try to set a time that is shorter than the default minimum time distance (as set in the configuration file for the module) a warning is printed.

This function can be used in all sections of the script and even allows to change the minimum time during an already running experiment repeatedly. Please note that setting a new minimum TWT pulse distance does not automatically change the current state of the pulses, they only get changed to reflect the new setting when either pulser_update() is called or another function that automatically updates the pulser, i.e. either pulser_reset(), pulser_next_phase() or pulser_phase_reset()

`pulser_keep_all_pulses()'

In some modules pulses that in the test run were found to be unused (i.e. always had a length of 0) are deleted and a warning message is printed indicating this. Any further references to or use of these deleted pulses leads to the immediate termination of the experiment. But there are a few situations where it can't be detected reliable in the test run that a pulse is actually needed (e.g. if it is only used in an untestable IF construct) and thus the pulse gets deleted even though it is needed. In this case you have to force the program to keep all pulses even if it assumes them to be useless by calling this function (without any arguments).

`pulser_maximum_pattern_length()'

This function only exists for the pulser modules dg2020_b, dg2020_b, hfs9000 and tegam2714a_p modules.

For the Bruker EP385 a maximum pattern length can't be specified, it is fixed to 32768 times the clocks oscillation period (i.e. 262.144 us when using the internal clock). The Interface Technology RS690 uses a rather different concept and there is no maximum pattern length. Calling the function for either of these pulsers does nothing.

For the Sony/Tektronix DG2020 (dg2020_b and dg2020_f) modules as well as for the TEGAM 2714A module the program will in most cases be able to figure out automatically how long the length of the longest pulse pattern in the experiment is going to be when doing the test run. Unfortunately, there are certain syntax constructs that make it difficult or even impossible to find out this maximum pattern length. These constructs are FOREVER loops and sometimes cases, where changes of pulse positions or lengths are done within IF-ELSE or UNLESS-ELSE constructs (please also see the discussion of the problems introduced by FOREVER loops and IF and ELSE constructs, see Control structures).

Whenever there is a reason to suspect that these problems may occur one can set the maximum pulse pattern length manually (i.e. the end point of the last pulse when it has been set to its latest position during the experiment) by calling pulser_maximum_pattern_length() with the the maximum pulse pattern length as the only argument.

Unless in the test run an even longer pattern length is found, this value is used. It is not a problem to specify too long a maximum pattern length (as long as one isn't using external trigering and the pattern length is longer than the repetition time), so a conservative guess will do. The only penalty incurred could be a longer time needed to set up the pulser at the start of the experiment. On the other hand, too short a pattern length will lead to the experiment being stopped with an error message when the actual pattern length becomes larger than specified.

In contrast with the Tektronix HFS9003 pulser the pattern length is per default set to the maximum possible length of 65536 times the time constant. If your pulse pattern is shorter than this length and using the default length isn't desirable (e.g. because you need a higher repetition rate) you can shorten the length of the pulse sequence by using this function.

This function can only be used in the PREPARATIONS section of an EDL script.

`pulser_phase_switch_delay()'

This function is only implemented for the Frankfurt version of the Sony/Tektronix DG2020 and the W-band Rulbus pulser. It lets you specify the time a phase pulse has to start before the beginning of a microwave pulse (or other phase cycled pulses), the phase switch needing some small amount of time to settle.

For the Frankfurt version of the Sony/Tektronix DG2020 the function takes two arguments, the first one being the phase function the phase switch delay is to be applied to (i.e. either PHASE_1 (or PHASE for short) or PHASE_2). The second argument is the amount of time.

For the W-band Rulbus pulser only the amount of time is to be specified, no further arguments are allowed (only microwave pulses can be phase-cycled, so only a single phase function is used).

When this function isn't called a default value as specified in the configuration file for the device is used.

When the program does its tests it will always check if the distances between the pulses are large enough to allow setting the phase pulses. If the pulse distances get too short to set the phase switch delays the program will abort with an error message.

The function can only be called during the PREPARATIONS section of an EDL script.

`pulser_grace_period()'

This function is only implemented for the Frankfurt version of the Sony/Tektronix DG2020 pulser and the W-band Rulbus pulser. While the time a phase pulse must start before the pulse it was set for can is supposed to start via the pulser_phase_switch_delay() function, you also may set how much longer a phase (pulse) has to be kept set after the original pulse ended.

The function takes only one argument, the time the phase pulses will last after the end of the pulse. For the dg2020_f module it applies automatically to both phase functions while for the rb_pulser_w only the MICROWAVE function allows phase switching.

If this function isn't called a default grace period as defined in the configuration file for the device will be used.

Here's a diagram that shows the phase switch delay and the grace period for the dg2020_f module (assuming that the microwave pulses are to be phase-cycled):

                   ____________________________
                  |                            |
Phase pulse       |                            |
             _____|                            |_________
                           _________________
                          |                 |
Microwave pulse           |                 |
             _____________|                 |____________
         
                ->|       |<-             ->|  |<-
               phase switch delay        grace period

When the program does its tests it will always check if the distances between the pulses are large enough to allow setting the phase pulses. If the pulse distances get very small it may drop the grace period.

The function can only be called during the PREPARATIONS section of an EDL script.

`pulser_show_pulses()'

This function allows to view the pulses as they become set during the test run. If this function is called an additional window pops up after the end of the test run which shows the position of all pulses at the start of the experiment. By using the (fast) forward and backward) buttons, the <PAGE UP> and <PAGE DOWN> as well as the <HOME> and <END> keys) you may view all pulse settings during the experiment (as far as they can be determined during the test run). Alternatively, the step number can be edited directly.

By using the Show delays button you can switch between a display where the pulses are shown at their "logical" positions (as they would be set if there would be no delays) and the positions at which they, due to delays really will be set.

In an additional window the paramters of the pulse the mouse is currenty positioned on are displayed. These include the pulse number (when the pulse number is enclosed in parentheses it's an automatically created pulse, the number itself is identical to the pulse number of the pulse it was created for), the positions with and without delays (depending on the current setting of the Show delays button, in parentheses the value for the other button state is shown), the pulse length, its function and the number of the pod or channel to which the pulse will be routed.

Further informations are the edge-to-edge distance to the previous and the next pulse (in parentheses the center-to center distance) is shown.

Finally, for automatically created pulses informations about the parent pulse, i.e. the pulse for which this pulse was created for, are displayed.

The function uses the fsc2_pulses program to display the pulse settings. fsc2_pulses only works if both Perl and Perl/Tk (in not too ancient a version) is installed on the system.

When running in batch mode this function does nothing.

This function can only be called during the PREPARATIONS section of an EDL script.

`pulser_dump_pulses()'

This function requests the user to select a file name and then writes all pulse settings during the test run into the file in a format suitable to be used as input for the fsc2_pulses utility.

When running in batch mode this function does nothing.

This function can only be called during the PREPARATIONS section of an EDL script.

`pulser_pulse_minimum_specs()'

This function is available only for the Rulbus pulser (rb_pulser_w and rb_pulser_j) modules. It expects a single argument, a pulse, e.g. P1. If it is the first pulse of a function (i.e. MICROWAVE, RF or DETECTION), the function returns the earliest possible absolute position of the pulse. For all later pulses, the minimum distance to the end of the previous pulse is returned. Please note that the minimum positions of both the RF pulse and the detection pulse depend on the position of the first MW pulse, so after changes of the position of this pulse minimum start positions for the RF and detection pulses have to be recalculated.

This function can only be called during the EXPERIMENT section of an EDL script.

`pulser_minimum_defense_distance()'

This function exists only for the W-band Rulbus pulser. Unless explicitely forbidden by a call of pulser_defense_pulse_mode() with the appropriate argument, for this module a defense pulse is created automatically, lasting from the start of the pulse pattern to some time after the end of the last microwave pulse, in order to protect amplifiers and receivers from excessive levels of microwave power. Using this function the minimum distance between the end of the last microwave pulse and the end of the defense pulse can be set (or queried), please note that this time can end up being be slightly longer, up to the length of the timebase of the pulser.

If this function isn't called a default minimum time as defined in the configuration file for the device will be used.

This function can be called to set the minimum defense delay only during the PEPARATIONS section of an EDL script. Unless compiled into the module by changing a configuration variable the program will explictely ask the user at the start of the experiment if she really intended to change the minimum defense delay.

`pulser_defense_pulse_mode()'

This function exists only for the W-band Rulbus pulser. For this module a defense pulse, starting at the very start of the pulse pattern and lasting to some time after the end of the last microwave pulse, is created in order to protect amplifiers and receivers from excessive levels of microwave power. But in some situations such an automatic creation of a defense pulse is not desirable, in which case this function can be called during the PREPARATIONS section of the EDL script before a defense pulse is defined. It can be called with a string argument of either "ON" or "OFF" (or an integer argument of 1 or 0). Calling it with the argument "ON" isn't really useful since this is the default (and switching back to automatic creation isn't possible once the function has been called with the "OFF" argument). To be able to create the defense pulse yourself and later control its length you need to call the function with an argument of "OFF". Calling the function with this argument and not defining a defense pulse at all allows to avoid the creation of a defense pulse.

Once in manual mode the module does not evaluate the value set by a call of pulser_minimum_defense_distance() anymore - the user is now completely responsible for creating a defense pulse and setting its correct length..

If the function has been called with the argument "OFF" the user will always explicitely asked if that's what he really wants because of the potential dangers involved.

This document was generated by Jens Thoms Toerring on September 6, 2017 using texi2html 1.82.