Bathtub and eye scans

The sections below outline the empbutler commands for running and plotting bathtub and eye scans. The first steps are in common with the Configuring the link firmware section.

Note

In these commands, you will need to replace the following arguments with appropriate values:

• CONNECTIONS_FILE.xml : Relative/absolute path to your connections file

• LINKS_YAML.yaml : Relative/absolute path to your links yaml file (described in detail below)

• DEVICE_ID : ID string for your FPGA in that connections file

• CHANNEL_LIST: Comma-separated list of input/output channels (e.g. 4-7,12 for links 4, 5, 6, 7 and 12)

Python dependencies

Although not necessary to run the eye scans, the optional plotting part has the following additional dependencies:

sudo pip install --upgrade pip
sudo pip install matplotlib scipy "iminuit<2.0.0" probfit

The latter three packages are required only for the bathtub fitting. For python 2, "iminuit<1.4" is instead required.

Links yaml file

In order to correctly identify the physical links with the EMP channels, the connections and their properties must be specified in a links yaml file.

There are examples for possible single-board and inter-board connections at /opt/cactus/etc/emp/links/singleBoardConnections.yml and /opt/cactus/etc/emp/links/interBoardConnections.yml, but typically users will need to provide their own links yaml file LINKS_YAML.yaml to match their setup.

The links yaml files have two top-level keys, and we’ll look at /opt/cactus/etc/emp/links/singleBoardConnections.yml as an example. The first top-level key is fpgas, which holds details of the connected FPGAs:

fpgas:
  x0:
    uid: FT-9999A-999
    board:
      - serenity_dc_ku15p_so1_v1
      - serenity_v1.1

  x1:
    uid: FT-8888A-888
    board:
      - serenity_dc_ku15p_so1_v1
      - serenity_v1.1

In fpgas there is a key for each connected site, named by the DEVICE_ID (in this case x0 and x1). Each holds the following information:

• uid: serial number of the FPGA

• board: list of two strings identifying the daughter card type (in this case serenity_dc_ku15p_so1_v1) and carrier card type (in this case serenity_v1.1). These strings must exactly match the name of a corresponding yaml file in /opt/cactus/etc/emp/links/ (with the .yaml part omitted). These additional yaml files provide the hardware-specific mapping between the EMP channels and the carrier card sockets, and should not need to be edited by the user.

The second top-level key is connections, which contains a list of dictionaries describing the Tx -> Rx connections. Each dictionary in connections represents a group of similar connections and has the following keys:

• from: the DEVICE_ID of the FPGA the connections are from

• to: the DEVICE_ID of the FPGA the connections are to

• type: the type of the connections (can be direct or reverse). This determines the mapping between the 12 channels within each tx and rx socket. For direct, rx channel i maps to tx channel i. For reverse, rx socket channel i maps to tx channel (11-i).

• links: map specifying the carrier card sockets the connections are from:to.

The example from /opt/cactus/etc/emp/links/singleBoardConnections.yml is as follows:

connections:
  - from: x0
    to: x1
    type: reverse
    links:
      Tx0: Rx0
      Tx1: Rx1
      Tx2: Rx2
      Tx3: Rx3
      Tx4: Rx4
      Tx5: Rx5

  - from: x0
    to: x1
    type: direct
    links:
      intraTx: intraRx

In this example, there are two dictionaries in the connections list. The first dictionary in the list indicates that there are cables connecting the tx carrier card sockets Tx0-5 at site x0 to the rx carrier card sockets Rx0-5 at site x1. These connections are all of type: reverse (in this case, Cu12 cable with X polarity).

The second dictionary in the list describes the direct inter-interposer link from intraTx (site x0) to intraRx (site x1).

Note

When running in internal loopback mode (e.g. mgts configure tx --loopback nearPMA), it is known that the tx is connected internally to the rx for each EMP channel, so only the fpgas section is required in LINKS_YAML.yaml.

Scanning the links

1. Follow the instructions to configure the link firmware, up to the mgts align command.

2. Scan the links:

   empbutler -c CONNECTIONS_FILE.xml do DEVICE_ID mgts scan -c CHANNEL_LIST --ber=1e-8 -l LINKS_YAML.yaml --scantype bathtub
   

   • The links yaml file (described in the section above) is specified by -l or --linkmap LINKS_YAML.yaml.

   • The scan type (bathtub or eye) is specified by -s or --scantype [bathtub|eye].

   • The target BER sensitivity of the scan is set using -b or --ber FLOAT. This specifies the smallest BER that the scan will be able to detect, at a given confidence level (CL). The chosen target BER will be rounded down to the nearest discrete step (corresponding to an integer prescale value).

   • The target BER CL is 90% by default, which means there’s a 90% chance an error will be seen if the true BER equals the target BER. A custom CL can be set in % via e.g. --bercl 99 (this is not recommended for standard workflows).

   • Use option -p, --plot to plot the scan results. The plots can also be produced by the Standalone plotting script, with options for customisation.

   • The default range and granularity of the time (x) and voltage (y) offsets can be overridden using the --xmax, --xstep, --ymax, and --ystep options. If these are set, it is not necessary to specify the --scantype.

   • To scan channels with good Rx status only, use option -g, --goodrxonly (this is not recommended for standard workflows).

   Further details of the options are described in the help: ... mgts scan -h.

   The scan command will create a folder for the results of the scan, named scans_YYYYMMDD_HHMMSS using the current date and time. The contents are as follows:

   • data/: a folder containing the scan data and metadata, saved in one text file per EMP channel. The scan data (measured sample and error counts, i.e. the denominator and numerator for the BER) is stored in csv format. The sample count is stored as log2(sample_count + 1), because this is always an integer power of 2 in the interesting part of the scan (where the error count is not saturated). The metadata is stored in yaml format at the top of the file, but commented out (each line preceded by a #) so it can be easily ignored when reading the csv part.

   • If running with option -l, --linkmap (recommended):

     • links.yml, a copy of the links yaml file

     • processed_data/: an updated copy of data/, with the links metadata added and the text file names modified to include the link numbers.

   • If running with option -p, --plot, the plots will be saved here in pdf format.

Note

When running sequences of commands like this it can be useful to use the Butler scripting interface, e.g.:

empbutler -c CONNECTIONS_FILE.xml script bathtubScanLoopbackTest.script

The above example script can be found at /opt/cactus/etc/emp/examples/bathtubScanLoopbackTest.script

Standalone plotting

The plotting part can be (re)run independently of empbutler using the following script (which is included in the RPM):

plot_emp_scans plot -i indir -o outdir

Here, indir is the output folder from the mgts scan command (scans_YYYYMMDD_HHMMSS), and outdir is the desired location for the output plots (it defaults to indir if unspecified).

The resulting plots are identical to those automatically produced when running mgts scan with option --plot as described above.

The behaviour of the fit can be customised as follows:

• The upper threshold for the BER data to be included in bathtub fit is set using -t, --threshold FLOAT

• The rho density parameter used in the fit is set using -r, --rho FLOAT

• The minimum required opening fraction for a bathtub to be considered ‘good’ is set using -a, --acceptance FLOAT

If desired, the links metadata can be (re)processed by specifying option -m, --processmetadata or, to set or override the saved links yaml file, -l or --linkmap LINKS_YAML.yaml.

Comparison plots for two scans_YYYYMMDD_HHMMSS directories can be generated as follows:

plot_emp_scans compare -i indir -c compdir -o outdir

Further options are described in the help: plot_emp_scans plot -h and plot_emp_scans compare -h.