gh-36581: `sage/stats/distributions`: Implement non-spherical Gaussian sampling over lattices
    
I implemented non-spherical Gaussian sampling over lattices. It's useful
for cryptography.

~~There are some TODOs that I hope to fix as soon as possible before
merging, hence it's in draft status.~~ Done!

There are some missing features e.g. when $B$ is not full-rank, or
computing the normalisation factor for non-integral lattices, etc. But
those should be easy to fix.

Suggestions to variable naming would be appreciated too :)

TODO:
- [x] Finish writing doctest
- [x] Support taking a basis $B$ and compute $\Sigma = BB^T$ instead.
- [x] Allow setting $c$ dynamically.
- [x] Fix merge conflicts :(
- [x] Fix linting issues, coding style issues, ...
    
URL: #36581
Reported by: grhkm21
Reviewer(s): grhkm21, Travis Scrimshaw

Author: Release Manager

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

@@ -5137,6 +5137,11 @@ REFERENCES:
              small Schroeder paths*, JCTA 125 (2014), 357-378,
              :doi:`10.1016/j.jcta.2014.04.002`
 
+.. [Pei2010] Peikert, C. (2010). An Efficient and Parallel Gaussian Sampler for
+             Lattices. In: Rabin, T. (eds) Advances in Cryptology – CRYPTO 2010.
+             CRYPTO 2010. Lecture Notes in Computer Science, vol 6223. Springer,
+             Berlin, Heidelberg. :doi:`10.1007/978-3-642-14623-7_5`
+
 .. [Pen2012] \R. Pendavingh, On the evaluation at `(-i, i)` of the
              Tutte polynomial of a binary matroid. Preprint:
              :arxiv:`1203.0910`

src/sage/stats/all.py

@@ -1,3 +1,4 @@
+import sage.stats.distributions.catalog as distributions
 
 from .r import ttest
 from .basic_stats import (mean, mode, std, variance, median, moving_average)

src/sage/stats/distributions/all.py

@@ -0,0 +1,6 @@
+# We lazy_import the following modules since they import numpy which
+# slows down sage startup
+from sage.misc.lazy_import import lazy_import
+lazy_import("sage.stats.distributions.discrete_gaussian_integer", ["DiscreteGaussianDistributionIntegerSampler"])
+lazy_import("sage.stats.distributions.discrete_gaussian_lattice", ["DiscreteGaussianDistributionLatticeSampler"])
+lazy_import("sage.stats.distributions.discrete_gaussian_polynomial", ["DiscreteGaussianDistributionPolynomialSampler"])

src/sage/stats/distributions/catalog.py

@@ -0,0 +1,34 @@
+r"""
+Index of distributions
+
+This catalogue includes the samplers for statistical distributions listed below.
+
+Let ``<tab>`` indicate pressing the :kbd:`Tab` key.  So begin by typing
+``algebras.<tab>`` to the see the currently implemented named algebras.
+
+- :class:`distributions.discrete_gaussian_integer.DiscreteGaussianDistributionIntegerSampler
+  <sage.stats.distributions.discrete_gaussian_integer.DiscreteGaussianDistributionIntegerSampler>`
+- :class:`distributions.discrete_gaussian_lattice.DiscreteGaussianDistributionLatticeSampler
+  <sage.stats.distributions.discrete_gaussian_lattice.DiscreteGaussianDistributionLatticeSampler>`
+- :class:`distributions.discrete_gaussian_polynomial.DiscreteGaussianDistributionPolynomialSampler
+  <sage.stats.distributions.discrete_gaussian_polynomial.DiscreteGaussianDistributionPolynomialSampler>`
+
+To import these names into the global namespace, use::
+
+    sage: from sage.stats.distributions.catalog import *
+
+"""
+#*****************************************************************************
+#       Copyright (C) 2024 Gareth Ma <[email protected]>
+#
+#  Distributed under the terms of the GNU General Public License (GPL),
+#  version 2 or later (at your preference).
+#
+#                  http://www.gnu.org/licenses/
+#*****************************************************************************
+
+from sage.misc.lazy_import import lazy_import
+lazy_import("sage.stats.distributions.discrete_gaussian_integer", ["DiscreteGaussianDistributionIntegerSampler"])
+lazy_import("sage.stats.distributions.discrete_gaussian_lattice", ["DiscreteGaussianDistributionLatticeSampler"])
+lazy_import("sage.stats.distributions.discrete_gaussian_polynomial", ["DiscreteGaussianDistributionPolynomialSampler"])
+del lazy_import