0
# Elliptic Functions and Modular Forms
1

2
Elliptic functions, modular forms, theta functions, and q-analog functions for advanced mathematical applications including algebraic geometry, number theory, and mathematical physics.
3

4
## Capabilities
5

6
### Elliptic Functions and Jacobi Functions
7

8
Jacobi elliptic functions and their variants.
9

10
```python { .api }
11
def jacobi(kind, u, m):
12
    """
13
    Jacobi elliptic functions.
14
    
15
    Args:
16
        kind: Function type ('sn', 'cn', 'dn', 'ns', 'nc', 'nd', 'sc', 'cs', 'sd', 'ds', 'cd', 'dc')
17
        u: Argument
18
        m: Parameter (0 ≤ m ≤ 1)
19
        
20
    Returns:
21
        Specified Jacobi elliptic function
22
    """
23

24
def ellipfun(kind, u, m):
25
    """
26
    Jacobi elliptic function (alias for jacobi).
27
    
28
    Args:
29
        kind: Function type
30
        u: Argument  
31
        m: Parameter
32
        
33
    Returns:
34
        Jacobi elliptic function
35
    """
36
```
37

38
### Modular Parameter Conversions
39

40
Functions for converting between different modular parameters.
41

42
```python { .api }
43
def qfrom(m=None, k=None, tau=None):
44
    """
45
    Compute nome q from modular parameters.
46
    
47
    Args:
48
        m: Parameter m (alternative to k or tau)
49
        k: Modulus k (alternative to m or tau)
50
        tau: Half-period ratio τ (alternative to m or k)
51
        
52
    Returns:
53
        Nome q = exp(iπτ)
54
    """
55

56
def mfrom(q=None, k=None, tau=None):
57
    """
58
    Compute parameter m from other modular parameters.
59
    
60
    Args:
61
        q: Nome q (alternative to k or tau)
62
        k: Modulus k (alternative to q or tau)
63
        tau: Half-period ratio τ (alternative to q or k)
64
        
65
    Returns:
66
        Parameter m
67
    """
68

69
def kfrom(m=None, q=None, tau=None):
70
    """
71
    Compute modulus k from other modular parameters.
72
    
73
    Args:
74
        m: Parameter m (alternative to q or tau)
75
        q: Nome q (alternative to m or tau)
76
        tau: Half-period ratio τ (alternative to m or q)
77
        
78
    Returns:
79
        Modulus k
80
    """
81

82
def taufrom(m=None, k=None, q=None):
83
    """
84
    Compute half-period ratio τ from other modular parameters.
85
    
86
    Args:
87
        m: Parameter m (alternative to k or q)
88
        k: Modulus k (alternative to m or q)
89
        q: Nome q (alternative to m or k)
90
        
91
    Returns:
92
        Half-period ratio τ
93
    """
94

95
def qbarfrom(m=None, k=None, tau=None):
96
    """
97
    Compute complementary nome q' from modular parameters.
98
    
99
    Args:
100
        m: Parameter m (alternative to k or tau)
101
        k: Modulus k (alternative to m or tau)
102
        tau: Half-period ratio τ (alternative to m or k)
103
        
104
    Returns:
105
        Complementary nome q'
106
    """
107
```
108

109
### Jacobi Theta Functions
110

111
Jacobi theta functions and their variants.
112

113
```python { .api }
114
def jtheta(n, z, q, derivative=0):
115
    """
116
    Jacobi theta function θ_n(z,q).
117
    
118
    Args:
119
        n: Function index (1, 2, 3, or 4)
120
        z: Argument
121
        q: Nome parameter
122
        derivative: Derivative order (default 0)
123
        
124
    Returns:
125
        θ_n(z,q) or its derivative
126
    """
127
```
128

129
### Modular Forms
130

131
Modular forms and related functions.
132

133
```python { .api }
134
def kleinj(tau):
135
    """
136
    Klein j-invariant function.
137
    
138
    Args:
139
        tau: Modular parameter
140
        
141
    Returns:
142
        j(τ) - Klein j-invariant
143
    """
144

145
def eta(tau):
146
    """
147
    Dedekind eta function η(τ).
148
    
149
    Args:
150
        tau: Modular parameter (Im(τ) > 0)
151
        
152
    Returns:
153
        η(τ) = q^(1/24) ∏(1-q^n) where q = exp(2πiτ)
154
    """
155
```
156

157
### Elliptic Integrals
158

159
Complete and incomplete elliptic integrals of the first, second, and third kind.
160

161
```python { .api }
162
def ellipe(*args):
163
    """
164
    Complete or incomplete elliptic integral of the second kind E(m) or E(φ,m).
165
    
166
    Args:
167
        m: Parameter (when called with one argument)
168
        φ, m: Amplitude and parameter (when called with two arguments)
169
        
170
    Returns:
171
        Complete: E(m) = ∫₀^(π/2) √(1-m sin²θ) dθ
172
        Incomplete: E(φ,m) = ∫₀^φ √(1-m sin²θ) dθ
173
    """
174

175
def ellipf(phi, m):
176
    """
177
    Incomplete elliptic integral of the first kind F(φ,m).
178
    
179
    Args:
180
        phi: Amplitude
181
        m: Parameter
182
        
183
    Returns:
184
        F(φ,m) = ∫₀^φ dθ/√(1-m sin²θ)
185
    """
186

187
def ellippi(n, *args):
188
    """
189
    Complete or incomplete elliptic integral of the third kind Π(n,m) or Π(n,φ,m).
190
    
191
    Args:
192
        n: Characteristic
193
        m: Parameter (for complete integral)
194
        φ, m: Amplitude and parameter (for incomplete integral)
195
        
196
    Returns:
197
        Complete: Π(n,m) = ∫₀^(π/2) dθ/((1-n sin²θ)√(1-m sin²θ))
198
        Incomplete: Π(n,φ,m) = ∫₀^φ dθ/((1-n sin²θ)√(1-m sin²θ))
199
    """
200
```
201

202
### Q-Functions and Quantum Analogs
203

204
Q-analog functions for quantum mathematics and combinatorics.
205

206
```python { .api }
207
def qp(a, q, n):
208
    """
209
    q-Pochhammer symbol (a;q)_n.
210
    
211
    Args:
212
        a: Base parameter
213
        q: q-parameter
214
        n: Count (can be infinity)
215
        
216
    Returns:
217
        (a;q)_n = ∏(1-aq^k) for k=0 to n-1
218
    """
219

220
def qhyper(a_s, b_s, q, z, **kwargs):
221
    """
222
    Basic hypergeometric function.
223
    
224
    Args:
225
        a_s: List of numerator parameters
226
        b_s: List of denominator parameters
227
        q: q-parameter
228
        z: Argument
229
        **kwargs: Additional options
230
        
231
    Returns:
232
        Basic hypergeometric series
233
    """
234

235
def qgamma(z, q):
236
    """
237
    q-gamma function Γ_q(z).
238
    
239
    Args:
240
        z: Argument
241
        q: q-parameter
242
        
243
    Returns:
244
        q-gamma function
245
    """
246

247
def qfac(n, q):
248
    """
249
    q-factorial [n]_q!.
250
    
251
    Args:
252
        n: Non-negative integer
253
        q: q-parameter
254
        
255
    Returns:
256
        [n]_q! = [1]_q[2]_q...[n]_q where [k]_q = (1-q^k)/(1-q)
257
    """
258
```
259

260
### Usage Examples
261

262
```python
263
import mpmath
264
from mpmath import mp
265

266
# Set precision
267
mp.dps = 25
268

269
# Jacobi elliptic functions
270
m = 0.5  # Parameter
271
u = 1.0  # Argument
272

273
sn_val = mp.jacobi('sn', u, m)
274
cn_val = mp.jacobi('cn', u, m)
275
dn_val = mp.jacobi('dn', u, m)
276

277
print(f"sn({u}, {m}) = {sn_val}")
278
print(f"cn({u}, {m}) = {cn_val}")
279
print(f"dn({u}, {m}) = {dn_val}")
280

281
# Verify fundamental identity: sn² + cn² = 1
282
identity = sn_val**2 + cn_val**2
283
print(f"sn² + cn² = {identity}")  # Should be 1
284

285
# Modular parameter conversions
286
k = 0.5  # Modulus
287
m_from_k = mp.mfrom(k=k)
288
q_from_k = mp.qfrom(k=k)
289
tau_from_k = mp.taufrom(k=k)
290

291
print(f"From k={k}:")
292
print(f"  m = {m_from_k}")
293
print(f"  q = {q_from_k}")
294
print(f"  τ = {tau_from_k}")
295

296
# Theta functions
297
tau = 1j  # Pure imaginary for convergence
298
z = 0.5
299
q = mp.exp(mp.j * mp.pi * tau)
300

301
theta1 = mp.jtheta(1, z, q)
302
theta2 = mp.jtheta(2, z, q)
303
theta3 = mp.jtheta(3, z, q)
304
theta4 = mp.jtheta(4, z, q)
305

306
print(f"θ₁({z}, q) = {theta1}")
307
print(f"θ₂({z}, q) = {theta2}")
308
print(f"θ₃({z}, q) = {theta3}")
309
print(f"θ₄({z}, q) = {theta4}")
310

311
# Dedekind eta function
312
eta_val = mp.eta(tau)
313
print(f"η({tau}) = {eta_val}")
314

315
# Klein j-invariant
316
j_val = mp.kleinj(tau)
317
print(f"j({tau}) = {j_val}")
318

319
# Q-functions
320
q = 0.5
321
n = 5
322

323
# q-factorial
324
qfac_val = mp.qfac(n, q)
325
print(f"[{n}]_q! = {qfac_val}")
326

327
# q-Pochhammer symbol
328
a = 2
329
qpoch_val = mp.qp(a, q, n)
330
print(f"({a};{q})_{n} = {qpoch_val}")
331

332
# q-gamma function
333
z = 3
334
qgamma_val = mp.qgamma(z, q)
335
print(f"Γ_q({z}) = {qgamma_val}")
336

337
# Complete elliptic integrals (for comparison)
338
K_val = mp.ellipk(m)
339
E_val = mp.ellipe(m)
340
print(f"K({m}) = {K_val}")
341
print(f"E({m}) = {E_val}")
342

343
# Relationship between Jacobi functions and elliptic integrals
344
# sn(K(m), m) should equal 1
345
sn_at_K = mp.jacobi('sn', K_val, m)
346
print(f"sn(K({m}), {m}) = {sn_at_K}")  # Should be close to 1
347

348
# Advanced: Basic hypergeometric series
349
a_list = [0.5]
350
b_list = [2]
351
z = 0.3
352
qhyper_val = mp.qhyper(a_list, b_list, q, z)
353
print(f"₁φ₁(0.5; 2; {q}, {z}) = {qhyper_val}")
354
```
355

356
### Applications and Context
357

358
These functions are fundamental in:
359

360
- **Algebraic Geometry**: Elliptic curves and modular forms
361
- **Number Theory**: L-functions and modular equations  
362
- **Mathematical Physics**: Exactly solvable models and conformal field theory
363
- **Combinatorics**: Partition functions and q-analogs
364
- **Complex Analysis**: Doubly periodic functions and uniformization
365

366
The modular parameter conversions allow seamless translation between different conventions used in various mathematical contexts, while the q-analog functions provide discrete analogs of classical special functions that arise naturally in quantum mathematics and combinatorics.