Set Up Julia and Load Circuitscape/Omniscape

Initialize the Julia session and load the Circuitscape and Omniscape Julia packages. This is called automatically on first use of any cs_* or os_* function. Call explicitly to control the Julia path, number of threads, or pre-warm the session.

Usage

cs_setup(julia_home = NULL, threads = 1L, quiet = TRUE, ...)

Arguments

julia_home: Character. Path to the Julia bin/ directory. If NULL (default), Julia is located the same way as JuliaCall::julia_setup(): the JULIA_HOME option or environment variable, a Julia installed by cs_install_julia() or JuliaCall::install_julia(), the system PATH (including a login shell's PATH on macOS and Linux), and common Windows install locations.
threads: Integer. Number of Julia threads to start. Default 1L. Takes effect only if Julia is not yet running in this R session — once Julia is running, the thread count cannot be changed without restarting R, and a warning is issued. This setting controls parallelism for os_run() only; Circuitscape functions (cs_*) run single-threaded regardless of this value.
quiet: Logical. Suppress Julia startup messages. Default TRUE.
...: Additional arguments passed to JuliaCall::julia_setup().

Value

Invisibly returns TRUE on success.

Details

cs_setup() does not install Julia or Julia packages. If Julia is not found or the required packages are missing, it throws an informative error directing you to cs_install_julia().

cs_setup() will:

Verify that Julia is installed and accessible.
Verify that the Circuitscape and Omniscape Julia packages are installed.
Load both packages and warm up the JIT compiler.

Once Julia is initialized, it stays warm for the R session. Subsequent calls to cs_setup() return immediately.

Threading

Julia's thread count is fixed when Julia starts and cannot be changed mid-session. Multi-threading is used by os_run() when parallelize = TRUE. Circuitscape functions (cs_pairwise, cs_one_to_all, etc.) do not benefit from multiple threads.

cs_setup(threads = 4)
os_run(resistance, radius = 50, parallelize = TRUE)

Call cs_setup(threads = ) before anything else starts Julia, including JuliaCall::julia_setup() or another package that uses JuliaCall. If you need to start Julia yourself, set the thread count first with Sys.setenv(JULIA_NUM_THREADS = "4,0"). The ,0 (no interactive threads) matters: Omniscape releases before 0.6.3 fail in parallel when Julia has an interactive thread, and os_run() then falls back to a serial run with a warning.

References

McRae, B.H. (2006). Isolation by resistance. Evolution, 60(8), 1551–1561. doi:10.1111/j.0014-3820.2006.tb00500.x

Landau, V.A., Shah, V.B., Anantharaman, R. & Hall, K.R. (2021). Omniscape.jl: Software to compute omnidirectional landscape connectivity. Journal of Open Source Software, 6(57), 2829. doi:10.21105/joss.02829

Circuitscape.jl: https://docs.circuitscape.org/Circuitscape.jl/latest/

Omniscape.jl: https://docs.circuitscape.org/Omniscape.jl/latest/

Examples

if (FALSE) { # circuitscaper::cs_julia_available()
cs_setup()
cs_setup(threads = 4)
cs_setup(julia_home = "/usr/local/julia/bin")
}