Changeset 1014

Timestamp:

Jul 14, 2012 8:50:54 AM (11 years ago)

Author:

jemian

Message:

regexp problem with def macro recognition, see problem-auto.mac

Location:

specdomain/trunk/src/specdomain/comparison

Files:

• auto.mac (modified) (33 diffs)
• problem-auto.mac (added)

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

@@ -62 +62 @@
 ----------------------------------------
 The filter adjustment assures a high incident photon rate within a band
-just below the rate limit of the detector. The width of the band is
-defined by the step size in transmission, defined in AUTO_FILTER_FACTOR,
+just below the rate limit of the detector. The width of the band is defined
+by the step size in transmission, defined in AUTO_FILTER_FACTOR,
 which is used for each correction. If the count rate is higher than
 AUTO_RATE_LIMIT, the transmission is immediately reduced by
@@ -132 +132 @@
 
 No special configuration is needed to run these macros. Simply load the macro
-file and run ``auto_setup``::
-
-> qdo auto.mac
-> auto_setup
+file and run :spec:def:`auto_setup`::
+
+  > qdo auto.mac
+  > auto_setup
 
 Dependencies
@@ -142 +142 @@
 Dependencies on other macros:
 
-* filter.mac (used to control the attenuators):
-
-  - filter_trans
-  - filter_get_trans()
-  - filter_get_trans_up()
-  - filter_get_mask()
-  - filter_max()
-
-* recount (modified count command used to retake an exposure)
+* :spec:macrofile:`filter.mac` (used to control the attenuators):
+
+  - :spec:def:`filter_trans`
+  - :spec:def:`filter_get_trans()`
+  - :spec:def:`filter_get_trans_up()`
+  - :spec:def:`filter_get_mask()`
+  - :spec:def:`filter_max()`
+
+* :spec:def:`recount` (modified count command used to retake an exposure)
 
 Impact
@@ -156 +156 @@
 The following chained macro definitions are affected by this macro:
 
-* user_prescan_head
-* user_chk_counts (provided in our modified ``count`` command)
-* user_precount
+* :spec:def:`user_prescan_head`
+* :spec:def:`user_chk_counts` (from our modified :spec:def:`count` command)
+* :spec:def:`user_precount`
 
 File information
@@ -252 +252 @@
   SPHINX code documentation suite.
 
+2012/07/13 (CS):
+
+- renamed some private macros to start with underscores::
+
+    auto_precount        --> _auto_precount
+    auto_prescan_head    --> _auto_prescan_head
+    auto_user_chk_counts --> _auto_user_chk_counts
+
+- moved the macro definitions for the above macros out of the
+  :spec:def:`auto_set_level` macro to avoid unnecessary nested definitions.
+
+
 TO DO
 -----
@@ -258 +270 @@
 - complete documentation
 - insert hyperlinks into documentation
+
 """
 
-#==============================================================================
-
-#==============================================================================
+###############################################################################
 # Global variable definitions
-#==============================================================================
-
-  # Save the name of this macro file (Used for the help function).
-  global AUTO_MAC
-         AUTO_MAC = DOFILE
-
-  global AUTO_LEVEL                # Type of adjustments {0,1,2}
-  global AUTO_MODE                 # Adjustment mode (pilot/post-exp){0,1}
-  global AUTO_COUNTER              # Counter to monitor
-  global AUTO_COUNT_RBV            # Counter read back value (measured counts)
-  global AUTO_RETRY_MAX            # Maximum number of retries
-  global AUTO_EXP_LOW              # low exposure time limit
-  global AUTO_EXP_HIGH             # highexposure time limit
-  global AUTO_PILOT_EXPTIME        # exposure time for pilot exposures
-  global AUTO_RATE_LIMIT           # High rate limit
-  global AUTO_COUNT_HIGH           # High count limit
-  global AUTO_COUNT_TARGET         # Target count level
-  global AUTO_COUNT_LOW            # Low count limit
-  global AUTO_FILTER_FACTOR        # Filter transmission factor for adjustments
-  global AUTO_COUNT_PREC           # Count time precision (rounding)
-
-  global AUTO_FILTER_LOCK          # Lock if rate-limited
-  global AUTO_SET_PILOT            # Set pilot exposure time in user_precount
-  global AUTO_ORIG_EXPTIME         # save the original requested count time
-  global AUTO_DEBUG                # debug flag
+###############################################################################
+
+  global AUTO_MAC                 #: Save the name of this macro file
+  global AUTO_LEVEL               #: Type of adjustments {0,1,2}
+  global AUTO_MODE                #: Adjustment mode (pilot vs. post-exp) {0,1}
+  global AUTO_COUNTER             #: Counter to monitor
+  global AUTO_COUNT_RBV           #: Counter read back value (measured counts)
+  global AUTO_RETRY_MAX           #: Maximum number of retries
+  global AUTO_EXP_LOW             #: Low exposure time limit
+  global AUTO_EXP_HIGH            #: High exposure time limit
+  global AUTO_PILOT_EXPTIME       #: Exposure time for pilot exposures
+  global AUTO_RATE_LIMIT          #: High rate limit
+  global AUTO_COUNT_HIGH          #: High count limit
+  global AUTO_COUNT_TARGET        #: Target count level
+  global AUTO_COUNT_LOW           #: Low count limit
+  global AUTO_FILTER_FACTOR       #: Filter transmission factor for adjustments
+  global AUTO_COUNT_PREC          #: Count time precision (rounding)
+  global AUTO_FILTER_LOCK         #: Lock if rate-limited
+  global AUTO_SET_PILOT           #: Set pilot exposure time in user_precount
+  global AUTO_ORIG_EXPTIME        #: Save the original requested count time
+  global AUTO_DEBUG               #: Debug flag
 
   # set default values for global variables
+  AUTO_MAC = DOFILE
   AUTO_COUNTER = det
   AUTO_LEVEL = 0
@@ -309 +317 @@
   AUTO_DEBUG = 0
 
-#==============================================================================
+
+###############################################################################
 # Macro command definitions
-#==============================================================================
+###############################################################################
 
 #------------------------------------------------------------------------------
 # allow for misspelled help commands
-def autohelp 'auto_help'
+#def autohelp '{auto_help}'
 
 def auto_help '{
@@ -497 +506 @@
   Turn off any automatic filter and exposure adjustments.
 
-  Usage::
+  USAGE::
 
     > auto_off
 
-  .. note:: This command is equivalent to ``auto_set_level 0``
-
-  .. seealso::
+  NOTE:
+    This command is equivalent to ``auto_set_level 0``
+
+  SEE ALSO:
      :spec:def:`auto_set_level`,
      :spec:def:`auto_on`
@@ -517 +527 @@
 def auto_on '{
   """
-  See :spec:def:`auto_set_level`
-  """
+  Turn on automatic filter and exposure adjustments.
+
+  This macro is identical to :spec:def:`auto_set_level`. Please refer to the
+  :spec:def:`auto_set_level` documentation for more details.
+  """
+
 auto_set_level $*
 
@@ -528 +542 @@
   Set the level of automatic filter and exposure adjustments.
 
-  Usage::
+  USAGE::
 
     > auto_set_level [<level>]
     > auto_on [<level>]
-        where <level> can be one of the following:
-          0 - automatic filter and exposure OFF
-          1 - automatic filter ON, automatic exposure OFF
-          2 - automatic filter and exposure ON
-        if <level> is ommitted, the users is asked for input
-
-
-        ===== =================================================================
-        Level Description
-        ===== =================================================================
-        0     No automatic adjustments are made
-        1     Only filters are adjusted, no exposure time adjustments
-        2     Both filters and exposure times are automatically adjusted
-        ===== =================================================================
-
-
-  Examples::
+
+  If now arguement is given, the user is prompted for input. The argument
+  ``<level>`` can be one of the following:
+
+      =====  =================================================================
+      Level  Description
+      =====  =================================================================
+      ``0``  No automatic adjustments are made
+      ``1``  Only filters are adjusted, no exposure time adjustments
+      ``2``  Both filters and exposure times are automatically adjusted
+      =====  =================================================================
+
+  EXAMPLES::
 
     > auto_set_level
@@ -556 +566 @@
         turns on automatic filter adjustments (level 1)
 
-  .. note::
-     ``auto_set_level`` and ``auto_on`` are equivalent to each other
-
-  .. seealso::
+  NOTE:
+     :spec:def:`auto_set_level` and :spec:def:`auto_on` are equivalent to
+     each other.
+
+  SEE ALSO:
      :spec:def:`auto_off`
 
@@ -595 +606 @@
   }
 
-  #-------------------------------------------
-  # define necessary chained macro definitions
-
-  #--------------------
-  def auto_prescan_head \'
-  #   =================
-    # if automatic filter setting is active start scan with very low
-    # filter transmission
-    if(AUTO_LEVEL > 0){
-      AUTO_ORIG_EXPTIME = COUNT_TIME
-      filter_trans 1e-8
-      if(AUTO_LEVEL > 1){
-        # start with low exposure times
-        COUNT_TIME = AUTO_EXP_LOW
-        _ctime = COUNT_TIME
-      }
-    }
-    # add auto_cleanup to cleanup_once
-    cdef("cleanup_once","auto_cleanup; ", "auto_cleanup_once_key",0x20)
-  \'
-
-  #-----------------------
-  def auto_user_chk_counts \'
-  #   ====================
-    if(AUTO_LEVEL > 0){
-      # automatic filter and exposure setting (if activated)
-      success = _auto_adjust_redo()
-    }
-  \'
-
-  #----------------
-  def auto_precount \'
-  #   =============
-    if(AUTO_LEVEL > 0){
-      if(AUTO_MODE == 1 & AUTO_SET_PILOT == 1){
-        # remember the original exposure time
-        AUTO_ORIG_EXPTIME = COUNT_TIME
-        # set the pilot exposure time
-        COUNT_TIME = AUTO_PILOT_EXPTIME
-        _ctime = COUNT_TIME
-        AUTO_SET_PILOT = 0
-      }
-    }
-  \'
-
-  #---------------
-  def auto_cleanup \'
-  #   ============
-    # drop in filters after finishing, since we do not know where we end up
-    # (center of a peak for dscan?)
-    AUTO_SET_PILOT = 1
-    AUTO_FILTER_LOCK = 0
-    if(AUTO_LEVEL > 0){
-      filter_trans 1e-8
-    }
-    cdef("cleanup_once", "", "auto_cleanup_once_key", "delete")
-  \'
-
-
   #--------------------------------------------
   # include necessary chained macro definitions
@@ -660 +612 @@
   if (AUTO_LEVEL > 0){
 
-    # add auto_prescan_head to user_prescan_head
-    cdef("user_prescan_head", "auto_prescan_head; ", "auto_prescan_head_key",\
-         0x10)
-
-    # add auto_user_chk_counts to user_chk_counts
-    cdef("user_chk_counts", "auto_user_chk_counts; ", \
+    #: add _auto_prescan_head to user_prescan_head
+    cdef("user_prescan_head", "{_auto_prescan_head}; ", \
+         "auto_prescan_head_key", 0x10)
+
+    #: add _auto_user_chk_counts to user_chk_counts
+    cdef("user_chk_counts", "{_auto_user_chk_counts}; ", \
          "auto_user_chk_counts_key")
 
-    # add auto_precount to user_precount
-    cdef("user_precount", "auto_precount; ", "auto_precount_key", 0x10)
-
-    # add auto_cleanup to the end of user_scan_tail
-    cdef("user_scan_tail","auto_cleanup; ", \
+    #: add _auto_precount to user_precount
+    cdef("user_precount", "{_auto_precount}; ", "auto_precount_key", 0x10)
+
+    #: add _auto_cleanup to the end of user_scan_tail
+    cdef("user_scan_tail","{_auto_cleanup}; ", \
          "auto_user_scan_tail_key",0x20)
-
   }
 
@@ -686 +637 @@
   if (AUTO_LEVEL < 1) {
 
-    # remove auto_prescan_head from user_prescan_head
+    #: remove _auto_prescan_head from user_prescan_head
     cdef("user_prescan_head", "", "auto_prescan_head_key", "delete")
 
-    # remove auto_user_chk_counts from user_chk_counts
+    #: remove _auto_user_chk_counts from user_chk_counts
     cdef("user_chk_counts", "", "auto_user_chk_counts_key", "delete")
 
-    # remove auto_precount from user_precount
+    #: remove _auto_precount from user_precount
     cdef("user_precount", "", "auto_precount_key", "delete")
 
-    # remove auto_cleanup from user_scan_tail and cleanup_once
+    #: remove _auto_cleanup from user_scan_tail
     cdef("user_scan_tail", "", "auto_user_scan_tail_key", "delete")
+    #: remove _auto_cleanup from cleanup_once
     cdef("cleanup_once", "", "auto_cleanup_once_key", "delete")
   }
@@ -710 +662 @@
   exposure time adjustments.
 
-  Description:
-
+  DESCRIPTION:
     Need some more details here...
 
-
-  Usage::
+  USAGE::
 
     > auto_set_mode [<mode>]
@@ -723 +673 @@
         when called with no arguments, the user is prompted
 
-  Example::
+  EXAMPLE::
 
     > auto_set_mode 1
         use the pilot exposure mode for automatic adjustments.
 
-  .. seealso::
-
+  SEE ALSO:
     :spec:def:`auto_setup`
 
@@ -767 +716 @@
   adjustments.
 
-  Usage::
+  USAGE::
 
     > auto_set_exposure [<min> <max>]
@@ -773 +722 @@
         when called with no arguments, the user is prompted
 
-  Arguments:
-
-  :param float min_exptime: minimum exposure time [s]
-  :param float max_exptime: maximum exposure time [s]
-
-  Example:
-
-    * set the minimum exposure time to 1 sec and the maximum to 10 sec::
+  EXAMPLE::
 
       > auto_set_exposure 1 10
+          set the minimum exposure time to 1 sec and the maximum to 10 sec
 
   """
@@ -811 +754 @@
   Display the current auto settings.
 
-  Usage::
+  USAGE::
 
     > auto_show
@@ -857 +800 @@
   Display the current auto-level exposure settings.
 
-  Usage::
+  USAGE::
 
     > auto_show_exposure
@@ -869 +812 @@
 
 
-#==============================================================================
+###############################################################################
 # Internal macros
-#==============================================================================
+###############################################################################
+
+#------------------------------------------------------------------------------
+def _auto_cleanup '{
+  """
+  Cleanup routine for automatic filter/exposure control
+  """
+
+  # drop in filters after finishing, since we do not know where we end up
+  # (center of a peak for dscan?)
+  AUTO_SET_PILOT = 1
+  AUTO_FILTER_LOCK = 0
+  if(AUTO_LEVEL > 0){
+    filter_trans 1e-10
+  }
+  #: remove _auto_cleanup_once from cleanup_once
+  cdef("cleanup_once", "", "auto_cleanup_once_key", "delete")
+}'
+
+
+#------------------------------------------------------------------------------
+def _auto_prescan_head '{
+  """
+  Prepare for automatic filter/exposure control before the start of a scan
+
+  This inserts filters with a transmission of 1e-10, sets some values in
+  the global variables and adds a cleanup routine to ``cleanup_once``.
+  """
+
+  # if automatic filter setting is active start scan with very low
+  # filter transmission
+  if(AUTO_LEVEL > 0){
+    AUTO_ORIG_EXPTIME = COUNT_TIME
+    filter_trans 1e-10
+    if(AUTO_LEVEL > 1){
+      # start with low exposure times
+      COUNT_TIME = AUTO_EXP_LOW
+      _ctime = COUNT_TIME
+    }
+  }
+  #: add _auto_cleanup to cleanup_once
+  cdef("cleanup_once","{_auto_cleanup}; ", "auto_cleanup_once_key",0x20)
+}'
+
+
+#------------------------------------------------------------------------------
+def _auto_user_chk_counts '{
+  """
+  Check if counts are valid and retake exposure if necessary.
+  """
+
+  if(AUTO_LEVEL > 0){
+    # automatic filter and exposure setting (if activated)
+    success = _auto_adjust_redo()
+  }
+}'
+
+
+#------------------------------------------------------------------------------
+def _auto_precount '{
+  """
+  Prepare for automatic filter/exposure control at beginning of count command.
+  """
+
+  if(AUTO_LEVEL > 0){
+    if(AUTO_MODE == 1 & AUTO_SET_PILOT == 1){
+      # remember the original exposure time
+      AUTO_ORIG_EXPTIME = COUNT_TIME
+      # set the pilot exposure time
+      COUNT_TIME = AUTO_PILOT_EXPTIME
+      _ctime = COUNT_TIME
+      AUTO_SET_PILOT = 0
+    }
+  }
+}'
+
 
 #------------------------------------------------------------------------------
 def _auto_print_setup '{
   """
-  Summary
-  -------
-  Prints the configuration options and current values to screen
-
-  .. note::
+  Print the configuration options and current values to screen
+
+  NOTE:
      The option numbers must be kept in sync between
      :spec:def:`_auto_set_option` and
@@ -919 +935 @@
 def _auto_set_option '{
   """
-  Sets a new value for a given option
-
-  Description:
-
+  Sets a new value for a given option.
+
+  DESCRIPTION:
     Sets a new value for a given option from the options menu that was created
     with the :spec:def:`_auto_print_setup` command.
 
-  .. note::
-     The option numbers must be kept in sync between
-     :spec:def:`_auto_set_option` and
-     :spec:def:`_auto_print_setup`.
+  NOTE:
+    The option numbers must be kept in sync between
+    :spec:def:`_auto_set_option` and
+    :spec:def:`_auto_print_setup`.
 
   """
@@ -1163 +1178 @@
   Analyze the previous exposure
 
-  Description:
-
+  DESCRIPTION:
     This macro retrieves the necessary information to analyze the last exposure
     and to initiate adjustments, if necessary. Usually, this step consists only
@@ -1172 +1186 @@
     etc.
 
-  Usage::
+  USAGE::
 
     > _auto_analyze_exposure
@@ -1188 +1202 @@
   Calculate and apply necessary exposure time and filter adjustments.
 
-  Description:
-
-    The function returns 1 if transmission or exposure time are changed, 0
-    otherwise.
+  DESCRIPTION:
+
+    The function returns 1 if transmission or exposure time have been changed,
+    0 otherwise.
+
+  USAGE::
+    > changed = _auto_adjust()
 
   """
@@ -1407 +1424 @@
   Make sure the user-entered exposure times are consistent
 
-  Usage::
+  USAGE::
 
     > _auto_check_exposure
@@ -1429 +1446 @@
   Make sure the user-entered count levels are consistent
 
-  Usage::
+  USAGE::
 
     > _auto_check_levels
@@ -1459 +1476 @@
   round it to the given count time precision.
 
-  Usage::
+  USAGE::
 
     > adjusted_time = _auto_calc_exposure(requested_time)
@@ -1486 +1503 @@
   Determines whether the auto-adjusting has been successful.
 
-  Description:
+  DESCRIPTION:
 
     If the current exposure does not meet the required criteria, counting
@@ -1493 +1510 @@
     The function returns 1 in case of success, 0 otherwise.
 
-  Usage::
+  USAGE::
 
     > success = _auto_adjust_redo()
 
-  .. note::
-     This macro makes use of the :spec:def:`recount` macro, which has to be
-     added to SPEC during the startup procedure.
+  NOTE:
+    This macro makes use of the :spec:def:`recount` macro, which has to be
+    added to SPEC during the startup procedure.
 
   """
@@ -1546 +1563 @@
     Clears the terminal screen
 
-    Description:
-
+    DESCRIPTION:
       Clears the screen without losing the screen history or messing up the
       scrolling capabilities (this has been a problem for certain terminals)
@@ -1553 +1569 @@
       returning the cursor to the top left corner.
 
-    Usage::
+    USAGE::
 
       > _clear_screen
@@ -1576 +1592 @@
 }
 
-#==============================================================================
+###############################################################################
 # End of $Id: $
-#==============================================================================
+###############################################################################