1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename giac_us.info 4@settitle Giac API 5@comment Carleos 20020729 for Debian packaging added: 6@dircategory Math 7@direntry 8* Giac : (giac_us). Computer Algebra System Library 9@end direntry 10@documentlanguage en 11@documentencoding ISO-8859-1 12@c %**end of header 13 14@setchapternewpage odd 15 16@titlepage 17@sp 10 18@comment The title is printed in a large font. 19@center @titlefont{Giac/Xcas} 20 21@c The following two commands start the copyright page. 22@page 23@vskip 0pt plus 1filll 24Copyright @copyright{} 2001 B. Parisse, Institut Fourier 25@end titlepage 26 27@node Top, Installation, , (dir) 28@comment node-name, next,previous, up 29 30Giac is a C++ library that has types for symbolic algebraic manipulations. 31Xcas is a GUI linked with Giac that provides the functionnalities 32of a general purpose computer algebra system. 33Giac's name derive from @uref{http://www.ginac.de}, another C++ 34library for symbolic algebraic computations. 35 36@menu 37* Installation:: How to install giac/icas/xcas 38* Xcas:: Describes the xcas user-interface to giac 39* Giac:: How to program in C++ using giac. 40* Examples:: Some examples of xcas script and C++ program using giac 41* Concept Index:: Index. 42@end menu 43 44@node Installation, Xcas, Top, Top 45@chapter Installing Giac/Xcas 46@menu 47* Binaries:: Installing xcas binaries only 48* Requirements:: Compiling xcas requires libraries and program 49* Options:: Optionnal libraries that enhance giac behaviour 50* Configure:: Options for the configure shell script 51* Compiling:: Compilation of giac 52* Troubles:: Some tips if you are in trouble 53@end menu 54 55@node Binaries, Requirements, Installation, Installation 56@section Installing binaries 57If you want to use @code{xcas/giac} like another CAS and your OS is 58Intel x86 GNU/Linux or Intel StrongARM GNU/Linux or Windows 9x or Mac OS 59X.4(+), then 60you don't need to worry about compilation. Instead you can install 61precompiled binaries: 62@itemize 63@item x86 GNU/Linux as a normal user: 64@uref{ftp://ftp-fourier.ujf-grenoble.fr/xcas/xcas_user.tgz} 65 66Unpack the archive with 67@command{tar xvfz xcas_user.tgz} 68 69then 70@command{cd xcas} 71 72and 73@command{./xcas} 74@item x86 GNU/Linux if you have root access: 75@uref{ftp://ftp-fourier.ujf-grenoble.fr/xcas/xcas_root.tgz} 76Unpack the archive from the @code{/} directory 77@item ARM GNU/Linux: 78@uref{ftp://ftp-fourier.ujf-grenoble.fr/xcas/xcas_ipaq.tgz} 79@item Windows 9x: 80@uref{ftp://ftp-fourier.ujf-grenoble.fr/xcas/xcasinst.exe}. 81Run @code{xcas} from the Start menu. 82@item Mac OS X: 83@uref{ftp://ftp-fourier.ujf-grenoble.fr/xcas/xcas_osx4.dmg.gz}. 84Run @code{xcas} from the Applications. 85@end itemize 86 87@node Requirements, Options, Binaries, Installation 88@section Requirements 89Get Giac source at @uref{ftp://ftp-fourier.ujf-grenoble.fr/xcas/giac_stable.tgz} 90or @uref{http://perso.wanadoo.fr/bernard.parisse/}. 91Check that your C++ compiler understand the C++ ANSI 3 norm. For 92example @code{gcc} version 2.95 or later will work. If the GMP GNU Math 93Precision Library is not installed on your system, install it: 94@uref{http://www.gnu.org/directory/gnump.html}. If you are using GNU/Linux, 95the GMP library is most probably installed but the headers files 96might not, check for a package named something like @code{gmp-devel}. 97 98@node Options, Configure, Requirements, Installation 99@section Options 100@enumerate 101@item If you want numerical functions you should install the Gnu Scientific 102Library available at @uref{http://sources.redhat.com/gsl} 103@item If you want to use NTL for some polynomial operations (currently 104factorization), get version >= 5.2 at @uref{http://www.shoup.net}. Then 105check that you configured with namespace enabled (this is not the 106default) and with GMP enabled (not the default, but this is not mandatory) 107If you are not sure of your install go in the NTL directory and type 108@smallexample 109 make clean 110 ./configure NTL_GMP_LIP=on NTL_STD_CXX=on 111 make 112 make install 113@end smallexample 114@item If you want advanced arithmetic functions, get PARI at 115@uref{http://www.parigp-home.de}. 116If you plan to use an old version of PARI WITHOUT NTL then you MUST MAKE THE 117FOLLOWING PATCHES in the PARI source directory: 118@itemize 119@item File @code{src/basemath/polarit2.c}: remove the word 120@code{static} from the declaration: 121@smallexample 122 static GEN 123 combine_factors(...) 124@end smallexample 125@item File @code{src/headers/paridecl.h}: Add the line 126 127@code{GEN combine_factors(GEN a, GEN famod, GEN p, long klim, long hint);} 128 129in the @code{* polarit2.c} section. 130@item Recompile (@command{make all}) and reinstall PARI (@code{make install}) 131and check that @code{libpari.a} has been updated or copy it explicitely 132from the @code{O<your_os>} directory. 133@item Replace in @code{/usr/local/include/pari/pariinl.h} @code{labs} 134by @code{std::abs} otherwise you might get compiler errors. 135@end itemize 136Check in the giac src directory, file pari.cc that the memory allocated 137to the PARI stack suit your needs (default is 10M of RAM) or modify: 138@code{ long pari_mem_size=10000000;} 139 140@item If you want GUI support, check that you have FLTK 1.1 141installed (available at @uref{http://www.fltk.org}). 142 143@item TeXmacs provides an interface for giac. You can get it 144at @uref{http://www.texmacs.org}. 145After installing giac, run texmacs and use Insert->Session->giac. 146 147@end enumerate 148 149@node Configure, Compiling, Options, Installation 150@section Configure options 151The @code{./configure } shell-script recognizes the following options: 152@enumerate 153@item --enable-debug 154 Allow vecteurs printing and add some debugging code 155@item --enable-fltk 156 GUI support 157@item --enable-gsl 158 Use the Gnu Scientific Library for floating point (e.g. special functions..) 159@item --enable-sscl 160 Allow inclusion of code for semi-classical algorithms (Moyal product, ...) 161 Not available yet 162@item --enable-ntl 163 Allow inclusion of NTL code 164@item --enable-pari 165 Allow inclusion of PARI code 166@end enumerate 167 168These options can be turned off using @code{--disable-option-name} instead of 169@code{--enable-option-name}. By default @code{configure} will use these 170options if the libraries are available on your system. 171 172For full speed binaries, before calling @code{configure} do (with bash 173as shell) 174 175@command{$ export CXXFLAGS="-O3 -fexpensive-optimizations -malign-loops=2 -malign-jumps=2 -malign-functions=2"} 176 177or (with tcsh as shell) 178 179@command{$ setenv CXXFLAGS "-O3 -fexpensive-optimizations -malign-loops=2 -malign-jumps=2 -malign-functions=2"} 180 181 182 183@node Compiling, Troubles, Configure, Installation 184@section Compiling 185Like with any autoconfiguring GNU software, you can type : 186 187@command{ ./configure } 188 189[add options as needed: try @command{./configure -help} for option info] 190 191@command{ make } 192 193@command{ make check } 194 195[become root if necessary] 196 197@command{ make install } 198 199Tips: 200@itemize 201 202@item If you don't want optimizations, set the environment variable 203@env{CXXFLAGS} to @code{-g} before calling configure, with tcsh 204@command{ setenv CXXFLAGS -g}, with bash @command{export CXXFLAGS=-g}. 205 206@item If you want the commandline icas only run 207 208 @command{ ./configure --disable-gui} 209 210 @command{ make } 211 212@item If you want to build xcas for the ARM processor with the Linux familiar 213distribution (e.g. for an iPaq @uref{http://www.handhelds.org}) 214assuming you have the skiff toolchain installed and FLTK installed. 215Check that @code{config.h} defines HAVE_LIBFLTK and does not define 216HAVE_LIBGSL and HAVE_LIBGSLCBLAS unless you have these libraries too, then 217 218@command{ make -f Makefile.ipaq} 219 220Note that I never succeded to build with optimization for the iPaq. 221 222 223@item Windows 224 225You can compile the library version of giac like under Unix. 226Or assuming you have the cygwin tools, gmp and FLTK installed (see 227@uref{http://sources.redhat.com/cygwin} for cygwin, run cygwin, 228go in the @code{src} directory and run 229 230@command{ make -f Makefile.win} 231 232After that, you may run @code{xcas.exe} standalone, provided 233@code{/usr/bin/cygwin1.dll} has been copied in the path (e.g. in the same 234directory as @code{xcas.exe}) 235@end itemize 236 237 238@node Troubles, , Compiling, Installation 239@section Troubles 240@itemize 241@item If you test giac after compilation with @code{make check}, 242please note that the answer assume PARI and NTL are enabled. 243Otherwise you will get some errors because factoring will not 244return the factors in the same order. 245@item Optimization requires much memory for compilation. If you are low 246in memory edit @code{src/Makefile} and if necessary replace the line : 247 248@code{CXXFLAGS = -g -O2} 249by : 250 251@code{CXXFLAGS = -g} 252 253@item If you get an error like 254 255@command{autoheader: Symbol 'CONSTANT_DEBUG_SUPPORT' is not covered by ...} 256 257run 258 259@command{autoheader --localdir=.} 260@item If you get error when compiling @code{modpoly.cc}, it's most certainly 261because you compiled NTL without namespaces. Recompile it (see section) 262@item If you get a linker error about combine_factors not found in 263@code{modfactor.o} it's because you did not modify PARI correctly or 264forgot to re-install the PARI libraries (see section) 265@item Cygwin compilation of Giac with PARI 2.1.1 requires you to make 266some hand work. I could not get the dynamic version of PARI library compiling. 267Therefore I had to do the install by hand 268@smallexample 269cp libpari.a /usr/local/lib 270mkdir /usr/local/include/pari 271cp src/headers/*.h /usr/local/include/pari 272cp Ocygwin/*.h /usr/local/include/pari 273@end smallexample 274Then I got an error compiling @code{pari.cc} that dispeared by commenting 275the offending line in the header @code{/usr/local/include/pari/paricom.h} 276After that all went OK. 277@end itemize 278 279@node Xcas, Giac, Installation, Top 280@chapter Using xcas, an user-interface to giac 281@code{xcas} is an user-interface to giac that is similar to a calculator. 282A readline interface named @code{cas} is also available. 283 284@menu 285* Interface:: 286* CAS:: 287* Geometry:: 288* Spreadsheet:: 289* Scripting:: 290* Environment:: 291@end menu 292 293@node Interface, CAS, ,Xcas 294@section The interface 295You can use but you don't need to have a keyboard to use xcas, it 296is designed to be used on a PDA as well. Use the green shift button to get the 297button-keyboard. 298 299The window is composed from left and up to right and down of: 300@enumerate 301@item The main menu-bar: at the left: session management, configuration 302and help, at the right the commands by theme 303@item The session menu: file and edit operations. In the Edit menu, 304the Add item lets you add levels of different kinds: commandlines, 305comments, 2-d and 3-d geometry and graphs, spreadsheet, program editor 306@item The session, with a blank commandline at startup 307@item The buttons: help (?), switch for scientific keyboard (kbd), 308status button (in red, click here to change the CAS configuration) 309@end enumerate 310 311 312The on-line help gives a short description of all the CAS commands 313with examples that can be pasted to the commandline. A more complete 314description is available by clicking on Details. Command completion 315is enabled in commandlines with the Tab key. 316 317Printing may be done natively to Postscript or with a working 318@code{LaTeX} installation (with @code{pstricks} for 2-d graphs). 319 320@node CAS, Geometry, Interface, Xcas 321@section Computer algebra system commands 322A list of commands of the CAS system. 323@menu 324* Math menu:: 325* Arithmetic:: 326* Cas menu:: 327* Linear algebra:: 328@end menu 329 330@node Math menu, Arithmetic, , CAS 331@subsection Basic mathematic commands 332 333@node Arithmetic, Cas menu, Math menu, CAS 334@subsection Arithmetic of integers and polynomials 335The @code{gcd} and @code{lcm} commands apply to both argument types : they 336return the greatest common divisor or the least common multiplicator. 337Other arithmetic commands must begin with an @code{i} if you want 338to use them with integers, otherwise the arguments will be considered 339as constant polynomials. 340@menu 341* Integer arithmetic:: 342* Polynomial arithmetic:: 343@end menu 344 345@node Integer arithmetic, Polynomial arithmetic, , Arithmetic 346@subsubsection Integer arithmetic functions 347@menu 348* Division:: Euclidean division 349* Gcd:: Gcd, lcm, extended gcd, chinese remainder 350* Primality:: Primality test, factorization, Euler characteristic 351* Other integer:: Jacobi, Legendre symbol... 352@end menu 353 354@node Division, Gcd, , Integer arithmetic 355@subsubsection Euclidean integer division 356Given two integers @code{a} and @code{b}, the euclidean integer division 357is defined by the equality : 358@example 359a=b*q+r 360@end example 361where usually @code{r} is taken between 0 and @code{b-1}, or 362in the symmetric representation, between @code{-b/2} and @code{b/2}. 363The functions @code{iquo(a,b)} and @code{irem(a,b)} return respectively 364@code{q} and @code{r}, or @code{iquorem(a,b)} return both in a vector. 365The @code{smod(a,b)} function will return @code{r} using the symmetric 366remainder convention. 367 368@node Gcd, Primality, Division, Integer arithmetic 369@subsubsection Integer gcd 370The @code{gcd(a,b)} function returns the greatest common divisor 371@code{d} of two integers @code{a} and @code{b}. If you need two integers 372@code{u} and @code{v} such that: 373@example 374a*u+b*v=d 375@end example 376you should call @code{egcd(a,b)} instead, it will return @code{[u,v,d]}. 377 378The @code{ichinrem([a,n],[b,m])} call where @code{n} and @code{m} 379are prime together will return a vector @code{[c,n*m]} such that 380@code{c=a (mod n)} and @code{c=b (mod m)}. 381 382@node Primality, Other integer, Gcd, Integer arithmetic 383@subsubsection Primality and factorization 384The @code{is_prime(a)} function will return 0 if @code{a} is not prime. 385It will return 2 if @code{a} is known to be prime, and 1 if @code{a} 386is a (strong) pseudo-prime. If you have compiled @code{xcas} with PARI 387support, you will get a prime certificate instead (see PARI documentation for 388more information). 389 390The @code{nextprime(a)} and @code{prevprime(a)} will return the next 391or previous (pseudo-)prime, given an integer @code{a}. 392 393The @code{ifactor(a)} function returns a factorization of @code{a}. 394It is a good idea to compile with PARI support if you plan to factor 395relatively large integers (with prime factors having more than 20 digits). 396 397@node Other integer, , Primality, Integer arithmetic 398@subsubsection Other integer functions (Legendre, Jacobi, ...) 399Additional integer functions provided by @code{xcas} are 400@itemize 401@item @code{jacobi(a,b)} 402and @code{legendre(a,b)}, see the GMP documentation for more details. 403@item @code{pa2b2(p)} return @code{[a,b]} so that @code{p=a*a+b*b} 404if @code{p=1 (mod 4)} is prime. 405@end itemize 406 407@node Polynomial arithmetic, , Integer arithmetic, Arithmetic 408@subsubsection Polynomial arithmetic functions 409Polynomials have two representations: symbolic representation or 410by a vector of coefficients. In the symbolic representation you might 411add the variable name as an additionnal parameter to the functions 412you call, otherwise the default variable is used. For the vector 413representation, it is recommended to use the right delimiter @code{poly1[} 414instead of @code{[} so that usual operations (addition, ...) behave 415correctly (i.e. not like vectors or matrices). 416@enumerate 417@item @code{quo(a,b)} @code{rem(a,b)} and @code{quorem(a,b)} 418return respectively @code{q}, @code{r} and @code{[q,r]} polynomials 419so that @code{a=b*q+r} and @code{degree(r)<degree(b)} 420@item @code{gcd(a,b)} return the greatest common divisor of two 421polynomials 422@item @code{egcd(a,b)} is the extended euclidean GCD algorithm, like for 423integers it returns a list of 3 polynomials @code{u,v,d} such 424that @code{au+bv=d}. 425@item @code{chinrem} return the chinese remainder for polynomials written 426as lists. The 2 arguments are two lists made of a polynomial modulo 427another polynomial (where the modulo polynomials must be prime together). 428The answer is the polynomial modulo the product of the modulo polynomials 429that reduce to the original polynomials modulo the original modulo 430polynomials 431@item @code{cyclotomic} takes an integer n as argument and returns the 432n-th cyclotomic polynomial. 433@end enumerate 434 435@node Cas menu, Linear algebra, Arithmetic, CAS 436@subsection Algebra, calculus, ... 437@menu 438* Rewriting:: 439* Diff and integrate:: 440* Limits and series:: 441* Solving equations:: 442* Other cas functions:: 443@end menu 444 445@node Rewriting, Diff and integrate, , Cas menu 446@subsubsection Rewriting expressions 447The @code{normal} command rewrites a rational fraction as a ratio of two 448coprime polynomials. If an expression is not rational, it is first 449rationalized by substitution of transcendental expressions (e.g. 450@code{sin(x)} by a temporary identifier. Algebraic expressions 451(e.g. @code{sqrt(x)}) are normalized too. 452 453The @code{factor} command factorize polynomials. Like above a non 454polynomial expression is first rationalized. You can choose the main 455variable with respect to which the polynomial will be factorized by 456adding it as second argument of @code{factor}. 457 458The @code{texpand} function is called to expand transcendental 459expressions like @code{exp(x+y)=exp(x)*exp(y)} or similar rules 460for trigonometric functions. The @code{tlin} function does 461the reverse operation for trigonometric functions, as the @code{lin} 462function does it for exponentials. 463 464The @code{halftan} function rewrites trigonometric expressions 465in terms of the tangent of the half angle. The @code{hyp2exp} 466function rewrites hyperbolic functions in terms of exponentials. 467 468@node Diff and integrate, Limits and series, Rewriting, Cas menu 469@subsubsection Derivation, integration 470The differentiation instruction is @code{diff(expression,variable)}. 471The undefined antiderivative is obtained using 472@code{integrate(expression,variable)}. If you need defined integration 473between bounds @code{a} and @code{b}, choose 474@code{integrate(expression,variable,a,b)} for exact integration 475or @code{romberg(expression,variable,a,b)} for numeric integration. 476 477Example of defined integration are Fourier coefficients of periodic 478functions. They are provided using @code{fourier_an} and @code{fourier_bn} 479for trigonometric coefficients or using @code{fourier_cn} for 480complex exponentials coefficients. 481 482Some discrete antiderivatives may be obtained using the 483@code{sum(variable,expression)} call. 484 485@node Limits and series, Solving equations, Diff and integrate, Cas menu 486@subsubsection Limits, series expansion. 487For a limit the syntax is 488@code{limit(expression,variable,limitpoint[,direction])}. 489For a series expansion 490@code{series(expression,variable,limitpoint,order[,direction])}. 491@code{giac} implementation of @code{limit} and @code{series} is based 492on the mrv algorithm. 493 494@node Solving equations, Other cas functions, Limits and series, Cas menu 495@subsection Solving equations 496The @code{solve(expression,variable)} call is used to find exact 497solutions of (polynomial-)like equations. Use @code{newton} instead 498for numeric solutions (of a wider range of equations). 499 500@node Other cas functions, , Solving equations, Cas menu 501 502@node Linear algebra, , Cas menu, CAS 503@subsection Linear algebra 504Arithmetic operations on matrices and vectors are done using the usual 505operators. The scalar product of two vectors is obtained using the @code{*} 506operator. 507 508Gaussian elimination (Gauss-Bareiss) over a matrix is performed 509using @code{rref(m)}. The kernel of a linear application with matrix 510m is obtained with @code{ker(m)}. A system of linear equations (written 511symbolically in a vector) can be solved via 512@code{linsolve([equations],[variables])}. 513 514The determinant of a matrix may be obtained using two algorithms, 515either Gauss-Bareiss invoking @code{det(m)}, or by computing minors 516@code{det_minor(m)}. Actually, a last method is provided using the 517computation of the constant coefficient of the characteristic polynomial 518using Fadeev-Leverrier algorithm. 519 520The characteristic polynomial of a matrix may be computed by Fadeev-Leverrier 521algorithm calling @code{pcar(m)}. For matrices withe coefficients in 522a finite field, @code{pcar_hessenberg(m)} is a better choice (@code{O(n^3)} 523complexity where @code{n} is the size of the matrix). 524 525Eigenvalues and eigenvectors are computed using respectively @code{egvl(m)} 526and @code{egv(m)}. The Jordan normal form is obtained invoking 527@code{jordan(m)}. 528 529Quadratic forms (written symbolically) can be reduced to sum and differences 530of squares using @code{gauss(expression,[variables])}. 531 532There is some support for isometries: @code{mkisom} may be used to 533make an isometry from its proper elements as @code{isom(m)} return the 534proper elements of an isometry. 535 536@node Geometry, Spreadsheet, CAS, Xcas 537@section Geometry 538Add a figure (Edit menu of the session, Add item, then select geometry 539and graph 2-d or 3-d). 540As other objects, you can create geometrical objects anatically using the 541commandlines at the left. You may also create points, 542segments, etc. with the mouse (or the stylus) or move a geometrical 543object depending on the mouse mode (Pointer, point, segment, circle, etc.) 544 545To configure or print a graph, use the menu at the right of the graph. 546 547@node Spreadsheet, Scripting, Geometry, Xcas 548@section Spreadsheet 549Add a spreadsheet (Edit menu of the session, Add item, spreadsheet). 550Cells may have a formal value, or eval to a geometric 2-d object 551that will be displayed in a dynamically linked 2-d graph. 552 553@node Scripting, Environment, Spreadsheet, Xcas 554@section The xcas scripting language 555The xcas and icas program provide an interpreted language that is similar to 556popular other CAS programming language. This scripting language is 557available in 4 flavours: C-like syntax (default) or compatibility 558mode for simple Maple, Mupad or TI programs. We describe only the C-like 559syntax. Instructions must end with a semi-column @code{;}. Groups of 560instructions may be combined like in C with brackets. 561 562You can define a program in a commandline, but it is recommended 563to use a Program Editor (Edit->Add->Program menuitem of the session 564menubar) if it is larger than a few lines. 565 566@menu 567* Language mode:: 568* Data:: 569* Loops and conditionnals:: 570* Functions:: 571@end menu 572 573@node Language mode, Data, , Scripting 574@section Selecting the language mode 575Click on the status button and select the programming style. 576Alternatively, the command @code{maple_mode(0)} or @code{maple_mode(1)} or 577@code{maple_mode(2)} may be used to switch the language flavour 578respectively from C-like to Maple-like or Mupad-like mode. Note that this 579command takes effect only when the current parser session is finished 580which means when the next command is processed in interative mode or at 581the end of the current file in batch mode, hence you should not begin a script 582file with this command. In batch mode you can achieve the mode switch by 583setting the environment variable @code{GIAC_MAPLE_MODE}, for example with 584tcsh: @command{setenv GIAC_MAPLE_MODE 1} 585or with bash @command{export GIAC_MAPLE_MODE=1} 586will switch to the Maple-like language. Additionnally you can enter 587the @code{maple_mode(1)} command in the @code{.xcasrc} of your home directory 588to change the default behavior. Or inside @code{xcas} you can run 589the @code{Import} command of the @code{File} menu and select the flavour. 590The @code{Export} command can be used to translate the current level 591of the history inside @code{xcas} to a file, or the @code{View as} command 592of the @code{Edit} menu to translate to the Help output window. 593 594@node Data, Loops and conditionnals, Language mode, Scripting 595@section Data 596The language accept local and global variables, variables are not typed. 597Global variables do not need to be declared, local variables must be declared 598at the beginning of a function by the keyword @code{local} followed by 599the names of the local variables separated by commas @code{,} with a final 600semi-columns @code{;} 601 602The affectation sign is @code{:=} like popular CAS and unlike C. 603For large vectors, lists and matrices, you may also use @code{=<} to make 604in-place modifications (in other words by reference), but be aware 605that all references of the object will be modified. 606Other operations (e.g. @{+ - * /@}) and function calls are done like in C 607or like in an interactive session. 608As in C, the equality test is @code{==}. The single equal sign @code{=} 609is used to return an equation (note that 610an equation will be transformed in a test 611in some situations where an equation could not be expected). 612The other tests are @code{!=} for non equal, @code{< <= > >=} for 613real value comparisons. You can combine tests with @code{&&} or @code{and}, 614and @code{||} or @code{or}. The boolean negation is @code{!} or @code{not}. 615 616@node Loops and conditionnals, Functions, Data, Scripting 617The loop keywoard is like in C 618 619@command{for (initialization;while_condition;increment)@{ loop_block @}} 620 621You can break a loop inside the loop block with @code{break;}. 622You can skip immediately to the next iteration with @code{continue;}. 623 624The conditionnal keywoard is like in C 625 626@command{if (condition) @{ bloc_if_true @} [ else @{ bloc_if_false @} ]} 627 628Additionnaly, multiple-cases is translated like in C 629 630@command{swith (variable)@{ case (value_1): ... break; default: ... ; @} } 631 632@node Functions, , Loops and conditionnals, Scripting 633Functions are declared and implemeted together like this 634 635@command{function_name(parameters):=@{ definition @}} 636 637Parameters are like local variables with an additional initialization 638from the values of the parameters inside the calling instruction. 639 640@code{return return_value;} should be used to return the value 641of the function. 642 643It is not possible to pass arguments by reference, only by value. 644 645 646@node Environment, , Scripting, Xcas 647@section Environment variables 648If one of these variables @code{GIAC_MAPLE}, @code{GIAC_MUPAD}, 649@code{GIAC_C} or @code{GIAC_TI} is defined, the corresponding 650syntax mode will be in effect. If @code{XCAS_RPN} is defined, 651then xcas will start in RPN mode. 652 653The variable @code{XCAS_ROOT} may be used for a custom xcas installation, 654it should point to the directory where xcas is installed. @code{XCAS_LOCALE} 655should point to the directory where the locales are. @code{XCAS_TMP} 656may be defined for temporary exchange files between xcas processes, 657if not defined it will use the home directory. 658 659The variable @code{PARI_SIZE} may be used to define the memory 660available for pari. 661 662The variable @code{BROWSER} may be used for the HTML documentation browser. 663 664The variable @code{LANG} may be used for internationalization. 665 666The variable @code{GIAC_TIME} and @code{GIAC_TEX} may be used 667in giac readline interface to ask for timing and tex output. 668@code{GIAC_DEBUG} will give some info on the internals used. 669 670@node Giac, Examples, Xcas, Top 671In this chapter we will first describe the generic data type of giac, 672the @code{gen} class. Then we describe the most important data 673types than @code{gen} dispatches to (polynomials, vectors, symbolic 674objects and gen unary functions). At this point, the reader should be 675able to code using @code{giac}, hence we describe how to integrate 676code to @code{giac} by inclusion in the library or as a separate 677runtime loadable library (called module). The last item describes 678how you can add new mathematical objects, e.g. quaternions, 679inside the @code{gen} type. 680 681@menu 682* C++:: Why we choosed C++ 683* Gen:: The generic class used everywhere in giac 684* Polynomials:: Polynomials. 685* Vectors and matrices:: Vectors and matrices. 686* Symbolics:: Symbolics. 687* Unary functions:: Functions taking a gen and returning a gen 688* Making a library function:: Add functionnalities to giac 689* Making modules:: Add dynamically loadable functions to giac 690* User defined data:: Define your own data inside giac 691@end menu 692 693@node C++, Gen, , Giac 694Giac uses the C++ language because it is easier to write algebraic 695operations using usual operators, for example @code{a+b*x} is easier 696to understand and modify than @code{add(a,mul(b,x))}, but it does not 697require that you learn object oriented programming. In fact it is more 698a C library using C++ features that makes programming easier (like the 699I/O streams and the Standard Template Library). However you will need 700a recent C++ compiler, e.g. @code{gcc} version 2.95 or later. 701 702 703@node Gen, Polynomials, C++, Giac 704@chapter The gen class 705@cindex gen 706 707@code{gen} is the class used to represent mathematical objects 708(@code{#include <giac/gen.h>}). It's a C union, made either of ``direct'' 709objects like @code{int} or @code{double} 710or of pointers to heap allocated objects that are reference counted. 711Memory allocation is handled by the class itself (except for 712user-defined object types). You can check 713the actual type of a variable of type @code{gen}, e.g. @code{gen e;}, 714using it's @code{type} field (e.g. @code{if (e.type==...)}). This 715@code{type} field of a @code{gen} is an @code{int}. 716 717The @code{gen} might be~: 718@enumerate 719@item an immediate int (@code{e.type==_INT_}) 720@item a double (@code{e.type==_DOUBLE_}) 721@item an arbitrary precision integer (@code{e.type==_ZINT}) 722@item a complex number (@code{e.type==_CPLX}), a pointer to 723two objects of type @code{gen} the real and imaginary parts 724@item a global name (@code{e.type==_IDNT}), with a pointer to an 725@code{identificateur} type 726@item a symbolic object (@code{e.type==_SYMB}), with a pointer to 727a @code{symbolic} type 728@item a vector object (in fact it is a list) (@code{e.type==_VECT}), 729with a pointer to a @code{vecteur} type 730@item a function object (@code{e.type==_FUNC}), 731with a pointer to a @code{unary_function_ptr} type 732@end enumerate 733 734Some other types are available (e.g. a pointer to @code{gen_user} 735an object you can derive to make your own class, or arbitrary precision 736floating point numbers @code{_REAL}), for a complete 737description look at @code{giac/gen.h} (if you have installed @code{giac} 738the path to the include files is @code{/usr/local/include/giac} unless you 739override the default, if you did not install it, the path is the path 740to the @code{src} directory of the source code distribution). 741 742If you want to access the underlying type, after checking that the type 743is correct, you can do the following: 744@enumerate 745@item for immediate int: @code{int i=e.val;} 746@item for double: @code{double d=e._DOUBLE_val;} 747@item for arbitray precision integers: @code{mpz_t * m=e._ZINTptr;} 748@item for complex numbers: @code{gen realpart=*e._CPLXptr,impart=*(e._CPLXptr+1); } 749@item for identificateur: @code{identificateur i=*e._IDNTptr; } 750@item for symbolics: @code{symbolic s=*e._SYMBptr;} 751@item for composites: @code{vecteur v=*e._VECTptr;} 752@item for function objects: @code{unary_function_ptr u=*e._FUNCptr} 753@end enumerate 754 755In addition to the main @code{type}, each @code{gen} has a @code{subtype}. 756This subtype is used sometimes to select different behaviour, e.g. 757adding a constant to a vector might add the constant to all terms for 758some geometric objects represented using vectors, only to the term of 759the diagonal of a square matrix, or to the last term for dense polynomials. 760See @code{giac/dispatch.h} for the description of the subtypes. 761 762@node Polynomials, Vectors and matrices, Gen, Giac 763@cindex Polynomials 764@section Polynomials 765Polynomials are available as: 766@itemize 767@item sparse multivariate polynomials @code{polynome}, 768header files are @code{gausspol.h}, @code{poly.h}, @code{monomial.h} 769@item dense univariate polynomials: @code{poly1} or alias @code{modpoly} 770used for modular univariate polynomials. The type used is the same 771as for vectors and matrices. 772Header files are @code{giac/modfactor.h} and @code{giac/modpoly.h}. 773@end itemize 774 775A @code{gen} can be a polynomials if it's @code{type} field is 776respectively @code{_POLY} (sparse) or @code{_VECT} (dense). 777Conversion functions to and from the symbolic representation with 778respect to global names are declared in @code{giac/sym2poly.cc/h}. 779 780@node Vectors and matrices, Symbolics, Polynomials, Giac 781@cindex Vectors 782@cindex Matrices 783@section Vectors and matrices 784The type used for vectors and matrices is the same, it's a 785@code{std::vector<gen>} (unless you have configured with 786@code{--enable-debug}). The header file is @code{giac/vecteur.h}. 787A @code{gen} can be a vector if it's @code{type} field is 788@code{_VECT}. 789 790@node Symbolics, Unary functions, Vectors and matrices, Giac 791@cindex Symbolics 792@section Symbolics 793Symbolic objects are trees. The @code{sommet} is a @code{unary_function_ptr} 794(a class pointing to the function). The @code{feuille} is either 795an atomic @code{gen} (for a function with one argument) or a composite 796(@code{feuille.type==_VECT}) for a function with more than one argument 797(these functions appears therefore as a function with one argument which 798is the list of all it's arguments). 799 800@node Unary functions, Making a library function, Symbolics, Giac 801@cindex Unary functions 802@section Unary functions 803In the giac library, every function is viewed as a function taking one 804argument and returning one argument. Almost every Xcas functions have 805a C++ equivalent with the same name preceded by a _. 806If a Xcas function has more than one argument, these arguments 807are packed in a vector which is the first argument of the C++ function. 808Most C++ functions require a second argument, which is 809a context pointer. This context pointer 810encapsulate all the context (e.g. complex vs real mode, or all the 811variables that are assigned or assumed). You can use 812@code{giac::context0} as global context pointer or define a context 813@code{giac::context ct;} and use @code{&ct} as last argument to the function. 814 815The files @code{usual.cc/.h} give examples of declaration e.g. for 816exponential and trigonometric functions. Unary functions have the 817following members~: 818@itemize 819@item a fonction taking a @code{gen} and a @code{context *} 820and returning an @code{gen} which does the job 821@item partial derivatives of this function if they exist 822@item a special Taylor expansion if it's needed (see e.g. @code{taylor_asin}). 823This is always the case if your function is defined at infinity. 824Note that this function 825is called at initialization so that you can include code in it for 826example to add your function to the symbolic preprocessing step of the 827@code{limit/series} algorithm. 828@item a string identifier for printing. If you want the parser to 829recognize your function you must add a line in @code{input_lexer.ll} 830(see for example @code{"sin"}) or you must register it (see below). 831@item two special printing function if normal printing (normal printing 832means printing the function name followed by the argument(s) in parentheses) 833is not the right way to print. A null pointer means using normal 834printing. 835@end itemize 836Once your @code{unary_function_eval} is defined, you must construct 837a @code{unary_function_ptr} to be able to use it inside symbolics. 838When declaring the @code{unary_function_ptr}, 839you may give an optional argument to specify a behavior for the evaluation 840of arguments (quoting or special parser rules). 841In this case, you may give a second optionnal argument 842to register your function dynamically in the list of function names 843recognized by the lexer. Be sure to link the object file so that 844initialization occurs after the initialization of @code{input_lexer.ll}, 845it means you must put your object file before @code{input_lexer.o} 846when linking (see for example the position of @code{moyal.o} in 847the @code{Makefile.am} file, @code{moyal} 848is one example where dynamic registering is done). 849 850You have of course the option to declare the function name 851statically in the file @code{input_lexer.ll} but this is not recommended. 852 853@node Making a library function, Making modules, Unary functions, Giac 854Here is one example of a dynamically linkable function named 855@code{example} which takes 2 arguments and returns the sum divided 856by the product if the argument are integers and return itself otherwise. 857The C++ header @code{example.h} code looks like 858@example 859#ifndef __EXAMPLE_H 860#define __EXAMPLE_H 861#include <giac/config.h> 862#include <giac/gen.h> 863#include <giac/unary.h> 864 865#ifndef NO_NAMESPACE_GIAC 866namespace giac @{ 867#endif // ndef NO_NAMESPACE_GIAC 868 869 gen example(const gen & a,const gen & b,GIAC_CONTEXT); 870 gen _example(const gen & args,GIAC_CONTEXT); 871 extern const unary_function_ptr * const at_example ; 872 873#ifndef NO_NAMESPACE_GIAC 874@} // namespace giac 875#endif // ndef NO_NAMESPACE_GIAC 876#endif // __EXAMPLE_H 877@end example 878 879The C++ source code looks like: 880@example 881using namespace std; 882#include "example.h" 883#include <giac/giac.h> 884 885#ifndef NO_NAMESPACE_GIAC 886namespace giac @{ 887#endif // ndef NO_NAMESPACE_GIAC 888 889 gen example(const gen & a,const gen & b,GIAC_CONTEXT)@{ 890 if (is_integer(a) && is_integer(b)) 891 return (a+b)/(a*b); 892 return symbolic(at_example,makesequence(a,b)); 893 @} 894 895 gen _example(const gen & args,GIAC_CONTEXT)@{ 896 if ( (args.type!=_VECT) || (args._VECTptr->size()!=2) ) 897 return gensizeerr(contextptr); // type checking : args must be a vector of size 2 898 vecteur & v=*args._VECTptr; 899 return example(v[0],v[1],contextptr); 900 @} 901 const string _example_s("example"); 902 static define_unary_function_eval (__example,&_example,_example_s); 903 define_unary_function_ptr5( at_example ,alias_at_example,&__example,0,true); 904 905#ifndef NO_NAMESPACE_GIAC 906@} 907#endif // ndef NO_NAMESPACE_GIAC 908@end example 909 910Compile it with 911@example 912c++ -g -c example.cc 913@end example 914 915To test your code, you should write the following @code{test.cc} program 916@example 917#include "example.h" 918 919using namespace std; 920using namespace giac; 921 922int main()@{ 923 gen args; 924 context ct; 925 cout << "Enter arguments of example function, for example 2,3 "; 926 cin >> args; 927 cout << "Result: " << _example(args,&ct) << endl; 928@} 929@end example 930Compile it with the command 931@example 932c++ -g example.o test.cc -lgiac -lgmp 933@end example 934You might need to link to other libraries e.g. 935@code{-lreadline -lhistory -lcurses} depedning on your installation. 936Then run @code{a.out}. Here you would test e.g. with @code{[1,2]}. 937 938You can debug your program as usual, e.g. with 939@code{gdb a.out}, it is recommended to create a @code{.gdbinit} file 940in the current directory so that you can use the @code{v} command 941to print giac data, the @code{.gdbinit} file should contain : 942@example 943echo Defining v as print command for giac types\n 944define v 945print ($arg0).dbgprint() 946end 947@end example 948 949When your function is tested, you can add it to the library. Edit 950the file @code{Makefile.am} of the @code{src} subdirectory 951of @code{giac} : just add @code{example.cc} before @code{input_lexer.cc} 952in the @code{libgiac_la_SOURCES} line and add @code{example.h} in the 953@code{giacinclude_HEADERS} line. 954 955To rebuild the library go in the @code{giac} directory and type 956@code{automake; make} 957 958If you want to share your function(s) with other people, you must 959license it under the GPL (because it will be linked to GPL-ed code). 960Add the GPL header to the files, and send them to the @code{giac} 961contribution e-mail, currently @code{mailto:parisse@@fourier.ujf-grenoble.fr} 962@example 963/* 964 * Copyright (C) 2007 Your name 965 * 966 * This program is free software; you can redistribute it and/or modify 967 * it under the terms of the GNU General Public License as published by 968 * the Free Software Foundation; either version 3 of the License, or 969 * (at your option) any later version. 970 * 971 * This program is distributed in the hope that it will be useful, 972 * but WITHOUT ANY WARRANTY; without even the implied warranty of 973 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 974 * GNU General Public License for more details. 975 * 976 * You should have received a copy of the GNU General Public License 977 * along with this program; if not, write to the Free Software 978 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 979 */ 980@end example 981 982@node Making modules, User defined data, Making a library function, Giac 983Another way to share your code could be to build a dynamic library 984that can be loaded at runtime using facilities of @code{<dlfcns.h>}. 985Warning: modules do not work with static binaries. Be sure 986to have dynamic binaries (this is the default when you compile giac, 987but the packaged @code{xcas} distributed as a binary is build static to 988avoid incompatible libraries). 989 990Let us define a function named @code{mydll} in the file @code{mydll.cc} like 991this : 992@example 993#include <giac/config.h> 994#include <giac/giac.h> 995 996#ifndef NO_NAMESPACE_GIAC 997namespace giac @{ 998#endif // ndef NO_NAMESPACE_GIAC 999 1000 const string _mydll_s("mydll"); 1001 gen _mydll(const gen & args,GIAC_CONTEXT)@{ 1002 return sin(ln(args,contextptr),contextptr); 1003 @} 1004 unary_function_eval __mydll(0,&giac::_mydll,_mydll_s); 1005 unary_function_ptr at_mydll (&__mydll,0,true); // auto-register 1006 1007#ifndef NO_NAMESPACE_GIAC 1008@} // namespace giac 1009#endif // ndef NO_NAMESPACE_GIAC 1010@end example 1011 1012Compile it like this 1013@example 1014c++ -fPIC -DPIC -g -c mydll.cc -o mydll.lo 1015cc -shared mydll.lo -lc -Wl,-soname -Wl,libgiac_mydll.so.0 -o libgiac_mydll.so.0.0.0 1016rm -f libgiac_mydll.so.0 && ln -s libgiac_mydll.so.0.0.0 libgiac_mydll.so.0 1017rm -f libgiac_mydll.so && ln -s libgiac_mydll.so.0.0.0 libgiac_mydll.so 1018@end example 1019 1020The library is loadable at runtime in a session using the command 1021@code{insmod("mydll")} 1022assuming it is stored in a directory available 1023from @code{LD_LIBRARY_PATH} or in @code{/etc/ld.so.conf} otherwise 1024you must put a path to the library file (beginning with @code{./} if 1025it is in the current directory), something like 1026@code{insmod("/path_to/libgiac_mydll.so")} 1027 1028A nice way to test your code is to add the following line in your 1029@code{~/.xcasrc} file : 1030@example 1031insmod("path_to_libmydll/libmydll.so"); 1032@end example 1033where you replace @code{path_to_libmydll.so} with the actual path to 1034@code{libmydll.so} for example @code{/home/joe} if your login name is 1035@code{joe} and @code{mydll} is in your home directory. 1036Then if you are using @code{emacs} as editor, put as first line of 1037the file @code{mydll.cc} 1038@example 1039// -*- mode:C++ ; compile-command: "g++ -I.. -fPIC -DPIC -g -c mydll.cc -o mydll.lo && ln -sf mydll.lo mydll.o && gcc -shared mydll.lo -lc -Wl,-soname -Wl,libmydll.so.0 -o libmydll.so.0.0.0 && ln -sf libmydll.so.0.0.0 libmydll.so.0 && ln -sf libmydll.so.0.0.0 libmydll.so" -*- 1040@end example 1041Now you can compile it with @code{Compile} of the menu @code{Tools} 1042and the resulting code is automatically loaded when you launch a new 1043session with @code{xcas} or @code{cas} which makes testing a breath. 1044 1045@node User defined data, , Making modules, Giac 1046@cindex User defined data 1047@section User defined data 1048The class @code{gen_user} can be derived so that you can include 1049your own data inside @code{gen}. Look at the declaration of @code{gen_user} 1050in the file @code{gen.h} and at the example of the quaternions 1051in the files @code{quater.h} and @code{quater.cc}. 1052 1053@node Examples, Concept Index, Giac, Top 1054@chapter Some examples of C++ program using giac 1055 1056@menu 1057* First example:: 1058@end menu 1059 1060@node First example, , , Examples 1061@chapter A first simple example 1062Type the following text with your favorite editor 1063 1064@smallexample 1065#include <giac/config.h> 1066#include <giac/giac.h> 1067using namespace std; 1068using namespace giac; 1069 1070int main()@{ 1071 context ct; 1072 gen e("x^2-1",&ct); 1073 e=eval(e,1,&ct); 1074 cout << _factor(e,&ct) << endl; 1075@} 1076@end smallexample 1077 1078save it e.g. as @code{tryit.cc} and compile it with 1079 1080@command{c++ -g tryit.cc -lgiac -lgmp} 1081 1082If you get unresolved symbol, then @code{readline} is probably enabled 1083and you should compile like that 1084 1085@command{c++ -g tryit.cc -lgiac -lgmp -lreadline -lcurses} 1086 1087You can now run @code{a.out} which will print the factorisation of 1088@code{x^2-1}. 1089 1090You can also run the program step by step using gdb. We 1091recommended that you copy the file @code{.gdbinit} from the @code{src} 1092directory of the giac distribution, because it enables using 1093@code{v varname} to print the variable @code{varname} of type @code{gen}. 1094 1095Some explanations of the code: 1096@itemize 1097@item the @code{#include <giac/giac.h>} 1098directive includes all the headers of giac (which includes some STL 1099headers like @code{string} or @code{vector}). 1100@item The @code{using namespace} 1101directive are not mandatory, if you don't use them, you need to modify 1102some of the code, e.g. use @code{std::string} instead of @code{string} 1103or @code{giac::gen} instead of @code{gen}. 1104@item Variables of type @code{gen} 1105can be constructed from strings (using the parser), from some C types 1106(like @code{int} or @code{double}), from the STL type 1107@code{std::complex<double>} or from streams (using the parser). 1108@item Operations like @code{+, -, *} are defined on the @code{gen} type 1109but the division is not redefined to avoid confusion between integers 1110(use @code{iquo}) and double C division (use @code{rdiv}). For powers, 1111use @code{pow} as usual. 1112@end itemize 1113 1114@node Concept Index, , Examples, Top 1115@comment node-name, next, previous, up 1116@unnumbered Concept Index 1117 1118@printindex cp 1119 1120@contents 1121@bye 1122