The Honeycomb User Guide

Current Version GitHub commits since latest release Build Status Rust Tests codecov

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 many-core architectures.

The current objective is to

  • write a first implementation in Rust
  • improve the structure without having to deal with data races and similar issues, thanks to the Rust's guarantees
  • implement basic meshing algorithms to evaluate the viability of the implementation & improve our structure using Rust's framework to streamline the refactoring and parallelization process
  • Benchmark and/or profile and/or parallelize our first algorithm, grisubal
  • Work on efficient parallelism
  • Ship a first stable version of the library (on the back burner, see this issue)
  • Implement a variety of 3D parallel meshing algorithms to support and extend our 2D results

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
  • hwloc - The library is used by the benchmark binary to bind threads to physical cores; you can disable its usage by compiling the benchmark binary without default features

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.9.0" # it is highly encouraged to pin version using a tag or a revision
}

Alternatively, you can add the sub-crates that are currently published on crates.io:

# [dependencies]
honeycomb-core = "0.9.0"
honeycomb-kernels = "0.9.0"
honeycomb-render = "0.9.0"

Note that the documentation hosted on GitHub corresponds to the master branch. Versioned documentation is available 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.

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-dimensional 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

Integration

  • The repository structure and workspace system is heavily inspired by the wgpu and bevy repositories.