lulu 0.0.2

data/ext/lulu/marker.c

@@ -0,0 +1,111 @@
+/*
+ * marker.c
+ *
+ *  Created on: Feb 24, 2014
+ *      Author: generessler
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <math.h>
+#include "marker.h"
+#include "utility.h"
+
+#define SQRT_1_PI 0.564189583547756286948079451560772585844050629328998856844085
+
+void mr_info_init(MARKER_INFO *info) {
+    info->kind = CIRCLE;
+    info->scale = 1;
+	info->c = SQRT_1_PI;
+}
+
+void mr_info_set(MARKER_INFO *info, MARKER_KIND kind, DISTANCE scale) {
+    info->kind = kind;
+    info->scale = scale;
+	info->c = scale * (kind == SQUARE ? 0.5 : SQRT_1_PI);
+}
+
+void mr_init(MARKER *markers, int n_markers) {
+	for (int i = 0; i < n_markers; i++) {
+		MARKER *marker = markers + i;
+		marker->deleted_p = 0;
+		marker->size = 0;
+		marker->r = 0;
+		marker->x = marker->y = marker->x_sum = marker->y_sum = 0;
+		mr_reset_parts(marker);
+	}
+}
+
+void mr_reset_parts(MARKER *marker) {
+    marker->part_a = -1;
+    marker->part_b = 0;
+}
+
+void mr_set(MARKER_INFO *info, MARKER *marker, COORD x, COORD y, SIZE size) {
+	mr_init(marker, 1);
+	marker->size = size;
+	marker->r = size_to_radius(info, size);
+	marker->x = x;
+	marker->y = y;
+	marker->x_sum = x * size;
+	marker->y_sum = y * size;
+}
+
+void mr_merge(MARKER_INFO *info, MARKER *markers, int i_merged, int ia, int ib) {
+    MARKER *merged = markers + i_merged;
+    MARKER *a = markers + ia;
+    MARKER *b = markers + ib;
+	merged->deleted_p = 0;
+	merged->size = a->size + b->size;
+	merged->r = size_to_radius(info, merged->size);
+	merged->x_sum = a->x_sum + b->x_sum;
+	merged->y_sum = a->y_sum + b->y_sum;
+	merged->x = merged->x_sum / merged->size;
+	merged->y = merged->y_sum / merged->size;
+	merged->part_a = ia;
+	merged->part_b = ib;
+}
+
+DISTANCE size_to_radius(MARKER_INFO *info, SIZE size) {
+	return info->c * sqrt(size);
+}
+
+DISTANCE mr_distance(MARKER_INFO *info, MARKER *a, MARKER *b) {
+	if (info->kind == SQUARE) {
+		double r_sum = mr_r(a) + mr_r(b);
+		double dx = fabs(mr_x(b) - mr_x(a)) - r_sum;
+		double dy = fabs(mr_y(b) - mr_y(a)) - r_sum;
+		DISTANCE d = dx < 0 && dy < 0 ? fmax(dx, dy) : sqrt(dx * dx + dy * dy);
+		return d;
+	}
+	double dx = mr_x(b) - mr_x(a);
+	double dy = mr_y(b) - mr_y(a);
+	return sqrt(dx * dx + dy * dy) - mr_r(a) - mr_r(b);
+}
+
+void get_marker_array_extent(MARKER *a, int n_markers, MARKER_EXTENT *ext) {
+	if (n_markers > 0) {
+		double ew = mr_w(a);
+		double ee = mr_e(a);
+		double es = mr_s(a);
+		double en = mr_n(a);
+		for (int i = 1; i < n_markers; i++) {
+			double w = mr_w(a + i);
+			double e = mr_e(a + i);
+			double s = mr_s(a + i);
+			double n = mr_n(a + i);
+			if (w < ew)
+				ew = w;
+			if (e > ee)
+				ee = e;
+			if (s < es)
+				es = s;
+			if (n > en)
+				en = n;
+		}
+		ext->x = ew;
+		ext->y = es;
+		ext->w = ee - ew;
+		ext->h = en - es;
+	}
+}

data/ext/lulu/marker.h

@@ -0,0 +1,70 @@
+/*
+ * marker.h
+ *
+ *  Created on: Feb 24, 2014
+ *      Author: generessler
+ */
+
+#ifndef MARKER_H_
+#define MARKER_H_
+
+typedef double COORD;
+typedef double DISTANCE;
+/**
+ * Size of population represented by the marker.  For
+ * discrete populations, this can be an unsigned int.
+ */
+typedef double SIZE;
+
+typedef struct marker_s {
+	SIZE size;
+	DISTANCE r;
+	COORD x, y, x_sum, y_sum;
+	int part_a;
+	unsigned deleted_p:1, part_b:31;
+} MARKER;
+
+typedef enum marker_kind_e {
+	CIRCLE,
+	SQUARE,
+} MARKER_KIND;
+
+/**
+ * Holds parameters of the distance function and merging.
+ */
+typedef struct marker_type_info_s {
+	MARKER_KIND kind;
+	// User scale applied to radii of markers during distance computation.
+	DISTANCE scale;
+	// A scale factor that depends on both kind and user scale.
+	DISTANCE c;
+} MARKER_INFO;
+
+#define MARKER_INFO_DECL(I) MARKER_INFO I[1]; mr_info_init(I)
+
+typedef struct marker_extent_s {
+	COORD x, y, w, h;
+} MARKER_EXTENT;
+
+#define mr_deleted_p(M)		((M)->deleted_p)
+#define mr_set_deleted(M)	do { (M)->deleted_p = 1; } while (0)
+#define mr_merged(M)        ((M)->part_a >= 0)
+#define mr_x(M) ((M)->x)
+#define mr_y(M) ((M)->y)
+#define mr_r(M) ((M)->r)
+#define mr_w(M) ((M)->x - (M)->r)
+#define mr_e(M) ((M)->x + (M)->r)
+#define mr_s(M) ((M)->y - (M)->r)
+#define mr_n(M) ((M)->y + (M)->r)
+
+void mr_init(MARKER *marker, int n_markers);
+void mr_reset_parts(MARKER *marker);
+void mr_info_init(MARKER_INFO *info);
+void mr_info_set(MARKER_INFO *info, MARKER_KIND kind, DISTANCE scale);
+void mr_set(MARKER_INFO *info, MARKER *marker, COORD x, COORD y, SIZE size);
+void mr_merge(MARKER_INFO *info, MARKER *markers, int merged, int a, int b);
+DISTANCE mr_distance(MARKER_INFO *info, MARKER *a, MARKER *b);
+DISTANCE size_to_radius(MARKER_INFO *info, SIZE size);
+void get_marker_array_extent(MARKER *a, int n_markers, MARKER_EXTENT *ext);
+
+#endif /* MARKER_H_ */

data/ext/lulu/merger.c

@@ -0,0 +1,191 @@
+/*
+ * merger.c
+ *
+ *  Created on: Feb 24, 2014
+ *      Author: generessler
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <float.h>
+#include <assert.h>
+#include <time.h>
+#include "merger.h"
+#include "utility.h"
+#include "pq.h"
+#include "qt.h"
+#include "test.h"
+
+/**
+ * Repeatedly merge the closest pair of the given markers until they don't overlap.
+ *
+ * The centroid rule is used for merging.  I.e. each marker's area represents
+ * a population of points. Merging two markers removes the originals and creates a
+ * new marker with area the sum of the originals and center at the average position
+ * of the two merged populations.
+ *
+ * The markers array must include extra buffer space.  If there are n markers, the
+ * array must have 2n-1 spaces, with only the first n initialized.
+ *
+ * The number of markers after merging is returned. Zero or more of these will be
+ * marked deleted_p and should be ignored.
+ *
+ * This algorithm is O(n k log n), where k is the maximum number of simultaneously
+ * overlapping markers in the original, unmerged set.
+ */
+int merge_markers_fast(MARKER_INFO *info, MARKER *markers, int n_markers) {
+	int augmented_length = 2 * n_markers - 1;
+	NewArrayDecl(int, n_nghbr, augmented_length);
+	NewArrayDecl(DISTANCE, mindist, augmented_length);
+	NewArrayDecl(int, inv_nghbr_head, augmented_length);
+	NewArrayDecl(int, inv_nghbr_next, augmented_length);
+	NewArrayDecl(int, tmp, augmented_length); // Too big
+	// Do not free the following array!  It's owned by the priority queue.
+	NewArrayDecl(int, heap, augmented_length); // Too big
+
+	// Specialized quadtree supports finding closest marker to any given one.
+	QUADTREE_DECL(qt);
+
+	// Priority queue keyed on distances of overlapping pairs of markers.
+	PRIORITY_QUEUE_DECL(pq);
+
+	/// Extent of markers in the domain.
+	MARKER_EXTENT ext[1];
+
+	// Get a bounding box for the whole collection of markers.
+	get_marker_array_extent(markers, n_markers, ext);
+
+	// Set up the quadtree with the bounding box. Choose tree depth heuristically.
+	int max_depth = high_bit_position(n_markers) / 4 + 3;
+	qt_setup(qt, max_depth, ext->x, ext->y, ext->w, ext->h, info);
+
+	// Insert all the markers in the quadtree.
+	for (int i = 0; i < n_markers; i++)
+		qt_insert(qt, markers + i);
+
+	// Set all the inverse nearest neighbor links to null.
+	for (int i = 0; i < augmented_length; i++)
+		inv_nghbr_head[i] = inv_nghbr_next[i] = -1;
+
+	// Initialize the heap by adding an index for each overlapping pair. The
+	// The heap holds indices into the array of min-distance keys. An index for
+	// pair a->bis added iff markers with indices a and b overlap and b < a.
+	int heap_size = 0;
+	for (int a = 0; a < n_markers; a++) {
+		int b = qt_nearest_wrt(markers, qt, a);
+		if (0 <= b && b < a) {
+			n_nghbr[a] = b;
+			mindist[a] = mr_distance(info, markers + a, markers + b);
+			heap[heap_size++] = a;
+
+			// Here we are building a linked list of markers that have b as nearest.
+			inv_nghbr_next[a] = inv_nghbr_head[b];
+			inv_nghbr_head[b] = a;
+		}
+	}
+
+	// Now install the raw heap array into the priority queue. After this it's owned by the queue.
+	pq_set_up_heap(pq, heap, heap_size, mindist, augmented_length); // Too big
+
+	while (!pq_empty_p(pq)) {
+
+		// Get nearest pair from priority queue.
+		int a = pq_get_min(pq);
+		int b = n_nghbr[a];
+
+		// Delete both of the nearest pair from all data structures.
+		pq_delete(pq, b);
+		qt_delete(qt, markers + a);
+		qt_delete(qt, markers + b);
+		mr_set_deleted(markers + a);
+		mr_set_deleted(markers + b);
+
+		// Capture the inv lists of both a and b in tmp.
+		int tmp_size = 0;
+		for (int p = inv_nghbr_head[a]; p >= 0; p = inv_nghbr_next[p])
+			if (!markers[p].deleted_p)
+				tmp[tmp_size++] = p;
+		for (int p = inv_nghbr_head[b]; p >= 0; p = inv_nghbr_next[p])
+			if (!markers[p].deleted_p)
+				tmp[tmp_size++] = p;
+
+		// Create a new merged marker. Adding it after all others means
+		// nothing already in the heap could have it as nearest.
+		int aa = n_markers++;
+		mr_merge(info, markers, aa, a, b);
+
+		// Add to quadtree.
+		qt_insert(qt, markers + aa);
+
+		// Find nearest overlapping neighbor of the merged marker, if any.
+		int bb = qt_nearest_wrt(markers, qt, aa);
+		if (0 <= bb) {
+			n_nghbr[aa] = bb;
+			mindist[aa] = mr_distance(info, markers + aa, markers + bb);
+			pq_add(pq, aa);
+			inv_nghbr_next[aa] = inv_nghbr_head[bb];
+			inv_nghbr_head[bb] = aa;
+		}
+
+		// Reset the nearest neighbors of the inverse neighbors of the deletions.
+		for (int i = 0; i < tmp_size; i++) {
+			int aa = tmp[i];
+			int bb = qt_nearest_wrt(markers, qt, aa);
+			if (0 <= bb && bb < aa) {
+				n_nghbr[aa] = bb;
+				mindist[aa] = mr_distance(info, markers + aa, markers + bb);
+				pq_update(pq, aa);
+				inv_nghbr_next[aa] = inv_nghbr_head[bb];
+				inv_nghbr_head[bb] = aa;
+			} else {
+				pq_delete(pq, aa);
+			}
+		}
+	}
+	qt_clear(qt);
+	pq_clear(pq);
+	Free(n_nghbr);
+	Free(mindist);
+	Free(inv_nghbr_head);
+	Free(inv_nghbr_next);
+	Free(tmp);
+	return n_markers;
+}
+
+#ifndef EXCLUDE_UNIT_TEST
+
+#include <sys/time.h>
+
+/**
+ * Generate many random markers and then merge them. Write
+ * results as a Javascript array to be included included in a test page.
+ */
+int merge_test(int size) {
+	struct timeval start[1], stop[1], diff[1];
+
+	MARKER_INFO_DECL(info);
+	mr_info_set(info, CIRCLE, 2);
+
+	NewArrayDecl(MARKER, markers, 2 * size - 1);
+	mr_init(markers, 2 * size - 1);
+	set_random_markers(info, markers, size);
+
+	int m = emit_markers("before", markers, size);
+	fprintf(stderr, "before merge: %d\nmerging...\n", m);
+
+	gettimeofday(start, NULL);
+
+	size = merge_markers_fast(info, markers, size);
+
+	gettimeofday(stop, NULL);
+
+	int n = emit_markers("after", markers, size);
+	fprintf(stderr, "after merge: %d\n", n);
+
+	timersub(stop, start, diff);
+	fprintf(stderr, "%.3f seconds", diff->tv_sec + 1.0e-6 * diff->tv_usec);
+
+	return EXIT_SUCCESS;
+}
+
+#endif

data/ext/lulu/merger.h

@@ -0,0 +1,17 @@
+/*
+ * merger.h
+ *
+ *  Created on: Feb 24, 2014
+ *      Author: generessler
+ */
+
+#ifndef MERGER_H_
+#define MERGER_H_
+
+#include "marker.h"
+
+void merge_markers(MARKER_INFO *info, MARKER *markers, int markers_size);
+int merge_markers_fast(MARKER_INFO *info, MARKER *markers, int markers_size);
+int merge_test(int test_markers_size);
+
+#endif /* MERGER_H_ */

data/ext/lulu/pq.c

@@ -0,0 +1,244 @@
+/*
+ * priority_queue.c
+ *
+ * A priority queue with a min heap. This accepts an array
+ * of values and maintains a min heap of indices into the values array.
+ * There is also a reverse map that takes a value index to the heap
+ * element that refers to it. This allows values to be adjusted.
+ *
+ *  Created on: Feb 23, 2014
+ *      Author: generessler
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <assert.h>
+#include "utility.h"
+#include "pq.h"
+
+// Move index at heap location j upward until its parent's value is no bigger.
+static void pq_sift_up(PRIORITY_QUEUE *q, int j) {
+	int i = q->heap[j];
+	PRIORITY_QUEUE_VALUE val = q->values[i];
+	while (j > 0) {
+		int j_pnt = (j - 1) / 2;
+		if (q->values[q->heap[j_pnt]] <= val)
+			break;
+		int k = q->heap[j] = q->heap[j_pnt];
+		q->locs[k] = j;
+		j = j_pnt;
+	}
+	int k = q->heap[j] = i;
+	q->locs[k] = j;
+}
+
+// Move index at heap location j downward until its children's values are no smaller.
+// Pay some attention to efficiency because this is bottleneck code.
+static void pq_sift_down(PRIORITY_QUEUE *q, int j) {
+	int i = q->heap[j];
+	PRIORITY_QUEUE_VALUE val = q->values[i];
+	for (;;) {
+		int j_rgt = 2 * j + 2;
+		if (j_rgt < q->size) {
+			// two children
+			int j_lft = j_rgt - 1;
+			PRIORITY_QUEUE_VALUE val_lft = q->values[q->heap[j_lft]];
+			PRIORITY_QUEUE_VALUE val_rgt = q->values[q->heap[j_rgt]];
+			if (val_lft < val_rgt) {
+				if (val <= val_lft)
+					break;
+				int k = q->heap[j] = q->heap[j_lft];
+				q->locs[k] = j;
+				j = j_lft;
+			} else {
+				if (val <= val_rgt)
+					break;
+				int k = q->heap[j] = q->heap[j_rgt];
+				q->locs[k] = j;
+				j = j_rgt;
+			}
+		} else if (j_rgt == q->size) {
+			// left child only
+			int j_lft = j_rgt - 1;
+			if (val <= q->values[q->heap[j_lft]])
+				break;
+			int k = q->heap[j] = q->heap[j_lft];
+			q->locs[k] = j;
+			j = j_lft;
+			break; // this node has no children
+		} else {
+			break; // no children at all
+		}
+	}
+	int k = q->heap[j] = i;
+	q->locs[k] = j;
+}
+
+// Initialize a newly allocated priority queue structure.
+void pq_init(PRIORITY_QUEUE *q) {
+	q->max_size = q->size = 0;
+	q->heap = NULL;
+	q->locs = NULL;
+	q->values = NULL;
+}
+
+// Clear a previously initialized and possibly set up priority queue, returning
+// it to the initialized state but with all resourced freed.  Note the values
+// are owned by the user and are not freed here.
+void pq_clear(PRIORITY_QUEUE *q) {
+	Free(q->heap);
+	Free(q->locs);
+	pq_init(q);
+}
+
+// Build the queue with given pre-allocated and filled array of values.
+void pq_set_up(PRIORITY_QUEUE *q, PRIORITY_QUEUE_VALUE *values, int size) {
+	q->max_size = q->size = size;
+	q->values = values;
+	NewArray(q->heap, size);
+	NewArray(q->locs, size);
+	for (int i = 0; i < size; i++)
+		q->heap[i] = q->locs[i] = i;
+	// heapify
+	for (int j = size / 2 - 1; j >= 0; j--)
+		pq_sift_down(q, j);
+}
+
+// Build the queue with given pre-allocated and filled array of values
+// and given heap indices.  Note the indices are owned by the heap
+// after set up and will be freed with the heap.
+void pq_set_up_heap(PRIORITY_QUEUE *q, int *heap, int size,
+		PRIORITY_QUEUE_VALUE *values, int max_size) {
+	q->max_size = max_size;
+	q->values = values;
+	q->size = size;
+	q->heap = heap;
+	NewArray(q->locs, max_size);
+	for (int i = 0; i < max_size; i++)
+		q->locs[i] = -1;
+	for (int j = 0; j < size; j++)
+		q->locs[heap[j]] = j;
+	for (int j = size / 2 - 1; j >= 0; j--)
+		pq_sift_down(q, j);
+}
+
+// Return the index of the minimum value on the queue.
+int pq_peek_min(PRIORITY_QUEUE *q) {
+	return q->size <= 0 ? -1 : q->heap[0];
+}
+
+// Remove and return the index of the minimum value on the queue.
+int pq_get_min(PRIORITY_QUEUE *q) {
+	if (q->size <= 0)
+		return -1;
+	int i = q->heap[0];
+	q->locs[i] = -1;
+	if (--q->size > 0) {
+		q->heap[0] = q->heap[q->size];
+		pq_sift_down(q, 0);
+	}
+	return i;
+}
+
+// Add a new value with index i into the queue.
+void pq_add(PRIORITY_QUEUE *q, int i) {
+	if (q->size >= q->max_size)
+		return;
+	int j = q->size++;
+	q->heap[j] = i;
+	pq_sift_up(q, j);
+}
+
+// Restore the heap after the value at index i is changed.
+void pq_update(PRIORITY_QUEUE *q, int i) {
+	int j = q->locs[i];
+	if (j >= 0) {
+		pq_sift_down(q, j);
+		pq_sift_up(q, j);
+	}
+}
+
+// Delete index i from the heap, making the corresponding key an orphan.
+void pq_delete(PRIORITY_QUEUE *q, int i) {
+	int j = q->locs[i];
+	if (0 <= j) {
+		q->locs[i] = -1;
+		if (j < --q->size) {
+			q->heap[j] = q->heap[q->size];
+			pq_sift_down(q, j);
+			pq_sift_up(q, j);
+		}
+	}
+}
+
+#ifndef EXCLUDE_UNIT_TEST
+
+/* Randomly permute the given distance array. */
+void permute(PRIORITY_QUEUE_VALUE *a, int size) {
+	for (int i = size - 1; i > 0; i--) {
+		int j = rand() % (i + 1);
+		PRIORITY_QUEUE_VALUE tmp = a[i];
+		a[i] = a[j];
+		a[j] = tmp;
+	}
+}
+
+// Run a unit test on a priority queue of random data with given size.
+int pq_test(int size) {
+	PRIORITY_QUEUE q[1];
+	pq_init(q);
+
+	fprintf(stderr, "test: heap_ops (n = %d):\n", size);
+
+	// Build linear pointer array of random keys.
+	PRIORITY_QUEUE_VALUE *dist;
+	NewArray(dist, size);
+	for (int i = 0; i < size; i++)
+		dist[i] = i;
+	permute(dist, size);
+	fprintf(stderr, "  built random data\n");
+
+	pq_set_up(q, dist, size);
+	fprintf(stderr, "  finished set up\n");
+
+	// Pull min repeatedly and verify vals are what they should be.
+	PRIORITY_QUEUE_VALUE should_be = 0;
+	for (int n = 0; n < size; n++) {
+		int i = pq_get_min(q);
+		if (dist[i] != should_be++) {
+			fprintf(stderr, "fail 1: %i -> %g\n", i, dist[i]);
+			return 42;
+		}
+	}
+	fprintf(stderr, "  finished checking heapify\n");
+
+	// Now rebuild the heap by inserting one key at a time.
+	for (int n = 0; n < size; n++)
+		pq_add(q, n);
+	fprintf(stderr, "  finished insertions\n");
+
+	// And verify values again.
+	should_be = 0;
+	for (int n = 0; n < size; n++) {
+		int i = pq_get_min(q);
+		if (dist[i] != should_be++) {
+			fprintf(stderr, "  fail 2: %i -> %g\n", i, dist[i]);
+			return 4242;
+		}
+	}
+	fprintf(stderr, "  finished checking insert\n");
+
+	// Now rebuild the heap by inserting one key at a time in reverse.
+	for (int n = size - 1; n >= 0; n--)
+		pq_add(q, n);
+	fprintf(stderr, "  finished reverse insertions\n");
+
+	// Now delete one by one.
+	for (int n = 0; n < size; n++)
+		pq_delete(q, n);
+	fprintf(stderr, "  finished reverse deletions\n");
+
+	pq_clear(q);
+	return 0;
+}
+
+#endif

data/ext/lulu/pq.h

@@ -0,0 +1,70 @@
+/*
+ * priority_queue.h
+ *
+ *  Created on: Feb 23, 2014
+ *      Author: generessler
+ */
+
+#ifndef PRIORITY_QUEUE_H_
+#define PRIORITY_QUEUE_H_
+
+typedef double PRIORITY_QUEUE_VALUE;
+
+typedef struct priority_queue_s {
+	int max_size;					// max number of items in heap
+	int size;						// current number of items in heap
+	int *heap;						// heap of indices to values
+	int *locs;						// map of value indices to heap locations
+	PRIORITY_QUEUE_VALUE *values;	// values referred to by heap
+} PRIORITY_QUEUE;
+
+// Initialize a newly allocated priority queue structure.
+void pq_init(PRIORITY_QUEUE *q);
+
+#define PRIORITY_QUEUE_DECL(Q) PRIORITY_QUEUE Q[1]; pq_init(Q)
+
+// Clear a previously initialized and possibly set up priority queue, returning
+// it to the initialized state but with all resourced freed.
+void pq_clear(PRIORITY_QUEUE *q);
+
+// Build the queue with given pre-allocated and filled array of values.
+void pq_set_up(PRIORITY_QUEUE *q, PRIORITY_QUEUE_VALUE *values, int size);
+
+// Build the queue with given pre-allocated and filled array of values
+// and given heap indices.  Note the indices are owned by the heap
+// after set up and will be freed with the heap.
+void pq_set_up_heap(PRIORITY_QUEUE *q,
+		int *heap, int size,
+		PRIORITY_QUEUE_VALUE *values, int max_size);
+
+// Return the index of the minimum value on the queue.
+int pq_peek_min(PRIORITY_QUEUE *q);
+
+// Remove and return the index of the minimum value on the queue.
+int pq_get_min(PRIORITY_QUEUE *q);
+
+// Update the queue given that the value at index i has changed.
+void pq_update(PRIORITY_QUEUE *q, int i);
+
+// Add a new value with index i into the queue.
+void pq_add(PRIORITY_QUEUE *q, int i);
+
+// Delete index i from the heap, making the corresponding key an orphan.
+void pq_delete(PRIORITY_QUEUE *q, int i);
+
+// Return an array containing indices currently in the heap.
+#define pq_index_set(Q)			((Q)->heap)
+
+// Return an array containing indices currently in the heap.
+#define pq_index(Q, I)			((Q)->heap[I])
+
+// Return the size of the index array contained above.
+#define pq_index_set_size(Q)	((Q)->size)
+
+// Return non-zero iff the queue is empty.
+#define pq_empty_p(Q) ((Q)->size <= 0)
+
+// Run the heap module through some unit tests.
+int pq_test(int size);
+
+#endif /* PRIORITY_QUEUE_H_ */