GUPPI User's Guide

NOTE: As of 9/21/2009 the procedures on this page should not be used for standard GBT GUPPI observations. Up-to-date observing instructions can be found at GUPPIAstridGuide

What is GUPPI?

The Green Bank Ultimate Pulsar Processing Instrument is a backend built with off-the-shelf hardware designs, and custom FPGA "Gateware". This gateware is compiled and loaded into the 7 Xilinx FPGA's used for GUPPI's implementation. The current GUPPI's specifications are:
  • 8 bit "real" sampling
  • 2 polarizations
  • 800 MHz bandwidth
  • 2048 spectral channels (a 4K channel mode is being worked on)
  • Roughly 40.96 us minimum integration time (20.48 us sampling is possible when on-line folding) Although see section 'E' below.
  • Full Stokes parameters available
  • Reduced data rate modes:
    • Stokes I only
    • Frequency and time downsampling
    • On-line pulsar folding

User defined parameters

When using GUPPI, there are quite a few parameters that you can change to affect the way that GUPPI takes data. The vast majority of these parameters are passed to GUPPI (or the data acquisition software) by defining or setting FITS-header-like keyword/value pairs in a shared memory on "beef", the data acquisition machine.
  • Integration time
  • FFT shift factor
  • Scale and Offset factors
  • Output processing
    • Stokes I only
    • Frequency Decimation
    • Time decimation
  • Etc.

NOTE: The new instructions for running GUPPI via Astrid are found at GUPPIAstridGuide

GUPPI software user's guide

The GUPPI pulsar backend is still in development, and below are the instructions to get things up and running circa Dec 2008. This documentation is from Jason Ray, Paul Demorest, Glen Langston and Scott Ransom.

To get GUPPI running, you will need several xterms, all connected to beef.

A - Open the putty/xterm/console window to use for the guppi software

1. Open a putty/xterm window and connect to beef. Login as yourself, and source the guppi startup file (which will give you access to the GUPPI commands, the lastest PRESTO, and a very recent PSRCHIVE.

[user@beef ~]$ source /opt/64bit/guppi/guppi_daq/guppi.bash

You should do that in each beef xterm that you will be using. Source guppi.csh or guppi.bash as appropriate for your login shell.

2. Start up the command line interpreter:
    [user@beef ~]$ guppi
    Welcome to the NRAO GUPPI interpreter and command prompt.
    core functions:

If you get errors from this, call Scott, Paul or Patrick.

3. To ensure the correct design files are loaded in the hardware, use the mode() command. The only hardware mode currently supported is 2048 channels:
    guppi> mode('2048')
    Mode '2048':
    Unloading current mode:  ['True', 'True', 'True', 'True']
    Loading '2048' mode:  ['True', 'True', 'True', 'True']

4. If you need to reset GUPPI completely, or change the clock rate that GUPPI is running at, you will need to use the new reset command.
    guppi> reset()
    ... (etc)
    guppi> _

The reset() command has an optional string argument that will set the bandwidth (in MHz). Use "800" for an 800MHz mode, "200" for a 200MHz BW mode (i.e. for clean parts of L-band or for 820MHz PF1) or "100" for a 100MHz BW mode (i.e. for 350MHz PF1). So the call would simply be:
    guppi> reset("200")
    bofs = unload()
    set SYNTH/CFRQ/VALUE to 200 ... True
    ... (etc)
    guppi> _

otherwise, you can simply run the init() command to reset the nominal values:
    guppi> init()
    set BEE2/FPGA1/FFT_SHIFT to 'ffffffff' ... ['True']
    ... (etc)
    guppi> _
NOTE: init() and reset() now initialize the 10 gigabit Ethernet register, it is no long necessary to do so manually. The procedure has been left below for reference only.

Also, if you want to check to see what bandwidth GUPPI is currenty running at, do:
    guppi> get('SYNTH/CFRQ/VALUE')

5. Set the scale factors to a reasonable starting value.
    guppi> increase_scales(5)
    guppi> _
Note that you have tab completion on all these commands in the interpreter.

6. Arm.
    guppi> arm()
    guppi> _
Now the data should be streaming...

7. Go to part B below to start the guppi monitor software

8. To exit out of this, press CTRL+D, then type exit

B - Open the putty window to start the 10gig data monitor

1. Open up a couple more putty/xterm windows on beef.

2. In each of them source the "guppi" environment stuff:
    [user@beef ~]$ source /opt/64bit/guppi/guppi_daq/guppi.bash
Note that that command should be used before you try to do anything with GUPPI.

3. Now we're going to make sure that we can communicate with GUPPI via shared memory. In one of the windows type:

    [user@beef ~]$ guppi_set_params -D

That will put new data in the shared memory that is used by the GUPPI software. You can view that by running the following in another xterm. If you leave the '-D' off it will show you a help screen. The "-D" means use all default values.

    [user@beef ~]$ guppi_status

I recommend leaving that running during your observing session and checking it before you take any real data.

4. Now we are going to stream bogus data through the system so that we can check levels etc.

    [user@beef ~]$ test_net_thread

and in the window running the "guppi" command line interpreter, type:

    guppi> arm()

In the guppi_status window you should see values changing now, indicating that data is flowing.

5. In yet another xterm, run "guppi_monitor". That will open a real-time updating window that shows the bandpass of the data. If the levels are nasty, this will look nasty. For S-band observations that should end up looking like the following Sband guppi bandpass.png
Example guppi_monitor output for GBT S-band. Red = average, Blue = min/max.

And here is an example of the L-band bandpass using 800MHz of bandwidth

L-band bandpass with 800MHz of bandwidth

6. To exit out of this, select the plot window, and hit the q key. Then over in the putty window, type exit.

C - Look at histogram of input levels

1. In the GUPPI command interpreter (see part A), type "arm()" to refresh the data in the BRAMS. ( NOTE: Do not do this if someone is currently recording data to disk!).

2. Type "plot_adc_hist()" to show the histogram (see sample plot below). Close the plot window when done. plot_adc_hist() also reports suggested changes to the input attenuation for proper signal level.

Example Histogram of input sample levels to GUPPI, with the artificial Pulsar attached. Output level is set to 3 dB attenuation.

3. Basically, you need to adjust the input levels to GUPPI so that you get 2 almost identical gaussians as in the plot. The best way to do that is to adjust the Convertor Module attenuators for CM1 and CM5. Note, though that if you are taking Spigot data as well, CM1 is being used by the Spigot, so messing with that level will potentially mes the spigot up.

4. To re-view the levels, you need to re-arm() GUPPI.

D - Adjusting the internal GUPPI levels.

1. In this section, you will adjust the internal GUPPI scalings so that the mean value for most of the bandpass in guppi_monitor is between approx 30-80 in value (remember that the output data type is a signed byte from -127to 128).

2. In the "guppi" command line interpreter you can use the commands "increase_scales()" and "decrease_scales()" to bring those levels up and down by a factor of sqrt(2) by default. Or, if you supply an argument, the factor is the argument. If you make the scales too large, things will get wonky and you will need to run init() again to reset the levels to their initial state. Once you have a good looking A/D histograms and a good bandpass, you are ready to start taking data.

Here is the GUPPIDataTakingGuide.

E - Changing the GUPPI sampling rate.

By default, GUPPI is set to integrate 16 raw samples in the 2048 channel default FPGA code. We'll call that number acc_len (you'll see later). To see how that translates to the sample time (dt) you will get, the formula is (in sec): dt = acc_len x nchan / BW. So for the nominal mode: dt = 16 x 2048 / 800e6 = 4.096e-05, or ~41us.

We can change acc_len by running the command 'set_acc_len' which will set the GUPPI hardware parameter 'BEE2/FPGA2/ACC_LENGTH' to the value you state minus one in hex. So don't be confused by the value returned by the set_acc_len command.

For example, to see what that parameter is set at you can do:
    guppi> get('BEE2/FPGA2/ACC_LENGTH')
In this case, 'f' is hex for 15, so acc_len is 15+1 = 16.

You will almost certainly need to change the accumulation length for the low-BW modes. The current lowest value allowable for 'BEE2/FPGA2/ACC_LENGTH' is 5 (for acc_len = 6) 800MHz-BW mode, and 3 (for acc_len = 4) for the narrow-band (100MHz and 200MHz) modes.

Here is an example of setting the accumulation length to the fastest dumping rate for an 800MHz mode (for acc_len = 6) which gives 15.36 us sampling (note, though, that we can't write data or even fold data at that rate -- folding data rate limits are around 400MB/s and search-mode data rate limits are around 200MB/s).
    guppi> set_acc_len(6)
    set BEE2/FPGA2/ACC_LENGTH to 5 ... True
    guppi> get('BEE2/FPGA2/ACC_LENGTH')

If you use set_acc_len(4) for the 200MHz mode, your sampling rate will be 40.96 us. For the 100MHz mode it will be 81.92 us. Those are currently the fastest sampling rates we can get for those modes (using 2048 channels).

For search observations, it is often useful to get an even number of samples per second so that different scans can be exactly pieced together (scans start on integer seconds). For 800MHz BW mode, acc_len=25 gives 64 us sampling and therefore exactly 15625 samples per second. For the narrow band modes, unfortunately there are no reasonable values of acc_len that give an integer number of samples per second.

Also note that you must tell guppi_set_params (during data taking) that you are using a non-standard accumulation length. Just set the command-line parameter "--acc_len=6" for the above examples (remember that it is the value for 'BEE2/FPGA2/ACC_LENGTH' plus 1).

IMPORTANT NOTE for PF1 Observations: When you take GUPPI data using the small-BW modes with the PF1 receivers, you will be getting lower sideband data. You must tell guppi_set_params about that by specifying your bandwidth as a negative number: "--BW=-200" for a 200MHz mode for example.

The command line to set the shared memory information for a calibration observation using the fastest sampling rate for a 200MHz PF1 observation would be:
    guppi_set_params -c --BW=-200 --acc_len=6
Make sure to check all the values in guppi_status before you start taking data if you are worried!

Here is the GUPPIDataTakingGuide.

F - Other info which most people won't need to worry about...

Moving files from blinkin to the bee2

1. Open a putty window and connect to beef. Login as yourself.

2. type cd /home/gbt1/casper/rlm
ls -ltr

3. scp filename.bof root@bee2:/srv/guppi/bof

4. password = xxxxx

Setting the bee's 10gig E address parameters

NOTE: This is handled by the guppi command line init() script. It is no longer necessary to do this manually.

1. Open a putty window and connect to beef. Login as yourself.

2. ssh root@bee2 password = xxxxx

3. Set the MAC address for the output FPGA
    bee2:~# set_tengbe 2
    bee2:~# _

(or whichever FPGA number the output engine is located on in place of '2')

4. To exit out of this, type exit a few times.

For Developers (and Scripters)

The command line syntax consists of a small number of built-in commands. Each is explained below in detail.


The get command serves two purposes.

Syntax 1: "What can I get?"
guppi> get()
['BEE2/FPGA2/ten_GbE', ..., 'SYNTH/CFRQ/VALUE']

Calling get with no arguments returns a list of all the currently known parameters. In other words, only parameters which can be interacted with are displayed. The command line knows nothing about what registers non-loaded bofs may contain.

Syntax 2:
guppi> get('BEE2/FPGA2/SCALE_I')
['Error', '00400000', '00010000', '30.0', '800MHz']

Callin get with one or more parameters attempts to retrieve each value from the corresponding device. Calling get with a single parameter returns a single value. Calling get with a list of parameters returns a list of values positionally corresponding to the arguments passed in. If a register cannot be read (or doesn't exist), 'Error' is returned rather than a value. All parameters and values are strings.


set only has one syntax. This is because set(), or "What can I set?" is redundant with get().

guppi> set('SYNTH/CFRQ/VALUE', '200MHz')
['True', 'True']

set can take either a single parameter/value pair, or a list of parameters and a list of values.


Like get, load takes either:
  • no arguments ("What can I load?"), which returns a list of all available bofs. This list is filtered such that FPGAs which have a bof running on them do not show up as available.
  • one or more arguments either as a single bof name or a list of bofs.

For sake of clarity the bof names are truncated:
guppi> load()
['BEE2/fpga1_00.bof', 'BEE2/fpga1_01.bof', 'BEE2/fpga2.bof', ..., 'BEE2/fpga3.bof', 'BEE2/fpga4.bof']
guppi> load('BEE2/fpga1_00.bof')
guppi> load()
['BEE2/fpga2.bof', ..., 'BEE2/fpga3.bof', 'BEE2/fpga4.bof']
guppi> load(['BEE2/fpga2.bof', 'BEE2/fpga3.bof', 'BEE2/fpga4.bof'])
['True', 'True', 'True']
guppi> load()


unload is the complement to load, and the syntax is exactly the same.

  • unload() -> "What can I unload?" i.e. what is currently running
  • unload('') or unload([...]) -> unload one or more bofs

The only differences in syntax between these two are that unload works with pattern matching. That is to say, rather than specifying exactly which bofs to unload, one could say instead:

guppi> unload('BEE2/fpga4')

and this would unload whatever was running on FPGA4 (assuming something was running, and that the bofname had 'fpga4' in the name as this is not the case with "floating" bofs). The 'BEE2/' is still necessary because the controller must route unload commands to the proper device. The substring (e.g. 'fpga4') must be uniquely identifiable between the bofs running on the BEE2 or it will return a negative acknowledgment ('Error' or 'False').

float2xstr and xstr2float

In the examples above register values from the BEE2 are returned as 8 character hexadecimal. This alone is easy to decipher, but some registers are actually fixed point formatted, and possibly using two's complement. xstr2float can be used to translate the FPGA fixed point into a floating point number. The function takes up to 3 arguments: the value to be converted, the number of fractional bits, and the position of the sign bit (e.g. "bit number" 16).

# Function signature
def xstr2float(xstr, frac_bits=0, sign_bit=0):
# Usage
guppi> xstr2float('0000000A')
guppi> xstr2float('00010000', 16)
guppi> xstr2float('80010000', 16, 32)
guppi> xstr2float('f0', sign_bit=8) # or xstr2float('f0', 0, 8)

float2xstr is the reverse, for converting normal floating point numbers into a fixed point format. To see the docstrings for either function, type
guppi> help(xstrfloat) # or help(float2xstr)
# docstring text appears here...


profiles is a non-filtered list of all bofs found in the BEE2's repository ( /srv/guppi/bof on the BEE2 filesystem). Each bof name is returned with one of three codes, separated by a comma:
  • a - available. Not currently loaded. However, this does not imply that there isn't already a bof loaded on its target FPGA.
  • r - running. This bof is running and can be found in the BEE2's repository.
  • u - unknown. The BEE2 cannot match this running bof to any found in the repository. This may happen if a bof is started manually from another location on the BEE2.

A specific profile can also be specified to retrieve a single bof status.

guppi> profiles()
['BEE2/fpga1_00.bof, r', 'BEE2/fpga1_01.bof,a', 'BEE2/fpga2.bof,r', 'BEE2/fpga3.bof,r', 'BEE2/fpga4.bof,r']
guppi> profiles('BEE2/fpga1_00.bof')
guppi> profiles(['BEE2/NOT_A_REAL_BOF.bof', 'BEE2/fpga1_01.bof', 'BEE2/fpga2.bof'])
['Error', 'BEE2/fpga1_01.bof,a', 'BEE2/fpga2.bof,r']

-- ScottRansom - 26 Mar 2008
Topic attachments
I Attachment Action Size Date Who Comment
Sband_guppi_bandpass.pngpng Sband_guppi_bandpass.png manage 58 K 2008-12-19 - 15:12 ScottRansom Example output of guppi_monitor for the GBT S-band bandpass. Red = average, Blue = min/max
guppi43m800-1600MHz.gifgif guppi43m800-1600MHz.gif manage 45 K 2008-08-27 - 08:15 GlenLangston Guppi Monitor with 43m attached to Beef input
guppi43m800-1600MHz.pdfpdf guppi43m800-1600MHz.pdf manage 39 K 2008-08-27 - 08:21 GlenLangston pdf of guppi_mon plot
testPulsarHistogram3dB.gifgif testPulsarHistogram3dB.gif manage 70 K 2008-08-27 - 08:31 GlenLangston  
Topic revision: r22 - 2010-08-25, ShilpaBollineni
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback