The Combi Documentation
Combi is a Pythonic package for combinatorics.
Combi lets you explore spaces of permutations and combinations as if they
were Python sequences, but without generating all the permutations/combinations
in advance. It lets you specify a lot of special conditions on these spaces. It
also provides a few more classes that might be useful in combinatorics
programming.
Basic usage
Use PermSpace to create a permutation space:
>>> from combi import *
>>> perm_space = PermSpace('meow')
It behaves like a sequence:
>>> len(perm_space)
24
>>> perm_space[7]
<Perm: ('e', 'm', 'w', 'o')>
>>> perm_space.index('mowe')
3
And yet the permutations are created on-demand rather than in advance.
Use CombSpace to create a combination space, where order doesn’t
matter:
>>> comb_space = CombSpace(('vanilla', 'chocolate', 'strawberry'), 2)
>>> comb_space
<CombSpace: ('vanilla', 'chocolate', 'strawberry'), n_elements=2>
>>> comb_space[2]
<Comb, n_elements=2: ('chocolate', 'strawberry')>
>>> len(comb_space)
3
For more details, try the tutorial or see the
documentation contents.
Features
- PermSpace lets you explore a space of permutations as if it was a
Python sequence.
- Permutations are generated on-demand, so huge permutation spaces can be
created easily without big memory footprint.
- PermSpace will notice if you have repeating elements in your
sequence, and treat all occurences of the same value as interchangable
rather than create redundant permutations.
- A custom domain can be specified instead of just using index numbers.
- You may specify some elements to be fixed, so they’ll point to the same
value in all permutations. (Useful for limiting an experiment to a subset
of the original permutation space.)
- Permutation spaces may be limited to a certain degree of permutations. (A
permutation’s degree is the number of transformations it takes to make it.)
- k-permutations are supported.
- You may specify a custom type for the generated permutations, so you could
implement your own functionality on them.
- CombSpace lets you explore a space of combinations as if it was a
Python sequence.
- MapSpace is like Python’s built-in map(), except it’s a
sequence that allows index access.
- ProductSpace is like Python’s itertools.product(), except
it’s a sequence that allows index access.
- ChainSpace is like Python’s itertools.chain(), except
it’s a sequence that allows index access.
- SelectionSpace is a space of all selections from a sequence, of all
possible lengths.
- The Bag class is a multiset like Python’s
collections.Counter, except it offers far more functionality, like
more arithmetic operations between bags,
comparison between bags, and more. (It can do that
because unlike Python’s collections.Counter, it only allows natural
numbers as keys.)
- Classes FrozenBag, OrderedBag and
FrozenOrderedBag are provided, which are variations on Bag.
Installation
Use pip to install Combi:
Roadmap
Combi is currently at a version 0.1.1. It’s in a very early phase, and
currently backward compatibility will not be maintained, to allow for freedom
in changing the API. After more feedback and revisions to the API, backward
compatibility will start being maintained.
Combi has an extensive test suite.
Changelog.