Simulation Input

By default, a minimum of two files is necessary to completely define a simulation. These files are the configuration file, simulation.config, and the mesh file, simulation.msh. The configuration file defines the material parameters, control of the simulation (i.e., boundary conditions and loading history), printing of output files, and various optional input. The mesh file contains the polycrystal finite element mesh information (grain morphologies, phases and crystal orientations) as well as simulation-related information on the domain faces and the mesh partitions used for parallel simulations.

The Configuration File (simulation.config)

This file contains the necessary definitions to run a simulation. It is structured in several, successive blocks that define different aspects of the simulation. Each of these blocks is headed by a line starting by #, which provides a short description of the block. The structure for the simulation.config file is as follows:

# Optional Input
    <key_phrase> <value>
    ...

# Material Parameters
    <key_phrase> <value>
    ...

# Deformation History
    <key_phrase> <value>
    ...

# Boundary Conditions
    <key_phrase> <value>
    ...

# Printing Results
    <key_phrase> <value>
    ...

Configuration options within a block may generally be provided in any order; however, the material parameters and deformation history must follow specific orders. It is recommended that the overall structure of the simulation.config file follow the example structure above. The Optional Input block should always precede any others.

Any piece of text that is preceded by a # is assumed to be a comment and is ignored (which also makes block headers optional), while <key_phrase> is the input structure of the file, where <key_phrase> is the input command and <value> are the associated parameters for the input command (as will be defined in the following sections). A single line in the file should only ever pertain to a single <key_phrase>/<value> pairing. All strings are interpreted literally and should be lowercase except where otherwise stated.

Material Description

The model is described in Model Description, and the corresponding input parameters are made clear and written in fixed font, most often as in: \(\gamma\) (gamma). The specification of the input parameters in the simulation.config file is detailed in Input Parameters.

Model Description

The material is described via an elastic response (Hooke’s law) and a plastic response (rate dependent plastic flow and hardening).

The stress, \(\sigma\), is related to the elastic strain, \(\epsilon\), via Hooke’s law:

\[\sigma = \cal C \epsilon,\]

where \(\cal C\) is the stiffness tensor. Written in Voigt notation, the above equation is expanded for cubic materials:

\[\begin{split}\begin{Bmatrix} \sigma_{11} \\ \sigma_{22} \\ \sigma_{33} \\ \sigma_{23} \\ \sigma_{13} \\ \sigma_{12} \end{Bmatrix} = \begin{bmatrix} C_{11} & C_{12} & C_{12} & & & \\ C_{12} & C_{11} & C_{12} & & & \\ C_{12} & C_{12} & C_{11} & & & \\ & & & C_{44} & & \\ & & & & C_{44} & \\ & & & & & C_{44} \end{bmatrix} \begin{Bmatrix} \epsilon_{11} \\ \epsilon_{22} \\ \epsilon_{33} \\ 2\epsilon_{23} \\ 2\epsilon_{13} \\ 2\epsilon_{12} \end{Bmatrix}.\end{split}\]

Here, the strength of materials convention is utilized, where the shear factors of 2 are written in the strain vector. Special attention must be paid to ensure that the correct stiffness values are chosen, to align with the input convention used here.

For this convention, the Zener anisotropy ratio for cubic materials (which quantifies the level of elastic anisotropy, with 1 being perfectly isotropic) would be written as:

\[A = {2 C_{44} \over C_{11} - C_{12}}.\]

For example, Tungsten (W) is a nearly perfectly elastically isotropic cubic (BCC) material, with \(C_{11} = 522.4\) GPa, \(C_{12} = 204.4\) GPa, and \(C_{44} = 160.8\) GPa. This would yield a Zener ratio of 1.01.

The elastic constitutive relation may also be expanded for hexagonal materials:

\[\begin{split}\begin{Bmatrix} \sigma_{11} \\ \sigma_{22} \\ \sigma_{33} \\ \sigma_{23} \\ \sigma_{13} \\ \sigma_{12} \end{Bmatrix} = \begin{bmatrix} C_{11} & C_{12} & C_{13} & & & \\ C_{12} & C_{11} & C_{13} & & & \\ C_{13} & C_{13} & C_{33} & & & \\ & & & C_{44} & & \\ & & & & C_{44} & \\ & & & & & \left( C_{11}-C_{12}\right)/2 \end{bmatrix} \begin{Bmatrix} \epsilon_{11} \\ \epsilon_{22} \\ \epsilon_{33} \\ 2\epsilon_{23} \\ 2\epsilon_{13} \\ 2\epsilon_{12} \end{Bmatrix}.\end{split}\]

Note that to allow for the decoupling of the hydrostatic and deviatoric portions of the elastic deformation, the following must be satisfied: \(C_{33} = C_{11} + C_{12} - C_{13}\) (FEPX, thus, expects no input for \(C_{33}\)).

For tetragonal materials, the elastic constitutive relation is expanded to:

\[\begin{split}\begin{Bmatrix} \sigma_{11} \\ \sigma_{22} \\ \sigma_{33} \\ \sigma_{23} \\ \sigma_{13} \\ \sigma_{12} \end{Bmatrix} = \begin{bmatrix} C_{11} & C_{12} & C_{13} & & & \\ C_{12} & C_{11} & C_{13} & & & \\ C_{13} & C_{13} & C_{33} & & & \\ & & & C_{44} & & \\ & & & & C_{44} & \\ & & & & & C_{66} \end{bmatrix} \begin{Bmatrix} \epsilon_{11} \\ \epsilon_{22} \\ \epsilon_{33} \\ 2\epsilon_{23} \\ 2\epsilon_{13} \\ 2\epsilon_{12} \end{Bmatrix}.\end{split}\]

Again, to allow for the decoupling of the hydrostatic and deviatoric portions of the elastic deformation, \(C_{33} = C_{11} + C_{12} - C_{13}\).

Overall, the stiffness tensor is thus defined by the input parameters c11, c12, and c44 for cubic materials, c11, c12, c13, and c44 for hexagonal materials, and c11, c12, c13, c44, and c66 for tetragonal materials.

The kinematics of slip are described by a power law:

\[\dot{\gamma}^{\alpha} = \dot{\gamma}_{0} \left( \left| {\tau}^{\alpha} \right| \over g^{\alpha} \right)^{1/m} \rm sgn({\tau}^{\alpha}),\]

where \(\dot{\gamma}_0\) (gammadot_0) is the fixed-rate strain rate scaling coefficient (expressed in [1/s]), and \(m\) (m) is the rate sensitivity exponent.

Note

All variables presented are detailed by their dimensions (if applicable) instead of any specific unit. No unit system is inherently assumed by FEPX and the chosen unit system and value magnitudes should be consistent with the chosen length scale for the domain. For example, if it is assumed that the length scale is mm and SI units are to be used, then [force/area] will be understood to be MPa. The unit for time, however, is always assumed to be seconds (s).

For an isotropic hardening assumption, slip system strength evolution (hardening) is modeled by (note that for HCP and BCT materials, the implementation of an isotropic hardening assumption is such that the shape of the single crystal yield surface is maintained. That is, the slip rates on the basal, prismatic, and pyramidal slip systems will harden such that the ratios of slip strengths remains constant. The consequence of this is that for HCP and BCT materials, this is not a “true” isotropic assumption, as the different slip families may harden at different rates, depending on the ratios of slip system strengths):

\[\dot{g^{\alpha}} = h_{0} \left (g_{s0} - g^{\alpha} \over g_{s0} - g_{0} \right)^{n} \dot{\gamma},\]

where \(h_0\) (h_0) is the fixed-state hardening rate scaling coefficient, \(g_{s0}\) (g_s0) is the initial slip system saturation strength (expressed in [force/area]), \(g_0\) (g_0) is the initial slip system strength (expressed in [force/area]), and \(n\) (n) is the non-linear Voce hardening exponent. In the above equation, \(\dot{\gamma}\) is calculated as:

\[\dot{\gamma} = \sum_{\alpha} \left|\dot{\gamma}^{\alpha}\right|.\]

The slip system saturation strength may be evolved as a function of the slip activity. In this case, the hardening expression takes the form:

\[\dot{g^{\alpha}} = h_{0} \left (g_{s}(\dot{\gamma}) - g^{\alpha} \over g_{s}(\dot{\gamma}) - g_{0} \right)^{n} \dot{\gamma},\]

where \(g_{s}(\dot{\gamma})\) is the function for the saturation strength, which evolves via:

\[g_{s}(\dot{\gamma}) = g_{s0} \left (\dot{\gamma} \over \dot{\gamma}_{s0} \right)^{m'},\]

where \(g_{s0}\) (g_s0) is the initial slip system saturation strength (expressed in [force/area]), \(m'\) (m_prime) is the saturation strength rate scaling exponent, and \(\dot{\gamma}_{s0}\) (gammadot_s0) is the initial saturation slip system shear rate. Again, in the above two equations, \(\dot{\gamma}\) is calculated as the sum of the absolute value of the individual slip system shear rates, as defined above.

For a cyclic hardening assumption, the slip system strength evolution (hardening) is modeled by:

\[\dot{g^{\alpha}} = h_{0} \left (g_{s}(\dot{\gamma}) - g^{\alpha} \over g_{s}(\dot{\gamma}) - g_{0} \right)^{n} f,\]

where \(f\) is calculated as:

\[f = \sum_{\beta = 0}^{n_{a}} \left|\dot{\gamma}^{\beta}\right| .\]

A slip system that contributes to hardening (\(n_{a}\) total systems contributing to hardening) is that which has a change in shear greater than a critical value:

\[\Delta\gamma_{crit} = a \left[\, g / g_{s}(\dot{\gamma}) \right]^{c},\]

where the material parameters here are \(a\) (cyclic_a) and \(c\) (cyclic_c). A more complete description can be found in Turkmen et al. [TURKMEN04]. Note that minor differences exist between the implemented model described above and the formulation described in the paper.

For an anisotropic hardening assumption, slip system strength evolution (hardening) is modeled by:

\[\dot{g^{\alpha}} = h_{0} \left (g_{s}(\dot{\gamma}) - g^{\alpha} \over g_{s}(\dot{\gamma}) - g_{0} \right)^{n} \dot{\gamma} h_{\alpha \beta},\]

where the model parameters are the same as the isotropic case described above, with the addition of \(h_{\alpha \beta}\), the slip interaction matrix. The slip interaction matrix only allows for interactions from direct and coplanar slip families. The slip interaction matrix is defined by the diagonal entry, \(d\), and the off-diagonal entries, \(h_{1},\dots, h_{n}\). These input parameters are defined by diag, h1, h2, h3, and h4 for FCC materials, diag, h1, h2, h3, h4, h5, and h6 for BCC materials, diag, h1, h2, h3, h4, h5, h6, and h7 for HCP materials, and diag, h1, h2, h3, h4, h5, h6, h7, h8, h9, and h10 for BCT materials. A more complete description can be found in Carson et al. [CARSON17].

In any of the above hardening models, the base slip system strength may be modified to consider the effects of the presence of precipitates. This is performed via:

\[g_{0} = g_{0} + a_{p} \left( f_{p} r_{p} \over b_{p} \right)^{1 \over 2},\]

where \(a_{p}\) (a_p) is the precipitate hardening scaling coefficient, \(f_{p}\) (f_p) is the precipitate volume fraction, \(r_{p}\) (r_p) is the average precipitate diameter, and \(b_{p}\) (b_p) is the average Burgers’ vector for the precipitate phase. Currently, the increase in strength due to the presence of precipitates is applied globally to all elements.

For a hexagonal material, the crystal c/a ratio (c_over_a) must be defined. The initial slip strengths (g_0) must be provided as a set of three values. The order of the values for g_0 correspond to the basal slip family strength, prismatic slip family strength, and pyramidal slip family strength.

For a tetragonal material, the crystal c/a ratio (c_over_a) must be defined. The initial slip system strengths (g_0) must be provided as a set of ten values. The order of the values for g_0 correspond to the slip families \(\left\{100\right)\left<001\right]\), \(\left\{110\right)\left<001\right]\), \(\left\{100\right)\left<010\right]\), \(\left\{110\right)\left<1 \bar 11\right]\), \(\left\{110\right)\left<1 \bar10\right]\), \(\left\{100\right)\left<011\right]\), \(\left\{001\right)\left<010\right]\), \(\left\{001\right)\left<110\right]\), \(\left\{011\right)\left<01 \bar 1\right]\) and \(\left\{211\right)\left<01 \bar 1\right]\).

Input Parameters

The material (as defined in the mesh file) can include one or several phases (to which grains are assigned), and the mechanical behavior of these phases must be defined accordingly. The number of phases must first be provided:

number_of_phases <nphases>

The material parameters for a particular phase should be defined entirely for said phase before parameters for any subsequent phases are defined.

Each phase requires the specification of a consistent set of single-crystal material parameters, prefaced by

phase <phase_id>

where <phase_id>, the phase identification number, ranges from 1 to <nphases>.

First, the crystal symmetry is defined by:

crystal_type <ctype>

where the <ctype> can be fcc, bcc, hcp, and bct for face-centered cubic, body-centered cubic, hexagonal close-packed, and body-centered tetragonal respectively.

The single-crystal elastic and plastic material parameters of the phase must be defined. Depending on the crystal symmetry, the total number of required parameters varies.

Anisotropic elastic constants are defined using the strength of materials convention, as described previously in Model Description. The input is, for fcc and bcc crystal symmetry:

c11 <modulus>
c12 <modulus>
c44 <modulus>

for hcp crystal symmetry:

c11 <modulus>
c12 <modulus>
c13 <modulus>
c44 <modulus>

and for bct crystal symmetry:

c11 <modulus>
c12 <modulus>
c13 <modulus>
c44 <modulus>
c66 <modulus>

where <modulus> are expressed in [force/area]. For hcp and bct materials, the \(C_{33}\) (c33) elastic constant is constrained by the other moduli and is not required as direct input.

For hcp and bct materials, an additional crystal parameter needs to be provided:

c_over_a <ratio>

Crystallographic slip (plasticity) parameters are defined as:

m <value(s)>
gammadot_0 <value>
h_0 <strength>
g_0 <strength(s)>
g_s0 <strength>
n <value>

For hexagonal and tetragonal materials, multiple values may be provided for the rate sensitivity exponent, m, and the initial slip system strengths, g_0. If a single value is provided for m, a constant rate sensitivity exponent is assumed across all slip families. Otherwise, three or ten values (for hexagonal or tetragonal, respectively) may be provided for m, and the rate sensitivity exponents are applied on a per-family basis. Additionally, g_0 must be defined by three unique values for hexagonal materials and ten unique values for tetragonal materials. The order of the values for m and g_0 for hexagonal materials correspond to the: basal slip family, prismatic slip family, and pyramidal slip family. For tetragonal materials, the ten values correspond to the slip families \(\left\{100\right)\left<001\right]\), \(\left\{110\right)\left<001\right]\), \(\left\{100\right)\left<010\right]\), \(\left\{110\right)\left<1 \bar 11\right]\), \(\left\{110\right)\left<1 \bar10\right]\), \(\left\{100\right)\left<011\right]\), \(\left\{001\right)\left<010\right]\), \(\left\{001\right)\left<110\right]\), \(\left\{011\right)\left<01 \bar 1\right]\) and \(\left\{211\right)\left<01 \bar 1\right]\).

Saturation strength evolution (optional) is by default disabled, and may be enabled by defining both of the necessary parameters for saturation strength evolution. These parameters do not need to be defined if the saturation strength is not intended to evolve. To enable saturation strength evolution, define:

m_prime <value>
gammadot_s0 <value>

Cyclic hardening (optional) is by default disabled. It may be enabled via:

hard_type cyclic_isotropic

If cyclic hardening is enabled, each phase requires the definition of two additional parameters by:

cyclic_a <cyc_a>
cyclic_c <cyc_c>

where both cyclic_a and cyclic_c values are model parameters for a critical value of accumulated shear strain used to modify the form of the Voce hardening law [TURKMEN04].

Anisotropic hardening (optional) is by default disabled. It may be enabled via:

hard_type anisotropic

If anisotropic hardening is enabled, each phase requires the definition of slip interaction matrix values which vary based on crystal symmetry.

For fcc crystal symmetry:

latent_parameters <diag> <h1> <h2> <h3> <h4>

For bcc crystal symmetry:

latent_parameters <diag> <h1> <h2> <h3> <h4> <h5> <h6>

For hcp crystal symmetry:

latent_parameters <diag> <h1> <h2> <h3> <h4> <h5> <h6> <h7>

For bct crystal symmetry:

latent_parameters <diag> <h1> <h2> <h3> <h4> <h5> <h6> <h7> <h8> <h9> <h10>

where <diag> is the diagonal coefficient and h{1-10} are the in-plane interaction coefficients [CARSON17].

Strengthening due to the presence of precipitates is by default disabled, and may be enabled by defining the necessary parameters. These parameters do not need to be defined if precipitate strengthening is not intended to be considered. To enable precipitate strengthening, define:

a_p <strength>
f_p <volume_fraction>
r_p <length>
b_p <length>

Deformation History

A variety of deformation modes are available that are capable of reproducing various mechanical loading configurations. A deformation history is defined by both steps and increments, where steps are made of one or several increments. Steps define the strain or load targets that are to be reached during the simulation, and results can only be printed at the end of steps. One or several increments occur within each step to reach the prescribed step target while ensuring numerical stability. A step target can be expressed in terms of strain or load. The strain refers to the engineering strain as computed from the displacement of the loading surface and the initial sample length along the loading direction, and the load refers to the total force on the loading surface. Of course, the relative order of the steps defined for the deformation history matters and should be written in an ascending manner.

Deformation histories are divided into uniaxial loading and multiaxial loading. In general, the multiaxial loading definition is technically triaxial in nature; however, biaxial loading may be performed by zeroing one of the load columns accordingly. The available deformation history configuration options follow.

Uniaxial

Uniaxial loading is always strain controlled (i.e., constant strain rate); however, either specific strain targets or specific load targets may be prescribed. For strain targeting, the number of increments for a given step must be provided as opposed to a time-step value. For load targeting, the bounds on the time-step value are provided in order to control both the accuracy and, indirectly, the number of increments taken per step. These time-step values should be defined relative to the strain_rate value (Boundary Conditions).

Strain targeting allows the definition of loading to specific uniaxial strain states. This deformation history is defined as follows:

def_control_by uniaxial_strain_target
number_of_strain_steps <nsteps>
target_strain <target_val> <n_incr> <print_flag>
...

where <nsteps> is the number of strain steps that are defined in the file after this line, <target_val> is the desired strain value to be reached, <n_incr> is the number of increments to be performed in order to complete the step, and <print_flag> allows for the printing (or not) of specific steps. The options available for <print_flag> are: print_data or suppress_data.

Load targeting allows the definition of loading to specific uniaxial load states. This deformation history is defined as follows:

def_control_by uniaxial_load_target
number_of_load_steps <nsteps>
target_load <target_val> <dt_max> <dt_min> <print_flag>
...

where <nsteps> is the number of load steps that are defined in the file after this line, <target_val> is the desired load value to be reached, <dt_max> is the maximum time-step value to be used for a given increment, <dt_min> is the minimum time-step value to be used for a given increment, and <print_flag> allows for the printing (or not) of specific steps. The options available for <print_flag> are: print_data or suppress_data.

Strain rate jumps are also available for both uniaxial deformation modes and are defined by adding the following input to the block:

number_of_strain_rate_jumps <njumps>
strain_rate_jump <target_step> <new_strain_rate>
...

where <njumps> is the number of strain rate jumps defined in the file after this line, <target_step> defines which target_strain step is assigned a new strain rate, and <new_strain_rate> is the new strain rate to be assigned and has units of [1/s]. In general, and for numerical stability, the strain rate jumps should be of a similar magnitude to the strain_rate defined previously.

Multiaxial

Multiaxial loading is always strain controlled (internally) and operates at either a constant engineering strain rate or constant load rate; however, only specific load targets may be prescribed. The principal loading directions must be aligned with the coordinate axes of the mesh and the surface face normals should likewise be coincident with the coordinate axis of the mesh. Symmetry boundary conditions (zero normal velocities) are enforced on the three faces of minimal coordinates (<*0>), and, in the general case, non-zero normal velocities are applied to the faces of maximal coordinates (<*1>). The velocity on the primary control surface is held constant through the simulation (except during a strain rate jump).

Multiaxial loading with a constant strain rate (CSR) is defined as follows:

def_control_by triaxial_constant_strain_rate
number_of_csr_load_steps <nsteps>
target_csr_load <load_x> <load_y> <load_z> <dt_max> <dt_min> <print_flag>
...

where <nsteps> is the number of CSR load steps that are defined in the file after this line, <load_x> is the desired load value to be reached in the x direction, <load_y> is the desired load value to be reached in the y direction, <load_z> is the desired load value to be reached in the z direction, <dt_max> is the maximum time-step value to be used for a given increment, <dt_min> is the minimum time-step value to be used for a given increment, and <print_flag> allows for the printing (or not) of specific steps. The options available for <print_flag> are: print_data or suppress_data.

Strain rate jumps are available for this deformation mode and are defined by adding the following input to the block:

number_of_strain_rate_jumps <njumps>
strain_rate_jump <target_step> <new_strain_rate>
...

where <njumps> is the number of strain rate jumps defined in the file after this line, <target_step> defines which target_csr_load step is assigned a new strain rate, and <new_strain_rate> is the new strain rate to be assigned and has units of [1/s].

Multiaxial loading with a constant load rate (CLR) is defined as follows:

def_control_by triaxial_constant_load_rate
number_of_clr_load_steps <nsteps>
target_clr_load <load_x> <load_y> <load_z> <target_time_incr> <print_flag>
...

where <nsteps> is the number of CLR load steps that are defined in the file after this line, <load_x> is the desired load value to be reached in the x direction, <load_y> is the desired load value to be reached in the y direction, <load_z> is the desired load value to be reached in the z direction, <target_time_incr> is the physical time increment to be reached for the given target_clr_load steps for a given load rate, and <print_flag> allows for the printing (or not) of specific steps. The options available for <print_flag> are: print_data or suppress_data.

Load rate jumps and dwell episodes are available for this deformation mode. A dwell episode maintains the macroscopic loads of the step in which it is defined, but holds the ramp rate at zero for the amount of time defined by <dwell_time>. These options are defined as follows:

• For load rate jumps:

  number_of_load_rate_jumps <njumps>
  load_rate_jump <target_step> <new_ramp_rate>
  ...
  

  where <njumps> is the number of load rate jumps defined in the file after this line, <target_step> defines which target_clr_load step is assigned a new load rate, and <new_load_rate> is the new load rate to be assigned and has units of [force/s].

• For dwell episodes:

  number_of_dwell_episodes <nepisodes>
  dwell_episode <target_step> <dwell_time> <target_time_incr> <print_flag>
  ...
  

  where <nepisodes> is the number of dwell episodes defined in the file after this line, <target_step> defines which target_clr_load step is assigned to dwell, <dwell_time> is the physical amount of time in [s] for a given dwell episode, <target_time_incr> is the physical time increment to be reached for the given dwell episode, and <print_flag> allows for the printing (or not) of specific steps. The options available for <print_flag> are: print_data or suppress_data.

Boundary Conditions

Standard, simple boundary conditions are available for automatic definition with minimal input and are computed internally for each simulation based on the definitions in the simulation.config file. This ensures that standard boundary conditions are consistently defined for all simulations and increases the portability of the simulation.config file. Alternatively, custom boundary conditions can be defined, as described separately, in Externally Defined Boundary Conditions (Optional).

Uniaxial

Uniaxial definitions are available for three different constraint configurations. The available uniaxial constraint configuration options follow.

• Grip boundary conditions fully constrain two opposite faces in the spatial domain. The first face is fully fixed in all sample directions while the second face has a strain rate applied in the face normal direction while the other two sample directions are fully fixed. All other faces are unconstrained.

  

  Simplified schematic of the applied velocities for grip boundary conditions. The loading face is z1 and the sample is being loading in the +Z direction.

  Grip boundary conditions are defined as follows:

  boundary_conditions uniaxial_grip
  loading_direction <sample_dir>
  loading_face <face_label>
  strain_rate <strain_rate>
  

  where <sample_dir> is the direction along the a positive sample axis in which the sample is loaded, <face_label> is the face on which the loading is applied (the opposing face is fully fixed), and <strain_rate> is the strain rate value in units of [1/s].

• Symmetry boundary conditions constrain four faces in the spatial domain. The three <*0> faces are fixed in the face normal directions and unconstrained in the other two sample directions. The fourth <*1> face has a strain rate applied in the face normal direction while the other two sample directions are fully fixed. The selection of the <*1> face is based on the defined loading_direction.

  

  Simplified schematic of the applied velocities for symmetry boundary conditions. The sample is being loaded in the +Z direction.

  Symmetry boundary conditions are defined as follows:

  boundary_conditions uniaxial_symmetry
  loading_direction <sample_dir>
  strain_rate <strain_rate>
  

  where <sample_dir> is the direction along the a positive sample axis in which the sample is loaded, and <strain_rate> is the strain rate value in units of [1/s].

• Minimal boundary conditions are a modification of grip boundary conditions that only constrain two opposite faces in the face normal directions and two corner nodes in the spatial domain. The selection of the constrained faces is based on the defined loading_direction. The first node is always fully fixed where the <*0> faces converge. The second node is defined relative to the defined loading_direction and is constrained to prevent rigid body rotation about the loading_direction axis.

  

  Simplified schematic of the applied velocities for minimal boundary conditions. The sample is being loaded in the +Z direction. The two blue corner nodes are constrained to prevent rigid body translation and motion.

  Minimal boundary conditions are defined as follows:

  boundary_conditions uniaxial_minimal
  loading_direction <sample_dir>
  strain_rate <strain_rate>
  

  where <sample_dir> is the direction along the a positive sample axis in which the sample is loaded, and <strain_rate> is the strain rate value in units of [1/s].

Multiaxial

Multiaxial boundary conditions are generally consistent across modes, however, the input rate type varies depending on the mode. For both modes, the loading_direction defines the primary control direction in which the normal velocities are held constant throughout the simulation.

Multiaxial loading with a constant strain rate (CSR) is defined as follows:

boundary_conditions triaxial
loading_direction <sample_dir>
strain_rate <strain_rate>

where <sample_dir> is the direction along the a positive sample axis in which the sample is loaded, and <strain_rate> is the strain rate value in units of [1/s].

Multiaxial loading with a constant load rate (CLR) is defined as follows:

boundary_conditions triaxial
loading_direction <sample_dir>
load_rate <load_rate>

where <sample_dir> is the direction along the a positive sample axis in which the sample is loaded, and <load_rate> is the loading rate value in units of [force/s].

Externally Defined Boundary Conditions (Optional)

Boundary conditions different from the ones defined in Boundary Conditions can be applied using an external simulation.bcs containing per-node constraints. Of course, this file should be generated for a singular simulation.msh file (if the finite element mesh in the simulation.msh file changes, then the associated simulation.bcs file will need to be generated anew).

To read in external boundary conditions, the following line must be added to the simulation.config file:

read_bcs_from_file

The per-node constraints are defined as follows, in the simulation.bcs file:

<node_id> <coord_index> <vel>
...

where <node_id> is a unique 1-indexed identification number, <coord_index> defines the sample axis the constraint is applied to, and <vel> is the velocity being applied to the node in the constraint direction. The options for <coord_index> are: x, y, or z. A singular <coord_index>/<vel> pair should be defined per-line for a given <node_id>. The velocities should be prescribed relative to the mesh dimensions and time-step size in order to produce expected strain rates.

Externally Defined Orientations and Phases (Optional)

Crystallographic phase and orientations different from the ones defined in the simulation.msh file can be defined in external files by adding appropriate commands to the configuration file.

To read in external orientations, the following line must be added to the simulation.config file:

read_ori_from_file

More detailed information on the structure of this external file can be found in External Orientation Assignment (Optional).

To read in external grain/phase assignments, the following line must be added to the simulation.config file:

read_phase_from_file

More detailed information on the structure of this external file can be found in External Crystallographic Phase Assignment (Optional).

Printing Results

Each field variable file to be output from a simulation must be individually defined. This includes nodal output, elemental output, simulation restart information, and other miscellaneous output (see Simulation Output for a complete description of all output). The printing of a given field variable file is defined as follows:

print <output_file_name>
...

where <output_file_name> is the particular field variable file to be output. The available options for <output_file_name> are:

• coo: Nodal coordinates

• crss: Critical resolved shear stress

• defrate: Deformation rate tensor

• defrate-eq: Equivalent deformation rate

• defrate-pl: Plastic deformation rate tensor

• defrate-pl-eq: Equivalent plastic deformation rate

• disp: Nodal displacements

• elt-vol: Elemental volume

• ori: Crystallographic orientations

• slip: Slip system shear

• sliprate: Slip system shear rate

• spinrate: Plastic spin rate tensor

• strain: Total strain tensor

• strain-eq: Equivalent total strain

• strain-el: Elastic strain tensor

• strain-el-eq: Equivalent elastic strain

• strain-pl: Plastic strain tensor

• strain-pl-eq: Equivalent plastic strain

• stress: Stress tensor

• stress-eq: Equivalent stress

• vel: Nodal velocity

• velgrad: Velocity gradient tensor

• work: Work

• work-pl: Plastic work

• workrate: Work Rate

• workrate-pl: Plastic work rate

• forces: Surface forces

• convergence: Simulation convergence statistics

• restart: Simulation restart data

A full description of each output variable can be found in Simulation Output.

Optional Input Parameters

These options may pertain to specific deformation modes or control standard simulation behavior. All possible inputs presented in this section have default values already defined.

• max_incr <increments> specifies the maximum number of increments (default: 50000).

• max_total_time <time> specifies the maximum deformation time (default: 12000.0).

• check_necking {on,off} specifies whether or not to terminate simulation when specimen begins to neck (default: off).

• load_tol <tolerance> is the the target load tolerance. A small positive load tolerance (e.g. 0.1 \(\times\) control surface area) improves load control while reducing the number of small steps near target loads (default: 0.0).

• dtime_factor <time> is a number greater than or equal to 1 which is used when calculating time increments near target loads (default: 1.001).

• hard_type {isotropic,anisotropic,cyclic_isotropic} specifies the hardening model to use (default: isotropic).

• max_bc_iter <iterations> specifies the maximum number of boundary condition iterations (default: 10).

• min_pert_frac <fraction> is the minimum fraction of the control velocity by which the secondary and tertiary surface velocities are perturbed during boundary condition iterations (default: 0.001).

• load_tol_abs <tolerance> is the absolute tolerance on the secondary and tertiary loads. The absolute load criterion is that both loads are within the absolute load tolerance of the ideal load. Loads are considered to be within tolerance if either the absolute or relative criterion is satisfied (default: 0.1).

• load_tol_rel <tolerance> is the relative load tolerance on the secondary and tertiary loads. It represents a fraction of the load in the control direction. The relative load criterion is that the difference between the load and ideal load, normalized by the load in the control direction, is less than the relative load tolerance. Loads are considered to be within tolerance if either the absolute or relative criterion is satisfied (default: 0.001).

• max_strain_incr <increments> specifies the maximum strain increment for dwell episodes (default: 0.001).

• max_strain <strain> specifies the maximum allowable macroscopic strain (default: 0.2).

• max_eqstrain <strain> specifies the maximum allowable macroscopic equivalent strain (default: 0.2).

• max_iter_hard_limit <iterations> specifies the maximum allowable iterations on the Backward Euler approximation used to update hardnesses (default: 10).

Additional input commands related to restart capabilities and external file read-in are presented separately in Restarting a Simulation, External Orientation Assignment (Optional), and External Crystallographic Phase Assignment (Optional), respectively.

Optional Convergence Parameters

These options modify the tolerances and general behavior of the solution algorithms and should only be modified by those who know what they are doing. All possible inputs presented in this section have default values already defined.

Velocity Convergence

The velocity solver employs a hybrid successive-approximation/Newton-Raphson algorithm. Convergence of the velocity solution is based on a convergence parameter, which unless otherwise noted, is defined as the norm of the change in the velocity field, divided by the norm of the velocity field, \(||\Delta u||/||u||\). Other parameters are also used to assess the convergence of the velocity solution. The following parameters pertain to the convergence of the velocity solver:

• nl_max_iters <iterations>: maximum allowable number of iterations of the nonlinear velocity solver (default: 50).

• nl_tol_strict <tolerance>: desired tolerance on the elasto-viscoplastic velocity solution (default: 5e-4).

• nl_tol_loose <tolerance>: acceptable level of convergence if the desired level of convergence cannot be reached via nl_tol_strict (default: 5e-4).

• nl_tol_min <tolerance>: tolerance on the norm of the change in velocity, divided by the number of degrees of freedom, \((||u||/ \rm max(ndof))\). This parameter is useful for assessing convergence when the macroscopic velocity is near zero (default: 1e-10).

• nl_tol_switch_ref <tolerance>: value of the convergence parameter at which the solution algorithm switches from successive-approximation to Newton-Raphson. To only use successive-approximations, set the value of nr_tol_switch_ref equal to the value of nl_tol_strict (default: 1e-2).

• nl_tol_conv <tolerance>: parameter between 0 and 1 that is used to assess whether the Newton-Raphson algorithm is converging slowly (default: 0.2).

Conjugate Gradient Convergence

The solution of the linear system of equations \([K]\{\Delta u\} = -\{R\}\) is performed using a conjugate gradient solver. The following parameters pertain to the convergence of the conjugate gradient solver:

• cg_max_iters <iterations>: maximum allowable number of iterations of the conjugate gradient solver (default: 16000).

• cg_tol <tolerance>: desired tolerance on the conjugate gradient solver (default: 1e-8).

Material State Convergence

The convergence of the material stress state for both the viscoplastic and elasto-viscoplastic solutions is assessed by the following parameters:

• sx_max_iters_state <iterations>: maximum number of iterations on material state (default: 100).

• sx_max_iters_newton <iterations>: maximum number of iterations of the Newton algorithm used to solve for crystal stress (default: 100).

• sx_tol <tolerance>: tolerance on the stress solution (default: 1e-4).

The Mesh File (simulation.msh)

This file contains the finite element mesh information along with phase assignments and crystal orientations. The mesh file is generally generated by Neper and not directly modified. A brief description is provided below, which a more complete description can be found in the Neper reference manual. The file can be opened by Gmsh for interactive visualization.

The file is structured in several, successive fields that define different aspects of the mesh. Each of these fields is wrapped by $ lines, where <Field> is a short description of the information stored within the block. A typical simulation.msh file will contain the following information:

• Mesh Format ($MeshFormat),

• Mesh Version ($MeshVersion),

• Nodes ($Nodes),

• Elements ($Elements),

• Surface Element Sets ($Fasets),

• Crystal Orientations ($ElsetOrientations or $ElementOrientations),

• Grain/Phase Assignments ($Groups).

Additionally, the simulation.msh file may also include fields with partition information for both the nodes and elements if the domain is decomposed for parallel execution and surface node sets ($NSets).

Embedded microstructural information (phases and orientations) with the simulation.msh may be overridden by external files, simulation.ori and simulation.phase, if the appropriate commands are added to the simulation.config file (Externally Defined Orientations or Phase Assignments (Optional)).

External Orientation Assignment (Optional, simulation.ori)

The embedded orientation assignments within the simulation.msh may be overridden via an external simulation.ori file. This file contains formatting identical to the associated fields in the mesh file and is defined as:

For per-grain (or Elset) orientations:

$ElsetOrientations
<number_of_ori_entities> <orientation_descriptor>:<orientation_convention>
<entity_id> <ori_des1> ...
...
$EndElsetOrientations

For per-element orientations:

$ElementOrientations
<number_of_ori_entities> <orientation_descriptor>:<orientation_convention>
<entity_id> <ori_des1> ...
...
$EndElementOrientations

where <number_of_ori_entities> is the number of unique orientations defined in the section, <orientation_descriptor> is the parameterization for the orientations (see options below), <orientation_convention> describes the basis transformation route for the orientations provided, <entity_id> is a unique 1-indexed identification number, and <ori_des*> are the components of the unique orientation. Available options for <orientation_convention> are: active or passive. Following the usual terminology, an active orientation assumes that which describes a basis transformation from the sample basis to the crystal basis (sample-to-crystal), while a passive orientation convention assumes that which describes a basis transformation from the crystal basis to the sample basis (“crystal-to-sample”).

The following <orientation_descriptor> types are available (associated per-line formats are also described):

• For rodrigues, each orientation is described by \(r_1, r_2, r_3\), where \({\bf r} = {\bf t} \tan{ (\omega / 2)}\) (see: axis-angle for definitions of \({\bf t}\) and \(\omega\)). The per-line format is:

<entity_id> <r_1> <r_2> <r_3>

• For euler-bunge, each orientation is described by \(\phi_1, \theta, \phi_2\), where \(\phi_1\) is the rotation about the \(z\) axis, \(\theta\) is the rotation about the \(z^{\prime}\) axis, and \(\phi_2\) is the rotation about the \(z^{\prime \prime}\) axis, all in degrees). The per-line format is:

<entity_id> <phi_1> <Phi> <phi_2>

• For euler-kocks, each orientation is described by \(\Psi, \Theta, \phi\), where \(\Psi\) is the rotation about the \(z\) axis, \(\Theta\) is the rotation about the \(y^{\prime}\) axis, and \(\phi\) is the rotation about the \(z^{\prime \prime}\) axis, all in degrees). The per-line format is:

<entity_id> <Psi> <Theta> <phi>

• For axis-angle, each orientation is described by \(t_1, t_2, t_3, \omega\), where \(\bf{t}\) is the normalized axis of rotation and \(\omega\) is the angle of rotation about said axis, in degrees. The per-line format is:

<entity_id> <t_1> <t_2> <t_3> <omega>

• For quaternion, each orientation is described by \(q_0, q_1, q_2, q_3\), where \(q_0 = \cos{(\omega / 2)}\) and \(q_i = t_i \sin{(\omega / 2)}\) for \(i = 1, 2, 3\) (see: axis-angle for definitions of \({\bf t}\) and \(\omega\)). The per-line format is:

<entity_id> <q_0> <q_1> <q_2> <q_3>

External Crystallographic Phase Assignment (Optional, simulation.phase)

The embedded grain/phase assignments within the simulation.msh may be overridden via an external simulation.phase file. This file contains formatting identical to the associated fields in the mesh file and is defined as:

$Groups
<group_entity>
<number_of_group_entities>
<entity_id> <group>
...
$EndGroups

where <group_entity> defines the phase assignment method and must always be defined as elset, <number_of_group_entities> is the number of grain/phase pairs defined in the field, <entity_id> is a unique 1-indexed identification number, and <group> is an 1-indexed value that defines the phase for a given grain.

References

CARSON17(1,2)

18. Carson, M. Obstalecki, M. Miller, and P. R. Dawson. Characterizing heterogeneous intragranular deformations in polycrystalline solids using diffraction-based and mechanics-based metrics. Modelling and Simulation in Materials Science and Engineering, 25:055008, 2017.

TURKMEN04(1,2)

8. 19. Turkmen, M. P. Miller, P. R. Dawson, and J. C. Moosbrugger. A slip-based model for strength evolution during cyclic loading. Journal of Engineering Materials and Technology, 126(4):329-338, 2004.