hexrd.phase_transition.texture.unimodal_odf module

Unimodal Orientation Distribution Function (ODF)

Implements a kernel-based ODF with a single or multiple preferred orientations. Uses a combination of modal orientations and kernel functions to create smooth, localized texture distributions.

class hexrd.phase_transition.texture.unimodal_odf.UnimodalODF(modal_orientations, kernel, weights=None)

Bases: object

Unimodal orientation distribution function.

Represents a texture with one or more preferred orientations around which crystal orientations are concentrated. Uses kernel functions to create smooth distributions around modal orientations.

Mathematical form: f(g) = Σᵢ wᵢ K(g, g₀ᵢ), Σᵢ wᵢ = 1 Because the de la Vallée Poussin kernel is normalized so its mean over SO(3) is 1 (MRD), this weighted sum is itself a valid ODF in MRD units (uniform texture = 1).

Parameters

modal_orientationsarray_like

Modal (preferred) orientation(s). Can be: - Single 3x3 rotation matrix - Array of shape (N, 3, 3) for N modal orientations

kernelDeLaValleePoussinKernel

Kernel function defining the shape of the distribution. The kernel is the single source of truth for symmetry: any crystal/sample symmetry must be set on the kernel, and the ODF exposes it via the crystal_symmetry/sample_symmetry properties.

weightsarray_like, optional

Weights for multiple modal orientations. Must sum to 1. If None, equal weights are used for multiple orientations.

Attributes

modal_orientationsnumpy.ndarray

Array of modal orientations, shape (N, 3, 3)

kernelDeLaValleePoussinKernel

Kernel function used for the distribution

weightsnumpy.ndarray

Component weights, shape (N,)

crystal_symmetrystr or None

Crystal symmetry label, delegated from the kernel

sample_symmetrystr or None

Sample symmetry label, delegated from the kernel

n_componentsint

Number of modal orientations

Examples

>>> from hexrd.phase_transition.texture import UnimodalODF
>>> from hexrd.phase_transition.texture import DeLaValleePoussinKernel
>>>
>>> # Single modal orientation (cubic crystal symmetry on the kernel)
>>> kernel = DeLaValleePoussinKernel(
...     halfwidth=np.radians(15), crystal_symmetry='oh'
... )
>>> modal = np.eye(3)  # Identity orientation
>>> odf = UnimodalODF(modal, kernel)
>>>
>>> # Evaluate at modal orientation (should give maximum value)
>>> value = odf.eval(modal)

analytic_texture_index() → float | None

Exact texture index J = <f^2> when a closed form is available.

For a single mode with no kernel symmetry, the de la Vallee Poussin ODF depends only on the misorientation angle from the mode, whose Haar density on SO(3) is p(omega) = (1 - cos omega) / pi. Integrating f^2 against it gives the closed form

J = (2 * C^2 / pi) * B(2*kappa + 1/2, 3/2),

where C and kappa are the kernel normalization constant and shape parameter. Multi-modal ODFs (cross terms between modes) and symmetry-reduced kernels have no simple closed form here, so this returns None and callers fall back to Monte Carlo estimation.

Returns

float or None

Exact texture index, or None if no closed form applies.

property crystal_symmetry

str or None: Crystal symmetry label, delegated from the kernel.

estimated_max_value()

Estimate the maximum ODF value, in MRD.

The ODF maxima occur at (or very near) the modal orientations, so this evaluates the full ODF at each mode and returns the largest value.

Returns

float

Maximum ODF value in MRD (multiples of a random distribution)

eval(orientations)

Evaluate unimodal ODF at given orientations.

Computes f(g) = Σᵢ wᵢ K(g, g₀ᵢ) for all input orientations, in MRD.

Parameters

orientationsarray_like

Orientation matrices of shape (…, 3, 3)

Returns

numpy.ndarray

ODF values with shape matching leading dimensions of input

Examples

>>> modal = np.eye(3)
>>> kernel = DeLaValleePoussinKernel(halfwidth=np.radians(10))
>>> odf = UnimodalODF(modal, kernel)
>>>
>>> # Single evaluation
>>> value = odf.eval(modal)  # Should give maximum
>>>
>>> # Batch evaluation
>>> Rs = np.array([np.eye(3), rotation_matrix_z(np.pi/4)])
>>> values = odf.eval(Rs)  # shape (2,)

property kernel

DeLaValleePoussinKernel: Kernel function.

property modal_orientations

numpy.ndarray: Modal orientations, shape (N, 3, 3).

property n_components

int: Number of modal orientations.

norm(n_orientations=100000, seed=None)

L2 norm ||f|| = sqrt(J) of the ODF (MTEX norm), in MRD.

Uses the exact closed form when available; otherwise estimates the norm by Monte Carlo over Haar-uniform orientations.

Parameters

n_orientationsint, optional

Number of Haar-uniform samples for the Monte Carlo fallback, default 100000. Ignored when the closed form applies.

seedint, optional

Random seed for the Monte Carlo fallback.

Returns

float

L2 norm ||f|| = sqrt(J) (>= 1 in MRD units).

property sample_symmetry

str or None: Sample symmetry label, delegated from the kernel.

texture_index(n_orientations=100000, seed=None)

Texture index J = <f^2> of the ODF, in MRD^2.

Uses the exact closed form when available (see analytic_texture_index); otherwise estimates J by Monte Carlo over Haar-uniform orientations.

Parameters

n_orientationsint, optional

Number of Haar-uniform samples for the Monte Carlo fallback, default 100000. Ignored when the closed form applies.

seedint, optional

Random seed for the Monte Carlo fallback.

Returns

float

Texture index J = <f^2> (>= 1 in MRD units).

property weights

numpy.ndarray: Component weights, shape (N,).