<img src="./INCHI-1-DOC/assets/inchi-wheel.png" width="300" height="300" />

InChI - The IUPAC International Chemical Identifier

InChI is a structure-based chemical identifier, developed by IUPAC and the InChI Trust. It is a standard identifier for chemical databases that facilitates effective information management across chemistry.

InChI and InChIKey are open standards. They use unique machine readable strings to represent, store and search chemical structures. All the software and algorithms related to them are open source.

Contents of this document

Click on the icon in the upper right of this README to view the table of content.

What is InChI

InChI is a structure-based textual identifier, strictly unique, non-proprietary, open source, and freely accessible.

InChI identifiers describe chemical substances in terms of layers of information – the atoms and their bond connectivity, tautomeric information, isotope information, stereochemistry, and electronic charge.

With its fixed length of 27 characters the InChIKey — the hashed version of the InChI — allows for a compact representation and usage in databases or search engines.

InChI is used by most of the large chemical databases and software applications handling many millions of chemical structures.

InChI enables the linking and interlinking of chemistry and chemical structures on the web and computer platforms. By enhancing the discoverability of chemical structures, InChI advances the FAIR Guiding Principles for scientific data management and stewardship. FAIR was published in 2016 to provide guidelines to improve the Findability, Accessibility, Interoperability, and Reuse of digital assets. InChI provides ‘Findability’ for chemical structures and extends Interoperability between platforms, both of which foster Accessibility and Reuse.

InChI Trust

The InChI Trust is a charity that supports the development and promotion of the InChI standard. It works in partnership with IUPAC to update and release new extensions to and applications of InChI. The Trust is a membership organisation, governed by its Board of Trustees which includes representation from IUPAC.

The scientific design of the various tools and capabilities that comprise the InChI code are defined by the InChI Working Groups which are made up of volunteers from the InChI community with IUPAC oversight. These voluntary groups are each focused on specific areas of chemistry or tools within the InChI code. See Working Groups for details on each group and their membership.

The development of the code is coordinated by the Technical Director of the InChI Trust, together with the working groups, IUPAC and our development partners. Our development partners currently include RWTH Aachen (as part of NFDI4Chem, acknowledging funding from Volkswagen Stiftung and the Data Literacy Alliance – DALIA), and the Beilstein Institut.

How to contribute

Should you have any questions, comments, or suggestions, please feel free to post them here: GitHub discussion page.

If you encounter a bug, we kindly request you to create an issue.

You are welcome to contribute to this project. To do so, you may submit a pull request:

Source code documentation

We've started documenting the source code with Doxygen.

Follow the Doxygen syntax when writing comments. For example

/**
* @brief Read a field from a MOL file.
*
* @param data Pointer to the destination buffer.
* @param field_len Length of the field to read.
* @param data_type Type of the data to read.
* @param line_ptr Pointer to a variable that will receive the address of the next line.
* @return for MOL_FMT_STRING_DATA: number of bytes excluding trailing zero
*         for all others:  1=success; 0 = empty; -1= error
*/
int MolfileReadField(void *data,
     int field_len,
     int data_type,
     char **line_ptr);

Please write your comments in the header files where possible. The Doxygen documentation syntax is quite powerful: you can include formulas, tables, and diagrams. For details see https://www.doxygen.nl/manual.

The documentation is built on every push to the default branch of this repository and hosted at https://iupac-inchi.github.io/InChI/. That is, your comments will automatically be rendered to HTML and served as online documentation.

Contents of this repository

INCHI-1-DOC

The INCHI-1-DOC subfolder contains documentation related to the InChI Software.

INCHI-1-SRC

The INCHI-1-SRC subfolder contains the InChI source code. It also contains examples of InChI API usage, for C (inchi_main, mol2inchi, test_ixa), as well as the InChI API library source code and related projects/makefiles.

INCHI-1-TEST

The INCHI-1-TEST subfolder contains the test scripts and resources.

Using compiled binaries/libraries

You can download compiled artifacts from https://github.com/IUPAC-InChI/InChI/releases/latest. The archive release_artifacts.zip contains 64-bit artifacts for Windows, Linux, and macOS. The artifact archive of each of those three platforms includes the following:

• InChI executable inchi-1
• InChI library libinchi with corresponding inchi_main program

We're compiling these artifacts with GitHub Actions. If you're interested in details about the platforms and compilers, have a look at the following configuration, as well as the files in the cmake_configurations.zip archive, which is included for each platform.

Building from source

Users can build any InChI subproject (e.g. InChI CLI/inchi-1, libinchi, etc.) from source using:

• CMake build system (Microsoft Windows, Apple macOS, Linux, FreeBSD, OpenBSD, Solaris, AIX)
• Microsoft Visual Studio projects (Microsoft Windows)
• Make build system (Microsoft Windows, Unix, Apple macOS)

CMake build system

To build InChI sub-projects from source using CMake build system, make sure that CMake is installed on your system. Users can choose between running interactive CMake build tool script and running CMake in Command Line Interface (CLI).

Interactive CMake build tool

The easiest way to build any (or all) InChI sub-project(s) using CMake is to run the CMake build tool (cmake_build_tool.bat for Microsoft Windows platforms or cmake_build_tool.sh for Linux/Apple macOS platforms) which is located in the INCHI-1-SRC directory.

• Microsoft Windows

  • Double click on batch file cmake_build_tool.bat.
  • Run cmake_build_tool.bat command in Command Prompt.
  • Run ./cmake_build_tool.bat command in PowerShell.

• Linux/Apple macOS

  • Run ./inchi_build_tool.sh within INCHI-1-SRC directory.

CMake build tool users are only required to enter a number that corresponds to one or all InChI sub-projects which should be built from source using CMake.

<p><figure> <img src="INCHI-1-DOC/assets/cmake_tool1.jpg" alt="cmake_start_menu" /> <figcaption style="font-size:smaller;"><em>Figure cmbt01</em>. <em>CMake build tool</em>: start menu</figcaption> </figure></p> <p><figure> <img src="INCHI-1-DOC/assets/cmake_tool2.jpg" alt="cmake_build_success" /> <figcaption style="font-size:smaller;"><em>Figure cmbt02</em>. <em>CMake build tool</em>: build success</figcaption> </figure></p>

Please note that the main build directory CMake_build