From a7cdb80a6e350e217f12622aba3469220660222b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5vard=20Damm-Johnsen?= Date: Wed, 11 Oct 2023 12:13:14 +0200 Subject: [PATCH 1/3] Updated formatting in qfb.rst, added references to references.rst --- doc/source/qfb.rst | 95 +++++++++++++++++++-------------------- doc/source/references.rst | 10 ++++- 2 files changed, 54 insertions(+), 51 deletions(-) diff --git a/doc/source/qfb.rst b/doc/source/qfb.rst index 98d2fa1df9..9f698d084e 100644 --- a/doc/source/qfb.rst +++ b/doc/source/qfb.rst @@ -6,23 +6,32 @@ Authors: * William Hart +* Håvard Damm-Johnsen + + +Introduction +-------------------------------------------------------------------------------- + +This module contains functionality for creating, listing and reducing binary quadratic forms. A ``qfb`` struct consists of three ``fmpz_t`` s, `a`, `b` and `c`, and basic algorithms for operating on forms are described below. + +Currently, the code only works for definite binary quadratic forms. Memory management ---------------------------------------------------------------------------------------- .. function:: void qfb_init(qfb_t q) - Initialise a \code{qfb_t} `q` for use. + Initialise a ``qfb_t`` `q` for use. .. function:: void qfb_clear(qfb_t q) - Clear a \code{qfb_t} after use. This releases any memory allocated for + Clear a ``qfb_t`` after use. This releases any memory allocated for `q` back to flint. .. function:: void qfb_array_clear(qfb ** forms, slong num) - Clean up an array of \code{qfb} structs allocated by a qfb function. - The parameter \code{num} must be set to the length of the array. + Clean up an array of ``qfb`` structs allocated by a qfb function. + The parameter ``num`` must be set to the length of the array. Hash table ---------------------------------------------------------------------------------------- @@ -37,18 +46,18 @@ Hash table .. function:: void qfb_hash_insert(qfb_hash_t * qhash, qfb_t q, qfb_t q2, slong iter, slong depth) - Insert the binary quadratic form \code{q} into the given hash table - of size `2^{depth}` in the field \code{q} of the hash structure. - Also store the second binary quadratic form \code{q2} (if not - \code{NULL}) in the similarly named field and \code{iter} in the + Insert the binary quadratic form ``q`` into the given hash table + of size `2^{depth}` in the field ``q`` of the hash structure. + Also store the second binary quadratic form ``q2`` (if not + ``NULL``) in the similarly named field and ``iter`` in the similarly named field of the hash structure. .. function:: slong qfb_hash_find(qfb_hash_t * qhash, qfb_t q, slong depth) Search for the given binary quadratic form or its inverse in the given hash table of size `2^{depth}`. If it is found, return - the index in the table (which is an array of \code{qfb_hash_t} - structs, otherwise return \code{-1L}. + the index in the table (which is an array of ``qfb_hash_t`` + structs, otherwise return ``-1L``. Basic manipulation ---------------------------------------------------------------------------------------- @@ -90,32 +99,29 @@ Computing with forms .. function:: int qfb_is_reduced(qfb_t r) Returns `1` if `q` is a reduced binary quadratic form. Otherwise returns - `0`. + `0`. .. function:: slong qfb_reduced_forms(qfb ** forms, slong d) Given a discriminant `d` (negative for negative definite forms), compute all the reduced binary quadratic forms of that discriminant. The function - allocates space for these and returns it in the variable \code{forms} + allocates space for these and returns it in the variable ``forms`` (the user is responsible for cleaning this up by a single call to - \code{qfb_array_clear} on \code{forms}, after use. The function returns + ``qfb_array_clear`` on ``forms``, after use. The function returns the number of forms generated (the form class number). The forms are - stored in an array of \code{qfb} structs, which contain fields - \code{a, b, c} corresponding to forms `(a, b, c)`. + stored in an array of ``qfb`` structs, which contain fields + ``a, b, c`` corresponding to forms `(a, b, c)`. .. function:: slong qfb_reduced_forms_large(qfb ** forms, slong d) As for ``qfb_reduced_forms``. However, for small `|d|` it requires fewer primes to be computed at a small cost in speed. It is called - automatically by \code{qfb_reduced_forms} for large `|d|` so that + automatically by ``qfb_reduced_forms`` for large `|d|` so that ``flint_primes`` is not exhausted. .. function:: void qfb_nucomp(qfb_t r, const qfb_t f, const qfb_t g, fmpz_t D, fmpz_t L) - Shanks' NUCOMP as described in~\citep{JacvdP} - - % Computational aspects of NUCOMP", Michael J. Jacobson Jr., - % Alfred J. van der Poorten, ANTS 2002, LNCS 2369, pp. 120--133. + Shanks' NUCOMP as described in [JvdP2002]_. Computes the near reduced composition of forms `f` and `g` given `L = \lfloor |D|^{1/4} \rfloor` where `D` is the common discriminant of @@ -125,20 +131,20 @@ Computing with forms .. function:: void qfb_nudupl(qfb_t r, const qfb_t f, fmpz_t D, fmpz_t L) - As for \code{nucomp} except that the form `f` is composed with itself. + As for ``nucomp`` except that the form `f` is composed with itself. We require that `f` is a primitive form. .. function:: void qfb_pow_ui(qfb_t r, qfb_t f, fmpz_t D, ulong exp) Compute the near reduced form `r` which is the result of composing the - principal form (identity) with `f` \code{exp} times. + principal form (identity) with `f` ``exp`` times. We require `D` to be set to the discriminant of `f` and that `f` is a primitive form. .. function:: void qfb_pow(qfb_t r, qfb_t f, fmpz_t D, fmpz_t exp) - As per \code{qfb_pow_ui}. + As per ``qfb_pow_ui``. .. function:: void qfb_inverse(qfb_t r, qfb_t f) @@ -167,50 +173,41 @@ Computing with forms .. function:: int qfb_exponent_element(fmpz_t exponent, qfb_t f, fmpz_t n, ulong B1, ulong B2_sqrt) Find the exponent of the element `f` in the form class group of forms of - discriminant `n`, doing a stage `1` with primes up to at least \code{B1} + discriminant `n`, doing a stage `1` with primes up to at least ``B1`` and a stage `2` for a single large prime up to at least the square of - \code{B2}. If the function fails to find the exponent it returns `0`, - otherwise the function returns `1` and \code{exponent} is set to the + ``B2``. If the function fails to find the exponent it returns `0`, + otherwise the function returns `1` and ``exponent`` is set to the exponent of `f`, i.e. the minimum power of `f` which gives the identity. - It is assumed that the form `f` is reduced. We require that \code{iters} - is a power of `2` and that \code{iters}` >= 1024`. + It is assumed that the form `f` is reduced. We require that ``iters`` + is a power of `2` and that ``iters``` >= 1024`. The function performs a stage `2` which stores up to `4\times` - \code{iters} binary quadratic forms, and `12\times` \code{iters} - additional limbs of data in a hash table, where \code{iters} is the - square root of \code{B2}. + ``iters`` binary quadratic forms, and `12\times` ``iters`` + additional limbs of data in a hash table, where ``iters`` is the + square root of ``B2``. .. function:: int qfb_exponent(fmpz_t exponent, fmpz_t n, ulong B1, ulong B2_sqrt, slong c) Compute the exponent of the class group of discriminant `n`, doing a - stage `1` with primes up to at least \code{B1} and a stage `2` for a - single large prime up to at least the square of \code{B2_sqrt}, and with + stage `1` with primes up to at least ``B1`` and a stage `2` for a + single large prime up to at least the square of ``B2_sqrt``, and with probability at least `1 - 2^{-c}`. If the prime limits are exhausted without finding the exponent, the function returns `0`, otherwise it - returns `1` and \code{exponent} is set to the computed exponent, i.e. the + returns `1` and ``exponent`` is set to the computed exponent, i.e. the minimum power which every element of the class group has to be raised to give the identity. The function performs a stage `2` which stores up to `4\times` - \code{iters} binary quadratic forms, and `12\times` \code{iters} - additional limbs of data in a hash table, where \code{iters} is the - square root of \code{B2}. + ``iters`` binary quadratic forms, and `12\times` ``iters`` + additional limbs of data in a hash table, where ``iters`` is the + square root of ``B2``. - We use algorithm 8.1 of~\citep{SuthThesis} - - % "Order Computations in Generic Groups", Andrew Sutherland, - % MIT Thesis 2007. - % http://groups.csail.mit.edu/cis/theses/sutherland-phd.pdf + We use algorithm 8.1 of [Sut2007]_. .. function:: int qfb_exponent_grh(fmpz_t exponent, fmpz_t n, ulong B1, ulong B2_sqrt) - As per \code{qfb_exponent} except that the bound \code{c} is + As per ``qfb_exponent`` except that the bound ``c`` is automatically generated such that the exponent it guaranteed to be correct, if found, assuming the GRH, namely that the class group is - generated by primes less than `6\log^2(|n|)` as per~\citep{BuchDull1992} - - % "Distributed Class Group Computation", Johannes Buchmann, Stephan - % D\"{u}llman, Informatik 1 (1992), pp. 69--79. - - + generated by primes less than `6\log^2(|n|)` as per [BD1992]_. diff --git a/doc/source/references.rst b/doc/source/references.rst index ef71e43123..9e7ccf702d 100644 --- a/doc/source/references.rst +++ b/doc/source/references.rst @@ -21,6 +21,8 @@ References .. [BBK2014] \D. H. Bailey, J. M. Borwein and A. D. Kaiser. "Automated simplification of large symbolic expressions". Journal of Symbolic Computation Volume 60, January 2014, Pages 120-136. https://doi.org/10.1016/j.jsc.2013.09.001 +.. [BD1992] \D. Buchmann and S. Düllmann. "Distributed class group computation." Informatik: Festschrift zum 60. Geburtstag von Günter Hotz (1992): 69-79. + .. [BF2020] \F. Beukers and J. Forsgård. "Gamma-evaluations of hypergeometric series". Preprint, 2020. https://arxiv.org/abs/2004.08117 .. [BFSS2006] \A. Bostan, P. Flajolet, B. Salvy and É. Schost. "Fast computation of special resultants". Journal of Symbolic Computation, 41(1):1–29, January 2006. https://doi.org/10.1016/j.jsc.2005.07.001 @@ -28,7 +30,7 @@ References .. [BJ2013] \R. P. Brent and F. Johansson, "A bound for the error term in the Brent-McMillan algorithm", preprint (2013), http://arxiv.org/abs/1312.0039 .. [BM1980] \R. P. Brent and E. M. McMillan, "Some new algorithms for high-precision computation of Euler's constant", Mathematics of Computation 34 (1980) 305-312. - + .. [BZ1992] \J. Borwein and I. Zucker, "Fast evaluation of the gamma function for small rational fractions using complete elliptic integrals of the first kind", IMA Journal of Numerical Analysis 12 (1992) 519-526 .. [BZ2011] \R. P. Brent and P. Zimmermann, *Modern Computer Arithmetic*, Cambridge University Press (2011), http://www.loria.fr/~zimmerma/mca/pub226.html @@ -167,6 +169,8 @@ References .. [Joh2018b] \F. Johansson and others, "mpmath: a Python library for arbitrary-precision floating-point arithmetic (version 1.1.0)", December 2018. http://mpmath.org/ +.. [JvdP2002] \M. J. Jacobson Jr. and A. J. van der Poorten. "Computational aspects of NUCOMP." In International Algorithmic Number Theory Symposium, pp. 120-133. Berlin, Heidelberg: Springer Berlin Heidelberg, 2002. + .. [Kahan1991] \Kahan, William: Computing a Real Cube Root. https://csclub.uwaterloo.ca/~pbarfuss/qbrt.pdf .. [KanBac1979] \Kannan, R. and Bachem, A. : Polynomial algorithms for computing and the Smith and Hermite normal forms of an integer matrix, SIAM J. Computation vol. 9 (1979) 499--507 @@ -257,6 +261,8 @@ References .. [Str2012] \A. Strzebonski. "Real root isolation for exp-log-arctan functions". Journal of Symbolic Computation 47 (2012) 282–314. https://doi.org/10.1016/j.jsc.2011.11.004 +.. [Sut2007] \A. V. Sutherland. "Order computations in generic groups." PhD diss., Massachusetts Institute of Technology, 2007. + .. [Tak2000] \D. Takahashi, "A fast algorithm for computing large Fibonacci numbers", Information Processing Letters 75 (2000) 243-246, http://www.ii.uni.wroc.pl/~lorys/IPL/article75-6-1.pdf .. [ThullYap1990] \Thull, K. and Yap, C. : A Unified Approach to HGCD Algorithms for Polynomials and Integers, (1990) @@ -285,5 +291,5 @@ References .. [vdH2006] \J. van der Hoeven, "Computations with effective real numbers". Theoretical Computer Science, Volume 351, Issue 1, 14 February 2006, Pages 52-60. https://doi.org/10.1016/j.tcs.2005.09.060 -All referenced works: [AbbottBronsteinMulders1999]_, [Apostol1997]_, [Ari2011]_, [Ari2012]_, [Arn2010]_, [ArnoldMonagan2011]_, [BBC1997]_, [BBC2000]_, [BBK2014]_, [BF2020]_, [BFSS2006]_, [BJ2013]_, [BM1980]_, [BZ1992]_, [BZ2011]_, [BaiWag1980]_, [BerTas2010]_, [Blo2009]_, [Bodrato2010]_, [Boe2020]_, [Bog2012]_, [Bor1987]_, [Bor2000]_, [Bre1978]_, [Bre1979]_, [Bre2010]_, [BrentKung1978]_, [BuhlerCrandallSompolski1992]_, [CGHJK1996]_, [CP2005]_, [Car1995]_, [Car2004]_, [Chen2003]_, [Cho1999]_, [Coh1996]_, [Coh2000]_, [Col1971]_, [CraPom2005]_, [DYF1999]_, [DelegliseNicolasZimmermann2009]_, [DomKanTro1987]_, [Dup2006]_, [Dus1999]_, [EHJ2016]_, [EM2004]_, [Fie2007]_, [FieHof2014]_, [Fil1992]_, [GCL1992]_, [GG2003]_, [GS2003]_, [GVL1996]_, [Gas2018]_, [GowWag2008]_, [GraMol2010]_, [HM2017]_, [HS1967]_, [HZ2004]_, [HanZim2004]_, [Har2010]_, [Har2012]_, [Har2015]_, [Har2018]_, [Hart2010]_, [Hoe2001]_, [Hoe2009]_, [Iliopoulos1989]_, [JB2018]_, [JM2018]_, [JR1999]_, [Joh2012]_, [Joh2013]_, [Joh2014a]_, [Joh2014b]_, [Joh2014c]_, [Joh2015]_, [Joh2016]_, [Joh2017]_, [Joh2017a]_, [Joh2017b]_, [Joh2018a]_, [Joh2018b]_, [Kahan1991]_, [KanBac1979]_, [Kar1998]_, [Knu1997]_, [Kob2010]_, [Kri2013]_, [Leh1970]_, [LukPatWil1996]_, [MP2006]_, [MPFR2012]_, [MasRob1996]_, [Mic2007]_, [Miy2010]_, [Mos1971]_, [Mul2000]_, [NIST2012]_, [NakTurWil1997]_, [Olv1997]_, [PP2010]_, [PS1973]_, [PS1991]_, [Paterson1973]_, [PernetStein2010]_, [Pet1999]_, [Pla2011]_, [Pla2017]_, [RF1994]_, [Rad1973]_, [Rademacher1937]_, [Ric1992]_, [Ric1995]_, [Ric1997]_, [Ric2007]_, [Ric2009]_, [RosSch1962]_, [Rum2010]_, [Smi2001]_, [SorWeb2016]_, [Ste2002]_, [Ste2010]_, [Stehle2010]_, [Stein2007]_, [StoMul1998]_, [Str1997]_, [Str2012]_, [Tak2000]_, [ThullYap1990]_, [Tre2008]_, [Tru2011]_, [Tru2014]_, [Tur1953]_, [Villard2007]_, [WaktinsZeitlin1993]_, [Wei2000]_, [Whiteman1956]_, [Zip1985]_, [vHP2012]_, [vdH1995]_, [vdH2006]_ +All referenced works: [AbbottBronsteinMulders1999]_, [Apostol1997]_, [Ari2011]_, [Ari2012]_, [Arn2010]_, [ArnoldMonagan2011]_, [BBC1997]_, [BBC2000]_, [BBK2014]_, [BD1992]_, [BF2020]_, [BFSS2006]_, [BJ2013]_, [BM1980]_, [BZ1992]_, [BZ2011]_, [BaiWag1980]_, [BerTas2010]_, [Blo2009]_, [Bodrato2010]_, [Boe2020]_, [Bog2012]_, [Bor1987]_, [Bor2000]_, [Bre1978]_, [Bre1979]_, [Bre2010]_, [BrentKung1978]_, [BuhlerCrandallSompolski1992]_, [CGHJK1996]_, [CP2005]_, [Car1995]_, [Car2004]_, [Chen2003]_, [Cho1999]_, [Coh1996]_, [Coh2000]_, [Col1971]_, [CraPom2005]_, [DYF1999]_, [DelegliseNicolasZimmermann2009]_, [DomKanTro1987]_, [Dup2006]_, [Dus1999]_, [EHJ2016]_, [EM2004]_, [Fie2007]_, [FieHof2014]_, [Fil1992]_, [GCL1992]_, [GG2003]_, [GS2003]_, [GVL1996]_, [Gas2018]_, [GowWag2008]_, [GraMol2010]_, [HM2017]_, [HS1967]_, [HZ2004]_, [HanZim2004]_, [Har2010]_, [Har2012]_, [Har2015]_, [Har2018]_, [Hart2010]_, [Hoe2001]_, [Hoe2009]_, [Iliopoulos1989]_, [JB2018]_, [JM2018]_, [JR1999]_, [Joh2012]_, [Joh2013]_, [Joh2014a]_, [Joh2014b]_, [Joh2014c]_, [Joh2015]_, [Joh2016]_, [Joh2017]_, [Joh2017a]_, [Joh2017b]_, [Joh2018a]_, [Joh2018b]_, [JvdP2002]_, [Kahan1991]_, [KanBac1979]_, [Kar1998]_, [Knu1997]_, [Kob2010]_, [Kri2013]_, [Leh1970]_, [LukPatWil1996]_, [MP2006]_, [MPFR2012]_, [MasRob1996]_, [Mic2007]_, [Miy2010]_, [Mos1971]_, [Mul2000]_, [NIST2012]_, [NakTurWil1997]_, [Olv1997]_, [PP2010]_, [PS1973]_, [PS1991]_, [Paterson1973]_, [PernetStein2010]_, [Pet1999]_, [Pla2011]_, [Pla2017]_, [RF1994]_, [Rad1973]_, [Rademacher1937]_, [Ric1992]_, [Ric1995]_, [Ric1997]_, [Ric2007]_, [Ric2009]_, [RosSch1962]_, [Rum2010]_, [Smi2001]_, [SorWeb2016]_, [Ste2002]_, [Ste2010]_, [Stehle2010]_, [Stein2007]_, [Sut2007]_, [StoMul1998]_, [Str1997]_, [Str2012]_, [Tak2000]_, [ThullYap1990]_, [Tre2008]_, [Tru2011]_, [Tru2014]_, [Tur1953]_, [Villard2007]_, [WaktinsZeitlin1993]_, [Wei2000]_, [Whiteman1956]_, [Zip1985]_, [vHP2012]_, [vdH1995]_, [vdH2006]_ From e56e4f6abcc303dd93321f23d9802f1214d9200d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5vard=20Damm-Johnsen?= Date: Wed, 11 Oct 2023 14:08:03 +0200 Subject: [PATCH 2/3] Fixed formatting in nf_elem.rst --- doc/source/nf_elem.rst | 130 ++++++++++++++++++++--------------------- doc/source/qfb.rst | 47 +++++++-------- 2 files changed, 89 insertions(+), 88 deletions(-) diff --git a/doc/source/nf_elem.rst b/doc/source/nf_elem.rst index 2cb91d3cda..5726125777 100644 --- a/doc/source/nf_elem.rst +++ b/doc/source/nf_elem.rst @@ -19,7 +19,7 @@ Initialisation .. function:: void nf_elem_init(nf_elem_t a, const nf_t nf) Initialise a number field element to belong to the given number field - \code{nf}. The element is set to zero. + ``nf``. The element is set to zero. .. function:: void nf_elem_clear(nf_elem_t a, const nf_t nf) @@ -28,7 +28,7 @@ Initialisation .. function:: void nf_elem_randtest(nf_elem_t a, flint_rand_t state, mp_bitcnt_t bits, const nf_t nf) - Generate a random number field element `a` in the number field \code{nf} + Generate a random number field element `a` in the number field ``nf`` whose coefficients have up to the given number of bits. .. function:: void nf_elem_canonicalise(nf_elem_t a, const nf_t nf) @@ -39,13 +39,13 @@ Initialisation .. function:: void _nf_elem_reduce(nf_elem_t a, const nf_t nf) Reduce a number field element modulo the defining polynomial. This is used - with functions such as \code{nf_elem_mul_red} which allow reduction to be + with functions such as ``nf_elem_mul_red`` which allow reduction to be delayed. Does not canonicalise. .. function:: void nf_elem_reduce(nf_elem_t a, const nf_t nf) Reduce a number field element modulo the defining polynomial. This is used - with functions such as \code{nf_elem_mul_red} which allow reduction to be + with functions such as ``nf_elem_mul_red`` which allow reduction to be delayed. .. function:: int _nf_elem_invertible_check(nf_elem_t a, const nf_t nf) @@ -55,7 +55,7 @@ Initialisation able to check that a given number field element is invertible modulo the defining polynomial of the number field. This function does precisely this. - If `a` is invertible modulo the defining polynomial of \code{nf} the value + If `a` is invertible modulo the defining polynomial of ``nf`` the value `1` is returned, otherwise `0` is returned. The function is only intended to be used in test code. @@ -77,37 +77,37 @@ Conversion .. function:: void nf_elem_set_fmpq_poly(nf_elem_t a, const fmpq_poly_t pol, const nf_t nf) - Set `a` to the element corresponding to the polynomial \code{pol}. + Set `a` to the element corresponding to the polynomial ``pol``. .. function:: void nf_elem_get_fmpq_poly(fmpq_poly_t pol, const nf_elem_t a, const nf_t nf) - Set \code{pol} to a polynomial corresponding to `a`, reduced modulo the - defining polynomial of \code{nf}. + Set ``pol`` to a polynomial corresponding to `a`, reduced modulo the + defining polynomial of ``nf``. .. function:: void nf_elem_get_nmod_poly_den(nmod_poly_t pol, const nf_elem_t a, const nf_t nf, int den) - Set \code{pol} to the reduction of the polynomial corresponding to the - numerator of `a`. If \code{den == 1}, the result is multiplied by the + Set ``pol`` to the reduction of the polynomial corresponding to the + numerator of `a`. If ``den == 1``, the result is multiplied by the inverse of the denominator of `a`. In this case it is assumed that the reduction of the denominator of `a` is invertible. .. function:: void nf_elem_get_nmod_poly(nmod_poly_t pol, const nf_elem_t a, const nf_t nf) - Set \code{pol} to the reduction of the polynomial corresponding to the + Set ``pol`` to the reduction of the polynomial corresponding to the numerator of `a`. The result is multiplied by the inverse of the denominator of `a`. It is assumed that the reduction of the denominator of `a` is invertible. .. function:: void nf_elem_get_fmpz_mod_poly_den(fmpz_mod_poly_t pol, const nf_elem_t a, const nf_t nf, int den, const fmpz_mod_ctx_t ctx) - Set \code{pol} to the reduction of the polynomial corresponding to the - numerator of `a`. If \code{den == 1}, the result is multiplied by the + Set ``pol`` to the reduction of the polynomial corresponding to the + numerator of `a`. If ``den == 1``, the result is multiplied by the inverse of the denominator of `a`. In this case it is assumed that the reduction of the denominator of `a` is invertible. .. function:: void nf_elem_get_fmpz_mod_poly(fmpz_mod_poly_t pol, const nf_elem_t a, const nf_t nf, const fmpz_mod_ctx_t ctx) - Set \code{pol} to the reduction of the polynomial corresponding to the + Set ``pol`` to the reduction of the polynomial corresponding to the numerator of `a`. The result is multiplied by the inverse of the denominator of `a`. It is assumed that the reduction of the denominator of `a` is invertible. @@ -117,16 +117,16 @@ Basic manipulation .. function:: void nf_elem_set_den(nf_elem_t b, fmpz_t d, const nf_t nf) - Set the denominator of the \code{nf_elem_t b} to the given integer `d`. + Set the denominator of the ``nf_elem_t b`` to the given integer `d`. Assumes `d > 0`. .. function:: void nf_elem_get_den(fmpz_t d, const nf_elem_t b, const nf_t nf) - Set `d` to the denominator of the \code{nf_elem_t b}. + Set `d` to the denominator of the ``nf_elem_t b``. .. function:: void _nf_elem_set_coeff_num_fmpz(nf_elem_t a, slong i, const fmpz_t d, const nf_t nf) - Set the `i`th coefficient of the denominator of `a` to the given integer + Set the `i`-th coefficient of the denominator of `a` to the given integer `d`. Comparison @@ -135,13 +135,13 @@ Comparison .. function:: int _nf_elem_equal(const nf_elem_t a, const nf_elem_t b, const nf_t nf) Return `1` if the given number field elements are equal in the given - number field \code{nf}. This function does \emph{not} assume `a` and `b` + number field ``nf``. This function does \emph{not} assume `a` and `b` are canonicalised. .. function:: int nf_elem_equal(const nf_elem_t a, const nf_elem_t b, const nf_t nf) Return `1` if the given number field elements are equal in the given - number field \code{nf}. This function assumes `a` and `b` \emph{are} + number field ``nf``. This function assumes `a` and `b` \emph{are} canonicalised. .. function:: int nf_elem_is_zero(const nf_elem_t a, const nf_t nf) @@ -159,8 +159,8 @@ I/O .. function:: void nf_elem_print_pretty(const nf_elem_t a, const nf_t nf, const char * var) - Print the given number field element to \code{stdout} using the - null-terminated string \code{var} not equal to \code{"\0"} as the + Print the given number field element to ``stdout`` using the + null-terminated string ``var`` not equal to ``"\0"`` as the name of the primitive element. Arithmetic @@ -194,51 +194,51 @@ Arithmetic .. function:: void _nf_elem_add(nf_elem_t r, const nf_elem_t a, const nf_elem_t b, const nf_t nf) - Add two elements of a number field \code{nf}, i.e. set `r = a + b`. + Add two elements of a number field ``nf``, i.e. set `r = a + b`. Canonicalisation is not performed. .. function:: void nf_elem_add(nf_elem_t r, const nf_elem_t a, const nf_elem_t b, const nf_t nf) - Add two elements of a number field \code{nf}, i.e. set `r = a + b`. + Add two elements of a number field ``nf``, i.e. set `r = a + b`. .. function:: void _nf_elem_sub(nf_elem_t r, const nf_elem_t a, const nf_elem_t b, const nf_t nf) - Subtract two elements of a number field \code{nf}, i.e. set `r = a - b`. + Subtract two elements of a number field ``nf``, i.e. set `r = a - b`. Canonicalisation is not performed. .. function:: void nf_elem_sub(nf_elem_t r, const nf_elem_t a, const nf_elem_t b, const nf_t nf) - Subtract two elements of a number field \code{nf}, i.e. set `r = a - b`. + Subtract two elements of a number field ``nf``, i.e. set `r = a - b`. .. function:: void _nf_elem_mul(nf_elem_t a, const nf_elem_t b, const nf_elem_t c, const nf_t nf) - Multiply two elements of a number field \code{nf}, i.e. set `r = a * b`. + Multiply two elements of a number field ``nf``, i.e. set `r = a * b`. Does not canonicalise. Aliasing of inputs with output is not supported. .. function:: void _nf_elem_mul_red(nf_elem_t a, const nf_elem_t b, const nf_elem_t c, const nf_t nf, int red) - As per \code{_nf_elem_mul}, but reduction modulo the defining polynomial - of the number field is only carried out if \code{red == 1}. Assumes both + As per ``_nf_elem_mul``, but reduction modulo the defining polynomial + of the number field is only carried out if ``red == 1``. Assumes both inputs are reduced. .. function:: void nf_elem_mul(nf_elem_t a, const nf_elem_t b, const nf_elem_t c, const nf_t nf) - Multiply two elements of a number field \code{nf}, i.e. set `r = a * b`. + Multiply two elements of a number field ``nf``, i.e. set `r = a * b`. .. function:: void nf_elem_mul_red(nf_elem_t a, const nf_elem_t b, const nf_elem_t c, const nf_t nf, int red) - As per \code{nf_elem_mul}, but reduction modulo the defining polynomial - of the number field is only carried out if \code{red == 1}. Assumes both + As per ``nf_elem_mul``, but reduction modulo the defining polynomial + of the number field is only carried out if ``red == 1``. Assumes both inputs are reduced. .. function:: void _nf_elem_inv(nf_elem_t r, const nf_elem_t a, const nf_t nf) - Invert an element of a number field \code{nf}, i.e. set `r = a^{-1}`. + Invert an element of a number field ``nf``, i.e. set `r = a^{-1}`. Aliasing of the input with the output is not supported. .. function:: void nf_elem_inv(nf_elem_t r, const nf_elem_t a, const nf_t nf) - Invert an element of a number field \code{nf}, i.e. set `r = a^{-1}`. + Invert an element of a number field ``nf``, i.e. set `r = a^{-1}`. .. function:: void _nf_elem_div(nf_elem_t a, const nf_elem_t b, const nf_elem_t c, const nf_t nf) @@ -251,46 +251,46 @@ Arithmetic .. function:: void _nf_elem_pow(nf_elem_t res, const nf_elem_t a, ulong e, const nf_t nf) - Set \code{res} to `a^e` using left-to-right binary exponentiation as + Set ``res`` to `a^e` using left-to-right binary exponentiation as described in~\citep[p.~461]{Knu1997}. Assumes that `a \neq 0` and `e > 1`. Does not support aliasing. .. function:: void nf_elem_pow(nf_elem_t res, const nf_elem_t a, ulong e, const nf_t nf) - Set \code{res} = \code{a^e} using the binary exponentiation algorithm. - If `e` is zero, returns one, so that in particular \code{0^0 = 1}. + Set ``res`` = ``a^e`` using the binary exponentiation algorithm. + If `e` is zero, returns one, so that in particular ``0^0 = 1``. .. function:: void _nf_elem_norm(fmpz_t rnum, fmpz_t rden, const nf_elem_t a, const nf_t nf) - Set \code{{rnum, rden}} to the absolute norm of the given number field + Set ``rnum, rden`` to the absolute norm of the given number field element `a`. .. function:: void nf_elem_norm(fmpq_t res, const nf_elem_t a, const nf_t nf) - Set \code{res} to the absolute norm of the given number field + Set ``res`` to the absolute norm of the given number field element `a`. .. function:: void nf_elem_norm_div(fmpq_t res, const nf_elem_t a, const nf_t nf, const fmpz_t div, slong nbits) - Set \code{res} to the absolute norm of the given number field element `a`, - divided by \code{div} . Assumes the result to be an integer and having - at most \code{nbits} bits. + Set ``res`` to the absolute norm of the given number field element `a`, + divided by ``div`` . Assumes the result to be an integer and having + at most ``nbits`` bits. .. function:: void _nf_elem_norm_div(fmpz_t rnum, fmpz_t rden, const nf_elem_t a, const nf_t nf, const fmpz_t divisor, slong nbits) - Set \code{{rnum, rden}} to the absolute norm of the given number field element `a`, - divided by \code{div} . Assumes the result to be an integer and having - at most \code{nbits} bits. + Set ``rnum, rden`` to the absolute norm of the given number field element `a`, + divided by ``div`` . Assumes the result to be an integer and having + at most ``nbits`` bits. .. function:: void _nf_elem_trace(fmpz_t rnum, fmpz_t rden, const nf_elem_t a, const nf_t nf) - Set \code{{rnum, rden}} to the absolute trace of the given number field + Set ``rnum, rden`` to the absolute trace of the given number field element `a`. .. function:: void nf_elem_trace(fmpq_t res, const nf_elem_t a, const nf_t nf) - Set \code{res} to the absolute trace of the given number field + Set ``res`` to the absolute trace of the given number field element `a`. Representation matrix @@ -298,7 +298,7 @@ Representation matrix .. function:: void nf_elem_rep_mat(fmpq_mat_t res, const nf_elem_t a, const nf_t nf) - Set \code{res} to the matrix representing the multiplication with `a` with + Set ``res`` to the matrix representing the multiplication with `a` with respect to the basis `1, a, \dotsc, a^{d - 1}`, where `a` is the generator of the number field of `d` is its degree. @@ -314,26 +314,26 @@ Modular reduction .. function:: void nf_elem_mod_fmpz_den(nf_elem_t z, const nf_elem_t a, const fmpz_t mod, const nf_t nf, int den) - If \code{den == 0}, return an element `z` with denominator `1`, such that - the coefficients of `z - da` are divisble by \code{mod}, where `d` is the - denominator of `a`. The coefficients of `z` are reduced modulo \code{mod}. + If ``den == 0``, return an element `z` with denominator `1`, such that + the coefficients of `z - da` are divisble by ``mod``, where `d` is the + denominator of `a`. The coefficients of `z` are reduced modulo ``mod``. - If \code{den == 1}, return an element `z`, such that `z - a` has - denominator `1` and the coefficients of `z - a` are divisble by \code{mod}. - The coefficients of `z` are reduced modulo \code{mod * d}, where `d` is the + If ``den == 1``, return an element `z`, such that `z - a` has + denominator `1` and the coefficients of `z - a` are divisible by ``mod``. + The coefficients of `z` are reduced modulo `\mathtt{mod} \cdot d`, where `d` is the denominator of `a`. Reduction takes place with respect to the positive residue system. .. function:: void nf_elem_smod_fmpz_den(nf_elem_t z, const nf_elem_t a, const fmpz_t mod, const nf_t nf, int den) - If \code{den == 0}, return an element `z` with denominator `1`, such that - the coefficients of `z - da` are divisble by \code{mod}, where `d` is the - denominator of `a`. The coefficients of `z` are reduced modulo \code{mod}. + If ``den == 0``, return an element `z` with denominator `1`, such that + the coefficients of `z - da` are divisble by ``mod``, where `d` is the + denominator of `a`. The coefficients of `z` are reduced modulo ``mod``. - If \code{den == 1}, return an element `z`, such that `z - a` has - denominator `1` and the coefficients of `z - a` are divisble by \code{mod}. - The coefficients of `z` are reduced modulo \code{mod * d}, where `d` is the + If ``den == 1``, return an element `z`, such that `z - a` has + denominator `1` and the coefficients of `z - a` are divisible by ``mod``. + The coefficients of `z` are reduced modulo `\mathtt{mod} \cdot d`, where `d` is the denominator of `a`. Reduction takes place with respect to the symmetric residue system. @@ -341,30 +341,30 @@ Modular reduction .. function:: void nf_elem_mod_fmpz(nf_elem_t res, const nf_elem_t a, const fmpz_t mod, const nf_t nf) Return an element `z` such that `z - a` has denominator `1` and the - coefficients of `z - a` are divisible by \code{mod}. The coefficients of - `z` are reduced modulo \code{mod * d}, where `d` is the denominator of `b`. + coefficients of `z - a` are divisible by ``mod``. The coefficients of + `z` are reduced modulo `\mathtt{mod} \cdot d`, where `d` is the denominator of `b`. Reduction takes place with respect to the positive residue system. .. function:: void nf_elem_smod_fmpz(nf_elem_t res, const nf_elem_t a, const fmpz_t mod, const nf_t nf) Return an element `z` such that `z - a` has denominator `1` and the - coefficients of `z - a` are divisible by \code{mod}. The coefficients of - `z` are reduced modulo \code{mod * d}, where `d` is the denominator of `b`. + coefficients of `z - a` are divisible by ``mod``. The coefficients of + `z` are reduced modulo `\mathtt{mod} \cdot d`, where `d` is the denominator of `b`. Reduction takes place with respect to the symmetric residue system. .. function:: void nf_elem_coprime_den(nf_elem_t res, const nf_elem_t a, const fmpz_t mod, const nf_t nf) Return an element `z` such that the denominator of `z - a` is coprime to - \code{mod}. + ``mod``. Reduction takes place with respect to the positive residue system. .. function:: void nf_elem_coprime_den_signed(nf_elem_t res, const nf_elem_t a, const fmpz_t mod, const nf_t nf) Return an element `z` such that the denominator of `z - a` is coprime to - \code{mod}. + ``mod``. Reduction takes place with respect to the symmetric residue system. diff --git a/doc/source/qfb.rst b/doc/source/qfb.rst index 9f698d084e..2075660637 100644 --- a/doc/source/qfb.rst +++ b/doc/source/qfb.rst @@ -6,15 +6,15 @@ Authors: * William Hart -* Håvard Damm-Johnsen +* Håvard Damm-Johnsen (updated documentation) Introduction -------------------------------------------------------------------------------- -This module contains functionality for creating, listing and reducing binary quadratic forms. A ``qfb`` struct consists of three ``fmpz_t`` s, `a`, `b` and `c`, and basic algorithms for operating on forms are described below. +This module contains functionality for creating, listing and reducing binary quadratic forms. A ``qfb`` struct consists of three ``fmpz_t`` s, `a`, `b` and `c`, and basic algorithms for operations such as reduction, composition and enumerating are inplemented and described below. -Currently, the code only works for definite binary quadratic forms. +Currently the code only works for definite binary quadratic forms. Memory management ---------------------------------------------------------------------------------------- @@ -57,7 +57,7 @@ Hash table Search for the given binary quadratic form or its inverse in the given hash table of size `2^{depth}`. If it is found, return the index in the table (which is an array of ``qfb_hash_t`` - structs, otherwise return ``-1L``. + structs), otherwise return ``-1``. Basic manipulation ---------------------------------------------------------------------------------------- @@ -93,13 +93,14 @@ Computing with forms .. function:: void qfb_reduce(qfb_t r, qfb_t f, fmpz_t D) Set `r` to a reduced form equivalent to the binary quadratic form `f` - of discriminant `D`. If `D > 0`, then there can be more than one reduced - form equivalent to `f`. - + of discriminant `D`. + .. function:: int qfb_is_reduced(qfb_t r) - Returns `1` if `q` is a reduced binary quadratic form. Otherwise returns - `0`. + Returns `1` if `q` is a reduced binary quadratic form, otherwise + returns `0`. Note that this only tests for definite quadratic + forms, so a form `r = (a,b,c)` is reduced if and only if `|b| \le a \le + c` and if either inequality is an equality, then `b \ge 0`. .. function:: slong qfb_reduced_forms(qfb ** forms, slong d) @@ -107,7 +108,7 @@ Computing with forms all the reduced binary quadratic forms of that discriminant. The function allocates space for these and returns it in the variable ``forms`` (the user is responsible for cleaning this up by a single call to - ``qfb_array_clear`` on ``forms``, after use. The function returns + ``qfb_array_clear`` on ``forms``, after use.) The function returns the number of forms generated (the form class number). The forms are stored in an array of ``qfb`` structs, which contain fields ``a, b, c`` corresponding to forms `(a, b, c)`. @@ -175,12 +176,12 @@ Computing with forms Find the exponent of the element `f` in the form class group of forms of discriminant `n`, doing a stage `1` with primes up to at least ``B1`` and a stage `2` for a single large prime up to at least the square of - ``B2``. If the function fails to find the exponent it returns `0`, + ``B2_sqrt``. If the function fails to find the exponent it returns `0`, otherwise the function returns `1` and ``exponent`` is set to the exponent of `f`, i.e. the minimum power of `f` which gives the identity. It is assumed that the form `f` is reduced. We require that ``iters`` - is a power of `2` and that ``iters``` >= 1024`. + is a power of `2` and that ``iters`` `\ge 1024`. The function performs a stage `2` which stores up to `4\times` ``iters`` binary quadratic forms, and `12\times` ``iters`` @@ -189,14 +190,14 @@ Computing with forms .. function:: int qfb_exponent(fmpz_t exponent, fmpz_t n, ulong B1, ulong B2_sqrt, slong c) - Compute the exponent of the class group of discriminant `n`, doing a - stage `1` with primes up to at least ``B1`` and a stage `2` for a - single large prime up to at least the square of ``B2_sqrt``, and with - probability at least `1 - 2^{-c}`. If the prime limits are exhausted - without finding the exponent, the function returns `0`, otherwise it - returns `1` and ``exponent`` is set to the computed exponent, i.e. the - minimum power which every element of the class group has to be raised to - give the identity. + Compute the exponent of the class group of discriminant `n`, doing + a stage `1` with primes up to at least ``B1`` and a stage `2` for + a single large prime up to at least the square of ``B2_sqrt``, and + with probability at least `1 - 2^{-c}`. If the prime limits are + exhausted without finding the exponent, the function returns `0`, + otherwise it returns `1` and ``exponent`` is set to the computed + exponent, i.e. the minimum power to which every element of the + class group has to be raised in order to get the identity. The function performs a stage `2` which stores up to `4\times` ``iters`` binary quadratic forms, and `12\times` ``iters`` @@ -207,7 +208,7 @@ Computing with forms .. function:: int qfb_exponent_grh(fmpz_t exponent, fmpz_t n, ulong B1, ulong B2_sqrt) - As per ``qfb_exponent`` except that the bound ``c`` is - automatically generated such that the exponent it guaranteed to be + Similar to ``qfb_exponent`` except that the bound ``c`` is + automatically generated such that the exponent is guaranteed to be correct, if found, assuming the GRH, namely that the class group is - generated by primes less than `6\log^2(|n|)` as per [BD1992]_. + generated by primes less than `6\log^2(|n|)` as described in [BD1992]_. From 92e31be6f2a0ad3898fc5bf3c97683ec68e36d84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5vard=20Damm-Johnsen?= Date: Wed, 11 Oct 2023 14:33:27 +0200 Subject: [PATCH 3/3] Fixed reference --- doc/source/nf_elem.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/nf_elem.rst b/doc/source/nf_elem.rst index 5726125777..db2e4339b9 100644 --- a/doc/source/nf_elem.rst +++ b/doc/source/nf_elem.rst @@ -252,7 +252,7 @@ Arithmetic .. function:: void _nf_elem_pow(nf_elem_t res, const nf_elem_t a, ulong e, const nf_t nf) Set ``res`` to `a^e` using left-to-right binary exponentiation as - described in~\citep[p.~461]{Knu1997}. + described on p. 461 of [Knu1997]_. Assumes that `a \neq 0` and `e > 1`. Does not support aliasing.