Open Babel: Getting Started

Introduction to Open Babel API

Open Babel is a full chemical software toolbox. In addition to converting file formats, it offers a complete programming library for developing chemistry software. The library is written primarily in C++ and also offers interfaces to other languages (e.g., Perl and Python) using essentially the same API.

The heart of Open Babel lies in the OBMol, OBAtom, and OBBond classes, which handle operations on atoms, bonds and molecules. Newcomers should start with looking at the OBMol class, designed to store the basic information in a molecule and to perceive information about a molecule.

Evaluation

One of the key philosophies in the code is that transformations and automatic perception of properties are performed in a "lazy" manner. That is, until you call for partial atomic charges, no charges are calculated. This ensures faster transformations of chemical data -- properties that are not needed for your code will typically not be calculated. When such data is needed, appropriate routines are called, and a "flag" is set (e.g., via OBMol::SetFlag or OBAtom::SetFlag etc.) so that the code is only run once.

Data

Arbitrary custom data and text descriptors can be stored in any atom, bond, molecule, or residue using the OBGenericData or OBPairData classes.

Conversion between various chemical file formats is accomplished through the OBConversion and OBFormat classes, often through use of the OBMoleculeFormat subclass which is designed for easy read/write access to one or more OBMol objects. The philosophy of the file format codes is to parse as much chemical information from a given file as possible (no data left behind) and ideally any perception or transformations will occur when writing to some other format later.

Getting Started

Not surprisingly, the Open Babel library is a full chemical toolbox. So to start out, the first example is to read in molecular file data and uses the OBMol, and OBConversion classes. The former is designed to store the basic information in a molecule and to perceive information and chemical properties. The latter is designed to handle conversion of a variety of data (i.e., not just molecules) and import and export.

This example program shows how to read in a molecule, check the number of atoms, and write a SMILES string.

      #include <iostream.h>

      // Include Open Babel classes for OBMol and OBConversion
      #include <openbabel/mol.h>
      #include <openbabel/obconversion.h>

      int main(int argc,char **argv)
      {
         // Read from STDIN (cin) and Write to STDOUT (cout)
         OBConversion conv(&cin,&cout);

         // Try to set input format to MDL SD file
         // and output to SMILES
         if(conv.SetInAndOutFormats("SDF","SMI"))
         {
            OBMol mol;
            if(conv.Read(&mol))
            {
               //  ...manipulate molecule
               cerr << " Molecule has: " << mol.NumAtoms()
                    << " atoms." << endl;
            }

            // Write SMILES to the standard output
            conv->Write(&mol);
         }
         return 0; // exit with success
      }

All of the main classes, including OBMol and OBConversion, include example code designed to facilitate using the Open Babel code in real-world chemistry. Complete examples are provided in the doc/examples directory and all these examples are included in the documentation.

For a further list of example code, see the developer tutorials. This section includes examples in C++, Perl, Python, and other programming languages.

Also, the tools directory of the Open Babel source releases include a variety of programs which are intended to be more advanced examples (although usually still under 300 lines of code).

Please e-mail the [email protected] mailing list if you have more questions!

Further Information

Open Babel is a community project. In addition to this API documentation, the website offers a variety of up-to-date and useful information for developing with the library.

Open Babel homepage:

SourceForge project pages: