Changeset 1019


Ignore:
Timestamp:
Jul 15, 2012 8:55:45 AM (11 years ago)
Author:
jemian
Message:

refs #11, fold back in additional changes from author

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r1017 r1019  
    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
     64just below the rate limit of the detector. The width of the band is 
    6565defined by the step size in transmission, defined in AUTO_FILTER_FACTOR,
    6666which is used for each correction. If the count rate is higher than
    … …  
    132132
    133133No special configuration is needed to run these macros. Simply load the macro
    134 file and run ``auto_setup``::
    135 
    136 > qdo auto.mac
    137 > auto_setup
     134file and run :spec:def:`auto_setup`::
     135
     136  > qdo auto.mac
     137  > auto_setup
    138138
    139139Dependencies
    … …  
    142142Dependencies on other macros:
    143143
    144 * filter.mac (used to control the attenuators):
    145 
    146   - filter_trans
    147   - filter_get_trans()
    148   - filter_get_trans_up()
    149   - filter_get_mask()
    150   - filter_max()
    151 
    152 * recount (modified count command used to retake an exposure)
     144* ``filter.mac`` (used to control the attenuators):
     145
     146  - :spec:def:`filter_trans`
     147  - :spec:def:`filter_get_trans()`
     148  - :spec:def:`filter_get_trans_up()`
     149  - :spec:def:`filter_get_mask()`
     150  - :spec:def:`filter_max()`
     151
     152* :spec:def:`recount` (modified count command used to retake an exposure)
    153153
    154154Impact
    … …  
    156156The following chained macro definitions are affected by this macro:
    157157
    158 * user_prescan_head
    159 * user_chk_counts (provided in our modified ``count`` command)
    160 * user_precount
     158* :spec:def:`user_prescan_head`
     159* :spec:def:`user_chk_counts` (from our modified :spec:def:`count` command)
     160* :spec:def:`user_precount`
    161161
    162162File information
    … …  
    252252  SPHINX code documentation suite.
    253253
     2542012/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
    254266TO DO
    255267-----
    … …  
    258270- complete documentation
    259271- insert hyperlinks into documentation
     272
    260273"""
    261274
    262 #==============================================================================
    263 
    264 #==============================================================================
     275###############################################################################
    265276# Global variable definitions
    266 #==============================================================================
    267 
    268   # Save the name of this macro file (Used for the help function).
    269   global AUTO_MAC
    270          AUTO_MAC = DOFILE
    271 
    272   global AUTO_LEVEL                # Type of adjustments {0,1,2}
    273   global AUTO_MODE                 # Adjustment mode (pilot/post-exp){0,1}
    274   global AUTO_COUNTER              # Counter to monitor
    275   global AUTO_COUNT_RBV            # Counter read back value (measured counts)
    276   global AUTO_RETRY_MAX            # Maximum number of retries
    277   global AUTO_EXP_LOW              # low exposure time limit
    278   global AUTO_EXP_HIGH             # highexposure time limit
    279   global AUTO_PILOT_EXPTIME        # exposure time for pilot exposures
    280   global AUTO_RATE_LIMIT           # High rate limit
    281   global AUTO_COUNT_HIGH           # High count limit
    282   global AUTO_COUNT_TARGET         # Target count level
    283   global AUTO_COUNT_LOW            # Low count limit
    284   global AUTO_FILTER_FACTOR        # Filter transmission factor for adjustments
    285   global AUTO_COUNT_PREC           # Count time precision (rounding)
    286 
    287   global AUTO_FILTER_LOCK          # Lock if rate-limited
    288   global AUTO_SET_PILOT            # Set pilot exposure time in user_precount
    289   global AUTO_ORIG_EXPTIME         # save the original requested count time
    290   global AUTO_DEBUG                # debug flag
     277###############################################################################
     278
     279  global AUTO_MAC                 #: Save the name of this macro file
     280  global AUTO_LEVEL               #: Type of adjustments {0,1,2}
     281  global AUTO_MODE                #: Adjustment mode (pilot vs. post-exp) {0,1}
     282  global AUTO_COUNTER             #: Counter to monitor
     283  global AUTO_COUNT_RBV           #: Counter read back value (measured counts)
     284  global AUTO_RETRY_MAX           #: Maximum number of retries
     285  global AUTO_EXP_LOW             #: Low exposure time limit
     286  global AUTO_EXP_HIGH            #: High exposure time limit
     287  global AUTO_PILOT_EXPTIME       #: Exposure time for pilot exposures
     288  global AUTO_RATE_LIMIT          #: High rate limit
     289  global AUTO_COUNT_HIGH          #: High count limit
     290  global AUTO_COUNT_TARGET        #: Target count level
     291  global AUTO_COUNT_LOW           #: Low count limit
     292  global AUTO_FILTER_FACTOR       #: Filter transmission factor for adjustments
     293  global AUTO_COUNT_PREC          #: Count time precision (rounding)
     294  global AUTO_FILTER_LOCK         #: Lock if rate-limited
     295  global AUTO_SET_PILOT           #: Set pilot exposure time in user_precount
     296  global AUTO_ORIG_EXPTIME        #: Save the original requested count time
     297  global AUTO_DEBUG               #: Debug flag
    291298
    292299  # set default values for global variables
     300  AUTO_MAC = DOFILE
    293301  AUTO_COUNTER = det
    294302  AUTO_LEVEL = 0
    … …  
    309317  AUTO_DEBUG = 0
    310318
    311 #==============================================================================
     319
     320###############################################################################
    312321# Macro command definitions
    313 #==============================================================================
     322###############################################################################
    314323
    315324#------------------------------------------------------------------------------
    316325# allow for misspelled help commands
    317 def autohelp 'auto_help'
     326#def autohelp '{auto_help}'
    318327
    319328def auto_help '{
    … …  
    497506  Turn off any automatic filter and exposure adjustments.
    498507
    499   Usage::
     508  USAGE::
    500509
    501510    > auto_off
    502511
    503   .. note:: This command is equivalent to ``auto_set_level 0``
    504 
    505   .. seealso::
     512  NOTE:
     513    This command is equivalent to ``auto_set_level 0``
     514
     515  SEE ALSO:
    506516     :spec:def:`auto_set_level`,
    507517     :spec:def:`auto_on`
    … …  
    517527def auto_on '{
    518528  """
    519   See :spec:def:`auto_set_level`
    520   """
     529  Turn on automatic filter and exposure adjustments.
     530
     531  This macro is identical to :spec:def:`auto_set_level`. Please refer to the
     532  :spec:def:`auto_set_level` documentation for more details.
     533  """
     534
    521535auto_set_level $*
    522536
    … …  
    528542  Set the level of automatic filter and exposure adjustments.
    529543
    530   Usage::
     544  USAGE::
    531545
    532546    > auto_set_level [<level>]
    533547    > auto_on [<level>]
    534         where <level> can be one of the following:
    535           0 - automatic filter and exposure OFF
    536           1 - automatic filter ON, automatic exposure OFF
    537           2 - automatic filter and exposure ON
    538         if <level> is ommitted, the users is asked for input
    539 
    540 
    541         ===== =================================================================
    542         Level Description
    543         ===== =================================================================
    544         0     No automatic adjustments are made
    545         1     Only filters are adjusted, no exposure time adjustments
    546         2     Both filters and exposure times are automatically adjusted
    547         ===== =================================================================
    548 
    549 
    550   Examples::
     548
     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      =====  =================================================================
     559
     560  EXAMPLES::
    551561
    552562    > auto_set_level
    … …  
    556566        turns on automatic filter adjustments (level 1)
    557567
    558   .. note::
    559      ``auto_set_level`` and ``auto_on`` are equivalent to each other
    560 
    561   .. seealso::
     568  NOTE:
     569     :spec:def:`auto_set_level` and :spec:def:`auto_on` are equivalent to
     570     each other.
     571
     572  SEE ALSO:
    562573     :spec:def:`auto_off`
    563574
    … …  
    595606  }
    596607
    597   #-------------------------------------------
    598   # define necessary chained macro definitions
    599 
    600   #--------------------
    601   def auto_prescan_head \'
    602   #   =================
    603     # if automatic filter setting is active start scan with very low
    604     # filter transmission
    605     if(AUTO_LEVEL > 0){
    606       AUTO_ORIG_EXPTIME = COUNT_TIME
    607       filter_trans 1e-8
    608       if(AUTO_LEVEL > 1){
    609         # start with low exposure times
    610         COUNT_TIME = AUTO_EXP_LOW
    611         _ctime = COUNT_TIME
    612       }
    613     }
    614     # add auto_cleanup to cleanup_once
    615     cdef("cleanup_once","auto_cleanup; ", "auto_cleanup_once_key",0x20)
    616   \'
    617 
    618   #-----------------------
    619   def auto_user_chk_counts \'
    620   #   ====================
    621     if(AUTO_LEVEL > 0){
    622       # automatic filter and exposure setting (if activated)
    623       success = _auto_adjust_redo()
    624     }
    625   \'
    626 
    627   #----------------
    628   def auto_precount \'
    629   #   =============
    630     if(AUTO_LEVEL > 0){
    631       if(AUTO_MODE == 1 & AUTO_SET_PILOT == 1){
    632         # remember the original exposure time
    633         AUTO_ORIG_EXPTIME = COUNT_TIME
    634         # set the pilot exposure time
    635         COUNT_TIME = AUTO_PILOT_EXPTIME
    636         _ctime = COUNT_TIME
    637         AUTO_SET_PILOT = 0
    638       }
    639     }
    640   \'
    641 
    642   #---------------
    643   def auto_cleanup \'
    644   #   ============
    645     # drop in filters after finishing, since we do not know where we end up
    646     # (center of a peak for dscan?)
    647     AUTO_SET_PILOT = 1
    648     AUTO_FILTER_LOCK = 0
    649     if(AUTO_LEVEL > 0){
    650       filter_trans 1e-8
    651     }
    652     cdef("cleanup_once", "", "auto_cleanup_once_key", "delete")
    653   \'
    654 
    655 
    656608  #--------------------------------------------
    657609  # include necessary chained macro definitions
    … …  
    660612  if (AUTO_LEVEL > 0){
    661613
    662     # add auto_prescan_head to user_prescan_head
    663     cdef("user_prescan_head", "auto_prescan_head; ", "auto_prescan_head_key",\
    664          0x10)
    665 
    666     # add auto_user_chk_counts to user_chk_counts
    667     cdef("user_chk_counts", "auto_user_chk_counts; ", \
     614    #: add _auto_prescan_head to user_prescan_head
     615    cdef("user_prescan_head", "{_auto_prescan_head}; ", \
     616         "auto_prescan_head_key", 0x10)
     617
     618    #: add _auto_user_chk_counts to user_chk_counts
     619    cdef("user_chk_counts", "{_auto_user_chk_counts}; ", \
    668620         "auto_user_chk_counts_key")
    669621
    670     # add auto_precount to user_precount
    671     cdef("user_precount", "auto_precount; ", "auto_precount_key", 0x10)
    672 
    673     # add auto_cleanup to the end of user_scan_tail
    674     cdef("user_scan_tail","auto_cleanup; ", \
     622    #: add _auto_precount to user_precount
     623    cdef("user_precount", "{_auto_precount}; ", "auto_precount_key", 0x10)
     624
     625    #: add _auto_cleanup to the end of user_scan_tail
     626    cdef("user_scan_tail","{_auto_cleanup}; ", \
    675627         "auto_user_scan_tail_key",0x20)
    676 
    677628  }
    678629
    … …  
    686637  if (AUTO_LEVEL < 1) {
    687638
    688     # remove auto_prescan_head from user_prescan_head
     639    #: remove _auto_prescan_head from user_prescan_head
    689640    cdef("user_prescan_head", "", "auto_prescan_head_key", "delete")
    690641
    691     # remove auto_user_chk_counts from user_chk_counts
     642    #: remove _auto_user_chk_counts from user_chk_counts
    692643    cdef("user_chk_counts", "", "auto_user_chk_counts_key", "delete")
    693644
    694     # remove auto_precount from user_precount
     645    #: remove _auto_precount from user_precount
    695646    cdef("user_precount", "", "auto_precount_key", "delete")
    696647
    697     # remove auto_cleanup from user_scan_tail and cleanup_once
     648    #: remove _auto_cleanup from user_scan_tail
    698649    cdef("user_scan_tail", "", "auto_user_scan_tail_key", "delete")
     650    #: remove _auto_cleanup from cleanup_once
    699651    cdef("cleanup_once", "", "auto_cleanup_once_key", "delete")
    700652  }
    … …  
    710662  exposure time adjustments.
    711663
    712   Description:
    713 
     664  DESCRIPTION:
    714665    Need some more details here...
    715666
    716 
    717   Usage::
     667  USAGE::
    718668
    719669    > auto_set_mode [<mode>]
    … …  
    723673        when called with no arguments, the user is prompted
    724674
    725   Example::
     675  EXAMPLE::
    726676
    727677    > auto_set_mode 1
    728678        use the pilot exposure mode for automatic adjustments.
    729679
    730   .. seealso::
    731 
     680  SEE ALSO:
    732681    :spec:def:`auto_setup`
    733682
    … …  
    767716  adjustments.
    768717
    769   Usage::
     718  USAGE::
    770719
    771720    > auto_set_exposure [<min> <max>]
    … …  
    773722        when called with no arguments, the user is prompted
    774723
    775   Arguments:
    776 
    777   :param float min_exptime: minimum exposure time [s]
    778   :param float max_exptime: maximum exposure time [s]
    779 
    780   Example:
    781 
    782     * set the minimum exposure time to 1 sec and the maximum to 10 sec::
     724  EXAMPLE::
    783725
    784726      > auto_set_exposure 1 10
     727          set the minimum exposure time to 1 sec and the maximum to 10 sec
    785728
    786729  """
    … …  
    811754  Display the current auto settings.
    812755
    813   Usage::
     756  USAGE::
    814757
    815758    > auto_show
    … …  
    857800  Display the current auto-level exposure settings.
    858801
    859   Usage::
     802  USAGE::
    860803
    861804    > auto_show_exposure
    … …  
    869812
    870813
    871 #==============================================================================
     814###############################################################################
    872815# Internal macros
    873 #==============================================================================
     816###############################################################################
     817
     818#------------------------------------------------------------------------------
     819def _auto_cleanup '{
     820  """
     821  Cleanup routine for automatic filter/exposure control
     822  """
     823
     824  # drop in filters after finishing, since we do not know where we end up
     825  # (center of a peak for dscan?)
     826  AUTO_SET_PILOT = 1
     827  AUTO_FILTER_LOCK = 0
     828  if(AUTO_LEVEL > 0){
     829    filter_trans 1e-10
     830  }
     831  #: remove _auto_cleanup_once from cleanup_once
     832  cdef("cleanup_once", "", "auto_cleanup_once_key", "delete")
     833}'
     834
     835
     836#------------------------------------------------------------------------------
     837def _auto_prescan_head '{
     838  """
     839  Prepare for automatic filter/exposure control before the start of a scan
     840
     841  This inserts filters with a transmission of 1e-10, sets some values in
     842  the global variables and adds a cleanup routine to ``cleanup_once``.
     843  """
     844
     845  # if automatic filter setting is active start scan with very low
     846  # filter transmission
     847  if(AUTO_LEVEL > 0){
     848    AUTO_ORIG_EXPTIME = COUNT_TIME
     849    filter_trans 1e-10
     850    if(AUTO_LEVEL > 1){
     851      # start with low exposure times
     852      COUNT_TIME = AUTO_EXP_LOW
     853      _ctime = COUNT_TIME
     854    }
     855  }
     856  #: add _auto_cleanup to cleanup_once
     857  cdef("cleanup_once","{_auto_cleanup}; ", "auto_cleanup_once_key",0x20)
     858}'
     859
     860
     861#------------------------------------------------------------------------------
     862def _auto_user_chk_counts '{
     863  """
     864  Check if counts are valid and retake exposure if necessary.
     865  """
     866
     867  if(AUTO_LEVEL > 0){
     868    # automatic filter and exposure setting (if activated)
     869    success = _auto_adjust_redo()
     870  }
     871}'
     872
     873
     874#------------------------------------------------------------------------------
     875def _auto_precount '{
     876  """
     877  Prepare for automatic filter/exposure control at beginning of count command.
     878  """
     879
     880  if(AUTO_LEVEL > 0){
     881    if(AUTO_MODE == 1 & AUTO_SET_PILOT == 1){
     882      # remember the original exposure time
     883      AUTO_ORIG_EXPTIME = COUNT_TIME
     884      # set the pilot exposure time
     885      COUNT_TIME = AUTO_PILOT_EXPTIME
     886      _ctime = COUNT_TIME
     887      AUTO_SET_PILOT = 0
     888    }
     889  }
     890}'
     891
    874892
    875893#------------------------------------------------------------------------------
    876894def _auto_print_setup '{
    877895  """
    878   Summary
    879   -------
    880   Prints the configuration options and current values to screen
    881 
    882   .. note::
     896  Print the configuration options and current values to screen
     897
     898  NOTE:
    883899     The option numbers must be kept in sync between
    884900     :spec:def:`_auto_set_option` and
    … …  
    919935def _auto_set_option '{
    920936  """
    921   Sets a new value for a given option
    922 
    923   Description:
    924 
     937  Sets a new value for a given option.
     938
     939  DESCRIPTION:
    925940    Sets a new value for a given option from the options menu that was created
    926941    with the :spec:def:`_auto_print_setup` command.
    927942
    928   .. note::
    929      The option numbers must be kept in sync between
    930      :spec:def:`_auto_set_option` and
    931      :spec:def:`_auto_print_setup`.
     943  NOTE:
     944    The option numbers must be kept in sync between
     945    :spec:def:`_auto_set_option` and
     946    :spec:def:`_auto_print_setup`.
    932947
    933948  """
    … …  
    11631178  Analyze the previous exposure
    11641179
    1165   Description:
    1166 
     1180  DESCRIPTION:
    11671181    This macro retrieves the necessary information to analyze the last exposure
    11681182    and to initiate adjustments, if necessary. Usually, this step consists only
    … …  
    11721186    etc.
    11731187
    1174   Usage::
     1188  USAGE::
    11751189
    11761190    > _auto_analyze_exposure
    … …  
    11881202  Calculate and apply necessary exposure time and filter adjustments.
    11891203
    1190   Description:
    1191 
    1192     The function returns 1 if transmission or exposure time are changed, 0
    1193     otherwise.
     1204  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()
    11941211
    11951212  """
    … …  
    14071424  Make sure the user-entered exposure times are consistent
    14081425
    1409   Usage::
     1426  USAGE::
    14101427
    14111428    > _auto_check_exposure
    … …  
    14291446  Make sure the user-entered count levels are consistent
    14301447
    1431   Usage::
     1448  USAGE::
    14321449
    14331450    > _auto_check_levels
    … …  
    14591476  round it to the given count time precision.
    14601477
    1461   Usage::
     1478  USAGE::
    14621479
    14631480    > adjusted_time = _auto_calc_exposure(requested_time)
    … …  
    14861503  Determines whether the auto-adjusting has been successful.
    14871504
    1488   Description:
     1505  DESCRIPTION:
    14891506
    14901507    If the current exposure does not meet the required criteria, counting
    … …  
    14931510    The function returns 1 in case of success, 0 otherwise.
    14941511
    1495   Usage::
     1512  USAGE::
    14961513
    14971514    > success = _auto_adjust_redo()
    14981515
    1499   .. note::
    1500      This macro makes use of the :spec:def:`recount` macro, which has to be
    1501      added to SPEC during the startup procedure.
     1516  NOTE:
     1517    This macro makes use of the :spec:def:`recount` macro, which has to be
     1518    added to SPEC during the startup procedure.
    15021519
    15031520  """
    … …  
    15461563    Clears the terminal screen
    15471564
    1548     Description:
    1549 
     1565    DESCRIPTION:
    15501566      Clears the screen without losing the screen history or messing up the
    15511567      scrolling capabilities (this has been a problem for certain terminals)
    … …  
    15531569      returning the cursor to the top left corner.
    15541570
    1555     Usage::
     1571    USAGE::
    15561572
    15571573      > _clear_screen
    … …  
    15761592}
    15771593
    1578 #==============================================================================
     1594###############################################################################
    15791595# End of $Id: $
    1580 #==============================================================================
     1596###############################################################################
Note: See TracChangeset for help on using the changeset viewer.