morphogen.orientations

Orientation distributions of fibre axes, and random crystallographic orientations.

Fibre axes are given in configuration files as:

orientation: isotropic                              # uniform on the unit sphere
orientation: {type: aligned, direction: [0, 0, 1]}  # all fibres along a direction
orientation: {type: planar, normal: [0, 0, 1]}      # uniform in the plane normal to `normal`
orientation: {type: beta, beta: 0.1, axis: [0, 0, 1]}  # Schladitz's beta law about `axis`
orientation: {type: girdle, sigma: 0.4, axis: [0, 0, 1]}  # Gaussian girdle (Chatti et al.)
orientation: {type: von_mises_fisher, kappa: 10, axis: [0, 0, 1]}  # about `axis`
orientation: {type: mixture, laws: [...], weights: [0.4, 0.6]}  # Altendorf et al. 2014

Every law has a quadrature (OrientationDistribution.quadrature()): axes and weights that average functions of the axis (the covariances of the fibre models), and angle_weights() gives the law of the angle between the axes and a direction.

Crystal orientations are Bunge Euler angles (phi1, Phi, phi2), convention ZXZ, of rotations drawn uniformly on SO(3), of a fibre texture about the axes of one of these laws (fibre_orientations()), or of the texture of an orientation map:

texture: {type: measured, file: map.ctf, spread: 2.0}  # the grains of an EBSD map
morphogen.orientations.ANGLE_GRID = 193

Angles of the uniform grid of [0, pi/2] on which functions of the angle between an axis and a direction are tabulated when a law has more axes than that (angle_weights())

morphogen.orientations.uniform_unit_vectors(rng: Generator, n: int) → ndarray[source]

n directions uniformly distributed on the unit sphere.

morphogen.orientations.orthonormal_basis(directions: ndarray) → tuple[ndarray, ndarray][source]

Two unit vectors completing each direction into a right-handed orthonormal basis.

class morphogen.orientations.OrientationDistribution[source]

Bases: ABC

Distribution of undirected axes.

abstractmethod sample(rng: Generator, n: int) → ndarray[source]

Draw n unit vectors, shape (n, 3).

abstractmethod to_config()[source]

Plain configuration value.

quadrature(n: int = 24) → tuple[ndarray, ndarray][source]

Axes (m x 3) and weights (m, summing to 1) such that sum(w f(u)) approximates E[f(u)] for smooth functions of the axis. The laws below have rules of their own; this default takes 8 n^2 axes drawn from a fixed seed (a deterministic Monte Carlo rule).

class morphogen.orientations.Isotropic[source]

Bases: OrientationDistribution

sample(rng, n)[source]

Draw n unit vectors, shape (n, 3).

to_config()[source]

Plain configuration value.

quadrature(n=24)[source]

Gauss-Legendre in the cosine to z (n nodes) times 2n azimuths.

class morphogen.orientations.Aligned(direction: 'tuple[float, float, float]' = (0.0, 0.0, 1.0))[source]

Bases: OrientationDistribution

sample(rng, n)[source]

Draw n unit vectors, shape (n, 3).

to_config()[source]

Plain configuration value.

quadrature(n=24)[source]

Axes (m x 3) and weights (m, summing to 1) such that sum(w f(u)) approximates E[f(u)] for smooth functions of the axis. The laws below have rules of their own; this default takes 8 n^2 axes drawn from a fixed seed (a deterministic Monte Carlo rule).

class morphogen.orientations.Planar(normal: tuple[float, float, float] = (0.0, 0.0, 1.0))[source]

Bases: OrientationDistribution

Directions uniformly distributed in the plane orthogonal to normal.

sample(rng, n)[source]

Draw n unit vectors, shape (n, 3).

to_config()[source]

Plain configuration value.

quadrature(n=24)[source]

8n equally spaced azimuths in the plane (the trapezoidal rule).

class morphogen.orientations.Beta(beta: float = 1.0, axis: tuple[float, float, float] = (0.0, 0.0, 1.0))[source]

Bases: OrientationDistribution

The beta law of Schladitz et al. (2006) about axis (Ohser & Schladitz 2009), of density beta sin(t) / (4 pi (1 + (beta^2 - 1) cos^2 t)^(3/2)) in the angle t to the axis: uniform for beta = 1, concentrated on the axis as beta -> 0 and on the plane normal to it as beta -> infinity. Drawn as isotropic directions whose component along the axis is divided by beta (the angular central Gaussian law of diag(1, 1, 1 / beta^2)), so that P(|cos t| <= c) = beta c / sqrt(1 + (beta^2 - 1) c^2).

sample(rng, n)[source]

Draw n unit vectors, shape (n, 3).

to_config()[source]

Plain configuration value.

quadrature(n=24)[source]

The quantiles c = u / sqrt(beta^2 (1 - u^2) + u^2) of |cos t| at n Gauss-Legendre nodes u of [0, 1], both signs, times 2n azimuths.

class morphogen.orientations.Girdle(sigma: float = 0.4, axis: tuple[float, float, float] = (0.0, 0.0, 1.0))[source]

Bases: OrientationDistribution

The Gaussian girdle of Chatti et al. (2018, eq. 3) about axis: the angle t to the axis of density proportional to sin(t) exp(-(t - pi/2)^2 / 2 sigma^2) on [0, pi] (sigma in radians), the azimuth uniform: axes gathered about the plane normal to the axis as sigma -> 0, isotropic as sigma grows (their compressed entangled fibres: 0.4; at most 20, where the density is within 0.4 % of the isotropic one: the rejection below keeps fewer draws as sigma grows). Drawn by rejection: normal angles truncated to [0, pi], each kept with the probability sin(t).

sample(rng, n)[source]

Draw n unit vectors, shape (n, 3).

to_config()[source]

Plain configuration value.

quadrature(n=24)[source]

2n Gauss-Legendre nodes of the angle t over pi/2 +- 8 sigma (within [0, pi]) weighted by its density, times 2n azimuths.

class morphogen.orientations.VonMisesFisher(kappa: float = 10.0, axis: tuple[float, float, float] = (0.0, 0.0, 1.0))[source]

Bases: OrientationDistribution

The von Mises-Fisher law about axis, of density kappa exp(kappa cos t) / (4 pi sinh kappa) in the angle t to the axis: uniform for kappa = 0, concentrated on the axis as kappa grows (E[1 - cos t] ~ 1 / kappa). Drawn by inverting the law of w = cos t, w = 1 + ln(u + (1 - u) e^(-2 kappa)) / kappa, the azimuth uniform (as the steps of morphogen.models.fibers.von_mises_fisher()).

sample(rng, n)[source]

Draw n unit vectors, shape (n, 3).

to_config()[source]

Plain configuration value.

quadrature(n=24)[source]

The quantiles of cos t at 2n Gauss-Legendre nodes of [0, 1], times 2n azimuths.

class morphogen.orientations.Mixture(laws: tuple[OrientationDistribution, ...] = (Isotropic(),), weights: tuple[float, ...] | None = None)[source]

Bases: OrientationDistribution

A mixture of laws: an axis follows laws[i] with the probability weights[i] (normalized), as the mixed beta laws of Altendorf, Jeulin & Willot (2014, eq. 2), an orthotropic law of glass fibres (0.393 of a beta law of 0.114 about z, 0.607 of one of 10.1 about a normal to it).

sample(rng, n)[source]

Draw n unit vectors, shape (n, 3).

to_config()[source]

Plain configuration value.

quadrature(n=24)[source]

The rules of the laws, their weights times those of the mixture.

class morphogen.orientations.Measured(file: str = '', spread: float = 0.0, threshold: float = 5.0, min_size: int = 5, phase: int | None = None, axes: str = 'map', setting: int = 1)[source]

Bases: OrientationDistribution

The texture of an orientation map (EBSD, morphogen.io.ebsd): the crystals have the orientations of the grains of the map (file: an .ang or a .ctf file, or the name of a map that comes with morphoGen; threshold and min_size: those of its grains; axes and setting: those of its orientations), each drawn with the area of its grain, then turned about a random axis by an angle of the half-normal law of standard deviation spread degrees (0: the orientations of the grains themselves). phase: the phase of the map whose grains are taken (the one of largest area by default). As a law of axes, it is that of the third axes of these crystals.

grains()[source]

The orientations (Bunge angles, degrees) and the areas of the grains of the phase of the map, and the Laue class of that phase.

orientations(rng: Generator, n: int) → ndarray[source]

Bunge angles (degrees) of n crystals of the texture of the map.

sample(rng, n)[source]

Draw n unit vectors, shape (n, 3).

to_config()[source]

Plain configuration value.

morphogen.orientations.half_sphere(n: int = 6) → tuple[ndarray, ndarray][source]

Directions of the half sphere z >= 0 and their weights (summing to 1): n Gauss-Legendre cosines times 2n azimuths, the mean over the directions of an even function (f(-u) = f(u)).

morphogen.orientations.angle_weights(orientation: OrientationDistribution, direction=None, n: int = 24, *, grid: bool = False)[source]

The angles b in [0, pi/2] between the axes of orientation and direction (between undirected lines) and their weights, so that sum(w f(b)) approximates E[f(b)]: 128 Gauss-Legendre nodes of cos b in [0, 1] for isotropic axes or without a direction (a direction uniform on the sphere); otherwise the angles of the axes of the quadrature of the law, gathered on the ANGLE_GRID nodes of a uniform grid of [0, pi/2] when there are more, or always with grid (the weight of an angle shared by the two nodes about it, in proportion to their nearness: linear interpolation of f).

morphogen.orientations.orientation_from_config(value, name: str = 'orientation') → OrientationDistribution[source]

An orientation distribution from a configuration value: its name (isotropic) or a mapping with its type (isotropic, aligned, planar, beta, girdle, von_mises_fisher, mixture; measured: the texture of an orientation map) and parameters.

morphogen.orientations.random_orientations(rng: Generator, n: int, *, degrees: bool = True) → ndarray[source]

Bunge Euler angles (phi1, Phi, phi2) of n rotations uniform on SO(3).

Uniformity on SO(3) means phi1 and phi2 uniform on [0, 2 pi) and cos(Phi) uniform on [-1, 1] (the Haar measure is sin(Phi) dphi1 dPhi dphi2 / 8 pi^2).

morphogen.orientations.fibre_orientations(rng: Generator, n: int, law: OrientationDistribution, *, degrees: bool = True) → ndarray[source]

Bunge Euler angles of n crystals of a fibre texture: the third axis of each crystal (the axis c of a hexagonal lattice) is a direction of the sample drawn from law (VonMisesFisher about an axis: a basal texture; Planar: axes c in a plane…), and the crystal is turned about it by a uniform angle. A measured texture (Measured) gives the orientations of the grains of its map.

morphogen.orientations.euler_to_matrix(euler, *, degrees: bool = True) → ndarray[source]

Bunge (ZXZ, passive) rotation matrices g, crystal = g @ sample, shape (n, 3, 3).

morphogen.orientations.matrix_to_euler(g, *, degrees: bool = True) → ndarray[source]

Inverse of euler_to_matrix(); angles in [0, 360) x [0, 180] x [0, 360).