The EBSDReader user object reads in data from electron backscatter diffraction (EBSD) to set initial conditions for phase field simulations. EBSD identifies the grain and phase structure of a sample, as well as the crystal structure and the crystal orientation. The EBSDReader reads in this information from a specially formatted data file and reconstructs the microstructure. It accomplishes this by setting the initial conditions for all the phase field variables. In addition, it stores the crystal structure and orientation information by use by the phase field and mechanics models.

Note that the EBSDReader does not mesh the microstructure, but rather sets phase field variable initial conditions. To reconstruct a mesh of the microstructure, we recommend using OOF.

# EBSD Data File Syntax

Reconstructed microstructure using EBSDReader, created using the phase_field module example file IN100-111grn.i

Reconstructed microstructure with stress, created using the combined module example file EBSD_reconstruction_grain_growth_mech.i

The EBSDReader user object reads in a data file taken from EBSD data. The file should have the format:

# Header:    Marmot Input File
# Date:      19-Jul-2013 00:23:55
#
# Column 1:  Euler angle "phi1" (in radians)
# Column 2:  Euler angle "PHI" (in radians)
# Column 3:  Euler angle "phi2" (in radians)
# Column 4:  x-coordinate (in microns)
# Column 5:  y-coordinate (in microns)
# Column 6:  z-coordinate (in microns)
# Column 7:  grain number (integer)
# Column 8:  phase number (integer)
# Column 9:  symmetry class (from TSL)
#
# Phase 1:   Nickel (symmetry class = 43)
# Number of Grains in Phase 1:  111
#
# X_Min:      0.000000
# X_Max:      32.000000
# X_step:     0.250000
# X_Dim:      128
#
# Y_Min:      0.000000
# Y_Max:      32.000000
# Y_step:     0.250000
# Y_Dim:      128
#
# Z_Min:      0.000000
# Z_Max:      0.000000
# Z_step:     0.000000
# Z_Dim:      0
#
2.48663 1.84098 5.50548 0.12500 0.12500 0.00000 0 1 43
2.48663 1.84098 5.50548 0.12500 0.37500 0.00000 0 1 43
.
.
.


The open source code Dream3D has the option to output in this format using the "Write INL File" filter. Note that the data must be on a square grid rather than a hex grid.

## EBSDMesh

Doxygen

The mesh is generated from the EBSD information, to get an optimal reconstruction of the data. This is accomplished in the mesh block using the EBSDMesh type. The same data file used with the EBSD reader is used in the EBSDReader UserObject. The mesh is created with one node per data point in the EBSD data file. If you wish to use mesh adaptivity and allow the mesh to get coarser during the simulation, the uniform_refine parameter is used to set how many times the mesh can be coarsened. The block takes the form:

[Mesh]
type = EBSDMesh
filename = IN100_128x128.txt
uniform_refine = 4
[]


## EBSDReader UserObject

Doxygen

The user object reads in the data file, using the name supplied in the mesh block, and stores a data object with the local data at each material point as well as the average data about each grain. The block syntax is very simple:

  [./ebsd]
[../]


## Setting Variable ICs

The initial condition for the variables is set from the EBSD data. There are three possible use cases summarized below:

### Case 1: Create grain structure from the grain numbers in the EBSD data, ignoring the phase number

A grain structure is created from the EBSD data by assigning initial condition values for order parameters. Many more grains can be represented than the number of order parameters. The required blocks are

[Mesh] #Creates a mesh representing the EBSD data
type = EBSDMesh
filename = IN100_001_28x28_Marmot.txt
[]

[GlobalParams]
op_num = 9 #Defines the number of order parameters used to represent the grains
var_name_base = gr
[]

[UserObjects]
[./ebsd] #Reads in the EBSD data. Uses the filename given in the mesh block
[../]
[]

[Variables]
[./PolycrystalVariables] #Creates all the order parameters
[../]
[]

[ICs]
[./PolycrystalICs]
[./ReconVarIC] #Uses the data from the user object to initialize the variables for all the order parameters.
[../]
[../]
[]


This example was taken from tests/reconstruction/1phase_reconstruction.i

### Case 2: Initialize a variable from a specific phase number in the EBSD data, ignoring the grain numbers

Here, the value for a single variable is initialized from the EBSD data corresponding to a single phase number. The required blocks are

[Mesh] #Creates a mesh representing the EBSD data
type = EBSDMesh
filename = 'Ti_2Phase_28x28_Sqr_Marmot.txt'
[]

[UserObjects]
[./ebsd] #Reads in the EBSD data. Uses the filename given in the mesh block
[../]
[]

[Variables] #Creates the two variables being initialized
[./c1]
[../]
[./c2]
[../]
[]

[ICs]
[./phase1_recon] #Initializes the variable info from the ebsd data
type = ReconPhaseVarIC
phase = 1 #Phase number being used to initialize the variable
variable = c1 #Name of the variable being initialized
[../]
[./phase2_recon]
type = ReconPhaseVarIC
phase = 2 #Phase number being used to initialize the variable
variable = c2 #Name of the variable being initialized
[../]
[]


Example taken from tests/reconstruction/2phase_reconstruction1.i

### Case 3: Create an initial grain structure from the EBSD data only corresponding to one phase number

Here, the grain and phase numbers are used. The order parameters are initialized from the EBSD data, but only using those grains with a given phase number.

[Mesh] #Creates a mesh representing the EBSD data
type = EBSDMesh
filename = 'Ti_2Phase_28x28_Sqr_Marmot.txt'
[]

[GlobalParams]
op_num = 3 #Number of order parameters being used for this phase
var_name_base = gr
[]

[UserObjects]
[./ebsd]
[../]
[]

[Variables]
[./PolycrystalVariables]
[../]
[]

[ICs]
[./PolycrystalICs]
[./ReconVarIC]
phase = 1 #Phase number being used to assign the grain values
[../]
[../]
[]


This example was taken from tests/reconstruction/2phase_reconstruction2.i

# Using EBSD Crystal Info

The EBSDReader local grid data is extracted using the getData(Point) function call, where you pass in location of the point where you want the data. The available data that can be extracted for a given point is

• phi1 - The first Euler angle $$\phi_1$$$• phi - The second Euler angle $$\Phi$$$
• phi2 - The third Euler angle $$\phi_2$$$• grain - The index of the grain • phase - The index of the phase • symmetry - The symmetry class (from TSL) An example of using this function is shown here const EBSDReader::EBSDData & d = _ebsd_reader.getData(p); _euler_angles(0) = d.phi1; _euler_angles(1) = d.phi; _euler_angles(2) = d.phi2;  The EBSDReader average grain data is extracted using the getAvgData(unsigned int) function call, where you pass in the grain number for which you want the data. The available data that can be extracted • phi1 - The average first Euler angle $$\phi_1$$$
• phi - The average second Euler angle $$\Phi$$$• phi2 - The average third Euler angle $$\phi_2$$$
• phase - The index of the phase of the grain
• symmetry - The symmetry class (from TSL)
• p - Point with centroid location

An example of using this function is show here, taken from ReconVarIC

const EBSDReader::EBSDAvgData & d = _ebsd_reader.getAvgData(grn_index);
_centerpoints[gr] = d.p;


# Plotting Color Representation of Crystal Orientations

It is common to use an inverse pole figure representation of the crystal orientations to color the grains to represent EBSD data. To simplify the comparison with experiments, MOOSE has a tool for outputting color values for the inverse pole figure representation that can then be visualized using Paraview. The spatially varying red, green, and blue (RGB) values are outputted as auxvariables that are automatically read by Paraview as a vector.

Two Auxkernels can be used to output the RGB values. The first, EulerAngleProvider2RGBAux is the simplest but requires the entire domain to have the same crystal structure. The second, EulerAngleVariables2RGBAux requires various other auxvariables that contain the Euler angles, the crystal structure, and the phase number.

The easiest way of outputting the values is to use a custom action block in the input file that is available. The syntax is

[Modules]
[./PhaseField]
[./EulerAngles2RGB]
crystal_structure = cubic
euler_angle_provider = ebsd
grain_tracker = grain_tracker
[../]
[../]
[]


Reconstructed microstructure with the color representation of the inverse polefigure description of the crystyal orientations. Image created using the phase_field module example file IN100-111grn.i.

We recommend you plot the colors using Paraview. The EulerAngle2RGB action will create three auxvariables with default names RGB_x, RGB_y, and RGB_z. Paraview will automatically create a vector variable of name RGB_. To correctly represent the colors,
1. Select RGB_ as the visualization variable.
2. In the properties section with the advanced properties toggled on, uncheck Map Scalars under Scalar Coloring.

# Testing and Examples

The EBSDReader code is tested in phase_field/tests/reconstruction_test

It is demonstrated using the example phase_field/examples/ebsd_reconstruction/IN100-111grn.i