The EBSDReader user object reads in data from [electron backscatter diffraction (EBSD)](https://en.wikipedia.org/wiki/Electron_backscatter_diffraction) 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](http://www.ctcms.nist.gov/oof/).

EBSD Data File Syntax
==================

[image:245 align:right]
    Reconstructed microstructure using EBSDReader, created using the phase_field module example file ```IN100-111grn.i```


[image:247 align:right]
    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](http://dream3d.bluequartz.net/) 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](http://mooseframework.org/docs/doxygen/modules/classEBSDMesh.html)

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:
```puppet
[Mesh]
  type = EBSDMesh
  filename = IN100_128x128.txt
  uniform_refine = 4
[]
```

##```EBSDReader``` UserObject
[Doxygen](http://mooseframework.org/docs/doxygen/modules/classEBSDReader.html)

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:

```puppet
  [./ebsd]
    type = EBSDReader
  [../]
```

## 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
```puppet
[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
    type = EBSDReader
  [../]
[]

[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.
      ebsd_reader = ebsd #Name of the ebsd reader user object
    [../]
  [../]
[]
```
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

```puppet
[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
    type = EBSDReader
  [../]
[]

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

[ICs]
  [./phase1_recon] #Initializes the variable info from the ebsd data
    type = ReconPhaseVarIC
    ebsd_reader = ebsd #Name of the ebsd reader user object
    phase = 1 #Phase number being used to initialize the variable
    variable = c1 #Name of the variable being initialized
  [../]
  [./phase2_recon]
    type = ReconPhaseVarIC
    ebsd_reader = ebsd #Name of the ebsd reader user object
    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.

```puppet
[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]
    type = EBSDReader
  [../]
[]

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

[ICs]
  [./PolycrystalICs]
    [./ReconVarIC]
      ebsd_reader = ebsd #Name of the ebsd reader user object
      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
```c++
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

```c++
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](http://mooseframework.org/docs/doxygen/modules/classEulerAngleProvider2RGBAux.html) is the simplest but requires the entire domain to have the same crystal structure. The second, [EulerAngleVariables2RGBAux](http://mooseframework.org/docs/doxygen/modules/classEulerAngleVariables2RGBAux.html) 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
```puppet
[Modules]
  [./PhaseField]
    [./EulerAngles2RGB]
      crystal_structure = cubic
      euler_angle_provider = ebsd
      grain_tracker = grain_tracker
    [../]
  [../]
[]
```

[image:295 align:right]
    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```