Core Indigo API

/* All integer and float functions return -1 on error. */
/* All string functions return zero pointer on error. */

/* Almost all string functions return the same pointer on success;
   you should not free() it, but rather strdup() it if you want to keep it. */

/* System */

const char * indigoVersion ();

// Allocate a new session. Each session has its own
// set of objects created and options set up.
qword indigoAllocSessionId   ();
// Switch to another session. The session, if was not allocated
// previously, is allocated automatically and initialized with
// empty set of objects and default options.
void  indigoSetSessionId     (qword id);
// Release session. The memory used by the released session
// is not freed, but the number will be reused on
// further allocations.
void  indigoReleaseSessionId (qword id);

// Get the last error message
const char * indigoGetLastError (void);

typedef void (*INDIGO_ERROR_HANDLER)(const char *message, void *context);
void indigoSetErrorHandler (INDIGO_ERROR_HANDLER handler, void *context);

// Free an object
int indigoFree (int handle);
// Clone an object
int indigoClone (int object);
// Count object currently allocated
int indigoCountReferences (void);

/* Options */

int indigoSetOption (const char *name, const char *value);
int indigoSetOptionInt (const char *name, int value);
int indigoSetOptionBool (const char *name, int value);
int indigoSetOptionFloat (const char *name, float value);
int indigoSetOptionColor (const char *name, float r, float g, float b);
int indigoSetOptionXY (const char *name, int x, int y);

/* Basic input-output */

// indigoRead*** return a new reader object.
// indigoLoad*** return a new reader object which already
// contains all the data and does not depend on the given
// string/buffer. All these functions are low-level and
// rarely needed to anyone.

int indigoReadFile   (const char *filename);
int indigoReadString (const char *str);
int indigoLoadString (const char *str);
int indigoReadBuffer (const char *buffer, int size);
int indigoLoadBuffer (const char *buffer, int size);

// indigoWrite*** return a new writer object.

int indigoWriteFile   (const char *filename);
int indigoWriteBuffer (void);

// Closes the file output stream but does not delete the object
int indigoClose (int output);

/* Iterators */

/* Iterators work in the following way:
 *
 * int item, iter = indigoIterate***(...)
 *
 * if (iter == -1)
 * {
 *    fprintf(stderr, "%s", indigoGetLastError());
 *    return;
 * }
 *
 * while (item = indigoNext(iter))
 * {
 *    if (item == -1)
 *    {
 *       fprintf(stderr, "%s", indigoGetLastError());
 *       break;
 *    }
 *
 *    printf("on item #%d\n", indigoIndex(item));
 *
 *    // do something with item
 *
 *    indigoFree(item);
 * }
 * indigoFree(iter);
 */

// Obtains the next element, returns zero if there is no next element
int indigoNext (int iter);
// Does not obtain the next element, just tells if there is one
int indigoHasNext (int iter);
// Returns the index of the element
int indigoIndex (int item);

// Removes the item from its container (usually a molecule)
int indigoRemove (int item);

/* Molecules, query molecules, SMARTS */

int indigoCreateMolecule (void);
int indigoCreateQueryMolecule (void);

int indigoLoadMolecule  (int source);
int indigoLoadMoleculeFromString (const char *string);
int indigoLoadMoleculeFromFile   (const char *filename);
int indigoLoadMoleculeFromBuffer (const char *buffer, int size);

int indigoLoadQueryMolecule (int source);
int indigoLoadQueryMoleculeFromString (const char *string);
int indigoLoadQueryMoleculeFromFile   (const char *filename);
int indigoLoadQueryMoleculeFromBuffer (const char *buffer, int size);

int indigoLoadSmarts (int source);
int indigoLoadSmartsFromString (const char *string);
int indigoLoadSmartsFromFile   (const char *filename);
int indigoLoadSmartsFromBuffer (const char *buffer, int size);

int indigoSaveMolfile (int molecule, int output);
int indigoSaveMolfileToFile (int molecule, const char *filename);
const char * indigoMolfile (int molecule);

int indigoSaveCml (int object, int output);
int indigoSaveCmlToFile (int object, const char *filename);
const char * indigoCml (int object);

// the output must be a file or a buffer, but not a string
// (because MDLCT data usually contains zeroes)
int indigoSaveMDLCT (int item, int output);

/* Reactions, query reactions */

int indigoLoadReaction  (int source);
int indigoLoadReactionFromString (const char *string);
int indigoLoadReactionFromFile   (const char *filename);
int indigoLoadReactionFromBuffer (const char *buffer, int size);

int indigoLoadQueryReaction (int source);
int indigoLoadQueryReactionFromString (const char *string);
int indigoLoadQueryReactionFromFile   (const char *filename);
int indigoLoadQueryReactionFromBuffer (const char *buffer, int size);

int indigoCreateReaction (void);
int indigoCreateQueryReaction (void);

int indigoAddReactant (int reaction, int molecule);
int indigoAddProduct  (int reaction, int molecule);

int indigoCountReactants (int reaction);
int indigoCountProducts  (int reaction);
// Counts both reactants and products.
int indigoCountMolecules (int reaction);
int indigoIterateReactants (int reaction);
int indigoIterateProducts  (int reaction);
// Returns an iterator for both reactants and products.
int indigoIterateMolecules (int reaction);

int indigoSaveRxnfile (int reaction, int output);
int indigoSaveRxnfileToFile (int reaction, const char *filename);
const char * indigoRxnfile (int reaction);

// Automatic reaction atom-to-atom mapping
// mode is one of the following:
//    "discard" : discards the existing mapping entirely and considers only
//                the existing reaction centers (the default)
//    "keep"    : keeps the existing mapping and maps unmapped atoms
//    "alter"   : alters the existing mapping, and maps the rest of the
//                reaction but may change the existing mapping
//    "clear"   : removes the mapping from the reaction.
int indigoAutomap (int reaction, const char *mode);

/* Accessing a molecule */

enum
{
   INDIGO_ABS = 1,
   INDIGO_OR = 2,
   INDIGO_AND = 3,
   INDIGO_EITHER = 4,
   INDIGO_UP = 5,
   INDIGO_DOWN = 6,
   INDIGO_CIS = 7,
   INDIGO_TRANS = 8,
   INDIGO_CHAIN = 9,
   INDIGO_RING = 10
};

// Returns an iterator for all atoms of the given
// molecule, including r-sites and pseudoatoms.
int indigoIterateAtoms (int molecule);
int indigoIteratePseudoatoms (int molecule);
int indigoIterateRSites (int molecule);
int indigoIterateStereocenters (int molecule);
int indigoIterateRGroups (int molecule);
int indigoIsPseudoatom (int atom);
int indigoIsRSite (int atom);

// returns INDIGO_{ABS,OR,AND,EITHER}
// or zero if the atom is not a stereoatom
int indigoStereocenterType (int atom);
int indigoSingleAllowedRGroup (int rsite);

// Applicable to an R-Group, but not to a molecule
int indigoIterateRGroupFragments (int rgroup);
int indigoCountAttachmentPoints (int rgroup);

const char * indigoSymbol (int atom);
int indigoDegree (int atom);

// Returns zero if the charge is ambiguous
// If the charge is nonambiguous, returns 1 and writes *charge
int indigoGetCharge (int atom, int *charge);
// Same as indigoGetCharge
int indigoGetExplicitValence (int atom, int *valence);
// Same as indigoGetCharge
int indigoGetRadicalElectrons (int atom, int *electrons);
// Returns a number of element from the periodic table.
// Returns zero on ambiguous atom.
// Can not be applied to pseudo-atoms and R-sites.
int indigoAtomicNumber (int atom);
// Returns zero on unspecified or ambiguous isotope
int indigoIsotope (int atom);

// Applicable to atoms and query atoms. Can fail (return zero) on query atoms
// where the number of hydrogens is not definitely known. Otherwise, returns one
// and writes *hydro.
int indigoCountHydrogens (int atom, int *hydro);

// Applicable to non-query molecules and atoms.
int indigoCountImplicitHydrogens (int item);

// On success, returns always the same pointer to a 3-element array;
// you should not free() it, but rather memcpy() it if you want to keep it.
float * indigoXYZ (int atom);

int indigoCountSuperatoms (int molecule);
int indigoCountDataSGroups (int molecule);
int indigoCountRepeatingUnits (int molecule);
int indigoCountMultipleGroups (int molecule);
int indigoCountGenericSGroups (int molecule);
int indigoIterateDataSGroups (int molecule);
int indigoIterateSuperatoms (int molecule);
int indigoIterateGenericSGroups (int molecule);
int indigoIterateRepeatingUnits (int molecule);
int indigoIterateMultipleGroups (int molecule);
int indigoGetSuperatom (int molecule, int index);
int indigoGetDataSGroup (int molecule, int index);
const char * indigoDescription (int data_sgroup);

int indigoAddDataSGroup (int molecule, int natoms, int *atoms,
        int nbonds, int *bonds, const char *description, const char *data);

int indigoSetDataSGroupXY (int sgroup, float x, float y, const char *options);

int indigoResetCharge (int atom);
int indigoResetExplicitValence (int atom);
int indigoResetRadical (int atom);
int indigoResetIsotope (int atom);

int indigoSetAttachmentPoint (int atom, int order);

int indigoRemoveConstraints   (int item, const char *type);
int indigoAddConstraint    (int item, const char *type, const char *value);
int indigoAddConstraintNot (int item, const char *type, const char *value);

int indigoResetStereo (int item);
int indigoInvertStereo (int item);

int indigoCountAtoms (int molecule);
int indigoCountBonds (int molecule);
int indigoCountPseudoatoms (int molecule);
int indigoCountRSites (int molecule);

int indigoIterateBonds (int molecule);
// Returns 1/2/3 if the bond is a single/double/triple bond
// Returns 4 if the bond is an aromatic bond
// Returns zero if the bond is ambiguous (query bond)
int indigoBondOrder  (int bond);

// Returns INDIGO_{UP/DOWN/EITHER/CIS/TRANS},
// or zero if the bond is not a stereobond
int indigoBondStereo (int bond);

// Returns INDIGO_{CHAIN/RING},
int indigoTopology (int bond);

// Returns an iterator whose elements can be treated as atoms.
// At the same time, they support indigoBond() call.
int indigoIterateNeighbors (int atom);

// Applicable exclusively to the "atom neighbors iterator".
// Returns a bond to the neighbor atom.
int indigoBond (int nei);

// Accessing atoms and bonds by index
int indigoGetAtom (int molecule, int idx);
int indigoGetBond (int molecule, int idx);

int indigoSource (int bond);
int indigoDestination (int bond);

int indigoClearCisTrans (int handle);
int indigoClearStereocenters (int handle);
int indigoCountStereocenters (int molecule);

int indigoResetSymmetricCisTrans (int handle);
int indigoMarkEitherCisTrans (int handle);

// Accepts a symbol from the periodic table (like "C" or "Br"),
// or a pseudoatom symbol, like "Pol". Returns the added atom.
int indigoAddAtom (int molecule, const char *symbol);

int indigoSetCharge (int atom, int charge);
int indigoSetIsotope (int atom, int isotope);

// Accepts two atoms (source and destination) and the order of the new bond
// (1/2/3/4 = single/double/triple/aromatic). Returns the added bond.
int indigoAddBond (int source, int destination, int order);

int indigoSetBondOrder (int bond, int order);

int indigoMerge (int where_to, int what);

/* Connected components of molecules */

int indigoCountComponents (int molecule);
int indigoComponentIndex (int atom);
int indigoIterateComponents (int molecule);

// Returns a 'molecule component' object, which can not be used as a
// [query] molecule, but supports the indigo{Count,Iterate}{Atoms,Bonds} calls,
// and also the indigoClone() call, which returns a [query] molecule.
int indigoComponent (int molecule, int index);

/* Smallest Set of Smallest Rings */

int indigoCountSSSR (int molecule);
int indigoIterateSSSR (int molecule);

int indigoIterateSubtrees (int molecule, int min_atoms, int max_atoms);
int indigoIterateRings (int molecule, int min_atoms, int max_atoms);
int indigoIterateEdgeSubmolecules (int molecule, int min_bonds, int max_bonds);

/* Calculation on molecules */

int   indigoCountHeavyAtoms (int molecule);
int   indigoGrossFormula    (int molecule);
float indigoMolecularWeight (int molecule);
float indigoMostAbundantMass (int molecule);
float indigoMonoisotopicMass (int molecule);

const char * indigoCanonicalSmiles (int molecule);
const char * indigoLayeredCode (int molecule);

int indigoHasCoord (int molecule);
int indigoHasZCoord (int molecule);
int indigoIsChiral (int molecule);

int indigoCreateSubmolecule (int molecule, int nvertices, int *vertices);
int indigoCreateEdgeSubmolecule (int molecule, int nvertices, int *vertices, int nedges, int *edges);

int indigoRemoveAtoms (int molecule, int nvertices, int *vertices);

// Determines and applies the best transformation to the given molecule
// so that the specified atoms move as close as possible to the desired
// positions. The size of desired_xyz is equal to 3 * natoms.
// The return value is the root-mean-square measure of the difference
// between the desired and obtained positions.
float indigoAlignAtoms (int molecule, int natoms, int *atom_ids, float *desired_xyz);

/* Things that work for both molecules and reactions */

int indigoAromatize (int item);
int indigoDearomatize (int item);

int indigoFoldHydrogens (int item);
int indigoUnfoldHydrogens (int item);

int indigoLayout (int object);

const char * indigoSmiles (int item);

// Returns 1 if there is an exact match
int indigoExactMatch (int item1, int item2);

const char * indigoName (int handle);
int indigoSetName (int handle, const char *name);

// You should not free() the obtained buffer, but rather memcpy() it if you want to keep it
int indigoSerialize (int handle, char **buf, int *size);

int indigoUnserialize (char *buf, int size);

// Applicable to molecules/reactions obtained from SDF or RDF files,
// and to their clones, and to their R-Group deconvolutions.
int indigoHasProperty (int handle, const char *prop);
const char * indigoGetProperty (int handle, const char *prop);

// Applicable to newly created or cloned molecules/reactions,
// and also to molecules/reactions obtained from SDF or RDF files.
// If the property with the given name does not exist, it is created automatically.
int indigoSetProperty (int item, const char *prop, const char *value);

// Does not raise an error if the given property does not exist
int indigoRemoveProperty (int item, const char *prop);

// Returns an iterator that one can pass to indigoName() to
// know the name of the property. The value of the property can be
// obtained via indigoGetProperty() call to the object
int indigoIterateProperties (int handle);

// Clears all properties of the molecule
int indigoClearProperties (int handle);

// Accepts a molecule or reaction (but not query molecule or query reaction).
// Returns a string describing the first encountered mistake with valence.
// Returns an empty string if the input molecule/reaction is fine.
const char * indigoCheckBadValence (int handle);

// Accepts a molecule or reaction (but not query molecule or query reaction).
// Returns a string describing the first encountered mistake with ambiguous H counter.
// Returns an empty string if the input molecule/reaction is fine.
const char * indigoCheckAmbiguousH (int handle);

/* Fingerprints */

// Returns a 'fingerprint' object, which can then be passed to:
//   indigoToString() -- to get hexadecimal representation
//   indigoToBuffer() -- to get raw byte data
//   indigoSimilarity() -- to calculate similarity with another fingerprint
// The following fingerprint types are available:
//   "sim"     -- "Similarity fingerprint", useful for calculating
//                 similarity measures (the default)
//   "sub"     -- "Substructure fingerprint", useful for substructure screening
//   "sub-res" -- "Resonance substructure fingerprint", useful for resonance
//                 substructure screening
//   "sub-tau" -- "Tautomer substructure fingerprint", useful for tautomer
//                 substructure screening
//   "full"    -- "Full fingerprint", which has all the mentioned
//                 fingerprint types included
int indigoFingerprint (int item, const char *type);

// Counts the nonzero (i.e. one) bits in a fingerprint
int indigoCountBits (int fingerprint);

// Counts the number of the coinincident in two fingerprints
int indigoCommonBits (int fingerprint1, int fingerprint2);

// Accepts two molecules, two reactions, or two fingerprints.
// Returns the similarity measure between them.
// Metrics: "tanimoto", "tversky", "tversky ", or "euclid-sub".
// Zero pointer or empty string defaults to "tanimoto".
// "tversky" without numbers defaults to alpha = beta = 0.5
float indigoSimilarity (int item1, int item2, const char *metrics);

/* Working with SDF/RDF/SMILES/CML files  */

int indigoIterateSDF    (int reader);
int indigoIterateRDF    (int reader);
int indigoIterateSmiles (int reader);
int indigoIterateCML    (int reader);

int indigoIterateSDFile     (const char *filename);
int indigoIterateRDFile     (const char *filename);
int indigoIterateSmilesFile (const char *filename);
int indigoIterateCMLFile    (const char *filename);

// Applicable to items returned by SDF/RDF iterators.
// Returns the content of SDF/RDF item.
const char * indigoRawData (int item);

// Applicable to items returned by SDF/RDF iterators.
// Returns the offset in the SDF/RDF file.
int indigoTell (int handle);

// Saves the molecule to an SDF output stream
int indigoSdfAppend (int output, int item);
// Saves the molecule to a multiline SMILES output stream
int indigoSmilesAppend (int output, int item);

// Similarly for RDF files, except that the header should be written first
int indigoRdfHeader (int output);
int indigoRdfAppend (int output, int item);

// Similarly for CML files, except that they have both header and footer
int indigoCmlHeader (int output);
int indigoCmlAppend (int output, int item);
int indigoCmlFooter (int output);

/* Arrays */

int indigoCreateArray ();
// Note: a clone of the object is added, not the object itself
int indigoArrayAdd (int arr, int object);
int indigoAt (int item, int index);
int indigoCount (int item);
int indigoClear (int arr);
int indigoIterateArray (int arr);

/* Substructure matching */

// Returns a new 'matcher' object
// 'mode' is reserved for future use; currently its value is ignored
int indigoSubstructureMatcher (int target, const char *mode);

// Ignore target atom in the substructure matcher
int indigoIgnoreAtom (int matcher, int atom_object);

// Clear list of ignored target atoms in the substructure matcher
int indigoUnignoreAllAtoms (int matcher);

// Returns a new 'match' object on success, zero on fail
//    matcher is an matcher object returned by indigoSubstructureMatcher
int indigoMatch (int matcher, int query);

// Counts the number of embeddings of the query structure into the target
int indigoCountMatches (int matcher, int query);

// Returns substructure matches iterator
int indigoIterateMatches (int matcher, int query);

// Accepts a 'match' object obtained from indigoMatchSubstructure.
// Returns a new molecule which has the query highlighted.
int indigoHighlightedTarget (int match);

// Accepts an atom from the query, not an atom index.
//   You can use indigoGetAtom() to obtain the atom by its index.
// Returns the corresponding target atom, not an atom index. If query 
// atom doesn't match particular atom in the target (R-group or explicit 
// hydrogen) then return value is zero.
//   You can use indigoIndex() to obtain the index of the returned atom.
int indigoMapAtom (int match, int query_atom);

// Accepts a bond from the query, not a bond index.
//   You can use indigoGetBond() to obtain the bond by its index.
// Returns the corresponding target bond, not a bond index. If query 
// bond doesn't match particular bond in the target (R-group or explicit 
// hydrogen) then return value is zero.
//   You can use indigoIndex() to obtain the index of the returned bond.
int indigoMapBond (int match, int query_bond);

/* Scaffold detection */

// Returns zero if no common substructure is found.
// Otherwise, it returns a new object, which can be
//   (i) treated as a structure: the maximum (by the number of rings) common
//       substructure of the given structures.
//  (ii) passed to indigoAllScaffolds()
int indigoExtractCommonScaffold (int structures, const char *options);

// Returns an array of all possible scaffolds.
// The input parameter is the value returned by indigoExtractCommonScaffold().
int indigoAllScaffolds (int extracted);

/* R-Group deconvolution */

// Returns a ``decomposition'' object that can be passed to
// indigoDecomposedMoleculeScaffold() and
// indigoIterateDecomposedMolecules()
int indigoDecomposeMolecules (int scaffold, int structures);

// Returns a scaffold molecule with r-sites marking the place
// for substituents to add to form the structures given above.
int indigoDecomposedMoleculeScaffold (int decomp);

// Returns an iterator which corresponds to the given collection of structures.
// indigoDecomposedMoleculeHighlighted() and
// indigoDecomposedMoleculeWithRGroups() are applicable to the
// values returned by the iterator.
int indigoIterateDecomposedMolecules (int decomp);

// Returns a molecule with highlighted scaffold
int indigoDecomposedMoleculeHighlighted (int decomp);

// Returns a query molecule with r-sites and "R1=...", "R2=..."
// substituents defined. The 'scaffold' part of the molecule
// is identical to the indigoDecomposedMoleculeScaffold()
int indigoDecomposedMoleculeWithRGroups (int decomp);

/* Other */

const char * indigoToString (int handle);
int indigoToBuffer (int handle, char **buf, int *size);

/* Reaction products enumeration */

// Accepts a query reaction with markd R-sites, and array of arrays
// of substituents corresponding to the R-Sites. Returns an array of
// reactions with R-Sites replaced by the actual substituents.
int indigoReactionProductEnumerate (int reaction, int monomers);

Indigo Renderer Plugin

// Returns an 'output' object for the given HDC
int indigoRenderWriteHDC (void* hdc, int printingHdc);

// output is either a file output obtained via indigoWriteFile(), or
//        a buffer obtained via indigoWriteBuffer(), or
//        an HDC obtained via indigoRenderWriteHDC
int indigoRender (int object, int output);

// objects  is an array of molecules created with indigoCreateArray)
// refAtoms is an array of integers, whose size must be equal to the number
//          of molecules if the array
// nColumns is the number of columns in the grid
// output -- see the comment for indigoRender
int indigoRenderGrid (int objects, int* refAtoms, int nColumns, int output);

// Works like indigoRender(), but renders directly to file
int indigoRenderToFile (int object, const char *filename);

// Works like indigoRenderGrid(), but renders directly to file
int indigoRenderGridToFile (int objects, int* refAtoms, int nColumns, const char *filename);

// Resets all the rendering settings
int indigoRenderReset (int render);