Writing Chemistry with LaTeX (3/3)

In this last part of writing chemistry with LaTeX, we will look at the chemscheme portion of chemstyle.  It offers automatic tracking for schemes and compounds, and is a major time-saver for synthetic chemists.  Download example packages here: version 1, version 2.

Before we look at how to work with chemscheme, let me show you what it can do.  Imagine you are writing the following report: Fischer Esterification.

If you’re writing this in a word processor, your work-flow would likely be to draw and number the structures in ChemDraw.  Then you will either drag it directly into the word processor, or prepare a .tiff of it and link/embed that into the document.  You would be careful to make sure that duplicated compounds (e.g., 1 here) gets the same numbering.  You would be very careful in making sure that the numbers in the main text are the right numbers throughout, and you’re very proud that it all works out just right.

And then, your supervisor made a thoughtful comment that you should include what the real target and its starting material is.  And those should go in front of all your structures.  Now you’re in a not-so-great place: the two compounds will displace all your numbering, and you have to renumber all your figures, and then track down all the stray numbers.  Our example is trivial, but imagine doing that with a paper that has over 100 compounds, spreading across 200 pages!

chemstyle provides a behind-the-scenes mechanism to automatically track down the numbering of compounds and schemes, so the numbers are always right after you hit typeset.  To make the change to what the supervisor suggested, all I did here is just adding the additional scheme, and LaTeX-chemstyle does the hard work:

And in the rest of this post, we’ll look at the syntax and workflow that make this happen.  WordPress.com doesn’t color LaTeX syntax, so I’ll settle with screenshots.  You may want to follow with the examples, and they can be downloaded here: version 1, version 2.  Version 1 is the initial, version 2 is revised with the supervisor’s suggestion.

Structure Drawing

Draw the structures in your drawing program as usual (I’m using ChemDraw here).  However, instead of manually numbering the molecules, place a tag where there number would be; the default behaviour in chemstyle is to search for “TMP”.  Your structure file would thus look like:

You would probably want to save a copy as ChemDraw file as you usually do (in case you need to edit it), and you will need to save an additional copy as .eps (Encapsulated PostScript).  .eps, unlike .jpg or .png, is a vector file that LaTeX (through PSTricks) knows how to open up and replace content with.

In ChemDraw, choose Save As, and select .eps. On OSX, you’re given a choice of Mac or text format, and it does not matter which one you choose to use.  I like to organize my files in a /Figures/ directory, instead of saving directly with the paper.

Repeat for each scheme or structure.  When there are more than one structure you would want to label, use TMP1, TMP2… to denote them from left to right.

Annotating in LaTeX

The chemstyle package provide many different options to format the numbers.  For example: numbering with 1a, 1b, 1c; custom formatting for the labels (I use magenta here to make them stand out better); see the manual for more details.  We will only be concerned with getting the basics working here.

We need to first insert two lines in the preamble of our file (i.e., before \begin{document}:

A – you’re already familiar with the chemstyle line.  The auto-pst-pdf allows you to use .eps files with pdfLaTeX by converting them into .pdf on the fly.  The 2 runs is required for the text-substitution (I think – if someone can clarify, that’d be great).  auto-pst-pdf is included in major LaTeX implementations.

B – these lines modify the \schemerefformat command with the instructions to make it magenta and italics.  I tried this as part of the tutorial in Wright’s documentation, and I like it.  It stands out better, I think.  (When you are ready to submit your manuscript, just take out these lines to make the compound numbers bold, black, and boring again.)

The preamble is thus set up.  In your main text, whenever you need a scheme, all you need to do is:

  • The \begin/\end{scheme} indicates the scope of the scheme and that it is a scheme at first place – LaTeX counts quietly in the background to make sure the numbering in the caption and the textcomes out right.
  • \begin/\end{center} tells LaTeX you want the scheme to be in the middle (as opposed to being on the left or right side of the page).
  • \schemeref[TMP]{cmpd:PhCOOiPr} indicates that the words “TMP” in the .eps file is to be substituted with a number, and that number is for a compound called “cmpd:PhCOOiPr”.  You could have name it anything you like – “isopropylbenzoate”, “1methyl2ethylbenzoate” – but it should be unique for that compound.  This is the handle you will refer to it in the main text.  (I like to append cmpd: to tell myself it’s a compound; sch: for schemes, and fig: for figures, etc.)
  • \includegraphics line simply tells LaTeX which graphic to use here.

If you have multiple tags to substitute (TMP1, TMP2), then you will need one \schemeref[]{} line for each tag.

In the main text, wherever you want the number for a compound to appear, you will use the command \compound{name}; for example, for the ester above, it would be \compound{cmpd:PhCOOiPr}.

Note that the first time you typeset this, a bunch of ?? is in the manuscript where I promised you numbers, even though the compounds in the scheme received the right numbering:

This is because LaTeX needs to go through the manuscript once to generate the numbers, and as it do so, it keeps a running tally of the name:number pair in an auxiliary file.  The second time you typeset, it looks and see that there is an auxiliary file available, and will use that to fill in the ??s.

There is a bug related to this.  If the manuscript had been typeset before, and new compounds are added in, the main text does not update correctly.  To avoid that, you’ll need to trash the .aux file so that the whole numbering is redone from scratch.  (Be careful about when you trash .auxs, especially when you’re generating a bibliography as well.)

And that will get your numbering right all the time.  A very acceptable trade-off for a short learning curve… thank you to Joseph Wright and others whose work he built upon.

Addendum April 6th 2010: I heard back from Joseph about the misnumbering of compounds.  This may be of interest to everyone using chemscheme/chemcompounds:

You’re the second person who’s mentioned this to me recently. The way that chemstyle works is just by loading the chemcompounds package. Due to the way floats are processed it’s safest to include \compound* instructions before the floats to keep the numbering “in order”. I tend to have a block of \compound* lines at the start of each chapter/file so that everything stays in order.


18 thoughts on “Writing Chemistry with LaTeX (3/3)

  1. It might be regarded as a commercial (because I wrote this software), but there exist also another method for automatic compounds numbering in publications – using a konwerter software (http://piti.exroot.org/konwerter/). You can create the eps picture with the multiple reactions schemes, and all compounds there will be numbered. Might be a good choice – I know a few people have used it and were very happy.


  2. Pingback: Chemistry with LaTeX « Polariton

  3. You have just made my day. I have been so worried about how to get this sorted before I start typiong up my thesis (should have started months ago but I have kept putting it of) and you have just solved all my problems (apart from the obvious procastination problems I have).

    Thank you soooo much, it was just what I was looking for.

    • You’re welcome – if there are other LaTeX/chemistry questions, feel free to ask – I’ve probably bumped all the walls at least once by now. Additionally, if you happen to be a python-enabled synthetic chemist,

  4. I downloaded your prepared tex file (version 2) and it didn’t work – auto-pst-pdf showed some errors on creating/finding files. So I figured out that you need to add [crop=off] to the \usepackage{auto-pst-pdf}.
    Citation from the manual:
    Heiko Oberdiek’s pdfcrop Perl script must be installed for the default crop=on option. Under Windows, a Perl installation will also need to be installed even though pdfcrop itself is part of MiKTEX.

    • Hi Greem – I’m in the process of migrating Toeholds to an external site (while finishing a thesis), so I may not get to digging the root of this. On my machine, with TextMate-pdfLaTeX it typesets without the need of the extra option – but it’s great that you found a solution that works and gives other something to try!

  5. Hey,

    I really like your post and it will really help me with writing my thesis. But I have a problem with the misnumering of compounds. Even in your exaple files. The number is in this line: Our research project requires a target ester 3 whose starting material 4
    requires 15 synthetic steps.
    Are changed in 3 and 4 as you can see. I just run the tex file twice? I have the same problem with my own thesis file. Do you maybe have a soloutin for it. I’m using Kile on Ubuntu. And the latex-run is like pdflatex –shell-escape
    -interaction=nonstopmode ‘%source’

    Thanx for the help,


    • Hi Boudewijn – I once remember writing to Joseph Wright about this, and I don’t remember what his solution was. The problem, IIRC, has to do with the order in which things gets replaced in the text vs. the images, and re-typesetting does not in itself solve it. The short solution is to establish the order using a list of \compound*{} (which does not actually print anything to the file) in the beginning of the file before you typeset the final draft, ordered by the sequence where they appear in the images. At some point I wrote a python script that automatically extracts and places that, but I don’t know where I’ve (mis)placed it. If it’s just 15 compounds, a search and copy would be sufficient. Jon

      PS, I’ve moved my blog to a new domain, as I want to start writing science’y browser-based apps and WP doesn’t let me do that. It’s at http://www.jkwchui.com; eventually all posts in this blog will be redirected that (when that site is fully populated with content).

      • Hey Jon,

        Thanx, I made a list of compounds (marked \compound*{}) in the beginning of each section. This works perfect. However it is to bad that the chemstyle package takes the \compounds as primairy numbering instead of the \schemeref{} because I think this solves the problem.
        Thanx again and I will check out you new website.



      • Yes, it’s unfortunate that chemscheme works that way. I have some plans to package my homebrew LaTeX tools (the \schemeref{} extractor, my whole thesis with all the gadgets as LaTeX for people to look through, new tutorials with experience from writing the 1000+ pages, visual template builder etc.) – but they’ll have to wait until the dissertation is submitted. (Any day now!) Good luck on your writing. Jon

  6. Hey jon,

    Here I’m again. I have a other small problem with the chemstyle package. I want to change the font size of the references. But I could not find how to do this. Do you have a solution for this problem.



    • I assume you’re talking about the compound references (and not the bibliography). Are you referring to the *\compound{}* in text or the * \schemeref{}* in the pictures?

      • Sorry that I was not really clear on that. I meant the bibliography size. Because i thought it was fixed by chemstyle. But it isn’t so I changed it with {\footnotesize

        Sorry for my to fast post.

        Good luck with your defense,


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s