SEPs for SymPy (SymPy Enhancement Proposals)

[Oscar Benjamin]

Hi all,

I've been thinking for some time that there should be more
coordination amongst sympy contributors and more involvement with the
broader sympy community in the general direction that sympy takes. I
want to propose the idea of SymPy Enhancement Proposals (SEPs)
analogous to numpy's NEPs and core Python's PEPs.

The Python PEP process is explained in PEP 1 (the details would be
different for sympy):
https://www.python.org/dev/peps/pep-0001/

Background
-------------

At the moment most discussions around the general direction of sympy
take place on github and are spread across many different issues and
pull requests. The only way to really keep track or to engage with the
discussion is by following all traffic on the sympy github repos.
That's what I personally do (I get an email every time anyone posts
anything on any issue or pull request on any of sympy's repos) but
that's only really manageable for someone who is very actively engaged
with contributing to or following sympy development. That means that
the broader sympy community is not really included in most of the
discussions around the direction of sympy development.

Also there is a lack of higher-level coordination amongst
contributors. To me it seems that most work in sympy is piecemeal with
different contributors working on whichever problem they personally
care about without necessarily understanding the broader issues across
the codebase that are affected by the work that they do. SymPy
currently operates on a "consensus" model that once all people
involved in a discussion are agreed then a change can be made but it
is often not possible for many people to follow a particular
discussion. In practice this means that most changes are agreed by a
small number of people even if they have a wide impact.

One particularly limiting aspect of this is that there isn't really
any forum in which broader discussions about the higher-level
direction of sympy development take place. I think that right now
there are a number of major obstacles to further progress in sympy
that need to be dealt with by broad community discussion. This should
involve both downstream users and contributors (new, old, active and
inactive). Examples would be the future of the new and old
assumptions, new implementations of matrices, extensibility of the
core of sympy, fixing major problems like the 2-arg Rational-Add Mul,
fixing the evaluation model to get rid of evaluate=False, and many
more. All of these are changes that would involve a substantial amount
of work across the main sympy codebase and that would involve some
compatibility breaks. They are all needed (IMO) for the future
development of sympy though.

I think that maybe numpy was in a more similar state some years ago
but has now upped its organisational game and has many NEPs addressing
long standing problems and even weekly online meetings amongst
particularly active contributors. By contrast sympy has no
organisational arrangements to facilitate coordination of development
as far as I can tell.

A Python PEP or numpy NEP is a document that proposes a change to
Python/numpy but also explains bigger picture issues and crucially is
presented to a wide audience for discussion. Once approved the PEP
serves as a record of what was agreed at the time with a rationale for
the changes as well as a prescriptive high-level explanation of what
the changes will be. SymPy should have SEPs for the same reason that
Python has PEPs:

1. A PEP makes it possible for many more contributors/users to take
part in a discussion
2. The discussions around a PEP can improve the resulting proposal by
taking in as much feedback as possible.
3. Having the discussion (and documenting it) engages the broader
community so that the reasons for changes in sympy are understood.
4. After a PEP is agreed then it is possible to refer to it in future
as an explanation/justification for doing part of the work to
implement the PEP.
5. When a PEP has been fully implemented it serves as a historical
document motivating the reasons for the changes made.

A PEP serves a different purpose from documentation which explains the
code as it is at a given time. By contrast a PEP focuses on the
discussion around the changes to be made and the reasons for those
changes (at that time).



Idea
----

The idea I want to propose is that sympy should have a process for
proposing, discussing, approving and amending documents known as SymPy
Enhancement Proposals (SEPs) analogous to Python's PEPs. There should
be a repo `sympy/seps_repo` to host these documents. The main
discussion should take place here on the mailing list. Some SEPs can
be informational and others can be proposals for changes.

In core Python a PEP is generally expected to have a full working
implementation at the time of acceptance. I expect that for sympy it
will make more sense for a SEP to represent something aspirational
that is not achievable by a single contributor in a short period of
time. Rather the SEP should define the general direction in enough
detail that many different contributors can implement parts of the
proposal. It would probably make sense for a SEP to have a section
describing the extent to which it has been implemented. If we had a
few SEPs that were accepted and that were defined in sufficient detail
then it would be a lot easier for new contributors to implement those
changes knowing that they were already agreed and specced. We could
e.g. encourage GSOC projects that implement SEPs.

The process could be something like:

1. Post a SEP draft on the mailing list and open a PR against the SEPs repo
2. Discuss on the mailing list and the repo
3. Amend the draft and repost etc until discussion converges
4. Some sort of decision is made...
5. The SEP is accepted but needs to be implemented
6. Implementation happens over some time probably by multiple contributors.
7. The SEP can be discussed or amended subject to discussion on the
mailing list (if issues arise in implementation)
8. Once the SEP is fully implemented it is finalised and not edited further.


What do people think of this idea?

--
Oscar

[Jonathan Gutow]

+1

Although I am probably one of those "put in episodic work only on
projects that interest me" people. Other major open-source projects
(e.g. SageMath and Plone) I have done pieces for have similar structures
and I thought they were useful.

Jonathan

On 8/1/20 6:23 PM, Oscar Benjamin wrote:
> CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender and know the content is safe.

> --
> 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/CAHVvXxQ3bbJWOmHu7QYzQfnL_yO7WrE%2BzRoqsVZFkkyPA%2B%3DW_A%40mail.gmail.com.

--
Dr. Jonathan Gutow
Chemistry Department
UW Oshkosh
web: https://uwosh.edu/facstaff/gutow
e-mail: gu...@uwosh.edu
Ph: 920-424-1326

[Jason Moore]

I agree with this. SEPs would be a net positive. They seem to work well with other projects.

Question: How do we know what changes require SEPs and what don't? Is the idea that if informal proposals are brought up in our current communication mechanisms that someone would say "this should probably be a SEP" and then it's the proposer's burden to create the SEP to move forward? What prevents every suggested change being pushed towards a SEP?

Jason

moorepants.info
+01 530-601-9791

[Oscar Benjamin]

On Sun, 2 Aug 2020 at 01:42, Jonathan Gutow <gu...@uwosh.edu> wrote:
>
> Although I am probably one of those "put in episodic work only on
> projects that interest me" people. Other major open-source projects
> (e.g. SageMath and Plone) I have done pieces for have similar structures
> and I thought they were useful.

I'm not familiar with the processes for either of those projects.
Could you perhaps explain how they work?


Oscar

[Oscar Benjamin]

On Sun, 2 Aug 2020 at 04:58, Jason Moore <moore...@gmail.com> wrote:
>
> I agree with this. SEPs would be a net positive. They seem to work well with other projects.
>
> Question: How do we know what changes require SEPs and what don't?

I would say that for now at least it shouldn't be a requirement to
produce a SEP except where there are significant backwards
compatibility issues for users or downstream projects.

An example of a backwards compatibility change would be the import
changes introduced in sympy 1.6 should that probably have been
discussed in a SEP:
https://github.com/sympy/sympy/issues/18245
Those changes are still incomplete so a SEP for removal of the
deprecated imports would still be reasonable. A SEP would be a better
place than a github issue/PR to document the purpose of the changes
and what affected users should do in response to them.

> Is the idea that if informal proposals are brought up in our current communication mechanisms that someone would say "this should probably be a SEP" and then it's the proposer's burden to create the SEP to move forward?

I would look at this the other way round. As a contributor you can
write a SEP to get your idea fleshed out and accepted/rejected before
implementing the idea. Then you would know that the idea is accepted
and you and others would be able to work on the implementation with a
good shared understanding of the objectives and agreed specification.
I would be much happier when reviewing a PR that partially implements
a SEP than I am about merging a half-complete idea that isn't fully
specified anywhere.

I don't think anyone should be required to write a SEP but as a
contributor wanting to make larger changes you might want to write one
if e.g.

- You are not sure that your idea is something that will be accepted.
- There is a deadlock between contributors over proposed changes on github
- You want to get an agreed specification that can be implemented
afterwards partially or entirely by other contributors.
- The work is a longer term project that is too much for a single pull
request and you want to make the overall goal clear to others who
would review/merge the pull requests.
- You think that there is a need for all contributors to standardise
on something that isn't trivial to explain.

An example of a PR that might benefit from a SEP is:
https://github.com/sympy/sympy/pull/19479
That adds an Equation class which can be used intuitively in
arithmetic and function calls and so on. That's something that a lot
of users want and there is a very long-standing issue for it on
github. It's also something that can be easily understood by many
contributors and the wider community. Finally the discussion there has
a potential deadlock over the user of simplify. A SEP discussion can
resolve that deadlock as well as ensure that the design choices have
wide agreement. In this example there has already been a lot of
discussion on many issues and pull requests and on this mailing list.
The SEP would help to get broad agreement on the design.

Another example of a PR that could benefit from a SEP is this:
https://github.com/sympy/sympy/pull/19750
The proposal is to introduce a new function framework. I think that is
needed but there are many different ways to do it and there hasn't
really been any wider discussion around how it should work. The actual
changes would take a long time to implement since the implication is
that all function classes in sympy (exp, sin, ...) would be migrated
to the new framework. That's too big for one PR though so instead the
new framework will be introduced and then the classes incrementally
migrated over. I personally would object to merging that PR as a
half-implementation of an idea until it is clear to me what the
broader plan is and that it can actually replace the existing function
framework. In this case there has been hardly any discussion and now a
huge amount of work seems to have gone into implementing a design that
hasn't really been agreed by anyone. It would be better to have a SEP
discussion first before implementing something like this.

> What prevents every suggested change being pushed towards a SEP?

I do understand your concern here. It seems that the way things have
gone with core Python even trivial things end up having PEPs now:
https://www.python.org/dev/peps/pep-0485/
Part of the reason that happens I think is because in core Python many
changes/ideas are discussed excessively. The PEP process becomes a way
of structuring that conversation and also often serves the purpose of
resolving otherwise unending debates.

Right now there is fairly minimal discussion around any changes in
sympy (typically 2-3 people are involved in discussing even major
changes). Part of why I want to have SEPs for sympy is to give a space
to have wider discussion that otherwise just doesn't happen anywhere.
If the burden of writing/discussing SEPs becomes too great then that
we can rethink the idea.

I think that the biggest question is this: by what mechanism can a SEP
be considered "rejected"? Rejecting ideas is one of the most important
roles of these processes. SymPy's current collaboration model is based
on "consensus" which doesn't allow for an idea to be rejected if it
still has a single proponent (e.g. the author).

--
Oscar

[David Bailey]

Oscar,

I am amazed that you and other SymPy developers find time to develop the software after they have finished evaluating and responding to all the offers from students. Are you sure the time you all spend on this doesn't cost more than the help you receive?

I can certainly see that you need to make some changes, but I can't believe that more bureaucracy can help. When I was working with a team developing a compiler, we did take on a number of students - including one excellent one - but the only way to select them was to set them a programming test that could be done while they were with us, and evaluate that. When they joined us, we decided with them what they would work on.

The biggest thing SymPy needs is comprehensive documentation - preferably up to the standard of Mathematica.

David

[Jonathan Gutow]

I think the Plone PLIP implementation is the best of the two. Here's my brief understanding (details at: https://docs.plone.org/develop/coredev/docs/plips.html):

• PLIPs are implemented as issues in the github repository. This facilitates conversion to a simple bugfix or small enhancement if review determines that is more appropriate.
• PLIPs are primarily for changes that will have significant impact on the codebase, API or end user experience.
• The project is large enough that they have a number of committees that oversee things. One of them oversees PLIP review on the community discussion groups and makes the final decision of whether to approve or deny the PLIP.
• The issue is used to produce a final version of the PLIP with a detailed description of the desired outcome, how it will be implemented (not line-by-line changes) and the risks/potential problems associated with the implementation. The expectation is that all PLIPs will have some negatives and will only be approved if the community decides that the positives outweigh the negatives.

Based on my brief experience with SymPy, I think an oversight committee for SIPs might be more than the current SymPy community can manage. Otherwise, I think the model used by Plone makes it easy for people to propose significant changes and get a clear community review.

I still like the SIPs idea a lot.

Jonathan

On 8/2/20 4:11 AM, Oscar Benjamin wrote:

CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender and know the content is safe.


On Sun, 2 Aug 2020 at 01:42, Jonathan Gutow <gu...@uwosh.edu> wrote:

I'm not familiar with the processes for either of those projects.
Could you perhaps explain how they work?


Oscar

--
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/CAHVvXxSsMZpZ4K3KXbMpx1nK3BE0YuaeCWZCTe%3D9POJ94DbYCw%40mail.gmail.com.

[Oscar Benjamin]

On Sun, 2 Aug 2020 at 14:48, David Bailey <da...@dbailey.co.uk> wrote:
>
> I am amazed that you and other SymPy developers find time to develop the software after they have finished evaluating and responding to all the offers from students. Are you sure the time you all spend on this doesn't cost more than the help you receive?

In the early phase any new contributor will take more time to advise
than it would take for a more experienced contributor to do the work
directly. However as contributors become more experienced that turns
around. This applies to all contributors as well as GSOC students. The
difference with GSOC is that a student is then paid to work full time
on a project for 3 months and the outcome from that is definitely more
than mentors could achieve given the same amount of time working on
the problem directly. By the end of that a GSOC student will have
substantial experience with both the codebase and the workflow and
they can often continue to be a regular contributor afterwards.

> I can certainly see that you need to make some changes, but I can't believe that more bureaucracy can help.

I see SEPs as documents outlining high-level design and implementation
planning. I don't consider that bureaucracy: those are two things that
sympy sorely lacks at the moment. I think there are a number of active
contributors who have clear ideas about what they think should be done
to improve sympy in future but there is no forum in which to have that
bigger picture discussion so that anyone else understands those ideas.
If the agreed plans were clear then I think that there are capable and
willing contributors who would invest time in implementing them.

> The biggest thing SymPy needs is comprehensive documentation - preferably up to the standard of Mathematica.

Yes, better documentation is needed. There is work going on to improve
that. It's hard in many cases though to write the documentation
without having a clear idea what the future of sympy is supposed to
be. It's not even always clear who the documentation is intended for
i.e. which parts of sympy are "public" or "private".


Oscar

[Oscar Benjamin]

On Sun, 2 Aug 2020 at 14:54, Jonathan Gutow <gu...@uwosh.edu> wrote:
>
> I think the Plone PLIP implementation is the best of the two. Here's my brief understanding (details at: https://docs.plone.org/develop/coredev/docs/plips.html):
>
> PLIPs are implemented as issues in the github repository. This facilitates conversion to a simple bugfix or small enhancement if review determines that is more appropriate.
> PLIPs are primarily for changes that will have significant impact on the codebase, API or end user experience.
> The project is large enough that they have a number of committees that oversee things. One of them oversees PLIP review on the community discussion groups and makes the final decision of whether to approve or deny the PLIP.
> The issue is used to produce a final version of the PLIP with a detailed description of the desired outcome, how it will be implemented (not line-by-line changes) and the risks/potential problems associated with the implementation. The expectation is that all PLIPs will have some negatives and will only be approved if the community decides that the positives outweigh the negatives.
>
> Based on my brief experience with SymPy, I think an oversight committee for SIPs might be more than the current SymPy community can manage. Otherwise, I think the model used by Plone makes it easy for people to propose significant changes and get a clear community review.

I think that you are probably right. I was thinking more just that
SEPs (SIPs?) could be discussed here on the mailing list rather than
on github to involve a wider audience. That's a feature of PEPs/NEPs
that isn't described in the PLIPs guidance, presumably because the
process involves a regular oversight committee.

It's interesting to see that in the Plone model there is a very clear
separation between specification and implementation. The guidance
makes it clear that implementation is not expected to begin until some
agreement is reached on the changes to be made. That is I think what
sympy needs as well.


Oscar

[Gagandeep Singh (B17CS021)]

Hi, 

I read the original post and I think the idea of introducing SEPs seems to be really useful. Since, I am quite involved with `stats` module and was thinking to add some new features to it to make it more powerful and useful to the people working in the area of statistics. I wanted to know whether it will be possible to propose new features via SEP or more precisely, can SEPs initially have requirements and expectations, and then later on after community discussion, SEPs can be changed and more details can be added.

I also believe that there many similar issues in the issue tracker and they can be grouped together into a single SEP. In fact, once we do that, instead of having GSoC ideas list, students should be encouraged to make proposals for implementing the SEPs they are interested in. 

With Regards,
Gagandeep Singh
Github - https://github.com/czgdp1807
LinkedIn - https://www.linkedin.com/in/czgdp1807

--
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/CAHVvXxTGGT6L_vfFVtbH2T%3D-PsxdOyvJUe3cXojDM3ba%2BDcEtA%40mail.gmail.com.

[Jonathan Gutow]

On 8/2/20 12:16 PM, Oscar Benjamin wrote:
> SEPs (SIPs?)
How about "SyEPs" or "SymEPs" to make sure they are clearly distinct
from a possible SciPy equivalent? I am sort of partial to "SymEPs"
because I like the sound of "sym,E,P's" if it is said that way.

[Oscar Benjamin]

On Sun, 2 Aug 2020 at 18:49, Gagandeep Singh (B17CS021)
<sing...@iitj.ac.in> wrote:
>
> I read the original post and I think the idea of introducing SEPs seems to be really useful. Since, I am quite involved with `stats` module and was thinking to add some new features to it to make it more powerful and useful to the people working in the area of statistics. I wanted to know whether it will be possible to propose new features via SEP or more precisely, can SEPs initially have requirements and expectations, and then later on after community discussion, SEPs can be changed and more details can be added.

I think that a SEP would be most useful where it represents a
non-incremental change as incremental changes are well handled by the
existing issue/PR workflow. So if the proposal is to add a feature
without substantially altering the existing structure then that's not
the kind of situation I'm thinking of although we could use SEPs for
that if that's what people want to do.

On the other hand I think a SEP would be useful if the proposal is
something like "The stats module needs to be reworked with a new
structure/API because the existing structure can not be extended in a
backward compatible way to handle random variables with finite but
symbolically sized sample spaces" then that's the kind of situation I
was thinking of. Making deep incompatible changes needs careful
consideration and needs to have a motivation/explanation that we can
point to for downstream libraries and users.

To me it would also seem useful if the stats module had a document
(perhaps a SEP) that clarified what the intended scope of the module
is in its entirety. For example: what features would the module have
at the point that it was considered complete and what needs to be done
to get there? Personally I would find a document like that useful
because right now the intended scope of the stats module is unclear to
me.


Oscar

[Aaron Meurer]

Hi. Thanks for posting this. Here are my high level thoughts.

- I'm not opposed to the idea, and it's always good to write design
decisions down, but we should make sure it doesn't become
bureaucratic, as David mentioned.

- We have already done some degree of high-level planning in the past.
It just hasn't been organized. For example, you can see there are some
documents on the wiki that go over design ideas for various things.
Some of them are implemented and some not. And of course, every GSoC
project starts with a GSoC proposal that outlines what will be done in
the project.

- I would look at how other similar projects do this, especially
projects in the scientific ecosystem. NumPy, matplotlib, and
scikit-learn are some examples I know of. I would expect matplotlib
and scikit-learn to be more similar to SymPy, since they are also
large projects with distinct parts, where most contributors are only
familiar with some specific submodules, but there's also a "core" that
affects the entire library. We should also talk with members of those
communities to see how they feel about the processes and what works
and what doesn't. I think Python PEPs aren't a great model to mimic
directly. The Python community of developers is much larger, the
community of users is *much* larger, and they also care much more
about not breaking compatibility and being conservative about adding
new features than we do.

- My biggest concern is this: it is often impossible to really know
what will work unless we try to implement it. I think the assumptions
are a great example of this. The idea of what the "new assumptions"
should look like has changed several times over the years, because
every time it has become clear that the current idea isn't tenable.
This has led to a rather unfortunate state of things where we have two
concurrent systems. But I don't really see how we could have come up
with a "new assumptions" idea that would actually work without first
trying out what we did and seeing why it didn't work.

- I have a few gripes with the Python PEP process which I think we
should try to avoid.
- First, SEPs should not be treated as end-user documentation. There
are too many instances where Python links to a PEP instead of real
documentation. It always feels inappropriate, because PEPs spend a lot
of time talking about things that are irrelevant to an end-user, like
motivations for a feature, alternate proposals that were not
implemented, and so on.
- Python PEPs often give the impression of a cabal, or separation
between the "core contributors" and "users", which I want to avoid for
SymPy. For example, you may be familiar with the politics that occured
with PEP 572 (assignment expressions) or more recently, PEP 622
(pattern matching).
- Lastly, it really annoys me when people refer to Python PEPs by
number only. This serves to reinforce the "cabal" feeling, because
core developers tend to work with the PEPs a lot and know them by
number, but everyone else won't. Unless the PEP is PEP 8, I think
people should always either include a title with the PEP or a URL to
the PEP when referring to it.

- The SEP abbreviation is probably already used by some other
projects. How about SymPEP?

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/CAHVvXxSezSA%3Doiu9PWHNSX-7rAM_2Tdsg2yBDFvUKW9R9RENrw%40mail.gmail.com.

[Oscar Benjamin]

On Mon, 3 Aug 2020 at 21:15, Aaron Meurer <asme...@gmail.com> wrote:
>
> - We have already done some degree of high-level planning in the past.
> It just hasn't been organized. For example, you can see there are some
> documents on the wiki that go over design ideas for various things.
> Some of them are implemented and some not.

I took a look through the wiki and there are many different pages but
I don't see any that looks like a well specified design that has been
reviewed and agreed on. Since you mentioned the new assumptions
(below) I see that the new assumptions are one of the more discussed
topics having three separate pages:
https://github.com/sympy/sympy/wiki/_pages
https://github.com/sympy/sympy/wiki/Assumptions
https://github.com/sympy/sympy/wiki/Assumptions-Handlers
https://github.com/sympy/sympy/wiki/Assumptions-history

Mostly though the pages on the wiki look like collections of
first-draft notes each written by a single author, reviewed by no one
and then never updated again. Those can be useful in many situations
but they're really not the kind of thing I'm thinking about.

> And of course, every GSoC
> project starts with a GSoC proposal that outlines what will be done in
> the project.

There are also lots of GSOC proposals on the wiki but those are also
different. A GSOC proposal is used to select a student who is then
supervised by the mentor(s) who will then drive the high-level design.
When evaluating proposals I treat them as a demonstration that the
student understands roughly what they are volunteering to do (under
instruction) rather than as a specification of what will actually be
done.

> - I would look at how other similar projects do this, especially
> projects in the scientific ecosystem. NumPy, matplotlib, and
> scikit-learn

> ...

> We should also talk with members of those
> communities to see how they feel about the processes and what works
> and what doesn't.

I'll give that a go.

> I think Python PEPs aren't a great model to mimic
> directly. The Python community of developers is much larger, the
> community of users is *much* larger, and they also care much more
> about not breaking compatibility and being conservative about adding
> new features than we do.

I think we *should* be more conservative about adding features. For
the most part, time would be better spent improving the existing
features and documentation. We should also be more conservative about
breaking compatibility. The community of users for sympy is growing
all of the time as is the number of downstream libraries. PyPI now
records on the order of a million downloads per month for sympy:
https://pypistats.org/packages/sympy
I'm sure the vast majority of that is CI but that shows how many
projects now have sympy as a dependency. Of course it's easier to be
more conservative about breaking compatibility if you are also more
conservative about adding features in the first place.

> - My biggest concern is this: it is often impossible to really know
> what will work unless we try to implement it.

We would have to be prepared to discuss or allow changes as needed on
an ongoing basis until implementation is complete. I still think it's
good to start with a proper specification and consider that in full
with its rationale before implementing anything beyond proof of
concept. Problems will always emerge during implementation but better
design can help to avoid fundamental problems.

> I think the assumptions
> are a great example of this. The idea of what the "new assumptions"
> should look like has changed several times over the years, because
> every time it has become clear that the current idea isn't tenable.
> This has led to a rather unfortunate state of things where we have two
> concurrent systems. But I don't really see how we could have come up
> with a "new assumptions" idea that would actually work without first
> trying out what we did and seeing why it didn't work.

I wasn't around so I won't comment on discussion or design that took
place in the past. What I will say is that at this stage we really do
need something like a SymPEP to plan out what to do with assumptions
*going forwards*. There needs to be a discussion and decisions need to
be made and the result should be distilled and written down for all to
see. The implications for developers and users need to be spelled out
somewhere and there needs to be an implementation plan so that
contributors can get on with that work.

Last year there was a GSOC student working on making the new
assumptions faster which is a straight-forward improvement that we can
all understand without needing to think about complicated design
questions. This year we have 6 GSOC students and none of them is
working on assumptions even though it is high priority. I think that's
quite simply because no one knows what a project on the new
assumptions would do at this stage. (Design not agreed, no
implementation plan)

> - I have a few gripes with the Python PEP process which I think we
> should try to avoid.

All agreed.

> - The SEP abbreviation is probably already used by some other
> projects. How about SymPEP?

Yes, I like the pronunciation of that.


Oscar

[Aaron Meurer]

On Mon, Aug 3, 2020 at 5:01 PM Oscar Benjamin
<oscar.j....@gmail.com> wrote:
>
> On Mon, 3 Aug 2020 at 21:15, Aaron Meurer <asme...@gmail.com> wrote:
> >
> > - We have already done some degree of high-level planning in the past.
> > It just hasn't been organized. For example, you can see there are some
> > documents on the wiki that go over design ideas for various things.
> > Some of them are implemented and some not.
>
> I took a look through the wiki and there are many different pages but
> I don't see any that looks like a well specified design that has been
> reviewed and agreed on. Since you mentioned the new assumptions
> (below) I see that the new assumptions are one of the more discussed
> topics having three separate pages:
> https://github.com/sympy/sympy/wiki/_pages
> https://github.com/sympy/sympy/wiki/Assumptions
> https://github.com/sympy/sympy/wiki/Assumptions-Handlers
> https://github.com/sympy/sympy/wiki/Assumptions-history
>
> Mostly though the pages on the wiki look like collections of
> first-draft notes each written by a single author, reviewed by no one
> and then never updated again. Those can be useful in many situations
> but they're really not the kind of thing I'm thinking about.

Well usually if there was a discussion it happened on the list or on
an issue, and wasn't necessarily put into the document. So I think
having this sort of thing formalized so that the discussion always has
to be summarized in the document is good.

Here are some other examples that don't relate to assumptions:

https://github.com/sympy/sympy/wiki/UD-series (as well as a bunch of
other pages that start with "UD")
https://github.com/sympy/sympy/wiki/Args-Invariant (this one actually
does have some discussion on it)
https://github.com/sympy/sympy/wiki/Canonicalization

>
> > And of course, every GSoC
> > project starts with a GSoC proposal that outlines what will be done in
> > the project.
>
> There are also lots of GSOC proposals on the wiki but those are also
> different. A GSOC proposal is used to select a student who is then
> supervised by the mentor(s) who will then drive the high-level design.
> When evaluating proposals I treat them as a demonstration that the
> student understands roughly what they are volunteering to do (under
> instruction) rather than as a specification of what will actually be
> done.

I wasn't suggesting that the GSoC proposals are what this should look
like. I'm only pointing out that the idea of writing down proposals
for how to implement stuff in SymPy before doing it isn't completely
new. GSoC proposals are actually a good place to look to get an idea
of how far an original proposal can deviate from what was actually
implemented, and why.

>
> > - I would look at how other similar projects do this, especially
> > projects in the scientific ecosystem. NumPy, matplotlib, and
> > scikit-learn
> > ...
> > We should also talk with members of those
> > communities to see how they feel about the processes and what works
> > and what doesn't.
>
> I'll give that a go.
>
> > I think Python PEPs aren't a great model to mimic
> > directly. The Python community of developers is much larger, the
> > community of users is *much* larger, and they also care much more
> > about not breaking compatibility and being conservative about adding
> > new features than we do.
>
> I think we *should* be more conservative about adding features. For
> the most part, time would be better spent improving the existing
> features and documentation. We should also be more conservative about
> breaking compatibility. The community of users for sympy is growing
> all of the time as is the number of downstream libraries. PyPI now
> records on the order of a million downloads per month for sympy:
> https://pypistats.org/packages/sympy
> I'm sure the vast majority of that is CI but that shows how many
> projects now have sympy as a dependency. Of course it's easier to be
> more conservative about breaking compatibility if you are also more
> conservative about adding features in the first place.

Sure, any library should care about these things to some degree. But
someone pointed out a PEP earlier in this thread for adding a single
function to the Python standard library, a function which would
probably be used by less than 1% of Python developers. I don't think
we need to do that. If someone wants to add, say, a new well
established special function to the functions submodule, we shouldn't
need a design document to justify it.

Actually, I would start out only using SymPEPs for very large changes,
and see how it works. Then based on how it pans out we can see if it
makes sense for more targeted changes.

Some of the assumptions stuff predates me too (it's that old), but I
believe the original idea was that the new assumptions would replace
the old assumptions completely. I think it's now clear that this is a
bad idea, because at least syntactically, the old assumptions are very
convenient for the cases that they work for. And even ignoring that,
swapping out a whole piece of the core like that is an impossible
task, because it breaks too much (the devs from back then already went
through this with the so-called "new core", so you think they would
have known better).

But there were also design missteps, like making the new assumptions
handlers work too much like the old assumptions handlers, and not
being careful about definitions. Making them separate from each other
was also a mistake. If we had realized that the old assumptions syntax
should stay, we could have made the new assumptions call the old
assumptions as we do now, and avoided a lot of inconsistencies between
them.

There's also been disagreement, even now, about how good it is to have
assumptions be separate from expressions. That's the basic design
principle of the new assumptions.

I don't know if trying to write a design document from the front would
have avoided any of these issues, because it isn't clear to me that
anyone knew they would be issues from the start. The main thing I
think is that no one accurately predicted how difficult it would be to
make any kind of change to the current (old) assumptions system. Even
small changes that appear trivial can result in having to modify the
entire codebase, and the performance of it is critical as well.

Maybe we can do something now. We've definitely layed out some plans
of how to proceed in previous GSoC projects, which were not all
completely finished. I don't know if having a proposal would help to
get someone to do it or not. If it does, I can think of a few high
priority ideas that would be good to write SymPEPs for (see
https://www.sympy.org/en/roadmap.html).

>
> > - I have a few gripes with the Python PEP process which I think we
> > should try to avoid.
>
> All agreed.
>
> > - The SEP abbreviation is probably already used by some other
> > projects. How about SymPEP?
>
> Yes, I like the pronunciation of that.
>
>
> Oscar
>

> --
> 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/CAHVvXxR7v%2BTmt91wsxX5AehXmEfLAL7Hu%2BUuqf92bdfJv2zvfA%40mail.gmail.com.

[Nicolas Guarin]

I agree that this would be good for the project but maybe it would be a good idea to polish the documentation a bit. Some of the pages in the wiki are somewhat outdated and they are on the first results in a web search.

[David Bailey]

On 06/08/2020 00:47, Nicolas Guarin wrote:

I agree that this would be good for the project but maybe it would be a good idea to polish the documentation a bit. Some of the pages in the wiki are somewhat outdated and they are on the first results in a web search.

Assuming you are talking about the user level documentation,  I very much agree.

If you look up even the simplest function - e.g. Sin[] - in Mathematica, you get a simple explanation, some examples showing that it can be used with real numbers, and that it 'knows' about special arguments such as Pi/3.

It shows you the power series about zero and a plot of the function. It also shows some properties of the function such as Sin[x] = -Sin[-x] etc etc.

It also shows that Sin can be applied to complex arguments, or even to matrices, and that it can be applied to a high precision floating point number to deliver a high precision result.

That same level of detail is provided for every function - right up to complicated functions like MeijerG. Remember that for functions such as that, the documentation is even more important because there are different conventions as to the order,sign, etc of the arguments.

This might appear like overkill, but it means that wherever you start you will realise a Mathemaica function is far more than just a numerical function. This is also true for SymPy, but the information is harder to find. It is also easy to cut/paste from the documentation into your own code.

Of course, the documentation is massively redundant, but I imagine that the documentation for each function or operation would not be written from scratch, but pulled from some kind of database of information.

Obviously the SymPy documentation can't jump to the Mathematica standard overnight, but maybe a student could put together some sort of framework from which such documentation of the standard maths functions could be generated, and start the process off - then others could contribute information that would fit into the same scheme.

I think that such documentation would make SymPy very much more user-friendly.

David

[Matthew Brett]

Hi,

Just to say - that the Scipy Documentation Project took Numpy from
fairly woeful documentation, to very good documentation, in a few
months, and with a fairly small budget:

http://conference.scipy.org/proceedings/SciPy2008/paper_5/
https://ieeexplore.ieee.org/document/6879046

Cheers,

Matthew

[Jason Moore]

A nice thing for a GSoD student to do would be to organize a documentation sprint.

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 view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAH6Pt5q%3DN_Vb0Z_yM2w8nBKwFFJu8UPBO3_A0c1UeWhAKDBX%3Dg%40mail.gmail.com.

[Nikhil Maan]

On Thursday, August 6, 2020 at 9:39:43 PM UTC+5:30 moore...@gmail.com wrote:

A nice thing for a GSoD student to do would be to organize a documentation sprint.

 

This sounds like a great idea.

I also like the idea of SymPy Enhancement Proposals. Another project that I think might benefit SymPEPs is Naman Gera's work on adding control systems to SymPy. It will be a great place for folks who would like to help with/continue this work in the future to find the motivations and other details about the decision choices and future plans.

Looking at PEP-1 and seeing a large portion of the discussion in the thread is regarding what kind of work should have a SymPEP and what they should include, I think a good starting point for SymPEP-1 will be to describe what are SymPEPs, why we are planning to add them, what kind of changes should have a SymPEP, etc. Also, I like the sound of SymEP and SymPEP. +1 to calling them SymPEP or SymEP instead of SEP.

Regards,
Nikhil Maan

[Aaron Meurer]

I think the documentation stuff is a bit off topic here. We can
improve documentation and have SymPEPs. In fact, if improving
documentation requires a large concerted effort, that could itself be
a SymPEP. However, I will note that on this front:

- We are participating in Google Season of Docs (GSoD, not to be
confused with GSoC), which is a program that pays technical writers to
work on open source documentation. The GSoD results will be announced
in a couple of weeks, so watch this space.

- I agree that we should have a concerted effort to improve
documentation. A documentation sprint is one way. Getting funding to
improve things is another.

- We have a documentation style guide, which was developed as part of
last year's GSoD. However, only a small subset of SymPy actually
conforms to the guide
https://docs.sympy.org/latest/documentation-style-guide.html.

Aaron Meurer

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/b977b777-52de-43af-81c9-445662ffef9bn%40googlegroups.com.

[Aaron Meurer]

I'd like to restart discussion on SymPEPs.

Here are the documents outlining the processes for PEPs, MEPs
(Matplotlib Enhancement Proposals), and NEPs (NumPy Enhancement
Proposals)

https://www.python.org/dev/peps/pep-0001/
https://matplotlib.org/3.1.1/devel/MEP/template.html
https://numpy.org/neps/nep-0000.html

The MEP and NEP templates are both very similar to PEPs.

So I think we should start with SymPEP 1, which would be the outline
of the SymPEP process. The first meta question that needs to be
answered, though, is where should SymPEPs live, and where should the
discussions on them take place? A natural place would be the wiki, but
I actually think the wiki isn't the best place. The wiki doesn't have
any discussion features, and it also doesn't have any way to do pull
requests. Also the wiki allows anyone to edit it without permission,
which might not be what we want for SymPEPs.

So I would suggest either including them in the main SymPy repo, or
creating a new SymPEPs repo for them. Any preference on which would be
better? I think I would prefer a separate repo, unless we want to have
the rendered documents included in the SymPy documentation, in which
case that will be easier if they are in the SymPy repo. In either
case, I would suggest for the discussions for any SymPEP to take place
on issues or pull requests on the respective repo.

Once we decide this, we can start with an actual start for SymPEP 1
and the discussion of what it should look like.

Aaron Meurer

[Jonathan Gutow]

+1 for a separate repo.

I think that initially the default format for SymPEPs should be markdown
as it renders well in github. Markdown has some serious limitations, so
their may be reasons to change this later.

Regards,

Jonathan

On 10/12/20 5:06 PM, Aaron Meurer wrote:
> CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender and know the content is safe.
>
>

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6K114c9mbhXLVru4HCVB_M_-4wLdf7pHnz-ceHm97gAiQ%40mail.gmail.com.

[Oscar Benjamin]

I agree that a separate repo for SymPEPs is best.

Once 1.7 is released I can try to draft SymPEP 1 soon for discussion
here to bootstrap the process.

Oscar

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/680e649c-f869-dcb4-f17f-7f5e977a17cd%40uwosh.edu.

[Nicolas Guarin]

I also think that a new repo is the way to go. We don't want to have more (cognitive) load in the documentation.

[Aaron Meurer]

I started a repository for SymPEPs https://github.com/sympy/SymPEPs

There's nothing there yet. I will start a discussion on the repo
either later today or early next week to discuss the SymPEP process
and drafting the SymPEP format (unless someone else beats me to it).

Aaron Meurer

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/bd536574-b2c3-4cd8-983f-c91b3dbd4ffcn%40googlegroups.com.

[Aaron Meurer]

I have started a pull request for SymPEP 1.
https://github.com/sympy/SymPEPs/pull/2.

Feedback is encouraged. This is still a draft, so everything I've
written there can still be changed. I've based it largely on the NEP
(NumPy Enhancement Proposals) process, with some changes.

Aaron Meurer