Downloading Julia

Download Julia from the official website: https://julialang.org/downloads/

Install the current stable release (e.g., Julia 1.11.x). Both 64-bit Windows and macOS/Linux installers are available. The default installation location works well; note the installation path because you will need it later.

Version compatibility. The R-to-Julia bridge depends on the version of JuliaConnectoR you have installed keeping pace with very new Julia releases. If JuliaConnectoR::juliaEval() crashes the R session even though JuliaConnectoR::juliaSetupOk() returns TRUE, the most likely cause is a mismatch between a bleeding-edge Julia release and an older JuliaConnectoR. In that case, update JuliaConnectoR to its latest version, or install a Julia release one minor version behind the newest. A combination known to work for the package developer should be preferred over the absolute newest Julia.

Windows users. Do not rely on the julia command installed through the Microsoft Store app alias. That stub can report a version with julia --version yet fail to launch a working session for JuliaConnectoR (you may see an error about a missing sys.dll). Install Julia from the official downloads page above and point JULIA_HOME at that installation’s bin/ directory.

Default installation paths by platform:

• Windows: C:\Users\<username>\AppData\Local\Programs\Julia-X.Y.Z\
• macOS: /Applications/Julia-X.Y.app/Contents/Resources/julia/
• Linux: Wherever you extracted the tarball, typically /opt/julia-X.Y.Z/

The Julia binary directory (bin/) is one level inside the installation root. For example, on Windows: C:\Users\<username>\AppData\Local\Programs\Julia-<version>\bin\

Verifying the Julia Installation

Open a terminal (Command Prompt, PowerShell, or bash) and run:

julia --version

You should see output like julia version 1.x.y. If the command is not found, Julia’s bin/ directory is not on your PATH. You may need to add it manually, or just supply the full path when configuring ResistanceGA2.

Installing JuliaConnectoR

ResistanceGA2 uses JuliaConnectoR as its R-to-Julia bridge. This replaces the JuliaCall package used in the original ResistanceGA. If your scripts call JuliaCall functions directly, update them to the JuliaConnectoR equivalents.

Install the JuliaConnectoR R package:

install.packages("JuliaConnectoR")

How ResistanceGA2 Manages Julia Paths

The Julia-facing helpers in ResistanceGA2 are designed to keep your R session stable while still making Julia configuration explicit. You can either set JULIA_BINDIR once for the whole session, or pass the same path as JULIA_HOME to jl.prep(), Run_CS.jl(), or Run_CS.ini().

When you pass JULIA_HOME, the package temporarily points JuliaConnectoR to that Julia bin/ directory and restores the previous JULIA_BINDIR value when the function exits. This matters when you work on a machine with multiple Julia versions, or when a project should use a specific Julia installation without leaving your global R session changed.

# Record the session state before configuring the ResistanceGA2 Julia backend.
old_bindir <- Sys.getenv("JULIA_BINDIR", unset = NA_character_)

JULIA_HOME <- "C:/Users/your-name/AppData/Local/Programs/Julia-<version>/bin/"

jl_inputs <- jl.prep(
  n.Pops        = nrow(samples),
  response      = lower(as.matrix(dist(samples[, 2:3]))),
  CS_Point.File = terra::vect(samples[, 2:3], type = "points"),
  JULIA_HOME    = JULIA_HOME,
  run_test      = FALSE
)

# The package restores the previous value after jl.prep() returns.
identical(Sys.getenv("JULIA_BINDIR", unset = NA_character_), old_bindir)

ResistanceGA2 also loads Circuitscape.jl once per R session and Julia bin/ path. The first call to jl.prep(), Run_CS.jl(), or Run_CS.ini() may still pay the Julia startup cost, but later calls with the same JULIA_HOME reuse the loaded Julia session.

How to read this setup: JULIA_HOME is a project-level choice. It tells the package which Julia installation should run Circuitscape. JULIA_BINDIR is the environment variable used by JuliaConnectoR internally. In normal ResistanceGA2 workflows, pass JULIA_HOME to the package function and let the helper manage JULIA_BINDIR for that call.

Finding Julia’s Path Automatically

If Julia is on your system PATH, you can find the bin/ directory from R:

# Find Julia on PATH
julia_exe <- Sys.which("julia")
if (nzchar(julia_exe)) {
  JULIA_HOME <- dirname(julia_exe)
  message("Found Julia at: ", JULIA_HOME)
} else {
  message("Julia not found on PATH. Set JULIA_BINDIR manually.")
}

Set Up Sample Data

pts     <- vect(samples[, 2:3], type = "points")
surfaces <- terra::unwrap(resistance_surfaces)
surface  <- terra::subset(surfaces, "continuous")

pts
#> class       : SpatVector
#> geometry    : points
#> dimensions  : 25, 0  (geometries, attributes)
#> extent      : 6.25, 19.25, 6.25, 19.25  (xmin, xmax, ymin, ymax)
#> coord. ref. :
surface
#> class       : SpatRaster
#> size        : 50, 50, 1  (nrow, ncol, nlyr)
#> resolution  : 0.5, 0.5  (x, y)
#> extent      : 0, 25, 0, 25  (xmin, xmax, ymin, ymax)
#> coord. ref. : 
#> source(s)   : memory
#> name        : continuous
#> min value   :   6.514823
#> max value   :  13.376758

Create Julia Inputs with jl.prep()

jl.prep() configures everything needed for Circuitscape runs. Setting run_test = TRUE is strongly recommended the first time you use the package on a new machine; it runs a small Circuitscape test to verify the full pipeline before a long optimization:

pairwise_genetic <- lower(as.matrix(dist(samples[, 2:3])))

jl_inputs <- jl.prep(
  n.Pops        = nrow(samples),
  response      = pairwise_genetic,
  CS_Point.File = pts,
  JULIA_HOME    = JULIA_HOME,
  run_test      = TRUE,   # verify the connection
  silent        = TRUE    # suppress Julia startup messages
)

names(jl_inputs)

Run_CS.jl() for Pairwise Distances

In this workflow, Run_CS.jl(..., output = "matrix") returns a lower-triangle vector of pairwise resistance distances, ordered the same way as other ResistanceGA2 pairwise outputs. That is why the result is indexed like a vector, not like a 2-D matrix.

cs_vector <- Run_CS.jl(
  jl.inputs = jl_inputs,
  r         = surface,
  output    = "matrix"
)

length(cs_vector)
head(cs_vector)

The precomputed example for the small dataset ships with the package:

cs_vector <- vignette_pairwise_outputs$circuitscape_matrix

length(cs_vector)
#> [1] 300
head(cs_vector)
#> [1] 5.538005 6.486677 7.276222 7.802246 5.089549 5.828889

Run_CS.jl() Parameter Details

Direct Circuitscape runs with .ini-style control

If you want fuller control over Circuitscape options than Run_CS.jl() is designed to expose, use Run_CS.ini().

cs_out <- Run_CS.ini(
  r = surface,
  CS_Point.File = pts,
  JULIA_HOME = JULIA_HOME,
  scenario = "pairwise",
  connect_four_neighbors_only = TRUE,
  write_cur_maps = TRUE,
  write_cum_cur_map_only = TRUE,
  return = "all",
  rm.files = FALSE
)

See the separate Direct Circuitscape Runs from R vignette for examples using advanced mode, source and ground inputs, included-pairs files, and other Circuitscape support files.

Current maps

Conceptual Similarity

Both gdistance::commuteDistance() and Circuitscape compute random-walk based effective distances. They are derived from the same mathematical framework (circuit theory / random walk theory) and should produce highly correlated outputs on the same resistance surface.

In practice, the outputs are not identical because:

1. commuteDistance() uses a graph-based representation where only adjacent cells are connected, while Circuitscape models current flow through the full grid using finite element methods.
2. commuteDistance() uses 4-neighbor or 8-neighbor connectivity; Circuitscape uses 4-neighbor by default.
3. Numerical precision and solver differences introduce small discrepancies.

The two distance measures will typically be very highly correlated (r > 0.95) for the same resistance surface, but the absolute values will differ in scale.

Comparing Outputs

# Compute both distance types from the same surface
gdist_inputs <- gdist.prep(
  n.Pops = nrow(samples),
  samples = terra::vect(samples[, 2:3], type = "points"),
  method = "commuteDistance"
)

gdist_out <- Run_gdistance(
  gdist.inputs = gdist_inputs,
  r            = terra::subset(terra::unwrap(resistance_surfaces), "continuous")
)

# These will be on different scales but should be highly correlated
gdist_vec <- lower(as.matrix(gdist_out))
cs_vec    <- vignette_pairwise_outputs$circuitscape_matrix

cor(gdist_vec, cs_vec)

# Visual comparison
plot(gdist_vec, cs_vec,
     xlab = "gdistance commuteDistance",
     ylab = "Circuitscape resistance distance",
     main = "Comparison of distance engines")

The high correlation means that optimization results (which surface is best, what parameters are recovered) are typically very similar between the two engines. The choice of distance engine should be driven by what you need from the output (Circuitscape-matched values, current maps, etc.), not by expectation of meaningfully different optimization results.

Landscape Size

Circuitscape computational cost scales approximately with the number of non-null cells in the resistance raster. Larger landscapes take longer.

For large landscapes, consider:

1. Aggregating the raster to a coarser resolution for optimization, then resampling the optimal surface back to fine resolution for current map generation.
2. Using gdistance for the iterative optimization step, then running Circuitscape once with the optimal parameters for final output.
3. Using precision = TRUE to reduce memory use.
4. Using cholmod = FALSE if CHOLMOD runs out of memory.

Number of Populations

Circuitscape runtime also scales with the number of source nodes (sample populations). For n populations, there are n*(n-1)/2 pairwise computations.

For datasets with many populations on large landscapes, gdistance will usually be substantially faster for optimization. Use Circuitscape for the final output only.

recommend_commute_settings() can help with that handoff. A common pattern is:

commute_plan <- recommend_commute_settings(
  raster = terra::subset(terra::unwrap(resistance_surfaces), "continuous"),
  n.Pops = nrow(samples)
)

gdist_inputs <- gdist.prep(
  n.Pops         = nrow(samples),
  response       = lower(as.matrix(dist(samples[, 2:3]))),
  samples        = terra::vect(samples[, 2:3], type = "points"),
  method         = "commuteDistance",
  commute.approx = commute_plan$commute.approx,
  approx.factor  = commute_plan$approx.factor
)

# Use gdist_inputs during GA optimization, then run the final best surface with
# jl.prep() / Run_CS.jl() if you need Circuitscape-matched output or a current map.

Checking Your Julia Environment

From the Julia REPL:

using Pkg
Pkg.status()

This shows all packages installed in the current environment. You should see Circuitscape listed.

Multiple Julia Versions

If you have multiple Julia versions installed, make sure JULIA_HOME points to the one where you installed Circuitscape.jl. Different Julia versions have separate environments.

# Check which Julia version JuliaConnectoR is using
JuliaConnectoR::juliaEval("string(VERSION)")

# If wrong, update JULIA_HOME and restart R
Sys.setenv(JULIA_BINDIR = "/path/to/correct/julia/bin/")

Updating Circuitscape.jl

To update Circuitscape to the latest version, run from the Julia REPL:

using Pkg
Pkg.update("Circuitscape")

After updating, test the new version before running a large optimization:

jl_inputs_test <- jl.prep(
  n.Pops        = nrow(samples),
  CS_Point.File = vect(samples[, 2:3], type = "points"),
  JULIA_HOME    = JULIA_HOME,
  run_test      = TRUE
)

Julia Not Found

Symptom: Error: “Could not find Julia” or “JULIA_BINDIR not set”

Solutions: 1. Verify JULIA_BINDIR is set correctly: Sys.getenv("JULIA_BINDIR") 2. Confirm the path exists and contains the Julia executable:

bindir <- Sys.getenv("JULIA_BINDIR")
dir.exists(bindir)
file.exists(file.path(bindir, "julia.exe"))   # Windows
file.exists(file.path(bindir, "julia"))       # macOS/Linux

3. Set the path explicitly before calling any package functions:

   Sys.setenv(JULIA_BINDIR = "C:/path/to/julia/bin/")

Circuitscape Not Found

Symptom: using Circuitscape fails with “Package not installed”

Solutions: 1. Open Julia directly (not from R) and run Pkg.add("Circuitscape"). 2. Confirm you are using the correct Julia version: JuliaConnectoR::juliaEval("string(VERSION)"). 3. Check that Circuitscape was installed in the default environment, not a project-specific environment: julia using Pkg Pkg.activate() # activate default environment Pkg.add("Circuitscape")

Slow Startup

Symptom: The first call to jl.prep() or Run_CS.jl() takes 30–60 seconds.

This is normal Julia behavior (JIT compilation on first use). Subsequent calls within the same R session will be much faster because Julia caches compiled code. The startup cost is paid only once per R session.

To minimize the impact on optimization runs, call jl.prep() once at the beginning of your session (which triggers Julia startup) before beginning optimization.

Out of Memory

Symptom: Circuitscape crashes or returns an error about insufficient memory.

Solutions: 1. Use precision = TRUE in jl.prep() to switch to single-precision arithmetic. 2. Use cholmod = FALSE to switch from the direct CHOLMOD solver to an iterative solver. 3. Aggregate the resistance raster to a coarser resolution. 4. Reduce the number of sample populations if feasible.

File Permission Errors on Windows

Symptom: Error messages about inability to write to temporary files.

Solutions: 1. Set scratch in jl.prep() to a directory where you have write permissions:

jl_inputs <- jl.prep(
  ...,
  scratch = "C:/Users/your-name/julia_scratch/"
)

2. Verify that the default tempdir() is writable: dir.exists(tempdir())

Connection Drops Mid-Optimization

Symptom: Julia-related errors appear after the optimization has been running for a while.

This can occur if Julia’s memory or disk use causes the process to be killed. Solutions:

1. Monitor system resources during the run.
2. Use precision = TRUE and/or cholmod = FALSE to reduce memory use.
3. Aggregate the raster to a coarser resolution.
4. Split the optimization into smaller chunks (fewer surfaces, smaller GA population).