Simulation Module (-S)

Module -S is the module for post-processing simulation results. It generates and works on a simply-structured and human-friendly Simulation Directory (.sim). The Simulation Directory (.sim) is particularly well suited for result management and allows for the computation of new results.

A Simulation Directory (.sim) is typically generated by FEPX. It can also be generated by the Tessellation Module (-T) or the Meshing Module (-M) (option -format sim), in which case it contains the (raster) tessellation or mesh file but no simulation results — the various post-processing capabilities of Simulation Module (-S) can then be used on the (raster) tessellation or mesh. Finally, simulation directories that represent successive parts of a simulation (e.g. resulting from FEPX restarts) can be merged into a single one.

New results can be computed for several entities of the (raster) tessellation and mesh, including the (raster) tessellation cells and the mesh nodes, elements and elsets. The whole (raster) tessellation and mesh can also serve as entities. New entities corresponding to sets of elements can also be defined.

Results of (raster) tessellation entities are computed from the (raster) tessellation, while results of the mesh entities are computed from the mesh or the simulation results. The results of sets of elements (elset, mesh and new entities) are computed from the element results, by averaging or other statistical processing. Results can also be imported from external files. The results can be assigned names and defined from general expressions, as in energy:0.1234*(crss-crss(step=0))^2. Results can also be removed or updated.

The simulation directory can be loaded by module -V for result visualization.

Here is what a typical run of module -S looks like:

$  neper -S simulation.sim -reselset stress

========================    N   e   p   e   r    =======================
Info   : A software package for polycrystal generation and meshing.
Info   : Version 4.8.0
Info   : Built with: gsl|muparser|opengjk|openmp|nlopt|libscotch (full)
Info   : Running on 20 threads.
Info   : <https://neper.info>
Info   : Copyright (C) 2003-2024, and GNU GPL'd, by Romain Quey.
Info   : Loading initialization file `/home/rquey/.neperrc'...
Info   : ---------------------------------------------------------------
Info   : MODULE  -S loaded with arguments:
Info   : [ini file] (none)
Info   : [com line] simulation.sim -reselset stress
Info   : ---------------------------------------------------------------
Info   : Reading input data...
Info   :   - Reading arguments...
Info   :     > Input files: msh config
Info   :     > Node number      : 49
Info   :     > Element number   : 16
Info   :     > Elset number     : 2
Info   :     > Partition number : 2
Info   :     > Step number      : 2
Info   :     > Node results     : coo disp vel
Info   :     > Elt results      : ori stress
Info   : Running post-processing...
Info   :   - Loading inputs...
Info   :     > simulation.msh...
Info   :     > simulation.cfg...
Info   :   - Writing results...
Info   :     [o] Writing directory `simulation.sim/results/elsets'...
Info   :       . stress ........................................... 100%
Info   :     [o] Wrote directory `simulation.sim/results/elsets'.
Info   : Elapsed time: 0.010 secs.
========================================================================

Arguments

Input Data

<directory_name>

Specify the name of the input directory, which can be:

• a Simulation Directory (.sim);

• a series of simulation directories combined with , (to merge).

Default value: -.

-orispace <file_name>

Specify the mesh of orientation space used for ODF computation.

Default value: -.

Step Options

-step <step_nb>

Define the number of steps of a simulation.

This option is useful to import results (at simulation steps) into a simulation directory originally generated from a tessellation or a mesh (option -format sim in the Tessellation Module (-T) or Meshing Module (-M)).

Default value: -.

Entity Options

-entity <name>:<logical_expression>

Define a new entity (based on elements) from one or several logical expressions based on the variables described in Mesh Keys. The expression argument can be:

• a single logical expression;

• file(<file_name>): logical expressions to load from a file.

An entity corresponds to one or several sets of elements (just as mesh represents the set of all elements and elset represents the sets of elements of the mesh and corresponding to the tessellation cells).

Default value: -.

Results Options

Below are options to manipulate (add, remove or update) the results of a simulation directory. New results can be computed from the simulation inputs (tess, mesh, …), existing siumulation results, or be loaded from a file. Any result can also be assigned a name alongside its expression. [2] Results of element-based entities (including elset and mesh) are computed from the mesh in the case of known variables, or from the element results (when they exist), in this order of priority.

-res{cell,tess,node,elt,elset,mesh,<entity>} <res1>,<res2>,...

Specify the results to add, remove or update, using <res>, '!<res>' [4] or \<res>, respectively. A new result is typically computed from the tessellation, mesh or existing simulation results, as described in the following. To (optionally) assign a name to a result, use <name>:<expression>, where <name> is the name and <expression> is its expression. A result expression can be:

• any expression based on the tessellation results (see Tessellation Keys or Raster Tessellation Keys), mesh results (see Mesh Keys) or simulation results (see Simulation Results);

• <res>: for element-based entities (including elset and mesh), the value of a result computed from the element results, by weighted-averaging (considering the element volumes);

• <res>_<operation>: for element-based entities (including elset and mesh), the value of a result computed from the element results, by a given statistical operation (always considering the element volumes), which can be:

  • mean: mean;

  • stddev: standard deviation;

  • var: variance;

  • prval: principal values [5];

  • prvect: principal vectors [5].

• <res><X> or <res><X><Y>: a specific component of an existing result (<X> or <X><Y>, vectorial or tensorial, respectively, 1-indexed) [3];

• file(<basename>) (in which case a name must be assigned, as in <name>:file(<basename>)): a custom result to be loaded from files of basename <basename> (files <basename>.step* if they exist, and <basename> otherwise).

Note

To use a simulation result at a specific step, use <res>(step=<step_nb>), where <res> is the result and <step_nb> is the step number.

Default value: -.

Output Options

-o <directory_name>

Specify the name of the output simulation directory (the default sim extension is not added to the argument).

Default value: <fepx_result_directory>.sim

Output Directory

• sim: simulation directory (see Simulation Directory (.sim)).

Examples

Below are some examples of use of neper -S.

• Convert an FEPX raw result directory into a simulation directory:

  $ neper -S fepx-simulation
  

• Convert an FEPX raw result directory into a simulation directory of specified name:

  $ neper -S fepx-simulation -o foo
  

• Add the nodal x and the elemental vol and stress33 results to a simulation directory:

  $ neper -S simulation -resnode x -reselt vol,rr
  

• Add the elemental energy result, defined as 0.12*(crss-crss(step=0))^2, to a simulation directory:

  $ neper -S simulation -reselt "energy:0.12*(crss-crss(step=0))^2"
  

• Override the elemental energy result, newly defined as 0.34*(crss-crss(step=0))^2, in a simulation directory:

  $ neper -S simulation -reselt '!energy,energy:0.34*(crss-crss(step=0))^2'
  

• Add the elset and mesh stress results to a simulation directory (the stress result must exist for elements):

  $ neper -S simulation -reselset stress -resmesh stress
  

• Define a new entity named tophalf, corresponding to the top half of the sample along z, and compute its stress:

  $ neper -S simulation -entity "tophalf:z>0.5" -restophalf stress
  

• Define a new entity named halves, corresponding to the bottom and top halves of the sample along z, and compute its stresses:

  $ neper -S simulation -entity "halves:file(foo)" -reshalves stress
  

  where foo contains:

  z<=0.5
  z>0.5
  

• Merge two simulation directories into a single simulation directory:

  $ neper -S cycle1.sim,cycle2.sim -o cycle1-2
  

[1]

For a restarted FEPX simulation, append :<restart_number> to the directory name to specify the restart number; otherwise, Neper attempts to find the simulation restart files with the highest index.

[2]

Defining a name is mandatory for expressions containing divisions, as the / character cannot be used in file names. The name cannot be a known variable.

[3]

The original result, <res>, must already be available in the simulation directory.

[4]

Note the single quotes.

[5] (1,2)

For vectors of length 6 (stress, etc.), the 3 last components are multiplied by \(\sqrt{2}\).