From 6eb30dbd5402a4e28668b7bcfc783216c74baf92 Mon Sep 17 00:00:00 2001 From: imrn99 <95699343+imrn99@users.noreply.github.com> Date: Thu, 16 Jul 2026 17:15:33 +0200 Subject: [PATCH 1/8] doc: update STM page --- user-guide/src/definitions/stm.md | 57 +- user-guide/src/images/attribute_merge.svg | 10 - user-guide/src/images/cutedge-resolution.svg | 505 +++++ .../src/images/cutedge-steps-with-ops.svg | 1975 +++++++++++++++++ 4 files changed, 2511 insertions(+), 36 deletions(-) delete mode 100644 user-guide/src/images/attribute_merge.svg create mode 100644 user-guide/src/images/cutedge-resolution.svg create mode 100644 user-guide/src/images/cutedge-steps-with-ops.svg diff --git a/user-guide/src/definitions/stm.md b/user-guide/src/definitions/stm.md index f6eee4c8b..0bcb49e61 100644 --- a/user-guide/src/definitions/stm.md +++ b/user-guide/src/definitions/stm.md @@ -1,40 +1,40 @@ # Transactional memory -**This content has been copy-pasted from the previous guide. It is up-to-date but should be improved -at some point.** - --- +Meshing operations demand guarantees for coordinated access across sets of variables. They may also +be composed of multiple steps that should not be interrupted, or where intermediate mesh state may +be invalid. + +
+ EdgeCutSteps +
Edge cut operation with detailed steps.
+
+ +For example, an edge cut in a triangular mesh is defined by the insertion of a vertex on +an existing edge, before the creation of two new edges that cut across the original adjacent +triangles. After the first vertex insertion, and before both edges creation, the mesh actually +contains quadrangular cells. This is a state that should not be visible to other threads, nor should +it be a final state. + ## Needs +In order to guarantee validity, we must ensure that these intermediate, incorrect states aren’t +used by another thread to compute an erroneous result, i.e., that all changes made in a thread +appear at once to others. To obtain our final system, we worked incrementally on a synchronization +policy choice. + Rust's ownership semantics require us to add synchronization mechanism to our structure if we want to use it in concurrent contexts. Using primitives such as atomics and mutexes would be enough to get programs to compile, but it would respectively yield an incorrect or impractical implementation: -- Atomics give guarantees on instructions interleaving for a single given variable, they do not give - any guarantees for instructions affecting different atomic variables. -- Mutexes (and similar locks, e.g. RWLocks) can be used to create guarantees when accessing multiple - variable: for example, we can write an operation that does not progress until all of the used data - is locked. However, locks are error-prone, have very poor composability. +- Atomics give guarantees on instructions interleaving for a single given variable, these guarantees + cannot be extended to a set of accesses across different variables. +- Mutexes (and similar locks, e.g. RWLocks) can be used to implement greater synchronization + coordination: for example, we can write an operation that does not progress until all of the used + data is locked. However, locks are error-prone, have very poor composability. Issues that come + with those grow along the number of locks used. -The nature of meshing operations makes both mechanisms very unpractical. They are complex, access -many variables, and are often comprised of multiple steps. For example, the following operation is -executed on all affected attributes of a sew: - -
- Merge Operation -
Attribute merging operation. This occurs at each sew operation.
-
- -Because the map can go through invalid intermediate states during a single operation, we need to -ensure another thread will not use one of these as the starting point for another operation. This -rules out fine-grained atomics. - -The sew operation is the main method used to create new connectivities in the map. This means that -most high-level meshing operations will call this method multiple times. If these meshing operations -require locking all of the variables to ensure correct execution, the locks must be returned or -exposed to the user so that he can unlock them at the right time. Manual lock management is -error-prone, and becomes impossible in practice for complex meshing operations. ## Software Transactional Memory @@ -43,6 +43,11 @@ We choose to use Software Transactional Memory (STM) to handle high-level synchr the structure. Unlike locks, STM has great composability and allows users of the crate to easily define pseudo-atomic segments in their own algorithms. +
+ EdgeCutSTM +
Edge cut operation with detailed steps.
+
+ Exposing an API that allows users to handle synchronization also means that the implementation isn't bound to a given parallelization framework. Instead of relying on predefinite parallel routines (e.g. a provided `parallel_for` on given cells), the structure can be used to implement diff --git a/user-guide/src/images/attribute_merge.svg b/user-guide/src/images/attribute_merge.svg deleted file mode 100644 index 1442bc7e1..000000000 --- a/user-guide/src/images/attribute_merge.svg +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - NoneNoneNoneNoneNoneNoneNoneNoneNoneSome(v)Some(v)Some(v)Some(v)Some(v)0 d1 d2 d3 d4 d5 dn0 d1 d2 d3 d4 d5 dn... ... ...... ... ...AttrSparseVec(init)AttrSparseVec(final)MERGE d3 <= d2, d4.remove(d2).set(d3, v3).remove(d4)AttributeUpdate::merge(v2, v4)v4v3v2Intermediate state where all three entries are NoneNo other ops affecting theseentries should take place here! \ No newline at end of file diff --git a/user-guide/src/images/cutedge-resolution.svg b/user-guide/src/images/cutedge-resolution.svg new file mode 100644 index 000000000..2f0150891 --- /dev/null +++ b/user-guide/src/images/cutedge-resolution.svg @@ -0,0 +1,505 @@ + + + +T2T1T2finishes first - its changes are written to memoryT1finishes after - it fails and retries from the updated data diff --git a/user-guide/src/images/cutedge-steps-with-ops.svg b/user-guide/src/images/cutedge-steps-with-ops.svg new file mode 100644 index 000000000..497344f52 --- /dev/null +++ b/user-guide/src/images/cutedge-steps-with-ops.svg @@ -0,0 +1,1975 @@ + + + +5210135647891112104612781119253146213256412345639871011122-unsew(d1)1-unsew(d1)1-unsew(d2)1-unsew(d4)1-unsew(d5)1-sew(d1,d7)1-sew(d7,d3)1-sew(d2,d8)1-sew(d9,d2)1-sew(d4,d10)1-sew(d10,d6)1-sew(d5,d11)1-sew(d12,d5)2-sew(d1,d12)2-sew(d4,d9)New elements From afac76ad0cd8c094fd882df48ec6311fa4f4d51e Mon Sep 17 00:00:00 2001 From: imrn99 <95699343+imrn99@users.noreply.github.com> Date: Fri, 17 Jul 2026 08:01:33 +0200 Subject: [PATCH 2/8] doc: remove unused images --- user-guide/src/images/grisubal/input.svg | 21 ------------------- user-guide/src/images/grisubal/insertion.svg | 21 ------------------- .../src/images/grisubal/intersec_multiple.svg | 21 ------------------- .../src/images/grisubal/intersec_single.svg | 21 ------------------- .../src/images/grisubal/intersec_types.svg | 21 ------------------- .../src/images/grisubal/left_right_darts.svg | 10 --------- user-guide/src/images/grisubal/step1.svg | 21 ------------------- user-guide/src/images/grisubal/step2.svg | 21 ------------------- user-guide/src/images/grisubal/step3.svg | 21 ------------------- 9 files changed, 178 deletions(-) delete mode 100644 user-guide/src/images/grisubal/input.svg delete mode 100644 user-guide/src/images/grisubal/insertion.svg delete mode 100644 user-guide/src/images/grisubal/intersec_multiple.svg delete mode 100644 user-guide/src/images/grisubal/intersec_single.svg delete mode 100644 user-guide/src/images/grisubal/intersec_types.svg delete mode 100644 user-guide/src/images/grisubal/left_right_darts.svg delete mode 100644 user-guide/src/images/grisubal/step1.svg delete mode 100644 user-guide/src/images/grisubal/step2.svg delete mode 100644 user-guide/src/images/grisubal/step3.svg diff --git a/user-guide/src/images/grisubal/input.svg b/user-guide/src/images/grisubal/input.svg deleted file mode 100644 index f0cb7665a..000000000 --- a/user-guide/src/images/grisubal/input.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/user-guide/src/images/grisubal/insertion.svg b/user-guide/src/images/grisubal/insertion.svg deleted file mode 100644 index a7e768895..000000000 --- a/user-guide/src/images/grisubal/insertion.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - startstartstartstartstartendendendendenddididididi \ No newline at end of file diff --git a/user-guide/src/images/grisubal/intersec_multiple.svg b/user-guide/src/images/grisubal/intersec_multiple.svg deleted file mode 100644 index dfe066282..000000000 --- a/user-guide/src/images/grisubal/intersec_multiple.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - v1v2 \ No newline at end of file diff --git a/user-guide/src/images/grisubal/intersec_single.svg b/user-guide/src/images/grisubal/intersec_single.svg deleted file mode 100644 index aa29da563..000000000 --- a/user-guide/src/images/grisubal/intersec_single.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - v1v2v_dartcycxs*(v2-v1)t*cy \ No newline at end of file diff --git a/user-guide/src/images/grisubal/intersec_types.svg b/user-guide/src/images/grisubal/intersec_types.svg deleted file mode 100644 index 233a6c090..000000000 --- a/user-guide/src/images/grisubal/intersec_types.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - ABC \ No newline at end of file diff --git a/user-guide/src/images/grisubal/left_right_darts.svg b/user-guide/src/images/grisubal/left_right_darts.svg deleted file mode 100644 index 93a001e46..000000000 --- a/user-guide/src/images/grisubal/left_right_darts.svg +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/user-guide/src/images/grisubal/step1.svg b/user-guide/src/images/grisubal/step1.svg deleted file mode 100644 index 67a576377..000000000 --- a/user-guide/src/images/grisubal/step1.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/user-guide/src/images/grisubal/step2.svg b/user-guide/src/images/grisubal/step2.svg deleted file mode 100644 index f7c65d86a..000000000 --- a/user-guide/src/images/grisubal/step2.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/user-guide/src/images/grisubal/step3.svg b/user-guide/src/images/grisubal/step3.svg deleted file mode 100644 index 0cc2b5688..000000000 --- a/user-guide/src/images/grisubal/step3.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - \ No newline at end of file From 9e216581d1dbdc68fe10465cc4c0fbee244f9df7 Mon Sep 17 00:00:00 2001 From: imrn99 <95699343+imrn99@users.noreply.github.com> Date: Fri, 17 Jul 2026 08:09:22 +0200 Subject: [PATCH 3/8] doc: update link to IMR paper --- docs/index.html | 2 +- user-guide/src/definitions/stm.md | 2 ++ user-guide/src/index.md | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/index.html b/docs/index.html index ba7aac9bd..11ba49748 100644 --- a/docs/index.html +++ b/docs/index.html @@ -20,7 +20,7 @@

Related works

diff --git a/user-guide/src/definitions/stm.md b/user-guide/src/definitions/stm.md index 0bcb49e61..2d6853d74 100644 --- a/user-guide/src/definitions/stm.md +++ b/user-guide/src/definitions/stm.md @@ -35,6 +35,8 @@ get programs to compile, but it would respectively yield an incorrect or impract data is locked. However, locks are error-prone, have very poor composability. Issues that come with those grow along the number of locks used. +We detail how these usual mechanisms fail to provide the guarantees we need in one of +[our paper](https://epubs.siam.org/doi/10.1137/1.9781611979138.8). ## Software Transactional Memory diff --git a/user-guide/src/index.md b/user-guide/src/index.md index a50192e5e..26e33472c 100644 --- a/user-guide/src/index.md +++ b/user-guide/src/index.md @@ -19,7 +19,7 @@ The goal is to converge towards a (or multiple) structure(s) which could be used experiment with parallel meshing algorithm, specifically targeting many-core architectures. More extensive explanations regarding our needs and design choices of this solution is included in -[one of our paper](https://drive.google.com/file/d/1D_SLFSMMlBc2ycZURztTXnwX6jN0A8r8/view). +[one of our paper](https://epubs.siam.org/doi/10.1137/1.9781611979138.8). ## Requirements From 69fa1fa7f4c430d0c6fc998dc9cbc293925622f2 Mon Sep 17 00:00:00 2001 From: imrn99 <95699343+imrn99@users.noreply.github.com> Date: Fri, 17 Jul 2026 08:30:56 +0200 Subject: [PATCH 4/8] doc: add `Resources` page --- user-guide/src/SUMMARY.md | 2 +- user-guide/src/definitions/resources.md | 34 +++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 user-guide/src/definitions/resources.md diff --git a/user-guide/src/SUMMARY.md b/user-guide/src/SUMMARY.md index de1ac7884..cc9c17334 100644 --- a/user-guide/src/SUMMARY.md +++ b/user-guide/src/SUMMARY.md @@ -11,7 +11,7 @@ - [Element insertion and deletion](./definitions/ops.md) - [Sewing operation](./definitions/sews.md) - [Transactional memory](./definitions/stm.md) -- [Resources]() +- [Resources](./definitions/resources.md) # User guide diff --git a/user-guide/src/definitions/resources.md b/user-guide/src/definitions/resources.md new file mode 100644 index 000000000..b3d5ec50b --- /dev/null +++ b/user-guide/src/definitions/resources.md @@ -0,0 +1,34 @@ +# Resources + +--- + +This page groups a few references mentionned in this book, as well as others which help understand +all mechanism leveraged in the framework. + +## Rust + +- The Rust Programming Language [book](https://doc.rust-lang.org/book/). +- Rust by Example [book](https://doc.rust-lang.org/rust-by-example/) +- Rust's standard library [documentation](https://doc.rust-lang.org/stable/std/) + +## Combinatorial Maps + +- G. Damiand and P. Lienhardt, _Combinatorial Maps: Efficient Data Structures for Computer Graphics + and Image Processing_, A K Peters/CRC Press, Sept. 2014. +- G. Damiand and M. Teillaud, _A Generic Implementation of dD Combinatorial Maps in CGAL_, Procedia + Engineering, 82 (2014), pp. 46–58. +- P. Kraemer, L. Untereiner, T. Jund, S. Thery, and D. Cazier, _CGoGN: N-dimensional Meshes with + Combinatorial Maps_, in Proceedings of the 22nd International Meshing Roundtable, J. Sarrate and + M. Staten, eds., Springer International Publishing, Cham, Oct. 2013, pp. 485–503. + +## Transactional Memory + +- Dedicated STM chapter of _Real World Haskell_ for + a quick intuitive introduction +- _Software Transactional Memory_, Shavit et al., 1997 +- _On the correctness of transactional memory_, Guerraoui et al., 2008 + +## Algorithms + +References are given on a case by case basis when it comes to algorithms. Some were loosely adapted +from references while others were direct re-implementations. From 5123513fc292021692e63e09958ed37df12ccaa2 Mon Sep 17 00:00:00 2001 From: imrn99 <95699343+imrn99@users.noreply.github.com> Date: Fri, 17 Jul 2026 10:18:46 +0200 Subject: [PATCH 5/8] doc: update existing dev guide pages --- user-guide/src/definitions/resources.md | 4 +-- user-guide/src/dev-guide/contributing.md | 5 ++- user-guide/src/dev-guide/library.md | 32 +++++++++---------- user-guide/src/dev-guide/project-structure.md | 14 +++----- 4 files changed, 23 insertions(+), 32 deletions(-) diff --git a/user-guide/src/definitions/resources.md b/user-guide/src/definitions/resources.md index b3d5ec50b..101c0cf55 100644 --- a/user-guide/src/definitions/resources.md +++ b/user-guide/src/definitions/resources.md @@ -2,7 +2,7 @@ --- -This page groups a few references mentionned in this book, as well as others which help understand +This page groups a few references mentioned in this book, as well as others which help understand all mechanism leveraged in the framework. ## Rust @@ -31,4 +31,4 @@ all mechanism leveraged in the framework. ## Algorithms References are given on a case by case basis when it comes to algorithms. Some were loosely adapted -from references while others were direct re-implementations. +from references while others were direct re-implementations. diff --git a/user-guide/src/dev-guide/contributing.md b/user-guide/src/dev-guide/contributing.md index 92cc50234..6a45eb773 100644 --- a/user-guide/src/dev-guide/contributing.md +++ b/user-guide/src/dev-guide/contributing.md @@ -1,8 +1,5 @@ # Contributing -**This content has been copy-pasted from the previous guide. It is up-to-date but should be improved -at some point.** - --- Contributions are welcome and accepted as pull requests on [GitHub][GH]. Feel free to use issues @@ -53,10 +50,12 @@ Note that a most of the code possess documentation, including private modules / the complete documentation by using the following instructions: ```shell +# Book mdbook serve --open user-guide/ ``` ```shell +# Rust API cargo +nightly doc --all --all-features --no-deps --document-private-items ``` diff --git a/user-guide/src/dev-guide/library.md b/user-guide/src/dev-guide/library.md index f09b4f24c..7cdecf657 100644 --- a/user-guide/src/dev-guide/library.md +++ b/user-guide/src/dev-guide/library.md @@ -1,12 +1,8 @@ # Libraries -**This content has been copy-pasted from the previous guide. It is up-to-date but should be improved -at some point.** - --- -Several crates of this project are published on the registry _crates.io_: the main crate, **honeycomb** (not yet -published), as well as specialized crates **honeycomb-core**, **honeycomb-kernels**, and **honeycomb-render**. +The repository hosts four crates. ## honeycomb @@ -21,6 +17,7 @@ the dependency using the git repository: # [dependencies] honeycomb = { git = "https://github.com/LIHPC-Computational-Geometry/honeycomb" + # tag = "X.X.X" } ``` @@ -32,7 +29,7 @@ The following features are available: - a builder structure to handle map creation: `CMapBuilder`. - 2D and 3D combinatorial maps, usable in concurrent contexts: `CMap2`/`CMap3`. this includes: - - all regular operations (sew, unsew, beta images, ...), + - all regular operations (sew, unsew, beta image accesses, ...), - a custom embedding logic to associate vertices and attributes to darts. - abstractions over attributes, to allow arbitrary items binding to the map using the same embedding logic as vertices: @@ -49,23 +46,24 @@ The following features are available: **honeycomb-kernels** is a Rust crate that provides implementations of meshing kernels using the core crate's combinatorial maps. These implementations have multiple purposes: -1. Writing code using n-maps from a user's perspective +1. Writing code using \\(N\\)-maps from a user's perspective 2. Covering a wide range of operations, with routines that are more topology-heavy / geometry-heavy / balanced 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 in this guide focus on the overall workflow of algorithms; Implementation-specific details and -hypothesis are listed in the documentation of the crate. - +When discussing algorithms, explanations provided in this guide focus on the high-level workflow; +Implementation-specific details and hypothesis are kept to the documentation of the crate. ## honeycomb-render -**honeycomb-render** is a Rust crate that provides a simple visualization framework to allow the user to render their -combinatorial map. It is designed to be used directly in the code by reading data through a reference to the map (as -opposed to a binary that would read serialized data). This render tool can be used to quickly debug algorithm results -by looking at the resulting structure instead of reading hard-to-interpret numerical data. +**honeycomb-render** is a Rust crate that provides a simple visualization framework to allow the +user to render their combinatorial map. It is designed to be used directly in the code by reading +data through a reference to the map (as opposed to a binary that would read serialized data). This +render tool can be used to quickly debug algorithm results by looking at the resulting structure +instead of reading hard-to-interpret raw data. -Use the [exported functions](../../honeycomb_render/index.html) 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). +Use the [exported functions](../../honeycomb_render/index.html) 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). diff --git a/user-guide/src/dev-guide/project-structure.md b/user-guide/src/dev-guide/project-structure.md index a22240a27..dfed8c3a3 100644 --- a/user-guide/src/dev-guide/project-structure.md +++ b/user-guide/src/dev-guide/project-structure.md @@ -1,15 +1,9 @@ # Project structure -**This content has been copy-pasted from the previous guide. It is up-to-date but should be improved -at some point.** - --- -The project root is organized using Cargo workspaces at the moment. This may change when other languages are -introduced to the project. - -The [repository][GH] hosts both published crates (usable content) as well as complementary content such as benchmarks, -examples or this guide. +The project root is organized using Cargo workspaces. The [repository][GH] hosts both published +crates (libraries) as well as complementary content such as benchmarks, examples or this guide. [GH]: https://github.com/LIHPC-Computational-Geometry/honeycomb @@ -23,5 +17,5 @@ The following libraries are available: The repository also hosts: - The `applications` crate, which contains a collection of algorithms which are used as benchmarks - and/or examples -- This book's source files, available in the `user-guide` directory + and/or examples. +- This book's source files, available in the `user-guide` directory. From a7b30087b18bcff08a58f4418b0950e0433f76c0 Mon Sep 17 00:00:00 2001 From: imrn99 <95699343+imrn99@users.noreply.github.com> Date: Fri, 17 Jul 2026 11:41:09 +0200 Subject: [PATCH 6/8] doc: add `Applications` page --- user-guide/src/SUMMARY.md | 2 +- user-guide/src/dev-guide/apps.md | 92 ++ user-guide/src/images/cutedge-attributes.svg | 965 ++++++++++++ user-guide/src/images/grid-gen.svg | 1406 ++++++++++++++++++ 4 files changed, 2464 insertions(+), 1 deletion(-) create mode 100644 user-guide/src/images/cutedge-attributes.svg create mode 100644 user-guide/src/images/grid-gen.svg diff --git a/user-guide/src/SUMMARY.md b/user-guide/src/SUMMARY.md index cc9c17334..2c095b1b0 100644 --- a/user-guide/src/SUMMARY.md +++ b/user-guide/src/SUMMARY.md @@ -26,7 +26,7 @@ - [Contributing](./dev-guide/contributing.md) - [Project structure](./dev-guide/project-structure.md) - [Library](./dev-guide/library.md) - - [Applications]() + - [Applications](./dev-guide/apps.md) # Code examples diff --git a/user-guide/src/dev-guide/apps.md b/user-guide/src/dev-guide/apps.md index 598ebba32..550c58a30 100644 --- a/user-guide/src/dev-guide/apps.md +++ b/user-guide/src/dev-guide/apps.md @@ -1 +1,93 @@ # Applications + +--- + +The `applications` crate contains multiple binaries which serve as benchmarks and examples for the +library. The following targets are defined: + +| Algorithm | Target binary | Dimension | +| ------------------------------------ | ---------------------- | --------- | +| Delaunay triangulation | `incremental-delaunay` | 3D | +| Edge cut | `cut-edges` | 2D | +| Overlay grid (intersection-based) | `grisubal` | 2D | +| Overlay grid (refinement-based) | `overlay-grid` | 2D | +| Parameterized grid generation | `generate-grid` | 2D and 3D | +| Polygon triangulation | `triangulate` | 2D | +| Remeshing pipeline proxy-application | `remesh` | 2D | +| Vertex smooth | `shift-vertices` | 2D | + +Most algorithms work on 2D meshes because the structure was implemented first in 2D. Nonetheless, +the 3D structure is just as polished, and the 3D Delaunay triangulation was the most consequential +algorithm in our optimization process as it highlighted issues that did not appear in 2D. + +Each binary has a documented CLI, which can be printed using the `--help` option. Outputs can be +serialized, and, if the `render` feature is enabled, the output mesh will be displayed at the end +of the execution. + +## Delaunay triangulation + +This is a 3D incremental Delaunay triangulation implementation. It roughly follows the algorithm +presented in _One machine, one minute, three billion tetrahedra_, Marot et al, 2019. We do not +implement boundary recovery, and focus on the benchmarking aspect by sampling point in a box-shaped +domain and inserting them into a first basic triangulation. + +## Edge cut + +This algorithm apply a basic edge cut operation to all edges of the mesh until a target length is +reached. + +
+ EdgeCut +
Edge cut operation. This can be applied to boundary edges, using only three new darts.
+
+ +## Overlay grid + +### Intersection-based + +This mesh generation algorithms uses intersection with an overlaid grid to create a triangular mesh +of a geometry passed as input. + +### Refinement-based + +This mesh generation algorithms uses incremental refinement of an octree and its dualization to +create an hexahedral mesh of the input geometry. + +## Parameterized grid generation + +This is a grid generation algorithm for our structure, i.e., mesh instantiation with pre-definite +values representing a grid. + +
+ GridIndexing +
Dart indexing logic in generated 2D grids. The same approach is applied to 3D grids.
+
+ +Elements of the grid can be indexed in a systematic manner. Thanks to this, we implemented an +efficient parallel version of this algorithm, as well as a GPU version which outperforms the +parallel CPU one. We use the [`cudarc`](https://github.com/chelsea0x3b/cudarc) crate to offload +the value generation to the GPU. + +## Polygon triangulation + +This algorithm allows triangulation of simple 2D polygon using one of two methods: +[ear-clipping](https://en.wikipedia.org/wiki/Polygon_triangulation#Ear_clipping_method) or +[fanning](https://en.wikipedia.org/wiki/Fan_triangulation). The binary triangulates the entire +mesh input, while `honeycomb-kernel` provides the routine call used to triangulate a single cell. + +## Remeshing pipeline proxy-application + +This algorithm is a proxy-application for very common remeshing workflow found in triangle or +tetrahedron meshing. Multiple meshing kernels are applied in a loop until a certain predicate is +satisfied, or for a given number of rounds. + +
+ GridIndexing +
Remeshing loop structure.
+
+ +## Vertex smooth + +We implement two parameterized smoothing algorithm: Laplace smoothing and Taubin smoothing. A +current work in progress includes a GPU-based Jacobi smoother using a Rust-Kokkos interoperability +library. diff --git a/user-guide/src/images/cutedge-attributes.svg b/user-guide/src/images/cutedge-attributes.svg new file mode 100644 index 000000000..671030064 --- /dev/null +++ b/user-guide/src/images/cutedge-attributes.svg @@ -0,0 +1,965 @@ + + + +510461278111925314621325643987101112New elements diff --git a/user-guide/src/images/grid-gen.svg b/user-guide/src/images/grid-gen.svg new file mode 100644 index 000000000..41de2ab05 --- /dev/null +++ b/user-guide/src/images/grid-gen.svg @@ -0,0 +1,1406 @@ + + + +ijd1i, jd3i, j -1d3i, jd1i, j +1d4i, jd2i, jd4i+1, jd2i+1, jd4i, jd1i, jd2i, jd3i, jd2i, jd3i, jd4i, jd1i, jd3i, j-1d4i+1, jd1i, j+1d2i-1, jd1i, jd2i, jd3i, jd4i, jDβ0β1β2 From 3c903ba4fad3f40ece22a7337ba288f87a4a9341 Mon Sep 17 00:00:00 2001 From: imrn99 <95699343+imrn99@users.noreply.github.com> Date: Fri, 17 Jul 2026 11:44:54 +0200 Subject: [PATCH 7/8] doc: update figure list --- user-guide/src/dev-guide/apps.md | 2 +- user-guide/src/images/all-remesh-ops.svg | 1632 ++++++++++++++++++++++ user-guide/src/images/hex.svg | 4 - user-guide/src/images/remesh.svg | 194 --- user-guide/src/images/remesh_loop.svg | 495 ------- user-guide/src/images/tet.svg | 4 - 6 files changed, 1633 insertions(+), 698 deletions(-) create mode 100644 user-guide/src/images/all-remesh-ops.svg delete mode 100644 user-guide/src/images/hex.svg delete mode 100644 user-guide/src/images/remesh.svg delete mode 100644 user-guide/src/images/remesh_loop.svg delete mode 100644 user-guide/src/images/tet.svg diff --git a/user-guide/src/dev-guide/apps.md b/user-guide/src/dev-guide/apps.md index 550c58a30..9f6e74496 100644 --- a/user-guide/src/dev-guide/apps.md +++ b/user-guide/src/dev-guide/apps.md @@ -82,7 +82,7 @@ tetrahedron meshing. Multiple meshing kernels are applied in a loop until a cert satisfied, or for a given number of rounds.
- GridIndexing + GridIndexing
Remeshing loop structure.
diff --git a/user-guide/src/images/all-remesh-ops.svg b/user-guide/src/images/all-remesh-ops.svg new file mode 100644 index 000000000..403bc9a2f --- /dev/null +++ b/user-guide/src/images/all-remesh-ops.svg @@ -0,0 +1,1632 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Cut + + + + Smooth + + Swap + Collapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/user-guide/src/images/hex.svg b/user-guide/src/images/hex.svg deleted file mode 100644 index 873d8b0bb..000000000 --- a/user-guide/src/images/hex.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
23
24
21
22
 \ No newline at end of file diff --git a/user-guide/src/images/remesh.svg b/user-guide/src/images/remesh.svg deleted file mode 100644 index 2e628758a..000000000 --- a/user-guide/src/images/remesh.svg +++ /dev/null @@ -1,194 +0,0 @@ - - - -Overlay gridTriangulateRemeshShapeGridcharacteristicsUnstructuredmeshTriangularmesh diff --git a/user-guide/src/images/remesh_loop.svg b/user-guide/src/images/remesh_loop.svg deleted file mode 100644 index 939479685..000000000 --- a/user-guide/src/images/remesh_loop.svg +++ /dev/null @@ -1,495 +0,0 @@ - - - -RemeshEdge cutVertex relaxationTriangularmeshEdge swapEdge collapse diff --git a/user-guide/src/images/tet.svg b/user-guide/src/images/tet.svg deleted file mode 100644 index 7e13d50fb..000000000 --- a/user-guide/src/images/tet.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - - \ No newline at end of file From 1fbc15bdff1826f50085b51fa86e5b3dbfa63401 Mon Sep 17 00:00:00 2001 From: imrn99 <95699343+imrn99@users.noreply.github.com> Date: Fri, 17 Jul 2026 14:43:56 +0200 Subject: [PATCH 8/8] doc: proofread examples --- user-guide/src/examples/attributes.md | 7 ++----- user-guide/src/examples/serialization.md | 3 --- user-guide/src/examples/smoothing.md | 9 +++------ user-guide/src/examples/snippets/parallel_shift.rs | 6 +++--- 4 files changed, 8 insertions(+), 17 deletions(-) diff --git a/user-guide/src/examples/attributes.md b/user-guide/src/examples/attributes.md index fb5477b09..ddf406996 100644 --- a/user-guide/src/examples/attributes.md +++ b/user-guide/src/examples/attributes.md @@ -1,13 +1,10 @@ # Generic attribute system -**This content has been copy-pasted from the previous guide. It is up-to-date but should be improved -at some point.** - --- The `attributes` module of the core crate provides the necessary tools for to add custom attributes -to given orbits of the map. Each attribute should be uniquely typed (i.e. to type aliases) as the -maps' internal storages use `std::any::TypeId` for identification. +to given orbits of the map. Each attribute should be uniquely typed (i.e. no type aliases) as the +maps' internal storages use `std::any::TypeId` for identification. An attribute struct should implement both `AttributeBind` and `AttributeUpdate`. It can then be added to the map using the dedicated `CMapBuilder` method. This is showcased in n example below, diff --git a/user-guide/src/examples/serialization.md b/user-guide/src/examples/serialization.md index 47309169a..a75a63629 100644 --- a/user-guide/src/examples/serialization.md +++ b/user-guide/src/examples/serialization.md @@ -1,8 +1,5 @@ # (De)Serialization -**This content has been copy-pasted from the previous guide. It is up-to-date but should be improved -at some point.** - --- Our crate implements two different serialization logics. We use a custom format for combinatorial diff --git a/user-guide/src/examples/smoothing.md b/user-guide/src/examples/smoothing.md index 1376b3007..74f054f72 100644 --- a/user-guide/src/examples/smoothing.md +++ b/user-guide/src/examples/smoothing.md @@ -1,8 +1,5 @@ # Parallel Laplace smoothing -**This content has been copy-pasted from the previous guide. It is up-to-date but should be improved -at some point.** - --- In the following routine, we shift each vertex that's not on a boundary to the average of its @@ -22,9 +19,9 @@ The main map structure, `CMap2`, can be edited in parallel using transactions to correctness. In the main computation loop, we use a transaction to ensure each new vertex value is computed from -the current neighbor's values. The errors generated by `read_vertex` and `write_vertex` are used to -(early) detect any changes to the data used in the transaction, here, the list of `neigh` vertices. +the current neighbor's values. The errors generated by `read_vertex_tx` and `write_vertex_tx` are +used to detect any changes to the data used in the transaction, here, the list of `neigh` vertices. -At the end of the transaction block, the commit routine will check again if any used data has been +At the end of the transaction block, the commit routine will check if any used data has been altered. If not, results of the transaction will be validated and written to memory. diff --git a/user-guide/src/examples/snippets/parallel_shift.rs b/user-guide/src/examples/snippets/parallel_shift.rs index a28862ee0..9aa5573bd 100644 --- a/user-guide/src/examples/snippets/parallel_shift.rs +++ b/user-guide/src/examples/snippets/parallel_shift.rs @@ -45,16 +45,16 @@ fn main() { // the transaction will ensure that we do not validate an operation // where inputs have changed due to instruction interleaving between threads // here, it will retry the transaction until it can be validated - atomically(|trans| { + atomically(|tx| { let mut new_val = Vertex2::default(); for v in neigh { - let vertex = map.read_vertex(trans, *v)?.unwrap(); + let vertex = map.read_vertex_tx(tx, *v)?.unwrap(); new_val.0 += vertex.0; new_val.1 += vertex.1; } new_val.0 /= neigh.len() as f64; new_val.1 /= neigh.len() as f64; - map.write_vertex(trans, *vid, new_val) + map.write_vertex_tx(tx, *vid, new_val) }); });