home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine 1995 / ARCHIVE95.iso / discs / shareware / share_47 / orbits / !orbits / Doc < prev    next >
Text File  |  1991-11-24  |  10KB  |  195 lines
  1.                                    Orbits
  2.                                    ------
  3.  
  4.        A many body orbital mechanics simulation for RISC OS computers.
  5.  
  6.                               By Neil Hoggarth.
  7.  
  8. Introduction
  9. ------------
  10.         Orbits simulates the movement of an arbitary number of objects under
  11. the effects of their mutual gravitational attraction. The main program
  12. itself takes control of the machine for the duration of the run. However a
  13. multitasking desktop front end is provided so that the program can be
  14. started and controlled from within the desktop environment. The program is
  15. Public Domain and may be copyed subject to certain conditions. Please see
  16. the section "Copying" below and the license agreement.
  17.  
  18. Running the program
  19. -------------------
  20.         The program is started by double clicking the !Orbits application
  21. directory in the normal way. An Orbits icon is installed on the icon bar.
  22. The icon menu has six options.
  23.  
  24.         Info    - displays the usual 'information about program' box.
  25.         Intro   - displays this file in a text window.
  26.         License - displays the program's license conditions in a text
  27.                   window.
  28.         Trail   - selectable option. When this is ticked the bodies in the
  29.                   simulation leave a trail behind them, marking out the
  30.                   orbit.
  31.         Input   - opens a filer window for the sub-directory containing the
  32.                   example input files.
  33.         Quit    - terminates the program.
  34.  
  35.         A simulation is started by draging a text file with the appropriate
  36. format to the Orbits icon. The simulation program then takes over the
  37. machine for the duration of the simulation. Whilst the program is running
  38. the following control keys can be used.
  39.  
  40.         f1      - toggle the trail option on/off.
  41.         f2      - clear the screen. This is useful if the screen has become
  42.                   cluttered with orbit trails.
  43.         f12     - terminate simulation.
  44.  
  45.         The simulation runs until the user presses f12, after which it stops
  46. and the computer returns to the desktop environment.
  47.  
  48. Input format
  49. ------------
  50.         The simulation operates on a series of "bodies". Each body has
  51. the following attributes.
  52.  
  53.         mass
  54.         position ("x" and "y" co-ordinates)
  55.         velocity (rate of change of "x" and rate of change of "y")
  56.  
  57.         The co-ordinate system used is the same as the graphics co-ordinate
  58. system used by BBC BASIC but with the origin (the 0,0 point) shifted into
  59. the middle of the screen. Co-ordinate 0,0 is in the centre, the x axis runs
  60. horizontally from -640 on the left hand edge to +640 on the right and the y
  61. axis runs vertically from -512 at the bottom edge to +512 at the top.
  62. Hopefully the following diagram makes this clear (co-ordinates are given as
  63. x,y).
  64.  
  65.   -640, 512 --------------------  0,512 -------------------------  640, 512
  66.       |                                                               |
  67.       |                                                               |
  68.       |                                                               |
  69.       |                                                               |
  70.       |                                                               |
  71.   -640, 0                          0,0                             640, 0
  72.       |                                                               |
  73.       |                                                               |
  74.       |                                                               |
  75.       |                                                               |
  76.       |                                                               |
  77.    -640,-512 --------------------  0,512 -------------------------  640,-512
  78.  
  79. Bodies can be outside of the co-ordinate ranges given, but thay will no
  80. appear on the screen.
  81.  
  82.         Input files consist of a series of lines, each one of which is the
  83. specification of a body. These take the following form.
  84.  
  85.       mass / x , y / rate-of-change-of-x , rate-of-change-of-y
  86.  
  87. The properties are specified as decimal numbers. The "/" and "," punctuation
  88. is required. The "rate-of-change-of..." properties state how many pixels the
  89. body is shifted by in the relevent direction each time the simulator runs
  90. through its main loop and therefore govern how quickly the body moves
  91. around. If you violate the input format the program responds with the (not
  92. very helpful!) error message "parse error at line xxxx".
  93.  
  94.         Comments can be introduced using a "#" character. Everything from a
  95. "#" to the end of a line is treated as a comment and is ignored. Blank lines
  96. are also allowed.
  97.  
  98.         A number of example input files (with comments) are provided and
  99. studying these is proberbly the best way to get a feel for the sizes of
  100. parameter which work. These are supplied in a sub-directory 'input'. A
  101. filer window for this directory can be opened by clicking on "Input" in the
  102. main icon bar menu.
  103.  
  104. Running from the command line
  105. -----------------------------
  106.         Although the casual user does not need to know it, the application
  107. actually consists of two programs. "!RunImage" is the multitasking front end
  108. and "orbits" is the simulation. The !RunImage program invokes orbits in
  109. response to the user draging an input file to the icon. If you are the sort
  110. of person who doesn't like windows, desktops and rodents then you can use
  111. the orbits program directly. Simply copy "orbits" out of the application
  112. directory into your normal "library" directory. You can now use "orbits" as
  113. a command from the "*" prompt.
  114.  
  115.         *orbits [-t] [-h] [<input file>]
  116.  
  117.         The -t switch indicates that the program should trail orbits. The -h
  118. switch causes the program to print a short help message. If the name of an
  119. input file is omitted the program attempts to read from the standard input,
  120. usualy the keyboard. Terminate keyboard input by typing <CTRL>-D.
  121.  
  122. Bugs
  123. ----
  124.         The simulation is non-relativistic. Anyone who understands the
  125. General Theory is invited to rectify this and then explain to me how it
  126. works!
  127.         In the real universe (on the scale we are interested in!) time and
  128. space are continuous things. Unfortunatly the simulation runs in discrete
  129. steps. This has no major effect most of the time. However I am effectively
  130. making the assumption that each time the simulator moves on a step things
  131. don't change very much. This falls down when bodies get very close to each
  132. other. In such cases the gravitational gradiant can change very sharply. If
  133. two bodies pass very close together they get a massive kick due to the
  134. inverse square law. By the next discrete time interval they are far appart
  135. again and so only weakly interact. The result of this is that when two
  136. bodies almost collide then they tend to fly off at high speed never to be
  137. seen again. Similarly if a body orbits another and the low point of its
  138. orbit is very low then the orbit is distorted.
  139.  
  140. Notes to programmers
  141. --------------------
  142.         The programs are written in C language and the source files are
  143. distributed within the application directory. The programs were developed
  144. with release 4 of the Acorn ANSI C compiler and have been tested with both
  145. release 3 and release 4 (supplied with Desktop C). The module "c.RunImage"
  146. makes a call to RISC_OSlib which is only supported by release 4. You
  147. therefore require Desktop C to recompile RunImage. All the other files can
  148. be compiled under release 3. For distribution to the PD libraries I have
  149. compiled everything except RunImage under release 3. I have linked RunImage
  150. with ANSIlib rather than the shared C library. This is because programs
  151. compiled under release 4 require version 3.75 of the CLIB module which most
  152. users will not have yet.
  153.         The C source files are in the sub-directory "c". The files
  154. "c.orbpar" and "c.orblex", which control the reading of the input file, were
  155. generated automatically by software development tools called "bison" and
  156. "flex" from the files in the "y" and "l" sub-directories. If you don't have
  157. bison and flex (or similar programs) then you can't rebuild the programs
  158. from scratch. You can however change the other source files and re-link with
  159. the existing "c.orbpar" and "c.orblex". The file "Makefile" provides
  160. instructions to the AMU program (or similar) for putting the whole lot
  161. together. Simply make the application directory the current directory and
  162. type "amu" to compile any modifications you might make. 
  163.  
  164. Copying.
  165. --------
  166.         This program has been placed in the public domain by the author
  167. subject to the GNU general public license (NB: this program has nothing to
  168. do with the GNU project as such, I am simply borrowing the FSF's license). A
  169. copy of the license should be distributed with the program in a file called
  170. "Copying". You can read this file by choosing the option "License" from the
  171. main icon bar menu. The license covers all the program modules EXCEPT the
  172. file "c.getopt". I didn't write this and so have no right to impose
  173. conditions on its use. I have included the textfile "getopt" which is the
  174. function as originally distributed by its author.
  175.         As explained in the general license you may modify the program and
  176. distribute your own version. Since different people may take the source and
  177. modify it independently, it is impossible to come up with any consistent
  178. version numbering scheme. Instead I use a file which goes with the program
  179. called "ChangeLog". If you modify the code and subsiquently distribute your
  180. version then comment the changes in the code and also append an entry to
  181. ChangeLog. The ChangeLog file should therefore provide a "backtrace" of all
  182. the people who have had a hand in the code. The "Info" dialogue box of the
  183. application should contain the date of the last change and the initials of
  184. the person making the change. Modify the file "Templates" using FormEd to
  185. do this.
  186.  
  187.  
  188. All bug reports, new versions, constructive critisism, etc. to the following
  189. address.
  190.  
  191.     Neil Hoggarth
  192.     18 Stanmore Lane,
  193.     Winchester,
  194.     SO22 4AJ.
  195.