Isomer finder

This tool searches for isomers of a molecule. It is currently limited to acyclic compounds with single bonds only. There is both a command line and a web interface available.

Click here to see it in action.

Installation

To use this application as a command line tool follow the instructions below:

Get the code, e.g. using git.
Open a terminal and change into the root directory of this package.
Run the install.sh script with root privileges. Missing dependencies will automatically be detected, downloaded and installed.
Finally type isomers --help to verify that the installation completed successfully.

git clone git@github.com:just95/isomers.git
cd isomers
sudo ./install.sh

To uninstall the application simply run:

sudo /usr/lib/isomers/uninstall.sh

Usage

isomers <command> [arguments]

find command

isomers find [-H, --add-hydrogen] <sum-formula> ...

The find command searches for isomers with the specified sum formula. The output of this command can be piped into one of the other commands.

The --add-hydrogen flag can increase the performance of the search algorithm by initially removing the hydrogen atoms from the sum formula and later adding them back to the final molecule.

Example: To count the number of Decane isomers type the following:

isomers find -H C10H22 | wc -l

Which should print 75.

hnmr command

isomers hnmr [--filter=<number,...>] <structure-formula> ...

The hnmr command predicts the splitting patterns of a H-NMR spectrum.

The command accepts structure formulas like those generated by the find command. The output has the format

<structure-formula> // <number>,...

If a --filter is supplied only matching molecules are printed. * can be used as a placeholder for a single number, and ... as a placeholder for zero or more numbers.

Example: To find the molecule with the sum formula C₄H₉Cl whose H-NMR spectrum has exactly 4 peaks, one of which is a doublet, type:

isomers find -H C4H9Cl | isomers hnmr --filter 2,*,*,*

Which should print the structure formula of 2-Chlorobutane.

render command

isomers render [--no-sticky] [--sticky=<element,...>]
               [-r, --renderer=<name>]
               [--bg=<color>] [--fg=<color>] [--dpi=<number>]
               [--no-color] [--no-subscript]
               [-f, --format=<type>]
               [-o, --output=<path>]
               [--md5=<mode>] <structure-formula> ...

The render command draws the structure formula of a molecule. It can either print Unicode characters or create image files.

First the molecule is converted to a DOT graph. The actual rendering is then performed by Graph::Easy and graphviz.

If an element is --sticky no individual nodes will be generated for atoms of this type. By default this is the case for hydrogen atoms. To disable this behavior set the --no-sticky flag.

The command prints to the console by default. To create image files instead specify an --output directory and png or jpg as the --format. The file name is the MD5 hash of the image and therefore unique. The hash can alternatively be generated from the structure formula by setting the --md5 option to input. It's also possible to disable the MD5 file names: --md5=off. In this case numerical names are chosen.

You can customize the foreground (--fg) and background (--bg) color of the images. It's valid to specify the name of a color (e.g. red) or use hexadecimal notation (i.e. #RRGGBB). If you don't want element symbols to be colored you can specify --no-color.

To increase the resolution of the images you can set the --dpi (dots per inch) value.

Example: To render all the Decane isomers type the following:

isomers find -H C10H22 | isomers render -o decane/ -f png --bg red

Which creates 75 *.png files with red background in the decane directory.

--input option

The commands above read from stdin by default if no additional command line arguments are passed. Alternatively an --input file can be specified.

The example below demonstrates how to save the result of the find command in a temporary file for later processing. In this case the isomers of Decane are counted and rendered but calculated only once.

isomers find -H C10H22 > decane-isomers.txt
wc -l decane-isomers.txt 
isomers render -i decane-isomers.txt

Web application

Alternatively a web application can be created, which is more user friendly but less powerful than the command line tool. Just follow these steps:

Get the code, e.g. using git.
Open a terminal and change into the root directory of this package.
Run the build.sh script. The application will be compiled to JavaScript and all assets will be placed into a newly created directory build/web.

git clone git@github.com:just95/isomers.git
cd isomers
./build.sh

If you are using FireFox you can open the build/web/index.html file right away. Google Chrome, however, restricts loading of the configuration file because of security concerns. To work around this issue you can either launch the browser with the --allow-file-access-from-files flag set or use a local web server.

To deploy the application copy the contents of the build/web directory to the document root of your web server. In case of Apache2 the following steps are required:

sudo mv build/web/* /var/www/html
sudo chown -R www-data /var/www/html

License

This application is licensed under the MIT license agreement. See the LICENSE file for details.

just95 / isomers