From 350f5eb66a024c68fd2ae0d0e7ce0bd4236b574b Mon Sep 17 00:00:00 2001
From: Philip Eisenlohr <eisenlohr@egr.msu.edu>
Date: Tue, 29 Sep 2020 12:55:00 -0400
Subject: [PATCH] improved from_ODF documentation

---
 python/damask/_rotation.py | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/python/damask/_rotation.py b/python/damask/_rotation.py
index ebfc1b3df..b0c9dab5b 100644
--- a/python/damask/_rotation.py
+++ b/python/damask/_rotation.py
@@ -656,12 +656,7 @@ class Rotation:
     @staticmethod
     def from_ODF(weights,Eulers,N=500,degrees=True,fractions=True,seed=None):
         """
-        Sample discrete orientations from a binned ODF.
-
-        References
-        ----------
-        P. Eisenlohr, F. Roters, Computational Materials Science 42(4), 670-678, 2008
-        https://doi.org/10.1016/j.commatsci.2007.09.015
+        Sample discrete values from a binned ODF.
 
         Parameters
         ----------
@@ -681,6 +676,22 @@ class Rotation:
             A seed to initialize the BitGenerator. Defaults to None, i.e. unpredictable entropy
             will be pulled from the OS.
 
+        Returns
+        -------
+        samples : damask.Rotation of shape (N)
+            Array of sampled rotations closely representing the input ODF.
+
+        Notes
+        -----
+        Due to the distortion of Euler space in the vicinity of ϕ = 0, probability densities, p, defined on
+        grid points with ϕ = 0 will never result in reconstructed orientations as their dV/V = p dγ = p × 0.
+        Hence, it is recommended to transform any such dataset to cell centers that avoid grid points at ϕ = 0.
+
+        References
+        ----------
+        P. Eisenlohr, F. Roters, Computational Materials Science 42(4), 670-678, 2008
+        https://doi.org/10.1016/j.commatsci.2007.09.015
+
         """
         def _dg(eu,deg):
             """Return infinitesimal Euler space volume of bin(s)."""