DRY up docs/README

Cargo.toml

@@ -29,21 +29,34 @@ rug = { version = "1.24", optional = true,  default-features = false, features =
 default = ["ibig", "rayon"]
 ## Enable parallel construction of the Voronoi grid.
 rayon = ["dep:rayon"]
-## Allow saving Voronoi grids to
-## [HDF5 format](https://en.wikipedia.org/wiki/Hierarchical_Data_Format#HDF5).
-hdf5 = ["dep:hdf5"]
-## Use the `dashu` crate as the arbitrary precision integer arithmetic backend.
-dashu = ["dep:dashu"]
-## Use the `ibig` crate as the arbitrary precision integer arithmetic backend.
+## Use the `ibig` crate (MIT/Apache 2.0) as the arbitrary precision integer
+## arithmetic backend.
+## It generally has good performance, but can be up to 50% slower than the
+## `rug` backend for highly degenerate seed configurations (e.g. a perfect grid).
 ibig = ["dep:ibig"]
+## Use the `dashu` crate (MIT/Apache 2.0) as the arbitrary precision integer
+## arithmetic backend.
+## Similar performance to the `ibig` backend.
+dashu = ["dep:dashu"]
 ## Use the `malachite` crate as the arbitrary precision integer arithmetic backend.
-## *Warning:* this changes the license to the more restrictive LGPL-3.0-only license.
+## *Warning:* this changes the license to the more restrictive LGPL-3.0-only
+## license.
+## Slightly faster than the `dashu` backend (up to 40% slower than `rug`).
 malachite = ["malachite-nz", "malachite-base"]
-## Use the `num_bigint` crate as the arbitrary precision integer arithmetic backend.
+## Use the `num_bigint` crate (MIT/Apache 2.0) as the arbitrary precision
+## integer arithmetic backend.
+## Worst performance for degenerate seed configurations (measured up to 140%
+## slower than `rug`).
 num_bigint = ["dep:num-bigint"]
 ## Use the `rug` crate as arbitrary precision integer arithmetic backend.
-## *Warning:* this changes the license to the more restrictive LGPL-3.0+ license.
+## *Warning:* this changes the license to the more restrictive LGPL-3.0+
+## license.
+## The fastest backend, but depends on GNU GMP via the `gmp-mpfr-sys` crate
+## which requires a C compiler to build and hence has the slowest build time.
 rug = ["dep:rug"]
+## Allow saving Voronoi grids to
+## [HDF5 format](https://en.wikipedia.org/wiki/Hierarchical_Data_Format#HDF5).
+hdf5 = ["dep:hdf5"]
 
 [dev-dependencies]
 float-cmp = "0.9"

README.md

@@ -43,59 +43,67 @@ info:
 
 ## Integer Arithmetic Backend
 
-You can select from five backends for arbitrary precision integer arithmetic.
-These all provide identical functionality and vary only in performance and licensing.
+You can select from five backends for arbitrary precision integer
+arithmetic. These all provide identical functionality and vary only in
+performance and licensing.
 
-For most practical applications, the choice of backend does not significantly alter
-performance. However, for highly degenerate seed configurations - i.e. with many groups of more
-than 4 (almost) co-spherical seed points - many arbitrary precision arithmetic tests must be
-performed leading to some performance differences in such cases.
+For most practical applications, the choice of backend does not
+significantly alter performance (see results for a perturbed grid below).
+However, for highly degenerate seed configurations -- i.e. with many groups
+of more than four (almost) co-spherical seed points -- many arbitrary precision
+arithmetic tests must be performed leading to some performance differences
+in such cases (see results for a perfect grid below).
 
-- [`ibig`](https://crates.io/crates/ibig) (MIT/Apache 2.0): This is the default backend.
-  It generally has good performance, but can be up to 40% slower than the `rug` backend for
-  highly degenerate seed configurations.
+Benchmarks for construction of a 3D Voronoi grid with 64³ seeds:
 
-- [`dashu`](https://crates.io/crates/dashu) (MIT/Apache 2.0): Similar performance to the `ibig`
-  backend.
-
-- [`num_bigint`](https://crates.io/crates/num-bigint) (MIT/Apache 2.0): Worst performance for
-  degenerate seed configurations (measured up to 109% slower than `rug`)
-
-- [`malachite`](https://crates.io/crates/malachite) (LGPL-3.0-only): Slightly faster than the
-  `dashu` backend (up to 30% slower than `rug`).
+|              | Perfect grid      | Perturbed grid    |
+| ------------ | ----------------- | ----------------- |
+| `rug`        | 2.062 s ± 0.005 s | 1.308 s ± 0.008 s |
+| `malachite`  | 2.846 s ± 0.016 s | 1.293 s ± 0.005 s |
+| `ibig`       | 3.105 s ± 0.048 s | 1.320 s ± 0.022 s |
+| `dashu`      | 3.249 s ± 0.091 s | 1.313 s ± 0.009 s |
+| `num-bigint` | 4.852 s ± 0.078 s | 1.301 s ± 0.004 s |
 
-- [`rug`](https://crates.io/crates/rug) (LGPL-3.0+): The fastest backend, but depends on GNU GMP
-  via the `gmp-mpfr-sys` crate which requires a C compiler to build and hence has the slowest
-  build time.
+See the next section for details.
 
 ## Cargo Features
 
-<!-- cargo-rdme end -->
-- `rayon` (enabled by default) – Enable parallel construction of the Voronoi
-  grid.
-
-- `hdf5` – Allow saving Voronoi grids to [HDF5 format](https://en.wikipedia.org/wiki/Hierarchical_Data_Format#HDF5).
-
-- `dashu` — Use the `dashu` crate as the arbitrary precision integer arithmetic backend.
+**Note**: the features for choosing a backend are all *mutually exclusive*.
 
-- `ibig` (enabled by default) — Use the `ibig` crate as the arbitrary precision integer arithmetic backend.
-
-- `malachite` — Use the `malachite` crate as the arbitrary precision integer arithmetic backend. 
-
-  *Disclaimer*: this changes the license to the more restrictive LGPL-3.0-only license.
-
-- `num_bigint` — Use the `num_bigint` crate as the arbitrary precision integer arithmetic backend.
+<!-- cargo-rdme end -->
 
-- `rug` – Use the `rug` crate as the arbitrary precision integer arithmetic backend. 
-  This can increase performance significantly for highly degenerate seed configurations where lots of arbitrary 
-  precision arithmetic is needed. 
-
-  *Disclaimer:* this changes the license to the more restrictive LGPL-3.0+ license.
+- `rayon` -- Enable parallel construction of the Voronoi grid.
+- `ibig` -- Use the `ibig` crate (MIT/Apache 2.0) as the arbitrary precision
+  integer arithmetic backend.
+  It generally has good performance, but can be up to 50% slower than the
+  `rug` backend for highly degenerate seed configurations.
+- `dashu` -- Use the `dashu` crate (MIT/Apache 2.0) as the arbitrary precision
+  integer arithmetic backend.
+  Similar performance to the `ibig` backend.
+- `malachite` -- Use the `malachite` crate as the arbitrary precision integer
+  arithmetic backend.
+  *Warning:* this changes the license to the more restrictive LGPL-3.0-only
+  license.
+  Slightly faster than the `dashu` backend (up to 40% slower than `rug`).
+- `num_bigint` -- Use the `num_bigint` crate (MIT/Apache 2.0) as the arbitrary
+  precision integer arithmetic backend.
+  Worst performance for degenerate seed configurations (measured up to 140%
+  slower than `rug`).
+- `rug` -- Use the `rug` crate as arbitrary precision integer arithmetic
+  backend.
+  *Warning:* this changes the license to the more restrictive LGPL-3.0+ license.
+  The fastest backend, but depends on GNU GMP via the `gmp-mpfr-sys` crate which
+  requires a C compiler to build and hence has the slowest build time.
+- `hdf5` -- Allow saving Voronoi grids to
 
 ## License
 
 Licensed under:
- - [Apache-2.0](www.apache.org/licenses/LICENSE-2.0) OR [MIT](https://opensource.org/license/MIT) at your option when 
-   using the `ibig`, `dashu` or `num_bigint` arbitrary precision arithmetic backends.
- - [LGPL-3.0-only](https://www.gnu.org/licenses/lgpl-3.0.html) when using the `malachite` backend
- - [LGPL-3.0+](https://www.gnu.org/licenses/lgpl-3.0.html) when using the `rug` backend.
+
+- [Apache-2.0](www.apache.org/licenses/LICENSE-2.0) OR
+  [MIT](https://opensource.org/license/MIT) at your option when using the
+  `ibig`, `dashu` or `num_bigint` arbitrary precision arithmetic backends.
+- [LGPL-3.0-only](https://www.gnu.org/licenses/lgpl-3.0.html) when using the
+  `malachite` backend
+- [LGPL-3.0+](https://www.gnu.org/licenses/lgpl-3.0.html) when using the `rug`
+  backend.

examples/grid_3d.rs

@@ -0,0 +1,62 @@
+//! Example that builds a Voronoi tesselation for a (perturbed) grid of n^3 points in 3 dimensions.
+//!
+//! Run with: `cargo run --release --example grid_3d`
+//!
+//! The number of points and the size of perturbations can optionally be given as command line
+//! arguments: `cargo run --release --example grid_3d -- [n] [p]`
+//!
+//! Their default values are:
+//! - `n`: 64
+//! - `p`: 0.95
+
+extern crate glam;
+extern crate meshless_voronoi;
+extern crate rand;
+
+use glam::DVec3;
+use meshless_voronoi::Voronoi;
+use rand::{distributions::Uniform, prelude::*};
+use std::convert::TryInto;
+use std::env;
+
+fn perturbed_grid(anchor: DVec3, width: DVec3, count: usize, pert: f64) -> Vec<DVec3> {
+    let mut generators = vec![];
+    let mut rng = thread_rng();
+    let distr = Uniform::new(-0.5, 0.5);
+    for n in 0..count.pow(3) {
+        let i = n / count.pow(2);
+        let j = (n % count.pow(2)) / count;
+        let k = n % count;
+        let pos = DVec3 {
+            x: i as f64 + 0.5 + pert * rng.sample(distr),
+            y: j as f64 + 0.5 + pert * rng.sample(distr),
+            z: k as f64 + 0.5 + pert * rng.sample(distr),
+        } * width
+            / count as f64
+            + anchor;
+        generators.push(pos.clamp(anchor, anchor + width));
+    }
+
+    generators
+}
+
+fn main() {
+    let mut args = env::args().skip(1);
+    let count = match args.next() {
+        Some(n) => n.parse::<usize>().expect(
+            "The first argument should be an integer denoting the grid size along one dimension!",
+        ),
+        None => 64,
+    };
+    let pert = match args.next() {
+        Some(p) => p.parse::<f64>().expect(
+            "The second argument should be a number between 0 and 1 denoting the size of the grid perturbations!"
+        ),
+        None => 0.95,
+    };
+
+    let anchor = DVec3::splat(0.);
+    let width = DVec3::splat(1.);
+    let generators = perturbed_grid(anchor, width, count, pert);
+    let _voronoi = Voronoi::build(&generators, anchor, width, 3.try_into().unwrap(), false);
+}

src/bounding_sphere.rs

@@ -154,7 +154,7 @@ impl BoundingSphereSolver for Epos6 {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use glam::DVec3;
 
     use super::{BoundingSphereSolver, Epos6, Welzl};

src/geometry.rs

@@ -352,7 +352,7 @@ impl Aabb {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use glam::DVec3;
 
     use crate::geometry::{signed_area_tri, signed_volume_tet};

src/lib.rs

@@ -40,32 +40,32 @@
 //!
 //! # Integer Arithmetic Backend
 //!
-//! You can select from five backends for arbitrary precision integer arithmetic.
-//! These all provide identical functionality and vary only in performance and licensing.
+//! You can select from five backends for arbitrary precision integer
+//! arithmetic. These all provide identical functionality and vary only in
+//! performance and licensing.
 //!
-//! For most practical applications, the choice of backend does not significantly alter
-//! performance. However, for highly degenerate seed configurations - i.e. with many groups of more
-//! than 4 (almost) co-spherical seed points - many arbitrary precision arithmetic tests must be
-//! performed leading to some performance differences in such cases.
+//! For most practical applications, the choice of backend does not
+//! significantly alter performance (see results for a perturbed grid below).
+//! However, for highly degenerate seed configurations -- i.e. with many groups
+//! of more than four (almost) co-spherical seed points -- many arbitrary precision
+//! arithmetic tests must be performed leading to some performance differences
+//! in such cases (see results for a perfect grid below).
 //!
-//! - [`ibig`](https://crates.io/crates/ibig) (MIT/Apache 2.0): This is the default backend.
-//!   It generally has good performance, but can be up to 40% slower than the `rug` backend for
-//!   highly degenerate seed configurations.
+//! Benchmarks for construction of a 3D Voronoi grid with 64³ seeds:
 //!
-//! - [`dashu`](https://crates.io/crates/dashu) (MIT/Apache 2.0): Similar performance to the `ibig`
-//!   backend.
+//! |              | Perfect grid      | Perturbed grid    |
+//! | ------------ | ----------------- | ----------------- |
+//! | `rug`        | 2.062 s ± 0.005 s | 1.308 s ± 0.008 s |
+//! | `malachite`  | 2.846 s ± 0.016 s | 1.293 s ± 0.005 s |
+//! | `ibig`       | 3.105 s ± 0.048 s | 1.320 s ± 0.022 s |
+//! | `dashu`      | 3.249 s ± 0.091 s | 1.313 s ± 0.009 s |
+//! | `num-bigint` | 4.852 s ± 0.078 s | 1.301 s ± 0.004 s |
 //!
-//! - [`num_bigint`](https://crates.io/crates/num-bigint) (MIT/Apache 2.0): Worst performance for
-//!   degenerate seed configurations (measured up to 109% slower than `rug`)
-//!
-//! - [`malachite`](https://crates.io/crates/malachite) (LGPL-3.0-only): Slightly faster than the
-//!   `dashu` backend (up to 30% slower than `rug`).
-//!
-//! - [`rug`](https://crates.io/crates/rug) (LGPL-3.0+): The fastest backend, but depends on GNU GMP
-//!   via the `gmp-mpfr-sys` crate which requires a C compiler to build and hence has the slowest
-//!   build time.
+//! See the next section for details.
 //!
 //! # Cargo Features
+//!
+//! **Note**: the features for choosing a backend are all *mutually exclusive*.
 #![doc = document_features::document_features!()]
 
 #[cfg(any(
@@ -102,4 +102,6 @@ mod space;
 mod util;
 mod voronoi;
 
-pub use voronoi::{integrals, ConvexCell, Voronoi, VoronoiCell, VoronoiFace, VoronoiIntegrator};
+pub use voronoi::{
+    integrals, ConvexCell, Dimensionality, Voronoi, VoronoiCell, VoronoiFace, VoronoiIntegrator,
+};

src/simple_cycle.rs

@@ -101,7 +101,7 @@ impl<'a> Iterator for SimpleCycle2Iterator<'a> {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use crate::simple_cycle::SimpleCycle;
 
     #[test]

src/util.rs

@@ -44,7 +44,7 @@ impl<T> GetMutMultiple for Vec<T> {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
 
     #[test]

src/voronoi.rs

@@ -26,7 +26,7 @@ mod voronoi_cell;
 mod voronoi_face;
 
 /// The dimensionality of the Voronoi tessellation.
-#[derive(Clone, Copy, Debug, PartialEq, num_enum::IntoPrimitive)]
+#[derive(Clone, Copy, Debug, PartialEq, num_enum::IntoPrimitive, num_enum::TryFromPrimitive)]
 #[repr(usize)]
 pub enum Dimensionality {
     OneD = 1,
@@ -604,7 +604,7 @@ impl VoronoiIntegrator {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::{
         integrals::{AreaCentroidIntegrator, VolumeCentroidIntegrator},
         *,

src/voronoi/convex_cell.rs

@@ -474,7 +474,7 @@ impl From<ConvexCellAlternative> for ConvexCell {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
 
     #[test]

src/voronoi/voronoi_cell.rs

@@ -170,4 +170,4 @@ impl VoronoiCell {
 }
 
 #[cfg(test)]
-mod test {}
+mod tests {}