Rename zprimitive to zpoly

Author: oscarbenjamin

README.md

@@ -175,7 +175,7 @@ Contributors (0.10.0):
 Changes (0.10.0):
 
 - [gh-421](https://github.com/flintlib/python-flint/pull/421),
-  Add `zprimitive` and `zcontent` methods to `fmpq_mpoly`, to get
+  Add `zpoly` and `zcontent` methods to `fmpq_mpoly`, to get
   the primitive integer polynomial and the `fmpq` content, which
   form the internal representation of the `fmpq_mpoly`. Also add
   support for building with Cython 3.3. (VM, OB)

src/flint/test/test_all.py

@@ -3934,25 +3934,25 @@ def quick_poly():
         assert False # New _mpoly types?
 
 
-def test_fmpq_mpoly_zcontent_zprimitive():
+def test_fmpq_mpoly_zcontent_zpoly():
     ctx = flint.fmpq_mpoly_ctx.get(("x", "y"))
     x, y = ctx.gens()
     zctx = flint.fmpz_mpoly_ctx.from_context(ctx)
     zx, zy = zctx.gens()
 
     f = -2*x/3 - 2*y/5
     assert f.zcontent() == flint.fmpq(-2, 15)
-    assert f.zprimitive() == 5*zx + 3*zy
+    assert f.zpoly() == 5*zx + 3*zy
     assert isinstance(f.zcontent(), flint.fmpq)
-    assert isinstance(f.zprimitive(), flint.fmpz_mpoly)
+    assert isinstance(f.zpoly(), flint.fmpz_mpoly)
     # Can't mix fmpq_mpoly with fmpz_mpoly...
-    p = flint.fmpq_mpoly(f.zprimitive(), ctx=ctx)
+    p = flint.fmpq_mpoly(f.zpoly(), ctx=ctx)
     c = f.zcontent()
     assert p * c == f
 
     f = 0*x
     assert f.zcontent() == 0
-    assert f.zprimitive() == 0
+    assert f.zpoly() == 0
 
 
 def _all_mpoly_vecs():

src/flint/types/fmpq_mpoly.pyi

@@ -102,7 +102,7 @@ class fmpq_mpoly(flint_mpoly[fmpq_mpoly_ctx, fmpq, ifmpq]):
     def xgcd(self, other: fmpq_mpoly, /) -> fmpq: ...
     def term_content(self) -> fmpq_mpoly: ...
 
-    def zprimitive(self) -> fmpz_mpoly: ...
+    def zpoly(self) -> fmpz_mpoly: ...
     def zcontent(self) -> fmpq: ...
 
     def factor(self) -> tuple[fmpq, list[tuple[fmpq_mpoly, int]]]: ...

src/flint/types/fmpq_mpoly.pyx

@@ -215,6 +215,23 @@ cdef class fmpq_mpoly(flint_mpoly):
     """
     The *fmpq_mpoly* type represents sparse multivariate polynomials over
     the rationals.
+
+    Internally, an ``fmpq_mpoly`` is represented as the product of a signed
+    rational content and a primitive integer multivariate polynomial with
+    positive leading coefficient. The :meth:`zcontent` and :meth:`zpoly`
+    methods return copies of these two components, respectively.
+
+    The original polynomial can be reconstructed from these components by
+    converting the integer polynomial back to an ``fmpq_mpoly`` in the
+    original context and multiplying by the content:
+
+        >>> ctx = fmpq_mpoly_ctx.get(("x", "y"))
+        >>> x, y = ctx.gens()
+        >>> f = -2*x/3 - 2*y/5
+        >>> zpoly = f.zpoly()
+        >>> content = f.zcontent()
+        >>> fmpq_mpoly(zpoly, ctx=f.context()) * content == f
+        True
     """
 
     def __cinit__(self):
@@ -785,15 +802,15 @@ cdef class fmpq_mpoly(flint_mpoly):
         fmpq_mpoly_term_content(res.val, self.val, self.ctx.val)
         return res
 
-    def zprimitive(self):
+    def zpoly(self):
         """
         Return the integer polynomial of ``self``. The product
-        of this and ``self.zcontent()``, represents the whole
+        of this and ``self.zcontent()`` represents the whole
         polynomial.
 
             >>> ctx = fmpq_mpoly_ctx.get(("x","y"))
             >>> x, y = ctx.gens()
-            >>> (x*2/3 + y*2/5).zprimitive()
+            >>> (x*2/3 + y*2/5).zpoly()
             5*x + 3*y
         """
         cdef fmpz_mpoly_ctx zctx = fmpz_mpoly_ctx.from_context(self.ctx)
@@ -804,7 +821,7 @@ cdef class fmpq_mpoly(flint_mpoly):
     def zcontent(self):
         """
         Return the content of ``self``. The product of this and
-        ``self.zprimitive()``, represents the whole polynomial.
+        ``self.zpoly()`` represents the whole polynomial.
 
             >>> ctx = fmpq_mpoly_ctx.get(("x","y"))
             >>> x, y = ctx.gens()