Ticket #12815: 12815_tolerance_doc.patch

File 12815_tolerance_doc.patch, 2.4 KB (added by jdemeyer, 7 years ago)
  • doc/en/developer/conventions.rst

    # HG changeset patch
    # User Jeroen Demeyer <jdemeyer@cage.ugent.be>
    # Date 1357636755 -3600
    # Node ID 0d68a886ccf3a651fd5bfd92f11c55a59bed3d75
    # Parent  7b89b8deffb55ebc7951552bbbf3d2009b8e97ec
    Fix documentation for "tolerance" doctests
    
    diff --git a/doc/en/developer/conventions.rst b/doc/en/developer/conventions.rst
    a b  
    795795       0.0
    796796       
    797797   The 8-th cyclotomic field is generated by the complex number
    798    `e^\frac{i\pi}{4}`.  Here we compute a numerical approximation.
    799    The value provided in the source of the doctest
    800    (``0.707106781186548 + 0.707106781186547*I``), and the value
    801    computed by the tested instance of Sage (``N(zeta8)``) are
    802    subtracted from each other and fed into the ``abs()`` function
    803    for comparison to the tolerance.  So the only prerequisite for
    804    using this feature is that the ``abs()`` function may be applied.
    805    Of course, for a relative tolerance, division must also be possible.
    806    
    807    ::
     798   `e^\frac{i\pi}{4}`.  Here we compute a numerical approximation::
    808799       
    809800       sage: K.<zeta8> = CyclotomicField(8)
    810        sage: N(zeta8)                             # absolute tolerance 1e-15
    811        0.707106781186548 + 0.707106781186547*I
     801       sage: N(zeta8)                             # absolute tolerance 1e-10
     802       0.7071067812 + 0.7071067812*I
    812803
    813    A relative tolerance on a root of a polynomial.  Notice that
    814    the root should normally print as ``1e+16``, or something similar.
    815    However, the tolerance testing causes the doctest framework to
    816    use the output in a *computation*, so any valid text representation
    817    of the predicted value may be used. **This is actually broken**, see
    818    :trac:`12815`.
    819    
    820    ::
     804   The "tolerance" feature checks for floating-point literals, which
     805   may occur anywhere in the doctest output, for example as polynomial
     806   coefficients::
    821807
    822808       sage: y = polygen(RDF, 'y')
    823        sage: p = (y - 10^16) * (y - 10^-13) * (y - 2)
    824        sage: p.roots(multiplicities=False)[2]     # relative tol 1e-10
    825        1e16
     809       sage: p = (y - 10^10) * (y - 1); p
     810       y^2 - 10000000001.0*y + 10000000000.0
     811       sage: p                           # rel tol 1e-9
     812       y^2 - 1e10*y + 1e10
     813
    826814
    827815-  If a line contains ``todo: not implemented``, it is never
    828816   tested. It is good to include lines like this to make clear what we