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.11 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")

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> compute("path/to/config/file.ini")

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

julia> using Circuitscape
julia> Circuitscape.INIBuilder.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> 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 to use N threads, or set parallelize = True in your INI file.

Single Precision

Circuitscape can run in single precision for reduced memory use at the cost of solution accuracy. Add to your INI file:

precision = single

Performance

Circuitscape.jl is 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.

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!