]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | Copyright (c) 2012 John Maddock | |
3 | Use, modification and distribution are subject to the | |
4 | Boost Software License, Version 1.0. (See accompanying file | |
5 | LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
6 | ] | |
7 | ||
8 | [section:jacobi Jacobi Elliptic Functions] | |
9 | ||
10 | [section:jac_over Overvew of the Jacobi Elliptic Functions] | |
11 | ||
12 | There are twelve Jacobi Elliptic functions, of which the three copolar functions ['sn], ['cn] and ['dn] are the most important | |
13 | as the other nine can be computed from these three | |
14 | [footnote [@http://en.wikipedia.org/wiki/Jacobi_elliptic_functions Wikipedia: Jacobi elliptic functions]] | |
15 | [footnote [@http://mathworld.wolfram.com/JacobiEllipticFunctions.html Weisstein, Eric W. "Jacobi Elliptic Functions." From MathWorld - A Wolfram Web Resource.]] | |
16 | [footnote [@http://dlmf.nist.gov/22 Digital Library of Mathematical Functions: Jacobian Elliptic Functions]]. | |
17 | ||
18 | These functions each take two arguments: a parameter, and a variable as described below. | |
19 | ||
20 | Like all elliptic functions these can be parameterised in a number of ways: | |
21 | ||
22 | * In terms of a parameter ['m]. | |
23 | * In terms of the elliptic modulus ['k] where ['m = k[super 2]]. | |
24 | * In terms of the modular angle [alpha], where ['m = sin[super 2][alpha]]. | |
25 | ||
26 | In our implementation, these functions all take the elliptic modulus /k/ as the parameter. | |
27 | ||
28 | In addition the variable /u/ is sometimes expressed as an amplitude [phi], in our implementation we always use /u/. | |
29 | ||
30 | Finally note that our functions all take the elliptic modulus as the first argument - this is for alignment with | |
31 | the Elliptic Integrals. | |
32 | ||
33 | There are twenve functions for computing the twelve individual Jacobi elliptic functions: __jacobi_cd, __jacobi_cn, __jacobi_cs, | |
34 | __jacobi_dc, __jacobi_dn, __jacobi_ds, __jacobi_nc, __jacobi_nd, __jacobi_ns, __jacobi_sc, __jacobi_sd and __jacobi_sn. | |
35 | ||
36 | They are all called as for example: | |
37 | ||
38 | jacobi_cs(k, u); | |
39 | ||
40 | Note however that these individual functions are all really thin wrappers around the function __jacobi_elliptic which calculates | |
41 | the three copolar functions ['sn], ['cn] and ['dn] in a single function call. Thus if you need more than one of these functions | |
42 | for a given set of arguments, it's most efficient to use __jacobi_elliptic. | |
43 | ||
44 | [endsect] | |
45 | ||
46 | [section:jacobi_elliptic Jacobi Elliptic SN, CN and DN] | |
47 | ||
48 | [heading Synopsis] | |
49 | ||
50 | `` | |
51 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
52 | `` | |
53 | ||
54 | namespace boost { namespace math { | |
55 | ||
56 | template <class T, class U, class V> | |
57 | ``__sf_result`` jacobi_elliptic(T k, U u, V* pcn, V* pdn); | |
58 | ||
59 | template <class T, class U, class V, class Policy> | |
60 | ``__sf_result`` jacobi_elliptic(T k, U u, V* pcn, V* pdn, const Policy&); | |
61 | ||
62 | }} // namespaces | |
63 | ||
64 | [heading Description] | |
65 | ||
66 | The function __jacobi_elliptic calculates the three copolar Jacobi elliptic functions | |
67 | ['sn(u, k)], ['cn(u, k)] and ['dn(u, k)]. The returned value is | |
68 | ['sn(u, k)], and if provided, ['*pcn] is | |
69 | set to ['cn(u, k)], and ['*pdn] is set to ['dn(u, k)]. | |
70 | ||
71 | The functions are defined as follows, given: | |
72 | ||
73 | [equation jacobi1] | |
74 | ||
75 | The the angle [phi] is called the ['amplitude] and: | |
76 | ||
77 | [equation jacobi2] | |
78 | ||
79 | [note ['[phi]] is called the amplitude. | |
80 | ||
81 | ['k] is called the modulus. | |
82 | ||
83 | ] | |
84 | ||
85 | [caution Rather like other elliptic functions, the Jacobi functions | |
86 | are expressed in a variety of different ways. In particular, | |
87 | the parameter /k/ (the modulus) may also be expressed using a modular | |
88 | angle [alpha], or a parameter /m/. These are related by: | |
89 | ||
90 | k = sin[alpha] | |
91 | ||
92 | m = k[super 2] = sin[super 2][alpha] | |
93 | ||
94 | So that the function ['sn] (for example) may be expressed as | |
95 | either: | |
96 | ||
97 | sn(u, k) | |
98 | ||
99 | sn(u \\ [alpha]) | |
100 | ||
101 | sn(u| m) | |
102 | ||
103 | To further complicate matters, some texts refer to the ['complement | |
104 | of the parameter m], or 1 - m, where: | |
105 | ||
106 | 1 - m = 1 - k[super 2] = cos[super 2][alpha] | |
107 | ||
108 | This implementation uses /k/ throughout, and makes this the first argument | |
109 | to the functions: this is for alignment with the elliptic integrals which match the requirements | |
110 | of the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf | |
111 | Technical Report on C++ Library Extensions]. However, you should | |
112 | be extra careful when using these functions!] | |
113 | ||
114 | [optional_policy] | |
115 | ||
116 | The following graphs illustrate how these functions change as /k/ changes: for small /k/ | |
117 | these are sine waves, while as /k/ tends to 1 they become hyperbolic functions: | |
118 | ||
119 | [graph jacobi_sn] | |
120 | ||
121 | [graph jacobi_cn] | |
122 | ||
123 | [graph jacobi_dn] | |
124 | ||
125 | [heading Accuracy] | |
126 | ||
127 | These functions are computed using only basic arithmetic operations and trigomometric functions, so | |
128 | there isn't much variation in accuracy over differing platforms. | |
129 | Typically errors are trivially small for small angles, and as is typical for cyclic | |
130 | functions, grow as the angle increases. | |
131 | Note that only results for the widest floating point type on the | |
132 | system are given as narrower types have __zero_error. All values | |
133 | are relative errors in units of epsilon. | |
134 | ||
135 | [table_jacobi_cn] | |
136 | ||
137 | [table_jacobi_dn] | |
138 | ||
139 | [table_jacobi_sn] | |
140 | ||
141 | [heading Testing] | |
142 | ||
143 | The tests use a mixture of spot test values calculated using the online | |
144 | calculator at [@http://functions.wolfram.com/ functions.wolfram.com], | |
145 | and random test data generated using | |
146 | MPFR at 1000-bit precision and this implementation. | |
147 | ||
148 | [heading Implementation] | |
149 | ||
150 | For ['k > 1] we apply the relations: | |
151 | ||
152 | [equation jacobi3] | |
153 | ||
154 | Then filter off the special cases: | |
155 | ||
156 | ['sn(0, k) = 0] and ['cn(0, k) = dn(0, k) = 1]. | |
157 | ||
158 | ['sn(u, 0) = sin(u), cn(u, 0) = cos(u) and dn(u, 0) = 1]. | |
159 | ||
160 | ['sn(u, 1) = tanh(u), cn(u, 1) = dn(u, 1) = 1 / cosh(u)]. | |
161 | ||
162 | And for ['k[super 4] < [epsilon]] we have: | |
163 | ||
164 | [equation jacobi4] | |
165 | ||
166 | Otherwise the values are calculated using the method of [@http://dlmf.nist.gov/22.20#SS2 arithmetic geometric means]. | |
167 | ||
168 | [endsect] | |
169 | ||
170 | [section:jacobi_cd Jacobi Elliptic Function cd] | |
171 | ||
172 | [heading Synopsis] | |
173 | ||
174 | `` | |
175 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
176 | `` | |
177 | ||
178 | namespace boost { namespace math { | |
179 | ||
180 | template <class T, class U> | |
181 | ``__sf_result`` jacobi_cd(T k, U u); | |
182 | ||
183 | template <class T, class U, class Policy> | |
184 | ``__sf_result`` jacobi_cd(T k, U u, const Policy& pol); | |
185 | ||
186 | }} // namespaces | |
187 | ||
188 | [heading Description] | |
189 | ||
190 | This function returns the Jacobi elliptic function ['cd]. | |
191 | ||
192 | [optional_policy] | |
193 | ||
194 | This function is a trivial wrapper around __jacobi_elliptic, with: | |
195 | ||
196 | ['cd(u, k) = cn(u, k) / dn(u, k)] | |
197 | ||
198 | [graph jacobi_cd] | |
199 | ||
200 | [endsect] | |
201 | ||
202 | [section:jacobi_cn Jacobi Elliptic Function cn] | |
203 | ||
204 | [heading Synopsis] | |
205 | ||
206 | `` | |
207 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
208 | `` | |
209 | ||
210 | namespace boost { namespace math { | |
211 | ||
212 | template <class T, class U> | |
213 | ``__sf_result`` jacobi_cn(T k, U u); | |
214 | ||
215 | template <class T, class U, class Policy> | |
216 | ``__sf_result`` jacobi_cn(T k, U u, const Policy& pol); | |
217 | ||
218 | }} // namespaces | |
219 | ||
220 | [heading Description] | |
221 | ||
222 | This function returns the Jacobi elliptic function ['cn]. | |
223 | ||
224 | [optional_policy] | |
225 | ||
226 | This function is a trivial wrapper around __jacobi_elliptic. | |
227 | ||
228 | [graph jacobi_cn] | |
229 | ||
230 | [endsect] | |
231 | ||
232 | [section:jacobi_cs Jacobi Elliptic Function cs] | |
233 | ||
234 | [heading Synopsis] | |
235 | ||
236 | `` | |
237 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
238 | `` | |
239 | ||
240 | namespace boost { namespace math { | |
241 | ||
242 | template <class T, class U> | |
243 | ``__sf_result`` jacobi_cs(T k, U u); | |
244 | ||
245 | template <class T, class U, class Policy> | |
246 | ``__sf_result`` jacobi_cs(T k, U u, const Policy& pol); | |
247 | ||
248 | }} // namespaces | |
249 | ||
250 | [heading Description] | |
251 | ||
252 | This function returns the Jacobi elliptic function ['cs]. | |
253 | ||
254 | [optional_policy] | |
255 | ||
256 | This function is a trivial wrapper around __jacobi_elliptic, with: | |
257 | ||
258 | ['cs(u, k) = cn(u, k) / sn(u, k)] | |
259 | ||
260 | [graph jacobi_cs] | |
261 | ||
262 | [endsect] | |
263 | ||
264 | [section:jacobi_dc Jacobi Elliptic Function dc] | |
265 | ||
266 | [heading Synopsis] | |
267 | ||
268 | `` | |
269 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
270 | `` | |
271 | ||
272 | namespace boost { namespace math { | |
273 | ||
274 | template <class T, class U> | |
275 | ``__sf_result`` jacobi_dc(T k, U u); | |
276 | ||
277 | template <class T, class U, class Policy> | |
278 | ``__sf_result`` jacobi_dc(T k, U u, const Policy& pol); | |
279 | ||
280 | }} // namespaces | |
281 | ||
282 | [heading Description] | |
283 | ||
284 | This function returns the Jacobi elliptic function ['dc]. | |
285 | ||
286 | [optional_policy] | |
287 | ||
288 | This function is a trivial wrapper around __jacobi_elliptic, with: | |
289 | ||
290 | ['dc(u, k) = dn(u, k) / cn(u, k)] | |
291 | ||
292 | [graph jacobi_dc] | |
293 | ||
294 | [endsect] | |
295 | ||
296 | [section:jacobi_dn Jacobi Elliptic Function dn] | |
297 | ||
298 | [heading Synopsis] | |
299 | ||
300 | `` | |
301 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
302 | `` | |
303 | ||
304 | namespace boost { namespace math { | |
305 | ||
306 | template <class T, class U> | |
307 | ``__sf_result`` jacobi_dn(T k, U u); | |
308 | ||
309 | template <class T, class U, class Policy> | |
310 | ``__sf_result`` jacobi_dn(T k, U u, const Policy& pol); | |
311 | ||
312 | }} // namespaces | |
313 | ||
314 | [heading Description] | |
315 | ||
316 | This function returns the Jacobi elliptic function ['dn]. | |
317 | ||
318 | [optional_policy] | |
319 | ||
320 | This function is a trivial wrapper around __jacobi_elliptic. | |
321 | ||
322 | [graph jacobi_dn] | |
323 | ||
324 | [endsect] | |
325 | ||
326 | [section:jacobi_ds Jacobi Elliptic Function ds] | |
327 | ||
328 | [heading Synopsis] | |
329 | ||
330 | `` | |
331 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
332 | `` | |
333 | ||
334 | namespace boost { namespace math { | |
335 | ||
336 | template <class T, class U> | |
337 | ``__sf_result`` jacobi_ds(T k, U u); | |
338 | ||
339 | template <class T, class U, class Policy> | |
340 | ``__sf_result`` jacobi_ds(T k, U u, const Policy& pol); | |
341 | ||
342 | }} // namespaces | |
343 | ||
344 | [heading Description] | |
345 | ||
346 | This function returns the Jacobi elliptic function ['ds]. | |
347 | ||
348 | [optional_policy] | |
349 | ||
350 | This function is a trivial wrapper around __jacobi_elliptic, with: | |
351 | ||
352 | ['ds(u, k) = dn(u, k) / sn(u, k)] | |
353 | ||
354 | [graph jacobi_ds] | |
355 | ||
356 | [endsect] | |
357 | ||
358 | [section:jacobi_nc Jacobi Elliptic Function nc] | |
359 | ||
360 | [heading Synopsis] | |
361 | ||
362 | `` | |
363 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
364 | `` | |
365 | ||
366 | namespace boost { namespace math { | |
367 | ||
368 | template <class T, class U> | |
369 | ``__sf_result`` jacobi_nc(T k, U u); | |
370 | ||
371 | template <class T, class U, class Policy> | |
372 | ``__sf_result`` jacobi_nc(T k, U u, const Policy& pol); | |
373 | ||
374 | }} // namespaces | |
375 | ||
376 | [heading Description] | |
377 | ||
378 | This function returns the Jacobi elliptic function ['nc]. | |
379 | ||
380 | [optional_policy] | |
381 | ||
382 | This function is a trivial wrapper around __jacobi_elliptic, with: | |
383 | ||
384 | ['nc(u, k) = 1 / cn(u, k)] | |
385 | ||
386 | [graph jacobi_nc] | |
387 | ||
388 | [endsect] | |
389 | ||
390 | [section:jacobi_nd Jacobi Elliptic Function nd] | |
391 | ||
392 | [heading Synopsis] | |
393 | ||
394 | `` | |
395 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
396 | `` | |
397 | ||
398 | namespace boost { namespace math { | |
399 | ||
400 | template <class T, class U> | |
401 | ``__sf_result`` jacobi_nd(T k, U u); | |
402 | ||
403 | template <class T, class U, class Policy> | |
404 | ``__sf_result`` jacobi_nd(T k, U u, const Policy& pol); | |
405 | ||
406 | }} // namespaces | |
407 | ||
408 | [heading Description] | |
409 | ||
410 | This function returns the Jacobi elliptic function ['nd]. | |
411 | ||
412 | [optional_policy] | |
413 | ||
414 | This function is a trivial wrapper around __jacobi_elliptic, with: | |
415 | ||
416 | ['nd(u, k) = 1 / dn(u, k)] | |
417 | ||
418 | [graph jacobi_nd] | |
419 | ||
420 | [endsect] | |
421 | ||
422 | [section:jacobi_ns Jacobi Elliptic Function ns] | |
423 | ||
424 | [heading Synopsis] | |
425 | ||
426 | `` | |
427 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
428 | `` | |
429 | ||
430 | namespace boost { namespace math { | |
431 | ||
432 | template <class T, class U> | |
433 | ``__sf_result`` jacobi_ns(T k, U u); | |
434 | ||
435 | template <class T, class U, class Policy> | |
436 | ``__sf_result`` jacobi_ns(T k, U u, const Policy& pol); | |
437 | ||
438 | }} // namespaces | |
439 | ||
440 | [heading Description] | |
441 | ||
442 | This function returns the Jacobi elliptic function ['ns]. | |
443 | ||
444 | [optional_policy] | |
445 | ||
446 | This function is a trivial wrapper around __jacobi_elliptic, with: | |
447 | ||
448 | ['ns(u, k) = 1 / sn(u, k)] | |
449 | ||
450 | [graph jacobi_ns] | |
451 | ||
452 | [endsect] | |
453 | ||
454 | [section:jacobi_sc Jacobi Elliptic Function sc] | |
455 | ||
456 | [heading Synopsis] | |
457 | ||
458 | `` | |
459 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
460 | `` | |
461 | ||
462 | namespace boost { namespace math { | |
463 | ||
464 | template <class T, class U> | |
465 | ``__sf_result`` jacobi_sc(T k, U u); | |
466 | ||
467 | template <class T, class U, class Policy> | |
468 | ``__sf_result`` jacobi_sc(T k, U u, const Policy& pol); | |
469 | ||
470 | }} // namespaces | |
471 | ||
472 | [heading Description] | |
473 | ||
474 | This function returns the Jacobi elliptic function ['sc]. | |
475 | ||
476 | [optional_policy] | |
477 | ||
478 | This function is a trivial wrapper around __jacobi_elliptic, with: | |
479 | ||
480 | ['sc(u, k) = sn(u, k) / cn(u, k)] | |
481 | ||
482 | [graph jacobi_sc] | |
483 | ||
484 | [endsect] | |
485 | ||
486 | [section:jacobi_sd Jacobi Elliptic Function sd] | |
487 | ||
488 | [heading Synopsis] | |
489 | ||
490 | `` | |
491 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
492 | `` | |
493 | ||
494 | namespace boost { namespace math { | |
495 | ||
496 | template <class T, class U> | |
497 | ``__sf_result`` jacobi_sd(T k, U u); | |
498 | ||
499 | template <class T, class U, class Policy> | |
500 | ``__sf_result`` jacobi_sd(T k, U u, const Policy& pol); | |
501 | ||
502 | }} // namespaces | |
503 | ||
504 | [heading Description] | |
505 | ||
506 | This function returns the Jacobi elliptic function ['sd]. | |
507 | ||
508 | [optional_policy] | |
509 | ||
510 | This function is a trivial wrapper around __jacobi_elliptic, with: | |
511 | ||
512 | ['sd(u, k) = sn(u, k) / dn(u, k)] | |
513 | ||
514 | [graph jacobi_sd] | |
515 | ||
516 | [endsect] | |
517 | ||
518 | [section:jacobi_sn Jacobi Elliptic Function sn] | |
519 | ||
520 | [heading Synopsis] | |
521 | ||
522 | `` | |
523 | #include <boost/math/special_functions/jacobi_elliptic.hpp> | |
524 | `` | |
525 | ||
526 | namespace boost { namespace math { | |
527 | ||
528 | template <class T, class U> | |
529 | ``__sf_result`` jacobi_sn(T k, U u); | |
530 | ||
531 | template <class T, class U, class Policy> | |
532 | ``__sf_result`` jacobi_sn(T k, U u, const Policy& pol); | |
533 | ||
534 | }} // namespaces | |
535 | ||
536 | [heading Description] | |
537 | ||
538 | This function returns the Jacobi elliptic function ['sn]. | |
539 | ||
540 | [optional_policy] | |
541 | ||
542 | This function is a trivial wrapper around __jacobi_elliptic. | |
543 | ||
544 | [graph jacobi_sn] | |
545 | ||
546 | [endsect] | |
547 | ||
548 | ||
549 | [endsect] | |
550 |