BNMR: Shift Monitor: Difference between revisions

From DaqWiki
Jump to navigation Jump to search
en>Suz
mNo edit summary
No edit summary
 
(3 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|Getting Started]]
</div>
 


== Introduction ==
== Introduction ==
The BNMR shift monitor system consists of two perlscripts in directory  {{Filepath|path=/home/bnmr/online/perl}} :
The BNMR shift monitor system consists of the python program {{File|name=bnxr_common/beamtime_monitor.py}}, which is
<ul>
run as a '''cron job''' during the beam period.  It run as user ''bnmr'', and accesses the required information from both the {{bnmqr|join=and}} ODBs.
<li>    {{File|name=monitor.pl}}
<li>    {{File|name=cycle_monitor_logfiles.pl}}
</ul>
both of which are normally run as cron jobs.  They are run as user ''bnmr'', and access the required information from both the {{bnmqr|join=and}} ODBs.
 
 
The Shift Monitor program  {{File|name=monitor.pl}} keeps a running total of how much usable beam time  (in minutes) each TRIUMF experimental group has had access to, while running as experiment {{bnmqr|join=or}} (or both).  It reads the proton current from EPICS once per minute.
The information is stored in shift files in the directory  {{Filepath|path=/isdaq/data1/bnmr/mon/<year>/}}. This is also the location of the log files used to store messages.
== How it works ==
 
The perlscript  {{Filepath|path=/home/bnmr/online/perl/monitor.pl}}  is run on isdaq01 (i.e. the midas host for  {{bnmqr|join=and}} experiments)  as a cron job  (except for testing).  Its output is written to a log file. It is run '''only''' as user {{bnmr}},  which has permission to access the EPICS variables needed.


The script determines which TRIUMF experimental group is running by reading the '''experiment number''' from the ODB parameter {{Odbpath|path=/Experiment/Edit on start/experiment number}} on both experiments. Access to the {{bnqr}} ODB is done using {{Utility|name=odbedit}}, i.e.
The shift monitor keeps a running total of how much usable beam time (in minutes) each TRIUMF experimental group has had access to, while running as experiment {{bnmqr|join=or}} (or both). It reads the proton current from EPICS once per minute.
{|  style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="0" cellpadding="2" cellspacing="2"
The information is stored as text files in the directory {{Filepath|path=/isdaq/data1/bnmr/mon/<year>/}}, alongside an Excel spreadsheet that summarises each campaign. The text files are updated every minute, and the Excel spreadsheet every 8 hours.


|-
== beamtime_monitor.py ==
|for  <span style="color:#7b68ee; font-style=italic">bnmr</span>
This script is responsible for reading the state of the beamlines and DAQ systems, and recording summaries in text files.
| '' odbedit -c 'ls "/Experiment/Edit on start/experiment number" ' ''


|-
=== How it works ===
| for <span style="color:#20b2aa; font-style=italic">bnqr</span>
| '' odbedit -h isdaq01:1177 -e bnqr  -c 'ls "/Experiment/Edit on start/experiment number" ' ''
|}


The script determines which TRIUMF experimental group is running by reading the '''experiment number''' from the ODB parameter {{Odbpath|path=/Experiment/Edit on start/experiment number}} on both experiments. Access to both ODBs uses Midas' python tools.


The perlscript {{File|name=monitor.pl}} reads the proton current from EPICS (via ''caget "CCS2ISAC:BL2ACURRENT"'').
The program reads the proton current from EPICS (via <code>caget "CCS2ISAC:BL2ACURRENT"</code>).
<ul>
<ul>
<li> If it is below the threshold value (supplied as the first  [[#Input Parameter|input parameter]] to {{File|name=monitor.pl}}),  it exits.</li>
<li> If it is below the threshold value (supplied as the first  [[#Input Parameter|input parameter]] to {{File|name=monitor.pl}}),  it exits.</li>
Line 49: Line 25:
  </li>
  </li>
</ul>
</ul>
<li> It reads the [[#How it works|experiment number]] from the enabled experiment(s).  The experiment number must be > 0, otherwise no beam time will be allocated.</li>
<li> It reads the [[#How it works|experiment number]] from the enabled experiment(s).  The experiment number must be valid (0 < expt_num < 9999), otherwise no beam time will be allocated and an error will be reported </li>
<li> The program determines the name of the shift file by date and by 12-hour shift (AM/PM).</li>
<li> The program determines the name of the shift file by date and by 12-hour shift (AM/PM).</li>
<li> If no file of that filename exists, it is created and a line written for each different experiment number, and each running experiment assigned 1 minute of running time.  </li>
<li> If no file of that filename exists, it is created and a line written for each different experiment number, and each running experiment assigned 1 minute of running time.  </li>
<li> If {{bnmqr|join=and}} are '''both''' running with the '''same''' experiment number, only one line will be created with {{bnmqr|join=and}} experiments each given 1 minute accumulated time. </li>
<li> If {{bnmqr|join=and}} are '''both''' running with the '''same''' experiment number, only one line will be created with {{bnmqr|join=and}} experiments each given 1 minute accumulated time. </li>
<li> If there is an existing file, the program looks for a line with the experiment number. If it finds one, the accumulated time is incremented for the appropriate experiment.  All other lines are copied and an updated file is written. If no line exists for this experiment number, a new line will be written.</li>
<li> If there is an existing file, the program looks for a line with the experiment number. If it finds one, the accumulated time is incremented for the appropriate experiment.  All other lines are copied and an updated file is written. If no line exists for this experiment number, a new line will be written.</li>
<li> If '''test mode''' is enabled (see [[#Input Parameters]]) an entry to the shift file written in test mode will be followed by an asterisk (see example).</li>
<li> If '''test mode''' is enabled (see [[#Input Parameters]]) an entry to the shift file written in test mode will be followed by an asterisk (see [[#Shift files]]) -- unless parameter ''skip file'' is true</li>
</ul>
</ul>


The script  {{File|name=cycle_monitor_logfiles.pl}} cycles the logfiles to save disk space. After 5 days, the logfile information is deleted.
=== Debug files ===
;Note : the shift files are never deleted unless by the user.
The current log file is {{Filepath|path=/isdaq/data1/bnmr/mon/monitor.log}}
 
 
== Log files ==
The current log file is {{Filepath|path=/isdaq/data1/bnmr/mon/<year>/monitor.log}}
 
When  {{File|name=running monitor.pl}} as a cron job,  the output of the program can only be found in the log file, since printing to the screen must be suppressed (to prevent excessive email).


== Cycling the log files ==
When  the program is running as a cron job, the output of the program can only be found in the log file, since printing informational messages to the screen must be suppressed (any messages printed are sent as email (see MAILTO in crontab)).   
A second cron job  {{File|name=cycle_monitor_logfiles.pl}} cycles the log files, so that a new  {{File|name=monitor.log}} file is started every 24 hours. Five days worth of logs are retained in files  {{File|name=monitor.log_1}} to  {{File|name=monitor.log_5}} where  {{File|name=monitor.log_5}} is the oldest. Each day the cron job deletes  {{File|name=monitor.log_5}}, renames  {{File|name=monitor.log_n}} to {{File|name=monitor.log_n+1}} and renames {{File|name=monitor.log}} to  {{File|name=monitor.log_1}}. This is done to limit the disk space taken up by the log files.


{{File|name=cycle_monitor_logfiles.pl}} takes one parameter, which when set to 1  suppresses printing to the screen.  Output from  {{File|name=cycle_monitor_logfiles.pl}}  can be found in  {{File|name=cycle_files.log}}. A version of this file is created each time the script runs.
Note : the shift files are never rotated or deleted unless by the user.


== Shift files ==
=== Shift files ===
Shift files are located in the directory  {{Filepath|path=/isdaq/data1/bnmr/mon/<year>/}}  and filenames are of the form
Shift files are located in the directory  {{Filepath|path=/isdaq/data1/bnmr/mon/<year>/}}  and filenames are of the form
{{File|name=24Jul2014_AM.txt, 24Jul2014_PM.txt}}.  The AM shift starts at 8.30am, the PM shift at 8:30pm.
{{File|name=24Jul2014_AM.txt, 24Jul2014_PM.txt}}.  The AM shift starts at 8.30am, the PM shift at 8:30pm.


The format of the shift files is e.g.
The format of the shift files is shown in the following examples:


   
==== Example ====
  # Shift Monitor File first opened at Thu Jul 24 13:52:21 2014
This example shows one experimenter group (expt number 1604) has run on  {{bnmr}} and two (1539,1419) on {{bnqr}} during an 8-hour shift.
# Threshold(uA)  ExptNum        BNMR(min)       BNQR(min)   Time line written        Testing
<pre>
   10.000        00001508        0080            0036        Thu Jul 24 15:50:01 2014   '''*'''
# Shift Monitor File first opened at Sun Jun 12 20:30:01 2016
   10.000        00001412        0035            0021        Thu Jul 24 15:49:02 2014   '''*'''
# Threshold(uA)  ExptNum        BNMR(min)   BNQR(min) Time line written       Testing
  35.000        00001604      0643         0000      Mon Jun 13 08:28:01 2016   
   35.000        00001539      0000        0536      Mon Jun 13 06:32:01 2016    
   35.000        00001419      0000        0117      Mon Jun 13 08:29:01 2016    
</pre>


The '''*''' under "Testing"  indicates '''test mode''' (see [[#How it works]]).
=== Arguments ===
<pre>
usage: beamtime_monitor.py [-h] --min-current MIN_CURRENT [--dry-run]
                          [--skip-bnmr] [--skip-bnqr]
                          [--skip-expt-name-check] [--verbose]
                          [--verbose-to-logfile]


optional arguments:
  -h, --help            show this help message and exit
  --min-current MIN_CURRENT
                        Minimum beam current to count as being active
  --dry-run            Don't write to log file, just print to screen
  --skip-bnmr          Don't calculate BNMR beamtime
  --skip-bnqr          Don't calculate BNQR beamtime
  --skip-expt-name-check
                        Don't check that we're connecting to a midas expt
                        called 'bnmr'
  --verbose            Print more output to screen
  --verbose-to-logfile  Record more output to monitor.log
</pre>


== Input Parameters ==
== beamtime_to_excel.py ==
{|  style="text-align: left; width: 100%; background-color: rgb(255, 255, 255);" border="3" cellpadding="2" cellspacing="2"
|+ Table 1 :  Input Parameters to <span style="color:#b3b3ff; font-style:italic;">monitor.pl</span>
|- style="vertical-align: top; background-color: silver; "
! colspan=2  |Input Parameter!! Explanation
|-
|1|| Proton Current Threshold (uA)|| User selected value. If proton current is less than this value, program will exit without updating shift file.
|-  style="vertical-align: top; background-color: whitesmoke; "
|2|| Suppress printing || Must be TRUE if running as a cron job
|-
|3||Test Mode ||Set TRUE for testing if EPICS switches are set to "off"
|-
|4||BNMR enabled||In Test Mode, set TRUE to enable BNMR regardless of EPICS switch
|-
|5||BNQR enabled||In Test Mode, set TRUE to enable BNQR regardless of EPICS switch
|}
 
== Running the program by hand ==
The perlscript  {{File|name=monitor.pl}} can be run by hand to check its operation. However, each time it is run, a minute will be added to the current experiment(s) in the shift files.
;Therefore, it should not be run by hand during the beam period if the cron job is running.
 
To run the program, as user ''bnmr'', in an xterm type  e.g.
/home/bnmr/vmic_online/perl/monitor.pl  15 
Printing to the screen ( [[#Input Parameters|input parameter]] 2)  need not be suppressed when running by hand.
 
The program can also be run in '''test mode''', e.g
/home/bnmr/vmic_online/perl/monitor.pl  0 0 1 0 1 
This would enable the {{bnqr}} experiment regardless of the state of the proton current and the EPICS switches (see [[#Input Parameters]]).
 
The program {{File|name=cycle_monitor_logfiles.pl}} can also be run by hand at any time. Printing messages to the screen will not be suppressed if run as follows:
/home/bnmr/vmic_online/perl/cycle_monitor_logfiles.pl
 
== Running the cron job ==
As user ''bnmr'', in an xterm type
$ crontab -l
to '''list''' the crontab file, or to '''edit''' it
$ crontab -e
 
The crontab file will be displayed as follows:
 
# MAILTO=GM <gmorris@triumf.ca>
SHELL=/bin/csh
# cron parameters :
# minute hour dayofmonth month dayofweek command
#
# cycle_monitor_logfiles.pl : cycle the logfiles monitor.log
#
#: output from this script in cycle_files.log
# run like this as cron job (argument=1 suppresses printing to screen)
30 8,20 * * * /home/bnmr/vmic_online/perl/cycle_monitor_logfiles.pl 1
#
#
# monitor.pl parameters: proton_current(uA) noprint testing bnmr_running bnqr_running
#
# run like this for TESTING cron job when epics switches are not set correctly and proton I is zero:
#
#use the odb to change the experiment numbers under "/experiment/edit on start/"
#* * * * * /home/bnmr/vmic_online/perl/monitor.pl 0 1 1 1 1
#
# run like this normally (change "10" to required proton current threshold) :
# Uncomment to turn on logging
# this editor is emacs: use C-x C-c y to save changes and exit
# typical BL2A current is about 40 \mu A; set a threshold somewhat less.
#
* * * * * /home/bnmr/vmic_online/perl/monitor.pl 35 1
 
 
The example above shows
<ul>
<li>the script {{File|name=cycle_monitor_logfiles.pl}} run twice per day (cron parameters are minute=30 hour=8,20 i.e. 8.30am and pm)
<li>the shift program monitor.pl being run as a cron job every minute (cron parameters all = *)
with parameters
<ul>
<li>        minimum proton current  10
<li>        suppress printing  TRUE
</ul>
</ul>


Printing must be suppressed when running as a cron job, otherwise the MAILTO recipient will get long email messages every minute.
This script is responsible for reading the shift files generated by <code>beamtime_monitor.py</code> summarizing them in an Excel spreadsheet. The format of the spreadsheet matches one that was manually updated by Gerald in the past.
If the last line is commented out, the cron job will not be running the monitor program (see stopping the cron job).


=== Arguments ===


== Stopping the cron job ==
<pre>
As user ''bnmr'', in an xterm type
usage: Summarize beamtime monitor files into a single excel spreadsheet
$ crontab -e
      [-h] [--source-dir SOURCE_DIR] [--output-file OUTPUT_FILE]
which will display the crontab file to be edited (see above).
      [--schedule-info SCHEDULE_INFO] [--isotope-info ISOTOPE_INFO]
Comment out the two lines that starts the perlscripts, i.e.
      [--fake-data] [--start-date START_DATE] [--end-date END_DATE] [--quiet]
    # ...........
    #30 20 * * * /home/bnmr/vmic_online/perl/cycle_monitor_logfiles.pl 1
    # ...........
    # * * * * * /home/bnmr/vmic_online/perl/monitor.pl 10 1
and exit from the editor.


optional arguments:
  -h, --help            show this help message and exit
  --source-dir SOURCE_DIR
                        Defaults to /data1/bnmr/mon/<current_year>
  --output-file OUTPUT_FILE
                        Defaults to <source_dir>/beamtime.xlsx
  --schedule-info SCHEDULE_INFO
                        Text to describe the date range / schedule. Defaults
                        to date range shown.
  --isotope-info ISOTOPE_INFO
                        Text to describe the isotope(s) used. Defaults to
                        empty string.
  --fake-data          Skip reading real beamtime files, and use fake data
                        for testing.
  --start-date START_DATE
                        Format dd/mm/yyyy. Limit to only showing shifts
                        on/after this date.
  --end-date END_DATE  Format dd/mm/yyyy. Limit to only showing shifts
                        on/before this date.
  --quiet              Supress stdout output (e.g. if running in cron)
</pre>
[[Category:BNMR]]
[[Category:BNMR]]

Latest revision as of 14:13, 28 April 2022

Introduction

The BNMR shift monitor system consists of the python program bnxr_common/beamtime_monitor.py, which is run as a cron job during the beam period. It run as user bnmr, and accesses the required information from both the bnmr and bnqr ODBs.

The shift monitor keeps a running total of how much usable beam time (in minutes) each TRIUMF experimental group has had access to, while running as experiment bnmr or bnqr (or both). It reads the proton current from EPICS once per minute. The information is stored as text files in the directory /isdaq/data1/bnmr/mon/<year>/, alongside an Excel spreadsheet that summarises each campaign. The text files are updated every minute, and the Excel spreadsheet every 8 hours.

beamtime_monitor.py

This script is responsible for reading the state of the beamlines and DAQ systems, and recording summaries in text files.

How it works

The script determines which TRIUMF experimental group is running by reading the experiment number from the ODB parameter /Experiment/Edit on start/experiment number on both experiments. Access to both ODBs uses Midas' python tools.

The program reads the proton current from EPICS (via caget "CCS2ISAC:BL2ACURRENT").

  • If it is below the threshold value (supplied as the first input parameter to monitor.pl), it exits.
  • Otherwise it reads from the EPICS switches which experiment(s) is/are enabled:
  • It reads the experiment number from the enabled experiment(s). The experiment number must be valid (0 < expt_num < 9999), otherwise no beam time will be allocated and an error will be reported
  • The program determines the name of the shift file by date and by 12-hour shift (AM/PM).
  • If no file of that filename exists, it is created and a line written for each different experiment number, and each running experiment assigned 1 minute of running time.
  • If bnmr and bnqr are both running with the same experiment number, only one line will be created with bnmr and bnqr experiments each given 1 minute accumulated time.
  • If there is an existing file, the program looks for a line with the experiment number. If it finds one, the accumulated time is incremented for the appropriate experiment. All other lines are copied and an updated file is written. If no line exists for this experiment number, a new line will be written.
  • If test mode is enabled (see #Input Parameters) an entry to the shift file written in test mode will be followed by an asterisk (see #Shift files) -- unless parameter skip file is true

Debug files

The current log file is /isdaq/data1/bnmr/mon/monitor.log

When the program is running as a cron job, the output of the program can only be found in the log file, since printing informational messages to the screen must be suppressed (any messages printed are sent as email (see MAILTO in crontab)).

Note : the shift files are never rotated or deleted unless by the user.

Shift files

Shift files are located in the directory /isdaq/data1/bnmr/mon/<year>/ and filenames are of the form

24Jul2014_AM.txt, 24Jul2014_PM.txt. The AM shift starts at 8.30am, the PM shift at 8:30pm.

The format of the shift files is shown in the following examples:

Example

This example shows one experimenter group (expt number 1604) has run on bnmr and two (1539,1419) on bnqr during an 8-hour shift. 

# Shift Monitor File first opened at Sun Jun 12 20:30:01 2016
# Threshold(uA)   ExptNum        BNMR(min)    BNQR(min)  Time line written        Testing
   35.000         00001604       0643         0000       Mon Jun 13 08:28:01 2016    
   35.000         00001539       0000         0536       Mon Jun 13 06:32:01 2016    
   35.000         00001419       0000         0117       Mon Jun 13 08:29:01 2016

Arguments

usage: beamtime_monitor.py [-h] --min-current MIN_CURRENT [--dry-run]
                           [--skip-bnmr] [--skip-bnqr]
                           [--skip-expt-name-check] [--verbose]
                           [--verbose-to-logfile]

optional arguments:
  -h, --help            show this help message and exit
  --min-current MIN_CURRENT
                        Minimum beam current to count as being active
  --dry-run             Don't write to log file, just print to screen
  --skip-bnmr           Don't calculate BNMR beamtime
  --skip-bnqr           Don't calculate BNQR beamtime
  --skip-expt-name-check
                        Don't check that we're connecting to a midas expt
                        called 'bnmr'
  --verbose             Print more output to screen
  --verbose-to-logfile  Record more output to monitor.log

beamtime_to_excel.py

This script is responsible for reading the shift files generated by beamtime_monitor.py summarizing them in an Excel spreadsheet. The format of the spreadsheet matches one that was manually updated by Gerald in the past.

Arguments

usage: Summarize beamtime monitor files into a single excel spreadsheet
       [-h] [--source-dir SOURCE_DIR] [--output-file OUTPUT_FILE]
       [--schedule-info SCHEDULE_INFO] [--isotope-info ISOTOPE_INFO]
       [--fake-data] [--start-date START_DATE] [--end-date END_DATE] [--quiet]

optional arguments:
  -h, --help            show this help message and exit
  --source-dir SOURCE_DIR
                        Defaults to /data1/bnmr/mon/<current_year>
  --output-file OUTPUT_FILE
                        Defaults to <source_dir>/beamtime.xlsx
  --schedule-info SCHEDULE_INFO
                        Text to describe the date range / schedule. Defaults
                        to date range shown.
  --isotope-info ISOTOPE_INFO
                        Text to describe the isotope(s) used. Defaults to
                        empty string.
  --fake-data           Skip reading real beamtime files, and use fake data
                        for testing.
  --start-date START_DATE
                        Format dd/mm/yyyy. Limit to only showing shifts
                        on/after this date.
  --end-date END_DATE   Format dd/mm/yyyy. Limit to only showing shifts
                        on/before this date.
  --quiet               Supress stdout output (e.g. if running in cron)
Retrieved from "https://daq00.triumf.ca/DaqWiki/index.php?title=BNMR:_Shift_Monitor&oldid=6297"