1) UNPACKING

To get started you need to copy the following tar files

code.tar.gz   32 Kbytes

and

data.tar.gz   21 Mbytes

Unpack using gunzip and tar.


code.tar should unpack to produce the following files:

rancat_ascii_example.f90   -example calling program
rancat_jswml.f90           -main subroutine that implements the algorithm
user_routines.f90          -routines that you will have to adapt to your data
cosmology.f90              -workhorse routines called by rancat_jswml()
histograms.f90
ran3.f90
rancat_subs.f90
zbrent_subs.f90

and

Makefile                  -unix Makefile


data.tar should unpack to create the following two directories with
the containing the ascii files listed.

TestData/catalogue.txt    -an input redshift catalogue


TestData_Copy/catalogue_out.txt  -augmented version of the input catalogue
              delta.txt          -overdensity as function of z
              iterations.txt     -iteration history
              LF.txt             -luminosity function
              rancat.txt         -the resulting random catalogue
                    All these are a copy of what the example routine
                    should produce.

-------------------------------------------------------------------

2) COMPILING and RUNNING

make rancat_ascii_example.exe 
     should compile the example program, but you may have to set the
     name of the compiler and your choice of flags in the Makefile


Executing rancat_ascii_example.exe
    should cause the example data to be read from TestData/catalogue.txt
    the program then calls the main subroutine in rancat_jswml.f90
    and writes the output files catalogue_out.txt,delta.txt,iterations.txt,
    LF.txt and rancat.txt to TestData. These should be equivalent (modulo the
    effects of rouding errors) to those provided in TestData_Copy


In this example all the input and output files are simple ASCII files
though I recommend you modify the code to work with your preferred data 
format.

----------------------------------------------------------------------

3) INPUT and OUTPUT

Some commentary will be written to stnderr and stndout. This can be controlled
with the VERBOSITY flag set in the calling program.
   The code is set up to do the full parameter fitting with floating
number and density evolution parameters. However very tight priors have
been set in this quick example.

TestData/catalogue.txt: This input catalogue is a simple ASCII file 
  specifying the magnitude and redshift limits of the catalogue along with
  the apparent magnitudes and redshifts of the objects in the catalogue.

TestData/catalogue_out.txt: Is of similar format to the input catalogue
  but now contains additional derived properties of the objects such
  as absolute magnitudes and distance moduli.

TestData/rancat.txt: Is again of similar format but this is random
 catalogue and (by default) contains 10 times as many objects than 
 the original. Its header also contains information on the cosmological
 parameters used etc.
   Rounding errors will probably result in different sequences of 
 random numbers and so this catalogue should not be expected to be
 identical to the specimen in TestData_Copy. However it should be
 statistically equivalent, eg have the same redshift distribution
 galaxy number counts etc.

TestData/LF.txt: A tabulated estimate of the luminosity function.

TestData/delta.txt : A tabulated estimate of the overdensity with redshift

TestData/iterations.txt : A tabulated record of the iteration history
  listing the values of the evolution parameters u and a the
  normalization parameter mu and the corresponding posterior 
  probability  P_post

              
----------------------------------------------------------------------

4) ADVANCED USE           (i.e. using the code to do something useful)

To adapt the code to work with your own data in a different observational
band and with more and varied galaxy attributes you will have to edit two
of the source code files (both are quite well documented).


user_routines.f90: Please see the header of this file for a full
  explanation, but in short the routines in this file are the ones you
  will have to modify to specify the functional form of the k- and 
  e-corrections appropriate for your data, the functional form of the
  density evolution model, the list of data properties you have for
  each galaxy and how each transforms with redshift.


rancat_ascii_example.f90:
       This routine sets parameters, reads your data, calls the main
   code (the routine in rancat_jswml.f90) and writes out the ouput.

   The documentation in this source file explains what to do, but in short
   you set parameters to specify your priors on the evolution parameters,
   edit the code to read in your data catalogue, including all the properties
   of the galaxies you want reproduced in the output random catalogue, and
   modify the output to write these to the output catalogue.