ceph/src/boost/libs/math/doc/sf/jacobi_elliptic.qbk

   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