Interpretable AI System Image

Interpretable AI packages are implemented in the Julia language and provided using a precompiled system image for Julia. This is a file with the extension .dll for Windows, .dylib for macOS, or .so for Linux. There are two ways to install the software on your system:

  1. If you are planning to use the R or Python interfaces to the IAI algorithms, it is possible for these packages to download and configure a Julia installation automatically. For more information, please refer to the relevant installation instructions for either R or Python.

  2. If you would prefer to work directly in Julia, or use R or Python with a manually-managed Julia installation, please follow the instructions below to install Julia and the IAI system image.

In both cases, once the installation is complete, please follow the instructions to obtain a license file.

Installing the system image manually

Please contact us for access to the system image.

Each system image is compatible with a specific operating system and version of Julia, so when downloading, make sure you select the version that matches your environment.

You should install the exact version of Julia corresponding to your system image using the standard installers.

Warning

We strongly recommend that you install an official release of Julia, as we cannot guarantee compatibility with self-compiled versions of Julia.

Warning

Currently, only the x86 (Intel or Rosetta) version of Julia is supported on macOS. The ARM (M-series Processor) version of Julia will not work at this time.

Once installed, you need to configure Julia to use the new system image. There are two options.

Option 1: Replace default image

Replace the default system image file (sys.dll/sys.dylib/sys.so) with the file you have downloaded. You might also like to rename and keep the original file in case you want to revert to the default system image.

Warning

On macOS, replacing the default system image may lead to Julia being unable to start, with an error message stating "Julia.app is damaged". In this case, please restore the original system image and specify the system image at runtime instead.

For a default Julia installation, the system image is located at:

OSDefault system image location
WindowsC:\Users\username\AppData\Local\Programs\Julia-version\lib\julia\
macOS/Applications/Julia-version.app/Contents/Resources/julia/lib/julia/
Linuxjulia_install_dir/lib/julia/

If you are unsure about where to find the system image file, you can run the following command in Julia to show the correct location:

julia> unsafe_string(Base.JLOptions().image_file)
Option 2: Specify the system image at runtime

Specify the system image file when starting Julia using the -J/--sysimage flag. For example, the following shell command will start Julia with the modified system image, assuming julia is on the system PATH:

$ julia --sysimage path/to/sys.dylib

If you are using Jupyter, you can run the following code in Julia to create a custom kernel that loads the IAI system image:

julia> using IJulia

julia> installkernel("Julia (IAI)", "--sysimage=path/to/sys.dylib")

Obtaining a license file

Once installation is complete, when the IAI modules are launched for the first time, a number of packages will be installed in order to satisfy dependencies. You will then receive a message that there is no license file, along with a machine ID:

Could not find Interpretable AI license file at `~/iai.lic`. If you need to register a license for this machine, please send us the following machine ID:
478b884fa4f8fcd73a102ccffe3d347276f51cdf94d32b079226a8f9edb204c3

You can also get the machine ID directly with one of the following functions (depending on the language being used):

LanguageFunction
JuliaIAI.get_machine_id()
Pythoniai.get_machine_id()
Riai::get_machine_id()

Please send us this machine ID so that we can create a license file for your machine. You will need to place this file in your home folder (which you can find by running homedir() inside Julia) with the name iai.lic. By default, the path to the license file should be:

OSDefault license file location
WindowsC:\Users\username\iai.lic
macOS/Users/username/iai.lic
Linux/home/username/iai.lic

Alternatively, you can set the environment variable IAI_LICENSE_FILE to point to the location of your license file if you would like to place it elsewhere.

Using the system image in Julia

When working with the system image in Julia, you can use Julia as you would normally, with the exception that the Interpretable AI modules are already loaded into the Julia session.

Important

There is no need to run using IAI - the IAI package is already loaded in every session.

You can find the version of the system image by running IAISysImg.VERSION.

Troubleshooting

Incompatible architectures

On macOS with ARM (M-series) processors, you may see the following error:

OSError: dlopen(/Applications/Julia-1.8.app/Contents/Resources/julia/lib/libjulia.1.8.dylib, 0x000A):
tried: '/Applications/Julia-1.8.app/Contents/Resources/julia/lib/libjulia.1.8.dylib'
(mach-o file, but is an incompatible architecture (have (arm64), need (x86_64)))

This indicates that the architecture of the system image does not match that of Julia. Please double-check that Julia and the system image are either both Intel, or both ARM.

Security issues on macOS

On newer versions of macOS, you may receive a warning when you try to start Julia with the new system image:

"sys.dylib" cannot be opened because the developer cannot be verified

To fix this, go to the "General" tab under "Security & Privacy" in "System Preferences", and click "Allow Anyway".

API Reference

IAI.get_machine_idFunction
get_machine_id()

Return the machine ID for the current computer.

IAI.acquire_licenseFunction
acquire_license(; keyword_arguments...)

Acquire an IAI license for the current session.

This functionality is only needed when using a floating license server with a limited number of licenses, and you want to hold onto a license for the duration of your session.

The acquired license can then be released with release_license.

Keyword Arguments

  • parallel_processes::Vector{<:Integer}: the processes to include in the license request. Defaults to all available processes.
IAI.release_licenseFunction
release_license(; keyword_arguments...)

Release any IAI license held by the current session (obtained through acquire_license).

Keyword Arguments

  • parallel_processes::Vector{<:Integer}: the processes for which to release the license. Defaults to all available processes.