Initial commit

1 files changed, 219 insertions, 0 deletions

diff --git a/macros/latex/contrib/hepunits/hepunits.tex b/macros/latex/contrib/hepunits/hepunits.tex
new file mode 100644
index 0000000000..325ffa1cfc
--- /dev/null
+++ b/macros/latex/contrib/hepunits/hepunits.tex
@@ -0,0 +1,219 @@
+\documentclass[12pt]{article}
+\usepackage{maybemath, xspace, setspace, fancyvrb, a4wide}
+\usepackage{url, relsize, booktabs, ccaption, braket}
+\usepackage{hepunits}
+\usepackage[colorlinks=true,bookmarks=true]{hyperref}
+\newcommand{\hepunits}{\texttt{hepunits}\xspace}
+
+\let\OldCite\cite
+\renewcommand{\cite}[1]{\mbox{\!\!\OldCite{#1}}}
+
+\onehalfspacing
+\DefineShortVerb{\|}
+
+\author{Andy Buckley, \texttt{andy@insectnation.org}}
+\title{The \hepunits \LaTeX{} package}
+
+\newcommand{\Or}{\ensuremath{\vert}\xspace}
+\newcommand{\manifestsAs}{\ensuremath{\Rightarrow\quad}\xspace}
+\newcommand{\texcmd}[1]{\texttt{\char`\\#1}} 
+\newcommand{\texenv}[1]{\texttt{\char`#1}} 
+\newcommand{\texopt}[1]{\texttt{\char`#1}}
+\newcommand{\texarg}[1]{\texttt{\char`#1}}
+\newcommand{\texpkg}[1]{\texttt{\char`#1}}
+\newcommand{\texcls}[1]{\texttt{\char`#1}}
+\newcommand{\texcommand}[1]{\texcmd{#1}} 
+\newcommand{\texoption}[1]{\texopt{#1}}
+\newcommand{\texgen}[1]{\ensuremath{\braket{\text{\emph{#1}}}}}
+\newenvironment{snippet}{\Verbatim}{\endVerbatim}
+
+\begin{document}
+\maketitle
+
+\abstract{%
+  The \hepunits package extends the existing (and excellent) \texpkg{SIunits}
+  package to support units commonly used in high-energy physics. HEP uses a
+  rather specialised set of units to describe measurements of energies, masses,
+  momenta, reaction cross-sections, luminosities and so-on. Using this package
+  will provide particle physicists with a consistent and accurate way to refer
+  to dimensionful HEP quantities.
+%
+}
+
+\section{Recommended usage}
+The basic usage mode for \hepunits is to place
+%
+\begin{snippet}
+\usepackage{hepunits}
+\end{snippet}
+%
+in the preamble of your document. \hepunits also supports the \texpkg{SIunits}
+optional arguments (\texopt{thickspace}, \texopt{amssymb} and so-on), which are
+passed on directly to the \texpkg{SIunits} package. By default the
+\texopt{mediumspace}, \texopt{thickqspace}, \texopt{squaren} and
+\texopt{textstyle} options are passed, but these can be overridden.
+\texopt{amssymb} and \texopt{squaren} are considered to be mutually exclusive
+options, but you can choose to pass neither option to \texpkg{SIunits} by using
+the \hepunits \texopt{noamssquareissue} option. Additionally, the \hepunits
+\texopt{notextstyle} option can be used to turn the \texpkg{SIunits}
+\texopt{textstyle} off. On the whole, though, you should be able to use
+\hepunits with no options in most circumstances and are likely only to need them
+if you want access to the binary or derived units (using \texopt{binary} and
+\texopt{derived}/\texopt{derivedinbase} respectively).
+
+Finally, the only \hepunits-specific option is \texopt{noprefixcmds}. This is
+discussed at the end of the document and is probably only useful for macro
+language pedants!\footnote{No offence intended to macro language pedants, of course\dots}
+
+
+\section{Requirements}
+\hepunits requires the \texpkg{SIunits}, \texpkg{xspace} and \texpkg{amsmath}
+packages to be installed as part of your \TeX{} distribution. I don't know of
+any distributions for which this isn't the case, so chances are you're safe to
+just install \hepunits and use it right away!
+
+
+\section{Provided units}
+The HEP units provided by \hepunits are listed in Tables \ref{tab:normunits} and
+\ref{tab:hepunits} below. All the example outputs have been produced with a
+command like |\unit{1.0}{|\texgen{unit}|}| where \texgen{unit} is one of the
+unit commands listed in the tables.
+
+\begin{table}[ht]
+\centering
+\begin{tabular}{ll}
+\toprule
+Unit command & Example \\
+
+\midrule 
+Lengths & \\
+\texcmd{nm} & \unit{1.0}{\nm} \\
+\texcmd{micron} & \unit{1.0}{\micron} \\
+\texcmd{mm} & \unit{1.0}{\mm} \\
+\texcmd{cm} & \unit{1.0}{\cm} \\
+
+\midrule 
+Times & \\
+\texcmd{ns} & \unit{1.0}{\ns} \\
+\texcmd{ps} & \unit{1.0}{\ps} \\
+\texcmd{fs} & \unit{1.0}{\fs} \\
+\texcmd{as} & \unit{1.0}{\as} \\
+
+\midrule 
+Rates & \\
+\texcmd{mHz}   & \unit{1.0}{\mHz} \\
+\texcmd{Hz}    & \unit{1.0}{\Hz} \\
+\texcmd{kHz}   & \unit{1.0}{\kHz} \\
+\texcmd{MHz}   & \unit{1.0}{\MHz} \\
+\texcmd{GHz}   & \unit{1.0}{\GHz} \\
+\texcmd{THz}   & \unit{1.0}{\THz} \\
+
+\midrule 
+Misc. & \\
+\texcmd{mrad} & \unit{1.0}{\mrad} \\
+\texcmd{gauss} & \unit{1.0}{\gauss} \\
+
+\bottomrule 
+\end{tabular}
+\caption{List of non-HEP specific units provided by \hepunits}
+\label{tab:normunits}
+\end{table}
+
+\begin{table}[ht]
+\centering
+\begin{tabular}{ll}
+\toprule
+Unit command & Example \\
+\midrule 
+Luminosities & \\
+\texcmd{invcmsqpersecond} & \unit{1.0}{\invcmsqpersecond} \\
+\texcmd{invcmsqpersec} & \unit{1.0}{\invcmsqpersec} \\
+\texcmd{lumiunits} & \unit{1.0}{\lumiunits} \\
+
+\midrule
+Cross-sections & \\
+\texcmd{barn} & \unit{1.0}{\barn} \\
+\texcmd{invbarn} & \unit{1.0}{\invbarn} \\
+\texcmd{nanobarn}    & \unit{1.0}{\nanobarn} \\
+\texcmd{invnanobarn} / \texcmd{invnb} & \unit{1.0}{\invnanobarn} \\
+\texcmd{picobarn}    & \unit{1.0}{\picobarn} \\
+\texcmd{invpicobarn} / \texcmd{invpb} & \unit{1.0}{\invpicobarn} \\
+\texcmd{femtobarn}    & \unit{1.0}{\femtobarn} \\
+\texcmd{invfemtobarn} / \texcmd{invfb} & \unit{1.0}{\invfemtobarn} \\
+\texcmd{attobarn}    & \unit{1.0}{\attobarn} \\
+\texcmd{invattobarn} / \texcmd{invab} & \unit{1.0}{\invattobarn} \\
+
+\bottomrule 
+\end{tabular}
+\caption{List of HEP-specific units provided by \hepunits}
+\label{tab:hepunits}
+\end{table}
+
+
+\begin{table}[ht]
+\centering
+\begin{tabular}{ll}
+\toprule
+Unit command & Example \\
+\midrule
+\eV-based units & \\
+\texcmd{eV} & \unit{1.0}{\eV} \\
+\texcmd{inveV} & \unit{1.0}{\inveV} \\
+\texcmd{eVoverc} & \unit{1.0}{\eVoverc} \\
+\texcmd{eVovercsq} & \unit{1.0}{\eVovercsq} \\
+\texcmd{meV} & \unit{1.0}{\meV} \\
+\texcmd{keV} & \unit{1.0}{\keV} \\
+\texcmd{MeV} & \unit{1.0}{\MeV} \\
+\texcmd{GeV} & \unit{1.0}{\GeV} \\
+\texcmd{TeV} & \unit{1.0}{\TeV} \\
+\texcmd{minveV} & \unit{1.0}{\minveV} \\
+\texcmd{kinveV} & \unit{1.0}{\kinveV} \\
+\texcmd{MinveV} & \unit{1.0}{\MinveV} \\
+\texcmd{GinveV} & \unit{1.0}{\GinveV} \\
+\texcmd{TinveV} & \unit{1.0}{\TinveV} \\
+\texcmd{meVoverc} & \unit{1.0}{\meVoverc} \\
+\texcmd{keVoverc} & \unit{1.0}{\keVoverc} \\
+\texcmd{MeVoverc} & \unit{1.0}{\MeVoverc} \\
+\texcmd{GeVoverc} & \unit{1.0}{\GeVoverc} \\
+\texcmd{TeVoverc} & \unit{1.0}{\TeVoverc} \\
+\texcmd{meVovercsq} & \unit{1.0}{\meVovercsq} \\
+\texcmd{keVovercsq} & \unit{1.0}{\keVovercsq} \\
+\texcmd{MeVovercsq} & \unit{1.0}{\MeVovercsq} \\
+\texcmd{GeVovercsq} & \unit{1.0}{\GeVovercsq} \\
+\texcmd{TeVovercsq} & \unit{1.0}{\TeVovercsq} \\
+
+\bottomrule 
+\end{tabular}
+\contcaption{List of HEP-specific units provided by \hepunits (cont.)}
+\label{tab:hepunits2}
+\end{table}
+
+Note that a lot of these units have, for convenience, been provided as explicit
+commands with various SI prefixes, rather than just defining the base unit and
+using the \texpkg{SIunits} prescription for the prefixes. Let's give a demo in
+case you don't know what I'm waffling about\dots the ``usual'' \texpkg{SUunits}
+way of doing things is like this:
+|\unit{1.0}{\mega\eVoverc}|. This produces ``\unit{1.0}{\mega\eVoverc}''
+just like |\unit{1.0}{\MeVoverc}| would do.
+
+I've chosen to provide the explicit prefixed commands for convenience: choose
+your own favourite way (the same applies even more so for most of the non-HEP
+units). If you are bothered about the explictly prefixed commands clogging up
+the \LaTeX{} macro namespace then pass the \texopt{noprefixcmds} option to
+\hepunits and the offending commands won't be defined at all. This will make
+life awkward when it comes to inverse cross-sections as used for integrated
+luminosities, but with suitable use of \texcmd{invbarn} I'm sure you can make
+do.
+
+\section{Summary}
+\hepunits is a handy package for particle physicists who'd like their units to
+look right, with upright \micro{s} and properly italicised $c$s in the
+appropriate places. Fortunately most of the work has already been done by the
+marvellous \texpkg{SIunits} package and I've just provided a few more commands
+and an option passing wrapper on to that excellent piece of work.
+
+If you have any comments, criticism, huge cash donations etc., then please do
+send them my way. Email to |andy@insectnation.org| is preferred, but if you can
+find a way to get your message to me by carrier pigeon I'll be very impressed.
+
+\end{document}