BNMR: Adding a new mode
Links
Introduction
Adding a new experimental (PPG) mode takes several steps. First, answer these questions:
| Can an existing ppg script be used? | ||
| Yes Can you just add parameter(s) to an existing mode? |
No new mode and new ppg script | |
| ||
- Can an existing ppg script be used?
- No -> new mode and new ppg script
- Yes -> can you just add parameter(s) to an existing mode? -> Yes -> no new mode needed
- No -> make a new dummy mode, where a different parameter set is displayed, but an existing PPG script can be used
Many of the existing modes are actually "dummy modes", as they redirect to an actual PPG mode for which a PPG script exists.
- Decide whether the new mode (or new dummy mode) is Type 1, Type2 or combination. The combination modes defined so far are named as Type 1 because they save the histograms like the Type 1 modes, not the Type 2 modes.
Run parameters in the ODB
All run parameters used by rf_config and the frontend are those in /Equipment/FIFO_acq/frontend/input and /Equipment/FIFO_acq/frontend/hardware. These parameters are used by all modes (i.e. some parameters are common to some modes, others are unique to one mode). This had the problem that parameters changed for a particular mode, then were set wrongly for another mode. It was not possible to change mode and reliably return to a mode and have the parameters unchanged since the last time it was run.
To get away from this problem, #mode parameters were introduced, unique to each mode. These keep the value from the last run (and enable tunes to be saved and loaded for a particular mode). At the begin-of-run, the mode parameters are copied to the parameters area (by subroutines in update_run_parameters.c called by rf_config) /Equipment/FIFO_acq/frontend/input and /Equipment/FIFO_acq/frontend/hardware.
Adding a new parameter
To add a new parameter that does not yet exist in odb, add it in the parameters area, either /Equipment/FIFO_acq/frontend/input or /Equipment/FIFO_acq/frontend/hardware. Modes that use the new parameters will need this parameters added to the list of #Mode Parameters for that mode. See instructions for adding a mode parameter to an existing mode under #Mode Parameters. Note that adding parameters under /Equipment/FIFO_acq will require making a new experim.h (see #experim) and recompiling clients that include experim.h.
rf_config
All new modes must be added to rf_config.c and update_run_parameters.c - see #mode parameters.
New modes that require new ppg scripts must be also added type1_compute.c or type2_compute.c rf_config.c has to be able to deal with new dummy modes. This may include a direct direction to the actual PPG mode in rf_config.c e.g. 2g is directed to 00, or the mode may be directed in type1_compute.c or type2_compute.c after setting some variables. In this case a function e.g. compute_2g would be required.
Instructions for making a new ppg script haven't yet been written. Basically, start with an existing PPG template and modify it. Be sure to make a timing diagram.
After making all the changes to the ODB and the rf_config files, save the odb Template:Odbedit cmd, and create a new experim.h using Template:Odbedit cmd, e.g.
[bnqr@isdaq01]$ cd ~/online/bnqr [bnqr@isdaq01 bnqr]$ odbedit [local:bnqr:Stopped]/>save bnqr.odb [local:bnqr:Stopped]/>make Analyzer "Analyzer" not found in ODB, skipping analyzer parameters. "experim.h" has been written to /home/bnqr/vmic_online/bnqr [local:bnqr:Stopped]/>quit
Note that the file experim.h must be created in directory /home/bnm[q]r/online/bnm[q]r or equivalent as in example above (online is linked to vmic_online).
Then rebuild rf_config
[bnqr@isdaq01]$ cd ~/online/rf_config [bnqr@isdaq01 rf_config]$ make clean [bnqr@isdaq01 rf_config]$ make
Note that when the odb is changed so that a new experim.h is needed, mdarc and the frontend must also be rebuilt.
mode parameters
The parameters for each mode (see #Introduction) are stored in ODB :
[local:bnqr:Stopped]/>ls "/equipment/FIFO_acq/mode parameters/" Mode 10 Mode 1a Mode 1b Mode 1c Mode 1f Mode 1g Mode 1j Mode 1n Mode 20 Mode 2a Mode 2b Mode 2c Mode 2d Mode 2e Mode 2f
The parameters for e.g. mode 20 (SLR) are shown below :
[local:bnqr:Stopped]/>ls "/equipment/FIFO_acq/mode parameters/mode 20" MCS enable gate (ms) 10 Number of Prebeam dwelltimes 20 Number of Beam On dwelltimes 100 Number of Beam Off dwelltimes 1200 RFon Delay (dwelltimes) 0 RFon Duration (dwelltimes) 0 Flip helicity y Helicity sleep time (ms) 3000 [local:bnqr:Stopped]/>
These parameters are presented to the user by the custom parameter page. They store the parameter values for the last run of that mode. When a run is started, the parameters from this area are copied to the actual input parameters area under /Equipment/Fifo_acq/Input or /Equipment/Fifo_acq/hardware. The copy is done by rf_config, using code in update_run_parameters.c . The psm parameters are set directly in the psm area (no copy is retained elsewhere).
To make a new mode, copy the closest mode, e.g.
[local:bnqr:Stopped]/>cd "/equipment/FIFO_acq/mode parameters/" [local:bnqr:Stopped]/mode parameters> cp "Mode 20" "Mode 2g"
where the new mode is to be called "2g". Then modify or add more parameters in directory "Mode 2g".
Create a new function copy_XX (where XX is the new mode name) in update_run_parameters.c to copy the local #mode parameters to the actual parameters in /Equipment/FIFO_acq/frontend/input and /Equipment/FIFO_acq/frontend/hardware. This subroutine will be called by rf_config at the begin-of-run. Also add the new function to copy_run_parameters.h and increase MAX_COPY_EXPT in the same file.
Adding a parameter to an existing mode
If the parameter is not already defined under /Equipment/FIFO_acq/frontend/input or /Equipment/FIFO_acq/frontend/hardware, add it first (see #Adding a new parameter). Then add it to the mode parameters for the existing mode (say Mode YY) under /equipment/FIFO_acq/mode parameters/mode YY.
Modify copy_YY to copy the new parameter to the input parameter area.
- Note
Adding parameters under /Equipment/FIFO_acq will require making a new experim.h (see #experim) and recompiling clients that include experim.h.
/script and /customscript
Each mode button (i.e. button to change mode) is a script button (on the MIDAS status page) and a customscript button (on the custom status page). The script/customscript button causes the perlscript change_mode.pl to run and change the mode. The customscript buttons are actually links to the script buttons. The script button is named for the mode (e.g. SLR, 1c). The script button "SLR" is defined in ODB as follows:
[local:bnqr:Stopped]SLR>ls
cmd /home/bnqr/vmic_online/perl/change_mode.pl
include path /home/bnqr/vmic_online/perl
experiment name -> /experiment/name
bnqr
select mode 20
mode file tag defaults
The name of the script to run is given in the key cmd, and the parameters sent to the script are listed in the other keys. Although this script key is names "SLR", the select mode is set to "20", which is the name of the mode that rf_config uses. The key mode file tag indicates whether an optional mode file is to be loaded into ODB on changing to this mode. If left blank, no file is loaded. The example shows the value "defaults", which causes change_mode.pl to load the file ../online/modefiles/20_defaults.odb into the ODB on changing mode. To change this file for the new mode, follow instructions in #mode files.
To add a new mode, copy an existing mode and modify e.g.
[local:bnqr:Stopped]/Script>copy SLR 2g [local:bnqr:Stopped]/Script>copy SLR 2g [local:bnqr:Stopped]/Script>cd 2g [local:bnqr:Stopped]2g>set "select mode" 2g
If loading defaults, create a defaults file ../online/modefiles/2g_defaults.odb by copying and modifying 20_defaults.odb . Otherwise, set "mode file tag" blank (no mode file loaded).
All a link to the new mode in the ODB /customscript directory, i.e.
[local:bnqr:Stopped]2g>cd /customscript [local:bnqr:Stopped]/CustomScript>ln /script/2g 2g [local:bnqr:Stopped]/CustomScript>move 2g 15
The new link is moved into the desired position with the Template:Odbedit cmd. The link in /customscript is necessary to have the script button appear on the custom status page.
ls
modify change_mode.pl
New modes have to be added to ~/bn[mq]r/online/perl/change_mode.pl. There are several places to add the new mode.
- check that the mode exists (# make a few sanity checks)
- removing the link for new mode (add call to remove_a_link for new mode)
- load _last_psm.odb if new mode uses RF
File change_mode.pl calls subroutines in do_link.pl. These subroutines do not need to be changed when a new link is added.
mode files
When the experimental mode is changed on the custom page, e.g. SLR to 1f, the perlscript change_mode.pl runs. It does various things, including possibly loading a mode file. This is a file loaded into the ODB to set certain parameters to default values on changing mode. The mode files can be found in ..online/modefiles. There is a file AAA_README (reproduced below) that explains how to change these files.
AAA_README NOTE: FOR NOW, ONLY EXPERT USERS SHOULD BE CHANGING DEFAULT FILES !!! ------------------------------------------------------------------------ [ All instructions refer to experiment bnmr. For bnqr, substitute bnqr for bnmr.] This directory contains files of default settings of ODB parameters which are to be automatically loaded when the experimental mode (i.e. PPG Mode) is changed. For example, when mode "freq" is selected on the main status page of the browser, the file 1f_defaults.odb is to be loaded. ******************************************************************************** *** After editing these files, IT IS ESSENTIAL to run check_file.pl on them *** *** to make sure that the key names exist in the odb. *** ******************************************************************************** The odbedit "load" command used to load the files will automatically create any keys that do not exist. This will almost certainly cause the DAQ system to fail with a Recordsize error at the start of the next run. If a spurious key is created by mistake, it must be deleted from the ODB (using e.g. odbedit rm command ) before the run can start. ========================================================= = To check a file with check_file.pl, the command is = = = = cd ~bnmr/$ONLINE/modefiles = = check_file.pl <filename> = = = = e.g. check_file.pl 1f_defaults.odb = ========================================================= This perlscript (check_file.pl) invokes another perlscript, called mode_check.pl to check the file. To control which file of defaults gets loaded (or none): ---------------------------------------------------------- Provision has been included to load one of the following on changing mode: A. no default file B. a file of defaults C. a file of the user's choosing Only an expert user should mess with this! In the odb, in directory /scripts there is a sub-directory for every supported mode. Using odbedit in an xterm, $ odbedit [local:bnmr:S]/>ls /Script/freq cmd /home/bnmr/online/perl/change_mode.pl include path /home/bnmr/online/perl experiment name /experiment/name select mode 1f mode file tag defaults [local:bnmr:S]/>exit $ The keys "select mode" and "mode file tag" are combined to specify which file is to be loaded when changing mode. In this case, the file will be ~bnmr/$ONLINE/modefiles/1f_defaults.odb To specify no file is to be loaded, "mode file tag" is set to "none". To specify some other file, say 1f_mytest.odb, "mode file tag" must be set to "mytest" To change or add/remove default settings to the file ----------------------------------------------------- The files are in ASCII, in the format used by the odbedit "save" command, e.g. for 1f_defaults.odb [/Equipment/FIFO_acq/Frontend/Hardware/PSM] ALL profiles enabled = BOOL : n one_f profile enabled = BOOL : y three_f profile enabled = BOOL : n five_f profile enabled = BOOL : n fREF profile enabled = BOOL : n quadrature modulation mode = BOOL : y scale factor (def 181 max 255) = INT : 181 The first line is the DIRECTORY The following lines are those KEYS in that directory that need default values. Only those keys that require default values are specified. Any others will not be changed when the file is loaded. To add keys in a second directory, add a line with the new directory, followed by line(s) containing the key(s). Edit the file, e.g. $ cd ~bnmr/$ONLINE/modefiles $ emacs 1f_defaults.odb Changing/removing default settings is easy. Just edit the value, or delete the whole key. Adding a new key or directory requires care. The safest way is to find the new key and/or directory in a recent odb saved file. You can create your own by using the odbedit command "save", in the directory of the key you wish to add. e.g. $ odbedit $ cd "/equipment/fifo_acq/Frontend/hardware" $ save temp.odb Copy the keys you need from the file "temp.odb" into the default file. Otherwise you can find all the information saved in the file ~bnmr/$ONLINE/bnmr/bnmr.odb, which is a saved version of the whole odb. Copy the new key and/or directory to the defaults file you are editing EXACTLY as it appears in the saved odb file. Change the value as desired. Save the file, and ALWAYS RUN check_file.pl (see above) on it to check the validity of the keys.
/PPG
In the ODB directory /PPG there is a subdirectory for each mode containing links to the actual parameters in /Equipment/FIFO_acq/frontend/input and /Equipment/FIFO_acq/frontend/hardware. These are needed if anyone is using the Midas status page, rather than the Custom status page. They therefore are no longer used much, but should be provided in case of failure of the custom status page.
Tunes
Create a directory for tunes under /home/bn[mq]r/online/tunes, e.g.
[bnqr@isdaq01 tunes]$ mkdir mode_2g
This directory will contain any tunes the user may create, and the files used to reload the saved settings when the mode is changed. Create _current.odb and _last.odb in this directory by saving the #mode parameters e.g.
[bnqr@isdaq01 tunes]$ cd mode_2g [bnqr@isdaq01 mode_2g]$ odb [local:bnqr:Stopped]>cd "/Equipment/FIFO_acq/mode parameters/mode 2g" [local:bnqr:Stopped]>save _last.odb [local:bnqr:Stopped]>save _current.odb [local:bnqr:Stopped]>quit [bnqr@isdaq01 mode_2g]$ ls _current.odb _last.odb [bnqr@isdaq01 mode_2g]$ less _current.odb [/Equipment/FIFO_acq/mode parameters/Mode 2g] MCS enable gate (ms) = FLOAT : 10 Number of Prebeam dwelltimes = DWORD : 20 Number of Beam On dwelltimes = DWORD : 100 Number of Beam Off dwelltimes = DWORD : 1200 Flip helicity = BOOL : y Helicity sleep time (ms) = INT : 3000
If the mode needs the psm parameters, copy psm parameter files _current_psm.odb and _last_psm.odb from another mode, or save them from odb in a similar way.
tunes.pl
If new tunes does not use PSM parameters, add mode to pattern match in tunes.pl to make $needpsm be 0.
Custom Status Page
All custom pages to run with mhttpd are located in directory /home/bn[mq]r/custom/. The new mode must be added to the custom status page. The modes are generated in file cs_functions.js. Add the new mode name to array mode1Names[] or mode2Names[] where appropriate. If adding a type1 mode, increment num_type1_modes, the number of actual type1 modes excluding combined modes. Add any comment to mode1Info[] or mode2Info[]. Add a link to the timing diagram in the array diag[]. In function build_ppgmode_buttons() add the new mode to the switch and assign the index idx.
Custom Parameters Page
All custom pages to run with mhttpd are located in directory /home/bn[mq]r/custom/. In parameters.html, again add a link to the timing diagram in the array diag[]. Add the special name if appropriate to ppg_mode_array[] and ppg_mode_names[].
If new parameters have been added in /Equipment/FIFO_acq/frontend/input and /Equipment/FIFO_acq/frontend/hardware for the new mode, these parameters must be added as globals. They may need to be added in functions setup_ppgmode(), setup_true_ppg_paths(), get_globals() Add the mode as required to appear in the parameters list as required in functions setup_rf() write_freq_scan_params(), write_all_params() check_consistency() etc. Add the new mode to the appropriate pattern to have the parameter appear in the mode's parameter list.