From 17513c26855c93dd5c213f52bc3a775dc6bc90dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Isa=C3=AFe?= Date: Tue, 5 Mar 2024 09:17:19 +0100 Subject: [PATCH] doc: update user guide & documentation for next release (#12) * doc: add honeycomb-utils page to UG * doc: add Rust project setup instructions also, mention honeycomb-utils in index & workspace pages * doc: update README * doc: bump version of packages & update honeycomb-core todo list --- README.md | 9 ++- honeycomb-core/Cargo.toml | 2 +- honeycomb-guide/src/SUMMARY.md | 1 + honeycomb-guide/src/index.md | 35 ++++++++- .../src/project-structure/honeycomb-core.md | 2 +- .../src/project-structure/honeycomb-utils.md | 75 +++++++++++++++++++ .../src/project-structure/workspace.md | 1 + honeycomb-utils/Cargo.toml | 2 +- 8 files changed, 119 insertions(+), 8 deletions(-) create mode 100644 honeycomb-guide/src/project-structure/honeycomb-utils.md diff --git a/README.md b/README.md index 89ea25e4d..24444b444 100644 --- a/README.md +++ b/README.md @@ -32,11 +32,14 @@ kill $(ps -e | awk '/mdbook/ {print $1}') ### 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] +The content of each member as well as instructions for usage are available in the [user guide][UGW]. -[UGHC]: https://lihpc-computational-geometry.github.io/honeycomb/project-structure/honeycomb-core.html +- Basic structure are provided in the **honeycomb-core** crate ([Rust Doc][DOCHC]). +- Utilities for tests and benchmarks are provided in the **honeycomb-utils** crate ([Rust Doc][DOCHU]) + +[UGW]: https://lihpc-computational-geometry.github.io/honeycomb/project-structure/workspace.html [DOCHC]: https://lihpc-computational-geometry.github.io/honeycomb/honeycomb_core/ +[DOCHU]: https://lihpc-computational-geometry.github.io/honeycomb/honeycomb_utils/ ## Contributing diff --git a/honeycomb-core/Cargo.toml b/honeycomb-core/Cargo.toml index 853b77f2f..3656c094a 100644 --- a/honeycomb-core/Cargo.toml +++ b/honeycomb-core/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "honeycomb-core" -version = "0.1.0" +version = "0.1.1" edition = "2021" [features] diff --git a/honeycomb-guide/src/SUMMARY.md b/honeycomb-guide/src/SUMMARY.md index 53326200b..25019baf3 100644 --- a/honeycomb-guide/src/SUMMARY.md +++ b/honeycomb-guide/src/SUMMARY.md @@ -7,6 +7,7 @@ - [Workspace](./project-structure/workspace.md) - [honeycomb-core](./project-structure/honeycomb-core.md) - [honeycomb-guide](./project-structure/honeycomb-guide.md) + - [honeycomb-utils](./project-structure/honeycomb-utils.md) # Definitions diff --git a/honeycomb-guide/src/index.md b/honeycomb-guide/src/index.md index ff54caf8d..85fb17663 100644 --- a/honeycomb-guide/src/index.md +++ b/honeycomb-guide/src/index.md @@ -11,7 +11,7 @@ The current objective is to write a first implementation in Rust, to then improve the structure without having to deal with data races and similar issues, thanks to the language's guarantees. -### Requirements +### Core Requirements - **Rust stable release** - *Development started on 1.75, but we might use newer features as the project progresses* @@ -20,7 +20,37 @@ issues, thanks to the language's guarantees. #### Rust -... +The crate is not currently being published on crates.io, meaning you will have +to clone this repository and add the dependency using the path to the project. + +```shell +# Example: Setting up a new project using honeycomb-core + +# Create your project using cargo +cargo new --bin my_project + +# Clone the honeycomb repository +git clone https://github.com/LIHPC-Computational-Geometry/honeycomb.git + +# Add the dependency to your project +# Version is set to whatever the current version is in the repository +cd my_project +cargo add honeycomb-core --path=../honeycomb/honeycomb-core/ +``` + +The following lines should have appeared in the manifest of your project: + +```toml +# Cargo.toml +# ... + +[dependencies] +honeycomb-core = { path = "../honeycomb/honeycomb-core/" } +``` + +You can also copy-paste the above directly to your manifest. From there, you can +manually add whichever features your application requires. + #### Documentation @@ -37,6 +67,7 @@ cargo doc --all --no-deps ### Documentation - [honeycomb-core](honeycomb_core/) *Core definitions and tools* +- [honeycomb-utils](honeycomb_utils/) *Utility routines* ### References diff --git a/honeycomb-guide/src/project-structure/honeycomb-core.md b/honeycomb-guide/src/project-structure/honeycomb-core.md index 5613f5f65..1777d8676 100644 --- a/honeycomb-guide/src/project-structure/honeycomb-core.md +++ b/honeycomb-guide/src/project-structure/honeycomb-core.md @@ -37,10 +37,10 @@ structures: ## Future additions +- [x] Write structure benchmarks (2D) - done as of **0.1.1** - [ ] 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-utils.md b/honeycomb-guide/src/project-structure/honeycomb-utils.md new file mode 100644 index 000000000..63312e8f6 --- /dev/null +++ b/honeycomb-guide/src/project-structure/honeycomb-utils.md @@ -0,0 +1,75 @@ +# honeycomb-utils + +[Documentation](../honeycomb_utils/) + +--- + +**honeycomb-utils** is a Rust crate that provides utility functions to +the user (and developer) in order to write benchmarks and tests more +easily. A number of benchmarks are already defined in this crate using the +[criterion][CRITERION] and [iai-callgrind][IAI] crates. Additionally, +one example is provided to illustrate the result of the different *size* +methods on a given map, as well as a plotting script for the methods' output. + +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 + +### Benchmarks + +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-twomap-editing` | Iai-callgrind | `benches/core/twomap/editing.rs` | +| `prof-twomap-reading` | Iai-callgrind | `benches/core/twomap/reading.rs` | +| `prof-twomap-sewing-unsewing` | Iai-callgrind | `benches/core/twomap/sewing.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. + + +### Examples + +You can run examples using the following command: + +```shell +# Run a specific example +cargo run --example +``` + +The following examples are available: + +| Name | Description | +|----------------|-------------| +| `memory_usage` | Outputs the memory usage of a given map as three *csv* files. These files can be used to generate charts using the `memory_usage.py` script | + + +### Scripts + +- `memory_usage.py` - **requires matplotlib** - Plots pie charts using a *csv* file produced by a size method of TwoMap. + + +[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 \ 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 98785379d..56f50a7be 100644 --- a/honeycomb-guide/src/project-structure/workspace.md +++ b/honeycomb-guide/src/project-structure/workspace.md @@ -9,6 +9,7 @@ introduced to the project. These entries are members of the Cargo workspace. - [honeycomb-core](honeycomb-core.html) *Core definitions and tools for combinatorial map implementation* +- [honeycomb-utils](honeycomb-utils.html) *Utility routines used in benchmarking and testing* ## Others diff --git a/honeycomb-utils/Cargo.toml b/honeycomb-utils/Cargo.toml index 1c0de1f89..ff0b97c68 100644 --- a/honeycomb-utils/Cargo.toml +++ b/honeycomb-utils/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "honeycomb-utils" -version = "0.1.0" +version = "0.1.1" edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html