Suggestion to provide external links in documentation.
Dr. David Kirkby
suggested adding to docstrings the names of related commands. That seems very
sensbile - just like the "man" pages of a Unix system.
How would people feel about providing links to MathWorld and Wikipedia on the
docstrings too?
i.e. for "norm"
http://trac.sagemath.org/sage_trac/ticket/8825
add links to
http://en.wikipedia.org/wiki/Matrix_norm
http://mathworld.wolfram.com/Norm.html
http://mathworld.wolfram.com/MatrixNorm.html
http://mathworld.wolfram.com/VectorNorm.html
IMHO, it would also be worth adding the nearest equivalent commands in Macsyma,
Mathematica, Maple and MATLAB, though I doubt that will be possible for many
commands. sin() would have
Sin[] - nearest equivalent command for Mathematica
sin() - nearest equivalent command for MATLAB
I don't know about the command for 'sine' in other packages, but no doubt
someone is familiar with them.
One could also add for packages where there is no similar command for the
commercial packages.
foobar() - As of version 7.0, Mathematica has no similar functionality.
I think at one point, providing a list of equivalent commands in these packages
should be done, to aid people porting code from these packages to Sage. A start
would be to document the nearest equivalent commands in the actual docstrings.
At least if a conversion list was ever made, the docstrings would provide some
help to those compiling such a list.
Dave
Minh Nguyen
On Tue, Sep 21, 2010 at 7:11 PM, Dr. David Kirkby
<david....@onetel.net> wrote:
> I think at one point, providing a list of equivalent commands in these
> packages should be done, to aid people porting code from these packages to
> Sage. A start would be to document the nearest equivalent commands in the
> actual docstrings.
I don't have a problem with this. In fact, I heartily support your suggestion.
> At least if a conversion list was ever made, the docstrings would provide
> some help to those compiling such a list.
Nathann and I started a few months ago to make such a list for graph theory:
http://trac.sagemath.org/sage_trac/wiki/GraphTheoryRoadmap
--
Regards
Minh Van Nguyen
Tim Daly
mhampton
used to other systems could find equivalent commands by searching for
what they already know. For example, a Mathematica user might search
for NDSolve and be led to ode_solver.
Perhaps we need a new official docstring title for this (i.e. like
EXAMPLES or NOTES).
-Marshall
On Sep 21, 4:11 am, "Dr. David Kirkby" <david.kir...@onetel.net>
wrote:
> suggested adding to docstrings the names of related commands. That seems very
> sensbile - just like the "man" pages of a Unix system.
>
> How would people feel about providing links to MathWorld and Wikipedia on the
> docstrings too?
>
> i.e. for "norm"
>
> http://trac.sagemath.org/sage_trac/ticket/8825
>
> add links to
>
Nathann Cohen
> Nathann and I started a few months ago to make such a list for graph theory:
putting all these informations INSIDE of the docstrings instead ? We
could then generate the list of corespondances... It would be way
easier to maintain, and users could find the Sage equivalents to the
commands they know though search_doc (?)...
Nathann
Nathann Cohen
> putting all these informations INSIDE of the docstrings instead ? We
> could then generate the list of corespondances... It would be way
> easier to maintain, and users could find the Sage equivalents to the
> commands they know though search_doc (?)...
it inside the docstrings way before I arrived :-D
Now, dear Sphinx experts, is there any "good" way to to it ? We
already have a lot of "sections" (INPUT, OUTPUT, ALGORITHM, sometimes
COMPLEXITY, EXAMPLES and TESTS) : should we add something like
"EQUIVALENTS" containing "Matlab = ....., Mathemetica = ..." etc ?
Would something else be easier to parse afterwards ?
Nathann
Dr. David Kirkby
If it was possible to put the equivalent commands in the docstrings, and then
use some code to extract them in a logical way, it would be helpful.
If it was done done in a very consistent way, then generating a list from grep
and awk would be trivial:
Let's say one always had equivalent entries of the format:
sage_command Nearest Mathematica equivalent: MathematicaCommand[]. Anything else
in the doc files was ignored, since we only bother searching for the text
"Nearest Mathematica equivalent:"
drkirkby@hawk:~$ cat test.txt
factor() Nearest Mathematica equivalent: Factor[] FactorInteger[]
tan() Nearest Mathematica equivalent: Tan[]
Some other stuff, unrelated to Mathematica
cos() Nearest Mathematica equivalent: Cos[]
Some other stuff, about birds and bees
sin() Nearest Mathematica equivalent: Sin[]
drkirkby@hawk:~$ grep awk "Nearest Mathematica equivalent:" | awk '{print $5,
$1}' | sort | grep -v "^ "
Cos[] cos()
Factor[] factor()
Sin[] sin()
Tan[] tan()
We would then search for lines where's there is a 6th entry too, as there might
be two different commands needed in Mathematica, as there is for factor().
drkirkby@hawk:~$ grep "Nearest Mathematica equivalent" test.txt | awk '{print
$6, $1}' | sort | grep -v "^ "
FactorInteger[] factor()
Combining the two, we now have a complete list of Mathematica vs Sage commands,
sorted by the Mathematica name. (We don't need to sort each time - only at the end)
drkirkby@hawk:~$ grep "Nearest Mathematica equivalent" test.txt | awk '{print
$5, $1}' | grep -v "^ " > tmpfile
drkirkby@hawk:~$ grep "Nearest Mathematica equivalent" test.txt | awk '{print
$6, $1}' | grep -v "^ " >> tmpfile
Now sort them.
drkirkby@hawk:~$ sort tmpfile
Cos[] cos()
Factor[] factor()
FactorInteger[] factor()
Sin[] sin()
Tan[] tan()
I expect:
1) Someone will tell me there's a way to do it in Python.
2) There's better ways of doing it with shell scripts (one would want to
recursive search files for example), but that's trivial (-R option on GNU grep,
or with 'find' command).
3) There might be a better way of doing it in the dostrings.
But if all else fails, then grabbing the data via a shell script and sorting it
in order would be trivial as long as a consistent format was used. i.e. was
always use ""Nearest Mathematica equivalent" or something like that, and people
do not mis-spell it, swap the case of characters, or anything else that gets
away from a rigid agreed structure.
PS, it would also be trial to create an HTML web page from such a shell script!
Dave
Nathann Cohen
> If it was possible to put the equivalent commands in the docstrings, and
> then use some code to extract them in a logical way, it would be helpful.
>
> If it was done done in a very consistent way, then generating a list from
> grep and awk would be trivial:
I like very long bash lines, with as many pipes as I can. I'm in :-D
> Let's say one always had equivalent entries of the format:
> ...
> We would then search for lines where's there is a 6th entry too, as there
> might be two different commands needed in Mathematica, as there is for
> factor().
I totally agree on the idea. Now some details : if we finally put
these informations inside of the docstring then extract it from the
python files, it means these informations will be available in the
method's docstrings. So for example, it may be nice not to have to
repeat the command's name in those "equivalent" lines..
def method_name():
r"""
...
EQUIVALENTS:
method_name Mathematica MethodName[]
method_name Matlab MethodName[]
method_name Scilab MethodName[]
"""
...
This can be extracted from the line containing "def" just before the
r""" or the """.
Then, because I am thinking of Graph Theory, it would be hard
sometimes to give, as you say, just one equivalent. Sometimes, many
are available, sometimes our Sage methods replace several Mathematica
methods at once because of our optional arguments. Sometimes, there is
no equivalent Mathematica method, but one doing "almost" the same job
: I remember having seen that Mathematica was only able to approximate
problems for which we had exact solvers, in which case we have to
explain in the "Equivalent" line the difference between the two. All
in all, I would quite love to be able to write a small paragraph
corresponding to an "Equivalent" line, to deal with all of it.
What would you think of such a paragraph ?
EQUIVALENTS:
Mathematica : Small paragraph if necessary (and most probably on
multiple lines as we try to keep them short in the code), talking
about the differences between the current method and Method 1/2. (This
paragraph does not contain any list, as we want to be able to parse
the following commands easily ?)
* Method 1
* Method 2
Scilab : Same kind of things...
* Method 1
* Method 2
> Combining the two, we now have a complete list of Mathematica vs Sage
> commands, sorted by the Mathematica name. (We don't need to sort each time -
> only at the end)
Hmmm... Actually, we would only have a Mathematica Vs Sage comparison
when we have a Sage method equivalent to the Mathematica one, or close
enough. The methods that Mathematica can handle while we can not do
not appear. Or perhaps those should just become TRAC tickets, and be
written :-D
Nathann
Niles
equivalent" is going to be an essential part of this, then it should
be very carefully chosen, and probably implemented through some
function, so that typos are avoided.
e.g.
def doc_equiv_command(sage_command, other_command, system):
return <formatted string--you get the idea>
but probably this has to be implemented using some ReST functionality
that I don't know about.
And to me it seems that "nearest" is a bad word here. Cases where
sage/other system don't have easily comparable commands are likely to
arise, and then different people will have different ideas of what
"nearest" means. Discussion will ensue and slow everything down, when
both good options should just be listed.
Also, what if a particular sage function can be implemented in another
system using two lines of code or so, but not less? At what point is
it reasonable to declare "no equivalent function"?
just my two (or three) cents,
Niles
Dr. David Kirkby
> I'd just like to comment that, if the wording "nearest Mathematica
> equivalent" is going to be an essential part of this, then it should
> be very carefully chosen, and probably implemented through some
Maybe "nearest" is not appropriate. Perhaps "similar" or something like that, so
it avoids any arguments about what is similar and what is not.
Nobody can expect the commands to be identical - except for trivial ones like
Sin[], Cos[]. In the case of factor() there are two very obvious Mathematica
commands that provide broadly similar functionality.
At the end of the day, this is not a suggestion to make a Sage-> Mathematica or
Mathematica -> Sage converter, So people would be expected to look at what
commands might do.
I'm not very conversant with how the doctests work, so I can't really comment on
the way to do it, but I know if a precisely defined method was used, then it
would be possible to extract data with a shell script very easily.
mda_
wrote:
>
> > I'd just like to comment that, if the wording "nearest Mathematica
> > equivalent" is going to be an essential part of this, then it should
> > be very carefully chosen, and probably implemented through some
>
> Maybe "nearest" is not appropriate. Perhaps "similar" or something like that, so
> it avoids any arguments about what is similar and what is not.
full transformation of the grammar, it's not a "Natural
Transformation"/functor if I'm using the correct maths terminology.
> Nobody can expect the commands to be identical - except for trivial ones like
> Sin[], Cos[]. In the case of factor() there are two very obvious Mathematica
> commands that provide broadly similar functionality.
engineering.
-Don
Dr. David Kirkby
> On Sep 21, 10:39 am, "Dr. David Kirkby"<david.kir...@onetel.net>
> wrote:
>> On 09/21/10 06:12 PM, Niles wrote:
>>
>>> I'd just like to comment that, if the wording "nearest Mathematica
>>> equivalent" is going to be an essential part of this, then it should
>>> be very carefully chosen, and probably implemented through some
>>
>> Maybe "nearest" is not appropriate. Perhaps "similar" or something like that, so
>> it avoids any arguments about what is similar and what is not.
>
> How about "close analogue".
No, I don't like that. If nothing else, it will be more confusing to those whose
first language is not English, and even though mine is, I don't like that term.
> As you've said or alluded to, without a
> full transformation of the grammar, it's not a "Natural
> Transformation"/functor if I'm using the correct maths terminology.
If we were writing a Sage -> Mathematica converter, or a Mathematica -> Sage
converter, then clearly we would need to be very precise over this. But if
someone uses NIntegrate[] in Mathematica, they would probably want to know what
commands are related in Sage. It might be only "integrate" but there might be
others. At that point they know what commands it would be worth using the help
system for.
>> Nobody can expect the commands to be identical - except for trivial ones like
>> Sin[], Cos[]. In the case of factor() there are two very obvious Mathematica
>> commands that provide broadly similar functionality.
>
> Since Mma doesn't post it's BNF (Grammar), it's an exercise in reverse
> engineering.
>
> -Don
But we don't need that for documentation. I'd be quite keen to have Sage read
Mathematica input, or at least some sort of converter. Then one needs to be a
lot more accurate about the differences between commands. But for documentation
like this, we don't need it. There's no need to reverse engineer anything.
Dave
mda_
> > How about "close analogue".
>
> No, I don't like that. If nothing else, it will be more confusing to those whose
> first language is not English, and even though mine is, I don't like that term.
m-w.com: "1:something that is analogous or similar to something else"
Since the functions may have different modes, context, side-effects,
options, evaluation order, precision, memory complexity/access order/
alignment, cpu/runtime complexity, test coverage etc. ad nausium I
think the point is to call them "[Somewhat equivalent, but not the
same.]"
> >> Nobody can expect the commands to be identical - except for trivial ones like
> >> Sin[], Cos[]. In the case of factor() there are two very obvious Mathematica
> >> commands that provide broadly similar functionality.
>
> > Since Mma doesn't post it's BNF (Grammar), it's an exercise in reverse
> > engineering.
>
> > -Don
>
> But we don't need that for documentation. I'd be quite keen to have Sage read
> Mathematica input, or at least some sort of converter. Then one needs to be a
generator and maintain it, so I agree that trivial similars in the
docstrings is a good idea.
Cheers,
Don
Johan S. R. Nielsen
documentation and for luring other math-software users in. The biggest
problem is maintenance, I guess: I don't exactly know how much
Mathematica, Maple etc. change in each version, but for the more
obscure functions, there will be an upkeep for each new version. I
know that at least Maple is infamous for making larger changes without
warning.
> Nathann wrote:
> Then, because I am thinking of Graph Theory, it would be hard
> sometimes to give, as you say, just one equivalent. Sometimes, many
> are available, sometimes our Sage methods replace several Mathematica
> methods at once because of our optional arguments. Sometimes, there is
> no equivalent Mathematica method, but one doing "almost" the same job
> : I remember having seen that Mathematica was only able to approximate
> problems for which we had exact solvers, in which case we have to
> explain in the "Equivalent" line the difference between the two. All
> in all, I would quite love to be able to write a small paragraph
> corresponding to an "Equivalent" line, to deal with all of it.
>
> What would you think of such a paragraph ?
>
> EQUIVALENTS:
>
> Mathematica : Small paragraph if necessary (and most probably on
> multiple lines as we try to keep them short in the code), talking
> about the differences between the current method and Method 1/2. (This
> paragraph does not contain any list, as we want to be able to parse
> the following commands easily ?)
>
> * Method 1
> * Method 2
>
> Scilab : Same kind of things...
>
> * Method 1
> * Method 2
that for most functionality, another math system will not have an
equivalent or even a close analogue. Rather, there will be a set of
functions which combined in various ways can emulate most of the
behaviour. So I would suggest a heading being non-specific such as "In
other software". As I understood it, the list of methods after each
alternative system's text paragraph should only be for searching and
autogenerating dictionary-like documentation in the sense Dave
suggested, right?
Though it kind of disappeared from the discussion, I also like adding
the Wikipedia and Mathworld references. Don't we already have a
"references" section? This could be extended to including not directly
cited material. Or we could add a "See also" section, like
Wikipedia's.
Cheers,
Johan
Dr. David Kirkby
> I think this is quite a good idea as a complement to the usual topical
> documentation and for luring other math-software users in. The biggest
> problem is maintenance, I guess: I don't exactly know how much
> Mathematica, Maple etc. change in each version, but for the more
> obscure functions, there will be an upkeep for each new version. I
> know that at least Maple is infamous for making larger changes without
> warning.
To be honest, I'd guess Sage changes more in a backwards incompatible way than
Mathematica! If for no other reason that the release cycle of Mathematica, Maple
and MATLAB are much longer than Sages. (I don't know about Macsyma, but I know
of product aimed at professionals with a release cycle like Sage.)
Yes, maintenance could be an issue, but I believe even outdated references will
be better than none at all.
Perhaps there needs to be two sets of information then.
1) What I suggested. I'm not going to argue about the wording, but for the sake
of this discussion assume "Related Mathematica commands"
2) What Nathann suggested, but wrapped inside some very rigid structure, so the
full text can be extracted. Again, I'm not going to argue about the wording, but
lets for this discussion keep it to "Notes about the relationship between
Mathematica and Sage" and "End of notes about the use of Mathematica"
So for Sage's factor(), we would have something like:
**Related Mathematica commands:** Factor FactorInteger FactorList
FactorSquareFree FactorSquareFreeList FactorTerms FactorTermsList
**Notes about the relationship between Mathematica and Sage**
FactorInteger[] is used in Mathematica to factor only integers, with several
other commands used to factor polynomials. In contrast, Sage, factor() is used
to factor both polynomials and integers.
In both systems, testing if a number is prime is considerably quicker than
factorising that number, so much larger integers can be checked for primality,
that what can be factored in a reasonable amount of time. In Mathematica, the
command PrimeQ[] is used to test whether a number is prime. In Sage, is_prime()
can be used to test if a number is prime.
** End of notes about the use of Mathematica **
Then everything between:
**Notes about the relationship between Mathematica and Sage**
and
** End of notes about the use of Mathematica **
could easily be extracted with a script. (You don't need to have the *'s. I only
put that to indicate what text would be in a rigid format.) The notes could be
split into multiple paragraphs - one could still extract it with a shell script.
As long as that information is in a rigid format, extracting it is very easy. As
soon as people just write what they fancy on the day, then it would be an
impossible task.
> Though it kind of disappeared from the discussion, I also like adding
> the Wikipedia and Mathworld references. Don't we already have a
> "references" section? This could be extended to including not directly
> cited material. Or we could add a "See also" section, like
> Wikipedia's.
I was thinking of adding them in the doctest, being specific to the command. So
in the above case, we might add
Related external references:
http://en.wikipedia.org/wiki/Factorization
http://en.wikipedia.org/wiki/Integer_factorization
http://mathworld.wolfram.com/Factor.html
http://mathworld.wolfram.com/PrimeFactor.html
http://mathworld.wolfram.com/PolynomialFactorization.html
End of related external references:
Again, if the structure was rigid, these could be extracted with a script and if
necessary one create hyperlinks, which people could click.
> Cheers,
> Johan
Dave