annotate docs/ReadMe.First @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

				AIM R7

The current release of AIM is R6.22. The appropriate files are README
and aim.tar.Z.

Sometime over the next few months a Letter to the Editor will appear
in JASA announcing a software package for Time-Domain Modelling of
Peripheral Auditory Processing. It is based on AIM Release 7 which
will be released at the time the Letter to the Editor appears. There
are no changes to the first two stages of AIM (the bmm and nap
stages); improvements have been made to the third stage (sai) but they
only affect exotic stimuli like damped and ramped sounds. Most users
would not notice the differences.

In preparation for the new release, we have set up a WWW page that
directs readers to this file (ReadMe.First) and AIM R7. The release
contains an alot of new documentation on all stages of AIM. We are
setting the new system up now and so pieces of it may appear in this
directory.

The new release of AIM is R7.0. The appropriate files are ReadMe.First
(this file) and aimR7.tar.Z.  You are welcome to take them, but the
ReadMeFirst file may not describe AIM R7 correctly in all details at
this point in time.

============================================================================

    		AUDITORY IMAGE MODEL (AIM) SOFTWARE PACKAGE

	   	        Medical Research Council, 
			Applied Psychology Unit
			Cambridge,  CB2 2EF,  UK
	     


============================================================================

This file contains:

 1. General information:
        A. Disclaimer and copyright.
        B. Acknowledgements.
        C. Contact addresses.
        D. Ftp instructions for obtaining the software.

 2. Getting started:
        A. Installing the software [compilation].
        B. Running the model.
        C. Setting the environment variables PATH and the MANPATH.

3.  Compiling the model - further details.
        A. X11 libraries.
        B. Alternative compilers.
        C. A note on color workstations.

4.  Next step after installing AIM.



============================================================================
 1. GENERAL INFORMATION:
============================================================================

A. Disclaimer and Copyright

Permission to use, copy, modify, and distribute the software described in
this document without fee is hereby granted for research purposes, provided
that this copyright notice appears in all copies and in all supporting
documentation, and that the software is not redistributed for any fee
(except for a nominal shipping charge). Anyone wanting to incorporate all or
part of this software in a commercial product must obtain a license from the
Medical Research Council.

The MRC makes no representations about the suitability of the software
described in this document for any purpose. It is provided `as is' without
express or implied warranty.

The MRC disclaims all warranties with regard to this software, including all
implied warranties of merchantability and fitness.  In no event shall the
MRC be liable for any special, indirect or consequential damages or any
damages whatsoever resulting from loss of use, data or profits, whether in
an action of contract, negligence or other tortious action, arising out of
or in connection with the use or performance of this software. 


============================================================================

B. Acknowledgements

The AIM software was developed for Unix workstations by John
Holdsworth and Mike Allerhand of the MRC APU, under the direction of
Roy Patterson. The physiological version of AIM was developed by
Christian Giguere. The options handler is by Paul Manson. The revised
SAI module is by Jay Datta. Michael Akeroyd extended the postscript
facilites and developed the xreview routine for auditory image
cartoons.

The project was supported by the MRC and grants from the U.K. Defense
Research Agency, Farnborough (Research Contract 2239); the EEC Esprit
BR Porgramme, Project ACTS (3207); and the U.K. Hearing Research Trust.


============================================================================

C. Contact Addresses.

    Roy D Patterson, Mike Allerhand, Michael Akeroyd, Jay Datta
    MRC APU, 15 Chaucer Road, Cambridge CB2 2EF, England.
    Phone    [phone]
    Fax      [phone]

    Christian Giguere 
    email:   [e-mail]  

ASSISTANCE:

    email:   [e-mail]   (Software support)
	     [e-mail]    (Auditory modelling)
	     [e-mail]  (Modelling and graphics)
	     [e-mail]	(Software and documentation)
             [e-mail]  		(tlf, meddis, aimlinux)

============================================================================

D. ftp Instructionsu for Obtaining the Software

Access to the APU site via ftp is by the address:
ftp.mrc-apu.cam.ac.uk Use <Name>="anonymous" and <Password>=your email
address.  Once inside the APU ftp system, cd to the AIM directory,
pub/aim/.  The AIM software is in the compressed archive `aim.tar.Z'.
The ReadMe.First file contains the text of this document. Copy both.

For example:

	ftp ftp.mrc-apu.cam.ac.uk

	Name (mrc-apu.cam.ac.uk:you): anonymous
	Password: your email address

	cd pub/aim

	get aim.tar.Z
	get ReadMe.First


Details of machine and address

Name:    sirius.mrc-apu.cam.ac.uk
Address:  192.18.195.1
Aliases:  dns0.mrc-apu.cam.ac.uk



============================================================================
 2. GETTING STARTED:
============================================================================

A. Installing the Software

It is best to make a new directory (e.g. aim) for the software. Put
aim.tar.Z and ReadMe.First in the directory and unpack the source code 
using the command:

    zcat aim.tar.Z | tar xvf -

The current directory should then contain a makefile and a set of
subdirectories. Five of these contain the C source code for AIM
(filter, glib, model, stitch, and wdf). The tools directory contains C
code for ancillary routines to construct stimuli and process the
multi-channel output that AIM produces. The man directory contains
online manual pages available through MANPATH and the instruction
'manaim'. The scripts directory contains guided tours of AIM in the
form of scripts that also serve to test the installation and
illustrate a typical mode of operation. The waves directory contains
test waves demonstration waves including 'hat'. These sounds were all
sampled at 20 kHz and each sample is a 2-byte word in little-endian
order (i.e. Dec and PC order). The bytes need to be reversed for
Sun, HP and SGI machines. The bin directory contains executable routines
and links to executable routines produced by the compilation.


Compile the source code using

      make  <machine>

where: <machine> = decstation | vax | sun | sungcc | hp | linux  
(For other options see: "Compiling the model - further details")
The file `gen' is the AIM program itself.


============================================================================

B. Running the model.


To verify that AIM is operational, move to the bin directory and type:

      gen -help

This should print general usage information on the standard output.


============================================================================

C. Setting Up the Environment Variables PATH and MANPATH.


The software is now ready. Before setting off, however, we recommend
that you

a) Set your PATH to include [aim_directory]/bin     
		(instructions in docs/aimPaths)
b) Set your MANPATH to include [aim_directory]/man  
		(instructions in docs/aimPaths)



============================================================================
 3.  COMPILING THE MODEL - FURTHER DETAILS.
============================================================================

In the root directory, the command "make help" prints a list of the
targets and parameters for compilation.  The machine-specific details
refer only to the location of the X11 libraries and header files on
the target machine.


============================================================================

A. X11 Libraries

The AIM graphics library is based upon X11, and the library (libX11.a) and
included header files (X11/X.h and X11/Xlib.h) are expected to be in
standard places. The command "make <machine>" assigns the paths usually used
on the particular machine.

For example, the command

      make decstation

assigns paths so that the following files are expected:

      /usr/lib/libX11.a
      /usr/include/X11/X.h
      /usr/include/X11/Xlib.h

If the X11 library and header files are in non-standard directories,
then the path for the directories can be given to the root makefile
using the parameters X11DIR (for the directory containing the files
files X11/X.h and X11/Xlib.h) and X11LIB (for the directory containing the
library libX11.a). These parameters override the default parameters assigned
for a particular machine.
For example decstation paths could also be assigned using:-

      make X11DIR=/usr/include  X11LIB=/usr/lib  [<machine>]

sun paths could also be assigned using:-

      make X11DIR=/usr/openwin/include  X11LIB=/usr/lib  [<machine>]

To see what the internal defaults are for a particular machine, type:

      make  TARGET=help  <machine>

This prints a complete list of the makefile targets, arguments, and defaults
on the standard output. The values of the arguments X11DIR and X11LIB are
the default paths associated with the specified machine.


============================================================================

B. Alternative compilers

The default compiler is the traditional C compiler cc.
Alternative compilers can be specified by giving the name of the compiler to
the root makefile, (assuming it exists in the current path).
For example, the GNU Project C compiler, gcc, is specified as follows,
(including it's -ansi flag, for compatability with ansi cc):

      make CC=gcc CFLAGS="-O -ansi"  <machine>

We find following produces code which runs significantly faster that the
traditional cc compiler:

      make CC=gcc CFLAGS=-O2  <machine>


============================================================================

C. A Note on Color Workstations

The AIM software X11 interface is designed for monochrome screens, and
not for multiplane color screens.  The software will run on a color
screen, except that when bitmaps are created they are the same depth
as the screen, since they are exact copies of the screen memory.
This also happens, for example, when the "animate" option is on, or
when the "xreview" program is used. The symptoms are a very slow
response time, and huge bitmap files.

There is a hidden option "mono=on" (short for "monochrome") which
forces the bitmap to be a single plane of the screen memory.  By
default, it copies plane 1; if this does not work, the plane can be
varied with the hidden option "planemask=<integer>".

Any queries to: <[e-mail]>



============================================================================
 4.  Next step after installing AIM.
============================================================================


When the installation is complete go to the 'bin' directory. It
contains the compiled programs and the user ReadMe file which is the
start point for the user documentation. bin/ReadMe provides an
overview of AIM, a set of demonstrations, an overview of the AIM
documentation, and PATH information.