The nome and `tau`

[stla]

One of our "primitive" functions used to evaluate the Jacobi theta functions is defined in terms of tau. The nome is q = exp(1im * pi * tau). There's a consistency issue: if one starts with tau, then calculates q with this formula, then calculates tau = log(q) / pi / 1im, then we do not always find the original value of tau (if its imaginary part does not belong to (0, 2pi) I think). And this can lead to different values of the Jacobi functions.

Should we ban tau as an argument of the Jacobi theta functions, and use z, q as arguments instead? That was already suggested by @simonp0420.

@simonp0420 am I clear? Not sure.

[simonp0420]

Yes, the dilemma is clear. This is what NIST has to say about it: so my preference is to use $z$ and $q$ as inputs, assuming that the desired $\tau$ is obtainable from the principal branch of the $\log$ function. If there are actually applications where a different value of $\tau$ is needed (I'm not aware of any), I suppose that we could define the user-facing functions with an optional integer keyword argument branch that defaults to 0. If the user supplies a nonzero value for branch then the correct value of $\tau$ could be computed as log(q) / (im*pi) + 2*branch.

[stla]

@simonp0420 I'm lost actually. We have the correct implementation for the nome. If tau = log(q) / (im*pi) + 2*branch with branch != 0, how can we get the value of the Jacobi theta functions for tau?

[simonp0420]

I'm not sure I take your exact meaning, but your comment made me reflect on what the choice of branch means in terms of our computations. Consider the following numerical experiment:

using EllipticFunctions
julia> z = 1; zopi = z/pi
0.3183098861837907

julia> tau = 1im; t = -im * tau; topi = t/pi
0.3183098861837907 + 0.0im

julia> ans1 = EllipticFunctions._calctheta1_alt2(zopi, topi)
0.7670770950992594 + 0.0im

julia> tau₂ = 1im + 2; t₂ = -im * tau₂; topi₂ = t₂/pi
0.3183098861837907 - 0.6366197723675814im

julia> ans2 = EllipticFunctions._calctheta1_alt2(zopi, topi₂)
-1.1102230246251565e-16 + 0.7670770950992594im

Since tau and tau₂ produce the same q value, they should produce the same value of elliptic function, but they don't when evaluated using the "alt2" formula from the Poisson transform. This is because of the factor sqrt(1/t) that multiplies the series. One has to add the right multiple of 2im to t prior to taking the principal branch of the square root in order to get the right answer.

Is this what you're referring to?

[stla]

Since tau and tau₂ produce the same q value, they should produce the same value of elliptic function

So you mean that the theta functions depend on tau through q only? So ans2 is wrong? I never seriously studied these functions...

[simonp0420]

Yes the theta functions depend on tau only through q. You can see this by looking at the fundamental definitions of these functions on the NIST site. ans2 is wrong because the Poisson transformed formula is only valid for tau values related to q values through the principal branch of the log function.

[stla]

Ok. So in order to fix this error, is it enough to replace tau with taufromq(qfromtau(tau))?

[simonp0420]

Yeah, that ought to do it!

[simonp0420]

I haven't looked at all the other functions in the package, but if we change the theta functions to take q as an input rather than tau, then that would also do it for them.

[stla]

Ok thanks. Today I implemented the Dixon elliptic functions in terms of the Jacobi elliptic functions (sn, etc.) and there were some errors, I'm wondering whether this is due to these possibly wrong calculations of the theta functions. Will check.

[stla]

I've checked. I did the change taufromq(qfromtau(tau)) but the problem is still there. Here is the Dixon cm function I obtain:

You see at the bottom right, there's a problem. With another implementation I get a nice picture:

So there's a problem somewhere in our code.

[simonp0420]

I'm impressed that your beautiful graphics are also useful for debugging!