Ticket #13962: trac_13962_polybori_docs.patch

File trac_13962_polybori_docs.patch, 5.4 KB (added by malb, 9 years ago)
  • sage/rings/polynomial/pbori.pyx

    # HG changeset patch
    # User Martin Albrecht <martinralbrecht@googlemail.com>
    # Date 1358436348 0
    # Node ID 5a2675f83e8e09a76f6da6165b686206cc7f7d1e
    # Parent  42e8da06e2408995777f84375ce368c02b955614
    #13962 PolyBoRi docs improvement
    
    diff --git a/sage/rings/polynomial/pbori.pyx b/sage/rings/polynomial/pbori.pyx
    a b  
    1212areas. This implementation is a thin wrapper around the PolyBoRi
    1313library by Michael Brickenstein and Alexander Dreyer.
    1414
    15 "Boolean polynomials can be modelled in a rather simple way, with
    16 both coefficients and degree per variable lying in
    17 ``{0, 1}``. The ring of Boolean polynomials is, however,
    18 not a polynomial ring, but rather the quotient ring of the
    19 polynomial ring over the field with two elements modulo the field
    20 equations `x^2=x` for each variable `x`. Therefore,
    21 the usual polynomial data structures seem not to be appropriate for
    22 fast Groebner basis computations. We introduce a specialised data
    23 structure for Boolean polynomials based on zero-suppressed binary
    24 decision diagrams (ZDDs), which is capable of handling these
    25 polynomials more efficiently with respect to memory consumption and
    26 also computational speed. Furthermore, we concentrate on high-level
    27 algorithmic aspects, taking into account the new data structures as
    28 well as structural properties of Boolean polynomials." - [BD07]_
     15  Boolean polynomials can be modelled in a rather simple way, with
     16  both coefficients and degree per variable lying in ``{0, 1}``. The
     17  ring of Boolean polynomials is, however, not a polynomial ring, but
     18  rather the quotient ring of the polynomial ring over the field with
     19  two elements modulo the field equations `x^2=x` for each variable
     20  `x`. Therefore, the usual polynomial data structures seem not to be
     21  appropriate for fast Groebner basis computations. We introduce a
     22  specialised data structure for Boolean polynomials based on
     23  zero-suppressed binary decision diagrams (ZDDs), which is capable of
     24  handling these polynomials more efficiently with respect to memory
     25  consumption and also computational speed. Furthermore, we
     26  concentrate on high-level algorithmic aspects, taking into account
     27  the new data structures as well as structural properties of Boolean
     28  polynomials. - [BD07]_
    2929
    3030For details on the internal representation of polynomials see
    3131
    3232    http://polybori.sourceforge.net/zdd.html
    3333
    34 AUTHORS:
    35 
    36 - Michael Brickenstein: PolyBoRi author
    37 
    38 - Alexander Dreyer: PolyBoRi author
    39 
    40 - Burcin Erocal <burcin@erocal.org>: main Sage wrapper author
    41 
    42 - Martin Albrecht <malb@informatik.uni-bremen.de>: some
    43   contributions to the Sage wrapper
    44 
    45 - Simon King <simon.king@uni-jena.de>:
    46   Adopt the new coercion model. Fix conversion from univariate
    47   polynomial rings. Pickling of :class:`BooleanMonomialMonoid`
    48   (via :class:`~sage.structure.unique_representation.UniqueRepresentation`)
    49   and :class:`BooleanMonomial`.
    50 
    51 - Charles Bouillaguet <charles.bouillaguet@gmail.com>: minor changes
    52   to improve compatibility with MPolynomial and make the variety()
    53   function work on ideals of BooleanPolynomial's.
    54 
    55 
    56 EXAMPLES:
     34Example
     35-------
    5736
    5837Consider the ideal
    5938
     
    174153represented as tuples of tuples (Sage) or as ``BooleSet`` (PolyBoRi)
    175154and naturally the second option is faster.
    176155
     156Taking full advantage of PolyBoRi
     157---------------------------------
     158
     159PolyBoRi's data structures imply that the user should familiarise
     160herself to achieve optimal performance. The PolyBoRi tutorial on this
     161matter can be found at:
     162
     163  http://polybori.sourceforge.net/doc/tutorial/tutorialse2.html#x3-140002.1
     164
     165Authors and references
     166----------------------
     167
     168AUTHORS:
     169
     170- Michael Brickenstein: PolyBoRi author
     171
     172- Alexander Dreyer: PolyBoRi author
     173
     174- Burcin Erocal <burcin@erocal.org>: main Sage wrapper author
     175
     176- Martin Albrecht: some contributions to the Sage wrapper
     177
     178- Simon King <simon.king@uni-jena.de>:
     179  Adopt the new coercion model. Fix conversion from univariate
     180  polynomial rings. Pickling of :class:`BooleanMonomialMonoid`
     181  (via :class:`~sage.structure.unique_representation.UniqueRepresentation`)
     182  and :class:`BooleanMonomial`.
     183
     184- Charles Bouillaguet <charles.bouillaguet@gmail.com>: minor changes
     185  to improve compatibility with MPolynomial and make the variety()
     186  function work on ideals of BooleanPolynomial's.
     187
     188
    177189REFERENCES:
    178190
    179191.. [BD07] Michael Brickenstein, Alexander Dreyer\; *PolyBoRi: A
    180192  Groebner basis framework for Boolean polynomials*; pre-print
    181193  available at
    182194  http://www.itwm.fraunhofer.de/zentral/download/berichte/bericht122.pdf
     195
     196Classes
     197-------
    183198"""
    184199
    185200include "../../ext/interrupt.pxi"
     
    307322        True
    308323        sage: TestSuite(P).run()
    309324
    310     Boolean polynomial rings are unique parent structures. We
    311     thus have::
     325    Boolean polynomial rings are unique parent structures. We thus
     326    have::
    312327
    313328        sage: P.<x,y> = BooleanPolynomialRing(2)
    314329        sage: R.<x,y> = BooleanPolynomialRing(2)
    315330        sage: P is R
    316331        True
    317332
    318     ::
    319 
    320333        sage: Q.<x,z> = BooleanPolynomialRing(2)
    321334        sage: P == Q
    322335        False
    323336
    324     ::
    325 
    326337        sage: S.<x,y> = BooleanPolynomialRing(2, order='deglex')
    327338        sage: P == S
    328339        False
    329340
    330 
     341    .. note::
     342
     343        See documentation for :mod:`sage.rings.polynomial.pbring`
     344        for a highlevel description of PolyBoRi in Sage.
    331345    """
    332346    def __init__(self, n=None, names=None, order='lex'):
    333347        """