1% Copyright (c) 2000 The PARI Group 2% 3% This file is part of the PARI/GP documentation 4% 5% Permission is granted to copy, distribute and/or modify this document 6% under the terms of the GNU General Public License 7\chapter{Technical Reference Guide: the basics} 8 9In the following chapters, we describe all public low-level functions of the 10PARI library. These include specialized functions for handling all the PARI 11types. Simple higher level functions, such as arithmetic or transcendental 12functions, are described in Chapter~3 of the GP user's manual; we will 13eventually see more general or flexible versions in the chapters to come. A 14general introduction to the major concepts of PARI programming can be found 15in Chapter~4, which you should really read first. 16 17We shall now study specialized functions, more efficient than the library 18wrappers, but sloppier on argument checking and damage control; besides 19speed, their main advantage is to give finer control about the inner 20workings of generic routines, offering more options to the programmer. 21 22\misctitle{Important advice} Generic routines eventually call lower level 23functions. Optimize your algorithms first, not overhead and conversion costs 24between PARI routines. For generic operations, use generic routines first; 25do not waste time looking for the most specialized one available unless you 26identify a genuine bottleneck, or you need some special behavior the generic 27routine does not offer. The PARI source code is part of the documentation; 28look for inspiration there.\smallskip 29 30The type \kbd{long} denotes a \tet{BITS_IN_LONG}-bit signed long integer (32 31or 64 bits). The type \tet{ulong} is defined as \kbd{unsigned long}. The word 32\emph{stack} always refer to the PARI stack, allocated through an initial 33\kbd{pari\_init} call. Refer to Chapters 1--2 and~4 for general background. 34\kbdsidx{BIL} 35 36We shall often refer to the notion of \tev{shallow} function, which means that 37some components of the result may point to components of the input, which is 38more efficient than a \emph{deep} copy (full recursive copy of the object 39tree). Such outputs are not suitable for \kbd{gerepileupto} and particular 40care must be taken when garbage collecting objects which have been input to 41shallow functions: corresponding outputs also become invalid and should no 42longer be accessed. 43 44A function is \emph{not stack clean} if it leaves intermediate data on the 45stack besides its output, for efficiency reasons. 46 47\section{Initializing the library} 48 49The following functions enable you to start using the PARI functions 50in a program, and cleanup without exiting the whole program. 51 52\subsec{General purpose} 53 54\fun{void}{pari_init}{size_t size, ulong maxprime} initialize the 55library, with a stack of \kbd{size} bytes and a prime table 56up to the maximum of \kbd{maxprime} and $2^{16}$. Unless otherwise 57mentioned, no PARI function will function properly before such an 58initialization. 59 60\fun{void}{pari_close}{void} stop using the library (assuming it was 61initialized with \kbd{pari\_init}) and frees all allocated objects. 62 63\subsec{Technical functions}\label{se:pari_init_tech} 64 65\fun{void}{pari_init_opts}{size_t size, ulong maxprime, ulong opts} as 66\kbd{pari\_init}, more flexible. \kbd{opts} is a mask of flags 67among the following: 68 69 \kbd{INIT\_JMPm}: install PARI error handler. When an exception is 70raised, the program is terminated with \kbd{exit(1)}. 71 72 \kbd{INIT\_SIGm}: install PARI signal handler. 73 74 \kbd{INIT\_DFTm}: initialize the \kbd{GP\_DATA} environment structure. 75This one \emph{must} be enabled once. If you close pari, then restart it, 76you need not reinitialize \kbd{GP\_DATA}; if you do not, then old values are 77restored. 78 79 \kbd{INIT\_noPRIMEm}: do not compute the prime table (ignore the 80 \kbd{maxprime} argument). The user \emph{must} call 81 \tet{pari_init_primes} later. 82 83 \kbd{INIT\_noIMTm}: (technical, see \kbd{pari\_mt\_init} in the Developer's 84Guide for detail). Do not call \tet{pari_mt_init} to initialize the 85multi-thread engine. If this flag is set, \kbd{pari\_mt\_init()} will need to 86be called manually. See \kbd{examples/pari-mt.c} for an example. 87 88 \kbd{INIT\_noINTGMPm}: do not install PARI-specific GMP memory functions. 89This option is ignored when the GMP library is not in use. You may 90install PARI-specific GMP memory functions later by calling 91 92\fun{void}{pari_kernel_init}{void} 93 94\noindent and restore the previous values using 95 96\fun{void}{pari_kernel_close}{void} 97 98This option should not be used without a thorough understanding of the 99problem you are trying to solve. The GMP memory functions are global 100variables used by the GMP library. If your program is linked with two 101libraries that require these variables to be set to different values, 102conflict ensues. To avoid a conflict, the proper solution is to record 103their values with \kbd{mp\_get\_memory\_functions} and to call 104\kbd{mp\_set\_memory\_functions} to restore the expected values each time the 105code switches from using one library to the other. Here is an example: 106\bprog 107void *(*pari_alloc_ptr) (size_t); 108void *(*pari_realloc_ptr) (void *, size_t, size_t); 109void (*pari_free_ptr) (void *, size_t); 110void *(*otherlib_alloc_ptr) (size_t); 111void *(*otherlib_realloc_ptr) (void *, size_t, size_t); 112void (*otherlib_free_ptr) (void *, size_t); 113 114void init(void) 115{ 116 pari_init(8000000, 500000); 117 mp_get_memory_functions(&pari_alloc_ptr,&pari_realloc_ptr, 118 &pari_free_ptr); 119 otherlib_init(); 120 mp_get_memory_functions(&otherlib_alloc_ptr,&otherlib_realloc_ptr, 121 &otherlib_free_ptr); 122} 123void function_that_use_pari(void) 124{ 125 mp_set_memory_functions(pari_alloc_ptr,pari_realloc_ptr, 126 pari_free_ptr); 127 /*use PARI functions*/ 128} 129void function_that_use_otherlib(void) 130{ 131 mp_set_memory_functions(otherlib_alloc_ptr,otherlib_realloc_ptr, 132 otherlib_free_ptr); 133 /*use OTHERLIB functions*/ 134} 135@eprog 136 137\fun{void}{pari_close_opts}{ulong init_opts} as \kbd{pari\_close}, 138for a library initialized with a mask of options using 139\kbd{pari\_init\_opts}. \kbd{opts} is a mask of flags among 140 141 \kbd{INIT\_SIGm}: restore \kbd{SIG\_DFL} default action for signals 142tampered with by PARI signal handler. 143 144 \kbd{INIT\_DFTm}: frees the \kbd{GP\_DATA} environment structure. 145 146 \kbd{INIT\_noIMTm}: (technical, see \kbd{pari\_mt\_init} in the Developer's 147Guide for detail). Do not call \tet{pari_mt_close} to close the multi-thread 148engine. 149 \kbd{INIT\_noINTGMPm}: do not restore GMP memory functions. 150 151\fun{void}{pari_sig_init}{void (*f)(int)} install the signal handler \kbd{f} 152(see \kbd{signal(2)}): the signals \kbd{SIGBUS}, \kbd{SIGFPE}, \kbd{SIGINT}, 153\kbd{SIGBREAK}, \kbd{SIGPIPE} and \kbd{SIGSEGV} are concerned. 154 155\fun{void}{pari_init_primes}{ulong maxprime} Initialize the PARI 156primes. This function is called by \kbd{pari\_init(\dots,maxprime)}. 157It is provided for users calling \kbd{pari\_init\_opts} with the 158flag \kbd{INIT\_noPRIMEm}. 159 160\fun{void}{pari_sighandler}{int signum} the actual signal handler that 161PARI uses. This can be used as argument to \kbd{pari\_sig\_init} or 162\kbd{signal(2)}. 163 164\fun{void}{pari_stackcheck_init}{void *stackbase} controls the system stack 165exhaustion checking code in the GP interpreter. This should be used when the 166system stack base address change or when the address seen by \kbd{pari\_init} 167is too far from the base address. If \kbd{stackbase} is \kbd{NULL}, disable the 168check, else set the base address to \kbd{stackbase}. It is normally used this 169way 170\bprog 171int thread_start (...) 172{ 173 long first_item_on_the_stack; 174 ... 175 pari_stackcheck_init(&first_item_on_the_stack); 176} 177@eprog 178 179\fun{int}{pari_daemon}{void} forks a PARI daemon, detaching from the main 180process group. The function returns 1 in the parent, and 0 in the 181forked son. 182 183\fun{void}{paristack_setsize}{size_t rsize, size_t vsize} 184sets the default \kbd{parisize} to \kbd{rsize} and the 185default \kbd{parisizemax} to \kbd{vsize}, and reallocate the 186stack to match these value, destroying its content. 187Generally used just after \kbd{pari\_init}. 188 189\fun{void}{paristack_resize}{ulong newsize} 190changes the current stack size to \kbd{newsize} 191(double it if \kbd{newsize} is 0). 192The new size is clipped to be at least the current stack size and 193at most \kbd{parisizemax}. The stack content is not affected 194by this operation. 195 196\fun{void}{parivstack_reset}{void} 197resets the current stack to its default size \kbd{parisize}. This is 198used to recover memory after a computation that enlarged the stack. 199This function destroys the content of the enlarged stack (between 200the old and the new bottom of the stack). 201Before calling this function, you must ensure that \kbd{avma} lies 202within the new smaller stack. 203 204\fun{void}{paristack_newrsize}{ulong newsize} 205\emph{(does not return)}. Library version of 206\bprog 207 default(parisize, "newsize") 208@eprog\noindent Set the default \kbd{parisize} to \kbd{newsize}, or double 209\kbd{parisize} if \kbd{newsize} is equal to 0, then call 210\kbd{cb\_pari\_err\_recover(-1)}. 211 212\fun{void}{parivstack_resize}{ulong newsize} 213\emph{(does not return)}. Library version of 214\bprog 215 default(parisizemax, "newsize") 216@eprog\noindent Set the default \kbd{parisizemax} to \kbd{newsize} and call 217\kbd{cb\_pari\_err\_recover(-1)}. 218 219\subsec{Notions specific to the GP interpreter} 220 221An \kbd{entree} is the generic object attached to an identifier (a name) 222in GP's interpreter, be it a built-in or user function, or a variable. For 223a function, it has at least the following fields: 224 225 \kbd{char *name}: the name under which the interpreter knows us. 226 227 \kbd{void *value}: a pointer to the C function to call. 228 229 \kbd{long menu}: a small integer $\geq 1$ (to which group of function 230 help do we belong, for the \kbd{?$n$} help menu). 231 232 \kbd{char *code}: the prototype code. 233 234 \kbd{char *help}: the help text for the function. 235 236A routine in GP is described to the analyzer by an \kbd{entree} 237structure. Built-in PARI routines are grouped in \emph{modules}, which 238are arrays of \kbd{entree} structs, the last of which satisfy 239\kbd{name = NULL} (sentinel). There are currently four modules in PARI/GP: 240 241\item general functions (\tet{functions_basic}, known to \kbd{libpari}), 242 243\item gp-specific functions (\tet{functions_gp}), 244 245\noindent and two modules of obsolete functions. The function 246\kbd{pari\_init} initializes the interpreter and declares all symbols in 247\kbd{functions\_basic}. You may declare further functions on a case by case 248basis or as a whole module using 249 250\fun{void}{pari_add_function}{entree *ep} adds a single routine to the 251table of symbols in the interpreter. It assumes \kbd{pari\_init} has been 252called. 253 254\fun{void}{pari_add_module}{entree *mod} adds all the routines in module 255\kbd{mod} to the table of symbols in the interpreter. It assumes 256\kbd{pari\_init} has been called. 257 258\noindent For instance, gp implements a number of private routines, which 259it adds to the default set via the calls 260\bprog 261 pari_add_module(functions_gp); 262@eprog 263 264A GP \kbd{default} is likewise attached to a helper routine, that is run 265when the value is consulted, or changed by \tet{default0} or \tet{setdefault}. 266Such routines are grouped in the module \tet{functions_default}. 267 268\fun{void}{pari_add_defaults_module}{entree *mod} adds all the defaults in 269module \kbd{mod} to the interpreter. It assumes that \kbd{pari\_init} has 270been called. From this point on, all defaults in module \kbd{mod} are known 271to \tet{setdefault} and friends. 272 273\subsec{Public callbacks} 274 275The \kbd{gp} calculator associates elaborate functions (for instance the 276break loop handler) to the following callbacks, and so can you: 277 278\doc{cb_pari_ask_confirm}{void (*cb_pari_ask_confirm)(const char *s)} 279initialized to \kbd{NULL}. Called with argument $s$ whenever PARI wants 280confirmation for action $s$, for instance in \tet{secure} mode. 281 282\doc{cb_pari_init_histfile}{void (*cb_pari_init_histfile)(void)} 283initialized to \kbd{NULL}. Called when the \kbd{histfile} default 284is changed. The intent is for that callback to read the file content, append 285it to history in memory, then dump the expanded history to the new 286\kbd{histfile}. 287 288\doc{cb_pari_is_interactive}{int (*cb_pari_is_interactive)(void)}; 289initialized to \kbd{NULL}. 290 291\doc{cb_pari_quit}{void (*cb_pari_quit)(long)} 292initialized to a no-op. Called when \kbd{gp} must evaluate the \kbd{quit} 293command. 294 295\doc{cb_pari_start_output}{void (*cb_pari_start_output)(void)} 296initialized to \kbd{NULL}. 297 298\doc{cb_pari_handle_exception}{int (*cb_pari_handle_exception)(long)} 299initialized to \kbd{NULL}. If not \kbd{NULL}, this routine is called with 300argument $-1$ on \kbd{SIGINT}, and argument \kbd{err} on error \kbd{err}. If 301it returns a nonzero value, the error or signal handler returns, in effect 302further ignoring the error or signal, otherwise it raises a fatal error. 303A possible simple-minded handler, used by the \kbd{gp} interpreter, is 304 305\fun{int}{gp_handle_exception}{long err} if the \kbd{breakloop} 306default is enabled (set to $1$) and \tet{cb_pari_break_loop} is not 307\kbd{NULL}, we call this routine with \kbd{err} argument and return the 308result. 309 310\doc{cb_pari_err_handle}{int (*cb_pari_err_handle)(GEN)} 311If not \kbd{NULL}, this routine is called with a \typ{ERROR} argument 312from \kbd{pari\_err}. If it returns a nonzero value, the error returns, in 313effect further ignoring the error, otherwise it raises a fatal error. 314 315The default behavior is to print a descriptive error 316message (display the error), then return 0, thereby raising a fatal error. 317This differs from \tet{cb_pari_handle_exception} in that the 318function is not called on \kbd{SIGINT} (which do not generate a \typ{ERROR}), 319only from \kbd{pari\_err}. Use \tet{cb_pari_sigint} if you need to handle 320\kbd{SIGINT} as well. 321 322The following function can be used by \kbd{cb\_pari\_err\_handle} to display 323the error message. 324 325\fun{const char*}{closure_func_err}{} return a statically allocated string 326holding the name of the function that triggered the error. Return NULL if the 327error was not caused by a function. 328 329\doc{cb_pari_break_loop}{int (*cb_pari_break_loop)(int)} 330initialized to \kbd{NULL}. 331 332\doc{cb_pari_sigint}{void (*cb_pari_sigint)(void)}. 333Function called when we receive \kbd{SIGINT}. By default, raises 334\bprog 335 pari_err(e_MISC, "user interrupt"); 336@eprog\noindent A possible simple-minded variant, used by the 337\kbd{gp} interpreter, is 338 339\fun{void}{gp_sigint_fun}{void} 340 341\doc{cb_pari_pre_recover}{void (*cb_pari_pre_recover)(long)} 342initialized to \kbd{NULL}. If not \kbd{NULL}, this routine is called just 343before PARI cleans up from an error. It is not required to return. The error 344number is passed as argument. 345 346\doc{cb_pari_err_recover}{void (*cb_pari_err_recover)(long)} 347initialized to \kbd{pari\_exit()}. This callback must not return. 348It is called after PARI has cleaned-up from an error. The error number is 349passed as argument, unless the PARI stack has been destroyed, in which case 350it is called with argument $-1$. 351 352\doc{cb_pari_whatnow}{int (*cb_pari_whatnow)(PariOUT *out, const char *s, int 353flag)} initialized to \kbd{NULL}. If not \kbd{NULL}, must check whether $s$ 354existed in older versions of \kbd{pari} (the \kbd{gp} callback checks against 355\kbd{pari-1.39.15}). All output must be done via \kbd{out} methods. 356 357\item $\fl = 0$: should print verbosely the answer, including help text if 358available. 359 360\item $\fl = 1$: must return $0$ if the function did not change, and a 361nonzero result otherwise. May print a help message. 362 363\subsec{Configuration variables} 364 365\tet{pari_library_path}: If set, It should be a path to the libpari library. 366It is used by the function \tet{gpinstall} to locate the PARI library when 367searching for symbols. This should only be useful on Windows. 368 369\subsec{Utility functions} 370 371\fun{void}{pari_ask_confirm}{const char *s} raise an error if the 372callback \tet{cb_pari_ask_confirm} is \kbd{NULL}. Otherwise 373calls 374\bprog 375 cb_pari_ask_confirm(s); 376@eprog 377 378\fun{char*}{gp_filter}{const char *s} pre-processor for the GP 379parser: filter out whitespace and GP comments from $s$. The returned string 380is allocated on the PARI stack and must not be freed. 381 382\fun{GEN}{pari_compile_str}{const char *s} low-level form of 383\tet{compile_str}: assumes that $s$ does not contain spaces or GP comments and 384returns the closure attached to the GP expression $s$. Note 385that GP metacommands are not recognized. 386 387\fun{int}{gp_meta}{const char *s, int ismain} low-level component of 388\tet{gp_read_str}: assumes that $s$ does not contain spaces or GP comments and 389try to interpret $s$ as a GP metacommand (e.g. starting by \kbd{\bs} or 390\kbd{?}). If successful, execute the metacommand and return $1$; otherwise 391return $0$. The \kbd{ismain} parameter modifies the way \kbd{\bs r} commands 392are handled: if nonzero, act as if the file contents were entered via 393standard input (i.e. call \tet{switchin} and divert \tet{pari_infile}); 394otherwise, simply call \tet{gp_read_file}. 395 396\fun{void}{pari_hit_return}{void} wait for the use to enter \kbd{\bs n} 397via standard input. 398 399\fun{void}{gp_load_gprc}{void} read and execute the user's \kbd{GPRC} file. 400 401\fun{void}{pari_center}{const char *s} print $s$, centered. 402 403\fun{void}{pari_print_version}{void} print verbose version information. 404 405\fun{long}{pari_community}{void} return the index of the support section 406n the help. 407 408\fun{const char*}{gp_format_time}{long t} format a delay of $t$ ms 409suitable for \kbd{gp} output, with \kbd{timer} set. The string is allocated 410in the PARI stack via \kbd{stack\_malloc}. 411 412\fun{const char*}{gp_format_prompt}{const char *p} format a prompt $p$ 413suitable for \kbd{gp} prompting (includes colors and protecting ANSI escape 414sequences for readline). 415 416\fun{void}{pari_alarm}{long s} set an alarm after $s$ seconds (raise an 417\tet{e_ALARM} exception). 418 419\fun{void}{gp_help}{const char *s, long flag} print help for $s$, depending 420on the value of \fl: 421 422\item \tet{h_REGULAR}, basic help (\kbd{?}); 423 424\item \tet{h_LONG}, extended help (\kbd{??}); 425 426\item \tet{h_APROPOS}, a propos help (\kbd{??}). 427 428\fun{const char **}{gphelp_keyword_list}{void} return a 429\kbd{NULL}-terminated array a strings, containing keywords known to 430\kbd{gphelp} besides GP functions (e.g. \kbd{modulus} or \kbd{operator}). 431Used by the online help system and the contextual completion engine. 432 433\fun{void}{gp_echo_and_log}{const char *p, const char *s} given a prompt 434$p$ and attached input command $s$, update logfile and possibly 435print on standard output if \tet{echo} is set and we are not in interactive 436mode. The callback \tet{cb_pari_is_interactive} must be set to a sensible 437value. 438 439\fun{void}{gp_alarm_handler}{int sig} the \kbd{SIGALRM} handler 440set by the \kbd{gp} interpreter. 441 442\fun{void}{print_fun_list}{char **list, long n} 443print all elements of \kbd{list} in columns, pausing (hit return) 444every $n$ lines. \kbd{list} is \kbd{NULL} terminated. 445 446\subsec{Saving and restoring the GP context} 447 448\fun{void}{gp_context_save}{struct gp_context* rec} save the current GP 449context. 450 451\fun{void}{gp_context_restore}{struct gp_context* rec} restore a GP context. 452The new context must be an ancestor of the current context. 453 454\subsec{GP history} 455 456These functions allow to control the GP history (the \kbd{\%} operator). 457 458\fun{void}{pari_add_hist}{GEN x, long t, long r} adds \kbd{x} as the last history 459entry; $t$ (resp. r) is the cpu (resp. real) time used to compute it. 460 461\fun{GEN}{pari_get_hist}{long p}, if $p>0$ returns entry of index $p$ 462(i.e. \kbd{\%p}), else returns entry of index $n+p$ where $n$ is the 463index of the last entry (used for \kbd{\%}, \kbd{\%`}, \kbd{\%``}, etc.). 464 465\fun{long}{pari_get_histtime}{long p} as \tet{pari_get_hist}, 466returning the cpu time used to compute the history entry, instead of the entry 467itself. 468 469\fun{long}{pari_get_histrtime}{long p} as \tet{pari_get_hist}, 470returning the real time used to compute the history entry, instead of the entry 471itself. 472 473\fun{GEN}{pari_histtime}{long p} return the vector \kbd{[cpu, real]} where 474\kbd{cpu} and \kbd{real} are as above. 475 476\fun{ulong}{pari_nb_hist}{void} return the index of the last entry. 477 478\section{Handling \kbd{GEN}s} 479\noindent Almost all these functions are either macros or inlined. Unless 480mentioned otherwise, they do not evaluate their arguments twice. Most of them 481are specific to a set of types, although no consistency checks are made: 482e.g.~one may access the \kbd{sign} of a \typ{PADIC}, but the result is 483meaningless. 484 485\subsec{Allocation} 486 487\fun{GEN}{cgetg}{long l, long t} allocates (the root of) a \kbd{GEN} 488of type $t$ and length $l$. Sets $z[0]$. 489 490\fun{GEN}{cgeti}{long l} allocates a \typ{INT} of length $l$ (including the 4912 codewords). Sets $z[0]$ only. 492 493\fun{GEN}{cgetr}{long l} allocates a \typ{REAL} of length $l$ (including the 4942 codewords). Sets $z[0]$ only. 495 496\fun{GEN}{cgetc}{long prec} allocates a \typ{COMPLEX} whose real and 497imaginary parts are \typ{REAL}s of length \kbd{prec}. 498 499\fun{GEN}{cgetg_copy}{GEN x, long *lx} fast version of \kbd{cgetg}: 500allocate a \kbd{GEN} with the same type and length as $x$, setting \kbd{*lx} 501to \kbd{lg(x)} as a side-effect. (Only sets the first codeword.) This is 502a little faster than \kbd{cgetg} since we may reuse the bitmask in 503$x[0]$ instead of recomputing it, and we do not need to check that the 504length does not overflow the possibilities of the 505implementation (since an object with that length already exists). Note that 506\kbd{cgetg} with arguments known at compile time, as in 507\bprog 508 cgetg(3, t_INTMOD) 509@eprog\noindent will be even faster since the compiler will directly perform 510all computations and checks. 511 512\fun{GEN}{vectrunc_init}{long l} perform \kbd{cgetg(l,t\_VEC)}, then 513set the length to $1$ and return the result. This is used to implement 514vectors whose final length is easily bounded at creation time, that we intend 515to fill gradually using: 516 517\fun{void}{vectrunc_append}{GEN x, GEN y} assuming $x$ was allocated using 518\tet{vectrunc_init}, appends $y$ as the last element of $x$, which 519grows in the process. The function is shallow: we append $y$, not a copy; 520it is equivalent to 521\bprog 522 long lx = lg(x); gel(x,lx) = y; setlg(x, lx+1); 523@eprog\noindent 524Beware that the maximal size of $x$ (the $l$ argument to \tet{vectrunc_init}) 525is unknown, hence unchecked, and stack corruption will occur if we append 526more than $l-1$ elements to $x$. Use the safer (but slower) 527\kbd{shallowconcat} when $l$ is not easy to bound in advance. 528 529An other possibility is simply to allocate using \kbd{cgetg(l, t)} then fill 530the components as they become available: this time the downside is that we do 531not obtain a correct \kbd{GEN} until the vector is complete. Almost no PARI 532function will be able to operate on it. 533 534\fun{void}{vectrunc_append_batch}{GEN x, GEN y} successively apply 535\bprog 536 vectrunc_append(x, gel(y, i)) 537@eprog 538for all elements of the vector $y$. 539 540\fun{GEN}{coltrunc_init}{long l} as \kbd{vectrunc\_init} but perform 541\kbd{cgetg(l,t\_COL)}. 542 543\fun{GEN}{vecsmalltrunc_init}{long l} 544 545\fun{void}{vecsmalltrunc_append}{GEN x, long t} analog to the above for a 546\typ{VECSMALL} container. 547 548\subsec{Length conversions} 549 550These routines convert a nonnegative length to different units. Their 551behavior is undefined at negative integers. 552 553\fun{long}{ndec2nlong}{long x} converts a number of decimal digits to a number 554of words. Returns $ 1 + \kbd{floor}(x \times \B \log_2 10)$. 555 556\fun{long}{ndec2prec}{long x} converts a number of decimal digits to a number 557of codewords. This is equal to 2 + \kbd{ndec2nlong(x)}. 558 559\fun{long}{ndec2nbits}{long x} convers a number of decimal digits to a 560number of bits. 561 562\fun{long}{prec2ndec}{long x} converts a number of codewords to a 563number of decimal digits. 564 565\fun{long}{nbits2nlong}{long x} converts a number of bits to a number of 566words. Returns the smallest word count containing $x$ bits, i.e $ 567\kbd{ceil}(x / \B)$. 568 569\fun{long}{nbits2ndec}{long x} converts a number of bits to a number of 570decimal digits. 571 572\fun{long}{nbits2lg}{long x} converts a number of bits to a length 573in code words. Currently an alias for \kbd{nbits2nlong}. 574 575\fun{long}{nbits2prec}{long x} converts a number of bits to a number of 576codewords. This is equal to 2 + \kbd{nbits2nlong(x)}. 577 578\fun{long}{nbits2extraprec}{long x} converts a number of bits to the mantissa 579length of a \typ{REAL} in codewords. This is currently an alias to 580\kbd{nbits2nlong(x)}. 581 582\fun{long}{nchar2nlong}{long x} converts a number of bytes to number of 583words. Returns the smallest word count containing $x$ bytes, i.e 584$\kbd{ceil}(x / \kbd{sizeof(long)})$. 585 586\fun{long}{prec2nbits}{long x} converts a \typ{REAL} length into a number 587of significant bits; returns $(x - 2)\B$. 588 589\fun{double}{prec2nbits_mul}{long x, double y} returns 590\kbd{prec2nbits}$(x)\times y$. 591 592\fun{long}{bit_accuracy}{long x} converts a length into a number 593of significant bits; currently an alias for \kbd{prec2nbits}. 594 595\fun{double}{bit_accuracy_mul}{long x, double y} returns 596\kbd{bit\_accuracy}$(x)\times y$. 597 598\fun{long}{realprec}{GEN x} length of a \typ{REAL} in words; currently an alias 599for \kbd{lg}. 600 601\fun{long}{bit_prec}{GEN x} length of a \typ{REAL} in bits. 602 603\fun{long}{precdbl}{long prec} given a length in words corresponding to a 604\typ{REAL} precision, return the length corresponding to doubling the 605precision. Due to the presence of 2 code words, this is 606 $2(\kbd{prec} - 2) + 2$. 607 608\subsec{Read type-dependent information} 609 610\fun{long}{typ}{GEN x} returns the type number of~\kbd{x}. The header files 611included through \kbd{pari.h} define symbolic constants for the \kbd{GEN} 612types: \typ{INT} etc. Never use their actual numerical values. E.g to determine 613whether \kbd{x} is a \typ{INT}, simply check 614\bprog 615 if (typ(x) == t_INT) { } 616@eprog\noindent 617The types are internally ordered and this simplifies the implementation of 618commutative binary operations (e.g addition, gcd). Avoid using the ordering 619directly, as it may change in the future; use type grouping functions 620instead (\secref{se:typegroup}). 621 622\fun{const char*}{type_name}{long t} given a type number \kbd{t} this routine 623returns a string containing its symbolic name. E.g \kbd{type\_name(\typ{INT})} 624returns \kbd{"\typ{INT}"}. The return value is read-only. 625 626\fun{long}{lg}{GEN x} returns the length of~\kbd{x} in \B-bit words. 627 628\fun{long}{lgefint}{GEN x} returns the effective length of the \typ{INT} 629\kbd{x} in \B-bit words. 630 631\fun{long}{signe}{GEN x} returns the sign ($-1$, 0 or 1) of~\kbd{x}. Can be 632used for \typ{INT}, \typ{REAL}, \typ{POL} and \typ{SER} (for the last two 633types, only 0 or 1 are possible). 634 635\fun{long}{gsigne}{GEN x} returns the sign of a real number $x$, 636valid for \typ{INT}, \typ{REAL} as \kbd{signe}, but also for \typ{FRAC} 637and \typ{QUAD} of positive discriminants. Raise a type error if \kbd{typ(x)} 638is not among those. 639 640\fun{long}{expi}{GEN x} returns the binary exponent of the real number equal 641to the \typ{INT}~\kbd{x}. This is a special case of \kbd{gexpo}. 642 643\fun{long}{expo}{GEN x} returns the binary exponent of the 644\typ{REAL}~\kbd{x}. 645 646\fun{long}{mpexpo}{GEN x} returns the binary exponent of the \typ{INT} 647or \typ{REAL}~\kbd{x}. 648 649\fun{long}{gexpo}{GEN x} same as \kbd{expo}, but also valid when \kbd{x} 650is not a \typ{REAL} (returns the largest exponent found among the components 651of \kbd{x}). When \kbd{x} is an exact~0, this returns 652\hbox{\kbd{-HIGHEXPOBIT}}, which is lower than any valid exponent. 653 654\fun{long}{gexpo_safe}{GEN x} same as \kbd{gexpo}, but returns a value 655strictly less than \hbox{\kbd{-HIGHEXPOBIT}} when the exponent is not defined 656(e.g. for a \typ{PADIC} or \typ{INTMOD} component). 657 658\fun{long}{valp}{GEN x} returns the $p$-adic valuation (for 659a \typ{PADIC}) or $X$-adic valuation (for a \typ{SER}, taken with respect to 660the main variable) of~\kbd{x}. 661 662\fun{long}{precp}{GEN x} returns the precision of the \typ{PADIC}~\kbd{x}. 663 664\fun{long}{varn}{GEN x} returns the variable number of the 665\typ{POL} or \typ{SER}~\kbd{x} (between 0 and \kbd{MAXVARN}). 666 667\fun{long}{gvar}{GEN x} returns the main variable number when any variable 668at all occurs in the composite object~\kbd{x} (the smallest variable number 669which occurs), and \tet{NO_VARIABLE} otherwise. 670 671\fun{long}{gvar2}{GEN x} returns the variable number for the ring over which 672$x$ is defined, e.g. if $x\in \Z[a][b]$ return (the variable number for) 673$a$. Return \tet{NO_VARIABLE} if $x$ has no variable or is not defined over a 674polynomial ring. 675 676\fun{long}{degpol}{GEN x} is a simple macro returning \kbd{lg(x) - 3}. 677This is the degree of the \typ{POL}~\kbd{x} with respect to its main 678variable, \emph{if} its leading coefficient is nonzero (a rational $0$ is 679impossible, but an inexact $0$ is allowed, as well as an exact modular $0$, 680e.g. \kbd{Mod(0,2)}). If $x$ has no coefficients (rational $0$ polynomial), 681its length is $2$ and we return the expected $-1$. 682 683\fun{long}{lgpol}{GEN x} is equal to \kbd{degpol(x) + 1}. Used to loop over 684the coefficients of a \typ{POL} in the following situation: 685\bprog 686 GEN xd = x + 2; 687 long i, l = lgpol(x); 688 for (i = 0; i < l; i++) foo( xd[i] ). 689@eprog 690 691\fun{long}{precision}{GEN x} If \kbd{x} is of type \typ{REAL}, returns the 692precision of~\kbd{x}, namely the length of \kbd{x} in \B-bit words if \kbd{x} 693is not zero, and a reasonable quantity obtained from the exponent of \kbd{x} 694if \kbd{x} is numerically equal to zero. If \kbd{x} is of type 695\typ{COMPLEX}, returns the minimum of the precisions of the real and 696imaginary part. Otherwise, returns~0 (which stands for infinite precision). 697 698\fun{long}{lgcols}{GEN x} is equal to \kbd{lg(gel(x,1))}. This is the length 699of the columns of a \typ{MAT} with at least one column. 700 701\fun{long}{nbrows}{GEN x} is equal to \kbd{lg(gel(x,1))-1}. This is the number 702of rows of a \typ{MAT} with at least one column. 703 704\fun{long}{gprecision}{GEN x} as \kbd{precision} for scalars. Returns the 705lowest precision encountered among the components otherwise. 706 707\fun{long}{sizedigit}{GEN x} returns 0 if \kbd{x} is exactly~0. Otherwise, 708returns \kbd{\key{gexpo}(x)} multiplied by $\log_{10}(2)$. This gives a crude 709estimate for the maximal number of decimal digits of the components 710of~\kbd{x}. 711 712\subsec{Eval type-dependent information} 713These routines convert type-dependent information to bitmask to fill the 714codewords of \kbd{GEN} objects (see \secref{se:impl}). E.g for a 715\typ{REAL}~\kbd{z}: 716\bprog 717 z[1] = evalsigne(-1) | evalexpo(2) 718@eprog 719Compatible components of a codeword for a given type can be OR-ed as above. 720 721\fun{ulong}{evaltyp}{long x} convert type~\kbd{x} to bitmask (first 722codeword of all \kbd{GEN}s) 723 724\fun{long}{evallg}{long x} convert length~\kbd{x} to bitmask (first 725codeword of all \kbd{GEN}s). Raise overflow error if \kbd{x} is so large that 726the corresponding length cannot be represented 727 728\fun{long}{_evallg}{long x} as \kbd{evallg} \emph{without} the overflow 729check. 730 731\fun{ulong}{evalvarn}{long x} convert variable number~\kbd{x} to bitmask 732(second codeword of \typ{POL} and \typ{SER}) 733 734\fun{long}{evalsigne}{long x} convert sign~\kbd{x} (in $-1,0,1$) to bitmask 735(second codeword of \typ{INT}, \typ{REAL}, \typ{POL}, \typ{SER}) 736 737\fun{long}{evalprecp}{long x} convert $p$-adic ($X$-adic) precision~\kbd{x} 738to bitmask (second codeword of \typ{PADIC}, \typ{SER}). Raise overflow error 739if \kbd{x} is so large that the corresponding precision cannot be 740represented. 741 742\fun{long}{_evalprecp}{long x} same as \kbd{evalprecp} \emph{without} the 743overflow check. 744 745\fun{long}{evalvalp}{long x} convert $p$-adic ($X$-adic) valuation~\kbd{x} to 746bitmask (second codeword of \typ{PADIC}, \typ{SER}). Raise overflow error if 747\kbd{x} is so large that the corresponding valuation cannot be represented. 748 749\fun{long}{_evalvalp}{long x} same as \kbd{evalvalp} \emph{without} the 750overflow check. 751 752\fun{long}{evalexpo}{long x} convert exponent~\kbd{x} to bitmask (second 753codeword of \typ{REAL}). Raise overflow error if \kbd{x} is so 754large that the corresponding exponent cannot be represented 755 756\fun{long}{_evalexpo}{long x} same as \kbd{evalexpo} \emph{without} the 757overflow check. 758 759\fun{long}{evallgefint}{long x} convert effective length~\kbd{x} to bitmask 760(second codeword \typ{INT}). This should be less or equal than the length 761of the \typ{INT}, hence there is no overflow check for the effective length. 762 763\subsec{Set type-dependent information} 764Use these functions and macros with extreme care since usually the 765corresponding information is set otherwise, and the components and further 766codeword fields (which are left unchanged) may not be compatible with the new 767information. 768 769\fun{void}{settyp}{GEN x, long s} sets the type number of~\kbd{x} to~\kbd{s}. 770 771\fun{void}{setlg}{GEN x, long s} sets the length of~\kbd{x} to~\kbd{s}. This 772is an efficient way of truncating vectors, matrices or polynomials. 773 774\fun{void}{setlgefint}{GEN x, long s} sets the effective length 775of the \typ{INT} \kbd{x} to~\kbd{s}. The number \kbd{s} must be less than or 776equal to the length of~\kbd{x}. 777 778\fun{void}{setsigne}{GEN x, long s} sets the sign of~\kbd{x} to~\kbd{s}. 779If \kbd{x} is a \typ{INT} or \typ{REAL}, \kbd{s} must be equal to $-1$, 0 780or~1, and if \kbd{x} is a \typ{POL} or \typ{SER}, \kbd{s} must be equal to 0 781or~1. No sanity check is made; in particular, setting the sign of a 782$0$ \typ{INT} to $\pm1$ creates an invalid object. 783 784\fun{void}{togglesign}{GEN x} sets the sign $s$ of~\kbd{x} to $-s$, in place. 785 786\fun{void}{togglesign_safe}{GEN *x} sets the $s$ sign of~\kbd{*x} to $-s$, in 787place, unless \kbd{*x} is one of the integer universal constants in which case 788replace \kbd{*x} by its negation (e.g.~replace \kbd{gen\_1} by \kbd{gen\_m1}). 789 790\fun{void}{setabssign}{GEN x} sets the sign $s$ of~\kbd{x} to $|s|$, in place. 791 792\fun{void}{affectsign}{GEN x, GEN y} shortcut for \kbd{setsigne(y, signe(x))}. 793No sanity check is made; in particular, setting the sign of a 794$0$ \typ{INT} to $\pm1$ creates an invalid object. 795 796\fun{void}{affectsign_safe}{GEN x, GEN *y} sets the sign of~\kbd{*y} to that 797of~\kbd{x}, in place, unless \kbd{*y} is one of the integer universal 798constants in which case replace \kbd{*y} by its negation if needed 799(e.g.~replace \kbd{gen\_1} by \kbd{gen\_m1} if \kbd{x} is negative). No other 800sanity check is made; in particular, setting the sign of a $0$ 801\typ{INT} to $\pm1$ creates an invalid object. 802 803\fun{void}{normalize_frac}{GEN z} assuming $z$ is of the form \kbd{mkfrac(a,b)} 804with $b\neq 0$, make sure that $b > 0$ by changing the sign of $a$ in place if 805needed (use \kbd{togglesign}). 806 807\fun{void}{setexpo}{GEN x, long s} sets the binary exponent of the 808\typ{REAL}~\kbd{x} to \kbd{s}. The value \kbd{s} must be a 24-bit signed 809number. 810 811\fun{void}{setvalp}{GEN x, long s} sets the $p$-adic or $X$-adic valuation 812of~\kbd{x} to~\kbd{s}, if \kbd{x} is a \typ{PADIC} or a \typ{SER}, 813respectively. 814 815\fun{void}{setprecp}{GEN x, long s} sets the $p$-adic precision of the 816\typ{PADIC}~\kbd{x} to~\kbd{s}. 817 818\fun{void}{setvarn}{GEN x, long s} sets the variable number of the \typ{POL} 819or \typ{SER}~\kbd{x} to~\kbd{s} (where $0\le \kbd{s}\le\kbd{MAXVARN}$). 820 821\subsec{Type groups}\label{se:typegroup} 822In the following functions, \kbd{t} denotes the type of a \kbd{GEN}. 823They used to be implemented as macros, which could evaluate their argument 824twice; \emph{no longer}: it is not inefficient to write 825\bprog 826 is_intreal_t(typ(x)) 827@eprog 828 829\fun{int}{is_recursive_t}{long t} \kbd{true} iff \kbd{t} is a recursive 830type (the nonrecursive types are \typ{INT}, \typ{REAL}, 831\typ{STR}, \typ{VECSMALL}). Somewhat contrary to intuition, \typ{LIST} is 832also nonrecursive, ; see the Developer's guide for details. 833 834\fun{int}{is_intreal_t}{long t} \kbd{true} iff \kbd{t} is \typ{INT} 835or \typ{REAL}. 836 837\fun{int}{is_rational_t}{long t} \kbd{true} iff \kbd{t} is \typ{INT} 838or \typ{FRAC}. 839 840\fun{int}{is_real_t}{long t} \kbd{true} iff \kbd{t} is \typ{INT} 841or \typ{REAL} or \typ{FRAC}. 842 843\fun{int}{is_qfb_t}{long t} \kbd{true} iff \kbd{t} is \typ{QFI} 844or \typ{QFR}. 845 846\fun{int}{is_vec_t}{long t} \kbd{true} iff \kbd{t} is \typ{VEC} 847or \typ{COL}. 848 849\fun{int}{is_matvec_t}{long t} \kbd{true} iff \kbd{t} is \typ{MAT}, \typ{VEC} 850or \typ{COL}. 851 852\fun{int}{is_scalar_t}{long t} \kbd{true} iff \kbd{t} is a scalar, i.e 853a \typ{INT}, 854a \typ{REAL}, 855a \typ{INTMOD}, 856a \typ{FRAC}, 857a \typ{COMPLEX}, 858a \typ{PADIC}, 859a \typ{QUAD}, 860or 861a \typ{POLMOD}. 862 863\fun{int}{is_extscalar_t}{long t} \kbd{true} iff \kbd{t} is a scalar (see 864\kbd{is\_scalar\_t}) or \kbd{t} is \typ{POL}. 865 866\fun{int}{is_const_t}{long t} \kbd{true} iff \kbd{t} is a scalar which is not 867\typ{POLMOD}. 868 869\fun{int}{is_noncalc_t}{long t} true if generic operations (\kbd{gadd}, 870\kbd{gmul}) do not make sense for $t$: corresponds to types 871\typ{LIST}, \typ{STR}, \typ{VECSMALL}, \typ{CLOSURE} 872 873\subsec{Accessors and components}\label{se:accessors} 874The first two functions return \kbd{GEN} components as copies on the stack: 875 876\fun{GEN}{compo}{GEN x, long n} creates a copy of the \kbd{n}-th true 877component (i.e.\ not counting the codewords) of the object~\kbd{x}. 878 879\fun{GEN}{truecoeff}{GEN x, long n} creates a copy of the coefficient of 880degree~\kbd{n} of~\kbd{x} if \kbd{x} is a scalar, \typ{POL} or \typ{SER}, 881and otherwise of the \kbd{n}-th component of~\kbd{x}. 882\smallskip 883 884\noindent On the contrary, the following routines return the address of a 885\kbd{GEN} component. No copy is made on the stack: 886 887\fun{GEN}{constant_coeff}{GEN x} returns the address of the constant 888coefficient of \typ{POL}~\kbd{x}. By convention, a $0$ polynomial (whose 889\kbd{sign} is $0$) has \kbd{gen\_0} constant term. 890 891\fun{GEN}{leading_coeff}{GEN x} returns the address of the leading coefficient 892of \typ{POL}~\kbd{x}, i.e. the coefficient of largest index stored in the 893array representing $x$. This may be an inexact $0$. By convention, return 894\kbd{gen\_0} if the coefficient array is empty. 895 896\fun{GEN}{gel}{GEN x, long i} returns the address of the 897\kbd{x[i]} entry of~\kbd{x}. (\kbd{el} stands for element.) 898 899\fun{GEN}{gcoeff}{GEN x, long i, long j} returns the address of the 900\kbd{x[i,j]} entry of \typ{MAT}~\kbd{x}, i.e.~the coefficient at row~\kbd{i} 901and column~\kbd{j}. 902 903\fun{GEN}{gmael}{GEN x, long i, long j} returns the address of the 904\kbd{x[i][j]} entry of~\kbd{x}. (\kbd{mael} stands for multidimensional array 905element.) 906 907\fun{GEN}{gmael2}{GEN A, long x1, long x2} is an alias for \kbd{gmael}. 908Similar macros \tet{gmael3}, \tet{gmael4}, \tet{gmael5} are available. 909 910\section{Global numerical constants} 911These are defined in the various public PARI headers. 912 913\subsec{Constants related to word size} 914 915\noindent \kbd{long} $\tet{BITS_IN_LONG} = 2^{\tet{TWOPOTBITS_IN_LONG}}$: 916number of bits in a \kbd{long} (32 or 64). 917 918\noindent \kbd{long} \tet{BITS_IN_HALFULONG}: \kbd{BITS\_IN\_LONG} divided by 919$2$. 920 921\noindent \kbd{long} \tet{LONG_MAX}: the largest positive \kbd{long}. 922 923\noindent \kbd{ulong} \tet{ULONG_MAX}: the largest \kbd{ulong}. 924 925\noindent \kbd{long} \tet{DEFAULTPREC}: the length (\kbd{lg}) of a 926\typ{REAL} with 64 bits of accuracy 927 928\noindent \kbd{long} \tet{MEDDEFAULTPREC}: the length (\kbd{lg}) of a 929\typ{REAL} with 128 bits of accuracy 930 931\noindent \kbd{long} \tet{BIGDEFAULTPREC}: the length (\kbd{lg}) of a 932\typ{REAL} with 192 bits of accuracy 933 934\noindent \kbd{ulong} \tet{HIGHBIT}: the largest power of $2$ fitting in an 935\kbd{ulong}. 936 937\noindent \kbd{ulong} \tet{LOWMASK}: bitmask yielding the least significant 938bits. 939 940\noindent \kbd{ulong} \tet{HIGHMASK}: bitmask yielding the most significant 941bits. 942 943\noindent The last two are used to implement the following convenience macros, 944returning half the bits of their operand: 945 946\fun{ulong}{LOWWORD}{ulong a} returns least significant bits. 947 948\fun{ulong}{HIGHWORD}{ulong a} returns most significant bits. 949 950\noindent Finally 951 952\fun{long}{divsBIL}{long n} returns the Euclidean quotient of $n$ by 953\kbd{BITS\_IN\_LONG} (with nonnegative remainder). 954 955\fun{long}{remsBIL}{n} returns the (nonnegative) Euclidean remainder of $n$ 956by \kbd{BITS\_IN\_LONG} 957 958\fun{long}{dvmdsBIL}{long n, long *r} 959 960\fun{ulong}{dvmduBIL}{ulong n, ulong *r} sets $r$ to \kbd{remsBIL(n)} 961and returns \kbd{divsBIL(n)}. 962 963\subsec{Masks used to implement the \kbd{GEN} type} 964 965These constants are used by higher level macros, like \kbd{typ} or \kbd{lg}: 966 967\noindent \tet{EXPOnumBITS}, 968\tet{LGnumBITS}, 969\tet{SIGNnumBITS}, 970\tet{TYPnumBITS}, 971\tet{VALPnumBITS}, 972\tet{VARNnumBITS}: 973number of bits used to encode \kbd{expo}, \kbd{lg}, \kbd{signe}, 974\kbd{typ}, \kbd{valp}, \kbd{varn}. 975 976\noindent \tet{PRECPSHIFT}, 977\tet{SIGNSHIFT}, 978\tet{TYPSHIFT}, 979\tet{VARNSHIFT}: shifts used to recover or encode \kbd{precp}, \kbd{varn}, 980\kbd{typ}, \kbd{signe} 981 982\noindent \tet{CLONEBIT}, 983\tet{EXPOBITS}, 984\tet{LGBITS}, 985\tet{PRECPBITS}, 986\tet{SIGNBITS}, 987\tet{TYPBITS}, 988\tet{VALPBITS}, 989\tet{VARNBITS}: bitmasks used to extract \kbd{isclone}, \kbd{expo}, \kbd{lg}, 990\kbd{precp}, \kbd{signe}, \kbd{typ}, \kbd{valp}, \kbd{varn} from \kbd{GEN} 991codewords. 992 993\noindent \tet{MAXVARN}: the largest possible variable number. 994 995\noindent \tet{NO_VARIABLE}: sentinel returned by \kbd{gvar(x)} when \kbd{x} 996does not contain any polynomial; has a lower priority than any valid variable 997number. 998 999\noindent \tet{HIGHEXPOBIT}: a power of $2$, one more that the largest possible 1000exponent for a \typ{REAL}. 1001 1002\noindent \tet{HIGHVALPBIT}: a power of $2$, one more that the largest possible 1003valuation for a \typ{PADIC} or a \typ{SER}. 1004 1005\subsec{$\log 2$, $\pi$} 1006 1007These are \kbd{double} approximations to useful constants: 1008 1009\noindent \tet{M_PI}: $\pi$. 1010 1011\noindent \tet{M_LN2}: $\log 2$. 1012 1013\noindent \tet{LOG10_2}: $\log 2 / \log 10$. 1014 1015\noindent \tet{LOG2_10}: $\log 10 / \log 2$. 1016 1017\section{Iterating over small primes, low-level interface} 1018\label{se:primetable} 1019 1020One of the methods used by the high-level prime iterator (see 1021\secref{se:primeiter}), is a precomputed table. Its direct use is deprecated, 1022but documented here. 1023 1024After \kbd{pari\_init(size, maxprime)}, a ``prime table'' is 1025initialized with the successive \emph{differences} of primes up to (possibly 1026just a little beyond) \kbd{maxprime}. The prime table occupies roughly 1027$\kbd{maxprime}/\log(\kbd{maxprime})$ bytes in memory, so be sensible when 1028choosing \kbd{maxprime}; it is $500000$ by default under \kbd{gp} and there 1029is no real benefit in choosing a much larger value: the high-level 1030iterator provide \emph{fast} access to primes up to the \emph{square} 1031of \kbd{maxprime}. In any case, the implementation requires that 1032$\tet{maxprime} < 2^{\B} - 2048$, whatever memory is available. 1033 1034PARI currently guarantees that the first 6547 primes, up to and including 103565557, are present in the table, even if you set \kbd{maxprime} to zero. 1036in the \kbd{pari\_init} call. 1037 1038\noindent Some convenience functions: 1039 1040\fun{ulong}{maxprime}{} the largest prime computable using our prime table. 1041 1042\fun{ulong}{maxprimeN}{} the index $N$ of the largest prime computable using 1043the prime table. I.e., $p_N = \kbd{maxprime()}$. 1044 1045\fun{void}{maxprime_check}{ulong B} raise an error if \kbd{maxprime()} is $< B$. 1046 1047After the following initializations (the names $p$ and \var{ptr} are 1048arbitrary of course) 1049\bprog 1050byteptr ptr = diffptr; 1051ulong p = 0; 1052@eprog 1053\noindent calling the macro \tet{NEXT_PRIME_VIADIFF_CHECK}$(p, \var{ptr})$ 1054repeatedly will assign the successive prime numbers to $p$. Overrunning the 1055prime table boundary will raise the error \tet{e_MAXPRIME}, which just 1056prints the error message: 1057 1058\kbd{*** not enough precomputed primes, need primelimit \til $c$} 1059 1060\noindent (for some numerical value $c$), then the macro aborts the 1061computation. The alternative macro \tet{NEXT_PRIME_VIADIFF} operates in the 1062same way, but will omit that check, and is slightly faster. It should be used 1063in the following way: 1064% 1065\bprog 1066byteptr ptr = diffptr; 1067ulong p = 0; 1068 1069if (maxprime() < goal) pari_err_MAXPRIME(goal); /*@Ccom not enough primes */ 1070while (p <= goal) /*@Ccom run through all primes up to \kbd{goal} */ 1071{ 1072 NEXT_PRIME_VIADIFF(p, ptr); 1073 ... 1074} 1075@eprog\noindent 1076Here, we use the general error handling function \kbd{pari\_err} (see 1077\secref{se:err}), with the codeword \kbd{e\_MAXPRIME}, raising the ``not enough 1078primes'' error. This could be rewritten as 1079\bprog 1080maxprime_check(goal); 1081while (p <= goal) /*@Ccom run through all primes up to \kbd{goal} */ 1082{ 1083 NEXT_PRIME_VIADIFF(p, ptr); 1084 ... 1085} 1086@eprog 1087 1088\fun{bytepr}{initprimes}{ulong maxprime, long *L, ulong *lastp} 1089computes a (malloc'ed) ``prime table'', in fact a table of all prime 1090differences for $p < \kbd{maxprime}$ (and possibly a little beyond). Set $L$ 1091to the table length (argument to \kbd{malloc}), and \var{lastp} to the last 1092prime in the table. 1093 1094\fun{void}{initprimetable}{ulong maxprime} computes a prime table (of all prime 1095differences for $p < \kbd{maxprime}$) and assign it to the global variable 1096\kbd{diffptr}. Don't change \kbd{diffptr} directly, call this function 1097instead. This calls \kbd{initprimes} and updates internal data recording the 1098table size. 1099 1100\fun{ulong}{init_primepointer_geq}{ulong a, byteptr *pd} 1101returns the smallest prime $p \geq a$, and sets \kbd{*pd} to the proper offset 1102of \kbd{diffptr} so that \kbd{NEXT\_PRIME\_VIADIFF(p, *pd)} correctly 1103returns \kbd{unextprime(p + 1)}. 1104 1105\fun{ulong}{init_primepointer_gt}{ulong a, byteptr *pd} returns the smallest 1106prime $p > a$. 1107 1108\fun{ulong}{init_primepointer_leq}{ulong a, byteptr *pd} returns the largest 1109prime $p \leq a$. 1110 1111\fun{ulong}{init_primepointer_lt}{ulong a, byteptr *pd} returns the largest 1112prime $p < a$. 1113 1114\section{Handling the PARI stack} 1115 1116\subsec{Allocating memory on the stack} 1117 1118\fun{GEN}{cgetg}{long n, long t} allocates memory on the stack for 1119an object of length \kbd{n} and type~\kbd{t}, and initializes its first 1120codeword. 1121 1122\fun{GEN}{cgeti}{long n} allocates memory on the stack for a \typ{INT} 1123of length~\kbd{n}, and initializes its first codeword. Identical to 1124\kbd{cgetg(n,\typ{INT})}. 1125 1126\fun{GEN}{cgetr}{long n} allocates memory on the stack for a \typ{REAL} 1127of length~\kbd{n}, and initializes its first codeword. Identical to 1128\kbd{cgetg(n,\typ{REAL})}. 1129 1130\fun{GEN}{cgetc}{long n} allocates memory on the stack for a 1131\typ{COMPLEX}, whose real and imaginary parts are \typ{REAL}s 1132of length~\kbd{n}. 1133 1134\fun{GEN}{cgetp}{GEN x} creates space sufficient to hold the 1135\typ{PADIC}~\kbd{x}, and sets the prime $p$ and the $p$-adic precision to 1136those of~\kbd{x}, but does not copy (the $p$-adic unit or zero representative 1137and the modulus of)~\kbd{x}. 1138 1139\fun{GEN}{new_chunk}{size_t n} allocates a \kbd{GEN} with $n$ components, 1140\emph{without} filling the required code words. This is the low-level 1141constructor underlying \kbd{cgetg}, which calls \kbd{new\_chunk} then sets 1142the first code word. It works by simply returning the address 1143\kbd{((GEN)avma) - n}, after checking that it is larger than \kbd{(GEN)bot}. 1144 1145\fun{void}{new_chunk_resize}{size_t x} this function is called by 1146\kbd{new\_chunk} when the PARI stack overflows. There is no need to call it 1147manually. It will either extend the stack or report an \kbd{e\_STACK} error. 1148 1149\fun{char*}{stack_malloc}{size_t n} allocates memory on the stack for $n$ 1150chars (\emph{not} $n$ \kbd{GEN}s). This is faster than using \kbd{malloc}, 1151and easier to use in most situations when temporary storage is needed. In 1152particular there is no need to \kbd{free} individually all variables thus 1153allocated: a simple \kbd{set\_avma(oldavma)} might be enough. On the other hand, 1154beware that this is not permanent independent storage, but part of the stack. 1155The memory is aligned on \kbd{sizeof(long)} bytes boundaries. 1156 1157\fun{char*}{stack_malloc_align}{size_t n, long k} as \kbd{stack\_malloc}, 1158but the memory is aligned on \kbd{k} bytes boundaries. The number\kbd{k} must 1159be a multiple of the \kbd{sizeof(long)}. 1160 1161\fun{char*}{stack_calloc}{size_t n} as \kbd{stack\_malloc}, setting the memory 1162to zero. 1163 1164\fun{char*}{stack_calloc_align}{size_t n, long k} as 1165\kbd{stack\_malloc\_align}, setting the memory to zero. 1166 1167\noindent Objects allocated through these last three functions cannot be 1168\kbd{gerepile}'d, since they are not yet valid \kbd{GEN}s: their codewords 1169must be filled first. 1170 1171\fun{GEN}{cgetalloc}{long t, size_t l}, same as \kbd{cgetg(t, l)}, except 1172that the result is allocated using \tet{pari_malloc} instead of the PARI 1173stack. The resulting \kbd{GEN} is now impervious to garbage collecting 1174routines, but should be freed using \tet{pari_free}. 1175 1176\subsec{Stack-independent binary objects} 1177 1178\fun{GENbin*}{copy_bin}{GEN x} copies $x$ into a malloc'ed structure suitable 1179for stack-independent binary transmission or storage. The object obtained 1180is architecture independent provided, \kbd{sizeof(long)} remains the same 1181on all PARI instances involved, as well as the multiprecision kernel (either 1182native or GMP). 1183 1184\fun{GENbin*}{copy_bin_canon}{GEN x} as \kbd{copy\_bin}, ensuring furthermore 1185that the binary object is independent of the multiprecision kernel. Slower 1186than \kbd{copy\_bin}. 1187 1188\fun{GEN}{bin_copy}{GENbin *p} assuming $p$ was created by \kbd{copy\_bin(x)} 1189(not necessarily by the same PARI instance: transmission or external storage 1190may be involved), restores $x$ on the PARI stack. 1191 1192\noindent The routine \kbd{bin\_copy} transparently encapsulate the following 1193functions: 1194 1195\fun{GEN}{GENbinbase}{GENbin *p} the \kbd{GEN} data actually stored in $p$. 1196All addresses are stored as offsets with respect to a common reference point, 1197so the resulting \kbd{GEN} is unusable unless it is a nonrecursive type; 1198private low-level routines must be called first to restore absolute addresses. 1199 1200\fun{void}{shiftaddress}{GEN x, long dec} converts relative addresses to 1201absolute ones. 1202 1203\fun{void}{shiftaddress_canon}{GEN x, long dec} converts relative addresses to 1204absolute ones, and converts leaves from a canonical form to the one 1205specific to the multiprecision kernel in use. The \kbd{GENbin} type stores 1206whether leaves are stored in canonical form, so \kbd{bin\_copy} can call 1207the right variant. 1208 1209\noindent Objects containing closures are harder to e.g. copy and save to disk, 1210since closures contain pointers to libpari functions that will not be valid in 1211another gp instance: there is little chance for them to be loaded at the exact 1212same address in memory. Such objects must be saved along with a linking table. 1213 1214\fun{GEN}{copybin_unlink}{GEN C} returns a linking table allowing to safely 1215store and transmit \typ{CLOSURE} objects in $C$. If $C = \kbd{NULL}$ return a 1216linking table corresponding to the content of all gp variables. $C$ may then be 1217dumped to disk in binary form, for instance. 1218 1219\fun{void}{bincopy_relink}{GEN C, GEN V} given a binary object $C$, as dumped 1220by writebin and read back into a session, and a linking table $V$, restore all 1221closures contained in $C$ (function pointers are translated to their current 1222value). 1223 1224\subsec{Garbage collection} 1225See \secref{se:garbage} for a detailed explanation and many examples. 1226 1227\fun{void}{set_avma}{ulong av} reset \kbd{avma} to \kbd{av}. 1228 1229\fun{GEN}{gc_NULL}{pari_sp av} reset \kbd{avma} to \kbd{av} and return 1230\kbd{NULL}. 1231 1232The following 6 functions reset \kbd{avma} to \kbd{av} and return $x$: 1233 1234\fun{int}{gc_bool}{pari_sp av, int x} 1235 1236\fun{double}{gc_double}{pari_sp av, double x} 1237 1238\fun{int}{gc_int}{pari_sp av, int x} 1239 1240\fun{long}{gc_long}{pari_sp av, long x} 1241 1242\fun{ulong}{gc_ulong}{pari_sp av, ulong x} This allows for instance 1243to return \kbd{gc\_ulong(av, itou(z))}, whereas 1244\bprog 1245 pari_sp av = avma; 1246 GEN z = ... 1247 set_avma(av); 1248 return itou(z); 1249@eprog should be frowned upon since \kbd{set\_avma(av)} conceptually 1250destroys everything from the reference point on, including $z$. 1251 1252\fun{long}{gc_const}{pari_sp av, GEN x} assumes that $x$ is either not on the 1253stack (clone, universal constant such as \kbd{gen\_0}) or was defined 1254before \kbd{av}. 1255 1256\fun{void}{cgiv}{GEN x} frees object \kbd{x}, assuming it is the last created 1257on the stack. 1258 1259\fun{GEN}{gerepile}{pari_sp p, pari_sp q, GEN x} general garbage collector 1260for the stack. 1261 1262\fun{void}{gerepileall}{pari_sp av, int n, ...} cleans up the stack from 1263\kbd{av} on (i.e from \kbd{avma} to \kbd{av}), preserving the \kbd{n} objects 1264which follow in the argument list (of type \kbd{GEN*}). For instance, 1265\kbd{gerepileall(av, 2, \&x, \&y)} preserves \kbd{x} and \kbd{y}. 1266 1267\fun{void}{gerepileallsp}{pari_sp av, pari_sp ltop, int n, ...} 1268cleans up the stack between \kbd{av} and \kbd{ltop}, updating 1269the \kbd{n} elements which follow \kbd{n} in the argument list (of type 1270\kbd{GEN*}). Check that the elements of \kbd{g} have no component between 1271\kbd{av} and \kbd{ltop}, and assumes that no garbage is present between 1272\kbd{avma} and \kbd{ltop}. Analogous to (but faster than) \kbd{gerepileall} 1273otherwise. 1274 1275\fun{GEN}{gerepilecopy}{pari_sp av, GEN x} cleans up the stack from 1276\kbd{av} on, preserving the object \kbd{x}. Special case of \kbd{gerepileall} 1277(case $\kbd{n} = 1$), except that the routine returns the preserved \kbd{GEN} 1278instead of updating its address through a pointer. 1279 1280\fun{void}{gerepilemany}{pari_sp av, GEN* g[], int n} alternative interface 1281to \kbd{gerepileall}. The preserved \kbd{GEN}s are the elements of the array 1282\kbd{g} of length $n$: \kbd{g[0]}, \kbd{g[1]}, \dots, 1283\kbd{g[$n$-1]}. Obsolete: no more efficient than \kbd{gerepileall}, 1284error-prone, and clumsy (need to declare an extra \kbd{GEN *g}). 1285 1286\fun{void}{gerepilemanysp}{pari_sp av, pari_sp ltop, GEN* g[], int n} 1287alternative interface to \kbd{gerepileallsp}. Obsolete. 1288 1289\fun{void}{gerepilecoeffs}{pari_sp av, GEN x, int n} cleans up the stack 1290from \kbd{av} on, preserving \kbd{x[0]}, \dots, \kbd{x[n-1]} (which are 1291\kbd{GEN}s). 1292 1293\fun{void}{gerepilecoeffssp}{pari_sp av, pari_sp ltop, GEN x, int n} 1294cleans up the stack from \kbd{av} to \kbd{ltop}, preserving \kbd{x[0]}, 1295\dots, \kbd{x[n-1]} (which are \kbd{GEN}s). Same assumptions as in 1296\kbd{gerepilemanysp}, of which this is a variant. For instance 1297\bprog 1298 z = cgetg(3, t_COMPLEX); 1299 av = avma; garbage(); ltop = avma; 1300 z[1] = fun1(); 1301 z[2] = fun2(); 1302 gerepilecoeffssp(av, ltop, z + 1, 2); 1303 return z; 1304@eprog\noindent 1305cleans up the garbage between \kbd{av} and \kbd{ltop}, and connects \kbd{z} 1306and its two components. This is marginally more efficient than the standard 1307\bprog 1308 av = avma; garbage(); ltop = avma; 1309 z = cgetg(3, t_COMPLEX); 1310 z[1] = fun1(); 1311 z[2] = fun2(); return gerepile(av, ltop, z); 1312@eprog\noindent 1313 1314\fun{GEN}{gerepileupto}{pari_sp av, GEN q} analogous to (but faster than) 1315\kbd{gerepilecopy}. Assumes that \kbd{q} is connected and that its root was 1316created before any component. If \kbd{q} is not on the stack, this is 1317equivalent to \kbd{set\_avma(av)}; in particular, sentinels which are not even 1318proper \kbd{GEN}s such as \kbd{q = NULL} are allowed. 1319 1320\fun{GEN}{gerepileuptoint}{pari_sp av, GEN q} analogous to (but faster than) 1321\kbd{gerepileupto}. Assumes further that \kbd{q} is a \typ{INT}. The 1322length and effective length of the resulting \typ{INT} are equal. 1323 1324\fun{GEN}{gerepileuptoleaf}{pari_sp av, GEN q} analogous to (but faster than) 1325\kbd{gerepileupto}. Assumes further that \kbd{q} is a leaf, i.e a 1326nonrecursive type (\kbd{is\_recursive\_t(typ(q))} is nonzero). Contrary to 1327\kbd{gerepileuptoint} and \kbd{gerepileupto}, \kbd{gerepileuptoleaf} leaves 1328length and effective length of a \typ{INT} unchanged. 1329 1330\subsec{Garbage collection: advanced use} 1331 1332\fun{void}{stackdummy}{pari_sp av, pari_sp ltop} inhibits the memory area 1333between \kbd{av} \emph{included} and \kbd{ltop} \emph{excluded} with respect to 1334\kbd{gerepile}, in order to avoid a call to \kbd{gerepile(av, ltop,...)}. 1335The stack space is not reclaimed though. 1336 1337More precisely, this routine assumes that \kbd{av} is recorded earlier 1338than \kbd{ltop}, then marks the specified stack segment as a 1339nonrecursive type of the correct length. Thus gerepile will not inspect 1340the zone, at most copy it. To be used in the following situation: 1341\bprog 1342 av0 = avma; z = cgetg(t_VEC, 3); 1343 gel(z,1) = HUGE(); av = avma; garbage(); ltop = avma; 1344 gel(z,2) = HUGE(); stackdummy(av, ltop); 1345@eprog\noindent 1346Compared to the orthodox 1347\bprog 1348 gel(z,2) = gerepile(av, ltop, gel(z,2)); 1349@eprog\noindent 1350or even more wasteful 1351\bprog 1352 z = gerepilecopy(av0, z); 1353@eprog\noindent 1354we temporarily lose $(\kbd{av} - \kbd{ltop})$ words but save a costly 1355\kbd{gerepile}. In principle, a garbage collection higher up the call 1356chain should reclaim this later anyway. 1357 1358Without the \kbd{stackdummy}, if the $[\kbd{av}, \kbd{ltop}]$ zone is 1359arbitrary (not even valid \kbd{GEN}s as could happen after direct 1360truncation via \kbd{setlg}), we would leave dangerous data in the middle 1361of~\kbd{z}, which would be a problem for a later 1362\bprog 1363 gerepile(..., ... , z); 1364@eprog\noindent 1365And even if it were made of valid \kbd{GEN}s, inhibiting the area makes sure 1366\kbd{gerepile} will not inspect their components, saving time. 1367 1368Another natural use in low-level routines is to ``shorten'' an existing 1369\kbd{GEN} \kbd{z} to its first $\kbd{n}-1$ components: 1370\bprog 1371 setlg(z, n); 1372 stackdummy((pari_sp)(z + lg(z)), (pari_sp)(z + n)); 1373@eprog\noindent 1374or to its last \kbd{n} components: 1375\bprog 1376 long L = lg(z) - n, tz = typ(z); 1377 stackdummy((pari_sp)(z + L), (pari_sp)z); 1378 z += L; z[0] = evaltyp(tz) | evallg(L); 1379@eprog 1380 1381The first scenario (safe shortening an existing \kbd{GEN}) is in fact so 1382common, that we provide a function for this: 1383 1384\fun{void}{fixlg}{GEN z, long ly} a safe variant of \kbd{setlg(z, ly)}. If 1385\kbd{ly} is larger than \kbd{lg(z)} do nothing. Otherwise, shorten $z$ in 1386place, using \kbd{stackdummy} to avoid later \kbd{gerepile} problems. 1387 1388\fun{GEN}{gcopy_avma}{GEN x, pari_sp *AVMA} return a copy of $x$ as from 1389\kbd{gcopy}, except that we pretend that initially \kbd{avma} is \kbd{*AVMA}, 1390and that \kbd{*AVMA} is updated accordingly (so that the total size of $x$ is 1391the difference between the two successive values of \kbd{*AVMA}). It is not 1392necessary for \kbd{*AVMA} to initially point on the stack: \tet{gclone} is 1393implemented using this mechanism. 1394 1395\fun{GEN}{icopy_avma}{GEN x, pari_sp av} analogous to \kbd{gcopy\_avma} but 1396simpler: assume $x$ is a \typ{INT} and return a copy allocated as if 1397initially we had \kbd{avma} equal to \kbd{av}. There is no need to pass a 1398pointer and update the value of the second argument: the new (fictitious) 1399\kbd{avma} is just the return value (typecast to \kbd{pari\_sp}). 1400 1401\subsec{Debugging the PARI stack} 1402 1403\fun{int}{chk_gerepileupto}{GEN x} returns 1 if \kbd{x} is suitable for 1404\kbd{gerepileupto}, and 0 otherwise. In the latter case, print a warning 1405explaining the problem. 1406 1407\fun{void}{dbg_gerepile}{pari_sp ltop} outputs the list of all objects on the 1408stack between \kbd{avma} and \kbd{ltop}, i.e. the ones that would be inspected 1409in a call to \kbd{gerepile(...,ltop,...)}. 1410 1411\fun{void}{dbg_gerepileupto}{GEN q} outputs the list of all objects on the 1412stack that would be inspected in a call to \kbd{gerepileupto(...,q)}. 1413 1414\subsec{Copies} 1415 1416\fun{GEN}{gcopy}{GEN x} creates a new copy of $x$ on the stack. 1417 1418\fun{GEN}{gcopy_lg}{GEN x, long l} creates a new copy of $x$ 1419on the stack, pretending that \kbd{lg(x)} is $l$, which must be less than or 1420equal to \kbd{lg(x)}. If equal, the function is equivalent to \kbd{gcopy(x)}. 1421 1422\fun{int}{isonstack}{GEN x} \kbd{true} iff $x$ belongs to the stack. 1423 1424\fun{void}{copyifstack}{GEN x, GEN y} sets \kbd{y = gcopy(x)} if 1425$x$ belongs to the stack, and \kbd{y = x} otherwise. This macro evaluates 1426its arguments once, contrary to 1427\bprog 1428 y = isonstack(x)? gcopy(x): x; 1429@eprog 1430 1431\fun{void}{icopyifstack}{GEN x, GEN y} as \kbd{copyifstack} assuming \kbd{x} 1432is a \typ{INT}. 1433 1434\subsec{Simplify} 1435 1436\fun{GEN}{simplify}{GEN x} you should not need that function in library mode. 1437One rather uses: 1438 1439\fun{GEN}{simplify_shallow}{GEN x} shallow, faster, version of \tet{simplify}. 1440 1441\section{The PARI heap} 1442\subsec{Introduction} 1443 1444It is implemented as a doubly-linked list of \kbd{malloc}'ed blocks of 1445memory, equipped with reference counts. Each block has type \kbd{GEN} but need 1446not be a valid \kbd{GEN}: it is a chunk of data preceded by a hidden header 1447(meaning that we allocate $x$ and return $x + \kbd{header size}$). A 1448\tev{clone}, created by \tet{gclone}, is a block which is a valid \kbd{GEN} 1449and whose \emph{clone bit} is set. 1450 1451\subsec{Public interface} 1452 1453\fun{GEN}{newblock}{size_t n} allocates a block of $n$ \emph{words} (not bytes). 1454 1455\fun{void}{killblock}{GEN x} deletes the block~$x$ created by \kbd{newblock}. 1456Fatal error if $x$ not a block. 1457 1458\fun{GEN}{gclone}{GEN x} creates a new permanent copy of $x$ on the heap 1459(allocated using \kbd{newblock}). The \emph{clone bit} of the result is set. 1460 1461\fun{GEN}{gcloneref}{GEN x} if $x$ is not a clone, clone it and return the 1462result; otherwise, increase the clone reference count and return $x$. 1463 1464\fun{void}{gunclone}{GEN x} deletes a clone. Deletion at first only decreases 1465the reference count by $1$. If the count remains positive, no further action is 1466taken; if the count becomes zero, then the clone is actually deleted. In the 1467current implementation, this is an alias for \kbd{killblock}, but it is cleaner 1468to kill clones (valid \kbd{GEN}s) using this function, and other blocks using 1469\kbd{killblock}. 1470 1471\fun{void}{guncloneNULL}{GEN x} same as \kbd{gunclone}, first checking 1472whether $x$ is \kbd{NULL} (and doing nothing in this case). 1473 1474\fun{void}{gunclone_deep}{GEN x} is only useful in the context of the GP 1475interpreter which may replace arbitrary components of container types 1476(\typ{VEC}, \typ{COL}, \typ{MAT}, \typ{LIST}) by clones. If $x$ is such 1477a container, the function recursively deletes all clones among the components 1478of $x$, then unclones $x$. Useless in library mode: simply use 1479\kbd{gunclone}. 1480 1481\fun{void}{guncloneNULL_deep}{GEN x} same as \kbd{gunclone\_deep}, first 1482checking whether $x$ is \kbd{NULL} (and doing nothing in this case). 1483 1484\fun{void}{traverseheap}{void(*f)(GEN, void *), void *data} this applies 1485\kbd{f($x$, data)} to each object $x$ on the PARI heap, most recent 1486first. Mostly for debugging purposes. 1487 1488\fun{GEN}{getheap}{} a simple wrapper around \kbd{traverseheap}. Returns a 1489two-component row vector giving the number of objects on the heap and the 1490amount of memory they occupy in long words. 1491 1492\fun{GEN}{cgetg_block}{long x, long y} as \kbd{cgetg(x,y)}, creating the return 1493value as a \kbd{block}, not on the PARI stack. 1494 1495\fun{GEN}{cgetr_block}{long prec} as \kbd{cgetr(prec)}, creating the return 1496value as a \kbd{block}, not on the PARI stack. 1497 1498\subsec{Implementation note} The hidden block header is manipulated using the 1499following private functions: 1500 1501\fun{void*}{bl_base}{GEN x} returns the pointer that was actually allocated 1502by \kbd{malloc} (can be freed). 1503 1504\fun{long}{bl_refc}{GEN x} the reference count of $x$: the number of pointers 1505to this block. Decremented in \kbd{killblock}, incremented by the private 1506function \fun{void}{gclone_refc}{GEN x}; block is freed when the reference 1507count reaches $0$. 1508 1509\fun{long}{bl_num}{GEN x} the index of this block in the list of all blocks 1510allocated so far (including freed blocks). Uniquely identifies a block until 1511$2^\B$ blocks have been allocated and this wraps around. 1512 1513\fun{GEN}{bl_next}{GEN x} the block \emph{after} $x$ in the linked list of 1514blocks (\kbd{NULL} if $x$ is the last block allocated not yet killed). 1515 1516\fun{GEN}{bl_prev}{GEN x} the block allocated \emph{before} $x$ (never 1517\kbd{NULL}). 1518 1519We documented the last four routines as functions for clarity (and type 1520checking) but they are actually macros yielding valid lvalues. It is allowed 1521to write \kbd{bl\_refc(x)++} for instance. 1522 1523\section{Handling user and temp variables} 1524Low-level implementation of user / temporary variables is liable to change. We 1525describe it nevertheless for completeness. Currently variables are 1526implemented by a single array of values divided in 3 zones: 0--\kbd{nvar} 1527(user variables), \kbd{max\_avail}--\kbd{MAXVARN} (temporary variables), 1528and \kbd{nvar+1}--\kbd{max\_avail-1} (pool of free variable numbers). 1529 1530\subsec{Low-level} 1531 1532\fun{void}{pari_var_init}{}: a small part of \kbd{pari\_init}. Resets 1533variable counters \kbd{nvar} and \kbd{max\_avail}, notwithstanding existing 1534variables! In effect, this even deletes \kbd{x}. Don't use it. 1535 1536\fun{void}{pari_var_close}{void} attached destructor, called by 1537\kbd{pari\_close}. 1538 1539\fun{long}{pari_var_next}{}: returns \kbd{nvar}, the number of the next user 1540variable we can create. 1541 1542\fun{long}{pari_var_next_temp}{} returns \kbd{max\_avail}, the number of the 1543next temp variable we can create. 1544 1545\fun{long}{pari_var_create}{entree *ep} low-level initialization of an 1546\kbd{EpVAR}. Return the attached (new) variable number. 1547 1548\fun{GEN}{vars_sort_inplace}{GEN z} given a \typ{VECSMALL} $z$ of variable 1549numbers, sort $z$ in place according to variable priorities (highest priority 1550comes first). 1551 1552\fun{GEN}{vars_to_RgXV}{GEN h} given a \typ{VECSMALL} $z$ of variable numbers, 1553return the \typ{VEC} of \kbd{pol\_x}$(z[i])$. 1554 1555\subsec{User variables} 1556 1557\fun{long}{fetch_user_var}{char *s} returns a user variable whose name 1558is \kbd{s}, creating it is needed (and using an existing variable otherwise). 1559Returns its variable number. 1560 1561\fun{GEN}{fetch_var_value}{long v} returns a shallow copy of the 1562current value of the variable numbered $v$. Return \kbd{NULL} for a temporary 1563variable. 1564 1565\fun{entree*}{is_entry}{const char *s} returns the \kbd{entree*} attached 1566to an identifier \kbd{s} (variable or function), from the interpreter 1567hashtables. Return \kbd{NULL} is the identifier is unknown. 1568 1569\subsec{Temporary variables} 1570 1571\fun{long}{fetch_var}{void} returns the number of a new temporary variable 1572(decreasing \kbd{max\_avail}). 1573 1574\fun{long}{delete_var}{void} delete latest temp variable created and return 1575the number of previous one. 1576 1577\fun{void}{name_var}{long n, char *s} rename temporary variable number 1578\kbd{n} to \kbd{s}; mostly useful for nicer printout. Error when trying to 1579rename a user variable. 1580 1581\section{Adding functions to PARI} 1582\subsec{Nota Bene} 1583% 1584As mentioned in the \kbd{COPYING} file, modified versions of the PARI package 1585can be distributed under the conditions of the GNU General Public License. If 1586you do modify PARI, however, it is certainly for a good reason, and we 1587would like to know about it, so that everyone can benefit from your changes. 1588There is then a good chance that your improvements are incorporated into the 1589next release. 1590 1591We classify changes to PARI into four rough classes, where changes of the 1592first three types are almost certain to be accepted. The first type includes 1593all improvements to the documentation, in a broad sense. This includes 1594correcting typos or inaccuracies of course, but also items which are not 1595really covered in this document, e.g.~if you happen to write a tutorial, 1596or pieces of code exemplifying fine points unduly omitted in the present 1597manual. 1598 1599The second type is to expand or modify the configuration routines and skeleton 1600files (the \kbd{Configure} script and anything in the \kbd{config/} 1601subdirectory) so that compilation is possible (or easier, or more efficient) 1602on an operating system previously not catered for. This includes discovering 1603and removing idiosyncrasies in the code that would hinder its portability. 1604 1605The third type is to modify existing (mathematical) code, either to correct 1606bugs, to add new functionality to existing functions, or to improve their 1607efficiency. 1608 1609Finally the last type is to add new functions to PARI. We explain here how 1610to do this, so that in particular the new function can be called from \kbd{gp}. 1611 1612\subsec{Coding guidelines}\label{se:coding_guidelines} 1613\noindent 1614Code your function in a file of its own, using as a guide other functions 1615in the PARI sources. One important thing to remember is to clean the stack 1616before exiting your main function, since otherwise successive calls to 1617the function clutters the stack with unnecessary garbage, and stack 1618overflow occurs sooner. Also, if it returns a \kbd{GEN} and you want it 1619to be accessible to \kbd{gp}, you have to make sure this \kbd{GEN} is 1620suitable for \kbd{gerepileupto} (see \secref{se:garbage}). 1621 1622If error messages or warnings are to be generated in your function, use 1623\kbd{pari\_err} and \kbd{pari\_warn} respectively. 1624Recall that \kbd{pari\_err} does not return but ends with a \kbd{longjmp} 1625statement. As well, instead of explicit \kbd{printf}~/ \kbd{fprintf} 1626statements, use the following encapsulated variants: 1627 1628\fun{void}{pari_putc}{char c}: write character \kbd{c} to the output stream. 1629 1630\fun{void}{pari_puts}{char *s}: write \kbd{s} to the output stream. 1631 1632\fun{void}{pari_printf}{const char *fmt, ...}: write following arguments to the 1633output stream, according to the conversion specifications in format \kbd{fmt} 1634(see \tet{printf}). 1635 1636\fun{void}{err_printf}{const char *fmt, ...}: as \tet{pari_printf}, writing to 1637PARI's current error stream. 1638 1639\fun{void}{err_flush}{void} flush error stream. 1640 1641Declare all public functions in an appropriate header file, if you 1642want to access them from C. The other functions should be declared 1643\kbd{static} in your file. 1644 1645Your function is now ready to be used in library mode after compilation and 1646creation of the library. If possible, compile it as a shared library (see 1647the \kbd{Makefile} coming with the \kbd{extgcd} example in the 1648distribution). It is however still inaccessible from \kbd{gp}.\smallskip 1649 1650\subsec{GP prototypes, parser codes} 1651\label{se:gp.interface} 1652A \tev{GP prototype} is a character string describing all the GP parser needs 1653to know about the function prototype. It contains a sequence of the following 1654atoms: 1655 1656\settabs\+\indent&\kbd{Dxxx}\quad&\cr 1657 1658\noindent\item Return type: \kbd{GEN} by default (must be valid for 1659\kbd{gerepileupto}), otherwise the following can appear as the \emph{first} 1660char of the code string: 1661% 1662\+& \kbd{i} & return \kbd{int}\cr 1663\+& \kbd{l} & return \kbd{long}\cr 1664\+& \kbd{u} & return \kbd{ulong}\cr 1665\+& \kbd{v} & return \kbd{void}\cr 1666\+& \kbd{m} & return a \kbd{GEN} which is not \kbd{gerepile}-safe.\cr 1667 1668The \kbd{m} code is used for member functions, to avoid unnecessary copies. A 1669copy opcode is generated by the compiler if the result needs to be kept safe 1670for later use. 1671 1672\noindent\item Mandatory arguments, appearing in the same order as the 1673input arguments they describe: 1674% 1675\+& \kbd{G} & \kbd{GEN}\cr 1676\+& \kbd{\&}& \kbd{*GEN}\cr 1677\+& \kbd{L} & \kbd{long} (we implicitly typecast \kbd{int} to \kbd{long})\cr 1678\+& \kbd{U} & \kbd{ulong} \cr 1679\+& \kbd{V} & loop variable\cr 1680\+& \kbd{n} & variable, expects a \idx{variable number} (a \kbd{long}, not an 1681\kbd{*entree})\cr 1682\+& \kbd{W} & a \kbd{GEN} which is a lvalue to be modified in place 1683(for \typ{LIST})\cr 1684\+& \kbd{r} & raw input (treated as a string without quotes). Quoted 1685 args are copied as strings\cr 1686\+&&\quad Stops at first unquoted \kbd{')'} or \kbd{','}. Special chars can 1687be quoted using \kbd{'\bs'}\cr 1688\+&&\quad Example: \kbd{aa"b\bs n)"c} yields the string \kbd{"aab\bs{n})c"}\cr 1689\+& \kbd{s} & expanded string. Example: \kbd{Pi"x"2} yields \kbd{"3.142x2"}\cr 1690\+&&\quad Unquoted components can be of any PARI type, converted to string 1691 following\cr 1692\+&&\quad current output format\cr 1693\+& \kbd{I} & closure whose value is ignored, as in \kbd{for} loops,\cr 1694\+&&\quad to be processed by \fun{void}{closure_evalvoid}{GEN C}\cr 1695\+& \kbd{E} & closure whose value is used, as in \kbd{sum} loops,\cr 1696\+&&\quad to be processed by \fun{void}{closure_evalgen}{GEN C}\cr 1697\+& \kbd{J} & implicit function of arity $1$, as in \kbd{parsum} loops,\cr 1698\+&&\quad to be processed by \fun{void}{closure_callgen1}{GEN C}\cr 1699 1700\noindent A \tev{closure} is a GP function in compiled (bytecode) form. It 1701can be efficiently evaluated using the \kbd{closure\_eval}$xxx$ functions. 1702 1703\noindent\item Automatic arguments: 1704% 1705\+& \kbd{f} & Fake \kbd{*long}. C function requires a pointer but we 1706do not use the resulting \kbd{long}\cr 1707\+& \kbd{b} & current real precision in bits \cr 1708\+& \kbd{p} & current real precision in words \cr 1709\+& \kbd{P} & series precision (default \kbd{seriesprecision}, 1710 global variable \kbd{precdl} for the library)\cr 1711\+& \kbd{C} & lexical context (internal, for \kbd{eval}, 1712 see \kbd{localvars\_read\_str})\cr 1713 1714\noindent\item Syntax requirements, used by functions like 1715 \kbd{for}, \kbd{sum}, etc.: 1716% 1717\+& \kbd{=} & separator \kbd{=} required at this point (between two 1718arguments)\cr 1719 1720\noindent\item Optional arguments and default values: 1721% 1722\+& \kbd{E*} & any number of expressions, possibly 0 (see \kbd{E})\cr 1723\+& \kbd{s*} & any number of strings, possibly 0 (see \kbd{s})\cr 1724\+& \kbd{D\var{xxx}} & argument can be omitted and has a default value\cr 1725 1726The \kbd{E*} code reads all remaining arguments in closure context and passes 1727them as a single \typ{VEC}. 1728The \kbd{s*} code reads all remaining arguments in \tev{string context} and 1729passes the list of strings as a single \typ{VEC}. The automatic concatenation 1730rules in string context are implemented so that adjacent strings 1731are read as different arguments, as if they had been comma-separated. For 1732instance, if the remaining argument sequence is: \kbd{"xx" 1, "yy"}, the 1733\kbd{s*} atom sends \kbd{[a, b, c]}, where 1734$a$, $b$, $c$ are \kbd{GEN}s of type \typ{STR} (content \kbd{"xx"}), 1735\typ{INT} (equal to $1$) and \typ{STR} (content \kbd{"yy"}). 1736 1737The format to indicate a default value (atom starts with a \kbd{D}) is 1738``\kbd{D\var{value},\var{type},}'', where \var{type} is the code for any 1739mandatory atom (previous group), \var{value} is any valid GP expression 1740which is converted according to \var{type}, and the ending comma is 1741mandatory. For instance \kbd{D0,L,} stands for ``this optional argument is 1742converted to a \kbd{long}, and is \kbd{0} by default''. So if the 1743user-given argument reads \kbd{1 + 3} at this point, \kbd{4L} is sent to 1744the function; and \kbd{0L} if the argument is omitted. The following 1745special notations are available: 1746 1747\settabs\+\indent\indent&\kbd{Dxxx}\quad& optional \kbd{*GEN},&\cr 1748\+&\kbd{DG}& optional \kbd{GEN}, & send \kbd{NULL} if argument omitted.\cr 1749 1750\+&\kbd{D\&}& optional \kbd{*GEN}, send \kbd{NULL} if argument omitted.\cr 1751\+&&\quad The argument must be prefixed by \kbd{\&}.\cr 1752 1753\+&\kbd{DI}, \kbd{DE}& optional closure, send \kbd{NULL} if argument omitted.\cr 1754 1755\+&\kbd{DP}& optional \kbd{long}, send \kbd{precdl} if argument omitted.\cr 1756 1757\+&\kbd{DV}& optional \kbd{*entree}, send \kbd{NULL} if argument omitted.\cr 1758 1759\+&\kbd{Dn}& optional variable number, $-1$ if omitted.\cr 1760 1761\+&\kbd{Dr}& optional raw string, send \kbd{NULL} if argument omitted.\cr 1762 1763\+&\kbd{Ds}& optional \kbd{char *}, send \kbd{NULL} if argument omitted.\cr 1764 1765\misctitle{Hardcoded limit} C functions using more than 20 arguments are not 1766supported. Use vectors if you really need that many parameters. 1767 1768When the function is called under \kbd{gp}, the prototype is scanned and each 1769time an atom corresponding to a mandatory argument is met, a user-given 1770argument is read (\kbd{gp} outputs an error message it the argument was 1771missing). Each time an optional atom is met, a default value is inserted if the 1772user omits the argument. The ``automatic'' atoms fill in the argument list 1773transparently, supplying the current value of the corresponding variable (or a 1774dummy pointer). 1775 1776For instance, here is how you would code the following prototypes, which 1777do not involve default values: 1778\bprog 1779GEN f(GEN x, GEN y, long prec) ----> "GGp" 1780void f(GEN x, GEN y, long prec) ----> "vGGp" 1781void f(GEN x, long y, long prec) ----> "vGLp" 1782long f(GEN x) ----> "lG" 1783int f(long x) ----> "iL" 1784@eprog\noindent 1785If you want more examples, \kbd{gp} gives you easy access to the parser codes 1786attached to all GP functions: just type \kbd{\b{h} \var{function}}. You 1787can then compare with the C prototypes as they stand in \kbd{paridecl.h}. 1788 1789\misctitle{Remark} If you need to implement complicated control statements 1790(probably for some improved summation functions), you need to know 1791how the parser implements closures and lexicals and how the evaluator lets 1792you deal with them, in particular the \tet{push_lex} and \tet{pop_lex} 1793functions. Check their descriptions and adapt the source code in 1794\kbd{language/sumiter.c} and \kbd{language/intnum.c}. 1795 1796\subsec{Integration with \kbd{gp} as a shared module} 1797 1798In this section we assume that your Operating System is supported by 1799\tet{install}. You have written a function in C following the guidelines is 1800\secref{se:coding_guidelines}; in case the function returns a \kbd{GEN}, it 1801must satisfy \kbd{gerepileupto} assumptions (see \secref{se:garbage}). 1802 1803You then succeeded in building it as part of a shared library and want to 1804finally tell \kbd{gp} about your function. First, find a name for it. It does 1805not have to match the one used in library mode, but consistency is nice. It 1806has to be a valid GP identifier, i.e.~use only alphabetic characters, digits 1807and the underscore character (\kbd{\_}), the first character being 1808alphabetic. 1809 1810Then figure out the correct \idx{parser code} corresponding to the function 1811prototype (as explained in~\secref{se:gp.interface}) and write a GP script 1812like the following: 1813\bprog 1814install(libname, code, gpname, library) 1815addhelp(gpname, "some help text") 1816@eprog 1817\noindent The \idx{addhelp} part is not mandatory, but very useful if you 1818want others to use your module. \kbd{libname} is how the function is named in 1819the library, usually the same name as one visible from C. 1820 1821Read that file from your \kbd{gp} session, for instance from your 1822\idx{preferences file} (or \kbd{gprc}), and that's it. You 1823can now use the new function \var{gpname} under \kbd{gp}, and we would very 1824much like to hear about it! 1825\smallskip 1826 1827\misctitle{Example} 1828A complete description could look like this: 1829\bprog 1830{ 1831 install(bnfinit0, "GD0,L,DGp", ClassGroupInit, "libpari.so"); 1832 addhelp(ClassGroupInit, "ClassGroupInit(P,{flag=0},{data=[]}): 1833 compute the necessary data for ..."); 1834} 1835@eprog\noindent which means we have a function \kbd{ClassGroupInit} under 1836\kbd{gp}, which calls the library function \kbd{bnfinit0} . The function has 1837one mandatory argument, and possibly two more (two \kbd{'D'} in the code), 1838plus the current real precision. More precisely, the first argument is a 1839\kbd{GEN}, the second one is converted to a \kbd{long} using \kbd{itos} 1840(\kbd{0} is passed if it is omitted), and the third one is also a \kbd{GEN}, 1841but we pass \kbd{NULL} if no argument was supplied by the user. This matches 1842the C prototype (from \kbd{paridecl.h}): 1843% 1844\bprog 1845 GEN bnfinit0(GEN P, long flag, GEN data, long prec) 1846@eprog\noindent 1847This function is in fact coded in \kbd{basemath/buch2.c}, and is in this case 1848completely identical to the GP function \kbd{bnfinit} but \kbd{gp} does not 1849need to know about this, only that it can be found somewhere in the shared 1850library \kbd{libpari.so}. 1851 1852\misctitle{Important note} You see in this example that it is the 1853function's responsibility to correctly interpret its operands: \kbd{data = 1854NULL} is interpreted \emph{by the function} as an empty vector. Note that 1855since \kbd{NULL} is never a valid \kbd{GEN} pointer, this trick always 1856enables you to distinguish between a default value and actual input: the 1857user could explicitly supply an empty vector! 1858 1859\subsec{Library interface for \kbd{install}} 1860 1861There is a corresponding library interface for this \kbd{install} 1862functionality, letting you expand the GP parser/evaluator available in the 1863library with new functions from your C source code. Functions such as 1864\tet{gp_read_str} may then evaluate a GP expression sequence involving calls 1865to these new function! 1866 1867\fun{entree *}{install}{void *f, const char *gpname, const char *code} 1868 1869\noindent where \kbd{f} is the (address of the) function (cast to 1870\kbd{void*}), \kbd{gpname} is the name by which you want to access your 1871function from within your GP expressions, and \kbd{code} is as above. 1872 1873 1874\subsec{Integration by patching \kbd{gp}} 1875 1876If \tet{install} is not available, and installing Linux or a BSD operating 1877system is not an option (why?), you have to hardcode your function in the 1878\kbd{gp} binary. Here is what needs to be done: 1879 1880\item Fetch the complete sources of the PARI distribution. 1881 1882\item Drop the function source code module in an appropriate directory 1883(a priori \kbd{src/modules}), and declare all public functions 1884in \kbd{src/headers/paridecl.h}. 1885 1886\item Choose a help section and add a file 1887\kbd{src/functions/\var{section}/\var{gpname}} 1888containing the following, keeping the notation above: 1889\bprog 1890Function: @com\var{gpname} 1891Section: @com\var{section} 1892C-Name: @com\var{libname} 1893Prototype: @com\var{code} 1894Help: @com\var{some help text} 1895@eprog\noindent 1896(If the help text does not fit on a single line, continuation lines must 1897start by a whitespace character.) Two GP2C-related fields (\kbd{Description} 1898and \kbd{Wrapper}) are also available to improve the code GP2C generates when 1899compiling scripts involving your function. See the GP2C documentation for 1900details. 1901 1902\item Launch \kbd{Configure}, which should pick up your C files and build an 1903appropriate \kbd{Makefile}. At this point you can recompile \kbd{gp}, which 1904will first rebuild the functions database. 1905 1906\misctitle{Example} We reuse the \kbd{ClassGroupInit} / \kbd{bnfinit0} 1907from the preceding section. Since the C source code is already part 1908of PARI, we only need to add a file 1909 1910 \kbd{functions/number\_fields/ClassGroupInit} 1911 1912\noindent containing the following: 1913\bprog 1914Function: ClassGroupInit 1915Section: number_fields 1916C-Name: bnfinit0 1917Prototype: GD0,L,DGp 1918Help: ClassGroupInit(P,{flag=0},{tech=[]}): this routine does @com\dots 1919@eprog\noindent 1920and recompile \kbd{gp}. 1921 1922\section{Globals related to PARI configuration} 1923\subsec{PARI version numbers} 1924 1925\noindent \tet{paricfg_version_code} encodes in a single \kbd{long}, the Major 1926and minor version numbers as well as the patchlevel. 1927 1928\fun{long}{PARI_VERSION}{long M, long m, long p} produces the version code 1929attached to release $M.m.p$. Each code identifies a unique PARI release, 1930and corresponds to the natural total order on the set of releases (bigger 1931code number means more recent release). 1932 1933\noindent \tet{PARI_VERSION_SHIFT} is the number of bits used to store each of 1934the integers $M$, $m$, $p$ in the version code. 1935 1936\noindent \tet{paricfg_vcsversion} is a version string related to the 1937revision control system used to handle your sources, if any. For instance 1938\kbd{git-}\emph{commit hash} if compiled from a git repository. 1939 1940The two character strings \tet{paricfg_version} and \tet{paricfg_buildinfo}, 1941correspond to the first two lines printed by \kbd{gp} just before the 1942Copyright message. The character string \tet{paricfg_compiledate} is the 1943date of compilation which appears on the next line. The character string 1944\tet{paricfg_mt_engine} is the name of the threading engine on the next line. 1945 1946In the string \kbd{paricfg\_buildinfo}, the substring \kbd{"\%s"} needs 1947to be substituted by the output of the function \kbd{pari\_kernel\_version}. 1948 1949\fun{const char *}{pari_kernel_version}{void} 1950 1951\fun{GEN}{pari_version}{} returns the version number as a PARI object, a 1952\typ{VEC} with three \typ{INT} and one \typ{STR} components. 1953 1954\subsec{Miscellaneous} 1955 1956\tet{paricfg_datadir}: character string. The location of PARI's \tet{datadir}. 1957 1958\tet{paricfg_gphelp}: character string. The name of an external help command 1959for \kbd{??} (such as the \kbd{gphelp} script) 1960 1961\newpage 1962\chapter{Arithmetic kernel: Level 0 and 1} 1963 1964\section{Level 0 kernel (operations on ulongs)} 1965 1966\subsec{Micro-kernel} 1967The Level 0 kernel simulates basic operations of the 68020 processor on which 1968PARI was originally implemented. They need ``global'' \kbd{ulong} variables 1969\kbd{overflow} (which will contain only 0 or 1) and \kbd{hiremainder} to 1970function properly. A routine using one of these lowest-level functions 1971where the description mentions either \kbd{hiremainder} or \kbd{overflow} 1972must declare the corresponding 1973\bprog 1974 LOCAL_HIREMAINDER; /* provides 'hiremainder' */ 1975 LOCAL_OVERFLOW; /* provides 'overflow' */ 1976@eprog\noindent 1977in a declaration block. Variables \kbd{hiremainder} and \kbd{overflow} then 1978become available in the enclosing block. For instance a loop over the powers 1979of an \kbd{ulong}~\kbd{p} protected from overflows could read 1980\bprog 1981 while (pk < lim) 1982 { 1983 LOCAL_HIREMAINDER; 1984 ... 1985 pk = mulll(pk, p); if (hiremainder) break; 1986 } 1987@eprog\noindent 1988For most architectures, the functions mentioned below are really chunks of 1989inlined assembler code, and the above `global' variables are actually 1990local register values. 1991 1992\fun{ulong}{addll}{ulong x, ulong y} adds \kbd{x} and \kbd{y}, returns the 1993lower \B\ bits and puts the carry bit into \kbd{overflow}. 1994 1995\fun{ulong}{addllx}{ulong x, ulong y} adds \kbd{overflow} to the sum of the 1996\kbd{x} and \kbd{y}, returns the lower \B\ bits and puts the carry bit into 1997\kbd{overflow}. 1998 1999\fun{ulong}{subll}{ulong x, ulong y} subtracts \kbd{x} and \kbd{y}, returns 2000the lower \B\ bits and put the carry (borrow) bit into \kbd{overflow}. 2001 2002\fun{ulong}{subllx}{ulong x, ulong y} subtracts \kbd{overflow} from the 2003difference of \kbd{x} and \kbd{y}, returns the lower \B\ bits and puts the 2004carry (borrow) bit into \kbd{overflow}. 2005 2006\fun{int}{bfffo}{ulong x} returns the number of leading zero bits in \kbd{x}. 2007That is, the number of bit positions by which it would have to be shifted 2008left until its leftmost bit first becomes equal to~1, which can be between 0 2009and $\B-1$ for nonzero \kbd{x}. When \kbd{x} is~0, the result is undefined. 2010 2011\fun{ulong}{mulll}{ulong x, ulong y} multiplies \kbd{x} by \kbd{y}, returns 2012the lower \B\ bits and stores the high-order \B\ bits into \kbd{hiremainder}. 2013 2014\fun{ulong}{addmul}{ulong x, ulong y} adds \kbd{hiremainder} to the product 2015of \kbd{x} and \kbd{y}, returns the lower \B\ bits and stores the high-order 2016\B\ bits into \kbd{hiremainder}. 2017 2018\fun{ulong}{divll}{ulong x, ulong y} returns the quotient of 2019$ \left(\kbd{hiremainder} * 2^{\B}\right) + \kbd{x} $ 2020by \kbd{y} and stores the remainder into \kbd{hiremainder}. An error occurs 2021if the quotient cannot be represented by an \kbd{ulong}, i.e.~if initially 2022$\kbd{hiremainder}\ge\kbd{y}$. 2023 2024\fun{long}{hammingl}{ulong x)} returns the Hamming weight of $x$, i.e.~the 2025number of nonzero bits in its binary expansion. 2026 2027\misctitle{Obsolete routines} Those functions are awkward and no longer used; 2028they are only provided for backward compatibility: 2029 2030\fun{ulong}{shiftl}{ulong x, ulong y} returns $x$ shifted left by $y$ bits, 2031i.e.~\kbd{$x$ << $y$}, where we assume that $0\leq y\leq\B$. The global variable 2032\kbd{hiremainder} receives the bits that were shifted out, 2033i.e.~\kbd{$x$ >> $(\B - y)$}. 2034 2035\fun{ulong}{shiftlr}{ulong x, ulong y} returns $x$ shifted right by $y$ bits, 2036i.e.~\kbd{$x$ >> $y$}, where we assume that $0\leq y\leq\B$. The global variable 2037\kbd{hiremainder} receives the bits that were shifted out, 2038i.e.~\kbd{$x$ << $(\B - y)$}. 2039 2040\subsec{Modular kernel} 2041The following routines are not part of the level 0 kernel per se, but 2042implement modular operations on words in terms of the above. They are written 2043so that no overflow may occur. Let $m \geq 1$ be the modulus; all operands 2044representing classes modulo $m$ are assumed to belong to $[0,m-1]$. The 2045result may be wrong for a number of reasons otherwise: it may not be reduced, 2046overflow can occur, etc. 2047 2048\fun{int}{odd}{ulong x} returns 1 if $x$ is odd, and 0 otherwise. 2049 2050\fun{int}{both_odd}{ulong x, ulong y} returns 1 if $x$ and $y$ are both odd, 2051and 0 otherwise. 2052 2053\fun{ulong}{invmod2BIL}{ulong x} returns the smallest 2054positive representative of $x^{-1}$ mod $2^\B$, assuming $x$ is odd. 2055 2056\fun{ulong}{Fl_add}{ulong x, ulong y, ulong m} returns the smallest 2057nonnegative representative of $x + y$ modulo $m$. 2058 2059\fun{ulong}{Fl_neg}{ulong x, ulong m} returns the smallest 2060nonnegative representative of $-x$ modulo $m$. 2061 2062\fun{ulong}{Fl_sub}{ulong x, ulong y, ulong m} returns the smallest 2063nonnegative representative of $x - y$ modulo $m$. 2064 2065\fun{long}{Fl_center}{ulong x, ulong m, ulong mo2} returns the representative 2066in $]-m/2,m/2]$ of $x$ modulo $m$. Assume $0 \leq x < m$ and 2067$\kbd{mo2} = m >> 1$. 2068 2069\fun{ulong}{Fl_mul}{ulong x, ulong y, ulong m} returns the smallest 2070nonnegative representative of $x y$ modulo $m$. 2071 2072\fun{ulong}{Fl_double}{ulong x, ulong m} returns $2x$ modulo $m$. 2073 2074\fun{ulong}{Fl_triple}{ulong x, ulong m} returns $3x$ modulo $m$. 2075 2076\fun{ulong}{Fl_halve}{ulong x, ulong m} returns $z$ such that $2\*z = x$ modulo 2077$m$ assuming such $z$ exists. 2078 2079\fun{ulong}{Fl_sqr}{ulong x, ulong m} returns the smallest nonnegative 2080representative of $x^2$ modulo $m$. 2081 2082\fun{ulong}{Fl_inv}{ulong x, ulong m} returns the smallest 2083positive representative of $x^{-1}$ modulo $m$. If $x$ is not invertible 2084mod~$m$, raise an exception. 2085 2086\fun{ulong}{Fl_invsafe}{ulong x, ulong m} returns the smallest 2087positive representative of $x^{-1}$ modulo $m$. If $x$ is not invertible 2088mod~$m$, return $0$ (which is ambiguous if $m=1$). 2089 2090\fun{ulong}{Fl_invgen}{ulong x, ulong m, ulong *pg} set \kbd{*pg} to 2091$g = \gcd(x,m)$ and return $u$ in $(\Z/m\Z)^*$ such that $x u = g$ modulo $m$. 2092We have $g = 1$ if and only if $x$ is invertible, and in this case $u$ 2093is its inverse. 2094 2095\fun{ulong}{Fl_div}{ulong x, ulong y, ulong m} returns the smallest 2096nonnegative representative of $x y^{-1}$ modulo $m$. If $y$ is not invertible 2097mod $m$, raise an exception. 2098 2099\fun{ulong}{Fl_powu}{ulong x, ulong n, ulong m} returns the smallest 2100nonnegative representative of $x^n$ modulo $m$. 2101 2102\fun{GEN}{Fl_powers}{ulong x, long n, ulong p} returns 2103$[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ modulo $m$, as a \typ{VECSMALL}. 2104 2105\fun{ulong}{Fl_sqrt}{ulong x, ulong p} returns the square root of \kbd{x} 2106modulo \kbd{p} (smallest nonnegative representative). Assumes \kbd{p} to be 2107prime, and \kbd{x} to be a square modulo \kbd{p}. 2108 2109\fun{ulong}{Fl_sqrtl}{ulong x, ulong l, ulong p} returns a $l$-the root of \kbd{x} 2110modulo \kbd{p}. Assumes \kbd{p} to be prime and $p \equiv 1 \pmod{l}$, and 2111\kbd{x} to be a $l$-th power modulo \kbd{p}. 2112 2113\fun{ulong}{Fl_sqrtn}{ulong a, ulong n, ulong p, ulong *zn} 2114returns \kbd{ULONG\_MAX} if $a$ is not an $n$-th power residue mod $p$. 2115Otherwise, returns an $n$-th root of $a$; if \kbd{zn} is not \kbd{NULL} 2116set it to a primitive $m$-th root of 1, $m = \gcd(p-1,n)$ allowing to compute 2117all $m$ solutions in $\F_p$ of the equation $x^n = a$. 2118 2119\fun{ulong}{Fl_log}{ulong a, ulong g, ulong ord, ulong p} Let $g$ such that 2120$g^{ord} \equiv 1 \pmod{p}$. Return an integer $e$ such that 2121$a^e \equiv g \pmod{p}$. If $e$ does not exist, the result is undefined. 2122 2123\fun{ulong}{Fl_order}{ulong a, ulong o, ulong p} returns the order of the 2124\kbd{Fp} \kbd{a}. It is assumed that \kbd{o} is a multiple of the order of 2125\kbd{a}, $0$ being allowed (no nontrivial information). 2126 2127\fun{ulong}{random_Fl}{ulong p} returns a pseudo-random integer uniformly 2128distributed in $0, 1, \dots p-1$. 2129 2130\fun{ulong}{nonsquare_Fl}{ulong p} return a quadratic nonresidue modulo $p$, 2131assuming $p$ is an odd prime. If $p$ is $3$ mod $4$, return $p-1$, else 2132return the smallest (prime) nonresidue. 2133 2134\fun{ulong}{pgener_Fl}{ulong p} returns the smallest \idx{primitive root} 2135modulo \kbd{p}, assuming \kbd{p} is prime. 2136 2137\fun{ulong}{pgener_Zl}{ulong p} returns the smallest primitive root modulo 2138$p^k$, $k > 1$, assuming $p$ is an odd prime. 2139 2140\fun{ulong}{pgener_Fl_local}{ulong p, GEN L}, see \kbd{gener\_Fp\_local}, 2141\kbd{L} is an \kbd{Flv}. 2142 2143\fun{ulong}{factorial_Fl}{long n, ulong p} return $n!$ mod $p$. 2144 2145\subsec{Modular kernel with ``precomputed inverse''} 2146 2147This is based on an algorithm by T. Grandlund and N. M\"{o}ller in 2148``Improved division by invariant integers'' 2149\url{http://gmplib.org/~tege/division-paper.pdf}. 2150 2151In the following, we set $B=\B$. 2152 2153\fun{ulong}{get_Fl_red}{ulong p} returns a pseudo inverse \var{pi} for $p$ 2154 2155\fun{ulong}{divll_pre}{ulong x, ulong p, ulong yi} 2156as divll, where $yi$ is the pseudo inverse of $y$. 2157 2158\fun{ulong}{remll_pre}{ulong u1, ulong u0, ulong p, ulong pi} returns 2159the Euclidean remainder of $u_1\*2^B+u_0$ modulo $p$, assuming $pi$ is the 2160pseudo inverse of $p$. This function is faster if $u_1 < p$. 2161 2162\fun{ulong}{remlll_pre}{ulong u2, ulong u1, ulong u0, ulong p, ulong pi} 2163returns the Euclidean remainder of $u_2\*2^{2\*B}+u_1\*2^{B}+u_0$ modulo $p$, 2164assuming $pi$ is the pseudo inverse of $p$. 2165 2166\fun{ulong}{Fl_sqr_pre}{ulong x, ulong p, ulong pi} returns $x^2$ modulo $p$, 2167assuming $pi$ is the pseudo inverse of $p$. 2168 2169\fun{ulong}{Fl_mul_pre}{ulong x, ulong y, ulong p, ulong pi} returns $x\*y$ 2170modulo $p$, assuming $pi$ is the pseudo inverse of $p$. 2171 2172\fun{ulong}{Fl_addmul_pre}{ulong a, ulong b, ulong c, ulong p, ulong pi} 2173returns $a+b\*c$ modulo $p$, assuming $pi$ is the pseudo inverse of $p$. 2174 2175\fun{ulong}{Fl_addmulmul_pre}{ulong a,ulong b, ulong c,ulong d, ulong p, ulong pi} 2176returns $a\*b+c\*d$ modulo $p$, assuming $pi$ is the pseudo inverse of $p$. 2177 2178\fun{ulong}{Fl_powu_pre}{ulong x, ulong n, ulong p, ulong pi} returns 2179$x^n$ modulo $p$, assuming $pi$ is the pseudo inverse of $p$. 2180 2181\fun{GEN}{Fl_powers_pre}{ulong x, long n, ulong p, ulong pi} returns 2182the vector (\typ{VECSMALL}) $(x^0, \dots, x^n)$, assuming $pi$ is 2183the pseudo inverse of $p$. 2184 2185\fun{ulong}{Fl_log_pre}{ulong a, ulong g, ulong ord, ulong p, ulong pi} 2186as \kbd{Fl\_log}, assuming $pi$ is the pseudo inverse of $p$. 2187 2188\fun{ulong}{Fl_sqrt_pre}{ulong x, ulong p, ulong pi} returns a square root 2189of $x$ modulo $p$, assuming $pi$ is the pseudo inverse of $p$. 2190See \kbd{Fl\_sqrt}. 2191 2192\fun{ulong}{Fl_sqrtl_pre}{ulong x, ulong l, ulong p, ulong pi} 2193returns a $l$-the root of \kbd{x} 2194modulo \kbd{p}, assuming $pi$ is the pseudo inverse of $p$, 2195$p$ prime and $p \equiv 1 \pmod{l}$, and \kbd{x} to be a $l$-th power modulo 2196\kbd{p}. 2197 2198\fun{ulong}{Fl_sqrtn_pre}{ulong x, ulong n, ulong p, ulong *zn} 2199See \kbd{Fl\_sqrtn}, assuming $pi$ is the pseudo inverse of $p$. 2200 2201\fun{ulong}{Fl_2gener_pre}{ulong p, ulong pi} return a generator of 2202the $2$-Sylow subgroup of $\F_p^*$. To use with \kbd{Fl\_sqrt\_pre\_i}. 2203 2204\fun{ulong}{Fl_sqrt_pre_i}{ulong x, ulong s2, ulong p, ulong pi} 2205as \kbd{Fl\_sqrt\_pre} where \kbd{s2} is the element returned by 2206\kbd{Fl\_2gener\_pre}. 2207 2208\subsec{Switching between Fl\_xxx and standard operators} 2209 2210Even though the \kbd{Fl\_xxx} routines are efficient, they are slower than 2211ordinary \kbd{long} operations, using the standard \kbd{+}, \kbd{\%}, etc. 2212operators. 2213The following macro is used to choose in a portable way the most efficient 2214functions for given operands: 2215 2216\fun{int}{SMALL_ULONG}{ulong p} true if $2p^2 <2^\B$. In that case, it is 2217possible to use ordinary operators efficiently. If $p < 2^\B$, one 2218may still use the \kbd{Fl\_xxx} routines. Otherwise, one must use generic 2219routines. For instance, the scalar product of the \kbd{GEN}s $x$ and $y$ mod 2220$p$ could be computed as follows. 2221\bprog 2222 long i, l = lg(x); 2223 if (lgefint(p) > 3) 2224 { /* arbitrary */ 2225 GEN s = gen_0; 2226 for (i = 1; i < l; i++) s = addii(s, mulii(gel(x,i), gel(y,i))); 2227 return modii(s, p). 2228 } 2229 else 2230 { 2231 ulong s = 0, pp = itou(p); 2232 x = ZV_to_Flv(x, pp); 2233 y = ZV_to_Flv(y, pp); 2234 if (SMALL_ULONG(pp)) 2235 { /* very small */ 2236 for (i = 1; i < l; i++) 2237 { 2238 s += x[i] * y[i]; 2239 if (s & HIGHBIT) s %= pp; 2240 } 2241 s %= pp; 2242 } 2243 else 2244 { /* small */ 2245 for (i = 1; i < l; i++) 2246 s = Fl_add(s, Fl_mul(x[i], y[i], pp), pp); 2247 } 2248 return utoi(s); 2249 } 2250@eprog\noindent 2251In effect, we have three versions of the same code: very small, small, and 2252arbitrary inputs. The very small and arbitrary variants use lazy reduction 2253and reduce only when it becomes necessary: when overflow might occur (very 2254small), and at the very end (very small, arbitrary). 2255 2256\section{Level 1 kernel (operations on longs, integers and reals)} 2257 2258\misctitle{Note} Some functions consist of an elementary operation, 2259immediately followed by an assignment statement. They will be introduced as 2260in the following example: 2261 2262\fun{GEN}{gadd[z]}{GEN x, GEN y[, GEN z]} followed by the explicit 2263description of the function 2264 2265\fun{GEN}{gadd}{GEN x, GEN y} 2266 2267\noindent which creates its result on the stack, returning a \kbd{GEN} pointer 2268to it, and the parts in brackets indicate that there exists also a function 2269 2270\fun{void}{gaddz}{GEN x, GEN y, GEN z} 2271 2272\noindent which assigns its result to the pre-existing object 2273\kbd{z}, leaving the stack unchanged. These assignment variants are kept for 2274backward compatibility but are inefficient: don't use them. 2275 2276\subsec{Creation} 2277 2278\fun{GEN}{cgeti}{long n} allocates memory on the PARI stack for a \typ{INT} 2279of length~\kbd{n}, and initializes its first codeword. Identical to 2280\kbd{cgetg(n,\typ{INT})}. 2281 2282\fun{GEN}{cgetipos}{long n} allocates memory on the PARI stack for a 2283\typ{INT} of length~\kbd{n}, and initializes its two codewords. The sign 2284of \kbd{n} is set to $1$. 2285 2286\fun{GEN}{cgetineg}{long n} allocates memory on the PARI stack for a negative 2287\typ{INT} of length~\kbd{n}, and initializes its two codewords. The sign 2288of \kbd{n} is set to $-1$. 2289 2290\fun{GEN}{cgetr}{long n} allocates memory on the PARI stack for a \typ{REAL} 2291of length~\kbd{n}, and initializes its first codeword. Identical to 2292\kbd{cgetg(n,\typ{REAL})}. 2293 2294\fun{GEN}{cgetc}{long n} allocates memory on the PARI stack for a 2295\typ{COMPLEX}, whose real and imaginary parts are \typ{REAL}s 2296of length~\kbd{n}. 2297 2298\fun{GEN}{real_1}{long prec} create a \typ{REAL} equal to $1$ to \kbd{prec} 2299words of accuracy. 2300 2301\fun{GEN}{real_1_bit}{long bitprec} create a \typ{REAL} equal to $1$ to 2302\kbd{bitprec} bits of accuracy. 2303 2304\fun{GEN}{real_m1}{long prec} create a \typ{REAL} equal to $-1$ to \kbd{prec} 2305words of accuracy. 2306 2307\fun{GEN}{real_0_bit}{long bit} create a \typ{REAL} equal to $0$ with 2308exponent $-\kbd{bit}$. 2309 2310\fun{GEN}{real_0}{long prec} is a shorthand for 2311\bprog 2312 real_0_bit( -prec2nbits(prec) ) 2313@eprog 2314 2315\fun{GEN}{int2n}{long n} creates a \typ{INT} equal to \kbd{1<<n} (i.e 2316$2^n$ if $n \geq 0$, and $0$ otherwise). 2317 2318\fun{GEN}{int2u}{ulong n} creates a \typ{INT} equal to $2^n$. 2319 2320\fun{GEN}{int2um1}{long n} creates a \typ{INT} equal to $2^n - 1$. 2321 2322\fun{GEN}{real2n}{long n, long prec} create a \typ{REAL} equal to $2^n$ 2323to \kbd{prec} words of accuracy. 2324 2325\fun{GEN}{real_m2n}{long n, long prec} create a \typ{REAL} equal to $-2^n$ 2326to \kbd{prec} words of accuracy. 2327 2328\fun{GEN}{strtoi}{char *s} convert the character string \kbd{s} to a 2329nonnegative \typ{INT}. 2330Decimal numbers, hexadecimal numbers prefixed by \kbd{0x} and binary numbers prefixed 2331by \kbd{0b} are allowed. The string \kbd{s} consists exclusively of digits: 2332no leading sign, no whitespace. Leading zeroes are discarded. 2333 2334\fun{GEN}{strtor}{char *s, long prec} convert the character string \kbd{s} to 2335a nonnegative \typ{REAL} of precision \kbd{prec}. The string \kbd{s} 2336consists exclusively of digits and optional decimal point and exponent 2337(\kbd{e} or \kbd{E}): no leading sign, no whitespace. Leading zeroes are 2338discarded. 2339 2340\subsec{Assignment} 2341In this section, the \kbd{z} argument in the \kbd{z}-functions must be of type 2342\typ{INT} or~\typ{REAL}. 2343 2344\fun{void}{mpaff}{GEN x, GEN z} assigns \kbd{x} into~\kbd{z} (where \kbd{x} 2345and \kbd{z} are \typ{INT} or \typ{REAL}). 2346Assumes that $\kbd{lg(z)} > 2$. 2347 2348\fun{void}{affii}{GEN x, GEN z} assigns the \typ{INT} \kbd{x} into the 2349\typ{INT}~\kbd{z}. 2350 2351\fun{void}{affir}{GEN x, GEN z} assigns the \typ{INT} \kbd{x} into the 2352\typ{REAL}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$. 2353 2354\fun{void}{affiz}{GEN x, GEN z} assigns \typ{INT}~\kbd{x} into \typ{INT} or 2355\typ{REAL}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$. 2356 2357\fun{void}{affsi}{long s, GEN z} assigns the \kbd{long}~\kbd{s} into the 2358\typ{INT}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$. 2359 2360\fun{void}{affsr}{long s, GEN z} assigns the \kbd{long}~\kbd{s} into the 2361\typ{REAL}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$. 2362 2363\fun{void}{affsz}{long s, GEN z} assigns the \kbd{long}~\kbd{s} into the 2364\typ{INT} or \typ{REAL}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$. 2365 2366\fun{void}{affui}{ulong u, GEN z} assigns the \kbd{ulong}~\kbd{u} into the 2367\typ{INT}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$. 2368 2369\fun{void}{affur}{ulong u, GEN z} assigns the \kbd{ulong}~\kbd{u} into the 2370\typ{REAL}~\kbd{z}. Assumes that $\kbd{lg(z)} > 2$. 2371 2372\fun{void}{affrr}{GEN x, GEN z} assigns the \typ{REAL}~\kbd{x} into the 2373\typ{REAL}~\kbd{z}. 2374 2375\fun{void}{affgr}{GEN x, GEN z} assigns the scalar \kbd{x} into the 2376\typ{REAL}~\kbd{z}, if possible. 2377 2378\noindent The function \kbd{affrs} and \kbd{affri} do not exist. So don't use 2379them. 2380 2381\fun{void}{affrr_fixlg}{GEN y, GEN z} a variant of \kbd{affrr}. First shorten 2382$z$ so that it is no longer than $y$, then assigns $y$ to $z$. This is used 2383in the following scenario: room is reserved for the result but, due to 2384cancellation, fewer words of accuracy are available than had been 2385anticipated; instead of appending meaningless $0$s to the mantissa, we store 2386what was actually computed. 2387 2388Note that shortening $z$ is not quite straightforward, since \kbd{setlg(z, ly)} 2389would leave garbage on the stack, which \kbd{gerepile} might later inspect. 2390It is done using 2391 2392\fun{void}{fixlg}{GEN z, long ly} see \tet{stackdummy} and the examples that 2393follow. 2394 2395\subsec{Copy} 2396 2397\fun{GEN}{icopy}{GEN x} copy relevant words of the \typ{INT}~\kbd{x} on the 2398stack: the length and effective length of the copy are equal. 2399 2400\fun{GEN}{rcopy}{GEN x} copy the \typ{REAL}~\kbd{x} on the stack. 2401 2402\fun{GEN}{leafcopy}{GEN x} copy the leaf~\kbd{x} on the 2403stack (works in particular for \typ{INT}s and \typ{REAL}s). 2404Contrary to \kbd{icopy}, \kbd{leafcopy} preserves the original 2405length of a \typ{INT}. The obsolete form \fun{GEN}{mpcopy}{GEN x} 2406is still provided for backward compatibility. 2407 2408This function also works on recursive types, copying them as if they were 2409leaves, i.e.~making a shallow copy in that case: the components of the copy 2410point to the same data as the component of the source; see also 2411\kbd{shallowcopy}. 2412 2413\fun{GEN}{leafcopy_avma}{GEN x, pari_sp av} analogous to \kbd{gcopy\_avma} 2414but simpler: assume $x$ is a leaf and return a copy allocated as if 2415initially we had \kbd{avma} equal to \kbd{av}. There is no need to pass a 2416pointer and update the value of the second argument: the new (fictitious) 2417\kbd{avma} is just the return value (typecast to \kbd{pari\_sp}). 2418 2419\fun{GEN}{icopyspec}{GEN x, long nx} copy the \kbd{nx} words 2420\kbd{x[2]}, \dots, \kbd{x[nx+1]} to make up a new \typ{INT}. Set the sign 2421to $1$. 2422 2423\subsec{Conversions} 2424 2425\fun{GEN}{itor}{GEN x, long prec} converts the \typ{INT}~\kbd{x} to a 2426\typ{REAL} of length \kbd{prec} and return the latter. 2427Assumes that $\kbd{prec} > 2$. 2428 2429\fun{long}{itos}{GEN x} converts the \typ{INT}~\kbd{x} to a \kbd{long} if 2430possible, otherwise raise an exception. We consider the conversion 2431to be possible if and only if $|x| \leq \kbd{LONG\_MAX}$, i.e. $|x| < 2^{63}$ 2432on a 64-bit architecture. Since the range is symetric, the output of 2433\kbd{itos} can safely be negated. 2434 2435\fun{long}{itos_or_0}{GEN x} converts the \typ{INT}~\kbd{x} to a \kbd{long} if 2436possible, otherwise return $0$. 2437 2438\fun{int}{is_bigint}{GEN n} true if \kbd{itos(n)} would give an error. 2439 2440\fun{ulong}{itou}{GEN x} converts the \typ{INT}~\kbd{|x|} to an \kbd{ulong} if 2441possible, otherwise raise an exception. The conversion is possible if 2442and only if $\kbd{lgefint}(x) \leq 3$. 2443 2444\fun{long}{itou_or_0}{GEN x} converts the \typ{INT}~\kbd{|x|} to an 2445\kbd{ulong} if possible, otherwise return $0$. 2446 2447\fun{GEN}{stoi}{long s} creates the \typ{INT} corresponding to the 2448\kbd{long}~\kbd{s}. 2449 2450\fun{GEN}{stor}{long s, long prec} converts the \kbd{long}~\kbd{s} into a 2451\typ{REAL} of length \kbd{prec} and return the latter. Assumes that 2452$\kbd{prec} > 2$. 2453 2454\fun{GEN}{utoi}{ulong s} converts the \kbd{ulong}~\kbd{s} into a \typ{INT} 2455and return the latter. 2456 2457\fun{GEN}{utoipos}{ulong s} converts the \emph{nonzero} \kbd{ulong}~\kbd{s} 2458into a \typ{INT} and return the latter. 2459 2460\fun{GEN}{utoineg}{ulong s} converts the \emph{nonzero} \kbd{ulong}~\kbd{s} 2461into the \typ{INT} $-s$ and return the latter. 2462 2463\fun{GEN}{utor}{ulong s, long prec} converts the \kbd{ulong}~\kbd{s} into a 2464\typ{REAL} of length \kbd{prec} and return the latter. Assumes that 2465$\kbd{prec} > 2$. 2466 2467\fun{GEN}{rtor}{GEN x, long prec} converts the \typ{REAL}~\kbd{x} to a 2468\typ{REAL} of length \kbd{prec} and return the latter. If 2469$\kbd{prec} < \kbd{lg(x)}$, round properly. If $\kbd{prec} > \kbd{lg(x)}$, 2470pad with zeroes. Assumes that $\kbd{prec} > 2$. 2471 2472\noindent The following function is also available as a special case of 2473\tet{mkintn}: 2474 2475\fun{GEN}{uu32toi}{ulong a, ulong b} returns the \kbd{GEN} equal to $2^{32} a + 2476b$, \emph{assuming} that $a,b < 2^{32}$. This does not depend on 2477\kbd{sizeof(long)}: the behavior is as above on both $32$ and $64$-bit 2478machines. 2479 2480\fun{GEN}{uu32toineg}{ulong a, ulong b} returns the \kbd{GEN} equal to 2481$- (2^{32} a + b)$, \emph{assuming} that $a,b < 2^{32}$ and that one of $a$ 2482or $b$ is positive. This does not depend on \kbd{sizeof(long)}: the behavior 2483is as above on both $32$ and $64$-bit machines. 2484 2485\fun{GEN}{uutoi}{ulong a, ulong b} returns the \kbd{GEN} equal to 2486$2^{\B} a + b$. 2487 2488\fun{GEN}{uutoineg}{ulong a, ulong b} returns the \kbd{GEN} equal to 2489$-(2^{\B} a + b)$. 2490 2491\subsec{Integer parts} 2492The following four functions implement the conversion from \typ{REAL} to 2493\typ{INT} using standard rounding modes. Contrary to usual semantics 2494(complement the mantissa with an infinite number of 0), they will raise an 2495error \emph{precision loss in truncation} if the \typ{REAL} represents a 2496range containing more than one integer. 2497 2498\fun{GEN}{ceilr}{GEN x} smallest integer larger or equal 2499to the \typ{REAL}~\kbd{x} (i.e.~the \kbd{ceil} function). 2500 2501\fun{GEN}{floorr}{GEN x} largest integer smaller or equal to the 2502\typ{REAL}~\kbd{x} (i.e.~the \kbd{floor} function). 2503 2504\fun{GEN}{roundr}{GEN x} rounds the \typ{REAL} \kbd{x} to the nearest integer 2505(towards~$+\infty$ in case of tie). 2506 2507\fun{GEN}{truncr}{GEN x} truncates the \typ{REAL}~\kbd{x} (not the same as 2508\kbd{floorr} if \kbd{x} is negative). 2509 2510The following four function are analogous, but can also treat the trivial 2511case when the argument is a \typ{INT}: 2512 2513\fun{GEN}{mpceil}{GEN x} 2514as \kbd{ceilr} except that \kbd{x} may be a \typ{INT}. 2515 2516\fun{GEN}{mpfloor}{GEN x} 2517as \kbd{floorr} except that \kbd{x} may be a \typ{INT}. 2518 2519\fun{GEN}{mpround}{GEN x} 2520as \kbd{roundr} except that \kbd{x} may be a \typ{INT}. 2521 2522\fun{GEN}{mptrunc}{GEN x} 2523as \kbd{truncr} except that \kbd{x} may be a \typ{INT}. 2524 2525\fun{GEN}{diviiround}{GEN x, GEN y} if \kbd{x} and \kbd{y} are \typ{INT}s, 2526returns the quotient $\kbd{x}/\kbd{y}$ of \kbd{x} and~\kbd{y}, rounded to 2527the nearest integer. If $\kbd{x}/\kbd{y}$ falls exactly halfway between 2528two consecutive integers, then it is rounded towards~$+\infty$ (as for 2529\tet{roundr}). 2530 2531\fun{GEN}{ceil_safe}{GEN x}, \kbd{x} being a real number (not necessarily a 2532\typ{REAL}) returns the smallest integer which is larger than any possible 2533incarnation of \kbd{x}. (Recall that a \typ{REAL} represents an interval of 2534possible values.) Note that \kbd{gceil} raises an exception if the input 2535accuracy is too low compared to its magnitude. 2536 2537\fun{GEN}{floor_safe}{GEN x}, \kbd{x} being a real number (not necessarily a 2538\typ{REAL}) returns the largest integer which is smaller than any possible 2539incarnation of \kbd{x}. (Recall that a \typ{REAL} represents an interval of 2540possible values.) Note that \kbd{gfloor} raises an exception if the input 2541accuracy is too low compared to its magnitude. 2542 2543\fun{GEN}{trunc_safe}{GEN x}, \kbd{x} being a real number (not necessarily a 2544\typ{REAL}) returns the integer with the largest absolute value, which is closer 2545to $0$ than any possible incarnation of \kbd{x}. (Recall that a \typ{REAL} 2546represents an interval of possible values.) 2547 2548\fun{GEN}{roundr_safe}{GEN x} rounds the \typ{REAL} \kbd{x} to the nearest 2549integer (towards~$+\infty$). Complement the mantissa with an infinite number 2550of $0$ before rounding, hence never raise an exception. 2551 2552\subsec{$2$-adic valuations and shifts} 2553 2554\fun{long}{vals}{long s} 2-adic valuation of the \kbd{long}~\kbd{s}. Returns 2555$-1$ if \kbd{s} is equal to 0. 2556 2557\fun{long}{vali}{GEN x} 2-adic valuation of the \typ{INT}~\kbd{x}. Returns $-1$ 2558if \kbd{x} is equal to 0. 2559 2560\fun{GEN}{mpshift}{GEN x, long n} shifts the~\typ{INT} or 2561\typ{REAL} \kbd{x} by~\kbd{n}. If \kbd{n} is positive, this is a left shift, 2562i.e.~multiplication by $2^{\kbd{n}}$. If \kbd{n} is negative, it is a right 2563shift by~$-\kbd{n}$, which amounts to the truncation of the quotient of \kbd{x} 2564by~$2^{-\kbd{n}}$. 2565 2566\fun{GEN}{shifti}{GEN x, long n} shifts the \typ{INT}~$x$ by~$n$. 2567 2568\fun{GEN}{shiftr}{GEN x, long n} shifts the \typ{REAL}~$x$ by~$n$. 2569 2570\fun{void}{shiftr_inplace}{GEN x, long n} shifts the \typ{REAL}~$x$ by~$n$, 2571in place. 2572 2573\fun{GEN}{trunc2nr}{GEN x, long n} given a \typ{REAL} $x$, returns 2574\kbd{truncr(shiftr(x,n))}, but faster, without leaving garbage on the stack 2575and never raising a \emph{precision loss in truncation} error. 2576Called by \tet{gtrunc2n}. 2577 2578\fun{GEN}{mantissa2nr}{GEN x, long n} given a \typ{REAL} $x$, returns 2579the mantissa of $x 2^n$ (disregards the exponent of $x$). Equivalent to 2580\bprog 2581 trunc2nr(x, n-expo(x)+bit_prec(x)-1) 2582@eprog 2583 2584\fun{GEN}{mantissa_real}{GEN z, long *e} returns the mantissa $m$ of $z$, and 2585sets \kbd{*e} to the exponent $\kbd{bit\_accuracy(lg(z))}-1-\kbd{expo}(z)$, 2586so that $z = m / 2^e$. 2587 2588\misctitle{Low-level} In the following two functions, $s$(ource) and $t$(arget) 2589need not be valid \kbd{GEN}s (in practice, they usually point to some part of a 2590\typ{REAL} mantissa): they are considered as arrays of words representing some 2591mantissa, and we shift globally $s$ by $n > 0$ bits, storing the result in 2592$t$. We assume that $m\leq M$ and only access $s[m], s[m+1],\ldots s[M]$ 2593(read) and likewise for $t$ (write); we may have $s = t$ but more general 2594overlaps are not allowed. The word $f$ is concatenated to $s$ to supply extra 2595bits. 2596 2597\fun{void}{shift_left}{GEN t, GEN s, long m, long M, ulong f, ulong n} 2598shifts the mantissa 2599$$s[m], s[m+1],\ldots s[M], f$$ 2600left by $n$ bits. 2601 2602\fun{void}{shift_right}{GEN t, GEN s, long m, long M, ulong f, ulong n} 2603shifts the mantissa 2604$$f, s[m], s[m+1],\ldots s[M]$$ 2605right by $n$ bits. 2606 2607\subsec{From \typ{INT} to bits or digits in base $2^k$ and back} 2608 2609\fun{GEN}{binary_zv}{GEN x} given a \typ{INT} $x$, return a \typ{VECSMALL} of 2610bits, from most significant to least significant. 2611 2612\fun{GEN}{binary_2k}{GEN x, long k} given a \typ{INT} $x$, and 2613$k > 0$, return a \typ{VEC} of digits of $x$ in base $2^k$, as \typ{INT}s, from 2614most significant to least significant. 2615 2616\fun{GEN}{binary_2k_nv}{GEN x, long k} given a \typ{INT} $x$, and $0 < k < 2617\tet{BITS_IN_LONG}$, return a \typ{VECSMALL} of digits of $x$ in base $2^k$, as 2618\kbd{ulong}s, from most significant to least significant. 2619 2620\fun{GEN}{bits_to_int}{GEN x, long l} given a vector $x$ of $l$ bits (as a 2621\typ{VECSMALL} or even a pointer to a part of a larger vector, so not a 2622proper \kbd{GEN}), return the integer $\sum_{i = 1}^l x[i] 2^{l-i}$, as a 2623\typ{INT}. 2624 2625\fun{ulong}{bits_to_u}{GEN v, long l} same as \tet{bits_to_int}, where 2626$l < \tet{BITS_IN_LONG}$, so we can return an \kbd{ulong}. 2627 2628\fun{GEN}{fromdigitsu}{GEN x, GEN B} 2629given a \typ{VECSMALL} $x$ of length $l$ and a \typ{INT} $B$, 2630return the integer $\sum_{i = 1}^l x[i] B^{i-1}$, as a \typ{INT}, 2631where the \kbd{x[i]} are seen as unsigned integers. 2632 2633\fun{GEN}{fromdigits_2k}{GEN x, long k} converse of \tet{binary_2k}; 2634given a \typ{VEC} $x$ of length $l$ and a positive \kbd{long} $k$, 2635where each $x[i]$ is a \typ{INT} with $0\leq x[i] < 2^k$, return the 2636integer $\sum_{i = 1}^l x[i] 2^{k(l-i)}$, as a \typ{INT}. 2637 2638\fun{GEN}{nv_fromdigits_2k}{GEN x, long k} as \tet{fromdigits_2k}, but 2639with $x$ being a \typ{VECSMALL} and each $x[i]$ being a \kbd{ulong} 2640with $0\leq x[i] < 2^{\min\{k,\tet{BITS_IN_LONG}\}}$. Here $k$ may be 2641any positive \kbd{long}, and the $x[i]$ are regarded as $k$-bit 2642integers by truncating or extending with zeroes. 2643 2644\subsec{Integer valuation} 2645For integers $x$ and $p$, such that $x\neq 0$ and $|p| > 1$, we define 2646$v_p(x)$ to be the largest integer exponent $e$ such that $p^e$ divides $x$. 2647If $p$ is prime, this is the ordinary valuation of $x$ at $p$. 2648 2649\fun{long}{Z_pvalrem}{GEN x, GEN p, GEN *r} applied to \typ{INT}s 2650$\kbd{x}\neq 0$ and~\kbd{p}, $|\kbd{p}| > 1$, returns $e := v_p(x)$ 2651The quotient $\kbd{x}/\kbd{p}^e$ is returned in~\kbd{*r}. If 2652$|\kbd{p}|$ is a prime, \kbd{*r} is the prime-to-\kbd{p} part of~\kbd{x}. 2653 2654\fun{long}{Z_pval}{GEN x, GEN p} as \kbd{Z\_pvalrem} but only returns 2655$v_p(x)$. 2656 2657\fun{long}{Z_lvalrem}{GEN x, ulong p, GEN *r} as \kbd{Z\_pvalrem}, 2658except that \kbd{p} is an \kbd{ulong} ($\kbd{p} > 1$). 2659 2660\fun{long}{Z_lvalrem_stop}{GEN *x, ulong p, int *stop} assume $x > 0$; 2661returns $e := v_p(x)$ and replaces $x$ by $x / p^e$. Set \kbd{stop} to $1$ if 2662the new value of $x$ is $ < p^2$ (and $0$ otherwise). To be used when trial 2663dividing $x$ by successive primes: the \kbd{stop} condition is cheaply tested 2664while testing whether $p$ divides $x$ (is the quotient less than $p$?), and 2665allows to decide that $n$ is prime if no prime $< p$ divides $n$. Not 2666memory-clean. 2667 2668\fun{long}{Z_lval}{GEN x, ulong p} as \kbd{Z\_pval}, 2669except that \kbd{p} is an \kbd{ulong} ($\kbd{p} > 1$). 2670 2671\fun{long}{u_lvalrem}{ulong x, ulong p, ulong *r} as \kbd{Z\_pvalrem}, 2672except the inputs/outputs are now \kbd{ulong}s. 2673 2674\fun{long}{u_lvalrem_stop}{ulong *n, ulong p, int *stop} as 2675\kbd{Z\_pvalrem\_stop}. 2676 2677\fun{long}{u_pvalrem}{ulong x, GEN p, ulong *r} as \kbd{Z\_pvalrem}, 2678except \kbd{x} and \kbd{r} are now \kbd{ulong}s. 2679 2680\fun{long}{u_lval}{ulong x, ulong p} as \kbd{Z\_pval}, 2681except the inputs are now \kbd{ulong}s. 2682 2683\fun{long}{u_pval}{ulong x, GEN p} as \kbd{Z\_pval}, 2684except \kbd{x} is now an \kbd{ulong}. 2685 2686\fun{long}{z_lval}{long x, ulong p} as \kbd{u\_lval}, for signed \kbd{x}. 2687 2688\fun{long}{z_lvalrem}{long x, ulong p} as \kbd{u\_lvalrem}, for signed \kbd{x}. 2689 2690\fun{long}{z_pval}{long x, GEN p} as \kbd{Z\_pval}, 2691except \kbd{x} is now a \kbd{long}. 2692 2693\fun{long}{z_pvalrem}{long x, GEN p} as \kbd{Z\_pvalrem}, 2694except \kbd{x} is now a \kbd{long}. 2695 2696\fun{long}{factorial_lval}{ulong n, ulong p} returns $v_p(n!)$, assuming 2697$p$ is prime. 2698 2699The following convenience functions generalize \kbd{Z\_pval} and its variants 2700to ``containers'' (\kbd{ZV} and \kbd{ZX}): 2701 2702 2703\fun{long}{ZV_pvalrem}{GEN x, GEN p, GEN *r} $x$ being a \kbd{ZV} (a vector 2704of \typ{INT}s), return the min $v$ of the valuations of its components and 2705set \kbd{*r} to $x/p^v$. Infinite loop if $x$ is the zero vector. 2706This function is not stack clean. 2707 2708\fun{long}{ZV_pval}{GEN x, GEN p} as \kbd{ZV\_pvalrem} but only returns the 2709``valuation''. 2710 2711\fun{int}{ZV_Z_dvd}{GEN x, GEN p} returns $1$ if $p$ divides all components 2712of $x$ and $0$ otherwise. Faster than testing \kbd{ZV\_pval(x,p) >= 1}. 2713 2714\fun{long}{ZV_lvalrem}{GEN x, ulong p, GEN *px} as \kbd{ZV\_pvalrem}, 2715except that \kbd{p} is an \kbd{ulong} ($\kbd{p} > 1$). 2716This function is not stack-clean. 2717 2718\fun{long}{ZV_lval}{GEN x, ulong p} as \kbd{ZV\_pval}, 2719except that \kbd{p} is an \kbd{ulong} ($\kbd{p} > 1$). 2720 2721 2722\fun{long}{ZX_pvalrem}{GEN x, GEN p, GEN *r} as \kbd{ZV\_pvalrem}, for 2723a \kbd{ZX} $x$ (a \typ{POL} with \typ{INT} coefficients). 2724This function is not stack-clean. 2725 2726\fun{long}{ZX_pval}{GEN x, GEN p} as \kbd{ZV\_pval} for a \kbd{ZX} $x$. 2727 2728\fun{long}{ZX_lvalrem}{GEN x, ulong p, GEN *px} as \kbd{ZV\_lvalrem}, 2729a \kbd{ZX} $x$. 2730This function is not stack-clean. 2731 2732\fun{long}{ZX_lval}{GEN x, ulong p} as \kbd{ZX\_pval}, 2733except that \kbd{p} is an \kbd{ulong} ($\kbd{p} > 1$). 2734 2735\subsec{Generic unary operators} Let ``\op'' be a unary operation among 2736 2737\item \key{neg}: negation ($-x$). 2738 2739\item \key{abs}: absolute value ($|x|$). 2740 2741\item \key{sqr}: square ($x^2$). 2742 2743\noindent The names and prototypes of the low-level functions corresponding 2744to \op\ are as follows. The result is of the same type as~\kbd{x}. 2745 2746\funno{GEN}{\op i}{GEN x} creates the result of \op\ applied to the 2747\typ{INT}~\kbd{x}. 2748 2749\funno{GEN}{\op r}{GEN x} creates the result of \op\ applied to the 2750\typ{REAL}~\kbd{x}. 2751 2752\funno{GEN}{mp\op}{GEN x} creates the result of \op\ applied to the 2753\typ{INT} or \typ{REAL}~\kbd{x}. 2754 2755\noindent Complete list of available functions: 2756 2757\fun{GEN}{absi}{GEN x}, \fun{GEN}{absr}{GEN x}, \fun{GEN}{mpabs}{GEN x} 2758 2759\fun{GEN}{negi}{GEN x}, \fun{GEN}{negr}{GEN x}, \fun{GEN}{mpneg}{GEN x} 2760 2761\fun{GEN}{sqri}{GEN x}, \fun{GEN}{sqrr}{GEN x}, \fun{GEN}{mpsqr}{GEN x} 2762 2763\fun{GEN}{absi_shallow}{GEN x} $x$ being a \typ{INT}, returns a shallow copy of 2764$|x|$, in particular returns $x$ itself when $x \geq 0$, and \kbd{negi($x$)} 2765otherwise. 2766 2767\fun{GEN}{mpabs_shallow}{GEN x} $x$ being a \typ{INT} or a \typ{REAL}, returns 2768a shallow copy of $|x|$, in particular returns $x$ itself when $x \geq 0$, and 2769\kbd{mpneg($x$)} otherwise. 2770 2771 2772\noindent Some miscellaneous routines: 2773 2774\fun{GEN}{sqrs}{long x} returns $x^2$. 2775 2776\fun{GEN}{sqru}{ulong x} returns $x^2$. 2777 2778\subsec{Comparison operators} 2779 2780\fun{int}{cmpss}{long s, long t} compares the \kbd{long}~\kbd{s} to the 2781\typ{long}~\kbd{t}. 2782 2783\fun{int}{cmpuu}{ulong u, ulong v} compares the \kbd{ulong}~\kbd{u} to the 2784\typ{ulong}~\kbd{v}. 2785 2786\fun{long}{minss}{long x, long y} 2787 2788\fun{ulong}{minuu}{ulong x, ulong y} 2789 2790\fun{double}{mindd}{double x, double y} returns the \kbd{min} of $x$ and $y$. 2791 2792 2793\fun{long}{maxss}{long x, long y} 2794 2795\fun{ulong}{maxuu}{ulong x, ulong y} 2796 2797\fun{double}{maxdd}{double x, double y} returns the \kbd{max} of $x$ and $y$. 2798 2799\smallskip 2800 2801\fun{int}{mpcmp}{GEN x, GEN y} compares the \typ{INT} or \typ{REAL}~\kbd{x} 2802to the \typ{INT} or \typ{REAL}~\kbd{y}. The result is the sign of 2803$\kbd{x}-\kbd{y}$. 2804 2805\fun{int}{cmpii}{GEN x, GEN y} compares the \typ{INT} \kbd{x} to the 2806\typ{INT}~\kbd{y}. 2807 2808\fun{int}{cmpir}{GEN x, GEN y} compares the \typ{INT} \kbd{x} to the 2809\typ{REAL}~\kbd{y}. 2810 2811\fun{int}{cmpis}{GEN x, long s} compares the \typ{INT}~\kbd{x} to the 2812\kbd{long}~\kbd{s}. 2813 2814\fun{int}{cmpiu}{GEN x, ulong s} compares the \typ{INT}~\kbd{x} to the 2815\kbd{ulong}~\kbd{s}. 2816 2817\fun{int}{cmpsi}{long s, GEN x} compares the \kbd{long}~\kbd{s} to the 2818\typ{INT}~\kbd{x}. 2819 2820\fun{int}{cmpui}{ulong s, GEN x} compares the \kbd{ulong}~\kbd{s} to the 2821\typ{INT}~\kbd{x}. 2822 2823\fun{int}{cmpsr}{long s, GEN x} compares the \kbd{long}~\kbd{s} to the 2824\typ{REAL}~\kbd{x}. 2825 2826\fun{int}{cmpri}{GEN x, GEN y} compares the \typ{REAL}~\kbd{x} to the 2827\typ{INT}~\kbd{y}. 2828 2829\fun{int}{cmprr}{GEN x, GEN y} compares the \typ{REAL}~\kbd{x} to the 2830\typ{REAL}~\kbd{y}. 2831 2832\fun{int}{cmprs}{GEN x, long s} compares the \typ{REAL}~\kbd{x} to the 2833\kbd{long}~\kbd{s}. 2834 2835\fun{int}{equalii}{GEN x, GEN y} compares the \typ{INT}s \kbd{x} and~\kbd{y}. 2836The result is $1$ if $\kbd{x} = \kbd{y}$, $0$ otherwise. 2837 2838\fun{int}{equalrr}{GEN x, GEN y} compares the \typ{REAL}s \kbd{x} and~\kbd{y}. 2839The result is $1$ if $\kbd{x} = \kbd{y}$, $0$ otherwise. Equality is decided 2840according to the following rules: all real zeroes are equal, and 2841different from a nonzero real; two nonzero reals are equal if all their 2842digits coincide up to the length of the shortest of the two, and the 2843remaining words in the mantissa of the longest are all $0$. 2844 2845\fun{int}{equalis}{GEN x, long s} compare the \typ{INT} \kbd{x} and 2846the \kbd{long}~\kbd{s}. The result is $1$ if $\kbd{x} = \kbd{y}$, $0$ otherwise. 2847 2848\fun{int}{equalsi}{long s, GEN x} 2849 2850\fun{int}{equaliu}{GEN x, ulong s} compare the \typ{INT} \kbd{x} and 2851the \kbd{ulong}~\kbd{s}. The result is $1$ if $\kbd{x} = \kbd{y}$, $0$ 2852otherwise. 2853 2854\fun{int}{equalui}{ulong s, GEN x} 2855 2856The remaining comparison operators disregard the sign of their operands 2857 2858\fun{int}{absequaliu}{GEN x, ulong u} compare the absolute value of the 2859\typ{INT} \kbd{x} and the \kbd{ulong}~\kbd{s}. The result is $1$ if 2860$|\kbd{x}| = \kbd{y}$, $0$ otherwise. This is marginally more efficient 2861than \kbd{equalis} even when \kbd{x} is known to be nonnegative. 2862 2863\fun{int}{absequalui}{ulong u, GEN x} 2864 2865\fun{int}{abscmpiu}{GEN x, ulong u} compare the absolute value of the 2866\typ{INT} \kbd{x} and the \kbd{ulong}~\kbd{u}. 2867 2868\fun{int}{abscmpui}{ulong u, GEN x} 2869 2870 2871\fun{int}{abscmpii}{GEN x, GEN y} compares the \typ{INT}s \kbd{x} and~\kbd{y}. 2872The result is the sign of $|\kbd{x}| - |\kbd{y}|$. 2873 2874\fun{int}{absequalii}{GEN x, GEN y} compares the \typ{INT}s \kbd{x} 2875and~\kbd{y}. The result is $1$ if $|\kbd{x}| = |\kbd{y}|$, $0$ otherwise. 2876 2877\fun{int}{abscmprr}{GEN x, GEN y} compares the \typ{REAL}s \kbd{x} and~\kbd{y}. 2878The result is the sign of $|\kbd{x}| - |\kbd{y}|$. 2879 2880\fun{int}{absrnz_equal2n}{GEN x} tests whether a nonzero \typ{REAL} \kbd{x} 2881is equal to $\pm 2^e$ for some integer $e$. 2882 2883\fun{int}{absrnz_equal1}{GEN x} tests whether a nonzero \typ{REAL} \kbd{x} 2884is equal to $\pm 1$. 2885 2886\subsec{Generic binary operators}\label{se:genbinop} The operators in this 2887section have arguments of C-type \kbd{GEN}, \kbd{long}, and \kbd{ulong}, and 2888only \typ{INT} and \typ{REAL} \kbd{GEN}s are allowed. We say an argument is a 2889real type if it is a \typ{REAL} \kbd{GEN}, and an integer type otherwise. The 2890result is always a \typ{REAL} unless both \kbd{x} and \kbd{y} are integer 2891types. 2892 2893Let ``\op'' be a binary operation among 2894 2895\item \key{add}: addition (\kbd{x + y}). 2896 2897\item \key{sub}: subtraction (\kbd{x - y}). 2898 2899\item \key{mul}: multiplication (\kbd{x * y}). 2900 2901\item \key{div}: division (\kbd{x / y}). In the case where \kbd{x} and \kbd{y} 2902are both integer types, the result is the Euclidean quotient, where the 2903remainder has the same sign as the dividend~\kbd{x}. It is the ordinary 2904division otherwise. A division-by-$0$ error occurs if \kbd{y} is equal to 2905$0$. 2906 2907The last two generic operations are defined only when arguments have integer 2908types; and the result is a \typ{INT}: 2909 2910\item \key{rem}: remainder (``\kbd{x \% y}''). The result is the Euclidean 2911remainder corresponding to \kbd{div},~i.e. its sign is that of the 2912dividend~\kbd{x}. 2913 2914\item \key{mod}: true remainder (\kbd{x \% y}). The result is the true 2915Euclidean remainder, i.e.~nonnegative and less than the absolute value 2916of~\kbd{y}. 2917 2918\misctitle{Important technical note} The rules given above fixing the output 2919type (to \typ{REAL} unless both inputs are integer types) are subtly 2920incompatible with the general rules obeyed by PARI's generic functions, such 2921as \kbd{gmul} or \kbd{gdiv} for instance: the latter return a result 2922containing as much information as could be deduced from the inputs, so it is 2923not true that if $x$ is a \typ{INT} and $y$ a \typ{REAL}, then 2924\kbd{gmul(x,y)} is always the same as \kbd{mulir(x,y)}. The exception 2925is $x = 0$, in that case we can deduce that the result is an exact $0$, 2926so \kbd{gmul} returns \kbd{gen\_0}, while \kbd{mulir} returns a 2927\typ{REAL} $0$. Specifically, the one resulting from the conversion of 2928\kbd{gen\_0} to a \typ{REAL} of precision \kbd{precision(y)}, multiplied by 2929$y$; this determines the exponent of the real $0$ we obtain. 2930 2931The reason for the discrepancy between the two rules is that we use the two 2932sets of functions in different contexts: generic functions allow to write 2933high-level code forgetting about types, letting PARI return results which are 2934sensible and as simple as possible; type specific functions are used in 2935kernel programming, where we do care about types and need to maintain strict 2936consistency: it is much easier to compute the types of results when they are 2937determined from the types of the inputs only (without taking into account 2938further arithmetic properties, like being nonzero). 2939\smallskip 2940 2941The names and prototypes of the low-level functions corresponding 2942to \op\ are as follows. In this section, the \kbd{z} argument in the 2943\kbd{z}-functions must be of type \typ{INT} when no \kbd{r} or \kbd{mp} 2944appears in the argument code (no \typ{REAL} operand is involved, only integer 2945types), and of type \typ{REAL} otherwise. 2946 2947\funno{GEN}{mp\op[z]}{GEN x, GEN y[, GEN z]} applies \op\ to 2948the \typ{INT} or \typ{REAL} \kbd{x} and~\kbd{y}. The function 2949\kbd{mpdivz} does not exist (its semantic would change drastically 2950depending on the type of the \kbd{z} argument), and neither do 2951\kbd{mprem[z]} nor \kbd{mpmod[z]} (specific to integers). 2952 2953\funno{GEN}{\op si[z]}{long s, GEN x[, GEN z]} applies \op\ to the 2954\kbd{long}~\kbd{s} and the \typ{INT}~\kbd{x}. 2955 These functions always return the global constant 2956\kbd{gen\_0} (not a copy) when the sign of the result is $0$. 2957 2958\funno{GEN}{\op sr[z]}{long s, GEN x[, GEN z]} applies \op\ to the 2959\kbd{long}~\kbd{s} and the \typ{REAL}~\kbd{x}. 2960 2961\funno{GEN}{\op ss[z]}{long s, long t[, GEN z]} applies \op\ to the longs 2962\kbd{s} and~\kbd{t}. These functions always return the global constant 2963\kbd{gen\_0} (not a copy) when the sign of the result is $0$. 2964 2965\funno{GEN}{\op ii[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the 2966\typ{INT}s \kbd{x} and~\kbd{y}. These functions always return the global 2967constant \kbd{gen\_0} (not a copy) when the sign of the result is $0$. 2968 2969\funno{GEN}{\op ir[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the 2970\typ{INT} \kbd{x} and the \typ{REAL}~\kbd{y}. 2971 2972\funno{GEN}{\op is[z]}{GEN x, long s[, GEN z]} applies \op\ to the 2973\typ{INT}~\kbd{x} and the \kbd{long}~\kbd{s}. These functions always return 2974the global constant \kbd{gen\_0} (not a copy) when the sign of the result 2975is $0$. 2976 2977\funno{GEN}{\op ri[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the 2978\typ{REAL}~\kbd{x} and the \typ{INT}~\kbd{y}. 2979 2980\funno{GEN}{\op rr[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the 2981\typ{REAL}s~\kbd{x} and~\kbd{y}. 2982 2983\funno{GEN}{\op rs[z]}{GEN x, long s[, GEN z]} applies \op\ to the 2984\typ{REAL}~\kbd{x} and the \kbd{long}~\kbd{s}. 2985 2986\noindent Some miscellaneous routines: 2987 2988\fun{long}{expu}{ulong x} assuming $x > 0$, returns the binary exponent of 2989the real number equal to $x$. This is a special case of \kbd{gexpo}. 2990 2991\fun{GEN}{adduu}{ulong x, ulong y} 2992 2993\fun{GEN}{addiu}{GEN x, ulong y} 2994 2995\fun{GEN}{addui}{ulong x, GEN y} adds \kbd{x} and \kbd{y}. 2996 2997\fun{GEN}{subuu}{ulong x, ulong y} 2998 2999\fun{GEN}{subiu}{GEN x, ulong y} 3000 3001\fun{GEN}{subui}{ulong x, GEN y} subtracts \kbd{x} by \kbd{y}. 3002 3003\fun{GEN}{muluu}{ulong x, ulong y} multiplies \kbd{x} by \kbd{y}. 3004 3005\fun{ulong}{umuluu_le}{ulong x, ulong y, ulong n} multiplies \kbd{x} by \kbd{y}. 3006Return $xy$ if $xy \leq n$ and $0$ otherwise (in particular if $xy$ does not 3007fit in an \kbd{ulong}). 3008 3009\fun{ulong}{umuluu_or_0}{ulong x, ulong y} multiplies \kbd{x} by \kbd{y}. 3010Return $0$ if $xy$ does not fit in an \kbd{ulong}. 3011 3012\fun{GEN}{mului}{ulong x, GEN y} multiplies \kbd{x} by \kbd{y}. 3013 3014\fun{GEN}{muluui}{ulong x, ulong y, GEN z} return $xyz$. 3015 3016\fun{GEN}{muliu}{GEN x, ulong y} multiplies \kbd{x} by \kbd{y}. 3017 3018\fun{void}{addumului}{ulong a, ulong b, GEN x} return $a + b|X|$. 3019 3020\fun{GEN}{addmuliu}{GEN x, GEN y, ulong u} returns $x +yu$. 3021 3022\fun{GEN}{addmulii}{GEN x, GEN y, GEN z} returns $x + yz$. 3023 3024\fun{GEN}{addmulii_inplace}{GEN x, GEN y, GEN z} returns $x + yz$, but 3025returns $x$ itself and not a copy if $yz = 0$. Not suitable for 3026\tet{gerepile} or \tet{gerepileupto}. 3027 3028\fun{GEN}{addmuliu_inplace}{GEN x, GEN y, ulong u} returns $x +yu$, but 3029returns $x$ itself and not a copy if $yu = 0$. Not suitable for 3030\tet{gerepile} or \tet{gerepileupto}. 3031 3032\fun{GEN}{submuliu_inplace}{GEN x, GEN y, ulong u} returns $x- yu$, but 3033returns $x$ itself and not a copy if $yu = 0$. Not suitable for 3034\tet{gerepile} or \tet{gerepileupto}. 3035 3036\fun{GEN}{lincombii}{GEN u, GEN v, GEN x, GEN y} returns $ux + vy$. 3037 3038\fun{GEN}{mulsubii}{GEN y, GEN z, GEN x} returns $yz - x$. 3039 3040\fun{GEN}{submulii}{GEN x, GEN y, GEN z} returns $x - yz$. 3041 3042\fun{GEN}{submuliu}{GEN x, GEN y, ulong u} returns $x -yu$. 3043 3044\fun{GEN}{mulu_interval}{ulong a, ulong b} returns $a(a+1)\cdots b$, assuming 3045that $a \leq b$. 3046 3047\fun{GEN}{mulu_interval_step}{ulong a, ulong b, ulong s} returns the product 3048of all integers in $[a,b]$ congruent to $a$ modulo $s$. Assume $a\leq b$ and 3049$s > 0$; 3050 3051\fun{GEN}{muls_interval}{long a, long b} returns $a(a+1)\cdots b$, assuming 3052that $a \leq b$. 3053 3054\fun{GEN}{invr}{GEN x} returns the inverse of the nonzero \typ{REAL}~$x$. 3055 3056\fun{GEN}{truedivii}{GEN x, GEN y} returns the true Euclidean quotient 3057(with nonnegative remainder less than $|y|$). 3058 3059\fun{GEN}{truedivis}{GEN x, long y} returns the true Euclidean quotient 3060(with nonnegative remainder less than $|y|$). 3061 3062\fun{GEN}{truedivsi}{long x, GEN y} returns the true Euclidean quotient 3063(with nonnegative remainder less than $|y|$). 3064 3065\fun{GEN}{centermodii}{GEN x, GEN y, GEN y2}, given 3066\typ{INT}s \kbd{x}, \kbd{y}, returns $z$ congruent to \kbd{x} modulo \kbd{y}, 3067such that $-\kbd{y}/2 \leq z < \kbd{y}/2$. The function requires an extra 3068argument \kbd{y2}, such that \kbd{y2 = shifti(y, -1)}. (In most cases, \kbd{y} 3069is constant for many reductions and \kbd{y2} need only be computed once.) 3070 3071\fun{GEN}{remi2n}{GEN x, long n} returns \kbd{x} mod $2^n$. 3072 3073\fun{GEN}{addii_sign}{GEN x, long sx, GEN y, long sy} add the \typ{INT}s 3074$x$ and $y$ as if their signs were \kbd{sx} and \kbd{sy}. 3075 3076\fun{GEN}{addir_sign}{GEN x, long sx, GEN y, long sy} 3077add the \typ{INT} $x$ and the \typ{REAL} $y$ as if their signs were \kbd{sx} 3078and \kbd{sy}. 3079 3080\fun{GEN}{addrr_sign}{GEN x, long sx, GEN y, long sy} add the \typ{REAL}s $x$ 3081and $y$ as if their signs were \kbd{sx} and \kbd{sy}. 3082 3083\fun{GEN}{addsi_sign}{long x, GEN y, long sy} add $x$ and the \typ{INT} $y$ 3084as if its sign was \kbd{sy}. 3085 3086\fun{GEN}{addui_sign}{ulong x, GEN y, long sy} add $x$ and the \typ{INT} $y$ 3087as if its sign was \kbd{sy}. 3088 3089\subsec{Exact division and divisibility} 3090 3091\fun{GEN}{diviiexact}{GEN x, GEN y} returns the Euclidean quotient 3092$\kbd{x} / \kbd{y}$, assuming $\kbd{y}$ divides $\kbd{x}$. Uses Jebelean 3093algorithm (Jebelean-Krandick bidirectional exact division is not 3094implemented). 3095 3096\fun{GEN}{diviuexact}{GEN x, ulong y} returns the Euclidean quotient 3097$\kbd{x} / \kbd{y}$, assuming $\kbd{y}$ divides 3098$\kbd{x}$ and $\kbd{y}$ is nonzero. 3099 3100\fun{GEN}{diviuuexact}{GEN x, ulong y, ulong z} returns the Euclidean 3101quotient $x/(yz)$, assuming $yz$ divides $x$ and $yz \neq 0$. 3102 3103The following routines return 1 (true) if \kbd{y} divides \kbd{x}, and 31040 otherwise. All \kbd{GEN} are assumed to be \typ{INT}s: 3105 3106\fun{int}{dvdii}{GEN x, GEN y}, 3107\fun{int}{dvdis}{GEN x, long y}, 3108\fun{int}{dvdiu}{GEN x, ulong y}, 3109 3110\fun{int}{dvdsi}{long x, GEN y}, 3111\fun{int}{dvdui}{ulong x, GEN y}. 3112 3113The following routines return 1 (true) if \kbd{y} divides \kbd{x}, and in 3114that case assign the quotient to \kbd{z}; otherwise they return 0. All 3115\kbd{GEN} are assumed to be \typ{INT}s: 3116 3117\fun{int}{dvdiiz}{GEN x, GEN y, GEN z}, 3118\fun{int}{dvdisz}{GEN x, long y, GEN z}. 3119 3120\fun{int}{dvdiuz}{GEN x, ulong y, GEN z} if \kbd{y} divides \kbd{x}, assigns 3121the quotient $|\kbd{x}|/\kbd{y}$ to \kbd{z} and returns 1 (true), otherwise 3122returns 0 (false). 3123 3124\subsec{Division with integral operands and \typ{REAL} result} 3125 3126\fun{GEN}{rdivii}{GEN x, GEN y, long prec}, assuming $x$ and $y$ 3127are both of type \typ{INT}, return the quotient $x/y$ as a \typ{REAL} of 3128precision \kbd{prec}. 3129 3130\fun{GEN}{rdiviiz}{GEN x, GEN y, GEN z}, assuming $x$ and $y$ 3131are both of type \typ{INT}, and $z$ is a \typ{REAL}, 3132assign the quotient $x/y$ to $z$. 3133 3134\fun{GEN}{rdivis}{GEN x, long y, long prec}, assuming \kbd{x} 3135is of type \typ{INT}, return the quotient x/y as a \typ{REAL} of 3136precision \kbd{prec}. 3137 3138\fun{GEN}{rdivsi}{long x, GEN y, long prec}, assuming \kbd{y} 3139is of type \typ{INT}, return the quotient x/y as a \typ{REAL} of 3140precision \kbd{prec}. 3141 3142\fun{GEN}{rdivss}{long x, long y, long prec}, return the quotient x/y as a 3143\typ{REAL} of precision \kbd{prec}. 3144 3145 3146\subsec{Division with remainder} The following functions return two objects, 3147unless specifically asked for only one of them~--- a quotient and a remainder. 3148The quotient is returned and the remainder is returned through the variable 3149whose address is passed as the \kbd{r} argument. The term \emph{true 3150Euclidean remainder} refers to the nonnegative one (\kbd{mod}), and 3151\emph{Euclidean remainder} by itself to the one with the same sign as the 3152dividend (\kbd{rem}). All \kbd{GEN}s, whether returned directly or through a 3153pointer, are created on the stack. 3154 3155\fun{GEN}{dvmdii}{GEN x, GEN y, GEN *r} returns the Euclidean quotient of the 3156\typ{INT}~\kbd{x} by a \typ{INT}~\kbd{y} and puts the remainder 3157into~\kbd{*r}. If \kbd{r} is equal to \kbd{NULL}, the remainder is not 3158created, and if \kbd{r} is equal to \kbd{ONLY\_REM}, only the remainder is 3159created and returned. In the generic case, the remainder is created after the 3160quotient and can be disposed of individually with a \kbd{cgiv(r)}. The 3161remainder is always of the sign of the dividend~\kbd{x}. If the remainder 3162is $0$ set \kbd{r = gen\_0}. 3163 3164\fun{void}{dvmdiiz}{GEN x, GEN y, GEN z, GEN t} assigns the Euclidean 3165quotient of the \typ{INT}s \kbd{x} and \kbd{y} into the \typ{INT}~\kbd{z}, 3166and the Euclidean remainder into the \typ{INT}~\kbd{t}. 3167 3168\noindent Analogous routines \tet{dvmdis}\kbd{[z]}, \tet{dvmdsi}\kbd{[z]}, 3169\tet{dvmdss}\kbd{[z]} are available, where \kbd{s} denotes a \kbd{long} 3170argument. But the following routines are in general more flexible: 3171 3172\fun{long}{sdivss_rem}{long s, long t, long *r} computes the Euclidean 3173quotient and remainder of the longs \kbd{s} and~\kbd{t}. Puts the remainder 3174into \kbd{*r}, and returns the quotient. The remainder is of the sign of the 3175dividend~\kbd{s}, and has strictly smaller absolute value than~\kbd{t}. 3176 3177\fun{long}{sdivsi_rem}{long s, GEN x, long *r} computes the Euclidean 3178quotient and remainder of the \kbd{long}~\kbd{s} by the \typ{INT}~\kbd{x}. As 3179\kbd{sdivss\_rem} otherwise. 3180 3181\fun{long}{sdivsi}{long s, GEN x} as \kbd{sdivsi\_rem}, without 3182remainder. 3183 3184\fun{GEN}{divis_rem}{GEN x, long s, long *r} computes the Euclidean quotient 3185and remainder of the \typ{INT}~\kbd{x} by the \kbd{long}~\kbd{s}. As 3186\kbd{sdivss\_rem} otherwise. 3187 3188\fun{GEN}{absdiviu_rem}{GEN x, ulong s, ulong *r} computes the Euclidean quotient 3189and remainder of \emph{absolute value} of the \typ{INT}~\kbd{x} by the 3190\kbd{ulong}~\kbd{s}. As \kbd{sdivss\_rem} otherwise. 3191 3192\fun{ulong}{uabsdiviu_rem}{GEN n, ulong d, ulong *r} as \tet{absdiviu_rem}, assuming 3193that $|n|/d$ fits into an \kbd{ulong}. 3194 3195\fun{ulong}{uabsdivui_rem}{ulong x, GEN y, ulong *rem} 3196computes the Euclidean quotient and remainder of $x$ by $|y|$. As 3197\kbd{sdivss\_rem} otherwise. 3198 3199\fun{ulong}{udivuu_rem}{ulong x, ulong y, ulong *rem} 3200computes the Euclidean quotient and remainder of $x$ by $y$. As 3201\kbd{sdivss\_rem} otherwise. 3202 3203\fun{ulong}{ceildivuu}{ulong x, ulong y} return the ceiling of $x / y$. 3204 3205\fun{GEN}{divsi_rem}{long s, GEN y, long *r} computes the Euclidean quotient 3206and remainder of the \kbd{long}~\kbd{s} by the \kbd{GEN}~\kbd{y}. As 3207\kbd{sdivss\_rem} otherwise. 3208 3209\fun{GEN}{divss_rem}{long x, long y, long *r} computes the Euclidean quotient 3210and remainder of the \kbd{long}~\kbd{x} by the \kbd{long}~\kbd{y}. As 3211\kbd{sdivss\_rem} otherwise. 3212\smallskip 3213\fun{GEN}{truedvmdii}{GEN x, GEN y, GEN *r}, as \kbd{dvmdii} but with a 3214nonnegative remainder. 3215 3216\fun{GEN}{truedvmdis}{GEN x, long y, GEN *z}, as \kbd{dvmdis} but with a 3217nonnegative remainder. 3218 3219\fun{GEN}{truedvmdsi}{long x, GEN y, GEN *z}, as \kbd{dvmdsi} but with a 3220nonnegative remainder. 3221 3222\subsec{Modulo to longs} The following variants of \kbd{modii} do not 3223clutter the stack: 3224 3225\fun{long}{smodis}{GEN x, long y} computes the true Euclidean 3226remainder of the \typ{INT}~\kbd{x} by the \kbd{long}~\kbd{y}. This is the 3227nonnegative remainder, not the one whose sign is the sign of \kbd{x} 3228as in the \kbd{div} functions. 3229 3230\fun{long}{smodss}{long x, long y} computes the true Euclidean 3231remainder of the \kbd{long}~\kbd{x} by a \kbd{long}~\kbd{y}. 3232 3233\fun{ulong}{umodsu}{long x, ulong y} computes the true Euclidean 3234remainder of the \kbd{long}~\kbd{x} by a \kbd{ulong}~\kbd{y}. 3235 3236\fun{ulong}{umodiu}{GEN x, ulong y} computes the true Euclidean 3237remainder of the \typ{INT}~\kbd{x} by the \kbd{ulong}~\kbd{y}. 3238 3239\fun{ulong}{umodui}{ulong x, GEN y} computes the true Euclidean 3240remainder of the \kbd{ulong}~\kbd{x} by the \typ{INT}~\kbd{|y|}. 3241 3242The routine \tet{smodsi} does not exist, since it would not always be 3243defined: for a \emph{negative} \kbd{x}, if the quotient is $\pm1$, the result 3244\kbd{x + |y|} would in general not fit into a \kbd{long}. Use either 3245\kbd{umodui} or \kbd{modsi}. 3246 3247These functions directly access the binary data and are thus much faster than 3248the generic modulo functions: 3249 3250\fun{int}{mpodd}{GEN x} which is 1 if \kbd{x} is odd, and 0 otherwise. 3251 3252\fun{ulong}{Mod2}{GEN x} 3253 3254\fun{ulong}{Mod4}{GEN x} 3255 3256\fun{ulong}{Mod8}{GEN x} 3257 3258\fun{ulong}{Mod16}{GEN x} 3259 3260\fun{ulong}{Mod32}{GEN x} 3261 3262\fun{ulong}{Mod64}{GEN x} give the residue class of $x$ modulo the 3263corresponding power of $2$. 3264 3265\fun{ulong}{umodi2n}{GEN x, long n} give the residue class of $x$ modulo 3266$2^n$, $0 \leq n < BITS\_IN\_LONG$. 3267 3268The following functions assume that $x\neq 0$ and in fact disregard the 3269sign of $x$. There are about $10\%$ faster than the safer variants above: 3270 3271\fun{long}{mod2}{GEN x} 3272 3273\fun{long}{mod4}{GEN x} 3274 3275\fun{long}{mod8}{GEN x} 3276 3277\fun{long}{mod16}{GEN x} 3278 3279\fun{long}{mod32}{GEN x} 3280 3281\fun{long}{mod64}{GEN x} give the residue class of $|x|$ modulo the 3282corresponding power of 2, for \emph{nonzero}~\kbd{x}. As well, 3283 3284\fun{ulong}{mod2BIL}{GEN x} returns the least significant word of $|x|$, still 3285assuming that $x\neq 0$. 3286 3287\subsec{Powering, Square root} 3288 3289\fun{GEN}{powii}{GEN x, GEN n}, assumes $x$ and $n$ are \typ{INT}s and 3290returns $x^n$. 3291 3292\fun{GEN}{powuu}{ulong x, ulong n}, returns $x^n$. 3293 3294\fun{GEN}{powiu}{GEN x, ulong n}, assumes $x$ is a \typ{INT} and returns $x^n$. 3295 3296\fun{GEN}{powis}{GEN x, long n}, assumes $x$ is a \typ{INT} and returns $x^n$ 3297(possibly a \typ{FRAC} if $n < 0$). 3298 3299\fun{GEN}{powrs}{GEN x, long n}, assumes $x$ is a \typ{REAL} and returns 3300$x^n$. This is considered as a sequence of \kbd{mulrr}, possibly empty: 3301as such the result has type \typ{REAL}, even if $n = 0$. 3302Note that the generic function \kbd{gpowgs(x,0)} would return \kbd{gen\_1}, 3303see the technical note in \secref{se:genbinop}. 3304 3305\fun{GEN}{powru}{GEN x, ulong n}, assumes $x$ is a \typ{REAL} and returns $x^n$ 3306(always a \typ{REAL}, even if $n = 0$). 3307 3308\fun{GEN}{powersr}{GEN e, long n}. Given a \typ{REAL} $e$, return the vector 3309$v$ of all $e^i$, $0 \leq i \leq n$, where $v[i] = e^{i-1}$. 3310 3311\fun{GEN}{powrshalf}{GEN x, long n}, assumes $x$ is a \typ{REAL} and returns 3312$x^{n/2}$ (always a \typ{REAL}, even if $n = 0$). 3313 3314\fun{GEN}{powruhalf}{GEN x, ulong n}, assumes $x$ is a \typ{REAL} and returns 3315$x^{n/2}$ (always a \typ{REAL}, even if $n = 0$). 3316 3317\fun{GEN}{powrfrac}{GEN x, long n, long d}, assumes $x$ is a \typ{REAL} and 3318returns $x^{n/d}$ (always a \typ{REAL}, even if $n = 0$). 3319 3320\fun{GEN}{powIs}{long n} returns $I^n\in\{1,I,-1,-I\}$ (\typ{INT} for even $n$, 3321\typ{COMPLEX} otherwise). 3322 3323\fun{ulong}{upowuu}{ulong x, ulong n}, returns $x^n$ when $< 2^\B$, and $0$ 3324otherwise (overflow). 3325 3326\fun{ulong}{upowers}{ulong x, long n}, returns $[1,x,\ldots,x^n]$ as a 3327\typ{VECSMALL}. Assume there is no overflow. 3328 3329\fun{GEN}{sqrtremi}{GEN N, GEN *r}, returns the integer square root $S$ of 3330the nonnegative \typ{INT}~\kbd{N} (rounded towards 0) and puts the remainder 3331$R$ into~\kbd{*r}. Precisely, $N = S^2 + R$ with $0\leq R \leq 2S$. If 3332\kbd{r} is equal to \kbd{NULL}, the remainder is not created. In the generic 3333case, the remainder is created after the quotient and can be disposed of 3334individually with \kbd{cgiv(R)}. If the remainder is $0$ set \kbd{R = gen\_0}. 3335 3336Uses a divide and conquer algorithm (discrete variant of Newton iteration) 3337due to Paul Zimmermann (``Karatsuba Square Root'', INRIA Research Report 3805 3338(1999)). 3339 3340\fun{GEN}{sqrti}{GEN N}, returns the integer square root $S$ of 3341the nonnegative \typ{INT}~\kbd{N} (rounded towards 0). This is identical 3342to \kbd{sqrtremi(N, NULL)}. 3343 3344\fun{long}{logintall}{GEN B, GEN y, GEN *ptq} 3345returns the floor $e$ of $\log_y B$, where $B > 0$ and $y > 1$ are integers. 3346If \kbd{ptq} is not \kbd{NULL}, set it to $y^e$. (Analogous to \kbd{logint0}, 3347whithout sanity checks.) 3348 3349\fun{ulong}{ulogintall}{ulong B, ulong y, ulong *ptq} as \kbd{logintall} for 3350\kbd{ulong} arguments. 3351 3352\fun{long}{logint}{GEN B, GEN y} returns the floor $e$ of $\log_y B$, where 3353$B > 0$ and $y > 1$ are integers. 3354 3355\fun{ulong}{ulogint}{ulong B, ulong y} as \kbd{logint} for 3356\kbd{ulong} arguments. 3357 3358\fun{GEN}{vecpowuu}{long N, ulong a} return the vector of $n^a$, $n = 1, 3359\dots, N$. Not memory clean. 3360 3361\fun{GEN}{vecpowug}{long N, GEN a, long prec} return the vector of $n^a$, $n 3362= 1, \dots, N$, where the powers are computed at precision \kbd{prec}. Not 3363memory clean. 3364 3365\subsec{GCD, extended GCD and LCM} 3366 3367\fun{long}{cgcd}{long x, long y} returns the GCD of \kbd{x} and \kbd{y}. 3368 3369\fun{ulong}{ugcd}{ulong x, ulong y} returns the GCD of \kbd{x} and \kbd{y}. 3370 3371\fun{ulong}{ugcdiu}{GEN x, ulong y} returns the GCD of \kbd{x} and \kbd{y}. 3372 3373\fun{ulong}{ugcdui}{ulong x, GEN y} returns the GCD of \kbd{x} and \kbd{y}. 3374 3375\fun{GEN}{coprimes_zv}{ulong N} return a \typ{VECSMALL} $T$ with $N$ entries 3376such that $T[i] = 1$ iff $(i,N) = 1$ and $0$ otherwise. 3377 3378\fun{long}{clcm}{long x, long y} returns the LCM of \kbd{x} and \kbd{y}, 3379provided it fits into a \kbd{long}. Silently overflows otherwise. 3380 3381\fun{ulong}{ulcm}{ulong x, ulong y} returns the LCM of \kbd{x} and \kbd{y}, 3382provided it fits into an \kbd{ulong}. Silently overflows otherwise. 3383 3384\fun{GEN}{gcdii}{GEN x, GEN y}, returns the GCD of the \typ{INT}s \kbd{x} and 3385\kbd{y}. 3386 3387\fun{GEN}{lcmii}{GEN x, GEN y}, returns the LCM of the \typ{INT}s \kbd{x} and 3388\kbd{y}. 3389 3390\fun{GEN}{bezout}{GEN a,GEN b, GEN *u,GEN *v}, returns the GCD $d$ of 3391\typ{INT}s \kbd{a} and \kbd{b} and sets \kbd{u}, \kbd{v} to the Bezout 3392coefficients such that $\kbd{au} + \kbd{bv} = d$. 3393 3394\fun{long}{cbezout}{long a,long b, long *u,long *v}, returns the GCD 3395$d$ of \kbd{a} and \kbd{b} and sets \kbd{u}, \kbd{v} to the Bezout coefficients 3396such that $\kbd{au} + \kbd{bv} = d$. 3397 3398\fun{GEN}{halfgcdii}{GEN x, GEN y} 3399assuming \kbd{x} and \kbd{y} are \typ{INT}s, 3400returns a $2$-components \typ{VEC} $[M,V]$ where $M$ is a $2\times 2$ 3401\typ{MAT} and $V$ a $2$-component \typ{COL}, both with \typ{INT} entries, 3402such that $M*[x,y]~==V$ and such that if $V=[a,b]~$, then 3403$a \geq \ceil{\sqrt{\max(|x|,|y|)}} > b$. 3404 3405\fun{GEN}{ZV_extgcd}{GEN A} given a vector of $n$ integers $A$, returns $[d, 3406U]$, where $d$ is the GCD of the $A[i]$ and $U$ is a matrix 3407in $\text{GL}_n(\Z)$ such that $AU = [0,\dots,0,D]$. 3408 3409\fun{GEN}{ZV_lcm}{GEN v} given a vector $v$ of integers 3410returns the LCM of its entries. 3411 3412\fun{GEN}{ZV_snf_gcd}{GEN v, GEN N} given a vector $v$ of integers and a 3413positive integer $N$, return the vector whose entries are the gcds 3414$(v[i],N)$. Use case: if $v$ gives the cyclic components for some Abelian 3415group $G$ of finite type, then this returns the structure of the finite 3416groupe $G/G^N$. 3417 3418\subsec{Continued fractions and convergents} 3419 3420\fun{GEN}{ZV_allpnqn}{GEN x} given $x = [a_0, ..., a_n]$ a 3421continued fraction from \tet{gboundcf}, $n\geq0$, return all 3422convergents as $[P,Q]$, where $P = [p_0,\dots,p_n]$ and $Q = 3423[q_0,\dots,q_n]$. 3424 3425\subsec{Pseudo-random integers} 3426These routine return pseudo-random integers uniformly distributed in some 3427interval. The all use the same underlying generator which can be seeded and 3428restarted using \tet{getrand} and \tet{setrand}. 3429 3430\fun{void}{setrand}{GEN seed} reseeds the random number generator using the 3431seed $n$. The seed is either a technical array output by \kbd{getrand} 3432or a small positive integer, used to generate deterministically a suitable 3433state array. For instance, running a randomized computation starting by 3434\kbd{setrand(1)} twice will generate the exact same output. 3435 3436\fun{GEN}{getrand}{void} returns the current value of the seed used by the 3437pseudo-random number generator \tet{random}. Useful mainly for debugging 3438purposes, to reproduce a specific chain of computations. The returned value 3439is technical (reproduces an internal state array of type \typ{VECSMALL}), 3440and can only be used as an argument to \tet{setrand}. 3441 3442\fun{ulong}{pari_rand}{void} returns a random $0 \leq x < 2^\B$. 3443 3444\fun{long}{random_bits}{long k} returns a random $0 \leq x < 2^k$. Assumes 3445that $0 \leq k \leq \B$. 3446 3447\fun{ulong}{random_Fl}{ulong p} returns a pseudo-random integer 3448in $0, 1, \dots p-1$. 3449 3450\fun{GEN}{randomi}{GEN n} returns a random \typ{INT} between $0$ and $\kbd{n} 3451- 1$. 3452 3453\fun{GEN}{randomr}{long prec} returns a random \typ{REAL} in $[0,1[$, with 3454precision \kbd{prec}. 3455 3456\subsec{Modular operations} In this subsection, all \kbd{GEN}s are 3457\typ{INT}. 3458 3459\fun{GEN}{Fp_red}{GEN a, GEN m} returns \kbd{a} modulo \kbd{m} (smallest 3460nonnegative residue). (This is identical to modii). 3461 3462\fun{GEN}{Fp_neg}{GEN a, GEN m} returns $-$\kbd{a} modulo \kbd{m} (smallest 3463nonnegative residue). 3464 3465\fun{GEN}{Fp_add}{GEN a, GEN b, GEN m} returns the sum of \kbd{a} and 3466\kbd{b} modulo \kbd{m} (smallest nonnegative residue). 3467 3468\fun{GEN}{Fp_sub}{GEN a, GEN b, GEN m} returns the difference of \kbd{a} and 3469\kbd{b} modulo \kbd{m} (smallest nonnegative residue). 3470 3471\fun{GEN}{Fp_center}{GEN a, GEN p, GEN pov2} assuming that \kbd{pov2} is 3472\kbd{shifti(p,-1)} and that $-p/2 < a < p$, returns the representative of 3473\kbd{a} in the symmetric residue system $]-p/2,p/2]$. 3474 3475\fun{GEN}{Fp_center_i}{GEN a, GEN p, GEN pov2} internal variant of 3476\tet{Fp_center}, not \kbd{gerepile}-safe: when $a$ is already in the 3477proper interval, it is returned as is, without a copy. 3478 3479\fun{GEN}{Fp_mul}{GEN a, GEN b, GEN m} returns the product of \kbd{a} by 3480\kbd{b} modulo \kbd{m} (smallest nonnegative residue). 3481 3482\fun{GEN}{Fp_addmul}{GEN x, GEN y, GEN z, GEN p} returns $x + y\*z$. 3483 3484\fun{GEN}{Fp_mulu}{GEN a, ulong b, GEN m} returns the product of \kbd{a} by 3485\kbd{b} modulo \kbd{m} (smallest nonnegative residue). 3486 3487\fun{GEN}{Fp_muls}{GEN a, long b, GEN m} returns the product of \kbd{a} by 3488\kbd{b} modulo \kbd{m} (smallest nonnegative residue). 3489 3490\fun{GEN}{Fp_halve}{GEN x, GEN m} returns $z$ such that $2\*z = x$ modulo 3491$m$ assuming such $z$ exists. 3492 3493\fun{GEN}{Fp_sqr}{GEN a, GEN m} returns $\kbd{a}^2$ modulo \kbd{m} (smallest 3494nonnegative residue). 3495 3496\fun{ulong}{Fp_powu}{GEN x, ulong n, GEN m} raises \kbd{x} to the \kbd{n}-th 3497power modulo \kbd{m} (smallest nonnegative residue). Not memory-clean, but 3498suitable for \kbd{gerepileupto}. 3499 3500\fun{ulong}{Fp_pows}{GEN x, long n, GEN m} raises \kbd{x} to the \kbd{n}-th 3501power modulo \kbd{m} (smallest nonnegative residue). A negative \kbd{n} is 3502allowed Not memory-clean, but suitable for \kbd{gerepileupto}. 3503 3504\fun{GEN}{Fp_pow}{GEN x, GEN n, GEN m} returns $\kbd{x}^\kbd{n}$ 3505modulo \kbd{m} (smallest nonnegative residue). 3506 3507\fun{GEN}{Fp_pow_init}{GEN x, GEN n, long k, GEN p} 3508Return a table \kbd{R} that can be used with 3509\kbd{Fp\_pow\_table} to compute the powers of $x$ up to $n$. 3510The table is of size $2^k\*\log_2(n)$. 3511 3512\fun{GEN}{Fp_pow_table}{GEN R, GEN n, GEN p} 3513return $x^n$, where $R$ is given by \kbd{Fp\_pow\_init(x,m,k,p)} 3514for some integer $m\geq n$. 3515 3516\fun{GEN}{Fp_powers}{GEN x, long n, GEN m} returns 3517$[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ modulo \kbd{m} as a \typ{VEC} 3518 (smallest nonnegative residue). 3519 3520\fun{GEN}{Fp_inv}{GEN a, GEN m} returns an inverse of \kbd{a} modulo \kbd{m} 3521(smallest nonnegative residue). Raise an error if \kbd{a} is not invertible. 3522 3523\fun{GEN}{Fp_invsafe}{GEN a, GEN m} as \kbd{Fp\_inv}, but return 3524\kbd{NULL} if \kbd{a} is not invertible. 3525 3526\fun{GEN}{Fp_invgen}{GEN x, GEN m, GEN *pg} set \kbd{*pg} to 3527$g = \gcd(x,m)$ and return $u$ in $(\Z/m\Z)^*$ such that $x u = g$ modulo $m$. 3528We have $g = 1$ if and only if $x$ is invertible, and in this case $u$ 3529is its inverse. 3530 3531\fun{GEN}{FpV_prod}{GEN x, GEN p} returns the product of the components of 3532$x$. 3533 3534\fun{GEN}{FpV_inv}{GEN x, GEN m} $x$ being a vector of \typ{INT}s, return 3535the vector of inverses of the $x[i]$ mod $m$. The routine uses Montgomery's 3536trick, and involves a single inversion mod $m$, plus $3(N-1)$ multiplications 3537for $N$ entries. The routine is not stack-clean: $2N$ integers mod $m$ 3538are left on stack, besides the $N$ in the result. 3539 3540\fun{GEN}{Fp_div}{GEN a, GEN b, GEN m} returns the quotient of \kbd{a} by 3541\kbd{b} modulo \kbd{m} (smallest nonnegative residue). Raise an error if 3542\kbd{b} is not invertible. 3543 3544\fun{GEN}{Fp_divu}{GEN a, ulong b, GEN m} returns the quotient of \kbd{a} by 3545\kbd{b} modulo \kbd{m} (smallest nonnegative residue). Raise an error if 3546\kbd{b} is not invertible. 3547 3548\fun{int}{invmod}{GEN a, GEN m, GEN *g}, return $1$ if \kbd{a} 3549modulo \kbd{m} is invertible, else return $0$ and set 3550$\kbd{g} = \gcd(\kbd{a},\kbd{m})$. 3551 3552In the following three functions the integer parameter \kbd{ord} can be given 3553either as a positive \typ{INT} $N$, or as its factorization matrix $\var{faN}$, 3554 or as a pair $[N,\var{faN}]$. The parameter may be omitted by setting it to 3555\kbd{NULL} (the value is then $p-1$). 3556 3557\fun{GEN}{Fp_log}{GEN a, GEN g, GEN ord, GEN p} Let $g$ such that 3558$g^{ord} \equiv 1 \pmod{p}$. Return an integer $e$ such that 3559$a^e \equiv g \pmod{p}$. If $e$ does not exist, the result is undefined. 3560 3561\fun{GEN}{Fp_order}{GEN a, GEN ord, GEN p} returns the order of the 3562\kbd{Fp} \kbd{a}. Assume that \kbd{ord} is a multiple of the order of 3563\kbd{a}. 3564 3565\fun{GEN}{Fp_factored_order}{GEN a, GEN ord, GEN p} returns $[o,F]$, where $o$ 3566is the multiplicative order of the \kbd{Fp} $a$ in $\F_p^*$, and $F$ is the 3567factorization of $o$. Assume that \kbd{ord} is a multiple of the order of 3568\kbd{a}. 3569 3570\fun{int}{Fp_issquare}{GEN x, GEN p} returns $1$ if \kbd{x} is a square 3571modulo \kbd{p}, and $0$ otherwise. 3572 3573\fun{int}{Fp_ispower}{GEN x, GEN n, GEN p} returns $1$ if \kbd{x} is an 3574$n$-th power modulo \kbd{p}, and $0$ otherwise. 3575 3576\fun{GEN}{Fp_sqrt}{GEN x, GEN p} returns a square root of \kbd{x} modulo 3577\kbd{p} (the smallest nonnegative residue), where \kbd{x}, \kbd{p} are 3578\typ{INT}s, and \kbd{p} is assumed to be prime. Return \kbd{NULL} 3579if \kbd{x} is not a quadratic residue modulo \kbd{p}. 3580 3581\fun{GEN}{Fp_2gener}{GEN p} return a generator of 3582the $2$-Sylow subgroup of $\F_p^*$. To use with \kbd{Fp\_sqrt\_i}. 3583 3584\fun{GEN}{Fp_sqrt_i}{GEN x, GEN s2, GEN p} 3585as \kbd{Fp\_sqrt} where \kbd{s2} is the element returned by 3586\kbd{Fp\_2gener}. 3587 3588\fun{GEN}{Fp_sqrtn}{GEN a, GEN n, GEN p, GEN *zn} 3589returns \kbd{NULL} if $a$ is not an $n$-th power residue mod $p$. 3590Otherwise, returns an $n$-th root of $a$; if \kbd{zn} is not \kbd{NULL} 3591set it to a primitive $m$-th root of 1, $m = \gcd(p-1,n)$ allowing to compute 3592all $m$ solutions in $\F_p$ of the equation $x^n = a$. 3593 3594\fun{GEN}{Zn_sqrt}{GEN x, GEN n} returns one of the square roots of \kbd{x} 3595modulo \kbd{n} (possibly not prime), where \kbd{x} is a \typ{INT} and \kbd{n} 3596is either a \typ{INT} or is given by its factorization matrix. Return 3597\kbd{NULL} if no such square root exist. 3598 3599\fun{GEN}{Zn_quad_roots}{GEN N, GEN B, GEN C} solves the equation $X^2 + B X 3600+ C$ modulo $N$. Return \kbd{NULL} if there are no solutions. Else returns 3601 $[v, M]$ where $M \mid N$ and the \kbd{FpV} $v$ of distinct integers 3602(reduced, implicitly modulo $M$) is such that $x$ modulo $N$ is a solution to 3603the equation if and only if $x$ modulo $M$ belongs to $v$. If the 3604discriminant $B^2-4C$ is coprime to $N$, we have $M = N$ but in general $M$ 3605can be a strict divisor of $N$. 3606 3607\fun{long}{kross}{long x, long y} returns the \idx{Kronecker symbol} $(x|y)$, 3608i.e.$-1$, $0$ or $1$. If \kbd{y} is an odd prime, this is the \idx{Legendre 3609symbol}. (Contrary to \kbd{krouu}, \kbd{kross} also supports $\kbd{y} = 0$) 3610 3611\fun{long}{krouu}{ulong x, ulong y} returns the \idx{Kronecker symbol} 3612$(x|y)$, i.e.~$-1$, $0$ or $1$. Assumes \kbd{y} is nonzero. If \kbd{y} is an 3613odd prime, this is the \idx{Legendre symbol}. 3614 3615\fun{long}{krois}{GEN x, long y} returns the \idx{Kronecker symbol} $(x|y)$ 3616of \typ{INT}~x and \kbd{long}~\kbd{y}. As \kbd{kross} otherwise. 3617 3618\fun{long}{kroiu}{GEN x, ulong y} returns the \idx{Kronecker symbol} $(x|y)$ 3619of \typ{INT}~x and nonzero \kbd{ulong}~\kbd{y}. As \kbd{krouu} otherwise. 3620 3621\fun{long}{krosi}{long x, GEN y} returns the \idx{Kronecker symbol} $(x|y)$ 3622of \kbd{long}~x and \typ{INT}~\kbd{y}. As \kbd{kross} otherwise. 3623 3624\fun{long}{kroui}{ulong x, GEN y} returns the \idx{Kronecker symbol} $(x|y)$ 3625of \kbd{long}~x and \typ{INT}~\kbd{y}. As \kbd{kross} otherwise. 3626 3627\fun{long}{kronecker}{GEN x, GEN y} returns the \idx{Kronecker symbol} $(x|y)$ 3628of \typ{INT}s~x and~\kbd{y}. As \kbd{kross} otherwise. 3629 3630\fun{GEN}{factorial_Fp}{long n, GEN p} return $n!$ mod $p$. 3631 3632\fun{GEN}{pgener_Fp}{GEN p} returns the smallest primitive root modulo 3633\kbd{p}, assuming \kbd{p} is prime. 3634 3635\fun{GEN}{pgener_Zp}{GEN p} returns the smallest primitive root modulo $p^k$, 3636$k > 1$, assuming \kbd{p} is an odd prime. 3637 3638\fun{long}{Zp_issquare}{GEN x, GEN p} returns 1 if the \typ{INT} $x$ is 3639a $p$-adic square, $0$ otherwise. 3640 3641\fun{long}{Zn_issquare}{GEN x, GEN n} returns 1 if \typ{INT} $x$ is 3642a square modulo \kbd{n} (possibly not prime), where $n$ is either a \typ{INT} 3643or is given by its factorization matrix. Return $0$ otherwise. 3644 3645\fun{long}{Zn_ispower}{GEN x, GEN n, GEN K, GEN *py} returns 1 if \typ{INT} 3646$x$ is a $K$-th power modulo \kbd{n} (possibly not prime), where $n$ is 3647either a \typ{INT} or is given by its factorization matrix. Return $0$ 3648otherwise. If \kbd{py} is not \kbd{NULL}, set it to $y$ such that $y^K = x$ 3649modulo $n$. 3650 3651\fun{GEN}{pgener_Fp_local}{GEN p, GEN L}, \kbd{L} being a vector of 3652primes dividing $p - 1$, returns the smallest integer $x > 1$ which is a 3653generator of the $\ell$-Sylow of $\F_p^*$ for every $\ell$ in \kbd{L}. In 3654other words, $x^{(p-1)/\ell} \neq 1$ for all such $\ell$. In particular, 3655returns \kbd{pgener\_Fp(p)} if \kbd{L} contains all primes dividing $p - 1$. 3656It is not necessary, and in fact slightly inefficient, to include $\ell=2$, 3657since 2 is treated separately in any case, i.e. the generator obtained is 3658never a square. 3659 3660\fun{GEN}{rootsof1_Fp}{GEN n, GEN p} returns a primitive $n$-th root modulo 3661the prime $p$. 3662 3663\fun{GEN}{rootsof1u_Fp}{ulong n, GEN p} returns a primitive $n$-th root modulo 3664the prime $p$. 3665 3666\fun{ulong}{rootsof1_Fl}{ulong n, ulong p} returns a primitive $n$-th root 3667modulo the prime $p$. 3668 3669\subsec{Extending functions to vector inputs} 3670 3671The following functions apply $f$ to the given arguments, recursively 3672if they are of vector / matrix type: 3673 3674\fun{GEN}{map_proto_G}{GEN (*f)(GEN), GEN x} For instance, if $x$ is a 3675\typ{VEC}, return a \typ{VEC} whose components are the $f(x[i])$. 3676 3677\fun{GEN}{map_proto_lG}{long (*f)(GEN), GEN x} As above, applying the 3678function \kbd{stoi( f() )}. 3679 3680\fun{GEN}{map_proto_GL}{GEN (*f)(GEN,long), GEN x, long y} 3681 3682\fun{GEN}{map_proto_lGL}{long (*f)(GEN,long), GEN x, long y} 3683 3684In the last function, $f$ implements an associative binary operator, which we 3685extend naturally to an $n$-ary operator $f_n$ for any $n$: by convention, 3686$f_0() = 1$, $f_1(x) = x$, and 3687$$ f_n(x_1,\dots,x_n) = f( f_{n-1}(x_1,\dots,x_{n-1}), x_n)),$$ 3688for $n \geq 2$. 3689 3690\fun{GEN}{gassoc_proto}{GEN (*f)(GEN,GEN),GEN x, GEN y} If $y$ is not 3691\kbd{NULL}, return $f(x,y)$. Otherwise, $x$ must be of vector type, and we 3692return the result of $f$ applied to its components, computed using a 3693divide-and-conquer algorithm. More precisely, return 3694$$f( f(x_1,\kbd{NULL}), f(x_2,\kbd{NULL}) ),$$ 3695where $x_1$, $x_2$ are the two halves of $x$. 3696 3697\subsec{Miscellaneous arithmetic functions} 3698 3699\fun{long}{bigomegau}{ulong n} returns the number of prime divisors of $n > 37000$, counted with multiplicity. 3701 3702\fun{ulong}{coreu}{ulong n}, unique squarefree integer $d$ dividing $n$ such 3703that $n/d$ is a square. 3704 3705\fun{ulong}{coreu_fact}{GEN fa} same, where \kbd{fa} is \kbd{factoru(n)}. 3706 3707\fun{ulong}{corediscs}{long d, ulong *pt_f}, $d$ (possibly negative) 3708being congruent to $0$ or $1$ modulo $4$, return the fundamental 3709discriminant $D$ such that $d=D*f^2$ and set \kbd{*pt\_f} to $f$ 3710(if \kbd{*pt\_f} not \kbd{NULL}). 3711 3712\fun{ulong}{eulerphiu}{ulong n}, Euler's totient function of $n$. 3713 3714\fun{ulong}{eulerphiu_fact}{GEN fa} same, where \kbd{fa} is \kbd{factoru(n)}. 3715 3716\fun{long}{moebiusu}{ulong n}, Moebius $\mu$-function of $n$. 3717 3718\fun{long}{moebiusu_fact}{GEN fa} same, where \kbd{fa} is \kbd{factoru(n)}. 3719 3720\fun{ulong}{radicalu}{ulong n}, product of primes dividing $n$. 3721 3722\fun{GEN}{divisorsu}{ulong n}, returns the divisors of $n$ in a 3723\typ{VECSMALL}, sorted by increasing order. 3724 3725\fun{GEN}{divisorsu_fact}{GEN fa} same, where \kbd{fa} is \kbd{factoru(n)}. 3726 3727\fun{GEN}{divisorsu_fact_factored}{GEN fa} where \kbd{fa} is \kbd{factoru(n)}. 3728Return a vector $[D,F]$, where $D$ is a a \typ{VECSMALL} containing the 3729divisors of $u$ and $F[i]$ contains \kbd{factoru}$(D[i])$. 3730 3731\fun{GEN}{divisorsu_moebius}{GEN P} returns the divisors of $n$ of the form 3732$\prod_{p\in S} (-p)$, $S\subset P$ in a \typ{VECSMALL}. The vector is not 3733sorted but its first element is guaranteed to be $1$. If $P$ is 3734\kbd{factoru(n)[1]}, this returns the set of $\mu(d) d$ where $d$ runs 3735through the squarefree divisors of $n$. 3736 3737\fun{long}{numdivu}{ulong n}, returns the number of positive divisors of $n>0$. 3738 3739\fun{long}{numdivu_fact}{GEN fa} same, where \kbd{fa} is \kbd{factoru(n)}. 3740 3741\fun{long}{omegau}{ulong n} returns the number of prime divisors of $n > 0$. 3742 3743\fun{long}{uissquarefree}{ulong n} returns $1$ if \kbd{n} 3744is square-free, and $0$ otherwise. 3745 3746\fun{long}{uissquarefree_fact}{GEN fa} same, where \kbd{fa} is 3747\kbd{factoru(n)}. 3748 3749\fun{long}{uposisfundamental}{ulong x} return $1$ if $x$ is a fundamental 3750discriminant, and $0$ otherwise. 3751 3752\fun{long}{unegisfundamental}{ulong x} return $1$ if $-x$ is a fundamental 3753discriminant, and $0$ otherwise. 3754 3755\fun{long}{sisfundamental}{long x} return $1$ if $x$ is a fundamental 3756discriminant, and $0$ otherwise. 3757 3758\fun{int}{uis_357_power}{ulong x, ulong *pt, ulong *mask} as \tet{is_357_power} 3759for \kbd{ulong} $x$. 3760 3761\fun{int}{uis_357_powermod}{ulong x, ulong *mask} as \tet{uis_357_power}, but 3762only check for 3rd, 5th or 7th powers modulo 3763$211\times209\times61\times203\times117\times31\times43\times71$. 3764 3765\fun{long}{uisprimepower}{ulong n, ulong *p} as \tet{isprimepower}, for 3766\kbd{ulong} $n$. 3767 3768\fun{int}{uislucaspsp}{ulong n} returns $1$ if the \kbd{ulong} $n$ fails Lucas 3769compositeness test (it thus may be prime or composite), and $0$ otherwise 3770(proving that $n$ is composite). 3771 3772\fun{int}{uis2psp}{ulong n} returns $1$ if the odd \kbd{ulong} $n > 1$ fails a 3773strong Rabin-Miller test for the base $2$ (it thus may be prime or 3774composite), and $0$ otherwise (proving that $n$ is composite). 3775 3776\fun{int}{uispsp}{ulong a, ulong n} returns $1$ if the odd \kbd{ulong} $n > 1$ 3777fails a strong Rabin-Miller test for the base $1 < a < n$ (it thus may be 3778prime or composite), and $0$ otherwise (proving that $n$ is composite). 3779 3780\fun{ulong}{sumdigitsu}{ulong n} returns the sum of decimal digits of $u$. 3781 3782\fun{GEN}{usumdiv_fact}{GEN fa}, sum of divisors of \kbd{ulong} $n$, where 3783\kbd{fa} is \kbd{factoru(n)}. 3784 3785\fun{GEN}{usumdivk_fact}{GEN fa, ulong k}, sum of $k$-th powers of divisors 3786of \kbd{ulong} $n$, where \kbd{fa} is \kbd{factoru(n)}. 3787 3788\fun{GEN}{hilbertii}{GEN x, GEN y, GEN p}, returns the Hilbert symbol 3789$(x,y)$ at the prime $p$ (\kbd{NULL} for the place at infinity); $x$ and $y$ 3790are \typ{INT}s. 3791 3792\fun{GEN}{sumdedekind}{GEN h, GEN k} returns the Dedekind sum attached to 3793the \typ{INT} $h$ and $k$, $k > 0$. 3794 3795\fun{GEN}{sumdedekind_coprime}{GEN h, GEN k} as \kbd{sumdedekind}, except 3796that $h$ and $k$ are assumed to be coprime \typ{INT}s. 3797 3798\fun{GEN}{u_sumdedekind_coprime}{long h, long k} 3799Let $k > 0$, $0 \leq h < k$, $(h,k) = 1$. Returns $[s_1,s_2]$ 3800in a \typ{VECSMALL}, such that $s(h,k) = (s_2 + k s_1) / (12k)$. 3801Requires $\max(h + k/2, k) < \kbd{LONG\_MAX}$ 3802to avoid overflow, in particular $k \leq (2/3)\kbd{LONG\_MAX}$ is fine. 3803 3804\newpage 3805\chapter{Level 2 kernel} 3806 3807These functions deal with modular arithmetic, linear algebra and polynomials 3808where assumptions can be made about the types of the coefficients. 3809 3810\section{Naming scheme}\label{se:level2names} 3811A function name is built in the following way: 3812$A_1\kbd{\_}\dots\kbd{\_}A_n\var{fun}$ for an operation \var{fun} with $n$ 3813arguments of class $A_1$,\dots, $A_n$. A class name is given by a base ring 3814followed by a number of code letters. Base rings are among 3815 3816 \kbd{Fl}: $\Z/l\Z$ where $l < 2^{\B}$ is not necessarily prime. Implemented 3817 using \kbd{ulong}s 3818 3819 \kbd{Fp}: $\Z/p\Z$ where $p$ is a \typ{INT}, not necessarily prime. 3820Implemented as \typ{INT}s $z$, preferably satisfying $0 \leq z < p$. 3821More precisely, any \typ{INT} can be used as an \kbd{Fp}, but reduced 3822inputs are treated more efficiently. Outputs from \kbd{Fp}xxx routines are 3823reduced. 3824 3825 \kbd{Fq}: $\Z[X]/(p,T(X))$, $p$ a \typ{INT}, $T$ a \typ{POL} with \kbd{Fp} 3826coefficients or \kbd{NULL} (in which case no reduction modulo \kbd{T} is 3827performed). Implemented as \typ{POL}s $z$ with \kbd{Fp} coefficients, 3828$\deg(z) < \deg \kbd{T}$, although $z$ a \typ{INT} is allowed for elements in 3829the prime field. 3830 3831 \kbd{Z}: the integers $\Z$, implemented as \typ{INT}s. 3832 3833 \kbd{Zp}: the $p$-adic integers $\Z_p$, implemented as \typ{INT}s, for arbitrary $p$ 3834 3835 \kbd{Zl}: the $p$-adic integers $\Z_p$, implemented as \typ{INT}s, for $p< 2^{\B}$ 3836 3837 \kbd{z}: the integers $\Z$, implemented using (signed) \kbd{long}s. 3838 3839 \kbd{Q}: the rational numbers $\Q$, implemented as \typ{INT}s and 3840\typ{FRAC}s. 3841 3842 \kbd{Rg}: a commutative ring, whose elements can be 3843\kbd{gadd}-ed, \kbd{gmul}-ed, etc. 3844 3845\noindent Possible letters are: 3846 3847 \kbd{X}: polynomial in $X$ (\typ{POL} in a fixed variable), e.g. \kbd{FpX} 3848 means $\Z/p\Z[X]$ 3849 3850 \kbd{Y}: polynomial in $Y\neq X$. This is used to resolve ambiguities. 3851 E.g. \kbd{FpXY} means $((\Z/p\Z)[X])[Y]$. 3852 3853 \kbd{V}: vector (\typ{VEC} or \typ{COL}), treated as a line vector 3854 (independently of the actual type). E.g. \kbd{ZV} means $\Z^k$ for some $k$. 3855 3856 \kbd{C}: vector (\typ{VEC} or \typ{COL}), treated as a column vector 3857 (independently of the actual type). The difference with \kbd{V} is purely 3858 semantic: if the result is a vector, it will be of type \typ{COL} unless 3859 mentioned otherwise. For instance the function \kbd{ZC\_add} receives two 3860 integral vectors (\typ{COL} or \typ{VEC}, possibly different types) of the 3861 same length and returns a \typ{COL} whose entries are the sums of the input 3862 coefficients. 3863 3864 \kbd{M}: matrix (\typ{MAT}). E.g. \kbd{QM} means a matrix with rational 3865 entries 3866 3867 \kbd{T}: Trees. Either a leaf or a \typ{VEC} of trees. 3868 3869 \kbd{E}: point over an elliptic curve, represented 3870 as two-component vectors \kbd{[x,y]}, except for the represented by the 3871 one-component vector \kbd{[0]}. Not all curve models are supported. 3872 3873 \kbd{Q}: representative (\typ{POL}) of a class in a polynomial quotient ring. 3874 E.g.~an \kbd{FpXQ} belongs to $(\Z/p\Z)[X]/(T(X))$, \kbd{FpXQV} means a 3875 vector of such elements, etc. 3876 3877 \kbd{n}: a polynomial representative (\typ{POL}) for a truncated power 3878 series modulo $X^n$. E.g.~an \kbd{FpXn} belongs to $(\Z/p\Z)[X]/(X^n)$, 3879 \kbd{FpXnV} means a vector of such elements, etc. 3880 3881 \kbd{x}, \kbd{y}, \kbd{m}, \kbd{v}, \kbd{c}, \kbd{q}: as their uppercase 3882 counterpart, but coefficient arrays are implemented using \typ{VECSMALL}s, 3883 which coefficient understood as \kbd{ulong}s. 3884 3885 \kbd{x} and \kbd{y} (and \kbd{q}) are implemented by a \typ{VECSMALL} whose 3886 first coefficient is used as a code-word and the following are the 3887 coefficients , similarly to a \typ{POL}. This is known as a 'POLSMALL'. 3888 3889 \kbd{m} are implemented by a \typ{MAT} whose components (columns) are 3890 \typ{VECSMALL}s. This is known as a 'MATSMALL'. 3891 3892 \kbd{v} and \kbd{c} are regular \typ{VECSMALL}s. Difference between the 3893 two is purely semantic. 3894 3895\noindent Omitting the letter means the argument is a scalar in the base 3896ring. Standard functions \var{fun} are 3897 3898 \kbd{add}: add 3899 3900 \kbd{sub}: subtract 3901 3902 \kbd{mul}: multiply 3903 3904 \kbd{sqr}: square 3905 3906 \kbd{div}: divide (Euclidean quotient) 3907 3908 \kbd{rem}: Euclidean remainder 3909 3910 \kbd{divrem}: return Euclidean quotient, store remainder in a pointer 3911argument. Three special values of that pointer argument modify the default 3912behavior: \kbd{NULL} (do not store the remainder, used to implement 3913\kbd{div}), \tet{ONLY_REM} (return the remainder, used to implement 3914\kbd{rem}), \tet{ONLY_DIVIDES} (return the quotient if the division is exact, 3915and \kbd{NULL} otherwise). 3916 3917 \kbd{gcd}: GCD 3918 3919 \kbd{extgcd}: return GCD, store Bezout coefficients in pointer arguments 3920 3921 \kbd{pow}: exponentiate 3922 3923 \kbd{eval}: evaluation / composition 3924 3925\section{Coefficient ring} 3926 3927\fun{long}{Rg_type}{GEN x, GEN *ptp, GEN *ptpol, long *ptprec} returns 3928the ``natural'' base ring over which the object $x$ is defined. 3929 3930Raise an error if it detects consistency problems in modular objects: 3931incompatible rings (e.g. $\F_p$ and $\F_q$ for primes $p\neq q$, 3932$\F_p[X]/(T)$ and $\F_p[X]/(U)$ for $T\neq U$). Minor discrepancies are 3933supported if they make general sense (e.g. $\F_p$ and $\F_{p^k}$, but not 3934$\F_p$ and $\Q_p$); \typ{FFELT} and \typ{POLMOD} of \typ{INTMOD}s are 3935considered inconsistent, even if they define the same field: if you need to 3936use simultaneously these different finite field implementations, multiply the 3937polynomial by a \typ{FFELT} equal to $1$ first. 3938 3939\item 0: none of the others (presumably multivariate, possibly inconsistent). 3940 3941\item \typ{INT}: defined over $\Z$. 3942 3943\item \typ{FRAC}: defined over $\Q$. 3944 3945\item \typ{INTMOD}: defined over $\Z/p\Z$, where \kbd{*ptp} is set to $p$. 3946It is not checked whether $p$ is prime. 3947 3948\item \typ{COMPLEX}: defined over $\C$ (at least one \typ{COMPLEX} with at 3949least one inexact floating point \typ{REAL} component). Set \kbd{*ptprec} 3950to the minimal accuracy (as per \kbd{precision}) of inexact components. 3951 3952\item \typ{REAL}: defined over $\R$ (at least one inexact floating point 3953\typ{REAL} component). Set \kbd{*ptprec} to the minimal accuracy (as per 3954\kbd{precision}) of inexact components. 3955 3956\item \typ{PADIC}: defined over $\Q_p$, where \kbd{*ptp} is set to $p$ and 3957\kbd{*ptprec} to the $p$-adic accuracy. 3958 3959\item \typ{FFELT}: defined over a finite field $\F_{p^k}$, where \kbd{*ptp} 3960is set to the field characteristic $p$ and \kbd{*ptpol} is set to a 3961\typ{FFELT} belonging to the field. 3962 3963\item \typ{POL}: defined over a polynomial ring. 3964 3965\item other values are composite corresponding to quotients $R[X]/(T)$, with 3966one primary type \kbd{t1}, describing the form of the quotient, 3967and a secondary type \kbd{t2}, describing $R$. If \kbd{t} is the 3968\kbd{RgX\_type}, \kbd{t1} and \kbd{t2} are recovered using 3969 3970\fun{void}{RgX_type_decode}{long t, long *t1, long *t2} 3971 3972\kbd{t1} is one of 3973 3974\typ{POLMOD}: at least one \typ{POLMOD} component, 3975set \kbd{*ppol} to the modulus, 3976 3977\typ{QUAD}: no \typ{POLMOD}, at least one \typ{QUAD} component, 3978set \kbd{*ppol} to the modulus (\kbd{$-$.pol}) of the \typ{QUAD}, 3979 3980\typ{COMPLEX}: no \typ{POLMOD} or \typ{QUAD}, at least one \typ{COMPLEX} 3981component, set \kbd{*ppol} to $y^2 + 1$. 3982 3983and the underlying base ring $R$ is given by \kbd{t2}, which 3984is one of \typ{INT}, \typ{INTMOD} (set \kbd{*ptp}) or \typ{PADIC} 3985(set \kbd{*ptp} and \kbd{*ptprec}), with the same meaning 3986as above. 3987 3988\fun{int}{RgX_type_is_composite}{long t} $t$ as returned by \kbd{RgX\_type}, 3989return 1 if $t$ is a composite type, and 0 otherwise. 3990 3991\fun{GEN}{Rg_get_0}{GEN x} returns $0$ in the base ring over which $x$ 3992is defined, to the proper accuracy (e.g. \kbd{0}, \kbd{Mod(0,3)}, 3993\kbd{O(5\pow 10)}). 3994 3995\fun{GEN}{Rg_get_1}{GEN x} returns $1$ in the base ring over which $x$ 3996is defined, to the proper accuracy (e.g. \kbd{0}, \kbd{Mod(0,3)}, 3997 3998\fun{long}{RgX_type}{GEN x, GEN *ptp, GEN *ptpol, long *ptprec} returns 3999the ``natural'' base ring over which the polynomial $x$ is defined, 4000otherwise as \kbd{Rg\_type}. 4001 4002\fun{long}{RgX_Rg_type}{GEN x, GEN y, GEN *ptp, GEN *ptpol, long *ptprec} 4003returns the ``natural'' base ring over which the polynomial $x$ and the element 4004$y$ are defined, otherwise as \kbd{Rg\_type}. 4005 4006\fun{long}{RgX_type2}{GEN x, GEN y, GEN *ptp, GEN *ptpol, long *ptprec} returns 4007the ``natural'' base ring over which the polynomials $x$ and $y$ are defined, 4008otherwise as \kbd{Rg\_type}. 4009 4010\fun{long}{RgX_type3}{GEN x, GEN y, GNE z, GEN *ptp, GEN *ptpol, long *ptprec} 4011returns the ``natural'' base ring over which the polynomials $x$, $y$ and $z$ 4012are defined, otherwise as \kbd{Rg\_type}. 4013 4014\fun{long}{RgM_type}{GEN x, GEN *ptp, GEN *ptpol, long *ptprec} returns 4015the ``natural'' base ring over which the matrix $x$ is defined, 4016otherwise as \kbd{Rg\_type}. 4017 4018\fun{long}{RgM_type2}{GEN x, GEN y, GEN *ptp, GEN *ptpol, long *ptprec} returns 4019the ``natural'' base ring over which the matrices $x$ and $y$ are defined, 4020otherwise as \kbd{Rg\_type}. 4021 4022\fun{long}{RgV_type}{GEN x, GEN *ptp, GEN *ptpol, long *ptprec} returns 4023the ``natural'' base ring over which the vector $x$ is defined, 4024otherwise as \kbd{Rg\_type}. 4025 4026\fun{long}{RgV_type2}{GEN x, GEN y, GEN *ptp, GEN *ptpol, long *ptprec} returns 4027the ``natural'' base ring over which the vectors $x$ and $y$ are defined, 4028otherwise as \kbd{Rg\_type}. 4029 4030\fun{long}{RgM_RgC_type}{GEN x, GEN y, GEN *ptp, GEN *ptpol, long *ptprec} 4031returns the ``natural'' base ring over which the matrix $x$ and the vector 4032$y$ are defined, otherwise as \kbd{Rg\_type}. 4033 4034\section{Modular arithmetic} 4035 4036\noindent These routines implement univariate polynomial arithmetic and 4037linear algebra over finite fields, in fact over finite rings of the form 4038$(\Z/p\Z)[X]/(T)$, where $p$ is not necessarily prime and $T\in(\Z/p\Z)[X]$ is 4039possibly reducible; and finite extensions thereof. All this can be emulated 4040with \typ{INTMOD} and \typ{POLMOD} coefficients and using generic routines, 4041at a considerable loss of efficiency. Also, specialized routines are 4042available that have no obvious generic equivalent. 4043 4044\subsec{\kbd{FpC} / \kbd{FpV}, \kbd{FpM}} A \kbd{ZV} 4045(resp.~a~\kbd{ZM}) is a \typ{VEC} or \typ{COL} (resp.~\typ{MAT}) with 4046\typ{INT} coefficients. An \kbd{FpV} or \kbd{FpM}, with respect to a given 4047\typ{INT}~\kbd{p}, is the same with \kbd{Fp} coordinates; operations are 4048understood over $\Z/p\Z$. 4049 4050\subsubsec{Conversions} 4051 4052\fun{int}{Rg_is_Fp}{GEN z, GEN *p}, checks if \kbd{z} can be mapped to 4053$\Z/p\Z$: a \typ{INT} or a \typ{INTMOD} whose modulus is equal to \kbd{*p}, 4054(if \kbd{*p} not \kbd{NULL}), in that case return $1$, else $0$. If a modulus 4055is found it is put in \kbd{*p}, else \kbd{*p} is left unchanged. 4056 4057\fun{int}{RgV_is_FpV}{GEN z, GEN *p}, \kbd{z} a \typ{VEC} (resp. \typ{COL}), 4058checks if it can be mapped to a \kbd{FpV} (resp. \kbd{FpC}), by checking 4059\kbd{Rg\_is\_Fp} coefficientwise. 4060 4061\fun{int}{RgM_is_FpM}{GEN z, GEN *p}, \kbd{z} a \typ{MAT}, 4062checks if it can be mapped to a \kbd{FpM}, by checking \kbd{RgV\_is\_FpV} 4063columnwise. 4064 4065\fun{GEN}{Rg_to_Fp}{GEN z, GEN p}, \kbd{z} a scalar which can be mapped to 4066$\Z/p\Z$: a \typ{INT}, a \typ{INTMOD} whose modulus is divisible by $p$, 4067a \typ{FRAC} whose denominator is coprime to $p$, or a \typ{PADIC} with 4068underlying prime $\ell$ satisfying $p = \ell^n$ for some $n$ (less than the 4069accuracy of the input). Returns \kbd{lift(z * Mod(1,p))}, normalized. 4070 4071\fun{GEN}{padic_to_Fp}{GEN x, GEN p} special case of \tet{Rg_to_Fp}, 4072for a $x$ a \typ{PADIC}. 4073 4074\fun{GEN}{RgV_to_FpV}{GEN z, GEN p}, \kbd{z} a \typ{VEC} or \typ{COL}, 4075returns the \kbd{FpV} (as a \typ{VEC}) obtained by applying \kbd{Rg\_to\_Fp} 4076coefficientwise. 4077 4078\fun{GEN}{RgC_to_FpC}{GEN z, GEN p}, \kbd{z} a \typ{VEC} or \typ{COL}, 4079returns the \kbd{FpC} (as a \typ{COL}) obtained by applying \kbd{Rg\_to\_Fp} 4080coefficientwise. 4081 4082\fun{GEN}{RgM_to_FpM}{GEN z, GEN p}, \kbd{z} a \typ{MAT}, 4083returns the \kbd{FpM} obtained by applying \kbd{RgC\_to\_FpC} 4084columnwise. 4085 4086\fun{GEN}{RgM_Fp_init}{GEN z, GEN p, ulong *pp}, given an \kbd{RgM} $z$, 4087whose entries can be mapped to $\F_p$ (as per \tet{Rg_to_Fp}), and a prime 4088number $p$. This routine returns a normal form of $z$: either an 4089\kbd{F2m} ($p = 2$), an \kbd{Flm} ($p$ fits into an \kbd{ulong}) 4090or an \kbd{FpM}. In the first two cases, \kbd{pp} is set to \kbd{itou}$(p)$, 4091and to $0$ in the last. 4092 4093The functions above are generally used as follows: 4094\bprog 4095GEN add(GEN x, GEN y) 4096{ 4097 GEN p = NULL; 4098 if (Rg_is_Fp(x, &p) && Rg_is_Fp(y, &p) && p) 4099 { 4100 x = Rg_to_Fp(x, p); y = Rg_to_Fp(y, p); 4101 z = Fp_add(x, y, p); 4102 return Fp_to_mod(z); 4103 } 4104 else return gadd(x, y); 4105} 4106@eprog 4107 4108\fun{GEN}{FpC_red}{GEN z, GEN p}, \kbd{z} a \kbd{ZC}. Returns \kbd{lift(Col(z) * 4109Mod(1,p))}, hence a \typ{COL}. 4110 4111\fun{GEN}{FpV_red}{GEN z, GEN p}, \kbd{z} a \kbd{ZV}. Returns \kbd{lift(Vec(z) * 4112Mod(1,p))}, hence a \typ{VEC} 4113 4114\fun{GEN}{FpM_red}{GEN z, GEN p}, \kbd{z} a \kbd{ZM}. Returns \kbd{lift(z * 4115Mod(1,p))}, which is an \kbd{FpM}. 4116 4117\subsubsec{Basic operations} 4118 4119\fun{GEN}{random_FpC}{long n, GEN p} returns a random \kbd{FpC} with $n$ 4120components. 4121 4122\fun{GEN}{random_FpV}{long n, GEN p} returns a random \kbd{FpV} with $n$ 4123components. 4124 4125\fun{GEN}{FpC_center}{GEN z, GEN p, GEN pov2} returns a \typ{COL} whose 4126entries are the \kbd{Fp\_center} of the \kbd{gel(z,i)}. 4127 4128\fun{GEN}{FpM_center}{GEN z, GEN p, GEN pov2} returns a matrix whose 4129entries are the \kbd{Fp\_center} of the \kbd{gcoeff(z,i,j)}. 4130 4131\fun{void}{FpC_center_inplace}{GEN z, GEN p, GEN pov2} 4132in-place version of \kbd{FpC\_center}, using \kbd{affii}. 4133 4134\fun{void}{FpM_center_inplace}{GEN z, GEN p, GEN pov2} 4135in-place version of \kbd{FpM\_center}, using \kbd{affii}. 4136 4137\fun{GEN}{FpC_add}{GEN x, GEN y, GEN p} adds the \kbd{ZC} $x$ and $y$ 4138and reduce modulo $p$ to obtain an \kbd{FpC}. 4139 4140\fun{GEN}{FpV_add}{GEN x, GEN y, GEN p} same as \kbd{FpC\_add}, returning and 4141\kbd{FpV}. 4142 4143\fun{GEN}{FpM_add}{GEN x, GEN y, GEN p} adds the two \kbd{ZM}s~\kbd{x} 4144and \kbd{y} (assumed to have compatible dimensions), and reduce modulo 4145\kbd{p} to obtain an \kbd{FpM}. 4146 4147\fun{GEN}{FpC_sub}{GEN x, GEN y, GEN p} subtracts the \kbd{ZC} $y$ to 4148the \kbd{ZC} $x$ and reduce modulo $p$ to obtain an \kbd{FpC}. 4149 4150\fun{GEN}{FpV_sub}{GEN x, GEN y, GEN p} same as \kbd{FpC\_sub}, returning and 4151\kbd{FpV}. 4152 4153\fun{GEN}{FpM_sub}{GEN x, GEN y, GEN p} subtracts the two \kbd{ZM}s~\kbd{x} 4154and \kbd{y} (assumed to have compatible dimensions), and reduce modulo 4155\kbd{p} to obtain an \kbd{FpM}. 4156 4157\fun{GEN}{FpC_Fp_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZC}~\kbd{x} 4158(seen as a column vector) by the \typ{INT}~\kbd{y} and reduce modulo \kbd{p} to 4159obtain an \kbd{FpC}. 4160 4161\fun{GEN}{FpM_Fp_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZM}~\kbd{x} 4162(seen as a column vector) by the \typ{INT}~\kbd{y} and reduce modulo \kbd{p} to 4163obtain an \kbd{FpM}. 4164 4165\fun{GEN}{FpC_FpV_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZC}~\kbd{x} 4166(seen as a column vector) by the \kbd{ZV}~\kbd{y} (seen as a row vector, 4167assumed to have compatible dimensions), and reduce modulo \kbd{p} to obtain 4168an \kbd{FpM}. 4169 4170\fun{GEN}{FpM_mul}{GEN x, GEN y, GEN p} multiplies the two \kbd{ZM}s~\kbd{x} 4171and \kbd{y} (assumed to have compatible dimensions), and reduce modulo 4172\kbd{p} to obtain an \kbd{FpM}. 4173 4174\fun{GEN}{FpM_powu}{GEN x, ulong n, GEN p} computes $x^n$ where $x$ is a 4175square \kbd{FpM}. 4176 4177\fun{GEN}{FpM_FpC_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZM}~\kbd{x} 4178by the \kbd{ZC}~\kbd{y} (seen as a column vector, assumed to have compatible 4179dimensions), and reduce modulo \kbd{p} to obtain an \kbd{FpC}. 4180 4181\fun{GEN}{FpM_FpC_mul_FpX}{GEN x, GEN y, GEN p, long v} is a memory-clean 4182version of 4183\bprog 4184 GEN tmp = FpM_FpC_mul(x,y,p); 4185 return RgV_to_RgX(tmp, v); 4186@eprog 4187 4188\fun{GEN}{FpV_FpC_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZV}~\kbd{x} 4189(seen as a row vector) by the \kbd{ZC}~\kbd{y} (seen as a column vector, 4190assumed to have compatible dimensions), and reduce modulo \kbd{p} to obtain 4191an \kbd{Fp}. 4192 4193\fun{GEN}{FpV_dotproduct}{GEN x,GEN y,GEN p} scalar product of 4194$x$ and $y$ (assumed to have the same length). 4195 4196\fun{GEN}{FpV_dotsquare}{GEN x, GEN p} scalar product of $x$ with itself. 4197has \typ{INT} entries. 4198 4199\fun{GEN}{FpV_factorback}{GEN L, GEN e, GEN p} given an \kbd{FpV} $L$ 4200and a \kbd{ZV} or \kbd{zv} $e$ of the same length, return $\prod_i L_i^{e_i}$ 4201modulo $p$. 4202 4203\subsubsec{\kbd{Fp}-linear algebra} The implementations are not 4204asymptotically efficient ($O(n^3)$ standard algorithms). 4205 4206\fun{GEN}{FpM_deplin}{GEN x, GEN p} returns a nontrivial kernel vector, 4207or \kbd{NULL} if none exist. 4208 4209\fun{GEN}{FpM_det}{GEN x, GEN p} as \kbd{det} 4210 4211\fun{GEN}{FpM_gauss}{GEN a, GEN b, GEN p} as \kbd{gauss}, where $a$ and 4212$b$ are \kbd{FpM}. 4213 4214\fun{GEN}{FpM_FpC_gauss}{GEN a, GEN b, GEN p} as \kbd{gauss}, where $a$ 4215is a \kbd{FpM} and $b$ a \kbd{FpC}. 4216 4217\fun{GEN}{FpM_image}{GEN x, GEN p} as \kbd{image} 4218 4219\fun{GEN}{FpM_intersect}{GEN x, GEN y, GEN p} as \kbd{intersect} 4220 4221\fun{GEN}{FpM_inv}{GEN x, GEN p} returns a left inverse of \kbd{x} 4222(the inverse if $x$ is square), or \kbd{NULL} if \kbd{x} is not invertible. 4223 4224\fun{GEN}{FpM_FpC_invimage}{GEN A, GEN y, GEN p} 4225 given an \kbd{FpM} $A$ and an \kbd{FpC} $y$, returns an $x$ such that $Ax = 4226 y$, or \kbd{NULL} if no such vector exist. 4227 4228\fun{GEN}{FpM_invimage}{GEN A, GEN y, GEN p} 4229given two \kbd{FpM} $A$ and $y$, returns $x$ such that $Ax = y$, or \kbd{NULL} 4230if no such matrix exist. 4231 4232\fun{GEN}{FpM_ker}{GEN x, GEN p} as \kbd{ker} 4233 4234\fun{long}{FpM_rank}{GEN x, GEN p} as \kbd{rank} 4235 4236\fun{GEN}{FpM_indexrank}{GEN x, GEN p} as \kbd{indexrank} 4237 4238\fun{GEN}{FpM_suppl}{GEN x, GEN p} as \kbd{suppl} 4239 4240\fun{GEN}{FpM_hess}{GEN x, GEN p} upper Hessenberg form of $x$ over $\F_p$. 4241 4242\fun{GEN}{FpM_charpoly}{GEN x, GEN p} characteristic polynomial of $x$. 4243 4244\subsubsec{\kbd{FqC}, \kbd{FqM} and \kbd{Fq}-linear algebra} 4245 4246An \kbd{FqM} (resp. \kbd{FqC}) is a matrix (resp a \typ{COL}) with 4247\kbd{Fq} coefficients (with respect to given \kbd{T}, \kbd{p}), not necessarily 4248reduced (i.e arbitrary \typ{INT}s and \kbd{ZX}s in the same variable as 4249\kbd{T}). 4250 4251\fun{GEN}{RgC_to_FqC}{GEN z, GEN T, GEN p} 4252 4253\fun{GEN}{RgM_to_FqM}{GEN z, GEN T, GEN p} 4254 4255\fun{GEN}{FqC_add}{GEN a, GEN b, GEN T, GEN p} 4256 4257\fun{GEN}{FqC_sub}{GEN a, GEN b, GEN T, GEN p} 4258 4259\fun{GEN}{FqC_Fq_mul}{GEN a, GEN b, GEN T, GEN p} 4260 4261\fun{GEN}{FqC_FqV_mul}{GEN a, GEN b, GEN T, GEN p} 4262 4263\fun{GEN}{FqM_FqC_gauss}{GEN a, GEN b, GEN T, GEN p} 4264as \kbd{gauss}, where $b$ is a \kbd{FqC}. 4265 4266\fun{GEN}{FqM_FqC_invimage}{GEN a, GEN b, GEN T, GEN p} 4267 4268\fun{GEN}{FqM_FqC_mul}{GEN a, GEN b, GEN T, GEN p} 4269 4270\fun{GEN}{FqM_deplin}{GEN x, GEN T, GEN p} returns a nontrivial 4271kernel vector, or \kbd{NULL} if none exist. 4272 4273\fun{GEN}{FqM_det}{GEN x, GEN T, GEN p} as \kbd{det} 4274 4275\fun{GEN}{FqM_gauss}{GEN a, GEN b, GEN T, GEN p} 4276as \kbd{gauss}, where $b$ is a \kbd{FqM}. 4277 4278\fun{GEN}{FqM_image}{GEN x, GEN T, GEN p} as \kbd{image} 4279 4280\fun{GEN}{FqM_indexrank}{GEN x, GEN T, GEN p} as \kbd{indexrank} 4281 4282\fun{GEN}{FqM_inv}{GEN x, GEN T, GEN p} returns the inverse of \kbd{x}, or 4283\kbd{NULL} if \kbd{x} is not invertible. 4284 4285\fun{GEN}{FqM_invimage}{GEN a, GEN b, GEN T, GEN p} as \kbd{invimage} 4286 4287\fun{GEN}{FqM_ker}{GEN x, GEN T, GEN p} as \kbd{ker} 4288 4289\fun{GEN}{FqM_mul}{GEN a, GEN b, GEN T, GEN p} 4290 4291\fun{long}{FqM_rank}{GEN x, GEN T, GEN p} as \kbd{rank} 4292 4293\fun{GEN}{FqM_suppl}{GEN x, GEN T, GEN p} as \kbd{suppl} 4294 4295 4296\subsec{\kbd{Flc} / \kbd{Flv}, \kbd{Flm}} See \kbd{FpV}, \kbd{FpM} 4297operations. 4298 4299\fun{GEN}{Flv_copy}{GEN x} returns a copy of \kbd{x}. 4300 4301\fun{GEN}{Flv_center}{GEN z, ulong p, ulong ps2} 4302 4303\fun{GEN}{random_Flv}{long n, ulong p} returns a random \kbd{Flv} with $n$ 4304components. 4305 4306\fun{GEN}{Flm_copy}{GEN x} returns a copy of \kbd{x}. 4307 4308\fun{GEN}{matid_Flm}{long n} returns an \kbd{Flm} which is an $n \times n$ 4309identity matrix. 4310 4311\fun{GEN}{scalar_Flm}{long s, long n} returns an \kbd{Flm} which is $s$ times 4312the $n \times n$ identity matrix. 4313 4314\fun{GEN}{Flm_center}{GEN z, ulong p, ulong ps2} 4315 4316\fun{GEN}{Flm_Fl_add}{GEN x, ulong y, ulong p} returns $x + y*\text{Id}$ 4317($x$ must be square). 4318 4319\fun{GEN}{Flm_Fl_sub}{GEN x, ulong y, ulong p} returns $x - y*\text{Id}$ 4320($x$ must be square). 4321 4322\fun{GEN}{Flm_Flc_mul}{GEN x, GEN y, ulong p} multiplies \kbd{x} and \kbd{y} 4323(assumed to have compatible dimensions). 4324 4325\fun{GEN}{Flm_Flc_mul_pre}{GEN x, GEN y, ulong p, ulong pi} multiplies \kbd{x} 4326and \kbd{y} (assumed to have compatible dimensions), assuming $pi$ is the 4327pseudo inverse of $p$. 4328 4329\fun{GEN}{Flc_Flv_mul}{GEN x, GEN y, ulong p} multiplies the column vector $x$ 4330by the row vector $y$. The result is a matrix. 4331 4332\fun{GEN}{Flm_Flc_mul_pre_Flx}{GEN x, GEN y, ulong p, ulong pi, long sv} 4333return \kbd{Flv\_to\_Flx(Flm\_Flc\_mul\_pre(x, y, p, pi), sv)}. 4334 4335\fun{GEN}{Flm_Fl_mul}{GEN x, ulong y, ulong p} multiplies the \kbd{Flm} 4336\kbd{x} by \kbd{y}. 4337 4338\fun{GEN}{Flm_Fl_mul_pre}{GEN x, ulong y, ulong p, ulong pi} multiplies the 4339\kbd{Flm} \kbd{x} by \kbd{y} assuming $pi$ is the pseudo inverse of $p$. 4340 4341\fun{GEN}{Flm_neg}{GEN x, ulong p} negates the \kbd{Flm} \kbd{x}. 4342 4343\fun{void}{Flm_Fl_mul_inplace}{GEN x, ulong y, ulong p} replaces 4344the \kbd{Flm} \kbd{x} by $\kbd{x}*\kbd{y}$. 4345 4346\fun{GEN}{Flv_Fl_mul}{GEN x, ulong y, ulong p} multiplies the \kbd{Flv} 4347\kbd{x} by \kbd{y}. 4348 4349\fun{void}{Flv_Fl_mul_inplace}{GEN x, ulong y, ulong p} replaces 4350the \kbd{Flc} \kbd{x} by $\kbd{x}*\kbd{y}$. 4351 4352\fun{void}{Flv_Fl_mul_part_inplace}{GEN x, ulong y, ulong p, long l} 4353multiplies $x[1..l]$ by $y$ modulo $p$. In place. 4354 4355\fun{GEN}{Flv_Fl_div}{GEN x, ulong y, ulong p} divides the \kbd{Flv} 4356\kbd{x} by \kbd{y}. 4357 4358\fun{void}{Flv_Fl_div_inplace}{GEN x, ulong y, ulong p} replaces 4359the \kbd{Flv} \kbd{x} by $\kbd{x}/\kbd{y}$. 4360 4361\fun{void}{Flc_lincomb1_inplace}{GEN X, GEN Y, ulong v, ulong q} 4362sets $X\leftarrow X + vY$, where $X,Y$ are \kbd{Flc}. Memory efficient (e.g. 4363no-op if $v = 0$), and gerepile-safe. 4364 4365\fun{GEN}{Flv_add}{GEN x, GEN y, ulong p} adds two \kbd{Flv}. 4366 4367\fun{void}{Flv_add_inplace}{GEN x, GEN y, ulong p} replaces 4368$x$ by $x+y$. 4369 4370\fun{GEN}{Flv_neg}{GEN x, ulong p} returns $-x$. 4371 4372\fun{void}{Flv_neg_inplace}{GEN x, ulong p} replaces $x$ by $-x$. 4373 4374\fun{GEN}{Flv_sub}{GEN x, GEN y, ulong p} subtracts \kbd{y} to \kbd{x}. 4375 4376\fun{void}{Flv_sub_inplace}{GEN x, GEN y, ulong p} replaces $x$ by $x-y$. 4377 4378\fun{ulong}{Flv_dotproduct}{GEN x, GEN y, ulong p} returns the scalar product 4379of \kbd{x} and \kbd{y} 4380 4381\fun{ulong}{Flv_dotproduct_pre}{GEN x, GEN y, ulong p, ulong pi} returns the 4382scalar product of \kbd{x} and \kbd{y} assuming $pi$ is the pseudo inverse of 4383$p$. 4384 4385\fun{GEN}{Flv_factorback}{GEN L, GEN e, ulong p} given an \kbd{Flv} $L$ 4386and a \kbd{zv} $e$ of the same length, return $\prod_i L_i^{e_i}$ modulo $p$. 4387 4388\fun{ulong}{Flv_sum}{GEN x, ulong p} returns the sum of the components of $x$. 4389 4390\fun{ulong}{Flv_prod}{GEN x, ulong p} returns the product of the components of 4391$x$. 4392 4393\fun{ulong}{Flv_prod_pre}{GEN x, ulong p, ulong pi} as \kbd{Flv\_prod} 4394assuming $pi$ is the pseudo inverse of $p$. 4395 4396\fun{GEN}{Flv_inv}{GEN x, ulong p} returns the vector of inverses of the elements 4397of $x$ (as a \kbd{Flv}). Use Montgomery trick. 4398 4399\fun{void}{Flv_inv_inplace}{GEN x, ulong p} in place variant of \kbd{Flv\_inv}. 4400 4401\fun{GEN}{Flv_inv_pre}{GEN x, ulong p, ulong pi} as \kbd{Flv\_inv} 4402assuming $pi$ is the pseudo inverse of $p$. 4403 4404\fun{void}{Flv_inv_pre_inplace}{GEN x, ulong p, ulong pi} in place variant of 4405\kbd{Flv\_inv}. 4406 4407\fun{GEN}{Flc_FpV_mul}{GEN x, GEN y, GEN p} multiplies $x$ 4408(seen as a column vector) by $y$ (seen as a row vector, 4409assumed to have compatible dimensions) to obtain an \kbd{Flm}. 4410 4411\fun{GEN}{zero_Flm}{long m, long n} creates a \kbd{Flm} with \kbd{m} x \kbd{n} 4412components set to $0$. Note that the result allocates a 4413\emph{single} column, so modifying an entry in one column modifies it in 4414all columns. 4415 4416\fun{GEN}{zero_Flm_copy}{long m, long n} creates a \kbd{Flm} with \kbd{m} x 4417\kbd{n} components set to $0$. 4418 4419\fun{GEN}{zero_Flv}{long n} creates a \kbd{Flv} with \kbd{n} components set to 4420$0$. 4421 4422\fun{GEN}{Flm_row}{GEN A, long x0} return $A[i,]$, the $i$-th row of the 4423\kbd{Flm} $A$. 4424 4425\fun{GEN}{Flm_add}{GEN x, GEN y, ulong p} adds \kbd{x} and \kbd{y} 4426(assumed to have compatible dimensions). 4427 4428\fun{GEN}{Flm_sub}{GEN x, GEN y, ulong p} subtracts \kbd{x} and \kbd{y} 4429(assumed to have compatible dimensions). 4430 4431\fun{GEN}{Flm_mul}{GEN x, GEN y, ulong p} multiplies \kbd{x} and \kbd{y} 4432(assumed to have compatible dimensions). 4433 4434\fun{GEN}{Flm_mul_pre}{GEN x, GEN y, ulong p, ulong pi} multiplies \kbd{x} and 4435\kbd{y} (assumed to have compatible dimensions), assuming $pi$ is the pseudo 4436inverse of $p$. 4437 4438\fun{GEN}{Flm_powers}{GEN x, ulong n, ulong p} returns 4439$[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ as a \typ{VEC} of \kbd{Flm}s. 4440 4441\fun{GEN}{Flm_powu}{GEN x, ulong n, ulong p} computes $x^n$ where $x$ is a 4442square \kbd{Flm}. 4443 4444\fun{GEN}{Flm_charpoly}{GEN x, ulong p} return the characteristic polynomial of 4445the square \kbd{Flm} $x$, as a \kbd{Flx}. 4446 4447\fun{GEN}{Flm_deplin}{GEN x, ulong p} 4448 4449\fun{ulong}{Flm_det}{GEN x, ulong p} 4450 4451\fun{ulong}{Flm_det_sp}{GEN x, ulong p}, as \kbd{Flm\_det}, in place 4452(destroys~\kbd{x}). 4453 4454\fun{GEN}{Flm_gauss}{GEN a, GEN b, ulong p} as \kbd{gauss}, where $b$ is a 4455\kbd{Flm}. 4456 4457\fun{GEN}{Flm_Flc_gauss}{GEN a, GEN b, ulong p} as \kbd{gauss}, where $b$ is 4458a \kbd{Flc}. 4459 4460\fun{GEN}{Flm_indexrank}{GEN x, ulong p} 4461 4462\fun{GEN}{Flm_inv}{GEN x, ulong p} 4463 4464\fun{GEN}{Flm_adjoint}{GEN x, ulong p} as \kbd{matadjoint}. 4465 4466\fun{GEN}{Flm_Flc_invimage}{GEN A, GEN y, ulong p} given an \kbd{Flm} 4467$A$ and an \kbd{Flc} $y$, returns an $x$ such that $Ax = y$, or \kbd{NULL} 4468if no such vector exist. 4469 4470\fun{GEN}{Flm_invimage}{GEN A, GEN y, ulong p} 4471given two \kbd{Flm} $A$ and $y$, returns $x$ such that $Ax = y$, or \kbd{NULL} 4472if no such matrix exist. 4473 4474\fun{GEN}{Flm_ker}{GEN x, ulong p} 4475 4476\fun{GEN}{Flm_ker_sp}{GEN x, ulong p, long deplin}, as \kbd{Flm\_ker} (if 4477\kbd{deplin=0}) or \kbd{Flm\_deplin} (if \kbd{deplin=1}) , in place 4478(destroys~\kbd{x}). 4479 4480\fun{long}{Flm_rank}{GEN x, ulong p} 4481 4482\fun{long}{Flm_suppl}{GEN x, ulong p} 4483 4484\fun{GEN}{Flm_image}{GEN x, ulong p} 4485 4486\fun{GEN}{Flm_intersect}{GEN x, GEN y, ulong p} 4487 4488\fun{GEN}{Flm_transpose}{GEN x} 4489 4490\fun{GEN}{Flm_hess}{GEN x, ulong p} upper Hessenberg form of $x$ over $\F_p$. 4491 4492\subsec{\kbd{F2c} / \kbd{F2v}, \kbd{F2m}} An \kbd{F2v}~\kbd{v} is a 4493\typ{VECSMALL} representing a vector over $\F_2$. Specifically \kbd{z[0]} is 4494the usual codeword, \kbd{z[1]} is the number of components of $v$ and the 4495coefficients are given by the bits of remaining words by increasing indices. 4496 4497\fun{ulong}{F2v_coeff}{GEN x, long i} returns the coefficient $i\ge 1$ of $x$. 4498 4499\fun{void}{F2v_clear}{GEN x, long i} sets the coefficient $i\ge 1$ of $x$ to 4500$0$. 4501 4502\fun{int}{F2v_equal0}{GEN x} returns $1$ if all entries are $0$, and return 4503$0$ otherwise. 4504 4505\fun{void}{F2v_flip}{GEN x, long i} adds $1$ to the coefficient $i\ge 1$ of $x$. 4506 4507\fun{void}{F2v_set}{GEN x, long i} sets the coefficient $i\ge 1$ of $x$ to $1$. 4508 4509\fun{void}{F2v_copy}{GEN x} returns a copy of $x$. 4510 4511\fun{GEN}{F2v_slice}{GEN x, long a, long b} returns the \kbd{F2v} with 4512entries $x[a]$, \dots, $x[b]$. Assumes $a \leq b$. 4513 4514\fun{ulong}{F2m_coeff}{GEN x, long i, long j} returns the coefficient $(i,j)$ 4515of $x$. 4516 4517\fun{void}{F2m_clear}{GEN x, long i, long j} sets the coefficient $(i,j)$ of $x$ 4518to $0$. 4519 4520\fun{void}{F2m_flip}{GEN x, long i, long j} adds $1$ to the coefficient $(i,j)$ 4521of $x$. 4522 4523\fun{void}{F2m_set}{GEN x, long i, long j} sets the coefficient $(i,j)$ of $x$ 4524to $1$. 4525 4526\fun{GEN}{F2m_copy}{GEN x} returns a copy of $x$. 4527 4528\fun{GEN}{F2m_transpose}{GEN x} returns the transpose of $x$. 4529 4530\fun{GEN}{F2m_row}{GEN x, long j} returns the \kbd{F2v} which corresponds 4531to the $j$-th row of the \kbd{F2m} $x$. 4532 4533\fun{GEN}{F2m_rowslice}{GEN x, long a, long b} returns the \kbd{F2m} built 4534from the $a$-th to $b$-th rows of the \kbd{F2m} $x$. Assumes $a \leq b$. 4535 4536\fun{GEN}{F2m_F2c_mul}{GEN x, GEN y} multiplies \kbd{x} and \kbd{y} (assumed 4537to have compatible dimensions). 4538 4539\fun{GEN}{F2m_image}{GEN x} gives a subset of the columns of $x$ that generate 4540the image of $x$. 4541 4542\fun{GEN}{F2m_invimage}{GEN A, GEN B} 4543 4544\fun{GEN}{F2m_F2c_invimage}{GEN A, GEN y} 4545 4546\fun{GEN}{F2m_gauss}{GEN a, GEN b} 4547as \kbd{gauss}, where $b$ is a \kbd{F2m}. 4548 4549\fun{GEN}{F2m_F2c_gauss}{GEN a, GEN b} 4550as \kbd{gauss}, where $b$ is a \kbd{F2c}. 4551 4552 4553\fun{GEN}{F2m_indexrank}{GEN x} $x$ being a matrix of rank $r$, returns a 4554vector with two \typ{VECSMALL} components $y$ and $z$ of length $r$ giving a 4555list of rows and columns respectively (starting from 1) such that the extracted 4556matrix obtained from these two vectors using \kbd{vecextract}$(x,y,z)$ is 4557invertible. 4558 4559\fun{GEN}{F2m_mul}{GEN x, GEN y} multiplies \kbd{x} and \kbd{y} (assumed to 4560have compatible dimensions). 4561 4562\fun{GEN}{F2m_powu}{GEN x, ulong n} computes $x^n$ where $x$ is a square 4563\kbd{F2m}. 4564 4565\fun{long}{F2m_rank}{GEN x} as \kbd{rank}. 4566 4567\fun{long}{F2m_suppl}{GEN x} as \kbd{suppl}. 4568 4569\fun{GEN}{matid_F2m}{long n} returns an \kbd{F2m} which is an $n \times n$ 4570identity matrix. 4571 4572\fun{GEN}{zero_F2v}{long n} creates a \kbd{F2v} with \kbd{n} components set to 4573$0$. 4574 4575\fun{GEN}{const_F2v}{long n} creates a \kbd{F2v} with \kbd{n} components set to 4576$1$. 4577 4578\fun{GEN}{F2v_ei}{long n, long i} creates a \kbd{F2v} with \kbd{n} components 4579set to $0$, but for the $i$-th one, which is set to $1$ ($i$-th vector in the 4580canonical basis). 4581 4582\fun{GEN}{zero_F2m}{long m, long n} creates a \kbd{Flm} with \kbd{m} x \kbd{n} 4583components set to $0$. Note that the result allocates a 4584\emph{single} column, so modifying an entry in one column modifies it in 4585all columns. 4586 4587\fun{GEN}{zero_F2m_copy}{long m, long n} creates a \kbd{F2m} with \kbd{m} x 4588\kbd{n} components set to $0$. 4589 4590\fun{GEN}{F2v_to_Flv}{GEN x} 4591 4592\fun{GEN}{F2c_to_ZC}{GEN x} 4593 4594\fun{GEN}{ZV_to_F2v}{GEN x} 4595 4596\fun{GEN}{RgV_to_F2v}{GEN x} 4597 4598\fun{GEN}{F2m_to_Flm}{GEN x} 4599 4600\fun{GEN}{F2m_to_ZM}{GEN x} 4601 4602\fun{GEN}{Flv_to_F2v}{GEN x} 4603 4604\fun{GEN}{Flm_to_F2m}{GEN x} 4605 4606\fun{GEN}{ZM_to_F2m}{GEN x} 4607 4608\fun{GEN}{RgM_to_F2m}{GEN x} 4609 4610\fun{void}{F2v_add_inplace}{GEN x, GEN y} replaces $x$ by $x+y$. It is 4611allowed for $y$ to be shorter than $x$. 4612 4613\fun{void}{F2v_and_inplace}{GEN x, GEN y} replaces $x$ by the term-by term product 4614of $x$ and $y$ (which is the logical \kbd{and}). It is allowed for $y$ to be 4615shorter than $x$. 4616 4617\fun{void}{F2v_negimply_inplace}{GEN x, GEN y} replaces $x$ by the term-by term 4618logical \kbd{and not} of $x$ and $y$. It is allowed for $y$ to be 4619shorter than $x$. 4620 4621\fun{void}{F2v_or_inplace}{GEN x, GEN y} replaces $x$ by the term-by term 4622logical \kbd{or} of $x$ and $y$. It is allowed for $y$ to be 4623shorter than $x$. 4624 4625\fun{ulong}{F2v_hamming}{GEN x} returns the Hamming weight of \kbd{x}, that is 4626the number of nonzero entries. 4627 4628\fun{ulong}{F2m_det}{GEN x} 4629 4630\fun{ulong}{F2m_det_sp}{GEN x}, as \kbd{F2m\_det}, in place (destroys~\kbd{x}). 4631 4632\fun{GEN}{F2m_deplin}{GEN x} 4633 4634\fun{ulong}{F2v_dotproduct}{GEN x, GEN y} returns the scalar product of \kbd{x} 4635and \kbd{y} 4636 4637\fun{GEN}{F2m_inv}{GEN x} 4638 4639\fun{GEN}{F2m_ker}{GEN x} 4640 4641\fun{GEN}{F2m_ker_sp}{GEN x, long deplin}, as \kbd{F2m\_ker} (if 4642\kbd{deplin=0}) or \kbd{F2m\_deplin} (if \kbd{deplin=1}), in place 4643(destroys~\kbd{x}). 4644 4645\subsec{\kbd{FlxqV}, \kbd{FlxqC}, \kbd{FlxqM}} 4646See \kbd{FqV}, \kbd{FqC}, \kbd{FqM} operations. 4647 4648\fun{GEN}{FlxqV_dotproduct}{GEN x, GEN y, GEN T, ulong p} as 4649\kbd{FpV\_dotproduct}. 4650 4651\fun{GEN}{FlxM_Flx_add_shallow}{GEN x, GEN y, ulong p} as 4652\kbd{RgM\_Rg\_add\_shallow}. 4653 4654\fun{GEN}{FlxqC_Flxq_mul}{GEN x, GEN y, GEN T, ulong p} 4655 4656\fun{GEN}{FlxqM_Flxq_mul}{GEN x, GEN y, GEN T, ulong p} 4657 4658\fun{GEN}{FlxqM_FlxqC_gauss}{GEN a, GEN b, GEN T, ulong p} 4659 4660\fun{GEN}{FlxqM_FlxqC_invimage}{GEN a, GEN b, GEN T, ulong p} 4661 4662\fun{GEN}{FlxqM_FlxqC_mul}{GEN a, GEN b, GEN T, ulong p} 4663 4664\fun{GEN}{FlxqM_deplin}{GEN x, GEN T, ulong p} 4665 4666\fun{GEN}{FlxqM_det}{GEN x, GEN T, ulong p} 4667 4668\fun{GEN}{FlxqM_gauss}{GEN a, GEN b, GEN T, ulong p} 4669 4670\fun{GEN}{FlxqM_image}{GEN x, GEN T, ulong p} 4671 4672\fun{GEN}{FlxqM_indexrank}{GEN x, GEN T, ulong p} 4673 4674\fun{GEN}{FlxqM_inv}{GEN x, GEN T, ulong p} 4675 4676\fun{GEN}{FlxqM_invimage}{GEN a, GEN b, GEN T, ulong p} 4677 4678\fun{GEN}{FlxqM_ker}{GEN x, GEN T, ulong p} 4679 4680\fun{GEN}{FlxqM_mul}{GEN a, GEN b, GEN T, ulong p} 4681 4682\fun{long}{FlxqM_rank}{GEN x, GEN T, ulong p} 4683 4684\fun{GEN}{FlxqM_suppl}{GEN x, GEN T, ulong p} 4685 4686\fun{GEN}{matid_FlxqM}{long n, GEN T, ulong p} 4687 4688\subsec{\kbd{FpX}} Let \kbd{p} an understood \typ{INT}, to be given in 4689the function arguments; in practice \kbd{p} is not assumed to be prime, but 4690be wary. Recall than an \kbd{Fp} object is a \typ{INT}, preferably belonging 4691to $[0, \kbd{p}-1]$; an \kbd{FpX} is a \typ{POL} in a fixed variable whose 4692coefficients are \kbd{Fp} objects. Unless mentioned otherwise, all outputs in 4693this section are \kbd{FpX}s. All operations are understood to take place in 4694$(\Z/\kbd{p}\Z)[X]$. 4695 4696\subsubsec{Conversions} In what follows \kbd{p} is always a \typ{INT}, 4697not necessarily prime. 4698 4699\fun{int}{RgX_is_FpX}{GEN z, GEN *p}, \kbd{z} a \typ{POL}, 4700checks if it can be mapped to a \kbd{FpX}, by checking \kbd{Rg\_is\_Fp} 4701coefficientwise. 4702 4703\fun{GEN}{RgX_to_FpX}{GEN z, GEN p}, \kbd{z} a \typ{POL}, returns the 4704\kbd{FpX} obtained by applying \kbd{Rg\_to\_Fp} coefficientwise. 4705 4706\fun{GEN}{FpX_red}{GEN z, GEN p}, \kbd{z} a \kbd{ZX}, returns \kbd{lift(z * 4707Mod(1,p))}, normalized. 4708 4709\fun{GEN}{FpXV_red}{GEN z, GEN p}, \kbd{z} a \typ{VEC} of \kbd{ZX}. Applies 4710\kbd{FpX\_red} componentwise and returns the result (and we obtain a vector 4711of \kbd{FpX}s). 4712 4713\fun{GEN}{FpXT_red}{GEN z, GEN p}, \kbd{z} a tree of \kbd{ZX}. Applies 4714\kbd{FpX\_red} to each leaf and returns the result (and we obtain a tree 4715of \kbd{FpX}s). 4716 4717\subsubsec{Basic operations} In what follows \kbd{p} is always a \typ{INT}, 4718not necessarily prime. 4719 4720\noindent Now, except for \kbd{p}, the operands and outputs are all \kbd{FpX} 4721objects. Results are undefined on other inputs. 4722 4723\fun{GEN}{FpX_add}{GEN x,GEN y, GEN p} adds \kbd{x} and \kbd{y}. 4724 4725\fun{GEN}{FpX_neg}{GEN x,GEN p} returns $-\kbd{x}$, the components are 4726between $0$ and $p$ if this is the case for the components of $x$. 4727 4728\fun{GEN}{FpX_renormalize}{GEN x, long l}, as \kbd{normalizepol}, where 4729$\kbd{l} = \kbd{lg(x)}$, in place. 4730 4731\fun{GEN}{FpX_sub}{GEN x,GEN y,GEN p} returns $x-y$. 4732 4733\fun{GEN}{FpX_halve}{GEN x, GEN p} returns $z$ such that $2\*z = x$ modulo 4734$p$ assuming such $z$ exists. 4735 4736\fun{GEN}{FpX_mul}{GEN x,GEN y,GEN p} returns $x\*y$. 4737 4738\fun{GEN}{FpX_mulspec}{GEN a, GEN b, GEN p, long na, long nb} 4739see \kbd{ZX\_mulspec} 4740 4741\fun{GEN}{FpX_sqr}{GEN x,GEN p} returns $\kbd{x}^2$. 4742 4743\fun{GEN}{FpX_powu}{GEN x, ulong n, GEN p} returns $x^n$. 4744 4745\fun{GEN}{FpX_convol}{GEN x, GEN y, GEN p} return the-term by-term product of $x$ 4746and $y$. 4747 4748\fun{GEN}{FpX_divrem}{GEN x, GEN y, GEN p, GEN *pr} returns the quotient 4749of \kbd{x} by \kbd{y}, and sets \kbd{pr} to the remainder. 4750 4751\fun{GEN}{FpX_div}{GEN x, GEN y, GEN p} returns the quotient of \kbd{x} by 4752\kbd{y}. 4753 4754\fun{GEN}{FpX_div_by_X_x}{GEN A, GEN a, GEN p, GEN *r} returns the 4755quotient of the \kbd{FpX}~\kbd{A} by $(X - \kbd{a})$, and sets \kbd{r} to the 4756remainder $\kbd{A}(\kbd{a})$. 4757 4758\fun{GEN}{FpX_rem}{GEN x, GEN y, GEN p} returns the remainder \kbd{x} mod 4759\kbd{y}. 4760 4761\fun{long}{FpX_valrem}{GEN x, GEN t, GEN p, GEN *r} The arguments \kbd{x} and 4762\kbd{e} being nonzero \kbd{FpX} returns the highest exponent $e$ such that 4763$\kbd{t}^{e}$ divides~\kbd{x}. The quotient $\kbd{x}/\kbd{t}^{e}$ is returned 4764in~\kbd{*r}. In particular, if \kbd{t} is irreducible, this returns the 4765valuation at \kbd{t} of~\kbd{x}, and \kbd{*r} is the prime-to-\kbd{t} part 4766of~\kbd{x}. 4767 4768\fun{GEN}{FpX_deriv}{GEN x, GEN p} returns the derivative of \kbd{x}. 4769This function is not memory-clean, but nevertheless suitable for 4770\kbd{gerepileupto}. 4771 4772\fun{GEN}{FpX_integ}{GEN x, GEN p} returns the primitive of \kbd{x} whose 4773constant term is $0$. 4774 4775\fun{GEN}{FpX_digits}{GEN x, GEN B, GEN p} returns a vector of \kbd{FpX} 4776$[c_0,\ldots,c_n]$ of degree less than the degree of $B$ and such that 4777$x=\sum_{i=0}^{n}{c_i\*B^i}$. 4778 4779\fun{GEN}{FpXV_FpX_fromdigits}{GEN v, GEN B, GEN p} where $v=[c_0,\ldots,c_n]$ 4780is a vector of \kbd{FpX}, returns $\sum_{i=0}^{n}{c_i\*B^i}$. 4781 4782\fun{GEN}{FpX_translate}{GEN P, GEN c, GEN p} let $c$ be an \kbd{Fp} and let 4783$P$ be an \kbd{FpX}; returns the translated \kbd{FpX} of $P(X+c)$. 4784 4785\fun{GEN}{FpX_gcd}{GEN x, GEN y, GEN p} returns a (not necessarily monic) 4786greatest common divisor of $x$ and $y$. 4787 4788\fun{GEN}{FpX_halfgcd}{GEN x, GEN y, GEN p} returns a two-by-two \kbd{FpXM} 4789$M$ with determinant $\pm 1$ such that the image $(a,b)$ of $(x,y)$ by $M$ 4790has the property that $\deg a \geq {\deg x \over 2} > \deg b$. 4791 4792\fun{GEN}{FpX_extgcd}{GEN x, GEN y, GEN p, GEN *u, GEN *v} returns 4793$d = \text{GCD}(\kbd{x},\kbd{y})$ (not necessarily monic), and sets \kbd{*u}, 4794\kbd{*v} to the Bezout coefficients such that $\kbd{*ux} + \kbd{*vy} = d$. 4795If \kbd{*u} is set to \kbd{NULL}, it is not computed which is a bit faster. 4796This is useful when computing the inverse of $y$ modulo $x$. 4797 4798\fun{GEN}{FpX_center}{GEN z, GEN p, GEN pov2} returns the polynomial whose 4799coefficient belong to the symmetric residue system. Assumes the coefficients 4800already belong to $]-p/2, p[$ and that \kbd{pov2} is \kbd{shifti(p,-1)}. 4801 4802\fun{GEN}{FpX_center_i}{GEN z, GEN p, GEN pov2} internal variant of 4803\tet{FpX_center}, not \kbd{gerepile}-safe. 4804 4805\fun{GEN}{FpX_Frobenius}{GEN T, GEN p} returns $X^{p}\pmod{T(X)}$. 4806 4807\fun{GEN}{FpX_matFrobenius}{GEN T, GEN p} returns the matrix of the 4808Frobenius automorphism $x\mapsto x^p$ over the power basis of $\F_p[X]/(T)$. 4809 4810\subsubsec{Mixed operations} 4811The following functions implement arithmetic operations between \kbd{FpX} 4812and \kbd{Fp} operands, the result being of type \kbd{FpX}. The integer 4813\kbd{p} need not be prime. 4814 4815\fun{GEN}{Z_to_FpX}{GEN x, GEN p, long v} converts a \typ{INT} to a scalar 4816polynomial in variable $v$, reduced modulo $p$. 4817 4818\fun{GEN}{FpX_Fp_add}{GEN y, GEN x, GEN p} add the \kbd{Fp}~\kbd{x} to the 4819\kbd{FpX}~\kbd{y}. 4820 4821\fun{GEN}{FpX_Fp_add_shallow}{GEN y, GEN x, GEN p} add the \kbd{Fp}~\kbd{x} 4822to the \kbd{FpX}~\kbd{y}, using a shallow copy (result not suitable for 4823\kbd{gerepileupto}) 4824 4825\fun{GEN}{FpX_Fp_sub}{GEN y, GEN x, GEN p} subtract the \kbd{Fp}~\kbd{x} from 4826the \kbd{FpX}~\kbd{y}. 4827 4828\fun{GEN}{FpX_Fp_sub_shallow}{GEN y, GEN x, GEN p} subtract the 4829\kbd{Fp}~\kbd{x} from the \kbd{FpX}~\kbd{y}, using a shallow copy (result not 4830suitable for \kbd{gerepileupto}) 4831 4832\fun{GEN}{Fp_FpX_sub}{GEN x,GEN y,GEN p} returns $x - y$, where $x$ is 4833a \typ{INT} and $y$ an \kbd{FpX}. 4834 4835\fun{GEN}{FpX_Fp_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{FpX}~\kbd{x} 4836by the \kbd{Fp}~\kbd{y}. 4837 4838\fun{GEN}{FpX_Fp_mulspec}{GEN x, GEN y, GEN p, long lx} see \kbd{ZX\_mulspec} 4839 4840\fun{GEN}{FpX_mulu}{GEN x, ulong y, GEN p} multiplies the \kbd{FpX}~\kbd{x} 4841by \kbd{y}. 4842 4843\fun{GEN}{FpX_Fp_mul_to_monic}{GEN y,GEN x,GEN p} returns $y\*x$ assuming the 4844result is monic of the same degree as $y$ (in particular $x\neq 0$). 4845 4846\fun{GEN}{FpX_Fp_div}{GEN x, GEN y, GEN p} divides the \kbd{FpX}~\kbd{x} 4847by the \kbd{Fp}~\kbd{y}. 4848 4849\fun{GEN}{FpX_divu}{GEN x, ulong y, GEN p} divides the \kbd{FpX}~\kbd{x} 4850by \kbd{y}. 4851 4852\subsubsec{Miscellaneous operations} 4853 4854\fun{GEN}{FpX_normalize}{GEN z, GEN p} divides the \kbd{FpX}~\kbd{z} by its 4855leading coefficient. If the latter is~$1$, \kbd{z} itself is returned, not a 4856copy. If not, the inverse remains uncollected on the stack. 4857 4858\fun{GEN}{FpX_invBarrett}{GEN T, GEN p}, returns the Barrett inverse 4859$M$ of $T$ defined by $M(x)\*x^n\*T(1/x)\equiv 1\pmod{x^{n-1}}$ where $n$ is 4860the degree of $T$. 4861 4862\fun{GEN}{FpX_rescale}{GEN P, GEN h, GEN p} returns $h^{\deg(P)} P(x/h)$. 4863\kbd{P} is an \kbd{FpX} and \kbd{h} is a nonzero \kbd{Fp} (the routine would 4864work with any nonzero \typ{INT} but is not efficient in this case). 4865Neither memory-clean nor suitable for \kbd{gerepileupto}. 4866 4867\fun{GEN}{FpX_eval}{GEN x, GEN y, GEN p} evaluates the \kbd{FpX}~\kbd{x} 4868at the \kbd{Fp}~\kbd{y}. The result is an~\kbd{Fp}. 4869 4870\fun{GEN}{FpX_FpV_multieval}{GEN P, GEN v, GEN p} returns the vector 4871$[P(v[1]),\ldots,P(v[n])]$ as a \kbd{FpV}. 4872 4873\fun{GEN}{FpX_dotproduct}{GEN x, GEN y, GEN p} return the scalar product 4874$\sum_{i\geq 0} x_i\*y_i$ of the coefficients of $x$ and $y$. 4875 4876\fun{GEN}{FpXV_FpC_mul}{GEN V, GEN W, GEN p} multiplies a nonempty line 4877vector of\kbd{FpX} by a column vector of \kbd{Fp} of compatible dimensions. 4878The result is an~\kbd{FpX}. 4879 4880\fun{GEN}{FpXV_prod}{GEN V, GEN p}, \kbd{V} being a vector of \kbd{FpX}, 4881returns their product. 4882 4883\fun{GEN}{FpV_roots_to_pol}{GEN V, GEN p, long v}, \kbd{V} being a vector 4884of \kbd{INT}s, returns the monic \kbd{FpX} 4885$\prod_i (\kbd{pol\_x[v]} - \kbd{V[i]})$. 4886 4887\fun{GEN}{FpX_chinese_coprime}{GEN x,GEN y, GEN Tx,GEN Ty, GEN Tz, GEN p}: 4888returns an \kbd{FpX}, congruent to \kbd{x} mod \kbd{Tx} and to \kbd{y} mod 4889\kbd{Ty}. Assumes \kbd{Tx} and \kbd{Ty} are coprime, and \kbd{Tz = Tx * Ty} 4890or \kbd{NULL} (in which case it is computed within). 4891 4892\fun{GEN}{FpV_polint}{GEN x, GEN y, GEN p, long v} returns the \kbd{FpX} 4893interpolation polynomial with value \kbd{y[i]} at \kbd{x[i]}. Assumes lengths 4894are the same, components are \typ{INT}s, and the \kbd{x[i]} are distinct 4895modulo \kbd{p}. 4896 4897\fun{GEN}{FpV_FpM_polint}{GEN x, GEN V, GEN p, long v} equivalent (but 4898faster) to applying \kbd{FpV\_polint(x,$\ldots$)} to all the elements of the 4899vector $V$ (thus, returns a \kbd{FpXV}). 4900 4901\fun{GEN}{FpX_FpXV_multirem}{GEN A, GEN P, GEN p} 4902given a \kbd{FpX} $A$ and a vector $P$ of pairwise coprime \kbd{FpX} of length 4903$n\ge 1$, return a vector $B$ of the same length such that $B[i] = 4904A\pmod{P[i]}$ and $B[i]$ of minimal degree for all $1\leq i\leq n$. 4905 4906\fun{GEN}{FpXV_chinese}{GEN A, GEN P, GEN p, GEN *pM} 4907let $P$ be a vector of pairwise coprime \kbd{FpX}, let $A$ be a vector of 4908\kbd{FpX} of the same length $n\ge 1$ and let $M$ be the product of the 4909elements of $P$. Returns a \kbd{FpX} of minimal degree congruent to $A[i]$ mod 4910$P[i]$ for all $1\leq i\leq n$. 4911If \kbd{pM} is not \kbd{NULL}, set \kbd{*pM} to $M$. 4912 4913\fun{GEN}{FpV_invVandermonde}{GEN L, GEN d, GEN p} $L$ being a \kbd{FpV} 4914of length $n$, return the inverse $M$ of the Vandermonde matrix attached to 4915the elements of $L$, eventually multiplied by \kbd{d} if it is not 4916\kbd{NULL}. If $A$ is a \kbd{FpV} and $B=M\*A$, then the polynomial 4917$P=\sum_{i=1}^n B[i]\*X^{i-1}$ verifies $P(L[i])=d\*A[i]$ for 4918$1 \leq i \leq n$. 4919 4920\fun{int}{FpX_is_squarefree}{GEN f, GEN p} returns $1$ if the 4921\kbd{FpX}~\kbd{f} is squarefree, $0$ otherwise. 4922 4923\fun{int}{FpX_is_irred}{GEN f, GEN p} returns $1$ if the \kbd{FpX}~\kbd{f} 4924is irreducible, $0$ otherwise. Assumes that \kbd{p} is prime. If~\kbd{f} has 4925few factors, \kbd{FpX\_nbfact(f,p) == 1} is much faster. 4926 4927\fun{int}{FpX_is_totally_split}{GEN f, GEN p} returns $1$ if the 4928\kbd{FpX}~\kbd{f} splits into a product of distinct linear factors, $0$ 4929otherwise. Assumes that \kbd{p} is prime. The $0$ polynomial is not 4930totally split. 4931 4932\fun{long}{FpX_ispower}{GEN f, ulong k, GEN p, GEN *pt} 4933return $1$ if the \kbd{FpX} $f$ is a $k$-th power, $0$ otherwise. 4934If \kbd{pt} is not \kbd{NULL}, set it to $g$ such that $g^k = f$. 4935 4936\fun{GEN}{FpX_factor}{GEN f, GEN p}, factors the \kbd{FpX}~\kbd{f}. Assumes 4937that \kbd{p} is prime. The returned value \kbd{v} is a \typ{VEC} with two 4938components: \kbd{v[1]} is a vector of distinct irreducible (\kbd{FpX}) 4939factors, and \kbd{v[2]} is a \typ{VECSMALL} of corresponding exponents. The 4940order of the factors is deterministic (the computation is not). 4941 4942\fun{GEN}{FpX_factor_squarefree}{GEN f, GEN p} returns the squarefree 4943factorization of $f$ modulo $p$. This is a vector $[u_1,\dots,u_k]$ 4944of squarefree and pairwise coprime \kbd{FpX} such that $u_k \neq 1$ and $f = 4945\prod u_i^i$. The other~$u_i$ may equal~$1$. 4946Shallow function. 4947 4948\fun{GEN}{FpX_ddf}{GEN f, GEN p} assuming that $f$ is squarefree, 4949returns the distinct degree factorization of $f$ modulo $p$. 4950The returned value \kbd{v} is a \typ{VEC} with two 4951components: \kbd{F=v[1]} is a vector of (\kbd{FpX}) 4952factors, and \kbd{E=v[2]} is a \typ{VECSMALL}, such that 4953$f$ is equal to the product of the \kbd{F[i]} and each \kbd{F[i]} 4954is a product of irreducible factors of degree \kbd{E[i]}. 4955 4956\fun{long}{FpX_ddf_degree}{GEN f, GEN XP, GEN p} assuming that $f$ is squarefree 4957and that all its factors have the same degree, return the common degree, 4958where \kbd{XP} is \kbd{FpX\_Frobenius(f, p)}. 4959 4960\fun{long}{FpX_nbfact}{GEN f, GEN p}, assuming the \kbd{FpX}~f is squarefree, 4961returns the number of its irreducible factors. Assumes that \kbd{p} is prime. 4962 4963\fun{long}{FpX_nbfact_Frobenius}{GEN f, GEN XP, GEN p}, as 4964\kbd{FpX\_nbfact(f, p)} but faster, 4965where \kbd{XP} is \kbd{FpX\_Frobenius(f, p)}. 4966 4967\fun{GEN}{FpX_degfact}{GEN f, GEN p}, as \kbd{FpX\_factor}, but the 4968degrees of the irreducible factors are returned instead of the factors 4969themselves (as a \typ{VECSMALL}). Assumes that \kbd{p} is prime. 4970 4971\fun{long}{FpX_nbroots}{GEN f, GEN p} returns the number of distinct 4972roots in \kbd{\Z/p\Z} of the \kbd{FpX}~\kbd{f}. Assumes that \kbd{p} is prime. 4973 4974\fun{GEN}{FpX_oneroot}{GEN f, GEN p} returns one root in \kbd{\Z/p\Z} of 4975the \kbd{FpX}~\kbd{f}. Return \kbd{NULL} if no root exists. 4976Assumes that \kbd{p} is prime. 4977 4978\fun{GEN}{FpX_oneroot_split}{GEN f, GEN p} as \kbd{FpX\_oneroot}. 4979Faster when $f$ is close to be totally split. 4980 4981\fun{GEN}{FpX_roots}{GEN f, GEN p} returns the roots in \kbd{\Z/p\Z} of 4982the \kbd{FpX}~\kbd{f} (without multiplicity, as a vector of \kbd{Fp}s). 4983Assumes that \kbd{p} is prime. 4984 4985\fun{GEN}{FpX_split_part}{GEN f, GEN p} returns the largest totally split 4986squarefree factor of $f$. 4987 4988\fun{GEN}{random_FpX}{long d, long v, GEN p} returns a random \kbd{FpX} 4989in variable \kbd{v}, of degree less than~\kbd{d}. 4990 4991\fun{GEN}{FpX_resultant}{GEN x, GEN y, GEN p} returns the resultant 4992of \kbd{x} and \kbd{y}, both \kbd{FpX}. The result is a \typ{INT} 4993belonging to $[0,p-1]$. 4994 4995\fun{GEN}{FpX_disc}{GEN x, GEN p} returns the discriminant 4996of the \kbd{FpX} \kbd{x}. The result is a \typ{INT} belonging to $[0,p-1]$. 4997 4998\fun{GEN}{FpX_FpXY_resultant}{GEN a, GEN b, GEN p}, \kbd{a} a \typ{POL} of 4999\typ{INT}s (say in variable $X$), \kbd{b} a \typ{POL} (say in variable $X$) 5000whose coefficients are either \typ{POL}s in $\Z[Y]$ or \typ{INT}s. 5001Returns $\text{Res}_X(a, b)$ in $\F_p[Y]$ as an \kbd{FpY}. The function 5002assumes that $X$ has lower priority than $Y$. 5003 5004\fun{GEN}{FpX_Newton}{GEN x, long n, GEN p} return 5005$\sum{i=0}^{n-1} \pi_i\*X^i$ where $\pi_i$ is the sum of the $i$th-power 5006of the roots of $x$ in an algebraic closure. 5007 5008\fun{GEN}{FpX_fromNewton}{GEN x, GEN p} recover a polynomial from it 5009s Newton sums given by the coefficients of $x$. 5010This function assumes that $p$ and the accuracy of $x$ as a \kbd{FpXn} is 5011larger than the degree of the solution. 5012 5013\fun{GEN}{FpX_Laplace}{GEN x, GEN p} return 5014$\sum_{i=0}^{n-1} x_i\*i!\*X^i$. 5015 5016\fun{GEN}{FpX_invLaplace}{GEN x, GEN p} return 5017$\sum_{i=0}^{n-1} x_i/{i!}\*X^i$. 5018 5019\subsec{\kbd{FpXQ}, \kbd{Fq}} Let \kbd{p} a \typ{INT} and \kbd{T} an 5020\kbd{FpX} for \kbd{p}, both to be given in the function arguments; an \kbd{FpXQ} 5021object is an \kbd{FpX} whose degree is strictly less than the degree of 5022\kbd{T}. An \kbd{Fq} is either an \kbd{FpXQ} or an \kbd{Fp}. Both represent 5023a class in $(\Z/\kbd{p}\Z)[X] / (T)$, in which all operations below take 5024place. In addition, \kbd{Fq} routines also allow $\kbd{T} = \kbd{NULL}$, in 5025which case no reduction mod \kbd{T} is performed on the result. 5026 5027For efficiency, the routines in this section may leave small unused objects 5028behind on the stack (their output is still suitable for \kbd{gerepileupto}). 5029Besides \kbd{T} and \kbd{p}, arguments are either \kbd{FpXQ} or \kbd{Fq} 5030depending on the function name. (All \kbd{Fq} routines accept \kbd{FpXQ}s by 5031definition, not the other way round.) 5032 5033\subsubsec{Preconditioned reduction} 5034 5035For faster reduction, the modulus $T$ can be replaced by an extended modulus 5036in all \kbd{FpXQ}- and \kbd{Fq}-classes functions, and in \kbd{FpX\_rem} and 5037\kbd{FpX\_divrem}. An extended modulus(\kbd{FpXT}, which is a tree whose leaves are \kbd{FpX})In 5038current implementation, an extended modulus is either a plain modulus (an 5039\kbd{FpX}) or a pair of polynomials, one being the plain modulus $T$ and the 5040other being \tet{FpX_invBarret}$(T,p)$. 5041 5042\fun{GEN}{FpX_get_red}{GEN T, GEN p} returns the extended modulus \kbd{eT}. 5043 5044To write code that works both with plain and extended moduli, the following 5045accessors are defined: 5046 5047\fun{GEN}{get_FpX_mod}{GEN eT} returns the underlying modulus $T$. 5048 5049\fun{GEN}{get_FpX_var}{GEN eT} returns the variable number \kbd{varn}$(T)$. 5050 5051\fun{GEN}{get_FpX_degree}{GEN eT} returns the degree \kbd{degpol}$(T)$. 5052 5053\subsubsec{Conversions} 5054 5055\fun{int}{ff_parse_Tp}{GEN Tp, GEN *T, GEN *p, long red} \kbd{Tp} is either 5056a prime number $p$ or a \typ{VEC} with 2 entries $T$ (an irreducible 5057polynomial mod $p$) and $p$ (a prime number). Sets \kbd{*p} and \kbd{*T} 5058to the corresponding \kbd{GEN}s (\kbd{NULL} if undefined). If \kbd{red} 5059is nonzero, normalize \kbd{*T} as an \kbd{FpX}; on the other hand, 5060to initialize a $p$-adic function, set \kbd{red} to $0$ and \kbd{*T} is left 5061as is and must be a \kbd{ZX} to start with. Return $1$ on success, and $0$ on 5062failure. This helper routine is used by GP functions such as \kbd{factormod} 5063where a single user argument defines a finite field. \typ{FFELT} is not 5064supported. 5065 5066\fun{GEN}{Rg_is_FpXQ}{GEN z, GEN *T, GEN *p}, checks if \kbd{z} is a \kbd{GEN} 5067which can be mapped to $\F_p[X]/(T)$: anything for which \kbd{Rg\_is\_Fp} return 5068$1$, a \typ{POL} for which \kbd{RgX\_to\_FpX} return $1$, a \typ{POLMOD} 5069whose modulus is equal to \kbd{*T} if \kbd{*T} is not \kbd{NULL} (once mapped 5070to a \kbd{FpX}), or a \typ{FFELT} $z$ with the same definition field as \kbd{*T} 5071if \kbd{*T} is not \kbd{NULL} and is a \typ{FFELT}. 5072 5073If an integer modulus is found it is put in \kbd{*p}, else \kbd{*p} is left 5074unchanged. If a polynomial modulus is found it is put in \kbd{*T}, 5075if a \typ{FFELT} $z$ is found, $z$ is put in \kbd{*T}, else 5076\kbd{*T} is left unchanged. 5077 5078\fun{int}{RgX_is_FpXQX}{GEN z, GEN *T, GEN *p}, \kbd{z} a \typ{POL}, 5079checks if it can be mapped to a \kbd{FpXQX}, by checking \kbd{Rg\_is\_FpXQ} 5080coefficientwise. 5081 5082\fun{GEN}{Rg_to_FpXQ}{GEN z, GEN T, GEN p}, \kbd{z} a \kbd{GEN} which can be 5083mapped to $\F_p[X]/(T)$: anything \kbd{Rg\_to\_Fp} can be applied to, 5084a \typ{POL} to which \kbd{RgX\_to\_FpX} can be applied to, a \typ{POLMOD} 5085whose modulus is divisible by $T$ (once mapped to a \kbd{FpX}), a suitable 5086\typ{RFRAC}. Returns \kbd{z} as an \kbd{FpXQ}, normalized. 5087 5088\fun{GEN}{Rg_to_Fq}{GEN z, GEN T, GEN p}, applies \kbd{Rg\_to\_Fp} if $T$ 5089is \kbd{NULL} and \kbd{Rg\_to\_FpXQ} otherwise. 5090 5091\fun{GEN}{RgX_to_FpXQX}{GEN z, GEN T, GEN p}, \kbd{z} a \typ{POL}, returns the 5092\kbd{FpXQ} obtained by applying \kbd{Rg\_to\_FpXQ} coefficientwise. 5093 5094\fun{GEN}{RgX_to_FqX}{GEN z, GEN T, GEN p}: let \kbd{z} be a \typ{POL}; 5095returns the \kbd{FqX} obtained by applying \kbd{Rg\_to\_Fq} coefficientwise. 5096 5097\fun{GEN}{Fq_to_FpXQ}{GEN z, GEN T, GEN p /*unused*/} 5098if $z$ is a \typ{INT}, convert it to a constant polynomial in the variable of 5099$T$, otherwise return $z$ (shallow function). 5100 5101\fun{GEN}{Fq_red}{GEN x, GEN T, GEN p}, \kbd{x} a \kbd{ZX} or \typ{INT}, 5102reduce it to an \kbd{Fq} ($\kbd{T} = \kbd{NULL}$ is allowed iff \kbd{x} is a 5103\typ{INT}). 5104 5105\fun{GEN}{FqX_red}{GEN x, GEN T, GEN p}, \kbd{x} a \typ{POL} 5106whose coefficients are \kbd{ZX}s or \typ{INT}s, reduce them to \kbd{Fq}s. (If 5107$\kbd{T} = \kbd{NULL}$, as \kbd{FpXX\_red(x, p)}.) 5108 5109\fun{GEN}{FqV_red}{GEN x, GEN T, GEN p}, \kbd{x} a vector of \kbd{ZX}s or 5110\typ{INT}s, reduce them to \kbd{Fq}s. (If $\kbd{T} = \kbd{NULL}$, only 5111reduce components mod \kbd{p} to \kbd{FpX}s or \kbd{Fp}s.) 5112 5113\fun{GEN}{FpXQ_red}{GEN x, GEN T,GEN p} \kbd{x} a \typ{POL} 5114whose coefficients are \typ{INT}s, reduce them to \kbd{FpXQ}s. 5115 5116\subsec{\kbd{FpXQ}} 5117 5118\fun{GEN}{FpXQ_add}{GEN x, GEN y, GEN T,GEN p} 5119 5120\fun{GEN}{FpXQ_sub}{GEN x, GEN y, GEN T,GEN p} 5121 5122\fun{GEN}{FpXQ_mul}{GEN x, GEN y, GEN T,GEN p} 5123 5124\fun{GEN}{FpXQ_sqr}{GEN x, GEN T, GEN p} 5125 5126\fun{GEN}{FpXQ_div}{GEN x, GEN y, GEN T,GEN p} 5127 5128\fun{GEN}{FpXQ_inv}{GEN x, GEN T, GEN p} computes the inverse of \kbd{x} 5129 5130\fun{GEN}{FpXQ_invsafe}{GEN x,GEN T,GEN p}, as \kbd{FpXQ\_inv}, returning 5131\kbd{NULL} if \kbd{x} is not invertible. 5132 5133\fun{GEN}{FpXQ_pow}{GEN x, GEN n, GEN T, GEN p} computes $\kbd{x}^\kbd{n}$. 5134 5135\fun{GEN}{FpXQ_powu}{GEN x, ulong n, GEN T, GEN p} computes $\kbd{x}^\kbd{n}$ 5136for small $n$. 5137 5138In the following three functions the integer parameter \kbd{ord} can be given 5139either as a positive \typ{INT} $N$, or as its factorization matrix $\var{faN}$, 5140or as a pair $[N,\var{faN}]$. The parameter may be omitted by setting it to 5141\kbd{NULL} (the value is then $p^d-1$, $d = \deg T$). 5142 5143\fun{GEN}{FpXQ_log}{GEN a, GEN g, GEN ord, GEN T, GEN p} Let \kbd{g} be of 5144order dividing \kbd{ord} in the finite field $\F_p[X]/(T)$, return $e$ such that 5145$a^e=g$. If $e$ does not exists, the result is undefined. Assumes 5146that \kbd{T} is irreducible mod \kbd{p}. 5147 5148\fun{GEN}{Fp_FpXQ_log}{GEN a, GEN g, GEN ord, GEN T, GEN p} As 5149\kbd{FpXQ\_log}, \kbd{a} being a \kbd{Fp}. 5150 5151\fun{GEN}{FpXQ_order}{GEN a, GEN ord, GEN T, GEN p} returns the order of the 5152\kbd{FpXQ} \kbd{a}. Assume that \kbd{ord} is a multiple of the order of 5153\kbd{a}. Assume that \kbd{T} is irreducible mod \kbd{p}. 5154 5155\fun{int}{FpXQ_issquare}{GEN x, GEN T, GEN p} returns $1$ if $x$ is a square 5156and $0$ otherwise. Assumes that \kbd{T} is irreducible mod \kbd{p}. 5157 5158\fun{GEN}{FpXQ_sqrt}{GEN x, GEN T, GEN p} returns a square root of \kbd{x}. 5159Return \kbd{NULL} if \kbd{x} is not a square. 5160 5161\fun{GEN}{FpXQ_sqrtn}{GEN x, GEN n, GEN T, GEN p, GEN *zn} 5162Let $T$be irreducible mod $p$ and $q = p^{\deg T}$; returns \kbd{NULL} if $a$ 5163is not an $n$-th power residue mod $p$. Otherwise, returns an $n$-th root of 5164$a$; if \kbd{zn} is not \kbd{NULL} set it to a primitive $m$-th root of $1$ 5165in $\F_q$, $m = \gcd(q-1,n)$ allowing to compute all $m$ solutions in $\F_q$ 5166of the equation $x^n = a$. 5167 5168\subsec{\kbd{Fq}} 5169 5170\fun{GEN}{Fq_add}{GEN x, GEN y, GEN T/*unused*/, GEN p} 5171 5172\fun{GEN}{Fq_sub}{GEN x, GEN y, GEN T/*unused*/, GEN p} 5173 5174\fun{GEN}{Fq_mul}{GEN x, GEN y, GEN T, GEN p} 5175 5176\fun{GEN}{Fq_Fp_mul}{GEN x, GEN y, GEN T, GEN p} multiplies the \kbd{Fq} $x$ 5177by the \typ{INT} $y$. 5178 5179\fun{GEN}{Fq_mulu}{GEN x, ulong y, GEN T, GEN p} multiplies the \kbd{Fq} $x$ 5180by the scalar $y$. 5181 5182\fun{GEN}{Fq_halve}{GEN x, GEN T, GEN p} returns $z$ such that $2\*z = x$ 5183assuming such $z$ exists. 5184 5185\fun{GEN}{Fq_sqr}{GEN x, GEN T, GEN p} 5186 5187\fun{GEN}{Fq_neg}{GEN x, GEN T, GEN p} 5188 5189\fun{GEN}{Fq_neg_inv}{GEN x, GEN T, GEN p} computes $-\kbd{x}^{-1}$ 5190 5191\fun{GEN}{Fq_inv}{GEN x, GEN pol, GEN p} computes $\kbd{x}^{-1}$, raising an 5192error if \kbd{x} is not invertible. 5193 5194\fun{GEN}{Fq_invsafe}{GEN x, GEN pol, GEN p} as \kbd{Fq\_inv}, but returns 5195\kbd{NULL} if \kbd{x} is not invertible. 5196 5197\fun{GEN}{Fq_div}{GEN x, GEN y, GEN T, GEN p} 5198 5199\fun{GEN}{FqV_inv}{GEN x, GEN T, GEN p} $x$ being a vector of \kbd{Fq}s, 5200return the vector of inverses of the $x[i]$. The routine uses Montgomery's 5201trick, and involves a single inversion, plus $3(N-1)$ multiplications for 5202$N$ entries. The routine is not stack-clean: $2N$ \kbd{FpXQ} are left on 5203stack, besides the $N$ in the result. 5204 5205\fun{GEN}{FqV_factorback}{GEN L, GEN e, GEN T, GEN p} given an \kbd{FqV} $L$ 5206and a \kbd{ZV} or \kbd{zv} $e$ of the same length, return $\prod_i L_i^{e_i}$ 5207modulo $p$. 5208 5209\fun{GEN}{Fq_pow}{GEN x, GEN n, GEN pol, GEN p} returns $\kbd{x}^\kbd{n}$. 5210 5211\fun{GEN}{Fq_powu}{GEN x, ulong n, GEN pol, GEN p} returns $\kbd{x}^\kbd{n}$ 5212for small $n$. 5213 5214\fun{GEN}{Fq_log}{GEN a, GEN g, GEN ord, GEN T, GEN p} as 5215\tet{Fp_log} or \tet{FpXQ_log}. 5216 5217\fun{int}{Fq_issquare}{GEN x, GEN T, GEN p} returns $1$ if $x$ is a square 5218and $0$ otherwise. Assumes that \kbd{T} is irreducible mod \kbd{p} and that 5219$p$ is prime; $T = \kbd{NULL}$ is forbidden unless $x$ is an \kbd{Fp}. 5220 5221\fun{long}{Fq_ispower}{GEN x, GEN n, GEN T, GEN p} returns $1$ if $x$ 5222is a $n$-th power and $0$ otherwise. Assumes that \kbd{T} is irreducible mod 5223\kbd{p} and that $p$ is prime; $T = \kbd{NULL}$ is forbidden unless $x$ is an 5224\kbd{Fp}. 5225 5226\fun{GEN}{Fq_sqrt}{GEN x, GEN T, GEN p} returns a square root of \kbd{x}. 5227Return \kbd{NULL} if \kbd{x} is not a square. 5228 5229\fun{GEN}{Fq_sqrtn}{GEN a, GEN n, GEN T, GEN p, GEN *zn} 5230as \tet{FpXQ_sqrtn}. 5231 5232\fun{GEN}{FpXQ_charpoly}{GEN x, GEN T, GEN p} returns the characteristic 5233polynomial of \kbd{x} 5234 5235\fun{GEN}{FpXQ_minpoly}{GEN x, GEN T, GEN p} returns the minimal polynomial 5236of \kbd{x} 5237 5238\fun{GEN}{FpXQ_norm}{GEN x, GEN T, GEN p} returns the norm of \kbd{x} 5239 5240\fun{GEN}{FpXQ_trace}{GEN x, GEN T, GEN p} returns the trace of \kbd{x} 5241 5242\fun{GEN}{FpXQ_conjvec}{GEN x, GEN T, GEN p} returns the vector of conjugates 5243$[x,x^p,x^{p^2},\ldots,x^{p^{n-1}}]$ where $n$ is the degree of $T$. 5244 5245\fun{GEN}{gener_FpXQ}{GEN T, GEN p, GEN *po} returns a primitive root modulo 5246$(T,p)$. $T$ is an \kbd{FpX} assumed to be irreducible modulo the prime 5247$p$. If \kbd{po} is not \kbd{NULL} it is set to $[o,\var{fa}]$, where $o$ is 5248the order of the multiplicative group of the finite field, and \var{fa} is 5249its factorization. 5250 5251\fun{GEN}{gener_FpXQ_local}{GEN T, GEN p, GEN L}, \kbd{L} being a vector of 5252primes dividing $p^{\deg T} - 1$, returns an element of $G:=\F_p[x]/(T)$ 5253which is a generator of the $\ell$-Sylow of $G$ for every $\ell$ in 5254\kbd{L}. It is not necessary, and in fact slightly inefficient, to include 5255$\ell=2$, since 2 is treated separately in any case, i.e. the generator 5256obtained is never a square if $p$ is odd. 5257 5258\fun{GEN}{gener_Fq_local}{GEN T, GEN p, GEN L} as 5259\kbd{pgener\_Fp\_local(p, L)} if $T$ is \kbd{NULL}, 5260or \kbd{gener\_FpXQ\_local} (otherwise). 5261 5262 5263\fun{GEN}{FpXQ_powers}{GEN x, long n, GEN T, GEN p} returns $[\kbd{x}^0, 5264\dots, \kbd{x}^\kbd{n}]$ as a \typ{VEC} of \kbd{FpXQ}s. 5265 5266\fun{GEN}{FpXQ_matrix_pow}{GEN x, long m, long n, GEN T, GEN p}, as 5267\kbd{FpXQ\_powers}$(x, n-1, T, p)$, but returns the powers as a an 5268$m\times n$ matrix. Usually, we have $m = n = \deg T$. 5269 5270\fun{GEN}{FpXQ_autpow}{GEN a, ulong n, GEN T, GEN p} computes $\sigma^n(X)$ 5271assuming $a=\sigma(X)$ where $\sigma$ is an automorphism of the algebra 5272$\F_p[X]/T(X)$. 5273 5274\fun{GEN}{FpXQ_autsum}{GEN a, ulong n, GEN T, GEN p} 5275$a$ being a two-component vector, 5276$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$, 5277returns the vector $[\sigma^n(X),b\sigma(b)\ldots\sigma^{n-1}(b)]$ 5278where $b=a[2]$. 5279 5280\fun{GEN}{FpXQ_auttrace}{GEN a, ulong n, GEN T, GEN p} 5281$a$ being a two-component vector, 5282$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$, 5283returns the vector $[\sigma^n(X),b+\sigma(b)+\ldots+\sigma^{n-1}(b)]$ 5284where $b=a[2]$. 5285 5286\fun{GEN}{FpXQ_autpowers}{GEN S, long n, GEN T, GEN p} returns 5287$[x,S(x),S(S(x)),\dots,S^{(n)}(x)]$ as a \typ{VEC} of \kbd{FpXQ}s. 5288 5289\fun{GEN}{FpXQM_autsum}{GEN a, long n, GEN T, GEN p} 5290$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$, 5291returns the vector $[\sigma^n(X),b\sigma(b)\ldots\sigma^{n-1}(b)]$ 5292where $b=a[2]$ is a square matrix. 5293 5294\fun{GEN}{FpX_FpXQ_eval}{GEN f, GEN x, GEN T, GEN p} returns 5295$\kbd{f}(\kbd{x})$. 5296 5297\fun{GEN}{FpX_FpXQV_eval}{GEN f, GEN V, GEN T, GEN p} returns 5298$\kbd{f}(\kbd{x})$, assuming that \kbd{V} was computed by 5299$\kbd{FpXQ\_powers}(\kbd{x}, n, \kbd{T}, \kbd{p})$. 5300 5301\fun{GEN}{FpXC_FpXQ_eval}{GEN C, GEN x, GEN T,GEN p} applies 5302\kbd{FpX\_FpXQV\_eval} to all elements of the vector $C$ 5303and returns a \typ{COL}. 5304 5305\fun{GEN}{FpXC_FpXQV_eval}{GEN C, GEN V,GEN T,GEN p} applies 5306\kbd{FpX\_FpXQV\_eval} to all elements of the vector $C$ 5307and returns a \typ{COL}. 5308 5309\fun{GEN}{FpXM_FpXQV_eval}{GEN M, GEN V,GEN T,GEN p} applies 5310\kbd{FpX\_FpXQV\_eval} to all elements of the matrix $M$. 5311 5312\subsec{\kbd{FpXn}} Let \kbd{p} a \typ{INT} and \kbd{T} an 5313\kbd{FpX} for \kbd{p}, both to be given in the function arguments; an \kbd{FpXn} 5314object is an \kbd{FpX} whose degree is strictly less than \kbd{n}. 5315They represent a class in $(\Z/\kbd{p}\Z)[X] / (X^n)$, in which all operations 5316below take place. They can be seen as truncated power series. 5317 5318\fun{GEN}{FpXn_mul}{GEN x, GEN y, long n, GEN p} return $x\*y\pmod{X^n}$. 5319 5320\fun{GEN}{FpXn_sqr}{GEN x, long n, GEN p} return $x^2\pmod{X^n}$. 5321 5322\fun{GEN}{FpXn_inv}{GEN x, long n, GEN p} return $1/x\pmod{X^n}$. 5323 5324\fun{GEN}{FpXn_exp}{GEN f, long n, GEN p} return $\exp(f)$ 5325as a composition of formal power series. 5326It is required that the valuation of $f$ is positive and that $p>n$. 5327 5328\fun{GEN}{FpXn_expint}{GEN f, long n, GEN p} return $\exp(F)$ 5329where $F$ is the primitive of $f$ that vanishes at $0$. 5330It is required that $p>n$. 5331 5332\subsec{\kbd{FpXC}, \kbd{FpXM}} 5333 5334\fun{GEN}{FpXC_center}{GEN C, GEN p, GEN pov2} 5335 5336\fun{GEN}{FpXM_center}{GEN M, GEN p, GEN pov2} 5337 5338\subsec{\kbd{FpXX}, \kbd{FpXY}} 5339Contrary to what the name implies, an \kbd{FpXX} is a \typ{POL} whose 5340coefficients are either \typ{INT}s or \kbd{FpX}s. This reduces memory 5341overhead at the expense of consistency. The prefix \kbd{FpXY} is an 5342alias for \kbd{FpXX} when variables matters. 5343 5344\fun{GEN}{FpXX_red}{GEN z, GEN p}, \kbd{z} a \typ{POL} whose coefficients are 5345either \kbd{ZX}s or \typ{INT}s. Returns the \typ{POL} equal to \kbd{z} with 5346all components reduced modulo \kbd{p}. 5347 5348\fun{GEN}{FpXX_renormalize}{GEN x, long l}, as \kbd{normalizepol}, where 5349$\kbd{l} = \kbd{lg(x)}$, in place. 5350 5351\fun{GEN}{FpXX_add}{GEN x, GEN y, GEN p} adds \kbd{x} and \kbd{y}. 5352 5353\fun{GEN}{FpXX_sub}{GEN x, GEN y, GEN p} returns $\kbd{x}-\kbd{y}$. 5354 5355\fun{GEN}{FpXX_neg}{GEN x, GEN p} returns $-\kbd{x}$. 5356 5357\fun{GEN}{FpXX_Fp_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{FpXX}~\kbd{x} 5358by the \kbd{Fp}~\kbd{y}. 5359 5360\fun{GEN}{FpXX_FpX_mul}{GEN x, GEN y, GEN p} multiplies the coefficients of the 5361\kbd{FpXX}~\kbd{x} by the \kbd{FpX}~\kbd{y}. 5362 5363\fun{GEN}{FpXX_mulu}{GEN x, GEN y, GEN p} multiplies the \kbd{FpXX}~\kbd{x} 5364by the scalar \kbd{y}. 5365 5366\fun{GEN}{FpXX_halve}{GEN x, GEN p} returns $z$ such that $2\*z = x$ 5367assuming such $z$ exists. 5368 5369\fun{GEN}{FpXX_deriv}{GEN P, GEN p} differentiates \kbd{P} with respect to 5370the main variable. 5371 5372\fun{GEN}{FpXX_integ}{GEN P, GEN p} returns the primitive of \kbd{P} with 5373respect to the main variable whose constant term is $0$. 5374 5375\fun{GEN}{FpXY_eval}{GEN Q, GEN y, GEN x, GEN p} $Q$ being an \kbd{FpXY}, 5376i.e.~a \typ{POL} with \kbd{Fp} or \kbd{FpX} coefficients representing an 5377element of $\F_p[X][Y]$. Returns the \kbd{Fp} $Q(x,y)$. 5378 5379\fun{GEN}{FpXY_evalx}{GEN Q, GEN x, GEN p} $Q$ being an \kbd{FpXY}, returns the 5380\kbd{FpX} $Q(x,Y)$, where $Y$ is the main variable of $Q$. 5381 5382\fun{GEN}{FpXY_evaly}{GEN Q, GEN y, GEN p, long vx} $Q$ an \kbd{FpXY}, returns 5383the \kbd{FpX} $Q(X,y)$, where $X$ is the second variable of $Q$, and \kbd{vx} 5384is the variable number of $X$. 5385 5386\fun{GEN}{FpXY_FpXQ_evaly}{GEN Q, GEN y, GEN T, GEN p, long vx} $Q$ an \kbd{FpXY} 5387and $y$ being an \kbd{FpXQ}, returns the \kbd{FpXQX} $Q(X,y)$, where $X$ is the 5388second variable of $Q$, and \kbd{vx} is the variable number of $X$. 5389 5390\fun{GEN}{FpXY_Fq_evaly}{GEN Q, GEN y, GEN T, GEN p, long vx} $Q$ an \kbd{FpXY} 5391and $y$ being an \kbd{Fq}, returns the \kbd{FqX} $Q(X,y)$, where $X$ is the 5392second variable of $Q$, and \kbd{vx} is the variable number of $X$. 5393 5394\fun{GEN}{FpXY_FpXQ_evalx}{GEN Q, GEN x, ulong p} $Q$ an \kbd{FpXY} and 5395$x$ being an \kbd{FpXQ}, returns the \kbd{FpXQX} $Q(x,Y)$, where $Y$ is the 5396first variable of $Q$. 5397 5398\fun{GEN}{FpXY_FpXQV_evalx}{GEN Q, GEN V, ulong p} $Q$ an \kbd{FpXY} and 5399$x$ being an \kbd{FpXQ}, returns the \kbd{FpXQX} $Q(x,Y)$, where $Y$ is the 5400first variable of $Q$, assuming that \kbd{V} was computed by 5401$\kbd{FpXQ\_powers}(\kbd{x}, n, \kbd{T}, \kbd{p})$. 5402 5403\fun{GEN}{FpXYQQ_pow}{GEN x, GEN n, GEN S, GEN T, GEN p}, \kbd{x} being a 5404\kbd{FpXY}, \kbd{T} being a \kbd{FpX} and \kbd{S} being a \kbd{FpY}, 5405return $x^n \pmod{S,T,p}$. 5406 5407\subsec{\kbd{FpXQX}, \kbd{FqX}} 5408Contrary to what the name implies, an \kbd{FpXQX} is a \typ{POL} whose 5409coefficients are \kbd{Fq}s. So the only difference between \kbd{FqX} and 5410\kbd{FpXQX} routines is that $\kbd{T} = \kbd{NULL}$ is not allowed in the 5411latter. (It was thought more useful to allow \typ{INT} components than to 5412enforce strict consistency, which would not imply any efficiency gain.) 5413 5414\subsubsec{Basic operations} 5415 5416\fun{GEN}{FqX_add}{GEN x,GEN y,GEN T,GEN p} 5417 5418\fun{GEN}{FqX_Fq_add}{GEN x, GEN y, GEN T, GEN p} adds the 5419\kbd{Fq}~\kbd{y} to the \kbd{FqX}~\kbd{x}. 5420 5421\fun{GEN}{FqX_Fq_sub}{GEN x, GEN y, GEN T, GEN p} substracts the 5422\kbd{Fq}~\kbd{y} to the \kbd{FqX}~\kbd{x}. 5423 5424\fun{GEN}{FqX_neg}{GEN x,GEN T,GEN p} 5425 5426\fun{GEN}{FqX_sub}{GEN x,GEN y,GEN T,GEN p} 5427 5428\fun{GEN}{FqX_mul}{GEN x, GEN y, GEN T, GEN p} 5429 5430\fun{GEN}{FqX_Fq_mul}{GEN x, GEN y, GEN T, GEN p} multiplies the 5431\kbd{FqX}~\kbd{x} by the \kbd{Fq}~\kbd{y}. 5432 5433\fun{GEN}{FqX_mulu}{GEN x, ulong y, GEN T, GEN p} multiplies the 5434\kbd{FqX}~\kbd{x} by the scalar~\kbd{y}. 5435 5436\fun{GEN}{FqX_halve}{GEN x, GEN T, GEN p} returns $z$ such that $2\*z = x$ 5437assuming such $z$ exists. 5438 5439\fun{GEN}{FqX_Fp_mul}{GEN x, GEN y, GEN T, GEN p} multiplies the 5440\kbd{FqX}~\kbd{x} by the \typ{INT}~\kbd{y}. 5441 5442\fun{GEN}{FqX_Fq_mul_to_monic}{GEN x, GEN y, GEN T, GEN p} 5443returns $x\*y$ assuming the result is monic of the same degree as $x$ (in 5444particular $y\neq 0$). 5445 5446\fun{GEN}{FpXQX_normalize}{GEN z, GEN T, GEN p} 5447 5448\fun{GEN}{FqX_normalize}{GEN z, GEN T, GEN p} divides the \kbd{FqX}~\kbd{z} 5449by its leading term. The leading coefficient becomes $1$ as a \typ{INT}. 5450 5451\fun{GEN}{FqX_sqr}{GEN x, GEN T, GEN p} 5452 5453\fun{GEN}{FqX_powu}{GEN x, ulong n, GEN T, GEN p} 5454 5455\fun{GEN}{FqX_divrem}{GEN x, GEN y, GEN T, GEN p, GEN *z} 5456 5457\fun{GEN}{FqX_div}{GEN x, GEN y, GEN T, GEN p} 5458 5459\fun{GEN}{FqX_div_by_X_x}{GEN a, GEN x, GEN T, GEN p, GEN *r} 5460 5461\fun{GEN}{FqX_rem}{GEN x, GEN y, GEN T, GEN p} 5462 5463\fun{GEN}{FqX_deriv}{GEN x, GEN T, GEN p} returns the derivative of \kbd{x}. 5464(This function is suitable for \kbd{gerepilupto} but not memory-clean.) 5465 5466\fun{GEN}{FqX_integ}{GEN x, GEN T, GEN p} returns the primitive of \kbd{x}. 5467whose constant term is $0$. 5468 5469\fun{GEN}{FqX_translate}{GEN P, GEN c, GEN T, GEN p} let $c$ be an \kbd{Fq} 5470defined modulo $(p, T)$, and let $P$ be an \kbd{FqX}; returns the translated 5471\kbd{FqX} of $P(X+c)$. 5472 5473\fun{GEN}{FqX_gcd}{GEN P, GEN Q, GEN T, GEN p} returns a (not necessarily 5474monic) greatest common divisor of $x$ and $y$. 5475 5476\fun{GEN}{FqX_extgcd}{GEN x, GEN y, GEN T, GEN p, GEN *ptu, GEN *ptv} 5477returns $d = \text{GCD}(\kbd{x},\kbd{y})$ (not necessarily monic), and sets 5478\kbd{*u}, \kbd{*v} to the Bezout coefficients such that $\kbd{*ux} + 5479\kbd{*vy} = d$. 5480 5481\fun{GEN}{FqX_halfgcd}{GEN x, GEN y, GEN T, GEN p} returns a two-by-two 5482\kbd{FqXM} $M$ with determinant $\pm 1$ such that the image $(a,b)$ of $(x,y)$ 5483by $M$ has the property that $\deg a \geq {\deg x \over 2} > \deg b$. 5484 5485\fun{GEN}{FqX_eval}{GEN x, GEN y, GEN T, GEN p} evaluates the \kbd{FqX}~\kbd{x} 5486at the \kbd{Fq}~\kbd{y}. The result is an~\kbd{Fq}. 5487 5488\fun{GEN}{FqXY_eval}{GEN Q, GEN y, GEN x, GEN T, GEN p} $Q$ an \kbd{FqXY}, 5489i.e.~a \typ{POL} with \kbd{Fq} or \kbd{FqX} coefficients representing an 5490element of $\F_q[X][Y]$. Returns the \kbd{Fq} $Q(x,y)$. 5491 5492\fun{GEN}{FqXY_evalx}{GEN Q, GEN x, GEN T, GEN p} $Q$ being an \kbd{FqXY}, 5493returns the \kbd{FqX} $Q(x,Y)$, where $Y$ is the main variable of $Q$. 5494 5495\fun{GEN}{random_FpXQX}{long d, long v, GEN T, GEN p} returns a random 5496\kbd{FpXQX} in variable \kbd{v}, of degree less than~\kbd{d}. 5497 5498\fun{GEN}{FpXQX_renormalize}{GEN x, long lx} 5499 5500\fun{GEN}{FpXQX_red}{GEN z, GEN T, GEN p} \kbd{z} a \typ{POL} whose 5501coefficients are \kbd{ZX}s or \typ{INT}s, reduce them to \kbd{FpXQ}s. 5502 5503\fun{GEN}{FpXQX_mul}{GEN x, GEN y, GEN T, GEN p} 5504 5505\fun{GEN}{Kronecker_to_FpXQX}{GEN z, GEN T, GEN p}. Let $n = \deg T$ and let 5506$P(X,Y)\in \Z[X,Y]$ lift a polynomial in $K[Y]$, where $K := \F_p[X]/(T)$ and 5507$\deg_X P < 2n-1$ --- such as would result from multiplying minimal degree 5508lifts of two polynomials in $K[Y]$. Let $z = P(t,t^{2*n-1})$ be a Kronecker 5509form of $P$, this function returns $Q\in \Z[X,t]$ such that $Q$ is congruent to 5510$P(X,t)$ mod $(p, T(X))$, $\deg_X Q < n$, and all coefficients are in $[0,p[$. 5511Not stack-clean. Note that $t$ need not be the same variable as $Y$! 5512 5513\fun{GEN}{FpXQX_FpXQ_mul}{GEN x, GEN y, GEN T, GEN p} 5514 5515\fun{GEN}{FpXQX_sqr}{GEN x, GEN T, GEN p} 5516 5517\fun{GEN}{FpXQX_divrem}{GEN x, GEN y, GEN T, GEN p, GEN *pr} 5518 5519\fun{GEN}{FpXQX_div}{GEN x, GEN y, GEN T, GEN p} 5520 5521\fun{GEN}{FpXQX_div_by_X_x}{GEN a, GEN x, GEN T, GEN p, GEN *r} 5522 5523\fun{GEN}{FpXQX_rem}{GEN x, GEN y, GEN T, GEN p} 5524 5525\fun{GEN}{FpXQX_powu}{GEN x, ulong n, GEN T, GEN p} returns $x^n$. 5526 5527\fun{GEN}{FpXQX_digits}{GEN x, GEN B, GEN T, GEN p} 5528 5529\fun{GEN}{FpXQX_dotproduct}{GEN x, GEN y, GEN T, GEN p} returns the scalar 5530product of the coefficients of $x$ and $y$. 5531 5532\fun{GEN}{FpXQXV_FpXQX_fromdigits}{GEN v, GEN B, GEN T, GEN p} 5533 5534\fun{GEN}{FpXQX_invBarrett}{GEN y, GEN T, GEN p} returns the Barrett inverse of 5535the \kbd{FpXQX} $y$, namely a lift of $1/\kbd{polrecip}(y)+O(x^{\deg(y)-1})$. 5536 5537\fun{GEN}{FpXQXV_prod}{GEN V, GEN T, GEN p}, \kbd{V} being a vector of 5538\kbd{FpXQX}, returns their product. 5539 5540\fun{GEN}{FpXQX_gcd}{GEN x, GEN y, GEN T, GEN p} 5541 5542\fun{GEN}{FpXQX_extgcd}{GEN x, GEN y, GEN T, GEN p, GEN *ptu, GEN *ptv} 5543 5544\fun{GEN}{FpXQX_halfgcd}{GEN x, GEN y, GEN T, GEN p} 5545 5546\fun{GEN}{FpXQX_resultant}{GEN x, GEN y, GEN T, GEN p} returns the resultant 5547of \kbd{x} and \kbd{y}. 5548 5549\fun{GEN}{FpXQX_disc}{GEN x, GEN T, GEN p} returns the discriminant 5550of \kbd{x}. 5551 5552\fun{GEN}{FpXQX_FpXQXQ_eval}{GEN f,GEN x,GEN S, GEN T,GEN p} returns 5553$\kbd{f}(\kbd{x})$. 5554 5555\subsec{\kbd{FpXQXn}, \kbd{FqXn}} 5556 5557A \kbd{FpXQXn} is a \typ{FpXQX} which represents an element of the ring 5558$(Fp[X]/T(X))[Y]/(Y^n)$, where $T$ is a \kbd{FpX}. 5559 5560\fun{GEN}{FpXQXn_sqr}{GEN x, long n, GEN T, GEN p} 5561 5562\fun{GEN}{FqXn_sqr}{GEN x, long n, GEN T, GEN p} 5563 5564\fun{GEN}{FpXQXn_mul}{GEN x, GEN y, long n, GEN T, GEN p} 5565 5566\fun{GEN}{FqXn_mul}{GEN x, GEN y, long n, GEN T, GEN p} 5567 5568\fun{GEN}{FpXQXn_inv}{GEN x, long n, GEN T, GEN p} 5569 5570\fun{GEN}{FqXn_inv}{GEN x, long n, GEN T, GEN p} 5571 5572\fun{GEN}{FpXQXn_exp}{GEN x, long n, GEN T, GEN p} return $\exp(x)$ 5573as a composition of formal power series. 5574It is required that the valuation of $x$ is positive and that $p>n$. 5575 5576\fun{GEN}{FqXn_exp}{GEN x, long n, GEN T, GEN p} 5577 5578\fun{GEN}{FpXQXn_expint}{GEN f, long n, GEN p} return $\exp(F)$ 5579where $F$ is the primitive of $f$ that vanishes at $0$. 5580It is required that $p>n$. 5581 5582\fun{GEN}{FqXn_expint}{GEN x, long n, GEN T, GEN p} 5583 5584\subsec{\kbd{FpXQXQ}, \kbd{FqXQ}} 5585 5586A \kbd{FpXQXQ} is a \typ{FpXQX} which represents an element of the ring 5587$(Fp[X]/T(X))[Y]/S(X,Y)$, where $T$ is a \kbd{FpX} and $S$ a \kbd{FpXQX} 5588modulo $T$. A \kbd{FqXQ} is identical except that $T$ is allowed to be 5589\kbd{NULL} in which case $S$ must be a \kbd{FpX}. 5590 5591\subsubsec{Preconditioned reduction} 5592 5593For faster reduction, the modulus \kbd{S} can be replaced by an extended 5594modulus, which is an \kbd{FpXQXT}, in all \kbd{FpXQXQ}- and \kbd{FqXQ}-classes 5595functions, and in \kbd{FpXQX\_rem} and \kbd{FpXQX\_divrem}. 5596 5597\fun{GEN}{FpXQX_get_red}{GEN S, GEN T, GEN p} returns the extended modulus 5598\kbd{eS}. 5599 5600\fun{GEN}{FqX_get_red}{GEN S, GEN T, GEN p} identical, but allow $T$ to 5601be \kbd{NULL}, in which case it returns \kbd{FpX\_get\_red(S,p)}. 5602 5603To write code that works both with plain and extended moduli, the following 5604accessors are defined: 5605 5606\fun{GEN}{get_FpXQX_mod}{GEN eS} returns the underlying modulus \kbd{S}. 5607 5608\fun{GEN}{get_FpXQX_var}{GEN eS} returns the variable number of the modulus. 5609 5610\fun{GEN}{get_FpXQX_degree}{GEN eS} returns the degree of the modulus. 5611 5612Furthermore, \kbd{ZXXT\_to\_FlxXT} allows to convert an extended modulus for 5613a \kbd{FpXQX} to an extended modulus for the corresponding \kbd{FlxqX}. 5614 5615\subsubsec{basic operations} 5616 5617\fun{GEN}{FpXQX_FpXQXQV_eval}{GEN f,GEN V,GEN S,GEN T,GEN p} returns 5618$\kbd{f}(\kbd{x})$, assuming that \kbd{V} was computed by 5619$\kbd{FpXQXQ\_powers}(\kbd{x}, n, \kbd{S}, \kbd{T}, \kbd{p})$. 5620 5621\fun{GEN}{FpXQXQ_div}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x}, \kbd{y} and 5622\kbd{S} being \kbd{FpXQX}s, returns $\kbd{x}*\kbd{y}^{-1}$ modulo \kbd{S}. 5623 5624\fun{GEN}{FpXQXQ_inv}{GEN x, GEN S, GEN T, GEN p}, \kbd{x} and 5625\kbd{S} being \kbd{FpXQX}s, returns $\kbd{x}^{-1}$ modulo \kbd{S}. 5626 5627\fun{GEN}{FpXQXQ_invsafe}{GEN x, GEN S, GEN T,GEN p}, as \kbd{FpXQXQ\_inv}, 5628returning \kbd{NULL} if \kbd{x} is not invertible. 5629 5630\fun{GEN}{FpXQXQ_mul}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x}, \kbd{y} and 5631\kbd{S} being \kbd{FpXQX}s, returns $\kbd{x}\*\kbd{y}$ modulo \kbd{S}. 5632 5633\fun{GEN}{FpXQXQ_sqr}{GEN x, GEN S, GEN T, GEN p}, \kbd{x} and 5634\kbd{S} being \kbd{FpXQX}s, returns $\kbd{x}^2$ modulo \kbd{S}. 5635 5636\fun{GEN}{FpXQXQ_pow}{GEN x, GEN n, GEN S, GEN T, GEN p}, \kbd{x} and 5637\kbd{S} being \kbd{FpXQX}s, returns $\kbd{x}^\kbd{n}$ modulo \kbd{S}. 5638 5639\fun{GEN}{FpXQXQ_powers}{GEN x, long n, GEN S, GEN T, GEN p}, \kbd{x} and 5640\kbd{S} being \kbd{FpXQX}s, returns $[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ as a 5641\typ{VEC} of \kbd{FpXQXQ}s. 5642 5643\fun{GEN}{FpXQXQ_halfFrobenius}{GEN A, GEN S, GEN T, GEN p} returns 5644$A(X)^{(q-1)/2}\pmod{S(X)}$ over the finite field $\F_q$ defined by $T$ 5645and $p$, thus $q=p^n$ where $n$ is the degree of $T$. 5646 5647\fun{GEN}{FpXQXQ_minpoly}{GEN x, GEN S, GEN T, GEN p}, as 5648\kbd{FpXQ\_minpoly} 5649 5650\fun{GEN}{FpXQXQ_matrix_pow}{GEN x, long m, long n, GEN S, GEN T, GEN p} 5651returns the same powers of \kbd{x} as \kbd{FpXQXQ\_powers}$(x, n-1,S, T, p)$, 5652but as an $m\times n$ matrix. 5653 5654\fun{GEN}{FpXQXQ_autpow}{GEN a, long n, GEN S, GEN T, GEN p} 5655$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$, 5656$\sigma(Y)=a[2]\pmod{S(X,Y),T(X)}$, returns $[\sigma^n(X),\sigma^n(Y)]$. 5657 5658\fun{GEN}{FpXQXQ_autsum}{GEN a, long n, GEN S, GEN T, GEN p} 5659$\sigma$ being the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$, 5660$\sigma(Y)=a[2]\pmod{S(X,Y),T(X)}$, returns the vector 5661$[\sigma^n(X),\sigma^n(Y),b\sigma(b)\ldots\sigma^{n-1}(b)]$ 5662where $b=a[3]$. 5663 5664\fun{GEN}{FpXQXQ_auttrace}{GEN a, long n, GEN S, GEN T, GEN p} 5665$\sigma$ being the automorphism defined by $\sigma(X)=X\pmod{T(X)}$, 5666$\sigma(Y)=a[1]\pmod{S(X,Y),T(X)}$, returns the vector 5667$[\sigma^n(X),\sigma^n(Y),b+\sigma(b)+\ldots+\sigma^{n-1}(b)]$ 5668where $b=a[2]$. 5669 5670% FqXQ 5671 5672\fun{GEN}{FqXQ_add}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x}, \kbd{y} and 5673\kbd{S} being \kbd{FqX}s, returns $\kbd{x} + \kbd{y}$ modulo \kbd{S}. 5674 5675\fun{GEN}{FqXQ_sub}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x}, \kbd{y} and 5676\kbd{S} being \kbd{FqX}s, returns $\kbd{x} - \kbd{y}$ modulo \kbd{S}. 5677 5678\fun{GEN}{FqXQ_mul}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x}, \kbd{y} and 5679\kbd{S} being \kbd{FqX}s, returns $\kbd{x}\*\kbd{y}$ modulo \kbd{S}. 5680 5681\fun{GEN}{FqXQ_div}{GEN x, GEN y, GEN S, GEN T, GEN p}, \kbd{x} and 5682\kbd{S} being \kbd{FqX}s, returns $\kbd{x}/\kbd{y}$ modulo \kbd{S}. 5683 5684\fun{GEN}{FqXQ_inv}{GEN x, GEN S, GEN T, GEN p}, \kbd{x} and 5685\kbd{S} being \kbd{FqX}s, returns $\kbd{x}^{-1}$ modulo \kbd{S}. 5686 5687\fun{GEN}{FqXQ_invsafe}{GEN x, GEN S, GEN T, GEN p} , as \kbd{FqXQ\_inv}, 5688returning \kbd{NULL} if \kbd{x} is not invertible. 5689 5690\fun{GEN}{FqXQ_sqr}{GEN x, GEN S, GEN T, GEN p}, \kbd{x} and 5691\kbd{S} being \kbd{FqX}s, returns $\kbd{x}^2$ modulo \kbd{S}. 5692 5693\fun{GEN}{FqXQ_pow}{GEN x, GEN n, GEN S, GEN T, GEN p}, \kbd{x} and 5694\kbd{S} being \kbd{FqX}s, returns $\kbd{x}^\kbd{n}$ modulo \kbd{S}. 5695 5696\fun{GEN}{FqXQ_powers}{GEN x, long n, GEN S, GEN T, GEN p}, \kbd{x} and 5697\kbd{S} being \kbd{FqX}s, returns $[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ as a 5698\typ{VEC} of \kbd{FqXQ}s. 5699 5700\fun{GEN}{FqXQ_matrix_pow}{GEN x, long m, long n, GEN S, GEN T, GEN p} 5701returns the same powers of \kbd{x} as \kbd{FqXQ\_powers}$(x, n-1,S, T, p)$, 5702but as an $m\times n$ matrix. 5703 5704\fun{GEN}{FqV_roots_to_pol}{GEN V, GEN T, GEN p, long v}, 5705\kbd{V} being a vector of \kbd{Fq}s, returns the monic \kbd{FqX} 5706$\prod_i (\kbd{pol\_x[v]} - \kbd{V[i]})$. 5707 5708\subsubsec{Miscellaneous operations} 5709 5710\fun{GEN}{init_Fq}{GEN p, long n, long v} returns an irreducible polynomial 5711of degree $\kbd{n} > 0$ over $\F_p$, in variable \kbd{v}. 5712 5713\fun{int}{FqX_is_squarefree}{GEN P, GEN T, GEN p} 5714 5715\fun{GEN}{FpXQX_roots}{GEN f, GEN T, GEN p} return the roots of $f$ in 5716$\F_p[X]/(T)$. Assumes \kbd{p} is prime and \kbd{T} irreducible in $\F_p[X]$. 5717 5718\fun{GEN}{FqX_roots}{GEN f, GEN T, GEN p} same but allow $\kbd{T} = \kbd{NULL}$. 5719 5720\fun{GEN}{FpXQX_factor}{GEN f, GEN T, GEN p} same output convention as 5721\kbd{FpX\_factor}. Assumes \kbd{p} is prime and \kbd{T} irreducible 5722in $\F_p[X]$. 5723 5724\fun{GEN}{FqX_factor}{GEN f, GEN T, GEN p} same but allow $\kbd{T} = \kbd{NULL}$. 5725 5726\fun{GEN}{FpXQX_factor_squarefree}{GEN f, GEN T, GEN p} squarefree 5727factorization of $f$ modulo $(T,p)$; same output convention as 5728\kbd{FpX\_factor\_squarefree}. Assumes \kbd{p} is prime and \kbd{T} 5729irreducible in $\F_p[X]$. 5730 5731\fun{GEN}{FqX_factor_squarefree}{GEN f, GEN T, GEN p} same but allow 5732$\kbd{T} = \kbd{NULL}$. 5733 5734\fun{GEN}{FpXQX_ddf}{GEN f, GEN T, GEN p} as \kbd{FpX\_ddf}. 5735 5736\fun{GEN}{FqX_ddf}{GEN f, GEN T, GEN p} same but allow $\kbd{T} = \kbd{NULL}$. 5737 5738\fun{long}{FpXQX_ddf_degree}{GEN f, GEN XP, GEN T, GEN p}, as 5739\kbd{FpX\_ddf\_degree}. 5740 5741\fun{GEN}{FpXQX_degfact}{GEN f, GEN T, GEN p}, as \kbd{FpX\_degfact}. 5742 5743\fun{GEN}{FqX_degfact}{GEN f, GEN T, GEN p} same but allow 5744$\kbd{T} = \kbd{NULL}$. 5745 5746\fun{GEN}{FpXQX_split_part}{GEN f, GEN T, GEN p} returns the largest totally 5747split squarefree factor of $f$. 5748 5749\fun{long}{FpXQX_ispower}{GEN f, ulong k, GEN T, GEN p, GEN *pt} 5750return $1$ if the \kbd{FpXQX} $f$ is a $k$-th power, $0$ otherwise. 5751If \kbd{pt} is not \kbd{NULL}, set it to $g$ such that $g^k = f$. 5752 5753\fun{long}{FqX_ispower}{GEN f, ulong k, GEN T, GEN p, GEN *pt} 5754same but allow $\kbd{T} = \kbd{NULL}$. 5755 5756\fun{GEN}{FpX_factorff}{GEN P, GEN T, GEN p}. Assumes \kbd{p} prime 5757and \kbd{T} irreducible in $\F_p[X]$. Factor the \kbd{FpX} \kbd{P} 5758over the finite field $\F_p[Y]/(T(Y))$. See \kbd{FpX\_factorff\_irred} 5759if \kbd{P} is known to be irreducible of $\F_p$. 5760 5761\fun{GEN}{FpX_rootsff}{GEN P, GEN T, GEN p}. Assumes \kbd{p} prime 5762and \kbd{T} irreducible in $\F_p[X]$. Returns the roots of the \kbd{FpX} 5763\kbd{P} belonging to the finite field $\F_p[Y]/(T(Y))$. 5764 5765\fun{GEN}{FpX_factorff_irred}{GEN P, GEN T, GEN p}. Assumes \kbd{p} prime 5766and \kbd{T} irreducible in $\F_p[X]$. Factors the \emph{irreducible} 5767\kbd{FpX} \kbd{P} over the finite field $\F_p[Y]/(T(Y))$ and returns the 5768vector of irreducible \kbd{FqX}s factors (the exponents, being all equal to 5769$1$, are not included). 5770 5771\fun{GEN}{FpX_ffisom}{GEN P, GEN Q, GEN p}. Assumes \kbd{p} prime, 5772\kbd{P}, \kbd{Q} are \kbd{ZX}s, both irreducible mod \kbd{p}, and 5773$\deg(P) \mid \deg Q$. Outputs a monomorphism between $\F_p[X]/(P)$ and 5774$\F_p[X]/(Q)$, as a polynomial $R$ such that $\kbd{Q} \mid \kbd{P}(R)$ in 5775$\F_p[X]$. If \kbd{P} and \kbd{Q} have the same degree, it is of course an 5776isomorphism. 5777 5778\fun{void}{FpX_ffintersect}{GEN P, GEN Q, long n, GEN p, GEN *SP,GEN *SQ, GEN 5779MA,GEN MB}\hfil\break 5780Assumes \kbd{p} is prime, \kbd{P}, \kbd{Q} are \kbd{ZX}s, both 5781irreducible mod \kbd{p}, and \kbd{n} divides both the degree of \kbd{P} and 5782\kbd{Q}. Compute \kbd{SP} and \kbd{SQ} such that the subfield of 5783$\F_p[X]/(P)$ generated by \kbd{SP} and the subfield of $\F_p[X]/(Q)$ 5784generated by \kbd{SQ} are isomorphic of degree \kbd{n}. The polynomials 5785\kbd{P} and \kbd{Q} do not need to be of the same variable. If \kbd{MA} 5786(resp. \kbd{MB}) is not \kbd{NULL}, it must be the matrix of the Frobenius 5787map in $\F_p[X]/(P)$ (resp.~$\F_p[X]/(Q)$). 5788 5789\fun{GEN}{FpXQ_ffisom_inv}{GEN S, GEN T, GEN p}. Assumes \kbd{p} is prime, 5790\kbd{T} a \kbd{ZX}, which is irreducible modulo \kbd{p}, \kbd{S} a 5791\kbd{ZX} representing an automorphism of $\F_q := \F_p[X]/(\kbd{T})$. 5792($\kbd{S}(X)$ is the image of $X$ by the automorphism.) Returns the 5793inverse automorphism of \kbd{S}, in the same format, i.e.~an \kbd{FpX}~$H$ 5794such that $H(\kbd{S}) \equiv X$ modulo $(\kbd{T}, \kbd{p})$. 5795 5796\fun{long}{FpXQX_nbfact}{GEN S, GEN T, GEN p} returns the number of 5797irreducible factors of the polynomial $S$ over the finite field $\F_q$ 5798defined by $T$ and $p$. 5799 5800\fun{long}{FpXQX_nbfact_Frobenius}{GEN S, GEN Xq, GEN T, GEN p} as 5801\kbd{FpXQX\_nbfact} where \kbd{Xq} is \kbd{FpXQX\_Frobenius(S, T, p)}. 5802 5803\fun{long}{FqX_nbfact}{GEN S, GEN T, GEN p} as above but accept \kbd{T=NULL}. 5804 5805\fun{long}{FpXQX_nbroots}{GEN S, GEN T, GEN p} returns the number of roots of 5806the polynomial $S$ over the finite field $\F_q$ defined by $T$ and $p$. 5807 5808\fun{long}{FqX_nbroots}{GEN S, GEN T, GEN p} as above but accept \kbd{T=NULL}. 5809 5810\fun{GEN}{FpXQX_Frobenius}{GEN S, GEN T, GEN p} returns 5811$X^{q}\pmod{S(X)}$ over the finite field $\F_q$ defined by $T$ and $p$, thus 5812$q=p^n$ where $n$ is the degree of $T$. 5813 5814\subsec{\kbd{Flx}} Let \kbd{p} be an \kbd{ulong}, not assumed to be 5815prime unless mentioned otherwise (e.g., all functions involving Euclidean 5816divisions and factorizations), to be given the function arguments; an 5817\kbd{Fl} is an \kbd{ulong} belonging to $[0,\kbd{p}-1]$, an \kbd{Flx}~\kbd{z} 5818is a \typ{VECSMALL} representing a polynomial with small integer 5819coefficients. Specifically \kbd{z[0]} is the usual codeword, \kbd{z[1] = 5820evalvarn($v$)} for some variable $v$, then the coefficients by increasing 5821degree. An \kbd{FlxX} is a \typ{POL} whose coefficients are \kbd{Flx}s. 5822 5823\noindent In the following, an argument called \kbd{sv} is of the form 5824\kbd{evalvarn}$(v)$ for some variable number~$v$. 5825 5826\subsubsec{Preconditioned reduction} 5827 5828For faster reduction, the modulus \kbd{T} can be replaced by an extended 5829modulus (\kbd{FlxT}) in all \kbd{Flxq}-classes functions, and in 5830\kbd{Flx\_divrem}. 5831 5832\fun{GEN}{Flx_get_red}{GEN T, ulong p} returns the extended modulus \kbd{eT}. 5833 5834To write code that works both with plain and extended moduli, the following 5835accessors are defined: 5836 5837\fun{GEN}{get_Flx_mod}{GEN eT} returns the underlying modulus \kbd{T}. 5838 5839\fun{GEN}{get_Flx_var}{GEN eT} returns the variable number of the modulus. 5840 5841\fun{GEN}{get_Flx_degree}{GEN eT} returns the degree of the modulus. 5842 5843Furthermore, \kbd{ZXT\_to\_FlxT} allows to convert an extended modulus for 5844a \kbd{FpX} to an extended modulus for the corresponding \kbd{Flx}. 5845 5846\subsubsec{Basic operations} 5847 5848\fun{ulong}{Flx_lead}{GEN x} returns the leading coefficient of $x$ as a 5849\kbd{ulong} (return $0$ for the zero polynomial). 5850 5851\fun{ulong}{Flx_constant}{GEN x} returns the constant coefficient of $x$ as a 5852\kbd{ulong} (return $0$ for the zero polynomial). 5853 5854\fun{GEN}{Flx_red}{GEN z, ulong p} converts from \kbd{zx} with 5855nonnegative coefficients to \kbd{Flx} (by reducing them mod \kbd{p}). 5856 5857\fun{int}{Flx_equal1}{GEN x} returns 1 (true) if the \kbd{Flx} $x$ is equal 5858to~1, 0~(false) otherwise. 5859 5860\fun{int}{Flx_equal}{GEN x, GEN y} returns 1 (true) if the \kbd{Flx} $x$ 5861and $y$ are equal, and 0~(false) otherwise. 5862 5863\fun{GEN}{Flx_copy}{GEN x} returns a copy of \kbd{x}. 5864 5865\fun{GEN}{Flx_add}{GEN x, GEN y, ulong p} 5866 5867\fun{GEN}{Flx_Fl_add}{GEN y, ulong x, ulong p} 5868 5869\fun{GEN}{Flx_neg}{GEN x, ulong p} 5870 5871\fun{GEN}{Flx_neg_inplace}{GEN x, ulong p}, same as \kbd{Flx\_neg}, in place 5872(\kbd{x} is destroyed). 5873 5874\fun{GEN}{Flx_sub}{GEN x, GEN y, ulong p} 5875 5876\fun{GEN}{Flx_Fl_sub}{GEN y, ulong x, ulong p} 5877 5878\fun{GEN}{Flx_halve}{GEN x, ulong p} returns $z$ such that $2\*z = x$ modulo 5879$p$ assuming such $z$ exists. 5880 5881\fun{GEN}{Flx_mul}{GEN x, GEN y, ulong p} 5882 5883\fun{GEN}{Flx_Fl_mul}{GEN y, ulong x, ulong p} 5884 5885\fun{GEN}{Flx_double}{GEN y, ulong p} returns $2\*y$. 5886 5887\fun{GEN}{Flx_triple}{GEN y, ulong p} returns $3\*y$. 5888 5889\fun{GEN}{Flx_mulu}{GEN y, ulong x, ulong p} as \kbd{Flx\_Fl\_mul} but do not 5890assume that $x<p$. 5891 5892\fun{GEN}{Flx_Fl_mul_to_monic}{GEN y, ulong x, ulong p} returns $y\*x$ 5893assuming the result is monic of the same degree as $y$ (in particular $x\neq 58940$). 5895 5896\fun{GEN}{Flx_sqr}{GEN x, ulong p} 5897 5898\fun{GEN}{Flx_powu}{GEN x, ulong n, ulong p} return $x^n$. 5899 5900\fun{GEN}{Flx_divrem}{GEN x, GEN y, ulong p, GEN *pr}, 5901here $p$ must be prime. 5902 5903\fun{GEN}{Flx_div}{GEN x, GEN y, ulong p}, 5904here $p$ must be prime. 5905 5906\fun{GEN}{Flx_rem}{GEN x, GEN y, ulong p}, 5907here $p$ must be prime. 5908 5909\fun{GEN}{Flx_deriv}{GEN z, ulong p} 5910 5911\fun{GEN}{Flx_integ}{GEN z, ulong p}, 5912here $p$ must be prime. 5913 5914\fun{GEN}{Flx_translate1}{GEN P, ulong p} return $P(x+1)$, $p$ must be prime. 5915Asymptotically fast (quasi-linear in the degree of $P$). 5916 5917\fun{GEN}{Flx_translate1_basecase}{GEN P, ulong p} return $P(x+1)$, $p$ 5918need not be prime. Not asymptotically fast (quadratic in the degree of $P$). 5919 5920\fun{GEN}{zlx_translate1}{GEN P, ulong p, long e} return $P(x+1)$ 5921modulo $p^e$ for prime $p$. Asymptotically fast (quasi-linear in the degree of 5922$P$). 5923 5924\fun{GEN}{Flx_diff1}{GEN P, ulong p} return $P(x+1)-P(x)$; $p$ must be prime. 5925 5926\fun{GEN}{Flx_digits}{GEN x, GEN B, ulong p} returns a vector of \kbd{Flx} 5927$[c_0,\ldots,c_n]$ of degree less than the degree of $B$ and such that 5928$x=\sum_{i=0}^{n}{c_i\*B^i}$. 5929 5930\fun{GEN}{FlxV_Flx_fromdigits}{GEN v, GEN B, ulong p} where $v=[c_0,\ldots,c_n]$ 5931is a vector of \kbd{Flx}, returns $\sum_{i=0}^{n}{c_i\*B^i}$. 5932 5933\fun{GEN}{Flx_Frobenius}{GEN T, ulong p} 5934here $p$ must be prime. 5935 5936\fun{GEN}{Flx_matFrobenius}{GEN T, ulong p} 5937here $p$ must be prime. 5938 5939\fun{GEN}{Flx_gcd}{GEN a, GEN b, ulong p} returns a (not necessarily monic) 5940greatest common divisor of $x$ and $y$. Here $p$ must be prime. 5941 5942\fun{GEN}{Flx_halfgcd}{GEN x, GEN y, ulong p} returns a two-by-two \kbd{FlxM} 5943$M$ with determinant $\pm 1$ such that the image $(a,b)$ of $(x,y)$ by $M$ 5944has the property that $\deg a \geq {\deg x \over 2} > \deg b$. 5945Assumes that $p$ is prime. 5946 5947\fun{GEN}{Flx_extgcd}{GEN a, GEN b, ulong p, GEN *ptu, GEN *ptv}, 5948here $p$ must be prime. 5949 5950\fun{GEN}{Flx_roots}{GEN f, ulong p} returns the vector of roots 5951of $f$ (without multiplicity, as a \typ{VECSMALL}). Assumes that $p$ is 5952prime. 5953 5954\fun{ulong}{Flx_oneroot}{GEN f, ulong p} returns one root $0 \leq r < p$ of 5955the \kbd{Flx}~\kbd{f} in \kbd{\Z/p\Z}. Return $p$ if no root exists. 5956Assumes that $p$ is prime. 5957 5958\fun{ulong}{Flx_oneroot_split}{GEN f, ulong p} as \kbd{Flx\_oneroot} but 5959assume $f$ is totally split. Assumes that $p$ is prime. 5960 5961\fun{long}{Flx_ispower}{GEN f, ulong k, ulong p, GEN *pt} 5962return $1$ if the \kbd{Flx} $f$ is a $k$-th power, $0$ otherwise. 5963If \kbd{pt} is not \kbd{NULL}, set it to $g$ such that $g^k = f$. 5964 5965\fun{GEN}{Flx_factor}{GEN f, ulong p} Assumes that $p$ is prime. 5966 5967\fun{GEN}{Flx_ddf}{GEN f, ulong p} Assumes that $p$ is prime. 5968 5969\fun{GEN}{Flx_factor_squarefree}{GEN f, ulong p} returns the squarefree 5970factorization of $f$ modulo $p$. This is a vector $[u_1,\dots,u_k]$ 5971of pairwise coprime \kbd{Flx} such that $u_k \neq 1$ and $f = \prod u_i^i$. 5972Shallow function. Assumes that $p$ is prime. 5973 5974\fun{GEN}{Flx_mod_Xn1}{GEN T, ulong n, ulong p} return $T$ modulo 5975$(X^n + 1, p)$. Shallow function. 5976 5977\fun{GEN}{Flx_mod_Xnm1}{GEN T, ulong n, ulong p} return $T$ modulo 5978$(X^n - 1, p)$. Shallow function. 5979 5980\fun{GEN}{Flx_degfact}{GEN f, ulong p} as \tet{FpX_degfact}. Assumes that $p$ 5981is prime. 5982 5983\fun{GEN}{Flx_factorff_irred}{GEN P, GEN Q, ulong p} as 5984\tet{FpX_factorff_irred}. Assumes that $p$ is prime. 5985 5986\fun{GEN}{Flx_rootsff}{GEN P, GEN T, ulong p} as \tet{FpX_rootsff}. 5987Assumes that $p$ is prime. 5988 5989\fun{GEN}{Flx_ffisom}{GEN P,GEN Q,ulong l} as \tet{FpX_ffisom}. 5990Assumes that $p$ is prime. 5991 5992\subsubsec{Miscellaneous operations} 5993 5994\fun{GEN}{pol0_Flx}{long sv} returns a zero \kbd{Flx} in variable $v$. 5995 5996\fun{GEN}{zero_Flx}{long sv} alias for \kbd{pol0\_Flx} 5997 5998\fun{GEN}{pol1_Flx}{long sv} returns the unit \kbd{Flx} in variable $v$. 5999 6000\fun{GEN}{polx_Flx}{long sv} returns the variable $v$ as degree~1~\kbd{Flx}. 6001 6002\fun{GEN}{polxn_Flx}{long n, long sv} Returns the monomial of degree $n$ as 6003a \kbd{Flx} in variable $v$; assume that $n \geq 0$. 6004 6005\fun{GEN}{monomial_Flx}{ulong a, long d, long sv} returns the \kbd{Flx} 6006$a\*X^d$ in variable $v$. 6007 6008\fun{GEN}{init_Flxq}{ulong p, long n, long sv} returns an irreducible 6009polynomial of degree $\kbd{n} > 0$ over $\F_p$, in variable \kbd{v}. 6010 6011\fun{GEN}{Flx_normalize}{GEN z, ulong p}, as \kbd{FpX\_normalize}. 6012 6013\fun{GEN}{Flx_rescale}{GEN P, ulong h, ulong p} returns $h^{\deg(P)} P(x/h)$, 6014\kbd{P} is a \kbd{Flx} and \kbd{h} is a nonzero integer. 6015 6016\fun{GEN}{random_Flx}{long d, long sv, ulong p} returns a random \kbd{Flx} 6017in variable \kbd{v}, of degree less than~\kbd{d}. 6018 6019\fun{GEN}{Flx_recip}{GEN x}, returns the reciprocal polynomial 6020 6021\fun{ulong}{Flx_resultant}{GEN a, GEN b, ulong p}, returns the resultant 6022of \kbd{a} and \kbd{b}. Assumes that $p$ is prime. 6023 6024\fun{ulong}{Flx_extresultant}{GEN a, GEN b, ulong p, GEN *ptU, GEN *ptV} 6025given two \kbd{Flx} \kbd{a} and \kbd{b}, 6026returns their resultant and sets Bezout coefficients (if the resultant is 0, 6027the latter are not set). Assumes that $p$ is prime. 6028 6029\fun{GEN}{Flx_invBarrett}{GEN T, ulong p}, returns the Barrett inverse 6030$M$ of $T$ defined by $M(x)\*x^n\*T(1/x)\equiv 1\pmod{x^{n-1}}$ where $n$ is 6031the degree of $T$. Assumes that $p$ is prime. 6032 6033\fun{GEN}{Flx_renormalize}{GEN x, long l}, as \kbd{FpX\_renormalize}, where 6034$\kbd{l} = \kbd{lg(x)}$, in place. 6035 6036\fun{GEN}{Flx_shift}{GEN T, long n} returns $\kbd{T} * x^n$ if $n\geq 0$, 6037and $\kbd{T} \bs x^{-n}$ otherwise. 6038 6039\fun{long}{Flx_val}{GEN x} returns the valuation of \kbd{x}, i.e. the 6040multiplicity of the $0$ root. 6041 6042\fun{long}{Flx_valrem}{GEN x, GEN *Z} as \kbd{RgX\_valrem}, returns the 6043valuation of \kbd{x}. In particular, if the valuation is $0$, set \kbd{*Z} 6044to $x$, not a copy. 6045 6046\fun{GEN}{Flx_div_by_X_x}{GEN A, ulong a, ulong p, ulong *rem}, returns the 6047Euclidean quotient of the \kbd{Flx}~\kbd{A} by $X - \kbd{a}$, and sets 6048\kbd{rem} to the remainder $ \kbd{A}(\kbd{a})$. 6049 6050\fun{ulong}{Flx_eval}{GEN x, ulong y, ulong p}, as \kbd{FpX\_eval}. 6051 6052\fun{ulong}{Flx_eval_pre}{GEN x, ulong y, ulong p, ulong pi}, as \kbd{Flx\_eval}, 6053assuming $pi$ is the pseudo inverse of $p$. 6054 6055\fun{ulong}{Flx_eval_powers_pre}{GEN P, GEN y, ulong p, ulong pi}. Let $y$ be 6056the \typ{VECSMALL} $(1,a,\dots,a^n)$, where $n$ is the degree of the 6057\kbd{Flx} $P$, return $P(a)$, assuming $pi$ is the pseudo inverse of $p$. 6058 6059\fun{GEN}{Flx_Flv_multieval}{GEN P, GEN v, ulong p} returns the vector 6060$[P(v[1]),\ldots,P(v[n])]$ as a \kbd{Flv}. 6061 6062\fun{ulong}{Flx_dotproduct}{GEN x, GEN y, ulong p} returns the scalar product 6063of the coefficients of $x$ and $y$. 6064 6065\fun{GEN}{Flx_deflate}{GEN P, long d} assuming $P$ is a polynomial of the 6066form $Q(X^d)$, return $Q$. 6067 6068\fun{GEN}{Flx_inflate}{GEN P, long d} returns $P(X^d)$. 6069 6070\fun{GEN}{Flx_splitting}{GEN P, long k}, as \tet{RgX_splitting}. 6071 6072\fun{GEN}{Flx_blocks}{GEN P, long n, long m}, as \tet{RgX_blocks}. 6073 6074\fun{int}{Flx_is_squarefree}{GEN z, ulong p}. Assumes that $p$ is prime. 6075 6076\fun{int}{Flx_is_irred}{GEN f, ulong p}, as \kbd{FpX\_is\_irred}. 6077Assumes that $p$ is prime. 6078 6079\fun{int}{Flx_is_totally_split}{GEN f, ulong p} returns $1$ if the 6080\kbd{Flx}~\kbd{f} splits into a product of distinct linear factors, $0$ 6081otherwise. Assumes that \kbd{p} is prime. 6082 6083\fun{int}{Flx_is_smooth}{GEN f, long r, ulong p} return $1$ if all 6084irreducible factors of $f$ are of degree at most $r$, $0$ otherwise. 6085Assumes that $p$ is prime. 6086 6087\fun{long}{Flx_nbroots}{GEN f, ulong p}, as \kbd{FpX\_nbroots}. 6088Assumes that $p$ is prime. 6089 6090\fun{long}{Flx_nbfact}{GEN z, ulong p}, as \kbd{FpX\_nbfact}. 6091Assumes that $p$ is prime. 6092 6093\fun{long}{Flx_nbfact_Frobenius}{GEN f, GEN XP, ulong p}, 6094as \kbd{FpX\_nbfact\_Frobenius}. Assumes that $p$ is prime. 6095 6096\fun{GEN}{Flx_degfact}{GEN f, ulong p}, as \kbd{FpX\_degfact}. 6097Assumes that $p$ is prime. 6098 6099\fun{GEN}{Flx_nbfact_by_degree}{GEN z, long *nb, ulong p} Assume 6100that the \kbd{Flx} $z$ is squarefree mod the prime $p$. Returns a 6101\typ{VECSMALL} $D$ with $\deg z$ entries, such that $D[i]$ is the number of 6102irreducible factors of degree $i$. Set \kbd{nb} to the total number of 6103irreducible factors (the sum of the $D[i]$). 6104Assumes that $p$ is prime. 6105 6106\fun{void}{Flx_ffintersect}{GEN P,GEN Q, long n, ulong p, GEN*SP, GEN*SQ, GEN 6107MA,GEN MB},\hfil\break 6108as \kbd{FpX\_ffintersect}. Assumes that $p$ is prime. 6109 6110\fun{GEN}{Flx_Laplace}{GEN x, ulong p} 6111 6112\fun{GEN}{Flx_invLaplace}{GEN x, ulong p} 6113 6114\fun{GEN}{Flx_Newton}{GEN x, long n, ulong p} 6115 6116\fun{GEN}{Flx_fromNewton}{GEN x, ulong p} 6117 6118\fun{GEN}{Flx_Teichmuller}{GEN P, ulong p, long n} 6119Return a \kbd{ZX} $Q$ such that $P\equiv Q\pmod{p}$ and 6120$Q(X^p)=0\pmod{Q,p^n}$. Assumes that $p$ is prime. 6121 6122\fun{GEN}{Flv_polint}{GEN x, GEN y, ulong p, long sv} as \kbd{FpV\_polint}, 6123returning an \kbd{Flx} in variable $v$. Assumes that $p$ is prime. 6124 6125\fun{GEN}{Flv_Flm_polint}{GEN x, GEN V, ulong p, long sv} equivalent (but 6126faster) to applying \kbd{Flv\_polint(x,$\ldots$)} to all the elements of the 6127vector $V$ (thus, returns a \kbd{FlxV}). Assumes that $p$ is prime. 6128 6129\fun{GEN}{Flv_invVandermonde}{GEN L, ulong d, ulong p} $L$ being a \kbd{Flv} 6130of length $n$, return the inverse $M$ of the Vandermonde matrix attached to 6131the elements of $L$, multiplied by \kbd{d}. 6132If $A$ is a \kbd{Flv} and $B=M\*A$, then the polynomial 6133$P=\sum_{i=1}^n B[i]\*X^{i-1}$ verifies $P(L[i])=d\*A[i]$ for 6134$1 \leq i \leq n$. Assumes that $p$ is prime. 6135 6136\fun{GEN}{Flv_roots_to_pol}{GEN a, ulong p, long sv} as 6137\kbd{FpV\_roots\_to\_pol} returning an \kbd{Flx} in variable $v$. 6138 6139\subsec{\kbd{FlxV}} See \kbd{FpXV} operations. 6140 6141\fun{GEN}{FlxV_Flc_mul}{GEN V, GEN W, ulong p}, as \kbd{FpXV\_FpC\_mul}. 6142 6143\fun{GEN}{FlxV_red}{GEN V, ulong p} reduces each components with \kbd{Flx\_red}. 6144 6145\fun{GEN}{FlxV_prod}{GEN V, ulong p}, \kbd{V} being a vector of \kbd{Flx}, 6146returns their product. 6147 6148\fun{ulong}{FlxC_eval_powers_pre}{GEN x, GEN y, ulong p, ulong pi} 6149apply \kbd{Flx\_eval\_powers\_pre} to all elements of \kbd{x}. 6150 6151\fun{GEN}{FlxV_Flv_multieval}{GEN F, GEN v, ulong p} returns the vector 6152$[[F[1](v[1]),\ldots,F[1](v[n])],\ldots,[F[m](v[1]),\ldots,F[m](v[n])]]$ 6153as a \kbd{FlvV}. 6154 6155\fun{GEN}{FlxC_neg}{GEN x, ulong p} 6156 6157\fun{GEN}{FlxC_sub}{GEN x, GEN y, ulong p} 6158 6159\fun{GEN}{zero_FlxC}{long n, long sv} 6160 6161\subsec{\kbd{FlxM}} See \kbd{FpXM} operations. 6162 6163\fun{ulong}{FlxM_eval_powers_pre}{GEN M, GEN y, ulong p, ulong pi} 6164this function applies \kbd{FlxC\_eval\_powers\_pre} to all entries of \kbd{M}. 6165 6166\fun{GEN}{FlxM_neg}{GEN x, ulong p} 6167 6168\fun{GEN}{FlxM_sub}{GEN x, GEN y, ulong p} 6169 6170\fun{GEN}{zero_FlxM}{long r, long c, long sv} 6171 6172\subsec{\kbd{FlxT}} See \kbd{FpXT} operations. 6173 6174\fun{GEN}{FlxT_red}{GEN V, ulong p} reduces each leaf with \kbd{Flx\_red}. 6175 6176\subsec{\kbd{Flxn}} See \kbd{FpXn} operations. 6177 6178\fun{GEN}{Flxn_inv}{GEN a, long n, ulong p} 6179returns $1/a$ modulo $X^n$. 6180 6181\fun{GEN}{Flxn_mul}{GEN a, GEN b, long n, ulong p} 6182returns $a\*b$ modulo $X^n$. 6183 6184\fun{GEN}{Flxn_sqr}{GEN a, long n, ulong p} 6185returns $a^2$ modulo $X^n$. 6186 6187\fun{GEN}{Flxn_red}{GEN a, long n} 6188returns $a$ modulo $X^n$. 6189 6190\fun{GEN}{Flxn_exp}{GEN x, long n, ulong p} return $\exp(x)$ 6191as a composition of formal power series. 6192It is required that the valuation of $x$ is positive and that $p>n$. 6193 6194\fun{GEN}{Flxn_expint}{GEN f, long n, ulong p} return $\exp(F)$ 6195where $F$ is the primitive of $f$ that vanishes at $0$. 6196It is required that $p>n$. 6197 6198\subsec{\kbd{Flxq}} See \kbd{FpXQ} operations. 6199 6200\fun{GEN}{Flxq_add}{GEN x, GEN y, GEN T, ulong p} 6201 6202\fun{GEN}{Flxq_sub}{GEN x, GEN y, GEN T, ulong p} 6203 6204\fun{GEN}{Flxq_mul}{GEN x, GEN y, GEN T, ulong p} 6205 6206\fun{GEN}{Flxq_sqr}{GEN y, GEN T, ulong p} 6207 6208\fun{GEN}{Flxq_inv}{GEN x, GEN T, ulong p} 6209 6210\fun{GEN}{Flxq_invsafe}{GEN x, GEN T, ulong p} 6211 6212\fun{GEN}{Flxq_div}{GEN x, GEN y, GEN T, ulong p} 6213 6214\fun{GEN}{Flxq_pow}{GEN x, GEN n, GEN T, ulong p} 6215 6216\fun{GEN}{Flxq_powu}{GEN x, ulong n, GEN T, ulong p} 6217 6218\fun{GEN}{FlxqV_factorback}{GEN L, GEN e, GEN Tp, ulong p} 6219 6220\fun{GEN}{Flxq_pow_init}{GEN x, GEN n, long k, GEN T, ulong p} 6221 6222\fun{GEN}{Flxq_pow_table}{GEN R, GEN n, GEN T, ulong p} 6223 6224\fun{GEN}{Flxq_powers}{GEN x, long n, GEN T, ulong p} 6225 6226\fun{GEN}{Flxq_matrix_pow}{GEN x, long m, long n, GEN T, ulong p}, 6227see \kbd{FpXQ\_matrix\_pow}. 6228 6229\fun{GEN}{Flxq_autpow}{GEN a, long n, GEN T, ulong p} 6230see \kbd{FpXQ\_autpow}. 6231 6232\fun{GEN}{Flxq_autpowers}{GEN a, long n, GEN T, ulong p} 6233return $[X,\sigma(X),\ldots,\sigma^n(X)]$, 6234assuming $a=\sigma(X)$ where $\sigma$ is an automorphism of the algebra 6235$\F_p[X]/T(X)$. 6236 6237\fun{GEN}{Flxq_autsum}{GEN a, long n, GEN T, ulong p} 6238see \kbd{FpXQ\_autsum}. 6239 6240\fun{GEN}{Flxq_auttrace}{GEN a, ulong n, GEN T, ulong p} 6241see \kbd{FpXQ\_auttrace}. 6242 6243\fun{GEN}{Flxq_ffisom_inv}{GEN S, GEN T, ulong p}, as \kbd{FpXQ\_ffisom\_inv}. 6244 6245\fun{GEN}{Flx_Flxq_eval}{GEN f, GEN x, GEN T, ulong p} returns 6246$\kbd{f}(\kbd{x})$. 6247 6248\fun{GEN}{Flx_FlxqV_eval}{GEN f, GEN x, GEN T, ulong p}, 6249see \kbd{FpX\_FpXQV\_eval}. 6250 6251\fun{GEN}{FlxC_Flxq_eval}{GEN C, GEN x, GEN T, ulong p}, 6252see \kbd{FpXC\_FpXQ\_eval}. 6253 6254\fun{GEN}{FlxC_FlxqV_eval}{GEN C, GEN V, GEN T, ulong p} 6255see \kbd{FpXC\_FpXQV\_eval}. 6256 6257\fun{GEN}{FlxqV_roots_to_pol}{GEN V, GEN T, ulong p, long v} as 6258\kbd{FqV\_roots\_to\_pol} returning an \kbd{FlxqX} in variable $v$. 6259 6260\fun{int}{Flxq_issquare}{GEN x, GEN T, ulong p} returns $1$ if $x$ is a square 6261and $0$ otherwise. Assume that \kbd{T} is irreducible mod \kbd{p}. 6262 6263\fun{int}{Flxq_is2npower}{GEN x, long n, GEN T, ulong p} returns $1$ if $x$ is 6264a $2^n$-th power and $0$ otherwise. Assume that \kbd{T} is irreducible mod 6265\kbd{p}. 6266 6267\fun{GEN}{Flxq_order}{GEN a, GEN ord, GEN T, ulong p} 6268as \tet{FpXQ_order}. 6269 6270\fun{GEN}{Flxq_log}{GEN a, GEN g, GEN ord, GEN T, ulong p} 6271as \tet{FpXQ_log} 6272 6273\fun{GEN}{Flxq_sqrtn}{GEN x, GEN n, GEN T, ulong p, GEN *zn} as 6274\tet{FpXQ_sqrtn}. 6275 6276\fun{GEN}{Flxq_sqrt}{GEN x, GEN T, ulong p} returns a square root of \kbd{x}. 6277Return \kbd{NULL} if \kbd{x} is not a square. 6278 6279\fun{GEN}{Flxq_lroot}{GEN a, GEN T, ulong p} returns $x$ such that $x^p = a$. 6280 6281\fun{GEN}{Flxq_lroot_fast}{GEN a, GEN V, GEN T, ulong p} assuming that 6282\kbd{V=Flxq\_powers(s,p-1,T,p)} where $s(x)^p \equiv x\pmod{T(x),p}$, 6283returns $b$ such that $b^p=a$. Only useful if $p$ is less than the degree of 6284$T$. 6285 6286\fun{GEN}{Flxq_charpoly}{GEN x, GEN T, ulong p} returns the characteristic 6287polynomial of \kbd{x} 6288 6289\fun{GEN}{Flxq_minpoly}{GEN x, GEN T, ulong p} returns the minimal polynomial 6290of \kbd{x} 6291 6292\fun{ulong}{Flxq_norm}{GEN x, GEN T, ulong p} returns the norm of \kbd{x} 6293 6294\fun{ulong}{Flxq_trace}{GEN x, GEN T, ulong p} returns the trace of \kbd{x} 6295 6296\fun{GEN}{Flxq_conjvec}{GEN x, GEN T, ulong p} returns the conjugates 6297$[x,x^p,x^{p^2},\ldots,x^{p^{n-1}}]$ where $n$ is the degree of $T$. 6298 6299\fun{GEN}{gener_Flxq}{GEN T, ulong p, GEN *po} returns a primitive root modulo 6300$(T,p)$. $T$ is an \kbd{Flx} assumed to be irreducible modulo the prime 6301$p$. If \kbd{po} is not \kbd{NULL} it is set to $[o,\var{fa}]$, where $o$ is the 6302order of the multiplicative group of the finite field, and \var{fa} is 6303its factorization. 6304 6305\subsec{\kbd{FlxX}} See \kbd{FpXX} operations. 6306 6307\fun{GEN}{pol1_FlxX}{long vX, long sx} returns the unit \kbd{FlxX} as a 6308\typ{POL} in variable \kbd{vX} which only coefficient is \kbd{pol1\_Flx(sx)}. 6309 6310\fun{GEN}{polx_FlxX}{long vX, long sx} returns the variable $X$ as a 6311degree~1~\typ{POL} with \kbd{Flx} coefficients in the variable $x$. 6312 6313\fun{long}{FlxY_degreex}{GEN P} return the degree of $P$ with respect to 6314the secondary variable. 6315 6316\fun{GEN}{FlxX_add}{GEN P, GEN Q, ulong p} 6317 6318\fun{GEN}{FlxX_sub}{GEN P, GEN Q, ulong p} 6319 6320\fun{GEN}{FlxX_Fl_mul}{GEN x, ulong y, ulong p} 6321 6322\fun{GEN}{FlxX_double}{GEN x, ulong p} 6323 6324\fun{GEN}{FlxX_triple}{GEN x, ulong p} 6325 6326\fun{GEN}{FlxX_neg}{GEN x, ulong p} 6327 6328\fun{GEN}{FlxX_Flx_add}{GEN x, GEN y, ulong p} 6329 6330\fun{GEN}{FlxX_Flx_sub}{GEN x, GEN y, ulong p} 6331 6332\fun{GEN}{FlxX_Flx_mul}{GEN x, GEN y, ulong p} 6333 6334\fun{GEN}{FlxY_Flx_div}{GEN x, GEN y, ulong p} divides the coefficients of $x$ 6335by $y$ using \kbd{Flx\_div}. 6336 6337\fun{GEN}{FlxX_deriv}{GEN P, ulong p} returns the derivative of \kbd{P} with 6338respect to the main variable. 6339 6340\fun{GEN}{FlxX_Laplace}{GEN x, ulong p} 6341 6342\fun{GEN}{FlxX_invLaplace}{GEN x, ulong p} 6343 6344\fun{GEN}{FlxY_evalx}{GEN P, ulong z, ulong p} $P$ being an \kbd{FlxY}, returns 6345the \kbd{Flx} $P(z,Y)$, where $Y$ is the main variable of $P$. 6346 6347\fun{GEN}{FlxX_translate1}{GEN P, ulong p, long n} $P$ being an \kbd{FlxX} with 6348all coefficients of degree at most $n$, return $(P(x,Y+1)$, where $Y$ is the 6349main variable of $P$. 6350 6351\fun{GEN}{zlxX_translate1}{GEN P, ulong p, long e, long n} 6352$P$ being an \kbd{zlxX} with all coefficients of degree at most $n$, return 6353$(P(x,Y+1)$ modulo $p^e$ for prime $p$ , where $Y$ is the main variable of 6354$P$. 6355 6356\fun{GEN}{FlxY_Flx_translate}{GEN P, GEN f, ulong p} $P$ being an \kbd{FlxY} and $f$ 6357being an \kbd{Flx}, return $(P(x,Y+f(x))$, where $Y$ is the main variable of $P$. 6358 6359\fun{ulong}{FlxY_evalx_powers_pre}{GEN P, GEN xp, ulong p, ulong pi}, \kbd{xp} 6360being the vector $[1,x,\dots,x^n]$, where $n$ is larger or equal to the degree 6361of $P$ in $X$, return $P(x,Y)$, where $Y$ is the main variable of $Q$, assuming 6362$pi$ is the pseudo inverse of $p$. 6363 6364\fun{ulong}{FlxY_eval_powers_pre}{GEN P, GEN xp, GEN yp, ulong p, ulong pi}, 6365\kbd{xp} being the vector $[1,x,\dots,x^n]$, where $n$ is larger or equal to the degree 6366of $P$ in $X$ and \kbd{yp} being the vector $[1,y,\dots,y^m]$, where $m$ is larger or equal to the degree of $P$ in $Y$ return $P(x,y)$, assuming 6367$pi$ is the pseudo inverse of $p$. 6368 6369\fun{GEN}{FlxY_Flxq_evalx}{GEN x, GEN y, GEN T, ulong p} as \kbd{FpXY\_FpXQ\_evalx}. 6370 6371\fun{GEN}{FlxY_FlxqV_evalx}{GEN x, GEN V, GEN T, ulong p} as \kbd{FpXY\_FpXQV\_evalx}. 6372 6373\fun{GEN}{FlxX_renormalize}{GEN x, long l}, as \kbd{normalizepol}, where 6374$\kbd{l} = \kbd{lg(x)}$, in place. 6375 6376\fun{GEN}{FlxX_resultant}{GEN u, GEN v, ulong p, long sv} Returns 6377$\text{Res}_X(u, v)$, which is an \kbd{Flx}. The coefficients of \kbd{u} 6378and \kbd{v} are assumed to be in the variable $v$. 6379 6380\fun{GEN}{Flx_FlxY_resultant}{GEN a, GEN b, ulong p} 6381Returns $\text{Res}_x(a, b)$, which is an \kbd{Flx} 6382in the main variable of \kbd{b}. 6383 6384\fun{GEN}{FlxX_blocks}{GEN P, long n, long m, long sv}, as \tet{RgX_blocks}, 6385where $v$ is the secondary variable. 6386 6387\fun{GEN}{FlxX_shift}{GEN a, long n, long sv}, as \kbd{RgX\_shift\_shallow}, 6388where $v$ is the secondary variable. 6389 6390\fun{GEN}{FlxX_swap}{GEN x, long n, long ws}, as \kbd{RgXY\_swap}. 6391 6392\fun{GEN}{FlxYqq_pow}{GEN x, GEN n, GEN S, GEN T, ulong p}, as 6393\kbd{FpXYQQ\_pow}. 6394 6395\subsec{\kbd{FlxqX}} See \kbd{FpXQX} operations. 6396 6397\subsubsec{Preconditioned reduction} 6398 6399For faster reduction, the modulus \kbd{S} can be replaced by an extended 6400modulus, which is an \kbd{FlxqXT}, in all \kbd{FlxqXQ}-classes 6401functions, and in \kbd{FlxqX\_rem} and \kbd{FlxqX\_divrem}. 6402 6403\fun{GEN}{FlxqX_get_red}{GEN S, GEN T, ulong p} returns the extended modulus 6404\kbd{eS}. 6405 6406To write code that works both with plain and extended moduli, the following 6407accessors are defined: 6408 6409\fun{GEN}{get_FlxqX_mod}{GEN eS} returns the underlying modulus \kbd{S}. 6410 6411\fun{GEN}{get_FlxqX_var}{GEN eS} returns the variable number of the modulus. 6412 6413\fun{GEN}{get_FlxqX_degree}{GEN eS} returns the degree of the modulus. 6414 6415\subsubsec{basic functions} 6416 6417\fun{GEN}{random_FlxqX}{long d, long v, GEN T, ulong p} returns a random 6418\kbd{FlxqX} in variable \kbd{v}, of degree less than~\kbd{d}. 6419 6420\fun{GEN}{zxX_to_Kronecker}{GEN P, GEN Q} assuming $P(X,Y)$ is a polynomial 6421of degree in $X$ strictly less than $n$, returns $P(X,X^{2*n-1})$, the 6422Kronecker form of $P$. 6423 6424\fun{GEN}{Kronecker_to_FlxqX}{GEN z, GEN T, ulong p}. Let $n = \deg T$ and let 6425$P(X,Y)\in \Z[X,Y]$ lift a polynomial in $K[Y]$, where $K := \F_p[X]/(T)$ and 6426$\deg_X P < 2n-1$ --- such as would result from multiplying minimal degree 6427lifts of two polynomials in $K[Y]$. Let $z = P(t,t^{2*n-1})$ be a Kronecker 6428form of $P$, this function returns $Q\in \Z[X,t]$ such that $Q$ is congruent to 6429$P(X,t)$ mod $(p, T(X))$, $\deg_X Q < n$, and all coefficients are in $[0,p[$. 6430Not stack-clean. Note that $t$ need not be the same variable as $Y$! 6431 6432\fun{GEN}{FlxqX_red}{GEN z, GEN T, ulong p} 6433 6434\fun{GEN}{FlxqX_normalize}{GEN z, GEN T, ulong p} 6435 6436\fun{GEN}{FlxqX_mul}{GEN x, GEN y, GEN T, ulong p} 6437 6438\fun{GEN}{FlxqX_Flxq_mul}{GEN P, GEN U, GEN T, ulong p} 6439 6440\fun{GEN}{FlxqX_Flxq_mul_to_monic}{GEN P, GEN U, GEN T, ulong p} 6441returns $P*U$ assuming the result is monic of the same degree as $P$ (in 6442particular $U\neq 0$). 6443 6444\fun{GEN}{FlxqX_sqr}{GEN x, GEN T, ulong p} 6445 6446\fun{GEN}{FlxqX_powu}{GEN x, ulong n, GEN T, ulong p} 6447 6448\fun{GEN}{FlxqX_divrem}{GEN x, GEN y, GEN T, ulong p, GEN *pr} 6449 6450\fun{GEN}{FlxqX_div}{GEN x, GEN y, GEN T, ulong p} 6451 6452\fun{GEN}{FlxqX_rem}{GEN x, GEN y, GEN T, ulong p} 6453 6454\fun{GEN}{FlxqX_invBarrett}{GEN T, GEN Q, ulong p} 6455 6456\fun{GEN}{FlxqX_gcd}{GEN x, GEN y, ulong p} returns a (not necessarily monic) 6457greatest common divisor of $x$ and $y$. 6458 6459\fun{GEN}{FlxqX_extgcd}{GEN x, GEN y, GEN T, ulong p, GEN *ptu, GEN *ptv} 6460 6461\fun{GEN}{FlxqX_halfgcd}{GEN x, GEN y, GEN T, ulong p}, see \kbd{FpX\_halfgcd}. 6462 6463\fun{GEN}{FlxqX_resultant}{GEN x, GEN y, GEN T, ulong p} 6464 6465\fun{GEN}{FlxqX_saferesultant}{GEN P, GEN Q, GEN T, ulong p} Returns the 6466resultant of $P$ and $Q$ if Euclid's algorithm succeeds and \kbd{NULL} otherwise. 6467In particular, if $p$ is not prime or $T$ is not irreducible over $\F_p[X]$, the 6468routine may still be used (but will fail if noninvertible leading terms 6469occur). 6470 6471\fun{GEN}{FlxqX_disc}{GEN x, GEN T, ulong p} 6472 6473\fun{GEN}{FlxqXV_prod}{GEN V, GEN T, ulong p} 6474 6475\fun{GEN}{FlxqX_safegcd}{GEN P, GEN Q, GEN T, ulong p} Returns the \emph{monic} 6476GCD of $P$ and $Q$ if Euclid's algorithm succeeds and \kbd{NULL} otherwise. In 6477particular, if $p$ is not prime or $T$ is not irreducible over $\F_p[X]$, the 6478routine may still be used (but will fail if noninvertible leading terms 6479occur). 6480 6481\fun{GEN}{FlxqX_dotproduct}{GEN x, GEN y, GEN T, ulong p} returns the scalar 6482product of the coefficients of $x$ and $y$. 6483 6484\fun{GEN}{FlxqX_Newton}{GEN x, long n, GEN T, ulong p} 6485 6486\fun{GEN}{FlxqX_fromNewton}{GEN x, GEN T, ulong p} 6487 6488\fun{long}{FlxqX_is_squarefree}{GEN S, GEN T, ulong p}, as 6489\kbd{FpX\_is\_squarefree}. 6490 6491\fun{long}{FlxqX_ispower}{GEN f, ulong k, GEN T, ulong p, GEN *pt} 6492return $1$ if the \kbd{FlxqX} $f$ is a $k$-th power, $0$ otherwise. 6493If \kbd{pt} is not \kbd{NULL}, set it to $g$ such that $g^k = f$. 6494 6495\fun{GEN}{FlxqX_Frobenius}{GEN S, GEN T, ulong p}, as \kbd{FpXQX\_Frobenius} 6496 6497\fun{GEN}{FlxqX_roots}{GEN f, GEN T, ulong p} return the roots of \kbd{f} in 6498$\F_p[X]/(T)$. Assumes \kbd{p} is prime and \kbd{T} irreducible in $\F_p[X]$. 6499 6500\fun{GEN}{FlxqX_factor}{GEN f, GEN T, ulong p} return the factorization of 6501\kbd{f} over $\F_p[X]/(T)$. Assumes \kbd{p} is prime and \kbd{T} irreducible 6502in $\F_p[X]$. 6503 6504\fun{GEN}{FlxqX_factor_squarefree}{GEN f, GEN T, ulong p} returns the squarefree 6505factorization of $f$, see \kbd{FpX\_factor\_squarefree}. 6506 6507\fun{GEN}{FlxqX_ddf}{GEN f, GEN T, ulong p} as \kbd{FpX\_ddf}. 6508 6509\fun{long}{FlxqX_ddf_degree}{GEN f, GEN XP, GEN T, GEN p}, 6510as \kbd{FpX\_ddf\_degree}. 6511 6512\fun{GEN}{FlxqX_degfact}{GEN f, GEN T, ulong p}, as \kbd{FpX\_degfact}. 6513 6514\fun{long}{FlxqX_nbroots}{GEN S, GEN T, ulong p}, as \kbd{FpX\_nbroots}. 6515 6516\fun{long}{FlxqX_nbfact}{GEN S, GEN T, ulong p}, as \kbd{FpX\_nbfact}. 6517 6518\fun{long}{FlxqX_nbfact_Frobenius}{GEN S, GEN Xq, GEN T, ulong p}, 6519as \kbd{FpX\_nbfact\_Frobenius}. 6520 6521\fun{GEN}{FlxqX_FlxqXQ_eval}{GEN Q, GEN x, GEN S, GEN T, ulong p} as 6522\kbd{FpX\_FpXQ\_eval}. 6523 6524\fun{GEN}{FlxqX_FlxqXQV_eval}{GEN P, GEN V, GEN S, GEN T, ulong p} as 6525\kbd{FpX\_FpXQV\_eval}. 6526 6527\subsec{\kbd{FlxqXQ}} See \kbd{FpXQXQ} operations. 6528 6529\fun{GEN}{FlxqXQ_mul}{GEN x, GEN y, GEN S, GEN T, ulong p} 6530 6531\fun{GEN}{FlxqXQ_sqr}{GEN x, GEN S, GEN T, ulong p} 6532 6533\fun{GEN}{FlxqXQ_inv}{GEN x, GEN S, GEN T, ulong p} 6534 6535\fun{GEN}{FlxqXQ_invsafe}{GEN x, GEN S, GEN T, ulong p} 6536 6537\fun{GEN}{FlxqXQ_div}{GEN x, GEN y, GEN S, GEN T, ulong p} 6538 6539\fun{GEN}{FlxqXQ_pow}{GEN x, GEN n, GEN S, GEN T, ulong p} 6540 6541\fun{GEN}{FlxqXQ_powu}{GEN x, ulong n, GEN S, GEN T, ulong p} 6542 6543\fun{GEN}{FlxqXQ_powers}{GEN x, long n, GEN S, GEN T, ulong p} 6544 6545\fun{GEN}{FlxqXQ_matrix_pow}{GEN x, long n, long m, GEN S, GEN T, ulong p} 6546 6547\fun{GEN}{FlxqXQ_autpow}{GEN a, long n, GEN S, GEN T, ulong p} 6548as \kbd{FpXQXQ\_autpow} 6549 6550\fun{GEN}{FlxqXQ_autsum}{GEN a, long n, GEN S, GEN T, ulong p} 6551as \kbd{FpXQXQ\_autsum} 6552 6553\fun{GEN}{FlxqXQ_auttrace}{GEN a, long n, GEN S, GEN T, ulong p} 6554as \kbd{FpXQXQ\_auttrace} 6555 6556\fun{GEN}{FlxqXQ_halfFrobenius}{GEN A, GEN S, GEN T, ulong p}, as 6557\kbd{FpXQXQ\_halfFrobenius} 6558 6559\fun{GEN}{FlxqXQ_minpoly}{GEN x, GEN S, GEN T, ulong p}, as 6560\kbd{FpXQ\_minpoly} 6561 6562\subsec{\kbd{FlxqXn}} See \kbd{FpXn} operations. 6563 6564\fun{GEN}{FlxXn_red}{GEN a, long n} returns $a$ modulo $X^n$. 6565 6566\fun{GEN}{FlxqXn_mul}{GEN a, GEN b, long n, GEN T, ulong p} 6567 6568\fun{GEN}{FlxqXn_sqr}{GEN a, long n, GEN T, ulong p} 6569 6570\fun{GEN}{FlxqXn_inv}{GEN a, long n, GEN T, ulong p} 6571 6572\fun{GEN}{FlxqXn_expint}{GEN a, long n, GEN T, ulong p} 6573 6574\subsec{\kbd{F2x}} An \kbd{F2x}~\kbd{z} is a \typ{VECSMALL} 6575representing a polynomial over $\F_2[X]$. Specifically 6576\kbd{z[0]} is the usual codeword, \kbd{z[1] = evalvarn($v$)} for some 6577variable $v$ and the coefficients are given by the bits of remaining 6578words by increasing degree. 6579 6580\subsubsec{Preconditioned reduction} 6581 6582For faster reduction, the modulus \kbd{T} can be replaced by an extended 6583modulus (\kbd{FlxT}) in all \kbd{Flxq}-classes functions, and in 6584\kbd{Flx\_divrem}. 6585 6586\fun{GEN}{F2x_get_red}{GEN T} returns the extended modulus \kbd{eT}. 6587 6588To write code that works both with plain and extended moduli, the following 6589accessors are defined: 6590 6591\fun{GEN}{get_F2x_mod}{GEN eT} returns the underlying modulus \kbd{T}. 6592 6593\fun{GEN}{get_F2x_var}{GEN eT} returns the variable number of the modulus. 6594 6595\fun{GEN}{get_F2x_degree}{GEN eT} returns the degree of the modulus. 6596 6597\subsubsec{Basic operations} 6598 6599\fun{ulong}{F2x_coeff}{GEN x, long i} returns the coefficient $i\ge 0$ of $x$. 6600 6601\fun{void}{F2x_clear}{GEN x, long i} sets the coefficient $i\ge 0$ of $x$ to 6602$0$. 6603 6604\fun{void}{F2x_flip}{GEN x, long i} adds $1$ to the coefficient $i\ge 0$ of $x$. 6605 6606\fun{void}{F2x_set}{GEN x, long i} sets the coefficient $i\ge 0$ of $x$ to $1$. 6607 6608\fun{GEN}{F2x_copy}{GEN x} 6609 6610\fun{GEN}{Flx_to_F2x}{GEN x} 6611 6612\fun{GEN}{Z_to_F2x}{GEN x, long sv} 6613 6614\fun{GEN}{ZX_to_F2x}{GEN x} 6615 6616\fun{GEN}{F2v_to_F2x}{GEN x, long sv} 6617 6618\fun{GEN}{F2x_to_Flx}{GEN x} 6619 6620\fun{GEN}{F2x_to_F2xX}{GEN x, long sv} 6621 6622\fun{GEN}{F2x_to_ZX}{GEN x} 6623 6624\fun{GEN}{pol0_F2x}{long sv} returns a zero \kbd{F2x} in variable $v$. 6625 6626\fun{GEN}{zero_F2x}{long sv} alias for \kbd{pol0\_F2x}. 6627 6628\fun{GEN}{pol1_F2x}{long sv} returns the \kbd{F2x} in variable $v$ constant to 6629$1$. 6630 6631\fun{GEN}{polx_F2x}{long sv} returns the variable $v$ as degree~1~\kbd{F2x}. 6632 6633\fun{GEN}{monomial_F2x}{long d, long sv} returns the \kbd{F2x} 6634$X^d$ in variable $v$. 6635 6636\fun{GEN}{random_F2x}{long d, long sv} returns a random \kbd{F2x} 6637in variable \kbd{v}, of degree less than~\kbd{d}. 6638 6639\fun{long}{F2x_degree}{GEN x} returns the degree of the \kbd{F2x x}. The 6640degree of $0$ is defined as $-1$. 6641 6642\fun{GEN}{F2x_recip}{GEN x} 6643 6644\fun{int}{F2x_equal1}{GEN x} 6645 6646\fun{int}{F2x_equal}{GEN x, GEN y} 6647 6648\fun{GEN}{F2x_1_add}{GEN y} returns \kbd{y+1} where \kbd{y} is a \kbd{Flx}. 6649 6650\fun{GEN}{F2x_add}{GEN x, GEN y} 6651 6652\fun{GEN}{F2x_mul}{GEN x, GEN y} 6653 6654\fun{GEN}{F2x_sqr}{GEN x} 6655 6656\fun{GEN}{F2x_divrem}{GEN x, GEN y, GEN *pr} 6657 6658\fun{GEN}{F2x_rem}{GEN x, GEN y} 6659 6660\fun{GEN}{F2x_div}{GEN x, GEN y} 6661 6662\fun{GEN}{F2x_renormalize}{GEN x, long lx} 6663 6664\fun{GEN}{F2x_deriv}{GEN x} 6665 6666\fun{GEN}{F2x_deflate}{GEN x, long d} 6667 6668\fun{ulong}{F2x_eval}{GEN P, ulong u} returns $P(u)$. 6669 6670\fun{void}{F2x_shift}{GEN x, long d} as \tet{RgX_shift} 6671 6672\fun{void}{F2x_even_odd}{GEN P, GEN *pe, GEN *po} as \tet{RgX_even_odd} 6673 6674\fun{long}{F2x_valrem}{GEN x, GEN *Z} 6675 6676\fun{GEN}{F2x_extgcd}{GEN a, GEN b, GEN *ptu, GEN *ptv} 6677 6678\fun{GEN}{F2x_gcd}{GEN a, GEN b} 6679 6680\fun{GEN}{F2x_halfgcd}{GEN a, GEN b} 6681 6682\fun{int}{F2x_issquare}{GEN x} returns $1$ if $x$ is a square of a \kbd{F2x} 6683and $0$ otherwise. 6684 6685\fun{int}{F2x_is_irred}{GEN f}, as \tet{FpX_is_irred}. 6686 6687\fun{GEN}{F2x_degfact}{GEN f} as \tet{FpX_degfact}. 6688 6689\fun{GEN}{F2x_sqrt}{GEN x} returns the squareroot of $x$, assuming $x$ is a 6690square of a \kbd{F2x}. 6691 6692\fun{GEN}{F2x_Frobenius}{GEN T} 6693 6694\fun{GEN}{F2x_matFrobenius}{GEN T} 6695 6696\fun{GEN}{F2x_factor}{GEN f} 6697 6698\fun{GEN}{F2x_factor_squarefree}{GEN f} 6699 6700\fun{GEN}{F2x_ddf}{GEN f} 6701 6702\fun{GEN}{F2x_Teichmuller}{GEN P, long n} 6703Return a \kbd{ZX} $Q$ such that $P\equiv Q\pmod{2}$ and 6704$Q(X^p)=0\pmod{Q,2^n}$. 6705 6706\subsec{\kbd{F2xq}} See \kbd{FpXQ} operations. 6707 6708\fun{GEN}{F2xq_mul}{GEN x, GEN y, GEN T} 6709 6710\fun{GEN}{F2xq_sqr}{GEN x, GEN T} 6711 6712\fun{GEN}{F2xq_div}{GEN x,GEN y,GEN T} 6713 6714\fun{GEN}{F2xq_inv}{GEN x, GEN T} 6715 6716\fun{GEN}{F2xq_invsafe}{GEN x, GEN T} 6717 6718\fun{GEN}{F2xq_pow}{GEN x, GEN n, GEN T} 6719 6720\fun{GEN}{F2xq_powu}{GEN x, ulong n, GEN T} 6721 6722\fun{GEN}{F2xq_pow_init}{GEN x, GEN n, long k, GEN T} 6723 6724\fun{GEN}{F2xq_pow_table}{GEN R, GEN n, GEN T} 6725 6726\fun{ulong}{F2xq_trace}{GEN x, GEN T} 6727 6728\fun{GEN}{F2xq_conjvec}{GEN x, GEN T} returns the vector of conjugates 6729$[x,x^2,x^{2^2},\ldots,x^{2^{n-1}}]$ where $n$ is the degree of $T$. 6730 6731\fun{GEN}{F2xq_log}{GEN a, GEN g, GEN ord, GEN T} 6732 6733\fun{GEN}{F2xq_order}{GEN a, GEN ord, GEN T} 6734 6735\fun{GEN}{F2xq_Artin_Schreier}{GEN a, GEN T} returns a solution of $x^2+x=a$, 6736assuming it exists. 6737 6738\fun{GEN}{F2xq_sqrt}{GEN a, GEN T} 6739 6740\fun{GEN}{F2xq_sqrt_fast}{GEN a, GEN s, GEN T} assuming that 6741$s^2 \equiv x\pmod{T(x)}$, computes $b \equiv a(s)\pmod{T}$ so that $b^2=a$. 6742 6743\fun{GEN}{F2xq_sqrtn}{GEN a, GEN n, GEN T, GEN *zeta} 6744 6745\fun{GEN}{gener_F2xq}{GEN T, GEN *po} 6746 6747\fun{GEN}{F2xq_powers}{GEN x, long n, GEN T} 6748 6749\fun{GEN}{F2xq_matrix_pow}{GEN x, long m, long n, GEN T} 6750 6751\fun{GEN}{F2x_F2xq_eval}{GEN f, GEN x, GEN T} 6752 6753\fun{GEN}{F2x_F2xqV_eval}{GEN f, GEN x, GEN T}, see \kbd{FpX\_FpXQV\_eval}. 6754 6755\fun{GEN}{F2xq_autpow}{GEN a, long n, GEN T} computes $\sigma^n(X)$ assuming 6756$a=\sigma(X)$ where $\sigma$ is an automorphism of the algebra $\F_2[X]/T(X)$. 6757 6758\subsec{\kbd{F2xn}} See \kbd{FpXn} operations. 6759 6760\fun{GEN}{F2xn_red}{GEN a, long n} 6761 6762\fun{GEN}{F2xn_inv}{GEN f, long e} 6763 6764\subsec{\kbd{F2xqV}, \kbd{F2xqM}}. See \kbd{FqV}, \kbd{FqM} operations. 6765 6766\fun{GEN}{F2xqM_F2xqC_gauss}{GEN a, GEN b, GEN T} 6767 6768\fun{GEN}{F2xqM_F2xqC_invimage}{GEN a, GEN b, GEN T} 6769 6770\fun{GEN}{F2xqM_F2xqC_mul}{GEN a, GEN b, GEN T} 6771 6772\fun{GEN}{F2xqM_deplin}{GEN x, GEN T} 6773 6774\fun{GEN}{F2xqM_det}{GEN a, GEN T} 6775 6776\fun{GEN}{F2xqM_gauss}{GEN a, GEN b, GEN T} 6777 6778\fun{GEN}{F2xqM_image}{GEN x, GEN T} 6779 6780\fun{GEN}{F2xqM_indexrank}{GEN x, GEN T} 6781 6782\fun{GEN}{F2xqM_inv}{GEN a, GEN T} 6783 6784\fun{GEN}{F2xqM_invimage}{GEN a, GEN b, GEN T} 6785 6786\fun{GEN}{F2xqM_ker}{GEN x, GEN T} 6787 6788\fun{GEN}{F2xqM_mul}{GEN a, GEN b, GEN T} 6789 6790\fun{long}{F2xqM_rank}{GEN x, GEN T} 6791 6792\fun{GEN}{F2xqM_suppl}{GEN x, GEN T} 6793 6794\fun{GEN}{matid_F2xqM}{long n, GEN T} 6795 6796\subsec{\kbd{F2xX}}. See \kbd{FpXX} operations. 6797 6798\fun{GEN}{ZXX_to_F2xX}{GEN x, long v} 6799 6800\fun{GEN}{FlxX_to_F2xX}{GEN x} 6801 6802\fun{GEN}{F2xX_to_FlxX}{GEN B} 6803 6804\fun{GEN}{F2xX_to_F2xC}{GEN B, long N, long sv} 6805 6806\fun{GEN}{F2xXV_to_F2xM}{GEN B, long N, long sv} 6807 6808\fun{GEN}{F2xX_to_ZXX}{GEN B} 6809 6810\fun{GEN}{F2xX_renormalize}{GEN x, long lx} 6811 6812\fun{long}{F2xY_degreex}{GEN P} return the degree of $P$ with respect to 6813the secondary variable. 6814 6815\fun{GEN}{pol1_F2xX}{long v, long sv} 6816 6817\fun{GEN}{polx_F2xX}{long v, long sv} 6818 6819\fun{GEN}{F2xX_add}{GEN x, GEN y} 6820 6821\fun{GEN}{F2xX_F2x_add}{GEN x, GEN y} 6822 6823\fun{GEN}{F2xX_F2x_mul}{GEN x, GEN y} 6824 6825\fun{GEN}{F2xX_deriv}{GEN P} returns the derivative of \kbd{P} with respect to 6826the main variable. 6827 6828\fun{GEN}{Kronecker_to_F2xqX}{GEN z, GEN T} 6829 6830\fun{GEN}{F2xX_to_Kronecker}{GEN z, GEN T} 6831 6832\fun{GEN}{F2xY_F2xq_evalx}{GEN x, GEN y, GEN T} as \kbd{FpXY\_FpXQ\_evalx}. 6833 6834\fun{GEN}{F2xY_F2xqV_evalx}{GEN x, GEN V, GEN T} as \kbd{FpXY\_FpXQV\_evalx}. 6835 6836\subsec{\kbd{F2xXV/F2xXC}}. See \kbd{FpXXV} operations. 6837 6838\fun{GEN}{FlxXC_to_F2xXC}{GEN B} 6839 6840\fun{GEN}{F2xXC_to_ZXXC}{GEN B} 6841 6842\subsec{\kbd{F2xqX}}. See \kbd{FlxqX} operations. 6843 6844\subsubsec{Preconditioned reduction} 6845 6846For faster reduction, the modulus \kbd{S} can be replaced by an extended 6847modulus, which is an \kbd{F2xqXT}, in all \kbd{F2xqXQ}-classes 6848functions, and in \kbd{F2xqX\_rem} and \kbd{F2xqX\_divrem}. 6849 6850\fun{GEN}{F2xqX_get_red}{GEN S, GEN T} returns the extended modulus 6851\kbd{eS}. 6852 6853To write code that works both with plain and extended moduli, the following 6854accessors are defined: 6855 6856\fun{GEN}{get_F2xqX_mod}{GEN eS} returns the underlying modulus \kbd{S}. 6857 6858\fun{GEN}{get_F2xqX_var}{GEN eS} returns the variable number of the modulus. 6859 6860\fun{GEN}{get_F2xqX_degree}{GEN eS} returns the degree of the modulus. 6861 6862\subsubsec{basic functions} 6863 6864\fun{GEN}{random_F2xqX}{long d, long v, GEN T, ulong p} returns a random 6865\kbd{F2xqX} in variable \kbd{v}, of degree less than~\kbd{d}. 6866 6867\fun{GEN}{F2xqX_red}{GEN z, GEN T} 6868 6869\fun{GEN}{F2xqX_normalize}{GEN z, GEN T} 6870 6871\fun{GEN}{F2xqX_F2xq_mul}{GEN P, GEN U, GEN T} 6872 6873\fun{GEN}{F2xqX_F2xq_mul_to_monic}{GEN P, GEN U, GEN T} 6874 6875\fun{GEN}{F2xqX_mul}{GEN x, GEN y, GEN T} 6876 6877\fun{GEN}{F2xqX_sqr}{GEN x, GEN T} 6878 6879\fun{GEN}{F2xqX_powu}{GEN x, ulong n, GEN T} 6880 6881\fun{GEN}{F2xqX_rem}{GEN x, GEN y, GEN T} 6882 6883\fun{GEN}{F2xqX_div}{GEN x, GEN y, GEN T} 6884 6885\fun{GEN}{F2xqX_divrem}{GEN x, GEN y, GEN T, GEN *pr} 6886 6887\fun{GEN}{F2xqXQ_inv}{GEN x, GEN S, GEN T} 6888 6889\fun{GEN}{F2xqXQ_invsafe}{GEN x, GEN S, GEN T} 6890 6891\fun{GEN}{F2xqX_invBarrett}{GEN T, GEN Q} 6892 6893\fun{GEN}{F2xqX_extgcd}{GEN x, GEN y, GEN T, GEN *ptu, GEN *ptv} 6894 6895\fun{GEN}{F2xqX_gcd}{GEN x, GEN y, GEN T} 6896 6897\fun{GEN}{F2xqX_halfgcd}{GEN x, GEN y, GEN T} 6898 6899\fun{GEN}{F2xqX_resultant}{GEN x, GEN y, GEN T} 6900 6901\fun{GEN}{F2xqX_disc}{GEN x, GEN T} 6902 6903\fun{long}{F2xqX_ispower}{GEN f, ulong k, GEN T, GEN *pt} 6904 6905\fun{GEN}{F2xqX_F2xqXQ_eval}{GEN Q, GEN x, GEN S, GEN T} as 6906\kbd{FpX\_FpXQ\_eval}. 6907 6908\fun{GEN}{F2xqX_F2xqXQV_eval}{GEN P, GEN V, GEN S, GEN T} as 6909\kbd{FpX\_FpXQV\_eval}. 6910 6911\fun{GEN}{F2xqX_roots}{GEN f, GEN T} return the roots of \kbd{f} in 6912$\F_2[X]/(T)$. Assumes \kbd{T} irreducible in $\F_2[X]$. 6913 6914\fun{GEN}{F2xqX_factor}{GEN f, GEN T} return the factorization of \kbd{f} over 6915$\F_2[X]/(T)$. Assumes \kbd{T} irreducible in $\F_2[X]$. 6916 6917\fun{GEN}{F2xqX_factor_squarefree}{GEN f, GEN T} as 6918\kbd{FlxqX\_factor\_squarefree}. 6919 6920\fun{GEN}{F2xqX_ddf}{GEN f, GEN T} as \kbd{FpX\_ddf}. 6921 6922\fun{GEN}{F2xqX_degfact}{GEN f, GEN T} as \kbd{FpX\_degfact}. 6923 6924\subsec{\kbd{F2xqXQ}}. See \kbd{FlxqXQ} operations. 6925 6926\fun{GEN}{FlxqXQ_inv}{GEN x, GEN S, GEN T} 6927 6928\fun{GEN}{FlxqXQ_invsafe}{GEN x, GEN S, GEN T} 6929 6930\fun{GEN}{F2xqXQ_mul}{GEN x, GEN y, GEN S, GEN T} 6931 6932\fun{GEN}{F2xqXQ_sqr}{GEN x, GEN S, GEN T} 6933 6934\fun{GEN}{F2xqXQ_pow}{GEN x, GEN n, GEN S, GEN T} 6935 6936\fun{GEN}{F2xqXQ_powers}{GEN x, long n, GEN S, GEN T} 6937 6938\fun{GEN}{F2xqXQ_autpow}{GEN a, long n, GEN S, GEN T} 6939as \kbd{FpXQXQ\_autpow} 6940 6941\fun{GEN}{F2xqXQ_auttrace}{GEN a, long n, GEN S, GEN T}. Let 6942$\sigma$ be the automorphism defined by $\sigma(X)=a[1]\pmod{T(X)}$ and 6943$\sigma(Y)=a[2]\pmod{S(X,Y),T(X)}$; returns the vector 6944$[\sigma^n(X),\sigma^n(Y),b+\sigma(b)+\ldots+\sigma^{n-1}(b)]$ 6945where $b=a[3]$. 6946 6947\fun{GEN}{F2xqXQV_red}{GEN x, GEN S, GEN T} 6948 6949\subsec{Functions returning objects with \typ{INTMOD} coefficients} 6950 6951Those functions are mostly needed for interface reasons: \typ{INTMOD}s should 6952not be used in library mode since the modular kernel is more flexible and more 6953efficient, but GP users do not have access to the modular kernel. 6954We document them for completeness: 6955 6956\fun{GEN}{Fp_to_mod}{GEN z, GEN p}, \kbd{z} a \typ{INT}. Returns \kbd{z * 6957Mod(1,p)}, normalized. Hence the returned value is a \typ{INTMOD}. 6958 6959\fun{GEN}{FpX_to_mod}{GEN z, GEN p}, \kbd{z} a \kbd{ZX}. Returns \kbd{z * 6960Mod(1,p)}, normalized. Hence the returned value has \typ{INTMOD} coefficients. 6961 6962\fun{GEN}{FpC_to_mod}{GEN z, GEN p}, \kbd{z} a \kbd{ZC}. Returns \kbd{Col(z) * 6963Mod(1,p)}, a \typ{COL} with \typ{INTMOD} coefficients. 6964 6965\fun{GEN}{FpV_to_mod}{GEN z, GEN p}, \kbd{z} a \kbd{ZV}. Returns \kbd{Vec(z) * 6966Mod(1,p)}, a \typ{VEC} with \typ{INTMOD} coefficients. 6967 6968\fun{GEN}{FpVV_to_mod}{GEN z, GEN p}, \kbd{z} a \kbd{ZVV}. Returns \kbd{Vec(z) * 6969Mod(1,p)}, a \typ{VEC} of \typ{VEC} with \typ{INTMOD} coefficients. 6970 6971\fun{GEN}{FpM_to_mod}{GEN z, GEN p}, \kbd{z} a \kbd{ZM}. Returns \kbd{z * 6972Mod(1,p)}, with \typ{INTMOD} coefficients. 6973 6974\fun{GEN}{F2c_to_mod}{GEN x} 6975 6976\fun{GEN}{F2m_to_mod}{GEN x} 6977 6978\fun{GEN}{Flc_to_mod}{GEN z} 6979 6980\fun{GEN}{Flm_to_mod}{GEN z} 6981 6982\fun{GEN}{FqC_to_mod}{GEN z, GEN T, GEN p} 6983 6984\fun{GEN}{FqM_to_mod}{GEN z, GEN T, GEN p} 6985 6986\fun{GEN}{FpXC_to_mod}{GEN V, GEN p} 6987 6988\fun{GEN}{FpXM_to_mod}{GEN V, GEN p} 6989 6990\fun{GEN}{FpXQC_to_mod}{GEN V, GEN T, GEN p} $V$ being a vector of \kbd{FpXQ}, 6991converts each entry to a \typ{POLMOD} with \typ{INTMOD} coefficients, and return 6992a \typ{COL}. 6993 6994\fun{GEN}{FpXQX_to_mod}{GEN P, GEN T, GEN p} 6995$P$ being a \kbd{FpXQX}, converts each coefficient to a \typ{POLMOD} with 6996\typ{INTMOD} coefficients. 6997 6998\fun{GEN}{FqX_to_mod}{GEN P, GEN T, GEN p} same but allow 6999$\kbd{T} = \kbd{NULL}$. 7000 7001\fun{GEN}{FqXC_to_mod}{GEN P, GEN T, GEN p} 7002 7003\fun{GEN}{FqXM_to_mod}{GEN P, GEN T, GEN p} 7004 7005\fun{GEN}{QXQ_to_mod_shallow}{GEN x, GEN T} $x$ a \kbd{QXQ}, which is 7006a lifted representative of elements of $\Q[X]/(T)$ (number field elements 7007in most applications) and $T$ is in $\Z[X]$. Convert it to a \typ{POLMOD} 7008modulo $T$; no reduction mod $T$ is attempted: the representatives should be 7009already reduced. Shallow function. 7010 7011\fun{GEN}{QXQV_to_mod}{GEN V, GEN T} $V$ a vector of \kbd{QXQ}, which 7012are lifted representatives of elements of $\Q[X]/(T)$ (number field elements 7013in most applications) and $T$ is in $\Z[X]$. Return a vector where all 7014nonrational entries are converted to \typ{POLMOD} modulo $T$; no reduction 7015mod $T$ is attempted: the representatives should be already reduced. Used to 7016normalize the output of \kbd{nfroots}. 7017 7018\fun{GEN}{QXQX_to_mod_shallow}{GEN P, GEN T} $P$ a polynomial with \kbd{QXQ} 7019coefficients; replace them by \kbd{mkpolmod(.,T)}. Shallow function. 7020 7021\fun{GEN}{QXQC_to_mod_shallow}{GEN V, GEN T} $V$ a vector with \kbd{QXQ} 7022coefficients; replace them by \kbd{mkpolmod(.,T)}. Shallow function. 7023 7024\fun{GEN}{QXQM_to_mod_shallow}{GEN M, GEN T} $M$ a matrix with \kbd{QXQ} 7025coefficients; replace them by \kbd{mkpolmod(.,T)}. Shallow function. 7026 7027\fun{GEN}{QXQXV_to_mod}{GEN V, GEN T} $V$ a vector of polynomials whose 7028coefficients are \kbd{QXQ}. Analogous to \kbd{QXQV\_to\_mod}. 7029Used to normalize the output of \kbd{nffactor}. 7030 7031The following functions are obsolete and should not be used: they receive a 7032polynomial with arbitrary coefficients, apply a conversion function to map 7033them to a finite field, a function from the modular kernel, then 7034\kbd{*\_to\_mod}: 7035 7036\fun{GEN}{rootmod}{GEN f, GEN p}, applies \kbd{FpX\_roots}. 7037 7038\fun{GEN}{rootmod2}{GEN f, GEN p}, (now) identical to \kbd{rootmod}. 7039 7040\fun{GEN}{rootmod0}{GEN f, GEN p, long flag}, (now) identical to 7041\kbd{rootmod}; ignores \fl. 7042 7043\fun{GEN}{factmod}{GEN f, GEN p} applies \kbd{*\_factor}. 7044 7045\fun{GEN}{simplefactmod}{GEN f, GEN p} applies \kbd{*\_degfact}. 7046 7047\subsec{Slow Chinese remainder theorem over $\Z$} 7048The routines in this section have quadratic time complexity with respect to 7049the input size; see the routines in the next two sections for quasi-linear 7050time variants. 7051 7052\fun{GEN}{Z_chinese}{GEN a, GEN b, GEN A, GEN B} returns the integer 7053in $[0, \lcm(A,B)[$ congruent to $a$ mod $A$ and $b$ mod $B$, assuming it 7054exists; in other words, that $a$ and $b$ are congruent mod $\gcd(A,B)$. 7055 7056\fun{GEN}{Z_chinese_all}{GEN a, GEN b, GEN A, GEN B, GEN *pC} as 7057\kbd{Z\_chinese}, setting \kbd{*pC} to the lcm of $A$ and $B$. 7058 7059\fun{GEN}{Z_chinese_coprime}{GEN a, GEN b, GEN A, GEN B, GEN C}, as 7060\kbd{Z\_chinese}, assuming that $\gcd(A,B) = 1$ and that $C = \lcm(A,B) = AB$. 7061 7062\fun{ulong}{u_chinese_coprime}{ulong a, ulong b, ulong A, ulong B, ulong C}, as 7063\kbd{Z\_chinese\_coprime} for \kbd{ulong} inputs and output. 7064 7065\fun{void}{Z_chinese_pre}{GEN A, GEN B, GEN *pC, GEN *pU, GEN *pd} 7066initializes chinese remainder computations modulo $A$ and $B$. Sets 7067\kbd{*pC} to $\lcm(A,B)$, \kbd{*pd} to $\gcd(A,B)$, 7068\kbd{*pU} to an integer congruent to $0$ mod $(A/d)$ and $1$ mod $(B/d)$. 7069It is allowed to set \kbd{pd = NULL}, in which case, $d$ is still 7070computed, but not saved. 7071 7072\fun{GEN}{Z_chinese_post}{GEN a, GEN b, GEN C, GEN U, GEN d} returns 7073the solution to the chinese remainder problem $x$ congruent 7074to $a$ mod $A$ and $b$ mod $B$, where $C, U, d$ were set in 7075\kbd{Z\_chinese\_pre}. If $d$ is \kbd{NULL}, assume the problem has a 7076solution. Otherwise, return \kbd{NULL} if it has no solution. 7077 7078\medskip 7079 7080The following pair of functions is used in homomorphic imaging schemes, 7081when reconstructing an integer from its images modulo pairwise coprime 7082integers. The idea is as follows: we want to discover an integer $H$ which 7083satisfies $|H| < B$ for some known bound $B$; we are given pairs $(H_p, p)$ 7084with $H$ congruent to $H_p$ mod $p$ and all $p$ pairwise coprime. 7085 7086Given \kbd{H} congruent to $H_p$ modulo a number of $p$, whose product is 7087$q$, and a new pair $(\kbd{Hp}, \kbd{p})$, \kbd{p} coprime to $q$, the 7088following incremental functions use the chinese remainder theorem (CRT) to 7089find a new \kbd{H}, congruent to the preceding one modulo $q$, but also to 7090\kbd{Hp} modulo \kbd{p}. It is defined uniquely modulo $qp$, and we choose 7091the centered representative. When $P$ is larger than $2B$, we have $\kbd{H} = 7092H$, but of course, the value of \kbd{H} may stabilize sooner. In many 7093applications it is possible to directly check that such a partial result is 7094correct. 7095 7096\fun{GEN}{Z_init_CRT}{ulong Hp, ulong p} given a \kbd{Fl} \kbd{Hp} in 7097$[0, p-1]$, returns the centered representative \kbd{H} congruent to \kbd{Hp} 7098modulo \kbd{p}. 7099 7100\fun{int}{Z_incremental_CRT}{GEN *H, ulong Hp, GEN *q, ulong p} 7101given a \typ{INT} \kbd{*H}, centered modulo \kbd{*q}, a new pair $(\kbd{Hp}, 7102\kbd{p})$ with \kbd{p} coprime to \kbd{q}, this function updates \kbd{*H} so 7103that it also becomes congruent to $(\kbd{Hp}, \kbd{p})$, and \kbd{*q} to the 7104product$\kbd{qp} = \kbd{p} \cdot \kbd{*q}$. It returns $1$ if the new value 7105is equal to the old one, and $0$ otherwise. 7106 7107\fun{GEN}{chinese1_coprime_Z}{GEN v} an alternative divide-and-conquer 7108implementation: $v$ is a vector of \typ{INTMOD} with pairwise coprime moduli. 7109Return the \typ{INTMOD} solving the corresponding chinese remainder problem. 7110This is a streamlined version of 7111 7112\fun{GEN}{chinese1}{GEN v}, which solves a general chinese remainder problem 7113(not necessarily over $\Z$, moduli not assumed coprime). 7114 7115As above, for $H$ a \kbd{ZM}: we assume that $H$ and all \kbd{Hp} have 7116dimension $> 0$. The original \kbd{*H} is destroyed. 7117 7118\fun{GEN}{ZM_init_CRT}{GEN Hp, ulong p} 7119 7120\fun{int}{ZM_incremental_CRT}{GEN *H, GEN Hp, GEN *q, ulong p} 7121 7122As above for $H$ a \kbd{ZX}: note that the degree may increase or decrease. 7123The original \kbd{*H} is destroyed. 7124 7125\fun{GEN}{ZX_init_CRT}{GEN Hp, ulong p, long v} 7126 7127\fun{int}{ZX_incremental_CRT}{GEN *H, GEN Hp, GEN *q, ulong p} 7128 7129As above, for $H$ a matrix whose coefficient are \kbd{ZX}. 7130The original \kbd{*H} is destroyed. 7131The entries of $H$ are not normalized, use \kbd{ZX\_renormalize} 7132for this. 7133 7134\fun{GEN}{ZXM_init_CRT}{GEN Hp, long deg, ulong p} where \kbd{deg} 7135is the maximal degree of all the \kbd{Hp} 7136 7137\fun{int}{ZXM_incremental_CRT}{GEN *H, GEN Hp, GEN *q, ulong p} 7138 7139\subsec{Fast remainders} 7140 7141The routines in these section are asymptotically fast (quasi-linear time in 7142the input size). 7143 7144\fun{GEN}{Z_ZV_mod}{GEN A, GEN P} given a \typ{INT} $A$ and a vector $P$ of 7145positive pairwise coprime integers of length $n\ge 1$, return a vector $B$ of 7146the same length such that $B[i] = A\pmod{P[i]}$ and $0\leq B[i] < P[i]$ for 7147all $1\leq i\leq n$. The vector $P$ may be a \typ{VEC} or a \typ{VECSMALL} 7148(treated as \kbd{ulong}s) and $B$ has the same type as $P$. 7149 7150\fun{GEN}{Z_nv_mod}{GEN A, GEN P} given a \typ{INT} $A$ and a \typ{VECSMALL} 7151$P$ of positive pairwise coprime integers of length $n\ge 1$, return a 7152\typ{VECSMALL} $B$ of the same length such that $B[i]=A\pmod{P[i]}$ and 7153$0\leq B[i] < P[i]$ for all $1\leq i\leq n$. The entries of $P$ and $B$ are 7154treated as \kbd{ulong}s. 7155 7156The following low level functions allow precomputations: 7157 7158\fun{GEN}{ZV_producttree}{GEN P} where $P$ is a vector of integers (or 7159\typ{VECSMALL}) of length $n\ge 1$, return the vector of \typ{VEC}s 7160$[f(P),f^2(P),\ldots,f^k(P)]$ where $f$ is the transformation 7161$[p_1,p_2,\ldots,p_m] \mapsto [p_1\*p_2,p_3\*p_4,\ldots,p_{m-1}\*p_m]$ if $m$ 7162is even and $[p_1\*p_2,p_3\*p_4,\ldots,p_{m-2}\*p_{m-1},p_m]$ if $m$ is odd, 7163and $k = O(\log m)$ is minimal so that $f^k(P)$ has length $1$; in other 7164words, $f^k(P) = [p_1\*p_2\*\ldots\*p_m]$. 7165 7166\fun{GEN}{Z_ZV_mod_tree}{GEN A, GEN P, GEN T} 7167as \kbd{Z\_ZV\_mod} where $T$ is the tree \kbd{ZV\_producttree(P)}. 7168 7169\fun{GEN}{ZV_nv_mod_tree}{GEN A, GEN P, GEN T} $A$ being a \kbd{ZV} 7170and $P$ a \typ{VECSMALL} of length $n\ge 1$, the elements of $P$ being 7171pairwise coprime, return the vector of \kbd{Flv} 7172$[A \pmod{P[1]},\ldots,A \pmod{P[n]}]$, 7173where $T$ is the tree \kbd{ZV\_producttree(P)}. 7174 7175\fun{GEN}{ZM_nv_mod_tree}{GEN A, GEN P, GEN T} $A$ being a \kbd{ZM} 7176and $P$ a \typ{VECSMALL} of length $n\ge 1$, the elements of $P$ being 7177pairwise coprime, return the vector of \kbd{Flm} 7178$[A \pmod{P[1]},\ldots,A \pmod{P[n]}]$, 7179where $T$ is the tree \kbd{ZV\_producttree(P)}. 7180 7181\fun{GEN}{ZX_nv_mod_tree}{GEN A, GEN P, GEN T} $A$ being a \kbd{ZX} 7182and $P$ a \typ{VECSMALL} of length $n\ge 1$, the elements of $P$ being 7183pairwise coprime, return the vector of \kbd{Flx} polynomials 7184$[A \pmod{P[1]},\ldots,A \pmod{P[n]}]$, 7185where $T$ is the tree \kbd{ZV\_producttree(P)}. 7186 7187\fun{GEN}{ZXC_nv_mod_tree}{GEN A, GEN P, GEN T} $A$ being a \kbd{ZXC} 7188and $P$ a \typ{VECSMALL} of length $n\ge 1$, the elements of $P$ being 7189pairwise coprime, return the vector of \kbd{FlxC} 7190$[A \pmod{P[1]},\ldots,A \pmod{P[n]}]$, 7191where $T$ is the tree \kbd{ZV\_producttree(P)}. 7192 7193\fun{GEN}{ZXM_nv_mod_tree}{GEN A, GEN P, GEN T} $A$ being a \kbd{ZXM} 7194and $P$ a \typ{VECSMALL} of length $n\ge 1$, the elements of $P$ being 7195pairwise coprime, return the vector of \kbd{FlxM} 7196$[A \pmod{P[1]},\ldots,A \pmod{P[n]}]$, 7197where $T$ is the tree \kbd{ZV\_producttree(P)}. 7198 7199\fun{GEN}{ZXX_nv_mod_tree}{GEN A, GEN P, GEN T, long v} $A$ being a \kbd{ZXX}, 7200and $P$ a \typ{VECSMALL} of length $n\ge 1$, the elements of $P$ being 7201pairwise coprime, return the vector of \kbd{FlxX} 7202$[A \pmod{P[1]},\ldots,A \pmod{P[n]}]$, 7203where $T$ is assumed to be the tree created by \kbd{ZV\_producttree(P)}. 7204 7205\medskip 7206 7207\subsec{Fast Chinese remainder theorem over $\Z$} 7208The routines in these section are asymptotically fast (quasi-linear time in 7209the input size) and should be used whenever the moduli are known from 7210the start. 7211 7212The simplest function is 7213 7214\fun{GEN}{ZV_chinese}{GEN A, GEN P, GEN *pM} 7215let $P$ be a vector of positive pairwise coprime integers, let $A$ be a 7216vector of integers of the same length $n\ge 1$ such that $0 \leq A[i] < P[i]$ 7217for all $i$, and let $M$ be the product of the elements of $P$. Returns the 7218integer in $[0, M[$ congruent to $A[i]$ mod $P[i]$ for all $1\leq i\leq n$. 7219If \kbd{pM} is not \kbd{NULL}, set \kbd{*pM} to $M$. We also allow 7220\typ{VECSMALL}s for $A$ and $P$ (seen as vectors of unsigned integers). 7221 7222\fun{GEN}{ZV_chinese_center}{GEN A, GEN P, GEN *pM} 7223As \kbd{ZV\_chinese} but return integers in $[-M/2, M/2[$ instead. 7224 7225The following functions allow to solve many Chinese remainder problems 7226simultaneously, for a given set of moduli: 7227 7228\fun{GEN}{nxV_chinese_center}{GEN A, GEN P, GEN *pt_mod} 7229where $A$ is a vector of \kbd{nx} 7230and $P$ a \typ{VECSMALL} of the same length $n\ge 1$, the elements of $P$ 7231being pairwise coprime, and $M$ being the product of the elements of $P$, 7232returns the \typ{POL} whose entries are integers in $[-M/2, M/2[$ congruent to $A[i]$ 7233mod $P[i]$ for all $1\leq i\leq n$. 7234If \kbd{pt\_mod} is not \kbd{NULL}, set \kbd{*pt\_mod} to $M$. 7235 7236\fun{GEN}{ncV_chinese_center}{GEN A, GEN P, GEN *pM} where $A$ is a 7237vector of \kbd{VECSMALL}s (seen as vectors of unsigned integers) and $P$ a 7238\typ{VECSMALL} of the same length $n\ge 1$, the elements of $P$ being 7239pairwise coprime, and $M$ being the product of the elements of $P$, returns 7240the \typ{COL} whose entries are integers in $[-M/2, M/2[$ congruent to $A[i]$ 7241mod $P[i]$ for all $1\leq i\leq n$. If \kbd{pM} is not \kbd{NULL}, set 7242\kbd{*pt\_mod} to $M$. 7243 7244\fun{GEN}{nmV_chinese_center}{GEN A, GEN P, GEN *pM} where $A$ is a 7245vector of \kbd{MATSMALL}s (seen as matrices of unsigned integers) and $P$ a 7246\typ{VECSMALL} of the same length $n\ge 1$, the elements of $P$ being 7247pairwise coprime, and $M$ being the product of the elements of $P$, returns 7248the matrix whose entries are integers in $[-M/2, M/2[$ congruent to $A[i]$ 7249mod $P[i]$ for all $1\leq i\leq n$. If \kbd{pM} is not \kbd{NULL}, set 7250\kbd{*pM} to $M$. N.B.: this function uses the parallel GP interface. 7251 7252\fun{GEN}{nxCV_chinese_center}{GEN A, GEN P, GEN *pM} where $A$ is a 7253vector of \kbd{nxC}s and $P$ a 7254\typ{VECSMALL} of the same length $n\ge 1$, the elements of $P$ being 7255pairwise coprime, and $M$ being the product of the elements of $P$, returns 7256the \typ{COL} whose entries are integers in $[-M/2, M/2[$ congruent to $A[i]$ 7257mod $P[i]$ for all $1\leq i\leq n$. If \kbd{pM} is not \kbd{NULL}, set 7258\kbd{*pt\_mod} to $M$. 7259 7260\fun{GEN}{nxMV_chinese_center}{GEN A, GEN P, GEN *pM} where $A$ is a 7261vector of \kbd{nxM}s and $P$ a 7262\typ{VECSMALL} of the same length $n\ge 1$, the elements of $P$ being 7263pairwise coprime, and $M$ being the product of the elements of $P$, returns 7264the matrix whose entries are integers in $[-M/2, M/2[$ congruent to $A[i]$ 7265mod $P[i]$ for all $1\leq i\leq n$. If \kbd{pM} is not \kbd{NULL}, set 7266\kbd{*pM} to $M$. N.B.: this function uses the parallel GP interface. 7267 7268The other routines allow for various precomputations : 7269 7270\fun{GEN}{ZV_chinesetree}{GEN P, GEN T} given $P$ a vector of integers 7271(or \typ{VECSMALL}) and a product tree $T$ from \tet{ZV_producttree}$(P)$ 7272for the same $P$, return a ``chinese remainder tree'' $R$, preconditionning 7273the solution of Chinese remainder problems modulo the $P[i]$. 7274 7275\fun{GEN}{ZV_chinese_tree}{GEN A, GEN P, GEN T, GEN R} 7276return \kbd{ZV\_chinese}$(A,P,\kbd{NULL})$, where $T$ is created by 7277\kbd{ZV\_producttree}$(P)$ and $R$ by \kbd{ZV\_chinesetree}$(P,T)$. 7278 7279\fun{GEN}{ncV_chinese_center_tree}{GEN A, GEN P, GEN T, GEN R} 7280as \kbd{ncV\_chinese\_center} where $T$ is assumed to be the tree created by 7281\kbd{ZV\_producttree(P)} and $R$ by \kbd{ZV\_chinesetree}$(P,T)$. 7282 7283\fun{GEN}{nmV_chinese_center_tree}{GEN A, GEN P, GEN T, GEN R} 7284as \kbd{nmV\_chinese\_center} where $T$ is assumed to be the tree created by 7285\kbd{ZV\_producttree(P)} and $R$ by \kbd{ZV\_chinesetree}$(P,T)$. 7286 7287\fun{GEN}{nxV_chinese_center_tree}{GEN A, GEN P, GEN T, GEN R} 7288as \kbd{nxV\_chinese\_center} where $T$ is assumed to be the tree created by 7289\kbd{ZV\_producttree(P)} and $R$ by \kbd{ZV\_chinesetree}$(P,T)$. 7290 7291\fun{GEN}{nxCV_chinese_center_tree}{GEN A, GEN P, GEN T, GEN R} 7292as \kbd{nxCV\_chinese\_center} where $T$ is assumed to be the tree created by 7293\kbd{ZV\_producttree(P)} and $R$ by \kbd{ZV\_chinesetree}$(P,T)$. 7294 7295\subsec{Rational reconstruction} 7296 7297\fun{int}{Fp_ratlift}{GEN x, GEN m, GEN amax, GEN bmax, GEN *a, GEN *b}. 7298Assuming that $0 \leq x < m$, $\kbd{amax} \geq 0$, and 7299$\kbd{bmax} > 0$ are \typ{INT}s, and that $2 \kbd{amax} \kbd{bmax} < m$, 7300attempts to recognize $x$ as a rational $a/b$, i.e. to find \typ{INT}s $a$ 7301and $b$ such that 7302 7303\item $a \equiv b x$ modulo $m$, 7304 7305\item $|a| \leq \kbd{amax}$, $0 < b \leq \kbd{bmax}$, 7306 7307\item $\gcd(m,b) = \gcd(a,b)$. 7308 7309\noindent If unsuccessful, the routine returns $0$ and leaves $a$, $b$ 7310unchanged; otherwise it returns $1$ and sets $a$ and $b$. 7311 7312In almost all applications, we actually know that a solution exists, as well 7313as a nonzero multiple $B$ of $b$, and $m = p^\ell$ is a prime power, for a 7314prime $p$ chosen coprime to $B$ hence to $b$. Under the single assumption 7315$\gcd(m,b) = 1$, if a solution $a,b$ exists satisfying the three conditions 7316above, then it is unique. 7317 7318\fun{GEN}{FpM_ratlift}{GEN M, GEN m, GEN amax, GEN bmax, GEN denom} 7319given an \kbd{FpM} modulo $m$ with reduced or \kbd{Fp\_center}-ed entries, 7320reconstructs a matrix with rational coefficients by applying \kbd{Fp\_ratlift} 7321to all entries. Assume that all preconditions for \kbd{Fp\_ratlift} are 7322satisfied, as well $\gcd(m,b) = 1$ (so that the solution is unique if it 7323exists). Return \kbd{NULL} if the reconstruction fails, and the rational 7324matrix otherwise. If \kbd{denom} is not \kbd{NULL} check further that all 7325denominators divide \kbd{denom}. 7326 7327The function is not stack clean if one of the coefficients of $M$ is negative 7328(centered residues), but still suitable for \kbd{gerepileupto}. 7329 7330\fun{GEN}{FpX_ratlift}{GEN P, GEN m, GEN amax, GEN bmax, GEN denom} as 7331\kbd{FpM\_ratlift}, where $P$ is an \kbd{FpX}. 7332 7333\fun{GEN}{FpC_ratlift}{GEN P, GEN m, GEN amax, GEN bmax, GEN denom} as 7334\kbd{FpM\_ratlift}, where $P$ is an \kbd{FpC}. 7335 7336\subsec{Zp} 7337 7338\fun{GEN}{Zp_sqrt}{GEN b, GEN p, long e} $b$ and $p$ being \typ{INT}s, with $p$ 7339a prime (possibly $2$), returns a \typ{INT} $a$ such that $a^2 \equiv b \mod 7340p^e$. 7341 7342\fun{GEN}{Z2_sqrt}{GEN b, long e} $b$ being a \typ{INT}s 7343returns a \typ{INT} $a$ such that $a^2 \equiv b \mod 2^e$. 7344 7345\fun{GEN}{Zp_sqrtlift}{GEN b, GEN a, GEN p, long e} let 7346$a,b,p$ be \typ{INT}s, with $p > 1$ odd, such that $a^2\equiv b\mod p$. 7347Returns a \typ{INT} $A$ such that $A^2 \equiv b \mod p^e$. Special case 7348of \tet{Zp_sqrtnlift}. 7349 7350\fun{GEN}{Zp_sqrtnlift}{GEN b, GEN n, GEN a, GEN p, long e} let 7351$a,b,n,p$ be \typ{INT}s, with $n,p > 1$, and $p$ coprime to $n$, 7352such that $a^n \equiv b \mod p$. Returns a \typ{INT} $A$ such that 7353$A^n \equiv b \mod p^e$. Special case of \tet{ZpX_liftroot}. 7354 7355\fun{GEN}{Zp_teichmuller}{GEN x, GEN p, long e, GEN pe} for $p$ an odd prime, 7356$x$ a \typ{INT} coprime to $p$, and $pe = p^e$, returns the $(p-1)$-th root of 7357$1$ congruent to $x$ modulo $p$, modulo $p^e$. For convenience, $p = 2$ is 7358also allowed and we return $1$ ($x$ is $1$ mod $4$) or $2^e - 1$ ($x$ is $3$ 7359mod $4$). 7360 7361\fun{GEN}{teichmullerinit}{long p, long n} returns the values of 7362\tet{Zp_teichmuller} at all $x = 1, \dots, p-1$. 7363 7364\subsec{ZpM} 7365 7366\fun{GEN}{ZpM_invlift}{GEN M, GEN Np, GEN p, long e} let 7367$p$ be a prime \typ{INT}, $Np$ be a \kbd{FpM} (modulo $p$) and 7368$M$ a \kbd{ZpM} such that $M\*Np \equiv 1 \mod p$. 7369Returns an \kbd{ZpM} $N$ such that $N \equiv Np \pmod{p}$ and 7370$M\*N \equiv 1 \mod p^e$. 7371 7372\subsec{ZpX} 7373 7374\fun{GEN}{ZpX_roots}{GEN f, GEN p, long e} $f$ a \kbd{ZX} with leading 7375term prime to $p$, and without multiple roots mod $p$. Return a vector 7376of \typ{INT}s which are the roots of $f$ mod $p^e$. 7377 7378\fun{GEN}{ZpX_liftroot}{GEN f, GEN a, GEN p, long e} $f$ a \kbd{ZX} with 7379leading term prime to $p$, and $a$ a root mod $p$ such that 7380$v_p(f'(a))=0$. Return a \typ{INT} which is the root of $f$ mod $p^e$ 7381congruent to $a$ mod $p$. 7382 7383\fun{GEN}{ZX_Zp_root}{GEN f, GEN a, GEN p, long e} same as \tet{ZpX_liftroot} 7384without the assumption $v_p(f'(a)) = 0$. Return a \typ{VEC} of \typ{INT}s, 7385which are the $p$-adic roots of $f$ congruent to $a$ mod $p$ (given modulo 7386$p^e$). 7387 7388\fun{GEN}{ZpX_liftroots}{GEN f, GEN S, GEN p, long e} $f$ a \kbd{ZX} with 7389leading term prime to $p$, and $S$ a vector of simple roots mod $p$. Return a 7390vector of \typ{INT}s which are the root of $f$ mod $p^e$ congruent to the 7391$S[i]$ mod $p$. 7392 7393\fun{GEN}{ZpX_liftfact}{GEN A, GEN B, GEN pe, GEN p, long e} is 7394the routine underlying \tet{polhensellift}. Here, $p$ is prime 7395defines a finite field $\F_p$. $A$ is a polynomial in 7396$\Z[X]$, whose leading coefficient is nonzero in $\F_q$. $B$ is a vector of 7397monic \kbd{FpX}, pairwise coprime in $\F_p[X]$, whose product is congruent to 7398$A/\text{lc}(A)$ in $\F_p[X]$. Lifts the elements of $B$ mod $\kbd{pe} = p^e$. 7399 7400\fun{GEN}{ZpX_Frobenius}{GEN T, GEN p, ulong e} returns the $p$-adic lift 7401of the Frobenius automorphism of $\F_p[X]/(T)$ to precision $e$. 7402 7403\fun{long}{ZpX_disc_val}{GEN f, GEN p} returns the valuation at $p$ of the 7404discriminant of $f$. Assume that $f$ is a monic \emph{separable} \kbd{ZX} 7405and that $p$ is a prime number. Proceeds by dynamically increasing the 7406$p$-adic accuracy; infinite loop if the discriminant of $f$ is 7407$0$. 7408 7409\fun{long}{ZpX_resultant_val}{GEN f, GEN g, GEN p, long M} returns the 7410valuation at $p$ of $\text{Res}(f,g)$. Assume $f,g$ are both \kbd{ZX}, 7411and that $p$ is a prime number coprime to the leading coefficient of $f$. 7412Proceeds by dynamically increasing the $p$-adic accuracy. 7413To avoid an infinite loop when the resultant is $0$, we return $M$ if 7414the Sylvester matrix mod $p^M$ still does not have maximal rank. 7415 7416\fun{GEN}{ZpX_gcd}{GEN f,GEN g, GEN p, GEN pm} $f$ a monic \kbd{ZX}, 7417$g$ a \kbd{ZX}, $\kbd{pm} = p^m$ a prime power. There is a unique integer 7418$r\geq 0$ and a monic $h\in \Q_p[X]$ such that 7419$$p^rh\Z_p[X] + p^m\Z_p[X] = f\Z_p[X] + g\Z_p[X] + p^m\Z_p[X].$$ 7420Return the $0$ polynomial if $r\geq m$ and a monic $h\in\Z[1/p][X]$ otherwise 7421(whose valuation at $p$ is $> -m$). 7422 7423\fun{GEN}{ZpX_reduced_resultant}{GEN f, GEN g, GEN p, GEN pm} $f$ a monic 7424\kbd{ZX}, $g$ a \kbd{ZX}, $\kbd{pm} = p^m$ a prime power. The $p$-adic 7425\emph{reduced resultant}\varsidx{resultant (reduced)} of $f$ and $g$ is 7426$0$ if $f$, $g$ not coprime in $\Z_p[X]$, and otherwise the generator of the 7427form $p^d$ of 7428$$ (f\Z_p[X] + g\Z_p[X])\cap \Z_p. $$ 7429Return the reduced resultant modulo $p^m$. 7430 7431\fun{GEN}{ZpX_reduced_resultant_fast}{GEN f, GEN g, GEN p, long M} $f$ 7432a monic \kbd{ZX}, $g$ a \kbd{ZX}, $p$ a prime. Returns 7433the $p$-adic reduced resultant of $f$ and $g$ modulo $p^M$. This function 7434computes resultants for a sequence of increasing $p$-adic accuracies 7435(up to $M$ $p$-adic digits), returning as soon as it obtains a nonzero 7436result. It is very inefficient when the resultant is $0$, but otherwise 7437usually more efficient than computations using a priori bounds. 7438 7439\fun{GEN}{ZpX_monic_factor}{GEN f, GEN p, long M} $f$ a monic 7440\kbd{ZX}, $p$ a prime, return the $p$-adic factorization of $f$, modulo 7441$p^M$. This is the underlying low-level recursive function behind 7442\kbd{factorpadic} (using a combination of Round 4 factorization and Hensel 7443lifting); the factors are not sorted and the function is not 7444\kbd{gerepile}-clean. 7445 7446\fun{GEN}{ZpX_primedec}{GEN T, GEN p} $T$ a monic separable \kbd{ZX}, $p$ a 7447prime, return as a factorization matrix the shape of the prime ideal 7448decomposition of $(p)$ in $\Q[X]/(T)$: the first column contains inertia 7449degrees, the second columns contains ramification degrees. 7450 7451\subsec{ZpXQ} 7452 7453\fun{GEN}{ZpXQ_invlift}{GEN b, GEN a, GEN T, GEN p, long e} let 7454$p$ be a prime \typ{INT}, $a$ be a \kbd{FpXQ} (modulo $(p, T)$) and 7455$b$ a \kbd{ZpXQ} such that $a\*b \equiv 1 \mod (p, T)$. 7456Returns an \kbd{ZpXQ} $A$ such that $A \equiv a \pmod{p}$ and 7457$A\*b \equiv 1 \mod (p^e, T)$. 7458 7459\fun{GEN}{ZpXQ_inv}{GEN b, GEN T, GEN p, long e} let 7460$p$ be a prime \typ{INT} and $b$ be a \kbd{FpXQ} (modulo $T, p^e$). 7461Returns an \kbd{FpXQ} $A$ such that $A\*b \equiv 1 \mod (p^e, T)$. 7462 7463\fun{GEN}{ZpXQ_div}{GEN a, GEN b, GEN T, GEN q, GEN p, long e} let 7464$p$ be a prime \typ{INT} and $a$ and $b$ be a \kbd{FpXQ} (modulo $T, p^e$). 7465Returns an \kbd{FpXQ} $c$ such that $c\*b \equiv a \mod (p^e, T)$. 7466The parameter $q$ must be equal to $p^e$. 7467 7468\fun{GEN}{ZpXQ_sqrtnlift}{GEN b, GEN n, GEN a, GEN T, GEN p, long e} let 7469$n,p$ be \typ{INT}s, with $n,p > 1$ and $p$ coprime to $n$, and $a,b$ 7470be \kbd{FpXQ}s (modulo $T$) such that $a^n \equiv b \mod (p,T)$. 7471Returns an \kbd{Fq} $A$ such that $A^n \equiv b \mod (p^e, T)$. 7472 7473\fun{GEN}{ZpXQ_sqrt}{GEN b, GEN T, GEN p, long e} let 7474$p$ being a odd prime and $b$ be a \kbd{FpXQ} (modulo $T, p^e$), 7475returns $a$ such that $a^2 \equiv b \mod (p^e, T)$. 7476 7477\fun{GEN}{ZpX_ZpXQ_liftroot}{GEN f, GEN a, GEN T, GEN p, long e} 7478as \tet{ZpXQX_liftroot}, but $f$ is a polynomial in $\Z[X]$. 7479 7480\fun{GEN}{ZpX_ZpXQ_liftroot_ea}{GEN f, GEN a, GEN T, GEN p, long e, 7481 void *E, GEN early(void *E, GEN x, GEN q)} 7482as \tet{ZpX_ZpXQ_liftroot} with early abort: the function \kbd{early(E,x,q)} 7483will be called with $x$ is a root of $f$ modulo $q=p^n$ for some $n$. If 7484\kbd{early} returns a non-\kbd{NULL} value $z$, the function returns $z$ 7485immediately. 7486 7487\fun{GEN}{ZpXQ_log}{GEN a, GEN T, GEN p, long e} $T$ being a \kbd{ZpX} 7488irreducible modulo $p$, return the logarithm of $a$ in $\Z_p[X]/(T)$ to 7489precision $e$, assuming that $a\equiv 1 \pmod{p\Z_p[X]}$ if $p$ odd or 7490$a\equiv 1 \pmod{4\Z_2[X]}$ if $p=2$. 7491 7492\subsec{Zq} 7493 7494\fun{GEN}{Zq_sqrtnlift}{GEN b, GEN n, GEN a, GEN T, GEN p, long e} 7495 7496\subsec{ZpXQM} 7497 7498\fun{GEN}{ZpXQM_prodFrobenius}{GEN M, GEN T, GEN p, long e} 7499returns the product of matrices $M\*\sigma(M)\*\sigma^2(M)\ldots\sigma^{n-1}(M)$ 7500to precision $e$ where $\sigma$ is the lift of the Frobenius automorphism 7501over $\Z_p[X]/(T)$ and $n$ is the degree of $T$. 7502 7503\subsec{ZpXQX} 7504 7505\fun{GEN}{ZpXQX_liftfact}{GEN A, GEN B, GEN T, GEN pe, GEN p, long e} is the 7506routine underlying \tet{polhensellift}. Here, $p$ is prime, $T(Y)$ defines a 7507finite field $\F_q$. $A$ is a polynomial in $\Z[X,Y]$, whose leading 7508coefficient is nonzero in $\F_q$. $B$ is a vector of monic or \kbd{FqX}, 7509pairwise coprime in $\F_q[X]$, whose product is congruent to $A/\text{lc}(A)$ 7510in $\F_q[X]$. Lifts the elements of $B$ mod $\kbd{pe} = p^e$, such that the 7511congruence now holds mod $(T,p^e)$. 7512 7513\fun{GEN}{ZpXQX_liftroot}{GEN f, GEN a, GEN T, GEN p, long e} as 7514\tet{ZpX_liftroot}, but $f$ is now a polynomial in $\Z[X,Y]$ and lift the 7515root $a$ in the unramified extension of $\Q_p$ with residue field $\F_p[Y]/(T)$, 7516assuming $v_p(f(a))>0$ and $v_p(f'(a))=0$. 7517 7518\fun{GEN}{ZpXQX_liftroot_vald}{GEN f, GEN a, long v, GEN T, GEN p, long e} 7519returns the foots of $f$ as \tet{ZpXQX_liftroot}, where $v$ is the valuation 7520of the content of $f'$ and it is required that $v_p(f(a))>v$ and 7521$v_p(f'(a))=v$. 7522 7523\fun{GEN}{ZpXQX_roots}{GEN F, GEN T, GEN p, long e} 7524 7525\fun{GEN}{ZpXQX_liftroots}{GEN F, GEN S, GEN T, GEN p, long e} 7526 7527\fun{GEN}{ZpXQX_divrem}{GEN x, GEN Sp, GEN T,GEN q,GEN p,long e, GEN *pr} 7528as \kbd{FpXQX\_divrem}. The parameter $q$ must be equal to $p^e$. 7529 7530\fun{GEN}{ZpXQX_digits}{GEN x, GEN B, GEN T, GEN q, GEN p, long e} 7531As \kbd{FpXQX\_digits}. The parameter $q$ must be equal to $p^e$. 7532 7533\subsec{ZqX} 7534 7535\fun{GEN}{ZqX_roots}{GEN F, GEN T, GEN p, long e} 7536 7537\fun{GEN}{ZqX_liftfact}{GEN A, GEN B, GEN T, GEN pe, GEN p, long e} 7538 7539\fun{GEN}{ZqX_liftroot}{GEN f, GEN a, GEN T, GEN p, long e} 7540 7541\subsec{Other $p$-adic functions} 7542 7543\fun{GEN}{ZpM_echelon}{GEN M, long early_abort, GEN p, GEN pm} given a 7544\kbd{ZM} $M$, a prime $p$ and $\kbd{pm} = p^m$, returns an echelon form 7545$E$ for $M$ mod $p^m$. I.e. there exist a square integral matrix $U$ with 7546$\det U$ coprime to $p$ such that $E = MU$ modulo $p^m$. I 7547\kbd{early\_abort} is nonzero, return NULL as soon as one pivot in 7548the echelon form is divisible by $p^m$. The echelon form is an upper 7549triangular HNF, we do not waste time to reduce it to Gauss-Jordan form. 7550 7551\fun{GEN}{zlm_echelon}{GEN M, long early_abort, ulong p, ulong pm} 7552variant of \kbd{ZpM\_echelon}, for a \kbd{Zlm} $M$. 7553 7554\fun{GEN}{ZlM_gauss}{GEN a, GEN b, ulong p, long e, GEN C} as \kbd{gauss} 7555with the following peculiarities: $a$ and $b$ are \kbd{ZM}, such that $a$ is 7556invertible modulo $p$. Optional $C$ is an \kbd{Flm} that is an inverse of 7557$a\mod p$ or \kbd{NULL}. Return the matrix $x$ such that $ax=b\mod p^e$ and 7558all elements of $x$ are in $[0,p^e-1]$. For efficiency, it is better 7559to reduce $a$ and $b$ mod $p^e$ first. 7560 7561\fun{GEN}{padic_to_Q}{GEN x} truncate the \typ{PADIC} to a \typ{INT} or 7562\typ{FRAC}. 7563 7564\fun{GEN}{padic_to_Q_shallow}{GEN x} shallow version of \tet{padic_to_Q} 7565 7566\fun{GEN}{QpV_to_QV}{GEN v} apply \tet{padic_to_Q_shallow} 7567 7568\fun{long}{padicprec}{GEN x, GEN p} returns the absolute $p$-adic precision of 7569the object $x$, by definition the minimum precision of the components of $x$. 7570For a nonzero \typ{PADIC}, this returns \kbd{valp(x) + precp(x)}. 7571 7572\fun{long}{padicprec_relative}{GEN x} returns the relative $p$-adic 7573precision of the \typ{INT}, \typ{FRAC}, or \typ{PADIC} $x$ (minimum precision 7574of the components of $x$ for \typ{POL} or vector/matrices). 7575For a \typ{PADIC}, this returns \kbd{precp(x)} if $x\neq0$, and $0$ for $x=0$. 7576 7577\subsubsec{low-level} 7578 7579The following technical function returns an optimal sequence of $p$-adic 7580accuracies, for a given target accuracy: 7581 7582\fun{ulong}{quadratic_prec_mask}{long n} we want to reach accuracy 7583$n\geq 1$, starting from accuracy 1, using a quadratically convergent, 7584self-correcting, algorithm; in other words, from inputs correct to accuracy 7585$l$ one iteration outputs a result correct to accuracy $2l$. 7586For instance, to reach $n = 9$, we want to use accuracies 7587$[1,2,3,5,9]$ instead of $[1,2,4,8,9]$. The idea is to essentially double 7588the accuracy at each step, and not overshoot in the end. 7589 7590Let $a_0$ = 1, $a_1 = 2, \ldots, a_k = n$, be the desired sequence of 7591accuracies. To obtain it, we work backwards and set 7592$$ a_k = n,\quad a_{i-1} = (a_i + 1)\,\bs\, 2.$$ 7593This is in essence what the function returns. 7594But we do not want to store the $a_i$ explicitly, even as a \typ{VECSMALL}, 7595since this would leave an object on the stack. Instead, we store $a_i$ 7596implicitly in a bitmask \kbd{MASK}: let $a_0 = 1$, if the $i$-th bit of the 7597mask is set, set $a_{i+1} = 2a_i - 1$, and $2a_i$ otherwise; in short the 7598bits indicate the places where we do something special and do not quite 7599double the accuracy (which would be the straightforward thing to do). 7600 7601In fact, to avoid returning separately the mask and the sequence length 7602$k+1$, the function returns $\kbd{MASK} + 2^{k+1}$, so the highest bit of 7603the mask indicates the length of the sequence, and the following ones give 7604an algorithm to obtain the accuracies. This is much simpler than it sounds, 7605here is what it looks like in practice: 7606\bprog 7607 ulong mask = quadratic_prec_mask(n); 7608 long l = 1; 7609 while (mask > 1) { /* here, the result is known to accuracy l */ 7610 l = 2*l; if (mask & 1) l--; /* new accuracy l for the iteration */ 7611 mask >>= 1; /* pop low order bit */ 7612 /* ... lift to the new accuracy ... */ 7613 } 7614 /* we are done. At this point l = n */ 7615@eprog\noindent We just pop the bits in \kbd{mask} starting from the low 7616order bits, stop when \kbd{mask} is $1$ (that last bit corresponds to the 7617$2^{k+1}$ that we added to the mask proper). Note that there is nothing 7618specific to Hensel lifts in that function: it would work equally well for 7619an Archimedean Newton iteration. 7620 7621Note that in practice, we rather use an infinite loop, and insert an 7622\bprog 7623 if (mask == 1) break; 7624@eprog\noindent in the middle of the loop: the loop body usually includes 7625preparations for the next iterations (e.g. lifting Bezout coefficients 7626in a quadratic Hensel lift), which are costly and useless in the \emph{last} 7627iteration. 7628 7629\subsec{Conversions involving single precision objects} 7630 7631\subsubsec{To single precision} 7632 7633\fun{ulong}{Rg_to_Fl}{GEN z, ulong p}, \kbd{z} which can be mapped to 7634$\Z/p\Z$: a \typ{INT}, a \typ{INTMOD} whose modulus is divisible by $p$, 7635a \typ{FRAC} whose denominator is coprime to $p$, or a \typ{PADIC} with 7636underlying prime $\ell$ satisfying $p = \ell^n$ for some $n$ (less than the 7637accuracy of the input). Returns \kbd{lift(z * Mod(1,p))}, normalized, as an 7638\kbd{Fl}. 7639 7640\fun{ulong}{Rg_to_F2}{GEN z}, as \tet{Rg_to_Fl} for $p = 2$. 7641 7642\fun{ulong}{padic_to_Fl}{GEN x, ulong p} special case of \tet{Rg_to_Fl}, 7643for a $x$ a \typ{PADIC}. 7644 7645\fun{GEN}{RgX_to_F2x}{GEN x}, \kbd{x} a \typ{POL}, returns the 7646\kbd{F2x} obtained by applying \kbd{Rg\_to\_Fl} coefficientwise. 7647 7648\fun{GEN}{RgX_to_Flx}{GEN x, ulong p}, \kbd{x} a \typ{POL}, returns the 7649\kbd{Flx} obtained by applying \kbd{Rg\_to\_Fl} coefficientwise. 7650 7651\fun{GEN}{RgXV_to_FlxV}{GEN x, ulong p}, \kbd{x} a vector, returns the 7652\kbd{FlxV} obtained by applying \kbd{RgX\_to\_Flx} coefficientwise. 7653 7654\fun{GEN}{Rg_to_F2xq}{GEN z, GEN T}, \kbd{z} a \kbd{GEN} which can be 7655mapped to $\F_2[X]/(T)$: anything \kbd{Rg\_to\_Fl} can be applied to, 7656a \typ{POL} to which \kbd{RgX\_to\_F2x} can be applied to, a \typ{POLMOD} 7657whose modulus is divisible by $T$ (once mapped to a \kbd{F2x}), a suitable 7658\typ{RFRAC}. Returns \kbd{z} as an \kbd{F2xq}, normalized. 7659 7660\fun{GEN}{Rg_to_Flxq}{GEN z, GEN T, ulong p}, \kbd{z} a \kbd{GEN} which can be 7661mapped to $\F_p[X]/(T)$: anything \kbd{Rg\_to\_Fl} can be applied to, 7662a \typ{POL} to which \kbd{RgX\_to\_Flx} can be applied to, a \typ{POLMOD} 7663whose modulus is divisible by $T$ (once mapped to a \kbd{Flx}), a suitable 7664\typ{RFRAC}. Returns \kbd{z} as an \kbd{Flxq}, normalized. 7665 7666\fun{GEN}{RgX_to_FlxqX}{GEN z, GEN T, ulong p}, \kbd{z} a \kbd{GEN} which can be 7667mapped to $\F_p[x]/(T)[X]$: anything \kbd{Rg\_to\_Flxq} can be applied to, 7668a \typ{POL} to which \kbd{RgX\_to\_Flx} can be applied to, a \typ{POLMOD} 7669whose modulus is divisible by $T$ (once mapped to a \kbd{Flx}), a suitable 7670\typ{RFRAC}. Returns \kbd{z} as an \kbd{FlxqX}, normalized. 7671 7672\fun{GEN}{ZX_to_Flx}{GEN x, ulong p} reduce \kbd{ZX}~\kbd{x} modulo \kbd{p} 7673(yielding an \kbd{Flx}). Faster than \kbd{RgX\_to\_Flx}. 7674 7675\fun{GEN}{ZV_to_Flv}{GEN x, ulong p} reduce \kbd{ZV}~\kbd{x} modulo \kbd{p} 7676(yielding an \kbd{Flv}). 7677 7678\fun{GEN}{ZXV_to_FlxV}{GEN v, ulong p}, as \kbd{ZX\_to\_Flx}, repeatedly 7679called on the vector's coefficients. 7680 7681\fun{GEN}{ZXT_to_FlxT}{GEN v, ulong p}, as \kbd{ZX\_to\_Flx}, repeatedly 7682called on the tree leaves. 7683 7684\fun{GEN}{ZXX_to_FlxX}{GEN B, ulong p, long v}, as \kbd{ZX\_to\_Flx}, 7685repeatedly called on the polynomial's coefficients. 7686 7687\fun{GEN}{zxX_to_FlxX}{GEN z, ulong p} as \kbd{zx\_to\_Flx}, 7688repeatedly called on the polynomial's coefficients. 7689 7690\fun{GEN}{ZXXV_to_FlxXV}{GEN V, ulong p, long v}, as \kbd{ZXX\_to\_FlxX}, 7691repeatedly called on the vector's coefficients. 7692 7693\fun{GEN}{ZXXT_to_FlxXT}{GEN V, ulong p, long v}, as \kbd{ZXX\_to\_FlxX}, 7694repeatedly called on the tree leaves. 7695 7696\fun{GEN}{RgV_to_Flv}{GEN x, ulong p} reduce the \typ{VEC}/\typ{COL} 7697$x$ modulo $p$, yielding a \typ{VECSMALL}. 7698 7699\fun{GEN}{RgM_to_Flm}{GEN x, ulong p} reduce the \typ{MAT} $x$ modulo $p$. 7700 7701\fun{GEN}{ZM_to_Flm}{GEN x, ulong p} reduce \kbd{ZM}~$x$ modulo $p$ 7702(yielding an \kbd{Flm}). 7703 7704\fun{GEN}{ZV_to_zv}{GEN z}, converts coefficients using \kbd{itos} 7705 7706\fun{GEN}{ZV_to_nv}{GEN z}, converts coefficients using \kbd{itou} 7707 7708\fun{GEN}{ZM_to_zm}{GEN z}, converts coefficients using \kbd{itos} 7709 7710\fun{GEN}{FqC_to_FlxC}{GEN x, GEN T, GEN p}, converts coefficients in \kbd{Fq} 7711to coefficient in Flx, result being a column vector. 7712 7713\fun{GEN}{FqV_to_FlxV}{GEN x, GEN T, GEN p}, converts coefficients in \kbd{Fq} 7714to coefficient in Flx, result being a line vector. 7715 7716 7717\fun{GEN}{FqM_to_FlxM}{GEN x, GEN T, GEN p}, converts coefficients in \kbd{Fq} 7718to coefficient in Flx. 7719 7720\subsubsec{From single precision} 7721 7722\fun{GEN}{Flx_to_ZX}{GEN z}, converts to \kbd{ZX} (\typ{POL} of nonnegative 7723\typ{INT}s in this case) 7724 7725\fun{GEN}{Flx_to_FlxX}{GEN z}, converts to \kbd{FlxX} (\typ{POL} of constant 7726\kbd{Flx} in this case). 7727 7728\fun{GEN}{Flx_to_ZX_inplace}{GEN z}, same as \kbd{Flx\_to\_ZX}, in place 7729(\kbd{z} is destroyed). 7730 7731\fun{GEN}{FlxX_to_ZXX}{GEN B}, converts an \kbd{FlxX} to a polynomial with 7732\kbd{ZX} or \typ{INT} coefficients (repeated calls to \kbd{Flx\_to\_ZX}). 7733 7734\fun{GEN}{FlxXC_to_ZXXC}{GEN B}, converts an \kbd{FlxXC} to a \typ{COL} with 7735\kbd{ZXX} coefficients (repeated calls to \kbd{FlxX\_to\_ZXX}). 7736 7737\fun{GEN}{FlxXM_to_ZXXM}{GEN B}, converts an \kbd{FlxXM} to a \typ{MAT} with 7738\kbd{ZXX} coefficients (repeated calls to \kbd{FlxX\_to\_ZXX}). 7739 7740\fun{GEN}{FlxC_to_ZXC}{GEN x}, converts a vector of \kbd{Flx} to a column 7741vector of polynomials with \typ{INT} coefficients (repeated calls to 7742\kbd{Flx\_to\_ZX}). 7743 7744\fun{GEN}{FlxV_to_ZXV}{GEN x}, as above but return a \typ{VEC}. 7745 7746\fun{void}{F2xV_to_FlxV_inplace}{GEN v} v is destroyed. 7747 7748\fun{void}{F2xV_to_ZXV_inplace}{GEN v} v is destroyed. 7749 7750\fun{void}{FlxV_to_ZXV_inplace}{GEN v} v is destroyed. 7751 7752\fun{GEN}{FlxM_to_ZXM}{GEN z}, converts a matrix of \kbd{Flx} to a matrix of 7753polynomials with \typ{INT} coefficients (repeated calls to \kbd{Flx\_to\_ZX}). 7754 7755\fun{GEN}{zx_to_ZX}{GEN z}, as \kbd{Flx\_to\_ZX}, without assuming 7756the coefficients to be nonnegative. 7757 7758\fun{GEN}{zx_to_Flx}{GEN z, ulong p} as \kbd{Flx\_red} without assuming 7759the coefficients to be nonnegative. 7760 7761\fun{GEN}{Flc_to_ZC}{GEN z}, converts to \kbd{ZC} (\typ{COL} of nonnegative 7762\typ{INT}s in this case) 7763 7764\fun{GEN}{Flc_to_ZC_inplace}{GEN z}, same as \kbd{Flc\_to\_ZC}, in place 7765(\kbd{z} is destroyed). 7766 7767\fun{GEN}{Flv_to_ZV}{GEN z}, converts to \kbd{ZV} (\typ{VEC} of nonnegative 7768\typ{INT}s in this case) 7769 7770\fun{GEN}{Flm_to_ZM}{GEN z}, converts to \kbd{ZM} (\typ{MAT} with 7771nonnegative \typ{INT}s coefficients in this case) 7772 7773\fun{GEN}{Flm_to_ZM_inplace}{GEN z}, same as \kbd{Flm\_to\_ZM}, in place 7774(\kbd{z} is destroyed). 7775 7776\fun{GEN}{zc_to_ZC}{GEN z} as \kbd{Flc\_to\_ZC}, without assuming 7777coefficients are nonnegative. 7778 7779\fun{GEN}{zv_to_ZV}{GEN z} as \kbd{Flv\_to\_ZV}, without assuming 7780coefficients are nonnegative. 7781 7782\fun{GEN}{zm_to_ZM}{GEN z} as \kbd{Flm\_to\_ZM}, without assuming 7783coefficients are nonnegative. 7784 7785\fun{GEN}{zv_to_Flv}{GEN z, ulong p} 7786 7787\fun{GEN}{zm_to_Flm}{GEN z, ulong p} 7788 7789\subsubsec{Mixed precision linear algebra} Assumes dimensions are compatible. 7790Multiply a multiprecision object by a single-precision one. 7791 7792\fun{GEN}{RgM_zc_mul}{GEN x, GEN y} 7793 7794\fun{GEN}{RgMrow_zc_mul}{GEN x, GEN y, long i} 7795 7796\fun{GEN}{RgM_zm_mul}{GEN x, GEN y} 7797 7798\fun{GEN}{RgV_zc_mul}{GEN x, GEN y} 7799 7800\fun{GEN}{RgV_zm_mul}{GEN x, GEN y} 7801 7802\fun{GEN}{ZM_zc_mul}{GEN x, GEN y} 7803 7804\fun{GEN}{zv_ZM_mul}{GEN x, GEN y} 7805 7806\fun{GEN}{ZV_zc_mul}{GEN x, GEN y} 7807 7808\fun{GEN}{ZM_zm_mul}{GEN x, GEN y} 7809 7810\fun{GEN}{ZC_z_mul}{GEN x, long y} 7811 7812\fun{GEN}{ZM_nm_mul}{GEN x, GEN y} the entries of $y$ are \kbd{ulong}s. 7813 7814\fun{GEN}{nm_Z_mul}{GEN y, GEN c} the entries of $y$ are \kbd{ulong}s. 7815 7816\subsubsec{Miscellaneous involving Fl} 7817 7818\fun{GEN}{Fl_to_Flx}{ulong x, long evx} converts a \kbd{unsigned long} to a 7819scalar \kbd{Flx}. Assume that \kbd{evx = evalvarn(vx)} for some variable 7820number \kbd{vx}. 7821 7822\fun{GEN}{Z_to_Flx}{GEN x, ulong p, long sv} converts a \typ{INT} to a scalar 7823\kbd{Flx} polynomial. Assume that \kbd{sv = evalvarn(v)} for some variable 7824number \kbd{v}. 7825 7826\fun{GEN}{Flx_to_Flv}{GEN x, long n} converts from \kbd{Flx} to \kbd{Flv} 7827with \kbd{n} components (assumed larger than the number of coefficients of 7828\kbd{x}). 7829 7830\fun{GEN}{zx_to_zv}{GEN x, long n} as \kbd{Flx\_to\_Flv}. 7831 7832\fun{GEN}{Flv_to_Flx}{GEN x, long sv} converts from vector (coefficient 7833array) to (normalized) polynomial in variable $v$. 7834 7835\fun{GEN}{zv_to_zx}{GEN x, long n} as \kbd{Flv\_to\_Flx}. 7836 7837\fun{GEN}{Flm_to_FlxV}{GEN x, long sv} converts the columns of 7838\kbd{Flm}~\kbd{x} to an array of \kbd{Flx} in the variable $v$ 7839(repeated calls to \kbd{Flv\_to\_Flx}). 7840 7841\fun{GEN}{zm_to_zxV}{GEN x, long n} as \kbd{Flm\_to\_FlxV}. 7842 7843\fun{GEN}{Flm_to_FlxX}{GEN x, long sw, long sv} same as 7844\kbd{Flm\_to\_FlxV(x,sv)} but returns the result as a (normalized) polynomial 7845in variable $w$. 7846 7847\fun{GEN}{FlxV_to_Flm}{GEN v, long n} reverse \kbd{Flm\_to\_FlxV}, to obtain 7848an \kbd{Flm} with \kbd{n} rows (repeated calls to \kbd{Flx\_to\_Flv}). 7849 7850\fun{GEN}{FlxX_to_Flx}{GEN P} Let $P(x,X)$ be a \kbd{FlxX}, return $P(0,X)$ 7851as a \kbd{Flx}. 7852 7853\fun{GEN}{FlxX_to_Flm}{GEN v, long n} reverse \kbd{Flm\_to\_FlxX}, to obtain 7854an \kbd{Flm} with \kbd{n} rows (repeated calls to \kbd{Flx\_to\_Flv}). 7855 7856\fun{GEN}{FlxX_to_FlxC}{GEN B, long n, long sv} see \kbd{RgX\_to\_RgV}. 7857The coefficients of \kbd{B} are assumed to be in the variable $v$. 7858 7859\fun{GEN}{FlxV_to_FlxX}{GEN x, long v} see \kbd{RgV\_to\_RgX}. 7860 7861\fun{GEN}{FlxXV_to_FlxM}{GEN V, long n, long sv} see \kbd{RgXV\_to\_RgM}. 7862The coefficients of \kbd{V[i]} are assumed to be in the variable $v$. 7863 7864\fun{GEN}{Fly_to_FlxY}{GEN a, long sv} convert coefficients of \kbd{a} to 7865constant \kbd{Flx} in variable $v$. 7866 7867\subsubsec{Miscellaneous involving \kbd{F2x}} 7868 7869\fun{GEN}{F2x_to_F2v}{GEN x, long n} converts from \kbd{F2x} to \kbd{F2v} 7870with \kbd{n} components (assumed larger than the number of coefficients of 7871\kbd{x}). 7872 7873\fun{GEN}{F2xC_to_ZXC}{GEN x}, converts a vector of \kbd{F2x} to a column 7874vector of polynomials with \typ{INT} coefficients (repeated calls to 7875\kbd{F2x\_to\_ZX}). 7876 7877\fun{GEN}{F2xC_to_FlxC}{GEN x} 7878 7879\fun{GEN}{FlxC_to_F2xC}{GEN x} 7880 7881\fun{GEN}{F2xV_to_F2m}{GEN v, long n} \kbd{F2x\_to\_F2v} to each polynomial 7882to get an \kbd{F2m} with \kbd{n} rows. 7883 7884\section{Higher arithmetic over $\Z$: primes, factorization} 7885 7886\subsec{Pure powers} 7887 7888\fun{long}{Z_issquare}{GEN n} returns $1$ if the \typ{INT} $n$ is 7889a square, and $0$ otherwise. This is tested first modulo small prime 7890powers, then \kbd{sqrtremi} is called. 7891 7892\fun{long}{Z_issquareall}{GEN n, GEN *sqrtn} as \kbd{Z\_issquare}. If 7893$n$ is indeed a square, set \kbd{sqrtn} to its integer square root. 7894Uses a fast congruence test mod $64\times 63\times 65\times 11$ before 7895computing an integer square root. 7896 7897\fun{long}{Z_ispow2}{GEN x} returns $1$ if the \typ{INT} $x$ is a power of 7898$2$, and $0$ otherwise. 7899 7900\fun{long}{uissquare}{ulong n} as \kbd{Z\_issquare}, 7901for an \kbd{ulong} operand \kbd{n}. 7902 7903\fun{long}{uissquareall}{ulong n, ulong *sqrtn} as \kbd{Z\_issquareall}, 7904for an \kbd{ulong} operand \kbd{n}. 7905 7906\fun{ulong}{usqrt}{ulong a} returns the floor of the square root of $a$. 7907 7908\fun{ulong}{usqrtn}{ulong a, ulong n} returns the floor of the $n$-th root 7909of $a$. 7910 7911\fun{long}{Z_ispower}{GEN x, ulong k} returns $1$ if the \typ{INT} $n$ is a 7912$k$-th power, and $0$ otherwise; assume that $k > 1$. 7913 7914\fun{long}{Z_ispowerall}{GEN x, ulong k, GEN *pt} as \kbd{Z\_ispower}. If 7915$n$ is indeed a $k$-th power, set \kbd{*pt} to its integer $k$-th root. 7916 7917\fun{long}{Z_isanypower}{GEN x, GEN *ptn} returns the maximal $k\geq 2$ such 7918that the \typ{INT} $x = n^k$ is a perfect power, or $0$ if no such $k$ exist; 7919in particular \kbd{ispower(1)}, \kbd{ispower(0)}, \kbd{ispower(-1)} all 7920return 0. If the return value $k$ is not $0$ (so that $x = n^k$) and 7921\kbd{ptn} is not \kbd{NULL}, set \kbd{*ptn} to $n$. 7922 7923The following low-level functions are called by \tet{Z_isanypower} but can 7924be directly useful: 7925 7926\fun{int}{is_357_power}{GEN x, GEN *ptn, ulong *pmask} tests whether the 7927integer $x > 0$ is a $3$-rd, $5$-th or $7$-th power. The bits of \kbd{*mask} 7928initially indicate which test is to be performed; 7929bit $0$: $3$-rd, 7930bit $1$: $5$-th, 7931bit $2$: $7$-th (e.g.~$\kbd{*pmask} = 7$ performs all tests). They are 7932updated during the call: if the ``$i$-th power'' bit is set to $0$ 7933then $x$ is not a $k$-th power. The function returns $0$ 7934(not a 7935$3$-rd, 7936$5$-th or 7937$7$-th power), 7938$3$ 7939($3$-rd power, 7940not a $5$-th or 7941$7$-th power), 7942$5$ 7943($5$-th power, 7944not a $7$-th power), 7945or $7$ 7946($7$-th power); if an $i$-th power bit is initially set to $0$, we take it 7947at face value and assume $x$ is not an $i$-th power without performing any 7948test. If the return value $k$ is nonzero, set \kbd{*ptn} to $n$ such that $x 7949= n^k$. 7950 7951\fun{int}{is_pth_power}{GEN x, GEN *ptn, forprime_t *T, ulong cutoff} 7952let $x > 0$ be an integer, $\kbd{cutoff} > 0$ and $T$ be an iterator over 7953primes $\geq 11$, we look for the smallest prime $p$ such that $x = n^p$ 7954(advancing $T$ as we go along). The $11$ is due to the fact that 7955\tet{is_357_power} and \kbd{issquare} are faster than the generic version for 7956$p < 11$. 7957 7958Fail and return $0$ when the existence of $p$ would imply $2^{\kbd{cutoff}} > 7959x^{1/p}$, meaning that a possible $n$ is so small that it should have been 7960found by trial division; for maximal speed, you should start by a round of 7961trial division, but the cut-off may also be set to $1$ for a rigorous result 7962without any trial division. 7963 7964Otherwise returns the smallest suitable prime power $p^i$ and set \kbd{*ptn} 7965to the $p^i$-th root of $x$ (which is now not a $p$-th power). We may 7966immediately recall the function with the same parameters after setting $x = 7967\kbd{*ptn}$: it will start at the next prime. 7968 7969\subsec{Factorization} 7970 7971\fun{GEN}{Z_factor}{GEN n} factors the \typ{INT} \kbd{n}. The ``primes'' 7972in the factorization are actually strong pseudoprimes. 7973 7974\fun{GEN}{absZ_factor}{GEN n} returns \kbd{Z\_factor(absi(n))}. 7975 7976\fun{long}{Z_issmooth}{GEN n, ulong lim} returns $1$ if all the 7977prime factors of the \typ{INT} $n$ are less or equal to $lim$. 7978 7979\fun{GEN}{Z_issmooth_fact}{GEN n, ulong lim} returns \kbd{NULL} if a prime 7980factor of the \typ{INT} $n$ is $> lim$, and returns the factorization 7981of $n$ otherwise, as a \typ{MAT} with \typ{VECSMALL} columns (word-size 7982primes and exponents). Neither memory-clean nor suitable for 7983\kbd{gerepileupto}. 7984 7985\fun{GEN}{Z_factor_until}{GEN n, GEN lim} as \kbd{Z\_factor}, but stop the 7986factorization process as soon as the unfactored part is smaller than \kbd{lim}. 7987The resulting factorization matrix only contains the factors found. No other 7988assumptions can be made on the remaining factors. 7989 7990\fun{GEN}{Z_factor_limit}{GEN n, ulong lim} trial divide $n$ by all primes $p 7991< \kbd{lim}$ in the precomputed list of prime numbers and the \kbd{addprimes} 7992prime table. Return the corresponding factorization matrix. The first column 7993of the factorization matrix may contain a single composite, which may 7994or may not be the last entry in presence of a prime table. 7995 7996If $\kbd{lim} = 0$, the effect is the same as setting $\kbd{lim} = 7997\kbd{maxprime()} + 1$: use all precomputed primes. 7998 7999\fun{GEN}{absZ_factor_limit}{GEN n, ulong all} returns 8000\kbd{Z\_factor\_limit(absi(n))}. 8001 8002\fun{GEN}{absZ_factor_limit_strict}{GEN n, ulong all, GEN *pU} analogous to 8003\tet{absZ_factor_limit}, with a better interface: trial divide $n$ by all 8004primes $p < \kbd{lim}$ in the precomputed list of prime numbers and the 8005\kbd{addprimes} prime table. Return the corresponding factorization matrix. 8006In this case, a composite cofactor is \emph{not} included. 8007 8008If \kbd{pU} is not \kbd{NULL}, set it to the cofactor, which is either 8009\kbd{NULL} (no cofactor) or $[q,k]$, where $k > 0$, $q$ is a composite 8010whose prime divisors are greater than \kbd{all}, not a pure power 8011and $q^k$ is the largest power of $q$ dividing $n$. 8012 8013\fun{GEN}{boundfact}{GEN x, ulong lim} as \tet{Z_factor_limit}, applying to 8014\typ{INT} or \typ{FRAC} inputs. 8015 8016\fun{GEN}{Z_smoothen}{GEN n, GEN L, GEN *pP, GEN *pE} given a \typ{VECSMALL} 8017$L$ containing a list of small primes and a \typ{INT} $n$, trial divide 8018$n$ by the elements of $L$ and return the cofactor. Return \kbd{NULL} if the 8019cofactor is $\pm 1$. \kbd{*P} and \kbd{*E} contain the list of prime divisors 8020found and their exponents, as \typ{VECSMALL}s. Neither memory-clean, nor 8021suitable for \tet{gerepileupto}. 8022 8023\fun{GEN}{Z_factor_listP}{GEN N, GEN L} given a \typ{INT} $N$, a vector or 8024primes $L$ containing all prime divisors of $N$ (and possibly others). Return 8025\kbd{factor(N)}. Neither memory-clean, nor suitable for \tet{gerepileupto}. 8026 8027\fun{GEN}{factor_pn_1}{GEN p, ulong n} returns the factorization of $p^n-1$, 8028where $p$ is prime and $n$ is a positive integer. 8029 8030\fun{GEN}{factor_pn_1_limit}{GEN p, ulong n, ulong B} returns a partial 8031factorization of $p^n-1$, where $p$ is prime and $n$ is a positive integer. 8032Don't actively search for prime divisors $p > B$, but we may find still find 8033some due to Aurifeuillian factorizations. Any entry $> B^2$ in the output 8034factorization matrix is \emph{a priori} not a prime (but may well be). 8035 8036\fun{GEN}{factor_Aurifeuille_prime}{GEN p, long n} an Aurifeuillian factor 8037of $\phi_n(p)$, assuming $p$ prime and an Aurifeuillian factor exists 8038($p \zeta_n$ is a square in $\Q(\zeta_n)$). 8039 8040\fun{GEN}{factor_Aurifeuille}{GEN a, long d} an Aurifeuillian factor of 8041$\phi_n(a)$, assuming $a$ is a nonzero integer and $n > 2$. Returns $1$ 8042if no Aurifeuillian factor exists. 8043 8044\fun{GEN}{odd_prime_divisors}{GEN a} \typ{VEC} of all prime divisors of the 8045\typ{INT} $a$. 8046 8047\fun{GEN}{factoru}{ulong n}, returns the factorization of $n$. The result 8048is a $2$-component vector $[P,E]$, where $P$ and $E$ are \typ{VECSMALL} 8049containing the prime divisors of $n$, and the $v_p(n)$. 8050 8051\fun{GEN}{factoru_pow}{ulong n}, returns the factorization of $n$. The result 8052is a $3$-component vector $[P,E,C]$, where $P$, $E$ and $C$ are 8053\typ{VECSMALL} containing the prime divisors of $n$, the $v_p(n)$ 8054and the $p^{v_p(n)}$. 8055 8056\fun{GEN}{vecfactoru}{ulong a, ulong b}, returns a \typ{VEC} $v$ containing 8057the factorizations (\tet{factoru} format) of $a,\dots, b$; assume that $b 8058\geq a > 0$. Uses a sieve with primes up to $\sqrt{b}$. For all 8059$c$, $a \leq c \leq b$, the factorization of $c$ is given in $v[c-a+1]$. 8060 8061\fun{GEN}{vecfactoroddu}{ulong a, ulong b}, returns a \typ{VEC} $v$ containing 8062the factorizations (\tet{factoru} format) of odd integers in $a,\dots, b$; 8063assume that $b \geq a > 0$ are odd. Uses a sieve with primes up to 8064$\sqrt{b}$. For all odd $c$, $a \leq c \leq b$, the factorization of $c$ is 8065given in in $v[(c-a)/2 + 1]$. 8066 8067\fun{GEN}{vecfactoru_i}{ulong a, ulong b}, private version of 8068\kbd{vecfactoru}, not memory clean. 8069 8070\fun{GEN}{vecfactoroddu_i}{ulong a, ulong b}, private version of 8071\kbd{vecfactoroddu}, not memory clean. 8072 8073\fun{GEN}{vecfactorsquarefreeu}{ulong a, ulong b} return a \typ{VEC} $v$ 8074containing the prime divisors of squarefree integers in $a,\dots,b$; assume 8075that $a \leq b$. Uses a sieve with primes up to $\sqrt{b}$. 8076For all squarefree $c$, $a\leq c\leq b$, the prime divisors of $c$ (as a 8077\typ{VECSMALL}) are given in $v[c-a+1]$, and the other entries are 8078\kbd{NULL}. Note that because of these \kbd{NULL} markers, $v$ is not a valid 8079\kbd{GEN}, it is not memory clean and cannot be used in garbage collection 8080routines. 8081 8082\fun{GEN}{vecfactorsquarefreeu_coprime}{ulong a, ulong b, GEN P} 8083given a \emph{sorted} \typ{VECSMALL} of primes $P$, return a \typ{VEC} $v$ 8084containing the prime divisors of squarefree integers in $a,\dots,b$ coprime to 8085the elements of $P$; assume that $a \leq b$. Uses a sieve with primes up to 8086$\sqrt{b}$. For all squarefree $c$, $a\leq c\leq b$, the prime divisors of $c$ 8087(as a \typ{VECSMALL}) are given in $v[c-a+1]$, and the other entries are 8088\kbd{NULL}. Note that because of these \kbd{NULL} markers, $v$ is not a valid 8089\kbd{GEN}, it is not memory clean and cannot be used in garbage collection 8090routines. 8091 8092\fun{GEN}{vecsquarefreeu}{ulong a, ulong b} return a \typ{VECSMALL} $v$ 8093containing the squarefree integers in $a,\dots,b$. Assume that 8094$a\leq b$. Uses a sieve with primes up to $\sqrt{b}$. 8095 8096\fun{ulong}{tridiv_bound}{GEN n} returns the trial division bound used by 8097\tet{Z_factor}$(n)$. 8098 8099\fun{GEN}{Z_pollardbrent}{GEN N, long n, long seed} try to factor 8100\typ{INT} $N$ using $n\geq 1$ rounds of Pollard iterations; \var{seed} is an 8101integer whose value (mod $8$) selects the quadratic polynomial use to 8102generate Pollard's (pseudo)random walk. Returns \kbd{NULL} on failure, else a 8103vector of 2 (possibly 3) integers whose product is $N$. 8104 8105\fun{GEN}{Z_ECM}{GEN N, long n, long seed, ulong B1} try to 8106factor \typ{INT} $N$ using $n\geq 1$ rounds of ECM iterations (on $8$ to $64$ 8107curves simultaneously, depending on the size of $N$); \var{seed} is an 8108integer whose value selects the curves to be used: increase it by $64n$ to 8109make sure that a subsequent call with a factor of $N$ uses a disjoint set of 8110curves. 8111Finally $B_1 > 7$ determines the computations performed on the 8112curves: we compute $[k]P$ for some point in $E(\Z/N\Z)$ and $k = q \prod 8113p^{e_p}$ where $p^{e_p} \leq B_1$ and $q \leq B_2 := 110 B_1$; a higher value 8114of $B_1$ means higher chances of hitting a factor and more time spent. 8115The computation is deterministic for a given set of parameters. Returns 8116\kbd{NULL} on failure, else a nontrivial factor or \kbd{N}. 8117 8118\fun{GEN}{Q_factor}{GEN x} as \tet{Z_factor}, where $x$ is a \typ{INT} or 8119a \typ{FRAC}. 8120 8121\fun{GEN}{Q_factor_limit}{GEN x, ulong lim} as \tet{Z_factor_limit}, where 8122$x$ is a \typ{INT} or a \typ{FRAC}. 8123 8124\subsec{Coprime factorization} 8125 8126Given $a$ and $b$ two nonzero integers, let \teb{ppi}$(a,b)$, \teb{ppo}$(a,b)$, 8127\teb{ppg}$(a,b)$, \teb{pple}$(a,b)$ (powers in $a$ of primes inside $b$, 8128outside $b$, greater than those in $b$, less than or equal to those in $b$) be 8129the integers defined by 8130 8131\item $v_p(\text{ppi}) = v_p(a) [v_p(b) > 0]$, 8132 8133\item $v_p(\text{ppo}) = v_p(a) [v_p(b) = 0]$, 8134 8135\item $v_p(\text{ppg}) = v_p(a) [v_p(a) > v_p(b)]$, 8136 8137\item $v_p(\text{pple}) = v_p(a) [v_p(a) \leq v_p(b)]$. 8138 8139\fun{GEN}{Z_ppo}{GEN a, GEN b} returns $\text{ppo}(a,b)$; shallow function. 8140 8141\fun{ulong}{u_ppo}{ulong a, ulong b} returns $\text{ppo}(a,b)$. 8142 8143\fun{GEN}{Z_ppgle}{GEN a, GEN b} returns $[\text{ppg}(a,b), \text{pple}(a,b)]$; 8144shallow function. 8145 8146\fun{GEN}{Z_ppio}{GEN a, GEN b} returns 8147$[\gcd(a,b), \text{ppi}(a,b), \text{ppo}(a,b)]$; shallow function. 8148 8149\fun{GEN}{Z_cba}{GEN a, GEN b} fast natural coprime base algorithm. Returns a 8150vector of coprime divisors of $a$ and $b$ such that both $a$ and $b$ can 8151be multiplicatively generated from this set. Perfect powers are not removed, 8152use \tet{Z_isanypower} if needed; shallow function. 8153 8154\fun{GEN}{ZV_cba_extend}{GEN P, GEN b} extend a coprime basis $P$ by the 8155integer $b$, the result being a coprime basis for $P\cup \{b\}$. 8156Perfect powers are not removed; shallow function. 8157 8158\fun{GEN}{ZV_cba}{GEN v} given a vector of nonzero integers $v$, return 8159a coprime basis for $v$. Perfect powers are not removed; shallow function. 8160 8161\subsec{Checks attached to arithmetic functions} 8162 8163Arithmetic functions accept arguments of the following kind: a plain positive 8164integer $N$ (\typ{INT}), the factorization \var{fa} of a positive integer (a 8165\typ{MAT} with two columns containing respectively primes and exponents), or 8166a vector $[N,\var{fa}]$. A few functions accept nonzero 8167integers (e.g.~\tet{omega}), and some others arbitrary integers 8168(e.g.~\tet{factorint}, \dots). 8169 8170\fun{int}{is_Z_factorpos}{GEN f} returns $1$ if $f$ looks like the 8171factorization of a positive integer, and $0$ otherwise. Useful for sanity 8172checks but not 100\% foolproof. Specifically, this routine checks that $f$ is 8173a two-column matrix all of whose entries are positive integers. It does 8174\emph{not} check that entries in the first column (``primes'') are prime, 8175or even pairwise coprime, nor that they are stricly increasing. 8176 8177\fun{int}{is_Z_factornon0}{GEN f} returns $1$ if $f$ looks like the 8178factorization of a nonzero integer, and $0$ otherwise. Useful for sanity 8179checks but not 100\% foolproof, analogous to \tet{is_Z_factorpos}. (Entries 8180in the first column need only be nonzero integers.) 8181 8182\fun{int}{is_Z_factor}{GEN f} returns $1$ if $f$ looks like the 8183factorization of an integer, and $0$ otherwise. Useful for sanity 8184checks but not 100\% foolproof. Specifically, this routine checks that $f$ is 8185a two-column matrix all of whose entries are integers. Entries in the second 8186column (``exponents'') are all positive. Either it encodes the 8187``factorization'' $0^e$, $e > 0$, or entries in the first column (``primes'') 8188are all nonzero. 8189 8190\fun{GEN}{clean_Z_factor}{GEN f} assuming $f$ is the factorization of an 8191integer $n$, return the factorization of $|n|$, i.e.~remove $-1$ from the 8192factorization. Shallow function. 8193 8194\fun{GEN}{fuse_Z_factor}{GEN f, GEN B} assuming $f$ is the 8195factorization of an integer $n$, return \kbd{boundfact(n, B)}, i.e. 8196return a factorization where all primary factors for $|p| \leq B$ 8197are preserved, and all others are ``fused'' into a single composite 8198integer; if that remainder is trivial, i.e.~equal to 1, it is of course 8199not included. Shallow function. 8200 8201In the following three routines, $f$ is the name of an arithmetic function, 8202and $n$ a supplied argument. They all raise exceptions if $n$ does not 8203correspond to an integer or an integer factorization of the expected shape. 8204 8205\fun{GEN}{check_arith_pos}{GEN n, const char *f} check whether $n$ 8206is attached to the factorization of a positive integer, and return 8207\kbd{NULL} (plain \typ{INT}) or a factorization extracted from $n$ otherwise. 8208May raise an \tet{e_DOMAIN} ($n \leq 0$) or an \tet{e_TYPE} exception (other 8209failures). 8210 8211\fun{GEN}{check_arith_non0}{GEN n, const char *f} check whether $n$ 8212is attached to the factorization of a nonzero integer, and return 8213\kbd{NULL} (plain \typ{INT}) or a factorization extracted from $n$ otherwise. 8214May raise an \tet{e_TYPE} exception. 8215 8216\fun{GEN}{check_arith_all}{GEN n, const char *f} 8217is attached to the factorization of an integer, and return \kbd{NULL} 8218(plain \typ{INT}) or a factorization extracted from $n$ otherwise. 8219 8220\subsec{Incremental integer factorization} 8221 8222Routines attached to the dynamic factorization of an integer $n$, iterating 8223over successive prime divisors. This is useful to implement high-level 8224routines allowed to take shortcuts given enough partial information: e.g. 8225\kbd{moebius}$(n)$ can be trivially computed if we hit $p$ such that $p^2 8226\mid n$. For efficiency, trial division by small primes should have already 8227taken place. In any case, the functions below assume that no prime $< 2^{14}$ 8228divides $n$. 8229 8230\fun{GEN}{ifac_start}{GEN n, int moebius} schedules a new factorization 8231attempt for the integer $n$. If \kbd{moebius} is nonzero, the factorization 8232will be aborted as soon as a repeated factor is detected (Moebius mode). 8233The function assumes that $n > 1$ is a \emph{composite} \typ{INT} whose prime 8234divisors satisfy $p > 2^{14}$ \emph{and} that one can write to $n$ in place. 8235 8236This function stores data on the stack, no \kbd{gerepile} call should 8237delete this data until the factorization is complete. Returns \kbd{partial}, 8238a data structure recording the partial factorization state. 8239 8240\fun{int}{ifac_next}{GEN *partial, GEN *p, long *e} deletes a primary factor 8241$p^e$ from \kbd{partial} and sets \kbd{p} (prime) and \kbd{e} (exponent), and 8242normally returns $1$. Whatever remains in the \kbd{partial} structure is now 8243coprime to $p$. 8244 8245Returns $0$ if all primary factors have been used already, so we are done 8246with the factorization. In this case $p$ is set to \kbd{NULL}. If we ran in 8247Moebius mode and the factorization was in fact aborted, we have $e = 1$, 8248otherwise $e = 0$. 8249 8250\fun{int}{ifac_read}{GEN part, GEN *k, long *e} peeks at the next integer 8251to be factored in the list $k^e$, where $k$ is not necessarily prime 8252and can be a perfect power as well, but will be factored by the next call to 8253\tet{ifac_next}. You can remove this factorization from the schedule by 8254calling: 8255 8256\fun{void}{ifac_skip}{GEN part} removes the next scheduled factorization. 8257 8258\fun{int}{ifac_isprime}{GEN n} given $n$ whose prime divisors are $> 2^{14}$, 8259returns the decision the factoring engine would take about the compositeness 8260of $n$: $0$ if $n$ is a proven composite, and $1$ if we believe it to be 8261prime; more precisely, $n$ is a proven prime if \tet{factor_proven} is 8262set, and only a BPSW-pseudoprime otherwise. 8263 8264\subsec{Integer core, squarefree factorization} 8265 8266\fun{long}{Z_issquarefree}{GEN n} returns $1$ if the \typ{INT} \kbd{n} 8267is square-free, and $0$ otherwise. 8268 8269\fun{long}{Z_isfundamental}{GEN x} returns $1$ if the \typ{INT} \kbd{x} 8270is a fundamental discriminant, and $0$ otherwise. 8271 8272\fun{GEN}{core}{GEN n} unique squarefree integer $d$ dividing $n$ such that 8273$n/d$ is a square. The core of $0$ is defined to be $0$. 8274 8275\fun{GEN}{core2}{GEN n} return $[d,f]$ with $d$ squarefree and $n = df^2$. 8276 8277\fun{GEN}{corepartial}{GEN n, long lim} as \kbd{core}, using 8278\kbd{boundfact(n,lim)} to partially factor \kbd{n}. The result is not 8279necessarily squarefree, but $p^2 \mid n$ implies $p > \kbd{lim}$. 8280 8281\fun{GEN}{core2partial}{GEN n, long lim} as \kbd{core2}, using 8282\kbd{boundfact(n,lim)} to partially factor \kbd{n}. The resulting $d$ is not 8283necessarily squarefree, but $p^2 \mid n$ implies $p > \kbd{lim}$. 8284 8285\subsec{Primes, primality and compositeness tests} 8286 8287\subsubsec{Chebyshev's $\pi$ function, bounds} 8288 8289\fun{ulong}{uprimepi}{ulong n}, returns the number of primes $p\leq n$ 8290(Chebyshev's $\pi$ function). 8291 8292\fun{double}{primepi_upper_bound}{double x} return a quick upper bound for 8293$\pi(x)$, using Dusart bounds. 8294 8295\fun{GEN}{gprimepi_upper_bound}{GEN x} as \tet{primepi_upper_bound}, returns a 8296\typ{REAL}. 8297 8298\fun{double}{primepi_lower_bound}{double x} return a quick lower bound for 8299$\pi(x)$, using Dusart bounds. 8300 8301\fun{GEN}{gprimepi_lower_bound}{GEN x} as \tet{primepi_lower_bound}, returns 8302a \typ{REAL} or \kbd{gen\_0}. 8303 8304\subsubsec{Primes, primes in intervals} 8305 8306\fun{ulong}{unextprime}{ulong n}, returns the smallest prime $\geq n$. Return 8307$0$ if it cannot be represented as an \kbd{ulong} ($n$ bigger than $2^{64} - 830859$ or $2^{32} - 5$ depending on the word size). 8309 8310\fun{ulong}{uprecprime}{ulong n}, returns the largest prime $\leq n$. Return 8311$0$ if $n\leq 1$. 8312 8313\fun{ulong}{uprime}{long n} returns the $n$-th prime, assuming it fits in an 8314\kbd{ulong} (overflow error otherwise). 8315 8316\fun{GEN}{prime}{long n} same as \kbd{utoi(uprime(n))}. 8317 8318\fun{GEN}{primes_zv}{long m} returns the first $m$ primes, in a 8319\typ{VECSMALL}. 8320 8321\fun{GEN}{primes}{long m} return the first $m$ primes, as a \typ{VEC} of 8322\typ{INT}s. 8323 8324\fun{GEN}{primes_interval}{GEN a, GEN b} return the primes in the interval 8325$[a,b]$, as a \typ{VEC} of \typ{INT}s. 8326 8327\fun{GEN}{primes_interval_zv}{ulong a, ulong b} return the primes in the 8328interval $[a,b]$, as a \typ{VECSMALL} of \kbd{ulongs}s. 8329 8330\fun{GEN}{primes_upto_zv}{ulong b} return the primes in the interval $[2,b]$, 8331as a \typ{VECSMALL} of \kbd{ulongs}s. 8332 8333\subsubsec{Tests} 8334 8335\fun{int}{uisprime}{ulong p}, returns $1$ if \kbd{p} is a prime number and 8336$0$ otherwise. 8337 8338\fun{int}{uisprime_101}{ulong p}, assuming that $p$ has no divisor $\leq 8339101$, returns $1$ if \kbd{p} is a prime number and $0$ otherwise. 8340 8341\fun{int}{uisprime_661}{ulong p}, assuming that $p$ has no divisor $\leq 8342661$, returns $1$ if \kbd{p} is a prime number and $0$ otherwise. 8343 8344\fun{int}{isprime}{GEN n}, returns $1$ if the \typ{INT} \kbd{n} is a 8345(fully proven) prime number and $0$ otherwise. 8346 8347\fun{long}{isprimeAPRCL}{GEN n}, returns $1$ if the \typ{INT} \kbd{n} is a 8348prime number and $0$ otherwise, using only the APRCL test --- not even trial 8349division or compositeness tests. The workhorse \kbd{isprime} should be 8350faster on average, especially if nonprimes are included! 8351 8352\fun{long}{isprimeECPP}{GEN n}, returns $1$ if the \typ{INT} \kbd{n} is a 8353prime number and $0$ otherwise, using only the ECPP test. The workhorse 8354\kbd{isprime} should be faster on average. 8355 8356\fun{long}{BPSW_psp}{GEN n}, returns $1$ if the \typ{INT} \kbd{n} is a 8357Baillie-Pomerance-Selfridge-Wagstaff pseudoprime, and $0$ otherwise (proven 8358composite). 8359 8360\fun{int}{BPSW_isprime}{GEN x} assuming $x$ is a BPSW-pseudoprime, rigorously 8361prove its primality. The function \tet{isprime} is currently implemented 8362as 8363\bprog 8364 BPSW_psp(x) && BPSW_isprime(x) 8365@eprog 8366 8367\fun{long}{millerrabin}{GEN n, long k} performs $k$ strong Rabin-Miller 8368compositeness tests on the \typ{INT} $n$, using $k$ random bases. This 8369function also caches square roots of $-1$ that are encountered during the 8370successive tests and stops as soon as three distinct square roots have been 8371produced; we have in principle factored $n$ at this point, but 8372unfortunately, there is currently no way for the factoring machinery to 8373become aware of it. (It is highly implausible that hard to find factors 8374would be exhibited in this way, though.) This should be slower than 8375\tet{BPSW_psp} for $k\geq 4$ and we expect it to be less reliable. 8376 8377\fun{GEN}{ecpp}{GEN N} returns an ECPP certificate for \typ{INT} $N$; 8378underlies \kbd{primecert}. 8379 8380\fun{GEN}{ecppexport}{GEN cert, long flag} export a PARI ECPP certificate to 8381MAGMA or Primo format; underlies \kbd{primecertexport}. 8382 8383\fun{long}{ecppisvalid}{GEN cert} checks whether a PARI ECPP certificate 8384is valid; underlies \kbd{primecertisvalid}. 8385 8386\subsec{Iterators over primes} 8387 8388\fun{int}{forprime_init}{forprime_t *T, GEN a, GEN b} initialize an 8389iterator $T$ over primes in $[a,b]$; over primes $\geq a$ if $b = 8390\kbd{NULL}$. Return $0$ if the range is known to be empty from the start 8391(as if $b < a$ or $b < 0$), and return $1$ otherwise. Use \tet{forprime_next} 8392to iterate over the prime collection. 8393 8394\fun{int}{forprimestep_init}{forprime_t *T, GEN a, GEN b, GEN q} initialize an 8395iterator $T$ over primes in an arithmetic progression in $[a,b]$; 8396over primes $\geq a$ if $b = \kbd{NULL}$. The argument $q$ is either a 8397\typ{INT} ($p \equiv a \pmod{q}$) or a \typ{INTMOD} \kbd{Mod(c,N)} 8398and we restrict to that congruence class. Return $0$ if the range is known to 8399be empty from the start (as if $b < a$ or $b < 0$), and return $1$ otherwise. 8400Use \tet{forprime_next} to iterate over the prime collection. 8401 8402\fun{GEN}{forprime_next}{forprime_t *T} returns the next prime in the range, 8403assuming that $T$ was initialized by \tet{forprime_init}. 8404 8405\fun{int}{u_forprime_init}{forprime_t *T, ulong a, ulong b} 8406 8407\fun{ulong}{u_forprime_next}{forprime_t *T} 8408 8409\fun{void}{u_forprime_restrict}{forprime_t *T, ulong c} let $T$ an iterator 8410over primes initialized via \kbd{u\_forprime\_init(\&T, a, b)}, possibly 8411followed by a number of calls to \tet{u_forprime_next}, and $a \leq c \leq 8412b$. Restrict the range of primes considered to $[a,c]$. 8413 8414\fun{int}{u_forprime_arith_init}{forprime_t *T, ulong a,ulong b, ulong c,ulong q} initialize an iterator over primes in $[a,b]$, congruent to $c$ 8415modulo $q$. Subsequent calls to \tet{u_forprime_next} will only return primes 8416congruent to $c$ modulo $q$. Note that unless $(c,q) = 1$ there will be at 8417most one such prime. 8418 8419\section{Integral, rational and generic linear algebra} 8420\subsec{\kbd{ZC} / \kbd{ZV}, \kbd{ZM}} A \kbd{ZV} (resp.~a~\kbd{ZM}, 8421resp.~a~\kbd{ZX}) is a \typ{VEC} or \typ{COL} (resp.~\typ{MAT}, 8422resp.~\typ{POL}) with \typ{INT} coefficients. 8423 8424\subsubsec{\kbd{ZC} / \kbd{ZV}} 8425 8426\fun{void}{RgV_check_ZV}{GEN x, const char *s} Assuming \kbd{x} is a \typ{VEC} 8427or \typ{COL} raise an error if it is not a \kbd{ZV} ($s$ should point to the 8428name of the caller). 8429 8430\fun{int}{RgV_is_ZV}{GEN x} Assuming \kbd{x} is a \typ{VEC} 8431or \typ{COL} return $1$ if it is a \kbd{ZV}, and $0$ otherwise. 8432 8433\fun{int}{RgV_is_ZVpos}{GEN x} Assuming \kbd{x} is a \typ{VEC} 8434or \typ{COL} return $1$ if it is a \kbd{ZV} with positive entries, and $0$ 8435otherwise. 8436 8437\fun{int}{RgV_is_ZVnon0}{GEN x} Assuming \kbd{x} is a \typ{VEC} 8438or \typ{COL} return $1$ if it is a \kbd{ZV} with nonzero entries, and $0$ 8439otherwise. 8440 8441\fun{int}{RgV_is_QV}{GEN P} return 1 if the \kbd{RgV}~$P$ has only 8442\typ{INT} and \typ{FRAC} coefficients, and 0 otherwise. 8443 8444\fun{int}{RgV_is_arithprog}{GEN v, GEN *a, GEN *b} assuming $x$ is a \typ{VEC} 8445or \typ{COL} return $1$ if its entries follow an arithmetic progression 8446of the form $a + b*n$, $n = 0, 1, \dots$ and set $a$ and $b$. Else return $0$. 8447 8448\fun{int}{ZV_equal0}{GEN x} returns 1 if all entries of the \kbd{ZV} $x$ are 8449zero, and $0$ otherwise. 8450 8451\fun{int}{ZV_cmp}{GEN x, GEN y} compare two \kbd{ZV}, which we assume have 8452the same length (lexicographic order, comparing absolute values). 8453 8454\fun{int}{ZV_abscmp}{GEN x, GEN y} compare two \kbd{ZV}, which we assume have 8455the same length (lexicographic order). 8456 8457\fun{int}{ZV_equal}{GEN x, GEN y} returns $1$ if the two \kbd{ZV} are equal 8458and $0$ otherwise. A \typ{COL} and a \typ{VEC} with the same entries are 8459declared equal. 8460 8461\fun{GEN}{identity_ZV}{long n} return the \typ{VEC} $[1, 2, \dots, n]$. 8462 8463\fun{GEN}{ZC_add}{GEN x, GEN y} adds \kbd{x} and \kbd{y}. 8464 8465\fun{GEN}{ZC_sub}{GEN x, GEN y} subtracts \kbd{x} and \kbd{y}. 8466 8467\fun{GEN}{ZC_Z_add}{GEN x, GEN y} adds \kbd{y} to \kbd{x[1]}. 8468 8469\fun{GEN}{ZC_Z_sub}{GEN x, GEN y} subtracts \kbd{y} to \kbd{x[1]}. 8470 8471\fun{GEN}{Z_ZC_sub}{GEN a, GEN x} returns the vector $[a - x_1, 8472-x_2,\dots,-x_n]$. 8473 8474\fun{GEN}{ZC_copy}{GEN x} returns a (\typ{COL}) copy of \kbd{x}. 8475 8476\fun{GEN}{ZC_neg}{GEN x} returns $-\kbd{x}$ as a \typ{COL}. 8477 8478\fun{void}{ZV_neg_inplace}{GEN x} negates the \kbd{ZV} \kbd{x} in place, by 8479replacing each component by its opposite (the type of \kbd{x} remains the 8480same, \typ{COL} or \typ{COL}). If you want to save even more memory by 8481avoiding the implicit component copies, use \kbd{ZV\_togglesign}. 8482 8483\fun{void}{ZV_togglesign}{GEN x} negates \kbd{x} in place, by toggling the 8484sign of its integer components. Universal constants \kbd{gen\_1}, 8485\kbd{gen\_m1}, \kbd{gen\_2} and \kbd{gen\_m2} are handled specially and will 8486not be corrupted. (We use \tet{togglesign_safe}.) 8487 8488\fun{GEN}{ZC_Z_mul}{GEN x, GEN y} multiplies the \kbd{ZC} or \kbd{ZV}~\kbd{x} 8489(which can be a column or row vector) by the \typ{INT}~\kbd{y}, returning a 8490\kbd{ZC}. 8491 8492\fun{GEN}{ZC_Z_divexact}{GEN x, GEN y} returns $x/y$ assuming all divisions 8493are exact. 8494 8495\fun{GEN}{ZC_u_divexact}{GEN x, ulong y} returns $x/y$ assuming all divisions 8496are exact. 8497 8498\fun{GEN}{ZC_Z_div}{GEN x, GEN y} returns $x/y$, where the resulting vector 8499has rational entries. 8500 8501\fun{GEN}{ZV_dotproduct}{GEN x,GEN y} as \kbd{RgV\_dotproduct} assuming $x$ 8502and $y$ have \typ{INT} entries. 8503 8504\fun{GEN}{ZV_dotsquare}{GEN x} as \kbd{RgV\_dotsquare} assuming $x$ 8505has \typ{INT} entries. 8506 8507\fun{GEN}{ZC_lincomb}{GEN u, GEN v, GEN x, GEN y} returns $ux + vy$, where 8508$u$, $v$ are \typ{INT} and $x,y$ are \kbd{ZC} or \kbd{ZV}. Return a \kbd{ZC} 8509 8510\fun{void}{ZC_lincomb1_inplace}{GEN X, GEN Y, GEN v} sets $X\leftarrow X + 8511vY$, where $v$ is a \typ{INT} and $X,Y$ are \kbd{ZC} or \kbd{ZV}. (The result 8512has the type of $X$.) Memory efficient (e.g. no-op if $v = 0$), but not 8513gerepile-safe. 8514 8515\fun{void}{ZC_lincomb1_inplace_i}{GEN X, GEN Y, GEN v, long n} 8516variant of \tet{ZC_lincomb1_inplace}: only update $X[1], \dots, X[n]$, 8517assuming that $n < \kbd{lg}(X)$. 8518 8519\fun{GEN}{ZC_ZV_mul}{GEN x, GEN y, GEN p} multiplies the \kbd{ZC}~\kbd{x} 8520(seen as a column vector) by the \kbd{ZV}~\kbd{y} (seen as a row vector, 8521assumed to have compatible dimensions). 8522 8523\fun{GEN}{ZV_content}{GEN x} returns the GCD of all the components 8524of~\kbd{x}. 8525 8526\fun{GEN}{ZV_extgcd}{GEN A} given a vector of $n$ integers $A$, returns $[d, 8527U]$, where $d$ is the content of $A$ and $U$ is a matrix 8528in $\text{GL}_n(\Z)$ such that $AU = [D,0, \dots,0]$. 8529 8530\fun{GEN}{ZV_prod}{GEN x} returns the product of all the components 8531of~\kbd{x} ($1$ for the empty vector). 8532 8533\fun{GEN}{ZV_sum}{GEN x} returns the sum of all the components 8534of~\kbd{x} ($0$ for the empty vector). 8535 8536\fun{long}{ZV_max_lg}{GEN x} returns the effective length of the longest 8537entry in $x$. 8538 8539\fun{int}{ZV_dvd}{GEN x, GEN y} assuming $x$, $y$ are two \kbd{ZV}s of the same 8540length, return $1$ if $y[i]$ divides $x[i]$ for all $i$ and $0$ otherwise. 8541Error if one of the $y[i]$ is $0$. 8542 8543\fun{GEN}{ZV_sort}{GEN L} sort the \kbd{ZV} $L$. 8544Returns a vector with the same type as $L$. 8545 8546\fun{void}{ZV_sort_inplace}{GEN L} sort the \kbd{ZV} $L$, in place. 8547 8548\fun{GEN}{ZV_sort_uniq}{GEN L} sort the \kbd{ZV} $L$, removing duplicate 8549entries. Returns a vector with the same type as $L$. 8550 8551\fun{long}{ZV_search}{GEN L, GEN y} look for the \typ{INT} $y$ in the sorted 8552\kbd{ZV} $L$. Return an index $i$ such that $L[i] = y$, and $0$ otherwise. 8553 8554\fun{GEN}{ZV_indexsort}{GEN L} returns the permutation which, applied to the 8555\kbd{ZV} $L$, would sort the vector. The result is a \typ{VECSMALL}. 8556 8557\fun{GEN}{ZV_union_shallow}{GEN x, GEN y} given two \emph{sorted} ZV (as per 8558\tet{ZV_sort}, returns the union of $x$ and $y$. Shallow function. In case two 8559entries are equal in $x$ and $y$, include the one from $x$. 8560 8561\fun{GEN}{ZC_union_shallow}{GEN x, GEN y} as \kbd{ZV\_union\_shallow} but return 8562a \typ{COL}. 8563 8564\subsubsec{\kbd{ZM}} 8565 8566\fun{void}{RgM_check_ZM}{GEN A, const char *s} Assuming \kbd{x} is a \typ{MAT} 8567raise an error if it is not a \kbd{ZM} ($s$ should point to the name of the 8568caller). 8569 8570\fun{GEN}{RgM_rescale_to_int}{GEN x} given a matrix $x$ with real entries 8571(\typ{INT}, \typ{FRAC} or \typ{REAL}), return a \kbd{ZM} wich is very close 8572to $D x$ for some well-chosen integer $D$. More precisely, if the input is 8573exact, $D$ is the denominator of $x$; else it is a power of $2$ chosen 8574so that all inexact entries are correctly rounded to 1 ulp. 8575 8576\fun{GEN}{ZM_copy}{GEN x} returns a copy of \kbd{x}. 8577 8578\fun{int}{ZM_equal}{GEN A, GEN B} returns $1$ if the two \kbd{ZM} are equal 8579and $0$ otherwise. 8580 8581\fun{int}{ZM_equal0}{GEN A} returns $1$ if the \kbd{ZM} $A$ is identically 8582equal to $0$. 8583 8584\fun{GEN}{ZM_add}{GEN x, GEN y} returns $\kbd{x} + \kbd{y}$ (assumed to have 8585compatible dimensions). 8586 8587\fun{GEN}{ZM_sub}{GEN x, GEN y} returns $\kbd{x} - \kbd{y}$ (assumed to have 8588compatible dimensions). 8589 8590\fun{GEN}{ZM_neg}{GEN x} returns $-\kbd{x}$. 8591 8592\fun{void}{ZM_togglesign}{GEN x} negates \kbd{x} in place, by toggling the 8593sign of its integer components. Universal constants \kbd{gen\_1}, 8594\kbd{gen\_m1}, \kbd{gen\_2} and \kbd{gen\_m2} are handled specially and will 8595not be corrupted. (We use \tet{togglesign_safe}.) 8596 8597\fun{GEN}{ZM_mul}{GEN x, GEN y} multiplies \kbd{x} and \kbd{y} (assumed to 8598have compatible dimensions). 8599 8600\fun{GEN}{ZM_sqr}{GEN x} returns $x^2$, where $x$ is a square \kbd{ZM}. 8601 8602\fun{GEN}{ZM_Z_mul}{GEN x, GEN y} multiplies the \kbd{ZM}~\kbd{x} 8603by the \typ{INT}~\kbd{y}. 8604 8605\fun{GEN}{ZM_ZC_mul}{GEN x, GEN y} multiplies the \kbd{ZM}~\kbd{x} 8606by the \kbd{ZC}~\kbd{y} (seen as a column vector, assumed to have compatible 8607dimensions). 8608 8609\fun{GEN}{ZM_ZX_mul}{GEN x, GEN T} returns $x \times y$, where $y$ 8610is \kbd{RgX\_to\_RgC}$(T, \kbd{lg}(x)-1)$. 8611 8612\fun{GEN}{ZM_diag_mul}{GEN d, GEN m} given a vector $d$ with integer entries 8613and a \kbd{ZM} $m$ of compatible dimensions, return \kbd{diagonal(d) * m}. 8614 8615\fun{GEN}{ZM_mul_diag}{GEN m, GEN d} given a vector $d$ with integer entries 8616 and a \kbd{ZM} $m$ of compatible dimensions, return \kbd{m * diagonal(d)}. 8617 8618\fun{GEN}{ZM_multosym}{GEN x, GEN y} 8619 8620\fun{GEN}{ZM_transmultosym}{GEN x, GEN y} 8621 8622\fun{GEN}{ZM_transmul}{GEN x, GEN y} 8623 8624\fun{GEN}{ZMrow_ZC_mul}{GEN x, GEN y, long i} multiplies the $i$-th row 8625of \kbd{ZM}~\kbd{x} by the \kbd{ZC}~\kbd{y} (seen as a column vector, assumed 8626to have compatible dimensions). Assumes that $x$ is nonempty and 8627$0 < i < \kbd{lg(x[1])}$. 8628 8629\fun{int}{ZMrow_equal0}{GEN V, long i} returns $1$ if the $i$-th row of 8630the \kbd{ZM}~\kbd{V} is zero, and $0$ otherwise. 8631 8632\fun{GEN}{ZV_ZM_mul}{GEN x, GEN y} multiplies the \kbd{ZV}~\kbd{x} 8633by the \kbd{ZM}~\kbd{y}. Returns a \typ{VEC}. 8634 8635\fun{GEN}{ZM_Z_divexact}{GEN x, GEN y} returns $x/y$ assuming all divisions 8636are exact. 8637 8638\fun{GEN}{ZM_Z_div}{GEN x, GEN y} returns $x/y$, where the resulting matrix 8639has rational entries. 8640 8641\fun{GEN}{ZC_Q_mul}{GEN x, GEN y} returns $x*y$, where $y$ is a rational number 8642and the resulting \typ{COL} has rational entries. 8643 8644\fun{GEN}{ZM_Q_mul}{GEN x, GEN y} returns $x*y$, where $y$ is a rational number 8645and the resulting matrix has rational entries. 8646 8647\fun{GEN}{ZM_pow}{GEN x, GEN n} returns $\kbd{x}^\kbd{n}$, assuming \kbd{x} 8648is a square \kbd{ZM} and $\kbd{n}\geq 0$. 8649 8650\fun{GEN}{ZM_powu}{GEN x, ulong n} returns $\kbd{x}^\kbd{n}$, assuming \kbd{x} 8651is a square \kbd{ZM} and $\kbd{n}\geq 0$. 8652 8653\fun{GEN}{ZM_det}{GEN M} if \kbd{M} is a \kbd{ZM}, returns the determinant of 8654$M$. This is the function underlying \tet{matdet} whenever $M$ is a \kbd{ZM}. 8655 8656\fun{GEN}{ZM_permanent}{GEN M} if \kbd{M} is a \kbd{ZM}, returns its 8657permanent. This is the function underlying \tet{matpermanent} whenever $M$ 8658is a \kbd{ZM}. It assumes that the matrix is square of dimension $< 8659\kbd{BITS\_IN\_LONG}$. 8660 8661\fun{GEN}{ZM_detmult}{GEN M} if \kbd{M} is a \kbd{ZM}, returns a multiple of 8662the determinant of the lattice generated by its columns. This is the function 8663underlying \tet{detint}. 8664 8665\fun{GEN}{ZM_supnorm}{GEN x} return the sup norm of the \kbd{ZM} $x$. 8666 8667\fun{GEN}{ZM_charpoly}{GEN M} returns the characteristic polynomial (in 8668variable $0$) of the \kbd{ZM} $M$. 8669 8670\fun{GEN}{ZM_imagecompl}{GEN x} returns \kbd{matimagecompl(x)}. 8671 8672\fun{long}{ZM_rank}{GEN x} returns \kbd{matrank(x)}. 8673 8674\fun{GEN}{ZM_ker}{GEN x} returns the primitive part of \kbd{matker(x)}; in 8675other words the $\Q$-basis vectors are made integral and primitive. 8676 8677\fun{GEN}{ZM_indexrank}{GEN x} returns \kbd{matindexrank(x)}. 8678 8679\fun{GEN}{ZM_indeximage}{GEN x} returns \kbd{gel(ZM\_indexrank(x), 2)}. 8680 8681\fun{long}{ZM_max_lg}{GEN x} returns the effective length of the longest 8682entry in $x$. 8683 8684\fun{GEN}{ZM_inv}{GEN M, GEN *pd} if \kbd{M} is a \kbd{ZM}, return 8685a primitive matrix $H$ such that $M H$ is $d$ times the identity 8686and set \kbd{*pd} to $d$. Uses a multimodular algorithm up to Hadamard's bound. 8687If you suspect that the denominator is much smaller than $\det M$, you may 8688use \tet{ZM_inv_ratlift}. 8689 8690\fun{GEN}{ZM_inv_ratlift}{GEN M, GEN *pd} if \kbd{M} is a \kbd{ZM}, 8691return a primitive matrix $H$ such that $M H$ is $d$ times the identity 8692and set \kbd{*pd} to $d$. Uses a multimodular algorithm, attempting 8693rational reconstruction along the way. To be used when you expect that the 8694denominator of $M^{-1}$ is much smaller than $\det M$ else use \kbd{ZM\_inv}. 8695 8696\fun{GEN}{SL2_inv_shallow}{GEN M} return the inverse of $M \in 8697\text{SL}_2(\Z)$. Not gerepile-safe. 8698 8699\fun{GEN}{ZM_pseudoinv}{GEN M, GEN *pv, GEN *pd} if \kbd{M} is a nonempty 8700\kbd{ZM}, let $v = [y,z]$ returned by \kbd{indexrank} and 8701let $M_1$ be the corresponding square invertible matrix. 8702Return a primitive left-inverse $H$ such that $H M_1$ is 8703$d$ times the identity and set \kbd{*pd} to $d$. If \kbd{pv} is not 8704\kbd{NULL}, set \kbd{*pv} to $v$. Not gerepile-safe. 8705 8706\fun{GEN}{ZM_gauss}{GEN a, GEN b} as \kbd{gauss}, where $a$ and $b$ 8707coefficients are \typ{INT}s. 8708 8709\fun{GEN}{ZM_det_triangular}{GEN x} returns the product of the diagonal 8710entries of $x$ (its determinant if it is indeed triangular). 8711 8712\fun{int}{ZM_isidentity}{GEN x} return 1 if the \kbd{ZM} $x$ is the 8713identity matrix, and 0 otherwise. 8714 8715\fun{int}{ZM_isdiagonal}{GEN x} return 1 if the \kbd{ZM} $x$ is diagonal, 8716and 0 otherwise. 8717 8718\fun{int}{ZM_isscalar}{GEN x, GEN s} given a \kbd{ZM} $x$ and a 8719\typ{INT} $s$, return 1 if $x$ is equal to $s$ times the identity, and 0 8720otherwise. If $s$ is \kbd{NULL}, test whether $x$ is an arbitrary scalar 8721matrix. 8722 8723\fun{long}{ZC_is_ei}{GEN x} return $i$ if the \kbd{ZC} $x$ has $0$ entries, 8724but for a $1$ at position $i$. 8725 8726\fun{int}{ZM_ishnf}{GEN x} return $1$ if $x$ is in HNF form, i.e. is upper 8727triangular with positive diagonal coefficients, and for $j>i$, 8728$x_{i,i}>x_{i,j} \ge 0$. 8729 8730\subsec{\kbd{QM}} 8731 8732\fun{GEN}{QM_charpoly_ZX}{GEN M} returns the characteristic polynomial 8733(in variable $0$) of the \kbd{QM} $M$, assuming that the result has integer 8734coefficients. 8735 8736\fun{GEN}{QM_charpoly_ZX_bound}{GEN M, long b} as \tet{QM_charpoly_ZX} 8737assuming that the sup norm of the (integral) result is $\leq 2^b$. 8738 8739\fun{GEN}{QM_gauss}{GEN a, GEN b} as \kbd{gauss}, where $a$ and $b$ 8740coefficients are \typ{FRAC}s. 8741 8742\fun{GEN}{QM_gauss_i}{GEN a, GEN b, long flag} as \kbd{QM\_gauss} if 8743\kbd{flag} is $0$. Else, no longer assume that $a$ is left-invertible and 8744return a solution of $P a x = P b$ where $P$ is a row-selection matrix 8745such that $A = P a Q$ is square invertible of maximal rank, for some 8746column-selection matrix $Q$; in particular, $x$ is a solution of 8747the original equation $a x = b$ if and only if a solution exists. 8748 8749\fun{GEN}{QM_indexrank}{GEN x} returns \kbd{matindexrank(x)}. 8750 8751\fun{GEN}{QM_inv}{GEN M} return the inverse of the \kbd{QM} $M$. 8752 8753\fun{long}{QM_rank}{GEN x} returns \kbd{matrank(x)}. 8754 8755\fun{GEN}{QM_image}{GEN x} returns an integral matrix with primitive columns 8756generating the image of $x$. 8757 8758\fun{GEN}{QM_image_shallow}{GEN A} shallow version of the previous function, 8759not suitable for \kbd{gerepile}. 8760 8761\subsec{\kbd{Qevproj}} 8762 8763\fun{GEN}{Qevproj_init}{GEN M} let $M$ be a $n\times d$ \kbd{ZM} of 8764maximal rank $d \leq n$, representing the basis of a $\Q$-subspace 8765$V$ of $\Q^n$. Return a projector on $V$, to be used by \tet{Qevproj_apply}. 8766The interface details may change in the future, but this function currently 8767returns $[M, B,D,p]$, where $p$ is a \typ{VECSMALL} with $d$ entries 8768such that the submatrix $A = \kbd{rowpermute}(M,p)$ is invertible, $B$ is a 8769\kbd{ZM} and $d$ a \typ{INT} such that $A B = D \Id_d$. 8770 8771\fun{GEN}{Qevproj_apply}{GEN T, GEN pro} let $T$ be an $n\times n$ 8772\kbd{QM}, stabilizing a $\Q$-subspace $V\subset \Q^n$ of dimension $d$, and 8773let \kbd{pro} be a projector on that subspace initialized by 8774\tet{Qevproj_init}$(M)$. Return the $d\times d$ matrix representing $T_{|V}$ 8775on the basis given by the columns of $M$. 8776 8777\fun{GEN}{Qevproj_apply_vecei}{GEN T, GEN pro, long k} as 8778\tet{Qevproj_apply}, return only the image of the $k$-th basis vector $M[k]$ 8779(still on the basis given by the columns of $M$). 8780 8781\fun{GEN}{Qevproj_down}{GEN T, GEN pro} given a \kbd{ZC} (resp.~a \kbd{ZM}) 8782$T$ representing an element (resp.~a vector of elements) in the subspace $V$ 8783return a \kbd{QC} (resp.~a \kbd{QM}) $U$ such that $T = MU$. 8784 8785\subsec{\kbd{zv}, \kbd{zm}} 8786 8787\fun{GEN}{identity_zv}{long n} return the \typ{VECSMALL} $[1, 2, \dots, n]$. 8788 8789\fun{GEN}{random_zv}{long n} returns a random \kbd{zv} with $n$ components. 8790 8791\fun{GEN}{zv_neg}{GEN x} return $-x$. No check for overflow is done, which 8792occurs in the fringe case where an entry is equal to $2^{\B-1}$. 8793 8794\fun{GEN}{zv_neg_inplace}{GEN x} negates $x$ in place and return it. No check 8795for overflow is done, which occurs in the fringe case where an entry is equal 8796to $2^{\B-1}$. 8797 8798\fun{GEN}{zm_zc_mul}{GEN x, GEN y} 8799 8800\fun{GEN}{zm_mul}{GEN x, GEN y} 8801 8802\fun{GEN}{zv_z_mul}{GEN x, long n} return $n\*x$. No check for overflow is 8803done. 8804 8805\fun{long}{zv_content}{GEN x} returns the gcd of the entries of $x$. 8806 8807\fun{long}{zv_dotproduct}{GEN x, GEN y} 8808 8809\fun{long}{zv_prod}{GEN x} returns the product of all the components 8810of~\kbd{x} (assumes no overflow occurs). 8811 8812\fun{GEN}{zv_prod_Z}{GEN x} returns the product of all the components 8813of~\kbd{x}; consider all $x[i]$ as \kbd{ulong}s. 8814 8815\fun{long}{zv_sum}{GEN x} returns the sum of all the components 8816of~\kbd{x} (assumes no overflow occurs). 8817 8818\fun{long}{zv_sumpart}{GEN v, long n} returns the sum $v[1] + \dots + v[n]$ 8819(assumes no overflow occurs and \kbd{lg}$(v) > n$). 8820 8821\fun{int}{zv_cmp0}{GEN x} returns 1 if all entries of the \kbd{zv} $x$ are $0$, 8822and $0$ otherwise. 8823 8824\fun{int}{zv_equal}{GEN x, GEN y} returns $1$ if the two \kbd{zv} are equal 8825and $0$ otherwise. 8826 8827\fun{int}{zv_equal0}{GEN x} returns $1$ if all entries are $0$, and return 8828$0$ otherwise. 8829 8830\fun{long}{zv_search}{GEN L, long y} look for $y$ in the sorted 8831\kbd{zv} $L$. Return an index $i$ such that $L[i] = y$, and $0$ otherwise. 8832 8833\fun{GEN}{zv_copy}{GEN x} as \kbd{Flv\_copy}. 8834 8835\fun{GEN}{zm_transpose}{GEN x} as \kbd{Flm\_transpose}. 8836 8837\fun{GEN}{zm_copy}{GEN x} as \kbd{Flm\_copy}. 8838 8839\fun{GEN}{zero_zm}{long m, long n} as \kbd{zero\_Flm}. 8840 8841\fun{GEN}{zero_zv}{long n} as \kbd{zero\_Flv}. 8842 8843\fun{GEN}{zm_row}{GEN A, long x0} as \kbd{Flm\_row}. 8844 8845\fun{GEN}{zv_diagonal}{GEN v} return the square \kbd{zm} whose diagonal 8846is given by the entries of $v$. 8847 8848\fun{GEN}{zm_permanent}{GEN M} return the permanent of $M$. 8849The function assumes that the matrix is square of dimension 8850$< \kbd{BITS\_IN\_LONG}$. 8851 8852\fun{int}{zvV_equal}{GEN x, GEN y} returns $1$ if the two \kbd{zvV} (vectors 8853of \kbd{zv}) are equal and $0$ otherwise. 8854 8855\subsec{\kbd{ZMV} / \kbd{zmV} (vectors of \kbd{ZM}/\kbd{zm})} 8856 8857\fun{int}{RgV_is_ZMV}{GEN x} Assuming \kbd{x} is a \typ{VEC} 8858or \typ{COL} return $1$ if its components are \kbd{ZM}, and $0$ otherwise. 8859 8860\fun{GEN}{ZMV_to_zmV}{GEN z} 8861 8862\fun{GEN}{zmV_to_ZMV}{GEN z} 8863 8864\fun{GEN}{ZMV_to_FlmV}{GEN z, ulong m} 8865 8866\subsec{\kbd{QC} / \kbd{QV}, \kbd{QM}} 8867 8868\fun{GEN}{QM_mul}{GEN x, GEN y} multiplies \kbd{x} and \kbd{y} (assumed to 8869have compatible dimensions). 8870 8871\fun{GEN}{QM_sqr}{GEN x} returns the square of \kbd{x} (assumed to be square). 8872 8873\fun{GEN}{QM_QC_mul}{GEN x, GEN y} multiplies \kbd{x} and \kbd{y} (assumed to 8874have compatible dimensions). 8875 8876\fun{GEN}{QM_det}{GEN M} returns the determinant of $M$. 8877 8878\fun{GEN}{QM_ker}{GEN x} returns \kbd{matker(x)}. 8879 8880\subsec{\kbd{RgC} / \kbd{RgV}, \kbd{RgM}} 8881 8882\kbd{RgC} and \kbd{RgV} routines assume the inputs are \kbd{VEC} or \kbd{COL} 8883of the same dimension. \kbd{RgM} assume the inputs are \kbd{MAT} of 8884compatible dimensions. 8885 8886\subsubsec{Matrix arithmetic} 8887 8888\fun{void}{RgM_dimensions}{GEN x, long *m, long *n} sets $m$, resp.~$n$, to 8889the number of rows, resp.~columns of the \typ{MAT} $x$. 8890 8891\fun{GEN}{RgC_add}{GEN x, GEN y} returns $x + y$ as a \typ{COL}. 8892 8893\fun{GEN}{RgC_neg}{GEN x} returns $-x$ as a \typ{COL}. 8894 8895\fun{GEN}{RgC_sub}{GEN x, GEN y} returns $x - y$ as a \typ{COL}. 8896 8897\fun{GEN}{RgV_add}{GEN x, GEN y} returns $x + y$ as a \typ{VEC}. 8898 8899\fun{GEN}{RgV_neg}{GEN x} returns $-x$ as a \typ{VEC}. 8900 8901\fun{GEN}{RgV_sub}{GEN x, GEN y} returns $x - y$ as a \typ{VEC}. 8902 8903\fun{GEN}{RgM_add}{GEN x, GEN y} return $x+y$. 8904 8905\fun{GEN}{RgM_neg}{GEN x} returns $-x$. 8906 8907\fun{GEN}{RgM_sub}{GEN x, GEN y} returns $x-y$. 8908 8909\fun{GEN}{RgM_Rg_add}{GEN x, GEN y} assuming $x$ is a square matrix 8910and $y$ a scalar, returns the square matrix $x + y*\text{Id}$. 8911 8912\fun{GEN}{RgM_Rg_add_shallow}{GEN x, GEN y} as \kbd{RgM\_Rg\_add} with much 8913fewer copies. Not suitable for \kbd{gerepileupto}. 8914 8915\fun{GEN}{RgM_Rg_sub}{GEN x, GEN y} assuming $x$ is a square matrix 8916and $y$ a scalar, returns the square matrix $x - y*\text{Id}$. 8917 8918\fun{GEN}{RgM_Rg_sub_shallow}{GEN x, GEN y} as \kbd{RgM\_Rg\_sub} with much 8919fewer copies. Not suitable for \kbd{gerepileupto}. 8920 8921\fun{GEN}{RgC_Rg_add}{GEN x, GEN y} assuming $x$ is a nonempty column vector 8922and $y$ a scalar, returns the vector $[x_1 + y, x_2,\dots,x_n]$. 8923 8924\fun{GEN}{RgC_Rg_sub}{GEN x, GEN y} assuming $x$ is a nonempty column vector 8925and $y$ a scalar, returns the vector $[x_1 - y, x_2,\dots,x_n]$. 8926 8927\fun{GEN}{Rg_RgC_sub}{GEN a, GEN x} assuming $x$ is a nonempty column vector 8928and $a$ a scalar, returns the vector $[a - x_1, -x_2,\dots,-x_n]$. 8929 8930\fun{GEN}{RgC_Rg_div}{GEN x, GEN y} 8931 8932\fun{GEN}{RgM_Rg_div}{GEN x, GEN y} returns $x/y$ ($y$ treated as a scalar). 8933 8934\fun{GEN}{RgC_Rg_mul}{GEN x, GEN y} 8935 8936\fun{GEN}{RgV_Rg_mul}{GEN x, GEN y} 8937 8938\fun{GEN}{RgM_Rg_mul}{GEN x, GEN y} returns $x\times y$ ($y$ treated as a 8939scalar). 8940 8941\fun{GEN}{RgV_RgC_mul}{GEN x, GEN y} returns $x\times y$. 8942 8943\fun{GEN}{RgV_RgM_mul}{GEN x, GEN y} returns $x\times y$. 8944 8945\fun{GEN}{RgM_RgC_mul}{GEN x, GEN y} returns $x\times y$. 8946 8947\fun{GEN}{RgM_RgX_mul}{GEN x, GEN T} returns $x \times y$, where $y$ 8948is \kbd{RgX\_to\_RgC}$(T, \kbd{lg}(x)-1)$. 8949 8950\fun{GEN}{RgM_mul}{GEN x, GEN y} returns $x\times y$. 8951 8952\fun{GEN}{RgM_ZM_mul}{GEN x, GEN y} returns $x\times y$ assuming that $y$ is 8953a \kbd{ZM}. 8954 8955\fun{GEN}{RgM_transmul}{GEN x, GEN y} returns $x\til \times y$. 8956 8957\fun{GEN}{RgM_multosym}{GEN x, GEN y} returns $x\times y$, assuming 8958the result is a symmetric matrix (about twice faster than a generic matrix 8959multiplication). 8960 8961\fun{GEN}{RgM_transmultosym}{GEN x, GEN y} returns $x\til \times y$, assuming 8962the result is a symmetric matrix (about twice faster than a generic matrix 8963multiplication). 8964 8965\fun{GEN}{RgMrow_RgC_mul}{GEN x, GEN y, long i} multiplies the $i$-th row of 8966\kbd{RgM}~\kbd{x} by the \kbd{RgC}~\kbd{y} (seen as a column vector, assumed 8967to have compatible dimensions). Assumes that $x$ is nonempty and $0 < i < 8968\kbd{lg(x[1])}$. 8969 8970\fun{GEN}{RgM_mulreal}{GEN x, GEN y} returns the real part of $x\times y$ 8971(whose entries are \typ{INT}, \typ{FRAC}, \typ{REAL} or \typ{COMPLEX}). 8972 8973\fun{GEN}{RgM_sqr}{GEN x} returns $x^2$. 8974 8975\fun{GEN}{RgC_RgV_mul}{GEN x, GEN y} returns $x\times y$ (the matrix 8976$(x_iy_j)$). 8977 8978The following two functions are not well defined in general and only provided 8979for convenience in specific cases: 8980 8981\fun{GEN}{RgC_RgM_mul}{GEN x, GEN y} returns $x\times y[1,]$ if $y$ is 8982a row matrix $1\times n$, error otherwise. 8983 8984\fun{GEN}{RgM_RgV_mul}{GEN x, GEN y} returns $x\times y[,1]$ if $y$ is 8985a column matrix $n\times 1$, error otherwise. 8986 8987\fun{GEN}{RgM_powers}{GEN x, long n} returns $[\kbd{x}^0, 8988\dots, \kbd{x}^\kbd{n}]$ as a \typ{VEC} of \kbd{RgM}s. 8989 8990\smallskip 8991 8992\fun{GEN}{RgV_sum}{GEN v} sum of the entries of $v$ 8993 8994\fun{GEN}{RgV_prod}{GEN v} product of the entries of $v$, using 8995a divide and conquer strategy 8996 8997\fun{GEN}{RgV_sumpart}{GEN v, long n} returns the sum $v[1] + \dots + v[n]$ 8998(assumes that \kbd{lg}$(v) > n$). 8999 9000\fun{GEN}{RgV_sumpart2}{GEN v, long m, long n} returns the sum $v[m] + \dots + 9001v[n]$ (assumes that \kbd{lg}$(v) > n$ and $m > 0$). Returns \kbd{gen\_0} 9002when $m > n$. 9003 9004\fun{GEN}{RgM_sumcol}{GEN v} returns a \typ{COL}, sum of the columns of the 9005\typ{MAT} $v$. 9006 9007\fun{GEN}{RgV_dotproduct}{GEN x,GEN y} returns the scalar product of $x$ and $y$ 9008 9009\fun{GEN}{RgV_dotsquare}{GEN x} returns the scalar product of $x$ with itself. 9010 9011\fun{GEN}{RgV_kill0}{GEN v} returns a shallow copy of $v$ where entries 9012matched by \kbd{gequal0} are replaced by \kbd{NULL}. The return value 9013is not a valid \kbd{GEN} and must be handled specially. The idea is 9014to pre-treat a vector of coefficients to speed up later linear combinations 9015or scalar products. 9016 9017\fun{GEN}{gram_matrix}{GEN v} returns the \idx{Gram matrix} $(v_i\cdot v_j)$ 9018attached to the entries of $v$ (matrix, or vector of vectors). 9019 9020\fun{GEN}{RgV_polint}{GEN X, GEN Y, long v} $X$ and $Y$ being two vectors of 9021the same length, returns the polynomial $T$ in variable $v$ such that 9022$T(X[i]) = Y[i]$ for all $i$. The special case $X = \kbd{NULL}$ 9023corresponds to $X = [1,2,\dots,n]$, where $n$ is the length of $Y$. 9024 9025\fun{GEN}{polintspec}{GEN X, GEN Y, GEN t, long n, long *pe} 9026return $P(t)$ where $P$ is the Lagrange interpolation polynomial 9027attached to the $n$ points $(X[0],Y[0]), \dots, (X[n-1],Y[n-1])$. 9028If \kbd{pe} is not \kbd{NULL} and $t$ is a complex numeric value, \kbd{*pe} 9029contains an error estimate for the returned value (Neville's algorithm, see 9030\kbd{polinterpolate}). In extrapolation algorithms, e.g., Romberg 9031integration, this function is usually called on actual \kbd{GEN} vectors 9032with offsets: $x + k$ and $y + k$ so as to interpolate on $x[k..k+n-1]$ 9033without having to use \kbd{vecslice}. 9034 9035\fun{GEN}{polint_i}{GEN X, GEN Y, GEN t, long *pe} as \kbd{polintspec}, 9036where $X$ and $Y$ are actual \kbd{GEN} vectors. 9037 9038\subsubsec{Special shapes} 9039 9040The following routines check whether matrices or vectors have a special 9041shape, using \kbd{gequal1} and \kbd{gequal0} to test components. (This makes 9042a difference when components are inexact.) 9043 9044\fun{int}{RgV_isscalar}{GEN x} return 1 if all the entries of $x$ are $0$ 9045(as per \kbd{gequal0}), except possibly the first one. The name comes from 9046vectors expressing polynomials on the standard basis $1,T,\dots, T^{n-1}$, or 9047on \kbd{nf.zk} (whose first element is $1$). 9048 9049\fun{int}{QV_isscalar}{GEN x} as \kbd{RgV\_isscalar}, assuming $x$ is a 9050\kbd{QV} (\typ{INT} and \typ{FRAC} entries only). 9051 9052\fun{int}{ZV_isscalar}{GEN x} as \kbd{RgV\_isscalar}, assuming $x$ is a 9053\kbd{ZV} (\typ{INT} entries only). 9054 9055\fun{int}{RgM_isscalar}{GEN x, GEN s} return 1 if $x$ is the scalar matrix 9056equal to $s$ times the identity, and 0 otherwise. If $s$ is \kbd{NULL}, test 9057whether $x$ is an arbitrary scalar matrix. 9058 9059\fun{int}{RgM_isidentity}{GEN x} return 1 if the \typ{MAT} $x$ is the 9060identity matrix, and 0 otherwise. 9061 9062\fun{int}{RgM_isdiagonal}{GEN x} return 1 if the \typ{MAT} $x$ is a 9063diagonal matrix, and 0 otherwise. 9064 9065\fun{long}{RgC_is_ei}{GEN x} return $i$ if the \typ{COL} $x$ has $0$ entries, 9066but for a $1$ at position $i$. 9067 9068\fun{int}{RgM_is_ZM}{GEN x} return 1 if the \typ{MAT}~$x$ has only 9069\typ{INT} coefficients, and 0 otherwise. 9070 9071\fun{long}{qfiseven}{GEN M} return 1 if the square symetric typ{ZM}~$x$ 9072is an even quadratic form (all diagonal coefficients are even), and 0 otherwise. 9073 9074\fun{int}{RgM_is_QM}{GEN x} return 1 if the \typ{MAT}~$x$ has only 9075\typ{INT} or \typ{FRAC} coefficients, and 0 otherwise. 9076 9077\fun{long}{RgV_isin}{GEN v, GEN x} return the first index $i$ such that 9078$v[i] = x$ if it exists, and $0$ otherwise. Naive search in linear time, does 9079not assume that \kbd{v} is sorted. 9080 9081\fun{long}{RgV_isin_i}{GEN v, GEN x, long n} return the first index $i\ leq n$ 9082such that $v[i] = x$ if it exists, and $0$ otherwise. Naive search in linear 9083time, does not assume that \kbd{v} is sorted. Assume that $n < \kbd{lg(v)}$. 9084 9085\fun{GEN}{RgM_diagonal}{GEN m} returns the diagonal of $m$ as a \typ{VEC}. 9086 9087\fun{GEN}{RgM_diagonal_shallow}{GEN m} shallow version of \kbd{RgM\_diagonal} 9088 9089\subsubsec{Conversion to floating point entries} 9090 9091\fun{GEN}{RgC_gtofp}{GEN x, GEN prec} returns the \typ{COL} obtained by 9092applying \kbd{gtofp(gel(x,i), prec)} to all coefficients of $x$. 9093 9094\fun{GEN}{RgV_gtofp}{GEN x, GEN prec} returns the \typ{VEC} obtained by 9095applying \kbd{gtofp(gel(x,i), prec)} to all coefficients of $x$. 9096 9097\fun{GEN}{RgC_gtomp}{GEN x, long prec} returns the \typ{COL} obtained by 9098applying \kbd{gtomp(gel(x,i), prec)} to all coefficients of $x$. 9099 9100\fun{GEN}{RgC_fpnorml2}{GEN x, long prec} returns (a stack-clean variant of) 9101\bprog 9102 gnorml2( RgC_gtofp(x, prec) ) 9103@eprog 9104 9105\fun{GEN}{RgM_gtofp}{GEN x, GEN prec} returns the \typ{MAT} obtained by 9106applying \kbd{gtofp(gel(x,i), prec)} to all coefficients of $x$. 9107 9108\fun{GEN}{RgM_gtomp}{GEN x, long prec} returns the \typ{MAT} obtained by 9109applying \kbd{gtomp(gel(x,i), prec)} to all coefficients of $x$. 9110 9111\fun{GEN}{RgM_fpnorml2}{GEN x, long prec} returns (a stack-clean variant of) 9112\bprog 9113 gnorml2( RgM_gtofp(x, prec) ) 9114@eprog 9115 9116\subsubsec{Linear algebra, linear systems} 9117 9118\fun{GEN}{RgM_inv}{GEN a} returns a left inverse of $a$ (which needs not be 9119square), or \kbd{NULL} if this turns out to be impossible. The latter 9120happens when the matrix does not have maximal rank (or when rounding errors 9121make it appear so). 9122 9123\fun{GEN}{RgM_inv_upper}{GEN a} as \kbd{RgM\_inv}, assuming that $a$ is a 9124nonempty invertible upper triangular matrix, hence a little faster. 9125 9126\fun{GEN}{RgM_RgC_invimage}{GEN A, GEN B} returns a \typ{COL} $X$ such that 9127$A X = B$ if one such exists, and \kbd{NULL} otherwise. 9128 9129\fun{GEN}{RgM_invimage}{GEN A, GEN B} returns a \typ{MAT} $X$ such that 9130$A X = B$ if one such exists, and \kbd{NULL} otherwise. 9131 9132\fun{GEN}{RgM_Hadamard}{GEN a} returns a upper bound for the absolute 9133value of $\text{det}(a)$. The bound is a \typ{INT}. 9134 9135\fun{GEN}{RgM_solve}{GEN a, GEN b} returns $a^{-1}b$ where $a$ is a square 9136\typ{MAT} and $b$ is a \typ{COL} or \typ{MAT}. Returns \kbd{NULL} if $a^{-1}$ 9137cannot be computed, see \tet{RgM_inv}. 9138 9139If $b = \kbd{NULL}$, the matrix $a$ need no longer be square, and we strive 9140to return a left inverse for $a$ (\kbd{NULL} if it does not exist). 9141 9142\fun{GEN}{RgM_solve_realimag}{GEN M, GEN b} $M$ being a \typ{MAT} 9143with $r_1+r_2$ rows and $r_1+2r_2$ columns, $y$ a \typ{COL} or \typ{MAT} 9144such that the equation $Mx = y$ makes sense, returns $x$ under the following 9145simplifying assumptions: the first $r_1$ rows of $M$ and $y$ are real 9146(the $r_2$ others are complex), and $x$ is real. This is stabler and faster 9147than calling $\kbd{RgM\_solve}(M, b)$ over $\C$. In most applications, 9148$M$ approximates the complex embeddings of an integer basis in a number 9149field, and $x$ is actually rational. 9150 9151\fun{GEN}{split_realimag}{GEN x, long r1, long r2} $x$ is a \typ{COL} or 9152\typ{MAT} with $r_1 + r_2$ rows, whose first $r_1$ rows have real entries 9153(the $r_2$ others are complex). Return an object of the same type as 9154$x$ and $r_1 + 2r_2$ rows, such that the first $r_1 + r_2$ rows contain 9155the real part of $x$, and the $r_2$ following ones contain the imaginary part 9156of the last $r_2$ rows of $x$. Called by \tet{RgM_solve_realimag}. 9157 9158\fun{GEN}{RgM_det_triangular}{GEN x} returns the product of the diagonal 9159entries of $x$ (its determinant if it is indeed triangular). 9160 9161\fun{GEN}{Frobeniusform}{GEN V, long n} given the vector $V$ of elementary 9162divisors for $M - x\text{Id}$, where $M$ is an $n\times n$ square matrix. 9163Returns the Frobenius form of $M$. 9164 9165\fun{int}{RgM_QR_init}{GEN x, GEN *pB, GEN *pQ, GEN *pL, long prec} 9166QR-decomposition of a square invertible \typ{MAT} $x$ with real coefficients. 9167Sets \kbd{*pB} to the vector of squared lengths of the $x[i]$, \kbd{*pL} to 9168the Gram-Schmidt coefficients and \kbd{*pQ} to a vector of successive 9169Householder transforms. If $R$ denotes the transpose of $L$ and $Q$ is the 9170result of applying \kbd{*pQ} to the identity matrix, then $x = QR$ is the QR 9171decomposition of $x$. Returns $0$ is $x$ is not invertible or we hit a 9172precision problem, and $1$ otherwise. 9173 9174\fun{int}{QR_init}{GEN x, GEN *pB, GEN *pQ, GEN *pL, long prec} as 9175\kbd{RgM\_QR\_init}, assuming further that $x$ has \typ{INT} or \typ{REAL} 9176coefficients. 9177 9178\fun{GEN}{R_from_QR}{GEN x, long prec} assuming that $x$ is a square 9179invertible \typ{MAT} with \typ{INT} or \typ{REAL} coefficients, return 9180the upper triangular $R$ from the $QR$ docomposition of $x$. Not memory 9181clean. If the matrix is not known to have \typ{INT} or \typ{REAL} 9182coefficients, apply \tet{RgM_gtomp} first. 9183 9184\fun{GEN}{gaussred_from_QR}{GEN x, long prec} assuming that $x$ is a square 9185invertible \typ{MAT} with \typ{INT} or \typ{REAL} coefficients, returns 9186\kbd{qfgaussred(x\til * x)}; this is essentially the upper triangular $R$ 9187matrix from the $QR$ decomposition of $x$, renormalized to accomodate 9188\kbd{qfgaussred} conventions. Not memory clean. 9189 9190\fun{GEN}{RgM_gram_schmidt}{GEN e, GEN *ptB} naive (unstable) Gram-Schmidt 9191orthogonalization of the basis $(e_i)$ given by the columns of \typ{MAT} $e$. 9192Return the $e_i^*$ (as columns of a \typ{MAT}) and set \kbd{*ptB} to the 9193vector of squared lengths $|e_i^*|^2$. 9194 9195\fun{GEN}{RgM_Babai}{GEN M, GEN y} given a \typ{MAT} $M$ of maximal rank $n$ 9196and a \typ{COL} $y$ of the same dimension, apply Babai's nearest plane 9197algorithm to return an \emph{integral} $x$ such that $y - Mx$ has small $L_2$ 9198norm. This yields an approximate solution to the closest vector problem: if 9199$M$ is LLL-reduced, then 9200$$|| y - Mx ||_2 \leq 2 (2/\sqrt{3})^n || y - MX ||_2$$ 9201for all $X \in \Z^n$. 9202 9203\subsec{\kbd{ZG}} 9204 9205Let $G$ be a multiplicative group with neutral element $1_G$ whose 9206multiplication is supported by \kbd{gmul} and where equality test is 9207performed using \tet{gidentical}, e.g. a matrix group. The following 9208routines implement basic computations in the group algebra $\Z[G]$. All of 9209them are shallow for efficiency reasons. A \kbd{ZG} is either 9210 9211\item a \typ{INT} $n$, representing $n[1_G]$ 9212 9213\item or a ``factorization matrix'' with two columns $[g,e]$: the first one 9214contains group elements, sorted according to \tet{cmp_universal}, and the 9215second one contains integer ``exponents'', representing $\sum e_i [g_i]$. 9216 9217Note that \tet{to_famat} and \tet{to_famat_shallow}$(g,e)$ allow to build 9218the \kbd{ZG} $e[g]$ from $e\in \Z$ and $g\in G$. 9219 9220\fun{GEN}{ZG_normalize}{GEN x} given a \typ{INT} $x$ or a factorization 9221matrix \emph{without} assuming that the first column is properly sorted. 9222Return a valid (sorted) \kbd{ZG}. Shallow function. 9223 9224\fun{GEN}{ZG_add}{GEN x, GEN y} return $x+y$; shallow function. 9225 9226\fun{GEN}{ZG_neg}{GEN x} return $-x$; shallow function. 9227 9228\fun{GEN}{ZG_sub}{GEN x, GEN y} return $x-y$; shallow function. 9229 9230\fun{GEN}{ZG_mul}{GEN x, GEN y} return $xy$; shallow function. 9231 9232\fun{GEN}{ZG_G_mul}{GEN x, GEN y} given a \kbd{ZG} $x$ and $y\in G$, 9233 return $xy$; shallow function. 9234 9235\fun{GEN}{G_ZG_mul}{GEN x, GEN y} given a \kbd{ZG} $y$ and $x\in G$, 9236 return $xy$; shallow function. 9237 9238\fun{GEN}{ZG_Z_mul}{GEN x, GEN n} given a \kbd{ZG} $x$ and $y\in \Z$, 9239 return $xy$; shallow function. 9240 9241\fun{GEN}{ZGC_G_mul}{GEN v, GEN x} given $v$ a vector of \kbd{ZG} and $x\in 9242G$ return the vector (with the same type as $v$ with entries $v[i]\cdot x$. 9243Shallow function. 9244 9245\fun{void}{ZGC_G_mul_inplace}{GEN v, GEN x} as \tet{ZGC_G_mul}, modifying 9246$v$ in place. 9247 9248\fun{GEN}{ZGC_Z_mul}{GEN v, GEN n} given $v$ a vector of \kbd{ZG} and $n\in 9249Z$ return the vector (with the same type as $v$ with entries $n \cdot v[i]$. 9250Shallow function. 9251 9252\fun{GEN}{G_ZGC_mul}{GEN x, GEN v} given $v$ a vector of \kbd{ZG} and $x\in 9253G$ return the vector of $x \cdot v[i]$. Shallow function. 9254 9255\fun{GEN}{ZGCs_add}{GEN x, GEN y} add two sparse vectors of 9256\kbd{ZG} elements (see Sparse linear algebra below). 9257 9258\subsec{Sparse and blackbox linear algebra} 9259 9260A sparse column \kbd{zCs} $v$ is a \typ{COL} with two components $C$ and $E$ 9261which are \typ{VECSMALL} of the same length, representing $\sum_i 9262E[i]*e_{C[i]}$, where $(e_j)$ is the canonical basis. A sparse matrix 9263(\kbd{zMs}) is a \typ{VEC} of \kbd{zCs}. 9264 9265\kbd{FpCs} and \kbd{FpMs} are identical to the above, but $E[i]$ is now 9266interpreted as a \emph{signed} C long integer representing an element of 9267$\F_p$. This is important since $p$ can be so large that $p+E[i]$ would not 9268fit in a C long. 9269 9270\kbd{RgCs} and \kbd{RgMs} are similar, except that the type of the components 9271of $E$ is now unspecified. Functions handling those later objects 9272must not depend on the type of those components. 9273 9274\kbd{F2Ms} are \typ{VEC} of \kbd{F2Cs}. \kbd{F2Cs} are \typ{VECSMALL} whoses 9275entries are the nonzero coefficients ($1$). 9276 9277It is not possible to derive the space dimension (number of rows) from the 9278above data. Thus most functions take an argument \kbd{nbrow} which is the 9279number of rows of the corresponding column/matrix in dense representation. 9280 9281\fun{GEN}{F2Ms_to_F2m}{GEN M, long nbrow} convert a \kbd{F2m} to a \kbd{F2Ms}. 9282 9283\fun{GEN}{F2m_to_F2Ms}{GEN M} convert a \kbd{F2m} to a \kbd{F2Ms}. 9284 9285\fun{GEN}{zCs_to_ZC}{GEN C, long nbrow} convert the sparse vector $C$ 9286to a dense \kbd{ZC} of dimension \kbd{nbrow}. 9287 9288\fun{GEN}{zMs_to_ZM}{GEN M, long nbrow} convert the sparse matrix $M$ 9289to a dense \kbd{ZM} whose columns have dimension \kbd{nbrow}. 9290 9291\fun{GEN}{FpMs_FpC_mul}{GEN M, GEN B, GEN p} multiply the sparse matrix $M$ 9292(over $\F_p$) by the \kbd{FpC} $B$. The result is an \kbd{FpC}, i.e.~a 9293dense vector. 9294 9295\fun{GEN}{zMs_ZC_mul}{GEN M, GEN B, GEN p} multiply the sparse matrix $M$ 9296by the \kbd{ZC} $B$ (over $\Z$). The result is an \kbd{ZC}, i.e.~a 9297dense vector. 9298 9299\fun{GEN}{FpV_FpMs_mul}{GEN B, GEN M, GEN p} multiply the \kbd{FpV} $B$ 9300by the sparse matrix $M$ (over $\F_p$). The result is an \kbd{FpV}, i.e.~a 9301dense vector. 9302 9303\fun{GEN}{ZV_zMs_mul}{GEN B, GEN M, GEN p} multiply the \kbd{FpV} $B$ (over 9304$\Z$) by the sparse matrix $M$. The result is an \kbd{ZV}, i.e.~a 9305dense vector. 9306 9307\fun{void}{RgMs_structelim}{GEN M, long nbrow, GEN A, GEN *p_col, GEN *p_row} 9308$M$ being a RgMs with \kbd{nbrow} rows, $A$ being a list of row indices, 9309Perform structured elimination on $M$ by removing some rows and columns until 9310the number of effectively present rows is equal to the number of columns. 9311the result is stored in two \typ{VECSMALL}s, \kbd{*p\_col} and \kbd{*p\_row}: 9312\kbd{*p\_col} is a map from the new columns indices to the old one. 9313\kbd{*p\_row} is a map from the old rows indices to the new one ($0$ if removed). 9314 9315\fun{GEN}{F2Ms_colelim}{GEN M, long nbrow} returns some subset of the columns 9316of $M$ as a \typ{VECSMALL} of indices, selected such that the dimension of the 9317kernel of the matrix is preserved. The subset is not guaranteed to be minimal. 9318 9319\fun{GEN}{F2Ms_ker}{GEN M, long nbrow} returns some kernel vectors of $M$ 9320using block Lanczos algorithm. 9321 9322\fun{GEN}{FpMs_leftkernel_elt}{GEN M, long nbrow, GEN p} 9323$M$ being a sparse matrix over $\F_p$, return a nonzero kbd{FpV} $X$ such 9324that $X\*M$ components are almost all $0$. 9325 9326\fun{GEN}{FpMs_FpCs_solve}{GEN M, GEN B, long nbrow, GEN p} 9327solve the equation $M\*X = B$, where $M$ is a sparse matrix and $B$ is a sparse 9328vector, both over $\F_p$. Return either a solution as a \typ{COL} (dense 9329vector), the index of a column which is linearly dependent from the 9330others as a \typ{VECSMALL} with a single component, or \kbd{NULL} 9331(can happen if $B$ is not in the image of $M$). 9332 9333\fun{GEN}{FpMs_FpCs_solve_safe}{GEN M, GEN B, long nbrow, GEN p} 9334as above, but in the event that $p$ is not a prime and an impossible division 9335occurs, return \kbd{NULL}. 9336 9337\fun{GEN}{ZpMs_ZpCs_solve}{GEN M, GEN B, long nbrow, GEN p, long e} 9338solve the equation $MX = B$, where $M$ is a sparse matrix and $B$ is a sparse 9339vector, both over $\Z/p^e\Z$. Return either a solution as a \typ{COL} (dense 9340vector), or the index of a column which is linearly dependent from the 9341others as a \typ{VECSMALL} with a single component. 9342 9343\fun{GEN}{gen_FpM_Wiedemann}{void *E, GEN (*f)(void*, GEN), GEN B, GEN p} 9344solve the equation $f(X) = B$ over $\F_p$, where $B$ is a \kbd{FpV}, and $f$ 9345is a blackbox endomorphism, where $f(E, X)$ computes the value of $f$ at the 9346(dense) column vector $X$. Returns either a solution \typ{COL}, or a kernel 9347vector as a \typ{VEC}. 9348 9349\fun{GEN}{gen_ZpM_Dixon_Wiedemann}{void *E, GEN (*f)(void*, GEN), GEN B, GEN p, long e} 9350solve equation $f(X) = B$ over $\Z/p^e\Z$, where $B$ is a \kbd{ZV}, and $f$ is a 9351blackbox endomorphism, where $f(E, X)$ computes the value of $f$ at the 9352(dense) column vector $X$. Returns either a solution \typ{COL}, or a kernel 9353vector as a \typ{VEC}. 9354 9355\subsec{Obsolete functions} 9356 9357The functions in this section are kept for backward compatibility only 9358and will eventually disappear. 9359 9360\fun{GEN}{image2}{GEN x} compute the image of $x$ using a very slow 9361algorithm. Use \tet{image} instead. 9362 9363\section{Integral, rational and generic polynomial arithmetic} 9364 9365\subsec{\kbd{ZX}} 9366 9367\fun{void}{RgX_check_ZX}{GEN x, const char *s} Assuming \kbd{x} is a \typ{POL} 9368raise an error if it is not a \kbd{ZX} ($s$ should point to the name of the 9369caller). 9370 9371\fun{GEN}{ZX_copy}{GEN x,GEN p} returns a copy of \kbd{x}. 9372 9373\fun{long}{ZX_max_lg}{GEN x} returns the effective length of the longest 9374component in $x$. 9375 9376\fun{GEN}{scalar_ZX}{GEN x, long v} returns the constant \kbd{ZX} in variable 9377$v$ equal to the \typ{INT} $x$. 9378 9379\fun{GEN}{scalar_ZX_shallow}{GEN x, long v} returns the constant \kbd{ZX} in 9380variable $v$ equal to the \typ{INT} $x$. Shallow function not suitable for 9381\kbd{gerepile} and friends. 9382 9383\fun{GEN}{ZX_renormalize}{GEN x, long l}, as \kbd{normalizepol}, where 9384$\kbd{l} = \kbd{lg(x)}$, in place. 9385 9386\fun{int}{ZX_equal}{GEN x, GEN y} returns $1$ if the two \kbd{ZX} have 9387the same \kbd{degpol} and their coefficients are equal. Variable numbers are 9388not checked. 9389 9390\fun{int}{ZX_equal1}{GEN x} returns $1$ if the \kbd{ZX} $x$ is equal to $1$ 9391and $0$ otherwise. 9392 9393\fun{int}{ZX_is_monic}{GEN x} returns $1$ if the \kbd{ZX} $x$ is monic and $0$ 9394otherwise. The zero polynomial considered not monic. 9395 9396\fun{GEN}{ZX_add}{GEN x,GEN y} adds \kbd{x} and \kbd{y}. 9397 9398\fun{GEN}{ZX_sub}{GEN x,GEN y} subtracts \kbd{x} and \kbd{y}. 9399 9400\fun{GEN}{ZX_neg}{GEN x} returns $-\kbd{x}$. 9401 9402\fun{GEN}{ZX_Z_add}{GEN x,GEN y} adds the integer \kbd{y} to the 9403\kbd{ZX}~\kbd{x}. 9404 9405\fun{GEN}{ZX_Z_add_shallow}{GEN x,GEN y} shallow version of \tet{ZX_Z_add}. 9406 9407\fun{GEN}{ZX_Z_sub}{GEN x,GEN y} subtracts the integer \kbd{y} to the 9408\kbd{ZX}~\kbd{x}. 9409 9410\fun{GEN}{Z_ZX_sub}{GEN x,GEN y} subtracts the \kbd{ZX} \kbd{y} to the 9411integer \kbd{x}. 9412 9413\fun{GEN}{ZX_Z_mul}{GEN x,GEN y} multiplies the \kbd{ZX} \kbd{x} by the 9414integer \kbd{y}. 9415 9416\fun{GEN}{ZX_mulu}{GEN x, ulong y} multiplies \kbd{x} by the integer \kbd{y}. 9417 9418\fun{GEN}{ZX_shifti}{GEN x, long n} shifts all coefficients of \kbd{x} by $n$ 9419bits, which can be negative. 9420 9421\fun{GEN}{ZX_Z_divexact}{GEN x, GEN y} returns $x/y$ assuming all divisions 9422are exact. 9423 9424\fun{GEN}{ZX_divuexact}{GEN x, ulong y} returns $x/y$ assuming all divisions 9425are exact. 9426 9427\fun{GEN}{ZX_remi2n}{GEN x, long n} reduces all coefficients of \kbd{x} to 9428$n$ bits, using \tet{remi2n}. 9429 9430\fun{GEN}{ZX_mul}{GEN x,GEN y} multiplies \kbd{x} and \kbd{y}. 9431 9432\fun{GEN}{ZX_sqr}{GEN x,GEN p} returns $\kbd{x}^2$. 9433 9434\fun{GEN}{ZX_mulspec}{GEN a, GEN b, long na, long nb}. Internal routine: 9435\kbd{a} and \kbd{b} are arrays of coefficients representing polynomials 9436$\sum_{i = 0}^{\kbd{na-1}} \kbd{a}[i] X^i$ and 9437$\sum_{i = 0}^{\kbd{nb-1}} \kbd{b}[i] X^i$. Returns their product (as a true 9438\kbd{GEN}) in variable $0$. 9439 9440\fun{GEN}{ZX_sqrspec}{GEN a, long na}. Internal routine: 9441\kbd{a} is an array of coefficients representing polynomial 9442$\sum_{i = 0}^{\kbd{na-1}} \kbd{a}[i] X^i$. Return its square (as a true 9443\kbd{GEN}) in variable $0$. 9444 9445\fun{GEN}{ZX_rem}{GEN x, GEN y} returns the remainder of the Euclidean 9446division of $x$ mod $y$. Assume that $x$, $y$ are two \kbd{ZX} and that 9447$y$ is monic. 9448 9449\fun{GEN}{ZX_mod_Xnm1}{GEN T, ulong n} return $T$ modulo $X^n - 1)$. Shallow 9450function. 9451 9452\fun{GEN}{ZX_div_by_X_1}{GEN T, GEN *r} return the quotient of $T$ by $X-1$. 9453If $r$ is not \kbd{NULL} set it to $T(1)$. 9454 9455\fun{GEN}{ZX_gcd}{GEN x,GEN y} returns a gcd of the \kbd{ZX} $x$ and $y$. 9456Not memory-clean, but suitable for \kbd{gerepileupto}. 9457 9458\fun{GEN}{ZX_gcd_all}{GEN x, GEN y, GEN *pX} returns a gcd $d$ of $x$ and 9459$y$. If \kbd{pX} is not \kbd{NULL}, set $\kbd{*pX}$ to a (nonzero) integer 9460multiple of $x/d$. If $x$ and $y$ are both monic, then $d$ is monic and 9461\kbd{*pX} is exactly $x/d$. Not memory clean. 9462 9463\fun{GEN}{ZX_radical}{GEN x} returns the largest squarefree divisor 9464of the \kbd{ZX} $x$. Not memory clean. 9465 9466\fun{GEN}{ZX_content}{GEN x} returns the content of the \kbd{ZX} $x$. 9467 9468\fun{long}{ZX_val}{GEN P} as \kbd{RgX\_val}, but assumes \kbd{P} has \typ{INT} 9469coefficients. 9470 9471\fun{long}{ZX_valrem}{GEN P, GEN *z} as \kbd{RgX\_valrem}, but assumes 9472\kbd{P} has \typ{INT} coefficients. 9473 9474\fun{GEN}{ZX_to_monic}{GEN q GEN *L} given $q$ a nonzero \kbd{ZX}, 9475returns a monic integral polynomial $Q$ such that $Q(x) = C q(x/L)$, for some 9476rational $C$ and positive integer $L > 0$. If $\kbd{L}$ is not \kbd{NULL}, 9477set \kbd{*L} to $L$; if $L = 1$, \kbd{*L} is set to \kbd{gen\_1}. Shallow 9478function. 9479 9480\fun{GEN}{ZX_primitive_to_monic}{GEN q, GEN *L} as \tet{ZX_to_monic} except 9481$q$ is assumed to have trivial content, which avoids recomputing it. 9482The result is suboptimal if $q$ is not primitive ($L$ larger than 9483necessary), but remains correct. Shallow function. 9484 9485\fun{GEN}{ZX_Z_normalize}{GEN q, GEN *L} a restricted version of 9486\kbd{ZX\_primitive\_to\_monic}, where $q$ is a \emph{monic} \kbd{ZX} 9487of degree $> 0$. Finds the largest integer $L > 0$ such that 9488$Q(X) := L^{-\deg q} q(Lx)$ is integral and return $Q$; this is not 9489well-defined if $q$ is a monomial, in that case, set $L=1$ and $Q = q$. If 9490\kbd{L} is not \kbd{NULL}, set \kbd{*L} to $L$. Shallow function. 9491 9492\fun{GEN}{ZX_Q_normalize}{GEN q, GEN *L} a variant of \tet{ZX_Z_normalize} 9493where $L > 0$ is allowed to be rational, the monic $Q\in \Z[X]$ has possibly 9494smaller coefficients. Shallow function. 9495 9496\fun{GEN}{ZX_Q_mul}{GEN x, GEN y} returns $x*y$, where $y$ is a rational number 9497and the resulting \typ{POL} has rational entries. 9498 9499\fun{long}{ZX_deflate_order}{GEN P} given a nonconstant \kbd{ZX} 9500$P$, returns the largest exponent $d$ such that $P$ is of the form $P(x^d)$. 9501 9502\fun{long}{ZX_deflate_max}{GEN P, long *d}. Given a nonconstant 9503polynomial with integer coefficients $P$, sets \kbd{d} to 9504\kbd{ZX\_deflate\_order(P)} and returns \kbd{RgX\_deflate(P,d)}. Shallow 9505function. 9506 9507\fun{GEN}{ZX_rescale}{GEN P, GEN h} returns $h^{\deg(P)} P(x/h)$. 9508\kbd{P} is a \kbd{ZX} and \kbd{h} is a nonzero integer. Neither memory-clean 9509nor suitable for \kbd{gerepileupto}. 9510 9511\fun{GEN}{ZX_rescale2n}{GEN P, long n} returns $2^{n\deg(P)} P(x>>n)$ where 9512\kbd{P} is a \kbd{ZX}. 9513 9514\fun{GEN}{ZX_rescale_lt}{GEN P} returns the monic integral polynomial 9515$h^{\deg(P)-1} P(x/h)$, where \kbd{P} is a nonzero \kbd{ZX} and \kbd{h} is 9516its leading coefficient. Neither memory-clean nor suitable for 9517\kbd{gerepileupto}. 9518 9519\fun{GEN}{ZX_translate}{GEN P, GEN c} assume $P$ is a \kbd{ZX} and $c$ an 9520integer. Returns $P(X + c)$ (optimized for $c = \pm 1$). 9521 9522\fun{GEN}{ZX_unscale}{GEN P, GEN h} given a \kbd{ZX} $P$ and a \typ{INT} $h$, 9523returns $P(hx)$. Not memory clean. 9524 9525\fun{GEN}{ZX_z_unscale}{GEN P, long h} given a \kbd{ZX} $P$, 9526returns $P(hx)$. Not memory clean. 9527 9528\fun{GEN}{ZX_unscale2n}{GEN P, long n} given a \kbd{ZX} $P$, returns 9529$P(x<<n)$. Not memory clean. 9530 9531\fun{GEN}{ZX_unscale_div}{GEN P, GEN h} given a \kbd{ZX} $P$ and a \typ{INT} $h$ 9532such that $h \mid P(0)$, returns $P(hx)/h$. Not memory clean. 9533 9534\fun{GEN}{ZX_eval1}{GEN P} returns the integer $P(1)$. 9535 9536\fun{GEN}{ZX_graeffe}{GEN p} returns the Graeffe transform of $p$, i.e. the 9537\kbd{ZX} $q$ such that $p(x)p(-x) = q(x^2)$. 9538 9539\fun{GEN}{ZX_deriv}{GEN x} returns the derivative of \kbd{x}. 9540 9541\fun{GEN}{ZX_resultant}{GEN A, GEN B} returns the resultant of the 9542\kbd{ZX}~\kbd{A} and \kbd{B}. 9543 9544\fun{GEN}{ZX_disc}{GEN T} returns the discriminant of the \kbd{ZX} 9545\kbd{T}. 9546 9547\fun{GEN}{ZX_factor}{GEN T} returns the factorization of the primitive part 9548of \kbd{T} over $\Q[X]$ (the content is lost). 9549 9550\fun{int}{ZX_is_squarefree}{GEN T} returns $1$ if the 9551\kbd{ZX}~\kbd{T} is squarefree, $0$ otherwise. 9552 9553\fun{long}{ZX_is_irred}{GEN T} returns 1 it \kbd{T} is irreducible, and 95540 otherwise. 9555 9556\fun{GEN}{ZX_squff}{GEN T, GEN *E} write $T$ as a product $\prod T_i^{e_i}$ 9557with the $e_1 < e_2 < \cdots$ all distinct and the $T_i$ pairwise coprime. 9558Return the vector of the $T_i$, and set \kbd{*E} to the vector of the $e_i$, 9559as a \typ{VECSMALL}. 9560 9561\fun{GEN}{ZX_Uspensky}{GEN P, GEN ab, long flag, long bitprec} let \kbd{P} be a 9562\kbd{ZX} polynomial whose real roots are simple and \kbd{bitprec} is the 9563relative precision in bits. For efficiency reasons, \kbd{P} should not only 9564have simple real roots but actually be primitive and squarefree, but the 9565routine neither checks nor enforces this, and it returns correct results in 9566this case as well. 9567 9568\item If \kbd{flag} is 0 returns a list of intervals that isolate the real 9569roots of \kbd{P}. The return value is a column of elements which are either 9570vectors \kbd{[a,b]} of rational numbers meaning that there is a single 9571nonrational root in the open interval \kbd{(a,b)} or elements \kbd{x0} such 9572that \kbd{x0} is a rational root of \kbd{P}. Beware that the limits of the 9573open intervals can be roots of the polynomial. 9574 9575\item If \kbd{flag} is 1 returns an approximation of the real roots of \kbd{P}. 9576 9577\item If \kbd{flag} is 2 returns the number of roots. 9578 9579The argument \kbd{ab} specify the interval in which the roots 9580are searched. The default interval is $(-\infty,\infty)$. If \kbd{ab} is an 9581integer or fraction $a$ then the interval is $[a,\infty)$. If \kbd{ab} is 9582a vector $[a,b]$, where \typ{INT}, \typ{FRAC} or \typ{INFINITY} are allowed 9583for $a$ and $b$, the interval is $[a,b]$. 9584 9585\fun{long}{ZX_sturm}{GEN P} number of real roots of the nonconstant 9586squarefree \kbd{ZX} $P$. For efficiency, it is advised to make $P$ primitive 9587first. 9588 9589\fun{long}{ZX_sturmpart}{GEN P, GEN ab} number of real roots of the 9590nonconstant squarefree \kbd{ZX} $P$ in the interval specified by \kbd{ab}: 9591either \kbd{NULL} (no restriction) or a \typ{VEC} $[a,b]$ with two real 9592components (of type \typ{INT}, \typ{FRAC} or \typ{INFINITY}). For efficiency, 9593it is advised to make $P$ primitive first. 9594 9595\fun{long}{ZX_sturm_irred}{GEN P} number of real roots of the \kbd{ZX} $P$, 9596assumed irreducible over $\Q[X]$. For efficiency, it is advised to make $P$ 9597primitive first. 9598 9599\fun{long}{ZX_realroots_irred}{GEN P, long prec} real roots of the \kbd{ZX} 9600$P$, assumed irreducible over $\Q[X]$ to precision prec. For efficiency, it 9601is advised to make $P$ primitive first. 9602 9603\subsec{Resultants} 9604 9605\fun{GEN}{ZX_ZXY_resultant}{GEN A, GEN B} 9606under the assumption that \kbd{A} in $\Z[Y]$, \kbd{B} in $\Q[Y][X]$, and 9607$R = \text{Res}_Y(A, B) \in \Z[X]$, returns the resultant $R$. 9608 9609\fun{GEN}{ZX_compositum_disjoint}{GEN A, GEN B} given two irreducible \kbd{ZX} 9610defining linearly disjoint extensions, returns a \kbd{ZX} defining their 9611compositum. 9612 9613\fun{GEN}{ZX_compositum}{GEN A, GEN B, long *lambda} 9614given two irreducible \kbd{ZX}, returns an irreducible \kbd{ZX} $C$ defining 9615their compositum and set \kbd{lambda} to a small integer $k$ such that if 9616$\alpha$ is a root of $A$ and $\beta$ is a root of $B$, then $k\*\alpha + 9617\beta$ is a root of $C$. 9618 9619\fun{GEN}{ZX_ZXY_rnfequation}{GEN A, GEN B, long *lambda}, 9620assume \kbd{A} in $\Z[Y]$, \kbd{B} in $\Q[Y][X]$, and $R = 9621\text{Res}_Y(A, B) \in \Z[X]$. If \kbd{lambda = NULL}, returns $R$ 9622as in \kbd{ZY\_ZXY\_resultant}. Otherwise, \kbd{lambda} must point to 9623some integer, e.g. $0$ which is used as a seed. The function then finds a 9624small $\lambda \in \Z$ (starting from \kbd{*lambda}) such that 9625$R_\lambda(X) := \text{Res}_Y(A, B(X + \lambda Y))$ is squarefree, resets 9626\kbd{*lambda} to the chosen value and returns $R_{\lambda}$. 9627 9628\subsec{\kbd{ZXV}} 9629 9630\fun{GEN}{ZXV_equal}{GEN x,GEN y} returns $1$ if the two vectors of \kbd{ZX} 9631are equal, as per \tet{ZX_equal} (variables are not checked to be equal) and 9632$0$ otherwise. 9633 9634\fun{GEN}{ZXV_Z_mul}{GEN x,GEN y} multiplies the vector of \kbd{ZX} \kbd{x} 9635by the integer \kbd{y}. 9636 9637\fun{GEN}{ZXV_remi2n}{GEN x, long n} applies \kbd{ZX\_remi2n} to all 9638coefficients of \kbd{x}. 9639 9640\fun{GEN}{ZXV_dotproduct}{GEN x,GEN y} as \kbd{RgV\_dotproduct} assuming $x$ 9641and $y$ have \kbd{ZX} entries. 9642 9643\subsec{\kbd{ZXT}} 9644 9645\fun{GEN}{ZXT_remi2n}{GEN x, long n} applies \kbd{ZX\_remi2n} to all 9646leaves of the tree \kbd{x}. 9647 9648\subsec{\kbd{ZXQ}} 9649 9650\fun{GEN}{ZXQ_mul}{GEN x,GEN y,GEN T} returns $x*y$ mod $T$, assuming 9651that all inputs are \kbd{ZX}s and that $T$ is monic. 9652 9653\fun{GEN}{ZXQ_sqr}{GEN x,GEN T} returns $x^2$ mod $T$, assuming 9654that all inputs are \kbd{ZX}s and that $T$ is monic. 9655 9656\fun{GEN}{ZXQ_powu}{GEN x,ulong n,GEN T} returns $x^n$ mod $T$, assuming 9657that all inputs are \kbd{ZX}s and that $T$ is monic. 9658 9659\fun{GEN}{ZXQ_powers}{GEN x, long n, GEN T} returns $[\kbd{x}^0, 9660\dots, \kbd{x}^\kbd{n}]$ mod $T$ as a \typ{VEC}, assuming that all inputs are 9661\kbd{ZX}s and that $T$ is monic. 9662 9663\fun{GEN}{ZXQ_charpoly}{GEN A, GEN T, long v}: let \kbd{T} and \kbd{A} be 9664\kbd{ZX}s, returns the characteristic polynomial of \kbd{Mod(A, T)}. 9665More generally, \kbd{A} is allowed to be a \kbd{QX}, hence possibly has 9666rational coefficients, \emph{assuming} the result is a \kbd{ZX}, i.e.~the 9667algebraic number \kbd{Mod(A,T)} is integral over \kbd{Z}. 9668 9669\fun{GEN}{ZXQ_minpoly}{GEN A, GEN B, long d, ulong bound} 9670let \kbd{T} and \kbd{A} be 9671\kbd{ZX}s, returns the minimal polynomial of \kbd{Mod(A, T)} assuming it has 9672degree $d$ and its coefficients are less than $2^{\text{bound}}$. 9673More generally, \kbd{A} is allowed to be a \kbd{QX}, hence possibly has 9674rational coefficients, \emph{assuming} the result is a \kbd{ZX}, i.e.~the 9675algebraic number \kbd{Mod(A,T)} is integral over \kbd{Z}. 9676 9677\subsec{\kbd{ZXn}} 9678 9679\fun{GEN}{ZXn_mul}{GEN x, GEN y, long n} return $x\*y\pmod{X^n}$. 9680 9681\fun{GEN}{ZXn_sqr}{GEN x, long n} return $x^2\pmod{X^n}$. 9682 9683\fun{GEN}{eta_ZXn}{long r, long n} return $\eta(X^r) = \prod_{i>0} (1-X^{ri}) 9684\pmod{X^n}$, $r > 0$. 9685 9686\fun{GEN}{eta_product_ZXn}{GEN DR, long n}: $\kbd{DR}= [D,R]$ being a vector 9687with two \typ{VECSMALL} components, return $\prod_i \eta(X^{d_i})^{r_i}$. 9688Shallow function. 9689 9690\subsec{\kbd{ZXQM}} 9691 9692\kbd{ZXQM} are matrices of \kbd{ZXQ}. All entries must be integers or 9693polynomials of degree strictly less than the degree of $T$. 9694 9695\fun{GEN}{ZXQM_mul}{GEN x,GEN y,GEN T} returns $x*y$ mod $T$, assuming 9696that all inputs are \kbd{ZX}s and that $T$ is monic. 9697 9698\fun{GEN}{ZXQM_sqr}{GEN x,GEN T} returns $x^2$ mod $T$, assuming 9699that all inputs are \kbd{ZX}s and that $T$ is monic. 9700 9701\subsec{\kbd{ZXQX}} 9702 9703\fun{GEN}{ZXQX_mul}{GEN x,GEN y,GEN T} returns $x*y$, assuming 9704that all inputs are \kbd{ZXQX}s and that $T$ is monic. 9705 9706\fun{GEN}{ZXQX_ZXQ_mul}{GEN x, GEN y, GEN T} returns $x*y$, assuming 9707that $x$ is a \kbd{ZXQX}, $y$ is a \kbd{ZXQ} and $T$ is monic. 9708 9709\fun{GEN}{ZXQX_sqr}{GEN x,GEN T} returns $x^2$, assuming 9710that all inputs are \kbd{ZXQX}s and that $T$ is monic. 9711 9712\fun{GEN}{ZXQX_gcd}{GEN x,GEN y,GEN T} returns the gcd of $x$ and $y$, 9713assuming that all inputs are \kbd{ZXQX}s and that $T$ is monic. 9714 9715\subsec{\kbd{ZXX}} 9716 9717\fun{void}{RgX_check_ZXX}{GEN x, const char *s} Assuming \kbd{x} is a \typ{POL} 9718raise an error if it one of its coefficients is not an integer or a \kbd{ZX} 9719($s$ should point to the name of the caller). 9720 9721\fun{GEN}{ZXX_renormalize}{GEN x, long l}, as \kbd{normalizepol}, where 9722$\kbd{l} = \kbd{lg(x)}$, in place. 9723 9724\fun{long}{ZXX_max_lg}{GEN x} returns the effective length of the longest 9725component in $x$; assume all coefficients are \typ{INT} or \kbd{ZX}s. 9726 9727\fun{GEN}{ZXX_evalx0}{GEN P} returns $P(X, 0)$. 9728 9729\fun{GEN}{ZXX_Z_mul}{GEN x, GEN y} returns $x\*y$. 9730 9731\fun{GEN}{ZXX_Q_mul}{GEN x, GEN y} returns $x*y$, where $y$ is a rational number 9732and the resulting \typ{POL} has rational entries. 9733 9734\fun{GEN}{ZXX_Z_add_shallow}{GEN x, GEN y} returns $x+y$. Shallow function. 9735 9736\fun{GEN}{ZXX_Z_divexact}{GEN x, GEN y} returns $x/y$ assuming all integer 9737divisions are exact. 9738 9739\fun{GEN}{ZXX_to_Kronecker}{GEN P, long n} Assuming $P(X,Y)$ is a polynomial 9740of degree in $X$ strictly less than $n$, returns $P(X,X^{2*n-1})$, the 9741Kronecker form of $P$. Shallow function. 9742 9743\fun{GEN}{ZXX_to_Kronecker_spec}{GEN Q, long lQ, long n} return 9744\tet{ZXX_to_Kronecker}$(P, n)$, where $P$ is the polynomial 9745$\sum_{i = 0}^{\kbd{lQ} - 1} Q[i] x^i$. To be used when splitting 9746the coefficients of genuine polynomials into blocks. Shallow function. 9747 9748\fun{GEN}{Kronecker_to_ZXX}{GEN z, long n, long v} recover $P(X,Y)$ 9749from its Kronecker form $P(X,X^{2\*n-1})$, $v$ is the variable number 9750corresponding to $Y$. Shallow function. 9751 9752\fun{GEN}{Kronecker_to_ZXQX}{GEN z, GEN T}. Let $n = \deg T$ and let 9753$P(X,Y)\in \Z[X,Y]$ lift a polynomial in $K[Y]$, where $K := \Z[X]/(T)$ and 9754$\deg_X P < 2n-1$ --- such as would result from multiplying minimal degree 9755lifts of two polynomials in $K[Y]$. Let $z = P(t,t^{2*n-1})$ be a Kronecker 9756form of $P$, this function returns $Q\in \Z[X,t]$ such that $Q$ is congruent to 9757$P(X,t)$ mod $(T(X))$, $\deg_X Q < n$. 9758Not stack-clean. Note that $t$ need not be the same variable as $Y$! 9759 9760\fun{GEN}{ZXX_mul_Kronecker}{GEN P, GEN Q, long n} return \tet{ZX_mul} 9761applied to the Kronecker forms $P(X,X^{2\*n-1})$ and $Q(X,X^{2\*n-1})$ 9762of $P$ and $Q$. Not memory clean. 9763 9764\fun{GEN}{ZXX_sqr_Kronecker}{GEN P, long n} return \tet{ZX_sqr} 9765applied to the Kronecker forms $P(X,X^{2\*n-1})$ 9766of $P$. Not memory clean. 9767 9768\subsec{\kbd{QX}} 9769 9770\fun{void}{RgX_check_QX}{GEN x, const char *s} Assuming \kbd{x} is a \typ{POL} 9771raise an error if it is not a \kbd{QX} ($s$ should point to the name of the 9772caller). 9773 9774\fun{GEN}{QX_mul}{GEN x,GEN y} 9775 9776\fun{GEN}{QX_sqr}{GEN x} 9777 9778\fun{GEN}{QX_ZX_rem}{GEN x, GEN y} $y$ is assumed to be monic. 9779 9780\fun{GEN}{QX_gcd}{GEN x,GEN y} returns a gcd of the \kbd{QX} $x$ and $y$. 9781 9782\fun{GEN}{QX_disc}{GEN T} returns the discriminant of the \kbd{QX} 9783\kbd{T}. 9784 9785\fun{GEN}{QX_factor}{GEN T} as \kbd{ZX\_factor}. 9786 9787\fun{GEN}{QX_resultant}{GEN A, GEN B} returns the resultant of the 9788\kbd{QX}~\kbd{A} and \kbd{B}. 9789 9790\fun{GEN}{QX_complex_roots}{GEN p, long l} returns the complex roots of the 9791\kbd{QX} $p$ at accuracy $l$, where real roots are returned as \typ{REAL}s. 9792More efficient when $p$ is irreducible and primitive. Special case 9793of \tet{cleanroots}. 9794 9795\subsec{\kbd{QXQ}} 9796 9797\fun{GEN}{QXQ_norm}{GEN A, GEN B} $A$ being a \kbd{QX} and $B$ being a 9798\kbd{ZX}, returns the norm of the algebraic number $A \mod B$, using a 9799modular algorithm. To ensure that $B$ is a \kbd{ZX}, one may replace it by 9800\kbd{Q\_primpart(B)}, which of course does not change the norm. 9801 9802If $A$ is not a \kbd{ZX} --- it has a denominator ---, but the result is 9803nevertheless known to be an integer, it is much more efficient to call 9804\tet{QXQ_intnorm} instead. 9805 9806\fun{GEN}{QXQ_intnorm}{GEN A, GEN B} $A$ being a \kbd{QX} and $B$ 9807being a \kbd{ZX}, returns the norm of the algebraic number $A \mod B$, 9808\emph{assuming} that the result is an integer, which is for instance the case 9809is $A\mod B$ is an algebraic integer, in particular if $A$ is a \kbd{ZX}. To 9810ensure that $B$ is a \kbd{ZX}, one may replace it by \kbd{Q\_primpart(B)} 9811(which of course does not change the norm). 9812 9813If the result is not known to be an integer, you must use \tet{QXQ_norm} 9814instead, which is slower. 9815 9816\fun{GEN}{QXQ_mul}{GEN A, GEN B, GEN T} returns the product of $A$ and $B$ 9817modulo $T$ where both $A$ and $B$ are a \kbd{QX} and $T$ is a monic \kbd{ZX}. 9818 9819\fun{GEN}{QXQ_sqr}{GEN A, GEN T} returns the square of $A$ 9820modulo $T$ where $A$ is a \kbd{QX} and $T$ is a monic \kbd{ZX}. 9821 9822\fun{GEN}{QXQ_inv}{GEN A, GEN B} returns the inverse of $A$ modulo $B$ 9823where $A$ is a \kbd{QX} and $B$ is a \kbd{ZX}. Should you need this for 9824a \kbd{QX} $B$, just use 9825\bprog 9826 QXQ_inv(A, Q_primpart(B)); 9827@eprog\noindent But in all cases where modular arithmetic modulo $B$ is 9828desired, it is much more efficient to replace $B$ by \kbd{Q\_primpart$(B)$} 9829once and for all. 9830 9831\fun{GEN}{QXQ_div}{GEN A, GEN B, GEN T} returns $A/B$ modulo $T$ 9832where $A$ and $B$ are \kbd{QX} and $T$ is a \kbd{ZX}. Use this function 9833when the result is expected to be of the same size as $B^{-1}$ mod $T$ 9834or smaller. 9835Otherwise, it will be faster to use \tet{QXQ_mul(A,QXQ_inv(B,T),T)}. 9836 9837\fun{GEN}{QXQ_charpoly}{GEN A, GEN T, long v} where \kbd{A} is a \kbd{QX} and 9838\kbd{T} is a \kbd{ZX}, returns the characteristic polynomial of \kbd{Mod(A, T)}. 9839If the result is known to be a \kbd{ZX}, then calling \kbd{ZXQ\_charpoly} will 9840be faster. 9841 9842\fun{GEN}{QXQ_powers}{GEN x, long n, GEN T} returns $[\kbd{x}^0, \dots, 9843\kbd{x}^\kbd{n}]$ as \kbd{RgXQ\_powers} would, but in a more efficient way when 9844$x$ has a huge integer denominator (we start by removing that denominator). 9845Meant to be used to precompute powers of algebraic integers in $\Q[t]/(T)$. 9846The current implementation does not require $x$ to be a \kbd{QX}: any 9847polynomial to which \kbd{Q\_remove\_denom} can be applied is fine. 9848 9849\fun{GEN}{QXQ_reverse}{GEN f, GEN T} as \kbd{RgXQ\_reverse}, assuming $f$ 9850is a \kbd{QX}. 9851 9852\fun{GEN}{QX_ZXQV_eval}{GEN f, GEN nV, GEN dV} as \kbd{RgX\_RgXQV\_eval}, 9853except that $f$ is assumed to be a \kbd{QX}, $V$ is given implicitly 9854by a numerator \kbd{nV} (\kbd{ZV}) and denominator \kbd{dV} (a positive 9855\typ{INT} or \kbd{NULL} for trivial denominator). Not memory clean, but 9856suitable for \kbd{gerepileupto}. 9857 9858\fun{GEN}{QXV_QXQ_eval}{GEN v, GEN a, GEN T} $v$ is a vector of \kbd{QX}s 9859(possibly scalars, i.e.~rational numbers, for convenience), $a$ and $T$ both 9860\kbd{QX}. Return the vector of evaluations at $a$ modulo $T$. 9861Not memory clean, nor suitable for \kbd{gerepileupto}. 9862 9863\fun{GEN}{QXX_QXQ_eval}{GEN P, GEN a, GEN T} $P(X,Y)$ is a \typ{POL} with 9864\kbd{QX} coefficients (possibly scalars, i.e.~rational numbers, for 9865convenience) , $a$ and $T$ both \kbd{QX}. Return the \kbd{QX} $P(X, a \mod 9866T)$. Not memory clean, nor suitable for \kbd{gerepileupto}. 9867 9868\subsec{\kbd{QXQX}} 9869 9870\fun{GEN}{QXQX_mul}{GEN x, GEN y, GEN T} where $T$ is a monic \kbd{ZX}. 9871 9872\fun{GEN}{QXQX_QXQ_mul}{GEN x, GEN y, GEN T} where $T$ is a monic \kbd{ZX}. 9873 9874\fun{GEN}{QXQX_sqr}{GEN x, GEN T} where $T$ is a monic \kbd{ZX} 9875 9876\fun{GEN}{QXQX_powers}{GEN x, long n, GEN T} where $T$ is a monic \kbd{ZX} 9877 9878\fun{GEN}{nfgcd}{GEN P, GEN Q, GEN T, GEN den} given $P$ and $Q$ in 9879$\Z[X,Y]$, $T$ monic irreducible in $\Z[Y]$, returns the primitive $d$ in 9880$\Z[X,Y]$ which is a gcd of $P$, $Q$ in $K[X]$, where $K$ is the number field 9881$\Q[Y]/(T)$. If not \kbd{NULL}, \kbd{den} is a multiple of the integral 9882denominator of the (monic) gcd of $P,Q$ in $K[X]$. 9883 9884\fun{GEN}{nfgcd_all}{GEN P, GEN Q, GEN T, GEN den, GEN *Pnew} as \kbd{nfgcd}. 9885If \kbd{Pnew} is not \kbd{NULL}, set \kbd{*Pnew} to a nonzero integer 9886multiple of $P/d$. If $P$ and $Q$ are both monic, then $d$ is monic and 9887\kbd{*Pnew} is exactly $P/d$. Not memory clean if the gcd is $1$ 9888(in that case \kbd{*Pnew} is set to $P$). 9889 9890\fun{GEN}{QXQX_gcd}{GEN x, GEN y, GEN T} returns the gcd of $x$ and $y$, 9891assuming that $x$ and $y$ are \kbd{QXQX}s and that $T$ is a monic \kbd{ZX}. 9892 9893\subsec{\kbd{QXQM}} 9894 9895\kbd{QXQM} are matrices of \kbd{QXQ}. All entries must be \typ{INT}, \typ{FRAC} or 9896polynomials of degree strictly less than the degree of $T$, which must be a monic 9897\kbd{ZX}. 9898 9899\fun{GEN}{QXQM_mul}{GEN x,GEN y,GEN T} returns $x*y$ mod $T$. 9900 9901\fun{GEN}{QXQM_sqr}{GEN x,GEN T} returns $x^2$ mod $T$. 9902 9903\subsec{\kbd{zx}} 9904 9905\fun{GEN}{zero_zx}{long sv} returns a zero \kbd{zx} in variable $v$. 9906 9907\fun{GEN}{polx_zx}{long sv} returns the variable $v$ as degree~1~\kbd{Flx}. 9908 9909\fun{GEN}{zx_renormalize}{GEN x, long l}, as \kbd{Flx\_renormalize}, where 9910$\kbd{l} = \kbd{lg(x)}$, in place. 9911 9912\fun{GEN}{zx_shift}{GEN T, long n} return \kbd{T} 9913multiplied by $\kbd{x}^n$, assuming $n\geq 0$. 9914 9915\fun{long}{zx_lval}{GEN f, long p} return the valuation of $f$ at $p$. 9916 9917\fun{GEN}{zx_z_divexact}{GEN x, long y} return \kbd{x/y} assuming all divisions 9918are exact. 9919 9920\subsec{\kbd{RgX}} 9921 9922\subsubsec{Tests} 9923 9924\fun{long}{RgX_degree}{GEN x, long v} $x$ being a \typ{POL} and $v \geq 0$, 9925returns the degree in $v$ of $x$. Error if $x$ is not a polynomial in $v$. 9926 9927\fun{int}{RgX_isscalar}{GEN x} return 1 if $x$ all the coefficients of 9928$x$ of degree $> 0$ are $0$ (as per \kbd{gequal0}). 9929 9930\fun{int}{RgX_is_rational}{GEN P} return 1 if the \kbd{RgX}~$P$ has only 9931rational coefficients (\typ{INT} and \typ{FRAC}), and 0 otherwise. 9932 9933\fun{int}{RgX_is_QX}{GEN P} return 1 if the \kbd{RgX}~$P$ has only 9934\typ{INT} and \typ{FRAC} coefficients, and 0 otherwise. 9935 9936\fun{int}{RgX_is_ZX}{GEN P} return 1 if the \kbd{RgX}~$P$ has only 9937\typ{INT} coefficients, and 0 otherwise. 9938 9939\fun{int}{RgX_is_monomial}{GEN x} returns 1 (true) if \kbd{x} is a nonzero 9940monomial in its main variable, 0~otherwise. 9941 9942\fun{long}{RgX_equal}{GEN x, GEN y} returns $1$ if the \typ{POL}s $x$ and $y$ 9943have the same \kbd{degpol} and their coefficients are equal (as per 9944\tet{gequal}). Variable numbers are not checked. Note that this is more 9945stringent than \kbd{gequal(x,y)}, which only checks whether $x - y$ satisfies 9946\kbd{gequal0}; in particular, they may have different apparent degrees provided 9947the extra leading terms are $0$. 9948 9949\fun{long}{RgX_equal_var}{GEN x, GEN y} returns $1$ if $x$ and $y$ 9950have the same variable number and \kbd{RgX\_equal(x,y)} is $1$. 9951 9952\subsubsec{Coefficients, blocks} 9953 9954\fun{GEN}{RgX_coeff}{GEN P, long n} return the coefficient of $x^n$ in $P$, 9955defined as \kbd{gen\_0} if $n < 0$ or $n > \kbd{degpol}(P)$. Shallow 9956function. 9957 9958\fun{int}{RgX_blocks}{GEN P, long n, long m} writes 9959$P(X)=a_0(X)+X^n*a_1(X)*X^n+\ldots+X^{n*(m-1)}\*a_{m-1}(X)$, 9960where the $a_i$ are polynomial of degree at most $n-1$ 9961(except possibly for the last one) and returns 9962$[a_0(X),a_1(X),\ldots,a_{m-1}(X)]$. Shallow function. 9963 9964\fun{void}{RgX_even_odd}{GEN p, GEN *pe, GEN *po} write $p(X) = E(X^2) + 9965X O(X^2)$ and set \kbd{*pe = E}, \kbd{*po = O}. Shallow function. 9966 9967\fun{GEN}{RgX_splitting}{GEN P, long k} write 9968$P(X)=a_0(X^k)+X\*a_1(X^k)+\ldots+X^{k-1}\*a_{k-1}(X^k)$ and return 9969$[a_0(X),a_1(X),\ldots,a_{k-1}(X)]$. Shallow function. 9970 9971\fun{GEN}{RgX_copy}{GEN x} returns (a deep copy of) $\kbd{x}$. 9972 9973\fun{GEN}{RgX_renormalize}{GEN x} remove leading terms in \kbd{x} which are 9974equal to (necessarily inexact) zeros. 9975 9976\fun{GEN}{RgX_renormalize_lg}{GEN x, long lx} as \kbd{setlg(x, lx)} 9977followed by \kbd{RgX\_renormalize(x)}. Assumes that $\kbd{lx} \leq 9978\kbd{lg(x)}$. 9979 9980\fun{GEN}{RgX_recip}{GEN P} returns the reverse of the polynomial 9981$P$, i.e. $X^{\deg P} P(1/X)$. 9982 9983\fun{GEN}{RgX_recip_shallow}{GEN P} shallow function of \tet{RgX_recip}, 9984where we further assume that $P(0)\neq 0$, so that the degree of the output 9985is the degree of $P$. 9986 9987\fun{long}{rfracrecip}{GEN *a, GEN *b} let \kbd{*a} and \kbd{*b} be such that 9988their quotient $F$ is a \typ{RFRAC} in variable $X$. Write $F(1/X) = X^v A/B$ 9989where $A$ and $B$ are coprime to $X$ and $v$ in $\Z$. Set \kbd{*a} to A, 9990\kbd{*b} to $B$ and return $v$. 9991 9992\fun{GEN}{RgX_deflate}{GEN P, long d} assuming $P$ is a polynomial of the 9993form $Q(X^d)$, return $Q$. Shallow function, not suitable for 9994\kbd{gerepileupto}. 9995 9996\fun{long}{RgX_deflate_order}{GEN P} given a nonconstant polynomial 9997$P$, returns the largest exponent $d$ such that $P$ is of the form $P(x^d)$ 9998(use \kbd{gequal0} to check whether coefficients are 0). 9999 10000\fun{long}{RgX_deflate_max}{GEN P, long *d} given a nonconstant polynomial 10001$P$, sets \kbd{d} to \kbd{RgX\_deflate\_order(P)} and 10002returns \kbd{RgX\_deflate(P,d)}. Shallow function. 10003 10004\fun{long}{rfrac_deflate_order}{GEN F} 10005as \kbd{RgX\_deflate\_order} where $F$ is a nonconstant \typ{RFRAC}. 10006 10007\fun{long}{rfrac_deflate_max}{GEN F, long *d} 10008as \kbd{RgX\_deflate\_max} where $F$ is a nonconstant \typ{RFRAC}. 10009 10010\fun{GEN}{rfrac_deflate}{GEN F, long m} 10011as \kbd{RgX\_deflate} where $F$ is a \typ{RFRAC}. 10012 10013\fun{GEN}{RgX_inflate}{GEN P, long d} return $P(X^d)$. Shallow function, not 10014suitable for \kbd{gerepileupto}. 10015 10016\fun{GEN}{RgX_rescale_to_int}{GEN x} given a polynomial $x$ with real entries 10017(\typ{INT}, \typ{FRAC} or \typ{REAL}), return a \kbd{ZX} wich is very close 10018to $D x$ for some well-chosen integer $D$. More precisely, if the input is 10019exact, $D$ is the denominator of $x$; else it is a power of $2$ chosen 10020so that all inexact entries are correctly rounded to 1 ulp. 10021 10022\subsubsec{Shifts, valuations} 10023 10024\fun{GEN}{RgX_shift}{GEN x, long n} returns $\kbd{x} * t^n$ if $n\geq 0$, 10025and $\kbd{x} \bs t^{-n}$ otherwise. 10026 10027\fun{GEN}{RgX_shift_shallow}{GEN x, long n} as \kbd{RgX\_shift}, but 10028shallow (coefficients are not copied). 10029 10030\fun{GEN}{RgX_rotate_shallow}{GEN P, long k, long p} returns $\kbd{P} * X^k 10031\pmod {X^p-1}$, assuming the degree of $P$ is strictly less than $p$, and 10032$k\geq 0$. 10033 10034\fun{void}{RgX_shift_inplace_init}{long v} $v \geq 0$, prepare for a later 10035call to \tet{RgX_shift_inplace}. Reserves $v$ words on the stack. 10036 10037\fun{GEN}{RgX_shift_inplace}{GEN x, long v} $v \geq 0$, assume that 10038\tet{RgX_shift_inplace_init}$(v)$ has been called (reserving $v$ words on the 10039stack), immediately followed by a \typ{POL} $x$. Return \kbd{RgX\_shift}$(x,v)$ 10040by shifting $x$ in place. To be used as follows 10041\bprog 10042 RgX_shift_inplace_init(v); 10043 av = avma; 10044 ... 10045 x = gerepileupto(av, ...); /* a t_POL */ 10046 return RgX_shift_inplace(x, v); 10047@eprog 10048 10049\fun{long}{RgX_valrem}{GEN P, GEN *pz} returns the valuation $v$ of the 10050\typ{POL}~\kbd{P} with respect to its main variable $X$. Check whether 10051coefficients are $0$ using \kbd{isexactzero}. Set \kbd{*pz} to 10052$\kbd{RgX\_shift\_shallow}(P,-v)$. 10053 10054\fun{long}{RgX_val}{GEN P} returns the valuation $v$ of the 10055\typ{POL}~\kbd{P} with respect to its main variable $X$. Check whether 10056coefficients are $0$ using \kbd{isexactzero}. 10057 10058\fun{long}{RgX_valrem_inexact}{GEN P, GEN *z} as \kbd{RgX\_valrem}, using 10059\kbd{gequal0} instead of \kbd{isexactzero}. 10060 10061\fun{long}{RgXV_maxdegree}{GEN V} returns the maximum of the degrees of 10062the components of the vector of \typ{POL}s $V$. 10063 10064\subsubsec{Basic arithmetic} 10065 10066\fun{GEN}{RgX_add}{GEN x,GEN y} adds \kbd{x} and \kbd{y}. 10067 10068\fun{GEN}{RgX_sub}{GEN x,GEN y} subtracts \kbd{x} and \kbd{y}. 10069 10070\fun{GEN}{RgX_neg}{GEN x} returns $-\kbd{x}$. 10071 10072\fun{GEN}{RgX_Rg_add}{GEN y, GEN x} returns $x+y$. 10073 10074\fun{GEN}{RgX_Rg_add_shallow}{GEN y, GEN x} returns $x+y$; shallow function. 10075 10076\fun{GEN}{Rg_RgX_sub}{GEN x, GEN y} 10077 10078\fun{GEN}{RgX_Rg_sub}{GEN y, GEN x} returns $x-y$ 10079 10080\fun{GEN}{RgX_Rg_mul}{GEN y, GEN x} multiplies the \kbd{RgX} \kbd{y} 10081by the scalar \kbd{x}. 10082 10083\fun{GEN}{RgX_muls}{GEN y, long s} multiplies the \kbd{RgX} \kbd{y} 10084by the \kbd{long}~\kbd{s}. 10085 10086\fun{GEN}{RgX_Rg_div}{GEN y, GEN x} divides the \kbd{RgX} \kbd{y} 10087by the scalar \kbd{x}. 10088 10089\fun{GEN}{RgX_divs}{GEN y, long s} divides the \kbd{RgX} \kbd{y} 10090by the \kbd{long}~\kbd{s}. 10091 10092\fun{GEN}{RgX_Rg_divexact}{GEN x, GEN y} exact division of the \kbd{RgX} 10093\kbd{y} by the scalar \kbd{x}. 10094 10095\fun{GEN}{RgX_Rg_eval_bk}{GEN f, GEN x} returns $\kbd{f}(\kbd{x})$ using 10096Brent and Kung algorithm. (Use \tet{poleval} for Horner algorithm.) 10097 10098\fun{GEN}{RgX_RgV_eval}{GEN f, GEN V} as \kbd{RgX\_Rg\_eval\_bk(f, x)}, 10099assuming $V$ was output by \kbd{gpowers(x, n)} for some $n\geq 1$. 10100 10101\fun{GEN}{RgXV_RgV_eval}{GEN f, GEN V} apply \kbd{RgX\_RgV\_eval\_bk(, V)} 10102to all the components of the vector $f$. 10103 10104\fun{GEN}{RgX_normalize}{GEN x} divides $x$ by its 10105leading coefficient. If the latter is~$1$, $x$ itself is returned, not a 10106copy. Leading coefficients equal to $0$ are stripped, e.g. 10107\bprog 10108 0.*t^3 + Mod(0,3)*t^2 + 2*t 10109@eprog\noindent is normalized to $t$. 10110 10111\fun{GEN}{RgX_mul}{GEN x, GEN y} multiplies the two \typ{POL} (in the same 10112variable) \kbd{x} and \kbd{y}. Detect the coefficient ring and use an 10113appropriate algorithm. 10114 10115\fun{GEN}{RgX_mul_i}{GEN x, GEN y} multiplies the two \typ{POL} (in the same 10116variable) \kbd{x} and \kbd{y}. Do not detect the coefficient ring. 10117Use a generic Karatsuba algorithm. 10118 10119\fun{GEN}{RgX_mul_normalized}{GEN A, long a, GEN B, long b} 10120returns $(X^a + A)(X^b + B) - X^(a+b)$, where we assume that $\deg A < a$ 10121and $\deg B < b$ are polynomials in the same variable $X$. 10122 10123\fun{GEN}{RgX_sqr}{GEN x} squares the \typ{POL} \kbd{x}. Detect the coefficient 10124ring and use an appropriate algorithm. 10125 10126\fun{GEN}{RgX_sqr_i}{GEN x} squares the \typ{POL} \kbd{x}. Do not detect the 10127coefficient ring. Use a generic Karatsuba algorithm. 10128 10129\fun{GEN}{RgX_divrem}{GEN x, GEN y, GEN *r} by default, returns the Euclidean 10130quotient and store the remainder in $r$. Three special values of $r$ change 10131that behavior 10132\item \kbd{NULL}: do not store the remainder, used to implement \kbd{RgX\_div}, 10133 10134\item \tet{ONLY_REM}: return the remainder, used to implement \kbd{RgX\_rem}, 10135 10136\item \tet{ONLY_DIVIDES}: return the quotient if the division is exact, and 10137\kbd{NULL} otherwise. 10138 10139\fun{GEN}{RgX_div}{GEN x, GEN y} 10140 10141\fun{GEN}{RgX_div_by_X_x}{GEN A, GEN a, GEN *r} returns the 10142quotient of the \kbd{RgX}~\kbd{A} by $(X - \kbd{a})$, and sets \kbd{r} to the 10143remainder $\kbd{A}(\kbd{a})$. 10144 10145\fun{GEN}{RgX_rem}{GEN x, GEN y} 10146 10147\fun{GEN}{RgX_pseudodivrem}{GEN x, GEN y, GEN *ptr} compute a pseudo-quotient 10148$q$ and pseudo-remainder $r$ such that $\kbd{lc}(y)^{\deg(x) - \deg(y) + 1}x 10149= qy + r$. Return $q$ and set \kbd{*ptr} to $r$. 10150 10151\fun{GEN}{RgX_pseudorem}{GEN x, GEN y} return the remainder 10152in the pseudo-division of $x$ by $y$. 10153 10154\fun{GEN}{RgXQX_pseudorem}{GEN x, GEN y, GEN T} return the remainder 10155in the pseudo-division of $x$ by $y$ over $R[X]/(T)$. 10156 10157\fun{int}{ZXQX_dvd}{GEN x, GEN y, GEN T} let $T$ be a monic irreducible 10158\kbd{ZX}, let $x, y$ be \typ{POL} whose coefficients are either \typ{INT}s or 10159\kbd{ZX} in the same variable as $T$. Assume further that the leading 10160coefficient of $y$ is an integer. Return $1$ if $y | x$ in $(\Z[Y]/(T))[X]$, 10161and $0$ otherwise. 10162 10163\fun{GEN}{RgXQX_pseudodivrem}{GEN x, GEN y, GEN T, GEN *ptr} compute 10164a pseudo-quotient $q$ and pseudo-remainder $r$ such that 10165$\kbd{lc}(y)^{\deg(x) - \deg(y) + 1}x = qy + r$ in $R[X]/(T)$. Return $q$ and 10166set \kbd{*ptr} to $r$. 10167 10168\fun{GEN}{RgX_mulXn}{GEN a, long n} returns $a * X^n$. This may 10169be a \typ{FRAC} if $n < 0$ and the valuation of $a$ is not large 10170enough. 10171 10172\fun{GEN}{RgX_addmulXn}{GEN a, GEN b, long n} returns $a + b * X^n$, assuming 10173that $n > 0$. 10174 10175\fun{GEN}{RgX_addmulXn_shallow}{GEN a, GEN b, long n} shallow 10176variant of \tet{RgX_addmulXn}. 10177 10178\fun{GEN}{RgX_digits}{GEN x, GEN B} returns a vector of \kbd{RgX} 10179$[c_0,\ldots,c_n]$ of degree less than the degree of $B$ and such that 10180$x=\sum_{i=0}^{n}{c_i\*B^i}$. 10181 10182\subsubsec{Internal routines working on coefficient arrays} 10183 10184These routines operate on coefficient blocks which are invalid \kbd{GEN}s 10185A \kbd{GEN} argument $a$ or $b$ in routines below is actually a coefficient 10186arrays representing the polynomials 10187 $\sum_{i = 0}^{\kbd{na-1}} a[i] X^i$ and 10188 $\sum_{i = 0}^{\kbd{nb-1}} b[i] X^i$. Note that $a[0]$ and $b[0]$ contain 10189coefficients and not the mandatory \kbd{GEN} codeword. This allows to implement 10190divide-and-conquer methods directly, without needing to allocate wrappers 10191around coefficient blocks. 10192 10193\fun{GEN}{RgX_mulspec}{GEN a, GEN b, long na, long nb}. Internal routine: 10194given two coefficient arrays representing polynomials, return their product (as 10195a true \kbd{GEN}) in variable $0$. 10196 10197\fun{GEN}{RgX_sqrspec}{GEN a, long na}. Internal routine: 10198given a coefficient array representing a polynomial r eturn its square (as a 10199true \kbd{GEN}) in variable $0$. 10200 10201\fun{GEN}{RgX_addspec}{GEN x, GEN y, long nx, long ny} 10202given two coefficient arrays representing polynomials, return their sum (as a 10203true \kbd{GEN}) in variable $0$. 10204 10205\fun{GEN}{RgX_addspec_shallow}{GEN x, GEN y, long nx, long ny} shallow 10206variant of \tet{RgX_addspec}. 10207 10208\subsubsec{GCD, Resultant} 10209 10210\fun{GEN}{RgX_gcd}{GEN x, GEN y} returns the GCD of \kbd{x} and \kbd{y}, 10211assumed to be \typ{POL}s in the same variable. 10212 10213\fun{GEN}{RgX_gcd_simple}{GEN x, GEN y} as \tet{RgX_gcd} using a standard 10214extended Euclidean algorithm. Usually slower than \tet{RgX_gcd}. 10215 10216\fun{GEN}{RgX_extgcd}{GEN x, GEN y, GEN *u, GEN *v} returns 10217$d = \text{GCD}(\kbd{x},\kbd{y})$, and sets \kbd{*u}, \kbd{*v} to the Bezout 10218coefficients such that $\kbd{*ux} + \kbd{*vy} = d$. Uses a generic 10219subresultant algorithm. 10220 10221\fun{GEN}{RgX_extgcd_simple}{GEN x, GEN y, GEN *u, GEN *v} as 10222\tet{RgX_extgcd} using a standard extended Euclidean algorithm. Usually 10223slower than \tet{RgX_extgcd}. 10224 10225\fun{GEN}{RgX_halfgcd}{GEN x, GEN y} 10226assuming \kbd{x} and \kbd{y} are \typ{POL}s in the same variable, 10227returns a $2$-components \typ{VEC} $[M,V]$ where $M$ is a $2\times 2$ 10228\typ{MAT} and $V$ a $2$-component \typ{COL}, both with \typ{POL} entries, 10229such that $M*[x,y]~==V$ and such that f $V=[a,b]~$, then 10230$\deg a \geq \ceil{\max(\deg x,\deg y))/2} > \deg b$. 10231 10232\fun{GEN}{RgX_disc}{GEN x} returns the discriminant of the \typ{POL} \kbd{x} 10233with respect to its main variable. 10234 10235\fun{GEN}{RgX_resultant_all}{GEN x, GEN y, GEN *sol} returns 10236\kbd{resultant(x,y)}. If \kbd{sol} is not \kbd{NULL}, sets it to the last 10237nonconstant remainder in the polynomial remainder sequence if it exists and to 10238\kbd{gen\_0} otherwise (e.g. one polynomial has degree 0). 10239 10240\subsubsec{Other operations} 10241 10242\fun{GEN}{RgX_gtofp}{GEN x, GEN prec} returns the polynomial obtained by 10243applying 10244\bprog 10245 gtofp(gel(x,i), prec) 10246@eprog\noindent to all coefficients of $x$. 10247 10248\fun{GEN}{RgX_fpnorml2}{GEN x, long prec} returns (a stack-clean variant of) 10249\bprog 10250 gnorml2( RgX_gtofp(x, prec) ) 10251@eprog 10252 10253\fun{GEN}{RgX_deriv}{GEN x} returns the derivative of \kbd{x} with respect to 10254its main variable. 10255 10256\fun{GEN}{RgX_integ}{GEN x} returns the primitive of \kbd{x} vanishing at 10257$0$, with respect to its main variable. 10258 10259\fun{GEN}{RgX_rescale}{GEN P, GEN h} returns $h^{\deg(P)} P(x/h)$. 10260\kbd{P} is an \kbd{RgX} and \kbd{h} is nonzero. (Leaves small objects on the 10261stack. Suitable but inefficient for \kbd{gerepileupto}.) 10262 10263\fun{GEN}{RgX_unscale}{GEN P, GEN h} returns $P(h x)$. (Leaves small objects 10264on the stack. Suitable but inefficient for \kbd{gerepileupto}.) 10265 10266\fun{GEN}{RgXV_unscale}{GEN v, GEN h} apply \kbd{RgX\_unscale} to a vector 10267of \kbd{RgX}. 10268 10269\fun{GEN}{RgX_translate}{GEN P, GEN c} assume $c$ is a scalar or 10270a polynomials whose main variable has lower priority than the main variable 10271$X$ of $P$. Returns $P(X + c)$ (optimized for $c = \pm 1$). 10272 10273\subsubsec{Function related to modular forms} 10274 10275\fun{GEN}{RgX_act_Gl2Q}{GEN g, long k} let $R$ be a commutative ring 10276and $g = [a,b;c,d]$ be in $\text{GL}_2(\Q)$, $g$ acts (on the left) 10277on homogeneous polynomials of degree $k-2$ in $V := R[X,Y]_{k-2}$ via 10278$$ g\cdot P := P(dX-cY, -bX+aY) = (\det g)^{k-2} P((X,Y)\cdot g^{-1}).$$ 10279This function returns the matrix in $M_{k-1}(R)$ of $P\mapsto g\cdot P$ in 10280the basis $(X^{k-2},\dots,Y^{k-2})$ of $V$. 10281 10282\fun{GEN}{RgX_act_ZGl2Q}{GEN z, long k} let $G:=\text{GL}_2(\Q)$, acting 10283on $R[X,Y]_{k-2}$ and $z\in \Z[G]$. Return the matrix giving 10284$P\mapsto z\cdot P$ in the basis $(X^{k-2},\dots,Y^{k-2})$. 10285 10286\subsec{\kbd{RgXn}} 10287 10288\fun{GEN}{RgXn_red_shallow}{GEN x, long n} return $\kbd{x \% } t^n$, 10289where $n\geq 0$. Shallow function. 10290 10291\fun{GEN}{RgXn_recip_shallow}{GEN P} returns $X^n\*P(1/X)$. Shallow function. 10292 10293\fun{GEN}{RgXn_mul}{GEN a, GEN b, long n} returns $a b$ modulo $X^n$, 10294where $a,b$ are two \typ{POL} in the same variable $X$ and $n \geq 0$. Uses 10295Karatsuba algorithm (Mulders, Hanrot-Zimmermann variant). 10296 10297\fun{GEN}{RgXn_sqr}{GEN a, long n} returns $a^2$ modulo $X^n$, 10298where $a$ is a \typ{POL} in the variable $X$ and $n \geq 0$. Uses 10299Karatsuba algorithm (Mulders, Hanrot-Zimmermann variant). 10300 10301\fun{GEN}{RgX_mulhigh_i}{GEN f, GEN g, long n} return the Euclidean quotient 10302of $f(x)*g(x)$ by $x^n$ (high product). Uses \tet{RgXn_mul} applied to 10303the reciprocal polynomials of $f$ and $g$. Not suitable for \kbd{gerepile}. 10304 10305\fun{GEN}{RgX_sqrhigh_i}{GEN f, long n} return the Euclidean quotient 10306of $f(x)^2$ by $x^n$ (high product). Uses \tet{RgXn_sqr} applied to 10307the reciprocal polynomial of $f$. Not suitable for \kbd{gerepile}. 10308 10309\fun{GEN}{RgXn_inv}{GEN a, long n} returns $a^{-1}$ modulo $X^n$, 10310where $a$ is a \typ{POL} in the variable $X$ and $n \geq 0$. Uses 10311Newton-Raphson algorithm. 10312 10313\fun{GEN}{RgXn_inv_i}{GEN a, long n} as \tet{RgXn_inv} without final garbage 10314collection (suitable for \kbd{gerepileupto}). 10315 10316\fun{GEN}{RgXn_powers}{GEN x, long m, long n} returns $[\kbd{x}^0, 10317\dots, \kbd{x}^\kbd{m}]$ modulo $X^n$ as a \typ{VEC} of \kbd{RgXn}s. 10318 10319\fun{GEN}{RgXn_powu}{GEN x, ulong m, long n} returns $x^m$ modulo 10320$X^n$. 10321 10322\fun{GEN}{RgXn_powu_i}{GEN x, ulong m, long n} as \tet{RgXn_powu}, 10323not memory clean. 10324 10325\fun{GEN}{RgXn_sqrt}{GEN a, long n} returns $a^{1/2}$ modulo $X^n$, 10326where $a$ is a \typ{POL} in the variable $X$ and $n \geq 0$. 10327Assume that $a = 1 \mod{X}$. Uses Newton algorithm. 10328 10329\fun{GEN}{RgXn_exp}{GEN a, long n} returns $exp(a)$ modulo $X^n$, assuming 10330$a = 0 \mod{X}$. 10331 10332\fun{GEN}{RgXn_expint}{GEN f, long n} return $\exp(F)$ 10333where $F$ is the primitive of $f$ that vanishes at $0$. 10334 10335\fun{GEN}{RgXn_eval}{GEN Q, GEN x, long n} special case of 10336\tet{RgX_RgXQ_eval}, when the modulus is a monomial: 10337returns $\kbd{Q}(\kbd{x})$ modulo $t^n$, where $x \in R[t]$. 10338 10339\fun{GEN}{RgX_RgXn_eval}{GEN f, GEN x, long n} returns $\kbd{f}(\kbd{x})$ modulo 10340$X^n$. 10341 10342\fun{GEN}{RgX_RgXnV_eval}{GEN f, GEN V, long n} as \kbd{RgX\_RgXn\_eval(f, x, n)}, 10343assuming $V$ was output by \kbd{RgXn\_powers(x, m, n)} for some $m\geq 1$. 10344 10345\fun{GEN}{RgXn_reverse}{GEN f, long n} assuming that $f = a\*x \mod{x^2}$ 10346with $a$ invertible, returns a \typ{POL} $g$ of degree $< n$ such that $(g 10347\circ f)(x) = x$ modulo $x^n$. 10348 10349\subsec{\kbd{RgXnV}} 10350 10351\fun{GEN}{RgXnV_red_shallow}{GEN x, long n} apply \kbd{RgXn\_red\_shallow} 10352to all the components of the vector $x$. 10353 10354\subsec{\kbd{RgXQ}} 10355 10356\fun{GEN}{RgXQ_mul}{GEN y, GEN x, GEN T} computes $xy$ mod $T$ 10357 10358\fun{GEN}{RgXQ_sqr}{GEN x, GEN T} computes $x^2$ mod $T$ 10359 10360\fun{GEN}{RgXQ_inv}{GEN x, GEN T} return the inverse of $x$ mod $T$. 10361 10362\fun{GEN}{RgXQ_pow}{GEN x, GEN n, GEN T} computes $x^n$ mod $T$ 10363 10364\fun{GEN}{RgXQ_powu}{GEN x, ulong n, GEN T} computes $x^n$ mod $T$, 10365$n$ being an \kbd{ulong}. 10366 10367\fun{GEN}{RgXQ_powers}{GEN x, long n, GEN T} returns $[\kbd{x}^0, 10368\dots, \kbd{x}^\kbd{n}]$ as a \typ{VEC} of \kbd{RgXQ}s. 10369 10370\fun{GEN}{RgXQ_matrix_pow}{GEN y, long n, long m, GEN P} returns 10371\kbd{RgXQ\_powers(y,m-1,P)}, as a matrix of dimension $n \geq \deg P$. 10372 10373\fun{GEN}{RgXQ_norm}{GEN x, GEN T} returns the norm of \kbd{Mod(x, T)}. 10374 10375\fun{GEN}{RgXQ_charpoly}{GEN x, GEN T, long v} returns the characteristic 10376polynomial of \kbd{Mod(x, T)}, in variable $v$. 10377 10378\fun{GEN}{RgX_RgXQ_eval}{GEN f, GEN x, GEN T} returns $\kbd{f}(\kbd{x})$ modulo 10379$T$. 10380 10381\fun{GEN}{RgX_RgXQV_eval}{GEN f, GEN V, GEN T} as \kbd{RgX\_RgXQ\_eval(f, x, T)}, 10382assuming $V$ was output by \kbd{RgXQ\_powers(x, n, T)} for some $n\geq 1$. 10383 10384\fun{int}{RgXQ_ratlift}{GEN x, GEN T, long amax, long bmax, GEN *P, GEN *Q} 10385Assuming that $\kbd{amax}+\kbd{bmax}<\deg T$, attempts to recognize $x$ as a 10386rational function $a/b$, i.e. to find \typ{POL}s $P$ and $Q$ such that 10387 10388\item $P \equiv Q x$ modulo $T$, 10389 10390\item $\deg P \leq \kbd{amax}$, $\deg Q \leq \kbd{bmax}$, 10391 10392\item $\gcd(T,P) = \gcd(P,Q)$. 10393 10394\noindent If unsuccessful, the routine returns $0$ and leaves $P$, $Q$ 10395unchanged; otherwise it returns $1$ and sets $P$ and $Q$. 10396 10397\fun{GEN}{RgXQ_reverse}{GEN f, GEN T} returns a \typ{POL} $g$ of degree $< n 10398= \text{deg}~T$ such that $T(x)$ divides $(g \circ f)(x) - x$, by solving a 10399linear system. Low-level function underlying \tet{modreverse}: it returns a 10400lift of \kbd[modreverse(f,T)]; faster than the high-level function since it 10401needs not compute the characteristic polynomial of $f$ mod $T$ (often already 10402known in applications). In the trivial case where $n \leq 1$, returns a 10403scalar, not a constant \typ{POL}. 10404 10405\subsec{\kbd{RgXQV, RgXQC}} 10406 10407\fun{GEN}{RgXQC_red}{GEN z, GEN T} \kbd{z} a vector whose 10408coefficients are \kbd{RgX}s (arbitrary \kbd{GEN}s in fact), reduce them to 10409\kbd{RgXQ}s (applying \kbd{grem} coefficientwise) in a \typ{COL}. 10410 10411\fun{GEN}{RgXQV_red}{GEN z, GEN T} \kbd{z} a vector whose 10412coefficients are \kbd{RgX}s (arbitrary \kbd{GEN}s in fact), reduce them to 10413\kbd{RgXQ}s (applying \kbd{grem} coefficientwise) in a \typ{VEC}. 10414 10415\fun{GEN}{RgXQV_RgXQ_mul}{GEN z, GEN x, GEN T} \kbd{z} multiplies the 10416 \kbd{RgXQV} \kbd{z} by the scalar (\kbd{RgXQ}) \kbd{x}. 10417 10418\subsec{\kbd{RgXQM}} 10419 10420\fun{GEN}{RgXQM_red}{GEN z, GEN T} \kbd{z} a matrix whose 10421coefficients are \kbd{RgX}s (arbitrary \kbd{GEN}s in fact), reduce them to 10422\kbd{RgXQ}s (applying \kbd{grem} coefficientwise). 10423 10424\fun{GEN}{RgXQM_mul}{GEN x, GEN y, GEN T} 10425 10426\subsec{\kbd{RgXQX}} 10427 10428\fun{GEN}{RgXQX_red}{GEN z, GEN T} \kbd{z} a \typ{POL} whose 10429coefficients are \kbd{RgX}s (arbitrary \kbd{GEN}s in fact), reduce them to 10430\kbd{RgXQ}s (applying \kbd{grem} coefficientwise). 10431 10432\fun{GEN}{RgXQX_mul}{GEN x, GEN y, GEN T} 10433 10434\fun{GEN}{RgXQX_RgXQ_mul}{GEN x, GEN y, GEN T} multiplies the \kbd{RgXQX} 10435\kbd{y} by the scalar (\kbd{RgXQ}) \kbd{x}. 10436 10437\fun{GEN}{RgXQX_sqr}{GEN x, GEN T} 10438 10439\fun{GEN}{RgXQX_powers}{GEN x, long n, GEN T} 10440 10441\fun{GEN}{RgXQX_divrem}{GEN x, GEN y, GEN T, GEN *pr} 10442 10443\fun{GEN}{RgXQX_div}{GEN x, GEN y, GEN T} 10444 10445\fun{GEN}{RgXQX_rem}{GEN x, GEN y, GEN T} 10446 10447\fun{GEN}{RgXQX_translate}{GEN P, GEN c, GEN T} assume the main variable 10448$X$ of $P$ has higher priority than the main variable $Y$ of $T$ and $c$. 10449Return a lift of $P(X+\text{Mod}(c(Y), T(Y)))$. 10450 10451\fun{GEN}{Kronecker_to_mod}{GEN z, GEN T} $z\in R[X]$ represents an element 10452$P(X,Y)$ in $R[X,Y]$ mod $T(Y)$ in Kronecker form, i.e. $z = P(X,X^{2*n-1})$ 10453 10454Let $R$ be some commutative ring, $n = \deg T$ and let $P(X,Y)\in R[X,Y]$ lift 10455a polynomial in $K[Y]$, where $K := R[X]/(T)$ and $\deg_X P < 2n-1$ --- such as 10456would result from multiplying minimal degree lifts of two polynomials in 10457$K[Y]$. Let $z = P(t,t^{2*n-1})$ be a Kronecker form of $P$, this function 10458returns the image of $P(X,t)$ in $K[t]$, with \typ{POLMOD} coefficients. 10459Not stack-clean. Note that $t$ need not be the same variable as $Y$! 10460 10461\chapter{Black box algebraic structures} 10462 10463The generic routines like \kbd{gmul} or \kbd{gadd} allow handling objects 10464belonging to a fixed list of basic types, with some natural polymorphism 10465(you can mix rational numbers and polynomials, etc.), at the expense of 10466efficiency and sometimes of clarity when the recursive structure becomes 10467complicated, e.g. a few levels of \typ{POLMOD}s attached to different 10468polynomials and variable numbers for quotient structures. This 10469is the only possibility in GP. 10470 10471On the other hand, the Level 2 Kernel allows dedicated routines to handle 10472efficiently objects of a very specific type, e.g. polynomials with 10473coefficients in the same finite field. This is more efficient, but imvolves a 10474lot of code duplication since polymorphism is no longer possible. 10475 10476A third and final option, still restricted to library programming, is to 10477define an arbitrary algebraic structure (currently groups, fields, rings, 10478algebras and $\Z_p$-modules) by providing suitable methods, then using generic 10479algorithms. For instance naive Gaussian pivoting applies over all base fields 10480and need only be implemented once. The difference with the first solution 10481is that we no longer depend on the way functions like \kbd{gmul} or 10482\kbd{gadd} will guess what the user is trying to do. We can then implement 10483independently various groups / fields / algebras in a clean way. 10484 10485\section{Black box groups} 10486 10487A black box group is defined by a \tet{bb_group} struct, describing methods 10488available to handle group elements: 10489\bprog 10490 struct bb_group 10491 { 10492 GEN (*mul)(void*, GEN, GEN); 10493 GEN (*pow)(void*, GEN, GEN); 10494 GEN (*rand)(void*); 10495 ulong (*hash)(GEN); 10496 int (*equal)(GEN, GEN); 10497 int (*equal1)(GEN); 10498 GEN (*easylog)(void *E, GEN, GEN, GEN); 10499 }; 10500@eprog 10501\kbd{mul(E,x,y)} returns the product $x\*y$. 10502 10503\kbd{pow(E,x,n)} returns $x^n$ ($n$ integer, possibly negative or zero). 10504 10505\kbd{rand(E)} returns a random element in the group. 10506 10507\kbd{hash(x)} returns a hash value for $x$ (\kbd{hash\_GEN} is suitable for this field). 10508 10509\kbd{equal(x,y)} returns one if $x=y$ and zero otherwise. 10510 10511\kbd{equal1(x)} returns one if $x$ is the neutral element in the group, 10512and zero otherwise. 10513 10514\kbd{easylog(E,a,g,o)} (optional) returns either NULL or the discrete logarithm 10515$n$ such that $g^n=a$, the element $g$ being of order $o$. This provides a 10516short-cut in situation where a better algorithm than the generic one is known. 10517 10518A group is thus described by a \kbd{struct bb\_group} as above and auxiliary 10519data typecast to \kbd{void*}. The following functions operate on black box 10520groups: 10521 10522\fun{GEN}{gen_Shanks_log}{GEN x, GEN g, GEN N, void *E, const struct bb_group 10523*grp} \hbadness 10000\break 10524Generic baby-step/giant-step algorithm (Shanks's method). Assuming 10525that $g$ has order $N$, compute an integer $k$ such that $g^k = x$. 10526Return \kbd{cgetg(1, t\_VEC)} if there are no solutions. This requires 10527$O(\sqrt{N})$ group operations and uses an auxiliary table containing 10528$O(\sqrt{N})$ group elements. 10529 10530The above is useful for a one-shot computation. If many discrete logs 10531are desired: 10532\fun{GEN}{gen_Shanks_init}{GEN g, long n, void *E, const struct bb_group *grp} 10533return an auxiliary data structure $T$ required to compute a discrete log in 10534base $g$. Compute and store all powers $g^i$, $i < n$. 10535 10536\fun{GEN}{gen_Shanks}{GEN T, GEN x, ulong N, void *E, const struct bb_group *grp} 10537Let $T$ be computed by \tet{gen_Shanks_init}$(g,n,\dots)$. 10538Return $k < n N$ such that $g^k = x$ or \kbd{NULL} if no such index exist. 10539It uses $O(N)$ operation in the group and fast table lookups (in time 10540$O(\log n)$). The interface is such that the function may be used when the 10541order of the base $g$ is unknown, and hence compute it given only an upper 10542bound $B$ for it: e.g. choose $n,N$ such that $nN \geq B$ and compute the 10543discrete log $l$ of $g^{-1}$ in base $g$, then use \tet{gen_order} 10544with multiple $N = l+1$. 10545 10546\fun{GEN}{gen_Pollard_log}{GEN x, GEN g, GEN N, void *E, const struct bb_group 10547*grp} \hbadness 10000\break 10548Generic Pollard rho algorithm. Assuming that $g$ has order $N$, compute an 10549integer $k$ such that $g^k = x$. This requires $O(\sqrt{N})$ group operations 10550in average and $O(1)$ storage. Will enter an infinite loop if there are no 10551solutions. 10552 10553\fun{GEN}{gen_plog}{GEN x, GEN g, GEN N, void *E, const struct bb_group} 10554Assuming that $g$ has prime order $N$, compute an integer $k$ such that 10555$g^k = x$, using either \kbd{gen\_Shanks\_log} or \kbd{gen\_Pollard\_log}. 10556Return \kbd{cgetg(1, t\_VEC)} if there are no solutions. 10557 10558\fun{GEN}{gen_Shanks_sqrtn}{GEN a, GEN n, GEN N, GEN *zetan, void *E, const 10559struct bb_group *grp} \hbadness 10000 returns one solution of $x^n = a$ in a 10560black box cyclic group of order $N$. Return \kbd{NULL} if no solution exists. 10561If \kbd{zetan} is not \kbd{NULL} it is set to an element of exact order $n$. 10562This function uses \kbd{gen\_plog} for all prime divisors of $\gcd(n,N)$. 10563 10564\fun{GEN}{gen_PH_log}{GEN a, GEN g, GEN N, void *E, const struct bb_group *grp} 10565returns an integer $k$ such that $g^k = x$, assuming that the order of $g$ 10566divides $N$, using Pohlig-Hellman algorithm. Return \kbd{cgetg(1, t\_VEC)} if 10567there are no solutions. This calls \tet{gen_plog} repeatedly for all prime 10568divisors $p$ of $N$. 10569 10570In the following functions the integer parameter \kbd{ord} can be given 10571in all the formats recognized for the argument of arithmetic functions, 10572i.e.~either as a positive \typ{INT} $N$, or as its factorization matrix 10573$\var{faN}$, or (preferred) as a pair $[N,\var{faN}]$. 10574 10575\fun{GEN}{gen_order}{GEN x, GEN ord, void *E, const struct bb_group *grp} 10576computes the order of $x$; \kbd{ord} is a multiple of the order, for instance 10577the group order. 10578 10579\fun{GEN}{gen_factored_order}{GEN x, GEN ord, void *E, const struct bb_group 10580*grp} returns a pair $[o,F]$, where $o$ is the order of $x$ and $F$ is the 10581factorization of $o$; \kbd{ord} is as in \tet{gen_order}. 10582 10583\fun{GEN}{gen_gener}{GEN ord, void *E, const struct bb_group *grp} 10584returns a random generator of the group, assuming it is of order exactly 10585\kbd{ord}. 10586 10587\fun{GEN}{get_arith_Z}{GEN ord} given \kbd{ord} as above in one of the 10588formats recognized for arithmetic functions, i.e. a positive 10589\typ{INT} $N$, its factorization \var{faN}, or the pair $[N, \var{faN}]$, 10590return $N$. 10591 10592\fun{GEN}{get_arith_ZZM}{GEN ord} given \kbd{ord} as above, 10593return the pair $[N, \var{faN}]$. This may require factoring $N$. 10594 10595\fun{GEN}{gen_select_order}{GEN v, void *E, const struct bb_group *grp} 10596Let $v$ be a vector of possible orders for the group; try to find the true 10597order by checking orders of random points. This will not terminate if there 10598is an ambiguity. 10599 10600\subsec{Black box groups with pairing} 10601 10602These functions handle groups of rank at most $2$ equipped with a family of 10603bilinear pairings which behave like the Weil pairing on elliptic curves over 10604finite field. In the descriptions below, the function \kbd{pairorder(E, P, Q, 10605m, F)} must return the order of the $m$-pairing of $P$ and $Q$, both of order 10606dividing $m$, where $F$ is the factorization matrix of a multiple of $m$. 10607 10608\fun{GEN}{gen_ellgroup}{GEN o, GEN d, GEN *pt_m, void *E, const struct bb_group *grp, 10609 GEN pairorder(void *E, GEN P, GEN Q, GEN m, GEN F)} 10610returns the elementary divisors $[d_1, d_2]$ of the group, assuming it is of 10611order exactly $o>1$, and that $d_2$ divides $d$. If $d_2=1$ then $[o]$ is 10612returned, otherwise \kbd{m=*pt\_m} is set to the order of the pairing 10613required to verify a generating set which is to be used with 10614\kbd{gen\_ellgens}. For the parameter $o$, all formats recognized by 10615arithmetic functions are allowed, preferably a factorization matrix or a pair 10616$[n,\kbd{factor}(n)]$. 10617 10618\fun{GEN}{gen_ellgens}{GEN d1, GEN d2, GEN m, void *E, const struct bb_group *grp, 10619 GEN pairorder(void *E, GEN P, GEN Q, GEN m, GEN F)} 10620the parameters $d_1$, $d_2$, $m$ being as returned by \kbd{gen\_ellgroup}, 10621returns a pair of generators $[P,Q]$ such that $P$ is of order $d_1$ and the 10622$m$-pairing of $P$ and $Q$ is of order $m$. (Note: $Q$ needs not be of order 10623$d_2$). For the parameter $d_1$, all formats recognized by arithmetic 10624functions are allowed, preferably a factorization matrix or a pair 10625$[n,\kbd{factor}(n)]$. 10626 10627\subsec{Functions returning black box groups} 10628 10629\fun{const struct bb_group *}{get_Flxq_star}{void **E, GEN T, ulong p} 10630 10631\fun{const struct bb_group *}{get_FpXQ_star}{void **E, GEN T, GEN p} 10632returns a pointer to the black box group $(\F_p[x]/(T))^*$. 10633 10634\fun{const struct bb_group *}{get_FpE_group}{void **pE, GEN a4, GEN a6, GEN p} 10635returns a pointer to a black box group and set \kbd{*pE} to the necessary data for 10636computing in the group $E(\F_p)$ where $E$ is the elliptic curve $E:y^2=x^3+a_4\*x+a_6$, 10637with $a_4$ and $a_6$ in $\F_p$. 10638 10639\fun{const struct bb_group *}{get_FpXQE_group}{void **pE, GEN a4, GEN a6, GEN T, GEN p} 10640returns a pointer to a black box group and set \kbd{*pE} to the necessary data for 10641computing in the group $E(\F_p[X]/(T))$ where $E$ is the elliptic curve $E:y^2=x^3+a_4\*x+a_6$, 10642with $a_4$ and $a_6$ in $\F_p[X]/(T)$. 10643 10644\fun{const struct bb_group *}{get_FlxqE_group}{void **pE, GEN a4, GEN a6, GEN 10645T, ulong p} idem for small $p$. 10646 10647\fun{const struct bb_group *}{get_F2xqE_group}{void **pE, GEN a2, GEN a6, GEN T} 10648idem for $p=2$. 10649 10650\section{Black box fields} 10651 10652A black box field is defined by a \tet{bb_field} struct, describing methods 10653available to handle field elements: 10654\bprog 10655 struct bb_field 10656 { 10657 GEN (*red)(void *E ,GEN); 10658 GEN (*add)(void *E ,GEN, GEN); 10659 GEN (*mul)(void *E ,GEN, GEN); 10660 GEN (*neg)(void *E ,GEN); 10661 GEN (*inv)(void *E ,GEN); 10662 int (*equal0)(GEN); 10663 GEN (*s)(void *E, long); 10664 }; 10665@eprog\noindent In contrast of black box group, elements can have 10666non canonical forms, and only \kbd{red} is required to return a canonical form. 10667For instance a black box implementation of finite fields, all methods 10668except \kbd{red} may return arbitrary representatives in $\Z[X]$ of the 10669correct congruence class modulo $(p,T(X))$. 10670 10671\kbd{red(E,x)} returns the canonical form of $x$. 10672 10673\kbd{add(E,x,y)} returns the sum $x+y$. 10674 10675\kbd{mul(E,x,y)} returns the product $x\*y$. 10676 10677\kbd{neg(E,x)} returns $-x$. 10678 10679\kbd{inv(E,x)} returns the inverse of $x$. 10680 10681\kbd{equal0(x)} $x$ being in canonical form, returns one if $x=0$ and zero 10682otherwise. 10683 10684\kbd{s(n)} $n$ being a small signed integer, returns $n$ times the unit element. 10685 10686\noindent A field is thus described by a \kbd{struct bb\_field} as above and 10687auxiliary data typecast to \kbd{void*}. The following functions operate on 10688black box fields: 10689 10690\fun{GEN}{gen_Gauss}{GEN a, GEN b, void *E, const struct bb_field *ff} 10691 10692\fun{GEN}{gen_Gauss_pivot}{GEN x, long *rr, void *E, const struct bb_field *ff} 10693 10694\fun{GEN}{gen_det}{GEN a, void *E, const struct bb_field *ff} 10695 10696\fun{GEN}{gen_ker}{GEN x, long deplin, void *E, const struct bb_field *ff} 10697 10698\fun{GEN}{gen_matcolinvimage}{GEN a, GEN b, void *E, const struct bb_field *ff} 10699 10700\fun{GEN}{gen_matcolmul}{GEN a, GEN b, void *E, const struct bb_field *ff} 10701 10702\fun{GEN}{gen_matid}{long n, void *E, const struct bb_field *ff} 10703 10704\fun{GEN}{gen_matinvimage}{GEN a, GEN b, void *E, const struct bb_field *ff} 10705 10706\fun{GEN}{gen_matmul}{GEN a, GEN b, void *E, const struct bb_field *ff} 10707 10708\subsec{Functions returning black box fields} 10709 10710\fun{const struct bb_field *}{get_Fp_field}{void **pE, GEN p} 10711 10712\fun{const struct bb_field *}{get_Fq_field}{void **pE, GEN T, GEN p} 10713 10714\fun{const struct bb_field *}{get_Flxq_field}{void **pE, GEN T, ulong p} 10715 10716\fun{const struct bb_field *}{get_F2xq_field}{void **pE, GEN T} 10717 10718\fun{const struct bb_field *}{get_nf_field}{void **pE, GEN nf} 10719 10720\section{Black box algebra} 10721 10722A black box algebra is defined by a \tet{bb_algebra} struct, describing methods 10723available to handle algebra elements: 10724\bprog 10725struct bb_algebra 10726{ 10727 GEN (*red)(void *E, GEN x); 10728 GEN (*add)(void *E, GEN x, GEN y); 10729 GEN (*sub)(void *E, GEN x, GEN y); 10730 GEN (*mul)(void *E, GEN x, GEN y); 10731 GEN (*sqr)(void *E, GEN x); 10732 GEN (*one)(void *E); 10733 GEN (*zero)(void *E); 10734}; 10735@eprog\noindent In contrast with black box groups, elements can have non 10736canonical forms, but only \kbd{add} is allowed to return a non canonical 10737form. 10738 10739\kbd{red(E,x)} returns the canonical form of $x$. 10740 10741\kbd{add(E,x,y)} returns the sum $x+y$. 10742 10743\kbd{sub(E,x,y)} returns the difference $x-y$. 10744 10745\kbd{mul(E,x,y)} returns the product $x\*y$. 10746 10747\kbd{sqr(E,x)} returns the square $x^2$. 10748 10749\kbd{one(E)} returns the unit element. 10750 10751\kbd{zero(E)} returns the zero element. 10752 10753\noindent An algebra is thus described by a \kbd{struct bb\_algebra} as above 10754and auxiliary data typecast to \kbd{void*}. The following functions operate 10755on black box algebra: 10756 10757\fun{GEN}{gen_bkeval}{GEN P, long d, GEN x, int use_sqr, void *E, 10758 const struct bb_algebra *ff, GEN cmul(void *E, GEN P, long a, GEN x)} 10759$x$ being an element of the black box algebra, and $P$ some black box 10760polynomial of degree $d$ over the base field, returns $P(x)$. The function 10761\kbd{cmul(E,P,a,y)} must return the coefficient of degree $a$ of $P$ 10762multiplied by $y$. \kbd{cmul} is allowed to return a non canonical form; 10763it is also allowed to return \kbd{NULL} instead of an exact $0$. 10764 10765The flag \kbd{use\_sqr} has the same meaning as for \kbd{gen\_powers}. This 10766implements an algorithm of Brent and Kung (1978). 10767 10768\fun{GEN}{gen_bkeval_powers}{GEN P, long d, GEN V, void *E, 10769 const struct bb_algebra *ff, GEN cmul(void *E, GEN P, long a, GEN x)} 10770as \tet{gen_RgX_bkeval} assuming $V$ was output by 10771\tet{gen_powers}$(x, l, E, \var{ff})$ for some $l\geq 1$. For optimal 10772performance, $l$ should be computed by \tet{brent_kung_optpow}. 10773 10774\fun{long}{brent_kung_optpow}{long d, long n, long m} returns the optimal 10775parameter $l$ for the evaluation of $n/m$ polynomials of degree $d$. 10776Fractional values can be used if the evaluations are done with different 10777accuracies, and thus have different weights. 10778 10779\subsec{Functions returning black box algebras} 10780 10781\fun{const struct bb_algebra *}{get_FpX_algebra}{void **E, GEN p, long v} 10782return the algebra of polynomials over $\F_p$ in variable $v$. 10783 10784\fun{const struct bb_algebra *}{get_FpXQ_algebra}{void **E, GEN T, GEN p} 10785return the algebra $\F_p[X]/(T(X))$. 10786 10787\fun{const struct bb_algebra *}{get_FpXQX_algebra}{void **E, GEN T, GEN p, long v} 10788return the algebra of polynomials over $\F_p[X]/(T(X))$ in variable $v$. 10789 10790\fun{const struct bb_algebra *}{get_FlxqXQ_algebra}{void **E, GEN S, GEN T, ulong p} 10791return the algebra $\F_p[X,Y]/(S(X,Y),T(X))$ (for \kbd{ulong} $p$). 10792 10793\fun{const struct bb_algebra *}{get_FpXQXQ_algebra}{void **E, GEN S, GEN T, GEN p} 10794return the algebra $\F_p[X,Y]/(S(X,Y),T(X))$. 10795 10796\fun{const struct bb_algebra *}{get_Rg_algebra}{void} 10797return the generic algebra. 10798 10799\section{Black box ring} 10800 10801A black box ring is defined by a \tet{bb_ring} struct, describing methods 10802available to handle ring elements: 10803\bprog 10804struct bb_ring 10805{ 10806 GEN (*add)(void *E, GEN x, GEN y); 10807 GEN (*mul)(void *E, GEN x, GEN y); 10808 GEN (*sqr)(void *E, GEN x); 10809}; 10810@eprog 10811 10812\kbd{add(E,x,y)} returns the sum $x+y$. 10813 10814\kbd{mul(E,x,y)} returns the product $x\*y$. 10815 10816\kbd{sqr(E,x)} returns the square $x^2$. 10817 10818\fun{GEN}{gen_fromdigits}{GEN v, GEN B, void *E, struct bb_ring *r} 10819where $B$ is a ring element and $v=[c_0,\ldots,c_{n-1}]$ a vector of ring elements, 10820return $\sum_{i=0}^n c_i\*B^i$ using binary splitting. 10821 10822\fun{GEN}{gen_digits}{GEN x, GEN B, long n, void *E, struct bb_ring *r, 10823 GEN (*div)(void *E, GEN x, GEN y, GEN *r)} 10824 10825(Require the ring to be Euclidean) 10826 10827\kbd{div(E,x,y,\&r)} performs the Euclidean division of $x$ by $y$ in the ring 10828$R$, returning the quotient $q$ and setting $r$ to the residue so that 10829$x=q\*y+r$ holds. The residue must belong to a fixed set of representatives of 10830$R/(y)$. 10831 10832The argument $x$ being a ring element, \kbd{gen\_digits} returns a vector of 10833ring elements $[c_0,\ldots,c_{n-1}]$ such that $x = \sum_{i=0}^n c_i\*B^i$. 10834Furthermore for all $i\ne n-1$, the elements $c_i$ belonging to the fixed set 10835of representatives of $R/(B)$. 10836 10837\section{Black box free $\Z_p$-modules} 10838 10839(Very experimental) 10840 10841\fun{GEN}{gen_ZpX_Dixon}{GEN F, GEN V, GEN q, GEN p, long N, void *E, 10842 GEN lin(void *E, GEN F, GEN z, GEN q), 10843 GEN invl(void *E, GEN z)} 10844 10845Let $F$ be a \kbd{ZpXT} representing the coefficients of some abstract 10846linear mapping $f$ over $\Z_p[X]$ seen as a free $\Z_p$-module, let $V$ be 10847an element of $\Z_p[X]$ and let $q = p^N$. Return $y\in\Z_p[X]$ such that 10848$f(y)=V\pmod{p^N}$ assuming the following holds for $n\leq N$: 10849 10850\item $\kbd{lin}(E, \kbd{FpX\_red}(F, p^n), z, p^n) \equiv f(z) \pmod{p^n}$ 10851 10852\item $f(\kbd{invl}(E, z)) \equiv z \pmod{p}$ 10853 10854The rationale for the argument $F$ being that it allows \kbd{gen\_ZpX\_Dixon} 10855to reduce it to the required $p$-adic precision. 10856 10857\fun{GEN}{gen_ZpX_Newton}{GEN x, GEN p, long n, void *E, 10858 GEN eval(void *E, GEN a, GEN q), 10859 GEN invd(void *E, GEN b, GEN v, GEN q, long N)} 10860 10861Let $x$ be an element of $\Z_p[X]$ seen as a free $\Z_p$-module, and $f$ 10862some differentiable function over $\Z_p[X]$ such that $f(x) \equiv 0 10863\pmod{p}$. Return $y$ such that $f(y) \equiv 0\pmod{p^n}$, assuming the 10864following holds for all $a, b\in \Z_p[X]$ and $M\leq N$: 10865 10866\item $v = \kbd{eval}(E,a,p^N)$ is a vector of elements of $\Z_p[X]$, 10867 10868\item $w = \kbd{invd}(E,b,v,p^M,M)$ is an element in $\Z_p[X]$, 10869 10870\item $v[1] \equiv f(a) \pmod{p^N\Z_p[X]}$, 10871 10872\item $df_a(w) \equiv b \pmod{p^M\Z_p[X]}$ 10873 10874\noindent and $df_a$ denotes the differential of $f$ at $a$. Motivation: 10875\kbd{eval} allows to evaluate $f$ and \kbd{invd} allows to invert its 10876differential. Frequently, data useful to compute the differential appear as a 10877subproduct of computing the function. The vector $v$ allows \kbd{eval} to 10878provide these to \kbd{invd}. The implementation of \kbd{invd} will generally 10879involves the use of the function \kbd{gen\_ZpX\_Dixon}. 10880 10881\fun{GEN}{gen_ZpM_Newton}{GEN x, GEN p, long n, void *E, 10882 GEN eval(void *E, GEN a, GEN q), 10883 GEN invd(void *E, GEN b, GEN v, GEN q, long N)} 10884as above, with polynomials replaced by matrices. 10885 10886\newpage 10887\chapter{Operations on general PARI objects} 10888 10889\section{Assignment} 10890 10891It is in general easier to use a direct conversion, 10892e.g.~\kbd{y = stoi(s)}, than to allocate a target of correct type and 10893sufficient size, then assign to it: 10894\bprog 10895 GEN y = cgeti(3); affsi(s, y); 10896@eprog\noindent 10897These functions can still be moderately useful in complicated garbage 10898collecting scenarios but you will be better off not using them. 10899 10900\fun{void}{gaffsg}{long s, GEN x} assigns the \kbd{long}~\kbd{s} into the 10901object~\kbd{x}. 10902 10903\fun{void}{gaffect}{GEN x, GEN y} assigns the object \kbd{x} into the 10904object~\kbd{y}. Both \kbd{x} and \kbd{y} must be scalar types. Type 10905conversions (e.g.~from \typ{INT} to \typ{REAL} or \typ{INTMOD}) occur if 10906legitimate. 10907 10908\fun{int}{is_universal_constant}{GEN x} returns $1$ if $x$ is a global PARI 10909constant you should never assign to (such as \kbd{gen\_1}), and $0$ 10910otherwise. 10911 10912\section{Conversions} 10913 10914\subsec{Scalars} 10915 10916\fun{double}{rtodbl}{GEN x} applied to a \typ{REAL}~\kbd{x}, converts \kbd{x} 10917into a \kbd{double} if possible. 10918 10919\fun{GEN}{dbltor}{double x} converts the \kbd{double} \kbd{x} into a 10920\typ{REAL}. 10921 10922\fun{long}{dblexpo}{double x} returns \kbd{expo(dbltor(x))}, but 10923faster and without cluttering the stack. 10924 10925\fun{ulong}{dblmantissa}{double x} returns the most significant word 10926in the mantissa of \kbd{dbltor(x)}. 10927 10928\fun{int}{gisdouble}{GEN x} if \kbd{x} is a real number (not necessarily 10929a~\typ{REAL}), return $1$ if \kbd{x} can be converted to a \kbd{double}, 10930$0$ otherwise. 10931 10932\fun{double}{gtodouble}{GEN x} if \kbd{x} is a real number (not necessarily 10933a~\typ{REAL}), converts \kbd{x} into a \kbd{double} if possible. 10934 10935\fun{long}{gtos}{GEN x} converts the \typ{INT} \kbd{x} to a small 10936integer if possible, otherwise raise an exception. This function 10937is similar to \tet{itos}, slightly slower since it checks the type of \kbd{x}. 10938 10939\fun{ulong}{gtou}{GEN x} converts the non-negative \typ{INT} \kbd{x} to 10940an unsigned small integer if possible, otherwise raise an exception. This 10941function is similar to \tet{itou}, slightly slower since it checks the type 10942of \kbd{x}. 10943 10944\fun{double}{dbllog2r}{GEN x} assuming that \kbd{x} is a nonzero \typ{REAL}, 10945returns an approximation to \kbd{log2(|x|)}. 10946 10947\fun{double}{dblmodulus}{GEN x} return an approximation to \kbd{|x|}. 10948 10949\fun{long}{gtolong}{GEN x} if \kbd{x} is an integer (not necessarily 10950a~\typ{INT}), converts \kbd{x} into a \kbd{long} if possible. 10951 10952\fun{GEN}{fractor}{GEN x, long l} applied to a \typ{FRAC}~\kbd{x}, converts 10953\kbd{x} into a \typ{REAL} of length \kbd{prec}. 10954 10955\fun{GEN}{quadtofp}{GEN x, long l} applied to a \typ{QUAD}~\kbd{x}, converts 10956\kbd{x} into a \typ{REAL} or \typ{COMPLEX} depending on the sign of the 10957discriminant of~\kbd{x}, to precision \hbox{\kbd{l} \B-bit} words. 10958% forbid line brk at hyphen here [GN] 10959 10960\fun{GEN}{upper_to_cx}{GEN x, long *prec} valid for a \typ{COMPLEX} 10961or \typ{QUAD} belonging to the upper half-plane. If a \typ{QUAD}, convert it 10962to \typ{COMPLEX} using accuracy \kbd{*prec}. If $x$ is inexact, sets 10963\kbd{*prec} to the precision of $x$. 10964 10965\fun{GEN}{cxtofp}{GEN x, long prec} converts the \typ{COMPLEX}~\kbd{x} to a 10966a complex whose real and imaginary parts are \typ{REAL} of length \kbd{prec} 10967(special case of~\kbd{gtofp}. 10968 10969\fun{GEN}{cxcompotor}{GEN x, long prec} converts the 10970\typ{INT}, \typ{REAL} or \typ{FRAC} $x$ to a \typ{REAL} of length \kbd{prec}. 10971These are all the real types which may occur as components of a 10972\typ{COMPLEX}; special case of~\kbd{gtofp} (introduced so that the latter is 10973not recursive and can thus be inlined). 10974 10975\fun{GEN}{cxtoreal}{GEN x} converts the complex (\typ{INT}, \typ{REAL}, 10976\typ{FRAC} or \typ{COMPLEX}) $x$ to a real number if its imaginary part is 0. 10977Shallow function. 10978 10979converts the \typ{COMPLEX}~\kbd{x} to a 10980a complex whose real and imaginary parts are \typ{REAL} of length \kbd{prec} 10981(special case of~\kbd{gtofp}. 10982 10983\fun{GEN}{gtofp}{GEN x, long prec} converts the complex number~\kbd{x} 10984(\typ{INT}, \typ{REAL}, \typ{FRAC}, \typ{QUAD} or \typ{COMPLEX}) to either 10985a \typ{REAL} or \typ{COMPLEX} whose components are \typ{REAL} of precision 10986\kbd{prec}; not necessarily of \emph{length} \kbd{prec}: a real $0$ may be 10987given as \kbd{real\_0(...)}). If the result is a \typ{COMPLEX} extra care is 10988taken so that its modulus really has accuracy \kbd{prec}: there is a problem 10989if the real part of the input is an exact $0$; indeed, converting it to 10990\kbd{real\_0(prec)} would be wrong if the imaginary part is tiny, since the 10991modulus would then become equal to $0$, as in $1.E-100 + 0.E-28 = 0.E-28$. 10992 10993\fun{GEN}{gtomp}{GEN z, long prec} converts the real number~\kbd{x} 10994(\typ{INT}, \typ{REAL}, \typ{FRAC}, real \typ{QUAD}) to either 10995a \typ{INT} or a \typ{REAL} of precision \kbd{prec}. Not memory clean 10996if $x$ is a \typ{INT}: we return $x$ itself and not a copy. 10997 10998\fun{GEN}{gcvtop}{GEN x, GEN p, long l} converts $x$ into a \typ{PADIC} 10999of precision~$l$. Works componentwise on recursive objects, 11000e.g.~\typ{POL} or \typ{VEC}. Converting $0$ yields $O(p^l)$; converting a 11001nonzero number yield a result well defined modulo $p^{v_p(x) + l}$. 11002 11003\fun{GEN}{cvtop}{GEN x, GEN p, long l} as \kbd{gcvtop}, assuming that $x$ 11004is a scalar. 11005 11006\fun{GEN}{cvtop2}{GEN x, GEN y} $y$ being a $p$-adic, converts the scalar $x$ 11007to a $p$-adic of the same accuracy. Shallow function. 11008 11009\fun{GEN}{cvstop2}{long s, GEN y} $y$ being a $p$-adic, converts the scalar $s$ 11010to a $p$-adic of the same accuracy. Shallow function. 11011 11012\fun{GEN}{gprec}{GEN x, long l} returns a copy of $x$ whose precision is 11013changed to $l$ digits. The precision change is done recursively on all 11014components of $x$. Digits means \emph{decimal}, $p$-adic and $X$-adic digits 11015for \typ{REAL}, \typ{SER}, \typ{PADIC} components, respectively. 11016 11017\fun{GEN}{gprec_w}{GEN x, long l} returns a shallow copy of $x$ whose 11018\typ{REAL} components have their precision changed to $l$ \emph{words}. This 11019is often more useful than \kbd{gprec}. 11020 11021\fun{GEN}{gprec_wtrunc}{GEN x, long l} returns a shallow copy of $x$ whose 11022\typ{REAL} components have their precision \emph{truncated} to $l$ 11023\emph{words}. Contrary to \kbd{gprec\_w}, this function may never increase 11024the precision of~$x$. 11025 11026\fun{GEN}{gprec_wensure}{GEN x, long l} returns a shallow copy of $x$ whose 11027\typ{REAL} components have their precision \emph{increased} to at least $l$ 11028\emph{words}. Contrary to \kbd{gprec\_w}, this function may never decrease 11029the precision of~$x$. 11030 11031The following functions are obsolete and kept for backward compatibility only: 11032 11033\fun{GEN}{precision0}{GEN x, long n} 11034 11035\fun{GEN}{bitprecision0}{GEN x, long n} 11036 11037\subsec{Modular objects / lifts} 11038 11039\fun{GEN}{gmodulo}{GEN x, GEN y} creates the object \kbd{\key{Mod}(x,y)} on 11040the PARI stack, where \kbd{x} and \kbd{y} are either both \typ{INT}s, and the 11041result is a \typ{INTMOD}, or \kbd{x} is a scalar or a \typ{POL} and \kbd{y} a 11042\typ{POL}, and the result is a \typ{POLMOD}. 11043 11044\fun{GEN}{gmodulgs}{GEN x, long y} same as \key{gmodulo} except \kbd{y} is a 11045\kbd{long}. 11046 11047\fun{GEN}{gmodulsg}{long x, GEN y} same as \key{gmodulo} except \kbd{x} is a 11048\kbd{long}. 11049 11050\fun{GEN}{gmodulss}{long x, long y} same as \key{gmodulo} except both 11051\kbd{x} and \kbd{y} are \kbd{long}s. 11052 11053\fun{GEN}{lift_shallow}{GEN x} shallow version of \tet{lift} 11054 11055\fun{GEN}{liftall_shallow}{GEN x} shallow version of \tet{liftall} 11056 11057\fun{GEN}{liftint_shallow}{GEN x} shallow version of \tet{liftint} 11058 11059\fun{GEN}{liftpol_shallow}{GEN x} shallow version of \tet{liftpol} 11060 11061\fun{GEN}{centerlift0}{GEN x,long v} DEPRECATED, kept for backward 11062compatibility only: use either \tet{lift0}$(x,v)$ or \tet{centerlift}$(x)$. 11063 11064\subsec{Between polynomials and coefficient arrays} 11065 11066\fun{GEN}{gtopoly}{GEN x, long v} converts or truncates the object~\kbd{x} 11067into a \typ{POL} with main variable number~\kbd{v}. A common application 11068would be the conversion of coefficient vectors (coefficients are given by 11069decreasing degree). E.g.~\kbd{[2,3]} goes to \kbd{2*v + 3} 11070 11071\fun{GEN}{gtopolyrev}{GEN x, long v} converts or truncates the object~\kbd{x} 11072into a \typ{POL} with main variable number~\kbd{v}, but vectors are converted 11073in reverse order compared to \kbd{gtopoly} (coefficients are given by 11074increasing degree). E.g.~\kbd{[2,3]} goes to \kbd{3*v + 2}. In other words 11075the vector represents a polynomial in the basis $(1,v,v^2,v^3,\dots)$. 11076 11077\fun{GEN}{normalizepol}{GEN x} applied to an unnormalized \typ{POL}~\kbd{x} 11078(with all coefficients correctly set except that \kbd{leading\_term(x)} might 11079be zero), normalizes \kbd{x} correctly in place and returns~\kbd{x}. For 11080internal use. Normalizing means deleting all leading \emph{exact} zeroes 11081(as per \kbd{isexactzero}), except if the polynomial turns out to be $0$, 11082in which case we try to find a coefficient $c$ which is a nonrational zero, 11083and return the constant polynomial $c$. (We do this so that information 11084about the base ring is not lost.) 11085 11086\fun{GEN}{normalizepol_lg}{GEN x, long l} applies \kbd{normalizepol} to 11087\kbd{x}, pretending that \kbd{lg(x)} is $l$, which must be less than 11088or equal to \kbd{lg(x)}. If equal, the function is equivalent to 11089\kbd{normalizepol(x)}. 11090 11091\fun{GEN}{normalizepol_approx}{GEN x, long lx} as \kbd{normalizepol\_lg}, 11092with the difference that we just delete all leading zeroes (as per 11093\kbd{gequal0}). This rougher normalization is used when we have no other 11094choice, for instance before attempting a Euclidean division by $x$. 11095 11096The following routines do \emph{not} copy coefficients on the stack (they 11097only move pointers around), hence are very fast but not suitable for 11098\kbd{gerepile} calls. Recall that an \kbd{RgV} (resp.~an \kbd{RgX}, resp.~an 11099\kbd{RgM}) is a \typ{VEC} or \typ{COL} (resp.~a \typ{POL}, resp.~a \typ{MAT}) 11100with arbitrary components. Similarly, an \kbd{RgXV} is a \typ{VEC} or 11101\typ{COL} with \kbd{RgX} components, etc. 11102 11103\fun{GEN}{RgV_to_RgX}{GEN x, long v} converts the \kbd{RgV}~\kbd{x} to a 11104(normalized) polynomial in variable~\kbd{v} (as \kbd{gtopolyrev}, without 11105copy). 11106 11107\fun{GEN}{RgV_to_RgX_reverse}{GEN x, long v} converts the \kbd{RgV}~\kbd{x} 11108to a (normalized) polynomial in variable~\kbd{v} (as \kbd{gtopoly}, 11109without copy). 11110 11111\fun{GEN}{RgX_to_RgC}{GEN x, long N} converts the \typ{POL}~\kbd{x} to a 11112\typ{COL}~\kbd{v} with \kbd{N} components. Coefficients of \kbd{x} are listed 11113by increasing degree, so that \kbd{y[i]} is the coefficient of the term of 11114degree $i-1$ in \kbd{x}. 11115 11116\fun{GEN}{Rg_to_RgC}{GEN x, long N} as \tet{RgX_to_RgV}, except that other 11117types than \typ{POL} are allowed for \kbd{x}, which is then considered as a 11118constant polynomial. 11119 11120\fun{GEN}{RgM_to_RgXV}{GEN x, long v} converts the \kbd{RgM}~\kbd{x} to a 11121\typ{VEC} of \kbd{RgX}, by repeated calls to \kbd{RgV\_to\_RgX}. 11122 11123\fun{GEN}{RgV_to_RgM}{GEN v, long N} converts the vector~\kbd{v} to 11124a~\typ{MAT} with \kbd{N}~rows, by repeated calls to \kbd{Rg\_to\_RgV}. 11125 11126\fun{GEN}{RgXV_to_RgM}{GEN v, long N} converts the vector of \kbd{RgX}~\kbd{v} 11127to a~\typ{MAT} with \kbd{N}~rows, by repeated calls to \kbd{RgX\_to\_RgV}. 11128 11129\fun{GEN}{RgM_to_RgXX}{GEN x, long v,long w} converts the \kbd{RgM}~\kbd{x} into 11130a \typ{POL} in variable~\kbd{v}, whose coefficients are \typ{POL}s in 11131variable~\kbd{w}. This is a shortcut for 11132\bprog 11133 RgV_to_RgX( RgM_to_RgXV(x, w), v ); 11134@eprog\noindent 11135There are no consistency checks with respect to variable 11136priorities: the above is an invalid object if $\kbd{varncmp(v, w)} \geq 0$. 11137 11138\fun{GEN}{RgXX_to_RgM}{GEN x, long N} converts the \typ{POL}~\kbd{x} with 11139\kbd{RgX} (or constant) coefficients to a matrix with \kbd{N} rows. 11140 11141\fun{long}{RgXY_degreex}{GEN P} return the degree of $P$ with respect to 11142the secondary variable. 11143 11144\fun{GEN}{RgXY_swap}{GEN P, long n, long w} converts the bivariate polynomial 11145$\kbd{P}(u,v)$ (a \typ{POL} with \typ{POL} or scalar coefficients) to 11146$P(\kbd{pol\_x[w]},u)$, assuming \kbd{n} is an upper bound for 11147$\deg_v(\kbd{P})$. 11148 11149\fun{GEN}{RgXY_swapspec}{GEN C, long n, long w, long lP} 11150as \kbd{RgXY\_swap} where the coefficients of $P$ are given by 11151\kbd{gel(C,0),\dots,gel(C,lP-1)}. 11152 11153\fun{GEN}{RgX_to_ser}{GEN x, long l} convert the \typ{POL}~\kbd{x} to 11154a \emph{shallow} \typ{SER} of length~$l\geq 2$. 11155Unless the polynomial is an exact zero, the coefficient of lowest degree 11156$T^d$ of the result is not an exact zero (as per \kbd{isexactzero}). The 11157remainder is $O(T^{d+l-2})$. 11158 11159\fun{GEN}{RgX_to_ser_inexact}{GEN x, long l} convert the \typ{POL}~\kbd{x} to 11160a \emph{shallow} \typ{SER} of length~$l\geq 2$. 11161Unless the polynomial is zero, the coefficient of lowest degree 11162$T^d$ of the result is not zero (as per \kbd{gequal0}). The 11163remainder is $O(T^{d+l-2})$. 11164 11165\fun{GEN}{RgV_to_ser}{GEN x, long v, long l} convert the \typ{VEC}~\kbd{x}, 11166to a \emph{shallow} \typ{SER} of length~$l\geq 2$. 11167 11168\fun{GEN}{rfrac_to_ser}{GEN F, long l} applied to a \typ{RFRAC}~$F$, 11169creates a \typ{SER} of length~$l\geq 2$ congruent to $F$. Not memory-clean 11170but suitable for \kbd{gerepileupto}. 11171 11172\fun{GEN}{rfracrecip_to_ser_absolute}{GEN F, long d} applied to a 11173\typ{RFRAC}~$F$, creates the \typ{SER} $F(1/t) + O(t^d)$. Note that 11174we use absolute and not relative precision here. 11175 11176\fun{GEN}{gtoser}{GEN s, long v, long d}. This function is deprecated, 11177kept for backward compatibility: it follows the semantic of \kbd{Ser(s,v)}, 11178with $d = \kbd{seriesprecision}$ implied and is hard to use as a general 11179conversion function. Use \tet{gtoser_prec} instead. 11180 11181It converts the object~$s$ into a \typ{SER} with main variable number~\kbd{v} 11182and $d > 0$ significant terms, but the argument $d$ is sometimes ignored. 11183More precisely 11184 11185\item if $s$ is a scalar (with respect to variable $v$), we return a 11186constant power series with $d$ significant terms; 11187 11188\item if $s$ is a \typ{POL} in variable $v$, it is truncated to $d$ terms if 11189needed; 11190 11191\item if $s$ is a vector, the coefficients of the vector are understood to 11192be the coefficients of the power series starting from the constant term (as 11193in \tet{Polrev}), and the precision $d$ is \emph{ignored}; 11194 11195\item if $s$ is already a power series in $v$, we return a copy, and 11196the precision $d$ is again \emph{ignored}. 11197 11198\fun{GEN}{gtoser_prec}{GEN s, long v, long d} this function is a variant of 11199\kbd{gtoser} following the semantic of \kbd{Ser(s,v,d)}: the precision $d$ 11200is always taken into account. 11201 11202\fun{GEN}{gtocol}{GEN x} converts the object~\kbd{x} into a \typ{COL} 11203 11204\fun{GEN}{gtomat}{GEN x} converts the object~\kbd{x} into a \typ{MAT}. 11205 11206\fun{GEN}{gtovec}{GEN x} converts the object~\kbd{x} into a \typ{VEC}. 11207 11208\fun{GEN}{gtovecsmall}{GEN x} converts the object~\kbd{x} into a 11209\typ{VECSMALL}. 11210 11211\fun{GEN}{normalize}{GEN x} applied to an unnormalized \typ{SER}~\kbd{x} 11212(i.e.~type \typ{SER} with all coefficients correctly set except that \kbd{x[2]} 11213might be zero), normalizes \kbd{x} correctly in place. Returns~\kbd{x}. 11214For internal use. 11215 11216\fun{GEN}{serchop0}{GEN s} given a \typ{SER} of the form $x^v s(x)$, with 11217$s(0)\neq 0$, return $x^v(s - s(0))$. Shallow function. 11218 11219\fun{GEN}{serchop_i}{GEN x, long n} returns a shallow chopy of \typ{SER} $x$ 11220with all terms of degree strictly less than $n$ removed. Shallow 11221version of \kbd{serchop}. 11222 11223\section{Constructors} 11224 11225\subsec{Clean constructors}\label{se:clean} 11226 11227\fun{GEN}{zeropadic}{GEN p, long n} creates a $0$ \typ{PADIC} equal to 11228$O(\kbd{p}^\kbd{n})$. 11229 11230\fun{GEN}{zeroser}{long v, long n} creates a $0$ \typ{SER} in variable 11231\kbd{v} equal to $O(X^\kbd{n})$. 11232 11233\fun{GEN}{scalarser}{GEN x, long v, long prec} creates a constant \typ{SER} 11234in variable \kbd{v} and precision \kbd{prec}, whose constant coefficient is 11235(a copy of) \kbd{x}, in other words $\kbd{x} + O(\kbd{v}^\kbd{prec})$. 11236Assumes that $\kbd{prec}\geq 0$. 11237 11238\fun{GEN}{pol_0}{long v} Returns the constant polynomial $0$ in variable $v$. 11239 11240\fun{GEN}{pol_1}{long v} Returns the constant polynomial $1$ in variable $v$. 11241 11242\fun{GEN}{pol_x}{long v} Returns the monomial of degree $1$ in variable $v$. 11243 11244\fun{GEN}{pol_xn}{long n, long v} Returns the monomial of degree $n$ 11245in variable $v$; assume that $n \geq 0$. 11246 11247\fun{GEN}{pol_xnall}{long n, long v} Returns the Laurent monomial of degree $n$ 11248in variable $v$; $n < 0$ is allowed. 11249 11250\fun{GEN}{pol_x_powers}{long N, long v} returns the powers of 11251\kbd{pol\_x(v)}, of degree $0$ to $N-1$, in a vector with $N$ components. 11252 11253\fun{GEN}{scalarpol}{GEN x, long v} creates a constant \typ{POL} in variable 11254\kbd{v}, whose constant coefficient is (a copy of) \kbd{x}. 11255 11256\fun{GEN}{deg1pol}{GEN a, GEN b,long v} creates the degree 1 \typ{POL} 11257$a \kbd{pol\_x}(v) + b$ 11258 11259\fun{GEN}{zeropol}{long v} is identical \kbd{pol\_0}. 11260 11261\fun{GEN}{zerocol}{long n} creates a \typ{COL} with \kbd{n} components set to 11262\kbd{gen\_0}. 11263 11264\fun{GEN}{zerovec}{long n} creates a \typ{VEC} with \kbd{n} components set to 11265\kbd{gen\_0}. 11266 11267\fun{GEN}{zerovec_block}{long n} as \kbd{zerovec} but return a clone. 11268 11269\fun{GEN}{col_ei}{long n, long i} creates a \typ{COL} with \kbd{n} components 11270set to \kbd{gen\_0}, but for the \kbd{i}-th one which is set to \kbd{gen\_1} 11271(\kbd{i}-th vector in the canonical basis). 11272 11273\fun{GEN}{vec_ei}{long n, long i} creates a \typ{VEC} with \kbd{n} components 11274set to \kbd{gen\_0}, but for the \kbd{i}-th one which is set to \kbd{gen\_1} 11275(\kbd{i}-th vector in the canonical basis). 11276 11277\fun{GEN}{trivial_fact}{void} returns the trivial (empty) factorization 11278\kbd{Mat([]\til,[]\til)} 11279 11280\fun{GEN}{prime_fact}{GEN x} returns the factorization 11281\kbd{Mat([x]\til, [1]\til)} 11282 11283\fun{GEN}{Rg_col_ei}{GEN x, long n, long i} creates a \typ{COL} with \kbd{n} 11284components set to \kbd{gen\_0}, but for the \kbd{i}-th one which is set to 11285\kbd{x}. 11286 11287\fun{GEN}{vecsmall_ei}{long n, long i} creates a \typ{VECSMALL} with \kbd{n} 11288components set to \kbd{0}, but for the \kbd{i}-th one which is set to 11289\kbd{1} (\kbd{i}-th vector in the canonical basis). 11290 11291\fun{GEN}{scalarcol}{GEN x, long n} creates a \typ{COL} with \kbd{n} 11292components set to \kbd{gen\_0}, but the first one which is set to a copy 11293of \kbd{x}. (The name comes from \kbd{RgV\_isscalar}.) 11294 11295\smallskip 11296 11297\fun{GEN}{mkintmodu}{ulong x, ulong y} creates the \typ{INTMOD} \kbd{Mod(x, y)}. 11298The inputs must satisfy $x < y$. 11299 11300\fun{GEN}{zeromat}{long m, long n} creates a \typ{MAT} with \kbd{m} x \kbd{n} 11301components set to \kbd{gen\_0}. Note that the result allocates a 11302\emph{single} column, so modifying an entry in one column modifies it in 11303all columns. To fully allocate a matrix initialized with zero entries, 11304use \kbd{zeromatcopy}. 11305 11306\fun{GEN}{zeromatcopy}{long m, long n} creates a \typ{MAT} with \kbd{m} x 11307\kbd{n} components set to \kbd{gen\_0}. 11308 11309\fun{GEN}{matid}{long n} identity matrix in dimension \kbd{n} (with 11310components \kbd{gen\_1} and\kbd{gen\_0}). 11311 11312\fun{GEN}{scalarmat}{GEN x, long n} scalar matrix, \kbd{x} times the identity. 11313 11314\fun{GEN}{scalarmat_s}{long x, long n} scalar matrix, \kbd{stoi(x)} times 11315the identity. 11316 11317\fun{GEN}{vecrange}{GEN a, GEN b} returns the \typ{VEC} $[a..b]$. 11318 11319\fun{GEN}{vecrangess}{long a, long b} returns the \typ{VEC} $[a..b]$. 11320 11321\smallskip 11322See also next section for analogs of the following functions: 11323 11324\fun{GEN}{mkfracss}{long x, long y} creates the \typ{FRAC} $x/y$. Assumes that 11325$y > 1$ and $(x,y) = 1$. 11326 11327\fun{GEN}{sstoQ}{long x, long y} returns the \typ{INT} or \typ{FRAC} $x/y$; 11328no assumptions. 11329 11330\fun{void}{Qtoss}{GEN q, long *n, long *d} given a \typ{INT} or \typ{FRAC} $q$, 11331set $n$ and $d$ such that $q = n/d$ with $d \geq 1$ and $(n,d)$ = 1. Overflow 11332error if numerator or denominator do not fit into a long integer. 11333 11334\fun{GEN}{mkfraccopy}{GEN x, GEN y} creates the \typ{FRAC} $x/y$. Assumes that 11335$y > 1$ and $(x,y) = 1$. 11336 11337\fun{GEN}{mkrfraccopy}{GEN x, GEN y} creates the \typ{RFRAC} $x/y$. 11338Assumes that $y$ is a \typ{POL}, $x$ a compatible type whose variable has 11339lower or same priority, with $(x,y) = 1$. 11340 11341\fun{GEN}{mkcolcopy}{GEN x} creates a 1-dimensional \typ{COL} containing 11342\kbd{x}. 11343 11344\fun{GEN}{mkmatcopy}{GEN x} creates a 1-by-1 \typ{MAT} wrapping the \typ{COL} 11345\kbd{x}. 11346 11347\fun{GEN}{mkveccopy}{GEN x} creates a 1-dimensional \typ{VEC} containing 11348\kbd{x}. 11349 11350\fun{GEN}{mkvec2copy}{GEN x, GEN y} creates a 2-dimensional \typ{VEC} equal 11351to \kbd{[x,y]}. 11352 11353\fun{GEN}{mkcols}{long x} creates a 1-dimensional \typ{COL} 11354containing \kbd{stoi(x)}. 11355 11356\fun{GEN}{mkcol2s}{long x, long y} creates a 2-dimensional \typ{COL} 11357containing \kbd{[stoi(x), stoi(y)]~}. 11358 11359\fun{GEN}{mkcol3s}{long x, long y, long z} creates a 3-dimensional \typ{COL} 11360containing \kbd{[stoi(x), stoi(y), stoi(z)]~}. 11361 11362\fun{GEN}{mkcol4s}{long x, long y, long z, long t} creates a 4-dimensional 11363\typ{COL} containing \kbd{[stoi(x), stoi(y), stoi(z), stoi(t)]~}. 11364 11365\fun{GEN}{mkvecs}{long x} creates a 1-dimensional \typ{VEC} 11366containing \kbd{stoi(x)}. 11367 11368\fun{GEN}{mkvec2s}{long x, long y} creates a 2-dimensional \typ{VEC} 11369containing \kbd{[stoi(x), stoi(y)]}. 11370 11371\fun{GEN}{mkmat22s}{long a, long b, long c, long d} creates the $2$ by $2$ 11372\typ{MAT} with successive rows \kbd{[stoi(a), stoi(b)]} and 11373\kbd{[stoi(c), stoi(d)]}. 11374 11375\fun{GEN}{mkvec3s}{long x, long y, long z} creates a 3-dimensional \typ{VEC} 11376containing \kbd{[stoi(x), stoi(y), stoi(z)]}. 11377 11378\fun{GEN}{mkvec4s}{long x, long y, long z, long t} creates a 4-dimensional 11379\typ{VEC} containing \kbd{[stoi(x), stoi(y), stoi(z), stoi(t)]}. 11380 11381\fun{GEN}{mkvecsmall}{long x} creates a 1-dimensional \typ{VECSMALL} 11382containing \kbd{x}. 11383 11384\fun{GEN}{mkvecsmall2}{long x, long y} creates a 2-dimensional \typ{VECSMALL} 11385containing \kbd{[x, y]}. 11386 11387\fun{GEN}{mkvecsmall3}{long x, long y, long z} creates a 3-dimensional 11388\typ{VECSMALL} containing \kbd{[x, y, z]}. 11389 11390\fun{GEN}{mkvecsmall4}{long x, long y, long z, long t} creates a 4-dimensional 11391\typ{VECSMALL} containing \kbd{[x, y, z, t]}. 11392 11393\fun{GEN}{mkvecsmall5}{long x, long y, long z, long t, long u} creates a 113945-dimensional \typ{VECSMALL} containing \kbd{[x, y, z, t, u]}. 11395 11396\fun{GEN}{mkvecsmalln}{long n, ...} returns the \typ{VECSMALL} whose $n$ 11397coefficients (\kbd{long}) follow. 11398\emph{Warning:} since this is a variadic function, C type promotion is not 11399performed on the arguments by the compiler, thus you have to make sure that all 11400the arguments are of type \kbd{long}, in particular integer constants need to 11401be written with the \kbd{L} suffix: \kbd{mkvecsmalln(2, 1L, 2L)} is correct, 11402but \kbd{mkvecsmalln(2, 1, 2)} is not. 11403 11404\subsec{Unclean constructors}\label{se:unclean} 11405 11406Contrary to the policy of general PARI functions, the functions in this 11407subsection do \emph{not} copy their arguments, nor do they produce an object 11408a priori suitable for \tet{gerepileupto}. In particular, they are 11409faster than their clean equivalent (which may not exist). \emph{If} you 11410restrict their arguments to universal objects (e.g \kbd{gen\_0}), 11411then the above warning does not apply. 11412 11413\fun{GEN}{mkcomplex}{GEN x, GEN y} creates the \typ{COMPLEX} $x + iy$. 11414 11415\fun{GEN}{mulcxI}{GEN x} creates the \typ{COMPLEX} $ix$. The result in 11416general contains data pointing back to the original $x$. Use \kbd{gcopy} if 11417this is a problem. But in most cases, the result is to be used immediately, 11418before $x$ is subject to garbage collection. 11419 11420\fun{GEN}{mulcxmI}{GEN x}, as \tet{mulcxI}, but returns $-ix$. 11421 11422\fun{GEN}{mulcxpowIs}{GEN x, long k}, as \tet{mulcxI}, but returns 11423$x \cdot i^k$. 11424 11425\fun{GEN}{mkquad}{GEN n, GEN x, GEN y} creates the \typ{QUAD} $x + yw$, 11426where $w$ is a root of $n$, which is of the form \kbd{quadpoly(D)}. 11427 11428\fun{GEN}{mkfrac}{GEN x, GEN y} creates the \typ{FRAC} $x/y$. Assumes that 11429$y > 1$ and $(x,y) = 1$. 11430 11431\fun{GEN}{mkrfrac}{GEN x, GEN y} creates the \typ{RFRAC} $x/y$. Assumes 11432that $y$ is a \typ{POL}, $x$ a compatible type whose variable has lower 11433or same priority, with $(x,y) = 1$. 11434 11435\fun{GEN}{mkcol}{GEN x} creates a 1-dimensional \typ{COL} containing \kbd{x}. 11436 11437\fun{GEN}{mkcol2}{GEN x, GEN y} creates a 2-dimensional \typ{COL} equal to 11438\kbd{[x,y]}. 11439 11440\fun{GEN}{mkcol3}{GEN x, GEN y, GEN z} creates a 3-dimensional \typ{COL} 11441equal to \kbd{[x,y,z]}. 11442 11443\fun{GEN}{mkcol4}{GEN x, GEN y, GEN z, GEN t} creates a 4-dimensional \typ{COL} 11444equal to \kbd{[x,y,z,t]}. 11445 11446\fun{GEN}{mkcol5}{GEN a1, GEN a2, GEN a3, GEN a4, GEN a5} creates the 114475-dimensional \typ{COL} equal to $[a_1,a_2,a_3,a_4,a_5]$. 11448 11449\fun{GEN}{mkcol6}{GEN x, GEN y, GEN z, GEN t, GEN u, GEN v} 11450creates the $6$-dimensional column vector \kbd{[x,y,z,t,u,v]~}. 11451 11452\fun{GEN}{mkintmod}{GEN x, GEN y} creates the \typ{INTMOD} \kbd{Mod(x, y)}. 11453The inputs must be \typ{INT}s satisfying $0 \leq x < y$. 11454 11455\fun{GEN}{mkpolmod}{GEN x, GEN y} creates the \typ{POLMOD} \kbd{Mod(x, y)}. 11456The input must satisfy $\deg x < \deg y$ with respect to the main variable of 11457the \typ{POL} $y$. $x$ may be a scalar. 11458 11459\fun{GEN}{mkmat}{GEN x} creates a 1-column \typ{MAT} with column $x$ 11460(a \typ{COL}). 11461 11462\fun{GEN}{mkmat2}{GEN x, GEN y} creates a 2-column \typ{MAT} with columns 11463$x$, $y$ (\typ{COL}s of the same length). 11464 11465\fun{GEN}{mkmat22}{GEN a, GEN b, GEN c, GEN d} creates the $2$ by $2$ 11466\typ{MAT} with successive rows $[a,b]$ and $[c,d]$. 11467 11468\fun{GEN}{mkmat3}{GEN x, GEN y, GEN z} creates a 3-column \typ{MAT} with columns 11469$x$, $y$, $z$ (\typ{COL}s of the same length). 11470 11471\fun{GEN}{mkmat4}{GEN x, GEN y, GEN z, GEN t} creates a 4-column \typ{MAT} 11472with columns $x$, $y$, $z$, $t$ (\typ{COL}s of the same length). 11473 11474\fun{GEN}{mkmat5}{GEN x, GEN y, GEN z, GEN t, GEN u} creates a 5-column 11475\typ{MAT} with columns $x$, $y$, $z$, $t$, $u$ (\typ{COL}s of the same 11476length). 11477 11478\fun{GEN}{mkvec}{GEN x} creates a 1-dimensional \typ{VEC} containing \kbd{x}. 11479 11480\fun{GEN}{mkvec2}{GEN x, GEN y} creates a 2-dimensional \typ{VEC} equal to 11481\kbd{[x,y]}. 11482 11483\fun{GEN}{mkvec3}{GEN x, GEN y, GEN z} creates a 3-dimensional \typ{VEC} 11484equal to \kbd{[x,y,z]}. 11485 11486\fun{GEN}{mkvec4}{GEN x, GEN y, GEN z, GEN t} creates a 4-dimensional \typ{VEC} 11487equal to \kbd{[x,y,z,t]}. 11488 11489\fun{GEN}{mkvec5}{GEN a1, GEN a2, GEN a3, GEN a4, GEN a5} creates the 114905-dimensional \typ{VEC} equal to $[a_1,a_2,a_3,a_4,a_5]$. 11491 11492\fun{GEN}{mkqfi}{GEN x, GEN y, GEN z} creates \typ{QFI} equal 11493to \kbd{Qfb(x,y,z)}, assuming that $y^2 - 4xz < 0$. 11494 11495\fun{GEN}{mkerr}{long n} returns a \typ{ERROR} with error code $n$ 11496(\kbd{enum err\_list}). 11497 11498\smallskip 11499 11500It is sometimes useful to return such a container whose entries are not 11501universal objects, but nonetheless suitable for \tet{gerepileupto}. 11502If the entries can be computed at the time the result is returned, the 11503following macros achieve this effect: 11504 11505\fun{GEN}{retmkvec}{GEN x} returns a vector containing the single entry $x$, 11506where the vector root is created just before the function argument $x$ is 11507evaluated. Expands to 11508\bprog 11509 { 11510 GEN res = cgetg(2, t_VEC); 11511 gel(res, 1) = x; /* @Ccom or rather, the \emph{expansion} of $x$ */ 11512 return res; 11513 } 11514@eprog\noindent For instance, the \kbd{retmkvec(gcopy(x))} returns a clean 11515object, just like \kbd{return mkveccopy(x)} would. 11516 11517\fun{GEN}{retmkvec2}{GEN x, GEN y} 11518returns the $2$-dimensional \typ{VEC} \kbd{[x,y]}. 11519 11520\fun{GEN}{retmkvec3}{GEN x, GEN y, GEN z} 11521returns the $3$-dimensional \typ{VEC} \kbd{[x,y,z]}. 11522 11523\fun{GEN}{retmkvec4}{GEN x, GEN y, GEN z, GEN t} 11524returns the $4$-dimensional \typ{VEC} \kbd{[x,y,z,t]}. 11525 11526\fun{GEN}{retmkvec5}{GEN x, GEN y, GEN z, GEN t, GEN u} 11527returns the $5$-dimensional row vector \kbd{[x,y,z,t,u]}. 11528 11529\fun{GEN}{retconst_vec}{long n, GEN x} 11530returns the $n$-dimensional \typ{VEC} whose entries are constant and all 11531equal to $x$. 11532 11533\fun{GEN}{retmkcol}{GEN x} 11534returns the $1$-dimensional \typ{COL} \kbd{[x]~}. 11535 11536\fun{GEN}{retmkcol2}{GEN x, GEN y} 11537returns the $2$-dimensional \typ{COL} \kbd{[x,y]~}. 11538 11539\fun{GEN}{retmkcol3}{GEN x, GEN y, GEN z} 11540returns the $3$-dimensional \typ{COL} \kbd{[x,y,z]~}. 11541 11542\fun{GEN}{retmkcol4}{GEN x, GEN y, GEN z, GEN t} 11543returns the $4$-dimensional \typ{COL} \kbd{[x,y,z,t]~}. 11544 11545\fun{GEN}{retmkcol5}{GEN x, GEN y, GEN z, GEN t, GEN u} 11546returns the $5$-dimensional column vector \kbd{[x,y,z,t,u]~}. 11547 11548\fun{GEN}{retmkcol6}{GEN x, GEN y, GEN z, GEN t, GEN u, GEN v} 11549returns the $6$-dimensional column vector \kbd{[x,y,z,t,u,v]~}. 11550 11551\fun{GEN}{retconst_col}{long n, GEN x} 11552returns the $n$-dimensional \typ{COL} whose entries are constant and all 11553equal to $x$. 11554 11555\fun{GEN}{retmkmat}{GEN x} 11556returns the $1$-column \typ{MAT} with colum \kbd{x}. 11557 11558\fun{GEN}{retmkmat2}{GEN x, GEN y} 11559returns the $2$-column \typ{MAT} with columns \kbd{x}, \kbd{y}. 11560 11561\fun{GEN}{retmkmat3}{GEN x, GEN y, GEN z} 11562returns the $3$-dimensional \typ{MAT} with columns 11563\kbd{x}, \kbd{y}, \kbd{z}. 11564 11565\fun{GEN}{retmkmat4}{GEN x, GEN y, GEN z, GEN t} 11566returns the $4$-dimensional \typ{MAT} with columns 11567\kbd{x}, \kbd{y}, \kbd{z}, \kbd{t}. 11568 11569\fun{GEN}{retmkmat5}{GEN x, GEN y, GEN z, GEN t, GEN u} 11570returns the $5$-dimensional \typ{MAT} with columns 11571\kbd{x}, \kbd{y}, \kbd{z}, \kbd{t}, \kbd{u}. 11572 11573\fun{GEN}{retmkcomplex}{GEN x, GEN y} 11574returns the \typ{COMPLEX} \kbd{x + I*y}. 11575 11576\fun{GEN}{retmkfrac}{GEN x, GEN y} 11577returns the \typ{FRAC} \kbd{x / y}. Assume $x$ and $y$ are coprime and $y > 1$. 11578 11579\fun{GEN}{retmkrfrac}{GEN x, GEN y} 11580returns the \typ{RFRAC} \kbd{x / y}. Assume $x$ and $y$ are coprime and more 11581generally that the rational function cannot be simplified. 11582 11583\fun{GEN}{retmkintmod}{GEN x, GEN y} 11584returns the \typ{INTMOD} \kbd{Mod(x, y)}. 11585 11586\fun{GEN}{retmkqfi}{GEN a, GEN b, GEN c}. 11587 11588\fun{GEN}{retmkqfr}{GEN a, GEN b, GEN c, GEN d}. 11589 11590\fun{GEN}{retmkquad}{GEN n, GEN a, GEN b}. 11591 11592\fun{GEN}{retmkpolmod}{GEN x, GEN y} 11593returns the \typ{POLMOD} \kbd{Mod(x, y)}. 11594 11595\smallskip 11596 11597\fun{GEN}{mkintn}{long n, ...} returns the nonnegative \typ{INT} whose 11598development in base $2^{32}$ is given by the following $n$ 32bit-words 11599(\kbd{unsigned int}). 11600\bprog 11601 mkintn(3, a2, a1, a0); 11602@eprog 11603\noindent returns $a_2 2^{64} + a_1 2^{32} + a_0$. 11604 11605\fun{GEN}{mkpoln}{long n, ...} Returns the \typ{POL} whose $n$ 11606coefficients (\kbd{GEN}) follow, in order of decreasing degree. 11607\bprog 11608 mkpoln(3, gen_1, gen_2, gen_0); 11609@eprog 11610\noindent returns the polynomial $X^2 + 2X$ (in variable $0$, use 11611\tet{setvarn} if you want other variable numbers). Beware that $n$ is the 11612number of coefficients, hence \emph{one more} than the degree. 11613 11614\fun{GEN}{mkvecn}{long n, ...} returns the \typ{VEC} whose $n$ 11615coefficients (\kbd{GEN}) follow. 11616 11617\fun{GEN}{mkcoln}{long n, ...} returns the \typ{COL} whose $n$ 11618coefficients (\kbd{GEN}) follow. 11619 11620\fun{GEN}{scalarcol_shallow}{GEN x, long n} creates a \typ{COL} with \kbd{n} 11621components set to \kbd{gen\_0}, but the first one which is set to a shallow 11622copy of \kbd{x}. (The name comes from \kbd{RgV\_isscalar}.) 11623 11624\fun{GEN}{scalarmat_shallow}{GEN x, long n} creates an $n\times n$ 11625scalar matrix whose diagonal is set to shallow copies of the scalar \kbd{x}. 11626 11627\fun{GEN}{RgX_sylvestermatrix}{GEN f, GEN g} return the Sylvester matrix 11628attached to the two \typ{POL} in the same variable $f$ and $g$. 11629 11630\fun{GEN}{diagonal_shallow}{GEN x} returns a diagonal matrix whose diagonal 11631is given by the vector $x$. Shallow function. 11632 11633\fun{GEN}{scalarpol_shallow}{GEN a, long v} returns the degree $0$ 11634\typ{POL} $a \kbd{pol\_x}(v)^0$. 11635 11636\fun{GEN}{deg1pol_shallow}{GEN a, GEN b,long v} returns the degree $1$ 11637\typ{POL} $a\kbd{pol\_x}(v) + b$ 11638 11639\fun{GEN}{deg2pol_shallow}{GEN a, GEN b, GEN c, long v} returns the degree $2$ 11640\typ{POL} $a\*x^2+b\*x+c$ where $x=\kbd{pol\_x}(v)$. 11641 11642\fun{GEN}{zeropadic_shallow}{GEN p, long n} returns a (shallow) $0$ 11643\typ{PADIC} equal to $O(\kbd{p}^\kbd{n})$. 11644 11645\subsec{From roots to polynomials} 11646 11647\fun{GEN}{deg1_from_roots}{GEN L, long v} given a vector $L$ of scalars, 11648returns the vector of monic linear polynomials in variable $v$ whose roots 11649are the $L[i]$, i.e. the $x - L[i]$. 11650 11651\fun{GEN}{roots_from_deg1}{GEN L} given a vector $L$ of monic linear 11652polynomials, return their roots, i.e. the $- L[i](0)$. 11653 11654\fun{GEN}{roots_to_pol}{GEN L, long v} given a vector of scalars $L$, 11655returns the monic polynomial in variable $v$ whose roots are the $L[i]$. 11656Leaves some garbage on stack, but suitable for \kbd{gerepileupto}. 11657 11658\fun{GEN}{roots_to_pol_r1}{GEN L, long v, long r1} as \kbd{roots\_to\_pol} 11659assuming the first $r_1$ roots are ``real'', and the following ones are 11660representatives of conjugate pairs of ``complex'' roots. So if $L$ has $r_1 + 11661r_2$ elements, we obtain a polynomial of degree $r_1 + 2r_2$. In most 11662applications, the roots are indeed real and complex, but the implementation 11663assumes only that each ``complex'' root $z$ introduces a quadratic 11664factor $X^2 - \kbd{trace}(z) X + \kbd{norm}(z)$. 11665Leaves some garbage on stack, but suitable for \kbd{gerepileupto}. 11666 11667\section{Integer parts} 11668 11669\fun{GEN}{gfloor}{GEN x} creates the floor of~\kbd{x}, i.e.\ the (true) 11670integral part. 11671 11672\fun{GEN}{gfrac}{GEN x} creates the fractional part of~\kbd{x}, i.e.\ \kbd{x} 11673minus the floor of~\kbd{x}. 11674 11675\fun{GEN}{gceil}{GEN x} creates the ceiling of~\kbd{x}. 11676 11677\fun{GEN}{ground}{GEN x} rounds towards~$+\infty$ the components of \kbd{x} 11678to the nearest integers. 11679 11680\fun{GEN}{grndtoi}{GEN x, long *e} same as \kbd{ground}, but in addition sets 11681\kbd{*e} to the binary exponent of $x - \kbd{ground}(x)$. If this is 11682positive, all significant bits are lost. This kind of situation raises an 11683error message in \key{ground} but not in \key{grndtoi}. 11684 11685\fun{GEN}{gtrunc}{GEN x} truncates~\kbd{x}. This is the false integer part 11686if \kbd{x} is a real number (i.e.~the unique integer closest to \kbd{x} among 11687those between 0 and~\kbd{x}). If \kbd{x} is a \typ{SER}, it is truncated 11688to a \typ{POL}; if \kbd{x} is a \typ{RFRAC}, this takes the polynomial part. 11689 11690\fun{GEN}{gtrunc2n}{GEN x, long n} creates the floor of~$2^n$\kbd{x}, this is 11691only implemented for \typ{INT}, \typ{REAL}, \typ{FRAC} and \typ{COMPLEX} of 11692those. 11693 11694\fun{GEN}{gcvtoi}{GEN x, long *e} analogous to \key{grndtoi} for 11695\typ{REAL} inputs except that rounding is replaced by truncation. Also applies 11696componentwise for vector or matrix inputs; otherwise, sets \kbd{*e} to 11697\kbd{-HIGHEXPOBIT} (infinite real accuracy) and return \kbd{gtrunc(x)}. 11698 11699\section{Valuation and shift} 11700 11701\fun{GEN}{gshift[z]}{GEN x, long n[, GEN z]} yields the result of shifting 11702(the components of) \kbd{x} left by \kbd{n} (if \kbd{n} is nonnegative) 11703or right by $-\kbd{n}$ (if \kbd{n} is negative). Applies only to \typ{INT} 11704and vectors/matrices of such. For other types, it is simply multiplication 11705by~$2^{\kbd{n}}$. 11706 11707\fun{GEN}{gmul2n[z]}{GEN x, long n[, GEN z]} yields the product of \kbd{x} 11708and~$2^{\kbd{n}}$. This is different from \kbd{gshift} when \kbd{n} is negative 11709and \kbd{x} is a \typ{INT}: \key{gshift} truncates, while \key{gmul2n} 11710creates a fraction if necessary. 11711 11712\fun{long}{gvaluation}{GEN x, GEN p} returns the greatest exponent~$e$ such that 11713$\kbd{p}^e$ divides~\kbd{x}, when this makes sense. 11714 11715\fun{long}{gval}{GEN x, long v} returns the highest power of the variable 11716number \kbd{v} dividing the \typ{POL}~\kbd{x}. 11717 11718\section{Comparison operators} 11719 11720\subsec{Generic} 11721 11722\fun{long}{gcmp}{GEN x, GEN y} comparison of \kbd{x} with \kbd{y}: returns 11723$1$ ($x > y$), $0$ ($x = y$) or $-1$ ($x < y$). Two \typ{STR} 11724are compared using the standard lexicographic ordering; a \typ{STR} 11725cannot be compared to any non-string type. If neither 11726$x$ nor $y$ is a \typ{STR}, their allowed types are \typ{INT}, \typ{REAL}, 11727\typ{FRAC}, \typ{QUAD} with positive discriminant (use the canonical 11728embedding $w \to \sqrt{D}/2$ or $w \to (1 + \sqrt{D})/2$) or \typ{INFINITY}. 11729Use \tet{cmp_universal} to compare arbitrary \kbd{GEN}s. 11730 11731\fun{long}{lexcmp}{GEN x, GEN y} comparison of \kbd{x} with \kbd{y} for the 11732lexicographic ordering; when comparing objects of different lengths whose 11733components are all equal up to the smallest of their length, consider that 11734the longest is largest. Consider scalars as $1$-component vectors. Return 11735\kbd{gcmp}$(x,y)$ if both arguments are scalars. 11736 11737\fun{int}{gequalX}{GEN x} return 1 (true) if \kbd{x} is a variable 11738(monomial of degree $1$ with \typ{INT} coefficients equal to $1$ and $0$), 11739and $0$ otherwise 11740 11741\fun{long}{gequal}{GEN x, GEN y} returns 1 (true) if \kbd{x} is equal 11742to~\kbd{y}, 0~otherwise. A priori, this makes sense only if \kbd{x} and 11743\kbd{y} have the same type, in which case they are recursively compared 11744componentwise. When the types are different, a \kbd{true} result 11745means that \kbd{x - y} was successfully computed and that 11746\kbd{gequal0} found it equal to $0$. In particular 11747\bprog 11748 gequal(cgetg(1, t_VEC), gen_0) 11749@eprog\noindent is true, and the relation is not transitive. E.g.~an empty 11750\typ{COL} and an empty \typ{VEC} are not equal but are both equal to 11751\kbd{gen\_0}. 11752 11753\fun{long}{gidentical}{GEN x, GEN y} returns 1 (true) if \kbd{x} is identical 11754to~\kbd{y}, 0~otherwise. In particular, the types and length of \kbd{x} and 11755\kbd{y} must be equal. This test is much stricter than \tet{gequal}, in 11756particular, \typ{REAL} with different accuracies are tested different. This 11757relation is transitive. 11758 11759\fun{GEN}{gmax}{GEN x, GEN y} returns a copy of the maximum of $x$ and $y$, 11760compared using \kbd{gcmp}. 11761 11762\fun{GEN}{gmin}{GEN x, GEN y} returns a copy of the minimum of $x$ and $y$, 11763compared using \kbd{gcmp}. 11764 11765\fun{GEN}{gmax_shallow}{GEN x, GEN y} shallow version of \kbd{gmax}. 11766 11767\fun{GEN}{gmin_shallow}{GEN x, GEN y} shallow version of \kbd{gmin}. 11768 11769\subsec{Comparison with a small integer} 11770 11771\fun{int}{isexactzero}{GEN x} returns 1 (true) if \kbd{x} is exactly equal 11772to~0 (including \typ{INTMOD}s like \kbd{Mod(0,2)}), and 0~(false) otherwise. 11773This includes recursive objects, for instance vectors, whose components are $0$. 11774 11775\fun{GEN}{gisexactzero}{GEN x} returns \kbd{NULL} unless \kbd{x} is exactly 11776equal to~0 (as per \kbd{isexactzero}). When \kbd{x} is an exact zero 11777return the attached scalar zero as a \typ{INT} (\kbd{gen\_0}), 11778a \typ{INTMOD} (\kbd{Mod(0,$N$)} for the largest possible $N$) or a 11779\typ{FFELT}. 11780 11781\fun{int}{isrationalzero}{GEN x} returns 1 (true) if \kbd{x} is equal 11782to an integer~0 (excluding \typ{INTMOD}s like \kbd{Mod(0,2)}), and 0~(false) 11783otherwise. Contrary to \kbd{isintzero}, this includes recursive objects, for 11784instance vectors, whose components are $0$. 11785 11786\fun{int}{ismpzero}{GEN x} returns 1 (true) if \kbd{x} is a \typ{INT} or 11787a \typ{REAL} equal to~0. 11788 11789\fun{int}{isintzero}{GEN x} returns 1 (true) if \kbd{x} is a \typ{INT} 11790equal to~0. 11791 11792\fun{int}{isint1}{GEN x} returns 1 (true) if \kbd{x} is a \typ{INT} 11793equal to~1. 11794 11795\fun{int}{isintm1}{GEN x} returns 1 (true) if \kbd{x} is a \typ{INT} 11796equal to~$-1$. 11797 11798\fun{int}{equali1}{GEN n} 11799Assuming that \kbd{x} is a \typ{INT}, return 1 (true) if \kbd{x} is equal to 11800$1$, and return 0~(false) otherwise. 11801 11802\fun{int}{equalim1}{GEN n} 11803Assuming that \kbd{x} is a \typ{INT}, return 1 (true) if \kbd{x} is equal to 11804$-1$, and return 0~(false) otherwise. 11805 11806\fun{int}{is_pm1}{GEN x}. Assuming that \kbd{x} is a 11807\emph{nonzero} \typ{INT}, return 1 (true) if \kbd{x} is equal to $-1$ or 11808$1$, and return 0~(false) otherwise. 11809 11810\fun{int}{gequal0}{GEN x} returns 1 (true) if \kbd{x} is equal to~0, 0~(false) 11811otherwise. 11812 11813\fun{int}{gequal1}{GEN x} returns 1 (true) if \kbd{x} is equal to~1, 0~(false) 11814otherwise. 11815 11816\fun{int}{gequalm1}{GEN x} returns 1 (true) if \kbd{x} is equal to~$-1$, 118170~(false) otherwise. 11818 11819 11820\fun{long}{gcmpsg}{long s, GEN x} 11821 11822\fun{long}{gcmpgs}{GEN x, long s} comparison of \kbd{x} with the 11823\kbd{long}~\kbd{s}. 11824 11825\fun{GEN}{gmaxsg}{long s, GEN x} 11826 11827\fun{GEN}{gmaxgs}{GEN x, long s} returns the largest of \kbd{x} and 11828the \kbd{long}~\kbd{s} (converted to \kbd{GEN}) 11829 11830\fun{GEN}{gminsg}{long s, GEN x} 11831 11832\fun{GEN}{gmings}{GEN x, long s} returns the smallest of \kbd{x} and the 11833\kbd{long}~\kbd{s} (converted to \kbd{GEN}) 11834 11835\fun{long}{gequalsg}{long s, GEN x} 11836 11837\fun{long}{gequalgs}{GEN x, long s} returns 1 (true) if \kbd{x} is equal to 11838the \kbd{long}~\kbd{s}, 0~otherwise. 11839 11840\section{Miscellaneous Boolean functions} 11841 11842\fun{int}{isrationalzeroscalar}{GEN x} equivalent to, but faster than, 11843\bprog 11844 is_scalar_t(typ(x)) && isrationalzero(x) 11845@eprog 11846 11847\fun{int}{isinexact}{GEN x} returns 1 (true) if $x$ has an inexact 11848component, and 0 (false) otherwise. 11849 11850\fun{int}{isinexactreal}{GEN x} return 1 if $x$ has an inexact 11851\typ{REAL} component, and 0 otherwise. 11852 11853\fun{int}{isrealappr}{GEN x, long e} applies (recursively) to complex inputs; 11854returns $1$ if $x$ is approximately real to the bit accuracy $e$, and 0 11855otherwise. This means that any \typ{COMPLEX} component must have imaginary part 11856$t$ satisfying $\kbd{gexpo}(t) < e$. 11857 11858\fun{int}{isint}{GEN x, GEN *n} returns 0 (false) if \kbd{x} does not round 11859to an integer. Otherwise, returns 1 (true) and set \kbd{n} to the rounded 11860value. 11861 11862\fun{int}{issmall}{GEN x, long *n} returns 0 (false) if \kbd{x} does not 11863round to a small integer (suitable for \kbd{itos}). Otherwise, returns 1 11864(true) and set \kbd{n} to the rounded value. 11865 11866\fun{long}{iscomplex}{GEN x} returns 1 (true) if \kbd{x} is a complex number 11867(of component types embeddable into the reals) but is not itself real, 0~if 11868\kbd{x} is a real (not necessarily of type \typ{REAL}), or raises an error if 11869\kbd{x} is not embeddable into the complex numbers. 11870 11871\subsec{Obsolete} 11872 11873The following less convenient comparison functions and Boolean operators were 11874used by the historical GP interpreter. They are provided for backward 11875compatibility only and should not be used: 11876 11877\fun{GEN}{gle}{GEN x, GEN y} 11878 11879\fun{GEN}{glt}{GEN x, GEN y} 11880 11881\fun{GEN}{gge}{GEN x, GEN y} 11882 11883\fun{GEN}{ggt}{GEN x, GEN y} 11884 11885\fun{GEN}{geq}{GEN x, GEN y} 11886 11887\fun{GEN}{gne}{GEN x, GEN y} 11888 11889\fun{GEN}{gor}{GEN x, GEN y} 11890 11891\fun{GEN}{gand}{GEN x, GEN y} 11892 11893\fun{GEN}{gnot}{GEN x, GEN y} 11894 11895\section{Sorting} 11896 11897\subsec{Basic sort} 11898 11899\fun{GEN}{sort}{GEN x} sorts the vector \kbd{x} in ascending order using a 11900mergesort algorithm, and \kbd{gcmp} as the underlying comparison routine 11901(returns the sorted vector). This routine copies all components of $x$, use 11902\kbd{gen\_sort\_inplace} for a more memory-efficient function. 11903 11904\fun{GEN}{lexsort}{GEN x}, as \kbd{sort}, using \kbd{lexcmp} instead of 11905\kbd{gcmp} as the underlying comparison routine. 11906 11907\fun{GEN}{vecsort}{GEN x, GEN k}, as \kbd{sort}, but sorts the 11908vector \kbd{x} in ascending \emph{lexicographic} order, according to the 11909entries of the \typ{VECSMALL} \kbd{k}. For example, if $\kbd{k} = [2,1,3]$, 11910sorting will be done with respect to the second component, and when these 11911are equal, with respect to the first, and when these are equal, with 11912respect to the third. 11913 11914\subsec{Indirect sorting} 11915 11916\fun{GEN}{indexsort}{GEN x} as \kbd{sort}, but only returns the permutation 11917which, applied to \kbd{x}, would sort the vector. The result is a 11918\typ{VECSMALL}. 11919 11920\fun{GEN}{indexlexsort}{GEN x}, as \kbd{indexsort}, using \kbd{lexcmp} 11921instead of \kbd{gcmp} as the underlying comparison routine. 11922 11923\fun{GEN}{indexvecsort}{GEN x, GEN k}, as \kbd{vecsort}, but only 11924returns the permutation that would sort the vector \kbd{x}. 11925 11926\fun{long}{vecindexmin}{GEN x} returns the index for a maximal element of $x$ 11927(\typ{VEC}, \typ{COL} or \typ{VECSMALL}). 11928 11929\fun{long}{vecindexmax}{GEN x} returns the index for a maximal element of $x$ 11930(\typ{VEC}, \typ{COL} or \typ{VECSMALL}). 11931 11932\fun{long}{vecindexmax}{GEN x} 11933 11934\subsec{Generic sort and search} The following routines allow to use an 11935arbitrary comparison function \kbd{int (*cmp)(void* data, GEN x, GEN y)}, 11936such that \kbd{cmp(data,x,y)} returns a negative result if $x 11937< y$, a positive one if $x > y$ and 0 if $x = y$. The \kbd{data} argument is 11938there in case your \kbd{cmp} requires additional context. 11939 11940\fun{GEN}{gen_sort}{GEN x, void *data, int (*cmp)(void *,GEN,GEN)}, as 11941\kbd{sort}, with an explicit comparison routine. 11942 11943\fun{GEN}{gen_sort_shallow}{GEN x, void *data, int (*cmp)(void *,GEN,GEN)}, 11944shallow variant of \kbd{gen\_sort}. 11945 11946\fun{GEN}{gen_sort_uniq}{GEN x, void *data, int (*cmp)(void *,GEN,GEN)}, as 11947\kbd{gen\_sort}, removing duplicate entries. 11948 11949\fun{GEN}{gen_indexsort}{GEN x, void *data, int (*cmp)(void*,GEN,GEN)}, 11950as \kbd{indexsort}. 11951 11952\fun{GEN}{gen_indexsort_uniq}{GEN x, void *data, int (*cmp)(void*,GEN,GEN)}, 11953as \kbd{indexsort}, removing duplicate entries. 11954 11955\fun{void}{gen_sort_inplace}{GEN x, void *data, int (*cmp)(void*,GEN,GEN), GEN 11956*perm} sort \kbd{x} in place, without copying its components. If 11957\kbd{perm} is not \kbd{NULL}, it is set to the permutation that would sort 11958the original \kbd{x}. 11959 11960\fun{GEN}{gen_setminus}{GEN A, GEN B, int (*cmp)(GEN,GEN)} given two sorted 11961vectors $A$ and $B$, returns the vector of elements of $A$ not belonging to 11962$B$. 11963 11964\fun{GEN}{sort_factor}{GEN y, void *data, int (*cmp)(void *,GEN,GEN)}: 11965assuming \kbd{y} is a factorization matrix, sorts its rows in place (no copy 11966is made) according to the comparison function \kbd{cmp} applied to its first 11967column. 11968 11969\fun{GEN}{merge_sort_uniq}{GEN x,GEN y, void *data, int (*cmp)(void *,GEN,GEN)} 11970assuming \kbd{x} and \kbd{y} are sorted vectors, with respect to the \kbd{cmp} 11971comparison function, return a sorted concatenation, with duplicates removed. 11972Shallow function. 11973 11974\fun{GEN}{setunion_i}{GEN x,GEN y} shallow version of \kbd{setunion}, a 11975simple alias for 11976\bprog 11977 merge_sort_uniq(x,y, (void*)cmp_universal, cmp_nodata) 11978@eprog 11979 11980\fun{GEN}{merge_factor}{GEN fx, GEN fy, void *data, int (*cmp)(void *,GEN,GEN)} 11981let \kbd{fx} and \kbd{fy} be factorization matrices for $X$ and $Y$ 11982sorted with respect to the comparison function \kbd{cmp} (see 11983\tet{sort_factor}), returns the factorization of $X * Y$. 11984 11985\fun{long}{gen_search}{GEN v, GEN y, long flag, void *data, int 11986(*cmp)(void*,GEN,GEN)}.\hfil\break 11987Let \kbd{v} be a vector sorted according to \kbd{cmp(data,a,b)}; look for an 11988index $i$ such that \kbd{v[$i$]} is equal to \kbd{y}. \kbd{flag} has the 11989same meaning as in \kbd{setsearch}: if \kbd{flag} is 0, return $i$ if it 11990exists and 0 otherwise; if \kbd{flag} is nonzero, return $0$ if $i$ exists 11991and the index where \kbd{y} should be inserted otherwise. 11992 11993\fun{long}{tablesearch}{GEN T, GEN x, int (*cmp)(GEN,GEN)} is a faster 11994implementation for the common case \kbd{gen\_search(T,x,0,cmp,cmp\_nodata)}. 11995 11996\subsec{Further useful comparison functions} 11997 11998\fun{int}{cmp_universal}{GEN x, GEN y} a somewhat arbitrary universal 11999comparison function, devoid of sensible mathematical meaning. It is 12000transitive, and returns 0 if and only if \kbd{gidentical(x,y)} is true. 12001Useful to sort and search vectors of arbitrary data. 12002 12003\fun{int}{cmp_nodata}{void *data, GEN x, GEN y}. This function is a hack 12004used to pass an existing basic comparison function lacking the \kbd{data} 12005argument, i.e. with prototype \kbd{int (*cmp)(GEN x, GEN y)}. Instead of 12006\kbd{gen\_sort(x, NULL, cmp)} which may or may not work depending on how your 12007compiler handles typecasts between incompatible function pointers, one should 12008use \kbd{gen\_sort(x, (void*)cmp, cmp\_nodata)}. 12009 12010Here are a few basic comparison functions, to be used with \kbd{cmp\_nodata}: 12011 12012\fun{int}{ZV_cmp}{GEN x, GEN y} compare two \kbd{ZV}, which we assume have 12013the same length (lexicographic order). 12014 12015\fun{int}{cmp_Flx}{GEN x, GEN y} compare two \kbd{Flx}, which we assume 12016have the same main variable (lexicographic order). 12017 12018\fun{int}{cmp_RgX}{GEN x, GEN y} compare two polynomials, which we assume 12019have the same main variable (lexicographic order). The coefficients are 12020compared using \kbd{gcmp}. 12021 12022\fun{int}{cmp_prime_over_p}{GEN x, GEN y} compare two prime ideals, which 12023we assume divide the same prime number. The comparison is ad hoc but orders 12024according to increasing residue degrees. 12025 12026\fun{int}{cmp_prime_ideal}{GEN x, GEN y} compare two prime ideals in the same 12027\var{nf}. Orders by increasing primes, breaking ties using 12028\kbd{cmp\_prime\_over\_p}. 12029 12030\fun{int}{cmp_padic}{GEN x, GEN y} compare two \typ{PADIC} (for the same 12031prime $p$). 12032 12033Finally a more elaborate comparison function: 12034 12035\fun{int}{gen_cmp_RgX}{void *data, GEN x, GEN y} compare two polynomials, 12036ordering first by increasing degree, then according to the coefficient 12037comparison function: 12038\bprog 12039 int (*cmp_coeff)(GEN,GEN) = (int(*)(GEN,GEN)) data; 12040@eprog 12041 12042\section{Divisibility, Euclidean division} 12043 12044\fun{GEN}{gdivexact}{GEN x, GEN y} returns the quotient $\kbd{x} / \kbd{y}$, 12045assuming $\kbd{y}$ divides $\kbd{x}$. Not stack clean if $y = 1$ 12046(we return $x$, not a copy). 12047 12048\fun{int}{gdvd}{GEN x, GEN y} returns 1 (true) if \kbd{y} divides~\kbd{x}, 120490~otherwise. 12050 12051\fun{GEN}{gdiventres}{GEN x, GEN y} creates a 2-component vertical 12052vector whose components are the true Euclidean quotient and remainder 12053of \kbd{x} and~\kbd{y}. 12054 12055\fun{GEN}{gdivent[z]}{GEN x, GEN y[, GEN z]} yields the true Euclidean 12056quotient of \kbd{x} and the \typ{INT} or \typ{POL}~\kbd{y}, as per 12057the \kbd{\bs} GP operator. 12058 12059\fun{GEN}{gdiventsg}{long s, GEN y[, GEN z]}, as \kbd{gdivent} 12060except that \kbd{x} is a \kbd{long}. 12061 12062\fun{GEN}{gdiventgs[z]}{GEN x, long s[, GEN z]}, as \kbd{gdivent} 12063except that \kbd{y} is a \kbd{long}. 12064 12065\fun{GEN}{gmod[z]}{GEN x, GEN y[, GEN z]} yields the remainder of \kbd{x} 12066modulo the \typ{INT} or \typ{POL}~\kbd{y}, as per the \kbd{\%} GP operator. 12067A \typ{REAL} or \typ{FRAC} \kbd{y} is also allowed, in which case the 12068remainder is the unique real $r$ such that $0 \leq r < |\kbd{y}|$ and 12069$\kbd{y} = q\kbd{x} + r$ for some (in fact unique) integer $q$. 12070 12071\fun{GEN}{gmodsg}{long s, GEN y[, GEN z]} as \kbd{gmod}, except \kbd{x} is 12072a \kbd{long}. 12073 12074\fun{GEN}{gmodgs}{GEN x, long s[, GEN z]} as \kbd{gmod}, except \kbd{y} is 12075a \kbd{long}. 12076 12077\fun{GEN}{gdivmod}{GEN x, GEN y, GEN *r} If \kbd{r} is not equal to 12078\kbd{NULL} or \kbd{ONLY\_REM}, creates the (false) Euclidean quotient of 12079\kbd{x} and~\kbd{y}, and puts (the address of) the remainder into~\kbd{*r}. 12080If \kbd{r} is equal to \kbd{NULL}, do not create the remainder, and if 12081\kbd{r} is equal to \kbd{ONLY\_REM}, create and output only the remainder. 12082The remainder is created after the quotient and can be disposed of 12083individually with a \kbd{cgiv(r)}. 12084 12085\fun{GEN}{poldivrem}{GEN x, GEN y, GEN *r} same as \key{gdivmod} but 12086specifically for \typ{POL}s~\kbd{x} and~\kbd{y}, not necessarily in the same 12087variable. Either of \kbd{x} and \kbd{y} may also be scalars, treated as 12088polynomials of degree $0$. 12089 12090\fun{GEN}{gdeuc}{GEN x, GEN y} creates the Euclidean quotient of the 12091\typ{POL}s~\kbd{x} and~\kbd{y}. Either of \kbd{x} and \kbd{y} may also be 12092scalars, treated as polynomials of degree $0$. 12093 12094\fun{GEN}{grem}{GEN x, GEN y} creates the Euclidean remainder of the 12095\typ{POL}~\kbd{x} divided by the \typ{POL}~\kbd{y}. Either of \kbd{x} and 12096\kbd{y} may also be scalars, treated as polynomials of degree $0$. 12097 12098 12099\fun{GEN}{gdivround}{GEN x, GEN y} if \kbd{x} and \kbd{y} are real 12100(\typ{INT}, \typ{REAL}, \typ{FRAC}), return the rounded Euclidean quotient of 12101$x$ and $y$ as per the \kbd{\bs/} GP operator. Operate componentwise if 12102\kbd{x} is a \typ{COL}, \typ{VEC} or \typ{MAT}. Otherwise as \key{gdivent}. 12103 12104\fun{GEN}{centermod_i}{GEN x, GEN y, GEN y2}, as \kbd{centermodii}, 12105componentwise. 12106 12107\fun{GEN}{centermod}{GEN x, GEN y}, as \kbd{centermod\_i}, except that 12108\kbd{y2} is computed (and left on the stack for efficiency). 12109 12110\fun{GEN}{ginvmod}{GEN x, GEN y} creates the inverse of \kbd{x} modulo \kbd{y} 12111when it exists. \kbd{y} must be of type \typ{INT} (in which case \kbd{x} is 12112of type \typ{INT}) or \typ{POL} (in which case \kbd{x} is either a scalar 12113type or a \typ{POL}). 12114 12115\section{GCD, content and primitive part} 12116 12117\subsec{Generic} 12118 12119\fun{GEN}{resultant}{GEN x, GEN y} creates the resultant of the \typ{POL}s 12120\kbd{x} and~\kbd{y} computed using Sylvester's matrix (inexact inputs), a 12121modular algorithm (inputs in $\Q[X]$) or the subresultant algorithm, as 12122optimized by Lazard and Ducos. Either of \kbd{x} and \kbd{y} may also be 12123scalars (treated as polynomials of degree $0$) 12124 12125\fun{GEN}{ggcd}{GEN x, GEN y} creates the GCD of \kbd{x} and~\kbd{y}. 12126 12127\fun{GEN}{glcm}{GEN x, GEN y} creates the LCM of \kbd{x} and~\kbd{y}. 12128 12129\fun{GEN}{gbezout}{GEN x,GEN y, GEN *u,GEN *v} returns the GCD of \kbd{x} 12130and~\kbd{y}, and puts (the addresses of) objects $u$ and~$v$ such that 12131$u\kbd{x}+v\kbd{y}=\gcd(\kbd{x},\kbd{y})$ into \kbd{*u} and~\kbd{*v}. 12132 12133\fun{GEN}{subresext}{GEN x, GEN y, GEN *U, GEN *V} returns the resultant 12134of \kbd{x} and~\kbd{y}, and puts (the addresses of) polynomials $u$ and~$v$ 12135such that $u\kbd{x}+v\kbd{y}=\text{Res}(\kbd{x},\kbd{y})$ into \kbd{*U} 12136and~\kbd{*V}. 12137 12138\fun{GEN}{content}{GEN x} returns the GCD of all the components of~\kbd{x}. 12139 12140\fun{GEN}{primitive_part}{GEN x, GEN *c} sets \kbd{c} to \kbd{content(x)} 12141and returns the primitive part \kbd{x} / \kbd{c}. A trivial content is set to 12142\kbd{NULL}. 12143 12144\fun{GEN}{primpart}{GEN x} as above but the content is lost. 12145(For efficiency, the content remains on the stack.) 12146 12147\fun{GEN}{denom_i}{GEN x} shallow version of \kbd{denom}. 12148 12149\fun{GEN}{numer_i}{GEN x} shallow version of \kbd{numer}. 12150 12151\subsec{Over the rationals} 12152 12153\fun{long}{Q_pval}{GEN x, GEN p} valuation at the \typ{INT} \kbd{p} 12154of the \typ{INT} or \typ{FRAC}~\kbd{x}. 12155 12156\fun{long}{Q_lval}{GEN x, ulong p} same for \kbd{ulong} $p$. 12157 12158\fun{long}{Q_pvalrem}{GEN x, GEN p, GEN *r} returns the valuation $e$ at the 12159\typ{INT} \kbd{p} of the \typ{INT} or \typ{FRAC}~\kbd{x}. The quotient 12160$\kbd{x}/\kbd{p}^{e}$ is returned in~\kbd{*r}. 12161 12162\fun{long}{Q_lvalrem}{GEN x, ulong p, GEN *r} same for \kbd{ulong} $p$. 12163 12164\fun{GEN}{Q_abs}{GEN x} absolute value of the \typ{INT} or 12165\typ{FRAC}~\kbd{x}. 12166 12167\fun{GEN}{Qdivii}{GEN x, GEN y}, assuming $x$ and $y$ 12168are both of type \typ{INT}, return the quotient $x/y$ as a \typ{INT} or 12169\typ{FRAC}; marginally faster than \kbd{gdiv}. 12170 12171\fun{GEN}{Qdivis}{GEN x, long y}, assuming $x$ 12172is an \typ{INT}, return the quotient $x/y$ as a \typ{INT} or 12173\typ{FRAC}; marginally faster than \kbd{gdiv}. 12174 12175\fun{GEN}{Qdiviu}{GEN x, ulong y}, assuming $x$ 12176is an \typ{INT}, return the quotient $x/y$ as a \typ{INT} or 12177\typ{FRAC}; marginally faster than \kbd{gdiv}. 12178 12179\fun{GEN}{Q_abs_shallow}{GEN x} $x$ being a \typ{INT} or a \typ{FRAC}, returns 12180a shallow copy of $|x|$, in particular returns $x$ itself when $x \geq 0$, and 12181\kbd{gneg($x$)} otherwise. 12182 12183\fun{GEN}{Q_gcd}{GEN x, GEN y} gcd of the \typ{INT} or \typ{FRAC}~\kbd{x} 12184and~\kbd{y}. 12185\smallskip 12186 12187In the following functions, arguments belong to a $M\otimes_\Z\Q$ 12188for some natural $\Z$-module $M$, e.g. multivariate polynomials with integer 12189coefficients (or vectors/matrices recursively built from such objects), and 12190an element of $M$ is said to be \emph{integral}. 12191We are interested in contents, denominators, etc. with respect to this 12192canonical integral structure; in particular, contents belong to $\Q$, 12193denominators to $\Z$. For instance the $\Q$-content of $(1/2)xy$ is $(1/2)$, 12194and its $\Q$-denominator is $2$, whereas \kbd{content} would return $y/2$ and 12195\kbd{denom}~1. 12196 12197\fun{GEN}{Q_content}{GEN x} the $\Q$-content of $x$. 12198 12199\fun{GEN}{Z_content}{GEN x} as \kbd{Q\_content} but assume that all rationals 12200are in fact \typ{INT}s and return \kbd{NULL} when the content is $1$. This 12201function returns as soon as the content is found to equal $1$. 12202 12203\fun{GEN}{Q_content_safe}{GEN x} as \kbd{Q\_content}, returning 12204\kbd{NULL} when the $\Q$-content is not defined (e.g. for a \typ{REAL} 12205or \typ{INTMOD} component). 12206 12207\fun{GEN}{Q_denom}{GEN x} the $\Q$-denominator of $x$. Shallow function. 12208Raises en \kbd{e\_TYPE} error out when the notion is meaningless, e.g. for 12209a \typ{REAL} or \typ{INTMOD} component. 12210 12211\fun{GEN}{Q_denom_safe}{GEN x} the $\Q$-denominator of $x$. Shallow function. 12212Return \kbd{NULL} when the notion is meaningless. 12213 12214\fun{GEN}{Q_primitive_part}{GEN x, GEN *c} sets \kbd{c} to the $\Q$-content 12215of \kbd{x} and returns \kbd{x / c}, which is integral. 12216 12217\fun{GEN}{Q_primpart}{GEN x} as above but the content is lost. (For 12218efficiency, the content remains on the stack.) 12219 12220\fun{GEN}{vec_Q_primpart}{GEN x} as above component-wise. 12221 12222\fun{GEN}{Q_remove_denom}{GEN x, GEN *ptd} sets \kbd{d} to the 12223$\Q$-denominator of \kbd{x} and returns \kbd{x * d}, which is integral. 12224Shallow function. 12225 12226\fun{GEN}{Q_div_to_int}{GEN x, GEN c} returns \kbd{x / c}, assuming $c$ 12227is a rational number (\typ{INT} or \typ{FRAC}) and the result is integral. 12228 12229\fun{GEN}{Q_mul_to_int}{GEN x, GEN c} returns \kbd{x * c}, assuming $c$ 12230is a rational number (\typ{INT} or \typ{FRAC}) and the result is integral. 12231 12232\fun{GEN}{Q_muli_to_int}{GEN x, GEN d} returns \kbd{x * c}, assuming $c$ 12233is a \typ{INT} and the result is integral. 12234 12235\fun{GEN}{mul_content}{GEN cx, GEN cy} \kbd{cx} and \kbd{cy} are 12236as set by \kbd{primitive\_part}: either a \kbd{GEN} or \kbd{NULL} 12237representing the trivial content $1$. Returns their product (either a 12238\kbd{GEN} or \kbd{NULL}). 12239 12240\fun{GEN}{div_content}{GEN cx, GEN cy} \kbd{cx} and \kbd{cy} are 12241as set by \kbd{primitive\_part}: either a \kbd{GEN} or \kbd{NULL} 12242representing the trivial content $1$. Returns their quotient (either a 12243\kbd{GEN} or \kbd{NULL}). 12244 12245\fun{GEN}{inv_content}{GEN c} $c$ is as set by \kbd{primitive\_part}: either 12246a \kbd{GEN} or \kbd{NULL} representing the trivial content $1$. Returns its 12247inverse (either a \kbd{GEN} or \kbd{NULL}). 12248 12249\fun{GEN}{mul_denom}{GEN dx, GEN dy} \kbd{dx} and \kbd{dy} are 12250as set by \kbd{Q\_remove\_denom}: either a \typ{INT} or \kbd{NULL} representing 12251the trivial denominator $1$. Returns their product (either a \typ{INT} or 12252\kbd{NULL}). 12253 12254\section{Generic arithmetic operators} 12255 12256\subsec{Unary operators} 12257 12258\fun{GEN}{gneg[z]}{GEN x[, GEN z]} yields $-\kbd{x}$. 12259 12260\fun{GEN}{gneg_i}{GEN x} shallow function yielding $-\kbd{x}$. 12261 12262\fun{GEN}{gabs[z]}{GEN x[, GEN z]} yields $|\kbd{x}|$. 12263 12264\fun{GEN}{gsqr}{GEN x} creates the square of~\kbd{x}. 12265 12266\fun{GEN}{ginv}{GEN x} creates the inverse of~\kbd{x}. 12267 12268\subsec{Binary operators} 12269 12270Let ``\op'' be a binary operation among 12271 12272\op=\key{add}: addition (\kbd{x + y}). 12273 12274\op=\key{sub}: subtraction (\kbd{x - y}). 12275 12276\op=\key{mul}: multiplication (\kbd{x * y}). 12277 12278\op=\key{div}: division (\kbd{x / y}). 12279 12280\noindent The names and prototypes of the functions corresponding 12281to \op\ are as follows: 12282 12283\funno{GEN}{g\op}{GEN x, GEN y} 12284 12285\funno{GEN}{g\op gs}{GEN x, long s} 12286 12287\funno{GEN}{g\op sg}{long s, GEN y} 12288 12289\noindent Explicitly 12290 12291\fun{GEN}{gadd}{GEN x, GEN y}, \fun{GEN}{gaddgs}{GEN x, long s}, 12292\fun{GEN}{gaddsg}{long s, GEN x} 12293 12294\fun{GEN}{gmul}{GEN x, GEN y}, \fun{GEN}{gmulgs}{GEN x, long s}, 12295\fun{GEN}{gmulsg}{long s, GEN x} 12296 12297\fun{GEN}{gsub}{GEN x, GEN y}, \fun{GEN}{gsubgs}{GEN x, long s}, 12298\fun{GEN}{gsubsg}{long s, GEN x} 12299 12300\fun{GEN}{gdiv}{GEN x, GEN y}, \fun{GEN}{gdivgs}{GEN x, long s}, 12301\fun{GEN}{gdivsg}{long s, GEN x} 12302 12303 12304\fun{GEN}{gpow}{GEN x, GEN y, long l} creates $\kbd{x}^{\kbd{y}}$. If 12305\kbd{y} is a \typ{INT}, return \kbd{powgi(x,y)} (the precision \kbd{l} is not 12306taken into account). Otherwise, the result is $\exp(\kbd{y}*\log(\kbd{x}))$ 12307where exact arguments are converted to floats of precision~\kbd{l} in case of 12308need; if there is no need, for instance if $x$ is a \typ{REAL}, $l$ is 12309ignored. Indeed, if $x$ is a \typ{REAL}, the accuracy of $\log x$ is 12310determined from the accuracy of $x$, it is no problem to multiply by $y$, 12311even if it is an exact type, and the accuracy of the exponential is 12312determined, exactly as in the case of the initial $\log x$. 12313 12314\fun{GEN}{gpowgs}{GEN x, long n} creates $\kbd{x}^{\kbd{n}}$ using 12315binary powering. To treat the special case $n = 0$, we consider 12316\kbd{gpowgs} as a series of \kbd{gmul}, so we follow the rule of returning 12317result which is as exact as possible given the input. More precisely, 12318we return 12319 12320\item \kbd{gen\_1} if $x$ has type \typ{INT}, \typ{REAL}, \typ{FRAC}, or 12321\typ{PADIC} 12322 12323\item \kbd{Mod(1,N)} if $x$ is a \typ{INTMOD} modulo $N$. 12324 12325\item \kbd{gen\_1} for \typ{COMPLEX}, \typ{QUAD} unless one component 12326is a \typ{INTMOD}, in which case we return \kbd{Mod(1, N)} for a suitable 12327$N$ (the gcd of the moduli that appear). 12328 12329\item \kbd{FF\_1}$(x)$ for a \typ{FFELT}. 12330 12331\item \kbd{qfi\_1}$(x)$ and \kbd{qfr\_1}$(x)$ for \typ{QFI} and \typ{QFR}. 12332 12333\item the identity permutation for \typ{VECSMALL}. 12334 12335\item \kbd{Rg\_get\_1}$(x)$ otherwise 12336 12337Of course, the only practical use of this routine for $n = 0$ is 12338to obtain the multiplicative neutral element in the base ring (or to treat 12339marginal cases that should be special cased anyway if there is the slightest 12340doubt about what the result should be). 12341 12342\fun{GEN}{powgi}{GEN x, GEN y} creates $\kbd{x}^{\kbd{y}}$, where \kbd{y} is a 12343\typ{INT}, using left-shift binary powering. The case where $y = 0$ 12344(as all cases where $y$ is small) is handled by \kbd{gpowgs(x, 0)}. 12345 12346\fun{GEN}{gpowers}{GEN x, long n} returns the vector $[1,x,\dots,x^n]$. 12347 12348\fun{GEN}{grootsof1}{long n, long prec} returns the vector 12349$[1,x,\dots,x^{n-1}]$, where $x$ is the $n$-th root of unity $\exp(2i\pi/n)$. 12350 12351\fun{GEN}{gsqrpowers}{GEN x, long n} returns the vector $[x,x^4,\dots,x^{n^2}]$. 12352 12353In addition we also have the obsolete forms: 12354 12355\fun{void}{gaddz}{GEN x, GEN y, GEN z} 12356 12357\fun{void}{gsubz}{GEN x, GEN y, GEN z} 12358 12359\fun{void}{gmulz}{GEN x, GEN y, GEN z} 12360 12361\fun{void}{gdivz}{GEN x, GEN y, GEN z} 12362 12363\section{Generic operators: product, powering, factorback} 12364 12365To describe the following functions, we use the following private typedefs 12366to simplify the description: 12367\bprog 12368 typedef (*F0)(void *); 12369 typedef (*F1)(void *, GEN); 12370 typedef (*F2)(void *, GEN, GEN); 12371@eprog 12372\noindent They correspond to generic functions with one and two arguments 12373respectively (the \kbd{void*} argument provides some arbitrary evaluation 12374context). 12375 12376\fun{GEN}{gen_product}{GEN v, void *D, F2 op} 12377Given two objects $x,y$, assume that \kbd{op(D, $x$, $y$)} implements an 12378associative binary operator. If $v$ has $k$ entries, return 12379$$v[1]~\var{op}~v[2]~\var{op}~\ldots ~\var{op}~v[k];$$ 12380returns \kbd{gen\_1} if $k = 0$ and a copy of $v[1]$ if $k = 1$. 12381Use divide and conquer strategy. Leave some garbage on stack, but suitable for 12382\kbd{gerepileupto} if \kbd{mul} is. 12383 12384\fun{GEN}{gen_pow}{GEN x, GEN n, void *D, F1 sqr, F2 mul} $n > 0$ a 12385\typ{INT}, returns $x^n$; \kbd{mul(D, $x$, $y$)} implements the multiplication 12386in the underlying monoid; \kbd{sqr} is a (presumably optimized) shortcut for 12387\kbd{mul(D, $x$, $x$)}. 12388 12389\fun{GEN}{gen_powu}{GEN x, ulong n, void *D, F1 sqr, F2 mul} $n > 0$, 12390returns $x^n$. See \tet{gen_pow}. 12391 12392\fun{GEN}{gen_pow_i}{GEN x, GEN n, void *E, F1 sqr, F2 mul} 12393internal variant of \tet{gen_pow}, not memory-clean. 12394 12395\fun{GEN}{gen_powu_i}{GEN x, ulong n, void *E, F1 sqr, F2 mul} 12396internal variant of \tet{gen_powu}, not memory-clean. 12397 12398\fun{GEN}{gen_pow_fold}{GEN x, GEN n, void *D, F1 sqr, F1 msqr} variant 12399of \tet{gen_pow}, where \kbd{mul} is replaced by \kbd{msqr}, with 12400\kbd{msqr(D, $y$)} returning $xy^2$. In particular \kbd{D} must implicitly 12401contain $x$. 12402 12403\fun{GEN}{gen_pow_fold_i}{GEN x, GEN n, void *E, F1 sqr, F1 msqr} 12404internal variant of the function \tet{gen_pow_fold}, not memory-clean. 12405 12406\fun{GEN}{gen_powu_fold}{GEN x, ulong n, void *D, F1 sqr, F1 msqr}, see 12407\tet{gen_pow_fold}. 12408 12409\fun{GEN}{gen_powu_fold_i}{GEN x, ulong n, void *E, F1 sqr, F1 msqr} 12410see \tet{gen_pow_fold_i}. 12411 12412\fun{GEN}{gen_pow_init}{GEN x, GEN n, long k, void *E, GEN (*sqr)(void*,GEN), 12413 GEN (*mul)(void*,GEN,GEN)} 12414Return a table \kbd{R} that can be used with 12415\kbd{gen\_pow\_table} to compute the powers of $x$ up to $n$. 12416The table is of size $2^k\*\log_2(n)$. 12417 12418\fun{GEN}{gen_pow_table}{GEN R, GEN n, void *E, GEN (*one)(void*), 12419 GEN (*mul)(void*,GEN,GEN)} 12420 12421Return $x^n$, where $R$ is as given by \kbd{gen\_pow\_init(x,m,k,E,sqr,mul)} 12422for some integer $m\geq n$. 12423 12424\fun{GEN}{gen_powers}{GEN x, long n, long usesqr, void *D, F1 sqr, F2 mul, F0 one} 12425returns $[\kbd{x}^0, \dots, \kbd{x}^\kbd{n}]$ as a \typ{VEC}; \kbd{mul(D, 12426$x$, $y$)} implements the multiplication in the underlying monoid; \kbd{sqr} 12427is a (presumably optimized) shortcut for \kbd{mul(D, $x$, $x$)}; \kbd{one} 12428returns the monoid unit. The flag \kbd{usesqr} should be set to $1$ if 12429squaring are faster than multiplication by $x$. 12430 12431\fun{GEN}{gen_factorback}{GEN L, GEN e, void *D, F2 mul, F2 pow} generic form 12432of \tet{factorback}. The pair $[L,e]$ is of the form 12433 12434\item \kbd{[fa, NULL]}, \kbd{fa} a two-column factorization matrix: expand it. 12435 12436\item \kbd{[v, NULL]}, $v$ a vector of objects: return their product. 12437 12438\item or \kbd{[v, e]}, $v$ a vector of objects, $e$ a vector of integral 12439exponents (a \kbd{ZV} or \kbd{zv}): return the product of the $v[i]^{e[i]}$. 12440 12441\noindent \kbd{mul(D, $x$, $y$)} and \kbd{pow(D, $x$, $n$)} 12442return $xy$ and $x^n$ respectively. 12443 12444\section{Matrix and polynomial norms} This section concerns only standard norms 12445of $\R$ and $\C$ vector spaces, not algebraic norms given by the determinant of 12446some multiplication operator. We have already seen type-specific functions like 12447\tet{ZM_supnorm} or \tet{RgM_fpnorml2} and limit ourselves to generic functions 12448assuming nothing about their \kbd{GEN} argument; these functions allow 12449the following scalar types: \typ{INT}, \typ{FRAC}, \typ{REAL}, \typ{COMPLEX}, 12450\typ{QUAD} and are defined recursively (in terms of norms of their components) 12451for the following ``container'' types: \typ{POL}, \typ{VEC}, \typ{COL} and 12452\typ{MAT}. They raise an error if some other type appears in the argument. 12453 12454\fun{GEN}{gnorml2}{GEN x} The norm of a scalar is the square of its complex 12455modulus, the norm of a recursive type is the sum of the norms of its components. 12456For polynomials, vectors or matrices of complex numbers one recovers the 12457\emph{square} of the usual $L^2$ norm. In most applications, the missing square 12458root computation can be skipped. 12459 12460\fun{GEN}{gnorml1}{GEN x, long prec} The norm of a scalar is its complex 12461modulus, the norm of a recursive type is the sum of the norms of its components. 12462For polynomials, vectors or matrices of complex numbers one recovers 12463the usual $L^1$ norm. One must include a real precision \kbd{prec} in case 12464the inputs include \typ{COMPLEX} or \typ{QUAD} with exact rational components: 12465a square root must be computed and we must choose an accuracy. 12466 12467\fun{GEN}{gnorml1_fake}{GEN x} as \tet{gnorml1}, except that the norm 12468of a \typ{QUAD} $x + wy$ or \typ{COMPLEX} $x + Iy$ is defined as 12469$|x| + |y|$, where we use the ordinary real absolute value. This is still a norm 12470of $\R$ vector spaces, which is easier to compute than 12471\kbd{gnorml1} and can often be used in its place. 12472 12473\fun{GEN}{gsupnorm}{GEN x, long prec} The norm of a scalar is its complex 12474modulus, the norm of a recursive type is the max of the norms of its 12475components. A precision \kbd{prec} must be included for the same reason as in 12476\kbd{gnorml1}. 12477 12478\fun{void}{gsupnorm_aux}{GEN x, GEN *m, GEN *m2, long prec} 12479is the low-level function underlying 12480\kbd{gsupnorm}, used as follows: 12481\bprog 12482 GEN m = NULL, m2 = NULL; 12483 gsupnorm_aux(x, &m, &m2); 12484@eprog 12485After the call, the sup norm of $x$ is the min of \kbd{m} and the square root 12486of \kbd{m2}; one or both of \kbd{m}, \kbd{m2} may be \kbd{NULL}, in 12487which case it must be omitted. You may initially set \kbd{m} and \kbd{m2} to 12488non-\kbd{NULL} values, in which case, the above procedure yields the max of 12489(the initial) \kbd{m}, the square root of (the initial) \kbd{m2}, and the sup 12490norm of $x$. 12491 12492The strange interface is due to the fact that $|z|^2$ is easier to compute 12493than $|z|$ for a \typ{QUAD} or \typ{COMPLEX} $z$: \kbd{m2} is the max of 12494those $|z|^2$, and \kbd{m} is the max of the other $|z|$. 12495 12496\section{Substitution and evaluation} 12497 12498\fun{GEN}{gsubst}{GEN x, long v, GEN y} substitutes the object \kbd{y} 12499into~\kbd{x} for the variable number~\kbd{v}. 12500 12501\fun{GEN}{poleval}{GEN q, GEN x} evaluates the \typ{POL} or \typ{RFRAC} 12502$q$ at $x$. For convenience, a \typ{VEC} or \typ{COL} is also recognized as 12503the \typ{POL} \kbd{gtovecrev(q)}. 12504 12505\fun{GEN}{RgX_cxeval}{GEN T, GEN x, GEN xi} evaluate the \typ{POL} $T$ 12506at $x$ via Horner's scheme. If \var{xi} is not \kbd{NULL} it must be equal to 12507$1/x$ and we evaluate $x^{\deg T}T(1/x)$ instead. This is useful when 12508$|x| > 1$ is a \typ{REAL} or an inexact \typ{COMPLEX} and $T$ has 12509``balanced'' coefficients, since the evaluation becomes numerically stable. 12510 12511\fun{GEN}{RgX_RgM_eval}{GEN q, GEN x} evaluates the \typ{POL} $q$ at the 12512square matrix $x$. 12513 12514\fun{GEN}{RgX_RgMV_eval}{GEN f, GEN V} returns 12515the evaluation $\kbd{f}(\kbd{x})$, assuming that \kbd{V} was computed by 12516$\kbd{FpXQ\_powers}(\kbd{x}, n)$ for some $n>1$. 12517 12518\fun{GEN}{qfeval}{GEN q, GEN x} evaluates the quadratic form 12519$q$ (symmetric matrix) at $x$ (column vector of compatible dimensions). 12520 12521\fun{GEN}{qfevalb}{GEN q, GEN x, GEN y} evaluates the polar bilinear form 12522attached to the quadratic form $q$ (symmetric matrix) at $x$, $y$ (column 12523vectors of compatible dimensions). 12524 12525\fun{GEN}{hqfeval}{GEN q, GEN x} evaluates the Hermitian form $q$ 12526(a Hermitian complex matrix) at $x$. 12527 12528\fun{GEN}{qf_apply_RgM}{GEN q, GEN M} $q$ is a symmetric $n\times n$ matrix, 12529$M$ an $n\times k$ matrix, return $M' q M$. 12530 12531\fun{GEN}{qf_apply_ZM}{GEN q, GEN M} as above assuming that both 12532$q$ and $M$ have integer entries. 12533 12534\newpage 12535\chapter{Miscellaneous mathematical functions} 12536 12537\section{Fractions} 12538 12539\fun{GEN}{absfrac}{GEN x} returns the absolute value of the \typ{FRAC} $x$. 12540 12541\fun{GEN}{absfrac_shallow}{GEN x} $x$ being a \typ{FRAC}, returns a shallow 12542copy of $|x|$, in particular returns $x$ itself when $x \geq 0$, and 12543\kbd{gneg($x$)} otherwise. 12544 12545\fun{GEN}{sqrfrac}{GEN x} returns the square of the \typ{FRAC} $x$. 12546 12547\section{Binomials} 12548 12549\fun{GEN}{binomial}{GEN x, long k} 12550 12551\fun{GEN}{binomialuu}{ulong n, ulong k} 12552 12553\fun{GEN}{vecbinomial}{long n}, which returns a vector $v$ with $n+1$ 12554\typ{INT} components such that $v[k+1] = \kbd{binomial}(n,k)$ for $k$ from 12555$0$ up to $n$. 12556 12557\section{Real numbers} 12558 12559\fun{GEN}{R_abs}{GEN x} $x$ being a \typ{INT}, a \typ{REAL} or a 12560\typ{FRAC}, returns $|x|$. 12561 12562\fun{GEN}{R_abs_shallow}{GEN x} $x$ being a \typ{INT}, a \typ{REAL} or a 12563\typ{FRAC}, returns a shallow copy of $|x|$, in particular returns $x$ itself 12564when $x \geq 0$, and \kbd{gneg($x$)} otherwise. 12565 12566\fun{GEN}{modRr_safe}{GEN x, GEN y} let $x$ be a \typ{INT}, a \typ{REAL} or 12567\typ{FRAC} and let $y$ be a \typ{REAL}. Return $x\% y$ unless the input 12568accuracy is unsufficient to compute the floor or $x/y$ in which case we 12569return \kbd{NULL}. 12570 12571\section{Complex numbers} 12572 12573\fun{GEN}{gimag}{GEN x} returns a copy of the imaginary part of \kbd{x}. 12574 12575\fun{GEN}{greal}{GEN x} returns a copy of the real part of \kbd{x}. If \kbd{x} 12576is a \typ{QUAD}, returns the coefficient of $1$ in the ``canonical'' integral 12577basis $(1,\omega)$. 12578 12579\fun{GEN}{gconj}{GEN x} returns $\kbd{greal}(x) - 2\kbd{gimag}(x)$, which is 12580the ordinary complex conjugate except for a real \typ{QUAD}. 12581 12582\fun{GEN}{imag_i}{GEN x}, shallow variant of \kbd{gimag}. 12583 12584\fun{GEN}{real_i}{GEN x}, shallow variant of \kbd{greal}. 12585 12586\fun{GEN}{conj_i}{GEN x}, shallow variant of \kbd{gconj}. 12587 12588\fun{GEN}{mulreal}{GEN x, GEN y} returns the real part of $x\*y$; 12589$x$, $y$ have type \typ{INT}, \typ{FRAC}, \typ{REAL} or \typ{COMPLEX}. See also 12590\kbd{RgM\_mulreal}. 12591 12592\fun{GEN}{cxnorm}{GEN x} norm of the \typ{COMPLEX} $x$ (modulus squared). 12593 12594\fun{GEN}{cxexpm1}{GEN x} returns $\exp(x)-1$, for a \typ{COMPLEX} $x$. 12595 12596\fun{int}{cx_approx_equal}{GEN a, GEN b} test whether (\typ{INT}, \typ{FRAC}, 12597\typ{REAL}, or \typ{COMPLEX} of those) $a$ and $b$ are approximately equal. 12598This returns $1$ if and only if the division by $a-b$ would produce a 12599division by $0$ (which is a less stringent test than testing whether $a-b$ 12600evaluates to $0$). 12601 12602\section{Quadratic numbers and binary quadratic forms} 12603 12604\fun{GEN}{quad_disc}{GEN x} returns the discriminant of the \typ{QUAD} $x$. 12605Not stack-clean but suitable for \kbd{gerepileupto}. 12606 12607\fun{GEN}{quadnorm}{GEN x} norm of the \typ{QUAD} $x$. 12608 12609\fun{GEN}{qfb_disc}{GEN x} returns the discriminant of the \typ{QFI} 12610or \typ{QFR} \kbd{x}. 12611 12612\fun{GEN}{qfb_disc3}{GEN x, GEN y, GEN z} returns $y^2 - 4xz$ assuming all 12613inputs are \typ{INT}s. Not stack-clean. 12614 12615\fun{GEN}{qfb_apply_ZM}{GEN q, GEN g} returns $q \circ g$. 12616 12617\fun{GEN}{qfbforms}{GEN D} given a discriminant $D < 0$, return the list 12618of reduced forms of discriminant $D$ as \typ{VECSMALL} with 3 components. 12619The primitive forms in the list enumerate the class group of the quadratic 12620order of discriminant $D$; if $D$ is fundamental, all returned forms 12621are automatically primitive. 12622 12623\section{Polynomials}\label{se:polynomials} 12624 12625\fun{GEN}{truecoef}{GEN x, long n} returns \kbd{polcoef(x,n, -1)}, i.e. 12626the coefficient of the term of degree \kbd{n} in the main variable. This is 12627a safe but expensive function that must \emph{copy} its return value so that 12628it be \kbd{gerepile}-safe. Use \kbd{polcoef\_i} for a fast internal variant. 12629 12630\fun{GEN}{polcoef_i}{GEN x, long n, long v} internal shallow function. Rewrite 12631$x$ as a Laurent polynomial in the variable $v$ and returns its coefficient 12632of degree $n$ (\kbd{gen\_0} if this falls outside the coefficient array). 12633Allow \typ{POL}, \typ{SER}, \typ{RFRAC} and scalars. 12634 12635\fun{long}{degree}{GEN x} returns \kbd{poldegree(x, -1)}, the degree of 12636\kbd{x} with respect to its main variable, with the usual meaning if the 12637leading coefficient of $x$ is nonzero. If the sign of $x$ is $0$, this 12638function always returns $-1$. Otherwise, we return the index of the leading 12639coefficient of $x$, i.e. the coefficient of largest index stored in $x$. 12640For instance the ``degrees'' of 12641\bprog 12642 0. E-38 * x^4 + 0.E-19 * x + 1 12643 Mod(0,2) * x^0 \\ sign is 0 ! 12644@eprog\noindent are $4$ and $-1$ respectively. 12645 12646\fun{long}{degpol}{GEN x} is a simple macro returning \kbd{lg(x) - 3}. 12647This is the degree of the \typ{POL}~\kbd{x} with respect to its main 12648variable, \emph{if} its leading coefficient is nonzero (a rational $0$ is 12649impossible, but an inexact $0$ is allowed, as well as an exact modular $0$, 12650e.g. \kbd{Mod(0,2)}). If $x$ has no coefficients (rational $0$ polynomial), 12651its length is $2$ and we return the expected $-1$. 12652 12653\fun{GEN}{characteristic}{GEN x} returns the characteristic of the 12654base ring over which the polynomial is defined (as defined by \typ{INTMOD} 12655and \typ{FFELT} components). The function raises an exception if incompatible 12656primes arise from \typ{FFELT} and \typ{PADIC} components. Shallow function. 12657 12658\fun{GEN}{residual_characteristic}{GEN x} returns a kind of ``residual 12659characteristic'' of the base ring over which the polynomial is defined. This 12660is defined as the gcd of all moduli \typ{INTMOD}s occurring in the structure, 12661as well as primes $p$ arising from \typ{PADIC}s or \typ{FFELT}s. The function 12662raises an exception if incompatible primes arise from \typ{FFELT} and 12663\typ{PADIC} components. Shallow function. 12664 12665\fun{GEN}{resultant}{GEN x,GEN y} resultant of \kbd{x} and \kbd{y}, with 12666respect to the main variable of highest priority. Uses either the 12667subresultant algorithm (generic case), a modular algorithm (inputs in 12668$\Q[X]$) or Sylvester's matrix (inexact inputs). 12669 12670\fun{GEN}{resultant2}{GEN x, GEN y} resultant of \kbd{x} and \kbd{y}, with 12671respect to the main variable of highest priority. Computes the determinant 12672of Sylvester's matrix. 12673 12674\fun{GEN}{cleanroots}{GEN x, long prec} returns the complex roots of 12675the complex polynomial $x$ (with coefficients \typ{INT}, \typ{FRAC}, 12676\typ{REAL} or \typ{COMPLEX} of the above). The roots are returned 12677as \typ{REAL} or \typ{COMPLEX} of \typ{REAL}s of precision \kbd{prec} 12678(guaranteeing a nonzero imaginary part). See \tet{QX_complex_roots}. 12679 12680\fun{double}{fujiwara_bound}{GEN x} return a quick upper bound for the 12681logarithm in base $2$ of the modulus of the largest complex roots of 12682the polynomial $x$ (complex coefficients). 12683 12684\fun{double}{fujiwara_bound_real}{GEN x, long sign} return a quick upper 12685bound for the logarithm in base $2$ of the absolute value of the largest 12686real root of sign \var{sign} ($1$ or $-1$), for the polynomial $x$ (real 12687coefficients). 12688 12689\fun{GEN}{polmod_to_embed}{GEN x, long prec} return the vector of complex 12690embeddings of the \typ{POLMOD} $x$ (with complex coefficients). Shallow 12691function, simple complex variant of \tet{conjvec}. 12692 12693\fun{GEN}{pollegendre_reduced}{long n, long v} let $P_n(t)\in \Q[t]$ 12694be the $n$-th Legendre polynomial in variable $v$. Return $p\in \Z[t]$ 12695such that $2^n P_n(t) = p(t^2)$ ($n$ even) or $t p(t^2)$ ($n$ odd). 12696 12697\section{Power series} 12698 12699\fun{GEN}{sertoser}{GEN x, long prec} return the \typ{SER} $x$ truncated 12700or extended (with zeros) to \kbd{prec} terms. Shallow function, assume 12701that $\kbd{prec} \geq 0$. 12702 12703\fun{GEN}{derivser}{GEN x} returns the derivative of the \typ{SER} \kbd{x} 12704with respect to its main variable. 12705 12706\fun{GEN}{integser}{GEN x} returns the primitive of the \typ{SER} \kbd{x} 12707with respect to its main variable. 12708 12709\fun{GEN}{truecoef}{GEN x, long n} returns \kbd{polcoef(x,n, -1)}, i.e. 12710the coefficient of the term of degree \kbd{n} in the main variable. This is a 12711safe but expensive function that must \emph{copy} its return value so that it 12712be \kbd{gerepile}-safe. Use \kbd{polcoef\_i} for a fast internal variant. 12713 12714\fun{GEN}{ser_unscale}{GEN P, GEN h} return $P(h x)$, not memory clean. 12715 12716\fun{GEN}{ser_normalize}{GEN x} divide $x$ by its ``leading term'' so that 12717the series is either $0$ or equal to $t^v(1+O(t))$. Shallow function if the 12718``leading term'' is $1$. 12719 12720\fun{int}{ser_isexactzero}{GEN x} return $1$ if $x$ is a zero series, all 12721of whose known coefficients are exact zeroes; this implies that 12722$\kbd{sign}(x) = 0$ and $\kbd{lg}(x) \leq 3$. 12723 12724\fun{GEN}{ser_inv}{GEN x} return the inverse of the \typ{SER} $x$ using 12725Newton iteration. This is in general slower than \kbd{ginv} unless the 12726precision is huge (hundreds of terms, where the threshold depends strongly 12727on the base field). 12728 12729\fun{GEN}{psi1series}{long n, long v, long prec} creates the \typ{SER} 12730$\psi(1 + x + O(x^n))$ in variable $v$. 12731 12732\section{Functions to handle \typ{FFELT}} 12733These functions define the public interface of the \typ{FFELT} type to use in 12734generic functions. However, in specific functions, it is better to use the 12735functions class \kbd{FpXQ} and/or \kbd{Flxq} as appropriate. 12736 12737\fun{GEN}{FF_p}{GEN a} returns the characteristic of the definition field of the 12738\typ{FFELT} element \kbd{a}. 12739 12740\fun{long}{FF_f}{GEN a} returns the dimension of the definition field over 12741its prime field; the cardinality of the dimension field is thus $p^f$. 12742 12743\fun{GEN}{FF_p_i}{GEN a} shallow version of \kbd{FF\_p}. 12744 12745\fun{GEN}{FF_q}{GEN a} returns the cardinality of the definition field of the 12746\typ{FFELT} element \kbd{a}. 12747 12748\fun{GEN}{FF_mod}{GEN a} returns the polynomial (with reduced \typ{INT} 12749coefficients) defining the finite field, in the variable used to display $a$. 12750 12751\fun{long}{FF_var}{GEN a} returns the variable used to display $a$. 12752 12753\fun{GEN}{FF_gen}{GEN a} returns the standard generator of the definition field 12754of the \typ{FFELT} element \kbd{a}, see \kbd{ffgen}, that is $x\pmod{T}$ where 12755$T$ is the polynomial over the prime field that define the finite field. 12756 12757\fun{GEN}{FF_to_FpXQ}{GEN a} converts the \typ{FFELT} \kbd{a} to a polynomial 12758$P$ with reduced \typ{INT} coefficients such that $a=P(g)$ where $g$ is the 12759generator of the finite field returned by \kbd{ffgen}, in the variable used to 12760display $g$. 12761 12762\fun{GEN}{FF_to_FpXQ_i}{GEN a} shallow version of \kbd{FF\_to\_FpXQ}. 12763 12764\fun{GEN}{FF_to_F2xq}{GEN a} converts the \typ{FFELT} \kbd{a} to a \kbd{F2x} 12765$P$ such that $a=P(g)$ where $g$ is the generator of the finite field returned 12766by \kbd{ffgen}, in the variable used to display $g$. This only work if the 12767characteristic is $2$. 12768 12769\fun{GEN}{FF_to_F2xq_i}{GEN a} shallow version of \kbd{FF\_to\_F2xq}. 12770 12771\fun{GEN}{FF_to_Flxq}{GEN a} converts the \typ{FFELT} \kbd{a} to a \kbd{Flx} 12772$P$ such that $a=P(g)$ where $g$ is the generator of the finite field returned 12773by \kbd{ffgen}, in the variable used to display $g$. This only work if the 12774characteristic is small enough. 12775 12776\fun{GEN}{FF_to_Flxq_i}{GEN a} shallow version of \kbd{FF\_to\_Flxq}. 12777 12778\fun{GEN}{p_to_FF}{GEN p, long v} returns a \typ{FFELT} equal to $1$ in the 12779finite field $\Z/p\Z$. Useful for generic code that wants to handle 12780(inefficiently) $\Z/p\Z$ as if it were not a prime field. 12781 12782\fun{GEN}{Tp_to_FF}{GEN T, GEN p} returns a \typ{FFELT} equal to $1$ in the 12783finite field $\F_p/(T)$, where $T$ is a \kbd{ZX}, assumed to be irreducible 12784modulo $p$, or \kbd{NULL} in which case the routine acts as \tet{p_to_FF(p,0)}. 12785No checks. 12786 12787\fun{GEN}{Fq_to_FF}{GEN x, GEN ff} returns a \typ{FFELT} equal to $x$ 12788in the finite field defined by the \typ{FFELT} \kbd{ff}, where 12789$x$ is an \kbd{Fq} (either a \typ{INT} or a \kbd{ZX}: a \typ{POL} with 12790\typ{INT} coefficients). No checks. 12791 12792\fun{GEN}{FqX_to_FFX}{GEN x, GEN ff} given an \kbd{FqX} $x$, 12793return the polynomial with \typ{FFELT} coefficients obtained by 12794applying \tet{Fq_to_FF} coefficientwise. No checks, and no normalization 12795if the leading coefficient maps to $0$. 12796 12797\fun{GEN}{FF_1}{GEN a} returns the unity in the definition field of the 12798\typ{FFELT} element \kbd{a}. 12799 12800\fun{GEN}{FF_zero}{GEN a} returns the zero element of the definition field of 12801the \typ{FFELT} element \kbd{a}. 12802 12803\fun{int}{FF_equal0}{GEN a} returns $1$ if the \typ{FFELT} \kbd{a} is equal 12804to $0$ else returns $0$. 12805 12806\fun{int}{FF_equal1}{GEN a} returns $1$ if the \typ{FFELT} \kbd{a} is equal 12807to $1$ else returns $0$. 12808 12809\fun{int}{FF_equalm1}{GEN a} returns $-1$ if the \typ{FFELT} \kbd{a} is equal 12810to $1$ else returns $0$. 12811 12812\fun{int}{FF_equal}{GEN a, GEN b} return $1$ if the \typ{FFELT} \kbd{a} and 12813\kbd{b} have the same definition field and are equal, else $0$. 12814 12815\fun{int}{FF_samefield}{GEN a, GEN b} return $1$ if the \typ{FFELT} \kbd{a} and 12816\kbd{b} have the same definition field, else $0$. 12817 12818\fun{int}{Rg_is_FF}{GEN c, GEN *ff} to be called successively on many objects, 12819setting \kbd{*ff = NULL} (unset) initially. Returns $1$ as long as $c$ is a 12820\typ{FFELT} defined over the same field as \kbd{*ff} (setting \kbd{*ff = c} 12821if unset), and $0$ otherwise. 12822 12823\fun{int}{RgC_is_FFC}{GEN x, GEN *ff} apply \tet{Rg_is_FF} successively to all 12824components of the \typ{VEC} or \typ{COL} $x$. Return $0$ if one call fails, 12825and $1$ otherwise. 12826 12827\fun{int}{RgM_is_FFM}{GEN x, GEN *ff} apply \tet{Rg_is_FF} to all components 12828of the \typ{MAT}. Return $0$ if one call fails, and $1$ otherwise. 12829 12830\fun{GEN}{FF_add}{GEN a, GEN b} returns $a+b$ where \kbd{a} and \kbd{b} are 12831\typ{FFELT} having the same definition field. 12832 12833\fun{GEN}{FF_Z_add}{GEN a, GEN x} returns $a+x$, where \kbd{a} is a 12834\typ{FFELT}, and \kbd{x} is a \typ{INT}, the computation being 12835performed in the definition field of \kbd{a}. 12836 12837\fun{GEN}{FF_Q_add}{GEN a, GEN x} returns $a+x$, where \kbd{a} is a 12838\typ{FFELT}, and \kbd{x} is a \typ{RFRAC}, the computation being 12839performed in the definition field of \kbd{a}. 12840 12841\fun{GEN}{FF_sub}{GEN a, GEN b} returns $a-b$ where \kbd{a} and \kbd{b} are 12842\typ{FFELT} having the same definition field. 12843 12844\fun{GEN}{FF_mul}{GEN a, GEN b} returns $a\*b$ where \kbd{a} and \kbd{b} are 12845\typ{FFELT} having the same definition field. 12846 12847\fun{GEN}{FF_Z_mul}{GEN a, GEN b} returns $a\*b$, where \kbd{a} is a 12848\typ{FFELT}, and \kbd{b} is a \typ{INT}, the computation being 12849performed in the definition field of \kbd{a}. 12850 12851\fun{GEN}{FF_div}{GEN a, GEN b} returns $a/b$ where \kbd{a} and \kbd{b} are 12852\typ{FFELT} having the same definition field. 12853 12854\fun{GEN}{FF_neg}{GEN a} returns $-a$ where \kbd{a} is a \typ{FFELT}. 12855 12856\fun{GEN}{FF_neg_i}{GEN a} shallow function returning $-a$ where \kbd{a} is a 12857\typ{FFELT}. 12858 12859\fun{GEN}{FF_inv}{GEN a} returns $a^{-1}$ where \kbd{a} is a \typ{FFELT}. 12860 12861\fun{GEN}{FF_sqr}{GEN a} returns $a^2$ where \kbd{a} is a \typ{FFELT}. 12862 12863\fun{GEN}{FF_mul2n}{GEN a, long n} returns $a\*2^n$ where \kbd{a} is a 12864\typ{FFELT}. 12865 12866\fun{GEN}{FF_pow}{GEN a, GEN n} returns $a^n$ where \kbd{a} is a \typ{FFELT} 12867and \kbd{n} is a \typ{INT}. 12868 12869\fun{GEN}{FF_Frobenius}{GEN a, GEN n} returns $x^{p^n}$ where \kbd{x} is 12870the standard generator of the definition field of the \typ{FFELT} element 12871\kbd{a}, \typ{FFELT}, \kbd{n} is a \typ{INT}, and $p$ is the characteristic 12872of the definition field of $a$. 12873 12874\fun{GEN}{FF_Z_Z_muldiv}{GEN a, GEN x, GEN y} returns $a\*y/z$, where \kbd{a} 12875is a \typ{FFELT}, and \kbd{x} and \kbd{y} are \typ{INT}, the computation being 12876performed in the definition field of \kbd{a}. 12877 12878\fun{GEN}{Z_FF_div}{GEN x, GEN a} return $x/a$ where \kbd{a} is a 12879\typ{FFELT}, and \kbd{x} is a \typ{INT}, the computation being 12880performed in the definition field of \kbd{a}. 12881 12882\fun{GEN}{FF_norm}{GEN a} returns the norm of the \typ{FFELT} \kbd{a} with 12883respect to its definition field. 12884 12885\fun{GEN}{FF_trace}{GEN a} returns the trace of the \typ{FFELT} \kbd{a} with 12886respect to its definition field. 12887 12888\fun{GEN}{FF_conjvec}{GEN a} returns the vector of conjugates 12889$[a,a^p,a^{p^2},\ldots,a^{p^{n-1}}]$ where the \typ{FFELT} \kbd{a} belong to a 12890field with $p^n$ elements. 12891 12892\fun{GEN}{FF_charpoly}{GEN a} returns the characteristic polynomial) of the 12893\typ{FFELT} \kbd{a} with respect to its definition field. 12894 12895\fun{GEN}{FF_minpoly}{GEN a} returns the minimal polynomial of 12896the \typ{FFELT} \kbd{a}. 12897 12898\fun{GEN}{FF_sqrt}{GEN a} returns an \typ{FFELT} $b$ such that $a=b^2$ if 12899it exist, where \kbd{a} is a \typ{FFELT}. 12900 12901\fun{long}{FF_issquareall}{GEN x, GEN *pt} returns $1$ if \kbd{x} is a 12902square, and $0$ otherwise. If \kbd{x} is indeed a square, set \kbd{pt} to its 12903square root. 12904 12905\fun{long}{FF_issquare}{GEN x} returns $1$ if \kbd{x} is a square and $0$ 12906otherwise. 12907 12908\fun{long}{FF_ispower}{GEN x, GEN K, GEN *pt} Given $K$ a positive integer, 12909returns $1$ if \kbd{x} is a $K$-th power, and $0$ otherwise. If \kbd{x} is 12910indeed a $K$-th power, set \kbd{pt} to its $K$-th root. 12911 12912\fun{GEN}{FF_sqrtn}{GEN a, GEN n, GEN *zn} returns an \kbd{n}-th root of 12913$\kbd{a}$ if it exist. If \kbd{zn} is non-\kbd{NULL} set it to a primitive 12914\kbd{n}-th root of the unity. 12915 12916\fun{GEN}{FF_log}{GEN a, GEN g, GEN o} the \typ{FFELT} \kbd{g} being a 12917generator for the definition field of the \typ{FFELT} \kbd{a}, returns a 12918\typ{INT} $e$ such that $a^e=g$. If $e$ does not exists, the result is 12919currently undefined. If \kbd{o} is not \kbd{NULL} it is assumed to be a 12920factorization of the multiplicative order of \kbd{g} (as set by 12921\tet{FF_primroot}) 12922 12923\fun{GEN}{FF_order}{GEN a, GEN o} returns the order of the \typ{FFELT} \kbd{a}. 12924If \kbd{o} is non-\kbd{NULL}, it is assumed that \kbd{o} is a multiple of the 12925order of \kbd{a}. 12926 12927\fun{GEN}{FF_primroot}{GEN a, GEN *o} returns a generator of the 12928multiplicative group of the definition field of the \typ{FFELT} \kbd{a}. 12929If \kbd{o} is not \kbd{NULL}, set it to the factorization of the order 12930of the primitive root (to speed up \tet{FF_log}). 12931 12932\fun{GEN}{FF_map}{GEN m, GEN a} returns $A(m)$ where \kbd{A=a.pol} assuming 12933$a$ and $m$ belongs to fields having the same characteristic. 12934 12935\subsec{FFX} 12936 12937The functions in this sections take polynomial arguments and a \typ{FFELT} 12938$a$. The coefficients of the polynomials must be of type \typ{INT}, 12939\typ{INTMOD} or \typ{FFELT} and compatible with \kbd{a}. 12940 12941\fun{GEN}{FFX_add}{GEN P, GEN Q, GEN a} returns the sum of the polynomials 12942\kbd{P} and \kbd{Q} defined over the definition field of the \typ{FFELT} 12943\kbd{a}. 12944 12945\fun{GEN}{FFX_mul}{GEN P, GEN Q, GEN a} returns the product of the polynomials 12946\kbd{P} and \kbd{Q} defined over the definition field of the \typ{FFELT} 12947\kbd{a}. 12948 12949\fun{GEN}{FFX_sqr}{GEN P, GEN a} returns the square of the polynomial 12950\kbd{P} defined over the definition field of the \typ{FFELT} \kbd{a}. 12951 12952\fun{GEN}{FFX_rem}{GEN P, GEN Q, GEN a} returns the remainder 12953of the polynomial \kbd{P} modulo the polynomial \kbd{Q}, where \kbd{P} and 12954\kbd{Q} are defined over the definition field of the \typ{FFELT} \kbd{a}. 12955 12956\fun{GEN}{FFX_gcd}{GEN P, GEN Q, GEN a} returns the GCD of the polynomials 12957\kbd{P} and \kbd{Q} defined over the definition field of the \typ{FFELT} 12958\kbd{a}. 12959 12960\fun{GEN}{FFX_extgcd}{GEN P, GEN Q, GEN a, GEN *U, GEN *V} 12961returns the GCD of the polynomials \kbd{P} and \kbd{Q} defined over 12962the definition field of the \typ{FFELT} \kbd{a} and sets \kbd{*U}, \kbd{*V} to 12963the Bezout coefficients such that $\kbd{*UP} + \kbd{*VQ} = d$. If \kbd{*U} is 12964set to \kbd{NULL}, it is not computed which is a bit faster. 12965 12966\fun{GEN}{FFX_halfgcd}{GEN x, GEN y, GEN a} returns a two-by-two matrix 12967$M$ with determinant $\pm 1$ such that the image $(a,b)$ of $(x,y)$ by $M$ 12968has the property that $\deg a \geq {\deg x \over 2} > \deg b$. 12969 12970\fun{GEN}{FFX_resultant}{GEN P, GEN Q, GEN a} returns the resultant of the polynomials 12971\kbd{P} and \kbd{Q} where \kbd{P} and \kbd{Q} are defined over the definition 12972field of the \typ{FFELT} \kbd{a}. 12973 12974\fun{GEN}{FFX_disc}{GEN P, GEN a} returns the discriminant of the polynomial 12975\kbd{P} where \kbd{P} is defined over the definition field of the \typ{FFELT} 12976\kbd{a}. 12977 12978\fun{GEN}{FFX_ispower}{GEN P, ulong k, GEN a, GEN *py} 12979return $1$ if the \kbd{FFX} $P$ is a $k$-th power, $0$ otherwise, 12980where \kbd{P} is defined over the definition field of the \typ{FFELT} \kbd{a}. 12981If \kbd{py} is not \kbd{NULL}, set it to $g$ such that $g^k = f$. 12982 12983\fun{GEN}{FFX_factor}{GEN f, GEN a} returns the factorization of the univariate 12984polynomial \kbd{f} over the definition field of the \typ{FFELT} \kbd{a}. The 12985coefficients of \kbd{f} must be of type \typ{INT}, \typ{INTMOD} or \typ{FFELT} 12986and compatible with \kbd{a}. 12987 12988\fun{GEN}{FFX_factor_squarefree}{GEN f, GEN a} returns the squarefree 12989factorization of the univariate polynomial \kbd{f} over the definition field of 12990the \typ{FFELT} \kbd{a}. This is a vector $[u_1,\dots,u_k]$ of pairwise 12991coprime \kbd{FFX} such that $u_k \neq 1$ and $f = \prod u_i^i$. 12992 12993\fun{GEN}{FFX_ddf}{GEN f, GEN a} assuming that $f$ is squarefree, 12994returns the distinct degree factorization of $f$ modulo $p$. 12995The returned value \kbd{v} is a \typ{VEC} with two 12996components: \kbd{F=v[1]} is a vector of (\kbd{FFX}) 12997factors, and \kbd{E=v[2]} is a \typ{VECSMALL}, such that 12998$f$ is equal to the product of the \kbd{F[i]} and each \kbd{F[i]} 12999is a product of irreducible factors of degree \kbd{E[i]}. 13000 13001\fun{GEN}{FFX_degfact}{GEN f, GEN a}, as \kbd{FFX\_factor}, but the 13002degrees of the irreducible factors are returned instead of the factors 13003themselves (as a \typ{VECSMALL}). 13004 13005\fun{GEN}{FFX_roots}{GEN f, GEN a} returns the roots (\typ{FFELT}) 13006of the univariate polynomial \kbd{f} over the definition field of the 13007\typ{FFELT} \kbd{a}. The coefficients of \kbd{f} must be of type \typ{INT}, 13008\typ{INTMOD} or \typ{FFELT} and compatible with \kbd{a}. 13009 13010\fun{GEN}{FFX_preimagerel}{GEN F, GEN x, GEN a} returns $P\%F$ 13011where \kbd{P=x.pol} assuming $a$ and $x$ belongs to fields having the same 13012characteristic, and that the coefficients of $F$ belong to the definition 13013field of $a$. 13014 13015\fun{GEN}{FFX_preimage}{GEN F, GEN x, GEN a} as \kbd{FFX\_preimagerel} 13016but return \kbd{NULL} if the remainder is of degree greater or equal to $1$, 13017the constant coefficient otherwise. 13018 13019\subsec{FFM} 13020 13021\fun{GEN}{FFM_FFC_gauss}{GEN M, GEN C, GEN ff} given a matrix \kbd{M} 13022(\typ{MAT}) and a column vector \kbd{C} (\typ{COL}) over the finite 13023field given by \kbd{ff} (\typ{FFELT}) such that $M$ is invertible, 13024return the unique column vector $X$ such that $MX=C$. 13025 13026\fun{GEN}{FFM_FFC_invimage}{GEN M, GEN C, GEN ff} given a matrix 13027\kbd{M} (\typ{MAT}) and a column vector \kbd{C} (\typ{COL}) over the 13028finite field given by \kbd{ff} (\typ{FFELT}), return a column vector 13029\kbd{X} such that $MX=C$, or \kbd{NULL} if no such vector exists. 13030 13031\fun{GEN}{FFM_FFC_mul}{GEN M, GEN C, GEN ff} returns the product of 13032the matrix~\kbd{M} (\typ{MAT}) and the column vector~\kbd{C} 13033(\typ{COL}) over the finite field given by \kbd{ff} (\typ{FFELT}). 13034 13035\fun{GEN}{FFM_deplin}{GEN M, GEN ff} returns a nonzero vector 13036(\typ{COL}) in the kernel of the matrix~\kbd{M} over the finite field 13037given by \kbd{ff}, or \kbd{NULL} if no such vector exists. 13038 13039\fun{GEN}{FFM_det}{GEN M, GEN ff} returns the determinant of the 13040matrix~\kbd{M} over the finite field given by \kbd{ff}. 13041 13042\fun{GEN}{FFM_gauss}{GEN M, GEN N, GEN ff} given two matrices \kbd{M} 13043and~\kbd{N} (\typ{MAT}) over the finite field given by \kbd{ff} 13044(\typ{FFELT}) such that $M$ is invertible, return the unique matrix 13045$X$ such that $MX=N$. 13046 13047\fun{GEN}{FFM_image}{GEN M, GEN ff} returns a matrix whose columns 13048span the image of the matrix~\kbd{M} over the finite field given by 13049\kbd{ff}. 13050 13051\fun{GEN}{FFM_indexrank}{GEN M, GEN ff} given a matrix \kbd{M} of 13052rank~$r$ over the finite field given by \kbd{ff}, returns a vector 13053with two \typ{VECSMALL} components $y$ and $z$ containing $r$ row and 13054column indices, respectively, such that the $r\times r$-matrix formed 13055by the \kbd{M[i,j]} for $i$ in $y$ and $j$ in $z$ is invertible. 13056 13057\fun{GEN}{FFM_inv}{GEN M, GEN ff} returns the inverse of the square 13058matrix~\kbd{M} over the finite field given by \kbd{ff}, or \kbd{NULL} 13059if \kbd{M} is not invertible. 13060 13061\fun{GEN}{FFM_invimage}{GEN M, GEN N, GEN ff} given two matrices 13062\kbd{M} and~\kbd{N} (\typ{MAT}) over the finite field given by 13063\kbd{ff} (\typ{FFELT}), return a matrix \kbd{X} such that $MX=N$, or 13064\kbd{NULL} if no such matrix exists. 13065 13066\fun{GEN}{FFM_ker}{GEN M, GEN ff} returns the kernel of the \typ{MAT} 13067\kbd{M} over the finite field given by the \typ{FFELT} \kbd{ff}. 13068 13069\fun{GEN}{FFM_mul}{GEN M, GEN N, GEN ff} returns the product of the 13070matrices \kbd{M} and~\kbd{N} (\typ{MAT}) over the finite field given 13071by \kbd{ff} (\typ{FFELT}). 13072 13073\fun{long}{FFM_rank}{GEN M, GEN ff} returns the rank of the 13074matrix~\kbd{M} over the finite field given by \kbd{ff}. 13075 13076\fun{GEN}{FFM_suppl}{GEN M, GEN ff} given a matrix \kbd{M} over the 13077finite field given by \kbd{ff} whose columns are linearly independent, 13078returns a square invertible matrix whose first columns are those 13079of~\kbd{M}. 13080 13081\subsec{FFXQ} 13082 13083\fun{GEN}{FFXQ_mul}{GEN P, GEN Q, GEN T, GEN a} returns the product 13084of the polynomials \kbd{P} and \kbd{Q} modulo the polynomial \kbd{T}, where 13085\kbd{P}, \kbd{Q} and \kbd{T} are defined over the definition field of the 13086\typ{FFELT} \kbd{a}. 13087 13088\fun{GEN}{FFXQ_sqr}{GEN P, GEN T, GEN a} returns the square 13089of the polynomial \kbd{P} modulo the polynomial \kbd{T}, where \kbd{P} and 13090\kbd{T} are defined over the definition field of the \typ{FFELT} \kbd{a}. 13091 13092\fun{GEN}{FFXQ_inv}{GEN P, GEN Q, GEN a} returns the inverse 13093of the polynomial \kbd{P} modulo the polynomial \kbd{Q}, where \kbd{P} and 13094\kbd{Q} are defined over the definition field of the \typ{FFELT} \kbd{a}. 13095 13096\fun{GEN}{FFXQ_minpoly}{GEN Pf, GEN Qf, GEN a} returns the minimal 13097polynomial of the polynomial \kbd{P} modulo the polynomial \kbd{Q}, where 13098\kbd{P} and \kbd{Q} are defined over the definition field of the \typ{FFELT} 13099\kbd{a}. 13100 13101\section{Transcendental functions} 13102 13103The following two functions are only useful when interacting with \kbd{gp}, 13104to manipulate its internal default precision (expressed as a number of 13105decimal digits, not in words as used everywhere else): 13106 13107\fun{long}{getrealprecision}{void} returns \kbd{realprecision}. 13108 13109\fun{long}{setrealprecision}{long n, long *prec} sets the new 13110\kbd{realprecision} to $n$, which is returned. As a side effect, set 13111\kbd{prec} to the corresponding number of words \kbd{ndec2prec(n)}. 13112 13113\subsec{Transcendental functions with \typ{REAL} arguments} 13114 13115In the following routines, $x$ is assumed to be a \typ{REAL} and the result 13116is a \typ{REAL} (sometimes a \typ{COMPLEX} with \typ{REAL} components), with 13117the largest accuracy which can be deduced from the input. The naming scheme 13118is inconsistent here, since we sometimes use the prefix \kbd{mp} even though 13119\typ{INT} inputs are forbidden: 13120 13121\fun{GEN}{sqrtr}{GEN x} returns the square root of $x$. 13122 13123\fun{GEN}{cbrtr}{GEN x} returns the real cube root of $x$. 13124 13125\fun{GEN}{sqrtnr}{GEN x, long n} returns the $n$-th root of $x$, assuming 13126$n\geq 1$ and $x \geq 0$. 13127 13128\fun{GEN}{sqrtnr_abs}{GEN x, long n} returns the $n$-th root of $|x|$, 13129assuming $n\geq 1$ and $x \neq 0$. 13130 13131\fun{GEN}{mpcos[z]}{GEN x[, GEN z]} returns $\cos(x)$. 13132 13133\fun{GEN}{mpsin[z]}{GEN x[, GEN z]} returns $\sin(x)$. 13134 13135\fun{GEN}{mplog[z]}{GEN x[, GEN z]} returns $\log(x)$. We must have $x > 0$ 13136since the result must be a \typ{REAL}. Use \kbd{glog} for the general case, 13137where you want such computations as $\log(-1) = I$. 13138 13139\fun{GEN}{mpexp[z]}{GEN x[, GEN z]} returns $\exp(x)$. 13140 13141\fun{GEN}{mpexpm1}{GEN x} returns $\exp(x)-1$, but is more accurate than 13142\kbd{subrs(mpexp(x), 1)}, which suffers from catastrophic cancellation if 13143$|x|$ is very small. 13144 13145\fun{void}{mpsincosm1}{GEN x, GEN *s, GEN *c} sets $s$ and $c$ to 13146$\sin(x)$ and $\cos(x)-1$ respectively, where $x$ is a \typ{REAL}; the latter 13147is more accurate than \kbd{subrs(mpcos(y), 1)}, which suffers from 13148catastrophic cancellation if $|x|$ is very small. 13149 13150\fun{GEN}{mpveceint1}{GEN C, GEN eC, long n} as \kbd{veceint1}; assumes 13151that $C > 0$ is a \typ{REAL} and that \kbd{eC} is \kbd{NULL} or \kbd{mpexp(C)}. 13152 13153\fun{GEN}{mpeint1}{GEN x, GEN expx} returns \kbd{eint1}$(x)$, for a \typ{REAL} 13154$x\neq 0$, assuming that \kbd{expx} is \kbd{mpexp}$(x)$. 13155 13156\fun{GEN}{mplambertW}{GEN y} solution $x$ of the implicit equation 13157$x \exp(x) = y$, for $y > 0$ a \typ{REAL}. 13158 13159\noindent Useful low-level functions which \emph{disregard} the sign of $x$: 13160 13161\fun{GEN}{sqrtr_abs}{GEN x} returns $\sqrt{|x|}$ assuming $x\neq 0$. 13162 13163\fun{GEN}{cbrtr_abs}{GEN x} returns $|x|^{1/3}$ assuming $x\neq 0$. 13164 13165\fun{GEN}{exp1r_abs}{GEN x} returns $\exp(|x|) - 1$, assuming $x \neq 0$. 13166 13167\fun{GEN}{logr_abs}{GEN x} returns $\log(|x|)$, assuming $x \neq 0$. 13168 13169\subsec{Other complex transcendental functions} 13170 13171\fun{GEN}{szeta}{long s, long prec} returns the value of Riemann's zeta 13172function at the (possibly negative) integer $s\neq 1$, in relative accuracy 13173\kbd{prec}. 13174 13175\fun{GEN}{veczeta}{GEN a, GEN b, long N, long prec} returns in a vector 13176all the $\zeta(aj + b)$, where $j = 0, 1, \dots, N-1$, where $a$ and $b$ are 13177real numbers (of arbitrary type, although \typ{INT} is treated more 13178efficiently) and $b > 1$. Assumes that $N \geq 1$. 13179 13180\fun{GEN}{ggamma1m1}{GEN x, long prec} return $\Gamma(1+x) - 1$ assuming 13181$|x| < 1$. Guard against cancellation when $x$ is small. 13182 13183\noindent A few variants on sin and cos: 13184 13185\fun{void}{mpsincos}{GEN x, GEN *s, GEN *c} sets $s$ and $c$ to 13186$\sin(x)$ and $\cos(x)$ respectively, where $x$ is a \typ{REAL} 13187 13188\fun{void}{mpsinhcosh}{GEN x, GEN *s, GEN *c} sets $s$ and $c$ to 13189$\sinh(x)$ and $\cosh(x)$ respectively, where $x$ is a \typ{REAL} 13190 13191\fun{GEN}{expIr}{GEN x} returns $\exp(ix)$, where $x$ is a \typ{REAL}. 13192The return type is \typ{COMPLEX} unless the imaginary part is equal to $0$ 13193to the current accuracy (its sign is $0$). 13194 13195\fun{GEN}{expIPiR}{GEN x, long prec} return $\exp(i \pi x)$, where $x$ is a 13196real number (\typ{INT}, \typ{FRAC} or \typ{REAL}). 13197 13198\fun{GEN}{expIPiC}{GEN z, long prec} return $\exp(i \pi x)$, where $x$ is a 13199complex number (\typ{INT}, \typ{FRAC}, \typ{REAL} or \typ{COMPLEX}). 13200 13201\fun{GEN}{expIxy}{GEN x, GEN y, long prec} returns $\exp(ixy)$. Efficient 13202when $x$ is real and $y$ pure imaginary. 13203 13204\fun{GEN}{pow2Pis}{GEN s, long prec} returns $(2\pi)^s$. The intent of this 13205function and the next one is to be accurate even if $s$ has a huge imaginary 13206part: $\pi$ is computed at an accuracy taking into account the cancellation 13207induced by argument reduction when computing the sine or cosine of 13208$\Im s \log 2\pi$. 13209 13210\fun{GEN}{powPis}{GEN s, long prec} returns $\pi^s$, as \kbd{pow2Pis}. 13211 13212\fun{void}{gsincos}{GEN x, GEN *s, GEN *c, long prec} general case. 13213 13214\fun{GEN}{rootsof1_cx}{GEN d, long prec} return $e(1/d)$ at precision 13215\kbd{prec}, $e(x) = \exp(2i\pi x)$. 13216 13217\fun{GEN}{rootsof1u_cx}{ulong d, long prec} return $e(1/d)$ at 13218precision \kbd{prec}. 13219 13220\fun{GEN}{rootsof1q_cx}{long a, long b, long prec} return $e(a/b)$ at 13221precision \kbd{prec}. 13222 13223\fun{GEN}{rootsof1powinit}{long a, long b, long prec} precompute $b$-th 13224roots of $1$ for \kbd{rootsof1pow}, i.e. to later compute $e(ac/b)$ for 13225varying $c$. 13226 13227\fun{GEN}{rootsof1pow}{GEN T, long c} given 13228$T = \kbd{rootsof1powinit}(a,b,\kbd{prec})$, return $e(ac/b)$. 13229 13230 13231\noindent A generalization of \tet{affrr_fixlg} 13232 13233\fun{GEN}{affc_fixlg}{GEN x, GEN res} assume \kbd{res} was allocated using 13234\tet{cgetc}, and that $x$ is either a \typ{REAL} or a \typ{COMPLEX} 13235with \typ{REAL} components. Assign $x$ to \kbd{res}, first shortening 13236the components of \kbd{res} if needed (in a \kbd{gerepile}-safe way). Further 13237convert \kbd{res} to a \typ{REAL} if $x$ is a \typ{REAL}. 13238 13239\fun{GEN}{trans_eval}{const char *fun, GEN (*f) (GEN, long), GEN x, long prec} 13240evaluate the transcendental function $f$ (named \kbd{"fun"} at the argument 13241$x$ and precision \kbd{prec}. This is a quick way to implement a transcendental 13242function to be made available under GP, starting from a $C$ function 13243handling only \typ{REAL} and \typ{COMPLEX} arguments. This routine first 13244converts $x$ to a suitable type: 13245 13246\item \typ{INT}/\typ{FRAC} to \typ{REAL} of precision \kbd{prec}, \typ{QUAD} to 13247\typ{REAL} or \typ{COMPLEX} of precision \kbd{prec}. 13248 13249\item \typ{POLMOD} to a \typ{COL} of complex embeddings (as in \tet{conjvec}) 13250 13251Then evaluates the function at \typ{VEC}, \typ{COL}, \typ{MAT} arguments 13252coefficientwise. 13253 13254\subsec{Modular functions} 13255 13256\fun{GEN}{cxredsl2}{GEN z, GEN *g} given $t$ a \typ{COMPLEX} belonging to the 13257upper half-plane, find $\gamma \in \text{SL}_2(\Z)$ such that $\gamma \cdot z$ 13258belongs to the standard fundamental domain and set \kbd{*g} to $\gamma$. 13259 13260\fun{GEN}{cxredsl2_i}{GEN z, GEN *g, GEN *czd} as \kbd{cxredsl2}; also sets 13261\kbd{*czd} to $cz + d$, if $\gamma = [a,b;c,d]$. 13262 13263\fun{GEN}{cxEk}{GEN tau, long k, long prec} returns $E_k(\tau)$ by direct 13264evaluation of $1 + 2/\zeta(1-k) \sum_n n^{k-1} q^n/(1-q^n)$, $q = e(\tau)$. 13265Assume that $\Im \tau > 0$ and $k$ even. Very slow unless $\tau$ is already 13266reduced modulo $\text{SL}_2(\Z)$. Not \kbd{gerepile}-clean but suitable for 13267\kbd{gerepileupto}. 13268 13269\subsec{Transcendental functions with \typ{PADIC} arguments} 13270 13271\fun{GEN}{Qp_exp}{GEN x} shortcut for \kbd{gexp(x, /*ignored*/prec)} 13272 13273\fun{GEN}{Qp_gamma}{GEN x} shortcut for \kbd{ggamma(x, /*ignored*/prec)} 13274 13275\fun{GEN}{Qp_log}{GEN x} shortcut for \kbd{glog(x, /*ignored*/prec)} 13276 13277\fun{GEN}{Qp_sqrt}{GEN x} shortcut for \kbd{gsqrt(x, /*ignored*/prec)} 13278Return \kbd{NULL} if $x$ is not a square. 13279 13280\fun{GEN}{Qp_sqrtn}{GEN x, GEN n, GEN *z} shortcut for \kbd{gsqrtn(x, n, z, 13281/*ignored*/prec)}. Return \kbd{NULL} if $x$ is not an $n$-th power. 13282 13283\fun{GEN}{Qp_agm2_sequence}{GEN a1, GEN b1} assume $a_1/b_1 = 1$ mod $p$ 13284if $p$ odd and mod $2^4$ if $p = 2$. Let $A_1 = a_1/p^v$ and $B_1 = b_1/p^v$ 13285with $v = v_p(a_1) = v_p(b_1)$; let further 13286$A_{n+1} = (A_n + B_n + 2 B_{n+1}) / 4$, 13287$B_{n+1} = B_n \sqrt{A_n / B_n}$ (the square root of $A_n B_n$ congruent to 13288$B_n$ mod $p$) and $R_n = p^v(A_n - B_n)$. We stop when $R_n$ is $0$ 13289at the given $p$-adic accuracy. This function returns in a triplet \typ{VEC} 13290the three sequences $(A_n)$, $(B_n)$ and $(R_n)$, corresponding to a sequence 13291of $2$-isogenies on the Tate curve $y^2 = x(x-a_1)(x+a_1-b_1)$. The 13292common limit of $A_n$ and $B_n$ is the $M_2(a_1,b_1)$, the square 13293of the $p$-adic AGM of $\sqrt(a_1)$ and $\sqrt(b_1)$. This is given 13294by \tet{ellQp_Ei} and is used by corresponding ascending and descending 13295$p$-adic Landen transforms: 13296 13297\fun{void}{Qp_ascending_Landen}{GEN ABR, GEN *ptx, GEN *pty} 13298 13299\fun{void}{Qp_descending_Landen}{GEN ABR, GEN *ptx, GEN *pty} 13300 13301\subsec{Cached constants} 13302 13303The cached constant is returned at its current precision, which may be larger 13304than \kbd{prec}. One should always use the \kbd{mp\var{xxx}} variant: 13305\kbd{mppi}, \kbd{mpeuler}, or \kbd{mplog2}. 13306 13307\fun{GEN}{consteuler}{long prec} precomputes Euler-Mascheroni's constant 13308at precision \kbd{prec}. 13309 13310\fun{GEN}{constcatalan}{long prec} precomputes Catalan's constant at precision 13311\kbd{prec}. 13312 13313\fun{GEN}{constpi}{long prec} precomputes $\pi$ at precision \kbd{prec}. 13314 13315\fun{GEN}{constlog2}{long prec} precomputes $\log(2)$ at precision 13316\kbd{prec}. 13317 13318\fun{void}{constbern}{long n} precomputes the $n$ even \idx{Bernoulli} numbers 13319$B_2,\dots,B_{2n}$ as \typ{FRAC}. No more than $n$ Bernoulli numbers will 13320ever be stored (by \tet{bernfrac} or \tet{bernreal}), unless a subsequent 13321call to \kbd{constbern} increases the cache. 13322 13323\fun{GEN}{constzeta}{long n, long prec} ensures that the $n$ values 13324$\gamma, \zeta(2),\dots, \zeta(n)$ are cached at accuracy bigger than or equal 13325to \kbd{prec} and return a vector containing at least those value. Note that 13326$\gamma = \lim_1 \zeta(s) - 1/(s-1)$. If the accuracy of cached data is too 13327low or $n$ is greater than the cache length, the cache is recomputed at the 13328given parameters. 13329 13330The following functions use cached data if \kbd{prec} is smaller than the 13331precision of the cached value; otherwise the newly computed data replaces the 13332old cache. 13333 13334\fun{GEN}{mppi}{long prec} returns $\pi$ at precision \kbd{prec}. 13335 13336\fun{GEN}{Pi2n}{long n, long prec} returns $2^n\pi$ at precision \kbd{prec}. 13337 13338\fun{GEN}{PiI2}{long n, long prec} returns the complex number $2\pi i$ at 13339precision \kbd{prec}. 13340 13341\fun{GEN}{PiI2n}{long n, long prec} returns the complex number $2^n\pi i$ at 13342precision \kbd{prec}. 13343 13344\fun{GEN}{mpeuler}{long prec} returns Euler-Mascheroni's constant at 13345precision \kbd{prec}. 13346 13347\fun{GEN}{mpeuler}{long prec} returns Catalan's number at precision \kbd{prec}. 13348 13349\fun{GEN}{mplog2}{long prec} returns $\log 2$ at precision \kbd{prec}. 13350 13351The following functions use the \idx{Bernoulli} numbers cache initialized by 13352\kbd{constbern}: 13353 13354\fun{GEN}{bernreal}{long i, long prec} returns the \idx{Bernoulli} number 13355$B_i$ as a \typ{REAL} at precision \kbd{prec}. If \kbd{constbern(n)} 13356was called previously with $n \geq i$, then the cached value is (converted to 13357a \typ{REAL} of accuracy \kbd{prec} then) returned. Otherwise, the missing 13358value is computed; the cache is not updated. 13359 13360\fun{GEN}{bernfrac}{long i} returns the \idx{Bernoulli} number $B_i$ as a 13361rational number (\typ{FRAC} or \typ{INT}). If the \kbd{constbern} cache includes 13362$B_i$, the latter is returned. Otherwise, the missing value is computed; the 13363cache is not updated. 13364 13365\subsec{Obsolete functions} 13366 13367\fun{void}{mpbern}{long n, long prec} 13368 13369\section{Permutations } 13370 13371\noindent Permutations are represented in two different ways 13372 13373\item (\kbd{perm}) a \typ{VECSMALL} $p$ representing the bijection $i\mapsto 13374p[i]$; unless mentioned otherwise, this is the form used in the functions 13375below for both input and output, 13376 13377\item (\kbd{cyc}) a \typ{VEC} of \typ{VECSMALL}s representing a product of 13378disjoint cycles. 13379 13380\fun{GEN}{identity_perm}{long n} return the identity permutation on $n$ 13381symbols. 13382 13383\fun{GEN}{cyclic_perm}{long n, long d} return the cyclic permutation mapping 13384$i$ to $i+d$ (mod $n$) in $S_n$. Assume that $d \leq n$. 13385 13386\fun{GEN}{perm_mul}{GEN s, GEN t} multiply $s$ and $t$ (composition $s\circ t$) 13387 13388\fun{GEN}{perm_sqr}{GEN s} multiply $s$ by itself (composition $s\circ s$) 13389 13390\fun{GEN}{perm_conj}{GEN s, GEN t} return $sts^{-1}$. 13391 13392\fun{int}{perm_commute}{GEN p, GEN q} return $1$ if $p$ and $q$ commute, 0 13393otherwise. 13394 13395\fun{GEN}{perm_inv}{GEN p} returns the inverse of $p$. 13396 13397\fun{GEN}{perm_pow}{GEN p, GEN n} returns $p^n$ 13398 13399\fun{GEN}{perm_powu}{GEN p, ulong n} returns $p^n$ 13400 13401\fun{GEN}{cyc_pow_perm}{GEN p, long n} the permutation $p$ is given as 13402a product of disjoint cycles (\kbd{cyc}); return $p^n$ (as a \kbd{perm}). 13403 13404\fun{GEN}{cyc_pow}{GEN p, long n} the permutation $p$ is given as 13405a product of disjoint cycles (\kbd{cyc}); return $p^n$ (as a \kbd{cyc}). 13406 13407\fun{GEN}{perm_cycles}{GEN p} return the cyclic decomposition of $p$. 13408 13409\fun{GEN}{perm_order}{GEN p} returns the order of the permutation $p$ 13410(as the lcm of its cycle lengths). 13411 13412\fun{ulong}{perm_orderu}{GEN p} returns the order of the permutation $p$ 13413(as the lcm of its cycle lengths) assuming it fits in a \kbd{ulong}. 13414 13415\fun{long}{perm_sign}{GEN p} returns the sign of the permutation $p$. 13416 13417\fun{GEN}{vecperm_orbits}{GEN gen, long n} return the orbits of 13418$\{1,2,\ldots,n\}$ under the action of the subgroup of $S_n$ generated by 13419$gen$. 13420 13421\fun{GEN}{Z_to_perm}{long n, GEN x} as \kbd{numtoperm}, returning a 13422\typ{VECSMALL}. 13423 13424\fun{GEN}{perm_to_Z}{GEN v} as \kbd{permtonum} for a \typ{VECSMALL} input. 13425 13426\fun{GEN}{perm_to_GAP}{GEN p} return a \typ{STR} which is a representation 13427of $p$ comptatible with the GAP computer algebra system. 13428 13429\section{Small groups} 13430 13431The small (finite) groups facility is meant to deal with subgroups of Galois 13432groups obtained by \tet{galoisinit} and thus is currently limited to weakly 13433super-solvable groups. 13434 13435A group \var{grp} of order $n$ is represented by its regular representation 13436(for an arbitrary ordering of its element) in $S_n$. A subgroup of such group 13437is represented by the restriction of the representation to the subgroup. 13438A \emph{small group} can be either a group or a subgroup. Thus it is embedded 13439in some $S_n$, where $n$ is the multiple of the order. Such an $n$ is called 13440the \emph{domain} of the small group. The domain of a trivial subgroup cannot 13441be derived from the subgroup data, so some functions require the subgroup 13442domain as argument. 13443 13444The small group \var{grp} is represented by a \typ{VEC} with two 13445components: 13446 13447$\var{grp}[1]$ is a generating subset $[s_1,\ldots,s_g]$ of \var{grp} 13448expressed as a vector of permutations of length~$n$. 13449 13450$\var{grp}[2]$ contains the relative orders $[o_1,\ldots,o_g]$ of 13451the generators $\var{grp}[1]$. 13452 13453See \tet{galoisinit} for the technical details. 13454 13455\fun{GEN}{checkgroup}{GEN gal, GEN *elts} check whether \var{gal} is a 13456small group or a Galois group. Returns the underlying small 13457group and set \var{elts} to the list of elements or to \kbd{NULL} if it is not 13458known. 13459 13460\fun{GEN}{checkgroupelts}{GEN gal} 13461check whether \var{gal} is a small group or a Galois group, or a vector of 13462permutations listing the group elements. Returns the list of group elements as 13463permutations. 13464 13465\fun{GEN}{galois_group}{GEN gal} return the underlying small group of the 13466Galois group \var{gal}. 13467 13468\fun{GEN}{cyclicgroup}{GEN g, long s} return the cyclic group with generator 13469$g$ of order $s$. 13470 13471\fun{GEN}{trivialgroup}{void} return the trivial group. 13472 13473\fun{GEN}{dicyclicgroup}{GEN g1, GEN g2, long s1, long s2} returns the group 13474with generators \var{g1}, \var{g2} with respecting relative orders \var{s1}, 13475\var{s2}. 13476 13477\fun{GEN}{abelian_group}{GEN v} let v be a \typ{VECSMALL} seen as the SNF of 13478a small abelian group, return its regular representation. 13479 13480\fun{long}{group_domain}{GEN grp} returns the \kbd{domain} of the 13481\emph{nontrivial} small group \var{grp}. Return an error if \var{grp} is 13482trivial. 13483 13484\fun{GEN}{group_elts}{GEN grp, long n} returns the list of elements of the 13485small group \var{grp} of domain \var{n} as permutations. 13486 13487\fun{GEN}{groupelts_to_group}{GEN elts}, where \var{elts} is the list of 13488elements of a group, returns the corresponding small group, if it 13489exists, otherwise return \kbd{NULL}. 13490 13491\fun{GEN}{group_set}{GEN grp, long n} returns a \var{F2v} $b$ such that 13492$b[i]$ is set if and only if the small group \var{grp} of domain \var{n} 13493contains a permutation sending $1$ to $i$. 13494 13495\fun{GEN}{groupelts_set}{GEN elts, long n}, where \var{elts} is the list of 13496elements of a small group of domain \var{n}, returns a \var{F2v} $b$ such that 13497$b[i]$ is set if and only if the small group contains a permutation sending $1$ 13498to $i$. 13499 13500\fun{GEN}{groupelts_conj_set}{GEN elts, GEN p}, where \var{elts} is the list of 13501elements of a small group of domain \var{n}, returns a \var{F2v} $b$ such that 13502$b[i]$ is set if and only if the small group contains a permutation sending 13503$p^{-1}[1]$ to $p^{-1}[i]$. 13504 13505\fun{int}{group_subgroup_is_faithful}{GEN G, GEN H} return $1$ if the action 13506of $G$ on $G/H$ by translation is faithful, $0$ otherwise. 13507 13508\fun{GEN}{groupelts_conjclasses}{GEN elts, long *pn}, where \var{elts} is 13509the list of elements of a small group (sorted with respect to 13510\kbd{vecsmall\_lexcmp}), return a \typ{VECSMALL} \kbd{conj} of 13511the same length such that \kbd{conj[i]} is the index in $\{1,\cdots,n\}$ of 13512the conjugacy class of \kbd{elts[i]} for some unspecified but deterministic 13513ordering of the classes, where $n$ is the number of conjugacy classes. If 13514\kbd{pn} is non \kbd{NULL}, \kbd{*pn} is set to $n$. 13515 13516\fun{GEN}{conjclasses_repr}{GEN conj, long nb}, 13517where \kbd{conj} and \kbd{nb} are as returned by the call 13518\kbd{groupelts\_conjclasses(elts)}, return \typ{VECSMALL} of length \kbd{nb} 13519which gives the indices in \kbd{elts} of a representative of each conjugacy 13520class. 13521 13522\fun{GEN}{group_to_cc}{GEN G}, where $G$ is a small group or a Galois group, 13523returns a \kbd{cc} (conjclasses) structure \kbd{[elts,conj,rep,flag]}, 13524 as obtained by \kbd{alggroupcenter}, where \kbd{conj} is 13525\kbd{groupelts\_conjclasses}$(\kbd{elts})$ and \kbd{rep} is the attached 13526\kbd{conjclasses\_repr}. \kbd{flag} is 1 if the permutation representation 13527is transitive (in which case an element $g$ of $G$ is characterized by $g[1]$), 13528and 0 otherwise. Shallow function. 13529 13530\fun{long}{group_order}{GEN grp} returns the order of the small group 13531\var{grp} (which is the product of the relative orders). 13532 13533\fun{long}{group_isabelian}{GEN grp} returns $1$ if the small group 13534\var{grp} is Abelian, else $0$. 13535 13536\fun{GEN}{group_abelianHNF}{GEN grp, GEN elts} if \var{grp} is not Abelian, 13537returns \kbd{NULL}, else returns the HNF matrix of \var{grp} with respect to 13538the generating family $\var{grp}[1]$. If \var{elts} is no \kbd{NULL}, it must 13539be the list of elements of \var{grp}. 13540 13541\fun{GEN}{group_abelianSNF}{GEN grp, GEN elts} if \var{grp} is not Abelian, 13542returns \kbd{NULL}, else returns its cyclic decomposition. If \var{elts} is no 13543\kbd{NULL}, it must be the list of elements of \var{grp}. 13544 13545\fun{long}{group_subgroup_isnormal}{GEN G, GEN H}, $H$ being a subgroup of the 13546small group $G$, returns $1$ if $H$ is normal in $G$, else $0$. 13547 13548\fun{long}{group_isA4S4}{GEN grp} returns $1$ if the small group 13549\var{grp} is isomorphic to $A_4$, $2$ if it is isomorphic to $S_4$, 13550$3$ if it is isomorphic to $(3\times 3):4$ and 13551$0$ else. This is mainly to deal with the idiosyncrasy of the format. 13552 13553\fun{GEN}{group_leftcoset}{GEN G, GEN g} where $G$ is a small group and $g$ a 13554permutation of the same domain, the left coset $gG$ as a vector of 13555permutations. 13556 13557\fun{GEN}{group_rightcoset}{GEN G, GEN g} where $G$ is a small group and $g$ a 13558permutation of the same domain, the right coset $Gg$ as a vector of 13559permutations. 13560 13561\fun{long}{group_perm_normalize}{GEN G, GEN g} where $G$ is a small group and 13562$g$ a permutation of the same domain, return $1$ if $gGg^{-1}=G$, else $0$. 13563 13564\fun{GEN}{group_quotient}{GEN G, GEN H}, where $G$ is a small group and 13565$H$ is a subgroup of $G$, returns the quotient map $G\rightarrow G/H$ 13566as an abstract data structure. 13567 13568\fun{GEN}{groupelts_quotient}{GEN elts, GEN H}, where \var{elts} is the list of 13569elements of a small group $G$, $H$ is a subgroup of $G$, returns the quotient 13570map $G\rightarrow G/H$ as an abstract data structure. 13571 13572\fun{GEN}{quotient_perm}{GEN C, GEN g} where $C$ is the quotient map 13573$G\rightarrow G/H$ for some subgroup $H$ of $G$ and $g$ an element of $G$, 13574return the image of $g$ by $C$ (i.e. the coset $gH$). 13575 13576\fun{GEN}{quotient_group}{GEN C, GEN G} where $C$ is the quotient map 13577$G\rightarrow G/H$ for some \emph{normal} subgroup $H$ of $G$, return the 13578quotient group $G/H$ as a small group. 13579 13580\fun{GEN}{quotient_groupelts}{GEN C} where $C$ is the quotient map 13581$G\rightarrow G/H$ for some group $G$ and some \emph{normal} subgroup $H$ of $G$, 13582return the list of elements of the quotient group $G/H$ (as permutations over 13583corresponding to the regular representation). 13584 13585\fun{GEN}{quotient_subgroup_lift}{GEN C, GEN H, GEN S} where $C$ is the 13586quotient map $G\rightarrow G/H$ for some group $G$ normalizing $H$ and $S$ is 13587a subgroup of $G/H$, return the inverse image of $S$ by $C$. 13588 13589\fun{GEN}{group_subgroups}{GEN grp} returns the list of subgroups of the 13590small group \var{grp} as a \typ{VEC}. 13591 13592\fun{GEN}{subgroups_tableset}{GEN S, long n} where $S$ is a vector of subgroups 13593of domain $n$, returns a table which matchs the set of elements of the 13594subgroups against the index of the subgroups. 13595 13596\fun{long}{tableset_find_index}{GEN tbl, GEN set} searchs the set \kbd{set} in 13597the table \kbd{tbl} and returns its attached index, or $0$ if not found. 13598 13599\fun{GEN}{groupelts_abelian_group}{GEN elts} where \var{elts} is the list of 13600elements of an \emph{Abelian} small group, returns the corresponding 13601small group. 13602 13603\fun{long}{groupelts_exponent}{GEN elts} where \var{elts} is the list of 13604elements of a small group, returns the exponent the group (the LCM of the order 13605of the elements of the group). 13606 13607\fun{GEN}{groupelts_center}{GEN elts} where \var{elts} is the list of elements 13608of a small group, returns the list of elements of the center of the 13609group. 13610 13611\fun{GEN}{group_export}{GEN grp, long format} convert a small group 13612to another format, as a \typ{STR} describing the group for the given syntax, 13613see \tet{galoisexport}. 13614 13615\fun{GEN}{group_export_GAP}{GEN G} export a small group to GAP format. 13616 13617\fun{GEN}{group_export_MAGMA}{GEN G} export a small group to MAGMA format. 13618 13619\fun{long}{group_ident}{GEN grp, GEN elts} returns the index of the small group 13620\var{grp} in the GAP4 Small Group library, see \tet{galoisidentify}. If 13621\var{elts} is not \kbd{NULL}, it must be the list of elements of \var{grp}. 13622 13623\fun{long}{group_ident_trans}{GEN grp, GEN elts} returns the index of the 13624regular representation of the small group \var{grp} in the GAP4 Transitive 13625Group library, see \tet{polgalois}. If \var{elts} is no \kbd{NULL}, it must be 13626the list of elements of \var{grp}. 13627 13628\newpage 13629\chapter{Standard data structures} 13630 13631\section{Character strings} 13632 13633\subsec{Functions returning a \kbd{char *}} 13634 13635\fun{char*}{pari_strdup}{const char *s} returns a malloc'ed copy of $s$ 13636(uses \kbd{pari\_malloc}). 13637 13638\fun{char*}{pari_strndup}{const char *s, long n} returns a malloc'ed copy of 13639at most $n$ chars from $s$ (uses \kbd{pari\_malloc}). If $s$ is longer than 13640$n$, only $n$ characters are copied and a terminal null byte is added. 13641 13642\fun{char*}{stack_strdup}{const char *s} returns a copy of $s$, allocated 13643on the PARI stack (uses \kbd{stack\_malloc}). 13644 13645\fun{char*}{stack_strcat}{const char *s, const char *t} returns the 13646concatenation of $s$ and $t$, allocated on the PARI stack (uses 13647\kbd{stack\_malloc}). 13648 13649\fun{char*}{stack_sprintf}{const char *fmt, ...} runs \kbd{pari\_sprintf} 13650on the given arguments, returning a string allocated on the PARI stack. 13651 13652\fun{char*}{uordinal}{ulong x} return the ordinal number attached to $x$ 13653(i.e. $1$st, $2$nd, etc.) as a \tet{stack_malloc}'ed string. 13654 13655\fun{char*}{itostr}{GEN x} writes the \typ{INT} $x$ to a \tet{stack_malloc}'ed 13656string. 13657 13658\fun{char*}{GENtostr}{GEN x}, using the current default output format 13659(\kbd{GP\_DATA->fmt}, which contains the output style and the number of 13660significant digits to print), converts $x$ to a malloc'ed string. Simple 13661variant of \tet{pari_sprintf}. 13662 13663\fun{char*}{GENtostr_raw}{GEN x} as \tet{GENtostr} with the following 13664differences: 1) the output format is \tet{f_RAW}; 2) the result is allocated 13665on the stack and \emph{must not} be freed. 13666 13667\fun{char*}{GENtostr_unquoted}{GEN x} as \tet{GENtostr_raw} with the following 13668additional difference: a \typ{STR} $x$ is printed without enclosing quotes 13669(to be used by \kbd{print}. 13670 13671\fun{char*}{GENtoTeXstr}{GEN x}, as \kbd{GENtostr}, except that 13672\tet{f_TEX} overrides the output format from \kbd{GP\_DATA->fmt}. 13673 13674\fun{char*}{RgV_to_str}{GEN g, long flag} $g$ being a vector of \kbd{GEN}s, 13675returns a malloc'ed string, the concatenation of the \kbd{GENtostr} applied 13676to its elements, except that \typ{STR} are printed without enclosing quotes. 13677\kbd{flag} determines the output format: \tet{f_RAW}, \tet{f_PRETTYMAT} 13678or \tet{f_TEX}. 13679 13680\subsec{Functions returning a \typ{STR}} 13681 13682\fun{GEN}{strtoGENstr}{const char *s} returns a \typ{STR} with content $s$. 13683 13684\fun{GEN}{strntoGENstr}{const char *s, long n} 13685returns a \typ{STR} containing the first $n$ characters of $s$. 13686 13687\fun{GEN}{chartoGENstr}{char c} returns a \typ{STR} containing the character 13688$c$. 13689 13690\fun{GEN}{GENtoGENstr}{GEN x} returns a \typ{STR} containing the printed 13691form of $x$ (in \tet{raw} format). This is often easier to use that 13692\tet{GENtostr} (which returns a malloc-ed \kbd{char*}) since there is no need 13693to free the string after use. 13694 13695\fun{GEN}{GENtoGENstr_nospace}{GEN x} as \kbd{GENtoGENstr}, removing all 13696spaces from the output. 13697 13698\fun{GEN}{Str}{GEN g} as \tet{RgV_to_str} with output format \tet{f_RAW}, 13699but returns a \typ{STR}, not a malloc'ed string. 13700 13701\fun{GEN}{strtex}{GEN g} as \tet{RgV_to_str} with output format \tet{f_TEX}, 13702but returns a \typ{STR}, not a malloc'ed string. 13703 13704\fun{GEN}{strexpand}{GEN g} as \tet{RgV_to_str} with output format \tet{f_RAW}, 13705performing tilde and environment expansion on the result. Returns a 13706\typ{STR}, not a malloc'ed string. 13707 13708\fun{GEN}{gsprintf}{const char *fmt, ...} equivalent to 13709\kbd{pari\_sprintf(fmt,...}, followed by \tet{strtoGENstr}. Returns a \typ{STR}, 13710not a malloc'ed string. 13711 13712\fun{GEN}{gvsprintf}{const char *fmt, va_list ap} variadic version of 13713\tet{gsprintf} 13714 13715\subsec{Dynamic strings} 13716 13717A \tet{pari_str} is a dynamic string which grows dynamically as needed. 13718This structure contains private data and two public members \kbd{char *string}, 13719which is the string itself and \kbd{use\_stack} which tells whether the 13720string lives 13721 13722\item on the PARI stack (value $1$), meaning that it will be destroyed by any 13723manipulation of the stack, e.g. a \kbd{gerepile} call or resetting 13724\kbd{avma}; 13725 13726\item in malloc'ed memory (value $0$), in which case it is impervious to 13727stack manipulation but will need to be explicitly freed by the user 13728after use, via \kbd{pari\_free(s.string)}. 13729 13730 13731\fun{void}{str_init}{pari_str *S, int use_stack} initializes a dynamic 13732string; if \kbd{use\_stack} is 0, then the string is malloc'ed, else 13733it lives on the PARI stack. 13734 13735\fun{void}{str_printf}{pari_str *S, const char *fmt, ...} write to the end 13736of $S$ the remaining arguments according to PARI format \kbd{fmt}. 13737 13738\fun{void}{str_putc}{pari_str *S, char c} write the character $c$ to the end 13739of $S$. 13740 13741\fun{void}{str_puts}{pari_str *S, const char *s} write the string $s$ to the 13742end of $S$. 13743 13744\section{Output} 13745 13746\subsec{Output contexts} 13747 13748An output coutext, of type \tet{PariOUT}, is a \kbd{struct} 13749that models a stream and contains the following function pointers: 13750\bprog 13751void (*putch)(char); /* fputc()-alike */ 13752void (*puts)(const char*); /* fputs()-alike */ 13753void (*flush)(void); /* fflush()-alike */ 13754@eprog\noindent 13755The methods \tet{putch} and \tet{puts} are used to print a character 13756or a string respectively. The method \tet{flush} is called to finalize a 13757messages. 13758 13759The generic functions \tet{pari_putc}, \tet{pari_puts}, \tet{pari_flush} and 13760\tet{pari_printf} print according to a \emph{default output context}, which 13761should be sufficient for most purposes. Lower level functions are available, 13762which take an explicit output context as first argument: 13763 13764\fun{void}{out_putc}{PariOUT *out, char c} essentially equivalent to 13765\kbd{out->putc(c)}. In addition, registers whether the last character printed 13766was a \kbd{\bs n}. 13767 13768\fun{void}{out_puts}{PariOUT *out, const char *s} essentially equivalent to 13769\kbd{out->puts(s)}. In addition, registers whether the last character printed 13770was a \kbd{\bs n}. 13771 13772\fun{void}{out_printf}{PariOUT *out, const char *fmt, ...} 13773 13774\fun{void}{out_vprintf}{PariOUT *out, const char *fmt, va_list ap} 13775 13776\noindent N.B. The function \kbd{out\_flush} does not exist since it would be 13777identical to \kbd{out->flush()} 13778 13779\fun{int}{pari_last_was_newline}{void} returns a nonzero value if the last 13780character printed via \tet{out_putc} or \tet{out_puts} was \kbd{\bs 13781n}, and $0$ otherwise. 13782 13783\fun{void}{pari_set_last_newline}{int last} sets the boolean value 13784to be returned by the function \tet{pari_last_was_newline} to \var{last}. 13785 13786\subsec{Default output context} They are defined by the global variables 13787\tet{pariOut} and \tet{pariErr} for normal outputs and warnings/errors, and you 13788probably do not want to change them. If you \emph{do} change them, diverting 13789output in nontrivial ways, this probably means that you are rewriting 13790\kbd{gp}. For completeness, we document in this section what the default 13791output contexts do. 13792 13793\misctitle{pariOut} writes output to the \kbd{FILE*} \tet{pari_outfile}, 13794initialized to \tet{stdout}. The low-level methods are actually the standard 13795\kbd{putc} / \kbd{fputs}, plus some magic to handle a log file if one is 13796open. 13797 13798\misctitle{pariErr} prints to the \kbd{FILE*} \tet{pari_errfile}, initialized 13799to \tet{stderr}. The low-level methods are as above. 13800 13801You can stick with the default \kbd{pariOut} output context and change PARI's 13802standard output, redirecting \tet{pari_outfile} to another file, using 13803 13804\fun{void}{switchout}{const char *name} where \kbd{name} is a character string 13805giving the name of the file you want to write to; the output is 13806\emph{appended} at the end of the file. To close the file and revert to 13807outputting to \kbd{stdout}, call \kbd{switchout(NULL)}. 13808 13809\subsec{PARI colors} 13810In this section we describe the low-level functions used to implement GP's 13811color scheme, attached to the \tet{colors} default. The following symbolic 13812names are attached to gp's output strings: 13813 13814\item \tet{c_ERR} an error message 13815 13816\item \tet{c_HIST} a history number (as in \kbd{\%1 = ...}) 13817 13818\item \tet{c_PROMPT} a prompt 13819 13820\item \tet{c_INPUT} an input line (minus the prompt part) 13821 13822\item \tet{c_OUTPUT} an output 13823 13824\item \tet{c_HELP} a help message 13825 13826\item \tet{c_TIME} a timer 13827 13828\item \tet{c_NONE} everything else 13829 13830\emph{If} the \tet{colors} default is set to a nonempty value, before gp 13831outputs a string, it first outputs an ANSI colors escape sequence --- 13832understood by most terminals ---, according to the \kbd{colors} 13833specifications. As long as this is in effect, the following strings are 13834rendered in color, possibly in bold or underlined. 13835 13836\fun{void}{term_color}{long c} prints (as if using \tet{pari_puts}) the ANSI 13837color escape sequence attached to output object \kbd{c}. If \kbd{c} is 13838\tet{c_NONE}, revert to default printing style. 13839 13840\fun{void}{out_term_color}{PariOUT *out, long c} as \tet{term_color}, 13841using output context \kbd{out}. 13842 13843\fun{char*}{term_get_color}{char *s, long c} returns as a character 13844string the ANSI color escape sequence attached to output object \kbd{c}. 13845If \kbd{c} is \tet{c_NONE}, the value used to revert to default printing 13846style is returned. The argument \kbd{s} is either \kbd{NULL} (string 13847allocated on the PARI stack), or preallocated storage (in which case, it must 13848be able to hold at least 16 chars, including the final \kbd{\bs 0}). 13849 13850\subsec{Obsolete output functions} 13851 13852These variants of \fun{void}{output}{GEN x}, which prints \kbd{x}, followed by 13853a newline and a buffer flush are complicated to use and less flexible 13854than what we saw above, or than the \tet{pari_printf} variants. They are 13855provided for backward compatibility and are scheduled to disappear. 13856 13857\fun{void}{brute}{GEN x, char format, long dec} 13858 13859\fun{void}{matbrute}{GEN x, char format, long dec} 13860 13861\fun{void}{texe}{GEN x, char format, long dec} 13862 13863\section{Files} 13864 13865The following routines are trivial wrappers around system functions 13866(possibly around one of several functions depending on availability). 13867They are usually integrated within PARI's diagnostics system, printing 13868messages if \kbd{DEBUGFILES} is high enough. 13869 13870\fun{int}{pari_is_dir}{const char *name} returns $1$ if \kbd{name} points to 13871a directory, $0$ otherwise. 13872 13873\fun{int}{pari_is_file}{const char *name} returns $1$ if \kbd{name} points to 13874a directory, $0$ otherwise. 13875 13876\fun{int}{file_is_binary}{FILE *f} returns $1$ if the file $f$ is a binary 13877file (in the \tet{writebin} sense), $0$ otherwise. 13878 13879\fun{void}{pari_unlink}{const char *s} deletes the file named $s$. Warn 13880if the operation fails. 13881 13882\fun{void}{pari_fread_chars}{void *b, size_t n, FILE *f} read $n$ chars from 13883stream $f$, storing the result in pre-allocated buffer $b$ (assumed to be 13884large enough). 13885 13886\fun{char*}{path_expand}{const char *s} perform tilde and environment expansion 13887on $s$. Returns a \kbd{malloc}'ed buffer. 13888 13889\fun{void}{strftime_expand}{const char *s, char *buf, long max} perform 13890time expansion on $s$, storing the result (at most \kbd{max} chars) in 13891buffer \kbd{buf}. Trivial wrapper around 13892\bprog 13893 time_t t = time(NULL); 13894 strftime(but, max, s, localtime(&t); 13895@eprog 13896 13897\fun{char*}{pari_get_homedir}{const char *user} expands \kbd{\til user} 13898constructs, returning the home directory of user \kbd{user}, or \kbd{NULL} if 13899it could not be determined (in particular if the operating system has no such 13900concept). The return value may point to static area and may be overwritten 13901by subsequent system calls: use immediately or \kbd{strdup} it. 13902 13903\fun{int}{pari_stdin_isatty}{void} returns $1$ if our standard input 13904\kbd{stdin} is attached to a terminal. Trivial wrapper around \kbd{isatty}. 13905 13906\subsec{pariFILE} 13907 13908PARI maintains a linked list of open files, to reclaim resources 13909(file descriptors) on error or interrupts. The corresponding data structure 13910is a \kbd{pariFILE}, which is a wrapper around a standard \kbd{FILE*}, 13911containing further the file name, its type (regular file, pipe, input or 13912output file, etc.). The following functions create and manipulate this 13913structure; they are integrated within PARI's diagnostics system, printing 13914messages if \kbd{DEBUGFILES} is high enough. 13915 13916\fun{pariFILE*}{pari_fopen}{const char *s, const char *mode} wrapper 13917around \kbd{fopen(s, mode)}, return \kbd{NULL} on failure. 13918 13919\fun{pariFILE*}{pari_fopen_or_fail}{const char *s, const char *mode} 13920simple wrapper around \kbd{fopen(s, mode)}; error on failure. 13921 13922\fun{pariFILE*}{pari_fopengz}{const char *s} opens the file whose name is 13923$s$, and associates a (read-only) \kbd{pariFILE} with it. If $s$ is a 13924compressed file (\kbd{.gz} suffix), it is uncompressed on the fly. 13925If $s$ cannot be opened, also try to open \kbd{$s$.gz}. Returns \kbd{NULL} 13926on failure. 13927 13928\fun{void}{pari_fclose}{pariFILE *f} closes 13929the underlying file descriptor and deletes the \kbd{pariFILE} struct. 13930 13931\fun{pariFILE*}{pari_safefopen}{const char *s, const char *mode} 13932creates a \emph{new} file $s$ (a priori for writing) with \kbd{600} 13933permissions. Error if the file already exists. To avoid symlink attacks, 13934a symbolic link exists, regardless of where it points to. 13935 13936\subsec{Temporary files} 13937 13938PARI has its own idea of the system temp directory derived from an 13939environment variable (\kbd{\$GPTMPDIR}, else \kbd{\$TMPDIR}), or the first 13940writable directory among \kbd{/tmp}, \kbd{/var/tmp} and \kbd{.}. 13941 13942\fun{char*}{pari_unique_dir}{const char *s} creates a ``unique directory'' 13943and return its name built from the string $s$, the user id and process pid 13944(on Unix systems). This directory is itself located in the temp 13945directory mentioned above. The name returned is \tet{malloc}'ed. 13946 13947\fun{char*}{pari_unique_filename}{const char *s} creates a \emph{new} empty 13948file in the temp directory, whose name contains the id-string $s$ (truncated 13949to its first $8$ chars), followed by a system-dependent suffix (incorporating 13950the ids of both the user and the running process, for instance). The function 13951returns the tempfile name and creates an empty file with that name. The name 13952returned is \tet{malloc}'ed. 13953 13954\fun{char*}{pari_unique_filename_suffix}{const char *s, const char *suf} 13955analogous to above \tet{pari_unique_filename}, creating a (previously 13956nonexistent) tempfile whose name ends with suffix \kbd{suf}. 13957 13958\section{Errors}\label{se:errors} 13959 13960This section documents the various error classes, and the corresponding 13961arguments to \tet{pari_err}. The general syntax is 13962 13963\fun{void}{pari_err}{numerr,...} 13964 13965\noindent In the sequel, we mostly use sequences of arguments of the form 13966\bprog 13967 const char *s 13968 const char *fmt, ... 13969@eprog\noindent where \kbd{fmt} is a PARI 13970format, producing a string $s$ from the remaining arguments. Since 13971providing the correct arguments to \tet{pari_err} is quite error-prone, we 13972also provide specialized routines \kbd{pari\_err\_\var{ERRORCLASS}(\dots)} 13973instead of \kbd{pari\_err(e\_\var{ERRORCLASS}, \dots)} so that the C compiler 13974can check their arguments. 13975 13976\noindent We now inspect the list of valid keywords (error classes) for 13977\kbd{numerr}, and the corresponding required arguments. 13978 13979\subsec{Internal errors, ``system'' errors} 13980 13981\subsubsec{e\_ARCH} A requested feature $s$ is not available on this 13982architecture or operating system. 13983\bprog 13984 pari_err(e_ARCH) 13985@eprog\noindent prints the error message: \kbd{sorry, '$s$' not available on 13986this system}. 13987 13988\subsubsec{e\_BUG} A bug in the PARI library, in function $s$. 13989\bprog 13990 pari_err(e_BUG, const char *s) 13991 pari_err_BUG(const char *s) 13992@eprog\noindent prints the error message: \kbd{Bug in $s$, please report}. 13993 13994\subsubsec{e\_FILE} Error while trying to open a file. 13995\bprog 13996 pari_err(e_FILE, const char *what, const char *name) 13997 pari_err_FILE(const char *what, const char *name) 13998@eprog\noindent prints the error message: \kbd{error opening 13999\emph{what}: `\emph{name}'}. 14000 14001\subsubsec{e\_FILEDESC} Error while handling a file descriptor. 14002\bprog 14003 pari_err(e_FILEDESC, const char *where, long n) 14004 pari_err_FILEDESC(const char *where, long n) 14005@eprog\noindent prints the error message: \kbd{invalid file descriptor in 14006\emph{where}: `\emph{name}'}. 14007 14008\subsubsec{e\_IMPL} A requested feature $s$ is not implemented. 14009\bprog 14010 pari_err(e_IMPL, const char *s) 14011 pari_err_IMPL(const char *s) 14012@eprog\noindent prints the error message: \kbd{sorry, $s$ is not yet 14013implemented}. 14014 14015\subsubsec{e\_PACKAGE} Missing optional package $s$. 14016\bprog 14017 pari_err(e_PACKAGE, const char *s) 14018 pari_err_PACKAGE(const char *s) 14019@eprog\noindent prints the error message: \kbd{package $s$ is required, 14020please install it} 14021 14022\subsec{Syntax errors, type errors} 14023 14024\subsubsec{e\_DIM} arguments submitted to function $s$ have inconsistent 14025dimensions. E.g., when solving a linear system, or trying to compute the 14026determinant of a nonsquare matrix. 14027\bprog 14028 pari_err(e_DIM, const char *s) 14029 pari_err_DIM(const char *s) 14030@eprog\noindent prints the error message: \kbd{inconsistent dimensions in $s$}. 14031 14032\subsubsec{e\_FLAG} A flag argument is out of bounds in function $s$. 14033\bprog 14034 pari_err(e_FLAG, const char *s) 14035 pari_err_FLAG(const char *s) 14036@eprog\noindent prints the error message: \kbd{invalid flag in $s$}. 14037 14038\subsubsec{e\_NOTFUNC} Generated by the PARI evaluator; tried to use a 14039\kbd{GEN} which is not a \typ{CLOSURE} in a function call syntax (as in 14040\kbd{f = 1; f(2);}). 14041\bprog 14042 pari_err(e_NOTFUNC, GEN fun) 14043@eprog\noindent prints the error message: \kbd{not a function in a function 14044call}. 14045 14046\subsubsec{e\_OP} Impossible operation between two objects than cannot be 14047typecast to a sensible common domain for deeper reasons than a type mismatch, 14048usually for arithmetic reasons. As in \kbd{O(2) + O(3)}: it is valid to add 14049two \typ{PADIC}s, provided the underlying prime is the same; so the addition 14050is not forbidden a priori for type reasons, it only becomes so when 14051inspecting the objects and trying to perform the operation. 14052\bprog 14053 pari_err(e_OP, const char *op, GEN x, GEN y) 14054 pari_err_OP(const char *op, GEN x, GEN y) 14055@eprog\noindent As \kbd{e\_TYPE2}, replacing \kbd{forbidden} by 14056\kbd{inconsistent}. 14057 14058\subsubsec{e\_PRIORITY} object $o$ in function $s$ contains 14059variables whose priority is incompatible with the expected operation. 14060E.g.~\kbd{Pol([x,1], 'y)}: this raises an error because it's not possible to 14061create a polynomial whose coefficients involve variables with higher priority 14062than the main variable. 14063\bprog 14064 pari_err(e_PRIORITY, const char *s, GEN o, const char *op, long v) 14065 pari_err_PRIORITY(const char *s, GEN o, const char *op, long v) 14066@eprog\noindent prints the error message: \kbd{incorrect priority 14067in $s$, variable $v_o$ \var{op} $v$}, were $v_o$ is \kbd{gvar(o)}. 14068 14069\subsubsec{e\_SYNTAX} Syntax error, generated by the PARI parser. 14070\bprog 14071 pari_err(e_SYNTAX, const char *msg, const char *e, const char *entry) 14072@eprog\noindent where \kbd{msg} is a complete error message, and \kbd{e} and 14073\kbd{entry} point into the \emph{same} character string, which is the input 14074that was incorrectly parsed: \kbd{e} points to the character where the parser 14075failed, and $\kbd{entry}\leq \kbd{e}$ points somewhat before. 14076 14077\noindent Prints the error message: \kbd{msg}, followed by a colon, then 14078a part of the input character string (in general \kbd{entry} itself, but an 14079initial segment may be truncated if $\kbd{e}-\kbd{entry}$ is large); a caret 14080points at \kbd{e}, indicating where the error took place. 14081 14082\subsubsec{e\_TYPE} An argument $x$ of function $s$ had an unexpected type. 14083(As in \kbd{factor("blah")}.) 14084\bprog 14085 pari_err(e_TYPE, const char *s, GEN x) 14086 pari_err_TYPE(const char *s, GEN x) 14087@eprog\noindent prints the error message: \kbd{incorrect type in $s$ 14088(\typ{$x$})}, where \typ{$x$} is the type of $x$. 14089 14090\subsubsec{e\_TYPE2} Forbidden operation between two objects than cannot be 14091typecast to a sensible common domain, because their types do not match up. 14092(As in \kbd{Mod(1,2) + Pi}.) 14093\bprog 14094 pari_err(e_TYPE2, const char *op, GEN x, GEN y) 14095 pari_err_TYPE2(const char *op, GEN x, GEN y) 14096@eprog\noindent prints the error message: \kbd{forbidden} $s$ 14097\typ{$x$} \var{op} \typ{$y$}, where \typ{$z$} denotes the type of $z$. 14098Here, $s$ denotes the spelled out name of the operator 14099$\var{op}\in\{\kbd{+}, \kbd{*}, \kbd{/}, \kbd{\%}, \kbd{=}\}$, e.g. 14100\emph{addition} for \kbd{"+"} or \emph{assignment} for \kbd{"="}. If \var{op} 14101is not in the above operator, list, it is taken to be the already spelled out 14102name of a function, e.g. \kbd{"gcd"}, and the error message becomes 14103\kbd{forbidden} \var{op} \typ{$x$}, \typ{$y$}. 14104 14105\subsubsec{e\_VAR} polynomials $x$ and $y$ submitted to function $s$ have 14106inconsistent variables. E.g., considering the algebraic number 14107\kbd{Mod(t,t\pow2+1)} in \kbd{nfinit(x\pow2+1)}. 14108\bprog 14109 pari_err(e_VAR, const char *s, GEN x, GEN y) 14110 pari_err_VAR(const char *s, GEN x, GEN y) 14111@eprog\noindent prints the error message: \kbd{inconsistent variables in $s$ 14112$X$ != $Y$}, where $X$ and $Y$ are the names of the variables of $x$ and $y$, 14113respectively. 14114 14115\subsec{Overflows} 14116 14117\subsubsec{e\_COMPONENT} Trying to access an inexistent component of a 14118vector/matrix/list: the index is less than $1$ or greater 14119than the allowed length. 14120\bprog 14121 pari_err(e_COMPONENT, const char *f, const char *op, GEN lim, GEN x) 14122 pari_err_COMPONENT(const char *f, const char *op, GEN lim, GEN x) 14123@eprog\noindent prints the error message: \kbd{nonexistent component in $f$: 14124index \var{op} \var{lim}}. Special case: if $f$ is the empty string (no 14125meaningful public function name can be used), we ignore it and print the 14126message: \kbd{nonexistent component: index \var{op} \var{lim}}. 14127 14128\subsubsec{e\_DOMAIN} An argument $x$ is not in the function's domain (as in 14129\kbd{moebius(0)} or \kbd{zeta(1)}). 14130\bprog 14131 pari_err(e_DOMAIN, char *f, char *v, char *op, GEN lim, GEN x) 14132 pari_err_DOMAIN(char *f, char *v, char *op, GEN lim, GEN x) 14133@eprog\noindent prints the error message: \kbd{domain error in $f$: $v$ 14134\var{op} \var{lim}}. Special case: if \var{op} is the empty string, we ignore 14135\var{lim} and print the error message: \kbd{domain error in $f$: $v$ out of 14136range}. 14137 14138\subsubsec{e\_MAXPRIME} A function using the precomputed list of prime numbers 14139ran out of primes. 14140\bprog 14141 pari_err(e_MAXPRIME, ulong c) 14142 pari_err_MAXPRIME(ulong c) 14143@eprog\noindent prints the error message: \kbd{not enough precomputed primes, 14144need primelimit \til $c$} if $c$ is nonzero. And simply \kbd{not enough 14145precomputed primes} otherwise. 14146 14147\subsubsec{e\_MEM} A call to \tet{pari_malloc} or \tet{pari_realloc} failed. 14148\bprog 14149 pari_err(e_MEM) 14150@eprog\noindent prints the error message: \kbd{not enough memory}. 14151 14152\subsubsec{e\_OVERFLOW} An object in function $s$ becomes too large to be 14153represented within PARI's hardcoded limits. (As in \kbd{2\pow2\pow2\pow10} 14154or \kbd{exp(1e100)}, which overflow in \kbd{lg} and \kbd{expo}.) 14155\bprog 14156 pari_err(e_OVERFLOW, const char *s) 14157 pari_err_OVERFLOW(const char *s) 14158@eprog\noindent prints the error message: \kbd{overflow in $s$}. 14159 14160\subsubsec{e\_PREC} Function $s$ fails because input accuracy is too low. 14161(As in \kbd{floor(1e100)} at default accuracy.) 14162\bprog 14163 pari_err(e_PREC, const char *s) 14164 pari_err_PREC(const char *s) 14165@eprog\noindent prints the error message: \kbd{precision too low in $s$}. 14166 14167\subsubsec{e\_STACK} The PARI stack overflows. 14168\bprog 14169 pari_err(e_STACK) 14170@eprog\noindent prints the error message: \kbd{the PARI stack overflows !} 14171as well as some statistics concerning stack usage. 14172 14173\subsec{Errors triggered intentionally} 14174 14175\subsubsec{e\_ALARM} A timeout, generated by the \tet{alarm} function. 14176\bprog 14177 pari_err(e_ALARM, const char *fmt, ...) 14178@eprog\noindent prints the error message: $s$. 14179 14180\subsubsec{e\_USER} A user error, as triggered by \tet{error}($g_1,\dots,g_n)$ 14181in GP. 14182\bprog 14183 pari_err(e_USER, GEN g) 14184@eprog\noindent prints the error message: \kbd{user error:}, then the 14185entries of the vector $g$. 14186 14187\subsec{Mathematical errors} 14188 14189\subsubsec{e\_CONSTPOL} An argument of function $s$ is a constant polynomial, 14190which does not make sense. (As in \kbd{galoisinit(Pol(1))}.) 14191\bprog 14192 pari_err(e_CONSTPOL, const char *s) 14193 pari_err_CONSTPOL(const char *s) 14194@eprog\noindent prints the error message: \kbd{constant polynomial in $s$}. 14195 14196\subsubsec{e\_COPRIME} Function $s$ expected two coprime arguments, and did 14197receive $x$, $y$ which were not. 14198\bprog 14199 pari_err(e_COPRIME, const char *s, GEN x, GEN y) 14200 pari_err_COPRIME(const char *s, GEN x, GEN y) 14201@eprog\noindent prints the error message: \kbd{elements not coprime in $s$: 14202$x, y$}. 14203 14204\subsubsec{e\_INV} Tried to invert a noninvertible object $x$. 14205\bprog 14206 pari_err(e_INV, const char *s, GEN x) 14207 pari_err_INV(const char *s, GEN x) 14208@eprog\noindent prints the error message: \kbd{impossible inverse in $s$: $x$}. 14209If $x = \kbd{Mod}(a,b)$ is a \typ{INTMOD} and $a$ is not $0$ mod $b$, this 14210allows to factor the modulus, as \kbd{gcd}$(a,b)$ is a nontrivial divisor of 14211$b$. 14212 14213\subsubsec{e\_IRREDPOL} Function $s$ expected an irreducible polynomial, 14214and did not receive one. (As in \kbd{nfinit(x\pow2-1)}.) 14215\bprog 14216 pari_err(e_IRREDPOL, const char *s, GEN x) 14217 pari_err_IRREDPOL(const char *s, GEN x) 14218@eprog\noindent prints the error message: \kbd{not an irreducible polynomial 14219in $s$: $x$}. 14220 14221\subsubsec{e\_MISC} Generic uncategorized error. 14222\bprog 14223 pari_err(e_MISC, const char *fmt, ...) 14224@eprog\noindent prints the error message: $s$. 14225 14226\subsubsec{e\_MODULUS} moduli $x$ and $y$ submitted to function $s$ are 14227inconsistent. E.g., considering the algebraic number 14228\kbd{Mod(t,t\pow2+1)} in \kbd{nfinit(t\pow3-2)}. 14229\bprog 14230 pari_err(e_MODULUS, const char *s, GEN x, GEN y) 14231 pari_err_MODULUS(const char *s, GEN x, GEN y) 14232@eprog\noindent prints the error message: \kbd{inconsistent moduli in $s$}, 14233then the moduli. 14234 14235\subsubsec{e\_PRIME} Function $s$ expected a prime number, and did receive $p$, 14236which was not. (As in \kbd{idealprimedec(nf, 4)}.) 14237\bprog 14238 pari_err(e_PRIME, const char *s, GEN x) 14239 pari_err_PRIME(const char *s, GEN x) 14240@eprog\noindent prints the error message: \kbd{not a prime in $s$: $x$}. 14241 14242\subsubsec{e\_ROOTS0} An argument of function $s$ is a zero polynomial, and 14243we need to consider its roots. (As in \kbd{polroots(0)}.) 14244\bprog 14245 pari_err(e_ROOTS0, const char *s) 14246 pari_err_ROOTS0(const char *s) 14247@eprog\noindent prints the error message: \kbd{zero polynomial in $s$}. 14248 14249\subsubsec{e\_SQRTN} Tried to compute an $n$-th root of $x$, which does not 14250exist, in function $s$. 14251(As in \kbd{sqrt(Mod(-1,3))}.) 14252\bprog 14253 pari_err(e_SQRTN, GEN x) 14254 pari_err_SQRTN(GEN x) 14255@eprog\noindent prints the error message: \kbd{not an n-th power residue in 14256$s$: $x$}. 14257 14258\subsec{Miscellaneous functions} 14259 14260\fun{long}{name_numerr}{const char *s} return the error number corresponding to 14261an error name. E.g. \kbd{name\_numerr("e\_DIM")} returns \kbd{e\_DIM}. 14262 14263\fun{const char*}{numerr_name}{long errnum} returns the error name 14264corresponding to an error number. E.g. \kbd{name\_numerr(e\_DIM)} returns 14265\kbd{"e\_DIM"}. 14266 14267\fun{char*}{pari_err2str}{GEN err} returns the error message that would be 14268printed on \typ{ERROR} \kbd{err}. The name is allocated on the PARI stack and 14269must not be freed. 14270 14271\section{Hashtables} 14272A \tet{hashtable}, or associative array, is a set of pairs $(k,v)$ of keys 14273and values. PARI implements general extensible hashtables for fast data 14274retrieval: when creating a table, we may either choose to use the PARI stack, 14275or \kbd{malloc} so as to be stack-independent. A hashtable is implemented as 14276a table of linked lists, each list containing all entries sharing the same 14277hash value. The table length is a prime number, which roughly doubles as the 14278table overflows by gaining new entries; both the current number of entries 14279and the threshold before the table grows are stored in the table. Finally the 14280table remembers the functions used to hash the entries's keys and to test for 14281equality two entries hashed to the same value. 14282 14283An entry, or \tet{hashentry}, contains 14284 14285\item a key/value pair $(k,v)$, both of type \kbd{void*} for maximal 14286flexibility, 14287 14288\item the hash value of the key, for the table hash function. This hash is 14289mapped to a table index (by reduction modulo the table length), but it 14290contains more information, and is used to bypass costly general equality 14291tests if possible, 14292 14293\item a link pointer to the next entry sharing the same table cell. 14294 14295\bprog 14296typedef struct { 14297 void *key, *val; 14298 ulong hash; /* hash(key) */ 14299 struct hashentry *next; 14300} hashentry; 14301 14302typedef struct { 14303 ulong len; /* table length */ 14304 hashentry **table; /* the table */ 14305 ulong nb, maxnb; /* number of entries stored and max nb before enlarging */ 14306 ulong pindex; /* prime index */ 14307 ulong (*hash) (void *k); /* hash function */ 14308 int (*eq) (void *k1, void *k2); /* equality test */ 14309 int use_stack; /* use the PARI stack, resp. malloc */ 14310} hashtable; 14311@eprog\noindent 14312 14313\fun{hashtable*}{hash_create}{size, hash, eq, use_stack} 14314\vskip -0.5em % switch to K&R style to avoid atrocious line break 14315\bprog 14316 ulong size; 14317 ulong (*hash)(void*); 14318 int (*eq)(void*,void*); 14319 int use_stack; 14320@eprog\noindent 14321creates a hashtable with enough room to contain 14322\kbd{size} entries. The functions \kbd{hash} and \kbd{eq} compute the hash 14323value of keys and test keys for equality, respectively. If \kbd{use\_stack} 14324is non zero, the resulting table will use the PARI stack; otherwise, we use 14325\kbd{malloc}. 14326 14327\fun{hashtable*}{hash_create_ulong}{ulong size, long stack} special case 14328when the keys are \kbd{ulongs} with ordinary equality test. 14329 14330\fun{hashtable*}{hash_create_str}{ulong size, long stack} special case 14331when the keys are character strings with string equality test (and 14332\tet{hash_str} hash function). 14333 14334\fun{void}{hash_init}{hashtable *h, ulong size, ulong (*hash)(void*), 14335int (*eq)(void*,void*), use_stack} 14336Initialize \kbd{h} for an hashtable with enough room to contain 14337\kbd{size} entries of type \kbd{void*}. The functions \kbd{eq} test keys for 14338equality. If \kbd{use\_stack} is non zero, the resulting table will use the 14339PARI stack; otherwise, we use \kbd{malloc}. 14340 14341\fun{void}{hash_init_GEN}{hashtable *h, ulong size, int (*eq)(GEN,GEN), use_stack} 14342Initialize \kbd{h} for an hashtable with enough room to contain 14343\kbd{size} entries of type \kbd{GEN}. The functions \kbd{eq} test keys for 14344equality. If \kbd{use\_stack} is non zero, the resulting table will use the 14345PARI stack; otherwise, we use \kbd{malloc}. The hash used is \kbd{hash\_GEN}. 14346 14347\fun{void}{hash_init_ulong}{hashtable *h, ulong size, use_stack} 14348Initialize \kbd{h} for an hashtable with enough room to contain 14349\kbd{size} entries of type \kbd{ulong}. 14350If \kbd{use\_stack} is non zero, the resulting table will use the 14351PARI stack; otherwise, we use \kbd{malloc}. 14352 14353\fun{void}{hash_insert}{hashtable *h, void *k, void *v} inserts $(k,v)$ 14354in hashtable $h$. No copy is made: $k$ and $v$ themselves are stored. The 14355implementation does not prevent one to insert two entries with equal 14356keys $k$, but which of the two is affected by later commands is undefined. 14357 14358\fun{void}{hash_insert2}{hashtable *h, void *k, void *v, ulong hash} 14359as \kbd{hash\_insert}, assuming \kbd{h->hash(k)} is \kbd{hash}. 14360 14361\fun{void}{hash_insert_long}{hashtable *h, void *k, long v} as 14362\kbd{hash\_insert} but \kbd{v} is a \kbd{long}. 14363 14364\fun{hashentry*}{hash_search}{hashtable *h, void *k} look for an entry 14365with key $k$ in $h$. Return it if it one exists, and \kbd{NULL} if not. 14366 14367\fun{hashentry*}{hash_search2}{hashtable *h, void *k, ulong hash} as 14368\kbd{hash\_search} assuming \kbd{h->hash(k)} is \kbd{hash}. 14369 14370\fun{GEN}{hash_haskey_GEN}{hashtable *h, void *k} 14371returns the associate value if the key $k$ belongs to the hash, 14372otherwise returns \kbd{NULL}. 14373 14374\fun{int}{hash_haskey_long}{hashtable *h, void *k, long *v} 14375returns $1$ if the key $k$ belongs to the hash and set $v$ to its value, 14376otherwise returns 0. 14377 14378\fun{hashentry *}{hash_select}{hashtable *h, void *k, void *E, int (*select)(void *, hashentry *)} variant of \tet{hash_search}, useful when entries 14379with identical keys are inserted: among the entries attached to 14380key $k$, return one satisfying the selection criterion (such that 14381\kbd{select(E,e)} is nonzero), or \kbd{NULL} if none exist. 14382 14383\fun{hashentry*}{hash_remove}{hashtable *h, void *k} deletes an entry $(k,v)$ 14384with key $k$ from $h$ and return it. (Return \kbd{NULL} if none was found.) 14385Only the linking structures are freed, memory attached to $k$ and $v$ 14386is not reclaimed. 14387 14388\fun{hashentry*}{hash_remove_select}{hashtable *h, void *k, void *E, int(*select)(void*, hashentry *)} 14389a variant of \tet{hash_remove}, useful when entries with identical keys are 14390inserted: among the entries attached to key $k$, return one satisfying the 14391selection criterion (such that \kbd{select(E,e)} is nonzero) and delete it, 14392or \kbd{NULL} if none exist. Only the linking structures are freed, memory 14393attached to $k$ and $v$ is not reclaimed. 14394 14395\fun{GEN}{hash_keys}{hashtable *h} return in a \typ{VECSMALL} the keys 14396stored in hashtable $h$. 14397 14398\fun{GEN}{hash_values}{hashtable *h} return in a \typ{VECSMALL} 14399the values stored in hashtable $h$. 14400 14401\fun{void}{hash_destroy}{hashtable *h} deletes the hashtable, by removing all 14402entries. 14403 14404\fun{void}{hash_dbg}{hashtable *h} print statistics for hashtable $h$, allows 14405to evaluate the attached hash function performance on actual data. 14406 14407Some interesting hash functions are available: 14408 14409\fun{ulong}{hash_str}{const char *s} 14410 14411\fun{ulong}{hash_str_len}{const char *s, long len} hash the prefix string 14412containing the first \kbd{len} characters (assume $\kbd{strlen}(s) \geq 14413\kbd{len}$). 14414 14415\fun{ulong}{hash_GEN}{GEN x} generic hash function. 14416 14417\fun{ulong}{hash_zv}{GEN x} hash a \typ{VECSMALL}. 14418 14419\section{Dynamic arrays} 14420 14421A \teb{dynamic array} is a generic way to manage stacks of data that need 14422to grow dynamically. It allocates memory using \kbd{pari\_malloc}, and is 14423independent of the PARI stack; it even works before the \kbd{pari\_init} call. 14424 14425\subsec{Initialization} 14426 14427To create a stack of objects of type \kbd{foo}, we proceed as follows: 14428\bprog 14429foo *t_foo; 14430pari_stack s_foo; 14431pari_stack_init(&s_foo, sizeof(*t_foo), (void**)&t_foo); 14432@eprog\noindent Think of \kbd{s\_foo} as the controlling interface, and 14433\kbd{t\_foo} as the (dynamic) array tied to it. The value of \kbd{t\_foo} 14434may be changed as you add more elements. 14435 14436\subsec{Adding elements} 14437The following function pushes an element on the stack. 14438\bprog 14439/* access globals t_foo and s_foo */ 14440void push_foo(foo x) 14441{ 14442 long n = pari_stack_new(&s_foo); 14443 t_foo[n] = x; 14444} 14445@eprog 14446 14447\subsec{Accessing elements} 14448 14449Elements are accessed naturally through the \kbd{t\_foo} pointer. 14450For example this function swaps two elements: 14451\bprog 14452void swapfoo(long a, long b) 14453{ 14454 foo x; 14455 if (a > s_foo.n || b > s_foo.n) pari_err_BUG("swapfoo"); 14456 x = t_foo[a]; 14457 t_foo[a] = t_foo[b]; 14458 t_foo[b] = x; 14459} 14460@eprog 14461 14462\subsec{Stack of stacks} 14463Changing the address of \kbd{t\_foo} is not supported in general. 14464In particular \kbd{realloc()}'ed array of stacks and stack of stacks are not 14465supported. 14466 14467\subsec{Public interface} 14468Let \kbd{s} be a \kbd{pari\_stack} and \kbd{data} the data linked to it. The 14469following public fields are defined: 14470 14471\item \kbd{s.alloc} is the number of elements allocated for \kbd{data}. 14472 14473\item \kbd{s.n} is the number of elements in the stack and \kbd{data[s.n-1]} is 14474the topmost element of the stack. \kbd{s.n} can be changed as long as 14475$0\leq\kbd{s.n}\leq\kbd{s.alloc}$ holds. 14476 14477\fun{void}{pari_stack_init}{pari_stack *s, size_t size, void **data} links 14478\kbd{*s} to the data pointer \kbd{*data}, where \kbd{size} is the size of 14479data element. The pointer \kbd{*data} is set to \kbd{NULL}, \kbd{s->n} and 14480\kbd{s->alloc} are set to $0$: the array is empty. 14481 14482\fun{void}{pari_stack_alloc}{pari_stack *s, long nb} makes room for \kbd{nb} 14483more elements, i.e.~makes sure that $\kbd{s.alloc}\geq\kbd{s.n} + \kbd{nb}$, 14484possibly reallocating \kbd{data}. 14485 14486\fun{long}{pari_stack_new}{pari_stack *s} increases \kbd{s.n} by one unit, 14487possibly reallocating \kbd{data}, and returns $\kbd{s.n}-1$. 14488 14489\misctitle{Caveat} The following construction is incorrect because 14490\kbd{stack\_new} can change the value of \kbd{t\_foo}: 14491\bprog 14492t_foo[ pari_stack_new(&s_foo) ] = x; 14493@eprog 14494 14495\fun{void}{pari_stack_delete}{pari_stack *s} frees \kbd{data} and resets the 14496stack to the state immediately following \kbd{stack\_init} (\kbd{s->n} and 14497\kbd{s->alloc} are set to $0$). 14498 14499\fun{void *}{pari_stack_pushp}{pari_stack *s, void *u} This function assumes 14500that \kbd{*data} is of pointer type. Pushes the element \kbd{u} on the stack 14501\kbd{s}. 14502 14503\fun{void **}{pari_stack_base}{pari_stack *s} returns the address of \kbd{data}, 14504typecast to a \kbd{void **}. 14505 14506\section{Vectors and Matrices} 14507 14508\subsec{Access and extract} 14509See~\secref{se:clean} and~\secref{se:unclean} for various useful constructors. 14510Coefficients are accessed and set using \tet{gel}, \tet{gcoeff}, 14511see~\secref{se:accessors}. There are many internal functions to extract or 14512manipulate subvectors or submatrices but, like the accessors above, none of 14513them are suitable for \tet{gerepileupto}. Worse, there are no type 14514verification, nor bound checking, so use at your own risk. 14515 14516\fun{GEN}{shallowcopy}{GEN x} returns a \kbd{GEN} whose components are the 14517components of $x$ (no copy is made). The result may now be used to compute in 14518place without destroying $x$. This is essentially equivalent to 14519\bprog 14520 GEN y = cgetg(lg(x), typ(x)); 14521 for (i = 1; i < lg(x); i++) y[i] = x[i]; 14522 return y; 14523@eprog\noindent 14524except that \typ{MAT} is treated specially since shallow copies of all columns 14525are made. The function also works for nonrecursive types, but is useless 14526in that case since it makes a deep copy. If $x$ is known to be a \typ{MAT}, you 14527may call \tet{RgM_shallowcopy} directly; if $x$ is known not to be a \typ{MAT}, 14528you may call \tet{leafcopy} directly. 14529 14530\fun{GEN}{RgM_shallowcopy}{GEN x} returns \kbd{shallowcopy(x)}, where $x$ 14531is a \typ{MAT}. 14532 14533\fun{GEN}{shallowtrans}{GEN x} returns the transpose of $x$, \emph{without} 14534copying its components, i.~e.,~it returns a \kbd{GEN} whose components are 14535(physically) the components of $x$. This is the internal function underlying 14536\tet{gtrans}. 14537 14538\fun{GEN}{shallowconcat}{GEN x, GEN y} concatenate $x$ and $y$, \emph{without} 14539copying components, i.~e.,~it returns a \kbd{GEN} whose components are 14540(physically) the components of $x$ and $y$. 14541 14542\fun{GEN}{shallowconcat1}{GEN x} 14543$x$ must be \typ{VEC} or \typ{LIST}, concatenate 14544its elements from left to right. Shallow version of \kbd{gconcat1}. 14545 14546\fun{GEN}{shallowmatconcat}{GEN v} shallow version of \kbd{matconcat}. 14547 14548\fun{GEN}{shallowextract}{GEN x, GEN y} extract components 14549of the vector or matrix $x$ according to the selection parameter $y$. 14550This is the shallow analog of \kbd{extract0(x, y, NULL)}, see \tet{vecextract}. 14551\kbdsidx{extract0} 14552 14553\fun{GEN}{shallowmatextract}{GEN M, GEN l1, GEN l2} extract components of the 14554matrix $M$ according to the \typ{VECSMALL} $l1$ (list of lines indices) and 14555$l2$ (list of columns indices). 14556This is the shallow analog of \kbd{extract0(x, l1, l2)}, see \tet{vecextract}. 14557\kbdsidx{extract0} 14558 14559\fun{GEN}{RgM_minor}{GEN A, long i, long j} given a square \typ{MAT} A, 14560return the matrix with $i$-th row and $j$-th column removed. 14561 14562\fun{GEN}{vconcat}{GEN A, GEN B} concatenate vertically the two \typ{MAT} $A$ 14563and $B$ of compatible dimensions. A \kbd{NULL} pointer is accepted for an 14564empty matrix. See \tet{shallowconcat}. 14565 14566\fun{GEN}{matslice}{GEN A, long a, long b, long c, long d} 14567returns the submatrix $A[a..b,c..d]$. Assume $a \leq b$ and $c \leq d$. 14568 14569\fun{GEN}{row}{GEN A, long i} return $A[i,]$, the $i$-th row of the \typ{MAT} 14570$A$. 14571 14572\fun{GEN}{row_i}{GEN A, long i, long j1, long j2} return part of the $i$-th 14573row of \typ{MAT}~$A$: $A[i,j_1]$, $A[i,j_1+1]\dots,A[i,j_2]$. Assume $j_1 14574\leq j_2$. 14575 14576\fun{GEN}{rowcopy}{GEN A, long i} return the row $A[i,]$ of 14577the~\typ{MAT}~$A$. This function is memory clean and suitable for 14578\kbd{gerepileupto}. See \kbd{row} for the shallow equivalent. 14579 14580\fun{GEN}{rowslice}{GEN A, long i1, long i2} return the \typ{MAT} 14581formed by the $i_1$-th through $i_2$-th rows of \typ{MAT} $A$. Assume $i_1 14582\leq i_2$. 14583 14584\fun{GEN}{rowsplice}{GEN A, long i} return the \typ{MAT} formed from the 14585coefficients of \typ{MAT} $A$ with $j$-th row removed. 14586 14587\fun{GEN}{rowpermute}{GEN A, GEN p}, $p$ being a \typ{VECSMALL} 14588representing a list $[p_1,\dots,p_n]$ of rows of \typ{MAT} $A$, returns the 14589matrix whose rows are $A[p_1,],\dots, A[p_n,]$. 14590 14591\fun{GEN}{rowslicepermute}{GEN A, GEN p, long x1, long x2}, short for 14592\bprog 14593 rowslice(rowpermute(A,p), x1, x2) 14594@eprog\noindent 14595(more efficient). 14596 14597\fun{GEN}{vecslice}{GEN A, long j1, long j2}, return $A[j_1], \dots, 14598A[j_2]$. If $A$ is a \typ{MAT}, these correspond to \emph{columns} of $A$. 14599The object returned has the same type as $A$ (\typ{VEC}, \typ{COL} or 14600\typ{MAT}). Assume $j_1 \leq j_2$. 14601 14602\fun{GEN}{vecsplice}{GEN A, long j} return $A$ with $j$-th entry removed 14603(\typ{VEC}, \typ{COL}) or $j$-th column removed (\typ{MAT}). 14604 14605\fun{GEN}{vecreverse}{GEN A}. Returns a \kbd{GEN} which has the same 14606type as $A$ (\typ{VEC}, \typ{COL} or \typ{MAT}), and whose components 14607are the $A[n],\dots,A[1]$. If $A$ is a \typ{MAT}, these are the 14608\emph{columns} of $A$. 14609 14610\fun{void}{vecreverse_inplace}{GEN A} as \kbd{vecreverse}, but reverse 14611$A$ in place. 14612 14613\fun{GEN}{vecpermute}{GEN A, GEN p} $p$ is a \typ{VECSMALL} representing 14614a list $[p_1,\dots,p_n]$ of indices. Returns a \kbd{GEN} which has the same 14615type as $A$ (\typ{VEC}, \typ{COL} or \typ{MAT}), and whose components 14616are $A[p_1],\dots,A[p_n]$. If $A$ is a \typ{MAT}, these are the 14617\emph{columns} of $A$. 14618 14619\fun{GEN}{vecsmallpermute}{GEN A, GEN p} as \kbd{vecpermute} when \kbd{A} is a 14620\typ{VECSMALL}. 14621 14622\fun{GEN}{vecslicepermute}{GEN A, GEN p, long y1, long y2} short for 14623\bprog 14624 vecslice(vecpermute(A,p), y1, y2) 14625@eprog\noindent 14626(more efficient). 14627 14628\subsec{Componentwise operations} 14629 14630The following convenience routines automate trivial loops of the form 14631\bprog 14632 for (i = 1; i < lg(a); i++) gel(v,i) = f(gel(a,i), gel(b,i)) 14633@eprog\noindent 14634for suitable $f$: 14635 14636\fun{GEN}{vecinv}{GEN a}. Given a vector $a$, 14637returns the vector whose $i$-th component is \kbd{ginv}$(a[i])$. 14638 14639\fun{GEN}{vecmul}{GEN a, GEN b}. Given $a$ and $b$ two vectors of the same 14640length, returns the vector whose $i$-th component is \kbd{gmul}$(a[i], b[i])$. 14641 14642\fun{GEN}{vecdiv}{GEN a, GEN b}. Given $a$ and $b$ two vectors of the same 14643length, returns the vector whose $i$-th component is \kbd{gdiv}$(a[i], b[i])$. 14644 14645\fun{GEN}{vecpow}{GEN a, GEN n}. Given $n$ a \typ{INT}, returns 14646the vector whose $i$-th component is $a[i]^n$. 14647 14648\fun{GEN}{vecmodii}{GEN a, GEN b}. Assuming $a$ and $b$ are two \kbd{ZV} 14649of the same length, returns the vector whose $i$-th component 14650is \kbd{modii}$(a[i], b[i])$. 14651 14652\fun{GEN}{vecmoduu}{GEN a, GEN b}. Assuming $a$ and $b$ are two \typ{VECSMALL} 14653of the same length, returns the vector whose $i$-th component 14654is $a[i]~\kbd{\%}~b[i]$. 14655 14656Note that \kbd{vecadd} or \kbd{vecsub} do not exist since \kbd{gadd} 14657and \kbd{gsub} have the expected behavior. On the other hand, 14658\kbd{ginv} does not accept vector types, hence \kbd{vecinv}. 14659 14660\subsec{Low-level vectors and columns functions} 14661 14662These functions handle \typ{VEC} as an abstract container type of 14663\kbd{GEN}s. No specific meaning is attached to the content. They accept both 14664\typ{VEC} and \typ{COL} as input, but \kbd{col} functions always return 14665\typ{COL} and \kbd{vec} functions always return \typ{VEC}. 14666 14667\misctitle{Note} All the functions below are shallow. 14668 14669\fun{GEN}{const_col}{long n, GEN x} returns a \typ{COL} of \kbd{n} components 14670equal to \kbd{x}. 14671 14672\fun{GEN}{const_vec}{long n, GEN x} returns a \typ{VEC} of \kbd{n} components 14673equal to \kbd{x}. 14674 14675\fun{int}{vec_isconst}{GEN v} Returns 1 if all the components of \kbd{v} are 14676equal, else returns 0. 14677 14678\fun{void}{vec_setconst}{GEN v, GEN x} $v$ a pre-existing vector. Set all its 14679components to $x$. 14680 14681\fun{int}{vec_is1to1}{GEN v} Returns 1 if the components of \kbd{v} are 14682pair-wise distinct, i.e. if $i\mapsto v[i]$ is a 1-to-1 mapping, else returns 146830. 14684 14685\fun{GEN}{vec_append}{GEN V, GEN s} append \kbd{s} to the vector \kbd{V}. 14686 14687\fun{GEN}{vec_prepend}{GEN V, GEN s} prepend \kbd{s} to the vector \kbd{V}. 14688 14689\fun{GEN}{vec_shorten}{GEN v, long n} shortens the vector \kbd{v} to \kbd{n} 14690components. 14691 14692\fun{GEN}{vec_lengthen}{GEN v, long n} lengthens the vector \kbd{v} 14693to \kbd{n} components. The extra components are not initialized. 14694 14695\fun{GEN}{vec_insert}{GEN v, long n, GEN x} inserts $x$ at position $n$ in the vector 14696$v$. 14697 14698\fun{GEN}{vec_equiv}{GEN O} given a vector of objects $O$, return a vector 14699with $n$ components where $n$ is the number of distinct objects in $O$. The 14700$i$-th component is a \typ{VECSMALL} containing the indices of the elements 14701in $O$ having the same value. Applied to the image of a function evaluated on 14702some finite set, it computes the fibers of the function. 14703 14704\fun{GEN}{vec_reduce}{GEN O, GEN *pE} given a vector of objects $O$, 14705return the vector $v$ (of the same type as $O$) of \emph{distinct} elements 14706of $O$ and set a \typ{VECSMALL} $E$ with the same length as $v$, such 14707that $E[i]$ is the multiplicity of object $v[i]$ in the original $O$. 14708Shallow function. 14709 14710\section{Vectors of small integers} 14711 14712\subsec{\typ{VECSMALL}} 14713 14714These functions handle \typ{VECSMALL} as an abstract container type 14715of small signed integers. No specific meaning is attached to the content. 14716 14717\fun{GEN}{const_vecsmall}{long n, long c} returns a \typ{VECSMALL} 14718of \kbd{n} components equal to \kbd{c}. 14719 14720\fun{GEN}{vec_to_vecsmall}{GEN z} identical to \kbd{ZV\_to\_zv(z)}. 14721 14722\fun{GEN}{vecsmall_to_vec}{GEN z} identical to \kbd{zv\_to\_ZV(z)}. 14723 14724\fun{GEN}{vecsmall_to_col}{GEN z} identical to \kbd{zv\_to\_ZC(z)}. 14725 14726\fun{GEN}{vecsmall_to_vec_inplace}{GEN z} apply \kbd{stoi} to all entries 14727of $z$ and set its type to \typ{VEC}. 14728 14729\fun{GEN}{vecsmall_copy}{GEN x} makes a copy of \kbd{x} on the stack. 14730 14731\fun{GEN}{vecsmall_shorten}{GEN v, long n} shortens the \typ{VECSMALL} \kbd{v} 14732to \kbd{n} components. 14733 14734\fun{GEN}{vecsmall_lengthen}{GEN v, long n} lengthens the \typ{VECSMALL} 14735\kbd{v} to \kbd{n} components. The extra components are not initialized. 14736 14737\fun{GEN}{vecsmall_indexsort}{GEN x} performs an indirect sort of the 14738components of the \typ{VECSMALL} \kbd{x} and return a permutation stored in a 14739\typ{VECSMALL}. 14740 14741\fun{void}{vecsmall_sort}{GEN v} sorts the \typ{VECSMALL} \kbd{v} in place. 14742 14743\fun{GEN}{vecsmall_reverse}{GEN v} as \kbd{vecreverse} for a \typ{VECSMALL} 14744\kbd{v}. 14745 14746\fun{long}{vecsmall_max}{GEN v} returns the maximum of the elements of 14747\typ{VECSMALL} \kbd{v}, assumed nonempty. 14748 14749\fun{long}{vecsmall_indexmax}{GEN v} returns the index of the largest 14750element of \typ{VECSMALL} \kbd{v}, assumed nonempty. 14751 14752\fun{long}{vecsmall_min}{GEN v} returns the minimum of the elements of 14753\typ{VECSMALL} \kbd{v}, assumed nonempty. 14754 14755\fun{long}{vecsmall_indexmin}{GEN v} returns the index of the smallest 14756element of \typ{VECSMALL} \kbd{v}, assumed nonempty. 14757 14758\fun{int}{vecsmall_isconst}{GEN v} Returns 1 if all the components of \kbd{v} 14759are equal, else returns 0. 14760 14761\fun{int}{vecsmall_is1to1}{GEN v} Returns 1 if the components of \kbd{v} are 14762pair-wise distinct, i.e. if $i\mapsto v[i]$ is a 1-to-1 mapping, else returns 147630. 14764 14765\fun{long}{vecsmall_isin}{GEN v, long x} returns the first index $i$ 14766such that \kbd{v[$i$]} is equal to \kbd{x}. Naive search in linear time, does 14767not assume that \kbd{v} is sorted. 14768 14769\fun{GEN}{vecsmall_uniq}{GEN v} given a \typ{VECSMALL} \kbd{v}, return 14770the vector of unique occurrences. 14771 14772\fun{GEN}{vecsmall_uniq_sorted}{GEN v} same as \kbd{vecsmall\_uniq}, but assumes 14773 \kbd{v} sorted. 14774 14775\fun{long}{vecsmall_duplicate}{GEN v} given a \typ{VECSMALL} \kbd{v}, return 14776$0$ if there is no duplicates, or the index of the first duplicate 14777(\kbd{vecsmall\_duplicate([1,1])} returns $2$). 14778 14779\fun{long}{vecsmall_duplicate_sorted}{GEN v} same as 14780\kbd{vecsmall\_duplicate}, but assume \kbd{v} sorted. 14781 14782\fun{int}{vecsmall_lexcmp}{GEN x, GEN y} compares two \typ{VECSMALL} lexically. 14783 14784\fun{int}{vecsmall_prefixcmp}{GEN x, GEN y} truncate the longest \typ{VECSMALL} 14785to the length of the shortest and compares them lexicographically. 14786 14787\fun{GEN}{vecsmall_prepend}{GEN V, long s} prepend \kbd{s} to the 14788\typ{VECSMALL} \kbd{V}. 14789 14790\fun{GEN}{vecsmall_append}{GEN V, long s} append \kbd{s} to the 14791\typ{VECSMALL} \kbd{V}. 14792 14793\fun{GEN}{vecsmall_concat}{GEN u, GEN v} concat the \typ{VECSMALL} \kbd{u} 14794and \kbd{v}. 14795 14796\fun{long}{vecsmall_coincidence}{GEN u, GEN v} returns the numbers of indices 14797where \kbd{u} and \kbd{v} agree. 14798 14799\fun{long}{vecsmall_pack}{GEN v, long base, long mod} handles the 14800\typ{VECSMALL} \kbd{v} as the digit of a number in base \kbd{base} and return 14801this number modulo \kbd{mod}. This can be used as an hash function. 14802 14803\fun{GEN}{vecsmall_prod}{GEN v} given a \typ{VECSMALL} \kbd{v}, return 14804the product of its entries. 14805 14806\subsec{Vectors of \typ{VECSMALL}} 14807These functions manipulate vectors of \typ{VECSMALL} (vecvecsmall). 14808 14809\fun{GEN}{vecvecsmall_sort}{GEN x} sorts lexicographically the components of 14810the vector \kbd{x}. 14811 14812\fun{GEN}{vecvecsmall_sort_shallow}{GEN x}, shallow variant of 14813\kbd{vecvecsmall\_sort}. 14814 14815\fun{void}{vecvecsmall_sort_inplace}{GEN x, GEN *perm} sort lexicographically 14816\kbd{x} in place, without copying its components. If 14817\kbd{perm} is not \kbd{NULL}, it is set to the permutation that would sort 14818the original \kbd{x}. 14819 14820\fun{GEN}{vecvecsmall_sort_uniq}{GEN x} sorts lexicographically the components of 14821the vector \kbd{x}, removing duplicates entries. 14822 14823\fun{GEN}{vecvecsmall_indexsort}{GEN x} performs an indirect lexicographic 14824sorting of the components of the vector \kbd{x} and return a permutation 14825stored in a \typ{VECSMALL}. 14826 14827\fun{long}{vecvecsmall_search}{GEN x, GEN y, long flag} \kbd{x} being a sorted 14828vecvecsmall and \kbd{y} a \typ{VECSMALL}, search \kbd{y} inside \kbd{x}. 14829\kbd{flag} has the same meaning as for \kbd{setsearch}. 14830 14831\fun{GEN}{vecvecsmall_max}{GEN x} returns the largest entry in all $x[i]$, 14832assumed nonempty. Shallow function. 14833 14834\newpage 14835\chapter{Functions related to the GP interpreter} 14836 14837\section{Handling closures}\label{se:closure} 14838 14839\subsec{Functions to evaluate \typ{CLOSURE}} 14840 14841\fun{void}{closure_disassemble}{GEN C} print the \typ{CLOSURE} \kbd{C} in 14842GP assembly format. 14843 14844\fun{GEN}{closure_callgenall}{GEN C, long n, ...} evaluate the \typ{CLOSURE} 14845\kbd{C} with the \kbd{n} arguments (of type \kbd{GEN}) following \kbd{n} in 14846the function call. Assumes \kbd{C} has arity $\geq \kbd{n}$. 14847 14848\fun{GEN}{closure_callgenvec}{GEN C, GEN args} evaluate the \typ{CLOSURE} 14849\kbd{C} with the arguments supplied in the vector \kbd{args}. Assumes \kbd{C} 14850has arity $\geq \kbd{lg(args)-1}$. 14851 14852\fun{GEN}{closure_callgenvecprec}{GEN C, GEN args, long prec} as 14853\kbd{closure\_callgenvec} but set the precision locally to \kbd{prec}. 14854 14855\fun{GEN}{closure_callgenvecdef}{GEN C, GEN args, GEN def} evaluate the \typ{CLOSURE} 14856\kbd{C} with the arguments supplied in the vector \kbd{args}, where the \typ{VECSMALL} 14857\kbd{def} indicates which arguments are actually present. 14858Assumes \kbd{C} has arity $\geq \kbd{lg(args)-1}$. 14859 14860\fun{GEN}{closure_callgenvecdefprec}{GEN C, GEN args, GEN def, long prec} as 14861\kbd{closure\_callgenvecdef} but set the precision locally to \kbd{prec}. 14862 14863\fun{GEN}{closure_callgen0prec}{GEN C, long prec} evaluate the \typ{CLOSURE} 14864\kbd{C} without arguments, but set the precision locally to \kbd{prec}. 14865 14866\fun{GEN}{closure_callgen1}{GEN C, GEN x} evaluate the \typ{CLOSURE} 14867\kbd{C} with argument \kbd{x}. Assumes \kbd{C} has arity $\geq 1$. 14868 14869\fun{GEN}{closure_callgen1prec}{GEN C, GEN x, long prec} as 14870\kbd{closure\_callgen1}, but set the precision locally to \kbd{prec}. 14871 14872\fun{GEN}{closure_callgen2}{GEN C, GEN x, GEN y} evaluate the \typ{CLOSURE} 14873\kbd{C} with argument \kbd{x}, \kbd{y}. Assumes \kbd{C} has arity $\geq 2$. 14874 14875\fun{void}{closure_callvoid1}{GEN C, GEN x} evaluate the \typ{CLOSURE} 14876\kbd{C} with argument \kbd{x} and discard the result. Assumes \kbd{C} 14877has arity $\geq 1$. 14878 14879The following technical functions are used to evaluate \emph{inline} 14880closures and closures of arity 0. 14881 14882The control flow statements (break, next and return) will cause the 14883evaluation of the closure to be interrupted; this is called below a 14884\emph{flow change}. When that occurs, the functions below generally 14885 return \kbd{NULL}. The caller can then adopt three positions: 14886 14887\item raises an exception (\kbd{closure\_evalnobrk}). 14888 14889\item passes through (by returning NULL itself). 14890 14891\item handles the flow change. 14892 14893\fun{GEN}{closure_evalgen}{GEN code} evaluates a closure and returns the result, 14894or \kbd{NULL} if a flow change occurred. 14895 14896\fun{GEN}{closure_evalnobrk}{GEN code} as \kbd{closure\_evalgen} but raise 14897an exception if a flow change occurs. Meant for iterators where 14898interrupting the closure is meaningless, e.g.~\kbd{intnum} or \kbd{sumnum}. 14899 14900\fun{void}{closure_evalvoid}{GEN code} evaluates a closure whose return 14901value is ignored. The caller has to deal with eventual flow changes by 14902calling \kbd{loop\_break}. 14903 14904The remaining functions below are for exceptional situations: 14905 14906\fun{GEN}{closure_evalres}{GEN code} evaluates a closure and returns the result. 14907The difference with \kbd{closure\_evalgen} being that, if the flow end by a 14908\kbd{return} statement, the result will be the returned value instead of 14909\kbd{NULL}. Used by the main GP loop. 14910 14911\fun{GEN}{closure_evalbrk}{GEN code, long *status} as \kbd{closure\_evalres} 14912but set \kbd{status} to a nonzero value if a flow change occurred. This 14913variant is not stack clean. Used by the break loop. 14914 14915\fun{GEN}{closure_trapgen}{long numerr, GEN code} evaluates closure, while 14916trapping error \kbd{numerr}. Return \kbd{(GEN)1L} if error trapped, and the 14917result otherwise, or \kbd{NULL} if a flow change occurred. Used by trap. 14918 14919 14920\subsec{Functions to handle control flow changes} 14921 14922\fun{long}{loop_break}{void} processes an eventual flow changes inside an 14923iterator. If this function return $1$, the iterator should stop. 14924 14925\subsec{Functions to deal with lexical local variables}\label{se:pushlex} 14926 14927Function using the prototype code \kbd{`V'} need to manually create and delete a 14928lexical variable for each code \kbd{`V'}, which will be given a number $-1, -2, 14929\ldots$. 14930 14931\fun{void}{push_lex}{GEN a, GEN code} creates a new lexical variable whose 14932initial value is $a$ on the top of the stack. This variable get the number 14933$-1$, and the number of the other variables is decreased by one unit. When 14934the first variable of a closure is created, the argument \kbd{code} must be the 14935closure that references this lexical variable. The argument \kbd{code} must be 14936\kbd{NULL} for all subsequent variables (if any). (The closure contains the 14937debugging data for the variable). 14938 14939\fun{void}{pop_lex}{long n} deletes the $n$ topmost lexical variables, 14940increasing the number of other variables by $n$. The argument $n$ must match 14941the number of variables allocated through \kbd{push\_lex}. 14942 14943\fun{GEN}{get_lex}{long vn} get the value of the variable with number \kbd{vn}. 14944 14945\fun{void}{set_lex}{long vn, GEN x} set the value of the variable with number 14946\kbd{vn}. 14947 14948\subsec{Functions returning new closures} 14949 14950\fun{GEN}{compile_str}{const char *s} returns the closure corresponding to the 14951GP expression $s$. 14952 14953\fun{GEN}{closure_deriv}{GEN code} returns a closure corresponding to the 14954numerical derivative of the closure \kbd{code}. 14955 14956\fun{GEN}{closure_derivn}{GEN code, long n} returns a closure corresponding to 14957the numerical derivative of order $n > 0$ of the closure \kbd{code}. 14958 14959\fun{GEN}{snm_closure}{entree *ep, GEN data} 14960Let \kbd{data} be a vector of length $m$, \kbd{ep} be an \kbd{entree} 14961pointing to a C function $f$ of arity $n+m$, returns a \typ{CLOSURE} object 14962$g$ of arity $n$ such that 14963$g(x_1,\ldots,x_n)=f(x_1,\ldots,x_n,gel(data,1),...,gel(data,m))$. If 14964\kbd{data} is \kbd{NULL}, then $m=0$ is assumed. Shallow function. 14965 14966\fun{GEN}{strtofunction}{char *str} returns a closure corresponding to the 14967built-in or install'ed function named \kbd{str}. 14968 14969\fun{GEN}{strtoclosure}{char *str, long n, ...} returns a closure 14970corresponding to the built-in or install'ed function named \kbd{str} with the 14971$n$ last parameters set to the $n$ \kbd{GEN}s following $n$. This is 14972analogous to \kbd{snm\_closure(isentry(str), mkvecn(...))} but the latter has 14973lower overhead since it does not copy arguments, nor does it validate inputs. 14974 14975In the example code below, \kbd{agm1} is set to the function 14976\kbd{x->agm(x,1)} and \kbd{res} is set to \kbd{agm(2,1)}. 14977 14978\bprog 14979 GEN agm1 = strtoclosure("agm",1, gen_1); 14980 GEN res = closure_callgen1(agm1, gen_2); 14981@eprog 14982 14983\subsec{Functions used by the gp debugger (break loop)} 14984\fun{long}{closure_context}{long s} restores the compilation context starting 14985at frame \kbd{s+1}, and returns the index of the topmost frame. This allow to 14986compile expressions in the topmost lexical scope. 14987 14988\fun{void}{closure_err}{long level} prints a backtrace of the last $20$ stack 14989frames, starting at frame \kbd{level}, the numbering starting at $0$. 14990 14991\subsec{Standard wrappers for iterators} 14992Two families of standard wrappers are provided to interface iterators like 14993\kbd{intnum} or \kbd{sumnum} with GP. 14994 14995\subsubsec{Standard wrappers for inline closures} 14996These wrappers are used to implement GP functions taking inline closures as 14997input. The object \kbd{(GEN)E} must be an inline closure which is evaluated 14998with the lexical variable number $-1$ set to $x$. 14999 15000\fun{GEN}{gp_eval}{void *E, GEN x} is used for the prototype code \kbd{`E'}. 15001 15002\fun{GEN}{gp_evalprec}{void *E, GEN x, long prec} as \kbd{gp\_eval}, but 15003set the precision locally to \kbd{prec}. 15004 15005\fun{long}{gp_evalvoid}{void *E, GEN x} is used for the prototype code 15006\kbd{`I'}. The resulting value is discarded. Return a nonzero value if a 15007control-flow instruction request the iterator to terminate immediately. 15008 15009\fun{long}{gp_evalbool}{void *E, GEN x} returns the boolean 15010\kbd{gp\_eval(E, x)} evaluates to (i.e. true iff the value is nonzero). 15011 15012\fun{GEN}{gp_evalupto}{void *E, GEN x} memory-safe version of \kbd{gp\_eval}, 15013\kbd{gcopy}-ing the result, when the evaluator returns components of 15014previously allocated objects (e.g. member functions). 15015 15016\subsubsec{Standard wrappers for true closures} 15017These wrappers are used to implement GP functions taking true closures as 15018input. 15019 15020\fun{GEN}{gp_call}{void *E, GEN x} evaluates the closure \kbd{(GEN)E} on $x$. 15021 15022\fun{GEN}{gp_callprec}{void *E, GEN x, long prec} as \kbd{gp\_call}, 15023but set the precision locally to \kbd{prec}. 15024 15025\fun{GEN}{gp_call2}{void *E, GEN x, GEN y} evaluates the closure \kbd{(GEN)E} 15026on $(x,y)$. 15027 15028\fun{long}{gp_callbool}{void *E, GEN x} evaluates the closure \kbd{(GEN)E} on 15029$x$, returns \kbd{1} if its result is nonzero, and \kbd{0} otherwise. 15030 15031\fun{long}{gp_callvoid}{void *E, GEN x} evaluates the closure \kbd{(GEN)E} on 15032$x$, discarding the result. Return a nonzero value if a control-flow 15033instruction request the iterator to terminate immediately. 15034 15035\section{Defaults} 15036 15037\fun{entree*}{pari_is_default}{const char *s} return the \kbd{entree} 15038structure attached to $s$ if it is the name of a default, \kbd{NULL} 15039otherwise. 15040 15041\fun{GEN}{setdefault}{const char *s, const char *v, long flag} is the 15042low-level function underlying \kbd{default0}. If $s$ is \kbd{NULL}, call all 15043default setting functions with string argument \kbd{NULL} and flag 15044\tet{d_ACKNOWLEDGE}. Otherwise, check whether $s$ corresponds to a default 15045and call the corresponding default setting function with arguments $v$ and 15046\fl. 15047 15048We shall describe these functions below: if $v$ is \kbd{NULL}, we only look 15049at the default value (and possibly print or return it, depending on 15050\kbd{flag}); otherwise the value of the default to $v$, possibly after some 15051translation work. The flag is one of 15052 15053\item \tet{d_INITRC} called while reading the \kbd{gprc}: print and return 15054\kbd{gnil}, possibly defer until \kbd{gp} actually starts. 15055 15056\item \tet{d_RETURN} return the current value, as a \typ{INT} if possible, as 15057a \typ{STR} otherwise. 15058 15059\item \tet{d_ACKNOWLEDGE} print the current value, return \kbd{gnil}. 15060 15061\item \tet{d_SILENT} print nothing, return \kbd{gnil}. 15062 15063\noindent Low-level functions called by \kbd{setdefault}: 15064 15065 15066\fun{GEN}{sd_TeXstyle}{const char *v, long flag} 15067 15068\fun{GEN}{sd_breakloop}{const char *v, long flag} 15069 15070\fun{GEN}{sd_colors}{const char *v, long flag} 15071 15072\fun{GEN}{sd_compatible}{const char *v, long flag} 15073 15074\fun{GEN}{sd_datadir}{const char *v, long flag} 15075 15076\fun{GEN}{sd_debug}{const char *v, long flag} 15077 15078\fun{GEN}{sd_debugfiles}{const char *v, long flag} 15079 15080\fun{GEN}{sd_debugmem}{const char *v, long flag} 15081 15082\fun{GEN}{sd_echo}{const char *v, long flag} 15083 15084\fun{GEN}{sd_factor_add_primes}{const char *v, long flag} 15085 15086\fun{GEN}{sd_factor_proven}{const char *v, long flag} 15087 15088\fun{GEN}{sd_format}{const char *v, long flag} 15089 15090\fun{GEN}{sd_graphcolormap}{const char *v, long flag} 15091 15092\fun{GEN}{sd_graphcolors}{const char *v, long flag} 15093 15094\fun{GEN}{sd_help}{const char *v, long flag} 15095 15096\fun{GEN}{sd_histfile}{const char *v, long flag} 15097 15098\fun{GEN}{sd_histsize}{const char *v, long flag} 15099 15100\fun{GEN}{sd_lines}{const char *v, long flag} 15101 15102\fun{GEN}{sd_linewrap}{const char *v, long flag} 15103 15104\fun{GEN}{sd_log}{const char *v, long flag} 15105 15106\fun{GEN}{sd_logfile}{const char *v, long flag} 15107 15108\fun{GEN}{sd_nbthreads}{const char *v, long flag} 15109 15110\fun{GEN}{sd_new_galois_format}{const char *v, long flag} 15111 15112\fun{GEN}{sd_output}{const char *v, long flag} 15113 15114\fun{GEN}{sd_parisize}{const char *v, long flag} 15115 15116\fun{GEN}{sd_parisizemax}{const char *v, long flag} 15117 15118\fun{GEN}{sd_path}{const char *v, long flag} 15119 15120\fun{GEN}{sd_plothsizes}{const char *v, long flag} 15121 15122\fun{GEN}{sd_prettyprinter}{const char *v, long flag} 15123 15124\fun{GEN}{sd_primelimit}{const char *v, long flag} 15125 15126\fun{GEN}{sd_prompt}{const char *v, long flag} 15127 15128\fun{GEN}{sd_prompt_cont}{const char *v, long flag} 15129 15130\fun{GEN}{sd_psfile}{const char *v, long flag} The \kbd{psfile} default 15131is obsolete, don't use this function. 15132 15133\fun{GEN}{sd_readline}{const char *v, long flag} 15134 15135\fun{GEN}{sd_realbitprecision}{const char *v, long flag} 15136 15137\fun{GEN}{sd_realprecision}{const char *v, long flag} 15138 15139\fun{GEN}{sd_recover}{const char *v, long flag} 15140 15141\fun{GEN}{sd_secure}{const char *v, long flag} 15142 15143\fun{GEN}{sd_seriesprecision}{const char *v, long flag} 15144 15145\fun{GEN}{sd_simplify}{const char *v, long flag} 15146 15147\fun{GEN}{sd_sopath}{const char *v, int flag} 15148 15149\fun{GEN}{sd_strictargs}{const char *v, long flag} 15150 15151\fun{GEN}{sd_strictmatch}{const char *v, long flag} 15152 15153\fun{GEN}{sd_timer}{const char *v, long flag} 15154 15155\fun{GEN}{sd_threadsize}{const char *v, long flag} 15156 15157\fun{GEN}{sd_threadsizemax}{const char *v, long flag} 15158 15159\noindent Generic functions used to implement defaults: most of the above 15160routines are implemented in terms of the following generic ones. In all 15161routines below 15162 15163\item \kbd{v} and \kbd{flag} are the arguments passed to \kbd{default}: 15164\kbd{v} is a new value (or the empty string: no change), and \kbd{flag} is one 15165of \tet{d_INITRC}, \tet{d_RETURN}, etc. 15166 15167\item \kbd{s} is the name of the default being changed, used to display error 15168messages or acknowledgements. 15169 15170\fun{GEN}{sd_toggle}{const char *v, long flag, const char *s, int *ptn} 15171 15172\item if \kbd{v} is neither \kbd{"0"} nor \kbd{"1"}, an error is raised using 15173\tet{pari_err}. 15174 15175\item \kbd{ptn} points to the current numerical value of the toggle (1 or 0), 15176and is set to the new value (when \kbd{v} is nonempty). 15177 15178For instance, here is how the timer default is implemented internally: 15179\bprog 15180GEN 15181sd_timer(const char *v, long flag) 15182{ return sd_toggle(v,flag,"timer", &(GP_DATA->chrono)); } 15183@eprog 15184 15185The exact behavior and return value depends on \kbd{flag}: 15186 15187\item \tet{d_RETURN}: returns the new toggle value, as a \kbd{GEN}. 15188 15189\item \tet{d_ACKNOWLEDGE}: prints a message indicating the new toggle value 15190and return \kbd{gnil}. 15191 15192\item other cases: print nothing and return \kbd{gnil}. 15193 15194 15195\fun{GEN}{sd_ulong}{const char *v, long flag, const char *s, ulong *ptn, 15196ulong Min, ulong Max, const char **msg}\hbadness 10000 15197 15198\item \kbd{ptn} points to the current numerical value of the toggle, and is set 15199to the new value (when \kbd{v} is nonempty). 15200 15201\item \kbd{Min} and \kbd{Max} point to the minimum and maximum values allowed 15202for the default. 15203 15204\item \kbd{v} must translate to an integer in the allowed ranger, a suffix 15205among 15206\kbd{k}/\kbd{K} ($\times 10^3$), 15207\kbd{m}/\kbd{M} ($\times 10^6$), 15208or 15209\kbd{g}/\kbd{G} ($\times 10^9$) is allowed, but no arithmetic expression. 15210 15211\item \kbd{msg} is a \kbd[NULL]-terminated array of messages or \kbd{NULL} 15212(ignored). If \kbd{msg} is not \kbd{NULL}, \kbd{msg}$[i]$ contains 15213a message attached to the value $i$ of the default. The last entry in the 15214\kbd{msg} array is used as a message attached to all subsequent ones. 15215 15216The exact behavior and return value depends on \kbd{flag}: 15217 15218\item \tet{d_RETURN}: returns the new value, as a \kbd{GEN}. 15219 15220\item \tet{d_ACKNOWLEDGE}: prints a message indicating the new value, 15221possibly a message attached to it via the \kbd{msg} argument, and return 15222\kbd{gnil}. 15223 15224\item other cases: print nothing and return \kbd{gnil}. 15225 15226\fun{GEN}{sd_intarray}{const char *v, long flag, const char *s, GEN *pz} 15227 15228\item records a \typ{VECSMALL} array of nonnegative integers. 15229 15230\item \kbd{pz} points to the current \typ{VECSMALL} value, and is set to the 15231new value (when \kbd{v} is nonempty). 15232 15233The exact return value depends on \kbd{flag}: 15234 15235\item \tet{d_RETURN}: returns the new value, as a \typ{VEC} (converted via 15236\kbd{zv\_to\_ZV}) 15237 15238\item \tet{d_ACKNOWLEDGE}: prints a message indicating the new value, 15239(as a \typ{VEC}) and return \kbd{gnil}. 15240 15241\item other cases: print nothing and return \kbd{gnil}. 15242 15243\fun{GEN}{sd_string}{const char *v, long flag, const char *s, char **pstr} 15244\item \kbd{v} is subjet to environment expansion, then time expansion. 15245 15246\item \kbd{pstr} points to the current string value, and is set to the new 15247value (when \kbd{v} is nonempty). 15248 15249\section{Records and Lazy vectors} 15250The functions in this section are used to implement \kbd{ell} structures and 15251analogous objects, which are vectors some of whose components are initialized 15252to dummy values, later computed on demand. We start by initializing the 15253structure: 15254 15255\fun{GEN}{obj_init}{long d, long n} returns an \tev{obj} $S$, a \typ{VEC} 15256with $d$ regular components, accessed as \kbd{gel(S,1)}, \dots, 15257\kbd{gel(S,d)}; together with a record of $n$ members, all initialized to 15258$0$. The arguments $d$ and $n$ must be nonnegative. 15259 15260After \kbd{S = obj\_init(d, n)}, the prototype of our other functions are of 15261the form 15262\bprog 15263 GEN obj_do(GEN S, long tag, ...) 15264@eprog\noindent The first argument $S$ holds the structure to be managed. 15265The second argument \var{tag} is the index of the struct member (from $1$ to 15266$n$) we operate on. We recommend to define an \kbd{enum} and use descriptive 15267names instead of hardcoded numbers. For instance, if $n = 3$, after defining 15268\bprog 15269 enum { TAG_p = 1, TAG_list, TAG_data }; 15270@eprog\noindent one may use \kbd{TAG\_list} or $2$ indifferently as a tag. 15271The former being preferred, of course. 15272 15273\misctitle{Technical note} 15274In the current implementation, $S$ is a \typ{VEC} with $d+1$ entries. 15275The first $d$ components are ordinary \typ{GEN} entries, which you can 15276read or assign to in the customary way. But the last component $\kbd{gel(S, 15277d+1)}$, a \typ{VEC} of length $n$ initialized to \kbd{zerovec}$(n)$, must 15278be handled in a special way: you should never access or modify its components 15279directly, only through the API we are about to describe. Indeed, its entries 15280are meant to contain dynamic data, which will be stored, retrieved and 15281replaced (for instance by a value computed to a higher accuracy), while 15282interacting safely with intermediate \kbd{gerepile} calls. This mechanism 15283allows to simulate C \kbd{struct}s, in a simpler way than with general 15284hashtables, while remaining compatible with the GP language, which knows 15285neither structs nor hashtables. It also serialize the structure in an 15286ordinary \kbd{GEN}, which facilitates copies and garbage collection (use 15287\kbd{gcopy} or \kbd{gerepile}), rather than having to deal with individual 15288components of actual C \kbd{struct}s. 15289 15290\fun{GEN}{obj_reinit}{GEN S} make a shallow copy of $S$, re-initializing 15291all dynamic components. This allows ``forking'' a lazy vector while 15292avoiding both a memory leak, and storing pointers to the same data 15293in different objects (with risks of a double free later). 15294 15295\fun{GEN}{obj_check}{GEN S, long tag} if the \emph{tag}-component in $S$ 15296is non empty, return it. Otherwise return \kbd{NULL}. The \typ{INT} $0$ 15297(initial value) is used as a sentinel to indicated an empty component. 15298 15299\fun{GEN}{obj_insert}{GEN S, long tag, GEN O} insert (a clone of) $O$ 15300as \emph{tag}-component of $S$. Any previous value is deleted, and 15301data pointing to it become invalid. 15302 15303\fun{GEN}{obj_insert_shallow}{GEN S, long K, GEN O} as \tet{obj_insert}, 15304inserting $O$ as-is, not via a clone. 15305 15306\fun{GEN}{obj_checkbuild}{GEN S, long tag, GEN (*build)(GEN)} if the 15307\emph{tag}-component of $S$ is non empty, return it. Otherwise insert 15308(a clone of) \kbd{build(S)} as \emph{tag}-component in $S$, and return it. 15309 15310\fun{GEN}{obj_checkbuild_padicprec}{GEN S, long tag, GEN (*build)(GEN,long), 15311long prec} 15312if the \emph{tag}-component of $S$ is non empty \emph{and} has relative 15313$p$-adic precision $\geq \kbd{prec}$, return it. Otherwise insert (a clone 15314of) \kbd{build(S, prec)} as \emph{tag}-component in $S$, and return it. 15315 15316\fun{GEN}{obj_checkbuild_realprec}{GEN S, long tag, GEN (*build)(GEN, long), 15317long prec} if the \emph{tag}-component of $S$ is non empty \emph{and} 15318satisfies \kbd{gprecision} $\geq \kbd{prec}$, return it. Otherwise insert (a 15319clone of) \kbd{build(S, prec)} as \emph{tag}-component in $S$, and return it. 15320 15321\fun{GEN}{obj_checkbuild_prec}{GEN S, long tag, GEN (*build)(GEN,long), GEN 15322(*gpr)(GEN), long prec} if the \emph{tag}-component of $S$ is non empty 15323\emph{and} has precision $\kbd{gpr}(x)\geq \kbd{prec}$, return it. Otherwise 15324insert (a clone of) \kbd{build(S, prec)} as \emph{tag}-component in $S$, 15325and return it. 15326 15327\fun{void}{obj_free}{GEN S} destroys all clones stored in the $n$ tagged 15328components, and replace them by the initial value $0$. The regular entries of 15329$S$ are unaffected, and $S$ remains a valid object. This is used to 15330avoid memory leaks. 15331