# HG changeset patch
# User KarlDieter Crisman <kcrisman@gmail.com>
# Date 1308190121 14400
# Node ID 6eb48a955eafc11a67f5530ea3e18dca79020edc
# Parent e9f1521444edad5a826d36a1a0ad88dfb5a27def
Add documentation for optional keywords to toplevel solve
diff git a/sage/symbolic/relation.py b/sage/symbolic/relation.py
a

b


479  479  are no solutions, return an empty list (rather than a list containing 
480  480  an empty dictionary). Likewise, if there's only a single solution, 
481  481  return a list containing one dictionary with that solution. 
482   
 482  
 483  There are a few optional keywords if you are trying to solve a single 
 484  equation. They may only be used in that context. 
 485  
 486   ``multiplicities``  bool (default: False); if True, 
 487  return corresponding multiplicities. This keyword is 
 488  incompatible with ``to_poly_solve=True`` and does not make 
 489  any sense when solving inequalities. 
 490  
 491   ``explicit_solutions``  bool (default: False); require that 
 492  all roots be explicit rather than implicit. Not used 
 493  when solving inequalities. 
 494  
 495   ``to_poly_solve``  bool (default: False) or string; use 
 496  Maxima's ``to_poly_solver`` package to search for more possible 
 497  solutions, but possibly encounter approximate solutions. 
 498  This keyword is incompatible with ``multiplicities=True`` 
 499  and is not used when solving inequality. Setting ``to_poly_solve`` 
 500  to 'force' (string) omits Maxima's solve command (useful when 
 501  some solution of trigonometric equations are lost). 
 502  
 503  
483  504  EXAMPLES:: 
484  505  
485  506  sage: x, y = var('x, y') 
… 
… 

520  541  sage: solve( [y^6 == y], y)==solve( y^6 == y, y) 
521  542  True 
522  543  
 544  Here we demonstrate very basic use of the optional keywords for 
 545  a single expression to be solved:: 
 546  
 547  sage: ((x^21)^2).solve(x) 
 548  [x == 1, x == 1] 
 549  sage: ((x^21)^2).solve(x,multiplicities=True) 
 550  ([x == 1, x == 1], [2, 2]) 
 551  sage: solve(sin(x)==x,x) 
 552  [x == sin(x)] 
 553  sage: solve(sin(x)==x,x,explicit_solutions=True) 
 554  [] 
 555  sage: solve(abs(1abs(1x)) == 10, x) 
 556  [abs(abs(x  1)  1) == 10] 
 557  sage: solve(abs(1abs(1x)) == 10, x, to_poly_solve=True) 
 558  [x == 10, x == 12] 
 559  
523  560  .. note:: 
524  561  
525   For more details about solving a single equations, see 
526   the documentation for its solve. 
 562  For more details about solving a single equation, see 
 563  the documentation for the singleexpression 
 564  :meth:`~sage.symbolic.expression.Expression.solve`. 
527  565  
528  566  :: 
529  567  
… 
… 

561  599  be implicitly an integer (hence the ``z``):: 
562  600  
563  601  sage: solve([cos(x)*sin(x) == 1/2, x+y == 0],x,y) 
564   [[x == 1/4*pi + pi*z68, y == 1/4*pi  pi*z68]] 
 602  [[x == 1/4*pi + pi*z78, y == 1/4*pi  pi*z78]] 
565  603  
566  604  Expressions which are not equations are assumed to be set equal 
567  605  to zero, as with `x` in the following example:: 
… 
… 

605  643  sage: solve(x^2>8,x) 
606  644  [[x < 2*sqrt(2)], [x > 2*sqrt(2)]] 
607  645  
608   Use use_grobner if no solution is obtained from to_poly_solve:: 
 646  We use ``use_grobner`` in Maxima if no solution is obtained from 
 647  Maxima's ``to_poly_solve``:: 
609  648  
610  649  sage: x,y=var('x y'); c1(x,y)=(x5)^2+y^216; c2(x,y)=(y3)^2+x^29 
611  650  sage: solve([c1(x,y),c2(x,y)],[x,y]) 