Five Degree-of-Freedom (5DOF) Interpolation

Code related to meshing and interpolation of grain boundaries by representing 5DOF of grain boundaries as octonions and mapping them into a Voronoi Fundamental Zone.

See

Baird, S., Homer, E., Fullwood, T., & Johnson, O. (2020). Five Degree-of-Freedom Property Interpolation of Arbitrary GrainBoundaries via Voronoi Fundamental Zone Octonion Framework. (Submitted to Acta Materialia)
GB_octonion_code
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
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

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, 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 under "method-specific interpolation" section --> 'gpr' case.)
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 and pull requests are welcome/encouraged.

Basic steps:

Step 0: download the code
Step 1: navigate to interp-5DOF/code/
Step 2: open MATLAB and call interp5DOF_test.m

Platform-specific directions

Linux

Step 0: download the code

git clone --recurse-submodules https://github.com/sgbaird-5DOF/interp.git

Verify that MATslurm is not an empty directory. If you're using GitHub Desktop, you may need to clone the directory with the above command using Git Bash, which can be opened via Ctrl-` or on the toolbar via Repository-->"Open in Git Bash".

Step 1: navigate to interp-5DOF/code/

cd interp-5DOF/code/

Step 2: open MATLAB and call interp5DOF_test.m

matlab

>> interp5DOF_test

Windows

Step 0: download the code

Open GitHub Desktop and clone and/or fork https://github.com/sgbaird-5DOF/interp.git The submodules should be downloaded automatically. If you want to commit to 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:

Navigate to interp-5DOF/code/

Step 2: open MATLAB and call interp5DOF_test.m

Accessing functions via addpathdir()

dir() and addpath() commands are used to locate functions in subfolders of the current working directory via a custom function addpathdir.m. This could give anomalous behavior if the directory structure is changed such that filenames are non-unique in sub-folders of the parent folder where addpathdir() gets called, or if files with the same name are present elsewhere on the user's MATLAB path.

Getting started

Look at interp5DOF.m, which is a top-level function for creating a mesh, importing/generating data, triangulating a mesh and identifying the intersecting facet for datapoints (if applicable), 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, input values, query points, and query values.

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 may be changed freely (e.g. dimension, number of points, etc.) where applicable. 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.

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, 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), or 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 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.

About

MIT License

Languages

Language:C++ 56.2%Language:MATLAB 42.1%Language:Mathematica 0.8%Language:C 0.7%Language:Shell 0.1%Language:Makefile 0.1%Language:CMake 0.0%Language:Objective-C 0.0%