#7477: Matroids
----------------------------------------------------+-----------------------
Reporter: ncohen | Owner: jkantor
Type: enhancement | Status:
needs_review
Priority: major | Milestone: sage-5.10
Component: combinatorics | Resolution:
Keywords: | Work issues:
Report Upstream: N/A | Reviewers:
Authors: Stefan van Zwam, Rudi Pendavingh | Merged in:
Dependencies: #14669 | Stopgaps:
----------------------------------------------------+-----------------------
Comment (by rbeezer):
Dear Stefan,
OK, here's the result of another pass - got through two sections this
time. Some of this may be systematic, I'll let you decide what needs mass
editing, and what might be one-off. Generally, the documentation is
really very good. Lots of thought has gone into it and I'm sure it will
be easy for new users to get up-to-speed quickly. Most of this is
annoying details (yes, I said annoying). Some themes, amplified in
specific comments below:
1. Single backticks get TeX treatment for mathematics. Small chunks of
code need double backticks. This might be isolated in small parts of the
constructor file.
1. Making references to documentation of other classes (inside or outside
of the matroids package) would be better as live links, definitely when
you say "see...".
1. I'm not too dogmatic about long lines in doctests, but an effort
should be made to line-break both input and output in the cases where it
goes on forever.
1. Lots of "simple" methods without OUTPUT sections. Yes, it seems silly
to just say "foo() returns all the foo's of the matroid." I like to
provide some very basic idea of what a foo is if possible, then the
documentation seems worthwhile. I've learned a lot of math by reading
Sage documentation.
I know this seems like a lot of trouble, but it will be worthwhile in the
long run. I'm thinking this package might be a very good example for
others to follow if they wish to add-in other new areas of mathematics.
Rob
Matroid construction (constructor.pyx):
"For EXAMPLES:" appears at least twice, probably a mass substitution
hitting the phrase "For example". Perhaps more in other files?
The flexibility of the Matroid() constructor in the first two arguments
may drive you crazy some day down the road. I am not suggesting you
change it - just a comment.
"A matroid specified by a list of circuits gets converted to a
BasisMatroid internally:"
Making BasisMatroid a link to the class would be an improvement.
"Note: if a groundset is specified, we assume it is in the same order as
G.edge_iterator() provides:"
It'd be nice if small chunks of code were typeset as such, here
``G.edge_iterator()``
Code: "If that fails, we simply use a list `[0..m-1]`"
The single backticks are giving TeX, this should definitely be code,
hence two backticks
Probably the (i,j) preceding is similar, though we could debate if that
is math or code.
Code: "When the ``graph`` keyword is used, a variety of inputs can be
converted to a graph automatically. The following
uses a graph6 string (see the ``Graph()`` method's documentation)::"
Formatting of the keyword is exactly correct. Perhaps "Graph()" should
definitely be a link when it is used in a suggestion to go there.
Code: "sage: M = Matroid(circuit_closures={3: ['edfg', 'acdg', 'bcfg',
'cefh', 'afgh', 'abce', 'abdf', 'begh', 'bcdh', 'adeh'], 4: ['abcdefgh']})
Makes a very long line in the documentation, which puts up a scrollable
box in my browser.
You could define the the long list on its own line, then just reference
it, or I think there is enough flexibility on where you can line break the
command (maybe open the dictionary, put each key/value on its own line,
mildly indented, then close dictionary at start of a subsequent line?).
Abstract class (matroid.pyx)
URL in [GG12] seems broken
Doctest output:
"sage: M = matroids.named_matroids.Fano()
sage: sorted([sorted(C) for C in M.circuits()])
[['a', 'b', 'c', 'g'], ['a', 'b', 'd', 'e'], ['a', 'b', 'f'], ['a',
'c', 'd', 'f'], ['a', 'c', 'e'], ['a', 'd', 'g'], ['a', 'e', 'f', 'g'],
['b', 'c', 'd'], ['b', 'c', 'e', 'f'], ['b', 'd', 'f', 'g'], ['b', 'e',
'g'], ['c', 'd', 'e', 'g'], ['c', 'f', 'g'], ['d', 'e', 'f']]"
You can line-break output at any whitespace and the test should succeed.
Here, you could put each interior list
on a line of its own. I have not looked at the PDF version, but I suspect
this will just run off the right edge of the page.
f-vector() documentation:
Has a list with just one item for output. Probably does not need to
be a list. Ditto for flats(). I'm seeing more like this. I'm inclined
to just write a paragraph, unless returning a pair, triple, or ...
groundset():
Not sure an INPUT section is necessary if there is none. Even though
this is an abstract method, maybe the OUTPUT should be documented?
is_connected(), is_cosimple() (and more is_ methods) lack OUTPUT, even
if it seems silly to have it.
"loops() Return the set of loops of the matroid." Is it easy to say in
an OUTPUT section what a loop is? Some people learn mathematics by
reading the documentation. You do not have to go overboard, but can you
say in one sentence what a loop is? It makes the documantation look less
vacuous. (eg OUTPUT: A list of the loops of the matroid. A loop is a
one-element dependent set.)
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/7477#comment:55>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
