Circuitscape Documentation

Circuitscape is an open-source Julia 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. Circuit theory complements commonly-used connectivity models because of its connections to random walk theory and its ability to simultaneously evaluate contributions of multiple dispersal pathways. Landscapes are represented as conductive surfaces, with low resistances assigned to landscape features types that are most permeable to movement or best promote gene flow, and high resistances assigned to movement barriers. Effective resistances, current flow, and voltages calculated across the landscapes can then be related to ecological processes, such as individual movement and gene flow.

More detail about the underlying model, its parameterization, and potential applications in ecology, evolution, and conservation planning can be found in McRae (2006) and McRae et al. (2008).

More detail about implementation can be found in the Circuitscape In Julia paper.

A PDF version of this documentation is also available.

Quick Start Guide

This is a quick start guide. If you're looking for basics on how to use Circuitscape, refer to the usage guide.

To run Circuitscape, you need to install Julia. At the Julia prompt, install the Circuitscape package by running the following code

using Pkg
Pkg.add("Circuitscape")

You can also install Circuitscape in a local project as well.

Running a job

A Circuitscape job is fully described by an INI file. This configuration file consists of file paths to data as well as flag values. A detailed list of all INI arguments can be found in the Inputs, Outputs and Options section. Examples can be found in the test folder. You can also use a built-in terminal UI to build Circuitscape jobs. For more on that, skip ahead to Building a Circuitscape Job.

If you do have your INI file handy, you can run the job by:

using Circuitscape
Circuitscape.compute("myjob.ini")

You can also run Circuitscape programmatically by passing a configuration dictionary:

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

Building a Circuitscape Job

The builder is kicked off by calling Circuitscape.start(), from the Julia prompt or a script. It will build an INI file for you step by step, and either run the job directly or write the final INI file to a specified location. You can exit the builder at any time by hitting Ctrl+C.

Please note that this version of Circuitscape does not come with a GUI.

You can also manually write your own INI file by copying and pasting an example from the test folder and changing values as needed.

Citing Circuitscape

Please use the following to cite Circuitscape:

@article{hall2021circuitscape,
  title={Circuitscape in julia: empowering dynamic approaches to connectivity assessment},
  author={Hall, Kimberly R and Anantharaman, Ranjan and Landau, Vincent A and Clark, Melissa and Dickson, Brett G and Jones, Aaron and Platt, Jim and Edelman, Alan and Shah, Viral B},
  journal={Land},
  volume={10},
  number={3},
  pages={301},
  year={2021},
  publisher={Multidisciplinary Digital Publishing Institute}
}

Circuitscape.jl vs Circuitscape 4 (Python)

Circuitscape.jl is built entirely in the Julia language, offering significant performance advantages over the previous Python version (v4.0.5).

Faster and More Scalable

The benchmark below dates from 2021 and compares Circuitscape.jl 5.x with the Python version (v4.0.5), both using 16 parallel processes, on problems from the standard Circuitscape benchmark suite. It predates the 6.0 performance work (chunked thread scheduling, native raster I/O, the removal of several graph copies), which is described with measurements under What Makes a Run Fast in On Solvers and Computation Time.

These benchmarks were run on a Linux (Ubuntu) server machine with the following specs:

Name: Intel(R) Xeon(R) Silver 4114 CPU
Clock Speed: 2.20GHz
Number of cores: 20
RAM: 384 GB

From the benchmark, Circuitscape.jl is up to 4x faster on 16 processes. However, the best performing bar in the chart is Julia-CHOLMOD, which uses a direct solver.

Solvers, Threads and Precision

Circuitscape ships with the iterative cg+amg solver (the default) and the direct CHOLMOD solver, and can use Apple Accelerate (macOS) or Intel MKL Pardiso through optional package extensions. Runs are parallelized with Julia threads (julia -t N together with parallelize = True). Single precision (precision = single) is supported: it is tested in CI for cg+amg, CHOLMOD and Accelerate with a precision-aware residual check, and trades memory for some accuracy. GeoTIFF input and output needs the optional ArchGDAL package; ESRI ASCII grids need nothing extra.

All of this, including guidance on choosing a solver and the accuracy note on single precision, is in On Solvers and Computation Time. The INI options are listed in Inputs, Outputs and Options, and users of Circuitscape 5.x should read Upgrading to 6.0.

Omniscape.jl - Omnidirectional connectivity analysis built on top of Circuitscape
AlgebraicMultigrid.jl - Algebraic Multigrid methods in Julia. This is the default solver used in Circuitscape.