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

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

# HG changeset patch
# User Rob Beezer <beezer@ups.edu>
# Date 1314202161 25200
# Parent  f32a34f366fbbd1b1942c4585bdd0c61e2fa0a4c
diff --git a/doc/en/developer/conventions.rst b/doc/en/developer/conventions.rst
 a sage: E.regulator()              # long time (1 second) 0.0511114082399688 -  If a line contains tol or tolerance, numerical results are only verified to the given tolerance. This may be prefixed by abs[olute -  If a line contains tol or tolerance, numerical results are only verified to the given tolerance. This may be prefixed by abs[olute] or rel[ative] to specify whether to measure absolute or relative error; defaults to relative error except when the expected value is exactly zero: error; this defaults to relative error except when the expected value is exactly zero: :: sage: RDF(pi)                               # abs tol 1e-5 3.14159 sage: [10^n for n in [0.0 .. 4]]            # rel tol 2e-4 [0.9999, 10.001, 100.01, 999.9, 10001] sage: RDF(pi)                               # abs tol 1e-5 3.14159 sage: [10^n for n in [0.0 .. 4]]            # rel tol 2e-4 [0.9999, 10.001, 100.01, 999.9, 10001] This can be useful when the exact output is subject to rounding error and/or processor floating point arithmetic variation. and/or processor floating point arithmetic variation.  Here are some more examples. A singular value decomposition of a matrix will produce two unitary matrices.  Over the reals, this means the inverse of the matrix is equal to its transpose.  We test this result by applying the norm to a matrix difference.  The result will usually be a "small" number, distinct from zero. :: sage: A = matrix(RDF, 8, range(64)) sage: U, S, V = A.SVD() sage: (U.transpose()*U-identity_matrix(8)).norm()    # abs tol 1e-10 0.0 The 8-th cyclotomic field is generated by the complex number e^\frac{i\pi}{4}.  Here we compute a numerical approximation. The value provided in the source of the doctest (0.707106781186548 + 0.707106781186547*I), and the value computed by the tested instance of Sage (N(zeta8)) are subtracted from each other and fed into the abs() function for comparison to the tolerance.  So the only prerequisite for using this feature is that the abs() function may be applied. Of course, for a relative tolerance, division must also be possible. :: sage: K = CyclotomicField(8) sage: g = K.gen(0); g zeta8 sage: N(zeta8)                             # absolute tolerance 1e-15 0.707106781186548 + 0.707106781186547*I A relative tolerance on a root of a polynomial.  Notice that the root should normally print as 1e+16, or something similar. However, the tolerance testing causes the doctest framework to use the output in a *computation*, so any valid text representation of the predicted value may be used. :: sage: y = polygen(RDF, 'y') sage: p = (y - 10^16)*(y-10^(-13))*(y-2); p y^3 + (-1e+16)*y^2 + (2e+16)*y - 2000.0 sage: p.roots(multiplicities=False)[2]     # relative tol 1e-10 10^16 -  If a line contains todo: not implemented, it is never tested. It is good to include lines like this to make clear what we