Add new capabilities

- module -T: fixed -morpho cube, added -statcell and -statvox
  <orientation_descriptor>, added -ori :flat, added -transform ori, made minor
  fix to the objective function for tesr (does not change the result), made
  minor fixes to -statface and -statpoly, made other minor fixes.
- module -M: added -transform node and ori, fixed -stateltco and -statelsetco,
  added -stat{elt,elset}{1d,2d} theta, fixed nsets in 2D, added -statelt and
  -statelset <orientation_descriptor>, added -statelset scaleid, added
  -statelset* elts,nodenb,nodes, made minor fix to inp output, made minor fixes
  and improvements.
- module -S: fixed various bugs related to the initial state, revised odf and
  odfn, made minor other improvements.
- module -V: added -datacellsymbol, -datapointsymbol, -lightambient,
  -lightsource, -lightdiffuse and -lightreflection options, added -space pf to
  plot pole figures, added -space tree to plot a simulation directory, added
  -asymptote, added -pfpole, -pfprojection, -pfmode, -pfgrid, -pfkernel,
  -pfdir, -pfclustering, -pfsym and -pfshape options, renamed -imageantialias
  into -povrayantialiasing, added :shape transformation to color maps, made
  minor fixes.
- documentation: made minor improvements.
- general: added tutorials to documentation, fixed FORCE_BUILTIN_*
  configuration options, made various installation improvements.

Author: rquey

VERSIONS

@@ -1,17 +1,33 @@
-New in 4.4.2-34 (25 Aug 2022):
-- module -T: fixed -morpho cube, made minor fixes, added -statcell and -statvox
+New in 4.5.0 (07 Sep 2022):
+- module -T: fixed -morpho cube, added -statcell and -statvox
   <orientation_descriptor>, added -ori :flat, added -transform ori, made minor
   fix to the objective function for tesr (does not change the result), made
-  minor fixes to -statface and -statpoly.
+  minor fixes to -statface and -statpoly, made other minor fixes.
 - module -M: added -transform node and ori, fixed -stateltco and -statelsetco,
-  made minor fix to inp output, made minor fixes, added -stat{elt,elset}{1d,2d}
-  theta, added -statelt and -statelset <orientation_descriptor>, added
-  -statelset* elts,nodenb,nodes, made minor fixes.
-- module -S: fixed various bugs related to the initial state, made minor other
-  fixes.
-- module -V: made minor fixes.
-- general: fixed FORCE_BUILTIN_* configuration options, made various
-  installation improvements.
+  added -stat{elt,elset}{1d,2d} theta, fixed nsets in 2D, added -statelt and
+  -statelset <orientation_descriptor>, added -statelset scaleid, added
+  -statelset* elts,nodenb,nodes, made minor fix to inp output, made minor fixes
+  and improvements.
+- module -S: fixed various bugs related to the initial state, revised odf and
+  odfn, made minor other improvements.
+- module -V: added -datacellsymbol, -datapointsymbol, -lightambient,
+  -lightsource, -lightdiffuse and -lightreflection options, added -space pf to
+  plot pole figures, added -space tree to plot a simulation directory, added
+  -asymptote, added -pfpole, -pfprojection, -pfmode, -pfgrid, -pfkernel,
+  -pfdir, -pfclustering, -pfsym and -pfshape options, renamed -imageantialias
+  into -povrayantialiasing, added :shape transformation to color maps, made
+  minor fixes.
+- documentation: made minor improvements.
+- general: added tutorials to documentation, fixed FORCE_BUILTIN_*
+  configuration options, made various installation improvements.
+
+* Incompatible changes:  In -V, removed -sceneshadow (merged in -light), renamed
+  -imageantialias into -povrayantialiasing, moved point shape definition to
+  -datapointsymbol, rotated long scale title by 180°, changed syntax for custom
+  color maps from <color1>:<color2>:... to custom(<color1>,<color2>,...).
+  In -S, changed odf(sigma=<value>) using radians into odf(theta=<value>) using
+  degrees, changed odfn(sigma=<value>) using radians into odf(theta=<value>) using
+  degrees.
 
 New in 4.4.1 (09 Mar 2022):
 - module -T: improved -morpho lamellar to avoid unrealistically small lamellae

doc/_static/ini

@@ -0,0 +1 @@
+0.088838317183 0.000000000000 0.176326980708

doc/_static/my_theme.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+  max-width: 1200px !important;
+}

doc/conf.py

@@ -11,8 +11,8 @@
 import sphinx_rtd_theme
 
 project = u'Neper'
-version = u'4.4.2-34'
-release = u'4.4.2-34'
+version = u'4.5.0'
+release = u'4.5.0'
 author = u'Romain Quey'
 copyright = u'Romain Quey'
 language = 'en'
@@ -22,3 +22,11 @@
     'logo_only': False,
     'navigation_depth': 5,
 }
+
+def setup(app):
+    app.add_css_file('my_theme.css')
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

doc/exprskeys.rst

@@ -40,8 +40,8 @@ The following table gives an overview of the functions supported by the default
 :data:`sign`    sign function: -1 if :math:`x<0`; 1 if :math:`x>0`
 :data:`rint`    round to nearest integer
 :data:`abs`     absolute value
-:data:`<min>`     min of all arguments
-:data:`<max>`     max of all arguments
+:data:`min`     min of all arguments
+:data:`max`     max of all arguments
 :data:`sum`     sum of all arguments
 :data:`avg`     mean value of all arguments
 =============== =========================================================
@@ -464,8 +464,9 @@ Available keys for a mesh itself are provided below.  "co" stands for "cohesive"
 
 ======================= ================================================= ==============================
 **Key**                 **Descriptor**                                    **Apply to**
-:data:`eltnb`           element number                                    {0-3}D,co mesh, co-elt mesh
+:data:`eltnb`           element number                                    {0-3}D,co mesh
 :data:`nodenb`          node number                                       {0-3}D mesh
+:data:`elsetnb`         elset number                                      {0-3}D,co mesh
 :data:`partnb`          partition number                                  highest-dimension mesh
 :data:`x`               x coordinate                                      {0-3}D mesh
 :data:`y`               y coordinate                                      {0-3}D mesh
@@ -494,6 +495,7 @@ Available keys for mesh node, elements and element sets (of all dimensions) and
 :data:`elsetco`                                   Cohesive elset                                                        co elt
 :data:`part`                                      partition                                                             {0-3}D elt, node
 :data:`group`                                     group                                                                 {0-3}D elt, {0-3}D elset
+:data:`scaleid(<scale_nb>)`                       identifier of the corresponding tess cell at scale :data:`<scale_nb>` 2D elset, 3D elset
 :data:`cyl`                                       cylinder polygonization [#cyl]_                                       1D elt, 1D elset
 :data:`vol`                                       volume                                                                3D elt, 3D elset
 :data:`area`                                      surface area                                                          2D elt
@@ -561,15 +563,15 @@ A result of a :ref:`simulation directory <simulation_directory>` can be invoked
 
 Available results / keys and concerning orientation distributions are provided below.
 
-===================================== ======================================================================================== ====================================================
-**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(sigma=value)`              ODF defined at elements, with sigma the standard deviation of the kernel (optional)      mesh
-:data:`odfn(sigma=value)`             ODF defined at nodes, with sigma the standard deviation of the kernel (optional)         mesh
-===================================== ======================================================================================== ====================================================
+===================================== ======================================================================================================= ===============
+**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=<value>)`            ODF defined at elements, with :data:`theta` the standard deviation of the kernel (in degrees, optional) mesh
+:data:`odfn(theta=<value>)`           ODF defined at nodes, with :data:`theta` the standard deviation of the kernel (in degrees, optional)    mesh
+===================================== ======================================================================================================= ===============
 
 .. _rotations_and_orientations:
 
@@ -643,7 +645,7 @@ Crystal Symmetries
 Crystal symmetries can be described using the following descriptors.
 
 ======================== ============================================ ========================
-Key                      Descriptor                                   Number of operators
+**Key**                  **Descriptor**                               **Number of operators**
 :data:`triclinic`        triclinic (Laue group :math:`\overline{1}`)  24
 :data:`cubic`            cubic				              24
 :data:`hexagonal`        hexagonal				      1
@@ -821,29 +823,44 @@ Color Maps
 .. _color_map_for_integer_values:
 
 Color Map for Integer Values
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The *color map* or *palette* used to represent integer values is defined from the above color list, by excluding colors of brightness below 0.2 and above 0.8.  The brightness is defined as the average of the channel values divided by 255.  The resulting list of colors is: \(1) :data:`red`, (2) :data:`green`, (3) :data:`blue`, (4) :data:`yellow`, (5) :data:`magenta`, (6) :data:`cyan`, (7) :data:`chartreuse`, (8) :data:`springgreen`, (9) :data:`olive`, (10) :data:`purple`, (11) :data:`teal`, (12) :data:`gray`, (13) :data:`deepskyblue`, (14) :data:`lawngreen`, (15) :data:`darkgray`, (16) :data:`orangered`, (17) :data:`silver`, (18) :data:`darkorange`, (19) :data:`mediumblue`, (20) :data:`indigo`, (21) :data:`lightcoral`, (22) :data:`coral`, (23) :data:`salmon`, (24) :data:`aquamarine`, (25) :data:`gold`, (26) :data:`orange`, (27) :data:`darkmagenta`, (28) :data:`darkcyan`, (29) :data:`peru`, (30) :data:`steelblue`, (31) :data:`mediumspringgreen`, (32) :data:`darkslateblue`, (33) :data:`darkgoldenrod`, (34) :data:`lightsalmon`, (35) :data:`lightskyblue`, (36) :data:`tomato`, (37) :data:`slategray`, (38) :data:`hotpink`, (39) :data:`darkkhaki`, (40) :data:`darkturquoise`, (41) :data:`mediumseagreen`, (42) :data:`mediumvioletred`, (43) :data:`violet`, (44) :data:`greenyellow`, (45) :data:`darkseagreen`, (46) :data:`rosybrown`, (47) :data:`deeppink`, (48) :data:`saddlebrown`, (49) :data:`darkviolet`, (50) :data:`dodgerblue`, (51) :data:`lightslategray`, (52) :data:`burlywood`, (53) :data:`mediumslateblue`, (54) :data:`turquoise`, (55) :data:`skyblue`, (56) :data:`mediumturquoise`, (57) :data:`tan`, (58) :data:`limegreen`, (59) :data:`darksalmon`, (60) :data:`lightsteelblue`, (61) :data:`royalblue`, (62) :data:`palegreen`, (63) :data:`crimson`, (64) :data:`mediumorchid`, (65) :data:`khaki`, (66) :data:`lightgreen`, (67) :data:`darkslategray`, (68) :data:`darkorchid`, (69) :data:`seagreen`, (70) :data:`yellowgreen`, (71) :data:`blueviolet`, (72) :data:`palevioletred`, (73) :data:`olivedrab`, (74) :data:`mediumpurple`, (75) :data:`sandybrown`, (76) :data:`darkolivegreen`, (77) :data:`mediumaquamarine`, (78) :data:`slateblue`, (79) :data:`forestgreen`, (80) :data:`midnightblue`, (81) :data:`lightseagreen`, (82) :data:`orchid`, (83) :data:`cornflowerblue`, (84) :data:`sienna`, (85) :data:`firebrick`, (86) :data:`indianred`, (87) :data:`dimgray`, (88) :data:`chocolate`, (89) :data:`brown`, (90) :data:`goldenrod`, (91) :data:`plum` and (92) :data:`cadetblue`.
 
 .. _color_map_for_real_values:
 
 Color Maps for Real Values
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The color *map* used to represent real values is smooth and obtained by interpolation between nominal colors. `Tinycolormap <https://github.com/yuki-koyama/tinycolormap>`_ is used to generate standard color maps:
-
-================= =============================== ========================
-**Python-style**  **Matlab-style**                **GitHub-style**
-:data:`magma`     :data:`parula`                  :data:`github`
-:data:`inferno`   :data:`heat`
-:data:`plasma`    :data:`hot`
-:data:`viridis`   :data:`jet`
-:data:`cividis`   :data:`gray`
-================= =============================== ========================
-
-and :data:`viridis` is the default.  See `Tinycolormap <https://github.com/yuki-koyama/tinycolormap>`_  for illustrations.
-
-Alternatively, any series of colors can be used to define a color map.  Neper's legacy color map (version :math:`< 4`) is :data:`blue,cyan,yellow,green` and can be obtained using :data:`legacy`.
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The color *map* used to represent real values is smooth and obtained by interpolation between nominal colors. `Tinycolormap <https://github.com/yuki-koyama/tinycolormap>`_ is used to generate standard color maps, and the default is :data:`viridis`. The color maps are
+
+================= ===================================================
+**Key**           **Color bar**
+viridis           .. image:: imgs/color-maps-real/viridis.png
+cividis           .. image:: imgs/color-maps-real/cividis.png
+magma             .. image:: imgs/color-maps-real/magma.png
+inferno           .. image:: imgs/color-maps-real/inferno.png
+plasma            .. image:: imgs/color-maps-real/plasma.png
+parula            .. image:: imgs/color-maps-real/parula.png
+heat              .. image:: imgs/color-maps-real/heat.png
+hot               .. image:: imgs/color-maps-real/hot.png
+jet               .. image:: imgs/color-maps-real/jet.png
+gray              .. image:: imgs/color-maps-real/gray.png
+github            .. image:: imgs/color-maps-real/github.png
+================= ===================================================
+
+Alternatively, a custom color map can be provided as :data:`custom(<color1>,<color2>,...)`.  Neper's legacy color map (version :math:`< 4`) is :data:`custom(blue,cyan,yellow,green)` and can also be obtained using :data:`legacy`:
+
+================= ===================================================
+legacy            .. image:: imgs/color-maps-real/legacy.png
+================= ===================================================
+
+Finally, it is possible to gradually fade the start of a color map, to make it starts with white.  This can be done using the :data:`fade` modifier, following the syntax :data:`<colormap>:fade[(threshold)]`.  The threshold ranges from 0 to 1 and is equal to 0.1 by default.  Fading is applied linearly from 0 (full fading) to the threshold (no fading).  Examples are show below:
+
+================= ===================================================
+viridis:fade      .. image:: imgs/color-maps-real/viridis-fade.png
+viridis:fade(0.2) .. image:: imgs/color-maps-real/viridis-fade0p2.png
+================= ===================================================
 
 .. [#muparser_doc] Taken from the :data:`muparser` `documentation <http://beltoforion.de/article.php?a=muparser>`_
 

doc/fileformat.rst

@@ -807,7 +807,7 @@ The file could be used in :data:`-T` as :data:`-n msfile(<file_name>)::msfile(<f
 Data File
 ---------
 
-A data file provides a number of data to be assigned to entities (seeds, cells, points, etc.).  It must contain the expected number of data.  It is a general, simply-formatted ASCII file that contains a fixed number of data per entity, and the data can be integers, real numbers or character strings.  A real number can have an arbitrary number of digits, but the decimal mark must be :option:`.`.  The data can be separated from each other by spaces, tabulators or newlines (any number as well as arbitrary combinations of them are supported).  However, a good practice is to format the file with the data of one entity per line.  An example of a data file containing 5 values is::
+A data file contains a number of data to be assigned to entities (seeds, cells, points, etc.).  It must contain the expected number of data.  It is a general, simply-formatted ASCII file that contains a fixed number of data per entity, and the data can be integers, real numbers or character strings.  A real number can have an arbitrary number of digits, but the decimal mark must be :option:`.`.  The data can be separated from each other by spaces, tabulators or newlines (any number as well as arbitrary combinations of them are supported).  However, a good practice is to format the file with the data of one entity per line.  An example of a data file containing 5 values is::
 
   2.1235
   5.9564
@@ -836,7 +836,7 @@ An example of a data file containing 5 colors is::
 Position File
 -------------
 
-A position file lists the coordinates of a given number of points.  The file must contain 1 coordinate per point in 1D, 2 coordinates per point in 2D and 3 coordinates per point in 3D.  While the dimension can be known from the context in which the file is read, it can also be specified by appending :data:`:dim` to the name of the position file, where :data:`dim` is the dimension.  A coordinate can be an integer or real number. A real number can have an arbitrary number of digits, but the decimal mark must be :option:`.`.  The coordinates can be separated from each other by spaces, tabulators or newlines (any number as well as arbitrary combinations of them are supported).  However, a good practice is to format the file with one point per line.  An example of a position file containing 5 points in 3D is::
+A position file contains the coordinates of a number of points.  The file must contain 1 coordinate per point in 1D, 2 coordinates per point in 2D and 3 coordinates per point in 3D.  While the dimension can be known from the context in which the file is read, it can also be specified by appending :data:`:dim` to the name of the position file, where :data:`dim` is the dimension.  A coordinate can be an integer or real number. A real number can have an arbitrary number of digits, but the decimal mark must be :option:`.`.  The coordinates can be separated from each other by spaces, tabulators or newlines (any number as well as arbitrary combinations of them are supported).  However, a good practice is to format the file with one point per line.  An example of a position file containing 5 points in 3D is::
 
   2.1235 9.4544 5.2145
   5.9564 3.6884 9.2145