How to run BKChem from outside

Starting from version 0.9.0-pre1 it is possible to import bkchem from a script and operate it from outside. This short article should help you getting started.

Word of warning

The possibility to run bkchem from a script adds the used a really powerful tool. However, keep in mind that the API is not yet very stable, badly documented and many convenience features are missing. Therefore you should be warned that it might be very frustrating to write such scripts and they may even not work with further versions on BKchem.

Creating the simple script

I will demonstrate the process in calling bkchem from outside on a simple script. It will take a filename of a bkchem file from the command line, open it, recolor all double bonds to red, save the result and quit. You can find the script here.

At the very beginning of the script we just check for the filename to process:

import sys

# at first we check the command line
if len( sys.argv) <= 1:
  print "you have to supply a filename"
  sys.exit()

The most important part comes now - it shows the general approach to the problem of calling bkchem from another application:

# then we import bkchem and threading
from bkchem.bkchem import bkchem
import threading

# bkchem.myapp is the application instance
app = bkchem.myapp

# we need to set batch mode = 1 if we want to suppress some interactive warnings,
# questions and mouse events
app.in_batch_mode = 1  

# now we start the application in a separate thread to be able to manipulate it
t = threading.Thread( target=app.mainloop, name='app')
t.setDaemon( 1)
t.start()

The initial import depends on how you have installed BKchem. You can either make a symlink or copy of the entire bkchem tree to the directory where this script is saved or you can do a source code installation (on linux) and the package will be found by python automatically. In the former case the import shown above applies, in the latter the import statement is only from bkchem import bkchem (because only part of the directory tree is saved under the python site-packages directory).

Because bkchem is a Tkinter application it has its own mainloop that runs all the time the application exists. Therefore you have to run it in another thread in order to be able to use it. Some other remarks are in the comments.

The code that does the actual work is pretty simple and straightforward:

# here comes the actual code

# we load the file
app.load_CDML( sys.argv[1])

# we take all molecules from the current paper, find all the double bonds,
# change their color to red and
for mol in app.paper.molecules:
  for bond in mol.bonds:
    if bond.order == 2:
      bond.line_color = "#aa0000"
      bond.redraw()

# finally we save the result and quit
app.save_CDML()
app.destroy()

We load the file, do the transformation, save the file and quit.

Last word

In the directory doc you can find an automatically generated documentation of the BKChem API. It is not yet very stable, certainly not nice and polished, however its the only one I can offer at this time :).

In any case you can simply ask me. The only limitation is that I will not answer questions in the direction "What is python and how to make it print "hello world"?". Also please use the bkchem mailing list for such questions so that everybody interested can benefit from the discussion.