Package: xcover
xcoverA python package for solving exact cover with colours problems.InstallationThis package can be installed using pip:pip install xcoverThe only dependency isnumba.UsageA simple example of anexact coverproblem is the following. Given the set of 6 options
0:={1, 4, 7}; 1:={1, 4}; 2:={4, 5, 7}; 3:={3, 5, 6}; 4:={2, 3, 6, 7}; 5:={2, 7}, each of which are subsets of a set of seven items (the numbers 1 to 7), find a subset of the options which contains each item once and only once. Such a problem can be solved using the package asfrom xcover import covers

options = [[1, 4, 7], [1, 4], [4, 5, 7], [3, 5, 6], [2, 3, 6, 7], [2, 7]]
print(list(covers(options)))[[1, 3, 5]]which outputs a list of possible exact covers. In this case there is a single solution: cover by the options 1:={1, 4}, 3:={3, 5, 6}, and 5:={2, 7}.Thecoversfunction returns apython generator, an object that can be used in aforloop. This is useful in the case of multiple solutions if you want to do something immediately with each solution as it is calculated. If you just want to find the next solution you can use thenextfunction on the generator.Exact cover with coloursThe package supports two extensions to the standard exact cover problem. The first extension is the addition of secondary items. These are items that do not need to be covered, but may be covered once if required. The second extension is the ability to colour the secondary items in each option. In the coloured case the secondary item may be covered multiple times, so long as it is coloured the same way in each cover. A simple example of an exact cover with colours problem is the followingprimary = ["p", "q", "r"]
secondary = ["x", "y"]
options = [
    ["p", "q", "x", "y:A"],
    ["p", "r", "x:A", "y"],
    ["p", "x:B"],
    ["q", "x:A"],
    ["r", "y:B"],
]

print(list(covers(options, primary=primary, secondary=secondary, colored=True)))[[3, 1]]In this problem there are three primary itemsp,q, andrthat must be covered, and two secondary itemsxandythat may be covered. The exact cover is given by the two sets {p,r,x:A,y} and {q,x:A}. In this cover the itemxis covered twice, but that is acceptable as both instances are coloredA. The xcover package denotes the colouring of items by a colon followed by a label.Boolean arraysAn alternative way of specifying an exact cover problem is in terms of aboolean incidence matrix. The package provides acovers_boolfunction for directly solving such problems.import numpy as np
from xcover import covers_bool

matrix = np.array([
    [1, 0, 0, 1, 0, 0, 1],
    [1, 0, 0, 1, 0, 0, 0],
    [0, 0, 0, 1, 1, 0, 1],
    [0, 0, 1, 0, 1, 1, 0],
    [0, 1, 1, 0, 0, 1, 1],
    [0, 1, 0, 0, 0, 0, 1]
    ], dtype=bool)
print(next(covers_bool(matrix)))[1, 3, 5]Dancing cellsThe algorithm used for finding the exact covers isDonald Knuth'salgorithm C which uses "dancing cells". A full description of the algorithm can be found in hisdraft manuscript. The main algorithm is inxcover.dancing_cells.algorithm_cand can be called directly if desired.NumbaTo accelerate the performance of the solver this package usesnumbato perform Just In Time (JIT) compilation of the main algorithm. This means the first call to the solver may be slow (a few seconds) while numba compiles the function. However, later calls will be fast, as numba uses a cache to avoid repeated compilation. JIT compilation can be disabled by explicitly configuring numba before importing thexcoverpackage.from numba import config
config.DISABLE_JIT = TrueApplicationsMany recreational mathematical puzzles can be naturally cast as exact cover problems. Examples include pentomino tiling, sudoku, and the n-queens problem. Donald Knuth'sArt of Computing volume 4Bhas an extensive discussion of many such problems. Exact cover problems areNP-completewhich means solve times can get very long very quickly as problems get larger. Be warned!LicenseThis package is licenced under the GNU Lesser General Public License v3.0.