This module will create sorting networks, a sequence of comparisons
that do not depend upon the results of prior comparisons.

Since the sequences and their order never change, they can be very
useful if deployed in hardware, or if used in software with a compiler
that can take advantage of parallelism. Unfortunately a sorting network cannot
be used for generic run-time sorting like quicksort, since the arrangement of
the comparisons is fixed according to the number of elements to be
sorted.

This modules main purpose is to create compare-and-swap macros (or
functions, or templates) that one may insert into source code. It may
also be used to create images of the sorting networks in either encapsulated
postscript (EPS), scalar vector graphics (SVG), or in ascii art format.

None by default. There is only one available export tag, :all, which
exports the functions to create and use sorting networks. The functions are
nw_algorithms(), nw_algorithm_name(), nw_comparator(), nw_format(), nw_graph(),
nw_color(), nw_group(), and nw_sort().

Returns a list of comparators that can sort <B>B>$inputs<B>B>
items. The algorithm for generating the list may be chosen, but by default the
sorting network is generated by the Bose-Nelson algorithm. The different methods will
produce different networks in general, although in some cases the differences
will be in the arrangement of the comparators, not in their number.

Regardless of the algorithm you use, you may not get the comparators in the best
order possible to prevent stalling in a CPUs pipeline. So a third option,
grouping, is available that arranges the comparators in a slightly different
order by calling nw_group() and flattening the array of arrays by taking the
comparators in order. See also the documentation for nw_group().

Use the Bose-Nelson algorithm to generate the network. This is the most
commonly implemented algorithm, recursive and simple to code.

hibbard

Use Hibbards algorithm. This iterative algorithm was developed after the
Bose-Nelson algorithm was published, and produces a different network
... for generating the comparisons one by one in the order in which
they are needed for sorting, according to his article (see below).

batcher

Use Batchers Merge Exchange algorithm. Merge Exchange is a real sort, in
that in its usual form (for example, as described in Knuth) it can handle
a variety of inputs. But while sorting it always generates an identical set of
comparison pairs per array size, which lends itself to sorting networks.

bitonic

Use Batchers bitonic algorithm. A bitonic sequence is a sequence that
monotonically increases and then monotonically decreases. The bitonic sort
algorithm works by recursively splitting sequences into bitonic sequences
using so-called half-cleaners. These bitonic sequences are then merged
into a fully sorted sequence. Bitonic sort is a very efficient sort and
is especially suited for implementations that can exploit network
parallelism.

bubble

Use a naive bubble-sort/insertion-sort algorithm. Since this algorithm
produces more comparison pairs than the other algorithms, it is only
useful for illustrative purposes.

best

For some inputs, sorting networks have been discovered that are more efficient
than those generated by rote algorithms. When best is specified one
of these are returned instead. The term best does not actually guarantee
the best network for all cases. It simply means that at the time of this
version of the module, the network returned has the lowest number of
comparators for the number of inputs. Considerations of parallelism, or of
other networks with an equally low comparator count but with a different
arrangement are ignored.

Currently more efficient sorting networks have been discoverd for inputs of
nine through sixteen, eighteen, and twenty-two. If you choose best outside
of this range the module will fall back to Batchers Merge Exchange algorithm.

nw_format()

$string = nw_format(\@network, $format1, $format2, \@index_base);

Returns a formatted string that represents the list of comparators.
There are two sprintf-style format strings, which lets you separate
the comparison and exchange portions if you want. The second format
string is optional.

The first format string may also be ignored, in which case the default
format will be used: an array of arrays as represented in perl.

The network sorting pairs are zero-based. If you want the pairs written out
for some sequence other than 0, 1, 2, ... then you can provide that in
an array reference.

All parts not named are reset to undef, and will be colored with the
default foreground color. The foreground color itself has a default
value of black. The one exception is the background color, which
has no default color at all.

nw_graph()

Returns a string that graphs out the networks comparators. The format
may be encapsulated postscript (graph=>eps), scalar vector graphics
(graph=>svg), or the default plain text (graph=>text or none). The text
and eps options produce output that is self-contained. The svg option
produces output between <svg> and </svg> tags, which needs
to be combined with XML markup in order to be viewed.

Default value: 9.
The indention between the start of the input lines and the placement of
the first comparator. The same value spaces the placement of the final
comparator and the end of the input lines.

stroke_width

Default value: 2.
Width of the lines used to define comparators and input lines. Also
represents the radii of the endpoint circles.

title

Default value: N = $inputs Sorting Network.
Title of the graph. It should be a short one-line description.

vt_margin

Default value: 21.
The vertical spacing between the edges of the graphic and the sorting network.

Default value: -|-.
The characters that make up an input line that has a comparator crossing
over it.

inputend

Default value: -o\n.
The characters that make up the end of an input line.

compbegin

Default value: -^-.
The characters that make up an input line with the starting point of
a comparator.

compend

Default value: -v-.
The characters that make up an input line with the end point of
a comparator.

gapbegin

Default value: (two spaces).
The characters that start the gap between the input lines.

gapcompline

Default value: | (space vertical bar space).
The characters that make up the gap with a comparator passing through.

gapnone

Default value: (three spaces).
The characters that make up the space between the input lines.

gapend

Default value: \n (two spaces and a newline).
The characters that end the gap between the input lines.

nw_group()

This is a function called by nw_graph() and optionally by nw_comparators(). The
function takes the comparator list and returns a list of comparator lists, each
sub-list representing a group of comparators that can be printed in a single
column. There is one option available, grouping, that will produce a grouping
that represents parallel operations of comparators.

The chances that you will need to use this function are slim, but the
following code snippet may represent an example:

There are 19 comparators in this network, grouped into 6 parallel operations.
[[0,4],[1,5],[2,6],[3,7]]
[[0,2],[1,3],[4,6],[5,7]]
[[2,4],[3,5],[0,1],[6,7]]
[[2,3],[4,5]]
[[1,4],[3,6]]
[[1,2],[3,4],[5,6]]
This will be graphed in 11 columns.

nw_sort()

Sort an array using the network. This is meant for testing purposes
only - looping around an array of comparators in order to sort an
array in an interpreted language is not the most efficient mechanism
for using a sorting network.

Kenneth Batcher, Sorting Networks and their Applications, Proc. of the
AFIPS Spring Joint Computing Conf., Vol. 32, 1968, pp. 307-3114. A PDF of
this article may be found at <http://www.cs.kent.edu/~batcher/sort.pdf>.

The paper discusses both the Odd-Even Merge algorithm and the Bitonic algorithm.