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.
+
+
+
diff --git a/docs/theme.js b/docs/theme.js
new file mode 100644
index 00000000..0c830922
--- /dev/null
+++ b/docs/theme.js
@@ -0,0 +1,16 @@
+document.getElementById('theme-toggle').addEventListener('change', function() {
+ document.documentElement.classList.toggle('dark-mode', this.checked);
+ // Optional: Persist theme preference in localStorage
+ localStorage.setItem('theme', this.checked ? 'dark' : 'light');
+});
+
+// Check for saved theme preference or system preference on page load
+document.addEventListener('DOMContentLoaded', () => {
+ const savedTheme = localStorage.getItem('theme');
+ const themeToggle = document.getElementById('theme-toggle');
+
+ if (savedTheme === 'dark') {
+ document.documentElement.classList.add('dark-mode');
+ themeToggle.checked = true;
+ }
+});
diff --git a/user-guide/src/SUMMARY.md b/user-guide/src/SUMMARY.md
index 300b92b5..d6774573 100644
--- a/user-guide/src/SUMMARY.md
+++ b/user-guide/src/SUMMARY.md
@@ -9,11 +9,13 @@
- [Other content](./project-structure/others.md)
- [Benchmarks](./project-structure/honeycomb-benches.md)
- [Examples](./project-structure/honeycomb-examples.md)
- - [User guide](./project-structure/honeycomb-guide.md)
# Kernels
+- [DVR](./kernels/dvr.md)
- [Grisubal](./kernels/grisubal.md)
+- [Polygon triangulation](./kernels/triangulations.md)
+- [Splits](./kernels/splits.md)
# Definitions
@@ -27,5 +29,4 @@
- [Add / Remove a dimension](./definitions/changeNdim.md)
- [Add / Remove a free dart](./definitions/changeNdart.md)
- [Sewing / Unsewing operation](./definitions/sew.md)
-- [Advanced Operations](./definitions/advancedops.md)
diff --git a/user-guide/src/definitions/advancedops.md b/user-guide/src/definitions/advancedops.md
deleted file mode 100644
index 8a65fc1b..00000000
--- a/user-guide/src/definitions/advancedops.md
+++ /dev/null
@@ -1 +0,0 @@
-# Advanced Operations
diff --git a/user-guide/src/definitions/embedding.md b/user-guide/src/definitions/embedding.md
index 2009f417..1c93a036 100644
--- a/user-guide/src/definitions/embedding.md
+++ b/user-guide/src/definitions/embedding.md
@@ -10,10 +10,9 @@ dedicated sections.
## Implementation
-Because embedding is defined per-application or per-needs, our combinatorial map
-implementation uses a generic system to handle this; The storage follows our
-own specific logic, which is detailed in [this](../honeycomb_core/struct.CMap2.html#note-on-cell-identifiers)
-documentation entry.
+Because embedding is defined per-application or per-needs, our combinatorial map implementation uses
+a generic system to handle this; The storage follows our own specific logic, which is detailed in
+[this](../../honeycomb_core/cmap/struct.CMap2.html#note-on-cell-identifiers) documentation entry.
## Examples
diff --git a/user-guide/src/definitions/sew.md b/user-guide/src/definitions/sew.md
index 0a21312c..8cdd9cea 100644
--- a/user-guide/src/definitions/sew.md
+++ b/user-guide/src/definitions/sew.md
@@ -35,9 +35,9 @@ Exact properties of the link operation directly depends on the property of the m
The *i-sew* operation corresponds to an *i-link* operation, coupled with an update of the affected attributes. *How*
the attributes are updated is defined through trait implementation in the Rust crate (see
-[AttributeUpdate](../honeycomb_core/trait.AttributeUpdate.html),
-[AttributeBind](../honeycomb_core/trait.AttributeBind.html)). *Which* attributes are updated can be deduced from the
-dimension *i* of the sewing operation. This is summarized in the following table:
+[AttributeUpdate](../../honeycomb_core/attributes/trait.AttributeUpdate.html),
+[AttributeBind](../../honeycomb_core/attributes/trait.AttributeBind.html)). *Which* attributes are updated can be
+deduced from the dimension *i* of the sewing operation. This is summarized in the following table:
| Dimension | Geometrical operation | 0-cell / Vertex Attributes | 1-cell / Edge Attributes | 2-cell / Face Attributes | 3-cell / Volume Attributes |
|-----------|-----------------------|----------------------------|--------------------------|--------------------------|----------------------------|
@@ -49,4 +49,4 @@ dimension *i* of the sewing operation. This is summarized in the following table
The unsew operation is the complementary to the sew operation. It behaves according to similar properties, but is used
to remove links between darts. It does so by replacing values of the beta functions by the null dart. Geometrical
-updates are handled and defined in the same way as for the sew operation.
\ No newline at end of file
+updates are handled and defined in the same way as for the sew operation.
diff --git a/user-guide/src/index.md b/user-guide/src/index.md
index 0a6f2906..c33b9ced 100644
--- a/user-guide/src/index.md
+++ b/user-guide/src/index.md
@@ -20,8 +20,9 @@ The current objective is to
- ~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**~
- Ship a first stable version of the library (see this [issue](https://github.com/LIHPC-Computational-Geometry/honeycomb/issues/150))
-- Benchmark and/or profile and/or parallelize our first algorithm, **grisubal**
+- Work on efficient parallelism
### Core Requirements
@@ -53,28 +54,16 @@ version, and use the GitHub Pages documentation instead of the one hosted on doc
## Documentation
-Published crates:
-
-- [honeycomb](honeycomb/) *Main crate*
-- [honeycomb-core](honeycomb_core/) *Core definitions and tools*
-- [honeycomb-kernels](honeycomb_kernels/) *Meshing kernel implementations*
-- [honeycomb-render](honeycomb_render/) *Visualization tool*
-
-Others:
-
-- [honeycomb-benches](honeycomb_benches/) *Rust code benchmarks*
-- [honeycomb-examples](honeycomb_examples/) *Rust code examples*
-
-You can also generate this documentation locally using **mdbook** and **cargo doc**:
+You can generate this book and the Rust documentation locally using respectively **mdbook** and **cargo doc**:
```shell
-# Serve the doc on a local server
-mdbook serve --open -d ../target/doc/ user-guide/ &
+mdbook serve --open user-guide/
+```
+```shell
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.
+Note that generating the doc using a stable toolchain is possible, the features just won't be documented as clearly.
## Contributing
@@ -109,7 +98,7 @@ defined in the Apache-2.0 license, shall be dual licensed as above, without any
### Combinatorial Maps
-- Damiand, Guillaume, and Pascal Lienhardt. *Combinatorial Maps: Efficient Data Structures for Computer Graphics and
+- 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](https://hal.science/hal-01090890v1)
@@ -118,6 +107,15 @@ defined in the Apache-2.0 license, shall be dual licensed as above, without any
implementation uses a different approach than ours, & support N-dimensionnal map.
- [Link](https://doc.cgal.org/latest/Combinatorial_map/)
+### Algorithms
+
+- Staten, Noble, and Wilson. *Constructing Tetrahedral Meshes No Matter How Ugly*. SIAM, 2024
+ - Describes the logic behind an overlay grid algorithm.
+ - [Link](https://internationalmeshingroundtable.com/assets/research-notes/imr32/2011.pdf)
+- Rangarajan and Lew. *Provably Robust Directional Vertex Relaxation for geometric mesh optimization*. SIAM, 2017
+ - usage TBD
+ - [Link](https://epubs.siam.org/doi/abs/10.1137/16M1089101)
+
### Integration
- The repository structure and workspace system is heavily inspired by
diff --git a/user-guide/src/kernels/dvr.md b/user-guide/src/kernels/dvr.md
new file mode 100644
index 00000000..1b712d34
--- /dev/null
+++ b/user-guide/src/kernels/dvr.md
@@ -0,0 +1,5 @@
+# Directional Vertices Relaxation
+
+---
+
+WIP: https://github.com/LIHPC-Computational-Geometry/honeycomb/pull/212
diff --git a/user-guide/src/kernels/grisubal.md b/user-guide/src/kernels/grisubal.md
index 5d9971a0..0556a0c8 100644
--- a/user-guide/src/kernels/grisubal.md
+++ b/user-guide/src/kernels/grisubal.md
@@ -6,7 +6,7 @@
the input geometry in an overlapping grid, by first computing intersection vertices and then rebuilding
boundaries from the captured vertices.
-The algorithm can be called using [this](../honeycomb_kernels/grisubal/fn.grisubal.html) function.
+The algorithm can be called using [this](../../honeycomb_kernels/grisubal/fn.grisubal.html) function.
[IMR-RN]: https://internationalmeshingroundtable.com/assets/research-notes/imr32/2011.pdf
@@ -70,28 +70,29 @@ made up of a dart identifier (the intersected dart) as well as the relative posi
At the same time, vertices are labeled as one of three types: `Regular`, `PoI`, or `Intersec`. This is used by the
processing logic of the next steps.
-### Step 2 - Insert Intersection Vertices
+### Step 2 - Transform data for step 3 and 4
-Intersection information is sorted **per intersected edge** for processing and mapped back to its initial storage.
+This is an intermediate step which enables better implementation of the next two step. It roughly
+results in:
-The workflow follows these steps:
-- Group intersection data per edge
-- Adjust the relative position value to match the edge's direction instead of the dart's
-- Per edge:
- - Sort intersections by relative position along the edge (required for correct insertion)
- - Insert the vertices / darts (call to `CMap2::splitn_edge`)
-- Link back the inserted darts to their corresponding intersection
+- the parallelization of step 3
+- the decorrelation of step 3 from step 4, making their concurrent execution posssible
-There are two main reasons for this step to exist as its own:
-- Algorithm modularity; By having a dedicated section to process intersections, we can more easily introduce more
- intersection variants (corners? tangents?).
-- Handling cases where a single edge is intersected multiple time by the geometry; Since we assume that we're
- intersecting one of the grid's original dart, we can't insert vertices on the fly without creating issues related to
- execution path.
+This is achieved by:
-### Step 3 - Filter & Rebuild Segment Data
+1. grouping intersection data (obtained from step 1) per edge
+2. pre-allocating darts for step 2
+3. computing each intersection's corresponding new dart
-Given the list of segments computed during the previous step, we must rebuild new segments where both ends are either
+### Step 3 - Insert Intersection Vertices
+
+Given intersection information per edge (step 2 `1.`), and pre-allocated darts (step 2 `2.`), we iterate
+through edges, building intersections into the map. Thanks to the `splitn_edge` implementation and dart
+pre-allocation, processing edges should be an embarassingly parallel section.
+
+### Step 4 - Filter & Rebuild Segment Data
+
+Given information computed at step 2 `3.`, we can rebuild new segments where both ends are either
points of interest or intersections. This corresponds to building segments using the following vertices:
@@ -108,7 +109,7 @@ This can be done in two substeps:
Using a set of data made up of starting intersection, ending intersection, and (optional) intermediates, we can build
edges into the final 2-map.
-### Step 4 - Insert Segments
+### Step 5 - Insert Segments
Given the data built up at the last step, we can proceed with insertion into the map. At this point, only darts linking
the first intersection to the following vertex need to be added to the map.
@@ -215,4 +216,4 @@ These steps are followed:
Insertion of new edges with one intermediate
-
\ No newline at end of file
+
diff --git a/user-guide/src/kernels/splits.md b/user-guide/src/kernels/splits.md
new file mode 100644
index 00000000..38579712
--- /dev/null
+++ b/user-guide/src/kernels/splits.md
@@ -0,0 +1,26 @@
+# Splits
+
+---
+
+We refer to "splits" or "splitting functions" when talking about higher-level routines involving the split of
+a geometrical cell (e.g. an edge/1-cell). They are implemented in [this](../../honeycomb_kernels/splits/index.html)
+module.
+
+## No-allocation variants
+
+To avoid small, repetitive call to system allocator, we implement no-allocation variants of these routines.
+Instead of adding darts to the map in the function, the variants take an additional argument: a slice of
+free darts. These darts are then used to apply modifications to the map.
+
+This, coupled with grouped pre-allocation, allows to significantly reduce the number of allocator calls in programs.
+
+## Functions
+
+### Edges
+
+Two splitting functions are implemented over edges, each having a no-allocation variant:
+
+- `split_edge` / `split_edge_noalloc`: split an edge in two, inserting one new vertex in the map
+- `splitn_edge` / `splitn_edge_noalloc`: split an edge into `n+1` segments, `n` being the number of new
+ intermediate vertices
+
diff --git a/user-guide/src/kernels/triangulations.md b/user-guide/src/kernels/triangulations.md
new file mode 100644
index 00000000..b39272c2
--- /dev/null
+++ b/user-guide/src/kernels/triangulations.md
@@ -0,0 +1,27 @@
+# Polygon triangulation
+
+---
+
+We implement two functions for polygon triangulation. These are not meshing functions; our goal with
+these is to cut existing cells of an irregular mesh into triangular cells.
+
+With consideration to the above, we implement two polygon triangulation methods: *fanning*, and *ear-clipping*.
+Both implementations are designed to operate in parallel; they take pre-allocated darts as argument and do not
+create any contention over data as long as two calls are not made on the same face (2-cell).
+
+
+## Fanning
+
+Two versions of this algorithm are implemented:
+
+The first implementation is a defensive one where the function actively search for a valid vertex to fan from.
+
+The second implementation assume the cell is convex; it fans the polygon from its first vertex. Convexity is not
+checked, so use this only if you know all your cells fit the requirements!
+
+
+## Ear-clipping
+
+This method isn't algorithmically efficient, but we operate on small cells, and it covers our needs: it is a potential
+fallback for non-fannable polygons without holes.
+
diff --git a/user-guide/src/project-structure/honeycomb-benches.md b/user-guide/src/project-structure/honeycomb-benches.md
index 680d5655..ae29c18c 100644
--- a/user-guide/src/project-structure/honeycomb-benches.md
+++ b/user-guide/src/project-structure/honeycomb-benches.md
@@ -1 +1,87 @@
# Benchmarks
+
+## Binaries
+
+```shell
+cargo run --profile=profiling --bin= --
+```
+
+#### `builder`
+
+Generate a grid using `GridDescriptor` w.r.t. the specified arguments.
+Arguments are the following: ``, with:
+
+- ``: number of cell of the grid along the X axis
+- ``: number of cell of the grid along the Y axis
+- ``: if non-empty, the program will build a grid of
+ tris instead of quads
+
+
+#### `grisubal`
+
+Run the `grisubal` algorithm w.r.t. the specified arguments. Arguments are the following:
+``, with:
+
+- ``: input geometry, passed as a VTK file input
+- ``: length of the cells of the overlay grid along the X axis
+- ``: length of the cells of the overlay grid along the Y axis
+- ``: `left` to clip the left side of the boundary, `right` the right
+ side, anything else is a no-op
+
+
+## Benchmarks
+
+```shell
+cargo bench --bench
+```
+
+The following benchmarks are available:
+
+| Name | Type | Source file |
+|------------------------------|---------------|--------------------------------------|
+| `builder` | Criterion | `benches/builder/time.rs` |
+| `builder-grid-size` | Criterion | `benches/builder∕grid_size.rs` |
+| `fetch-icells` | Criterion | `benches/core/cmap2/fetch_icells.rs` |
+| `grisubal` | Criterion | `benches/grisubal/time.rs` |
+| `grisubal_grid_size` | Criterion | `benches/grisubal/grid_size.rs` |
+| `prof-cmap2-basic` | Iai-callgrind | `benches/core/cmap2/basic_ops.rs` |
+| `prof-cmap2-build` | Iai-callgrind | `benches/core/cmap2/constructors.rs` |
+| `prof-cmap2-sewing-unsewing` | Iai-callgrind | `benches/core/cmap2/link_and_sew.rs` |
+| `triangulate_quads` | Criterion | `benches/triangulate/quads.rs` |
+
+A detailed explanation about the purpose of each benchmark is provided at the beginning of their respective source
+files.
+
+
+## Scripts
+
+### Benchmarking
+
+Both scripts provide an interactive menu with four options:
+
+```
+(0) all
+(1) fixed-size profiling
+(2) grid size scaling
+(3) thread number scaling (not yet implmented)
+```
+
+#### `builder.py`
+
+The script aggregates metrics about the grid building routines used by `CMapBuilder`. Data is collected from Criterion
+(runtime benchmarks), perf (CPU profiling), flamegraph (visualization), heaptrack (memory analysis), and across
+different grid sizes (from 128x128 to 8192x8192).
+
+#### `grisubal.py`
+
+The script aggregates metrics about the `grisubal` kernel. Data is collected from Criterion (runtime benchmarks),
+perf (CPU profiling), flamegraph (visualization), and heaptrack (memory analysis). Additionally, internal timers
+are implemented to measure time-per-sections of the algorithm. Measurements are done across different grid
+granularities (from `0.1` to `1.0` in `0.1` increments).
+
+### Plotting
+
+#### `grisubal_plot.py`
+
+This script generates a pie chart from per-section timings sampled by the `grisubal.py` script.
+
diff --git a/user-guide/src/project-structure/honeycomb-examples.md b/user-guide/src/project-structure/honeycomb-examples.md
index df635b4e..fe3d9030 100644
--- a/user-guide/src/project-structure/honeycomb-examples.md
+++ b/user-guide/src/project-structure/honeycomb-examples.md
@@ -1 +1,18 @@
# Examples
+
+```shell
+# Run a specific example
+cargo run --example
+```
+
+The following examples are available:
+
+| Name | Source file |
+|----------------|------------------------------------|
+| `grisubal` | `examples/kernels/grisubal.rs` |
+| `io_read` | `examples/io/read.rs` |
+| `io_write` | `examples/io/write.rs` |
+| `memory_usage` | `examples/memory_usage/compute.rs` |
+| `render` | `examples/render.rs` |
+
+Note that the `memory_usage` example is deprecated and should be updated along with its plotting script.
diff --git a/user-guide/src/project-structure/honeycomb-guide.md b/user-guide/src/project-structure/honeycomb-guide.md
deleted file mode 100644
index 023ee7c7..00000000
--- a/user-guide/src/project-structure/honeycomb-guide.md
+++ /dev/null
@@ -1 +0,0 @@
-# User guide
diff --git a/user-guide/src/project-structure/others.md b/user-guide/src/project-structure/others.md
index a0438474..5fccd54d 100644
--- a/user-guide/src/project-structure/others.md
+++ b/user-guide/src/project-structure/others.md
@@ -4,75 +4,22 @@
## Benchmarks
-**honeycomb-benches** is a Rust crate used to group benchmarking routines of the Rust code. Benchmarks are defined in
-this crate using the [criterion][CRITERION] and [iai-callgrind][IAI] crates.
+**honeycomb-benches** is the crate used to group benchmarking routines of the Rust code. It contains:
-Note that the **iai-callgrind** benchmarks require their runner to be installed as well as Valgrind. Refer to the
-crate's [README][IAIRM] for detailed instructions.
-
-### Usage
-
-You can run benchmarks using the following commands:
-
-```shell
-# Run all benchmarks
-cargo bench --benches
-
-# Run a specific benchmark
-cargo bench --bench
-```
-
-The following benchmarks are available:
-
-| Name | Type | Source file |
-|------------------------------|---------------|--------------------------------------|
-| `splitsquaremap-init` | Criterion | `benches/splitsquaremap/init.rs` |
-| `splitsquaremap-shift` | Criterion | `benches/splitsquaremap/shift.rs` |
-| `squaremap-init` | Criterion | `benches/squaremap/init.rs` |
-| `squaremap-shift` | Criterion | `benches/squaremap/shift.rs` |
-| `squaremap-splitquads` | Criterion | `benches/squaremap/split.rs` |
-| `prof-cmap2-basic` | Iai-callgrind | `benches/core/cmap2/basic_ops.rs` |
-| `prof-cmap2-build` | Iai-callgrind | `benches/core/cmap2/constructors.rs` |
-| `prof-cmap2-sewing-unsewing` | Iai-callgrind | `benches/core/cmap2/link_and_sew.rs` |
-
-A detailed explanation about the purpose of each benchmark is provided at the beginning of their respective source
-files. As a rule of thumb, the **iai-callgrind** benchmarks cover individual methods of the structure while
-**criterion** benchmarks cover higher level computations.
+- binaries used to profile code and kernels
+- benchmarks implemented using the [criterion][CRITERION] crate
+- scritps used to aggregate and (partially) process results of both
[CRITERION]: https://github.com/bheisler/criterion.rs
-[IAI]: https://github.com/iai-callgrind/iai-callgrind
-
-[IAIRM]: https://github.com/iai-callgrind/iai-callgrind?tab=readme-ov-file#installation
---
## Examples
-**honeycomb-examples** is a Rust crate used to group examples & snippets illustrating the crates' usage.
+**honeycomb-examples** is the crate used to group examples & snippets illustrating possible usages. It also
+contains sample VTK files to ensure examples and benchmarks can run out-of-the-box.
-### Usage
-
-You can run examples using the following command:
-
-```shell
-# Run a specific example
-cargo run --example
-```
-
-The following examples are available:
-
-| Name | Description |
-|----------------|--------------------------------------------------------------------------------------------------------------------|
-| `io_read` | Initialize and render a map from the VTK file passed to the command line. |
-| `io_write` | Serialize the map that is built by the `squaremap_split_some` benchmark. |
-| `memory_usage` | Outputs the memory usage of a given map as three *csv* files. Use `memory_usage.py` to generate charts from those. |
-| `render` | Render a map representing a simple orthogonal grid. |
-
-### Scripts
-
-- `memory_usage.py` - **requires matplotlib** - Plots pie charts using a *csv* file produced by
- a size method of CMap2.
---
@@ -84,23 +31,17 @@ found in the code documentation.
### Building
-You can generate this documentation locally using **mdbook** and **cargo doc**:
+You can generate this documentation locally using **mdbook**:
```shell
-mdbook serve --open -d ../target/doc/ user-guide/ &
-cargo doc --all --no-deps
+mdbook serve --open user-guide/
```
### Additional Information
-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`.
-
A few observations on writing documentation using **mdbook**:
- If you edit the user guide's content, you will have to generate the rust doc again as mdbook remove all files of its
target folder at each update.
-- When linking to a folder containing an `index.html` file, be sure to include the last `/` in the name of the folder
- if you don't name the index file directly. Not including that last character seems to break in-file linking of the
- local version.
\ No newline at end of file
+- Linking to `html` files (and not markdown) has a varying level of success when working locally. Your browser may or
+ may not like links toward folders instead of explicit `index.html`.
diff --git a/user-guide/src/project-structure/published.md b/user-guide/src/project-structure/published.md
index 0f496d74..7d9f3af9 100644
--- a/user-guide/src/project-structure/published.md
+++ b/user-guide/src/project-structure/published.md
@@ -9,7 +9,7 @@ published), as well as specialized crates **honeycomb-core**, **honeycomb-kernel
## honeycomb
-**honeycomb** is the main crate provided to user and serve as the entrypoint for combinatorial map usage. It is
+**honeycomb** is the main crate provided to users and serve as the entrypoint for combinatorial map usage. It is
exclusively made up of re-exports from the core, kernels and render crate to provide a clean, all-in-one dependency.
### Usage
@@ -18,13 +18,10 @@ At the moment, the `honeycomb` name is not available on crates.io; this means th
the dependency using the git repository:
```toml
-# Cargo.toml
-
-[dependencies]
+# [dependencies]
honeycomb = { git = "https://github.com/LIHPC-Computational-Geometry/honeycomb" }
```
-The documentation is available [here](../honeycomb/).
---
@@ -33,21 +30,22 @@ The documentation is available [here](../honeycomb/).
**honeycomb-core** is a Rust crate that provides basic structures and operations for combinatorial map manipulation.
This includes map structures, methods implementation, type aliases and geometric modeling for mesh representation.
-### Usage
-
-A quickstart example encompassing most features is provided for the following structures:
-
-- [CMap2](../honeycomb_core/struct.CMap2.html)
-- [Vector2](../honeycomb_core/struct.Vector2.html)
-- [Vertex2](../honeycomb_core/struct.Vertex2.html)
-- [CMapBuilder](../honeycomb_core/cmap/struct.CMapBuilder.html)
-
-Optional features can be enabled when using this crate:
+### Implemented features
-- `utils` -- provides additionnal implementations for map generation, benchmarking & debugging
-- `io` -- provides a function and a method for building maps from VTK meshes and vice versa
+- a builder structure to handle map creation: `CMapBuilder`.
+- 2D combinatorial maps, usable in concurrent contexts: `CMap2`. this includes:
+ - all regular operations (sew, unsew, beta images, ...),
+ - a custom embedding logic to associate vertices and attributes to darts.
+- 2D orbit computation: `Orbit2`.
+- abstractions over attributes, to allow arbitrary items binding to the map using the
+ same embedding logic as vertices:
+ - `AttributeBind` & `AttributeUpdate` traits,
+ - `AttrSparseVec` as a predefined collection for attributes,
+ - additional traits to describe custom collection structures.
+- geometry primitives:
+ - `Vector2` / `Vertex2`,
+ - `Vector3` / `Vertex3`.
-Both of these are enabled by default in the **honeycomb** crate.
---
@@ -61,20 +59,16 @@ combinatorial maps. These implementations have multiple purposes:
3. Stressing the data structure, to identify its advantages and its pitfalls in a meshing context
4. Testing for more unwanted behaviors / bugs
-Explanations provided on this page focus on the overall workflow of algorithms; Implementation-specific details and
+Explanations provided in this guide focus on the overall workflow of algorithms; Implementation-specific details and
hypothesis are listed in the documentation of the crate.
-### Usage
-
-The documentation is available [here](../honeycomb_kernels/).
-
-### Algorithms
+### Implemented algorithms
-**Grisubal**, short for **GRId SUBmersion ALgorithm**, is a mesh generation algorithm inspired by [Morph][IMR-RN].
-The mesh is built by capturing the input geometry in an overlapping grid, by first computing intersection vertices and
-then rebuild new edges from the captured vertices. This is explained in more details [here](../kernels/grisubal.md).
+- [Directional Vertex Relaxation](../kernels/dvr.md)
+- [Grisubal](../kernels/grisubal.md)
+- [Polygon triangulations](../kernels/triangulations.md)
+- [Cell splits](../kernels/splits.md)
-[IMR-RN]: https://internationalmeshingroundtable.com/assets/research-notes/imr32/2011.pdf
---
@@ -87,8 +81,7 @@ significantly easier way than reading internal data would.
### Usage
-Use the [App](../honeycomb_render/struct.App.html) structure to render a given combinatorial map. You may need to run
-the program in `release` mode to render large maps. All items used to build that tool are kept public to allow users
+Use the [App](../../honeycomb_render/struct.App.html) structure to render a given combinatorial map. **You may need to run
+the program in `release` mode to render large maps**. All items used to build that tool are kept public to allow users
to customize the render logic (e.g. to render a specific attribute).
-The documentation is available [here](../honeycomb_render/).
diff --git a/user-guide/src/project-structure/workspace.md b/user-guide/src/project-structure/workspace.md
index fbb6e4d6..d4c68f74 100644
--- a/user-guide/src/project-structure/workspace.md
+++ b/user-guide/src/project-structure/workspace.md
@@ -8,13 +8,13 @@ examples or this guide.
## Published crates
-- [honeycomb](honeycomb.md) *Main crate*
-- [honeycomb-core](honeycomb-core.md) *Core definitions and tools for combinatorial map implementation*
-- [honeycomb-kernels](honeycomb-kernels.md) *Meshing kernel implementations using combinatorial maps*
-- [honeycomb-render](honeycomb-render.md) *Visualization tool for combinatorial maps*
+- [honeycomb](../../honeycomb/index.html) *Main crate*
+- [honeycomb-core](../../honeycomb_core/index.html) *Core definitions and tools for combinatorial map implementation*
+- [honeycomb-kernels](../../honeycomb_kernels/index.html) *Meshing kernel implementations using combinatorial maps*
+- [honeycomb-render](../../honeycomb_render/index.html) *Visualization tool for combinatorial maps*
## Other content
-- [honeycomb-benches](honeycomb-benches.md) *Benchmarks of the main map structures and methods*
-- [honeycomb-examples](honeycomb-examples.md) *Examples of usage of the project's features*
-- [user guide](honeycomb-guide.md) *Source files of the user guide*
\ No newline at end of file
+- [honeycomb-benches](../../honeycomb_benches/index.html) *Benchmarks of the main map structures and methods*
+- [honeycomb-examples](../../honeycomb_examples/index.html) *Examples of usage of the project's features*
+- [user guide](../index.md) *Source files of the user guide*
