Overview

The two faces of experiment.cfg

The two important copies of experiment.cfg are:

$MAS_CONFIG/experiment.cfg - the main, archived copy where static parameter updates and commentary should be entered.
- Note that this main copy used to live in $MAS_TEMPLATE; systems in transition can just set $MAS_CONFIG to be equal to MAS_TEMPLATE.
$MAS_DATA/experiment.cfg - the temporary copy of the config file that is updated by auto-tuning and used to configure the MCE.

The main copy has comments and stuff. The temporary copy gets stripped and reformatted by the tuning scripts.

Support for multiple configurations

To support multiple configuration files (for different MCEs, arrays, fridges, whatever), the following system is used:

each configuration is given a label, e.g. "AR1" or "AR2"
there are separate template configuration files, called $MAS_TEMPLATE/experiment_<label>.cfg
the file /data/cryo/array_id contains the name of the active label.
when experiment_<label>.cfg is copied to $MAS_DATA, the <label> is removed -- so the file in $MAS_DATA will always be called experiment.cfg
the label "default" is special; in that case the template configuration file is simply $MAS_TEMPLATE/experiment.cfg, not experiment_default.cfg
the file $MAS_TEMPLATE/array_list should contain a list of all array labels being used, along with a unique integer to be associated with each array label. This integer will be written to the MCE during configuration and all frame data will include it in a special place in the frame header.

The various scripts that need to use experiment.cfg will check /data/cryo/array_id for the array label, and then process the corresponding template file in $MAS_TEMPLATE.

Basic configuration

When setting up an array, some basic settings that you will want to configure are:

Array label: #array_id
Readout card configuration: #hardware_rc , #hardware_rc_data , #config_rc
Firmware version: #hardware_rect

Once those are set up properly, you may be able to run the configuration script; e.g.

  set_directory
  mce_reconfig

Parameter types

System parameters

array_id

A string identifying the array. Unless you have multiple array setups that require different configuration files, use "default".

Array description parameters

hardware_rc

A list of 4 integers (boolean), identifying the presence (in the MCE) of each readout card. e.g. for RC1 and RC2 use:

hardware_rc = [1,1,0,0];

hardware_sync

An integer (boolean) identifying the presence of a sync box. This doesn't actually do anything -- use #config_sync to enable or disable the MCE's use of a connected syncbox.

hardware_rect

An integer (boolean) identifying the use of "rectangle mode" firmware on the MCE. Firmware revisions from v5.0.0 are "rectangle mode". The RC and CC configuration steps change substantially between non-rectangle and rectangle mode firmware so it is critical to set this flag correctly.

hardware_fast_sq2

An integer describing the capabilities of the card in the BC2 slot.

Values: 0 - old-school bias card, no fast-switching capabilities; 1 - biasing address card, fast-switching only.; 2 - new-school bias card support both behaviours.

hardware_rc_data

A list of 4 integers (boolean), identifying which RCs should be included when reading "RCS" data from the MCE. The flags are processed and written to "cc rcs_to_report_data" by the config script. This will usually match hardware_rc.

config_rc

A list of 4 integers (boolean) identifying what readout cards should be configured by the config script. It should probably match #hardware_rc.

config_sync

An integer (boolean). When set to 1, the MCE will be configured to take its timing parameters from the sync box. The sync box must be connected and properly configured for this to work. When set to 0, the MCE will be configured to ignore the sync_box.

config_filter

An integer (boolean) indicating that the low-pass filter parameters specified in #filter_params need to be written to the MCE. Starting with RC 5.1.0, alternative parameters can be written to the MCE.

filter_params

Filter parameters for RC. See description in template, or here: Digital 4-pole Butterworth Low-pass filter.

default_num_rows, num_rows

Integer specifying the number of rows to tune. Currently these both need to be set to same value.

default_sample_num, sample_num

Integer specifying the number of ADC samples the MCE should co-add when measuring the error signal. Currently these both need to be set to same value.

default_data_mode

Integer indicating the data_mode the MCE should be placed into at the end of the auto-setup.

default_flux_jumping

Integer (boolean) indicating whether to enable flux_jumping following auto-setup.

default_servo_p, default_servo_i, default_servo_d

Each of these parameters is a list of integers containing the default servo gain parameters. There is one value per column. Note that the values actually written to the mce are determined by servo_p, servo_i, servo_d. These are loaded from default_* at the end of auto-setup.

default_sa_bias, default_sq2_bias, default_sq1_bias, default_sq1_bias_off

Each is a list of integers, giving the default DAC values for the SA bias, SQ2 bias, SQ1 "on" bias and SQ1 "off" bias. The SA and SQ2 biases are lists of integers, one value per MCE column. The SQ1 values are one per row.

columns_off

A list of integers (boolean) indicating columns that should be disabled following auto-tuning. Disabled columns have their SA and SQ2 biases turned off. (It should also kill the servo gains, but it doesn't as of r809.)

Tuning control parameters

stop_after_sq1_servo

sa_offset_bias_ratio

As the SA bias is increased, a DC voltage drop builds up across it. An "SA offset" DAC compensates for this at the ADC input. When auto_setup ramps or sets the SA bias, it will also set SA offset to

sa_offset = sa_bias * sa_offset_bias_ratio

The general rule for tweaking sa_offset_bias_ratio is: if your SA Ramp curves are railing at the top of the ADC range, then increase sa_offset_bias_ratio. If they're railing at the bottom, decrease the ratio.

There is a script to estimate a suitable sa_offset_bias_ratio. Run:

 python $MAS_PYTHON/special_ops.py measure_sa_offset_ratio

sa_ramp_bias

sa_ramp_flux_start, sa_ramp_flux_count, sa_ramp_flux_step

sa_ramp_bias_start, sa_ramp_bias_count, sa_ramp_bias_step

sq2_rows

List of integers indicating which row in each column should be used in the SQ1 servo step. Only relevant when config_fast_sq2 = 0.

sq2_servo_gain, sq1_servo_gain

Lists of floats, one per column, indicating the gain to use during the SQ2 servo and SQ1 servo steps of auto-tuning. The locking slopes on the SA and SQ2 are determined by the signs of these gains. See Locking slopes.

For the servo gains, it is a good idea to pick values that are near to the critical gain (this is unlike the internal MCE servo, where you definitely do not want to risk exceeding the critical gain). The critical gains may be estimated using the "servo_gains.py" script. First acquire a partial tuning:

auto_setup --last-stage sq2_servo

Then run

python $MAS_PYTHON/servo_gains.py <tuning_folder>

where <tuning_folder> is the location of the tuning data you just acquired.

The script suggests values for sq2_servo_gain based on the SA ramp curve, and values for sq1_servo_gain based on the SQ2 servo. If the initial values for sq2_servo_gain were not good ones, the sq1_servo_gain values will wrong. So this process should be iterated to first set up sq2_servo_gain, then sq1_servo_gain.

tuning_do_plots, tuning_plot_format

Set tuning_do_plots=0 to suppress the generation of plots during tuning.

The tuning_plot_format may be set to "png", "svg", or "pdf". PDF generation is slow, but produces nice booklets of vector plots.

To install the packages required for PDF plotting, run:

sudo apt-get install python-setuptools
sudo easy_install pypdf svglib reportlab

(Those packages should eliminate the warning message "Failed to load PDF collation libraries.")

tuning_check_bias, tuning_therm_time

Set the default behaviour for checking the SA bias when the tuning is initialized. Set tuning_check_bias to 0 to disable this check entirely. If the check happens and fails, the tuning will set the biases and wait "tuning_therm_time" seconds before continuing.

Structural parameters

array_width

Some parameters specify values for every row and column. These are expressed as one-dimensional lists, such that the correspondence between (row,column) and index into the 1d array is

 index = row + column * array_width

Experiment.cfg

Contents