source: specdomain/trunk/src/specdomain/comparison/auto.rst0 @ 996

Last change on this file since 996 was 996, checked in by jemian, 10 years ago

for comparison against a RoboDoc? build

File size: 20.7 KB
Line 
1.. title: auto
2.. subtitle: Macros to implement automatic filter and exposure time control
3.. date: jan 31 2012
4.. version: $Revision: 25 $
5.. manual_section: macros
6.. manual_group: counting
7
8#################
9AUTO.MAC
10#################
11
12===================
13General Information
14===================
15
16Summary
17=======
18This macro provides a set of definitions which allow for automatic filter
19transmission and exposure time adjustments during experiments.
20
21Description
22===========
23After each count command, the obtained counts are evaluated and checked for
24over-/under-exposure. In case of unsatisfactory count levels, filter
25transmissions and optionally exposure times are adjusted and exposures are
26repeated until a valid exposure is obtained.
27
28Exposure optimization modes
29---------------------------
30Two different modes of operation are available to optimize the count levels
31for each exposure:
32
33- Post-exposure adjustments: Each new exposures is taken with settings that
34  are based on the feedback obtained from the previous one. This mode is
35  based on the assumption that the measured intensity profiles are only
36  gradually changing, and that a satisfactory prediction of the change in
37  the count levels can be obtained in most cases to yield a good exposure.
38  In those cases where the predictions fail and the new exposure falls
39  outside the acceptable limits, the settings are adjusted and the exposure
40  is retaken immediately.
41- Pilot exposure: Each exposure is preceeded by a short pilot exposure,
42  which is used to establish the count levels at the current positions.
43
44Both modes have their relative merits and drawbacks. Post-exposure
45adjustments are riskier in terms of overexposing a detector, since the
46feedback is obtained only after potentially very long exposures. On the
47other hand, they are more efficient in terms of dead-time, especially when
48scanning signals that change only gradually. In this case, it is very
49seldomly necessary to repeat exposures. The pilot exposure mode, in
50contrast, is safer, since it detects potentially harmfully strong signals
51much faster. This comes at the cost of significantly increased dead-times,
52particularly for detectors with longer arming or readout times.
53
54Exposure optimization scheme
55----------------------------
56The filter and exposure time adjustments principles are based on the
57following criteria to formulate an adjustment strategy.  Firstly, it is
58important to note that there are two separate effects which may cause an
59over-exposure of the detector:
60
61#. Paralizing the counter as a result of a count RATE which exceeds the
62   ability of the detector to separate individual photons in time (only for
63   single-photon-counting devices, does not apply to charge-integrating).
64#. Saturating the counter as a result of exceeding the maximum NUMBER OF
65   COUNTS that can be stored in the counter.
66
67The incident photon RATE (case 1) can only be adjusted through the use of
68filters (attenuators), while the integrated NUMBER OF COUNTS is affected
69both by the filter transmission and the integration duration (count time).
70In this implementation, ensuring a valid photon RATE always takes
71precedence over any other adjustment. Once the rate has been optimized
72(keeping it within a given band below the saturation threshold), the
73exposure times may be adjusted. See the next sections below for details.
74
75Filter tramsmission adjustments (RATE)
76----------------------------------------
77The filter adjustment assures a high incident photon rate within a band
78just below the rate limit of the detector. The width of the band is
79defined by the step size in transmission, defined in AUTO_FILTER_FACTOR,
80which is used for each correction. If the count rate is higher than
81AUTO_RATE_LIMIT, the transmission is immediately reduced by
82AUTO_FILTER_FACTOR and the exposure is retaken. If the count rate is
83lower than AUTO_RATE_LIMIT/(2*AUTO_FILTER_FACTOR), the change in
84transmission required to reach a count rate of 0.75*AUTO_RATE_LIMIT is
85calculated, the transmission increased by that factor and the exposure is
86retaken immediately. If the measured count rate falls between these limits,
87no change is applied to the filters. The following scheme illustrates
88this behavior::
89
90  Threshold levels           Actions
91  ----------------           -------
92
93                             - decrease trasmission by AUTO_FILTER_FACTOR
94                             - retake exposure immediately
95  AUTO_RATE_LIMIT---------------------------------------------------------
96   /\
97   || 2*AUTO_FILTER_FACTOR   - leave filters as they are
98   \/
99  ------------------------------------------------------------------------
100                             - calculate change in transmission required to
101                               reach 0.75*AUTO_RATE_LIMIT
102                             - increase trasmission by this factor
103                             - retake exposure immediately
104
105Exposure time adjustments (integrated NUMBER OF COUNTS)
106---------------------------------------------------------
107Exposure time adjustments are designed with maximum efficiency in mind.
108The general idea is to attempt to maintain the integrated count level as
109close as possible to the user-defined AUTO_COUNT_TARGET, but to minimize
110the number of re-exposures by accepting exposures which fall into an
111"acceptable" count range, which is defined as any count level between
112the detectors saturation count AUTO_COUNT_HIGH and a user-defined
113lower count level AUTO_COUNT_LOW. If the exposure is within this
114acceptable band, a new count time to reach the target level is
115calculated based on the current exposure, but only applied to the next
116exposure in an attempt to predict a change in the right direction. If the
117current exposure falls outside the acceptable count range, the expsoure
118time is adjusted and the exposure is retaken immediately. Note that
119chosing a small acceptable range will thus result in retaking many
120exposures, hence increasing scan times.
121Count times will be adjusted between user-defined limits AUTO_EXP_LOW and
122AUTO_EXP_HIGH and rounded to a user-defined precision AUTO_COUNT_PREC.
123
124The diagram below outlines the measures taken when the registered maximum
125NUMBER OF COUNTS falls into the various defined ranges::
126
127  Threshold levels           Actions
128  ----------------           -------
129
130                             - reduce exposure time (if > minimum time)
131                             - retake exposure immediately
132  AUTO_COUNT_HIGH---------------------------------------------------------
133                             - reduce exposure time (if > minimum time)
134                             - apply only to next exposure
135  AUTO_COUNT_TARGET-------------------------------------------------------
136                             - increase exposure time (if < maximum time)
137                             - apply only to next exposure
138  AUTO_COUNT_LOW----------------------------------------------------------
139                             - increase exposure time (if < maximum time)
140                             - retake exposure immediately
141
142
143Configuration
144=============
145
146No special configuration is needed to run these macros. Simply load the macro
147file and run ''auto_setup''::
148
149> qdo auto.mac
150> auto_setup
151
152Dependencies
153------------
154
155Dependencies on other macros:
156
157* filter.mac (used to control the attenuators):
158
159  - filter_trans
160  - filter_get_trans()
161  - filter_get_trans_up()
162  - filter_get_mask()
163  - filter_max()
164
165* recount (modified count command used to retake an exposure)
166
167Impact
168------
169The following chained macro definitions are affected by this macro:
170
171* user_prescan_head
172* user_chk_counts (provided in our modified ``count`` command)
173* user_precount
174
175File information
176================
177
178Authors
179-------
180* C.M. Schlepuetz (CS, cschlep),
181  Argonne National Laboratory, cschlep@aps.anl.gov
182* Y. Yang (YY, ysyang),
183  University of Michigan, ysyang@umich.edu
184
185Creation date
186-------------
1872011/02/25
188
189Copyright
190---------
191Copyright 2010 by the above authors (see AUTHOR/AUTHORS)
192
193This program is free software: you can redistribute it and/or modify
194it under the terms of the GNU General Public License as published by
195the Free Software Foundation, either version 3 of the License, or
196(at your option) any later version.
197
198This program is distributed in the hope that it will be useful,
199but WITHOUT ANY WARRANTY; without even the implied warranty of
200MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
201GNU General Public License for more details.
202
203You should have received a copy of the GNU General Public License
204along with this program.  If not, see http://www.gnu.org/licenses/.
205
206Version
207-------
208::
209
210  $Date: 2011-04-11 13:17:13 -0400 (Mon, 11 Apr 2011) $
211  $Author: cschlep $
212  $URL: file:///data/svn/software/spec/trunk/common/auto.mac $
213  $Revision: 25 $
214 
215 
216Change log
217----------
2182011/02/25 (CS, YY):
219
220- completely reworked previous versions of ``auto.mac`` to produce this new
221  version:
222
223  * improved efficiency
224  * simplified code
225  * new method of scaling the count times (see description above)
226
2272011/04/04 (CS):
228
229- cleaned up code further
230- added and updated documentation
231- added ``auto_setup`` macro
232- added AUTO_AREADETECTOR_VERSION global to track which version of
233  areaDetector is used in ``auto_init_analysis``.
234- added ``auto_on`` and ``auto_off``
235- changed all macro names to lower case and underscore naming convention
236- changed all calls to macros from ``filter.mac`` to lower case and underscore
237  naming conventions.
238
2392011/04/11 (CS):
240
241- changed ``auto_prescan_header``: if AUTO_LEVEL > 1, set the exposure times to
242  the minimum exposure time to start with.
243
2442012/03/29 (CS):
245
246- modified code documentation to be compatible with the ROBODoc
247  documentation generation software.
248- monitor a configurable SPEC counter rather than an EPICS channel for the
249  adjustments. This allows for the monitoring of any arbitrary counter in
250  SPEC, but requires that whatever signal is to be monitored is captured in
251  a SPEC counter during the count process.
252- reworked the setup routines for easier use.
253- removed unnecessary ``auto_init_analysis``
254- removed unnecessary AUTO_AREADETECTOR_VERSION global variable
255- renamed many variables for improved consistency
256
2572012/04/23 (CS):
258
259- fixed a bug where long exposures with valid rate but saturating the
260  counter would result in an infinite loop.
261 
2622012/07/06 (CS):
263
264- changed code documentation to be compatible with the new SPEC domain for the
265  SPHINX code documentation suite.
266 
267TO DO
268-----
269
270- Extensive testing of the pilot exposure mode
271- complete documentation
272- insert hyperlinks into documentation
273
274================
275Available Macros
276================
277
278auto_help
279===============================================================================
280Summary
281-------
282Displays the auto help text.
283
284Usage
285-----
286::
287
288   > auto_help
289
290.. note:: The help text is generated by simply displaying the text file
291   ``auto_mac.txt``, which should reside in the same directory as
292   ``auto.mac``. If the file does not exist, a generic help text defined in
293   ``auto_help`` is shown.
294
295
296auto_setup
297===============================================================================
298
299Summary
300-------
301  Set up the control parameters for the automatic filter and exposure
302  adjustments.
303
304Description
305-----------
306  The following parameters can be adjusted to fit the particular needs of an
307  experiment or detector type (global variables holding these parameters and
308  default values are given in brackets):
309 
310  * Auto level: the level of automatic adjustments to be performed. Three
311    levels are currently available [AUTO_LEVEL = 0]:
312   
313      ===== ===================================================================
314      Level Description
315      ===== ===================================================================
316      0     No automatic adjustments are made
317      1     Only filters are adjusted, no exposure time adjustments
318      2     Both filters and exposure times are automatically adjusted
319      ===== ===================================================================
320
321  * Auto mode: the mode used to calculate/apply the adjustments. Two modes
322    are available [AUTO_MODE = 0]:
323
324      ==== ===================================================================
325      Mode Description
326      ==== ===================================================================
327      0    Post-exposure analysis: exposures are taken at normal settings and
328           analyzed in retrospect. The exposure is only retaken if it is
329           deemed unacceptable. Otherwise, the calculated adjustments are
330           applied only to the next exposure. This mode is faster, but riskier
331           in terms of over-exposing the detector for potentially much longer
332           times.
333      1    Pilot exposure mode: A short pilot exposure is taken before each
334           exposure to determine the correct filter and exposure time
335           settings. This is safer in terms of identifying over-exposures
336           quickly and provides optimized settings for each exposure, but
337           comes at a considerable cost in additional dead time. The pilot
338           exposure time is specified in AUTO_PILOT_EXPTIME.
339      ==== ===================================================================
340
341  * Counter to monitor: the SPEC counter mnemonic or number of the counter
342    used to assess the validity of the exposure. Note that when using area
343    detectors, it is necessary to monitor the count levels per pixel, as this
344    the saturation conditions. In this case, there needs to be a counter
345    configured that is monitoring the maximum count rate of all pixels within
346    the relevant region of interest. [AUTO_COUNTER = det]
347
348  * Count RATE high limit: the maximum count rate (counts per second) on
349    the detector that is acceptable for the experiment. If the measured count
350    rate is higher than this limit, filters will be inserted to lower the
351    rate. [AUTO_RATE_LIMIT = 2.0e5]
352
353  * Target count level: the desired count level for a "perfect" exposure.
354    All adjustments applied to filter and/or count times aim to achieve this
355    level. [AUTO_COUNT_TARGET = 1.0e4]
356
357  * Count level low limit: The lower count limit for an acceptable exposure.
358    If the measured level is below this, filters and exposure times will be
359    adjusted (if possible) and the exposure retaken.
360    [AUTO_COUNT_LOW = 5000]
361
362  * Counter saturation limit: The upper count limit for an acceptable
363    exposure. This should be chosen below the actual saturation level of the
364    detector. If the measured level exceeds the saturation limit, filters and
365    exposure times will be adjusted (if possible) and the exposure is
366    repeated.
367    [AUTO_COUNT_HIGH = 5.0e5]
368
369  * Transmission step: The step in filter transmission to be taken when
370    adjusting the filters. The specified step must be larger than the
371    largest available incremet in transmission values of the experimental
372    setup to ensure that the adjustments can be successful. Ideally, this
373    number is chosen anywhere between 2 and 10, but may need to be higher
374    depending on the available filters. [AUTO_FILTER_FACTOR = 5]
375
376  * Minimum exposure time: Minimum allowable exposure time to be used whith
377    automatic exposure time adjustments. [AUTO_EXP_LOW = 1]
378
379  * Maximum exposure time: Maximum allowable exposure time to be used whith
380    automatic exposure time adjustments. [AUTO_EXP_HIGH = 10]
381
382  * Pilot exposure time: Exposure time for the pilot exposure used in pilot
383    mode. [AUTO_PILOT_EXPTIME = 0.05]
384
385  * Count time precision: Automatically calculated count times will be
386    rounded to this precision. Typically, a value of 0.01 or 0.001 seconds is
387    recommended. [AUTO_COUNT_PREC = 0.01]
388
389  * Maximum number of retries: The maximum number of retries to adjust
390    exposure and filter settings before giving up. This avoids infinite loops
391    due to inconsistent choices of control parameters. [AUTO_RETRY_MAX = 20]
392
393Usage
394-----
395::
396
397  > auto_setup
398      then answer the questions
399
400
401
402auto_off
403=============
404
405Summary
406-------
407Turn off any automatic filter and exposure adjustments.
408
409Usage
410-----
411::
412
413  > auto_off
414
415.. note:: This command is equivalent to ``auto_set_level 0``
416
417See also
418--------
419auto_set_level, auto_on
420
421
422
423auto_set_level, auto_on
424=========================
425
426Summary
427-------
428Set the level of automatic filter and exposure adjustments.
429
430Usage
431-----
432::
433
434  > auto_set_level [<level>]
435  > auto_on [<level>]
436      where <level> can be one of the following:
437        0 - automatic filter and exposure OFF
438        1 - automatic filter ON, automatic exposure OFF
439        2 - automatic filter and exposure ON
440      if <level> is ommitted, the users is asked for input
441
442Example
443-------
444::
445
446  > auto_set_level
447      then answer the questions in the dialogue
448
449  > auto_on 1
450      turns on automatic filter adjustments (level 1)
451
452.. note::
453   ``auto_set_level`` and ``auto_on`` are equivalent to each other
454
455See also
456--------
457auto_off
458
459
460auto_set_mode
461==================
462
463Summary
464-------
465Set the acquisition mode to be used for the automatic filter and
466exposure time adjustments.
467
468Description
469-----------
470Need some more details here...
471
472
473Usage
474-----
475::
476
477  > auto_set_mode [<mode>]
478      where <mode> must be one of the following:
479        0 - post-exposure analysis
480        1 - pilot exposure mode
481      when called with no arguments, the user is prompted
482
483Example
484-------
485::
486
487  > auto_set_mode 1
488      use the pilot exposure mode for automatic adjustments.
489
490See also
491--------
492auto, auto_setup
493
494
495auto_set_exposure
496======================
497
498Summary
499-------
500Set the maximum and minimum exposure times used for automatic exposure
501adjustments.
502
503Usage
504-----
505::
506
507  > auto_set_exposure [<min> <max>]
508      where <min> is the minimum and <max> the maximum exposure time [s]
509      when called with no arguments, the user is prompted
510
511Example
512-------
513::
514
515  > auto_set_exposure 1 10
516      sets the minimum exposure time to 1 sec and the maximum to 10 sec.
517
518auto_show
519==============
520
521Summary
522-------
523Display the current auto settings.
524
525Usage
526-----
527::
528
529  > auto_show
530
531auto_show_exposure
532=======================
533
534Summary
535-------
536Display the current auto-level exposure settings.
537
538Usage
539-----
540::
541
542  > auto_show_exposure
543
544
545================
546Internal Macros
547================
548
549_auto_print_setup
550======================
551
552Summary
553-------
554Prints the configuration options and current values to screen
555
556.. note::
557   The option numbers must be kept in sync between ``_auto_set_option`` and
558   ``_auto_print_setup``.
559
560
561_auto_set_option
562=====================
563
564Summary
565-------
566Sets a new value for a given option
567
568Description
569-----------
570Sets a new value for a given option from the options menu that was created
571with the _auto_print_setup command.
572
573.. note::
574   The option numbers must be kept in sync between ``_auto_set_option`` and
575   ``_auto_print_setup``.
576
577
578_auto_analyze_exposure
579===========================
580
581Summary
582-------
583Analyze the previous exposure
584
585Description
586-----------
587This macro retrieves the necessary information to analyze the last exposure
588and to initiate adjustments, if necessary. Usually, this step consists only
589of retrieving the count value from the monitored SPEC counter, but for more
590sophisticated experimental setups, this definition could be overwritten to
591include non-standard procedures, such as retrieving counts from EPICS PVs,
592etc.
593
594Usage
595-----
596::
597
598  > _auto_analyze_exposure
599
600
601
602_auto_adjust()
603===================
604
605Summary
606-------
607Calculate and apply necessary exposure time and filter adjustments.
608
609Description
610-----------
611The function returns 1 if transmission or exposure time are changed, 0
612otherwise.
613
614
615_auto_check_exposure
616=========================
617
618Summary
619-------
620Make sure the user-entered exposure times are consistent
621
622Usage
623-----
624::
625
626  > _auto_check_exposure
627
628
629_auto_check_levels
630=======================
631
632Summary
633-------
634Make sure the user-entered count levels are consistent
635
636Usage
637-----
638::
639
640  > _auto_check_levels
641
642
643_auto_calc_exposure
644========================
645
646Summary
647-------
648Make sure the requested exposure time is between the min and max values and
649round it to the given count time precision.
650
651Usage
652-----
653::
654
655  > adjusted_time = _auto_calc_exposure(requested_time)
656
657
658
659_auto_adjust_redo()
660========================
661
662Summary
663-------
664Determines whether the auto-adjusting has been successful.
665
666Description
667-----------
668If the current exposure does not meet the required criteria, counting
669is repeated until the best possible filter and exposure settings have been
670obtained, or a maximum number of retry counts has been reached.
671The function returns 1 in case of success, 0 otherwise.
672
673Usage
674-----
675::
676
677  > success = _auto_adjust_redo()
678
679.. note::
680   This macro makes use of the ``recount`` macro, which has to be added to SPEC
681   during the startup procedure.
682
683_clear_screen
684==================
685
686Summary
687-------
688Clears the terminal screen
689
690Description
691-----------
692Clears the screen without losing the screen history or messing up the
693scrolling capabilities (this has been a problem for certain terminals)
694by blanking out the entire height of the screen and returning the cursor to
695the top left corner.
Note: See TracBrowser for help on using the repository browser.