*****************************************************************************
GLOBULAR - release v1.2 
           An educational/ fun simulation of the effects of gravity and other
           forces in space.

           This program is Freeware, subject to the distribution terms in the
           "Legal" section.
*****************************************************************************

-----------------------------------------------------------------------------
QUICK START------------------------------------------------------------------

Type

        globular
or
        globular /?

at the DOS prompt.

-----------------------------------------------------------------------------
LEGAL------------------------------------------------------------------------

This Document Copyright (C) 1998 Graeme Fenwick.
Program       Copyright (C) 1998 Graeme Fenwick.
Source Code   Copyright (C) 1998 Graeme Fenwick,
              except gl_inter.c, which is jointly-copyright with the
              author (unknown) of the original BASIC program.

The program, and its related files are freely distributable, subject
to the following conditions :-
        - This program may not be used as part of a commercial package, nor
          for any commercial purposes.
        - No charge may be made for distribution, beyond reasonable expenses
          incurred.
        - If the files are to be distributed separately, then adequate
          instructions on where to find the full package (comprising the
          executable program, all source files, and this documentation file)
          must be provided.
        - This documentation file may not be modified.

Modification, recompilation and redistribution of the source files is
permitted, subject to the following conditions :-
        - Any modifications are made explicit.
        - All copyright/ authorship notices and copyrights themselves remain
          intact, and may not be removed or altered.
        - All original executables, source code files, and documentation
          must be provided alongside in an unmodified form, or adequate
          instructions on how to obtain them provided.
        - These rules apply to any number of subsequent modifications.

Disclaimer: By using this program, you accept the following -
        - This Program is free of charge, and comes with no guarantees,
          or acceptance of liability whatsoever.
        - The author(s) do not accept any liability for damage incurred by
          its use.

-----------------------------------------------------------------------------
INTRO/ INSTRUCTIONS----------------------------------------------------------

        Depending on your point of view, this program is either a serious
(but lightweight) simulation of a spherical cluster of bodies in space, and
the ways in which they interact or... it's a glorified "fireworks" display!
The choice is yours. If any of the instructions seem unclear, the best way
to learn is to run the program with different parameters (globular /? for
a list) and see what effect they have.

        The program requires a 32-bit IBM PC compatible running either :-
                - MS-DOS (with a DPMI server installed), or
                - Windows 3.1, 95 or 98
It also needs VGA or better graphics (which covers most modern PCs). If
you're using Windows, the program can be started from any DOS prompt.
        Making sure you're in the correct directory, simple type "globular"
<return> to start with the default settings- easy, isn't it?!

As the program would be fairly limited with only the default settings, you
can override them using various switches:-

GLOBULAR [/E] [/P] [/T] [/N:x] [/M:x] [/R:x] [/D:x] [/Z:x] [/S:x] [/A:x]

  /E    Turns on the energy and time status displays. "Energy" is the total
        energy in the system, and "Time" is the "time" passed in the system
        (how fast this updates depends on processor speed, number of bodies,
        accuracy chosen, and so on). "Bad Energy Error" is derived from the
        original version of the program. As far as I can tell, this display
        sometimes appears when the energy calculations are unable to give
        accurate results (usually when two speeding bodies get very close).
        I usually ignore this!...
  /P    Selects point source display. By default, the program displays
        the bodies as spheres, with visible size.
  /T    Leaves Trails behind if you want to see the paths taken. This is off
        by default.
  /N:x  Number of Bodies in system.
  /M:x  Total Mass of System. Each body has Mass = total mass / no. bodies.
  /R:x  Running Time. This is in "real" seconds. After this time, the program
        will return you to the DOS prompt. (I've deliberately left the CTRL-C
        handler in, so you can use this combination of keys to quit the program
        at any point).
  /D:x  Viewing Distance from Globular Centre. The initial spherical
        distribution has a radius of 99, and anything closer than 2 units is
        "behind" you, so if you want to see everything (initially), 101 is
        approximately the lowest value you'll want. The further away you
        make this, the smaller everything appears.
  /Z:x  Apparent Size of Bodies. Normally, the program displays the size, as
        well as position of the bodies in perspective. If you want the bodies
        to appear larger without moving in closer, change this parameter. It
        has no effect on the mass, and does nothing if you have the "/p"
        switch selected.
  /S:x  The seed of the "random" number generator. The program always starts
        with 1 as the seed. Choosing a different value will give you a
        different distribution of bodies. The same seed will always produce
        the same initial distribution of bodies.
  /A:x  Accuracy of Timesteps. Smaller values produce more accurate results,
        but will result in the simulation running more slowly. Experiment
        with different values to see which are best for your computer.

Any incorrect switches or values will result in the user being given a
brief listing of the correct usage.
(Hints: For a less spectacular, but more stable simulation, try running the
program with a total mass of 1 (/M switch). For a longer simulation, 
increase the actual running time (/R switch). If the initial configuration
is too fast/ slow on your PC, experiment with the /A switch). 

-----------------------------------------------------------------------------
SOURCE CODE: DOCUMENTATION---------------------------------------------------

        This heart of this program is based on a BBC-BASIC listing I got my
hands on a few years ago, after a lecture hosted by the Dundee Astronomical
Society. The lecture itself was called something along the lines of "The
N-Body Problem" (the title related to the way that the number of computations
involved in simulating stellar clusters went up exponentially, leading to
serious computer power being needed). Unfortunately, I can't remember the
name of the person who actually gave the talk, or even if he was the person
who wrote the program (sorry!). As far as I know however, the original
listing is freely distributable, and it is from this that Globular's
interaction functions are partly derived.

        Globular was written in C using DJGPP (the MS-DOS port of the gcc
compiler) and the Allegro graphics libraries. Care was taken to ensure
that any non-ANSI C code was confined to the gl_gfx.c file. Hopefully this
will minimise any trouble in converting it to another system.
        The source files are as follows :-
        gl.h            Typedef for SETTINGS structure
        gl.c            Contains main() function, from which the program
                        is set up, and memory allocation dealt with.
        gl_arg.c        Functions dealing with command line
                        interpretation.
        gl_inter.c      Body set-up and interaction functions. All the code
                        derived from the original BASIC listing is here,
                        albeit in restructured/ modified form.
        gl_gfx.c        System specific graphics functions.
        all other .h    Prototypes for "public" functions in corresponding .c
                        files.

Additional Code Annotation:
        gl.c          - Pos(ition), Vel(ocity) and Frc(e) each have 3
                        components, in pseudo-array form.
                        Pos[n][0] is the x component of body no. n, and so
                        on.
                      - The memory allocation function allocates memory in
                        a pointer -> pointer -> (double) form, but pos, vel
                        and frc are passed as double ***, because we need to
                        modify the value in the calling environment.
                        It returns a 0 (failure) or a 1 (success), which
                        main() then deals with.
                      - **__crt0_glob_function(char *_arg) is included
                        to suppress UNIX-style "globbing" of any arguments.
                        (DJGPP is a port of a UNIX compiler, but this
                        behaviour is inappropriate for an MS-DOS program).
        gl_arg.c      - pint and pdbl are expected to hold positive values
                        scanned from arguments using argparse_numscan() in
                        the same file. A negative value means the program
                        could not read a suitable integer/ double value
                        following the current switch.
                      - I know the switch statement is inelegant, but it
                        works!
                      - Any invalid arguments result in info() being printed
                        out, with a "wrong" message.
                      - Calling info() automatically exits the program
                        immediately afterwards. Whether is returns a success/
                        fail value to the system depends on whether it is
                        called with 1 or 0 as the argument.
        gl_gfx.c      - There is a lot of Allegro/ DJGPP specific code in
                        this file, most of which you will have to change if
                        porting it.
                      - The object "screen" is defined elsewhere by Allegro
                        (i.e. it has external linkage).
        gl_inter.c    - I apologise if some parts of this file are unclear -
                        much of this it is derived from a program I didn't
                        entirely understand in the first place!
                      - Theta and phi are spherical polar angles.
                      - The array U[][] has something to do with being
                        vectors at right angles to the radius vector.
                      - Use of the SETTINGS structure variable cfg saves
                        passing each setting (except the number of bodies
                        n) separately.
                      - pe and ke are potential and kinetic energy.
                      - e is energy.
                      - dsqu (distance between bodies squared), r, and r3
                        are all related.
                      - Force is actually force per unit mass, or
                        acceleration.

-----------------------------------------------------------------------------
CREDIT-----------------------------------------------------------------------

Firstly, thanks go to the author of the original BASIC program, and
also to my Dad (Hi Dad! ;-)), as he was the one who obtained the
listing in the first place. (I really can't remember how old I was at the
time, but it was a few years ago now, I guess!). Thanks also go to DJ Delorie
(http://www.delorie.com/) for the DJGPP compiler, Shawn Hargreaves for the
Allegro libraries (http://www.talula.demon.co.uk/allegro), the Free
Software Foundation for the original gcc compiler, and everyone involved in
the development of the C language, ever....
Reckon that should just about cover things. :-)

-----------------------------------------------------------------------------
EMAIL------------------------------------------------------------------------

If you have any questions regarding the program, you can email me at
        gfenwick@primex.co.uk

Remember that it was never intended to be a heavyweight scientific
simulation, and for this reason, I've gone for ease of use (and programming)
over flexibility. Like the original, however, it does demonstrate the
principles involved (if you're into that sort of thing). It's also quite
pretty to look at (if you get the settings right), but that was *never* the
intention. Honest!

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


        

