Five Degree-of-Freedom Grain Boundary Interpolation

⚠️ NOTE: As of 2026-02-24, we are in the process of refactoring this codebase, including correcting a helper function within one of the GB conversion scripts

Code related to meshing, interpolation, and distance calculations of grain boundaries by representing 5DOF of grain boundaries as grain boundary octonions (GBOs) and mapping them into a Voronoi Fundamental Zone (VFZ). (https://github.com/sgbaird-5DOF/interp)

<img src=https://user-images.githubusercontent.com/45469701/152452613-2cab0239-1412-4a6c-8fb7-7af9f810be33.png width=750> ^{Figure adapted based on table of contents from DOI: 10.1016/j.commatsci.2021.110756 (a) 2D analogy of a Grain Boundary Octonion Voronoi Fundamental Zone (GBO-VFZ) with dark blue points within the VFZ, with the VFZ defined by the reference point (white) and Oh point group. (b) grain boundary energy (GBE) values plotted continuously between two arbitrary grain boundary octonions (i.e. changes in all 5DOF). (c) Hexagonally binned parity plot of GPR predictions colored by number of points per bin, log colorscale.}

We go over dependencies, getting started instructions including installation, basic usage, distance calculations, plotting, and using custom datasets. Finally, we go over the file dependencies (no additional installation needed), short descriptions of various files in the repository, advanced installation, and citing information.

To quickly navigate the README table of contents, use the table of contents button <img src=https://user-images.githubusercontent.com/45469701/116359125-a68e5200-a7bb-11eb-8eba-dbea2acf653c.png width=30> at the top-left of the GitHub README window.

Dependencies

MATLAB Version

MATLAB R2019b or higher (mainly for the arguments ... end syntax checking at the beginning of functions, which is used extensively throughout).

R2007a - R2019a

I suggest removing the arguments ... end syntax for any functions that use this and replacing it with corresponding inputParser() and varargin code to deal with variable input arguments, default parameter values, and repeating arguments. Alternatively, you could remove the arguments ... end syntax lines for each function and update every place that the function is called so that all input arguments are specified. Open up an issue if you need more details on this. Other functions may need to be replaced if they aren't available in early MATLAB versions.

MATLAB Toolboxes

• Statistics and Machine Learning Toolbox (for Gaussian Process Regression: fitrgp(), fitrgp.predict())
• Parallel Computing Toolbox (parfor, optional)
• Symbolic Math Toolbox (optional, for numStabBary.m)

<!---, but for fitrgp() may need to change `hyperopts = struct('UseParallel',true,'Optimizer','bayesopt','MaxObjectiveEvaluations',maxhyperobj);` to `hyperopts = struct('UseParallel',false,'Optimizer','bayesopt','MaxObjectiveEvaluations',maxhyperobj);` in [interp5DOF.m](code/interp5DOF.m) under "method-specific interpolation" section 'gpr' case.) --->

Files

See File dependencies for a list of files that interp5DOF.m depends on.

Getting Started

Quick Installation

The quickest way to install the code is downloading and unzipping the latest release or latest version, add all subfolders of interp to the path via addpath(genpath(".")), and make sure it's working by running interp5DOF_test. For additional details or development instructions, see advanced installation.

Basic Usage

See interp5DOF.m, which is a high-level function for Gaussian Process Regression (GPR), barycentric, nearest neighbor (NN), and inverse-distance weighting (IDW) interpolation. This involves importing/generating data and computing an interpolation.

interp5DOF.m can be called in other functions/scripts to produce interpolation results using 5DOF misorientation/boundary plane normal pairs (qm/nA) and grain boundary property values. It was written with loosely similar input/output structure to the MATLAB built-in function interpn() involving input points and values, query points and values, and options.

For a short description of the various functions included in this repository, see Contents.m or this section.

Simple Example Data

Separate from interp5DOF_test.m, the following is a fast, bare-bones example to show the basic input/output format of interp5DOF.m. See also get_cubo.m

cd code/
addpath(genpath("."))
npts = 100;
qm = get_cubo(npts); nA = normr(rand(npts,3)); %random (qm,nA) pairs
propList = 1:npts; %property values
qm2 = get_cubo(npts); nA2 = normr(rand(npts,3)); %random (qm,nA) pairs
method = 'gpr'; %interpolation method
[propOut,interpfn,mdl,mdlpars] = interp5DOF(qm,nA,propList,qm2,nA2,method)

Test functions

Most functions have a corresponding "test" function (e.g. hsphext_subdiv.m --> hsphext_subdiv_test.m, interp5DOF.m --> interp5DOF_test.m) which gives simple usage example(s). These are useful for debugging, visualizations, and understanding the functions without having to do a full run which could be time-consuming. This also allows for the non-test function code to be more succinct, as certain plotting routines can be moved to the test function instead. The various test functions generally run to completion within a few seconds, and the parameters can generally be changed freely (e.g. dimension, number of points). Some test functions have specific plotting routines for 1-sphere (2D) and 2-sphere (3D) cases since a 7-sphere is difficult to visualize and interpret (n-sphere). For example, see sphbary_test.m and toBPFZ_test.m.

Distance Calculations

If you only want to (manually) compute distances in the VFZ sense, first you need to map all GBs into a VFZ.

npts = 100;
o = get_ocubo(npts); %generate some random data
o = get_octpairs(o); %symmetrize (using default reference GBO), vecnorm(o(1,:)) == ~sqrt(2)
o = normr(o); % normalize

At this point, you can get the VFZ pairwise distance matrix via:

pd = pdist(o);
mat = squareform(pd);

The units will be the same as is given by eq.(1) from DOI: 10.1016/j.commatsci.2021.110756.

<img src=https://user-images.githubusercontent.com/45469701/152618082-91d597fb-6646-4156-89d2-98540eddadaa.png width=200>

To convert to the traditional GBO distance, multiply $d_E$ by a factor of 2.

Alternatively, pdist2() may be of interest if you want pairwise distances between two sets of points, or vecnorm() if you want to calculate distances between two lists of GBOs:

npts2 = 100;
o1 = get_ocubo(npts1);
o1 = get_octpairs(o1);
o1 = normr(o1);

o2 = get_ocubo(npts2);
o2 = get_octpairs(o2);
o2 = normr(o2)

d = vecnorm(o1-o2,2,2); %o1 and