# HG changeset patch
# User Rob Beezer
# 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/doc/en/developer/conventions.rst
+++ b/doc/en/developer/conventions.rst
@@ -728,20 +728,55 @@
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``
+ 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.
+
+ ::
+
+ 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.
+
+ ::
+
+ 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