In this directory,  you will find the  source file for  the release of
AutoLink 2.20 . See file AL_CHANGES for changes done to AutoLink.

--------------------

Program information :
 AutoMap / AutoLink 2.20

   Version 1.1 (January 1997) :
     Eric Baland (AutoMap) & Koen Vrielink AutoLink)
   Version 2.0 (July 1997) :
     Jasper Peeters (AutoLink)
   Version 2.1 (July 1998)
     Martial MICHEL (AutoMap & AutoLink : Concept & Programming)
     & Delphine GOUJON (AutoLink : Concept)
   Version 2.11 (November 1998)
     Martial MICHEL
     & Thibaut ROUFFINEAU (Testing)
   Version 2.11.1 (January 1999)
     Martial MICHEL
   Version 2.11.2 (February 1999)
     Martial MICHEL
   Version 2.20 (June 1999)
     Martial MICHEL

--------------------

Basic Description of the files :
-----
o "src" directory :
 o al_common.h
   File that  allow  the user  to  set  all the  internal  settings of
AutoLink.

 o al_internals.c
   Define all the internal data-types used by AutoLink algorithm.

 o al_internals.h
   Define the prototypes for the internal  data-types used by AutoLink
algorithm.

 o autolink.inc
   Contains  the  internal     definitions  of  the   functions    and
sub-functions defining the AutoLink user available functions.

 o Makefile.base
   Is a template Makefile for  users to adapt to their  use to be able
to use AutoMap and AutoLink easily.
-----
o "script" directory :
 o al_analyze.pl
   Is a perl script to create log files if  the user chooses to output
AutoLink traces to screen and redirect it to a file.

 o al_bench.pl
   Is   a perl  script  to  extract  benchmark logs  from the AutoLink
generated logs. Same restriction as AL_analyze.pl regarding the use of
"env". Launch the script without arguments to get a small help page.

 o al_packettune.pl
   Is a perl script to analyze packettuning output.

 o runbench
   Is a shell script to run a packettuning full analyze.

-----
o "doc" directory :
 o autolink_use.html
   HTML documentation on how to use AutoMap and AutoLink

 o am-al-use.gif
   A  picture  showing how to  work  with all  the files  generated by
AutoMap and used by AutoLink. "struct.h" is the structure file used by
the "userprog"ram.
-----
o "PacketTuning" directory :
 This  directory contains a   full example suite of PacketTuning,  and
uses  of new   AutoLink  functionalities.  See   README file in   this
directory.
-----
 o AL_CHANGES
   Changes since initial version with new algorithm (2.1)

 o AL_README
   The file you are reading right now :)

--------------------

Detailed description of some file use:

 o al_common.h
   In this file you  will be able to find  some "#define" that you may
want to adapt to your particular use :
   - AL_HASH_TABLE_PRIME_NUMBER is the prime number used to define the
internal number of  cells   available to  one of  AutoLink's  internal
data-type.  Some rules  to the setting of  this variable are specified
before the definition of  this value. This  number is used to dispatch
efficiently already  traversed  addresses, so  the more  links you may
have to traverse, the largest distribution possible is advised.
   - AL_SARRAY_SIZE is the size  of one another of AutoLink's internal
data-type.  This  set the minimum size  of  a dynamically extended two
dimensional array, used  to store addresses  of traversed or  restored
elements.
   -  AL_DEFAULTMAXPACKET   is  the   maximal  size (and/or   minimal,
depending of the size  of the data-type) of  the packet to be sent for
each data-type.    Its influence  on  the  efficiency of  AutoLink  is
related to the implementation of MPI  that you are  using. The size is
defined in bytes.

   In  this file is also defined  trace generation entries  to see the
way AutoLink  behaves. This is  done by setting  (uncommenting mostly)
the   define  "_AL_DEBUG_".  Once  this  done,   you may want  to  set
"_AL_DBG_LVL" with an "|" (or) combination of the following values :
   - _AL_NODEBUG   : Basic level that should always be set
   - _AL_DBG_FNAME : Print the function name entered
   - _AL_DBG_FINT :  Tell  the basic  functions done  by  the function
entered
   - _AL_DBG_DATA  : Tell the status of the processed data
   - _AL_DBG_STEP  : Follow the step of some "for" functions
   And also should  debug mode be set, you  may want to set (uncomment
and set) the define "_AL_DEBUG_FILENAME"  to a file name for  AutoLink
to output its trace into a "filename.nodenumber" file.
   - _AL_DBG_BENCH :  For  AutoLink to   generate its  own  benchmarks
(required if  using  the al_bench.pl  script  in any  other mode  than
"user")
   -  _AL_DBG_UBENCH : For user   to make AutoLink  generate their log
entry, adding  Time  stamp  and   Packet size  (required  to  use  the
al_bench.pl script in "user" mode)

 o autolink.inc
   Defines the following user available functions:
   - AL_Init() :  to use after doing  an "MPI_Init", will take care of
creating the MPI data-types and set all required AutoLink internals.
   - AL_Finalize() : to use just before doing "MPI_Finalize" to finish
processing with AutoLink.
   - AL_SetPacketSize(size)  : where "size"  is an integer. Will allow
you to dynamically change the maximum packet size.  Note that you have
to do that  on every node for  which you want  to change the size, for
every  send  and receive function will  check  for consistency of this
value, and will stop if there is a problem.
   -   AL_Send(buf, datatype,     dest,   tag, comm)   :   will return
"MPI_SUCCESS" if  successfully achieved sending, otherwise return code
of the  last MPI  function  used. AL_Send will  send  the buffer "buf"
(from a   pointer to the  data-type) of  data-type "datatype" ("AL_" +
type  name  [example :  should  the  definition  be  "typedef   struct
_intStruct intStruct    /*~   AM   */;"   the   data-type    would  be
"AL_intStruct"]) to MPI destination "dest" with MPI tag "tag", and MPI
communicator "comm".
   - AL_Recv(buf, datatype, source,  tag, comm, status) : will  return
"MPI_SUCCESS" if successfully  achieved sending, otherwise return code
of the last MPI function used.  AL_Recv will receive an AutoLink send,
recreates its links and store a pointer  to the initial element of the
data-structure by putting the result both in "buf" (the address of the
element  [of type pointer] to   store the  result) and "datatype"  (to
store the data-type, that  can be compared to  "AL_" + type  name [see
description in AL_Send]). It    received  its data from MPI     source
"source", with MPI tag "tag" and MPI communicator "comm". It will also
save the last MPI status in status (pointer to) if provided.
   - AL_LogEntry(char *entry) : will add entry to AutoLink log file so
that it can be post-processed by "al_bench.pl".
