Introduction

The Java version of the OpenEye Toolkits is a JNI (Java Native Interface) wrapper created using SWIG. It is important to note that this is not a new version of the toolkits written in Java nor is it a Java interpretation of the toolkit API, but a rather faithful reproduction of the toolkit API in Java. As such there are some features that might not be as Java-like as a toolkit written entirely in Java, but most of these are minor issues and consistency with all the supported languages makes translation from one to another relatively easy and greatly enhances our ability to support all the language versions.

A few of these idiomatic differences include:

• There are relatively few classes in OEChem and they have a rather shallow inheritance hierarchy.

• Most OEChem algorithms are in C++ free functions. These are mapped to static methods in the class oechem.

• Method names in most OEChem TK classes start with uppercase letters.

• Java doesn’t support operator overloading, so C++ operators are mapped to methods. For example, operator bool() is mapped to a member function called IsValid(), operator() is mapped to call() and operator() const is mapped to constCall().

• Java doesn’t support direct access to class attributes, so for some simple C++ classes and structs, direct access is mapped to a get/set pair of functions.

• Calling close() is required for all objects that provide a close() method.

• delete() should be explicitly called on all objects that come from the following toolkits:

  • Grid TK

  • Shape TK

  • Szybki TK

  • Zap TK

  The user should interact with these particular libraries from only a single Java thread. Failing to do so can lead to subtle race conditions.

• There is a known bug concerning OpenEye constants that occurs when compiling against an older version of the OpenEye jar and running against a newer version of the OpenEye jar. Please make sure to run against java programs against the same version it was compiled with.

A Java version of the toolkits allows integration into Java desktop and server-side applications. However, the Java toolkits are not necessarily suited for applet programming since they require native code and platform- specific shared libraries. This can be achieved by building a multi-platform JAR as described in the final section, but this is considered for experts only.

Note

In general, due to the wrapping of native code, using explicit obj.delete() calls on class instances obtained from any toolkit is highly recommended as it minimizes issues with early or delayed deletion activity by the Java garbage collector on OpenEye class instances.

Prerequisites

In order to use the OpenEye Java toolkits, a compatible version of the Java SDK must be installed. For the most part, this means installing a version of OpenJDK8, OpenJDK11, or OpenJDK20 (on macOS arm64). See https://openjdk.org/ for your platform.

Linux installation also requires the zlib and libcairo libraries be available. These are usually available on Desktop Linux installations by default, but may not be available on Linux server installations.

Platform Support

OpenEye’s support of operating systems changes from the time to time, with older systems retired and newer ones validated. For the current set of supported platforms, see the current release notes.

Additional software requirements are spelled out in the following sections.

Windows

• OpenJDK8 x64

• OpenJDK11 (supported by the OpenJDK8 package)

Linux

Support for OpenJDK8 and OpenJDK11 is available.

macOS

Java 8 x64 and Java 11 are supported with one single-build macOS package. Additionally, Java 20 arm64 is supported with a single macOS package. See the current release notes for the macOS versions supported.

GPU Prerequisites

GPU-Related Requirements

The following is required in order to use GPU-accelerated OpenEye toolkits and applications:

Supported Platforms

CUDA-enabled OpenEye software is only available on supported Linux platforms. For supported Linux platforms see above and/or the Platform Support Page

Supported GPUs

An NVIDIA Tesla, Quadro, or GeForce GPU with a compute capability of 3.5 or higher is required on your system. For a comprehensive table of which GPUs fall into which compute capability category please refer to the CUDA wikipedia page.

NVIDIA Drivers

• Minimum NVIDIA Driver version: 450.x.

• CUDA is not required to be installed.

We recommend driver 450.80.02 and we strongly advise manually downloading and installing the appropriate NVidia driver for your system as opposed to using a package manager.

To install, root privilege is required. Follow these steps:

1. Download the driver to the machine you are installing it on.

2. chmod +x the driver package to make it executable.

3. Ensure you have disabled X-server by killing any running sessions. Reboot may be required if X-server is still running after this step.

   Warning

   Disabling X-server requires different processes to be killed depending on your Linux distribution. See Nvidia installation guide for more details.

   Warning

   The NVidia kernel module can often conflict with the open source Nouveau display drivers depending on your specific Linux distribution. The NVidia documentation is a much more complete and up-to-date source for information on how to work around this issue. See Disabling Nouveau on the NVIDIA website.

4. Install the driver by sudo ./NVIDIA-Linux-x86_64-450.80.02.run and follow the step-by-step installation instructions.

For more details on driver installations see the CUDA Installation Guide

Note

The output of the nvidia-smi command is extremely useful when debugging GPU issues. Please include the output from nvidia-smi in any request to support@eyesopen.com.

Performance Tuning

To get the most performance out of an NVIDIA Graphics card, use the persistence daemon to switch persistence mode on across all cards on the system (root privilege required):

sudo nvidia-persistenced --user foo

This will automatically enable persistence mode after reboot.

For full instructions on persistence daemon see the Persistence daemon section of the NVIDIA docs.

Download the OpenEye Java distribution

Picking a distribution is relatively easy. For each platform (Windows, Linux, and macOS), we only have 1 download, a 64-bit version (x64).

Download from http://www.eyesopen.com/downloads.

Installation

Untar or unzip the distribution into a directory of your choice. This will create the following structure:

OpenEye-Java-|pkgversion|-OSName-xArch/
    docs/
    lib/
       oejava-|pkgversion|-OSName-xArch.jar
    verify/
       verify.py
    examples/
       build.xml
       openeye/
          examples/
          docexamples/

Warning

For Windows, the distribution should be unzipped to a directory with a short pathname, so the longest directory pathname in the tree can be specified in less than 260 characters. Otherwise, one may see errors when running the verify.py mentioned below due to the 260 character maximum path limit in Windows.

Warning

For Windows, please note that spaces in the path names to the distribution, ant or java may cause errors with building and running examples. Please install these items in a location that does not contain spaces in the path name.

All the examples are found in the examples directory. Use ant to compile the examples jar then you can run an OEChem example using:

For Linux/macOS:

cd OpenEye-Java-|pkgversion|-OSName-xArch/examples
ant
java -cp ../lib/oejava-|pkgversion|-Linux-x64.jar:openeye.examples.jar openeye.examples.oechem.OEChemInfo

For Windows, note the use of semi-colon instead of a colon in the class path argument:

cd OpenEye-Java-|pkgversion|-OSName-xArch/examples
ant
java -cp ../lib/oejava-|pkgversion|-Windows-x64.jar;openeye.examples.jar openeye.examples.oechem.OEChemInfo

The verify.py script can also be run to ensure a properly working distribution in the current environment. If there are problems with the distribution or environment the script will fail. To run verify.py:

cd OpenEye-Java-|pkgversion|-OSName-xArch/verify
python verify.py

Note

If an error similar to java.lang.OutOfMemoryError: Java heap space occurs, one can increase the heap size of the JVM using the ‘JAVAFLAGS’ environment variable. The ‘-Xmx’ option controls the size of Java heap used. For example, add export JAVAFLAGS=-Xmx4G in bash, and then rerun verify.py.