README for Toolbox Dec. 1996 ================== wolf@first.gmd.de This toolbox is written as interactive visualization tool for the "Numerical Recipes", for X-window under Unix (other platforms are in development) It is based on my "grafix" X-Window library, which routines also may be used explicitly. However, it declares some structures and interface functions, which make it simple to use for users without knowledge of C++ (which is the basis for grafix). To have an short overview how it works, please have a look at the demo programs "one-demo.C" and "two-demo.C". If you have an intuitive understanding of these two programs you already should be able to write own applications for one- and twodimensional visualizations. What do you need ---------------- * NR function library in C * "gcc" to compile the code, other compilers possibly do not allow some special constructs, and also "gmake", the GNU version of make is needed at the moment. * You need a Unix clone (SunOS, Linux) and X11R5 or X11R6. Reported platforms that work (possibly with minor adaptions): PC (Linux, or Interactive Unix, ISC 4.0) SGI (Silicon Graphics, IRIX) Sun , SunOS 5.3 (Solaris 2.3) Bull DPX/20 (PowerPC and AIX 3.2.5) HP 9000/735 with HP/UX 9.03A IBM RS/6000 Portations to other platforms are problay simple if you have gcc and X11. I am considering a port to "PC-Windows". * you have to agree to the "GNU GENERAL PUBLIC LICENSE" TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION, (see included standard file "COPYING" for details) in order to use the program, copy, distribute or modificate it or parts of the code. Additionally, I forbid the use of any part of the package for military purposes. The programs ------------ one-demo.C : visualization of the one dimensional wavelet transform using NR function wt1. (See : NR 13.10). It displays the original function (a peak) and its wavelet approximation. Two parameters are intractively changeable : the used nr of wavelet coeffs and the peak width. The wavelet order k (4,12,20) is selectable with a pulldown menu Also displayable are the wavelets theirself. two-demo.C : visualization of solving two dimensionional linear elliptic equation (boundary value problems, see NR 19.5, 19.6). The solvers "sor" (successive overrelaxation) and "mglin" (full multigrid algorithm) are implemented here. The display shows various arrays of the problem (solution, source, error). There are various methods of showing the twodim arrays interactively selectable : grid type, body type (coloured faces), isolines with various options. Click the "help" buttons for explanations. The scrollbar enables to select a source function that varies from one point to a broad stripe. The >> button shows an animation (this is thought as demonstration) wave1.C : also onedim wavelets, but with an interface for experienced C++ programmers. It uses classes of grafix directly and defines inhereted classes. sort-demo.C : graphic demonstration of 4 sorting routines of NR : "piksrt", "shell", "sort", "hpsort". It shows their working online, in real-time. This is a "high-end" example. If you don't see how it works, don't bother with it. (It uses forked processes, shared memory....) advect.C, parabolic.C : an older program for testing several methods for the onedim advective equation (see NR 19.1) "simple upstream", "Lax-Wendroff", "Smolarkievicz" with or without diffusion term. Here included only for special interested users. Similiar programs exist for two and three dimensional equations (please Email me, if interested). Structures and interface functions ---------------------------------- These are defined in toolbox.h/C. 1. solvers You must write at least one function of the C-type void solver(int n); for onedim, or void solver(int nx, int ny) for twodim problems This is the function, which is invoked, whenever a parameter changes. It must compute the desired vectors to display (globally defined, see below). If you want to use functions of NR (or some other numerical library), which have usually other parameters, you must write a "wrapper" function of this type, like it is shown in the demos. These "solvers" are put together in a list : eg : two_solver *sv[] = { new two_solver(sor_wrapper,"sor"), new two_solver(mglin_wrapper,"mglin"), 0 }; You must use the constructors "new two_solver(solver,name)" for this. *** Never forget the closing 0 (the program will probably crash, or your monitor will explode in worst case :-) ** 2. Vectors and Arrays You must declare which vectors (in the onedim case) or arrays (in the twodim) should be displayable. The construction of these must be in the usual NR way eg, : w = vector(1,NMAX) or u = dmatrix(1, n, 1, n); The toolbox is limited yet to the use of float vectors and double arrays, since NR uses them in most cases. Later versions may implement other types also. Again they all are put together in a NULL terminated list, eg : disp_vector *dv[] = { new disp_vector(w, "w : original vector"), new disp_vector(cv,"cv : backtransform "), 0 }; // never forget this terminating NULL !!!! or : disp_array *da[] = { new disp_array(u,"u array auto"), // auto factor new disp_array(u,"u array zinit",zinit), new disp_array(u,"u array fixed",0.1),... 0 }; Twodim disp_arrays have an optional third parameter, which describes how the z-magnification will be computed. If it is omitted, "zauto" is used by default, which means that at each step it is adapted for best display. The other option "zinit" will compute the factor only once for the first step. Afterwards it is held constant (It is interactively changable, however, with the bottom menuline buttons "z+", "z-"). As third option you can give the value explicitely. 3. Parameters Your solvers may use several float parameters, which you want to change interactively (This option is the great advantage of this toolbox) and see the results immediatly. You can also show animations, where these parameters grow automatically by a step size (default = 1.0). These options are defined by a structure : parameter("used number of wavelet coefficients", &frac, 0, 100); The arguments are : a description (type char*), a float pointer (the address of a global float variable, here "frac", which must be initialized somewhere, eg. in main or when defined), the minimum and maximum value it can take, and optionally a step size (def = 1). All parameters are then to put together in a NULL terminated list like above : parameter *scr[] = { new parameter("used number of wavelet coefficients", &frac, 0,100), new parameter("width of the peak function to approx", &fwid, 10, 100), 0 }; // never forget this terminating NULL !!!! The following call of "one-show" or "two-show" will then construct a window, which contains a scrollbar for each parameter. If you have no paramters at all, you need not to define scr. Start the show -------------- You have to use only one function call to show all, eg : one_show("one-demo", n, dv, sv, scr); or: two_show("two-demo", nx, ny, da, sv, scr); The first parameter is only a description string : the name of the window. The parameters n,nx,ny must be the same (or possibly smaller) the the defined vector and array size. Then follow the list of disp_vectors (or disp_arrays), the list of solvers and optionally the list of parameters. Installation and Compilation ---------------------------- 1. "gtar -xvzf toolbox.tgz" : expands the gzipped tar file If you don't have gtar, use gunzip and following tar 2. "cd toolbox0.9" 3. Please inspect "Makefile" and set the right path variable for your Numerical Recipes directory, eg "NR = /home/wolf/nr" 4. Please check the file "grafix/grafix.mk" if your operating system is supported and set the correct path for your X-Window installation (XPATH) It is needed for the include files eg. "Xlib.h" and the library "libX11.a" 5. "gmake all" 6. start with "one-demo" and "two-demo" miscellaneous files : Makefile f_select.c : this is actually the routine select from NR. It had to be renamed because the name conflicts with a UNIX system function grafix : subdirectory for the grafix stuff. If you happen to have it installed already, you might replace this with a link COPYING : GNU public licence Known Problems -------------- There seems to be a problem with "g++ version 2.7.0" on IBM RS/6000 machines. The parameter passing to routines compiled with cc is incorrect for the 9. parameter. This results in a "rjac" value of 0, when calling "sor" which leads to nonconvergence of the routine. That's all folks, enjoy and never forget : ------------------------------------------------------------------------- ... always look on the bright side of life ... (Monty Python) ------------------------------------------------------------------------- Wolfgang Koehler wolf@first.gmd.de GMD-FIRST an der TU Berlin German National Research Centre Tel. priv. (0331) 863238 for Computer Science