1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Open Babel: Migration from 1.x to 2.0</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
<link rel="top" href="http://openbabel.sourceforge.net/" />
<link rel="stylesheet" href="site.css" type="text/css" media="all" />
</head>
<body bgcolor="#ffffff">
<div id="header">
<img src="babel130.png" width=130 height=124 alt="Babel Logo" id="logo" />
<h1><img src="OBTitle.jpg" width=333 height=92 alt="Open Babel" /></h1>
</div>
<div id="content">
<h1>Migration from Open Babel 1.x</h1>
<h2>(a.k.a. What's New for Developers in Open Babel 2.0)</h2>
<p>$Date: 2005-11-17 19:53:15 -0500 (Thu, 17 Nov 2005) $</p>
<h2>General:</h2>
<p>Many things have changed internally in the new Open Babel 2.0
release, including a variety of new classes, methods, and
algorithms. For a full list of what's new, see the <a
href="../NEWS">Release Notes</a> and <a href="../ChangeLog">Change Log</a>.</p>
<p>This document aims to outline major changes in the Open Babel
library which differ from previous versions. In general, major version numbers of Open Babel indicate major changes to the library which will break backwards-compatibility in at least some areas. For example 1.x to 2.x represents changes that are backwards-incompatible as well as several new interfaces. Changes between 2.0 and 2.1 will <strong>add</strong> but <strong>not break</strong> existing code</p>
<p><a name="toc">There are four main areas of updates:</a></p>
<ul>
<li><a href="#obconversion">OBFileFormat vs. OBConversion</a></li>
<li><a href="#iterators">Iterator Classes</a></li>
<li><a href="#errors">Error Handling</a></li>
<li><a href="#generic">Generic Data</a></li>
</ul>
<h2><a name="obconversion">OBFileFormat vs. OBConversion</a></h2>
<p>By far the largest change between Open Babel 1.x and 2.0 is the
introduction of the OBConversion and OBFormat classes to handle
reading and writing chemical data, replacing the OBFileFormat
class. There are several main advantages to these new classes.</p>
<ul>
<li>Dynamic loading and unloading of file formats.</li>
<ul>
<li>This means that to write a new format, only one file (with the
format code) is needed. No other code changes are required.</li>
<li>In Open Babel 1.x, in addition to the file format code, 2 code
files, 2 header files, and extable.txt needed to be changed.</li>
</ul>
<li>Better support for formats which handle multiple molecules "records" in one file (e.g., CML, MDL Molfile, SMILES, etc.).</li>
<li>Batch conversion, splitting, and joining multiple molecule files.</li>
<li>Support for handling reaction data (e.g., MDL Rxn, CMLReact files) and other types of chemical data beyond simple molecular files.</li>
</ul>
<h3>Code Changes</h3>
<p>Example code for accessing OBConversion and OBFormat to translate files is included in all of the command-line programs <code>babel</code>, <code>obgrep</code>, <code>obfit</code>, etc. For example:</p>
<pre>
// old code
ifstream ifs(filename);
io_type inFileType = extab.FilenameToType(FileIn);
if (extab.IsReadable(inFileType) && extab.IsWritable(SMI)
{
OBMol mol(inFileType, SMI);
stringstream outstream;
fileFormat.ReadMolecule(ifs, mol, filename);
fileFormat.WriteMolecule(outstream, mol);
...
}
</pre>
<p>now becomes</p>
<pre>
// new code
ifstream ifs(filename);
OBConversion conv;
// Try
OBFormat* inFormat = conv.FormatFromExt(filename);
OBFormat* outFormat = conv.GetFormat("SMI");
istream* pIn = &ifs;
stringstream newstream;
if(inFormat && outFormat)
{
conv.SetInAndOutFormats(inFormat,outFormat);
conv.Convert(pIn,&newstream); // note works on more than just OBMol objects! (reactions...)
...
}
</pre>
<p>Here's another example of setting up the <a href="http://openbabel.sourceforge.net/dev-api/classOpenBabel_1_1OBConversion.shtml">OBConversion</a> framework:</p>
<pre>
OBConversion conv(&cin,&cout);
if(conv.SetInAndOutFormats("SMI","MOL"))
{
OBMol mol;
if(conv.Read(&mol))
...manipulate molecule
conv->Write(&mol);
}
</pre>
<p>Some small changes are needed to the file format translator code modules themselves. In general, these are easy to see from the current code files, e.g., <code>src/formats/xyzformat.cpp</code>. If your format writes molecular records (as opposed to reactions), you will likely be able to derive from the <a href="http://openbabel.sourceforge.net/dev-api/classOpenBabel_1_1OBMoleculeFormat.shtml">OBMoleculeFormat</a> class.
</p>
<p>For more information, see the <a href="http://openbabel.sourceforge.net/dev-api/classOpenBabel_1_1OBConversion.shtml">OBConversion</a> API documentation.</p>
<p><a href="#top">Top</a>
<h2><a name="iterators">Iterator Classes</a></h2>
<p>
To facilitate iteration through all atoms, bonds, residues, etc, without resorting to index access (which may change in the future) or the various OBMol::BeginAtom() and OBAtom::NextAtom() methods which may only be safely used by one method at once (e.g., if your code is multithreaded, or a method above your code or underneath your code uses these iterators, errors will occur).
</p>
<p>
Therefore, it is <strong>highly recommended</strong> to use the new STL-style iterator classes introduced into Open Babel 2.0.
</p>
<h3>Code Changes</h3>
<p>No old code <strong>needs</strong> to be updated to work with Open Babel 2.0. However, the old iterator methods are deprecated and will disappear in some future release. The new methods are easier to use and less error-prone, so it is highly recommended to convert. For example:</p>
<pre>
// old code
#include "mol.h"
OBAtom *atom;
OBAtom *nbr;
vector<OBEdgeBase*>::iterator i;
for (nbr = atom->BeginNbrAtom(i);nbr;nbr = atom->NextNbrAtom(i))
...
</pre>
<p>becomes</p>
<pre>
// new code
#include "obiter.h"
#include "mol.h"
OBAtom *atom;
FOR_NBORS_OF_ATOM(nbr, atom)
{
...
</pre>
<p>For more information, see the documentation for the <a href="http://openbabel.sourceforge.net/dev-api/classOpenBabel_1_1OBMol.shtml">OBMol</a> class.
<p><a href="#top">Top</a></p>
<h2><a name="errors">Error Handling</a></h2>
<p>
In order to allow users and developers to easily redirect, filter, and log errors, debugging messages, and internal "audit log" information when molecules are altered, the new OBMessageHandler class has been added.
</p>
<h3>Code Changes</h3>
<p>Rather than using <code>std::cerr</code> or <code>std::cout</code> or the old <strong>ThrowError()</strong> method, you should use the global obErrorLog object.</p>
<pre>
ThrowError("Requested Atom Out of Range");
...
std::cerr << " Could not parse line in type translation table types.txt -- incorect number of columns";
std::cerr << " found " << vc.size() << " expected " << _ncols << "." << std::endl;
</pre>
<p>becomes...</p>
<pre>
// new code
obErrorLog.ThrowError(__FUNCTION__, "Requested Atom Out of Range", obDebug);
...
stringstream errorMsg;
errorMsg << " Could not parse line in type translation table types.txt -- incorect number of columns";
errorMsg << " found " << vc.size() << " expected " << _ncols << ".";
obErrorLog.ThrowError(__FUNCTION__, errorMsg.str(), obInfo);
</pre>
<p>For more information, see the <a href="http://openbabel.sourceforge.net/dev-api/classOpenBabel_1_1OBMessageHandler.shtml">OBMessageHandler</a> class.</p>
<p><a href="#top">Top</a></p>
<h2><a name="generic">Generic Data</a></h2>
<p>
The OBGenericData class has some small modifications, notably the expansion of hash-index access through the old obDataType class to <a href="http://openbabel.sourceforge.net/dev-api/namespaceOpenBabel_1_1OBGenericDataType.shtml">OBGenericDataType</a>, with named unsigned integers. In particular, this greatly facilitates the storage and manipulation of essentially an unlimited number of data types on a per-atom, per-bond, per-residue, or per-molecule basis.
</p>
<h3>Code Changes</h3>
<p>Very little needs to be done. If you have derived a subclass of <a href="http://openbabel.sourceforge.net/dev-api/namespaceOpenBabel_1_1OBGenericData.shtml">OBGenericData</a>, then you should also pick a new <a href="http://openbabel.sourceforge.net/dev-api/namespaceOpenBabel_1_1OBGenericDataType.shtml">OBGenericDataType</a>, using some of the undefined namespace. (We would prefer if you also let us know, so we can minimize conflicts or future compatibility problems.)
</p>
<pre>
if (mol.HasData(obUnitCell))
{
OBUnitCell *uc = (OBUnitCell*)mol.GetData(obUnitCell)
...
}
...
if (mol.HasData("Author"))
...
</pre>
<p>becomes...</p>
<pre>
if (mol.HasData(OBGenericDataType::UnitCell))
{
OBUnitCell *uc = (OBUnitCell*)mol.GetData(OBGenericDataType::UnitCell)
...
}
// String access doesn't need to be changed at all
if (mol.HasData("Author"))
...
</pre>
<p><a href="#top">Top</a></p>
</div> <!-- end content -->
<!--#include file="footer.html" -->
|
