Configuration File (`simulation.cfg`)

A simulation input typically consists of two files with pre-defined names: the mesh file, simulation.msh, and the configuration file, simulation.cfg, which are read by the program at run time. The mesh file describes the polycrystal as a finite element mesh, where the grains are defined by element sets, with additional fields to record polycrystal-related information, such as (optionally) phases, crystal orientations, or simulation-related information, such as node sets and mesh partitions. The configuration file completes the definition of the polycrystal by the specification of the material model and the corresponding parameters, and defines the details of the simulation (boundary conditions, loading history, output, etc). The mesh file is typically provided by Neper and does not need to be edited, and information on its format can be found in Mesh File (simulation.msh). Conversely, the configuration file is specific to the program and is to be written by the user. Of course, the mesh file and the and configuration file are closely related and should be consistent with each other.

General Structure

The configuration file (simulation.cfg) 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.cfg file is as follows:

# Material Description

    { parameter definition }

# Boundary Conditions / Deformation History

    { parameter definition }

# Output

    { parameter definition }

# Special commands

   { commands }

{ parameter definition } represents a general block of text that follows the following syntax:

<key_phrase1> <value1>
<key_phrase2> <value2>
...

<key_phrase> <value> is the input structure of the file, where <key_phrase> is either a simulation parameter or a command and <value> are one or several numerical or literal values. A parameter takes only one value, while a command can require one or several values. The possible inputs will be defined in the following sections.

{ commands } represents special commands that go beyond the definition of a standard simulation, by allowing to override mesh attributes (see Polycrystal Overwriting) or restarting a simulation (see Simulation Restart).

In the following, brackets ([ / ]) will be used to denote optional inputs (they are not expected in the simulation.cfg file and will generate parsing errors):

 <required_key_phrase> <value1>
 [ <optional_key_phrase> <value> ]
...

Any piece of text that is preceded by a # is considered as a comment and is ignored (which also makes block headers optional). 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. Parameters within a block may generally be specified in any order; however, the material parameters and deformation history must follow specific orders, and it is recommended that the overall structure of the Configuration File (simulation.cfg) follows the example structure above. Spaces and indentations may be freely used for file formatting and do not affect parsing.

Note

The following points are important to ensure the consistency between the Mesh File (simulation.msh), the Configuration File (simulation.cfg) and the running conditions (MPI):

The physical dimension of the mesh: the loading definition may be sensitive to this dimension

The number of phases: a material behavior must be defined for each phase

The definition of the node sets: the boundary conditions must be applied to existing node sets
The number of partitions of the mesh: it must match the number of computation units. A mesh can be “re-partitionned” by Neper at any time using:
neper -M -loadmesh simulation.msh -part <num_partitions>

Special Commands

Polycrystal Overwriting

Optionally, crystallographic phase and orientations different from the ones defined in the Mesh File (simulation.msh) can be defined in external files by adding appropriate commands to the configuration file.

To read in orientations from an Orientation File (simulation.ori), the following command may be used:

read_ori_from_file

To read in grain/phase assignments from a Phase File (simulation.phase), the following command may be used:

read_phase_from_file

Config Overwriting

To read in hardening parameters from an Optional Inputs File (simulation.opt), the following command may be used:

read_from_opt_file

Simulation Restart

A simulation may be restarted only if the restart files were printed as simulation output on the previous run (see Advanced Results). Upon restart, the restart files must be included in the simulation directory along with all simulation inputs (the Mesh File (simulation.msh), the Configuration File (simulation.cfg), and any other files, such as an Orientation File (simulation.ori) or Phase File (simulation.phase)).

A simulation may be restarted by adding the following line to the simulation.cfg file:

restart on

When restarting a simulation, the prescribed Deformation History (Steps) should include only additional steps, as the restarted simulation will not consider steps that were completed in the previous simulation. Consequently, step and increment indices, as well as the simulation time, are all reset to 0.

A simulation restart must be performed with the same number of cores that were used to run the original simulation. When a simulation restarts, it will attempt to find the simulation restart files with the highest step index, <N>. It will write output variable data to a new set of files, post.<var>.rst<N+1>.core*, where <var> is the requested output variable name and rst is the restart label applied to all new output variable files. Likewise, if restart files are again printed, their index will increase to <N+2> (the previous restart’s files will not be overwritten).

Configuration File (simulation.cfg)