Improvements to the construction of subalgebras

[tscrim]

This speeds up the construction of subalgebras by only applying generators to newly created elements (i.e., not in the span of the previous iteration). We also take into account the basis order (which also works for things that are indexed by objects that do not have natural comparisons).

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation and checked the documentation preview.

⌛ Dependencies

[orlitzky]

Tangential, but it would be nice to have the category and order arguments documented.

[tscrim]

@orlitzky Good point, done.

[tscrim]

I refactored it slightly so that ideals can also use the same implementation (grow and expand only using the newly discovered elements).

[github-actions]

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

[tscrim]

@orlitzky @fchapoton Can one of you review this fully? This gets quite a good speedup on this construction.

[orlitzky]

I'm not that familiar with FiniteDimensionalAlgebrasWithBasis, but I don't see anything unusual. Since I can't really follow what the implementation is doing at a low level, I would feel better if there were some tests for _build_basis_by_generators that e.g. pass in a random set of generators for a random algebra, and check that the result is actually a basis satisfying the stated properties.

I'd also like to check that both ideal algorithms work in all cases by tweaking the default algorithm= parameter, but I can do that myself. At that point I'm willing to trust you.

[orlitzky]

I tried setting both generators and basis as the default algorithm and it didn't hurt the CI.

One more idea though. In the ideal example, you could add an extra test to ensure that both algorithms return the same submodule (they should, right?). For example:

sage: MS = MatrixSpace(QQ, 5)
sage: gens = [MS.random_element() for _ in range(ZZ.random_element(5))]
sage: I = MS.ideal_submodule(gens, algorithm="generators")
sage: J = MS.ideal_submodule(gens, algorithm="basis")
sage: I.is_equal_subspace(J)
True

[tscrim]

Thank you. I've added the doctest and some others to demonstrate the correct properties. I had to work around an issue with the submodule __contains__ not being specific enough, and I didn't want to change that here for a doctest (but I will fix it on a followup PR).

[orlitzky]

OK, I'm convinced, thanks.

[tscrim]

Thank you!