Merge pull request #216 from Jake-Moss/master

Add mpoly docs, functions for discriminant, resultant, term_content, and deflation, and run mod_mpoly doctests.

Author: oscarbenjamin

doc/source/fmpq_mpoly.rst

@@ -0,0 +1,18 @@
+**fmpq_mpoly** -- multivariate polynomials over the rational numbers
+===============================================================================
+
+.. autoclass :: flint.fmpq_mpoly_ctx
+  :members:
+  :inherited-members:
+  :undoc-members:
+
+.. autoclass :: flint.fmpq_mpoly
+  :members:
+  :inherited-members:
+  :undoc-members:
+
+.. autoclass :: flint.fmpq_mpoly_vec
+  :members:
+  :inherited-members:
+  :undoc-members:
+

doc/source/fmpz_mod_mpoly.rst

@@ -0,0 +1,18 @@
+**fmpz_mod_mpoly** -- multivariate polynomials over the integers mod n
+===============================================================================
+
+.. autoclass :: flint.fmpz_mod_mpoly_ctx
+  :members:
+  :inherited-members:
+  :undoc-members:
+
+.. autoclass :: flint.fmpz_mod_mpoly
+  :members:
+  :inherited-members:
+  :undoc-members:
+
+.. autoclass :: flint.fmpz_mod_mpoly_vec
+  :members:
+  :inherited-members:
+  :undoc-members:
+

doc/source/fmpz_mpoly.rst

@@ -0,0 +1,18 @@
+**fmpz_mpoly** -- multivariate polynomials over the integers
+===============================================================================
+
+.. autoclass :: flint.fmpz_mpoly_ctx
+  :members:
+  :inherited-members:
+  :undoc-members:
+
+.. autoclass :: flint.fmpz_mpoly
+  :members:
+  :inherited-members:
+  :undoc-members:
+
+.. autoclass :: flint.fmpz_mpoly_vec
+  :members:
+  :inherited-members:
+  :undoc-members:
+

doc/source/index.rst

@@ -73,9 +73,13 @@ Polynomial types
    :maxdepth: 1
 
    fmpz_poly.rst
+   fmpz_mpoly.rst
    fmpq_poly.rst
+   fmpq_mpoly.rst
    nmod_poly.rst
+   nmod_mpoly.rst
    fmpz_mod_poly.rst
+   fmpz_mod_mpoly.rst
    fq_default_poly.rst
    arb_poly.rst
    acb_poly.rst

doc/source/nmod_mpoly.rst

@@ -0,0 +1,18 @@
+**nmod_mpoly** -- multivariate polynomials over the integers mod n (word-size n)
+===============================================================================
+
+.. autoclass :: flint.nmod_mpoly_ctx
+  :members:
+  :inherited-members:
+  :undoc-members:
+
+.. autoclass :: flint.nmod_mpoly
+  :members:
+  :inherited-members:
+  :undoc-members:
+
+.. autoclass :: flint.nmod_mpoly_vec
+  :members:
+  :inherited-members:
+  :undoc-members:
+

src/flint/flint_base/flint_base.pxd

@@ -23,6 +23,8 @@ cdef class flint_mpoly(flint_elem):
     cdef _mul_mpoly_(self, other)
 
     cdef _divmod_mpoly_(self, other)
+    cdef _truediv_scalar_(self, other)
+    cdef _divexact_scalar_(self, other)
     cdef _floordiv_mpoly_(self, other)
     cdef _truediv_mpoly_(self, other)
     cdef _mod_mpoly_(self, other)

src/flint/flint_base/flint_base.pyx

@@ -229,7 +229,7 @@ cdef class flint_poly(flint_elem):
         integer root and *m* is the multiplicity of the root.
 
         To compute complex roots of a polynomial, instead use
-        the `.complex_roots()` method, which is available on
+        the ``.complex_roots()`` method, which is available on
         certain polynomial rings.
 
             >>> from flint import fmpz_poly
@@ -322,9 +322,9 @@ cdef class flint_mpoly_context(flint_elem):
     @staticmethod
     def create_variable_names(slong nvars, names: str):
         """
-        Create a tuple of variable names based on the comma separated `names` string.
+        Create a tuple of variable names based on the comma separated ``names`` string.
 
-        If `names` contains a single value, and `nvars` > 1, then the variables are numbered, e.g.
+        If ``names`` contains a single value, and ``nvars`` > 1, then the variables are numbered, e.g.
 
             >>> flint_mpoly_context.create_variable_names(3, "x")
             ('x0', 'x1', 'x2')
@@ -344,24 +344,24 @@ cdef class flint_mpoly_context(flint_elem):
         Create a key for the context cache via the number of variables, the ordering, and
         either a variable name string, or a tuple of variable names.
         """
-        # A type hint of `ordering: Ordering` results in the error "TypeError: an integer is required" if a Ordering
+        # A type hint of ``ordering: Ordering`` results in the error "TypeError: an integer is required" if a Ordering
         # object is not provided. This is pretty obtuse so we check its type ourselves
         if not isinstance(ordering, Ordering):
-            raise TypeError(f"`ordering` ('{ordering}') is not an instance of flint.Ordering")
+            raise TypeError(f"'ordering' ('{ordering}') is not an instance of flint.Ordering")
 
         if nametup is not None:
             key = nvars, ordering, nametup
         elif nametup is None and names is not None:
             key = nvars, ordering, cls.create_variable_names(nvars, names)
         else:
-            raise ValueError("must provide either `names` or `nametup`")
+            raise ValueError("must provide either 'names' or 'nametup'")
         return key
 
     @classmethod
     def get_context(cls, *args, **kwargs):
         """
-        Retrieve a context via the number of variables, `nvars`, the ordering, `ordering`, and either a variable
-        name string, `names`, or a tuple of variable names, `nametup`.
+        Retrieve a context via the number of variables, ``nvars``, the ordering, ``ordering``, and either a variable
+        name string, ``names``, or a tuple of variable names, ``nametup``.
         """
         key = cls.create_context_key(*args, **kwargs)
 
@@ -391,6 +391,24 @@ cdef class flint_mpoly_context(flint_elem):
         elif other is not self:
             raise IncompatibleContextError(f"{other} is not {self}")
 
+    def term(self, coeff = None, exp_vec = None):
+        """
+        Create a monomial from a coefficient and exponent vector. ``coeff`` defaults
+        to ``1``. ``exp_vec``` defaults to ``(0,) * self.nvars()```.
+
+            >>> from flint import fmpz_mpoly_ctx, Ordering
+            >>> ctx = fmpz_mpoly_ctx.get_context(2, Ordering.lex, 'x')
+            >>> ctx.term(coeff=5, exp_vec=(2, 3))
+            5*x0^2*x1^3
+            >>> ctx.term()
+            1
+        """
+        if coeff is None:
+            coeff = 1
+        if exp_vec is None:
+            exp_vec = (0,) * self.nvars()
+        return self.from_dict({tuple(exp_vec): coeff})
+
 
 cdef class flint_mpoly(flint_elem):
     """
@@ -405,7 +423,7 @@ cdef class flint_mpoly(flint_elem):
 
     def _division_check(self, other):
         if not other:
-            raise ZeroDivisionError("nmod_mpoly division by zero")
+            raise ZeroDivisionError(f"{self.__class__.__name__} division by zero")
 
     cdef _add_scalar_(self, other):
         return NotImplemented
@@ -431,6 +449,12 @@ cdef class flint_mpoly(flint_elem):
     cdef _floordiv_mpoly_(self, other):
         return NotImplemented
 
+    cdef _truediv_scalar_(self, other):
+        return NotImplemented
+
+    cdef _divexact_scalar_(self, other):
+        return NotImplemented
+
     cdef _truediv_mpoly_(self, other):
         return NotImplemented
 
@@ -589,8 +613,12 @@ cdef class flint_mpoly(flint_elem):
         if other is NotImplemented:
             return NotImplemented
 
-        other = self.context().scalar_as_mpoly(other)
         self._division_check(other)
+        res = self._truediv_scalar_(other)
+        if res is not NotImplemented:
+            return res
+
+        other = self.context().scalar_as_mpoly(other)
         return self._truediv_mpoly_(other)
 
     def __rtruediv__(self, other):
@@ -725,7 +753,7 @@ cdef class flint_mpoly(flint_elem):
 
     def __contains__(self, x):
         """
-        Returns True if `self` contains a term with exponent vector `x` and a non-zero coefficient.
+        Returns True if ``self`` contains a term with exponent vector ``x`` and a non-zero coefficient.
 
             >>> from flint import fmpq_mpoly_ctx, Ordering
             >>> ctx = fmpq_mpoly_ctx.get_context(2, Ordering.lex, 'x')
@@ -829,7 +857,7 @@ cdef class flint_mat(flint_elem):
 
 cdef ordering_t ordering_py_to_c(ordering):  # Cython does not like an "Ordering" type hint here
     if not isinstance(ordering, Ordering):
-        raise TypeError(f"`ordering` ('{ordering}') is not an instance of flint.Ordering")
+        raise TypeError(f"'ordering' ('{ordering}') is not an instance of flint.Ordering")
 
     if ordering == Ordering.lex:
         return ordering_t.ORD_LEX

src/flint/flintlib/types/nmod.pxd

@@ -13,9 +13,6 @@ cdef extern from "flint/nmod_types.h":
 
     ctypedef nmod_mat_struct nmod_mat_t[1]
 
-    # XXX: Undocumented function:
-    int nmod_mat_is_square(const nmod_mat_t mat)
-
     # Macros:
     ulong nmod_mat_entry(nmod_mat_t mat, slong i, slong j)
 

src/flint/flintlib/types/undocumented.pxd

@@ -0,0 +1,12 @@
+from flint.flintlib.types.nmod cimport nmod_mat_t
+
+from flint.flintlib.types.flint cimport fmpz_struct
+from flint.flintlib.types.nmod cimport nmod_mpoly_ctx_t, nmod_mpoly_t
+
+cdef extern from "flint/nmod_types.h":
+    int nmod_mat_is_square(const nmod_mat_t mat)
+
+cdef extern from "flint/nmod_mpoly.h":
+    void nmod_mpoly_deflation(fmpz_struct * shift, fmpz_struct * stride, const nmod_mpoly_t A, const nmod_mpoly_ctx_t ctx)
+    void nmod_mpoly_deflate(nmod_mpoly_t A, const nmod_mpoly_t B, const fmpz_struct * shift, const fmpz_struct * stride, const nmod_mpoly_ctx_t ctx)
+    void nmod_mpoly_inflate(nmod_mpoly_t A, const nmod_mpoly_t B, const fmpz_struct * shift, const fmpz_struct * stride, const nmod_mpoly_ctx_t ctx)

src/flint/test/__main__.py

@@ -11,6 +11,7 @@
 
 import flint
 from flint.test.test_all import all_tests
+from flint.test.test_docstrings import find_doctests
 
 
 def run_tests(verbose=None):
@@ -48,54 +49,18 @@ def run_tests(verbose=None):
     return failed, total
 
 
-def run_doctests(verbose=None):
-    """Run the python-flint doctests"""
-    # Here verbose=True shows a lot of output.
-    modules = [flint.pyflint,
-               flint.flint_base.flint_base,
-               flint.flint_base.flint_context,
-               flint.types.fmpz,
-               flint.types.fmpz_poly,
-               flint.types.fmpz_mat,
-               flint.types.fmpz_mpoly,
-               flint.types.fmpz_series,
-               flint.types.fmpz_mod,
-               flint.types.fmpz_mod_poly,
-               flint.types.fmpz_mod_mat,
-               flint.types.fmpq,
-               flint.types.fmpq_poly,
-               flint.types.fmpq_mat,
-               flint.types.fmpq_mpoly,
-               flint.types.fmpq_series,
-               flint.types.nmod,
-               flint.types.nmod_poly,
-               flint.types.nmod_mat,
-               flint.types.nmod_series,
-               flint.types.fq_default,
-               flint.types.fq_default_poly,
-               flint.types.arf,
-               flint.types.arb,
-               flint.types.arb_poly,
-               flint.types.arb_mat,
-               flint.types.arb_series,
-               flint.types.acb,
-               flint.types.acb_poly,
-               flint.types.acb_mat,
-               flint.types.acb_series,
-               flint.types.dirichlet,
-               flint.functions.showgood]
-    try:
-        from flint.types import acb_theta
-        modules.append(acb_theta)
-    except ImportError:
-        pass
-
-    results = []
-    for x in modules:
-        if verbose:
-            print(f" {x.__name__}")
-        results.append(doctest.testmod(x))
-    return tuple(sum(res) for res in zip(*results))
+def run_doctests(tests, verbose=False):
+    runner = doctest.DocTestRunner()
+    for module, test_set in tests:
+        if test_set:
+            print(f"{module}...", end="" if not verbose else "\n", flush=True)
+            for test in test_set:
+                if verbose:
+                    print("\tTesting:", test.name)
+                runner.run(test)
+            print("OK")
+
+    return runner.summarize()
 
 
 def run_all_tests(tests=True, doctests=True, verbose=None):
@@ -108,7 +73,7 @@ def run_all_tests(tests=True, doctests=True, verbose=None):
 
     if doctests:
         print("Running doctests...")
-        d_failed, d_total = run_doctests(verbose=verbose)
+        d_failed, d_total = run_doctests(find_doctests(flint), verbose=verbose)
 
     if tests:
         if t_failed: