Utrecht branch of Eggleton's TWIN/STARS code

TERMS OF USE
------------
This code is based on Peter Eggleton's stellar evolution code and his terms
of use apply. In particular, you should cite one or more of the papers listed 
at the beginning of doc/writeup.ps in published work. In addition, you should
refer to papers describing enhancements made to the code in Utrecht where
relevant:
 * For thermohaline mixing:
   Stancliffe, Glebbeek, Izzard & Pols, 2007 A&A
 * For the OPAL 1996 opacity tables:
   Eldridge & Tout, 2004 MNRAS 348
 * For enhancements to the solver:
   Glebbeek, Pols & Hurley, 2008 A&A 
In addition, there are uses of the code where you might consider asking
Evert Glebbeek or other people from Utrecht University whether they would
like to be more closely involved in what you are doing and would like to
co-author any papers. At this time of writing and for this version of the
code, such usage include:
 * importing and evolving models of stellar mergers
 * using the code as a stellar evolution library embedded in another code
 * differential rotation and rotational mixing (experimental)
 * semiconvection
 * anything involving pair production/pair instability
 * using the radiative levitation option in the code

Contact one of us if in doubt.

INSTALLING - CMAKE
------------------
To install this code you need a FORTRAN-90 compatible FORTRAN compiler. A
plain FORTRAN 77 compiler will NOT work.
You will also need CMake and GNU Make.

The CMake script understands options for the ifort and GNU (gfortran)
compilers. If you want to use a different compiler, you'll need to edit the
compiler definitionsin cmake/CompilerFlags.cmake.

a) Preparations
---------------
Make sure you have CMake version 2.4 (or newer) installed on your machine.
You can test this by typing
 $ cmake --version
If you do not have CMake, download it from http://cmake.org/ or install it
using your system package manager (or get your friendly sysadmin to do it
for you).
It is generally best to keep the source tree "clean" and do a so-called
"out of source" build. Run
 $ mkdir Build
 $ cd Build
from the top-level stars/ directory.

b) Configuring
--------------
From the build directory, run
 $ ccmake ..
to launch the CMake interactive setup tool. Set the options you want (or
leave things at their default), then hit c (configure), g (generate).
Alternatively, type
 $ cmake ..
if you don't want to change any of the options and just want to accept the
default.

c) Compiling
------------
Again from the Build/ directory, run
 $ make
and wait for everything to compile.
If there are no problems, the executable "ev" should be placed in the
stars/code/ directory.

RUNNING THE CODE
----------------
Let us assume that you have "ev" in your path somewhere. In order to run,
ev needs to know three things: where to find its input files, what metallicity
to use (for the opacity tables and ZAMS library) and what basename to use for
your output. The easiest way to do this is to pass this information directly to
ev in the following way
  $ ev basename metallicity path-to-datafiles
For instance
  $ ev sun 02 $HOME/stars
See the top of the sourcefile code/aamain.f for a more detailed description.
In order to run, EV needs two files with settings, referred to here init.dat
and init.run. These names are mainly for backward compatibility with older
versions of the code. If these do not exist, it will fall back to basename.run 
and basename.dat, so multiple instances of the code can use the same directory
and you do not lose your original input files if you run a separate model in the
same directory. Using basename.run and basename.dat is recommended.

There are two formats for init.run and init.dat. The original (legacy) format
uses a matrix of numbers and can be found in the run/ directory tree. The newer
format can be found in the stars_standards/ tree. The code will accept either,
but some options can only be changed from their defaults with the new format.
For a description of the various parameters, see doc/iomanual.pdf or the Utrecht
STARS code Wiki (http://www.phys.uu.nl/~glebbeek/starswiki/bin/view).
The new format init files should include comments that describe the
different options.

THE TWIN CODE LIBRARY
---------------------
The current version of TWIN can be used in another project as a stellar
evolution library. This is still experimental at the moment!

Missing functionality:
   * Proper evaluation of stop conditions
   * No clean way to return the cause of code breakdown at the moment
   * The stand-alone version can work around the He flash, the library
     version does not and will just break down.
   * Binaries do not work. This is actually very easy to fix (at least for
     binaries evolved in TWIN mode).
   * More accessor functions for querying the evolutionary state of the star,
     getting convergence information or dumping the internal structure are
     needed.

