Toolkit Overview

Table of Contents

1. Introduction

The Daylight Toolkits...

... are a set of shared object libraries and header files.
... give programmers the power to handle complex chemistry with ease.
... use a robust, consistent and well-defined API.
... are written to allow cross-platform portability and language-independence.

2. Datatypes

Datatype Concept & Example
dt_Boolean Concept: Logical
Example: The dt_Boolean datatype represents one bit of information. Valid values are 1 (for TRUE) and 0 (for FALSE).
dt_Integer Concept: Integral
Example: The dt_Integer datatype represents whole numbers within the range of 2^31 to -2^31.
dt_Real Concept: Floating-point
Example: The dt_Real datatype represents floating-point values (2-2^23)^127 to -(2-2^23)^127 and is not able to represent zero.
dt_String Concept: Character Array
Example: The dt_String datatype represents an array of characters. For platform independence, the length of the character array is specified with an associated dt_Integer datatype, not with a character (i.e., NULL) within the array. Functions that return a string typically accept the address of the dt_Integer as the first parameter, which is used to pass the length of the string back to the caller.

3. Objects

Datatype Concept & Example
dt_Handle Concept: Object Handling
Example: A handle is an integer representing an object. The integer is an index into the internal toolkit table. A handle is used to represent objects, including: Atom, Bond, Cycle, Molecule, Reaction, Pattern, Pathset, Path, Transform, Stream, Sequence.
NULL_OB Concept: Error Handling
Example: The NULL object is a valid handle that refers to nothing. It is returned when errors occur. Errors can be detected by checking for NULL_OB.

4. Relationships

Object Concept & Example
Concept: A child is an integral part of a parent.
Example: Atoms, bonds, and cycles (children) are parts of a molecule (parent). You may allocate a molecule and add an oxygen atom to it to create water ("O"). The water molecule has an atom count of 1, a bond count of 0, and a cycle count of 0. The atom refers to the molecule as its parent.
Example Code and Resulting Output
Concept: A parent is directly accessible from the child.
Example: The following are the parent-child relationships:

Molecule-Atom
Molecule-Bond
Molecule-Cycle
Reaction-Molecule

Example Code and Resulting Output
Concept: A parent owns its child.
Example: Deallocation of the molecule causes deallocation of the atom, which makes the atom invalid.
Example Code and Resulting Output
Concept: A child affects its parent.
Example: Deallocation of the atom changes the molecules' atom count to 0.
Example Code and Resulting Output

5. SMILES - Molecules

Object Concept & Example
Concept: A molecule is input and output using the SMILES Toolkit.
Example: You can read SMILES in and create an ionized water molecule ("[OH-].[H+]"). The molecule can be written in canonical SMILES or arbitrary SMILES form.
Example Code and Resulting Output
Concept: A stream is a container object.
Example: A molecule is streamed to access its atoms, bonds, or cycles.
Example Code and Resulting Output
Concept: A stream is like a linked list.
Example: The atom stream contains a next atom. Initially, asking for the next item gives the first atom ("[OH-]"). The atom number is 8, the symbol is "O", and the charge is -1. The next item gives the second atom ("[H+]"). The atom number is 1, the symbol is "H", and the charge is 1. When there are no more atoms, the next item is the NULL OBject. The atom stream can be reset and the next item gives the first atom again. Each atom refers to the molecule as its parent.
Example Code and Resulting Output
Concept: A stream is invalid when its base object changes.
Example: The atom stream is invalid when an atom is added to the molecule, or an atom or the molecule is deallocated.
Example Code and Resulting Output
Concept: A stream is derived from a base object.
Example: The atom stream refers to its molecule as its base. The atoms are not deallocated when the atom stream is deallocated. The stream is deallocated when the molecule is deallocated.
Example Code and Resulting Output

6. SMILES - Reactions

Object Concept & Example
Concept: A reaction is input and output using the SMILES Toolkit with reaction capabilities.
Example: You can read SMILES in and create a water ionization reaction ("O>>[OH-].[H+]"). The reaction can be written in canonical SMILES or arbitrary SMILES form.
Example Code and Resulting Output
Concept: A stream is a container object.
Example: A reaction is streamed to access its molecules, atoms, bonds, or cycles.
Example Code and Resulting Output
Concept: A stream is like a linked list.
Example: The molecule stream contains a next molecule. Initially, asking for the next item gives the first molecule ("O"). The molecule role is "reactant". The next item gives the second molecule ("[OH-].[H+]"). The molecule role is "product". When there are no more molecules, the next item is the NULL OBject. The molecule stream can be reset and the next item gives the first molecule again. Each molecule refers to the reaction as its parent.
Example Code and Resulting Output
Concept: A stream may become invalid when its base object changes.
Example: The molecule stream is invalid when a component is added to the reaction, or a molecule or the reaction is deallocated.
Example Code and Resulting Output
Concept: A stream is derived from a base object.
Example: The molecule stream refers to its reaction as its base. The molecules are not deallocated when the molecule stream is deallocated. The stream is deallocated when the reaction is deallocated.
Example Code and Resulting Output

7. SMARTS - Patterns

Object Concept & Example
Concept: A pattern object is input using the SMARTS Toolkit.
Example: You can read SMARTS in and create an aromatic oxygen pattern ("Oa"). The pattern can be SMARTS optimized for matches on typical molecules.
Example Code and Resulting Output
Concept: A pattern object and either a molecule or reaction are used to find matching paths.
Example: The aromatic oxygen pattern and hydroquinone ("Oc1ccc(O)cc1") have matching paths.
Example Code and Resulting Output
Concept: A pathset object is a set of paths.
Example: There are two oxygen-aromatic paths in hydroquinone.
Example Code and Resulting Output
Concept: A path object is a set of atoms and bonds.
Example: The oxygen-aromatic path contains 2 atoms and 1 bond.
Example Code and Resulting Output
Concept: A pathset and its paths are derived from a base object.
Example: The pathset and paths refer to their molecule as its base. The pathset and oxygen-aromatic paths are deallocated when the hydroquinone molecule is deallocated. Paths are deallocated when the pathset is deallocated.
Example Code and Resulting Output
Concept: A pathset and path may become invalid when its base object changes.
Example: The pathset and the oxygen-aromatic paths are invalid when an atom is added to the molecule, or an atom or the molecule is deallocated.
Example Code and Resulting Output
Concept: A stream is a container object
Example: The pathset is streamed to access its oxygen-aromatic paths.
Example Code and Resulting Output
Concept: A stream is like a linked list.
Example: The path stream contains a next path. Initially, asking for the next item gives the first path ("Oa"). The unique identifiers (uid) of the atoms and bond reflect their position in the input SMILES string. When there are no more paths, the next item is the NULL OBject. The path stream can be reset and the next item gives the first path again. Each path refers to the molecule as its base.
Example Code and Resulting Output
Concept: A stream may become invalid when its base object changes.
Example: The path stream is invalid when an atom is added to the molecule, or an atom or the molecule is deallocated.
Example Code and Resulting Output
Concept: A stream is derived from a base object.
Example: The path stream refers to its pathset as its base. The paths are not deallocated when the path stream is deallocated. The stream is deallocated when the pathset is deallocated.
Example Code and Resulting Output

8. SMIRKS - Transforms

Object Concept & Example
Concept: A transform object is input using the SMILES Toolkit with reaction capabilities.
Example: You can read SMIRKS in and create a water ionization transform ("[O:1][H:2]>>[O-:1].[H+:2]").
Example Code and Resulting Output
Concept: A sequence is a container object.
Example: Any object can be appended or inserted to a sequence.
Example Code and Resulting Output
Concept: A sequence is like a linked list
Example: Like a stream, the molecule sequence contains a next molecule. Initially, asking for the next item gives the first molecule. The next item gives the second molecule. When there are no more molecules, the next item is the NULL OBject. The molecule sequence can be reset and the next item gives the first molecule again.
Example Code and Resulting Output
Concept: A transform object and a sequence of molecules are used to transform the molecules into a sequence of reactions.
Example: The water ionization transform and a sequence containing water and hydroquinone molecules are transformed into ionized water and ionized hydroquinone reactions ("[OH-:1].[H+:2]" and "[O-:1]c1ccc(cc1)O.[H+:2]"). The atoms involved in the transformation are "mapped" by class number.
Example Code and Resulting Output
Concept: A sequence does not become invalid when other objects change.
Example: The molecule sequence is not invalid when adding an atom to a molecule, or when a molecule is deallocated.
Example Code and Resulting Output
Concept: A sequence is completely separate and not derived from another object.
Example: The molecule sequence does not refer to another object. The molecules are not deallocated when the sequence is deallocated. The sequence is not deallocated when the molecules are deallocated. The proper way to deallocate a sequence and its contents is to reset the container, delete and deallocate each item, then deallocate the container.
Example Code and Resulting Output


Programming Exercises
Toolkit Programmers Guide