Skip to main content

tests Build documentation DOI

JAXScape logo: corridors restored through the letters of JAXscape

The quality and permeability rasters are uniform, except on the title: a barrier with no habitat quality and low permeability. jaxscape.SensitivityAnalysis computes the elasticity of connectivity to the permeability of each pixel. The corridors through the letters with the highest elasticity are made permeable (lime) in batches, and the elasticity is recomputed after each batch. Habitat is shaded by its elasticity. Generated by make_logo.py.


JAXScape is a minimal JAX library for connectivity analysis at scales. It provide key utilities to build your own connectivity analysis workflow, including

  • differentiable and GPU-accelerated graph distance metrics
  • differentiable raster to graph and graph to raster mappings
  • moving window utilities for implementing large-scale connectivity analysis pipelines

JAXScape implements custom methods and leverages JAX's capabilities to accelerate distance computations on CPUs/GPUs/TPUs, while ensuring differentiability across the codebase for awesome sensitivity analysis and optimization.

Why JAXScape?

We report below some key runtimes from a comprehensive benchmark testing JAXScape on a RTX 3090 GPU against other related CPU-based software in Python, R, and Julia backends. See the benchmark documentation for the full setup, raw scorecards, convergence status, and fit-quality metrics.

Resistance distance calculation

On a 1000 x 1000 spatial grid, JAXScape is 74x faster than Circuitscape.jl with cg+amg solver and 17x faster than Circuitscape.jl with cholmod solver.

Sensitivity analysis

On a 175 x 175 spatial grid, JAXScape is 12x faster than gdistance shortestPath for shortest-path sensitivity and 5.0x faster than gdistance passage for resistance sensitivity.

Inverse landscape genetics

On a 100 x 100 spatial grid, JAXScape is 32x faster than ResistanceGA and reaches a final relative RMSE about 16x lower.

Installation

uv add jaxscape

The default installation is CPU-only. For NVIDIA GPUs, use uv add 'jaxscape[cuda]', or install JAX following the official JAX installation guide. JAXScape will automatically use the JAX backend you have configured.

Graphs other than grids and large free-energy computations may need an optional linear solver; see the linear solver page.

Quick start

1. Download sample data

curl -sL https://github.com/vboussange/jaxscape/releases/download/v0.0.6/data.zip -o data.zip && unzip -q data.zip && rm data.zip

2. Run the analysis

import jax.numpy as jnp
import matplotlib.pyplot as plt
import numpy as np
from jaxscape import FreeEnergyDistance, GridGraph, LCPDistance, ResistanceDistance

permeability = jnp.array(
    np.loadtxt("data/permeability.csv", delimiter=","), dtype=jnp.float32
) + 0.01
barriers = np.asarray(permeability <= 0.1)

# Symmetric conductances are the mean permeability of neighboring cells.
grid = GridGraph(grid=permeability, fun=lambda x, y: (x + y) / 2)

# Compute distances from the top-left pixel to every other pixel.
source = grid.coord_to_index(jnp.array([0]), jnp.array([0]))
distances = {
    "LCP distance": LCPDistance()(grid, sources=source),
    "Resistance distance": ResistanceDistance()(grid, sources=source),
    "Free-energy distance": FreeEnergyDistance(theta=0.03)(grid, sources=source),
}

distance_cmap = plt.cm.magma.copy()
distance_cmap.set_bad(color="lightgray")

fig, axs = plt.subplots(1, 4, figsize=(12, 3.3))

permeability_im = axs[0].imshow(permeability, cmap="gray", vmin=0, vmax=1)
axs[0].set_xticks([])
axs[0].set_yticks([])
for spine in axs[0].spines.values():
    spine.set_visible(True)
axs[0].set_title("Permeability")
fig.colorbar(permeability_im, ax=axs[0], shrink=0.2)

for ax, (title, dist_to_node) in zip(axs[1:], distances.items()):
    # Convert from node values to a 2D array and hide barrier cells
    dist_array = np.asarray(grid.node_values_to_array(dist_to_node.ravel()))
    dist_array = np.ma.masked_where(barriers, dist_array)

    # Plotting
    im = ax.imshow(dist_array, cmap=distance_cmap)
    ax.axis("off")
    ax.set_title(title)
    fig.colorbar(im, ax=ax, shrink=0.2)

fig.suptitle("Permeability and distance to the top-left pixel")
plt.tight_layout()
plt.show()

theta is the inverse temperature of the free-energy distance: larger values bring it closer to the least-cost distance. The solver guide covers solver choices for other graphs and larger landscapes.

Distances

But what's really cool about JAXscape is that you can autodiff through thoses distances! Check out the documentation to learn about applications and more!

Inverse landscape genetics built on JAXScape, which fits landscape permeability to genetic data by differentiating through resistance distances, lives in ilg-toolkit.

Documentation

Comprehensive documentation is available at https://vboussange.github.io/jaxscape

Contributing

See CONTRIBUTING.md for setup instructions, code contributions, and documentation previews.

Benchmarking

JAXScape includes a benchmark workspace that profiles internal JAXScape implementations and compares them with external landscape-connectivity tools. Published results and task definitions are available in the benchmark documentation. To reproduce the suite or run it on a local CPU/GPU device, follow the instructions in benchmark/README.md.

License

jaxscape is distributed under the terms of the MIT license.

Citation

If you use JAXScape in your research, please cite:

@software{jaxscape2024,
  author = {Boussange, Victor},
  title = {JAXScape: A minimal JAX library for connectivity modelling at scale},
  year = {2025},
  doi = {10.5281/zenodo.15267703},
  url = {https://github.com/vboussange/jaxscape}
}

Metadata

Release files for jaxscape 0.0.17

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jaxscape 0.0.17
File Size Uploaded Provenance Actions
jaxscape-0.0.17.tar.gz 4.9 MB Without provenance Details for jaxscape-0.0.17.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jaxscape 0.0.17
File Interpreter ABI Platform Actions
jaxscape-0.0.17-py3-none-any.whl Python 3 none any Details for jaxscape-0.0.17-py3-none-any.whl

Total release size: 5.0 MB

Release files / jaxscape-0.0.17.tar.gz

Download URL jaxscape-0.0.17.tar.gz
Size 4.9 MB
Tags Source
SHA-256 checksum
How to use checksums
177ae075c572a5a5bd8b3c9204f4c873eb70ae6b3dc640245590d213ae9515ac
BLAKE2b-256 checksum
How to use checksums
ed33564ab1ce0d3df8af4cf89db5ca7c68b4ecd6bc282e0bab32daf6a5823fdc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / jaxscape-0.0.17-py3-none-any.whl

Download URL jaxscape-0.0.17-py3-none-any.whl
Size 99.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
96abb14bed7eaab18d93fce791c81b6b0a8209243082fcf93fdf47130c2c153d
BLAKE2b-256 checksum
How to use checksums
c811b7c0022a1ccbfba1749954ca98c504838b5ab72f7ee0f9f3024a6e68bb31
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.16

Security for jaxscape 0.0.17

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page