Debian Codegraph @

texmf-dist/source/latex/siunitx/siunitx.tex

raw
1 \iffalse meta-comment
2
3 File: siunitx.tex Copyright (C) 2014-2025 Joseph Wright
4
5 It may be distributed and/or modified under the conditions of the
6 LaTeX Project Public License (LPPL), either version 1.3c of this
7 license or (at your option) any later version. The latest version
8 of this license is in the file
9
10 https://www.latex-project.org/lppl.txt
11
12 This file is part of the "siunitx bundle" (The Work in LPPL)
13 and all files in that bundle must be distributed together.
14
15 The released version of this bundle is available from CTAN.
16
17 -----------------------------------------------------------------------
18
19 The development version of the bundle can be found at
20
21 https://github.com/josephwright/siunitx
22
23 for those people who are interested.
24
25 -----------------------------------------------------------------------
26
27 \fi
28
29 \DocumentMetadata{lang = en, pdfversion = 2.0}
30
31 \documentclass[a4paper]{l3doc}
32
33 % The next line is needed so that \GetFileInfo will be able to pick up
34 % version data (quite apart from making the demos work).
35 \usepackage{siunitx}
36 % So we can have 'sensible' demos for \arcsecond
37 \DeclareSIUnit\arcsecond{as}
38 \DeclareSIUnit[quantity-product = {}]\stdarcsecond{\ensuremath {{}''}}
39 \sisetup{angle-symbol-second = \stdarcsecond}
40 \DeclareSIUnit\noop{\relax} % For printing prefixes
41 \DeclareSIPower\quartic\tothefourth{4} % For demos
42 \DeclareSIUnit\KWH{kWh}
43 \DeclareSIQualifier\polymer{pol}
44 \DeclareSIQualifier\catalyst{cat}
45 \DeclareSIUnit\millimetremercury{mmHg}
46
47 % Commands for this document
48 \ExplSyntaxOn
49 \makeatletter
50 \NewDocumentCommand \acro { m }
51 {
52 \textsc
53 {
54 \exp_args:NV \tl_if_head_eq_charcode:nNTF \f@series { m }
55 { \text_lowercase:n }
56 { \use:n }
57 {#1}
58 }
59 }
60 \makeatother
61 \ExplSyntaxOff
62 \NewDocumentCommand\email{m}{\href{mailto:#1}{\nolinkurl{#1}}}
63 \NewDocumentCommand\ext{m}{\texttt{.#1}}
64 \NewDocumentCommand\foreign{m}{\textit{#1}}
65 \NewDocumentCommand\opt{m}{\texttt{#1}}
66 \NewDocumentCommand\version{m}{\ensuremath{#1}}
67 % Tidy up the above in bookmarks
68 \makeatletter
69 \pdfstringdefDisableCommands{%
70 \let\acro\@firstofone
71 \let\ext\@firstofone
72 \let\foreign\@firstofone
73 \let\opt\@firstofone
74 \let\version\@firstofone
75 }
76 \makeatother
77
78 \NewDocumentCommand\DescribePrefix{m}{%
79 #1 &
80 \cs{#1} &
81 \unit{\csname #1\endcsname\noop}
82 }
83 \NewDocumentCommand\DescribeUnit{O{#2}m}{%
84 #1 &
85 \cs{#2} &
86 \unit{\csname #2\endcsname}
87 }
88
89 % For demos
90 \usepackage[portuguese,brazilian,catalan,french,german,italian,polish,spanish,UKenglish]{babel}
91 \AtBeginDocument{\shorthandoff{<>}}
92 \usepackage{translations}
93 \usepackage{cancel}
94 \usepackage{collcell}
95 \usepackage{sansmath}
96 \usepackage{steinmetz}
97 \newlength{\mylength}
98
99 % For creating code demonstrations
100 % This needs access to some code-level interfaces in listings
101 \usepackage{listings}
102 \makeatletter
103 \lst@RequireAspects{writefile}
104 \newsavebox\LaTeXdemo@box
105 \lstnewenvironment{LaTeXdemo}[1][code and example]
106 {%
107 \global\let\lst@intname\@empty
108 \edef\LaTeXdemo@end{%
109 \expandafter\noexpand\csname LaTeXdemo@@#1@end\endcsname
110 }%
111 \@nameuse{LaTeXdemo@@#1}%
112 }
113 {\LaTeXdemo@end}
114 \newcommand\LaTeXdemo@new[3]{%
115 \@namedef{LaTeXdemo@@#1}{#2}%
116 \@namedef{LaTeXdemo@@#1@end}{#3}%
117 }
118 \newcommand*\LaTeXdemo@common{%
119 \setkeys{lst}
120 {%
121 basicstyle = \small\ttfamily,
122 basewidth = 0.51em,
123 gobble = 2,
124 language = [LaTeX]{TeX},
125 }%
126 }
127 \newcount\LaTeXdemo@count
128 \newcommand*\LaTeXdemo@input{%
129 \catcode`\^^M = 10\relax
130 \input{\jobname-\number\[email protected]}%
131 }
132 \LaTeXdemo@new{code and example}{%
133 \setbox\LaTeXdemo@box=\hbox\bgroup
134 \global\advance\LaTeXdemo@count by 1 %
135 \lst@BeginAlsoWriteFile{\jobname-\number\[email protected]}%
136 \LaTeXdemo@common
137 }{%
138 \lst@EndWriteFile
139 \egroup
140 \begin{center}
141 \ifdim\wd\LaTeXdemo@box > 0.48\linewidth
142 \begin{minipage}{\linewidth}
143 \usebox\LaTeXdemo@box
144 \end{minipage}%
145 \par
146 \begin{minipage}{\linewidth}
147 \LaTeXdemo@input
148 \end{minipage}
149 \else
150 \begin{minipage}{0.48\linewidth}
151 \LaTeXdemo@input
152 \end{minipage}%
153 \hspace{\fill}%
154 \begin{minipage}{0.48\linewidth}
155 \usebox\LaTeXdemo@box
156 \end{minipage}%
157 \fi
158 \end{center}
159 }
160 \LaTeXdemo@new{code and float}{%
161 \global\advance\LaTeXdemo@count by 1 %
162 \lst@BeginAlsoWriteFile{\jobname-\number\[email protected]}%
163 \LaTeXdemo@common
164 }{%
165 \lst@EndWriteFile
166 \LaTeXdemo@input
167 }
168 \LaTeXdemo@new{code only}{\LaTeXdemo@common}{}
169 \makeatother
170
171 % For table demos
172 \usepackage{datatool}
173 \usepackage{multirow}
174 \usepackage[table]{xcolor}
175 % Has to come after xcolor
176 \usepackage{pgfplots}
177 \pgfplotsset{compat = 1.18, compat/show suggested version = false}
178
179 % For the extra-long tables
180 \usepackage{xtab}
181
182 % For the table notes
183 \usepackage{threeparttable}
184
185 % Design changes
186 \usepackage{caption}
187 \makeatletter
188 \edef\@floatboxreset{%
189 \unexpanded\expandafter{\@floatboxreset}%
190 \noexpand\centering
191 }
192 \makeatother
193 %\usepackage[osf]{mathpazo}
194 \usepackage{fontspec}
195 \setmainfont[Numbers = OldStyle]{TeX Gyre Pagella}
196 \usepackage{unicode-math}
197 \setmathfont{TeX Gyre Pagella Math}
198
199 \hypersetup{hidelinks}
200
201 \begin{document}
202
203 \GetFileInfo{siunitx.sty}
204
205 \title{%
206 \pkg{siunitx} -- A comprehensive (\acro{SI}) units package%
207 \thanks{This file describes \fileversion,
208 last revised \filedate.}%
209 }
210
211 \author{%
212 Joseph Wright%
213 \thanks{%
214 E-mail:
215 \email{[email protected]}%
216 }%
217 }
218
219 \date{Released \filedate}
220
221 \maketitle
222
223 \tableofcontents
224
225 \begin{abstract}
226 Physical quantities have both numbers and units, and each physical quantity
227 should be expressed as the product of a number and a unit. Typesetting
228 physical quantities requires care to ensure that the combined mathematical
229 meaning of the number--unit combination is clear. In particular, the
230 \acro{SI} units system lays down a consistent set of units with rules on how
231 these are to be used. However, different countries and publishers have
232 differing conventions on the exact appearance of numbers (and units). The
233 \pkg{siunitx} package provides a set of tools for authors to typeset
234 quantities in a consistent way. The package has an extended set of
235 configuration options which make it possible to follow varying typographic
236 conventions with the same input syntax. The package includes automated
237 processing of numbers and units, and the ability to control tabular alignment
238 of numbers.
239 \end{abstract}
240
241 \begin{documentation}
242
243 \section{Introduction}
244
245 The correct application of units of measurement is very important in technical
246 applications. For this reason, carefully-crafted definitions of a coherent
247 units system have been laid down by the \foreign{Conférence Génrale des Poids
248 et Mesures} (\acro{CGPM}): this has resulted in the \foreign{Système
249 International d'Unités}~(\acro{SI}). At the same time, typographic conventions
250 for correctly displaying both numbers and units exist to ensure that no loss of
251 meaning occurs in printed matter.
252
253 The \pkg{siunitx} package aims to provide a unified method for \LaTeX{} users
254 to typeset numbers and units correctly and easily. The design philosophy of
255 \pkg{siunitx} is to follow the agreed rules by default, but to allow variation
256 through option settings. In this way, users can use \pkg{siunitx} to follow the
257 requirements of publishers, co-authors, universities, \foreign{etc}.\ without
258 needing to alter the input at all.
259
260 \section{\pkg{siunitx} for the impatient}
261
262 The package provides the user macros:
263 \begin{itemize}
264 \item \cs{ang}\oarg{options}\marg{angle}
265 \item \cs{duration}\oarg{options}\marg{duration}
266 \item \cs{num}\oarg{options}\marg{number}
267 \item \cs{unit}\oarg{options}\marg{unit}
268 \item \cs{qty}\oarg{options}\marg{number}\marg{unit}
269 \item \cs{numlist}\oarg{options}\marg{numbers}
270 \item \cs{numproduct}\oarg{options}\marg{numbers}
271 \item \cs{numrange}\oarg{options}\marg{numbers}\marg{number2}
272 \item \cs{qtylist}\oarg{options}\marg{numbers}\marg{unit}
273 \item \cs{qtyproduct}\oarg{options}\marg{numbers}\marg{unit}
274 \item \cs{qtyrange}\oarg{options}\marg{number1}\marg{number2}\marg{unit}
275 \item \cs{complexnum}\oarg{options}\marg{number}
276 \item \cs{complexqty}\oarg{options}\marg{number}\marg{unit}
277 \item \cs{sisetup}\marg{options}
278 \item \cs{tablenum}\oarg{options}\marg{number}
279 \end{itemize}
280 plus the \texttt{S} column type for decimal alignments and units in tabular
281 environments. These user macros and column types are designed for typesetting
282 numbers and units with control of appearance and with intelligent processing.
283
284 Numbers are processed with understanding of exponents, or using additional
285 commands for products and complex numbers.
286 \begin{LaTeXdemo}
287 \num{12345,67890} \\
288 \num{.3e45} \\
289 \complexnum{1+-2i} \\
290 \numproduct{1.654 x 2.34 x 3.430}
291 \end{LaTeXdemo}
292
293 The unit system can interpret units given as text to be used directly or as
294 macro-based units. In the latter case, different formatting is possible.
295 \begin{LaTeXdemo}
296 \unit{kg.m.s^{-1}} \\
297 \unit{\kilogram\metre\per\second} \\
298 \unit[per-mode = symbol]
299 {\kilogram\metre\per\second} \\
300 \unit[per-mode = symbol]
301 {\kilogram\metre\per\ampere\per\second}
302 \end{LaTeXdemo}
303
304 Simple lists and ranges of numbers can be handled.
305 \begin{LaTeXdemo}
306 \numlist{10;20;30} \\
307 \qtylist{0.13;0.67;0.80}{\milli\metre} \\
308 \numrange{10}{20} \\
309 \qtyrange{0.13}{0.67}{\milli\metre}
310 \end{LaTeXdemo}
311
312 A wide range of options are available to control the behavior of the package.
313 For example, with the standard settings all text is typeset in the current
314 upright math font. This can be adjusted to use text mode, follow various
315 aspects of the surrounding formatting, \foreign{etc}. Similarly, the standard
316 settings are based around an English-speaking locale, but can be adjusted
317 to follow the traditions of other areas.
318
319 \section{Using the \pkg{siunitx} package}
320
321 \subsection{Numbers}
322
323 \begin{function}{\num}
324 \begin{syntax}
325 \cs{num}\oarg{options}\marg{number}
326 \end{syntax}
327 \end{function}
328 Numbers are automatically formatted by the \cs{num} macro. This takes one
329 optional argument, \meta{options}, and one mandatory one, \meta{number}. The
330 contents of \meta{number} are automatically formatted. The formatter removes
331 both \enquote{soft} (\verb*| |) and \enquote{hard} spaces (|\,| and |~|),
332 automatically identifies exponents (as standard marked using |e|, |E|, |d| or
333 |D|) and adds the appropriate spacing of large numbers. If required,
334 a leading zero is added before a decimal marker: both |.|
335 and "," are recognised as decimal markers.
336 \begin{LaTeXdemo}
337 \num{123} \\
338 \num{1234} \\
339 \num{12345} \\
340 \num{0.123} \\
341 \num{0,1234} \\
342 \num{.12345} \\
343 \num{3.45d-4} \\
344 \num{-e10}
345 \end{LaTeXdemo}
346
347 Note that numbers are parsed before typesetting, which does have a performance
348 overhead (only obvious with very large amounts of numerical input). The parser
349 understands a range of input syntaxes, as demonstrated above.
350
351 \begin{function}{\numlist}
352 \begin{syntax}
353 \cs{numlist}\oarg{options}\marg{numbers}
354 \end{syntax}
355 \end{function}
356 Lists of numbers may be processed using the \cs{numlist} function. Each
357 \meta{number} is given within the list of \meta{numbers} within a brace pair,
358 as the list can have a flexible length.
359 \begin{LaTeXdemo}
360 \numlist{10;30;50;70}
361 \end{LaTeXdemo}
362
363 \begin{function}{\numproduct}
364 \begin{syntax}
365 \cs{numproduct}\oarg{options}\marg{numbers}
366 \end{syntax}
367 \end{function}
368 Runs of products of numbers may be inserted using the \cs{numproduct} function.
369 This acts in the same way as \cs{num}, but inserts either a symbol or phrase
370 between the entries. The latter should be separated by |x| tokens.
371 \begin{LaTeXdemo}
372 \numproduct{10 x 30}
373 \end{LaTeXdemo}
374
375 \begin{function}{\numrange}
376 \begin{syntax}
377 \cs{numrange}\oarg{options}\marg{number1}\marg{number2}
378 \end{syntax}
379 \end{function}
380 Simple ranges of numbers can be handled using the \cs{numrange} function. This
381 acts in the same way as \cs{num}, but inserts a phrase or other text between
382 the two entries.
383 \begin{LaTeXdemo}
384 \numrange{10}{30}
385 \end{LaTeXdemo}
386
387 \subsection{Angles}
388
389 \begin{function}{\ang}
390 \begin{syntax}
391 \cs{ang}\oarg{options}\marg{angle}
392 \end{syntax}
393 \end{function}
394 Angles can be typeset using the \cs{ang} command. The \meta{angle} can be given
395 either as a decimal number or as a semi-colon separated list of degrees,
396 minutes and seconds, which is called \enquote{arc format} in this document. The
397 numbers which make up an angle are processed using the same system as other
398 numbers. However, no unit prefixes are applied here: as such, conversion from
399 exponent form to unit prefixes does not apply.
400 \begin{LaTeXdemo}
401 \ang{10} \\
402 \ang{12.3} \\
403 \ang{4,5} \\
404 \ang{1;2;3} \\
405 \ang{;;1} \\
406 \ang{+10;;} \\
407 \ang{-0;1;}
408 \end{LaTeXdemo}
409
410 \subsection{Durations}
411
412 \begin{function}{\duration}
413 \begin{syntax}
414 \cs{duration}\oarg{options}\marg{angle}
415 \end{syntax}
416 \end{function}
417 Durations (of hours, minutes and seconds) can be typeset using the
418 \cs{duration} command. The \meta{duration} can be given either as a decimal
419 number or as a semi-colon separated list of hours, minutes and seconds, which
420 is called \enquote{component format} in this document. The numbers which make
421 up a duration are processed using the same system as other numbers. However, no
422 unit prefixes are applied here: as such, conversion from exponent form to unit
423 prefixes does not apply.
424 \begin{LaTeXdemo}
425 \duration{10} \\
426 \duration{12.3} \\
427 \duration{4,5} \\
428 \duration{1;2;3} \\
429 \duration{;;1} \\
430 \duration{+10;;} \\
431 \duration{-0;1;}
432 \end{LaTeXdemo}
433
434 \subsection{Units}
435
436 \begin{function}{\unit}
437 \begin{syntax}
438 \cs{unit}\oarg{options}\marg{unit}
439 \end{syntax}
440 \end{function}
441 The symbol for a unit can be typeset using the \cs{unit} macro: this provides
442 full control over output format for the unit. Like the \cs{num} macro,
443 \cs{unit} takes one optional and one mandatory argument. The unit formatting
444 system can accept two types of input. When the \meta{unit} contains literal
445 items (for example letters or numbers) then \pkg{siunitx} converts |.| and |~|
446 into inter-unit product and correctly positions sub- and superscripts specified
447 using |_| and |^|. The formatting methods will work with both math and text
448 mode.
449 \begin{LaTeXdemo}
450 \unit{kg.m/s^2} \\
451 \unit{g_{polymer}~mol_{cat}.s^{-1}}
452 \end{LaTeXdemo}
453
454 The second operation mode for the \cs{unit} macro is an \enquote{interpreted}
455 system. Here each unit, \acro{SI} multiple prefix and power is given a macro
456 name. These are entered in a method very similar to the reading of the unit
457 name in English.
458 \begin{LaTeXdemo}
459 \unit{\kilo\gram\metre\per\square\second} \\
460 \unit{\gram\per\cubic\centi\metre} \\
461 \unit{\square\volt\cubic\lumen\per\farad} \\
462 \unit{\metre\squared\per\gray\cubic\lux} \\
463 \unit{\henry\second}
464 \end{LaTeXdemo}
465
466 On its own, this is less convenient than the direct method, although it does
467 use meaning rather than appearance for input. However, the package allows you
468 to define new unit macros; a large number of pre-defined abbreviations are also
469 supplied. More importantly, by defining macros for units, instead of literal
470 input, new functionality is made available. By altering the settings used by
471 the package, the same input can yield a variety of different output formats.
472 For example, the \cs{per} macro can give reciprocal powers, slashes or be used
473 to construct units as fractions.
474
475 \begin{function}{\qty}
476 \begin{syntax}
477 \cs{qty}\oarg{options}\marg{number}\marg{unit}
478 \end{syntax}
479 \end{function}
480 Very often, numbers and units are given together. Formally, the value of a
481 quantity is the product of the number and the unit, the space being regarded as
482 a multiplication sign. The \cs{qty} macro combines the
483 functionality of \cs{num} and \cs{unit}, and makes this both possible and easy.
484 The \meta{number} and \meta{unit} arguments work exactly like those for the
485 \cs{num} and \cs{unit} macros, respectively.
486 \begin{LaTeXdemo}
487 \qty[mode = text]{1.23}{J.mol^{-1}.K^{-1}} \\
488 \qty{.23e7}{\candela} \\
489 \qty[per-mode = symbol]{1.99}{\per\kilogram} \\
490 \qty[per-mode = fraction]{1,345}{\coulomb\per\mole}
491 \end{LaTeXdemo}
492
493 It is possible to set up the unit macros to be available outside of the
494 \cs{qty} and \cs{unit} functions. This is not the standard behavior as there is
495 the risk of name clashes (for example, \cs{day} is a \TeX{} primitive and
496 several packages define \cs{degree}). Full details of using \enquote{stand
497 alone} units are found in \ref{sec:units:creating}.
498
499 \begin{function}{\qtylist}
500 \begin{syntax}
501 \cs{qtylist}\oarg{options}\marg{numbers}\marg{unit}
502 \end{syntax}
503 \end{function}
504 Lists of numbers with units can be handled using the \cs{qtylist} function. The
505 behavior of this function is similar to \cs{numlist}, but with the addition of
506 the unit to each number.
507 \begin{LaTeXdemo}
508 \qtylist{10;30;45}{\metre}
509 \end{LaTeXdemo}
510
511 \begin{function}{\qtyproduct}
512 \begin{syntax}
513 \cs{qtyproduct}\oarg{options}\marg{numbers}\marg{unit}
514 \end{syntax}
515 \end{function}
516 Runs of products of numbers with units can be handled using the \cs{qtyproduct}
517 function. The behavior of this function is similar to \cs{numproduct}, but with
518 the addition of a unit to each number.
519 \begin{LaTeXdemo}
520 \qtyproduct{10 x 30 x 45}{\metre}
521 \end{LaTeXdemo}
522
523 \begin{function}{\qtyrange}
524 \begin{syntax}
525 \cs{qtyrange}\oarg{options}\marg{number1}\marg{number2}\marg{unit}
526 \end{syntax}
527 \end{function}
528 Ranges of numbers with units can be handled using the \cs{qtyrange} function.
529 The behavior of this function is similar to \cs{numrange}, but with the
530 addition of a unit to each number.
531 \begin{LaTeXdemo}
532 \qtyrange{10}{30}{\metre}
533 \end{LaTeXdemo}
534
535 The input of lists, products and ranges of quantities using a single command
536 allows them to be adjusted together. These commands are intended to allow
537 consistent formatting of related values: as such, they apply a single
538 unit to all of the values. This is particularly notable when using
539 adjustment of the numerical values.
540
541 \subsection{Complex numbers and quantities}
542
543 \begin{function}{\complexnum}
544 \begin{syntax}
545 \cs{complexnum}\oarg{options}\marg{number}
546 \end{syntax}
547 \end{function}
548 Typesets the complex number, which can be given in the Cartesian form $a +
549 b\mathrm{i}$ or $a + \mathrm{i}b$, or in the polar form $r$\texttt{:}$\theta$.
550 Processing of the numerical parts is otherwise identical to the standard
551 \cs{num} command.
552
553 \begin{function}{\complexqty}
554 \begin{syntax}
555 \cs{complexqty}\oarg{options}\marg{number}\marg{unit}
556 \end{syntax}
557 \end{function}
558 Typesets the complex number, which can be given in the Cartesian form $a +
559 b\mathrm{i}$ or $a + \mathrm{i}b$, or in the polar form $r$\texttt{:}$\theta$.
560 Processing of the numerical parts is otherwise identical to the standard
561 \cs{qty} command.
562
563 \subsection{The unit macros}
564
565 The package always defines the basic set of \acro{SI} units with macro names.
566 This includes the base \acro{SI} units, the derived units with special names
567 and the prefixes. A small number of powers are also given pre-defined names.
568 Full details of units in the \acro{SI} are available on-line~\cite{BIPM}.
569
570 The seven base \acro{SI} units are always defined (Table~\ref{tab:unit:base}).
571 In addition, the macro \cs{meter} is available as an alias for \cs{metre}, for
572 users of US spellings. The full details of the base units are given in the
573 \acro{SI} Brochure.
574 \begin{table}
575 \caption{\acro{SI} base units.%
576 \label{tab:unit:base}}
577 \begin{tabular}{@{}lll@{}}
578 \toprule
579 Unit & Command & Symbol \\
580 \midrule
581 \DescribeUnit{ampere} \\
582 \DescribeUnit{candela} \\
583 \DescribeUnit{kelvin} \\
584 \DescribeUnit{kilogram} \\
585 \DescribeUnit{metre} \\
586 \DescribeUnit{mole} \\
587 \DescribeUnit{second} \\
588 \bottomrule
589 \end{tabular}
590 \end{table}
591
592 The \acro{SI} also lists a number of units which have special names and
593 symbols: these are listed in Table~\ref{tab:unit:derived}.
594 \begin{table}
595 \caption{Coherent derived units in the \acro{SI} with special names and
596 symbols.%
597 \label{tab:unit:derived}}
598 \begin{tabular}{@{}lll>{\qquad}lll@{}}
599 \toprule
600 Unit & Command & Symbol & Unit & Command & Symbol \\
601 \midrule
602 \DescribeUnit{becquerel} &
603 \DescribeUnit{newton} \\
604 \DescribeUnit[degree Celsius]{degreeCelsius} &
605 \DescribeUnit{ohm} \\
606 \DescribeUnit{coulomb} &
607 \DescribeUnit{pascal} \\
608 \DescribeUnit{farad} &
609 \DescribeUnit{radian} \\
610 \DescribeUnit{gray} &
611 \DescribeUnit{siemens} \\
612 \DescribeUnit{hertz} &
613 \DescribeUnit{sievert} \\
614 \DescribeUnit{henry} &
615 \DescribeUnit{steradian} \\
616 \DescribeUnit{joule} &
617 \DescribeUnit{tesla} \\
618 \DescribeUnit{lumen} &
619 \DescribeUnit{volt} \\
620 \DescribeUnit{katal} &
621 \DescribeUnit{watt} \\
622 \DescribeUnit{lux} &
623 \DescribeUnit{weber} \\
624 \bottomrule
625 \end{tabular}
626 \end{table}
627
628 In addition to the official \acro{SI} units, \pkg{siunitx} also provides macros
629 for a number of units which are accepted for use in the \acro{SI} although they
630 are not \acro{SI} units. Table~\ref{tab:unit:accepted} lists the
631 \enquote{accepted} units. The command \cs{percent} is also provided for use in
632 units: this is accepted with the \acro{SI} as detailed in Section~5.4.7 of the
633 Brochure.
634 \begin{table}
635 \caption{Non-\acro{SI} units accepted for use with the International System of
636 Units.%
637 \label{tab:unit:accepted}}
638 \begin{tabular}{@{}lll@{}}
639 \toprule
640 Unit & Command & Symbol \\
641 \midrule
642 \DescribeUnit[astronomical unit]{astronomicalunit} \\
643 \DescribeUnit{bel} \\
644 \DescribeUnit{dalton} \\
645 \DescribeUnit{day} \\
646 \DescribeUnit{decibel} \\
647 \DescribeUnit{degree} \\
648 \DescribeUnit{electronvolt} \\
649 \DescribeUnit{hectare} \\
650 \DescribeUnit{hour} \\
651 \DescribeUnit{litre} \\
652 & \cs{liter} & \unit{\liter} \\
653 \DescribeUnit[minute (plane angle)]{arcminute} \\
654 \DescribeUnit[minute (time)]{minute} \\
655 second (plane angle) & \cs{arcsecond} & \unit{\stdarcsecond} \\
656 \DescribeUnit{neper} \\
657 \DescribeUnit{tonne} \\
658 \bottomrule
659 \end{tabular}
660 \end{table}
661
662 In addition to the units themselves, \pkg{siunitx} provides pre-defined macros
663 for all of the \acro{SI} prefixes (Table~\ref{tab:unit:prefix}).
664 The spelling \enquote{\cs{deka}} is provided for US users as an alternative to
665 \cs{deca}.
666 \begin{table}
667 \caption{SI prefixes.%
668 \label{tab:unit:prefix}}
669 \sisetup{table-number-alignment = right, table-format = 2}
670 \begin{tabular}{@{}llcS[table-format = -2]>{\qquad}llcS@{}}
671 \toprule
672 Prefix & Command & Symbol & \multicolumn{1}{l}{Power} &
673 Prefix & Command & Symbol & \multicolumn{1}{l@{}}{Power} \\
674 \midrule
675 \DescribePrefix{quecto} & -30 &
676 \DescribePrefix{deca} & 1 \\
677 \DescribePrefix{ronto} & -27 &
678 \DescribePrefix{hecto} & 2 \\
679 \DescribePrefix{yocto} & -24 &
680 \DescribePrefix{kilo} & 3 \\
681 \DescribePrefix{zepto} & -21 &
682 \DescribePrefix{mega} & 6 \\
683 \DescribePrefix{atto} & -18 &
684 \DescribePrefix{giga} & 9 \\
685 \DescribePrefix{femto} & -15 &
686 \DescribePrefix{tera} & 12 \\
687 \DescribePrefix{pico} & -12 &
688 \DescribePrefix{peta} & 15 \\
689 \DescribePrefix{nano} & -9 &
690 \DescribePrefix{exa} & 18 \\
691 \DescribePrefix{micro} & -6 &
692 \DescribePrefix{zetta} & 21 \\
693 \DescribePrefix{milli} & -3 &
694 \DescribePrefix{yotta} & 24 \\
695 \DescribePrefix{centi} & -2 &
696 \DescribePrefix{ronna} & 27 \\
697 \DescribePrefix{deci} & -1 &
698 \DescribePrefix{quetta} & 30 \\
699 \bottomrule
700 \end{tabular}
701 \end{table}
702
703 A small number of pre-defined powers are provided as macros. \cs{square} and
704 \cs{cubic} are intended for use before units, with \cs{squared} and \cs{cubed}
705 going after the unit.
706 \begin{LaTeXdemo}
707 \unit{\square\becquerel} \\
708 \unit{\joule\squared\per\lumen} \\
709 \unit{\cubic\lux\volt\tesla\cubed}
710 \end{LaTeXdemo}
711 Generic powers can be inserted on a one-off basis using the \cs{tothe} and
712 \cs{raiseto} macros. These are the only macros for units which take an
713 argument:
714 \begin{LaTeXdemo}
715 \unit{\henry\tothe{5}} \\
716 \unit{\raiseto{4.5}\radian}
717 \end{LaTeXdemo}
718 Reciprocal powers are indicated using the \cs{per} macro. This applies to the
719 next unit only, unless the \opt{sticky-per} option is turned on.
720 \begin{LaTeXdemo}
721 \unit{\joule\per\mole\per\kelvin} \\
722 \unit{\joule\per\mole\kelvin} \\
723 \unit{\per\henry\tothe{5}} \\
724 \unit{\per\square\becquerel}
725 \end{LaTeXdemo}
726 As for generic powers, generic qualifiers are also available using the \cs{of}
727 function:
728 \begin{LaTeXdemo}
729 \unit{\kilogram\of{metal}} \\
730 \qty[qualifier-mode = bracket]
731 {0.1}{\milli\mole\of{cat}\per\kilogram\of{prod}}
732 \end{LaTeXdemo}
733
734 When the \pkg{cancel} package is loaded, it is possible to \enquote{cancel out}
735 units using the \cs{cancel} macro. This applies to the next unit, in a similar
736 manner to a prefix. The \cs{highlight} macro is also available to selectively
737 color units. Both \cs{cancel} and \cs{highlight} are outside of the normal
738 semantic meaning of units, but are provided as they may be useful in some
739 cases.
740 \begin{LaTeXdemo}
741 \unit[per-mode = fraction]
742 {\cancel\kilogram\metre\per\cancel\kilogram\per\second} \\
743 \unit{\highlight{red}\kilogram\metre\per\second} \\
744 \unit[unit-color = purple]
745 {\highlight{blue}\kilogram\metre\per\second}
746 \end{LaTeXdemo}
747
748 \subsection{Unit abbreviations}
749
750 In addition to the \enquote{full} names, \pkg{siunitx} loads a set of
751 abbreviated versions of the \acro{SI} units (Table~\ref{tab:unit:abbr}). The
752 standard \pkg{siunitx} settings only create these abbreviations within the
753 scope of the \cs{unit} and \cs{qty} functions, meaning that no clashes should
754 occur (for example with the standard \cs{pm} symbol).
755 \begin{center}
756 \tablecaption{Unit abbreviations}
757 \label{tab:unit:abbr}
758 \tablefirsthead{%
759 \toprule
760 \multicolumn{1}{@{}l}{Unit} &
761 \multicolumn{1}{l}{Abbreviation} &
762 \multicolumn{1}{l@{}}{Symbol} \\
763 \midrule
764 }
765 \tablehead{%
766 \multicolumn{3}{@{}l@{}}{\emph{Continued from previous page}} \\
767 \toprule
768 \multicolumn{1}{@{}l}{Unit} &
769 \multicolumn{1}{l}{Abbreviation} &
770 \multicolumn{1}{l@{}}{Symbol} \\
771 \midrule
772 }
773 \tabletail{%
774 \bottomrule
775 \multicolumn{3}{@{}r@{}}{\emph{Continued on next page}} \\
776 }
777 \tablelasttail{\bottomrule}
778 \begin{xtabular}{@{}lcc@{}}
779 \DescribeUnit[femtogram]{fg} \\
780 \DescribeUnit[picogram]{pg} \\
781 \DescribeUnit[nanogram]{ng} \\
782 \DescribeUnit[microgram]{ug} \\
783 \DescribeUnit[milligram]{mg} \\
784 \DescribeUnit[gram]{g} \\
785 \DescribeUnit[kilogram]{kg} \\
786
787 \midrule
788
789 \DescribeUnit[picometre]{pm} \\
790 \DescribeUnit[nanometre]{nm} \\
791 \DescribeUnit[micrometre]{um} \\
792 \DescribeUnit[millimetre]{mm} \\
793 \DescribeUnit[centimetre]{cm} \\
794 \DescribeUnit[decimetre]{dm} \\
795 \DescribeUnit[metre]{m} \\
796 \DescribeUnit[kilometre]{km} \\
797
798 \midrule
799
800 \DescribeUnit[attosecond]{as} \\
801 \DescribeUnit[femtosecond]{fs} \\
802 \DescribeUnit[picosecond]{ps} \\
803 \DescribeUnit[nanosecond]{ns} \\
804 \DescribeUnit[microsecond]{us} \\
805 \DescribeUnit[millisecond]{ms} \\
806 \DescribeUnit[second]{s} \\
807
808 \midrule
809
810 \DescribeUnit[femtomole]{fmol} \\
811 \DescribeUnit[picomole]{pmol} \\
812 \DescribeUnit[nanomole]{nmol} \\
813 \DescribeUnit[micromole]{umol} \\
814 \DescribeUnit[millimole]{mmol} \\
815 \DescribeUnit[mole]{mol} \\
816 \DescribeUnit[kilomole]{kmol} \\
817
818 \midrule
819
820 \DescribeUnit[picoampere]{pA} \\
821 \DescribeUnit[nanoampere]{nA} \\
822 \DescribeUnit[microampere]{uA} \\
823 \DescribeUnit[milliampere]{mA} \\
824 \DescribeUnit[ampere]{A} \\
825 \DescribeUnit[kiloampere]{kA} \\
826
827 \midrule
828
829 \DescribeUnit[microlitre]{ul} \\
830 \DescribeUnit[millilitre]{ml} \\
831 \DescribeUnit[litre]{l} \\
832 \DescribeUnit[hectolitre]{hl} \\
833 \DescribeUnit[microliter]{uL} \\
834 \DescribeUnit[milliliter]{mL} \\
835 \DescribeUnit[liter]{L} \\
836 \DescribeUnit[hectoliter]{hL} \\
837
838 \midrule
839
840 \DescribeUnit[millihertz]{mHz} \\
841 \DescribeUnit[hertz]{Hz} \\
842 \DescribeUnit[kilohertz]{kHz} \\
843 \DescribeUnit[megahertz]{MHz} \\
844 \DescribeUnit[gigahertz]{GHz} \\
845 \DescribeUnit[terahertz]{THz} \\
846
847 \midrule
848
849 \DescribeUnit[millinewton]{mN} \\
850 \DescribeUnit[newton]{N} \\
851 \DescribeUnit[kilonewton]{kN} \\
852 \DescribeUnit[meganewton]{MN} \\
853
854 \midrule
855
856 \DescribeUnit[pascal]{Pa} \\
857 \DescribeUnit[kilopascal]{kPa} \\
858 \DescribeUnit[megapacal]{MPa} \\
859 \DescribeUnit[gigapascal]{GPa} \\
860
861 \midrule
862
863 \DescribeUnit[milliohm]{mohm} \\
864 \DescribeUnit[kilohm]{kohm} \\
865 \DescribeUnit[megohm]{Mohm} \\
866
867 \midrule
868
869 \DescribeUnit[picovolt]{pV} \\
870 \DescribeUnit[nanovolt]{nV} \\
871 \DescribeUnit[microvolt]{uV} \\
872 \DescribeUnit[millivolt]{mV} \\
873 \DescribeUnit[volt]{V} \\
874 \DescribeUnit[kilovolt]{kV} \\
875
876 \midrule
877
878 \DescribeUnit[watt]{W} \\
879 \DescribeUnit[nanowatt]{nW} \\
880 \DescribeUnit[microwatt]{uW} \\
881 \DescribeUnit[milliwatt]{mW} \\
882 \DescribeUnit[kilowatt]{kW} \\
883 \DescribeUnit[megawatt]{MW} \\
884 \DescribeUnit[gigawatt]{GW} \\
885 \DescribeUnit[joule]{J} \\
886 \DescribeUnit[microjoule]{uJ} \\
887 \DescribeUnit[millijoule]{mJ} \\
888 \DescribeUnit[kilojoule]{kJ} \\
889 \DescribeUnit[electronvolt]{eV} \\
890 \DescribeUnit[millielectronvolt]{meV} \\
891 \DescribeUnit[kiloelectronvolt]{keV} \\
892 \DescribeUnit[megaelectronvolt]{MeV} \\
893 \DescribeUnit[gigaelectronvolt]{GeV} \\
894 \DescribeUnit[teraelectronvolt]{TeV} \\
895 \DescribeUnit[kilowatt hour]{kWh} \\
896
897 \midrule
898
899 \DescribeUnit[farad]{F} \\
900 \DescribeUnit[femtofarad]{fF} \\
901 \DescribeUnit[picofarad]{pF} \\
902 \DescribeUnit[nanofarad]{nF} \\
903 \DescribeUnit[microfarad]{uF} \\
904 \DescribeUnit[millifarad]{mF} \\
905
906 \midrule
907
908 \DescribeUnit[henry]{H} \\
909 \DescribeUnit[femtohenry]{fH} \\
910 \DescribeUnit[picohenry]{pH} \\
911 \DescribeUnit[nanohenry]{nH} \\
912 \DescribeUnit[millihenry]{mH} \\
913 \DescribeUnit[microhenry]{uH} \\
914
915 \midrule
916
917 \DescribeUnit[coulomb]{C} \\
918 \DescribeUnit[nanocoulomb]{nC} \\
919 \DescribeUnit[millicoulomb]{mC} \\
920 \DescribeUnit[microcoulomb]{uC} \\
921
922 \midrule
923
924 \DescribeUnit[tesla]{T} \\
925 \DescribeUnit[millitesla]{mT} \\
926 \DescribeUnit[microtesla]{uT} \\
927
928 \midrule
929
930 \DescribeUnit[kelvin]{K} \\
931
932 \midrule
933
934 \DescribeUnit[decibel]{dB} \\
935
936 \end{xtabular}
937 \end{center}
938
939 \DescribeMacro{bit}
940 \DescribeMacro{byte}
941 Binary data is expressed in units of bits and bytes. These are normally given
942 prefixes which use powers of two, rather than the powers of ten used by the
943 \acro{SI} prefixes. As these binary prefixes are closely related to the
944 \acro{SI} prefixes, they are defined by \pkg{siunitx}.
945 \begin{table}
946 \caption{Binary prefixes.%
947 \label{tab:unit:binary}}
948 \sisetup{table-number-alignment = right, table-format = 2}
949 \begin{tabular}{@{}llcS@{}}
950 \toprule
951 Prefix & Command & Symbol & \multicolumn{1}{l@{}}{Power} \\ \\
952 \midrule
953 \DescribePrefix{kibi} & 10 \\
954 \DescribePrefix{mebi} & 20 \\
955 \DescribePrefix{gibi} & 30 \\
956 \DescribePrefix{tebi} & 40 \\
957 \DescribePrefix{pebi} & 50 \\
958 \DescribePrefix{exbi} & 60 \\
959 \DescribePrefix{zebi} & 70 \\
960 \DescribePrefix{yobi} & 80 \\
961 \bottomrule
962 \end{tabular}
963 \end{table}
964
965 \subsection{Creating new macros}
966
967 The various macro components of a unit have to be defined before they can be
968 used. The package supplies a number of common definitions, but new definitions
969 are also possible. As the definition of a logical unit should remain the same
970 in a single document, these creation functions are all preamble-only.
971
972 \begin{function}{\DeclareSIUnit}
973 \begin{syntax}
974 \cs{DeclareSIUnit}\oarg{options}\marg{unit}\marg{symbol}
975 \end{syntax}
976 \end{function}
977 New units are produced using the \cs{DeclareSIUnit} macro. The \meta{symbol}
978 can contain literal input, other units, multiple prefixes, powers and \cs{per},
979 although literal text should not be intermixed with unit macros. Units can be
980 created with \meta{options} from the usual list understood by \pkg{siunitx},
981 and apply the specific unit macro only. The (first) optional argument to
982 \cs{qty} and \cs{unit} can be used to override the settings for the unit: an
983 example is the \cs{degree} unit.
984 \begin{LaTeXdemo}
985 \qty{3.1415}{\degree}
986 \end{LaTeXdemo}
987 This is declared in the package (effectively) as
988 \begin{LaTeXdemo}[code only]
989 \DeclareSIUnit[quantity-product = {}]
990 \degree{\text{\textdegree}}
991 \end{LaTeXdemo}
992 The spacing can still be altered at point of use:
993 \begin{LaTeXdemo}
994 \qty{67890}{\degree} \\
995 \qty[quantity-product = \,]{67890}{\degree}
996 \end{LaTeXdemo}
997 The meaning of a pre-defined unit can be altered by using \cs{DeclareSIUnit}
998 after loading \pkg{siunitx}. This will overwrite the original definition with
999 the newer version.
1000
1001 \begin{function}{\DeclareSIPrefix}
1002 \begin{syntax}
1003 \cs{DeclareSIPrefix}\marg{prefix}\marg{symbol}\marg{powers-ten}
1004 \end{syntax}
1005 \end{function}
1006 The standard \acro{SI} powers of ten are defined by the package, and are
1007 described above. However, the user can define new prefixes with
1008 \cs{DeclareSIPrefix}. For example, \cs{kilo} is defined
1009 \begin{LaTeXdemo}[code only]
1010 \DeclareSIPrefix\kilo{k}{3}
1011 \end{LaTeXdemo}
1012
1013 \begin{function}{\DeclareSIPower}
1014 \begin{syntax}
1015 \cs{DeclareSIPower}\marg{symbol-before}\marg{symbol-after}\marg{power}
1016 \end{syntax}
1017 \end{function}
1018 This function creates two symbols, one for use before a unit, the second
1019 for use after a unit, both of which are equivalent to the \meta{power}.
1020 For example, one might use
1021 \begin{LaTeXdemo}[code only]
1022 \DeclareSIPower\quartic\tothefourth{4}
1023 \end{LaTeXdemo}
1024 with the functions then used in the document as
1025 \begin{LaTeXdemo}
1026 \unit{\kilogram\tothefourth}\\
1027 \unit{\quartic\metre}
1028 \end{LaTeXdemo}
1029
1030 \begin{function}{\DeclareSIQualifier}
1031 \begin{syntax}
1032 \cs{DeclareSIQualifier}\marg{qualifier}\marg{symbol}
1033 \end{syntax}
1034 \end{function}
1035 Following the syntax of the other macros, qualifiers may be created using the
1036 \cs{DeclareSIQualifier} command. In contrast to the other parts of a unit,
1037 there are no pre-defined qualifiers. It is therefore entirely up to the user to
1038 create these. For example, to identify the mass of a product created when using
1039 a particular catalyst, the preamble could contain:
1040 \begin{LaTeXdemo}[code only]
1041 \DeclareSIQualifier\polymer{pol}
1042 \DeclareSIQualifier\catalyst{cat}
1043 \end{LaTeXdemo}
1044 and then in the body the document could read
1045 \begin{LaTeXdemo}
1046 \qty{1.234}{\gram\polymer\per\mole\catalyst\per\hour}
1047 \end{LaTeXdemo}
1048
1049 \subsection{Tabular material}
1050
1051 Aligning numbers in tabular content is handled by a new column type, the
1052 \texttt{S} column. This new column type can align material using a number of
1053 different strategies, with the aim of flexibility of output without needing to
1054 alter the input. The method used as standard is to place the decimal marker in
1055 the number at the center of the cell and to align the material appropriately
1056 (Table~\ref{tab:S:standard}).
1057 \begin{LaTeXdemo}[code and float]
1058 \begin{table}
1059 \caption{Standard behavior of the \texttt{S} column type.%
1060 \label{tab:S:standard}}
1061 \begin{tabular}{@{}S@{}}
1062 \toprule
1063 {Some Values} \\
1064 \midrule
1065 2.3456 \\
1066 34.2345 \\
1067 -6.7835 \\
1068 90.473 \\
1069 5642.5 \\
1070 1.2e3 \\
1071 e4 \\
1072 \bottomrule
1073 \end{tabular}
1074 \end{table}
1075 \end{LaTeXdemo}
1076
1077 The \texttt{S} column will attempt to automatically detect material which
1078 should be placed before or after a number, and will maintain the alignment of
1079 the numerical data (Table~\ref{tab:S:extras}). If the material could be
1080 mistaken for part of a number, it should be protected by braces. The use of
1081 \cs{color} in a table cell will also be detected and will override any general
1082 color applied by \pkg{siunitx}.
1083 \begin{LaTeXdemo}[code and float]
1084 \begin{table}
1085 \caption{Detection of surrounding material in an \texttt{S} column.%
1086 \label{tab:S:extras}}
1087 \begin{tabular}{@{}S@{}}
1088 \toprule
1089 {Some Values} \\
1090 \midrule
1091 12.34 \\
1092 \color{purple} 975,31 \\
1093 44.268 \textsuperscript{\emph{a}} \\
1094 \bottomrule
1095 \end{tabular}
1096 \end{table}
1097 \end{LaTeXdemo}
1098
1099 \begin{function}{\tablenum}
1100 \begin{syntax}
1101 \cs{tablenum}\oarg{options}\marg{number}
1102 \end{syntax}
1103 \end{function}
1104 Within more complex tables, aligned numbers may be desirable within the
1105 argument of \cs{multicolumn} or \cs{multirow}.\footnote{Provided by the
1106 \pkg{multirow} package} The \cs{tablenum} function is available to achieve
1107 alignment in these situations: this is, in effect, a macro version of the
1108 \texttt{S} column (Table~\ref{tab:tablenum}).
1109 \begin{LaTeXdemo}[code and float]
1110 \begin{table}
1111 \caption{Controlling complex alignment with the \cs{tablenum} macro.%
1112 \label{tab:tablenum}}
1113 \begin{tabular}{@{}lr@{}}
1114 \toprule
1115 Heading & Heading \\
1116 \midrule
1117 Info & More info \\
1118 Info & More info \\
1119 \multicolumn{2}{c}{\tablenum[table-format = 4.4]{12,34}} \\
1120 \multicolumn{2}{c}{\tablenum[table-format = 4.4]{333.5567}} \\
1121 \multicolumn{2}{c}{\tablenum[table-format = 4.4]{4563.21}} \\
1122 \bottomrule
1123 \end{tabular}
1124 \hspace{\fill}%
1125 \begin{tabular}{@{}lr@{}}
1126 \toprule
1127 Heading & Heading \\
1128 \midrule
1129 \multirow{2}*{\tablenum{88,999}} & aaa \\
1130 & bbb \\
1131 \multirow{2}*{\tablenum{33,435}} & ccc \\
1132 & ddd \\
1133 \bottomrule
1134 \end{tabular}
1135 \end{table}
1136 \end{LaTeXdemo}
1137
1138 \section{Package control options}
1139
1140 \subsection{The key--value control system}
1141
1142 The package uses a range of different key types:
1143 \begin{description}
1144 \item[\texttt{Choice}] Takes a limited number of choices, which are described
1145 separately for each key.
1146 \item[\texttt{Integer}] Requires a number as the argument.
1147 \item[\texttt{Length}] Requires a length, either as a literal
1148 value such as \texttt{2.0cm}, or stored as a \LaTeX{} length.
1149 \item[\texttt{Literal}] A key which uses the value(s) given directly,
1150 either to check input or in output.
1151 \item[\texttt{Macro}] Requires a macro, which may need a single argument.
1152 \item[\texttt{Math}] Similar to a \texttt{literal} option, but the input is
1153 always used in math mode, irrespective of other \pkg{siunitx} settings.
1154 Thus to text-mode only input must be placed inside the argument of a
1155 \cs{text} macro.
1156 \item[\texttt{Meta}] These are options which actually apply a number of
1157 other options.
1158 \item[\texttt{Switch}] These are on--off switches, and recognise \opt{true}
1159 and \opt{false}. Giving just the key name also turns the key on.
1160 \end{description}
1161 The tables of option names use these descriptions to indicate how the keys
1162 should be used.
1163
1164 \subsection{Printing%
1165 \label{sec:print}}
1166
1167 The \pkg{siunitx} package can control the font used to print output
1168 independently of the surrounding material. Which aspects of the font follow
1169 those of the surroundings is influenced by a range of setting as detailed in
1170 Table~\ref{tab:opt:print}.
1171 \begin{table}
1172 \caption{Print options.%
1173 \label{tab:opt:print}}
1174 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
1175 \toprule
1176 \multicolumn{1}{@{}l}{Option name} &
1177 Type &
1178 \multicolumn{1}{l@{}}{Default} \\
1179 \midrule
1180 color & Literal & \meta{none} \\
1181 mode & Choice & math \\
1182 number-color & Literal & \meta{none} \\
1183 number-mode & Choice & math \\
1184 propagate-math-font & Switch & false \\
1185 reset-math-version & Switch & true \\
1186 reset-text-family & Switch & true \\
1187 reset-text-series & Switch & true \\
1188 reset-text-shape & Switch & true \\
1189 text-family-to-math & Switch & false \\
1190 text-font-command & Literal & \meta{none} \\
1191 text-subscript-command & Literal & \cs{textsubscript} \\
1192 text-superscript-command & Literal & \cs{textsuperscript} \\
1193 text-series-to-math & Switch & false \\
1194 unit-color & Literal & \meta{none} \\
1195 unit-mode & Choice & math \\
1196 \bottomrule
1197 \end{tabular}
1198 \end{table}
1199
1200 \DescribeOption{mode}
1201 \DescribeOption{number-mode}
1202 \DescribeOption{unit-mode}
1203 The \opt{mode} option determines whether \pkg{siunitx} uses math or text mode
1204 when printing output. The choices are \opt{match}, \opt{math}, \opt{text}. The
1205 \opt{match} setting means that printing uses the prevailing mode unchanged
1206 whereas \opt{math} and \opt{text} select the appropriate \TeX{} mode. It is
1207 possible to have different fonts in math and text modes, which will highlight
1208 the difference. The font settings which apply are also different depending on
1209 the mode. As well as the overall setting, it is possible to apply mode
1210 to numbers and units separately using the \opt{number-mode} and \opt{unit-mode}
1211 options.
1212
1213 \DescribeOption{reset-text-family}
1214 \DescribeOption{reset-text-series}
1215 \DescribeOption{reset-text-shape}
1216 When printing in text mode, the options \opt{reset-text-family},
1217 \opt{reset-text-series} and \opt{reset-text-shape} apply. When these are
1218 active, \pkg{siunitx} resets the relevant font selection axis property
1219 when printing: the standard font setting is upright mid-weight roman
1220 (|\upshape| |\mdseries| |\rmfamily|).
1221 \begin{LaTeXdemo}
1222 \sisetup{mode = text}
1223 {\itshape \num{1234}}\\
1224 {\bfseries \num{1234}}\\
1225 {\sffamily \num{1234}}\\
1226 \sisetup{
1227 reset-text-family = false ,
1228 reset-text-series = false ,
1229 reset-text-shape = false
1230 }
1231 {\itshape \num{1234}}\\
1232 {\bfseries \num{1234}}\\
1233 {\sffamily \num{1234}}\\
1234 \end{LaTeXdemo}
1235
1236 \DescribeOption{propagate-math-font}
1237 \DescribeOption{reset-math-version}
1238 In math mode, the font used by \LaTeX{} is \enquote{invariant}, and this is
1239 reflected in the options available. With the standard settings, in math mode
1240 printing uses the standard math font and version (weight). The option
1241 \opt{propagate-math-font} may be used to apply the prevailing math font
1242 to the printed material. The setting \opt{reset-math-version} controls
1243 whether the math version is reset or not. Note that math version is typically
1244 used to set \enquote{bold math} but may also be used for other effects, for
1245 example all sanserif math.
1246 \begin{LaTeXdemo}
1247 {\boldmath \unit{\kilogram}}\\
1248 {\sansmath $\unit{\kilogram}$}\\
1249 {$\mathsf{\unit{\kilogram}}$}\\
1250 \sisetup{
1251 propagate-math-font = true ,
1252 reset-math-version = false
1253 }
1254 {\boldmath \unit{\kilogram}}\\
1255 {\sansmath $\unit{\kilogram}$}\\
1256 {$\mathsf{\unit{\kilogram}}$}
1257 \end{LaTeXdemo}
1258
1259 \DescribeOption{text-family-to-math}
1260 \DescribeOption{text-series-to-math}
1261 The options \opt{text-family-to-math} and \opt{text-series-to-math} can be
1262 used to match (as far as possible) math mode output to the surrounding text.
1263 These options work by detecting the current text settings and making the
1264 appropriate choice in math mode.
1265 \begin{LaTeXdemo}
1266 {\sffamily \unit{\kilogram}}\\
1267 {\bfseries $\unit{\kilogram}$}\\
1268 \sisetup{
1269 text-family-to-math = true ,
1270 text-series-to-math = true
1271 }
1272 {\sffamily \unit{\kilogram}}\\
1273 {\bfseries $\unit{\kilogram}$}
1274 \end{LaTeXdemo}
1275
1276 \DescribeOption{text-font-command}
1277 In some circumstances, it may be desirable to use a non-standard font command
1278 when printing in text mode. This might be used for example to switch from
1279 old-style to lining numbers whilst still using text mode. This may be achieved
1280 by setting \opt{text-font-command}. For example, this document uses old-style
1281 numbers in text mode as-standard, which can be over-ridden by selecting the
1282 font variant which does not feature them.
1283 \begin{LaTeXdemo}
1284 \sisetup{number-mode = text}
1285 \qty{123456789}{\kilo\volt\per\centi\metre} \\
1286 \sisetup{text-font-command = \fontfamily{pplx}\selectfont}
1287 \qty{123456789}{\kilo\volt\per\centi\metre}
1288 \end{LaTeXdemo}
1289
1290 \DescribeOption{text-subscript-command}
1291 \DescribeOption{text-superscript-command}
1292 In most cases, the commands \cs{textsubscript} and \cs{textsuperscript} are
1293 appropriate for creating sub- and superscript material in text mode. However,
1294 when the \pkg{realscripts} package is loaded, it is possible that the output is
1295 not as desired. These two commands are therefore available to allow tuning of
1296 the results. They can also be used for non-standard effects, for example as
1297 here adding color to subscripts.
1298 \begin{LaTeXdemo}
1299 \sisetup{unit-mode = text}
1300 \unit{\kg\of{polymer}} \\
1301 \newcommand*\mysubscript[1]{%
1302 \textsubscript{\textcolor{blue}{#1}}%
1303 }
1304 \sisetup{text-subscript-command = \mysubscript}
1305 \unit{\kg\of{polymer}}
1306 \end{LaTeXdemo}
1307
1308 \DescribeOption{color}
1309 \DescribeOption{number-color}
1310 \DescribeOption{unit-color}
1311 The color of printed output can be set using the \opt{color} option. When no
1312 color is given, printing follows the surrounding text. In contrast, when a
1313 specific color is given, it is used irrespective of the surroundings. As with
1314 \opt{mode}, the \opt{color} setting may also be applied to numbers and units
1315 independently.
1316 \begin{LaTeXdemo}
1317 \color{red}%
1318 Some text \\
1319 \qty{4}{\kilogram} \\
1320 More text \\
1321 \qty[color = blue]{4}{\kilogram} \\
1322 Still red here!
1323 \end{LaTeXdemo}
1324 Note that the color does \emph{not} apply to text inserted by the package
1325 between numbers, units or quantities. For example, in
1326 \begin{LaTeXdemo}
1327 \numproduct[color = blue, product-mode = phrase]{1x2}
1328 \end{LaTeXdemo}
1329 only the numerals are colored; coloring all output should be done using the
1330 standard \LaTeX{} interfaces.
1331
1332 \subsection{Parsing numbers}
1333
1334 The package uses a sophisticated parsing system to understand numbers. This
1335 allows \pkg{siunitx} to carry out a range of formatting, as described later.
1336 All of the input options take lists of literal tokens, and are summarised in
1337 Table~\ref{tab:opt:num:in}.
1338 \begin{table}
1339 \caption{Options for number parsing.%
1340 \label{tab:opt:num:in}}
1341 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
1342 \toprule
1343 \multicolumn{1}{@{}l}{Option name} &
1344 Type &
1345 \multicolumn{1}{l@{}}{Default} \\
1346 \midrule
1347 evaluate-expression & Switch & false \\
1348 expression & Literal & |#1| \\^^A (
1349 input-close-uncertainty & Literal & ) \\
1350 input-comparators & Literal &
1351 <=>\cs{approx}\cs{ge}\cs{geq} \\
1352 & & \cs{gg}\cs{le}\cs{leq}\cs{ll}\cs{sim} \\
1353 input-decimal-markers & Literal & ., \\
1354 input-digits & Literal & 0123456789 \\
1355 input-exponent-markers & Literal & dDeE \\
1356 input-ignore & Literal & \meta{none} \\
1357 input-open-uncertainty & Literal & ( \\ ^^A )
1358 input-signs & Literal & +-\cs{pm}\cs{mp} \\
1359 input-uncertainty-divider & Literal & : \\
1360 input-uncertainty-signs & Literal & \cs{pm} \\
1361 parse-numbers & Switch & true \\
1362 retain-explicit-decimal-marker & Switch & false \\
1363 retain-explicit-plus & Switch & false \\
1364 retain-negative-zero & Switch & false \\
1365 retain-zero-uncertainty & Switch & false \\
1366 \bottomrule
1367 \end{tabular}
1368 \end{table}
1369
1370 \DescribeOption{input-digits}
1371 \DescribeOption{input-decimal-markers}
1372 \DescribeOption{input-signs}
1373 \DescribeOption{input-exponent-markers}
1374 The basic parts of a number are the digits, any sign and a separator between
1375 the integer and decimal parts. These are stored in the input options
1376 \opt{input-digits}, \opt{input-decimal-markers} and \opt{input-signs},
1377 respectively. More than one input decimal marker can be used: it will be
1378 converted by the package to the appropriate output marker. Numbers which
1379 include an exponent part also require a marker for the exponent: this again is
1380 taken from the range of tokens in the \opt{input-exponent-markers} option.
1381
1382 \DescribeOption{input-ignore}
1383 Tokens given in the \opt{input-ignore} list are totally passed over by
1384 \pkg{siunitx}: they will be removed from the input with no further processing.
1385
1386 \DescribeOption{input-comparators}
1387 In addition to signs, \pkg{siunitx} can recognise comparators, such as |<|. The
1388 package will automatically carry out conversions for |<<|, |>>|, |<=|, |>=| and
1389 |~| to |\ll|, |\gg|, |\le|, |\ge| and |\sim|, respectively.
1390 \begin{LaTeXdemo}
1391 \num{< 10} \\
1392 \qty{>> 5}{\metre} \\
1393 \num{\le 0.12}
1394 \end{LaTeXdemo}
1395
1396 \DescribeOption{input-open-uncertainty}
1397 \DescribeOption{input-close-uncertainty}
1398 \DescribeOption{input-uncertainty-signs}
1399 In some fields, it is common to give the uncertainty in a number in brackets
1400 after the main part of the number, for example \enquote{\num{1.234(5)}}. The
1401 opening and closing symbols used for this type of input are set as
1402 \opt{input-open-uncertainty} and \opt{input-close-uncertainty}. Alternatively,
1403 the uncertainty may be given as a separate part following a sign. Which signs
1404 are valid for this operation is determined by the \opt{input-uncertainty-signs}
1405 option. As with other signs, the combination |+-| will automatically be
1406 converted to |\pm| internally.
1407 \begin{LaTeXdemo}
1408 \num{9.99(9)} \\
1409 \num{9.99 +- 0.09} \\
1410 \num{9.99 \pm 0.09} \\
1411 \num{123 +- 4.5} \\
1412 \num{12.3 +- 6}
1413 \end{LaTeXdemo}
1414
1415 Uncertainties which cross the decimal marker may be given with or without a
1416 decimal marker in \enquote{compact} form. These are treated as equivalent by
1417 the code.\footnote{The package author favors the form without a decimal marker,
1418 and formal guidance is ambiguous on which is correct. The form with a decimal
1419 marker is seen in for example some \acro{NIST} publications.} Where multiple
1420 uncertainty values cross the decimal marker, they should all have the same
1421 number of digits.
1422 \begin{LaTeXdemo}
1423 \num{123.4(12)} \\
1424 \num{123.4(1.2)}
1425 \end{LaTeXdemo}
1426 Multiple symmetrical uncertainties may also be given: these must all either be
1427 in the short or the long form.
1428 \begin{LaTeXdemo}
1429 \num{123.4(12)(45)} \\
1430 \num{123.4 \pm 1.2 \pm 4.5}
1431 \end{LaTeXdemo}
1432
1433 \DescribeOption{input-uncertainty-divider}
1434 In some areas, uncertainties (or tolerances) are given in an asymmetric format.
1435 This is supported in the \enquote{compact} input form in \pkg{siunitx}, with
1436 the positive and negative parts of the uncertainty divided by a symbol listed
1437 in \opt{input-uncertainty-divider}. When given in this divided form, the
1438 two parts are interpreted as first the positive and then the negative
1439 component. Asymmetric uncertainties which cross the decimal marker are
1440 supported provided both components have the same number of digits.
1441 \begin{LaTeXdemo}
1442 \num{10.56(12:34)} \\
1443 \num{123.4(4.6:7.8)}
1444 \end{LaTeXdemo}
1445 Symmetrical and asymmetrical uncertainties may be intermixed.
1446 \begin{LaTeXdemo}
1447 \num{10.56(1:2)(3)} \\
1448 \num{6.45(2)(3:4)}
1449 \end{LaTeXdemo}
1450
1451 \DescribeOption{parse-numbers}
1452 The \opt{parse-numbers} option turns the entire parsing system on and off. The
1453 option is made available for two reasons. First, if all of the numbers in a
1454 document are to be reproduced \enquote{as given}, turning off the parser will
1455 represent a significant saving in processing required. Second, it allows the
1456 use of arbitrary \TeX{} code in numbers. If the parser is turned off, the input
1457 will be printed in math mode (requiring |\text| to protect any text in the
1458 number).
1459 \begin{LaTeXdemo}
1460 \num[parse-numbers = false]{\sqrt{2}} \\
1461 \qty[parse-numbers = false]{\sqrt{3}}{\metre}
1462 \end{LaTeXdemo}
1463
1464 \DescribeOption{evaluate-expression}
1465 \DescribeOption{expression}
1466 With the standard settings, numerical input is parsed \enquote{as is} with no
1467 attempt to interpret it mathematically. By enabling the
1468 \opt{evaluate-expression} option, the input can be processed by the standard
1469 \LaTeX3 \acro{FPU} (see package \pkg{xfp} for more). The nature of the
1470 expression itself can be adjusted using the \opt{expression} setting: as
1471 standard, the entire input is simply parsed with no change, but this setting
1472 may be used to add additional steps. The \emph{input} in such an expression is
1473 represented by |#1|. Note that the \acro{FPU} uses its own syntax for numbers,
1474 most notably in that a decimal marker must be |.|.
1475 \begin{LaTeXdemo}
1476 \sisetup{evaluate-expression}%
1477 \qty{2 + 4 * 3}{\joule} \\
1478 \qty[expression = 10 * (#1)]{2 + 4 * 3}{\joule}
1479 \end{LaTeXdemo}
1480
1481 \DescribeOption{retain-explicit-decimal-marker}
1482 \DescribeOption{retain-explicit-plus}
1483 \DescribeOption{retain-negative-zero}
1484 \DescribeOption{retain-zero-uncertainty}
1485 In some areas, a trailing decimal marker with no decimal part present is used
1486 to show that zeros in the integer part are significant. This can be enabled
1487 using the \opt{retain-explicit-decimal-marker} option. The inclusion of a
1488 leading plus sign is usually unnecessary for positive numbers, and so they are
1489 not retained as-standard when parsing. The \opt{retain-explicit-plus} option is
1490 available to control this behavior. Similarly, an uncertainty of zero is
1491 normally not meaningful, and so is ignored by the parser. This can be
1492 controlled using the \opt{retain-zero-uncertainty} option. Finally, a negative
1493 sign for an entirely zero value may or may not have significance: this is
1494 controlled by the \opt{retain-negative-zero} option.
1495 \begin{LaTeXdemo}
1496 \num{10.} \\
1497 \num[retain-explicit-decimal-marker]{10.} \\
1498 \num{+345} \\
1499 \num[retain-explicit-plus]{+345} \\
1500 \num{-0} \\
1501 \num[retain-negative-zero]{-0} \\
1502 \num{12.3(0)} \\
1503 \num[retain-zero-uncertainty]{12.3(0)}
1504 \end{LaTeXdemo}
1505
1506 \subsection{Post-processing numbers}
1507
1508 Before typesetting numbers, various post-processing steps can be carried out.
1509 These involve adding or removing information from the number in a systematic
1510 way; the options are summarised in Table~\ref{tab:opt:num:post}.
1511 \begin{table}
1512 \caption{Number post-processing options.%
1513 \label{tab:opt:num:post}}
1514 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
1515 \toprule
1516 \multicolumn{1}{@{}l}{Option name} &
1517 Type &
1518 \multicolumn{1}{l@{}}{Default} \\
1519 \midrule
1520 drop-exponent & Switch & false \\
1521 drop-uncertainty & Switch & false \\
1522 drop-zero-decimal & Switch & false \\
1523 exponent-mode & Switch & input \\
1524 exponent-thresholds & Literal & -3:3 \\
1525 fixed-exponent & Integer & 0 \\
1526 minimum-integer-digits & Integer & 0 \\
1527 minimum-decimal-digits & Integer & 0 \\
1528 round-direction & Choice & nearest \\
1529 round-half & Choice & up \\
1530 round-minimum & Literal & 0 \\
1531 round-mode & Choice & none \\
1532 round-pad & Switch & true \\
1533 round-precision & Integer & 2 \\
1534 round-zero-positive & Switch & true \\
1535 uncertainty-round-direction & Choice & nearest \\
1536 \bottomrule
1537 \end{tabular}
1538 \end{table}
1539
1540 \DescribeOption{exponent-mode}
1541 \DescribeOption{fixed-exponent}
1542 Numbers can be converted to scientific notation by the package. This is
1543 controlled by the \opt{exponent-mode} option, which takes choices \opt{input},
1544 \opt{fixed}, \opt{engineering}, \opt{scientific} and \opt{threshold}. The
1545 \opt{fixed} setting will use the exponent value by the \opt{fixed-exponent}
1546 option. When \opt{engineering} is set, the exponent is always a power of three.
1547 \begin{LaTeXdemo}
1548 \num{0.001} \\
1549 \num{0.0100} \\
1550 \num{1200} \\
1551 \sisetup{exponent-mode = scientific}%
1552 \num{0.001} \\
1553 \num{0.0100} \\
1554 \num{1200} \\
1555 \sisetup{exponent-mode = engineering}%
1556 \num{0.001} \\
1557 \num{0.0100} \\
1558 \num{1200} \\
1559 \sisetup{
1560 exponent-mode = fixed,
1561 fixed-exponent = 2,
1562 }%
1563 \num{0.001} \\
1564 \num{0.0100} \\
1565 \num{1200}
1566 \end{LaTeXdemo}
1567 When used with a \opt{fixed-exponent} of zero, this may be used to remove
1568 scientific notation from the input
1569 \begin{LaTeXdemo}
1570 \num{1.23e4} \\
1571 \num[exponent-mode = fixed, fixed-exponent = 0]{1.23e4}
1572 \end{LaTeXdemo}
1573 \DescribeOption{exponent-thresholds}
1574 When the \opt{exponent-mode} is set to \opt{threshold}, values outside of a
1575 threshold range for the exponent are always printed in scientific form. The
1576 threshold range itself is controlled by \opt{exponent-thresholds}, which is
1577 given as \texttt{\meta{min}:\meta{max}} (Table~\ref{tab:threshold}).
1578 \begin{LaTeXdemo}[code and float]
1579 \begin{table}
1580 \caption{Thresholds for exponents.%
1581 \label{tab:threshold}}
1582 \begin{tabular}
1583 {
1584 @{}
1585 S
1586 S[exponent-mode = threshold]
1587 S[exponent-mode = threshold, exponent-thresholds = -2:2]
1588 @{}
1589 }
1590 \toprule
1591 {Input} & {Threshold $-3:3$} & {Threshold $-2:2$} \\
1592 \midrule
1593 0.001 & 0.001 & 0.001 \\
1594 0.012 & 0.012 & 0.012 \\
1595 0.123 & 0.123 & 0.123 \\
1596 1 & 1 & 1 \\
1597 12 & 12 & 12 \\
1598 123 & 123 & 123 \\
1599 1234 & 1234 & 1234 \\
1600 \bottomrule
1601 \end{tabular}
1602 \end{table}
1603 \end{LaTeXdemo}
1604
1605 Exponent mode applies \emph{after} rounding, such that the number of decimal
1606 places for rounding is those which appear in the output.
1607
1608 \DescribeOption{drop-exponent}
1609 \DescribeOption{drop-uncertainty}
1610 The use of an uncertainty can be suppressed entirely using the
1611 \opt{drop-uncertainty} option: this applies \emph{before} rounding is
1612 attempted. Similarly, exponents can be dropped using \opt{drop-exponent} can be
1613 used to suppress the exponent part (\emph{after} conversion to a fixed
1614 exponent).
1615 \begin{LaTeXdemo}
1616 \num{0.01(2)} \\
1617 \num[drop-uncertainty]{0.01(2)} \\
1618 \num{0.01e3} \\
1619 \num[drop-exponent]{0.01e3}
1620 \end{LaTeXdemo}
1621
1622 \DescribeOption{round-mode}
1623 \DescribeOption{round-precision}
1624 \DescribeOption{round-pad}
1625 The package can round numerical input to a fixed number of significant figures
1626 or decimal places. This is controlled by the \opt{round-mode} option, which
1627 takes the choices \opt{none}, \opt{figures}, \opt{places} and
1628 \opt{uncertainty}. When rounding is turned on, the number of digits used
1629 (either decimal places or significant figures in the mantissa) is set using the
1630 \opt{round-precision} option. Rounding numbers with uncertainties may be
1631 carried out using the \opt{uncertainty} setting to \opt{round-mode}. In this
1632 case the precision is used first to round the uncertainty itself (to a number
1633 of figures), before rounding the main value to follow.
1634 \begin{LaTeXdemo}
1635 \num{1.23456} \\
1636 \num{14.23} \\
1637 \num{0.12345(9)} \\
1638 \sisetup{
1639 round-mode = places,
1640 round-precision = 3
1641 }%
1642 \num{1.23456} \\
1643 \num{14.23} \\
1644 \num{0.12345(9)} \\
1645 \sisetup{
1646 round-mode = figures,
1647 round-precision = 3
1648 }%
1649 \num{1.23456} \\
1650 \num{14.23} \\
1651 \num{0.12345(9)} \\
1652 \sisetup{
1653 round-mode = uncertainty,
1654 round-precision = 1
1655 }%
1656 \num{0.12345(9)} \\
1657 \num{0.12345(23)} \\
1658 \num{0.12345(234)}
1659 \end{LaTeXdemo}
1660 Rounding may \enquote{extend} a short number to more digits (or figures): this
1661 is controlled by the switch \opt{round-pad}, which is \opt{true} as standard.
1662 \begin{LaTeXdemo}
1663 \sisetup{round-mode = figures, round-precision = 4}%
1664 \num{12.3} \\
1665 \num[round-pad = false]{12.3}
1666 \end{LaTeXdemo}
1667
1668 \DescribeOption{round-direction}
1669 \DescribeOption{round-half}
1670 The detail of which approach to use for rounding may be adjusted using the
1671 options \opt{round-direction} and \opt{round-half}. The option
1672 \opt{round-direction} determines which direction a value is rounded toward: a
1673 choice of \opt{nearest}, \opt{up} or \opt{down}. The standard setting,
1674 \opt{nearest}, gives the common outcome that values round depending on whether
1675 the preceding digit is greater or less than \num{5}. The options \opt{up} and
1676 \opt{down} mean that values are always rounded in one direction: the \opt{down}
1677 option may be thought of as \enquote{truncation}.
1678 \begin{LaTeXdemo}
1679 \sisetup{round-mode = places}
1680 \num{0.054} \\
1681 \num{0.046} \\
1682 \sisetup{round-direction = down}%
1683 \num{0.054} \\
1684 \num{0.046} \\
1685 \sisetup{round-direction = up}%
1686 \num{0.054} \\
1687 \num{0.046}
1688 \end{LaTeXdemo}
1689 For rounding to \opt{nearest}, where the rounded part of a number is exactly
1690 half, there are two common methods for \enquote{breaking the tie}. The choice
1691 of method is determined by the option \opt{round-half}, which recognises the
1692 choices \opt{up} and \opt{even}.
1693 \begin{LaTeXdemo}
1694 \sisetup{
1695 round-mode = figures,
1696 round-precision = 1,
1697 round-half = up
1698 }%
1699 \num{0.055} \\
1700 \num{0.045} \\
1701 \sisetup{round-half = even}%
1702 \num{0.055} \\
1703 \num{0.045}
1704 \end{LaTeXdemo}
1705
1706 \DescribeOption{uncertainty-round-direction}
1707 When rounding with uncertainties, the direction to round the uncertainty part
1708 may be set independently of the main number: this is typically used to round
1709 the uncertainty strictly upward.
1710 \begin{LaTeXdemo}
1711 \sisetup{round-mode = uncertainty}
1712 \num{0.123(141)} \\
1713 \sisetup{uncertainty-round-direction = up}%
1714 \num{0.123(141)}
1715 \end{LaTeXdemo}
1716
1717 \DescribeOption{round-minimum}
1718 There are cases in which rounding will result in the number reaching zero. It
1719 may be desirable to show such results as below a threshold value. This can be
1720 achieved by setting \opt{round-minimum} to the threshold value. There will be
1721 no effect when rounding to a number of significant figures as it is not
1722 possible to obtain the value zero in these cases.
1723 \begin{LaTeXdemo}
1724 \sisetup{round-mode = places}%
1725 \num{0.0055} \\
1726 \num{0.0045} \\
1727 \sisetup{round-minimum = 0.01}%
1728 \num{0.0055} \\
1729 \num{0.0045}
1730 \end{LaTeXdemo}
1731
1732 \DescribeOption{round-zero-positive}
1733 When rounding negative numbers to a fixed number of places, a zero value may
1734 result. Usually this is expressed as an unsigned value, but in some cases
1735 retaining the negative sign may be desirable. This behavior can be controlled
1736 using the \opt{round-zero-positive} switch.
1737 \begin{LaTeXdemo}
1738 \sisetup{round-mode = places}%
1739 \num{-0.001} \\
1740 \sisetup{round-zero-positive = false}%
1741 \num{-0.001}
1742 \end{LaTeXdemo}
1743
1744 \DescribeOption{drop-zero-decimal}
1745 It may be desirable to convert decimals to integers when the decimal part is
1746 zero. This is set up using the \opt{drop-zero-decimal} option, which applies
1747 after rounding but before setting minimum numbers of digits.
1748 \begin{LaTeXdemo}
1749 \num{2.0} \\
1750 \num{2.1} \\
1751 \sisetup{drop-zero-decimal}%
1752 \num{2.0} \\
1753 \num{2.1}
1754 \end{LaTeXdemo}
1755
1756 \DescribeOption{minimum-decimal-digits}
1757 \DescribeOption{minimum-integer-digits}
1758 The \opt{minimum-decimal-digits} and \opt{minimum-integer-digits} option may be
1759 used to pad numbers to a given size. This applies independent of any rounding.
1760 \begin{LaTeXdemo}
1761 \num{123} \\
1762 \num[minimum-integer-digits = 2]{123} \\
1763 \num[minimum-integer-digits = 4]{123} \\
1764 \num{0.123} \\
1765 \num[minimum-decimal-digits = 2]{0.123} \\
1766 \num[minimum-decimal-digits = 4]{0.123} \\
1767 \end{LaTeXdemo}
1768
1769 \subsection{Printing numbers}
1770
1771 Actually printing numbers is controlled by a number of settings, which apply
1772 ideas such as differing decimal markers, digit grouping and so on. All of these
1773 options are concerned with the appearance of output, rather than the data it
1774 conveys. The options are summarised in Table~\ref{tab:opt:num:out}.
1775 \begin{table}
1776 \caption{Output options for numbers.%
1777 \label{tab:opt:num:out}}
1778 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
1779 \toprule
1780 \multicolumn{1}{l}{Option name} &
1781 Type &
1782 \multicolumn{1}{l}{Default} \\
1783 \midrule
1784 bracket-ambiguous-numbers & Switch & true \\
1785 bracket-negative-numbers & Switch & false \\
1786 digit-group-size & Integer & 3 \\
1787 digit-group-first-size & Integer & 3 \\
1788 digit-group-other-size & Integer & 3 \\
1789 exponent-base & Literal & 10 \\
1790 exponent-product & Math & \verb=\times= \\
1791 group-allow-singleton & Switch & true \\
1792 group-digits & Choice & all \\
1793 group-minimum-digits & Integer & 5 \\
1794 group-separator & Literal & \cs{,} \\
1795 negative-color & Literal & \meta{none} \\ ^^A (
1796 output-close-uncertainty & Literal & ) \\
1797 output-decimal-marker & Literal & . \\
1798 output-exponent-marker & Literal & \meta{none} \\
1799 output-open-uncertainty & Literal & ( \\ ^^A )
1800 print-exponent-implicit-plus & Switch & false \\
1801 print-implicit-plus & Switch & false \\
1802 print-mantissa-implicit-plus & Switch & false \\
1803 print-unity-mantissa & Switch & true \\
1804 print-zero-exponent & Switch & false \\
1805 print-zero-integer & Switch & true \\
1806 simplify-uncertainty & Switch & false \\
1807 tight-spacing & Switch & false \\
1808 uncertainty-descriptor-mode & Choice & bracket-separator \\
1809 uncertainty-descriptor-separator & Literal & \cs{ } \\
1810 uncertainty-descriptors & Literal & \meta{none} \\
1811 uncertainty-mode & Choice & compact \\
1812 uncertainty-separator & Literal & \meta{none} \\
1813 zero-decimal-as-symbol & Switch & false \\
1814 zero-symbol & Literal & \verb=\mbox{---}= \\
1815 \bottomrule
1816 \end{tabular}
1817 \end{table}
1818
1819 \DescribeOption{group-digits}
1820 \DescribeOption{group-separator}
1821 Grouping digits into blocks of three is a common method to increase the ease of
1822 reading of numbers. The \opt{group-digits} choice controls whether this
1823 behavior applies, and takes the values \opt{all}, \opt{none}, \opt{decimal} and
1824 \opt{integer}. Grouping can be activated separately for the integer and decimal
1825 parts of a number using the appropriately-named values.
1826 \begin{LaTeXdemo}
1827 \num{12345.67890} \\
1828 \num[group-digits = none]{12345.67890} \\
1829 \num[group-digits = decimal]{12345.67890} \\
1830 \num[group-digits = integer]{12345.67890}
1831 \end{LaTeXdemo}
1832 The separator used between groups of digits is stored by the
1833 \opt{group-separator} option. This takes literal input and may be used in math
1834 mode: for a text-mode full space use \verb*|\ |.
1835 \begin{LaTeXdemo}
1836 \num{12345} \\
1837 \num[group-separator = {,}]{12345} \\
1838 \num[group-separator = \ ]{12345}
1839 \end{LaTeXdemo}
1840
1841 \DescribeOption{group-minimum-digits}
1842 Grouping is not always applied to smaller numbers; this can be controlled using
1843 the option \opt{group-minimum-digits}, which specifies how many digits must be
1844 present before grouping is applied. The number of digits is considered
1845 separately for the integer and decimal parts of the number: grouping does not
1846 \enquote{cross the boundary}.
1847 \begin{LaTeXdemo}
1848 \num{1234} \\
1849 \num{12345} \\
1850 \num[group-minimum-digits = 5]{1234} \\
1851 \num[group-minimum-digits = 5]{12345} \\
1852 \num{1234.5678} \\
1853 \num{12345.67890} \\
1854 \num[group-minimum-digits = 5]{1234.5678} \\
1855 \num[group-minimum-digits = 5]{12345.67890}
1856 \end{LaTeXdemo}
1857
1858 \DescribeOption{digit-group-size}
1859 \DescribeOption{digit-group-first-size}
1860 \DescribeOption{digit-group-other-size}
1861 The number of digits in each group can be controlled by the setting
1862 \opt{digit-group-size}, which has standard value $3$. Finer control can be
1863 achieved using \opt{digit-group-first-size} and \opt{digit-group-other-size}:
1864 the first group is that immediately by the decimal point, the other value
1865 applies to the second and subsequent groupings. These can be used for
1866 example to achieve the grouping typically used in India (lakh).
1867 \begin{LaTeXdemo}
1868 \num{1234567890} \\
1869 \num[digit-group-size = 5]{1234567890} \\
1870 \num[digit-group-other-size = 2]{1234567890}
1871 \end{LaTeXdemo}
1872
1873 \DescribeOption{final-digit-group-min-size}
1874 Grouping can result in a \enquote{dangling} digit, for example if there are
1875 seven digits in the decimal part with the standard group-of-three approach. To
1876 allow these to be avoided automatically, the setting
1877 \opt{final-digit-group-min-size} is available. Setting this to for example
1878 \opt{2} will mean that the final group is enlarged to respect the minimum size
1879 where this is required to avoid a group size of~1.
1880 \begin{LaTeXdemo}
1881 \num{0.1234567} \\
1882 \num[final-digit-group-min-size = 2]{0.1234567}
1883 \end{LaTeXdemo}
1884
1885 \DescribeOption{output-decimal-marker}
1886 The decimal marker used in output is set using the \opt{output-decimal-marker}
1887 option; this can differ from the input marker.
1888 \begin{LaTeXdemo}
1889 \num{1.23} \\
1890 \num[output-decimal-marker = {,}]{1.23} \\
1891 \end{LaTeXdemo}
1892
1893 \DescribeOption{exponent-base}
1894 \DescribeOption{exponent-product}
1895 When exponents are present in the input, the \opt{exponent-base} and
1896 \opt{exponent-product} options set the obvious parts of the output.
1897 \begin{LaTeXdemo}
1898 \num[exponent-product = \times]{1e2} \\
1899 \num[exponent-product = \cdot]{1e2} \\
1900 \num[exponent-base = 2]{1e2}
1901 \end{LaTeXdemo}
1902 \DescribeOption{output-exponent-marker}
1903 Alternatively, if the \opt{output-exponent-marker} option is set then the value
1904 stored will be used in place of the normal product and base combination.
1905 \begin{LaTeXdemo}
1906 \num[output-exponent-marker = e]{1e2} \\
1907 \num[output-exponent-marker = \mathrm{E}]{1e2}
1908 \end{LaTeXdemo}
1909
1910 \DescribeOption{uncertainty-mode}
1911 \DescribeOption{output-open-uncertainty}
1912 \DescribeOption{output-close-uncertainty}
1913 \DescribeOption{uncertainty-separator}
1914 \DescribeOption{allow-uncertainty-breaks}
1915 When input is given including a single uncertainty, it can be printed either
1916 with the uncertainty in brackets or as a separate number. This behavior is
1917 controlled by the \opt{uncertainty-mode} choice. When this is set to
1918 \opt{separate}, the uncertainty is printed as an entirely separate number
1919 preceded by \cs{pm}. Other settings all place the uncertainty in brackets
1920 directly attached to the main value. The standard setting of \opt{compact}
1921 prints digits of uncertainty in the least-significant digits. It does
1922 \emph{not} print a decimal marker if the uncertainty crosses the decimal. The
1923 setting \opt{full} prints the full value of the uncertainty. Finally,
1924 \opt{compact-marker} is available to print in the \opt{compact} style except
1925 where the uncertainty crosses the decimal, in which case the \opt{full} style
1926 is used. When the uncertainty is given in brackets, a space may be added
1927 between the main number and the uncertainty: this is stored using the
1928 \opt{uncertainty-separator} option. The opening and closing brackets used are
1929 stored in \opt{output-open-uncertainty} and \opt{output-close-uncertainty},
1930 respectively. Tokens may be inserted before the opening bracket using
1931 \opt{uncertainty-separator}. As standard, a break is allowed before a separated
1932 uncertainty: this can be suppressed by setting \opt{allow-uncertainty-breaks}
1933 to \opt{false}.
1934 \begin{LaTeXdemo}
1935 \num{123.45(120)} \\
1936 \num{0.035(14)} \\
1937 \sisetup{uncertainty-mode = full}
1938 \num{123.45(120)} \\
1939 \num{0.035(14)} \\
1940 \sisetup{uncertainty-mode = compact-marker}
1941 \num{123.45(120)} \\
1942 \num{0.035(14)} \\
1943 \sisetup{
1944 output-open-uncertainty = [,
1945 output-close-uncertainty = ],
1946 uncertainty-separator = \,
1947 }%
1948 \num{1.234(5)}
1949 \end{LaTeXdemo}
1950
1951 \DescribeOption{uncertainty-descriptors}
1952 \DescribeOption{uncertainty-descriptor-mode}
1953 \DescribeOption{uncertainty-descriptor-separator}
1954 Multiple uncertainties can be given for a number. These are always printed in a
1955 separated form. When there is more than one uncertainty part, it may be useful
1956 to describe the nature of this value. This can be achieved using the
1957 \opt{uncertainty-descriptors} option, which take a comma-separated list of
1958 descriptions. The formatting of the descriptors can be adjusted using the
1959 settings \opt{uncertainty-descriptor-mode} and
1960 \opt{uncertainty-descriptor-separator}. The choices for the \opt{mode} are
1961 \opt{bracket}, \opt{bracket-separator}, \opt{separator} and \opt{subscript}.
1962 \begin{LaTeXdemo}
1963 \num{1.2(3)(4)} \\
1964 \sisetup{uncertainty-descriptors = {sys, stat}}
1965 \num{1.2(3)(4)} \\
1966 \num[uncertainty-descriptor-mode = subscript]{1.2(3)(4)}
1967 \end{LaTeXdemo}
1968
1969 \DescribeOption{simplify-uncertainty}
1970 Where the upper and lower parts of an asymmetrical uncertainty are identical,
1971 it may be desirable to print as in symmetrical format. This can be enabled
1972 using the \opt{simplify-uncertainty} option.
1973 \begin{LaTeXdemo}
1974 \num{10.56(2:2)} \\
1975 \num[simplify-uncertainty]{10.56(2:2)}
1976 \end{LaTeXdemo}
1977
1978 \DescribeOption{bracket-ambiguous-numbers}
1979 There are certain combinations of numerical input which can be ambiguous. This
1980 can be corrected by adding brackets in the appropriate place, and is controlled
1981 by the \opt{bracket-ambiguous-numbers} switch. This option only applies to pure
1982 numbers: when formatting quantities, the need for brackets also depends on the
1983 placement of units, so is controlled by \opt{separate-uncertainty-units}.
1984 \begin{LaTeXdemo}
1985 \sisetup{uncertainty-mode = separate}
1986 \num{1.2(3)e4} \\
1987 \num[bracket-ambiguous-numbers = false]{1.2(3)e4}
1988 \end{LaTeXdemo}
1989
1990 \DescribeOption{negative-color}
1991 The package can detect negative mantissa values and alter print color
1992 accordingly. This is disabled by setting the option to an empty value.
1993 This option does \emph{not} apply to complex numbers.
1994 \begin{LaTeXdemo}
1995 \num{-15673} \\
1996 \num[negative-color = red]{-15673}
1997 \end{LaTeXdemo}
1998
1999 \DescribeOption{bracket-negative-numbers}
2000 A common means to display negative numbers in financial situations is to place
2001 them in brackets. This can be carried out automatically using the
2002 \opt{bracket-negative-numbers} option. This option does \emph{not} apply to
2003 complex numbers.
2004 \begin{LaTeXdemo}
2005 \num{-15673} \\
2006 \num[bracket-negative-numbers]{-15673} \\
2007 \qty{-10}{\metre} \\
2008 \qty[bracket-negative-numbers]{-10}{\metre}
2009 \end{LaTeXdemo}
2010
2011 \DescribeOption{tight-spacing}
2012 Under some circumstances is may be desirable to \enquote{squeeze} the output
2013 spacing. This is turned on using the \opt{tight-spacing} switch, which
2014 compresses spacing where possible.
2015 \begin{LaTeXdemo}
2016 \num{2e3} \\
2017 \num[tight-spacing = true]{2e3}
2018 \end{LaTeXdemo}
2019
2020 \DescribeOption{print-implicit-plus}
2021 \DescribeOption{print-mantissa-implicit-plus}
2022 \DescribeOption{print-exponent-implicit-plus}
2023 It may be useful to force all numbers to have a sign. This behavior is
2024 controlled by the \opt{print-implicit-plus} option: this is used if given and
2025 if no sign was present in the input. It is possible to set this behavior for
2026 the exponent and mantissa independently.
2027 \begin{LaTeXdemo}
2028 \num{345} \\
2029 \num[print-implicit-plus]{345}
2030 \end{LaTeXdemo}
2031
2032 \DescribeOption{print-unity-mantissa}
2033 \DescribeOption{print-zero-exponent}
2034 \DescribeOption{print-zero-integer}
2035 Printing of a mantissa of $1$, an exponent of $0$ and an integer component of
2036 $0$ is controllable by the options \opt{print-unity-mantissa},
2037 \opt{print-zero-exponent} and \opt{print-zero-integer}. The standard settings
2038 print a mantissa of $1$ and an integer part of $0$, but omit an exponent of
2039 $0$. Notice that where both \opt{print-unity-mantissa} and
2040 \opt{print-zero-exponent} are set to \opt{false}, the value $1$ will still be
2041 printed (\foreign{i.e.}~\opt{print-zero-exponent} has a higher priority).
2042 \begin{LaTeXdemo}
2043 \num{1e4} \\
2044 \num[print-unity-mantissa = false]{1e4} \\
2045 \num{444e0} \\
2046 \num[print-zero-exponent = true]{444e0} \\
2047 \num{0.123} \\
2048 \num[print-zero-integer = false]{0.123}
2049 \end{LaTeXdemo}
2050
2051 \DescribeOption{zero-decimal-as-symbol}
2052 \DescribeOption{zero-symbol}
2053 In some areas, particularly financial, entirely zero decimal parts are
2054 replaced by a dash. This is supported by option \opt{zero-decimal-as-symbol},
2055 which then uses the material stored using \opt{zero-symbol} as the replacement.
2056 \begin{LaTeXdemo}
2057 \num{123.00} \\
2058 \sisetup{zero-decimal-as-symbol}
2059 \num{123.00} \\
2060 \num[zero-symbol = \text{[{---}]}]{123.00}
2061 \end{LaTeXdemo}
2062
2063 \subsection{Lists, products and ranges}
2064
2065 Lists, products and ranges of numbers and quantities have a small number of
2066 specialised options, which apply to these more unusual input forms
2067 (Table~\ref{tab:opt:num:list}).
2068 \begin{table}
2069 \begin{threeparttable}
2070 \caption{Output options for lists, products and ranges of numbers and
2071 quantities.%
2072 \label{tab:opt:num:list}}
2073 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
2074 \toprule
2075 \multicolumn{1}{l}{Option name} &
2076 Type &
2077 \multicolumn{1}{l}{Default\tnote{*}} \\
2078 \midrule % (
2079 list-close-bracket & Literal & ) \\
2080 list-exponents & Choice & individual \\
2081 list-final-separator & Literal & \verb*= \text{and} = \\
2082 list-independent-prefix & Switch & false \\
2083 list-open-bracket & Literal & ( \\ % )
2084 list-pair-separator & Literal & \verb*= \text{and} = \\
2085 list-separator & Literal & \verb*=\text{,} = \\
2086 list-units & Choice & repeat \\ % (
2087 product-close-bracket & Literal & ) \\
2088 product-exponents & Choice & individual \\
2089 product-independent-prefix & Switch & false \\
2090 product-mode & Choice & symbol \\
2091 product-open-bracket & Literal & ( \\ % )
2092 product-phrase & Literal & \verb*= \text{by} = \\
2093 product-symbol & Literal & \cs{times} \\
2094 product-units & Choice & repeat \\ % (
2095 range-close-bracket & Literal & ) \\
2096 range-exponents & Choice & individual \\
2097 range-independent-prefix & Switch & false \\
2098 range-open-bracket & Literal & ( \\ % )
2099 range-open-phrase & Literal & \meta{empty} \\
2100 range-phrase & Literal & \verb*= \text{to} = \\
2101 range-units & Choice & repeat \\
2102 \bottomrule
2103 \end{tabular}
2104 \footnotesize
2105 \begin{tablenotes}
2106 \item[*] The default values are actually more complex for two
2107 reasons: allowing spaces to work in both math and text modes,
2108 and localization of strings.
2109 \end{tablenotes}
2110 \end{threeparttable}
2111 \end{table}
2112
2113 \DescribeOption{list-final-separator}
2114 \DescribeOption{list-pair-separator}
2115 \DescribeOption{list-separator}
2116 Lists of numbers are printed with a separator between each item, which is
2117 stored using the \opt{list-separator} option. The separator before the last
2118 item of a list may be different, and is therefore set using the
2119 \opt{list-final-separator} option. The separator used for exactly two items is
2120 set using the \opt{list-pair-separator} option. Any spaces needed should be
2121 included in the option settings: none are added within the code. The separators
2122 are always printed in text mode.
2123 \begin{LaTeXdemo}
2124 \numlist{0.1;0.2;0.3} \\
2125 \numlist[list-separator = {; }]{0.1;0.2;0.3} \\
2126 \numlist[list-final-separator = {, }]{0.1;0.2;0.3} \\
2127 \numlist[
2128 list-separator = { and },
2129 list-final-separator = { and finally }
2130 ]{0.1;0.2;0.3} \\
2131 \numlist{0.1;0.2} \\
2132 \numlist[list-pair-separator = {, and }]{0.1;0.2}
2133 \end{LaTeXdemo}
2134
2135 \DescribeOption{product-mode}
2136 \DescribeOption{product-phrase}
2137 \DescribeOption{product-symbol}
2138 Products of numbers can be output using either a product symbol or phrase:
2139 this is controlled by the \opt{product-mode} setting. When \opt{symbol} is
2140 set, the appropriate symbol is stored in \opt{product-symbol}. When using
2141 \opt{phrase-mode}, the information is stored in \opt{product-phrase}. Phrases
2142 are always printed in text mode; symbols are printed using the same routine
2143 as for numbers.
2144 \begin{LaTeXdemo}
2145 \numproduct{5 x 100 x 2} \\
2146 \numproduct[product-symbol = \ensuremath{\cdot}]{5 x 100 x 2} \\
2147 \sisetup{product-mode = phrase}%
2148 \numproduct{5 x 100 x 2}\\
2149 \numproduct[product-phrase = { BY }]{5 x 100 x 2} \\
2150 \end{LaTeXdemo}
2151
2152 \DescribeOption{range-open-phrase}
2153 \DescribeOption{range-phrase}
2154 Ranges of numbers can be given as input. These will have an appropriate word or
2155 symbol inserted between the two entries: this is stored using the
2156 \opt{range-phrase} option. The phrase should include any necessary spaces: no
2157 extra space is added. The phrase is always printed in text mode.
2158 \begin{LaTeXdemo}
2159 \numrange{5}{100} \\
2160 \numrange[range-phrase = --]{5}{100}
2161 \end{LaTeXdemo}
2162 In some languages, an opening phrase is \emph{required}; this is supported
2163 using the \opt{range-open-phrase} key.
2164 \begin{LaTeXdemo}
2165 \numrange{10}{12} \\
2166 \numrange[range-open-phrase = {\text{from} }]{5}{100}
2167 \end{LaTeXdemo}
2168
2169 \DescribeOption{list-exponents}
2170 \DescribeOption{product-exponents}
2171 \DescribeOption{range-exponents}
2172 Lists, products and ranges can be \enquote{compressed} by combining the
2173 exponent parts. This is controlled by the options \opt{list-exponents},
2174 \opt{product-exponents} and \opt{range-exponents}, all of which take the
2175 choices \opt{individual}, \opt{combine-bracket} and \opt{combine}. The standard
2176 setting, \opt{individual}, leaves the exponent with the matching value. Both
2177 \opt{combine} and \opt{combine-bracket} take the exponent of the first entry
2178 and apply to all other entries, with the exponent itself places at the end.
2179 \begin{LaTeXdemo}
2180 \numlist{5e3;7e3;9e3;1e4} \\
2181 \numproduct{5e3 x 7e3 x 9e3 x 1e4} \\
2182 \numrange{5e3}{7e3} \\
2183 \sisetup
2184 {
2185 list-exponents = combine-bracket ,
2186 product-exponents = combine-bracket ,
2187 range-exponents = combine-bracket
2188 }
2189 \numlist{5e3;7e3;9e3;1e4} \\
2190 \numproduct{5e3 x 7e3 x 9e3 x 1e4} \\
2191 \numrange{5e3}{7e3} \\
2192 \sisetup
2193 {
2194 list-exponents = combine ,
2195 product-exponents = combine ,
2196 range-exponents = combine
2197 }
2198 \numlist{5e3;7e3;9e3;1e4} \\
2199 \numproduct{5e3 x 7e3 x 9e3 x 1e4} \\
2200 \numrange{5e3}{7e3}
2201 \end{LaTeXdemo}
2202
2203 \DescribeOption{list-units}
2204 \DescribeOption{product-units}
2205 \DescribeOption{range-units}
2206 The \opt{list-units}, \opt{product-units} and \opt{range-units} options
2207 determine how \cs{qtylist}, \cs{qtyproduct} and \cs{qtyrange} command print
2208 units, respectively. The standard setting for these is \opt{repeat}, where each
2209 number will be printed with a unit. Alternatives are \opt{bracket} and
2210 \opt{single}. If set to \opt{single}, this will override collection of
2211 exponents.
2212 \begin{LaTeXdemo}
2213 \qtylist{2;4;6;8}{\tesla} \\
2214 \qtylist[list-units = bracket]{2;4;6;8}{\tesla} \\
2215 \qtylist[list-units = repeat]{2;4;6;8}{\tesla} \\
2216 \qtylist[list-units = single]{2;4;6;8}{\tesla} \\
2217 \qtyrange{2}{4}{\degreeCelsius} \\
2218 \qtyrange[range-units = bracket]{2}{4}{\degreeCelsius} \\
2219 \qtyrange[range-units = repeat]{2}{4}{\degreeCelsius} \\
2220 \qtyrange[range-units = single]{2}{4}{\degreeCelsius}
2221 \end{LaTeXdemo}
2222 The option \opt{product-units} also offers the settings \opt{bracket-power} and
2223 \opt{power}.
2224 \begin{LaTeXdemo}
2225 \qtyproduct{2 x 4}{\metre} \\
2226 \qtyproduct[product-units = bracket-power]{2 x 4}{\metre} \\
2227 \qtyproduct[product-units = power]{2 x 4}{\metre}
2228 \end{LaTeXdemo}
2229 \DescribeOption{list-close-bracket}
2230 \DescribeOption{list-open-bracket}
2231 \DescribeOption{product-close-bracket}
2232 \DescribeOption{product-open-bracket}
2233 \DescribeOption{range-close-bracket}
2234 \DescribeOption{range-open-bracket}
2235 The brackets used can be customised using the relevant \texttt{\dots-open-bracket}
2236 and \texttt{\dots-close-bracket} options.
2237 \begin{LaTeXdemo}
2238 \sisetup{
2239 list-units = bracket ,
2240 list-open-bracket = [ ,
2241 list-close-bracket = ]
2242 }
2243 \qtylist{5e3;7e3;9e3;1e4}{\second} \\
2244 \sisetup{
2245 product-units = bracket ,
2246 product-open-bracket = \{ ,
2247 product-close-bracket = \}
2248 }
2249 \qtyproduct{5e3 x 7e3 x 9e3 x 1e4}{\metre} \\
2250 \sisetup{
2251 range-units = bracket ,
2252 range-open-bracket = \langle ,
2253 range-close-bracket = \rangle
2254 }
2255 \qtyrange{2}{4}{\degreeCelsius}
2256 \end{LaTeXdemo}
2257
2258 \DescribeOption{list-independent-prefix}
2259 \DescribeOption{product-independent-prefix}
2260 \DescribeOption{range-independent-prefix}
2261 When converting exponents to prefixes, there are two possible approaches to the
2262 case where units are repeated. They can all be converted to use the same
2263 (initial) prefix, or they can be processed separately. The
2264 \texttt{\dots-independent-prefix} options are used to control this outcome.
2265 \begin{LaTeXdemo}
2266 \sisetup{exponent-to-prefix = true}%
2267 \qtyrange{1e3}{1e9}{\watt}\\
2268 \sisetup{range-independent-prefix = true}%
2269 \qtyrange{1e3}{1e9}{\watt}
2270 \end{LaTeXdemo}
2271
2272 \subsection{Complex numbers}
2273
2274 A small number of options apply specifically to the handling of complex
2275 numbers; these are summarised in Table~\ref{tab:opt:num:complex}.
2276 \begin{table}
2277 \caption{Options for complex numbers.%
2278 \label{tab:opt:num:complex}}
2279 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
2280 \toprule
2281 \multicolumn{1}{@{}l}{Option name} &
2282 Type &
2283 \multicolumn{1}{l@{}}{Default} \\
2284 \midrule
2285 complex-angle-unit & Choice & degrees \\
2286 complex-mode & Choice & input \\
2287 complex-phase-command & Literal & \cs{angle} \\
2288 complex-root-position & Choice & after-number \\
2289 complex-symbol-degree & Literal & \cs{degree} \\
2290 input-complex-root & Literal & ij \\
2291 output-complex-root & Literal & \verb=\mathrm{i}= \\
2292 print-complex-unity & Switch & false \\
2293 \bottomrule
2294 \end{tabular}
2295 \end{table}
2296
2297 \DescribeOption{complex-mode}
2298 The format in which complex values are printed can be set using the
2299 \opt{complex-mode} option. With the standard setting (\opt{input}), the complex
2300 value is printed as-given. By setting the option to \opt{cartesian} or
2301 \opt{polar}, the output format can be set to an Cartesian or polar form.
2302 Conversion uses the \LaTeX3 floating-point unit, so is limited to $16$ decimal
2303 places. When converting from Cartesian to polar form, the complex root symbol
2304 must come at the \emph{end} of the imaginary part. It must also be specified
2305 using \texttt{i}.
2306 \begin{LaTeXdemo}
2307 \complexnum{1 + i} \\
2308 \complexnum{1:45} \\
2309 \complexnum[complex-mode = cartesian]{1 + i} \\
2310 \complexnum[complex-mode = cartesian, round-mode = places]{1:45} \\
2311 \complexnum[complex-mode = polar]{1 + i} \\
2312 \complexnum[complex-mode = polar]{1:45}
2313 \end{LaTeXdemo}
2314
2315 \DescribeOption{input-complex-root}
2316 When using complex numbers in input, the complex root $(\mathrm{i} =
2317 \sqrt{-1}\,)$ is indicated by one of the tokens stored in
2318 \opt{input-complex-roots}. The parser understands complex root symbols given
2319 either before or after the associated number (but will detect any invalid
2320 arrangement):
2321 \begin{LaTeXdemo}
2322 \complexnum{9.99 + 88.8i} \\
2323 \complexnum{9.99 + i88.8}
2324 \end{LaTeXdemo}
2325
2326 \DescribeOption{output-complex-root}
2327 The output complex root symbol is independent of the input and can be changed
2328 using the \opt{output-complex-root} setting.
2329 \begin{LaTeXdemo}
2330 \complexnum[output-complex-root = i]{1+2i} \\
2331 \complexnum[output-complex-root = j]{1+2i}
2332 \end{LaTeXdemo}
2333
2334 \DescribeOption{complex-root-position}
2335 The position of the complex root can be adjusted to place it
2336 either before or after the associated numeral in a complex number
2337 using the \opt{complex-root-position} option.
2338 \begin{LaTeXdemo}
2339 \complexnum{67-0.9i} \\
2340 \complexnum[complex-root-position = before-number]{67-0.9i} \\
2341 \complexnum[complex-root-position = after-number]{67-0.9i}
2342 \end{LaTeXdemo}
2343
2344 \DescribeOption{complex-angle-unit}
2345 \DescribeOption{complex-symbol-degree}
2346 \DescribeOption{complex-phase-command}
2347 When printing or converting to polar form, the angle may be interpreted in
2348 units set by \opt{complex-angle-unit}: one of \opt{degrees} or \opt{radians}.
2349 The unit symbol used for degrees is controlled by \opt{complex-symbol-degree}.
2350 To allow control of the surrounding of the entire phase part, the option
2351 \opt{complex-phase-command} is available. This can be used for example to
2352 print using Steinmetz notation (which requires the \pkg{steinmetz} package).
2353 \begin{LaTeXdemo}
2354 \complexqty{1:1}{\ohm} \\
2355 \complexqty[complex-angle-unit = radians]{1:1}{\ohm} \\
2356 \complexqty[complex-symbol-degree = d]{1:1}{\ohm} \\
2357 \complexqty[complex-phase-command = \phase]{1:1}{\ohm}
2358 \end{LaTeXdemo}
2359
2360 \DescribeOption{print-complex-unity}
2361 When the complex part of a number is exactly \num{1}, it is possible to either
2362 print or suppress the value. This is controlled by the switch
2363 \opt{print-complex-unity}.
2364 \begin{LaTeXdemo}
2365 \complexqty{1i}{\ohm} \\
2366 \complexqty[print-complex-unity]{1i}{\ohm}
2367 \end{LaTeXdemo}
2368
2369 \subsection{Angles}
2370
2371 Angle processing provided by the \cs{ang} function has a set of options which
2372 apply in addition to the general ones set up for number processing.
2373 \begin{table}
2374 \caption{Angle options.%
2375 \label{tab:opt:ang}}
2376 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
2377 \toprule
2378 \multicolumn{1}{@{}l}{Option name} &
2379 Type &
2380 \multicolumn{1}{l@{}}{Default} \\
2381 \midrule
2382 angle-mode & Choice & input \\
2383 angle-symbol-degree & Literal & \cs{degree} \\
2384 angle-symbol-minute & Literal & \cs{arcminute} \\
2385 angle-symbol-over-decimal & Switch & false \\
2386 angle-symbol-second & Literal & \cs{arcsecond} \\
2387 angle-separator & Literal & \meta{empty} \\
2388 fill-angle-degrees & Switch & false \\
2389 fill-angle-minutes & Switch & false \\
2390 fill-angle-seconds & Switch & false \\
2391 \bottomrule
2392 \end{tabular}
2393 \end{table}
2394
2395 \DescribeOption{angle-mode}
2396 The format in which angles are printed can be set using the \opt{angle-mode}
2397 option. With the standard setting (\opt{input}), the angle is printed as-given.
2398 By setting the option to \opt{arc} or \opt{decimal}, the output format can
2399 be set to an arc (degrees/minutes/seconds) or decimal value. Conversion uses
2400 the \LaTeX3 floating-point unit, so is limited to $16$ decimal places.
2401 \begin{LaTeXdemo}
2402 \ang{2.67} \\
2403 \ang{2;3;4} \\
2404 \ang[angle-mode = arc]{2.67} \\
2405 \ang[angle-mode = arc]{2;3;4} \\
2406 \ang[angle-mode = decimal]{2.67} \\
2407 \ang[angle-mode = decimal]{2;3;4} \\
2408 \end{LaTeXdemo}
2409 When integer angles are converted to arc format, the presence of minute and
2410 second components is controlled by the options \opt{fill-angle-minutes} and
2411 \opt{fill-angle-seconds} (see below).
2412
2413 \DescribeOption{angle-separator}
2414 When angles are printed in arc format, the separation of the different parts is
2415 set up using the \opt{arc-separator} option.
2416 \begin{LaTeXdemo}
2417 \ang{6;7;6.5} \\
2418 \ang[angle-separator = \,]{6;7;6.5}
2419 \end{LaTeXdemo}
2420
2421 \DescribeOption{fill-angle-degrees}
2422 \DescribeOption{fill-angle-minutes}
2423 \DescribeOption{fill-angle-seconds}
2424 Zero-filling for the degree, minute or second parts of an arc is controlled
2425 using the \opt{fill-angle-degrees}, \opt{fill-angle-minutes} and
2426 \opt{fill-angle-seconds} options. All are off as standard.
2427 \begin{LaTeXdemo}
2428 \ang{-1;;} \\
2429 \ang{;-2;} \\
2430 \ang{;;-3} \\
2431 {
2432 \sisetup{fill-angle-degrees}
2433 \ang{-1;;} \\
2434 \ang{;-2;} \\
2435 \ang{;;-3} \\
2436 }
2437 {
2438 \sisetup{fill-angle-minutes}
2439 \ang{-1;;} \\
2440 \ang{;-2;} \\
2441 \ang{;;-3} \\
2442 }
2443 {
2444 \sisetup{fill-angle-seconds}
2445 \ang{-1;;} \\
2446 \ang{;-2;} \\
2447 \ang{;;-3}
2448 }
2449 \end{LaTeXdemo}
2450
2451 \DescribeOption{angle-symbol-degree}
2452 \DescribeOption{angle-symbol-minute}
2453 \DescribeOption{angle-symbol-second}
2454 With the standard settings, the symbols used for arc angles are the unit
2455 commands \cs{degree}, \cs{arcminute} and \cs{arcsecond}. These can be altered
2456 using \opt{angle-symbol-degree}, \opt{angle-symbol-minute} and
2457 \opt{angle-symbol-second}. This is most likely to be used when the definition
2458 of the unit macros is altered, for example to set \cs{arcsecond} as
2459 \texttt{as} (see also Section~\ref{sec:hint:prefixangle}).
2460 \begin{LaTeXdemo}
2461 \ang{6;7;6.5} \\
2462 \sisetup{
2463 angle-symbol-degree = d ,
2464 angle-symbol-minute = m ,
2465 angle-symbol-second = s
2466 }
2467 \ang{6;7;6.5}
2468 \end{LaTeXdemo}
2469
2470 \DescribeOption{angle-symbol-over-decimal}
2471 In some subject areas, most notably astronomy, the angle symbols are given over
2472 the decimal marker, rather than at the end of the number. This behavior is
2473 available using the \opt{angle-symbol-over-decimal} option.
2474 \begin{LaTeXdemo}
2475 \ang{45.697} \\
2476 \ang{6;7;6.5} \\
2477 \ang[angle-symbol-over-decimal]{45.697} \\
2478 \ang[angle-symbol-over-decimal]{6;7;6.5}
2479 \end{LaTeXdemo}
2480
2481 \subsection{Durations}
2482
2483 Duration processing provided by the \cs{duration} function has a set of options
2484 which apply in addition to the general ones set up for number processing.
2485 \begin{table}
2486 \caption{Angle options.%
2487 \label{tab:opt:duration}}
2488 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
2489 \toprule
2490 \multicolumn{1}{@{}l}{Option name} &
2491 Type &
2492 \multicolumn{1}{l@{}}{Default} \\
2493 \midrule
2494 duration-mode & Choice & input \\
2495 duration-symbol-hour & Literal & \cs{hour} \\
2496 duration-symbol-minute & Literal & \cs{minute} \\
2497 duration-symbol-second & Literal & \cs{second} \\
2498 duration-separator & Literal & \verb*"\ " \\
2499 fill-duration-hours & Switch & false \\
2500 fill-duration-minutes & Switch & false \\
2501 fill-duration-seconds & Switch & false \\
2502 \bottomrule
2503 \end{tabular}
2504 \end{table}
2505
2506 \DescribeOption{duration-mode}
2507 The format in which durations are printed can be set using the \opt{duration-mode}
2508 option. With the standard setting (\opt{input}), the duration is printed as-given.
2509 By setting the option to \opt{component} or \opt{decimal}, the output format can
2510 be set to a component (hours/minutes/seconds) or decimal value. Conversion uses
2511 the \LaTeX3 floating-point unit, so is limited to $16$ decimal places.
2512 \begin{LaTeXdemo}
2513 \duration{8.56} \\
2514 \duration{8;33;36} \\
2515 \duration[duration-mode = component]{8.56} \\
2516 \duration[duration-mode = component]{8;33;36} \\
2517 \duration[duration-mode = decimal]{8.56} \\
2518 \duration[duration-mode = decimal]{8;33;36} \\
2519 \end{LaTeXdemo}
2520 When integer durations are converted to component format, the presence of minute
2521 and second components is controlled by the options \opt{fill-duration-minutes}
2522 and \opt{fill-duration-seconds} (see below).
2523
2524 \DescribeOption{duration-separator}
2525 When durations are printed in component format, the separation of the different
2526 parts is set up using the \opt{duration-separator} option.
2527 \begin{LaTeXdemo}
2528 \duration{6;7;6.5} \\
2529 \duration[duration-separator = {, }]{6;7;6.5}
2530 \end{LaTeXdemo}
2531
2532 \DescribeOption{fill-duration-hours}
2533 \DescribeOption{fill-duration-minutes}
2534 \DescribeOption{fill-duration-seconds}
2535 Zero-filling for the hour, minute or second components of durations is controlled
2536 using the \opt{fill-duration-hours}, \opt{fill-duration-minutes} and
2537 \opt{fill-duration-seconds} options. All are off as standard.
2538 \begin{LaTeXdemo}
2539 \duration{1;;} \\
2540 \duration{;2;} \\
2541 \duration{;;3} \\
2542 {
2543 \sisetup{fill-duration-hours}
2544 \duration{1;;} \\
2545 \duration{;2;} \\
2546 \duration{;;3} \\
2547 }
2548 {
2549 \sisetup{fill-duration-minutes}
2550 \duration{1;;} \\
2551 \duration{;2;} \\
2552 \duration{;;3} \\
2553 }
2554 {
2555 \sisetup{fill-duration-seconds}
2556 \duration{1;;} \\
2557 \duration{;2;} \\
2558 \duration{;;3}
2559 }
2560 \end{LaTeXdemo}
2561
2562 \DescribeOption{duration-unit-hour}
2563 \DescribeOption{duration-unit-minute}
2564 \DescribeOption{duration-unit-second}
2565 With the standard settings, the units used for durations are the commands
2566 \cs{hour}, \cs{minute} and \cs{second}. These can be altered using
2567 \opt{duration-unit-hour}, \opt{duration-unit-minute} and
2568 \opt{duration-unit-second}.
2569 \begin{LaTeXdemo}
2570 \duration{1;3;4.5} \\
2571 \sisetup{
2572 duration-unit-hour = d ,
2573 duration-unit-minute = m ,
2574 duration-unit-second = s
2575 }
2576 \duration{1;3;4.5}
2577 \end{LaTeXdemo}
2578
2579 \subsection{Creating units%
2580 \label{sec:units:creating}}
2581
2582 The various macro units are created at the start of the document. \pkg{siunitx}
2583 can define these such that they are only available for use within the \cs{unit}
2584 and \cs{qty} functions, or can make the unit macros available throughout the
2585 document body. There are a number of settings which control this creation
2586 process (Table~\ref{tab:opt:units:def}). As a result, these options all apply
2587 in the preamble only.
2588 \begin{table}
2589 \caption{Unit creation options.%
2590 \label{tab:opt:units:def}}
2591 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
2592 \toprule
2593 \multicolumn{1}{@{}l}{Option name} &
2594 Type &
2595 \multicolumn{1}{l@{}}{Default} \\
2596 \midrule
2597 free-standing-units & Switch & false \\
2598 overwrite-command & Switch & false \\
2599 space-before-unit & Switch & false \\
2600 unit-optional-argument & Switch & false \\
2601 use-xspace & Switch & false \\
2602 \bottomrule
2603 \end{tabular}
2604 \end{table}
2605
2606 \DescribeOption{free-standing-units}
2607 \DescribeOption{overwrite-functions}
2608 The \opt{free-standing-units} option controls whether the unit macros are
2609 usable outside of the \cs{unit} and \cs{qty} arguments. When this option is
2610 \opt{true}, \pkg{siunitx} creates the macros for general use. The standard
2611 method to achieve this does not overwrite any existing macros: this behavior
2612 can be altered using the \opt{overwrite-commands} switch. For technical
2613 reasons, when \opt{free-standing-units} is set \opt{false}, the names of unit
2614 macros still have to be defined: as such, they will be created if they do not
2615 exist, but will raise an error if used outside of the \cs{unit} and \cs{qty}
2616 arguments.
2617
2618 When using the approach of \enquote{free-standing} unit commands, only macros
2619 created using \cs{DeclareSIUnit} are defined generally. Thus prefixes and
2620 powers should be combined with the desired unit into a single free-standing
2621 command, for example
2622 \begin{LaTeXdemo}[code only]
2623 \DeclareSIUnit\kilometre{\kilo\metre}
2624 \end{LaTeXdemo}
2625
2626 \DescribeOption{space-before-unit}
2627 \DescribeOption{unit-optional-argument}
2628 \DescribeOption{use-xspace}
2629 When \enquote{free standing} unit macros are created, their behavior can be
2630 adjusted by a number of options. These are mainly intended for emulating the
2631 input syntax of older packages. The option \opt{unit-optional-argument} gives
2632 the same behavior for the inputs
2633 \begin{LaTeXdemo}[code only]
2634 \qty{10}{\metre}
2635 \end{LaTeXdemo}
2636 and
2637 \begin{LaTeXdemo}[code only]
2638 \metre[10].
2639 \end{LaTeXdemo}
2640 The \opt{space-before-unit} and \opt{use-xspace} options control the behavior
2641 at the \enquote{ends} of the unit macros. Activating \opt{space-before-unit}
2642 inserts the number--unit space before the unit is printed. This is suitable for
2643 the input syntax
2644 \begin{LaTeXdemo}[code only]
2645 30\metre
2646 \end{LaTeXdemo}
2647 but does mean that the unit macros are incorrectly spaced in running text. On
2648 the other hand, the \opt{use-xspace} option attempts to correctly space input
2649 such as
2650 \begin{LaTeXdemo}[code only]
2651 \metre is the symbol for metres.
2652 \end{LaTeXdemo}
2653
2654 \subsection{Using units}
2655
2656 Part of the power of \pkg{siunitx} is the ability to alter the output format
2657 for units without changing the input. The behavior of units is therefore
2658 controlled by a number of options which alter either the processing of units or
2659 the output directly (Table~\ref{tab:opt:units:out}).
2660 \begin{table}
2661 \centering
2662 \caption{Unit output options.%
2663 \label{tab:opt:units:out}}
2664 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
2665 \toprule
2666 \multicolumn{1}{@{}l}{Option name} &
2667 Type &
2668 \multicolumn{1}{l@{}}{Default} \\
2669 \midrule
2670 bracket-unit-denominator & Switch & true \\
2671 forbid-literal-units & Switch & false \\
2672 fraction-command & Literal & \cs{frac} \\
2673 inter-unit-product & Literal & \cs{,} \\
2674 parse-units & Switch & true \\
2675 per-mode & Choice & power \\
2676 per-symbol-script-correction & Literal & \cs{!} \\
2677 per-symbol & Literal & / \\
2678 power-half-as-sqrt & Switch & false \\
2679 qualifier-mode & Choice & subscript \\
2680 qualifier-phrase & Literal & \meta{empty} \\
2681 sticky-per & Switch & false \\
2682 unit-font-command & Literal & \cs{mathrm} \\
2683 \bottomrule
2684 \end{tabular}
2685 \end{table}
2686
2687 \DescribeOption{inter-unit-product}
2688 The separator between each unit is stored using the \opt{inter-unit-product}
2689 option. The standard setting is a thin space: another common choice is a
2690 centered dot. To get the correct spacing it is necessary to use
2691 |\ensuremath{{}\cdot{}}| in the latter case.
2692 \begin{LaTeXdemo}
2693 \unit{\farad\squared\lumen\candela} \\
2694 \unit[inter-unit-product = \ensuremath{{}\cdot{}}]
2695 {\farad\squared\lumen\candela}
2696 \end{LaTeXdemo}
2697
2698 \DescribeOption{per-mode}
2699 \DescribeOption{display-per-mode}
2700 \DescribeOption{inline-per-mode}
2701 \DescribeOption{per-symbol}
2702 \DescribeOption{fraction-command}
2703 \DescribeOption{bracket-unit-denominator}
2704 The handling of \cs{per} is altered using the \opt{per-mode} choice option. The
2705 standard setting is \opt{power}, meaning that \cs{per} generates reciprocal
2706 powers for units. Setting the option to \opt{fraction} uses the |\frac|
2707 function to typeset the positive and negative powers of a unit separately.
2708 The exact function can be adjusted using the \opt{fraction-command} option.
2709 \begin{LaTeXdemo}
2710 \unit{\joule\per\mole\per\kelvin} \\
2711 \unit{\metre\per\second\squared} \\
2712 \unit[per-mode = fraction]{\joule\per\mole\per\kelvin} \\
2713 \unit[per-mode = fraction]{\metre\per\second\squared}
2714 \end{LaTeXdemo}
2715 The closely-related \opt{power-positive-first} setting acts in the same way but
2716 places all of the positive powers before any negative ones.
2717 \begin{LaTeXdemo}
2718 \unit{\ampere\per\mole\second} \\
2719 \unit[per-mode = power-positive-first]
2720 {\ampere\per\mole\second}
2721 \end{LaTeXdemo}
2722 It is possible to use a symbol (usually |/|) to separate the two parts of a
2723 unit by setting \opt{per-mode} to \opt{symbol}; the symbol used is stored using
2724 the setting \opt{per-symbol}. This method for displaying units can be
2725 ambiguous, and so brackets are added unless \opt{bracket-unit-denominator} is
2726 set to \opt{false}. Notice that \opt{bracket-unit-denominator} only applies
2727 when \opt{per-mode} is set to \opt{symbol}.
2728 \begin{LaTeXdemo}
2729 \sisetup{per-mode = symbol}%
2730 \unit{\joule\per\mole\per\kelvin} \\
2731 \unit{\metre\per\second\squared} \\
2732 \unit[per-symbol = \ \text{div}\ ]{\joule\per\mole\per\kelvin} \\
2733 \unit[bracket-unit-denominator = false]{\joule\per\mole\per\kelvin}
2734 \end{LaTeXdemo}
2735 The often-requested (but mathematically invalid) \opt{repeated-symbol} option
2736 is also available to repeat the symbol for each \cs{per}.
2737 \begin{LaTeXdemo}
2738 \unit[per-mode = repeated-symbol]{\joule\per\mole\per\kelvin}
2739 \end{LaTeXdemo}
2740 The use of a symbol can be restricted to the case where exactly one is
2741 required: the setting \opt{single-symbol} will use a symbol if and only
2742 if there are one or more positive powers and exactly one negative power.
2743 In other cases, powers are used.
2744 \begin{LaTeXdemo}
2745 \sisetup{per-mode = single-symbol}
2746 \qty{10}{\per\metre} \\
2747 \qty{20}{\metre\per\second} \\
2748 \qty{30}{\joule\per\mole\per\kelvin}
2749 \end{LaTeXdemo}
2750 It is possible for the behavior of the \cs{per} function to depend on the
2751 prevailing math style. Setting either \opt{display-per-mode} or
2752 \opt{inline-per-mode} independently can be used to achieve this. For example,
2753 the following example will use the \opt{symbol} setting for in line math,
2754 and the \opt{fraction} setting when used in display math.
2755 \begin{LaTeXdemo}
2756 \sisetup{
2757 display-per-mode = fraction ,
2758 inline-per-mode = symbol
2759 }%
2760 $ \unit{\joule\per\mole\per\kelvin} $
2761 \[ \unit{\joule\per\mole\per\kelvin} \]
2762 \unit{\joule\per\mole\per\kelvin} \\
2763 $
2764 \displaystyle
2765 \unit{\joule\per\mole\per\kelvin}
2766 $
2767 \[
2768 \textstyle
2769 \unit{\joule\per\mole\per\kelvin}
2770 \]
2771 \end{LaTeXdemo}
2772
2773 \DescribeOption{per-symbol-script-correction}
2774 When using the \opt{symbol} setting for \opt{per-mode}, there may the need to
2775 adjust spacing between a superscript power and the symbol. This is provided as
2776 a command to be inserted between the two items: the standard value is a thin
2777 negative space, \cs{!}.
2778 \begin{LaTeXdemo}
2779 \sisetup{per-mode = symbol}%
2780 \unit{\cm\cubed\per\gram} \\
2781 \unit[per-symbol-script-correction = ]{\cm\cubed\per\gram}
2782 \end{LaTeXdemo}
2783
2784 \DescribeOption{sticky-per}
2785 By default, \cs{per} applies only to the next unit given.\footnote{This is the
2786 standard method of reading units in English: for example,
2787 \unit{\joule\per\mole\per\kelvin} is pronounced \enquote{joules per mole per
2788 kelvin}.} By setting the \opt{sticky-per} flag, this behavior is changed so
2789 that \cs{per} applies to all subsequent units.
2790 \begin{LaTeXdemo}
2791 \unit{\pascal\per\gray\henry} \\
2792 \unit[sticky-per]{\pascal\per\gray\henry}
2793 \end{LaTeXdemo}
2794
2795 \DescribeOption{qualifier-mode}
2796 \DescribeOption{qualifier-phrase}
2797 Unit qualifiers can be printed in three different formats, set by the
2798 \opt{qualifier-mode} option. The standard setting is \opt{subscript}, while the
2799 options \opt{bracket}, \opt{combine} and \opt{phrase} are also possible. With
2800 the last settings, powers can lead to ambiguity and are automatically detected
2801 and brackets added as appropriate.
2802 \begin{LaTeXdemo}
2803 \unit{\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour} \\
2804 \unit[qualifier-mode = bracket]
2805 {\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour} \\
2806 \unit[qualifier-mode = combine]
2807 {\deci\bel\of{i}}
2808 \end{LaTeXdemo}
2809 The \opt{phrase} option is used with \opt{qualifier-phrase}, which allows for
2810 example a space or other linking text to be inserted.
2811 \begin{LaTeXdemo}
2812 \sisetup{qualifier-mode = phrase, qualifier-phrase = \ }%
2813 \unit{\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour} \\
2814 \sisetup{qualifier-phrase = \ \mbox{of}\ }%
2815 \unit{\kilogram\of{pol}\squared\per\mole\of{cat}\per\hour}
2816 \end{LaTeXdemo}
2817
2818 \DescribeOption{power-half-as-sqrt}
2819 In some cases, the power of $0.5$ is shown by giving the unit symbol as a
2820 square root. This can be enabled by setting \opt{power-half-as-sqrt} to
2821 \opt{true}
2822 \begin{LaTeXdemo}
2823 \unit{\Hz\tothe{0.5}} \\
2824 \unit[power-half-as-sqrt]{\Hz\tothe{0.5}}
2825 \end{LaTeXdemo}
2826
2827 \DescribeOption{parse-units}
2828 Normally, \pkg{siunitx} is used with the unit parse enabled, and only prints
2829 units directly if there is literal input. However, if the input is known to be
2830 essentially consistent and high performance is desired, then the parser can be
2831 turned off using the \opt{parse-units} switch.
2832 \begin{LaTeXdemo}
2833 \qty{300}{\MHz} \\
2834 \qty[parse-units = false]{300}{\MHz}
2835 \end{LaTeXdemo}
2836
2837 \DescribeOption{forbid-literal-units}
2838 Some users may prefer to completely disable the use of literal input in units,
2839 for example to enforce consistency. This can be accomplished by setting the
2840 \opt{forbid-literal-units} switch. With this option enabled, only macro-based
2841 units can be used in a document. This only applies when \opt{parse-units} is
2842 \opt{true}.
2843
2844 \DescribeOption{unit-font-command}
2845 The command used to set unit themselves may be adjusted using the
2846 \opt{unit-font-command} option. This is typically set to |\mathrm|.
2847 \begin{LaTeXdemo}
2848 \unit{\lumen} \\
2849 \unit[unit-font-command = \mathit]{\lumen}
2850 \end{LaTeXdemo}
2851
2852 \subsection{Quantities}
2853
2854 Some options apply to quantities (the combination of a number and a unit),
2855 rather than to the numbers or units alone (Table~\ref{tab:opt:quantities}).
2856 \begin{table}
2857 \centering
2858 \caption{Options for quantities.%
2859 \label{tab:opt:quantities}}
2860 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
2861 \toprule
2862 \multicolumn{1}{@{}l}{Option name} &
2863 Type &
2864 \multicolumn{1}{@{}l}{Default} \\
2865 \midrule
2866 allow-quantity-breaks & Switch & false \\
2867 extract-mass-in-kilograms & Switch & true \\
2868 prefix-mode & Choice & input \\
2869 quantity-product & Literal & \cs{,} \\
2870 separate-uncertainty-units & Choice & bracket \\
2871 \bottomrule
2872 \end{tabular}
2873 \end{table}
2874
2875 \DescribeOption{allow-quantity-breaks}
2876 Usually, the combination of a number and unit is regarded as a single
2877 mathematical entity which should not be split across lines. However, there are
2878 cases (very long units, narrow columns, \foreign{etc}.) where breaks may be
2879 needed. This can be turned on using the \opt{allow-quantity-breaks} option.
2880 \begin{LaTeXdemo}
2881 \begin{minipage}{3cm}
2882 % Gives an underfull hbox
2883 X\hspace{2.4cm}\qty{10}{\metre} \\
2884 \sisetup{allow-quantity-breaks}
2885 X\hspace{2.4cm}\qty{10}{\metre}
2886 \end{minipage}
2887 \end{LaTeXdemo}
2888
2889 \DescribeOption{quantity-product}
2890 The product symbol between the number and unit is set using the
2891 \opt{quantity-product} option.
2892 \begin{LaTeXdemo}
2893 \qty{2.67}{\farad} \\
2894 \qty[quantity-product = \ ]{2.67}{\farad} \\
2895 \qty[quantity-product = ]{2.67}{\farad}
2896 \end{LaTeXdemo}
2897
2898 \DescribeOption{prefix-mode}
2899 \DescribeOption{extract-mass-in-kilograms}
2900 The unit prefixes (\cs{kilo}, \foreign{etc}.) are normally given as letters.
2901 However, the package can convert these into numerical powers. This is
2902 controlled by the \opt{prefix-mode} option, which takes the values \opt{input},
2903 \opt{combine-exponent} and \opt{extract-exponent}. The \opt{input} setting
2904 leaves the prefixes unchanged. Using \opt{combine-exponent} will add any
2905 exponent amount from the number to the first unit: this will modify any
2906 existing prefix. Finally, using \opt{extract-exponent} will remove all prefixes
2907 and express them as an exponent. The treatment of kilograms in this case can be
2908 set using \opt{extract-mass-in-kilograms}: when \opt{true}, the \emph{kilo}
2909 prefix is retained as part of the unit. This will mean that all grams are
2910 converted to kilograms.
2911 \begin{LaTeXdemo}
2912 \qty{1e3}{\metre\second} \\
2913 \qty[prefix-mode = combine-exponent]{1e3}{\metre\second} \\
2914 \qty{10}{\kilo\gram\squared\deci\second} \\
2915 \qty[prefix-mode = extract-exponent]{10}{\kilo\gram\squared\deci\second}\\
2916 \qty[prefix-mode = extract-exponent]{7.5}{\gram} \\
2917 \sisetup{extract-mass-in-kilograms = false}
2918 \qty{10}{\kilo\gram\squared\deci\second} \\
2919 \qty[prefix-mode = extract-exponent]{10}{\kilo\gram\squared\deci\second} \\
2920 \qty[prefix-mode = extract-exponent]{7.5}{\gram} \\
2921 \end{LaTeXdemo}
2922 This option does not apply to units \cs{degree}, \cs{arcminute}, \cs{arcsecond}
2923 and \cs{percent}.
2924
2925 \DescribeOption{separate-uncertainty-units}
2926 When a number has multiple parts (such as a separate uncertainty) then the unit
2927 must apply to all parts of the number. How this is shown is controlled using
2928 the \opt{separate-uncertainty-units} options. The standard setting is
2929 \opt{brackets}, which will place the entire numerical part in brackets and use
2930 a single unit symbol. Alternative options are \opt{repeat} (print the unit for
2931 each part of the number) and \opt{single} (print only one unit symbol:
2932 mathematically incorrect).
2933 \begin{LaTeXdemo}
2934 \sisetup{uncertainty-mode = separate}
2935 \qty{12.3(4)}{\kilo\gram} \\
2936 \qty[separate-uncertainty-units = bracket]{12.3(4)}{\kilo\gram} \\
2937 \qty[separate-uncertainty-units = repeat]{12.3(4)}{\kilo\gram} \\
2938 \qty[separate-uncertainty-units = single]{12.3(4)}{\kilo\gram}
2939 \end{LaTeXdemo}
2940
2941 \subsection{Tabular material}
2942
2943 Processing of material in tables obeys the same settings as described for the
2944 functions already described. However, there are some settings which apply only
2945 to the layout of tabular material (Table~\ref{tab:opt:tables}).
2946 \begin{table}
2947 \caption{Options for tabular material.%
2948 \label{tab:opt:tables}}
2949 \begin{tabular}{@{}>{\ttfamily}ll>{\ttfamily}l@{}}
2950 \toprule
2951 \multicolumn{1}{@{}l}{Option name} &
2952 Type &
2953 \multicolumn{1}{l@{}}{Default} \\
2954 \midrule
2955 table-align-comparator & Switch & true \\
2956 table-align-exponent & Switch & true \\
2957 table-align-text-after & Switch & true \\
2958 table-align-text-before & Switch & true \\
2959 table-align-uncertainty & Switch & true \\
2960 table-alignment & Meta & center \\
2961 table-alignment-mode & Choice & marker \\
2962 table-auto-round & Switch & false \\
2963 table-column-width & Length & 0pt \\
2964 table-fixed-width & Switch & false \\
2965 table-format & Special & 2.2 \\
2966 table-model-setup & Literal & \meta{empty} \\
2967 table-number-alignment & Choice & center \\
2968 table-text-alignment & Choice & center \\
2969 \bottomrule
2970 \end{tabular}
2971 \end{table}
2972
2973 \DescribeOption{table-alignment-mode}
2974 The method used by \pkg{siunitx} to align numbers is selected using the
2975 \opt{table-alignment-mode} option, which may be one of \opt{marker},
2976 \opt{format} or \meta{none}. With the standard setting, \opt{marker}, the
2977 package centers the decimal marker in a tabular column, potentially leaving
2978 white space at the shorter end of a number. The \opt{format} mode uses
2979 information from the \opt{table-format} key to construct a model: this is then
2980 used to define the space available to a number. For asymmetrical numbers, this
2981 method is strongly preferable. Finally, \opt{none} disables alignment entirely:
2982 numbers are simply parsed.
2983
2984 \DescribeOption{table-number-alignment}
2985 When \opt{table-alignment-mode} is set to \opt{format} or \opt{none}, the
2986 placement of the number \enquote{block} within the cell as a whole is set by
2987 the \opt{table-number-alignment} option, which may be one of \opt{left},
2988 \opt{center} or \opt{right}. (When \opt{table-alignment-mode} is set to
2989 \opt{marker}, the decimal marker is always centered in the cell.) The
2990 different alignment choices are illustrated in Table~\ref{tab:S:align}, which
2991 uses somewhat exaggerated column headings to show the relative position of the
2992 cell contents.
2993 \begin{LaTeXdemo}[code and float]
2994 \begin{table}
2995 \caption{Aligning the \texttt{S} column.%
2996 \label{tab:S:align}}
2997 \centering
2998 \sisetup{table-format = 2.4, table-alignment-mode = format}
2999 \begin{tabular}{@{}
3000 S[table-alignment-mode = marker]
3001 S[table-number-alignment = center]
3002 S[table-number-alignment = left]
3003 S[table-number-alignment = right]
3004 @{}}
3005 \toprule
3006 {Some Values} & {Some Values} & {Some Values} & {Some Values} \\
3007 \midrule
3008 2.3456 & 2.3456 & 2.3456 & 2.3456 \\
3009 34.2345 & 34.2345 & 34.2345 & 34.2345 \\
3010 56.7835 & 56.7835 & 56.7835 & 56.7835 \\
3011 90.473 & 90.473 & 90.473 & 90.473 \\
3012 \bottomrule
3013 \end{tabular}
3014 \end{table}
3015 \end{LaTeXdemo}
3016 When the alignment mode is set to \opt{none}, number are simply collected and
3017 parsed without any further processing, as illustrated in
3018 Table~\ref{tab:S:parse}.
3019 \begin{LaTeXdemo}[code and float]
3020 \begin{table}
3021 \caption{Parsing without aligning in an \texttt{S} column.%
3022 \label{tab:S:parse}}
3023 \begin{tabular}
3024 {@{}
3025 S
3026 S[table-alignment-mode = none]
3027 @{}}
3028 \toprule
3029 {Decimal-centered} &
3030 {Simple centering} \\
3031 \midrule
3032 12.345 & 12.345 \\
3033 6,78 & 6,78 \\
3034 -88.8(9) & -88.8(9) \\
3035 4.5e3 & 4.5e3 \\
3036 \bottomrule
3037 \end{tabular}
3038 \end{table}
3039 \end{LaTeXdemo}
3040
3041 \DescribeOption{table-format}
3042 When the \opt{table-alignment-mode} is set to \opt{format}, \pkg{siunitx} uses
3043 the information set in \opt{table-format} to construct a \enquote{model} which
3044 defines the space to reserve for a number. The \opt{table-format} key is
3045 interpreted in much the same way as a table cell. The numerical part should
3046 consist of a number showing how many figures to reserve in each part of the
3047 input, plus any comparators, signs, \foreign{etc.} A variety of examples are
3048 given in Table~\ref{tab:S:format}.
3049 \begin{LaTeXdemo}[code and float]
3050 \begin{table}
3051 \caption{Reserving space in \texttt{S} columns.%
3052 \label{tab:S:format}}
3053 \sisetup{
3054 table-alignment-mode = format,
3055 table-number-alignment = center,
3056 }
3057 \begin{tabular}{@{}
3058 S[table-format = 2.2]
3059 S[table-format = 2.2, table-number-alignment = right]
3060 S[table-format = 2.2(1)]
3061 S[table-format = 2.2(1), uncertainty-mode = separate]
3062 S[table-format = +2.2]
3063 S[table-format = 2.2e1]
3064 @{}}
3065 \toprule
3066 {Values}
3067 & {Values}
3068 & {Values}
3069 & {Values}
3070 & {Values}
3071 & {Values} \\
3072 \midrule
3073 2.3 & 2.3 & 2.3(5) & 2.3(5) & 2.3 & 2.3e8 \\
3074 34.23 & 34.23 & 34.23(4) & 34.23(4) & 34.23 & 34.23 \\
3075 56.78 & 56.78 & 56.78(3) & 56.78(3) & -56.78 & 56.78e3 \\
3076 3,76 & 3,76 & 3,76(2) & 3.76(2) & +-3.76 & e6 \\
3077 \bottomrule
3078 \end{tabular}
3079 \end{table}
3080 \end{LaTeXdemo}
3081 It is important to note that any parts of a number \emph{not} specified in the
3082 table format argument are set to be absent (the number of figures is set to
3083 zero). Setting the \opt{table-format} option also resets
3084 \opt{table-alignment-mode} to \opt{format}.
3085
3086 \DescribeOption{table-model-setup}
3087 In some tables (particularly those using bold extended fonts), it may be
3088 necessary to insert additional information when creating the \enquote{model}.
3089 This is handled using the \opt{table-model-setup} key. An example of the use of
3090 this key is given in Section~\ref{sec:hint:heading}.
3091
3092 Space for material before and after the \texttt{S} column can be reserved by
3093 giving model text as part of the \opt{table-format} key. This is then used to
3094 provide the necessary gap while maintaining alignment (Table~\ref{tab:S:ends}).
3095 \begin{LaTeXdemo}[code and float]
3096 \begin{table}
3097 \caption{Text before and after numbers.%
3098 \label{tab:S:ends}}
3099 \sisetup{table-format = {now }2.4{\textsuperscript{\emph{a}}}}
3100 \begin{tabular}{@{}S@{}}
3101 \toprule
3102 {Values} \\
3103 \midrule
3104 2.3456 \\
3105 34.2345 \textsuperscript{\emph{a}}\\
3106 56.7835 \\
3107 now~ 90.473 \\
3108 \bottomrule
3109 \end{tabular}
3110 \end{table}
3111 \end{LaTeXdemo}
3112
3113 \DescribeOption{table-align-exponent}
3114 \DescribeOption{table-align-uncertainty}
3115 \DescribeOption{table-align-comparator}
3116 When printing exponents in tables, there is a choice of aligning the exponent
3117 parts or having these close up to the mantissa. This is controlled by the
3118 \opt{table-align-exponent} option (Table~\ref{tab:align:exp}). Similarly,
3119 uncertainty parts which are printed separately from the mantissa can be aligned
3120 or closed up. This is set by the \opt{table-align-uncertainty} option
3121 (Table~\ref{tab:align:uncert}). Finally, the same approach is available for the
3122 comparator with the \opt{table-align-comparator} option
3123 (Table~\ref{tab:align:comp}).
3124 \begin{LaTeXdemo}[code and float]
3125 \begin{table}
3126 \caption{The \opt{table-align-exponent} option.%
3127 \label{tab:align:exp}}
3128 \sisetup{table-format = 1.3e2}
3129 \begin{tabular}{@{}SS[table-align-exponent = false]@{}}
3130 \toprule
3131 {Header} & {Header} \\
3132 \midrule
3133 1.2e3 & 1.2e3 \\
3134 1.234e56 & 1.234e56 \\
3135 \bottomrule
3136 \end{tabular}
3137 \end{table}
3138 \end{LaTeXdemo}
3139 \begin{LaTeXdemo}[code and float]
3140 \begin{table}
3141 \caption{The \opt{table-align-uncertainty} option.%
3142 \label{tab:align:uncert}}
3143 \sisetup{
3144 uncertainty-mode = separate,
3145 table-format = 1.3(1),
3146 }
3147 \begin{tabular}{@{}SS[table-align-uncertainty = false]@{}}
3148 \toprule
3149 {Header} & {Header} \\
3150 \midrule
3151 1.2(1) & 1.2(3) \\
3152 1.234(5) & 1.234(5) \\
3153 \bottomrule
3154 \end{tabular}
3155 \end{table}
3156 \end{LaTeXdemo}
3157 \begin{LaTeXdemo}[code and float]
3158 \begin{table}
3159 \caption{The \opt{table-align-comparator} option.%
3160 \label{tab:align:comp}}
3161 \sisetup{table-format = >2.2}
3162 \begin{tabular}{@{}SS[table-align-comparator = false]@{}}
3163 \toprule
3164 {Header} & {Header} \\
3165 \midrule
3166 > 1.2 & > 1.2 \\
3167 < 12.34 & < 12.34 \\
3168 \bottomrule
3169 \end{tabular}
3170 \end{table}
3171 \end{LaTeXdemo}
3172
3173 \DescribeOption{table-align-text-before}
3174 \DescribeOption{table-align-text-after}
3175 Note markers are often given in tables after the numerical content. It may be
3176 desirable for these to close up to the numbers. Whether this takes place is
3177 controlled by the \opt{table-align-text-before} and \opt{\ldots-after}
3178 option (Table~\ref{tab:S:notes}).
3179 \begin{LaTeXdemo}[code and float]
3180 \begin{table}
3181 \caption{Closing notes up to text.%
3182 \label{tab:S:notes}}
3183 \newrobustcmd\NoteMark[1]{%
3184 \textsuperscript{\emph{#1}}%
3185 }
3186 \sisetup{table-format = {\NoteMark{a}}2.4}
3187 \begin{tabular}{@{}
3188 S
3189 S[table-align-text-before = false]
3190 @{}}
3191 \toprule
3192 {Values} & {Values} \\
3193 \midrule
3194 2.3456 & 2.3456 \\
3195 \NoteMark{a} 4.234 & \NoteMark{a} 4.234 \\
3196 \NoteMark{b} .78 & \NoteMark{b} .78 \\
3197 \NoteMark{d} 88 & \NoteMark{d} 88 \\
3198 \bottomrule
3199 \end{tabular}
3200 \hspace{\fill}%
3201 \sisetup{table-format = 2.4\NoteMark{a}}
3202 \begin{tabular}{@{}
3203 S
3204 S[table-align-text-after = false]
3205 @{}}
3206 \toprule
3207 {Values} & {Values} \\
3208 \midrule
3209 2.3456 & 2.3456 \\
3210 34.234 \NoteMark{a} & 34.234 \NoteMark{a} \\
3211 56.78 \NoteMark{b} & 56.78 \NoteMark{b} \\
3212 90.4 \NoteMark{c} & 90.4 \NoteMark{c} \\
3213 88 \NoteMark{d} & 88 \NoteMark{d} \\
3214 \bottomrule
3215 \end{tabular}
3216 \end{table}
3217 \end{LaTeXdemo}
3218
3219 \DescribeOption{table-auto-round}
3220 The contents of table cells can automatically be rounded or zero-filled to the
3221 number of decimal digits given for the decimal part of the \opt{table-format}
3222 option. This mode is activated using the \opt{table-auto-round} switch, as
3223 illustrated in Table~\ref{tab:S:auto}.
3224 \begin{LaTeXdemo}[code and float]
3225 \begin{table}
3226 \centering
3227 \caption{The \opt{table-auto-round} option.%
3228 \label{tab:S:auto}}
3229 \sisetup{table-format = 1.3}
3230 \begin{tabular}{@{}SS[table-auto-round]@{}}
3231 \toprule
3232 {Header} & {Header} \\
3233 \midrule
3234 1.2 & 1.2 \\
3235 1.2345 & 1.2345 \\
3236 \bottomrule
3237 \end{tabular}
3238 \end{table}
3239 \end{LaTeXdemo}
3240
3241 \DescribeOption{parse-numbers}
3242 When the \opt{parse-numbers} option is set to \opt{false}, then the alignment
3243 code for tables takes a different approach. The output is always set in math
3244 mode, and alignment takes place at the first decimal marker. This is achieved
3245 by making it active in math mode. When reserving space for content only the
3246 integer and decimal values for the mantissa are considered
3247 (Table~\ref{tab:S:nonparsed}).
3248 \begin{LaTeXdemo}[code and float]
3249 \begin{table}
3250 \caption{Aligning without parsing.%
3251 \label{tab:S:nonparsed}}
3252 \sisetup{
3253 parse-numbers = false,
3254 table-format = 3.3
3255 }
3256 \centering
3257 \begin{tabular}{@{}
3258 S
3259 S[table-number-alignment = center]
3260 S[table-number-alignment = right]
3261 S[table-number-alignment = left]
3262 @{}}
3263 \toprule
3264 {Some values}
3265 & {Some values}
3266 & {Some values}
3267 & {Some values} \\
3268 \midrule
3269 2.35 & 2.35 & 2.35 & 2.35 \\
3270 34.234 & 34.234 & 34.234 & 34.234 \\
3271 56.783 & 56.783 & 56.783 & 56.783 \\
3272 3,762 & 3,762 & 3,762 & 3.762 \\
3273 \sqrt{2} & \sqrt{2} & \sqrt{2} & \sqrt{2} \\
3274 \bottomrule
3275 \end{tabular}
3276 \end{table}
3277 \end{LaTeXdemo}
3278
3279 \DescribeOption{drop-exponent}
3280 In cases where data cover a range of values, printing using a fixed exponent in
3281 a table may make presentation clearer. In these cases, dropping the exponent
3282 value from the table is useful. The general numerical options \opt{drop-exponent}
3283 combined with \opt{exponent-mode = fixed} can be used to achieve this
3284 (Table~\ref{tab:exp:omit}).
3285 \begin{LaTeXdemo}[code and float]
3286 \begin{table}
3287 \caption{The \opt{drop-exponent} option.%
3288 \label{tab:exp:omit}}
3289 \begin{tabular}{@{}
3290 S[table-format = 1.1e1]
3291 S[
3292 drop-exponent = true,
3293 exponent-mode = fixed,
3294 fixed-exponent = 3,
3295 table-format = 2.1,
3296 ]
3297 @{}}
3298 \toprule
3299 {Header} &
3300 \multicolumn{1}{c@{}}{Header / \num[print-unity-mantissa = false]{e3}} \\
3301 \midrule
3302 1.2e3 & 1.2e3 \\
3303 3e2 & 3e2 \\
3304 1.0e4 & 1.0e4 \\
3305 \bottomrule
3306 \end{tabular}
3307 \end{table}
3308 \end{LaTeXdemo}
3309
3310 \DescribeOption{table-column-width}
3311 \DescribeOption{table-fixed-width}
3312 Usually, the width of the numerical column is allowed to vary depending on the
3313 content. However, there are cases where a strictly fixed width is desirable.
3314 For these cases, the \opt{table-fixed-width} and \opt{table-column-width}
3315 options are available. The \opt{table-fixed-width} option activates fixed-width
3316 columns, whilst \opt{table-column-width} defines the target width
3317 (Table~\ref{tab:width:fixed}). Setting \opt{table-column-width} to a positive
3318 value automatically enables \opt{table-fixed-width}.
3319 \begin{LaTeXdemo}[code and float]
3320 \begin{table}
3321 \caption{Fixed-width columns.%
3322 \label{tab:width:fixed}}
3323 \begin{tabular}
3324 {@{}
3325 S
3326 S[table-column-width = 2cm]
3327 @{}}
3328 \toprule
3329 {Flexible} &
3330 {Fixed} \\
3331 \midrule
3332 1.23 & 1.23 \\
3333 45.6 & 45.6 \\
3334 \bottomrule
3335 \end{tabular}
3336 \end{table}
3337 \end{LaTeXdemo}
3338
3339 The \opt{table-column-width} option can also be used to achieve special
3340 effects. One example is centring a column of numbers under a wide heading, with
3341 the numbers themselves right-aligned (Table~\ref{tab:width:special}).
3342 \begin{LaTeXdemo}[code and float]
3343 \begin{table}
3344 \centering
3345 \caption{Right-aligning under a heading.%
3346 \label{tab:width:special}}
3347 \settowidth{\mylength}{Long header}
3348 \sisetup{
3349 table-alignment-mode = none ,
3350 table-column-width = \mylength ,
3351 table-number-alignment = right
3352 }
3353 \begin{tabular}{@{}S@{}}
3354 \toprule
3355 {Long header} \\
3356 \midrule
3357 12.33 \\
3358 2 \\
3359 1234 \\
3360 \bottomrule
3361 \end{tabular}
3362 \end{table}
3363 \end{LaTeXdemo}
3364
3365 \DescribeOption{table-text-alignment}
3366 \DescribeOption{table-alignment}
3367 Cell contents which are not part of a number can be protected using braces, as
3368 illustrated. Cells which contain no numerical data at all are aligned using the
3369 setting specified by the \opt{table-text-alignment} option, which recognises
3370 the values \opt{center}, \opt{left}, \opt{none} and \opt{right}
3371 (Table~\ref{tab:S:text}). The setting \opt{none} is intended for use with
3372 the package \pkg{tabularray}, which carries out its own alignment of textual
3373 values.
3374 \begin{LaTeXdemo}[code and float]
3375 \begin{table}
3376 \caption{Aligning text in \texttt{S} columns.%
3377 \label{tab:S:text}}
3378 \sisetup{table-format = 4.4}
3379 \centering
3380 \begin{tabular}{@{}
3381 S
3382 S[table-text-alignment = left]
3383 S[table-text-alignment = right]
3384 @{}}
3385 \toprule
3386 {Values}
3387 & {Values}
3388 & {Values} \\
3389 \midrule
3390 992.435 & 992.435 & 992.435 \\
3391 7734.2344 & 7734.2344 & 7734.2344 \\
3392 56.7834 & 56.7834 & 56.7834 \\
3393 3,7462 & 3,7462 & 3,7462 \\
3394 \bottomrule
3395 \end{tabular}
3396 \end{table}
3397 \end{LaTeXdemo}
3398
3399 \DescribeOption{table-alignment}
3400 The table alignment options \opt{table-number-alignment} and
3401 \opt{table-text-alignment} can be set to the same value using the
3402 \opt{table-alignment} option. This will set all three alignment options to the
3403 same value (one of \opt{center}, \opt{right} or \opt{left}).
3404
3405 \subsection{Locale options}
3406
3407 \DescribeOption{locale}
3408 \pkg{siunitx} allows the user to switch between the typographic conventions of
3409 different (geographical) areas by using locales. Currently, the package is
3410 supplied with configurations for locales \opt{UK}, \opt{US}, \opt{DE}
3411 (Germany), \opt{IT} (Italian), \opt{PL} (Poland), \opt{FR} (French), \opt{SI}
3412 (Slovene) and \opt{ZA} (South Africa). The \opt{locale} option is used to
3413 switch to a particular locale.
3414 \begin{LaTeXdemo}
3415 \qty{1.234}{\metre}\\
3416 \qty[locale = DE]{6.789}{\metre}
3417 \end{LaTeXdemo}
3418
3419 \subsection{Preamble-only options}
3420
3421 \DescribeOption{list-input-separator}
3422 \DescribeOption{product-input-separator}
3423 The separator between \emph{input} elements of lists (\cs{numlist},
3424 \cs{qtylist}) and products (\cs{numproduct}, \cs{qtyproduct}) can be adjusted
3425 using the options \opt{list-input-separator} and \opt{product-input-separator},
3426 respectively. These are load-time only options as the separator here is part of
3427 the \enquote{document interface} rather than part of the individual number(s).
3428 The supplied value should be a \emph{single} marker.
3429
3430 \DescribeOption{table-column-type}
3431 The letter(s) used to create table columns can be adjusted using the
3432 \opt{table-column-type} option. The standard setting is |S|, but one or more
3433 letters may be used: these must be single tokens. For example, provided the
3434 \pkg{numprint} package has not been loaded, the letter |n| could be used as
3435 this would suggest a numerical column.
3436
3437 \DescribeOption{disable-deprecated-commands}
3438 \DescribeOption{disable-deprecated-options}
3439 To allow users to require only interfaces from the current release, the options
3440 \opt{disable-deprecated-options} and \opt{disable-deprecated-commands} are
3441 available. Settings these to \opt{false} will disable options and document
3442 commands that have been removed from version~\version{3}, respectively.
3443
3444 \section{Significant new features updates}
3445
3446 Here, a short reminder for users of new features added since the release of
3447 version~\version{3} of the package is given.
3448
3449 \subsection{Version~\version{3.1}}
3450
3451 \begin{itemize}
3452 \item Extend support for complex numbers to cover polar form including
3453 new options to control output
3454 \item Parse and format multiple uncertainties; new options added
3455 to allow descriptions of each uncertainty
3456 \item Customisation of text sub/superscript output
3457 \item Selectable group size when dividing digits
3458 \item Finer controls for \enquote{per mode} output
3459 \item Support for negative zero values and controlled output for zero
3460 values
3461 \item Allow negative values to round to zero
3462 \item Addition unit abbreviations for capacitance, power and magnetic
3463 flux
3464 \item Portuguese locale
3465 \end{itemize}
3466
3467 \subsection{Version~\version{3.2}}
3468
3469 \begin{itemize}
3470 \item \enquote{Threshold} approach to producing exponent notation:
3471 similar to a calculator
3472 \item Finer control of printing plus signs using new options to split
3473 mantissa and exponent
3474 \item Support for updated prefixes introduced by \acro{bipm}
3475 \item Revised alignment of uncertainties in tabulars
3476 \end{itemize}
3477
3478 \subsection{Version~\version{3.3}}
3479
3480 \begin{itemize}
3481 \item Support for languages which need a begin as well as end phrase in
3482 ranges, \foreign{e.g.}~Italian, was added; this includes appropriate
3483 supporting options
3484 \item Support for asymmetric uncertainties (tolerances)
3485 \item Rounding extended to allow truncation (rounding down) for both
3486 main values and when using the uncertainty part
3487 \item Finer control of the appearance of brackets in ambiguous
3488 output introduced by adding options for different contexts
3489 \item Control of list and product input and output extended
3490 \item Finer control of table alignment setup for bold values
3491 \item New unit abbreviations for magnetic fields
3492 \end{itemize}
3493
3494 \subsection{Version~\version{3.4}}
3495
3496 \begin{itemize}
3497 \item Support uncertainties in seconds part of arc angles
3498 \item Control creation of minute and second components on conversion of
3499 integer angles to arc format
3500 \item Ability to simplify \enquote{asymmetric} uncertainties with
3501 equal components in both directions
3502 \item Combination of all control for angle unit formatting into
3503 \cs{degree}, \cs{arcminute} and \cs{arcsecond} unit macros,
3504 with \opt{number-angle-product} deprecated
3505 \item Support for more varied printing of complex numbers phases
3506 \end{itemize}
3507
3508 \subsection{Version~\version{3.5}}
3509
3510 \begin{itemize}
3511 \item New \cs{duration} command and supporting options
3512 \item Support for extending the last group of numbers to avoid a dangling
3513 digit
3514 \item Options to suppress interfaces from version~\version{2}
3515 \end{itemize}
3516
3517 \section{Upgrading from version~\version{2}%
3518 \label{sec:upgrading}}
3519
3520 The package has been largely re-written internally between versions \version{2}
3521 and \version{3}. A significant number of key--value settings have new, more
3522 descriptive, names. Where possible, older names are mapped to newer ones
3523 internally: you will be warned in the log if this is the case.
3524
3525 It is possible to use the \LaTeXe{} kernel mechanism to load the last
3526 version~\version{2} release for documents that cannot be successfully processed
3527 using version~\version{3}. This can be achieved using
3528 \begin{LaTeXdemo}[code only]
3529 \usepackage{siunitx}[=2021-04-09]
3530 \end{LaTeXdemo}
3531 or
3532 \begin{LaTeXdemo}[code only]
3533 \usepackage{siunitx}[=v2]
3534 \end{LaTeXdemo}
3535 This approach will work with older systems which still have version~\version{2}
3536 installed, meaning that you can reliably use it to work between systems with
3537 different versions of \pkg{siunitx}.
3538
3539 \begin{function}{\SI, \SIlist, \SIrange, \si}
3540 In version~\version{3}, the document commands have been revised to be more
3541 descriptive. As such, the commands \cs{SI}, \cs{SIlist}, \cs{SIrange} and
3542 \cs{si} remain available but are not recommended for use in new documents.
3543 Use the new \cs{qty\ldots} commands instead: they are clearer and in some
3544 cases very slightly faster.
3545 \end{function}
3546
3547 Some changes have been made to the semantics of commands or options. Most
3548 notably
3549 \begin{itemize}
3550 \item prefixes cannot now be given without units;
3551 \item prefixes can only be interconverted with numbers as part
3552 of a quantity, not as stand-alone units.
3553 \end{itemize}
3554 See Section~\ref{sec:hint:prefixes} for how to work with the new approach
3555 if you want to print prefix information.
3556
3557 The font control system has been completely re-written for version~\version{3}.
3558 The method used is entirely different from version~\version{2}. Emulation is
3559 therefore not provided for all outcomes: if you need non-standard font
3560 settings, you will need to adjust your source. See Section~\ref{sec:print} for
3561 more details on the options available in this area.
3562
3563 The input approach for version~\version{3} is slightly more structured and
3564 restricted than for version~\version{2}. As well as the updated names for
3565 document commands, this means that
3566 \begin{itemize}
3567 \item Products of numbers must now be given using the dedicated
3568 \cs{numproduct} and \cs{qtyproduct} commands;
3569 \item Quotients of numbers are only supported as literals;
3570 \item Complex values need to be given using the dedicated command
3571 \cs{complexnum}.
3572 \end{itemize}
3573 The option \opt{round-integer-to-decimal = false} has been removed, and whilst
3574 there is not a direct replacement, users are likely to find that \opt{round-pad
3575 = false} offers the desired outcome.
3576
3577 A new approach has been taken to providing non-Latin symbols for use in
3578 units: these are now handled directly where needed, for example in the
3579 definition of the \cs{micro} prefix.
3580
3581 Translation of fixed strings is now carried out using the \pkg{translations}
3582 package. If you have manually set up translations in version~\version{2} using
3583 \pkg{translator}, you will need to load it manually.
3584
3585 The letter used for a numerical tabular column can now be selected by the
3586 user: the letter |S| has been retained as the standard interface. The unit
3587 column (|s|) has been removed from this release. It can be emulated using
3588 the \pkg{collcell} package, for example
3589 \begin{LaTeXdemo}[code only]
3590 \usepackage{collcell}
3591 \newcolumntype{s}{>{\collectcell\unit}c<{\endcollectcell}}
3592 \end{LaTeXdemo}
3593 or
3594 \begin{LaTeXdemo}[code only]
3595 \usepackage{collcell}
3596 \newcolumntype{s}{>{\collectcell\si}c<{\endcollectcell}}
3597 \end{LaTeXdemo}
3598
3599 If you are using \opt{table-column-width} to have fixed-width columns, you
3600 also now need \opt{table-fixed-width} to set this option active.
3601
3602 Direct support for loading a local configuration file, \texttt{siunitx.cfg},
3603 has been removed. However, the approach described in
3604 Section~\ref{sec:hint:config} may be used to achieve the same effect with the
3605 additions more clearly shown in document sources.
3606
3607 The command \cs{SendSettingsToPgf} is deprecated, and should be replaced
3608 simply by setting the appropriate \cs{pgfkeys} in parallel to \cs{sisetup}.
3609
3610 \section{Unit changes made by \acro{BIPM}%
3611 \label{sec:BIPM8}}
3612
3613 In addition to the changes in the \pkg{siunitx} package described in
3614 Section~\ref{sec:upgrading}, there are changes in the units defined by the
3615 \acro{BIPM} in the 9th Edition of the \acro{SI} Brochure which are reflected
3616 here. There are two major areas of change.
3617
3618 The first is in respect of units accepted for use with \acro{SI} units. In the
3619 8th Edition of the \acro{SI} Brochure, the following units were listed as
3620 accepted for use in specialist fields
3621 \begin{itemize}
3622 \item ångström (\cs{angstrom})
3623 \item bar (\cs{bar})
3624 \item barn (\cs{barn})
3625 \item knot (\cs{knot})
3626 \item millimetre of mercury (\cs{mmHg})
3627 \item nautical mile (\cs{nauticalmile})
3628 \end{itemize}
3629 These are no longer listed in the 9th Edition, and so are deprecated as
3630 pre-defined units by \pkg{siunitx}. These units will issue a warning on first
3631 use, and users should add their own definitions to the start of their sources
3632 to avoid this.
3633
3634 Secondly, the move to a new definition of base units means that the table of
3635 units determined experimentally has been removed from the \acro{SI} Brochure.
3636 This covers the following units defined by \pkg{siunitx} in previous releases
3637 \begin{itemize}
3638 \item \cs{bohr}
3639 \item \cs{clight}
3640 \item \cs{electronmass}
3641 \item \cs{elementarycharge}
3642 \item \cs{hartree}
3643 \item \cs{planckbar}
3644 \end{itemize}
3645 These are also deprecated in \pkg{siunitx} and users should provide their own
3646 definitions.
3647
3648 In addition to these two major blocks, the unit \cs{atomicmassunit} has similar
3649 deprecated status: this was listed as with experimentally-determined units in
3650 the 8th Edition of the \acro{SI} Brochure but is equivalent to the dalton, a
3651 unit which remains accepted.
3652
3653 \section{Localisation}
3654
3655 The \pkg{translations} package provides a structured framework for
3656 localisation of words and phrases. In particular, it offers the
3657 \cs{GetTranslation} macro, which will provide appropriate translations based
3658 on the current \pkg{babel} or \pkg{polyglossia} language setting.
3659
3660 If \pkg{translations} is available, \pkg{siunitx} will load it and alter the
3661 standard settings for the \opt{list-final-separator} and \opt{range-phrase}
3662 options to read:
3663 \begin{LaTeXdemo}[code only]
3664 \sisetup{
3665 list-final-separator = { \GetTranslation{and} },
3666 list-pair-separator = { \GetTranslation{and} },
3667 range-phrase = { \GetTranslation{to (numerical range)} },
3668 }
3669 \end{LaTeXdemo}
3670 The setting for \opt{range-open-phrase} is also adjusted to support a setting
3671 for \opt{range-open-phrase}: this requires some conditionals so is more
3672 complex.
3673
3674 If the current language is known to the \pkg{translations} package then the
3675 result will be localised text. The preamble for this manual loads English,
3676 French, German, Italian, Polish, Spanish, Catalan, Portuguese and Brazilian as
3677 options, and also loads the \pkg{babel} package:
3678 \begin{LaTeXdemo}
3679 % In English by default
3680 \numlist{1;2;3} \\
3681 \numrange{1}{10} \\
3682 \selectlanguage{french}%
3683 \numlist{1;2;3} \\
3684 \numrange{1}{10} \\
3685 \selectlanguage{german}%
3686 \numlist{1;2;3} \\
3687 \numrange{1}{10} \\
3688 \selectlanguage{italian}%
3689 \numlist{1;2;3} \\
3690 \numrange{1}{10} \\
3691 \selectlanguage{polish}%
3692 \numlist{1;2;3} \\
3693 \numrange{1}{10} \\
3694 \selectlanguage{spanish}%
3695 \numlist{1;2;3} \\
3696 \numrange{1}{10} \\
3697 \selectlanguage{catalan}%
3698 \numlist{1;2;3} \\
3699 \numrange{1}{10} \\
3700 \selectlanguage{portuguese}%
3701 \numlist{1;2;3} \\
3702 \numrange{1}{10} \\
3703 \selectlanguage{brazilian}%
3704 \numlist{1;2;3} \\
3705 \numrange{1}{10}
3706 \end{LaTeXdemo}
3707
3708 \section{Compatibility with other packages}
3709
3710 In general, \pkg{siunitx} should be usable with other packages without
3711 interference.
3712
3713 When the \pkg{physics} package is loaded before \pkg{siunitx}, the command
3714 \cs{qty} is not defined. Users may use the version~\version{2} command \cs{SI},
3715 which can be used as a drop-in replacement for \cs{qty}. Alternatively, if the
3716 \pkg{siunitx} definition is preferred, you may use
3717 \begin{LaTeXdemo}[code only]
3718 \AtBeginDocument{\RenewCommandCopy\qty\SI}
3719 \end{LaTeXdemo}
3720 and use the longer name \cs{quantity} to access the functionality of the
3721 \pkg{physics} package.
3722
3723 \section{Hints for using \pkg{siunitx}}
3724
3725 \subsection{Problematic font encodings%
3726 \label{sec:hint:encoding}}
3727
3728 The standard settings in \pkg{siunitx} assume that \enquote{sensible} input and
3729 font encoding values prevail. The input encoding is assumed to be \acro{UTF-8}
3730 in all cases. With pdf\LaTeX{}, the font encoding should be \texttt{T1},
3731 whereas for Xe\LaTeX{} and Lua\LaTeX{}, \texttt{TU} (Unicode font encoding) is
3732 expected.
3733
3734 Some packages, for example \pkg{newtxtext} or \pkg{stix2}, either force
3735 \texttt{T1} or do not anticipate \texttt{TU} correctly with Xe\LaTeX{} and
3736 Lua\LaTeX{}. In these cases, the symbols used by \pkg{siunitx} may be
3737 incorrect. If correcting the font encoding is not possible, you will need to
3738 re-declare the relevant units using symbol definitions which account for this
3739 non-standard setup.
3740
3741 \subsection{Adjusting \cs{litre} and \cs{liter}%
3742 \label{sec:hint:litre}}
3743
3744 As detailed earlier, the unit macros \cs{litre} and \cs{liter} are both
3745 available for litres. With the standard settings, \cs{liter} is defined as
3746 \begin{LaTeXdemo}[code only]
3747 \DeclareSIUnit\liter{\litre}
3748 \end{LaTeXdemo}
3749 meaning that \cs{litre} is the \enquote{canonical} unit. This follows the same
3750 relationship as exists between \cs{metre} and \cs{meter}.
3751
3752 In contrast to metres, however, there is more likelihood of users wishing to
3753 adjust the appearance of litres: both \enquote{\unit{l}} and \enquote{\unit{L}}
3754 are commonly used. The recommended approach to adjustment is to re-declare
3755 the \cs{litre} macro, as \cs{liter} will follow automatically.
3756 \begin{LaTeXdemo}[code only]
3757 \DeclareSIUnit\litre{l}
3758 \end{LaTeXdemo}
3759
3760 \subsection{Ensuring text or math output%
3761 \label{sec:hint:text-math}}
3762
3763 The macros \cs{ensuremath} and \cs{text} should be used to ensure that a
3764 particular item is always printed in the desired mode. Some mathematical output
3765 does not work well in \cs{mathrm} (the font setting used by \pkg{siunitx} for
3766 printing units). The easiest way to solve this is to use the construction
3767 "\text{\ensuremath{...}}", which will print the material in the standard
3768 mathematics font without affecting the rest of the output. In some cases,
3769 simply forcing \cs{mathnormal} will suffice, but this is less reliable with
3770 non-Latin characters.
3771
3772 \subsection{Including a literal hyphen inside \cs{text}%
3773 \label{sec:hint:hyphen-minus}}
3774
3775 In most cases, a "-" character inside \cs{text} will represent a minus. The
3776 package will therefore replace it with \cs{textminus}. However, this may be
3777 problematic if you want a hyphen, or if you are using "-" in a piece of \TeX{}
3778 syntax. You can prevent this by using a second set of braces
3779 \begin{LaTeXdemo}[code only]
3780 \DeclareSIUnit\electronvolt{\text{{e\kern -0.1em V}}}
3781 \end{LaTeXdemo}
3782 or by defining a protected command that will yield a hyphen on typesetting
3783 \begin{LaTeXdemo}[code only]
3784 \usepackage{etoolbox}
3785 \newrobustcmd*\hyphenminus{-}
3786 \DeclareSIUnit\electronvolt{\text{e\kern \hyphenminus0.1em V}}
3787 \end{LaTeXdemo}
3788
3789 \subsection{Expanding content in tables%
3790 \label{sec:hint:expanding}}
3791
3792 When processing tables, \pkg{siunitx} will expand anything stored inside a
3793 macro, unless it is long or protected. \LaTeXe{} robust commands are also
3794 detected and are not expanded (Table~\ref{tab:xmpl:macro}). Values which would
3795 otherwise be expanded can be protected by wrapping them in a set of braces. As
3796 \TeX{} itself will expand the first token in a table cell before \pkg{siunitx}
3797 can act on it, using the \eTeX{} protected mechanism is the recommended course
3798 of action to prevent expansion of macros in table cells. (As is shown in the
3799 table, \TeX's expansion of \LaTeXe{} robust commands can lead to unexpected
3800 results.)
3801 \begin{LaTeXdemo}[code and float]
3802 \begin{table}
3803 \caption{Values as macros in \texttt{S} columns.%
3804 \label{tab:xmpl:macro}}
3805 \newcommand*\myvaluea{1234}
3806 \newcommand\myvalueb{1234}
3807 \DeclareRobustCommand*\myvaluec{1234}
3808 \protected\def\myvalued{1234}
3809 \begin{tabular}{@{}S@{}}
3810 \toprule
3811 {Some Values} \\
3812 \midrule
3813 \myvaluea 8.8 \myvaluea \\ % Both expanded
3814 \myvalueb 8.8 \myvalueb \\ % First expanded by TeX
3815 % to numbers
3816 \myvaluec 8.8 \myvaluec \\ % First expanded by TeX
3817 % but not to numbers!
3818 \myvalued 8.8 \myvalued \\ % Neither expanded
3819 {\myvaluea\ 8.8 \myvaluea} \\ % Neither expanded
3820 \bottomrule
3821 \end{tabular}
3822 \end{table}
3823 \end{LaTeXdemo}
3824
3825 It is possible to use calculated values in tables. For this to work, the
3826 calculation must take place before attempting to parse the number (the parser
3827 cannot \enquote{know} all of the possible values inside an expression). This is
3828 most conveniently handled using the \pkg{xfp} package, which is distributed as
3829 part of the required support for \pkg{siunitx}. The general approach is
3830 illustrated in Table~\ref{tab:xmpl:calc}
3831 \begin{LaTeXdemo}[code and float]
3832 \begin{table}
3833 \caption{Calculated values.%
3834 \label{tab:xmpl:calc}}
3835 \newcommand{\valuea}{66.7012}
3836 \newcommand{\valueb}{66.0212}
3837 \newcommand{\valuec}{64.9026}
3838 \begin{tabular}{
3839 @{}
3840 S[table-format = 2.4]
3841 S[table-format = 3.4]
3842 @{}
3843 }
3844 \toprule
3845 {Value} & {Doubled} \\
3846 \midrule
3847 \valuea & \fpeval{\valuea * 2} \\
3848 \valueb & \fpeval{\valueb * 2} \\
3849 \valuec & \fpeval{\valuec * 2} \\
3850 \bottomrule
3851 \end{tabular}
3852 \end{table}
3853 \end{LaTeXdemo}
3854
3855 A more sophisticated approach is to generate the rows themselves from a
3856 database: this is illustrated in Section~\ref{sec:hint:datatool}.
3857
3858 \subsection{Using \pkg{siunitx} with \pkg{datatool}%
3859 \label{sec:hint:datatool}}
3860
3861 As illustrated in Table~\ref{tab:xmpl:calc}, \pkg{siunitx} can be used to
3862 typeset data stored using \pkg{datatool}. For quickly displaying the contents
3863 of tables, \pkg{datatool} offers the \cs{DTLshowtable} macro. This will only
3864 work with \texttt{S} columns if number parsing is turned off
3865 (Table~\ref{tab:xmpl:datatool}).
3866 \begin{LaTeXdemo}[code and float]
3867 \DTLnewdb{moredata}
3868 \DTLnewrow{moredata}\DTLnewdbentry{moredata}{value}{ 6.7012}
3869 \DTLnewrow{moredata}\DTLnewdbentry{moredata}{value}{66.0212}
3870 \DTLnewrow{moredata}\DTLnewdbentry{moredata}{value}{64.902 }
3871 \begin{table}
3872 \caption{Displaying a \textsf{datatool} table.%
3873 \label{tab:xmpl:datatool}}
3874 \sisetup{parse-numbers= false, table-format = 2.4}
3875 \renewcommand*\dtlrealalign{S}
3876 \DTLdisplaydb{moredata}
3877 \end{table}
3878 \end{LaTeXdemo}
3879
3880 The \pkg{datatool} package may also be used to create on-the-fly tables using
3881 calculations. For example, the demonstration in Table~\ref{tab:xmpl:calc} may
3882 be achieved without needing to write out each row, as shown in
3883 Table~\ref{tab:xmpl:datatool-calc}. An extra column is used to contain the
3884 calculations in this case.
3885 \begin{LaTeXdemo}[code and float]
3886 \begin{table}
3887 \caption{Calculated values using \pkg{datatool}.%
3888 \label{tab:xmpl:datatool-calc}}
3889 \DTLnewdb{data}
3890 \DTLnewrow{data}\DTLnewdbentry{data}{value}{66.7012}
3891 \DTLnewrow{data}\DTLnewdbentry{data}{value}{66.0212}
3892 \DTLnewrow{data}\DTLnewdbentry{data}{value}{64.9026}
3893 \begin{tabular}{
3894 @{}
3895 S[table-format = 2.4]
3896 S[table-format = 3.4]
3897 @{}l
3898 @{}
3899 }
3900 \toprule
3901 {Value} & {Doubled} &
3902 \DTLforeach{data}{\myvalue=value}{%
3903 \DTLiffirstrow {\\ \midrule}{\\}%
3904 \myvalue & % First column
3905 \fpeval{\myvalue * 2} % second column
3906 & }\\
3907 \bottomrule
3908 \end{tabular}
3909 \end{table}
3910 \end{LaTeXdemo}
3911
3912 \subsection{Using units in section headings and bookmarks%
3913 \label{sec:hint:bookmarks}}
3914
3915 The \pkg{siunitx} code is designed to work correctly with functions in
3916 headings. They will print correctly in headings and in the table of contents.
3917 As illustrated here, the standard behavior is to ignore font changes. When the
3918 \pkg{hyperref} package is loaded, the functions automatically \enquote{degrade
3919 gracefully} to produce useful information in \acro{pdf} bookmarks. If you want
3920 more control over the bookmark text, use the \cs{texorpdfstring} function from
3921 \pkg{hyperref}, for example:
3922 \begin{LaTeXdemo}[code only]
3923 \section{Some text
3924 \texorpdfstring
3925 {\unit{\joule\per\mole\per\kelvin}}
3926 {J mol-1 K-1}%
3927 }
3928 \end{LaTeXdemo}
3929
3930 You may find it useful to load \pkg{hyperref} with the \opt{unicode} option,
3931 as this will allow \unit{\ohm} to appear in bookmarks. Without the option,
3932 the encoding used by \pkg{hyperref} does not support this symbol.
3933
3934 \subsection{A left-aligned column visually centered under a heading%
3935 \label{sec:hint:left-column}}
3936
3937 When you have a column of non-related numbers, the usual advice is to make
3938 these left-aligned and then center the resulting column under the heading. With
3939 the \pkg{dcolumn} package, that would be done with something like
3940 |D{x}{}{5.0}|. This is something of an abuse of the nature of a number, but can
3941 also be done using \pkg{siunitx} (Table~\ref{tbl:xmpl:unrel}).
3942 \begin{LaTeXdemo}[code and float]
3943 \begin{table}
3944 \caption{Formatting unrelated numbers.%
3945 \label{tbl:xmpl:unrel}}
3946 \centering
3947 \begin{tabular}
3948 {
3949 @{}
3950 S[
3951 table-format = 5.0,
3952 parse-numbers = false,
3953 input-decimal-markers = x
3954 ]
3955 @{}
3956 }
3957 \toprule
3958 \multicolumn{1}{@{}c@{}}{Header} \\
3959 \midrule
3960 120 \\
3961 12.3 \\
3962 12340 \\
3963 12.02 \\
3964 123 \\
3965 1 \\
3966 \bottomrule
3967 \end{tabular}
3968 \end{table}
3969 \end{LaTeXdemo}
3970
3971 \subsection{Regression tables%
3972 \label{sec:hint:regression}}
3973
3974 In some subject areas, it is common to present regression values or similar,
3975 which feature an uncertainty value in parenthesis on the line below the main
3976 value. As these are separate cells, they cannot be entered using \pkg{siunitx}
3977 in one value. There are a couple of ways of formatting them using the package,
3978 depending on whether the values also need to be parsed.
3979
3980 Where parsing is not required, the most straight-forward method is available:
3981 provide a model format allowing space for an extra \enquote{digit} at each end,
3982 which will then allow for the parenthesis. If a sign is applied to the number,
3983 it may not be necessary to add a \enquote{digit} for the leading bracket. If
3984 parsing is also required, this approach cannot be employed. Instead, the
3985 parsing needs to be adjusted such that |(| and |)| are not treated as part of
3986 the number, and \opt{table-align-text-before} is set to |false| such that these
3987 will be placed next to the numerical part. These methods are illustrated in
3988 Table~\ref{tab:regression}.
3989
3990 \begin{LaTeXdemo}[code and float]
3991 \begin{table}
3992 \caption{Regression tables%
3993 \label{tab:regression}
3994 }
3995 \begin{tabular}
3996 {
3997 @{}
3998 S[table-format = 2.4, parse-numbers = false]
3999 S[table-format = +1.4, parse-numbers = false]
4000 S[
4001 input-open-uncertainty = ,
4002 input-close-uncertainty = ,
4003 minimum-decimal-digits = 3, % (
4004 table-format = +1.3),
4005 table-align-text-before = false
4006 ]
4007 @{}
4008 }
4009 \toprule
4010 {Header} &{Header} & {Header} \\
4011 \midrule
4012 1.234 & -1.234 & -1.23 \\
4013 (0.053) & (0.053) & (0.053) \\
4014 \bottomrule
4015 \end{tabular}
4016 \end{table}
4017 \end{LaTeXdemo}
4018
4019 \subsection{Maximising performance%
4020 \label{sec:hint:performance}}
4021
4022 Both the number and unit parsers require significant effort in terms of \TeX{}
4023 programming. For input that does not require such processing, the maximum
4024 performance for \pkg{siunitx} can therefore be obtained by turning off both
4025 systems:
4026 \begin{LaTeXdemo}
4027 \qty{7.3}{\Hz} \\
4028 \qty[parse-units = false]{7.3}{\Hz} \\
4029 \qty[
4030 parse-numbers = false,
4031 parse-units = false
4032 ]{7.3}{\Hz}
4033 \end{LaTeXdemo}
4034
4035 For tables, any settings that can be given before the table are only parsed once,
4036 whereas given in the optional argument to |S| they are read in every cell. As such,
4037 you should favour
4038 \begin{LaTeXdemo}[code only]
4039 \begin{table}
4040 \sisetup{...}
4041 \begin{tabular}{S}
4042 ...
4043 \end{LaTeXdemo}
4044 for common settings.
4045
4046 \subsection{Special considerations for the \cs{kWh} unit%
4047 \label{sec:hint:kWh}}
4048
4049 The standard settings provide the \cs{kWh} unit set up with no spacing between
4050 the \enquote{\unit{\kilo\watt}} and the \enquote{\unit{\hour}} unit to give
4051 \enquote{\unit{\kWh}}. However, this only applies when the unit is given on its
4052 own: combinations will follow the normal rules
4053 \begin{LaTeXdemo}
4054 \unit{\kWh} \\
4055 \unit{\kWh\per\metre}
4056 \end{LaTeXdemo}
4057 This is because the unit \cs{kWh} is defined so that it can still be varied by
4058 altering \cs{kilo}, \cs{watt} and \cs{hour}, and so that the prefix can still
4059 be turned into a number. However, some users may prefer to have a non-flexible
4060 macro which never adds a space. This can be achieved by redefining \cs{kWh}
4061 with \cs{DeclareSIUnit}, by added an alternative definition
4062 \begin{LaTeXdemo}[code only]
4063 \DeclareSIUnit\kWh{kWh}
4064 \DeclareSIUnit\KWH{kWh}
4065 \end{LaTeXdemo}
4066 or of course by using literal unit input.
4067 \begin{LaTeXdemo}
4068 \unit{\KWH\per\metre}\\
4069 \unit{kWh.m^{-1}}
4070 \end{LaTeXdemo}
4071
4072 Another point to notice is that the \cs{per} macro applies to the next unit,
4073 and not an entire unit combination. Thus in
4074 \begin{LaTeXdemo}
4075 \unit{\candela\per\kWh}
4076 \end{LaTeXdemo}
4077 \cs{per} applies to the watts but not to the hours. In this case, the units
4078 need to be written out in full or the \opt{sticky-per} option should be used.
4079 \begin{LaTeXdemo}
4080 \unit{\candela\per\kilo\watt\per\hour} \\
4081 \unit[sticky-per]{\candela\per\kWh}
4082 \end{LaTeXdemo}
4083
4084 \subsection{Prefixes and small angles%
4085 \label{sec:hint:prefixangle}}
4086
4087 Typically, prefixes are not applied to the standard symbols for angles: as
4088 such, the \cs{ang} command is not subject to the \opt{prefix-mode} option. In
4089 some areas, very small angles are given in arcseconds using the symbol
4090 \unit{as}. To apply prefixes in this case, use the \cs{qty} command rather than
4091 \cs{ang}.
4092 \begin{LaTeXdemo}
4093 % In the preamble
4094 % \DeclareSIUnit\arcsecond{as}
4095 \qty{1e-3}{\arcsecond} \\
4096 \qty[prefix-mode = combine-exponent]{1e-3}{\arcsecond}
4097 \end{LaTeXdemo}
4098
4099 \subsection{Creating a column with numbers and units%
4100 \label{sec:hint:mixed}}
4101
4102 Usually, numbers in a table should be given with the units in the column
4103 heading. However, there are cases where a series of data are best presented in
4104 a table but have different units. There are two ways to do this
4105 (Table~\ref{tab:xmpl:mixed}). The first is to place the units in the first
4106 column of the table, which makes sense if there are several related items in
4107 the table. The second method is to generate two columns, one for numbers and a
4108 second for units, and then to format these to give the visual effect of a
4109 single column. The later effect is most appropriate when only one set of
4110 numbers are presented in a table. This method requires cell content is
4111 collected, easiest to do using the \pkg{collcell} package.
4112 \begin{LaTeXdemo}[code and float]
4113 \begin{table}
4114 \caption{Tables where numbers have different units.%
4115 \label{tab:xmpl:mixed}}
4116 \hspace{\fill}%
4117 \begin{tabular}
4118 {
4119 @{}
4120 >{$}l<{$}
4121 S[table-format = 3.3(1)]
4122 S[table-format = 3.3(1)]
4123 @{}
4124 }
4125 \toprule
4126 & {One} & {Two} \\
4127 \midrule
4128 a / \unit{\pm} & 123.4(2) & 567.8(4) \\
4129 \beta / \unit{\degree} & 90.34(4) & 104.45(5) \\
4130 \mu / \unit{\per\mm} & 0.532 & 0.894 \\
4131 \bottomrule
4132 \end{tabular}
4133 \hspace{\fill}%
4134 \begin{tabular}
4135 {
4136 @{}
4137 S[table-format=1.3]@{\,}
4138 >{\collectcell\unit}l<{\endcollectcell}
4139 @{}
4140 }
4141 \toprule
4142 \multicolumn{2}{@{}c}{Heading} \\
4143 \midrule
4144 1.234 & \metre \\
4145 0.835 & \candela \\
4146 4.23 & \joule\per\mole \\
4147 \bottomrule
4148 \end{tabular}
4149 \hspace{\fill}%
4150 \end{table}
4151 \end{LaTeXdemo}
4152
4153 \subsection{Tables with heading rows%
4154 \label{sec:hint:heading}}
4155
4156 A common format for tables is to make the heading row visually distinct using a
4157 background color and bold text. If numbers appear in such a heading row within
4158 an \texttt{S} column then getting the appearance right can be challenging. The
4159 best approach is to make the \cs{bfseries} macro \enquote{robust} (as
4160 demonstrated in Section~\ref{sec:hint:expanding}), then to use this macro to
4161 make the heading cells bold. This approach is illustrated in
4162 Table~\ref{tab:xmpl:headers}, along with the use of \cs{rowcolor} to provide a
4163 background color. Some typical \LaTeX{} font arrangements use a wider
4164 (extended) width for the bold font compared with the normal font. This will
4165 disturb the alignment if the \opt{table-format} is not symmetrical. For these
4166 cases, the \opt{table-model-setup} key may be used to apply the wider font to
4167 the \enquote{model} used in ensuring alignment.
4168 \begin{LaTeXdemo}[code and float]
4169 \begin{table}
4170 \caption{Header row in a table.%
4171 \label{tab:xmpl:headers}}
4172 \robustify\bfseries
4173 \centering
4174 \sisetup{text-series-to-math}
4175 \begin{tabular}
4176 {
4177 @{}
4178 S[table-format = 3.3]
4179 S[table-format = 3.6, table-model-setup = \bfseries]
4180 @{}
4181 }
4182 \rowcolor[gray]{0.9}
4183 \bfseries 123.456 & \bfseries 123.456789 \\
4184 23.45 & 23.45 \\
4185 123.4 & 123.4 \\
4186 3.456 & 3.456 \\
4187 \end{tabular}
4188 \end{table}
4189 \end{LaTeXdemo}
4190
4191 \subsection{Associating a locale with a \pkg{babel} language%
4192 \label{sec:hint:babel}}
4193
4194 It is possible to instruct the \pkg{babel} package to switch to a particular
4195 \pkg{siunitx} locale when changing language. This can be done using the
4196 \pkg{babel} \cs{extras\meta{language}} system. For example, to associate the
4197 \texttt{DE} locale with the \texttt{german} \pkg{babel} language, the
4198 appropriate code would be
4199 \begin{LaTeXdemo}[code only]
4200 \addto\extrasgerman{\sisetup{locale = DE}}
4201 \end{LaTeXdemo}
4202
4203 \subsection{Symbolic \enquote{digits}%
4204 \label{sec:hint:symbols}}
4205
4206 In some cases you may want to use \enquote{digits} which do not fall within the
4207 usual set |0123456789|. This can be done by setting the \opt{input-digits}
4208 option, but bearing in mind that this will affect (prevent) for example
4209 rounding.
4210 \begin{LaTeXdemo}
4211 \sisetup{input-digits = 0123456789\pi}%
4212 \num{4\pi e-7}
4213 \end{LaTeXdemo}
4214 Each extra entry should be a single token, and should either have a definition
4215 which is safe in both math and text mode, or should only be used when the
4216 output mode is known. It may be necessary to make some tokens robust using
4217 \pkg{etoolbox} for this to work, for example
4218 \begin{LaTeXdemo}
4219 \robustify\dots
4220 \sisetup{input-digits = 0123456789\dots}%
4221 \qty{0,4066\dots}{\metre\squared}
4222 \end{LaTeXdemo}
4223
4224 \subsection{Demonstrating prefixes%
4225 \label{sec:hint:prefixes}}
4226
4227 As \pkg{siunitx} contains data about the numerical values of unit prefixes,
4228 you may wish to print this in an automated way. Prefixes cannot be given
4229 on their own, but it is possible to create a \enquote{do nothing} unit.
4230 \begin{LaTeXdemo}[code only]
4231 \DeclareSIUnit\noop{\relax}
4232 \end{LaTeXdemo}
4233 which can then be used to show just the prefix symbol.
4234 \begin{LaTeXdemo}
4235 \unit{\yotta\noop}
4236 \end{LaTeXdemo}
4237 To show just the numerical value of a prefix, you will need to use \cs{qty}
4238 and appropriate settings.
4239 \begin{LaTeXdemo}
4240 \qty[prefix-mode = extract-exponent, print-unity-mantissa = false]%
4241 {1}{\yotta\noop}
4242 \end{LaTeXdemo}
4243 This may be conveniently wrapped up inside a document command, for example
4244 \begin{LaTeXdemo}[code only]
4245 \NewDocumentCommand\prefixvalue{m}{%
4246 \qty[prefix-mode=extract-exponent,print-unity-mantissa=false]{1}{#1\noop}
4247 }
4248 \end{LaTeXdemo}
4249
4250 \subsection{Creating a set of pre-defined units%
4251 \label{sec:hint:config}}
4252
4253 There are many units which sit outside of those defined in the (current)
4254 \acro{SI} Brochure which are of use to many people. Most obvious are those
4255 which have been detailed in previous editions of the Brochure, as described
4256 in Section~\ref{sec:BIPM8}, but there are many others.
4257
4258 It is often convenient to have a pre-defined set of useful units available
4259 without needing to copy the full set of definitions into each source file. At
4260 the same time, it is important that such sources do show that they are using
4261 units not defined by the core part of \pkg{siunitx}. The most straight-forward
4262 way to achieve this is to create a separate file, for example
4263 \texttt{siunitx-local-units.tex}, and place it in your local \TeX{} tree
4264 (usually \verb|~/texmf/tex/latex/| on Linux, \verb|~/Library/texmf/tex/latex/|
4265 on macOS or \verb|C:\Users\<name>\texmf\tex\latex| on Windows). This can then
4266 be loaded in the preamble using
4267 \begin{LaTeXdemo}[code only]
4268 % Load useful 'local' units
4269 \input{siunitx-local-units}
4270 \end{LaTeXdemo}
4271
4272 \subsection{Overloading the standard interfaces%
4273 \label{sec:hint:overload}}
4274
4275 The interfaces in \pkg{siunitx} deliberately split up different types of
4276 numerical input (ranges, products, etc.) for semantic reasons. This also means
4277 that there is less chance of confusion in parsing input. However, some users
4278 would prefer to overload the \cs{num} and \cs{qty} commands such that they
4279 accept multiple different types of input. There is a code-level interface that
4280 could be used for this, but most end-users will likely want to avoid this. A
4281 possible approach that covers most of the common cases is.
4282 \begin{LaTeXdemo}[code only]
4283 \ExplSyntaxOn
4284 \cs_gset_eq:NN \ifstrpresent \tl_if_in:nnTF
4285 \ExplSyntaxOff
4286 \NewCommandCopy\oldnum\num
4287 \NewCommandCopy\oldnumrange\numrange
4288 \RenewDocumentCommand\num{O{}m}{%
4289 \ifstrpresent{#2}{x}
4290 {\numproduct[#1]{#2}}
4291 {%
4292 \ifstrpresent{#2}{;}
4293 {\numlist[#1]{#2}}
4294 {%
4295 \ifstrpresent{#2}{:}
4296 {\numrange[#1]{#2}}
4297 {\oldnum[#1]{#2}}%
4298 }%
4299 }%
4300 }
4301 \RenewDocumentCommand\numrange{O{}>{\SplitList{:}}m}
4302 {\oldnumrange[#1]#2}
4303 \end{LaTeXdemo}
4304 for the \cs{num} command and
4305 \begin{LaTeXdemo}[code only]
4306 \ExplSyntaxOn
4307 \cs_gset_eq:NN \ifstrpresent \tl_if_in:nnTF
4308 \ExplSyntaxOff
4309 \NewCommandCopy\oldqty\qty
4310 \NewCommandCopy\oldqtyrange\qtyrange
4311 \RenewDocumentCommand\qty{O{}mm}{%
4312 \ifstrpresent{#2}{x}
4313 {\qtyproduct[#1]{#2}{#3}}
4314 {%
4315 \ifstrpresent{#2}{;}
4316 {\qtylist[#1]{#2}{#3}}
4317 {%
4318 \ifstrpresent{#2}{:}
4319 {\qtyrange[#1]{#2}{#3}}
4320 {\oldqty[#1]{#2}{#3}}%
4321 }%
4322 }%
4323 }
4324 \RenewDocumentCommand\qtyrange{O{}>{\SplitList{:}}mm}
4325 {\oldqtyrange[#1]#2{#3}}
4326 \end{LaTeXdemo}
4327 for \cs{qty}.
4328
4329 \section{Using (\acro{SI}) units}
4330
4331 Consistent and logical units are a necessity for scientific work, and have
4332 applicability everywhere. Historically, a number of systems have been used for
4333 physical units. \acro{SI} units were introduced by the \foreign{Conférence
4334 Générale des Poids et Mesures} (\acro{CGPM}) in 1960. \acro{SI} units are a
4335 coherent system based on seven base units, from which all other units may be
4336 derived.
4337
4338 At the same time, physical quantities with units are mathematical entities, and
4339 as such way that they are typeset is important. In mathematics, changes of type
4340 (such as using bold, italic, sans serif typeface and so on) convey information.
4341 This means that rules exist not only for the type of units to be used under the
4342 \acro{SI} system, but also the way they should appear in print. Advice on best
4343 practice has been made available by the \emph{National Institute of Standards
4344 and Technology} (\acro{NIST})~\cite{NIST}.
4345
4346 As befits an agreed international standard, the full rules are detailed. It is
4347 not appropriate to reproduce these in totality here; instead, a useful summary
4348 of the key points is provided. The full details are available from the
4349 \foreign{Bureau International des Poids et Mesures}~\cite{BIPM}.
4350
4351 The \pkg{siunitx} package takes account of the information given here, so far
4352 as is possible. Thus the package defaults follow the recommendations made for
4353 typesetting numbers and units. Spacing and so forth is handled in such a way as
4354 to make implementing the rules (relatively) easy.
4355
4356 \subsection{Units}
4357
4358 There are seven base \acro{SI} units, listed in Table~\ref{tab:unit:base}.%
4359 \footnote{Some base units need others defined first; there is therefore a
4360 required order of definition.} The base units have been chosen such that all
4361 physical quantities can be expressed using an appropriative combination of
4362 these units, needing no others and with no redundancy.
4363
4364 All other units within the \acro{SI} system are regarded as \enquote{derived}
4365 from the seven base units. At the most basic, all other \acro{SI} units can be
4366 expressed as combinations of the base units. However, many units (listed in
4367 Table~\ref{tab:unit:derived}) have a special name and symbol. Most of these
4368 units are simple combinations of one or more base units (raised to powers as
4369 appropriate).
4370
4371 A series of \acro{SI} prefixes for decimal multiples and sub-multiples are
4372 provided, and can be used as modifiers for any \acro{SI} unit (either base or
4373 derived units) with the exception of the kilogram. The prefixes are listed in
4374 Table~\ref{tab:unit:prefix}. No space should be used between a prefix and the
4375 unit, and only a single prefix should be used. Even the degree Celsius can be
4376 given a prefix, for example \qty{1}{\milli\degreeCelsius}.
4377
4378 It is important to note that the kilogram is the only \acro{SI} unit with a
4379 prefix as part of its name and symbol. Only single prefix may be used, and so
4380 in the case of the kilogram prefix names are used with the unit name
4381 \enquote{gram} and the prefix symbols are used with the unit symbol
4382 \unit{\gram}. For example $\qty{1e-6}{\kilo\gram} = \qty{1e-3}{\gram} =
4383 \qty{1}{\milli\gram}$.
4384
4385 The application of \acro{SI} units is meant to provide a single set of units
4386 which ensure consistency and clarity across all areas. However, other units are
4387 common is many areas, and are not without merit. The units provided by
4388 \pkg{siunitx} by default do not include any of these; only units which are part
4389 of the \acro{SI} set or are accepted for use with \acro{SI} units are defined.
4390 However, several other sets of units can be loaded as optional modules. The
4391 binary prefixes and units (Table~\ref{tab:unit:binary}) are the most obvious
4392 example. These are \emph{not} part of the \acro{SI} specifications, but the
4393 prefix names are derived from those in Table~\ref{tab:unit:prefix}.
4394
4395 Other units are normally to be avoided where possible. \acro{SI} units should,
4396 in the main, be preferred due to the advantages of clear definition and
4397 self-consistency this brings. However, there will probably always be a place
4398 for specialist or non-standard units. This is particularly true of units
4399 derived from basic physical constants.
4400
4401 There are also many areas where non-standard units are used so commonly that to
4402 do otherwise is difficult or impossible. For example, most synthetic chemists
4403 measure the pressure inside vacuum apparatus in \unit{\millimetremercury},
4404 partly because the most common gauge for the task still uses a column of
4405 mercury metal. For these reasons, \pkg{siunitx} allows definition of such
4406 units.
4407
4408 \subsection{Mathematical meaning}
4409
4410 As explained earlier, a quantity combination is a single mathematical entity.
4411 This has implications for how both the number and the unit should be printed.
4412 Firstly, the two parts should not be separated: a quantity is a product of the
4413 number and the unit. With the exception of the symbols for plane angles
4414 (\unit{\degree}, \unit{\arcminute} and \unit{\arcsecond}), the \acro{BIPM}
4415 specifies either a space or half-height (centered) dot should be
4416 used~\cite{BIPM}.
4417 \begin{LaTeXdemo}
4418 A space for \qty{10}{\percent}\\
4419 and also for \qty{100}{\degreeCelsius}\\
4420 but not for \ang{1.23}.
4421 \end{LaTeXdemo}
4422
4423 The mathematical meaning of units also means that the shape, weight and family
4424 are important. Units are supposed to be typeset in an upright, medium weight
4425 font. Italic, bold and sans serif are all used mathematically to convey other
4426 meanings. (In an all sanserif document, using sans serif for units is
4427 reasonable.) The \pkg{siunitx} package defaults again follow this convention:
4428 any local settings are ignored, and uses the current upright math font.
4429 However, there are occasions where this may not be the most desirable behavior.
4430 A classic example would be in an all-bold section heading. As the surrounding
4431 text is bold, some people feel that any units should follow this.
4432 \begin{LaTeXdemo}
4433 Units should \textbf{not be bold: \qty{54}{\farad}}\\
4434 \textbf{But perhaps in a running block,\\
4435 it might look better:
4436 \qty[text-series-to-math]{54}{\farad}}
4437 \end{LaTeXdemo}
4438
4439 Symbols for units formed from other units by multiplication are indicated by
4440 means of either a half-height (that is, centered) dot or a (thin) space.
4441 \begin{LaTeXdemo}
4442 $\unit{\metre\second} = \text{metre second}$ \\
4443 $\unit{\milli\second} = \text{millisecond}$ \\
4444 \sisetup{inter-unit-product = \ensuremath { { } \cdot { } } }
4445 $\unit{\metre\second} = \text{metre second}$ \\
4446 $\unit{\milli\second} = \text{millisecond}$
4447 \end{LaTeXdemo}
4448 There are some circumstances under which it is common practice to omit any
4449 spaces. The classic example is \unit{\kWh}, where
4450 \enquote{\unit[inter-unit-product = \,]{\kWh}} does not add any useful
4451 information. If using such a unit repeatedly, users of \pkg{siunitx} are
4452 advised to create a custom unit to ensure consistency. It is important to note
4453 that while this is common practice, it is \emph{not} allowed by the
4454 \acro{BIPM}~\cite{BIPM}.
4455
4456 Symbols for units formed from other units by division are indicated by means of
4457 a virgule (oblique stroke, slash, "/"), a horizontal line, or negative
4458 exponents.\footnote{Notice that a virgule and a solidus are not the same
4459 symbol.} However, to avoid ambiguity, the virgule must not be repeated on the
4460 same line unless parentheses are used. This is ensured when using named unit
4461 macros in \pkg{siunitx}, which will \enquote{trap} repeated division and format
4462 it correctly. In complicated cases, negative exponents are to be preferred over
4463 other formats.
4464 \begin{LaTeXdemo}
4465 \unit{\joule\per\mole\per\kelvin} \\
4466 \unit[per-mode = fraction]{\joule\per\mole\per\kelvin} \\
4467 \unit[per-mode = symbol]{\joule\per\mole\per\kelvin}
4468 \end{LaTeXdemo}
4469
4470 Products and errors should show what unit applies to each number given. Thus
4471 \qtyproduct[product-units = bracket]{2x3}{\metre} is an ordered set of lengths
4472 of a geometric area, whereas \qtyproduct[product-units = single]{2x3}{\metre}
4473 is a length (and equal to \qty{6}{\metre}). Thus, $\times$ is not a product but
4474 is a mathematical operator; in the same way, a $2 \times 3$ matrix is not a $6$
4475 matrix! In some areas, areas and volumes are given with separated units but a
4476 unit raised to the appropriate power: \qtyproduct[product-units = power]{2 x
4477 3}{\metre}. Although this does display the correct overall units, it is
4478 potentially-confusing and is not encouraged.
4479
4480 Care must be taken when writing ranges of numbers. For purely numerical values,
4481 it is common to use an en-dash to show a range, for example \enquote{see pages
4482 1--5}. On the other hand, physical quantities could be misinterpret as negative
4483 values if written in this way. As the quantity is a single mathematical entity,
4484 writing the values with an en-dash followed by a single unit is also incorrect.
4485 As a result, using the word \enquote{to} is strongly recommended.
4486 \begin{LaTeXdemo}
4487 \qtyrange{1}{5}{\metre} long.
4488 \end{LaTeXdemo}
4489
4490 \subsection{Graphs and tables}
4491
4492 In graphs and tables, repetition of the units following each entry or axis mark
4493 is confusing and repetitive. It is therefore best to place the unit in the
4494 label part of the information. Placing the unit in square brackets is common
4495 but mathematically poor.\footnote{For example, for an acceleration \(a\), the
4496 expression $[a]$ is the dimensions of $a$, \foreign{i.e.}~length per time
4497 squared in this case.} Much better is to show division of all quantities by the
4498 unit, which leaves the entries as unitless ratios. This is illustrated in
4499 Table~\ref{tab:xmpl:unitless} and Figure~\ref{fig:xmpl:unitless}.
4500 \begin{LaTeXdemo}[code and float]
4501 \begin{table}
4502 \caption{An example of table labelling.%
4503 \label{tab:xmpl:unitless}}
4504 \sisetup{
4505 table-number-alignment = center,
4506 table-format = 1.4
4507 }
4508 \begin{tabular}{@{}cS@{}}
4509 \toprule
4510 Entry & {Length/\unit{\metre}} \\
4511 \midrule
4512 1 & 1.1234 \\
4513 2 & 1.1425 \\
4514 3 & 1.7578 \\
4515 4 & 1.9560 \\
4516 \bottomrule
4517 \end{tabular}
4518 \end{table}
4519 \end{LaTeXdemo}
4520 \begin{LaTeXdemo}[code and float]
4521 \begin{figure}
4522 \begin{tikzpicture}
4523 \begin{axis}[
4524 xlabel = $t/\unit{\second}$,
4525 xmax = 6,
4526 xmin = 0,
4527 ylabel = $d/\unit{\metre}$,
4528 ymin = 0
4529 ]
4530 \addplot[smooth,mark=*]
4531 plot coordinates {
4532 (0,0)
4533 (1,5)
4534 (2,8)
4535 (3,9)
4536 (4,8)
4537 (5,5)
4538 (6,0)
4539 };
4540 \end{axis}
4541 \end{tikzpicture}
4542 \caption{An example of graph labelling.%
4543 \label{fig:xmpl:unitless}}
4544 \end{figure}
4545 \end{LaTeXdemo}
4546
4547 In most cases, adding exponent values in the body of a table is
4548 less desirable than adding a fixed exponent to column headers. An
4549 example is shown in Table~\ref{tab:good}. The use of \cs{multicolumn} is
4550 needed here due to the \enquote{\texttt{<}}; without \cs{multicolumn},
4551 the titles are followed by \enquote{\unit{\kilo\gram}}!
4552 \begin{LaTeXdemo}[code and float]
4553 \begin{table}
4554 \caption{Bad and good columns.%
4555 \label{tab:good}}
4556 \sisetup{table-number-alignment = center}
4557 \begin{tabular}{
4558 @{}
4559 c
4560 S[table-format = 1.3e1]
4561 @{\,\unit{\kilogram}}
4562 S[table-format = 2.2]
4563 @{}
4564 }
4565 \toprule
4566 Entry & \multicolumn{1}{c}{Mass} &
4567 {Mass/\qty[print-unity-mantissa = false]{e3}{\kilogram}} \\
4568 \midrule
4569 1 & 4.56e3 & 4.56 \\
4570 2 & 2.40e3 & 2.40 \\
4571 3 & 1.345e4 & 13.45 \\
4572 4 & 4.5e2 & 0.45 \\
4573 \bottomrule
4574 \end{tabular}
4575 \end{table}
4576 \end{LaTeXdemo}
4577
4578 \section{Installation}
4579
4580 For most users, there will be no need to explicitly install \pkg{siunitx}:
4581 it is available from the package management system in current \TeX{} Live
4582 and MiK\TeX{} systems.
4583
4584 For manual installation, the package is available from
4585 \href{http://ctan.org/pkg/siunitx}{\acro{CTAN}}. As well as the raw source
4586 files, \acro{CTAN} hold the package as a pre-extracted zip file,
4587 \file{siunitx.tds.zip}. The later is most convenient for most users: simply
4588 unzip this in your local \path{texmf} directory.
4589
4590 The package requires \pkg{expl3} support as provided in the \pkg{l3kernel} and
4591 bundle, which is required by the \LaTeX{} kernel. As such, you are very
4592 unlikely to need to update this manually.
4593
4594 \section{Thanks}
4595
4596 Many users have provided feedback, bug reports and ideas for new features for
4597 \pkg{siunitx}: thanks to all of them. Particular thanks to Stefan Pinnow, who
4598 has taken the lead role as beta tester for \pkg{siunitx}, finding incorrect
4599 output, bad documentation and the odd spelling mistake in the documentation.
4600 Thanks also to Enrico Gregorio for encouraging me to complete a fully
4601 \pkg{expl3}-compliant version of the package. Thanks also to Danie Els and
4602 Marcel Heldoorn for the \pkg{SIstyle} and \pkg{SIunits} packages, respectively,
4603 which provided the starting point for the development of \pkg{siunitx}.
4604
4605 \section{Making suggestions and reporting bugs}
4606
4607 Feedback on \pkg{siunitx} is always welcome, either to make suggestions or to
4608 report problems. When sending feedback, it is always useful if a small example
4609 file is included, showing the bug being reported or illustrating the desired
4610 output. It is helpful if a \enquote{reference rendering} is included, showing
4611 what the output should look like. A typical example file might read
4612 \begin{verbatim}
4613 \listfiles
4614 % Use the article class unless the problem is class-dependent
4615 \documentclass{article}
4616 \usepackage{siunitx}
4617 % Other packages loaded as required
4618 \begin{document}
4619 Reference output: $1.23\,\mathrm{m}$
4620
4621 \textsf{siunitx} output: \qty{1.23}{\metre}
4622 \end{document}
4623 \end{verbatim}
4624 As illustrated, it is usually best to use the \cls{article} class and to only
4625 load packages which are needed to show the issue. It is also useful to include
4626 a copy of the log file generate by \LaTeX{} when reporting a bug (as the
4627 versions of packages can be important to solving the issue).
4628
4629 Feedback can be sent in a range of ways. The development code and issue tracker
4630 are hosted on GitHub: \url{https://github.com/josephwright/siunitx/}. Issues
4631 opened there are visible to other users and makes sure that they cannot be
4632 forgotten.
4633
4634 \end{documentation}
4635
4636 \begin{thebibliography}{10}
4637 \bibitem{BIPM}
4638 \emph{The International System of Units (\acro{SI})},
4639 \url{https://www.bipm.org/en/measurement-units/}.
4640 \bibitem{NIST}
4641 \emph{International System of Units from \acro{NIST}},
4642 \url{http://physics.nist.gov/cuu/Units/index.html}.
4643 \end{thebibliography}
4644
4645 \PrintIndex
4646
4647 \end{document}