User Tools

Site Tools



Software for modelling resolved gravitational lenses by Randall Wayth.


2012 April: Homepage moved to Curtin University wiki (here). Some typos in this page fixed.
2008 Oct 31: v1.1.2 release (source only). No functionality change. Some cleanup of print statement bugs for 32-bit machines. No longer overwrites existing model files when making magnification maps.
2008 Oct 26: v1.1.1 release (source code only). Some updates to better handle parameters that go into illegal ranges (like axis ratio more than 1) when using the minfinder. No change in basic functionality.
2008 Oct 14: V1.1.0 release.

  • change in behaviour for how the 'srcdefaultval' parameter is used. NOTE: This is a departure from the description in the published paper. Details in the description of the parameter below.
  • output best models at end of param search
  • fastell code and dependencies included by default in source distribution
  • some small usability improvements

2007 May 04: V1.0.3 release. updated usage() message and tarball with fastell dependencies. No new binary files.
2007 Jan 08: V1.0.2 release. Fixes bug for external shear models.
2006 Sep 18: V1.0 release. Paper on astro-ph.


Lensview is a software program for the modelling of resolved gravitational lens systems based on LensMEM (see Wallington) but using the Skilling & Bryan MEM algorithm. The main purpose of the software is to find statistically acceptable lens models for lensed images and to reconstruct the surface brightness profile of the source. The software can also be used for more simple tasks such as projecting a given source through a lens model to generate a “true” image by conserving surface brightness.

The software allows the user to specify complicated lens models based on one or more components, such as softened isothermal ellipsoids, point masses, exponential discs, external shears and so on. The parameter space of the model is searched according to the user specifications and a best-fitting source is generated to match the observed data for each specific combination of model parameters.


The main features of lensview are:

  • projection between image and source plane conserving surface brightness
  • compound lens models which can contain several basic components. E.g a lens galaxy can be modelled by a constant M/L section plus halo
  • reconstruction of the (unlensed) source brightness profile and corresponding model image using a non-parametric source
  • iterative source reconstruction process incorporating a maximum entropy metric
  • statistical evaluation of the model image given by the current lens model parameters

The software is written in C and is portable.

Lensview is one of several pieces of software available for modelling graviational lenses. You should see also:


If you just want an executable, check to see if a statically linked binary is available in downloads. If you want to compile it yourself (to make changes or whatever), read on.

This section assumes a good knowledge of Unix and in particular how to compile and link code. If you don't know how to make a code library or what a makefile is, you should enlist the help of your friendly local computer geek now.

Lensview has been compiled and tested on DEC OSF1 V4.0, Solaris (SunOS 5.7), and Linux kernels 2.4.17+ and 2.6.*. The code is extremely portable. Only the makefile should need any tweaking to compile on your system (with exceptions below).


Software: Lensview makes use of the following software:

  • cfitsio. v2.510 (or better) For reading and writing FITS files.
  • FFTW. v2.1.x For convolutions. NOTE: Not version 3.x
  • GNU scientific library (GSL) v1.x. For some lens models which require numerical integration. I have tested Lensview with versions 1.5, 1.6 and 1.7. I think newer versions are backwards compatible.
  • fastell (optional, see below). Rennan Barkana's code (ref) for some power-law lens models. As of V1.1.0 fastell and dependencies are packaged with Lensview with permission from Rennan Barkana. Note that fastell is optional and you might want to exclude it if you can't get a fortran 77 compiler. Some Mac users have reported problems with newer fortran compilers like gfortran. I know for sure that using g77 will work, but Mac users are encouraged to look into the implications of installing g77 since it can conflict with other fortran compilers.

The top three dependencies are available as standard installable packages in most linux distros. For Redhat FC5, cfitsio version 3 is available. Debian based distros and RHEL4/CentOS4 currently have cfitsio 2.510. Cfitsio version 3 seems to be backwards compatible with v2.5 although most of the development and testing of Lensview was with done with v2.5. I have done some basic tests with V3 and it looks good, so you should be OK with either. Generally, you want the development versions of a package (usually with a name ending in ”-dev” or ”-devel”). You don't need to have these libraries installed system wide, however if they are not found in standard locations you will need to tell the compiler where to find them by editing the makefile (and possibly your LD_LIBRARY_PATH or equivalent).

Mac OSX: I have compiled Lensview successfully on a PPC Mac OSX 10.4 (Tiger). Here are my notes. Here is the makefile I used.

Hardware: Depending on what you are modelling, lensview can take very small (~10M) or very large (~500M) amounts of CPU time and memory. However, any reasonably modern machine with at least 256M of memory should be OK to begin with.

Before installing any lensview stuff at all, you should install the software listed above. If you don't want the fastell, then don't panic. You will just need to comment out some code in the file “lv_lens.c” (see below).

I would suggest using the double-precision libraries for FFTW (unless your machine is significantly faster using single-precision), although things work fine with single-precision also. If you compile both single and double precision libraries (as described in the FFTW manual), then you can switch between them very easily.

Installing dependencies for common distros


 sudo apt-get install libgsl0-dev libcfitsio3-dev fftw-dev 

If you don't use fastell

  • comment out the call to the fastell function “fastelldefl_” in lv_lens.c
  • comment out the line ”#include “fastell.h” ” in lv_lens.c
  • update the function “lm_CreateLMComp_SPEMD” to print an error message saying that this lens model is not available

Compiling lensview

So, you've installed and tested FFTW, GSL and cfitsio, and you've downloaded and un-tarred the software. Right!

The code consists of 8 C files and headers and a simple makefile. All of the C files will happily compile into ”.o” files. If you are using fastell, then the program must be linked with the fortran linker, otherwise the standard C linker is fine. The makefile has two lines under the “lensview” target and you will need to un-comment one of them. You will need to:

  • update the makefile variables INCLUDES and LIBS. These will need to be set to where you have the header files for cfitsio and FFTW (for INCLUDES) and where you put the cfitsio, FFTW, fastell and GSL libraries (for LIBS). If you have installed these dependencies through a package manager (yum, apt, fink, port etc), then you probably don't have to do anything here.
  • If you are using the fastell code, then the code must be linked with a fortran→C compatibility library. On linux distros, this just means linking with ”-lg2c” when using g77 or ”-lgfortran” when using gfortran.
  • If you are compiling with a native fortran compiler (e.g. with DEC OSF or Solaris) and are using fastell, then you must add the compiler option ”-nofor_main” in the compiling command. This tells the compiler that “main” is not a fortran program. e.g:
    • $(FC) $(FFLAGS) -o lensview $(OBJS) … becomes
    • $(FC) $(FFLAGS) -nofor_main -o lensview.osf $(OBJS)…

If your FFTW installation does not have the precision embedded in the library name (e.g. “libdfftw” for double precision, “libsfftw” for single precision), then you will need to change the compiler flags ”-ldrfftw” and ”-ldfftw” accordinly. (Some Linux distributions come with FFTW installed like this.)

So, you should be ready to go! To compile, type “make”. You should see something like:

cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux   -c -o log.o log.c
cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux   -c -o parseopts.o parseopts.c
cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux   -c -o lv_common.o lv_common.c
cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux   -c -o lv_lens.o lv_lens.c
cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux   -c -o lv_geom.o lv_geom.c
cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux   -c -o lv_image.o lv_image.c
cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux   -c -o lv_mem.o lv_mem.c
cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux   -c -o lv_critline.o lv_critline.c
cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux   -c -o lv_paramfit.o lv_paramfit.c
cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux   -c -o lensview.o lensview.c
f77 -O -c fastell.f dqnc79.f
cc -O -I/home/rwayth/include -L/home/rwayth/lib.linux -o lensview log.o parseopts.o lv_common.o lv_lens.o lv_geom.o lv_image.o lv_mem.o lv_critline.o lv_paramfit.o fastell.o dqnc79.o lensview.o -lgsl -lgslcblas -lcfitsio -lrfftw -lfftw -lm -lpthread -L/usr/lib/gcc-lib/i386-redhat-linux/3.2.3 -lgfortran

No errors? Great! Errors? Not great. Any errors will almost certainly be a problem with the compiler being able to find include files or libraries.

At this stage you may (or may not) want to put lensview in your Unix path.

Using Lensview

Lensview is a command line driven application. There are many inputs and options which are described below. Each time lensview is run, it generates a log file which tracks the internal workings and results of the program. Under normal circumstances, the only thing printed to the screen while the program runs is the name of the log file. Any severe errors which cause the program to stop will also be printed to stderr.

Modes of operation

Lensview can be thought of as having two basic modes of operation: “simple projection” mode and “normal” (fit an observed image) mode. Mostly you will be using “normal” mode.

Simple mode is where the program takes as inputs: a source, a lens model and (optional) data image and just projects the source into an image. The projected image and chi-squared (between the data and model images) are the output of the program (and a few other useful things).

Normal mode is where the program searches parameter space, either by parameter sweep or using the downhill simplex method. It takes as inputs: an image (the “data”), a lens model (with a range of parameter values) and an (optional) image which characterises the noise in each image pixel. For set of lens model parameters, it performs an iterative reconstruction of a source to best-match the input image. A chi-squared and reduced chi-squared is calculated for each set of lens model parameters. To use the downhill simplex method, use the ”-useminfinder” flag.

Command-line options

Lensview has many command line options. We list them here with the type of any associated argument (e.g. string, floating point, integer or “toggle” [i.e. a flag]) and a description of what they do.

-logfilepath string destination directory where the log file will be placed.
-srcxoffset float (pixels) x offset of centre of source plane compared to centre of image. Positive values will move the reconstructed source in the positive direction relative to the source plane itself.
-srcyoffset float (pixels) y offset of centre of source plane compared to centre of image
-tracelevel int Tracing priority (see logfiles). 1=all trace points, 2= trace medium/high priority, 3= trace high priority, 4= trace only errors. 5=trace nothing

Simple ray tracing & simple projections using the triangle mapping:

-raytraceonly toggle switch to indicate that forward-projection should be done using simple ray-tracing. The output image intensity at each pixel is just the value of the source wherever the ray lands in the source plane.
-imgfile string Name of the output file when ray-tracing. Default is “test_image.fits”

Options for lens modelling:

-constvariance float use a constant value variance for all pixels in the data. Most likely only applicable for radio data.
-datafile string Name of the FITS file which contains the image to model.
-debugimgs toggle Create images of the various search directions/intermediate states generated during the minimisation process. This creates LOTS of images, and is for debugging purposes only.
-dofit toggle Flag to tell the program to perform a parameter sweep over the ranges specified in the lens components file. Otherwise the source will just be projected into an image using the starting values from the components file.
-dumpimg toggle Flag to have the program create a FITS file with the best-fit image & source for each combination of lens model parameters. The default names of the files are “imagedump_mainX.fits” and “sourcedump_mainX.fits”, where X is just a number which increases each time.
-fixlambda float (Obsolete) For use with the ”-useconjgrad” flag. The algorithm tries to minimise the metric C=χ2 - λS where S is the entropy in the source. Normally, λ is varied so that the χ2 reaches the target chisqu. You can fix it to some value using this flag. Setting lambda to zero diables the entropy and allows negative values in the source.
-makemag toggle Flag to make a pixel-by-pixel magnification map in the source and image planes as well as text files containing sets of points whcih describe the critical line and caustic. The output files are called “mag_src.fits”, “mag_img_inv.fits”, “critline.txt” and “caustic.txt”. The output file in the image plane is actually 1/mag just because this is easy to calculate from the way the program stores the weights matrix. When the program runs through many lens models, then the magnifications will be calculated for the last lens model. Usually, you would want to do this for a unique lens model.
-mask string File name of a FITS file which will be used as a user-defined mask in the image. The χ2 will be calculated only for pixels in the region specified by the mask. The FITS mask should be a 1 or 0 (floating point is OK). A value of 0 (FALSE) means “mask this pixel” which means “don't use it in χ2 calculations”. So the area you want the χ2 calculation to be performed over should be non-zeros.
-maxiter int maximum number of iterations performed in the Max Entropy procedure for each lens model. Default is 100.
-nice int Set the “nice” level. By default the program runs at whatever the nice level of the calling shell is.
-noisefile string File name of the pixel-by-pixel variance (σ2) for the data. Obviously must be the same dimesions as the data file. If not supplied, the program will use the overall variance in the data file as a (poor) guess for the variance in each pixel.
-normalisepsfmax toggle instead of normalising the PSF so that the total in the PSF is 1, normalise so that the max value in the PSF is 1.
-paramfile string File name of the list of lens model components.
-pixelratio float Sets the ratio in angular size of the pixels between the image and source planes. E.g a pixelratio of 2 means that the angular size of a pixel in the source plane is 1/2 that of an image pixel.
-pixelres float The pixel resolution of the image in arcseconds. You must supply this number.
-psffile string Name of the FITS file which contains the PSF for the data. It is strongly recommended that this be an odd sized image for symmetry.
-srcdefaultval float The default value (or “sky” value) for pixels in the source plane. This is the “A” parameter in the Skilling & Bryan terminology. Must be > 0. Should be the same order of magnitude as the variance in a blank part of your image. (i.e. in a sky-dominated optical image, if the sky value is N photons, then the noise will be sqrt(N) and the srcdefaultval should be of order N. Take care with units, because the entropy constraint is technically relevant to the number of photons received. See the recommended units of the data below in the 'tips' section.) NOTE: as of v1.1.0, this number is subtracted from the model source before the model image is calculated, which is a departure from the definition in the Lensview paper.
The reason for this change is to accommodate high SNR images and for the entropy constraint to reflect photon statistics (where applicable). Practically, what this means is that the srcdefaultval can be set higher without detrimental effects to the models (because parts of the source model that don't affect the image model are zeroed before projection into the image plane). Using a higher value will allow the model to be closer to the data (hence noisier). As a general rule, you want this parameter to have the same magnitude as your variance, but smaller if possible to keep unnecessary structure out of your source model.
-sourcefile string Name of the fits file for the source. This image defines the size of the source plane.
-targetchisqu float The target chisqu which the Max Ent algorithm tries to reach. Once this value is reached (or maxiter) the algorithm stops. If you don't know what this number is, you can't be sure you have found the best fit. Lensview makes a guess at what the target chisqu is, but it isn't reliable. You need to know this number.
-useconjgrad toggle (Obsolete and no longer supported.) Instead of using Skilling & Bryan MEM, use the simple conjugate gradient method instead. Sources generated with conj gradient tend to me more noisy than those generated with S&B MEM. With this option and ”-fixlambda 0”, one can disable the entropy constraint entirely.
-useminfinder toggle rather than do a parameter sweep (the default), use the downhill simplex method (“amoeba”) to find the best set of parameters. In this case, the values in the parameter file are used as the starting boundary for the simplex. This overrides -dofit.

Lens component files

Each time lensview is run, it reads a file specified by the “paramfile” command-line option (see above) which describe the components (1 or more) of the lens model. The file is just a text file. Lines which are blank or start with the '#' character are ignored. Components are specified by their type (e.g. SIE, exponential disc etc.) plus an offset of the component from the centre of the image, followed by a range of values which the program works through during execution.

The (x,y) offset of the lens component is fixed throughout the modelling process. The other components are iterated through as specified in the file. Each parameter has a start value, an end value (which should be > start value) and an increment. If you specify the same end value as start value, then the parameter is not changed and the increment is irrelevant. For each combination of lens model parameters, the image is fitted.


xoffset, yoffset: in pixel units. Positive values move the lens centre in the positive (x,y) direction relative to the centre of the image. Generally, you want the offset to be less than half a pixel in either direction. Do this by cutting out a subimage from your data with the lens centre within a pixel of the centre of the image. Note Lensview defines (0,0) at the bottom left corner of a pixel, unlike IRAF.
critical radii (b): in arcsec
core radii (rc): in arcsec
ellipticity (ε) is dimensionless and the same as 1-q where q is the axisratio
angles (θ) are in degrees measured anti-clockwise from horizontal. (NOTE: lensview has no idea what the PA of your data is even if it is in the FITS header.)
shear (γ) is dimensionless
point masses are in arcsec (i.e. their Einstein radius)
Kappa: is the usual dimensionless definition of Kappa.


The following lens model components are supported:

  • PIEP: The classic psuedo-isothermal potential. Don't use large ellipticities with this one. The major-axis of the potential is in the x-direction when the orientation angle is zero. See Narayan & Bartelmann. Defined as Φ = b(rc2 + (1-ε)x2 + (1+ε)y2 )½ . Can be rotated by angle (θ).
  • SIE: Also a classic: the singular isothermal ellipsoid. Defined by the suface density: Σ = Σ0 [q/(1-q2)]½ / (x2q + y2/q)½ The extra factor after Σ0 normalises the Einstein radius for a given Σ0 independent of q.
  • PTMASS: a point mass defined by its critical radius.
  • SPEMD: The power-law mass distribution. (Requires fastell code). See Barkana. Defined as: Σ = Σ0 [(2-2β)/q]β / (x2q + y2/q)β The extra factor after Σ0 normalises the Einstein radius for a given Σ0 independent of q and β.
  • NFW: The nouveau-classic dark matter profile of Navarro, Frenk & White. Implemented as the PNFW profile. See Golse & Kneib. Defined by: Equation 6 of Golse & Kneib where the mass scale parameter in Lensview is (κc) in Equation 6 and (rs) is the NFW scale length in arcsec, as well as an axis ratio (q) and angle (θ).
  • MASSSHT: a constant-density mass sheet.
  • EXTSHEAR: an external shear with magnitude (γ) and angle (θ).
  • EXPDISC: an inclined/elliptical exponential disc. See Keeton.
  • SERSIC: a Sersic mass distribution of index (shape parameter) “m” which can include deVaucouleurs (m=4), exponential discs (m=1) and Gaussians (m=1/2). Defined by Σ = Σ0 exp[-B(m)(r/rs)(1/m)] with scale length (rs), axis ratio (q) and angle (θ).

Note that EXPDISC and SERSIC require numerical integration to calculate deflection angles, so they can be quite time consuming, especially when using -useminfinder. The deflection angles are cached for a given axis ratio (axis ratio and shape parameter for SERSIC) so that changes in other parameters (mass scale, orientation angle) do not cause deflection angles to be calculated again. Hence, it is best to use a parameter sweep for these if possible.

Templates for each component are shown here:

lenscomp{NFW} (xoff,yoff,mass_scalefrom,massto,massinc,scale_lenfrom,scaleto,scaleinc,ellipfrom,ellipto,ellipinc,anglefrom,to,inc)
lenscomp{EXPDISC}(xoff, yoff, kapfrom, kapto, kapinc, axratiofrom, to, inc, orientationanglefrom, to, inc, discscalefrom,to,inc)
lenscomp{SERSIC}(xoff, yoff, kapfrom, kapto, kapinc, axratiofrom, to, inc, orientationanglefrom, to, inc, scalefrom,to,inc,mfrom,mto,minc)

E.g. if you wanted to model a lens as a PIEP with lens centre offset (0.12,0.36), critical radius 1.5 arcsec, with ellipticity 0.1 and orientation angle 25 deg, then your file would be:

# This is a comment
#  This is another comment

If you now want to increment the critical radius between 1.4 and 1.6 arcsec in 0.01 arcsec increments and the orientation angle between 20 and 30 degrees in 1 degree increments, then the file would be:

# This is a comment
# It is easy to keep old models by commenting them out.

If you now want to add a point mass at a different location (say -2.5,3.6 from centre of the image) of critical radius 0.03 arcsec, then the file becomes:

# This is a comment
# just add another component!

Log files

Each time Lensview is run, it generates a log file. The amount of stuff written to the log depends on the trace level. The log file name is lv_<date>_<computer>.log where <date> is like “20060917_163024” (YYYYMMDD_HHMMSS) and '<computer>' is your computer name (the same as “uname -n”). When Lensview starts, it prints the name of the log file to stdout.


Here is the simulated image (no noise), data (with noise) and variance from the optical simulations in the paper. Here is an empty 15x15 source. Here's a PSF file and the mask. Here is a lens component file you could use for it and a short script to make the whole thing run.

Handy scripts

I use a bunch of short shell and IDL scripts to make life easy. I put them here hoping they might prove useful, but there's some hard-coded file paths in them that you will need to change to use them. Hopefully it is obvious what needs to be changed.

run_lv - just a simple shell script which has all the command line args in it. This one is an example.
match.txt - use fgrep -f match.txt lv_<logfile>.log > chi.txt to extract the chisqu results for each set of lens model params from a lensview log file. - IDL script to process the “chi.txt” file created above and read all chisqu results and all parameter values into nice arrays. You'll need to remove the .txt from the filename. (Wiki doesn't allow .pro extensions.) You can then make nice plots of the chisqu surfaces really easily. This one for 4 parameter models like PIEP. This requires this template from IDL's ascii_template() function. (This file is an IDL binary file from the command 'save'.) Change the hard-code line ”/home/rwayth/idl/…” in the script to point to this template. (Sorry about the hard-code.) - This one for 3 parameter models like SIE. - This one for a Sersic model with a 4 parameter model for the halo. - This one for a Sersic model. -This one for 5 parameter models like SPEMD.

Tips and tricks

Setting up your data
In general, you will need a data image, a variance image, a PSF image and a mask image. The data, variance and mask all need to be the same size. (You can just use a data image with no variance and no mask, but the results aren't statistically meaningful.) Your data should be an image cutout from some larger image that already has the lensing galaxy and sky background subtracted. The variance should be cut out from the variance map over the same sub-region as the data. The variance should include the contributions from sky and read noise (in optical data).

The units used in the data/variance can matter because of the log in the entropy. For optical data, generally you want to the units to reflect the number of photons received (i.e. counts, not counts/sec), so the data and variance values should be >= 1.

Generally you should use the smallest image you can. This is because Lensview will convolve the model image with the PSF over the entire image using FFTs. The computational cost of the convolution increases with the image size. The size of the image doesn't actually affect the chi-squ, since that is only computed over the mask.

You will almost certainly need an image mask, which should select just the region of the cutout data image where there is lensed flux. You probably want a buffer of a couple of pixels around the lensed image so models that are a little bit incorrect (project flux into slightly the wrong place) can be appropriately penalised. The mask is just another FITS file that has zero in pixels that you don't want to include in χ2 and ones where you do.

Your cutout image should have the lens centre as close to the actual center of the image as possible. In general, you want the lens centre offset to be less than 1/2 a pixel in either X or Y.

Getting started
When first starting with new data, you need to get a feel for the correct lens model and source size/location. The best way to do this is with the ”-useminfinder” option. At the beginning, use a large(ish) source plane with low source/image plane pixel size ratio (1 or 2). The idea is to guarantee that the source will fall in your source plane even if it is offset a bit from the centre. Make an initial estimate of the Einstein radius (should be within 10%). Generally, the minfinder is pretty good at sniffing out the correct axis ratio and orientation angle. Don't put the range on the axis ratio too large, since bad things happen if it tries to search with axis ratio > 1. Put a large (say 0 to 90 degrees) range on the angle if you're not sure, however it is generally a good bet that the angle will be resonably aligned with the lens galaxy light. Once you have an approximately correct model, you should refine the source plane properties (size, pixel size ratio, offset etc).

pixel co-ordinate conventions
Lensview considers (0,0) to be the bottom left corner in an image. Note that this is different to iraf, where the bottom left of an image is (-0.5,-0.5) pixel units. The centre of the image is (xsize/2, ysize/2) where the division is integer. So, in an odd-sized image (e.g 99 x 99 pixels), then the centre of the image is at (49,49) which is the same as if the image was 98×98 pixels. Be careful to know where you centre should be… You can specify offsets in your lens models components with respect to this image centre.

It is very straightforward to do parameter sweeps in parallel with lensview. Just change the lens component parameter file to fix (or reduce the range of) a parameter for a single process and start lots of processes. Lensview has been used sucessfully with parallelization manager type programs to run on clusters of computers, for example with Nimrod.

Get Lensview

If you just want a binary and don't care about compiling, please send me an email and I'll see if I can make a statically linked binary for your system.

Please consider sending me an email if you're using Lensview so that I can keep you up-to-date on any changes.


staff/rwayth/lensview.txt · Last modified: 2012/04/02 13:41 by rwayth