Skip to content


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation

/** @page start

Downloading the Source                            {#start_get}
The latest release of Active Harmony can always be found at:


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`

Or, through our repository's web interface at:


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`

    $ 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` |
XML Writer | `LIBXML2`  |

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

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

    $ export
    $ 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

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 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 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 \
                LOG_FILE=search.log AGG_TIMES=5 AGG_FUNC=median

    $ ./minimal \
                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.