File and Directory Formats

Simulation Directory (`.sim`)

Here are details on the .sim simulation directory (the .sim extension is entirely optional). The directory contains inputs and results on the mesh nodes and elements, over a certain number of simulation steps. It is structured as follows:

simulation.sim
|-- inputs
|   |-- job.sh
|   |-- simulation.cfg
|   |-- simulation.msh
|   `-- simulation.tess
|-- results
|   |-- elts
|   |   |-- ori
|   |   |   |-- ori.step0
|   |   |   |-- ori.step1
|   |   |   `-- ...
|   |   `-- ...
|   `-- nodes
|       |-- coo
|       |   |-- coo.step0
|       |   |-- coo.step1
|       |   `-- ...
|       `-- ...
`-- [restart]

where

inputs is an input file directory containing the Neper tessellation file (simulation.tess, if found in the input directory), the mesh file (simulation.msh), the FEPX configuration file (simulation.cfg), and all script files (*.sh, likely including a job submission file).
results is the result directory.
results/nodes is the node result directory.
results/elts is the element result directory.
results/*/<res> is a directory for result <res> of an entity (nodes or elements). The directory contains one file per simulation step, named <res>.step<nb>, where nb is the step number, ranging from 0 (for the initial state) to the total number of steps.
restart is the restart directory. It is present only if restart on was used.

Results can have integer values, real values, vectorial values or tensorial values. In the result files, values for the different entities (nodes or elements) are written on successive lines, with components written on successive columns (space delimited). The components are written as follows:

vector, $v$: $v_1$, $v_2$, $v_3$;

symmetrical tensor, $t$: $t_{11}$, $t_{22}$, $t_{33}$, $t_{23}$, $t_{31}$, $t_{12}$ (Voigt notation);

skew-symmetrical tensor, $t$: $t_{12}$, $t_{13}$, $t_{23}$;

non-symmetrical tensor, $t$: $t_{11}$, $t_{12}$, $t_{13}$, $t_{21}$, $t_{22}$, $t_{23}$, $t_{31}$, $t_{32}$, $t_{33}$.

The directory also contains a hidden file, .sim, containing information on the simulation and the content of the simulation directory. This file is only for internal use and is formatted as follows:

***sim
 **format
   <format>
 **input
  *tess
   <tess_file>
  *tesr
   <tesr_file>
  *msh
   <msh_file>
  *ori
   <ori_file>
  *bcs
   <bcs_file>
  *phase
   <phase_file>
  *config
   <config_file>
 **general
   <cell_nb> <node_nb> <elt_nb> <elset_nb> <part_nb>
  *orides
   <orientation_descriptor>
 **entity <entity>                                     \
  *member                                              |
   <member_nb>                                         |
   <member1> <member2> ...                             | section repeated for each entity
  *result                                              |
   <result_nb>                                         |
   <result1> <result2> ...                             /
 **orispace
  *rodrigues <space_file>
 **step
   <step_nb>
***end

Mesh File (`simulation.msh`)

Here are details on the native .msh (adapted from Gmsh’s msh format version 2.2). Developers should note that read and write functions are available as neut_msh_fscanf and neut_msh_fprintf, defined in directories neut/neut_msh/neut_msh_fscanf and neut/neut_msh/neut_msh_fprintf.

$MeshFormat
2.2 <file_type> <data_size>
$EndMeshFormat
$MeshVersion
<mesh_version>
$EndMeshVersion
$Domain
<domain>
$EndDomain
$Topology
<reconstruct_topology>
$EndTopology
$Nodes
<number_of_nodes>
<node_id> <node_x> <node_y> <node_z>
...
$EndNodes
$Elements
<number_of_elements>
<elt_id> <elt_type> <number_of_tags> <tag1> ... <elt_id_node1> ...
...
$EndElements
$Periodicity
<number_of_periodicities>
<secondary_node_id> <primary_node_id> <per_vect_x> <per_vect_y> <per_vect_z>
...
$EndPeriodicity
$NSets
<number_of_nsets>
<nset1_label>
<nset_node_nb>
<nset_node1>
<nset_node2>
...
<nset2_label>
...
$EndNSets
$Fasets
<number_of_fasets>
<faset1_label>
<faset_elt_nb>
<faset_elt_id> <faset_elt_id_node1> ...
...
<faset2_label>
...
$EndFasets
$NodePartitions
<number_of_nodes>
<node_id> <node_partition>
...
$EndNodePartitions
$PhysicalNames
<number_of_physical_names>
<physical_dimension> <physical_id> <physical_name>
...
$EndPhysicalNames
$ElsetOrientations
<number_of_elsets> <orientation_descriptor>
<elset_id> <ori_des1> ...
...
$EndOrientations
$ElsetCrySym
<crysym>
$EndElsetCrySym
$ElementOrientations
<number_of_elements> <orientation_descriptor>
<element_id> ori_des1> ...
...
$EndElementOrientations
$Groups
<group_entity>
<number_of_group_entities>
<entity_id group>
...
$EndGroups

where

$MeshFormat denotes the beginning of a mesh format field.
<file_type> is equal to 0 for an ASCII file and 1 for a binary file.
<data_size> is an integer equal to the size of the floating point numbers used in the file (= sizeof (double)).
$EndMeshFormat denotes the end of a mesh format field.
$MeshVersion denotes the beginning of a mesh version field.
<mesh_version> is the mesh file version (currently 2.2.3).
$EndMeshVersion denotes the end of a mesh version field.
$Domain denotes the beginning of an optional domain field.
<domain> is the domain.
$EndDomain denotes the end of an optional domain field.
$Topology denotes the beginning of an optional topology field.
<reconstruct_topology> is a boolean indicating whether the topology is to be reconstructed upon parsing or not (use 0 to solve parsing issues).
$EndTopology denotes the end of an optional topology field.
$Nodes denotes the beginning of a node field.
<number_of_nodes> is the number of nodes.
<node_id> is the identifier of a node and ranges from 1 to <number_of_nodes>.
<node_x>, <node_y> and <node_z> are the three coordinates of a node (real numbers).
$EndNodes denotes the end of a node field.
$Elements denotes the beginning of an element field.
<number_of_elements> is the number of elements.
<elt_type> is an integer specifying the type of elements: 15 for a 0D element, 1 for a 1st-order 1D element (2 nodes), 8 for a 2nd-order 1D element (3 nodes), 2 for a 1st-order triangular element (3 nodes), 3 for a 1st-order quadrangular element (4 nodes), 9 for a 2nd-order triangular element (6 nodes), 16 for a 2nd-order quadrangular element (8 nodes), 10 for a 2nd-order quadrangular element (9 nodes), 4 for a 1st-order tetrahedral element (4 nodes), 5 for a 1st-order hexahedral element (8 nodes), 11 for a 2nd-order tetrahedral element (10 nodes), 17 for a 2nd-order hexahedral element (20 nodes), 6 for a 1st-order prismatic element (6 nodes), 18 for a 2nd-order prismatic element (15 nodes).
<number_of_tags> is the number of tags, and <tag#> are the tags. In the general case, the number of tags is equal to 3, the first and second tags are the elset and the third tag is the element partition. The mesh partition is non-zero only for the higher-dimension elements of a mesh which was previously partitioned.
<elt_id_node#> are the nodes associated to an element. The number of nodes depends on the element type (<elt_type>).
$EndElements denotes the end of an element field.
$Periodicity denotes the beginning of a periodicity field.
<number_of_periodicities> is the number of periodicities.
<primary_node_id> is the identifier of the primary node.
<secondary_node_id> is the identifier of the secondary node.
<per_vect_x> <per_vect_y> <per_vect_z> are the scaled components of the vector going from the primary node to the secondary node (-1, 0 or 1).
$EndPeriodicity denotes the end of a periodicity field.
$NSets denotes the beginning of an nset field.
<number_of_nsets> is the number of nsets.
<nset#_label> are the labels of the nsets.
<nset_node_nb> is the number of nodes of an nset.
<nset_node_id#> are the identifiers of the nodes of an nset.
$EndNSets denotes the end of an nset field.
$Fasets denotes the beginning of a faset field.
<number_of_fasets> is the number of fasets.
<faset#_label> are the labels of the fasets.
<faset_elt_nb> is the number of elements of a faset.
<faset_elt_id> are the identifiers of the elements of a faset (3D elements adjacent to the boundary).
<faset_elt_id_node#> are the nodes of an element of a faset.
$EndFasets denotes the end of a faset field.
$NodePartitions denotes the beginning of a node partition field.
<nodeid_partition> is the partition of node <id> (ranging from 1 to the total number of partitions).
$EndNodePartitions denotes the end of a node partition field.
$PhysicalNames denotes the beginning of a physical name field.
<number_of_physical_names> is the number of physical names. There are as many names as physical entities, and the physical entities correspond to all tessellation vertices, edges, faces and polyhedra (i.e., mesh 0D, 1D, 2D and 3D elsets).
<physical_dimension> is the dimension of a physical entity and can be equal to 0, 1, 2 or 3.
<physical_id> is the id of a physical entity. It ranges from 1 to the number of 0D elsets (tessellation vertices) for the 0D entities, 1 to the number of 1D elsets (tessellation edges) for the 1D entities, 1 to the number of 2D elsets (tessellation faces) for the 2D entities and 1 to the number of 3D elsets (tessellation polyhedra) for the 3D entities.
<physical_name> is the name of a physical entity, under the form <verid> for 0D elsets (tessellation vertices), <edgeid> for 1D elsets (tessellation edges), <faceid> for 2D elsets (tessellation faces) and <polyid> for 3D elsets (tessellation polyhedra), where <id> ranges from 1 to the number of elsets.
$EndPhysicalNames denotes the end of a physical name field.
$ElsetOrientations denotes the beginning of an elset orientation field.
$EndElsetOrientations denotes the end of an elset orientation field.
<number_of_elsets> is the number of elsets.
<orientation_descriptor> is the orientation descriptor.
<elset_id> is the elset id.
<ori_des1>, … is the orientation, following <orientation_descriptor>.
$EndElsetOrientations denotes the end of an elset orientation field.
$ElsetCrySym denotes the beginning of an elset crystal symmetry field.
<crysym> is the crystal symmetry (triclinic, cubic or hexagonal).
$EndElsetCrySym denotes the end of an elset crystal symmetry field.
$ElementOrientations denotes the beginning of an element orientation field.
<number_of_elements> is the number of elements.
<element_id> is the element id.
$EndElementOrientations denotes the end of an element orientation field.
$Groups denotes the beginning of a group field.
<group_entity> is the entity for which groups are defined, which must be elset.
<number_of_group_entities> is the number of group entities (number of elsets).
<entity_id> is the id of an entity.
<group> is the group of the entity.
$EndGroups denotes the end of a group field.

Orientation File (`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>
```

Phase File (`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.

Restart Files (`rst<N>.*`)

If the print restart command is present in the simulation.cfg file, a set of additional restart files will be generated from the simulation. These files are written at the end of each prescribed step and contain necessary information to restart a given simulation ([LEGACY] Restarting a Simulation with Appended Load Steps for information on how to restart a simulation). Two types of restart files are generated, a control file, rst<N>.control, and per-core field files, rst<N>.field.core* (where <N> indicates which simulation the files describe, 0 indexing). Both file types are unformatted (or binary) files and are generally unmodifiable. The structures of the data stored within both files for the various deformation modes follow.

Uniaxial Restart Control

The rst<N>.control file for uniaxial loading modes contains the following data in the given order:

current_step <step>
previous_load_array <load_x> <load_y> <load_z>
step_complete_flag <logical>
previous_timestep_value <time>
current_incr <increment>
current_time <time>
surface_1_loads <load_x> <load_y> <load_z>
...
surface_6_loads <load_x> <load_y> <load_z>
previous_prescribed_load <load>
current_surface_areas <area_surf_1> ... <area_surf_6>
initial_surface_areas <area_surf_1> ... <area_surf_6>

Multiaxial CSR Restart Control

The rst<N>.control file for multiaxial constant strain rate loading modes contains the following data in the given order:

current_step <step>
current_load_array <load_x> <load_y> <load_z>
previous_load_array <load_x> <load_y> <load_z>
step_complete_flag <logical>
previous_timestep_value <time>
current_incr <increment>
current_time <time>
surface_1_loads <load_x> <load_y> <load_z>
...
surface_6_loads <load_x> <load_y> <load_z>
current_surface_areas <area_surf_1> ... <area_surf_6>
initial_surface_areas <area_surf_1> ... <area_surf_6>
current_mesh_lengths <length_x> <length_y> <length_z>
initial_mesh_lengths <length_x> <length_y> <length_z>
current_control_velocity <vel_x> <vel_y> <vel_z>
s_pert_mag <vel>
t_pert_mag <vel>

Multiaxial CLR Restart Control

The rst<N>.control file for multiaxial constant load rate loading modes contains the following data in the given order:

current_step <step>
current_load_array <load_x> <load_y> <load_z>
previous_load_array <load_x> <load_y> <load_z>
first_incr_in_step <logical>
current_incr <increment>
current_time <time>
surface_1_loads <load_x> <load_y> <load_z>
...
surface_6_loads <load_x> <load_y> <load_z>
current_surface_areas <area_surf_1> ... <area_surf_6>
initial_surface_areas <area_surf_1> ... <area_surf_6>
current_mesh_lengths <length_x> <length_y> <length_z>
initial_mesh_lengths <length_x> <length_y> <length_z>
current_control_velocity <vel_x> <vel_y> <vel_z>
previous_control_action <integer>
current_control_action <integer>
initial_load_dwell_velocity <vel_x> <vel_y> <vel_z>
initial_unload_dwell_velocity <vel_x> <vel_y> <vel_z>

Restart Field Data

All loading modes also write field data on a per-core basis to rst<N>.field.core* files. These files contain the necessary field variable information in order to spatially define the total state of the virtual sample at the time of printing. The following field data arrays are written to the files in the given order:

coords <coords>
velocity <velocity>

c0_angs <orientation>
c_angs <orientation>
rstar <rotation>
rstar_n <rotation>
wts <weight>
crss <crss>
crss_n <crss>

gela_kk_bar <strain>
gsig_vec_n <stress>
pela_kk_bar <strain>
psig_vec_n <stress>
e_elas_kk_bar <strain>
sig_vec_n <stress>

eqstrain <strain>
eqplstrain <strain>
gamma <shear>

el_work_n <work>
el_workp_n <work>
el_work_rate_n <work_rate>
el_workp_rate_n <work_rate>

File and Directory Formats

Simulation Directory (.sim)

Mesh File (simulation.msh)

Orientation File (simulation.ori)

Phase File (simulation.phase)

Restart Files (rst<N>.*)