Skip to contents

Julia: connect R to Julia

Source: R/julia-connect.R
julia_connect.Rd

This function connects R to Julia.

Usage

julia_connect(
  JULIA_HOME,
  JULIA_PROJ,
  JULIA_NUM_THREADS,
  JULIA_PATTER_SOURCE,
  .pkg_config = NULL,
  .pkg_install = NULL,
  .pkg_update = NULL,
  .pkg_load = NULL,
  .socket = !interactive(),
  .verbose = getOption("patter.verbose"),
  ...
)

Arguments

JULIA_HOME, JULIA_PROJ, JULIA_NUM_THREADS, JULIA_PATTER_SOURCE

(optional) Julia options, provided as function arguments, global options or environment variables.

  • JULIA_HOME—A character string that defines the location of the Julia installation (see JuliaCall::julia_setup()). Usually, this is not required.

  • JULIA_PROJ—A character string that defines the directory of a Julia Project. If unspecified, the default environment (e.g., ~/.julia/environments/v1.10/Project.toml) is used with a message instead of a local Julia project.

  • JULIA_NUM_THREADS—On MacOS or Linux, JULIA_NUM_THREADS is a character ("auto") or an integer that defines the number of threads used by multi-threaded operations in Julia. This defaults to "auto" (not 1). This can only be set once per R session. On Windows, JULIA_NUM_THREADS must be set system-wide and use of this argument produces a warning. See this GitHub Issue for instructions.

  • JULIA_PATTER_SOURCE—For advanced use only: a character string that defines the source of Patter.jl. This may be:

    • An absolute file path to a local copy of the package, in which case it is added as a development dependency;

    • A Git branch name (e.g., "main", "dev") or a commit SHA (e.g., "b7c2fda733f80fcfd8770058cded7e0946b3abc0");

    • A valid installation URL (e.g., "https://github.com/edwardlavender/Patter.jl.git");

If missing, JULIA_PATTER_SOURCE defaults to "https://github.com/edwardlavender/Patter.jl.git".

If JULIA_PATTER_SOURCE changes, force the update by .pkg_update.

.pkg_config, .pkg_install, .pkg_update, .pkg_load

(optional) Julia package options.

  • .pkg_config is a character string of Julia code, evaluated by julia_code(), that configures Julia prior to dependency management.

  • .pkg_install—A character vector of accessory Julia packages for install.

  • .pkg_update—Package update control:

    • NULL or FALSE suppresses package updates;

    • TRUE updates all installed packages;

    • A character vector updates named packages;

  • .pkg_load—Package loading (using) control:

    • NULL or FALSE loads required packages only;

    • TRUE loads all installed packages

    • A character vector loads required and additionally named packages;

Note that for Patter.jl, .pkg_update does not respect the current branch of the installation and always defaults to "https://github.com/edwardlavender/Patter.jl.git". Specify JULIA_PATTER_SOURCE to update on a different branch.

.socket

A logical variable that defines whether or not to reconnect to Julia.

  • Use FALSE (default) to skip re-running the function (i.e., if JULIA_SESSION = "TRUE");

  • Use TRUE to force a reconnect. This is required for nodes in a socket cluster, which inherit JULIA_SESSION = "TRUE" but which are not connected to Julia;

.verbose

User output control (see patter-progress for supported options).

...

Additional arguments passed to JuliaCall::julia_setup() (excluding verbose).

Value

The function returns the Julia interface invisibly (see JuliaCall::julia_setup()). If JULIA_SESSION is already "TRUE" and .socket = FALSE, invisible(NULL) is returned.

Details

patter is an R front-end for the Patter.jl package. This requires a local installation of Julia. This function connects R to the local Julia installation, sets up JuliaCall, which provides the integration between R and Julia, and Patter.jl. Internally, the steps are as follows:

  • JuliaCall is set up via JuliaCall::julia_setup().

  • The environment variable JULIA_SESSION is set to "TRUE".

  • The number of threads is set, if possible, via JULIA_NUM_THREADS.

  • The Julia installation is validated.

  • A local Julia Project is generated in JULIA_PROJ (if specified and required) and activated. We recommend using patter within an RStudio Project, with a Julia directory at the top-level that contains the Julia project.

  • If specified, .pkg_config is run via julia_code().

  • Patter.jl and supporting dependencies are added or updated (if required) and loaded (optionally in the local Julia Project).

To set JULIA_* options (e.g., JULIA_HOME, JULIA_PROJ, JULIA_NUM_THREADS), it is recommended to use .Rprofile or .Renviron. To set these options in .Rprofile, follow these instructions:

# (1) Open .Rprofile
usethis::edit_r_profile()

# (2) Add the following to .Rprofile

# Use a local `Julia` project:
if (!requireNamespace("here", quietly = TRUE)) {
  install.packages("here")
}
julia_proj <- here::here("Julia")
if (!dir.exists(julia_proj)) {
  dir.create(julia_proj)
}
Sys.setenv(JULIA_PROJ = here::here("Julia"))

# Set `JULIA_NUM_THREADS` (on MacOS/Linux):
# - In general, more threads faster, up to a point;
# - On Windows, follow the alternative instructions linked above;
# - (You may also set [`data.table::data.table`] threads here via `OMP_NUM_THREADS`)
Sys.setenv(JULIA_NUM_THREADS = parallel::detectCores() - 1L)

# (3) Save .Rprofile and restart R:

# (4) Run `julia_connect()` in the `R` console as usual:
# There is no need to specify `JULIA_*` arguments e.g., JULIA_PROJ
# There are inherited from .Rprofile
julia_connect()

You should run julia_connect() once per R session (and additionally for every socket in a socket cluster, if necessary).

To update the number of threads, restart R and re-run the function with an updated JULIA_NUM_THREADS argument.

See also

See julia_validate() to validate the R—Julia interface.

Author

Edward Lavender

Examples

if (patter_run(.geospatial = FALSE)) {

  #### Set JULIA OPTIONS
  # Recommended: set JULIA options in .Rprofile or .Renviron (see Details)
  # Otherwise: include JULIA options as function arguments below

  #### Example (1): First time use
  # Use `...` to customise `JuliaCall::julia_setup()`
  # Try `installJulia` if you require a Julia installation
  # The first call to `julia_connect()` may take several minutes
  julia_connect(installJulia = TRUE)

  #### Example (2): Connect to `Julia` using default settings
  julia_connect()

  #### Example (3): Force an update of installed packages
  # This example is potentially slow
  if (FALSE) {
    # Update a specific package
    julia_connect(.pkg_update = "GeoArrays")
    # Update all packages
    julia_connect(.pkg_update = TRUE)
  }

  #### Example (4): Customise user output
  julia_connect(.verbose = FALSE)

}
#> `patter::julia_connect()` called @ 2025-04-22 09:30:54... 
#> ... Running `Julia` setup via `JuliaCall::julia_setup()`... 
#> ... Validating Julia installation... 
#> ... Setting up Julia project... 
#> ... Handling dependencies... 
#> ... `Julia` set up with 11 thread(s). 
#> `patter::julia_connect()` call ended @ 2025-04-22 09:30:54 (duration: ~0 sec(s)). 
#> `patter::julia_connect()` called @ 2025-04-22 09:30:54... 
#> ... Running `Julia` setup via `JuliaCall::julia_setup()`... 
#> ... Validating Julia installation... 
#> ... Setting up Julia project... 
#> ... Handling dependencies... 
#> ... `Julia` set up with 11 thread(s). 
#> `patter::julia_connect()` call ended @ 2025-04-22 09:30:54 (duration: ~0 sec(s)).