support the user

PRIVATE

@@ -1 +1 @@
-Subproject commit 156831f7962a1eb965023331a900121c5aee5e55
+Subproject commit afffa8d04e110282e514a4e57d0bad9c76effe01

python/damask/__init__.py

@@ -1,11 +1,4 @@
-"""
+"""Tools for managing DAMASK simulations."""
-Tools for pre and post processing of DAMASK simulations.
-
-Modules that contain only one class (of the same name),
-are prefixed by a '_'. For example, '_colormap' contains
-a class called 'Colormap' which is imported as 'damask.Colormap'.
-
-"""
 
 from pathlib import Path as _Path
 import re as _re
@@ -15,7 +8,6 @@ with open(_Path(__file__).parent/_Path('VERSION')) as _f:
     version = _re.sub(r'^v','',_f.readline().strip())
     __version__ = version
 
-# make classes directly accessible as damask.Class
 from .                 import util             # noqa
 from .                 import seeds            # noqa
 from .                 import tensor           # noqa
@@ -23,6 +15,8 @@ from .                 import mechanics        # noqa
 from .                 import solver           # noqa
 from .                 import grid_filters     # noqa
 from .                 import lattice          # noqa
+#Modules that contain only one class (of the same name), are prefixed by a '_'.
+#For example, '_colormap' containsa class called 'Colormap' which is imported as 'damask.Colormap'.
 from ._rotation        import Rotation         # noqa
 from ._orientation     import Orientation      # noqa
 from ._table           import Table            # noqa

python/damask/_colormap.py

@@ -96,6 +96,11 @@ class Colormap(mpl.colors.ListedColormap):
         new : damask.Colormap
             Colormap within given bounds.
 
+        Examples
+        --------
+        >>> import damask
+        >>> damask.Colormap.from_range((0,0,1),(0,0,0),'blue_to_black')
+
         """
         low_high = np.vstack((low,high))
         if   model.lower() == 'rgb':
@@ -160,6 +165,11 @@ class Colormap(mpl.colors.ListedColormap):
         new : damask.Colormap
             Predefined colormap.
 
+        Examples
+        --------
+        >>> import damask
+        >>> damask.Colormap.from_predefined('strain')
+
         """
         # matplotlib presets
         try:
@@ -230,6 +240,11 @@ class Colormap(mpl.colors.ListedColormap):
         damask.Colormap
             The reversed colormap.
 
+        Examples
+        --------
+        >>> import damask
+        >>> damask.Colormap.from_predefined('stress').reversed()
+
         """
         rev = super(Colormap,self).reversed(name)
         return Colormap(np.array(rev.colors),rev.name[:-4] if rev.name.endswith('_r_r') else rev.name)

python/damask/grid_filters.py

@@ -263,8 +263,8 @@ def cellsSizeOrigin_coordinates0_point(coordinates0,ordered=True):
 
     Returns
     -------
-    DNA : tuple with 3 numpy.ndarray of shape (3)
+    cells, size, origin : Three numpy.ndarray, each of shape (3)
-        Information to reconstruct grid: cells, size, origin.
+        Information to reconstruct grid.
 
     """
     coords    = [_np.unique(coordinates0[:,i]) for i in range(3)]
@@ -420,8 +420,8 @@ def cellsSizeOrigin_coordinates0_node(coordinates0,ordered=True):
 
     Returns
     -------
-    DNA : tuple with 3 numpy.ndarray of shape (3)
+    cells, size, origin : Three numpy.ndarray, each of shape (3)
-        Information to reconstruct grid: cells, size, origin.
+        Information to reconstruct grid.
 
     """
     coords    = [_np.unique(coordinates0[:,i]) for i in range(3)]

python/damask/seeds.py

@@ -26,8 +26,8 @@ def from_random(size,N_seeds,cells=None,rng_seed=None):
 
     Returns
     -------
-    new : numpy.ndarray of shape (N_seeds,3)
+    coords : numpy.ndarray of shape (N_seeds,3)
-        Coordinates in 3D space.
+        Seed coordinates in 3D space.
 
     """
     rng = _np.random.default_rng(rng_seed)
@@ -63,8 +63,8 @@ def from_Poisson_disc(size,N_seeds,N_candidates,distance,periodic=True,rng_seed=
 
     Returns
     -------
-    new : numpy.ndarray of shape (N_seeds,3)
+    coords : numpy.ndarray of shape (N_seeds,3)
-        Coordinates in 3D space.
+        Seed coordinates in 3D space.
 
     """
     rng = _np.random.default_rng(rng_seed)
@@ -106,8 +106,8 @@ def from_grid(grid,selection=None,invert=False,average=False,periodic=True):
 
     Returns
     -------
-    new : numpy.ndarray of shape (...,3)
+    coords, materials : numpy.ndarray of shape (:,3), numpy.ndarray of shape (:)
-        Coordinates in 3D space.
+        Seed coordinates in 3D space, material IDs.
 
     """
     material = grid.material.reshape((-1,1),order='F')

python/damask/util.py

@@ -49,7 +49,7 @@ _colors = {
 ####################################################################################################
 def srepr(arg,glue = '\n'):
     r"""
-    Join arguments with glue string.
+    Join items with glue string.
 
     Parameters
     ----------
@@ -58,6 +58,11 @@ def srepr(arg,glue = '\n'):
     glue : str, optional
         Glue used for joining operation. Defaults to \n.
 
+    Returns
+    -------
+    joined : str
+        String representation of the joined items.
+
     """
     if (not hasattr(arg, 'strip') and
            (hasattr(arg, '__getitem__') or
@@ -68,19 +73,71 @@ def srepr(arg,glue = '\n'):
 
 
 def emph(what):
-    """Formats string with emphasis."""
+    """
+    Format with emphasis.
+
+    Parameters
+    ----------
+    what : object with __repr__ or iterable of objects with __repr__.
+        Message to format.
+
+    Returns
+    -------
+    formatted : str
+        Formatted string representation of the joined items.
+
+    """
     return _colors['bold']+srepr(what)+_colors['end_color']
 
 def deemph(what):
-    """Formats string with deemphasis."""
+    """
+    Format with deemphasis.
+
+    Parameters
+    ----------
+    what : object with __repr__ or iterable of objects with __repr__.
+        Message to format.
+
+    Returns
+    -------
+    formatted : str
+        Formatted string representation of the joined items.
+
+    """
     return _colors['dim']+srepr(what)+_colors['end_color']
 
 def warn(what):
-    """Formats string for warning."""
+    """
+    Format for warning.
+
+    Parameters
+    ----------
+    what : object with __repr__ or iterable of objects with __repr__.
+        Message to format.
+
+    Returns
+    -------
+    formatted : str
+        Formatted string representation of the joined items.
+
+    """
     return _colors['warning']+emph(what)+_colors['end_color']
 
 def strikeout(what):
-    """Formats string as strikeout."""
+    """
+    Format as strikeout.
+
+    Parameters
+    ----------
+    what : object with __repr__ or iterable of objects with __repr__.
+        Message to format.
+
+    Returns
+    -------
+    formatted : str
+        Formatted string representation of the joined items.
+
+    """
     return _colors['crossout']+srepr(what)+_colors['end_color']
 
 
@@ -97,6 +154,11 @@ def execute(cmd,wd='./',env=None):
     env : dict, optional
         Environment for execution.
 
+    Returns
+    -------
+    stdout, stderr : str
+        Output of the executed command.
+
     """
     print(f"executing '{cmd}' in '{wd}'")
     process = subprocess.run(shlex.split(cmd),
@@ -157,6 +219,11 @@ def scale_to_coprime(v):
     v : numpy.ndarray of shape (:)
         Vector to scale.
 
+    Returns
+    -------
+    m : numpy.ndarray of shape (:)
+        Vector scaled to co-prime numbers.
+
     """
     MAX_DENOMINATOR = 1000000
 
@@ -371,9 +438,14 @@ def DREAM3D_base_group(fname):
 
     Parameters
     ----------
-    fname : str
+    fname : str or pathlib.Path
         Filename of the DREAM.3D (HDF5) file.
 
+    Returns
+    -------
+    path : str
+        Path to the base group.
+
     """
     with h5py.File(fname,'r') as f:
         base_group = f.visit(lambda path: path.rsplit('/',2)[0] if '_SIMPL_GEOMETRY/SPACING' in path else None)
@@ -393,9 +465,14 @@ def DREAM3D_cell_data_group(fname):
 
     Parameters
     ----------
-    fname : str
+    fname : str or pathlib.Path
         Filename of the DREAM.3D (HDF5) file.
 
+    Returns
+    -------
+    path : str
+        Path to the cell data group.
+
     """
     base_group = DREAM3D_base_group(fname)
     with h5py.File(fname,'r') as f: