src/ElasticTensor_explained.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ElasticProps class explained\n",
    "\n",
    "ElasticProps is a Python class designed to efficiently store and manage the crystallographic, elastic and mechanical properties of earth materials, including minerals and mineral aggregates (rocks). The class takes as input a set of strings used to identify a particular material, the elastic tensor that characterises the elastic properties of the material, and the corresponding pressure (P) and temperature (T) conditions for the defined elastic tensor. The class automatically estimates various average elastic and mechanical properties, performs validation checks to ensure the correctness of the provided input, and decomposes the tensor into its isotropic and anisotropic parts. The class aims to produce a Python object that can be used as input to other methods for estimating seismic properties of any Earth material, such as the velocities of different seismic waves and their polarisations as a function of propagation direction, anisotropy or seismic attenuation.\n",
    "\n",
    "TODO -> scheme\n",
    "\n",
    "## The inputs of the class\n",
    "\n",
    "TODO\n",
    "\n",
    "\n",
    "### The elastic (stiffness) tensor\n",
    "\n",
    "The elastic (stiffness) tensor is the central input to the class as it provides a complete description of the response of the material to external stresses within the elastic limit and correlates with various mechanical and thermal properties of the material, including seismic wave velocities.  The elastic tensor can represent the elastic properties of a particular mineral or a mono- or polymineral aggregate.\n",
    "\n",
    "In particular, for any material the stress $\\varepsilon$ is **linearly related** to the elastic strain $\\sigma$ by Hooke's law\n",
    "\n",
    "$$\n",
    "\\sigma_{ij} = C_{ijkl} \\cdot \\varepsilon_{kl}\n",
    "$$\n",
    "\n",
    "where $C_{ijkl}$ is the elastic tensor that generalises Hooke's law in three dimensions. Since stress and elastic strain in three dimensions are represented by 3 x 3 symmetric tensors with 6 independent values each, the elastic (stiffness) tensor that relates them becomes a 3 x 3 x 3 x 3 symmetric tensor (rank 4, dimension 3) which is notoriously difficult to visualise. Fortunately, its symmetries allow it to be represented as a $C_{ij}$ matrix of rank 2 and dimension 6 as follows (Voigt, 1910):\n",
    "\n",
    "\n",
    "$$\n",
    "\\begin{bmatrix}\n",
    "\\sigma_{1} \\\\\n",
    "\\sigma_{2} \\\\\n",
    "\\sigma_{3} \\\\\n",
    "\\sigma_{4} \\\\\n",
    "\\sigma_{5} \\\\\n",
    "\\sigma_{6} \n",
    "\\end{bmatrix}\n",
    "=\n",
    "\\begin{bmatrix}\n",
    "C_{11} & C_{12} & C_{13} & C_{14} & C_{15} & C_{16} \\\\\n",
    "C_{12} & C_{22} & C_{23} & C_{24} & C_{25} & C_{26} \\\\\n",
    "C_{13} & C_{23} & C_{33} & C_{34} & C_{35} & C_{36} \\\\\n",
    "C_{14} & C_{24} & C_{34} & C_{44} & C_{45} & C_{46} \\\\\n",
    "C_{15} & C_{25} & C_{35} & C_{45} & C_{55} & C_{56} \\\\\n",
    "C_{16} & C_{26} & C_{36} & C_{46} & C_{56} & C_{66} \n",
    "\\end{bmatrix}\n",
    "\n",
    "\\begin{bmatrix}\n",
    "\\epsilon_{1} \\\\\n",
    "\\epsilon_{2} \\\\\n",
    "\\epsilon_{3} \\\\\n",
    "2\\epsilon_{4} \\\\\n",
    "2\\epsilon_{5} \\\\\n",
    "2\\epsilon_{6} \n",
    "\\end{bmatrix}\n",
    "$$\n",
    "\n",
    "Depending on whether the material deforms isotropically or anisotropically and the symmetry of the anisotropy, the most general being triclinic anisotropy, the elastic tensor can have from 3 to 21 independent elements (see figure below).\n",
    "\n",
    "![](https://raw.githubusercontent.com/marcoalopez/PyRockWave/main/src/img/Cijs_symmetry.png)\n",
    "After Nye (1959)\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The average properties derived from the elastic tensor\n",
    "\n",
    "### Voigt and Reuss bounds, and the Hill average\n",
    "\n",
    "TODO\n",
    "\n",
    "### Elastic and seismic properties\n",
    "\n",
    "**Bulk modulus** characterizes the material's ability to resist changes in volume when subjected to hydrostatic pressure. It is typically denoted by the symbol $K$ and is expressed in units of pressure, usually gigapascals (GPa). The bulk modulus is the reciprocal of the **bulk compressibility**, which is widely used to describe the volumetric compliance of the material.\n",
    "\n",
    "**Shear (rigidity) modulus** characterized the resistance of a material to shear deformation, i.e. the material's ability to resist changes in shape when subjected to parallel forces applied in opposite directions. It is typically denoted by the symbol $G$ and is expressed in units of pressure, such as gigapascals (GPa).\n",
    "\n",
    "**Young's modulus** is the ratio of the extensional stress to the extensional strain in an _uniaxial stress test_, and measures the material's stiffness or resistance to elastic deformation when subjected to tensile or compressive forces. It quantifies the material's ability to resist changes in length along its axis under applied stress. Young's modulus is typically denoted by the symbol $E$ and is expressed in units of pressure, such as gigapascals (GPa).\n",
    "\n",
    "**Poisson's ratio** is a material property that describes the ratio of transverse strain (lateral contraction or expansion) to the corresponding axial strain (longitudinal elongation or compression) when a material is subjected to tensile or compressive stress. It characterizes the material's tendency to change in lateral dimensions when stretched or compressed along its axis (Poisson effect). Poisson's ratio is typically denoted by the symbol $\\nu$, ranges from 0.5 to -1, and is a dimensionless quantity. Poisson's ratio can also be written in terms of the longitudinal and transverse wave speeds. \n",
    "\n",
    "**Pugh's ratio** is a parameter used to assess the ductility or brittleness of a material. It is derived by dividing the bulk modulus ($K$) by the shear modulus ($G$). The critical value of Pugh's ratio is commonly considered to be 1.75. When the ratio $K/G > 1.75$ the material is typically considered ductile (i.e. it can undergo substantial deformation before fracturing and thus transitions from elastic to plastic strain) and when $K/G < 1.75$ the material is typically regarded as brittle, indicating that it is prone to fracture without significant plastic deformation (transitions from elastic strain to fracture). It also relates with the Poisson's ratio.\n",
    "\n",
    "The **Universal anisotropy index** (UAI) is a universal (i.e. symmetry independent) measure of material anisotropy proposed by [Ranganathan and Ostoja-Starzewski (2008)](https://doi.org/10.1103/PhysRevLett.101.055504). A zero value indicates that the elastic response of the material is isotropic, while any positive deviation would indicate elastic anisotropy. Since its publication, it has become a widely used anisotropy index. On the downside, the index does not scale proportionally making direct comparisons between materials difficult.\n",
    "\n",
    "The **Kube's (log-Euclidean) anisotropy index** (KAI) is a universal anisotropy index proposed by [Kube (2016)](https://doi.org/10.1063/1.4962996) where a zero value indicates that the material is elastically isotropic and any positive deviation indicate elastic anisotropy. Unlike the UAI, the index scales proportionally so that, for example, when comparing two materials with KAI values of 1 and 2, the one with a KAI of 2 can be said to be twice as anisotropic as the one with a KAI of 1.\n",
    "\n",
    "**Isotropic wave velocities**, either Vp or Vs, can refer to different concepts. In anisotropic minerals, it corresponds to the average speed of sound of the mineral. In mineral aggregates (rocks), it corresponds to the sound propagation speed, assuming that the aggregate is untextured (i.e. lacking CPO) and therefore isotropic.\n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "main",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.11"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}