Clarify simplify_radical and Maxima's radcan

[kcrisman]

We use Maxima's radcan (warning - link may change) for simplify_radical. The documentation claims

Simplifies expr, which can contain logs, exponentials, and radicals, by
converting it into a form which is canonical over a large class of expressions
and a given ordering of variables; that is, all functionally equivalent forms
are mapped into a unique form. For a somewhat larger class of expressions,
radcan produces a regular form. Two equivalent expressions in this class do
not necessarily have the same appearance, but their difference can be
simplified by radcan to zero.

For some expressions radcan is quite time consuming. This is the cost of
exploring certain relationships among the components of the expression for
simplifications based on factoring and partial-fraction expansions of
exponents. 

but it can be really hard to tell exactly what this all means. See this ask.sagemath.org question and #8497, to which this is a followup.

The plan is to rename simplify_radical() to radcan() to match the upstream name. We can then alias simplify_radical() to radcan(), and deprecate the simplify_radical() name.

Afterwards we can attempt to clarify the docs, and provide more examples of radcan()'s usage. We should provide both cautionary examples from our tickets, and some of the use cases that Dr. Fateman has described.

CC: @burcin @zimmermann6

Component: documentation

Keywords: sd48

Author: Michael Orlitzky

Branch/Commit: 5d24f4c

Reviewer: Karl-Dieter Crisman

Issue created by migration from https://trac.sagemath.org/ticket/11912

[kcrisman]

comment:1

We should probably solve this at the same time as #12737.

[orlitzky]

Description changed:

--- 
+++ 
@@ -15,3 +15,8 @@
 exponents. 
 ```
 but it can be really hard to tell exactly what this all means.  See [this ask.sagemath.org question](http://ask.sagemath.org/question/767/simplification-errors-in-simple-expressions) and #8497, to which this is a followup.
+
+The plan is to rename `simplify_radical()` to `radcan()` to match the upstream name. We can then alias `simplify_radical()` to `radcan()`, and deprecate the `simplify_radical()` name.
+
+Afterwards we can attempt to clarify the docs, and provide more examples of `radcan()`'s usage. We should provide both cautionary examples from our tickets, and some of the use cases that Dr. Fateman has described.
+

[burcin]

Replying to @kcrisman:

The plan is to rename simplify_radical() to radcan() to match the upstream name. We can then alias simplify_radical() to radcan(), and deprecate the simplify_radical() name.

Why would we use the Maxima name? It doesn't match any Sage convention. I suggest radical_canonicalize() or canonicalize_radical() in anticipation of other canonicalize_*() methods.

[orlitzky]

comment:4

There is Expression.rectform() (also my fault), but I don't particularly care about the name. Of those two I think I prefer radical_canonicalize().

[orlitzky]

comment:5

Actually, I take that back -- canonicalize_radical() would be better for tab completion if we add other canonicalize_foo() methods.

[orlitzky]

comment:6

Attachment: sage-trac_11912.patch.gz

Here's the deprecation/rename, and a few changes to the docs. I haven't been able to come up with any good use cases for radcan(), but I'm not feeling very imaginative today.

[orlitzky]

comment:7

Note: I haven't updated the function name anywhere, so a ton of tests fail. Just looking for some ideas for now.

[kcrisman]

comment:8

Yeah, and we'll need a doctest for the deprecation as well. Let's think about this for a day or two, but resolve it by the end of SD 48. I think that looking at the simplifications that simplify_radical() does would be sufficient.

[kcrisman]

Changed keywords from none to sd48

[kcrisman]

comment:9

See this comment for both some good use cases and some potential new aliases...