.. index:: single: -S .. _neper_s: Simulation Module (-S) ====================== Module -S is the module for post-processing simulation results. It generates and works on a simply-structured and human-friendly :ref:`simulation_directory`. The :ref:`simulation_directory` is particularly well suited for result management and allows for the computation of new results. A :ref:`simulation_directory` is typically generated by FEPX. It can also be generated by the :ref:`neper_t` or the :ref:`neper_m` (option :data:`-format sim`), in which case it contains the (raster) tessellation or mesh file but no simulation results --- the various post-processing capabilities of :ref:`neper_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 (:data:`elset`, :data:`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 :data:`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: .. code-block:: console $ 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 : Info : Copyright (C) 2003-2022, 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 ~~~~~~~~~~ .. option:: Specify the name of the input directory, which can be: - a :ref:`simulation_directory`; - a series of simulation directories combined with :data:`,` (to merge). **Default value**: -. .. option:: -orispace Specify the mesh of orientation space used for ODF computation. **Default value**: -. Step Options ~~~~~~~~~~~~ .. option:: -step 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 :option:`-format` :data:`sim` in the :ref:`neper_t` or :ref:`neper_m`). **Default value**: -. Entity Options ~~~~~~~~~~~~~~ .. option:: -entity : Define a new entity (based on elements) from one or several logical expressions based on the variables described in :ref:`mesh_keys`. The expression argument can be: - a single logical expression; - :data:`file()`: logical expressions to load from a file. An entity corresponds to one or several sets of elements (just as :data:`mesh` represents the set of all elements and :data:`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. [#f2]_ Results of element-based entities (including :data:`elset` and :data:`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. .. option:: -res{cell,tess,node,elt,elset,mesh,} ,,... Specify the results to add, remove or update, using :data:``, :data:`'!'` [#quotes]_ or :data:`\\\`, 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 :data:`:\`, where :data:`` is the name and :data:`` is its expression. A result expression can be: - any expression based on the tessellation results (see :ref:`tessellation_keys` or :ref:`raster_tessellation_keys`), mesh results (see :ref:`mesh_keys`) or simulation results (see :ref:`simulation_results`); - :data:``: for element-based entities (including :data:`elset` and :data:`mesh`), the value of a result computed from the element results, by weighted-averaging (considering the element volumes); - :data:`_\`: for element-based entities (including :data:`elset` and :data:`mesh`), the value of a result computed from the element results, by a given statistical :data:`operation` (always considering the element volumes), which can be: - :data:`mean`: mean; - :data:`stddev`: standard deviation; - :data:`var`: variance; - :data:`prval`: principal values [#principal]_; - :data:`prvect`: principal vectors [#principal]_. - :data:`\` or :data:`\\`: a specific component of an existing result (:data:`` or :data:`\`, vectorial or tensorial, respectively, 1-indexed) [#f3]_; - :data:`file()` (in which case a name *must* be assigned, as in :data:`:file()`): a custom result to be loaded from files of basename :data:`` (files :data:`.step*` if they exist, and :data:`` otherwise). .. note:: To use a simulation result at a specific step, use :data:`(step=)`, where :data:`` is the result and :data:`` is the step number. **Default value**: -. Output Options ~~~~~~~~~~~~~~ .. option:: -o Specify the name of the output simulation directory (the default :data:`.sim` extension is not added to the argument). **Default value**: :data:`.sim` Output Directory ---------------- - :data:`.sim`: simulation directory (see :ref:`simulation_directory`). Examples -------- Below are some examples of use of neper -S. - Convert an FEPX raw result directory into a simulation directory: .. code-block:: console $ neper -S fepx-simulation - Convert an FEPX raw result directory into a simulation directory of specified name: .. code-block:: console $ neper -S fepx-simulation -o foo - Add the nodal :data:`x` and the elemental :data:`vol` and :data:`stress33` results to a simulation directory: .. code-block:: console $ neper -S simulation -resnode x -reselt vol,rr - Add the elemental :data:`energy` result, defined as :data:`0.12*(crss-crss(step=0))^2`, to a simulation directory: .. code-block:: console $ neper -S simulation -reselt "energy:0.12*(crss-crss(step=0))^2" - Override the elemental :data:`energy` result, newly defined as :data:`0.34*(crss-crss(step=0))^2`, in a simulation directory: .. code-block:: console $ neper -S simulation -reselt '!energy,energy:0.34*(crss-crss(step=0))^2' - Add the elset and mesh :data:`stress` results to a simulation directory (the :data:`stress` result must exist for elements): .. code-block:: console $ neper -S simulation -reselset stress -resmesh stress - Define a new entity named :data:`tophalf`, corresponding to the top half of the sample along :data:`z`, and compute its stress: .. code-block:: console $ neper -S simulation -entity "tophalf:z>0.5" -restophalf stress - Define a new entity named :data:`halves`, corresponding to the bottom and top halves of the sample along :data:`z`, and compute its stresses: .. code-block:: console $ neper -S simulation -entity "halves:file(foo)" -reshalves stress where :file:`foo` contains: .. code-block:: console z<=0.5 z>0.5 - Merge two simulation directories into a single simulation directory: .. code-block:: console $ neper -S cycle1.sim,cycle2.sim -o cycle1-2 .. [#f1] For a restarted FEPX simulation, append :data:`:\` to the directory name to specify the restart number; otherwise, Neper attempts to find the simulation restart files with the highest index. .. [#f2] Defining a name is mandatory for expressions containing divisions, as the :data:`/` character cannot be used in file names. The name cannot be a known variable. .. [#f3] The original result, :data:``, must already be available in the simulation directory. .. [#quotes] Note the single quotes. .. [#principal] For vectors of length 6 (:data:`stress`, etc.), the 3 last components are multiplied by :math:`\sqrt{2}`.