Install#

Orthonym is a Python package. It needs two things on your machine and downloads two more.

You need	Why
Python 3.10 or newer	the engine is written in Python
A Java runtime, version 11 or newer, on your `PATH`	OPSIN, which reads names back for the round-trip check, and centres, which assigns the CIP stereodescriptors, are Java programs

Check the Java runtime with java -version. Any Java 11+ runtime works (for example OpenJDK or Temurin).

Install the package#

$ pip install orthonym
$ orthonym --fetch-jars

With conda, the first line is conda install -c conda-forge orthonym; the conda package also installs a Java runtime. To install the newest code from GitHub instead, use pip install "git+https://github.com/Steinbeck-Lab/Orthonym.git".

The first line installs Orthonym and the packages it needs, among them RDKit, which reads the structures. The second line downloads the two Java programs Orthonym uses, checks each against the SHA-256 checksum recorded in Orthonym, and prints where they are:

$ orthonym --fetch-jars
[orthonym] opsin 2.9.0: /home/you/.cache/orthonym/jars/opsin-cli-2.9.0-jar-with-dependencies.jar
[orthonym] centres 1.2.1: /home/you/.cache/orthonym/jars/centres-cli-1.2.1.jar

If you skip orthonym --fetch-jars, the first call that names a molecule downloads the two jars (about 17 MB) and says so; later calls are fast. An install from GitHub or from a clone already tries this download while pip builds the package. Run orthonym --fetch-jars once anyway: it also re-checks the files, and it tells you at once if something is missing. If your shell does not find orthonym right after the install, open a new terminal (or run hash -r); python -m orthonym works in any case.

The two jars#

Orthonym does not ship any Java program. It uses two, each pinned to one version, and downloads them from their official releases:

Jar	Version	Used for	Licence
OPSIN, `opsin-cli-2.9.0-jar-with-dependencies.jar`	2.9.0	round-trip validation of names	MIT (the jar bundles jna-inchi, LGPL-2.1, and others)
centres, `centres-cli-1.2.1.jar`	1.2.1	CIP stereodescriptors (R/S, E/Z)	BSD-2-Clause (the jar bundles CDK, LGPL-2.1+)

A missing jar is downloaded: when pip builds the package, on first use (unless ORTHONYM_NO_DOWNLOAD=1 is set), or by orthonym --fetch-jars. Downloaded jars and jars in the jar directory are checked against the pinned SHA-256; a jar you point to with ORTHONYM_OPSIN_JAR or ORTHONYM_CENTRES_JAR is used as given. Orthonym stops with an error only when a jar can be neither found nor downloaded. Without a Java runtime it declines every molecule.

Three settings for the jars#

Setting	Effect
`ORTHONYM_OPSIN_JAR=/path/to/opsin-cli-2.9.0-jar-with-dependencies.jar`	use this OPSIN jar
`ORTHONYM_CENTRES_JAR=/path/to/centres-cli-1.2.1.jar`	use this centres jar
`ORTHONYM_JAR_DIR=/path/to/dir`	keep the downloaded jars here (the default is your user cache, `~/.cache/orthonym/jars`)

On a machine with no internet#

On a machine with internet, run orthonym --fetch-jars and copy the two files it prints.
On the offline machine, point Orthonym at the copies:
```
$ export ORTHONYM_OPSIN_JAR=/opt/jars/opsin-cli-2.9.0-jar-with-dependencies.jar
$ export ORTHONYM_CENTRES_JAR=/opt/jars/centres-cli-1.2.1.jar
$ export ORTHONYM_NO_DOWNLOAD=1
```
ORTHONYM_NO_DOWNLOAD=1 stops Orthonym from downloading a missing jar when it names a structure. orthonym --fetch-jars is an explicit request and still downloads.

Naming without the jars#

ORTHONYM_ALLOW_REDUCED=1 lets Orthonym name without the jars. Then no name is read back by OPSIN and the stereodescriptors come from RDKit instead of centres. Use it only when you know you want that.

Next: your first name.