Point users of solve() to the to_poly_solve option

[benjaminfjones]

Many users of of the solve() function complain that Sage can't solve some simple equations, when in fact it can if the to_poly_solve=True option is passed. See, for example:

 http://ask.sagemath.org/question/506/solving-complex-equation

sage: z = var('z')
sage: solve(sin(z) + cos(z) == 2, z)
[sin(z) == -cos(z) + 2]

I propose that when Maxima returns an implicit solution, solve() should display an informative message to the user about the existence of the to_poly_solve parameter.

[kcrisman]

I further propose that this ticket should clarify all the options involved - I still don't get the !use_grobner one.

[afleckenstein]

solve documentation fix

[afleckenstein]

The patch I have created does two main things. First, it modifies the documentation in sage.symbolic.expression.Expression.solve and sage.symbolic.relation.solve to convey mostly the same information, as well as include all of the options (including 'use_grobner'.) Second, it gives the user a clue when explicit results are not found. Specifically, it points the user to the to_poly_solve option, per benjaminfjones's request. I don't know if this should be included, as it gets monotonous to see the message over and over again very quickly.

[kcrisman]

A few comments.

• One of the examples is over-indented
• The examples in the global solve should be somehow marked as only applying to single expressions, not lists of expressions (and in particular multiplicities only does, I think)
• The error message or whatever you call it should be doctested

But this is well on the way to a great addition, thank you for taking the time to do something tedious but necessary. Please feel free to add yourself to the main list of Trac users, and please put your name as you desire it in Authors below.

[benjaminfjones]

That's a good start. Thanks for the contribution!

I started looking at the patch and I have a couple of comments. First, I tried running doctests on sage/symbolic/expression.pyx and there are a lot of new failures due to the unexpected info message that's been added. For example,

jonesbe@macbook ~/sage/latest/devel/sage> ../../sage -t sage/symbolic/expression.pyx
sage -t  "devel/sage-test/sage/symbolic/expression.pyx"     
**********************************************************************
File "/Users/jonesbe/sage/sage-5.0.beta12/devel/sage-test/sage/symbolic/expression.pyx", line 7761:
    sage: f.roots(x)
Expected:
    [(a, 1), (-I, 1), (I, 1), (1, 3), (-1, 3)]
Got:
    For explicit results, try setting the 'to_poly_solve' keyword to True.
    [(a, 1), (-I, 1), (I, 1), (1, 3), (-1, 3)]

There might be other doctest failures besides ones related to the new message, I don't have time to look through them all right now.

---

I'm still not sure what exactly setting to_poly_solve='use_grobner=true' does. Consider the following Sage-5.0.beta12 session (with your patch applied):

Here is what Maxima (5.26.0) does:

sage: maxima('load(to_poly_solver)')
"/Users/jonesbe/sage/sage-5.0.beta12/local/share/maxima/5.26.0/share/contrib/to_poly_solver.mac"
sage: maxima('to_poly_solve([x^2+y^2=2^2,(x-1)^2+(y-1)^2=2^2],[x,y]);')
%union()
sage: maxima('to_poly_solve([x^2+y^2=2^2,(x-1)^2+(y-1)^2=2^2],[x,y],use_grobner=true);')
%union([x=-(sqrt(7)-1)/2,y=(sqrt(7)+1)/2],[x=(sqrt(7)+1)/2,y=-(sqrt(7)-1)/2])

Here is what Sage does (same system of equations, same options):

sage: solve(x == sqrt(x+1), x)
For explicit results, try setting the 'to_poly_solve' keyword to True.
[x == sqrt(x + 1)]
sage: solve(x == sqrt(x+1), x, to_poly_solve=True)
For explicit results, try setting the 'to_poly_solve' keyword to True.
[x == 1/2*sqrt(5) + 1/2]
sage: solve(x == sqrt(x+1), x, to_poly_solve='use_grobner=true')
For explicit results, try setting the 'to_poly_solve' keyword to True.
[x == 1/2*sqrt(5) + 1/2]

So it seems like use_grobner has no effect, despite it having an effect in Maxima. Is it always set to true when to_poly_solve=True is specified? If so, we should really get rid of this confusing solve option. If there is a good example where it actually has an effect, that should be added to the EXAMPLES:: section in the solve docs. The example illustrating it right now doesn't change if you set to_poly_solve=True instead of to_poly_solve='use_grobner=true':

sage: solve(x == sqrt(x+1), x)
For explicit results, try setting the 'to_poly_solve' keyword to True.
[x == sqrt(x + 1)]
sage: solve(x == sqrt(x+1), x, to_poly_solve=True)
For explicit results, try setting the 'to_poly_solve' keyword to True.
[x == 1/2*sqrt(5) + 1/2]
sage: solve(x == sqrt(x+1), x, to_poly_solve='use_grobner=true')
For explicit results, try setting the 'to_poly_solve' keyword to True.
[x == 1/2*sqrt(5) + 1/2]

Last comment: I think the info message should not be printed when I do give to_poly_solve= a value (see last two commands in the last session).

[afleckenstein]

Replying to benjaminfjones:

Here is what Sage does (same system of equations, same options):

Using the same system of equations in sage does this:

sage: y=var('y')
sage: solve([x^2+y^2==2^2, (x-1)^2+(y-1)^2==2^2], [x, y], to_poly_solve=True)
[[x == -1/2*sqrt(7) + 1/2, y == 1/2*sqrt(7) + 1/2], [x == 1/2*sqrt(7) + 1/2, y == -1/2*sqrt(7) + 1/2]]

I'm sure this is what you meant :-)

Which makes is seem that use_grobner is set to true automatically if to_poly_solve is set to true. I think we should forget about printing a message and just focus on fixing the documentation, but I ran into a bit of a dead end with #12809. I guess the failing doctests could be rewritten, or a shorter message could be added in the documentation (e.g. "If you don't get explicit results, try setting to_poly_solve to True.")