Poly(..., domain='EX') -> where is it documented?

[Bastian Weber]

I often work with polynomials (say w.r.t. x) like:

p_expr = a0 + a1*x + a2*x**2

And I use the Poly-Class for that purpose:

from sympy import Poly
# ...
my_ploy = Poly(p_expr, x, domain='EX').


Now, a colleague wants to understand my code in detail. Together we
could not find a place in the docs where the possible arguments for
domain are described. I would have suggested it at [1] but apparently it
is not there.

While looking for that piece of information, we noticed that the docs
for that module is somewhat hard to handle.

* The file is quite long (more than 3000 lines of code)

* The string "Poly" occurs to often to make reasonable use of the search
function of the browser

* Something like a table of contents is missing (for an overview which
functions and classes are documented in this file)

* The docstring for the Poly class gives only very limited explanation:
"Generic class for representing polynomial expressions."

To sum up: it took us quite a while to find the docs of that class in
the module reference for polytools. And even there the information about
domain='EX' was not there.


[1]
http://docs.sympy.org/latest/modules/polys/reference.html#sympy.polys.polytools.Poly


Questions:

* Did we miss some other place in the docs where this can be found?
* Is it possible to (locally) build the docs with a table of contents
for each html-file in the module reference (or increase the TOC depth in
the sidebar)?


Best regards,
Bastian.

[Aaron Meurer]

The domain argument is likely undocumented. The polys are unfortunately not so well documented, beyond the docstrings on the methods of Poly.  You could also look at Mateusz Paprocki's master's thesis. 

Regarding rebuilding the docs, as far as I know Sphinx doesn't generate TOCs for methods. Maybe I'm wrong, though. The docs are all in the doc directory of the SymPy git source. They do have a few dependencies to build, though. 

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 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/54BFA8C8.3050406%40gmx-topmail.de.
For more options, visit https://groups.google.com/d/optout.

[Bastian Weber]

On 01/21/2015 08:26 PM, Aaron Meurer wrote:
> The domain argument is likely undocumented.

Thats a pity.

> The polys are unfortunately
> not so well documented, beyond the docstrings on the methods of Poly.

What I am looking for is the documentation of the "constructor" of Poly.

Suppose, I would like to write a doctest for

Poly(..., domain='EX').

Where would it live?

> You could also look at Mateusz Paprocki's master's thesis.
>
> Regarding rebuilding the docs, as far as I know Sphinx doesn't generate
> TOCs for methods.

It would already help, if the _classes_ showed up in the TOC (e.g. the
class Poly). Maybe I have a look on it.


Bastian.

[Mateusz Paprocki]

Hi,

On 21 January 2015 at 22:06, Bastian Weber <bastia...@gmx-topmail.de> wrote:
> On 01/21/2015 08:26 PM, Aaron Meurer wrote:
>> The domain argument is likely undocumented.
> Thats a pity.

Yeah, documentation of polys module is below standards.

>
>> The polys are unfortunately
>> not so well documented, beyond the docstrings on the methods of Poly.
>
> What I am looking for is the documentation of the "constructor" of Poly.
>
> Suppose, I would like to write a doctest for
>
> Poly(..., domain='EX').
>
> Where would it live?

You could add it to Poly class, so that `Poly?` in IPython gave
something useful.

In general, you should avoid using EX, as this is the "catch all"
option, that's there to not fail miserably, but doesn't give you any
guarantees. Given the original polynomial, i.e. p_expr = a0 + a1*x +
a2*x**2, I would use simply Poly(p_expr, x) or Poly(p_expr, x,
field=True) if you want to work over a field. But all depends on the
problem you try to solve. Any specifics would be helpful to advice
anything.

The list of possible options to Poly is available in
sympy/polys/polyoptions.py:96 (obviously barely or not documented).

Mateusz

>
>> You could also look at Mateusz Paprocki's master's thesis.
>>
>> Regarding rebuilding the docs, as far as I know Sphinx doesn't generate
>> TOCs for methods.
>
> It would already help, if the _classes_ showed up in the TOC (e.g. the
> class Poly). Maybe I have a look on it.
>
>
> Bastian.
>

> --
> 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/54C014C5.8070403%40gmx-topmail.de.