added best practices

Author: thomasWeise

bibliography/bibliography.bib

@@ -29,6 +29,7 @@ @string { a_back_ralph_johan
 @string { a_bai_junjie = "Junjie Bai" }
 @string { a_barham_paul = "Paul Barham" }
 @string { a_barret_daniel_j = "Daniel J. Barrett" }
+@string { a_baumgartner_gary = "Gary Baumgartner" }
 @string { a_beazley_david_m = "David M.\ Beazley" }
 @string { a_beigel_richard = "Richard Beigel" }
 @string { a_ben_david_shai = "Shai Ben{-}David" }
@@ -56,6 +57,7 @@ @string { a_chilamkurthy_sasank
 @string { a_chintala_soumith = "Soumith Chintala" }
 @string { a_cimran_robert = "Robert Cimrman" }
 @string { a_clinton_david = "David Clinton" }
+@string { a_coghlan_alyssa = "Alyssa Coghlan" }
 @string { a_cornapeau_david = "David Cournapeau" }
 @string { a_d_alche_buc_florence = "Florence d'Alch{\'e}{-}Buc" }
 @string { a_da_veiga_leprevost_felipe = "Felipe {da Veiga Leprevost}" }
@@ -73,6 +75,7 @@ @string { a_fang_lu
 @string { a_feng_yu = "Yu Feng" }
 @string { a_fernandez_del_rio_jaime = "Jaime {Fern{\'a}ndez del R{\'i}o}" }
 @string { a_filaseta_michael = "Michael Filaseta" }
+@string { a_flannery_brian_p = "Brian P.\ Flannery" }
 @string { a_flight_robert_m = "Robert M.\ Flight" }
 @string { a_fox_emily_b = "Emily B.\ Fox" }
 @string { a_fufezan_christian = "Christian Fufezan" }
@@ -86,13 +89,15 @@ @string { a_gommers_ralf
 @string { a_gramfort_alexandre = "Alexandre Gramfort" }
 @string { a_grendell_lina = "Linda Grandell" }
 @string { a_grisel_olivier = "Olivier Grisel" }
+@string { a_goodger_david = "David Goodger" }
 @string { a_gross_sam = "Sam Gross" }
 @string { a_grus_joel = "Joel Grus" }
 @string { a_grys_slawomir = "S{\l}awomir Gry{\'s}" }
 @string { a_haberland_matt = "Matt Haberland" }
 @string { a_haldane_allan = "Allan Haldane" }
 @string { a_harris_charles_r = "Charles R.\ Harris" }
 @string { a_hausenblas_michael = "Michael Hausenblas" }
+@string { a_heap_danny = "Danny Heap" }
 @string { a_henriksen_ian = "Ian Henriksen" }
 @string { a_hollasch_steve = "Steve Hollasch" }
 @string { a_hoyer_stephan = "Stephan Hoyer" }
@@ -109,6 +114,7 @@ @string { a_kern_robert
 @string { a_killeen_trevor = "Trevor Killeen" }
 @string { a_klopf_andreas = "Andreas K{\"o}pf" }
 @string { a_konovalov_alexander = "Alexander Konovalov" }
+@string { a_krueger_richard = "Richard Krueger" }
 @string { a_kudlur_manjunath = "Manjunath Kudlur" }
 @string { a_landau_charles = "Charles Landau" }
 @string { a_larochelle_hugo = "Hugo Larochelle" }
@@ -155,6 +161,7 @@ @string { a_peterson_pearu
 @string { a_picus_matti = "Matti Picus" }
 @string { a_polat_ilhan = "Ilhan Polat" }
 @string { a_pollard_tom_j = "Tom J.\ Pollard" }
+@string { a_press_william_h = "William H.\ Press" }
 @string { a_prettenhofer_peter = "Peter Prettenhofer" }
 @string { a_quinter_ea = "E.\ A.\ Quintero" }
 @string { a_raison_martin = "Martin Raison" }
@@ -178,6 +185,7 @@ @string { a_steiner_benoit
 @string { a_taylor_julian = "Julian Taylor" }
 @string { a_tejani_alykhan = "Alykhan Tejani" }
 @string { a_ternent_tobias = "Tobias Ternent" }
+@string { a_teukolsky_saul_a = "Saul A.\ Teukolsky" }
 @string { a_thirion_bertrand = "Bertrand Thirion" }
 @string { a_tolhurst_denise = "Denise Tolhurst" }
 @string { a_torregrossa_dario = "Dario Torregrossa" }
@@ -194,12 +202,14 @@ @string { a_van_rossum_guido
 @string { a_van_rysdam = "Peter {van Rysdam}" }
 @string { a_varoquaux_gael = "Ga{\"e}l Varoquaux" }
 @string { a_vasudevan_vijay = "Vijay Vasudevan" }
+@string { a_vetterling_william_t = "William T.\ Vetterling" }
 @string { a_virtanen_pauli = "Pauli Virtanen" }
 @string { a_vizcaino_juan_antonio = "Juan Antonio Vizca{\'i}no" }
 @string { a_wallach_hanna_m = "Hanna M.\ Wallach" }
 @string { a_wang_rui = "Rui Wang" }
 @string { a_warden_pete = "Pete Warden" }
-@string { a_warren_weckesser = "Warren Weckesser" }
+@string { a_warsaw_barry = "Barry Warsaw" }
+@string { a_weckesser_warren = "Warren Weckesser" }
 @string { a_weise_thomas = "Thomas Weise" }
 @string { a_weiss_ron = "Ron Weiss" }
 @string { a_wicke_martin = "Martin Wicke" }
@@ -218,6 +228,7 @@ @string { a_zinoviev_dimitry
 %% locations
 @string { l_australia_hobart = "{{Hobart}, {TAS}, {Australia}}" }
 @string { l_canada_oakville = "{{Oakville}, {ON}, {Canada}}" }
+@string { l_canada_toronto = "{{Toronto}, {ON}, {Canada}}" }
 @string { l_canada_vancouver = "{{Vancouver}, {BC}, {Canada}}" }
 @string { l_china_beijing = "{{China}, {Beijing}}" }
 @string { l_portugal_lisbon = "{{Lisbon}, {Portugal}}" }
@@ -283,6 +294,7 @@ @string { p_springer_new_york
 @string { p_taylor_and_francis = "{Taylor and Francis Ltd.}" }
 @string { p_unicode_consortium = "{The Unicode Consortium}" }
 @string { p_university_of_south_carolina = "{University of South Carolina}" }
+@string { p_university_of_toronto_cs = "{{Department of Computer Science}, {University of Toronto}}" }
 @string { p_university_of_washington = "{University of Washington}" }
 @string { p_usas = "{United States of America Standards Institute~{(USAS)}}" }
 @string { p_usenix = "{{USENIX} Association}" }
@@ -320,6 +332,7 @@ @string { pa_springer_nature_limited
 @string { pa_springer_new_york = l_usa_new_york }
 @string { pa_unicode_consortium = l_usa_south_san_francisco }
 @string { pa_university_of_south_carolina = l_usa_columbia }
+@string { pa_university_of_toronto_cs = l_canada_toronto }
 @string { pa_university_of_washington = l_usa_seattle }
 @string { pa_usas = l_usa_new_york }
 @string { pa_usenix = l_usa_berkeley }
@@ -436,6 +449,12 @@ @xdata{rep_ieee_standard
  type = {{IEEE}~Std},
 }
 
+@xdata{rep_pep,
+ type = {Python Enhancement Proposal~{(PEP)}},
+ institution = p_python_software_foundation,
+ address = pa_python_software_foundation
+}
+
 @xdata{rep_nsotprocg,
  type = {National Standard of the People's Republic of China~{(GB)}},
  address = l_china_beijing
@@ -571,6 +590,24 @@ @book{B2023W1IO
  execute = {\sloppy}
 }
 
+@book{BHK2006CNFCMEARFCS,
+ author = a_baumgartner_gary # and # a_heap_danny # and # a_krueger_richard,
+ title = {Course Notes for {CSC165H}: Mathematical Expression and Reasoning for Computer Science},
+ date = {2006-23},
+ publisher = p_university_of_toronto_cs,
+ address = pa_university_of_toronto_cs,
+ url = {https://www.cs.toronto.edu/~krueger/csc165h/f06},
+ urldate = {2024-07-27}
+}
+
+@inbook{BHK2006NS,
+ title = {Numerical Systems},
+ chapter = {7},
+ crossref = {BHK2006CNFCMEARFCS},
+ url = {https://www.cs.toronto.edu/~krueger/csc165h/f06/lectures/ch7.pdf},
+ urldate = {2024-07-27}
+}
+
 @article{CBST2024LOHPPTDDSAMLA,
  author = a_castro_oscar # and # a_bruneau_pierrix # and # a_sottet_jean_sebastien # and # a_torregrossa_dario,
  title = {Landscape of High-Performance \python\ to Develop Data Science and Machine Learning Applications},
@@ -722,7 +759,7 @@ @book{H2023ABGTP3P
 }
 
 @article{HMvdWGVCWTBSKPHvKBHFdRWPGMSRWAGO2020APWN,
- author = a_harris_charles_r # and # a_millman_jarrod_k # and # a_van_der_walt_stefan # and # a_gommers_ralf # and # a_virtanen_pauli # and # a_cornapeau_david # and # a_wieser_eric # and # a_taylor_julian # and # a_berg_sebastian # and # a_smith_nathaniel_j # and # a_kern_robert # and # a_picus_matti # and # a_hoyer_stephan # and # a_van_kerkwijk_marten_h # and # a_brett_matthew # and # a_haldane_allan # and # a_fernandez_del_rio_jaime # and # a_wiebe_mark # and # a_peterson_pearu # and # a_gerard_marchant_pierre # and # a_sheppart_kevin # and # a_reddy_tyler # and # a_warren_weckesser # and # a_abbasi_hameer # and # a_gohlke_christoph # and # a_oliphant_travis_e,
+ author = a_harris_charles_r # and # a_millman_jarrod_k # and # a_van_der_walt_stefan # and # a_gommers_ralf # and # a_virtanen_pauli # and # a_cornapeau_david # and # a_wieser_eric # and # a_taylor_julian # and # a_berg_sebastian # and # a_smith_nathaniel_j # and # a_kern_robert # and # a_picus_matti # and # a_hoyer_stephan # and # a_van_kerkwijk_marten_h # and # a_brett_matthew # and # a_haldane_allan # and # a_fernandez_del_rio_jaime # and # a_wiebe_mark # and # a_peterson_pearu # and # a_gerard_marchant_pierre # and # a_sheppart_kevin # and # a_reddy_tyler # and # a_weckesser_warren # and # a_abbasi_hameer # and # a_gohlke_christoph # and # a_oliphant_travis_e,
  title = {Array programming with \numpy},
  xdata = {j_n},
  volume = {585},
@@ -847,6 +884,36 @@ @book{P2021HOMLPAVWP
  isbn = {9781484274101}
 }
 
+@techreport{PEP8,
+ title = {Style Guide for Python Code},
+ author = a_van_rossum_guido # and # a_warsaw_barry # and # a_coghlan_alyssa,
+ xdata = {rep_pep},
+ number = {8},
+ date = {2001-07-05},
+ url = {https://peps.python.org/pep-0008},
+ urldate = {2024-07-27}
+}
+
+@techreport{PEP257,
+ title = {Docstring Conventions},
+ author = a_goodger_david # and # a_van_rossum_guido,
+ number = {257},
+ xdata = {rep_pep},
+ date = {2001-05-29},
+ url = {https://peps.python.org/pep-0257},
+ urldate = {2024-07-27},
+}
+
+@techreport{PEP498,
+ author = a_smith_eric_v,
+ title = {Literal String Interpolation},
+ xdata = {rep_pep},
+ number = {498},
+ date = {2016-11-06/2023-09-09},
+ url = {https://peps.python.org/pep-0498},
+ urldate = {2024-07-25},
+}
+
 @inproceedings{PGMLBCKLGADKYDRTCSFBC2019PAISHPDLL,
  author = a_paszke_adam # and # a_gross_sam # and # a_massa_francisco # and # a_lerer_adam # and # a_bradbury_james # and # a_chanan_gregory # and # a_killeen_trevor # and # a_lin_zeming # and # a_gimelshein_natalia # and # a_antiga_luca # and # a_desmaison_alban # and # a_klopf_andreas # and # a_yang_edward_z # and # a_devito_zachary # and # a_raison_martin # and # a_tejani_alykhan # and # a_chilamkurthy_sasank # and # a_steiner_benoit # and # a_fang_lu # and # a_bai_junjie # and # a_chintala_soumith,
  title = {\pytorch: An Imperative Style, High-Performance Deep Learning Library},
@@ -940,6 +1007,26 @@ @inbook{PSF2024TSTS
  urldate = {2024-07-25},
 }
 
+@inbook{PTVF2007EAAS,
+ title = {1.1~Error, Accuracy, and Stability},
+ chapter = {1~Preliminaries},
+ pages = {8--12},
+ crossref = {PTVF2007NRTAOSC}
+}
+
+@book{PTVF2007NRTAOSC,
+ author = a_press_william_h # and # a_teukolsky_saul_a # and # a_vetterling_william_t # and # a_flannery_brian_p,
+ title = {Numerical Recipes: The Art of Scientific Computing},
+ edition = {3},
+ date = {2007/2011},
+ note = {Version~3.04},
+ publisher = p_cambridge_uni_press_ass,
+ address = pa_cambridge_uni_press_ass,
+ isbn = {978-0-521-88068-8},
+ url = {https://numerical.recipes/book.html},
+ urldate = {2024-07-27},
+}
+
 @article{PVGMTGBPWDVPCBPD2011SMLIP,
  author = a_pedregosa_fabian # and # a_varoquaux_gael # and # a_gramfort_alexandre # and # a_michel_vincent # and # a_thirion_bertrand # and # a_grisel_olivier # and # a_blondel_mathieu # and # a_prettenhofer_peter # and # a_weiss_ron # and # a_dubourg_vincent # and # a_vanderplas_jake # and # a_passos_alexandre # and # a_cornapeau_david # and # a_brucher_matthieu # and # a_perrot_matthieu # and # a_duchesnay_edouard,
  title = {\scikitlearn: Machine Learning in \python},
@@ -981,16 +1068,6 @@ @article{S1988WPCHD
  pages = {117},
 }
 
-@book{S2016P4LSI,
- author = a_smith_eric_v,
- title = {PEP~498 -- Literal String Interpolation},
- publisher = p_python_software_foundation,
- address = pa_python_software_foundation,
- date = {2016-11-06/2023-09-09},
- url = {https://peps.python.org/pep-0498},
- urldate = {2024-07-25},
-}
-
 @book{S2023LG,
  author = a_skoulikari_anna,
  title = {Learning \git},
@@ -1071,7 +1148,7 @@ @techreport{USAS1967USCFII
 }
 
 @article{VGOHRCBPWBvdWBWMMNJKLCPFMVLPCHQHARPvMS2020SFAFSCIP,
- author = a_virtanen_pauli # and # a_gommers_ralf # and # a_oliphant_travis_e # and # a_haberland_matt # and # a_reddy_tyler # and # a_cornapeau_david # and # a_burovski_evgeni # and # a_peterson_pearu # and # a_warren_weckesser # and # a_bright_jonathan # and # a_van_der_walt_stefan # and # a_brett_matthew # and # a_wilson_joshua # and # a_millman_jarrod_k # and # a_mayorov_nikolay # and # a_nelson_andrew_r_j # and # a_jones_eric # and # a_kern_robert # and # a_larson_eric # and # a_carey_cj # and # a_polat_ilhan # and # a_feng_yu # and # a_moore_eric_w # and # a_vanderplas_jake # and # a_laxalde_denis # and # a_perktold_josef # and # a_cimran_robert # and # a_henriksen_ian # and # a_quinter_ea # and # a_harris_charles_r # and # a_archibald_anne_m # and # a_ribeiro_antonio_h # and # a_pedregosa_fabian # and # a_van_mulbregt_paul # and # a_scipy_1,
+ author = a_virtanen_pauli # and # a_gommers_ralf # and # a_oliphant_travis_e # and # a_haberland_matt # and # a_reddy_tyler # and # a_cornapeau_david # and # a_burovski_evgeni # and # a_peterson_pearu # and # a_weckesser_warren # and # a_bright_jonathan # and # a_van_der_walt_stefan # and # a_brett_matthew # and # a_wilson_joshua # and # a_millman_jarrod_k # and # a_mayorov_nikolay # and # a_nelson_andrew_r_j # and # a_jones_eric # and # a_kern_robert # and # a_larson_eric # and # a_carey_cj # and # a_polat_ilhan # and # a_feng_yu # and # a_moore_eric_w # and # a_vanderplas_jake # and # a_laxalde_denis # and # a_perktold_josef # and # a_cimran_robert # and # a_henriksen_ian # and # a_quinter_ea # and # a_harris_charles_r # and # a_archibald_anne_m # and # a_ribeiro_antonio_h # and # a_pedregosa_fabian # and # a_van_mulbregt_paul # and # a_scipy_1,
  title = {\scipy~1.0:~Fundamental Algorithms for Scientific Computing in \python},
  xdata = {j_nm},
  date = {2020-03-02},

styles/colors.sty

@@ -51,8 +51,8 @@
 %%
 \colorlet{definition-frame}{hfuu-red!70}%
 \colorlet{definition-background}{hfuu-orange!20}%
-\colorlet{ruleofthumb-frame}{OliveGreen!50}%
-\colorlet{ruleofthumb-background}{Aquamarine!20}%
+\colorlet{bestpractice-frame}{OliveGreen!50}%
+\colorlet{bestpractice-background}{Aquamarine!20}%
 %
 %%
 %% Table Coloring

styles/definitions.sty

@@ -15,32 +15,32 @@ rightmargin=5pt,%
 font={}%
 ]{definition}{\definitionautorefname}[chapter]%
 %
-\newcommand{\@ruleOfThumbautorefname}{Rule of Thumb}%
+\newcommand{\@bestPracticeautorefname}{Best Practice}%
 %
 \newmdtheoremenv[%
 linewidth=2pt,%
-linecolor=ruleofthumb-frame,%
+linecolor=bestpractice-frame,%
 roundcorner=4pt,%
-backgroundcolor=ruleofthumb-background,%
+backgroundcolor=bestpractice-background,%
 leftmargin=5pt,%
 rightmargin=5pt,%
 font={}%
-]{@ruleOfThumb}{\@ruleOfThumbautorefname}%
-%%
-\xdef\@rulesOfThumb{}%
+]{@bestPractice}{\@bestPracticeautorefname}%
+%
+\xdef\@bestPractices{}%
 %
-\gdef\ruleOfThumb#1#2{%
-\begin{@ruleOfThumb}\label{rule:#1}#2\end{@ruleOfThumb}%
+\gdef\bestPractice#1#2{%
+\begin{@bestPractice}\label{bp:#1}#2\end{@bestPractice}%
 %
-\ifx\@rulesOfThumbs\empty\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi%
-{\gdef\@rulesOfThumb{\noindent\autoref{rule:#1}:~#2}}%
-{\g@addto@macro\@rulesOfThumb{\medskip\par\noindent\autoref{rule:#1}: #2}}%
+\ifx\@bestPractices\empty\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi%
+{\gdef\@bestPractices{\noindent\cref{bp:#1}:~#2}}%
+{\g@addto@macro\@bestPractices{\medskip\par\noindent\cref{bp:#1}: #2}}%
 }%
 %
-\gdef\printRulesOfThumb{%
-\chapter*{Rules of Thumb}%
-\pdfbookmark{Rules of Thumb}{Rules of Thumb}%
-\@rulesOfThumb%
+\gdef\printBestPractices{%
+\chapter*{Best Practices}%
+\pdfbookmark{Best Practices}{Best Practices}%
+\@bestPractices%
 }%
 %
 \protected\gdef\noviceHint#1{%

styles/styles.sty

@@ -33,5 +33,6 @@
 \RequirePackage[sort&compress,capitalise,nameinlink,noabbrev]{cleveref}%
 \creflabelformat{equation}{#2\textup{#1}#3}%%
 \crefrangelabelformat{equation}{#3\textup{#1}#4 to~#5\textup{#2}#6}%
-\crefname{@ruleOfThumb}{Rule of Thumb}{Rules of Thumb}%
+\crefname{@bestPractice}{\@bestPracticeautorefname}{\@bestPracticeautorefname}%
+\Crefname{@bestPractice}{\@bestPracticeautorefname}{\@bestPracticeautorefname}%
 %

text/back/backmatter.tex

@@ -8,8 +8,7 @@
 \setulmarginsandblock{2.5cm}{2.5cm}{*}%0
 \checkandfixthelayout%
 %
-%\printRulesOfThumb%
-%\printsymbols%
+\printBestPractices%
 \printacronyms%
 \printglossaries%
 %

text/main/basics/simpleDataTypesAndOperations/float/float.tex

@@ -66,6 +66,7 @@
 In other words, regardless whether your \pythonilIdx{float} stores a very large or a very small number, you can have at most 15~digits of precision.
 For example, adding~1 to~$10^{16}$ would still yield~$10^{16}$, because only 15~digits are \inQuotes{stored} and the~1 will just \inQuotes{fall off.}
 You cannot represent numbers arbitrarily precisely.%
+%
 \endhsection%
 %
 \hsection{Floating Point Arithmetic}%
@@ -138,6 +139,17 @@
 Calculating \pythonil{asin(sin(0.925))}\pythonIdx{asin}\pythonIdx{sin} indeed yields~\pythonil{0.9250000000000002}.
 Due to the periodicity of the trigonometric functions, $\arccos{\cos{-0.3}}$ is~$0.3$ and \pythonil{acos(cos(-0.3))}\pythonIdx{acos}\pythonIdx{cos} results in~\pythonil{0.30000000000000016}.
 For $\arctan{\tan{1}}$ we even get the exact result \pythonil{1.0} by computing \pythonil{atan(tan(1))}\pythonIdx{atan}\pythonIdx{tan}.%
+%
+\bestPractice{floatImprecise}{%
+Always assume that any \pythonilIdx{float} value is imprecise. %
+Never expect it to be exact~\cite{PTVF2007EAAS,BHK2006NS}.%
+}%
+%
+Due to the limited precision, it could be that you add two numbers $c=a+b$ but then find that $c-a\neq b$, because some digit was lost. %
+This is obvious when adding a very small number to a very large number.
+We only have about 15~digits, so doing something like~$10^{20} + 1$ will usually work out to just be~$10^{20}$ in floating point arithmetics~\cite{PTVF2007EAAS}.
+But digits could also be lost when adding numbers of roughly the same scale, because their sum could just be larger so that the 15-digit-window shifts such that the least-significant digit falls off~\cite{BHK2006NS}{\dots}%
+%
 \endhsection%
 %
 \hsection{Back to Integers: Rounding}%

text/main/basics/simpleDataTypesAndOperations/int/int.tex

@@ -56,6 +56,8 @@
 Computing \pythonil{32 / 4} thus yields~\pythonil{8.0}, \pythonil{33 / 4} gives us \pythonil{8.25}, \pythonil{34 / 4} yields~\pythonil{8.5}, \pythonil{35 / 4} results in \pythonil{8.75}, and, finally, \pythonil{36 / 4} returns~\pythonil{9.0}.
 Notice that the result of this division operator is always a floating point number, even if the number itself is an integer.
 
+\bestPractice{intDivision}{Always be careful with which division operator you use for \pythonilIdx{int}s. If you need an integer result, make sure to use \pythonilIdx{//}. Remember that \pythonilIdx{/} always returns a \pythonilIdx{float} (and see \cref{bp:floatImprecise}), even if the result is a whole number.}
+
 Now above we have said that \pythonil{33 // 4} yields the integer~\pythonil{8}.
 The remainder of this operation can be computed using the \pgls{modulodiv} operator \expandafter\pythonilIdx{\%}, i.e., by typing \pythonil{33 \% 4}, which yields~\pythonil{1}.
 We also find that \expandafter\pythonil{34 \% 4} yields~\pythonil{2}, \expandafter\pythonil{35 \% 4} gives us~\pythonil{3}, and \expandafter\pythonil{36 \% 4} is~\pythonil{0}.