Skip to content

VIII. Engine Management I (DeepLearningVersion)

Jump to bottom
carlosuc3m edited this page Sep 13, 2023 · 2 revisions

Introduction

When JDLL is first installed it is "empty". To be able to run models, the corresponding Deep Learning (DL) frameworks (engines) have to be downloaded and setup (explained here).

Each model might need a different DL framework and version, thus for several models the user might end up with many new engines installed. JDLL offers tools to keep track of what is available and what has been installed to minimize conflicts and improve user experience.

These tools are separted in two classes, one helps understanding which engines have already been installed: io.bioimage.modelrunner.versionmanagement.InstalledEngines and the other one provides information about the engines that can be installed: io.bioimage.modelrunner.versionmanagement.AvailableEngines.

It is important to understand that JDLL supports many enignes and depending on the model the system or the needs one or another engined might be preferred.

Each of the engines is characterized by several fields:

  • Framework name. The name of the Deep Learning framework of the engine.
  • Python version. The version of the DL framework in the Python API.
  • Java version. The version of the DL framework in the Java API.
  • OS. The operating system where then engine can be used.
  • CPU. Whether the engine can be used in a CPU.
  • GPU. Whether the engine can be used in a GPU.
  • Minumum Java version. Minimum required Java version that the engine needs to work.
  • Rosetta. This field is only relevant for systems based on ARM64 chips. Rosetta is a translation process that allows users to run apps that contain x86_64 instructions on Apple silicon. Apple silicon and ARM64 chips are only supported after Java 11, older Java versions use Rosetta to be able to run. However, not all the softwares work well in ARM64, even with Rosetta. Thus, if rosetta=true the engine will be able to run on oler Java versions, and no if not. Again, this is only relevant for Apple silicon systems and a few Linux machines.
  • JARs. List of JAR files that the engine needs to work.

All the above information for each of the engines is stored in the JDLL engines JSON file.

In order to simplify version management and installation, JDLL comes with the io.bioimage.modelrunner.versionmanagement.DeepLearningVersion class. Instances of DeepLearningVersion contain all the information listed above in an organised manner. They provide concise methods that help retrieving the wanted information from each field.

This page is going to detail how to handle the instances of DeepLearningVersion to help developing an efficient management of the DL engines.

io.bioimage.modelrunner.versionmanagement.DeepLearningVersion

General description

The class allows creating objects containing all the information required to handle JDLL Deep Learing engines.

All the information about the engines supported by JDLL can be found in the engines JSON file. This file enumerates all the engines available in JDLL together with the name of their DL framework, the version number in Python, the version number in Java, the operating system that supports it, the minimum Java version required to use it, whether it supports GPU or not, whether it supports CPU or not, whether it supports Rosetta or not and all the JAR files that are needed to run the engine.

Constructors

DL engines have completely fixed features. The details of each of the engines is predefined by JDLL and new engines cannot be created. This is why to create a DeepLearningVersion instance, either the engines JSON file has to be parsed or one of the already installed engines has to be used as reference.

The engines JSON file can be parsed with the following code snippet:

BufferedReader br = new BufferedReader(new InputStreamReader(
                AvailableEngines.class.getClassLoader().getResourceAsStream("availableDLVersions.json")));
Gson g = new Gson();
AvailableEngines availableEngines = g.fromJson(br, AvailableEngines.class);
List<DeepLearningVersion> enginesList = availableEngines.getVersions();

The enginesList variable will contain a List of all the engines that JDLL supports. However, the classes io.bioimage.modelrunner.versionmanagement.AvailableEngines or io.bioimage.modelrunner.versionmanagement.InstalledEngines beter helpful methods to get the engines supported by JDLL and installed in the system respectively. These methods allow retrieving lists of DeepLearningVesion instances filtered by certain fields using methods such as InstalledEngines.checkEngineWithArgsInstalled(String framework, String version, Boolean cpu, Boolean gpu, Boolean rosetta, Integer minJavaVersion, String enginesDir).

The other way to create a DeepLearningVersion object is to use a method from its class DeepLearningVersion.fromFile(File engineDir).

DeepLearningVersion DeepLearningVersion.fromFile(File engineDir)

Method that creates a DeepLearningVesion instance contain all the information about an engine from its folder name when installed.

Engines installed by JDLL should follow a naming protocol:

<DL_framework_name>-<version_of_the _DL_framework_Python_API>-<version_of_the _DL_framework_Java_API>-<os_where_the_engine_works>-<CPU_if_the_engine_supports_CPU>-<GPU_if_the_engine_supports_GPU>

With that name, the features of the engine can be parsed into the DeepLearningInstance. However, if a String that does not correspond to an engine folder, an exception will be thrown.

NOTE THAT THIS METHOD WORKS EVEN IF THE ENGINE AT THE ENGINE PATH IS NOT INSTALLED.

  • engineDir: path to an engine folder. The path to the folder is not required to exist, the name of he engine just needs to be correct. In the image below, one valid engineDir argument would be "C:\Users\carlos\icy\engines\Pytorch-1.11.0-1.11.0-windows-x86_64-CPU-GPU"

Image Alt Text

Here is an example of how to use the method correctly:

String enginesDir = "C:\\Users\\carlos\\icy\\engines\\Pytorch-1.11.0-1.11.0-windows-x86_64-CPU-GPU";
DeepLearningVersion engine = DeepLearningVersion.fromFile(enginesDir);
System.out.println(engine.getFramework());
System.out.println(engine.getMinJavaVersion());
System.out.println(engine.getRosetta());

Output:

pytorch
8
true

Here is an example of how to use the method incorrectly:

String enginesDir = "/path/to/random/not/related/folder";
DeepLearningVersion engine = DeepLearningVersion.fromFile(enginesDir);

Output:

IllegalArgumentException: The name of the engine does not follow the engine name convention followed by DeepIcy: <name_of_the_engine>-<engine_python_version>-<engine_java_version>-<os>-<cpu_if_supported>-<gpu_if_supported>.

And this is what would happen if the engine folder does not exist:

String enginesDir = "/invented/path/to/folder/Pytorch-1.11.0-1.11.0-windows-x86_64-CPU-GPU";
DeepLearningVersion engine = DeepLearningVersion.fromFile(enginesDir);
System.out.println(engine.getFramework());
System.out.println(engine.getMinJavaVersion());
System.out.println(engine.getRosetta());

Output:

pytorch
8
true

String enginesDir = "Pytorch-1.11.0-1.11.0-windows-x86_64-CPU-GPU";
DeepLearningVersion engine = DeepLearningVersion.fromFile(enginesDir);
System.out.println(engine.getFramework());
System.out.println(engine.getMinJavaVersion());
System.out.println(engine.getRosetta());

Output:

pytorch
8
true

If the engine does not exist, another exception will be thrown. In the example below, he version 10000 doe snot exist for pytorch:

String enginesDir = "C:\\Users\\carlos\\icy\\engines\\Pytorch-10000-10000-windows-x86_64-CPU-GPU";
DeepLearningVersion engine = DeepLearningVersion.fromFile(enginesDir);

Output:

Exception: There should only one engine in the resources engine specs file 
'https://raw.githubusercontent.com/bioimage-io/JDLL/main/src/main/resources/availableDLVersions.yml' 
that corresponds to the engine defined by: Pytorch-10000-10000-windows-x86_64-CPU-GPU

Non static methods

List<String> checkMissingJars()

Method that returns all the missing jars of an installed engine. If the DeepLearningVersion instance was created with the DeepLearningVersion.fromFile(File engineDir) method and engineDir argument did not exist, all the jars will be undestood as missing JARs.

However, if the engine referenced by the object is correctly installed, an empty list will be returned.

String folderName()

MEthod that returns the folder name that would be used to call the engine if installed.

The name has to follow a certain naming convention that specifies the enigne features:

<DL_framework_name>-<version_of_the _DL_framework_Python_API>-<version_of_the _DL_framework_Java_API>-<os_where_the_engine_works>-<CPU_if_the_engine_supports_CPU>-<GPU_if_the_engine_supports_GPU>

String getFramework()

Get the name of the DL framework of the enigne. The currently supported DL frameworks are defined here: https://github.com/bioimage-io/JDLL/wiki/List-of-supported-engines

String getPythonVersion()

Get the version of the DL framework Python API

String getVersion()

Get the version of the DL framework JAva API

String getOs()

Get the OS for which the engine works. The possible OS are: windows-x86_64, linux-x86_64, macosx-x86_64, linux-arm64 and macosx-arm64.

String getCPU()

Get whether the engine works on CPU or not

String getGPU()

Get whether the engine works on CPU or not

String getMinJavaVersion()

Get the minimum Java version required to run the engine. Usually 8, although the newer ones might require Java 11

String getRosetta()

Get whether the engine supports Rosetta mode or not. This should only be a concern for Apple Silicon and a few Linux systems that use ARM64 chips

List<String> getJars()

Get a list of strings that correspond to all the JAR files required to run the engine

Clone this wiki locally