Self-introduction--Interest: Making SymPy easier for new users via documentation

[Jeremy Monat]

Hello, I'm Jeremy Monat. My primary interest in helping with SymPy development is making it easier for new users to use SymPy by improving the documentation. It is plenty powerful for the application I needed; learning how to use SymPy was the challenge for me.

• level of familiarity with python (years of programming, previous projects): 1 year of experience with artificial intelligence (natural language processing) and materials informatics
  
• mathematical education level (high school / ... / PhD?): minor as part of BS degree
  
• particular expertise (physics? biology? ...subtopics): PhD in physical chemistry--laser spectroscopy of molecules for solar electricity cells. Currently a software developer for applications in operations research.
  
• particular algorithmic interests: Solvers
  
• level of familiarity with symbolic math systems "computer algebra": Used Mathematica quite a while ago
  
• your familiarity with SymPy (e.g. how have you used SymPy)? Used SyPy to solve systems of inequalities to bound the ranges of parameters for materials informatics
  
• other possibly relevant information -- geographical location? native language?: USA. English.
  

[David Bailey]

On 27/11/2021 18:20, Jeremy Monat wrote:

Hello, I'm Jeremy Monat. My primary interest in helping with SymPy development is making it easier for new users to use SymPy by improving the documentation. It is plenty powerful for the application I needed; learning how to use SymPy was the challenge for me.

I agree that SymPy documentation really doesn't begin to justice to the quality of this software

I suspect the problem is that most of us - developers and users - are keen on programming, not on writing documentation. I'm definitely guilty as charged.

Just one of the problems I find, is that the documentation is incredibly uneven. Just as an example in 3.4.6 we learn that sqrt is not a function, which is a fairly elementary piece of information - it translates immediately into Pow, but then the example it gives IMHO, is anything but elementary! Indeed this is the first mention of the Wild() in the documentation.

Incidentally, if you try help(sqrt) the response starts with:

"Help on function sqrt in module sympy.functions.elementary.miscellaneous"

Best wishes,

David

[Oscar Benjamin]

On Sun, 28 Nov 2021 at 11:09, Jeremy Monat <jem...@gmail.com> wrote:
>
> Hello, I'm Jeremy Monat. My primary interest in helping with SymPy development is making it easier for new users to use SymPy by improving the documentation. It is plenty powerful for the application I needed; learning how to use SymPy was the challenge for me.

Hello and welcome Jeremy. Contributions to improving the documentation
are absolutely welcome. There are a few things already happening in
relation to this.

We've just had a GSOD (Google Summer of Docs) project working on
reorganising the documentation from a high-level. This was work by
Joannah Nanjekye looking at different aspects of how to organise
things. The most immediately noticeable change is the new front page
which you can see in the dev docs for the next release:
https://docs.sympy.org/latest/index.html
https://docs.sympy.org/dev/index.html

There is plenty more to do in terms of organisation. I'd like to break
down the long API doc pages into smaller more organised pages more
like this:
https://numpy.org/doc/stable/reference/routines.fft.html
There was a PR to do that somewhere but it seems to have stalled.

Another thing happening right now is that Aaron Meurer is being funded
by CZI to spend time writing new docs with a particular focus on
guides for general usage rather than basic API docs. I bet Aaron would
be grateful or any insights you have on what is really needed.

Absolutely more is needed in improving the docs though. A good example
is that you said your interest area was solvers. There should be a
guide somewhere that explains how to "solve equations". There are so
many different options for doing this in SymPy and I don't think many
users understand what the pros and cons are or when each is
applicable. Instead of a good guide explaining these we have things
like this:
https://docs.sympy.org/latest/modules/solvers/solveset.html#what-will-you-do-with-the-old-solve
That page implies that solveset will replace solve and that solve
should not be used any more (not at all true!). That kind of thing
leads to a lot of confusion for people learning to use SymPy because
it makes them think that they should use solveset instead of solve but
solveset does not even begin to replace solve because it doesn't
handle multivariate equations.

--
Oscar

[Jeremy Monat]

David and Oscar,

Glad there is agreement on the need for improved documentation! And that there's a Google Summer of Documentation to go along with the one of Code.

>There should be a guide somewhere that explains how to "solve equations".

Definitely--web searches for things such as "SymPy solve inequalities" return the Inequality Solvers page, and there's nothing telling the visitor that they should probably be using a high-level solver such as solve() or solveset().

There also needs to be a page on how to programmatically parse results of e.g. solve()--there's nothing on the site that I could find. For example, to answer my StackOveflow question about parsing results, smichr put together three concepts that I could not glean from the documentation, certainly not all in one place:

1. Solved inequalities can be parsed using .atoms()
2. .atoms() can be filtered using Relational
3. .canonical puts the atoms in order so the symbol is on the left
   

I'd be happy to communicate with Joannah Nanjekye and Aaron Meurer about what documentation is needed, how I can help with existing efforts, etc. Because I'm new here, could you give me their contact information?

Thanks,

Jeremy

[Aaron Meurer]

On Sun, Nov 28, 2021 at 9:10 AM David Bailey <da...@dbailey.co.uk> wrote:
>
> On 27/11/2021 18:20, Jeremy Monat wrote:
>
> Hello, I'm Jeremy Monat. My primary interest in helping with SymPy development is making it easier for new users to use SymPy by improving the documentation. It is plenty powerful for the application I needed; learning how to use SymPy was the challenge for me.
>
> I agree that SymPy documentation really doesn't begin to justice to the quality of this software
>
> I suspect the problem is that most of us - developers and users - are keen on programming, not on writing documentation. I'm definitely guilty as charged.
>
> Just one of the problems I find, is that the documentation is incredibly uneven. Just as an example in 3.4.6 we learn that sqrt is not a function, which is a fairly elementary piece of information - it translates immediately into Pow, but then the example it gives IMHO, is anything but elementary! Indeed this is the first mention of the Wild() in the documentation.

Can you clarify what you mean by "3.4.6"? This is the sort of issue I
plan on addressing as part of my CZI documentation project.

Aaron Meurer

>
> Incidentally, if you try help(sqrt) the response starts with:
>
> "Help on function sqrt in module sympy.functions.elementary.miscellaneous"
>
> Best wishes,
>
> David
>
>
>

> --
> 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 view this discussion on the web visit https://groups.google.com/d/msgid/sympy/15799423-b96f-9f4e-a023-610df8d92f0d%40dbailey.co.uk.

[Aaron Meurer]

On Mon, Nov 29, 2021 at 10:49 AM Jeremy Monat <jem...@gmail.com> wrote:
>
> David and Oscar,
>
> Glad there is agreement on the need for improved documentation! And that there's a Google Summer of Documentation to go along with the one of Code.
>
> >There should be a guide somewhere that explains how to "solve equations".
> Definitely--web searches for things such as "SymPy solve inequalities" return the Inequality Solvers page, and there's nothing telling the visitor that they should probably be using a high-level solver such as solve() or solveset().
>
> There also needs to be a page on how to programmatically parse results of e.g. solve()--there's nothing on the site that I could find. For example, to answer my StackOveflow question about parsing results, smichr put together three concepts that I could not glean from the documentation, certainly not all in one place:
>
> Solved inequalities can be parsed using .atoms()
> .atoms() can be filtered using Relational
> .canonical puts the atoms in order so the symbol is on the left
>
> I'd be happy to communicate with Joannah Nanjekye and Aaron Meurer about what documentation is needed, how I can help with existing efforts, etc. Because I'm new here, could you give me their contact information?

There's no need to contact me separately. It's best to do these
discussions on the list. As Oscar mentioned, my work will mostly focus
on writing new documentation guides. If you have any suggestions on
the sorts of new documentation you'd like to see written, please let
me know. Of course, just because I will be writing documentation
doesn't mean you can't either. There is plenty of work to do. As a new
user, you may have a better sense of what is lacking in the
documentation than I do.

Another piece of work that we need help with is updating the existing
API documentation (docstrings) to conform to our style guide.
https://docs.sympy.org/latest/documentation-style-guide.html. Some of
the previous season of docs projects worked on this (see
https://github.com/sympy/sympy/wiki/GSoD-2019-Report-Lauren-Glattly:-SymPy-Documentation-Style-Guide
and https://github.com/sympy/sympy/wiki/GSoD-2020-Report-Soumi-Bardhan:-Consistency-across-docstrings---SymPy-Documentation),
but the work is incomplete.

As for Joannah, her project has just come to a conclusion. See
https://github.com/sympy/sympy/wiki/GSoD-2021-Report-Joannah-Nanjekye:-Reorganizing-the-SymPy-Documentation.
If you're interested in improving that work, see the "future work"
section on that page. That work mostly involves doing technical work
with Sphinx, so I would only recommend it if you have some familiarity
with Sphinx already.

Aaron Meurer

> --
> 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 view this discussion on the web visit https://groups.google.com/d/msgid/sympy/11e75753-91be-4d3e-b18a-d744784b0badn%40googlegroups.com.

[Jeremy Monat]

Aaron,

Thanks for the information. While my exploration of SymPy is largely limited to solvers, here are the documentation improvements I think would be helpful:

1. Improve the tutorial solvers page's order by first explaining how to solve equations and inequalities, particularly explaining the strengths of different solvers, when to use each, and giving examples of each (as suggested by Oscar)
   1. Add an example to solveset() on how to solve a set of equations or inequalities in a single variable (if it does--the documentation is ambiguous on whether this is even possible)
      
   2. Add an example to solve() on how to solve a set of equations or inequalities, in a single variable, then in multiple variables (if possible)
      
2. Add a guide on how to programmatically parse solved equations and inequalities (atoms, canonical, etc.)
3. Add a guide on how to programmatically parse expressions (args, other?)
4. At the top of each of the low-level solvers pages, put a note that you probably want to use a high-level solver instead--I reached the inequalities solvers page via a web search, and thought I had to use it instead of solve
   
5. Use simpler math for examples, or at least the first example for a function. For example, that page on solving inequalities has as its first example the following. I didn't know what the Poly function was (plus I couldn't find documentation for it), so I couldn't understand the solver.
   

solve_rational_inequalities([[ ((Poly(-x + 1), Poly(1, x)), '>='),

((Poly(-x + 1), Poly(1, x)), '<=')]])

{1}

The overall theme of 1-3 is "here's how to do things using easy-to-understand math" so maybe they'd be best in the tutorial rather than as reference pages.

Best,

Jeremy

[Oscar Benjamin]

On Tue, 30 Nov 2021 at 02:37, Jeremy Monat <jem...@gmail.com> wrote:
>
> Improve the tutorial solvers page's order by first explaining how to solve equations and inequalities, particularly explaining the strengths of different solvers, when to use each, and giving examples of each (as suggested by Oscar)

The number one question that comes up on StackOverflow over and over
again is basically "solve doesn't work for my transcendental equation"
to which the answer is "use nsolve" e.g.:
https://stackoverflow.com/questions/70157801/using-sympy-to-solve-equation/70158503?noredirect=1#comment124022352_70158503

The docs should make it clear that:

1. Closed form solutions to equations are only available in simple
cases or otherwise when you are lucky in some way. This is firstly a
mathematical limitation rather than a limitation of SymPy itself.
2. The nsolve function can find numeric solutions using either bisect
or something like the Newton method if the equation has no symbolic
parameters.
3. For polynomial equations without symbolic parameters the nroots
function can find all roots numerically.
4. Otherwise for arbitrary nonlinear equations with symbolic
parameters the problem as posed may be impossible.

> Add an example to solveset() on how to solve a set of equations or inequalities in a single variable (if it does--the documentation is ambiguous on whether this is even possible)
> Add an example to solve() on how to solve a set of equations or inequalities, in a single variable, then in multiple variables (if possible)

The solveset function is for univariate equations and inequalities.
For a system of equations you should use solve, linsolve or
nonlinsolve. There isn't a solver for systems of inequalities (yet):
https://github.com/sympy/sympy/pull/22389
https://github.com/sympy/sympy/pull/21687

> Add a guide on how to programmatically parse solved equations and inequalities (atoms, canonical, etc.)
> Add a guide on how to programmatically parse expressions (args, other?)

Yes, this is a good idea. There should be something that discusses the
different options here. For solve it is best to use dict=True if you
want to programmatically parse the results. For solveset it is
difficult to do anything with the output but there is a function
solvify that tries to make the output more like solve:
https://docs.sympy.org/latest/modules/solvers/solveset.html#sympy.solvers.solveset.solvify

> At the top of each of the low-level solvers pages, put a note that you probably want to use a high-level solver instead--I reached the inequalities solvers page via a web search, and thought I had to use it instead of solve
> Use simpler math for examples, or at least the first example for a function. For example, that page on solving inequalities has as its first example the following. I didn't know what the Poly function was (plus I couldn't find documentation for it), so I couldn't understand the solver.
>
> solve_rational_inequalities([[ ((Poly(-x + 1), Poly(1, x)), '>='),
> ((Poly(-x + 1), Poly(1, x)), '<=')]])
> {1}
>
> The overall theme of 1-3 is "here's how to do things using easy-to-understand math" so maybe they'd be best in the tutorial rather than as reference pages.

These all seem like good ideas.

Oscar

[David Bailey]

Thanks for responding,

On 29/11/2021 18:51, Aaron Meurer wrote:
> Can you clarify what you mean by "3.4.6"? This is the sort of issue I
> plan on addressing as part of my CZI documentation project.
>

Yes, sorry I was referring to the section

3.4.6 Sqrt is not a Function

in the PDF version of the 1.8 documentation (I guess the numbers
probably change from version to version - so I should have used 1.9.

David

[Jeremy Monat]

Oscar, thanks for the information about SymPy's capabilities and options.

Because many of the pages we're discussing are in the tutorial, I think it would be useful to lay out the current and proposed tutorial structure in a document. I created a page on the wiki Tutorial structure on docs.sympy.org. I started by pasting in the current tutorial structure (at the page and topic levels), and suggest we collaboratively develop a proposed structure.

If there is a better medium, or someone else (e.g. Aaron Meurer) already has something in the works, please let me know.

Jeremy

[Aaron Meurer]

On Tue, Nov 30, 2021 at 9:00 PM Jeremy Monat <jem...@gmail.com> wrote:
>
> Oscar, thanks for the information about SymPy's capabilities and options.
>
> Because many of the pages we're discussing are in the tutorial, I think it would be useful to lay out the current and proposed tutorial structure in a document. I created a page on the wiki Tutorial structure on docs.sympy.org. I started by pasting in the current tutorial structure (at the page and topic levels), and suggest we collaboratively develop a proposed structure.
>
> If there is a better medium, or someone else (e.g. Aaron Meurer) already has something in the works, please let me know.

Let's use the issue tracker for this. I'm still trying to figure out
in general how I plan to organize my documentation ideas.

There are a few things here. First, regarding the "tutorial", I think
we shouldn't be misled. Currently the pages that exist are in the
tutorial, but that doesn't mean all pages should go in the tutorial.
We have recently made a new organization for our documentation, which
can be viewed at https://docs.sympy.org/dev/index.html. This is based
on the Diataxis Framework https://diataxis.fr/. Sections should go in
the place that make the most sense. I expect a large part of what we
are talking about will not be tutorial, but either explanation of
how-to guides (the recorded talk on the Diataxis page gives the best
explanation of the differences between these). In particular, the
current "tutorial" is actually an "introductory tutorial". It should
not really be expanded much, unless the material really is relevant
for a very first time user of SymPy.

For solvers, there is a lot of stuff that needs better documentation.
A big problem also is that the current API of the solvers is itself a
bit of a mess, which makes it harder to document the "best practices".
I think what we should do for solvers is to break it down into smaller
pieces, which can be documented separately. Just as an initial idea, I
think we could use a top-level tutorial on intro to solving (which
already partly exists in the existing tutorial) that just goes over
the very basics and does things like stress the differences between
symbolic and numeric solutions. Then we can have several how-to guides
on different types of problems that might come up relating to solving,
like solving inequalities, finding roots of polynomials, and
manipulating the output of solve() and solveset(). There is also this
existing documentation on solveset that goes over the high-level
design, https://docs.sympy.org/latest/modules/solvers/solveset.html,
which mostly fits in the "explanation" Diataxis category.

Aaron Meurer

>
> Jeremy
> On Tuesday, November 30, 2021 at 11:35:15 AM UTC-5 da...@dbailey.co.uk wrote:
>>
>> Thanks for responding,
>>
>> On 29/11/2021 18:51, Aaron Meurer wrote:
>> > Can you clarify what you mean by "3.4.6"? This is the sort of issue I
>> > plan on addressing as part of my CZI documentation project.
>> >
>> Yes, sorry I was referring to the section
>>
>> 3.4.6 Sqrt is not a Function
>>
>> in the PDF version of the 1.8 documentation (I guess the numbers
>> probably change from version to version - so I should have used 1.9.
>>
>> David
>>

> --
> 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 view this discussion on the web visit https://groups.google.com/d/msgid/sympy/f9bed2ab-789d-445f-bb03-d696fc8ab43fn%40googlegroups.com.

[Jeremy Monat]

Aaron,

Thanks. Great--the new documentation homepage is much clearer with its division into 1) Tutorials, 2) How-to Guides, 3) Explanation, and 4) API Reference. With the old documentation, my mental model of the content categorization was just 1) tutorial and 2) technical documentation. That's why I thought anything along the lines of a guide belonged in the tutorial.

Diataxis Framework Categorization

Having those four categories also helpfully highlights the lack of guides. Currently, the top-level guides are only Getting Started, Contributing to SymPy, Assumptions, and Symbolic and fuzzy booleans. Having a roadmap for which guides we'd like to add would be helpful so whoever is available and interested could start building a guide, e.g.

• we've already identified solvers, parsing solved equations, and parsing expressions
  
• it would be helpful to have a guide explaining what kinds of things you can do with SymPy (Calculus, Linear Algebra, etc.), as the wiki tutorial nicely does

It's good that the breadcrumbs at the top of each new page indicate which category the page is in, e.g. SymPy 1.10.dev documentation » Explanation » Gotchas and Pitfalls for https://docs.sympy.org/dev/explanation/gotchas.html#equals-signs. Displaying the category even more prominently might be helpful.

Tutorial "What's next"

Typically, when I want to use a new package, I do the tutorial, then (unless otherwise directed) figure I'm on my own, so I search for my topic of interest. (Perhaps the documentation site admins can provide quantitative data about navigation patterns of new users.) The new tutorial simply ends without suggesting where learners might want to go next. So it'd be helpful to add a "What's next" page at the end of the tutorial pointing learners to the guides--that seems like the most likely section they'd want, to learn more about any particular topic they came to SymPy to use.

My next step

I'll identify a first issue and create it in the tracker.

Jeremy

[Aaron Meurer]

On Wed, Dec 1, 2021 at 9:12 PM Jeremy Monat <jem...@gmail.com> wrote:
>
> Aaron,
>
> Thanks. Great--the new documentation homepage is much clearer with its division into 1) Tutorials, 2) How-to Guides, 3) Explanation, and 4) API Reference. With the old documentation, my mental model of the content categorization was just 1) tutorial and 2) technical documentation. That's why I thought anything along the lines of a guide belonged in the tutorial.
>
> Diataxis Framework Categorization
> Having those four categories also helpfully highlights the lack of guides. Currently, the top-level guides are only Getting Started, Contributing to SymPy, Assumptions, and Symbolic and fuzzy booleans. Having a roadmap for which guides we'd like to add would be helpful so whoever is available and interested could start building a guide, e.g.
>
> we've already identified solvers, parsing solved equations, and parsing expressions
> it would be helpful to have a guide explaining what kinds of things you can do with SymPy (Calculus, Linear Algebra, etc.), as the wiki tutorial nicely does

That's why guides are the main focus of my project.

As for a roadmap, my plan is to use a combination of issues, questions
here on the mailing list and in other places like StackOverflow, and a
user survey which is currently running (at
https://forms.gle/EjkFEdnLXaYxjvfn6 for anyone who hasn't yet taken
it) to get a better idea of our documentation needs. I haven't yet
worked out how I want to keep track of this stuff. Most likely I will
have a tracking issue, but I may also end up using something more
dynamic to take notes for myself on what I see that needs documenting.

>
> It's good that the breadcrumbs at the top of each new page indicate which category the page is in, e.g. SymPy 1.10.dev documentation » Explanation » Gotchas and Pitfalls for https://docs.sympy.org/dev/explanation/gotchas.html#equals-signs. Displaying the category even more prominently might be helpful.
>
> Tutorial "What's next"
> Typically, when I want to use a new package, I do the tutorial, then (unless otherwise directed) figure I'm on my own, so I search for my topic of interest. (Perhaps the documentation site admins can provide quantitative data about navigation patterns of new users.) The new tutorial simply ends without suggesting where learners might want to go next. So it'd be helpful to add a "What's next" page at the end of the tutorial pointing learners to the guides--that seems like the most likely section they'd want, to learn more about any particular topic they came to SymPy to use.

That's a good idea.

Aaron Meurer

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/e6a74d60-fb49-404f-8e88-c12ed3ee72d8n%40googlegroups.com.