state return value

not for Rotation as its docstring is extended by Orientation

python/damask/_colormap.py

@@ -91,6 +91,11 @@ class Colormap(mpl.colors.ListedColormap):
             - 'lab': CIE Lab.
             - 'msh': Msh (for perceptual uniform interpolation).
 
+        Returns
+        -------
+        new : damask.Colormap
+            Colormap within given bounds.
+
         """
         low_high = np.vstack((low,high))
         if   model.lower() == 'rgb':
@@ -150,6 +155,11 @@ class Colormap(mpl.colors.ListedColormap):
            This parameter is not used for matplotlib colormaps
            that are of type `ListedColormap`.
 
+        Returns
+        -------
+        new : damask.Colormap
+            Predefined colormap.
+
         """
         # matplotlib presets
         try:
@@ -239,8 +249,8 @@ class Colormap(mpl.colors.ListedColormap):
 
         Returns
         -------
-        f
+        f : file object
-            File handle
+            File handle with write access.
 
         """
         if fname is None:

python/damask/_grid.py

@@ -161,6 +161,11 @@ class Grid:
             Grid file to read. Valid extension is .vtr, which will be appended
             if not given.
 
+        Returns
+        -------
+        loaded : damask.Grid
+            Geometry representation from file.
+
         """
         v = VTK.load(fname if str(fname).endswith('.vtr') else str(fname)+'.vtr')
         comments = v.get_comments()
@@ -190,6 +195,11 @@ class Grid:
         fname : str, pathlib.Path, or file handle
             Geometry file to read.
 
+        Returns
+        -------
+        loaded : damask.Grid
+            Geometry representation from file.
+
         """
         warnings.warn('Support for ASCII-based geom format will be removed in DAMASK 3.1.0', DeprecationWarning,2)
         try:
@@ -281,6 +291,10 @@ class Grid:
             and grain- or cell-wise data. Defaults to None, in which case
             it is set as the path that contains _SIMPL_GEOMETRY/SPACING.
 
+        Returns
+        -------
+        loaded : damask.Grid
+            Geometry representation from file.
 
         """
         b = util.DREAM3D_base_group(fname)      if base_group is None else base_group
@@ -319,6 +333,11 @@ class Grid:
             Label(s) of the columns containing the material definition.
             Each unique combination of values results in one material ID.
 
+        Returns
+        -------
+        new : damask.Grid
+            Geometry representation from values in table.
+
         """
         cells,size,origin = grid_filters.cellsSizeOrigin_coordinates0_point(table.get(coordinates))
 
@@ -356,6 +375,11 @@ class Grid:
         periodic : Boolean, optional
             Assume grid to be periodic. Defaults to True.
 
+        Returns
+        -------
+        new : damask.Grid
+            Geometry representation from tessellation.
+
         """
         if periodic:
             weights_p = np.tile(weights,27)                                                         # Laguerre weights (1,2,3,1,2,3,...,1,2,3)
@@ -405,6 +429,11 @@ class Grid:
         periodic : Boolean, optional
             Assume grid to be periodic. Defaults to True.
 
+        Returns
+        -------
+        new : damask.Grid
+            Geometry representation from tessellation.
+
         """
         coords = grid_filters.coordinates0_point(cells,size).reshape(-1,3)
         KDTree = spatial.cKDTree(seeds,boxsize=size) if periodic else spatial.cKDTree(seeds)
@@ -478,6 +507,11 @@ class Grid:
         materials : (int, int), optional
             Material IDs. Defaults to (1,2).
 
+        Returns
+        -------
+        new : damask.Grid
+            Geometry representation defined by a minimal surface.
+
         Notes
         -----
         The following triply-periodic minimal surfaces are implemented:
@@ -598,6 +632,11 @@ class Grid:
         periodic : Boolean, optional
             Assume grid to be periodic. Defaults to True.
 
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
         """
         # radius and center
         r = np.array(dimension)/2.0*self.size/self.cells if np.array(dimension).dtype in np.sctypes['int'] else \
@@ -638,6 +677,11 @@ class Grid:
         reflect : bool, optional
             Reflect (include) outermost layers. Defaults to False.
 
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
         """
         valid = ['x','y','z']
         if not set(directions).issubset(valid):
@@ -670,6 +714,11 @@ class Grid:
             Direction(s) along which the grid is flipped.
             Valid entries are 'x', 'y', 'z'.
 
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
         """
         valid = ['x','y','z']
         if not set(directions).issubset(valid):
@@ -695,6 +744,11 @@ class Grid:
         periodic : Boolean, optional
             Assume grid to be periodic. Defaults to True.
 
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
         """
         return Grid(material = ndimage.interpolation.zoom(
                                                            self.material,
@@ -723,6 +777,11 @@ class Grid:
         periodic : Boolean, optional
             Assume grid to be periodic. Defaults to True.
 
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
         """
         def mostFrequent(arr,selection=None):
             me = arr[arr.size//2]
@@ -746,7 +805,15 @@ class Grid:
 
 
     def renumber(self):
-        """Renumber sorted material indices as 0,...,N-1."""
+        """
+        Renumber sorted material indices as 0,...,N-1.
+
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
+        """
         _,renumbered = np.unique(self.material,return_inverse=True)
 
         return Grid(material = renumbered.reshape(self.cells),
@@ -767,6 +834,11 @@ class Grid:
         fill : int or float, optional
             Material index to fill the corners. Defaults to material.max() + 1.
 
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
         """
         if fill is None: fill = np.nanmax(self.material) + 1
         dtype = float if isinstance(fill,float) or self.material.dtype in np.sctypes['float'] else int
@@ -802,6 +874,11 @@ class Grid:
         fill : int or float, optional
             Material index to fill the background. Defaults to material.max() + 1.
 
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
         """
         if offset is None: offset = 0
         if fill is None: fill = np.nanmax(self.material) + 1
@@ -834,6 +911,11 @@ class Grid:
         to_material : iterable of ints
             New material indices.
 
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
         """
         def mp(entry,mapper):
             return mapper[entry] if entry in mapper else entry
@@ -849,7 +931,15 @@ class Grid:
 
 
     def sort(self):
-        """Sort material indices such that min(material) is located at (0,0,0)."""
+        """
+        Sort material indices such that min(material) is located at (0,0,0).
+
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
+        """
         a = self.material.flatten(order='F')
         from_ma = pd.unique(a)
         sort_idx = np.argsort(from_ma)
@@ -884,6 +974,11 @@ class Grid:
         periodic : Boolean, optional
             Assume grid to be periodic. Defaults to True.
 
+        Returns
+        -------
+        updated : damask.Grid
+            Updated geometry representation.
+
         """
         def tainted_neighborhood(stencil,trigger):
 

python/damask/_rotation.py

@@ -357,7 +357,7 @@ class Rotation:
 
         Parameters
         ----------
-            other : Rotation or list of Rotations.
+            other : damask.Rotation
 
         """
         return self.copy(rotation=np.vstack(tuple(map(lambda x:x.quaternion,
@@ -365,12 +365,28 @@ class Rotation:
 
 
     def flatten(self,order = 'C'):
-        """Flatten array."""
+        """
+        Flatten array.
+
+        Returns
+        -------
+            flattened : damask.Rotation
+            Rotation flattened to single dimension.
+
+        """
         return self.copy(rotation=self.quaternion.reshape((-1,4),order=order))
 
 
     def reshape(self,shape,order = 'C'):
-        """Reshape array."""
+        """
+        Reshape array.
+
+        Returns
+        -------
+            reshaped : damask.Rotation
+            Rotation of given shape.
+
+        """
         if isinstance(shape,(int,np.integer)): shape = (shape,)
         return self.copy(rotation=self.quaternion.reshape(tuple(shape)+(4,),order=order))
 
@@ -387,6 +403,11 @@ class Rotation:
             Where to preferentially locate missing dimensions.
             Either 'left' or 'right' (default).
 
+        Returns
+        -------
+            broadcasted : damask.Rotation
+            Rotation broadcasted to given shape.
+
         """
         if isinstance(shape,(int,np.integer)): shape = (shape,)
         return self.copy(rotation=np.broadcast_to(self.quaternion.reshape(util.shapeshifter(self.shape,shape,mode)+(4,)),
@@ -404,7 +425,7 @@ class Rotation:
 
         Returns
         -------
-        average : Rotation
+        average : damask.Rotation
             Weighted average of original Rotation field.
 
         References
@@ -438,9 +459,14 @@ class Rotation:
 
         Parameters
         ----------
-        other : Rotation
+        other : damask.Rotation
             Rotation to which the misorientation is computed.
 
+        Returns
+        -------
+            g : damask.Rotation
+            Misorientation.
+
         """
         return other*~self
 
@@ -531,10 +557,10 @@ class Rotation:
 
         Returns
         -------
-        rho : numpy.ndarray of shape (...,4) containing 
+        rho : numpy.ndarray of shape (...,4) containing
             [n_1, n_2, n_3, tan(ω/2)], ǀnǀ = 1 and ω ∈ [0,π]
             unless compact == True:
-            numpy.ndarray of shape (...,3) containing 
+            numpy.ndarray of shape (...,3) containing
             tan(ω/2) [n_1, n_2, n_3], ω ∈ [0,π].
 
         """