Program:       POTENTIAL

Purpose:       Program to calculate the 2-dim gravitational potential 
               map of a 2-dim image. This is evaluating the integral 
               given as Eq. 2-3 in the book Galactic Dynamics by 
               Binney and Tremaine. 

Category:      ANALYSIS, CALCULATION

File:          potential.c

Author:        M.G.R. Vogelaar
               Roelof Bottema (algorithm and documentation).

Keywords:

   INSET=      Give set, subsets:
              
               Maximum number of subsets is 1024.
               Input map for which you want to calculate the potential.


   BOX1=       Region for potential field:               [entire subset]
   
               Region in the input map for which you want to calculate
               the potential.
               

   BOX2=       Region to include in calculation:         [entire subset]
   
               The region of the input map which you want to include in
               the calculation of the potential.
               
              
   OUTSET=     Give output set (, subsets):
               
               Output set and subset(s) for the result. The number of
               output subsets is the same as the number of input 
               subsets.
               Also, the size and attributes (header items)
               of the output map are equal to that of the input map.
       


Description:   Program to calculate the 2-dim gravitational potential map 
               of a 2-dim image. This is evaluating the integral given 
               as Eq. 2-3 Galactic Dynamics by Binney and Tremaine. The 
               integral is replaced by a sum over the pixel values in 
               the image of INSET=


                                     rho(p)
               Pot(P) = -G * SUM   ---------- dx dy dz
                                    | p - P |


               P, and p are vector positions, rho(p) is the space density 
               at position p. For the present application, rho(p) * dz 
               is replaced by the (surface density) value at pixel p. 
               dx and dy are pixel sizes which are taken to be equal to 
               1.0 and the distance |p-P| is measured in pixels. 
               Furthermore the constant -G is replaced with 1.0. 

               To calculate the physical value for the potential in 
               some units, you have to multiply the value of Pot 
               with a certain constant. Then you have to know your 
               pixel size in length units and actual value of the surface 
               density. In addition the gravitational constant G has to 
               be included. Since everybody uses his or her own units
               we leave this calculation to the user........ 

               Blanks or undefined values in the input map are replaced 
               with zeros. Positions outside BOX1 in the output map are 
               filled up with blanks.


Notes:         For large regions the calculation may take a while, 
               which gives you the opportunity to have a cup of coffee.


Example:       Calculate the 2-dim potential which would result for a
               photometric image of a galaxy. You first have to do a 
               proper sky subtraction and interpolation over any 
               irregularities or foreground stars. Project the image 
               to face on. Then use POTENTIAL. 


Updates:       Jun 14, 2001: VOG, Document created.