hiro/arb
1
0
Fork 0
mirror of https://github.com/vale981/arb synced 2025-03-06 01:41:39 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

edit documentation

Browse source
This commit is contained in:
Fredrik Johansson 2016-09-08 16:53:21 +02:00
parent f6907b4c8c
commit 6845ba1386
4 changed files with 77 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

89
doc/source/acb_dirichlet.rst
View file

@ -3,17 +3,11 @@
**acb_dirichlet.h** -- Dirichlet L-functions, zeta functions, and related functions
===================================================================================
Warning: the interfaces in this module are experimental and may change
without notice.
This module will eventually allow working with Dirichlet L-functions and
possibly slightly more general Dirichlet series. At the moment, it contains
nothing interesting.
The code in other modules for computing the Riemann zeta function,
Hurwitz zeta function and polylogarithm will possibly be migrated to this
module in the future.
*Warning: the interfaces in this module are experimental and may change
without notice.*
This module allows working with Dirichlet characters, Dirichlet L-functions,
and related functions.
A Dirichlet L-function is the analytic continuation of an L-series
.. math ::
@ -22,6 +16,10 @@ A Dirichlet L-function is the analytic continuation of an L-series
where `\chi(k)` is a Dirichlet character.
The code in other modules for computing the Riemann zeta function,
Hurwitz zeta function and polylogarithm will possibly be migrated to this
module in the future.
Multiplicative group modulo *q*
-------------------------------------------------------------------------------
@ -152,18 +150,18 @@ Character type
An *acb_dirichlet_char_t* is defined as an array of *acb_dirichlet_char_struct*
of length 1, permitting it to be passed by reference.
.. function:: void acb_dirichlet_char_init(acb_dirichlet_char_t chi, const acb_dirichlet_group_t G);
.. function:: void acb_dirichlet_char_init(acb_dirichlet_char_t chi, const acb_dirichlet_group_t G)
.. function:: void acb_dirichlet_char_clear(acb_dirichlet_char_t chi);
.. function:: void acb_dirichlet_char_clear(acb_dirichlet_char_t chi)
Initializes and clear *chi*.
.. function:: void acb_dirichlet_char(acb_dirichlet_char_t chi, const acb_dirichlet_group_t G, ulong n);
.. function:: void acb_dirichlet_char(acb_dirichlet_char_t chi, const acb_dirichlet_group_t G, ulong n)
Sets *chi* to the Dirichlet character of number *n*, using Conrey numbering scheme.
This function performs a discrete logarithm in *G*.
.. function:: void acb_dirichlet_char_conrey(acb_dirichlet_char_t chi, const acb_dirichlet_group_t G, const acb_dirichlet_conrey_t x);
.. function:: void acb_dirichlet_char_conrey(acb_dirichlet_char_t chi, const acb_dirichlet_group_t G, const acb_dirichlet_conrey_t x)
Sets *chi* to the Dirichlet character of Conrey index *x*.
@ -171,7 +169,7 @@ Character properties
-------------------------------------------------------------------------------
As a consequence of the Conrey numbering, all these numbers are available at the
level off *number* and *index*, and for *char*.
level of *number* and *index*, and for *char*.
No discrete log computation is performed.
.. function:: ulong acb_dirichlet_number_primitive(const acb_dirichlet_group_t G)
@ -184,7 +182,7 @@ No discrete log computation is performed.
.. function:: ulong acb_dirichlet_char_conductor(const acb_dirichlet_char_t chi)
return the *conductor* of `\chi_q(a,\cdot)`, that is the smallest `r` dividing `q`
Return the *conductor* of `\chi_q(a,\cdot)`, that is the smallest `r` dividing `q`
such `\chi_q(a,\cdot)` can be obtained as a character mod `r`.
This number is precomputed for the *char* type.
@ -194,7 +192,7 @@ No discrete log computation is performed.
.. function:: int acb_dirichlet_char_parity(const acb_dirichlet_char_t chi)
return the *parity* `\lambda` in `\{0,1\}` of `\chi_q(a,\cdot)`, such that
Return the *parity* `\lambda` in `\{0,1\}` of `\chi_q(a,\cdot)`, such that
`\chi_q(a,-1)=(-1)^\lambda`.
This number is precomputed for the *char* type.
@ -204,7 +202,7 @@ No discrete log computation is performed.
.. function:: ulong acb_dirichlet_char_order(const acb_dirichlet_char_t chi)
return the order of `\chi_q(a,\cdot)` which is the order of `a\mod q`.
Return the order of `\chi_q(a,\cdot)` which is the order of `a\mod q`.
This number is precomputed for the *char* type.
Character evaluation
@ -218,7 +216,7 @@ unity.
.. function:: ulong acb_dirichlet_ui_chi(const acb_dirichlet_group_t G, const acb_dirichlet_char_t chi, ulong n)
compute that value `\chi(a)` as the exponent mod the order of `\chi`.
Compute that value `\chi(a)` as the exponent mod the order of `\chi`.
.. function:: void acb_dirichlet_chi(acb_t res, const acb_dirichlet_group_t G, const acb_dirichlet_char_t chi, ulong n, slong prec)
@ -232,7 +230,7 @@ Roots of unity
.. function:: void acb_dirichlet_nth_root(acb_t res, ulong order, slong prec)
sets *res* to `\exp(\frac{2i\pi}{\mathrm{order}})` to precision *prec*.
Sets *res* to `\exp(\frac{2i\pi}{\mathrm{order}})` to precision *prec*.
.. function:: void acb_dirichlet_vec_nth_roots(acb_ptr z, slong order, slong prec)
@ -244,61 +242,61 @@ Roots of unity
.. type:: acb_dirichlet_powers_t
this structure allows to compute *n* powers of a fixed root of unity of order *m*
This structure allows to compute *n* powers of a fixed root of unity of order *m*
using precomputations. Extremal cases are
- all powers are stored: `O(m)` initialization + storage, `O(n)` eval
- all powers are stored: `O(m)` initialization + storage, `O(n)` evaluations
- nothing stored: `O(1)` initialization + storage, `O(\log(m)n)` eval
- nothing stored: `O(1)` initialization + storage, `O(\log(m)n)` evaluations
- `k` step decomposition: `O(k m^{\frac1k})` init + storage, `O((k-1)n)` eval.
- `k` step decomposition: `O(k m^{\frac1k})` init + storage, `O((k-1)n)` evaluations.
Currently, only baby-step giant-step decomposition (i.e. `k=2`)
is implemented, allowing to obtain each power using one multiplication.
.. function:: void acb_dirichlet_powers_init(acb_dirichlet_powers_t t, ulong order, slong num, slong prec)
initialize the powers structure for *num* evaluations of powers of the root of unity
Initialize the powers structure for *num* evaluations of powers of the root of unity
of order *order*.
.. function:: void acb_dirichlet_powers_clear(acb_dirichlet_powers_t t)
clears *t*.
Clears *t*.
.. function:: void acb_dirichlet_power(acb_t z, const acb_dirichlet_powers_t t, ulong n, slong prec)
sets *z* to `x^n` where *t* contains precomputed powers of `x`.
Sets *z* to `x^n` where *t* contains precomputed powers of `x`.
Vector evaluation
-------------------------------------------------------------------------------
.. function:: void acb_dirichlet_ui_chi_vec(ulong * v, const acb_dirichlet_group_t G, const acb_dirichlet_char_t chi, slong nv)
compute the list of exponent values *v[k]* for `0\leq k < nv`
Compute the list of exponent values *v[k]* for `0\leq k < nv`.
.. function:: void acb_dirichlet_chi_vec(acb_ptr v, const acb_dirichlet_group_t G, const acb_dirichlet_char_t chi, slong nv, slong prec)
compute the *nv* first Dirichlet values
Compute the *nv* first Dirichlet values.
Operations
Character operations
-------------------------------------------------------------------------------
.. function:: void acb_dirichlet_conrey_mul(acb_dirichlet_conrey_t c, const acb_dirichlet_group_t G, const acb_dirichlet_conrey_t a, const acb_dirichlet_conrey_t b)
.. function:: void acb_dirichlet_char_mul(acb_dirichlet_char_t chi12, const acb_dirichlet_group_t G, const acb_dirichlet_char_t chi1, const acb_dirichlet_char_t chi2)
multiply two characters in the same group
Multiply two characters in the same group.
.. function:: void acb_dirichlet_conrey_pow(acb_dirichlet_conrey_t c, const acb_dirichlet_group_t G, const acb_dirichlet_conrey_t a, ulong n)
take the power of some character
Take the power of some character.
Gauss and Jacobi sums
-------------------------------------------------------------------------------
.. function:: void acb_dirichlet_gauss_sum(acb_t res, const acb_dirichlet_group_t G, const acb_dirichlet_char_t chi, slong prec)
compute the Gauss sum
Compute the Gauss sum
.. math::
@ -306,7 +304,7 @@ Gauss and Jacobi sums
.. function:: void acb_dirichlet_jacobi_sum(acb_t res, const acb_dirichlet_group_t G, const acb_dirichlet_char_t chi1, const acb_dirichlet_char_t chi2, slong prec)
compute the Jacobi sum
Compute the Jacobi sum
.. math::
@ -315,7 +313,7 @@ Gauss and Jacobi sums
Theta sums
-------------------------------------------------------------------------------
We call Theta series of a Dirichlet character the quadratic series
We call *theta series* of a Dirichlet character the quadratic series
.. math::
@ -333,7 +331,7 @@ For `\Re(t)>0` we write `x(t)=\exp(-\frac{\pi}{N}t^2)` and define
.. function:: void acb_dirichlet_ui_theta_arb(acb_t res, const acb_dirichlet_group_t G, ulong a, const arb_t t, slong prec);
compute the theta series `\Theta_q(a,t)` for real argument `t>0`.
Compute the theta series `\Theta_q(a,t)` for real argument `t>0`.
Beware that if `t<1` the functional equation
.. math::
@ -345,14 +343,14 @@ For `\Re(t)>0` we write `x(t)=\exp(-\frac{\pi}{N}t^2)` and define
.. function:: ulong acb_dirichlet_theta_length(ulong q, const arb_t t, slong prec)
compute the number of terms to be summed in the theta series of argument *t*
Compute the number of terms to be summed in the theta series of argument *t*
so that the tail is less than `2^{-\mathrm{prec}}`.
.. function:: void acb_dirichlet_arb_theta_naive(acb_t res, const arb_t x, int parity, const ulong * a, const acb_dirichlet_powers_t z, slong len, slong prec)
.. function:: void acb_dirichlet_arb_theta_smallorder(acb_t res, const arb_t x, int parity, const ulong * a, const acb_dirichlet_powers_t z, slong len, slong prec)
compute the series `\sum n^p z^{a_n} x^{n^2}` for exponent list *a*,
Compute the series `\sum n^p z^{a_n} x^{n^2}` for exponent list *a*,
precomputed powers *z* and parity *p* (being 0 or 1).
The *naive* version sums the series as defined, while the *smallorder*
@ -384,7 +382,7 @@ the Fourier transform on Conrey labels as
.. function:: void acb_dirichlet_dft_conrey(acb_ptr w, acb_srcptr v, const acb_dirichlet_group_t G, slong prec)
Compute the DFT of *v* using conrey indices.
Compute the DFT of *v* using Conrey indices.
This function assumes *v* and *w* are vectors
of size *G->phi_q*, whose values correspond to a lexicographic ordering
of Conrey indices.
@ -393,7 +391,7 @@ the Fourier transform on Conrey labels as
order
============ =====================
index [e,f] number = 7^e11^f
index [e,f] number = 7^e 11^f
============ =====================
[0, 0] 1
[0, 1] 7
@ -450,7 +448,7 @@ Simple functions
Note that the alternating character `\{1,-1\}` is not itself
a Dirichlet character.
L functions
L-functions
-------------------------------------------------------------------------------
.. function:: void acb_dirichlet_l_hurwitz(acb_t res, const acb_t s, const acb_dirichlet_group_t G, const acb_dirichlet_char_t chi, slong prec)
@ -476,11 +474,12 @@ Implementation notes
The current implementation introduces a *char* type which contains a *conrey*
index plus additional information which
- make evaluation of a single character a bit faster
- makes evaluation of a single character a bit faster
- have some initialization cost.
- has some initialization cost.
Even if it is straiforward to convert a *conrey* index to the
Even if it is straightforward to convert a *conrey* index to the
corresponding *char*, looping is faster at the
level of conrey representation. Things can be improved on this aspect
level of Conrey representation. Things can be improved on this aspect
but it makes code more intricate.

11
doc/source/credits.rst
View file

@ -34,13 +34,18 @@ Fredrik Johansson is the main author. The project was started in 2012
as a numerical extension of FLINT, and the initial design was heavily based
on FLINT 2.0 (with particular credit to Bill Hart and Sebastian Pancratz).
The following authors have developed major new features.
* Pascal Molin - Dirichlet characters, Dirichlet L-functions, discrete logarithm computation
* Alex Griffing - sinc function, matrix trace, improved matrix squaring, boolean matrices, improved structured matrix exponentials, Cholesky decomposition, miscellaneous patches
Several people have contributed patches, bug reports, or substantial feedback.
This list is probably incomplete.
This list (ordered by time of first contribution) is probably incomplete.
* Bill Hart - build system, Windows 64 support, design of FLINT
* Sebastian Pancratz - divide-and-conquer polynomial composition algorithm (taken from FLINT)
* The MPFR development team - Arb includes two-limb multiplication code taken from MPFR
* Jonathan Bober - Dirichlet characters (the code in Arb is based on his Cython implementation), C++ compatibility fixes
* Jonathan Bober - original code for Dirichlet characters, C++ compatibility fixes
* Yuri Matiyasevich - feedback about the zeta function and root-finding code
* Abhinav Baid - dot product and norm functions
* Ondřej Čertík - bug reports, feedback
@ -48,14 +53,12 @@ This list is probably incomplete.
* Francesco Biscani - C++ compatibility fixes, feedback
* Clemens Heuberger - work on Arb interface in Sage, feedback
* Marc Mezzarobba - work on Arb interface in Sage, bug reports, feedback
* Pascal Molin - feedback
* Ricky Farr - convenience functions, feedback
* Marcello Seri - fix for static builds on OS X
* Tommy Hofmann - matrix transpose, comparison, other utility methods, Julia interface
* Alexander Kobel - documentation and code cleanup patches
* Hrvoje Abraham - patches for MinGW compatibility
* Julien Puydt - soname versioning support
* Alex Griffing - sinc function, matrix trace, improved matrix squaring, boolean matrices, improved structured matrix exponentials, Cholesky decomposition, miscellaneous patches
* Jeroen Demeyer - patch for major bug on PPC64
Funding

49
doc/source/dlog.rst
View file

@ -3,8 +3,8 @@
**dlog.h** -- discrete logarithms mod ulong primes
===============================================================================
This module implements discrete logarithms, with in mind the application
to Dirichlet characters.
This module implements discrete logarithms, with the application
to Dirichlet characters in mind.
In particular, this module defines a :type:`dlog_precomp_t` structure
permitting to describe a discrete log problem in some subgroup
@ -24,13 +24,13 @@ Algorithms
Several discrete logarithms strategies are implemented:
- complete lookup table for small groups
- Complete lookup table for small groups
- baby-step giant-step table
- Baby-step giant-step table
combined with mathematical reductions
- Pohlig-Hellman decomposition (chinese remainder decomposition on the
- Pohlig-Hellman decomposition (Chinese remainder decomposition on the
order of the group and base `p` decomposition for primepower order)
- p-adic log for primepower modulus `p^e`.
@ -38,17 +38,17 @@ combined with mathematical reductions
For *dlog_vec* functions which compute the vector of discrete logarithms
of successive integers `1\dots n`:
- a simple loop on group elements avoiding all logarithms is done when
- A simple loop on group elements avoiding all logarithms is done when
the group size is comparable with the number of elements requested
- otherwise the logarithms are computed on primes and propagated by
- Otherwise the logarithms are computed on primes and propagated by
Eratosthene-like sieving on composite numbers.
- when several logarithms are already computed, a basic smoothing technique
- When several logarithms are already computed, a basic smoothing technique
inspired by index-calculus is adopted to obtain larger logs from
smaller ones.
- in the the present implementation, the full index-calculus method is not
- In the the present implementation, the full index-calculus method is not
implemented.
Types, macros and constants
@ -56,38 +56,38 @@ Types, macros and constants
.. macro:: DLOG_NONE
return value when the discrete logarithm does not exist
Return value when the discrete logarithm does not exist
.. type:: dlog_precomp_struct
.. type:: dlog_precomp_t
structure for discrete logarithm precomputed data.
Structure for discrete logarithm precomputed data.
.. function:: void dlog_precomp_clear(dlog_precomp_t pre)
Precomputations
-------------------------------------------------------------------------------
.. function:: void dlog_precomp_n_init(dlog_precomp_t pre, ulong a, ulong mod, ulong n, ulong num);
.. function:: void dlog_precomp_n_init(dlog_precomp_t pre, ulong a, ulong mod, ulong n, ulong num)
precompute data for *num* discrete logarithms evaluations in the subgroup generated
Precompute data for *num* discrete logarithms evaluations in the subgroup generated
by *a* modulo *mod*, where *a* is known to have order *n*.
Specialized versions are available when specific information is known about the
group:
.. function:: void dlog_precomp_modpe_init(dlog_precomp_t pre, ulong a, ulong p, ulong e, ulong pe, ulong num);
.. function:: void dlog_precomp_modpe_init(dlog_precomp_t pre, ulong a, ulong p, ulong e, ulong pe, ulong num)
assume that *a* generates the group of residues modulo `p^e`.
Assume that *a* generates the group of residues modulo `p^e`.
.. function:: void dlog_precomp_p_init(dlog_precomp_t pre, ulong a, ulong mod, ulong p, ulong num);
.. function:: void dlog_precomp_p_init(dlog_precomp_t pre, ulong a, ulong mod, ulong p, ulong num)
assume that *a* has prime order *p*.
Assume that *a* has prime order *p*.
.. function:: void dlog_precomp_pe_init(dlog_precomp_t pre, ulong a, ulong mod, ulong p, ulong e, ulong pe, ulong num);
.. function:: void dlog_precomp_pe_init(dlog_precomp_t pre, ulong a, ulong mod, ulong p, ulong e, ulong pe, ulong num)
assume that *a* has primepower order *p*.
Assume that *a* has primepower order *p*.
Single evaluation
@ -95,26 +95,27 @@ Single evaluation
.. function:: ulong dlog_precomp(const dlog_precomp_t pre, ulong b)
returns `\log(b)` for the group described in *pre*
Returns `\log(b)` for the group described in *pre*
Vector evaluations
-------------------------------------------------------------------------------
.. function:: void dlog_vec_fill(ulong * v, ulong nv, ulong x);
.. function:: void dlog_vec_fill(ulong * v, ulong nv, ulong x)
Sets values *v[k]* to *x* for all *k* less than *nv*.
.. function:: void dlog_vec_set_not_found(ulong * v, ulong nv, nmod_t mod);
.. function:: void dlog_vec_set_not_found(ulong * v, ulong nv, nmod_t mod)
Sets values *v[k]* to :macro:`DLOG_NONE` for all *k* not coprime to *mod*.
.. function:: void dlog_vec(ulong * v, ulong nv, ulong a, ulong va, nmod_t mod, ulong na, nmod_t order)
sets *v[k]* to `\log(k,a)` times value *va* for `0\leq k < nv`, where *a*
Sets *v[k]* to `\log(k,a)` times value *va* for `0\leq k < nv`, where *a*
has order *na*. *va* should be *1* for usual log computation.
.. function:: void dlog_vec_add(ulong * v, ulong nv, ulong a, ulong va, nmod_t mod, ulong na, nmod_t order)
same parameters as before, but adds `\log(k,a)` times value *va*
Same parameters as before, but adds `\log(k,a)` times value *va*
to *v[k]* and reduce modulo *order* instead of replacing the value. Indices
*k* such that *v[k]* equals *DLOG_NONE* are ignored.

1
doc/source/index.rst
View file

@ -146,6 +146,7 @@ Mainly for internal use.
fmpz_extras.rst
bool_mat.rst
dlog.rst
fmpr.rst
Supplementary algorithm notes