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

File trac_10683-vector-products-docs-v2.patch, 11.1 KB (added by rbeezer, 11 years ago)

Apply second

  • sage/modules/free_module_element.pyx

    # HG changeset patch
    # User Rob Beezer <beezer@ups.edu>
    # Date 1295909054 28800
    # Node ID 3aa276649760e86f6a86eee05ccaf059ade6a31b
    # Parent  f3faa10b1a2e873d62c661f5c2ec2459df98c8ab
    10683: vector products documentation
    
    diff -r f3faa10b1a2e -r 3aa276649760 sage/modules/free_module_element.pyx
    a b  
    10891089        return sum([x**2 for x in self.list()]).sqrt()
    10901090
    10911091    def norm(self, p=sage.rings.integer.Integer(2)):
    1092         """
    1093         Return the p-norm of this vector, where p can be a real number
    1094         `\geq 1`, Infinity, or a symbolic expression. If `p=2` (default),
    1095         this is the usual Euclidean norm; if p=Infinity, this is the
    1096         maximum norm; if `p=1`, this is the taxicab (Manhattan) norm.
    1097 
    1098         .. SEEALSO::
    1099 
    1100             - :func:`sage.misc.functional.norm`
    1101        
     1092        r"""
     1093        Return the `p`-norm of ``self``.
     1094
     1095        INPUT:
     1096
     1097        - ``p`` - defalt: 2 - ``p`` can be a real number greater than 1,
     1098          infinity (``oo`` or ``Infinity``), or a symbolic expression.
     1099
     1100            - `p=1`: the taxicab (Manhattan) norm
     1101            - `p=2`: the usual Euclidean norm (the default)
     1102            - `p=\infty`: the maximum entry (in absolute value)
     1103
     1104        .. note::
     1105
     1106            See also :func:`sage.misc.functional.norm`
     1107
    11021108        EXAMPLES::
    1103        
     1109
    11041110            sage: v = vector([1,2,-3])
    11051111            sage: v.norm(5)
    11061112            276^(1/5)
    1107        
    1108         The default is the usual Euclidean norm::
    1109        
    1110             sage: v.norm() 
     1113
     1114        The default is the usual Euclidean norm::
     1115
     1116            sage: v.norm()
    11111117            sqrt(14)
    11121118            sage: v.norm(2)
    11131119            sqrt(14)
    1114        
    1115         The infinity norm is the maximum size of any entry::
    1116        
     1120
     1121        The infinity norm is the maximum size (in absolute value)
     1122        of the entries.  ::
     1123
    11171124            sage: v.norm(Infinity)
    11181125            3
    1119        
    1120         Any real or symbolic value works::
    1121        
     1126            sage: v.norm(oo)
     1127            3
     1128
     1129        Real or symbolic values may be used for ``p``.  ::
     1130
    11221131            sage: v=vector(RDF,[1,2,3])
    11231132            sage: v.norm(5)
    11241133            3.07738488539
     
    11271136            sage: _=var('a b c d p'); v=vector([a, b, c, d])
    11281137            sage: v.norm(p)
    11291138            (abs(a)^p + abs(b)^p + abs(c)^p + abs(d)^p)^(1/p)
     1139
     1140        Notice that the result may be a symbolic expression, owing to
     1141        the necessity of taking a square root (in the default case).
     1142        These results can be converted to numerical values if needed. ::
     1143
     1144            sage: v = vector(ZZ, [3,4])
     1145            sage: nrm = v.norm(); nrm
     1146            5
     1147            sage: nrm.parent()
     1148            Rational Field
     1149
     1150            sage: v = vector(QQ, [3, 5])
     1151            sage: nrm = v.norm(); nrm
     1152            sqrt(34)
     1153            sage: nrm.parent()
     1154            Symbolic Ring
     1155            sage: numeric = N(nrm); numeric
     1156            5.83095189484...
     1157            sage: numeric.parent()
     1158            Real Field with 53 bits of precision
     1159
     1160        TESTS:
     1161
     1162        The value of ``p`` must be greater than, or
     1163        equal to, one. ::
     1164
     1165            sage: v = vector(QQ, [1,2])
     1166            sage: v.norm(0.99)
     1167            Traceback (most recent call last):
     1168            ...
     1169            ValueError: 0.990000 is not greater than or equal to 1
    11301170        """
    11311171        abs_self = [abs(x) for x in self]
    11321172        if p == Infinity:
     
    16681708            return points(v, **kwds)
    16691709
    16701710    def dot_product(self, right):
    1671         """
    1672         Return the dot product of self and right, which is the sum of the
     1711        r"""
     1712        Return the dot product of ``self`` and ``right``, which is the sum of the
    16731713        product of the corresponding entries.
    1674        
     1714
    16751715        INPUT:
    1676        
    1677        
    1678         -  ``right`` - vector of the same degree as self. It
    1679            need not be in the same vector space as self, as long as the
    1680            coefficients can be multiplied.
    1681        
    1682        
     1716
     1717        - ``right`` - a vector of the same degree as ``self``.
     1718          It does not need to belong to the same parent as ``self``,
     1719          so long as the necessary products and sums are defined.
     1720
     1721        OUTPUT:
     1722
     1723        If ``self`` and ``right`` are the vectors `\vec{x}` and `\vec{y}`,
     1724        of degree `n`, then this method returns
     1725
     1726        .. math::
     1727
     1728            \sum_{i=1}^{n}x_iy_i
     1729
     1730        .. note::
     1731
     1732            The :meth:`inner_product` is a more general version of
     1733            this method, and the :meth:`hermitian_inner_product`
     1734            method may be more appropriate if your vectors
     1735            have complex entries.
     1736
    16831737        EXAMPLES::
    1684        
     1738
    16851739            sage: V = FreeModule(ZZ, 3)
    16861740            sage: v = V([1,2,3])
    16871741            sage: w = V([4,5,6])
    16881742            sage: v.dot_product(w)
    16891743            32
    1690        
    1691         ::
    1692        
    1693             sage: W = VectorSpace(GF(3),3)
    1694             sage: w = W([0,1,2])
    1695             sage: w.dot_product(v)
     1744
     1745        The vectors may be from different vector spaces,
     1746        provided the necessary operations make sense.
     1747        Notice that coercion will generate a result of
     1748        the same type, even if the order of the
     1749        arguments is reversed.::
     1750
     1751            sage: v = vector(ZZ, [1,2,3])
     1752            sage: w = vector(FiniteField(3), [0,1,2])
     1753            sage: ip = w.dot_product(v); ip
    16961754            2
    1697             sage: w.dot_product(v).parent()
     1755            sage: ip.parent()
    16981756            Finite Field of size 3
    1699        
    1700         Implicit coercion is well defined (regardless of order), so we
    1701         get 2 even if we do the dot product in the other order.
    1702        
    1703         ::
    1704        
    1705             sage: v.dot_product(w) 
     1757
     1758            sage: ip = v.dot_product(w); ip
    17061759            2
     1760            sage: ip.parent()
     1761            Finite Field of size 3
     1762
     1763        The dot product of a vector with itself is the 2-norm, squared. ::
     1764
     1765            sage: v = vector(QQ, [3, 4, 7])
     1766            sage: v.dot_product(v) - v.norm()^2
     1767            0
     1768
     1769        TESTS:
     1770
     1771        The second argument must be a free module element. ::
     1772
     1773            sage: v = vector(QQ, [1,2])
     1774            sage: v.dot_product('junk')
     1775            Traceback (most recent call last):
     1776            ...
     1777            TypeError: right must be a free module element
     1778
     1779        The degrees of the arguments must match. ::
     1780
     1781            sage: v = vector(QQ, [1,2])
     1782            sage: w = vector(QQ, [1,2,3])
     1783            sage: v.dot_product(w)
     1784            Traceback (most recent call last):
     1785            ...
     1786            ArithmeticError: degrees (2 and 3) must be the same
    17071787        """
    17081788        if not PY_TYPE_CHECK(right, FreeModuleElement):
    17091789            raise TypeError, "right must be a free module element"
     
    21002180        return V(vector(R, degree, entries))
    21012181
    21022182    def inner_product(self, right):
    2103         """
    2104         Returns the inner product of self and other, with respect to the
    2105         inner product defined on the parent of self.
    2106        
     2183        r"""
     2184        Returns the inner product of ``self`` and ``right``,
     2185        possibly using an inner product matrix from the parent of ``self``.
     2186
     2187        INPUT:
     2188
     2189        - ``right`` - a vector of the same degree as ``self``
     2190
     2191        OUTPUT:
     2192
     2193        If the parent vector space does not have an inner product
     2194        matrix defined, then this is the usual dot product
     2195        (:meth:`dot_product`).  If ``self`` and ``right`` are
     2196        considered as single column matrices, `\vec{x}` and `\vec{y}`,
     2197        and `A` is the inner product matrix, then this method computes
     2198
     2199        .. math::
     2200
     2201            \left(\vec{x}\right)^tA\vec{y}
     2202
     2203        where `t` indicates the transpose.
     2204
     2205        .. note::
     2206
     2207            If your vectors have complex entries, the
     2208            :meth:`hermitian_inner_product` may be more
     2209            appropriate for your purposes.
     2210
    21072211        EXAMPLES::
    2108        
    2109             sage: I = matrix(ZZ,3,[2,0,-1,0,2,0,-1,0,6])
    2110             sage: M = FreeModule(ZZ, 3, inner_product_matrix = I)
    2111             sage: (M.0).inner_product(M.0)
     2212
     2213            sage: v = vector(QQ, [1,2,3])
     2214            sage: w = vector(QQ, [-1,2,-3])
     2215            sage: v.inner_product(w)
     2216            -6
     2217            sage: v.inner_product(w) == v.dot_product(w)
     2218            True
     2219
     2220        The vector space or free module that is the parent to
     2221        ``self`` can have an inner product matrix defined, which
     2222        will be used by this method.  This matrix will be passed
     2223        through to subspaces. ::
     2224
     2225            sage: ipm = matrix(ZZ,[[2,0,-1], [0,2,0], [-1,0,6]])
     2226            sage: M = FreeModule(ZZ, 3, inner_product_matrix = ipm)
     2227            sage: v = M([1,0,0])
     2228            sage: v.inner_product(v)
    21122229            2
    21132230            sage: K = M.span_of_basis([[0/2,-1/2,-1/2], [0,1/2,-1/2],[2,0,0]])
    21142231            sage: (K.0).inner_product(K.0)
    21152232            2
     2233            sage: w = M([1,3,-1])
     2234            sage: v = M([2,-4,5])
     2235            sage: w.row()*ipm*v.column() == w.inner_product(v)
     2236            True
     2237
     2238        Note that the inner product matrix comes from the parent of ``self``.
     2239        So if a vector is not an element of the correct parent, the result
     2240        could be a source of confusion.  ::
     2241
     2242            sage: V = VectorSpace(QQ, 2, inner_product_matrix=[[1,2],[2,1]])
     2243            sage: v = V([12, -10])
     2244            sage: w = vector(QQ, [10,12])
     2245            sage: v.inner_product(w)
     2246            88
     2247            sage: w.inner_product(v)
     2248            0
     2249            sage: w = V(w)
     2250            sage: w.inner_product(v)
     2251            88
     2252
     2253        .. note::
     2254
     2255            The use of an inner product matrix makes no restrictions on
     2256            the nature of the matrix.  In particular, in this context it
     2257            need not be Hermitian and positive-definite (as it is in the
     2258            example above).
     2259
     2260        TESTS:
     2261
     2262        Most error handling occurs in the :meth:`dot_product` method.
     2263        But with an inner product defined, this method will check
     2264        that the input is a vector or free module element. ::
     2265
     2266            sage: W = VectorSpace(RDF, 2, inner_product_matrix = matrix(RDF, 2, [1.0,2.0,3.0,4.0]))
     2267            sage: v = W([2.0, 4.0])
     2268            sage: v.inner_product(5)
     2269            Traceback (most recent call last):
     2270            ...
     2271            TypeError: right must be a free module element
    21162272        """
    21172273        if self.parent().is_ambient() and self.parent()._inner_product_is_dot_product():
    21182274            return self.dot_product(right)
     
    21482304
    21492305        where the bar indicates complex conjugation.
    21502306
    2151         ..note::
     2307        .. note::
    21522308
    21532309            If your vectors do not contain complex entries, then
    21542310            :meth:`dot_product` will return the same result without
     
    21562312
    21572313            If you are not computing a weighted inner product, and
    21582314            your vectors do not have complex entries, then the
    2159             :meth:`dot_product` should return the same result.
     2315            :meth:`dot_product` will return the same result.
    21602316
    21612317        EXAMPLES::
    21622318