








                                    GRAVITY 1.2



                       Copyright (c) 1994 Jens Jorgen Nielsen



       Congratulations! You now have an evaluation  copy of GRAVITY 1.2,  a
       fun and easy to use educational celestial mechanics program.

       GRAVITY is copyrighted material. You  are granted permission to  use
       GRAVITY 1.2, and to make as many backup copies for your own purposes
       as you want.  You are  encouraged to distribute  copies of  GRAVITY,
       subject to the following conditions:

       1) All files are distributed together and unaltered.
       2) No charge is made for the software.



       WHAT IS GRAVITY

       Gravity is the force  of attraction that governs  the motion of  all
       larger objects  in  the Universe,  e.g.  moons, planets,  stars  and
       comets.  It  was  formulated  by  Newton  as  the  law   of  general
       gravitation :

                               F = k * m * M / (r*r).

       In words it states :

       "Two bodies attract each other with a force that is  proportional to
       the mass of each body and is inversely proportional to the square of
       their distance apart."

       If more than two bodies are involved, then every body attracts every
       other body according to the law of general gravitation. Applying the
       rule of superposition  the resulting  force on  one of  them can  be
       obtained by  adding the  force experienced  from each  of the  other
       bodies.












                                                                           1






       ABOUT THE PROGRAM

       GRAVITY is capable of simulating the motion of bodies, which attract
       each other according to the law of general gravitation in  the three
       dimensional space.

       Input to GRAVITY is  a description of what  the Universe looks  like
       just before simulation begins. The  initial "State of the  Universe"
       is completely specified in an easy to read text file supplied by the
       user when the program is started.

       Several sample  files  are  available, but  try  creating  your  own
       private Universe and observe how it evolves. This is what  is really
       exciting about using GRAVITY.

       During simulation the motion of each  of the bodies in the  Universe
       is shown as a moving dot or as a line on the  screen. Several vision
       modes are available.

       Also during simulation it is possible  to move around the  perimeter
       of the  Universe  using the  arrow  keys, thereby  viewing  it  from
       different angles.



       USING THE PROGRAM

       The program is started from the DOS prompt, e.g.:

          C:> GRAVITY PLANETS.BDY

       The second parameter on the command line, in this  case PLANETS.BDY,
       refers to  a  text  file  specifying the  start  conditions  of  the
       Universe to be simulated. The exact format of this file is described
       below.

       Simulation proceeds immediately after  the start condition file  has
       been read. During simulation several keys are active :

          Left arrow  : Move your point of view 5 degrees to the left.
          Right arrow : Move your point of view 5 degrees to the right.
          Up arrow    : Move your point of view 5 degrees up.
          Down arrow  : Move your point of view 5 degrees down.

          1 : Vision mode 1. Custom colouring as specified in .BDY file.
          2 : Vision mode 2. Grey scale showing depth.
          3 : Vision mode 3. 3D using red/green stereogram.

          Other keys  : Stop simulation.







                                                                           2






       In vision mode 1  the bodies have the  colour specified in the  .BDY
       file. This mode is very useful  when the motion of specific  objects
       is observed.

       Vision mode 2 visualises the third dimension using the  intensity of
       the dot on a grey scale.  The brighter the object the closer  to the
       viewer it is. With a  little practice you will  be able to see  some
       depth in the picture.

       Vision mode 3 presents a red/green stereogram. When viewed through a
       pair of coloured glasses,  red for the right  eye and green for  the
       left eye,  the feeling  of bodies  moving in  space is  surprisingly
       real.

       When the simulation is stopped the  current "state of the  Universe"
       is saved in  a file named  EXIT.BDY. GRAVITY uses  this file as  its
       input if no other filename is specified.







































                                                                           3






       EXAMPLES

       A number of .BDY files, each  describing a "universe", are  supplied
       with GRAVITY. They demonstrate some of the possibilities of GRAVITY.

        4STARS.BDY     Four celestial objects with equal mass. Position  and
                       velocity is symmetrical.

        8STARS.BDY     Same as  4STARS.BDY but  with 4  more objects  added.
                       This example reminds me of "les lanciers", a dance  I
                       practised at  high school  (especially when  a  small
                       error causes total chaos).

        MOON.BDY       A system  with a  light object  (moon) circulating  a
                       heavy object  (planet) which  is circulating  a  very
                       heavy object (sun). This example uses vision mode  2,
                       where  grey   scale   coding  is   used   for   depth
                       visualisation.

        PLANETS.BDY    This system  with four  heavy objects  circulating  a
                       very heavy  object is  a (very)  rough model  of  our
                       solar system (Sun, Mercury, Venus, Earth, Mars).

        2PLUS1.BDY     One planet is circulating a double star system.  Note
                       the very aperiodic but still stable behaviour of  the
                       planet.

        LAGRANGE.BDY   The famous  stable lagrange  points are  demonstrated
                       with an  object  (Moon) circulating  a  heavy  object
                       (Earth).  A  number  of  massless  particles   (dust)
                       initially follow  the same  trajectory as  the  Moon.
                       After some time the  location of the lagrange  points
                       becomes evident.

        CLASH.BDY      Two groups, each comprising 100 stars of equal  mass,
                       clash. Although operating in vision mode 2 the  arrow
                       keys give a great 3D feeling of what is going on.

        3D.BDY         This example  showing  41 objects  with  equal  mass,
                       initially  distributed  on  a  sphere,   demonstrates
                       vision  mode  3,  the  three  dimensional   red/green
                       stereogram mode.  A  pair  of  coloured  glasses  are
                       highly recommended in order  to enjoy the 3D  effect.
                       Try the arrow keys.

        INTRUDER.BDY   This is a  model of  a galaxy. A  number of  massless
                       objects (stars) are circulating  a very heavy  object
                       (centre of galaxy). Another very heavy object  passes
                       by  at  a  high  speed  (another  galaxy).  Red/green
                       glasses are highly recommended.






                                                                           4






       SPECIFYING A UNIVERSE

       The initial "State  of the  Universe" is completely  specified in  a
       text file supplied  by the user  when the program  is started.  Also
       specified in this file  are a number  of parameters controlling  the
       simulation and selecting the vision mode.

       The file consists  of a  special first  line containing  information
       common to all bodies, followed by a number of lines  each describing
       the state of a specific body in the Universe.

       The format of the first line is :

         <timeSlice> <graviConst> <viewMode> <obsDist> <softening>

       The format of the following lines is :

         <mass> <x1> <x2> <x3> <v1> <v2> <v3> <colour> <dotLine>

       For implementation purposes the number of bodies is limited  to max.
       8095. You  will  probably  never experience  this  limitation  as  a
       problem, because the simulation proceeds very slowly when the number
       of bodies is that large.

       The parameters have no dimensions,  meaning that no particular  unit
       of time is assumed for the timeSlice parameter. The same is true for
       the other parameters such as mass, distance and velocity.

         Parameter    Format  Example   Comment

         timeSlice    float    0.0001   Time between iterations.
         graviConst   float    1000.0   Natural constant.
         viewMode     integer       2   Vision mode, see above.
         obsDist      float    3000.0   Eye distance from screen.
         softening    float       1.0   Numerical softening, see below.

         mass         float    1000.0   Mass of the body.
         x1           float    -100.0   Position, horisontal.
         x2           float     100.0   Position, vertical.
         x3           float    -100.0   Position, depth.
         v1           float     100.0   Velocity, horizontal.
         v2           float    -100.0   Velocity, vertical.
         v3           float     100.0   Velocity, depth.
         colour       integer      15   Colour of the body, 0-15.
         dotLine      integer       0   Dot or line flag (0 or 1).











                                                                           5






       The timeSlice  parameter  determines  the  step  size  used  in  the
       simulation. In order to  work properly the step  size must be  lower
       than a  certain level,  which  depends on  the  value of  the  other
       parameters.

       The  graviConst   parameter   corresponds   to   the   constant   of
       proportionality, k, of Newton's law of general gravitation.

       The obsDist specifies the distance of  the observer's eyes from  the
       screen. This parameter is used only in Vision Mode 3. As  the screen
       is approx. 600 units wide, a proper value is in the range of 2000 to
       3000.

       Softening is a  parameter that helps  the simulator avoid  numerical
       instability. As two bodies get very close to each other the force of
       attraction between them gets very large  with the result that  large
       errors are introduced to the simulation.  This problem is solved  by
       limiting the numerical value of the  attractional force in a  smooth
       manner. If  a  value of  1  is  chosen, the  limiting  only  becomes
       effective when two bodies get very  close to each other (distance  <
       1).

       Mass is the weight of the body.

       The position of the body is specified using x1, x2 and x3.  In order
       to be within the limit of the screen, the values of x1 and x2 should
       be in the range of  -250 to 250. No  two bodies must occupy  exactly
       the same position in space. The velocity is specified by v1,  v2 and
       v3.

       The colour parameter is used in  vision mode 1. It ranges from  0 to
       15. Depending on the dotLine  parameter a dot (0)  or a line (1)  is
       drawn.

       An easy way to get familiar with the file format is to try modifying
       one of the .BDY files supplied with GRAVITY.




















                                                                           6






       HINTS

       *   With the coloured  transparent film  normally used for  overhead
           projectors, you can manufacture a very cheap and  efficient pair
           of red/green glasses  for the 3D  stereogram mode. You  probably
           have to experiment a little with the number of layers, but  4 to
           6 layers worked quite well for me.

       *   If the number of bodies, N, is large, the simulation tends to be
           very slow. The reason is that  the number of body pairs  is N(N-
           1), meaning  that if  N  is doubled,  the  time needed  for  one
           iteration is almost multiplied by 4.

       *   When simulating  e.g.  colliding  galaxies a  few  heavy  bodies
           dominate the gravitational field. In such a case you  should set
           the mass of as many bodies as possible to zero,  because GRAVITY
           actually skips the time consuming calculations for all  pairs of
           massless bodies.

       *   If the bodies of your Universe leaves the screen soon  after you
           start your simulation, you should make sure that the momentum of
           the entire system is zero or close to zero.



       Comments, questions and suggestions are  welcomed. If you create  an
       interesting universe dont hesitate to e-mail it to me.



       Have Fun

       Jens Jorgen Nielsen
       Studsgaardsgade 48
       DK-2100 Copenhagen East
       DENMARK

       e-mail :  jjn@login.dknet.dk


















                                                                           7
