mtex 1.0.0__py3-none-any.whl

mtex/__init__.py

@@ -0,0 +1,94 @@
+"""MTEX: the crystallographic texture analysis toolbox
+
+The Python port of MTEX: crystal symmetry and orientations, EBSD maps, grains and their
+boundaries, pole figures, orientation distribution functions and tensors, in one flat
+namespace, with MATLAB's names
+
+  from mtex import *
+  cs = crystalFrame('m-3m')
+  ori = orientation.byEuler(30*degree, 50*degree, 10*degree, cs)
+  ebsd = mtexdata('forsterite')
+  grains = calcGrains(ebsd('indexed'))
+
+The namespace is assembled from the layers, each importing only those above it
+
+  mtex.geometry   vectors, rotations, orientations, point groups, frames, Miller indices, grids
+  mtex.functions  harmonics, kernels, functions on S2 and SO(3), ODFs, pole figures
+  mtex.tensors    the tensor container, its algebra and the physical tensors
+  mtex.maps       EBSD maps, grains, grain boundaries, parent grain reconstruction
+  mtex.maps3d     maps of volumes: EBSD3, 3D grains and boundaries
+  mtex.analysis   what iterates or optimises: pole figure inversion, elasticity, Taylor, ...
+  mtex.io         loadEBSD, loadPoleFigure, export, mtexdata, openDoc
+  mtex.plotting   plot, plotPF, plotIPF, plotSection, the colour keys (matplotlib, the plot extra)
+
+Help
+
+  help(orientation)                 what a class or function is and takes
+  openDoc('GrainReconstruction')  a documentation page as a script to run
+  mtexdata()                        the sample data sets
+
+The documentation is at https://mtex-toolbox.github.io
+"""
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError, version as _version
+
+# the version of the installed distribution
+try:
+  __version__ = _version("mtex")
+except _PackageNotFoundError:
+  __version__ = "unknown"
+
+from typing import TYPE_CHECKING
+
+from . import geometry as _geometry
+from . import maps as _maps
+from . import maps3d as _maps3d
+from . import functions as _functions
+from . import tensors as _tensors
+from . import analysis as _analysis
+from . import io as _io
+from . import plotting as _plotting
+from .geometry import *  # noqa: F401,F403
+from .maps import *  # noqa: F401,F403
+from .maps3d import *  # noqa: F401,F403
+from .functions import *  # noqa: F401,F403
+from .tensors import *  # noqa: F401,F403
+from .analysis import *  # noqa: F401,F403
+from .io import *  # noqa: F401,F403
+from .plotting import *  # noqa: F401,F403
+from .wizard import importWizard  # noqa: F401
+
+# the one flat namespace, the layers in the order they import each other
+__all__ = []
+__all__ += _geometry.__all__
+__all__ += _maps.__all__
+__all__ += _maps3d.__all__
+__all__ += _functions.__all__
+__all__ += _tensors.__all__
+__all__ += _analysis.__all__
+__all__ += _io.__all__
+__all__ += _plotting.__all__
+__all__ += ["importWizard", "xvector", "yvector", "zvector"]
+
+
+# the displays of a notebook and of the IPython terminal, when mtex is imported in one
+from .plotting.richdisplay import registerDisplays as _registerDisplays
+_registerDisplays()
+
+# in IPython, the strings a call takes completed inside its quotes
+from .io.completer import registerCompleter as _registerCompleter
+_registerCompleter()
+
+# the user's saved settings, what MATLAB keeps in mtex_settings.m
+from .geometry.settings import loadSettings as _loadSettings
+_loadSettings()
+
+
+# xvector, yvector, zvector are fresh on every access
+def __getattr__(name):
+  if name in ("xvector", "yvector", "zvector"):
+    return getattr(_geometry, name)
+  raise AttributeError(name)
+
+
+if TYPE_CHECKING:
+  from .geometry.vector3d import xvector, yvector, zvector

mtex/analysis/__init__.py

@@ -0,0 +1,34 @@
+"""the analysis layer: the algorithms that iterate or optimise over the cores, from the
+pole figure inversion to the denoising of a map"""
+from .elasticity import (velocity, energyVector, YoungsModulus, linearCompressibility, volumeCompressibility,
+                         shearModulus, PoissonRatio, bulkModulus, isotropicShearModulus, HashinShtrikmanModulus,
+                         hashinShtrikmanBounds)
+from .mechanics import (meanStress, deviatoric, deviatoricStress, deviatoricStrain, equivalentStress, equivalentStrain,
+                        octahedralStrain, axisRatios, maxStrain, calcShearStress, SchmidFactor, CauchyStrain,
+                        GreenStrain, strainRate, spin, angularVelocityVector, rotationRate, vorticity, spinTensorOf,
+                        dislocationDensity)
+from .optics import refractiveIndex, birefringence, opticalAxis, spectralTransmission
+from .taylor import calcTaylor, linearProgram, linprogCentre, TaylorModel
+from .texture import calcTensor, calcLankford, calcKearnsFactor, SO3FunSBF, doEulerStep
+from .pf2odf import MLSSolver, zeroRangeMethod, calcODF, calcODFIterative
+from .embedding import embedding, embeddingSpec, double, setDouble
+from .optimalsample import optimalSample, OptimalSampleResult
+from .cluster import calcCluster, classix, knnRadius
+from .variational import EBSDFilter, splineFilter, halfQuadraticFilter, l1TVFilter, infimalConvolutionFilter
+from .dislocations import fitDislocationSystems
+from .denoising import meanFilter, medianFilter, KuwaharaFilter
+from .gbnd import calcGBNDKernel
+from .gbnd3d import calcGBND
+
+__all__ = ["velocity", "energyVector", "YoungsModulus", "linearCompressibility", "volumeCompressibility",
+           "shearModulus", "PoissonRatio", "bulkModulus", "isotropicShearModulus", "HashinShtrikmanModulus",
+           "hashinShtrikmanBounds", "meanStress", "deviatoric", "deviatoricStress", "deviatoricStrain",
+           "equivalentStress", "equivalentStrain", "octahedralStrain", "axisRatios", "maxStrain", "calcShearStress",
+           "SchmidFactor", "CauchyStrain", "GreenStrain", "strainRate", "spin", "angularVelocityVector", "rotationRate",
+           "vorticity", "spinTensorOf", "dislocationDensity", "refractiveIndex", "birefringence", "opticalAxis",
+           "spectralTransmission", "calcTaylor", "linearProgram", "linprogCentre", "TaylorModel", "calcTensor",
+           "calcLankford", "calcKearnsFactor", "SO3FunSBF", "doEulerStep", "MLSSolver", "zeroRangeMethod", "calcODF",
+           "calcODFIterative", "embedding", "embeddingSpec", "double", "setDouble", "optimalSample",
+           "OptimalSampleResult", "calcCluster", "classix", "knnRadius", "EBSDFilter", "splineFilter",
+           "halfQuadraticFilter", "l1TVFilter", "infimalConvolutionFilter", "fitDislocationSystems", "meanFilter",
+           "medianFilter", "KuwaharaFilter", "calcGBND", "calcGBNDKernel"]

mtex/analysis/cluster.py

@@ -0,0 +1,308 @@
+# clustering directions and orientations (MATLAB vector3d/calcCluster, orientation/calcCluster,
+# extern/classix; docs/plans/functions.md F6, ported 2026-09-22)
+#
+#   cId, center = calcCluster(v)                                     CLASSIX on the coordinates
+#   cId, center = calcCluster(ori, method='classix', radius=, minPoints=)
+#   cId, center = calcCluster(ori)                                   the modes of the density, MATLAB's default
+#   cId, center = calcCluster(ori, method='hierarchical', maxAngle=15*degree, numCluster=)
+#   labels = classix(X, radius, minPts=, mergeScale=1.5)
+#
+# CLASSIX (Chen and Guettel, Fast and explainable clustering based on sorting,
+# arXiv:2202.01456): the data is centred, scaled by its median norm and sorted along its
+# first principal axis; every point joins the first group whose centre lies within radius;
+# groups whose centres lie within mergeScale times the radius are merged; a cluster below
+# minPts points is dissolved into the nearest larger one. Directions cluster on their
+# coordinates, axes on the rank one tensor that identifies v with -v, orientations on the
+# isometric embedding that carries the symmetry. The hierarchical method merges the closest
+# pair of centres until the count or the angle is reached; the density method takes the
+# modes the orientations ascend to.
+from __future__ import annotations
+
+import numpy as np
+
+from ..geometry.orientation import orientation
+from ..geometry.quaternion import rotation
+from ..geometry.units import degree
+from ..geometry.vector3d import vector3d
+from ..geometry.install import install
+
+
+# ------------------------------------------------------------------ CLASSIX
+
+# the entries of one block of distances when the small clusters are dissolved
+DISSOLVE_BLOCK = 1 << 22
+
+
+def classix(X, radius, minPts=1, mergeScale=1.5, mergeTiny=True):
+  """one cluster label per row of X, counted from zero"""
+  X = np.asarray(X, dtype=float)
+  if X.ndim == 1:
+    X = X[:, None]
+  n, d = X.shape
+  if n == 0:
+    return np.zeros(0, dtype=int)
+  if radius <= 0:
+    raise ValueError("the radius must be positive")
+  # centre by the mean, scale by the median norm
+  x = X - X.mean(axis=0)
+  scale = np.median(np.linalg.norm(x, axis=1))
+  x = x / (scale if scale > 0 else 1.0)
+  # the scores along the first principal axis, oriented deterministically
+  if d == 1:
+    u = x[:, 0].copy()
+  else:
+    vals, vecs = np.linalg.eigh(x.T @ x)
+    u = x @ vecs[:, np.argmax(np.abs(vals))]
+  u = u * (1.0 if u[0] == 0 else -np.sign(u[0]))
+  perm = np.argsort(u, kind="stable")
+  x, u = x[perm], u[perm]
+  halfN = np.sum(x * x, axis=1) / 2
+  halfR2 = radius ** 2 / 2
+  # aggregation: the first group within the radius takes the point
+  label = np.full(n, -1)
+  centres, sizes = [], []
+  for i in range(n):
+    if label[i] >= 0:
+      continue
+    lab = len(centres)
+    centres.append(i)
+    sizes.append(1)
+    label[i] = lab
+    hi = np.searchsorted(u, u[i] + radius, side="right")
+    if hi <= i + 1:
+      continue
+    window = slice(i + 1, hi)
+    close = (label[window] < 0) & (halfN[window] - x[window] @ x[i] <= halfR2 - halfN[i])
+    idx = np.flatnonzero(close) + i + 1
+    label[idx] = lab
+    sizes[lab] += idx.size
+  centres, sizes = np.array(centres), np.array(sizes)
+  ng = len(centres)
+  # merge the group centres within mergeScale times the radius by union find
+  gx, gu, gh = x[centres], u[centres], halfN[centres]
+  parent = np.arange(ng)
+
+  def find(a):
+    while parent[a] != a:
+      parent[a] = parent[parent[a]]
+      a = parent[a]
+    return a
+
+  mr = mergeScale * radius
+  for i in range(ng):
+    if not mergeTiny and sizes[i] < minPts:
+      continue
+    hi = np.searchsorted(gu, gu[i] + mr, side="right")
+    if hi <= i + 1:
+      continue
+    window = slice(i + 1, hi)
+    close = gh[window] - gx[window] @ gx[i] <= mr ** 2 / 2 - gh[i]
+    if not mergeTiny:
+      close &= sizes[window] >= minPts
+    ri = find(i)
+    for j in np.flatnonzero(close) + i + 1:
+      rj = find(j)
+      if ri != rj:
+        if ri < rj:
+          parent[rj] = ri
+        else:
+          parent[ri] = rj
+          ri = rj
+  gLabel, counts = _renumber(np.array([find(k) for k in range(ng)]), sizes)
+  # dissolve the clusters below minPts into the nearest group of a large enough cluster
+  if np.any(counts < minPts):
+    fixed = gLabel.copy()
+    large = counts[fixed] >= minPts
+    if np.any(large):
+      # every group of a small cluster to the nearest group of a large one, in blocks of rows
+      small = np.flatnonzero(~large)
+      step = max(1, DISSOLVE_BLOCK // len(gh))
+      for a in range(0, len(small), step):
+        g = small[a:a + step]
+        dist = gh - gx[g] @ gx.T
+        dist[:, ~large] = np.inf
+        gLabel[g] = fixed[np.argmin(dist, axis=1)]
+      gLabel, counts = _renumber(gLabel, sizes)
+  out = np.empty(n, dtype=int)
+  out[perm] = gLabel[label]
+  return out
+
+
+# the labels renamed to 0..K-1, in order of appearance, with the points per cluster
+def _renumber(gLabel, sizes):
+  uniq, inv = np.unique(gLabel, return_inverse=True)
+  counts = np.bincount(inv, weights=sizes, minlength=len(uniq)).astype(int)
+  return inv, counts
+
+
+def knnRadius(X, k=10, sub=1500):
+  """the median distance to the tenth nearest neighbour of a subsample, the estimate CLASSIX suggests"""
+  from scipy.spatial import cKDTree
+  X = np.asarray(X, dtype=float)
+  n = len(X)
+  if n <= k + 1:
+    return 1.0
+  idx = np.arange(n) if n <= sub else np.unique(np.round(np.linspace(0, n - 1, sub)).astype(int))
+  d, _ = cKDTree(X).query(X[idx], k=k + 1)
+  return float(np.median(d[:, -1]))
+
+
+# ------------------------------------------------------------------ the clusters of directions and orientations
+
+def calcCluster(x, *args, method=None, radius=None, minPoints=None, mergeScale=1.5, numCluster=None, maxAngle=None,
+                halfwidth=5 * degree, weights=None, resolution=2.5 * degree, verbose=False):
+  """the clusters of directions or orientations: one cluster id per element, counted from
+  zero, and the centre of every cluster
+
+    cId, center = calcCluster(v)                                          directions by CLASSIX
+    cId, center = calcCluster(ori, method='classix', radius=0.1, minPoints=15)
+    cId, center = calcCluster(ori)                                        the modes of the density
+    cId, center = calcCluster(ori, method='hierarchical', maxAngle=15*degree)
+    cId, center = calcCluster(v, method='hierarchical', numCluster=5)
+  """
+  for a in args:
+    if isinstance(a, str):
+      method = a
+  isOri = isinstance(x, orientation)
+  if method is None:
+    method = "odf" if isOri else "classix"
+  if method == "classix":
+    return _classixCluster(x, radius, minPoints, mergeScale)
+  if method == "hierarchical":
+    return _hierarchical(x, numCluster, maxAngle, weights, resolution)
+  if method == "odf":
+    if not isOri:
+      raise ValueError("the density method clusters orientations; use 'classix' or 'hierarchical' for directions")
+    return _densityCluster(x, halfwidth, weights, numCluster)
+  raise ValueError("the method is 'classix', 'hierarchical' or 'odf'")
+
+
+def _classixCluster(x, radius, minPoints, mergeScale):
+  n = x.size
+  if isinstance(x, orientation):
+    from .embedding import embedding
+    X = embedding(x.flatten()).double()
+    r = 0.5 * knnRadius(X) / np.max(np.std(X, axis=0)) if radius is None else float(radius)
+  else:
+    v = x.flatten()
+    xyz = v.normalize().data
+    if v.antipodal:
+      X = np.stack([xyz[:, 0] ** 2, xyz[:, 1] ** 2, xyz[:, 2] ** 2, xyz[:, 0] * xyz[:, 1], xyz[:, 0] * xyz[:, 2], xyz[:, 1] * xyz[:, 2]], axis=1)
+    else:
+      X = xyz
+    r = 2 * knnRadius(X) if radius is None else float(radius)
+  mp = max(1, round(n / 100)) if minPoints is None else int(minPoints)
+  cId = classix(X, r, minPts=mp, mergeScale=mergeScale)
+  return cId.reshape(x.shape), _centers(x, cId)
+
+
+# the mean of every cluster, as the elements are: an axis mean for axes, a symmetry reduced
+# mean for orientations
+def _centers(x, cId):
+  K = int(cId.max()) + 1 if cId.size else 0
+  flat = x.flatten()
+  if isinstance(x, orientation):
+    q = np.stack([rotation(flat[cId == c].mean().data).data.reshape(4) for c in range(K)]) if K else np.zeros((0, 4))
+    return orientation(rotation(q), x.CS, x.SS, antipodal=x.antipodal)
+  data = np.stack([flat[cId == c].mean().data.reshape(3) for c in range(K)]) if K else np.zeros((0, 3))
+  return vector3d(data, antipodal=x.antipodal, frame=x.frame)
+
+
+# the modes of the density the orientations ascend to, the largest numCluster of them
+def _densityCluster(o, halfwidth, weights, numCluster):
+  from ..functions.characteristics import calcComponents
+  from ..functions.density import calcDensity
+  flat = o.flatten()
+  odf = calcDensity(flat, weights=weights, halfwidth=halfwidth)
+  modes, vol, cId = calcComponents(odf, seed=flat, weights=weights)
+  K = min(20 if numCluster is None else int(numCluster), modes.size)
+  cId = np.asarray(cId).astype(float)
+  cId[cId >= K] = np.nan
+  center = modes[:K]
+  # the points too far from their centre, beyond twice the mean angle, are dropped
+  for i in range(K):
+    mask = cId == i
+    if not np.any(mask):
+      continue
+    omega = flat[mask].angle(center[i])
+    far = np.flatnonzero(mask)[omega > 2 * np.mean(omega)]
+    cId[far] = np.nan
+  return cId.reshape(o.shape), center
+
+
+# the closest pair of centres merged, the mean weighted by the points behind them, until
+# the number of clusters or the angle between the centres is reached; a large list is
+# binned on a grid first
+def _hierarchical(x, numCluster, maxAngle, weights, resolution):
+  flat = x.flatten()
+  n = flat.size
+  w = np.ones(n) if weights is None else np.asarray(weights, dtype=float).ravel()
+  isOri = isinstance(x, orientation)
+  if n > 1000 and isOri:
+    from ..geometry.grids.so3grid import equispacedSO3Grid
+    g = equispacedSO3Grid(x.CS, x.SS, resolution=resolution)
+    ind, _ = g.find(flat)
+    gw = np.bincount(np.asarray(ind).ravel(), weights=w, minlength=g.size)
+    keep = gw > 0
+    _, center = _hierarchical(g.subGrid(keep), numCluster, maxAngle, gw[keep], resolution)
+    cId = _nearest(flat, center)
+    center = _centers(x, cId)
+    cId = _nearest(flat, center)
+    counts = np.bincount(cId, minlength=center.size)
+    order = np.argsort(-counts, kind="stable")
+    rank = np.empty_like(order)
+    rank[order] = np.arange(order.size)
+    cId = rank[cId]
+    center = center[order][counts[order] > 0]
+    return cId.reshape(x.shape), center
+  nTarget = 2 if numCluster is None else int(numCluster)
+  cosMax = -np.inf if maxAngle is None else np.cos(maxAngle)
+  members = [[i] for i in range(n)]
+  # the coordinates of the centres, one row each, the merged ones kept but never read again
+  C = np.array(flat.data.reshape(n, -1), dtype=float)
+  d = _similarity(flat, flat)
+  np.fill_diagonal(d, -np.inf)
+  alive = np.ones(n, dtype=bool)
+  while np.count_nonzero(alive) > nTarget:
+    k = int(np.argmax(d))
+    i, j = divmod(k, n)
+    if d[i, j] < cosMax:
+      break
+    members[i] += members[j]
+    members[j] = []
+    alive[j] = False
+    sel = np.array(members[i])
+    centre = flat[sel].mean(weights=w[sel])
+    C[i] = centre.data.reshape(-1)
+    dd = _similarity(centre, flat._new(C)).ravel()
+    dd[~alive] = -np.inf
+    dd[i] = -np.inf
+    d[i, :] = dd
+    d[:, i] = dd
+    d[j, :] = -np.inf
+    d[:, j] = -np.inf
+  cId = np.empty(n, dtype=int)
+  keep = np.flatnonzero(alive)
+  for c, i in enumerate(keep):
+    cId[members[i]] = c
+  center = flat._new(C[keep])
+  return cId.reshape(x.shape), center
+
+
+# the cosine of the angle between every pair, reduced by the symmetry
+def _similarity(a, b):
+  A, B = a.reshape(-1, 1), b.reshape(1, -1)
+  return np.cos(A.angle(B))
+
+
+def _nearest(x, center):
+  return np.argmin(x.reshape(-1, 1).angle(center.reshape(1, -1)), axis=1)
+
+
+def _install():
+  install((vector3d, orientation), calcCluster)
+
+
+_install()
+
+__all__ = ["calcCluster", "classix", "knnRadius"]

mtex/analysis/data/__init__.py

@@ -0,0 +1 @@
+"""the data tables of the function layer"""