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 matricies 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 definate.
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
builtin 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 effecive 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 stiffnes,
the case of layering of isotropic materials of different stiffness, and the effect of 
alligned 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_effective_spltting_N.html[MS_effective_splitting_N]  | N-layer effective splitting operator calculation
| 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. 
|======================                                                

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

Finally, range of misellaneous 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.
|======================
