- EBSD.refine_orientation(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: float = None, rtol: float = 0.0001, maxeval: int | None = None, compute: bool = True, rechunk: bool = True, chunk_kwargs: dict | None = None) CrystalMap | da.Array #
Refine orientations by searching orientation space around the best indexed solution using fixed projection centers.
Refinement attempts to maximize the similarity between patterns in this signal and simulated patterns projected from a master pattern. The similarity metric used 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:
Crystal map with points to refine. Only the points in the data (see
CrystalMap) are refined. If a
navigation_maskis given, points equal to points in the data and points equal to
Falsein this mask are refined.
Detector describing the detector-sample geometry with either one PC to be used for all map points or one for each point.
Master pattern in the square Lambert projection of the same phase as the one in the crystal map.
Accelerating voltage of the electron beam in kV specifying which master pattern energy to use during projection of simulated patterns.
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.
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 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.
Name of the
scipy.optimizeor NLopt optimization method, among
"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
Keyword arguments passed to the
method. For example, to perform refinement with the modified Powell algorithm from SciPy, pass
method_kwargs=dict(method="Powell"). Not used if
List of three +/- angular deviations in degrees used to determine the bound constraints on the three Euler angles per navigation point, e.g.
[2, 2, 2]. Not passed to SciPy
methodif 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.
A single initial step size for all Euler angle, in degrees. Only used if
method="LN_NELDERMEAD". If not given, this is not set for the NLopt optimizer.
Stop optimization of a pattern when the difference in NCC score between two iterations is below this value (relative tolerance). Default is
1e-4. Only used if
Stop optimization of a pattern when the number of function evaluations exceeds this value, e.g.
100. Only used if
Whether to refine now (
True) or later (
False). Default is
compute()for more details.
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.
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_opsis given is returned.. If
compute=False, a dask array of navigation size + (5,) (or (6,) if
pseudo_symmetry_opsis passed) is returned, to be computed later. See
compute_refine_orientation_results(). Each navigation point in the data has the optimized score, the number of function evaluations, the three Euler angles in radians and potentially the pseudo-symmetry operator index in element 0, 1, 2, 3, 4 and 5, respectively.
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.