Ticket #10952: trac_10952-reviewer-docs-v2.patch

File trac_10952-reviewer-docs-v2.patch, 2.8 KB (added by rbeezer, 9 years ago)
  • doc/en/developer/conventions.rst

    # HG changeset patch
    # User Rob Beezer <beezer@ups.edu>
    # Date 1314169147 25200
    # Node ID d029c89a9755beeb4ad345dec78924825a1ad0a3
    # Parent  f32a34f366fbbd1b1942c4585bdd0c61e2fa0a4c
    10952: reviewer documentation additions
    
    diff --git a/doc/en/developer/conventions.rst b/doc/en/developer/conventions.rst
    a b  
    728728       0.0511114082399688
    729729
    730730-  If a line contains ``tol`` or ``tolerance, numerical results are only
    731    verified to the given tolerance. This may be prefixed by ``abs[olute``
     731   verified to the given tolerance. This may be prefixed by ``abs[olute]``
    732732   or ``rel[ative]`` to specify whether to measure absolute or relative
    733    error; defaults to relative error except when the expected value is
    734    exactly zero:
     733   error; this defaults to relative error except when the expected value
     734   is exactly zero:
    735735
    736736   ::
    737737
    738            sage: RDF(pi)                               # abs tol 1e-5
    739            3.14159
    740            sage: [10^n for n in [0.0 .. 4]]            # rel tol 2e-4
    741            [0.9999, 10.001, 100.01, 999.9, 10001]
     738       sage: RDF(pi)                               # abs tol 1e-5
     739       3.14159
     740       sage: [10^n for n in [0.0 .. 4]]            # rel tol 2e-4
     741       [0.9999, 10.001, 100.01, 999.9, 10001]
    742742
    743743   This can be useful when the exact output is subject to rounding error
    744    and/or processor floating point arithmetic variation.
     744   and/or processor floating point arithmetic variation.  Here are some
     745   more examples.
     746   
     747   A singular value decomposition of a matrix will produce two unitary
     748   matrices.  Over the reals, this means the inverse of the matrix is
     749   equal to its transpose.  We test this result by applying the norm to
     750   a matrix difference.  The result will usually be a "small" number,
     751   distinct from zero.
     752   
     753   ::
     754
     755       sage: A = matrix(RDF, 8, range(64))
     756       sage: U, S, V = A.SVD()
     757       sage: (U.transpose()*U-identity_matrix(8)).norm()    # abs tol 1e-10
     758       0.0
     759       
     760   The 8-th cyclotomic field is generated by the complex number
     761   `e^\frac{i\pi}{4}`.  Here we compute a numerical approximation.
     762   
     763   ::
     764       
     765       sage: K = CyclotomicField(8)                     
     766       sage: g = K.gen(0); g
     767       zeta8
     768       sage: N(zeta8)                             # absolute tolerance 1e-15
     769       0.707106781186548 + 0.707106781186547*I
     770
     771   A relative tolerance on a root of a polynomial.
     772   
     773   ::
     774
     775       sage: y = polygen(RDF, 'y')
     776       sage: p = (y - 10^16)*(y-10^(-13))*(y-2); p
     777       y^3 + (-1e+16)*y^2 + (2e+16)*y - 2000.0
     778       sage: p.roots(multiplicities=False)[2]     # relative tol 1e-10
     779       10^16
    745780
    746781-  If a line contains ``todo: not implemented``, it is never
    747782   tested. It is good to include lines like this to make clear what we