diff --git a/.gitignore b/.gitignore index c39c740f1..44bdcc897 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ +/target -/target \ No newline at end of file +serve_doc.sh +kill_doc.sh \ No newline at end of file diff --git a/README.md b/README.md index 53f752e81..89ea25e4d 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,33 @@ issues, thanks to the language's guarantees. ## Usage +The [user guide][UG] provides an overview of everything available in the +project. It can be generated offline using **mdbook**: + +```shell +# Serve the doc on a local server +mdbook serve --open -d ../target/doc/ honeycomb-guide/ & +cargo doc --all --no-deps +``` + +```shell +# Kill the local server +kill $(pidof mdbook) + +# Without pidof +kill $(ps -e | awk '/mdbook/ {print $1}') +``` + +[UG]: https://lihpc-computational-geometry.github.io/honeycomb/ + +### Rust + +Basic structure are provided in the **honeycomb-core** crate. Its content is listed +in the [user guide][UGHC] and details about its usage can be found in its [Rust documentation][DOCHC] + +[UGHC]: https://lihpc-computational-geometry.github.io/honeycomb/project-structure/honeycomb-core.html +[DOCHC]: https://lihpc-computational-geometry.github.io/honeycomb/honeycomb_core/ + ## Contributing ## License diff --git a/honeycomb-core/src/twomap.rs b/honeycomb-core/src/twomap.rs index 8dd7a5fca..b998003ad 100644 --- a/honeycomb-core/src/twomap.rs +++ b/honeycomb-core/src/twomap.rs @@ -76,7 +76,7 @@ const TWO_MAP_BETA: usize = 3; /// The following example goes over multiple operations on the mesh in order /// to demonstrate general usage of the structure and its methods. /// -/// ![TWOMAP_EXAMPLE](link_to_example_file.svg) +/// ![TWOMAP_EXAMPLE](../../images/TwoMapExample.svg) /// /// Note that the map we operate on has no boundaries. In addition to the different /// operations realized at each step, we insert a few assertions to demonstrate the diff --git a/honeycomb-guide/src/SUMMARY.md b/honeycomb-guide/src/SUMMARY.md index e7bd67003..53326200b 100644 --- a/honeycomb-guide/src/SUMMARY.md +++ b/honeycomb-guide/src/SUMMARY.md @@ -6,6 +6,7 @@ - [Workspace](./project-structure/workspace.md) - [honeycomb-core](./project-structure/honeycomb-core.md) + - [honeycomb-guide](./project-structure/honeycomb-guide.md) # Definitions @@ -15,4 +16,17 @@ - [Beta Functions](./definitions/betaf.md) - [Orbits](./definitions/orbits.md) - [Embedding](./definitions/embedding.md) -- [Basic Operations](./definitions/basicops.md) \ No newline at end of file +- [Basic Operations](./definitions/basicops.md) + - [Add / Remove a dimension](./definitions/changeNdim.md) + - [Add / Remove a free dart](./definitions/changeNdart.md) + - [Sewing operation](./definitions/sew.md) + - [Unsewing operation](./definitions/unsew.md) +- [Advanced Operations](./definitions/advancedops.md) + - [Generic orbit](./definitions/genorbit.md) + - [I-cells computation](./definitions/icells.md) + - [Orientation](./definitions/orientation.md) + +# Examples + +- [TwoMap](./examples/twomap.md) + diff --git a/honeycomb-guide/src/definitions/advancedops.md b/honeycomb-guide/src/definitions/advancedops.md new file mode 100644 index 000000000..8a65fc1b9 --- /dev/null +++ b/honeycomb-guide/src/definitions/advancedops.md @@ -0,0 +1 @@ +# Advanced Operations diff --git a/honeycomb-guide/src/definitions/betaf.md b/honeycomb-guide/src/definitions/betaf.md index 7d9f5e483..96ce8c252 100644 --- a/honeycomb-guide/src/definitions/betaf.md +++ b/honeycomb-guide/src/definitions/betaf.md @@ -1 +1,25 @@ # Beta Functions + +Each combinatorial map of dimension *N* defines *N* beta functions linking +the set of darts together (e.g. a 2-map contains *β1* and +*β2*). These functions model the topology of the map, giving +information about connections of the different cells of the map / mesh. In +our case, we mostly use: + +- *β1*, a (partial) permutation, +- *β2*, *β3*, two (partial) involutions + + +
+ Embed +
Representation of β1 (red, only on a single face) and β2 (yellow) for a simple 2-map
+
+ +Additionally, we define *β0* as the inverse of *β1*, i.e. +*β0(β1(d)) = d*. This comes from a practical consideration +for performances and efficiency of the implementation. + +The *βi* functions can be interpreted as navigation functions along the +*i-th* dimensions: *β1* makes you navigate along the edges, *β2* +along the faces, etc. This can be generalized to *N* dimensions, but we are only +interested in 2D and 3D at the moment. \ No newline at end of file diff --git a/honeycomb-guide/src/definitions/changeNdart.md b/honeycomb-guide/src/definitions/changeNdart.md new file mode 100644 index 000000000..4b1008d0d --- /dev/null +++ b/honeycomb-guide/src/definitions/changeNdart.md @@ -0,0 +1 @@ +# Add / Remove a free dart diff --git a/honeycomb-guide/src/definitions/changeNdim.md b/honeycomb-guide/src/definitions/changeNdim.md new file mode 100644 index 000000000..20df96db6 --- /dev/null +++ b/honeycomb-guide/src/definitions/changeNdim.md @@ -0,0 +1 @@ +# Add / Remove a dimension diff --git a/honeycomb-guide/src/definitions/cmaps.md b/honeycomb-guide/src/definitions/cmaps.md index 1f39ec426..554021696 100644 --- a/honeycomb-guide/src/definitions/cmaps.md +++ b/honeycomb-guide/src/definitions/cmaps.md @@ -1 +1,26 @@ # Combinatorial Maps + +N-dimensional combinatorial maps, noted *N-map*, are objects made up of +two main elements: + +- A set of darts, darts being the smallest elements making up the map +- N beta functions, linking the darts of the map + +Additionally, we can define *embedded data* as spatial anchoring of the +darts making up the map. While the first two elements hold topological +information, embedded data gives information about the "shape" of the +map (e.g. vertices position in a spatial domain). + +With these elements, we can represent and operate on meshes. + +## Example + +Operations on a combinatorial map can affect its topology, shape or both: + +
+ MapMeshEquivalent +
Mesh-Map equivalent of a four step transformation
+
+ +The specifics on how data is encoded is detailed in attribute-specific +sections. \ No newline at end of file diff --git a/honeycomb-guide/src/definitions/darts.md b/honeycomb-guide/src/definitions/darts.md index 6177afa0a..3331a522b 100644 --- a/honeycomb-guide/src/definitions/darts.md +++ b/honeycomb-guide/src/definitions/darts.md @@ -1 +1,16 @@ # Darts + +Darts are the finest grain composing combinatorial maps. The structure +of the map is given by the relationship between darts, defined through +beta functions. + +
+ Darts +
Boundless square modeling using four darts
+
+ +In our implementation, darts exist implictly through indexing and their +associated data. There are no dart *objects* in a strict sense, there is +only a given number of dart, their associated data ordered by an array-like +logic, and a record of "unused" slots that can be used for dart insertion. +Because of this, we assimilate dart and dart index. \ No newline at end of file diff --git a/honeycomb-guide/src/definitions/embedding.md b/honeycomb-guide/src/definitions/embedding.md index 9d8d8a882..f89fe8445 100644 --- a/honeycomb-guide/src/definitions/embedding.md +++ b/honeycomb-guide/src/definitions/embedding.md @@ -1 +1,31 @@ # Embedding + +Embedding, or embedded data refers to the association of topological +entities (darts, *i*-cells) to geometrical data (spatial positions, +vertices, faces, volumes). + +We choose to encode the origin of darts as their associated vertex. In +order to avoid duplicating coordinates, what is associated to each dart +is an identifier, meaning that all darts starting from a given point in +space share the same associated vertex ID. + +
+ Embed +
Geometric embedding of spatial data
+
+ +In the above example, the data would be organized in the following way: + +- *darts = { null, d1, d2, d3, d4 }* +- *associated_vertex = { null, v1, v2, v3, v4 }* +- *vertices = { (0.0, 0.0), (0.0, 1.0), (1.0, 1.0), (1.0, 0.0) }* + +In this case, *v1 = 0*; *v2 = 1*; *v3 = 2*; *v4 = 3*. + +Association of darts and vertices ID is done implictly through indexing; +In practice, the *darts* vector does not even exist. This example is limited +to vertices, but we also keep track of faces, and volumes eventually. + +The embedding of geometrical data also has implication for operations +on the map. This is detailed along operation specificities in their +dedicated sections. \ No newline at end of file diff --git a/honeycomb-guide/src/definitions/genorbit.md b/honeycomb-guide/src/definitions/genorbit.md new file mode 100644 index 000000000..e32f889ec --- /dev/null +++ b/honeycomb-guide/src/definitions/genorbit.md @@ -0,0 +1 @@ +# Generic orbit diff --git a/honeycomb-guide/src/definitions/icells.md b/honeycomb-guide/src/definitions/icells.md new file mode 100644 index 000000000..8630fa80d --- /dev/null +++ b/honeycomb-guide/src/definitions/icells.md @@ -0,0 +1 @@ +# I-cells diff --git a/honeycomb-guide/src/definitions/introduction.md b/honeycomb-guide/src/definitions/introduction.md index e10b99d01..fb7f6c426 100644 --- a/honeycomb-guide/src/definitions/introduction.md +++ b/honeycomb-guide/src/definitions/introduction.md @@ -1 +1,11 @@ # Introduction + +## Scope + +Because our implementation has very practical goals, the definitions +presented here use a more intuitive approach rather than strict +mathematical concepts. + +Our main interest at the moment being 2D and 3D combinatorial maps, +some operations are defined with consideration to these restricitions. +This is especially useful for orbits and sewing operations. \ No newline at end of file diff --git a/honeycomb-guide/src/definitions/orbits.md b/honeycomb-guide/src/definitions/orbits.md index bae7863af..9ed1b0e89 100644 --- a/honeycomb-guide/src/definitions/orbits.md +++ b/honeycomb-guide/src/definitions/orbits.md @@ -1 +1,26 @@ # Orbits + +We define orbits as a set of darts that are accessible from a given dart, +using a certain set of beta functions. For example: + +- *⟨β1⟩(d)* refers to all darts accessible from *d* using + *β1* recursively any number of times. +- *⟨β1, β3⟩(d)* refers to all darts accessible + from *d* using any combination of *β1* and *β3*. + +## *i*-cells + +A specific subset of orbits, refered to as *i*-cells are defined and often +used in algorithms. The general definition is the following: + +- **if i = 0**: *0-cell(d) = ⟨{ βj o βk with 1 ≤ j < k ≤ N }⟩(d)* +- **else**: *i-cell(d) = ⟨β1, β2, ..., βi-1, βi+1, ..., βN⟩(d)* + +In our case, we can use specialized definitions for our dimensions: + +| *i* | Geometry | 2-map | 3-map | +| --- | --- | --- | --- | +| 0 | Vertex | *⟨β1 o β2⟩(d)*
**or**
*⟨β2 o β-1⟩(d)* | *⟨β3 o β2, β1 o β3⟩(d)*
**or**
*⟨β3 o β2, β3 o β-1⟩(d)* | +| 1 | Edge | *⟨β2⟩(d)* | *⟨β2, β3⟩(d)* | +| 2 | Face | *⟨β1⟩(d)* | *⟨β1, β3⟩(d)* | +| 3 | Volume | - | *⟨β1, β2⟩(d)* | \ No newline at end of file diff --git a/honeycomb-guide/src/definitions/orientation.md b/honeycomb-guide/src/definitions/orientation.md new file mode 100644 index 000000000..68fefa379 --- /dev/null +++ b/honeycomb-guide/src/definitions/orientation.md @@ -0,0 +1 @@ +# Orientation diff --git a/honeycomb-guide/src/definitions/sew.md b/honeycomb-guide/src/definitions/sew.md new file mode 100644 index 000000000..575af6c19 --- /dev/null +++ b/honeycomb-guide/src/definitions/sew.md @@ -0,0 +1 @@ +# Sewing operation diff --git a/honeycomb-guide/src/definitions/unsew.md b/honeycomb-guide/src/definitions/unsew.md new file mode 100644 index 000000000..1ef93a915 --- /dev/null +++ b/honeycomb-guide/src/definitions/unsew.md @@ -0,0 +1 @@ +# Unsewing operation diff --git a/honeycomb-guide/src/examples/twomap.md b/honeycomb-guide/src/examples/twomap.md new file mode 100644 index 000000000..2bc30add4 --- /dev/null +++ b/honeycomb-guide/src/examples/twomap.md @@ -0,0 +1,21 @@ +# TwoMap + +## Usage + +A general example is [provided](../honeycomb_core/twomap/struct.TwoMap.html#example) in +the Rust doc of the TwoMap structure. From a meshing perspective, it corresponds to the +following operations: + +
+ TwoMapExample +
Sample operations transforming two triangles into a square
+
+ +After the creation of an initial map modeling a simple triangle, we: +- (a) add & initialize new darts to the map to model a second triangle. +- (b) 2-sew the two triangles using according to a **StretchLeft** sewing policy. +- (c) move the most upper right vertex to form a square using both triangles. +- (d) 2-unsew the inner edge, free and remove its darts to form an actual square. + +Most of those steps require multiple method calls and assertions are used to highlight +the modification done to the structure along the way. \ No newline at end of file diff --git a/honeycomb-guide/src/images/BetaFunc.svg b/honeycomb-guide/src/images/BetaFunc.svg new file mode 100644 index 000000000..dc5b2f621 --- /dev/null +++ b/honeycomb-guide/src/images/BetaFunc.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/honeycomb-guide/src/images/Darts.svg b/honeycomb-guide/src/images/Darts.svg new file mode 100644 index 000000000..92a48b21b --- /dev/null +++ b/honeycomb-guide/src/images/Darts.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/honeycomb-guide/src/images/Embed.svg b/honeycomb-guide/src/images/Embed.svg new file mode 100644 index 000000000..275908591 --- /dev/null +++ b/honeycomb-guide/src/images/Embed.svg @@ -0,0 +1,4 @@ + + + +
d1
d3
d4
d2
v1
v3
v4
v2
 \ No newline at end of file diff --git a/honeycomb-guide/src/images/TwoMapMesh.svg b/honeycomb-guide/src/images/TwoMapMesh.svg new file mode 100644 index 000000000..cfcd9537f --- /dev/null +++ b/honeycomb-guide/src/images/TwoMapMesh.svg @@ -0,0 +1,4 @@ + + + +
(a)
(a)
(b)
(b)
(c)
(c)
(d)
(d) \ No newline at end of file diff --git a/honeycomb-guide/src/index.md b/honeycomb-guide/src/index.md index fb1746941..ff54caf8d 100644 --- a/honeycomb-guide/src/index.md +++ b/honeycomb-guide/src/index.md @@ -13,13 +13,30 @@ issues, thanks to the language's guarantees. ### Requirements -- **Rust 1.75** - *The code may compile and work for earlier versions, but we do not test for those* +- **Rust stable release** - *Development started on 1.75, but we might use + newer features as the project progresses* + +### Quickstart + +#### Rust + +... + +#### Documentation + +You can generate this documentation locally using **mdbook** and **cargo doc**: + +```shell +# Serve the doc on a local server +mdbook serve --open -d ../target/doc/ honeycomb-guide/ & +cargo doc --all --no-deps +``` ## Links ### Documentation -- [honeycomb-core](honeycomb_core) *Core definitions and tools* +- [honeycomb-core](honeycomb_core/) *Core definitions and tools* ### References diff --git a/honeycomb-guide/src/project-structure/honeycomb-core.md b/honeycomb-guide/src/project-structure/honeycomb-core.md index 0fd3fd5d7..5613f5f65 100644 --- a/honeycomb-guide/src/project-structure/honeycomb-core.md +++ b/honeycomb-guide/src/project-structure/honeycomb-core.md @@ -1 +1,46 @@ # honeycomb-core + +[Documentation](../honeycomb_core/) + +--- + +**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: + +- [TwoMap](../honeycomb_core/twomap/struct.TwoMap.html#example) + +## Content + +### Structures + +- **TwoMap**: 2D combinatorial map implementation + +### Aliases + +- **Vertex2**: 2-elements array +- **DartIdentifier**: Integer identifier for darts +- **VertexIdentifier**: Integer identifier for 0D cells +- **FaceIdentifier**: Integer identifier for 2D cells +- **VolumeIdentifier**: Integer identifier for 3D cells + +### Enums + +- **SewPolicy**: Logic to follow for the geometrical part of the sewing operation. +- **UnsewPolicy**: Logic to follow for the geometrical part of the unsewing operation. + +## Future additions + +- [ ] Add a custom vector type for spatial representation (2D & 3D) +- [ ] Replace returned `Vec` by an alternative structure or type + to prevent too many runtime allocations. +- [ ] Write structure benchmarks (2D) +- [ ] Add I/O support for mesh formats (2D) +- [ ] Add orientation checks (2D) +- [ ] Implement 3D maps \ No newline at end of file diff --git a/honeycomb-guide/src/project-structure/honeycomb-guide.md b/honeycomb-guide/src/project-structure/honeycomb-guide.md new file mode 100644 index 000000000..eed70a477 --- /dev/null +++ b/honeycomb-guide/src/project-structure/honeycomb-guide.md @@ -0,0 +1,27 @@ +# honeycomb-guide + +--- + +**honeycomb-guide** is the mdbook project used to generate the documentation you are +currently reading. Its content mainly focuses on definition and feature-listing +rather than technical details on implementation. The latter can be found in the code +documentation. + +## Building + +You can generate this documentation locally using **mdbook** and **cargo doc**: + +```shell +mdbook serve --open -d ../target/doc/ honeycomb-guide/ & +cargo doc --all --no-deps +``` + +## Contributing + +A few observations on writing documentation using **mdbook**: + +- Note that 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 diff --git a/honeycomb-guide/src/project-structure/workspace.md b/honeycomb-guide/src/project-structure/workspace.md index 079e19eb5..98785379d 100644 --- a/honeycomb-guide/src/project-structure/workspace.md +++ b/honeycomb-guide/src/project-structure/workspace.md @@ -1 +1,19 @@ # Workspace + +The project root is organized using Cargo workspaces at +the moment. This may change when other languages are +introduced to the project. + +## Members + +These entries are members of the Cargo workspace. + +- [honeycomb-core](honeycomb-core.html) *Core definitions and tools for combinatorial map implementation* + +## Others + +These entries are additional sections that are not linked to +the project through Cargo, most likely because they require a +different building process. + +- [honeycomb-guide](honeycomb-guide.html) *Source files of the user guide* \ No newline at end of file