Skip to content

Commit 2e320a6

Browse files
orxfunorxfun
authored
Merge pull request #36 from orxfun/version-incremented-and-documentation-revised-for-licenses
version incremented and documentation revised for licenses
2 parents 523dcff + 0526ef3 commit 2e320a6

File tree

2 files changed

+2
-314
lines changed

2 files changed

+2
-314
lines changed

‎Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "orx-priority-queue"
3-
version = "1.6.0"
3+
version = "1.7.0"
44
edition = "2021"
55
authors = ["orxfun <[email protected]>"]
66
description = "Priority queue traits and high performance d-ary heap implementations."

‎src/lib.rs‎

Lines changed: 1 addition & 313 deletions
Original file line numberDiff line numberDiff line change
@@ -1,316 +1,4 @@
1-
//! # orx-priority-queue
2-
//!
3-
//! [![orx-priority-queue crate](https://img.shields.io/crates/v/orx-priority-queue.svg)](https://crates.io/crates/orx-priority-queue)
4-
//! [![orx-priority-queue documentation](https://docs.rs/orx-priority-queue/badge.svg)](https://docs.rs/orx-priority-queue)
5-
//!
6-
//!
7-
//! Priority queue traits and high performance d-ary heap implementations.
8-
//!
9-
//! ## A. Priority Queue Traits
10-
//!
11-
//! This crate aims to provide algorithms with the abstraction over priority queues. In order to achieve this, two traits are defined: **`PriorityQueue<N, K>`** and **`PriorityQueueDecKey<N, K>`**. The prior is a simple queue while the latter extends it by providing additional methods to change priorities of the items that already exist in the queue.
12-
//!
13-
//! The separation is important since additional operations often requires the implementors to allocate internal memory for bookkeeping. Therefore, we would prefer `PriorityQueueDecKey<N, K>` only when we need to change the priorities.
14-
//!
15-
//! See [DecreaseKey](https://github.com/orxfun/orx-priority-queue/blob/main/docs/DecreaseKey.md) section for a discussion on when decrease-key operations are required and why they are important.
16-
//!
17-
//! ## B. d-ary Heap Implementations
18-
//!
19-
//! d-ary implementations are generalizations of the binary heap; i.e., binary heap is a special case where `D=2`. It is advantageous to have a parametrized d; as for instance, in the benchmarks defined here, `D=4` outperforms `D=2`.
20-
//! * With a large d: number of per level comparisons increases while the tree depth becomes smaller.
21-
//! * With a small d: each level requires fewer comparisons while the tree with the same number of nodes is deeper.
22-
//!
23-
//! Further, three categories of d-ary heap implementations are introduced.
24-
//!
25-
//! ### 1. DaryHeap (PriorityQueue)
26-
//!
27-
//! This is the basic d-ary heap implementing `PriorityQueue`. It is the default choice unless priority updates or decrease-key operations are required.
28-
//!
29-
//! ### 2. DaryHeapOfIndices (PriorityQueue + PriorityQueueDecKey)
30-
//!
31-
//! This is a d-ary heap paired up with a positions array and implements `PriorityQueueDecKey`.
32-
//!
33-
//! * It requires the nodes to implement `HasIndex` trait which is nothing but `fn index(&self) -> usize`. Note that `usize`, `u64`, etc., already implements `HasIndex`.
34-
//! * Further, it requires to know the maximum index that is expected to enter the queue. In other words, candidates are expected to come from a closed set.
35-
//!
36-
//! Once these conditions are satisfied, it **performs significantly faster** than the alternative decrease key queues.
37-
//!
38-
//! Although the closed set requirement might sound strong, it is often naturally satisfied in mathematical algorithms. For instance, for most network traversal algorithms, the candidates set is the nodes of the graph, or indices in `0..num_nodes`. Similarly, if the heap is used to be used for sorting elements of a list, indices are simply coming from `0..list_len`.
39-
//!
40-
//! This is the default decrease-key queue provided that the requirements are satisfied.
41-
//!
42-
//! ### 3. DaryHeapWithMap (PriorityQueue + PriorityQueueDecKey)
43-
//!
44-
//! This is a d-ary heap paired up with a positions map (`HashMap` or `BTreeMap` when no-std) and also implements `PriorityQueueDecKey`.
45-
//!
46-
//! This is the most general decrease-key queue that provides the open-set flexibility and fits to almost all cases.
47-
//!
48-
//! ### Other Queues
49-
//!
50-
//! In addition, queue implementations are provided in this crate for the following external data structures:
51-
//!
52-
//! * `std::collections::BinaryHeap<(N, K)>` implements only `PriorityQueue<N, K>`,
53-
//! * `priority_queue:PriorityQueue<N, K>` implements both `PriorityQueue<N, K>` and `PriorityQueueDecKey<N, K>`
54-
//! * requires `--features impl_priority_queue`
55-
//!
56-
//! This allows to use all the queue implementations interchangeably and pick the one fitting best to the use case.
57-
//!
58-
//! ### Performance & Benchmarks
59-
//!
60-
//! *You may find the details of the benchmarks at [benches](https://github.com/orxfun/orx-priority-queue/blob/main/benches) folder.*
61-
//!
62-
//! <img src="https://raw.githubusercontent.com/orxfun/orx-priority-queue/main/docs/bench_results.PNG" alt="https://raw.githubusercontent.com/orxfun/orx-priority-queue/main/docs/bench_results.PNG" />
63-
//!
64-
//! The table above summarizes the benchmark results of basic operations on basic queues, and queues allowing decrease key operations.
65-
//!
66-
//! * In the first benchmark, we repeatedly call `push` and `pop` operations on a queue while maintaining an average length of 100000:
67-
//! * We observe that `BinaryHeap` (`DaryHeap<_, _, 2>`) performs almost the same as the standard binary heap.
68-
//! * Experiments on different values of d shows that `QuaternaryHeap` (D=4) outperforms both binary heaps.
69-
//! * Further increasing D to 8 does not improve performance.
70-
//! * Finally, we repeat the experiments with `BinaryHeap` and `QuaternaryHeap` using the specialized [`push_then_pop`](https://docs.rs/orx-priority-queue/latest/orx_priority_queue/trait.PriorityQueue.html#tymethod.push_then_pop) operation. Note that this operation further doubles the performance, and hence, should be used whenever it fits the use case.
71-
//! * In the second benchmark, we add [`decrease_key_or_push`](https://docs.rs/orx-priority-queue/latest/orx_priority_queue/trait.PriorityQueueDecKey.html#method.decrease_key_or_push) calls to the operations. Standard binary heap is excluded since it cannot implement `PriorityQueueDecKey`.
72-
//! * We observe that `DaryHeapOfIndices` significantly outperforms other decrease key queues.
73-
//! * Among `BinaryHeapOfIndices` and `QuaternaryHeapOfIndices`, the latter with D=4 again performs better.
74-
//!
75-
//!
76-
//! ## C. Examples
77-
//!
78-
//! ### C.1. Basic Usage
79-
//!
80-
//! Below example demonstrates basic usage of a simple `PriorityQueue`. You may see the entire functionalities [here](https://docs.rs/orx-priority-queue/latest/orx_priority_queue/trait.PriorityQueue.html).
81-
//!
82-
//! ```rust
83-
//! use orx_priority_queue::*;
84-
//!
85-
//! // generic over simple priority queues
86-
//! fn test_priority_queue<P>(mut pq: P)
87-
//! where
88-
//! P: PriorityQueue<usize, f64>,
89-
//! {
90-
//! pq.clear();
91-
//!
92-
//! pq.push(0, 42.0);
93-
//! assert_eq!(Some(&0), pq.peek().map(|x| x.node()));
94-
//! assert_eq!(Some(&42.0), pq.peek().map(|x| x.key()));
95-
//!
96-
//! let popped = pq.pop();
97-
//! assert_eq!(Some((0, 42.0)), popped);
98-
//! assert!(pq.is_empty());
99-
//!
100-
//! pq.push(0, 42.0);
101-
//! pq.push(1, 7.0);
102-
//! pq.push(2, 24.0);
103-
//! pq.push(10, 3.0);
104-
//!
105-
//! while let Some(popped) = pq.pop() {
106-
//! println!("pop {:?}", popped);
107-
//! }
108-
//! }
109-
//!
110-
//! // d-ary heap generic over const d
111-
//! const D: usize = 4;
112-
//!
113-
//! test_priority_queue(DaryHeap::<usize, f64, D>::default());
114-
//! test_priority_queue(DaryHeapWithMap::<usize, f64, D>::default());
115-
//! test_priority_queue(DaryHeapOfIndices::<usize, f64, D>::with_index_bound(100));
116-
//!
117-
//! // type aliases for common heaps: Binary or Quaternary
118-
//! test_priority_queue(BinaryHeap::default());
119-
//! test_priority_queue(QuaternaryHeapWithMap::default());
120-
//! test_priority_queue(BinaryHeapOfIndices::with_index_bound(100));
121-
//! ```
122-
//!
123-
//! As mentioned, `PriorityQueueDecKey` extends capabilities of a `PriorityQueue`. You may see the additional functionalities [here](https://docs.rs/orx-priority-queue/latest/orx_priority_queue/trait.PriorityQueueDecKey.html).
124-
//!
125-
//! ```rust
126-
//! use orx_priority_queue::*;
127-
//!
128-
//! // generic over decrease-key priority queues
129-
//! fn test_priority_queue_deckey<P>(mut pq: P)
130-
//! where
131-
//! P: PriorityQueueDecKey<usize, f64>,
132-
//! {
133-
//! pq.clear();
134-
//!
135-
//! pq.push(0, 42.0);
136-
//! assert_eq!(Some(&0), pq.peek().map(|x| x.node()));
137-
//! assert_eq!(Some(&42.0), pq.peek().map(|x| x.key()));
138-
//!
139-
//! let popped = pq.pop();
140-
//! assert_eq!(Some((0, 42.0)), popped);
141-
//! assert!(pq.is_empty());
142-
//!
143-
//! pq.push(0, 42.0);
144-
//! assert!(pq.contains(&0));
145-
//!
146-
//! pq.decrease_key(&0, 7.0);
147-
//! assert_eq!(Some(&0), pq.peek().map(|x| x.node()));
148-
//! assert_eq!(Some(&7.0), pq.peek().map(|x| x.key()));
149-
//!
150-
//! let deckey_result = pq.try_decrease_key(&0, 10.0);
151-
//! assert!(matches!(ResTryDecreaseKey::Unchanged, deckey_result));
152-
//! assert_eq!(Some(&0), pq.peek().map(|x| x.node()));
153-
//! assert_eq!(Some(&7.0), pq.peek().map(|x| x.key()));
154-
//!
155-
//! while let Some(popped) = pq.pop() {
156-
//! println!("pop {:?}", popped);
157-
//! }
158-
//! }
159-
//!
160-
//! // d-ary heap generic over const d
161-
//! const D: usize = 4;
162-
//!
163-
//! test_priority_queue_deckey(DaryHeapOfIndices::<usize, f64, D>::with_index_bound(100));
164-
//! test_priority_queue_deckey(DaryHeapWithMap::<usize, f64, D>::default());
165-
//!
166-
//! // type aliases for common heaps: Binary or Quaternary
167-
//! test_priority_queue_deckey(BinaryHeapOfIndices::with_index_bound(100));
168-
//! test_priority_queue_deckey(QuaternaryHeapWithMap::default());
169-
//! ```
170-
//!
171-
//! ### C.2. Usage in Dijkstra's Shortest Path
172-
//!
173-
//! You may see below two implementations of the Dijkstra's shortest path algorithm: one using a `PriorityQueue` and the other with a `PriorityQueueDecKey`. Please note the following:
174-
//!
175-
//! * Priority queue traits allow us to be generic over queues. Therefore, we are able to implement the algorithm once that works for any queue implementation.
176-
//! * The second implementation with a decrease key queue pushes some of the bookkeeping to the queue, and arguably leads to a cleaner algorithm implementation.
177-
//!
178-
//! ```rust
179-
//! use orx_priority_queue::*;
180-
//!
181-
//! pub struct Edge {
182-
//! head: usize,
183-
//! weight: u32,
184-
//! }
185-
//!
186-
//! pub struct Graph(Vec<Vec<Edge>>);
187-
//!
188-
//! impl Graph {
189-
//! fn num_nodes(&self) -> usize {
190-
//! self.0.len()
191-
//! }
192-
//!
193-
//! fn out_edges(&self, node: usize) -> impl Iterator<Item = &Edge> {
194-
//! self.0[node].iter()
195-
//! }
196-
//! }
197-
//!
198-
//! // Implementation using a PriorityQueue
199-
//!
200-
//! fn dijkstras_with_basic_pq<Q: PriorityQueue<usize, u32>>(
201-
//! graph: &Graph,
202-
//! queue: &mut Q,
203-
//! source: usize,
204-
//! sink: usize,
205-
//! ) -> Option<u32> {
206-
//! // init
207-
//! queue.clear();
208-
//! let mut dist = vec![u32::MAX; graph.num_nodes()];
209-
//! dist[source] = 0;
210-
//! queue.push(source, 0);
211-
//!
212-
//! // iterate
213-
//! while let Some((node, cost)) = queue.pop() {
214-
//! if node == sink {
215-
//! return Some(cost);
216-
//! } else if cost > dist[node] {
217-
//! continue;
218-
//! }
219-
//!
220-
//! let out_edges = graph.out_edges(node);
221-
//! for Edge { head, weight } in out_edges {
222-
//! let next_cost = cost + weight;
223-
//! if next_cost < dist[*head] {
224-
//! queue.push(*head, next_cost);
225-
//! dist[*head] = next_cost;
226-
//! }
227-
//! }
228-
//! }
229-
//!
230-
//! None
231-
//! }
232-
//!
233-
//! // Implementation using a PriorityQueueDecKey
234-
//!
235-
//! fn dijkstras_with_deckey_pq<Q: PriorityQueueDecKey<usize, u32>>(
236-
//! graph: &Graph,
237-
//! queue: &mut Q,
238-
//! source: usize,
239-
//! sink: usize,
240-
//! ) -> Option<u32> {
241-
//! // init
242-
//! queue.clear();
243-
//! let mut visited = vec![false; graph.num_nodes()];
244-
//!
245-
//! // init
246-
//! visited[source] = true;
247-
//! queue.push(source, 0);
248-
//!
249-
//! // iterate
250-
//! while let Some((node, cost)) = queue.pop() {
251-
//! if node == sink {
252-
//! return Some(cost);
253-
//! }
254-
//!
255-
//! let out_edges = graph.out_edges(node);
256-
//! for Edge { head, weight } in out_edges {
257-
//! if !visited[*head] {
258-
//! queue.try_decrease_key_or_push(&head, cost + weight);
259-
//! }
260-
//! }
261-
//! visited[node] = true;
262-
//! }
263-
//!
264-
//! None
265-
//! }
266-
//!
267-
//! // example input
268-
//!
269-
//! let e = |head: usize, weight: u32| Edge { head, weight };
270-
//! let graph = Graph(vec![
271-
//! vec![e(1, 4), e(2, 5)],
272-
//! vec![e(0, 3), e(2, 6), e(3, 1)],
273-
//! vec![e(1, 3), e(3, 9)],
274-
//! vec![],
275-
//! ]);
276-
//!
277-
//! // TESTS: basic priority queues
278-
//!
279-
//! let mut pq = BinaryHeap::new();
280-
//! assert_eq!(Some(5), dijkstras_with_basic_pq(&graph, &mut pq, 0, 3));
281-
//! assert_eq!(None, dijkstras_with_basic_pq(&graph, &mut pq, 3, 1));
282-
//!
283-
//! let mut pq = QuaternaryHeap::new();
284-
//! assert_eq!(Some(5), dijkstras_with_basic_pq(&graph, &mut pq, 0, 3));
285-
//! assert_eq!(None, dijkstras_with_basic_pq(&graph, &mut pq, 3, 1));
286-
//!
287-
//! let mut pq = DaryHeap::<_, _, 8>::new();
288-
//! assert_eq!(Some(5), dijkstras_with_basic_pq(&graph, &mut pq, 0, 3));
289-
//! assert_eq!(None, dijkstras_with_basic_pq(&graph, &mut pq, 3, 1));
290-
//!
291-
//! // TESTS: decrease key priority queues
292-
//!
293-
//! let mut pq = BinaryHeapOfIndices::with_index_bound(graph.num_nodes());
294-
//! assert_eq!(Some(5), dijkstras_with_deckey_pq(&graph, &mut pq, 0, 3));
295-
//! assert_eq!(None, dijkstras_with_deckey_pq(&graph, &mut pq, 3, 1));
296-
//!
297-
//! let mut pq = DaryHeapOfIndices::<_, _, 8>::with_index_bound(graph.num_nodes());
298-
//! assert_eq!(Some(5), dijkstras_with_deckey_pq(&graph, &mut pq, 0, 3));
299-
//! assert_eq!(None, dijkstras_with_deckey_pq(&graph, &mut pq, 3, 1));
300-
//!
301-
//! let mut pq = BinaryHeapWithMap::new();
302-
//! assert_eq!(Some(5), dijkstras_with_deckey_pq(&graph, &mut pq, 0, 3));
303-
//! assert_eq!(None, dijkstras_with_deckey_pq(&graph, &mut pq, 3, 1));
304-
//! ```
305-
//!
306-
//! ## Contributing
307-
//!
308-
//! Contributions are welcome! If you notice an error, have a question or think something could be improved, please open an [issue](https://github.com/orxfun/orx-priority-queue/issues/new) or create a PR.
309-
//!
310-
//! ## License
311-
//!
312-
//! This library is licensed under MIT license. See LICENSE for details.
313-
1+
#![doc = include_str!("../README.md")]
3142
#![warn(
3153
missing_docs,
3164
clippy::unwrap_in_result,

0 commit comments

Comments
 (0)