Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/juntyr/necsim-rust
Spatially explicit biodiversity simulations using a parallel library written in Rust
https://github.com/juntyr/necsim-rust
biodiversity cuda mpi necsim rust simulation
Last synced: 3 months ago
JSON representation
Spatially explicit biodiversity simulations using a parallel library written in Rust
- Host: GitHub
- URL: https://github.com/juntyr/necsim-rust
- Owner: juntyr
- License: apache-2.0
- Created: 2020-10-12T18:10:52.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-09-26T10:25:22.000Z (5 months ago)
- Last Synced: 2024-10-14T15:43:25.212Z (4 months ago)
- Topics: biodiversity, cuda, mpi, necsim, rust, simulation
- Language: Rust
- Homepage: https://juntyr.github.io/necsim-rust-docs/
- Size: 8.15 MB
- Stars: 2
- Watchers: 5
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# necsim-rust [![CI Status]][workflow] [![Rust Doc]][docs] [![License Status]][fossa] [![Code Coverage]][codecov] [![Binder Demo]][binder] [![Gitpod Ready-to-Code]][gitpod] [![DOI]][zenodo]
[CI Status]: https://img.shields.io/github/actions/workflow/status/juntyr/necsim-rust/ci.yml?branch=main
[workflow]: https://github.com/juntyr/necsim-rust/actions/workflows/ci.yml?query=branch%3Amain
[Rust Doc]: https://img.shields.io/badge/docs-main-blue
[docs]: https://juntyr.github.io/necsim-rust-docs/
[License Status]: https://app.fossa.com/api/projects/custom%2B26490%2Fgithub.com%2Fjuntyr%2Fnecsim-rust.svg?type=shield
[fossa]: https://app.fossa.com/projects/custom%2B26490%2Fgithub.com%2Fjuntyr%2Fnecsim-rust?ref=badge_shield
[Code Coverage]: https://img.shields.io/codecov/c/github/juntyr/necsim-rust?token=DCT0WVLU5V
[codecov]: https://codecov.io/gh/juntyr/necsim-rust
[Binder Demo]: https://img.shields.io/badge/binder-demo-579ACA.svg?logo=data:image/png;base64,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
[binder]: https://mybinder.org/v2/gh/juntyr/necsim-rust-demo/main?urlpath=tree/demo.ipynb
[Gitpod Ready-to-Code]: https://img.shields.io/badge/Gitpod-ready-blue?logo=gitpod
[gitpod]: https://gitpod.io/#https://github.com/juntyr/necsim-rust
[DOI]: https://zenodo.org/badge/DOI/10.5281/zenodo.5220080.svg
[zenodo]: https://doi.org/10.5281/zenodo.5220080
## Introduction
necsim-rust is a Rust reimplementation of the C++ library [necsim](https://bitbucket.org/thompsonsed/necsim) and its Python wrapper [pycoalescence](https://bitbucket.org/thompsonsed/pycoalescence), which are used to run neutral coalescence biodiversity simulations.
necsim-rust aims to provide a smaller, more concise subset of the functionality of necsim and pycoalescence but be easier to use and extend. For instance, necsim-rust contains the classical coalescence algorithm. Additionally, it implements two Gillespie-based algorithms and a novel independent algorithm with a CPU and a CUDA variant. Furthermore, necsim-rust can use MPI to parallelise the simulation.
necsim-rust is built in a modular way to reduce code duplication and allow the user (and other programmers) to plug together different components to customise the simulated scenario, the algorithm it is simulated with as well as finer implementation details. Currently, necsim-rust supports four built-in scenarios:
- non-spatial model
- spatially implicit model with migration from a non-spatial metacommunity to a non-spatial local community
- spatially explicit (almost) infinite model with Gaussian Normal dispersal
- spatially-explicit simulation with habitat and dispersal maps
## Prerequisites
First, you need to clone the necsim-rust GitHub repository:
```shell
git clone https://github.com/juntyr/necsim-rust.git
```
necsim-rust is written in the [Rust language](https://www.rust-lang.org/tools/install), which must be installed in your `PATH` first. necsim-rust includes a `rust-toolchain` file that configures Rust to use a working nightly toolchain version and install all components required for compilation. If you want to use necsim-rust on a target different than `x86_64-unknown-linux-gnu`, please update the [rust-toolchain](rust-toolchain) config file accordingly.
The `necsim-plugins-species` reporter depends on `libsqlite3-dev`, and the `necsim-plugins-tskit` reporter and the `necsim-partitioning-mpi` parallelisation backend (enabled with the `mpi-partitioning` feature) depend on `libclang-dev`. You can install these optional packages using
```shell
sudo apt-get install libclang-dev libsqlite3-dev
```
## Installation
To install `rustcoalescence`, you need to decide which algorithms you want to compile with it. You can enable the provided algorithms by enabling their corresponding features. For instance, to compile all CPU-based algorithms with all scenarios, you can use
```shell
cargo install --path rustcoalescence --locked --features gillespie-algorithms --features independent-algorithm --features all-scenarios
```
To install with CUDA support, you first need to ensure that the dynamic CUDA libraries are in the `LD_LIBRARY_PATH` and enable the `cuda-algorithm` feature:
```shell
LIBRARY_PATH="$LD_LIBRARY_PATH" cargo install --path rustcoalescence --locked [...] --features cuda-algorithm
```
To compile with MPI support, you need to enable the `mpi-partitioning` feature:
```shell
cargo install --path rustcoalescence --locked [...] --features mpi-partitioning
```
After compilation, you can then run `rustcoalescence` using:
```shell
rustcoalescence [...]
```
If you want to use any of the provided reporter analysis plugins, you have to compile them manually. For instance, to compile the `common` plugin which includes the `Biodiversity()`, `Counter()`, `Execution()`, `Progress()` and `Verbose()` reporters, you can run:
```shell
> cargo build --release --manifest-path necsim/plugins/common/Cargo.toml
```
## Compiling for Development
If you want to compile the library for development, you can use any of the above installation commands, but replace
```shell
cargo install --path rustcoalescence --locked [...]
```
with
```shell
cargo build --release [...]
```
## Running rustcoalescence
`rustcoalescence` has two subcommands: `simulate` and `replay` and accepts command-line arguments in the following format:
```shell
rustcoalescence args..
```
Here, `args..` is a configuration string in [RON](https://github.com/ron-rs/ron) format, which can also directly be read from a configuration file:
```shell
rustcoalescence "$(