/** @page start

Downloading the Source {#start_get}

The latest release of Active Harmony can always be found at:

http://www.dyninst.org/harmony

Release tarballs represent snapshots of our development repository in a tested and stable state. If you'd like to try new features or bug fixes, you can download a version directly from our Git repository:

Directly via git:

git clone http://git.dyninst.org/activeharmony.git

Or, through our repository's web interface at:

http://git.dyninst.org/?p=activeharmony.git;a=summary

Installation {#start_install}

Once you obtain a copy of the source tree (via tarball or Git), the following utilities are necessary for a successful build:

GNU Make
C99-compliant compiler

To build and install Active Harmony, issue the following command:

$ make install

By default, this will create relevant files within the source tree. If you'd like to install the software elsewhere, use the PREFIX variable:

$ make install PREFIX=$HOME/local/harmony-4.6.0

This make system is also sensitive to standard build flags supplied by the environment:

$ make CFLAGS=-O3 LDFLAGS=-L/usr/local/lib64

Furthermore, some processing layers bundled with Active Harmony depend on external packages. Build targets with such a dependency are protected behind specific environment variables. The make system will only attempt to build the processing layer if the associated package variable is defined. Otherwise, that target is skipped.

Dependent Package Variables Layer | Variable | Package Download URL ---------- | ---------- | -------------------- TAUdb | LIBTAUDB | http://www.cs.uoregon.edu/research/tau/downloads.php XML Writer | LIBXML2 | http://www.xmlsoft.org/downloads.html

Additional details on any of these build variables can be found in their respective Processing Layer documentation page of the User's Guide.

Building the Documentation {#start_doc}

The following software packages will also be necessary to build the documentation:

Doxygen
TeX Live (pdflatex)
Inkscape

To generate documentation in PDF and HTML formats, issue the following command:

$ make doc

This should leave .pdf files and .html directories in the doc/ directory.

Testing the Installation {#start_test}

There are two separate modes of operation for using Active Harmony, standalone mode and server mode. Both modes are described below and can be used to verify a successful build.

Standalone Mode {#start_test_standalone}

This is the default model for Active Harmony clients. When initiating a new tuning session, the target application spawns its own dedicated tuning process automatically.

Correct operation relies on the HARMONY_HOME environment variable. It should be set to wherever your version of Active Harmony has been installed. Namely, it should match the PREFIX variable used during make install. For example, the following command would match the installation described in the [Installation](\ref start_install) section above (assuming Bourne shell semantics):

$ export HARMONY_HOME=$HOME/local/harmony-4.6.0

If no PREFIX variable was used during make install, HARMONY_HOME should be set to the base directory of the source tree.

Navigate to the example/client_api source directory. The file minimal should exist if the build was successful. If HARMONY_HOME environment variable is set up correctly, the example should be immediately executable. The example may be run as follows:

$ ./minimal

This should produce the output similar to the following:

Starting Harmony...
( 481, 0.5269, "pineapple") = 874545.454545
( 490, 0.3286, "oranges") = 1119872.185027
( 655, 0.5611, "grapes") = 749438.602745
( 373, 0.5836, "grapes") = 410325.565456
( 516, 0.7858, "peaches") = 478701.959786

<... snip ...>

(   1, 1.0000, "figs") = 425.000000
(   1, 1.0000, "figs") = 425.000000
(   1, 0.9999, "figs") = 425.042504
(   1, 1.0000, "figs") = 425.000000
(   1, 1.0000, "figs") = 425.000000 (* Best point found. *)

This example uses a simple arithmetic function with six variables to produce a synthetic performance value.

Server Mode {#start_test_server}

This running model requires tuning clients to communicate to a server via a TCP connection. To run the server:

$ ./hserver [-p PORT]

Once the server is running, we must inform the client to use it. This is accomplished through two environment variables, HARMONY_HOST and HARMONY_PORT. As a quick example, to run the previous example in server mode, one could use the following command (assuming Bourne shell semantics):

$ HARMONY_HOST=localhost ./minimal

If HARMONY_HOST is defined, the example will attempt to contact a Harmony Server listening on the specified host (in this case, localhost) on port 1979. If you wish to connect to a server running on a different port, set the HARMONY_PORT environment variable. For example:

$ export HARMONY_HOST=other.host.net
$ export HARMONY_PORT=2013

An additional perk of running in Server Mode is the web interface. Simply point a javascript-enabled browser to the host:port of a running Harmony Server, and it will provide a visual interface for any tuning sessions under its control.

Exploring Further {#start_explore}

Now that you have a sample Harmony client working, you can begin to explore the flexibility of the Active Harmony framework. All the examples below make use of the [Configuration System](\ref cfg), which is documented in the User's Manual.

By default, the PRO search strategy is used. It can easily be changed by setting the STRATEGY configuration variable. This way, search strategies are easily comparable. For instance, the following example instructs the session to use a random search strategy instead:

$ ./minimal STRATEGY=random.so

In addition to changing the core search strategy, additional [processing layers](\ref layers) can be easily added to the feedback loop. For instance, if you'd like to write a log of the search session to disk, use the [Point Logger](\ref logger) processing layer:

$ ./minimal LAYERS=log.so LOG_FILE=search.log

Wall-time is a non-deterministic performance metric. Multiple factors such as competing processes, or even CPU temperature can perturb measurement. This phenomenon can be mitigated by performing multiple tests of each point and aggregating the results with the [Aggregator](\ref agg) processing layer:

$ ./minimal LAYERS=agg.so AGG_TIMES=5 AGG_FUNC=median

As described in the [Tuning Session](\ref intro_session), processing layers may be stacked. However, it is important to remember that processing layers are not commutative; their order is important. Consider the following two tuning sessions:

$ ./minimal LAYERS=agg.so:log.so \
            LOG_FILE=search.log AGG_TIMES=5 AGG_FUNC=median

and

$ ./minimal LAYERS=log.so:agg.so \
            LOG_FILE=search.log AGG_TIMES=5 AGG_FUNC=median

Only the order of the processing layers have changed, but the second invocation will produce a much smaller log file. This is because the Aggregator is the outermost layer and receives performance reports before the Point Logger. The Point Logger is then unaware of the repeated experiments and only records the resulting aggregated performance value.

In the first invocation, the Point Logger records each performance report before the Aggregator has a chance to unify them. This results in a log file with many repeated experiments.

A real-world example is provided in example/code_generation source directory. That example relies on the code-server, MPI, and CHiLL. Additional details can be found in example/code_generation/README of the source distribution.

Harmony

Install / Use

README