ca_ext.h – real and complex extension numbers¶
A ca_ext_t
represents a fixed real or complex number a.
The content of a ca_ext_t
can be one of the following:
An algebraic constant represented in canonical form by a
qqbar_t
instance (example: \(i\), represented as the root of \(x^2+1\) with positive imaginary part).A constant of the form \(f(x_1, \ldots, x_n)\) where f is a builtin symbolic function and \(x_1, \ldots, x_n\) are given
ca_t
instances.A builtin symbolic constant such as \(\pi\). (This is just a special case of the above with a zerolength argument list.)
(Not implemented): a userdefined constant or function defined by suppling a function pointer for Arb numerical evaluation to specified precision.
The ca_ext_t
structure is heavyweight object, not just meant to act
as a node in a symbolic expression. It will cache various data to support
repeated computation with this particular number, including its numerical
enclosure and number field data in the case of algebraic numbers.
Extension numbers are used internally by the ca_t
type to
define the embeddings \(\mathbb{Q}(a) \to \mathbb{C}\) of formal fields.
The user does not normally need to create ca_ext_t
instances
directly; the intended way for the user to work with the extension number a
is to create a ca_t
representing the field element \(1 \cdot a\).
The underlying ca_ext_t
may be accessed to
determine symbolic and numerical properties of this number.
Since extension numbers may depend recursively on nontrivial fields for
function arguments, ca_ext_t
operations require a ca_ctx_t
context object.
Type and macros¶
For all types, a type_t is defined as an array of length one of type type_struct, permitting a type_t to be passed by reference.

type
ca_ext_struct
¶

type
ca_ext_t
¶ An extension number object contains a header, a hash value, data (a
qqbar_t
instance and an Anticnf_t
in the case of algebraic numbers, and a pointer to arguments in the case of a symbolic function), and a cachedacb_t
enclosure (in the case of aqqbar_t
, the enclosure internal to that structure is used).

type
ca_ext_ptr
¶ Alias for
ca_ext_struct *
.

type
ca_ext_srcptr
¶ Alias for
const ca_ext_struct *
.

CA_EXT_HEAD
(x)¶ Accesses the head (a
calcium_func_code
) of x. This is CA_QQBar if x represents an algebraic constant in canonical form, and CA_Exp, CA_Pi, etc. for symbolic functions and constants.

CA_EXT_HASH
(x)¶ Accesses the hash value of x.

CA_EXT_QQBAR
(x)¶ Assuming that x represents an algebraic constant in canonical form, accesses this
qqbar_t
object.

CA_EXT_QQBAR_NF
(x)¶ Assuming that x represents an algebraic constant in canonical form, accesses the corresponding Antic number field
nf_t
object.

CA_EXT_FUNC_ARGS
(x)¶ Assuming that x represents a symbolic constant or function, accesses the argument list (as a
ca_ptr
).

CA_EXT_FUNC_NARGS
(x)¶ Assuming that x represents a symbolic constant or function, accesses the number of function arguments.

CA_EXT_FUNC_ENCLOSURE
(x)¶ Assuming that x represents a symbolic constant or function, accesses the cached
acb_t
numerical enclosure.

CA_EXT_FUNC_PREC
(x)¶ Assuming that x represents a symbolic constant or function, accesses the working precision of the cached numerical enclosure.
Memory management¶

void
ca_ext_init_qqbar
(ca_ext_t res, const qqbar_t x, ca_ctx_t ctx)¶ Initializes res and sets it to the algebraic constant x.

void
ca_ext_init_const
(ca_ext_t res, calcium_func_code func, ca_ctx_t ctx)¶ Initializes res and sets it to the constant defined by func (example: func = CA_Pi for \(x = \pi\)).

void
ca_ext_init_fx
(ca_ext_t res, calcium_func_code func, const ca_t x, ca_ctx_t ctx)¶ Initializes res and sets it to the univariate function value \(f(x)\) where f is defined by func (example: func = CA_Exp for \(e^x\)).

void
ca_ext_init_fxy
(ca_ext_t res, calcium_func_code func, const ca_t x, const ca_t y, ca_ctx_t ctx)¶ Initializes res and sets it to the bivariate function value \(f(x, y)\) where f is defined by func (example: func = CA_Pow for \(x^y\)).

void
ca_ext_init_fxn
(ca_ext_t res, calcium_func_code func, ca_srcptr x, slong nargs, ca_ctx_t ctx)¶ Initializes res and sets it to the multivariate function value \(f(x_1, \ldots, x_n)\) where f is defined by func and n is given by nargs.
Structure¶

slong
ca_ext_nargs
(const ca_ext_t x, ca_ctx_t ctx)¶ Returns the number of function arguments of x. The return value is 0 for any algebraic constant and for any builtin symbolic constant such as \(\pi\).

void
ca_ext_get_arg
(ca_t res, const ca_ext_t x, slong i, ca_ctx_t ctx)¶ Sets res to argument i (indexed from zero) of x. This calls flint_abort if i is out of range.

ulong
ca_ext_hash
(const ca_ext_t x, ca_ctx_t ctx)¶ Returns a hash of the structural representation of x.

int
ca_ext_equal_repr
(const ca_ext_t x, const ca_ext_t y, ca_ctx_t ctx)¶ Tests x and y for structural equality, returning 0 (false) or 1 (true).

int
ca_ext_cmp_repr
(const ca_ext_t x, const ca_ext_t y, ca_ctx_t ctx)¶ Compares the representations of x and y in a canonical sort order, returning 1, 0 or 1. This only performs a structural comparison of the symbolic representations; the return value does not say anything meaningful about the numbers represented by x and y.
Input and output¶
Numerical evaluation¶
Cache¶

type
ca_ext_cache_struct
¶

type
ca_ext_cache_t
¶ Represents a set of structurally distinct
ca_ext_t
instances. This object contains an array of pointers to individual heapallocatedca_ext_struct
objects as well as a hash table for quick lookup.

void
ca_ext_cache_init
(ca_ext_cache_t cache, ca_ctx_t ctx)¶ Initializes cache for use.

void
ca_ext_cache_clear
(ca_ext_cache_t cache, ca_ctx_t ctx)¶ Clears cache, freeing the memory allocated internally.

ca_ext_ptr
ca_ext_cache_insert
(ca_ext_cache_t cache, const ca_ext_t x, ca_ctx_t ctx)¶ Adds x to cache without duplication. If a structurally identical instance already exists in cache, a pointer to that instance is returned. Otherwise, a copy of x is inserted into cache and a pointer to that new instance is returned.