  ----------
  JNI-InChI - Guide
  ----------
  Sam Adams
  ----------

Introduction

  JNI-InChI is a library indended for use by developers of other projects. It does not enable users to generate InChIs from molecule file formats such as .mol, .cml, .mol2, or SMILES strings. If you want to do any of these, you should take a look at the {{{http://sourceforge.net/projects/cdk}Chemistry Development Kit (CDK)}}, or {{{http://sourceforge.net/projects/cml}JUMBO}} which includes InChI generation powered by the JNI-InChI. If, however, you are a software developer and you want want to generate the InChI for a molecule that you already hold in memory, JNI-InChI is what you need.

InChI Generation

  The main aim of the JNI-InChI is to enable the generation of InChIs from within Java. The InChI libaray's functionality is accessed through the net.sf.jniinchi.JniInchiWrapper class. To generate an InChI, first a representation of the molecule must be constructed that the InChI library can recognise. This is achieved by creating JniInchiAtoms, JniInchiBonds and JniInchiStereo0Ds, and adding them to a JniInchiInput object. This is illustrated in the examples below:

%{snippet|id=structure2inchi-dichloroethene|file=src/test/java/net/sf/jniinchi/TestExamples.java}
%{snippet|id=structure2inchi-alanine|file=src/test/java/net/sf/jniinchi/TestExamples.java}

  Further examples can be found in the  {{{http://jni-inchi.svn.sourceforge.net/viewvc/jni-inchi/trunk/src/test/java/net/sf/jniinchi/TestJniInchiWrapper.java?view=markup}TestJniInchiWrapper}} class,  the {{{http://cdk.svn.sourceforge.net/viewvc/cdk/cdk/trunk/src/org/openscience/cdk/inchi/InChIGenerator.java?view=markup}CDK}}, and {{{http://cml.svn.sourceforge.net/viewvc/cml/inchi/src/main/java/org/xmlcml/cml/inchi/InChIGenerator.java?view=markup}JUMBO}}.


* Output

  The JniInchiOutput object returned contains the results of the InChI generation:

*----------------------------+--------------------------------------------+
 INCHI_RET getReturnStatus() | Returns the status code (see below)
*----------------------------+--------------------------------------------+
 String getInchi()           | Returns the generated InChI
*----------------------------+--------------------------------------------+
 String getAuxInfo()         | Returns the generated AuxInfo
*----------------------------+--------------------------------------------+
 String getMessage()         | Returns warning or error message
*----------------------------+--------------------------------------------+
 String getLog()             | Returns log messages from InChI generation
*----------------------------+--------------------------------------------+

** Return status codes

  The InChI generation process returns a status code which describes how successful the process was:

*--------+-------------------------------------------------------------------------------+
 SKIP    | Not used
*--------+-------------------------------------------------------------------------------+
 EOF     | No structural data has been provided
*--------+-------------------------------------------------------------------------------+
 OKAY    | Success, no errors or warnings
*--------+-------------------------------------------------------------------------------+
 WARNING | Success, warning(s) issued
*--------+-------------------------------------------------------------------------------+
 ERROR   | Error: no InChI has been created
*--------+-------------------------------------------------------------------------------+
 FATAL   | Severe error: no InChI has been created (typically, memory allocation failure)
*--------+-------------------------------------------------------------------------------+
 UNKNOWN | Unknown program error
*--------+-------------------------------------------------------------------------------+
 BUSY    | Previous call to InChI has not returned yet
*--------+-------------------------------------------------------------------------------+

  <(Documentation from inchi_api.h)>

* Options

  JNI-InChI supports the full range of options that InChI generation takes:

*--------------+---------------------+
 SUCF          | Use Chiral Flag
*--------------+---------------------+
 ChiralFlagON  | Set Chiral Flag
*--------------+---------------------+
 ChiralFlagOFF | Set Not-Chiral Flag
*--------------+---------------------+

*-------------------*---------------*------------------------------------------*
 <<Options>>        | <<Equivalent to>> | <<Chiral Flag Information stored in AuxInfo>>
*-------------------+---------------+------------------------------------------+
 SUCF ChiralFlagON  | SABS          | Chiral Flag
*-------------------+---------------+------------------------------------------+
 SUCF ChiralFlagOFF | SREL          | Not-Chiral Flag
*-------------------+---------------+------------------------------------------+
 SUCF               | SREL          | none
*-------------------+---------------+------------------------------------------+
 ChiralFlagON       | none          | Chiral Flag
*-------------------+---------------+------------------------------------------+
 ChiralFlagOFF      | none          | Not-Chiral Flag
*-------------------+---------------+------------------------------------------+

  Other options:

*---------------------+--------------------------------------------------------+
 SNon                 | Exclude stereo (Default: Include Absolute stereo)
*---------------------+--------------------------------------------------------+
 SRel                 | Relative stereo
*---------------------+--------------------------------------------------------+
 SRac                 | Racemic stereo
*---------------------+--------------------------------------------------------+
 SUU                  | Include omitted unknown/undefined stereo
*---------------------+--------------------------------------------------------+
 NEWPS                | Narrow end of wedge points to stereocenter (default: both)
*---------------------+--------------------------------------------------------+
 RecMet               | Include reconnected bond to metal results
*---------------------+--------------------------------------------------------+
 FixedH               | Mobile H Perception Off (Default: On)
*---------------------+--------------------------------------------------------+
 AuxNone              | Omit auxiliary information (default: Include)
*---------------------+--------------------------------------------------------+
 NoADP                | Disable Aggressive Deprotonation (for testing only)
*---------------------+--------------------------------------------------------+
 Compress             | Compressed output
*---------------------+--------------------------------------------------------+
 DoNotAddH            | Overrides inchi_Atom::num_iso_H[0] == -1
*---------------------+--------------------------------------------------------+
 Wnumber              | Set time-out per structure in seconds; W0 means unlimited In InChI library the default value is unlimited
*---------------------+--------------------------------------------------------+
 OutputSDF            | Output SDfile instead of InChI
*---------------------+--------------------------------------------------------+
 WarnOnEmptyStructure | Warn and produce empty InChI for empty structure
*---------------------+--------------------------------------------------------+

  <(Documentation from inchi_api.h)>


InChI-to-Structure

  JNI-InChI also supports InChI-to-Structure conversion:

%{snippet|id=inchi2structure|file=src/test/java/net/sf/jniinchi/TestExamples.java}


InChI-to-InChI

  The InChI libary also provides an option to convert InChI-to-InChI. This may be of use if you wish to remove layers
  from an InChI:

%{snippet|id=inchi2inchi-hydrogen|file=src/test/java/net/sf/jniinchi/TestExamples.java}

  Or if you wish to convert between compressed and  uncompressed InChIs:

%{snippet|id=inchi2inchi-compress|file=src/test/java/net/sf/jniinchi/TestExamples.java}


InChI-to-InChIKey

%{snippet|id=inchi2inchikey|file=src/test/java/net/sf/jniinchi/TestExamples.java}


Check InChI

%{snippet|id=checkinchi|file=src/test/java/net/sf/jniinchi/TestExamples.java}


Check InChIKey

%{snippet|id=checkinchikey|file=src/test/java/net/sf/jniinchi/TestExamples.java}


AuxInfo-to-InChI Input

%{snippet|id=auxinfo2input|file=src/test/java/net/sf/jniinchi/TestExamples.java}


Native Code

  JNI-InChI does not contain a Java version of the InChI algorithm, it wraps up the InChI library distributed by IUPAC, making its functionality available to Java programmers. The InChI library is only available in C, and is not sufficiently well documented for it to be easy to produce an implementation in another language, without first reverse engineering the existing code.

  The problem with using native code is that the cross-platform benefits of java are lost. In an attempt to overcome this the JNI-InChI contains a mechanism package the native files with the java code, to deploy the appropriate ones on a system, as required. This is all handled by the net.sf.jniinchi.JniInchiNativeCodeLoader class.
