Chemistry notation using mhchem

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

The mhchem pack­age pro­vides com­mands for type­set­ting chem­i­cal molec­u­lar for­mu­lae and equa­tions.

Why mhchem?

It is possible to display chemical formulae and equations using TeX mathematics mode. However, it is rather cumbersome for a range or reasons. Different display conventions: uppercase letters are displayed in italics for mathematics, whereas element symbols are upright for chemistry. The complexities of supercript and subscript notation, ions and isotopes. Bonds, equilibrium reaction arrows etc.

The mhchem extension allows a more adaptable display and more natural input of chemical formulae and equations. In Moodle, mhchem syntax can use text input directly into an HTML editor (TinyMCE or Atto) or by an Atto chemistry plugin (similar to the equation plugin).

This is particularly useful for documenting isotopes, relative atomic and relative molecular mass, empirical and molecular formulae, balanced equations (full and ionic), equilibium reactions and themodynamics.

For more complex structural and displayed formulae (e.g. organic chemistry), homologous series and functional groups, you may also wish to consider a 'drawing' plugin such as the MarvinJS-based Chemical structures and reaction editor

Installation

The mhchem package can be integrated with Moodle in one of two ways. In general, the first via MathJax is recommended as this is the simplest to set up and provides high quality rendering. However, Mathax depends on client-side JavaScript processing by the browser and in some circumstances, e.g. on some platforms (mobile) or particularly complex maths/science expressions, where this results in an unacceptable delay in display. Also, there may be conflicts between MathJax and other JavaScript libraries (e.g. in some third-party Moodle plugins). In these cases, it may be advantageous to shift the workload to the server-side via LaTex.

In Moodle 2.8, it is possible to enable both the TeX and MathJax filters in parallel such that the TeX filter (particularly with SVG rendering) provides a fallback for MathJax, and vice versa.

via MathJax

MathJax has become the de facto standard for displaying mathematics on the Web and since version 2.7 Moodle has a built-in MathJax loader filter. However, mhchem still needs to be added to the MathJax configuration.

In Administration > Site administration > Plugins > Filters > Mathjax > Local Mathjax installation, edit the Mathjax configuration to include mhchem.js in the TeX extensions:

TeX: {extensions: ["AMSmath.js","AMSsymbols.js","mhchem.js","noErrors.js","noUndefined.js"]},

For Moodle 2.6 and earlier MathJax, together with the mhchem, extension can be added to the site HEAD section in:

Administration > Site administration > Appearance > Additional HTML > Within HEAD

via LaTeX

It is also possible to add mhchem alongside LaTex on the Moodle server, and then use the Moodle TeX filter. You will need to install and configure the following binaries on the Moodle server.

latex dvips and either dvisvg for SVG rendering (Moodle 2.8 and later) or convert for PNG/GIF rendering (Moodle 2.7 and earlier) mhchem

Installation details will depend on the server operating system. Most Linux distributions can use their standard package manager to install the binaries and dependencies. e.g. For Fedora 20, mhchem can be installed with: yum install texlive-mhchem. Alternatively, you can use a LaTeX installation bundle for Linux, Windows or Macintosh servers.

Once installed, in your Moodle Administration > Site administration > Plugins > Filters > TeX notation > LaTeX renderer Settings, add the following to the LaTeX preamble:

\usepackage{mhchem}

Basics

Note that mhchem is not currently installed in this documentation wiki. Therefore the chemical display of chemical formulae and equations is simulated and may not exactly correspond to rendering using mhchem, which is usually nicer!.

The default TeX delimiters are \[...\] or $$...$$ for displayed mathematics, and \(...\) for in-line mathematics. For mhchem the additional delimiter \ce{...} is required inside the mathematics delimeters i.e .\[\ce{...}\] or $$\ce{...}$$ for displayed chemical formulae, and \(\ce{...}\) for in-line chemical formulae. In the rest of this document the TeX delimiters are not explicitly shown.

$\mathrm {H_{2}O}$ \ce{H2O}

$\mathrm {Sb_{2}O_{3}}$ \ce{Sb2O3}

$\mathrm {H^{+}}$ \ce{H+}

$\mathrm {CrO_{4}^{2-}}$ \ce{CrO4^2-}

$\mathrm {AgCl_{2}^{-}}$ \ce{AgCl2-}

$\mathrm {[AgCl_{2}]^{-}}$ \ce{[AgCl2]-}

$\mathrm {Y^{99+}}$ \ce{Y^{99}+}

$\mathrm {H_{2}(aq)}$ \ce{H2_{(aq)}}

$\mathrm {NO_{3}^{-}}$ \ce{NO3-}

$\mathrm {(NH_{4})_{2}S}$ \ce{(NH4)2S}

Amounts

Place amounts directly in front of a formula. A small space will be inserted automatically.

$\mathrm {2H_{2}O}$ \ce{2H2O}

$\mathrm {{\frac {\scriptstyle {1}}{\scriptstyle {2}}}H_{2}O}$ \ce{1/2H2O}

Isotopes

$\mathrm {{}_{90}^{227}Th^{+}}$ \ce{^{227}_{90}Th+}

Fonts

When you are in a math environment (e.g. opened and closed with a \[...\], \(...)\ or $$...$$), you could simply use \ce to set content in an upright font. Remember: all variables—like V for volume—are set using an italic font, physical units and chemical elements are set using an upright font.

${\mathit {V}}\mathrm {_{H_{2}O}}$ $V_{\ce{H2O}}$

When used in text mode, \ce adapts to the current text font. You could simply write a formula in one of your section titles it would be set with the correct, no matter where is appears (sectiontitle, header, contents, references, ...).

$\mathrm {H_{2}O}$, $\mathrm {H_{2}O}$ \ce{H2O}, $\ce{H2O}$

$\mathrm {Ce^{IV}}$ \ce{Ce^{IV}}

There are some special cases. A negative charge (-) in text mode is replaced with a dash (–), because a text minus sign often is too short. All ‘operators’, e.g. ‘+’ and reaction arrows, are always taken from the math font.

Special Symbols

$\mathrm {KCr(SO_{4})_{2}\cdot 12H_{2}O}$ \ce{KCr(SO4)2*12H2O}

$\mathrm {KCr(SO_{4})_{2}\cdot 12H_{2}O}$ \ce{KCr(SO4)2.12H2O}

$\mathrm {[Cd\{SC(NH_{2})_{2}\}_{2}]\cdot [Cr(SCN)_{4}(NH_{3})_{2}]_{2}}$ \cf{[Cd\{SC(NH2)2\}2].[Cr(SCN)4(NH3)2]2}

$\mathrm {RNO_{2}^{-.}}$, $\mathrm {RNO_{2}^{-.}}$ $\ce{RNO2^{-.}}$, \ce{RNO2^{-.}}

$\mu \!-\!\mathrm {Cl}$ \ce{$\mu\hyphen$Cl}

Bonds

Horizontal bonds can be set using the characters -, = and # (single, double, triple bond) inside a formula (a - at the end of a formula yields a negative charge).

$\mathrm {C_{6}H_{5}\!-\!CHO}$ \ce{C6H5-CHO}

$\mathrm {X\!=\!Y\!\equiv \!Z}$ \ce{X=Y#Z}

$\mathrm {A\!-\!B\!=\!C\!\equiv \!D}$ \ce{A\sbond B\dbond C\tbond D}

Different books visualise bonds in extremely different ways. Currently, the minus sign from the math font is used to display the bonds (even in text mode). The bonds are vertically aligned on the math axis. For most math fonts, this is lower than half the height of a capital letter.

The \bond command allows you to typeset some types of special bonds.

$\mathrm {A\!-\!B\!=\!C\!\equiv \!D}$ \ce{A\bond{-}B\bond{=}C\bond{#}D}

$\mathrm {A\!\sim \!B\!\simeq \!C}$ \ce{A\bond{~}B\bond{~-}C}

$\mathrm {A\!\cong \!B\!\cong \!C\!\cong \!D}$ \ce{A\bond{~=}B\bond{~--}C\bond{-~-}D}

$\mathrm {A\!\cdots \!B\!\cdot \cdots \!C}$ \ce{A\bond{...}B\bond{....}C}

$\mathrm {A\!\rightarrow \!B\!\leftarrow \!C}$ \ce{A\bond{->}B\bond{<-}C}

Using Math

To use math commands inside \ce{...}, one can enclose the commands with $.

$\mathrm {Fe(CN)_{\frac {6}{2}}}$ \ce{Fe(CN)_{$\frac{6}{2}$}}

$\mathrm {{\mathit {x}}Na(NH_{4})HPO_{4}{\overset {\Delta }{\rightarrow }}(NaPO_{3})_{\mathit {x}}+{\mathit {x}}NH_{3}\uparrow +{\mathit {x}}H_{2}O}$ \ce{$x\,$ Na(NH4)HPO4 ->[\Delta](NaPO3)_{$x$} + $x\,$ NH3 ^ + $x\,$ H2O}

Formulae

Reaction Arrows

$\mathrm {CO_{2}+C\rightarrow 2CO}$ \ce{CO2 + C -> 2CO}

$\mathrm {CO_{2}+C\leftarrow 2CO}$ \ce{CO2 + C <- 2CO}

$\mathrm {CO_{2}+C\rightleftharpoons 2CO}$ \ce{CO2 + C <=> 2CO}

$\mathrm {H^{+}+OH^{-}{\overset {-\!-\!-\!\rightharpoonup }{\quad \leftharpoondown \quad }}H_{2}O}$ \ce{H+ + OH- <=>> H2O}

$A\leftrightarrow A'$ \ce{$A$ <-> $A’$}

$\mathrm {CO_{2}+C\;{\overset {\alpha }{\rightarrow }}\;2CO}$ \ce{CO2 + C ->[\alpha] 2CO}

$\mathrm {CO_{2}+C\;{\underset {\beta }{\overset {\alpha }{\rightarrow }}}\;2CO}$ \ce{CO2 + C ->[\alpha][\beta] 2CO}

As with ^ and _, the content above and below reaction arrows is set in math font. When you want to put descriptive text there, use the \text command. Or, as a shortcut, you could type a ‘T’ between reaction arrow and opening bracket.

$\mathrm {CO_{2}+C\;{\overset {above}{\longrightarrow }}\;2CO}$ \ce{CO2 + C ->[\text{above}] 2CO}

$\mathrm {CO_{2}+C\;{\underset {below}{\overset {above}{\longrightarrow }}}\;2CO}$ \ce{CO2 + C ->[\text{above}][\text{below}] 2CO}

$\mathrm {CO_{2}+C\;{\underset {below}{\overset {above}{\longrightarrow }}}\;2CO}$ \ce{CO2 + C ->T[above][below] 2CO}

Similarly, there is a shortcut for using \ce with reaction arrows:

$\mathrm {A\;{\overset {H_{2}O}{\longrightarrow }}\;B}$ \ce{$A$ ->[\ce{+H2O}] $B$}

$\mathrm {A\;{\overset {H_{2}O}{\longrightarrow }}\;B}$ \ce{$A$ ->C[+H2O] $B$}

Precipitate and Gas

Use v or (v) for precipitate (arrow down) and ^ or (^) for gas (arrow up), both separated by spaces.

$\mathrm {SO_{4}^{2-}+Ba^{2+}\rightarrow BaSO_{4}\downarrow }$ \ce{SO4^2- + Ba^2+ -> BaSO4 v}

Watch Out!

Please be aware that you sometimes have to enclose spaces in braces. In particular, you have to do so, when they appear between brackets that belong to an reaction arrow.

$A\mathrm {\overset {\text{Enclose spaces!}}{\longleftarrow \!\!\!-\!\!\!-\!\!\!-\!\!\!-\!\!\!\longrightarrow }} A'$ \ce{$A$ <->T[{Enclose spaces!}] $A’$}

Further Examples

$\mathrm {Zn^{2+}{\underset {+2H^{+}}{\overset {+2OH^{-}}{\rightleftharpoons }}}{\underset {\text{amphoteric hydroxide}}{Zn(OH)_{2}\downarrow }}{\underset {+2H^{+}}{\overset {+2OH^{-}}{\rightleftharpoons }}}{\underset {\text{tetrahydroxozincate}}{[Zn(OH)_{4}]^{2-}}}}$

\ce{Zn^2+ <=>[\ce{+ 2OH-}][\ce{+ 2H+}]$\underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}}$<=>C[+2OH-][{+ 2H+}]$\underset{\text{tetrahydroxozincate}}{\cf{[Zn(OH)4]^2-}}$}

$K=\mathrm {\frac {[Hg^{2+}][Hg]}{[Hg_{2}^{2+}]}}$

$K = \frac{[\ce{Hg^2+}][\ce{Hg}]}{[\ce{Hg2^2+}]}$

$\mathrm {Hg^{2+}\;{\overset {I^{-}}{\rightarrow }}\;{\underset {\text{red}}{HgI_{2}}}\;{\overset {I^{-}}{\rightarrow }}\;{\underset {\text{red}}{[Hg^{II}I_{4}]^{2-}}}}$

\ce{Hg^2+ ->[\ce{I-}]$\underset{\mathrm{red}}{\ce{HgI2}}$->C[I-]$\underset{\mathrm{red}}{\ce{[Hg^{II}I4]^2-}}$}

Further information

The mhchem package

mhchem manual

MathJax and mhchem