home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / fractal / kaos.lha / userlib / README < prev    next >
Encoding:
Text File  |  1990-01-19  |  7.0 KB  |  178 lines
  1. #
  2. ########################################################################
  3. #       INSTALLING NEW DYNAMICAL SYSTEMS
  4. ########################################################################
  5. #
  6.     Notation: ${KAOSHOME} is whatever directory where the entire
  7.     sourcecode of koas is installed.
  8.  
  9. The installation of a new dynamical system requires changes
  10. in only a few well-isolated set of subroutines.
  11.  
  12. (1) If $HOME/kaos does not exist yet,
  13. create it with the command
  14.     mkdir $HOME/kaos
  15. To find the name of your home directory,
  16. type  set and return. The name after the string  home is your home directory.
  17.  
  18. (2) The directory ${KAOSHOME} contains a file,  Makefile, for
  19. making the kaos executable. Copy this on the directory to ${KAOSUSERHOME}.
  20.  
  21. (3) The subdirectory,  userlib, in  ${KAOSHOME} contains three
  22. templates for dynamical systems.  Each template is a file (three
  23. subroutines) ending with the suffix *_def.c which can be freely edited
  24. to install a new dynamical system.  If copies of this subdirectory and 
  25. files in it do not exist in your own directory
  26.  ${KAOSUSERHOME}, copy them to your user directory,  ${KAOSUSERHOME}
  27. by typing  
  28.     rcp -r ${KAOSHOME}/userlib ${KAOSUSERHOME}
  29.  
  30. (4) To enter your own model, for example, codenamed as  userds0, into the kaos, 
  31. edit a copy of the file,  userds0_def.c,
  32. in the directory  ${KAOSUSERHOME}/userlib following instructions
  33. in the later part of this file or the user manual.
  34.  
  35. (5) Compile kaos with the edited subroutines
  36. by  typing
  37.     make userlib.a
  38. in the directory  ${KAOSUSERHOME}/userlib.
  39. The UNIX  make facility automatically tracks which files
  40. are modified and have to be recompiled.
  41. Debug the edited programs until the command
  42.     make userlib.a
  43. is successful.
  44.  
  45. (6) Type make all_u, to make user executables named  kaos_u  and
  46. kaos_batch_u in the directory  ${KAOSUSERHOME}/kaos.
  47.  
  48. (7) Start the kaos package by typing  kaos_u instead of kaos.
  49. The name kaos is reserved for the original executable.
  50.  
  51. (8) When the program starts, a different dynamical system may have
  52. been currently selected. In the main panel, select
  53. the desired entry from the panel cycle item  Model.
  54. If you have edited the dynamical system file, codenamed userds0, 
  55. an entry labeled as "User Dynamical System 0"
  56. should be selected to simulate the newly entered model. 
  57. (** Warning: Note that the title name of the new model has not
  58. changed in the panel cycle item  Model but it will show up
  59. correctly in the message area. **)
  60.  
  61. In case of bugs or errors, edit the user subroutines and repeat the above
  62. processes (4)-(8).
  63.  
  64. ##########################################################################
  65. #    FORMAT OF DYNAMICAL SYSTEM DEFINITION FILE (*_def.c)
  66. ##########################################################################
  67.  
  68. Subroutine *_init()
  69. ===================
  70. The initial settings for a dynamical system are located here. 
  71. When a dynamical system is selected, system parameters are initialized
  72. as instructed in this file. For parameters not defined here,
  73. the default values are assigned as in the file
  74. ${KAOSHOME}/modellib/default_init.c. 
  75. The major global variables
  76. can be declared external be used by any calling subroutines.
  77. For the dynamical system definition files,
  78. these global variables are already declared external
  79. by a hidden header file, so that the user can forget about them.
  80.  
  81.  title_label: a label for a dynamical system being installed
  82.  
  83.  mapping_on: a toggle switch for a dynamical system type; 1 = mapping, 0 = vector field
  84.  
  85.  inverse_on: a toggle switch for the existence of an explicit inverse;
  86. 1 = exists, 0 = does not exist. It should be always set to 1 for a vector field.
  87.  
  88.  fderiv_on: a toggle switch for the existence of an explicit Jacobian;
  89. 1 = exists, 0 = does not exist.  
  90. (** Warning: Not fully implemented. **)
  91.  
  92.  
  93.  enable_polar: a toggle switch for polar coordinates;
  94. 1 = enable polar coordinates, 0 = disable
  95.  
  96.  enable_period: a toggle switch for using periodic variables;
  97. 1 = enable periodic variables, 0 = disable. If enabled, the period
  98. of each variable needs to be specified.
  99. Insert lines such as  period_len[0] = 1; period_len[1] = 0; if the first variable has a period 1 and the second variable is not periodic.
  100.  
  101.  var_dim: dimension of the phase space
  102.  
  103.  param_dim: dimension of the parameter space
  104.  
  105.  func_dim: dimension of the function space
  106.  
  107.  var_label: labels for primary phase space coordinates.
  108. Primary coordinates are those which are used to
  109. define a vector field or a mapping.
  110.  
  111.  var_polar_label: labels for secondary phase space coordinates
  112. Secondary coordinates are obtained from the primary ones by coordinate transformations.
  113. Currently the secondary coordinates are restricted to the polar coordinates.
  114. The transformation is defined by a set of subroutines 
  115.  euclid_to_polar and  polar_to_euclid.
  116. If  enable_polar = 0, these need not to be defined.
  117.  
  118.  param_label: labels for parameters of a dynamical system
  119.  
  120.  func_label: labels for user defined functions; e.g., 
  121. t,  Energy, and  AngMom
  122.  
  123.  param: initial values of parameters
  124.  
  125.  var_i: initial values of the primary phase space variables
  126.  
  127.  var_polar_i: initial values of the secondary phase space variables
  128. (need not to be defined if  enable_polar = 0)
  129.  
  130.  param_min and  param_max: initial values of lower and upper bounds of the parameters used to size the parameter space box
  131.  
  132.  var_min and  var_max: initial values of lower and upper bounds of the primary phase space variables
  133.  
  134.  var_polar_min and  var_polar_max: starting values of lower and upper bounds of the secondary phase space variables 
  135. (need not to be defined if  enable_polar: = 0)
  136.  
  137.  func_min and  func_max: initial values of lower and upper bounds of the functions used to size the parameter space box
  138.  
  139. Subroutine  *_f()
  140. =================
  141. The right hand side of a vector field or mapping is defined in this subroutine.
  142. Its arguments are:
  143.  
  144.  dim: dimension of the phase space (the number of phase space variables).\footnoteThis is equivalent to the global variable  var_dim.
  145.  
  146.  f: an  dim-dimensional vector representing the values of the right hand side
  147. of a vector field or mapping.
  148.  
  149.  x: an  dim-dimensional vector representing the values of the phase
  150. space variables.
  151.  
  152.  p: an  param_dim-dimensional vector representing the values of the
  153. parameters of a dynamical system, where the variable  param_dim is
  154. the global variable defining the dimension of the parameter space.
  155.  
  156.  t: a value of the time variable. This information is discarded for a mapping.
  157.  
  158.  index: an index switch used for several purposes. For a mapping,
  159. this switch is ignored if an explicit
  160. inverse is not defined. Otherwise, the forward map is returned
  161. if index=1, and the inverse map if index=0.
  162. For a non-Hamiltonian
  163. vector field, the index switch is ignored.
  164. For a Hamiltonian vector
  165. field, the momentum part of the vector field should be defined if
  166. index=1 and the coordinate part, if index=2. Look
  167. at examples of Hamiltonian systems for more information.
  168.  
  169. Subroutine *_func()
  170. ===================
  171. The functions should be defined here. The arguments of this
  172. subroutine are similar to those of  *_f() except that
  173. the argument, index, is not present. 
  174. For example, to use a time axis for plotting,
  175. include the line
  176.  
  177.  f[0] = t;.
  178.