Importing Tensor Data

Importing a coefficient table is only the first step in defining a tensor. The physical property, unit, compact-matrix convention, crystal symmetry, and crystal frame must agree with the source that published the values. MTEX cannot infer that scientific context from plausible-looking numbers.

This page assumes the ranks and physical classes introduced in Defining Tensorial Properties. Read Crystal Reference System first if the alignment between lattice axes and Cartesian axes is new to you.

A reference frame is the coordinate system in which data are expressed. It is distinct from crystal symmetry, which states the point group under which the property is invariant.

Load a generic tensor

tensor.load selects a file interface automatically. Interface detection identifies how to read the coefficient table; it does not establish what the coefficients mean.

The bundled quartz file contains descriptive header lines, but its .P interface imports only the compact \(3\times6\) coefficient table. The point group and alignment options below attach the crystal frame used by the source. The alignment belongs to the frame, not to point group 32.

% define the quartz crystal symmetry and frame
csQuartz = crystalSymmetry('32',[4.916 4.916 5.4054],...
  'X||a*','Z||c','mineral','Quartz');

% define the file name
quartzFile = fullfile(mtexDataPath,'tensor','Single_RH_quartz_poly.P');

% import and display the piezoelectric strain tensor
P = tensor.load(quartzFile,csQuartz,...
  'propertyname','piezoelectric strain','unit','pC/N',...
  'doubleConvention')

P = tensor (Quartz)
  propertyname    : piezoelectric strain
  unit            : pC/N                
  rank            : 3 (3 × 3 × 3)       
  doubleConvention: true                
 
  tensor in compact matrix form:
     0     0     0 -0.67     0   4.6
   2.3  -2.3     0     0  0.67     0
     0     0     0     0     0     0

Read the import summary

The display is an import audit. It identifies a rank 3 tensor in the quartz crystal frame, labels its values in pC/N, and reports doubleConvention: true before printing the compact coefficient table.

The propertyname and unit options are labels stored with P. They do not convert the numbers, so the file values must already be in pC/N. These labels are the imported object's record of the physical meaning and unit; retain the publication itself as the record of provenance.

Check the compact-matrix convention

The six compact columns represent the index pairs \((11,22,33,23,13,12)\). With doubleConvention, columns 4 to 6 contain twice the corresponding off-diagonal tensor components. MTEX divides those entries by two when expanding the table to \(3\times3\times3\).

This is the engineering-shear convention used by the quartz file. Do not infer it from the shape of a table: omitting the option for this source would silently double part of the tensor.

Load a physically specific tensor

Common physical tensors have dedicated loaders. The stiffnessTensor.load method returns the physically typed class, fixes rank 4, uses the stiffness form of the Voigt convention, and supplies GPa as the default unit label.

Those defaults are correct for this olivine file, but they are still assumptions rather than unit conversion or validation. The file also gives a density of 3355 kg/m\(^3\). The numeric interface does not attach it, so it is converted to 3.355 g/cm\(^3\) and supplied explicitly.

% define the file name
olivineFile = fullfile(mtexDataPath,'tensor','Olivine1997PC.GPa');

% define the olivine crystal symmetry and frame
csOlivine = crystalSymmetry('mmm',[4.7646 10.2296 5.9942],...
  'mineral','Olivine');

% import and display the elastic stiffness tensor
C = stiffnessTensor.load(olivineFile,csOlivine,'density',3.355)

C = stiffnessTensor (Olivine)
  density: 3.355            
  unit   : GPa              
  rank   : 4 (3 × 3 × 3 × 3)
 
  tensor in Voigt matrix representation:
 320.5  68.2  71.6     0     0     0
  68.2 196.5  76.8     0     0     0
  71.6  76.8 233.5     0     0     0
     0     0     0    64     0     0
     0     0     0     0    77     0
     0     0     0     0     0  78.7

Read the typed result

The display now reports a rank 4 stiffnessTensor in GPa, the attached density, and the \(6\times6\) Voigt matrix. The typed result provides elastic moduli and wave-velocity operations that a generic tensor does not. Wave Velocities explains why density is required for seismic velocities.

Check compatibility with crystal symmetry

checkSymmetry tests whether each imported tensor is invariant under its attached crystal point group. The two logical values below correspond to quartz and olivine.

symmetryMatches = [checkSymmetry(P),checkSymmetry(C)]

symmetryMatches =
  1×2 logical array
   1   1

Both values are true for these files. This check can detect an incompatible point group, and for the quartz file it also catches a missing 'doubleConvention'. It cannot verify units, axis sense, handedness, or whether the correct physical property was selected. Compare those items with the source publication before using the tensor.

Next

Continue with Tensor Arithmetic to rotate and contract imported tensors. Tensor Visualization shows how to inspect their directional dependence, and Tensor Averages combines a single-crystal property with orientations or an ODF.

The quartz example continues in Piezoelectricity. The olivine example continues in Anisotropic Elasticity and Wave Velocities.

Further reading