in the galsim lib, what does the applyShear do?

Question

does it do the same image distortion as applyTransformation? is there still this function applyTransformation?

and about the applyShear function, it only apply shear, no other lensing effect, i.e. no magnification, or no other higher order effects, right?

Answer 1

In version 1.1, the methods applyShear and applyTransformation were deprecated. The preferred methods to use are now shear and transform.

The shear method is typically used as sheared_obj = obj.shear(g1=g1, g2=g2) where g1, g2 are the components of the reduced shear to be applied. You can also give e1,e2 (distortions rather than shear), or g, beta or e, beta (giving the magnitude and position angle), among other possibilities. See the docs for the Shear class for more information about ways to specify a shear in GalSim.

However you specify the shear, the shear method will shear the given surface brightness profile by that amount in a manner that preserves total flux.

The transform method is somewhat more general in that you can transform by any arbitrary 2x2 coordinate transformation matrix. Specifically, you specify an arbitrary Jacobian: dudx, dudy, dvdx, dvdy, where (x,y) are the original coordinates and (u,v) are the transformed coordinates. With this method, you could apply a transformation that is equivalent to a shear, but you would need to manually calculate the correct terms in the Jacobian.

The other difference is that transform does not necessarily preserve flux. The flux is only preserved if the Jacobian has unit determinant. So depending on your use case, you may want to rescale the flux by the determinant when you are done.

My guess is that you will most often want to use shear rather than transform. Here is a sample use case (taken from demo5.py in the GalSim examples directory):

gal = galsim.Exponential(flux=1., half_light_radius=gal_re)

[...] 

for [...]:
    # Now in a loop to draw many versions of this galaxy with different shears, etc.

    # Make a new copy of the galaxy with an applied e1/e2-type distortion 
    # by specifying the ellipticity and a real-space position angle
    this_gal = gal.shear(e=ellip, beta=beta)

    # Apply the gravitational reduced shear by specifying g1/g2
    this_gal = this_gal.shear(g1=gal_g1, g2=gal_g2)

    [...]

Hope this helps.

Note: The links above are current as of December, 2014. If they go stale, try navigating from the top level of the Doxygen documentation, which hopefully will still work.

Answer 2

I would just like to add to the response above from ne1410s (I don't have the reputation points to comment on his or her post).

In addition to that excellent information, there are thorough docstrings for most of the standard functionality, which you can check out using the python help() routine, i.e.

import galsim
help(galsim.GSObject.applyShear)

In the case of applyShear(), this routine is deprecated in the latest version of GalSim, but the docstring still exists and points the user to the new functionality. For older versions of GalSim, there is a complete docstring that explains how applyShear() works.

To summarize, going to the GalSim repository, you can get help in the following ways:

1. Go through the demos in examples/ (they are extensively commented).
2. Go through the quick reference guide in doc/
3. Go to the complete documentation including all docstrings, at http://galsim-developers.github.io/GalSim/

And then there are the docstrings for individual routines, which are accessible via help(). It should not, in general, be necessary to read the source code to learn how routines work.

Answer 3

All the written documentation, examples and source code can be found on GitHub, at the following location. https://github.com/GalSim-developers/GalSim

I suggest looking there first, and if there aren't any docs that answer your question directly, you could always study the source code for the applyShear functionality you are describing.

Good luck