The Spatial Use Case

This page explains how to run HyperMapper with the Spatial language (https://spatial-lang.org). Here Spatial is the program that calls HyperMapper. HyperMapper replies with the points that have to be run by Spatial. Both software are writing on stdio and stdout and following a precise protocol of communication, like explained here. This is what in HyperMapper terminology is called "client-server mode". The developer responsible for Spatial is Matt Feldman.

For a general introduction on how to use Spatial and HyperMapper see the Design Space Exploration tutorial at PLDI 2020.

Setup Spatial

We provide a quick installation setup for HyperMapper here. We recommend you use spatial-quickstart, but full spatial works too.

First, install the following Spatial dependencies:

Scala SBT - sudo apt-get install sbt # see www.scala-sbt.org/release/docs/Setup.html if sbt isn't found
Java JDK 8 - sudo apt-get install openjdk-8-jdk
Integer Set Library - sudo apt-get install libisl-dev
Python 3 - Make sure python points to python3 and not python2

Then, install Spatial:

git clone https://github.com/stanford-ppl/spatial-quickstart
cd spatial-quickstart/
export SPATIAL_HOME=`pwd`
mkdir dse_hm
git submodule update --init

Setup HyperMapper

Install HyperMapper following our installation guide.

Set the HYPERMAPPER_HOME environment variable:

export HYPERMAPPER_HOME=/path/to/hypermapper

This variable is mandatory for this use case, Spatial will use it to call HyperMapper.

Compile app and call HyperMapper DSE

This branch conveniently contains a GEMM example, annotated with 13 DSE parameters.

bin/spatial GEMM --tune --hypermapper --synth --fpga=ZCU --hypermapper_doeSamples=14 --hypermapper_iters=20

In general, Spatial apps should live in spatial-quickstart/src/main/scala

After the script finishes, the result of the optimization will be saved in spatial/gen/<benchmark>/<benchmark>_output_dse_samples.csv. E.g., for GEMM, the results will be saved in spatial/gen/GEMM/GEMM_output_dse_samples.csv.

Visualize Pareto for Slices vs Cycles

cd $HYPERMAPPER_HOME
python scripts/compute_pareto.py $SPATIAL_HOME/dse_hm/GEMM.json 
python scripts/plot_dse.py $SPATIAL_HOME/dse_hm/GEMM.json 
cd $SPATIAL_HOME/gen/GEMM/

A pareto front plot will be stored as all_GEMM_output_pareto.pdf in the app's generated directory.