Documentation: polynomials and division #11425

jksuom · 2016-07-23T12:51:02Z

Documentation for some basic concepts in polys.

moorepants · 2016-07-24T16:09:09Z

doc/src/modules/polys/basics.rst

+multiplications before additions and subtractions.
+The products of generators thus obtained are called
+*monomials*. They are usually written in the form
+`x_1^{\nu_1}x_2^{\nu_2}\cdots x_n^{\nu_n}` where the exponents `\nu_i`


Don't you need to use :math:4 +5 `` for this to render?

That does not seem necessary.

Ok, I thought you had to use the math directive.

Backquotes automatically do inline math. You only need a .. math:: for display math.

moorepants · 2016-07-24T16:14:37Z

This is very nice and helpful! Please run sphinx and see if the math renders properly.

jksuom · 2016-07-24T16:48:11Z

I have done that. I could put up a html version in Google drive if desired.

moorepants · 2016-07-24T16:59:48Z

No need. Just wanted to make sure the math renders. This is fine to merge. It's a great improvement.

moorepants · 2016-07-24T17:08:26Z

doc/src/modules/polys/basics.rst

+properly as an algebraic number.
+
+Divisibility
+------------


It'd be nice to see some code examples in the following sections to show the relevancy to what a user would do in SymPy with polynomials.

That is explained, at least to some extent, in the sequel of the same file basics.rst. See http://docs.sympy.org/latest/modules/polys/basics.html, Basic functionality .

I would not expect an example necessarily, since this is a section named "Basic Concepts", otherwise in the same file we do have a section named "Basic functionality" (mostly contains code examples) which does contain examples of divisibility i.e div function.

@jksuom I didn't saw your comment (commented there on the outdated version). I can't believe I almost commented the same thing :)

Sure that's all fine. I'm just giving you my opinion as a user that doesn't care too much about polynomial theory. The polynomial module's dosctrings and documentation seem to lack a pointed introduction for people that just want to use it.

The polynomial module's dosctrings and documentation seem to lack a pointed introduction for people that just want to use it.

I think so too. This text aims to give background information for the developers, those who would write the docstrings or implement polynomial methods in symengine.

jksuom · 2016-07-28T07:28:28Z

Thanks for the review, @smichr !

asmeurer · 2016-07-29T15:37:28Z

doc/src/modules/polys/basics.rst

+Given a family `(x_i)` of symbols, or other suitable objects,
+expressions derived from them by repeated addition, subtraction
+and multiplication are called *polynomial expressions in the
+generators* `x_i`.


And some base field or ring of coefficients.

I see, so they are included in the x_i. In that case, maybe mention "or other suitable objects, including numbers" or something like that. I think I understand what you are defining here, but it's easy to confuse this with what people usually think of as a "polynomial".

I tried to make a distinction between 'polynomial expressions' and 'polynomials'. The belong to different classes in SymPy. Adding 'including numbers' here seems a good idea. But I did not want to introduce base rings at this point.
(Writing expository texts is always balancing between brevity and completeness.)

asmeurer · 2016-07-29T16:11:56Z

The definition in the beginning seems a bit confusing, especially since you jump directly to SymPy expressions, but the definition doesn't exactly match how expressions work in SymPy.

I read through the rest of the document and it looks fine, excepting my comments.

asmeurer · 2016-07-29T16:13:42Z

Maybe the division and gcd examples below this could be incorporated into the text.

jksuom · 2016-07-29T16:38:09Z

The definition in the beginning seems a bit confusing, especially since you jump directly to SymPy expressions, but the definition doesn't exactly match how expressions work in SymPy.

Can you elaborate on this?

jksuom · 2016-07-29T16:40:09Z

Maybe the division and gcd examples below this could be incorporated into the text.

Do you mean that the examples in the next section on 'Basic Functionality' should be moved here?

asmeurer · 2016-07-29T16:40:30Z

Do you mean that the examples in the next section on 'Basic Functionality' should be moved here?

Yes

jksuom · 2016-07-29T16:47:23Z

What should be done with the rest of 'Basic Functionality'?

In particular the subsections on Division and GCD.

asmeurer · 2016-07-29T20:29:30Z

I guess just leave it there at the end. There is no in-depth discussion of factoring and groebner bases (although there could be).

asmeurer · 2016-07-29T20:30:17Z

An alternative might be to split out the theory discussion and the examples into separate documents.

asmeurer · 2016-07-29T20:42:06Z

Advantages of splitting theory and examples/usage:

Separates the theory from distracting (but important) discussions on gotchas, like algebraically dependent generators and behavior of div when the coefficient domain is not a field (currently in the "basic functionality/division" section)
Removes potential confusion between presentation of the theory and the implementation in SymPy

Disadvantages:

The theory may be easier to follow and more motivated with examples.

What do you think? I think it would be great to have more theoretical discussions like this in the SymPy docs (contingent on people writing it, of course).

jksuom · 2016-08-02T12:49:27Z

I think that examples are well suited for this type of introductory texts. Although there are 'theoretical discussions' I have tried to make them readable for everybody explaining only such concepts that seem essential for an understanding of the subject and its implementation.

I have expanded the polynomial part of the text and added examples to the divisibility section.

asmeurer · 2016-08-19T16:17:33Z

Do you intend to add more here? There are still a couple of minor typo comments to address, but otherwise I am +1 to merge if you are done.

jksuom · 2016-08-19T16:32:43Z

This is as far as I had intended to go. I only wanted to clarify some concepts to help those who want to write docstrings or implement polys methods in symengine.

smichr · 2016-09-23T22:29:00Z

doc/src/modules/polys/basics.rst

+
+        `a = qb + r`
+
+    and such that either `r = 0` or `w(r) < w(b)`.


I would strike 'and' here.

I think you are right. In a mathematical text these conditions are typically added on the same line after the equation with a quad or two to separate them. Here, I felt that some words were needed.

you could add 'are' after 'and' if you want to keep the 'and', but I don't see a problem with just writing

"such that either r = 0 or w(r) < w(b). "

But since you don't refer to 'q' you might just say

"where either r = 0 or w(r) < w(b). "

I feel quite comfortable with your first suggestion.

smichr

Just a few typos raised by @asmeurer and @smichr.

jksuom · 2016-09-24T07:08:02Z

I have been waiting for #11558 to be finished. Then some examples have to be modified. I was planning to fix the minor flaws in the same commit.

smichr · 2017-08-15T23:27:20Z

I have been waiting for #11558 to be finished

ping @jksuom -- the blocking PR has been merged so I think this is ready to finish off when you get the chance.

jksuom · 2017-08-16T05:30:46Z

Yes, I'll try to find some time for this.

jksuom · 2017-08-16T07:22:08Z

The typos should also be fixed. Can you point out those that I didn't find?

smichr · 2017-08-17T15:22:47Z

I didn't re-read everything but looked at where comments had been made to see if anything still needed to be done and made comments as necessary.

Symbolic numbers will no more lead to the EX domain after sympy#11558.

smichr · 2017-08-17T23:54:08Z

The comments that I added aren't showing up here. See the commit tab and search for today's date to see the comments I left.

jksuom · 2017-10-26T18:39:49Z

Thanks! This can now go in the next release.

jksuom added 2 commits July 2, 2016 22:46

Basic concepts, polynomials

d7f11ee

Basic concepts, divisibility

1d9e641

jksuom force-pushed the division branch from 36773b7 to 1d9e641 Compare July 23, 2016 14:54

jksuom mentioned this pull request Jul 24, 2016

The Poly class needs a useful doc string #11427

Closed

Minor edit

fc842e4

moorepants reviewed Jul 24, 2016
View reviewed changes

asmeurer reviewed Jul 29, 2016
View reviewed changes

Text and examples added

655a802

smichr reviewed Sep 23, 2016

View reviewed changes

smichr requested changes Sep 23, 2016

View reviewed changes

Fix the creation of a polynomial involving pi.

01bb6c8

Symbolic numbers will no more lead to the EX domain after sympy#11558.

Fix two typos

da19b53

smichr approved these changes Oct 26, 2017

View reviewed changes

smichr merged commit 97571bb into sympy:master Oct 26, 2017

jksuom deleted the division branch October 26, 2017 18:39

Documentation: polynomials and division #11425

Documentation: polynomials and division #11425

Conversation

jksuom commented Jul 23, 2016

moorepants Jul 24, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

moorepants commented Jul 24, 2016

jksuom commented Jul 24, 2016

moorepants commented Jul 24, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jksuom commented Jul 28, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

asmeurer commented Jul 29, 2016

asmeurer commented Jul 29, 2016

jksuom commented Jul 29, 2016

jksuom commented Jul 29, 2016

asmeurer commented Jul 29, 2016

jksuom commented Jul 29, 2016 • edited

asmeurer commented Jul 29, 2016

asmeurer commented Jul 29, 2016

asmeurer commented Jul 29, 2016

jksuom commented Aug 2, 2016

asmeurer commented Aug 19, 2016

jksuom commented Aug 19, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smichr left a comment

Choose a reason for hiding this comment

jksuom commented Sep 24, 2016

smichr commented Aug 15, 2017

jksuom commented Aug 16, 2017 • edited

jksuom commented Aug 16, 2017

smichr commented Aug 17, 2017

smichr commented Aug 17, 2017

jksuom commented Oct 26, 2017

moorepants Jul 24, 2016 •

edited

jksuom commented Jul 29, 2016 •

edited

jksuom commented Aug 16, 2017 •

edited