find the permutation of the atoms which minimizes the distance X1X2
With all the default parameters, findBestPermutation assumes that X1, X2 are arrays of atoms in 3d space and performs reshaping on the coordinates. However, if you want to pass a 2D system or a custom array with own cost function, you can turn automatic reshaping off.
Parameters :  X1, X2 :
permlist : a list of lists
user_algoriithm : None or callable
gen_cost_matrix : None or callable
reshape : boolean
box_lengths : float array


Returns :  dist : float
perm:

Notes
For each list of interchangeable atoms in permlist the permutation which minimizes the distance between the two structures is found. This minimimization is done by mapping the problem onto the linear assignment problem which can then be solved using graph theoretic techniques.
http://en.wikipedia.org/wiki/Linear_assignment_problem http://en.wikipedia.org/wiki/Hungarian_algorithm
there are several packages in pypi which solve the linear assignment problem
hungarian : c++ code wrapped in python. scales roughly like natoms**2.5
munkres : completely in python. scales roughly like natoms**3. very slow for natoms > 10
in addition we have wrapped the OPTIM version for use in pele. It uses the sparse version of the JonkerVolgenant algorithm. Furthermore the cost matrix calculated in a compiled language for an additional speed boost. It scales roughly like natoms**2