Characteristics, derivatives and precision

This guide explains the conventions shared by all functions of acb_theta. The definitions follow [Mum1983] and [Igu1972]; the algorithms are in Theta functions.

Theta functions with characteristics#

For $\tau \in \mathcal{H}_g$ (a symmetric complex $g \times g$ matrix with positive definite imaginary part $Y$ ), $z \in \mathbb{C}^g$ and $a, b \in \{0, 1\}^g$ , viewed as column vectors,

\theta_{a,b}(z,\tau) = \sum_{n\in \mathbb{Z}^{g} + \tfrac a2} \exp\bigl(\pi i n^T \tau n + 2\pi i n^T (z + \tfrac b2)\bigr).

The $2^{2g}$ functions are the theta functions of level 2. Shifting $z$ by half-periods permutes them up to explicit exponential factors:

\theta_{a,b}(z,\tau) = \exp\bigl(\pi i a^T\tau a/4 + \pi i a^T(z + \tfrac b2)\bigr) \, \theta_{0,0}\bigl(z + \tau\tfrac{a}{2} + \tfrac{b}{2}, \tau\bigr).

The characteristic is even if $a^T b$ is even and odd otherwise. $\theta_{a,b}(-z, \tau) = (-1)^{a^T b} \theta_{a,b}(z, \tau)$ , so the odd theta functions vanish at $z = 0$ ; there are $2^{g-1}(2^g + 1)$ even and $2^{g-1}(2^g - 1)$ odd characteristics.

For $g = 1$ , in the notation of acb_modular, $\theta_{0,0} = \theta_3$ , $\theta_{0,1} = \theta_4$ , $\theta_{1,0} = \theta_2$ and $\theta_{1,1} = -\theta_1$ .

Numbering of characteristics#

A characteristic $(a, b)$ is stored as the ulong whose binary expansion, most significant bit first, is $a_0 a_1 \ldots a_{g-1} b_0 b_1 \ldots b_{g-1}$ ; vectors of $2^{2g}$ theta values are ordered by this number. For $g = 2$ , $(a, b) = ((1,0), (0,0))$ is number $8 = 1000_2$ , and the even characteristics are those with numbers 0, 1, 2, 3, 4, 6, 8, 9, 12, 15. When $a$ or $b$ is handled alone (vectors of $2^g$ values $\theta_{a,0}$ , say), it is numbered on $g$ bits in the same way. acb_theta_char_set_slong_vec converts a vector of bits to this number and acb_theta_char_bit extracts a bit.

Derivatives#

Only derivatives with respect to $z$ are computed: those with respect to $\tau$ follow from the heat equation $2\pi i (1 + \delta_{j,k}) \, \partial\theta_{a,b}/\partial\tau_{j,k} = \partial^2\theta_{a,b}/\partial z_j \partial z_k$ . A derivation tuple $k = (k_0, \ldots, k_{g-1})$ of nonnegative integers corresponds to the normalised derivative

\frac{1}{k_0! \cdots k_{g-1}!} \frac{\partial^{|k|}\theta_{a,b}}{\partial z_0^{k_0}\cdots \partial z_{g-1}^{k_{g-1}}}, \qquad |k| = k_0 + \cdots + k_{g-1},

which is the coefficient of $h_0^{k_0} \cdots h_{g-1}^{k_{g-1}}$ in the Taylor expansion of $\theta_{a,b}(z + h, \tau)$ , as in acb_modular_theta_jet. The derivatives up to total order ord, of which there are $\binom{\mathit{ord}+g}{g}$ (acb_theta_jet_nb), are ordered by total order and then reverse-lexicographically; for $g = 2$ : $(0,0), (1,0), (0,1), (2,0), (1,1), (0,2), (3,0), \ldots$ . acb_theta_jet_tuples lists them and acb_theta_jet_index finds the position of a tuple. The functions acb_theta_jet_mul, acb_theta_jet_compose, acb_theta_jet_exp_pi_i and acb_theta_jet_exp_qf compute with such vectors for arbitrary functions.

The symplectic group#

$\mathrm{Sp}_{2g}(\mathbb{Z})$ is the group of integer matrices $m = \begin{pmatrix} \alpha & \beta \\ \gamma & \delta \end{pmatrix}$ with $m^T J m = J$ , $J = \begin{pmatrix} 0 & I_g \\ -I_g & 0 \end{pmatrix}$ . It acts on $\mathbb{C}^g \times \mathcal{H}_g$ by

m \cdot (z, \tau) = \bigl((\gamma\tau + \delta)^{-T} z, \; (\alpha\tau + \beta)(\gamma\tau + \delta)^{-1}\bigr),

and the theta functions transform as

\theta_{a,b}(m\cdot(z,\tau)) = \kappa(m) \zeta_8^{e(m, a, b)} \det(\gamma\tau + \delta)^{1/2} e^{\pi i z^T (\gamma\tau + \delta)^{-1} \gamma z} \theta_{a',b'}(z,\tau),

where $\zeta_8 = e^{\pi i/4}$ , $(a', b')$ and $e(m, a, b)$ are given by acb_theta_char_table, and $\kappa(m)$ , an 8th root of unity that depends on the branch of the square root, by acb_siegel_kappa [Igu1972], [Mum1983]. Every $\tau$ is equivalent to a reduced matrix, for which the theta series converge fast and uniformly; see Reduction.

Precision#

The magnitude of $\theta_{a,b}(z, \tau)$ is, barring cancellation, about

|\theta_{a,b}(z,\tau)| \approx e^{\pi y^T Y^{-1} y} e^{-d^2},

where $y = \operatorname{Im}(z)$ and $d$ is the distance from $-Y^{-1}y$ to the shifted lattice $\mathbb{Z}^g + \tfrac a2$ for the norm $\lVert x \rVert_\tau^2 = \pi x^T Y x$ : the largest term of the series is the one with $n$ closest to $-Y^{-1}y$ . The module therefore works with the normalised function

\widetilde{\theta}_{a,b}(z,\tau) = e^{-\pi y^T Y^{-1} y} \, \theta_{a,b}(z,\tau),

which is not holomorphic but is bounded on $\mathbb{C}^g$ for fixed $\tau$ , and satisfies the same duplication formulas. A precision argument prec means that $\widetilde{\theta}_{a,b}(z,\tau)$ is computed with an absolute error of about $2^{-\mathit{prec}}$ , so the outputs of acb_theta_jet and acb_theta_all have absolute errors of about $e^{\pi y^T Y^{-1} y} 2^{-\mathit{prec}}$ (for the reduced arguments). This avoids unbounded work when $y$ is far from zero. Some internal functions (with a distances argument or a shifted_prec flag) also take the factor $e^{-d^2}$ into account and compute $\widetilde\theta_{a,b}$ with absolute error about $e^{-d^2} 2^{-\mathit{prec}}$ , a shifted absolute precision; the squared distances are computed by acb_theta_eld_distances.

All outputs are certified enclosures. If the imaginary part of $\tau$ is not certainly positive definite at the working precision, the outputs have infinite radius.

Testing and profiling programs#

The test programs in src/acb_theta/test check, among others, that the transformation formula and the duplication formulas hold on random input, that acb_siegel_reduce produces matrices accepted by acb_siegel_is_reduced, and that the quasi-linear algorithm agrees with summation. The programs in src/acb_theta/profile are used for tuning:

p-sum g prec all_a all_b tilde skew times acb_theta_sum (distances, contexts, summation) on random input whose last row and column of $\tau$ are multiplied by skew;
p-ql_setup g nb_steps all skew checks that acb_theta_ql_setup stays cheap and succeeds as the precision and number of steps grow;
p-ql_exact g pmin pmax cst s exp compares, for precisions from pmin to pmax, the pattern suggested by acb_theta_ql_nb_steps with neighbouring patterns in acb_theta_ql_exact, on matrices whose last s rows and columns are scaled by $2^{\mathit{exp}}$ ;
p-ql_jet_fd g prec ord all compares acb_theta_ql_jet_fd with acb_theta_sum_jet, which decides the cutoffs of acb_theta_ql_jet.