BNMR: Adding a new mode: Difference between revisions

From DaqWiki
Jump to navigation Jump to search
m (Bsmith moved page DaqWiki:BNMR: Adding a new mode to BNMR: Adding a new mode without leaving a redirect)
No edit summary
 
Line 1: Line 1:
{{Pagelinks}}
{{Pagelinks}}
= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[BNMR]]
*
* [[BNMR: Experimental Modes|Experimental Modes]]
* [[BNMR: Getting Started]]
</div>


==Introduction==
== Introduction ==
Adding a new experimental (PPG) mode takes several steps. First, answer these questions:
Adding a new experimental mode takes several steps. The exact changes depend on whether a new feature is required, or if the mode is just enabling a new combination of existing features.
<center>
{|  style="text-align: center; width: 75%; background-color: rgb(255, 255, 255);" border="5" cellpadding="2" cellspacing="2"
|+  Mode Decision Table
|-
| colspan="2" style="vertical-align: top; color: navy; font-weight: bold; text-align: left;" |
<span style="color:white">spacerspacerspacer</span> 1. Can an existing ppg script be used for the new mode?
|-
|  colspan="1" style="text-align:center; vertical-align: top; color:green; font-weight: bold;" | Yes
|  colspan="1" style="text-align:center; vertical-align: top; color:maroon; font-weight: bold;" |
<span style="color:white">spacerspacerspacer</span> No <span style="color:white">spacerspacerspacer</span>
|-
| colspan="1" style="text-align:center; vertical-align: top; color:navy; font-weight: bold;" |2. Can you just add parameter(s) to an existing mode?
| colspan="1" style="rowspan=1 text-align:center; vertical-align: top; font-weight: normal;" |
* new mode and
* new [[BNMR: PPG scripts|ppg script]]
|-
| colspan="1" style="text-align:center; vertical-align: top; " |


{|  style="text-align: center; width: 100%; " border="1" cellpadding="2" cellspacing="2"
== Decide on a new name for the mode ==
|-
Historically all [[BNMR#Experimental_modes|BNMR/BNQR modes]] are named as 2-character strings, starting with a 1 for TI modes and a 2 for TD modes. There is no significant logic to the second character, but the first character is important for user comprehension!
|  colspan="1" style="text-align:center; vertical-align: top; top; color:green;  font-weight: bold;" | Yes
|  colspan="1" style="text-align:center; vertical-align: top;  top; color:maroon; font-weight: bold;" | No
|-


| colspan="1" style="text-align:left; vertical-align: top;  font-weight: normal;" |
== Add the mode to mode_changer.py ==
* new mode not needed
Modes are defined in the <code>mode_changer.py</code> script. Most other code doesn't refer explicitly to mode names, and only looks at which features are enabled for a given mode (by looking at the flags in {{Odbpath|path=/CurrentMode}} in the ODB).
|  colspan="1" style="vertical-align: top; text-align:left; font-weight: normal;" |
*  make a new dummy mode,<br> where a different parameter set is displayed
*  use an existing PPG script
|}
|}
</center>


Many of the existing modes are actually "dummy modes", as they redirect to an actual PPG mode for which a PPG script exists. Examples of dummy modes are 1n (NaCell scan),
* If a new feature is required, add a new flag to the <code>ModeFeatures</code> class. Set the default value such that existing classes will NOT enable the new feature.
and 1c (Camp scan), because they both use the PPG script for 1f (frequency scan).
* In all cases, add the definition of the new mode to the <code>self.modes</code> dictionary.


Decide whether the new mode (or new dummy mode) is Type 1, Type 2 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. Type 2 modes store the histograms in memory allocated by frontend (Histogram Memory), then save the histograms directly to .msr (MUD) files. Type 1 modes send out the scaler data at each scan value which are saved into a .mid (midas) file. The midas file is then converted to MUD format.
== Create a new PPG timing scheme ==


== Run parameters in the ODB ==
If a new PPG timing scheme is required:
Excluding the PSM parameters, all '''run parameters''' used by [[rf_config]] and the frontend are those in  {{Odbpath|path=/Equipment/FIFO_acq/frontend/input}} and {{Odbpath|path=/Equipment/FIFO_acq/frontend/hardware}}. These parameters may be used by any mode (i.e. some parameters are common to some modes, others are unique to one mode). Links to the run parameters used by a particular mode are listed under {{Odbpath|path=/PPG/PPG<mode>}} (see [[#/PPG ODB tree]]).


Sharing the parameters between modes had the problem that parameters changed for a particular mode were then 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.
* Define any "questions" that the user should answer to configure the timing scheme in <code>self.default_ppg_questions</code> in <code>mode_changer.py</code>.
* Handle the new mode in <code>compute_ppg()</code> in <code>ppg_prog_helper.py</code> (used by <code>rf_calculator_fe.py</code>). This should generate the <code>cycling_framework.ppg.compiler.Program</code> that defines the PPG timing.


To solve this problem, [[#mode parameters]] were introduced, unique to each mode. These store the value from the last run (and enable tunes to be saved and loaded for a particular mode). The name of the run parameter can be different from that of the input parameter.  '''At the begin-of-run, the mode parameters are copied to the run parameters area''' (by subroutines in {{File|name=update_run_parameters.c}} called by rf_config)  {{Odbpath|path=/Equipment/FIFO_acq/frontend/input}} and {{Odbpath|path=/Equipment/FIFO_acq/frontend/hardware}}.  The mode parameters are also saved into the [[#Tunes]] directory, so that when this mode is selected in the future, the saved parameters can be loaded automatically.
== Write the new feature ==


'''PSM parameters'''  (in ODB subtree {{Odbpath|path=/Equipment/FIFO_acq/frontend/hardware/PSM}}) are treated differently. These are only required for modes that use RF, and were never presented with different names. For modes that use RF, all the PSM parameters are also saved as files in the [[#Tunes]] directory when the run starts. When the user changes mode to a mode that uses the PSM, the saved PSM parameters are loaded in addition to the saved mode parameters.
If a new feature is required, write the code for the new feature. Use the ODB for any settings that the user might want to configure.


== Handle storing settings in MUD files ==


If there is a new PPG timing scheme or a new feature that is configurable, any settings the user can configure should be stored in the MUD file as "independent variables":


== Adding a new run parameter ==
* Store the new settings by calling <code>set_mud_ind_vars()</code> in <code>ppg_prog_helper.py</code>.
To add a new run parameter that does not yet exist in ODB, add it in the run parameters area, either
* If some custom logic was needed when storing the variable (e.g. the ODB flag is a bool, but was stored as a string in the MUD file), edit <code>load_from_old_run()</code> in <code>mode_changer.py</code>
* <span style="color: purple; font-style:italic;">/Equipment/FIFO_acq/frontend/input</span> or
* <span style="color: purple; font-style:italic;">/Equipment/FIFO_acq/frontend/hardware</span>. 


PPG Modes that use the new parameters will need the new parameter added to
== Update custom settings page ==
# the links to the run parameters in the <span style="color: purple; font-style:italic;">/PPG</span> tree (see [[#/PPG ODB tree]]).
# the list of [[#Mode Parameters]]


Note;
If there is a new PPG timing scheme or a new feature that is configurable:
:adding parameters under  <span style="color: purple; font-style:italic;">/Equipment/FIFO_acq</span>  will require making a new <span style="color:#b3b3ff ; font-style:italic; ">experim.h</span> (see [[#experim]]) and recompiling clients that include <span style="color:#b3b3ff ; font-style:italic; ">experim.h</span>.


* Update <code>populate_tables()</code> in <code>settings.js</code> to build the new interface.


== /PPG ODB tree ==
== Update saved settings ==
In the ODB directory {{Odbpath|path=/PPG}} there is a subdirectory for each mode containing links to the actual parameters in  {{Odbpath|path=/Equipment/FIFO_acq/frontend/input}} and {{Odbpath|path=/Equipment/FIFO_acq/frontend/hardware}}.  This directory was used to set the PPG parameters before the Custom Parameter page was written, and is still used to access the run parameters by some clients (mdarc).  They are also required if anyone is using the Midas status page, or there is a problem with the Custom Parameter page.


Therefore the  {{Odbpath|path=/PPG}} ODB tree '''must be kept up-to-date'''. Any new parameters added to existing modes, or new modes created must be added to the   {{Odbpath|path=/PPG}} tree.
If there is a new feature that is configurable, update any saved settings for other modes to ensure that the feature is not enabled when those settings are loaded. This command must be run on the main DAQ PC, and run separately for each experiment (BNMR/BNQR).


== Rebuild frontend  ==
* <code>python save_load.py add --odb-path "/path/to/new/setting" --json-value '{"value": true}'</code> etc
Most likely the frontend will use the new run parameter(s). After modifying, [[#experim|rebuild the frontend]].


{{File|name=..online/rf_config/rf_config will probably need to be modified and rebuilt -  see [[#Modify rf_config routines]].
<div id="experim"></div>
After making all the changes to the ODB and the rf_config (and frontend) files,  save the odb {{Odbedit cmd|cmd=save}}, and create a new experim.h using {{Odbedit cmd|cmd=make}}, 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  {{Filepath|path=/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 mode parameters for each mode (see [[#Introduction]]) are stored in ODB :
<pre>
[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       
</pre>
The parameters for e.g. mode 20 (SLR) are shown below :
<pre>
[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]/>
</pre>
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).
=== Adding a new mode ===
If adding a new mode, first make a subdirectory by copying the closest mode, e.g.
[local:bnqr:Stopped]/>cd "/equipment/FIFO_acq/mode parameters/"
[local:bnqr:Stopped]/mode parameters> cp "Mode 20" "Mode 2x"
where the new mode is to be called "2x".
Then modify or add more parameters in directory "Mode 2x".
==== Modify rf_config routines ====
Copy and modify an existing ''copy_*'' function to create a new function  (i.e. ''copy_2x'' where new mode is "2x")  in {{File|name=update_run_parameters.c}}. These functions copy the local [[#mode parameters]] to the actual parameters in {{Odbpath|path=/Equipment/FIFO_acq/frontend/input}} and {{Odbpath|path=/Equipment/FIFO_acq/frontend/hardware}}.  The appropriate function will be called by {{File|name=rf_config}} at the begin-of-run.
Also add the new function to  {{File|name=copy_run_parameters.h}}.
Add the new mode to {{File|name=..online/rf_config/rf_config.c}}. The modes are directed to a function ''exx_compute'' in either  {{File|name=type1_compute.c}} or {{File|name=type2_compute.c}}.  A mode may be  a "dummy", where the mode is directed to the exx_compute of an actual PPG mode. PPG modes have a PPG script associated with them. For example, modes 1j,1g and 2h are all "dummy" modes which call e00_compute after setting some parameters unique to the dummy mode. They all use the ppg template associated with Mode 20 (the PPG mode) to create the PPG load file.
If adding a new PPG mode (with new ppg template(s)), add the associated exx_compute function to  {{File|name=type1_compute.c}} or {{File|name=type2_compute.c}}. These routines read values from the ODB in order to calculate the parameters for the ppg load file. Add the template for the new exx_compute function into rf_config.h.
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.
Modify
;Note
: New modes and new parameters must also be added to the [[#/PPG ODB tree]].
=== Adding a parameter to an existing mode ===
If the parameter is not already defined as a run parameter under {{Odbpath|path=/Equipment/FIFO_acq/frontend/input}} or {{Odbpath|path=/Equipment/FIFO_acq/frontend/hardware}}, create it first (see [[#Adding a new parameter]]).
Then add it to the mode parameters for the existing mode (say Mode 1y) under {{Odbpath|path=/equipment/FIFO_acq/mode parameters/mode 1y}}.  Modify [[#Modify rf_config routines|function copy_1y]] to copy the new mode parameter to the input parameter area.
;Note
: New modes and new parameters must also be added to the [[#/PPG ODB tree]].
== /script and /customscript ODB trees ==
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:
<pre>
[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
</pre>
The name of the script to run is given in the key {{Odbpath|path=cmd}}, and the parameters sent to the script are listed in the other keys.  Although this script key is names "SLR", the {{Odbpath|path=select mode}} is set to "20", which is the name of the mode that rf_config uses. The key
{{Odbpath|path=mode file tag}} indicates whether an optional [[#default files|default 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  {{File|name=../online/modefiles/20_defaults.odb}} into the ODB on changing mode. To change this file for the new mode, follow instructions in [[#default files]].
To add a new mode, copy an existing mode and modify e.g.
<pre>
[local:bnqr:Stopped]/Script>copy SLR 2x
[local:bnqr:Stopped]/Script>copy SLR 2x
[local:bnqr:Stopped]/Script>cd 2x
[local:bnqr:Stopped]2g>set "select mode" 2x
</pre>
If loading defaults, create a defaults file  {{File|name=../online/modefiles/2x_defaults.odb}} by copying and modifying 20_defaults.odb . Otherwise, set "mode file tag" blank (no mode defaults file loaded).
<small>
;Note
: Loading a file other than "defaults" is supported but has not been used. A file 20_xxx.odb would be loaded if the "mode file tag" is set to "xxx" where the name "xxx" is chosen by the user.
</small>
All a link to the new mode in the ODB {{Odbpath|path=/customscript}} directory, i.e.
[local:bnqr:Stopped]2x>cd /customscript
[local:bnqr:Stopped]/CustomScript>ln /script/2x 2x
[local:bnqr:Stopped]/CustomScript>move 2x 15
The new link is moved into the desired position with the  {{Odbedit cmd|cmd=move}}.
The link in /customscript is necessary to have the button appear on the custom status page.
 
== modify change_mode.pl ==
New modes have to be added to {{Filepath|path=~/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 (see [[#Tunes]])
File  {{File|name=change_mode.pl}} calls subroutines in  {{File|name=do_link.pl}}. These subroutines do not need to be changed when a new link is added.
== default 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 default mode file. This is a file loaded into the ODB to set certain parameters to default values on changing mode. This is needed because many modes share parameters, and different modes may require different default values for these parameters. 
The default mode files can be found in ..online/modefiles. There is a file AAA_README (reproduced below) that explains how to change these files.
<pre>
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.                      ***
********************************************************************************
  This is because 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 ONE default file with check_file.csh:      =
=  on the host computer  (NOT vmic)                    =
== Modify Custom Parameters Page ==
All custom pages to run with {{Utility|name=mhttpd}} are located in directory {{Filepath|path=/home/bn[mq]r/custom/}}.
In {{File|name=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[]. For example, Mode 20 has the special name "SLR".
{{File|name=parameters.html}} includes functions in the file {{File|name=parameter_functions.js}}. Functions in this javascript file determine which parameters appear for a particular mode. For each parameters, pattern matches determines which mode(s) require that parameter. For example, 
// RF used by modes  1a 1b 1f 1g 1h 20 2a 2b 2c 2d 2e 2h
  pattern1 = /1[abfgh]/;
  pattern2 = /2[0abcdefh]/;
If new parameters have been added in {{Odbpath|path=/Equipment/FIFO_acq/frontend/input}} and {{Odbpath|path=/Equipment/FIFO_acq/frontend/hardware}} for the new mode, these parameters must be added as globals at the top of {{File|name=parameter_functions.js}}.  In function setup_ppgmode(), add the path of each new parameter including ''ppg_mode_path'', which will be set to the ODB path {{Odbpath|path=/Equipment/FIFO_acq/mode parameters/Mode xx}}  where xx is the mode containing the new parameter(s).
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.
[[Category:BNMR]] [[Category:Experiment (PPG) Modes]]
=  cd ~bnmr/$ONLINE/modefiles                          =
=  check_file.csh  <filename>                          =
=                                                      =
=    e.g. check_file.csh  1f_defaults.odb              =
=                                                      =
=  To check ALL the default files,                      =
=    check_all.csh                                      =
=                                                      =
=========================================================
The scripts (check_file.csh, check_all.csh) invokes perlscripts
check_file.pl and mode_check.pl to check the file. 
check_all.csh uses ls *.odb to find all the default files in the directory.
If it detects a failure on a default file, it will stop. Correct the
offending file and rerun until all files are correct. You should see the
message :
  "All *.odb files have been checked successfully"
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 {{File|name=~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.
</pre>
== Tunes ==
The '''Tunes directory''' for each mode is found under  {{Filepath|path=~bn[mq]r/online/tunes}}. A subdirectory is created for each mode, e.g. for mode 20 tunes files with be in directory  {{Filepath|path=~bn[mq]r/online/tunes/mode_20}}.
The Tunes directory for each mode contains files ''automatically created by the perlscript'' {{File|name=tunes.pl}}.
* a file  <span style="color:navy ; font-style:italic; ">_last.odb</span>  a saved odb file containing the mode parameters and values for the last time this mode was run
* a file <span style="color:navy ; font-style:italic; ">_current.odb</span>  a saved odb file containing the mode parameters and current values. These will be the same as _last.odb unless the user has changed some values since the last time this mode was run.
* a file <span style="color:navy ; font-style:italic; ">_last_psm.odb</span> if the mode uses RF. This is a saved odb file containing the psm parameters and values for the last time this mode was run.
* a file <span style="color:navy ; font-style:italic; ">_current_psm.odb</span> if the mode uses RF. This is a saved odb file containing the psm parameters and current values. These will be the same as <span style="color:navy ; font-style:italic; ">_last_psm.odb</span> unless the user has changed some PSM values since the last time this mode was run.
* optionally tune files (e.g. <span style="color:navy ; font-style:italic; ">mytune.odb</span>) saved by the users, saving the mode parameters and their values for states they might want to return to.
* optionally psm files  (e.g. <span style="color:navy ; font-style:italic; ">mytune_psm.odb</span>) for each tune saved by the users when they saved a tune, if this mode uses RF.
* a file <span style="color:navy ; font-style:italic; ">tune_names.odb</span> containing the current list of saved tunes
Create a directory for the new mode under {{Filepath|path=/home/bn[mq]r/online/tunes}}, e.g.
[bnqr@isdaq01 tunes]$ mkdir mode_2x
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.
<pre>
[bnqr@isdaq01 tunes]$ cd mode_2x
[bnqr@isdaq01 mode_2x]$ odb
  [local:bnqr:Stopped]>cd "/Equipment/FIFO_acq/mode parameters/mode 2x"
  [local:bnqr:Stopped]>save _last.odb
  [local:bnqr:Stopped]>save _current.odb
  [local:bnqr:Stopped]>quit
[bnqr@isdaq01 mode_2x]$ ls
_current.odb  _last.odb
[bnqr@isdaq01 mode_2x]$ less _current.odb
  [/Equipment/FIFO_acq/mode parameters/Mode 2x]
  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
</pre>
If the mode needs the psm parameters, copy psm parameter files  {{File|name=_current_psm.odb}] and  {{File|name=_last_psm.odb}} from another mode, or save them from odb in a similar way.
== Modify tunes.pl ==
If the new tune does NOT use PSM parameters, add the mode to the pattern match in  {{File|name=tunes.pl}} to make $needpsm be 0.
== Modify Custom Status Page ==
All custom pages to run with {{Utility|name=mhttpd}} are located in directory {{Filepath|path=/home/bn[mq]r/custom/}}.
The new mode must be added to the custom status page. The modes are generated in file {{File|name=cs_functions.js}}.
The mode names for each type are listed in array ''mode1Names[]'' or ''mode2Names[]''. Only those modes available for  {{bnmqr|join=or}} should be listed.
;NOTE
Since adding PPG modes 1h and 2h (Alpha) to {{bnqr}} only,  ''mode1Names'' and ''mode2Names'' arrays have been moved to a file  {{File|name=bnqr_params.js}}  defined under  {{Odbpath|path=/custom/expt_specific!}}. For {{bnmr}}, mode1Names and mode2Names are currently still found in {{File|name=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[]''.
Also in file {{File|name=cs_functions.js}}
# in function ''build_ppgmode_buttons()'' add the new mode to the switch and assign the index ''idx''.
# Add a link to the timing diagram in the array ''diag[]''.
== Modify Custom Parameters Page ==
All custom pages to run with {{Utility|name=mhttpd}} are located in directory {{Filepath|path=/home/bn[mq]r/custom/}}.
In {{File|name=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[]. For example, Mode 20 has the special name "SLR".
{{File|name=parameters.html}} includes functions in the file {{File|name=parameter_functions.js}}. Functions in this javascript file determine which parameters appear for a particular mode. For each parameters, pattern matches determines which mode(s) require that parameter. For example, 
// RF used by modes  1a 1b 1f 1g 1h 20 2a 2b 2c 2d 2e 2h
  pattern1 = /1[abfgh]/;
  pattern2 = /2[0abcdefh]/;
If new parameters have been added in {{Odbpath|path=/Equipment/FIFO_acq/frontend/input}} and {{Odbpath|path=/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.


[[Category:BNMR]] [[Category:Experiment (PPG) Modes]]
[[Category:BNMR]] [[Category:Experiment (PPG) Modes]]

Latest revision as of 11:43, 26 April 2022

Introduction

Adding a new experimental mode takes several steps. The exact changes depend on whether a new feature is required, or if the mode is just enabling a new combination of existing features.

Decide on a new name for the mode

Historically all BNMR/BNQR modes are named as 2-character strings, starting with a 1 for TI modes and a 2 for TD modes. There is no significant logic to the second character, but the first character is important for user comprehension!

Add the mode to mode_changer.py

Modes are defined in the mode_changer.py script. Most other code doesn't refer explicitly to mode names, and only looks at which features are enabled for a given mode (by looking at the flags in /CurrentMode in the ODB).

  • If a new feature is required, add a new flag to the ModeFeatures class. Set the default value such that existing classes will NOT enable the new feature.
  • In all cases, add the definition of the new mode to the self.modes dictionary.

Create a new PPG timing scheme

If a new PPG timing scheme is required:

  • Define any "questions" that the user should answer to configure the timing scheme in self.default_ppg_questions in mode_changer.py.
  • Handle the new mode in compute_ppg() in ppg_prog_helper.py (used by rf_calculator_fe.py). This should generate the cycling_framework.ppg.compiler.Program that defines the PPG timing.

Write the new feature

If a new feature is required, write the code for the new feature. Use the ODB for any settings that the user might want to configure.

Handle storing settings in MUD files

If there is a new PPG timing scheme or a new feature that is configurable, any settings the user can configure should be stored in the MUD file as "independent variables":

  • Store the new settings by calling set_mud_ind_vars() in ppg_prog_helper.py.
  • If some custom logic was needed when storing the variable (e.g. the ODB flag is a bool, but was stored as a string in the MUD file), edit load_from_old_run() in mode_changer.py

Update custom settings page

If there is a new PPG timing scheme or a new feature that is configurable:

  • Update populate_tables() in settings.js to build the new interface.

Update saved settings

If there is a new feature that is configurable, update any saved settings for other modes to ensure that the feature is not enabled when those settings are loaded. This command must be run on the main DAQ PC, and run separately for each experiment (BNMR/BNQR).

  • python save_load.py add --odb-path "/path/to/new/setting" --json-value '{"value": true}' etc
Retrieved from "https://daq00.triumf.ca/DaqWiki/index.php?title=BNMR:_Adding_a_new_mode&oldid=6232"