AIMS(1)

NAME
     AIMS  - Automated Instrumentation and Monitoring System

DESCRIPTION
     AIMS provides users of  multi-processor  parallel  computers
     and  workstation networks with a suite of tools for monitor-
     ing and analyzing the performance of their parallel applica-
     tions.   Native application source code (in either C or For-
     tran) is passed through an instrumentor (see xinstrument(1)
     and batch_inst(1))  which  inserts  ``instrumentation'' (or
     monitoring  code)  around  certain  (user-selectable)   con-
     structs.   This  instrumented  code  is then linked with the
     AIMS monitor libraries.  When the  instrumented  application
     is  run,  the monitor routines produce a trace of the execu-
     tion. This trace can then be sorted (see  tracesort(1))  and
     passed to the analysis tools provided with AIMS. These tools
     include VK(1) (an execution-trace animator),  tally(1)  (for
     tabulation  of performance data), and pc(1) (for perturbance
     compensation).

GETTING STARTED QUICKLY
     This section will show the first-time user  how  to  quickly
     instrument  and  view the performance of an application.  To
     learn about the full range of capabilites of AIMS,  see  The
     AIMS Reference Manual.

     Before  actually  instrumenting  an  application,  the  user
     should become familiar with two data structures generated by
     AIMS.  The ``application  database''  is  used  for  storing
     information  about  the static structure of an application's
     source code.  The analysis tools  use  this  information  to
     relate  traced  events  to  instrumented  constructs  in the
     source   code.    The    instrumentation    programs    (see
     batch_inst(1)  and  xinstrument(1))  build  the  application
     database and write it  to  a  file,  which  is  subsequently
     incorporated by AIMS into the trace file produced by execut-
     ing an instrumented application program.  Another  important
     data  structure  in  AIMS  is the ``instrument enabling pro-
     file.'' This is a table of flags, one for each  instrumented
     construct  in  the  application database. The profile can be
     used either by the instrumentor to select the constructs  to
     be instrumented or by the monitor to select the instrumented
     constructs to be traced. Only those constructs whose flag is
     true  in  the profile will be instrumented/traced (see 
     MONITOR(5)).

     AIMS supports two types of instrumentor interfaces:  a batch
     version  and  an  interactive  version. The batch version is
     used by the interactive version and is not  recommended  for
     the   casual   user.   In  both  instances,  instrumentation
     proceeds in two basic phases:  the extraction  phase,  where
     the  program  structure  is  extracted from source files and
     written out to the application database; and the  instrumen-
     tation  phase,  where  the source code is annotated.  In the
     batch version of our  instrumentors,  there  is  no  visible
     separation between these phases; certain instrumentable con-
     structs (see below) are  instrumented  by  default.  In  the
     interactive  version, users are given an opportunity between
     the phases to use the information  about  the  structure  of
     their  applications  to interactively select the source-code
     constructs to be instrumented.

     The instrumented source files have the same names  as  their
     respective  originals;  they  are  written  into a different
     directory.  ./inst is  the  default  pathname  used  by  our
     instrumentors.  Here  is  an  example  of  running the batch
     instrumentor:

          batch_inst -platform f77-pvm xpose_node.f xpose1.f

     By default, all communication and syncronization calls,  and
     none  of  the  user  constructs  (e.g.  routines, loops) are
     instrumented. To instrument all of the  instrumentable  con-
     structs in the source, the following line could be used:

          batch_inst -platform f77-pvm -enable all xpose_node.f

     For information about the interactive instrumentor, refer to
     the documentation for xinstrument(1).

     Before compiling the instrumented code, the user  must  copy
     any  support files (e.g. include files, make files) into the
     directory containing the instrumented  code.  Also,  if  any
     modules were not instrumented (note that you must instrument
     the modules containing the main procedures), these must also
     be  copied  into the instrumented directory. Finally, modify
     the makefile (in the  instrumented  directory)  so  that  it
     links  the  AIMS monitor libraries with the application exe-
     cutables.  Ask the system administrator for the location  of
     these libraries; their names are nodelib.a and hostlib.a.

     Before running the program, you may need to modify the moni-
     tor  profile (named AIMS.monrc) created by the instrumentor.
     This file specifies how large a buffer  the  monitor  should
     use, where the trace file should go, whether you have a host
     program, as well as several other options. Refer to the AIMS
     reference  manual  or  MONITOR(5)  for details.  The example
     shipped with AIMS provides the following AIMS.monrc file:

          # Output for trace data
          TRACE_FILE:       TRACE.OUT
          # application database
          APPL_DB_FILE:     APPL_DB

          # Output for statistical trace data
          STAT_FILE:        TRACE.OUT.STAT
          # Amount of data to save before flushing
          BUFFER_SIZE:      262144
          # 0 - Use the SRM's file system.
          # 1 - Use the Concurrent File System
          FILE_MODE:        1
          # 0 - Don't flush when the buffer fills up.
          # 1- Flush when the record buffer fills up.
          FLUSH_MODE:       1
          # 0 - Running hostless
          # 1 - Running with a host program
          HOST_PROGRAM:     0
          # Define trace level, 0 for no trace
          TRACE_LEVEL:      4
          # Define statistical trace level, 0 for no statistics
          STAT_LEVEL:       0
          # 1 - Do tracesort, 0 - Don't perform tracesort
          TRACE_SORT:       1

     The AIMS.monrc profile must be in the  same  directory  from
     which  you  run your application. After running the applica-
     tion, obtain the trace file and sort it using  tracesprt(1).
     You can now view the trace file with VK(1) or obtain perfor-
     mance statistics using the tally(1) program.

     An important note:  AIMS currently does not monitor the full
     PVM or MPI constructs.

USAGE OUTLINE
     1) Instrument code using either the interactive instrumentor
          (cref.    xinstrument(1))  or  the  batch  instrumentor
          (cref. batch_inst(1)).

     2) Copy support files into the instrumented directory.

     3) Modify the makefile so that the  AIMS  monitor  libraries
          are linked with the final executable.

     4) Modify the monitor profile (AIMS.monrc).

     5) Run the application.

     6) Sort the resulting trace file if necessary.

     7) Analyze the sorted trace file using AIMS' analysis tools

FILES
     /usr/lib/X11/app-defaults/Aims

SEE ALSO
     batch_inst(1),    xinstrument(1),    tracesort(1),    VK(1),
     tally(1), pc(1), MONITOR(3), MONITOR(5)
     The AIMS Reference Manual

AIMS Release 3.7    Last change: 2 July 1997