Add new capabilities

- module -T: fixed truncated statistical distributions (from and to), improved
  -domain stdtriangle, generalized body key, added elsetbody key, removed legacy
  true key.
- module -M: added crystal symmetry to mesh file.
- module -S: added computation of standard deviation (or variance) and other
  statistical properties of the results of element-based entities (elset, mesh,
  etc.), added -restess odf,odfn and -restesr odf,odfn, made various fixes.
- module -V: fixed -data*colscheme ipf to support hexagonal crystal symmetry
  (see the "Plotting an Orientation Color Key" tutorial too), added support for
  hexagonal crystal symmetry (pole figures and inverse pole figures), added
  -dataelset, -datacellweight and -dataelsetweight, added -res{cell,elt,elset}
  odf, added -pfsym uniaxial, improved -step, enabled string completion for
  options, added -space ipf, added -ipf* options, added -[i]pfprojlabel and
  -[i]pfpolelabel options, extended -space [i]pf to mesh results, made code
  overhaul, made minor fixes.
- general: added tutorial, improved testing (including -S), added step, gos
  and scale keys, added REAL_PRINT_FORMAT configuration variables.
- documentation: made minor improvements.

Author: rquey

VERSIONS

@@ -1,6 +1,22 @@
-New in 4.5.1-4 (02 Nov 2022):
+New in 4.6.0 (06 Apr 2023):
+- module -T: fixed truncated statistical distributions (from and to), improved
+  -domain stdtriangle, generalized body key, added elsetbody key, removed legacy
+  true key.
+- module -M: added crystal symmetry to mesh file.
+- module -S: added computation of standard deviation (or variance) and other
+  statistical properties of the results of element-based entities (elset, mesh,
+  etc.), added -restess odf,odfn and -restesr odf,odfn, made various fixes.
+- module -V: fixed -data*colscheme ipf to support hexagonal crystal symmetry
+  (see the "Plotting an Orientation Color Key" tutorial too), added support for
+  hexagonal crystal symmetry (pole figures and inverse pole figures), added
+  -dataelset, -datacellweight and -dataelsetweight, added -res{cell,elt,elset}
+  odf, added -pfsym uniaxial, improved -step, enabled string completion for
+  options, added -space ipf, added -ipf* options, added -[i]pfprojlabel and
+  -[i]pfpolelabel options, extended -space [i]pf to mesh results, made code
+  overhaul, made minor fixes.
+- general: added tutorial, improved testing (including -S), added step, gos
+  and scale keys, added REAL_PRINT_FORMAT configuration variables.
 - documentation: made minor improvements.
-- fixed truncated statistical distributions (from and to).
 
 New in 4.5.0 (07 Sep 2022):
 - module -T: fixed -morpho cube, added -statcell and -statvox

doc/_static/ini

@@ -11,8 +11,8 @@
 import sphinx_rtd_theme
 
 project = u'Neper'
-version = u'4.5.1-4'
-release = u'4.5.1-4'
+version = u'4.6.0'
+release = u'4.6.0'
 author = u'Romain Quey'
 copyright = u'Romain Quey'
 language = 'en'

doc/conf.py

@@ -474,7 +474,7 @@ Here are details on the native :file:`.msh` (adapted from Gmsh's msh format vers
   2.2 <file_type> <data_size>
   $EndMeshFormat
   $MeshVersion
-  2.2 <mesh_version>
+  <mesh_version>
   $EndMeshVersion
   $Domain
   <domain>
@@ -531,6 +531,9 @@ Here are details on the native :file:`.msh` (adapted from Gmsh's msh format vers
   <elset_id> <ori_des1> ...
   ...
   $EndOrientations
+  $ElsetCrySym
+  <crysym>
+  $EndElsetCrySym
   $ElementOrientations
   <number_of_elements> <orientation_descriptor>
   <element_id> ori_des1> ...
@@ -555,7 +558,7 @@ where
 
 - :data:`$MeshVersion` denotes the beginning of a mesh version field.
 
-- :data:`<mesh_version>` is the mesh file version (currently :data:`2.2.2`).
+- :data:`<mesh_version>` is the mesh file version (currently :data:`2.2.3`).
 
 - :data:`$EndMeshVersion` denotes the end of a mesh version field.
 
@@ -651,6 +654,8 @@ where
 
 - :data:`$ElsetOrientations` denotes the beginning of an elset orientation field.
 
+- :data:`$EndElsetOrientations` denotes the end of an elset orientation field.
+
 - :data:`<number_of_elsets>` is the number of elsets.
 
 - :data:`<orientation_descriptor>` is the orientation descriptor.
@@ -661,6 +666,12 @@ where
 
 - :data:`$EndElsetOrientations` denotes the end of an elset orientation field.
 
+- :data:`$ElsetCrySym` denotes the beginning of an elset crystal symmetry field.
+
+- :data:`<crysym>` is the crystal symmetry (:data:`triclinic`, :data:`cubic` or :data:`hexagonal`).
+
+- :data:`$EndElsetCrySym` denotes the end of an elset crystal symmetry field.
+
 - :data:`$ElementOrientations` denotes the beginning of an element orientation field.
 
 - :data:`<number_of_elements>` is the number of elements.

doc/exprskeys.rst

@@ -97,19 +97,19 @@ This procedure uses the default configuration options and should work out-of-the
 Fine Configuration
 ~~~~~~~~~~~~~~~~~~
 
-The locations where files are installed, which dependencies are included and other dependency information can be specified, before installation, using CMake variables.   This can be done using
+The locations where files are installed, which dependencies are included, other dependency information and program configuration options can be specified, before installation, using CMake variables.   This can be done using a terminal tool:
 
 .. code-block:: console
 
   $ ccmake ..
 
-for an interactive command-line tool, using
+or an interactive tool:
 
 .. code-block:: console
 
   $ cmake-gui ..
 
-for an interactive graphical tool, or directly at the command line, using Cmake's :data:`-D` option:
+or directly at the command line, using Cmake's :data:`-D` option:
 
 .. code-block:: console
 
@@ -150,6 +150,12 @@ Finally, other third-party libraries are directly included in the source code (s
 
 - The `openGJK <https://github.com/MattiaMontanari/openGJK>`_ library.
 
+The program configuration variables concern the printing format of the real numbers, in the result files (:file:`.tess`, :file:`.msh`, etc.):
+
+- :code:`REAL_PRINT_FORMAT`, default :code:`"%.12f"` (12 decimal digits);
+- :code:`REAL_PRINT_FORMAT3`, default :code:`"%15.12f"` (12 decimal digits, 15 total digits);
+- :code:`REAL_PRINT_FORMAT5`, default :code:`"%17.12f"` (12 decimal digits, 17 total digits).
+
 Testing Neper
 -------------
 
@@ -216,7 +222,7 @@ String completion is available for all options, so they may be abbreviated as lo
 
 Logical options can be enabled or disabled by providing argument values of :data:`1` or :data:`0`, respectively.  Integer or real arguments can be written as numeral values or :ref:`mathematical_and_logical_expressions`.  For instance, in module -T, option :data:`-rcl 0.5` can also be written as :data:`-rcl 1/2` or :data:`-rcl "cos(pi/3)"`.  For some options, different values can be specified to different entities by loading them from an external :ref:`data_file` (or similar), using :data:`file(<file_name>)`.  For the more complex case of a multiscale tessellation, a :ref:`multiscale_cell_file` can also be used, and loaded using :data:`msfile(<file_name>)`.
 
-Module -V shows some exceptions with respect to these rules: the argument cannot be listed in arbitrary order, string completion is not available, and option :option:`-loop` takes several arguments.
+Module -V shows some exceptions with respect to these rules: the argument can only be listed in arbitrary order before their corresponding :option:`-print` call, string completion is not available for custom input options, and option :option:`-loop` takes several arguments.
 
 Argument Separators
 ~~~~~~~~~~~~~~~~~~~

doc/fileformat.rst

@@ -6,13 +6,15 @@
 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`.  A :ref:`simulation_directory` is typically generated from an FEPX raw result directory, which can be done as simply as follows:
+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 from an FEPX raw result directory, which can be done as simply as follows:
 
 .. code-block:: console
 
   $ neper -S <fepx_raw_result_directory>
 
-A :ref:`simulation_directory` can also be generated by the :ref:`neper_t` or the :ref:`neper_m` (option :data:`-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.
+A :ref:`simulation_directory` 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.
 
@@ -78,8 +80,8 @@ Input Data
 
   Specify the name of the input directory, which can be:
 
-  - an FEPX raw result directory [#f1]_  (to convert into a simulation directory);
-  - a simulation directory;
+  - an FEPX raw result directory [#f1]_  (to convert into a :ref:`simulation_directory`);
+  - a :ref:`simulation_directory`;
   - a series of simulation directories combined with :data:`,` (to merge).
 
   **Default value**: -.
@@ -106,7 +108,7 @@ Entity Options
 
 .. option:: -entity <name>:<logical_expression>
 
-  Define a new entity (based on elements) from one or several logical expressions based on the variables described in :ref:`mesh_keys`. The argument can be:
+  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(<file_name>)`: logical expressions to load from a file.
@@ -118,11 +120,26 @@ Entity Options
 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. [#f2]_  Results of element-based entities (including :data:`elset` and :data:`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.
+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,<entity>} <res1>,<res2>,...
 
-  Specify the results to add, remove or update.  Provide as argument :data:`<res>`, :data:`'!<res>'` [#quotes]_  or :data:`\\\<res\>` to add, remove or update result :data:`<res>`, respectively.  Provide :data:`<res><X>` or :data:`<res>\<X\>\<Y\>` to get a specific component of an existing result (:data:`<X>` or :data:`<X>\<Y\>`, vectorial or tensorial, respectively, 1-indexed) [#f3]_ , :data:`<res>:file(<basename>)` to import results from files of basename :data:`<basename>` (the files of the different steps must be available as :data:`<basename>.step*`; if the file does not exist, it is attempted to read from :data:`<basename>`), or any expression based on the tessellation, mesh or simulation results (the mesh results can be any variables described in :ref:`tessellation_keys`, :ref:`raster_tessellation_keys` and :ref:`mesh_keys`). For nodes, :data:`disp` can be used to get the node displacements from the node coordinates. To use a simulation result at a specific step, use :data:`<res>(step=<step_nb>)`, where :data:`<res>` is the result and :data:`<step_nb>` is the step number. To define a name corresponding to a result, use :data:`<name>:\<expression\>`, where :data:`<name>` is the name and :data:`<expression>` is its expression. To provide several values, combine them with :data:`,`.
+  Specify the results to add, remove or update, using :data:`<res>`, :data:`'!<res>'` [#quotes]_  or :data:`\\\<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 :data:`<name>:\<expression\>`, where :data:`<name>` is the name and :data:`<expression>` 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:`<res>`: 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:`<res>_\<operation>`: 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:`<res>\<X\>` or :data:`<res>\<X\>\<Y\>`: a specific component of an existing result (:data:`<X>` or :data:`<X>\<Y\>`, vectorial or tensorial, respectively, 1-indexed) [#f3]_;
+   - :data:`file(<basename>)` (in which case a name *must* be assigned, as in :data:`<name>:file(<basename>)`): a custom result to be loaded from files of basename :data:`<basename>` (files :data:`<basename>.step*` if they exist, and :data:`<basename>` otherwise).
+
+  .. note:: To use a simulation result at a specific step, use :data:`<res>(step=<step_nb>)`, where :data:`<res>` is the result and :data:`<step_nb>` is the step number.
 
   **Default value**: -.
 
@@ -213,3 +230,5 @@ Below are some examples of use of neper -S.
 .. [#f3] The original result, :data:`<res>`, 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}`.

doc/introduction.rst

@@ -119,7 +119,11 @@ Input Data
 
   - :data:`euler-bunge(<size_x>,<size_y>,<size_z>)`: the Euler space (Bunge convention), where :data:`<size_x>`, :data:`<size_y>` and :data:`<size_z>` are the space dimensions (in degrees or radians [#euler-bunge]_);
 
-  - :data:`stdtriangle(<segment_nb>)`: a standard stereographic triangle, where :data:`<segment_nb>` is the number of segments used to describe the [011]--[111] line.
+  - :data:`stdtriangle(crysym=<crysym>,projection=<projection>,segmentnb=<segment_nb>)`: a standard stereographic triangle, with the optional arguments:
+
+    - :data:`crysym`: the crystal symmetry (default :data:`cubic`);
+    - :data:`projection`: the projection (default :data:`stereographic`);
+    - :data:`segmentnb`: the number of segments along the curved edge (default :data:`20`);
 
   The transformation can be:
 
@@ -455,6 +459,14 @@ The following option can be used to define cell groups (each cell is assigned to
 Crystal Orientation Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. option:: -crysym <crysym>
+
+  Specify the :ref:`Crystal Symmetry <crystal_symmetries>`.
+
+  .. note :: It is used by option :data:`-ori uniform`, to reduce the domain of definition of the orientation descriptors and by the :ref:`neper_v`.
+
+  **Default value**: :data:`triclinic`.
+
 .. option:: -ori <ori_distrib>
 
   Specify the type of crystal orientation distribution. It can be:
@@ -501,14 +513,6 @@ Crystal Orientation Options
 
   **Default value**: :data:`none`.
 
-.. option:: -oricrysym <crysym>
-
-  Specify the :ref:`Crystal Symmetry <crystal_symmetries>`.
-
-  This is used by option :data:`-ori uniform` and to reduce the domain of definition of the orientation descriptors.
-
-  **Default value**: :data:`triclinic`.
-
 .. option:: -orioptiini <ori_distrib> (secondary option)
 
   Specify the initial crystal orientations, which can be: