Table of Contents

    Introduction
    Portability
    Manifest
    Installation
    Application Setups
    Application Output
    Documentation
    Notes


Introduction

    Unify is a code library that programmers can link with their
    programs to write distributed shared memory programs.


Portability

    Unify currently works under Solaris versions 2.3, 2.4, and 2.5.1.
    See the INSTALL file for instructions on configuring Unify.
    Future versions will run under Linux.


Manifest

    The following directories are included under the top level directory

    unify/include	headers for the Unify library
    unify/src		source for the Unify library
    apps		sample application programs using the Unify library
    events		an event counter and sequencer library use by Unify
    threads		thread packages used by Unify
    tmksim		a library to allow easy porting of TreadMarks programs
    tmtp		tree based multicast protocol (currently not used)
    tools		tools to help develop Unify programs

    The following applications are included in the apps directory

    apps/hello_ran	simple "hello world" with random segments
    apps/hello_seq	simple "hello world" with sequential-access segments
    apps/gu_false	simple example of Get_Updates with false sharing
    apps/matmul		matrix multiplication benchmark
    apps/sor_ran	SOR benchmark with only random segments
    apps/sor_seq	SOR benchmark with sequential-access segments
    apps/water_ran	SPLASH Water benchmark with only random segments
    apps/water_seq	SPLASH Water benchmark with sequential-access segments


Installation

    See the INSTALL file for instructions on installing Unify and
    running Unify applications.


Application Setups

    In each application, the definition of the problem size may be changed
    to fit a particular test.  Here is a quick list of the key factors
    in each benchmark, and where they are found.

    matmul:
	In matmul.c, the symbols M,N,P define the dimensions of the three
	matrices, such that (MxN) * (NxP = (MxP).
	In the distribution, these values are each 512.

	In matmul.c, the symbol OUTPUT_FILE defines the output file prefix
	for the workers.  See below for more information.

        In matmul.c, the symbol VERIFY should be defined if you want
	the master worker to verify the reported results.  If defined,
	be aware that the application run will take a few miniutes longer.

    sor_ran, and sor_seq:
        In func.h, N defines the size of the NxN grid.

	In func.h, NUM_ITER defines the number of iterations.

	In func.h, OUTPUT_FILE defines the output file prefix for the
	workers.  See below for more information.

        In func.h, the symbol VERIFY should be defined if you want
	the master worker to verify the reported results.  If defined,
	be aware that the application run will take a few minutes longer.

    water_ran and water_seq:
	In misc.h, INPUT_FILE defines the absolute filename of the file 'input'.

	In misc.h, RANDOM_FILE defines the absolute filename of the file
	'random.in'.

	In misc.h, OUTPUT_FILE defines the output file prefix for the
	workers.  See below for more information.

	The second number in the file 'input' defines the number of molecules
	to use, and the third number defines the number of iterations.


    These definitions may be changed to fit your needs.

    In addition, the Water benchmarks use an input file of random numbers.


Application Output

    The applications send output of the initialization and startup
    to stdout.  The output from the application code is sent to output
    files if OUTPUT_FILE is defined as stated above.  So that each
    worker writes to a unique file, output files are named with this
    convention:
	<OUTPUT_FILE>.<Num_Workers>.<worker_seq>
    where <worker_seq> is a number from 1 to <Num_Workers>.
    For example, the output of worker one of eight in a random SOR run
    will have it's output in sor_random.8.1

    If you wish all application output to go to stdout, undefine
    OUTPUT_FILE for that application.  You will still be able to tell
    which line of output came from which worker since the worker's
    sequence number will appear at the beginning of a line.  However,
    this approach can be difficult to read, especially if the output
    is large.


Documentation

    More documentation is available in the doc directory.  Much of the
    documentation is incomplete.  A summary of most of the Unify API
    is provided in the text file primitives.  unifyintro.html contains
    a brief introduction to Unify.  Other HTML files in the doc
    directory describe Unify API calls and other Unify concepts.


Notes

    In this release, the events (SEC) package is not used by default due
    to some implementation problems.  Rather, events and sequencers are
    implemented by a unicast protocol in the unify library.
