Merge branch 'crystal-examples' into 'development'

some guidance for users

See merge request damask/DAMASK!532

python/damask/_crystal.py

@@ -29,7 +29,29 @@ lattice_symmetries: Dict[CrystalLattice, CrystalFamily] = {
 
 
 class Crystal():
-    """Crystal lattice."""
+    """
+    Representation of a crystal as (general) crystal family or (more specific) as a scaled Bravais lattice.
+
+    Examples
+    --------
+    Cubic crystal family:
+
+    >>> import damask
+    >>> cubic = damask.Crystal(family='cubic')
+    >>> cubic
+    Crystal family: cubic
+
+    Body-centered cubic Bravais lattice with parameters of iron:
+
+    >>> import damask
+    >>> Fe = damask.Crystal(lattice='cI', a=287e-12)
+    >>> Fe
+    Crystal family: cubic
+    Bravais lattice: cI
+    a=2.87e-10 m, b=2.87e-10 m, c=2.87e-10 m
+    α=90°, β=90°, γ=90°
+
+    """
 
     def __init__(self, *,
                  family: CrystalFamily = None,
@@ -38,7 +60,7 @@ class Crystal():
                  alpha: float = None, beta: float = None, gamma: float = None,
                  degrees: bool = False):
         """
-        Representation of crystal in terms of crystal family or Bravais lattice.
+        New representation of a crystal.
 
         Parameters
         ----------
@@ -114,10 +136,10 @@ class Crystal():
         """Represent."""
         family = f'Crystal family: {self.family}'
         return family if self.lattice is None else \
-               '\n'.join([family,
-                          f'Bravais lattice: {self.lattice}',
-                          'a={:.5g}m, b={:.5g}m, c={:.5g}m'.format(*self.parameters[:3]),
-                          'α={:.5g}°, β={:.5g}°, γ={:.5g}°'.format(*np.degrees(self.parameters[3:]))])
+               util.srepr([family,
+                           f'Bravais lattice: {self.lattice}',
+                           'a={:.5g} m, b={:.5g} m, c={:.5g} m'.format(*self.parameters[:3]),
+                           'α={:.5g}°, β={:.5g}°, γ={:.5g}°'.format(*np.degrees(self.parameters[3:]))])
 
 
     def __eq__(self,
@@ -323,7 +345,8 @@ class Crystal():
         Parameters
         ----------
         direction|plane : numpy.ndarray, shape (...,3)
-            Vector along direction or plane normal.
+            Real space vector along direction or
+            reciprocal space vector along plane normal.
 
         Returns
         -------
@@ -344,7 +367,7 @@ class Crystal():
                  uvw: FloatSequence = None,
                  hkl: FloatSequence = None) -> np.ndarray:
         """
-        Calculate crystal frame vector along lattice direction [uvw] or plane normal (hkl).
+        Calculate crystal frame vector corresponding to lattice direction [uvw] or plane normal (hkl).
 
         Parameters
         ----------
@@ -354,7 +377,24 @@ class Crystal():
         Returns
         -------
         vector : numpy.ndarray, shape (...,3)
-            Crystal frame vector along [uvw] direction or (hkl) plane normal.
+            Crystal frame vector in real space along [uvw] direction or
+            in reciprocal space along (hkl) plane normal.
+
+        Examples
+        --------
+        Crystal frame vector (real space) of Magnesium corresponding to [1,1,0] direction:
+
+        >>> import damask
+        >>> Mg = damask.Crystal(lattice='hP', a=321e-12, c=521e-12)
+        >>> Mg.to_frame(uvw=[1, 1, 0])
+        array([1.60500000e-10, 2.77994155e-10, 0.00000000e+00])
+
+        Crystal frame vector (reciprocal space) of Titanium along (1,0,0) plane normal:
+
+        >>> import damask
+        >>> Ti = damask.Crystal(lattice='hP', a=0.295e-9, c=0.469e-9)
+        >>> Ti.to_frame(hkl=(1, 0, 0))
+        array([ 3.38983051e+09,  1.95711956e+09, -4.15134508e-07])
 
         """
         if (uvw is not None) ^ (hkl is None):