226 lines
9.5 KiB
TeX
226 lines
9.5 KiB
TeX
\section{\module{heapq} ---
|
||
Heap queue algorithm}
|
||
|
||
\declaremodule{standard}{heapq}
|
||
\modulesynopsis{Heap queue algorithm (a.k.a. priority queue).}
|
||
\moduleauthor{Kevin O'Connor}{}
|
||
\sectionauthor{Guido van Rossum}{guido@python.org}
|
||
% Theoretical explanation:
|
||
\sectionauthor{Fran\c cois Pinard}{}
|
||
\versionadded{2.3}
|
||
|
||
|
||
This module provides an implementation of the heap queue algorithm,
|
||
also known as the priority queue algorithm.
|
||
|
||
Heaps are arrays for which
|
||
\code{\var{heap}[\var{k}] <= \var{heap}[2*\var{k}+1]} and
|
||
\code{\var{heap}[\var{k}] <= \var{heap}[2*\var{k}+2]}
|
||
for all \var{k}, counting elements from zero. For the sake of
|
||
comparison, non-existing elements are considered to be infinite. The
|
||
interesting property of a heap is that \code{\var{heap}[0]} is always
|
||
its smallest element.
|
||
|
||
The API below differs from textbook heap algorithms in two aspects:
|
||
(a) We use zero-based indexing. This makes the relationship between the
|
||
index for a node and the indexes for its children slightly less
|
||
obvious, but is more suitable since Python uses zero-based indexing.
|
||
(b) Our pop method returns the smallest item, not the largest (called a
|
||
"min heap" in textbooks; a "max heap" is more common in texts because
|
||
of its suitability for in-place sorting).
|
||
|
||
These two make it possible to view the heap as a regular Python list
|
||
without surprises: \code{\var{heap}[0]} is the smallest item, and
|
||
\code{\var{heap}.sort()} maintains the heap invariant!
|
||
|
||
To create a heap, use a list initialized to \code{[]}, or you can
|
||
transform a populated list into a heap via function \function{heapify()}.
|
||
|
||
The following functions are provided:
|
||
|
||
\begin{funcdesc}{heappush}{heap, item}
|
||
Push the value \var{item} onto the \var{heap}, maintaining the
|
||
heap invariant.
|
||
\end{funcdesc}
|
||
|
||
\begin{funcdesc}{heappop}{heap}
|
||
Pop and return the smallest item from the \var{heap}, maintaining the
|
||
heap invariant. If the heap is empty, \exception{IndexError} is raised.
|
||
\end{funcdesc}
|
||
|
||
\begin{funcdesc}{heapify}{x}
|
||
Transform list \var{x} into a heap, in-place, in linear time.
|
||
\end{funcdesc}
|
||
|
||
\begin{funcdesc}{heapreplace}{heap, item}
|
||
Pop and return the smallest item from the \var{heap}, and also push
|
||
the new \var{item}. The heap size doesn't change.
|
||
If the heap is empty, \exception{IndexError} is raised.
|
||
This is more efficient than \function{heappop()} followed
|
||
by \function{heappush()}, and can be more appropriate when using
|
||
a fixed-size heap. Note that the value returned may be larger
|
||
than \var{item}! That constrains reasonable uses of this routine
|
||
unless written as part of a conditional replacement:
|
||
\begin{verbatim}
|
||
if item > heap[0]:
|
||
item = heapreplace(heap, item)
|
||
\end{verbatim}
|
||
\end{funcdesc}
|
||
|
||
Example of use:
|
||
|
||
\begin{verbatim}
|
||
>>> from heapq import heappush, heappop
|
||
>>> heap = []
|
||
>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
|
||
>>> for item in data:
|
||
... heappush(heap, item)
|
||
...
|
||
>>> ordered = []
|
||
>>> while heap:
|
||
... ordered.append(heappop(heap))
|
||
...
|
||
>>> print ordered
|
||
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
|
||
>>> data.sort()
|
||
>>> print data == ordered
|
||
True
|
||
>>>
|
||
\end{verbatim}
|
||
|
||
The module also offers three general purpose functions based on heaps.
|
||
|
||
\begin{funcdesc}{merge}{*iterables}
|
||
Merge multiple sorted inputs into a single sorted output (for example, merge
|
||
timestamped entries from multiple log files). Returns an iterator over
|
||
over the sorted values.
|
||
|
||
Similar to \code{sorted(itertools.chain(*iterables))} but returns an iterable,
|
||
does not pull the data into memory all at once, and reduces the number of
|
||
comparisons by assuming that each of the input streams is already sorted.
|
||
\versionadded{2.6}
|
||
\end{funcdesc}
|
||
|
||
\begin{funcdesc}{nlargest}{n, iterable\optional{, key}}
|
||
Return a list with the \var{n} largest elements from the dataset defined
|
||
by \var{iterable}. \var{key}, if provided, specifies a function of one
|
||
argument that is used to extract a comparison key from each element
|
||
in the iterable: \samp{\var{key}=\function{str.lower}}
|
||
Equivalent to: \samp{sorted(iterable, key=key, reverse=True)[:n]}
|
||
\versionadded{2.4}
|
||
\versionchanged[Added the optional \var{key} argument]{2.5}
|
||
\end{funcdesc}
|
||
|
||
\begin{funcdesc}{nsmallest}{n, iterable\optional{, key}}
|
||
Return a list with the \var{n} smallest elements from the dataset defined
|
||
by \var{iterable}. \var{key}, if provided, specifies a function of one
|
||
argument that is used to extract a comparison key from each element
|
||
in the iterable: \samp{\var{key}=\function{str.lower}}
|
||
Equivalent to: \samp{sorted(iterable, key=key)[:n]}
|
||
\versionadded{2.4}
|
||
\versionchanged[Added the optional \var{key} argument]{2.5}
|
||
\end{funcdesc}
|
||
|
||
The latter two functions perform best for smaller values of \var{n}. For larger
|
||
values, it is more efficient to use the \function{sorted()} function. Also,
|
||
when \code{n==1}, it is more efficient to use the builtin \function{min()}
|
||
and \function{max()} functions.
|
||
|
||
|
||
\subsection{Theory}
|
||
|
||
(This explanation is due to Fran<61>ois Pinard. The Python
|
||
code for this module was contributed by Kevin O'Connor.)
|
||
|
||
Heaps are arrays for which \code{a[\var{k}] <= a[2*\var{k}+1]} and
|
||
\code{a[\var{k}] <= a[2*\var{k}+2]}
|
||
for all \var{k}, counting elements from 0. For the sake of comparison,
|
||
non-existing elements are considered to be infinite. The interesting
|
||
property of a heap is that \code{a[0]} is always its smallest element.
|
||
|
||
The strange invariant above is meant to be an efficient memory
|
||
representation for a tournament. The numbers below are \var{k}, not
|
||
\code{a[\var{k}]}:
|
||
|
||
\begin{verbatim}
|
||
0
|
||
|
||
1 2
|
||
|
||
3 4 5 6
|
||
|
||
7 8 9 10 11 12 13 14
|
||
|
||
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
|
||
\end{verbatim}
|
||
|
||
In the tree above, each cell \var{k} is topping \code{2*\var{k}+1} and
|
||
\code{2*\var{k}+2}.
|
||
In an usual binary tournament we see in sports, each cell is the winner
|
||
over the two cells it tops, and we can trace the winner down the tree
|
||
to see all opponents s/he had. However, in many computer applications
|
||
of such tournaments, we do not need to trace the history of a winner.
|
||
To be more memory efficient, when a winner is promoted, we try to
|
||
replace it by something else at a lower level, and the rule becomes
|
||
that a cell and the two cells it tops contain three different items,
|
||
but the top cell "wins" over the two topped cells.
|
||
|
||
If this heap invariant is protected at all time, index 0 is clearly
|
||
the overall winner. The simplest algorithmic way to remove it and
|
||
find the "next" winner is to move some loser (let's say cell 30 in the
|
||
diagram above) into the 0 position, and then percolate this new 0 down
|
||
the tree, exchanging values, until the invariant is re-established.
|
||
This is clearly logarithmic on the total number of items in the tree.
|
||
By iterating over all items, you get an O(n log n) sort.
|
||
|
||
A nice feature of this sort is that you can efficiently insert new
|
||
items while the sort is going on, provided that the inserted items are
|
||
not "better" than the last 0'th element you extracted. This is
|
||
especially useful in simulation contexts, where the tree holds all
|
||
incoming events, and the "win" condition means the smallest scheduled
|
||
time. When an event schedule other events for execution, they are
|
||
scheduled into the future, so they can easily go into the heap. So, a
|
||
heap is a good structure for implementing schedulers (this is what I
|
||
used for my MIDI sequencer :-).
|
||
|
||
Various structures for implementing schedulers have been extensively
|
||
studied, and heaps are good for this, as they are reasonably speedy,
|
||
the speed is almost constant, and the worst case is not much different
|
||
than the average case. However, there are other representations which
|
||
are more efficient overall, yet the worst cases might be terrible.
|
||
|
||
Heaps are also very useful in big disk sorts. You most probably all
|
||
know that a big sort implies producing "runs" (which are pre-sorted
|
||
sequences, which size is usually related to the amount of CPU memory),
|
||
followed by a merging passes for these runs, which merging is often
|
||
very cleverly organised\footnote{The disk balancing algorithms which
|
||
are current, nowadays, are
|
||
more annoying than clever, and this is a consequence of the seeking
|
||
capabilities of the disks. On devices which cannot seek, like big
|
||
tape drives, the story was quite different, and one had to be very
|
||
clever to ensure (far in advance) that each tape movement will be the
|
||
most effective possible (that is, will best participate at
|
||
"progressing" the merge). Some tapes were even able to read
|
||
backwards, and this was also used to avoid the rewinding time.
|
||
Believe me, real good tape sorts were quite spectacular to watch!
|
||
From all times, sorting has always been a Great Art! :-)}.
|
||
It is very important that the initial
|
||
sort produces the longest runs possible. Tournaments are a good way
|
||
to that. If, using all the memory available to hold a tournament, you
|
||
replace and percolate items that happen to fit the current run, you'll
|
||
produce runs which are twice the size of the memory for random input,
|
||
and much better for input fuzzily ordered.
|
||
|
||
Moreover, if you output the 0'th item on disk and get an input which
|
||
may not fit in the current tournament (because the value "wins" over
|
||
the last output value), it cannot fit in the heap, so the size of the
|
||
heap decreases. The freed memory could be cleverly reused immediately
|
||
for progressively building a second heap, which grows at exactly the
|
||
same rate the first heap is melting. When the first heap completely
|
||
vanishes, you switch heaps and start a new run. Clever and quite
|
||
effective!
|
||
|
||
In a word, heaps are useful memory structures to know. I use them in
|
||
a few applications, and I think it is good to keep a `heap' module
|
||
around. :-)
|