Trac #17379: Add a 'all' option to the .nth_root() method of algebrai…

…c numbers

There is currently no `all` option for the `.nth_root()` method of
algebraic numbers:

{{{
sage: a = QQbar(-1)
sage: a.nth_root(3)
0.500000000000000? + 0.866025403784439?*I
sage: a.nth_root(3, all=True)
...
TypeError: nth_root() got an unexpected keyword argument 'all'
}}}

while such an option exists for other representations of complex
numbers:

{{{
sage: a = CDF(-1)
sage: sage: a.nth_root(3)
0.5000000000000001 + 0.8660254037844386*I
sage: sage: a.nth_root(3, all=True)
[0.5000000000000001 + 0.8660254037844386*I,
 -1.0 + 3.4393603416671414e-16*I,
 0.49999999999999933 - 0.8660254037844389*I]
}}}

The aim of this ticket is to provide one. This feature was requested
today during a workshop at Villetaneuse.

URL: http://trac.sagemath.org/17379
Reported by: tmonteil
Ticket author(s): Thierry Monteil
Reviewer(s): Vincent Delecroix

src/sage/rings/qqbar.py

@@ -3564,14 +3564,21 @@ def sqrt(self, all=False, extend=True):
         else:
            return root
 
-    def nth_root(self, n):
+    def nth_root(self, n, all=False):
         r"""
         Return the ``n``-th root of this number.
 
-        Note that for odd `n` and negative real numbers, ``AlgebraicReal``
-        and ``AlgebraicNumber`` values give different answers: ``AlgebraicReal``
-        values prefer real results, and ``AlgebraicNumber`` values
-        return the principal root.
+        INPUT:
+
+        -  ``all`` - bool (default: ``False``). If ``True``, return a list of
+           all `n`-th roots as complex algebraic numbers.
+
+        .. WARNING::
+
+            Note that for odd `n`, all=`False` and negative real numbers,
+            ``AlgebraicReal`` and ``AlgebraicNumber`` values give different
+            answers: ``AlgebraicReal`` values prefer real results, and
+            ``AlgebraicNumber`` values return the principal root.
 
         EXAMPLES::
 
@@ -3581,8 +3588,40 @@ def nth_root(self, n):
             1.000000000000000? + 1.732050807568878?*I
             sage: QQbar.zeta(12).nth_root(15)
             0.9993908270190957? + 0.03489949670250097?*I
+
+        You can get all ``n``-th roots of algebraic numbers::
+
+            sage: AA(-8).nth_root(3, all=True)
+            [1.000000000000000? + 1.732050807568878?*I,
+            -2,
+            1.000000000000000? - 1.732050807568878?*I]
+
+            sage: QQbar(1+I).nth_root(4, all=True)
+            [1.069553932363986? + 0.2127475047267431?*I,
+             -0.2127475047267431? + 1.069553932363986?*I,
+             -1.069553932363986? - 0.2127475047267431?*I,
+             0.2127475047267431? - 1.069553932363986?*I]
+
+        TESTS::
+
+            sage: AA(-8).nth_root(3, all=True)[1]
+            -2
+            sage: _.parent()
+            Algebraic Field
+
+            sage: AA(-2).nth_root(5, all=True) == QQbar(-2).nth_root(5, all=True)   # long time
+            True
         """
-        return self ** ~ZZ(n)
+        if not all:
+            return self ** ~ZZ(n)
+        else:
+            root = QQbar(self) ** ~ZZ(n)
+            zlist = [root]
+            zeta = QQbar.zeta(n)
+            for k in range(1, n):
+                root *= zeta
+                zlist.append(root)
+            return zlist
 
     def as_number_field_element(self, minimal=False):
         r"""