A SymPy tutorial for students

[Ivan Savov]

Dear SymPy developers,

I'm a big fan of sympy and have been using it to learn and teach math and physics

for many years. Awesome work! Thank you all for building this powerful tool.

This summer I wrote a sympy tutorial intended for students that explains the

basics of using SymPy for solving typical high school math problems, and 

also covers a bit of calculus, mechanics, vectors, and linear algebra.

See the PDF of it here: http://minireference.com/static/sympy_tutorial.pdf

I want to contribute the tutorial to the SymPy project  (minus the book plug of course), 

and I want to know what's the best way to go about this. Specifically:

• Do you think this tutorial will be useful?
• If yes, what should be the title? Sympy tutorial 2?  SymPy tutorial for students?
• What license should I use to make it compatible/includable with SymPy? 

I plan to continue to distribute the IEEEtran formatted pdf from my site for

marketing purposes, but I can convert the text into .rst for ease of merging into /doc/src/.

Note, currently, Z. Janák is working on converting the tutorial into an ipython notebook:

http://nbviewer.ipython.org/gist/ivanistheone/74144fee778d1f117c99

this work will be happening here: https://github.com/ivanistheone/sympy_tutorial/

He recommended CC BY-SA for the notebooks. Is CC BY-SA compatible with:

https://github.com/sympy/sympy/blob/master/LICENSE  ?

Best,

  Ivan

[Aaron Meurer]

On Sat, Jan 31, 2015 at 12:41 PM, Ivan Savov <ivan....@gmail.com> wrote:

Dear SymPy developers,

I'm a big fan of sympy and have been using it to learn and teach math and physics

for many years. Awesome work! Thank you all for building this powerful tool.

This summer I wrote a sympy tutorial intended for students that explains the

basics of using SymPy for solving typical high school math problems, and 

also covers a bit of calculus, mechanics, vectors, and linear algebra.

See the PDF of it here: http://minireference.com/static/sympy_tutorial.pdf

Good work.

 

I want to contribute the tutorial to the SymPy project  (minus the book plug of course), 

and I want to know what's the best way to go about this. Specifically:

• Do you think this tutorial will be useful?
• If yes, what should be the title? Sympy tutorial 2?  SymPy tutorial for students?
• What license should I use to make it compatible/includable with SymPy? 

I plan to continue to distribute the IEEEtran formatted pdf from my site for

marketing purposes, but I can convert the text into .rst for ease of merging into /doc/src/.

There is definitely useful material here. There is also material that is effectively duplicate what is already in the existing tutorial. It would probably be confusing to have two tutorials. 

How do you feel about contributing the parts that aren't in the existing tutorial at all (like the mechanics), improving the parts that are in the existing tutorial but not as well done (like the matrices), and looking at the base SymPy stuff and seeing what can be improved. 

I'm also welcome to general suggestions and improvements to the current SymPy tutorial.

One difference I notice between your tutorial and the official SymPy one is that yours also teaches some math along the way, whereas the SymPy one assumes the reader already knows the math behind the various functions. Which way do you think is better? I wrote the current SymPy tutorial, and I used that style because it simplifies things, especially for readers who already know the math.

 

Note, currently, Z. Janák is working on converting the tutorial into an ipython notebook:

http://nbviewer.ipython.org/gist/ivanistheone/74144fee778d1f117c99

this work will be happening here: https://github.com/ivanistheone/sympy_tutorial/

He recommended CC BY-SA for the notebooks. Is CC BY-SA compatible with:

https://github.com/sympy/sympy/blob/master/LICENSE  ?

IANAL, but I believe CC BY-SA is not compatible with BSD, because of the SA (share alike), which makes it copyleft. Regardless, I think at best, it would be a confusing situation to have different parts of SymPy be licensed differently, so if you want to contribute this to SymPy, it would be best if you licensed it as BSD (my understanding of dual licensing is that you can also license it as something else for other purposes if you want).

Aaron Meurer

 

Best,

  Ivan

--
You received this message because you are subscribed to the Google Groups "sympy" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sympy+un...@googlegroups.com.
To post to this group, send email to sy...@googlegroups.com.
Visit this group at http://groups.google.com/group/sympy.
To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/6c54bdb0-1ed3-4bd9-b8ee-e8725dae9b29%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Ivan Savov]

Hi Aaron, 

I plan to continue to distribute the IEEEtran formatted pdf from my site for

marketing purposes, but I can convert the text into .rst for ease of merging into /doc/src/.

There is definitely useful material here. There is also material that is effectively duplicate what is already in the existing tutorial. It would probably be confusing to have two tutorials. 

The reason I was suggesting two parallel tutorials is for the different intended audiences.

Think of this as different sections in man pages:

• the official tutorial is   symp_tutorial(3)    intended for programmers
  
• my tutorial is symp_tutorial(1) intended for end users (w/o dev skills)

 

How do you feel about contributing the parts that aren't in the existing tutorial at all (like the mechanics),

improving the parts that are in the existing tutorial but not as well done (like the matrices), 

 

This could work, though it will be a week or two of editing to merge the two narratives...

Also, I think both tutorial could benefit being "presentable" as ipython notebooks.

(I believe I've seen some other HOWTOs on sympy, delivered as notebooks).

and looking at the base SymPy stuff and seeing what can be improved. 

I'm also welcome to general suggestions and improvements to the current SymPy tutorial.

 

I have somewhat limited time during the coming weeks, but I'll print out the current

tutorial and try to imagine a narratives-merge that sticks....  Also I imagine the 

combined tutorial will be quite long---we'll almost need a tutorial to the tutorial ;)

 

One difference I notice between your tutorial and the official SymPy one is that yours also teaches some math along the way, whereas the SymPy one assumes the reader already knows the math behind the various functions. Which way do you think is better? I wrote the current SymPy tutorial, and I used that style because it simplifies things, especially for readers who already know the math.

 

That's an interesting question, and one all technical writers face constantly. The intended reader could have:

• Different computer skills:  non-technical (used to clicking on stuff); poweruser (knows what a command line is);  or developer.
• Different math background:   no-math;   HS level proficiency; university level;  or  graduate level.
• Willing to invest different amount of time:  5-mins; 20-mins; or 60-mins   to read the tutorial.

One could say we need 3*4*3 different versions!

My guess is aiming for "HS level" math discourse can only be a good thing, so long as the explanations don't go on tangents, i.e., one or two sentences added as math introduction is OK, but adding paragraphs of "theory" would slow down the reading to much for people in the know.

An unrelated idea --- but related to attention span --- is a possible split of the tutorial into a "Quickstart" (20 mins) and a "Tutorial" (1 hour). 

[...] Is CC BY-SA compatible with:  https://github.com/sympy/sympy/blob/master/LICENSE  ?

IANAL, but I believe CC BY-SA is not compatible with BSD, because of the SA (share alike), which makes it copyleft.

it would be best if you licensed it as BSD [...]

BSD it will be then!

  - Ivan 

[Jason Moore]

I like the idea of adding the tutorial as is. I don't think it hurts to have the two different perspectives. +1 to adding a second tutorial to the docs.

Jason
moorepants.info
+01 530-601-9791

--

You received this message because you are subscribed to the Google Groups "sympy" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sympy+un...@googlegroups.com.
To post to this group, send email to sy...@googlegroups.com.
Visit this group at http://groups.google.com/group/sympy.

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/778ec05e-329f-4bac-a5f0-480b48e9e442%40googlegroups.com.

[Joachim Durchholz]

Am 01.02.2015 um 01:30 schrieb Jason Moore:
> I like the idea of adding the tutorial as is. I don't think it hurts to
> have the two different perspectives. +1 to adding a second tutorial to the
> docs.

I'd want that the links to the tutorials have enough descriptive text to
that readers can decide which link to click.
With that in place, I do not see much room for confusion.

There's a different reason to merge: More tutorials means more official
text to review for validity with every SymPy release.
Can this work be kept to a minimum?
Main point would be to make sure that all examples still work. I'd
almost expect that SymPy's release procedure has some doctest equivalent
for the tutorial; it should be relatively easy to extend that to the new
tutorial (the new tutorial might need to follow some conventions to
allow this, so there might still be work involved).

Just my 2c.

[Ivan Savov]

I'd want that the links to the tutorials have enough descriptive text to
that readers can decide which link to click.
With that in place, I do not see much room for confusion.

What do you think the two links should say?
There is a lot of overlap between the two docs (intro, basics, and many topics).

 

There's a different reason to merge: More tutorials means more official
text to review for validity with every SymPy release.
Can this work be kept to a minimum?
Main point would be to make sure that all examples still work. I'd
almost expect that SymPy's release procedure has some doctest equivalent
for the tutorial;

That's a very cool idea.  Apparently, we can already run .rst files (and .md files)
through doctest and the code blocks within them will be processed. For example:

$ cat tut.rst
=======
WELCOME
=======

The ``string`` module comes with some useful constants.

For example::

   >>> import string
   >>> string.ascii_letters
   'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'

Which can then be tested using:

$ python -m doctest -v tut.rst
Trying:
    import string
Expecting nothing
ok
Trying:
    string.ascii_letters
Expecting:
    'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
ok
1 items passed all tests:
   2 tests in tut.rst
2 tests in 1 items.
2 passed and 0 failed.
Test passed.

I also tried running the files in doc/src/tutorial  through doctest
and most of them pass (except for minor formatting differences,
like line breaks and latex output using unicode symbols).
Maybe we need a doctest-variant that is tolerant towards
minor formatting diffs and the whole "testing the docs" could
be automated...



Ivan






Ivan

[Ondřej Čertík]

Hi Ivan,

It is already automated, see here:

https://github.com/sympy/sympy/blob/398fbec97d65c76483c32640b85672710b029551/bin/test_travis.sh#L42

and a sample result here, I put the link at the line which tests the tutorial:

https://travis-ci.org/sympy/sympy/jobs/49419181#L3709


Overall I am fine with putting your tutorial in (mostly as it is), as
long as it is tested in a similar way. Do you plan to put it in as
sphinx or the notebook?

Ondrej

[Ondřej Čertík]

> IANAL, but I believe CC BY-SA is not compatible with BSD, because of the SA
> (share alike), which makes it copyleft. Regardless, I think at best, it
> would be a confusing situation to have different parts of SymPy be licensed
> differently, so if you want to contribute this to SymPy, it would be best if
> you licensed it as BSD (my understanding of dual licensing is that you can
> also license it as something else for other purposes if you want).

You own copyright to what you created, so by submitting a PR to sympy,
you agree to license your contribution under BSD, but you still have
full right to put your own contribution on your website and use any
license you want (including commercial).

Ondrej