.TH "allpairs_multicore" 1 "" "CCTools 7.1.2 FINAL" "Cooperative Computing Tools"

.SH NAME
.LP
\fBallpairs_multicore\fP - executes All-Pairs workflow in parallel on a multicore machine

.SH SYNOPSIS
.LP
\FC\fBallparis_multicore [options] <set A> <set B> <compare function>\fP\FT

.SH DESCRIPTION
.LP

\fBallpairs_multicore\fP computes the Cartesian product of two sets
(\fB<set A>\fP and \fB<set B>\fP), generating a matrix where each cell
M[i,j] contains the output of the function F (\fB<compare function>\fP) on
objects A[i] (an item in \fB<set A>\fP) and B[j] (an item in
\fB<set B>\fP). The resulting matrix is displayed on the standard output,
one comparison result per line along with the associated X and Y indices.
.PP
For large sets of objects, \fBallpairs_multicore\fP will use as many cores as
you have available, and will carefully manage virtual memory to exploit
locality and avoid thrashing. Because of this, you should be prepared for the
results to come back in any order. If you want to further exploit the
parallelism of executing All-Pairs workflows on multiple (multicore) machines,
please refer to the \fBallpairs_master(1)\fP utility.

.SH OPTIONS
.LP

.LP
.TP
\fB-b\fP, \fB-\-block-size\fP=\fI<items>\fP
.
Block size: number of items to hold in memory at once. (default: 50% of RAM)
.TP
\fB-c\fP, \fB-\-cores\fP=\fI<cores>\fP
.
Number of cores to be used. (default: # of cores in machine)
.TP
\fB-e\fP, \fB-\-extra-args\fP=\fI<args>\fP
.
Extra arguments to pass to the comparison program.
.TP
\fB-d\fP, \fB-\-debug\fP=\fI<flag>\fP
.
Enable debugging for this subsystem.
.TP
.B \ -v, --version
.
Show program version.
.TP
.B \ -h, --help
.
Display this message.


.SH EXIT STATUS
.LP
On success, returns zero.  On failure, returns non-zero.

.SH EXAMPLES
.LP

Let's suppose you have a whole lot of files that you want to compare all to
each other, named \FCa\FT, \FCb\FT, \FCc\FT, and so on. Suppose that you also
have a program named \FC\fBcompareit\fP\FT that when invoked as \FCcompareit a b\FT
will compare files \FCa\FT and \FCb\FT and produce some output summarizing the
difference between the two, like this:

.fam C
.nf
.nh
.IP "" 8
 a b are 45 percent similar
.fi
.hy
.fam
.P

To use the allpairs framework, create a file called \FCset.list\FT that lists each of
your files, one per line:

.fam C
.nf
.nh
.IP "" 8
 a
 b
 c
 ...
.fi
.hy
.fam
.P

Then, invoke \fBallpairs_multicore\fP like this:

.fam C
.nf
.nh
.IP "" 8
 % allpairs_multicore set.list set.list compareit
.fi
.hy
.fam
.P

The framework will carry out all possible comparisons of the objects, and print
the results one by one (note that the first two columns are X and Y indices in
the resulting matrix):

.fam C
.nf
.nh
.IP "" 8
 1	1	a a are 100 percent similar
 1	2	a b are 45 percent similar
 1	3	a c are 37 percent similar
 ...
.fi
.hy
.fam
.P

.SH COPYRIGHT
.LP

The Cooperative Computing Tools are Copyright (C) 2005-2019 The University of Notre Dame.  This software is distributed under the GNU General Public License.  See the file COPYING for details.

.SH SEE ALSO
.LP


.IP \(bu 4
The Cooperative Computing Tools (\fB"http://ccl.cse.nd.edu/software/manuals"\fP)
.IP \(bu 4
All-Pairs User Manual (\fB"http://ccl.cse.nd.edu/software/manuals/allpairs.html"\fP)
.IP \(bu 4
\fBallpairs_master(1)\fP