siunitx A comprehensive (SI) units package

1 siunitx A comprehensive (SI) units package Joseph Wright Released2009/09/21 AbstractTypesetting values with units requires care to ensure that the combinedmathematical meaning of the value plus unit combination is clear. In par-ticular, the si units system lays down a consistent set of units with rules onhow these are to be used. However, different countries and publishers havediffering conventions on the exact appearance of numbers (and units ).Thesiunitxprovides a set of tools for authors to typeset numbers and unitsin a consistent way. The package has an extended set of configuration optionswhich make it possible to follow varying typographic conventions with thesame input syntax. The package includes automated processing of numbersand units , and the ability to control tabular alignment of number of LATEX packages have been developed in the past for format-ting units :SIunits,SIstyle,unitsdef, units ,fan cyunitsandfancynum.

2 Support forusers of all of these packages is available as emulation modules insiunitx. Inaddition,siunitxcan carry out many of the functions of thedcolumn, Introduction3II Using thesiunitxpack-age41 For the impatient42 Requirements53 Loading the package54 Numbers55 Tabular numbers .. of units ..96 Angles107 units and units .. unit interpreter .. of units .. with no values .. units .. units , pre-fixes and powers .. and abbrevi-ated units .. new units ..188 Ranges of numbers209 Specialist units (binary) .20 This file describes version , last revised2009/09/21. E-mail: .. physics (hep) (astro) .. (geophys) . (chemeng) ..2210 Font control2211 package family and style . and formatting .. formatting .. material .. support . control.

3 Of all options3512 Emulation of other packages3813 Configuration files3914 Common do I need\permore than once? .. is the order of myunits changed? .. not recommendedoutside of\SI/\si? .. do I set super-scripts to use liningnumbers? .. do most of the ex-amples use J mol 1K 1? cannumprintdothatsiunitxcannot? ..4015 Tricks and known maths mode .. fixedspaces in units .. unprocessed di-gits through of\ document in sansserif font .. of emulation .. columns onnon-decimal input .. content intables .. items after thelast column of a thecellspacepackage .. themathabxpackage .. with no man-tissa inScolumns ..4616 Reporting a problem4617 Feature requests4718 Acknowledgements47 III Correct application of(SI) base units .. derived units .

4 Prefixes .. units ..4921 units and values in meaning . multiplication anddivision .. units .. in writing valuesof quantities .. and tables ..51IV Notes5422 Change History5423 Index5424 References602 Part IIntroductionThe correct application of units of measurement is very important in technicalapplications. For this reason, carefully-crafted definitions of a coherent unitssystem have been laid down by theConf rence G n rale des Poids et Mesures1(CGPM): this has resulted in theSyst me International d unit s2(SI). At the sametime, typographic conventions for correctly displaying both numbers and unitsexist to ensure that no loss of meaning occurs in printed to provide a unified method for LATEX users to typeset units andvalues correctly and easily. The design philosophy ofsiunitxis to follow theagreed rules by default, but to allow variation through option settings.

5 In thisway, users can usesiunitxto follow the requirements of publishers, co-authors,universities,etc. without needing to alter the input at intended as a complete replacement forSIunits,SIstyle,unitsdef, units ,fancyu nitsandfancynum. As such, emulation modes are provided for all of thesepackages. Where possible, conventions from the existing solutions have beenused here. For example, the macros\num,\angand\SIact in a very similarfashion to those in existing Conference on Weights and System of IIUsing thesiunitxpackage1 For the impatientsiunitxprovides the user macros: \SI[ options ]{ value }[ pre- unit ]{ unit } \si[ options ]{ unit } \num[ options ]{ number } \ang[ options ]{ angle } \sisetup{ options }plus theSandscolumn types for decimal alignments and units in tables. Thesemacros are designed for typesetting units and values with control of appearanceand with intelligent default, all text is typeset in the current upright, serif maths font.

6 This canbe changed by setting the appropriate package options:obeyallwill use thecurrent font for package includes a unit processor , which allows the use of namedunits or literal values. Named units are processed to correctly include g cm31 10341 2 3 m s 130 mm mm mm mol 1K 1 Jmol \SI{10}{\gram}\\\SI{ }{ ^3}\\\num{1e34}\\\ang{1;2;3}\\\emph{\SI{ 16,7}{\metre\per\second}}\\\textbf{\SI{3 0e3}{\Hz}}\\\SI{ x x }{\milli\metre}\\\sisetup{obeyall}\textb f{\SI{ }{\cm}}\\\si{\joule\per\mole\per\kelvin} \\\si[per=frac]{\joule\per\mole\per\kelv in}\\\num[dp=4]{ }\\\num[dp=4]{ }\\\begin{tabular}{S[tabformat= ]}\toprule{Heading}\\\ \\ \\ \\74,7 \\\bottomrule\end{tabular}42 Requirementssiunitxrequires a reasonably up to date TEX system. The package requires -TEX-extensions, which should be available on most following packagesare also needed: arrayandxspace: from thetoolsbundle, which should be available toeveryone; xkeyval: this processes the option handling, and needs to be at least ; amstext: from theAMSTEX support bundle (theAMSfonts are also neededto provide the default upright ).

7 Hopefully most people using the package will have access to all of those use thefraction=sfracoption, thexfracpackage is needed. This needsvarious experimental LATEX3packages. As a result,siunitxdoes not you want to usefraction=sfrac,youneed to loadxfracin your the package is not loaded,fraction=sfracfalls back on anicefrac-like method. The interested user should look at thexfracdocumentationfor reasons this might not be the packagesiunitxis loaded by the usual LATEX method.\usepackage[<options>]{ siunitx }As is shown in the example, the package can be loaded with one or more options,using the key value system. The full range of package options are describedin Section11; some options are described in the along with the appropriateuser macros. Most of the user macros accept the same key value settings as anoptional are automatically formatted by the\nummacro.

8 This takes one op-\numtional and one mandatory argument:\num[ options ]{ number }. The contentsof number are automatically formatted, in a similar method to that used bynumprint. The formatter removes hard spaces (\,and~), automatically identi-fies exponents (by default marked usingeord) and adds the appropriate spacingof large numbers. A leading zero is added before a decimal marker, if needed:both . and , are recognised as decimal 123 1234 12 451 10 4 1010\num{1} \num{123} \num{1234} \num{12345}\\\num{ } \num{ } \num{0,1234} \num{.12345}\\\num{1e10} \num{ } \num{-e10}3If you have an old LATEX try elatex rather than latex .4 This document has been compiled in this way. You have to loadxfracfirst as otherwise very nastythings happen withxkeyval. MiKTEX users should note that the packaged versions ofexpl3,templateandxparsewill not work withxfrac: download copies fromctan!

9 5On the other hand, some fractional units will look really bad with\sfrac. Use this option error-checking systems are built into the package , so that if number does not contain any numeric characters, a warning is issued. Isolated signs arealso detected. The package recognises(and)as extra characters, which canbe used to indicate the error in a this data to begiven as a separate error value. If the number also contains an exponent, thenbrackets are re-added after the separation to ensure that meaning is not (5) = (5) 106= ( ) 106$\num{ (5)} = \num[seperr]{ (5)}$\\$\num{ (5)e6} = \num[seperr]{ (5)e6}$The same applies to the unit and value macro\SI, described later, for examplethe rest mass of an electron [1]:me= 389 7(54) 10 31kgme= ( 389 7 005 4) 10 31kg$ m_{\mathrm{e}}= \SI{ (54)e-31}{\kg} $\\$ m_{\mathrm{e}}= \SI[seperr]{ (54)e-31}{\kg} $A number of effects are available as options.

10 These are fully explained inSection11. Some of the more useful options are illustrated here. By default, theoutput of the package is typeset in maths mode. However, the use of the currenttext font can be 234 567 8901 234 567 890\num{1234567890} \num[mode=text]{1234567890}siunitxcan automatically add zeros and signs to numbers. This can be altered +23 104+3 104+3 10+ .5\num{1.} \num[padnumber=all]{1.}\\\num{2} \num[addsign=all]{2}\\\num{3e4} \num[addsign=mant]{3e4} \num[addsign=all]{3e4}\\\num{.5} \num[padnumber=none]{.5}The separation of digits can be turned on and off, and the output 1 23412 345 12,34512345\num{1234} \num[sepfour=true]{1234}\\\num{12345} \num[digitsep=comma]{12345}\\\num[digits ep=none]{12345}The formatting of exponents is also 10101 10102 10202 5203 10303 1030\num{1e10} \num[expproduct=cdot]{1e10}\\\num{2e20} \num[expbase=5]{2e20}\\\num{3e30} \num[expproduct=tighttimes]{3e30} siunitx can automatically add colour to negative numbers, which is oftenuseful for highlighting purposes.