Documentation Quality Initiative
Harald Schilly
documentation. This is the by far most annoying thing about Sage
according to the last survey. I think the userbase is already big and
willing enough to contribute more documentation. To do this in a more
coordinated way, there should be some sort of process and guidelines.
I've seen a - in my eyes - very good approach at the netbeans.org
project. They organize and collect the documentation work in a
standard wiki system and maybe transform those articles or tutorials
into the official documentation later. They have a list of
contributions, a contact email address for each entry (feedback,
errors, and of course attribution! ...), a wish list, some status
information about ongoing processes, their own blog and their own
mailing list. I think, some or all of those ideas could work for Sage
as well and they are also compatible with possible paid contributors.
Read more here http://www.netbeans.org/community/articles/nb-communitydocs-200.html
docs: http://www.netbeans.org/community/commdocs.html
main organization page: http://wiki.netbeans.org/CommunityDocs
I think, Sage could improve very much, by providing more documentation
towards explaining certain tasks, how they are accomplished (also
pointing out what *not* to do to avoid common pitfalls) or by
explaining basics more detailed. It is certainly not enough to point a
new user to an all-in-all documentation, because those documentations
require some knowledge about Sage in the first place, i.e. knowing
where to look for what. It is much more satisfying for new users to
present them thematically narrow examples to give them an instant
moment of success when they execute the tutorial on their own - and
then they are more encouraged to try more...
Therefore, I hope, some folks are interested to start and once there
is already something online, more and more should come.
ideas, thoughts, comments? H
Philippe Saade
On Tue, Aug 26, 2008 at 8:07 PM, Harald Schilly
<harald....@gmail.com> wrote:
>
> Hi, I want to propose a process to increase the quality of the Sage
> documentation. This is the by far most annoying thing about Sage
> according to the last survey. I think the userbase is already big and
> willing enough to contribute more documentation. To do this in a more
> coordinated way, there should be some sort of process and guidelines.
>
I vote for it. And one very important thing IMHO is a script that
could generate most of the code (images, sections, subsections, etc)
from the worksheet. It is painful to have to manage two documents when
correcting errors or changing the code of a cell.
Maybe there should be two kind of cells : code and text(Latex or Html
or structured)
> I've seen a - in my eyes - very good approach at the netbeans.org
> project. They organize and collect the documentation work in a
> standard wiki system and maybe transform those articles or tutorials
> into the official documentation later. They have a list of
> contributions, a contact email address for each entry (feedback,
> errors, and of course attribution! ...), a wish list, some status
> information about ongoing processes, their own blog and their own
> mailing list. I think, some or all of those ideas could work for Sage
> as well and they are also compatible with possible paid contributors.
>
I started learning Java and Netbeans two months ago. It was not easy
but the netbeans.org tutorials are definitely very helpful and
encouraging.
> Read more here http://www.netbeans.org/community/articles/nb-communitydocs-200.html
> docs: http://www.netbeans.org/community/commdocs.html
> main organization page: http://wiki.netbeans.org/CommunityDocs
>
> I think, Sage could improve very much, by providing more documentation
> towards explaining certain tasks, how they are accomplished (also
> pointing out what *not* to do to avoid common pitfalls) or by
> explaining basics more detailed. It is certainly not enough to point a
> new user to an all-in-all documentation, because those documentations
> require some knowledge about Sage in the first place, i.e. knowing
> where to look for what. It is much more satisfying for new users to
> present them thematically narrow examples to give them an instant
> moment of success when they execute the tutorial on their own - and
> then they are more encouraged to try more...
>
I am a mid level teacher/user and i confirm that Sage documentation is
not *always* friendly. (but my respect to those who wrote it...)
Narrow and exhaustive examples are very important i believe
> Therefore, I hope, some folks are interested to start and once there
> is already something online, more and more should come.
>
I am interested (in french ??)
Philippe
> ideas, thoughts, comments? H
>
> >
>
William Stein
Are you saying: "I, Harald, am willing to organize this, and I'm just
curious if people think this is a good idea and would be enthuisiastic
about contributing."
If so, yes, I'm enthuisiastic.
william
Fernando Perez
On Tue, Aug 26, 2008 at 11:07 AM, Harald Schilly
<harald....@gmail.com> wrote:
>
> Hi, I want to propose a process to increase the quality of the Sage
> documentation. This is the by far most annoying thing about Sage
> according to the last survey. I think the userbase is already big and
> willing enough to contribute more documentation. To do this in a more
> coordinated way, there should be some sort of process and guidelines.
It would be great if you could find a way to reuse/improve the tool
recently developed for scipy's 'documentation marathon':
- Live site: http://sd-2116.dedibox.fr/pydocweb/wiki/Front%20Page/
- Project sources: https://code.launchpad.net/~pauli-virtanen/scipy/pydocweb
This tool produced a great amount of improved docs this summer for
numpy. There's a bit too much workflow process for my personal taste,
but perhaps in practice it's the right balance, and it certainly
worked for them.
What that tool is missing is integration with other docs
(sphinx/rest). Right now I think it only does docstrings, and I'd
*love* to have that same workflow for rest doc sources, so that the
public can contribute to all the docs in a wiki, that is automatically
wired to generate diffs for review. For Sage it could create tickets
for your Trac, for numpy it would be numpy/scipy Trac tickets also,
for ipython it could be a special bzr branch on launchpad, etc. A
generic tool of this kind to manage both the 'narrative' docs of a
project and its docstring-based API would be tremendously useful, and
the numpy one is a pretty good start already (and publicly available).
Cheers,
f
Harald Schilly
> Are you saying: "I, Harald, am willing to organize this,...
Ok, then I will start this on a wiki page and yes, organizing is
something i'm better than writing text.
H
Harald Schilly
> I'll keep you updated on
> this tutorial in the next few weeks.
great! also linking to pari, R and other tutorials from the sage
documentation page is a good idea if someone wants to understand those
modules better.
h
Minh Nguyen
On Wed, Aug 27, 2008 at 9:33 AM, Harald Schilly
<harald....@gmail.com> wrote:
[...]
>> I'll keep you updated on
>> this tutorial in the next few weeks.
>
> great! also linking to pari, R and other tutorials from the sage
> documentation page is a good idea if someone wants to understand those
> modules better.
A while ago, I wrote a short tutorial on using Pari/GP to study the
shift (or Caesar) cipher. You can find it at
[1] http://mvngu.wordpress.com/2008/08/20/the-shift-cipher-using-parigp/
Now I'm writing a Sage version of the above tutorial. But I'm not
quite sure about things like presentation, the level of mathematical
rigor, and so on. My current plan is to model this Sage tutorial on
the tutorial at [1]. Ideas, comments, do's and don'ts are welcome.
--
Regards
Minh Van Nguyen
Web: http://nguyenminh2.googlepages.com
Blog: http://mvngu.wordpress.com
CristianCantoro
I'm Cristian Consonni. I wish to contribute to Sage documentations
unless I'm a new user.
(I've produced a very brief Maxima presentation (in italian), you can
find it in Maxima's documentation page)
I hope to hear some news from you soon.
Ciao ciao
Cristian
John Cremona
Thanks for the offer to produce some Sage documentation. Did you mean
documentation in Italian? It's not so clear from what you wrote (I
think you did not mean "unless"?)
Ciao,
John Cremona
(ma non sono Italiano, scusi)
2008/9/13 CristianCantoro <kikkoc...@gmail.com>:
CristianCantoro
The point was: "can I produce some (english) Sage documentation even
if I'm a new user? (i. e. I'm not an expert, I just know some python)
And how?"
However, probably I'll find myself better translating existing
documentation. The SAGE tutorial, for instance. How can I get the TeX
source code?
It's quite long but it could be a good way to start.
> John Cremona
> (ma non sono Italiano, scusi)
Ciao and thank you for your help.
Cristian
John Cremona
>
>
>
> On 14 Set, 21:05, "John Cremona" <john.crem...@gmail.com> wrote:
>> Cristian,
>>
>> Thanks for the offer to produce some Sagedocumentation. Did you meandocumentationin Italian? It's not so clear from what you wrote (I
>> think you did not mean "unless"?)
>
> ... that should have been an "although"... :P.
> The point was: "can I produce some (english) Sage documentation even
> if I'm a new user? (i. e. I'm not an expert, I just know some python)
> And how?"
> However, probably I'll find myself better translating existing
> documentation. The SAGE tutorial, for instance. How can I get the TeX
> source code?
Look in SAGE_ROOT/devel/doc/tut .
John
Jason Grout
> 2008/9/19 CristianCantoro <kikkoc...@gmail.com>:
>>
>>
>> On 14 Set, 21:05, "John Cremona" <john.crem...@gmail.com> wrote:
>>> Cristian,
>>>
>>> Thanks for the offer to produce some Sagedocumentation. Did you meandocumentationin Italian? It's not so clear from what you wrote (I
>>> think you did not mean "unless"?)
>> ... that should have been an "although"... :P.
>> The point was: "can I produce some (english) Sage documentation even
>> if I'm a new user? (i. e. I'm not an expert, I just know some python)
>> And how?"
>> However, probably I'll find myself better translating existing
>> documentation. The SAGE tutorial, for instance. How can I get the TeX
>> source code?
>
> Look in SAGE_ROOT/devel/doc/tut .
Mike Hansen has been redoing all the documentation in a new system and
hopefully his changes will be committed soon. You might want to talk
with him before doing lots of work on the documentation.
-Jason
Minh Nguyen
> Hi Harald,
>
> On Tue, Aug 26, 2008 at 6:07 PM, Harald Schilly
> <harald....@gmail.com> wrote:
>>
>> Hi, I want to propose a process to increase the quality of the Sage
>> documentation. This is the by far most annoying thing about Sage
>> according to the last survey. I think the userbase is already big and
>> willing enough to contribute more documentation. To do this in a more
>> coordinated way, there should be some sort of process and guidelines.
>> Therefore, I hope, some folks are interested to start and once there
>> is already something online, more and more should come.
>>
>> ideas, thoughts, comments? H
>
> I agree with you that there's a need for "short tutorials" on getting
> (new) users familiar with Sage, or at least a (small) subset of its
> features that are useful for what they want to do. I'm in the process
> of writing a short tutorial on using Sage to learn cryptography,
> specifically the shift (or Caesar) cipher. I'll keep you updated on
> this tutorial in the next few weeks.
It has taken me longer than I expected, but here it is:
http://nguyenminh2.googlepages.com/sage_numtheory-crypto.pdf
This is a short tutorial on using Sage to study elementary number
theory and the RSA public key cryptosystem. By "short", I mean at most
10 pages. If anyone has write privileges on the www.sagemath.org
server, you're welcome to put the above PDF document there or
somewhere where folks can access them. Hope (new) users find the
tutorial helpful in getting themselves familiar with Sage.
William Stein
I skimmed the crypto tutorial and liked it. I really wish we
had a bunch of domain-specific tutorials gathered together
and included in a single book or directory with Sage,
and on the website. I wrote one recently for algebraic
number fields. These tutorials would mostly -- like yours
and mine -- assume the reader is new to Sage.
+1
William
--
William Stein
Associate Professor of Mathematics
University of Washington
http://wstein.org
William Stein
>
> William Stein wrote:
>> Hi,
>>
>> I skimmed the crypto tutorial and liked it. I really wish we
>> had a bunch of domain-specific tutorials gathered together
>> and included in a single book or directory with Sage,
>> and on the website.
>
>
> On a serious note, I'm planning to do something similar for Sage. The
> above crypto tutorial is just a start.
>
>
>> I wrote one recently for algebraic
>> number fields. These tutorials would mostly -- like yours
>> and mine -- assume the reader is new to Sage.
>
http://wstein.org/papers/2008-bordeaux/
It's the first lecture of the three there.
William
Ronan Paixão
Em Qua, 2008-11-05 às 12:07 +1100, Minh Nguyen escreveu:
> On Wed, Aug 27, 2008 at 10:17 AM, Minh Nguyen <nguye...@gmail.com> wrote:
> > Hi Harald,
> >
> > On Tue, Aug 26, 2008 at 6:07 PM, Harald Schilly
> > <harald....@gmail.com> wrote:
> >>
> >> Hi, I want to propose a process to increase the quality of the Sage
> >> documentation. This is the by far most annoying thing about Sage
> >> according to the last survey. I think the userbase is already big and
> >> willing enough to contribute more documentation. To do this in a more
> >> coordinated way, there should be some sort of process and guidelines.
> > [...]
> >> Therefore, I hope, some folks are interested to start and once there
> >> is already something online, more and more should come.
> >>
> >> ideas, thoughts, comments? H
> >
It would be nice to have some "code repository" like the cookbook in
ActiveState's website.
I have always envied php.net's help site. Python's documentation (in my
opinion) just isn't par with it, specially in the "examples" category.
At least sage does a good work with most docstrings, with helpful
examples, but sometimes it would be nice to have an easily searchable
database, because a lot of times I know what I want to do but I don't
know what function does it (and sometimes I don't even know there's a
function for it).
Ronan Paixão
William Stein
Having some meta information in docstrings, and extracting
such a document from docstrings would be pretty cool.
Whatever we do, it's critically important that it be automatically
test-able.
William
David Joyner
I am still hoping to replace the document const.tex by
cookbook.tex. I'm happy to assemble the chapters but
even happier if someone else does:-)
I'm not sure what the correct procedure is, so I put a
chapter up on trac http://trac.sagemath.org/sage_trac/ticket/3624
Maybe a wiki page is better though?
Rob Beezer
keeping notes on how to use Sage for this, and distributing them to my
students. So they follow the outline of a typical undergraduate
course on group theory, trying to use only the ideas they have been
taught previously in the course (not always so easy!). Heavy on
PermutationGroup representations. About 10 pages right now at the 2/3
point of the semester. I will likely do the same in the spring with
rings, fields, Galois theory, etc.
They are a typographical mess at the moment, but once the semester
ends I'd be happy to clean them up and contribute them (if they don't
duplicate something out there already). It would be really helpful
if there was an idea of what type of format would be best: wiki,
worksheet, TeX, latex2html, SageTeX, etc. My mess is in LaTeX, but I
have always meant to go back and tidy it up, so a conversion wouldn't
be that painful. Some guidance on format would be helpful to those
perhaps just starting out on a similar tack.
Thanks to Harald for getting this started. Like others have said,
some pointed, direct expositions in focused domains would help folks
who are just getting started.
+1
On Nov 4, 5:42 pm, "William Stein" <wst...@gmail.com> wrote:
> Hi,
>
> I skimmed the crypto tutorial and liked it. I really wish we
> had a bunch of domain-specific tutorials gathered together
> and included in a single book or directory with Sage,
> and on the website. I wrote one recently for algebraic
> number fields. These tutorials would mostly -- like yours
> and mine -- assume the reader is new to Sage.
>
> +1
>
> William
>
>
>
Minh Nguyen
Rob Beezer wrote:
> As I have been teaching abstract algebra this semester, I have been
> keeping notes on how to use Sage for this, and distributing them to my
> students. So they follow the outline of a typical undergraduate
> course on group theory, trying to use only the ideas they have been
> taught previously in the course (not always so easy!). Heavy on
> PermutationGroup representations. About 10 pages right now at the 2/3
> point of the semester. I will likely do the same in the spring with
> rings, fields, Galois theory, etc.
>
> They are a typographical mess at the moment, but once the semester
> ends I'd be happy to clean them up and contribute them (if they don't
> duplicate something out there already). It would be really helpful
> if there was an idea of what type of format would be best: wiki,
> worksheet, TeX, latex2html, SageTeX, etc. My mess is in LaTeX, but I
> have always meant to go back and tidy it up, so a conversion wouldn't
> be that painful. Some guidance on format would be helpful to those
> perhaps just starting out on a similar tack.
A good way to do it is to "dump" your abstract algebra notes on a novice
like me :-) I'd be more than happy to go over your notes, tidy up
typographical stuff, LaTeXing your notes, polish them for Sage
beginners, etc. I'm planning to write more tutorials for Sage beginners,
so I don't want to duplicate efforts in this regard.
> Thanks to Harald for getting this started. Like others have said,
> some pointed, direct expositions in focused domains would help folks
> who are just getting started.
>
> +1
Rob Beezer
back in touch once I have something to "dump" your way. ;-)
Rob
Minh Nguyen
Martin Albrecht wrote:
>> http://nguyenminh2.googlepages.com/sage_numtheory-crypto.pdf
>>
>> This is a short tutorial on using Sage to study elementary number
>> theory and the RSA public key cryptosystem. By "short", I mean at most
>> 10 pages. If anyone has write privileges on the www.sagemath.org
>> server, you're welcome to put the above PDF document there or
>> somewhere where folks can access them. Hope (new) users find the
>> tutorial helpful in getting themselves familiar with Sage.
>
> Hi Minh,
>
> I have a few remarks about your nice introduction. I'm not sure whether you
> accept criticism/suggestions, but I figured I send them in any case:
>
> 1) "Modern cryptography uses many fundamental concepts from number theory"
>
> I think the precise statement would be that public key cryptography uses many
> fundamental concepts from number theory. Most of symmetric cryptography is
> not based on a computational (perceived) hard mathematical problem.
When I wrote that statement, I was also thinking of hardware
implementation as well, such as using the Chinese Remainder Theorem for
efficient arithmetic at the hardware level, etc. Of course in this
sense, any computation that involves hardware uses hardware
implementations of fundamental concepts from number theory. Since you've
made a distinction above between public key and symmetric cryptography
(without explicitly appealing to hardware implementation), I think I
should make the following change in order to avoid confusion on the part
of readers:
-"Modern cryptography uses many fundamental concepts from number theory"
+"Public key cryptography uses many fundamental concepts from number theory"
> 2) "The command gcd has an optional argument called integer, which defaults to
> the value of False."
>
> It might be worth pointing out that this flag has no effect on the result that
> is returned.
Yep, you're right. Tutorial's updated.
> Also note to self: the flag seems odd to me, why don't we just
> check types?
>
> 3) "How to keep a secret"
>
> This section seems to give an example for encoding a message and not
> encryption. The encoding provides no security at all. You probably know that
> but it might make sense to point it out very explicitly.
This tutorial is mostly for folks who don't have prior
knowledge/experience with cryptography. In particular, students who are
taking a first course in cryptography at the undergraduate level can use
this tutorial while doing so. I did mention that it's "a simple method
of scrambling a message written in English". But it wouldn't hurt anyone
to also clarify the relative cryptographic insecurity of that "simple
method".
> 4) Generating public and private keys
>
> Choosing p and q of such different sizes is really a bad idea and IMHO
> shouldn't be encouraged. The hardness of factorisation depends on the size
> (and form) of the smaller factor.
Technically, you're right. But again, this tutorial is for Sage
beginners and, I also assume, folks doing cryptography for the first
time. I can write about special attacks against RSA, but that would
increase the page count of the tutorial. Remember, we want "short"
tutorials to introduce Sage beginners to various features of Sage. For
more in-depth information, there's the official reference manual as well
as the source code. I've provided references if readers want more stuff
on cryptography or Sage. Furthermore, at the beginning of the tutorial,
I've provided various avenues for obtaining more help.
> 5) the pseudocode on top of page 8
>
> sage: m = list("HELLOWORLD")
> sage: S = list("ABCDEFGHIJKLMNOPQRSTUVWXYZ")
> sage: for i in xrange(len(m)):
> for j in xrange(len(S)):
> if m[i] == S[j]:
> m[i] = j + 65
>
> can be done more python-ic like this:
>
> sage: m = "HELLOWORLD" # no need for list()
> sage: m = [ord(c) for c in m]
> Also, you can convert to an integer like this:
>
> sage: ZZ(list(reversed(m)),100)
> 72697676798779827668
Yep, list comprehension and friends are nice features of Python, and I
really like them. But I don't want to assume that Sage beginners are
familiar with those features. Of course, the pseudocode can be
re-written like this:
[1]
sage: m = "HELLOWORLD"
sage: m = [ord(c) for c in m] ; m
[72, 69, 76, 76, 79, 87, 79, 82, 76, 68]
sage: m = ZZ(list(reversed(m)), 100) ; m
72697676798779827668
which is short, elegant and Pythonic. The tutorial has now been updated
with the above code --- and I hope it doesn't result in too much
confusion on the part of beginners.
> 6) "Brute force modular exponentiation"
>
> What is brute force modular exponentiation? Do you mean naive exponentiation
> over ZZ?
Yep, like trying to naively compute a^b first, then reduce modulo n.
> Also note that if you just create the IntegerModRing (the Sage way) then
> exponentiation just works as it should:
>
> sage: R = IntegerModRing(1000)
> sage: e = R.random_element()
> sage: e^3423523523513513513513524643636
> 81
Yep, but any element from R.random_element() is not guaranteed to be
relatively prime to 1000, for example. We can do this:
sage: n = 4951760154835678088235319297
sage: N = IntegerModRing(euler_phi(n))
sage: e = N.random_element()
sage: gcd(Integer(e), euler_phi(n))
3
But what we require is some positive $e \in Z$ that is relatively prime
to $\phi(n)$. Then we'd still need a test for relative primeness with
respect to $\phi(n)$. OK, no problem, how about this:
[2]
sage: n = 4951760154835678088235319297
sage: N = IntegerModRing(euler_phi(n))
sage: e = N.random_element()
sage: while gcd(Integer(e), euler_phi(n)) != 1:
....: e = N.random_element()
....:
sage: e
4548792647289896041320266443
sage: gcd(Integer(e), euler_phi(n))
1
But from [1], we have
sage: type(m)
<type 'sage.rings.integer.Integer'>
so Sage goes berserk here:
sage: m^e
---------------------------------------------------------------------------
RuntimeError Traceback (most recent call last)
/home/mvngu/<ipython console> in <module>()
/home/mvngu/usr/bin/sage-3.1.4/local/lib/python2.5/site-packages/sage/rings/integer.so
in sage.rings.integer.Integer.__pow__ (sage/rings/integer.c:9650)()
RuntimeError: exponent must be at most 2147483647
So in this case, it doesn't help to generate $e$ using [2].
> 7) for i in xrange(len(bin))
>
> that seems un-Pythonic to me. Why not do
>
> for b in b.digits() ?
Yep, we can do that. However, note that
sage: 2.digits()
[0, 1]
sage: list(Integer.binary(2))
['1', '0']
so 2.digits() returns the binary digits of the integer 2 but the order
of those digits are reversed. OK, this is more Pythonic:
def modexp(a, b, n):
d = 1
for i in list(Integer.binary(b)):
d = mod(d * d, n)
if Integer(i) == 1:
d = mod(d * a, n)
return Integer(d)
> I hope you find my comments helpful.
I greatly appreciate all your comments and suggestions. The tutorial has
been updated to reflect many of your suggestions. Here it is, hot off
the digital press:
http://nguyenminh2.googlepages.com/sage_numtheory-crypto-v2.pdf
William Stein
>> 4) Generating public and private keys
>>
>> Choosing p and q of such different sizes is really a bad idea and IMHO
>> shouldn't be encouraged. The hardness of factorisation depends on the size
>> (and form) of the smaller factor.
>
> Technically, you're right. But again, this tutorial is for Sage
I basically agree with all your responses except this one. It's
really bad chosing p and q to be far from each or of a special
form (Mersenne primes). It's really critically important that the
primes be chosen of relatively the same size (but not too close!),
and be chosen at random. That one can chose primes at random
requires a fast (pseudo)-primality test, and that these exist is
really a major important central idea in public-key crypto.
So, I encourage you to either change your choice of p,q in that
example, or to put in a warning.
William
John Cremona
Actually since 3.2.alpha1 the Integer parameter is no longer there in
gcd() and lcm() (see #3118).
John
Martin Albrecht
sorry for taking this off-list earlier.
> > 1) "Modern cryptography uses many fundamental concepts from number
> > theory"
> >
> > I think the precise statement would be that public key cryptography uses
> > many fundamental concepts from number theory. Most of symmetric
> > cryptography is not based on a computational (perceived) hard
> > mathematical problem.
>
> When I wrote that statement, I was also thinking of hardware
> implementation as well, such as using the Chinese Remainder Theorem for
> efficient arithmetic at the hardware level, etc. Of course in this
> sense, any computation that involves hardware uses hardware
> implementations of fundamental concepts from number theory.
But most symmetric cryptography constructs don't use big numbers: most block
ciphers, most stream ciphers, most hash functions. They are designed for
speed and avoid bigint arithmetic where possible. Of course, there are a few
exceptions but AFAIK they are not used in practice.
> Since you've
> made a distinction above between public key and symmetric cryptography
> (without explicitly appealing to hardware implementation), I think I
> should make the following change in order to avoid confusion on the part
> of readers:
>
> -"Modern cryptography uses many fundamental concepts from number theory"
>
> +"Public key cryptography uses many fundamental concepts from number
> theory"
>
> > 3) "How to keep a secret"
> >
> > This section seems to give an example for encoding a message and not
> > encryption. The encoding provides no security at all. You probably know
> > that but it might make sense to point it out very explicitly.
>
> This tutorial is mostly for folks who don't have prior
> knowledge/experience with cryptography. In particular, students who are
> taking a first course in cryptography at the undergraduate level can use
> this tutorial while doing so. I did mention that it's "a simple method
> of scrambling a message written in English". But it wouldn't hurt anyone
> to also clarify the relative cryptographic insecurity of that "simple
> method".
I might be a bit pedantic but this scrambling has less than relative
insecurity, it doesn't provide any. I think being somewhat precise this issue
is worth it because:
- people who read the tutorial but who are familiar with basic cryptology
don't get the wrong impression that "the Sage folks" don't know what they are
talking about
- students don't get the wrong impression that coming up with encryption
algorithms is straight-forward.
For fun, here's the 'attack' if one doesn't recognise the ASCII directly:
sage: s = "Sage can be used to study general and advanced, pure and applied
mathematics. This includes a huge range of mathematics, including algebra,
calculus, elementary to very advanced number theory, cryptography, numerical
computation, commutative algebra, group theory, combinatorics, graph theory,
exact linear algebra and much more. It combines various software packages and
seamlessly integrates their functionality into a common experience. It is
well suited for education, studying and research. The interface is a
notebook in a web-browser or the command-line. Using the notebook, Sage
connects either locally to your own Sage installation or to a Sage server on
the network. Inside the Sage notebook you can create embedded graphics,
beautifully typeset mathematical expressions, add and delete input, and share
your work across the network. The following showcase presents some of Sage's
capabilities, screenshots and gives you an overall impression of what Sage
is. The examples show the lines of code in Sage on the left side, accompanied
by an explanation on the right. They only show the very basic concepts of how
Sage works. Please refer to the documentation material for more detailed
explanations or visit the library to see Sage in action."
sage: s = map(ord,s)
sage: from rpy import r
sage: r.png('histogram.png',width=900,height=480)
sage: r.hist(s,r.seq(min(s),max(s)),main="Histogram",col="lightblue",
prob=True, xlab="orders")
sage: r.dev_off()
The Basic Cryptanalysis US Army Field Manual (aka the Cryptonomicon ;-)) has a
nice introduction http://www.umich.edu/~umich/fm-34-40-2/ :-) Stinson's book
is a good (and civil) reference. I'm not implying you don't know all this,
I'm just pointing it out in case someone else on [sage-devel] doesn't.
> > 4) Generating public and private keys
> >
> > Choosing p and q of such different sizes is really a bad idea and IMHO
> > shouldn't be encouraged. The hardness of factorisation depends on the
> > size (and form) of the smaller factor.
>
> Technically, you're right. But again, this tutorial is for Sage
> beginners and, I also assume, folks doing cryptography for the first
> time. I can write about special attacks against RSA, but that would
> increase the page count of the tutorial. Remember, we want "short"
> tutorials to introduce Sage beginners to various features of Sage. For
> more in-depth information, there's the official reference manual as well
> as the source code. I've provided references if readers want more stuff
> on cryptography or Sage. Furthermore, at the beginning of the tutorial,
> I've provided various avenues for obtaining more help.
I agree with William here that at least a note should be added that this
construction is insecure and for education purposes only.
> which is short, elegant and Pythonic. The tutorial has now been updated
> with the above code --- and I hope it doesn't result in too much
> confusion on the part of beginners.
What is the general opinion on this matter? Is it fine to suppose some
knowledge of Python?
> > 6) "Brute force modular exponentiation"
> >
> > What is brute force modular exponentiation? Do you mean naive
> > exponentiation over ZZ?
>
> Yep, like trying to naively compute a^b first, then reduce modulo n.
Brute force sounds like trial-and-error to me.
Yep, of course we need to check for some properties of e first.
> But from [1], we have
>
> sage: type(m)
> <type 'sage.rings.integer.Integer'>
>
> so Sage goes berserk here:
>
> sage: m^e
> ---------------------------------------------------------------------------
> RuntimeError Traceback (most recent call last)
>
> /home/mvngu/<ipython console> in <module>()
>
> /home/mvngu/usr/bin/sage-3.1.4/local/lib/python2.5/site-packages/sage/rings
>/integer.so in sage.rings.integer.Integer.__pow__
> (sage/rings/integer.c:9650)()
>
> RuntimeError: exponent must be at most 2147483647
>
> So in this case, it doesn't help to generate $e$ using [2].
I think it does if you then coerce the result to ZZ. One of the main features
of Sage IMHO is its object oriented approach i.e. that it is much more than a
calculator. If I was to write such an introduction I would like to introduce
this feature which makes working with many things much easier (i.e. having
rings one defines first etc.).
> > 7) for i in xrange(len(bin))
> >
> > that seems un-Pythonic to me. Why not do
> >
> > for b in b.digits() ?
>
> Yep, we can do that. However, note that
>
> sage: 2.digits()
> [0, 1]
> sage: list(Integer.binary(2))
> ['1', '0']
>
> so 2.digits() returns the binary digits of the integer 2 but the order
> of those digits are reversed. OK, this is more Pythonic:
>
> def modexp(a, b, n):
> d = 1
> for i in list(Integer.binary(b)):
> d = mod(d * d, n)
> if Integer(i) == 1:
> d = mod(d * a, n)
> return Integer(d)
Sage is in many areas little-endian friendly (smallest thingy comes first)
because this is how number theorist like it. You can always call the reversed
iterator on digits() though. However, this is really pedantic now and I'll
shut up :)
Martin
--
name: Martin Albrecht
_pgp: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x8EF0DC99
_www: http://www.informatik.uni-bremen.de/~malb
_jab: martinr...@jabber.ccc.de
Ronan Paixão
I've been thinking about doing something like that for quite a while
through pydoc (which is plain ugly), but time doesn't come easy for
students (not counting my low programming skills).
The docstrings way would be nice, because if one knows the function it
would be easier to get to examples. However, it's not practical to have
too many examples on a docstring, and that restriction would not fulfill
the requirements of a cookbook.
The easy way to do it would be to create a wiki entry and use that as a
starting point for focused examples. That way it would be possible to
structure content in a "followable" manner.
Another way would be to make a special notebook version which could be
used wiki-like, implementing inter-worksheet links and searching.
Sagenb.org itself could be used somewhat like that, but since it's some
sort of test-before-downloading server, there's just too many noise and
not everyone is focusing on quality. Notice that a wiki-like notebook
would allow easy importing of the worksheets that are of good quality.
That would also help initiatives like Rob Beezer's of doing a sage-based
book with executable parts.
In either way, important examples can be referenced as links in the
docstrings themselves. If any sort of numbering can be placed in the
webpages, it would be even easier to reference examples. An idea is
placing a list of numbers for each function and have a list of them.
Imagine calling example(plot) or example(plot.examples) opening a new
window in the browser with the examples.
If any sort of customization is made in the wiki, some kind of spider
could also be used to create an optional spkg with all examples in the
wiki (maybe not practical, but probably doable).
Ronan Paixão
Minh Nguyen
Here it is, the latest version of a Sage tutorial in number theory and
crypto:
http://nguyenminh2.googlepages.com/sage_numtheory-crypto-v3.pdf
This version incorporates suggestions from John, Martin and William, and
they are duly acknowledged in the document itself. Please remind me if
I've failed to acknowledge anyone else.
OK, it now seems that at least 4 people have contributed to this
tutorial. Who says we don't have time to write tutorials for Sage? :-)
Jason Grout
> Hi folks,
>
> Here it is, the latest version of a Sage tutorial in number theory and
> crypto:
>
> http://nguyenminh2.googlepages.com/sage_numtheory-crypto-v3.pdf
>
> This version incorporates suggestions from John, Martin and William, and
> they are duly acknowledged in the document itself. Please remind me if
> I've failed to acknowledge anyone else.
>
>
> OK, it now seems that at least 4 people have contributed to this
> tutorial. Who says we don't have time to write tutorials for Sage? :-)
As long as someone takes the initiative to get it started, things often
get done. It's the initial effort that takes the most work, though. So
thanks!
Jason
Harald Schilly
> Here it is, the latest version of a Sage tutorial in number theory and
> crypto:
>
> http://nguyenminh2.googlepages.com/sage_numtheory-crypto-v3.pdf
expected.
It's now linked from here: http://wiki.sagemath.org/DocumentationProject
More generally speaking, i think it's important to write such
tutorials and "extended examples" and collect them. I've started this
wiki page above some time ago. Hopefully [if not, everybody can
edit :) ], it should explain itself and i hope some more content will
follow. I know that everything is spread across various pages and
links, but i'm confident that this will organize once there is a bit
of a structure.
Harald
David Joyner
Thanks for setting this up.
Just added the error-correcting codes paper to it.
>
> Harald
> >
>
Rob Beezer
graph theory commands to the Documentation Project wiki. These are
designed for a first-time student of the subject and are being
developed as I teach such a course this semester. So they should see
frequent updates for the next few weeks.
General comments on direction, format, purpose and gross
misunderstandings of Sage are all welcome. Typos, minor
reorganizations and inconsistencies can probably wait. ;-)
Rob Beezer
Jan Groenewald
On Tue, Nov 04, 2008 at 05:42:02PM -0800, William Stein wrote:
> I skimmed the crypto tutorial and liked it. I really wish we
> had a bunch of domain-specific tutorials gathered together
> and included in a single book or directory with Sage,
> and on the website. I wrote one recently for algebraic
> number fields. These tutorials would mostly -- like yours
> and mine -- assume the reader is new to Sage.
What about being able to click on "tutorial" somewhere near "new worksheet"
in the sage notebook? Which could present you cell by cell with explanatory
text, and then you execute the command to continue, and get a chance to try
variations. I have no idea what the implementation issues are, but from
a user perspective this sounds nice to me.
regards,
Jan
Jason Merrill
On Nov 6, 4:11 am, Jan Groenewald <j...@aims.ac.za> wrote:
> What about being able to click on "tutorial" somewhere near "new worksheet"
> in the sage notebook? Which could present you cell by cell with explanatory
> text, and then you execute the command to continue, and get a chance to try
> variations. I have no idea what the implementation issues are, but from
> a user perspective this sounds nice to me.
adjustable.
JM
David Joyner
>
> In the spirit of "release early" I've added my (incomplete) notes on
> graph theory commands to the Documentation Project wiki. These are
You meant "group theory" not "graph theory".
I looked at it briefly.
On page 3, the quotes around (1,3)(2,45,4) are the wrong ones.
You can use those used on oage 6, for example. My students make
mistakes using the wrong quotes frequently. Feel free to
reference and/or steal examples from
http://sage.math.washington.edu/home/wdj/expository/groups-sage4.pdf
Rob Beezer
Thanks for the peek and the corrections. And thanks for permission to
use material from your group theory write-up, which I found very
helpful as I got started.
Yes, GROUP theory. Graph theory will be next. ;-)
Available off the wiki, but I also meant to include a link:
http://buzzard.ups.edu/sage/sage-group-theory.pdf
Rob
On Nov 6, 6:15 am, "David Joyner" <wdjoy...@gmail.com> wrote:
> On Thu, Nov 6, 2008 at 1:11 AM, Rob Beezer <goo...@beezer.cotse.net> wrote:
>
> > In the spirit of "release early" I've added my (incomplete) notes on
> > graph theory commands to the Documentation Project wiki. These are
>
> You meant "group theory" not "graph theory".
>
> I looked at it briefly.
>
> On page 3, the quotes around (1,3)(2,45,4) are the wrong ones.
> You can use those used on oage 6, for example. My students make
> mistakes using the wrong quotes frequently. Feel free to