Ticket #10683: trac_10683-vector-products-docs.patch

File trac_10683-vector-products-docs.patch, 11.6 KB (added by rbeezer, 10 years ago)
  • sage/modules/free_module_element.pyx

    # HG changeset patch
    # User Rob Beezer <beezer@ups.edu>
    # Date 1295909054 28800
    # Node ID 3c5fd8875a2ca803ec67f1f054c20ee0f538c977
    # Parent  dbb2857a526eef8158a3cd04a6872b753250f3d2
    10683: vector products documentation
    
    diff -r dbb2857a526e -r 3c5fd8875a2c sage/modules/free_module_element.pyx
    a b  
    10801080        return sum([x**2 for x in self.list()]).sqrt()
    10811081
    10821082    def norm(self, p=sage.rings.integer.Integer(2)):
    1083         """
    1084         Return the p-norm of this vector, where p can be a real number
    1085         `\geq 1`, Infinity, or a symbolic expression. If `p=2` (default),
    1086         this is the usual Euclidean norm; if p=Infinity, this is the
    1087         maximum norm; if `p=1`, this is the taxicab (Manhattan) norm.
    1088 
    1089         .. SEEALSO::
    1090 
    1091             - :func:`sage.misc.functional.norm`
    1092        
     1083        r"""
     1084        Return the `p`-norm of ``self``.
     1085
     1086        INPUT:
     1087
     1088        - ``p`` - defalt: 2 - ``p`` can be a real number greater than 1,
     1089          infinity (``oo`` or ``Infinity``), or a symbolic expression.
     1090
     1091            - `p=1`: the taxicab (Manhattan) norm
     1092            - `p=2`: the usual Euclidean norm (the default)
     1093            - `p=\infty`: the maximum entry (in absolute value)
     1094
     1095        .. note::
     1096
     1097            See also :func:`sage.misc.functional.norm`
     1098
    10931099        EXAMPLES::
    1094        
     1100
    10951101            sage: v = vector([1,2,-3])
    10961102            sage: v.norm(5)
    10971103            276^(1/5)
    1098        
    1099         The default is the usual Euclidean norm::
    1100        
    1101             sage: v.norm() 
     1104
     1105        The default is the usual Euclidean norm::
     1106
     1107            sage: v.norm()
    11021108            sqrt(14)
    11031109            sage: v.norm(2)
    11041110            sqrt(14)
    1105        
    1106         The infinity norm is the maximum size of any entry::
    1107        
     1111
     1112        The infinity norm is the maximum size (in absolute value)
     1113        of the entries.  ::
     1114
    11081115            sage: v.norm(Infinity)
    11091116            3
    1110        
    1111         Any real or symbolic value works::
    1112        
     1117            sage: v.norm(oo)
     1118            3
     1119
     1120        Real or symbolic values may be used for ``p``.  ::
     1121
    11131122            sage: v=vector(RDF,[1,2,3])
    11141123            sage: v.norm(5)
    11151124            3.07738488539
     
    11181127            sage: _=var('a b c d p'); v=vector([a, b, c, d])
    11191128            sage: v.norm(p)
    11201129            (abs(a)^p + abs(b)^p + abs(c)^p + abs(d)^p)^(1/p)
     1130
     1131        Notice that the result may be a symbolic expression, owing to
     1132        the necessity of taking a square root (in the default case).
     1133        These results can be converted to numerical values if needed. ::
     1134
     1135            sage: v = vector(ZZ, [3,4])
     1136            sage: nrm = v.norm(); nrm
     1137            5
     1138            sage: nrm.parent()
     1139            Rational Field
     1140
     1141            sage: v = vector(QQ, [3, 5])
     1142            sage: nrm = v.norm(); nrm
     1143            sqrt(34)
     1144            sage: nrm.parent()
     1145            Symbolic Ring
     1146            sage: numeric = N(nrm); numeric
     1147            5.83095189484...
     1148            sage: numeric.parent()
     1149            Real Field with 53 bits of precision
     1150
     1151        TESTS:
     1152
     1153        The value of ``p`` must be greater than, or
     1154        equal to, one. ::
     1155
     1156            sage: v = vector(QQ, [1,2])
     1157            sage: v.norm(0.99)
     1158            Traceback (most recent call last):
     1159            ...
     1160            ValueError: 0.990000 is not greater than or equal to 1
    11211161        """
    11221162        abs_self = [abs(x) for x in self]
    11231163        if p == Infinity:
     
    16591699            return points(v, **kwds)
    16601700
    16611701    def dot_product(self, right):
    1662         """
    1663         Return the dot product of self and right, which is the sum of the
     1702        r"""
     1703        Return the dot product of ``self`` and ``right``, which is the sum of the
    16641704        product of the corresponding entries.
    1665        
     1705
    16661706        INPUT:
    1667        
    1668        
    1669         -  ``right`` - vector of the same degree as self. It
    1670            need not be in the same vector space as self, as long as the
    1671            coefficients can be multiplied.
    1672        
    1673        
     1707
     1708        - ``right`` - a vector of the same degree as ``self``.
     1709          It does not need to belong to the same parent as ``self``,
     1710          so long as the necessary products and sums are defined.
     1711
     1712        OUTPUT:
     1713
     1714        If ``self`` and ``right`` are the vectors `\vec{x}` and `\vec{y}`,
     1715        of degree `n`, then this method returns
     1716
     1717        .. math::
     1718
     1719            \sum_{i=1}^{n}x_iy_i
     1720
     1721        .. note::
     1722
     1723            The :meth:`inner_product` is a more general version of
     1724            this method, and the :meth:`hermitian_inner_product`
     1725            method may be more appropriate if your vectors
     1726            have complex entries.
     1727
    16741728        EXAMPLES::
    1675        
     1729
    16761730            sage: V = FreeModule(ZZ, 3)
    16771731            sage: v = V([1,2,3])
    16781732            sage: w = V([4,5,6])
    16791733            sage: v.dot_product(w)
    16801734            32
    1681        
    1682         ::
    1683        
    1684             sage: W = VectorSpace(GF(3),3)
    1685             sage: w = W([0,1,2])
    1686             sage: w.dot_product(v)
     1735
     1736        The vectors may be from different vector spaces,
     1737        provided the necessary operations make sense.
     1738        Notice that coercion will generate a result of
     1739        the same type, even if the order of the
     1740        arguments is reversed.::
     1741
     1742            sage: v = vector(ZZ, [1,2,3])
     1743            sage: w = vector(FiniteField(3), [0,1,2])
     1744            sage: ip = w.dot_product(v); ip
    16871745            2
    1688             sage: w.dot_product(v).parent()
     1746            sage: ip.parent()
    16891747            Finite Field of size 3
    1690        
    1691         Implicit coercion is well defined (regardless of order), so we
    1692         get 2 even if we do the dot product in the other order.
    1693        
    1694         ::
    1695        
    1696             sage: v.dot_product(w) 
     1748
     1749            sage: ip = v.dot_product(w); ip
    16971750            2
     1751            sage: ip.parent()
     1752            Finite Field of size 3
     1753
     1754        The dot product of a vector with itself is the 2-norm, squared. ::
     1755
     1756            sage: v = vector(QQ, [3, 4, 7])
     1757            sage: v.dot_product(v) - v.norm()^2
     1758            0
     1759
     1760        TESTS:
     1761
     1762        The second argument must be a free module element. ::
     1763
     1764            sage: v = vector(QQ, [1,2])
     1765            sage: v.dot_product('junk')
     1766            Traceback (most recent call last):
     1767            ...
     1768            TypeError: right must be a free module element
     1769
     1770        The degrees of the arguments must match. ::
     1771
     1772            sage: v = vector(QQ, [1,2])
     1773            sage: w = vector(QQ, [1,2,3])
     1774            sage: v.dot_product(w)
     1775            Traceback (most recent call last):
     1776            ...
     1777            ArithmeticError: degrees (2 and 3) must be the same
    16981778        """
    16991779        if not PY_TYPE_CHECK(right, FreeModuleElement):
    17001780            raise TypeError, "right must be a free module element"
     
    20912171        return V(vector(R, degree, entries))
    20922172
    20932173    def inner_product(self, right):
    2094         """
    2095         Returns the inner product of self and other, with respect to the
    2096         inner product defined on the parent of self.
    2097        
     2174        r"""
     2175        Returns the inner product of ``self`` and ``right``,
     2176        possibly using an inner product matrix from the parent of ``self``.
     2177
     2178        INPUT:
     2179
     2180        - ``right`` - a vector of the same degree as ``self``
     2181
     2182        OUTPUT:
     2183
     2184        If the parent vector space does not have an inner product
     2185        matrix defined, then this is the usual dot product
     2186        (:meth:`dot_product`).  If ``self`` and ``right`` are
     2187        considered as single column matrices, `\vec{x}` and `\vec{y}`,
     2188        and `A` is the inner product matrix, then this method computes
     2189
     2190        .. math::
     2191
     2192            \left(\vec{x}\right)^tA\vec{y}
     2193
     2194        where `t` indicates the transpose.
     2195
     2196        .. note::
     2197
     2198            If your vectors have complex entries, the
     2199            :meth:`hermitian_inner_product` may be more
     2200            appropriate for your purposes.
     2201
    20982202        EXAMPLES::
    2099        
    2100             sage: I = matrix(ZZ,3,[2,0,-1,0,2,0,-1,0,6])
    2101             sage: M = FreeModule(ZZ, 3, inner_product_matrix = I)
    2102             sage: (M.0).inner_product(M.0)
     2203
     2204            sage: v = vector(QQ, [1,2,3])
     2205            sage: w = vector(QQ, [-1,2,-3])
     2206            sage: v.inner_product(w)
     2207            -6
     2208            sage: v.inner_product(w) == v.dot_product(w)
     2209            True
     2210
     2211        The vector space or free module that is the parent to
     2212        ``self`` can have an inner product matrix defined, which
     2213        will be used by this method.  This matrix will be passed
     2214        through to subspaces. ::
     2215
     2216            sage: ipm = matrix(ZZ,[[2,0,-1], [0,2,0], [-1,0,6]])
     2217            sage: M = FreeModule(ZZ, 3, inner_product_matrix = ipm)
     2218            sage: v = M([1,0,0])
     2219            sage: v.inner_product(v)
    21032220            2
    21042221            sage: K = M.span_of_basis([[0/2,-1/2,-1/2], [0,1/2,-1/2],[2,0,0]])
    21052222            sage: (K.0).inner_product(K.0)
    21062223            2
     2224            sage: w = M([1,3,-1])
     2225            sage: v = M([2,-4,5])
     2226            sage: w.row()*ipm*v.column() == w.inner_product(v)
     2227            True
     2228
     2229        Note that the inner product matrix comes from the parent of ``self``.
     2230        So if a vector is not an element of the correct parent, the result
     2231        could be a source of confusion.  ::
     2232
     2233            sage: V = VectorSpace(QQ, 2, inner_product_matrix=[[1,2],[2,1]])
     2234            sage: v = V([12, -10])
     2235            sage: w = vector(QQ, [10,12])
     2236            sage: v.inner_product(w)
     2237            88
     2238            sage: w.inner_product(v)
     2239            0
     2240            sage: w = V(w)
     2241            sage: w.inner_product(v)
     2242            88
     2243
     2244        .. note::
     2245
     2246            The use of an inner product matrix makes no restrictions on
     2247            the nature of the matrix.  In particular, in this context it
     2248            need not be symmetric and positive-definite.
     2249
     2250        TESTS:
     2251
     2252        Most error handling occurs in the :meth:`dot_product` method.
     2253        But with an inner product defined, this method will check
     2254        that the input is a vector or free module element. ::
     2255
     2256            sage: W = VectorSpace(RDF, 2, inner_product_matrix = matrix(RDF, 2, [1.0,2.0,3.0,4.0]))
     2257            sage: v = W([2.0, 4.0])
     2258            sage: v.inner_product(5)
     2259            Traceback (most recent call last):
     2260            ...
     2261            TypeError: right must be a free module element
     2262
    21072263        """
    21082264        if self.parent().is_ambient() and self.parent()._inner_product_is_dot_product():
    21092265            return self.dot_product(right)
     
    21382294
    21392295        where the bar indicates complex conjugation.
    21402296
    2141         ..note::
     2297        .. note::
    21422298
    21432299            If your vectors do not contain complex entries, then
    21442300            :meth:`inner_product` will return the same result without
     
    21462302
    21472303            If you are not computing a weighted inner product, and
    21482304            your vectors do not have complex entries, then the
    2149             :meth:`dot_product` should return the same result.
     2305            :meth:`dot_product` will return the same result.
    21502306
    21512307        EXAMPLES::
    21522308
     
    22162372
    22172373            The use of an inner product matrix makes no restrictions on
    22182374            the nature of the matrix.  In particular, in this context it
    2219             need not be Hermitian and positive-definite (as in the
     2375            need not be Hermitian and positive-definite (as it is in the
    22202376            example above).
    22212377
    22222378        TESTS:
     
    22332389            ArithmeticError: degrees (1 and 2) must be the same
    22342390        """
    22352391        return (self.conjugate()).inner_product(right)
    2236        
     2392
    22372393    def is_dense(self):
    22382394        """
    22392395        Return True if this is a dense vector, which is just a