Add pull_from_function_field to curves

[kwankyu]

For an algebraic curve C, C.pull_from_function_field() provides the inverse map of C.function() between the fraction field of the coordinate ring of C and the abstract function field of C. This tightens the integration of the two isomorphic fields. Elements of the fraction field of the coordinate ring of C is represented by elements of the fraction field of the coordinate ring of the ambient affine or projective space, for user's convenience.

This is the missing feature as discussed in

https://groups.google.com/g/sage-support/c/Axkaex63f8w/m/wKL0TzmDAwAJ

The problem there can be solved by

sage: P2.<x,y,z> = ProjectiveSpace(QQ, 2)
sage: f = 2*x^5 - 4*x^3*y*z + x^2*y*z^2 + 2*x*y^3*z + 2*x*y^2*z^2+ y^5
sage: C = Curve(f)
sage: K = C.function(x/y).differential().divisor()  # canonical divisor
sage: basis = (-K).basis_function_space()
sage: Basis = [C.pull_from_function_field(f) for f in basis]
sage: phi = C.hom(Basis, P2)
sage: D = phi.image()  # conic
sage: D.degree()
2
sage: D
Closed subscheme of Projective Space of dimension 2 over Rational Field defined by:
  x^2 + x*y + 2*y*z

📝 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

[kwankyu]

@nbruin ?

[kwankyu]

@jhpalmieri ?

[jhpalmieri]

@jhpalmieri ?

Not really my field of expertise, unfortunately. I hope @nbruin can chime in.

[nbruin]

Sorry, I don't know how to review things on github. I think you'll have quicker results if someone else does it.

[jhpalmieri]

Sorry, I don't know how to review things on github. I think you'll have quicker results if someone else does it.

If you find some time, you can browse the changes at https://github.com/sagemath/sage/pull/36592/files. I will also try to take a look; I can certainly run tests, check the documentation, etc.

[kwankyu]

Sorry for being late.

Sorry, I don't know how to review things on github. I think you'll have quicker results if someone else does it.

I thank John and Nils for taking care of this PR.

If you find some time, you can browse the changes at https://github.com/sagemath/sage/pull/36592/files. I will also try to take a look; I can certainly run tests, check the documentation, etc.

Reviewing PRs, especially mathematical ones, on github is relatively easy. Perhaps I can summarize the procedure as follows:

1. Check if what the PR achieves as described in the PR description is worth to be merged to Sage. This needs your expertise on the subject domain.

2. Check if the code changes does only what the PR intends to do. This can be done by reading the new doctests or checking the mere existence of them. It is also important to check the documentation changes. For this PR, find pull_from_function_field in the "diffsite" and the "diffsite".

3. Check if the new code does not break Sage. This is certified if you see "All checks have passed" below.

4. Optionally you can play with the PR to suggest further improvement to the author. Currently this requires that you build Sage on the PR branch on your own system. I think this is the most time-consuming part of the review procedure. But for a simple PR like the present one, you can skip this part.

If you need any assistance on any of these steps, I am here.

[jhpalmieri]

Great, I am happy with it. Let's merge it!

[github-actions]

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

[kwankyu]

Thank both of you, for pointing me to the opportunity to fill the feature gap!