This software library contains efficient implementations of Discrete Optimal Transport algorithms for the computation of Kantorovich-Wassestein distances [1] customized for large spatial maps.

The core library is written in standard ANSI-C++11, but it has two wrappers:

1. A Python wrapper
2. An R wrapper

If you need a wrapper in another language, please let us know by posting a request on GitHub.

Currently, the Spatial-KWD library is tested on

• Google Colabs notebooks
• Windows 10 (R v4.0.3, Python >= 3.6)
• Mac OS X Bug Sur 11.0.1 (R v4.0.3, Python 3.8.3)
• Linux 20.04.1 LTS (R v4.0.0, Python 3.8.5)

The simplest way to test this library is to run one of the following notebooks on Colab:

Data	Notebook	Link
[2021/02/20]	Tutorial 1: Using Spatial-KWD with Python
[2020/11/22]	Tutorial 2: Using Spatial-KWD with R

To compile the Python wrapper you need the following library:

• Cython (>= 0.23)

To install Cython you can look at the official documentation Installing Cython.

Then, you have to download this repository, move to the subdirectory .\wrapper\python\, and then run from command line the following command:

python setup.py build_ext

This will compile the C++ code and build the python wrapper. If you prefer to compile the wrapper in a local directory, you can run the command:

python setup.py build_ext --inplace

In this case, however, you can only use the library in the local directory where you compile it.

Once you have done with the installation of the python wrapper, you can test it using one of the following script:

• test_kwd.py: A basic example with three histograms.
• test_pandas.py: An example based on Pandas Series, which uses also an exact solver.

The wrapper for R is contained in the SpatialKWD_0.3.0.tar.gz package, and all the source code are freely available on this site under the directory wrappers/R.

For compiling the wrapper, you need a recent version of R and the Rcpp package (we test it with Rcpp v.1.0.5, but it should work also with older versions).

Windows users can download a pre-compiled binary package at the following link:

• SpatialKWD_0.3.0.zip

Once you have installed the Spatial-KWD package, you can test it running one of the following scripts:

• test_SKWD.R: to compute the distances among three dummies histograms
• test_SKWD_dataframe.R: to compute the distance between two histograms stored in a data.frame or in a data.table.

If you need an interface for a different R data structure, again, please let us know.

Contributors
Status	since 2020
License	EUPL v1.2

• [1] Bassetti F., Gualandi S., Veneroni M. On the computation of Kantorovich-Wasserstein distances between 2D-histograms by uncapacitated minimum cost flows. SIAM J. Optim., 30(3), 2441–2469, 2020. Preprint on arXiv: 1804.00445.

Windows package of the R wrapper is built with Win-Builder.