diff --git a/VERSIONS b/VERSIONS index 49d007400..c612904f8 100644 --- a/VERSIONS +++ b/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 diff --git a/doc/_static/ini b/doc/_static/ini deleted file mode 100644 index 03aaa97a5..000000000 --- a/doc/_static/ini +++ /dev/null @@ -1 +0,0 @@ -0.088838317183 0.000000000000 0.176326980708 diff --git a/doc/conf.py b/doc/conf.py index 610e2e736..9360ad1dc 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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' diff --git a/doc/exprskeys.rst b/doc/exprskeys.rst index bc003607e..1919b9d25 100644 --- a/doc/exprskeys.rst +++ b/doc/exprskeys.rst @@ -135,11 +135,12 @@ Available keys for a tessellation itself are provided below. :data:`area` surface area tess :data:`vol` volume tess :data:`size` size (surface area/volume in 2D/3D) tess +:data:`step` simulation step tess =============== =================================== ================== Available keys for tessellation seeds, vertices, edges, faces, polyhedra, crystals and cell groups are provided below. Also note that the keys apply to *cells* if they are tagged to apply to *polyhedra* and the tessellation is 3D and *faces* and the tessellation is 2D, and that keys apply to *crystals* if they apply to *cells*. You may also replace, in the tessellation keys themselves, :data:`poly` by :data:`cell` if the tessellation is 3D and :data:`face` by :data:`cell` if the tessellation is 2D (it applies only in rare cases). For example, for a 2D tessellation, you may use :data:`-statcell ncells` instead of :data:`-statface nfaces`. Keys specific to cells are defined accordingly in the following but also apply to *polys* is the tessellation is 3D and *faces* is the tessellations is 2D. -To turn a key value into a value relative to the mean over all entities (e.g. the relative cell size), append the key expression with the :data:`:rel` modifier. To turn a key value into a value which holds for a unit cell size, append the key expression with the :data:`:uc` modifier. To use as a reference only the *body* or *true* entities (see below), append :data:`b` or :data:`t` to the modifiers, respectively. +To turn a key value into a value relative to the mean over all entities (e.g. the relative cell size), append the key expression with the :data:`:rel` modifier. To turn a key value into a value which holds for a unit cell size, append the key expression with the :data:`:uc` modifier. To use as a reference only the *body* entities (see below), append :data:`b` to the modifiers. ================================= =================================================================================================== ========================================= **Key** **Descriptor** **Apply to** @@ -155,14 +156,13 @@ To turn a key value into a value relative to the mean over all entities (e.g. th :data:`ymax` maximum y coordinate edge, face, poly :data:`zmax` maximum z coordinate edge, face, poly :data:`w` weight (width for a lamellar tessellation) seed, cell -:data:`true` true level ver, edge, face, poly -:data:`body` body level ver, edge, face, poly +:data:`body[]` body level ver, edge, face, poly :data:`state` state ver, edge, face, poly :data:`domtype` type of domain (0 if on a domain vertex, 1 if on a domain edge and 2 if on a domain face) ver, edge, face :data:`domface` domain face (-1 if undefined) face :data:`domedge` domain edge (-1 if undefined) edge :data:`domver` domain vertex (-1 if undefined) ver -:data:`scale` scale face [#multiscale_face]_ +:data:`scale` scale ver, edge, face [#multiscale_entity]_ :data:`length` length edge :data:`area` surface area face, poly, group :data:`vol` volume poly, group @@ -210,19 +210,19 @@ To turn a key value into a value relative to the mean over all entities (e.g. th :data:`per` periodic (1 if periodic, 0 otherwise) ver, edge, face (in 3D) :data:`fiber(...)` 1 if in orientation fiber and 0 otherwise, see :ref:`orientation_fibers` poly :data:`` :ref:`orientation descriptor ` face (in 2D), poly (in 3D) +:data:`step` simulation step ver, edge, face, poly ================================= =================================================================================================== ========================================= Variables consisting of several values (:data:`vers`, etc.) are not available for sorting (option :option:`-sort`). - For a cell, the :data:`body` and :data:`true` variables are - defined as follows, + For a cell, the :data:`body` variable is defined as follows: - - :data:`body` is an integer equal to :data:`0` if the cell is at the domain boundary, i.e. if it shares at least one face with it (edge in 2D), and is equal to :data:`1` or higher otherwise. This is determined as follows: if a cell is surrounded by cells with :data:`body` values equal to or higher than :data:`n`, its :data:`body` value is equal to :data:`n + 1`. Therefore, :data:`body` tends to increase with the distance to the domain boundary and can be used to define cells that may suffer from boundary effects. + - In the general case (:data:`body`, no argument provided), it is an integer equal to :data:`0` if the cell is at the domain boundary, i.e. if it shares at least one face with it (edge in 2D), and is equal to :data:`1` or higher otherwise. This is determined as follows: if a cell is surrounded by cells with :data:`body` values equal to or higher than :data:`n`, its :data:`body` value is equal to :data:`n + 1`. Therefore, :data:`body` tends to increase with the distance to the domain boundary and can be used to define cells that may suffer from boundary effects. - - :data:`true` is an integer equal to :data:`0` it the cell shape is biased by the domain boundary, and is equal to :data:`1` or higher otherwise. A value higher than :data:`0` is achieved if and only if any seed that would have been located outside the domain (where it could not be) would not have affected the shape of the cell. This condition is fulfilled if the distance between the seed of the cell and any of its vertices is lower than the minimum distance between a vertex of the cell and the domain boundary. :data:`true` is extended to values higher than :data:`1` in the same way as body: if a cell is surrounded by cells with :data:`true` values equal to or higher than :data:`n`, its :data:`true` value is equal to :data:`n + 1`. As :data:`body`, :data:`true` tends to increase with the distance to the domain boundary, and :math:`true \leq body`. :data:`true` is especially useful for statistics on the cells (morphology, mesh, etc.), for which only cells with :math:`true \geq 1` should be considered. + - In the case where an expression is provided as argument (:data:`body()`), the expression is a logical expression that defines the boundary to consider, from the domain face (edge in 2D) labels (for a cube, :data:`x0`, :data:`x1`, :data:`y0`, :data:`y1`, :data:`z0` and :data:`z1`). For example, :data:`body(z0||z1)` considers only the :data:`z0` and :data:`z1` domain faces as the boundary, and the more exotic :data:`body(x1&&y0||z1)` considers only the intersection between the :data:`x1` and :data:`y0` domain faces, and the :data:`z1` domain face as the boundary. - For entities of lower dimension than cells (vertices, edges and faces), :data:`body` and :data:`true` are equal to the maximum :data:`body`or :data:`true` values of the cells they belong to. + For entities of lower dimension than cells (vertices, edges and faces), :data:`body` is equal to the maximum :data:`body` value of the cells they belong to. .. _raster_tessellation_keys: @@ -255,6 +255,7 @@ Available keys for raster tessellation itself are provided below. :data:`y` y coordinate tesr :data:`z` z coordinate tesr :data:`coo` x, y and z coordinates tesr +:data:`step` simulation step tesr ===================== ============================================ ====================== Available keys for raster tessellation seeds, cells, cell groups and voxels are provided below. Mathematical and logical expressions based on these keys can also be used. To turn a key value into a value relative to the mean over all entities (e.g.the relative cell size), append the key expression with the :data:`:rel` modifier. To turn a key value into a value which holds for a unit cell size, append the key expression with the :data:`:uc` modifier. @@ -268,6 +269,7 @@ General :data:`cell` cell voxel :data:`oridef` orientation is defined voxel :data:`w` Laguerre weight seed +:data:`step` simulation step tesr ============================ ======================================================================= ==================================== Geometry @@ -477,7 +479,8 @@ Available keys for a mesh itself are provided below. "co" stands for "cohesive" :data:`length` length 1D mesh :data:`area` surface area 2D mesh :data:`vol` volume 3D mesh -:data:`size` size (length/area/volume in 1D/2D/3D) 1D mesh, 2D mesh, 3D mesh +:data:`size` size (length/area/volume in 1D/2D/3D) {1-3}D mesh +:data:`step` simulation step {0-3}D,co mesh ======================= ================================================= ============================== Available keys for mesh node, elements and element sets (of all dimensions) and points are provided below. "co" stands for "cohesive". @@ -498,6 +501,7 @@ Available keys for mesh node, elements and element sets (of all dimensions) and :data:`part` partition {0-3}D elt, node :data:`group` group {0-3}D elt, {0-3}D elset :data:`scaleid()` identifier of the corresponding tess cell at scale :data:`` 2D elset, 3D elset +:data:`scale` scale {0-2}D elset [#multiscale_entity_mesh]_ :data:`cyl` cylinder polygonization [#cyl]_ 1D elt, 1D elset :data:`vol` volume 3D elt, 3D elset :data:`area` surface area 2D elt @@ -517,8 +521,8 @@ Available keys for mesh node, elements and element sets (of all dimensions) and :data:`elts` elements {0-3}D,co elset :data:`nodenb` number of nodes {0-3}D,co elset :data:`nodes` nodes {0-3}D,co elset -:data:`true` true level {0-3}D elt, {0-3}D elset :data:`body` body level {0-3}D elt, {0-3}D elset +:data:`elsetbody` body level, relative to the elset boundary {1-3}D elt :data:`domtype` type of domain [#domtype]_ {0-2}D elt, {0-2}D elset :data:`2dmeshp` closest point of the 2D mesh node, 3D elt :data:`2dmeshd` distance to :data:`2dmeshp` node, 3D elt @@ -526,10 +530,14 @@ Available keys for mesh node, elements and element sets (of all dimensions) and :data:`2dmeshn` outgoing normal vector at :data:`2dmeshp` node, 3D elt :data:`per` periodic (1 if periodic, 0 otherwise) {0,1}D elt, 2D elt (in 3D), {0,1}D elset, 2D elset (in 3D) :data:`col_rodrigues` color in Rodrigues vector convention [#col_rodrigues]_ node -:data:`col_stdtriangle` color in IPF convention [#col_stdtriangle]_ node +:data:`col_stdtriangle` color in IPF convention, cubic symmetry [#col_stdtriangle]_ node +:data:`col_stdtriangle_hexagonal` color in IPF convention, hexagonal symmetry [#col_stdtriangle]_ node :data:`fiber(...)` [#fiber]_ 1 if in orientation fiber and 0 otherwise 3D elt, 3D elset :data:`theta` disorientation angle (in degrees) 1D elt and elset (in 2D), 2D elt and elset (in 3D) +:data:`gos` grain orientation spread [#gos]_ {2,3}D elset +:data:`anisogos` grain orientation spread estimated from the orientation distribution [#gos]_ {2,3}D elset :data:`` :ref:`orientation descriptor ` 2D elt (in 2D), 2D elset (in 2D), 3D elt (in 3D), 3D elset (in 3D) +:data:`step` simulation step {0-3}D,co mesh ================================================= ===================================================================== =================================================================== Variables beginning with :data:`2dmesh` are only available for statistics (options beginning with :data:`-stat` of module -M); for elements, they apply to the centroids. @@ -561,19 +569,37 @@ Available keys for points are provided below. Simulation Results ------------------ -A result of a :ref:`simulation directory ` can be invoked simply from its name. A component of a vectorial or tensorial result can be invoked by prefixing the component to the name, as in :data:`coo1`, :data:`stress11`, etc. For a symmetrical tensor (for which only 6 values are stored), :data:`t`, both :data:`t\\` and :data:`t\\` are valid. The type of a result of the simulation directory is determined automatically. Elset and mesh results can be obtained from the element results, by averaging or other statistical treatments. +A result of a :ref:`simulation_directory` can be invoked simply from its name. A component of a vectorial or tensorial result can be invoked by prefixing the component to the name, as in :data:`coo1`, :data:`stress11`, etc. For a symmetrical tensor (for which only 6 values are stored), :data:`t`, both :data:`t\\` and :data:`t\\` are valid. The type of a result of the simulation directory is determined automatically. Tessellation results can be obtained from the cell results, by averaging or other statistical treatments. Similarly, elset and mesh results can be obtained from the element results, by averaging or other statistical treatments. -Available results / keys and concerning orientation distributions are provided below. +Available results / keys for nodes are the following: -===================================== ======================================================================================================= =============== -**Key** **Descriptor** **Apply to** -:data:`ori` average orientation elset, mesh -:data:`oridisanisoangles` orientation distribution principal angles elset, mesh -:data:`oridisanisoaxes` orientation distribution principal axes elset, mesh -:data:`oridisanisofact` orientation distribution factor elset, mesh -:data:`odf(theta=)` ODF defined at elements, with :data:`theta` the standard deviation of the kernel (in degrees, optional) mesh -:data:`odfn(theta=)` ODF defined at nodes, with :data:`theta` the standard deviation of the kernel (in degrees, optional) mesh -===================================== ======================================================================================================= =============== +========================================== ================================================================ ================================== +**Key** **Descriptor** **Apply to** +:data:`disp` displacement (computed from positions) node +========================================== ================================================================ ================================== + +Available results / keys for elements sets are the following: + +========================================== ================================================================ ================================== +**Key** **Descriptor** **Apply to** +:data:`ori` average orientation elset, mesh +:data:`gos` grain orientation spread [#gos]_ elset +:data:`anisogos` grain orientation spread computed from :data:`oridisanisoangles` elset +:data:`oridisanisoangles` orientation distribution principal angles elset, mesh +:data:`oridisanisoaxes` orientation distribution principal axes elset, mesh +:data:`oridisanisofact` orientation distribution factor elset, mesh +:data:`odf(=,...)` ODF defined at elements of orientation space (see also below) tess, tesr, mesh, cell, elt, elset +:data:`odfn(=,...)` ODF defined at nodes of orientation space (see also below) tess, tesr, mesh +========================================== ================================================================ ================================== + +The ODF (:data:`odf` or :data:`odfn`) of a tessellation or mesh is computed over orientation space (provided using :option:`-orispace`) from the orientations of the (tessellation) cells or (mesh) elsets. The (optional) parameters are: + +- :data:`theta`: the standard deviation of the kernel (in degrees); +- :data:`weight`: the weight of a cell or elset, which can be a real value or an expression based on the :ref:`tessellation_keys` (for cells) or :ref:`mesh_keys` (for elsets) -- by default, the volumes of the cells or elsets are used; +- :data:`cutoff`: the cut-off factor used to compute the ODF, which can be :data:`all` (for no cut-off) or any positive real value (default :data:`5`). + + +For a cell, element or elset, :data:`odf` returns the value of the ODF of the tessellation or mesh at the corresponding orientation (and simulation step). .. _rotations_and_orientations: @@ -866,7 +892,9 @@ viridis:fade(0.2) .. image:: imgs/color-maps-real/viridis-fade0p2.png .. [#muparser_doc] Taken from the :data:`muparser` `documentation `_ -.. [#multiscale_face] Applies only to a 3D tessellation and relevant for multiscale tessellations. The scale of a face is the scale at which the face was created, and it ranges from 0 (for domain faces) to the number of scales of the tessellation (for the last created faces). +.. [#multiscale_entity] Applies only to a 3D tessellation and relevant for multiscale tessellations. The scale of an entity (vertex, edge or face) is the scale at which the entity was created, and it ranges from 0 (for domain entities) to the number of scales of the tessellation (for the last created entities). + +.. [#multiscale_entity_mesh] Applies only to a 3D mesh and relevant for meshes of multiscale tessellations. The scale of an elset is equal to the scale of its corresponding tessellation entity [#multiscale_entity]_. .. [#equivalent_diameter] Equivalent diameter = diameter of the circle of equivalent area/volume in 2D/3D diff --git a/doc/fileformat.rst b/doc/fileformat.rst index cb5261bfd..38532c877 100644 --- a/doc/fileformat.rst +++ b/doc/fileformat.rst @@ -474,7 +474,7 @@ Here are details on the native :file:`.msh` (adapted from Gmsh's msh format vers 2.2 $EndMeshFormat $MeshVersion - 2.2 + $EndMeshVersion $Domain @@ -531,6 +531,9 @@ Here are details on the native :file:`.msh` (adapted from Gmsh's msh format vers ... ... $EndOrientations + $ElsetCrySym + + $EndElsetCrySym $ElementOrientations ori_des1> ... @@ -555,7 +558,7 @@ where - :data:`$MeshVersion` denotes the beginning of a mesh version field. -- :data:`` is the mesh file version (currently :data:`2.2.2`). +- :data:`` 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:`` is the number of elsets. - :data:`` 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:`` 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:`` is the number of elements. diff --git a/doc/introduction.rst b/doc/introduction.rst index a292998bd..937e571ce 100644 --- a/doc/introduction.rst +++ b/doc/introduction.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 `_ 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()`. For the more complex case of a multiscale tessellation, a :ref:`multiscale_cell_file` can also be used, and loaded using :data:`msfile()`. -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 ~~~~~~~~~~~~~~~~~~~ diff --git a/doc/neper_s.rst b/doc/neper_s.rst index 9fde2cc0c..18d628b43 100644 --- a/doc/neper_s.rst +++ b/doc/neper_s.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 -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 : - 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()`: 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,} ,,... - Specify the results to add, remove or update. Provide as argument :data:``, :data:`'!'` [#quotes]_ or :data:`\\\` to add, remove or update result :data:``, respectively. Provide :data:`` or :data:`\\` to get a specific component of an existing result (:data:`` or :data:`\`, vectorial or tensorial, respectively, 1-indexed) [#f3]_ , :data:`:file()` to import results from files of basename :data:`` (the files of the different steps must be available as :data:`.step*`; if the file does not exist, it is attempted to read from :data:``), 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:`(step=)`, where :data:`` is the result and :data:`` is the step number. To define a name corresponding to a result, use :data:`:\`, where :data:`` is the name and :data:`` is its expression. To provide several values, combine them with :data:`,`. + 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**: -. @@ -213,3 +230,5 @@ Below are some examples of use of neper -S. .. [#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}`. diff --git a/doc/neper_t.rst b/doc/neper_t.rst index da8162122..8c2bdeec4 100644 --- a/doc/neper_t.rst +++ b/doc/neper_t.rst @@ -119,7 +119,11 @@ Input Data - :data:`euler-bunge(,,)`: the Euler space (Bunge convention), where :data:``, :data:`` and :data:`` are the space dimensions (in degrees or radians [#euler-bunge]_); - - :data:`stdtriangle()`: a standard stereographic triangle, where :data:`` is the number of segments used to describe the [011]--[111] line. + - :data:`stdtriangle(crysym=,projection=,segmentnb=)`: 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 + + Specify the :ref:`Crystal Symmetry `. + + .. 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 Specify the type of crystal orientation distribution. It can be: @@ -501,14 +513,6 @@ Crystal Orientation Options **Default value**: :data:`none`. -.. option:: -oricrysym - - Specify the :ref:`Crystal Symmetry `. - - 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 (secondary option) Specify the initial crystal orientations, which can be: diff --git a/doc/neper_v.rst b/doc/neper_v.rst index 71efb1044..6c5621975 100644 --- a/doc/neper_v.rst +++ b/doc/neper_v.rst @@ -11,7 +11,7 @@ Visualization Module (-V) ========================= -Module -V is the module for visualizing tessellations, meshes, simulation results and custom data, either as publication-quality (raster) PNG or (vectorial) PDF images, or VTK files, for interactive visualization. Visualization can be done in real (physical) space, but also on pole figures, which is managed by option :option:`-space`. +Module -V is the module for visualizing tessellations, meshes, simulation results and custom data, either as publication-quality (raster) PNG or (vectorial) PDF images, or VTK files, for interactive visualization. Visualization can be done in real (physical) space, but also on pole figures or inverse pole figures, which is managed by option :option:`-space`. Virtually any detail of the visualization can be set. For example, all entities (tessellation polyhedra, faces, edges, vertices, seeds and crystals, 3D, 2D, 1D and 0D mesh elements and nodes, and points) can be assigned a particular color, size, transparency, etc. (options :data:`-data*`), the visibility of the different entities can be adjusted (options :option:`-show*`), or slice views can be generated (option :option:`-slicemesh`). This different capabilities make it possible to carry out standard or advanced visualizations but also post-processing. @@ -19,9 +19,9 @@ Virtually any detail of the visualization can be set. For example, all entities Standard, real space visualizations (default :option:`-space` :data:`real`) are achieved using the POV-Ray ray tracing renderer to produce high-quality (raster) PNG images. The parameters of the "scene" are assigned default values, but can also be fine-tuned, such as the light positions, camera position and angle, projection type, etc. (options :data:`-camera*` and :data:`-light*`). -Pole figure visualizations (:option:`-space` :data:`pf`) are achieved using the Asymptote vector graphics rendered to produce high-quality (raster) PNG images (by default), but also high-quality (vectorial) PDF images. Data can be represented as symbols or a density field, and can be superimposed. +Pole figure and inverse pole figure visualizations (option :option:`-space` :data:`pf`) are achieved using the Asymptote vector graphics rendered to produce high-quality (raster) PNG images (by default) or high-quality (vectorial) PDF images. Data can be represented as symbols or a density field, and can be superimposed. Orientation trajectories can be plotted (option :option:`-step`). -In contrast to other modules, module -V processes the command arguments one after the other. +In contrast to other modules, module -V can generate several outputs on the same run (using option :option:`-print` several times); command arguments are therefore read in batches, stopping at each :option:`print` to generate an output. Here is what a typical run of module -V looks like: @@ -101,7 +101,7 @@ Input Data - :data:`[[(type=)]:]file([,des=])`: a custom input (points, vectors, ...) to load from a :ref:`data_file`, given a custom name, :data:`` (default :data:`point`), and of a specified type, which can be: - :data:`point`: points (default in :option:`-space` :data:`real`); - - :data:`ori`: orientations (default in :option:`-space` :data:`pf`); + - :data:`ori`: orientations (default in :option:`-space` :data:`[i]pf`); - :data:`vector`: vectors. For :data:`ori`, the descriptor can be specified (see :ref:`rotations_and_orientations`, default :data:`rodrigues`). @@ -110,11 +110,26 @@ Input Data **Default value**: -. +.. option:: -crysym + + Specify the :ref:`Crystal Symmetry `. + + .. note:: It is used by option :option:`-space` :data:`[i]pf`. + + **Default value**: value read in the inputs when defined, and :data:`cubic` otherwise. + When a simulation directory is loaded as input, it is possible to specify the simulation step to consider. .. option:: -step - Specify the simulation step (:data:`0` for the initial state)., + Specify the simulation step(s), which can be: + + - :data:`0`: initial state; + - any step number; + - :data:`all`: all steps; + - a list of steps combined with :data:`,`; a range of values can also be specified using :data:`-`. An example is :data:`0-10,20` (for steps 0 to 10, and 20). + + .. note:: Several steps can be specified in the case of :option:`-space` :data:`[i]pf`, to plot orientation trajectories. **Default value**: :data:`0`. @@ -131,6 +146,7 @@ The following option enables the definition of the space in which data (simulati - :data:`real`: real (physical) space; - :data:`pf`: pole figure space; + - :data:`ipf`: inverse pole figure space; - :data:`tree`: tree space. **Default value**: :data:`real`. @@ -154,13 +170,21 @@ The following option enables the definition of the cell data itself (pole figure **Default value**: :data:`ori`. +.. option:: -datacellweight -The following options enable the definition of the properties (color and size) of the tessellation cells or entities (polyhedra, faces, edges and vertices), seeds and crystals. *Crystals* are plotted at the centers of their respective cells, shaped according to the `Crystal Symmetry `_ and have the same volumes as their respective cells. |data_description| + Specify the cell weights, which can be: + + - a real value; + - an expression based on the variables described in :ref:`tessellation_keys`, such as :data:`x` or :data:`vol`, or in a :ref:`simulation_directory`, which allows to define individual values; + - :data:`file()`: individual values to load from a :ref:`data_file`. + + .. note:: :option:`-datacellweight` applies only in :data:`[i]pf` space (see option :option:`-space`). -For each entity, all attributes can be set, although the may not apply in certain spaces (see option :option:`-space`). Specifically, + **Default value**: :data:`size`. - - :data:`-data{cell,poly,face}rad` applies only in PF space; - - :data:`-data*trs` does not apply in PF space. +The following options enable the definition of the properties (color and size) of the tessellation cells or entities (polyhedra, faces, edges and vertices), seeds and crystals. *Crystals* are plotted at the centers of their respective cells, shaped according to the `Crystal Symmetry `_ and have the same volumes as their respective cells. |data_description| + +For each entity, all attributes can be set, although the may not apply in certain spaces (see option :option:`-space`). Specifically, :data:`-data{cell,poly,face}rad` do not apply in real space. .. index:: single: -datacellcol @@ -320,6 +344,18 @@ For each entity, all attributes can be set, although the may not apply in certai Mesh Data Loading and Rendering Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. option:: -dataelsetweight + + Specify the elset weights, which can be: + + - a real value; + - an expression based on the variables described in :ref:`tessellation_keys`, such as :data:`x` or :data:`vol`, or in a :ref:`simulation_directory`, which allows to define individual values; + - :data:`file()`: individual values to load from a :ref:`data_file`. + + .. note:: :option:`-dataelsetweight` applies only in :data:`[i]pf` space (see option :option:`-space`). + + **Default value**: :data:`size`. + The following options enable the definition of the properties (color, size, etc.) of the mesh entities (3D, 2D, 1D and 0D elements and elsets, nodes, and full mesh). :data:`elt` and :data:`elset` refer to the elements and elsets of higher dimensions. The dimension can be also be specified explicitly, as in :data:`elt2d` or :data:`elset2d`. :data:`node` represents all nodes, and :data:`mesh` the full mesh. |data_description| .. option:: -data{elt,elset,node,elt{0-3}d,elset{0-3}d,elt{2,3}dedge,mesh}col @@ -407,7 +443,7 @@ The following options enable the definition of the properties (color, size, etc. **Default value**: -. -.. option:: -data{elt{0,1}d,node,elt{2,3}dedge,elset{0,1}d}rad +.. option:: -data{elt{0,1}d,node,elt{2,3}dedge,elset{0-3}d}rad Specify the radii, which can be: @@ -416,7 +452,6 @@ The following options enable the definition of the properties (color, size, etc. **Default value**: mesh dependent. - The following options enable the loading of node positions. .. option:: -datanodecoo @@ -798,10 +833,12 @@ Scene Options **Default value**: :data:`white`. -Pole Figure Options -~~~~~~~~~~~~~~~~~~~~ +Pole Figure and Inverse Pole Figure Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Most options apply to pole figures or inverse pole figures and can equivalently be called as :option:`-pf...` or :option:`-ipf...`. For inverse pole figures, cubic crystal symmetry is assumed. -.. option:: -pfdir : +.. option:: -[i]pfdir : Specify the 2 reference coordinate system directions aligned with the horizontal and vertical directions of the pole figure, respectively, which can be :data:`x`, :data:`y`, :data:`z`, :data:`-x`, :data:`-y` or :data:`-z`. @@ -809,13 +846,13 @@ Pole Figure Options **Default value**: :data:`x:-y`. -.. option:: -pfpole :: +.. option:: -[i]pfpole :: or ::: - Specify the pole family (for orientation input). + Specify the pole (for orientation input). It is a crystal (family) direction for pole figures and a reference direction for inverse pole figures. A crystal family direction can be specified using Miller indices (3 values, for cubic) or Miller-Bravais indices (4 values, for hexagonal). - **Default value**: :data:`1:1:1`. + **Default value**: :data:`1:1:1` for :option:`-space pf` and cubic crystal symmetry, :data:`0:0:0:1` for :option:`-space pf` and hexagonal crystal symmetry, and :data:`0:0:1` for :option:`-space ipf`. -.. option:: -pfprojection +.. option:: -[i]pfprojection Specify the projection, which can be :data:`stereographic` or :data:`equal-area`. @@ -823,7 +860,7 @@ Pole Figure Options .. option:: -pfsym - Specify the symmetry, which can be :data:`monoclinic` or :data:`orthotropic`. + Specify the symmetry, which can be :data:`monoclinic`, :data:`orthotropic` or :data:`uniaxial`. **Default value**: :data:`monoclinic`. @@ -833,7 +870,7 @@ Pole Figure Options **Default value**: :data:`full`. -.. option:: -pfmode ,,... +.. option:: -[i]pfmode ,,... Specify the representation mode, which can be: @@ -842,9 +879,9 @@ Pole Figure Options .. note:: Modes are processed successively, so that the last one(s) are printed on top of the first one(s). In the case of multiple inputs, :data:`density` is applied only to the first input. - **Default value**: :data:`point`. + **Default value**: :data:`symbol`. -.. option:: -pfkernel +.. option:: -[i]pfkernel Specify the kernel used to smooth pole directions when computing a pole density field, which can be: @@ -852,26 +889,40 @@ Pole Figure Options **Default value**: :data:`normal(theta=3)`. -.. option:: -pfgridsize (secondary option) +.. option:: -[i]pfgridsize (secondary option) Specify the size of the density grid (in pixels). **Default value**: :data:`200`. -.. option:: -pfclustering +.. option:: -[i]pfclustering Specify whether data clustering (which speeds up density generation) should be used. - .. note:: Clustering applies to all representation modes and slightly alters the point positions. It should be disable for absolute accuracy. + .. note:: Clustering is available only for standard pole figures (:option:`-space` :data:`pf` :option:`-pfshape` :data:`full`). + + Clustering applies to all representation modes (see :option:`-[i]pfmode`) and slightly alters the point positions. It should be disable for absolute accuracy. **Default value**: :data:`1`. -.. option:: -pffont (secondary option) +.. option:: -[i]pffont (secondary option) Specify the character font, which can be :data:`TimesRoman` or :data:`ComputerModern`. **Default value**: :data:`TimesRoman`. +.. option:: -[i]pfprojectionlabel