nf and qqbar into python-flint?

[dimpase]

We (in sagemath) have an interest in bringing Flint's number fields, i.e. nf and qqbar into sagemath; I prefer this happening via python-flint.

We also have a current GSoC student @Madhu18S looking into this sagemath/sage#42261

@fredrik-johansson

Originally posted by @dimpase in #53

[Madhu18S]

Hi, I am the GSoC student working with @dimpase on this integration.

I have been running diagnostics on the experimental _gr module locally using a native FLINT 3 build to evaluate the context design pattern for gr_complex_qqbar_ctx and gr_real_qqbar_ctx.

Structurally, this context-centric approach matches perfectly with what we need for a clean integration into Sage's parent/element framework. The underlying Calcium evaluation and element arithmetic dispatch through these contexts smoothly, and things like repr handle relations beautifully (e.g., CA(2).sqrt() + 1 evaluates to the exact algebraic expression under the hood).

However, to make these contexts viable as a functional backend engine for Sage's QQbar, the element constructors will need to be expanded. Currently, the gr contexts only instantiate elements from single scalar types; attempting to pass polynomial strings or coefficient lists (which Sage relies on to define algebraic numbers via minimal polynomials) triggers type conversion errors.

My immediate focus is shifting to extending these context constructors to interface with FLINT/Calcium's low-level polynomial root-finding hooks (like qqbar_roots), ensuring that these domain objects can handle full polynomial-based element instantiation. I will also be digging into the fmpz_poly bindings.

[oscarbenjamin]

Structurally, this context-centric approach matches perfectly with what we need for a clean integration into Sage's parent/element framework.

How would you envisage this looking?

Right now the _gr module is experimental. Having worked through the design a bit I think we should look to reorganise it. It would be better to have not just separate context classes but also separate element classes for e.g. elements of QQbar vs CA etc. Currently in _gr all domains end up using the same gr type but that is not very nice in Python where lots of code would expect to do something like isinstance(obj, QQbarElement).

[Madhu18S]

That is a very good point, @oscarbenjamin. Having dedicated element classes like QQbarElement or AlgebraicNumber rather than a monolithic gr type is much cleaner and fits better with how SageMath handles parent/element relationships (where parents like QQbar map to specific element types).

This is how I envisage the user-facing API looking, incorporating both our points(using the current _gr structural layout as a base) :
QQbar = _gr.gr_complex_qqbar_ctx.new()

//1. Simple scalar instantiation remains clean:
x = QQbar(2).sqrt() + 1
isinstance(x, QQbarElement) // True

// 2. Polynomial-based root instantiation: Define an algebraic number via its minimal polynomial
p = fmpz_poly([-2, 0, 1]) // x^2 - 2

// Option A: Context method (factory pattern)
alpha = QQbar.from_poly(p, root_index=0)

// Option B: Direct Element constructor via context dispatch
beta = QQbar(p, root_index=0)

Personally, I think having the context class double as a factory or allowing the context constructor to dynamically dispatch when it receives an fmpz_poly object (Option B) would keep the syntax very intuitive.

If we split the elements into distinct classes, would you envision QQbarElement inheriting from a common base class like FlintGenericElement to share basic arithmetic dispatches, while overriding domain-specific methods? And down the line, would these context/domain objects be exposed directly at the top-level flint namespace?

[oscarbenjamin]

So I think there are a few separate things that could be done here:

1. Just add non-generic types for nf and qqbar similar to the existing types like nmod, fmpz etc in python-flint.
2. Add more functionality to the existing _gr design in python-flint to make nf and qqbar more useful/usable from that interface and add tests for the features that are needed in sagemath.
3. Completely redesign the _gr module in python-flint and then have separate classes for all types including nf and qqbar as well as fmpz etc and have these eventually replace the existing non-generic types in python-flint.

Ultimately I think that the last option is what should be done in python-flint but it is a significantly bigger task and would be a big digression from the immediate basic goal of adding a usable interface for the nf and qqbar types in python-flint. The first option would be the easiest approach for the scope of a GSOC project I think.

What I am not sure about is how this would be used in SageMath. Would SageMath have a Python wrapper around these? In SageMath most types are part of a big system of base classes but those cannot be used in python-flint because it does not depend on SageMath.

[dimpase]

my idea was to add Cython code here so that it can be used in SageMath Cython interface - and also used in python-flint.
But maybe this is not realistic

[oscarbenjamin]

We could add Cython code here. Currently python-flint does not expose any cython bindings (it does not ship the .xd files) but it would be good to provide cython bindings.

I'm not sure how much cython bindings in python-flint would help sagemath though compared to sagemath having its own cython code for whatever it is that would be in python-flint. Much of the cython code here is such a thin wrapper around calling a C function that the cython binding would not be much easier to wrap than the original C library.

Having Python (rather than Cython) code in sagemath that wraps things in python-flint would reduce the collective code maintenance/development burden but would obviously have the runtime overhead of a Python wrapper.

[Madhu18S]

That makes a lot more sense, going with the first options of writing the non-generic types.
Regarding the Cython/Sage boundary—since python-flint doesn't export its .pxd headers right now, Sage wouldn't get a true C-level speedup from wrapping python-flint's Cython . If Sage needs maximum performance without Python wrapper overhead for specific tight loops, it can always hit FLINT's C API directly. But having native nf and qqbar types directly in python-flint gives Sage (and everyone else) a fast interface out of the box.

I’ve been digging into the underlying C functions like gr_poly_roots and checking out how inputs get normalized. If this sounds good to you both, I can start sketching out a dedicated QQbar element class modeled after the existing stable wrappers. What do you think?

[oscarbenjamin]

python-flint doesn't export its .pxd headers right now, Sage wouldn't get a true C-level speedup from wrapping python-flint's Cython

I think it would be fine to start distributing these. I'm just not sure how exactly that works and how much benefit it would give.

I can start sketching out a dedicated QQbar element class modeled after the existing stable wrappers. What do you think?

That sounds good to me.

I think that qqbar would be simpler to wrap than nf so is probably a good starting point.

The gr code for qqbar distinguishes between real_qqbar and complex_qqbar. I think that python-flint's wrapper should probably do the same and it probably also makes sense for SageMath too (although if SageMath is wrapping this then it could just be handled in the wrapper). In Python real and complex numbers are expected to have different methods e.g. with real numbers you can do x < 2 or float(x) but those usually give errors for complex types. I think that it would maybe make sense to have:

• A type called something like qqbar_real_elem for real qqbar elements.
• A context object for real qqbar with methods for manipulating/converting real qqbar elements and for getting the real roots of a fmpz_poly/fmpq_poly.
• A type like qqbar_complex_elem for complex qqbar elements.
• A context object for complex qqbar that can get all roots (as a mix of real and complex elements?).
• Maybe some common base classes for these real vs complex context and element types?

Then perhaps later nf number fields can have real/complex types and can be initialised from qqbar_real_elem or qqbar_complex_elem to specify the field generator.

[oscarbenjamin]

If that is the design then perhaps a good starting point would just be the real qqbar part.

[dimpase]

On June 22, 2026 12:58:33 PM CDT, Oscar Benjamin ***@***.***> wrote: oscarbenjamin left a comment (flintlib/python-flint#398) If that is the design then perhaps a good starting point would just be the real qqbar part.

Sage has `QQbar` - the field of algebraic numbers, and `AA` - the field of real algebraic numbers. Yes, it's good to start from `AA`, which is the "base ring" (in Sage terms) of `QQbar`.

[Madhu18S]

Hi, quick update before I head out of station for the next 4 days:

Following your advice to start with the real algebraic numbers context (AA), I dug into the _gr module, resolved the local Cython compilation bottlenecks, and successfully hooked up the gr_real_qqbar_ctx layer. The singleton initializes cleanly directly from the underlying FLINT C layer (gr_ctx_init_real_qqbar) without any hitches.

I've committed this foundational context layer locally. As soon as I'm back on july 5th, I'll pick right back up with sketching out the qqbar_real_elem element allocation methods and setting up initial root-finding test cases.

[oscarbenjamin]

I'm not sure if there are big advantages or disadvantages either way but I was imagining using qqbar directly rather than gr_real_qqbar. If this is being implemented as non-generic types then we don't need the gr functions. One general disadvantage of using gr is that it always gives an extra pointer indirection and heap allocation but I don't know how significant that actually is.

[dimpase]

@Madhu18S - your GSoC midterm evaluations are due by 2026-07-10. We need to see some working code.

[Madhu18S]

Thank you for the feedback.
Oscar—that makes perfect sense. I will definitely try.
Dima—Thank you for the reminder on the midterm evaluations. To make sure my progress is visible, I have pushed my exploratory compilation work (getting the build configuration stabilized and verifying the C-backend context initialization without segfaults) to my fork under the branch name feature/qqbar-experimental.
I will be traveling and completely away from my machine for the next 4 days (returning July 5th). The moment I am back, I am pivoting entirely to sketching out the direct qqbar wrappers based on this new design path. We will have a solid, working implementation ready well before the July 10th deadline.

[Madhu18S]

Hi Dima and Oscar,

Following up on Oscar's advice to bypass the generic gr layer and use the direct types directly to avoid heap allocation overhead, I shifted focus to binding the direct qqbar types. I wanted to share my working progress.

I have resolved the local Cython build/path bottlenecks for qqbar.pyx and qqbar.pxd against the updated upstream FLINT headers. The library now compiles completely and installs in editable mode.

The code is now executing at runtime. Here is the current status of the direct implementation:
`>>> import flint

from flint import qqbar
x = qqbar()
##The object now successfully allocates in memory via the C-layer
print(x)
AttributeError: 'flint.types.qqbar.qqbar' object has no attribute 'str'`

The underlying C-allocation is completely functional. The current bottleneck is simply that the .str() string conversion wrapper hasn't been implemented yet, which is causing the Python print() method to catch.
I have pushed my local branch and opened a Draft PR here so you can review the codebase updates directly:
#413
Now that the build pipeline is unblocked, my immediate next step over the next 48 hours is completing the missing string conversion and constructor methods so we can initialize non-zero values.