Matlab Seismic Anisotropy Toolkit - using the functions
=======================================================

This section of the user guide includes some information on the functions provided in, and 
theory implemented by, the MSAT toolkit.
The functions provided by MSAT can be classified into groups according to how they are used. These groups 
broadly correspond to how elasticity matrices appear in the input and output arguments lists. In all 
cases function names begin with "MS_" and argument lists typically begin with the elasticity
followed, where needed, by the density. Units are always GPa for the elasticity, 
km/s for phase velocities and kg/m^3 for densities.

In all cases when elastic constants (stiffness) tensors are used they 
are represented using Voigt notation. This takes advantage of the
major (latexmath:[$C_{ijkl} = C_{klij}$]) and minor (latexmath:[$C_{ijkl} = C_{jikl}$] and
latexmath:[$C_{ijkl} = C_{ijlk}$]) symmetries of the tensor to 
limit the number of constants needed with no loss of data. The
4th order tensor latexmath:[$C_{ijkl}$] is expressed 
as a symmetric latexmath:[$6\times 6$] Matlab array latexmath:[$C_{\alpha \beta}$]
with elements given by:

latexmath:[$
\begin{array}{ccccc}
ij &\mathrm{or} &kl &: & \\
\downarrow & &\downarrow & & \\
\alpha & &\beta & &
\end{array} 
\begin{array}{cccccc}
11 &22 &33 &32=23 &31=13 &12=21 \\
\downarrow &\downarrow &\downarrow
&\downarrow &\downarrow &\downarrow \\
1 &2 &3 &4 &5 &6
\end{array}.
$]

In the MSAT documentation we call the Voigt representation of 
the elastic constants tensor the elasticity matrix (in an attempt to 
avoid confusion) and note that, if the matrix is to make physical sense,
it must be symmetric, consist of real numbers, and be positive definite.
Conversion and validation functions are described in the section 
"Other functions", below. Functions are otherwise classified as follows.

The input and generation functions
----------------------------------

The first group of functions generate elasticity matrices from input 
arguments (see the table below). MS_load and MS_load_list
read data from input files 
while MS_elasticDB extracts elasticity information from a
built-in database. Other functions create elasticity matrices 
from summary information and a knowledge of the symmetry. 

In the most general case 21 elastic constants are required to represent minerals and materials
with a triclinic symmetry, but systems with a higher symmetry 
(e.g. orthorhombic, hexagonal or cubic) require fewer elastic constants. In the simplest case,
that of isotropic materials, this reduces to two parameters. 
The limitations of what 
can usually be resolved using seismology mean that higher symmetry classes are often assumed. 
A class which is commonly invoked is transverse isotropy (TI, also known as radial 
or polar anisotropy). In a TI medium properties only vary with angle from the 
symmetry axis. This can arise in a number of ways and is exhibited by: crystalline materials with a 
hexagonal symmetry, isotropic thin layers of different stiffness,
aligned inclusions
or cracks which are uniformly oriented. TI requires five 
independent constants to parameterise. There are a number of commonly used choices of
parameter sets (depending on the area of literature); MSAT has functions to work with 
several of these. 

It is also possible to model the effective anisotropic elasticity caused by particular
rock fabrics; an effect that can be important even if all the components of the rock are isotropic
on a short length scale compared to the seismic wavelength. Several effective medium models are 
supported by the MS_effective_medum function. These include the case of an
elastically isotropic medium contains aligned ellipsoidal 
inclusions filled with an elastically isotropic material of a different stiffness,
the case of layering of isotropic materials of different stiffness, and the effect of 
aligned cracks.

.MSAT Input / generation of elastic constants. 
[width="80%",cols="3,10",frame="topbot",options="header"]
|======================
|Function|Purpose
| link:funcs/MS_build_isotropic.html[MS_build_isotropic]             | Create elasticity matrix from pairs of isotropic moduli.
| link:funcs/MS_TI.html[MS_TI]                                       | Generate elastic constants for a vertically transverse isotropic medium from Thomsen parameters or other parameterisation. Symmetry is in the 3-axis. 
| link:funcs/MS_effective_medium.html[MS_effective_medium]           | Generate elastic constants from various effective medium theories. 
| link:funcs/MS_elasticDB.html[MS_elasticDB]                         | Database of various elastic constants.
| link:funcs/MS_expand.html[MS_expand]                               | Fill out elasticity matrix.
| link:funcs/MS_iso.html[MS_iso]                                     | Generate elastic matrix from isotropic velocities.
| link:funcs/MS_load.html[MS_load]                                   | Load a set of elastic constants from a file.
| link:funcs/MS_load_list.html[MS_load_list]                         | Load a list of CIJs, in a specific format
|======================                                                

The manipulation functions 
--------------------------

A second group of functions include elasticity matrices as input and output. These
functions, listed below, are used to manipulate or
transform an elasticity matrix. 

One important manipulation is tensor rotation. MS_rot3,
MS_rotEuler and MS_rotR all rotate an elasticity matrix (the 
functions differ in the way the rotation is specified: in all
cases a rotation matrix is constructed and MS_rotR is used 
to perform the actual manipulation). To understand the approach 
recall that a vector, latexmath:[$\mathbf{v}$] is 
rotated from to a new orientation, latexmath:[$\mathbf{v}^{(R)}$], by multiplication by a rotation matrix:
latexmath:[$\mathbf{v}^{(R)}=\mathbf{g}\mathbf{v}$], where the rotation matrix, latexmath:[$\mathbf{g}$], is a 
latexmath:[$3 \times 3$] orthogonal matrix with determinant 1 and elements that represent the cosines of
angles of the rotation. This transformation be also be written element-wise as: 
latexmath:[$v_i^{(R)}$] = latexmath:[$g_{ij}v_j$] (with an implicit summation over latexmath:[$j=1,3$]). This formula 
can be extended for higher order Cartesian tensors. For example, the second order 
stress tensor is rotated: latexmath:[$\sigma_{ij}^{(R)}$] = latexmath:[$g_{ik}g_{jl}\sigma_{kl}$] (with two
implicit summations) and the elastic stiffness tensor rotated: 
latexmath:[$C_{ijkl}^{(R)}$] = latexmath:[$g_{im}g_{jn}g_{kp}g_{lq}C_{mnpq}$] (with four summations and avoiding Voigt 
notation). For second
order tensors the transformation can also be written in the form of matrix multiplication by the
rotation matrix and its transpose: latexmath:[$\mathbf{\sigma}^{(R)} = \mathbf{g} \mathbf{\sigma} \mathbf{g}^{T}$],
but this shortcut is not available for higher order tensors. However,
it is possible (in fact, highly desirable for performance reasons) to perform rotations on 
elastic constants in Voigt form without requiring to transform to the latexmath:[$3\times3\times3\times3$]
tensor form. In order to do this we use the basis change formula from 
Bower (2009; Section 3.2.11):

latexmath:[$
\mathrm{C}^{(R)}=\mathrm{K}\,\mathrm{C}\,\mathrm{K}^T
$]

where latexmath:[$\mathrm{C}^{(R)}$] is the rotated version of latexmath:[$\mathrm{C}$]. In this equation 
latexmath:[$\mathrm{K}$] is a latexmath:[$6\times6$] matrix derived from combinations of the normal 
latexmath:[$3\times3$] rotation matrix (see Bower 2009 for details), and latexmath:$\mathrm{K}^T$]
is its matrix transpose. 

MS_axes also rotates an 
input matrix but by an amount designed to allow the anisotropic nature of the 
matrix to be analysed. Such analysis makes use of two other functions,
MS_decomp and MS_norms. Taken together, these three
functions allow the symmetry of elasticity matrices to be expressed following 
the approach of Browaeys and Chevrot (2004). Example of this approach are
provided elsewhere in the documentation. 

Another type of manipulation concerns the 
averaging of elastic constants. In many fields we do not deal with 
single crystals. We need, therefore, a method of estimating 
the aggregate elastic properties of a polycrystalline material containing a range of crystal types 
and orientations. While much more rigorous treatments exist 
for many purposes simple 
averaging schemes suffice. These either assume constant strain (Voigt averaging) 
or stress (Reuss averaging) throughout the sample, and essentially amount to taking 
the arithmetic average of each element of the stiffness or compliance tensor, respectively. These two 
values place an upper (Voigt) and lower (Reuss) bound on the true value. It was 
observed by Hill (1952) that experimental values were often close to the 
average of these two bounds, a value which has become known as the 
Voigt-Reuss-Hill (VRH) average:

latexmath:[$
C^{\mathrm{VRH}}=\frac{1}{2}\left(C^{\mathrm{Voigt}}+C^{\mathrm{Reuss}}\right)
$]

where

latexmath:[$
C^{\mathrm{Voigt}}=\sum_{i=1}^{N}{v_iC_i}\;\;\;
\mathrm{and}\;\;\;C^{\mathrm{Reuss}}=\left(\sum_{i=1}^{N}{v_iS_i}\right)^{-1}.
$]

Here, latexmath:[$v_i$] are the volume fractions of the latexmath:[$N$] individual components, with 
associated elasticities (latexmath:[$C_i$]) and compliances (latexmath:[$S_i$]). This is very commonly 
employed. 
It should be noted that it is an empirical relation with 
no strict theoretical foundation, albeit a useful one.
MS_VRH calculates the Voigt, Reuss, and 
Voigt-Reuss-Hill average elasticity of an aggregate of materials, 
each described by their own elasticity matrix and volume fraction, while 
MS_polyaverage takes this averaging one step further and estimates the 
isotopic elasticity matrix if the components are randomly oriented.  

.MSAT Manipulation / transformation                                    
[width="80%",cols="3,10",frame="topbot",options="header"]              
|======================                                                
|Function|Purpose                                                      
| link:funcs/MS_VRH.html[MS_VRH]                                     | N phase Voigt-Reuss-Hill average of elasticity.
| link:funcs/MS_axes.html[MS_axes]                                   | Reorient elasticity matrix for optimal decomposition.
| link:funcs/MS_decomp.html[MS_decomp]                               | Browaeys and Chevrot decomposition of the elasticity matrix.
// | link:funcs/MS_interpolate.html[MS_interpolate]                     | Symmetry preserving elasticity interpolation 
| link:funcs/MS_polyaverage.html[MS_polyaverage]                     | Isotropic elasticity for polycrystal 
| link:funcs/MS_rot3.html[MS_rot3]                                   | Elasticity matrix rotation.
| link:funcs/MS_rotEuler.html[MS_rotEuler]                           | Rotate an elasticity matrix using Bunge's Euler angles.
| link:funcs/MS_rotR.html[MS_rotR]                                   | Script to rotate a set of elastic constants by a rotation matrix
|======================                                                

The analysis functions 
----------------------

The third group of functions allow elasticity to be analysed or displayed.
They take elasticity matrices as input arguments and either return derived 
quantities or cause graphics to be produced. Examples include MS_anisotropy,
which implements some of the attempts to capture the degree of elastic anisotropy
of a material as a single value and 
MS_poisson which calculates
Poisson's ratio for a general anisotropic material as a function of direction.

For seismology, one of the most important ways to analyse the anisotropic
elasticity of a medium is in terms of seismic phase velocities. 
The propagation of motion through an elastic medium is governed 
by the elastodynamics equation:

latexmath:[$
\rho\left(\frac{\partial^2u_i}{\partial t^2}\right) = C_{ijkl}\left(\frac{\partial^2u_l}{\partial x_jx_k}\right)
$]

where latexmath:[$\rho$] is the density, latexmath:[$u_i$] is the displacement, latexmath:[$x_j$] is position 
and latexmath:[$t$] is time. By substituting into this the displacement associated with a 
monochromatic plane wave as a function of time, we obtain the well-known 
Christoffel equation:

latexmath:[$
\left(C_{ijkl}n_jn_l-\rho V^2\delta_{ik}\right)p_{k}=0
$]

where latexmath:[$n_j$] is the propagation unit vector, latexmath:[$V$] are the phase velocities, latexmath:[$p_k$] are 
the polarisation unit vectors and latexmath:[$\delta_{ik}$] is the Kronecker delta function. 
Solutions to this equation for a given direction (latexmath:[$n_j$]) yield the three orthogonal 
waves with different phase velocities. One of these will be close to the wavefront 
normal (designated quasi-P or qP) and two will be near perpendicular (quasi-S1, 
quasi-S2; qS1 and qS2). In practice the quasi- prefix is often omitted. The reader 
is directed to Mainprice (2007) for a more complete treatment of the subject. 
MSAT follows the methodology of Mainprice (1990) to calculate phase 
velocities and this is implemented in  MS_phasevels.
The function accepts a (set of) propagation direction(s) and returns the three seismic phase velocities 
along with their polarisations. This function is used by MS_plot and MS_sphere,
which plot the resulting seismic anisotropy on a pole figures and a three-dimensional
spherical representation, respectively.                                                                        

.MSAT Analysis                                                         
[width="80%",cols="3,10",frame="topbot",options="header"]              
|======================                                                
|Function|Purpose                                                      
| link:funcs/MS_anisotropy.html[MS_anisotropy]                       | Simple measures of anisotropy 
| link:funcs/MS_phasevels.html[MS_phasevels]                         | Wave velocities in anisotropic media.
| link:funcs/MS_plot.html[MS_plot]                                   | Plot phasevels/anisotropy on pole figures.
| link:funcs/MS_poisson.html[MS_poisson]                             | Poisson's ratio in anisotropic media.
| link:funcs/MS_norms.html[MS_norms]                                 | Browaeys and Chevrot analysis of the elasticity matrix.
| link:funcs/MS_sphere.html[MS_sphere]                               | Plot a spherical plot of phasevels/anisotropy from a set of elastic constants.
| link:funcs/MS_TI_parameters.html[MS_TI_parameters]                 | Calculate Thomsen and other parameters for a vertically transverse isotropic medium given the elasticity matrix. Symmetry is in the 3-axis. 
|======================                                                

Shear wave splitting
--------------------

Alongside the functions designed to analyse aspects of elasticity, MSAT also contains functions to 
deal with simple aspects of modelling one of the most common seismological observations related to 
elastic anisotropy, shear wave splitting. As discussed above, seismic waves can propagate at
three velocities through an anisotropy body and two of these velocities correspond to shear waves. 
If a shear wave passes through an anisotropic region it is split into two shear waves with 
particle motion polarised at 90 degrees to each other (and approximately perpendicular to the 
direction of wave propagation. As the two shear waves have different velocities they will emerge
from the anisotropic region at different times and with particle motion direction imposed by the 
elastic anisotropy of the medium. This process is known as shear wave splitting (SWS) and its 
observation in seismic data is considered strong evidence for anisotropy somewhere along the ray 
path.

.MSAT Shear wave splitting                                                         
[width="80%",cols="3,10",frame="topbot",options="header"]              
|======================                                                
|Function|Purpose
| link:funcs/MS_make_trace.html[MS_make_trace] | Create simple wavelet for splitting calculation
| link:funcs/MS_split_trace.html[MS_split_trace] | Apply splitting operators to wavelet
| link:funcs/MS_effective_splitting_N.html[MS_effective_splitting_N]  | N-layer effective splitting operator calculation
| link:funcs/MS_measure_trace_splitting.html[MS_measure_trace_splitting] | Measure splitting from wavelet
| link:funcs/MS_splitting_misfit.html[MS_splitting_misfit] | Calculate misfit between two splitting operators
| link:funcs/MS_plot_trace.html[MS_plot_trace] | Plot wavelet and splitting measurement results
|======================  

In MSAT we only implement functions to handle the simplest aspects of SWS. Time series of particle displacements are described by 
three arrays we call `time`, `T00` and `T90`. `T00(i)` and `T90(i)` relate to the particle position of two perpendicular traces at
time `time(i)`. The function `MS_make_trace` generates these assuming a first derivative Gaussian shape for a given dominant frequency 
making space in the arrays for a user selected maximum amount of splitting. `MS_phasevels` can calculate splitting parameters from 
an elasticity matrix and this can be used with `MS_split_trace` to apply splitting parameters. The effective splitting generated
by a wave passing through multiple layers can be found by combing splitting operators using `MS_effective_spltting_N`. This either
implements an analytic approach to calculating the resulting splitting parameters or uses `MS_split_trace` multiple times and then
makes a measurement of the resulting effective splitting using `MS_measure_trace_splitting`. `MS_splitting_misfit` allows 
two splitting operators to be compared (allowing the best fitting elasticity to be found, see the
link:examples/splitting_misfit_example.html[Splitting misfit example]) and `MS_plot_trace` can be used to visualise
`time`, `T00` and `T90`. For complex applications these three arrays can be converted to and from SAC records using the functions 
available from link:http://www1.gly.bris.ac.uk/~wookey/codes/index.htm[MSAC]. 

Other functions 
---------------

Finally, range of miscellaneous and utility functions are provided to, for example, convert between different ways of representing elasticity or check that
a particular Matlab array is a valid elasticity matrix.
                                                                       
.MSAT Miscellaneous / utility                                          
[width="80%",cols="3,10",frame="topbot",options="header"]              
|======================                                                
|Function|Purpose                                                      
| link:funcs/MS_Vrot3.html[MS_Vrot3]                                 | Rotate a (set of) 3-vector(s) by 3 angles.
| link:funcs/MS_cij2cijkl.html[MS_cij2cijkl]                         | Convert from Voigt elasticity matrix to tensor
| link:funcs/MS_cijkl2cij.html[MS_cijkl2cij]                         | Convert from elastic tensor to Voigt elasticity matrix
| link:funcs/MS_list.html[MS_list]                                   | Print elasticity matrix (in 'list' format)
| link:funcs/MS_rotM.html[MS_rotM]                                   | Create a cartesian rotation matrix.
| link:funcs/MS_unwind_pm_90.html[MS_unwind_pm_90]                   | Unwind an angle until it is between 0 and 360 degrees
| link:funcs/MS_checkC.html[MS_checkC]                      | Check consistency of a stiffness matrix against various criteria
| link:funcs/MS_info.html[MS_info]                                   | Information about an elasticity matrix.
|======================
