better document

make damask.mpie.de colorful ;)

python/damask/_grid.py

@@ -525,7 +525,7 @@ class Grid:
         periods : integer, optional.
             Number of periods per unit cell. Defaults to 1.
         materials : (int, int), optional
-            Material IDs. Defaults to (1,2).
+            Material IDs. Defaults to (0,1).
 
         Returns
         -------
@@ -559,6 +559,30 @@ class Grid:
         M.-T. Hsieh and L. Valdevit, Software Impacts 6:100026, 2020
         https://doi.org/10.1016/j.simpa.2020.100026
 
+        Examples
+        --------
+        Minimal surface of 'Gyroid' type.
+
+        >>> import numpy as np
+        >>> import damask
+        >>> damask.Grid.from_minimal_surface(np.array([64]*3,int),np.ones(3),
+        ...                                  'Gyroid')
+        cells  a b c: 64 x 64 x 64
+        size   x y z: 1.0 x 1.0 x 1.0
+        origin x y z: 0.0   0.0   0.0
+        # materials: 2
+
+        Minimal surface of 'Neovius' type. non-default material IDs.
+
+        >>> import numpy as np
+        >>> import damask
+        >>> damask.Grid.from_minimal_surface(np.array([80]*3,int),np.ones(3),
+        ...                                  'Neovius',materials=(1,5))
+        cells  a b c: 80 x 80 x 80
+        size   x y z: 1.0 x 1.0 x 1.0
+        origin x y z: 0.0   0.0   0.0
+        # materials: 2 (min: 1, max: 5)
+
         """
         x,y,z = np.meshgrid(periods*2.0*np.pi*(np.arange(cells[0])+0.5)/cells[0],
                             periods*2.0*np.pi*(np.arange(cells[1])+0.5)/cells[1],

python/damask/_result.py

@@ -704,6 +704,14 @@ class Result:
         T : str
             Name of tensor dataset.
 
+        Examples
+        --------
+        Add the deviatoric part of Cauchy stress 'sigma':
+
+        >>> import damask
+        >>> r = damask.Result('my_file.hdf5')
+        >>> r.add_deviator('sigma')
+
         """
         self._add_generic_pointwise(self._add_deviator,{'T':T})
 
@@ -737,6 +745,14 @@ class Result:
         eigenvalue : {'max', 'mid', 'min'}
             Eigenvalue. Defaults to 'max'.
 
+        Examples
+        --------
+        Add the minimum eigenvalue of Cauchy stress 'sigma':
+
+        >>> import damask
+        >>> r = damask.Result('my_file.hdf5')
+        >>> r.add_eigenvalue('sigma','min')
+
         """
         self._add_generic_pointwise(self._add_eigenvalue,{'T_sym':T_sym},{'eigenvalue':eigenvalue})
 

python/damask/_rotation.py

@@ -502,6 +502,15 @@ class Rotation:
             Bunge-Euler angles: (φ_1, ϕ, φ_2), φ_1 ∈ [0,2π], ϕ ∈ [0,π], φ_2 ∈ [0,2π]
             unless degrees == True: φ_1 ∈ [0,360], ϕ ∈ [0,180], φ_2 ∈ [0,360]
 
+        Examples
+        --------
+        Cube orientation as Bunge-Euler angles.
+
+        >>> import damask
+        >>> import numpy as np
+        >>> damask.Rotation(np.array([1,0,0,0])).as_Euler_angles()
+        array([0., 0., 0.])
+
         """
         eu = Rotation._qu2eu(self.quaternion)
         if degrees: eu = np.degrees(eu)
@@ -527,6 +536,15 @@ class Rotation:
             Axis angle pair: (n_1, n_2, n_3, ω), ǀnǀ = 1 and ω ∈ [0,π]
             unless degrees = True: ω ∈ [0,180].
 
+        Examples
+        --------
+        Cube orientation as axis angle pair.
+
+        >>> import damask
+        >>> import numpy as np
+        >>> damask.Rotation(np.array([1,0,0,0])).as_axis_angle()
+        array([0., 0., 1., 0.])
+
         """
         ax = Rotation._qu2ax(self.quaternion)
         if degrees: ax[...,3] = np.degrees(ax[...,3])
@@ -541,6 +559,16 @@ class Rotation:
         R : numpy.ndarray of shape (...,3,3)
             Rotation matrix R, det(R) = 1, R.T∙R=I.
 
+        Examples
+        --------
+        Cube orientation as rotation matrix.
+
+        >>> import damask
+        >>> import numpy as np
+        >>> damask.Rotation(np.array([1,0,0,0])).as_matrix()
+        array([[1., 0., 0.],
+               [0., 1., 0.],
+               [0., 0., 1.]])
         """
         return Rotation._qu2om(self.quaternion)
 
@@ -563,6 +591,15 @@ class Rotation:
             numpy.ndarray of shape (...,3) containing
             tan(ω/2) [n_1, n_2, n_3], ω ∈ [0,π].
 
+        Examples
+        --------
+        Cube orientation as 'real' Rodrigues-Frank vector.
+
+        >>> import damask
+        >>> import numpy as np
+        >>> damask.Rotation(np.array([1,0,0,0])).as_Rodrigues_vector(compact=True)
+        array([ 0.,  0., 0.])
+
         """
         ro = Rotation._qu2ro(self.quaternion)
         if compact:
@@ -580,6 +617,15 @@ class Rotation:
         h : numpy.ndarray of shape (...,3)
             Homochoric vector: (h_1, h_2, h_3), ǀhǀ < (3/4*π)^(1/3).
 
+        Examples
+        --------
+        Cube orientation as homochoric vector.
+
+        >>> import damask
+        >>> import numpy as np
+        >>> damask.Rotation(np.array([1,0,0,0])).as_homochoric()
+        array([0., 0., 0.])
+
         """
         return Rotation._qu2ho(self.quaternion)
 
@@ -592,6 +638,15 @@ class Rotation:
         x : numpy.ndarray of shape (...,3)
               Cubochoric vector: (x_1, x_2, x_3), max(x_i) < 1/2*π^(2/3).
 
+        Examples
+        --------
+        Cube orientation as cubochoric vector.
+
+        >>> import damask
+        >>> import numpy as np
+        >>> damask.Rotation(np.array([1,0,0,0])).as_cubochoric()
+        array([0., 0., 0.])
+
         """
         return Rotation._qu2cu(self.quaternion)
 

python/damask/grid_filters.py

@@ -2,7 +2,7 @@
 Filters for operations on regular grids.
 
 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.
+This convention is consistent with the layout in grid vti files.
 
 When converting to/from a plain list (e.g. storage in ASCII table),
 the following operations are required for tensorial data: