This directory contains the source code for VINE, which was written by
Andy Nelson, Markus Wetzstein and Thorsten Naab. This code is
distributed in a form that is known to compile and run with a variety
of common Fortran90/95 compilers. 

=========================================
Creating an executable
=========================================

The src directory contains all of the source code needed to compile
VINE, along with related makefiles and include files in their
own `INCLUDE' subdirectory.

The makefile in the src directory contains a variety of user settable
variables at its top, which turn on or off various options for the
code, causing them to compile or not for example. Depending on the
setting of the MACHINE variable, different sub-makefiles (in the
INCLUDE directory) are included in the main makefile. It is these
makefiles that you will probably want to modify or to add other
variants for your own architectures. 

Also, depending on which machine you use, you will need to create a
symbolic link between one specific hwinfo.<something> file and a 
`hwinfo' file (with no .<something> at the end). For example, to use
the hwinfo file specific to the Intel Itanium2 processor you would
do this at the command line:

ln -s hwinfo.itanium hwinfo

If you don't see a relevant hwinfo file in the INCLUDE directory,
then you will have to make another one based on the chip you plan 
to run on.

=========================================
ENDIANNESS
=========================================

Currently, the sub-makefiles include compiler options, such that
binary files are always converted to big endian. If you want to 
work with little endian binary files, then you must change the 
corresponding compiler switches in the sub-makefile you're using!

=========================================
Creating an initial condition
=========================================

The `init' directory contains a short program which can be used
to create input dumps for use in VINE. As noted there, the initial
condition currently in place is completely artificial. You will
have to replace it with conditions relevant for whatever system
you would like to simulate. 

=========================================
The `insph' file              
=========================================

The insph file is a file that is read in by VINE as one of its
first acts, before any real processing gets started. It contains
a variety of user settable parameters, which you will likely have
to modify for your problem and to which you may need to add your
own or other options.

In the doc directory, there is a file called insph.tex, which
briefly describes each of the lines in the insph file and what 
its purpose is.


=========================================
About the implementation language of vine
=========================================

The careful reader will notice that the supposedly fortran 95 (*) code
looks suspiciously like fortran 77 code. In fact, the code takes
advantage of almost none of the modern features of the language that
make the modern language a lot more useful, powerful and safer to use
than the older language version. There are several reasons for that.

First and most important is that most/all of astronomical fortran
users will be most familiar only with the f77 dialect of the language,
and because we would like people to use our code, it is important to
provide an environment that is at least for the most part friendly and
familiar. On the other hand, the tight binding to a language version
for which some vendors already have stopped shipping as a product
(e.g. the Sun f77 compiler is a script to call f95) and will continue
to deprecate more and more as time passes into the next decade or two,
is already partly broken. The code leap between f77 and f95 has
already been made (by us), so there is no fear-of-the-unknown excuse
for not using f95 as a language. Future development by others can take
advantage (or not) of the modern features quite incrementally,
starting from small and easy changes in various bits of the code.

Another reason is that, like many numerical codes, this code started
out before there was a fortran 90, let alone 95. We kept it as f77
during our later development and use essentially out of our own
inertia and resistance to change. It was converted to work with
the more modern features (modules mostly) relatively late in the
process. In order not to break too much, we didn't want to make huge,
wholescale structural changes to the code. You can do that later if
you choose, and in any case, they really aren't particularly
neccessary, since the code is very well optimized as it stands. 
Most likely, the next big change that will need to be made to the code
is whatever sort of language design issues that come up once multicore
and Cell processor-like things become common enough to worry about.
It is difficult at best to see how that will come together in the
future.

Finally, an important reason for not using one of the most commonly
discussed features of f90 (whole array operations like a=b+c were a,b
and c are arrays) is that we have a particle code, where whole arrays
may not be updated at the same time, only certain particles defined
within them.

(*) Note that f95 is essentially a `bugfix' of the f90 standard,
and so the two are indistinguishable for most users.

========================
Some useful information:
========================

o  This code packs several bits of information about each particle 
   into the same array, for efficient memory access and management.
   For example,
      posmas(1  ,i) refers to the x coordinate of particle i
      posmas(2  ,i) refers to the y coordinate of particle i
      posmas(3  ,i) refers to the z coordinate of particle i
      posmas(ims,i) refers to the mass of particle i (ims=ndim+1 by defn)

   similarly with velocity and several other variables. The
   principle is to put bits of information that are used at
   the same time (i.e. x, y, z) very close to each other in
   memory. The first array index in fortran is the `fast' one,
   so 1,2,3,ims are consecutive memory locations, and accessing
   one will almost inevitably bring the others into cache as
   a side effect, just in time to be used themselves.

o  The code packs information into arrays with SPH particles first,
   then Nbody particles. In other words

      posmas(1,1 . . . .npart_sph) refer to the x coordinate of
                                 sph particles 1...npart_sph

      posmas(1,npart_sph+1..npart) refer to the x coordinate of
                                 nbody particles npart_sph+1...npart


o  Individual time steps:

   The code packs information into the iactive arrays, fully
   active particles first, then 1/2 active, then inactive.
   In other words:

      i=iactive(1. . . . .nactivef)  refers to a particle needing a 
                                     full timestep update

      i=iactive(nactivef+1..nactive)  refers to a particle needing a 
                                      half timestep update

      i=iactive(nactive+1,npart)     refers to a particle needing 
                                      extrapolation only


For one step integrators, like the leapfrog in VINE, particles are
*only* on half steps, so there are no `full' timestep updates
according to the definition above.

