section of routines in ylm.i

functions in ylm.i -

 
 
 
legbins


             legbins(y, xb, lmax)  
 
    Return coefficients of Legendre polynomials Pl(z) through order LMAX  
    which give least squares best fit of truncated Legendre series to  
    the given values y integrated over bins xb.  numberof(y) must equal  
    numberof(xb)-1.  The returned coefficients are of the density  
    function represented by y; that is, the value of the Legendre series  
    is y/xb(dif).  
    Use the keyword dy= to specify standard deviations of y.  If not  
    specified, all y will be equally weighted in the fit.  
SEE ALSO: legeval,   legfit,   legser,   legpol,   legint  
 
 
 
legeval


             legeval(al, x)  
 
    evaluate the Legendre series with coefficients AL = [a0,a1,a2,...]  
    at points X.  
SEE ALSO: legfit,   legser,   legpol,   ylm  
 
 
 
legfit


             legfit(y, x, lmax)  
 
    return coefficients of Legendre polynomials Pl(z) through order LMAX  
    which give least squares best fit of truncated Legendre series to  
    the given points (X,Y).  The points X should be uniformly distributed  
    in the interval [-1,1].  If not, you should specify the dx= keyword  
    giving the dx associated with each point Y (dx must be conformable  
    with Y).  
SEE ALSO: legeval,   legbins,   legser,   legpol  
 
 
 
legint


             legint(lmax, z)  
 
    Return integrals of Legendre polynomials Pl(z) through order LMAX  
    evaluated at Z, as a 1+LMAX by dimsof(Z) array.  
      integral[1,z]{ dz P[l](z) } = (P[l+1](z) - P[l-1](z)) / (2l+1)  
    Note that the lower limit of integration is z=+1.  If you want  
    the integral from some other z=z0, subtract legint(lmax,z0).  
SEE ALSO: legpol,   legbins,   legeval,   legfit,   legser  
 
 
 
legpol


             legpol(lmax, z)  
 
    return Legendre polynomials Pl(z) through order LMAX evaluated at Z,  
    as a 1+LMAX by dimsof(Z) array.  
      P[0] = 1  
      P[1] = z  
      l P[l] = (2l-1) z P[l-1] - (l-1) P[l-2,m]  
    integral[-1,1]{ dz P[l](z)^2 } = 2/(2l+1)  
SEE ALSO: legeval,   legint,   legfit,   legser,   ylm  
 
 
 
legser


             b = legser(a)  
         or b = legser(f, lmax)  
         or b = legser(cfit, lmax)  
         or matrix = legser(lmax)  
 
    return coefficients B of Legendre series, given coefficients A of  
    Chebyshev series for the same function.  
    In the second form, F is a function F(x) on -1<=x<=1, and LMAX is the  
    maximum order of the Legendre series.  This first performs a Chebyshev  
    fit of order 2*LMAX to F(x), then truncates the Chebyshev fit to LMAX.  
    In the third form, CFIT is returned by cheby_fit, and will be truncated  
    to order LMAX.  (The interval for CFIT should be [-1,1] to make sense.)  
    You may specify LMAX=-1 to use the full order of CFIT, but unless CFIT  
    has already been truncated, that will risk inaccuracy at high order.  
    In the fourth form, returns the MATRIX such that B = A(+)*MATRIX(+,).  
    
    ACM algorithm 473, Robert Piessens, Comm ACM vol 17 no 1, Jan 1974  
    Tn(x) = Chebyshev polynomials, Pl(x) = Legendre polynomials  
    f(x) = sum[n=0,N]{An Tn(x)}  
    Bl = (2l+1)/2 integral[-1,1]{dx Pl(x) f(x)}  
       ~ (2l+1)/2 sum[k=0,N]{Ak Ilk}  
    where Ilk = integral[-1,1]{dx Pl(x) Tk(x)}  
      I[l,k] = 0 for k

SEE ALSO: legeval,   legfit,   legpol,   cheby_fit  
 
 
 
ylm


             ylm(lmax, theta, phi)  
         or ylm(lmax, x, y, z)  
 
    return 1+LMAX by 1+LMAX by dimsof(THETA,PHI) or dimsof(X,Y,Z) array  
    of all real spherical harmonics through L=LMAX.  The (X,Y,Z) are  
    projected onto the unit sphere to get (sin(THETA)*cos(PHI),  
    sin(THETA)*sin(PHI), cos(THETA)).  The inverse relation is  
    THETA = acos(Z), PHI = atan(Y,X).  The point X=Y=Z=0 is mapped to  
    THETA=0 or (0,0,1).  
    
    Supply the cplx=1 keyword to return complex spherical harmonics.  
    
    The real spherical harmonics y[l,m] are defined in terms of the complex  
    spherical harmonics Y[l,m] by:  
      y[l,m] = sqrt(2) * Re(Y[l,m])       for m>0  
             = Y[l,0]                     for m=0  
             = sqrt(2) * Im(Y[l,abs(m)])  for m<0  
    With the Condon-Shortly phase convention for m<0, the Y[l,m] are:  
      Y[l,m] = sqrt(0.5) * (y[l,m] + 1i*y[l,-m])           for m>0  
             = y[l,0]                                      for m=0  
             = (-1)^m * sqrt(0.5) * (y[l,-m] - 1i*y[l,m])  for m<0  
      so that conj(Y[l,m]) = (-1)^m Y[l,-m]  
    (This is the Y[l,m] used by Mathematica and most quantum mechanics  
     texts, but not necessarily in other disciplines.)  
    
    The layout of the Y[l,m] in the first two dimensions of ylm is:  
      y[l,m] = y(1+l, 1+l-m)   for m>=0  
             = y(1+l+m, 1+l)   for m<=0  
      y(i,j) = y[max(i,j)-1, i-j  
    so  y(,1) = y[0, 0]  y[1, 1]  y[2, 2]  y[3, 3] ...  
        y(,2) = y[1,-1]  y[1, 0]  y[2, 1]  y[3, 2]  
        y(,3) = y[2,-2]  y[2,-1]  y[2, 0]  y[3, 1]  
        y(,4) = y[3,-3]  y[3,-2]  y[3,-1]  y[3, 0] ...  
                  ...                        ...  
    You can use the auxilliary function ylm_lm to extract or set particular  
    [l,m] values in such an array.  
    
    Note: Will produce SIGFPE due to overflow for LMAX>150 or so.  The  
    overflow occurs in an intermediate calculation, but I believe the  
    domain of the function could not be extended too much further before  
    overflow would occur in the result.  
    
SEE ALSO: ylm_lm,   ylm_fit,   ylm_eval,   legpol  
 
 
 
ylm_eval


             v = ylm_eval(alm, theta, phi)  
         or v = ylm_eval(alm, x, y, z)  
 
    evaluates the spherical harmonic expansion ALM at points (THETA,PHI)  
    or (X,Y,Z), where (X,Y,Z) will be projected onto the unit sphere.  
    The return value has dimsof(THETA,PHI), or dimsof(X,Y,Z).  The input  
    ALM is arranged as a 1+lmax by 1+lmax array, as described in detail  
    in the help,ylm documentation, and as returned by ylm_fit.  
    
SEE ALSO: ylm_fit,   ylm,   ylm_lm  
 
 
 
ylm_fit


             alm = ylm_fit(lmax, v, theta, phi)  
         or alm = ylm_fit(lmax, v, x, y, z)  
 
    returns least squares fit of spherical harmonic coefficients alm  
    through l=LMAX to the function V specified at points (THETA,PHI)  
    on the surface of a sphere.  The points on the sphere may also be  
    specified by three coordinates (X,Y,Z), which are projected onto  
    the unit sphere.  The V, THETA, PHI (or X, Y, Z) arrays should all  
    have the same dimensions, although the coordinate arrays THETA  
    and PHI (or X, Y, Z) will be broadcast to the dimensions of V if  
    necessary.  The returned ALM is a 1+LMAX by 1+LMAX array of real  
    numbers for a real spherical harmonic expansion.  The correspondence  
    between the dimensions of ALM and the values of l and m is detailed  
    in the help,ylm documentation.  
    
    The ylm_fit function returns the ALM which minimize  
       sum( ((ALM * ylm(lmax, THETA,PHI))(sum,sum,..) - V)^2 )  
    using the regress function.  See  help,regress for details.  
    
    This fit requires that the points (THETA,PHI) be uniformly  
    distributed over the sphere.  If not, you may supply a domega=  
    keyword, where domega has the same dimensions as V, and specifies  
    the solid angle (or effective solid angle) to be associated with  
    each point V.  The domega= keyword should always be used when  
    (THETA,PHI) are the centers of a spherical mesh.  
    
    Note that numberof(V) must be at least (1+LMAX)^2.  
    
SEE ALSO: ylm_eval,   ylm,   ylm_lm  
 
 
 
ylm_lm


             lm = ylm_lm(lmax)  
         or list = ylm_lm(lmax, l, m)  
         or lm = ylm_lm(y)  
         or y_subset = ylm_lm(y, l, m)  
         or y_old = ylm_lm(y, l, m, y_values)  
 
    manipulates an array of values Y returned by the ylm function,  
    for which the first two indices represent the l and m values of  
    the spherical harmonic, y[l,m] = y(1+l-min(0,m), 1+l-max(0,m)).  
    (See help,ylm for a complete description of the indexing of Y.)  
    Note that for real spherical harmonics, M>0 are the cosine  
    components and M<0 are the sin components.  
   
    The first argument to ylm_lm can be either a scalar LMAX, or an  
    array Y returned by ylm, whose first two dimensions, 1+lmax by  
    1+lmax, determine lmax.  
    
    Called with a single argument, ylm_lm returns the  
    1+LMAX by 1+LMAX by 2 array of [l,m] values corresponding to the  
    first two dimensions of a result returned by ylm.  
    
    If present, the second and third arguments L and M to ylm_lm must  
    be conformable arrays of L and M values.  When the first argument  
    is the scalar LMAX, ylm_lm returns the index list, with dimsof(L,M),  
    of indices into a 1+LMAX by 1+LMAX array corresponding to those  
    values of L and M.  For example:  
       y = ylm(lmax, z);  
       list = ylm_lm(lmax, l, m);  
       y_subset = y(list,1,..);  // extracts subset of y  
    
    If you only want the index list returned by ylm_lm(lmax,l,m) in  
    order to extract or to set a subset of a single array with leading  
    dimensions 1+lmax by 1+lmax, you may pass that array as the first  
    argument Y to ylm_lm, and ylm_lm will return the extracted values  
    y_subset as in the previous example, rather than the index list.  
    Thus, the following extracts the same subset as in the previous  
    example:  
       y = ylm(lmax, z);  
       y_subset = ylm_lm(y, l, m);  
    
    Finally, if you wish to set the subset of Y, you may supply a  
    fourth argument Y_VALUES, in which case ylm_lm returns the previous  
    values of the subset before changing them in the input Y:  
       y_old = ylm_lm(y, l, m, y_values);  
    
    Note that y_subset (or y_old) has the two leading dimensions of Y  
    replaced by dimsof(L,M), and that Y_VALUES must be conformable with  
    y_subset for the purposes of the assignment.  
    
SEE ALSO: ylm,   ylm_fit