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 multiple 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 self-managed Julia installation, there are two options for installing Julia and the IAI system image:

   1. Use juliaup to manage your Julia installation and automatically install your desired Julia and IAI versions. This approach offers an easy setup process, and updating Julia and IAI is straightforward.

   2. Advanced: Install Julia and the IAI system image manually. We do not recommend this approach unless you have a very specific need as it is the most error-prone and least user-friendly method of installation.

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

Installing Julia and the IAI system image with juliaup

Start by installing juliaup, which is both an installer and version manager for Julia that takes care of installing and configuring one or more versions of Julia on your machine.

Once you have installed juliaup, the julia executable is automatically added to the PATH. You should restart your terminal and then run julia to start Julia, after which you should add the IAISystemImages package by running

julia> import Pkg; Pkg.add(url="https://github.com/InterpretableAI/IAISystemImages.jl")

Once complete, you can use the IAISystemImages package to install the IAI system image by running

julia> import IAISystemImages

julia> IAISystemImages.install()

This will open an interactive prompt that allows you to select a version of IAI to install, along with your desired version of Julia. Once installed, you should close Julia to return to the terminal. You can see your installed channels by running juliaup status:

$ juliaup status
 Default  Channel          Version          Update
---------------------------------------------------
       *  1.8.0            1.8.0+0.x64
          1.8.0/IAI/3.1.0  Linked to `...`

You can start this specific combination of Julia and IAI by running julia with the name of the desired channel. For example, we start Julia v1.8.0 with IAI v3.1.0 by running

$ julia +1.8.0/IAI/3.1.0

It is possible to have multiple channels installed simultaneously and switch between them as needed.

If you would like to refer to the channel by a shorter name, you can use juliaup to create an alias. For example, we can create an alias named IAI for the 1.8.0/IAI/3.1.0 channel by running

$ juliaup link IAI julia +1.8.0/IAI/3.1.0

This will allow you to start the selected version simply by running

$ julia +IAI

You can also change the default channel that is used if no channel is specified when starting julia. For instance, if we wanted to set the default channel to be 1.8.0/IAI/3.1.0, we could run

$ juliaup default 1.8.0/IAI/3.1.0

After this, running julia will automatically launch Julia v1.8.0 with IAI v3.1.0

If you are using Jupyter, you can create a kernel that uses a specific channel. To do this, start Julia with the desired channel, and then run the following code:

julia> using IJulia

julia> installkernel("Julia (IAI)", julia=Base.julia_cmd())

This will create a new kernel that uses the current channel. The first argument to installkernel can be used to customize the name of the new kernel.

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):

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:

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.

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

Troubleshooting

Some general errors that can occur during installation are listed below. If you are using the R or Python interfaces, please also refer to the respective installation instructions for these packages to find troubleshooting steps that are specific to those languages.

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.

Missing dependencies

You may see an error during initialization that refers to the artifact belonging to a JLL package:

fatal: error thrown and no exception handler available.
InitError(mod=:OpenSpecFun_jll, error=ErrorException("Artifact "OpenSpecFun" was not found by looking in the paths:
...

This indicates that the required Julia dependencies have not been installed. Please follow [the instructions] to install these dependencies, ensuring that you run the required steps using a Julia runtime that is not configured to use the IAI system image.

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".

Advanced: Installing Julia and the IAI system image manually

After installing Julia using the standard installers, 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.

Once you have downloaded and unzipped the system image, you will need to install the required dependencies for this version of IAI. If there is a file Artifacts.toml inside the zip file, please run the following commands in Julia (replacing /path/to/Artifacts.toml with the path to your unzipped file):

julia> import Pkg; Pkg.add(url="https://github.com/InterpretableAI/IAISystemImages.jl")

julia> import IAISystemImages

julia> IAISystemImages.install_artifacts("/path/to/Artifacts.toml")

If there is no Artifacts.toml file included with the system image then this step can be skipped.

Finally, you need to configure Julia to use this 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.

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

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")

API Reference

get_machine_id()

acquire_license(; keyword_arguments...)

release_license(; keyword_arguments...)