vasilito
ff4ff35918
Red Bear OS is a full fork. All sources must be available from git clone with zero network access. Removed gitignore rules that excluded fetched source trees under recipes/*/source/, local/recipes/kde/*/source/, local/recipes/qt/*/source/, and vendor source trees. Build artifacts (target/, build/, source.tar, *.o, *.so) remain excluded. 127291 files added — kernel, relibc, base, bootloader, pkgar, all KDE/Qt frameworks, mesa, wayland, DRM drivers, and every other recipe source.
1628 lines
69 KiB
Plaintext
1628 lines
69 KiB
Plaintext
\input texinfo
|
|
@setfilename mpc.info
|
|
@include version.texi
|
|
@settitle GNU MPC @value{VERSION}
|
|
|
|
@set MINGMP 5.0.0
|
|
@set MINMPFR 4.1.0
|
|
|
|
@set AUTHORS Andreas Enge, Philippe Th@'eveny, Paul Zimmermann
|
|
|
|
@copying
|
|
This manual is for GNU MPC, a library for multiple precision complex arithmetic,
|
|
version @value{VERSION} of @value{UPDATED-MONTH}.
|
|
|
|
Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2016, 2018, 2020, 2022 INRIA
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections. A copy of the license is included in the section
|
|
entitled ``GNU Free Documentation License.''
|
|
@end quotation
|
|
@end copying
|
|
|
|
@iftex
|
|
@afourpaper
|
|
@end iftex
|
|
@tex
|
|
\global\parindent=0pt
|
|
\global\parskip=8pt
|
|
\global\baselineskip=13pt
|
|
@end tex
|
|
|
|
@dircategory GNU Packages
|
|
@direntry
|
|
* mpc: (mpc)Multiple Precision Complex Library.
|
|
@end direntry
|
|
|
|
|
|
@titlepage
|
|
@title GNU MPC
|
|
@subtitle The GNU Multiple Precision Complex Library
|
|
@subtitle Edition @value{VERSION}
|
|
@subtitle @value{UPDATED-MONTH}
|
|
@author @value{AUTHORS}
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top GNU MPC
|
|
|
|
This manual documents how to install and use the GNU Multiple Precision
|
|
Complex Library, version @value{VERSION}
|
|
@end ifnottex
|
|
|
|
@menu
|
|
* Copying:: GNU MPC Copying Conditions (LGPL).
|
|
* Introduction to GNU MPC:: Brief introduction to GNU MPC.
|
|
* Installing GNU MPC:: How to configure and compile the GNU MPC library.
|
|
* Reporting Bugs:: How to usefully report bugs.
|
|
* GNU MPC Basics:: What every GNU MPC user should know.
|
|
* Complex Functions:: Functions for arithmetic on complex numbers.
|
|
* Ball Arithmetic:: Types and functions for complex balls.
|
|
* References::
|
|
* Concept Index::
|
|
* Function Index::
|
|
* Type Index::
|
|
* GNU Free Documentation License::
|
|
@end menu
|
|
|
|
@c @times{} made available as a "x" in info and html (already works in tex).
|
|
@ifnottex
|
|
@macro times
|
|
x
|
|
@end macro
|
|
@end ifnottex
|
|
|
|
@c @m{T,N} is $T$ in tex or @math{N} otherwise. This is an easy way to give
|
|
@c different forms for math in tex and info. Commas in N or T don't work,
|
|
@c but @C{} can be used instead. \, works in info but not in tex.
|
|
@c (copied from mpfr.texi)
|
|
@iftex
|
|
@macro m {T,N}
|
|
@tex$\T\$@end tex
|
|
@end macro
|
|
@end iftex
|
|
@ifnottex
|
|
@macro m {T,N}
|
|
@math{\N\}
|
|
@end macro
|
|
@end ifnottex
|
|
|
|
@node Copying
|
|
@unnumbered GNU MPC Copying Conditions
|
|
@cindex Copying conditions
|
|
@cindex Conditions for copying GNU MPC
|
|
|
|
GNU MPC is free software; you can redistribute it and/or modify it under
|
|
the terms of the GNU Lesser General Public License as published by the
|
|
Free Software Foundation; either version 3 of the License, or (at your
|
|
option) any later version.
|
|
|
|
GNU MPC is distributed in the hope that it will be useful, but WITHOUT ANY
|
|
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
|
|
more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public License
|
|
along with this program. If not, see @uref{http://www.gnu.org/licenses/}.
|
|
|
|
|
|
@node Introduction to GNU MPC
|
|
@chapter Introduction to GNU MPC
|
|
|
|
|
|
GNU MPC is a portable library written in C for arbitrary precision arithmetic
|
|
on complex numbers providing correct rounding. It implements a multiprecision
|
|
equivalent of the C99 standard.
|
|
It builds upon the GNU MP and the GNU MPFR libraries.
|
|
|
|
@section How to use this Manual
|
|
|
|
Everyone should read @ref{GNU MPC Basics}. If you need to install the library
|
|
yourself, you need to read @ref{Installing GNU MPC}, too.
|
|
|
|
The remainder of the manual can be used for later reference, although it is
|
|
probably a good idea to skim through it.
|
|
|
|
@node Installing GNU MPC
|
|
@chapter Installing GNU MPC
|
|
@cindex Installation
|
|
|
|
To build GNU MPC, you first have to install GNU MP (version @value{MINGMP} or higher) and
|
|
GNU MPFR (version @value{MINMPFR} or higher) on your computer. You need a C compiler;
|
|
GCC version 4.4 or higher is recommended, since GNU MPC may trigger a bug in previous
|
|
versions, see the thread at
|
|
@uref{https://sympa.inria.fr/sympa/arc/mpc-discuss/2011-02/msg00024.html}.
|
|
And you need a
|
|
standard Unix @samp{make} program, plus some other standard Unix utility
|
|
programs.
|
|
|
|
Here are the steps needed to install the library on Unix systems:
|
|
|
|
@enumerate
|
|
@item
|
|
@samp{tar xzf mpc-@value{VERSION}.tar.gz}
|
|
|
|
@item
|
|
@samp{cd mpc-@value{VERSION}}
|
|
|
|
@item
|
|
@samp{./configure}
|
|
|
|
if GMP and GNU MPFR are installed into standard directories, that is, directories
|
|
that are searched by default by the compiler and the linking tools.
|
|
|
|
@samp{./configure --with-gmp=<gmp_install_dir>}
|
|
|
|
is used to indicate a different location where GMP is
|
|
installed. Alternatively, you can specify directly GMP include and GMP lib
|
|
directories with @samp{./configure --with-gmp-lib=<gmp_lib_dir>
|
|
--with-gmp-include=<gmp_include_dir>}.
|
|
|
|
@samp{./configure --with-mpfr=<mpfr_install_dir>}
|
|
|
|
is used to indicate a different location where GNU MPFR is
|
|
installed. Alternatively, you can specify directly GNU MPFR include and GNU MPFR lib
|
|
directories with @samp{./configure --with-mpf-lib=<mpfr_lib_dir>
|
|
--with-mpfr-include=<mpfr_include_dir>}.
|
|
|
|
Another useful parameter is @samp{--prefix}, which can be used to
|
|
specify an alternative installation location instead of
|
|
@file{/usr/local}; see @samp{make install} below.
|
|
|
|
To enable checking for memory leaks using @command{valgrind} during
|
|
@code{make check}, add the parameter @code{--enable-valgrind-tests}.
|
|
|
|
If for debugging purposes you wish to log calls to GNU MPC functions from
|
|
within your code, add the parameter @samp{--enable-logging}.
|
|
In your code, replace the inclusion of @file{mpc.h} by @file{mpc-log.h}
|
|
and link the executable dynamically.
|
|
Then all calls to functions with only complex arguments are printed to
|
|
@file{stderr} in the following form: First, the function name is given,
|
|
followed by its type such as @samp{c_cc}, meaning that the function has
|
|
one complex result (one @samp{c} in front of the @samp{_}), computed from
|
|
two complex arguments (two @samp{c} after the @samp{_}). Then, the
|
|
precisions of the real and the imaginary part of the first result is given,
|
|
followed by the second one and so on. Finally, for each argument, the
|
|
precisions of its real and imaginary part are specified and the argument
|
|
itself is printed in hexadecimal via the function
|
|
@code{mpc_out_str}
|
|
(@pxref{String and Stream Input and Output}).
|
|
The option requires a dynamic library, so it may not be combined with
|
|
@code{--disable-shared}.
|
|
|
|
Use @samp{./configure --help} for an exhaustive list of parameters.
|
|
|
|
@item
|
|
@samp{make}
|
|
|
|
This compiles GNU MPC in the working directory.
|
|
|
|
@item
|
|
@samp{make check}
|
|
|
|
This will make sure GNU MPC was built correctly.
|
|
|
|
If you get error messages, please report them to
|
|
@samp{mpc-discuss@@inria.fr} (@xref{Reporting Bugs}, for
|
|
information on what to include in useful bug reports).
|
|
|
|
@item
|
|
@samp{make install}
|
|
|
|
This will copy the file @file{mpc.h} to the directory
|
|
@file{/usr/local/include}, the file @file{libmpc.a} to the directory
|
|
@file{/usr/local/lib}, and the file @file{mpc.info} to the directory
|
|
@file{/usr/local/share/info} (or if you passed the @samp{--prefix} option to
|
|
@file{configure}, using the prefix directory given as argument to
|
|
@samp{--prefix} instead of @file{/usr/local}). Note: you need write permissions
|
|
on these directories.
|
|
|
|
@end enumerate
|
|
|
|
|
|
@section Other `make' Targets
|
|
|
|
There are some other useful make targets:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@samp{info}
|
|
|
|
Create an info version of the manual, in @file{mpc.info}.
|
|
|
|
@item
|
|
@samp{pdf}
|
|
|
|
Create a PDF version of the manual, in @file{doc/mpc.pdf}.
|
|
|
|
@item
|
|
@samp{dvi}
|
|
|
|
Create a DVI version of the manual, in @file{doc/mpc.dvi}.
|
|
|
|
@item
|
|
@samp{ps}
|
|
|
|
Create a Postscript version of the manual, in @file{doc/mpc.ps}.
|
|
|
|
@item
|
|
@samp{html}
|
|
|
|
Create an HTML version of the manual, in several pages in the
|
|
directory @file{doc/mpc.html}; if you want only one output HTML file,
|
|
then type @samp{makeinfo --html --no-split mpc.texi} instead.
|
|
|
|
@item
|
|
@samp{clean}
|
|
|
|
Delete all object files and archive files, but not the configuration files.
|
|
|
|
@item
|
|
@samp{distclean}
|
|
|
|
Delete all files not included in the distribution.
|
|
|
|
@item
|
|
@samp{uninstall}
|
|
|
|
Delete all files copied by @samp{make install}.
|
|
@end itemize
|
|
|
|
|
|
|
|
@section Known Build Problems
|
|
|
|
On AIX, if GMP was built with the 64-bit ABI, before building and testing GNU MPC,
|
|
it might be necessary to set the @samp{OBJECT_MODE} environment variable to 64
|
|
by, e.g.,
|
|
|
|
@samp{export OBJECT_MODE=64}
|
|
|
|
This has been tested with the C compiler IBM XL C/C++ Enterprise Edition
|
|
V8.0 for AIX, version: 08.00.0000.0021, GMP 4.2.4 and GNU MPFR 2.4.1.
|
|
|
|
Please report any other problems you encounter to
|
|
@samp{mpc-discuss@@inria.fr}.
|
|
@xref{Reporting Bugs}.
|
|
|
|
@node Reporting Bugs
|
|
@chapter Reporting Bugs
|
|
@cindex Reporting bugs
|
|
|
|
If you think you have found a bug in the GNU MPC library,
|
|
please investigate
|
|
and report it. We have made this library available to you, and it is not to ask
|
|
too much from you, to ask you to report the bugs that you find.
|
|
|
|
There are a few things you should think about when you put your bug report
|
|
together.
|
|
|
|
You have to send us a test case that makes it possible for us to reproduce the
|
|
bug. Include instructions on how to run the test case.
|
|
|
|
You also have to explain what is wrong; if you get a crash, or if the results
|
|
printed are incorrect and in that case, in what way.
|
|
|
|
Please include compiler version information in your bug report.
|
|
This can be extracted using @samp{gcc -v},
|
|
or @samp{cc -V} on some machines.
|
|
Also, include the output from @samp{uname -a}.
|
|
|
|
If your bug report is good, we will do our best to help you to get a corrected
|
|
version of the library; if the bug report is poor, we will not do anything about
|
|
it (aside of chiding you to send better bug reports).
|
|
|
|
Send your bug report to: @samp{mpc-discuss@@inria.fr}.
|
|
|
|
If you think something in this manual is unclear, or downright incorrect, or if
|
|
the language needs to be improved, please send a note to the same address.
|
|
|
|
@node GNU MPC Basics
|
|
@chapter GNU MPC Basics
|
|
|
|
|
|
@cindex @file{mpc.h}
|
|
All declarations needed to use GNU MPC are collected in the include file
|
|
@file{mpc.h}. It is designed to work with both C and C++ compilers.
|
|
You should include that file in any program using the GNU MPC library
|
|
by adding the line
|
|
@example
|
|
#include "mpc.h"
|
|
@end example
|
|
|
|
@section Nomenclature and Types
|
|
|
|
@cindex Complex number
|
|
@tindex mpc_t
|
|
@tindex mpc_ptr
|
|
@tindex mpc_srcptr
|
|
@noindent
|
|
@dfn{Complex number} or @dfn{Complex} for short, is a pair of two
|
|
arbitrary precision floating-point numbers (for the real and imaginary parts).
|
|
The C data type for such objects is @code{mpc_t}.
|
|
|
|
@cindex Precision
|
|
@tindex mpfr_prec_t
|
|
@noindent
|
|
The @dfn{Precision} is the number of bits used to represent the mantissa
|
|
of the real and imaginary parts;
|
|
the corresponding C data type is @code{mpfr_prec_t}.
|
|
For more details on the allowed precision range,
|
|
@ifinfo
|
|
@pxref{Nomenclature and Types,,, mpfr.info,GNU MPFR}.
|
|
@end ifinfo
|
|
@ifnotinfo
|
|
see Section ``Nomenclature and Types'' in @cite{GNU MPFR}.
|
|
@end ifnotinfo
|
|
|
|
@cindex Rounding Mode
|
|
@tindex mpc_rnd_t
|
|
@noindent
|
|
The @dfn{rounding mode} specifies the way to round the result of a
|
|
complex operation, in case the exact result can not be represented
|
|
exactly in the destination mantissa;
|
|
the corresponding C data type is @code{mpc_rnd_t}.
|
|
A complex rounding mode is a pair of two rounding modes: one for the real
|
|
part, one for the imaginary part.
|
|
|
|
@section Function Classes
|
|
|
|
There is only one class of functions in the GNU MPC library, namely functions for
|
|
complex arithmetic. The function names begin with @code{mpc_}. The
|
|
associated type is @code{mpc_t}.
|
|
|
|
|
|
@section GNU MPC Variable Conventions
|
|
|
|
As a general rule, all GNU MPC functions expect output arguments before input
|
|
arguments. This notation is based on an analogy with the assignment operator.
|
|
|
|
GNU MPC allows you to use the same variable for both input and output in the same
|
|
expression. For example, the main function for floating-point multiplication,
|
|
@code{mpc_mul}, can be used like this: @code{mpc_mul (x, x, x, rnd_mode)}.
|
|
This
|
|
computes the square of @var{x} with rounding mode @code{rnd_mode}
|
|
and puts the result back in @var{x}.
|
|
|
|
Before you can assign to an GNU MPC variable, you need to initialise it by calling
|
|
one of the special initialization functions. When you are done with a
|
|
variable, you need to clear it out, using one of the functions for that
|
|
purpose.
|
|
|
|
A variable should only be initialised once, or at least cleared out between
|
|
each initialization. After a variable has been initialised, it may be
|
|
assigned to any number of times.
|
|
|
|
For efficiency reasons, avoid to initialise and clear out a variable in loops.
|
|
Instead, initialise it before entering the loop, and clear it out after the
|
|
loop has exited.
|
|
|
|
You do not need to be concerned about allocating additional space for GNU MPC
|
|
variables, since each of its real and imaginary part
|
|
has a mantissa of fixed size.
|
|
Hence unless you change its precision, or clear and reinitialise it,
|
|
a complex variable will have the same allocated space during all its
|
|
life.
|
|
|
|
|
|
@section Rounding Modes
|
|
|
|
A complex rounding mode is of the form @code{MPC_RNDxy} where
|
|
@code{x} and @code{y} are one of @code{N} (to nearest), @code{Z} (towards
|
|
zero), @code{U} (towards plus infinity), @code{D} (towards minus infinity),
|
|
@code{A} (away from zero, that is, towards plus or minus infinity depending
|
|
on the sign of the number to be rounded).
|
|
The first letter refers to the rounding mode for the real part,
|
|
and the second one for the imaginary part.
|
|
For example @code{MPC_RNDZU} indicates to round the real part towards zero,
|
|
and the imaginary part towards plus infinity.
|
|
|
|
The @samp{round to nearest} mode works as in the IEEE P754 standard: in case
|
|
the number to be rounded lies exactly in the middle of two representable
|
|
numbers, it is rounded to the one with the least significant bit set to zero.
|
|
For example, the number 5, which is represented by (101) in binary, is rounded
|
|
to (100)=4 with a precision of two bits, and not to (110)=6.
|
|
|
|
|
|
@anchor{return-value}
|
|
@section Return Value
|
|
|
|
Most GNU MPC functions have a return value of type @code{int}, which is used
|
|
to indicate the position of the rounded real and imaginary parts with respect
|
|
to the exact (infinite precision) values.
|
|
If this integer is @code{i}, the macros @code{MPC_INEX_RE(i)} and
|
|
@code{MPC_INEX_IM(i)} give 0 if the corresponding rounded value is exact,
|
|
a negative value if the rounded value is less than the exact one,
|
|
and a positive value if it is greater than the exact one.
|
|
Similarly, functions computing a result of type @code{mpfr_t}
|
|
return an integer that is 0, positive or negative depending on
|
|
whether the rounded value is the same, larger or smaller then
|
|
the exact result.
|
|
|
|
Some functions, such as @code{mpc_sin_cos}, compute two complex results;
|
|
the macros @code{MPC_INEX1(i)} and @code{MPC_INEX2(i)}, applied to
|
|
the return value @code{i} of such a function, yield the exactness value
|
|
corresponding to the first or the second computed value, respectively.
|
|
|
|
|
|
@section Branch Cuts And Special Values
|
|
|
|
Some complex functions have branch cuts, across which the function is
|
|
discontinous. In GNU MPC, the branch cuts chosen are the same as those
|
|
specified for the corresponding functions in the ISO C99 standard.
|
|
|
|
Likewise, when evaluated at a point whose real or imaginary part is
|
|
either infinite or a NaN or a signed zero, a function returns the same
|
|
value as those specified for the corresponding function in the ISO C99
|
|
standard.
|
|
|
|
|
|
@node Complex Functions
|
|
@chapter Complex Functions
|
|
@cindex Complex functions
|
|
|
|
The complex functions expect arguments of type @code{mpc_t}.
|
|
|
|
The GNU MPC floating-point functions have an interface that is similar to the
|
|
GNU MP
|
|
integer functions. The function prefix for operations on complex numbers is
|
|
@code{mpc_}.
|
|
|
|
@cindex User-defined precision
|
|
The precision of a computation is defined as follows: Compute the requested
|
|
operation exactly (with ``infinite precision''), and round the result to
|
|
the destination variable precision with the given rounding mode.
|
|
|
|
The GNU MPC complex functions are intended to be a smooth extension
|
|
of the IEEE P754 arithmetic. The results obtained on one
|
|
computer should not differ from the results obtained on a computer with a
|
|
different word size.
|
|
|
|
|
|
@menu
|
|
* Initializing Complex Numbers::
|
|
* Assigning Complex Numbers::
|
|
* Converting Complex Numbers::
|
|
* String and Stream Input and Output::
|
|
* Complex Comparison::
|
|
* Projection & Decomposing::
|
|
* Basic Arithmetic::
|
|
* Power Functions and Logarithm::
|
|
* Trigonometric Functions::
|
|
* Modular Functions::
|
|
* Miscellaneous Complex Functions::
|
|
* Advanced Functions::
|
|
* Internals::
|
|
@end menu
|
|
|
|
@node Initializing Complex Numbers
|
|
@section Initialization Functions
|
|
|
|
An @code{mpc_t} object must be initialised before storing the first value in
|
|
it. The functions @code{mpc_init2} and @code{mpc_init3}
|
|
are used for that purpose.
|
|
|
|
@deftypefun void mpc_init2 (mpc_t @var{z}, mpfr_prec_t @var{prec})
|
|
Initialise @var{z} to precision @var{prec} bits
|
|
and set its real and imaginary parts to NaN.
|
|
Normally, a variable should be initialised once only
|
|
or at least be cleared, using @code{mpc_clear}, between initializations.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpc_init3 (mpc_t @var{z}, mpfr_prec_t @var{prec_r}, mpfr_prec_t @var{prec_i})
|
|
Initialise @var{z} with the precision of its real part being
|
|
@var{prec_r} bits and the precision of its imaginary part being
|
|
@var{prec_i} bits, and set the real and imaginary parts to NaN.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpc_clear (mpc_t @var{z})
|
|
Free the space occupied by @var{z}. Make sure to call this function for all
|
|
@code{mpc_t} variables when you are done with them.
|
|
@end deftypefun
|
|
|
|
@need 2000
|
|
Here is an example on how to initialise complex variables:
|
|
@example
|
|
@{
|
|
mpc_t x, y;
|
|
mpc_init2 (x, 256); /* precision @emph{exactly} 256 bits */
|
|
mpc_init3 (y, 100, 50); /* 100/50 bits for the real/imaginary part */
|
|
@dots{}
|
|
mpc_clear (x);
|
|
mpc_clear (y);
|
|
@}
|
|
@end example
|
|
|
|
The following function is useful for changing the precision during a
|
|
calculation. A typical use would be for adjusting the precision gradually in
|
|
iterative algorithms like Newton-Raphson, making the computation precision
|
|
closely match the actual accurate part of the numbers.
|
|
|
|
@deftypefun void mpc_set_prec (mpc_t @var{x}, mpfr_prec_t @var{prec})
|
|
Reset the precision of @var{x} to be @strong{exactly} @var{prec} bits,
|
|
and set its real/imaginary parts to NaN.
|
|
The previous value stored in @var{x} is lost. It is equivalent to
|
|
a call to @code{mpc_clear(x)} followed by a call to
|
|
@code{mpc_init2(x, prec)}, but more efficient as no allocation is done in
|
|
case the current allocated space for the mantissa of @var{x} is sufficient.
|
|
@end deftypefun
|
|
|
|
@deftypefun mpfr_prec_t mpc_get_prec (const mpc_t @var{x})
|
|
If the real and imaginary part of @var{x} have the same precision, it is returned,
|
|
otherwise, 0 is returned.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpc_get_prec2 (mpfr_prec_t* @var{pr}, mpfr_prec_t* @var{pi}, const mpc_t @var{x})
|
|
Returns the precision of the real part of @var{x} via @var{pr} and of its imaginary part
|
|
via @var{pi}.
|
|
@end deftypefun
|
|
|
|
|
|
@node Assigning Complex Numbers
|
|
@section Assignment Functions
|
|
@cindex Complex assignment functions
|
|
|
|
These functions assign new values to already initialised complex numbers
|
|
(@pxref{Initializing Complex Numbers}).
|
|
When using any functions with @code{intmax_t} or @code{uintmax_t}
|
|
parameters, you must include
|
|
@code{<stdint.h>} or @code{<inttypes.h>} @emph{before} @file{mpc.h}, to allow
|
|
@file{mpc.h} to define prototypes for these functions.
|
|
Similarly, functions with parameters of type @code{complex} or
|
|
@code{long complex} are defined only if @code{<complex.h>} is included
|
|
@emph{before} @file{mpc.h}.
|
|
If you need assignment functions that are not in the current API, you can
|
|
define them using the @code{MPC_SET_X_Y} macro (@pxref{Advanced Functions}).
|
|
|
|
@deftypefun int mpc_set (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set the value of @var{rop} from @var{op}, rounded to the precision of @var{rop}
|
|
with the given rounding mode @var{rnd}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_set_ui (mpc_t @var{rop}, unsigned long int @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_si (mpc_t @var{rop}, long int @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_uj (mpc_t @var{rop}, uintmax_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_sj (mpc_t @var{rop}, intmax_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_d (mpc_t @var{rop}, double @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_ld (mpc_t @var{rop}, long double @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_dc (mpc_t @var{rop}, double _Complex @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_ldc (mpc_t @var{rop}, long double _Complex @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_z (mpc_t @var{rop}, const mpz_t @var{op} mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_q (mpc_t @var{rop}, const mpq_t @var{op} mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_f (mpc_t @var{rop}, const mpf_t @var{op} mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_fr (mpc_t @var{rop}, const mpfr_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set the value of @var{rop} from @var{op}, rounded to the precision of
|
|
@var{rop} with the given rounding mode @var{rnd}.
|
|
The argument @var{op} is interpreted as real, so the imaginary part of
|
|
@var{rop} is set to zero with a positive sign.
|
|
Please note that even a @code{long int} may have to be rounded, if the
|
|
destination precision is less than the machine word width.
|
|
For @code{mpc_set_d}, be careful that the input number @var{op} may not be
|
|
exactly representable as a double-precision number (this happens for 0.1 for
|
|
instance), in which case it is first rounded by the C compiler to a
|
|
double-precision number, and then only to a complex number.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_set_ui_ui (mpc_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_si_si (mpc_t @var{rop}, long int @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_uj_uj (mpc_t @var{rop}, uintmax_t @var{op1}, uintmax_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_sj_sj (mpc_t @var{rop}, intmax_t @var{op1}, intmax_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_d_d (mpc_t @var{rop}, double @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_ld_ld (mpc_t @var{rop}, long double @var{op1}, long double @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_z_z (mpc_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_q_q (mpc_t @var{rop}, const mpq_t @var{op1}, const mpq_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_f_f (mpc_t @var{rop}, const mpf_t @var{op1}, const mpf_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_set_fr_fr (mpc_t @var{rop}, const mpfr_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
Set the real part of @var{rop} from @var{op1}, and its imaginary part from
|
|
@var{op2}, according to the rounding mode @var{rnd}.
|
|
|
|
Beware that the behaviour of @code{mpc_set_fr_fr} is undefined if @var{op1}
|
|
or @var{op2} is a pointer to the real or imaginary part of @var{rop}.
|
|
To exchange the real and the imaginary part of a complex number, either use
|
|
@code{mpfr_swap (mpc_realref (rop), mpc_imagref (rop))}, which also exchanges
|
|
the precisions of the two parts; or use a temporary variable.
|
|
@end deftypefun
|
|
|
|
For functions assigning complex variables from strings or input streams,
|
|
@pxref{String and Stream Input and Output}.
|
|
|
|
@deftypefun void mpc_set_nan (mpc_t @var{rop})
|
|
Set @var{rop} to Nan+i*NaN.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpc_swap (mpc_t @var{op1}, mpc_t @var{op2})
|
|
Swap the values of @var{op1} and @var{op2} efficiently. Warning: The
|
|
precisions are exchanged, too; in case these are different,
|
|
@code{mpc_swap} is thus not equivalent to three @code{mpc_set} calls using a
|
|
third auxiliary variable.
|
|
@end deftypefun
|
|
|
|
|
|
@node Converting Complex Numbers
|
|
@section Conversion Functions
|
|
@cindex Conversion functions
|
|
|
|
The following functions are available only if @code{<complex.h>}
|
|
is included @emph{before} @file{mpc.h}.
|
|
|
|
@deftypefun double _Complex mpc_get_dc (const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx {long double _Complex} mpc_get_ldc (mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Convert @var{op} to a C complex number, using the rounding mode @var{rnd}.
|
|
@end deftypefun
|
|
|
|
|
|
For functions converting complex variables to strings or stream output,
|
|
@pxref{String and Stream Input and Output}.
|
|
|
|
|
|
@node String and Stream Input and Output
|
|
@section String and Stream Input and Output
|
|
@cindex String and stream input and output
|
|
|
|
@deftypefun int mpc_strtoc (mpc_t @var{rop}, const char *@var{nptr}, char **@var{endptr}, int @var{base}, mpc_rnd_t @var{rnd})
|
|
Read a complex number from a string @var{nptr} in base @var{base}, rounded to
|
|
the precision of @var{rop} with the given rounding mode @var{rnd}.
|
|
The @var{base} must be either 0 or a number from 2 to 36 (otherwise the
|
|
behaviour is undefined).
|
|
If @var{nptr} starts with valid data, the result is stored in @var{rop},
|
|
the usual inexact value is returned (@pxref{return-value,, Return
|
|
Value}) and, if @var{endptr} is not the null pointer,
|
|
@var{*endptr} points to the character just after the valid data.
|
|
Otherwise, @var{rop} is set to @code{NaN + i * NaN}, -1 is returned and,
|
|
if @var{endptr} is not the null pointer,
|
|
the value of @var{nptr} is stored in the location referenced by
|
|
@var{endptr}.
|
|
|
|
The expected form of a complex number string is either a real number (an
|
|
optional leading whitespace, an optional sign followed by a floating-point
|
|
number), or a pair of real numbers in parentheses separated by whitespace. If
|
|
a real number is read, the missing imaginary part is set to +0.
|
|
The form of a floating-point number depends on the base and is described
|
|
in the documentation of @code{mpfr_strtofr}
|
|
@ifinfo
|
|
(@pxref{Assignment Functions,,, mpfr.info,GNU MPFR}).
|
|
@end ifinfo
|
|
@ifnotinfo
|
|
in the GNU MPFR manual.
|
|
@end ifnotinfo
|
|
For instance, @code{"3.1415926"}, @code{"(1.25e+7 +.17)"}, @code{"(@@nan@@
|
|
2)"} and @code{"(-0 -7)"} are valid strings for @var{base} = 10.
|
|
If @var{base} = 0, then a prefix may be used to indicate the base in which the
|
|
floating-point number is written. Use prefix '0b' for binary numbers, prefix
|
|
'0x' for hexadecimal numbers, and no prefix for decimal numbers.
|
|
The real and imaginary part may then be written in different bases.
|
|
For instance, @code{"(1.024e+3 +2.05e+3)"} and @code{"(0b1p+10 +0x802)"} are
|
|
valid strings for @code{base}=0 and represent the same value.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_set_str (mpc_t @var{rop}, const char *@var{s}, int @var{base}, mpc_rnd_t rnd)
|
|
Set @var{rop} to the value of the string @var{s} in base @var{base}, rounded
|
|
to the precision of @var{rop} with the given rounding mode @var{rnd}.
|
|
See the documentation of @code{mpc_strtoc} for a detailed description of the
|
|
valid string formats.
|
|
Contrarily to @code{mpc_strtoc}, @code{mpc_set_str} requires the @emph{whole}
|
|
string to represent a valid complex number (potentially followed by
|
|
additional white space).
|
|
This function returns the usual inexact value (@pxref{return-value,, Return
|
|
Value}) if the entire string up to the final null character is a valid number
|
|
in base @var{base}; otherwise it returns @minus{}1, and @var{rop} is set to
|
|
NaN+i*NaN.
|
|
@end deftypefun
|
|
|
|
@deftypefun {char *} mpc_get_str (int @var{b}, size_t @var{n}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Convert @var{op} to a string containing its real and imaginary parts,
|
|
separated by a space and enclosed in a pair of parentheses.
|
|
The numbers are written in base @var{b} (which may vary from 2 to 36) and
|
|
rounded according to @var{rnd}. The number of significant digits, at least 2,
|
|
is given by @var{n}. It is also possible to let
|
|
@var{n} be zero, in which case the number of digits is chosen large
|
|
enough so that re-reading the printed value with the same precision, assuming
|
|
both output and input use rounding to nearest, will recover the original value
|
|
of @var{op}.
|
|
Note that @code{mpc_get_str} uses the decimal point of the current locale
|
|
if available, and @samp{.} otherwise.
|
|
|
|
The string is generated using the current memory allocation function
|
|
(@code{malloc} by default, unless it has been modified using the custom
|
|
memory allocation interface of @code{gmp}); once it is not needed any more,
|
|
it should be freed by calling @code{mpc_free_str}.
|
|
@end deftypefun
|
|
|
|
@deftypefun {void} mpc_free_str (char *@var{str})
|
|
Free the string @var{str}, which needs to have been allocated by
|
|
a call to @code{mpc_get_str}.
|
|
@end deftypefun
|
|
|
|
The following two functions read numbers from input streams and write
|
|
them to output streams.
|
|
When using any of these functions, you need to include @file{stdio.h}
|
|
@emph{before} @file{mpc.h}.
|
|
|
|
@deftypefun int mpc_inp_str (mpc_t @var{rop}, FILE *@var{stream}, size_t *@var{read}, int @var{base}, mpc_rnd_t @var{rnd})
|
|
Input a string in base @var{base} in the same format as for @code{mpc_strtoc}
|
|
from stdio stream @var{stream}, rounded according to @var{rnd}, and put the
|
|
read complex number into @var{rop}.
|
|
If @var{stream} is the null pointer, @var{rop} is read from @code{stdin}.
|
|
Return the usual inexact value; if an error occurs, set @var{rop} to @code{NaN
|
|
+ i * NaN} and return -1.
|
|
If @var{read} is not the null pointer, it is set to the number of read
|
|
characters.
|
|
|
|
Unlike @code{mpc_strtoc}, the function @code{mpc_inp_str} does not possess
|
|
perfect knowledge of the string to transform and has to read it
|
|
character by character, so it behaves slightly differently: It tries
|
|
to read a string describing a complex number and processes this string
|
|
through a call to @code{mpc_set_str}. Precisely, after skipping optional
|
|
whitespace, a minimal string is read according to the regular expression
|
|
@code{mpfr | '(' \s* mpfr \s+ mpfr \s* ')'}, where @code{\s} denotes a whitespace,
|
|
and @code{mpfr} is either a string containing neither whitespaces nor
|
|
parentheses, or @code{nan(n-char-sequence)} or @code{@@nan@@(n-char-sequence)}
|
|
(regardless of capitalisation) with @code{n-char-sequence} a string
|
|
of ascii letters, digits or @code{'_'}.
|
|
|
|
For instance, upon input of @code{"nan(13 1)"}, the function
|
|
@code{mpc_inp_str} starts to recognise a value of NaN followed by an
|
|
n-char-sequence indicated by the opening parenthesis; as soon as the
|
|
space is reached, it becomes clear that the expression in parentheses
|
|
is not an n-char-sequence, and the error flag -1 is returned after 6
|
|
characters have been consumed from the stream (the whitespace itself
|
|
remaining in the stream).
|
|
The function @code{mpc_strtoc}, on the other hand, may track back
|
|
when reaching the whitespace; it treats the string as the two successive
|
|
complex numbers @code{NaN + i * 0} and @code{13 + i}.
|
|
It is thus recommended to have a whitespace follow each floating point number
|
|
to avoid this problem.
|
|
@end deftypefun
|
|
|
|
@deftypefun size_t mpc_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n_digits}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Output @var{op} on stdio stream @var{stream} in
|
|
base @var{base}, rounded according to @var{rnd}, in the same format
|
|
as for @code{mpc_strtoc}
|
|
If @var{stream} is the null pointer, @var{rop} is written to @code{stdout}.
|
|
|
|
Return the number of characters written.
|
|
@end deftypefun
|
|
|
|
|
|
@node Complex Comparison
|
|
@section Comparison Functions
|
|
@cindex Complex comparisons functions
|
|
@cindex Comparison functions
|
|
|
|
@deftypefn Function int mpc_cmp (const mpc_t @var{op1}, const mpc_t @var{op2})
|
|
@deftypefnx Function int mpc_cmp_si_si (const mpc_t @var{op1}, long int @var{op2r}, long int @var{op2i})
|
|
@deftypefnx Macro int mpc_cmp_si (mpc_t @var{op1}, long int @var{op2})
|
|
|
|
Compare @var{op1} and @var{op2}, where in the case of @code{mpc_cmp_si_si},
|
|
@var{op2} is taken to be @var{op2r} + i @var{op2i}.
|
|
The return value @var{c} can be decomposed into @code{x = MPC_INEX_RE(c)}
|
|
and @code{y = MPC_INEX_IM(c)}, such that @var{x} is
|
|
positive if the real part of @var{op1} is greater than that of @var{op2},
|
|
zero if both real parts are equal, and negative if the real part of @var{op1}
|
|
is less than that of @var{op2}, and likewise for @var{y}.
|
|
Both @var{op1} and @var{op2} are considered to their full own precision,
|
|
which may differ.
|
|
It is not allowed that one of the operands has a NaN (Not-a-Number) part.
|
|
|
|
The storage of the return value is such that equality can be simply checked
|
|
with @code{mpc_cmp (op1, op2) == 0}.
|
|
@end deftypefn
|
|
|
|
@deftypefn Function int mpc_cmp_abs (const mpc_t @var{op1}, const mpc_t @var{op2})
|
|
|
|
Compare the absolute values of @var{op1} and @var{op2}.
|
|
The return value is 0 if both are the same (including infinity),
|
|
positive if the absolute value of @var{op1} is greater than that of @var{op2},
|
|
and negative if it is smaller.
|
|
If @var{op1} or @var{op2} has a real or imaginary part which is NaN,
|
|
the function behaves like @code{mpfr_cmp} on two real numbers of which at least
|
|
one is NaN.
|
|
@end deftypefn
|
|
|
|
|
|
@node Projection & Decomposing
|
|
@section Projection and Decomposing Functions
|
|
@cindex Projection and Decomposing Functions
|
|
|
|
@deftypefn Function int mpc_real (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd})
|
|
Set @var{rop} to the value of the real part of @var{op} rounded
|
|
in the direction @var{rnd}.
|
|
@end deftypefn
|
|
|
|
@deftypefn Function int mpc_imag (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd})
|
|
Set @var{rop} to the value of the imaginary part of @var{op} rounded in the
|
|
direction @var{rnd}.
|
|
@end deftypefn
|
|
|
|
@deftypefn Macro mpfr_t mpc_realref (mpc_t @var{op})
|
|
@deftypefnx Macro mpfr_t mpc_imagref (mpc_t @var{op})
|
|
Return a reference to the real part and imaginary part of @var{op},
|
|
respectively. The @code{mpfr} functions can be used on the result of these
|
|
macros (note that the @code{mpfr_t} type is itself a pointer).
|
|
@end deftypefn
|
|
|
|
@deftypefn Function int mpc_arg (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd})
|
|
Set @var{rop} to the argument of @var{op}, with a branch cut along the
|
|
negative real axis.
|
|
@end deftypefn
|
|
|
|
@deftypefn Function int mpc_proj (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Compute a projection of @var{op} onto the Riemann sphere. Set @var{rop} to
|
|
@var{op} rounded in the direction @var{rnd}, except when at least one part of
|
|
@var{op} is infinite (even if the other part is a NaN) in which case the real
|
|
part of @var{rop} is set to plus infinity and its imaginary part to a signed
|
|
zero with the same sign as the imaginary part of @var{op}.
|
|
@end deftypefn
|
|
|
|
|
|
@node Basic Arithmetic
|
|
@section Basic Arithmetic Functions
|
|
@cindex Complex arithmetic functions
|
|
@cindex Arithmetic functions
|
|
|
|
All the following functions are designed in such a way that, when working
|
|
with real numbers instead of complex numbers, their complexity should
|
|
essentially be the same as with the GNU MPFR library, with only a marginal
|
|
overhead due to the GNU MPC layer.
|
|
|
|
For functions taking as input an integer argument
|
|
(for example @code{mpc_add_ui}), when this argument is zero,
|
|
it is considered as an unsigned (that is, exact in this context)
|
|
zero, and we follow the MPFR conventions:
|
|
(0) + (+0) = +0, (0) - (+0) = -0, (0) - (+0) = -0, (0) - (-0) = +0.
|
|
The same applies for functions taking an argument of type @code{mpfr_t},
|
|
such as @code{mpc_add_fr}, of which the imaginary part is considered
|
|
to be an exact, unsigned zero.
|
|
|
|
@deftypefun int mpc_add (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_add_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_add_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to @var{op1} @math{+} @var{op2} rounded according to @var{rnd}.
|
|
@end deftypefun
|
|
|
|
@deftypefn Function int mpc_sub (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefnx Function int mpc_sub_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefnx Function int mpc_fr_sub (mpc_t @var{rop}, const mpfr_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefnx Function int mpc_sub_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefnx Macro int mpc_ui_sub (mpc_t @var{rop}, unsigned long int @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefnx Function int mpc_ui_ui_sub (mpc_t @var{rop}, unsigned long int @var{re1}, unsigned long int @var{im1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to @var{op1} @minus{} @var{op2} rounded according to @var{rnd}.
|
|
For @code{mpc_ui_ui_sub}, @var{op1} is @var{re1} + @var{im1}.
|
|
@end deftypefn
|
|
|
|
@deftypefun int mpc_neg (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to @minus{}@var{op} rounded according to @var{rnd}.
|
|
Just changes the sign if @var{rop} and @var{op} are the same variable.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_sum (mpc_t @var{rop}, const mpc_ptr* @var{op}, unsigned long @var{n}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the sum of the elements in the array @var{op} of
|
|
length @var{n}, rounded according to @var{rnd}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_mul (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_mul_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_mul_si (mpc_t @var{rop}, const mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_mul_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to @var{op1} times @var{op2} rounded according to @var{rnd}.
|
|
Note: for @code{mpc_mul}, in case @var{op1} and @var{op2} have the same value,
|
|
use @code{mpc_sqr} for better efficiency.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_mul_i (mpc_t @var{rop}, const mpc_t @var{op}, int @var{sgn}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to @var{op} times the imaginary unit i if @var{sgn} is
|
|
non-negative, set @var{rop} to @var{op} times -i otherwise,
|
|
in both cases rounded according to @var{rnd}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_sqr (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the square of @var{op} rounded according to @var{rnd}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_fma (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, const mpc_t @var{op3}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to @var{op1}*@var{op2}+@var{op3},
|
|
rounded according to @var{rnd}, with only one final rounding.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_dot (mpc_t @var{rop}, const mpc_ptr* @var{op1}, mpc_ptr* @var{op2}, unsigned long @var{n}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the dot product of the elements in the arrays @var{op1} and
|
|
@var{op2}, both of length @var{n}, rounded according to @var{rnd}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_div (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_div_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_div_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_ui_div (mpc_t @var{rop}, unsigned long int @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_fr_div (mpc_t @var{rop}, const mpfr_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to @var{op1}/@var{op2} rounded according to @var{rnd}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_conj (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the conjugate of @var{op} rounded according to @var{rnd}.
|
|
Just changes the sign of the imaginary part
|
|
if @var{rop} and @var{op} are the same variable.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_abs (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd})
|
|
Set the floating-point number @var{rop} to the absolute value of @var{op},
|
|
rounded in the direction @var{rnd}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_norm (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd})
|
|
Set the floating-point number @var{rop} to the norm of @var{op}
|
|
(i.e., the square of its absolute value),
|
|
rounded in the direction @var{rnd}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_mul_2ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_mul_2si (mpc_t @var{rop}, const mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to @var{op1} times 2 raised to @var{op2}
|
|
rounded according to @var{rnd}. Just modifies the exponents
|
|
of the real and imaginary parts by @var{op2}
|
|
when @var{rop} and @var{op1} are identical.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_div_2ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_div_2si (mpc_t @var{rop}, const mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}
|
|
rounded according to @var{rnd}. Just modifies the exponents
|
|
of the real and imaginary parts by @var{op2}
|
|
when @var{rop} and @var{op1} are identical.
|
|
@end deftypefun
|
|
|
|
|
|
@node Power Functions and Logarithm
|
|
@section Power Functions and Logarithm
|
|
@cindex Power functions
|
|
@cindex Logarithm
|
|
|
|
@deftypefun int mpc_sqrt (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the square root of @var{op} rounded according to @var{rnd}.
|
|
The returned value @var{rop} has a non-negative real part, and if its real
|
|
part is zero, a non-negative imaginary part.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_pow (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_pow_d (mpc_t @var{rop}, const mpc_t @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_pow_ld (mpc_t @var{rop}, const mpc_t @var{op1}, long double @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_pow_si (mpc_t @var{rop}, const mpc_t @var{op1}, long @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_pow_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_pow_z (mpc_t @var{rop}, const mpc_t @var{op1}, const mpz_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_pow_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to @var{op1} raised to the power @var{op2}, rounded according
|
|
to @var{rnd}.
|
|
For @code{mpc_pow_d}, @code{mpc_pow_ld}, @code{mpc_pow_si}, @code{mpc_pow_ui},
|
|
@code{mpc_pow_z} and @code{mpc_pow_fr},
|
|
the imaginary part of @var{op2} is considered as +0.
|
|
When both @var{op1} and @var{op2} are zero, the result has real part 1,
|
|
and imaginary part 0, with sign being the opposite of that of @var{op2}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_exp (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the exponential of @var{op},
|
|
rounded according to @var{rnd} with the precision of @var{rop}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_log (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_log10 (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the natural and base-10 logarithm of @var{op} respectively,
|
|
rounded according to @var{rnd} with the precision of @var{rop}.
|
|
The principal branch is chosen, with the branch cut on the negative real axis,
|
|
so that the imaginary part of the result lies in
|
|
@iftex
|
|
@math{]-\pi , \pi]}
|
|
@end iftex
|
|
@ifnottex
|
|
]-Pi , Pi]
|
|
@end ifnottex
|
|
and
|
|
@iftex
|
|
@math{]-\pi/\log(10) , \pi/\log(10)]}
|
|
@end iftex
|
|
@ifnottex
|
|
]-Pi/log(10) , Pi/log(10)]
|
|
@end ifnottex
|
|
respectively.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_rootofunity (mpc_t @var{rop}, unsigned long int @var{n}, unsigned long int @var{k}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the standard primitive @var{n}-th root of unity raised to the power @var{k}, that is,
|
|
@m{\exp (2 \pi i k / n),exp (2 Pi i k / n)},
|
|
rounded according to @var{rnd} with the precision of @var{rop}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_agm (mpc_t @var{rop}, const mpc_t @var{a}, const mpc_t @var{b}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the arithmetic-geometric mean (AGM) of @var{a} and
|
|
@var{b}, rounded according to @var{rnd} with the precision of @var{rop}.
|
|
Concerning the branch cut, the function is computed by homogeneity either
|
|
as @var{a} AGM(1,b0) with b0=@var{b}/@var{a} if |@var{a}|>=|@var{b}|,
|
|
or as @var{b} AGM(1,b0) with b0=@var{a}/@var{b} otherwise;
|
|
then when b0 is real and negative, AGM(1,b0) is chosen to have positive
|
|
imaginary part.
|
|
@end deftypefun
|
|
|
|
|
|
@node Trigonometric Functions
|
|
@section Trigonometric Functions
|
|
@cindex Trigonometric functions
|
|
|
|
@deftypefun int mpc_sin (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_cos (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_tan (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the sine, cosine, tangent of @var{op},
|
|
rounded according to @var{rnd} with the precision of @var{rop}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_sin_cos (mpc_t @var{rop_sin}, mpc_t @var{rop_cos}, const mpc_t @var{op}, mpc_rnd_t @var{rnd_sin}, mpc_rnd_t @var{rnd_cos})
|
|
Set @var{rop_sin} to the sine of @var{op},
|
|
rounded according to @var{rnd_sin} with the precision of @var{rop_sin},
|
|
and @var{rop_cos} to the cosine of @var{op},
|
|
rounded according to @var{rnd_cos} with the precision of @var{rop_cos}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_sinh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_cosh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_tanh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the hyperbolic sine, hyperbolic cosine, hyperbolic tangent of @var{op},
|
|
rounded according to @var{rnd} with the precision of @var{rop}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_asin (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_acos (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_atan (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the inverse sine, inverse cosine, inverse tangent of @var{op},
|
|
rounded according to @var{rnd} with the precision of @var{rop}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpc_asinh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_acosh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
@deftypefunx int mpc_atanh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Set @var{rop} to the inverse hyperbolic sine, inverse hyperbolic cosine,
|
|
inverse hyperbolic tangent of @var{op},
|
|
rounded according to @var{rnd} with the precision of @var{rop}.
|
|
The branch cut of @code{mpc_acosh} is
|
|
@iftex
|
|
@math{(-\infty, 1)}.
|
|
@end iftex
|
|
@ifnottex
|
|
(-Inf, 1)
|
|
@end ifnottex
|
|
@end deftypefun
|
|
|
|
|
|
@node Modular Functions
|
|
@section Modular Functions
|
|
@cindex Modular functions
|
|
|
|
The following function is experimental, not least because it depends on
|
|
the equally experimental ball arithmetic, see @ref {Ball Arithmetic}.
|
|
So its prototype may change in future releases, and it may be removed
|
|
altogether.
|
|
|
|
@deftypefun int mpc_eta_fund (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
|
|
Assuming that the argument @var{op} lies in the fundamental domain for
|
|
@math{Sl_2(Z)}, that is, it has real part not below @math{-1/2} and
|
|
not above @math{+1/2} and absolute value at least 1,
|
|
return the value of the Dedekind eta-function in @var{rop}.
|
|
For arguments outside the fundamental domain the function is expected to
|
|
loop indefinitely.
|
|
@end deftypefun
|
|
|
|
|
|
@node Miscellaneous Complex Functions
|
|
@section Miscellaneous Functions
|
|
@cindex Miscellaneous complex functions
|
|
|
|
@deftypefun int mpc_urandom (mpc_t @var{rop}, gmp_randstate_t @var{state})
|
|
Generate a uniformly distributed random complex in the unit square @math{[0,
|
|
1] @times [0, 1]}. Return 0, unless an exponent in the real or imaginary part
|
|
is not in the current exponent range, in which case that part is set to NaN
|
|
and a zero value is returned. The second argument is a @code{gmp_randstate_t}
|
|
structure which should be created using the GMP @code{rand_init} function, see
|
|
the GMP manual.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} mpc_get_version (void)
|
|
Return the GNU MPC version, as a null-terminated string.
|
|
@end deftypefun
|
|
|
|
@defmac MPC_VERSION
|
|
@defmacx MPC_VERSION_MAJOR
|
|
@defmacx MPC_VERSION_MINOR
|
|
@defmacx MPC_VERSION_PATCHLEVEL
|
|
@defmacx MPC_VERSION_STRING
|
|
@code{MPC_VERSION} is the version of GNU MPC as a preprocessing constant.
|
|
@code{MPC_VERSION_MAJOR}, @code{MPC_VERSION_MINOR} and
|
|
@code{MPC_VERSION_PATCHLEVEL} are respectively the major, minor and
|
|
patch level of GNU MPC version, as preprocessing constants.
|
|
@code{MPC_VERSION_STRING} is the version as a string constant, which
|
|
can be compared to the result of @code{mpc_get_version} to check at
|
|
run time the header file and library used match:
|
|
@example
|
|
if (strcmp (mpc_get_version (), MPC_VERSION_STRING))
|
|
fprintf (stderr, "Warning: header and library do not match\n");
|
|
@end example
|
|
Note: Obtaining different strings is not necessarily an error, as in
|
|
general, a program compiled with some old GNU MPC version can be
|
|
dynamically linked with a newer GNU MPC library version (if allowed by the
|
|
library versioning system).
|
|
@end defmac
|
|
|
|
@deftypefn Macro long MPC_VERSION_NUM (@var{major}, @var{minor}, @var{patchlevel})
|
|
Create an integer in the same format as used by @code{MPC_VERSION} from the
|
|
given @var{major}, @var{minor} and @var{patchlevel}.
|
|
Here is an example of how to check the GNU MPC version at compile time:
|
|
@example
|
|
#if (!defined(MPC_VERSION) || (MPC_VERSION<MPC_VERSION_NUM(2,1,0)))
|
|
# error "Wrong GNU MPC version."
|
|
#endif
|
|
@end example
|
|
@end deftypefn
|
|
|
|
@node Advanced Functions
|
|
@section Advanced Functions
|
|
|
|
@defmac MPC_SET_X_Y (@var{real_suffix}, @var{imag_suffix}, @var{rop}, @var{real}, @var{imag}, @var{rnd})
|
|
The macro MPC_SET_X_Y is designed to serve as the body of an assignment
|
|
function and cannot be used by itself.
|
|
The @var{real_suffix} and @var{imag_suffix} parameters are the
|
|
types of the real and imaginary part, that is, the @code{x} in the
|
|
@code{mpfr_set_x} function one would use to set the part;
|
|
for the mpfr type, use @code{fr}.
|
|
@var{real} (respectively @var{imag}) is the value you want to assign to the
|
|
real (resp. imaginary) part, its type must conform to @var{real_suffix}
|
|
(resp. @var{imag_suffix}).
|
|
@var{rnd} is the @code{mpc_rnd_t} rounding mode.
|
|
The return value is the usual inexact value (@pxref{return-value,, Return
|
|
Value}).
|
|
|
|
For instance, you can define mpc_set_ui_fr as follows:
|
|
@example
|
|
int mpc_set_ui_fr (mpc_t rop, unsigned long int re, mpfr_t im, mpc_rnd_t rnd)
|
|
MPC_SET_X_Y (ui, fr, rop, re, im, rnd);
|
|
@end example
|
|
@end defmac
|
|
|
|
|
|
@node Internals
|
|
@section Internals
|
|
|
|
These macros and
|
|
functions are mainly designed for the implementation of GNU MPC,
|
|
but may be useful for users too.
|
|
However, no upward compatibility is guaranteed.
|
|
You need to include @code{mpc-impl.h} to use them.
|
|
|
|
The macro @code{MPC_MAX_PREC(z)} gives the maximum of the precisions
|
|
of the real and imaginary parts of a complex number.
|
|
|
|
|
|
@node Ball Arithmetic
|
|
@chapter Ball Arithmetic
|
|
@cindex Ball arithmetic
|
|
|
|
Since release 1.3.0, GNU MPC contains a simple and very limited
|
|
implementation of complex balls (or rather, circles). This part is
|
|
experimental, its interface may vary and it may be removed completely
|
|
in future releases.
|
|
|
|
@tindex mpcb_t
|
|
A complex ball of the new type @code{mpcb_t} is defined by a non-zero centre
|
|
@math{c} of the type @code{mpc_t} and a relative radius @math{r} of
|
|
the new type @code{mpcr_t}, and it represents all complex numbers
|
|
@math{z = c (1 + ϑ)} with @math{|ϑ| ≤ r}, or equivalently
|
|
the closed circle with centre @math{c} and radius @math{r |c|}.
|
|
The approach of using a relative error (or radius) instead of an absolute
|
|
one simplifies error analyses for multiplicative operations (multiplication,
|
|
division, square roots, and the AGM), at the expense of making them more
|
|
complicated for additive operations. It has the major drawback of not being
|
|
able to represent balls centred at 0; in floating point arithmetic, however,
|
|
0 is never reached by rounding, but only through operations with exact
|
|
result, which could be handled at a higher, application level. For more
|
|
discussion on these issues, see the file @code{algorithms.tex}.
|
|
|
|
|
|
@section Radius type and functions
|
|
@tindex mpcr_t
|
|
@tindex mpcr_ptr
|
|
@tindex mpcr_srcptr
|
|
|
|
The radius type is defined by
|
|
@verbatim
|
|
struct {
|
|
int64_t mant;
|
|
int64_t exp;
|
|
}
|
|
@end verbatim
|
|
with the usual trick in the GNU multiprecision libraries of defining the
|
|
main type @code{mpcr_t} as a 1-dimensional array of this struct, and
|
|
variable and constant pointers @code{mpcr_ptr} and @code{mpcr_srcptr}.
|
|
It can contain the special values infinity or zero, or floating point
|
|
numbers encoded as @math{m⋅2@sup{e}} for a positive mantissa
|
|
@math{m} and an arbitrary (usually negative) exponent @math{e}.
|
|
Normalised finite radii use 31 bits for the mantissa, that is,
|
|
@math{2@sup{30}≤m≤2@sup{31} - 1}.
|
|
The special values infinity and 0 are encoded through the sign of
|
|
@math{m}, but should be tested for and set using dedicated functions.
|
|
|
|
Unless indicated otherwise, the following functions
|
|
assume radius arguments to be normalised,
|
|
they return normalised results, and they round their results up, not
|
|
necessarily to the smallest representable number, although reasonable
|
|
effort is made to get a tight upper bound: They only guarantee that
|
|
their outputs are an upper bound on the true results.
|
|
(There may be a trade-off between tightness of the result and speed of
|
|
computation. For instance, when a 32-bit mantissa is normalised, an even
|
|
mantissa should be divided by 2, an odd mantissa should be divided by 2
|
|
and 1 should be added, and then in both cases the exponent must be
|
|
increased by 1. It might be more efficient to add 1 all the time instead
|
|
of testing the last bit of the mantissa.)
|
|
|
|
@deftypefun int mpcr_inf_p (mpcr_srcptr @var{r})
|
|
@deftypefunx int mpcr_zero_p (mpcr_srcptr @var{r})
|
|
Test whether @var{r} is infinity or zero, respectively, and return a
|
|
boolean.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int mpcr_lt_half_p (mpcr_srcptr @var{r})
|
|
Return @code{true} if @var{r}<1/2, and @code{false} otherwise.
|
|
(Everywhere in this document,
|
|
@code{true} means any non-zero value, and @code{false} means zero.)
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int mpcr_cmp (mpcr_srcptr @var{r}, mpcr_srcptr @var{s})
|
|
Return +1, 0 or -1 depending on whether @var{r} is larger than, equal to
|
|
or less than @var{s}, with the natural total order on the compactified
|
|
non-negative real axis letting 0 be smaller and letting infinity be larger
|
|
than any finite real number.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcr_set_inf (mpcr_ptr @var{r})
|
|
@deftypefunx void mpcr_set_zero (mpcr_ptr @var{r})
|
|
@deftypefunx void mpcr_set_one (mpcr_ptr @var{r})
|
|
@deftypefunx void mpcr_set (mpcr_ptr @var{r}, mpcr_srcptr @var{s})
|
|
@deftypefunx void mpcr_set_ui64_2si64 (mpcr_ptr @var{r}, uint64_t @var{mant}, int64_t @var{exp})
|
|
Set @var{r} to infinity, zero, 1, @var{s} or
|
|
@var{mant}⋅2@sup{@var{exp}}, respectively.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcr_max (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t})
|
|
Set @var{r} to the maximum of @var{s} and @var{t}.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int64_t mpcr_get_exp (mpcr_srcptr @var{r})
|
|
Assuming that @var{r} is neither infinity nor 0, return its exponent
|
|
@math{e} when writing @math{r = m⋅2@sup{e}} with
|
|
@math {1/2 ≤ m < 1}. (Notice that this is @emph{not} the same as the
|
|
field @code{exp} in the struct representing a radius, but that instead it
|
|
is independent of the implementation.)
|
|
Otherwise the behaviour is undefined.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcr_out_str (FILE *@var{f}, mpcr_srcptr @var{r})
|
|
Output @var{r} on @var{f}, which may be @code{stdout}.
|
|
Caveat: This function so far serves mainly for debugging purposes, its
|
|
behaviour will probably change in the future.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcr_add (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t})
|
|
@deftypefunx void mpcr_sub (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t})
|
|
@deftypefunx void mpcr_mul (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t})
|
|
@deftypefunx void mpcr_div (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t})
|
|
@deftypefunx void mpcr_mul_2ui (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, unsigned long int @var{t})
|
|
@deftypefunx void mpcr_div_2ui (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, unsigned long int @var{t})
|
|
@deftypefunx void mpcr_sqr (mpcr_ptr @var{r}, mpcr_srcptr @var{s})
|
|
@deftypefunx void mpcr_sqrt (mpcr_ptr @var{r}, mpcr_srcptr @var{s})
|
|
Set @var{r} to the sum, difference, product or quotient of @var{s} and
|
|
@var{t}, or to the product of @var{s} by 2@sup{@var{t}} or to the
|
|
quotient of @var{s} by 2@sup{@var{t}},
|
|
or to the square or the square root of @var{s}.
|
|
If any of the arguments is infinity, or if a difference is negative,
|
|
the result is infinity.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcr_sub_rnd (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t}, mpfr_rnd_t @var{rnd})
|
|
Set @var{r} to the difference of @var{s} and @var{t}, rounded into
|
|
direction @var{rnd}, which can be one of @code{MPFR_RNDU} or
|
|
@code{MPFR_RNDD}. If one of the arguments is infinity or the difference is
|
|
negative, the result is infinity. Calling the function with @code{MPFR_RNDU}
|
|
is equivalent to calling @code{mpcr_sub}.
|
|
|
|
This is one out of several functions taking a rounding parameter. Rounding
|
|
down may be useful to obtain an upper bound when dividing by the result.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcr_c_abs_rnd (mpcr_ptr @var{r}, mpc_srcptr @var{z}, mpfr_rnd_t @var{rnd})
|
|
Set @var{r} to the absolute value of the complex number @var{z}, rounded
|
|
in direction @var{rnd}, which may be one of @code{MPFR_RNDU} or
|
|
@code{MPFR_RNDD}.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcr_add_rounding_error (mpcr_ptr @var{r}, mpfr_prec_t @var{p}, mpfr_rnd_t @var{rnd})
|
|
Set @var{r} to @math{r + (1 + r) 2@sup{-p}} if @var{rnd} equals
|
|
@code{MPFR_RNDN}, and to @math{r + (1 + r) 2@sup{1-p}} otherwise.
|
|
The idea is that if a (potentially not representable) centre of an ideal
|
|
complex ball of radius @var{r} is rounded to a representable complex
|
|
number at precision @var{p}, this shifts the centre by up to 1/2 ulp
|
|
(for rounding to nearest) or 1 ulp (for directed rounding of at least one
|
|
of the real or imaginary parts), which increases the radius accordingly.
|
|
So this function is typically called internally at the end of each
|
|
operation with complex balls to account for the error made by rounding
|
|
the centre.
|
|
@end deftypefun
|
|
|
|
|
|
@section Ball type and functions
|
|
@tindex mpcb_t
|
|
@tindex mpcb_ptr
|
|
@tindex mpcb_srcptr
|
|
|
|
The ball type is defined by
|
|
@verbatim
|
|
typedef struct {
|
|
mpc_t c;
|
|
mpcr_t r;
|
|
}
|
|
@end verbatim
|
|
or, more precisely, @code{mpcb_t} is again a 1-dimensional array of such
|
|
a struct, and variable and constant pointer types are defined as
|
|
@code{mpcb_ptr} and @code{mpcb_srcptr}, respectively.
|
|
As usual, the components should only be accessed through corresponding
|
|
functions.
|
|
|
|
To understand functions on balls, one needs to consider the balls passed
|
|
as arguments as sets of complex values, to which a mathematical function
|
|
is applied; the C function ``rounds up'' in the sense that it returns a
|
|
ball containing all possible values of the function in all the possible
|
|
input values. Reasonable effort is made to return small balls, but again
|
|
there is no guarantee that the result is the smallest possible one.
|
|
In the current implementation, the centre of a ball returned as a value
|
|
is obtained by applying the function to the centres of the balls passed
|
|
as arguments, and rounding. While this is a natural approach, it is not
|
|
the only possible one; however, it also simplifies the error analysis
|
|
as already carried out for functions with regular complex arguments.
|
|
Whenever the centre of a complex ball has a non-finite real or imaginary
|
|
part (positive or negative infinity or NaN) the radius is set to infinity;
|
|
this can be interpreted as the ``useless ball'', representing the whole
|
|
complex plane, whatever the value of the centre is.
|
|
|
|
Unlike for variables of @code{mpc_t} type, where the precision needs to
|
|
be set explicitly at initialisation, variables of type @code{mpcb_t}
|
|
handle their precision dynamically. Ball centres always have the same
|
|
precision for their real and their imaginary parts (again this is a
|
|
choice of the implementation; if they are of very different sizes, one
|
|
could theoretically reduce the precision of the part that is smaller
|
|
in absolute value, which is more strongly affected by the common error
|
|
coded in the radius).
|
|
When setting a complex ball from a value of a different type, an
|
|
additional precision parameter is passed, which determines the precision
|
|
of the centre. Functions on complex balls set the precision of their
|
|
result depending on the input. In the current implementation, this is the
|
|
minimum of the argument precisions, so if all balls are initially set to
|
|
the same precision, this is preserved throughout the computations.
|
|
(Notice that the exponent of the radius encodes roughly the number of
|
|
correct binary digits of the ball centre; so it would also make sense
|
|
to reduce the precision if the radius becomes larger.)
|
|
|
|
The following functions on complex balls are currently available; the
|
|
eclectic collection is motivated by the desire to provide an implementation
|
|
of the arithmetic-geometric mean of complex numbers through the use of
|
|
ball arithmetic. As for functions taking complex arguments, there may
|
|
be arbitrary overlaps between variables representing arguments and
|
|
results; for instance
|
|
@code{mpcb_mul (z, z, z)} is an allowed way of replacing the ball @var{z}
|
|
by its square.
|
|
|
|
|
|
@deftypefun void mpcb_init (mpcb_ptr @var{z})
|
|
@deftypefunx void mpcb_clear (mpcb_ptr @var{z})
|
|
Initialise or free memory for @var{z}; @code{mpcb_init} must be called once
|
|
before using a variable, and @code{mpcb_clear} must be called once before
|
|
stopping to use a variable. Unlike its @code{mpc_t} counterpart,
|
|
@code{mpcb_init} does not fix the precision of @var{z}, but it sets its
|
|
radius to infinity, so that @var{z} represents the whole complex plane.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun mpfr_prec_t mpcb_get_prec (mpcb_srcptr @var{z})
|
|
Return the (common) precision of the real and the complex parts of the
|
|
centre of @var{z}.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcb_set (mpcb_ptr @var{z}, mpcb_srcptr @var{z1})
|
|
Set @var{z} to @var{z1}, preserving the precision of the centre.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcb_set_inf (mpcb_ptr @var{z})
|
|
Set @var{z} to the whole complex plane. This is intended to be used much
|
|
in the spirit of an assertion: When a precondition is not satisfied inside
|
|
a function, it can set its result to this value, which will propagate
|
|
through further computations.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcb_set_c (mpcb_ptr @var{z}, mpc_srcptr @var{c}, mpfr_prec_t @var{prec}, unsigned long int @var{err_re}, unsigned long int @var {err_im})
|
|
Set @var{z} to a ball with centre @var{c} at precision @var{prec}.
|
|
If @var{prec} is at least the maximum of the precisions of the real and the
|
|
imaginary parts of @var{c} and @var{err_re} and @var{err_im} are 0, then
|
|
the resulting ball is exact with radius zero. Using a larger value for
|
|
@var{prec} makes sense if @var{c} is considered exact and a larger target
|
|
precision for the result is desired, or some leeway for the working
|
|
precision is to be taken into account.
|
|
If @var{prec} is less than the precision of @var{c}, then usually some
|
|
rounding error occurs when setting the centre, which is taken into account
|
|
in the radius.
|
|
|
|
If @var{err_re} and @var{err_im} are non-zero, the argument @var{c} is
|
|
considered as an inexact complex number, with a bound on the absolute error
|
|
of its real part given in @var{err_re} as a multiple of 1/2 ulp of the real
|
|
part of @var{c}, and a bound on the absolute error of its imaginary part
|
|
given in @var{err_im} as a multiple of 1/2 ulp of the imaginary part of
|
|
@var{c}. (Notice that if the parts of @var{c} have different precisions or
|
|
exponents, the absolute values of their ulp differ.)
|
|
Then @var{z} is created as a ball with centre @var{c} and a radius taking
|
|
these errors on @var{c} as well as the potential additional rounding error
|
|
for the centre into account.
|
|
If the real part of @var{c} is 0, then @var{err_re} must be 0, since
|
|
ulp of 0 makes no sense; otherwise the radius is set to infinity. The same
|
|
remark holds for the imaginary part.
|
|
|
|
Using @var{err_re} and @var{err_im} different from 0 is particularly
|
|
useful in two settings: If @var{c} is itself the result of a call to an
|
|
@code{mpc_} function with exact input and rounding mode @code{MPC_RNDNN}
|
|
of both parts to nearest, then its parts are known with errors of at most
|
|
1/2 ulp, and setting @var{err_re} and @var{err_im} to 1 yields a ball
|
|
which is known to contain the exact result (this motivates the strange
|
|
unit of 1/2 ulp); if directed rounding was used, @var{err_re} and
|
|
@var{err_im} can be set to 2 instead.
|
|
|
|
And if @var{c} is the result of a sequence of calls to @code{mpc_}
|
|
functions for which some error analysis has been carried out (as is
|
|
frequently the case internally when implementing complex functions),
|
|
again the resulting ball @var{z} is known to contain the exact result
|
|
when using appropriate values for @var{err_re} and @var{err_im}.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcb_set_ui_ui (mpcb_ptr @var{z}, unsigned long int @var{re}, unsigned long int @var {im}, mpfr_prec_t @var{prec})
|
|
Set @var{z} to a ball with centre @var{re}+I*@var{im} at precision
|
|
@var{prec} or the size of an @code{unsigned long int}, whatever is larger.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpcb_neg (mpcb_ptr @var{z}, mpcb_srcptr @var{z1})
|
|
@deftypefunx void mpcb_add (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, mpcb_srcptr @var{z2})
|
|
@deftypefunx void mpcb_mul (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, mpcb_srcptr @var{z2})
|
|
@deftypefunx void mpcb_sqr (mpcb_ptr @var{z}, mpcb_srcptr @var{z1})
|
|
@deftypefunx void mpcb_pow_ui (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, unsigned long int @var{e})
|
|
@deftypefunx void mpcb_sqrt (mpcb_ptr @var{z}, mpcb_srcptr @var{z1})
|
|
@deftypefunx void mpcb_div (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, mpcb_srcptr @var{z2})
|
|
@deftypefunx void mpcb_div_2ui (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, unsigned long int @var{e})
|
|
These are the exact counterparts of the corresponding functions
|
|
@code{mpc_neg}, @code{mpc_add} and so on, but on complex balls instead of
|
|
complex numbers.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int mpcb_can_round (mpcb_srcptr @var{z}, mpfr_prec_t @var{prec_re}, mpfr_prec_t @var{prec_im}, mpc_rnd_t @var{rnd})
|
|
If the function returns @code{true} (a non-zero number), then rounding
|
|
any of the complex numbers in the ball to a complex number with precision
|
|
@var{prec_re} of its real and precision @var{prec_im} of its imaginary
|
|
part and rounding mode @var{rnd} yields the same result and rounding
|
|
direction value, cf. @ref{return-value}.
|
|
If the function returns @code{false} (that is, 0), then it could not
|
|
conclude, or there are two numbers in the ball which would be rounded to
|
|
a different complex number or in a different direction. Notice that the
|
|
function works in a best effort mode and errs on the side of caution by
|
|
potentially returning @code{false} on a roundable ball; this is consistent
|
|
with computational functions not necessarily returning the smallest
|
|
enclosing ball.
|
|
|
|
If @var{z} contains the result of evaluating some mathematical function
|
|
through a sequence of calls to @code{mpcb} functions, starting with exact
|
|
complex numbers, that is, balls of radius 0, then a return value of
|
|
@code{true} indicates that rounding any value in the ball (its centre is
|
|
readily available) in direction @var{rnd} yields the correct result of
|
|
the function and the correct rounding direction value with the usual
|
|
MPC semantics.
|
|
|
|
Notice that when the precision of @var{z} is larger than @var{prec_re}
|
|
or @var{prec_im}, the centre need not be representable at the desired
|
|
precision, and in fact the ball need not contain a representable number
|
|
at all to be ``roundable''. Even worse, when @var{rnd} is a directed
|
|
rounding mode for the real or the imaginary part and the ball of
|
|
non-zero radius contains
|
|
a representable number, the return value is necessarily @code{false}.
|
|
Even worse, when the rounding mode for one part is to nearest, the
|
|
corresponding part of the centre of the ball is representable and the ball
|
|
has a non-zero radius, then the return value is also necessarily
|
|
@code{false}, since even if rounding may be possible, the rounding
|
|
direction value cannot be determined.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun int mpcb_round (mpc_ptr @var{c}, mpcb_srcptr @var{z}, mpc_rnd_t @var{rnd})
|
|
Set @var{c} to the centre of @var{z}, rounded in direction @var{rnd},
|
|
and return the corresponding rounding direction value.
|
|
If @code{mpcb_can_round}, called with @var {z}, the precisions of @var{c}
|
|
and the rounding mode @var{rnd} returns @code{true}, then this function
|
|
does what is expected, it ``correctly rounds the ball'' and returns a
|
|
rounding direction value that is valid for all of the ball.
|
|
As explained above, the result is then not necessarily (in the presence of
|
|
directed rounding with radius different from 0, it is rather
|
|
necessarily not) an element of the ball.
|
|
@end deftypefun
|
|
|
|
|
|
|
|
@node References
|
|
@unnumbered References
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
Torbj@"orn Granlund et al.
|
|
@code{GMP} -- GNU multiprecision library.
|
|
Version 6.2.0, @url{http://gmplib.org}.
|
|
|
|
@item
|
|
Guillaume Hanrot, Vincent Lef@`evre, Patrick P@'elissier, Paul Zimmermann et al.
|
|
@code{MPFR} -- A library for multiple-precision floating-point computations with exact rounding.
|
|
Version 4.1.0, @url{http://www.mpfr.org}.
|
|
|
|
@item
|
|
IEEE Standard for Floating-Point Arithmetic,
|
|
IEEE Computer Society,
|
|
IEEE Std 754-2019, Approved 13 June 2019, 84 pages.
|
|
|
|
@item
|
|
Donald E. Knuth, "The Art of Computer Programming", vol 2,
|
|
"Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981.
|
|
|
|
@item
|
|
ISO/IEC 9899:1999, Programming languages — C.
|
|
|
|
@end itemize
|
|
|
|
@node Concept Index
|
|
@unnumbered Concept Index
|
|
@printindex cp
|
|
|
|
@node Function Index
|
|
@unnumbered Function Index
|
|
@printindex fn
|
|
|
|
@node Type Index
|
|
@unnumbered Type Index
|
|
@printindex tp
|
|
|
|
@node GNU Free Documentation License
|
|
@appendix GNU Free Documentation License
|
|
@include fdl-1.3.texi
|
|
|
|
@ifnothtml
|
|
@contents
|
|
@end ifnothtml
|
|
|
|
@bye
|