Ticket #12688: trac_12688_span_documentation.patch

File trac_12688_span_documentation.patch, 4.7 KB (added by rbeezer, 10 years ago)
  • sage/modules/free_module.py

    # HG changeset patch
    # User Rob Beezer <beezer@ups.edu>
    # Date 1332134080 25200
    # Node ID 0279d28c5388bba201bb1bb605a9d28a79da3820
    # Parent  7bd45999bd04973c73b090e423fc8a8f2fedcb62
    12688: documentation for span constructor
    
    diff --git a/sage/modules/free_module.py b/sage/modules/free_module.py
    a b  
    436436###############################################################################
    437437
    438438def span(gens, base_ring=None, check=True, already_echelonized=False):
    439     """
    440     Return the `R`-span of gens (a list of vectors) where R =
    441     base_ring.
    442    
    443     EXAMPLES::
    444    
     439    r"""
     440    Return the span of the vectors in ``gens`` using scalars from ``base_ring``.
     441
     442    INPUTS:
     443
     444    - ``gens`` - a list of either vectors or lists of ring elements
     445      used to generate the span
     446
     447    - ``base_ring`` - default: ``None`` - a principal ideal domain
     448      for the ring of scalars
     449
     450    - ``check`` - default: ``True`` - passed to the ``span()`` method
     451      of the ambient module
     452
     453    - ``already_echelonized`` - default: ``False`` - set to ``True``
     454      if the vectors form the rows of a matrix in echelon form, in
     455      order to skip the computation of an echelonized basis for the
     456      span.
     457
     458    EXAMPLES:
     459
     460    The vectors in the list of generators can be given as
     461    lists, provided a base ring is specified and the elements of the list
     462    are in the ring (or the fraction field of the ring).  If the
     463    base ring is a field, the span is a vector space.  ::
     464
    445465        sage: V = span([[1,2,5], [2,2,2]], QQ); V
    446466        Vector space of degree 3 and dimension 2 over Rational Field
    447467        Basis matrix:
    448468        [ 1  0 -3]
    449469        [ 0  1  4]
     470
    450471        sage: span([V.gen(0)], QuadraticField(-7,'a'))
    451472        Vector space of degree 3 and dimension 1 over Number Field in a with defining polynomial x^2 + 7
    452473        Basis matrix:
    453474        [ 1  0 -3]
     475
    454476        sage: span([[1,2,3], [2,2,2], [1,2,5]], GF(2))
    455477        Vector space of degree 3 and dimension 1 over Finite Field of size 2
    456478        Basis matrix:
    457479        [1 0 1]
    458    
     480
     481    If the base ring is not a field, then a module is created.
     482    The entries of the vectors can lie outside the ring, if they
     483    are in the fraction field of the ring.  ::
     484
     485        sage: span([[1,2,5], [2,2,2]], ZZ)
     486        Free module of degree 3 and rank 2 over Integer Ring
     487        Echelon basis matrix:
     488        [ 1  0 -3]
     489        [ 0  2  8]
     490
     491        sage: span([[1,1,1], [1,1/2,1]], ZZ)
     492        Free module of degree 3 and rank 2 over Integer Ring
     493        Echelon basis matrix:
     494        [  1   0   1]
     495        [  0 1/2   0]
     496
     497        sage: R.<x> = QQ[]
     498        sage: M= span( [[x, x^2+1], [1/x, x^3]], R); M
     499        Free module of degree 2 and rank 2 over
     500        Univariate Polynomial Ring in x over Rational Field
     501        Echelon basis matrix:
     502        [          1/x           x^3]
     503        [            0 x^5 - x^2 - 1]
     504        sage: M.basis()[0][0].parent()
     505        Fraction Field of Univariate Polynomial Ring in x over Rational Field
     506
     507    A base ring can be inferred if the generators are given as a
     508    list of vectors. ::
     509
     510        sage: span([vector(QQ, [1,2,3]), vector(QQ, [4,5,6])])
     511        Vector space of degree 3 and dimension 2 over Rational Field
     512        Basis matrix:
     513        [ 1  0 -1]
     514        [ 0  1  2]
     515        sage: span([vector(QQ, [1,2,3]), vector(ZZ, [4,5,6])])
     516        Vector space of degree 3 and dimension 2 over Rational Field
     517        Basis matrix:
     518        [ 1  0 -1]
     519        [ 0  1  2]
     520        sage: span([vector(ZZ, [1,2,3]), vector(ZZ, [4,5,6])])
     521        Free module of degree 3 and rank 2 over Integer Ring
     522        Echelon basis matrix:
     523        [1 2 3]
     524        [0 3 6]
     525
    459526    TESTS::
    460    
     527
    461528        sage: span([[1,2,3], [2,2,2], [1,2/3,5]], ZZ)
    462529        Free module of degree 3 and rank 3 over Integer Ring
    463530        Echelon basis matrix:
     
    468535        Traceback (most recent call last):
    469536        ...
    470537        ValueError: The elements of gens (= [[1, 2, 3], [2, 2, 2], [1, 2, x]]) must be defined over base_ring (= Integer Ring) or its field of fractions.
    471    
     538
    472539    For backwards compatibility one can also give the base ring as the
    473     first argument::
    474    
     540    first argument::
     541
    475542        sage: span(QQ,[[1,2],[3,4]])
    476543        Vector space of degree 2 and dimension 2 over Rational Field
    477544        Basis matrix:
    478545        [1 0]
    479546        [0 1]
    480547
     548    The base ring must be a principal ideal domain (PID).  ::
     549
     550        sage: span([[1,2,3]], Integers(6))
     551        Traceback (most recent call last):
     552        ...
     553        TypeError: The base_ring (= Ring of integers modulo 6)
     554        must be a principal ideal domain.
     555       
    481556    Fix :trac:`5575`::
    482557   
    483558        sage: V = QQ^3