# HG changeset patch
# User Rob Beezer
# 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/doc/en/developer/conventions.rst
+++ b/doc/en/developer/conventions.rst
@@ -727,21 +727,67 @@
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