# JuliaCall for Seamless Integration of R and Julia

Package JuliaCall is an R interface to Julia, which is a high-level, high-performance dynamic programming language for numerical computing, see https://julialang.org/ for more information. Below is an image for Mandelbrot set. JuliaCall brings more than 100 times speedup of the calculation! See https://github.com/Non-Contradiction/JuliaCall/tree/master/example/mandelbrot for more information.

## Installation

You can install JuliaCall just like any other R packages by

install.packages("JuliaCall")

To use JuliaCall you must have a working installation of Julia. This can be easily done via:

library(JuliaCall)
install_julia()

which will automatically install and setup a version of Julia specifically for use with JuliaCall. Or you can do

library(JuliaCall)
julia_setup(installJulia = TRUE)

which will invoke install_julia automatically if Julia is not found and also do initialization of JuliaCall.

You can also setup Julia manually by downloading a generic binary from https://julialang.org/downloads/ and add it to your path. Currently Julia v0.6.x and the Julia v1.x releases are all supported by JuliaCall.

You can get the development version of JuliaCall by

devtools::install_github("Non-Contradiction/JuliaCall")

## Basic Usage

Before using JuliaCall, you need to do initial setup by function julia_setup() for automatic type conversion, Julia display systems, etc. It is necessary for every new R session to use the package. If not carried out manually, it will be invoked automatically before other julia_xxx functions. Solutions to some common error in julia_setup() are documented in the troubleshooting section.

library(JuliaCall)
julia <- julia_setup()
#> Julia version 1.5.0 at location C:\Users\lch34\AppData\Local\JULIAC~1\JULIAC~1\julia\V15~1.0\bin will be used.

## If you want to use Julia at a specific location, you could do the following:
## julia_setup(JULIA_HOME = "the folder that contains Julia binary").
## You can also set JULIA_HOME in command line environment or use options(...).

## Different ways of using Julia to calculate sqrt(2)

# julia$command("a = sqrt(2);"); julia$eval("a")
julia_command("a = sqrt(2);"); julia_eval("a")
#> [1] 1.414214
julia_eval("sqrt(2)")
#> [1] 1.414214
julia_call("sqrt", 2)
#> [1] 1.414214
julia_eval("sqrt")(2)
#> [1] 1.414214
julia_assign("x", sqrt(2)); julia_eval("x")
#> [1] 1.414214
julia_assign("rsqrt", sqrt); julia_call("rsqrt", 2)
#> [1] 1.414214
2 %>J% sqrt
#> [1] 1.414214

## You can use julia$exists as exists in R to test ## whether a function or name exists in Julia or not julia_exists("sqrt") #> [1] TRUE julia_exists("c") #> [1] FALSE ## Functions related to installing and using Julia packages julia_install_package_if_needed("Optim") julia_installed_package("Optim") #> [1] "0.22.0" julia_library("Optim") ## Troubleshooting and Ways to Get Help ### Julia is not found Make sure the Julia installation is correct. JuliaCall can find Julia on PATH, and there are three ways for JuliaCall to find Julia not on PATH. • Use julia_setup(JULIA_HOME = "the folder that contains julia binary") • Use options(JULIA_HOME = "the folder that contains julia binary") • Set JULIA_HOME in command line environment. ### libstdc++.so.6: version GLIBCXX_3.4.xx’ not found Such problems are usually on Linux machines. The cause for the problem is that R cannot find the libstdc++ version needed by Julia. To deal with the problem, users can export “TheFolderContainsJulia/lib/julia” to R_LD_LIBRARY_PATH. ### RCall not properly installed The issue is usually caused by updates in R, and it can be typically solved by setting rebuild argument to TRUE in julia_setup() as follows. JuliaCall::julia_setup(rebuild = TRUE) ### ERROR: could not load library "/usr/lib/x86_64-linux-gnu/../bin/../lib/x86_64-linux-gnu/julia/sys.so" This error happens when Julia is built/installed with MULTIARCH_INSTALL=1, as it is on e.g. Debian. It is caused by the bindir-locating code in jl_init not being multiarch-aware. To work around it, try setting JULIA_BINDIR=/usr/bin in .Renviron. ### How to Get Help • One way to get help for Julia functions is just using julia$help as the following example:
julia_help("sqrt")
#> 
#> sqrt(x)
#> 
#>
#> Return $\sqrt{x}$. Throws [DomainError](@ref) for negative [Real](@ref) arguments. Use complex negative arguments instead. The prefix operator v is equivalent to sqrt.
#>
#> # Examples
#>
#> jldoctest; filter = r"Stacktrace:(\n $[0-9]+$.*)*"
#> julia> sqrt(big(81))
#> 9.0
#>
#> julia> sqrt(big(-81))
#> ERROR: DomainError with -81.0:
#> NaN result for non-NaN input.
#> Stacktrace:
#>  [1] sqrt(::BigFloat) at ./mpfr.jl:501
#> [...]
#>
#> julia> sqrt(big(complex(-81)))
#> 0.0 + 9.0im
#> 
#>
#> 
#> sqrt(A::AbstractMatrix)
#> 
#>
#> If A has no negative real eigenvalues, compute the principal matrix square root of A, that is the unique matrix $X$ with eigenvalues having positive real part such that $X^2 = A$. Otherwise, a nonprincipal square root is returned.
#>
#> If A is real-symmetric or Hermitian, its eigendecomposition ([eigen](@ref)) is used to compute the square root.   For such matrices, eigenvalues <U+03BB> that appear to be slightly negative due to roundoff errors are treated as if they were zero More precisely, matrices with all eigenvalues = -rtol*(max |<U+03BB>|) are treated as semidefinite (yielding a Hermitian square root), with negative eigenvalues taken to be zero. rtol is a keyword argument to sqrt (in the Hermitian/real-symmetric case only) that defaults to machine precision scaled by size(A,1).
#>
#> Otherwise, the square root is determined by means of the Björck-Hammarling method [^BH83], which computes the complex Schur form ([schur](@ref)) and then the complex square root of the triangular factor.
#>
#> [^BH83]: Åke Björck and Sven Hammarling, "A Schur method for the square root of a matrix", Linear Algebra and its Applications, 52-53, 1983, 127-140. [doi:10.1016/0024-3795(83)80010-X](https://doi.org/10.1016/0024-3795(83)80010-X)
#>
#> # Examples
#>
#> jldoctest
#> julia> A = [4 0; 0 4]
#> 2×2 Array{Int64,2}:
#>  4  0
#>  0  4
#>
#> julia> sqrt(A)
#> 2×2 Array{Float64,2}:
#>  2.0  0.0
#>  0.0  2.0
#> 

## JuliaCall for R Package Developers

If you are interested in developing an R package which is an interface for a Julia package, JuliaCall is an ideal choice. You only need to find the Julia function or Julia module you want to have in R, using the module, and julia_call the function. There are some examples:

If you have any issues in developing an R package using JuliaCall, you may report it using the link: https://github.com/Non-Contradiction/JuliaCall/issues/new, or email me at lch34677@gmail.com or cxl508@psu.edu.

## Suggestion, Issue Reporting, and Contributing

JuliaCall is under active development now. Any suggestion or issue reporting is welcome! You may report it using the link: https://github.com/Non-Contradiction/JuliaCall/issues/new, or email me at lch34677@gmail.com or cxl508@psu.edu. You are welcome to use the issue template and the pull request template. The contributing guide provides some guidance for making contributions.

### Checking JuliaCall Package

To check and test the JuliaCall package, you need to have the source package. You can

• download the source of JuliaCall from Github,
• open JuliaCall.Rproj in your RStudio or open R from the downloaded directory,
• run devtools::test() to see the result of the test suite.
• run devtools::check() or click the Check button in the RStudio Build panel in the upper right to see the result of R CMD check.

## Other Interfaces Between R and Julia

• RCall.jl is a Julia package which embeds R in Julia. JuliaCall is inspired by RCall.jl and depends on RCall.jl for many functionalities like type conversion between R and Julia.
• XRJulia is an R package based on John Chambers’ XR package and allows for structured integration of R with Julia. It connects to Julia and uses JSON to transfer data between Julia and R. A simple performance comparison between XRJulia and Julia can be found in JuliaCall JOSS paper.
• RJulia is an R package which embeds Julia in R as well as JuliaCall. It is not on CRAN yet, and I haven’t tested it.

JuliaCall is licensed under MIT.

## Code of Conduct

Please note that the JuliaCall project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

## Citing

If you use JuliaCall in research that resulted in publications, then please cite the JuliaCall paper using the following BibTeX entry:

@Article{JuliaCall,
author = {Changcheng Li},
title = {{JuliaCall}: an {R} package for seamless integration between {R} and {Julia}},
journal = {The Journal of Open Source Software},
publisher = {The Open Journal},
year = {2019},
volume = {4},
number = {35},
pages = {1284},
doi = {10.21105/joss.01284},
}`