From 95831e53f621246c2f06ba1090fff26eca39a764 Mon Sep 17 00:00:00 2001
From: Martin Diehl <mail@martin-diehl.net>
Date: Sat, 24 Apr 2021 14:47:52 +0200
Subject: [PATCH] using improved documentation

---
 PRIVATE                          |  2 +-
 python/damask/_grid.py           | 36 ++++++++++++++++----------------
 python/damask/_result.py         |  2 ++
 python/damask/_rotation.py       |  2 +-
 python/damask/_vtk.py            | 30 +++++++++++++++++++++++---
 python/damask/grid_filters.py    | 18 ++++++++++++++--
 python/damask/mechanics.py       |  2 --
 python/damask/solver/__init__.py |  2 +-
 python/damask/tensor.py          |  7 ++-----
 9 files changed, 68 insertions(+), 33 deletions(-)

diff --git a/PRIVATE b/PRIVATE
index d58a002b0..156831f79 160000
--- a/PRIVATE
+++ b/PRIVATE
@@ -1 +1 @@
-Subproject commit d58a002b0a43d240f143aee1396fdc766d87a886
+Subproject commit 156831f7962a1eb965023331a900121c5aee5e55
diff --git a/python/damask/_grid.py b/python/damask/_grid.py
index 5f5bad63d..aebd8f92c 100644
--- a/python/damask/_grid.py
+++ b/python/damask/_grid.py
@@ -164,7 +164,7 @@ class Grid:
         Returns
         -------
         loaded : damask.Grid
-            Geometry representation from file.
+            Grid-based geometry from file.
 
         """
         v = VTK.load(fname if str(fname).endswith('.vtr') else str(fname)+'.vtr')
@@ -198,7 +198,7 @@ class Grid:
         Returns
         -------
         loaded : damask.Grid
-            Geometry representation from file.
+            Grid-based geometry from file.
 
         """
         warnings.warn('Support for ASCII-based geom format will be removed in DAMASK 3.1.0', DeprecationWarning,2)
@@ -294,7 +294,7 @@ class Grid:
         Returns
         -------
         loaded : damask.Grid
-            Geometry representation from file.
+            Grid-based geometry from file.
 
         """
         b = util.DREAM3D_base_group(fname)      if base_group is None else base_group
@@ -336,7 +336,7 @@ class Grid:
         Returns
         -------
         new : damask.Grid
-            Geometry representation from values in table.
+            Grid-based geometry from values in table.
 
         """
         cells,size,origin = grid_filters.cellsSizeOrigin_coordinates0_point(table.get(coordinates))
@@ -378,7 +378,7 @@ class Grid:
         Returns
         -------
         new : damask.Grid
-            Geometry representation from tessellation.
+            Grid-based geometry from tessellation.
 
         """
         if periodic:
@@ -432,7 +432,7 @@ class Grid:
         Returns
         -------
         new : damask.Grid
-            Geometry representation from tessellation.
+            Grid-based geometry from tessellation.
 
         """
         coords = grid_filters.coordinates0_point(cells,size).reshape(-1,3)
@@ -510,7 +510,7 @@ class Grid:
         Returns
         -------
         new : damask.Grid
-            Geometry representation defined by a minimal surface.
+            Grid-based geometry from definition of minimal surface.
 
         Notes
         -----
@@ -635,7 +635,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         # radius and center
@@ -680,7 +680,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         valid = ['x','y','z']
@@ -717,7 +717,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         valid = ['x','y','z']
@@ -747,7 +747,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         return Grid(material = ndimage.interpolation.zoom(
@@ -780,7 +780,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         def mostFrequent(arr,selection=None):
@@ -811,7 +811,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         _,renumbered = np.unique(self.material,return_inverse=True)
@@ -837,7 +837,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         if fill is None: fill = np.nanmax(self.material) + 1
@@ -877,7 +877,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         if offset is None: offset = 0
@@ -914,7 +914,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         def mp(entry,mapper):
@@ -937,7 +937,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         a = self.material.flatten(order='F')
@@ -977,7 +977,7 @@ class Grid:
         Returns
         -------
         updated : damask.Grid
-            Updated geometry representation.
+            Updated grid-based geometry.
 
         """
         def tainted_neighborhood(stencil,trigger):
diff --git a/python/damask/_result.py b/python/damask/_result.py
index 62ee2d8fe..bc3d3916d 100644
--- a/python/damask/_result.py
+++ b/python/damask/_result.py
@@ -277,6 +277,7 @@ class Result:
         -------
         increments : list of ints
             Increment number of all increments within the given bounds.
+
         """
         # compatibility hack
         ln = 3 if self.version_minor < 12 else 10
@@ -303,6 +304,7 @@ class Result:
         -------
         times : list of float
             Simulation time of all increments within the given bounds.
+
         """
         selected = []
         for i,time in enumerate(self.times):
diff --git a/python/damask/_rotation.py b/python/damask/_rotation.py
index 47ac59eb3..6b2869033 100644
--- a/python/damask/_rotation.py
+++ b/python/damask/_rotation.py
@@ -24,7 +24,7 @@ class Rotation:
     - Euler angle triplets are implemented using the Bunge convention,
       with angular ranges of [0,2π], [0,π], [0,2π].
     - The rotation angle ω is limited to the interval [0,π].
-    - The real part of a quaternion is positive, Re(q) > 0
+    - The real part of a quaternion is positive, Re(q) ≥ 0
     - P = -1 (as default).
 
     Examples
diff --git a/python/damask/_vtk.py b/python/damask/_vtk.py
index e415d5e90..2a6cbd3f2 100644
--- a/python/damask/_vtk.py
+++ b/python/damask/_vtk.py
@@ -3,7 +3,6 @@ import multiprocessing as mp
 from pathlib import Path
 
 import numpy as np
-import numpy.ma as ma
 import vtk
 from vtk.util.numpy_support import numpy_to_vtk            as np_to_vtk
 from vtk.util.numpy_support import numpy_to_vtkIdTypeArray as np_to_vtkIdTypeArray
@@ -51,6 +50,11 @@ class VTK:
         origin : iterable of float, len (3), optional
             Spatial origin coordinates.
 
+        Returns
+        -------
+        new : damask.VTK
+            VTK-based geometry without nodal or cell data.
+
         """
         vtk_data = vtk.vtkRectilinearGrid()
         vtk_data.SetDimensions(*(np.array(grid)+1))
@@ -68,7 +72,7 @@ class VTK:
         """
         Create VTK of type vtk.vtkUnstructuredGrid.
 
-        This is the common type for FEM solver results.
+        This is the common type for mesh solver results.
 
         Parameters
         ----------
@@ -80,6 +84,11 @@ class VTK:
         cell_type : str
             Name of the vtk.vtkCell subclass. Tested for TRIANGLE, QUAD, TETRA, and HEXAHEDRON.
 
+        Returns
+        -------
+        new : damask.VTK
+            VTK-based geometry without nodal or cell data.
+
         """
         vtk_nodes = vtk.vtkPoints()
         vtk_nodes.SetData(np_to_vtk(nodes))
@@ -110,6 +119,11 @@ class VTK:
         points : numpy.ndarray of shape (:,3)
             Spatial position of the points.
 
+        Returns
+        -------
+        new : damask.VTK
+            VTK-based geometry without nodal or cell data.
+
         """
         N = points.shape[0]
         vtk_points = vtk.vtkPoints()
@@ -140,6 +154,11 @@ class VTK:
             Name of the vtk.vtkDataSet subclass when opening a .vtk file.
             Valid types are vtkRectilinearGrid, vtkUnstructuredGrid, and vtkPolyData.
 
+        Returns
+        -------
+        loaded : damask.VTK
+            VTK-based geometry from file.
+
         """
         if not os.path.isfile(fname):                                                               # vtk has a strange error handling
             raise FileNotFoundError(f'no such file: {fname}')
@@ -246,7 +265,7 @@ class VTK:
                 raise ValueError('No label defined for numpy.ndarray')
 
             N_data = data.shape[0]
-            data_ = np.where(data.mask,data.fill_value,data) if isinstance(data,ma.MaskedArray) else\
+            data_ = np.where(data.mask,data.fill_value,data) if isinstance(data,np.ma.MaskedArray) else\
                     data
             d = np_to_vtk((data_.astype(np.single) if data_.dtype in [np.double, np.longdouble] else
                            data_).reshape(N_data,-1),deep=True)                                      # avoid large files
@@ -277,6 +296,11 @@ class VTK:
         label : str
             Data label.
 
+        Returns
+        -------
+        data : numpy.ndarray
+            Data stored under the given label.
+
         """
         cell_data = self.vtk_data.GetCellData()
         for a in range(cell_data.GetNumberOfArrays()):
diff --git a/python/damask/grid_filters.py b/python/damask/grid_filters.py
index d82f25ea9..fe5e290c6 100644
--- a/python/damask/grid_filters.py
+++ b/python/damask/grid_filters.py
@@ -1,8 +1,6 @@
 """
 Filters for operations on regular grids.
 
-Notes
------
 The grids are defined as (x,y,z,...) where x is fastest and z is slowest.
 This convention is consistent with the layout in grid vtr files.
 
@@ -263,6 +261,11 @@ def cellsSizeOrigin_coordinates0_point(coordinates0,ordered=True):
         Expect coordinates0 data to be ordered (x fast, z slow).
         Defaults to True.
 
+    Returns
+    -------
+    DNA : tuple with 3 numpy.ndarray of shape (3)
+        Information to reconstruct grid: cells, size, origin.
+
     """
     coords    = [_np.unique(coordinates0[:,i]) for i in range(3)]
     mincorner = _np.array(list(map(min,coords)))
@@ -415,6 +418,11 @@ def cellsSizeOrigin_coordinates0_node(coordinates0,ordered=True):
         Expect coordinates0 data to be ordered (x fast, z slow).
         Defaults to True.
 
+    Returns
+    -------
+    DNA : tuple with 3 numpy.ndarray of shape (3)
+        Information to reconstruct grid: cells, size, origin.
+
     """
     coords    = [_np.unique(coordinates0[:,i]) for i in range(3)]
     mincorner = _np.array(list(map(min,coords)))
@@ -452,6 +460,7 @@ def point_to_node(cell_data):
     -------
     node_data : numpy.ndarray of shape (:,:,:,...)
         Data defined on the nodes of a periodic grid.
+
     """
     n = (  cell_data + _np.roll(cell_data,1,(0,1,2))
          + _np.roll(cell_data,1,(0,))  + _np.roll(cell_data,1,(1,))  + _np.roll(cell_data,1,(2,))
@@ -491,6 +500,11 @@ def coordinates0_valid(coordinates0):
     coordinates0 : numpy.ndarray
         Array of undeformed cell coordinates.
 
+    Returns
+    -------
+    valid : bool
+        Wheter the coordinates lie on a regular grid.
+
     """
     try:
         cellsSizeOrigin_coordinates0_point(coordinates0,ordered=True)
diff --git a/python/damask/mechanics.py b/python/damask/mechanics.py
index 2396d969e..6ba785df1 100644
--- a/python/damask/mechanics.py
+++ b/python/damask/mechanics.py
@@ -1,8 +1,6 @@
 """
 Finite-strain continuum mechanics.
 
-Notes
------
 All routines operate on numpy.ndarrays of shape (...,3,3).
 
 """
diff --git a/python/damask/solver/__init__.py b/python/damask/solver/__init__.py
index 298adb1f7..01cfeed9b 100644
--- a/python/damask/solver/__init__.py
+++ b/python/damask/solver/__init__.py
@@ -1,3 +1,3 @@
-"""Tools to control the various solvers."""
+"""Run simulations directly from python."""
 
 from ._marc     import Marc       # noqa
diff --git a/python/damask/tensor.py b/python/damask/tensor.py
index 00fc7e72a..cf5d94020 100644
--- a/python/damask/tensor.py
+++ b/python/damask/tensor.py
@@ -1,10 +1,7 @@
 """
-Tensor operations.
+Tensor mathematics.
 
-Notes
------
-This is not a tensor class, but a collection of routines
-to operate on numpy.ndarrays of shape (...,3,3).
+All routines operate on numpy.ndarrays of shape (...,3,3).
 
 """