Re: polred and variants

[John Cremona <john.cremona@gmail.com>]

Thanks Karim,

You answered all my questions.  (I do understand the difference
between | and ||, that was just a slip.) I'm not even sure that I need
the ring of integers.   (The fields in question are the Hecke
eigenvalue fields of Bianchi modular forms, by the way).

When I searched through the pdf manual I did not notice that I reached
a section on obsolete functions (yes, I see that the section heading
is on the same page...).  But it is still true that there is no
documentation in this manual for any non-obsolete *polred* functions.

One suggested improvement to the gp documentation for nf_ORIG: it
seems to me that the second thing returned by the nf_ORIG flag is
Mod(a,P) and not a itself: in the code I have to use lift() to get the
polynomial.

John

On Thu, 22 Jan 2026 at 17:30, Karim Belabas <Karim.Belabas@u-bordeaux.fr> wrote:
>
> Hi John,
>
> * John Cremona [2026-01-22 16:05]:
> > In the  manual https://pari.math.u-bordeaux.fr/pub/pari/manuals/2.18.1/libpari.pdf
> > there are mentioned a whole lot of functions called 'polred' with
> > various prefixes and suffixes.  In fact the string 'polred' appears 20
> > times, all on p.327 or in the index.
> >
> > None of these have any documentation at all, except for the comment on
> > p.327 "use polredbest" -- but polredbest is not referred to anywhere
> > else in the manual.
>
> You mean the section "13.1.32 Obsolete routines" ?
>
> Their common documentation, as already suggested by the section title, is
>
>   "Still provided for backward compatibility, but should not be used in new
>   programs. They will eventually disappear."
>
> > Please may we add documentation for some or all these functions to
> > this manual?
>
> The idea is not to use them anymore. You can do the same or better using
> documented functions.
>
> > I have a C program where I successfully use both both
> > plain polredabs() which juIs there any documentation anywhere st
> > returns one reduced polynomial, and also polredabs0() with flag
> > nf_ORIG which also returns a polynomial giving one root in terms of
> > the other.  That is useful.  From gp I can see documentation using
> > ??polredabs which says that the library function is called
> > polredabs0(), but does not mention polredabs() in the library --
> > should I stop using that but use polredabs0() with flag=0?
>
> Yes, it's cleaner.
>
> > I know about polredbest() but my polynomials have small degree and
> > polredabs is fast for them.
>
> As you wish. If you really know what you are doing, then fine.
>
> >   I currently use flag nf_ORIG but am
> > about to start to use nf_ADDZK so that I also get the integral basis.
> > I think that to get both the nf_ORIG polynomial I need to use as flag
> > nf_ORIG||nf_ADDZK (is that right?)
>
> No. Binary or (= single |) not boolean or :
>
>    nf_ORIG | nf_ADDZK
>
> But the gp documentation is out of date: the nf_ADDZK flag was removed
> in 2018. The modern way nowadays, as mentioned in ??polredabs and fully
> documented in ??nfinit, is to call your functions (polred, nfinit, etc.)
> with input [P, nfbasis(P)] rather than trying to obtain the integer
> basis as a byproduct of various operations in cryptic/inconsistent ways.
>
> By the way, if your polynomials are so small than polredabs is acceptably fast,
> I wouldn't bother, though. Chances are the time needed to recompute the
> integral basis is negligible. Please test.
>
> > and the output will be of the form
> > [[reduced-poly, root_poly], [list of integral basis]].  Again, is that
> > right?
>
> Not anymore, see above.
>
> > The gp flags are differernt from the library flags (only numerical 1
> > and 4 not the symbolic nf_ORIG etc.)
>
> Yes. The gp flags are bad: cryptic and less flexible. Use a combination
> of symbolic flags (or-ing properties attached to powers of 2 is standard C
> practice, not a libpari quirk). All this is documented in the gp users's
> manual, where all the math is explained. This is a general decision with
> respect to documentation : gp user's manual should document all
> mathematical features and the libpari user manual does not re-document
> anything that was there to avoid massive duplication (and out-of-synch doc).
>
> -------------------
>    The library syntax is GEN polredabs0(GEN T, long flag). Instead of the above
> hardcoded numerical flags, one should use an or-ed combination of
>
> *  nf_PARTIALFACT   (OBSOLETE):  possibly  use a suborder of the maximal order,
> without attempting to certify the result.
>
> * nf_ORIG: return [P, a], where Mod(a, P) is a root of T.
>
> * nf_RAW: return [P, b], where Mod(b, T) is a root of P.  The algebraic integer
> b  is  the  raw result produced by the small vectors enumeration in the maximal
> order;  P was computed as the characteristic polynomial of Mod(b, T). Mod(a, P)
> as in nf_ORIG is obtained with modreverse.
>
> * nf_ALL: return a vector of results of the above form,  for all polynomials of
> minimal T_2-norm.
> -------------------
>
> What would you suggest to improve there ?
>
> Cheers,
>
>     K.B.
> --
> Pr. Karim Belabas, U. Bordeaux, Vice-président en charge du Numérique
> Institut de Mathématiques de Bordeaux UMR 5251 - (+33) 05 40 00 29 77
> http://www.math.u-bordeaux.fr/~kbelabas/