Documentation

When built using CMake, two executables are created: generate_samples and kde. The latter includes U. Lopez-Novoa et al.'s OpenMP implementation of their S-KDE algorithm as a baseline. This may not build on all platforms; for example, it relies on the sys/time.h header, which may not be available. To disable it, change line 2 in benchmarking/CMakeLists.txt to:

set(RUN_SKDE_BASELINE false)

Benchmarking is split into two phases: generating the samples and running the benchmarks. They can be executed together by running

generate_samples.exe num_samples variance_range center_range num_dists | kde.exe method grid_size cell_size bandwidth

Where the arguments are:

1. num_samples: Number of samples to generate
2. variance_range: Each Gaussian distribution will have a uniformly random variance with a max specified here
3. center_range: Each Gaussian distribution will have a uniformly random center with a max specified here
4. num_dists: Total number of distributions to sample from
5. method: Kernel Density Estimation method to use. Available: cpu_naive, cpu_skde, cuda_naive, cuda_skde
6. grid_size: Side of the evaluation grid, which is always a cube
7. cell_size: Side of a single cell in the evaluation grid
8. bandwidth: The size of the ellipsoid kernel

There are three scripts written in python for more easily running the benchmarks and analyzing the results.

The first is profile.py, which generates samples and runs benchmarking. Depending on the system, it may need to be told where the executable files live by specifying a build directory, and additionally it can be configured to skip the OpenMP baseline (see above). To run it, call:

profile.py [--build_dir path/from/project/root/to/build/dir] [--ignore_baseline]

The second analysis script is result_analysis.py, which generates an image of the PDF from a given benchmarking configuration. It requires numpy and matplotlib. To run:

result_analysis.py path/to/specific/results/dir

This app uses GLFW. Before building, make sure GLFW is installed and then modify lines 3 and 4 of CMakeLists.txt to point to the directories containing the GLFW headers and executables.

Then build using CMake.

To run, navigate to the build directory and call:

./visualize_skde.exe <grid_size> <max_density> <path_to_input_file> 

where the arguments are:

1. grid_size: number of grid cells (or evaluation points) per axis. So the final PDF will have dimension grid_size³
2. max_density: defines a simple transfer function. Accumulated density of [0..max_density] maps to opacity [0..1]
3. path_to_input_file: path to the file containing sample data

The app expects a plaintext input file of the form

<num_samples>
<x1> <y1> <z1>
<x2> <y2> <z2>
<x3> <y3> <z3>
...