Circuitscape

Circuitscape is an open-source program that uses circuit theory to model connectivity in heterogeneous landscapes. Its most common applications include modeling movement and gene flow of plants and animals, as well as identifying areas important for connectivity conservation.

Circuitscape is written in Julia for high performance and scalability. More detail about the implementation can be found in the JuliaCon paper.

Note

Circuitscape.jl requires Julia v1.12 or later.

Installation

1. Install Julia.

2. At the Julia prompt, install Circuitscape:

julia> using Pkg
julia> Pkg.add("Circuitscape")

To install the latest development version:

julia> Pkg.add(PackageSpec(name="Circuitscape", rev="master"))

Run the test suite with:

julia> Pkg.test("Circuitscape")

Optional: GeoTIFF support

ESRI ASCII grids (.asc) work out of the box. To read or write GeoTIFF rasters, add ArchGDAL and load it before Circuitscape:

julia> Pkg.add("ArchGDAL")
julia> using ArchGDAL, Circuitscape

Usage

Circuitscape jobs are configured via INI files. See the documentation for a full guide on data types, calculation modes, and all available options.

julia> using Circuitscape
julia> Circuitscape.compute("path/to/config/file.ini")

Nothing is exported; every function is called as Circuitscape.name (or use using Circuitscape: compute to bring the bare name in).

You can also build INI files interactively using the built-in terminal UI:

julia> using Circuitscape
julia> Circuitscape.start()

Or construct a configuration programmatically:

julia> using Circuitscape
julia> cfg = Circuitscape.init_config()
julia> cfg["habitat_file"] = "resistance_map.asc"
julia> cfg["point_file"] = "focal_nodes.asc"
julia> cfg["scenario"] = "pairwise"
julia> cfg["output_file"] = "output/results.out"
julia> Circuitscape.compute(cfg)

Example INI files can be found in the test folder.

Features

Solver Modes

Circuitscape supports four solver modes:

• CG+AMG (default) — an iterative solver using algebraic multigrid preconditioning. Scales well to large problems.
• CHOLMOD — a direct solver using Cholesky decomposition via the SuiteSparse library. Can be significantly faster for smaller problems, but memory use grows quickly with problem size due to fill-in.
• Apple Accelerate — a direct solver using Apple's Accelerate framework sparse Cholesky, available as a package extension on macOS (requires macOS 13.4+). Requires using AppleAccelerate before using Circuitscape.
• Pardiso — a direct solver via Pardiso.jl, available as a package extension. Requires using Pardiso before using Circuitscape.

To select a solver, add to your INI file:

solver = cholmod   # or accelerate, pardiso

Parallel Computing

Circuitscape supports multi-threaded computation on Linux, macOS, and Windows. Start Julia with julia -t N (or set JULIA_NUM_THREADS) to use N threads and set parallelize = True in your INI file; both are needed.

Single Precision

Circuitscape can run in single precision for reduced memory use at the cost of solution accuracy. It is tested for the CG+AMG, CHOLMOD and Apple Accelerate solvers (Pardiso is double-only). Add to your INI file:

precision = single

Configuration checking

Since 6.0, misspelt values such as solver = cholmodd (for cholmod) or write_cur_maps = Ture (for True), missing input files and a missing output directory are reported as errors before any data is read, instead of silently running something else. See Upgrading to 6.0 for what to change when upgrading.

Performance

In a 2021 benchmark, Circuitscape.jl 5.x was up to 4x faster than the legacy Python version (Circuitscape v4.0.5) on 16 parallel processes, with the CHOLMOD solver providing the best performance on suitable problem sizes. The benchmark predates the 6.0 performance work (threaded pair scheduling, native .asc I/O, lower memory use), which is documented with measurements in the solvers and computation time page.

Benchmarks were run on a Linux (Ubuntu) server with an Intel Xeon Silver 4114 CPU (2.20 GHz, 20 cores, 384 GB RAM) using problems from the benchmark suite.

Related Projects

• Omniscape.jl — Omnidirectional connectivity analysis built on Circuitscape
• AlgebraicMultigrid.jl — The default iterative solver used by Circuitscape

Contributing

If you encounter any issues or would like to ask a question, please file a report here. Contributions in the form of pull requests are welcome!