The phrase "this cone cannot be..." can be misinterpreted as making a
value judgment about the given cone, rather than a blanket statement
about the argument (self) to these two functions. This commit changes
it to "cone should not be..." to indicate that the user should not
pass in either a trivial cone or the ambient space.

…e().

The error message output when _random_admissible_cone() receives an
invalid ambient dimension was a full sentence. This commit pares it
down to just the important part; amely, that there are no nontrivial
cones in the ambient dimension.

The line "G_index_sets = list(gevp_licis(G))" appears twice in EXAMPLES,
but the variable "G_index_sets" is not used thereafter. It was most
likely copy/pasted into the example by mistake. This commit removes it.

…30605.

Thanks to some recent improvements in cone containment testing, we no
longer have to reimplement it for vectors with irrational entries
ourselves.

The sage library is now doctested with a random random seed (imagine),
making most calls to set_random_seed() superfluous. We remove a few
from the cone critical angle code here.

The solve_gevp_zero() and solve_gevp_nonzero() functions for cone
critical angles are "internal" and can return generators. Likewise for
the testing function _solve_gevp_naive(). This should be a tiny bit
more efficient.

…metic.

Passing exact=False to either the max_angle() or critical_angles()
method of cones is a bit "dangerous" because we can miss eigenspaces
of dimension >= 2 due to numerical issues. Add a warning to the
docstring about it.

…s.py.

Two tests in this module imported the gevp_licis() function but then
did not use it. No longer.

We already have a matroid method that does more or less what the new
gevp_licis() function does in cone_critical_angles.py. It's faster to
use the matroid implementation and then tweak its output slightly, so
let's do that instead.

For reasons I've long forgotten, the cone max/critical angles
algorithms were using QQbar for "rationals with roots." Switching it
to AA causes no problems now, and is clearly preferable (the only
eigenvalues we compute are of positive-definite matrices).

…problem.

This should make the field of "zero" consistent with all the non-zero
eigenvalues.

This lets the user (and us, in the tests) stick the results into a set
or any other structure whose elements must be hashable.

Now that all eigenvalue problems should be solved over the same field,
and now that we're returning immutable eigenvectors from those
problems, using set equality (as oposed to element-wise ==) becomes
possible.

Recent research has shown that (in many cases) the maximal angle does
not change too much if the cones are perturbed. This creates even more
of a safety net when computing the maximal angle, because falling back
to inexact arithmetic "perturbs" the cones.

The critical angle function, however, is not lower-semicontinuous as a
set-valued map. I don't like having a "debug" parameter that tells you
you're getting wrong results, and a user interface that requires you
to understand the subtle differences between upper- and
lower-semicontinuity for set-valued maps is not awesome. I think it's
best if we leave this out for now.

The max_angle() can fall back to exact=False if exact=True runs in to
(known) issues. The [Or2024] reference discusses when/why this is OK.

This special case is handled by the P.intersection(-Q) check before we
have to think too hard about whether or not it would hurt anything.

Allow _random_admissible_cone() to generate the entire ambient
space. This only affects a few test cases where it doesn't matter.

Maxima no longer crashes, so the description was wrong, and we can
avoid numerical comparisons with simplify() and a round trip through
sympy.

Witness:

  sage: n = 4 ## line 6313 ##
  sage: K = cones.schur(n) ## line 6314 ##
  sage: bool( K.max_angle()[0].simplify() == ((n-1)/n)*pi ) ## line 6315 ##
  ------------------------------------------------------------------------
  /usr/lib/python3.11/site-packages/cysignals/signals.cpython-311-x86_64-
  linux-gnu.so(+0x8950)[0x7fa8349c1950]

So let's go through sympy in the n=4 case, too.

We should explain why it's not a good idea to _start_ with
exact=False.

…itle

…dent

…tion

…prose

These names are helpful in the cone_critical_angles module, but not in
max_angle() which immediately passes them off to another method.

… docs

…not"

…calls

…call

…atrices

…nonzero()

Using the identity M[I,J].transpose() == M.transpose()[J,I], we can
avoid transposing M itself and instead transpose the smaller M[I,J]
when M[I,J] is already known.

…ning

The existing warning about this module being internal is easy to
miss. This one should appear in bright red at the top of the module
documentation.

…ngles

This is an internal module, but it's fully documented and nice to have
access to the implementation behind the max_angle() function. Despite
being documented, the functions in cone_critical_angles.py are subject
to change at any time. This itself is loudly documented.