
Ifeffit Installation Instructions
=================================

This file describes building and installing Ifeffit from source code on
Unix and Unix-like systems.  The essential steps are:

  1. Download and unpack the distribution file.
  2. Install PGPLOT with PGPLOT_install (see README.PGPLOT)
     
         Note that precompiled binary package for PGPLOT will NOT work.  
         You MUST install PGPLOT with PGPLOT_install. 

  3. Configure the building procedure for ifeffit for your system, 
     specifying whether to use PGPLOT graphics, where to install 
     the package, and which of the optional interfaces for Python, 
     Perl, and Tcl to install.
  4. Build the Ifeffit library and executable programs.
  5. Install the library and executables.
  6. Build and Install optional wrappers for perl and python, 
     and their associated scripts.
  7. Post-Installation configuration.

At it's simplest, the process will look something like this:

 ~> <verify that PGPLOT is installed>

 ~> <get http://cars9.uchicago.edu/~ifeffit/src/ifeffit.tar.gz>
 ~> gunzip -c ifeffit.tar.gz | tar xf -
 ~> cd ifeffit-1.2.10
 ~> ./configure
 ~> make
 ~> make install


The first If you have not already installed PGPLOT for IFEFFIT, you'll 
need to install it __BEFORE__ configuring Ifeffit.

 ~> ./PGPLOT_install 


-------------------------------------
Special Note on Root/Non-Root access:
-------------------------------------

If you have root access to the system you're installing Ifeffit on, I
recommend doing all installation steps as root.  If you're an old pro
at installing Unix software or particularly paranoid about doing things
as root, the configure and make steps above can be done as a non-root
user.  If you do not have root access to the machine you're installing
Ifeffit on, pay particular attention to the '--prefix' arguments to the
'PGPLOT_install' and 'configure' steps below, as you'll need write access
to these directories.

Note that both 'configure' and 'PGPLOT_install' take a '--prefix'
argument.  The default for each is '/usr/local'.   If you need to change
this, it is recommended that you use the same value for both installation
scripts.


More detailed instructions follow. 

1. Download and Unpack the Ifeffit tar file
-------------------------------------------
The Ifeffit source distribution is available from
  http://cars9.uchicago.edu/ifeffit/

Download the latest source kit, and unpack it:
   ~> gunzip -c ifeffit.tar.gz | tar xf -
   ~> cd ifeffit-1.2.7

If your system does not have gunzip, you may need to install it.

2. Install and Configure the PGPLOT library
-------------------------------------------
Ifeffit uses the PGPLOT library for plotting graphics.  This is a
separate package that must be installed before building Ifeffit.  The
Ifeffit configuration process (step 3) must be able to find the
installed PGPLOT library, or else Ifeffit will be built without
plotting graphics (everything else will still work).

If you are upgrading from an earlier version of Ifeffit, there should
be no need to re-install the PGPLOT library.

The PGPLOT library is not bundled with or distributed with the Ifeffit
distribution, and you must download it yourself. PGPLOT can be found
at http://astro.caltech.edu/~tjp/pgplot/

The PGPLOT_install shell script included with Ifeffit will attempt to
download and install the package for you.  This script assumes the
final location of the PGPLOT library will be
/usr/local/share/ifeffit/pgplot.  It assumes to be running as root, and
presumes a linux system.  It may work for other cases, but has not been
fully tested.  To use this script, type 
  ~> ./PGPLOT_install

PGPLOT_install assumes you want to install the PGPLOT library to
/usr/local/pgplot, which probably requires the installation to be 
done as root.  To install the PGPLOT library in another location,
you can specify the installation directory explicitly:

  ~> ./PGPLOT_install --prefix=/home/me/pgplot

Further details can be found in README.PGPLOT. 

You can also do a manual installation of PGPLOT, following the PGPLOT
installation instructions in install-unix.txt carefully.  This will
work on most Unix systems, but is not the simplest installation.
Please consult the README.PGPLOT file in the Ifeffit distribution for
more details.

I'd like the ./PGPLOT_install script to work for everyone, so if you 
have problems with it, please consult me.


3. Configure the building procedure for your system
--------------------------------------------------
Type './configure', or 'sh configure'.

Configure takes several options.  The most important are:
 
   --prefix
   --with-arraysize=[small,medium,large]
   --with-pgplot / --without-pgplot
   --with-fortran=name of fortran compiler
  
The full set of options can be listed with './configure --help'
 
== --prefix

The --prefix option specifies which directory should be used to install
the Ifeffit package.  By default, the prefix is /usr/local, which will
install executable programs (ifeffit, autobk, and possibly gifeffit) in
/usr/local/bin, and ifeffit data files to /usr/local/share/ifeffit.

== --with-arraysize=[tiny,small,medium,large]

This switch sets the largest array size (ie, number of elements) in the
ifeffit library.  Since ifeffit is written in statically-typed Fortran,
this upper limit is fixed when the library is built.  This limit directly
effects the amount of memory needed to run the program.  Currently the
values for arraysize and the corresponding maximum array size are:
    tiny     2048 point arrays 
    small    4096 point arrays 
    medium   8192 point arrays
    large   16384 point arrays

The default is currently '--with-arraysize=medium '.  This will cause the
command-line version to occupy up to ~20Mb of memory while running.  For
machines with less than 64Mb of RAM, it may be necessary to modify the
default size.  For most EXAFS analysis problems, arrays of size 2048 are
plenty long enough, and using '--with-arraysize=tiny' will be adequate.
For some analyses, particularly DAFS-related, using larger arrays is
better, and sometimes it's just convenient to be able to use much larger
arrays.  For machines with more that 128Mb of RAM, I've not seen any
problems with '--with-arraysize=large'.
  

== --with-fortran=[gfortran g77 g95 f77 xlf]

Specify the fortran compiler to use to build Ifeffit.  Note that under
normal circumstances, this must be the same one used to build PGPLOT.
Use the --with-fortran option with PGPLOT_Install if the one automatically
found is not the right one.

This option is provided because some early versions of gfortran (even in
the 4.0 and 4.1 series) have some problems, though may be the only 
fortran compiler installed on some linux systems. 

== --with-pgplot, --without-pgplot, --with-pgplot-link

These options tell the configuration script:
  --with-pgplot=/dir        location of the PGPLOT directory
  --without-pgplot          do not use PGPLOT, no graphics version.
  --with-pgplot-link='L...' exactly how to link with the PGPLOT lib.

If the PGPLOT library has been installed using PGPLOT_install, there
should be no need to explicitly set any of these. 

The --with-pgplot option specifies the location of the PGPLOT
library file, libpgplot_iff.a.  You can explicitly specify the location
like this:  
  --with-pgplot=/usr/local/share/ifeffit/pgplot/

You can also explicitly tell Ifeffit to build _without_ the PGPLOT
library, by saying
  --without-pgplot

You can also fully specify how the linker should link to the PGPLOT library
with something like

  --with-pgplot-link='-L/usr/local/share/ifeffit/pgplot -lpgplot_iff -lpng -lz -L/usr/X11R6/lib -lX11'

This should not be necessary. 

The Ifeffit configuration will look for PGPLOT and try to determine how to
use it.  See README.PGPLOT for more details, or run the shell script
   iconf_pgplot

to find out how Ifeffit will think PGPLOT is configured on your system.

4. Build the Ifeffit library and executable programs
----------------------------------------------------
Type 'make'.  

This will build the ifeffit library, a simple command-line interface,
and the latest versions of autobk, feffit, and diffkk.

5. Install the Package
----------------------
Type 'make install'.  

This will install the following files, using 'prefix' as specified during
configuration (/usr/local/ by default):

  prefix/bin/ 
             ifeffit            - interactive, command-line program
             autobk             - XAFS background removal program
             feffit             - XAFS fitting program
             feff6l             - ab initio XAFS calculation program
             diffkk             - convert XAFS to anomalous scattering
                                  factors
  prefix/lib/
             libifeffit.a       - main Ifeffit library
             libnopgplot.a      - dummy PGPLOT library
  prefix/include
             ifeffit.h          - header for C interfaces
  prefix/share/ifeffit/
             startup.iff        - system-wide ifeffit startup file
             config/ifeffit.h   - header for C interfaces
             config/Makefile.PL - Perl Makefile.PL 
             config/setup.py    - Python Setup file
             config/TclSetup.in - Tcl Setup and Build instructions
             config/Config.mak  - description of libraries to use
                                  to build with the current configuration 
                                  suitable for Makefile
             cldata/*.dat       - data files for Cromer-Libermann 
                                  f' and f'' data
             fefftab/*.dat      - data files for Feff Tables
             pgplot/            - pgplot installation directory



6. Building and Installing the Optional Wrappers for Python, Perl, and Tcl
-----------------------------------------------------------------------

The scripting-language wrappers for the Ifeffit library are useful for
developing high-level applications.  Even if you aren't planning on using
them directly, you may want to use some application that requires one of
these wrappers, including the several GUIs that exist for Ifeffit.

All the files needed to build each of the wrappers should be under the
wrapper directory: wrapper/perl, wrapper/python, and wrapper/tcl.

These extensions are not automatically built with ifeffit, and must be
built after Ifeffit is installed.  Please copy the appropriate
configuration file generated during the Ifeffit build and installed into
$prefix/share/ifeffit/config.

6.1  Python wrapper

  This will install the Python interface to Ifeffit, and gifeffit, a GUI
  program. It is assumed that python 1.52 or higher is installed on your
  system, and that the Tkinter module is installed:
  
    ~>cd wrappers/python
    ~>cp $prefix/share/ifeffit/config/setup.py .
    ~>python setup.py install

  Some pre-installed versions of python on some linux distributions do not
  come with enough python development tools to build extensions.  For such
  cases (RedHat6.1, I believe), you should find and install the
  'python-dev' package, or build python from sources.

6.2  Perl wrapper

  This will install the Perl interface to Ifeffit, but not any of the perl
  applications such as Athena, Atoms, or Artemis.  Please get those from
  Bruce Ravel's website.  It is assumed that perl5.003 or higher is
  installed:

    ~>cd wrappers/perl
    ~>cp $prefix/share/ifeffit/config/Makefile.PL .
    ~>perl Makefile.PL ; make ; make install

6.3  Tcl wrapper

  The tcl wrapper can be built like this:

    ~>cd wrappers/tcl
    ~>cp $prefix/share/ifeffit/config/TclSetup.in .
    ~>sh Build

  I don't know of a standard way to install Tcl modules...

7. Post-Installation Customization
----------------------------------------------------
Once Ifeffit is installed, you [as a normal, non-root user] should be able
to run the command-line program ifeffit, and (if installed) the GUI
gifeffit.  There are a few customizations you may want to perform.

You'll probably want to put these in your startup file (.cshrc for csh,
.profile or .bashrc for bash). 

By default, the 'X Server' PGPLOT graphics device is used. This creates a
persistent PGPLOT window that remains after you exit ifeffit, and can be
used in later ifeffit sessions.  If you'd prefer a graphics window that
goes away as soon as you exit the program, you can set the environmental
variable PGPLOT_DEV to '/xwin'.  If you're using csh shell, this looks like 
  ~> setenv PGPLOT_DEV /xwin
for bash, the syntax is
  ~> export PGPLOT_DEV=/xwin

If you would like to pre-define some ifeffit macros, put them in the file
.ifeffit in your home directory.  This file will be 'load'ed at startup,
just after the system-wide macros (from ....share/ifeffit/startup.iff as
installed above).



---------------
Test Procedures
---------------
(Currently a work-in-progress)

The test programs src/test/ifftest1 and src/test/ifftest2 are designed to
test the core functionality of the ifeffit library and interpreter and the
ability to use the library from Fortran and C programs.  These tests should
be run from the src/test directory, and will report success and failure of
the primitive functionality.

The programs do not test of the reasonableness of backgrounds generated by
the spline command, and so on, only if the interpreter and commands can be
executed without error.

In addition to these compiled test programs, the examples in the examples/
directory provide a means of testing the 'reasonableness' of the behavior
of Ifeffit. 


--Matt Newville <newville@cars.uchicago.edu>

Last update Mar-31-2005
