Ticket #10500: trac_10500-documentation-linear-combinations.patch

File trac_10500-documentation-linear-combinations.patch, 6.6 KB (added by rbeezer, 10 years ago)
  • sage/matrix/matrix0.pyx

    # HG changeset patch
    # User Rob Beezer <beezer@ups.edu>
    # Date 1292817982 28800
    # Node ID 6568dc90fe877c2fa2f0d490b83139bf72314c38
    # Parent  185b6d732d7e03e2374544dcb69d1eea83ddb352
    10500: documentation improvments, matrix row/column linear combinations
    
    diff -r 185b6d732d7e -r 6568dc90fe87 sage/matrix/matrix0.pyx
    a b  
    26562656    # Matrix-vector multiply
    26572657    ###################################################
    26582658    def linear_combination_of_rows(self, v):
    2659         """
    2660         Return the linear combination of the rows of self given by the
    2661         coefficients in the list v.  Raise a ValueError if the length
    2662         of v is longer than the number of rows of the matrix.
    2663        
     2659        r"""
     2660        Return the linear combination of the rows of ``self`` given by the
     2661        coefficients in the list ``v``.
     2662
    26642663        INPUT:
    2665        
    2666        
    2667         -  ``v`` - list of length at most the number of rows of
    2668                    self (less is fine)
    2669        
    2670        
     2664
     2665        -  ``v`` -  a list of scalars.  The length can be less than
     2666           the number of rows of ``self`` but not greater.
     2667
     2668        OUTPUT:
     2669
     2670        The vector (or free module element) that is a linear
     2671        combination of the rows of ``self``. If the list of
     2672        scalars has fewer entries than the number of rows,
     2673        additional zeros are appended to the list until it
     2674        has as many entries as the number of rows.
     2675
    26712676        EXAMPLES::
    2672        
     2677
    26732678            sage: a = matrix(ZZ,2,3,range(6)); a
    26742679            [0 1 2]
    26752680            [3 4 5]
    26762681            sage: a.linear_combination_of_rows([1,2])
    26772682            (6, 9, 12)
     2683
    26782684            sage: a.linear_combination_of_rows([0,0])
    26792685            (0, 0, 0)
     2686
    26802687            sage: a.linear_combination_of_rows([1/2,2/3])
    26812688            (2, 19/6, 13/3)
     2689
     2690        The list ``v`` can be anything that is iterable.  Perhaps most
     2691        naturally, a vector may be used. ::
     2692
     2693            sage: v = vector(ZZ, [1,2])
     2694            sage: a.linear_combination_of_rows(v)
     2695            (6, 9, 12)
     2696
     2697        We check that a matrix with no rows behaves properly. ::
     2698
    26822699            sage: matrix(QQ,0,2).linear_combination_of_rows([])
    26832700            (0, 0)
    2684            
     2701
     2702        The object returned is a vector, or a free module element. ::
     2703
     2704            sage: B = matrix(ZZ, 4, 3, range(12))
     2705            sage: w = B.linear_combination_of_rows([-1,2,-3,4])
     2706            sage: w
     2707            (24, 26, 28)
     2708            sage: w.parent()
     2709            Ambient free module of rank 3 over the principal ideal domain Integer Ring
     2710            sage: x = B.linear_combination_of_rows([1/2,1/3,1/4,1/5])
     2711            sage: x
     2712            (43/10, 67/12, 103/15)
     2713            sage: x.parent()
     2714            Vector space of dimension 3 over Rational Field
     2715
    26852716        The length of v can be less than the number of rows, but not
    2686         more than the number of rows::
    2687        
    2688             sage: A = matrix(QQ,2,3)
    2689             sage: A.linear_combination_of_rows([0])
    2690             (0, 0, 0)
    2691             sage: A.linear_combination_of_rows([1,2,3])
     2717        greater. ::
     2718
     2719            sage: A = matrix(QQ,3,4,range(12))
     2720            sage: A.linear_combination_of_rows([2,3])
     2721            (12, 17, 22, 27)
     2722            sage: A.linear_combination_of_rows([1,2,3,4])
    26922723            Traceback (most recent call last):
    26932724            ...
    26942725            ValueError: length of v must be at most the number of rows of self
     
    27022733        return (v * self)[0]
    27032734
    27042735    def linear_combination_of_columns(self, v):
    2705         """
    2706         Return the linear combination of the columns of self given by
    2707         the coefficients in the list v.  Raise a ValueError if the
    2708         length of v is longer than the number of columns of the
    2709         matrix.
    2710        
     2736        r"""
     2737        Return the linear combination of the columns of ``self`` given by the
     2738        coefficients in the list ``v``.
     2739
    27112740        INPUT:
    2712        
    2713        
    2714         -  ``v`` - list of length at most the number of columns of self (less is fine)
    2715        
    2716        
     2741
     2742        -  ``v`` -  a list of scalars.  The length can be less than
     2743           the number of columns of ``self`` but not greater.
     2744
     2745        OUTPUT:
     2746
     2747        The vector (or free module element) that is a linear
     2748        combination of the columns of ``self``. If the list of
     2749        scalars has fewer entries than the number of columns,
     2750        additional zeros are appended to the list until it
     2751        has as many entries as the number of columns.
     2752
    27172753        EXAMPLES::
    2718        
     2754
    27192755            sage: a = matrix(ZZ,2,3,range(6)); a
    27202756            [0 1 2]
    27212757            [3 4 5]
    27222758            sage: a.linear_combination_of_columns([1,1,1])
    27232759            (3, 12)
     2760
    27242761            sage: a.linear_combination_of_columns([0,0,0])
    27252762            (0, 0)
     2763
    27262764            sage: a.linear_combination_of_columns([1/2,2/3,3/4])
    2727              (13/6, 95/12)
     2765            (13/6, 95/12)
     2766
     2767        The list ``v`` can be anything that is iterable.  Perhaps most
     2768        naturally, a vector may be used. ::
     2769
     2770            sage: v = vector(ZZ, [1,2,3])
     2771            sage: a.linear_combination_of_columns(v)
     2772            (8, 26)
     2773
     2774        We check that a matrix with no columns behaves properly. ::
     2775
    27282776            sage: matrix(QQ,2,0).linear_combination_of_columns([])
    27292777            (0, 0)
    27302778
     2779        The object returned is a vector, or a free module element. ::
     2780
     2781            sage: B = matrix(ZZ, 4, 3, range(12))
     2782            sage: w = B.linear_combination_of_columns([-1,2,-3])
     2783            sage: w
     2784            (-4, -10, -16, -22)
     2785            sage: w.parent()
     2786            Ambient free module of rank 4 over the principal ideal domain Integer Ring
     2787            sage: x = B.linear_combination_of_columns([1/2,1/3,1/4])
     2788            sage: x
     2789            (5/6, 49/12, 22/3, 127/12)
     2790            sage: x.parent()
     2791            Vector space of dimension 4 over Rational Field
     2792
    27312793        The length of v can be less than the number of columns, but not
    2732         more than the number of columns::
    2733        
    2734             sage: A = matrix(QQ,2,3)
    2735             sage: A.linear_combination_of_columns([0])
    2736             (0, 0)
    2737             sage: A.linear_combination_of_columns([1,2,3,4])
     2794        greater. ::
     2795
     2796            sage: A = matrix(QQ,3,5, range(15))
     2797            sage: A.linear_combination_of_columns([1,-2,3,-4])
     2798            (-8, -18, -28)
     2799            sage: A.linear_combination_of_columns([1,2,3,4,5,6])
    27382800            Traceback (most recent call last):
    27392801            ...
    27402802            ValueError: length of v must be at most the number of columns of self