Circuitscape

Documentation	Chat	Build Status

[!NOTE]
Please note that to run the latest version of Circuitscape.jl, you need to install Julia v1.11 or up.

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 has now been rewritten in Julia for better performance and scalability. This work is based on the Python implemention in Circuitscape.py.

The New Circuitscape - Modern, Fast and Flexible

The new Circuitscape is built entirely in the Julia language, a new programming language for technical computing. Julia is built from the ground up to be fast. As such, this offers a number of advantages over the previous version, and these are detailed below.

Faster and More Scalable

We benchmarked Circuitscape.jl (v0.1.0) with the Python version (v4.0.5) to obtain the following results. We started up Circuitscape with 16 parallel processes, and used benchmark problems from the standard Circuitscape benchmark suite.

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, we see that the new version is upto 4x faster on 16 processes. However, the best performing bar in the chart is Julia-CHOLMOD, which is a new feature introduced.

New Solver Mode - CHOLMOD

Julia-CHOLMOD is a new solver mode used in the new Circuitscape. It performs a cholesky decomposition on the graph constructed, and performs a batched back substitution to compute the voltages. It plugs into the CHOLMOD library, which is part of the SuiteSparse collection of high performance sparse matrix algorithms.

To use the this new mode, include a line in your Circuitscape INI file:

solver = cholmod

The cholesky decomposition is a direct solver method, unlike the algebraic multigrid method used by default in both the old and the new version. The advantage with this new direct method is that it can be much faster than the iterative solution, within a particular problem size.

Word of caution: The cholesky decomposition is not practical to use beyond a certain problem size because of phenomenon called fill-in, which results in loss of sparsity and large memory consumption.

Parallel, everywhere

The old Circuitscape had limited support for parallelism, which worked on Mac and Linux, but didn't work on Windows.

Julia as a programming language is built from the ground up to be parallel, and as a result the new Circuitscape natively supports parallelism on all three platforms.

Single Precision (Experimental)

The new Circuitscape introduces the ability to run problems in single precision as opposed to the standard double precision.

Single precision usually takes much less memory, but trades off against solution accuracy.

Use this new feature by including a line in your config file:

precision = single

Installation

You will need to install Julia on your system first.
Once you start Julia, install Circuitscape by:

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

If you want the latest development version, you can additionally do:

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

Check if all the tests are passing by doing the following:

julia> Pkg.test("Circuitscape")

Usage

The current interface to Circuitscape is through the Julia terminal.

julia> using Circuitscape # loads the package into your environment
julia> compute("path/to/config/file.ini")

Contributing

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

Notes on INI files

Circuitscape takes as input INI files, which contain paths to the raster map, sources, grounds, and other inputs, as well as flags for each run. If you're using the GUI the INI file will automatically be generated for you and then fed into Circuitscape. But if you're using the Julia prompt, then you must write one yourself. The easiest way to do this is to copy an INI file from the tests and then modify it depending on your problem.

Citation

A preprint is available here: https://proceedings.juliacon.org/papers/10.21105/jcon.00058. You can also use the following BibTeX entry to cite this package:

@article{Anantharaman2020,
  doi = {10.21105/jcon.00058},
  url = {https://doi.org/10.21105/jcon.00058},
  year = {2020},
  publisher = {The Open Journal},
  volume = {1},
  number = {1},
  pages = {58},
  author = {Ranjan Anantharaman and Kimberly Hall and Viral B. Shah and Alan Edelman},
  title = {Circuitscape in Julia: High Performance Connectivity Modelling to Support Conservation Decisions},
  journal = {Proceedings of the JuliaCon Conferences}
}

Circuitscape / Circuitscape.jl

readme