add class groups of binary quadratic forms

src/doc/en/reference/quadratic_forms/index.rst

@@ -6,6 +6,7 @@ Quadratic Forms
 
    sage/quadratic_forms/quadratic_form
    sage/quadratic_forms/binary_qf
+   sage/quadratic_forms/bqf_class_group
    sage/quadratic_forms/constructions
    sage/quadratic_forms/random_quadraticform
    sage/quadratic_forms/special_values

src/sage/quadratic_forms/all.py

@@ -1,5 +1,7 @@
 from .binary_qf import BinaryQF, BinaryQF_reduced_representatives
 
+from .bqf_class_group import BQFClassGroup
+
 from .ternary_qf import TernaryQF, find_all_ternary_qf_by_level_disc, find_a_ternary_qf_by_level_disc
 
 from .quadratic_form import QuadraticForm, DiagonalQuadraticForm, quadratic_form_from_invariants

src/sage/quadratic_forms/binary_qf.py

@@ -177,6 +177,102 @@ def _pari_init_(self):
         """
         return 'Qfb(%s,%s,%s)' % (self._a, self._b, self._c)
 
+    @staticmethod
+    def principal(D):
+        r"""
+        Return the principal binary quadratic form of the given discriminant.
+
+        EXAMPLES::
+
+            sage: BinaryQF.principal(8)
+            x^2 - 2*y^2
+            sage: BinaryQF.principal(5)
+            x^2 + x*y - y^2
+            sage: BinaryQF.principal(4)
+            x^2 - y^2
+            sage: BinaryQF.principal(1)
+            x^2 + x*y
+            sage: BinaryQF.principal(-3)
+            x^2 + x*y + y^2
+            sage: BinaryQF.principal(-4)
+            x^2 + y^2
+            sage: BinaryQF.principal(-7)
+            x^2 + x*y + 2*y^2
+            sage: BinaryQF.principal(-8)
+            x^2 + 2*y^2
+
+        TESTS:
+
+        Some randomized testing::
+
+            sage: D = 1
+            sage: while D.is_square():
+            ....:     D = choice((-4,+4)) * randrange(9999) + randrange(2)
+            sage: Q = BinaryQF.principal(D)
+            sage: Q.discriminant() == D     # correct discriminant
+            True
+            sage: (Q*Q).is_equivalent(Q)    # idempotent (hence identity)
+            True
+        """
+        D = ZZ(D)
+        D4 = D % 4
+        if D4 not in (0,1):
+            raise ValueError('discriminant must be congruent to 0 or 1 modulo 4')
+        a, b, c = 1, D4, (D4-D)//4
+        return BinaryQF([1, D4, (D4-D)//4])
+
+    @staticmethod
+    def random(D):
+        r"""
+        Return a somewhat random primitive binary quadratic form of the
+        given discriminant.
+
+        (In the case `D < 0`, only positive definite forms are returned.)
+
+        .. NOTE::
+
+            No guarantees are being made about the distribution of forms
+            sampled by this function.
+
+        EXAMPLES::
+
+            sage: BinaryQF.random(5)    # random
+            448219*x^2 - 597179*x*y + 198911*y^2
+            sage: BinaryQF.random(-7)   # random
+            10007*x^2 + 10107*x*y + 2552*y^2
+
+        TESTS::
+
+            sage: D = choice((-4,+4)) * randrange(9999) + randrange(2) or 1
+            sage: Q = BinaryQF.random(D)
+            sage: Q.discriminant() == D
+            True
+            sage: Q.is_primitive()
+            True
+            sage: Q.is_indefinite() or Q.is_positive_definite()
+            True
+        """
+        D = ZZ(D)
+        D4 = D % 4
+        if D4 not in (0,1):
+            raise ValueError('discriminant must be congruent to 0 or 1 modulo 4')
+
+        from sage.misc.prandom import randrange
+        from sage.misc.misc_c import prod
+        from sage.matrix.special import random_matrix
+        B = (D.abs() or 1) * 99  # kind of arbitrary
+        while True:
+            b = randrange(D4, B, 2)
+            ac = (b**2 - D) // 4
+            if ac:
+                break
+        a = prod(l**randrange(e+1) for l,e in ac.factor())
+        a = a.prime_to_m_part(gcd([a, b, ac//a]))
+        c = ac // a
+        M = random_matrix(ZZ, 2, 2, 'unimodular')
+        M.rescale_row(0, (-1)**randrange(2))
+        return BinaryQF([a, b, c]) * M
+
     def __mul__(self, right):
         """
         Gauss composition or right action by a 2x2 integer matrix.
@@ -1589,14 +1685,15 @@ def solve_integer(self, n, *, algorithm="general"):
 
         ::
 
-            sage: Qs = BinaryQF_reduced_representatives(-23, primitive_only=True)       # optional - sage.libs.pari
-            sage: Qs                                                                    # optional - sage.libs.pari
+            sage: # needs sage.libs.pari
+            sage: Qs = BinaryQF_reduced_representatives(-23, primitive_only=True)
+            sage: Qs
             [x^2 + x*y + 6*y^2, 2*x^2 - x*y + 3*y^2, 2*x^2 + x*y + 3*y^2]
-            sage: [Q.solve_integer(3) for Q in Qs]                                      # optional - sage.libs.pari
+            sage: [Q.solve_integer(3) for Q in Qs]
             [None, (0, -1), (0, -1)]
-            sage: [Q.solve_integer(5) for Q in Qs]                                      # optional - sage.libs.pari
+            sage: [Q.solve_integer(5) for Q in Qs]
             [None, None, None]
-            sage: [Q.solve_integer(6) for Q in Qs]                                      # optional - sage.libs.pari
+            sage: [Q.solve_integer(6) for Q in Qs]
             [(1, -1), (1, -1), (-1, -1)]
 
         TESTS:
@@ -1695,6 +1792,23 @@ def solve_integer(self, n, *, algorithm="general"):
         sol = self.__pari__().qfbsolve(n, flag)
         return tuple(map(ZZ, sol)) if sol else None
 
+    def form_class(self):
+        r"""
+        Return the class of this form modulo equivalence.
+
+        EXAMPLES::
+
+            sage: F = BinaryQF([3, -16, 161])
+            sage: cl = F.form_class(); cl
+            Class of 3*x^2 + 2*x*y + 140*y^2
+            sage: cl.parent()
+            Form Class Group of Discriminant -1676
+            sage: cl.parent() is BQFClassGroup(-4*419)
+            True
+        """
+        from sage.quadratic_forms.bqf_class_group import BQFClassGroup
+        return BQFClassGroup(self.discriminant())(self)
+
 
 def BinaryQF_reduced_representatives(D, primitive_only=False, proper=True):
     r"""