The API (Application Programming Interface) comprised by the toolkit possesses object oriented features but is not a complete object-oriented language such as Smalltalk or Java. The concept of an object is essential to the toolkit interface, however, and atoms, bonds, molecules, datatrees, reactions, and many other things are toolkit objects. They may be created, manipulated, and destroyed easily using the toolkit interface. The Daylight Toolkit manages the objects for you - you need not be concerned with details of how the Toolkit represents the molecule or depiction.
An object is identified by its "handle" which is a simple and lightweight integer datatype. The handles themselves contain no information - they are not pointers to complex structures. Handles are opaque in that they cannot be dereferenced -- no access to the internal data structures is allowed. Handles are unique. Only one handle refers to one object. Handles are valid when they refer to an existing object, or invalid if they have been deallocated by the program, revoked by the toolkit or never assigned.
Because objects are managed by the Daylight Toolkit, the interface to various programming languages is straightforward: the Daylight Toolkit works equally well with C, FORTRAN, Pascal, or LISP.
Objects are self-describing: Each object "knows" what it is. Many toolkit functions are polymorphic: they will take a variety of different object types The function "asks" the object what type it is and performs the appropriate action.
| Object | Description |
|---|---|
| atom | atom in a molecule |
| bond | bond in a molecule |
| column | column of data in a pool |
| conformation | 3-D conformation |
| cycle | ring in a molecule |
| database | database object |
| datafield | datum in a dataitem |
| dataitem | dataitem in a TDT |
| datatree | a THOR datatree (TDT) |
| datatype | datatype definition |
| depiction | 2-D coordinates of a molecule |
| fieldtype | one datafield's type |
| fingerprint | fingerprint object |
| hitlist | search/sort results in a Merlin database |
| integer | intger object |
| merserver | Merlin server connection |
| molecule | molecule object |
| monomer | monomer object |
| monomerset | set of monomers |
| monomertable | table of monomer definitions |
| monopattern | search pattern for a monomer |
| multimer | multimer object (CHUCKLES) |
| path | results of a structural search |
| pathset | set of path objects |
| pattern | structural pattern (SMARTS) |
| pool | Merlin database ("pool") |
| program | external program object |
| reaction | reaction object |
| real | real number object |
| sequence | ordered list of objects |
| server | THOR server connection |
| stream | enumerated constituents of another object |
| string | string object |
| substruct | substructure object |
| transform | generic reaction |
| varimer | varimer object (CHORTLES) |
| varipattern | varimer pattern (CHARTS) |
| vbind | object providing faster evaluation of a match |
The toolkit function dt_stream is able to
derive streams of constituent objects from parent objects. Streams
of atoms or bonds can be derived from a molecule, streams of
datatrees can be derived from a database, streams of molecules
can be derived from a reaction. Streams are easily obtained and
used, but may be revoked if the parent object is modified. Deallocating
a stream does not affect its member objects.
Sequences behave like streams but are not deallocated if a member object is modified. The are simply ordered lists of objects. Objects may be added or deleted from a sequence. Deallocating a sequence does not affect its member objects.
Named properties were introduced with version 4.51, superceding the previous dt_adjunct/dt_setadjunct mechanism. Any number of properties of any types may be associated with any toolkit object.
-
Parent/child: A child is an integral part of its parent; a parent is
made up of one or more children. Creating/destroying/modifying a child
affects its parent.
Children of a parent are normally accessed with dt_stream().
The parent of a child is accessed with dt_parent(). -
Base/derivative: A derivative is a separate object, formed from its
base. The characteristics of the base object determine the
characteristics of the derivative when created, however operations on
the derivative never affect the base. The derivative can be
created/destroyed/modified without affecting the base.
Modification of the base object causes any derivatives to be deallocated.
One can't get access to all of the derivatives of a given base object (eg. all depictions of a molecule).
The base of any given derivative object is accessed with dt_base().
A parent/child example (molecule/atoms):
void do_stuff(dt_Handle ob)
{
dt_Handle atoms, atom, myparent;
atoms = dt_stream(ob, TYP_ATOM);
while (NULL_OB != (atom = dt_next(atoms)
{
/*** perform operations on each atom ***/
...
myparent = dt_parent(atom);
}
dt_dealloc(atoms);
return;
}
A base/derivative example (molecule/depiction):
void do_other_stuff(dt_Handle ob)
{
dt_Handle depiction, mybase;
depiction = dt_alloc_depiction(ob);
...
dt_calcxy(depiction);
dt_depict(depiction);
...
mybase = dt_base(depiction);
return;
}
Regardless of the programming language used to access the toolkit, the toolkit will use dynamic memory allocation in creating objects. The implication of this is that the process size of an executable program will grow as objects are allocated and care must be taken that it doesn't grow uncontrollably. If a "memory leak" is present in a loop, the process size will increase until the program crashes or the computer is paralyzed. So the issue becomes how and when to reliably deallocate objects to avoid memory leaks.
In general, the essential task is to deallocate objects which
are allocated inside loops. For example, if a new molecule is
allocated for each iteration of a loop, either by
dt_alloc_mol or dt_smilin,
it must be deallocated inside the loop. When a molecule is
deallocated, all atoms and bonds beloning to the parent molecule,
and any streams over the molecule, are deallocated. Likewise,
if each iteration of a loop allocates a TDT object, it must
be deallocated. Objects which are allocated only once in a
program need not be deallocated, but it is considered good
form to do so.
SMILES is a language for representing a molecule as an ASCII string. The toolkit can parse a SMILES into a molecule and express a molecule as a SMILES. But it should be noted that the molecule object is not itself a SMILES. This correspondence between a toolkit object and a linguistic representation is common in the toolkit.
| Object | Language |
|---|---|
| datatree | TDT |
| fingerprint | FP datum |
| molecule | SMILES |
| monomer | Monomer SMILES |
| multimer | CHUCKLES |
| pattern | SMARTS |
| reaction | Reaction SMILES |
| transform | SMIRKS |
| varimer | CHORTLES |
| varipattern | CHARTS |
Objects persist until they are deallocated by the program, revoked by the toolkit, or until the program terminates. In contrast, in C, a returned string is a (char *) pointer to a location in memory containing the string, managed by the toolkit, and not guaranteed to persist after the next toolkit function call.
Daylight Chemical Information Systems Inc.
