The Shear class

class galsim.Shear(*args, **kwargs)[source]

A class to represent shears in a variety of ways.

The Shear object can be initialized in a variety of ways to represent shape distortions. A shear is an operation that transforms a circle into an ellipse with minor-to-major axis ratio b/a, with position angle beta, while conserving the area (see below for a discussion of the implications of this choice). Given the multiple definitions of ellipticity, we have multiple definitions of shear:

reduced shear

\(|g| = \frac{a - b}{a + b}\)

distortion

\(|e| = \frac{a^2 - b^2}{a^2 + b^2}\)

conformal shear

\(\eta = \log(b/a)\)

minor-to-major axis ratio

\(q = \frac{b}{a}\)

These can be thought of as a magnitude and a real-space position angle \(\beta\), or as two components, e.g., \(g_1\) and \(g_2\), with:

\[\begin{split}g_1 &= |g| \cos(2 \beta) \\ g_2 &= |g| \sin(2 \beta)\end{split}\]

Note: \(\beta\) is _not_ the phase of a complex valued shear. Rather, the complex shear is \(g_1 + i g_2 = g \exp(2 i \beta)\). Likewise for \(\eta\) or \(e\). The phase of the complex value is \(2 \beta\).

The following are all examples of valid calls to initialize a Shear object:

>>> s = galsim.Shear()                    # empty constructor sets ellipticity/shear to zero
>>> s = galsim.Shear(g1=0.05, g2=0.05)
>>> s = galsim.Shear(g1=0.05)             # assumes g2=0
>>> s = galsim.Shear(e1=0.05, e2=0.05)
>>> s = galsim.Shear(e2=0.05)             # assumes e1=0
>>> s = galsim.Shear(eta1=0.07, eta2=-0.1)
>>> s = galsim.Shear(eta=0.05, beta=45.0*galsim.degrees)
>>> s = galsim.Shear(g=0.05, beta=0.25*numpy.pi*galsim.radians)
>>> s = galsim.Shear(e=0.3, beta=30.0*galsim.degrees)
>>> s = galsim.Shear(q=0.5, beta=0.0*galsim.radians)
>>> s = galsim.Shear(0.05 + 0.03j)        # Uses the g1,g2 reduced shear definition

There can be no mixing and matching, e.g., specifying g1 and e2. It is permissible to only specify one of two components, with the other assumed to be zero. If a magnitude such as e, g, eta, or q is specified, then beta is also required to be specified. It is possible to initialize a Shear with zero reduced shear by specifying no args or kwargs, i.e. galsim.Shear().

In addition, for use cases where extreme efficiency is required, you can skip all the normal sanity checks and branches in the regular Shear constructor by using a leading underscore with the complex shear g1 + 1j * g2:

>>> s = galsim._Shear(0.05 + 0.03j)  # Equivalent to galsim.Shear(g1=0.05, g2=0.03)

Analagous to the construction options, one can access the shear in the same variety of definitions.

Attributes:

  • g1 – The first component of the shear in the “reduced shear” definition.

  • g2 – The second component of the shear in the “reduced shear” definition.

  • g – The magnitude of the shear in the “reduced shear” definition.

  • e1 – The first component of the shear in the “distortion” definition.

  • e2 – The second component of the shear in the “distortion” definition.

  • e – The magnitude of the shear in the “distortion” definition.

  • eta1 – The first component of the shear in the “conformal shear” definition.

  • eta2 – The second component of the shear in the “conformal shear” definition.

  • eta – The magnitude of the shear in the “conformal shear” definition.

  • q – The minor-to-major axis ratio

  • beta – The position angle as an Angle instance

  • shear – The reduced shear as a complex number g1 + 1j * g2.

Note

Since we have defined a Shear as a transformation that preserves area, this means that it is not a precise description of what happens during the process of weak lensing.

The coordinate transformation that occurs during the actual weak lensing process is such that if a galaxy is sheared by some \((\gamma_1, \gamma_2)\), and then sheared by \((-\gamma_1, -\gamma_2)`\), it will in the end return to its original shape, but will have changed in area due to the magnification,

\[\mu = \frac{1}{(1-\kappa)^2 - (\gamma_1^2 + \gamma_2^2)}\]

which is not equal to 1 for non-zero shear even for convergence \(\kappa=0\).

Application of a Shear using the GSObject.shear method does not include this area change. To properly incorporate the effective change in area due to shear, it is necessary to either:

  1. define the Shear object, use the GSObject.shear method, and separately use the GSObject.magnify method, or

  2. use the GSObject.lens method that simultaneously magnifies and shears.

property beta

The position angle as an Angle instance

property e

The magnitude of the shear in the “distortion” definition.

property e1

The first component of the shear in the “distortion” definition.

property e2

The second component of the shear in the “distortion” definition.

property esq

The square of the magnitude of the shear in the “distortion” definition.

property eta

The magnitude of the shear in the “conformal shear” definition.

property eta1

The first component of the shear in the “conformal shear” definition.

property eta2

The second component of the shear in the “conformal shear” definition.

property g

The magnitude of the shear in the “reduced shear” definition.

property g1

The first component of the shear in the “reduced shear” definition.

property g2

The second component of the shear in the “reduced shear” definition.

getMatrix()[source]

Return the matrix that tells how this shear acts on a position vector:

If a field is sheared by some shear, s, then the position (x,y) -> (x’,y’) according to:

\[\begin{split}\left( \begin{array}{c} x^\prime \\ y^\prime \end{array} \right) = S \left( \begin{array}{c} x \\ y \end{array} \right)\end{split}\]

and \(S\) is the return value of this function S = shear.getMatrix().

Specifically, the matrix is

\[\begin{split}S = \frac{1}{\sqrt{1-g^2}} \left( \begin{array}{cc} 1+g_1 & g_2 \\ g_2 & 1-g_1 \end{array} \right)\end{split}\]
property q

The minor-to-major axis ratio

rotationWith(other)[source]

Return the rotation angle associated with the addition of two shears.

The effect of two shears is not just a single net shear. There is also a rotation associated with it. This is easiest to understand in terms of the matrix representations:

If shear3 = shear1 + shear2 is a sum of two shears, and the corresponding shear matrices are \(S_1\), \(S_2\), and \(S_3\), then \(S_3 R = S_1 S_2\), where \(R\) is a rotation matrix:

\[\begin{split}R = \left( \begin{array}{cc} cos(\theta) & -sin(\theta) \\ sin(\theta) & cos(\theta) \end{array} \right)\end{split}\]

and \(\theta\) is the return value (as a galsim.Angle) from shear1.rotationWith(shear2).

property shear

The reduced shear as a complex number g1 + 1j * g2.

galsim._Shear(shear)[source]

Equivalent to galsim.Shear(shear), but without the overhead of the normal sanity checks and other options for how to specify the shear.

Parameters:

shear – The complex shear g1 + 1j * g2.

Returns:

a galsim.Shear instance