Repository files navigation

This project is the rewrite ofpyLAPJV whichsupports Python 3 and updates the core code. The performance is twice as high asthe original thanks to the optimization of the augmenting row reduction phaseusing Intel AVX2 intrinsics. It is a native Python 3 module and doesnot work with Python 2.x, stick to pyLAPJV otherwise.

Linear assignment problemis the bijection between two sets with equal cardinality which optimizes the sumof the individual mapping costs taken from the fixed cost matrix. It naturallyarises e.g. when we want to fitt-SNE resultsinto a rectangular regular grid.See this awesome notebook for the details about why LAP matters:CloudToGrid.

Jonker-Volgenant algorithm is described in the paper:

R. Jonker and A. Volgenant, "A Shortest Augmenting Path Algorithm for Dense and Sparse Linear Assignment Problems,"Computing, vol. 38, pp. 325-340, 1987.

This paper is not publicly available though a brief description exists onsciencedirect.com.JV is faster in than theHungarian algorithm in practice,though the complexity is the same - O(n³).

The C++ source of the algorithm comes fromhttp://www.magiclogic.com/assignment.htmlIt has been reworked and partially optimized with OpenMP 4.0 SIMD.

pip3 install lapjv

Tested on Linux and Windows.macOS is not supported, please do not report macOS build errors in the issues.Feel free to PR macOS support, but I warn that it will be a rough ride.

Refer totest.py for the complete code.

from lapjv import lapjvrow_ind, col_ind, _ = lapjv(cost_matrix)

The assignment matrix by row isrow_ind: the value at n-th place is the assigned column index to the n-th row.col_ind is the reverse ofrow_ind: mapping from columns to row indexes.

Note: a bijection is only possible for sets with equal cardinality. If you need to map A vectors to B vectors,derive the square symmetric (A+B) x (A+B) matrix: take the first A rows and columns from A andthe remaining [A..A+B] rows and columns from B. Set the A->A and B->B costs to some maximum distance value,big enough so that you don't see assignment errors.

This error appears if your CPU does not support the AVX2 instruction set. We do not ship builds for different CPUs so you need to build the package yourself:

pip3 install git+https://github.com/src-d/lapjv

NAN-s in the cost matrix lead to completely undefined result. It is the caller's responsibility to check them.

MIT Licensed,seeLICENSE