FLINT3.7.0-dev
/

gr_ctx_init_transformed_mpn

Synopsis#include <flint/gr.h>
int gr_ctx_init_transformed_mpn(gr_ctx_t ctx, slong bits_bound, slong terms_bound, int is_signed, slong num_live, int alloc_strategy)source

Constructs the ring of transformed big integers: bilinear expressions over \mathbb{Z} whose value is below 2^{\mathit{bits\_bound}} in absolute value, with at most terms_bound accumulated elementary products and multiplicative depth two. Elements carry a sign bit when is_signed is nonzero; mixed-sign accumulations switch the pointwise additions and subtractions, and the sign of a mixed result is resolved at conversion out.

bits_bound bounds the magnitude of any single represented product; the representation provisions the accumulation capacity from terms_bound and the sign headroom from is_signed itself, so callers must not add either to the bound. num_live declares how many elements are expected alive simultaneously; the constructor declines (GR_UNABLE) when their combined transform storage would exceed flint_fft_small_max_transformed_ring_size.

alloc_strategy selects how element storage is obtained. GR_TRANSFORMED_MPN_ALLOC_MALLOC allocates each element separately. GR_TRANSFORMED_MPN_ALLOC_FIT_BUFFER reserves a stable region of the thread's fft_small scratch buffer holding num_live element slabs, from which gr_init draws and to which gr_clear returns; initialisations beyond num_live simultaneously live elements fall back to separate allocation. The reservation makes repeated context creation cheap, since the region persists in the thread's scratch buffer across contexts. It is designed for a context that is the only user of fft_small on its thread while it lives (construct, compute, destroy), which is how every library caller uses it. This is an assumption rather than a requirement: while a reservation is live the thread's scratch buffer can neither grow nor move, and an interleaved fft_small operation, such as an integer multiplication large enough to reach it, is served from a secondary buffer instead (see mpn_ctx_fit_buffer). A context held across unrelated work therefore stays correct. One reservation exists per thread, so a context constructed while another holds it silently uses separate allocation. Elements must be initialised with gr_init or GR_TMP_INIT_VEC in every strategy.

Conversions out whose destination window is too short to hold the reconstruction are staged inside the ring, and that staging is provisioned with the reservation (well under one element's storage, reserved past the slabs). A caller that will always have an element dead by the time it converts may add the flag GR_TRANSFORMED_MPN_SCRATCH_FROM_SLAB to alloc_strategy, and the ring then takes a free slab for the staging instead of reserving anything. The flag declares a footprint, not a correctness contract: if no slab is free the ring falls back to an allocation cached for the lifetime of the context. One conversion may be in flight at a time.

A context may be shared by several threads, each working on its own elements: element storage and staging are managed by an operand pool (shared with the complex products of fft_small) whose bookkeeping is locked, and every conversion takes independent scratch. A context holding a reservation pins the creating thread's scratch buffer and must be cleared on that thread, after all its elements.

Guides#

Cite this page

The FLINT team, “gr_ctx_init_transformed_mpn (gr.h),” FLINT: Fast Library for Number Theory, documentation, version 3.7.0-dev, 2026. https://flintlib.org/doc/gr/gr_ctx_init_transformed_mpn.html (generated 2026-10-20).