\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}
