# HG changeset patch
# User Rob Beezer <beezer@ups.edu>
# 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

b


728  728  0.0511114082399688 
729  729  
730  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`` 
 731  verified to the given tolerance. This may be prefixed by ``abs[olute]`` 
732  732  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: 
735  735  
736  736  :: 
737  737  
738   sage: RDF(pi) # abs tol 1e5 
739   3.14159 
740   sage: [10^n for n in [0.0 .. 4]] # rel tol 2e4 
741   [0.9999, 10.001, 100.01, 999.9, 10001] 
 738  sage: RDF(pi) # abs tol 1e5 
 739  3.14159 
 740  sage: [10^n for n in [0.0 .. 4]] # rel tol 2e4 
 741  [0.9999, 10.001, 100.01, 999.9, 10001] 
742  742  
743  743  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()*Uidentity_matrix(8)).norm() # abs tol 1e10 
 758  0.0 
 759  
 760  The 8th cyclotomic field is generated by the complex number 
 761  `e^\frac{i\pi}{4}`. Here we compute a numerical approximation. 
 762  
 763  :: 
 764  
 765  sage: K = CyclotomicField(8) 
 766  sage: g = K.gen(0); g 
 767  zeta8 
 768  sage: N(zeta8) # absolute tolerance 1e15 
 769  0.707106781186548 + 0.707106781186547*I 
 770  
 771  A relative tolerance on a root of a polynomial. 
 772  
 773  :: 
 774  
 775  sage: y = polygen(RDF, 'y') 
 776  sage: p = (y  10^16)*(y10^(13))*(y2); p 
 777  y^3 + (1e+16)*y^2 + (2e+16)*y  2000.0 
 778  sage: p.roots(multiplicities=False)[2] # relative tol 1e10 
 779  10^16 
745  780  
746  781   If a line contains ``todo: not implemented``, it is never 
747  782  tested. It is good to include lines like this to make clear what we 