Five Degree-of-Freedom Grain Boundary Interpolation

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

See

1. Baird, S. G.; Homer, E. R.; Fullwood, D. T.; Johnson, O. K. Five Degree-of-Freedom Property Interpolation of Arbitrary Grain Boundaries via Voronoi Fundamental Zone Octonion Framework. 2021. https://arxiv.org/abs/2104.06575 (Submitted to Computational Materials Science)
2. GB_octonion_code
3. Chesser, I., Francis, T., De Graef, M., & Holm, E. A. (2020). Learning the Grain Boundary Manifold: Tools for Visualizing and Fitting Grain Boundary Properties. Acta Materialia. https://doi.org/10.2139/ssrn.3460311
4. Francis, T., Chesser, I., Singh, S., Holm, E. A., & De Graef, M. (2019). A geodesic octonion metric for grain boundaries. Acta Materialia, 166, 135–147. https://doi.org/10.1016/j.actamat.2018.12.034

Table of Contents

Use the button at the top-left of the 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). For users of 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.

Toolboxes

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

Files

See File dependencies

Usage

See cloning a repository and git submodules for more information or other options such as using GitHub Desktop (Windows, Linux, etc.) or downloading a .zip file. Forking, pull requests, and opening of issues are welcome/encouraged. Note that the .zip files will not contain submodules, which means that you'll need to download any submodules individually if you go that route (bare minimum would be the MATslurm repository). Instead of downloading a .zip file, I suggest instead downloading and using GitHub Desktop. If you run into issues with the repository, you can download a lightweight version of interp5DOF.m and its dependencies, unzip it, and read README.txt for instructions, but please open up an issue in the GitHub repo if you do run into trouble with the repo. That way, you can get the most recent updates and others can benefit from it.

Basic steps:

• Step 0: download the code
• Step 1: set interp-5DOF/code/ as working directory
• Step 2: add subfolders to path (addpath(genpath('.'))) and run interp5DOF_test.m

Platform-specific directions

Linux

Step 0: download the code

git -c submodule.interp5DOF-paper.update=none clone --recurse-submodules https://github.com/sgbaird-5DOF/interp.git

Verify that MATslurm is not an empty directory.

Step 1: open MATLAB and navigate to navigate to interp-5DOF/code/

matlab

>> cd interp-5DOF/code/

Step 2: Add subfolders to path and run interp5DOF_test.m

>> addpath(genpath('.'))

>> interp5DOF_test

Windows

Step 0: download the code

Open GitHub Desktop and make a dummy repository via Ctrl+N so that you can open Git Bash via GitHub Desktop. Then clone and/or fork https://github.com/sgbaird-5DOF/interp.git by opening the Git Bash command line (i.e. Menubar --> Repository --> "Open in Git Bash" or

Ctrl+`

) then run the following command in the directory where you want interp to appear:

git -c submodule.interp5DOF-paper.update=none clone --recurse-submodules https://github.com/sgbaird-5DOF/interp.git

Alternatively, you can try cloning directly in GitHub Desktop or via the "Open in GitHub Desktop" button under , but it will likely throw an error, and I'm not sure if it will correctly clone the MATslurm submodule by the time it reaches that error. MATslurm is a bare minimum requirement for running interp5DOF.m. Attempt at your own risk.

The submodules should be downloaded automatically. In order to update these submodules, add these to GitHub desktop as well ("add from existing", navigate within interp folder to the submodule, click on submodule folder, and "add").

Step 1: open MATLAB and navigate to navigate to interp-5DOF/code/

Set interp-5DOF/code/ as working directory via cd or GUI

Step 2: Add subfolders to path and run interp5DOF_test.m

>> addpath(genpath('.'))

>> interp5DOF_test

Getting started

Look at 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.

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

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)

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

pd = pdist(o);

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;
o2 = get_ocubo(npts2);
o2 = get_octpairs(o2);
d = vecnorm(o1-o2,2,2); %o1 and o2 need to be the same size

If you want the "true" minimum distances (i.e. essentially the same implementation as GB_octonion_code, but vectorized and parallelized), you may use GBdist4.m directly with two sets of GBOs.

d = GBdist4(o1,o2);

It depends on the application, but if you want to compute large pairwise distance matrices that are nearly identical to the traditional GBO distances, I recommend using the ensembled VFZ distance via ensembleGBdist.m with K >= 10. This will be much faster than using GBdist4.m. For reference, this corresponds to (from the main paper when K==10):

This is distinct from ensembleVFZO.m, which takes the average interpolated property from K different VFZs.

Drop me a note in "Issues" if you have something you'd like to do or something you'd like to clarify, but can't figure out among the (many) options and functions in the interp repo. With a few details, there's a good chance I can offer some suggestions that will save a lot of time.

Plots

Most plots in the paper are produced in the script: plotting.m. First, you need to create a dummy folder:

mkdir interp/code/interp5DOF-paper/figures/

The larger file dependencies, gitID-0055bee_uuID-475a2dfd_paper-data6.mat and gpr46883_gitID-b473165_puuID-50ffdcf6_kim-rng11.mat can be downloaded at figshare and have the following citation:

@misc{baird_homer_fullwood_johnson_2021, title={Five Degree-of-Freedom Grain Boundary Interpolation}, url={https://figshare.com/articles/dataset/gitID-0055bee_uuID-475a2dfd_paper-data6_mat/14405924/3}, DOI={10.6084/m9.figshare.14405924.v3}, abstractNote={These are larger MATLAB .mat files required for reproducing plots from the sgbaird-5DOF/interp repository for grain boundary property interpolation. gitID-0055bee_uuID-475a2dfd_paper-data6.mat contains multiple trials of five degree-of-freedom interpolation model runs for various interpolation schemes. gpr46883_gitID-b473165_puuID-50ffdcf6_kim-rng11.mat contains a Gaussian Process Regression model trained on 46883 Fe simulation GBs.}, publisher={figshare}, author={Baird, Sterling and Homer, Eric R and Fullwood, David and Johnson, Oliver K.}, year={2021}, month={Apr} }

Data Preparation

Input GBs can take on the following forms:

• misorientation (qm) / boundary plane normal (nA) pairs
• octonions (o)

Prediction GBs have a 2 appended, as in qm2. The inputs are stacked vertically (i.e. 1st row corresponds to 1st GB, 2nd row to 2nd GB, etc.).

Data can be converted between forms/conventions using the various rotation functions available in the repository (modified versions of GB Octonion Code).

Active vs. Passive Rotation Convention

Active rotation is specified with an input parameter 'epsijk' == 1 and is the default used throughout the work. Passive rotation, in theory, can be specified via epsijk == -1 which should be propagated throughout the entire codebase via the top-level input, but this has not undergone the same extensive testing as the active rotation convention. To convert from the passive to the active rotation convention, I suggest converting the GB into octonion form and applying qinv.m to each grain boundary, that is:

o = [qinv(o(1:4,:) qinv(o(5:8,:))];

or simply

o = oflip(o);

parfor loops

Parfor loops are used by default where there is potential for significant speed-up. A parfor-compatible text progress bar is encoded into many of these. Adding disp() or fprintf() inside the parfor loop (aside from what's already inside the nested text progress bar function) may cause odd behavior on the command line output, but should not affect the integrity of the code execution. Because the parfor-compatible text progress bars need to be nested functions, in order to deal with the inability to add variables to static workspaces while debugging, you can either assign variables to "ans" (a special variable that is still accessible), output statements directly to the command line terminal (no variable assignment). Alternatively, you can comment the nested function, nUpdateProgress().

If the parallel computing toolbox is not installed, the parfor loops will execute as regular for loops. If the parallel computing toolbox is installed and you only want to use a single core, start a parallel pool with only one core before running any of the functions via parpool(1). The loop will still run internally as a parfor loop, however. A parfor loop with a single core and parallel computing toolbox should not run any slower than a regular for loop as long as they are contained within functions. A parfor loop executed within a script, however, is likely to result in significant slow-down.

To debug within a parfor loop, simply change it to a for loop while debugging and change it back afterwards. I added "parfor compatible" as a comment next to the parfor statements. Thus, you can use MATLAB find files (Ctrl+Shift+F) to search for the keyword "parfor compatible" (including quotes) in order to keep track of which parfor loops have been changed to for loops. If you make changes and an error arises, it is possible it will only give useful information at the top-level where the parfor started, hence the debugging suggestion above.

File dependencies

Take a look at parseReqFiles_test.m for generating a list of file dependencies for interp5DOF.m (below) or other files.

1. GB5DOF.m
2. GB5DOF_setup.m
3. PGnames.mat
4. PGsymops.mat
5. GBfive2oct.m
6. qinv_francis.m
7. qmult.m
8. GetPyramid.m
9. ax2qu.m
10. cu2ho.m
11. cu2qu.m
12. ho2ax.m
13. ho2qu.m
14. qu2om.m
15. GBdist4.m
16. GBlab2oct.m
17. get_gitcommit.m
18. get_uuid.m
19. structhorzcat.m
20. var_names.m
21. addpathdir.m
22. allcomb.m
23. constructGBMatrices.m
24. get_cubo.m
25. get_errmetrics.m
26. get_interp.m
27. get_knn.m
28. get_octpairs.m
29. get_ocubo.m
30. get_omega.m
31. get_sympairs.m
32. idw.m
33. get_ppts.m
34. get_pts.m
35. interp_avg.m
36. interp_bary.m
37. interp_bary_fast.m
38. interp_gpr.m
39. interp_idw.m
40. interp_nn.m
41. intersect_facet.m
42. mustBeSqrt2Norm.m
43. mustContainFields.m
44. normr.m
45. numStabBary.m
46. osymset.m
47. osymsets.m
48. proj_down.m
49. proj_up.m
50. projfacet2hyperplane.m
51. projray2hyperplane.m
52. projray2hypersphere.m
53. gmat2q.m
54. q2gmat.m
55. qconj.m
56. qinv_johnson.m
57. qmultiply.m
58. qnorm.m
59. sphbary.m
60. sphbary_setup.m
61. sphconvhulln.m
62. sqrt2norm.m
63. zeta_min2.m