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

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

    # HG changeset patch
    # User Rob Beezer <beezer@ups.edu>
    # Date 1314202161 25200
    # Node ID 19869e55d88e0b45c9ad19f73c949f7e925d29bf
    # Parent  f32a34f366fbbd1b1942c4585bdd0c61e2fa0a4c
    10952: reviewer documentation additions
    
    diff --git a/doc/en/developer/conventions.rst b/doc/en/developer/conventions.rst
    a b  
    727727       sage: E.regulator()              # long time (1 second)
    728728       0.0511114082399688
    729729
    730 -  If a line contains ``tol`` or ``tolerance, numerical results are only
    731    verified to the given tolerance. This may be prefixed by ``abs[olute``
     730-  If a line contains ``tol`` or ``tolerance``, numerical results are only
     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   The value provided in the source of the doctest
     763   (``0.707106781186548 + 0.707106781186547*I``), and the value
     764   computed by the tested instance of Sage (``N(zeta8)``) are
     765   subtracted from each other and fed into the ``abs()`` function
     766   for comparison to the tolerance.  So the only prerequisite for
     767   using this feature is that the ``abs()`` function may be applied.
     768   Of course, for a relative tolerance, division must also be possible.
     769   
     770   ::
     771       
     772       sage: K = CyclotomicField(8)                     
     773       sage: g = K.gen(0); g
     774       zeta8
     775       sage: N(zeta8)                             # absolute tolerance 1e-15
     776       0.707106781186548 + 0.707106781186547*I
     777
     778   A relative tolerance on a root of a polynomial.  Notice that
     779   the root should normally print as ``1e+16``, or something similar.
     780   However, the tolerance testing causes the doctest framework to
     781   use the output in a *computation*, so any valid text representation
     782   of the predicted value may be used.
     783   
     784   ::
     785
     786       sage: y = polygen(RDF, 'y')
     787       sage: p = (y - 10^16)*(y-10^(-13))*(y-2); p
     788       y^3 + (-1e+16)*y^2 + (2e+16)*y - 2000.0
     789       sage: p.roots(multiplicities=False)[2]     # relative tol 1e-10
     790       10^16
    745791
    746792-  If a line contains ``todo: not implemented``, it is never
    747793   tested. It is good to include lines like this to make clear what we