BNMR: Adding a new mode: Difference between revisions

From DaqWiki
Jump to navigation Jump to search
en>Suz
(New page: {{Pagelinks}} = Links = <div style="column-count:3;-moz-column-count:3;-webkit-column-count:3"> * BNMR * * Experimental Modes * BNMR: Getting Started ...)
 
No edit summary
 
(29 intermediate revisions by 2 users not shown)
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.


* Can an existing ppg script be used? 
== Decide on a new name for the mode ==
** No -> new mode and new ppg script
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!
** 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
New modes with new ppg scripts must be added to rf_config.c and type1_compute.c or type2_compute.c
rf_config.c has to be able to deal with new dummy modes. This include a direction to the actual PPG mode, e.g. 1c is directed to 1f.


Instructions for making a new ppg script haven't yet been written. Basically, start with an existing PPG script and modify it. Be sure to make a timing diagram.
== Add the mode to mode_changer.py ==
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).


* 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.
* In all cases, add the definition of the new mode to the <code>self.modes</code> dictionary.


== mode parameters ==
== Create a new PPG timing scheme ==
The parameters for each mode 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 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.
If a new PPG timing scheme is required:
[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".


* 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.


== /script and /customscript ==
== Write the new feature ==
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 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  {{File|name=../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.
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.
<pre>
[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
</pre>
If loading defaults, create a defaults file  {{File|name=../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 {{Odbpath|path=/customscript}} directory, i.e.
== Handle storing settings in MUD files ==
[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  {{Odbedit cmd|cmd=move}}.
The link in /customscript is necessary to have the script button appear on the custom status page.
== modify change_mode.pl ==


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 <code>set_mud_ind_vars()</code> in <code>ppg_prog_helper.py</code>.
* 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>


== Update custom settings page ==


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


== mode files ==
* Update <code>populate_tables()</code> in <code>settings.js</code> to build the new interface.
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.
<pre>
AAA_README


NOTE: FOR NOW, ONLY EXPERT USERS SHOULD BE CHANGING DEFAULT FILES  !!!
== Update saved settings ==
------------------------------------------------------------------------
[ 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  
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).
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,
* <code>python save_load.py add --odb-path "/path/to/new/setting" --json-value '{"value": true}'</code> etc
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
[[Category:BNMR]] [[Category:Experiment (PPG) Modes]]
  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.
</pre>

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"