Keyword Reference

Every keyword of simulation.cfg, generated from the keyword table in the source code (src/io/cfg_table_mod.f90), which the configuration reader also uses: the table below is therefore always that of the program. Each keyword links to its entry in the chapter that describes it. A default of “required” means that the keyword must be given; keywords given “in each phase block” belong in a phase block (see Crystal Behavior (simulation.cfg)). Rows of the form “a component, then …, one value per step” start with the component (e.g. 33) and give one value per step (see Loading (simulation.cfg)).

Keyword	Values	Unit	Default	Description
number_of_phases	integer >= 1		required	number of phases
phase	integer >= 1			start of the block of phase i
crystal_type	one of fcc, bcc, hcp, bct		required	crystal structure
model	one of elastic, crystal_plasticity		required	constitutive model
c11	real > 0	MPa	required	elastic constant C11 (Voigt)
c12	real > 0	MPa	required	elastic constant C12 (Voigt)
c13	real > 0	MPa	required (hcp, bct)	elastic constant C13 (Voigt)
c33	real > 0	MPa	required (hcp, bct)	elastic constant C33 (Voigt; independent)
c44	real > 0	MPa	required	elastic constant C44 (Voigt)
c66	real > 0	MPa	required (bct)	elastic constant C66 (Voigt)
c_over_a	real > 0		required (hcp, bct plasticity)	lattice ratio c/a (hcp, bct)
slip_families	all, or one or more slip families of the crystal type, each once, written exactly as listed (Slip families); their order numbers the slip systems		per crystal_type	active slip families, {plane}<direction>, or all (crystal_plasticity)
m	real > 0: one value per active slip family, in the order of slip_families (or of the default families), or one value per slip system, in the slip-system order		required (crystal_plasticity)	rate sensitivity, one per active slip family or per slip system
gammadot_0	real > 0: one value per active slip family, in the order of slip_families (or of the default families), or one value per slip system, in the slip-system order	1/s	required (crystal_plasticity)	reference slip rate, one per active slip family or per slip system
tau_0	real > 0: one value per active slip family, in the order of slip_families (or of the default families), or one value per slip system, in the slip-system order	MPa	required (crystal_plasticity)	initial slip strength, one per active slip family or per slip system
hardening	one of saturation_isotropic, saturation_anisotropic, kocks_mecking, none		saturation_isotropic	slip-system hardening law (crystal_plasticity)
h_0	real >= 0: one value; with hardening saturation_anisotropic also one value per active slip family, in the order of slip_families (or of the default families), or one value per slip system	MPa	required (saturation laws)	hardening rate coefficient: one value, or per family or system (anisotropic)
tau_s	real > 0: one value; with hardening saturation_anisotropic also one value per active slip family, in the order of slip_families (or of the default families), or one value per slip system	MPa	required (saturation laws)	saturation slip strength: one value, or per family or system (anisotropic)
n	real >= 0: one value; with hardening saturation_anisotropic also one value per active slip family, in the order of slip_families (or of the default families), or one value per slip system		required (saturation laws)	hardening exponent: one value, or per family or system (anisotropic)
interaction_matrix	N reals >= 0, one row of the matrix per line, N lines in the slip-system order (N the number of active slip systems)		1 diag., 1.4 off	one row of the interaction matrix (N lines of N values; saturation_anisotropic)
saturation_evolution	one of on, off		off	saturation strength tau_s0 (Gammadot/gammadot_s0)^m_prime (saturation laws)
gammadot_s0	real > 0	1/s	required (saturation_evolution)	reference slip rate of saturation evolution
m_prime	real > 0		required (saturation_evolution)	exponent of saturation evolution
cyclic_hardening	one of on, off		off	cyclic hardening: only slip past a critical accumulated slip hardens
cyclic_a	real > 0		required (cyclic_hardening on)	critical accumulated slip a (crss/tau_s)^c: coefficient a (0 < a < 1)
cyclic_c	real > 0		required (cyclic_hardening on)	critical accumulated slip a (crss/tau_s)^c: exponent c
precipitate_strengthening	one of on, off		off	precipitate strength tau_p added to tau_0 (cutting or bowing)
a_p	real > 0	MPa		precipitate cutting coefficient (cutting set: a_p, b_p)
b_p	real > 0	mm		Burgers vector of the precipitate (cutting set)
c_p	real > 0			precipitate bowing coefficient (bowing set: c_p, b_m)
b_m	real > 0	mm		Burgers vector of the matrix (bowing set)
f_p	real > 0 and <= 1		required (precipitate_strengthening on)	precipitate volume fraction
r_p	real > 0	mm	required (precipitate_strengthening on)	mean precipitate radius
km_b	real > 0	mm	required (kocks_mecking)	Burgers vector b (Kocks-Mecking)
km_h_n	real >= 0		required (kocks_mecking)	network hardening coefficient h_n (Kocks-Mecking)
km_rho_0	real > 0	1/mm^2	required (kocks_mecking)	initial network dislocation density rho_0 (Kocks-Mecking)
km_k1	real >= 0	1/mm	required (kocks_mecking)	dislocation storage coefficient k_1 (Kocks-Mecking)
km_k20	real >= 0		required (kocks_mecking)	dynamic recovery coefficient k_20 (Kocks-Mecking)
km_gammadot_k0	real > 0	1/s	required (kocks_mecking)	reference slip rate of k_2 = k_20 (gammadot_k0/Gammadot)^(1/km_n)
km_n	real > 0		required (kocks_mecking)	rate exponent n of k_2 = k_20 (gammadot_k0/Gammadot)^(1/km_n)
irradiation	one of on, off		off	irradiation softening: damage tensor from dislocation loops (kocks_mecking)
irr_h_d	real >= 0		required (irradiation)	defect hardening coefficient h_d (irradiation)
irr_eta	real >= 0		required (irradiation)	loop annihilation efficiency eta (irradiation)
irr_loop_density	real >= 0	1/mm^3	required (irradiation)	dislocation loop number density rho_l (irradiation)
irr_loop_diameter	real > 0	mm	required (irradiation)	dislocation loop diameter d_l (irradiation)
irr_loop_normals	one or more of <111>, <100>, <110>, each once		required (irradiation)	loop-normal families, <111> <100> <110> (irradiation; fcc, bcc)
boundary_conditions	one of uniaxial_grip, uniaxial_symmetry, uniaxial_minimal, triaxial, general, periodic		required	boundary-condition preset (constrained nodes and dofs)
set_bc	vel <nset> <d> <v> [<d> <v> [<d> <v>]]: a node set (or a node id), then one to three pairs of a direction x, y or z and a velocity; the line may be repeated	mm/s		set_bc vel <nset> <x, y or z> <v> […] (general)
set_mpc1	vel <nset> <d> [<d> [<d>]]: a node set, then one to three directions x, y or z; the line may be repeated			set_mpc1 vel <nset> <x, y or z> […]: equal velocity components on a node set
set_mpc	vel <nset> <d> <c> <o> [...]: a node set, then one to three triples of a direction x, y or z, a nonzero coefficient and an offset; the line may be repeated	mm/s		set_mpc vel <nset> <x, y or z> <c> <d> […]: v = c v(first node) + d
control_component	one of 11, 22, 33, 23, 13, 12, 32, 31, 21		required (triaxial, periodic)	component that sets the step durations (shear: periodic)
periodic_kinematics	one of small_strain, deformation_gradient_rate		small_strain	periodic: imposed rates of the symmetric or the full Fbar-dot
periodic_preconditioner	one of lumped_diagonal, exact_diagonal		lumped_diagonal	periodic: Jacobi diagonal of the reduced system
number_of_steps	integer >= 1		required	number of loading steps
strain_rate	a component, then real, one value per step (- for a step without a value)	1/s		strain rate of a component (periodic: of Fbar), per step
target_strain	a component, then real, one value per step (- for a step without a value)			strain target of a component (periodic: of Fbar - I), per step
target_load	a component, then real, one value per step (- for a step without a value)	N		load target: force on the face x1/y1/z1 of the control component, per step
target_stress	a component, then real, one value per step (- for a step without a value)	MPa		stress target: that force over the current face area, per step
target_time	real > 0, one value per step (- for a step without a value)	s		time target (cumulative), per step
load_rate	a component, then real, one value per step (- for a step without a value)	N/s		load rate of a component (force on its face x1/y1/z1), per step; 0 holds it
stress_rate	a component, then real, one value per step (- for a step without a value)	MPa/s		stress rate of a component (that force over the current face area), per step
target_duration	real > 0, one value per step (- for a step without a value)	s		length of the step from its actual start, per step (or a target)
number_of_incrs	integer >= 1, one value per step (- for a step without a value)		required (or dtime, dstrain)	increments per step (one of number_of_incrs, dtime, dstrain per step)
dtime	real > 0, one value per step (- for a step without a value)	s	required (or number_of_incrs, dstrain)	time increment per step (or number_of_incrs, dstrain)
dstrain	real > 0, one value per step (- for a step without a value)		required (or number_of_incrs, dtime)	strain increment per step, loading component (or number_of_incrs, dtime)
dtime_min	real > 0, one value per step (- for a step without a value)	s	required (unknown step duration)	smallest time increment of a load or stress target step
dtime_factor	real >= 1		1.001	factor on the increment aimed at a load or stress target
load_tol	real > 0	N	0.1	absolute tolerance of load rows: a load target is landed on within it
stress_tol	real > 0	MPa	0.1	absolute tolerance of stress rows: a stress target is landed on within it
max_bc_iter	integer >= 1		10	landing attempts of an increment; iterations of each boundary-velocity loop
min_pert_frac	real > 0		0.001	smallest velocity perturbation: a fraction of the control velocity or elastic estimate
max_strain_incr	real > 0		0.001	largest strain increment of the control component in a dwell
check_necking	one of on, off		off	stop when the control-face load falls (checked every increment)
print_results	integer from 0 to 1, one value per step		1	write the step results: 1 yes, 0 no
max_incr	integer >= 1		50000	run limit: increments
max_total_time	real > 0	s	12000	run limit: time
max_strain	real > 0			run limit: largest normal engineering strain (no limit if absent)
max_eqstrain	real > 0			run limit: equivalent engineering strain (no limit if absent)
cg_tol	real > 0 and <= 1		1e-8	CG relative tolerance
cg_max_iters	integer >= 1		16000	CG iteration limit
cg_preconditioner	one of jacobi, block_jacobi, none		block_jacobi	CG preconditioner (jacobi with MPCs or periodicity; none: for debugging only)
global_max_iters	integer >= 1		50	global iteration limit
global_tol	real > 0 and <= 1		5e-4	relative velocity-change tolerance
global_tol_abs	real > 0	mm/s	1e-10	absolute velocity-change tolerance
global_tol_slow	real > 0 and <= 1		5e-4	relative tolerance accepted after a slow NR, or in SA after NR
global_nr_switch	real >= 0		1e-2	relative velocity change below which SA switches to NR
global_nr_slow_ratio	real > 0		0.2	NR is slow below this fraction of its rate
midnode_linearization	one of on, off		off	move the mid-nodes of tet10 elements to the edge midpoints every increment
initialization	one of elastic_step, isotropic_viscoplastic		elastic_step	start of crystal-plasticity runs (velocity guess and stress start of increment 1)
point_tol	real > 0	1/s	1e-4	material point Newton tolerance (residual norm)
point_tol_state	real > 0		1e-5	material point state-loop tolerance (relative to tau_0)
point_tol_hardening	real > 0		1e-4	material point strength-update tolerance (relative to tau_0)
point_max_iters_newton	integer >= 1		100	material point Newton iteration limit
point_max_iters_hardening	integer >= 1		10	material point strength-update iteration limit
point_max_iters_state	integer >= 1		100	material point state-loop iteration limit
subincrementation	one of on, off		off	repeat a rejected increment as halves
subincrement_max_depth	integer >= 1		4	subdivisions of one increment, down to dt/2^value (subincrementation on)
subincrement_max_successive	integer >= 1		10	successive increments that may be subdivided (subincrementation on)
read_ori_from_file	none (the keyword alone)			orientations from simulation.ori
read_phase_from_file	none (the keyword alone)			phases from simulation.phase
read_from_opt_file	none (the keyword alone)			values from simulation.opt
restart	one of on, off		off	continue simulation.sim from its restart files
print	one of coo, disp, vel, stress, strain_el, ori, forces, crss, slip, sliprate, rss, strain_pl, strain_pl_eq, defrate_pl, spinrate, rotrate, work, strain, strain_eq, strain_el_eq, stress_eq, defrate, defrate_eq, defrate_pl_eq, velgrad, rotrate_spin, rotrate_slip, work_pl, workrate, workrate_pl, strain_pl_sample, strain_pl_sample_eq, convergence, km_rho, km_k2, km_rhorate, dmg, dmgrate, restart; the line may be repeated			output variable (one per line); restart: restart files at every step end
output_format	one of ascii, hdf5, one or more values		ascii	output formats: ascii (.sim text files), hdf5 (simulation.h5 and .xdmf), or both

Option Compatibility

The combinations of options that FEPX rejects (an error when the configuration file is read) or ignores (a warning), generated from the rules in the source code (src/io/cfg_rules_mod.f90), which the configuration reader also uses. Each rule is also stated at the entries of the options it concerns.

Keywords	Rule
c_over_a, crystal_type	c_over_a is used only with crystal_type hcp and bct.
slip_families, m, gammadot_0, tau_0, model	slip_families, m, gammadot_0 and tau_0 are used only with model crystal_plasticity.
hardening, h_0, tau_s, n, interaction_matrix, model	hardening, h_0, tau_s, n and interaction_matrix are used only with model crystal_plasticity.
h_0, tau_s, n, interaction_matrix, saturation_evolution, cyclic_hardening, precipitate_strengthening, hardening	h_0, tau_s, n, interaction_matrix, saturation_evolution, cyclic_hardening and precipitate_strengthening are used only with a saturation hardening law (hardening saturation_isotropic or saturation_anisotropic).
interaction_matrix, hardening	interaction_matrix is used only with hardening saturation_anisotropic.
gammadot_s0, m_prime, saturation_evolution	gammadot_s0 and m_prime are used only with saturation_evolution on.
cyclic_a, cyclic_c, cyclic_hardening	cyclic_a and cyclic_c are used only with cyclic_hardening on.
a_p, b_p, c_p, b_m, f_p, r_p, precipitate_strengthening	a_p, b_p, c_p, b_m, f_p and r_p are used only with precipitate_strengthening on.
km_b, km_h_n, km_rho_0, km_k1, km_k20, km_gammadot_k0, km_n, hardening	km_b, km_h_n, km_rho_0, km_k1, km_k20, km_gammadot_k0 and km_n are used only with hardening kocks_mecking.
irradiation, hardening	irradiation is used only with hardening kocks_mecking.
irradiation, crystal_type	irradiation on is used only with crystal_type fcc and bcc (the dislocation loop normals are defined only for fcc and bcc).
irr_h_d, irr_eta, irr_loop_density, irr_loop_diameter, irr_loop_normals, irradiation	irr_h_d, irr_eta, irr_loop_density, irr_loop_diameter and irr_loop_normals are used only with irradiation on.
periodic_kinematics, periodic_preconditioner, boundary_conditions	periodic_kinematics and periodic_preconditioner are used only with boundary_conditions periodic.
strain_rate, target_strain, target_load, target_stress, load_rate, stress_rate, control_component, boundary_conditions	The shear components (23, 13, 12, 32, 31, 21) of strain_rate, target_strain, target_load, target_stress, load_rate, stress_rate and control_component are used only with boundary_conditions periodic.
strain_rate, target_strain, control_component, periodic_kinematics	The components 32, 31 and 21 of strain_rate, target_strain and control_component cannot be used with periodic_kinematics small_strain (it takes the shear components 23, 13 and 12, one per pair; deformation_gradient_rate takes the nine components).
strain_rate, load_rate, stress_rate, boundary_conditions	strain_rate, load_rate and stress_rate cannot be used with boundary_conditions general (the velocities are given by the set_bc lines).
set_bc, boundary_conditions	set_bc cannot be used with boundary_conditions uniaxial_grip, uniaxial_symmetry, uniaxial_minimal or triaxial (the preset sets the velocities).
set_mpc, set_mpc1, boundary_conditions	Multi-point constraints (set_mpc, set_mpc1) cannot be used with boundary_conditions periodic.
set_mpc, set_mpc1, boundary_conditions	Multi-point constraints (set_mpc, set_mpc1) cannot be used with boundary_conditions triaxial.
set_mpc, set_mpc1, target_load, target_stress, load_rate, stress_rate	Multi-point constraints (set_mpc, set_mpc1) cannot be used with load or stress targets or rates (target_load, target_stress, load_rate, stress_rate: load control).
target_load, target_stress, load_rate, stress_rate, boundary_conditions	target_load, target_stress, load_rate and stress_rate cannot be used with boundary_conditions periodic (no macroscopic load or stress control).
control_component, boundary_conditions	control_component cannot be used with boundary_conditions general (the velocities are given by the set_bc lines).
load_rate, target_stress	load_rate cannot be used with a target_stress of the same component in the same step (a load_rate ends at a target_load, target_strain, target_time or target_duration).
stress_rate, target_load	stress_rate cannot be used with a target_load of the same component in the same step (a stress_rate ends at a target_stress, target_strain, target_time or target_duration).
dtime_factor, target_load, target_stress, load_rate, stress_rate	dtime_factor is used only with a target_load or target_stress (or a load_rate or stress_rate row).
load_tol, target_load, load_rate	load_tol is used only with a target_load or load_rate row.
stress_tol, target_stress, stress_rate	stress_tol is used only with a target_stress or stress_rate row.
max_bc_iter, target_load, target_stress, load_rate, stress_rate	max_bc_iter is used only with a target_load or target_stress (or a load_rate or stress_rate row).
min_pert_frac, target_load, target_stress, load_rate, stress_rate	min_pert_frac is used only with a target_load or target_stress row on a component other than the control component, or a load_rate or stress_rate row.
max_strain_incr, load_rate, stress_rate	max_strain_incr is used only with a dwell (a step with load_rate 0 or stress_rate 0 on the control component).
dtime_min, target_load, target_stress, load_rate, stress_rate	dtime_min is used only with a load or stress target at a strain rate, or a strain target at a load or stress rate (give “-” for the other steps).
number_of_incrs, target_load, target_stress, load_rate, stress_rate	number_of_incrs cannot be used with a load or stress target at a strain rate, or a strain target at a load or stress rate (the duration of the step is not known: give dtime or dstrain (the largest increment) and dtime_min).
number_of_incrs, load_rate, stress_rate	number_of_incrs cannot be used with a dwell (a step with load_rate 0 or stress_rate 0 on the control component: give dtime, its largest increment; its increments follow max_strain_incr).
dstrain, strain_rate	dstrain is used only with a strain_rate on the control component (not in a step at a load_rate or stress_rate: give number_of_incrs or dtime).
check_necking, boundary_conditions	check_necking on cannot be used with boundary_conditions periodic (no face loads).
check_necking, target_strain, target_load, target_stress	check_necking on is used only with a loaded component (a target_strain, target_load or target_stress row; the load of its face x1, y1 or z1 is checked).
subincrement_max_depth, subincrement_max_successive, subincrementation	subincrement_max_depth and subincrement_max_successive are used only with subincrementation on.
cg_preconditioner, boundary_conditions	cg_preconditioner block_jacobi and none cannot be used with boundary_conditions periodic (only jacobi).
cg_preconditioner, set_mpc, set_mpc1	cg_preconditioner block_jacobi and none cannot be used with multi-point constraints (set_mpc, set_mpc1: only jacobi).
print, hardening	print km_rho, print km_k2 and print km_rhorate are used only with a phase with hardening kocks_mecking.
print, irradiation	print dmg and print dmgrate are used only with a phase with irradiation on.
print, boundary_conditions	print forces is ignored with boundary_conditions periodic (no face forces file; the macroscopic stress is written to results/macro).