The PXD Whitebook Instructions 1 Contents 1 Writing Conventions - - PDF document

The PXD Whitebook Instructions

1

Contents

1 Writing Conventions and Typesetting 3

Manfred Valentan

1.1 Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.1 Spelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.2 Ignoring temporary files in git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.3 Acronyms and glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.4 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.5 Automatic compilation with latexmk . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.6 Tables, captions and labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.7 Axis labels and color map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2 Math typesetting in a nutshell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2.1 Variables, functions and Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2.2 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.2.3 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.2.4 Indices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2.5 Vectors and matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2.6 Particles and chemical elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.3 Other conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3.1 Quotation marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3.2 Umlauts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3.3 Useful commands and abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Glossary 11 Acronyms 14 2

Chapter 1

Writing Conventions and Typesetting

Manfred Valentan

This chapter gives an overview of guidelines, best practices and conventions which should lead to a con- sistent, useful and beautiful document. Read this first, before starting to write your own sections. If you have questions or suggestions, feel free to contact Manfred Valentan (manfred.valentan@mpp.mpg.de).

1.1 Best practices

1.1.1 Spelling

For this document we use the US1 spelling rather than the British one. Here are a few examples of spelling differences: US British digitizer digitiser neighbor neighbour flavor flavour labeling labelling center centre meter metre color colour gray grey We will update this list when more examples occur while writing the document.

1.1.2 Ignoring temporary files in git

L

AT

EX compilation produces a lot of temporary files, which we don’t want to upload to the git repository. One can have git ignore these files by writing them into the file .gitignore2.

1US: United States (of America) 2.gitignore is a hidden file, make sure to change the view options of your file browser to display it.

3

To see an overview of all changed files, run git status in a terminal, in the root folder of the

• whitebook. The section untracked files shows files which are new to git. If you see temporary files there,

please add them to .gitignore.

1.1.3 Acronyms and glossary

The documentation of the Belle II PXD3 project has to deal with a lot of acronyms and technical terms. In this whitebook we will compile a comprehensible collection of these terms in form of an acronym list and a glossary using the package glossaries [1]. The entries are defined in the files Conventions/acronyms.tex and Conventions/glossary.tex; all entries contain a key, a name and a description. When you write your text and come across an acronym or technical term, first check if it is already defined in one of these two files. If so, you can use it with the following command: \gls{key} This will put the name in the text. If it is an acronym which occurs for the first time, it will create a footnote with the description. Use glspl{key} to get the plural form of a technical term, and Gls{key}

• r Glspl{key} for the capitalized versions.

Usage After adding a new acronym or glossary entry, make sure you use \gls{...} in the text to invoke it. Compile the code once, then run makeglossaries PXDwb in a terminal. Many TeX editors have a dedicated button to do that. Recompile the code again. Your new acronym or glossary entry should appear in its respective section. See section 1.1.5 on how to automatize this compilation process.

1.1.4 Bibliography

The bibliography is provided by BibTeX [2]. All references are put in the file bibliography.bib, and the bibliography at the end of the whitebook is automatically sorted. The bibtex file bibliography.bib can be edited in any editor, but for more comfort you can use a specialized program like JabRef [3]. Usage After adding a new reference, make sure you use ~\cite{...} in the text to invoke it4. Compile the code once, then run bibtex PXDwb in a terminal. Many TeX editors have a dedicated button to do

• that. Recompile the code again. Your new reference should appear in the bibliography section. See

section 1.1.5 on how to automatize this compilation process.

1.1.5 Automatic compilation with latexmk

The Pearl script latexmk [4] automatizes the compilation process, including all commands for the bib- liography, the glossary and the acronym list. This is optional, you can also compile the document the traditional way. If you want to use latexmk, make sure it is installed on your local system. Use the web search to find

• ut how to do that for your operating system. Once installed, you can run the following command in a

command prompt: latexmk -pdf PXDwb Many TeX editors have a dedicated button to run latexmk.

1.1.6 Tables, captions and labels

Tables should only use horizontal lines, and the contents should be left-aligned [5].

3PXD: PiXel Detector 4Please note the non-breaking blank ˜ before the cite command. This makes sure that the the citation number can’t be

broken to the next line.

4

Table 1.1: A sample table to show the correct use of lines and justification. Header 1 Header 2 Header 3 Value 1 Value 2 Value 3 Value 4 Value 5 Value 6 Code for table 1.1: \begin{table}[htb] \centering \caption{A sample table to show the correct use of lines and justification.} \label{tab:sample} \begin{tabular}{lll} \toprule Header 1 & Header 2 & Header 3 \\ \midrule Value 1 & Value 2 & Value 3 \\ Value 4 & Value 5 & Value 6 \\ \bottomrule \end{tabular} \end{table} Please note that the command \label{} has to come after \caption{}, otherwise the counting of table numbers will be wrong. Captions

• f tables go on top (like in table 1.1), while captions of pictures and plots are put on the
• bottom. See figure 1.1 for an example plot. The caption should be self-explaining, i.e. one should be able

to understand the plot with help of the caption only, without having to refer to the document text. Labels used in the L

AT

EX code should consist of a prefix and a name, delimited by a semicolon: \label{prefix:name} See the code for table 1.1 for a sample label. Common prefixes include: Prefix Use for sec Chapters, sections, paragraphs tab Tables fig Figures and plots

1.1.7 Axis labels and color map

Axis labels should always display the name of the plotted quantity and its unit. A physical quantity is the product of a measure value (numerical) and a unit. In contrast, the values going into a plot are purely numerical, i.e. dimensionless. Consider this example: x = 3 cm This equation can be rewritten to: 3 = x/cm. The left side of the equation is the numerical value of the quantity x, which is drawn in the plot, while the right side is what goes on the axis. A correctly set plot would look like this: 5

−6 −4 −2 2 4 6 10 20 30 Distance x/cm Velocity v/cm s−1 Figure 1.1: A sample plot to show the correct axis labeling. Note that the common notation “Distance x [cm]” is wrong. The square brackets symbolize the unit

• perator. Applying the unit operator to a quantity returns its unit:

[x] = cm Read: “The unit of x is cm” Colormap The preferred and default colormap of Python’s plotting library matplotlib is Viridis. It is very linear, readable for partly color-blind people, and remains readable after conversion to grayscale. When you use a colormap, keep in mind that you can choose from many possibilities, and change to Viridis, if available. Figure 1.2 shows a comparison of the old and new default colormaps of matplotlib.

(a) Old: Jet (b) New: Viridis

Figure 1.2: Comparison of the old and new default colormaps of matplotlib. Viridis (b) is easier to read and converts better to grayscale.

1.2 Math typesetting in a nutshell

All conventions presented here are defined in the standard ISO-31 [6, 7, 8].

1.2.1 Variables, functions and Operators

Variables Symbols denoting variables are set italic. L

AT

EX math mode does that automatically. 6

Symbols consisting of more than one letters require special attention. Math mode thinks that multiple symbols are a multiplication, and sets them slightly apart. Use the command \mathit{...} to move them closer. Example: Ma = F (Newton’s law) Ma = 1 (Mach number) Functions Symbols denoting functions are generally set italic as well. For uppercase greek letters one has to enfore this by using \mathit{...}. Functions with well established names are set roman (i.e. using upright letters). Examples are: Description Code Result Wave function $\mathit{\Psi}(x,t)$ Ψ(x, t) Trigonometric functions $\cos(\phi)$ cos(φ) Exponential function $\exp(x)$ exp(x) Gamma function $\Gamma(x)$ Γ(x) Dirac’s delta function $\updelta(x)$ δ(x) Note that Dirac’s delta functions is set using the command \updelta from the package upgreek [9]. Operators Operators are functions with a well established name, and are treated the same: always set them roman (upright): Description Code Result Limes $\displaystyle\lim_{x\rightarrow\infty}f(x)$ lim

x→∞ f(x)

Differential operator $\int x^2 \mathrm{d}x$

• x2dx

1.2.2 Constants

Mathematical constants are set roman (upright), scientific and natural constants are set italic: Description Code Result Imaginary unit $\mathrm{i}$ i Circle constant $\uppi$ π Euler’s number $\mathrm{e}$ e Elementary charge $e$ e Velocity of light $c$ c

1.2.3 Units

Units (including their SI prefixes) are always set roman (upright). Between measure value and unit is a small, non-breaking blank. Description Code Result Correct $r = 3\,\upmu\mathrm{m}$ r = 3 µm Wrong $r = 3 \mu m$ r = 3µm 7

It is quite cumbersome to set units like this, so we use the package siunitx [10]. Description Code Result By hand $r = 3\,\upmu\mathrm{m}$ r = 3 µm Using siunitx $r = \SI{3}{\micro\metre}$ r = 3 µm Luminosity $\mathcal{L} = \SI{8e35} {\per\centi\metre\squared\per\second}$ L = 8 × 1035 cm−2 s−1 Momentum $p = \SI{1.2}{\giga\electronvolt\per\clight}$ p = 1.2 GeV c−1 Unit without value \si{\mega\electronvolt\per\clight\squared} MeV c−2 Notes: the µ from upgreek and siunitx are slightly different, because they come from different fonts. The c in units like MeV c−2 is italic, because it is a natural constant.

1.2.4 Indices

Indices representing another variable (like a counting index) or another physical quantity are set italic. Indices representing labels or abbreviations are set roman (upright): Description Code Result Bohr’s magneton $\mu_\mathrm{B}$ µB Transverse momentum $p_\mathrm{t}$ pt $\pt$ pt Counting index $x_i$ xi $x_\mathrm{max}$ xmax Muon neutrino $\upnu_\upmu$ νµ

1.2.5 Vectors and matrices

There are no SI rules, only international recommendations. In Germany one usually puts an arrow on top of the variable, but the internationally recommended way is to use a bold face instead. Vectors use lowercase letters, matrices use uppercase letters. Let’s use a simple eigenvalue equation as example: Description Code Result Usage in Germany $\bm{A}\vec{v}_n = \lambda_n \vec{v}_n$ A vn = λn vn Recommended $\bm{Av}_n = \lambda_n \bm v_n$ Avn = λnvn Wrong $\mathbf{Av}_n = \lambda_n \mathbf{v}_n$ Avn = λnvn Note that the command \textbf{...} does produce bold faced letters, but always sets them upright. This conflicts with the other SI rules. Instead use the command \bm{...} provided by the package bm [11].

1.2.6 Particles and chemical elements

Symbols representing particles and chemical elements are always set roman (upright). For greek letters this has to be enforced using the package upgreek [9]: 8

Description Code Result Electron $\mathrm{e}^-$ e− \eminus e− Upsilon(4S) $\Upsilon(4\mathrm{S})$ Υ(4S) with link to glossary \gls{upsilon}$(4\mathrm{S})$ Υ(4S) Neutrino $\upnu$ ν Leptons $\ell$ ℓ Note that the symbol for various leptons ℓ is set italic, because it is a variable. Don’t use the package hepnames, because it sets all greek letters wrongfully italic.

1.3 Other conventions

1.3.1 Quotation marks

There is a difference between opening and closing “quotation marks”. To open a quotation, use two times the symbol ‘ (next to the key 1 on US keyboards, next to ß on german keyboards); to close a quotation use two times the symbol ’ (next to Enter key).

1.3.2 Umlauts

The command \" just generates two dots on top of a letter, but the underlying letter is still the same. This can cause problems when searching the pdf for a word with umlauts. To get proper umlauts, make sure you have the TeXLive fonts installed: sudo apt-get install texlive-fonts-recommended Then replace all occurrences of the command \" with the commands below: Code Result \ae{} ä \Ae{} Ä \oe{} Ö \Oe{} Ö \ue{} ü \Ue{} Ü

1.3.3 Useful commands and abbreviations

The following symbols are often needed in high energy physics: Code Result Comment $\ell$ ℓ For variable leptons $\mathcal{L}$ L Luminosity $\mathcal{CP}$ CP Charge-parity conjugation The file abbreviations.tex contains a collection of commonly used L

AT

EX macros, for example: 9

Code Result Comment \eg e.g. Normal-sized blank after the period \ie i.e. Normal-sized blank after the period \xsuby{top}{bottom} topbottom Shortcut to set a roman index \axis{x} x-axis Works both in text mode and in math mode \coordinate{x} x-coordinate Works both in text mode and in math mode \plane{x}{y} x-y-plane Works both in text mode and in math mode \RPhi RΦ Shortcut for the correctly set coordinate \pt pt Works both in text mode and in math mode \type{n} n-type For silicon doping \xyztable xyz-table Includes a non-breaking dash \anti something anti-something Includes a non-breaking dash \CO2 CO2 Works both in text mode and in math mode You can extend the macros in abbreviations.tex and this list yourself, or you can ask Manfred Valentan to do it for you. 10

Glossary

Some of the definitions shown here are excerpts from Wikipedia. Υ The Υ meson is a so-called “bottonium”, consisting of a b quark and of a b anti-quark. 9 baryon A baryon is a composite subatomic particle composed of three quarks. 12 Belle Belle is the name of a former particle physics experiment at KEK5 (Tsukuba, Japan). Belle is not an acronym, so it’s written with a capital letter at the beginning only. Belle is the french word for “beautiful”, and hints to the b quark, also called “beauty quark”. 11 Belle II Belle II is the name of a future particle physics experiment at KEK (Tsukuba, Japan) which is presently under construction. It is the successor of the Belle experiment. 4 boson A boson is a (not necessarily fundamental) particle with an integer spin quantum number. It

• beys the Bose-Einstein statistics but not the Pauli exclusion principle. So, two bosons with an

identical set of quantum numbers can occupy the same state in a system. All mediators of the fundamental interactions are bosons. 13 charge conjugation The charge conjugation transforms a particle into its anti-particle by reversing all

• f its quantum numbers, especially the electrical charge. 11

charge-parity conjugation The charge-parity conjugation is the combination of the charge conjugation and the parity conjugation. 9 cross section The cross section is a hypothetical area which describes the likelihood of a reaction in a particle collision. It is different from the geometrical cross sections of the involved particles, and depends strongly on the collision energy. The typical unit is “barn”, where 1 b = 10−28 m2 (100 fm2). 12 electromagnetic The electromagnetic interaction is the force that acts on electrically charged particles, allowing them to be accelerated and trapped in bound states. Thus, it is responsible for the interaction between the atomic nucleus and the electron cloud. It is mediated by the photon. 12 electron The electron (symbol: e−) is a subatomic particle with a negative elementary electric charge. It is a lepton of the first generation of fundamental particles. 9, 11, 12 fermion A fermion is a (not necessarily fundamental) particle with a half-integer spin quantum number. It obeys the Fermi-Dirac statistics and the Pauli exclusion principle, stating that no two fermions with an identical set of quantum numbers can occupy the same state in a system. All leptons and quarks are fermions. 13

5KEK (Ko Enerugi Kasokuki Kenkyu Kiko) is a japanese organization whose purpose is to operate the largest particle

physics laboratory in Japan, which is located in Tsukuba (Ibaraki prefecture)

11

flavour Flavour refers to the type of elementary particles (either quarks or leptons) occurring in the Standard Model. There are flavour quantum numbers which depend on the number of particles of particular flavours which occur in a hadron. In strong interactions, flavour is conserved. In the weak interaction, however, this symmetry is broken, and flavour changing processes exist, such as quark decay or neutrino oscillations. 12 generation In particle physics, a generation (or family) is a division of the elementary particles. Between generations, particles differ by their (flavour) quantum number and mass, but their interactions are

• identical. There are three generations according to the Standard Model of particle physics. Each

generation is divided into two leptons and two quarks. The two leptons may be classified into one with electric charge -1 (electron-like) and one neutral (neutrino); the two quarks may be classified into one with charge -1/3 (down-type) and one with charge +2/3 (up-type). Every particle has a corresponding anti-particle. 11–13 gravitation Gravitation is the fourth fundamental interaction known today. It is the agent that gives weight to objects that have mass. Up to now it cannot be described with the same mathematical formalism as is used to describe the other three interactions. Therefore it could not yet be integrated into a consistent theory of all four interactions. Gravitation is described by the theory of general relativity, while the other interactions are described with quantum field theories. 12 hadron A hadron is a non-fundamental particle composed of quarks. Hadrons with three quarks are called baryons, hadrons with a quark and an anti-quark are called mesons. 12, 13 lepton A lepton is an fundamental particle which is assumed to be pointlike. The leptons of the standard model are the electron e−, the muon µ−, the tau τ−, the corresponding neutrinos νe, νµ and ντ, as well as their anti-particles. A lepton does not undergo strong interactions, it interacts electromagnetically, weakly and gravitationally. λǫπτ´

• σ (greek): small, thin, tiny. 9, 11–13

luminosity The luminosity L is one of the main parameters of a particle colliders, as it translates directly to the reaction rate R via R = σL, where σ is the cross section of the reaction in question. The luminosity can be tuned by proper adjustment of the collider. 9 meson A meson is a composite subatomic particle composed of one quark and one anti-quark. 11, 12 muon The muon (symbol: µ−) is a subatomic particle with a negative elementary charge. It is a lepton

• f the second generation of fundamental particles. 8, 12

neutrino The neutrino (symbol: νe, νµ or ντ, depending on the particle generation) is an electrically neutral lepton, which only interacts by the weak interaction and by gravitation. Is is therefore extremely difficult to detect. 8, 9, 12, 13 neutron The neutron (symbol: n or n0) is a subatomic particle with no net electric charge and a mass slightly larger than that of a proton. With the exception of hydrogen-1, nuclei of atoms consist

• f protons and neutrons, which are therefore collectively referred to as nucleons. In the modern

Standard Model of particle physics, the neutron is a hadron, composed of one up quark and two down quarks. 13 parity conjugation The parity conjugation is a symmetry operation which mirrors a vector at its foot

• point. 11

photon The photon γ is an elementary particle, the quantum of light and all other forms of electromag- netic radiation, and the mediator of the electromagnetic force, even when static via virtual photons. 11 12

proton The proton (symbol: p or p+) is a subatomic particle with one positive electric elementary

• charge. One or more protons are present in the nucleus of each atom. In the modern Standard

Model of particle physics, the proton is a hadron, composed of two up quarks and one down quark. 12, 13 quark A quark is an elementary particle and a fundamental constituent of matter. Quarks combine to form composite particles called hadrons, the most stable of which are protons and neutrons, the components of atomic nuclei. The quarks of the first generation are called “up” and “down”, those

• f the second generation are called “charm” and “strange”, and those of the third generation are

called “top” and “bottom” (or “beauty”). 11–13 Standard Model The Standard Model of particle physics is a theory concerning the electromagnetic, weak, and strong nuclear interactions, which mediate the dynamics of the known subatomic parti-

• cles. Because of its success in explaining a wide variety of experimental results, the Standard Model

is sometimes regarded as a “theory of almost everything”. However, the Standard Model falls short

• f being a complete theory of fundamental interactions because it makes certain simplifying as-
• sumptions. It does not incorporate the full theory of gravitation as described by general relativity,
• r predict the accelerating expansion of the universe (as possibly described by dark energy). It also

does not correctly account for neutrino oscillations (and their non-zero masses). 14 strong The strong interaction (or strong force) is the force that binds protons and neutrons (nucleons) together to form the nucleus of an atom. It furthermore is the force (carried by gluons) that holds quarks together to form protons, neutrons and other hadrons. 12 tau The tau particle (symbol: τ−) is a subatomic particle with a negative elementary charge. It is a lepton of the third generation of fundamental particles. 12 weak The weak interaction is responsible for the radioactive decay of subatomic particles and initiates the process known as hydrogen fusion in stars. Weak interactions affect all known fermions. It is mediated by the exchange of the Z, W+ and W− bosons. 12 13

Acronyms

KEK KEK (Ko Enerugi Kasokuki Kenkyu Kiko) is a japanese organization whose purpose is to operate the largest particle physics laboratory in Japan, which is located in Tsukuba (Ibaraki prefecture). 11 PXD PXD: PiXel Detector. 4 SM SM: Standard Model of particle physics. 12 US US: United States (of America). 3 14

References

[1] L

A

T EX package glossaries, URL https://www.ctan.org/pkg/glossaries. 4 [2] BibTeX, URL http://www.bibtex.org/. 4 [3] JabRef, an open source editor for BibTeX files, URL https://www.jabref.org/. 4 [4] latexmk – Fully automated L

A

T EX document generation, URL https://www.ctan.org/pkg/ latexmk/. 4 [5] Publication quality tables in L

A

T EX; package booktabs, URL https://www.ctan.org/pkg/booktabs. 4 [6] Bureau international des poids et mesures (BIPM), SI brochure (8th edition), Tech. rep., URL http: //www.bipm.org/en/si/si_brochure. 6 [7] Beccari, C., Typesetting mathematics for science technology according to ISO 31 XI, TUGboat, 18(1), URL http://www.tug.org/TUGboat/Articles/tb18-1/tb54becc.pdf. 6 [8] International Union of Pure and Applied Chemistry (IUPAC), Quantities, Units and Symbols in Physical Chemistry 3rd, Edition, Tech. rep., URL https://www.iupac.org/cms/wp-content/ uploads/2015/07/Green-Book-PDF-Version-2011.pdf. 6 [9] L

A

T EX package upgreek, URL https://www.ctan.org/pkg/upgreek. 7, 8 [10] L

A

T EX package siunitx, URL https://www.ctan.org/pkg/siunitx. 8 [11] L

A

T EX package bm, URL https://www.ctan.org/pkg/bm. 8 15