Changeset 1042


Ignore:
Timestamp:
Jul 16, 2012 6:27:09 PM (11 years ago)
Author:
jemian
Message:

new version from Christian

File:
1 edited

Legend:

Unmodified
Added
Removed

  • specdomain/trunk/src/specdomain/comparison/auto.mac

    r1019 r1042  
    1717for each exposure:
    1818
    19 - Post-exposure adjustments: Each new exposures is taken with settings that
     19- Post-exposure adjustments: Each new exposure is taken with settings that
    2020  are based on the feedback obtained from the previous one. This mode is
    2121  based on the assumption that the measured intensity profiles are only
    … …  
    5959exposure times may be adjusted. See the next sections below for details.
    6060
    61 Filter tramsmission adjustments (RATE)
     61Filter transmission adjustments (RATE)
    6262----------------------------------------
    6363The filter adjustment assures a high incident photon rate within a band
    64 just below the rate limit of the detector. The width of the band is
    65 defined by the step size in transmission, defined in AUTO_FILTER_FACTOR,
     64just below the rate limit of the detector. The width of the band is defined
     65by the step size in transmission, defined in AUTO_FILTER_FACTOR,
    6666which is used for each correction. If the count rate is higher than
    6767AUTO_RATE_LIMIT, the transmission is immediately reduced by
    … …  
    163163================
    164164
    165 Authors
    166 -------
    167 * C.M. Schlepuetz (CS, cschlep),
    168   Argonne National Laboratory, cschlep@aps.anl.gov
    169 * Y. Yang (YY, ysyang),
    170   University of Michigan, ysyang@umich.edu
    171 
    172 Creation date
    173 -------------
    174 2011/02/25
    175 
    176 Copyright
    177 ---------
    178 Copyright 2010 by the above authors (see AUTHOR/AUTHORS)
    179 
    180 This program is free software: you can redistribute it and/or modify
    181 it under the terms of the GNU General Public License as published by
    182 the Free Software Foundation, either version 3 of the License, or
    183 (at your option) any later version.
    184 
    185 This program is distributed in the hope that it will be useful,
    186 but WITHOUT ANY WARRANTY; without even the implied warranty of
    187 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    188 GNU General Public License for more details.
    189 
    190 You should have received a copy of the GNU General Public License
    191 along with this program.  If not, see http://www.gnu.org/licenses/.
    192 
    193 Version
    194 -------
    195 ::
     165AUTHORS:
     166
     167  * C.M. Schlepuetz (CS, cschlep),
     168    Argonne National Laboratory, cschlep@aps.anl.gov
     169  * Y. Yang (YY, ysyang),
     170    University of Michigan, ysyang@umich.edu
     171
     172CREATION DATE:
     173
     174  2011/02/25
     175
     176COPYRIGHT:
     177
     178  Copyright 2010-2012 by the above authors (see AUTHOR/AUTHORS)
     179
     180  This program is free software: you can redistribute it and/or modify
     181  it under the terms of the GNU General Public License as published by
     182  the Free Software Foundation, either version 3 of the License, or
     183  (at your option) any later version.
     184
     185  This program is distributed in the hope that it will be useful,
     186  but WITHOUT ANY WARRANTY; without even the implied warranty of
     187  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     188  GNU General Public License for more details.
     189
     190  You should have received a copy of the GNU General Public License
     191  along with this program.  If not, see http://www.gnu.org/licenses/.
     192
     193VERSION::
    196194
    197195  $Date: 2011-04-11 13:17:13 -0400 (Mon, 11 Apr 2011) $
    … …  
    201199
    202200
    203 Change log
    204 ----------
    205 2011/02/25 (CS, YY):
    206 
    207 - completely reworked previous versions of ``auto.mac`` to produce this new
    208   version:
    209 
    210   * improved efficiency
    211   * simplified code
    212   * new method of scaling the count times (see description above)
    213 
    214 2011/04/04 (CS):
    215 
    216 - cleaned up code further
    217 - added and updated documentation
    218 - added ``auto_setup`` macro
    219 - added AUTO_AREADETECTOR_VERSION global to track which version of
    220   areaDetector is used in ``auto_init_analysis``.
    221 - added ``auto_on`` and ``auto_off``
    222 - changed all macro names to lower case and underscore naming convention
    223 - changed all calls to macros from ``filter.mac`` to lower case and underscore
    224   naming conventions.
    225 
    226 2011/04/11 (CS):
    227 
    228 - changed ``auto_prescan_header``: if AUTO_LEVEL > 1, set the exposure times to
    229   the minimum exposure time to start with.
    230 
    231 2012/03/29 (CS):
    232 
    233 - modified code documentation to be compatible with the ROBODoc
    234   documentation generation software.
    235 - monitor a configurable SPEC counter rather than an EPICS channel for the
    236   adjustments. This allows for the monitoring of any arbitrary counter in
    237   SPEC, but requires that whatever signal is to be monitored is captured in
    238   a SPEC counter during the count process.
    239 - reworked the setup routines for easier use.
    240 - removed unnecessary ``auto_init_analysis``
    241 - removed unnecessary AUTO_AREADETECTOR_VERSION global variable
    242 - renamed many variables for improved consistency
    243 
    244 2012/04/23 (CS):
    245 
    246 - fixed a bug where long exposures with valid rate but saturating the
    247   counter would result in an infinite loop.
    248 
    249 2012/07/06 (CS):
    250 
    251 - changed code documentation to be compatible with the new SPEC domain for the
    252   SPHINX code documentation suite.
    253 
    254 2012/07/13 (CS):
    255 
    256 - renamed some private macros to start with underscores::
    257 
    258     auto_precount        --> _auto_precount
    259     auto_prescan_head    --> _auto_prescan_head
    260     auto_user_chk_counts --> _auto_user_chk_counts
    261 
    262 - moved the macro definitions for the above macros out of the
    263   :spec:def:`auto_set_level` macro to avoid unnecessary nested definitions.
    264 
    265 
    266 TO DO
    267 -----
    268 
    269 - Extensive testing of the pilot exposure mode
    270 - complete documentation
    271 - insert hyperlinks into documentation
     201CHANGE LOG:
     202
     203  2011/02/25 (CS, YY):
     204
     205  - completely reworked previous versions of ``auto.mac`` to produce this new
     206    version:
     207
     208    * improved efficiency
     209    * simplified code
     210    * new method of scaling the count times (see description above)
     211
     212  2011/04/04 (CS):
     213
     214  - cleaned up code further.
     215  - added and updated documentation.
     216  - added ``auto_setup`` macro.
     217  - added AUTO_AREADETECTOR_VERSION global to track which version of
     218    areaDetector is used in ``auto_init_analysis``.
     219  - added ``auto_on`` and ``auto_off``.
     220  - changed all macro names to lower case and underscore naming convention.
     221  - changed all calls to macros from ``filter.mac`` to lower case and
     222    underscore naming conventions.
     223
     224  2011/04/11 (CS):
     225
     226  - changed ``auto_prescan_header``: if AUTO_LEVEL > 1, set the exposure times
     227    to the minimum exposure time to start with.
     228
     229  2012/03/29 (CS):
     230
     231  - modified code documentation to be compatible with the ROBODoc
     232    documentation generation software.
     233  - monitor a configurable SPEC counter rather than an EPICS channel for the
     234    adjustments. This allows for the monitoring of any arbitrary counter in
     235    SPEC, but requires that whatever signal is to be monitored is captured in
     236    a SPEC counter during the count process.
     237  - reworked the setup routines for easier use.
     238  - removed unnecessary ``auto_init_analysis``.
     239  - removed unnecessary AUTO_AREADETECTOR_VERSION global variable.
     240  - renamed many variables for improved consistency.
     241
     242  2012/04/23 (CS):
     243
     244  - fixed a bug where long exposures with valid rate but saturating the
     245    counter would result in an infinite loop.
     246
     247  2012/07/06 (CS):
     248
     249  - changed code documentation to be compatible with the new SPEC domain for
     250    the SPHINX code documentation suite.
     251
     252  2012/07/13 (CS):
     253
     254  - moved the macro definitions for the above macros out of the
     255    :spec:def:`auto_set_level` macro to avoid unnecessary nested definitions.
     256  - Changed default value of ``AUTO_RETRY_MAX`` to 10 instead of 20.
     257  - Changed default value of ``AUTO_COUNTER`` to ``DET`` instead of ``det``.
     258  - renamed some private macros to start with underscores::
     259
     260      auto_precount        --> _auto_precount
     261      auto_prescan_head    --> _auto_prescan_head
     262      auto_user_chk_counts --> _auto_user_chk_counts
     263
     264TO DO:
     265
     266  - Extensive testing of the pilot exposure mode
     267  - complete documentation
     268  - insert hyperlinks into documentation
    272269
    273270"""
    … …  
    299296  # set default values for global variables
    300297  AUTO_MAC = DOFILE
    301   AUTO_COUNTER = det
     298  AUTO_COUNTER = DET
    302299  AUTO_LEVEL = 0
    303300  AUTO_MODE = 0
    304   AUTO_RETRY_MAX = 20
     301  AUTO_RETRY_MAX = 10
    305302  AUTO_COUNT_HIGH = 5e5
    306303  AUTO_RATE_LIMIT =2e5
    … …  
    309306  AUTO_COUNT_LOW = 0.5 * AUTO_COUNT_TARGET
    310307  AUTO_PILOT_EXPTIME = 0.05
    311   AUTO_EXP_LOW = 1
    312   AUTO_EXP_HIGH = 10
    313   AUTO_FILTER_FACTOR = 5
     308  AUTO_EXP_LOW = 1.0
     309  AUTO_EXP_HIGH = 10.0
     310  AUTO_FILTER_FACTOR = 5.0
    314311  AUTO_COUNT_PREC = 0.01
    315312  AUTO_FILTER_LOCK = 0
    … …  
    330327  Displays the auto help text.
    331328
    332   Usage::
     329  USAGE::
    333330
    334331     > auto_help
    335332
    336   .. note:: The help text is generated by simply displaying the text file
    337      ``auto_mac.txt``, which should reside in the same directory as
    338      ``auto.mac``. If the file does not exist, a generic help text defined in
    339      ``auto_help`` is shown.
     333  NOTE:
     334    The help text is generated by simply displaying the text file
     335    ``auto_mac.txt``, which should reside in the same directory as
     336    ``auto.mac``. If the file does not exist, a generic help text defined in
     337    ``auto_help`` is shown.
    340338  """
    341339
    … …  
    372370  adjustments.
    373371
    374   Description:
    375 
     372  DESCRIPTION:
    376373    The following parameters can be adjusted to fit the particular needs of an
    377374    experiment or detector type (global variables holding these parameters and
    378375    default values are given in brackets):
    379376
    380     * Auto level: the level of automatic adjustments to be performed. Three
     377    :Auto level: The level of automatic adjustments to be performed. Three
    381378      levels are currently available [AUTO_LEVEL = 0]:
    382379
    383         ===== =================================================================
    384         Level Description
    385         ===== =================================================================
    386         0     No automatic adjustments are made
    387         1     Only filters are adjusted, no exposure time adjustments
    388         2     Both filters and exposure times are automatically adjusted
    389         ===== =================================================================
    390 
    391     * Auto mode: the mode used to calculate/apply the adjustments. Two modes
     380        =====  ================================================================
     381        Level  Description
     382        =====  ================================================================
     383        ``0``  No automatic adjustments are made
     384        ``1``  Only filters are adjusted, no exposure time adjustments
     385        ``2``  Both filters and exposure times are automatically adjusted
     386        =====  ================================================================
     387
     388    :Auto mode: The mode used to calculate/apply the adjustments. Two modes
    392389      are available [AUTO_MODE = 0]:
    393390
    394         ==== ==================================================================
    395         Mode Description
    396         ==== ==================================================================
    397         0    Post-exposure analysis: exposures are taken at normal settings and
    398              analyzed in retrospect. The exposure is only retaken if it is
    399              deemed unacceptable. Otherwise, the calculated adjustments are
    400              applied only to the next exposure. This mode is faster, but
    401              riskier in terms of over-exposing the detector for potentially
    402              much longer times.
    403         1    Pilot exposure mode: A short pilot exposure is taken before each
    404              exposure to determine the correct filter and exposure time
    405              settings. This is safer in terms of identifying over-exposures
    406              quickly and provides optimized settings for each exposure, but
    407              comes at a considerable cost in additional dead time. The pilot
    408              exposure time is specified in AUTO_PILOT_EXPTIME.
    409         ==== ==================================================================
    410 
    411     * Counter to monitor: the SPEC counter mnemonic or number of the counter
     391        =====  ================================================================
     392        Mode   Description
     393        =====  ================================================================
     394        ``0``  Post-exposure analysis: exposures are taken at normal settings
     395               and analyzed in retrospect. The exposure is only retaken if it
     396               is deemed unacceptable. Otherwise, the calculated adjustments
     397               are applied only to the next exposure. This mode is faster, but
     398               riskier in terms of over-exposing the detector for potentially
     399               much longer times.
     400        ``1``  Pilot exposure mode: A short pilot exposure is taken before each
     401               exposure to determine the correct filter and exposure time
     402               settings. This is safer in terms of identifying over-exposures
     403               quickly and provides optimized settings for each exposure, but
     404               comes at a considerable cost in additional dead time. The pilot
     405               exposure time is specified in AUTO_PILOT_EXPTIME.
     406        =====  ================================================================
     407
     408    :Counter to monitor: The SPEC counter mnemonic or number of the counter
    412409      used to assess the validity of the exposure. Note that when using area
    413410      detectors, it is necessary to monitor the count levels per pixel, as this
    414411      the saturation conditions. In this case, there needs to be a counter
    415412      configured that is monitoring the maximum count rate of all pixels within
    416       the relevant region of interest. [AUTO_COUNTER = det]
    417 
    418     * Count RATE high limit: the maximum count rate (counts per second) on
     413      the relevant region of interest. [AUTO_COUNTER = DET]
     414
     415    :Count RATE high limit: The maximum count rate (counts per second) on
    419416      the detector that is acceptable for the experiment. If the measured count
    420417      rate is higher than this limit, filters will be inserted to lower the
    421418      rate. [AUTO_RATE_LIMIT = 2.0e5]
    422419
    423     * Target count level: the desired count level for a "perfect" exposure.
     420    :Target count level: The desired count level for a "perfect" exposure.
    424421      All adjustments applied to filter and/or count times aim to achieve this
    425422      level. [AUTO_COUNT_TARGET = 1.0e4]
    426423
    427     * Count level low limit: The lower count limit for an acceptable exposure.
     424    :Count level low limit: The lower count limit for an acceptable exposure.
    428425      If the measured level is below this, filters and exposure times will be
    429426      adjusted (if possible) and the exposure retaken.
    430427      [AUTO_COUNT_LOW = 5000]
    431428
    432     * Counter saturation limit: The upper count limit for an acceptable
     429    :Counter saturation limit: The upper count limit for an acceptable
    433430      exposure. This should be chosen below the actual saturation level of the
    434431      detector. If the measured level exceeds the saturation limit, filters and
    … …  
    437434      [AUTO_COUNT_HIGH = 5.0e5]
    438435
    439     * Transmission step: The step in filter transmission to be taken when
     436    :Transmission step: The step in filter transmission to be taken when
    440437      adjusting the filters. The specified step must be larger than the
    441438      largest available incremet in transmission values of the experimental
    … …  
    444441      depending on the available filters. [AUTO_FILTER_FACTOR = 5]
    445442
    446     * Minimum exposure time: Minimum allowable exposure time to be used whith
     443    :Minimum exposure time: Minimum allowable exposure time to be used whith
    447444      automatic exposure time adjustments. [AUTO_EXP_LOW = 1]
    448445
    449     * Maximum exposure time: Maximum allowable exposure time to be used whith
     446    :Maximum exposure time: Maximum allowable exposure time to be used whith
    450447      automatic exposure time adjustments. [AUTO_EXP_HIGH = 10]
    451448
    452     * Pilot exposure time: Exposure time for the pilot exposure used in pilot
     449    :Pilot exposure time: Exposure time for the pilot exposure used in pilot
    453450      mode. [AUTO_PILOT_EXPTIME = 0.05]
    454451
    455     * Count time precision: Automatically calculated count times will be
     452    :Count time precision: Automatically calculated count times will be
    456453      rounded to this precision. Typically, a value of 0.01 or 0.001 seconds is
    457454      recommended. [AUTO_COUNT_PREC = 0.01]
    458455
    459     * Maximum number of retries: The maximum number of retries to adjust
     456    :Maximum number of retries: The maximum number of retries to adjust
    460457      exposure and filter settings before giving up. This avoids infinite loops
    461       due to inconsistent choices of control parameters. [AUTO_RETRY_MAX = 20]
    462 
    463   Usage::
     458      due to inconsistent choices of control parameters. [AUTO_RETRY_MAX = 10]
     459
     460  USAGE::
    464461
    465462    > auto_setup
    … …  
    514511
    515512  SEE ALSO:
    516      :spec:def:`auto_set_level`,
    517      :spec:def:`auto_on`
     513    :spec:def:`auto_set_level`,
     514    :spec:def:`auto_on`
    518515
    519516  """
    … …  
    547544    > auto_on [<level>]
    548545
    549   If now arguement is given, the user is prompted for input. The argument
    550   ``<level>`` can be one of the following:
    551 
    552       =====  =================================================================
    553       Level  Description
    554       =====  =================================================================
    555       ``0``  No automatic adjustments are made
    556       ``1``  Only filters are adjusted, no exposure time adjustments
    557       ``2``  Both filters and exposure times are automatically adjusted
    558       =====  =================================================================
     546  ARGUMENTS:
     547    If no input argument is given, the user is prompted for input.
     548    The optional input argument ``level`` can be one of the following:
     549
     550      =========  ==========================================================
     551      ``level``  Description
     552      =========  ==========================================================
     553      ``0``      No automatic adjustments are made
     554      ``1``      Only filters are adjusted, no exposure time adjustments
     555      ``2``      Both filters and exposure times are automatically adjusted
     556      =========  ==========================================================
    559557
    560558  EXAMPLES::
    561559
    562560    > auto_set_level
    563         then answer the questions in the dialogue
     561        # then answer the questions in the dialogue
    564562
    565563    > auto_on 1
    566         turns on automatic filter adjustments (level 1)
     564        # turns on automatic filter adjustments (level 1)
    567565
    568566  NOTE:
    569      :spec:def:`auto_set_level` and :spec:def:`auto_on` are equivalent to
    570      each other.
     567    :spec:def:`auto_set_level` and :spec:def:`auto_on` are equivalent to
     568    each other.
    571569
    572570  SEE ALSO:
    573      :spec:def:`auto_off`
     571    :spec:def:`auto_off`
     572    :spec:def:`auto_setup`
    574573
    575574  """
    … …  
    662661  exposure time adjustments.
    663662
    664   DESCRIPTION:
    665     Need some more details here...
    666 
    667663  USAGE::
    668664
    669665    > auto_set_mode [<mode>]
    670         where <mode> must be one of the following:
    671           0 - post-exposure analysis
    672           1 - pilot exposure mode
    673         when called with no arguments, the user is prompted
     666
     667  ARGUMENTS:
     668    If no input argument is given, the user is prompted for input.
     669    The optional input argument ``mode`` can be one of the following:
     670
     671      ======== ================================================================
     672      ``mode`` Description
     673      ======== ================================================================
     674      ``0``    Post-exposure analysis: exposures are taken at normal settings
     675               and analyzed in retrospect. The exposure is only retaken if it
     676               is deemed unacceptable. Otherwise, the calculated adjustments
     677               are applied only to the next exposure. This mode is faster, but
     678               riskier in terms of over-exposing the detector for potentially
     679               much longer times.
     680      ``1``    Pilot exposure mode: A short pilot exposure is taken before each
     681               exposure to determine the correct filter and exposure time
     682               settings. This is safer in terms of identifying over-exposures
     683               quickly and provides optimized settings for each exposure, but
     684               comes at a considerable cost in additional dead time. The pilot
     685               exposure time is specified in AUTO_PILOT_EXPTIME.
     686      ======== ================================================================
    674687
    675688  EXAMPLE::
    676689
    677690    > auto_set_mode 1
    678         use the pilot exposure mode for automatic adjustments.
     691        # use the pilot exposure mode for automatic adjustments.
    679692
    680693  SEE ALSO:
    … …  
    718731  USAGE::
    719732
    720     > auto_set_exposure [<min> <max>]
    721         where <min> is the minimum and <max> the maximum exposure time [s]
    722         when called with no arguments, the user is prompted
     733    > auto_set_exposure [<min_exptime> <max_exptime>]
     734
     735  ARGUMENTS:
     736    The following arguments are optional:
     737
     738    :min_exptime: Shortest allowable exposure time [s]
     739    :max_exptime: Longest allowable exposure time [s]
     740
     741    When called with no arguments, the user is prompted for input.
    723742
    724743  EXAMPLE::
    725744
    726       > auto_set_exposure 1 10
    727           set the minimum exposure time to 1 sec and the maximum to 10 sec
     745    > auto_set_exposure 1 10
     746        # set the minimum exposure time to 1 sec and the maximum to 10 sec
    728747
    729748  """
    … …  
    803822
    804823    > auto_show_exposure
     824
     825  SEE ALSO:
     826    :spec:def:`auto_show`
    805827
    806828  """
    … …  
    9781000    _valid = 0
    9791001    while(!(_valid)){
    980       _input= getval("Upper limit for the counte RATE [cts/sec]", \
     1002      _input= getval("Upper limit for the count RATE [cts/sec]", \
    9811003        AUTO_RATE_LIMIT)
    9821004      _numitems = sscanf(_input, "%f", _input)
    … …  
    12031225
    12041226  DESCRIPTION:
    1205 
    1206     The function returns 1 if transmission or exposure time have been changed,
    1207     0 otherwise.
    1208 
    1209   USAGE::
    1210     > changed = _auto_adjust()
     1227    This function determines whether a filter and/or exposure time adjustment
     1228    is necessary and applies the corresponding adjustments. Note that it does
     1229    *not* repeat the exposure, this has to be done separately, usually in some
     1230    sort of for-loop, which terminates once no more adjustmens were necessary.
     1231
     1232  RETURNS:
     1233    The function returns
     1234
     1235    * 1 if an immediate re-exposure is necessary.
     1236    * 0 otherwise.
     1237
     1238  USAGE:
     1239    * check the status of the adjustment::
     1240
     1241        > retake = _auto_adjust()
     1242
     1243    * or inside a for-loop::
     1244
     1245        > while(_auto_adjust()){
     1246            --> keep taking exposures
     1247          }
    12111248
    12121249  """
    … …  
    14441481def _auto_check_levels '{
    14451482  """
    1446   Make sure the user-entered count levels are consistent
     1483  Make sure the user-entered count levels are valid.
     1484
     1485  DECRIPTION:
     1486    Checks the user-entered count levels for consistency, ensuring that:
     1487
     1488    * ``AUTO_COUNT_TARGET < AUTO_COUNT_HIGH``
     1489    * ``AUTO_COUNT_LOW < AUTO_COUNT_TARGET``
    14471490
    14481491  USAGE::
    … …  
    15081551    is repeated until the best possible filter and exposure settings have been
    15091552    obtained, or a maximum number of retry counts has been reached.
    1510     The function returns 1 in case of success, 0 otherwise.
    15111553
    15121554  USAGE::
    15131555
    15141556    > success = _auto_adjust_redo()
     1557
     1558  RETURNS:
     1559
     1560    * 1 if adjustment has been successful
     1561    * 0 otherwise (e.g.: after maximum number or unsuccessful retries)
    15151562
    15161563  NOTE:
Note: See TracChangeset for help on using the changeset viewer.