The Honeycomb User Guide
Honeycomb
Honeycomb aims to provide a safe, efficient and scalable implementation of combinatorial maps for meshing applications. More specifically, the goal is to converge towards a (or multiple) structure(s) adapted to algorithms exploiting GPUs and many-core architectures.
The current objective is to
write a first implementation in Rustimprove the structure without having to deal with data races and similar issues, thanks to the Rust's guaranteesimplement basic meshing algorithms to evaluate the viability of the implementation & improve our structure using Rust's framework to streamline the refactoring and parallelization processBenchmark and/or profile and/or parallelize our first algorithm, grisubal- Ship a first stable version of the library (see this issue)
- Work on efficient parallelism
Core Requirements
- Rust stable release - The MSRV may not be the latest stable release, but we do not give any guarantees for older versions compatibility
Quickstart
Rust
You can add honeycomb as a dependency of your project by adding the following lines to its Cargo.toml:
# [dependencies]
honeycomb = { git = "https://github.com/LIHPC-Computational-Geometry/honeycomb", tag = "0.6.0"} # remove tag for master branch build
Alternatively, you can add the sub-crates that are currently published on crates.io:
# [dependencies]
honeycomb-core = "0.6.0"
honeycomb-kernels = "0.6.0"
honeycomb-render = "0.6.0"
Note that if you want to access the latest changes and documentation, you may have to specify a commit instead of a version, and use the GitHub Pages documentation instead of the one hosted on docs.rs.
Documentation
You can generate this book and the Rust documentation locally using respectively mdbook and cargo doc:
mdbook serve --open user-guide/
cargo +nightly doc --all --all-features --no-deps
Note that generating the doc using a stable toolchain is possible, the features just won't be documented as clearly.
Contributing
Contributions are welcome and accepted as pull requests on GitHub. Feel free to use issues to report bugs, missing documentation or suggest improvements of the project.
Note that a most of the code possess documentation, including private modules / items / sections. You can generate the
complete documentation by using the instructions above and passing the option
--document-private-items to cargo doc.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your preference.
The SPDX license identifier for this project is MIT OR Apache-2.0.
Unless 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.
References
Combinatorial Maps
- Damiand and Lienhardt. Combinatorial Maps: Efficient Data Structures for Computer Graphics and
Image Processing. Chapman&Hall/CRC, 2015.
- Provides an in-depth presentation of the structure and its variants
- Link
- The CGAL Project. CGAL User and Reference Manual. CGAL Editorial Board, 5.6.1 edition, 2024.
- Provides concrete examples as well as code snippets of the CGAL implementation of the structure. The CGAL implementation uses a different approach than ours, & support N-dimensionnal map.
- Link
Algorithms
- Staten, Noble, and Wilson. Constructing Tetrahedral Meshes No Matter How Ugly. SIAM, 2024
- Describes the logic behind an overlay grid algorithm.
- Link
- Rangarajan and Lew. Provably Robust Directional Vertex Relaxation for geometric mesh optimization. SIAM, 2017
- usage TBD
- Link