{"id":16877410,"url":"https://github.com/juntyr/necsim-rust","last_synced_at":"2025-03-22T07:31:56.198Z","repository":{"id":36966899,"uuid":"303474757","full_name":"juntyr/necsim-rust","owner":"juntyr","description":"Spatially explicit biodiversity simulations using a parallel library written in Rust","archived":false,"fork":false,"pushed_at":"2024-10-30T06:14:42.000Z","size":8576,"stargazers_count":2,"open_issues_count":8,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-12-06T19:12:57.313Z","etag":null,"topics":["biodiversity","cuda","mpi","necsim","rust","simulation"],"latest_commit_sha":null,"homepage":"https://juntyr.github.io/necsim-rust-docs/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/juntyr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-12T18:10:52.000Z","updated_at":"2024-06-03T09:00:02.000Z","dependencies_parsed_at":"2024-01-06T19:40:38.145Z","dependency_job_id":"fc7aca73-f0df-4a93-abb4-5b21e99c35ec","html_url":"https://github.com/juntyr/necsim-rust","commit_stats":{"total_commits":773,"total_committers":11,"mean_commits":70.27272727272727,"dds":0.721862871927555,"last_synced_commit":"c8c3023a114aeacb97e130a60eff779f9c7cb539"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juntyr%2Fnecsim-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juntyr%2Fnecsim-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juntyr%2Fnecsim-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juntyr%2Fnecsim-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juntyr","download_url":"https://codeload.github.com/juntyr/necsim-rust/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244189797,"owners_count":20412991,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biodiversity","cuda","mpi","necsim","rust","simulation"],"created_at":"2024-10-13T15:43:28.131Z","updated_at":"2025-03-22T07:31:55.148Z","avatar_url":"https://github.com/juntyr.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# necsim-rust \u0026emsp; [![CI Status]][workflow] [![Rust Doc]][docs] [![License Status]][fossa] [![Code Coverage]][codecov] [![Binder Demo]][binder] [![Gitpod Ready-to-Code]][gitpod] [![DOI]][zenodo]\n\n[CI Status]: https://img.shields.io/github/actions/workflow/status/juntyr/necsim-rust/ci.yml?branch=main\n[workflow]: https://github.com/juntyr/necsim-rust/actions/workflows/ci.yml?query=branch%3Amain\n\n[Rust Doc]: https://img.shields.io/badge/docs-main-blue\n[docs]: https://juntyr.github.io/necsim-rust-docs/\n\n[License Status]: https://app.fossa.com/api/projects/custom%2B26490%2Fgithub.com%2Fjuntyr%2Fnecsim-rust.svg?type=shield\n[fossa]: https://app.fossa.com/projects/custom%2B26490%2Fgithub.com%2Fjuntyr%2Fnecsim-rust?ref=badge_shield\n\n[Code Coverage]: https://img.shields.io/codecov/c/github/juntyr/necsim-rust?token=DCT0WVLU5V\n[codecov]: https://codecov.io/gh/juntyr/necsim-rust\n\n[Binder Demo]: https://img.shields.io/badge/binder-demo-579ACA.svg?logo=data:image/png;base64,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\n[binder]: https://mybinder.org/v2/gh/juntyr/necsim-rust-demo/main?urlpath=tree/demo.ipynb\n\n[Gitpod Ready-to-Code]: https://img.shields.io/badge/Gitpod-ready-blue?logo=gitpod\n[gitpod]: https://gitpod.io/#https://github.com/juntyr/necsim-rust\n\n[DOI]: https://zenodo.org/badge/DOI/10.5281/zenodo.5220080.svg\n[zenodo]: https://doi.org/10.5281/zenodo.5220080\n\n## Introduction\n\nnecsim-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.\n\nnecsim-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.\n\nnecsim-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:\n- non-spatial model\n- spatially implicit model with migration from a non-spatial metacommunity to a non-spatial local community\n- spatially explicit (almost) infinite model with Gaussian Normal dispersal\n- spatially-explicit simulation with habitat and dispersal maps\n\n## Prerequisites\n\nFirst, you need to clone the necsim-rust GitHub repository:\n```shell\ngit clone https://github.com/juntyr/necsim-rust.git\n```\nnecsim-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.\n\nThe `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\n```shell\nsudo apt-get install libclang-dev libsqlite3-dev\n```\n\n## Installation\n\nTo 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\n```shell\ncargo install --path rustcoalescence --locked --features gillespie-algorithms --features independent-algorithm --features all-scenarios\n```\nTo 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:\n```shell\nLIBRARY_PATH=\"$LD_LIBRARY_PATH\" cargo install --path rustcoalescence --locked [...] --features cuda-algorithm\n```\nTo compile with MPI support, you need to enable the `mpi-partitioning` feature:\n```shell\ncargo install --path rustcoalescence --locked [...] --features mpi-partitioning\n```\nAfter compilation, you can then run `rustcoalescence` using:\n```shell\nrustcoalescence [...]\n```\nIf 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:\n```shell\n\u003e cargo build --release --manifest-path necsim/plugins/common/Cargo.toml\n```\n\n## Compiling for Development\n\nIf you want to compile the library for development, you can use any of the above installation commands, but replace\n```shell\ncargo install --path rustcoalescence --locked [...]\n```\nwith\n```shell\ncargo build --release [...]\n```\n\n## Running rustcoalescence\n\n`rustcoalescence` has two subcommands: `simulate` and `replay` and accepts command-line arguments in the following format:\n```shell\nrustcoalescence \u003cSUBCOMMAND\u003e args..\n```\nHere, `args..` is a configuration string in [RON](https://github.com/ron-rs/ron) format, which can also directly be read from a configuration file:\n```shell\nrustcoalescence \u003cSUBCOMMAND\u003e \"$(\u003cconfig.ron)\"\n```\nPlease refer to [docs/simulate.ron](docs/simulate.ron) and [docs/replay.ron](docs/replay.ron) for a detailed description of all configuration options. [./simulate.ron](simulate.ron) and [./replay.ron](replay.ron) also provide example configurations.\n\n## Project structure\n\nnecsim-rust consists of the following crates:\n- necsim/: this folder contains the core declaration of the simulation and implementation of its components\n    - core/: `necsim-core` declares the core structs, simulation cogs traits, as well as the generic `Simulation`.\n        - maths/: `necsim-core-maths` declares the required `f64` intrinsics for simulating in a `no-std` environment, and provides a default implementation.\n        - bond/: `necsim-core-bond` declares helper data types which guarantee a limited value range and are used for encoding preconditions through data types.\n    - impls/:\n        - no-std/: `necsim-impls-no-std` contains the implementations of cogs that **do not** require the Rust standard library\n        - std/: `necsim-impls-std` contains the implementations of cogs that **do** require the Rust standard library\n        - cuda/: `necsim-impls-cuda` contains the implementations of CUDA specific cogs\n    - plugins/:\n        - core/: `necsim-plugins-core` implements the reporter plugin system and provides the functionality to export and load plugins\n        - common/: `necsim-plugins-common` implements common analysis reporters, e.g. to measure biodiversity, print a progress bar, etc.\n        - metacommunity/: `necsim-plugins-metacommunity` implements a reporter which measures migrations to a static external metacommunity, which can be simulated separately using the non-spatial scenario\n        - csv/: `necsim-plugins-csv` implements a reporter which records events in a CSV file\n        - species/: `necsim-plugins-species` produces an SQLite database which lists the parent-child relationships of all simulated individuals as well as their species\n    - partitioning/:\n        - core/: `necsim-partitioning-core` declares the core partitioning traits\n        - monolithic/: `necsim-partitioning-monolithic` implements monolithic, i.e. non-parallel partitioning\n        - mpi/: `necsim-partitioning-mpi` implements the MPI-based partitioning backend\n        - threads/: `necsim-partitioning-threads` implements the multithreading-based partitioning backend\n- rustcoalescence/: `rustcoalescence` provides the command-line interface.\n    - scenarios/: `rustcoalescence-scenarios` contains the glue code to put together the cogs for the built-in scenarios. It is specifically built only for reducing code duplication in rustcoalescence, not for giving a minimal example of how to construct a simulation.\n    - algorithms/:\n        - gillespie/: `rustcoalescence-algorithms-gillespie` contains the glue code to put together the cogs for the two **monolithic Gillespie** coalescence algorithms. It is specifically built only for reducing code duplication in rustcoalescence, not for giving a minimal example of how to construct a simulation.\n            - src/gillespie: `GillespieAlgorithm` (also known as the classical algorithm) is a good allrounder that is built on Gillespie's \"next-reaction\" method. While it includes a specialised implementation for uniform turnover rates, it generally uses a dynamic alias method sampler (individual-based) to pick the next event. Therefore, it performs better on habitats with a high probability to disperse to a different location (i.e. small per-location demes).\n            - src/event_skipping: `EventSkippingAlgorithm` is a specialised mathematically correct algorithm that skips self-dispersal events without coalescence. It is built on Gillespie's \"next-reaction\" method and uses a dynamic alias method sampler (location-based) to pick the next event. Therefore, it is very fast on habitats with high self-dispersal probabilities (i.e. large per-location demes), or when the speciation probability is very small.\n        - independent/: `rustcoalescence-algorithms-independent` contains the glue code to put together the cogs for the **independent** coalescence algorithm on the CPU. The algorithm treats the simulation as an embarrassingly parallel problem. It can also be used to simulate subdomains of the simulation separately and piece the results back afterwards without loss of consistency.\n        - cuda/: `rustcoalescence-algorithms-cuda` contains the glue code to put together the cogs for the **independent** coalescence algorithm on a CUDA 3.5 capable GPU. The algorithm treats the simulation as an embarrassingly parallel problem. It can also be used to simulate subdomains of the simulation separately and piece the results back afterwards without loss of consistency.\n\n## GDAL GeoTiff compatibility\n\npycoalescence and necsim both used GDAL to load habitat, dispersal and turnover maps. As rustcoalescence is more strict about type checking the TIFF files, you can use the following commands to convert and compress your GeoTIFF files:\n```shell\ngdalwarp -ot Uint32 -co \"COMPRESS=LZW\" -dstnodata 0 -to \"SRC_METHOD=NO_GEOTRANSFORM\" -to \"DST_METHOD=NO_GEOTRANSFORM\" input_habitat.tif output_habitat.tif\ngdalwarp -ot Float64 -co \"COMPRESS=LZW\" -dstnodata 0 -to \"SRC_METHOD=NO_GEOTRANSFORM\" -to \"DST_METHOD=NO_GEOTRANSFORM\" input_dispersal.tif output_dispersal.tif\ngdalwarp -ot Float64 -co \"COMPRESS=LZW\" -dstnodata 0 -to \"SRC_METHOD=NO_GEOTRANSFORM\" -to \"DST_METHOD=NO_GEOTRANSFORM\" input_turnover.tif output_turnover.tif\n```\n\n## License\n\nLicensed under either of\n\n * Apache License, Version 2.0\n   ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n * MIT license\n   ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuntyr%2Fnecsim-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuntyr%2Fnecsim-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuntyr%2Fnecsim-rust/lists"}