1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Jacobi Zeta Function</title> 5<link rel="stylesheet" href="../../math.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Math Toolkit 2.12.0"> 8<link rel="up" href="../ellint.html" title="Elliptic Integrals"> 9<link rel="prev" href="ellint_d.html" title="Elliptic Integral D - Legendre Form"> 10<link rel="next" href="heuman_lambda.html" title="Heuman Lambda Function"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="ellint_d.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="heuman_lambda.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="math_toolkit.ellint.jacobi_zeta"></a><a class="link" href="jacobi_zeta.html" title="Jacobi Zeta Function">Jacobi Zeta Function</a> 28</h3></div></div></div> 29<h5> 30<a name="math_toolkit.ellint.jacobi_zeta.h0"></a> 31 <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.synopsis"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.synopsis">Synopsis</a> 32 </h5> 33<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">jacobi_zeta</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 34</pre> 35<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span> <span class="special">{</span> 36 37<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span> 38<a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">jacobi_zeta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">);</span> 39 40<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span> 41<a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">jacobi_zeta</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">k</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">phi</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span> 42 43<span class="special">}}</span> <span class="comment">// namespaces</span> 44</pre> 45<h5> 46<a name="math_toolkit.ellint.jacobi_zeta.h1"></a> 47 <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.description"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.description">Description</a> 48 </h5> 49<p> 50 This function evaluates the Jacobi Zeta Function <span class="emphasis"><em>Z(φ, k)</em></span> 51 </p> 52<div class="blockquote"><blockquote class="blockquote"><p> 53 <span class="inlinemediaobject"><img src="../../../equations/jacobi_zeta.svg"></span> 54 55 </p></blockquote></div> 56<p> 57 Please note the use of φ, and <span class="emphasis"><em>k</em></span> as the parameters, the 58 function is often defined as <span class="emphasis"><em>Z(φ, m)</em></span> with <span class="emphasis"><em>m 59 = k<sup>2</sup></em></span>, see for example <a href="http://mathworld.wolfram.com/JacobiZetaFunction.html" target="_top">Weisstein, 60 Eric W. "Jacobi Zeta Function." From MathWorld--A Wolfram Web Resource.</a> 61 Or else as <a href="https://dlmf.nist.gov/22.16#E32" target="_top"><span class="emphasis"><em>Z(x, k)</em></span></a> 62 with <span class="emphasis"><em>φ = am(x, k)</em></span>, where <span class="emphasis"><em>am</em></span> is the 63 <a href="https://dlmf.nist.gov/22.16#E1" target="_top">Jacobi amplitude function</a> 64 which is equivalent to <span class="emphasis"><em>asin(jacobi_elliptic(k, x))</em></span>. 65 </p> 66<p> 67 The return type of this function is computed using the <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result 68 type calculation rules</em></span></a> when the arguments are of different 69 types: when they are the same type then the result is the same type as the 70 arguments. 71 </p> 72<p> 73 Requires <span class="emphasis"><em>-1 <= k <= 1</em></span>, otherwise returns the result 74 of <a class="link" href="../error_handling.html#math_toolkit.error_handling.domain_error">domain_error</a> 75 (outside this range the result would be complex). 76 </p> 77<p> 78 The final <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can 79 be used to control the behaviour of the function: how it handles errors, 80 what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">policy 81 documentation for more details</a>. 82 </p> 83<p> 84 Note that there is no complete analogue of this function (where φ = π / 2) as 85 this takes the value 0 for all <span class="emphasis"><em>k</em></span>. 86 </p> 87<h5> 88<a name="math_toolkit.ellint.jacobi_zeta.h2"></a> 89 <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.accuracy"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.accuracy">Accuracy</a> 90 </h5> 91<p> 92 These functions are trivially computed in terms of other elliptic integrals 93 and generally have very low error rates (a few epsilon) unless parameter 94 φ 95is very large, in which case the usual trigonometric function argument-reduction 96 issues apply. 97 </p> 98<div class="table"> 99<a name="math_toolkit.ellint.jacobi_zeta.table_jacobi_zeta"></a><p class="title"><b>Table 8.68. Error rates for jacobi_zeta</b></p> 100<div class="table-contents"><table class="table" summary="Error rates for jacobi_zeta"> 101<colgroup> 102<col> 103<col> 104<col> 105<col> 106<col> 107</colgroup> 108<thead><tr> 109<th> 110 </th> 111<th> 112 <p> 113 GNU C++ version 7.1.0<br> linux<br> double 114 </p> 115 </th> 116<th> 117 <p> 118 GNU C++ version 7.1.0<br> linux<br> long double 119 </p> 120 </th> 121<th> 122 <p> 123 Sun compiler version 0x5150<br> Sun Solaris<br> long double 124 </p> 125 </th> 126<th> 127 <p> 128 Microsoft Visual C++ version 14.1<br> Win32<br> double 129 </p> 130 </th> 131</tr></thead> 132<tbody> 133<tr> 134<td> 135 <p> 136 Elliptic Integral Jacobi Zeta: Mathworld Data 137 </p> 138 </td> 139<td> 140 <p> 141 <span class="blue">Max = 0ε (Mean = 0ε)</span> 142 </p> 143 </td> 144<td> 145 <p> 146 <span class="blue">Max = 1.66ε (Mean = 0.48ε)</span> 147 </p> 148 </td> 149<td> 150 <p> 151 <span class="blue">Max = 1.66ε (Mean = 0.48ε)</span> 152 </p> 153 </td> 154<td> 155 <p> 156 <span class="blue">Max = 1.52ε (Mean = 0.357ε)</span> 157 </p> 158 </td> 159</tr> 160<tr> 161<td> 162 <p> 163 Elliptic Integral Jacobi Zeta: Random Data 164 </p> 165 </td> 166<td> 167 <p> 168 <span class="blue">Max = 0ε (Mean = 0ε)</span> 169 </p> 170 </td> 171<td> 172 <p> 173 <span class="blue">Max = 2.99ε (Mean = 0.824ε)</span> 174 </p> 175 </td> 176<td> 177 <p> 178 <span class="blue">Max = 3.96ε (Mean = 1.06ε)</span> 179 </p> 180 </td> 181<td> 182 <p> 183 <span class="blue">Max = 3.89ε (Mean = 0.824ε)</span> 184 </p> 185 </td> 186</tr> 187<tr> 188<td> 189 <p> 190 Elliptic Integral Jacobi Zeta: Large Phi Values 191 </p> 192 </td> 193<td> 194 <p> 195 <span class="blue">Max = 0ε (Mean = 0ε)</span> 196 </p> 197 </td> 198<td> 199 <p> 200 <span class="blue">Max = 2.92ε (Mean = 0.951ε)</span> 201 </p> 202 </td> 203<td> 204 <p> 205 <span class="blue">Max = 3.05ε (Mean = 1.13ε)</span> 206 </p> 207 </td> 208<td> 209 <p> 210 <span class="blue">Max = 2.52ε (Mean = 0.977ε)</span> 211 </p> 212 </td> 213</tr> 214</tbody> 215</table></div> 216</div> 217<br class="table-break"><h5> 218<a name="math_toolkit.ellint.jacobi_zeta.h3"></a> 219 <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.testing"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.testing">Testing</a> 220 </h5> 221<p> 222 The tests use a mixture of spot test values calculated using values calculated 223 at <a href="http://www.wolframalpha.com/" target="_top">Wolfram Alpha</a>, and random 224 test data generated using MPFR at 1000-bit precision and a deliberately naive 225 implementation in terms of the Legendre integrals. 226 </p> 227<h5> 228<a name="math_toolkit.ellint.jacobi_zeta.h4"></a> 229 <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.implementation"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.implementation">Implementation</a> 230 </h5> 231<p> 232 The implementation for Z(φ, k) first makes the argument φ positive using: 233 </p> 234<div class="blockquote"><blockquote class="blockquote"><p> 235 <span class="serif_italic"><span class="emphasis"><em>Z(-φ, k) = -Z(φ, k)</em></span></span> 236 </p></blockquote></div> 237<p> 238 The function is then implemented in terms of Carlson's integral R<sub>J</sub> 239using the 240 relation: 241 </p> 242<div class="blockquote"><blockquote class="blockquote"><p> 243 <span class="inlinemediaobject"><img src="../../../equations/jacobi_zeta.svg"></span> 244 245 </p></blockquote></div> 246<p> 247 There is one special case where the above relation fails: when <span class="emphasis"><em>k 248 = 1</em></span>, in that case the function simplifies to 249 </p> 250<div class="blockquote"><blockquote class="blockquote"><p> 251 <span class="serif_italic"><span class="emphasis"><em>Z(φ, 1) = sign(cos(φ)) sin(φ)</em></span></span> 252 </p></blockquote></div> 253<h6> 254<a name="math_toolkit.ellint.jacobi_zeta.h5"></a> 255 <span class="phrase"><a name="math_toolkit.ellint.jacobi_zeta.jacobi_zeta_example"></a></span><a class="link" href="jacobi_zeta.html#math_toolkit.ellint.jacobi_zeta.jacobi_zeta_example">Example</a> 256 </h6> 257<p> 258 A simple example comparing use of <a href="http://www.wolframalpha.com/" target="_top">Wolfram 259 Alpha</a> with Boost.Math (including much higher precision using Boost.Multiprecision) 260 is <a href="../../../../example/jacobi_zeta_example.cpp" target="_top">jacobi_zeta_example.cpp</a>. 261 </p> 262</div> 263<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 264<td align="left"></td> 265<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar 266 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, 267 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan 268 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, 269 Daryle Walker and Xiaogang Zhang<p> 270 Distributed under the Boost Software License, Version 1.0. (See accompanying 271 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 272 </p> 273</div></td> 274</tr></table> 275<hr> 276<div class="spirit-nav"> 277<a accesskey="p" href="ellint_d.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ellint.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="heuman_lambda.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 278</div> 279</body> 280</html> 281
