refine_orientation_projection_center#

EBSD.refine_orientation_projection_center(xmap: CrystalMap, detector: EBSDDetector, master_pattern: EBSDMasterPattern, energy: int | float, navigation_mask: np.ndarray | None = None, signal_mask: np.ndarray | None = None, pseudo_symmetry_ops: Rotation | None = None, method: str | None = 'minimize', method_kwargs: dict | None = None, trust_region: tuple | list | np.ndarray | None = None, initial_step: tuple | list | np.ndarray | None = None, rtol: float | None = 0.0001, maxeval: int | None = None, compute: bool = True, rechunk: bool = True, chunk_kwargs: dict | None = None) Tuple[CrystalMap, EBSDDetector] | da.Array[source]#

Refine orientations and projection centers simultaneously by searching the orientation and PC parameter space.

Refinement attempts to maximize the similarity between patterns in this signal and simulated patterns projected from a master pattern. The only supported similarity metric is the normalized cross-correlation (NCC). The orientation, represented by a Euler angle triplet (\(\phi_1\), \(\Phi\), \(\phi_2\)) relative to the EDAX TSL sample reference frame RD-TD-ND, is optimized during refinement, while the sample-detector geometry, represented by the three projection center (PC) parameters (PCx, PCy, PCz) in the Bruker convention, is fixed.

A subset of the optimization methods in SciPy and NLopt are available:

Parameters:
xmap

Crystal map with points to refine. Only the points in the data (see CrystalMap) are refined. If a navigation_mask is given, points equal to points in the data and points equal to False in this mask are refined.

detector

Detector describing the detector-sample geometry with either one PC to be used for all map points or one for each point. Which PCs are refined depend on xmap and navigation_mask.

master_pattern

Master pattern in the square Lambert projection of the same phase as the one in the crystal map.

energy

Accelerating voltage of the electron beam in kV specifying which master pattern energy to use during projection of simulated patterns.

navigation_mask

A boolean mask of points in the crystal map to refine (equal to False, i.e. points to mask out are True). The mask must be of equal shape to the signal’s navigation shape. If not given, all points in the crystal map data are refined.

signal_mask

A boolean mask of detector pixels to use in refinement (equal to False, i.e. pixels to mask out are True). The mask must be of equal shape to the signal’s signal shape. If not given, all pixels are used.

pseudo_symmetry_ops

Pseudo-symmetry operators as rotations. If given, each map point will be refined using the map orientation and the orientation after applying each operator. The chosen solution is the one with the highest score. E.g. if two operators are given, each map point is refined three times. If given, the returned crystal map will have a property array with the operator index giving the best score, with 0 meaning the original map point gave the best score.

method

Name of the scipy.optimize or NLopt optimization method, among "minimize", "differential_evolution", "dual_annealing", "basinhopping", "shgo" and "ln_neldermead" (from NLopt). Default is "minimize", which by default performs local optimization with the Nelder-Mead method, unless another "minimize" method is passed to method_kwargs.

method_kwargs

Keyword arguments passed to the scipy.optimize method. For example, to perform refinement with the modified Powell algorithm from SciPy, pass method="minimize" and method_kwargs=dict(method="Powell"). Not used if method="LN_NELDERMEAD".

trust_region

List of three +/- angular deviations in degrees as bound constraints on the three Euler angles and three +/- deviations in the range [0, 1] as bound constraints on the PC parameters, e.g. [2, 2, 2, 0.05, 0.05, 0.05]. Not passed to SciPy method if it does not support bounds. The definition ranges of the Euler angles are \(\phi_1 \in [0, 360]\), \(\Phi \in [0, 180]\) and \(\phi_2 \in [0, 360]\) in radians, while the definition range of the PC parameters are assumed to be [-2, 2].

initial_step

A list of two initial step sizes to use, one in degrees for all Euler angles and one in the range [0, 1] for all PC parameters. Only used if method="LN_NELDERMEAD".

rtol

Stop optimization of a pattern when the difference in NCC score between two iterations is below this value (relative tolerance). Only used if method="LN_NELDERMEAD". If not given, this is set to 1e-4.

maxeval

Stop optimization of a pattern when the number of function evaluations exceeds this value, e.g. 100. Only used if method="LN_NELDERMEAD".

compute

Whether to refine now (True) or later (False). Default is True. See compute() for more details.

rechunk

If True (default), rechunk the dask array with patterns used in refinement (not the signal data inplace) if it is returned from get_dask_array() in a single chunk. This ensures small data sets are rechunked so as to utilize multiple CPUs.

chunk_kwargs

Keyword arguments passed to get_chunking() if rechunk=True and the dask array with patterns used in refinement is returned from get_dask_array() in a single chunk.

Returns:
out

If compute=True, a crystal map with refined orientations, NCC scores in a "scores" property, the number of function evaluations in a "num_evals" property and which pseudo-symmetry operator gave the best score if pseudo_symmetry_ops is given is returned, as well as a new EBSD detector with the refined PCs. If compute=False, a dask array of navigation size + (8,) (or (9,) if pseudo_symmetry_ops is passed) is returned, to be computed later. See compute_refine_orientation_projection_center_results(). Each navigation point in the data has the score, the number of function evaluations, the three Euler angles in radians, the three PC parameters and potentially the pseudo-symmetry operator index in element 0, 1, 2, 3, 4, 5, 6, 7, 8 and 9, respectively.

Notes

If the crystal map to refine contains points marked as not indexed, the returned detector might not have a 2D navigation shape.

The method attempts to refine the orientations and projection center at the same time for each map point. The optimization landscape is sloppy [Pang et al., 2020], where the orientation and PC can make up for each other. Thus, it is possible that the parameters that yield the highest similarity are incorrect. As always, it is left to the user to ensure that the output is reasonable.

NLopt is for now an optional dependency, see Optional dependencies for details. Be aware that NLopt does not fail gracefully. If continued use of NLopt proves stable enough, its implementation of the Nelder-Mead algorithm might become the default.