all functions - m

             mac_primitives, file  
 
     sets FILE primitive data types to be native to MacIntosh, 8 byte double.  
interpreted function, defined at i0/std.i   line 2144  

             macl_primitives, file  
 
     sets FILE primitive data types to be native to MacIntosh, long double.  
interpreted function, defined at i0/std.i   line 2152  

             make, args  
          or make  
 
     makes a Makefile for ARGS(1) in the current working directory.  
     args is a list of strings that looks like this:  
       [code_name, new1, new2, ..., "+", old1, old2, ...]  
     (Without ARGS, checks to be sure that existing Makefile has  
     correct MAKE_TEMPLATE for this platform.)  
     Each NEWi is a Yorick include file in the current working  
     directory, which will become a startup file for the new custom  
     version of Yorick you want to build.  Each OLDi file is a  
     startup file for a previously built package; these must be in  
     either the Y_SITE/i0 or Y_SITE/contrib directories (or  
     have softlinks in the current working directory).  
     The matrix.i and fft.i packages are included by default; if you  
     want to override that default, specify "-matrix" and/or "-fft"  
     as part of the list of OLDi.  
     All the startup files must contain a MAKE-INSTRUCTIONS comment.  
     It should be placed near the top of each startup file.  
     This comment consists of a line containing slash* followed by  
     MAKE-INSTRUCTIONS then a number of lines with various keywords,  
     then the closing *slash on its own line.  The recognized keywords  
     are:  
     SRCS = src1.c src2.c src3.f ...  
     LIB = pkg  
     DEPLIBS = dep1 dep2  
     NO-WRAPPERS  
     The SRCS keyword is mandatory; the others are all optional.  
     The SRCS are the source files which produce the compiled functions  
     referenced by the extern statements in the startup file which  
     contains this MAKE-INSTRUCTIONS comment.  The extension ".f" or  
     ".F" implies Fortran source code, which has some special configuration  
     fiddles (see Y_HOME/Maketmpl).  You can continue the list by placing  
     a backslash \ at the end of a line; the list of SRCS stops after the  
     first line which does not end with \.  
     The LIB keyword specifies the name of the library for this package.  
     The library will actually be called libpkg.a and the load option will  
     be -lpkg (don't try to include these decoration in the name pkg you  
     supply).  If the LIB keyword is not present, you will get no library,  
     and you won't be able to use this startup file as one of the OLDi in  
     any new custom versions of Yorick you may build in the future.  
     DEPLIBS is a list of any dependent libraries which the compiled  
     functions in SRCS may need.  Do not include m (the libm math library)  
     or any Fortran libraries or other libraries related to or used by  
     Yorick itself here.  Hopefully, you won't need DEPLIBS at all -- if  
     you do, you will probably need to tweek the Makefile to add correct  
     -L options so that libdep1, libdep2, etc can be found.  
     If none of the extern functions in this startup file has a  
     PROTOTYPE comment, add the NO-WRAPPERS keyword, otherwise don't.  
     See Y_HOME/Maketmpl for more information (start yorick and type  
     Y_HOME to find the directory name at your site).  
     To run this program in batch mode:  
     yorick -batch make.i  
        type this after you've moved to a new platform in order to  
        set the MAKE_TEMPLATE in the Makefile to the correct value  
        for this platform (Y_HOME is probably different)  
     yorick -batch make.i code_name new1 new2 ...  
     yorick -batch make.i code_name new1 new2 ... + old1 old2 ...  
        type this to construct a new Makefile for code_name  
        if a Makefile already exists, it simply performs the check as  
        above; if you want to rebuild a new Makefile, you need to  
        remove or change the name of the old one by hand  
interpreted function, defined at i/make.i   line 10  

             make_sphere(radius, [imax,jmax,kmax],  
                         [phi1, phi2], [theta1, theta2])  
 
     return a mesh (see hex_mesh) representing the given section  
     of the sphere of given RADIUS.  IMAX, JMAX, and KMAX are the  
     number of nodes (cells+1) in the radial, longitude (phi), and  
     colatitude (theta) directions, respectively.  Note that for  
     a right handed coordinate system, phi1theta2.  
interpreted function, defined at i0/hex.i   line 432  

 matchbc  
 
  
interpreted function, defined at i/demo1.i   line 110  

 matgen  
 
  
interpreted function, defined at i/testlp.i   line 194  

             max(x)  
          or max(x, y, z, ...)  
 
     returns the scalar maximum value of its array argument, or, if  
     more than one argument is supplied, returns an array of the  
     maximum value for each array element among the several arguments.  
     In the multi-argument case, the arguments must be conformable.  
builtin function, documented at i0/std.i   line 764  

             median(x)  
          or median(x, which)  
 
     returns the median of the array X.  The search for the median takes  
     place along the dimension of X specified by WHICH.  WHICH defaults  
     to 1, meaning the first index of X.  The median function returns an  
     array with one fewer dimension than its argument X (the WHICH  
     dimension of X is missing in the result), in exact analogy with  
     rank reducing index range functions.  If dimsof(X)(WHICH) is  
     odd, the result will have the same data type as X; if even, the  
     result will be a float or a double, since the median is defined  
     as the arithmetic mean between the two central values in that  
     case.  
interpreted function, defined at i0/std.i   line 1152  

             merge(true_expr, false_expr, condition)  
 
     returns the values TRUE_EXPR or FALSE_EXPR where CONDITION is  
     non-zero or zero, respectively.  The result has the data type of  
     TRUE_EXPR or FALSE_EXPR, promoted to the higher arithmetic type  
     if necessary.  The result has the dimensions of CONDITION.  
     The number of elements in TRUE_EXPR must match the number of  
     non-zero elements of CONDITION, and the number of elements in  
     FALSE_EXPR must match the number of zero elements of CONDITION.  
     (TRUE_EXPR or FALSE_EXPR should be nil if there are no such  
     elements of CONDITION.  Normally, TRUE_EXPR and FALSE_EXPR should  
     be 1-D arrays if they are not nil.)  
     This function is intended for vectorizing a function whose  
     domain is divided into two or more parts, as in:  
        func f(x) {  
          big= (x>=threshhold);  
          wb= where(big);  
          ws= where(!big);  
          if (is_array(wb)) {  
            xx= x(wb);  
            fb=   
          }  
          if (is_array(ws)) {  
            xx= x(ws);  
            fs=   
          }  
          return merge(fb, fs, big);  
        }  
builtin function, documented at i0/std.i   line 846  

             merge2(true_expr, false_expr, condition)  
 
     returns the values TRUE_EXPR or FALSE_EXPR where CONDITION is  
     non-zero or zero, respectively.  The result has the data type of  
     TRUE_EXPR or FALSE_EXPR, promoted to the higher arithmetic type  
     if necessary.  Unlike the merge function, TRUE_EXPR and FALSE_EXPR  
     must be conformable with each other, and with the CONDITION.  
interpreted function, defined at i0/std.i   line 877  

             merge_n(val1,mask1, val2,mask2, ...)  
 
    return array with shape of MASKi (which must all have same shape)  
    and values VALi where MASKi is true.  Unspecified values will be  
    zero; the data type of the result is the data type of the first  
    non-nil VALi.  Each VALi must be a 1D array of length sum(MASKi!=0).  
interpreted function, defined at i/dawson.i   line 161  

             y = mergef(x, f1, cond1, f2, cond2, ... felse)  
 
    Evaluate F1(X(where(COND1))), F2(X(where(COND2))),  
    and so on, until FELSE(X(where(!(COND1 | COND2 | ...))))  
    and merge all the results back into an array Y with the  
    same dimensions as X.  Each of the CONDi must have the  
    same dimensions as X, and they must be mutally exclusive.  
    
    During the evaluation of Fi, note that all of the local  
    variables of the caller of mergef are available.  The  
    Fi are invoked as Fi(X(mergel)) and  the variable mergel  
    = where(CONDi) is available to the Fi, in case they need  
    to extract any additional parameters.  If noneof(CONDi)  
    then Fi will not be called at all, otherwise, the Fi are  
    invoked in order.  The return value of Fi must have the same  
    shape as its argument (which will be a 1D array or scalar).  
    
    Use mergeg to construct secondary results the same shape  
    as X and Y.  
    
interpreted function, defined at i0/std.i   line 899  

             z = mergeg(z, value)  
         or z = mergeg(z)  
 
    If secondary results are to be returned from a mergef, besides  
    its return value, the Fi may construct them using the second  
    form of mergef:  
      z = mergeg(z, value)  
    where z is a variable in the original caller of mergef,  
    and value is its value where(CONDi).  Note that the variable  
    name of the first parameter must be the same as the variable  
    name it is assigned to in this construction -- that variable  
    is being used to hold the state of z as it is built.  After  
    the outer mergef returns, the caller needs to invoke  
      z = mergeg(z)  
    one final time to complete each secondary return value.  
    
    z = [];  
    y = mergef(x, f1, cond, f2);  
    z = mergeg(z);  
    ...  
    func f1(x) {   
      z = mergeg(z, exprz(x));  
      return expry(x);  
    }  
    func f2(x) {   
      z = mergeg(z, exprz(x));  
      return expry(x);  
    }  
    
interpreted function, defined at i0/std.i   line 945  

             mesh3(x,y,z)  
          or mesh3(x,y,z, f1,f2,...)  
          or mesh3(xyz, f1,f2,...)  
          or mesh3(nxnynz, dxdydz, x0y0z0, f1,f2,...)  
 
     make mesh3 argument for slice3, xyz3, getv3, etc., functions.  
     X, Y, and Z are each 3D coordinate arrays.  The optional F1, F2,  
     etc. are 3D arrays of function values (e.g. density, temperature)  
     which have one less value along each dimension than the coordinate  
     arrays.  The "index" of each zone in the returned mesh3 is  
     the index in these cell-centered Fi arrays, so every index from  
     one through the total number of cells indicates one real cell.  
     The Fi arrays can also have the same dimensions as X, Y, or Z  
     in order to represent point-centered quantities.  
     If X has four dimensions and the length of the first is 3, then  
     it is interpreted as XYZ (which is the quantity actually stored  
     in the returned cell list).  
     If X is a vector of 3 integers, it is interpreted as [nx,ny,nz]  
     of a uniform 3D mesh, and the second and third arguments are  
     [dx,dy,dz] and [x0,y0,z0] respectively.  (DXDYDZ represent the  
     size of the entire mesh, not the size of one cell, and NXNYNZ are  
     the number of cells, not the number of points.)  
interpreted function, defined at i/slice3.i   line 66  

             mesh_loc(y0, x0)  
          or mesh_loc(y0, x0, y, x)  
          or mesh_loc(y0, x0, y, x, ireg)  
 
     returns the zone index (=i+imax*(j-1)) of the zone of the mesh  
     (X,Y) (with optional region number array IREG) containing the  
     point (X0,Y0).  If (X0,Y0) lies outside the mesh, returns 0.  
     Thus, eg- ireg(mesh_loc(x0, y0, y, x, ireg)) is the region number of  
     the region containing (x0,y0).  If no mesh specified, uses default.  
     X0 and Y0 may be arrays as long as they are conformable.  
     For mesh_loc wrappers to duplicate the functionality of the  
     digitize and interp functions in 2D, see the library file digit2.i.  
     After #include "digit2.i", type:  help,digit2  
builtin function, documented at i0/graph.i   line 1289  

             min(x)  
          or min(x, y, z, ...)  
 
     returns the scalar minimum value of its array argument, or, if  
     more than one argument is supplied, returns an array of the  
     minimum value for each array element among the several arguments.  
     In the multi-argument case, the arguments must be conformable.  
builtin function, documented at i0/std.i   line 754  

             mkdir, directory_name  
             rmdir, directory_name  
 
     Create DIRECTORY_NAME with mkdir, or remove it with rmdir.  
     The rmdir function only works if the directory is empty.  
builtin function, documented at i0/std.i   line 1703  

             mkdoc, filename  
          or mkdoc, filename, outname, lpp  
 
     alphabetizes and indexes the DOCUMENT comments in FILENAME, and  
     formats into "dictionary-like" pages for printing.  If OUTNAME  
     is not given or nil, the output file will be FILENAME with ".doc"  
     replacing the ".i".  If LPP is not given, it defaults to 58 --  
     the maximum number of available lines per page of output.  
     (Use 55 to be able to print with "lpr -p" style page headings.)  
     FILENAME can be an array of strings to combine several include  
     files into a single document.  
interpreted function, defined at i/mkdoc.i   line 10  

 mkdoc_cross  
 
  
interpreted function, defined at i/mkdoc.i   line 206  

 mkdoc_page  
 
  
interpreted function, defined at i/mkdoc.i   line 258  

 mkdoc_scan  
 
  
interpreted function, defined at i/mkdoc.i   line 144  

 mkdoc_title  
 
  
interpreted function, defined at i/mkdoc.i   line 218  

             mkhtmldoc         generate html documentation tree  
 
      
            mkhtmldoc, from=, to=, keywords=, packinfo= nosrc=, nofunc=   
   generates html documentation from yorick files in selected directories.  
   Without any arguments the subdirectories i0, i, and contrib  
   of Y_SITE are scanned for function definitions, and the documentation is   
   created in subdirectories of the current directory.  
   If specified, the  'from' keyword should be a string array of   
   directories to scan. The 'to' keyword can be used to set a   
   destination directory other than the current directory.  
   A keyword keywords= can be used to specify a file containing a list   
   of keywords from which to create a crude index. If not specified, and   
   if there is a file keywords.txt in the current directory, then that is   
   used. Likewise, the packinfo= can be used to specify a file containing   
   further information on some or all of the files in the source directories.  
   It defaults to packinfo.txt if not specified.   
   The keywords nosrc and nofunc, if non null cut out the slowest parts   
   of the document creation process - crossreferencing the source files,   
   and creating function pages. They can be useful when checking the   
   format of a source file without recreating the whole document set.  
   When source files do not match the formats mkhtmldoc is expecting,   
   warnings are printed to standard output, or to a file specified by  
   the warn keyword. Note that non-compliance with the expected format  
   is not necessarily an indication of errors in the source files - simply  
   that mkhtmldoc can't make sense of them. Generally, however, it is   
   far easier to make one's own files follow the format of the   
   yorick i0 files more closely than it is to modify mkhtmldoc   
   to cope with them.  
   The documentation tree is generated in seven stages.  
   1 - read through all the source files, extracting function names   
       extern declarations of builtin functions, and document comments  
   2 - reread the source files writing them out as preformatted html with   
       anchors for each function declaration and links to the (as yet   
       unwritten) function documentation  
   3 - for each source file, compile a series of html pages of the document   
       comments for the functions in that file. One html file is generated   
       for each first letter.    
   4 - compile a series of html pages for all the functions together, again  
       grouped into pages according to first letters.  
   5 - if a keywords file is available, match keywords in the document   
       comments, and compile a keyword index pointing to all the matched   
       functions.  
   6 - if a packinfo file is available, match source file names with   
       the packinfo file and compile a package list with the corresponding   
       descriptions. Alternatively, if a document comments appears near   
       the top of a source files, unattached to a function, this will be used  
       instead.   
   By default, mkhtmldoc, will create links to the yorick manual, but   
   it does nothing to the manual itself. To get the manual in the right place,   
   run texi2html on the texinfo file yorick.tex putting the files in  
   the 'manual' directory. To put an index bar at the top of each page  
   and set up a margin and background colours, run hdoc_wrap on the manual   
   directory   
   eg, if you are creating the documentation in the current directory,   
   and Y_SITE is where yorick i installed, then   
   >   cp Y_SITE/doc/yorick.tex  manual  
   >   cd manual  
   >   texi2html yorick.tex  
   then in yorick,   
   >  hdoc_wrap, manual  
       
   So as not to overwrite carefully modified pages, the "home" link   
   on the indexbar points to index.html in the documentation directory, but   
   mkhtmldoc writes its template to index-raw.html.  
   This should be moved to index.html and edited by hand as necessary  
   KEYWORDS: keywords, packinfo, from, to, nosrc, nofunc  
interpreted function, defined at contrib/htmldoc.i   line 24  

             fmin= mnbrent(f, x0, x1, x2)  
          or fmin= mnbrent(f, x0, x1, x2, xmin)  
          or fmin= mnbrent(f, x0, x1, x2, xmin, xerr)  
 
     returns the minimum of the function F (of a single argument x),  
     given three points X0, X1, and X2 such that F(X1) is less than  
     either F(X0) or F(X2), and X1 is between X0 and X2.  If the  
     XMIN argument is provided, it is set to the x value which  
     produced FMIN.  If XERR is supplied, the search stops when  
     a fractional error of XERR in x is reached; note that XERR  
     smaller than the square root of the machine precision (or  
     omitted) will cause convergence to machine precision in FMIN.  
     The algorithm is Brent's method - a combination of inverse  
     parabolic interpolation and golden section search - as adapted  
     from Numerical Recipes Ch. 10 (Press, et. al.).  
interpreted function, defined at i/roots.i   line 233  

 mod_midpt  
 
  
interpreted function, defined at i/rkutta.i   line 320  

             xyz = moon(time)  
 
     return position XYZ of the moon relative to center of earth  
     at TIME; the XYZ has leading dimension 3; x is along the vernal  
     equinox, z is ecliptic north.  The corrections to the lunar orbit  
     are from Schlyter (see sch_moon).  Claimed accurate to 2 arc minutes  
     over some reasonable time.  TIME is in days since 0/Jan/00 (that is,  
     0000 UT 31/Dec/99).  This is 1.5 days earlier than the J2000 epoch.  
interpreted function, defined at i/kepler.i   line 261  

             result= mouse(system, style, prompt)  
 
     displays a PROMPT, then waits for a mouse button to be pressed,  
     then released.  Returns array of eleven doubles:  
       result= [x_pressed, y_pressed, x_released, y_released,  
                xndc_pressed, yndc_pressed, xndc_released, yndc_released,  
                system, button, modifiers]  
     If SYSTEM>=0, the first four coordinate values will be relative to  
     that coordinate system.  
     For SYSTEM<0, the first four coordinate values will be relative to  
     the coordinate system under the mouse when the button was pressed.  
     The second four coordinates are always normalized device coordinates,  
     which start at (0,0) in the lower left corner of the 8.5x11 sheet of  
     paper the picture will be printed on, with 0.0013 NDC unit being  
     1/72.27 inch (1.0 point).  Look in the style sheet for the location  
     of the viewport in NDC coordinates (see the style keyword).  
     If STYLE is 0, there will be no visual cues that the mouse  
     command has been called; this is intended for a simple click.  
     If STYLE is 1, a rubber band box will be drawn; if STYLE is 2,  
     a rubber band line will be drawn.  These disappear when the  
     button is released.  
     Clicking a second button before releasing the first cancels the  
     mouse function, which will then return nil.  
     Ordinary text input also cancels the mouse function, which again  
     returns nil.  
     The left button reverses forground for background (by XOR) in  
     order to draw the rubber band (if any).  The middle and right  
     buttons use other masks, in case the rubber band is not visible  
     with the left button.  
     long(result(9)) is the coordinate system in which the first four  
     coordinates are to be interpreted.  
     long(result(10)) is the button which was pressed, 1 for left, 2  
     for middle, and 3 for right (4 and 5 are also possible).  
     long(result(11)) is a mask representing the modifier keys which  
     were pressed during the operation: 1 for shift, 2 for shift lock,  
     4 for control, 8 for mod1 (alt or meta), 16 for mod2, 32 for mod3,  
     64 for mod4, and 128 for mod5.  
builtin function, documented at i0/graph.i   line 1307  

             moush()  
          or moush(y, x, ireg)  
 
     returns the 1-origin zone index for the point clicked in  
     for the default mesh, or for the mesh (X,Y) (region array IREG).  
interpreted function, defined at i0/graph.i   line 1353  

             mov3, xa,ya,za  
 
     move the current 3D plot by XA along viewer's x-axis,  
     YA along viewer's y-axis, and ZA along viewer's z-axis.  
interpreted function, defined at i/pl3d.i   line 85  

             movie, draw_frame  
          or movie, draw_frame, time_limit  
          or movie, draw_frame, time_limit, min_interframe  
 
     runs a movie based on the given DRAW_FRAME function.  The movie  
     stops after a total elapsed time of TIME_LIMIT seconds, which  
     defaults to 60 (one minute), or when the DRAW_FRAME function  
     returns zero.  
     func draw_frame(i)  
     {  
       // Input argument i is the frame number.  
       // draw_frame should return non-zero if there are more  
       // frames in this movie.  A zero return will stop the  
       // movie.  
       // draw_frame must NOT include any fma command if the  
       // making_movie variable is set (movie sets this variable  
       // before calling draw_frame)  
     }  
     If MIN_INTERFRAME is specified, a pauses will be added as  
     necessary to slow down the movie.  MIN_INTERFRAME is a time  
     in seconds (default 0).  
     The keyword bracket_time= (again a time in seconds) can be  
     used to adjust the duration of the pauses after the first  
     and last frames.  It may also be a two element array [beg, end].  
     If the pause at the end is greater than five seconds, you will  
     be prompted to explain that hitting  will abort the final  
     pause.  
     If every frame of your movie has the same limits, use the  
     limits command to fix the limits before you call movie.  
   BUG:  If you hit  to start a movie early, it will not  
         pause at the end of the movie at all.  You probably should  
         not use long initial pauses.  
interpreted function, defined at i/movie.i   line 10  

             movie_stats  
          or movie_stats, timing  
 
     prints statistics from the last movie command, or from the  
     command which produced TIMING.  TIMING is the contents of the  
     movie_timing external variable after the movie command completes.  
interpreted function, defined at i/movie.i   line 116  

             if (catch(-1)) mp_abort  
 
     must be the first line of any function registered with mp_task.  
     This clears all pending messages, then blows up with an error,  
     so it does not return to the calling task.  
interpreted function, defined at i0/mpy.i   line 281  

             mp_bcast, mp_rank, msg  
                   
             msg= mp_bcast(origin)  
          or msg= mp_bcast(origin, dimlist)  
                   
 
     broadcast a message MSG from one process (the ORIGIN) to all other  
     processes, by means of a binary tree -- that is, each process  
     passes the message along to two others.  The ORIGIN argument must  
     have the same value on all processes; you cannot use mp_recv to  
     receive a message broadcast using mp_bcast.  The performance of  
     mp_bcast will probably be better than mp_send with a long to-list.  
     For receivers, the optional DIMLIST argument works as described  
     for mp_recv.  The returned msg will be scalar or 1D without it.  
     All processes can use the nfan= keyword (same value everywhere) to  
     have each distribute to nfan others instead of the default nfan=2.  
     If nfan=1, the message is passed in a daisy chain from one to the  
     next; if nfan=mp_size-1, mp_bcast reduces to a single mp_send.  
interpreted function, defined at i0/mpy.i   line 100  

             mp_cd, dirname  
          or mp_cd  
 
     Change all processes to directory DIRNAME, or to the current  
     working directory of the rank 0 process if DIRNAME is not  
     specified.  Note that DIRNAME must exist for all processes.  
     Note also that the processes may start in different directories.  
     The mp_cd function is registered as a parallel task, so  
     it may only be invoked interactively from the rank 0 process  
     or from another file included there (see mp_task for a more  
     elaborate description).  
interpreted function, defined at i0/mpy.i   line 359  

             rank= mp_from()  
          or rank= mp_from(next)  
 
     returns the rank number of the process of the sender of the most  
     recently received message (or -1 if mp_recv has not been called  
     since the last mpy_sync).  
     If NEXT is non-nil and non-zero, returns the rank of the sender  
     of the *next* message mp_recv will produce.  If no message has  
     yet been posted, returns -1 if next==1.  This feature may be used  
     to test for the arrival of a message without blocking.  If next  
     is a non-zero value other than 1, mp_from will block until the  
     next message actually arrives.  
builtin function, documented at i0/mpy.i   line 167  

             mp_include, filename  
 
     include the specified FILENAME in all processes.  The FILENAME  
     argument is ignored in all but the rank 0 process, which is  
     assumed to be the orginal caller.  The FILENAME must be visible  
     to every process (normally in Y_SITE/include, Y_SITE/contrib,  
     ~/Yorick, or the current working directory - but see mp_cd in  
     the latter case).  
     The mp_include function is registered as a parallel task, so  
     it may only be invoked interactively from the rank 0 process  
     or from another file included there (see mp_task for a more  
     elaborate description).  
interpreted function, defined at i0/mpy.i   line 327  

             ntasks= mp_partition(njobs, ntrips)  
          or ntasks= mp_partition(njobs, ntrips, master_works)  
 
   Partition NJOBS jobs into tasks to be distributed among slave  
   processes by mp_pool.  Typically, NJOBS will be the length of an  
   array of input variables, for example the number of rays to be  
   traced.  Each slave is to perform a task consisting of some number  
   of these individual jobs.  The idea is to pick a number of jobs  
   per task large enough that the overhead of message passing and of  
   carving up inputs then reassembling outputs is tolerable.  
   Conversely, the number of jobs per task should be small enough  
   that the pool of tasks will achieve reasonable load balancing by  
   requiring each slave to come back for a new task several times.  
   The NTRIPS argument is the number of tasks you would like each  
   slave to perform in order to achieve load balancing, bearing in  
   mind that if you choose it too large, you will increase the  
   overhead by partitioning your jobs into too many tasks.  The  
   minimum number of jobs for good load balancing is nslaves*NTRIPS.  
   The return value is the number of tasks into which you should  
   partition the NJOBS.  The mp_prange function can be used to  
   compute the job index range for the i-th such task.  
interpreted function, defined at i0/mpy.i   line 565  

             mp_pool, n_tasks, sow, work, reap, work0  
          or mp_pool, n_tasks, sow, work, reap  
 
   Implement pool-of-tasks parallel calculation.  In this model,  
   the master process on rank 0 has a number of tasks to be done,  
   which he wants to distribute to his slaves.  The pool of tasks  
   is hopefully larger than the number of slaves, so that as each  
   slave finishes, it can be assigned the next task in the pool,  
   achieving a simple form of load balancing.  The master can  
   optionally choose to do the next task when all slaves are busy,  
   or can just block until a slave finishes.  
   N_TASKS is the total number of tasks in the pool; the remaining  
   arguments are functions which carry out the various parts of  
   the particular calculation that mp_pool is managing:  
   func SOW(to, i)  
     mp_send, to, , , ...,   
       
     The SOW function will be called by mp_pool in order to send  
     the messages to a slave which will be received by the WORK  
     function.  Note that SOW only runs on the master process; it  
     is called by mp_pool, and has access to the local variables  
     of the caller of mp_pool, which it presumably will need in  
     order to figure out what to send for the i-th task.  Like  
     Yorick indices, i varies from 1 to N_TASKS.  The local variables  
     in the mp_pool function all have names beginning with "_p_", to  
     make it very unlikely that any variables local to its caller  
     will be shadowed.  
   func WORK  
     input1= mp_recv(dimsi1)  
     input2= mp_recv(dimsi2)  
     ...  
     inputQ= mp_recv(dimsiQ)  
       
     mp_send, 0, , , ...,   
       
     The WORK function runs on a slave, so it does NOT have access  
     to any variables available to the caller of mp_pool on the  
     master process.  Therefore, WORK must be completely self-contained  
     so that all of the information it needs to do its job must arrive  
     in the form of the messages sent by SOW (or state information  
     previously sent to all slaves).  When finished, WORK sends  
     its results back to the master on rank 0; it has no other return  
     value.  
   func REAP(i, m)  
     if (m==1) {  
       result1= mp_recv(dimsr1)  
         
     } else if (m==2) {  
       result2= mp_recv(dimsr2)  
         
     } else ...  
     } else if (m==R) {  
       resultR= mp_recv(dimsrR)  
         
     }  
     return (m==R)  
     The REAP function runs on the master to collect the results sent  
     from a slave by a WORK function.  Like SOW, it is called by mp_pool  
     on rank 0, and therefore has access to all the local variables of  
     the caller of mp_pool, into which REAP must store the results.  
     Because the slaves perform their tasks asynchronously, their return  
     messages may be interleaved.  That is, the first argument i to  
     REAP varies unpredictably in successive calls.  However, for a given  
     i, the second argument m will always begin at 1 and increment by one  
     on successive calls with that i.  Thus, it is possible to cope with  
     situations in which one result message determines the existence of  
     a subsequent message.  The return value of REAP informs mp_pool  
     when that slave has completed its task and is available for another,  
     by returning non-zero when m reaches the final message sent by work.  
     (The mp_pool function has actually peeked at the incoming message  
     to learn its origin, and therefore the corresponding task number i.  
     There is no reason for REAP to call mp_from.)  
   func WORK0(i)  
       
       
     If the optional WORK0 function is provided, and all slaves ever  
     busy, mp_pool will call WORK0 to have the master perform a task.  
     Like SOW and REAP, WORK0 always runs on rank0 and has access to the  
     local variables of the caller of mp_pool.  It should combine the  
     functions of SOW, WORK, and REAP without the message passing.  
interpreted function, defined at i0/mpy.i   line 393  

             range= mp_prange(i, ntasks, njobs)  
 
     return the job index range for the I-th of NTASKS, if the total  
     number of jobs is NJOBS.  This can be used in conjunction with  
     mp_partition and mp_pool.  
interpreted function, defined at i0/mpy.i   line 602  

             msg= mp_recv()  
          or msg= mp_recv(dimlist)  
 
     receive the next message sent by mp_send from some other process.  
     The operation blocks until the next message arrives.  The mp_from  
     function can be used to determine who sent the message, or to  
     determine whether any message at all has arrived.  
     If DIMLIST is specified, it has the same format as for the array  
     function.  The arriving message must have the correct number of  
     elements for the DIMLIST, or a multiple of that number; the  
     result will have either those dimensions, or with an extra  
     dimension tacked on the end if the arriving message is a multiple.  
     (That is, you are really specifying the dimensions of the "cells"  
     of which the message is to be composed.)  By default (and as a  
     special case), the result of mp_recv will be either a scalar value,  
     or a 1D array of the same type as the matching send.  
     Each mp_recv gets one MSG from an mp_send.  Several messages from  
     one process to another are guaranteed to arrive in the order of  
     the mp_send calls, and within each call in the order of the  
     arguments to mp_send.  However, you are responsible for considering  
     how to handle the order of messages arriving from several processes.  
     If you wish to process message in a different order from that in  
     which they are received, you must implement the necessary queuing  
     functions yourself in interpreted code.  
     See mp_task for how to synchronize all the processes in order to  
     cleanly begin a parallel calculation.  
builtin function, documented at i0/mpy.i   line 65  

             mp_send, to, msg  
          or mp_send, to, msg1, msg2, ...  
          or mp_send, to_list, msg1, msg2, ...  
 
     send MSG, MSG1, MSG2, ... to process whose rank is TO.  Each  
     MSG must be an array (or scalar) of type char, short, int, long,  
     float, double, or complex, or a scalar string.  
     If the object is to send a message to all other processes, the  
     binary tree broadcaster mp_bcast will probably be faster than  
     mp_send.  
     If TO_LIST is an array of rank numbers, then each MSG may be an  
     equal length array of pointers to send a different message to  
     each process in the TO_LIST, or one of the basic data types to  
     send the same message to each process in TO_LIST.  
     The mp_send operation blocks until the matching mp_recv operation  
     begins (for every message if multiple MSG or a TO_LIST are  
     specified).  However, within each mp_send, many messages may be  
     launched simultaneously (but never more than one at a time to  
     each process) -- the underlying MPI call is the non-blocking  
     synchronous send routine MPI_Issend.  
     See mp_task for how to synchronize all the processes in order to  
     cleanly begin a parallel calculation.  
builtin function, documented at i0/mpy.i   line 34  

             mp_start, task  
 
     must be the second line of any function TASK which is registered  
     as a parallel task interface using mp_task.  See mp_task for the  
     required form of the TASK function.  
     The mp_start function resynchronizes all processes participating  
     in the parallel calculation.  Called from the rank 0 process,  
     mp_start arranges for TASK to be started without arguments on  
     all other processes; called from any other process, mp_start  
     is a no-op.  
interpreted function, defined at i0/mpy.i   line 253  

             mp_task, task  
 
     register the TASK function as a parallel processing function.  
     Each process must call mp_task to declare the same set of TASK  
     functions, therefore mp_task will normally be called from a  
     source file included by mp_include.  
     A TASK function must be have the following structure in order  
     to work properly:  
        func TASK(arg1, arg2, ...)  
        {  
          if (catch(-1)) mp_abort;  
          mp_start, TASK;  
          if (mp_rank) {  
            ...TASK will be invoked as a subroutine with no    ...  
            ...arguments in all but the rank 0 process         ...  
            ...when it returns, the process becomes idle       ...  
            ...so it no longer participates in the calculation ...  
            ...instead of returning, a non-rank 0 task may also...  
            ...choose to hang indefinitely in an mp_recv --    ...  
            ...it will exit via a caught error when the next   ...  
            ...registered task runs on the rank 0 process      ...  
          } else {  
            ...the interface to task -- it's arguments and return...  
            ...value -- are relevant only to the rank 0 process  ...  
            ...which must distribute startup messages and collect...  
            ...results from all other processes.  when the rank 0...  
            ...process decides the task is finished it returns a ...  
            ...result (or has side effects) which the user wants ...  
            ...the catch line is optional; if not present an     ...  
            ...error in the rank 0 process will leave the other  ...  
            ...processes running.  if the other processes        ...  
            ...might run communicating with each other and       ...  
            ...meaninglessly consuming resources, you should     ...  
            ...worry about this; if the other processes will     ...  
            ...halt without continuing messages from rank 0      ...  
            ...you don't need to bother with this                ...  
            return significant_value;  
          }  
        }  
        mp_task, TASK;  
     Only a registered task will start running on every process  
     in the parallel machine.  A registered task must never be  
     called during the execution of another registered task (since  
     a side effect of the mp_start call is to halt and resynchronize);  
     a registered task may only be called by the rank 0 process,  
     invoked either interactively or as the result of some other  
     interactive action (e.g.- a #include or an unregistered function  
     which calls the registered TASK function).  
     The mp_include, mp_cd, and mp_pool functions are initially the only  
     registered tasks; other tasks are generally defined and registered  
     in source files included as startup files for other packages or by  
     means of mp_include.  
interpreted function, defined at i0/mpy.i   line 185  

             compute 3 pt correlation function in 3D in //  
 
   flag pp = defines the number of pts over which to average   
   EXAMPLE   
   #include "Chris/randfield.i"  
   ui=genrandfield3D(25); u=fft(ui,[-1,-1,-1]).re;  
   res =mp_threeptcor(u)  
       
interpreted function, defined at contrib/correl.i   line 959  

 mpy_idler  
 
  
interpreted function, defined at i0/mpy.i   line 303  

 mpy_init  
 
builtin function, documented at i0/mpy.i   line 647  

 mpy_rank  
 
  
builtin function, documented at i0/mpy.i   line 647  

 mpy_size  
 
builtin function, documented at i0/mpy.i   line 647  

 mpy_sync  
 
  
builtin function, documented at i0/mpy.i   line 623  

             msort(x1, x2, x3, ...)  
 
     returns an index list which sorts the array X1 into increasing  
     order.  Where X1 values are equal, the list will sort X2 into  
     increasing order.  Where both X1 and X2 are equal, X3 will be  
     in increasing order, and so on.  Finally, where all of the keys  
     are equal, the returned list will leave the order unchanged  
     from the input keys.  
     The Xi may be numbers or strings (e.g.- X1 could be an integer  
     while X2 was a string, and X3 was a real).  The Xi must all be  
     conformable, and each dimension of X1 must be as large as the  
     corresponding dimension of any otehr Xi.  
     Hence, msort(x) will return the same list as sort(x), except  
     where the values of x are equal, in which case msort leaves  
     the order unchanged, while sort non-deterministically permutes  
     equal elements.  This feature may cost a factor of two in speed,  
     so don't use it unless you really need it.  In general, msort  
     will call sort up to twice per input argument.  
interpreted function, defined at i/msort.i   line 10  

             msort_rank(x)  
             msort_rank(x, list)  
 
     returns a list of longs the same size and shape as X, whose  
     values are the "rank" of the corresponding element of X among  
     all the elements of X -- the smallest element has rank 0 and  
     the largest has the largest rank, which is equal to one less  
     than the number of distinct values in the array X.  
     If LIST is present, it is set to the order list returned by  
     sort(x(*)).  
interpreted function, defined at i/msort.i   line 55  

             multi_bav(gav)  
 
     returns bin boundaries for the bin centers gav.  
     The bin boundaries are taken at the geometric means between  
     consecutive gav(i), with the endpoints extended slightly beyond  
     the endpoints of gav.  
interpreted function, defined at i/multi.i   line 1141  

             multi_bins(mf)  
 
     The MF parameter is an array of MultiFiles, each created by multif.  
     Automatically generates the bin structure which will be used by  
     multi_streak (if the GB keyword is not specified).  
interpreted function, defined at i/multi.i   line 432  

             gb= multi_line(nbins, hnu0, dhnu, dhnu_min)  
 
     returns 2*NBINS+1 bin boundary energies for 2*NBINS bins  
     cenetered around a spectral line at HNU0 of width DHNU.  The  
     result begins at HNU0-DHNU and ends at HNU0+DHNU.  The finest  
     two bins (nearest HNU0) has width DHNU_MIN, and the remaining  
     bins have equal ratio widths as you move away from HNU0.  
interpreted function, defined at i/multi.i   line 1229  

             xnd= multi_no_dups(x)  
 
     returns its input vector X with any duplicate values removed.  
     X must be non-decreasing and of length at least two.  
interpreted function, defined at i/multi.i   line 1253  

             result= multi_streak(mf, rays, slimits, gb=common_bins)  
 
     like the streak function, but allows opacity to be built up from  
     "slave files", in addition to the "master file" MF(1).  The MF  
     parameter is an array of MultiFiles, each created by multif.  
     The master file MF(1) contains the mesh, and the master list of dump  
     times.  Only dump times which are present in this master list, and  
     in every slave file, will be processed.  
     The master file MF(1) need not contain any opacity or emissivity data  
     at all; each of the slave files MF(2:0) must contain data for at  
     least one zone.  
     The emissivities and opacities from each file are interpolated onto  
     a common group structure.  This common group structure can be  
     provided via the GB keyword to multi_streak.  If it is not provided,  
     GB is computed by examining the group boundary (or center) arrays  
     from the master and every slave file, and building a group structure  
     which is at least as fine as every component group structure, at every  
     point in the spectrum.  
     Example:  
       File family "prob_p00" contains the mesh and opacities and  
       emissivities for all zones.  Family "pp_h00" contains post  
       processed opacities and emissivities on a much finer spectral  
       mesh, but only for zones in regions 1 and 2 of the original  
       problem.  You want to transport the emission from the  
       inner regions 1 and 2 through the overlying material:  
         restore, openb("prob_p00"), ireg;  
         master= multif("prob_p00", zoneuse=where(ireg>2));  
         slave= multif("pp_h00", zonelist=where(ireg==1|ireg==2));  
         rays= ...  
         slimits= ...  
         drat_start= ...  
         drat_stop= ...  
         result= multi_streak([master,slave], rays, slimits);  
         multic, master;  
         multic, slave;  
interpreted function, defined at i/multi.i   line 251  

             multi_streak_save, outname, mf, rays, slimits, gb=common_bins  
          or multi_streak_save, outfile, mf, rays, slimits, gb=common_bins  
 
     like the streak function, but allows opacity to be built up from  
     "slave files", in addition to the "master file" MF(1) and   
     saves the streak in a PDB history file.  The MF parameter  
     is an array of MultiFiles, each created by multif.  
     The master file MF(1) contains the mesh, and the master list of dump  
     times.  Only dump times which are present in this master list, and  
     in every slave file, will be processed.  
     The master file MF(1) need not contain any opacity or emissivity data  
     at all; each of the slave files MF(2:0) must contain data for at  
     least one zone.  
     If the first argument is OUTFILE, a file variable instead of a  
     file name, then that file is used for output.  You can create  
     OUTFILE and add static variables to it with save (but do NOT call  
     add_record) which streak_save otherwise wouldn't know about.  
     The output file has history records at the same times as the  
     input file.  Each record contains "time" (a double scalar),  
     and the two arrays "transp", the transparency (between 0 and 1),  
     and "selfem", the self emission (which has the same units as  
     ekap in the file F).  The dimensions of transp and selfem  
     are ngroup-by-2-by-nrays (where nrays represents zero or more  
     dimensions, copied from the RAYS input array).  The RAYS and  
     SLIMITS inputs are placed into the output file as non-record  
     variables, and any variables in the drat_static option are  
     copied form F to the output file.  The gb and gav variables  
     are copied from F into the output file as well.  If the drat_glist  
     option is present, that is stored in the output file also.  
     The emissivities and opacities from each file are interpolated onto  
     a common group structure.  This common group structure can be  
     provided via the GB keyword to multi_streak.  If it is not provided,  
     GB is computed by examining the group boundary (or center) arrays  
     from the master and every slave file, and building a group structure  
     which is at least as fine as every component group structure, at every  
     point in the spectrum.  
     Example:  
       File family "prob_p00" contains the mesh and opacities and  
       emissivities for all zones.  Family "pp_h00" contains post  
       processed opacities and emissivities on a much finer spectral  
       mesh, but only for zones in regions 1 and 2 of the original  
       problem.  File "prob_strk" contains the streak history.   
       You want to transport the emission from the  
       inner regions 1 and 2 through the overlying material:  
         restore, openb("prob_p00"), ireg;  
         master= multif("prob_p00", zoneuse=where(ireg>2));  
         slave= multif("pp_h00", zonelist=where(ireg==1|ireg==2));  
         fout= openb("prob_strk");  
         save, fout, kmax, lmax;  
         rays= ...  
         slimits= ...  
         drat_start= ...  
         drat_stop= ...  
         result= multi_streak_save(fout, [master,slave], rays, slimits);  
         multic, master;  
         multic, slave;  
interpreted function, defined at i/multi.i   line 312  

             times= multi_times(mf)  
 
     returns the list of times which will be used by multi_streak.  This  
     is the subset of streak_times(mf(1)) which occur in all of the slave  
     files.  The drat_start and drat_stop times work as usual.  
interpreted function, defined at i/multi.i   line 471  

             multic, mf  
          or multic, [mf1, mf2, mf3, ...]  
 
     closes a MultiFile created with multif.  
     Presented with an array of multifiles, closes them all.  
interpreted function, defined at i/multi.i   line 217  

             multif(mf)  
 
     returns an ordinary file pointer for the MultiFile MF.  
     Do not use close to close this pointer; just set it to [] when  
     you are done.  Use multic to properly close the MF.  
interpreted function, defined at i/multi.i   line 240  

             mf= multio(filename)  
          or mf= multio(file)  
 
     opens file FILENAME for use with the multi_streak function.  
     The file MUST be subsequently closed using multic, since  
     this function produces a hidden reference to the file.  The function  
     multif can be used to return an ordinary file pointer, given the  
     returned MF structure.  If the argument is already a stream FILE,  
     that file will be used.  The call still produces a hidden copy of  
     FILE, so you may set your copy of the FILE variable to [], but do  
     not close the file.  
     The following keywords can be used to allow for variations in the  
     variable names or units, and to specify the correspondence between  
     the zones in this file, and the zones in the master file:  
     zonelist=index_list  
     -or- zonelist=zonelist_name  
       is an index list into the (rt,zt) mesh arrays of the master file.  
       If ireg is the region number array (having the same dimensions as  
       rt or zt, and with its first row and column all 0), and if FILENAME  
       contains opacity data only for zones with region numbers 1 and 2,  
       you could open the file using:  
          mf= multio(filename, zonelist=where(ireg==1 | ireg==2))  
       The zonelist should be nil only if the spatial dimensions of the  
       opacity and emissivity in this file exactly match those of rt or  
       zt in the master file.  
       If zonelist is a string, it replaces the default name for the  
       zonelist variable stored in the file (see multi_zonelist).  
     zoneuse=index_list  
       The zonelist specifies how the zones in this file correspond  
       with those in the master file.  The zoneuse list allows you  
       to specify that only some of the zones actually present in the  
       opacity and emissivity arrays of this file are to contribute  
       to the total.  This might be necessary to avoid double counting  
       in a region covered by more than one file.  Hence zoneuse is  
       a list of indices into the spatial dimension(s) of the opacity  
       and emissivity arrays in this file.  If nil, all zones in this  
       file will contribute.  If present, and if zonelist is supplied  
       as an array (rather than out of the file), zonelist should  
       have the same length as zoneuse.  
       As a special case, if zoneuse is a scalar 0, no opacity or  
       emissivity will come from this file; this makes sense only if  
       this is the master file.  
     opac=oname, emiss=ename, srcf=sname  
       specify non-default names for the opacity, emissivity, and  
       osource function arrays.  The defaults are given by the global  
       variables mutli_opac, multi_emiss, and multi_srcf (see help).  
       If the emissivity array is present in the file, it is preferred  
       to the source function array, which will then be ignored.  
     oscale=opacity_unit, escale=emissivity_unit  
       are optional conversion factors to bring the units of the  
       opac and emiss (or srcf) arrays into agreement among the various  
       files which are to be used in a single run.  The default value  
       is 1.0 (i.e.- all files are expected to have the same units).  
     gb=gbname, gav=gavname, gexist=gexistname  
     -or- gexist=group_existence_map  
       specify non-default names for the group boundary, group energy,  
       and group existence arrays.  The defaults are given by the global  
       variables mutli_gb, multi_gav, and multi_gexist (see help).  
       If the group boundary array is present in the file, it is preferred  
       to the group energy array, which will then be ignored.  The file  
       should specify group boundaries if its opacity and emissivity are  
       averaged over finite width bins; group energies if its opacity  
       and emissivity are computed at points.  The group existence map,  
       if present, allows several disjoint spectral regions to exist in  
       a single file.  If the data type of gexist is not "string", it  
       should be an array of length one less than gb, if gb is present,  
       or gav, otherwise.  By this means you can ignore spectral regions  
       which are present in the file.  
     gscale=photon_energy_unit  
       is an optional conversion factor to bring the units of the  
       gb (or gav) arrays into agreement among the various files  
       which are to be used in a single run.  The default value  
       is 1.0 (i.e.- all files are expected to have the same units).  
     tscale=time_unit  
       is an optional conversion factor to bring the units of the  
       time into agreement among the various files which are to be used  
       in a single run.  The default value is 1.0 (i.e.- all files are  
       expected to have the same units).  
     noextrap=1  
       if present and non-zero prevents the opacity and emissivity  
       data from this file from being extrapolated as 1/hnu^3 in  
       master bins at energies above the highest energy bin in this  
       file.  
     freqfirst=0  
       if present and non-zero means the frequency index is first  
       for the opacity and emissivity arrays, instead of the  
       default of frequency index last.  
interpreted function, defined at i/multi.i   line 62  

             fmax= mxbrent(f, x0, x1, x2)  
          or fmax= mxbrent(f, x0, x1, x2, xmax)  
          or fmax= mxbrent(f, x0, x1, x2, xmax, xerr)  
 
     returns the maximum of the function F (of a single argument x),  
     given three points X0, X1, and X2 such that F(X1) is greater than  
     either F(X0) or F(X2), and X1 is between X0 and X2.  If the  
     XMAX argument is provided, it is set to the x value which  
     produced FMAX.  If XERR is supplied, the search stops when  
     a fractional error of XERR in x is reached; note that XERR  
     smaller than the square root of the machine precision (or  
     omitted) will cause convergence to machine precision in FMAX.  
     The algorithm is Brent's method - a combination of inverse  
     parabolic interpolation and golden section search - as adapted  
     from Numerical Recipes Ch. 10 (Press, et. al.).  
interpreted function, defined at i/roots.i   line 208