acb.h – complex numbers¶
An acb_t represents a complex number with
error bounds. An acb_t consists of a pair of real number
balls of type arb_struct, representing the real and
imaginary part with separate error bounds.
An acb_t thus represents a rectangle
\([m_1-r_1, m_1+r_1] + [m_2-r_2, m_2+r_2] i\) in the complex plane.
This is used instead of a disk or square representation
(consisting of a complex floating-point midpoint with a single radius),
since it allows implementing many operations more conveniently by splitting
into ball operations on the real and imaginary parts.
It also allows tracking when complex numbers have an exact (for example
exactly zero) real part and an inexact imaginary part, or vice versa.
The interface for the acb_t type is slightly less developed
than that for the arb_t type. In many cases, the user can
easily perform missing operations by directly manipulating the real and
imaginary parts.
Types, macros and constants¶
-
acb_struct¶
-
acb_t¶ An acb_struct consists of a pair of arb_struct:s. An acb_t is defined as an array of length one of type acb_struct, permitting an acb_t to be passed by reference.
-
acb_ptr¶ Alias for
acb_struct *, used for vectors of numbers.
-
acb_srcptr¶ Alias for
const acb_struct *, used for vectors of numbers when passed as constant input to functions.
-
acb_realref(x)¶ Macro returning a pointer to the real part of x as an arb_t.
-
acb_imagref(x)¶ Macro returning a pointer to the imaginary part of x as an arb_t.
Memory management¶
Basic manipulation¶
Input and output¶
-
void
acb_printd(const acb_t z, slong digits)¶ Prints x in decimal. The printed value of the radius is not adjusted to compensate for the fact that the binary-to-decimal conversion of both the midpoint and the radius introduces additional error.
Random number generation¶
-
void
acb_randtest(acb_t z, flint_rand_t state, slong prec, slong mag_bits)¶ Generates a random complex number by generating separate random real and imaginary parts.
-
void
acb_randtest_special(acb_t z, flint_rand_t state, slong prec, slong mag_bits)¶ Generates a random complex number by generating separate random real and imaginary parts. Also generates NaNs and infinities.
Precision and comparisons¶
-
int
acb_equal(const acb_t x, const acb_t y)¶ Returns nonzero iff x and y are identical as sets, i.e. if the real and imaginary parts are equal as balls.
Note that this is not the same thing as testing whether both x and y certainly represent the same complex number, unless either x or y is exact (and neither contains NaN). To test whether both operands might represent the same mathematical quantity, use
acb_overlaps()oracb_contains(), depending on the circumstance.
-
int
acb_eq(const acb_t x, const acb_t y)¶ Returns nonzero iff x and y are certainly equal, as determined by testing that
arb_eq()holds for both the real and imaginary parts.
-
int
acb_ne(const acb_t x, const acb_t y)¶ Returns nonzero iff x and y are certainly not equal, as determined by testing that
arb_ne()holds for either the real or imaginary parts.
-
int
acb_overlaps(const acb_t x, const acb_t y)¶ Returns nonzero iff x and y have some point in common.
-
void
acb_get_abs_ubound_arf(arf_t u, const acb_t z, slong prec)¶ Sets u to an upper bound for the absolute value of z, computed using a working precision of prec bits.
-
void
acb_get_abs_lbound_arf(arf_t u, const acb_t z, slong prec)¶ Sets u to a lower bound for the absolute value of z, computed using a working precision of prec bits.
-
void
acb_get_rad_ubound_arf(arf_t u, const acb_t z, slong prec)¶ Sets u to an upper bound for the error radius of z (the value is currently not computed tightly).
-
void
acb_get_mag_lower(mag_t u, const acb_t x)¶ Sets u to a lower bound for the absolute value of x.
-
int
acb_contains_int(const acb_t x)¶ Returns nonzero iff the complex interval represented by x contains an integer.
-
slong
acb_rel_error_bits(const acb_t x)¶ Returns the effective relative error of x measured in bits. This is computed as if calling
arb_rel_error_bits()on the real ball whose midpoint is the larger out of the real and imaginary midpoints of x, and whose radius is the larger out of the real and imaginary radiuses of x.
-
slong
acb_rel_accuracy_bits(const acb_t x)¶ Returns the effective relative accuracy of x measured in bits, equal to the negative of the return value from
acb_rel_error_bits().
-
slong
acb_bits(const acb_t x)¶ Returns the maximum of arb_bits applied to the real and imaginary parts of x, i.e. the minimum precision sufficient to represent x exactly.
-
void
acb_indeterminate(acb_t x)¶ Sets x to \([\operatorname{NaN} \pm \infty] + [\operatorname{NaN} \pm \infty]i\), representing an indeterminate result.
-
void
acb_trim(acb_t y, const acb_t x)¶ Sets y to a a copy of x with both the real and imaginary parts trimmed (see
arb_trim()).
Complex parts¶
-
void
acb_arg(arb_t r, const acb_t z, slong prec)¶ Sets r to a real interval containing the complex argument (phase) of z. We define the complex argument have a discontinuity on \((-\infty,0]\), with the special value \(\operatorname{arg}(0) = 0\), and \(\operatorname{arg}(a+0i) = \pi\) for \(a < 0\). Equivalently, if \(z = a+bi\), the argument is given by \(\operatorname{atan2}(b,a)\) (see
arb_atan2()).
-
void
acb_sgn(acb_t r, const acb_t z, slong prec)¶ Sets r to the complex sign of z, defined as 0 if z is exactly zero and the projection onto the unit circle \(z / |z| = \exp(i \arg(z))\) otherwise.
-
void
acb_csgn(arb_t r, const acb_t z)¶ Sets r to the extension of the real sign function taking the value 1 for z strictly in the right half plane, -1 for z strictly in the left half plane, and the sign of the imaginary part when z is on the imaginary axis. Equivalently, \(\operatorname{csgn}(z) = z / \sqrt{z^2}\) except that the value is 0 when z is exactly zero.
Arithmetic¶
-
void
acb_sub(acb_t z, const acb_t x, const acb_t y, slong prec)¶ Sets z to the difference of x and y.
-
void
acb_mul_arb(acb_t z, const acb_t x, const arb_t y, slong prec)¶ Sets z to the product of x and y.
-
void
acb_mul(acb_t z, const acb_t x, const acb_t y, slong prec)¶ Sets z to the product of x and y. If at least one part of x or y is zero, the operations is reduced to two real multiplications. If x and y are the same pointers, they are assumed to represent the same mathematical quantity and the squaring formula is used.
-
void
acb_mul_2exp_fmpz(acb_t z, const acb_t x, const fmpz_t e)¶ Sets z to x multiplied by \(2^e\), without rounding.
-
void
acb_cube(acb_t z, const acb_t x, slong prec)¶ Sets z to x cubed, computed efficiently using two real squarings, two real multiplications, and scalar operations.
-
void
acb_addmul_arb(acb_t z, const acb_t x, const arb_t y, slong prec)¶ Sets z to z plus the product of x and y.
Powers and roots¶
-
void
acb_sqrt(acb_t r, const acb_t z, slong prec)¶ Sets r to the square root of z. If either the real or imaginary part is exactly zero, only a single real square root is needed. Generally, we use the formula \(\sqrt{a+bi} = u/2 + ib/u, u = \sqrt{2(|a+bi|+a)}\), requiring two real square root extractions.
-
void
acb_rsqrt(acb_t r, const acb_t z, slong prec)¶ Sets r to the reciprocal square root of z. If either the real or imaginary part is exactly zero, only a single real reciprocal square root is needed. Generally, we use the formula \(1/\sqrt{a+bi} = ((a+r) - bi)/v, r = |a+bi|, v = \sqrt{r |a+bi+r|^2}\), requiring one real square root and one real reciprocal square root.
-
void
acb_quadratic_roots_fmpz(acb_t r1, acb_t r2, const fmpz_t a, const fmpz_t b, const fmpz_t c, slong prec)¶ Sets r1 and r2 to the roots of the quadratic polynomial \(ax^2 + bx + c\). Requires that a is nonzero. This function is implemented so that both roots are computed accurately even when direct use of the quadratic formula would lose accuracy.
-
void
acb_root_ui(acb_t r, const acb_t z, ulong k, slong prec)¶ Sets r to the principal k-th root of z.
Exponentials and logarithms¶
-
void
acb_exp(acb_t y, const acb_t z, slong prec)¶ Sets y to the exponential function of z, computed as \(\exp(a+bi) = \exp(a) \left( \cos(b) + \sin(b) i \right)\).
-
void
acb_exp_invexp(acb_t s, acb_t t, const acb_t z, slong prec)¶ Sets \(v = \exp(z)\) and \(w = \exp(-z)\).
Trigonometric functions¶
-
void
acb_sin_cos(acb_t s, acb_t c, const acb_t z, slong prec)¶ Sets \(s = \sin(z)\), \(c = \cos(z)\), evaluated as \(\sin(a+bi) = \sin(a)\cosh(b) + i \cos(a)\sinh(b)\), \(\cos(a+bi) = \cos(a)\cosh(b) - i \sin(a)\sinh(b)\).
-
void
acb_tan(acb_t s, const acb_t z, slong prec)¶ Sets \(s = \tan(z) = \sin(z) / \cos(z)\). For large imaginary parts, the function is evaluated in a numerically stable way as \(\pm i\) plus a decreasing exponential factor.
-
void
acb_cot(acb_t s, const acb_t z, slong prec)¶ Sets \(s = \cot(z) = \cos(z) / \sin(z)\). For large imaginary parts, the function is evaluated in a numerically stable way as \(\pm i\) plus a decreasing exponential factor.
-
void
acb_sin_cos_pi(acb_t s, acb_t c, const acb_t z, slong prec)¶ Sets \(s = \sin(\pi z)\), \(c = \cos(\pi z)\), evaluating the trigonometric factors of the real and imaginary part accurately via
arb_sin_cos_pi().
-
void
acb_tan_pi(acb_t s, const acb_t z, slong prec)¶ Sets \(s = \tan(\pi z)\). Uses the same algorithm as
acb_tan(), but evaluates the sine and cosine accurately viaarb_sin_cos_pi().
Inverse trigonometric functions¶
-
void
acb_asin(acb_t res, const acb_t z, slong prec)¶ Sets res to \(\operatorname{asin}(z) = -i \log(iz + \sqrt{1-z^2})\).
Hyperbolic functions¶
Inverse hyperbolic functions¶
-
void
acb_asinh(acb_t res, const acb_t z, slong prec)¶ Sets res to \(\operatorname{asinh}(z) = -i \operatorname{asin}(iz)\).
Rising factorials¶
-
void
acb_rising(acb_t z, const acb_t x, const acb_t n, slong prec)¶ Computes the rising factorial \(z = x (x+1) (x+2) \cdots (x+n-1)\).
The bs version uses binary splitting. The rs version uses rectangular splitting. The rec version uses either bs or rs depending on the input. The default version uses the gamma function unless n is a small integer.
The rs version takes an optional step parameter for tuning purposes (to use the default step length, pass zero).
-
void
acb_rising2_ui(acb_t u, acb_t v, const acb_t x, ulong n, slong prec)¶ Letting \(u(x) = x (x+1) (x+2) \cdots (x+n-1)\), simultaneously compute \(u(x)\) and \(v(x) = u'(x)\), respectively using binary splitting, rectangular splitting (with optional nonzero step length step to override the default choice), and an automatic algorithm choice.
Gamma function¶
-
void
acb_rgamma(acb_t y, const acb_t x, slong prec)¶ Computes the reciprocal gamma function \(y = 1/\Gamma(x)\), avoiding division by zero at the poles of the gamma function.
-
void
acb_lgamma(acb_t y, const acb_t x, slong prec)¶ Computes the logarithmic gamma function \(y = \log \Gamma(x)\).
The branch cut of the logarithmic gamma function is placed on the negative half-axis, which means that \(\log \Gamma(z) + \log z = \log \Gamma(z+1)\) holds for all \(z\), whereas \(\log \Gamma(z) \ne \log(\Gamma(z))\) in general. In the left half plane, the reflection formula with correct branch structure is evaluated via
acb_log_sin_pi().
-
void
acb_digamma(acb_t y, const acb_t x, slong prec)¶ Computes the digamma function \(y = \psi(x) = (\log \Gamma(x))' = \Gamma'(x) / \Gamma(x)\).
-
void
acb_log_sin_pi(acb_t res, const acb_t z, slong prec)¶ Computes the logarithmic sine function defined by
\[S(z) = \log(\pi) - \log \Gamma(z) + \log \Gamma(1-z)\]which is equal to
\[S(z) = \int_{1/2}^z \pi \cot(\pi t) dt\]where the path of integration goes through the upper half plane if \(0 < \arg(z) \le \pi\) and through the lower half plane if \(-\pi < \arg(z) \le 0\). Equivalently,
\[S(z) = \log(\sin(\pi(z-n))) \mp n \pi i, \quad n = \lfloor \operatorname{re}(z) \rfloor\]where the negative sign is taken if \(0 < \arg(z) \le \pi\) and the positive sign is taken otherwise (if the interval \(\arg(z)\) does not certainly satisfy either condition, the union of both cases is computed). After subtracting n, we have \(0 \le \operatorname{re}(z) < 1\). In this strip, we use use \(S(z) = \log(\sin(\pi(z)))\) if the imaginary part of z is small. Otherwise, we use \(S(z) = i \pi (z-1/2) + \log((1+e^{-2i\pi z})/2)\) in the lower half-plane and the conjugated expression in the upper half-plane to avoid exponent overflow.
The function is evaluated at the midpoint and the propagated error is computed from \(S'(z)\) to get a continuous change when \(z\) is non-real and \(n\) spans more than one possible integer value.
-
void
acb_polygamma(acb_t z, const acb_t s, const acb_t z, slong prec)¶ Sets res to the value of the generalized polygamma function \(\psi(s,z)\).
If s is a nonnegative order, this is simply the s-order derivative of the digamma function. If \(s = 0\), this function simply calls the digamma function internally. For integers \(s \ge 1\), it calls the Hurwitz zeta function. Note that for small integers \(s \ge 1\), it can be faster to use
acb_poly_digamma_series()and read off the coefficients.The generalization to other values of s is due to Espinosa and Moll [EM2004]:
\[\psi(s,z) = \frac{\zeta'(s+1,z) + (\gamma + \psi(-s)) \zeta(s+1,z)}{\Gamma(-s)}\]
-
void
acb_log_barnes_g(acb_t res, const acb_t z, slong prec)¶ Computes Barnes G-function or the logarithmic Barnes G-function, respectively. The logarithmic version has branch cuts on the negative real axis and is continuous elsewhere in the complex plane, in analogy with the logarithmic gamma function. The functional equation
\[\log G(z+1) = \log \Gamma(z) + \log G(z).\]holds for all z.
For small integers, we directly use the recurrence relation \(G(z+1) = \Gamma(z) G(z)\) together with the initial value \(G(1) = 1\). For general z, we use the formula
\[\log G(z) = (z-1) \log \Gamma(z) - \zeta'(-1,z) + \zeta'(-1).\]
Zeta function¶
-
void
acb_zeta(acb_t z, const acb_t s, slong prec)¶ Sets z to the value of the Riemann zeta function \(\zeta(s)\). Note: for computing derivatives with respect to \(s\), use
acb_poly_zeta_series()or related methods.
-
void
acb_hurwitz_zeta(acb_t z, const acb_t s, const acb_t a, slong prec)¶ Sets z to the value of the Hurwitz zeta function \(\zeta(s, a)\). Note: for computing derivatives with respect to \(s\), use
acb_poly_zeta_series()or related methods.
-
void
acb_bernoulli_poly_ui(acb_t res, ulong n, const acb_t x, slong prec)¶ Sets res to the value of the Bernoulli polynomial \(B_n(x)\).
Warning: this function is only fast if either n or x is a small integer.
This function reads Bernoulli numbers from the global cache if they are already cached, but does not automatically extend the cache by itself.
Polylogarithms¶
Arithmetic-geometric mean¶
See Algorithms for the arithmetic-geometric mean for implementation details.
-
void
acb_agm1(acb_t m, const acb_t z, slong prec)¶ Sets m to the arithmetic-geometric mean \(M(z) = \operatorname{agm}(1,z)\), defined such that the function is continuous in the complex plane except for a branch cut along the negative half axis (where it is continuous from above). This corresponds to always choosing an “optimal” branch for the square root in the arithmetic-geometric mean iteration.
Other special functions¶
Vector functions¶
-
int
_acb_vec_is_zero(acb_srcptr vec, slong len)¶ Returns nonzero iff all entries in x are zero.
-
int
_acb_vec_is_real(acb_srcptr v, slong len)¶ Returns nonzero iff all entries in x have zero imaginary part.
-
void
_acb_vec_set(acb_ptr res, acb_srcptr vec, slong len)¶ Sets res to a copy of vec.
-
void
_acb_vec_set_round(acb_ptr res, acb_srcptr vec, slong len, slong prec)¶ Sets res to a copy of vec, rounding each entry to prec bits.
-
void
_acb_vec_neg(acb_ptr res, acb_srcptr vec, slong len)¶
-
void
_acb_vec_add(acb_ptr res, acb_srcptr vec1, acb_srcptr vec2, slong len, slong prec)¶
-
void
_acb_vec_sub(acb_ptr res, acb_srcptr vec1, acb_srcptr vec2, slong len, slong prec)¶
-
void
_acb_vec_scalar_mul_2exp_si(acb_ptr res, acb_srcptr vec, slong len, slong c)¶
-
void
_acb_vec_scalar_mul_onei(acb_ptr res, acb_srcptr vec, slong len)¶
-
void
_acb_vec_scalar_div_fmpz(acb_ptr res, acb_srcptr vec, slong len, const fmpz_t c, slong prec)¶ Performs the respective scalar operation elementwise.
-
slong
_acb_vec_bits(acb_srcptr vec, slong len)¶ Returns the maximum of
arb_bits()for all entries in vec.
-
void
_acb_vec_set_powers(acb_ptr xs, const acb_t x, slong len, slong prec)¶ Sets xs to the powers \(1, x, x^2, \ldots, x^{len-1}\).
-
void
_acb_vec_add_error_mag_vec(acb_ptr res, mag_srcptr err, slong len)¶ Adds the magnitude of each entry in err to the radius of the corresponding entry in res.
-
void
_acb_vec_indeterminate(acb_ptr vec, slong len)¶ Applies
acb_indeterminate()elementwise.
-
void
_acb_vec_trim(acb_ptr res, acb_srcptr vec, slong len)¶ Applies
acb_trim()elementwise.
-
int
_acb_vec_get_unique_fmpz_vec(fmpz * res, acb_srcptr vec, slong len)¶ Calls
acb_get_unique_fmpz()elementwise and returns nonzero if all entries can be rounded uniquely to integers. If any entry in vec cannot be rounded uniquely to an integer, returns zero.
