1\input texinfo 2@setfilename paritwine.info 3@include version.texi 4@settitle PariTwine @value{VERSION} 5 6@set AUTHORS Andreas Enge, Fredrik Johansson 7 8@iftex 9@afourpaper 10@end iftex 11 12@copying 13This manual is for PariTwine, a library to convert between multiprecision 14types of PARI/GP and external libraries, and to wrap functions from these 15libraries for use in GP, 16version @value{VERSION} of @value{UPDATED-MONTH}. 17 18Copyright @copyright{} 2018, 2019 Andreas Enge, Fredrik Johansson; 19@var{firstname}.@var{name}@@inria.fr 20 21@quotation 22Permission is granted to copy, distribute and/or modify this document 23under the terms of the GNU Free Documentation License, Version 1.3 or 24any later version published by the Free Software Foundation; with no 25Invariant Sections. A copy of the license is included in the section 26entitled ``GNU Free Documentation License.'' 27@end quotation 28@end copying 29 30@titlepage 31@title PariTwine 32@subtitle Edition @value{VERSION} 33@subtitle @value{UPDATED-MONTH} 34@author @value{AUTHORS} 35@page 36@vskip 0pt plus 1filll 37@insertcopying 38@end titlepage 39 40 41@ifnottex 42@node Top 43@top PariTwine 44 45This manual documents how to install and use the PariTwine library, 46version @value{VERSION} 47@end ifnottex 48 49@ifnothtml 50@contents 51@end ifnothtml 52 53@menu 54* Copying:: PariTwine Copying Conditions (GPL). 55* Introduction to PariTwine:: Brief introduction to PariTwine. 56* Installing PariTwine:: How to configure and compile PariTwine. 57* Using PariTwine:: How to use PariTwine in C code and GP. 58* Extending PariTwine:: How to add custom functionality to PariTwine. 59* GNU Free Documentation License:: 60@end menu 61 62@node Copying 63@unnumbered PariTwine Copying Conditions 64 65PariTwine is free software; you can redistribute it and/or modify it under 66the terms of the GNU General Public License as published by the 67Free Software Foundation; either version 2 of the License, or (at your 68option) any later version. 69 70PariTwine is distributed in the hope that it will be useful, but WITHOUT ANY 71WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 72FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 73more details. 74 75You should have received a copy of the GNU General Public License 76along with this program. If not, see @uref{http://www.gnu.org/licenses/}. 77 78 79@node Introduction to PariTwine 80@chapter Introduction to PariTwine 81 82PariTwine is a glue library between the system for computer algebra and 83number theory PARI/GP and a number of other mathematics libraries, 84currently 85GMP (@uref{https://gmplib.org/}), 86GNU MPFR (@uref{http://www.mpfr.org/}), 87GNU MPC (@uref{http://www.multiprecision.org/mpc/}), 88FLINT (@uref{http://www.flintlib.org/}), 89ARB (@uref{http://arblib.org/}) 90and 91CMH (@uref{http://cmh.gforge.inria.fr/}). 92 93PariTwine provides C functions to convert back and forth between basic types 94of PARI/GP and the other libraries, and it wraps a number of functions from 95the external libraries to be called from the PARI library with arguments 96of PARI type (otherwise said, @samp{GEN}). 97Finally PariTwine makes these wrapped functions available to GP scripts 98by installing them into the interpreter. 99 100 101 102@node Installing PariTwine 103@chapter Installing PariTwine 104 105To build PariTwine, you first have to install PARI/GP and all the desired 106libraries that you wish to wrap (at least GMP, and at your choice any of 107GNU MPFR, GNU MPC, FLINT, ARB and CMH) on your computer. 108You need a C compiler and a standard Unix @samp{make} program, plus some 109other standard Unix utility programs. 110 111 112@section Basic installation instructions 113 114Here are the steps needed to install the library on Unix systems: 115 116@enumerate 117@item 118@samp{tar xzf paritwine-@value{VERSION}.tar.gz} 119 120@item 121@samp{cd paritwine-@value{VERSION}} 122 123@item 124@samp{./configure} 125 126if dependencies are installed into standard directories, that is, directories 127that are searched by default by the compiler and the linking tools. 128 129@samp{./configure --with-gmp=DIR} 130 131is used to indicate a different location where GMP is installed. 132 133@samp{./configure --with-pari=DIR} 134 135is used to indicate a different location where PARI/GP is installed. 136 137@samp{./configure --with-mpfr=DIR} 138 139is used to indicate a different location where MPFR is installed. 140 141@samp{./configure --with-mpc=DIR} 142 143is used to indicate a different location where MPC is installed. 144 145@samp{./configure --with-flint=DIR} 146 147is used to indicate a different location where FLINT is installed. 148 149@samp{./configure --with-arb=DIR} 150 151is used to indicate a different location where ARB is installed. 152 153@samp{./configure --with-cmh=DIR} 154 155is used to indicate a different location where CMH is installed. 156 157For each package, separate search paths for the header and library 158files can be specified as follows: 159 160@samp{./configure --with-gmp-include=DIR} 161 162@samp{./configure --with-gmp-lib=DIR} 163 164and analogously for the other packages. 165 166 167Another useful parameter is @samp{--prefix}, which can be used to 168specify an alternative installation location instead of 169@file{/usr/local}; see @samp{make install} below. 170 171Use @samp{./configure --help} for an exhaustive list of parameters. 172 173@item 174@samp{make} 175 176This compiles PariTwine in the working directory. 177 178@item 179@samp{make check} 180 181This executes a number of tests on the compiled project. 182If you get error messages, please report them to the authors. 183 184@item 185@samp{make install} 186 187This copies the header files @file{paritwine-config.h} and 188@file{paritwine.h} into the directory @file{/usr/local/include}, 189the static library @file{libparitwine.a} and the dynamic library 190@file{libparitwine.so} into the directory @file{/usr/local/lib}, 191the GP script @file{paritwine.gp} into the directory 192@file{/usr/local/share/paritwine} and 193the manual @file{paritwine.info} into the directory 194@file{/usr/local/share/info}. 195If you passed the @samp{--prefix} option to @samp{configure}, the prefix 196directory given as argument to @samp{--prefix} is used instead of 197@file{/usr/local}. 198Note that you need write permissions on the prefix directory and its 199subdirectories. 200 201@end enumerate 202 203 204@section Other `make' Targets 205 206There are some other useful make targets: 207 208@itemize @bullet 209@item 210@samp{pdf} 211 212This creates a PDF version of the manual in @file{doc/paritwine.pdf}. 213 214@item 215@samp{html} 216 217This creates an HTML version of the manual, in several pages in the 218directory @file{doc/paritwine.html}; if you want only one output HTML file, 219then type @samp{makeinfo --html --no-split paritwine.texi} instead. 220 221@item 222@samp{clean} 223 224This deletes all object files and archive files, but not the configuration 225files. 226 227@item 228@samp{distclean} 229 230This has the same effect as @samp{make clean}, but it additionally deletes 231the configuration files created by @samp{./configure}. 232 233@item 234@samp{uninstall} 235 236This deletes all files copied by @samp{make install}. 237@end itemize 238 239 240 241@node Using PariTwine 242@chapter Using PariTwine 243 244 245PariTwine consists of essentially three parts: 246@itemize 247@item 248C functions for converting between the basic PARI types and the types 249of external libraries; 250@item 251C functions for wrapping functions of external libraries to be called with 252arguments of PARI types; 253@item 254a GP script to call these functions from within the GP command interpreter. 255@end itemize 256 257The following three sections describe these functionalities in order. 258 259 260@section Conversion functions 261 262Basically, for each external type @code{foo_t}, we provide two functions: 263 264@deftypefun void foo_set_GEN (foo_t @var{z}, GEN @var{x}) 265Set the value of @var{z} from the PARI variable @var{x}, which needs to be 266of compatible type; otherwise, a PARI error is raised. 267@end deftypefun 268 269@deftypefun GEN foo_get_GEN (foo_t @var{z}) 270Create from @var{z} a PARI object (of C type @code{GEN}) of suitable 271PARI type on the PARI stack and return it. 272@end deftypefun 273 274Functions operating on floating point numbers may take as additional argument 275a rounding mode and return an integer indicating the effective direction of 276rounding. 277 278 279@subsection Conversion functions for scalar types 280 281@deftypefun void mpz_set_GEN (mpz_t @var{z}, GEN @var{x}) 282@deftypefunx void fmpz_set_GEN (fmpz_t @var{z}, GEN @var{x}) 283Set the GMP or FLINT integer variable @var{z} to the value of @var{x}, 284which must be of PARI type @code{t_INT}. 285@end deftypefun 286 287@deftypefun GEN mpz_get_GEN (mpz_t @var{z}) 288@deftypefunx GEN fmpz_get_GEN (fmpz_t @var{z}) 289From the GMP or FLINT integer @var{z} create a variable of PARI type 290@code{t_INT} on the PARI stack and return it. 291@end deftypefun 292 293 294@deftypefun void mpq_set_GEN (mpq_t @var{z}, GEN @var{x}) 295@deftypefunx void fmpq_set_GEN (fmpq_t @var{z}, GEN @var{x}) 296Set the GMP or FLINT rational variable @var{z} to the value of @var{x}, 297which must be of PARI type @code{t_INT} or @code{t_FRAC}. 298@end deftypefun 299 300@deftypefun GEN mpq_get_GEN (mpq_t @var{z}) 301@deftypefunx GEN fmpq_get_GEN (fmpq_t @var{z}) 302From the GMP or FLINT rational @var{z} create a variable of PARI type 303@code{t_FRAC} on the PARI stack and return it. 304@end deftypefun 305 306 307@deftypefun int mpfr_set_GEN (mpfr_t @var{z}, GEN @var{x}, mpfr_rnd_t @var{rnd}) 308Set the MPFR floating point variable @var{z} to the value of @var{x}, 309which must be of PARI type @code{t_INT}, @code{t_FRAC} or @code{t_REAL}. 310The variable @var{z} must have been initialised to a given precision before, 311and the assigned value is the value of @var{x} rounded according to the 312rounding mode @var{rnd}; one possible choice is to use the constant 313@code{MPFR_RNDN} for rounding to nearest. 314The return value has the usual semantics of MPFR functions and indicates the 315effective direction of rounding: 0 if the result is exactly represented 316without rounding, a positive integer if the result is larger than the exact 317value and a negative integer if the result is smaller than the exact value. 318@end deftypefun 319 320@deftypefun GEN mpfr_get_GEN (mpfr_t @var{z}) 321From the MPFR floating point number @var{z} create a variable of PARI type 322@code{t_REAL} on the PARI stack and return it. The precision of the created 323variable is the minimal possible precision in PARI (a multiple of the word 324size) that is at least the bit precision of @var{z}. 325@end deftypefun 326 327 328@deftypefun int mpc_set_GEN (mpc_t @var{z}, GEN @var{x}, mpfr_rnd_t @var{rnd}) 329Set the MPC floating point variable @var{z} to the value of @var{x}, 330which must be of PARI type @code{t_INT}, @code{t_FRAC}, @code{t_REAL} 331or @code{t_COMPLEX}. 332The variable @var{z} must have been initialised to a given precision before, 333and the assigned value is the value of @var{x} rounded according to the 334rounding mode @var{rnd}; one possible choice is to use the constant 335@code{MPC_RNDNN} for rounding both the real and the imaginary part to nearest. 336The return value has the usual semantics of MPC functions and indicates the 337effective direction of rounding for the real and the imaginary part; 338for more details, see the MPC documentation. 339@end deftypefun 340 341@deftypefun GEN mpc_get_GEN (mpc_t @var{z}) 342From the MPC floating point number @var{z} create a variable of PARI type 343@code{t_COMPLEX} on the PARI stack and return it. The real and imaginary 344parts of the result are created using @code{mpfr_get_GEN}. 345So in particular their precisions are determined separately as the minimal 346possible precisions in PARI (multiples of the word size) that are at least 347the bit precisions of the corresponding parts of @var{z}. 348@end deftypefun 349 350 351@subsection Conversion functions for ball types 352 353@deftypefun void arf_set_GEN (arf_t @var{z}, GEN @var{x}) 354@deftypefunx void mag_set_GEN (mag_t @var{z}, GEN @var{x}) 355ARB implements two real floating point types, @code{arf_t} for holding 356the centre point of a real interval in ball representation at arbitrary 357precision, and @code{mag_t} for holding the radius of the interval 358(the ``magnitude of the error'') at small fixed precision. 359These two functions set the ARB floating point variable @var{z} to the 360value of @var{x}, which must be of PARI type @code{t_INT} or @code{t_REAL}. 361In the case of @var{z} of type @code{arf_t}, its precision is chosen minimal 362such that @var{x} can be stored exactly without rounding. 363In the case of @var{z} of type @code{mag_t}, the value is rounded up 364if necessary. 365@end deftypefun 366 367 368@deftypefun GEN arf_get_GEN (arf_t @var{z}, long @var{prec}) 369@deftypefunx GEN mag_get_GEN (mag_t @var{z}) 370From the ARB floating point number @var{z} create a PARI variable on the 371PARI stack and return it. If the value of @var{z} is 0, then the return 372value is of PARI type @code{t_INT}. 373Otherwise it is of PARI type @code{t_REAL}, and in the case of 374@code{arf_get_GEN}, the result is rounded to at least a precision of 375@var{prec} bits (precisely, to the next multiple of the word size); 376in the case of @code{mag_get_GEN}, a @code{t_REAL} of the minimal precision 377to hold the exact value of @var{z} is returned. 378@end deftypefun 379 380@deftypefun void arb_set_GEN (arb_t @var{z}, GEN @var{x}, long @var{prec}) 381Set the ARB real ball variable @var{z} to the value of @var{x}, which can 382be of PARI type @code{t_INT}, @code{t_FRAC}, @code{t_REAL} or @code{t_VEC}. 383If @var{x} is not of PARI type @code{t_VEC}, then the interval 384has as centre @var{x} rounded to precision @var{prec} and is taken of minimal 385size to handle the rounding error. 386 387If @var{x} is of PARI type @code{t_VEC}, it is supposed to represent an 388interval itself, that is, it contains two elements representing the centre 389and the radius. These are transformed into an @code{arb_t} interval by calls 390to @code{arf_set_GEN} and @code{mag_set_GEN}, respectively, on the two 391components. This transformation does not use the parameter @var{prec} and 392thus preserves exactly the centre, and it potentially rounds up the radius. 393@end deftypefun 394 395@deftypefun GEN arb_get_GEN (arb_t @var{z}, long @var{prec}) 396From the ARB real ball @var{z}, create a PARI variable on the PARI stack 397and return it. The result is of PARI type @code{t_VEC} with two elements 398and contains the interval in @var{z} as obtained by calls to 399@code{arf_get_GEN} and @code{mag_get_GEN}, respectively. 400@end deftypefun 401 402Notice that in a sequence of alternating calls to @code{arb_get_GEN} and 403@code{arb_set_GEN}, starting with either of them, and with the same value 404of @var{prec}, the first call may result in rounding if the value of 405@var{prec} is not large enough, or if the sequence starts with the conversion 406of a @code{t_FRAC}. In this case, the rounded ball always contains the 407input value. The subsequent calls will be lossless. 408 409@deftypefun void acb_set_GEN (acb_t @var{z}, GEN @var{x}, long @var{prec}) 410In ARB, complex ``balls'' of type @code{acb_t} are implemented as a pair 411of real intervals of type @code{arb_t} representing the real and imaginary 412parts; so they are in fact rectangles in the complex plane. 413The same complex rectangle is represented in PARI in a ``transposed'' form, 414as a @code{t_VEC} with two elements of type @code{t_COMPLEX}, the first 415of which represents the centre of the rectangle, and the second of which 416represents the two radii in the real and the imaginary direction. 417 418If @var{x} is of PARI type @code{t_COMPLEX}, the resulting value of @var{z} 419is the smallest complex ball with centre @var{x} at precision @var{prec}. 420 421If @var{x} is of PARI type @code{t_INT}, @code{t_FRAC} or @code{t_REAL}, 422the imaginary part of @var{z} is set to an exact 0, while its real part 423is set to a real ball by a call to @code{arb_set_GEN (z, x, prec)}. 424 425If @var{x} is of PARI type @code{t_VEC}, it is interpreted as a complex 426rectangle that is transformed into the corresponding @code{acb_t} rectangle 427@var{z} by calls to @code{arb_set_GEN}. This operation does not use the 428parameter @var{prec}, so that it preserves exactly the centre of the complex 429ball, while the real and imaginary radii may be rounded up. 430@end deftypefun 431 432 433@deftypefun GEN acb_get_GEN (acb_t @var{z}, long @var{prec}) 434From the ARB complex ball @var{z}, create a PARI variable on the PARI stack 435and return it. The result is of PARI type @code{t_VEC} with two elements, 436each of which are of type @code{t_COMPLEX}; it represents the same complex 437rectangle as @var{z}, with the real and imaginary part of its centre 438rounded through calls to @code{arf_get_GEN}. 439 440Notice that as for real balls of type @code{arb_t}, in a sequence of 441alternating calls to @code{acb_set_GEN} and @code{acb_get_GEN} with 442the same precision, only the first call may lead to rounding (in which 443case the output ball contains the input ball), while all following ones 444are lossless. 445@end deftypefun 446 447 448@subsection Initialisation on the PARI stack 449 450For the GNU MPFR and GNU MPC libraries, the following initialisation 451functions, the names of which start with the prefix @code{pari_}, have a 452special behaviour: Exactly like their counterparts without the @code{pari_} 453prefix from the respective libraries, they initialise a variable of type 454@code{mpfr_t} or @code{mpc_t}, but they allocate their mantissae on the PARI 455stack. So they should not be freed with calls to @code{mpfr_clear} or 456@code {mpc_clear}, but with the usual PARI stack handling (also known as 457``avma magic''). They are used internally inside the wrappers for 458functions from MPFR and MPC, but they may also be more efficient for use 459in C code relying on @code{libpari} and requiring handling of the PARI stack 460anyway. 461 462@deftypefun void pari_mpfr_init2 (mpfr_t z, mpfr_prec_t prec) 463@deftypefunx void pari_mpc_init2 (mpc_t z, mpfr_prec_t prec) 464@deftypefunx void pari_mpc_init3 (mpc_t z, mpfr_prec_t prec_re, mpfr_prec_t prec_im) 465These are the counterparts of @code{mpfr_init2}, @code{mpc_init2} and 466@code{mpc_init3}. All of them take additional arguments to determine the 467bit precisions of the numbers (the @code{init2} variants) or of the real 468and imaginary part separately (@code{mpc_init3}). 469@end deftypefun 470 471There are also functions combining initialisations of MPFR or MPC numbers 472on the PARI stack with assignments of PARI numbers. 473 474@deftypefun void pari_mpfr_init_set_GEN (mpfr_t z, GEN x, mpfr_prec_t default_prec) 475Conceptually, this function combines a call to @code{pari_mpfr_init2} and 476@code{mpfr_set_GEN}. However, the precision handling is special and depends on 477the type of @var{x}: 478If @var{x} is of the floating point type @code{t_REAL}, the 479precision used for initialising @var{z} is the same as that of @var{x}, 480so that the result fits without rounding. 481If @var{x} is of an exact type (@code{t_INT} or @code{t_FRAC}), however, the 482value of @var{default_prec} is used for initialising @var{z}. 483@end deftypefun 484 485@deftypefun void pari_mpc_init_set_GEN (mpc_t z, GEN x, mpfr_prec_t default_prec) 486This function calls @code{pari_mpfr_init_set_GEN} to initialise the real 487part of @var{z} and to assign the real part of @var{x} to it, and to 488separately initialise the complex part of @var{z} and to assign the complex 489part of @var{x} to it. Notice that the real and complex parts of @var{x} may 490have as types arbitrary combinations of @code{t_INT}, @code{t_FRAC} and 491@code{t_REAL}, and that the precision is determined by 492@code{pari_mpfr_init_set_GEN} independently for each part. 493@end deftypefun 494 495 496@section Wrapped library functions 497 498Besides providing functions to convert between PARI types and types of 499external libraries, a goal of PariTwine is to wrap functions from the 500external libraries so that they can be called directly from PARI with 501PARI type arguments, returning a PARI type result. 502 503Roughly speaking, if 504@code{void @var{lib}_@var{func} (@var{lib_t} @var{z}, @var{lib_t} @var{x}, 505@var{lib_t} @var{y}, ...)} 506is a function from the library @var{lib} computing the mathematical function 507@var{func} in the arguments @var{x}, @var{y}, ... and assigning the result 508to @var{z}, where all these variables are of some type @var{lib_t} defined 509in @var{lib}, we wrap it to obtain a function 510@code{GEN pari_@var{lib}_@var{func} (GEN @var{x}, GEN @var{y}, ..., 511long @var{prec})} that uses 512@code{@var{lib}_@var{func}} to compute @var{func} on the PARI type arguments 513@var{x}, @var{y}, ... and that returns the result as a PARI object. 514The additional parameter @var{prec} determines the working precision (in bits) 515used in the external library and also the precision of the result. 516Usually functions in GNU MPFR and GNU MPC take as an additional parameter 517a rounding mode; this parameter is dropped in the wrapped function, where 518rounding to nearest is used. 519Functions in MPFR and MPC also usually have an @code{int} return value, which 520indicates the effective rounding direction of the result; this is discarded. 521For instance, the MPFR function computing the Riemann zeta function, 522@code {int mpfr_zeta (mpfr_t @var{z}, mpfr_t @var{x}, mpfr_rnd_t @var{rnd})} 523is wrapped to become 524@code {GEN pari_mpfr_zeta (GEN @var{x}, GEN @var{y}, long @var{prec})}. 525 526Currently, the following wrapped functions are available in PariTwine; 527see @ref{Extending PariTwine} for instructions on how to add more functions. 528 529@deftypefun GEN pari_mpfr_add (GEN x, GEN y, long prec) 530@deftypefunx GEN pari_mpfr_sub (GEN x, GEN y, long prec) 531@deftypefunx GEN pari_mpfr_mul (GEN x, GEN y, long prec) 532@deftypefunx GEN pari_mpfr_sqr (GEN x, long prec) 533@deftypefunx GEN pari_mpfr_div (GEN x, GEN y, long prec) 534@deftypefunx GEN pari_mpfr_sqrt (GEN x, long prec) 535@deftypefunx GEN pari_mpfr_rec_sqrt (GEN x, long prec) 536@deftypefunx GEN pari_mpfr_cbrt (GEN x, long prec) 537@deftypefunx GEN pari_mpfr_pow (GEN x, GEN y, long prec) 538@deftypefunx GEN pari_mpfr_log (GEN x, long prec) 539@deftypefunx GEN pari_mpfr_log2 (GEN x, long prec) 540@deftypefunx GEN pari_mpfr_log10 (GEN x, long prec) 541@deftypefunx GEN pari_mpfr_exp (GEN x, long prec) 542@deftypefunx GEN pari_mpfr_exp2 (GEN x, long prec) 543@deftypefunx GEN pari_mpfr_exp10 (GEN x, long prec) 544@deftypefunx GEN pari_mpfr_sin (GEN x, long prec) 545@deftypefunx GEN pari_mpfr_cos (GEN x, long prec) 546@deftypefunx GEN pari_mpfr_tan (GEN x, long prec) 547@deftypefunx GEN pari_mpfr_sec (GEN x, long prec) 548@deftypefunx GEN pari_mpfr_csc (GEN x, long prec) 549@deftypefunx GEN pari_mpfr_cot (GEN x, long prec) 550@deftypefunx GEN pari_mpfr_acos (GEN x, long prec) 551@deftypefunx GEN pari_mpfr_asin (GEN x, long prec) 552@deftypefunx GEN pari_mpfr_atan (GEN x, long prec) 553@deftypefunx GEN pari_mpfr_cosh (GEN x, long prec) 554@deftypefunx GEN pari_mpfr_sinh (GEN x, long prec) 555@deftypefunx GEN pari_mpfr_tanh (GEN x, long prec) 556@deftypefunx GEN pari_mpfr_sech (GEN x, long prec) 557@deftypefunx GEN pari_mpfr_csch (GEN x, long prec) 558@deftypefunx GEN pari_mpfr_coth (GEN x, long prec) 559@deftypefunx GEN pari_mpfr_acosh (GEN x, long prec) 560@deftypefunx GEN pari_mpfr_asinh (GEN x, long prec) 561@deftypefunx GEN pari_mpfr_atanh (GEN x, long prec) 562@deftypefunx GEN pari_mpfr_log1p (GEN x, long prec) 563@deftypefunx GEN pari_mpfr_expm1 (GEN x, long prec) 564@deftypefunx GEN pari_mpfr_eint (GEN x, long prec) 565@deftypefunx GEN pari_mpfr_li2 (GEN x, long prec) 566@deftypefunx GEN pari_mpfr_gamma (GEN x, long prec) 567@deftypefunx GEN pari_mpfr_lngamma (GEN x, long prec) 568@deftypefunx GEN pari_mpfr_digamma (GEN x, long prec) 569@deftypefunx GEN pari_mpfr_zeta (GEN x, long prec) 570@deftypefunx GEN pari_mpfr_erf (GEN x, long prec) 571@deftypefunx GEN pari_mpfr_erfc (GEN x, long prec) 572@deftypefunx GEN pari_mpfr_j0 (GEN x, long prec) 573@deftypefunx GEN pari_mpfr_j1 (GEN x, long prec) 574@deftypefunx GEN pari_mpfr_y0 (GEN x, long prec) 575@deftypefunx GEN pari_mpfr_y1 (GEN x, long prec) 576@deftypefunx GEN pari_mpfr_fma (GEN x, GEN y, GEN z, long prec) 577@deftypefunx GEN pari_mpfr_fms (GEN x, GEN y, GEN z, long prec) 578@deftypefunx GEN pari_mpfr_agm (GEN x, GEN y, long prec) 579@deftypefunx GEN pari_mpfr_hypot (GEN x, GEN y, long prec) 580@deftypefunx GEN pari_mpfr_ai (GEN x, long prec) 581These functions take arguments of types @code{t_INT}, @code{t_FRAC} or 582@code{t_REAL} and use GNU MPFR to return a result of type @code{t_REAL}. 583@end deftypefun 584 585@deftypefun GEN pari_mpfr_fac_ui (unsigned long int t, long prec) 586This function takes as argument a small unsigned integer and 587returns its factorial as a number of type @code{t_REAL}. 588@end deftypefun 589 590@deftypefun GEN pari_mpfr_jn (long int i, GEN x, long prec) 591@deftypefunx GEN pari_mpfr_yn (long int i, GEN x, long prec) 592These functions take as arguments a small integer and a number of type 593@code{t_INT}, @code{t_FRAC} or @code{t_REAL} and return a Bessel 594function of the given order of the first or second kind in the argument. 595@end deftypefun 596 597@deftypefun GEN pari_mpc_add (GEN x, GEN y, long prec) 598@deftypefunx GEN pari_mpc_sub (GEN x, GEN y, long prec) 599@deftypefunx GEN pari_mpc_mul (GEN x, GEN y, long prec) 600@deftypefunx GEN pari_mpc_sqr (GEN x, long prec) 601@deftypefunx GEN pari_mpc_fma (GEN x, GEN y, GEN z, long prec) 602@deftypefunx GEN pari_mpc_div (GEN x, GEN y, long prec) 603@deftypefunx GEN pari_mpc_sqrt (GEN x, long prec) 604@deftypefunx GEN pari_mpc_pow (GEN x, GEN y, long prec) 605@deftypefunx GEN pari_mpc_exp (GEN x, long prec) 606@deftypefunx GEN pari_mpc_log (GEN x, long prec) 607@deftypefunx GEN pari_mpc_log10 (GEN x, long prec) 608@deftypefunx GEN pari_mpc_sin (GEN x, long prec) 609@deftypefunx GEN pari_mpc_cos (GEN x, long prec) 610@deftypefunx GEN pari_mpc_tan (GEN x, long prec) 611@deftypefunx GEN pari_mpc_sinh (GEN x, long prec) 612@deftypefunx GEN pari_mpc_cosh (GEN x, long prec) 613@deftypefunx GEN pari_mpc_tanh (GEN x, long prec) 614@deftypefunx GEN pari_mpc_asin (GEN x, long prec) 615@deftypefunx GEN pari_mpc_acos (GEN x, long prec) 616@deftypefunx GEN pari_mpc_atan (GEN x, long prec) 617@deftypefunx GEN pari_mpc_asinh (GEN x, long prec) 618@deftypefunx GEN pari_mpc_acosh (GEN x, long prec) 619@deftypefunx GEN pari_mpc_atanh (GEN x, long prec) 620These functions take arguments of types @code{t_INT}, @code{t_FRAC}, 621@code{t_REAL} or @code{t_COMPLEX} and use GNU MPC to return a result 622of type @code{t_COMPLEX}. 623@end deftypefun 624 625@deftypefun GEN pari_mpc_abs (GEN x, long prec) 626@deftypefunx GEN pari_mpc_norm (GEN x, long prec) 627These functions take arguments of types @code{t_INT}, @code{t_FRAC}, 628@code{t_REAL} or @code{t_COMPLEX} and use MPC to return a result 629of type @code{t_REAL}. 630@end deftypefun 631 632@c @deftypefun GEN pari_mpc_rootofunity (unsigned long int n, unsigned long int k, long prec) 633@c This function takes two small unsigned integers @math{n} and @math{k} 634@c and returns the root of unity @math{e^{2 \pi i k / n}}. 635@c @end deftypefun 636 637@deftypefun GEN pari_cmh_I2I4I6I10 (GEN tau, long prec) 638@deftypefunx GEN pari_cmh_4theta (GEN tau, long prec) 639@deftypefunx GEN pari_cmh_10theta2 (GEN tau, long prec) 640These functions do not completely fit the generic description above and 641might change in the future. They take as input a 2x2-matrix @var{tau} of 642type @code{t_MAT} with entries of type @code{t_COMPLEX}, which is supposed 643to be an element of the Siegel half space; in particular, @var{tau} is 644symmetric, and its lower left entry is not used. 645They use the CMH library to compute and return a vector of type @code{t_VEC}, 646containing four or ten elements of type @code{t_COMPLEX}. 647The first function computes the Igusa-Clebsch invariants @math{I_2}, 648@math{I_4}, @math{I_6} and @math{I_{10}}. 649The second function computes the first four theta constants. 650The third function computes the squares of the ten non-zero theta constants. 651@end deftypefun 652 653@deftypefun GEN pari_acb_add (GEN x, GEN y, long prec) 654@deftypefunx GEN pari_acb_sub (GEN x, GEN y, long prec) 655@deftypefunx GEN pari_acb_mul (GEN x, GEN y, long prec) 656@deftypefunx GEN pari_acb_div (GEN x, GEN y, long prec) 657@deftypefunx GEN pari_acb_neg (GEN x, long prec) 658@deftypefunx GEN pari_acb_conj (GEN x, long prec) 659@deftypefunx GEN pari_acb_exp (GEN x, long prec) 660@deftypefunx GEN pari_acb_log (GEN x, long prec) 661@deftypefunx GEN pari_acb_atan (GEN x, long prec) 662@deftypefunx GEN pari_acb_sin (GEN x, long prec) 663@deftypefunx GEN pari_acb_cos (GEN x, long prec) 664@deftypefunx GEN pari_acb_gamma (GEN x, long prec) 665@deftypefunx GEN pari_acb_digamma (GEN x, long prec) 666@deftypefunx GEN pari_acb_zeta (GEN s, long prec) 667@deftypefunx GEN pari_acb_hurwitz_zeta (GEN s, GEN z, long prec) 668@deftypefunx GEN pari_acb_modular_eta (GEN tau, long prec) 669@deftypefunx GEN pari_acb_modular_j (GEN tau, long prec) 670@deftypefunx GEN pari_acb_modular_delta (GEN tau, long prec) 671@deftypefunx GEN pari_acb_elliptic_p (GEN z, GEN tau, long prec) 672@deftypefunx GEN pari_acb_elliptic_inv_p (GEN z, GEN tau, long prec) 673@deftypefunx GEN pari_acb_elliptic_zeta (GEN z, GEN tau, long prec) 674@deftypefunx GEN pari_acb_elliptic_sigma (GEN z, GEN tau, long prec) 675 676These functions take arguments of types @code{t_INT}, @code{t_FRAC}, 677@code{t_REAL}, @code{t_COMPLEX} or @code{t_VEC} and return a result of 678type @code{t_VEC}. Here the @code{t_VEC} are vectors with two complex 679components, representing the centre and the radius of a complex rectangle. 680@end deftypefun 681 682Notice that unless the default precision is changed in between, it is safe 683to compose these functions operating on complex rectangles, since the 684conversion back and forth between GP and ARB is then lossless. 685In this way it is possible to build more complicated expressions using 686interval arithmetic all along, such that the final result contains the 687exact mathematical value. 688 689 690@deftypefun GEN pari_acb_modular_theta (GEN z, GEN tau, long prec) 691The function takes the same type of arguments as the previous ones, 692but instead of returning one result, it returns a @code{t_VEC} with 693four entries (each of which is a @code{t_VEC} representing a complex 694rectangle). It computes the four Jacobi theta functions 695@math{\theta_1}, @math{\theta_2}, @math{\theta_3} and @math{\theta_4} 696(in arb notation), which correspond to @math{-i \theta_{1,1}}, 697@math{\theta_{1,0}}, @math{\theta_{0,0}} and @math{\theta_{0,1}} 698(in notation using half-integral characteristics). 699@end deftypefun 700 701 702@deftypefun GEN pari_acb_modular_eisenstein (GEN tau, long n, long prec) 703As the previous function, this one returns a @code{t_VEC}, but this time 704of length @var{n}, of complex rectangles. The vector contains the @var{n} 705first Eisenstein series @math{G_4}, @math{G_6}, @math{G_8},@dots{} 706@end deftypefun 707 708 709@deftypefun GEN pari_fmpz_numbpart (GEN x) 710@deftypefunx GEN pari_arb_numbpart (GEN x, long prec) 711 712These functions take an argument @var{x} of type @code{t_INT} and compute 713the partition number of @var{x}. The first one uses FLINT to return the 714exact @code{t_INT}, the second one uses ARB to return a real ball of type 715@code{t_VEC} at the given precision. 716@end deftypefun 717 718@section Calling wrapped functions from GP 719 720PariTwine provides a GP snippet, @code{paritwine.gp}, which can be used 721to integrate the wrapped functions from the external libraries into the 722GP command interpreter. This file is copied by @code{make install} into the 723subdirectory @code{share/paritwine} of the installation prefix 724(@code{/usr/local}, unless specified otherwise). 725To use it, issue the command 726@verbatim 727\r /usr/local/share/paritwine/paritwine.gp 728@end verbatim 729 730Roughly speaking, if 731@code{void @var{lib}_@var{func} (@var{lib_t} @var{z}, @var{lib_t} @var{x}, 732@var{lib_t} @var{y}, ...)} 733is a function from the library @var{lib}, 734wrapped as the C library function 735@code{GEN pari_@var{lib}_@var{func} (GEN @var{x}, GEN @var{y}, ..., 736long @var{prec})} on PARI types, 737inclusion of the above GP snippet makes a GP function available 738that can be called as 739@code{@var{lib}_@var{func} (x, y, ...)}. 740The parameter @var{prec} is omitted and replaced by the current default 741bit precision. 742For instance, @code{mpfr_zeta (2)} uses GNU MPFR to compute the Riemann 743zeta function in the argument 2 at the current default precision. 744 745 746 747@node Extending PariTwine 748@chapter Extending PariTwine 749 750For wrapping a new function from an external library, one needs to add the 751wrapper function to one of the C files, a process that shall be illustrated 752with the function @code{int mpfr_zeta (mpfr_t z, mpfr_t x, mpfr_rnd_t rnd)} 753(which already exists in PariTwine). The wrapper function could look like 754this: 755@verbatim 756GEN pari_mpfr_zeta (GEN x, long prec) 757{ 758 pari_sp ltop = avma; 759 mpfr_prec_t p = prec; 760 mpfr_t z, z1; 761 762 pari_mpfr_init2 (z, p); 763 pari_mpfr_init_set_GEN (z1, x, p); 764 765 mpfr_zeta (z, z1, MPFR_RNDN); 766 767 return gerepileuptoleaf (ltop, mpfr_get_GEN (z)); 768} 769@end verbatim 770 771The first line memorises the state of the PARI stack in the variable 772@code{ltop}. The second line casts the PARI precision of type @code{long} 773into an MPFR precision (which could be dropped, since in general the latter 774is also @code{long}). 775The next line declares two variables, @code{z1} to hold the MPFR version 776of the argument @code{x}, and @code{z} to hold the result of the computation. 777Then @code{z} is initialised on the PARI stack with the desired precision, 778and @code{z1} is initialised and set to @code{x}. Hereby if @code{x} is of 779type @code{t_INT} or @code{t_FRAC}, the precision @code{prec} is used; if it 780is of type @code{t_REAL}, its own precision is used, which may be different 781from @code{prec}. 782Then the function @code{mpfr_zeta} is called with rounding to nearest 783(@code{MPFR_RNDN}), which puts the result of the computation into @code{z}. 784The subexpression @code{mpfr_get_GEN (z)} adds an object of type 785@code{t_REAL} to the PARI stack with the same value as @code{z}. 786The surrounding call to @code{gerepileupto} deletes everything between 787@code{ltop} and this result on the PARI stack and returns a pointer to 788the result. So the effect of the function on the PARI stack is exactly 789to have added this result. 790 791The modified version of PariTwine is compiled and installed using 792@code{make install}. 793 794The next (optional) step is to make this new library function available 795in the GP command interpreter. This can be done issuing the command 796@verbatim 797install ("pari_mpfr_zeta", "Gb", "mpfr_zeta", "/usr/local/lib/libparitwine.so"); 798@end verbatim 799@noindent 800It takes the function @code{pari_mpfr_zeta} from the shared library 801@code{/usr/local/lib/libparitwine.so} and installs it under the name of 802@code{mpfr_zeta}. The code @code{Gb} indicates that the function takes one 803argument of type @code{GEN} and also the current default bit precision of the 804GP environment; the latter is added automatically and need not be specified 805in the function call. The return value of type @code{GEN} is also understood. 806So now it is possible to call 807@verbatim 808Pisquareoversix = mpfr_zeta (2); 809@end verbatim 810@noindent 811in the GP interpreter. 812 813If you have extended PariTwine by wrapping more functions or adding a new 814external library, you may wish to contact the authors to have your 815modifications included into a future release. 816 817 818@node GNU Free Documentation License 819@appendix GNU Free Documentation License 820@include fdl-1.3.texi 821 822@bye 823 824