Set Java heap memory for r5r

Configures the maximum heap size for the Java Virtual Machine (JVM) used by r5r when computing travel-time matrices. Large matrices can require several gigabytes of heap space; insufficient memory causes R to crash with no useful error message.

Usage

set_java_memory(size, persist = interactive())

Arguments

size

Character. Memory size with a unit suffix: "g" for gigabytes or "m" for megabytes. Examples: "4g" (4 GB), "512m" (512 MB), "8g" (8 GB).

persist

Logical. If TRUE, also write the setting to ~/.Renviron so it persists across R sessions. Default: TRUE in interactive sessions, FALSE otherwise.

Value

Invisibly, the previous value of getOption("java.parameters").

Details

This sets options(java.parameters = "-Xmx<size>"). It must be called before r5r (or rJava) is loaded — once the JVM starts, the heap size cannot be changed without restarting R. If rJava is already loaded, a warning is issued.

How much memory do I need?

A rule of thumb: allocate \(\ge 2\) GB per million origin-destination pairs in your travel-time matrix.

Scenario	OD pairs	Recommended heap
Small municipality (500 tracts, 50 stations)	25 k	"2g"
Medium municipality (5,000 tracts, 200 stations)	1 M	"4g"
Large city (50,000 tracts, 2,000 stations)	100 M	"8g"–"16g"

When persist = TRUE, the value is appended to (or updated in) ~/.Renviron as _JAVA_OPTIONS=-Xmx<size>, so every future R session starts with the same heap limit.

See also

setup_java() to install Java 21, compute_travel_times() which uses the JVM heap configured here.

Examples

if (FALSE) { # \dontrun{
# Set 4 GB for the current session only
set_java_memory("4g", persist = FALSE)

# Set 8 GB and save to ~/.Renviron for future sessions
set_java_memory("8g")

# Then compute travel times as usual
tt <- compute_travel_times(tracts_sf, points_sf, network_path = "path/to/network")
} # }