HiCT JVM Implementation

Launching pre-built version

NOTE: currently only Windows (tested on 10 and 11) and Linux (with glibc, common Debain/Ubuntu are OK, Alpine users are out of luck) are supported, native libraries for MacOS are not bundled in these builds. Only AMD64 platform is supported. On Windows you might need to install additional libraries.

1. Install Java 19 or newer (older versions won’t be able to launch this code);

2. Make sure that JAVA_HOME variable points to the correct installation path (if you have multiple JREs or JDKs);

3. Download latest "fat" JAR from the Releases page in Assets section. Latest build will usually be on top, however the most stable implementation is in the build from master branch (called "Latest autogenerated build (branch master)"). You can rename it to hict.jar for convenience;

4. Open a terminal and change directory to where the downloaded hict.jar is located;

5. Issue java -jar hict.jar command and wait until message Starting WebUI server on port 8080 …​ WebUI Server started appears;

6. Open your browser and navigate to the http://localhost:8080 where HiCT WebUI should now be available.

Startup options

Currently, there are multiple environment variables that could be set prior to launching HiCT.

• DATA_DIR — should be a path to the directory containing .hict.hdf5, .agp and fasta files. These files could be anywhere in subtree of this directory, it is scanned recursively.

• VXPORT — should be an integer between 1 and 65535 denoting port number which will be served by HiCT API. Note that listening on ports below 4096 usually requires some kind of administrative privileges. If not provided, the default value is 5000. Startup might fail if the port is already occupied by another service. Be sure to set correct port in Connection → API Gateway field in HiCT WebUI if changed.

• WEBUI_PORT — should be an integer between 1 and 65535 denoting port number which will be served by HiCT WebUI. Note that listening on ports below 4096 usually requires some kind of administrative privileges. If not provided, the default value is 8080. Startup might fail if the port is already occupied by another service.

• SERVE_WEBUI — should either be true or false telling whether to start serving HiCT WebUI on the desired port or not. Might be useful during debugging or when WebUI is served by another process. Default is true. This option does not have any effect in case WebUI is not packed into the jar file.

• TILE_SIZE — should be an integer greater than one. Defines the default tile size for visualization. Experimental setting, currently might break WebUI renderer. Default is 256. The greater the tile size is, the less tiles are shown on screen and therefore less requests are sent to the server, but each request could potentially take longer to process.

An example of launching HiCT with parameters:

Linux, bash:

DATA_DIR=/home/${USER}/hict/data SERVE_WEBUI=false java -jar hict.jar

Windows, cmd:

set DATA_DIR="D:\hict\data"
set WEBUI_PORT="8888"
java -jar hict.jar

Windows, PowerShell:

$env:DATA_DIR = "D:\hict\data"
$env:WEBUI_PORT = "8888"
java -jar hict.jar

Custom JVM Options

Of course, you can also pass JVM parameters like this:

DATA_DIR=/home/${USER}/hict/data SERVE_WEBUI=false java -ea -Xms512M -Xmx16G -jar hict.jar

Startup errors

Since library naming conventions are different for different platform and libraries, there is currently a mechanism to try and load each library under a different name. This CAN produce errors on server startup, you can ignore them if Starting WebUI server on port 8080 …​ WebUI Server started message appeared in console.

If, however, server works but maps are not displayed in WebUI and an error sign displays at the bottom right corner of WebUI, you should check console for error output.

Obtaining .hict.hdf5 files

Currently, it’s necessary to use HiCT_Utils package for the file format conversion, there are plans to simplify this process.

Building HiCT_JVM from source

To start building from source, you can run:

./gradlew clean build

Current progress on modifying HDF5 and JHDF5 configuration resides in my personal repository. Modified configuration is necessary to rebuild native libraries (HDF5, HDF5 plugins and JHDF5 should all be build as dynamic libraries). However, prebuilt native libraries for AMD64 Windows and Linux platforms are already present in HiCT_JVM repository. Missing platforms are Linux on armv7 and aarch64 and MacOS (both amd64 and aarch64 variants).