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). A Simulation Directory (.sim) is typically generated from an FEPX raw result directory, which can be done as simply as follows:

$ neper -S <fepx_raw_result_directory>

A Simulation Directory (.sim) can also be generated by the Tessellation Module (-T) or the Meshing Module (-M) (option -format sim), in which case the directory contains only the tessellation, raster tessellation or mesh file but no actual simulation results. Finally, simulation directories that represent successive parts of a simulation (e.g. resulting from FEPX restarts) can be merged.

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 fepx-simulation

========================    N   e   p   e   r    =======================
Info   : A software package for polycrystal generation and meshing.
Info   : Version 4.0.0
Info   : Built with: gsl|muparser|opengjk|openmp|nlopt|libscotch (full)
Info   : Running on 8 threads.
Info   : <https://neper.info>
Info   : Copyright (C) 2003-2021, 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] fepx-simulation
Info   : ---------------------------------------------------------------
Info   : Reading input data...
Info   :   - Reading arguments...
Info   : Writing simulation directory from FEPX result directory...
Info   :     [o] Writing directory `fepx-simulation.sim'...
Info   :   - Parsing FEPX results...
Info   :     [i] Parsing file `fepx-simulation/post.report'...
Info   :     [i] Parsed file `fepx-simulation/post.report'.
Info   :     > Partition number: 8.
Info   :     > Step      number: 10.
Info   :     > Node      number: 2752.
Info   :     > Element   number: 1596.
Info   :   - Writing report file...
Info   :     [o] Writing file `fepx-simulation.sim/report'...
Info   :     [o] Wrote file `fepx-simulation.sim/report'.
Info   :   - Writing inputs...
Info   :     [o] Writing directory `fepx-simulation.sim/inputs'...
Info   :       . simulation.tess...
Info   :       . simulation.msh...
Info   :       . simulation.config...
Info   :     [o] Wrote directory `fepx-simulation.sim/inputs'.
Info   :   - Writing results...
Info   :     [o] Writing directory `fepx-simulation.sim/results'...
Info   :       . coo...       100%
Info   :       . ori...       100%
Info   :     [o] Wrote directory `fepx-simulation.sim/results'.
Info   :     [o] Wrote directory `fepx-simulation.sim'.
Info   : Elapsed time: 0.075 secs.
========================================================================

Arguments

Input Data

<directory_name>

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

an FEPX raw result directory 1 (to convert into a simulation directory);
a simulation directory;
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 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 define the results to add to a simulation directory. The results can be new results defined from the simulation inputs (tess, mesh, …) and simulation results, or subresults (such as vector or tensor components). It is also possible to import results for files. 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 by volume-weighted averaging of the element results (if 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. Provide as argument <res>, '!<res>' 4 or \<res> to add, remove or update result <res>, respectively. Provide <res> or <res><X><Y> to get a specific component of an existing result (<X> or <X><Y>, vectorial or tensorial, respectively, 1-indexed) 3 , <res>:file(<basename>) to import results from files of basename <basename> (the files of the different steps must be available as <basename>.step*; if the file does not exist, it is attempted to read from <basename>), or any expression based on the tessellation, mesh or simulation results (the mesh results can be any variables described in Tessellation Keys, Raster Tessellation Keys and Mesh Keys). For nodes, disp can be used to get the node displacements from the node coordinates. 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. To define a name corresponding to a result, use <name>:<expression>, where <name> is the name and <expression> is its expression. To provide several values, combine them with ,.

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.