Skip to content

Commit

Permalink
doc: update user guide & documentation for next release (#12)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
imrn99 authored Mar 5, 2024
1 parent 9cccfe1 commit 17513c2
Show file tree
Hide file tree
Showing 8 changed files with 119 additions and 8 deletions.
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion honeycomb-core/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "honeycomb-core"
version = "0.1.0"
version = "0.1.1"
edition = "2021"

[features]
Expand Down
1 change: 1 addition & 0 deletions honeycomb-guide/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
35 changes: 33 additions & 2 deletions honeycomb-guide/src/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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*
Expand All @@ -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

Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion honeycomb-guide/src/project-structure/honeycomb-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
75 changes: 75 additions & 0 deletions honeycomb-guide/src/project-structure/honeycomb-utils.md
Original file line number Diff line number Diff line change
@@ -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 <BENCHMARK>
```

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 <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
1 change: 1 addition & 0 deletions honeycomb-guide/src/project-structure/workspace.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion honeycomb-utils/Cargo.toml
Original file line number Diff line number Diff line change
@@ -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
Expand Down

0 comments on commit 17513c2

Please sign in to comment.