
   HALOSIM needs data on how crystals can be oriented with 
   respect to the incident solar rays.

   Orientation instructions are provided via 'Orientation' 
   files (*.XNG and the older *.XAN).  These are ASCII files 
   and can be created and edited on most file editors and 
   word processors.

   Files for the common crystal orientations:

       Singly oriented column
       Parry oriented column
       Horizontal plate
       Lowitz orientation

       .. are provided with HALOSIM.  More can be generated 
   automatically using the "Crystal Orientation File Maker"
   accessed from the 'Tools' menu.



   ORIENTATION FILE MAKER

   Let's look first at automatic generation.  Access the file
   make from 'Tools'.   'File Maker' has four buttons, one for
   each orientation.  

   1. Choose the orientation needed and click that button.   

        The Atmospheric Optics website at:

        http://www.sundog.clara.co.uk/atoptics/phenom.htm

        (click the lower left button to access) provides 
        guidance on the effects of different crystal 
        orientations.  For a deeper description go to the 
        books of Tape or Greenler (see Further Reading 
        in Help).

   2. Enter the axial dispersion value(s) in degrees.  This is 
      the standard deviation of the amount that the crystal
      can tilt from its preferred orientation. Within HALOSIM 
      the tilt takes a large number of randomly chosen values, 
      but its distribution is that chosen on the control panel 
      by the user and the standard deviation within the chosen 
      file characterises the tilt magnitude.

   3. Click 'Make a File'.   A dialogue box opens suggesting
      a name.  It is strongly recommended that the descriptive 
      name is accepted.  

   4. Click OK.   That's it, the file is created and stored.



   CUSTOM FILES

   Orientations might be required that do not conform to the 
   common types created by 'File Maker'.

   The description below outlines the stucture and logic of 
   the orientation files.

   First of all, the 'normal' orientation of the crystal with 
   respect to the horizontal plane must be known.   This is 
   fixed by that of the individual crystal faces as described 
   within the crystal shape (*.XSH) file.

   AN EXAMPLE
   HEXAGONAL PRISM - SINGLY ORIENTED

   The file 'Hexagonal Ice Prism.xsh' describes a crystal with
   its end faces horizontal and the prism side faces all 
   vertical.  The Z axis is taken to point upwards and a pair 
   of hexagon vertices are along the X axis.   

   To produce singly oriented columns it must:

      A. Rotate once through 90 deg onto its side
      B. Take a random position about its (long) 
          horizontal prism axis
      C. Randomly tilt about a vertical axis 
      D  Take a random orientation about a vertical 
         axis.
          
   The file to produce singly oriented columns from the 
   hexagonal crystals is: 

       9002 
       4 
       3    0    360 
       2    0      1 
       1    0    360 
       2   90      0

            [ Note: Other crystals might have other 
              initial orientations and the above file
              may not be suitable.  Examine the 
              orientation of each crystal. ]
   
   The first line of the file is a single integer telling 
   HALOSIM the file version. HALOSIM accepts several versions 
   and formats.   New files for versions 2 onwards should 
   start with 9002.

   The second line has a single integer - the number of 
   distinct rotations the crystal will undergo.

   The remaining lines describe each distinct rotation.

   THE FIRST ROTATION APPLIED WITHIN HALOSIM
   IS THAT ON THE LAST LINE.  The next is that
   on the penultimate line and so on.  

   The first integer on each line indicates the axis about 
   which a rotation will be performed (1= X axis, 2= Y 
   axis, 3= Z axis and 4= a special rotation for the 
   'Random' crystal orientation). 

   The second number on each rotation line indicates a 
   fixed amount in degrees that the crystal will be rotated.  

   The third number indicates a random (Between 0 and the 
   specified number of degrees) amount of rotation that 
   is be added to the fixed amount to produce the entire 
   rotation.  For example, the instructions:

       2   90      0

   will produce a rotation of exactly 90 degrees about the 
   Y axis and no random rotation.  The line:

       1    0    360
 
   will produce a totally random rotation of between 0 and 
   360 degrees about the X axis.  

   A further example is the rotation:

       2    45     5

   This results in a rotation about the Y axis of 45 degrees 
   (The fixed amount) PLUS a further rotation characterized
   by the dispersion function selected on the control panel 
   (Top Hat, Gaussian or Simple Harmonic) and a Standard 
   Deviation of 5 degrees.


   Lets look again at the example file above for singly 
   oriented columns.

   Within HALOSIM it causes the following (numerical) 
   operations on the model hexagonal ice crystal:

   1.  (Last line)  Rotation through a fixed 90 degrees 
       about the Y axis.

       This turns it so the long prism axis lies in a 
       horizontal plane.

   2.  (Penultimate line) Rotation by a random number 
       of degrees between 0 and 360 about the X axis.
       The random rotations are uniformly distributed.

       This positions the crystal randomly about its long 
       axis.  Without this operation the crystal would be 
       Parry oriented.

   3.  Rotation about the Y axis by a small amount 
       characterized by the distribution selected and a 
       Standard deviation of 1 degree.

       This models the 'dispersion' - the small tilt
       that characterizes the departure from perfect 
       orientation that no real crystals attain.

          HALOSIM treats the random rotation instruction 
          differently, depending on the value in the 
          file.   Values of 30, 45, 90, 180 and 360 degrees 
          are taken as limits and rotations are uniformly 
          distributed random values between 0 and the 
          limit.   Other values are taken to be standard 
          deviations for the distribution chosen on the 
          control panel.

  4.   Rotation about the Z (vertical) axis by a uniformly 
       distributed random amount between 0 and 360 degrees.

       This allows the long axes of the crystal population 
       to take up all azimuthal angles.

           
 





   



