   HALOSIM uses Crystal files (*.XSH) to store descriptions
   of the orientation and relative positions of the faces 
   of the crystal being modelled.  

   These ASCII files can be created with most file editors 
   or word processors.  

   AN EXAMPLE - A CUBE

   The following is the contents of an XSH file describing 
   a cube shaped crystal.

       6  1
       1  0  0
       1.0  0.0  0.0  -1.0
       -1  0  0
       1.0  0.0  0.0  1.0
       0  1  0
       0.0  1.0  0.0  -1.0 
       0  -1  0
       0.0  1.0  0.0  1.0   
       0  0  -1
       0.0  0.0  1.0  1.0
       0  0  1
       0.0  0.0  1.0  -1.0

   The first entry is the number of faces in the crystal 
   (i.e., 6 for a cube.).  

   The second entry is a flag to tell HALOSIM whether it 
   can vary the crystal c/a ratio within the program. A value 
   of 0 should normally be used to indicate that HALOSIM 
   cannot alter the c/a ratio internally.    A value of 1 is
   used for cubic and hexagonal prism crystals because their
   end faces are normal to the side faces and HALOSIM can 
   alter the c/a ratio at will.  

   Lines 2 onward are data describing each crystal face.  

   Two lines are used for each face. 

   The first line describes the DIRECTION the face points.  
   The second line describes the face POSITION.

   Consider the first face:

       1  0  0
       1.0  0.0  0.0  -1.0

   The first line provides the X, Y, and Z components of 
   the outward facing unit normal vector for the face.
 
       The coordinate convention is that the X and Y axes 
       are in a horizontal plane and the Z axis is vertical.  
       
   Since the vector is orientated directly along the X 
   axis, the X component is 1 and the Y and Z components 
   are 0.

   The second line provides the data describing the 
   position of a the plane containing the face.  The 
   general equation for a plane surface is:

        Ax + By + Cz + D = 0

   The second line is the values of A, B, C and D.  In 
   the case of the first cube face, A = 1, B = C = 0 
   and D = -1.  This simplifies to x-1 = 0 or x = 1.  
   In other words, the first face of the cube is 
   within the plane x = 1.  

   It may be useful to examine the constants for the 
   other 5 cube faces and verify that the normal vectors 
   are properly orientated and that the face planes 
   create a proper cube.


   For HALOSIM to work properly, the crystal should have 
   it's center of mass at the origin of the coordinate 
   system (i.e., At the point (0,0,0).  Presently, HALOSIM 
   can accommodate crystals with 20 or fewer faces but 
   this is not a fundamental limitation.

   

   HEXAGONAL ICE PRISM.XSH

   The file "Hexagonal Ice Prism.XSH" differs slightly
   from the above description.   This is because there
   are custom procedures within HALOSIM which do ray 
   tracing calculations for hexagonal prisms very 
   efficiently and require a special crystal file.

   
   PYRAMIDAL CRYSTAL FILES

   These can be generated automatically using "Pyramid 
   Maker" for whatever dimensions the user chooses.

   
   FACE NUMBERS

   The face numbers that appear to the user in HALOSIM 
   are not necessarily those used internally in 
   calculations.     For example, the face numbering 
   conventions of TAPE for pyramidal crystals require 
   special treatment because they are not consecutive 
   and not all possible faces are necessarily present on 
   any particular crystal.   

   Face number conversions follow instructions in a *.FCT
   crystal file of the exact same name as the correspond-
   ing *.XSH file.    In addition to a face number conversion 
   table, the file contains the name of the numbering system, 
   the crystal name and details of the image file for the 
   crystal.
    
 

