Installation

You can install the R package with

install.packages("iai")

The iai package is a wrapper around the Julia implementation of IAI algorithms, so you need to configure a working Julia installation in addition to installing the R package from CRAN. There are two options for doing this.

Option 1: Automatically install Julia and IAI

The iai package can automatically download and configure a working Julia installation with the IAI system image. To do this, simply run the following commands in R:

iai::install_julia()
iai::install_system_image()

After running these commands, you will need to restart R.

Option 2: Using a separate Julia installation

Follow the instructions for installing the IAI system image to get a working Julia installation with the IAI modules included.

In order to use Julia to run the IAI algorithms, R also needs to know where to find Julia on your computer. By default, it will look for an executable on the system PATH named julia. It is also possible to specify the location of Julia manually if preferred.

Using the R package

After configuring Julia following one of the two options above, you can begin using the iai package. The first time you use an IAI function in an R session, it will automatically initialize the connection to Julia.

Troubleshooting

Julia not correctly configured or not on the PATH

You may receive the following error if Julia is not correctly configured:

Error in JuliaCall::julia_setup(...) : Julia is not found.
In addition: Warning message:
running command ''bash' -l -c 'which julia'' had status 1

On Windows only, you may also see a message similar to the following about being unable to load a library:

Error: Error happens in Julia.
error compiling do_add!: error compiling #add#25: error compiling #update_registries#139: could not load library "libgit2"
The specified module could not be found.

In each case, you will either need to add julia to the system PATH, or follow the steps to specify the path to Julia.

Problem with Julia dependencies

When loading IAI, you might see the following error or one similar:

Error in .julia$cmd(paste0(Rhomeset, "Base.include(Main,\"", system.file("julia/setup.jl",  :
Error happens when you try to execute command ENV["R_HOME"] = "/usr/lib/R";Base.include(Main,"/home/iai/.r_libs_user/JuliaCall/julia/setup.jl") in Julia.
                    To have more helpful error messages,
                    you could considering running the command in Julia directly

The error message details the Julia code that R was trying to run when it failed. This code is specific to your computer and R installation, and must be extracted from your own error message. In the case of the message above, we determine that the following Julia code failed:

ENV["R_HOME"] = "/usr/lib/R"
Base.include(Main,"/home/iai/.r_libs_user/JuliaCall/julia/setup.jl")

To debug the error message further, you should run this Julia code in the Julia environment being used by R:

• If you installed Julia and IAI through the automatic installation process, then you will need to find the Julia information as follows:
  • run readLines(iai:::julia_path_prefs_file()) to show the path to Julia
  • run iai:::sysimage_load_install_path() to show the path to the IAI system image
• If you have manually installed Julia, then use the paths to Julia and the IAI system image from your installation.

You can now run the following command to start Julia (substituting your paths for Julia and the IAI system image):

/path/to/julia --sysimage /path/to/iaisystemimage

Once Julia starts, you can then run the Julia code from earlier to get more information about the error.

IAI not present in Julia installation

You may see the following error when using the package for the first time:

IAI is not present in your Julia installation.

Make sure you have followed the instructions for installing the IAI system image so that the IAI module is present in your Julia installation.

Crashes due to mismatched versions of binary dependencies

When R and Julia try to use incompatible versions of the same binary dependencies, it can result in abrupt errors or segmentation faults. For more background and discussion of this issue, please refer to the similar section of the Python Interface troubleshooting guide.

Here are some real examples of this occuring and the resulting errors:

• An error while loading a library that a specific procedure/function could not be found:

    ERROR: LoadError: LoadError: InitError: could not load library "~/.julia/artifacts/20c009b8faa6b86ae9ecc8002f2772cd4724774d/lib/libgobject-2.0.so"
    ~/.julia/artifacts/20c009b8faa6b86ae9ecc8002f2772cd4724774d/lib/libgobject-2.0.so: undefined symbol: g_dir_unref

As with Python, the most likely libraries to cause this problem are libcurl,libssh2, and libopenssl.

Please follow the steps outlined in the Python troubleshooting guide to try to resolve these conflicts.

Advanced: Specifying location of Julia

If julia is not on the system PATH, or you would like to use another Julia executable, there are two additional ways to specify the location of Julia.

1. Specifying location of Julia using IAI_JULIA

You can set the environment variable IAI_JULIA to point to the julia executable. You can then proceed with installing and using the package as usual.

If you are unsure of the path to your Julia installation, you can get the path to the julia executable by running the following command in Julia:

julia> unsafe_string(Base.JLOptions().julia_bin)

2. Specifying location of Julia using JULIA_HOME

You can also specify the location to Julia by setting the JULIA_HOME variable to point to the folder containing the julia executable.

If you are unsure about which directory to use for JULIA_HOME, you can find the directory by running the following command inside Julia:

julia> Sys.BINDIR

An easy way of specifying JULIA_HOME is using your .Renviron file, which can be configured via the usethis package:

install.packages("usethis")
usethis::edit_r_environ(scope = "user")

This will bring up your environ file, which you can edit to specify JULIA_HOME:

JULIA_HOME="the folder that contains the julia executable"

Once you restart R, the change will take effect

There are other options for setting JULIA_HOME that might better suit some scenarios, you can refer to the "Julia is not found" section in the JuliaCall documentation to see all options.

Advanced: Specifying location of system image

If you do not replace the default Julia system image, there are two additional ways to specify the location of the system image.

1. Specifying location of system image using IAI_SYSTEM_IMAGE

You can set the environment variable IAI_SYSTEM_IMAGE to point to the location of the system image. You can then proceed with installing and importing the package as usual.

2. Specifying location of system image manually

If you would like to specify the location of the system image without using environment variables, you will need to manually initialize the connection to Julia with the path to the system image as the sysimage_path argument. This will need to be done in every R session as the first step:

iai::iai_setup(sysimage_path = "path/to/sys")

Advanced: Development builds of iai

Development builds of the iai package can be installed with the following command:

install.packages("devtools")
devtools::install_url("https://iai-r-interface.s3.amazonaws.com/iai_latest.tar.gz")

There is no need to use these development builds unless directed to do so.