Re: polred and variants

[Karim Belabas <Karim.Belabas@u-bordeaux.fr>]

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/