Ticket #11201: trac_11201_solve_documentation_enhancements.patch

File trac_11201_solve_documentation_enhancements.patch, 6.7 KB (added by afleckenstein, 11 years ago)

solve documentation fix

  • sage/symbolic/expression.pyx

    # HG changeset patch
    # User Andrew Fleckenstein <andrew.fleckenstein@gmail.com>
    # Date 1333308572 14400
    # Node ID 33d8f92a8e1eb594736dc8f2173f0cc48e740958
    # Parent  c239be1054e01526a1b0b62da6691061b9dd5587
    Trac 11201: Solve documentation enhancements
    
    diff --git a/sage/symbolic/expression.pyx b/sage/symbolic/expression.pyx
    a b  
    75487548           return corresponding multiplicities.  This keyword is
    75497549           incompatible with ``to_poly_solve=True`` and does not make
    75507550           any sense when solving an inequality.
    7551        
     7551
    75527552        -  ``solution_dict`` - bool (default: False); if True or non-zero,
    75537553           return a list of dictionaries containing solutions. Not used
    75547554           when solving an inequality.
     
    75607560        -  ``to_poly_solve`` - bool (default: False) or string; use
    75617561           Maxima's ``to_poly_solver`` package to search for more possible
    75627562           solutions, but possibly encounter approximate solutions.
    7563            This keyword is incompatible with ``multiplicities=True``
    7564            and is not used when solving an inequality. Setting ``to_poly_solve``
    7565            to 'force' (string) omits Maxima's solve command (usefull when
    7566            some solution of trigonometric equations are lost).
     7563           If set to 'use_grobner=True' (string), the polynomials are simplified using
     7564           Grobner bases before solving. This keyword is incompatible with
     7565           ``multiplicities=True`` and is not used when solving an inequality.
     7566           Setting ``to_poly_solve`` to 'force' (string) omits Maxima's solve
     7567           command (useful when some solution of trigonometric equations are lost).
    75677568       
    75687569        EXAMPLES::
    75697570       
     
    75767577
    75777578        A simple example to show use of the keyword
    75787579        ``multiplicities``::
    7579        
     7580
    75807581            sage: ((x^2-1)^2).solve(x)
    75817582            [x == -1, x == 1]
    75827583            sage: ((x^2-1)^2).solve(x,multiplicities=True)
     
    75997600
    76007601        The following examples show use of the keyword ``to_poly_solve``::
    76017602
    7602             sage: solve(abs(1-abs(1-x)) == 10, x)
     7603            sage: solve(abs(1-abs(1-x)) == 10,x)
    76037604            [abs(abs(x - 1) - 1) == 10]
    76047605            sage: solve(abs(1-abs(1-x)) == 10, x, to_poly_solve=True)
    76057606            [x == -10, x == 12]
     
    76117612            sage: solve(Q*sqrt(Q^2 + 2) - 1, Q, to_poly_solve=True)
    76127613            [Q == 1/sqrt(-sqrt(2) + 1), Q == 1/sqrt(sqrt(2) + 1)]
    76137614
     7615        Here is how 'use_grobner' works::
     7616
     7617                        sage: solve(x == sqrt(x+1), x, to_poly_solve='use_grobner=True')
     7618                        [x == 1/2*sqrt(5) + 1/2]
     7619
    76147620        In some cases there may be infinitely many solutions indexed
    76157621        by a dummy variable.  If it begins with ``z``, it is implicitly
    76167622        assumed to be an integer, a real if with ``r``, and so on::
     
    77697775            P.eval('solveexplicit: true') # switches Maxima to looking for only explicit solutions
    77707776        try:
    77717777            if to_poly_solve != 'force':
    7772                 s = m.solve(x).str()
     7778                s = m.solve(x)
     7779                if (s[0].lhs()!=ex.variables()[0]) or (str(ex.variables()[0]) in s[0].rhs().str()):
     7780                    print("For explicit results, try setting the 'to_poly_solve' keyword to True.") #Give the user a clue if explicit results are not found
     7781                s = s.str()
    77737782            else: # omit Maxima's solve command
    77747783                s = str([])
    77757784        except TypeError, mess: # if Maxima's solve has an error, we catch it
  • sage/symbolic/relation.py

    diff --git a/sage/symbolic/relation.py b/sage/symbolic/relation.py
    a b  
    473473       list or tuple)
    474474   
    475475    -  ``*args`` - variables to solve for.
    476    
     476
     477    -  ``multiplicities`` - bool (default: False); if True,
     478       return corresponding multiplicities.  This keyword is
     479       incompatible with ``to_poly_solve=True`` and does not make
     480       any sense when solving an inequality.
     481
    477482    -  ``solution_dict`` - bool (default: False); if True or non-zero,
    478483       return a list of dictionaries containing the solutions. If there
    479484       are no solutions, return an empty list (rather than a list containing
    480485       an empty dictionary). Likewise, if there's only a single solution,
    481486       return a list containing one dictionary with that solution.
     487
     488    -  ``explicit_solutions`` - bool (default: False); require that
     489       all roots be explicit rather than implicit. Not used
     490       when solving an inequality.
     491
     492    -  ``to_poly_solve`` - bool (default: False) or string; use
     493       Maxima's ``to_poly_solver`` package to search for more possible
     494       solutions, but possibly encounter approximate solutions.
     495       If set to 'use_grobner=True' (string), the polynomials are simplified using
     496       Grobner bases before solving. This keyword is incompatible with
     497       ``multiplicities=True`` and is not used when solving an inequality.
     498       Setting ``to_poly_solve`` to 'force' (string) omits Maxima's solve
     499       command (useful when some solution of trigonometric equations are lost).
    482500   
    483501    EXAMPLES::
    484502   
     
    550568        x: 2, y: 4
    551569        x: -2, y: 4
    552570
     571    A simple example to show use of the keyword
     572    ``multiplicities``::
     573
     574        sage: solve((x^2-1)^2,x)
     575        [x == -1, x == 1]
     576        sage: solve((x^2-1)^2,x,multiplicities=True)
     577        ([x == -1, x == 1], [2, 2])
     578        sage: solve((x^2-1)^2,x,multiplicities=True,to_poly_solve=True)
     579        Traceback (most recent call last):
     580        ...
     581        NotImplementedError: to_poly_solve does not return multiplicities
     582
     583    Here is how the ``explicit_solutions`` keyword functions::
     584
     585        sage: solve(sin(x)==x,x)
     586        [x == sin(x)]
     587        sage: solve(sin(x)==x,x,explicit_solutions=True)
     588        []
     589        sage: solve(x*sin(x)==x^2,x)
     590        [x == 0, x == sin(x)]
     591        sage: solve(x*sin(x)==x^2,x,explicit_solutions=True)
     592        [x == 0]
     593
     594    The following examples show use of the keyword ``to_poly_solve``::
     595
     596        sage: solve(abs(1-abs(1-x)) == 10, x)
     597        [abs(abs(x - 1) - 1) == 10]
     598        sage: solve(abs(1-abs(1-x)) == 10, x, to_poly_solve=True)
     599        [x == -10, x == 12]
     600
     601        sage: var('Q')
     602        Q
     603        sage: solve(Q*sqrt(Q^2 + 2) - 1, Q)
     604        [Q == 1/sqrt(Q^2 + 2)]
     605        sage: solve(Q*sqrt(Q^2 + 2) - 1, Q, to_poly_solve=True)
     606        [Q == 1/sqrt(-sqrt(2) + 1), Q == 1/sqrt(sqrt(2) + 1)]
     607
     608    Here is how 'use_grobner' works::
     609
     610        sage: solve(x == sqrt(x+1), x, to_poly_solve='use_grobner=True')
     611        [x == 1/2*sqrt(5) + 1/2]
     612
    553613    If there is a parameter in the answer, that will show up as
    554614    a new variable.  In the following example, ``r1`` is a real free
    555615    variable (because of the ``r``)::