chemsym – a L^{A}TEX Macro for Chemical Symbols^{∗}

Mats Dahlgren

                         (matsd@homenet.se)

1997/07/07

Abstract

This document describes the chemsym package, which makes it easier to type chemical symbols correctly, without having to worry about math mode or text mode. Furthermore, chemsym makes both the super- and the subscript commands (^and _) and ‘·’ (\cdot) available in text mode. This file and the package: Copyright \begin{matrix}c \\ ◯ \end{matrix} 1997 by Mats Dahlgren. All rights reserved.

1 Introduction

chemsym is a L^{A}TEX package which makes it easier to type chemical symbols correctly. It defines a command for each element of the periodic table (the 109 first), Deuterium, the Methyl, Ethyl and Butyl groups^{1} (for the Propyle group, use \Pr, Praseodymium), and the −OH, −COOH, and −CH groups. The use of the commands results in a up-right chemical symbol, regardless of whether it is used in math mode or text mode. If not followed by a sub- or superscript, a (, a ), a [, or a ] a small space is added (slightly less than what ‘\,’ gives).

For elements 104-109 there is a (yet not settled) discussion on which names and symbols to use. I have chosen to use the names recommended by IUPAC. These recommendations were published in “Names and symbols of transfermium elements (IUPAC recommendations 1994)”, Pure and Applied Chemistry 1994, 66(12), 2419-2421. The recommended names are Dubnium, Db, Joliotium, Jl, Rutherfordium, Rf , Bohrium, Bh, Hahnium, Hn, and Meitnerium, Mt, respectively.

2 Userguide

2.1 Requirements

The file chemsym.sty must be available in the user’s TEXINPUTS directories. It requires L^{A}TEX 2ε of 1996/12/01 (or newer).

2.2 Usage

The package is included by stating

  \usepackage[option]{chemsym}

In the document preamble. The only option which has any effect on chemsym is collision, see below.

∗This document describes chemsym version 1.1, and was last updated 1997/07/07.

1Suggested by Ulf Henriksson (ulf@physchem.kth.se).

2.3 Commands

chemical The chemsym package defines 116 user commands; one for each of the 109 first elements, Deuterium, symbols the Methyl, Ethyl and Butyl groups (for the Propyle group, use \Pr, Praseodymium), and the −OH,

−COOH, and −CH groups. The command names are all made up of the chemical symbol preceeded by ‘\’; thus for Nitrogen, N, you type \N, and for Mercury, Hg, \Hg, etc. These commands appear to be robust. To obtain ‘CH_{2}’, you simply type ‘\CH_2’ in your input file; ‘CH_{3}’ is obtained by typing ‘\CH_3’ (of course).

\H Since there are six commands in TEX/L^{A}TEX already of this kind (\H, \O, \P, \S, \Re, and

\O
\P
\S
\Re
\Pr

\Pr), and one environment in AMS-L^{A}TEX (the Sb environment),^{2} these old commands have to

Sb

be renamed. The names of choice are shown in the table below.

TEX  With chemsym Use/Example
command  you write
\H          \h  The accent in ‘ő’

                   \O          \OO  Ø
                   \P          \PP  ¶
                   \S          \Ss  §

\Re         \re  ℜ (in math mode)
\Pr         \pr  Pr (in math mode)

                   \begin{Sb}  \begin{SB}  (with AMS-L^{A}TEX)
                   \end{Sb}    \end{SB}  (with AMS-L^{A}TEX)

\kemtkn Also, \kemtkn, a command for defining other chemical symbols and similar functions is available.

\kemtkn takes one mandatory argument (the string to treat as a chemical symbol). Two other \nsrrm internal commands, \nsrrm and \nsrrms are also available. \nsrrm simply puts its (mandatory) \nsrrms argument in mathrm. \nsrrms does the same, but also adds a small space after it. This space is

a second, optional, argument to \nsrrms which should be given in em units (without ‘em’). The ^default is 0.1em. For convenience when typing chemical formulas and units with exponents, the _super- and subscript commands ^and _are made available also outside of math mode, provided

the option collision is not specified. Thus, with chemsym you can type m^2 instead of m$^2$ for m^{2} also in text mode. Analogously, you can type \H_2\O for H_{2}O in both math and text mode and get the same result. Notice that text which you may put in the arguments of ^and _automatically is set in math mode. So if you want ‘M_{q}’ you must type M_{\mathrm{q}} and not only M_q, the latter comes out as ‘M_{q}’. (This feature is not seriously disturbing since this feature with ^and _ is intended to be used mainly with numbers in the arguments.)

\cdot Futhermore, the \cdot command (producing a ‘·’) is also available outside math mode. This feature is included to facilitate typing formulas like “CH_{3}·CH_{3}” (\CH_3\cdot\CH_3) also in text mode.^{3}

2.4 The collision option

collision To avoid probelms with other packages due to ^(and _) being active, this may be swithced off by stating the option collision when loading the chemsym package. If you get the following error message (or a similar), you are likely to have such a collision with chemsym involved (in this case with longtable):

    ! Argument of ^has an extra }.
    <inserted text>

2Thanks to Thorsten Löhl (lohl@uni-muenster.de) for pointing out this.

3Also suggested by Ulf Henriksson (ulf@physchem.kth.se).

                    \par
    l.120 \end{longtable}
    ?

To solve the problem, state the collision option and delete the .aux file before running L^{A}TEX again. Some packages contain ^^J-constructs which may not always be apparent to the user. One example, which collides with chemsym, is the multicol package’s warning if you specify only one column. In that case, the error message is:

    ! Argument of ^has an extra }.
    <inserted text>
                    \par
    l.18 \begin{multicols}{1}
    ?

In this case, you may come around the problem by specifying a number of columns ≥ 2; if not, specify the collision option for the chemsym package.

3 Examples

This section gives some simple examples of the use of chemsym. To write the formula for water in both math and text mode, you type \H_2\O{}, which gives H_{2}O as result. Notice that this differs from typing \H$_2$\O, which gives H_{2}O as result. In the first example, there is not any extra space added after the H. This addition of space makes formulas like HCN (\H\C\N) easier to read than just typing HCN: HCN.

The use of the commands of chemsym is specially useful when chemical symbols are used as indices in equations. The following example illustrates this:

M_{Fe(H_{2}O)_{6}} = 6M_{H_{2}O} + M_{Fe}  (1)

which was obtained by typing

  \begin{equation}
  \mathcal{M}_{\Fe(\H_2\O)_6} = 6\mathcal{M}_{\H_2\O} + \mathcal{M}_{\Fe}
  \end{equation}

It is also easy to define other chemical symbols commands, such as commands for specific isotopes. Suppose you rather want to use the notation ^{2}H than D for Deuterium. This may be defined as:

  \newcommand{\hH}{\kemtkn{{}^2H}}

(which was used above: … notation \hH{} than \D{} for…). Internally, chemsym uses a syntax like this to def ine the various commands for the chemical symbols.^{4}

After running chemsym.ins through L^{A}TEX 2ε, you can typeset the Periodic Table of the Elements by running L^{A}TEX 2ε on the file pertab.tex. (It fits fine on an A4 paper, and there should be no problem with a U.S. lettersize paper as well.) The Periodic Table requires the rotating package, which in turn requires the packages graphicx and ifthen.

4To make the command robust, say \newcommand{\hH}{ \protect\kemtkn{{}}ˆ 2H}} or use the command \DeclareRobustCommand instead of \newcommand.

4 Known Problems

• Since chemsym makes ^and _active, it will collide with other packages which make use of constructs like ^^J (e. g. the longtable package). To avoid this problem, specify the option collision when loading chemsym (or globally).

• If the chemsym package is used together with the rotating or amstex package, chemsym should be loaded last.

• If the chemsym package is used together with the fancyheadings package, fancyheadings should be loaded after chemsym.^{5}

• Since chemsym makes _and ^active, these characters cannot be used in labels when using the chemsym package, nor in file names loaded in L^{A}TEX runs loading the chemsym package (unless you specify the collision option).^{6}

• Also since ^is made active, when following after a prime in math mode ('), a “double superscript” error is produced unless a double bracing ({}) is included before the ^character.^{7} Thus, you should type x'{}^2 instead of x'^2 when using chemsym to obtain x′^{2}.

5 Sending a Bug Report

chemsym is likely to contain bugs, and reports about them are most welcome. Before filing a bug report, please take the following actions:

1. Ensure your problem is not due to your own input file, package(s), or class(es);

2. Ensure your problem is not covered in the section ”Known Problems” above;

3. Try to locate the problem by writing a minimal L^{A}TEX input file which reproduces the problem.

Include the command

  \setcounter{errorcontextlines}{999}

in your input;

4. Run your file through L^{A}TEX;

5. Send a description of your problem, the input file and the log file via e-mail to:

   matsd@homenet.se.

Enjoy your L^{A}TEX!mats d.

5Thanks to Lars Reinton (larsr@stud.unit.no) for pointing out this.

6Thanks to Axel (i0080108@ws.rz.tu-bs.de) for pointing out this problem.

7Thanks to Jeroen Paasschens (paassche@natlab.research.philips.com) for bringing my attention to this problem.

6 The Code

For the interested reader(s), here is a short description of the code. First, the package is to identify itself:

 1 \NeedsTeXFormat{LaTeX2e}[1996/12/01]
 2 \ProvidesPackage{chemsym}[1997/07/07 v.1.1 Chemical symbols]

First in the real code, we have to rename the old functions \H, \O, \P, \S, \Re, and \Pr:

 3 \let\h=\H
 4 \let\OO=\O
 5 \let\PP=\P
 6 \let\Ss=\S
 7 \let\re=\Re
 8 \let\pr=\Pr

Here we check if the AMS-L^{A}TEX package is loaded, and if so, change the Sb environment to be called SB.

 9 \@ifundefined{Sb}{\def\Sb{\protect\kemtkn{Sb}}}%
10 {\let\SB=\Sb \let\endSB=\endSb}

Now, we make ^, _, and \cdot work without $...$ also in text mode – if not switched off. To do this, we need a boolean and some option processing…

11 \newif  \ifc@llsn  \c@llsnfalse
12 \DeclareOption{collision}{\global\c@llsntrue}
13 \DeclareOption*{\OptionNotUsed}
14 \ProcessOptions*
15 \ifc@llsn\AtEndDocument{%
16 \PackageWarningNoLine{chemsym}{Due to possible collisions with other
17 \MessageBreak packages, super- and subscrips are not avaliable
18 \MessageBreak outside math mode despite your loading of `chemsym'}}
19 \else
20 \def\sprscrpt#1{\ensuremath{^{#1}}}
21 \def\sbscrpt#1{\ensuremath{_{#1}}}
22 \catcode`\^\active
23 \catcode`\_\active
24 \let^=\sprscrpt
25 \let_=\sbscrpt
26 \fi
27 \@ifundefined{cd@t}{%
28 \let\cd@t=\cdot
29 \def\cdot{\ensuremath{\cd@t}}}{}

(The \@ifundefined is required for local compatibility reasons at my former site.) Then, some general macros are defined:

30 \newcommand{\nsrrm}[1]{\ensuremath{\mathrm{#1}}}
31 \newcommand{\nsrrms}[2][0.1]{\ensuremath{\mathrm{#2}\kern #1em}}
32 \newcommand{\kemtkn}[1]{\@ifnextchar_{\nsrrm{#1}}{\@ifnextchar^{\nsrrm{#1}}%
33 {\@ifnextchar){\nsrrm{#1}}{\@ifnextchar({\nsrrm{#1}}%
34 {\@ifnextchar]{\nsrrm{#1}}{\@ifnextchar[{\nsrrm{#1}}{\nsrrms{#1}}}}}}}}

As you can see, you can change the spacing in the chemical formulas by making changes to \nsrrms. This you can do with \renewcommand in your document preamble or in another package file. Then we define the 110 commands for chemical symbols:

35 \renewcommand{\H}{\protect\kemtkn{H}} % modified
36 \newcommand{\D}{\protect\kemtkn{D}}

37 \newcommand{\He}{\protect\kemtkn{He}}
38 \newcommand{\Li}{\protect\kemtkn{Li}}
39 \newcommand{\Be}{\protect\kemtkn{Be}}
40 \newcommand{\B}{\protect\kemtkn{B}}
41 \newcommand{\C}{\protect\kemtkn{C}}
42 \newcommand{\N}{\protect\kemtkn{N}}
43 \renewcommand{\O}{\protect\kemtkn{O}} % modified
44 \newcommand{\F}{\protect\kemtkn{F}}
45 \newcommand{\Ne}{\protect\kemtkn{Ne}}
46 \newcommand{\Na}{\protect\kemtkn{Na}}
47 \newcommand{\Mg}{\protect\kemtkn{Mg}}
48 \newcommand{\Al}{\protect\kemtkn{Al}}
49 \newcommand{\Si}{\protect\kemtkn{Si}}
50 \renewcommand{\P}{\protect\kemtkn{P}} % modified
51 \renewcommand{\S}{\protect\kemtkn{S}} % modified
52 \newcommand{\Cl}{\protect\kemtkn{Cl}}
53 \newcommand{\Ar}{\protect\kemtkn{Ar}}
54 \newcommand{\K}{\protect\kemtkn{K}}
55 \newcommand{\Ca}{\protect\kemtkn{Ca}}
56 \newcommand{\Sc}{\protect\kemtkn{Sc}}
57 \newcommand{\Ti}{\protect\kemtkn{Ti}}
58 \newcommand{\V}{\protect\kemtkn{V}}
59 \newcommand{\Cr}{\protect\kemtkn{Cr}}
60 \newcommand{\Mn}{\protect\kemtkn{Mn}}
61 \newcommand{\Fe}{\protect\kemtkn{Fe}}
62 \newcommand{\Co}{\protect\kemtkn{Co}}
63 \newcommand{\Ni}{\protect\kemtkn{Ni}}
64 \newcommand{\Cu}{\protect\kemtkn{Cu}}
65 \newcommand{\Zn}{\protect\kemtkn{Zn}}
66 \newcommand{\Ga}{\protect\kemtkn{Ga}}
67 \newcommand{\Ge}{\protect\kemtkn{Ge}}
68 \newcommand{\As}{\protect\kemtkn{As}}
69 \newcommand{\Se}{\protect\kemtkn{Se}}
70 \newcommand{\Br}{\protect\kemtkn{Br}}
71 \newcommand{\Kr}{\protect\kemtkn{Kr}}
72 \newcommand{\Rb}{\protect\kemtkn{Rb}}
73 \newcommand{\Sr}{\protect\kemtkn{Sr}}
74 \newcommand{\Y}{\protect\kemtkn{Y}}
75 \newcommand{\Zr}{\protect\kemtkn{Zr}}
76 \newcommand{\Nb}{\protect\kemtkn{Nb}}
77 \newcommand{\Mo}{\protect\kemtkn{Mo}}
78 \newcommand{\Tc}{\protect\kemtkn{Tc}}
79 \newcommand{\Ru}{\protect\kemtkn{Ru}}
80 \newcommand{\Rh}{\protect\kemtkn{Rh}}
81 \newcommand{\Pd}{\protect\kemtkn{Pd}}
82 \newcommand{\Ag}{\protect\kemtkn{Ag}}
83 \newcommand{\Cd}{\protect\kemtkn{Cd}}
84 \newcommand{\In}{\protect\kemtkn{In}}
85 \newcommand{\Sn}{\protect\kemtkn{Sn}}
86 \renewcommand{\Sb}{\protect\kemtkn{Sb}}  % modified with AMS-LaTeX
87 \newcommand{\Te}{\protect\kemtkn{Te}}
88 \newcommand{\I}{\protect\kemtkn{I}}
89 \newcommand{\Xe}{\protect\kemtkn{Xe}}
90 \newcommand{\Cs}{\protect\kemtkn{Cs}}

 91 \newcommand{\Ba}{\protect\kemtkn{Ba}}
 92 \newcommand{\La}{\protect\kemtkn{La}}
 93 \newcommand{\Ce}{\protect\kemtkn{Ce}}
 94 \renewcommand{\Pr}{\protect\kemtkn{Pr}} % modified
 95 \newcommand{\Nd}{\protect\kemtkn{Nd}}
 96 \newcommand{\Pm}{\protect\kemtkn{Pm}}
 97 \newcommand{\Sm}{\protect\kemtkn{Sm}}
 98 \newcommand{\Eu}{\protect\kemtkn{Eu}}
 99 \newcommand{\Gd}{\protect\kemtkn{Gd}}
100 \newcommand{\Tb}{\protect\kemtkn{Tb}}
101 \newcommand{\Dy}{\protect\kemtkn{Dy}}
102 \newcommand{\Ho}{\protect\kemtkn{Ho}}
103 \newcommand{\Er}{\protect\kemtkn{Er}}
104 \newcommand{\Tm}{\protect\kemtkn{Tm}}
105 \newcommand{\Yb}{\protect\kemtkn{Yb}}
106 \newcommand{\Lu}{\protect\kemtkn{Lu}}
107 \newcommand{\Hf}{\protect\kemtkn{Hf}}
108 \newcommand{\Ta}{\protect\kemtkn{Ta}}
109 \newcommand{\W}{\protect\kemtkn{W}}
110 \renewcommand{\Re}{\protect\kemtkn{Re}} % modified
111 \newcommand{\Os}{\protect\kemtkn{Os}}
112 \newcommand{\Ir}{\protect\kemtkn{Ir}}
113 \newcommand{\Pt}{\protect\kemtkn{Pt}}
114 \newcommand{\Au}{\protect\kemtkn{Au}}
115 \newcommand{\Hg}{\protect\kemtkn{Hg}}
116 \newcommand{\Tl}{\protect\kemtkn{Tl}}
117 \newcommand{\Pb}{\protect\kemtkn{Pb}}
118 \newcommand{\Bi}{\protect\kemtkn{Bi}}
119 \newcommand{\Po}{\protect\kemtkn{Po}}
120 \newcommand{\At}{\protect\kemtkn{At}}
121 \newcommand{\Rn}{\protect\kemtkn{Rn}}
122 \newcommand{\Fr}{\protect\kemtkn{Fr}}
123 \newcommand{\Ra}{\protect\kemtkn{Ra}}
124 \newcommand{\Ac}{\protect\kemtkn{Ac}}
125 \newcommand{\Th}{\protect\kemtkn{Th}}
126 \newcommand{\Pa}{\protect\kemtkn{Pa}}
127 \newcommand{\U}{\protect\kemtkn{U}}
128 \newcommand{\Np}{\protect\kemtkn{Np}}
129 \newcommand{\Pu}{\protect\kemtkn{Pu}}
130 \newcommand{\Am}{\protect\kemtkn{Am}}
131 \newcommand{\Cm}{\protect\kemtkn{Cm}}
132 \newcommand{\Bk}{\protect\kemtkn{Bk}}
133 \newcommand{\Cf}{\protect\kemtkn{Cf}}
134 \newcommand{\Es}{\protect\kemtkn{Es}}
135 \newcommand{\Fm}{\protect\kemtkn{Fm}}
136 \newcommand{\Md}{\protect\kemtkn{Md}}
137 \newcommand{\No}{\protect\kemtkn{No}}
138 \newcommand{\Lr}{\protect\kemtkn{Lr}}
139 \newcommand{\Db}{\protect\kemtkn{Db}}
140 \newcommand{\Jl}{\protect\kemtkn{Jl}}
141 \newcommand{\Rf}{\protect\kemtkn{Rf}}
142 \newcommand{\Bh}{\protect\kemtkn{Bh}}
143 \newcommand{\Hn}{\protect\kemtkn{Hn}}
144 \newcommand{\Mt}{\protect\kemtkn{Mt}}

At last, we define the three alkyle groups and some other useful groups as chemical symbols:

145 \newcommand{\Me}{\protect\kemtkn{Me}}
146 \newcommand{\Et}{\protect\kemtkn{Et}}
147 \newcommand{\Bu}{\protect\kemtkn{Bu}}
148 \newcommand{\OH}{\protect\kemtkn{OH}}
149 \newcommand{\COOH}{\protect\kemtkn{COOH}}
150 \newcommand{\CH}{\protect\kemtkn{CH}}

This brings us to the end of chemsym. Hope you’ll enjoy it!

Copyright \begin{matrix}c \\ ◯ \end{matrix}1997 by Mats Dahlgren