I'm trying to count certain equivalence classes of permutations. It turns out that I can use permutations, set partitions, or integer partitions to do this.
I still don't know the landscape of Sage's combinatorics stuff very well, so I spent a lot of time hitting tab and using `?' and found the output not very helpful in many cases. What follows is a sort of log of what I tried and what my reactions (as a sort of end-user test case). (This is all with 2.10.2.) First, the following functions have pretty useless docstrings: Partitions, permutation, and permutation_nk. `SetPartitions?' says "partitions_set returns the set..." but not what SetPartitions returns! Also, the example is basically tautological; examples like those for `Permutations?' are much better. `Permutations?', however, should specify which kwargs it takes; there are several cool examples, but how would a user find out which keywords it takes? `partitions_list?' says "partitions_list(n,k) returns..." and then later, says that the function `partitions' "is also a function of only one argument"! `partitions_restricted' says it returns a set, but it returns a list. This is not such a big deal, but we do have lots of support for sets, and they're not the same as lists. Also, functions that return a list should say how to get an iterator in case that's what you need. On a similar note, `permutations_iterator' should *say* what it gives you; it's good that we've attributed its source, but first tell the user what it is! What's the difference between `permutation' and `Permutation'? Or between `Permutation' and `Permutations'? I talked with Mike Hansen a bit on IRC about this. It seems like the uncapitalized functions are deprecated and the capitalized guys are preferred. Is this true? Should I make a trac ticket for these documentation problems? Thanks, Dan -- --- Dan Drake <[EMAIL PROTECTED]> ----- KAIST Department of Mathematical Sciences ------- http://math.kaist.ac.kr/~drake
signature.asc
Description: Digital signature
