Documentation preview for this PR (built with commit ebddbd4; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

Ping?

So what I am thinking is your original idea is best with one small modification [...]

I tried the second variant, but it actually doesn't work the way I did it. Apparently, MethodType passes the class rather than the instance of the class.

Ah, right, it would pass the class rather than the instance. I think I messed up my initial experiment. However, this does work:

sage: class Foo():
....:     def __init__(self, B):
....:         print(B)
sage: class Bar():
....:     def __init__(self, v):
....:         self.v = v
....:         from types import MethodType
....:         self.F = MethodType(Foo, self)
....:     def __repr__(self):
....:         return "Bar: %s"  % self.v
sage: B = Bar(5)
sage: B.F()
Bar: 5
<__main__.Foo object at 0x723f4645e660>

However, it seems to me that the current approach (i.e., separate classes for univariate and multivariate species and providing proper methods defined in the class) makes sense. I think that we really want to see the methods (Sets, Graphs, ...) in the documentation, and it seems that the pattern of not having a class docstring for SetSpecies and using the SetSpecies.__init__ docstring just for running the testsuite is easy to understand and extend.

Yes, that is the downside with my MethodTypes approach. Anyways, let's go with the current version then.

Does there remain anything that I should do or do you just want to have a closer look?

The next (substantial) improvements are #40129, #40163 and #40186. Arithmetic product is easy and in the pipeline. After that, we have truly superseeded the old species framework.

One doc thing and one general question (that I probably should have asked much earlier, sorry).

No problem! I'm amazed and it really makes me happy that you do thorough reviews!

Should we call these Lazy(Combinatorial)Species and not just (Combinatorial)Species? Having Lazy in front suggests there is or will be a finite precision/non-lazy version, but I don't think this will happen.

I put the Lazy in front because of PolynomialSpecies, which is not a very good name, and because of uniformity and discoverability. The latter, because I would think that to many formal power series guys species won't occur as a possibly better tool, even when it is.

I agree that a finite precision version won't happen.

We could have CombinatorialSpecies for what's now PolynomialSpecies and LazyCombinatorialSpecies instead of LazySpecies. (By coincidence, LazyC + tab is currently unused, whereas we have LazySy + tab and LazySp + tab. I'd support that, but I won't advocate for it.

The reason for not advocating: AtomicSpecies and MolecularSpecies were useful to me frequently (mostly to generate all of a given grade), whereas PolynomialSpecies are only a unwanted necessity. PolynomialSpecies occur when extracting a term of a LazySpecies and to construct LazySpecies by passing a coefficient function.

I don’t think the lazy in from makes it very discoverable compared to the API we have for similar such objects (mainly completion aka formal_series_ring). It would only be if someone is already working with the other lazy series that they would find it, but they wouldn’t know what it is and ignore it. I think CombinatorialSpecies would be the ideal name with my current understanding. PolynomialSpecies will just remain as it is, which I feel fits well enough with the power series vs polynomials differences. Putting it another way, I don’t think it should be defined by its laziness (in contrast to FPS with finite precision where we have different implementations).

I think CombinatorialSpecies would be the ideal name with my current understanding. PolynomialSpecies will just remain as it is, which I feel fits well enough with the power series vs polynomials differences. Putting it another way, I don’t think it should be defined by its laziness (in contrast to FPS with finite precision where we have different implementations).

Just a brief update: I am not sure. Essentially, that does mean that we should make LazyPowerSeriesRing an implementation of PowerSeriesRing.

Another thing I just noticed is that CombinatorialSpecies(min=None) is currently in the global namespace: it designates a currently undefined species, with valuation min. Not sure how to do the deprecation here.

I guess we could first leave things as they are (perhaps rename LazySpecies to LazyCombinatorialSpecies) and after the deprecation period drop Lazy.

I think CombinatorialSpecies would be the ideal name with my current understanding. PolynomialSpecies will just remain as it is, which I feel fits well enough with the power series vs polynomials differences. Putting it another way, I don’t think it should be defined by its laziness (in contrast to FPS with finite precision where we have different implementations).

Just a brief update: I am not sure. Essentially, that does mean that we should make LazyPowerSeriesRing an implementation of PowerSeriesRing.

In the sense of a common abstract class and creation (with the default precision being passed as oo), then I would not be opposed. However, because there is both a finite precision and lazy version, it makes some sense to have them be separate. That being said, I do think it would be better to have more common API and base classes, but that should be done separately.

Another thing I just noticed is that CombinatorialSpecies(min=None) is currently in the global namespace: it designates a currently undefined species, with valuation min. Not sure how to do the deprecation here.

I guess we could first leave things as they are (perhaps rename LazySpecies to LazyCombinatorialSpecies) and after the deprecation period drop Lazy.

Hmm….that’s really annoying. We can’t really just do a drop-in replacement as it has different API, right? We could do a 2 step deprecation: the CombinatorialSpecies and then Lazy[Combinatorial]Species after removing Lazy from it. Yet that’s a bit of work. There might not be a good option here. :/

I would like to move on here. Meanwhile, I have also implemented the arithmetic product. I agreed to give an online course on enumeration with sagemath at 128.5, but I guess it is too late to have this even in develop.

Thank you!

This is causing one test failure here (Arch, all dependencies up to date)

sage -t --warn-long 30.0 --random-seed=98465613109387680556179046791300572857 sage-src/src/sage/rings/lazy_species.py
**********************************************************************
File "sage-src/src/sage/rings/lazy_species.py", line 647, in sage.rings.lazy_species.LazyCombinatorialSpeciesElement.__call__
Failed example:
    A[5]
Expected:
    X*E_4 + X^2*E_3 + 3*X^3*E_2 + X*E_2(X^2) + 3*X^5
Got:
    X*E_4 + X^2*E_3 + X*E_2(X^2) + 3*X^3*E_2 + 3*X^5
**********************************************************************
1 item had failures:
   1 of  37 in sage.rings.lazy_species.LazyCombinatorialSpeciesElement.__call__
    [302 tests, 1 failure, 10.73s wall]

Thank you for reporting! The problem is that there is no good ordering on the terms. Shall I mark it as random?

Thank you for reporting! The problem is that there is no good ordering on the terms. Shall I mark it as random?

I'd say mark that one as random, and then test equality against the expected output

see #40304