pot

library0.9.6.post1pypypi✓ verified 87d ago

POT (Python Optimal Transport) is a comprehensive Python library offering various solvers for optimal transport problems. It provides efficient implementations for classic optimal transport, Wasserstein distances, Sinkhorn algorithm, Gromov-Wasserstein, and more, including recent extensions like unbalanced OT and GMM-OT. Currently at version 0.9.6.post1, the library sees frequent minor releases, often introducing new features, solvers, and bug fixes.

data ai-ml

pip install pot

github ↗package ↗

INSTALL

IMPORT

SIG · POT

pot

datapythonv0.9.6.post1

Install

7.6s avg

Import

1435ms

Disk

233MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.6.post1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

build_error

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 7.6s · import 1.435s · 229MB

233MB installed

● package 233MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import ot

The entire library is typically imported under the alias 'ot'.

This example demonstrates how to compute the Earth Mover's Distance (EMD) between two 1D samples using POT's core `ot.emd` function. It covers generating samples, defining uniform marginal distributions, computing a normalized cost matrix, and finally, calculating the optimal transport plan and its total cost.

import numpy as np import ot # Generate two 1D samples n = 100 np.random.seed(0) xs = np.random.normal(0, 1, n) xt = np.random.normal(5, 1, n) # Histogram counts (uniform distribution) a = np.ones(n) / n b = np.ones(n) / n # Cost matrix: squared Euclidean distance M = ot.dist(xs.reshape((n, 1)), xt.reshape((n, 1))) M /= M.max() # Normalize cost matrix for stability # Compute Earth Mover's Distance (EMD) / Wasserstein-1 distance G = ot.emd(a, b, M) print(f"Optimal Transport plan (first 5x5): {G[:5,:5]}") print(f"EMD cost: {np.sum(G * M)}")

Debug

Known issues

breakingThe Gromov-Wasserstein (GW) solvers underwent a major refactor in version 0.9.0, leading to significant performance gains and the ability to handle non-symmetric cost matrices. While the API generally remained consistent, users relying on specific internal behaviors or numerical properties of older GW implementations might observe changes in results or performance characteristics.

fix

Review the official documentation and examples for GW solvers if migrating from versions older than 0.9.0. Verify results, especially when dealing with non-symmetric matrices.

affects: >=0.9.0

gotchaPOT supports multiple array backends (NumPy, PyTorch, JAX, CuPy) for computation. By default, it uses NumPy. To leverage GPU acceleration (e.g., with CuPy or PyTorch on CUDA), users must explicitly configure `ot.backend` or ensure their input arrays are of the desired backend type (e.g., CuPy arrays for `ot.gpu` functions). Mixing backends or incorrect setup can lead to errors or unexpected CPU-only computation.

fix

For GPU or specific backend usage, import and configure `ot.backend` (e.g., `import ot.backend as ob; ob.set_backend('torch', 'cuda')`) or ensure all input tensors are compatible with the desired backend.

affects: All versions with backend support

gotchaInput array dimensions are critical and frequently a source of errors. For example, marginal distributions `a` and `b` are typically 1D arrays, while coordinates `X` and `Y` are 2D arrays (n_samples, n_features), and cost matrices `M` are 2D (n_samples_source, n_samples_target). Mismatched dimensions (e.g., `(n,)` instead of `(n,1)` for single-feature coordinates or transposed cost matrices) will lead to runtime errors.

fix

Always consult the specific function's documentation for expected input shapes. Use `.reshape()` or `.T` carefully to ensure arrays conform to the required dimensions.

affects: All versions

gotchaFor many optimal transport problems, particularly those with a probabilistic interpretation, the marginal distributions `a` and `b` are expected to sum to 1. While some solvers might handle unnormalized inputs, it's best practice to normalize them (e.g., `a = a / np.sum(a)`) to ensure correct interpretation and avoid potential numerical instabilities in certain algorithms.

fix

Normalize marginal distributions `a` and `b` such that `np.sum(a) == 1` and `np.sum(b) == 1` before passing them to POT functions, unless the specific function documentation explicitly states otherwise for unbalanced OT.

affects: All versions

gotchaOptimal transport problems, especially exact EMD, can be computationally very expensive for large numbers of samples. While POT provides efficient C/Cython implementations, exact solvers scale poorly (e.g., cubic complexity for EMD). For large-scale applications, consider using entropic regularized solvers (Sinkhorn) or specialized approximate methods which trade off accuracy for speed.

fix

For N > 1000 samples, favor `ot.sinkhorn` or other regularized/approximate solvers over `ot.emd`. Explore techniques like sub-sampling, multi-scale, or barycentric mapping for further scalability.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'ot'

The Python Optimal Transport library is installed as 'POT' but its primary module for importing is named 'ot'.

fix

Use `import ot` instead of `import pot` in your Python code. Make sure the library is installed with `pip install POT` or `conda install -c conda-forge pot`.

ImportError: No module named Cython.Build

For older versions of POT (prior to 0.8) or when installing from source, Cython and NumPy are build-time dependencies that need to be installed before POT itself.

fix

First install Cython and NumPy: `pip install numpy cython`, then install POT: `pip install POT`. Upgrading POT to a newer version might also resolve this as pre-compiled wheels are often available.

ValueError: Solver for EMD in 1d only supports metrics from the following list: `['sqeuclidean', 'minkowski', 'cityblock', 'euclidean']`

This error occurs when a 1D Earth Mover's Distance (EMD) function, such as `ot.lp.emd2_1d`, is called with a distance metric string that is not explicitly supported by its implementation.

fix

Ensure the `metric` parameter provided to the 1D EMD function is one of the accepted strings: 'sqeuclidean', 'minkowski', 'cityblock', or 'euclidean'.

UserWarning: Problem infeasible. Check that a and b are in the simplex

This warning indicates that the optimal transport solver (e.g., `ot.emd`, `ot.sinkhorn`) could not find a feasible solution, often because the input histograms `a` and `b` (source and target distributions) do not sum to 1 (or close to 1) or contain negative values, violating the requirements for valid probability distributions.

fix

Normalize your histograms `a` and `b` so that `np.sum(a)` and `np.sum(b)` are both approximately 1.0, and ensure all elements in `a` and `b` are non-negative. For example: `a = a / np.sum(a)`.

Upgrade

Version history

0.9.6.post1latest on PyPI · released Sep 22, 2025

Audit

Dependencies

numpyrequiredCore library for numerical operations and array manipulation.

scipyrequiredProvides scientific computing tools, sparse matrix handling, and optimization algorithms.

matplotliboptionalUsed extensively for plotting and visualizing optimal transport plans and results, especially in examples and tutorials.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/PythonOT/POT ↗

packagehttps://pypi.org/project/pot/ ↗