Ticket #8825: trac_8825-more-norm-doc.patch

File trac_8825-more-norm-doc.patch, 8.9 KB (added by mvngu, 12 years ago)

  • sage/matrix/matrix2.pyx 

    # HG changeset patch
# User Minh Van Nguyen <nguyenminh2@gmail.com>
# Date 1272656283 25200
# Node ID d18a4dd6434c5c08316149189094ca59d2b47983
# Parent  d2f2f1bd8c082a20c3b35a4625ca3942b420d205
#8825: improve documentation for function norm and cross reference various norm functions

diff --git a/sage/matrix/matrix2.pyx b/sage/matrix/matrix2.pyx
    a b  
    64526452       
    64536453       
    64546454        OUTPUT: RDF number
     6455
     6456        .. SEEALSO::
     6457
     6458            - :func:`sage.misc.functional.norm`
    64556459       
    64566460        EXAMPLES::
    64576461       

  • sage/misc/functional.py 

    diff --git a/sage/misc/functional.py b/sage/misc/functional.py
    a b  
    10591059    return x.ngens()
    10601060
    10611061def norm(x):
    1062     """
    1063     Returns the norm of x.
     1062    r"""
     1063    Returns the norm of ``x``.
    10641064
    1065     For matrices and vectors, this returns the L2-norm.
    1066     For complex numbers, it returns the field norm.
     1065    For matrices and vectors, this returns the L2-norm. The L2-norm of a
     1066    vector `\textbf{v} = (v_1, v_2, \dots, v_n)`, also called the Euclidean
     1067    norm, is defined as
     1068
     1069    .. MATH::
     1070
     1071        |\textbf{v}|
     1072        =
     1073        \sqrt{\sum_{i=1}^n |v_i|^2}
     1074
     1075    where `|v_i|` is the complex modulus of `v_i`. The Euclidean norm is often
     1076    used for determining the distance between two points in two- or
     1077    three-dimensional space.
     1078
     1079    For complex numbers, the function returns the field norm. If
     1080    `c = a + bi` is a complex number, then the norm of `c` is defined as the
     1081    product of `c` and its complex conjugate
     1082
     1083    .. MATH::
     1084
     1085        \text{norm}(c)
     1086        =
     1087        \text{norm}(a + bi)
     1088        =
     1089        c \cdot \overline{c}
     1090        =
     1091        a^2 + b^2.
     1092
     1093    The norm of a complex number is different from its absolute value.
     1094    The absolute value of a complex number is defined to be the square
     1095    root of its norm. A typical use of the complex norm is in the
     1096    integral domain `\ZZ[i]` of Gaussian integers, where the norm of
     1097    each Gaussian integer `c = a + bi` is defined as its complex norm.
     1098
     1099    .. SEEALSO::
     1100
     1101        - :meth:`sage.matrix.matrix2.Matrix.norm`
     1102
     1103        - :meth:`sage.modules.free_module_element.FreeModuleElement.norm`
     1104
     1105        - :meth:`sage.rings.complex_double.ComplexDoubleElement.norm`
     1106
     1107        - :meth:`sage.rings.complex_number.ComplexNumber.norm`
     1108
     1109        - :meth:`sage.symbolic.expression.Expression.norm`
    10671110       
    1068     EXAMPLES::
    1069    
    1070         sage: z = 1+2*I
    1071         sage: norm(z)
    1072         5
     1111    EXAMPLES:
     1112
     1113    The norm of vectors::
     1114
     1115        sage: z = 1 + 2*I
    10731116        sage: norm(vector([z]))
    10741117        sqrt(5)
     1118        sage: v = vector([-1,2,3])
     1119        sage: norm(v)
     1120        sqrt(14)
     1121        sage: _ = var("a b c d")
     1122        sage: v = vector([a, b, c, d])
     1123        sage: norm(v)
     1124        sqrt(abs(a)^2 + abs(b)^2 + abs(c)^2 + abs(d)^2)
     1125
     1126    The norm of matrices::
     1127
     1128        sage: z = 1 + 2*I
    10751129        sage: norm(matrix([[z]]))
    10761130        2.2360679775
     1131        sage: M = matrix(ZZ, [[1,2,4,3], [-1,0,3,-10]])
     1132        sage: norm(M)
     1133        10.6903311292
    10771134        sage: norm(CDF(z))
    10781135        5.0
    10791136        sage: norm(CC(z))
    10801137        5.00000000000000
     1138
     1139    The norm of complex numbers::
     1140
     1141        sage: z = 2 - 3*I
     1142        sage: norm(z)
     1143        13
     1144        sage: a = randint(-10^10, 100^10)
     1145        sage: b = randint(-10^10, 100^10)
     1146        sage: z = a + b*I
     1147        sage: bool(norm(z) == a^2 + b^2)
     1148        True
     1149
     1150    The complex norm of symbolic expressions::
     1151
     1152        sage: a, b, c = var("a, b, c")
     1153        sage: z = a + b*I
     1154        sage: bool(norm(z).simplify() == a^2 + b^2)
     1155        True
     1156        sage: norm(a + b).simplify()
     1157        a^2 + 2*a*b + b^2
     1158        sage: v = vector([a, b, c])
     1159        sage: bool(norm(v).simplify_full() == sqrt(a^2 + b^2 + c^2))
     1160        True
    10811161    """
    10821162    return x.norm()
    10831163

  • sage/modules/free_module_element.pyx 

    diff --git a/sage/modules/free_module_element.pyx b/sage/modules/free_module_element.pyx
    a b  
    748748        `\geq 1`, Infinity, or a symbolic expression. If `p=2` (default),
    749749        this is the usual Euclidean norm; if p=Infinity, this is the
    750750        maximum norm; if `p=1`, this is the taxicab (Manhattan) norm.
     751
     752        .. SEEALSO::
     753
     754            - :func:`sage.misc.functional.norm`
    751755       
    752756        EXAMPLES::
    753757       

  • sage/rings/complex_double.pyx 

    diff --git a/sage/rings/complex_double.pyx b/sage/rings/complex_double.pyx
    a b  
    11121112
    11131113    def abs(self):
    11141114        """
    1115         This function returns the magnitude of the complex number
    1116         `z`, `|z|`.
     1115        This function returns the magnitude `|z|` of the complex number
     1116        `z`.
     1117
     1118        .. SEEALSO::
     1119
     1120            - :meth:`norm`
    11171121       
    11181122        EXAMPLES::
    11191123       
    … …  
    11421146   
    11431147    def abs2(self):
    11441148        """
    1145         This function returns the squared magnitude of the complex number
    1146         `z`, `|z|^2`.
    1147        
     1149        This function returns the squared magnitude `|z|^2` of the complex
     1150        number `z`, otherwise known as the complex norm.
     1151
     1152        .. SEEALSO::
     1153
     1154            - :meth:`norm`
     1155
    11481156        EXAMPLES::
    11491157       
    11501158            sage: CDF(2,3).abs2()
    … …  
    11531161        return RealDoubleElement(gsl_complex_abs2(self._complex))
    11541162
    11551163    def norm(self):
    1156         """
    1157         This function returns the squared magnitude of the complex number
    1158         `z`, `|z|^2`.
     1164        r"""
     1165        This function returns the squared magnitude `|z|^2` of the complex
     1166        number `z`, otherwise known as the complex norm. If `c = a + bi`
     1167        is a complex number, then the norm of `c` is defined as the product of
     1168        `c` and its complex conjugate
     1169       
     1170        .. MATH::
     1171
     1172            \text{norm}(c)
     1173            =
     1174            \text{norm}(a + bi)
     1175            =
     1176            c \cdot \overline{c}
     1177            =
     1178            a^2 + b^2.
     1179
     1180        The norm of a complex number is different from its absolute value.
     1181        The absolute value of a complex number is defined to be the square
     1182        root of its norm. A typical use of the complex norm is in the
     1183        integral domain `\ZZ[i]` of Gaussian integers, where the norm of
     1184        each Gaussian integer `c = a + bi` is defined as its complex norm.
     1185
     1186        .. SEEALSO::
     1187
     1188            - :meth:`abs`
     1189
     1190            - :meth:`abs2`
     1191
     1192            - :func:`sage.misc.functional.norm`
     1193
     1194            - :meth:`sage.rings.complex_number.ComplexNumber.norm`
    11591195       
    11601196        EXAMPLES::
    11611197       

  • sage/rings/complex_number.pyx 

    diff --git a/sage/rings/complex_number.pyx b/sage/rings/complex_number.pyx
    a b  
    552552    def norm(self):
    553553        r"""
    554554        Returns the norm of this complex number. If `c = a + bi` is a
    555         complex number, then the norm of `c` is defined as
     555        complex number, then the norm of `c` is defined as the product of
     556        `c` and its complex conjugate
    556557       
    557558        .. MATH::
    558559
    559             \text{norm}(c) = \text{norm}(a + bi) = a^2 + b^2
     560            \text{norm}(c)
     561            =
     562            \text{norm}(a + bi)
     563            =
     564            c \cdot \overline{c}
     565            =
     566            a^2 + b^2.
    560567
    561568        The norm of a complex number is different from its absolute value.
    562569        The absolute value of a complex number is defined to be the square
    563570        root of its norm. A typical use of the complex norm is in the
    564571        integral domain `\ZZ[i]` of Gaussian integers, where the norm of
    565572        each Gaussian integer `c = a + bi` is defined as its complex norm.
     573
     574        .. SEEALSO::
     575
     576            - :func:`sage.misc.functional.norm`
     577
     578            - :meth:`sage.rings.complex_double.ComplexDoubleElement.norm`
    566579       
    567580        EXAMPLES:
    568581

  • sage/symbolic/expression.pyx 

    diff --git a/sage/symbolic/expression.pyx b/sage/symbolic/expression.pyx
    a b  
    45644564    def norm(self):
    45654565        r"""
    45664566        The complex norm of this symbolic expression, i.e.,
    4567         the expression times its complex conjugate.
     4567        the expression times its complex conjugate. If `c = a + bi` is a
     4568        complex number, then the norm of `c` is defined as the product of
     4569        `c` and its complex conjugate
     4570       
     4571        .. MATH::
     4572
     4573            \text{norm}(c)
     4574            =
     4575            \text{norm}(a + bi)
     4576            =
     4577            c \cdot \overline{c}
     4578            =
     4579            a^2 + b^2.
     4580
     4581        The norm of a complex number is different from its absolute value.
     4582        The absolute value of a complex number is defined to be the square
     4583        root of its norm. A typical use of the complex norm is in the
     4584        integral domain `\ZZ[i]` of Gaussian integers, where the norm of
     4585        each Gaussian integer `c = a + bi` is defined as its complex norm.
     4586
     4587        .. SEEALSO::
     4588
     4589            - :func:`sage.misc.functional.norm`
    45684590       
    45694591        EXAMPLES::
    45704592