Ticket #1829: term-ordering-doc.patch

File term-ordering-doc.patch, 13.0 KB (added by malb, 14 years ago)

  • sage/rings/polynomial/term_order.py 

    # HG changeset patch
# User Martin Albrecht <malb@informatik.uni-bremen.de>
# Date 1200663296 0
# Node ID 45654ca1a75debf2d589089238f407c237dec89a
# Parent  2453d0497684ed6d32d044d1e383ffbea936b03b
some improvements for the Term Ordering documentation

diff -r 2453d0497684 -r 45654ca1a75d sage/rings/polynomial/term_order.py
    a b r""" 
    11r"""
    2 Term Orderings.
     2Term Orderings
    33
    44\SAGE supports the following term orderings:
    55
    66\begin{description}
    7 \item[Lexicographic (\emph{lex})], defined as
     7\item[Lexicographic (\emph{lex})]
    88
    99$x^a < x^b \Leftrightarrow \exists\; 1 \le i \le n : a_1 = b_1, \ldots, a_{i-1} = b_{i-1}, a_i < b_i$
    1010
    … … EXAMPLES: 
    2323
    2424This term ordering is called 'lp' in Singular.
    2525
    26 \item[Degree reverse lexicographic (\emph{degrevlex})], defined as:
     26\item[Degree reverse lexicographic (\emph{degrevlex})]
    2727
    2828Let $deg(x^a) = a_1 + \cdots + a_n,$ then
    2929$x^a < x^b \Leftrightarrow deg(x^a) < deg(x^b)$ or
    … … EXAMPLES: 
    4444
    4545This term ordering is called 'dp' in Singular.
    4646
    47 \item[Degree lexicographic (\emph{deglex})], defined as:
     47\item[Degree lexicographic (\emph{deglex})]
    4848
    4949Let $deg(x^a) = a_1 + \cdots + a_n,$ then
    5050$x^a < x^b \Leftrightarrow deg(x^a) < deg(x^b)$ or
    … … EXAMPLES: 
    6666
    6767This term order is called 'Dp' in Singular.
    6868
    69 \item[Inverse lexicographic (\emph{invlex})], defined as
     69\item[Inverse lexicographic (\emph{invlex})]
    7070
    7171$x^a < x^b \Leftrightarrow \exists\; 1 \le i \le n : a_n = b_n, \ldots, a_{i+1} = b_{i+1}, a_i < b_i.$
    7272
    … … because if P is the ring $k[x_1, \dots,  
    8686'invlex' then it is equivalent to the ring $k[x_n, \dots, x_1]$ with
    8787term ordering 'lex'. This ordering is called 'rp' in Singular.
    8888
    89 \item[Negative lexicographic (\emph{neglex})], defined as
     89\item[Negative lexicographic (\emph{neglex})]
    9090
    9191$x^a < x^b \Leftrightarrow \exists\; 1 \le i \le n : a_1 = b_1, \ldots, a_{i-1} = b_{i-1}, a_i > b_i$
    9292
    … … EXAMPLES: 
    105105
    106106This term ordering is called 'ls' in Singular.
    107107
    108 \item[Negative degree reverse lexicographic (\emph{negdegrevlex})], defined as:
     108\item[Negative degree reverse lexicographic (\emph{negdegrevlex})]
    109109
    110110Let $deg(x^a) = a_1 + \cdots + a_n,$ then
    111111$x^a < x^b \Leftrightarrow deg(x^a) > deg(x^b)$ or
    … … EXAMPLES: 
    126126
    127127This term ordering is called 'ds' in Singular.
    128128
    129 \item[Negative degree lexicographic (\emph{negdeglex})], defined as:
     129\item[Negative degree lexicographic (\emph{negdeglex})]
    130130
    131131Let $deg(x^a) = a_1 + \cdots + a_n,$ then
    132132$x^a < x^b \Leftrightarrow deg(x^a) > deg(x^b)$ or
    … … This term ordering is called 'Ds' in Sin 
    149149
    150150\end{description}
    151151
    152 Of these, only $degrevlex$, $deglex$, $invlex$ and $lex$ are global orderings.
     152Of these, only 'degrevlex', 'deglex', 'invlex' and 'lex' are global orderings.
    153153
    154154Additionally all these monomial orderings may be combined to product
    155155or block orderings, defined as:
    156156
    157 Let $x = (x_0, \ldots, x_{n-1})$ and $y = (y_0, \ldots, y_{m-1})$ be two ordered sets of variables, $<_1$ a
    158 monomial ordering on $k[x]$ and $<_2$ a monomial ordering on $k[y]$.
     157Let $x = (x_0, \ldots, x_{n-1})$ and $y = (y_0, \ldots, y_{m-1})$ be
     158two ordered sets of variables, $<_1$ a monomial ordering on $k[x]$ and
     159$<_2$ a monomial ordering on $k[y]$.
    159160
    160 The product ordering (or block ordering) $<\ := (<_1,<_2)$ on
    161 $k[x,y]$ is defined as:
    162 $x^a y^b < x^A y^B \Leftrightarrow x^a <_1 x^A \textrm{ or }(x^a =x^A \textrm{ and } y^b <_2 y^B)$.
     161The product ordering (or block ordering) $<\ := (<_1,<_2)$ on $k[x,y]$
     162is defined as: $x^a y^b < x^A y^B \Leftrightarrow x^a <_1 x^A$ or
     163$(x^a =x^A \textrm{ and } y^b <_2 y^B)$.
    163164
    164 These block orderings are constructed in SAGE by giving a comma
     165These block orderings are constructed in \SAGE by giving a comma
    165166separated list of monomial orderings with the length of each block
    166167attached to them.
    167168
    … … EXAMPLE: 
    192193   True
    193194
    194195If any other unsupported term ordering is given the provided string is
    195 passed through as is to SINGULAR, Macaulay2, and MAGMA. This ensures
    196 that it is for example possible to calculated a Groebner basis with
    197 respect to some term ordering SINGULAR supports but SAGE doesn't.
     196passed through as is to \textsc{Singular}, \textsc{Macaulay2}, and
     197\textsc{Magma}. This ensures that it is for example possible to
     198calculated a Groebner basis with respect to some term ordering
     199\textsc{Singular} supports but \SAGE doesn't.
    198200
    199201AUTHORS:
    200202    -- David Joyner and William Stein: initial version multi_polynomial_ring
    … … inv_singular_name_mapping ={'lp':'lex'  
    242244
    243245
    244246class TermOrder(SageObject):
    245     """
    246     Implements term orderings for polydict bases polynomials and
    247     conversions to MAGMA, SINGULAR, and Macaulay2.
    248 
    249     EXAMPLES:
    250    
    251         sage: t = TermOrder('lex')
    252         sage: t
    253         Lexicographic term order
    254         sage: loads(dumps(t)) == t
    255         True
    256 
    257         We can construct block orderings directly as
    258 
    259         sage: TermOrder('degrevlex(3),neglex(2)')
    260         degrevlex(3),neglex(2) term order
    261 
    262         or by adding together the blocks:
    263 
    264         sage: t1 = TermOrder('degrevlex',3)
    265         sage: t2 = TermOrder('neglex',2)
    266         sage: t1 + t2
    267         degrevlex(3),neglex(2) term order
    268         sage: t2 + t1
    269         neglex(2),degrevlex(3) term order
    270 
    271     """
    272247    def __init__(self, name='lex', n = 0):
    273248        """
    274249        Construct a new term ordering object.
    275 
    276         See \code{term_order.py} for details which term orderings are
    277         supported in SAGE.
    278250
    279251        INPUT:
    280252            name -- name of the term ordering (default: lex)
    … … class TermOrder(SageObject): 
    282254
    283255        See the \code{sage.rings.polynomial.term_order} module for
    284256        help which names and orderings are available.
     257
     258        EXAMPLES:
     259
     260            sage: t = TermOrder('lex')
     261            sage: t
     262            Lexicographic term order
     263            sage: loads(dumps(t)) == t
     264            True
     265
     266            We can construct block orderings directly as
     267
     268            sage: TermOrder('degrevlex(3),neglex(2)')
     269            degrevlex(3),neglex(2) term order
     270
     271            or by adding together the blocks:
     272
     273            sage: t1 = TermOrder('degrevlex',3)
     274            sage: t2 = TermOrder('neglex',2)
     275            sage: t1 + t2
     276            degrevlex(3),neglex(2) term order
     277            sage: t2 + t1
     278            neglex(2),degrevlex(3) term order
    285279
    286280        NOTE: The optional $n$ parameter is not necessary if only
    287281        simple orderings like $deglex$ are constructed. However, it is
    … … class TermOrder(SageObject): 
    341335    def __getattr__(self,name):
    342336        """
    343337        Return the correct compare_tuples/greater_tuple function.
     338
     339        EXAMPLE:
     340            sage: TermOrder('lex').compare_tuples
     341            <bound method TermOrder.compare_tuples_lp of Lexicographic term order>
     342
     343            sage: TermOrder('deglex').compare_tuples
     344            <bound method TermOrder.compare_tuples_Dp of Degree lexicographic term order>
    344345        """
    345346        if name=='compare_tuples':
    346347            if len(self.blocks) == 1:
    … … class TermOrder(SageObject): 
    360361        Compares two exponent tuples with respect to the
    361362        lexicographical term order.
    362363
     364        INPUT:
     365            f -- exponent tuple
     366            g -- exponent tuple
     367
    363368        EXAMPLE:
    364369            sage: P.<x,y> = PolynomialRing(QQ,2,order='lex')
    365             sage: x > y^2
     370            sage: x > y^2 # indirect doctest
    366371            True
    367372            sage: x > 1
    368373            True
    … … class TermOrder(SageObject): 
    380385        Compares two exponent tuples with respect to the inversed
    381386        lexicographical term order.
    382387
     388        INPUT:
     389            f -- exponent tuple
     390            g -- exponent tuple
     391
    383392        EXAMPLE:
    384393            sage: P.<x,y> = PolynomialRing(ZZ,2,order='invlex')
    385394            sage: x > y^2
    … … class TermOrder(SageObject): 
    393402        """
    394403        Compares two exponent tuples with respect to the
    395404        degree lexicographical term order.
     405
     406        INPUT:
     407            f -- exponent tuple
     408            g -- exponent tuple
    396409
    397410        EXAMPLE:
    398411            sage: P.<x,y> = PolynomialRing(GF(127),2,order='deglex')
    … … class TermOrder(SageObject): 
    415428        Compares two exponent tuples with respect to the degree
    416429        reversed lexicographical term order.
    417430
     431        INPUT:
     432            f -- exponent tuple
     433            g -- exponent tuple
     434
    418435        EXAMPLE:
    419436            sage: P.<x,y> = PolynomialRing(GF(127),2,order='degrevlex')
    420437            sage: x > y^2
    … … class TermOrder(SageObject): 
    437454        Compares two exponent tuples with respect to the
    438455        negative lexicographical term order.
    439456
     457        INPUT:
     458            f -- exponent tuple
     459            g -- exponent tuple
     460
    440461        EXAMPLE:
    441462            sage: P.<x,y> = PolynomialRing(GF(2^8,'a'),2,order='neglex')
    442463            sage: x > y^2
    … … class TermOrder(SageObject): 
    451472        Compares two exponent tuples with respect to the
    452473        negative degree reverse lexicographical term order.
    453474
     475        INPUT:
     476            f -- exponent tuple
     477            g -- exponent tuple
     478
    454479        EXAMPLE:
    455480            sage: P.<x,y> = PolynomialRing(IntegerModRing(10), 2,order='negdegrevlex')
    456481            sage: x > y^2
    … … class TermOrder(SageObject): 
    464489        """
    465490        Compares two exponent tuples with respect to the
    466491        negative degree lexicographical term order.
     492
     493        INPUT:
     494            f -- exponent tuple
     495            g -- exponent tuple
     496
    467497        EXAMPLE:
    468498            sage: P.<x,y> = PolynomialRing(GF(2), 2,order='negdevlex')
    469499            sage: x > y^2
    … … class TermOrder(SageObject): 
    479509        """
    480510        Compares two exponent tuple with respec to the block ordering
    481511        as specified when constructing this element.
     512
     513        INPUT:
     514            f -- exponent tuple
     515            g -- exponent tuple
    482516        """
    483517        n = 0
    484518        for order,length in self.blocks:
    … … class TermOrder(SageObject): 
    495529
    496530        This method is called by the lm/lc/lt methods of \code{MPolynomial_polydict}.
    497531
     532        INPUT:
     533            f -- exponent tuple
     534            g -- exponent tuple
    498535        """
    499536        return f > g and f or g
    500537
    … … class TermOrder(SageObject): 
    503540        Returns the greater exponent tuple with respect to the
    504541        inversed lexicographical term order.
    505542
     543        INPUT:
     544            f -- exponent tuple
     545            g -- exponent tuple
     546
    506547        This method is called by the lm/lc/lt methods of \code{MPolynomial_polydict}.
    507 
    508548        """
    509549        return f.reversed() > g.reversed()   and f or g
    510550       
    … … class TermOrder(SageObject): 
    513553        Returns the greater exponent tuple with respect to the total
    514554        degree lexicographical term order.
    515555
     556        INPUT:
     557            f -- exponent tuple
     558            g -- exponent tuple
     559
    516560        This method is called by the lm/lc/lt methods of \code{MPolynomial_polydict}.
    517 
    518561        """
    519562        return (sum(f.nonzero_values(sort=False))>sum(g.nonzero_values(sort=False))
    520563                or (sum(f.nonzero_values(sort=False))==sum(g.nonzero_values(sort=False)) and f  > g )) and f or g
    … … class TermOrder(SageObject): 
    523566        """
    524567        Returns the greater exponent tuple with respect to the total
    525568        degree reversed lexicographical term order.
     569
     570        INPUT:
     571            f -- exponent tuple
     572            g -- exponent tuple
    526573
    527574        This method is called by the lm/lc/lt methods of \code{MPolynomial_polydict}.
    528575
    … … class TermOrder(SageObject): 
    534581        """
    535582        Returns the greater exponent tuple with respect to the
    536583        negative degree reverse lexicographical term order.
     584
     585        INPUT:
     586            f -- exponent tuple
     587            g -- exponent tuple
    537588
    538589        This method is called by the lm/lc/lt methods of \code{MPolynomial_polydict}.
    539590       
    … … class TermOrder(SageObject): 
    548599        Returns the greater exponent tuple with respect to the
    549600        negative degree lexicographical term order.
    550601
     602        INPUT:
     603            f -- exponent tuple
     604            g -- exponent tuple
     605
    551606        This method is called by the lm/lc/lt methods of \code{MPolynomial_polydict}.
    552607
    553608        """
    … … class TermOrder(SageObject): 
    560615        """
    561616        Returns the greater exponent tuple with respect to the
    562617        negative lexicographical term order.
     618
     619        INPUT:
     620            f -- exponent tuple
     621            g -- exponent tuple
    563622
    564623        This method is called by the lm/lc/lt methods of \code{MPolynomial_polydict}.
    565624
    … … class TermOrder(SageObject): 
    575634        as specified when constructing this element.
    576635
    577636        This method is called by the lm/lc/lt methods of \code{MPolynomial_polydict}.
     637
     638        INPUT:
     639            f -- exponent tuple
     640            g -- exponent tuple
    578641
    579642        EXAMPLE:
    580643            sage: P.<a,b,c,d,e,f>=PolynomialRing(ZZ,6, order='degrevlex(3),degrevlex(3)')