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 ($C_{ijkl} = C_{klij}$) and minor ($C_{ijkl} = C_{jikl}$ and $C_{ijkl} = C_{ijlk}$) symmetries of the tensor to limit the number of constants needed with no loss of data. The 4th order tensor $C_{ijkl}$ is expressed as a symmetric $6\times 6$ Matlab array $C_{\alpha \beta}$ with elements given by:

$ \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.

Table 1. MSAT Input / generation of elastic constants.
Function Purpose

MS_build_isotropic

Create elasticity matrix from pairs of isotropic moduli.

MS_TI

Generate elastic constants for a vertically transverse isotropic medium from Thomsen parameters or other parameterisation. Symmetry is in the 3-axis.

MS_effective_medium

Generate elastic constants from various effective medium theories.

MS_elasticDB

Database of various elastic constants.

MS_expand

Fill out elasticity matrix.

MS_iso

Generate elastic matrix from isotropic velocities.

MS_load

Load a set of elastic constants from a file.

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, $\mathbf{v}$ is rotated from to a new orientation, $\mathbf{v}^{(R)}$, by multiplication by a rotation matrix: $\mathbf{v}^{(R)}=\mathbf{g}\mathbf{v}$, where the rotation matrix, $\mathbf{g}$, is a $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: $v_i^{(R)}$ = $g_{ij}v_j$ (with an implicit summation over $j=1,3$). This formula can be extended for higher order Cartesian tensors. For example, the second order stress tensor is rotated: $\sigma_{ij}^{(R)}$ = $g_{ik}g_{jl}\sigma_{kl}$ (with two implicit summations) and the elastic stiffness tensor rotated: $C_{ijkl}^{(R)}$ = $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: $\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 $3\times3\times3\times3$ tensor form. In order to do this we use the basis change formula from Bower (2009; Section 3.2.11):

$ \mathrm{C}^{(R)}=\mathrm{K}\,\mathrm{C}\,\mathrm{K}^T $

where $\mathrm{C}^{(R)}$ is the rotated version of $\mathrm{C}$. In this equation $\mathrm{K}$ is a $6\times6$ matrix derived from combinations of the normal 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:

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

where

$ 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, $v_i$ are the volume fractions of the $N$ individual components, with associated elasticities ($C_i$) and compliances ($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.

Table 2. MSAT Manipulation / transformation
Function Purpose

MS_VRH

N phase Voigt-Reuss-Hill average of elasticity.

MS_axes

Reorient elasticity matrix for optimal decomposition.

MS_decomp

Browaeys and Chevrot decomposition of the elasticity matrix.

MS_interpolate

Symmetry preserving elasticity interpolation

MS_polyaverage

Isotropic elasticity for polycrystal

MS_rot3

Elasticity matrix rotation.

MS_rotEuler

Rotate an elasticity matrix using Bunge’s Euler angles.

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:

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

where $\rho$ is the density, $u_i$ is the displacement, $x_j$ is position and $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:

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

where $n_j$ is the propagation unit vector, $V$ are the phase velocities, $p_k$ are the polarisation unit vectors and $\delta_{ik}$ is the Kronecker delta function. Solutions to this equation for a given direction ($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.

Table 3. MSAT Analysis
Function Purpose

MS_anisotropy

Simple measures of anisotropy

MS_phasevels

Wave velocities in anisotropic media.

MS_plot

Plot phasevels/anisotropy on pole figures.

MS_poisson

Poisson’s ratio in anisotropic media.

MS_norms

Browaeys and Chevrot analysis of the elasticity matrix.

MS_sphere

Plot a spherical plot of phasevels/anisotropy from a set of elastic constants.

MS_effective_splitting_N

N-layer effective splitting operator calculation

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.

Table 4. MSAT Miscellaneous / utility
Function Purpose

MS_Vrot3

Rotate a (set of) 3-vector(s) by 3 angles.

MS_cij2cijkl

Convert from Voigt elasticity matrix to tensor

MS_cijkl2cij

Convert from elastic tensor to Voigt elasticity matrix

MS_list

Print elasticity matrix (in list format)

MS_rotM

Create a cartesian rotation matrix.

MS_unwind_pm_90

Unwind an angle until it is between 0 and 360 degrees

MS_checkC

Check consistency of a stiffness matrix against various criteria

MS_info

Information about an elasticity matrix.