; SETMAXAP
;---------------------------------------------------------------
;! Examines/alters system parameter limiting dynamic pseudo-AP
;# VERB TV
;-----------------------------------------------------------------------
;;  Copyright (C) 2008
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
SETMAXAP  LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
SETMAXAP:  verb to set maximum dynamic pseudo-AP memory

          No adverbs: desired size in Megabytes is given as an
          immediate argument.  If that argument is missing or
          out of range the current size and limits are shown.
          Example: SETMAXAP(0) displays current and allowed
          limits; SETMAXAP(256) sets limit to 256 Mbytes.
----------------------------------------------------------------
SETMAXAP
Type: verb
Use:  The pseudo-AP in AIPS now uses dynamic memory in a size suited
      to the current problem.  AIPS has algorithms that can handle
      situations in which the problem does not fit into memory.  But
      it is very hard to determine a reasonable memory to use, since
      most operating systems will allow the task to ask for more
      memory than it can actually provide.  When this happens, the
      task will thrash (page fault a lot) and take much more time than
      if it were using a smaller memory and one of the small memory
      algorithms.  This verb lets you adjust this important system
      parameter to guide AIPS tasks to work as efficiently as
      possible.

      The initial limit will be set to 528 Mbytes, but you are allowed
      to go up to 1536 Mbytes on 32-bit addressing machines 6144
      Mbytes on 64-bit addressing machines (e.g. AMD running code
      specially compiled for them).

      Note that operating systems often use up to 512 Mbytes of RAM
      these days and there are other programs running on your machine
      such as editors, e-mail, and other AIPS tasks.

Adverbs: NONE.
      SETMAXAP takes an immediate argument giving the desired limit on
      AP size in Megabytes.  If the argument is missing or out of
      range, the verb will display the current size limit and the
      range of allowed size limits.  If the argument is in the legal
      range, the system parameter will be changed and known to all
      AIPS tasks starting on that computer after the verb is run.  If
      the machine is a multi-user (public) machine, please exercise
      caution and be responsible.

Discussion:
      Memory is used for the following:
         1. Basic operating system functions
         2. AIPS.EXE, TV, TeK, message server processes
         3. AIPS task - basic needs plus pseudo-AP
         4. "swap-memory" used by the OS to hold some or all of your
         disk file(s) in memory rather than use much slower disk
         5. memory types 3 and 4 for every other task in the system
      Note that a task such as IMAGR running on a multi-facet case
      can use a lot of pseudo-AP at times when it makes the initial
      beams and makes or remakes all the facet images at once.  In
      between these operations it uses less memory but still reads and
      rereads the IMAGR work file repetitively plus at least one image
      file.  It will work a great deal better if the IMAGR work file
      can stay in the swap-memory.  Therefore you should estimate the
      size of that work file and the costs of parts 1 and 2 before
      deciding to max out the pseudo-AP memory.  If there is no way
      the work file will fit in swap-memory, then you are better off
      maxing out the pseudo-AP.  In any case, beware of running
      several large AIPS tasks at once - they can end up clobering
      each other for memory with the agregate taking much longer to
      run than it would have taken running them sequentially.

      The verb SIZEFILE will tell you the size of your UV data set in
      magabytes, returning the value in adverb FSIZE.  If you are
      imaging all of the IFs and spectral channels in that data set
      together, then this will be about the size of your work file.
      If you are doing only one of the channels/IFs at a time, the
      work file will be slightly larger than FSIZE/n where n is the
      total number of channels times IFs in the input data set.
----------------------------------------------------------------
