documentation in combinat

[Dan Drake]

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 <dr...@mathsci.kaist.ac.kr>
----- KAIST Department of Mathematical Sciences
------- http://math.kaist.ac.kr/~drake

[David Joyner]

Yes, please. The lower case functions are all wrappers I wrote for GAP
functions.
Mike Hansen's functions are an improvement. Still, the docstrings should explain
things better. I've been meaning to write a patch dealing with the
lower case functions
which duplicate what Mike did, but was unsure if I should delete them
or just add
a method="gap" option to Mike's functions and then remove them from the
combinat/all.py list.

Suggestions or criticisms?

>
> Thanks,
>
> Dan
>
> --
> --- Dan Drake <dr...@mathsci.kaist.ac.kr>
> ----- KAIST Department of Mathematical Sciences
> ------- http://math.kaist.ac.kr/~drake
>

> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.6 (GNU/Linux)
>
> iD8DBQFHw8gtr4V8SljC5LoRAsVZAKDZzgH1SEo4PYJjdZpjsqhnTKjwAwCgpp0K
> uf0kUgGseFU+pry23G5oYTA=
> =Fd9c
> -----END PGP SIGNATURE-----
>
>

[Robert Bradshaw]

On Feb 26, 2008, at 4:52 AM, David Joyner wrote:

>>
>> 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?
>
> Yes, please. The lower case functions are all wrappers I wrote for GAP
> functions.
> Mike Hansen's functions are an improvement. Still, the docstrings
> should explain
> things better. I've been meaning to write a patch dealing with the
> lower case functions
> which duplicate what Mike did, but was unsure if I should delete them
> or just add
> a method="gap" option to Mike's functions and then remove them from
> the
> combinat/all.py list.
>
> Suggestions or criticisms?

method="gap" seems like the best way to deal with these things.

- Robert

[William Stein]

Yes, there are numerous instances like this though it should be

algorithm="gap"

*not* method, for consistency. Type number_of_partitions? for
a nice example of this.

In Maple "matrix" and "Matrix" are *completely* different commands
that return completely different objects with different semantics. This
is unbelievably lame, and I don't think Sage should ever do anything
like that. If Foo and foo are both defined in Sage for some reason,
they should be equal.

-- William

[David Joyner]

Sorry for replying to my own post, but I said something incorrect.

It is true that many of the lower case combinatorial functions are GAP wrappers
but not all. For example, permutations simply calls (Mike Hansen's)
Permutations,
so there is no need to add an algorithm="gap" option to Permutations.

On Tue, Feb 26, 2008 at 7:52 AM, David Joyner <wdjo...@gmail.com> wrote:
>
> On Tue, Feb 26, 2008 at 3:05 AM, Dan Drake <dr...@mathsci.kaist.ac.kr> wrote:
> > 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.

Agreed the docstring needs fixing.
Here it is harder for partitions_set to be simply a algorithm="gap"
option for SetPartitions, since they return slightly different things. Maybe
partitions_set should be deleted?