== MS_axes

 MS_AXES - Reorient elasticity matrix for optimal decomposition.

 // Part of MSAT - The Matlab Seismic Anisotropy Toolkit //

  Calculate the principle axes of elasticity tensor C, after: 
     Browaeys and Chevrot (GJI, v159, 667-678, 2004)
  
 [ CR, ... ] = MS_axes(C)

     [CR] = MS_axes(C)                    
         Return a rotated elasticity matrix minimising the number of 
         distinct elements. This is the orientation which, on further 
         decomposition using MS_NORMS, will maximise the high symmetry
         components of the matrix. 

     [CR, RR] = MS_axes(C)
         In addition, return the rotation matrix, RR, used to perform
         the rotation to generate C from CR.

  [ ... ] = MS_axes( C, 'nowarn' )
     Suppress all warnings.

  [ ... ] = MS_axes( C, 'X3_stiff' )
     For hexagonal or tetragonal tensors, make X3 the stiffest direction,
     not the distinct direction.

  [ ... ] = MS_axes( C, 'debug' )
     Enable debugging plots and messages. These are quite messy.  

 Notes:
     If the input matrix has isotropic, hexagonal or tetragonal 
     symmetry there are multiple orentations of the principle axes.
     In the isotropic case CR is not rotated with respect to C (and RR
     is the identity matrix). In the hexagonal and tetragonal cases, 
     X3 is defined by the distinct eigenvalue (see Browaeys and Chevrot)
     or, if 'X3_stiff', by the stiffest direction. For the monoclinic or 
     triclinic cases we have to make a 'best-guess' and following 
     Browraeys and Chevrot we use the bisectrix of each of the 
     eigenvectors of d and its closest match in v. Furthermore, in order
     to always give the same output orientation for the lowest symmetry 
     cases, a final rotation is performed to place the maximum P-wave 
     velocity in the positive quadrent of the output axis system.

 References:
     Browaeys, J. T. and S. Chevrot (2004) Decomposition of the elastic
         tensor and geophysical applications. Geophysical Journal 
         international v159, 667-678.
     Cowin, S. C. and M. M. Mehrabadi (1987) On the identification of 
         material symmetry for anisotropic elastic materials. Quartely
         Journal of Mechanics and Applied Mathematics v40, 451-476.

 See also: MS_NORMS, MS_INTERPOLATE, MS_DECOMP
