                          MILC Version 7

This code was developed by the MILC collaboration for simulations of
SU3 lattice gauge theory on MIMD parallel machines.  This code is
publicly available for research purposes.  Publications of work
done using this code or derivatives of this code should acknowledge
this use.  Development of this code was supported in part by grants
from the US Department of Energy and National Science Foundation.
Use this code at your own risk.

Since this is our working code, it is continually in a state of
development.  We will informally support the code as best we can by
answering questions and fixing bugs.  We will be very grateful for
reports of problems and suggestions for improvements.  These may be
sent to 

   detar@physics.utah.edu.

      or 

   doug@klingon.physics.arizona.edu 


Target architectures:

Currently code is supposed to run on:
1. Any scalar machine ("vanilla" version)
2. Linux/Unix switched clusters via MPI
3. MPP GigE mesh architectures
4. QCDOC

Overview of the code:

Each "application", or major variant of the code, has its own
directory.  For example, the ks_imp_dyn applications directory,
contains code for simulating full QCD in the staggered fermion scheme.
The compilation requires code from the "libraries", "generic", and
"generic_ks" directories, as well as the "ks_dynamical" directory
itself.  All applications share the "libraries" directory containing
low-level stuff, and the "generic" directory containing high level
stuff that is more or less independent of the physics.  The various
staggered fermion applications share the "generic_ks" directory.
Examples of "generic" code are the random number routines, the lattice
layout routines, routines to evaluate the plaquette or Polyakov loop,
etc.  Of the shared code, only the libraries must be built separately
before building any application code.  Code in the various generic
directories is compiled automatically as needed, and should not be
compiled separately.

doc:  More detailed documentation of the code

libraries:	Low level routines and include files
	
	complex.h:	Definitions and macros for complex numbers
	su3.h		Definitions and macros for SU(3)
	complex.1.a 	Routines for complex numbers (single precision)
	complex.2.a 	Routines for complex numbers (double precision)
	su3.1.a		Routines for SU(3) operations (single precision)
	su3.2.a		Routines for SU(3) operations (double precision)

include:   Header files required by the code

generic: High level code for generic SU(3) simulation. The other
	directories, which are for real applications, should use 
	the routines in this directory where possible, otherwise 
	copy routines from this directory and modify them or write 
	new routines.

generic_ks:     High level code shared by staggered fermion applications.

generic_wilson:   High level code shared by Wilson fermion applications.


The remaining directories are "applications" directories.  Most of the
application code can be built in various ways, depending on the
requirements of the project.  For example, the ks_imp_dyn directory
contains code for simulating full QCD in the staggered fermion scheme.
This code can be built to use the "R", "phi", and hybrid Monte Carlo
algorithms, and may also include measurements of the hadron spectrum.
These variants are obtained by selecting the appropriate compilation
target, as indicated in the application Make_template file.

clover_dynamical
	Simulations with improved dynamical Wilson fermions.  Variants
	include the "R", "phi" and hybrid Monte Carlo updating
	algorithms.  Measurements include plaquette, Polyakof loop,
	psi-bar-psi and fermion energy and pressure.  Optional
	measurements include hadron spectrum, screening spectrum,
	axial current quark mass, and Landau gauge quark propagators.

clover_invert
        Calculation of meson and baryon propagators with improved
        Wilson fermions.

gluon_prop
        Calculation of the gluon propagator in a specific gauge and
        the nonperturbative renormalization of the vector and axial
        vector current.

ks_hl_spectrum
        Heavy-light meson spectrum

ks_imp_dyn:
	Simulations with dynamical Kogut-Susskind fermions.  Variants
	include the "R", "phi" and hybrid Monte Carlo updating
	algorithms.  Measurements include plaquette, Polyakov loop,
	psi-bar-psi, and fermions energy and pressure.  Optional
	measurements include hadron spectrum, screening spectrum,
	and some wave functions. (includes FFT routines in wave function)

ks_imp_invert_multi
        Calculation of multiple staggered propagators.  Writes them to
        files.  Calculates f_pi as well.

ks_imp_rhmc:
        Simulations as above, but using the rational hybrid Monte
        Carlo method.

pure_gauge
	Simulation of the pure gauge theory

schroed_cl_inv
        Schroedinger functional computations with improved Wilson
        fermions.

Each directory should contain a README file which gives some further
information.

How to build the code:

1. Start with the particular application on a particular machine and
   edit the Makefile according to instructions there.

2. Edit the libraries/Make_vanilla make file as needed.

3. Select a particular make target by consulting the Make_template file
   in the desired applications directory.

4. Sample input and output files are provided for each target.
   It is a good idea to run the compiled code with the sample input
   file and compare the results with the sample output.

Good luck!

References:

For documentation, see the directory doc.

Please also see the README files in various subdirectories.




