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 zero-length argument list.)

  • (Not implemented): a user-defined constant or function defined by suppling a function pointer for Arb numerical evaluation to specified precision.

The ca_ext_t structure is heavy-weight 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 Antic nf_t in the case of algebraic numbers, and a pointer to arguments in the case of a symbolic function), and a cached acb_t enclosure (in the case of a qqbar_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.

void ca_ext_init_set(ca_ext_t res, const ca_ext_t x, ca_ctx_t ctx)

Initializes res and sets it to a copy of x.

void ca_ext_clear(ca_ext_t res, ca_ctx_t ctx)

Clears res.

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 built-in 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

void ca_ext_print(const ca_ext_t x, const ca_ctx_t ctx)

Prints a description of x to standard output.

Numerical evaluation

void ca_ext_get_acb_raw(acb_t res, ca_ext_t x, slong prec, ca_ctx_t ctx)

Sets res to an enclosure of the numerical value of x. A working precision of prec bits is used for the evaluation, without adaptive refinement.

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 heap-allocated ca_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.