****************************************************************************
                   SWIFT/HJS  --  TOOL and EXAMPLE DIRECTORY
****************************************************************************
Author : Herv Beust
Date   : January 10, 2003 

1 Contents of the directory
---------------------------

README : this file
Makefile : a makefile for the drivers supplied. Just type 'make <name>'
           if <name.f> is the name of the driver you want to compile.
gen_pl_hjs.f : a driver that creates the plhjs.in input file from 
               a simple output. See instructions below.
gen_ae_hjs.f : a driver that generates disks of particles orbiting
               various massive centers in the hierarchical system.
               See instructions below.
gen_pl_hjs_3.sh : a script input file for gen_pl_hjs.f that creates
                  the plhjs.in file for a triple system. Execute this
                  file. This 3-body system is designed to exhibit
                  a very strong Kozai resonance within ~130 years.
plhjs_3.in      : the corresponding file as generated by gen_pl_hjs.f
gen_pl_hjs_5.sh : Same as gen_pl_hjs_3.sh but for a more complex system
                  with 5 massive bodies.
plhjs_5.in      : the corresponding file as generated by gen_pl_hjs.f
gen_ae_hjs_3.sh : a script input file for gen_ae_hjs.f generating various
                  sets of test particles in the triple system listed above.
tphjs_3.in      : The resulting file
gen_ae_hjs_5.sh : Same as gen_ae_hjs_3.sh but for the 5-body system.
tphjs_5.in      : The resulting file
mvs_3.in, mvs_5.in : input files for swift_hjs for the two listed examples.
follow_hjs.f    : A driver that extracts the information about one orbit
                  or one particle from the simulation output. Adapted
                  from follow.f in the main SWIFT distribution.

2 Use of the drivers
--------------------

First compile the drivers gen_pl_hjs.f and gen_ae_hjs.f. The list of inputs
for gen_pl_hjs should have the following structure (see the examples
supplied):
- Coordinates used (1=AU and Years, 0=AU and Solar masses). Same as for SWIFT
- Plane information (1=invariable plane, 0= initila plane)
- nbod, number of bodies in the system (integer)
- nbod lines, each one containing the mass of the corresponding body
  in solar masses
- 2*(nbod-1) lines, for orbit information (nbod-1 orbits). For each orbit,
  the first line is made of 0's, 1's and -1's and describes the link between
  the orbit and the bodies (0=not concerned, 1=satellite,-1=center).
  See the README file in the root directory of the present distribution
  for the meaning of this line. The second line contains 6 reals describing
  the orbital elements of the orbit uneer consideration : Semi-major axis,
  eccentricity, inclination (degrees), longitude of node (degrees),
  argument of periastron (degrees), mean anomaly at beginning of simulation
  (degrees)
- The name of the resulting massive bodies input file (plhjs.in) for swift_hjs.

Note that in gen_pl_hjs.f, a test is made to check whether the hierarchical
structure defined by the nbod-1 orbits supplied is valid (see Beust 2003
for details). If this is not the case, then the resulting input file
is not generated.

The gen_ae_hjs driver is designed to generate the test particle input file
for swift_hjs. It is written here in such a way that is produces disks
of particles with given radial and vertical extensions around 
various subsets of the massive bodies. The input lines for this driver
are the following (see the examples supplied):
- Coordinates used (1=AU and Years, 0=AU and Solar masses). Same as for SWIFT
- Name of massive bodies input file (plhjs.in or similar) to work with
- a seed number for the random number generator
- Then, one or several series of 6 lines, each one corresponding 
  to one disk of randomly sorted particles orbiting some of the massive bodies
  of the system. For each set of particles, the 6 lines should
  have the following structure:
   1 - An integer : the number of particles to be sorted in that disk
   2 - a  line of nbod integers made of 0's and -1's, a -1 at rank i
       meaning that body#i should be considered as a center for that set
       of test particles (see details in the README file of the root
       directory of the present distribution)
   3 - Two reals: The lower and upper limits in orbital eccentricity
       for the randomly sorted test particles.
   4 - One real: The upper limit in inclination (degrees) for the particles.
       ==> Note that this inclination is given relative to the plane
           perpendicular to the angular momentum of the centers of the
           disk under consideration. This helps generating for example
           circumbinary disks. This is nevertheless valid if there is
           of course more than one center for that disk. Otherwize, the
           inclination is intended to refer to the same base plane as for
           the orbits between the massive bodies.
   5 - Two reals : the lower and upper limits in semi_major axis for
       the disk of particles to be sorted. 
   6 - One real : A power index that the randomly sorted semi-major axis
       distribution should follow. Set 0 for a uniform distribution.
- After all disks are given, a line with one 0 meaning that there
  are no additional particles.
- The name of the resulting test particle input file (tphjs.in or
  similar) for swift_hjs.

Here again, when a list of centers for particles is given, it is checked
whether the hierarchy rules are respected. If it is not the case, the
program stops. For example, consider a 4 body system made of two binaries
orbiting each other. Test particles may be added orbiting any of the
4 single bodies, or orbiting any of the two binaries, or orbiting
the whole system; but we may not give particles intended to orbit
the center or mass of one body of the first binary and one of
the second binary. The program will reject that proposition.


 
NOTE : These drivers are given as example tools, but the users are free
to modify them, or even to write totally new ones depending on their
needs. 

