Add sheaf cohomology for projective schemes

[kwankyu]

so we add a sheaf cohomology machinery of coherent sheaves on projective schemes. Using the machinery, we implement some invariants for projective subschemes. In particular,

• add Euler characterstic of coherent sheaves
• add arithmetic genus of projective schemes

📝 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 accordingly.

⌛ Dependencies

[tscrim]

I can review this when its ready.

[kwankyu]

I can review this when its ready.

I made this PR somewhat prematurely, to test the new PR template.

I will soon update and make it ready. Thanks!

[github-actions]

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

[tscrim]

Thinking a bit more, I am wondering if your implementation is the right way to do it. Mathematically, it seems like you should have two separate complexes, which then _cohomology_group uses to do the main computations.

For anything you want to make internal, you should start with the leading _ and hide the methods/attributes. In a similar way, I don't think it is a good ideal to use hidden methods in public doctests.

Can you also fix the linter issue too?

[kwankyu]

Thinking a bit more, I am wondering if your implementation is the right way to do it. Mathematically, it seems like you should have two separate complexes, which then _cohomology_group uses to do the main computations.

There are other methods to compute the cohomology (the dimension of the cohomology group) of coherent sheaves. Actually Maruyama's method is not the usual one implemented. Eisenbud-Floystad-Schreyer method is used in Macaulay2, and perhaps in Magma.

In the future, someone may implement other methods. Perhaps I won't. Then the main public API cohomology() (and the hidden method _cohomology_group() would get algorithm argument for a user to choose the method.

Hence the module cohomology actually computing the cohomology (and the cohomology group) is better to be separate from the module coherent_sheaf implementing coherent sheaves and providing cohomology() for a user. There is no need for the user to directly interface with the internal computation engines (Maruyama method or Eisenbud-Floystad-Schreyer method).

For anything you want to make internal, you should start with the leading _ and hide the methods/attributes.

Now there remains the question of how much "hidden" my implementation of Maruyama's method should be. I thought that declaring the module cohomology "internal" in the module docstring is enough - The reader is warned but if he wants he can read further to see what are in the module in the documentation. This is very common indeed. "internal" modules appear in our documentation. For instance, https://doc.sagemath.org/html/en/reference/groups/sage/groups/libgap_mixin.html. I guess you do not mean that all "internal" modules contain only classes whose name starts with _.

In a similar way, I don't think it is a good idea to use hidden methods in public doctests.

Can you also fix the linter issue too?

OK. I will do these later.

[tscrim]

It’s okay to have the class names be public (I would tend to say this is a good thing for most cases, this one included). However, you can directly access it by public methods (here, maruyama_complex()), so it is no longer internal.

[kwankyu]

However, you can directly access it by public methods (here, maruyama_complex()), so it is no longer internal.

There is no such method.

[kwankyu]

Can you also fix the linter issue too?

Thanks. Done.

[tscrim]

Sorry, I think I misread a few things while going over the code quickly. Yes, MaruyamaMethod is not public, but I felt like the right thing that it should be part of the API. You’re (baselessly) assuming that nobody will want to look at this data, but somebody might want to check it (even if for nothing else but pedagogical reasons or to check against hand computations).

However, I am fairly convinced the entire design should be reconsidered as the two separate complexes for the top and bottom complexes, both of which are public facing that could be done by a single class (differing by a single input parameter). So we would need the appropriate comparisons (where UniqueRepresentation becomes very useful), hashing, etc. Note that this is data that is associated with the scheme that is then used by the algorithm to do the computation. It isn’t a class that does the computation and needs to have many subroutines, internal parameters, etc. Moreover, I feel like this design matches the mathematics better.

If you don’t want to change the design, would you be open to me rewriting it with this approach as a replacement PR?

[kwankyu]

I know that you have a good intention. Thanks for that.

But I don't understand your proposal. It just sounds like overkill, like coating a break pedal with platinum (I just made up this analogy). I suspect that you are overzealous :-) I do appreciate your attention and time in reviewing this PR. Please don't get me wrong.

But let's solve the situation constructively. How about taking one of these two actions:

(A) You accept this PR as it is. Then you author a subsequent PR that implements your design. I may review the PR, but cannot be sure now that I would be positive to it.

(B) Or you leave this PR, and I will wait for a new reviewer.

?

[kwankyu]

I assume that you chose (B). Thanks for the review!

[kwankyu]

Regarding the code duplication that Travis pointed out, I think I may combine methods of class MaruyamaMethod:

cohomology_group_bottom() and cohomology_group_top() to cohomology_group(top=True);

differential_top() and differential_bottom() to differential(top=True)

This looks a bit ugly, but really removes a nontrivial code duplication. Let me know if this is desirable.

[kwankyu]

Better not to do the refactoring suggested in #37477 (comment), since Travis authored a subsequent PR #38003 that does more extensive refactoring based on the present PR.

[tscrim]

Okay, I finally found the time to do my proposed rewrite of this on #38003 as @kwankyu stated. In there, I provide the implementation I was recommending. In my proposal, everything is exposed to the user, it uses caching and unique representation, removes redundant code and documentation by making top-versus-bottom a boolean on each class, and separates the top versus bottom complexes with a class that models the entire cohomology.

I believe this provides several distinct advantages:

• Users can explore things to see the fine data involves, which can be useful for proofs and debugging.
• This is set up for future developers to build off of. For example, if they want to implement a nice basis for the cohomology (which can be done by Maruyama's method in most cases as I understand it; I'm not sure how much the current code does so) or implement group actions on the cohomology groups.
• The cohomology class could be easily expanded to include the cup product or Poincaré duality.
• This will work well with pickling; in particular, it means easier to run in multithreaded computations.
• It reflects the mathematical structures that are used in the computations.

The bulk of the code for #38003 is based off this branch.

[kwankyu]

OK. I regard #38003 as a sequel to this PR. Please copy and paste your remarks above into the description of your PR.

[kwankyu]

rebased.

[mkoeppe]

I'm not sure how to review this, in light of the alternative implementation in #38003.

If this PR is to be merged first, would it make sense to mark some of the implementation details that are intended to be done differently in #38003 as @experimental?

[kwankyu]

I'm not sure how to review this, in light of the alternative implementation in #38003.

As far as I see it, this PR has no problem, except some repetitive code (small to me, not so small to Travis). I want rather to keep the repetitive part for readibility while Travis wants to remove the repetitive part and refactor the code structure as he sees fit.

So I regard #38003 as sequel to this PR. Actually #38003 should set this PR as dependency. I may review #38003 after this PR.

If this PR is to be merged first, would it make sense to mark some of the implementation details that are intended to be done differently in #38003 as @experimental?

No. There is no "experimental" code.

[tscrim]

It isn't a sequel though, it is an alternative proposal. I have reservations about including the code as-is. You are asking me to include your code (despite my objections) without any guarantees that my code will not be opposed.

[kwankyu]

It isn't a sequel though, it is an alternative proposal. I have reservations about including the code as-is. You are asking me to include your code (despite my objections) ...

That was my interpretation of your saying "The bulk of the code for #38003 is based off this branch". I misunderstood and I am sorry. I now see your intention.

without any guarantees that my code will not be opposed.

I don't oppose a PR as a reviewer. I never did. If I don't like a PR, I leave it to others. I suggest my ideas to improve the code, but it is all up to the author whether to accept them or not.

Actually I did not see your PR yet. I don't know whether I will be positive or just leave. (By the way, my "positive over leave" ratio is very high. Matthias will agree :-)

[kwankyu]

As you left this comment here:

• ... For example, if they want to implement a nice basis for the cohomology (which can be done by Maruyama's method in most cases as I understand it; I'm not sure how much the current code does so) or implement group actions on the cohomology groups.

For the purpose, I exposed sheaf._cohomology.H(i). His paper defines an isomorphism between this vector space to the cohomology group for i > 0. Morphism between cohomology groups may be transferred to a map between these vector spaces, and then one may construct a basis nice to understand the map. But I didn't pursue the details...

• The cohomology class could be easily expanded to include the cup product or Poincaré duality.

Note that the paper does not construct a vector space isomorphic to the 0-th cohomology group.