; GLENS
;---------------------------------------------------------------
;! models galaxy gravitational lens acting on 3 component source
;# Task Modeling
;-----------------------------------------------------------------------
;;  Copyright (C) 1995
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
;---------------------------------------------------------------
GLENS     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
GLENS     Gravitational Lens Model for Elliptical Galaxies.
OBJECT                             Source name
IMSIZE                             Output image size (cells)
OUTNAME                            Output image name (name)
OUTCLASS                           Output image name (class)
OUTSEQ           -1.0     9999.0   Output image name (seq. #)
OUTDISK           0.0        9.0   Output image disk unit #.
APARM                              1:Source X1;  2:Source Y1;
                                   3:Major Axis; 4:Minor Axis;
                                   5:Angle;    6,7:Brightness
BPARM                              1:Source X2;  2:Source Y2;
                                   3:Major Axis; 4:Minor Axis;
                                   5:Angle;    6,7:Brightness
CPARM                              1:Source X3;  2:Source Y3;
                                   3:Major Axis; 4:Minor Axis;
                                   5:Angle;    6,7:Brightness
DPARM                              1:Lenx X0;    2:Lens Y0;
                                   3:Angle (Deg) 4:Ring Size
                                   5:Eccentric.  6:Core Radius
                                   8:Lens Model, <2: Blandford
                                     >=2: Point Lens
                                   9:Add Source >0 Yes
                                   10:Image<0,Source>0;0=Both
----------------------------------------------------------------
GLENS
Task:  Model Gravitational LENS Magnification by either a
       Blandford galaxy or a point mass.  The source model is
       made up of three ellipses which can be placed anywhere
       within the source plane.  GLENS will produce a source
       plane or image plane map or both images.
       Glen Langstion, NRL, MPIfR and MIT, NRAO: November 1990
Adverbs:
  OBJECT.....Object name.
  IMSIZE.....Desired image size in cells.
  OUTNAME....Output image name (name).     Standard behavior
             with default = 'SOURCE PLANE' or 'IMAGE  PLANE'.
  OUTCLASS...Output image name (class).    Standard defaults.
  OUTSEQ.....Output image name (seq. #).   0 => highest unique.
  OUTDISK....Disk drive # of output image. 0 => highest number
             with sufficient space.
  APARM......1:Source one x coordinate in Pixels.
             2:Source one y coordinate in Pixels
             3:Source one Major axis radius in Pixels
             4:Source one Minor axis radius in Pixels
             5:Source one Orientation angle in degrees.
               (Clockwise from north)
             6:Source one Constant Brightness in arbitray units.
             7:Source one Gaussian Brightness
  BPARM......1:Source two x coordinate in Pixels.
             2:Source two y coordinate in Pixels
             3:Source two Major axis radius in Pixels
             4:Source two Minor axis radius in Pixels
             5:Source two Orientation angle in degrees
             6:Source two Constant Brightness in arbitray units.
             7:Source two Gaussian Brightness
  CPARM......1:Source  3  x coordinate in Pixels.
             2:Source  3  y coordinate in Pixels
             3:Source  3  Major axis radius in Pixels
             4:Source  3  Minor axis radius in Pixels
             5:Source  3  Orientation angle in degrees
             6:Source  3  Constant Brightness in arbitray units.
             7:Source  3  Gaussian Brightness
  DPARM......1:X0- Galaxy Center Location in Pixels
             2:Y0- Galaxy Center Location in Pixels
             3:Theta- Galaxy Mass Major axis orientation (Degrees).
               (Measured Clockwise from North)
             4:Einstein ring radius (pixels)
             5:Galaxy projected eccentricty
             6:Galaxy core size (pixels)
             8:Lens Model, <=1 Blandford Kochaneck Lens,
               2=Point Lens
             9:Add Source: >0 Implies add source at
               un-lensed location
             10: <0: Produce Image Plane
                 >0: Source Plane
                  0: Both
----------------------------------------------------------------
GLENS:
Task:  Model Gravitational LENS Magnification by either a
       Blandford isothermal galaxy or a point mass.  The source
       model is made up of three ellipses which can be placed
       anywhere within the source plane.  GLENS will produce a
       source plane or image plane map or both maps.
DOCUMENTOR: Glen Langston, MIT, MPIfR, NRL, and NRAO
 
                          PURPOSE
The magnification of by a gravitational lens on background
objects (quasars) is modeled by GLENS.  Two types of lens
models are currently supported, the Blandford lens and a
simple point mass lens.

First a bit of terminology:  GLENS produces two types of images,
   1) Source Plane which is a map of the magnification
      of a background source if it at any position relative to
      the gravitational lens.
   2) Image Plane which is a map of the source after distortion
      and magnification by the gravitational lens.

GLENS allows a three component source model.  Each of the three
components are ellipses with variable major, minor axies and
orientation angles.  The surface brightness of each ellipse has
two components, a constant part and a gaussian part.

Both the Blandford lens and the Point lens have a characteristic
size which determines the size of an Einstein Ring produced
by perfect alignment of the lens and background object.

For the Point lens DPARM(4) is the Einstein ring radius.
This value is a function of the mass of the lens,M, and the
distances between observer and quasar, D_q, between observer and
lens, D_l, and between lens and quasar, D_lq.  The ring radius
in radians is equal to
                                          1/2
                          [4 G M   D_lq  ]
     DPARM(4) = Theta_R = [-----  -------] (pixels or radians).
                          [  2           ]
                          [ c     D_l D_q]

The velocity of light is c, G is Newtons constant and the
distances are angular distances (when measured from redshifs).

The scale of the lensed images are all relative to the angular
scale set by the Einstein ring size.  The relative positions and
sizes of the source components must be calculated by the user
converting angular sizes to pixels.

For the point lens, the source is always located radially
inwards towards the lens relative to the image location.

For the isothermal Blandford lens, the angular scale is also set
by DPARM(4) which corresponds to the "A" parameter.
The exponential parameter alpha is set to 1/2 in this model.

Note that the orientation axis is for the galaxy mass, and that
the source plane map of the magnification major axis will be
orthogonal to the mass distribution major axis.

                          ALGORITHM
A difficulty in modeling gravitational lensing is that the
mapping from source plane to image plane is ONE-TO-MANY.
That is, several points in the image plane correspond to one
point in the source plane.  This leads to quadradic equations
with several roots when starting with a source model and
calculating the image plane.  GLENS avoids this problem by
starting from the image plane and following light backwards to
the source plane.  Each point in the image plane corresponds to
exactly one point in the source plane.

The effect of different types of gravitational lenses has been
isolated into subroutines.  The Point lens and Blandford lens
effects are calculated by giving the subroutines the lens
model parameters and an input x,y IMAGE location.  The
subroutines calculate the output x,y SOURCE location and the
magnification of the source.

Other lens types could be easily added.

                           DEFAULT
Running GLENS with all defaults yields a blandford lens with
eccentricity = 0.1 and orientation angle = 30 degrees.
The Einstein Ring radius is set to a fifth of the X axis size.
(It is a fairly pretty default.)

                          REFERENCES
Blandford and Kochanek 1987, Ap. J. 321:658.
Langston, Conner, Lehar, Burke and Weiler 1990, Nature, 344:43.
Turner, Ostriker and Gott 1984, Ap. J. 284:1.

