Example 5: Modelling shear-wave splitting variation with backazimuth
====================================================================

This example script demonstrates simple shear-wave splitting modelling using the MSAT
toolset. It predicts the SKS splitting variation with backazimuth associated 
with two dipping, partially-aligned olivine layers. The splitting in each layer
is calculated using the Christoffel equation (MS_phasvels), and combined using
N-layer effective splitting equations (MS_effective_splitting_N; Silver and 
Savage, GJI, 1994). Straight raypaths through the upper mantle are assumed.

The source code for this 
example are contained in the file
split_model.m in the examples/splitting
directory distributed with MSAT. 

The first step is to set up the geometrical parameters of the model
and calculate the ray distances in the two layers.
[code, python]
----
%  ** Setup model parameters
      S_slow = 4.814 ; % (SKS at 100 degrees from iasp91) ->
      aoi = 11.2262 ; % at 100 km depth, angle of incidence

%  ** Layer 1 (upper) parameters
      L1_depth = 0. ; L1_thick = 100. ; L1_dip = 0.0 ; % layer geometry
      L1_aaz = 30.0 ; % a-axis azimuth (rel. to down dip direction)
      L1_faln = 0.3 ; % fraction aligned
      
%  ** Layer 2 (lower) parameters
      L2_depth = 150. ; L2_thick = 60. ; L2_dip = 30.0 ; % layer geometry
      L2_aaz = 0.0 ;  % a-axis azimuth (rel. to down dip direction)
      L2_faln = 0.3 ; % fraction aligned 

      report_model(L1_depth, L1_thick, L1_dip, L1_aaz, L1_faln, ...
                   L2_depth, L2_thick, L2_dip, L2_aaz, L2_faln) ; 

%  ** imaging parameters
      baz = [0:1:360] ; % 0 is down dip direction (perp. to strike)
      inc = -ones(size(baz)).*90 + aoi ;

%  ** calculate distances
      [dist1]=distance_in_dipping_layer(L1_dip,aoi,L1_thick,baz) ;
      [dist2]=distance_in_dipping_layer(L2_dip,aoi,L2_thick,baz) ;
----

The example then builds elasticity matrices for the two layers:
[code, python]
----
%  ** load anisotropy, and generate an isotropic version of it. 
      [Cani,rh] = MS_elasticDB('olivine') ;
      [Ciso] = MS_decomp(MS_axes(Cani)) ;
      Cani = MS_rot3(Cani,90,0,0) ; % orientation for dry upper mantle

%  ** generate layer elasticities:
%        This is a Voigt-Reuss-Hill average of the appropriately rotated olivine
%        tensor and its isotropic equivalent.
      [L1_C,~] = MS_VRH([L1_faln 1-L1_faln],...
         MS_rot3(Cani,0,-L1_dip,L1_aaz,'order',[3 2 1]),rh, Ciso, rh) ;

      [L2_C,~] = MS_VRH([L2_faln 2-L2_faln],...
         MS_rot3(Cani,0,-L2_dip,L2_aaz,'order',[3 2 1]),rh, Ciso, rh) ;
----

Finally, the splitting parameters for each layer are calculated, and then
combined:
[code, python]
----
%  ** interrogate elasticities to generate splitting parameters for each layer.
      [ pol, ~, vs1, vs2, ~, ~, ~ ] = MS_phasevels( L1_C, rh, inc, baz ) ;   
      fast1 = MS_unwind_pm_90((baz - pol')) ; % geog. reference frame
      tlag1 = dist1./vs2' - dist1./vs1' ;
            
      [ pol, ~, vs1, vs2, ~, ~, ~ ] = MS_phasevels( L2_C, rh, inc, baz ) ;   
      fast2 = MS_unwind_pm_90((baz - pol')) ; % geog. reference frame
      tlag2 = dist2./vs2' - dist2./vs1' ;

%  ** calculate the effective splitting between 2 layers    
      fast_eff = zeros(size(baz)) ;
      tlag_eff = fast_eff ;
      for i = 1:length(baz)
         [fast_eff(i),tlag_eff(i)] = ...
            MS_effective_splitting_N(0.125,baz(i), ...
            [fast2(i) fast1(i)],[tlag2(i) tlag1(i)]) ;
      end
----

Results for this calculation are shown in the graph below. For these parameters the delay time
becomes very large when the fast polarisation direction in the upper layer becomes close to 
parallel or perpendicular to the source polarisation (i.e. around 30 and 120 degrees).

image:SS.png[Effective SWS parameters for Silver and Savage method]

Using optional arguments, the example can be modified to examine if this effect is an artefact
of the Silver and Savage method. Adding the arguments "mode" and "GaussianWavelet" changes from
the analytical approach to a computation where a wavelet is split by each layer in turn and the 
resulting splitting parameters measured. Results of this computation ate shown below.

image:gw.png[Effective SWS parameters for wavelet method]

It can be seen that the overall pattern is the same but the very large lag times are reduced.



