New comparison mode to lazy series and better undefined check

[tscrim]

📚 Description

This fixes #35071 by:

1. providing a method to streams to see if they are unitinalized
2. includes a new mode for comparisons in the lazy series ring based on the proposal in simplify bool and make uninitialized streams nonzero unless they are trivially zero #35429.

The new comparison mode secure simply returns False when it cannot verify that f == g and makes sure that (f == g) == not (f != g), and this will become the new default. In particular, it will return True for f != g both when it cannot show that f == g and when they are genuinely different. In order to verify when the comparison is unknown, we expose the is_nonzero() that only returns True when the series is known to be nonzero. Thus, we verify by (f - g).is_nonzero().

When a finite halting precision is given, then that takes priority.

For the infinite halting precision in the "old" version (secure = True), it will raise a ValueError when it cannot verify the result.

NOTE: f.is_zero() is still the default not f for speed and the assumption these are in agreement elsewhere in Sage.

📝 Checklist

• The title is concise, informative, and self-explanatory.
• 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 accordingly.

⌛ Dependencies

[tscrim]

I haven't added all of the requisite doctests, but this is what I arrived at.

This is my proposal for a compromise solution from #35429 with what I want (verification of computations) and what @mantepse wants with speed and usability.

[tscrim]

One quick comment as I go out the door. In the last commit, I gave another variation on this, where instead of Unknown being returned, we return None for the comparisons and have the bool() return True. This almost passes all doctests except for one that I don't have time to understand, but can likely be easily fixed.

[mantepse]

Sorry, u probably won't be able to look at this until Saturday.

[tscrim]

No problem; no rush. I fixed the doctest failure. I did a force push of it to keep the alternative proposal within the one commit.

[tscrim]

The benefits for the last proposal as it (functionally) never gives a false positive for == and != as it returns None in place of Unknown for comparisons it can't know the result. (There are other changes that I would do if we go this route.) However, I think with it not necessarily matching bool(f) and the fact that code needs to be much more careful about f != g versus the less natural not (f == g) (which is typically is not, as evidenced by even the lazy series code needed to be changed), means we should not do this (at least as a default). I could add this as an even further additional option, but perhaps that is diminishing returns with comparison behaviors...

What do you think?

[tscrim]

This does not need to depend on #35362 as the new streams added have no way of verifying (i.e., an undecidable problem) if they have uninitialized streams being created in the iterator.

[mantepse]

There are a couple of things from #35480 that were lost but should be included:

diff --git a/src/sage/data_structures/stream.py b/src/sage/data_structures/stream.py
index 7038ce2149c..8cd49565fa8 100644
--- a/src/sage/data_structures/stream.py
+++ b/src/sage/data_structures/stream.py
@@ -968,6 +723,11 @@ class Stream_function(Stream_inexact):
     - ``approximate_order`` -- integer; a lower bound for the order
       of the stream
 
+    .. WARNING::
+
+        We assume for equality that ``function`` is a function in the
+        mathematical sense.
+
     EXAMPLES::
 
         sage: from sage.data_structures.stream import Stream_function
@@ -1000,6 +760,43 @@ class Stream_function(Stream_inexact):
         super().__init__(is_sparse, true_order)
         self._approximate_order = approximate_order
 
+    def __hash__(self):
+        """
+        Return the hash of ``self``.
+
+        EXAMPLES::
+
+            sage: from sage.data_structures.stream import Stream_function
+            sage: f = Stream_function(lambda n: n, True, 0)
+            sage: g = Stream_function(lambda n: 1, False, 1)
+            sage: hash(f) == hash(g)
+            True
+        """
+        # We don't hash the function as it might not be hashable.
+        return hash(type(self))
+
+    def __eq__(self, other):
+        """
+        Return whether ``self`` and ``other`` are known to be equal.
+
+        INPUT:
+
+        - ``other`` -- a stream
+
+        EXAMPLES::
+
+            sage: from sage.data_structures.stream import Stream_function
+            sage: fun = lambda n: n
+            sage: f = Stream_function(fun, True, 0)
+            sage: g = Stream_function(fun, False, 0)
+            sage: h = Stream_function(lambda n: n, False, 0)
+            sage: f == g
+            True
+            sage: f == h
+            False
+        """
+        return isinstance(other, type(self)) and self.get_coefficient == other.get_coefficient
+
 
 class Stream_uninitialized(Stream_inexact):
     r"""
@@ -2759,6 +2406,11 @@ class Stream_map_coefficients(Stream_inexact):
     - ``series`` -- a :class:`Stream`
     - ``function`` -- a function that modifies the elements of the stream
 
+    .. WARNING::
+
+        We assume for equality that ``function`` is a function in the
+        mathematical sense.
+
     EXAMPLES::
 
         sage: from sage.data_structures.stream import (Stream_map_coefficients, Stream_function)

[tscrim]

Thanks. I have added those changes (although I weakened .. WARNING:: to .. NOTE::, but I am not entirely sure how useful it is). I also expanded Stream_unary a bit to allow it to be inherited more to remove some code redundancy.

[tscrim]

I also have subsequently checked that merging in #35362 doesn't introduce any failures or conflicts.

[mantepse]

There are a few trivial doctest failures in recursive_species.py, you'd just have to replace Uninitialized Lazy Laurent Series with Uninitialized Lazy Series (which I like better anyway).

[tscrim]

You're right that we cannot have any fully correct is_uninitialized() check for streams involving functions (including map_coefficients). At least this gets us most of the way there, and your improvement certainly helps and covers cases I wasn't considering. I have also added a test for that.

For the infinite products/sums, I could make those work purely in terms of modifying #35362.

I am not convinced we should have a check global option. It is too easy for a user to have disabled it and then subsequently pass a series that breaks the assumptions. It would break through the wall separating the series and the streams (as some streams do their own checking). In either case, we would need an example that we cannot find any way to make work -- and really should work -- before I would say we should implement such things (on a separate PR). I think this one here makes a lot of progress as-is.

[mantepse]

Perfect!

[mantepse]

See #35485 (comment) - indeed, I do not want a global option, I want a check keyword for the element constructor..

Using the new is_uninitialized method, I think it will be only rarely necessary to pass check=False.

[tscrim]

Thank you.

Most likely, but I am hoping that we will never have to use/implement a check ever. We'll let's see what happens when we come across such a bug.

[tscrim]

Trivial rebase to fix the merge conflict.

[github-actions]

Documentation preview for this PR (built with commit 1ad7352; changes) is ready! 🎉

[tscrim]

Fixes #35071.

Once closed, this will also close #35429 and #35480 (our first two attempts).